proxmox/docs/11-references/LEDGER_BLOCKCHAIN_INTEGRATION_COMPLETE.md

Ledger Blockchain Integration — Complete Reference (All Steps)

Last Updated: 2026-02-13
Purpose: Full 8-step Ledger Wallet blockchain integration with gaps filled. Use for Defi Oracle Meta Mainnet (Chain ID 138) or any EVM chain.

Public code review for Ledger team: 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 for the Chain 138–specific action plan and submission text. Generated code for all 8 steps: pr-workspace/ledger-chain138-integration/. Gaps and missing integrations (tests, fixes, checklist): pr-workspace/ledger-chain138-integration/GAPS_AND_MISSING_INTEGRATIONS.md.

---

Prerequisites (do first)

1. Agreement with Ledger — Submit the form. 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.
3. Repos — Fork/clone LedgerHQ/ledger-live. For public code review by the Ledger team, publish your work to 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.

---

Step 1 — Currency (Cryptoassets library)

Doc: 1 - Currency

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:

// In libs/ledgerjs/packages/cryptoassets/src/currencies.ts
defi_oracle_meta_mainnet: {
  type: "CryptoCurrency",
  id: "defi_oracle_meta_mainnet",
  coinType: 60,  // SLIP-44 Ethereum
  name: "Defi Oracle Meta Mainnet",
  managerAppName: "Ethereum",
  ticker: "ETH",
  countervalueTicker: "ETH",
  scheme: "defi-oracle-meta",
  color: "#627EEA",
  family: "ethereum",
  units: [
    { name: "ETH", code: "ETH", magnitude: 18 },
    { name: "wei", code: "wei", magnitude: 0 },
  ],
  ethereumLikeInfo: { chainId: 138 },
  explorerViews: [
    {
      address: "https://explorer.d-bis.org/address/$address",
      tx: "https://explorer.d-bis.org/tx/$hash",
      token: "https://explorer.d-bis.org/token/$contractAddress?a=$address",
    },
  ],
},

Explorer order: list from most to least preferred; Ledger Wallet uses the first as default.

---

Step 2 — Device app lib (JS bindings)

Doc: 2 - Device app lib (full content behind GitHub login)

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.

---

Step 3 — Create coin module

Doc: 3 - Create module

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:

• Layout: api/ (optional), bridge/, logic/, network/, signer/, types/, config.ts, index.ts.
• 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).

---

Step 4 — Derivation / signer

Doc: 4 - Derivation / Signer

• Define signer types in the coin-module types/signer.ts (e.g. getAddress(path, display?), sign(path, message) or transaction signing).
• Implement getAddress in signer/getAddress.ts using @ledgerhq/coin-framework (GetAddressFn, SignerContext, GetAddressOptions); return { address, publicKey, path }.
• EVM standard: Derivation path 44'/60'/0'/0/0; no custom overrides needed unless Ledger specifies.

CLI check:

ledger-live getAddress --currency ethereum --path "44'/60'/0'/0/0" --derivationMode ""

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.

---

Step 5 — API

Doc: 5 - API (full content behind GitHub login)

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 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.

---

Step 6 — LLD & LLM (desktop and mobile)

Doc: 6 - LLD & LLM

Ledger Wallet Common (live-common):

• 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.

---

Step 7 — Wallet API (Ledger Wallet API)

Doc: 7 - Wallet API

In LedgerHQ/wallet-api:

1. Fork/clone; pnpm i and pnpm dev.
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.

In Ledger Wallet (ledger-live):

• Bump @ledgerhq/wallet-api-core, @ledgerhq/wallet-api-server, @ledgerhq/wallet-api-client.
• 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, Filecoin, Solana.

---

Step 8 — Manual tests

Doc: Manual tests

• Sync: Add account; migrate account (add in prod, no crash); sync completes without error; big account (multi-page history).
• Receive / address: Verify address with device; verify address without device.
• Balance: Available balance correct.
• Broadcast: Send max empties account; send amount correct; cannot send more than balance.
• Operations: Optimistic operation correct; history complete; tx id correct; “View on explorer” works; operation account correct.
• Account: Countervalue (fiat) correct if enabled; favorite works.

---

Deployment checklist (all steps)

#	Step	Owner	Action	Done
0	Agreement	Project	Submit form; wait for Ledger response.
0	Device app	Ledger or us	For Chain 138: confirm Ethereum app + chainId 138 (our fork has it); or follow Device App Kit if Ledger requests.
1	Currency	Ledger / us	Add Chain 138 to @ledgerhq/cryptoassets (id, ethereumLikeInfo.chainId 138, explorerViews).
2	Device app lib	Ledger / us	For EVM: use hw-app-eth; ensure chainId 138 in tx building/signing.
3	Create module	Ledger / us	Use or extend Ethereum coin-module; config RPC + explorer for Chain 138.
4	Derivation/Signer	Ledger / us	Standard 44'/60'; getAddress + sign integrated.
5	API	Ledger / us	RPC + Blockscout URLs provided; Ledger may add indexer/config.
6	LLD & LLM	Ledger / us	live-common setup + config; LLD/LLM currency list + i18n; run dev and QA.
7	Wallet API	Ledger / us	wallet-api: Ethereum family supports chainId 138 or new family; LL adapter updated.
8	Manual tests	Ledger / us	Execute send/receive test plan (sync, receive, balance, broadcast, operations, account).

---

Optional: tokens, swap, staking

• Tokens: Before you start → Device app → API → CAL; add integration/bot and manual tests.
• Swap: Device app → Wallet API → Exchange SDK → Swap Live App → Ledger Wallet; manual + E2E.
• Staking: Strategy → API → manual + E2E/integration/React/bot.

---

Chain 138 quick reference

Item	Value
Chain name	Defi Oracle Meta Mainnet
Chain ID	138 (0x8a)
SLIP-44	60 (Ethereum)
Derivation	44'/60'/0'/0/0
Native	ETH, 18 decimals
Public RPC	https://rpc-http-pub.d-bis.org, https://rpc.d-bis.org, etc.
Explorer	https://explorer.d-bis.org (Blockscout, EIP3091)
Chainlist	https://chainlist.org/chain/138
App-ethereum fork	pr-workspace/app-ethereum (network.c, defi_oracle.mk)

---

References

• Ledger – Adding your blockchain
• Ledger – Device App Kit
• Ledger – Blockchain integration form
• Ledger Live monorepo
• Ledger App-Ethereum
• ADD_CHAIN138_TO_LEDGER_LIVE — Chain 138 submission and materials