chore: sync all changes to Gitea

- Config, docs, scripts, and backup manifests - Submodule refs unchanged (m = modified content in submodules) Made-with: Cursor
2026-03-02 11:37:34 -08:00
parent ed85135249
commit b3a8fe4496
883 changed files with 73580 additions and 4796 deletions
--- a/docs/11-references/ADDRESS_MATRIX_AND_STATUS.md
+++ b/docs/11-references/ADDRESS_MATRIX_AND_STATUS.md
@@ -0,0 +1,215 @@
+# Address Matrix and Status — Correlated Reference
+
+**Last Updated:** 2026-02-28  
+**Purpose:** Single correlated matrix of all existing contract, token, and pool addresses with deployment status.  
+**Sources:** CONTRACT_ADDRESSES_REFERENCE, CHAIN138_TOKEN_ADDRESSES, LIQUIDITY_POOLS_MASTER_MAP, DEPLOYED_COINS_TOKENS_AND_NETWORKS, env examples, PRE_DEPLOYMENT_CHECKLIST.
+
+---
+
+## Status legend
+
+| Symbol | Meaning |
+|--------|---------|
+| ✅ | Deployed / Created / Live |
+| ❌ | Not deployed / Not created |
+| ⏳ | Pending (script run or set in .env from deploy output) |
+| ⛔ | Deprecated — do not use |
+| — | N/A or placeholder |
+
+---
+
+## 1. Chain 138 — Full address matrix
+
+### 1.1 Tokens (ERC‑20 / Genesis)
+
+| Symbol | Name | Address | Decimals | Status | Notes |
+|--------|------|---------|----------|--------|-------|
+| WETH | Wrapped Ether | `0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2` | 18 | ✅ | Genesis |
+| WETH10 | Wrapped Ether v10 | `0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9f` | 18 | ✅ | Genesis |
+| LINK | Chainlink Token | `0xb7721dD53A8c629d9f1Ba31a5819AFe250002b03` | 18 | ✅ | CCIP fees |
+| cUSDT | Compliant Tether USD | `0x93E66202A11B1772E55407B32B44e5Cd8eda7f22` | 6 | ✅ | Compliant stablecoin |
+| cUSDC | Compliant USD Coin | `0xf22258f57794CC8E06237084b353Ab30fFfa640b` | 6 | ✅ | Compliant stablecoin |
+| — | Tether USDT (official, Chain 138) | `0x15DF1D5BFDD8Aa4b380445D4e3E9B38d34283619` | — | ✅ | Reference / mainnet-style |
+| XAU | Gold (anchor) | — | — | ❌ | Not deployed |
+| cEURT | Compliant EUR T | — | — | ❌ | Not deployed |
+
+### 1.2 Core / registry / vault
+
+| Contract | Address | Status | Notes |
+|----------|---------|--------|-------|
+| ComplianceRegistry | `0xbc54fe2b6fda157c59d59826bcfdbcc654ec9ea1` | ✅ | |
+| TokenFactory | `0xEBFb5C60dE5f7C4baae180CA328D3BB39E1a5133` | ✅ | |
+| TokenRegistry | `0x91Efe92229dbf7C5B38D422621300956B55870Fa` | ✅ | |
+| BridgeVault | `0x31884f84555210FFB36a19D2471b8eBc7372d0A8` | ✅ | |
+| FeeCollector | `0xF78246eB94c6CB14018E507E60661314E5f4C53f` | ✅ | |
+| DebtRegistry | `0x95BC4A997c0670d5DAC64d55cDf3769B53B63C28` | ✅ | |
+| PolicyManager | `0x0C4FD27018130A00762a802f91a72D6a64a60F14` | ✅ | |
+| TokenImplementation | `0x0059e237973179146237aB49f1322E8197c22b21` | ✅ | |
+| Price Feed Keeper | `0xD3AD6831aacB5386B8A25BB8D8176a6C8a026f04` | ✅ | |
+| Multicall / Oracle Aggregator | `0x99b3511a2d315a497c8112c1fdd8d508d4b1e506` | ✅ | Confirm which contract at slot |
+| Oracle Proxy | `0x3304b747e565a97ec8ac220b0b6a1f6ffdb837e6` | ✅ | MetaMask price feed |
+
+### 1.3 CCIP / bridge (Chain 138)
+
+| Contract | Address | Status | Notes |
+|----------|---------|--------|-------|
+| CCIP Router | `0x8078A09637e47Fa5Ed34F626046Ea2094a5CDE5e` | ✅ | |
+| CCIP Sender | `0x105F8A15b819948a89153505762444Ee9f324684` | ✅ | |
+| CCIPWETH9Bridge | `0x971cD9D156f193df8051E48043C476e53ECd4693` | ✅ | Use for sendCrossChain |
+| CCIPWETH10Bridge | `0xe0E93247376aa097dB308B92e6Ba36bA015535D0` | ✅ | |
+| CCIPWETH9Bridge (old) | `0x89dd12025bfCD38A168455A44B400e913ED33BE2` | ⛔ | Deprecated |
+
+### 1.4 Governance / phased core / deterministic
+
+| Contract | Address | Status | Notes |
+|----------|---------|--------|-------|
+| UniversalAssetRegistry (proxy) | `0xAEE4b7fBe82E1F8295951584CBc772b8BBD68575` | ✅ | Phased core |
+| GovernanceController (proxy) | `0xA6891D5229f2181a34D4FF1B515c3Aa37dd90E0e` | ✅ | Phased core |
+| UniversalCCIPBridge (proxy) | `0xCd42e8eD79Dc50599535d1de48d3dAFa0BE156F8` | ✅ | Phased core |
+| BridgeOrchestrator (proxy) | `0x89aB428c437f23bAB9781ff8Db8D3848e27EeD6c` | ✅ | Phased core |
+| CREATE2Factory | `0x750E4a8adCe9f0e67A420aBE91342DC64Eb90825` | ✅ | |
+| UniversalAssetRegistry (deterministic) | `0xC98602aa574F565b5478E8816BCab03C9De0870f` | ✅ | |
+| UniversalCCIPBridge (deterministic) | `0x532DE218b94993446Be30eC894442f911499f6a3` | ✅ | |
+| MirrorRegistry | `0x6427F9739e6B6c3dDb4E94fEfeBcdF35549549d8` | ✅ | |
+| AlltraAdapter | `0x66FEBA2fC9a0B47F26DD4284DAd24F970436B8Dc` | ✅ | |
+
+### 1.5 Channels / mirror / trustless / reserve / vault
+
+| Contract | Address | Status | Notes |
+|----------|---------|--------|-------|
+| PaymentChannelManager | `0x302aF72966aFd21C599051277a48DAa7f01a5f54` | ✅ | |
+| GenericStateChannelManager | `0xe5e3bB424c8a0259FDE23F0A58F7e36f73B90aBd` | ✅ | |
+| AddressMapper | `0x439Fcb2d2ab2f890DCcAE50461Fa7d978F9Ffe1A` | ✅ | |
+| MirrorManager | `0x6eD905A30c552a6e003061A38FD52A5A427beE56` | ✅ | |
+| Lockbox138 | `0xFce6f50B312B3D936Ea9693C5C9531CF92a3324c` | ✅ | Trustless |
+| MerchantSettlementRegistry | `0x16D9A2cB94A0b92721D93db4A6Cd8023D3338800` | ✅ | |
+| WithdrawalEscrow | `0xe77cb26eA300e2f5304b461b0EC94c8AD6A7E46D` | ✅ | |
+| ReserveSystem | `0x607e97cD626f209facfE48c1464815DDE15B5093` | ✅ | |
+| ReserveTokenIntegration | `0x34B73e6EDFd9f85a7c25EeD31dcB13aB6E969b96` | ✅ | |
+| RegulatedEntityRegistry | `0xEA4C892D6c1253797c5D95a05BF3863363080b4B` | ✅ | Vault |
+| VaultFactory | `0xB2Ac70f35A81481B005067ed6567a5043BA32336` | ✅ | Vault |
+| Ledger | `0x67b3831dc64C14FB9352B2a45C6Dd69b3C86B7af` | ✅ | Vault |
+| Liquidation | `0x3aCdbCB749d6037a02F0ef6ea2E5Fb89D31fAB72` | ✅ | Vault |
+| XAU Oracle | `0xf23E1eDa304082ab7a81531dFE6020E6105e77A8` | ✅ | Vault |
+
+### 1.6 DODO PMM / liquidity (Chain 138)
+
+| Contract / pool | Address | Status | Notes |
+|-----------------|---------|--------|-------|
+| DODOPMMIntegration | `0x79cdbaFBaA0FdF9F55D26F360F54cddE5c743F7D` | ✅ | Mock DVM |
+| DODOPMMProvider | `0x8EF6657D2a86c569F6ffc337EE6b4260Bd2e59d0` | ✅ | Pools registered |
+| Pool cUSDT/cUSDC | `0x9fcB06Aa1FD5215DC0E91Fd098aeff4B62fEa5C8` | ✅ | Created |
+| Pool cUSDT/USDT | `0xa3Ee6091696B28e5497b6F491fA1e99047250c59` | ✅ | Created |
+| Pool cUSDC/USDC | `0x90bd9Bf18Daa26Af3e814ea224032d015db58Ea5` | ✅ | Created |
+| LiquidityPoolETH (trustless) | — | ❌ | Placeholder 0x0 |
+| EnhancedSwapRouter | — | ❌ | Not deployed |
+
+### 1.7 TransactionMirror / deployer
+
+| Item | Address | Status | Notes |
+|------|---------|--------|-------|
+| TransactionMirror | From deploy script (e.g. `0xb5876547c52CaBf49d7f40233B6f6a140F403d25`) | ⏳ | Set TRANSACTION_MIRROR_ADDRESS in .env |
+| Deployer / Admin | `0x4A666F96fC8764181194447A7dFdb7d471b301C8` | ✅ | EOA |
+
+---
+
+## 2. Multi-chain matrix (by chain)
+
+### 2.1 Chain 138 (primary)
+
+| Category | Count | Status summary |
+|----------|-------|-----------------|
+| Tokens | 5 live, 2 not deployed (XAU, cEURT) | ✅ cUSDT, cUSDC, WETH, WETH10, LINK |
+| Core / registry | 11+ | ✅ All deployed |
+| CCIP / bridge | 4 (1 deprecated) | ✅ Use 0x971c… WETH9 bridge |
+| Governance / deterministic | 9 | ✅ All deployed |
+| Channels / mirror / reserve / vault | 14+ | ✅ All deployed |
+| PMM / pools | 1 integration, 1 provider, 3 pools | ✅ Created; add liquidity to pools |
+| TransactionMirror | 1 | ⏳ Set from deploy output |
+
+### 2.2 Ethereum Mainnet (1)
+
+| Item | Address / value | Status |
+|------|------------------|--------|
+| CCIPRelayRouter | `0xAd9A228CcEB4cbB612cD165FFB72fE090ff10Afb` | ✅ |
+| CCIPRelayBridge | `0xF9A32F37099c582D28b4dE7Fca6eaC1e5259f939` | ✅ |
+| WETH | `0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2` | ✅ |
+| USDT | `0xdAC17F958D2ee523a2206206994597C13D831ec7` | ✅ |
+| USDC | `0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48` | ✅ |
+
+### 2.3 ALL Mainnet (651940)
+
+| Symbol | Address | Status |
+|--------|---------|--------|
+| AUSDT | `0x015B1897Ed5279930bC2Be46F661894d219292A6` | ✅ |
+| USDT (alt) | `0x66D8Efa0AF63B0e84eb1Dd72bf00f00cd1e2234e` | ✅ |
+| USDC (AUSDC) | `0xa95EeD79f84E6A0151eaEb9d441F9Ffd50e8e881` | ✅ |
+| WETH | `0x798F6762BB40d6801A593459d08F890603D3979C` | ✅ |
+| WALL | `0x2da2b8f961F161ab6320acB3377e2e844a3C3ce4` | ✅ |
+| HYDX | `0x0d9793861AEB9244AD1B34375a83A6730F6AdD38` | ✅ |
+
+### 2.4 Cronos (25) — ISO‑4217 W tokens
+
+| Symbol | Address | Status |
+|--------|---------|--------|
+| WETH9 | `0x99B3511A2d315A497C8112C1fdd8D508d4B1E506` | ✅ |
+| WETH10 | `0x3304b747E565a97ec8AC220b0B6A1f6ffDB837e6` | ✅ |
+| LINK | `0x8c80A01F461f297Df7F9DA3A4f740D7297C8Ac85` | ✅ |
+| USDW / EURW / GBPW / AUDW / JPYW / CHFW / CADW | (see DEPLOYED_COINS_TOKENS_AND_NETWORKS) | ✅ |
+
+### 2.5 CCIP config-ready chains (Gnosis, Celo, Wemix, Cronos)
+
+Bridges (CCIPWETH9 / CCIPWETH10) and LINK funding per runbook. Addresses in `smom-dbis-138/.env` and [ENV_CONFIG_READY_CHAINS.example](../../smom-dbis-138/docs/deployment/ENV_CONFIG_READY_CHAINS.example). Status: deploy bridges → run `complete-config-ready-chains.sh` → fund with LINK.
+
+| Chain | Chain ID | CCIP bridges | Status |
+|-------|----------|---------------|--------|
+| Gnosis | 100 | CCIPWETH9_BRIDGE_GNOSIS, CCIPWETH10_BRIDGE_GNOSIS | Set in .env after deploy |
+| Celo | 42220 | CCIPWETH9_BRIDGE_CELO, CCIPWETH10_BRIDGE_CELO | Set in .env after deploy |
+| Wemix | 1111 | CCIPWETH9_BRIDGE_WEMIX, CCIPWETH10_BRIDGE_WEMIX | Set in .env after deploy |
+| Cronos | 25 | CCIPWETH9_BRIDGE_CRONOS, CCIPWETH10_BRIDGE_CRONOS | Set in .env after deploy |
+
+---
+
+## 3. Env / config correlation
+
+| Env variable (Chain 138) | Canonical address |
+|--------------------------|-------------------|
+| DODO_PMM_INTEGRATION_ADDRESS | `0x79cdbaFBaA0FdF9F55D26F360F54cddE5c743F7D` |
+| DODO_PMM_PROVIDER_ADDRESS | `0x8EF6657D2a86c569F6ffc337EE6b4260Bd2e59d0` |
+| POOL_CUSDTCUSDC | `0x9fcB06Aa1FD5215DC0E91Fd098aeff4B62fEa5C8` |
+| POOL_CUSDTUSDT | `0xa3Ee6091696B28e5497b6F491fA1e99047250c59` |
+| POOL_CUSDCUSDC | `0x90bd9Bf18Daa26Af3e814ea224032d015db58Ea5` |
+| CCIPWETH9_BRIDGE_CHAIN138 | `0x971cD9D156f193df8051E48043C476e53ECd4693` |
+| CCIPWETH10_BRIDGE_CHAIN138 | `0xe0E93247376aa097dB308B92e6Ba36bA015535D0` |
+| LINK_TOKEN | `0xb7721dD53A8c629d9f1Ba31a5819AFe250002b03` |
+| COMPLIANT_USDT_ADDRESS / cUSDT | `0x93E66202A11B1772E55407B32B44e5Cd8eda7f22` |
+| COMPLIANT_USDC_ADDRESS / cUSDC | `0xf22258f57794CC8E06237084b353Ab30fFfa640b` |
+| TRANSACTION_MIRROR_ADDRESS | ⏳ From deploy script output |
+
+---
+
+## 4. Summary counts (Chain 138)
+
+| Category | Deployed | Not deployed | Pending / deprecated |
+|----------|----------|--------------|----------------------|
+| Tokens | 5 | 2 (XAU, cEURT) | 0 |
+| Core / CCIP / governance / vault / reserve | 35+ | 0 | 0 |
+| PMM integration + provider + pools | 5 | 1 (EnhancedSwapRouter), 1 (LiquidityPoolETH) | 0 |
+| Deprecated | 0 | 0 | 1 (old CCIPWETH9Bridge) |
+| TransactionMirror | — | — | 1 (set in .env) |
+
+---
+
+## 5. References
+
+| Document | Purpose |
+|----------|---------|
+| [CONTRACT_ADDRESSES_REFERENCE.md](CONTRACT_ADDRESSES_REFERENCE.md) | Full contract list and canonical .env |
+| [CHAIN138_TOKEN_ADDRESSES.md](CHAIN138_TOKEN_ADDRESSES.md) | Tokens on Chain 138 |
+| [LIQUIDITY_POOLS_MASTER_MAP.md](LIQUIDITY_POOLS_MASTER_MAP.md) | Pools (138 + ALL Mainnet) |
+| [DEPLOYED_COINS_TOKENS_AND_NETWORKS.md](DEPLOYED_COINS_TOKENS_AND_NETWORKS.md) | Networks and tokens by chain |
+| [PRE_DEPLOYMENT_CHECKLIST.md](../03-deployment/PRE_DEPLOYMENT_CHECKLIST.md) | PMM / pool / provider status |
+| [config/smart-contracts-master.json](../../config/smart-contracts-master.json) | Machine-readable single source (when present) |
+
+**Explorer (Chain 138):** https://explorer.d-bis.org  
+**Verification script:** `./scripts/verify/check-contracts-on-chain-138.sh`
--- a/docs/11-references/API_DOCUMENTATION.md
+++ b/docs/11-references/API_DOCUMENTATION.md
@@ -16,6 +16,7 @@
 |-----|----------|-------------|
 | **Bridge API** | This file | Bridge operations, CCIP, contract addresses |
 | **DBIS Core API** | [DBIS_CORE_API_REFERENCE.md](DBIS_CORE_API_REFERENCE.md) | DBIS Core APIs including Crypto.com OTC 2.0 |
