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

chore: sync all changes to Gitea
Some checks failed
Deploy to Phoenix / deploy (push) Has been cancelled
Details

Browse Source 
- Config, docs, scripts, and backup manifests
- Submodule refs unchanged (m = modified content in submodules)

Made-with: Cursor
This commit is contained in:
defiQUG
2026-03-02 11:37:34 -08:00
parent ed85135249
commit b3a8fe4496
883 changed files with 73580 additions and 4796 deletions
Download Patch File Download Diff File Expand all files Collapse all files

219
docs/07-ccip/CHAIN138_COMPLETE_ROUTING_TABLE.md
View File

@@ -1,219 +0,0 @@
# Chain 138 → All Possible Token Swap & Bridge Routes
**Last Updated:** 2026-02-16
**Status:** Complete reference
**Source of truth:** `config/token-mapping.json`, `config/token-mapping-multichain.json`, bridge routes API
---
## Overview
This document provides a **complete routing table** from Chain 138 to all possible token swaps and bridge destinations. Routes are organized by: (1) source token on 138, (2) bridge/protocol, (3) destination chain and token.
---
## 1. Chain 138 Token Inventory
| Token | Symbol | Address (138) | Decimals | Bridge Support |
|-------|--------|---------------|----------|----------------|
| Wrapped Ether | WETH9 | `0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2` | 18 | CCIP ✅ |
| Wrapped Ether v10 | WETH10 | `0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9f` | 18 | CCIP ✅ |
| Chainlink | LINK | `0xb7721dD53A8c629d9f1Ba31a5819AFe250002b03` | 18 | CCIP (not relay) |
| Compliant USDT | cUSDT | `0x93E66202A11B1772E55407B32B44e5Cd8eda7f22` | 6 | Bridge Vault, AlltraAdapter |
| Compliant USDC | cUSDC | `0xf22258f57794CC8E06237084b353Ab30fFfa640b` | 6 | Bridge Vault, AlltraAdapter |
| Tether USDT (Chain 138) | — | `0x15DF1D5BFDD8Aa4b380445D4e3E9B38d34283619` | 6 | — |
---
## 2. Bridge Protocols Summary
| Bridge | Tokens Supported | Destination Chains | Status |
|--------|------------------|--------------------|--------|
| **CCIP WETH9** | WETH9 | 1, 10, 56, 137, 42161, 43114, 8453 | ✅ Live |
| **CCIP WETH10** | WETH10 | 1, 10, 56, 137, 42161, 43114, 8453 | ✅ Live |
| **CCIP (config-ready)** | WETH9, WETH10 | 100, 42220, 1111 | ⚠️ Config ready |
| **AlltraAdapter** | WETH9, cUSDT, cUSDC | 651940 | ✅ Live |
| **Bridge Vault** | cUSDT, cUSDC | 1, 56, 137 | ✅ Deployed |
| **Trustless (Lockbox138)** | ETH, WETH | 1 | ⏳ Stuck deploy |
| **CCIP Relay (138→1)** | WETH9 only | 1 | ✅ WETH9 only |
---
## 3. Complete Routing Table: 138 → Destination
### 3.1 WETH9 Routes (138 → X)
| Dest Chain | Chain ID | Dest Token | Bridge | Dest Address | Status |
|------------|----------|------------|--------|--------------|--------|
| Ethereum Mainnet | 1 | WETH | CCIP WETH9 | `0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2` | ✅ |
| Ethereum Mainnet | 1 | WETH | Trustless | INBOX_ETH (when deployed) | ⏳ |
| Optimism | 10 | WETH | CCIP WETH9 | `0x4200000000000000000000000000000000000006` | ✅ |
| BSC | 56 | WETH | CCIP WETH9 | `0x2170Ed0880ac9A755fd29B2688956BD959F933F8` | ✅ |
| Polygon | 137 | WETH | CCIP WETH9 | `0x7ceB23fD6bC0adD59E62ac25578270cFf1b9f619` | ✅ |
| Gnosis | 100 | WETH | CCIP WETH9 | `0x6A023CCd1ff6F2045C3309768eAd9E68F978f6e1` | ⚠️ Config ready |
| Avalanche | 43114 | WETH | CCIP WETH9 | `0x49D5c2BdFfac6CE2BFdB6640F4F80f226bc10bAB` | ✅ |
| Base | 8453 | WETH | CCIP WETH9 | `0x4200000000000000000000000000000000000006` | ✅ |
| Arbitrum | 42161 | WETH | CCIP WETH9 | `0x82aF49447D8a07e3bd95BD0d56f35241523fBab1` | ✅ |
| ALL Mainnet | 651940 | WETH | AlltraAdapter | `0x798F6762BB40d6801A593459d08F890603D3979C` | ✅ |
| Cronos | 25 | WETH | CCIP WETH9 | `0xe44Fd7fCb2b1581822D0c862B68222998a0c299a` | ✅ |
| Celo | 42220 | WETH | CCIP WETH9 | `0xD221812de1BD094f35587EE8E174B07B6167D9Af` | ⚠️ Config ready |
| Wemix | 1111 | WETH | CCIP WETH9 | `0x5adcb99e7ccd357aceaade7abc5dfbd6f2fce1ae` | ⚠️ Config ready |
**Chain 138 WETH9 Bridge:** `0x971cD9D156f193df8051E48043C476e53ECd4693`
---
### 3.2 WETH10 Routes (138 → X)
| Dest Chain | Chain ID | Dest Token | Bridge | Dest Address | Status |
|------------|----------|------------|--------|--------------|--------|
| Ethereum Mainnet | 1 | WETH | CCIP WETH10 | `0xb7721dD53A8c629d9f1Ba31a5819AFe250002b03` | ✅ |
| Optimism | 10 | WETH | CCIP WETH10 | `0x4200000000000000000000000000000000000006` | ✅ |
| BSC | 56 | WETH | CCIP WETH10 | `0x2170Ed0880ac9A755fd29B2688956BD959F933F8` | ✅ |
| Polygon | 137 | WETH | CCIP WETH10 | `0x7ceB23fD6bC0adD59E62ac25578270cFf1b9f619` | ✅ |
| Gnosis | 100 | WETH | CCIP WETH10 | `0x6A023CCd1ff6F2045C3309768eAd9E68F978f6e1` | ⚠️ Config ready |
| Avalanche | 43114 | WETH | CCIP WETH10 | `0x49D5c2BdFfac6CE2BFdB6640F4F80f226bc10bAB` | ✅ |
| Base | 8453 | WETH | CCIP WETH10 | `0x4200000000000000000000000000000000000006` | ✅ |
| Arbitrum | 42161 | WETH | CCIP WETH10 | `0x82aF49447D8a07e3bd95BD0d56f35241523fBab1` | ✅ |
| Cronos | 25 | WETH | CCIP WETH10 | `0xe44Fd7fCb2b1581822D0c862B68222998a0c299a` | ✅ |
| Celo | 42220 | WETH | CCIP WETH10 | `0xD221812de1BD094f35587EE8E174B07B6167D9Af` | ⚠️ Config ready |
| Wemix | 1111 | WETH | CCIP WETH10 | `0x5adcb99e7ccd357aceaade7abc5dfbd6f2fce1ae` | ⚠️ Config ready |
**Chain 138 WETH10 Bridge:** `0xe0E93247376aa097dB308B92e6Ba36bA015535D0`
---
### 3.3 cUSDT Routes (138 → X)
| Dest Chain | Chain ID | Dest Token | Bridge | Dest Address | Status |
|------------|----------|------------|--------|--------------|--------|
| Ethereum Mainnet | 1 | USDT | Bridge Vault | `0xdAC17F958D2ee523a2206206994597C13D831ec7` | ✅ |
| BSC | 56 | USDT | Bridge Vault | `0x55d398326f99059fF775485246999027B3197955` | ✅ |
| Polygon | 137 | USDT | Bridge Vault | `0xc2132D05D31c914a87C6611C10748AEb04B58e8F` | ✅ |
| ALL Mainnet | 651940 | AUSDT | AlltraAdapter | `0x015B1897Ed5279930bC2Be46F661894d219292A6` | ✅ |
| BSC | 56 | USDT | CCIP (if configured) | `0x55d398326f99059fF775485246999027B3197955` | ⚠️ Via token mapping |
| Polygon | 137 | USDT | CCIP (if configured) | `0xc2132D05D31c914a87C6611C10748AEb04B58e8F` | ⚠️ Via token mapping |
| Gnosis | 100 | USDT | CCIP (config ready) | `0x4ECaBa5870353805a9F068101A40E0f32ed605C6` | ⚠️ Config ready |
| Avalanche | 43114 | USDT | CCIP (if configured) | `0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7` | ⚠️ Via token mapping |
| Base | 8453 | USDT | CCIP (if configured) | `0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2` | ⚠️ Via token mapping |
| Arbitrum | 42161 | USDT | CCIP (if configured) | `0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9` | ⚠️ Via token mapping |
| Optimism | 10 | USDT | CCIP (if configured) | `0x94b008aA00579c1307B0EF2c499aD98a8ce58e58` | ⚠️ Via token mapping |
| Cronos | 25 | USDT | CCIP | `0x66e4286603D22FF153A6547700f37C7Eae42F8E2` | ✅ |
| Celo | 42220 | USDT | CCIP (config ready) | `0x48065fbBE25f71C9282ddf5e1cD6D6A887483D5e` | ⚠️ Config ready |
| Wemix | 1111 | USDT | CCIP (config ready) | `0xA649325Aa7C5093d12D6F98EB4378deAe68CE23F` | ⚠️ Config ready |
---
### 3.4 cUSDC Routes (138 → X)
| Dest Chain | Chain ID | Dest Token | Bridge | Dest Address | Status |
|------------|----------|------------|--------|--------------|--------|
| Ethereum Mainnet | 1 | USDC | Bridge Vault | `0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48` | ✅ |
| BSC | 56 | USDC | Bridge Vault | `0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d` | ✅ |
| Polygon | 137 | USDC | Bridge Vault | `0x3c499c542cEF5E3811e1192ce70d8cC03d5c1369` | ✅ |
| ALL Mainnet | 651940 | AUSDC | AlltraAdapter | `0xa95EeD79f84E6A0151eaEb9d441F9Ffd50e8e881` | ✅ |
| BSC | 56 | USDC | CCIP (if configured) | `0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d` | ⚠️ Via token mapping |
| Polygon | 137 | USDC | CCIP (if configured) | `0x3c499c542cEF5E3811e1192ce70d8cC03d5c1369` | ⚠️ Via token mapping |
| Gnosis | 100 | USDC | CCIP (config ready) | `0xDDAfbb505ad214D7b80b1f830fcCc89B60fb7A83` | ⚠️ Config ready |
| Avalanche | 43114 | USDC | CCIP (if configured) | `0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E` | ⚠️ Via token mapping |
| Base | 8453 | USDC | CCIP (if configured) | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` | ⚠️ Via token mapping |
| Arbitrum | 42161 | USDC | CCIP (if configured) | `0xaf88d065e77c8cC2239327C5EDb3A432268e5831` | ⚠️ Via token mapping |
| Optimism | 10 | USDC | CCIP (if configured) | `0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85` | ⚠️ Via token mapping |
| Cronos | 25 | USDC | CCIP | `0xc21223249CA28397B4B6541dfFaEcC539BfF0c59` | ✅ |
| Celo | 42220 | USDC | CCIP (config ready) | `0xcebA9300f2b948710d2653dD7B07f33A8B32118C` | ⚠️ Config ready |
| Wemix | 1111 | USDC | CCIP (config ready) | `0xE3F5a90F9cb311505cd691a46596599aA1A0AD7D` | ⚠️ Config ready |
---
### 3.5 LINK Routes (138 → X)
| Dest Chain | Chain ID | Dest Token | Bridge | Notes |
|------------|----------|------------|--------|-------|
| Ethereum Mainnet | 1 | LINK | CCIP | ⚠️ Relay bridge is WETH9-only; LINK not relay-supported |
| Other CCIP chains | — | LINK | CCIP | ⚠️ Check CCIP supported tokens per chain |
---
### 3.6 Tether (Chain 138) — No Bridge
| Token | Address | Status |
|-------|---------|--------|
| Tether USDT (Chain 138) | `0x15DF1D5BFDD8Aa4b380445D4e3E9B38d34283619` | ❌ No bridge mapping |
---
## 4. Multi-Hop Routes (138 → X → Y)
### 4.1 138 → 651940 → Other Chains
For tokens that bridge to ALL Mainnet first, then to L2s:
| 138 Token | First Hop | 651940 Token | Second Hop | Dest Chains |
|-----------|-----------|--------------|------------|-------------|
| WETH9 | AlltraAdapter | WETH | CCIP/Alltra | 1, 56, 137, 100, 43114, 8453, 42161, 10, 25, 42220, 1111 |
| cUSDT | AlltraAdapter | AUSDT | CCIP/Alltra | 1, 56, 137, 100, 43114, 8453, 42161, 10, 25, 42220, 1111 |
| cUSDC | AlltraAdapter | AUSDC | CCIP/Alltra | 1, 56, 137, 100, 43114, 8453, 42161, 10, 25, 42220, 1111 |
---
### 4.2 138 → Ethereum Mainnet → Tezos (USDtz)
| Step | Action | Protocol |
|------|--------|----------|
| 1 | Swap on 138 (if needed) | Chain 138 DEX (DODO PMM planned) |
| 2 | Bridge cUSDC → Mainnet USDC | CCIP or Bridge Vault |
| 3 | Bridge Mainnet USDC → Tezos | ETH→Tezos bridge (Wrap Protocol, etc.) |
| 4 | Swap USDC → USDtz on Tezos | Tezos DEX |
**API:** `POST /v1/routes/chain138-to-usdtz` (multi-chain-execution)
---
## 5. On-Chain Swap Options (Chain 138)
| Pool / DEX | Pair | Status |
|------------|------|--------|
| DODO PMM | cUSDT / cUSDC | ❌ Not deployed |
| DODO PMM | cUSDT / USDT | ❌ Not deployed |
| DODO PMM | cUSDC / USDC | ❌ Not deployed |
| Reserve System | — | ✅ Deployed (ReserveSystem, ReserveTokenIntegration) |
| Trustless LiquidityPoolETH | ETH / WETH | ❌ Placeholder |
---
## 6. API & Config References
| Resource | Purpose |
|----------|---------|
| `GET /api/v1/bridge/routes` | Bridge routes (weth9, weth10, trustless) |
| `GET /api/v1/token-mapping/pairs` | All chain pairs |
| `GET /api/v1/token-mapping/resolve?fromChain=&toChain=&address=` | Resolve token address |
| `config/token-mapping.json` | 138 ↔ 1 mapping |
| `config/token-mapping-multichain.json` | 138↔651940, 651940↔all |
---
## 7. Quick Reference Matrix
| From (138) | To | Bridge | Direct? |
|------------|-----|--------|---------|
| WETH9 | 1, 10, 56, 137, 42161, 43114, 8453 | CCIP WETH9 | ✅ |
| WETH10 | 1, 10, 56, 137, 42161, 43114, 8453 | CCIP WETH10 | ✅ |
| WETH9 | 651940 | AlltraAdapter | ✅ |
| cUSDT | 1, 56, 137 | Bridge Vault | ✅ |
| cUSDT | 651940 | AlltraAdapter | ✅ |
| cUSDC | 1, 56, 137 | Bridge Vault | ✅ |
| cUSDC | 651940 | AlltraAdapter | ✅ |
| cUSDT/cUSDC | 25, 100, 42220, 1111 | CCIP (token mapping) | ⚠️ Config |
| Any 138 token | Tezos USDtz | 138→1→Tezos (multi-hop) | ✅ |
---
## References
- [CHAINS_AND_PROTOCOLS_BRIDGE_INTEGRATION.md](../11-references/CHAINS_AND_PROTOCOLS_BRIDGE_INTEGRATION.md)
- [MAPPER_COVERAGE_BRIDGES_AND_LIQUIDITY_POOLS.md](MAPPER_COVERAGE_BRIDGES_AND_LIQUIDITY_POOLS.md)
- [TOKEN_MAPPING_AND_MAINNET_ADDRESSES.md](TOKEN_MAPPING_AND_MAINNET_ADDRESSES.md)
- [LIQUIDITY_POOLS_MASTER_MAP.md](../11-references/LIQUIDITY_POOLS_MASTER_MAP.md)
- `config/token-mapping.json`
- `config/token-mapping-multichain.json`

89
docs/07-ccip/CONFIG_READY_CHAINS_COMPLETION_RUNBOOK.md
View File

@@ -1,6 +1,6 @@
# Config-Ready Chains Completion Runbook (Gnosis, Celo, Wemix)
# Config-Ready Chains Completion Runbook (Gnosis, Cronos, Celo, Wemix)
**Last Updated:** 2026-02-12
**Last Updated:** 2026-02-28
**Status:** Active
**Purpose:** Complete CCIP bridge setup for chains that are "Config ready" so they become fully operational (✅).
@@ -10,19 +10,33 @@
The following chains have **selectors and frontend config ready** but require deployment and configuration to enable bridging from ChainID 138:
| Chain | Chain ID | Selector (decimal) | Status |
|-------------|----------|------------------------|------------|
| Gnosis Chain| 100 | 465200170687744372 | Config ready |
| Celo | 42220 | 1346049177634351622 | Config ready |
| Wemix | 1111 | 5142893604156789321 | Config ready |
| Chain | Chain ID | Selector (decimal) | Gas Token | Status |
|-------------|----------|------------------------|-----------|-------------|
| Gnosis Chain| 100 | 465200170687744372 | xDAI (0.1) | Config ready |
| Cronos | 25 | 1456215246176062136 | CRO (1) | Config ready |
| Celo | 42220 | 1346049177634351622 | CELO (0.1)| Config ready |
| Wemix | 1111 | 5142893604156789321 | WEMIX (0.4)| Config ready |
**Prerequisite:** Confirm [Chainlink CCIP supports](https://docs.chain.link/ccip/supported-networks) each chain (Gnosis, Celo, Wemix). If a chain is not in the CCIP directory, deployment will fail; complete only the chains that are supported.
**Prerequisite:** Confirm [Chainlink CCIP supports](https://docs.chain.link/ccip/supported-networks) each chain. All four are supported.
---
## Preflight (RPC + Gas Balance)
Before deploying, ensure RPC URLs are set and deployer has native gas on each chain:
```bash
cd smom-dbis-138
./scripts/deployment/preflight-config-ready-chains.sh [gnosis|cronos|celo|wemix|all]
```
Fixes any RPC or balance issues before proceeding.
---
## Completion Steps (per chain)
For each of Gnosis, Celo, and Wemix:
For each of Gnosis, Cronos, Celo, and Wemix:
1. **Deploy** CCIPWETH9Bridge and CCIPWETH10Bridge on that chain.
2. **Configure Chain 138 → destination:** On Chain 138's WETH9/WETH10 bridges, call `addDestination(selector, receiverBridge)`.
@@ -31,14 +45,28 @@ For each of Gnosis, Celo, and Wemix:
---
## Step 1: Deploy bridges on Gnosis, Celo, Wemix
## Step 1: Deploy bridges on Gnosis, Cronos, Celo, Wemix
**Operator one-time setup:** Copy the non-secret vars from `smom-dbis-138/docs/deployment/ENV_CONFIG_READY_CHAINS.example` into `smom-dbis-138/.env`. Ensure `PRIVATE_KEY` is set and the deployer has **native gas** on each chain (xDAI, CRO, CELO, WEMIX). Then run:
```bash
cd smom-dbis-138
# Test first (no on-chain tx)
DRY_RUN=1 ./scripts/deployment/deploy-bridges-config-ready-chains.sh cronos
SIMULATE=1 ./scripts/deployment/deploy-bridges-config-ready-chains.sh cronos # forge without --broadcast
# Deploy (preflight runs automatically)
./scripts/deployment/deploy-bridges-config-ready-chains.sh gnosis # or cronos | celo | wemix | all
```
Record the logged bridge addresses and set `CCIPWETH9_BRIDGE_GNOSIS`, `CCIPWETH10_BRIDGE_GNOSIS` (and CELO/WEMIX) in `.env`. Then run `./scripts/deployment/complete-config-ready-chains.sh` to add destinations.
For each chain you need:
- RPC URL
- CCIP Router address (from [CCIP directory](https://docs.chain.link/ccip/supported-networks))
- LINK token address (chain-specific)
- WETH9 and WETH10 addresses (chain-specific or deploy)
- WETH9 and WETH10 addresses (chain-specific; example has WXDAI, WCELO, WWEMIX)
- Deployer private key with native gas token (xDAI for Gnosis, CELO for Celo, WEMIX for Wemix)
### Deploy command (per chain)
@@ -60,17 +88,17 @@ forge script script/deploy/bridge/DeployWETHBridges.s.sol:DeployWETHBridges \
-vvvv
```
Repeat for Celo and Wemix with their RPCs, routers, and LINK/WETH addresses. Record the deployed bridge addresses for Step 2 and Step 3.
Repeat for Cronos, Celo, and Wemix with their RPCs, routers, and LINK/WETH addresses. Record the deployed bridge addresses for Step 2 and Step 3.
### Environment variables (reference)
| Variable | Gnosis | Celo | Wemix |
|----------|--------|------|-------|
| RPC_URL | https://rpc.gnosischain.com | https://forno.celo.org | https://api.wemix.com |
| Chain ID | 100 | 42220 | 1111 |
| CCIP Router | See CCIP directory | See CCIP directory | See CCIP directory |
| LINK token | See CCIP directory | See CCIP directory | See CCIP directory |
| Gas token | xDAI | CELO | WEMIX |
| Variable | Gnosis | Cronos | Celo | Wemix |
|----------|--------|--------|------|-------|
| RPC_URL | https://rpc.gnosischain.com | https://evm.cronos.org | https://forno.celo.org | https://api.wemix.com |
| Chain ID | 100 | 25 | 42220 | 1111 |
| CCIP Router | See CCIP directory | 0xE26B0A098D861d5C7d9434aD471c0572Ca6EAa67 | See CCIP directory | See CCIP directory |
| LINK token | See CCIP directory | 0x8c80A01F461f297Df7F9DA3A4f740D7297C8Ac85 | See CCIP directory | See CCIP directory |
| Gas token | xDAI (0.1) | CRO (1) | CELO (0.1) | WEMIX (0.4) |
---
@@ -122,7 +150,22 @@ Repeat for WETH10 on Gnosis, and for both bridges on Celo and Wemix.
## Step 4: Fund bridges with LINK
Each bridge on Gnosis, Celo, and Wemix must hold LINK to pay CCIP fees. Recommended: **10 LINK per bridge** for initial operations.
Each bridge on Gnosis, Cronos, Celo, and Wemix must hold LINK to pay CCIP fees. Recommended: **10 LINK per bridge** for initial operations (20 LINK per chain for WETH9 + WETH10).
**Prerequisite:** The deployer must have LINK on each chain. Check balances first:
```bash
cd smom-dbis-138
./scripts/deployment/check-link-balance-config-ready-chains.sh all
```
If balances are insufficient, acquire LINK on each chain (bridge from mainnet or DEX), then run:
```bash
./scripts/deployment/fund-ccip-bridges-with-link.sh
```
Or fund manually per chain:
```bash
# Example: Fund Gnosis WETH9 bridge (amount in 18 decimals, 10 LINK)
@@ -131,7 +174,7 @@ cast send "$LINK_TOKEN_GNOSIS" "transfer(address,uint256)" \
--rpc-url "$GNOSIS_RPC" --private-key "$PRIVATE_KEY"
```
Repeat for WETH10 on each chain, and for Celo and Wemix using their LINK and RPC.
Repeat for WETH10 on each chain, and for Cronos, Celo, and Wemix using their LINK and RPC.
---
@@ -139,7 +182,9 @@ Repeat for WETH10 on each chain, and for Celo and Wemix using their LINK and RPC
Use the completion script to add destinations and print exact commands for deployment and funding when addresses are missing.
**Location:** `smom-dbis-138/scripts/deployment/complete-config-ready-chains.sh`
**Deploy bridges first:** `smom-dbis-138/scripts/deployment/deploy-bridges-config-ready-chains.sh [gnosis|celo|wemix|all]` — requires per-chain RPC, CCIP_ROUTER_*, LINK_TOKEN_*, WETH9_*, WETH10_* in .env (see `smom-dbis-138/docs/deployment/ENV_CONFIG_READY_CHAINS.example`).
**Then configure destinations:** `smom-dbis-138/scripts/deployment/complete-config-ready-chains.sh`
**Usage:**

