**Public code review for Ledger team:** [**bis-innovations/LedgerLive**](https://github.com/bis-innovations/LedgerLive) — use this repo for all Chain 138 integration code, specs, and patches intended for Ledger Live team review.
**See also:** [ADD_CHAIN138_TO_LEDGER_LIVE](../04-configuration/ADD_CHAIN138_TO_LEDGER_LIVE.md) for the Chain 138–specific action plan and submission text. **Generated code for all 8 steps:** [pr-workspace/ledger-chain138-integration/](../../pr-workspace/ledger-chain138-integration/). **Gaps and missing integrations (tests, fixes, checklist):** [pr-workspace/ledger-chain138-integration/GAPS_AND_MISSING_INTEGRATIONS.md](../../pr-workspace/ledger-chain138-integration/GAPS_AND_MISSING_INTEGRATIONS.md).
---
## Prerequisites (do first)
1.**Agreement with Ledger** — [Submit the form](https://tally.so/r/mORpv8). Do **not** start development before they respond.
2.**Device app** — Either Ledger builds it (option A) or you/partner build + security audit (option B). See [Device App Kit](https://developers.ledger.com/docs/device-app/getting-started).
3.**Repos** — Fork/clone [LedgerHQ/ledger-live](https://github.com/LedgerHQ/ledger-live). For **public code review by the Ledger team**, publish your work to [**bis-innovations/LedgerLive**](https://github.com/bis-innovations/LedgerLive). Requirements for ledger-live: Node 18, pnpm 8, Python 2.7 or 3.5+, C/C++ toolchain. Run `pnpm i` in `ledger-live`.
For **EVM chains (e.g. Chain 138):** The Ethereum device app already supports multiple chain IDs; Ledger may only need to add Chain 138 to the official app-ethereum `network.c` (we have this in our fork). No separate device app is required unless Ledger specifies otherwise.
Add the coin to **`@ledgerhq/cryptoassets`** in `libs/ledgerjs/packages/cryptoassets/src/currencies.ts` (or `.js`).
**CryptoCurrency fields:** `id`, `name`, `ticker`, `managerAppName`, `coinType` (SLIP-44), `scheme`, `color`, `family`, `units` (first = main unit, last must have `magnitude: 0`), `explorerViews` (tx, address, token URLs with `$hash`, `$address`, `$contractAddress`). For EVM: set `ethereumLikeInfo: { chainId: number }`.
**Chain 138 example:**
```javascript
// In libs/ledgerjs/packages/cryptoassets/src/currencies.ts
**Purpose:** JavaScript/TypeScript library that talks to the device app (e.g. `hw-app-eth` for Ethereum). Naming convention: `hw-app-*` (see `hw-app-btc`, `hw-app-eth` in the monorepo or on npm).
**For EVM / Chain 138:** The existing **Ethereum app** and **`@ledgerhq/hw-app-eth`** already support any chain ID; signing uses EIP-155 and the chain ID is passed in the transaction. No new device app lib is required unless Ledger asks for a dedicated package. If they do:
- Implement a class that extends or mirrors the Transport-based API (e.g. `getAddress(path, options)`, `signTransaction(path, rawTxHex)`, `signPersonalMessage(path, messageHex)`).
- Publish or add to the monorepo under `libs/ledgerjs/packages/hw-app-*`.
- The coin-module **signer** (Step 4) will call this lib.
**If using Ethereum family:** Ensure `chainId: 138` is passed in transaction building and signing so the device displays the correct network.
Add a **CoinModule** under `libs/coin-modules/` (e.g. for a dedicated family) or reuse the **Ethereum** family.
**For Chain 138 as Ethereum family:** Ledger typically adds new EVM chains by extending the existing **Ethereum** coin-module configuration (currency list, RPC, explorer) rather than creating a new `coin-defi_oracle_meta`. If Ledger requests a separate module:
- **Rules:** One-way dependencies (e.g. `logic` must not import `bridge`). Use `index.ts` per folder to control exports.
- **live-common:** Add or extend `libs/ledger-live-common/src/families/ethereum/` (or `families/defi_oracle_meta/` if separate) with setup, config, and walletApiAdapter.
**Bridge** implements: sync, buildTransaction, signOperation, broadcast, getFeesForTransaction, getTransactionStatus, etc. **Network** wraps RPC/explorer (e.g. public RPCs and Blockscout for Chain 138).
For Chain 138, currency may be `ethereum` with chainId 138 in config, or a dedicated id once added.
If you need **custom derivation:** extend `libs/coin-framework/src/derivation.ts` with `overridesDerivation`, `legacyDerivations`, `disableBIP44`, `seedIdentifierPath` for your family. See [LLC derivation](https://github.com/LedgerHQ/ledger-live/wiki/LLC:derivation).
**Purpose:** Backend/API used by the coin-module and optionally by Ledger Wallet services: RPC, indexer, or explorer integration for sync, fees, broadcast, and history.
**For Chain 138:**
- **RPC:** Use public endpoints (e.g. `https://rpc-http-pub.d-bis.org`, `https://rpc.d-bis.org`) for `eth_*` calls. See [ADD_CHAIN138_TO_LEDGER_LIVE § 3.1](../04-configuration/ADD_CHAIN138_TO_LEDGER_LIVE.md#31-chain-specification-chainlist-compatible) and `pr-workspace/chains/_data/chains/eip155-138.json`.
- **Explorer:** Blockscout at `https://explorer.d-bis.org` (EIP3091). Use for tx/address/token links and, if needed, for history or verification.
- Ledger may run their own indexer or proxy; they will specify. Have public RPC and explorer URLs ready for their config.
- In `libs/ledger-live-common/src/families/ethereum/` (or your family): **`setup.ts`** — create Bridge with `createBridges(executeWithSigner(createSigner), getCurrencyConfig)`, export `bridge`, `resolver`, `cliTools`.
- **Config:** Register coin config (e.g. `config_currency_defi_oracle_meta_mainnet`) with at least `status` and `node.url` (e.g. from env `API_DEFI_ORACLE_META_NODE` or Ledger’s env naming).
**Ledger Wallet Desktop (LLD):**
- In `live-common-set-supported-currencies.js` add the currency id (e.g. `defi_oracle_meta_mainnet`).
- Add error translation keys in `static/i18n/en`.
- Run: `pnpm dev:lld`.
**Ledger Wallet Mobile (LLM):**
- In `live-common-setup.js` add the currency.
- Add error keys in `src/locales/en/common.json`.
- Run: `pnpm dev:llm` (iOS, Mac); Android: `pnpm mobile android`; iOS: `pnpm mobile ios` or open `ios/ledgerlivemobile.xcworkspace`.
2. If adding a **new family:** create `packages/core/src/families/{COIN_FAMILY}/` with `validation.ts` (Zod, at least `schemaRaw{COIN_FAMILY}Transaction`), `types.ts` (`{COIN_FAMILY}Transaction`, `Raw{COIN_FAMILY}Transaction`), `serializer.ts` (serialize/deserialize for JSON-RPC).
3. In `packages/core/src/families/common.ts` add family name to `FAMILIES`.
4. Export in `packages/core/src/families/index.ts`; update `types.ts` and `validation.ts` and `serializer.ts` for the union `Transaction` and `schemaRawTransaction`.
5. Run `pnpm changelog`, create changeset for `@ledgerhq/wallet-api-core` (minor bump), open PR.
**For EVM:** Chain 138 may be supported by extending the existing **Ethereum** family in wallet-api (e.g. allow chainId 138 in validation and routing). Ledger will confirm.
- Add or extend **Wallet API adapter** in `libs/ledger-live-common/src/families/ethereum/walletApiAdapter.ts` (or your family) so WalletAPI transaction type maps to Ledger Wallet transaction type. Ensure the adapter is included by the sync-families-dispatch script (do not edit generated file by hand; add the source adapter file).
Example PRs: [Ethereum adapter](https://github.com/LedgerHQ/ledger-live/pull/3182), [Filecoin](https://github.com/LedgerHQ/wallet-api/pull/127), [Solana](https://github.com/LedgerHQ/wallet-api/pull/132).