+| **OMNL Fineract** | [../api/omnl-fineract-openapi.json](../api/omnl-fineract-openapi.json) | OpenAPI 3.0.3 spec pulled from [Swagger UI](https://omnl.hybxfinance.io/fineract-provider/swagger-ui/index.html); 555 paths, 91 tags |

 ---

--- a/docs/11-references/CHAIN138_TOKEN_ADDRESSES.md
+++ b/docs/11-references/CHAIN138_TOKEN_ADDRESSES.md
@@ -1,111 +0,0 @@
-# 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): Set `RPC_URL_138` (e.g. `http://192.168.11.211:8545` 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`
-
---
-
-## 🌉 Cross-chain (Chain 138 → Ethereum Mainnet)
-
-Not all Chain 138 tokens have a Mainnet bridged/wrapped address. The relay bridge on Mainnet is **WETH9-only**.
-
-| Token | Relay-supported (138→Mainnet) | Mainnet address (if any) |
-|-------|------------------------------|---------------------------|
-| WETH9 | ✅ Yes | `0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2` (same) |
-| LINK | ❌ No (bridge WETH9-only) | Canonical: `0x514910771AF9Ca656af840dff83E8264EcF986CA` |
-| WETH10, cUSDT, cUSDC, Tether_Chain138 | ❌ No | No Mainnet wrapped contract in current design |
-
-**Source of truth:** [TOKEN_MAPPING_AND_MAINNET_ADDRESSES.md](../07-ccip/TOKEN_MAPPING_AND_MAINNET_ADDRESSES.md) and `config/token-mapping.json`. Use these for token lists and UIs so integrators do not assume a Mainnet address exists for unsupported tokens.
-
---
-
-## 📝 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 $RPC_URL_138
-
-# Check token details (name, symbol, decimals)
-cast call <TOKEN_ADDRESS> "name()" --rpc-url $RPC_URL_138
-cast call <TOKEN_ADDRESS> "symbol()" --rpc-url $RPC_URL_138
-cast call <TOKEN_ADDRESS> "decimals()" --rpc-url $RPC_URL_138
-```
-
---
-
-## 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`
- **Cross-chain mapping:** [TOKEN_MAPPING_AND_MAINNET_ADDRESSES.md](../07-ccip/TOKEN_MAPPING_AND_MAINNET_ADDRESSES.md), `config/token-mapping.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)
--- a/docs/11-references/CONTRACT_ADDRESSES_REFERENCE.md
+++ b/docs/11-references/CONTRACT_ADDRESSES_REFERENCE.md
@@ -1,7 +1,7 @@
 # Contract Addresses Reference - ChainID 138

-**Last Updated:** 2026-02-13  
-**Document Version:** 1.3  
+**Last Updated:** 2026-02-28  
+**Document Version:** 1.4  
 **Status:** Active Documentation

 ---
@@ -21,7 +21,7 @@ See [config/README-CONTRACTS-MASTER.md](../../config/README-CONTRACTS-MASTER.md)
 **Network**: ChainID 138  
 **RPC Endpoint** (admin/deployment): Set `RPC_URL_138` (e.g. `http://192.168.11.211:8545` or `https://rpc-core.d-bis.org`)  
 **Explorer:** https://explorer.d-bis.org (Blockscout) — use for Chain 138 balances, contracts, and verification. For balances on **other chains** (Ethereum mainnet, etc.), use [blockscan.com](https://blockscan.com) or etherscan.io. See [EXPLORER_AND_BLOCKSCAN_REFERENCE](EXPLORER_AND_BLOCKSCAN_REFERENCE.md).  
-**Full inventory (deployed/undeployed/deprecated/verification):** [CONTRACT_INVENTORY_AND_VERIFICATION.md](CONTRACT_INVENTORY_AND_VERIFICATION.md)
+**Correlated matrix and status (Chain 138 + multi-chain):** [ADDRESS_MATRIX_AND_STATUS.md](ADDRESS_MATRIX_AND_STATUS.md). Reconcile addresses here and in `.env` when deploying or deprecating contracts (R2).

 ---

@@ -57,7 +57,7 @@ Contracts deployed after chain initialization:
 | **MultiSig** (deploy 2026-02-13) | `0xb9E29cFa1f89d369671E640d0BB3aD94Cab43965` | ✅ Deployed | deploy-all-contracts.sh | |
 | **CCIPReceiver** (deploy 2026-02-13) | `0xC12236C03b28e675d376774FCE2C2C052488430F` | ✅ Deployed | DeployCCIPReceiver.s.sol | |
 | **Voting** (deploy 2026-02-13) | `0x022267b26400114aF01BaCcb92456Fe36cfccD93` | ✅ Deployed | DeployVoting.s.sol | |
-| **UniversalAssetRegistry** (proxy) | `0xAEE4b7fBe82E1F8295951584CBc772b8BBD68575` | ✅ Deployed | Phased core (2026-02-11) | |
+| **UniversalAssetRegistry** (proxy) | `0xAEE4b7fBe82E1F8295951584CBc772b8BBD68575` | ✅ Deployed | Phased core (2026-02-11). Upgraded to impl `0x2526682F7e24febE4422647F0bFfA16b50438AA4` (registerGRUCompliantAsset). Upgrade script: `script/deploy/UpgradeUniversalAssetRegistry.s.sol`. | |
 | **GovernanceController** (proxy) | `0xA6891D5229f2181a34D4FF1B515c3Aa37dd90E0e` | ✅ Deployed | Phased core (2026-02-11) | |
 | **UniversalCCIPBridge** (proxy) | `0xCd42e8eD79Dc50599535d1de48d3dAFa0BE156F8` | ✅ Deployed | Phased core (2026-02-11) | |
 | **BridgeOrchestrator** (proxy) | `0x89aB428c437f23bAB9781ff8Db8D3848e27EeD6c` | ✅ Deployed | Phased core (2026-02-11) | |
@@ -89,6 +89,13 @@ Contracts deployed after chain initialization:
 | **MirrorRegistry** | `0x6427F9739e6B6c3dDb4E94fEfeBcdF35549549d8` | Merkle commitment roots for mirroring |
 | **AlltraAdapter** | `0x66FEBA2fC9a0B47F26DD4284DAd24F970436B8Dc` | Bridge adapter for ALL Mainnet (651940) |

+### TransactionMirror & DODO pool (Chain 138)
+
+| Contract | Address | Status / Notes |
+|----------|---------|----------------|
+| **TransactionMirror** | `0x7131F887DBEEb2e44c1Ed267D2A68b5b83285afc` (Chain 138; deployed 2026-02-27) | Set `TRANSACTION_MIRROR_ADDRESS` in `smom-dbis-138/.env`. Deploy: `./scripts/deployment/deploy-transaction-mirror-and-pmm-pool-after-txpool-clear.sh`. |
+| **DODO cUSDT/cUSDC pool** | `0x9fcB06Aa1FD5215DC0E91Fd098aeff4B62fEa5C8` | Pending until CreateCUSDTCUSDCPool succeeds; same script deploys after mirror. See [REQUIRED_FIXES_AND_DEPLOYMENTS_STATUS](../03-deployment/REQUIRED_FIXES_AND_DEPLOYMENTS_STATUS.md). |
+
 ### Deployer / Admin (Chain 138)

 | Role | Address | Explorer (Chain 138 only) |
@@ -192,9 +199,9 @@ Chain 138 WETH9 bridges (LINK fee and native ETH fee) have mainnet destination s

 | Address | Note |
 |---------|------|
-| `0x89dd12025bfCD38A168455A44B400e913ED33BE2` | **Deprecated** — old CCIPWETH9Bridge with router mismatch (no code at router). Use **CCIPWETH9Bridge** at `0x971cD9D156f193df8051E48043C476e53ECd4693` instead. See [CONTRACT_INVENTORY_AND_VERIFICATION.md](CONTRACT_INVENTORY_AND_VERIFICATION.md). |
+| `0x89dd12025bfCD38A168455A44B400e913ED33BE2` | **Deprecated** — old CCIPWETH9Bridge with router mismatch (no code at router). Use **CCIPWETH9Bridge** at `0x971cD9D156f193df8051E48043C476e53ECd4693` instead. See [ADDRESS_MATRIX_AND_STATUS.md](ADDRESS_MATRIX_AND_STATUS.md). |

 ---

-**Related:** [EXPLORER_AND_BLOCKSCAN_REFERENCE](EXPLORER_AND_BLOCKSCAN_REFERENCE.md) (correct explorer vs blockscan.com) | [CONTRACT_INVENTORY_AND_VERIFICATION](CONTRACT_INVENTORY_AND_VERIFICATION.md) | [CONTRACTS_TO_DEPLOY](CONTRACTS_TO_DEPLOY.md) | [CHAIN138_TOKEN_ADDRESSES](CHAIN138_TOKEN_ADDRESSES.md) | [TOKEN_MAPPING_AND_MAINNET_ADDRESSES](../07-ccip/TOKEN_MAPPING_AND_MAINNET_ADDRESSES.md) (138↔Mainnet token mapping)
+**Related:** [ADDRESS_MATRIX_AND_STATUS](ADDRESS_MATRIX_AND_STATUS.md) (correlated matrix and status) | [EXPLORER_AND_BLOCKSCAN_REFERENCE](EXPLORER_AND_BLOCKSCAN_REFERENCE.md) (correct explorer vs blockscan.com) | [ADDRESS_MATRIX_AND_STATUS](ADDRESS_MATRIX_AND_STATUS.md) | [CONTRACTS_TO_DEPLOY](CONTRACTS_TO_DEPLOY.md) | [CHAIN138_TOKEN_ADDRESSES](CHAIN138_TOKEN_ADDRESSES.md) | [TOKEN_MAPPING_AND_MAINNET_ADDRESSES](../07-ccip/TOKEN_MAPPING_AND_MAINNET_ADDRESSES.md) (138↔Mainnet token mapping)

--- a/docs/11-references/CONTRACT_INVENTORY_AND_VERIFICATION.md
+++ b/docs/11-references/CONTRACT_INVENTORY_AND_VERIFICATION.md
@@ -1,188 +0,0 @@
-# Contract Inventory and Verification — ChainID 138
-
-**Last Updated:** 2026-02-13  
-**Status:** Authoritative inventory for deployed/undeployed contracts, on-chain confirmation, and deprecated addresses.  
-**On-chain check:** 36 addresses (26 canonical + 5 channels/mirror/trustless + 5 CREATE2) — run `./scripts/verify/check-contracts-on-chain-138.sh` (uses `RPC_URL_138`) or pass URL. Use `--with-gas-price 1000000000` for all Chain 138 Forge deploys.  
-**Sources:** Documentation, dotenv examples, reports, `CONTRACT_ADDRESSES_REFERENCE.md`, `CHAIN138_TOKEN_ADDRESSES.md`, `CONTRACTS_TO_DEPLOY.md`, scripts, and env templates.
-
---
-
-## 1. Summary
-
-| Category | Count | Notes |
-|----------|--------|--------|
-| **Deployed (Chain 138)** | 36 | 36 addresses in check script (26 canonical + 5 channels/mirror/trustless + 5 CREATE2). Phased core 2026-02-11; AddressMapper, MirrorManager 2026-02-12. See tables below; verify on Blockscout when needed. |
-| **Undeployed / placeholders** | Multiple | TransactionMirror (deploy via forge create if needed); trustless mainnet stack; Dodo PMM; etc. |
-| **Deprecated / do not use** | 1 | Old CCIPWETH9 bridge (router mismatch) |
-| **Other chains** | — | Mainnet/ALL/651940 addresses in env examples only; not verified here |
-
---
-
-## 2. Deployed Contracts (Chain 138)
-
-### 2.1 Pre-deployed (Genesis)
-
-| Contract | Address | On-chain | Verified (Blockscout) | Notes |
-|----------|---------|----------|------------------------|--------|
-| WETH9 | `0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2` | ✅ Documented | Confirm at explorer | Genesis allocation |
-| WETH10 | `0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9f` | ✅ Documented | Confirm at explorer | Genesis allocation |
-| Multicall | `0x99b3511a2d315a497c8112c1fdd8d508d4b1e506` | ✅ Documented | Confirm at explorer | Genesis allocation; same address used for Oracle Aggregator in some docs — verify which contract is at this slot |
-
-### 2.2 Core / Oracle / CCIP
-
-| Contract | Address | On-chain | Verified (Blockscout) | Notes |
-|----------|---------|----------|------------------------|--------|
-| Oracle Aggregator | `0x99b3511a2d315a497c8112c1fdd8d508d4b1e506` | ✅ Documented | Confirm at explorer | May share address with Multicall; see [CONTRACT_ADDRESSES_REFERENCE](CONTRACT_ADDRESSES_REFERENCE.md) |
-| Oracle Proxy | `0x3304b747e565a97ec8ac220b0b6a1f6ffdb837e6` | ✅ Documented | Confirm at explorer | MetaMask price feed |
-| CCIP Router | `0x8078A09637e47Fa5Ed34F626046Ea2094a5CDE5e` | ✅ Documented | Confirm at explorer | Cross-chain router |
-| CCIP Sender | `0x105F8A15b819948a89153505762444Ee9f324684` | ✅ Documented | ⏳ Pending (doc) | [CCIP_SENDER_CONTRACT_REFERENCE](../07-ccip/CCIP_SENDER_CONTRACT_REFERENCE.md). Empty on mainnet; use on Chain 138 only. |
-| CCIPWETH9Bridge | `0x971cD9D156f193df8051E48043C476e53ECd4693` | ✅ Documented | Confirm at explorer | **Use for sendCrossChain**; working router |
-| CCIPWETH10Bridge | `0xe0E93247376aa097dB308B92e6Ba36bA015535D0` | ✅ Documented | Confirm at explorer | WETH10 cross-chain |
-| CCIPReceiver | `0xC12236C03b28e675d376774FCE2C2C052488430F` | ✅ Deployed 2026-02-13 | DeployCCIPReceiver.s.sol | Chain 138 |
-| Voting | `0x022267b26400114aF01BaCcb92456Fe36cfccD93` | ✅ Deployed 2026-02-13 | DeployVoting.s.sol | Chain 138 |
-
-### 2.3 Tokens (Chain 138)
-
-| Contract | Address | On-chain | Verified (Blockscout) | Notes |
-|----------|---------|----------|------------------------|--------|
-| LINK | `0xb7721dD53A8c629d9f1Ba31a5819AFe250002b03` | ✅ Documented | Confirm at explorer | CCIP fees |
-| CompliantUSDT (cUSDT) | `0x93E66202A11B1772E55407B32B44e5Cd8eda7f22` | ✅ Documented | Confirm at explorer | 6 decimals |
-| CompliantUSDC (cUSDC) | `0xf22258f57794CC8E06237084b353Ab30fFfa640b` | ✅ Documented | Confirm at explorer | 6 decimals; used by WithdrawalEscrow |
-
-### 2.4 Registry / Factory / Keeper
-
-| Contract | Address | On-chain | Verified (Blockscout) | Notes |
-|----------|---------|----------|------------------------|--------|
-| TokenRegistry | `0x91Efe92229dbf7C5B38D422621300956B55870Fa` | ✅ In MASTER_SECRETS, CHAIN138_TOKEN_ADDRESSES | Confirm at explorer | Central token registry |
-| TokenFactory | `0xEBFb5C60dE5f7C4baae180CA328D3BB39E1a5133` | ✅ In MASTER_SECRETS, explorer docs | Confirm at explorer | Token factory |
-| Price Feed Keeper | `0xD3AD6831aacB5386B8A25BB8D8176a6C8a026f04` | ✅ In scripts, INTEGRATION_TEST_SUMMARY, archive | ⏳ Pending (archive docs) | Automation; confirm at explorer |
-
-### 2.5 Governance / vault / policy (canonical .env)
-
-Canonical addresses from [CONTRACT_ADDRESSES_REFERENCE § Canonical source of truth](CONTRACT_ADDRESSES_REFERENCE.md#-canonical-source-of-truth-chain-138). Confirm on-chain when RPC/explorer is reachable.
-
-| Contract | Address | On-chain | Verified (Blockscout) | Notes |
-|----------|---------|----------|------------------------|--------|
-| ComplianceRegistry | `0xbc54fe2b6fda157c59d59826bcfdbcc654ec9ea1` | ✅ Documented | Confirm at explorer | Governance |
-| BridgeVault | `0x31884f84555210FFB36a19D2471b8eBc7372d0A8` | ✅ Documented | Confirm at explorer | Vault |
-| FeeCollector | `0xF78246eB94c6CB14018E507E60661314E5f4C53f` | ✅ Documented | Confirm at explorer | Fees |
-| DebtRegistry | `0x95BC4A997c0670d5DAC64d55cDf3769B53B63C28` | ✅ Documented | Confirm at explorer | Debt |
-| PolicyManager | `0x0C4FD27018130A00762a802f91a72D6a64a60F14` | ✅ Documented | Confirm at explorer | Policy |
-| TokenImplementation | `0x0059e237973179146237aB49f1322E8197c22b21` | ✅ Documented | Confirm at explorer | Token impl |
-
-### 2.6 Settlement (alltra-lifi-settlement)
-
-| Contract | Address | On-chain | Verified (Blockscout) | Notes |
-|----------|---------|----------|------------------------|--------|
-| MerchantSettlementRegistry | `0x16D9A2cB94A0b92721D93db4A6Cd8023D3338800` | ✅ Documented | Confirm at explorer | alltra-lifi-settlement |
-| WithdrawalEscrow | `0xe77cb26eA300e2f5304b461b0EC94c8AD6A7E46D` | ✅ Documented | Confirm at explorer | alltra-lifi-settlement; depends on cUSDC |
-
-### 2.7 Phased core (deployed 2026-02-11)
-
-| Contract | Address | On-chain | Verified (Blockscout) | Notes |
-|----------|---------|----------|------------------------|--------|
-| UniversalAssetRegistry (proxy) | `0xAEE4b7fBe82E1F8295951584CBc772b8BBD68575` | ✅ Deployed | Confirm at explorer | 01_DeployCore |
-| GovernanceController (proxy) | `0xA6891D5229f2181a34D4FF1B515c3Aa37dd90E0e` | ✅ Deployed | Confirm at explorer | 01_DeployCore |
-| UniversalCCIPBridge (proxy) | `0xCd42e8eD79Dc50599535d1de48d3dAFa0BE156F8` | ✅ Deployed | Confirm at explorer | 02_DeployBridges |
-| BridgeOrchestrator (proxy) | `0x89aB428c437f23bAB9781ff8Db8D3848e27EeD6c` | ✅ Deployed | Confirm at explorer | 02_DeployBridges |
-
-### 2.8 Channels / Trustless / Reserve / Vault (deployed 2026-02-11)
-
-| Contract | Address | Notes |
-|----------|---------|--------|
-| PaymentChannelManager | `0x302aF72966aFd21C599051277a48DAa7f01a5f54` | Channels |
-| GenericStateChannelManager | `0xe5e3bB424c8a0259FDE23F0A58F7e36f73B90aBd` | Channels |
-| Lockbox138 | `0xFce6f50B312B3D936Ea9693C5C9531CF92a3324c` | Trustless bridge |
-| AddressMapper | `0x439Fcb2d2ab2f890DCcAE50461Fa7d978F9Ffe1A` | DeployAddressMapper 2026-02-12 |
-| MirrorManager | `0x6eD905A30c552a6e003061A38FD52A5A427beE56` | DeployMirrorManager 2026-02-12 |
-| ReserveSystem | `0x607e97cD626f209facfE48c1464815DDE15B5093` | Reserve |
-| ReserveTokenIntegration | `0x34B73e6EDFd9f85a7c25EeD31dcB13aB6E969b96` | Reserve |
-| Vault system (Registry, Ledger, Liquidation, XAU Oracle, VaultFactory, etc.) | See CONTRACT_ADDRESSES_REFERENCE § Channels/Trustless/Reserve/Vault | DeployVaultSystem.s.sol |
-
---
-
-## 3. Deprecated Smart Contracts
-
-| Contract / Address | Reason | Action |
-|--------------------|--------|--------|
-| **CCIPWETH9Bridge** at `0x89dd12025bfCD38A168455A44B400e913ED33BE2` | **Deprecated.** Old bridge with router mismatch (pointed to address with no code). Replaced by bridge at `0x971cD9D156f193df8051E48043C476e53ECd4693`. | Do not use. Use `CCIPWETH9_BRIDGE_CHAIN138` from env or `0x971cD9D156f193df8051E48043C476e53ECd4693`. See [CCIP_SECURITY_DOCUMENTATION](../07-ccip/CCIP_SECURITY_DOCUMENTATION.md), [scripts/README.md](../../scripts/README.md). |
-
---
-
-## 4. Undeployed / Placeholder Contracts
-
-Addresses that appear in config or env templates as placeholders or not yet deployed on Chain 138:
-
- **Trustless bridge (Chain 138):** **Lockbox138 deployed** at `0xFce6f50B312B3D936Ea9693C5C9531CF92a3324c`. INBOX_ETH, BOND_MANAGER, CHALLENGE_MANAGER, LIQUIDITY_POOL, SWAP_ROUTER, BRIDGE_SWAP_COORDINATOR, MULTISIG — still placeholders in config when needed.
- **Phased core:** Deployed 2026-02-11 (see §2.7).
- **CREATE2 / deterministic:** **Deployed 2026-02-11** via DeployDeterministicCore.s.sol. Addresses: CREATE2Factory, UniversalAssetRegistry (proxy), UniversalCCIPBridge (proxy), MirrorRegistry, AlltraAdapter — see [CONTRACT_ADDRESSES_REFERENCE](CONTRACT_ADDRESSES_REFERENCE.md) § CREATE2 / Deterministic. setCCIPRouter(router) set on deterministic bridge 2026-02-11.
- **Dodo / swap:** ENHANCED_SWAP_ROUTER is mainnet-only script; Chain 138 Dodo placeholders in .env.example when needed.
- **Channels:** **PaymentChannelManager** and **GenericStateChannelManager** deployed 2026-02-11 (see §2.8). **AddressMapper** and **MirrorManager** deployed 2026-02-12 at `0x439Fcb2d2ab2f890DCcAE50461Fa7d978F9Ffe1A` and `0x6eD905A30c552a6e003061A38FD52A5A427beE56`. **TransactionMirror** — deploy when needed. If Forge script hits constructor-args decode bug, use `forge create` or run `./scripts/deployment/deploy-transaction-mirror-chain138.sh` (see CONTRACT_DEPLOYMENT_RUNBOOK § TransactionMirror).
- **Firefly:** Auto-deployed by Firefly (VMID 6200); addresses not in this repo.
-
---
-
-## 5. Confirming and Verifying On-Chain
-
- **Explorer:** https://explorer.d-bis.org (Blockscout).  
- **Verification:** Use [BLOCKSCOUT_VERIFICATION_GUIDE](../08-monitoring/BLOCKSCOUT_VERIFICATION_GUIDE.md) and [CONTRACT_DEPLOYMENT_RUNBOOK](../03-deployment/CONTRACT_DEPLOYMENT_RUNBOOK.md) (Forge Verification Proxy).  
- **Quick checks (RPC):**
-  ```bash
-  export RPC_URL_138=http://192.168.11.211:8545  # or https://rpc-core.d-bis.org (Chain 138 Core)
-  cast code <ADDRESS> --rpc-url $RPC_URL   # non-empty = contract present
-  ```
- **Verification status** in this doc is based on documentation and scripts; **confirm each contract on Blockscout** (explorer.d-bis.org) for "Verified" status and bytecode.
-
---
-
-## 6. Dotenv / Config Sources
-
-Contract-related env and config were reviewed in:
-
- Root: `.env.example`
- `smom-dbis-138`: `.env`, `.env.example`, `terraform/phases/phase1/config/env.chain138.example`, `config/trustless-bridge.config.json.example`
- `alltra-lifi-settlement`: `env.example`
- `config/production`: `.env.production.example`
- Backups under `backups/configs/` (production env examples)
- Docs: [CONTRACT_ADDRESSES_REFERENCE](CONTRACT_ADDRESSES_REFERENCE.md), [CHAIN138_TOKEN_ADDRESSES](CHAIN138_TOKEN_ADDRESSES.md), [CONTRACTS_TO_DEPLOY](CONTRACTS_TO_DEPLOY.md), [MASTER_SECRETS_INVENTORY](../04-configuration/MASTER_SECRETS_INVENTORY.md), [07-ccip/CCIP_SECURITY_DOCUMENTATION](../07-ccip/CCIP_SECURITY_DOCUMENTATION.md), [07-ccip/CCIP_SENDER_CONTRACT_REFERENCE](../07-ccip/CCIP_SENDER_CONTRACT_REFERENCE.md)
-
-No secrets (e.g. private keys) are stored in this inventory; only public addresses.
-
---
-
-## 7. Inconsistencies Resolved (2026-02-11)
-
-The following were corrected for consistency with [CONTRACT_ADDRESSES_REFERENCE](CONTRACT_ADDRESSES_REFERENCE.md):
-
-| Location | Issue | Correction |
-|----------|--------|------------|
-| `smom-dbis-138/.env.example` | `CCIP_ROUTER_ADDRESS` was `0x99B3...` (Multicall/Oracle Aggregator) | Set to CCIP Router `0x8078A09637e47Fa5Ed34F626046Ea2094a5CDE5e` |
-| `smom-dbis-138/terraform/phases/phase1/config/env.chain138.example` | Wrong CCIP_ROUTER, CCIPWETH9/10 bridges, LINK (mainnet values) | Set to Chain 138 addresses: CCIP_ROUTER `0x8078...`, CCIPWETH9_BRIDGE `0x971c...`, CCIPWETH10_BRIDGE `0xe0E9...`, LINK `0xb772...` |
-| `smom-dbis-138/services/token-aggregation/src/api/routes/bridge.ts` | `WETH9_BRIDGE_138` hardcoded to deprecated `0x89dd...` | Set to `0x971cD9D156f193df8051E48043C476e53ECd4693` |
-| `explorer-monorepo/frontend/public/index.html` | WETH9 Bridge displayed as `0x89dd...` in two places | Set to `0x971c...` |
-| `scripts/add-weth-wrap-unwrap-utilities.sh` | Injected deprecated bridge address into HTML | Set to `0x971c...` |
-| Multiple `scripts/*.sh` | Fallback `CCIPWETH9_BRIDGE_CHAIN138:-0x89dd...` when env unset | Fallback changed to `0x971c...` (e.g. bridge-with-dynamic-gas.sh, monitor-bridge-transfers.sh, add-bridge-monitoring-to-explorer.sh, etc.) |
-| `scripts/create-integration-test-summary.sh` | Generated doc cited deprecated as fallback | Updated to canonical address and deprecated note |
-| `smom-dbis-138/scripts/verify-bridge-setup-checklist.sh` | Deprecated bridge, mainnet LINK/CCIP_ROUTER | Chain 138 addresses used for bridge, LINK, CCIP_ROUTER |
-| `scripts/update-blockscout-bridge-info.sh` | `WETH9_BRIDGE_138` hardcoded to deprecated | Set to `0x971c...` |
-| `smom-dbis-138/frontend-dapp/src/config/bridge.ts` | `WETH9_BRIDGE` hardcoded to deprecated | Set to `0x971c...` |
-| `smom-dbis-138/scripts/verify-bridge-prerequisites.sh` | `WETH9_BRIDGE` hardcoded to deprecated | Set to `0x971c...` |
-| `explorer-monorepo/scripts/*.sh` (multiple) | `WETH9_BRIDGE` or similar defaulting to deprecated | Default set to `0x971c...` |
-
-**Note:** Archive scripts under `scripts/archive/` and `.bak` files were not changed; they may still reference the deprecated address for historical runs. The string "Deprecated (do not use): \`0x89dd...\`" in `scripts/create-integration-test-summary.sh` is intentional documentation.
-
---
-
-## 8. Other Chains (reference only)
-
- **Ethereum Mainnet:** CCIP Sender at `0x105F8A15b819948a89153505762444Ee9f324684` has **empty bytecode** — not used on mainnet.  
- **ALL Mainnet (651940):** Token addresses in [ALL_MAINNET_TOKEN_ADDRESSES](ALL_MAINNET_TOKEN_ADDRESSES.md); not re-verified here.  
- **Terraform/env examples:** `env.mainnet.example`, `env.chain138.example` contain mainnet and Chain 138 bridge addresses for deployment context only.
-
---
-
-**Related:** [CONTRACT_NEXT_STEPS_AND_RECOMMENDATIONS_COMPLETE](CONTRACT_NEXT_STEPS_AND_RECOMMENDATIONS_COMPLETE.md) | [CONTRACT_ADDRESSES_REFERENCE](CONTRACT_ADDRESSES_REFERENCE.md) | [CONTRACTS_TO_DEPLOY](CONTRACTS_TO_DEPLOY.md) | [CHAIN138_TOKEN_ADDRESSES](CHAIN138_TOKEN_ADDRESSES.md) | [CONTRACT_DEPLOYMENT_RUNBOOK](../03-deployment/CONTRACT_DEPLOYMENT_RUNBOOK.md) | [BLOCKSCOUT_VERIFICATION_GUIDE](../08-monitoring/BLOCKSCOUT_VERIFICATION_GUIDE.md)
-
---
-
-**Document change log:** 2026-02-11 — Added §7 Inconsistencies Resolved; all addresses aligned with CONTRACT_ADDRESSES_REFERENCE and deprecated bridge removed from defaults.
--- a/docs/11-references/CONTRACT_NEXT_STEPS_LIST.md
+++ b/docs/11-references/CONTRACT_NEXT_STEPS_LIST.md
@@ -8,18 +8,19 @@

 | # | Task | Type | Status |
 |---|------|------|--------|
-| 1 | On-chain check (36 addresses) | Operator | Run `./scripts/verify/check-contracts-on-chain-138.sh` from host with RPC |
-| 2 | Blockscout source verification | Operator | Run from host that can reach Blockscout |
-| 3 | Reconcile .env | Repo | Done 2026-02-11 |
-| 4 | Multicall vs Oracle at 0x99b3... | Operator | Confirm on explorer; document in CONTRACT_ADDRESSES_REFERENCE |
-| 5 | Deploy phased core (138) | Optional | Done 2026-02-11 |
-| 6 | Deploy trustless bridge | Optional | When needed; script/bridge/trustless/ |
-| 7 | Mainnet/multichain deployments | Optional | DeployAll or chain scripts; document addresses |
-| 8 | CREATE2 / deterministic core | Pending | When needed |
-| 9 | Vault / reserve / Keeper | Pending | When needed |
-| 10 | Dodo / swap integration | Pending | When needed |
-| 11 | eMoney / smart accounts | Pending | When needed |
-| 12 | PaymentChannelManager / GenericStateChannelManager | Pending | When needed; see PAYMENT_CHANNELS_DEPLOYMENT.md |
+| 1 | **Chain 138 next steps (all in one)** | Operator | `./scripts/deployment/run-all-next-steps-chain138.sh` — preflight → mirror+pool → register c* as GRU → verify; use `--skip-mirror` if mirror exists. |
+| 2 | On-chain check (38 addresses) | Operator | Run `./scripts/verify/check-contracts-on-chain-138.sh` from host with RPC |
+| 3 | Blockscout source verification | Operator | Run from host that can reach Blockscout |
+| 4 | Reconcile .env | Repo | Done 2026-02-11 |
+| 5 | Multicall vs Oracle at 0x99b3... | Operator | Confirm on explorer; document in CONTRACT_ADDRESSES_REFERENCE |
+| 6 | Deploy phased core (138) | Optional | Done 2026-02-11 |
+| 7 | Deploy trustless bridge | Optional | When needed; script/bridge/trustless/ |
+| 8 | Mainnet/multichain deployments | Optional | DeployAll or chain scripts; document addresses |
+| 9 | CREATE2 / deterministic core | Pending | When needed |
+| 10 | Vault / reserve / Keeper | Pending | When needed |
+| 11 | Dodo / swap integration | Pending | When needed |
+| 12 | eMoney / smart accounts | Pending | When needed |
+| 13 | PaymentChannelManager / GenericStateChannelManager | Pending | When needed; see PAYMENT_CHANNELS_DEPLOYMENT.md |

 ---

--- a/docs/11-references/CW_TOKENS_AND_NETWORKS.md
+++ b/docs/11-references/CW_TOKENS_AND_NETWORKS.md
@@ -0,0 +1,78 @@
+# cW* Tokens and Networks
+
+**Purpose:** Single reference for all compliant wrapped tokens (cW*) and the networks where they are defined or deployed.
+
+**Source of truth:** `config/token-mapping-multichain.json` (`cToCwSymbolMapping`), `smom-dbis-138/script/deploy/DeployCWTokens.s.sol`, and `smom-dbis-138/.env` (for recorded addresses).
+
+---
+
+## 1. All cW* tokens and deployability
+
+All 12 cW* tokens are deployable via `DeployCWTokens.s.sol` (env flags `DEPLOY_CWUSDT=1`, `DEPLOY_CWEURC=1`, etc.; default all 1). Set `DEPLOY_*=0` to skip a token.
+
+| cW* Token | Deploy script | Networks deployable (script) | Deployed on (addresses in .env) |
+|-----------|---------------|------------------------------|----------------------------------|
+| **cWUSDT** | Yes | 1, 25, 56, 137, 100, 43114, 8453, 42161, 10 | All 9 chains (Mainnet, Cronos, BSC, Polygon, Gnosis, Avalanche, Base, Arbitrum, Optimism) |
+| **cWUSDC** | Yes | 1, 25, 56, 137, 100, 43114, 8453, 42161, 10 | All 9 chains |
+| **cWEURC** | Yes | 1, 25, 56, 137, 100, 43114, 8453, 42161, 10 | BSC, Polygon, Gnosis, Avalanche, Base, Optimism (Mainnet/Cronos/Arbitrum: deploy failed nonce/gas) |
+| **cWEURT** | Yes | Same | Same as cWEURC |
+| **cWGBPC** | Yes | Same | Same |
+| **cWGBPT** | Yes | Same | Same |
+| **cWAUDC** | Yes | Same | Same |
+| **cWJPYC** | Yes | Same | Same |
+| **cWCHFC** | Yes | Same | Same |
+| **cWCADC** | Yes | Same | Same |
+| **cWXAUC** | Yes | Same | Same |
+| **cWXAUT** | Yes | Same | Same |
+
+---
+
+## 2. Network names (chain ID)
+
+| Chain ID | Network name |
+|----------|--------------|
+| 1 | Ethereum Mainnet |
+| 10 | Optimism |
+| 25 | Cronos |
+| 56 | BSC (BNB Chain) |
+| 100 | Gnosis Chain |
+| 137 | Polygon |
+| 43114 | Avalanche C-Chain |
+| 8453 | Base |
+| 42161 | Arbitrum One |
+
+Chains **42220** (Celo) and **1111** (Wemix) are in the token-mapping file for c*→cW* mapping but are not in the current `deploy-tokens-and-weth-all-chains-skip-canonical.sh` chain list for cW* deployment. **651940** (ALL Mainnet) is env-validation only; no cW* deploy from this repo.
+
+---
+
+## 2.1 Bridge support status
+
+| Chain(s) | Bridge / receiver | Bridge code mints cW*? | Notes |
+|----------|-------------------|------------------------|-------|
+| All (1, 25, 56, 137, 100, 43114, 8453, 42161, 10) | CCIPRelayBridge (Mainnet), CCIPWETH9_BRIDGE_* (others) | **No** | Current suite is WETH-only; `ccipReceive` only transfers the received token. Granting MINTER/BURNER to these addresses allows DeployCWTokens to run but does not enable cross-chain mint until the receiver is extended or a dedicated cW* receiver (e.g. TwoWayTokenBridgeL2) is deployed. See [CW_BRIDGE_APPROACH.md](../07-ccip/CW_BRIDGE_APPROACH.md) and [CW_BRIDGE_TASK_LIST.md](CW_BRIDGE_TASK_LIST.md). |
+| After Phase B or C | Extended bridge or TwoWayTokenBridgeL2 / CCIPReceiverCW | **Yes** (when implemented) | Per [CW_BRIDGE_APPROACH.md](../07-ccip/CW_BRIDGE_APPROACH.md), Option 2 (dedicated receiver) is chosen; deploy TwoWayTokenBridgeL2 or equivalent per chain and point `CW_BRIDGE_<CHAIN>` to it for cW* mint/burn. |
+
+---
+
+## 3. How to deploy cWUSDT / cWUSDC
+
+1. **Bridge addresses:** `CW_BRIDGE_ADDRESS` is left as default (zero). Per-chain `CW_BRIDGE_<CHAIN>` are set in `smom-dbis-138/.env` from the deployed bridge suite (Mainnet: CCIPRelayBridge; other chains: CCIPWETH9_BRIDGE_*). That contract receives MINTER_ROLE and BURNER_ROLE when deploying cW*; extend it for cW* support if needed.
+2. Run with `--deploy-cw`:
+   ```bash
+   cd smom-dbis-138 && ./scripts/deployment/deploy-tokens-and-weth-all-chains-skip-canonical.sh --deploy-cw
+   ```
+   Or deploy to a single chain (e.g. BSC):
+   ```bash
+   CW_BRIDGE_ADDRESS=0x... forge script script/deploy/DeployCWTokens.s.sol:DeployCWTokens \
+     --rpc-url "$BSC_RPC_URL" --chain-id 56 --broadcast --private-key "$PRIVATE_KEY" --legacy
+   ```
+3. Set `CWUSDT_<CHAIN>`, `CWUSDC_<CHAIN>` in `.env` from the script output, and update `config/token-mapping-multichain.json` `addressTo` for the corresponding `Compliant_USDT_cW` / `Compliant_USDC_cW` entries.
+
+---
+
+## 4. References
+
+- [C_TO_CW_MAPPER_MAPPING.md](../04-configuration/C_TO_CW_MAPPER_MAPPING.md) — c*→cW* symbol and address mapping for the mapper.
+- [TOKENS_DEPLOYER_DEPLOYED_ON_OTHER_CHAINS.md](TOKENS_DEPLOYER_DEPLOYED_ON_OTHER_CHAINS.md) — Deployer tokens on other chains; cW* deploy path.
+- [config/token-mapping-multichain.json](../../config/token-mapping-multichain.json) — `cToCwSymbolMapping` and per-pair `_cW` tokens.
+- **[CW_BRIDGE_TASK_LIST.md](../00-meta/CW_BRIDGE_TASK_LIST.md)** — Detailed task list: note review, checks performed, and phases (bridge extension vs dedicated receiver, deploy cW*, wire config, E2E).
--- a/docs/11-references/DEPLOYED_COINS_TOKENS_AND_NETWORKS.md
+++ b/docs/11-references/DEPLOYED_COINS_TOKENS_AND_NETWORKS.md
@@ -0,0 +1,132 @@
+# Deployed Coins, Tokens, and Networks — Master Inventory
+
+**Last Updated:** 2026-02-28  
+**Status:** Active Documentation
+
+---
+
+## Token categories (canonical)
+
+Tokens are grouped into four **canonical categories**. Full definitions and symbol lists: [TOKEN_CATEGORIES_CANONICAL.md](TOKEN_CATEGORIES_CANONICAL.md). **Remaining token deployments:** [TOKEN_CONTRACT_DEPLOYMENTS_REMAINING.md](TOKEN_CONTRACT_DEPLOYMENTS_REMAINING.md).
+
+| # | Category | Scope | Examples |
+|---|----------|--------|----------|
+| 1 | **Canonical 138 Compliant** | Chain 138 | Native ETH, WETH, WETH10, LINK, cUSDT, cUSDC, cEURT, cEURC, cGBPT, cGBPC, cAUDT, cAUDC, cJPYT, cJPYC, cCHFT, cCHFC, cCADT, cCADC, cAUSDT |
+| 2 | **ALL Mainnet (Alltra)** | Chain 651940 | Native, AUSDT, USDT, USDC, WETH, WALL, ACADT |
+| 3 | **Compliant Wrapped (cW\*)** | Public blockchains (bridged from 138) | cWUSDT, cWUSDC, cWEURT, cWEURC, cWGBPT, cWGBPC, cWAUDT, cWAUDC, cWJPYT, cWJPYC, cWCHFT, cWCHFC, cWCADT, cWCADC, cWUSDW, cWEURW, cWGBPW, cWAUDW, cWJPYW, cWCHFW, cWCADW |
+| 4 | **D-WIN W Tokens** | Cronos (25) / 138 / 651940 | USDW, EURW, GBPW, AUDW, JPYW, CHFW, CADW |
+
+---
+
+## Networks (Chains)
+
+| Chain ID | Name | RPC | Explorer | Status |
+|----------|------|-----|----------|--------|
+| **138** | DeFi Oracle Meta Mainnet (DBIS) | https://rpc-http-pub.d-bis.org, https://rpc.d-bis.org, https://rpc.defi-oracle.io | https://explorer.d-bis.org | ✅ Primary |
+| **1** | Ethereum Mainnet | https://eth.llamarpc.com, https://rpc.ankr.com/eth | https://etherscan.io | ✅ Supported |
+| **651940** | ALL Mainnet (Alltra) | https://mainnet-rpc.alltra.global | https://alltra.global | ✅ Supported |
+| **25** | Cronos Mainnet | https://evm.cronos.org, https://cronos-rpc.publicnode.com | https://cronos.org/explorer | ✅ ISO-4217 W tokens |
+| **56** | BSC (BNB Chain) | https://bsc-dataseed.binance.org | https://bscscan.com | ✅ MetaMask |
+| **100** | Gnosis Chain | https://rpc.gnosischain.com | https://gnosisscan.io | ✅ MetaMask |
+| **137** | Polygon | https://polygon-rpc.com | https://polygonscan.com | ✅ MetaMask |
+| **10** | Optimism | https://mainnet.optimism.io | https://optimistic.etherscan.io | ✅ MetaMask |
+| **42161** | Arbitrum One | https://arb1.arbitrum.io/rpc | https://arbiscan.io | ✅ MetaMask |
+| **8453** | Base | https://mainnet.base.org | https://basescan.org | ✅ MetaMask |
+| **43114** | Avalanche C-Chain | https://api.avax.network/ext/bc/C/rpc | https://snowtrace.io | ✅ MetaMask |
+| **42220** | Celo | https://forno.celo.org | https://celoscan.io | ✅ MetaMask |
+| **1111** | Wemix | https://api.wemix.com | https://scan.wemix.com | ✅ MetaMask |
+
+**Config sources:**
+- `explorer-monorepo/backend/api/rest/config/metamask/DUAL_CHAIN_NETWORKS.json` — MetaMask wallet_addEthereumChain (all 13 chains)
+- `token-lists/chainlists/chain-138.json` — Chainlist PR
+- `cross-chain-pmm-lps/config/chains.json` — PMM/LP hub chains
+
+---
+
+## Tokens by Chain
+
+### Chain 138 (DeFi Oracle Meta Mainnet)
+
+| Symbol | Name | Address | Decimals | Tags | Source |
+|--------|------|---------|----------|------|--------|
+| ETH-USD | ETH/USD Price Feed | `0x3304b747E565a97ec8AC220b0B6A1f6ffDB837e6` | 8 | oracle, pricefeed | token list |
+| WETH | Wrapped Ether | `0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2` | 18 | defi, wrapped | Genesis |
+| WETH10 | Wrapped Ether v10 | `0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9F` | 18 | defi, wrapped | Genesis |
+| LINK | Chainlink Token | `0xb7721dD53A8c629d9f1Ba31a5819AFe250002b03` | 18 | defi, oracle, ccip | Deployed |
+| cUSDT | Compliant Tether USD | `0x93E66202A11B1772E55407B32B44e5Cd8eda7f22` | 6 | stablecoin, defi, compliant | Deployed |
+| cUSDC | Compliant USD Coin | `0xf22258f57794CC8E06237084b353Ab30fFfa640b` | 6 | stablecoin, defi, compliant | Deployed |
+
+**Token Registry:** `0x91Efe92229dbf7C5B38D422621300956B55870Fa`
+
+### Chain 1 (Ethereum Mainnet)
+
+| Symbol | Name | Address | Decimals |
+|--------|------|---------|----------|
+| WETH | Wrapped Ether | `0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2` | 18 |
+| USDT | Tether USD | `0xdAC17F958D2ee523a2206206994597C13D831ec7` | 6 |
+| USDC | USD Coin | `0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48` | 6 |
+| DAI | Dai Stablecoin | `0x6B175474E89094C44Da98b954EedeAC495271d0F` | 18 |
+| ETH-USD | ETH/USD Price Feed | `0x5f4eC3Df9cbd43714FE2740f5E3616155c5b8419` | 8 |
+
+### Chain 25 (Cronos) — ISO-4217 W Tokens
+
+| Symbol | Name | Address | Decimals |
+|--------|------|---------|----------|
+| WETH9 | Wrapped Ether (WETH9) | `0x99B3511A2d315A497C8112C1fdd8D508d4B1E506` | 18 |
+| WETH10 | Wrapped Ether v10 | `0x3304b747E565a97ec8AC220b0B6A1f6ffDB837e6` | 18 |
+| LINK | Chainlink Token | `0x8c80A01F461f297Df7F9DA3A4f740D7297C8Ac85` | 18 |
+| USDW | USD W Token | `0x948690147D2e50ffe50C5d38C14125aD6a9FA036` | 2 |
+| EURW | EUR W Token | `0x58a8D8F78F1B65c06dAd7542eC46b299629A60dd` | 2 |
+| GBPW | GBP W Token | `0xFb4B6Cc81211F7d886950158294A44C312abCA29` | 2 |
+| AUDW | AUD W Token | `0xf9f5D0ACD71C76F9476F10B3F3d3E201F0883C68` | 2 |
+| JPYW | JPY W Token | `0xeE17bB0322383fecCA2784fbE2d4CD7d02b1905B` | 2 |
+| CHFW | CHF W Token | `0xc9750828124D4c10e7a6f4B655cA8487bD3842EB` | 2 |
+| CADW | CAD W Token | `0x328Cd365Bb35524297E68ED28c6fF2C9557d1363` | 2 |
+
+### Chain 651940 (ALL Mainnet)
+
+| Symbol | Name | Address | Decimals |
+|--------|------|---------|----------|
+| AUSDT | Alltra USD Token | `0x015B1897Ed5279930bC2Be46F661894d219292A6` | 18 |
+| USDT | AUSDT | `0x66D8Efa0AF63B0e84eb1Dd72bf00f00cd1e2234e` | 18 |
+| USDC | AUSDC | `0xa95EeD79f84E6A0151eaEb9d441F9Ffd50e8e881` | 18 |
+| WETH | Wrapped Ether | `0x798F6762BB40d6801A593459d08F890603D3979C` | 18 |
+| WALL | Wrapped Alltra | `0x2da2b8f961F161ab6320acB3377e2e844a3C3ce4` | 18 |
+| ACADT | Alltra CAD (Tether-style) | Deploy / env | TBD |
+
+---
+
+## File Locations
+
+| Purpose | Path |
+|---------|------|
+| **Chain 138 token list** | `token-lists/lists/dbis-138.tokenlist.json` |
+| **Cronos token list** | `token-lists/lists/cronos.tokenlist.json` |
+| **Multi-chain token list** | `explorer-monorepo/backend/api/rest/config/metamask/DUAL_CHAIN_TOKEN_LIST.tokenlist.json` |
+| **Network config** | `explorer-monorepo/backend/api/rest/config/metamask/DUAL_CHAIN_NETWORKS.json` |
+| **Chain 138 chainlist** | `token-lists/chainlists/chain-138.json` |
+| **Canonical tokens (token-aggregation)** | `smom-dbis-138/services/token-aggregation/src/config/canonical-tokens.ts` |
+| **IPFS logo manifest** | `docs/04-configuration/coingecko/logos/ipfs-manifest.json` |
+| **MetaMask config** | `metamask-integration/config/token-list.json` |
+| **PMM/LP chains** | `cross-chain-pmm-lps/config/chains.json` |
+
+---
+
+## Explorer API Endpoints
+
+| Endpoint | Purpose | Requires |
+|----------|---------|----------|
+| `https://explorer.d-bis.org/api/config/token-list` | Uniswap-format token list (MetaMask) | Nginx + config files in /var/www/html/config/ |
+| `https://explorer.d-bis.org/api/config/networks` | wallet_addEthereumChain params | Same |
+| `https://explorer.d-bis.org/api/v1/report/token-list?chainId=138` | Token-aggregation report API | token-aggregation on port 3000 |
+| `https://explorer.d-bis.org/api/v2/stats` | Blockscout stats | Blockscout on port 4000 |
+
+**Deploy config:** `./explorer-monorepo/scripts/deploy-explorer-config-to-vmid5000.sh`
+
+---
+
+## References
+
+- [CHAIN138_TOKEN_ADDRESSES.md](CHAIN138_TOKEN_ADDRESSES.md)
+- [CONTRACT_ADDRESSES_REFERENCE.md](CONTRACT_ADDRESSES_REFERENCE.md)
+- [LIQUIDITY_POOLS_MASTER_MAP.md](LIQUIDITY_POOLS_MASTER_MAP.md)
--- a/docs/11-references/DEPLOYER_WALLET_FUNDING_PLAN_PMM_POOLS.md
+++ b/docs/11-references/DEPLOYER_WALLET_FUNDING_PLAN_PMM_POOLS.md
@@ -0,0 +1,153 @@
+# Deployer Wallet — Chain 138 Balances, Funding Plan (PMM Pools), and Tokens on All Networks
+
+**Last Updated:** 2026-02-28  
+**Purpose:** Check deployer balances on ChainID 138, use **half** of balances for PMM liquidity pool funding; list all coins/tokens deployed by or associated with the deployer address on all networks.
+
+---
+
+## 1. Deployer address
+
+| Item | Value |
+|------|--------|
+| **Address** | `0x4A666F96fC8764181194447A7dFdb7d471b301C8` |
+| **Chain 138 Explorer** | https://explorer.d-bis.org/address/0x4A666F96fC8764181194447A7dFdb7d471b301C8 |
+| **Other chains (e.g. Mainnet)** | https://blockscan.com/address/0x4A666F96fC8764181194447A7dFdb7d471b301C8 |
+
+This address is the **documented deployer/admin** for Chain 138 (contracts, pools, and operations). The same address may hold assets or be used for deployments on other networks.
+
+---
+
+## 2. Check deployer balances on Chain 138
+
+**Script (recommended):** Run from repo root with `RPC_URL_138` set (e.g. `https://rpc-core.d-bis.org` or `http://192.168.11.211:8545`):
+
+```bash
+RPC_URL_138=https://rpc-core.d-bis.org ./scripts/deployment/check-deployer-balance-chain138-and-funding-plan.sh
+```
+
+The script:
+
+- Fetches **native ETH** and **ERC-20** balances for: **WETH**, **WETH10**, **LINK**, **cUSDT**, **cUSDC** (addresses from [CHAIN138_TOKEN_ADDRESSES](CHAIN138_TOKEN_ADDRESSES.md)).
+- Prints **half** of each balance for use as the liquidity funding plan.
+- Outputs suggested `ADD_LIQUIDITY_*` env vars for [AddLiquidityPMMPoolsChain138](../../smom-dbis-138/script/dex/AddLiquidityPMMPoolsChain138.s.sol).
+
+**Alternative:** Use [check-deployer-balance-blockscout-vs-rpc.sh](../../scripts/verify/check-deployer-balance-blockscout-vs-rpc.sh) for native balance only; or [list-deployer-tokens-all-networks.sh](../../smom-dbis-138/scripts/deployment/list-deployer-tokens-all-networks.sh) from `smom-dbis-138/` for all networks. The list script uses **fallback public RPCs** when env vars are unset, so it always prints every token line for Chain 138, Ethereum, ALL Mainnet, Cronos, Polygon, Base, Optimism, BSC, Avalanche, and Arbitrum. Use `PRIVATE_KEY` in .env to derive the deployer address, or set `DEPLOYER_ADDRESS=0x4A666F96fC8764181194447A7dFdb7d471b301C8` for read-only.
+
+---
+
+## 3. Funding plan: use half of balances for PMM liquidity pools
+
+**Rule:** Use **50%** of each deployer balance (native ETH and each ERC-20 above) for the **PMM liquidity pool funding plan**. The other 50% remains as reserve (gas, other operations).
+
+**Pools (Chain 138):**
+
+| Pool | Base | Quote | Pool address |
+|------|------|--------|--------------|
+| cUSDT / cUSDC | cUSDT | cUSDC | `0x9fcB06Aa1FD5215DC0E91Fd098aeff4B62fEa5C8` |
+| cUSDT / USDT  | cUSDT | USDT (official) | `0xa3Ee6091696B28e5497b6F491fA1e99047250c59` |
+| cUSDC / USDC  | cUSDC | USDC (official) | `0x90bd9Bf18Daa26Af3e814ea224032d015db58Ea5` |
+
+**Allocation (half of deployer balances):**
+
+- **cUSDT:** Half of deployer cUSDT → split between pool **cUSDT/cUSDC** (base) and pool **cUSDT/USDT** (base).
+- **cUSDC:** Half of deployer cUSDC → split between pool **cUSDT/cUSDC** (quote) and pool **cUSDC/USDC** (base).
+- **USDT (official), USDC (official):** If deployer holds them, use half for pool **cUSDT/USDT** (quote) and **cUSDC/USDC** (quote) respectively.
+- **Native ETH:** Keep half for gas; optionally wrap half to WETH for future WETH-denominated pools.
+- **WETH / WETH10 / LINK:** Reserve half for gas/CCIP or other use unless a pool is added that uses them.
+
+**Run liquidity add (after setting env from script output):**
+
+```bash
+cd smom-dbis-138
+# Set POOL_*, ADD_LIQUIDITY_BASE_AMOUNT, ADD_LIQUIDITY_QUOTE_AMOUNT (and per-pool vars if needed)
+forge script script/dex/AddLiquidityPMMPoolsChain138.s.sol:AddLiquidityPMMPoolsChain138 \
+  --rpc-url "$RPC_URL_138" --broadcast --private-key "$PRIVATE_KEY"
+```
+
+See [LIQUIDITY_POOL_CONTROLS_RUNBOOK](../03-deployment/LIQUIDITY_POOL_CONTROLS_RUNBOOK.md) and [NEXT_STEPS_PMM_FULL_PARITY_AND_ALL_POOLS](../03-deployment/NEXT_STEPS_PMM_FULL_PARITY_AND_ALL_POOLS.md).
+
+---
+
+## 4. All coins/tokens deployed by or associated with the deployer (all networks)
+
+Token **categories** are defined in [TOKEN_CATEGORIES_CANONICAL](TOKEN_CATEGORIES_CANONICAL.md): (1) Canonical 138 Compliant, (2) ALL Mainnet, (3) Compliant Wrapped cW*, (4) D-WIN W Tokens.
+
+Below: **tokens and coins** on each network where the deployer is the **documented admin** (Chain 138) or where the **same address** is used for deployments/holdings. Addresses are the **contract addresses** of the tokens on that chain (not the deployer).
+
+### Chain 138 (DeFi Oracle Meta Mainnet) — Category 1: Canonical 138 Compliant
+
+| Symbol | Name | Contract address | Decimals | Notes |
+|--------|------|------------------|----------|--------|
+| ETH | Native | — | 18 | Gas token |
+| WETH | Wrapped Ether | `0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2` | 18 | Genesis |
+| WETH10 | Wrapped Ether v10 | `0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9f` | 18 | Genesis |
+| LINK | Chainlink Token | `0xb7721dD53A8c629d9f1Ba31a5819AFe250002b03` | 18 | CCIP fees |
+| cUSDT | Compliant Tether USD | `0x93E66202A11B1772E55407B32B44e5Cd8eda7f22` | 6 | Deployed |
+| cUSDC | Compliant USD Coin | `0xf22258f57794CC8E06237084b353Ab30fFfa640b` | 6 | Deployed |
+| cEURT, cEURC, cGBPT, cGBPC, cAUDT, cAUDC, cJPYT, cJPYC, cCHFT, cCHFC, cCADT, cCADC, cAUSDT | (Category 1 remainder) | Deploy / env | 6 | See [TOKEN_CATEGORIES_CANONICAL](TOKEN_CATEGORIES_CANONICAL.md) |
+| USDT (official) | Tether (Chain 138) | `0x15DF1D5BFDD8Aa4b380445D4e3E9B38d34283619` | — | Reference |
+
+### Chain 1 (Ethereum Mainnet)
+
+| Symbol | Name | Contract address | Decimals |
+|--------|------|------------------|----------|
+| ETH | Native | — | 18 |
+| WETH | Wrapped Ether | `0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2` | 18 |
+| USDT | Tether USD | `0xdAC17F958D2ee523a2206206994597C13D831ec7` | 6 |
+| USDC | USD Coin | `0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48` | 6 |
+| DAI | Dai Stablecoin | `0x6B175474E89094C44Da98b954EedeAC495271d0F` | 18 |
+| LINK | Chainlink | `0x514910771AF9Ca656af840dff83E8264EcF986CA` | 18 |
+
+### Chain 651940 (ALL Mainnet / Alltra) — Category 2
+
+| Symbol | Name | Contract address | Decimals |
+|--------|------|------------------|----------|
+| AUSDT | Alltra USD Token | `0x015B1897Ed5279930bC2Be46F661894d219292A6` | 18 |
+| USDT | AUSDT (alt) | `0x66D8Efa0AF63B0e84eb1Dd72bf00f00cd1e2234e` | 18 |
+| USDC | AUSDC | `0xa95EeD79f84E6A0151eaEb9d441F9Ffd50e8e881` | 18 |
+| WETH | Wrapped Ether | `0x798F6762BB40d6801A593459d08F890603D3979C` | 18 |
+| WALL | Wrapped Alltra | `0x2da2b8f961F161ab6320acB3377e2e844a3C3ce4` | 18 |
+
+### Chain 25 (Cronos) — Category 4: D-WIN W Tokens
+
+| Symbol | Name | Contract address | Decimals |
+|--------|------|------------------|----------|
+| WETH9 | Wrapped Ether | `0x99B3511A2d315A497C8112C1fdd8D508d4B1E506` | 18 |
+| WETH10 | Wrapped Ether v10 | `0x3304b747E565a97ec8AC220b0B6A1f6ffDB837e6` | 18 |
+| LINK | Chainlink Token | `0x8c80A01F461f297Df7F9DA3A4f740D7297C8Ac85` | 18 |
+| USDW | USD W Token | `0x948690147D2e50ffe50C5d38C14125aD6a9FA036` | 2 |
+| EURW | EUR W Token | `0x58a8D8F78F1B65c06dAd7542eC46b299629A60dd` | 2 |
+| GBPW | GBP W Token | `0xFb4B6Cc81211F7d886950158294A44C312abCA29` | 2 |
+| AUDW | AUD W Token | `0xf9f5D0ACD71C76F9476F10B3F3d3E201F0883C68` | 2 |
+| JPYW | JPY W Token | `0xeE17bB0322383fecCA2784fbE2d4CD7d02b1905B` | 2 |
+| CHFW | CHF W Token | `0xc9750828124D4c10e7a6f4B655cA8487bD3842EB` | 2 |
+| CADW | CAD W Token | `0x328Cd365Bb35524297E68ED28c6fF2C9557d1363` | 2 |
+
+### Other supported chains (tokens from config / MetaMask)
+
+Tokens on these chains are documented in [DEPLOYED_COINS_TOKENS_AND_NETWORKS](DEPLOYED_COINS_TOKENS_AND_NETWORKS.md) and in token lists. The deployer address may hold or interact with tokens on:
+
+- **56** (BSC), **100** (Gnosis), **137** (Polygon), **10** (Optimism), **42161** (Arbitrum), **8453** (Base), **43114** (Avalanche), **42220** (Celo), **1111** (Wemix).
+
+To list **deployer holdings** on all networks (native + ERC-20), run from `smom-dbis-138/`:
+
+```bash
+cd smom-dbis-138 && ./scripts/deployment/list-deployer-tokens-all-networks.sh
+```
+
+The script **always lists** the tokens in the table below for each network. It uses fallback public RPCs when `RPC_URL_138`, `ETHEREUM_MAINNET_RPC`, `CHAIN_651940_RPC`, `CRONOS_RPC`, etc. are not set in `.env`. Set those in `.env` to use your own RPC endpoints. You need `PRIVATE_KEY` in `.env` to derive the deployer address, or set `DEPLOYER_ADDRESS=0x4A666F96fC8764181194447A7dFdb7d471b301C8` for read-only.
+
+---
+
+## 5. References
+
+| Document | Purpose |
+|----------|---------|
+| [TOKENS_AND_NETWORKS_MINTABLE_TO_DEPLOYER](TOKENS_AND_NETWORKS_MINTABLE_TO_DEPLOYER.md) | **All tokens and networks** where tokens can be minted to the deployer (Chain 138 + Cronos D-WIN; acquire elsewhere) |
+| [TOKENS_DEPLOYER_DEPLOYED_ON_OTHER_CHAINS](TOKENS_DEPLOYER_DEPLOYED_ON_OTHER_CHAINS.md) | **Tokens the deployer deployed** on all blockchains other than 138 (Cronos D-WIN W; WETH9/WETH10 on L2s) |
+| [CHAIN138_TOKEN_ADDRESSES](CHAIN138_TOKEN_ADDRESSES.md) | Token addresses Chain 138 |
+| [LIQUIDITY_POOLS_MASTER_MAP](LIQUIDITY_POOLS_MASTER_MAP.md) | PMM pool addresses |
+| [ADDRESS_MATRIX_AND_STATUS](ADDRESS_MATRIX_AND_STATUS.md) | Contract matrix |
+| [DEPLOYED_COINS_TOKENS_AND_NETWORKS](DEPLOYED_COINS_TOKENS_AND_NETWORKS.md) | Networks and tokens by chain |
+| [CONTRACT_ADDRESSES_REFERENCE](CONTRACT_ADDRESSES_REFERENCE.md) | Canonical contract list |
+| [LIQUIDITY_POOL_CONTROLS_RUNBOOK](../03-deployment/LIQUIDITY_POOL_CONTROLS_RUNBOOK.md) | How to add liquidity |
--- a/docs/11-references/DEX_AND_CROSS_CHAIN_CONTRACTS_NEEDED.md
+++ b/docs/11-references/DEX_AND_CROSS_CHAIN_CONTRACTS_NEEDED.md
@@ -2,7 +2,7 @@

 **Purpose:** Answer what contracts (and code) are needed beyond current deployments for full Dodo PMM, Uniswap, cross-chain liquidity pools, multi-token multi-chain routing, and atomic swaps. Also clarify TransactionMirror deployment status.

-**Related:** [CONTRACT_INVENTORY_AND_VERIFICATION](CONTRACT_INVENTORY_AND_VERIFICATION.md) | [CONTRACTS_TO_DEPLOY](CONTRACTS_TO_DEPLOY.md) | [CONTRACT_DEPLOYMENT_RUNBOOK](../03-deployment/CONTRACT_DEPLOYMENT_RUNBOOK.md) | [PLACEHOLDERS_AND_TBD](../PLACEHOLDERS_AND_TBD.md) | [OPERATOR_OPTIONAL_CHECKLIST](OPERATOR_OPTIONAL_CHECKLIST.md) §6
+**Related:** [ADDRESS_MATRIX_AND_STATUS](ADDRESS_MATRIX_AND_STATUS.md) | [CONTRACTS_TO_DEPLOY](CONTRACTS_TO_DEPLOY.md) | [CONTRACT_DEPLOYMENT_RUNBOOK](../03-deployment/CONTRACT_DEPLOYMENT_RUNBOOK.md) | [PLACEHOLDERS_AND_TBD](../PLACEHOLDERS_AND_TBD.md) | [OPERATOR_OPTIONAL_CHECKLIST](OPERATOR_OPTIONAL_CHECKLIST.md) §6

 ---

@@ -19,7 +19,7 @@

 ## 2. Currently Deployed (Relevant to DEX / Routing / Cross-Chain)

- **Chain 138:** CCIP bridges (CCIPWETH9/10), UniversalCCIPBridge, BridgeOrchestrator, AlltraAdapter, Lockbox138 (trustless), PaymentChannelManager, GenericStateChannelManager, AddressMapper, MirrorManager, Vault/Reserve system, MerchantSettlementRegistry, WithdrawalEscrow, phased core, CREATE2 deterministic set. See [CONTRACT_ADDRESSES_REFERENCE](CONTRACT_ADDRESSES_REFERENCE.md) and [CONTRACT_INVENTORY_AND_VERIFICATION](CONTRACT_INVENTORY_AND_VERIFICATION.md).
+- **Chain 138:** CCIP bridges (CCIPWETH9/10), UniversalCCIPBridge, BridgeOrchestrator, AlltraAdapter, Lockbox138 (trustless), PaymentChannelManager, GenericStateChannelManager, AddressMapper, MirrorManager, Vault/Reserve system, MerchantSettlementRegistry, WithdrawalEscrow, phased core, CREATE2 deterministic set, **DODOPMMIntegration** (`0x79cdbaFBaA0FdF9F55D26F360F54cddE5c743F7D`, Mock DVM — pools not yet created). See [CONTRACT_ADDRESSES_REFERENCE](CONTRACT_ADDRESSES_REFERENCE.md) and [ADDRESS_MATRIX_AND_STATUS](ADDRESS_MATRIX_AND_STATUS.md).
 - **alltra-lifi-settlement:** MerchantSettlementRegistry, WithdrawalEscrow (Chain 138).

 ---
@@ -30,7 +30,7 @@

 | Item | Location | Status | What’s needed |
 |------|----------|--------|----------------|
-| **DODOPMMIntegration** | `smom-dbis-138/contracts/dex/DODOPMMIntegration.sol` | Exists; not deployed | Deploy via `script/deploy/dex/DeployDODOPMMIntegration.s.sol` when DODO is integrated. Set DODO-related env (e.g. pool manager) in `smom-dbis-138/.env` per .env.example. |
+| **DODOPMMIntegration** | `smom-dbis-138/contracts/dex/DODOPMMIntegration.sol` | **Deployed** (Chain 138: `0x79cdbaFBaA0FdF9F55D26F360F54cddE5c743F7D`, Mock DVM) | Create pools via `createCUSDTCUSDCPool`, `createCUSDTUSDTPool`, `createCUSDCUSDCPool`; add liquidity. See [PMM_DEX_ROUTING_STATUS](PMM_DEX_ROUTING_STATUS.md), [DODO_PMM_INTEGRATION](../../smom-dbis-138/docs/integration/DODO_PMM_INTEGRATION.md). |
 | **DODOPMMProvider** | `smom-dbis-138/contracts/liquidity/providers/DODOPMMProvider.sol` | Placeholder | Implement oracle-driven `optimizePoolParameters` (or document flow); complete when DODO is integrated. See [NOT_CHANGED_BY_DESIGN_ACTIONABLE_STEPS](../00-meta/NOT_CHANGED_BY_DESIGN_ACTIONABLE_STEPS.md) §3. |
 | **Test** | `test/dex/DODOPMMIntegration.t.sol.bak` | Renamed to .bak | Restore/fix and re-enable when DODO integration is active (mockCall ambiguity was reason for .bak). |

@@ -55,7 +55,7 @@ Lockbox138 is deployed on Chain 138. The rest of the trustless stack is **not**
 | **SwapBridgeSwapCoordinator** / **BridgeSwapCoordinator** | `DeploySwapBridgeSwapCoordinator.s.sol`, etc. | Coordinates swap + bridge for atomic flows |
 | **MULTISIG** | (config) | Admin / relayer multisig |

-See [CONTRACT_INVENTORY_AND_VERIFICATION](CONTRACT_INVENTORY_AND_VERIFICATION.md) §4: “INBOX_ETH, BOND_MANAGER, CHALLENGE_MANAGER, LIQUIDITY_POOL, SWAP_ROUTER, BRIDGE_SWAP_COORDINATOR, MULTISIG — still placeholders in config when needed.”
+See [ADDRESS_MATRIX_AND_STATUS](ADDRESS_MATRIX_AND_STATUS.md) §4: “INBOX_ETH, BOND_MANAGER, CHALLENGE_MANAGER, LIQUIDITY_POOL, SWAP_ROUTER, BRIDGE_SWAP_COORDINATOR, MULTISIG — still placeholders in config when needed.”

 ### 3.4 Multi-Token Multi-Chain Routing (Off-Chain / Services)

@@ -80,7 +80,7 @@ See [CONTRACT_INVENTORY_AND_VERIFICATION](CONTRACT_INVENTORY_AND_VERIFICATION.md
 |------------|----------|--------------|
 | **Cross-chain bridge (CCIP)** | CCIP WETH9/10, UniversalCCIPBridge, AlltraAdapter | — |
 | **TransactionMirror** | Mainnet (0x4CF42...); optional on 138 | Chain 138: run deploy script if needed; Mainnet: confirm Etherscan verification |
-| **Dodo PMM liquidity** | — | Deploy DODOPMMIntegration; implement DODOPMMProvider; env for DODO |
+| **Dodo PMM liquidity** | DODOPMMIntegration deployed (Mock DVM); pools not created | Create PMM pools; add liquidity; deploy DODOPMMProvider and register pools |
 | **Uniswap/Balancer swaps** | — | Pools on 138/651940; deploy EnhancedSwapRouter with quoter/poolId; implement uniswap.service when pools exist |
 | **Full trustless atomic swap** | Lockbox138 | InboxETH, BondManager, ChallengeManager, LiquidityPoolETH, SwapRouter, BridgeSwapCoordinator, MULTISIG |
 | **Multi-chain routing** | LiFi (and config) | Jumper API when supported; Curve/Uniswap stubs when pools exist; quote service Fabric chainId |
--- a/docs/11-references/GAPS_FILLED_2026-02-27.md
+++ b/docs/11-references/GAPS_FILLED_2026-02-27.md
@@ -0,0 +1,63 @@
+# Gaps Filled — 2026-02-27
+
+**Purpose:** Summary of gaps filled so that pools are accessible via API and MCP, pool matrix is complete, and docs are consistent.
+
+---
+
+## 1. Token-aggregation API — cW* chains
+
+- **Gap:** API could not index cW* edge pools on chains 1, 10, 56, 100, 137 (dex-factories and chains only had 138 and 651940).
+- **Filled:**
+  - **chains.ts:** Added chain configs for 1, 10, 56, 100, 137 (name, rpcUrl, explorerUrl, nativeCurrency, blockTime, confirmations) with env-driven RPC (`CHAIN_*_RPC_URL`).
+  - **dex-factories.ts:** Added DEX_FACTORIES entries for chainIds 1, 10, 56, 100, 137 with env-driven DODO config (`CHAIN_*_DODO_PMM_INTEGRATION` or `CHAIN_*_DODO_POOL_MANAGER`, `CHAIN_*_DODO_VENDING_MACHINE`, `CHAIN_*_DODO_START_BLOCK`).
+- **Result:** When operators set the corresponding env vars and run the indexer for those chains, cW* DODO/pools can be indexed and exposed via the API.
+
+---
+
+## 2. MCP — Old MockDVMPool (Chain 138) without getOraclePrice / _K_ / _LP_FEE_RATE_
+
+- **Gap:** Pools created from an existing MockDVMFactory only had `getMidPrice` and `getVaultReserve`; `dodo.get_pool_state` with profile `dodo_pmm_v2_like` failed.
+- **Filled:**
+  - **pool_profiles.json:** Added profile `mock_dvm` with methods `get_mid_price` → `getMidPrice`, `get_vault_reserve` → `getVaultReserve` and defaults for oracle/k/fee.
+  - **server.py:** For profile `mock_dvm`, build ABI with getMidPrice and getVaultReserve only; set oracle_price = mid_price, k = 0.5, fee_rate = 0.03%.
+  - **server.py:** Added `_IDENTIFY_TUPLE_RETURNS` and `_probe_view_tuple` so `dodo.identify_pool_interface` can probe `getVaultReserve` (tuple return); added getVaultReserve to reserve_candidates in notes.
+  - **identify:** Build minimal_abi per candidate with correct output type (tuple for getVaultReserve); probe tuple-returning getters so `mock_dvm` is detected when only getMidPrice + getVaultReserve exist.
+- **Result:** Chain 138 pools from the **old** factory can use profile `mock_dvm` in the allowlist and work with `dodo.get_pool_state`. New pools (from updated MockDVMPool with getOraclePrice, _K_, _LP_FEE_RATE_) continue to use `dodo_pmm_v2_like`.
+
+---
+
+## 3. Cross-chain pool matrix — All 11 chains
+
+- **Gap:** pool-matrix.json had only 5 chains (1, 10, 56, 100, 137); chains.json listed 6 more (25, 42220, 43114, 42161, 8453, 1111) with no pool matrix.
+- **Filled:** Added to pool-matrix.json the 6 missing chains with the same structure (hubStable, poolsFirst, poolsOptional) so all 11 chains from chains.json have a defined pool matrix.
+- **Result:** Full design is 12 networks (138 + 11 cW*), 121 pools (10 on 138 + 111 cW*). See [POOLS_AND_NETWORKS_FULL_DESIGN.md](POOLS_AND_NETWORKS_FULL_DESIGN.md).
+
+---
+
+## 4. Docs — PMM_DEX_ROUTING_STATUS and POOLS_AND_NETWORKS_FULL_DESIGN
+
+- **Gap:** Line 116 in PMM_DEX_ROUTING_STATUS had outdated “Update docs” text (curly quotes prevented simple replace). POOLS_AND_NETWORKS_FULL_DESIGN still said 5 chains and 61 pools.
+- **Filled:**
+  - Replaced line 116 in PMM_DEX_ROUTING_STATUS with: “Add pool and DODOPMMProvider addresses to LIQUIDITY_POOLS_MASTER_MAP and CONTRACT_ADDRESSES_REFERENCE once created.”
+  - Updated POOLS_AND_NETWORKS_FULL_DESIGN: 11 networks and 111 pools in cW* matrix; 12 and 121 total; added table rows for chains 25, 42220, 43114, 42161, 8453, 1111; removed “Additional chains (pool matrix TBD)”; updated grand totals and summary.
+- **Result:** Docs match the current pool-matrix and full design.
+
+---
+
+## 5. Pool access summary
+
+- **API:** Chain 138 and cW* (1, 10, 56, 100, 137) are supported when the corresponding chain and DODO env vars are set. See [POOL_ACCESS_DASHBOARD_API_MCP.md](POOL_ACCESS_DASHBOARD_API_MCP.md).
+- **MCP:** Chain 138 works with allowlist + either `dodo_pmm_v2_like` (new MockDVMPool) or `mock_dvm` (old MockDVMPool). cW* per chain with allowlist + profile.
+- **Standard DODO dashboard:** Still does not support Chain 138 (custom chain + Mock DVM). cW* only if real DODO on a DODO-supported chain.
+
+---
+
+## References
+
+- [POOL_ACCESS_DASHBOARD_API_MCP.md](POOL_ACCESS_DASHBOARD_API_MCP.md)
+- [POOLS_AND_NETWORKS_FULL_DESIGN.md](POOLS_AND_NETWORKS_FULL_DESIGN.md)
+- [PMM_DEX_ROUTING_STATUS.md](PMM_DEX_ROUTING_STATUS.md)
+- [REQUIRED_FIXES_UPDATES_GAPS.md](REQUIRED_FIXES_UPDATES_GAPS.md)
+- `smom-dbis-138/services/token-aggregation/src/config/chains.ts`, `dex-factories.ts`
+- `ai-mcp-pmm-controller/config/pool_profiles.json`, `config/server.py`
+- `cross-chain-pmm-lps/config/pool-matrix.json`
--- a/docs/11-references/LINK_TOKEN_ADDRESSES_REFERENCE.md
+++ b/docs/11-references/LINK_TOKEN_ADDRESSES_REFERENCE.md
@@ -0,0 +1,49 @@
+# LINK Token Addresses — Reference
+
+**Purpose:** Single reference for the correct LINK token address per chain. Use these in `.env`, scripts, and UIs so CCIP fee payments and approvals use the proper contract.
+
+---
+
+## Chain 138 (Defi Oracle Meta Mainnet)
+
+| Variable | Address | Notes |
+|----------|---------|------|
+| `LINK_TOKEN` | `0xb7721dD53A8c629d9f1Ba31a5819AFe250002b03` | Deployed on Chain 138; used for CCIP fees |
+| `LINK_TOKEN_CHAIN138` | Same as above | Alias for scripts that distinguish by chain |
+| `CCIP_FEE_TOKEN` | Same as above | Fee token set on CCIPWETH9/CCIPWETH10 bridges |
+
+**Do not** use Ethereum Mainnet LINK (`0x514910771AF9Ca656af840dff83E8264EcF986CA`) when running scripts or contracts on Chain 138 — that address has no code on 138.
+
+**Source:** [CHAIN138_TOKEN_ADDRESSES.md](CHAIN138_TOKEN_ADDRESSES.md), [smom-dbis-138/docs/deployment/LINK_TOKEN_STATUS_FINAL.md](../../smom-dbis-138/docs/deployment/LINK_TOKEN_STATUS_FINAL.md).
+
+---
+
+## Ethereum Mainnet
+
+| Variable | Address | Notes |
+|----------|---------|------|
+| `MAINNET_LINK_TOKEN` / `CCIP_ETH_LINK_TOKEN` | `0x514910771AF9Ca656af840dff83E8264EcF986CA` | Canonical Chainlink LINK on Mainnet |
+
+---
+
+## Other chains (CCIP)
+
+Use [Chainlink CCIP Supported Networks](https://docs.chain.link/ccip/supported-networks) for official LINK addresses. In this repo, per-chain env vars follow the pattern `CCIP_<CHAIN>_LINK_TOKEN` (e.g. `CCIP_BSC_LINK_TOKEN`, `CCIP_POLYGON_LINK_TOKEN`). See `smom-dbis-138/.env` and [fund-ccip-bridges-with-link.sh](../../smom-dbis-138/scripts/deployment/fund-ccip-bridges-with-link.sh).
+
+---
+
+## Script defaults
+
+- **Chain 138:** Scripts that run on 138 (e.g. `check-link-balance.sh`, `wrap-and-bridge-weth9-to-mainnet.sh` when approving LINK on 138) must default to `0xb7721dD53A8c629d9f1Ba31a5819AFe250002b03` when `LINK_TOKEN_CHAIN138` / `LINK_TOKEN_138` is unset.
+- **Mainnet:** Scripts that run on Mainnet should use `0x514910771AF9Ca656af840dff83E8264EcF986CA` when a mainnet LINK default is needed.
+
+---
+
+## Quick check
+
+To confirm the bridge fee token on Chain 138 (should match LINK above):
+
+```bash
+cast call 0x971cD9D156f193df8051E48043C476e53ECd4693 "feeToken()(address)" --rpc-url $RPC_URL_138
+# Expected: 0xb7721dD53A8c629d9f1Ba31a5819AFe250002b03
+```
--- a/docs/11-references/LIQUIDITY_DEPTH_500M_PER_TOKEN_MULTICHAIN.md
+++ b/docs/11-references/LIQUIDITY_DEPTH_500M_PER_TOKEN_MULTICHAIN.md
@@ -0,0 +1,123 @@
+# Liquidity Depth — 500M per Token on Chain 138, Up to 3 Hops
+
+**Assumption:** You fund **500M USD per token** on Chain 138 (cUSDT, cUSDC, WETH9, WETH10) in DODO PMM pools and bridge destination sides.
+
+**Purpose:** Map effective liquidity depth on all reachable chains via 1-, 2-, and 3-hop routes.
+
+---
+
+## Source Liquidity (Chain 138)
+
+| Token | Amount (USD) | Pool(s) |
+|-------|--------------|---------|
+| cUSDT | 500M | cUSDT/cUSDC, cUSDT/USDT |
+| cUSDC | 500M | cUSDT/cUSDC, cUSDC/USDC |
+| WETH9 | 500M | (CCIP bridge source) |
+| WETH10 | 500M | (CCIP bridge source) |
+
+**Total source:** ~2B USD (500M × 4 tokens; cUSDT/cUSDC share pools).
+
+---
+
+## Bridge Routes (from config)
+
+| Bridge | Tokens | Destinations | Hop |
+|--------|--------|--------------|-----|
+| **CCIP WETH9/WETH10** | WETH | 1, 56, 137, 10, 42161, 8453, 43114 | 1 |
+| **AlltraAdapter** | cUSDT, cUSDC, WETH9 | 651940 | 1 |
+| **Lockbox** | ETH | 1 | 1 |
+| **Universal CCIP** | (config-dependent) | 1, 651940 | 1 |
+| **651940 → X** | AUSDT, AUSDC, WETH | 1, 56, 137, 100, 43114, 8453, 42161, 10, 25, 42220, 1111 | 2 (from 138) |
+
+---
+
+## Liquidity Depth by Chain (Up to 3 Hops)
+
+### 1-Hop (Direct from Chain 138)
+
+| Chain | Chain ID | Tokens | Depth (USD) | Route |
+|-------|----------|--------|-------------|-------|
+| **Ethereum Mainnet** | 1 | WETH, USDC, USDT | 500M each | CCIP WETH9/10; Lockbox ETH; Universal CCIP |
+| **ALL Mainnet** | 651940 | AUSDT, AUSDC, WETH | 500M each | AlltraAdapter |
+| **BSC** | 56 | WETH, USDT, USDC | 500M each | CCIP WETH9/10; token-mapping (cUSDT/cUSDC if bridge deployed) |
+| **Polygon** | 137 | WETH, USDT, USDC | 500M each | CCIP WETH9/10; token-mapping |
+| **Optimism** | 10 | WETH, USDT, USDC | 500M each | CCIP WETH9/10; token-mapping |
+| **Arbitrum** | 42161 | WETH, USDT, USDC | 500M each | CCIP WETH9/10; token-mapping |
+| **Base** | 8453 | WETH, USDT, USDC | 500M each | CCIP WETH9/10; token-mapping |
+| **Avalanche** | 43114 | WETH, USDT, USDC | 500M each | CCIP WETH9/10; token-mapping |
+
+**Note:** cUSDT/cUSDC direct CCIP to L2s (56, 137, etc.) depends on Universal CCIP or per-token CCIP deployment. WETH9/WETH10 CCIP is confirmed.
+
+---
+
+### 2-Hop (138 → 651940 → X)
+
+| Chain | Chain ID | Tokens | Depth (USD) | Route |
+|-------|----------|--------|-------------|-------|
+| **Ethereum Mainnet** | 1 | USDT, USDC, WETH | 500M each | 138 → 651940 → 1 |
+| **BSC** | 56 | USDT, USDC, WETH | 500M each | 138 → 651940 → 56 |
+| **Polygon** | 137 | USDT, USDC, WETH | 500M each | 138 → 651940 → 137 |
+| **Gnosis** | 100 | USDT, USDC, WETH | 500M each | 138 → 651940 → 100 |
+| **Avalanche** | 43114 | USDT, USDC, WETH | 500M each | 138 → 651940 → 43114 |
+| **Base** | 8453 | USDT, USDC, WETH | 500M each | 138 → 651940 → 8453 |
+| **Arbitrum** | 42161 | USDT, USDC, WETH | 500M each | 138 → 651940 → 42161 |
+| **Optimism** | 10 | USDT, USDC, WETH | 500M each | 138 → 651940 → 10 |
+| **Cronos** | 25 | USDT, USDC, WETH | 500M each | 138 → 651940 → 25 |
+| **Celo** | 42220 | USDT, USDC, WETH | 500M each | 138 → 651940 → 42220 |
+| **Wemix** | 1111 | USDT, USDC, WETH | 500M each | 138 → 651940 → 1111 |
+
+**Effective depth:** 500M per token, subject to 651940 bridge liquidity and routing.
+
+---
+
+### 3-Hop (138 → 651940 → 1 → L2, or 138 → 1 → L2)
+
+| Chain | Chain ID | Tokens | Depth (USD) | Route |
+|-------|----------|--------|-------------|-------|
+| **Arbitrum** | 42161 | USDT, USDC, WETH | 500M each | 138 → 651940 → 1 → Arbitrum (canonical bridge) |
+| **Optimism** | 10 | USDT, USDC, WETH | 500M each | 138 → 651940 → 1 → Optimism |
+| **Base** | 8453 | USDT, USDC, WETH | 500M each | 138 → 651940 → 1 → Base |
+| **Polygon** | 137 | USDT, USDC, WETH | 500M each | 138 → 1 → Polygon (if bridge exists) |
+| **BSC** | 56 | USDT, USDC, WETH | 500M each | 138 → 1 → BSC (third-party bridge) |
+
+**Note:** 3-hop typically uses Ethereum as hub. L2s (Arbitrum, Optimism, Base) receive via canonical bridges from Ethereum. Depth = min(500M, Ethereum-side liquidity, L2 bridge capacity).
+
+---
+
+## Summary Matrix
+
+| Chain | 1-Hop | 2-Hop | 3-Hop | Max Depth (USD) |
+|-------|-------|-------|-------|-----------------|
+| **138** | — | — | — | 500M per token (source) |
+| **651940** | ✅ | — | — | 500M per token |
+| **1 (Ethereum)** | ✅ | ✅ | — | 500M per token |
+| **56 (BSC)** | ✅ | ✅ | ✅ | 500M per token |
+| **137 (Polygon)** | ✅ | ✅ | ✅ | 500M per token |
+| **10 (Optimism)** | ✅ | ✅ | ✅ | 500M per token |
+| **42161 (Arbitrum)** | ✅ | ✅ | ✅ | 500M per token |
+| **8453 (Base)** | ✅ | ✅ | ✅ | 500M per token |
+| **43114 (Avalanche)** | ✅ | ✅ | — | 500M per token |
+| **100 (Gnosis)** | ⚠️* | ✅ | — | 500M per token |
+| **25 (Cronos)** | ⚠️* | ✅ | — | 500M per token |
+| **42220 (Celo)** | ⚠️* | ✅ | — | 500M per token |
+| **1111 (Wemix)** | ⚠️* | ✅ | — | 500M per token |
+
+\* Gnosis, Cronos, Celo, Wemix: 1-hop from 138 depends on CCIP bridge deployment (config ready; verify deployment).
+
+---
+
+## Constraints
+
+1. **Destination prefunding:** CCIP, AlltraAdapter, and Lockbox require destination-side liquidity. Fund bridges with 500M equivalent per token on each destination.
+2. **CCIP:** WETH9/WETH10 only for direct 1-hop to L2s. cUSDT/cUSDC to L2s via 2-hop (138 → 651940 → X).
+3. **Rate limits:** Tezos/Etherlink bridge-limits (alltra-lifi) use per-tx and daily caps; Chain 138→L2 bridges may have similar limits—check contract config.
+4. **LINK for CCIP:** Ensure LINK balance on bridges for CCIP fees.
+
+---
+
+## References
+
+- [LIQUIDITY_POOLS_MASTER_MAP.md](LIQUIDITY_POOLS_MASTER_MAP.md)
+- [token-mapping-multichain.json](../../config/token-mapping-multichain.json)
+- [cross-chain-bridges.ts](../../smom-dbis-138/services/token-aggregation/src/config/cross-chain-bridges.ts)
+- [LIQUIDITY_POOL_CONTROLS_RUNBOOK.md](../03-deployment/LIQUIDITY_POOL_CONTROLS_RUNBOOK.md)
--- a/docs/11-references/LIQUIDITY_POOLS_MASTER_MAP.md
+++ b/docs/11-references/LIQUIDITY_POOLS_MASTER_MAP.md
@@ -1,7 +1,7 @@
 # Liquidity Pools Master Map — ChainID 138 & ALL Mainnet (Alltra)

-**Last Updated:** 2026-02-15  
-**Document Version:** 1.0  
+**Last Updated:** 2026-02-28  
+**Document Version:** 1.1  
 **Status:** Reference documentation (designed vs deployed)

 ---
@@ -60,17 +60,17 @@ This document maps all **private**, **public**, **reserve**, and **stabilization

 | Pool Pair | Type | DEX | Status | Notes |
 |-----------|------|-----|--------|-------|
-| cUSDT / cUSDC | Public | DODO PMM | ❌ **Not deployed** | `createCUSDTCUSDCPool`; DODOPMMIntegration not deployed |
-| cUSDT / USDT (official) | Public | DODO PMM | ❌ **Not deployed** | `createCUSDTUSDTPool` |
-| cUSDC / USDC (official) | Public | DODO PMM | ❌ **Not deployed** | `createCUSDCUSDCPool` |
+| cUSDT / cUSDC | Public | DODO PMM | ✅ **Created** | Pool: `0x9fcB06Aa1FD5215DC0E91Fd098aeff4B62fEa5C8`; script: `CreateCUSDTCUSDCPool.s.sol` or `create-all-pmm-pools-chain138.sh` |
+| cUSDT / USDT (official) | Public | DODO PMM | ✅ **Created** | Pool: `0xa3Ee6091696B28e5497b6F491fA1e99047250c59`; script: `CreateCUSDTUSDTPool.s.sol` |
+| cUSDC / USDC (official) | Public | DODO PMM | ✅ **Created** | Pool: `0x90bd9Bf18Daa26Af3e814ea224032d015db58Ea5`; script: `CreateCUSDCUSDCPool.s.sol` |
 | cUSDT / XAU | Public | DODO PMM | ❌ **Not deployed** | Requires XAU token (not on chain) |
 | cUSDC / XAU | Public | DODO PMM | ❌ **Not deployed** | Requires XAU token |
 | cEURT / XAU | Public | DODO PMM | ❌ **Not deployed** | Requires cEURT + XAU (neither deployed) |

 **Purpose:** User routing, price discovery, flash loan access. **Not** primary stabilization.

-**Contracts:** `DODOPMMIntegration.sol`, `DODOPMMProvider.sol` — exist but **not deployed**.  
-**Config:** `CHAIN_138_DODO_POOL_MANAGER`, `CHAIN_138_DODO_VENDING_MACHINE` (env placeholders).
+**Contracts:** `DODOPMMIntegration.sol` at `0x79cdbaFBaA0FdF9F55D26F360F54cddE5c743F7D` (Mock DVM); all three pools created. **DODOPMMProvider** deployed at `0x8EF6657D2a86c569F6ffc337EE6b4260Bd2e59d0`; pools registered via `RegisterDODOPools.s.sol`. **Add liquidity:** [ADD_LIQUIDITY_PMM_CHAIN138_RUNBOOK.md](../03-deployment/ADD_LIQUIDITY_PMM_CHAIN138_RUNBOOK.md). **Pre-deployment steps:** [PRE_DEPLOYMENT_CHECKLIST.md](../03-deployment/PRE_DEPLOYMENT_CHECKLIST.md).
+**Config:** `CHAIN_138_DODO_PMM_INTEGRATION` set in .env; `CHAIN_138_DODO_POOL_MANAGER`, `CHAIN_138_DODO_VENDING_MACHINE` (optional).

 **Source:** [VAULT_SYSTEM_MASTER_TECHNICAL_PLAN.md](../VAULT_SYSTEM_MASTER_TECHNICAL_PLAN.md) §4, [DODO_PMM_INTEGRATION.md](../../smom-dbis-138/docs/integration/DODO_PMM_INTEGRATION.md)

@@ -121,7 +121,7 @@ This document maps all **private**, **public**, **reserve**, and **stabilization
 **Config:** `LIQUIDITY_POOL_ADDRESS` in `.env` — placeholder `0x0`.  
 **Related:** Lockbox138 `0xFce6f50B312B3D936Ea9693C5C9531CF92a3324c` (deployed); full trustless stack not deployed.

-**Source:** [DEX_AND_CROSS_CHAIN_CONTRACTS_NEEDED.md](DEX_AND_CROSS_CHAIN_CONTRACTS_NEEDED.md), [CONTRACT_INVENTORY_AND_VERIFICATION.md](CONTRACT_INVENTORY_AND_VERIFICATION.md)
+**Source:** [DEX_AND_CROSS_CHAIN_CONTRACTS_NEEDED.md](DEX_AND_CROSS_CHAIN_CONTRACTS_NEEDED.md), [ADDRESS_MATRIX_AND_STATUS.md](ADDRESS_MATRIX_AND_STATUS.md)

 ---

@@ -163,11 +163,23 @@ Not liquidity pools per se; they support XAU triangulation for private mesh pari

 ---

+## Public-chain cW* stabilization (edge pools + bot)
+
+M1 tokens on Chain 138 (cUSDT, cUSDC, cAUSDT, cEURC, cEURT, cUSDW) are bridged to public chains as **cW\*** wrappers (cWUSDT, cWUSDC, etc.). **Single-sided PMM edge pools** (cW* / USDC, cW* / USDT, etc.) on each public chain and a **bot-driven stabilization mesh** maintain the peg. Specs, pool matrix, peg bands, and deployment recipe:
+
+- **[cross-chain-pmm-lps/README.md](../../cross-chain-pmm-lps/README.md)** — Submodule overview and quick start
+- **[cross-chain-pmm-lps/docs/06-deployment-recipe.md](../../cross-chain-pmm-lps/docs/06-deployment-recipe.md)** — Step-by-step deployment
+- **[cross-chain-pmm-lps/config/](../../cross-chain-pmm-lps/config/)** — token-map.json, pool-matrix.json, peg-bands.json, chains.json
+
+See [SUBMODULE_RELATIONSHIP_MAP.md](SUBMODULE_RELATIONSHIP_MAP.md) for submodule status.
+
+---
+
 ## Summary Matrix

 | Category | Chain 138 | ALL Mainnet (651940) |
 |----------|-----------|----------------------|
-| **Public DEX pools** | DODO PMM (designed, not deployed) | Uniswap V2/V3, DODO (env placeholders); HYDX DEX present, pools undisclosed |
+| **Public DEX pools** | DODO PMM: integration deployed (Mock DVM); pools not created | Uniswap V2/V3, DODO (env placeholders); HYDX DEX present, pools undisclosed |
 | **Private stabilization** | XAU-anchored (designed; XAU/cEURT not deployed) | Not documented |
 | **Reserve / vault** | ReserveSystem, ReserveTokenIntegration ✅ | Not documented |
 | **Bridge liquidity** | LiquidityPoolETH (placeholder) | Not documented |
@@ -192,6 +204,9 @@ From [VAULT_SYSTEM_MASTER_TECHNICAL_PLAN.md](../VAULT_SYSTEM_MASTER_TECHNICAL_PL

 | Document | Purpose |
 |----------|---------|
+| [POOLS_AND_NETWORKS_FULL_DESIGN.md](POOLS_AND_NETWORKS_FULL_DESIGN.md) | **Full design:** every pool and network (61 pools, 6 networks). |
+| [POOL_ACCESS_DASHBOARD_API_MCP.md](POOL_ACCESS_DASHBOARD_API_MCP.md) | Whether pools are accessible via standard DODO dashboard, API, and MCP. |
+| [GAPS_FILLED_2026-02-27.md](GAPS_FILLED_2026-02-27.md) | Summary of gaps filled (API cW* chains, MCP mock_dvm, pool-matrix 11 chains, docs). |
 | [CHAIN138_TOKEN_ADDRESSES.md](CHAIN138_TOKEN_ADDRESSES.md) | Token list Chain 138 |
 | [ALL_MAINNET_TOKEN_ADDRESSES.md](ALL_MAINNET_TOKEN_ADDRESSES.md) | Token list ALL Mainnet |
 | [VAULT_SYSTEM_MASTER_TECHNICAL_PLAN.md](../VAULT_SYSTEM_MASTER_TECHNICAL_PLAN.md) | Pool architecture, capital buckets |
@@ -200,3 +215,4 @@ From [VAULT_SYSTEM_MASTER_TECHNICAL_PLAN.md](../VAULT_SYSTEM_MASTER_TECHNICAL_PL
 | [CONTRACT_DEPLOYMENT_RUNBOOK.md](../03-deployment/CONTRACT_DEPLOYMENT_RUNBOOK.md) | Deployment steps |
 | [config/smart-contracts-master.json](../../config/smart-contracts-master.json) | Contract addresses |
 | [dex-factories.ts](../../smom-dbis-138/services/token-aggregation/src/config/dex-factories.ts) | DEX config per chain |
+| [cross-chain-pmm-lps/](../../cross-chain-pmm-lps/README.md) | Public-chain cW* edge pools + stabilization bot (token map, pool matrix, peg bands, deployment) |
--- a/docs/11-references/PMM_DEX_ROUTING_STATUS.md
+++ b/docs/11-references/PMM_DEX_ROUTING_STATUS.md
@@ -0,0 +1,134 @@
+# PMM Liquidity Pools & DEX/DeFi Routing — Full System Status
+
+**Last Updated:** 2026-02-28  
+**Purpose:** Single reference for DEX/DeFi and PMM liquidity pool routing — what is designed, deployed, and in use.
+
+---
+
+## Executive summary (updated 2026-02-28)
+
+- **DODOPMMIntegration** is **deployed** on Chain 138 at `0x79cdbaFBaA0FdF9F55D26F360F54cddE5c743F7D` (Mock DVM). **All three PMM pools are created:** cUSDT/cUSDC (`0x9fcB06Aa1FD5215DC0E91Fd098aeff4B62fEa5C8`), cUSDT/USDT (`0xa3Ee6091696B28e5497b6F491fA1e99047250c59`), cUSDC/USDC (`0x90bd9Bf18Daa26Af3e814ea224032d015db58Ea5`). On-chain PMM swaps are available via DODOPMMIntegration and DODOPMMProvider.
+- **DODOPMMProvider** is **deployed** at `0x8EF6657D2a86c569F6ffc337EE6b4260Bd2e59d0` with all three pools registered (see [LIQUIDITY_POOLS_MASTER_MAP](LIQUIDITY_POOLS_MASTER_MAP.md), [ADDRESS_MATRIX_AND_STATUS](ADDRESS_MATRIX_AND_STATUS.md)).
+- **EnhancedSwapRouter** is **not deployed**; multi-provider DEX routing (Uniswap/Balancer/Curve/1inch) is not live.
+- **Token-aggregation** service is implemented and runnable (single-hop quotes; can index DODO pools). **Bridge quote API** (swap+bridge+swap) is implemented.
+- **Full system status:** PMM liquidity and DODOPMMProvider routing are **deployed and in use** on Chain 138. Remaining: add liquidity to pools as needed; optionally deploy EnhancedSwapRouter when other DEX pools exist on 138.
+- **Optional items completed (2026-02-27 / 2026-03-01):** DeployCompliantFiatTokens (10 tokens on 138); Blockscout verification run; MCP allowlist-138 (`ai-mcp-pmm-controller/config/allowlist-138.json`); add-liquidity runbook ([ADD_LIQUIDITY_PMM_CHAIN138_RUNBOOK](../03-deployment/ADD_LIQUIDITY_PMM_CHAIN138_RUNBOOK.md)); token-aggregation canonical fallbacks for cEURC/cEURT/cGBP*/cAUDC/cJPYC/cCHFC/cCADC/cXAU*; ENV_EXAMPLE_CONTENT + CREATE2_FACTORY_ADDRESS; E2E routing verification run.
+
+---
+
+## 1. Architecture Overview
+
+### 1.1 Designed routing layers
+
+| Layer | Description | Components |
+|-------|-------------|------------|
+| **On-chain multi-provider** | Size-based routing across DEXs for one leg (e.g. WETH↔stable) | EnhancedSwapRouter (Uniswap V3, Dodoex PMM, Balancer, Curve, 1inch) |
+| **PMM pools (Chain 138)** | cUSDT/cUSDC and cUSDT↔USDT, cUSDC↔USDC via DODO-style PMM | DODOPMMIntegration, DODOPMMProvider |
+| **Token-aggregation API** | Single-hop quotes, pool indexing, reports | token-aggregation service (UniswapV2/V3 + DODO from DODOPMMIntegration) |
+| **Swap–bridge–swap** | Cross-chain: swap (source) → bridge → swap (destination) | SwapBridgeSwapCoordinator (on-chain), orchestration QuoteService (`POST /api/bridge/quote`) |
+| **Public-chain cW* mesh** | cW* wrappers on public chains, single-sided PMM edge pools, bot-driven peg | cross-chain-pmm-lps (specs, simulation, deployment recipe) |
+
+### 1.2 Routing logic (EnhancedSwapRouter / Liquidity Engine)
+
+- **Size-based:** Small (&lt;$10k) → Uniswap V3 / Dodoex; Medium ($10k–$100k) → Dodoex → Balancer → Uniswap V3; Large (&gt;$100k) → Dodoex → Curve → Balancer.
+- **Slippage-based:** Low → prefer Dodoex (PMM); medium → Balancer; high → Curve.
+- **Liquidity-based:** High → Uniswap V3; medium → Dodoex; low → Curve.
+
+**Reference:** [smom-dbis-138/docs/bridge/trustless/integration/ENHANCED_ROUTING.md](../smom-dbis-138/docs/bridge/trustless/integration/ENHANCED_ROUTING.md), [LIQUIDITY_ENGINE.md](../smom-dbis-138/docs/bridge/trustless/integration/LIQUIDITY_ENGINE.md).
+
+---
+
+## 2. Deployment Status (Chain 138 & Related)
+
+### 2.1 PMM / DEX (Chain 138)
+
+| Component | Status | Address / Notes |
+|-----------|--------|------------------|
+| **DODOPMMIntegration** | Deployed | `0x79cdbaFBaA0FdF9F55D26F360F54cddE5c743F7D` — uses **Mock DVM** (MockDVMFactory/MockDVMPool); not official DODO AMM. |
+| **PMM pools (cUSDT/cUSDC, cUSDT/USDT, cUSDC/USDC)** | **Created** | cUSDT/cUSDC: `0x9fcB06Aa1FD5215DC0E91Fd098aeff4B62fEa5C8`; cUSDT/USDT: `0xa3Ee6091696B28e5497b6F491fA1e99047250c59`; cUSDC/USDC: `0x90bd9Bf18Daa26Af3e814ea224032d015db58Ea5`. See [LIQUIDITY_POOLS_MASTER_MAP](LIQUIDITY_POOLS_MASTER_MAP.md). |
+| **DODOPMMProvider** | **Deployed** | `0x8EF6657D2a86c569F6ffc337EE6b4260Bd2e59d0`; all three pools registered via `RegisterDODOPools.s.sol`. |
+| **EnhancedSwapRouter** | Not deployed | Deploy when Uniswap/Balancer pools exist on 138; configure quoter and Balancer poolId. |
+| **LiquidityPoolETH** (trustless bridge) | Placeholder | Not deployed; config uses `0x0`. |
+
+**Doc note:** [LIQUIDITY_POOLS_MASTER_MAP.md](LIQUIDITY_POOLS_MASTER_MAP.md) and [ADDRESS_MATRIX_AND_STATUS.md](ADDRESS_MATRIX_AND_STATUS.md) list pool and DODOPMMProvider addresses. DEX_AND_CROSS_CHAIN_CONTRACTS_NEEDED reflects DODOPMMIntegration deployed and pools created.
+
+### 2.2 Token-aggregation & orchestration
+
+| Component | Status | Notes |
+|-----------|--------|--------|
+| **Token-aggregation service** | Implemented & runnable | Indexes UniswapV2/V3 and DODO when `CHAIN_138_DODO_PMM_INTEGRATION` is set (set in smom-dbis-138/.env). Single-hop quote only; no N-hop pathfinding. |
+| **Orchestration QuoteService** | Implemented | `POST /api/bridge/quote` with optional source/destination swap quotes; requires bridge registry and optional EnhancedSwapRouter addresses. |
+| **Liquidity Engine (backend)** | Implemented | Depends on EnhancedSwapRouter being deployed; not usable for routing until router is live. |
+
+### 2.3 Swap–bridge–swap & trustless stack
+
+| Component | Status | Notes |
+|-----------|--------|--------|
+| **SwapBridgeSwapCoordinator** | Script exists; not in CONTRACT_ADDRESSES_REFERENCE | Deploy via `DeploySwapBridgeSwapCoordinator.s.sol` when swap+bridge+swap flow is needed. |
+| **Lockbox138** | Deployed | `0xFce6f50B312B3D936Ea9693C5C9531CF92a3324c` |
+| **InboxETH, BondManager, ChallengeManager, LiquidityPoolETH** | Not deployed (full trustless stack) | Optional; see [DEX_AND_CROSS_CHAIN_CONTRACTS_NEEDED.md](DEX_AND_CROSS_CHAIN_CONTRACTS_NEEDED.md) §3.3. |
+
+### 2.4 Cross-chain cW* PMM mesh (public chains)
+
+| Component | Status | Notes |
+|-----------|--------|--------|
+| **cross-chain-pmm-lps** | Design & tooling ready | Token map, pool topology, peg bands, simulation model, deployment recipe, safe inventory sizing. **Not deployed:** edge pools and bot v1/v2 are not documented as live. |
+
+---
+
+## 3. Multihop / routing capability summary
+
+| Capability | Available? | Where |
+|------------|------------|--------|
+| Single-hop quote (API) | Yes | `GET /api/v1/quote` (best direct pool for tokenIn/tokenOut) |
+| Multi-provider choice (one leg) | No (router not deployed) | EnhancedSwapRouter would provide WETH↔stable across Uniswap/Dodo/Balancer/Curve/1inch |
+| N-hop path (A→B→C on one chain) | No | No graph-based multi-hop swap API or on-chain pathfinder |
+| Swap–bridge–swap (cross-chain) | Yes (orchestration) | QuoteService; on-chain coordinator deployable when needed |
+| DODO PMM on-chain swaps | **Yes** | Pools created; DODOPMMProvider deployed; use getQuote/executeSwap or DODOPMMIntegration swap functions. |
+
+---
+
+## 4. Full system “ready and in use” — summary
+
+| Area | Ready? | In use? |
+|------|--------|--------|
+| **PMM liquidity pools (Chain 138)** | **Yes** | DODOPMMIntegration + three pools created; DODOPMMProvider deployed and registered; on-chain swaps available (liquidity may still need to be added). |
+| **DEX routing (EnhancedSwapRouter)** | No | Contract not deployed; no Uniswap/Balancer pools on 138. |
+| **Token-aggregation API** | Yes | Service can run; single-hop quotes; can index DODO pools once DODOPMMIntegration has pools. |
+| **Bridge quote (swap+bridge+swap)** | Partial | QuoteService implemented; coordinator and router optional; not full E2E flow. |
+| **Liquidity Engine (decision logic)** | No | Depends on EnhancedSwapRouter. |
+| **Cross-chain cW* PMM mesh** | No | Design/simulation only; edge pools and bots not deployed. |
+
+**Conclusion:** PMM liquidity and DODOPMMProvider routing **are** deployed and in use on Chain 138. What is in place:
+
+- **Live:** DODOPMMIntegration (Mock DVM), **three PMM pools created**, **DODOPMMProvider deployed** with pools registered, token-aggregation service, bridge/orchestration quote API.
+- **Remaining:** Add liquidity to pools as needed; deploy EnhancedSwapRouter when Uniswap/Balancer pools exist on 138.
+- **Optional / later:** Full trustless stack (LiquidityPoolETH, etc.), cross-chain cW* edge pools and bots.
+
+---
+
+## 5. Next steps to make PMM routing usable
+
+**Full ordered steps:** See [PRE_DEPLOYMENT_CHECKLIST.md](../03-deployment/PRE_DEPLOYMENT_CHECKLIST.md). **Run Phase 1 + Phase 2 in parallel:** [NEXT_STEPS_PMM_FULL_PARITY_AND_ALL_POOLS.md](../03-deployment/NEXT_STEPS_PMM_FULL_PARITY_AND_ALL_POOLS.md) — use `./scripts/deployment/run-pmm-full-parity-all-phases.sh` from `smom-dbis-138/`.
+
+1. **Create PMM pools (Chain 138):** Run `CreateCUSDTCUSDCPool.s.sol`, `CreateCUSDTUSDTPool.s.sol`, `CreateCUSDCUSDCPool.s.sol` (or `./scripts/deployment/create-all-pmm-pools-chain138.sh`), or `deploy-transaction-mirror-and-pmm-pool-after-txpool-clear.sh` for mirror + cUSDT/cUSDC only; ensure POOL_MANAGER_ROLE and nonce/RPC are correct.
+2. **Add liquidity** to created pools via `forge script script/dex/AddLiquidityPMMPoolsChain138.s.sol:AddLiquidityPMMPoolsChain138` (set `ADD_LIQUIDITY_BASE_AMOUNT`, `ADD_LIQUIDITY_QUOTE_AMOUNT` in .env) or call `addLiquidity(pool, baseAmount, quoteAmount)` on DODOPMMIntegration.
+3. **Deploy DODOPMMProvider** via `script/liquidity/DeployDODOPMMProvider.s.sol`, then register pools with `registerPool(tokenIn, tokenOut, pool)`.
+4. **Optionally deploy EnhancedSwapRouter** when Uniswap/Balancer quoter/poolId are configured for 138.
+5. **Update docs:** Add pool and DODOPMMProvider addresses to LIQUIDITY_POOLS_MASTER_MAP and CONTRACT_ADDRESSES_REFERENCE once created.
+
+---
+
+## 6. References
+
+| Doc | Purpose |
+|-----|---------|
+| [DEX_AND_AGGREGATORS_CHAIN138_EXPLAINER.md](../04-configuration/DEX_AND_AGGREGATORS_CHAIN138_EXPLAINER.md) | **Explainer:** Using DEX and aggregators with Chain 138 tokens; routing for DEXs; API and flows. |
+| [PRE_DEPLOYMENT_CHECKLIST.md](../03-deployment/PRE_DEPLOYMENT_CHECKLIST.md) | **Pre-deployment:** component status and ordered steps (pools, DODOPMMProvider, verification). |
+| [LIQUIDITY_POOLS_MASTER_MAP.md](LIQUIDITY_POOLS_MASTER_MAP.md) | Pool map 138 & 651940; update when pools created |
+| [STATUS_AND_TOKEN_ROUTING.md](../smom-dbis-138/docs/STATUS_AND_TOKEN_ROUTING.md) | Token-aggregation API and routing layers |
+| [DODO_PMM_INTEGRATION.md](../smom-dbis-138/docs/integration/DODO_PMM_INTEGRATION.md) | Pool creation and swap usage |
+| [DODO_PMM_NEXT_STEPS.md](../smom-dbis-138/docs/bridge/DODO_PMM_NEXT_STEPS.md) | Create-all-dodo-pools, SwapBridgeSwapCoordinator, bridge quote API |
+| [CONTRACT_DEPLOYMENT_RUNBOOK.md](../03-deployment/CONTRACT_DEPLOYMENT_RUNBOOK.md) | EnhancedSwapRouter & DODOPMMProvider config |
+| [LIQUIDITY_POOL_CONTROLS_RUNBOOK.md](../03-deployment/LIQUIDITY_POOL_CONTROLS_RUNBOOK.md) | DODO and trustless pool controls |
+| [cross-chain-pmm-lps/README.md](../../cross-chain-pmm-lps/README.md) | cW* mesh and deployment recipe |
--- a/docs/11-references/POOLS_AND_NETWORKS_FULL_DESIGN.md
+++ b/docs/11-references/POOLS_AND_NETWORKS_FULL_DESIGN.md
@@ -0,0 +1,112 @@
+# Pools and Networks — Full Design (Everything in Scope)
+
+**Last Updated:** 2026-02-28  
+**Purpose:** Single reference for **every** pool and **every** network in the design: create, deploy, and fund.
+
+---
+
+## Summary totals
+
+| Scope | Networks | Pools (total) | Pools (create + fund) | Status |
+|-------|----------|----------------|------------------------|--------|
+| **Chain 138** (DODO PMM + private + bridge) | 1 | 10 | 3 now; 7 when XAU/cEURT exist | 3 actionable; 7 blocked |
+| **Cross-chain cW* edge (pool-matrix)** | 11 | 111 | 66 first + 45 optional | Design only; not deployed |
+| **Full design total** | **12** | **121** | **3 now; 7 later (138) + 111 cW*** | See below |
+
+- **Networks in full design:** 12 (Chain 138 + 11 public chains in cW* pool-matrix).
+- **Pools in full design:** 121 (10 on 138 + 111 in cW* matrix). Of these, 3 are immediately actionable on 138; 7 on 138 depend on XAU/cEURT and bridge LP; 111 cW* pools across 11 chains when deployed.
+
+---
+
+## 1. Chain 138 — All pools in design
+
+**Network:** 1 (Chain 138 — DeFi Oracle Meta Mainnet).
+
+| # | Pool / component | Type | Create | Deploy | Fund | Blocked by |
+|---|-------------------|------|--------|--------|------|------------|
+| 1 | cUSDT / cUSDC | Public DODO PMM | ✅ Script | — (via DODOPMMIntegration) | ✅ addLiquidity | — |
+| 2 | cUSDT / USDT (official) | Public DODO PMM | ✅ Script | — | ✅ addLiquidity | — |
+| 3 | cUSDC / USDC (official) | Public DODO PMM | ✅ Script | — | ✅ addLiquidity | — |
+| 4 | cUSDT / XAU | Public DODO PMM | createPool | — | ✅ | XAU token not deployed |
+| 5 | cUSDC / XAU | Public DODO PMM | createPool | — | ✅ | XAU token not deployed |
+| 6 | cEURT / XAU | Public DODO PMM | createPool | — | ✅ | cEURT + XAU not deployed |
+| 7 | cUSDT ↔ XAU | Private (PrivatePoolRegistry) | createPool + register | — | ✅ | XAU not deployed |
+| 8 | cUSDC ↔ XAU | Private | createPool + register | — | ✅ | XAU not deployed |
+| 9 | cEURT ↔ XAU | Private | createPool + register | — | ✅ | cEURT + XAU not deployed |
+| 10 | LiquidityPoolETH | Bridge LP | — | ✅ Contract | ✅ | Full trustless stack not deployed |
+
+**Chain 138 subtotal:** 10 pools/components on 1 network. **3** create+fund now; **6** when XAU/cEURT exist; **1** when trustless stack is deployed.
+
+**Scripts (138):** [PRE_DEPLOYMENT_CHECKLIST.md](../03-deployment/PRE_DEPLOYMENT_CHECKLIST.md), `create-all-pmm-pools-chain138.sh`, `CreateCUSDTCUSDCPool.s.sol`, `CreateCUSDTUSDTPool.s.sol`, `CreateCUSDCUSDCPool.s.sol`.
+
+---
+
+## 2. Cross-chain cW* edge pools (pool-matrix)
+
+**Source:** `cross-chain-pmm-lps/config/pool-matrix.json`, `chains.json`.
+
+**Networks:** 11 (all chains from chains.json now have a defined pool matrix).
+
+| Chain ID | Network | Hub stable | PoolsFirst (count) | PoolsOptional (count) | Total |
+|----------|---------|-------------|---------------------|------------------------|-------|
+| 1 | Ethereum Mainnet | USDC | 6 | 4 | 10 |
+| 10 | Optimism | USDC | 6 | 4 | 10 |
+| 25 | Cronos | USDT | 6 | 4 | 10 |
+| 56 | BSC (BNB Chain) | USDT | 6 | 4 | 10 |
+| 100 | Gnosis Chain | USDC | 6 | 5 | 11 |
+| 137 | Polygon | USDC | 6 | 4 | 10 |
+| 42161 | Arbitrum One | USDC | 6 | 4 | 10 |
+| 42220 | Celo | USDC | 6 | 4 | 10 |
+| 43114 | Avalanche C-Chain | USDC | 6 | 4 | 10 |
+| 8453 | Base | USDC | 6 | 4 | 10 |
+| 1111 | Wemix | USDT | 6 | 4 | 10 |
+| **Total** | **11 networks** | — | **66** | **45** | **111** |
+
+### Per-chain pool pairs (from pool-matrix.json)
+
+**poolsFirst (66 pools — 6 per chain across 11 chains):**  
+cWUSDT/USDC, cWUSDC/USDC, cWEURC/USDC, cWEURT/USDC, cWUSDW/USDC, cWAUSDT/USDC (chains 1, 10, 100, 137); on BSC (56) hub is USDT: cWUSDT/USDT, cWUSDC/USDT, cWAUSDT/USDT, cWEURC/USDT, cWEURT/USDT, cWUSDW/USDT.
+
+**poolsOptional (21 pools):**  
+Vary by chain (e.g. cWUSDT/USDT, cWUSDT/DAI, cWUSDC/USDT, cWUSDC/DAI; BSC: cWUSDT/USDC, cWUSDT/BUSD, …; Gnosis: + cWUSDT/mUSD, cWUSDC/mUSD).
+
+**cW* tokens in design:** cWUSDT, cWUSDC, cWAUSDT, cWEURC, cWEURT, cWUSDW.
+
+**Status:** Design and tooling only; edge pools and bots **not deployed**. Deploy and fund per [cross-chain-pmm-lps/docs/06-deployment-recipe.md](../../cross-chain-pmm-lps/docs/06-deployment-recipe.md).
+
+---
+
+## 3. ALL Mainnet (651940)
+
+- **Network:** 1 (Alltra).
+- **Pools:** Not enumerated in this repo. DEX config is env-based (Uniswap V2/V3, DODO); HYDX exists; no explicit “create, deploy, fund” pool list.
+- **Count in “full design”:** 0 pools in this document; add when a pool matrix or runbook exists for 651940.
+
+---
+
+## 4. Grand totals (everything in the design)
+
+| Item | Count |
+|------|--------|
+| **Networks** | **12** (138 + 11 cW* matrix chains) |
+| **Total pools** | **121** (10 on 138 + 111 cW*) |
+| **Actionable now (create + fund)** | **3** (Chain 138 public DODO only) |
+| **After XAU/cEURT + trustless** | **+7** on 138 |
+| **cW* mesh (design)** | **111** (66 first + 45 optional) on 11 networks |
+
+**Create / deploy / fund by scope:**
+
+- **Chain 138:** 3 pools create + fund now; 7 more when tokens and trustless stack exist.
+- **cW* mesh:** 111 pools across 11 networks — all in design; deploy and fund per deployment recipe when cW* and infrastructure exist.
+
+---
+
+## References
+
+| Doc | Purpose |
+|-----|---------|
+| [LIQUIDITY_POOLS_MASTER_MAP.md](LIQUIDITY_POOLS_MASTER_MAP.md) | Pool map 138 & 651940 |
+| [PRE_DEPLOYMENT_CHECKLIST.md](../03-deployment/PRE_DEPLOYMENT_CHECKLIST.md) | Chain 138 steps (create, deploy, fund) |
+| [cross-chain-pmm-lps/config/pool-matrix.json](../../cross-chain-pmm-lps/config/pool-matrix.json) | cW* per-chain pool list |
+| [cross-chain-pmm-lps/config/chains.json](../../cross-chain-pmm-lps/config/chains.json) | Chain IDs and hub stables |
+| [cross-chain-pmm-lps/docs/06-deployment-recipe.md](../../cross-chain-pmm-lps/docs/06-deployment-recipe.md) | cW* deployment steps |
--- a/docs/11-references/POOL_ACCESS_DASHBOARD_API_MCP.md
+++ b/docs/11-references/POOL_ACCESS_DASHBOARD_API_MCP.md
@@ -0,0 +1,105 @@
+# Pool Access — Standard DODO Dashboard, API, and MCP
+
+**Last Updated:** 2026-02-28  
+**Purpose:** Whether all designed pools (61 across 6 networks) can be accessed via the **standard DODO dashboard**, **API**, and **MCP**, and what is required.
+
+---
+
+## Short answer
+
+| Access method | Chain 138 pools | cW* edge pools (5 public chains) | Requirement |
+|---------------|------------------|-----------------------------------|-------------|
+| **Standard DODO dashboard** | ❌ No | ⚠️ Only if real DODO + chain supported | 138 uses Mock DVM; dashboard does not support custom chain 138. |
+| **API (token-aggregation)** | ✅ Yes | ✅ Yes (when env set) | Chain 138: set `CHAIN_138_DODO_PMM_INTEGRATION`. cW* chains 1, 10, 56, 100, 137: added to dex-factories and chains.ts; set `CHAIN_*_DODO_PMM_INTEGRATION` or `CHAIN_*_DODO_POOL_MANAGER` and run indexer for those chains. |
+| **MCP (ai-mcp-pmm-controller)** | ✅ Yes (after allowlist) | ⚠️ Per-chain + allowlist | Chain 138: MockDVMPool now has getOraclePrice, _K_, _LP_FEE_RATE_ so dodo_pmm_v2_like profile works; add each pool to allowlist and set RPC to 138. Other chains: one MCP instance per chain + allowlist. |
+
+**Not all pools can be accessed by all three today.** Below is what works, what’s missing, and what to change.
+
+---
+
+## 1. Standard DODO dashboard
+
+**What it is:** The official DODO app (e.g. app.dodoex.io) and its subgraph/indexer for supported chains.
+
+| Pool scope | Accessible? | Reason |
+|------------|-------------|--------|
+| **Chain 138** (10 pools) | ❌ **No** | Chain 138 is a **custom/private** chain. The standard DODO dashboard only supports chains DODO officially supports (e.g. Ethereum, BSC, Polygon, Arbitrum). It does not connect to Chain 138 or index Mock DVM pools. |
+| **cW* edge pools** (51 on chains 1, 10, 56, 100, 137) | ⚠️ **Only if** | (1) Pools are **real DODO protocol** pools on that chain, and (2) DODO’s dashboard **supports that chain**. If you deploy via your own factory or a fork, they will not appear unless DODO adds your contracts/chain. |
+| **Private / bridge / other** | ❌ No | Private and bridge LPs are not part of the public DODO frontend. |
+
+**Conclusion:** **No** for Chain 138. **Maybe** for cW* only when they are official DODO pools on a DODO-supported chain. For full visibility you need your own **custom dashboard** or **API + UI** that talks to your RPC and indexer.
+
+---
+
+## 2. API (token-aggregation)
+
+**What it is:** The token-aggregation service indexes pools and exposes REST endpoints (tokens, pools, quote, report).
+
+| Pool scope | Accessible? | Requirement |
+|------------|-------------|-------------|
+| **Chain 138** | ✅ **Yes** | Set `CHAIN_138_DODO_PMM_INTEGRATION=0x79cdbaFBaA0FdF9F55D26F360F54cddE5c743F7D` (and RPC) in the service env. The pool indexer uses `getAllPools()`, then `getPoolConfig`, `getPoolReserves`, `getPoolPriceOrOracle` per pool. Once pools exist and the indexer runs, they appear in `/api/v1/tokens`, `/api/v1/pools`, `/api/v1/quote`, and report endpoints. |
+| **ALL Mainnet (651940)** | ⚠️ **If configured** | Set `CHAIN_651940_DODO_POOL_MANAGER` (and optional `dodoPmmIntegration`) in dex-factories / env. Today no DODO pool list is documented for 651940. |
+| **cW* edge (chains 1, 10, 56, 100, 137)** | ✅ **Yes** (when env set) | `dex-factories.ts` and `chains.ts` now include chainIds 1, 10, 56, 100, 137. Set `CHAIN_*_DODO_PMM_INTEGRATION` or `CHAIN_*_DODO_POOL_MANAGER` (and `CHAIN_*_RPC_URL`) so the indexer can index DODO/pools on those chains. |
+
+**Conclusion:** **Yes** for Chain 138 once integration address is set and pools are created. **Yes** for cW* on chains 1, 10, 56, 100, 137 once the corresponding `CHAIN_*_DODO_*` and RPC env vars are set and the indexer runs for those chains.
+
+---
+
+## 3. MCP (ai-mcp-pmm-controller)
+
+**What it is:** MCP hub with read-only tools `dodo.get_pool_state`, `dodo.identify_pool_interface`, and optional risk/simulation. Pools must be in **allowlist**; state is read via a **pool profile** (expected view methods).
+
+| Pool scope | Accessible? | Requirement |
+|------------|-------------|-------------|
+| **Chain 138** | ✅ **Yes** (after allowlist) | (1) **Allowlist:** Add each pool address and base/quote token to `config/allowlist.json` with profile `dodo_pmm_v2_like`. (2) **MockDVMPool** was updated to expose `getOraclePrice()`, `_K_`, `_LP_FEE_RATE_` so the existing MCP profile works. Pools created from a **new** MockDVMFactory (deployed after this change) are MCP-ready; pools from an existing factory may need a new factory deploy to get the updated pool bytecode. (3) Run MCP with `CHAIN=138` and `RPC_URL` pointing to Chain 138. |
+| **cW* edge (each chain)** | ⚠️ **Per chain** | One MCP instance is single-chain (`CHAIN`, `RPC_URL`). For each of the 5 chains: run an MCP instance (or add multi-chain support), add that chain’s pool addresses to the allowlist, and use a profile that matches the pool interface (DODO v2–like or custom). |
+
+**Conclusion:** **Yes** for any pool **after** (1) allowlisting, (2) profile/interface alignment (Chain 138 needs mock profile or MockDVMPool stubs), (3) correct RPC per chain.
+
+---
+
+## 4. What to do so “all pools” are accessible
+
+### Standard DODO dashboard
+
+- **Chain 138:** Use a **custom dashboard** that uses your RPC + token-aggregation API (or direct contract reads). The standard DODO app will not show 138.
+- **cW*:** If you want them on the official DODO UI, deploy **official DODO** pools on supported chains; otherwise use your own UI fed by API/MCP.
+
+### API
+
+- **Chain 138:** Set `CHAIN_138_DODO_PMM_INTEGRATION` and run the indexer; no code change needed.
+- **cW*:** Chain configs and DODO env-driven entries for 1, 10, 56, 100, 137 are in `dex-factories.ts` and `chains.ts`. Set `CHAIN_*_DODO_PMM_INTEGRATION` or `CHAIN_*_DODO_POOL_MANAGER` and `CHAIN_*_RPC_URL` per chain and run the indexer for those chains.
+
+### MCP
+
+- **Chain 138:**  
+  - `MockDVMPool.sol` now includes `getOraclePrice()`, `_K_`, and `_LP_FEE_RATE_` so the default `dodo_pmm_v2_like` profile works.  
+  - Add each pool to `allowlist.json` with base/quote tokens and profile `dodo_pmm_v2_like`.  
+  - Run MCP with `CHAIN=138` and Chain 138 `RPC_URL`.
+- **cW* (each chain):**  
+  - Run an MCP instance per chain (or implement multi-chain in the server).  
+  - Allowlist all pool addresses for that chain.  
+  - Use a profile that matches the pool contract (e.g. `dodo_pmm_v2_like` for real DODO pools).
+
+---
+
+## 5. Summary table (all 61 pools)
+
+| Access | Chain 138 (10) | cW* (51 on 5 chains) |
+|--------|-----------------|----------------------|
+| **Standard DODO dashboard** | ❌ No (custom chain + Mock DVM) | ⚠️ Only if real DODO on supported chain |
+| **API** | ✅ Yes (set integration env, run indexer) | ✅ Yes when CHAIN_*_DODO_* and RPC env set for each chain |
+| **MCP** | ✅ Yes after allowlist + RPC (MockDVMPool has profile-compatible view methods) | ⚠️ Yes per chain after allowlist + profile + RPC |
+
+So: **all pools can be accessed via API and MCP** once the above config and code changes are in place; **they cannot all be accessed by the standard DODO dashboard** (138 never; cW* only in the special case above).
+
+---
+
+## References
+
+- [LIQUIDITY_POOLS_MASTER_MAP.md](LIQUIDITY_POOLS_MASTER_MAP.md) — Pool map 138 & 651940  
+- [POOLS_AND_NETWORKS_FULL_DESIGN.md](POOLS_AND_NETWORKS_FULL_DESIGN.md) — All 61 pools, 6 networks  
+- [AI_AGENTS_57XX_MCP_CONTRACTS_AND_CHAINS.md](../02-architecture/AI_AGENTS_57XX_MCP_CONTRACTS_AND_CHAINS.md) — MCP allowlist and chains  
+- [DODO_PMM_INTEGRATION.md](../../smom-dbis-138/docs/integration/DODO_PMM_INTEGRATION.md) — Pool creation and integration  
+- Token-aggregation: `smom-dbis-138/services/token-aggregation`, `src/config/dex-factories.ts`, `src/indexer/pool-indexer.ts`  
+- MCP: `ai-mcp-pmm-controller/config/allowlist.json`, `config/pool_profiles.json`, `config/server.py`
--- a/docs/11-references/README.md
+++ b/docs/11-references/README.md
@@ -1,47 +0,0 @@
-# Technical References
-
-**Last Updated:** 2026-02-12  
-**Document Version:** 1.0  
-**Status:** Active Documentation
-
---
-
-This directory contains technical reference documentation.
-
-## Documents
-
-### Reference Guides
- **[DEFI_ORACLE_META_MAINNET_PROJECT_DESCRIPTION.md](DEFI_ORACLE_META_MAINNET_PROJECT_DESCRIPTION.md)** - Reusable project descriptions (short / medium / long) for Ledger, Chainlist, CoinGecko, outreach
- **[../04-configuration/CHAIN138_WALLET_ECOSYSTEM_AND_RATIONALE.md](../04-configuration/CHAIN138_WALLET_ECOSYSTEM_AND_RATIONALE.md)** ⭐⭐⭐ - **Why** MetaMask Snap, **why** Ledger Live when we have App-Ethereum, Trust Wallet; single wallet overview and rationale
- **[LEDGER_BLOCKCHAIN_INTEGRATION_COMPLETE.md](LEDGER_BLOCKCHAIN_INTEGRATION_COMPLETE.md)** ⭐⭐ - Full Ledger Wallet blockchain integration (all 8 steps, gaps filled), deployment checklist, Chain 138 quick reference; use with [ADD_CHAIN138_TO_LEDGER_LIVE](../04-configuration/ADD_CHAIN138_TO_LEDGER_LIVE.md). **Public code review for Ledger:** [bis-innovations/LedgerLive](https://github.com/bis-innovations/LedgerLive)
- **[CONTRACT_NEXT_STEPS_LIST.md](CONTRACT_NEXT_STEPS_LIST.md)** - Single checklist of all next steps (done / operator / pending)
- **[CONTRACT_NEXT_STEPS_AND_RECOMMENDATIONS_COMPLETE.md](CONTRACT_NEXT_STEPS_AND_RECOMMENDATIONS_COMPLETE.md)** - All next steps (completed/operator/pending), operator checklist, and full recommendations/suggestions
- **[OPERATOR_ACTIONS.md](OPERATOR_ACTIONS.md)** - Remaining contract-related operator actions (on-chain check, Blockscout, .env reconcile)
- **[SMART_CONTRACTS_INVENTORY_ALL_CHAINS.md](SMART_CONTRACTS_INVENTORY_ALL_CHAINS.md)** ⭐⭐⭐ - **All** smart contracts, **all** chains, **all** projects/modules — deployed and not deployed
- **[CONTRACT_INVENTORY_AND_VERIFICATION.md](CONTRACT_INVENTORY_AND_VERIFICATION.md)** ⭐⭐⭐ - Deployed/undeployed contracts (Chain 138), 36-address on-chain check, Blockscout verification, deprecated addresses; Chain 138 deploy: use `--with-gas-price 1000000000`
- **[CONTRACT_ADDRESSES_REFERENCE.md](CONTRACT_ADDRESSES_REFERENCE.md)** ⭐⭐⭐ - Canonical contract address list (Chain 138), AddressMapper/MirrorManager (2026-02-12), and service env snippets
- **[EXPLORER_AND_BLOCKSCAN_REFERENCE.md](EXPLORER_AND_BLOCKSCAN_REFERENCE.md)** - Use explorer.d-bis.org for Chain 138; not blockscan.com
- **[CONTRACTS_TO_DEPLOY.md](CONTRACTS_TO_DEPLOY.md)** ⭐⭐ - Master list of contracts with deployment scripts and status
- **[VMID_IP_FIXED_REFERENCE.md](VMID_IP_FIXED_REFERENCE.md)** ⭐⭐ - Fixed permanent VMID→IP (2101, 2201, 5000). Do not change.
- **[GLOSSARY.md](GLOSSARY.md)** ⭐⭐⭐ - Comprehensive glossary of terms and acronyms
- **[DBIS_CORE_API_REFERENCE.md](DBIS_CORE_API_REFERENCE.md)** ⭐⭐ - DBIS Core API reference including Crypto.com OTC 2.0
- **[TOKEN_LIST_AUTHORING_GUIDE.md](TOKEN_LIST_AUTHORING_GUIDE.md)** ⭐⭐⭐ - Token list authoring and management guide
- **[CHAIN138_TOKEN_ADDRESSES.md](CHAIN138_TOKEN_ADDRESSES.md)** ⭐⭐ - ChainID 138 token contract addresses
- **[APT_PACKAGES_CHECKLIST.md](APT_PACKAGES_CHECKLIST.md)** ⭐ - APT packages checklist
- **[PATHS_REFERENCE.md](PATHS_REFERENCE.md)** ⭐ - Paths reference guide
- **[SCRIPT_REVIEW.md](SCRIPT_REVIEW.md)** ⭐ - Script review documentation
- **[TEMPLATE_BASE_WORKFLOW.md](TEMPLATE_BASE_WORKFLOW.md)** ⭐ - Template base workflow guide
-
-## Quick Reference
-
-**Reference Materials:**
- Package checklists
- Path references
- Script documentation
- Workflow templates
-
-## Related Documentation
-
- **[../01-getting-started/PREREQUISITES.md](/docs/01-getting-started/PREREQUISITES.md)** - Prerequisites
- **[../12-quick-reference/](../12-quick-reference/)** - Quick reference guides
-
--- a/docs/11-references/TOKENS_AND_NETWORKS_MINTABLE_TO_DEPLOYER.md
+++ b/docs/11-references/TOKENS_AND_NETWORKS_MINTABLE_TO_DEPLOYER.md
@@ -0,0 +1,203 @@
+# Tokens and Networks — Mintable to Deployer (Liquidity Pools & Bridges)
+
+**Last Updated:** 2026-03-01  
+**Purpose:** Single list of all tokens and networks where tokens **can be minted** (or otherwise credited) to the deployer address for funding PMM liquidity pools and bridges. Use this to fund all operator/LAN-only items (add liquidity, CCIP bridges, etc.).
+
+**Deployer address:** `0x4A666F96fC8764181194447A7dFdb7d471b301C8`
+
+---
+
+## Summary
+
+| Network | Chain ID | Tokens mintable to deployer | Mechanism |
+|---------|----------|-----------------------------|-----------|
+| **DeFi Oracle Meta Mainnet** | 138 | cUSDT, cUSDC, cEURC, cEURT, cGBPC, cGBPT, cAUDC, cJPYC, cCHFC, cCADC, cXAUC, cXAUT | Owner mint (CompliantFiatToken / CompliantUSDT / CompliantUSDC) |
+| **Cronos** | 25 | USDW, EURW, GBPW, AUDW, JPYW, CHFW, CADW (D-WIN W) | MintController (MINTER_ROLE + reserve); conditional |
+| **All other chains** | 1, 56, 100, 137, 10, 42161, 8453, 43114, 42220, 1111, 651940 | — | Acquire via wrap, bridge, or DEX (see § Acquire) |
+
+---
+
+## 1. Chain 138 — Owner mint (all compliant tokens)
+
+On **Chain 138**, the deployer is **owner** of all compliant token contracts deployed by this repo. Each has `mint(address to, uint256 amount) public onlyOwner`. Mint to deployer by calling `mint(deployerAddress, amount)` from the deployer EOA.
+
+### 1.1 Token addresses and decimals (Chain 138)
+
+| Symbol | Contract address | Decimals | Use for |
+|--------|------------------|----------|---------|
+| **cUSDT** | `0x93E66202A11B1772E55407B32B44e5Cd8eda7f22` | 6 | PMM pools cUSDT/cUSDC, cUSDT/USDT |
+| **cUSDC** | `0xf22258f57794CC8E06237084b353Ab30fFfa640b` | 6 | PMM pools cUSDT/cUSDC, cUSDC/USDC |
+| **cEURC** | `0x8085961F9cF02b4d800A3c6d386D31da4B34266a` | 6 | Future pools / bridge |
+| **cEURT** | `0xdf4b71c61E5912712C1Bdd451416B9aC26949d72` | 6 | Future pools / bridge |
+| **cGBPC** | `0x003960f16D9d34F2e98d62723B6721Fb92074aD2` | 6 | Future pools / bridge |
+| **cGBPT** | `0x350f54e4D23795f86A9c03988c7135357CCaD97c` | 6 | Future pools / bridge |
+| **cAUDC** | `0xD51482e567c03899eecE3CAe8a058161FD56069D` | 6 | Future pools / bridge |
+| **cJPYC** | `0xEe269e1226a334182aace90056EE4ee5Cc8A6770` | 6 | Future pools / bridge |
+| **cCHFC** | `0x873990849DDa5117d7C644f0aF24370797C03885` | 6 | Future pools / bridge |
+| **cCADC** | `0x54dBd40cF05e15906A2C21f600937e96787f5679` | 6 | Future pools / bridge |
+| **cXAUC** | `0x290E52a8819A4fbD0714E517225429aA2B70EC6b` | 6 | Future pools / bridge |
+| **cXAUT** | `0x94e408E26c6FD8F4ee00b54dF19082FDA07dC96E` | 6 | Future pools / bridge |
+
+**Decimals:** All use 6 decimals. Amount in base units = amount × 10^6 (e.g. 1_000_000 = 1 token).
+
+### 1.2 How to mint on Chain 138
+
+**Option A — cUSDT / cUSDC (existing script):**
+
+```bash
+cd smom-dbis-138
+source .env
+# Mint 749M of each to deployer (or use custom amount/recipient)
+./scripts/mint-to-750m.sh both 0x4A666F96fC8764181194447A7dFdb7d471b301C8
+# Or per token:
+./scripts/mint-to-750m.sh usdt 0x4A666F96fC8764181194447A7dFdb7d471b301C8
+./scripts/mint-to-750m.sh usdc 0x4A666F96fC8764181194447A7dFdb7d471b301C8
+```
+
+**Option B — Any compliant token via cast (owner = deployer):**
+
+```bash
+# From smom-dbis-138, with PRIVATE_KEY and RPC_URL_138 set
+DEPLOYER=0x4A666F96fC8764181194447A7dFdb7d471b301C8
+# Example: mint 1,000,000 cEURC (1e6 * 1e6 = 1000000000000 base units)
+cast send 0x8085961F9cF02b4d800A3c6d386D31da4B34266a \
+  "mint(address,uint256)" "$DEPLOYER" 1000000000000 \
+  --rpc-url "$RPC_URL_138" --private-key "$PRIVATE_KEY"
+```
+
+Repeat for each token and desired amount. Replace the token address with the one from the table above.
+
+### 1.3 WETH and LINK on Chain 138
+
+| Token | Address | Mintable? | How to get balance for deployer |
+|-------|---------|-----------|----------------------------------|
+| **WETH** | `0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2` | No (standard wrap) | Wrap native ETH: send ETH to WETH contract and call `deposit()` (or use a wrapper script). |
+| **LINK** | `0xb7721dD53A8c629d9f1Ba31a5819AFe250002b03` | Depends (mock vs canonical) | If Chain 138 LINK is a mock with `mint`, call `mint(deployer, amount)`. Otherwise acquire via bridge or CCIP. |
+
+---
+
+## 2. Cronos (Chain 25) — D-WIN W tokens (MintController)
+
+D-WIN W tokens (USDW, EURW, GBPW, AUDW, JPYW, CHFW, CADW) on **Cronos** are **ISO4217WToken** contracts. Minting is done via **MintController**, which requires:
+
+- Caller has **MINTER_ROLE** on the MintController.
+- Token is **approved** in the controller (`isApprovedToken[token]`).
+- **Reserve oracle** and **compliance guard** allow the mint (reserve ≥ new supply).
+
+If the deployer (or an EOA you control) is the admin of the MintController and has MINTER_ROLE, you can mint to the deployer by calling:
+
+```solidity
+MintController.mint(token, deployerAddress, amount, settlementId)
+```
+
+Token addresses on Cronos (from [TOKEN_CATEGORIES_CANONICAL](TOKEN_CATEGORIES_CANONICAL.md) / [DEPLOYED_COINS_TOKENS_AND_NETWORKS](DEPLOYED_COINS_TOKENS_AND_NETWORKS.md)):
+
+| Symbol | Address (Cronos) | Decimals |
+|--------|------------------|----------|
+| USDW | `0x948690147D2e50ffe50C5d38C14125aD6a9FA036` | 2 |
+| EURW | `0x58a8D8F78F1B65c06dAd7542eC46b299629A60dd` | 2 |
+| GBPW | `0xFb4B6Cc81211F7d886950158294A44C312abCA29` | 2 |
+| AUDW | `0xf9f5D0ACD71C76F9476F10B3F3d3E201F0883C68` | 2 |
+| JPYW | `0xeE17bB0322383fecCA2784fbE2d4CD7d02b1905B` | 2 |
+| CHFW | `0xc9750828124D4c10e7a6f4B655cA8487bD3842EB` | 2 |
+| CADW | `0x328Cd365Bb35524297E68ED28c6fF2C9557d1363` | 2 |
+
+**Note:** You must have the MintController address for Cronos, have MINTER_ROLE, and have updated the reserve oracle so that `canMint(token, amount)` returns true. If the D-WIN system on Cronos is operated by another party, request a mint to the deployer from them.
+
+---
+
+## 3. Tokens that must be acquired (not minted to deployer)
+
+These are needed for liquidity pools and bridges but **cannot** be minted by the deployer; they must be obtained by wrap, bridge, or DEX.
+
+### 3.1 By network
+
+| Network | Chain ID | Tokens needed for pools/bridges | How to get |
+|---------|----------|----------------------------------|------------|
+| **Ethereum Mainnet** | 1 | USDT, USDC, WETH, LINK | DEX, CEX, or bridge from 138; WETH = wrap ETH. |
+| **ALL Mainnet (Alltra)** | 651940 | AUSDT, USDC, WETH, WALL | Ecosystem tokens; acquire via Alltra DEX/bridge or partner. |
+| **Cronos** | 25 | Native CRO (gas), LINK (if funding CCIP) | CRO from exchange; LINK from bridge/DEX. |
+| **BSC** | 56 | BNB (gas), USDT, USDC, WETH, LINK | DEX/CEX; wrap BNB for WBNB if needed. |
+| **Gnosis** | 100 | xDAI (gas), LINK | Bridge or DEX. |
+| **Polygon** | 137 | MATIC (gas), USDT, USDC, WETH, LINK | DEX/bridge. |
+| **Optimism** | 10 | ETH (gas), USDT, USDC, WETH, LINK | Bridge/DEX. |
+| **Arbitrum** | 42161 | ETH (gas), USDT, USDC, WETH, LINK | Bridge/DEX. |
+| **Base** | 8453 | ETH (gas), USDT, USDC, WETH, LINK | Bridge/DEX. |
+| **Avalanche** | 43114 | AVAX (gas), USDT, USDC, WETH, LINK | Bridge/DEX. |
+| **Celo** | 42220 | CELO (gas), LINK | Bridge/DEX. |
+| **Wemix** | 1111 | WEMIX (gas), LINK | Bridge/DEX. |
+
+### 3.2 CCIP bridge funding (LINK)
+
+For **CCIP bridges** (138 ↔ Mainnet, 138 ↔ Gnosis/Cronos/Celo/Wemix, etc.), the **bridge contract** on each chain must hold **LINK** to pay fees. The deployer does not mint LINK on public chains; you:
+
+1. Acquire LINK on the target chain (e.g. from Mainnet and bridge, or DEX on that chain).
+2. Transfer LINK from the deployer to the **bridge contract address** (e.g. `cast send ... transfer(bridgeAddress, amount)`).
+
+Recommended: **~10 LINK per bridge** for initial operations. See [CONFIG_READY_CHAINS_COMPLETION_RUNBOOK](../07-ccip/CONFIG_READY_CHAINS_COMPLETION_RUNBOOK.md) § Fund bridges with LINK.
+
+### 3.3 Official USDT / USDC on Chain 138 (PMM pools)
+
+PMM pools **cUSDT/USDT** and **cUSDC/USDC** use an “official” USDT/USDC pair on Chain 138. If that pair is a separate contract (e.g. bridged or canonical), the deployer cannot mint it; acquire from a bridge or use the compliant side only. If the “official” address is set to cUSDT/cUSDC for testing, then mint cUSDT/cUSDC as in §1.
+
+---
+
+## 4. Suggested mint order for liquidity and bridges
+
+1. **Chain 138 — Compliant tokens**  
+   Mint cUSDT and cUSDC (and optionally cEURC, cEURT, etc.) to the deployer in the amounts needed for:
+   - [ADD_LIQUIDITY_PMM_CHAIN138_RUNBOOK](../03-deployment/ADD_LIQUIDITY_PMM_CHAIN138_RUNBOOK.md): base/quote for the three PMM pools (cUSDT/cUSDC, cUSDT/USDT, cUSDC/USDC).
+   - Use [check-deployer-balance-chain138-and-funding-plan.sh](../../scripts/deployment/check-deployer-balance-chain138-and-funding-plan.sh) to see current balances; mint additional so that half of (current + minted) can be allocated to liquidity per [DEPLOYER_WALLET_FUNDING_PLAN_PMM_POOLS](DEPLOYER_WALLET_FUNDING_PLAN_PMM_POOLS.md).
+
+2. **Chain 138 — WETH**  
+   Ensure deployer has enough native ETH, then wrap the portion needed for WETH-denominated use (e.g. future pools or bridge).
+
+3. **Chain 138 — LINK**  
+   If LINK on 138 is mintable (mock), mint to deployer for local testing. For production, acquire LINK and send to the deployer or directly to bridge contracts as needed.
+
+4. **Cronos — D-WIN W**  
+   If you operate MintController and reserve, mint USDW, EURW, etc. to the deployer for Cronos-side liquidity or testing.
+
+5. **Other chains**  
+   Acquire native gas and LINK (and any USDT/USDC) per §3; then run add-liquidity and fund-ccip-bridges scripts from the operator/LAN runbooks.
+
+---
+
+## 5. Quick reference — mint commands (Chain 138)
+
+```bash
+# Load env (from smom-dbis-138 or repo root with RPC_URL_138 and PRIVATE_KEY)
+source smom-dbis-138/.env
+DEPLOYER=0x4A666F96fC8764181194447A7dFdb7d471b301C8
+
+# cUSDT – 1M tokens (6 decimals)
+cast send 0x93E66202A11B1772E55407B32B44e5Cd8eda7f22 "mint(address,uint256)" $DEPLOYER 1000000000000 --rpc-url "$RPC_URL_138" --private-key "$PRIVATE_KEY"
+
+# cUSDC – 1M tokens
+cast send 0xf22258f57794CC8E06237084b353Ab30fFfa640b "mint(address,uint256)" $DEPLOYER 1000000000000 --rpc-url "$RPC_URL_138" --private-key "$PRIVATE_KEY"
+
+# cEURC – 1M tokens
+cast send 0x8085961F9cF02b4d800A3c6d386D31da4B34266a "mint(address,uint256)" $DEPLOYER 1000000000000 --rpc-url "$RPC_URL_138" --private-key "$PRIVATE_KEY"
+
+# (Repeat for cEURT, cGBPC, cGBPT, cAUDC, cJPYC, cCHFC, cCADC, cXAUC, cXAUT with their addresses from §1.1)
+```
+
+---
+
+## 6. Tokens the deployer deployed on other chains
+
+For a list of **token contracts** the deployer wallet deployed on blockchains **other than 138** (Cronos D-WIN W, WETH9/WETH10 on L2s), see [TOKENS_DEPLOYER_DEPLOYED_ON_OTHER_CHAINS](TOKENS_DEPLOYER_DEPLOYED_ON_OTHER_CHAINS.md).
+
+---
+
+## 7. References
+
+| Document | Purpose |
+|----------|---------|
+| [TOKENS_DEPLOYER_DEPLOYED_ON_OTHER_CHAINS](TOKENS_DEPLOYER_DEPLOYED_ON_OTHER_CHAINS.md) | Tokens deployer deployed on other blockchains (Cronos, L2s) |
+| [TOKEN_CATEGORIES_CANONICAL](TOKEN_CATEGORIES_CANONICAL.md) | Token categories and symbols |
+| [CHAIN138_TOKEN_ADDRESSES](CHAIN138_TOKEN_ADDRESSES.md) | Chain 138 token addresses |
+| [DEPLOYED_COINS_TOKENS_AND_NETWORKS](DEPLOYED_COINS_TOKENS_AND_NETWORKS.md) | Tokens by chain |
+| [DEPLOYER_WALLET_FUNDING_PLAN_PMM_POOLS](DEPLOYER_WALLET_FUNDING_PLAN_PMM_POOLS.md) | Funding plan (50% for PMM) |
+| [ADD_LIQUIDITY_PMM_CHAIN138_RUNBOOK](../03-deployment/ADD_LIQUIDITY_PMM_CHAIN138_RUNBOOK.md) | Add liquidity to PMM pools |
+| [CONFIG_READY_CHAINS_COMPLETION_RUNBOOK](../07-ccip/CONFIG_READY_CHAINS_COMPLETION_RUNBOOK.md) | CCIP bridges and LINK funding |
--- a/docs/11-references/TOKENS_DEPLOYER_DEPLOYED_ON_OTHER_CHAINS.md
+++ b/docs/11-references/TOKENS_DEPLOYER_DEPLOYED_ON_OTHER_CHAINS.md
@@ -0,0 +1,153 @@
+# Tokens the Deployer Wallet Deployed on Other Blockchains
+
+**Last Updated:** 2026-03-01  
+**Purpose:** List all **token contracts** (ERC-20) that the deployer wallet (`0x4A666F96fC8764181194447A7dFdb7d471b301C8`) deployed on blockchains **other than Chain 138**. Use this to know where the deployer is contract owner/admin and can mint or manage tokens for liquidity and bridges.
+
+**Deployer address:** `0x4A666F96fC8764181194447A7dFdb7d471b301C8`
+
+---
+
+## Quick answer: cW*, WETH9/WETH10, ETH, c*, AUSDT on other chains?
+
+| Token type | Deployed by our deployer on other chains? | Where / notes |
+|------------|------------------------------------------|----------------|
+| **cW*** (compliant wrapped, e.g. cWUSDT, cWUSDC) | **Yes** (optional) | Use DeployCWTokens.s.sol and --deploy-cw; set CW_BRIDGE_ADDRESS. CompliantWrappedToken with MINTER/BURNER for bridge. |
+| **WETH9 / WETH10** | **Yes** | **Cronos (25):** documented addresses. **BSC, Polygon, Gnosis, Avalanche, Base, Arbitrum, Optimism:** only if DeployAll.s.sol was run with each chain’s RPC (addresses in .env). **Mainnet (1):** DeployAll skips WETH; uses .env. Wrap-only (no mint). |
+| **ETH** | **No** | Native gas token; not a contract. |
+| **c*** (compliant, e.g. cUSDT, cUSDC, cEURC) | **Yes** (optional) | Chain 138: DeployCompliantFiatTokens. Other chains: DeployCompliantFiatTokensForChain.s.sol and --deploy-c. |
+| **AUSDT** | **No** | ALL Mainnet (651940) ecosystem token; deployed by Alltra, not by this repo’s deployer. |
+
+---
+
+## Summary
+
+| Chain | Chain ID | Tokens deployed by deployer | Script | Mint / control |
+|-------|----------|-----------------------------|--------|-----------------|
+| **Cronos** | 25 | **USDW, EURW, GBPW, AUDW, JPYW, CHFW, CADW** (7 D-WIN W) + optionally **WETH9, WETH10** | DeployISO4217WSystem.s.sol; DeployAll.s.sol | Mint via MintController (W tokens); WETH = wrap only |
+| **Ethereum Mainnet** | 1 | **WETH9, WETH10** only if deployed by this repo (else from .env) | DeployAll.s.sol (skips WETH on Mainnet by default) | Wrap only |
+| **BSC, Polygon, Gnosis, Avalanche, Base, Arbitrum, Optimism** | 56, 137, 100, 43114, 8453, 42161, 10 | **WETH9, WETH10** (if DeployAll was run with each chain’s RPC) | DeployAll.s.sol | Wrap only; addresses in .env per chain |
+| **ALL Mainnet (Alltra)** | 651940 | None from this repo (AUSDT, USDC, WETH, WALL are ecosystem contracts) | — | — |
+
+**Chain 138** is not included here; see [CHAIN138_TOKEN_ADDRESSES](CHAIN138_TOKEN_ADDRESSES.md) and [TOKENS_AND_NETWORKS_MINTABLE_TO_DEPLOYER](TOKENS_AND_NETWORKS_MINTABLE_TO_DEPLOYER.md) for tokens the deployer deployed on 138.
+
+---
+
+## 1. Cronos (Chain 25) — D-WIN W tokens + WETH9/WETH10
+
+The deployer can deploy the full **ISO-4217 W** system and optionally **WETH9/WETH10** on Cronos by running the scripts with Cronos RPC. Documentation states these are **deployed** on Cronos.
+
+### 1.1 D-WIN W tokens (DeployISO4217WSystem.s.sol)
+
+Deployed with:  
+`forge script script/deploy/iso4217w/DeployISO4217WSystem.s.sol:DeployISO4217WSystem --rpc-url $CRONOS_RPC --broadcast --private-key $PRIVATE_KEY`
+
+| Symbol | Name | Contract address (Cronos) | Decimals | Admin / mint |
+|--------|------|---------------------------|----------|--------------|
+| **USDW** | USD W Token | `0x948690147D2e50ffe50C5d38C14125aD6a9FA036` | 2 | Mint via MintController (admin has MINTER_ROLE) |
+| **EURW** | EUR W Token | `0x58a8D8F78F1B65c06dAd7542eC46b299629A60dd` | 2 | Same |
+| **GBPW** | GBP W Token | `0xFb4B6Cc81211F7d886950158294A44C312abCA29` | 2 | Same |
+| **AUDW** | AUD W Token | `0xf9f5D0ACD71C76F9476F10B3F3d3E201F0883C68` | 2 | Same |
+| **JPYW** | JPY W Token | `0xeE17bB0322383fecCA2784fbE2d4CD7d02b1905B` | 2 | Same |
+| **CHFW** | CHF W Token | `0xc9750828124D4c10e7a6f4B655cA8487bD3842EB` | 2 | Same |
+| **CADW** | CAD W Token | `0x328Cd365Bb35524297E68ED28c6fF2C9557d1363` | 2 | Same |
+
+**Minting:** The deployer (admin) has **MINTER_ROLE** on **MintController**. Mint to the deployer by calling `MintController.mint(tokenAddress, deployerAddress, amount, settlementId)` after approving the token in the controller and satisfying the reserve oracle. See [TOKENS_AND_NETWORKS_MINTABLE_TO_DEPLOYER](TOKENS_AND_NETWORKS_MINTABLE_TO_DEPLOYER.md) § Cronos.
+
+**Source:** [DEPLOYED_COINS_TOKENS_AND_NETWORKS](DEPLOYED_COINS_TOKENS_AND_NETWORKS.md), [TOKEN_CATEGORIES_CANONICAL](TOKEN_CATEGORIES_CANONICAL.md), [canonical-tokens.ts](../../smom-dbis-138/services/token-aggregation/src/config/canonical-tokens.ts).
+
+### 1.2 WETH9 / WETH10 on Cronos (DeployAll.s.sol)
+
+If **WETH9_CRONOS** / **WETH10_CRONOS** were not set in `.env`, running `DeployAll.s.sol` with Cronos RPC deploys **WETH** and **WETH10** contracts. Documented addresses on Cronos:
+
+| Symbol | Address (Cronos) | Notes |
+|--------|------------------|--------|
+| WETH9 | `0x99B3511A2d315A497C8112C1fdd8D508d4B1E506` | Wrap-only (deposit native CRO) |
+| WETH10 | `0x3304b747E565a97ec8AC220b0B6A1f6ffDB837e6` | Wrap-only |
+
+These are not mintable to an address; users wrap native CRO to get WETH.
+
+---
+
+## 2. Ethereum Mainnet (Chain 1)
+
+**DeployAll.s.sol** on Mainnet is configured to **skip** deploying WETH9/WETH10 and the CCIP bridges (they are taken from `.env`). The only contract it deploys is **CCIPLogger** (and that is a logger, not a token).
+
+So in normal setup, **no token contracts** on Ethereum Mainnet are deployed by this deployer from this repo; WETH and others are canonical/mainnet contracts. If at some point WETH9/WETH10 were deployed by this deployer on Mainnet, their addresses would be in `WETH9_MAINNET` / `WETH10_MAINNET` in `.env`.
+
+---
+
+## 3. BSC, Polygon, Gnosis, Avalanche, Base, Arbitrum, Optimism (56, 137, 100, 43114, 8453, 42161, 10)
+
+**DeployAll.s.sol** is chain-agnostic: when run with a given chain’s RPC (and chain id 56, 137, 100, etc.), it deploys:
+
+- **WETH9** (if not set in .env for that chain)
+- **WETH10** (if not set in .env for that chain)
+- **CCIPWETH9Bridge**, **CCIPWETH10Bridge**
+- **CCIPLogger** (placeholder)
+
+So the **tokens** the deployer may have deployed on these chains are **WETH9** and **WETH10** only, and only if the script was run without pre-set addresses. Deployed addresses would be stored in `.env` (e.g. `WETH9_BSC`, `WETH10_BSC`, `WETH9_POLYGON`, …), not in the repo as a single canonical list.
+
+**Mint:** WETH9/WETH10 are wrap-only (no arbitrary mint to deployer); users deposit native gas to get WETH.
+
+**To confirm** on a specific chain: check `smom-dbis-138/.env` for `WETH9_<CHAIN>`, `WETH10_<CHAIN>` and verify on the chain’s explorer that the deployer (0x4A66…) is the deployer/owner of those contracts.
+
+---
+
+## 4. ALL Mainnet (651940)
+
+Tokens on ALL Mainnet (AUSDT, USDC, WETH, WALL, etc.) are **ecosystem/Alltra** contracts, not deployed by this repo’s deployer. The deployer did **not** deploy token contracts on 651940 from this codebase.
+
+---
+
+## 5. Script reference (deployer-deployed tokens on other chains)
+
+| Script | Chains | Tokens deployed |
+|--------|--------|------------------|
+| **`scripts/deployment/deploy-tokens-and-weth-all-chains-skip-canonical.sh`** | 1, 25, 56, 137, 100, 43114, 8453, 42161, 10, 651940 | DeployAll (WETH9/WETH10) when not set; Cronos ISO-4217 W when USDW missing; **--deploy-c** runs cUSDT/cUSDC per chain (skip 138, 1); **--deploy-cw** runs cWUSDT/cWUSDC per chain; 651940 env validation only. Options: `--dry-run`, `--chain 25 56`, `--no-iso4217`, `--iso4217-only`, `--deploy-c`, `--deploy-cw`. |
+| `script/deploy/DeployCompliantFiatTokensForChain.s.sol` | Any (e.g. 56, 137, 100) | cUSDT, cUSDC; optional cEURC, cEURT, … via env |
+| `script/deploy/DeployCWTokens.s.sol` | Any | cWUSDT, cWUSDC (CompliantWrappedToken); requires CW_BRIDGE_ADDRESS |
+| `script/deploy/iso4217w/DeployISO4217WSystem.s.sol` | Any (typically Cronos 25) | USDW, EURW, GBPW, AUDW, JPYW, CHFW, CADW + MintController, TokenRegistry, etc. |
+| `script/DeployAll.s.sol` | 25, 56, 137, 100, 43114, 8453, 42161, 10 | WETH9, WETH10 (if not in .env) |
+| `script/DeployAll.s.sol` | 1 (Mainnet) | None (uses .env WETH9/WETH10); only CCIPLogger |
+
+---
+
+## 6. “Out of scope” → within scope (implemented)
+
+The following items have been **brought within scope** and are implemented.
+
+### 6.1 c* (compliant tokens: cUSDT, cUSDC, cEURC, …) on other chains — **Implemented**
+
+- **Script:** `smom-dbis-138/script/deploy/DeployCompliantFiatTokensForChain.s.sol`  
+  Deploys cUSDT, cUSDC (default), and optionally cEURC, cEURT, cGBPC, … via env flags (`DEPLOY_CEURC=1`, etc.). Uses regular `new` deployment (no CREATE2 required). Chain-agnostic: run with any RPC and `--chain-id`.
+- **Env:** `CUSDT_<CHAIN>`, `CUSDC_<CHAIN>` (e.g. `CUSDT_BSC`, `CUSDC_POLYGON`). Optional: `OWNER`, `ADMIN`, `DEPLOY_CEURC`, `DEPLOY_CEURT`, etc.
+- **All-chains script:** `deploy-tokens-and-weth-all-chains-skip-canonical.sh --deploy-c`  
+  For each chain (except 138 and 1), if `CUSDT_<CHAIN>` / `CUSDC_<CHAIN>` are unset, runs `DeployCompliantFiatTokensForChain` and prompts to set addresses in .env.
+
+### 6.2 cW* (compliant wrapped: cWUSDT, cWUSDC) on public chains — **Implemented**
+
+- **Contract:** `smom-dbis-138/contracts/tokens/CompliantWrappedToken.sol`  
+  ERC-20 with `MINTER_ROLE` and `BURNER_ROLE`; only minter can mint, only burner can burn (e.g. bridge).
+- **Script:** `smom-dbis-138/script/deploy/DeployCWTokens.s.sol`  
+  Deploys cWUSDT and cWUSDC, grants `MINTER_ROLE` and `BURNER_ROLE` to `CW_BRIDGE_ADDRESS`.
+- **Env:** `CW_BRIDGE_ADDRESS` (required for deploy) or per-chain `CW_BRIDGE_<CHAIN>`; after deploy set `CWUSDT_<CHAIN>`, `CWUSDC_<CHAIN>`.
+- **All-chains script:** `deploy-tokens-and-weth-all-chains-skip-canonical.sh --deploy-cw`  
+  For each chain, if `CWUSDT_<CHAIN>` is unset and bridge address is set, runs `DeployCWTokens` and prompts to set addresses in .env.
+
+### 6.3 AUSDT and ALL Mainnet (651940) — **Implemented (env validation only)**
+
+- **All-chains script:** Chain **651940** is in the chain list. The script does **not** deploy tokens on 651940; it only runs **env validation**: if `CHAIN_651940_RPC` is set, it checks/reminds to set `AUSDT_ADDRESS_651940` (ecosystem token; not deployed by this repo).
+- **Env:** `CHAIN_651940_RPC` (or `ALL_MAINNET_RPC`), `AUSDT_ADDRESS_651940`.
+
+---
+
+## 7. References
+
+| Document | Purpose |
+|----------|---------|
+| [TOKENS_AND_NETWORKS_MINTABLE_TO_DEPLOYER](TOKENS_AND_NETWORKS_MINTABLE_TO_DEPLOYER.md) | How to mint to deployer (138 owner mint; Cronos MintController; acquire elsewhere) |
+| [TOKEN_CONTRACT_DEPLOYMENTS_REMAINING](TOKEN_CONTRACT_DEPLOYMENTS_REMAINING.md) | Remaining token deployments (cW* §3, etc.) |
+| [DEPLOYED_COINS_TOKENS_AND_NETWORKS](DEPLOYED_COINS_TOKENS_AND_NETWORKS.md) | Networks and token addresses by chain |
+| [TOKEN_CATEGORIES_CANONICAL](TOKEN_CATEGORIES_CANONICAL.md) | Token categories (D-WIN W, cW*, etc.) |
+| [DEPLOYER_WALLET_FUNDING_PLAN_PMM_POOLS](DEPLOYER_WALLET_FUNDING_PLAN_PMM_POOLS.md) | Deployer address and funding plan |
+| [smom-dbis-138/docs/deployment/DEPLOYED_CONTRACTS_OVERVIEW.md](../../smom-dbis-138/docs/deployment/DEPLOYED_CONTRACTS_OVERVIEW.md) | Contract deployment status (incl. ISO4217W Cronos) |
--- a/docs/11-references/TOKEN_CATEGORIES_CANONICAL.md
+++ b/docs/11-references/TOKEN_CATEGORIES_CANONICAL.md
@@ -0,0 +1,133 @@
+# Token Categories — Canonical Reference
+
+**Last Updated:** 2026-02-28  
+**Status:** Authoritative list of token categories for Chain 138, ALL Mainnet, compliant wrapped (cW*), and D-WIN W tokens.
+
+---
+
+## 1. Canonical 138 Compliant
+
+Tokens native to or deployed on **ChainID 138** (DeFi Oracle Meta Mainnet): native gas token plus wrapped and compliant M1 tokens.
+
+| Symbol | Description | Chain 138 address / status |
+|--------|-------------|----------------------------|
+| **Native ETH** | Gas token | — |
+| **WETH** | Wrapped Ether | `0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2` |
+| **WETH10** | Wrapped Ether v10 | `0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9f` |
+| **LINK** | Chainlink Token | `0xb7721dD53A8c629d9f1Ba31a5819AFe250002b03` |
+| **cUSDT** | Compliant Tether USD | `0x93E66202A11B1772E55407B32B44e5Cd8eda7f22` |
+| **cUSDC** | Compliant USD Coin | `0xf22258f57794CC8E06237084b353Ab30fFfa640b` |
+| **cEURT** | Compliant Tether EUR | Deploy / env; see canonical-tokens.ts |
+| **cEURC** | Compliant Euro Coin | Deploy / env; see canonical-tokens.ts |
+| **cGBPT** | Compliant Tether GBP | Deploy / env |
+| **cGBPC** | Compliant Pound Sterling | Deploy / env |
+| **cAUDT** | Compliant Tether AUD | Deploy / env |
+| **cAUDC** | Compliant Australian Dollar | Deploy / env |
+| **cJPYT** | Compliant Tether JPY | Deploy / env |
+| **cJPYC** | Compliant Japanese Yen | Deploy / env |
+| **cCHFT** | Compliant Tether CHF | Deploy / env |
+| **cCHFC** | Compliant Swiss Franc | Deploy / env |
+| **cCADT** | Compliant Tether CAD | Deploy / env |
+| **cCADC** | Compliant Canadian Dollar (Coin) | Deploy / env |
+| **cAUSDT** | Compliant Alltra/USD T | Deploy / env (e.g. ALL Mainnet bridge) |
+
+**Source of addresses:** [CHAIN138_TOKEN_ADDRESSES](CHAIN138_TOKEN_ADDRESSES.md), [canonical-tokens.ts](../../smom-dbis-138/services/token-aggregation/src/config/canonical-tokens.ts) (FALLBACK_ADDRESSES + env).
+
+---
+
+## 2. ALL Mainnet (Alltra)
+
+Tokens on **ChainID 651940** (ALL Mainnet / Alltra): native gas token and ecosystem tokens.
+
+| Symbol | Description | Chain 651940 address |
+|--------|-------------|------------------------|
+| **Native** | Gas token | — |
+| **AUSDT** | Alltra USD Token | `0x015B1897Ed5279930bC2Be46F661894d219292A6` |
+| **USDT** | AUSDT (alt) | `0x66D8Efa0AF63B0e84eb1Dd72bf00f00cd1e2234e` |
+| **USDC** | AUSDC | `0xa95EeD79f84E6A0151eaEb9d441F9Ffd50e8e881` |
+| **WETH** | Wrapped Ether | `0x798F6762BB40d6801A593459d08F890603D3979C` |
+| **WALL** | Wrapped Alltra | `0x2da2b8f961F161ab6320acB3377e2e844a3C3ce4` |
+| **ACADT** | Alltra CAD (Tether-style) | Deploy / env |
+
+**Source:** [DEPLOYED_COINS_TOKENS_AND_NETWORKS](DEPLOYED_COINS_TOKENS_AND_NETWORKS.md).
+
+---
+
+## 3. Compliant Wrapped Tokens for Public Blockchains (cW*)
+
+Bridged representations of Canonical 138 Compliant tokens on **public chains** (Ethereum, BSC, Polygon, etc.). Naming: **cW** + currency/type (e.g. cWUSDT = wrapped compliant USDT on public chain).
+
+| Symbol | Description |
+|--------|-------------|
+| **cWUSDT** | Wrapped cUSDT (public chain) |
+| **cWEURT** | Wrapped cEURT |
+| **cWGBPT** | Wrapped cGBPT |
+| **cWAUDT** | Wrapped cAUDT |
+| **cWJPYT** | Wrapped cJPYT |
+| **cWCHFT** | Wrapped cCHFT |
+| **cWCADT** | Wrapped cCADT |
+| **cWUSDC** | Wrapped cUSDC |
+| **cWEURC** | Wrapped cEURC |
+| **cWGBPC** | Wrapped cGBPC |
+| **cWAUDC** | Wrapped cAUDC |
+| **cWJPYC** | Wrapped cJPYC |
+| **cWCHFC** | Wrapped cCHFC |
+| **cWCADC** | Wrapped cCADC |
+| **cWUSDW** | Wrapped USDW (D-WIN W) |
+| **cWEURW** | Wrapped EURW |
+| **cWGBPW** | Wrapped GBPW |
+| **cWAUDW** | Wrapped AUDW |
+| **cWJPYW** | Wrapped JPYW |
+| **cWCHFW** | Wrapped CHFW |
+| **cWCADW** | Wrapped CADW |
+
+**Context:** M1 tokens on Chain 138 (cUSDT, cUSDC, cEURT, cEURC, etc.) are bridged to public chains as **cW*** wrappers; single-sided PMM edge pools (cW* / USDC, cW* / USDT) and bot-driven mesh maintain the peg. See [cross-chain-pmm-lps](../../cross-chain-pmm-lps/README.md), [LIQUIDITY_POOLS_MASTER_MAP](LIQUIDITY_POOLS_MASTER_MAP.md) § Public-chain cW* stabilization.
+
+---
+
+## 4. D-WIN W Tokens
+
+**ISO-4217 W** tokens (D-WIN W): multi-currency W tokens deployed e.g. on Cronos (Chain 25) and optionally Chain 138 / 651940.
+
+| Symbol | Description | Cronos (25) address |
+|--------|-------------|----------------------|
+| **USDW** | USD W Token | `0x948690147D2e50ffe50C5d38C14125aD6a9FA036` |
+| **EURW** | EUR W Token | `0x58a8D8F78F1B65c06dAd7542eC46b299629A60dd` |
+| **GBPW** | GBP W Token | `0xFb4B6Cc81211F7d886950158294A44C312abCA29` |
+| **AUDW** | AUD W Token | `0xf9f5D0ACD71C76F9476F10B3F3d3E201F0883C68` |
+| **JPYW** | JPY W Token | `0xeE17bB0322383fecCA2784fbE2d4CD7d02b1905B` |
+| **CHFW** | CHF W Token | `0xc9750828124D4c10e7a6f4B655cA8487bD3842EB` |
+| **CADW** | CAD W Token | `0x328Cd365Bb35524297E68ED28c6fF2C9557d1363` |
+
+**Source:** [DEPLOYED_COINS_TOKENS_AND_NETWORKS](DEPLOYED_COINS_TOKENS_AND_NETWORKS.md) § Chain 25, [canonical-tokens.ts](../../smom-dbis-138/services/token-aggregation/src/config/canonical-tokens.ts) (FALLBACK_ADDRESSES).
+
+---
+
+## Summary table
+
+| Category | Scope | Examples |
+|----------|--------|----------|
+| **1. Canonical 138 Compliant** | Chain 138 native + WETH, WETH10, LINK, cUSDT, cUSDC, cEURT, cEURC, cGBPT, cGBPC, cAUDT, cAUDC, cJPYT, cJPYC, cCHFT, cCHFC, cCADT, cCADC, cAUSDT | ETH, WETH, cUSDT, cUSDC |
+| **2. ALL Mainnet (Alltra)** | Chain 651940 | Native, AUSDT, USDT, USDC, WETH, WALL, ACADT |
+| **3. Compliant Wrapped (cW*)** | Public chains (bridged from 138) | cWUSDT, cWUSDC, cWEURT, cWEURC, cWUSDW, … |
+| **4. D-WIN W Tokens** | Cronos (25) / 138 / 651940 | USDW, EURW, GBPW, AUDW, JPYW, CHFW, CADW |
+
+---
+
+## Gaps and alignment notes
+
+- **canonical-tokens.ts:** Defines **cEURC**, **cEURT**, **cGBPC**, **cGBPT**, **cAUDC**, **cJPYC**, **cCHFC**, **cCADC** (no **cAUDT**, **cJPYT**, **cCHFT**, **cCADT**, **cAUSDT** in the base list). Category 1 uses both T (Tether-style) and C (Coin-style): **cCADT** and **cCADC** for CAD; D-WIN is **CADW**; wrapped are **cWCADT**, **cWCADC**, **cWCADW**; Alltra is **ACADT**. **cAUSDT** is referenced in ISO4217 and tests but not in CANONICAL_TOKENS; add when Alltra/bridge compliant token is defined.
+- **FALLBACK_ADDRESSES** (canonical-tokens.ts): Only **cUSDC**, **cUSDT**, and the seven **D-WIN W** tokens (Cronos) have hardcoded addresses. All other Category 1 tokens rely on env (e.g. `cEURT_ADDRESS_138`).
+- **CHAIN138_TOKEN_ADDRESSES.md:** Lists only the five deployed tokens (WETH, WETH10, LINK, cUSDT, cUSDC). For the full Category 1 list and status, see this document.
+- **list-deployer-tokens-all-networks.sh:** Reports only tokens with known addresses (Chain 138: the five above + USDT official). When cEURT, cEURC, etc. are deployed, add their addresses to the script or source from a single config.
+
+---
+
+## References
+
+- [CHAIN138_TOKEN_ADDRESSES](CHAIN138_TOKEN_ADDRESSES.md) — Chain 138 contract addresses (deployed subset)
+- [DEPLOYED_COINS_TOKENS_AND_NETWORKS](DEPLOYED_COINS_TOKENS_AND_NETWORKS.md) — Networks and tokens by chain
+- [LIQUIDITY_POOLS_MASTER_MAP](LIQUIDITY_POOLS_MASTER_MAP.md) — cW* edge pools and stabilization
+- [canonical-tokens.ts](../../smom-dbis-138/services/token-aggregation/src/config/canonical-tokens.ts) — Token-aggregation canonical list and addresses
+- [ISO4217_COMPLIANT_TOKEN_MATRIX](../04-configuration/ISO4217_COMPLIANT_TOKEN_MATRIX.md) — Naming (c* / cW*)
+- [TOKEN_CONTRACT_DEPLOYMENTS_REMAINING](TOKEN_CONTRACT_DEPLOYMENTS_REMAINING.md) — Remaining token contract deployments by category and chain
--- a/docs/11-references/TOKEN_LIST_AUTHORING_GUIDE.md
+++ b/docs/11-references/TOKEN_LIST_AUTHORING_GUIDE.md
@@ -1,448 +0,0 @@
-# Token List Authoring Guide
-
-**Last Updated:** 2026-01-31  
-**Document Version:** 1.0  
-**Status:** Active Documentation
-
---
-
-**Based on**: [Uniswap Token Lists Specification](https://github.com/Uniswap/token-lists#authoring-token-lists)  
-**Schema**: [https://uniswap.org/tokenlist.schema.json](https://uniswap.org/tokenlist.schema.json)  
-**Network**: ChainID 138 (SMOM-DBIS-138)
-
---
-
-## 📋 Overview
-
-This guide explains how to create and maintain token lists that conform to the Uniswap Token Lists specification. Token lists are JSON files that contain metadata about ERC20 tokens for use in dApp interfaces like MetaMask, Uniswap, and other DeFi applications.
-
---
-
-## 📁 File Structure
-
-Our token list files:
-
- **`token-lists/lists/dbis-138.tokenlist.json`** - Main token list file (production)
- **`docs/METAMASK_TOKEN_LIST.json`** - Legacy location (deprecated, kept for backward compatibility)
- **`token-list.json`** - Public-facing token list (deployed version)
-
-The `.tokenlist.json` extension enables automatic JSON schema validation in editors like VSCode and IntelliJ.
-
-**Note**: The token list has been migrated to `token-lists/lists/dbis-138.tokenlist.json` for better organization and CI/CD integration.
-
---
-
-## 📝 Token List Structure
-
-### Required Fields
-
-Every token list must include:
-
-```json
-{
-  "name": "SMOM-DBIS-138 Token List",
-  "version": {
-    "major": 1,
-    "minor": 0,
-    "patch": 0
-  },
-  "timestamp": "2025-12-22T17:45:00.000Z",
-  "tokens": [
-    // Array of token objects
-  ]
-}
-```
-
-### Optional Fields
-
-Recommended fields for better compatibility:
-
- **`logoURI`** (string): Logo URL for the token list itself
- **`tags`** (object): Tag definitions for categorizing tokens
- **`tokenMap`** (object): Optional map for quick token lookups
-
-### Token Object Structure
-
-Each token in the `tokens` array must have:
-
-**Required:**
- `chainId` (number): Chain ID (138 for SMOM-DBIS-138)
- `address` (string): Ethereum address (0x-prefixed, 40 hex chars)
- `name` (string): Human-readable token name
- `symbol` (string): Token symbol (e.g., "WETH", "ETH-USD")
- `decimals` (number): Number of decimals (0-255)
-
-**Optional:**
- `logoURI` (string): URL to token logo image
- `tags` (array of strings): Array of tag identifiers
-
---
-
-## 🎨 Example Token List
-
-```json
-{
-  "name": "SMOM-DBIS-138 Token List",
-  "version": {
-    "major": 1,
-    "minor": 1,
-    "patch": 0
-  },
-  "timestamp": "2025-12-22T17:45:00.000Z",
-  "logoURI": "https://example.com/logo.png",
-  "tokens": [
-    {
-      "chainId": 138,
-      "address": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
-      "name": "Wrapped Ether",
-      "symbol": "WETH",
-      "decimals": 18,
-      "logoURI": "https://example.com/weth.png",
-      "tags": ["defi", "wrapped"]
-    }
-  ],
-  "tags": {
-    "defi": {
-      "name": "DeFi",
-      "description": "Decentralized Finance tokens"
-    },
-    "wrapped": {
-      "name": "Wrapped",
-      "description": "Wrapped tokens representing native assets"
-    }
-  }
-}
-```
-
---
-
-## ✅ Validation
-
-### Using the Validation Script
-
-We provide enhanced validation scripts in `token-lists/scripts/`:
-
-```bash
-# Validate the token list (schema, checksums, duplicates, chain ID)
-node token-lists/scripts/validate-token-list.js token-lists/lists/dbis-138.tokenlist.json
-
-# Validate address checksums
-node token-lists/scripts/checksum-addresses.js token-lists/lists/dbis-138.tokenlist.json
-
-# Fix checksummed addresses
-node token-lists/scripts/checksum-addresses.js token-lists/lists/dbis-138.tokenlist.json --fix
-
-# Validate logos
-node token-lists/scripts/validate-logos.js token-lists/lists/dbis-138.tokenlist.json
-
-# Verify on-chain contracts
-node token-lists/scripts/verify-on-chain.js token-lists/lists/dbis-138.tokenlist.json
-
-# Validate and emit SHA256 hash (Blitzkrieg hash lock; deterministic audit)
-node token-lists/scripts/validate-and-hash.js
-```
-
-The script will:
-1. Fetch the official Uniswap schema
-2. Validate the JSON structure
-3. Check all required fields
-4. Validate token addresses format
-5. Verify decimals are in valid range (0-255)
-6. Display token list information
-
-### Manual Validation
-
-For manual validation, you can:
-
-1. **Use an editor with JSON Schema support** (VSCode, IntelliJ, etc.)
-   - Files with `.tokenlist.json` extension automatically get schema validation
-   - The schema is registered in SchemaStore
-
-2. **Use online validators**:
-   - [JSON Schema Validator](https://www.jsonschemavalidator.net/)
-   - Schema URL: `https://uniswap.org/tokenlist.schema.json`
-
-3. **Use command-line tools**:
-   ```bash
-   # Basic JSON validation
-   jq empty docs/METAMASK_TOKEN_LIST.json
-
-   # Validate against schema (requires ajv-cli)
-   ajv validate -s tokenlist.schema.json -d docs/METAMASK_TOKEN_LIST.json
-   ```
-
---
-
-## 🔄 Semantic Versioning
-
-Token list versions follow [semantic versioning](https://semver.org/) rules:
-
-### Version Increment Rules
-
- **Major version** (1.0.0 → 2.0.0):
-  - When tokens are **removed** from the list
-  - When token addresses or chain IDs change (considered remove + add)
-
- **Minor version** (1.0.0 → 1.1.0):
-  - When tokens are **added** to the list
-
- **Patch version** (1.0.0 → 1.0.1):
-  - When **existing tokens** have minor details changed:
-    - Name changes
-    - Symbol changes
-    - Logo URL updates
-    - Decimals changes
-    - Tag additions/removals
-
-### Example Version Changes
-
-```json
-// Version 1.0.0 → 1.0.1 (patch)
-// Changed logo URL for WETH
-{
-  "version": { "major": 1, "minor": 0, "patch": 1 },
-  "tokens": [
-    { "symbol": "WETH", "logoURI": "https://new-logo.png" }
-  ]
-}
-
-// Version 1.0.0 → 1.1.0 (minor)
-// Added new token
-{
-  "version": { "major": 1, "minor": 1, "patch": 0 },
-  "tokens": [
-    { "symbol": "WETH", ... },
-    { "symbol": "USDC", ... }  // New token
-  ]
-}
-
-// Version 1.0.0 → 2.0.0 (major)
-// Removed token
-{
-  "version": { "major": 2, "minor": 0, "patch": 0 },
-  "tokens": [
-    { "symbol": "WETH", ... }
-    // USDC removed
-  ]
-}
-```
-
---
-
-## 🛠️ Authoring Methods
-
-### Manual Authoring
-
-**Recommended for**: Small lists, occasional updates
-
-1. **Use an editor with JSON Schema support**:
-   - VSCode (recommended)
-   - IntelliJ IDEA
-   - Other editors from [SchemaStore](https://www.schemastore.org/json/)
-
-2. **Open the `.tokenlist.json` file**:
-   ```bash
-   code docs/METAMASK_TOKEN_LIST.tokenlist.json
-   ```
-
-3. **The editor will provide**:
-   - Autocomplete for valid fields
-   - Validation errors in real-time
-   - Schema-aware formatting
-
-4. **Make your changes** and save
-
-5. **Validate before committing**:
-   ```bash
-   node token-lists/scripts/validate-token-list.js token-lists/lists/dbis-138.tokenlist.json
-   ```
-
-### Automated Authoring
-
-**Recommended for**: Large lists, frequent updates, pulling from contracts
-
-You can use the `@uniswap/token-lists` npm package (now included as a dependency):
-
-```javascript
-import { TokenList, schema } from '@uniswap/token-lists'
-import Ajv from 'ajv'
-import addFormats from 'ajv-formats'
-
-// Generate your token list
-const myList: TokenList = {
-  name: "SMOM-DBIS-138 Token List",
-  version: { major: 1, minor: 0, patch: 0 },
-  timestamp: new Date().toISOString(),
-  tokens: [
-    // Your tokens
-  ]
-}
-
-// Validate against schema
-const ajv = new Ajv({ allErrors: true, verbose: true })
-addFormats(ajv)
-const validator = ajv.compile(schema)
-const valid = validator(myList)
-
-if (!valid) {
-  console.error('Validation errors:', validator.errors)
-} else {
-  // Print JSON
-  console.log(JSON.stringify(myList, null, 2))
-}
-```
-
-**Note**: The `@uniswap/token-lists` package is now included in the project dependencies. The validation scripts automatically use the schema from this package, with fallback to URL fetch if unavailable.
-
---
-
-## 📤 Deploying Token Lists
-
-### Release Process
-
-For production releases, use the release script:
-
-```bash
-# Bump version (patch, minor, or major)
-cd token-lists
-./scripts/release.sh patch
-
-# Sign the token list
-./scripts/sign-list.sh sign
-
-# Create git tag and push (triggers GitHub Actions release workflow)
-git tag -a v1.2.0 -m "Release v1.2.0"
-git push --tags
-```
-
-The GitHub Actions release workflow will automatically:
- Validate the token list
- Verify on-chain contracts
- Generate checksums
- Sign the token list
- Create a GitHub Release
-
-For manual hosting, you can use the hosting script:
-
-```bash
-# Prepare for GitHub Pages
-./scripts/host-token-list.sh github
-
-# Prepare for IPFS
-./scripts/host-token-list.sh ipfs
-
-# Get instructions for custom hosting
-./scripts/host-token-list.sh local
-```
-
-See [MetaMask Quick Start](../01-getting-started/METAMASK_QUICK_START_GUIDE.md) and [Contract Addresses](CONTRACT_ADDRESSES_REFERENCE.md) for deployment and token list references.
-
-### Hosting Requirements
-
- **HTTPS required**: MetaMask and other dApps require HTTPS
- **CORS headers**: Must include `Access-Control-Allow-Origin: *`
- **Content-Type**: Should be `application/json`
-
---
-
-## 🔍 Current Token List Contents
-
-Our token list currently includes:
-
-1. **WETH9** (`0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2`)
-   - Wrapped Ether (18 decimals)
-   - Tags: `defi`, `wrapped`
-
-2. **WETH10** (`0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9f`)
-   - Wrapped Ether v10 (18 decimals)
-   - Tags: `defi`, `wrapped`
-
-3. **ETH/USD Price Feed** (`0x3304b747e565a97ec8ac220b0b6a1f6ffdb837e6`)
-   - Oracle price feed (8 decimals)
-   - Tags: `oracle`, `price-feed`
-
---
-
-## 📚 Best Practices
-
-1. **Always validate** before deploying
-   ```bash
-   node scripts/validate-token-list.js docs/METAMASK_TOKEN_LIST.json
-   ```
-
-2. **Update timestamp** when making changes
-   ```json
-   "timestamp": "2025-12-22T17:45:00.000Z"
-   ```
-
-3. **Use checksummed addresses** (mixed case)
-   - Use tools like [ethsum.netlify.app](https://ethsum.netlify.app/)
-   - Or use ethers.js: `ethers.getAddress(address)`
-
-4. **Provide logo URLs** for better UX
-   - Use reliable CDNs (GitHub, IPFS, etc.)
-   - Recommended format: PNG or SVG
-   - Recommended size: 256x256 or larger
-
-5. **Use tags** to categorize tokens
-   - Makes filtering easier for users
-   - Define tag descriptions in the `tags` object
-
-6. **Follow versioning rules** strictly
-   - Helps users understand what changed
-   - Prevents breaking changes
-
-7. **Test in MetaMask** after updates
-   - Add the token list URL to MetaMask
-   - Verify tokens appear correctly
-   - Check metadata (name, symbol, decimals, logo)
-
---
-
-## 🔗 Related Documentation
-
- [Token Lists README](/docs/01-getting-started/README.md) - Main token lists documentation
- [Token Lists Project](../../token-lists/README.md) - Token lists repo (policy and integration in repo)
- [Uniswap Token Lists Specification](https://github.com/Uniswap/token-lists)
- [JSON Schema](https://uniswap.org/tokenlist.schema.json)
- [MetaMask Quick Start](../01-getting-started/METAMASK_QUICK_START_GUIDE.md) - Add network and tokens
- [Contract Addresses Reference](CONTRACT_ADDRESSES_REFERENCE.md) - Token addresses
-
---
-
-## 🐛 Troubleshooting
-
-### Validation Errors
-
-**Error: "Missing or invalid address"**
- Ensure address is 0x-prefixed with 40 hex characters
- Use checksummed (mixed case) addresses
-
-**Error: "Invalid decimals"**
- Decimals must be a number between 0 and 255
-
-**Error: "Invalid chainId"**
- Chain ID must be a number
- For SMOM-DBIS-138, use 138
-
-### Schema Validation Fails
-
-If AJV validation fails but basic validation passes:
-
-1. Install dependencies:
-   ```bash
-   npm install ajv ajv-formats
-   ```
-
-2. Run validation again:
-   ```bash
-   node scripts/validate-token-list.js docs/METAMASK_TOKEN_LIST.json
-   ```
-
-3. Check specific errors in the output
-
---
-
-**Last Updated**: 2025-12-22  
-**Maintainer**: DBIS Team
-