# Ledger Chain 138 Integration — Gaps and Missing Integrations

**Last Updated:** 2026-02-12  
**Purpose:** Test results and checklist of gaps, fixes, and possible missing integrations for the 8-step Ledger codebase.

---

## Tests performed

| Check | Result |
|-------|--------|
| Step 8 `run-checklist.sh` | ✅ Runs and prints full manual test plan |
| Step 1 currency vs eip155-138.json | ✅ chainId 138, slip44 60, explorer URLs match |
| Step 5 RPC list vs ADD_CHAIN138 doc | ✅ Same public RPCs and explorer |
| Step 3 explorer API | ✅ **Fixed** — was Etherscan-style; now uses Blockscout v2 `GET /api/v2/addresses/{address}/transactions` |
| Step 4 signer types vs hw-app-eth | ✅ publicKey used; Ledger may use `pubKey` in some APIs — confirm in ledger-live |
| Step 6 config default shape | ⚠️ Ledger live-config may expect different shape (e.g. `status: "active"` string); confirm in ledger-live |
| Step 7 Wallet API | ⚠️ Ethereum family may already support multiple chainIds; our snippets are for extension only |

---

## Gaps addressed in repo

1. **Step 3 — Blockscout API**  
   `network-explorer.ts` previously used Etherscan-style `module=account&action=txlist`. Blockscout uses REST v2: `GET /api/v2/addresses/{address_hash}/transactions` with pagination via `next_page_params` (block_number, index, items_count). The implementation was updated to use this API and export `EXPLORER_API_V2`.

---

## Possible missing integrations (to add when Ledger confirms)

### 1. Tokens (CAL / token list)

- **Gap:** No Step 1-style token entries or Crypto Assets List (CAL) for Chain 138 tokens (e.g. LINK, WETH, cUSDT, cUSDC).
- **Action:** After Ledger adds the chain, follow [Tokens integration](https://developers.ledger.com/docs/ledger-live/accounts/integration/tokens/before-you-start): device app (if needed), API, CAL. Provide token contract addresses from [CHAIN138_TOKEN_ADDRESSES](docs/CHAIN138_TOKEN_ADDRESSES.md).

### 2. Swap

- **Gap:** No swap provider or Exchange SDK integration for Chain 138.
- **Action:** Optional; only if Ledger or a partner will support swap on Chain 138. See [Swap integration](https://developers.ledger.com/docs/ledger-live/accounts/integration/swap/before-you-start).

### 3. Staking

- **Gap:** No staking API or UI for Chain 138 (e.g. validator staking if applicable).
- **Action:** Only if Chain 138 has staking and Ledger supports it; follow [Staking strategy](https://developers.ledger.com/docs/ledger-live/accounts/integration/staking/strategy).

### 4. Clear Signing plugin (dApps)

- **Gap:** No Clear Signing plugin for Chain 138–specific contract calls (e.g. CCIP, bridge) so the device shows human-readable descriptions.
- **Action:** Optional; see [Clear Signing for dApps](https://developers.ledger.com/docs/clear-signing/for-dapps/get-started) and [Write a plugin](https://developers.ledger.com/docs/ledger-live/discover/integration/dapp-browser/plugin).

### 5. i18n (LLD / LLM error keys)

- **Gap:** Step 6 README says “add error translation keys” but does not list the exact keys or strings.
- **Action:** When adding the currency to LLD/LLM, copy the same error keys used for Ethereum (or the family) and add any Chain 138–specific messages. Ledger’s contribution guide will specify the key format (e.g. `errors.defi_oracle_meta_mainnet.*`).

### 6. live-common supported currencies (exact files)

- **Gap:** Step 6 references `live-common-set-supported-currencies.js` and `live-common-setup.js`; exact paths can differ by ledger-live version (e.g. under `apps/ledger-live-desktop/` or generated).
- **Action:** After cloning ledger-live, search for where supported currencies are set and add `defi_oracle_meta_mainnet` there; confirm file names in the current branch.

### 7. wallet-api FAMILIES and union types

- **Gap:** Step 7 snippets show validation/types/serializer for Ethereum with chainId 138; the actual wallet-api repo may extend Ethereum family instead of adding a new family. The `FAMILIES` array and `Transaction` union may not need a new entry if Ethereum already supports multiple chainIds.
- **Action:** Check wallet-api `packages/core/src/families/ethereum` and `common.ts`; if chainId is already a field in the schema, add 138 to allowed values and ensure Ledger Wallet adapter maps it.

### 8. Currency optional fields

- **Gap:** Step 1 currency did not set `blockAvgTime` or `disableCountervalue`.
- **Status:** ✅ **Addressed** — `step-01-currency/currencies.chain138.ts` now includes `blockAvgTime: 2`. Uncomment `disableCountervalue: true` in the file if fiat should not be shown for Chain 138.

### 9. App-ethereum icon for Chain 138

- **Gap:** Step 2 README mentions “Ledger may require a network icon.” Our app-ethereum fork has the network entry but may need an icon asset for the device UI.
- **Action:** If Ledger requests an icon, follow [Device App Kit deliverables (Icons)](https://developers.ledger.com/docs/device-app/submission-process/deliverables/icons) or provide a standard Ethereum-style icon for Chain 138.

### 10. E2E and integration tests

- **Gap:** Step 8 is manual only; no automated E2E or integration test scripts in this repo.
- **Action:** Ledger’s flow includes [E2E](https://developers.ledger.com/docs/ledger-live/accounts/integration/blockchain/qa-requirements/e2e) and [Integration](https://developers.ledger.com/docs/ledger-live/accounts/integration/blockchain/qa-requirements/integ) tests. After integration, add or run these in the ledger-live monorepo for Chain 138.

---

## Summary

| Category | Status |
|----------|--------|
| **Fixed in repo** | Step 3 Blockscout API (v2) |
| **Confirm with Ledger** | Step 6 config shape, Step 7 extend vs new family, Step 4 pubKey vs publicKey |
| **Add when needed** | Tokens/CAL, optional Swap/Staking, Clear Signing plugin, i18n keys, blockAvgTime/disableCountervalue, app-ethereum icon |
| **Discover at integration time** | Exact LLD/LLM currency list file paths, E2E/integration test setup |

Use this document alongside [LEDGER_BLOCKCHAIN_INTEGRATION_COMPLETE.md](docs/LEDGER_BLOCKCHAIN_INTEGRATION_COMPLETE.md) and the step READMEs when implementing or handing off to Ledger.