proxmox/docs/04-configuration/FULL_PARITY_TOKEN_COVERAGE_RUNBOOK.md

Full Parity Token Coverage — Logos, Pricing, Token Lists, All Networks, All Entry Points

Last Updated: 2026-02-28
Purpose: Achieve complete coverage for token logos, pricing, and token lists across all networks and all aggregator/wallet entry points.

---

1. Coverage Matrix

Dimension	Target
Networks	138, 1, 651940, 56, 137, 100, 10, 42161, 8453, 43114, 25, 42220, 1111
Token lists	Uniswap format with logoURI; per-chain and unified
Logos	512×512 PNG for CoinGecko/CMC; logoURI for all tokens
Pricing	CoinGecko, CMC, on-chain oracle; report API
Entry points	MetaMask, Trust Wallet, Chainlist, CoinGecko, CMC, 1inch, Paraswap, Chain 138 Snap

---

2. Entry Points and Requirements

Entry Point	Token List	Logos	Pricing	Notes
MetaMask	CoinGecko (built-in) or custom URL	logoURI per token	CoinGecko API	Chain 138 not in built-in; use Snap token list
Trust Wallet	Trust Wallet registry	Trust Wallet assets	CoinGecko/CMC	PR to trustwallet/wallet-core
Chainlist	eip155-138.json	Chain icon	—	04-configuration/pr-ready/
CoinGecko	Submit chain + tokens	512×512 PNG	CoinGecko API	Primary for MetaMask
CoinMarketCap	Submit chain + tokens	512×512 PNG	CMC API	Fallback for some wallets
Chain 138 Snap	token-aggregation API	logoURI from API	Report API	GET /api/v1/report/token-list
1inch / Paraswap	Token list URL	logoURI	Their APIs	Add token list URL when supported
Explorer	Blockscout / custom	—	—	Token verification

---

3. Single Source of Truth

Asset	Location	Used By
Canonical tokens	smom-dbis-138/services/token-aggregation/src/config/canonical-tokens.ts	Report API, token-list, coingecko, cmc
Token mapping (cross-chain)	config/token-mapping-multichain.json	Bridge tooling, relay
Networks (EIP-3085)	smom-dbis-138/services/token-aggregation/src/config/networks.ts	Snap, wallet_addEthereumChain
Chain configs	smom-dbis-138/services/token-aggregation/src/config/chains.ts	Indexer, report API
Logo URLs	canonical-tokens.ts (getLogoUriForSpec), Trust Wallet assets	Token list, CoinGecko
512×512 logos	docs/04-configuration/coingecko/logos/ (prepare-token-logos-512x512.sh)	CoinGecko/CMC submission

---

4. Per-Network Token List Coverage

Chain ID	Network	Tokens in canonical-tokens	Report API	Token list URL
138	Chain 138	✅ Full	✅	?chainId=138
651940	ALL Mainnet	✅ cUSDC, cUSDT, WETH	✅	?chainId=651940
1	Ethereum	✅ (L2_CHAIN_IDS)	✅	?chainId=1
56	BSC	✅	✅	?chainId=56
137	Polygon	✅	✅	?chainId=137
100	Gnosis	✅	✅	?chainId=100
10	Optimism	✅	✅	?chainId=10
42161	Arbitrum	Env/fallback	Add to chains.ts	?chainId=42161
8453	Base	Env/fallback	Add to chains.ts	?chainId=8453
43114	Avalanche	Env/fallback	Add to chains.ts	?chainId=43114
25	Cronos	✅ USDW, etc.	Add to chains.ts	?chainId=25
42220	Celo	Env	Add to chains.ts	?chainId=42220
1111	Wemix	Env	Add to chains.ts	?chainId=1111

---

5. Implementation Checklist

5.1 Token-Aggregation (All Networks)

• Add chains 42161, 8453, 43114, 25, 42220, 1111 to chains.ts
• Add WETH9/WETH10 + cUSDT/cUSDC addresses per chain from token-mapping-multichain.json
• Add all networks to networks.ts with iconUrls (Trust Wallet fallback)
• Ensure getSupportedChainIds() returns all 13 chains
• Deploy token-aggregation and proxy /api/v1/* before Blockscout

5.2 Logos

• Run prepare-token-logos-512x512.sh (requires ImageMagick)
• Run upload-token-logos-to-ipfs.sh — see IPFS_TOKEN_LOGOS_RUNBOOK
• Verify all 23+ tokens have 512×512 PNG in docs/04-configuration/coingecko/logos/
• Ensure getLogoUriForSpec() returns valid Trust Wallet URLs for all tokens
• Add chain logos (138, 651940) for Chainlist/CoinGecko

5.3 Token Lists (Unified)

• Export unified token list: GET /api/v1/report/token-list (no chainId = all chains)
• Publish token list URL for 1inch/Paraswap: https://explorer.d-bis.org/api/v1/report/token-list
• Sync DUAL_CHAIN_TOKEN_LIST, metamask provider tokens.js with canonical-tokens
• Add Chainlist eip155-138.json to pr-ready (done)

5.4 Pricing

• Submit Chain 138 and 651940 to CoinGecko (chain + tokens)
• Submit to CoinMarketCap
• Consensys outreach for MetaMask native support
• Document on-chain oracle addresses per chain for dApp use

5.5 Entry Point Submissions

Entry Point	Action	Doc
CoinGecko	Submit chain + tokens via form	CMC_COINGECKO_SUBMISSION_RUNBOOK
CMC	Submit via listing form	Same
Trust Wallet	PR to wallet-core	ADD_CHAIN138_TO_TRUST_WALLET
Chainlist	Submit eip155-138.json	pr-ready/README
1inch	Token list URL (when chain supported)	—
Paraswap	Token list URL (when chain supported)	—

---

6. Commands

# Prepare logos (requires ImageMagick)
./docs/04-configuration/coingecko/scripts/prepare-token-logos-512x512.sh

# Upload logos to IPFS (requires ipfs daemon or PINATA_JWT)
./scripts/upload-token-logos-to-ipfs.sh

# Export report data for submission
API_BASE="https://explorer.d-bis.org"
for chain in 138 651940 1 56 137 100 10 42161 8453 43114 25 42220 1111; do
  curl -s "${API_BASE}/api/v1/report/coingecko?chainId=$chain" -o "report-coingecko-${chain}.json"
  curl -s "${API_BASE}/api/v1/report/cmc?chainId=$chain" -o "report-cmc-${chain}.json"
done

# Verify token list
curl -s "${API_BASE}/api/v1/report/token-list" | jq '.tokens | length'
curl -s "${API_BASE}/api/v1/report/token-list?chainId=138" | jq '.tokens[] | {symbol, logoURI}'

# Verify Snap API
./metamask-integration/chain138-snap/scripts/verify-snap-api-and-icons.sh "$API_BASE"

---

7. References

• PUBLICATION_LOCATIONS_MASTER — All locations to publish token lists, liquidity pools, chain metadata, pricing
• PRICE_FEED_CHAIN138_METAMASK_AND_WALLETS
• TOKEN_AGGREGATION_REPORT_API_RUNBOOK
• CMC_COINGECKO_SUBMISSION_RUNBOOK
• IPFS_TOKEN_LOGOS_RUNBOOK — IPFS hosting for all logos (explorers, token lists)
• REPOSITORIES_AND_PRS_CHAIN138