65
docs/07-ccip/CW_BRIDGE_APPROACH.md Normal file
View File

@@ -0,0 +1,65 @@
# cW* Bridge Approach (Chosen Strategy)
**Created:** 2026-02-27
**Status:** Decided — Option 2 (dedicated cW* receiver)
**Related:** [CW_BRIDGE_TASK_LIST.md](../00-meta/CW_BRIDGE_TASK_LIST.md)
---
## 1. Decision (A1)
**Chosen: Option 2 — Deploy dedicated cW* receiver per chain.**
- **Option 1 (extend existing bridge):** Would require changing CCIPWETH9Bridge / CCIPRelayBridge to accept more than WETH9 and mint cW* in `ccipReceive`. That mixes WETH and cW* in one contract and complicates upgrades.
- **Option 2 (dedicated receiver):** Use a contract that only handles cW* mint-on-receive and burn-on-send (e.g. **TwoWayTokenBridgeL2** or a minimal **CCIPReceiverCW**). Keeps WETH bridges unchanged; cW* flow is separate and easier to reason about.
**Concrete choice:** Use **TwoWayTokenBridgeL2** (or equivalent) per (chain, token) — one deployment per chain for cWUSDT and one for cWUSDC, or a generic receiver that supports multiple cW* via message data. **CompliantWrappedToken** is extended with **burnFrom** so TwoWayTokenBridgeL2’s outbound `burnFrom` works (Phase C1).
---
## 2. Flow 138 → chain (lock c* on 138, mint cW* on destination)
1. **User on Chain 138** locks cUSDT (or cUSDC) in a sender contract (e.g. UniversalCCIPBridge, or a dedicated c*→cW* bridge on 138).
2. **Sender** sends a CCIP message to the **destination chain** with:
- **Receiver:** Dedicated cW* receiver (e.g. TwoWayTokenBridgeL2 instance for cWUSDT on that chain).
- **Data:** `abi.encode(recipient, amount)` (same as TwoWayTokenBridgeL2).
- **Token amounts:** Either none (lock-and-mint: 138 locks c*, destination mints cW*) or source token as specified by the bridge design.
3. **On destination chain,** the **cW* receiver**’s `ccipReceive` is called by the CCIP router. It decodes `(recipient, amount)` and calls **cWUSDT.mint(recipient, amount)** (receiver must have MINTER_ROLE on the cW* token).
4. **User on destination** receives cWUSDT.
**Contracts implementing receive:** Dedicated cW* receiver (e.g. TwoWayTokenBridgeL2 with `mirroredToken` = cWUSDT or cWUSDC). Not CCIPWETH9Bridge / CCIPRelayBridge (they remain WETH-only).
**Contracts implementing send (138 side):** UniversalCCIPBridge (if extended for c* and destination = cW* receiver), or a dedicated “Lock c* and send CCIP” contract that configures receiver = TwoWayTokenBridgeL2 on the target chain.
---
## 3. Flow chain → 138 (burn cW* on chain, release c* on 138)
1. **User on destination chain** calls the **cW* receiver**’s outbound function (e.g. TwoWayTokenBridgeL2.**burnAndSend**(destSelector, recipient, amount)).
2. **Receiver** burns cW* from the user (`cWUSDT.burnFrom(user, amount)` — requires CompliantWrappedToken to implement **burnFrom**; see Phase C1) and sends a CCIP message to **Chain 138** with receiver = L1 bridge and data `(recipient, amount)`.
3. **On Chain 138,** the L1 bridge (or release contract) receives the message and releases cUSDT to the recipient (e.g. transfer from escrow or mint if L1 is mintable).
**Contracts implementing burn-and-send:** Same dedicated cW* receiver (TwoWayTokenBridgeL2) that has BURNER_ROLE on the cW* token and implements **burnAndSend**. CompliantWrappedToken must expose **burnFrom** for TwoWayTokenBridgeL2.
**Contracts implementing receive on 138:** L1 bridge or release contract that holds or mints c* and credits the recipient.
---
## 4. Contract summary
| Role | Contract(s) |
|------|-------------|
| **cW* token (destination chain)** | CompliantWrappedToken (cWUSDT, cWUSDC). MINTER_ROLE and BURNER_ROLE granted to the dedicated receiver (e.g. TwoWayTokenBridgeL2). |
| **Receive on destination (mint cW*)** | TwoWayTokenBridgeL2 (or CCIPReceiverCW). Constructor(router, cWUSDT, feeToken). Implements ccipReceive → mint(recipient, amount). |
| **Send from destination (burn cW*, send CCIP)** | Same TwoWayTokenBridgeL2. burnAndSend → burnFrom(user) → ccipSend to 138. |
| **Send from 138 (lock c*, send CCIP)** | UniversalCCIPBridge (with c* and cW* receiver config) or dedicated lock-and-send contract. Receiver address = TwoWayTokenBridgeL2 on destination. |
| **Receive on 138 (release c*)** | L1 bridge or release contract (existing or new) that credits recipient when message received from destination chain. |
---
## 5. References
- [TwoWayTokenBridgeL2.sol](../../smom-dbis-138/contracts/bridge/TwoWayTokenBridgeL2.sol) — Mint on receive, burnAndSend for outbound.
- [CompliantWrappedToken.sol](../../smom-dbis-138/contracts/tokens/CompliantWrappedToken.sol) — mint, burn, burnFrom (Phase C1).
- [CW_BRIDGE_TASK_LIST.md](../00-meta/CW_BRIDGE_TASK_LIST.md) — Full task list and phases.
- [CW_DEPLOY_AND_WIRE_RUNBOOK.md](CW_DEPLOY_AND_WIRE_RUNBOOK.md) — Operator steps to deploy cW*, wire config, verify.

