d-bis/LedgerLive
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add full Chain 138 integration: 8 steps, chain spec, app-ethereum config, docs

Browse Source 
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
defiQUG
2026-02-12 15:57:08 -08:00
parent 17020ba236
commit bee1d29d55
33 changed files with 1444 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

211
docs/ADD_CHAIN138_TO_LEDGER_LIVE.md Normal file
View File

@@ -0,0 +1,211 @@
# Add Chain 138 (Defi Oracle Meta Mainnet) to Ledger Live
**Last Updated:** 2026-02-13
**Status:** Action plan and submission guide
---
## Complete this now (your only required action) — ✅ Submitted 2026-02-13
The form has been submitted. Next: await Ledger’s response and follow their process (agreement + integration steps). For reference, the steps were:
1. **Open:** [Ledger blockchain integration form](https://tally.so/r/mORpv8).
2. **Paste** the text below into the form field *"What are you looking from Ledger?"*, then replace `[your email/Telegram]` with your contact.
3. **Submit** the form. Ledger will reply with next steps (and any agreement).
**Copy-paste block:**
```
We would like to add Defi Oracle Meta Mainnet (Chain ID 138) to Ledger Live so users can manage ETH and tokens on this EVM chain natively in Ledger Wallet.
- Chain name: Defi Oracle Meta Mainnet
- Chain ID: 138 (0x8a)
- EVM-compatible (EIP-155, EIP-1559), standard derivation 44'/60'
- Public RPCs and block explorer are live; chain is listed on Chainlist (chainlist.org/chain/138).
- We already have Chain ID 138 configured in a Ledger App-Ethereum fork (network name "Defi Oracle Meta", ticker ETH) and can provide specs or PRs as needed.
Preferred contact: [your email/Telegram]
```
---
## Overview
Ledger Live does not support user-added custom EVM networks. To have **Defi Oracle Meta Mainnet (Chain ID 138)** appear and work in Ledger Live (desktop/mobile), the chain must be added to Ledger’s supported list via their **official blockchain integration process**.
This doc gives the steps and materials to request and support that integration.
---
## Step 1: Submit the official request (required first)
**Do not start code changes** before Ledger has accepted your request. Their developer portal states:
> ⚠️ Don't start the development without signing an agreement with our teams.
1. **Open the Ledger blockchain integration request form:**
**https://tally.so/r/mORpv8**
2. **Fill in the form** (e.g. “What are you looking from Ledger?”) with a short request to add **Defi Oracle Meta Mainnet (Chain ID 138)** to Ledger Live. Suggested text:
```
We would like to add Defi Oracle Meta Mainnet (Chain ID 138) to Ledger Live so users can manage ETH and tokens on this EVM chain natively in Ledger Wallet.
- Chain name: Defi Oracle Meta Mainnet
- Chain ID: 138 (0x8a)
- EVM-compatible (EIP-155, EIP-1559), standard derivation 44'/60'
- Public RPCs and block explorer are live; chain is listed on Chainlist (chainlist.org/chain/138).
- We already have Chain ID 138 configured in a Ledger App-Ethereum fork (network name "Defi Oracle Meta", ticker ETH) and can provide specs or PRs as needed.
Preferred contact: [your email/Telegram]
```
3. **Submit** and wait for Ledger to respond. They will guide you through the next steps (and any agreement).
---
## Step 2: What Ledger’s integration involves (after they respond)
Ledger’s [Adding your blockchain to Ledger Wallet](https://developers.ledger.com/docs/ledger-live/accounts/getting-started) guide outlines an **8-step process**. For an **EVM chain** like 138, the main touchpoints are:
| Step | What it means for Chain 138 |
|------|-----------------------------|
| **1 – Currency** | Register the chain in Ledger’s crypto-assets (e.g. `@ledgerhq/cryptoassets` in ledger-live), with `ethereumLikeInfo.chainId: 138` and explorerViews. |
| **2 – Device app lib** | Ethereum app already supports multiple chain IDs; use `hw-app-eth` with chainId 138 in tx building/signing. Chain 138 may need to be in **official** Ledger app-ethereum (see below). |
| **3 – Create module** | EVM chains often use the same “Ethereum” family module with different chain config (RPC, explorer). |
| **4 – Derivation / Signer** | Standard EVM: `44'/60'` (already used in our app-ethereum config). |
| **5 – API** | Ledger may use their own indexer/RPC or point to your public RPCs and Blockscout. |
| **6 – LLD & LLM** | Desktop and mobile Ledger Wallet apps: live-common setup, currency list, i18n; run dev and QA. |
| **7 – Wallet API** | wallet-api: Ethereum family extended for chainId 138 (or new family); Ledger Wallet adapter. |
| **8 – Manual tests** | Execute send/receive test plan (sync, receive, balance, broadcast, operations, account). |
**Full step-by-step (all steps, no gaps):** [LEDGER_BLOCKCHAIN_INTEGRATION_COMPLETE.md](LEDGER_BLOCKCHAIN_INTEGRATION_COMPLETE.md). **Generated code for all 8 steps:** [step-01-currency/](../step-01-currency/) through [step-08-manual-tests/](../step-08-manual-tests/) — drop-in snippets and config for each step.
Ledger will tell you exactly which repos (e.g. `ledger-live`, `app-ethereum`, `wallet-api`) and which files to change or which data to provide.
---
## Step 3: Materials to have ready for Ledger
When Ledger asks for chain details or integration data, you can point them to or paste the following.
**Project description (short/medium/long):** [DEFI_ORACLE_META_MAINNET_PROJECT_DESCRIPTION.md](DEFI_ORACLE_META_MAINNET_PROJECT_DESCRIPTION.md) — use the **medium** paragraph for Ledger or listing forms.
### 3.1 Chain specification (Chainlist-compatible)
Our canonical chain spec is in this repo at `pr-workspace/chains/_data/chains/eip155-138.json`. Summary:
| Field | Value |
|-------|--------|
| **name** | Defi Oracle Meta Mainnet |
| **chainId** | 138 |
| **networkId** | 1 |
| **shortName** | dfio-meta-main |
| **nativeCurrency** | Ether (ETH), 18 decimals |
| **slip44** | 60 (standard EVM) |
| **infoURL** | https://d-bis.org |
**RPC URLs (public):**
- `https://rpc-http-pub.d-bis.org`
- `wss://rpc-ws-pub.d-bis.org`
- `https://rpc.d-bis.org`
- `wss://rpc.d-bis.org`
- `https://rpc2.d-bis.org`
- `wss://ws.rpc.d-bis.org`
- `wss://ws.rpc2.d-bis.org`
- `https://rpc.public-0138.defi-oracle.io`
- `wss://rpc.public-0138.defi-oracle.io`
- `https://rpc.defi-oracle.io`
- `wss://wss.defi-oracle.io`
**Block explorer:**
- Blockscout: `https://explorer.d-bis.org` (EIP3091)
**Features:** EIP-155, EIP-1559.
### 3.2 Ledger App-Ethereum (device) configuration
We already have Chain 138 in our app-ethereum fork:
- **`pr-workspace/app-ethereum/src/network.c`** (line 42):
`{.chain_id = 138, .name = "Defi Oracle Meta", .ticker = "ETH"}`
- **`pr-workspace/app-ethereum/makefile_conf/chain/defi_oracle.mk`**:
`CHAIN_ID = 138`, `APPNAME = "Defi Oracle Meta"`, `TICKER = "ETH"`, derivation `44'/60'`
If Ledger asks for device-app changes, we can either:
- Propose a PR to **LedgerHQ/app-ethereum** adding the same entry to `network.c` (and any makefile/chain list they use), or
- Provide the exact patch/snippet for them to integrate.
### 3.3 References in this repo
- [PUBLIC_RPC_CHAIN138_LEDGER.md](./PUBLIC_RPC_CHAIN138_LEDGER.md) – RPC list, NPMplus mapping, Ledger usage.
- [CHAIN138_WALLET_CONFIG_VALIDATION.md](./CHAIN138_WALLET_CONFIG_VALIDATION.md) – Validated wallet config (MetaMask, ethers, Ledger).
- [LEDGER_CHAIN138_ISSUES_AND_WORKAROUNDS.md](./LEDGER_CHAIN138_ISSUES_AND_WORKAROUNDS.md) – Current limitations and workarounds (e.g. Ledger + MetaMask).
---
## Public code review repo for the Ledger Live team
**All public code, specs, and patches for Ledger team review:** [**https://github.com/bis-innovations/LedgerLive**](https://github.com/bis-innovations/LedgerLive)
Use this repo to publish Chain 138 integration materials (cryptoassets entries, config snippets, app-ethereum changes, or full patches) so the Ledger Live team can review before or alongside any PR to LedgerHQ repos. Clone, add your changes, push, and share the repo or specific branches/PRs with Ledger when they ask for code.
### Initialize and push (from GitHub instructions)
**New repo (first commit):**
```bash
echo "# LedgerLive" >> README.md
git init
git add README.md
git commit -m "first commit"
git branch -M main
git remote add origin https://github.com/bis-innovations/LedgerLive.git
git push -u origin main
```
**Existing local repo:**
```bash
git remote add origin https://github.com/bis-innovations/LedgerLive.git
git branch -M main
git push -u origin main
```
---
## Step 4: Optional – prepare for a future PR to Ledger Live
If Ledger confirms that adding Chain 138 is done by editing their **ledger-live** monorepo (e.g. `libs/ledgerjs/packages/cryptoassets` or `libs/ledger-live-common`), you can:
1. **Publish for review:** Push your work to [bis-innovations/LedgerLive](https://github.com/bis-innovations/LedgerLive) for Ledger team code review.
2. Clone upstream: `git clone https://github.com/LedgerHQ/ledger-live.git`
3. Follow their [installation and contribution guide](https://github.com/LedgerHQ/ledger-live/blob/develop/CONTRIBUTING.md).
4. Locate where EVM chains are defined (often a data file or config listing chainId, name, RPC, explorer).
5. Add an entry for Chain ID 138 using the spec in **Step 3.1** and any format Ledger requires.
Do this **only after** Ledger has accepted the request and indicated where to add the chain; their structure may differ from public guesses.
---
## Summary checklist
- [x] Submit the request at **https://tally.so/r/mORpv8** (describe Chain 138 and add preferred contact) — **Done 2026-02-13.**
- [ ] Wait for Ledger’s response and follow their process (agreement + integration steps).
- [x] **Materials ready:** chain spec ([chains/eip155-138.json](../chains/eip155-138.json)), public RPCs, explorer, app-ethereum config ([app-ethereum/makefile_conf/chain/defi_oracle.mk](../app-ethereum/makefile_conf/chain/defi_oracle.mk)), project description ([DEFI_ORACLE_META_MAINNET_PROJECT_DESCRIPTION.md](DEFI_ORACLE_META_MAINNET_PROJECT_DESCRIPTION.md)) — all present in repo.
- [x] **Deployment reference ready:** [LEDGER_BLOCKCHAIN_INTEGRATION_COMPLETE.md](../11-references/LEDGER_BLOCKCHAIN_INTEGRATION_COMPLETE.md) — full 8-step integration with gaps filled, Chain 138 quick reference, and deployment checklist.
- [ ] If Ledger asks for a PR or code review: publish code to **[bis-innovations/LedgerLive](https://github.com/bis-innovations/LedgerLive)** for their review; use the materials above and [LEDGER_BLOCKCHAIN_INTEGRATION_COMPLETE.md](../11-references/LEDGER_BLOCKCHAIN_INTEGRATION_COMPLETE.md) with their contribution guidelines.
---
## References
- **Public code review for Ledger team:** [**bis-innovations/LedgerLive**](https://github.com/bis-innovations/LedgerLive) — use for all Chain 138 integration code/specs/patches for Ledger Live team review.
- **Full 8-step integration (this repo):** [LEDGER_BLOCKCHAIN_INTEGRATION_COMPLETE.md](../11-references/LEDGER_BLOCKCHAIN_INTEGRATION_COMPLETE.md) — all steps, deployment checklist, Chain 138 quick reference.
- **Ledger – Adding your blockchain:** https://developers.ledger.com/docs/ledger-live/accounts/getting-started
- **Ledger – Blockchain integration form:** https://tally.so/r/mORpv8
- **Ledger Live monorepo:** https://github.com/LedgerHQ/ledger-live
- **Ledger App-Ethereum:** https://github.com/LedgerHQ/app-ethereum
- **Ledger Wallet API:** https://github.com/LedgerHQ/wallet-api
- **Chainlist (Chain 138):** https://chainlist.org/chain/138

96
docs/CHAIN138_TOKEN_ADDRESSES.md Normal file
View File

@@ -0,0 +1,96 @@
# Token Contract Addresses - ChainID 138
**Last Updated:** 2026-01-31
**Document Version:** 1.0
**Status:** Active Documentation
---
**Network**: ChainID 138 (SMOM-DBIS-138)
**RPC Endpoint** (admin/deployment): `http://192.168.11.211:8545` (RPC_CORE_1) or `https://rpc-core.d-bis.org`
**Explorer**: https://explorer.d-bis.org
**Last Updated**: 2025-12-24
---
## 📋 ERC20 Token Contracts
### Standard Tokens
| Token | Symbol | Address | Decimals | Status | Notes |
|-------|--------|---------|----------|--------|-------|
| **Wrapped Ether** | WETH | `0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2` | 18 | ✅ Pre-deployed | Pre-deployed in Genesis |
| **Wrapped Ether v10** | WETH10 | `0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9f` | 18 | ✅ Pre-deployed | Pre-deployed in Genesis |
| **Chainlink Token** | LINK | `0xb7721dD53A8c629d9f1Ba31a5819AFe250002b03` | 18 | ✅ Deployed | Used for CCIP fees |
### Compliant Stablecoins
| Token | Symbol | Address | Decimals | Status | Notes |
|-------|--------|---------|----------|--------|-------|
| **Tether USD (Compliant)** | cUSDT | `0x93E66202A11B1772E55407B32B44e5Cd8eda7f22` | 6 | ✅ Deployed | Compliant USDT token |
| **USD Coin (Compliant)** | cUSDC | `0xf22258f57794CC8E06237084b353Ab30fFfa640b` | 6 | ✅ Deployed | Compliant USDC token |
---
## 🔗 Token Registry
The tokens can be tracked through the TokenRegistry contract:
| Contract | Address | Purpose |
|----------|---------|---------|
| **TokenRegistry** | `0x91Efe92229dbf7C5B38D422621300956B55870Fa` | Centralized registry for all tokens on ChainID 138 |
---
## 📊 Summary
### Total Token Contracts: 5
1. **WETH** - `0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2`
2. **WETH10** - `0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9f`
3. **LINK** - `0xb7721dD53A8c629d9f1Ba31a5819AFe250002b03`
4. **CompliantUSDT (cUSDT)** - `0x93E66202A11B1772E55407B32B44e5Cd8eda7f22`
5. **CompliantUSDC (cUSDC)** - `0xf22258f57794CC8E06237084b353Ab30fFfa640b`
---
## 📝 Notes
1. **WETH9 and WETH10** were pre-deployed in the genesis block
2. **LINK token** is used for CCIP (Cross-Chain Interoperability Protocol) fees
3. **Compliant stablecoins** (cUSDT, cUSDC) include regulatory compliance features
4. All addresses are checksummed and verified on-chain
5. Token list maintained at: `token-lists/lists/dbis-138.tokenlist.json`
---
## 🔍 Verification
To verify a token contract on-chain:
```bash
# Check contract code
cast code <TOKEN_ADDRESS> --rpc-url http://192.168.11.211:8545
# Check token details (name, symbol, decimals)
cast call <TOKEN_ADDRESS> "name()" --rpc-url http://192.168.11.211:8545
cast call <TOKEN_ADDRESS> "symbol()" --rpc-url http://192.168.11.211:8545
cast call <TOKEN_ADDRESS> "decimals()" --rpc-url http://192.168.11.211:8545
```
---
## Token alignment
| Source | File |
|--------|------|
| Token list | `token-lists/lists/dbis-138.tokenlist.json` |
| Canonical | `smom-dbis-138/services/token-aggregation/src/config/canonical-tokens.ts` (FALLBACK_ADDRESSES) |
| Allowlist | `dbis_core/src/core/defi/tezos-usdtz/allowlist.config.ts` (ALLOWED_CHAIN138_TOKENS) |
---
**References:**
- Token List: `token-lists/lists/dbis-138.tokenlist.json`
- Deployment Docs: `explorer-monorepo/docs/DEPLOYMENT_COMPLETE_CHAINID_138.md`
- Contract Reference: [CONTRACT_ADDRESSES_REFERENCE.md](CONTRACT_ADDRESSES_REFERENCE.md), [CONTRACT_INVENTORY_AND_VERIFICATION.md](CONTRACT_INVENTORY_AND_VERIFICATION.md)

89
docs/DEFI_ORACLE_META_MAINNET_PROJECT_DESCRIPTION.md Normal file
View File

@@ -0,0 +1,89 @@
# Defi Oracle Meta Mainnet (Chain ID 138) — Project Description
**Last Updated:** 2026-02-12
**Purpose:** Reusable project descriptions for listings, Ledger, Chainlist, CoinGecko, outreach, and documentation.
---
## Short (1–2 sentences)
**For:** Forms, badges, meta tags, character-limited fields.
**Option A (technical):**
Defi Oracle Meta Mainnet (Chain ID 138) is an EVM-compatible blockchain built on Hyperledger Besu with QBFT consensus, offering ~2s block time, native oracle integration, and CCIP cross-chain bridges.
**Option B (use-case):**
Defi Oracle Meta Mainnet is an enterprise-grade EVM chain (Chain ID 138) with compliant stablecoins, cross-chain bridges (CCIP), and native oracle support for institutional DeFi.
**Option C (minimal):**
Production EVM chain (Chain ID 138) on Hyperledger Besu with QBFT, CCIP bridges, and Blockscout explorer.
---
## Medium (one paragraph)
**For:** Ledger submission, Chainlist, CoinGecko chain description, listing blurbs.
DeFi Oracle Meta Mainnet (Chain ID 138) is an enterprise-grade, EVM-compatible blockchain built on Hyperledger Besu with QBFT consensus. It features ~2-second block time, native oracle integration, Chainlink CCIP cross-chain bridges to Ethereum Mainnet and other EVM chains, and compliant stablecoins (cUSDT, cUSDC, cEURC) for institutional DeFi applications. The network is production-ready with public RPC endpoints, a Blockscout block explorer, and full MetaMask and Chainlist support.
---
## Long (full description)
**For:** README, submission packages, detailed outreach, documentation.
**DeFi Oracle Meta Mainnet (Chain ID 138)** is a production-ready, EVM-compatible blockchain built on **Hyperledger Besu** with **QBFT consensus**. It provides immediate finality with approximately **2-second block time** and is designed for institutional DeFi with native oracle integration, cross-chain bridges, and compliant assets.
**Network:** Chain ID 138 (0x8a), native currency ETH (18 decimals), standard EVM derivation (SLIP-44: 60). EIP-155 and EIP-1559 supported.
**Infrastructure:** Tiered architecture (validators, sentries, RPC nodes), public RPC endpoints (HTTPS and WebSocket), and **Blockscout** block explorer at https://explorer.d-bis.org. Information and docs: https://d-bis.org.
**Cross-chain:** Full **Chainlink CCIP** implementation (CCIP Router, CCIPWETH9Bridge, CCIPWETH10Bridge) for cross-chain transfers with Ethereum Mainnet and other supported chains. LINK-based fees; relay and monitoring tooling deployed.
**Assets:** Compliant stablecoins (cUSDT, cUSDC, cEURC), WETH9/WETH10, LINK, and a token registry with compliance controls. Oracle price feeds and keeper infrastructure for institutional use.
**Ecosystem:** MetaMask integration (custom network and Chainlist), thirdweb bridge support, token aggregation and market-data APIs, and deployment automation. Listed on Chainlist (chainlist.org/chain/138).
---
## Key facts (bullet form)
Use for forms, tables, or “About” sections:
| Item | Value |
|------|--------|
| **Name** | Defi Oracle Meta Mainnet |
| **Chain ID** | 138 (0x8a) |
| **Network ID** | 1 |
| **Consensus** | QBFT (Hyperledger Besu) |
| **Block time** | ~2 seconds |
| **Native currency** | ETH (18 decimals) |
| **Explorer** | https://explorer.d-bis.org (Blockscout) |
| **Info / docs** | https://d-bis.org |
| **EVM** | Yes (EIP-155, EIP-1559) |
| **Derivation** | 44'/60' (standard EVM) |
**Features:** Public RPC (HTTPS/WSS), CCIP bridges, compliant stablecoins, oracle feeds, Blockscout, Chainlist, MetaMask, thirdweb.
---
## RPC and explorer (copy-paste)
**RPC (HTTP):**
https://rpc-http-pub.d-bis.org, https://rpc.d-bis.org, https://rpc2.d-bis.org, https://rpc.defi-oracle.io, https://rpc.public-0138.defi-oracle.io
**RPC (WebSocket):**
wss://rpc-ws-pub.d-bis.org, wss://rpc.d-bis.org, wss://ws.rpc.d-bis.org, wss://ws.rpc2.d-bis.org, wss://wss.defi-oracle.io, wss://rpc.public-0138.defi-oracle.io
**Block explorer:**
https://explorer.d-bis.org
---
## References
- [CONTRACT_ADDRESSES_REFERENCE](CONTRACT_ADDRESSES_REFERENCE.md) — Canonical contract addresses (Chain 138)
- [CHAINS_AND_PROTOCOLS_BRIDGE_INTEGRATION](CHAINS_AND_PROTOCOLS_BRIDGE_INTEGRATION.md) — Bridge chains and protocol acceptance
- [ADD_CHAIN138_TO_LEDGER_LIVE](../04-configuration/ADD_CHAIN138_TO_LEDGER_LIVE.md) — Ledger Live submission (uses medium description)
- [COINGECKO_SUBMISSION_PACKAGE](../04-configuration/coingecko/COINGECKO_SUBMISSION_PACKAGE.md) — CoinGecko chain/token submission
- Main project repo — Full project README (see bis-innovations/proxmox or d-bis smom-dbis-138)

237
docs/LEDGER_BLOCKCHAIN_INTEGRATION_COMPLETE.md Normal file
View File

@@ -0,0 +1,237 @@
# 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**](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](ADD_CHAIN138_TO_LEDGER_LIVE.md) for the Chain 138–specific action plan and submission text. **Generated code for all 8 steps:** [step-01-currency/](../step-01-currency/) through [step-08-manual-tests/](../step-08-manual-tests/). **Gaps and missing integrations (tests, fixes, checklist):** [GAPS_AND_MISSING_INTEGRATIONS.md](../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.
---
## Step 1 — Currency (Cryptoassets library)
**Doc:** [1 - Currency](https://developers.ledger.com/docs/ledger-live/accounts/integration/blockchain/cryptoassets-library)
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
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](https://developers.ledger.com/docs/ledger-live/accounts/integration/blockchain/js-bindings) *(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](https://developers.ledger.com/docs/ledger-live/accounts/integration/blockchain/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](https://developers.ledger.com/docs/ledger-live/accounts/integration/blockchain/address-derivation)
- 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:**
```bash
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](https://github.com/LedgerHQ/ledger-live/wiki/LLC:derivation).
---
## Step 5 — API
**Doc:** [5 - API](https://developers.ledger.com/docs/ledger-live/accounts/integration/blockchain/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](../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.
---
## Step 6 — LLD & LLM (desktop and mobile)
**Doc:** [6 - LLD & LLM](https://developers.ledger.com/docs/ledger-live/accounts/integration/blockchain/desktop-mobile)
**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](https://developers.ledger.com/docs/ledger-live/accounts/integration/blockchain/ledger-services-kit)
**In [LedgerHQ/wallet-api](https://github.com/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](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).
---
## Step 8 — Manual tests
**Doc:** [Manual tests](https://developers.ledger.com/docs/ledger-live/accounts/integration/blockchain/test-plan)
- **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](https://tally.so/r/mORpv8); 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](https://developers.ledger.com/docs/ledger-live/accounts/integration/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](https://developers.ledger.com/docs/ledger-live/accounts/integration/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](https://developers.ledger.com/docs/ledger-live/accounts/getting-started)
- [Ledger – Device App Kit](https://developers.ledger.com/docs/device-app/getting-started)
- [Ledger – Blockchain integration form](https://tally.so/r/mORpv8)
- [Ledger Live monorepo](https://github.com/LedgerHQ/ledger-live)
- [Ledger App-Ethereum](https://github.com/LedgerHQ/app-ethereum)
- [ADD_CHAIN138_TO_LEDGER_LIVE](../04-configuration/ADD_CHAIN138_TO_LEDGER_LIVE.md) — Chain 138 submission and materials