bea1903ac9
Some checks failed
Deploy to Phoenix / deploy (push) Has been cancelled
Co-authored-by: Cursor <cursoragent@cursor.com>
135 lines
9.8 KiB
Markdown
135 lines
9.8 KiB
Markdown
# Chain 138 Wallet Ecosystem — Overview and Rationale
|
||
|
||
**Last Updated:** 2026-02-12
|
||
**Status:** Single reference for wallet support and why we built or request each piece
|
||
|
||
---
|
||
|
||
## Purpose
|
||
|
||
This document ties together **all** wallet-related work for **Defi Oracle Meta Mainnet (Chain ID 138)** and answers:
|
||
|
||
1. **Why we created the MetaMask Snap** when basic Chain 138 connectivity already works in MetaMask.
|
||
2. **Why we need Ledger Live** when we already use Ledger’s App-Ethereum (and have Chain 138 in our app-ethereum fork).
|
||
3. **What we do for Trust Wallet** (user workaround + official Wallet Core path).
|
||
4. **Where each piece lives** (docs, repos, runbooks).
|
||
|
||
---
|
||
|
||
## 1. Wallet support at a glance
|
||
|
||
| Wallet / component | Basic Chain 138 support | Full / native support (our goal) | Doc / action |
|
||
|---------------------------|--------------------------------------------|----------------------------------------------------|--------------|
|
||
| **MetaMask** | ✅ Add network via RPC; send/receive; dApps | ❌ No native Swaps/Bridge/USD pricing for 138 | Custom **Snap** for swap quotes, bridge routes, market data |
|
||
| **Ledger device (App-Ethereum)** | ⚠️ Our fork has 138; official app may not | Device can sign; does not provide RPC or UI | [LEDGER_CHAIN138_ISSUES_AND_WORKAROUNDS.md](./LEDGER_CHAIN138_ISSUES_AND_WORKAROUNDS.md), [ADD_CHAIN138_TO_LEDGER_LIVE.md](./ADD_CHAIN138_TO_LEDGER_LIVE.md) |
|
||
| **Ledger Live** | ❌ No custom EVM networks | Request Chain 138 in Ledger’s list | [ADD_CHAIN138_TO_LEDGER_LIVE.md](./ADD_CHAIN138_TO_LEDGER_LIVE.md) |
|
||
| **Trust Wallet** | ✅ Users can add 138 manually (Chainlist) | Official support via Wallet Core PR | [ADD_CHAIN138_TO_TRUST_WALLET.md](./ADD_CHAIN138_TO_TRUST_WALLET.md) |
|
||
|
||
**Chainlist:** Chain 138 is listed at [chainlist.org/chain/138](https://chainlist.org/chain/138); any wallet that supports “add custom network” (e.g. MetaMask, Trust Wallet) can use it today with our public RPCs.
|
||
|
||
---
|
||
|
||
## 2. Why we created the MetaMask Snap
|
||
|
||
### What already works without a Snap
|
||
|
||
- Add Chain 138 via `wallet_addEthereumChain` or Chainlist.
|
||
- Connect wallet, send/receive ETH and tokens, view balances, use dApps.
|
||
- On-chain oracle (ETH/USD) is deployed; dApps can read it.
|
||
|
||
### What does *not* work for Chain 138 in standard MetaMask
|
||
|
||
- **MetaMask Swaps** — Supports a fixed list of chains (Ethereum, BNB, Polygon, Arbitrum, Base, etc.). **Chain 138 is not in that list.** Users cannot swap on 138 from the native Swaps UI.
|
||
- **Portfolio Bridge** — Same: curated set of chains only; **Chain 138 is not included.** Bridging today is via CCIP or third-party UIs; LiFi does not support Chain 138.
|
||
- **Native USD prices** — MetaMask uses CoinGecko for USD. Chain 138 tokens are not listed there for 138, so the wallet does not show USD values for Chain 138 assets.
|
||
- **No public Snap** — Interoperability Snaps target non-EVM chains (Starknet, Solana, etc.). No existing Snap adds swap/bridge/pricing for an EVM chain like 138. Consensys controls native Swaps/Bridge; we cannot add 138 there without their support.
|
||
|
||
So: **basic connectivity is solved; full feature parity (in-wallet swap, bridge, pricing) is not.**
|
||
|
||
### Why we built a custom MetaMask Snap
|
||
|
||
We built the **Chain 138 Snap** so users get **in-MetaMask** swap quotes, bridge routes, and market data **without waiting** for Consensys to add Chain 138 to native Swaps/Bridge and price feeds.
|
||
|
||
| Feature | What the Snap does | Backend |
|
||
|----------------|--------------------|--------|
|
||
| **Swap quotes**| User gets quotes for Chain 138 (and ALL Mainnet) inside MetaMask | Our swap/quote API (token-aggregation or compatible) |
|
||
| **Bridge routes** | Show CCIP routes (e.g. WETH9/WETH10 → Ethereum Mainnet); user signs in MetaMask | Bridge API (CCIP + custom routes) |
|
||
| **Market data / pricing** | Token list and USD prices in Snap UI | Token-aggregation REST API |
|
||
| **Network params** | Chain 138 and ALL Mainnet EIP-3085 params | Same API |
|
||
|
||
The Snap does **not** add Chain 138 to MetaMask’s **native** Swaps or Portfolio Bridge; those remain Consensys-controlled. It **does** provide a supported way to offer swap, bridge, and pricing **inside** the wallet by calling our APIs. We continue Consensys outreach for native support in parallel (see [metamask-integration/docs/CONSENSYS_OUTREACH_PACKAGE.md](../../metamask-integration/docs/CONSENSYS_OUTREACH_PACKAGE.md)).
|
||
|
||
**References:**
|
||
- [METAMASK_CHAIN138_FEATURE_PARITY_ANALYSIS.md](./metamask/METAMASK_CHAIN138_FEATURE_PARITY_ANALYSIS.md) — Gaps and options.
|
||
- [SNAP_IMPLEMENTATION_ROADMAP.md](./metamask/SNAP_IMPLEMENTATION_ROADMAP.md) — What the Snap uses (APIs, phases).
|
||
- [metamask-integration/chain138-snap/](https://github.com/bis-innovations/metamask-integration/tree/main/chain138-snap) — Snap code, runbook, deploy, testing.
|
||
|
||
---
|
||
|
||
## 3. Why we need Ledger Live when we already use App-Ethereum
|
||
|
||
### App-Ethereum vs Ledger Live — different roles
|
||
|
||
| Component | What it is | What it does for Chain 138 |
|
||
|-----------|------------|-----------------------------|
|
||
| **Ledger App-Ethereum** | Firmware app **on the Ledger device** | Knows chain IDs and display names. When signing a tx for chain 138, the device can show “Defi Oracle Meta” and “ETH” **if** that chain is in the app’s config. It does **not** provide RPC URLs, balances, or any account UI. |
|
||
| **Ledger Live** | **Desktop and mobile app** (wallet UI) | Shows balances, history, send/receive UI. Supports only a **fixed list** of networks (Ethereum, Polygon, Arbitrum, Base, etc.). There is **no “Add custom network”** for arbitrary EVM chains. |
|
||
|
||
So:
|
||
|
||
- **App-Ethereum** = “device can **sign** for chain 138 and display the right name” (we have this in our fork: `pr-workspace/app-ethereum` with `network.c` and `defi_oracle.mk`).
|
||
- **Ledger Live** = “user can **see** Chain 138 and **use** it in the Ledger app.” Without Chain 138 in Ledger Live’s list, users **cannot** add the network, see 138 balances, or send/receive on 138 from Ledger Live.
|
||
|
||
RPC is always supplied by the **host** (Ledger Live, MetaMask, or another wallet), not by the device. So even with App-Ethereum supporting 138 on the device, **Ledger Live itself** must list Chain 138 to use it there.
|
||
|
||
### Why we request Ledger Live integration
|
||
|
||
- **Users who prefer Ledger Live** (no MetaMask) today have **no** way to use Chain 138 in Ledger Live; they must use “Ledger device + MetaMask” and add 138 in MetaMask.
|
||
- Adding Chain 138 to **Ledger Live** (via Ledger’s official process) gives those users **native** Chain 138 support: add network, see balances, send/receive, all inside Ledger Live.
|
||
- **App-Ethereum** remains necessary on the device so the hardware correctly identifies and signs for chain 138; **Ledger Live** is necessary so the wallet app exposes Chain 138 to the user. We need **both**.
|
||
|
||
**References:**
|
||
- [ADD_CHAIN138_TO_LEDGER_LIVE.md](./ADD_CHAIN138_TO_LEDGER_LIVE.md) — Request form, materials, checklist.
|
||
- [LEDGER_CHAIN138_ISSUES_AND_WORKAROUNDS.md](./LEDGER_CHAIN138_ISSUES_AND_WORKAROUNDS.md) — Device vs Live, workaround (MetaMask + Ledger).
|
||
- [LEDGER_BLOCKCHAIN_INTEGRATION_COMPLETE.md](../11-references/LEDGER_BLOCKCHAIN_INTEGRATION_COMPLETE.md) — Full 8-step integration reference.
|
||
|
||
---
|
||
|
||
## 4. Trust Wallet — what we do
|
||
|
||
- **Today:** Users can add Chain 138 **manually** in Trust Wallet using [Chainlist](https://chainlist.org/chain/138); no official Trust support required.
|
||
- **Goal:** Have Chain 138 in Trust Wallet’s **built-in** chain list via a PR to **Trust Wallet Core** (`registry.json`, codegen, tests).
|
||
|
||
Details, user steps, and Wallet Core PR steps: [ADD_CHAIN138_TO_TRUST_WALLET.md](./ADD_CHAIN138_TO_TRUST_WALLET.md).
|
||
|
||
---
|
||
|
||
## 5. Where repositories live (all in `~/projects/`)
|
||
|
||
All four wallet repositories are **separate** and live **individually** in the **projects** directory (sibling to `proxmox`):
|
||
|
||
| Repo | Path | Status |
|
||
|------|------|--------|
|
||
| **metamask-integration** | `~/projects/metamask-integration` | ✅ Yes / Completed |
|
||
| **LedgerLive** | `~/projects/LedgerLive` | ✅ Yes / Completed |
|
||
| **app-ethereum** | `~/projects/app-ethereum` | ✅ Yes / Completed |
|
||
| **TrustWallet-Integration** | `~/projects/TrustWallet-Integration` | ✅ Yes / Completed |
|
||
|
||
Clone commands and checklist: [CHAIN138_WALLET_REPOSITORIES.md](./CHAIN138_WALLET_REPOSITORIES.md).
|
||
|
||
---
|
||
|
||
## 6. Quick links
|
||
|
||
| Topic | Document |
|
||
|-------|----------|
|
||
| **This overview** | [CHAIN138_WALLET_ECOSYSTEM_AND_RATIONALE.md](./CHAIN138_WALLET_ECOSYSTEM_AND_RATIONALE.md) (this file) |
|
||
| **MetaMask Snap** — why & what | [METAMASK_CHAIN138_FEATURE_PARITY_ANALYSIS.md](./metamask/METAMASK_CHAIN138_FEATURE_PARITY_ANALYSIS.md), [SNAP_IMPLEMENTATION_ROADMAP.md](./metamask/SNAP_IMPLEMENTATION_ROADMAP.md) |
|
||
| **Snap** — build, deploy, test | [metamask-integration/chain138-snap/RUNBOOK.md](../../../metamask-integration/chain138-snap/RUNBOOK.md), [DEPLOY_VMID5000.md](../../../metamask-integration/chain138-snap/DEPLOY_VMID5000.md) |
|
||
| **Ledger** — device vs Live, workarounds | [LEDGER_CHAIN138_ISSUES_AND_WORKAROUNDS.md](./LEDGER_CHAIN138_ISSUES_AND_WORKAROUNDS.md) |
|
||
| **Ledger Live** — add Chain 138 | [ADD_CHAIN138_TO_LEDGER_LIVE.md](./ADD_CHAIN138_TO_LEDGER_LIVE.md) |
|
||
| **Trust Wallet** — add Chain 138 | [ADD_CHAIN138_TO_TRUST_WALLET.md](./ADD_CHAIN138_TO_TRUST_WALLET.md) |
|
||
| **Validated wallet config** (RPC, explorer) | [CHAIN138_WALLET_CONFIG_VALIDATION.md](./CHAIN138_WALLET_CONFIG_VALIDATION.md) |
|
||
| **All wallet repos (canonical ~/projects/ layout)** | [CHAIN138_WALLET_REPOSITORIES.md](./CHAIN138_WALLET_REPOSITORIES.md) |
|
||
| **Consensys outreach** (native Swaps/Bridge) | [metamask-integration/docs/CONSENSYS_OUTREACH_PACKAGE.md](../../../metamask-integration/docs/CONSENSYS_OUTREACH_PACKAGE.md) |
|