215
docs/07-ccip/CW_DEPLOY_AND_WIRE_RUNBOOK.md Normal file
View File

@@ -0,0 +1,215 @@
# Runbook: Deploy cW* and Wire Config
**Created:** 2026-02-27
**Purpose:** Steps to deploy cWUSDT/cWUSDC on a chain, set `CW_BRIDGE_<CHAIN>`, update token-mapping, and verify roles. Covers Phase D and E from [CW_BRIDGE_TASK_LIST.md](../00-meta/CW_BRIDGE_TASK_LIST.md).
---
## Prerequisites
- `smom-dbis-138/.env` has `CW_BRIDGE_<CHAIN>` set (already done from deployed bridge suite for Mainnet, Cronos, BSC, Polygon, Gnosis, Avalanche, Base, Arbitrum, Optimism).
- For **cross-chain mint** to work, the bridge at that address must either be extended to mint cW* in `ccipReceive` or you must deploy a dedicated cW* receiver (e.g. TwoWayTokenBridgeL2) and point `CW_BRIDGE_<CHAIN>` to it; see [CW_BRIDGE_APPROACH.md](CW_BRIDGE_APPROACH.md).
- RPC URL and `PRIVATE_KEY` for the target chain(s).
---
## Phase D: Deploy cW* and wire config
**One-command helper (from repo root):**
`./scripts/deployment/run-cw-remaining-steps.sh` runs a dry-run and `--update-mapping` by default. Use `--deploy` to broadcast, then set CWUSDT_*/CWUSDC_* in .env from output and run again with `--update-mapping` (or run `--update-mapping` after editing .env). Use `--verify` to check MINTER/BURNER roles per chain.
### D1. Run cW* deploy
**All supported chains:**
```bash
cd smom-dbis-138
./scripts/deployment/deploy-tokens-and-weth-all-chains-skip-canonical.sh --deploy-cw
```
Or from repo root (runs same deploy, then can run update-mapping/verify):
```bash
./scripts/deployment/run-cw-remaining-steps.sh --deploy
```
**Single chain (e.g. BSC 56):**
```bash
cd smom-dbis-138
source .env
# Use the per-chain bridge; script will pick CW_BRIDGE_BSC when running for chain 56
CW_BRIDGE_ADDRESS="$CW_BRIDGE_BSC" forge script script/deploy/DeployCWTokens.s.sol:DeployCWTokens \
--rpc-url "$BSC_RPC_URL" --chain-id 56 --broadcast --private-key "$PRIVATE_KEY" --legacy
```
Or with the wrapper (target one chain only if the script supports `--chain 56`):
```bash
./scripts/deployment/deploy-tokens-and-weth-all-chains-skip-canonical.sh --deploy-cw --chain 56
```
Record the printed addresses for **cWUSDT** and **cWUSDC** per chain.
### D2. Set CWUSDT_<CHAIN> and CWUSDC_<CHAIN> in .env
Append or update in `smom-dbis-138/.env` (replace with actual addresses from D1 output):
```bash
# Example for BSC (56)
CWUSDT_BSC=0x...
CWUSDC_BSC=0x...
# Example for Polygon (137)
CWUSDT_POLYGON=0x...
CWUSDC_POLYGON=0x...
```
Use the chain suffix that matches the deploy script: MAINNET, CRONOS, BSC, POLYGON, GNOSIS, AVALANCHE, BASE, ARBITRUM, OPTIMISM.
### D3. Update token-mapping-multichain.json
**Automated:** After setting `CWUSDT_<CHAIN>` and `CWUSDC_<CHAIN>` in `smom-dbis-138/.env`, run from repo root:
```bash
./scripts/deployment/run-cw-remaining-steps.sh --update-mapping
```
This updates `config/token-mapping-multichain.json` for all chains that have `CWUSDT_*`/`CWUSDC_*` in .env (138→chain pairs; Compliant_USDT_cW, Compliant_USDC_cW, and Compliant_EURC_cW if `CWEURC_*` is set).
**Manual:** For each chain where cW* was deployed, set `addressTo` for the `_cW` entries (replace the `0x0` placeholder) in `config/token-mapping-multichain.json`: Compliant_USDT_cW → CWUSDT_<CHAIN>, Compliant_USDC_cW → CWUSDC_<CHAIN>, Compliant_EURC_cW if cWEURC deployed.
### D4. Verify on-chain
Confirm the bridge/receiver has MINTER_ROLE and BURNER_ROLE on the cW* token:
```bash
# MINTER_ROLE = keccak256("MINTER_ROLE")
cast keccak "MINTER_ROLE"
# Example: 0x...
# Check cWUSDT on BSC (replace addresses and rpc)
cast call <CWUSDT_BSC> "hasRole(bytes32,address)(bool)" $(cast keccak "MINTER_ROLE") $CW_BRIDGE_BSC --rpc-url $BSC_RPC_URL
cast call <CWUSDT_BSC> "hasRole(bytes32,address)(bool)" $(cast keccak "BURNER_ROLE") $CW_BRIDGE_BSC --rpc-url $BSC_RPC_URL
```
Both should return `true`.
---
## Phase E: Relay and send path (138 → other chains)
### E1. Relay service (138 → Mainnet)
If using the existing CCIPRelayBridge for cW* on Mainnet, that contract is WETH-only and must be **extended** (or a separate cW* receiver deployed and relay logic updated) so that when the relay sends a cUSDT/cUSDC message, the Mainnet receiver mints cWUSDT/cWUSDC. See [RELAY_BRIDGE_ADD_LINK_SUPPORT_RUNBOOK.md](RELAY_BRIDGE_ADD_LINK_SUPPORT_RUNBOOK.md) for the pattern (token whitelist + transfer or mint in `ccipReceive`). Then:
- Configure relay to send c* messages to the cW* receiver on Mainnet.
- Ensure the receiver has MINTER_ROLE on cWUSDT/cWUSDC and holds or mints as designed.
### E2. Direct CCIP (138 → chain)
If Chain 138 uses UniversalCCIPBridge or a dedicated sender to send c* to a destination chain:
- Add destination config for the c* token with **receiver** = the cW* receiver on the destination (e.g. TwoWayTokenBridgeL2 address).
- Ensure the receiver on the destination has MINTER_ROLE on the cW* token and implements `ccipReceive` → `cW*.mint(recipient, amount)` (see [CW_BRIDGE_APPROACH.md](CW_BRIDGE_APPROACH.md)).
### E3. Test E2E
1. On Chain 138: Lock or transfer cUSDT to the sender/bridge and trigger a send to the target chain (recipient = test address).
2. Wait for CCIP execution on the destination chain.
3. On the destination chain: Verify the recipient’s cWUSDT balance increased (e.g. `cast call <CWUSDT_<CHAIN>> "balanceOf(address)(uint256)" <recipient> --rpc-url <RPC>`).
---
## New chain checklist (summary)
| Step | Action |
|------|--------|
| 1 | Set `CW_BRIDGE_<CHAIN>` in .env (or use existing from bridge suite). |
| 2 | Run DeployCWTokens for that chain (D1). |
| 3 | Set `CWUSDT_<CHAIN>`, `CWUSDC_<CHAIN>` in .env (D2). |
| 4 | Update `config/token-mapping-multichain.json` `addressTo` for _cW entries (D3). |
| 5 | Verify MINTER_ROLE and BURNER_ROLE on cW* for the bridge (D4). |
| 6 | If cross-chain mint is required, ensure the bridge/receiver code mints cW* in ccipReceive (Phase B or C); then wire relay/direct CCIP (E1, E2) and run E2E test (E3). |
---
## Retry failed cW* deploys (Mainnet, Cronos, Arbitrum)
If the 10 remaining cW* (cWEURC..cWXAUT) failed on **Mainnet** (nonce), **Cronos** (RPC timeout), or **Arbitrum** (gas), use the steps below.
### Mainnet (1) — fix nonce
Deployer nonce on Mainnet must match the RPC (error: `nonce=256 maxNonce=253` means 3 pending txs are ahead of what the RPC has confirmed).
1. **Check nonce and balance:**
`./scripts/deployment/check-deployer-nonce-and-balance.sh`
2. **Options:**
- **Wait** for pending transactions to confirm, then re-run the deploy.
- **Replace/cancel** pending txs: send a 0-value transaction from the deployer to itself with the *next expected nonce* (e.g. 253) and higher gas so it replaces the stuck one; repeat until the queue is cleared.
- Use the same wallet in another tool (e.g. MetaMask) and ensure no other process is sending from this account.
3. **Run deploy** once nonce is aligned:
```bash
cd smom-dbis-138 && source .env
DEPLOY_CWUSDT=0 DEPLOY_CWUSDC=0 CW_BRIDGE_ADDRESS="$CW_BRIDGE_MAINNET" forge script script/deploy/DeployCWTokens.s.sol:DeployCWTokens \
--rpc-url "${ETHEREUM_MAINNET_RPC}" --chain-id 1 --broadcast --private-key "$PRIVATE_KEY" --legacy -vvv
```
Add the printed CWEURC_MAINNET … CWXAUT_MAINNET to `.env`, then run `./scripts/deployment/run-cw-remaining-steps.sh --update-mapping`.
### Cronos (25) — retry when RPC is stable; fix nonce if needed
If you see `invalid nonce; got X, expected Y`, wait for pending txs to confirm or replace/cancel them (same idea as Mainnet). Check: `./scripts/deployment/check-deployer-nonce-and-balance.sh`
```bash
cd smom-dbis-138 && source .env
DEPLOY_CWUSDT=0 DEPLOY_CWUSDC=0 CW_BRIDGE_ADDRESS="$CW_BRIDGE_CRONOS" forge script script/deploy/DeployCWTokens.s.sol:DeployCWTokens \
--rpc-url "${CRONOS_RPC_URL}" --chain-id 25 --broadcast --private-key "$PRIVATE_KEY" --legacy -vvv
```
Then set CWEURC_CRONOS … CWXAUT_CRONOS in `.env` from the script output and run `--update-mapping`.
### Arbitrum (42161) — use current gas; low gas price is enough
[Arbitrum One gas](https://arbiscan.io/gastracker) is often ~0.02 Gwei; the 10-contract deploy then costs &lt;0.001 ETH. If you see "max fee per gas less than block base fee", set `ARBITRUM_GAS_PRICE` slightly above base (e.g. `25000000` = 0.025 gwei). Only use 35 gwei if the network is congested. Run the deploy:
```bash
cd smom-dbis-138 && source .env
# Only if you see "max fee per gas less than block base fee" (check https://arbiscan.io/gastracker)
export ARBITRUM_GAS_PRICE=25000000
./scripts/deployment/deploy-tokens-and-weth-all-chains-skip-canonical.sh --deploy-cw --chain 42161
```
Or single-run without the script (use 25000000 = 0.025 gwei when gas is ~0.02 Gwei):
```bash
DEPLOY_CWUSDT=0 DEPLOY_CWUSDC=0 CW_BRIDGE_ADDRESS="$CW_BRIDGE_ARBITRUM" forge script script/deploy/DeployCWTokens.s.sol:DeployCWTokens \
--rpc-url "${ARBITRUM_MAINNET_RPC}" --chain-id 42161 --broadcast --private-key "$PRIVATE_KEY" --legacy --with-gas-price 25000000 -vvv
```
Then set in `.env` (expected addresses from script when it runs):
- CWEURC_ARBITRUM=0xd6969bC19b53f866C64f2148aE271B2Dae0C58E4
- CWEURT_ARBITRUM=0x3CD9ee18db7ad13616FCC1c83bC6098e03968E66
- CWGBPC_ARBITRUM=0xBeF5A0Bcc0E77740c910f197138cdD90F98d2427
- CWGBPT_ARBITRUM=0x948690147D2e50ffe50C5d38C14125aD6a9FA036
- CWAUDC_ARBITRUM=0x58a8D8F78F1B65c06dAd7542eC46b299629A60dd
- CWJPYC_ARBITRUM=0xFb4B6Cc81211F7d886950158294A44C312abCA29
- CWCHFC_ARBITRUM=0xf9f5D0ACD71C76F9476F10B3F3d3E201F0883C68
- CWCADC_ARBITRUM=0xeE17bB0322383fecCA2784fbE2d4CD7d02b1905B
- CWXAUC_ARBITRUM=0xc9750828124D4c10e7a6f4B655cA8487bD3842EB
- CWXAUT_ARBITRUM=0x328Cd365Bb35524297E68ED28c6fF2C9557d1363
Then run `./scripts/deployment/run-cw-remaining-steps.sh --update-mapping`.
---
## References
- [CW_BRIDGE_TASK_LIST.md](../00-meta/CW_BRIDGE_TASK_LIST.md)
- [CW_BRIDGE_APPROACH.md](CW_BRIDGE_APPROACH.md)
- [CW_TOKENS_AND_NETWORKS.md](../11-references/CW_TOKENS_AND_NETWORKS.md)
- [C_TO_CW_MAPPER_MAPPING.md](../04-configuration/C_TO_CW_MAPPER_MAPPING.md)

121
docs/07-ccip/MAPPER_COVERAGE_BRIDGES_AND_LIQUIDITY_POOLS.md
View File

@@ -1,121 +0,0 @@
# Mapper Coverage — All Networks with Bridges or Liquidity Pools
**Last Updated:** 2026-02-16
**Status:** ✅ Mapper complete for all networks with bridges or liquidity pools
---
## What “Mapper” Means
## Summary
**Mapper is complete for all:** Every network with our bridges or LPs (138, 1, 651940, 56, 137, 100, 43114, 8453, 42161, 10, 25, 42220, 1111) has master config `mapper` and token mapping (138↔1, 138↔651940, 651940↔all). Use `getMapperAddress(chainId)` and `getTokenMappingForPair()` / `getMappedAddress()`. Wemix (1111) addresses are set in config (user-provided from [scan.wemix.com/tokens](https://scan.wemix.com/tokens)); re-verify there and update JSON if different official addresses found.
---
## What "Mapper" Means
1. **On-chain AddressMapper**
Contract that maps genesis/canonical addresses to deployed addresses on that chain (e.g. Chain 138 where WETH9/WETH10 are deployed at different addresses than genesis). Used by tooling and contracts that need to resolve “canonical” → “deployed” per chain.
2. **Token/address mapping (config)**
Off-chain mapping (e.g. `config/token-mapping.json`) that defines which token on chain A corresponds to which on chain B. Used by relay, token-aggregation API, and UIs for bridge routes and liquidity.
**Goal:** Every network that has our bridges or liquidity pools should have mapper coverage (on-chain and/or config) so addresses are unambiguous and bridge/LP logic can resolve tokens correctly.
---
## Networks with Bridges or Liquidity Pools
| Network | Chain ID | Bridges / LPs | On-chain AddressMapper | Config token mapping |
|----------------|----------|---------------|------------------------|------------------------|
| **Chain 138** | 138 | CCIP WETH9/10, UniversalCCIPBridge, BridgeOrchestrator, Lockbox138, Bridge Vault, Reserve, DODO PMM (planned) | ✅ `0x439Fcb2d2ab2f890DCcAE50461Fa7d978F9Ffe1A` | ✅ `token-mapping.json` (138↔1); `token-mapping-multichain.json` (138↔651940) |
| **Ethereum Mainnet** | 1 | CCIP Relay Bridge, Trustless, TwoWayTokenBridge | canonical | ✅ 138↔1; 651940↔1 in multichain |
| **ALL Mainnet** | 651940 | AlltraAdapter, DEX/LPs | canonical | ✅ 138↔651940; 651940↔all in multichain |
| **BSC** | 56 | CCIP WETH9/10 (DeployAll) | canonical | ✅ 651940↔56 in multichain |
| **Polygon** | 137 | CCIP WETH9/10 (DeployAll) | canonical | ✅ 651940↔137 in multichain |
| **Gnosis** | 100 | Config ready | canonical | ✅ 651940↔100 in multichain |
| **Avalanche** | 43114 | CCIP WETH9/10 (DeployAll) | canonical | ✅ 651940↔43114 in multichain |
| **Base** | 8453 | CCIP WETH9/10 (DeployAll) | canonical | ✅ 651940↔8453 in multichain |
| **Arbitrum** | 42161 | CCIP WETH9/10 (DeployAll) | canonical | ✅ 651940↔42161 in multichain |
| **Optimism** | 10 | CCIP WETH9/10 (DeployAll) | canonical | ✅ 651940↔10 in multichain |
| **Cronos** | 25 | DeployAll / optional | canonical | ✅ 651940↔25 in multichain |
| **Celo** | 42220 | Config ready | canonical | ✅ 651940↔42220 in multichain |
| **Wemix** | 1111 | Config ready | canonical | ✅ 651940↔1111 in multichain (addresses set; re-verify on [scan.wemix.com/tokens](https://scan.wemix.com/tokens)) |
---
## Per-Network Detail
### Chain 138 (SMOM-DBIS-138)
- **Bridges:** CCIPWETH9_Bridge, CCIPWETH10_Bridge, Universal_CCIP_Bridge, Bridge_Orchestrator, Lockbox138, Bridge_Vault.
- **Liquidity:** Reserve_System, DODO PMM (planned), LiquidityPoolETH (trustless, conceptual).
- **AddressMapper:** Deployed at `0x439Fcb2d2ab2f890DCcAE50461Fa7d978F9Ffe1A`. Maps genesis WETH9/WETH10 to deployed addresses.
- **Config:** `config/smart-contracts-master.json` → `chains.138.contracts.Address_Mapper`; `config/token-mapping.json` (source chain 138).
- **Status:** ✅ Mapper provided (on-chain + config).
### Ethereum Mainnet (1)
- **Bridges:** CCIP_Relay_Bridge, Trustless stack (InboxETH, BondManager, LiquidityPoolETH, etc.), TwoWayTokenBridge (if deployed).
- **Liquidity:** LiquidityPoolETH (trustless).
- **AddressMapper:** Not deployed; WETH9/LINK at canonical addresses. Use canonical addresses directly.
- **Config:** `config/token-mapping.json` (destination chain 1); `config/smart-contracts-master.json` has WETH9, LINK, relay contracts.
- **Status:** ✅ Mapper provided (config + canonical; no on-chain mapper needed).
### ALL Mainnet (651940)
- **Bridges:** AlltraAdapter (138↔651940).
- **Liquidity:** DEX pools (e.g. Uniswap V2/V3, DODO PMM env-based); HYDX, AUSDC, etc.
- **AddressMapper:** Not used; tokens at native addresses. Mapping is off-chain (chains.ts, token lists).
- **Config:** `config/smart-contracts-master.json` → `chains.651940` with `mapper: "canonical"` and key contracts (WETH, AUSDC, AUSDT); token addresses also in docs and `smom-dbis-138` chains config.
- **Status:** ✅ Mapper provided (canonical in master config).
### Other CCIP chains (56, 137, 100, 43114, 8453, 42161, 10, 25, 42220, 1111)
- **Bridges:** CCIP WETH9/WETH10 (deployed or config-ready).
- **AddressMapper:** Not deployed; use canonical addresses. Each chain is in `config/smart-contracts-master.json` with `mapper: "canonical"` so `getMapperAddress(chainId)` returns `"canonical"` for all.
- **Config:** Token mapping 651940↔each chain is in `config/token-mapping-multichain.json`. Use `getTokenMappingForPair(651940, chainId)` or `getMappedAddress(651940, chainId, tokenAddress)`.
- **Status:** ✅ Mapper complete (canonical in master config; token mapping in multichain). Wemix (1111) addresses set in config; re-verify on [scan.wemix.com/tokens](https://scan.wemix.com/tokens) and update JSON if different official addresses found.
---
## Ensuring Mapper Is Provided Everywhere
### Already in place
- **Chain 138:** AddressMapper in `smart-contracts-master.json` and `.env`; token-mapping.json covers 138↔1.
- **Ethereum Mainnet:** Canonical addresses in master config; token-mapping.json for relay and docs.
### Recommended actions
1. **Master config**
- Each chain in `config/smart-contracts-master.json` has a `mapper` field: either an AddressMapper contract address (e.g. Chain 138) or `"canonical"` (Mainnet, ALL Mainnet). Use `getMapperAddress(chainId)` from `config/contracts-loader.cjs` to resolve.
- ALL Mainnet (651940) is in `smart-contracts-master.json` with `mapper: "canonical"` and key contracts.
2. **Other CCIP chains**
- When adding a chain to `smart-contracts-master.json`, set `Address_Mapper` (or `mapper`) if you deploy AddressMapper; otherwise set `mapper: "canonical"`.
- For Cronos/others: deploy AddressMapper via `script/DeployAddressMapper.s.sol` when you want parity with Chain 138 (see `smom-dbis-138/docs/deployment/CRONOS_FULL_DEPLOYMENT_TODO.md`).
3. **Token mapping**
- **138↔Mainnet:** `config/token-mapping.json` (relay and docs).
- **138↔651940 and 651940↔56, 137, 100, 43114, 8453, 42161, 10, 25, 1:** `config/token-mapping-multichain.json`. Use `getTokenMappingForPair(fromChainId, toChainId)` and `getMappedAddress(fromChainId, toChainId, tokenAddress)` from `config/token-mapping-loader.cjs`. See [TOKEN_MAPPING_AND_MAINNET_ADDRESSES.md](TOKEN_MAPPING_AND_MAINNET_ADDRESSES.md).
4. **Tooling**
- Use `config/contracts-loader.cjs` (and any new `getMapperAddress(chainId)`) so services can resolve “mapper” per chain from one place.
---
## References
- **[MAPPER_GAPS_DEPLOYMENTS_AND_IMPROVEMENTS.md](MAPPER_GAPS_DEPLOYMENTS_AND_IMPROVEMENTS.md)** — Gaps, deployments, and improvements (consolidated).
- [TOKEN_MAPPING_AND_MAINNET_ADDRESSES.md](TOKEN_MAPPING_AND_MAINNET_ADDRESSES.md) — 138↔Mainnet token mapping and relay.
- [CCIP_BRIDGE_MAINNET_CONNECTION.md](CCIP_BRIDGE_MAINNET_CONNECTION.md) — Relay and mainnet bridge.
- [LIQUIDITY_POOLS_MASTER_MAP.md](../11-references/LIQUIDITY_POOLS_MASTER_MAP.md) — Pools on 138 and ALL Mainnet.
- [CHAINS_AND_PROTOCOLS_BRIDGE_INTEGRATION.md](../11-references/CHAINS_AND_PROTOCOLS_BRIDGE_INTEGRATION.md) — Chains and bridge status.
- `config/smart-contracts-master.json` — Contract and mapper addresses per chain.
- `config/token-mapping.json` — Token mapping 138↔1 (relay).
- `config/token-mapping-multichain.json` — 138↔651940 and 651940↔1, 56, 137, 100, 43114, 8453, 42161, 10, 25, 42220, 1111.
- `config/token-mapping-loader.cjs` — `getRelayTokenMapping()`, `getTokenMappingForPair()`, `getAllMultichainPairs()`, `getMappedAddress()`.
- [EXPLORER_TOKENS_CANONICAL_MAPPING.md](EXPLORER_TOKENS_CANONICAL_MAPPING.md) — Explorer tokens/contracts list URLs for verifying canonical addresses per chain.
- `smom-dbis-138/docs/ADDRESS_MAPPING.md` — AddressMapper contract and usage.

145
docs/07-ccip/MAPPER_GAPS_DEPLOYMENTS_AND_IMPROVEMENTS.md
View File

@@ -1,145 +0,0 @@
# Mapper & Bridges: Gaps, Deployments, and Improvements
**Last Updated:** 2026-02-16
**Based on:** [MAPPER_COVERAGE_BRIDGES_AND_LIQUIDITY_POOLS.md](MAPPER_COVERAGE_BRIDGES_AND_LIQUIDITY_POOLS.md), bridge config, liquidity pool map, and contract inventory
---
## 1. Gaps
### 1.1 Token mapping / config
| Gap | Detail | Action |
|-----|--------|--------|
| **Wemix (1111) token addresses** | Addresses are set in JSON (user-provided from [scan.wemix.com/tokens](https://scan.wemix.com/tokens)). | Re-verify on [scan.wemix.com/tokens](https://scan.wemix.com/tokens) and with Tether/Circle/Wemix; if different official addresses found, update JSON and [WEMIX_TOKEN_VERIFICATION.md](WEMIX_TOKEN_VERIFICATION.md). |
| **138↔CCIP chains (56, 137, …) direct mapping** | Multichain mapping is 138↔651940 and 651940↔others. No direct 138↔56, 138↔137, etc. token entries. | Optional: add direct 138↔56, 138↔137, … pairs if bridge UIs need them without going via 651940. |
| **LINK on relay** | Mainnet CCIPRelayBridge is WETH9-only; LINK has a mapping in token-mapping.json but `relaySupported: false`. | Follow [RELAY_BRIDGE_ADD_LINK_SUPPORT_RUNBOOK.md](RELAY_BRIDGE_ADD_LINK_SUPPORT_RUNBOOK.md) to enable 138→Mainnet LINK. |
### 1.2 On-chain / contracts
| Gap | Detail | Action |
|-----|--------|--------|
| **AddressMapper on other chains** | Only Chain 138 has a deployed AddressMapper. Mainnet and all others use canonical addresses. | Optional: deploy AddressMapper on Cronos/others (e.g. per [CRONOS_FULL_DEPLOYMENT_TODO.md](../../smom-dbis-138/docs/deployment/CRONOS_FULL_DEPLOYMENT_TODO.md)) if you want genesis→deployed parity everywhere. |
| **Gnosis, Celo, Wemix CCIP bridges** | These are “Config ready” (selectors in place); CCIP WETH9/WETH10 bridges are **not** deployed on 100, 42220, 1111. | Deploy CCIPWETH9Bridge and CCIPWETH10Bridge on each, configure destinations, fund with LINK. Runbook: [CONFIG_READY_CHAINS_COMPLETION_RUNBOOK.md](CONFIG_READY_CHAINS_COMPLETION_RUNBOOK.md). |
| **Trustless bridge (Mainnet)** | LiquidityPoolETH, InboxETH, BondManager, etc. on Mainnet are referenced in docs but full stack deployment status is “optional / not deployed” in runbooks. | See [OPTIONAL_FUTURE_DEPLOYMENTS_RUNBOOK.md](../03-deployment/OPTIONAL_FUTURE_DEPLOYMENTS_RUNBOOK.md), [LIQUIDITY_POOL_CONTROLS_RUNBOOK.md](../03-deployment/LIQUIDITY_POOL_CONTROLS_RUNBOOK.md). |
| **DODO PMM on Chain 138** | DODOPMMIntegration and pools (cUSDT/cUSDC, etc.) are **not deployed**; env placeholders only. | Deploy DODOPMMIntegration and create pools when ready; see [LIQUIDITY_POOLS_MASTER_MAP.md](../11-references/LIQUIDITY_POOLS_MASTER_MAP.md). |
| **XAU / cEURT on 138** | XAU and cEURT tokens are planned, not deployed; blocks XAU-anchored stabilization pools. | Deploy tokens and pools when design is final. |
### 1.3 Documentation / tooling
| Gap | Detail | Action |
|-----|--------|--------|
| **References list in MAPPER_COVERAGE** | Done: 42220 and 1111 are already in the token-mapping-multichain.json reference bullet. | — |
| **Services using multichain loader** | Token-aggregation exposes token-mapping API (uses loader when run from monorepo). | Ensure bridge UIs / Snap use token-mapping API or `getTokenMappingForPair()` / `getMappedAddress()` for 138↔651940 and 651940↔other chains. |
---
## 2. Deployments (what is in place)
### 2.1 Mapper (config + on-chain)
| Item | Status | Where |
|------|--------|--------|
| **AddressMapper (Chain 138)** | Deployed | `0x439Fcb2d2ab2f890DCcAE50461Fa7d978F9Ffe1A`; in `smart-contracts-master.json` and `.env` |
| **Master config `mapper` for all bridge/LP chains** | Done | 138, 1, 651940, 56, 137, 100, 43114, 8453, 42161, 10, 25, 42220, 1111 in `config/smart-contracts-master.json` (138 = address, rest = `"canonical"`) |
| **138↔1 token mapping** | Done | `config/token-mapping.json`; relay uses it |
| **138↔651940 token mapping** | Done | `config/token-mapping-multichain.json` (both directions) |
| **651940↔1, 56, 137, 100, 43114, 8453, 42161, 10, 25, 42220, 1111 token mapping** | Done | Same file; Celo has canonical addresses; Wemix has placeholders |
| **contracts-loader.cjs** | Done | `getMapperAddress(chainId)` |
| **token-mapping-loader.cjs** | Done | `getTokenMappingForPair()`, `getAllMultichainPairs()`, `getMappedAddress()`, `getRelayTokenMapping()` |
| **Config validation** | Done | `scripts/validation/validate-config-files.sh` checks token-mapping.json and token-mapping-multichain.json |
### 2.2 Bridges
| Bridge / lane | Status | Notes |
|---------------|--------|--------|
| **CCIP 138↔1 (WETH9)** | Deployed | CCIPWETH9Bridge on 138; CCIPRelayBridge on Mainnet; relay service running |
| **CCIP 138↔1 (WETH10)** | Deployed | CCIPWETH10Bridge on 138 |
| **CCIP 138 → 56, 137, 43114, 8453, 42161, 10** | Deployed | CCIP WETH9/WETH10 bridges on those chains (DeployAll) |
| **CCIP 138 → 100, 42220, 1111** | Config ready | Selectors configured; bridges **not** deployed yet |
| **AlltraAdapter 138↔651940** | Deployed | On 138; token mapping in multichain |
| **Lockbox138 (trustless 138→1)** | Deployed on 138 | Mainnet trustless stack (InboxETH, LiquidityPoolETH, etc.) optional / runbook |
| **Universal CCIP Bridge (138)** | Deployed | Proxy + orchestrator; lanes to Mainnet and 651940 |
| **Bridge Vault (138)** | Deployed | Multi-chain stablecoin bridge (1, 137, 56 referenced in CHAINS_AND_PROTOCOLS) |
### 2.3 Liquidity / reserves
| Item | Status | Notes |
|------|--------|--------|
| **Reserve system (138)** | Deployed | Reserve_System, Reserve_Token_Integration in master config |
| **Vault factory (138)** | Deployed | Vault_Factory in master config |
| **DODO PMM (138)** | Not deployed | DODOPMMIntegration and pools planned; env placeholders |
| **LiquidityPoolETH (trustless)** | Not deployed | Mainnet; optional per runbooks |
| **ALL Mainnet DEX pools** | Env / external | Uniswap V2/V3, DODO env-based; HYDX, AUSDC, etc. on chain |
### 2.4 Other contracts (138)
| Category | Status | Ref |
|----------|--------|-----|
| Core (Token Registry, Compliance, Fee Collector, Governance, etc.) | Deployed | smart-contracts-master.json, CONTRACT_INVENTORY |
| Channels (Payment, GenericStateChannel) | Deployed | |
| Mirror (MirrorManager, TransactionMirror) | MirrorManager deployed; TransactionMirror deploy when needed | |
| CREATE2 deterministic set | Deployed | Universal_Asset_Registry_Deterministic, Universal_CCIP_Bridge_Deterministic, Mirror_Registry, Alltra_Adapter |
---
## 3. Improvements
### 3.1 Completed (mapper and token mapping)
- **Single mapper story for all bridge/LP chains:** Every such chain (138, 1, 651940, 56, 137, 100, 43114, 8453, 42161, 10, 25, 42220, 1111) has a `mapper` in `config/smart-contracts-master.json` and is resolvable via `getMapperAddress(chainId)`.
- **138↔651940 and 651940↔all:** `config/token-mapping-multichain.json` added with 13 pairs; loader exposes `getTokenMappingForPair()`, `getAllMultichainPairs()`, `getMappedAddress()`.
- **ALL Mainnet in master config:** Chain 651940 added with `mapper: "canonical"` and key contracts (WETH, AUSDC, AUSDT).
- **CCIP chains in master config:** 56, 137, 100, 43114, 8453, 42161, 10, 25, 42220, 1111 added with `mapper: "canonical"` (no contract addresses yet).
- **Celo (42220):** Canonical WETH/USDT/USDC added to multichain mapping.
- **Wemix (1111):** Pair and chain added; token addresses left as placeholders with a note to verify on explorer.
- **Validation:** `validate-config-files.sh` checks `token-mapping-multichain.json` (valid JSON + `.pairs` array).
- **Docs:** MAPPER_COVERAGE updated with summary, full table, and “mapper complete” status; TOKEN_MAPPING_AND_MAINNET_ADDRESSES updated with multichain section and references.
### 3.2 Recommended (next steps) — checklist and code completed where applicable
**Use the consolidated checklist:** [RECOMMENDED_COMPLETION_CHECKLIST.md](RECOMMENDED_COMPLETION_CHECKLIST.md).
**Run completable + see operator steps:** `./scripts/run-remaining-mapper-tasks.sh` (from repo root).
| Priority | Improvement | Status |
|----------|-------------|--------|
| High | Re-verify Wemix (1111) token addresses on [scan.wemix.com/tokens](https://scan.wemix.com/tokens); update JSON and [WEMIX_TOKEN_VERIFICATION.md](WEMIX_TOKEN_VERIFICATION.md) if different official addresses found. | ☐ Operator: steps in [RECOMMENDED_COMPLETION_CHECKLIST.md](RECOMMENDED_COMPLETION_CHECKLIST.md) §1 |
| High | Complete Gnosis, Celo, Wemix: deploy CCIP WETH9/WETH10 bridges, configure destinations, fund with LINK. | ☐ Ops: [CONFIG_READY_CHAINS_COMPLETION_RUNBOOK.md](CONFIG_READY_CHAINS_COMPLETION_RUNBOOK.md); checklist §2 |
| Medium | Wire token-aggregation (and bridge UIs) to multichain mapping. | ☑ **Done:** Token-aggregation exposes `GET /api/v1/token-mapping?fromChain=&toChain=`, `/pairs`, `/resolve` (uses config loader from monorepo). UIs: use API or loader. Checklist §3. |
| Medium | Add LINK support to Mainnet relay bridge so 138→Mainnet LINK is relay-supported. | ☐ [RELAY_BRIDGE_ADD_LINK_SUPPORT_RUNBOOK.md](RELAY_BRIDGE_ADD_LINK_SUPPORT_RUNBOOK.md); checklist §4 |
| Low | Optional: deploy AddressMapper on Cronos (and other chains) for parity with 138. | ☐ Checklist §5; script `script/DeployAddressMapper.s.sol` |
| Low | Optional: add direct 138↔56, 138↔137, … token entries in multichain. | ☑ **Done:** Direct 138↔56, 137, 100, 43114, 8453, 42161, 10, 25 added to `config/token-mapping-multichain.json`. |
| Low | Deploy DODO PMM integration and cUSDT/cUSDC (and related) pools on 138 when ready. | ☐ Checklist §6; LIQUIDITY_POOLS_MASTER_MAP, LIQUIDITY_POOL_CONTROLS_RUNBOOK |
| Low | Deploy Mainnet trustless stack (LiquidityPoolETH, etc.) if trustless 138↔1 is required. | ☐ Checklist §7; OPTIONAL_FUTURE_DEPLOYMENTS_RUNBOOK, LIQUIDITY_POOL_CONTROLS_RUNBOOK |
### 3.3 Doc / hygiene
- Add 42220 and 1111 to the “token-mapping-multichain.json” bullet in MAPPER_COVERAGE References.
- Keep MAPPER_COVERAGE and this doc in sync when new chains or pairs are added.
- When Wemix addresses are filled in, remove the “addresses TBD” note from MAPPER_COVERAGE and this doc.
---
## 4. Quick reference
| Need | Use |
|------|-----|
| Mapper for a chain | `getMapperAddress(chainId)` from `config/contracts-loader.cjs` |
| Token mapping 138↔1 (relay) | `getRelayTokenMapping()` from `config/token-mapping-loader.cjs` |
| Token mapping for any pair | `getTokenMappingForPair(fromChainId, toChainId)` |
| Resolve address on target chain | `getMappedAddress(fromChainId, toChainId, tokenAddress)` |
| List all multichain pairs | `getAllMultichainPairs()` |
| Master contract list | `config/smart-contracts-master.json` → `chains[chainId].contracts` and `.mapper` |
---
## References
- **[RECOMMENDED_COMPLETION_CHECKLIST.md](RECOMMENDED_COMPLETION_CHECKLIST.md)** — Consolidated checklist for all recommended items (Wemix, CCIP config-ready, LINK, AddressMapper, DODO, Trustless).
- [MAPPER_COVERAGE_BRIDGES_AND_LIQUIDITY_POOLS.md](MAPPER_COVERAGE_BRIDGES_AND_LIQUIDITY_POOLS.md)
- [TOKEN_MAPPING_AND_MAINNET_ADDRESSES.md](TOKEN_MAPPING_AND_MAINNET_ADDRESSES.md)
- [CHAINS_AND_PROTOCOLS_BRIDGE_INTEGRATION.md](../11-references/CHAINS_AND_PROTOCOLS_BRIDGE_INTEGRATION.md)
- [LIQUIDITY_POOLS_MASTER_MAP.md](../11-references/LIQUIDITY_POOLS_MASTER_MAP.md)
- [CONFIG_READY_CHAINS_COMPLETION_RUNBOOK.md](CONFIG_READY_CHAINS_COMPLETION_RUNBOOK.md)
- [OPTIONAL_FUTURE_DEPLOYMENTS_RUNBOOK.md](../03-deployment/OPTIONAL_FUTURE_DEPLOYMENTS_RUNBOOK.md)
- [LIQUIDITY_POOL_CONTROLS_RUNBOOK.md](../03-deployment/LIQUIDITY_POOL_CONTROLS_RUNBOOK.md)

60
docs/07-ccip/README.md
View File

@@ -1,60 +0,0 @@
# CCIP & Chainlink
**Last Updated:** 2026-02-12
**Document Version:** 1.2
**Status:** Active Documentation
---
This directory contains CCIP deployment and Chainlink documentation.
## Documents
### Core CCIP
- **[CCIP_DEPLOYMENT_SPEC.md](CCIP_DEPLOYMENT_SPEC.md)** ⭐⭐⭐ - CCIP fleet deployment specification (41-43 nodes)
- **[CCIP_RELAY_DEPLOYMENT.md](CCIP_RELAY_DEPLOYMENT.md)** ⭐⭐⭐ - CCIP Relay Service (Chain 138 → Mainnet); deployed on r630-01; uses VMID 2201 RPC
- **[CCIP_BRIDGE_MAINNET_CONNECTION.md](CCIP_BRIDGE_MAINNET_CONNECTION.md)** - Relay flow, mainnet contracts, funding
- **[TOKEN_MAPPING_AND_MAINNET_ADDRESSES.md](TOKEN_MAPPING_AND_MAINNET_ADDRESSES.md)** - Token mapping (138↔Mainnet), relay-supported tokens, recommendations; source of truth: `config/token-mapping.json`
- **[MAPPER_COVERAGE_BRIDGES_AND_LIQUIDITY_POOLS.md](MAPPER_COVERAGE_BRIDGES_AND_LIQUIDITY_POOLS.md)** - Mapper (AddressMapper + config) coverage for all networks with bridges or liquidity pools
- **[MAPPER_GAPS_DEPLOYMENTS_AND_IMPROVEMENTS.md](MAPPER_GAPS_DEPLOYMENTS_AND_IMPROVEMENTS.md)** - Gaps, deployments, and improvements (based on mapper coverage)
- **[RECOMMENDED_COMPLETION_CHECKLIST.md](RECOMMENDED_COMPLETION_CHECKLIST.md)** - Operator checklist to complete all recommended items (Wemix, CCIP, LINK, AddressMapper, DODO, Trustless)
- **[WEMIX_TOKEN_VERIFICATION.md](WEMIX_TOKEN_VERIFICATION.md)** - Wemix (1111) WETH/USDT/USDC addresses from scan.wemix.com and verification steps
- **[EXPLORER_TOKENS_CANONICAL_MAPPING.md](EXPLORER_TOKENS_CANONICAL_MAPPING.md)** - Explorer tokens/contracts list URLs for all chains (canonical mapping verification)
- **[OPTIONAL_DEPLOYMENTS_START_HERE.md](OPTIONAL_DEPLOYMENTS_START_HERE.md)** - Deployments start here (AddressMapper other chains, DODO PMM 138, Trustless, Paymaster). *Note: Nothing is optional nor future — planned deployments.*
- **[RELAY_BRIDGE_ADD_LINK_SUPPORT_RUNBOOK.md](RELAY_BRIDGE_ADD_LINK_SUPPORT_RUNBOOK.md)** - Runbook: add LINK support to Mainnet relay bridge
- **[CCIP_SENDER_CONTRACT_REFERENCE.md](CCIP_SENDER_CONTRACT_REFERENCE.md)** - CCIP sender contract
- **[CCIP_SECURITY_DOCUMENTATION.md](CCIP_SECURITY_DOCUMENTATION.md)** - Security documentation
- **[BRIDGE_TESTING_GUIDE.md](BRIDGE_TESTING_GUIDE.md)** - Bridge testing procedures
### Tezos / Etherlink / Jumper
- **[TEZOS_NETWORK_CONFIG_ENV_MATRIX.md](TEZOS_NETWORK_CONFIG_ENV_MATRIX.md)** - Network config and env vars (138, 651940, 42793, Tezos)
- **Tezos explorer (contracts list):** [tzkt.io/contracts](https://tzkt.io/contracts) — verify Tezos token/contract addresses (FA1.2/FA2, KT1)
- **[TEZOS_JUMPER_SUPPORT_MATRIX.md](TEZOS_JUMPER_SUPPORT_MATRIX.md)** - Jumper API support for Tezos/Etherlink
- **[TEZOS_CCIP_DON_PREREQUISITES.md](TEZOS_CCIP_DON_PREREQUISITES.md)** - Tezos CCIP DON onboarding prerequisites
- **[TEZOS_CCIP_RUNBOOKS_INDEX.md](TEZOS_CCIP_RUNBOOKS_INDEX.md)** - Runbooks index (Tezos L1, Etherlink, Jumper)
- **[TEZOS_ETHERLINK_PRODUCTION_CONFIG.md](TEZOS_ETHERLINK_PRODUCTION_CONFIG.md)** - Feature flags, rate limits, caps
- **[TEZOS_ETHERLINK_DON_CONFIG.md](TEZOS_ETHERLINK_DON_CONFIG.md)** - DON config for Etherlink (when CCIP supported)
- **[TEZOS_ETHERLINK_RMN_POLICY.md](TEZOS_ETHERLINK_RMN_POLICY.md)** - RMN policy for Tezos/Etherlink flows
- **[TEZOS_CROSS_CHAIN_FINALITY.md](TEZOS_CROSS_CHAIN_FINALITY.md)** - Cross-chain finality rules
## Quick Reference
**CCIP Relay Service (deployed 2026-02-12):**
- **Host:** r630-01 (192.168.11.11)
- **Path:** `/opt/smom-dbis-138/services/relay`
- **Chain 138 RPC:** VMID 2201 (192.168.11.221:8545)
- **Purpose:** Monitors MessageSent events, relays to Ethereum Mainnet
**CCIP Deployment:**
- 41-43 nodes total (minimum production fleet)
- 16 Commit nodes, 16 Execute nodes, 7 RMN nodes
- VLAN assignments and NAT pool configuration
**Tezos / Etherlink:** Chain IDs 1 (Tezos registry), 42793 (Etherlink). See TEZOS_NETWORK_CONFIG_ENV_MATRIX for RPC and relay env vars. Jumper route selection: TEZOS_JUMPER_SUPPORT_MATRIX.
## Related Documentation
- **[../02-architecture/ORCHESTRATION_DEPLOYMENT_GUIDE.md](../02-architecture/ORCHESTRATION_DEPLOYMENT_GUIDE.md)** - Deployment orchestration
- **[../02-architecture/NETWORK_ARCHITECTURE.md](../02-architecture/NETWORK_ARCHITECTURE.md)** - Network architecture
- **[../03-deployment/](../03-deployment/)** - Deployment guides

129
docs/07-ccip/TOKEN_MAPPING_AND_MAINNET_ADDRESSES.md
View File

@@ -1,129 +0,0 @@
# Token Mapping and Mainnet Addresses (Chain 138 ↔ Ethereum Mainnet)
**Last Updated:** 2026-02-13
**Status:** Active
**Source of truth:** `config/token-mapping.json`
---
## Overview
Ethereum Mainnet (chainId 1) in `config/smart-contracts-master.json` lists only **CCIP relay contracts plus canonical WETH9 and LINK**. It does **not** include wrapped/mirrored ERC‑20 addresses for tokens that originate on Chain 138 (e.g. Compliant USDT/USDC, WETH10). This document defines the full mapping and how to use it.
---
## Definitive Mainnet Addresses (from source of truth)
| Token | Mainnet address | Notes |
|-------|-----------------|--------|
| **WETH9** (canonical) | `0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2` | Same on Chain 138; only token the current Mainnet CCIPRelayBridge accepts. |
| **LINK** (canonical) | `0x514910771AF9Ca656af840dff83E8264EcF986CA` | Canonical Mainnet LINK; relay bridge does **not** accept LINK yet (WETH9-only). |
For any other token (USDT, USDC, WETH10, etc.) the JSON and the Mainnet bridge do **not** specify a Mainnet “bridged” contract. Mainnet canonical references (for documentation only) are in `config/token-mapping.json` under `mainnetCanonicalReference`.
---
## Full mapping table (Chain 138 → Mainnet)
| Token key | Chain 138 address | Mainnet address | Relay supported (138→Mainnet) |
|-----------|-------------------|-----------------|-------------------------------|
| WETH9 | `0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2` | `0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2` | ✅ Yes |
| LINK_Token | `0xb7721dD53A8c629d9f1Ba31a5819AFe250002b03` | `0x514910771AF9Ca656af840dff83E8264EcF986CA` | ❌ No (bridge WETH9-only) |
| WETH10 | `0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9f` | — | ❌ No |
| Compliant_USDT | `0x93E66202A11B1772E55407B32B44e5Cd8eda7f22` | — | ❌ No |
| Compliant_USDC | `0xf22258f57794CC8E06237084b353Ab30fFfa640b` | — | ❌ No |
| Tether_USDT_Chain138 | `0x15DF1D5BFDD8Aa4b380445D4e3E9B38d34283619` | — | ❌ No |
“—” means no Mainnet wrapped/mirrored contract in the current design; the Mainnet CCIPRelayBridge has no token registry or factory for these.
---
## Where mapping is used
- **Relay service** (`smom-dbis-138/services/relay`): `config.js` builds `tokenMapping` (Chain 138 address → Mainnet address) from `config/token-mapping.json` when available, otherwise uses a fallback object. Only WETH9 is accepted by the Mainnet bridge; LINK is mapped for future use.
- **Config:** `config/token-mapping.json` is the single source of truth. `config/token-mapping-loader.cjs` provides `getRelayTokenMapping()` and `getTokenList()` for consumers.
---
## Mainnet bridge behaviour
- **CCIPRelayBridge** (Mainnet): `0xF9A32F37099c582D28b4dE7Fca6eaC1e5259f939`
- Accepts only **WETH9** (`message.tokenAmounts[0].token == weth9`).
- No view functions such as `getWrappedToken(originChainId, originToken)` or `nativeToWrapped(...)`.
- No on-chain token registry; no wrapped token deployment for Chain 138–origin tokens.
- **Getting Mainnet token address** for a bridged token:
- **WETH9:** use `0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2`.
- **LINK:** use `0x514910771AF9Ca656af840dff83E8264EcF986CA` (canonical); relay bridge does not support it yet.
- **Anything else:** not derivable from the current bridge or JSON; would require a different Mainnet contract that deploys/registers wrapped tokens and exposes a mapping.
---
## Recommendations and suggestions
1. **Keep `config/token-mapping.json` as the single source of truth**
Add or change token entries there; the relay and docs should reference it. When adding a new token with a Mainnet address, set `mainnetAddress` and `relaySupported` as appropriate.
2. **Extend Mainnet bridge for LINK (optional)**
To support 138→Mainnet LINK via the relay, either:
- Extend CCIPRelayBridge to accept LINK (and hold/fund LINK), or
- Deploy a separate receiver contract for LINK and point relay to it for LINK messages.
After that, set `relaySupported: true` for LINK in `token-mapping.json`.
3. **Document unsupported tokens**
WETH10, Compliant_USDT, Compliant_USDC, and Tether_USDT_Chain138 have no Mainnet wrapped address in this design. For token lists or UIs, use this doc or `token-mapping.json` so integrators do not assume a Mainnet address exists.
4. **If you introduce wrapped tokens on Mainnet later**
If a future bridge or TokenFactory deploys wrapped tokens on Mainnet for Chain 138 assets:
- Add the Mainnet wrapped address to `config/token-mapping.json` for that token.
- If the relay will deliver that token, add the Chain 138 → Mainnet mapping to the relay’s `tokenMapping` (already driven by `token-mapping.json` when the config path is available).
- Optionally add the wrapped contract to `config/smart-contracts-master.json` under chain 1 if you want it in the main contract list.
5. **Canonical Mainnet references (reference only)**
For documentation and off-chain tooling, canonical Mainnet addresses are in `config/token-mapping.json` under `mainnetCanonicalReference` (e.g. USDT, USDC, WETH9, LINK). These are not “bridged” addresses from Chain 138 unless explicitly mapped in `tokens`.
6. **Relay service**
When running the relay from the monorepo, ensure `config/token-mapping.json` and `config/token-mapping-loader.cjs` are available so the relay uses the full mapping. Fallback in `config.js` covers WETH9 and LINK when the config is not present.
---
## Additional recommendations
7. **CI validation**
The pipeline runs `scripts/validation/validate-config-files.sh` when `config/` changes. That script checks for `config/token-mapping.json` and, if present, validates that it is valid JSON with a `.tokens` array. Keep the file valid so CI passes.
8. **Sync when adding tokens**
When adding a new token to Chain 138 (or a new bridged token), update both:
- `config/smart-contracts-master.json` (under `chains.138.contracts` if it is a contract),
- `config/token-mapping.json` (add an entry with `key`, `chain138Address`, `mainnetAddress` if known, `relaySupported`, `notes`).
Optionally update [CHAIN138_TOKEN_ADDRESSES.md](../11-references/CHAIN138_TOKEN_ADDRESSES.md) and the cross-chain table there.
9. **Runbook for LINK support**
To enable 138→Mainnet LINK delivery, follow [RELAY_BRIDGE_ADD_LINK_SUPPORT_RUNBOOK.md](RELAY_BRIDGE_ADD_LINK_SUPPORT_RUNBOOK.md) (extend bridge or deploy separate LINK receiver, then set `relaySupported: true` for LINK in `token-mapping.json`).
10. **Token lists and UIs**
When building token lists or UIs that show “Mainnet address” or “bridged address” for Chain 138 tokens, read from `config/token-mapping.json` or this doc. Do not assume every Chain 138 token has a Mainnet address; only WETH9 is relay-supported today; LINK has a canonical Mainnet address but is not yet relay-supported.
---
## Multi-chain mapping (138↔651940, 651940↔other chains)
For **138↔651940** and **651940↔56, 137, 100, 43114, 8453, 42161, 10, 25, 1**, use `config/token-mapping-multichain.json`. The same loader provides:
- `getTokenMappingForPair(fromChainId, toChainId)` — returns `{ tokens, addressMapFromTo, addressMapToFrom }`.
- `getAllMultichainPairs()` — list of defined chain pairs.
- `getMappedAddress(fromChainId, toChainId, tokenAddress)` — resolve token address on target chain.
See [MAPPER_COVERAGE_BRIDGES_AND_LIQUIDITY_POOLS.md](MAPPER_COVERAGE_BRIDGES_AND_LIQUIDITY_POOLS.md). To verify canonical token addresses per chain, use the explorer token lists in [EXPLORER_TOKENS_CANONICAL_MAPPING.md](EXPLORER_TOKENS_CANONICAL_MAPPING.md).
---
## References
- [CCIP_BRIDGE_MAINNET_CONNECTION.md](CCIP_BRIDGE_MAINNET_CONNECTION.md) — Relay flow and mainnet contracts.
- [RELAY_BRIDGE_ADD_LINK_SUPPORT_RUNBOOK.md](RELAY_BRIDGE_ADD_LINK_SUPPORT_RUNBOOK.md) — Optional runbook to add LINK support to the Mainnet relay bridge.
- [MAPPER_COVERAGE_BRIDGES_AND_LIQUIDITY_POOLS.md](MAPPER_COVERAGE_BRIDGES_AND_LIQUIDITY_POOLS.md) — Mapper and multichain token mapping coverage.
- [CHAIN138_TOKEN_ADDRESSES.md](../11-references/CHAIN138_TOKEN_ADDRESSES.md) — Chain 138 token list.
- `config/token-mapping.json` — 138↔Mainnet machine-readable mapping.
- `config/token-mapping-multichain.json` — 138↔651940 and 651940↔CCIP/canonical chains.
- `config/token-mapping-loader.cjs` — Loader API for relay and multichain tooling.
- [EXPLORER_TOKENS_CANONICAL_MAPPING.md](EXPLORER_TOKENS_CANONICAL_MAPPING.md) — Explorer tokens/contracts list URLs for verifying canonical addresses per chain.

2
docs/07-ccip/WEMIX_TOKEN_VERIFICATION.md
View File

@@ -29,6 +29,8 @@ This doc records the Wemix token addresses used in `config/token-mapping-multich
- Our 651940↔1111 mapping uses **WETH** `0x5adcb99e7ccd357aceaade7abc5dfbd6f2fce1ae` (wrapped Ether, not WWEMIX). Confirm on scan that this is the correct WETH contract for bridged Ether on Wemix.
- USDT/USDC addresses in the table above are unchanged; confirm on scan or official lists.
**Re-check (2026-02-28):** Fetched scan.wemix.com/tokens again. WWEMIX confirmed at `0x7d72b22a74a216af4a002a1095c8c707d6ec1c5f`. WEMIX$ at `0x8e81fcc2d4a3baa0ee9044e0d7e36f59c9bba9c1`. USDT/USDC not in first 15 tokens; table above unchanged. Run validate-config-files.sh after any mapping change.
---
## How to verify