docs(chain138): canonicalize Stack-A DODO PMM stack (live, traded)

On-chain probe (2026-04-22) confirms two parallel DODOPMM deployments on Chain 138. Stack A is the live, traded one: - DODOPMMIntegration (Stack A): 0x86ADA6Ef91A3B450F89f2b751e93B1b7A3218895 - DODOPMMProvider (Stack A): 0x3f729632E9553EBacCdE2e9b4c8F2B285b014F2e - 8 registered pools, all isKnownPool=true, with traded liquidity (cUSDT/cUSDC, cUSDT/USDT, cUSDC/USDC, cBTC/cUSDT, cBTC/cUSDC, WETH/USDC, WETH/USDT, cBTC/cXAUC). Stack B (DODOPMMIntegration=0x5BDc62f1..., DODOPMMProvider=0x5CAe6Ce1..., pools 0xff8d3b8f.../0x6fc60D.../0x9f74Be...) is a parallel deployment with seeded but un-traded pools (10M/10M flat or 0/0). Earlier docs that cited Stack B as canonical are superseded. Updates: - .cursor/rules/chain138-tokens-and-pmm.mdc: replace integration + pool addresses with Stack A; add provider, cBTC, and full live-pool table. - docs/11-references/ADDRESS_MATRIX_AND_STATUS.md: re-version to 2026-04-22; show both stacks with status flags; add 5 cBTC/WETH pools; flip EnhancedSwapRouter row from Not deployed to Pending Phase 3. - docs/11-references/PMM_DEX_ROUTING_STATUS.md: rewrite executive summary; refer to Phase 3 LAN deploy command. No code change. Companion to atomic-swap-dapp PR #4 (frontend routing-honesty) and the upcoming Phase 3 EnhancedSwapRouter deploy. Co-Authored-By: Nakamoto, S <defi@defi-oracle.io>
2026-04-29 04:19:06 +00:00
3 changed files with 52 additions and 22 deletions
--- a/.cursor/rules/chain138-tokens-and-pmm.mdc
+++ b/.cursor/rules/chain138-tokens-and-pmm.mdc
@@ -10,9 +10,23 @@ alwaysApply: true
 - **cUSDT:** `0x93E66202A11B1772E55407B32B44e5Cd8eda7f22` (6 decimals)
 - **cUSDC:** `0xf22258f57794CC8E06237084b353Ab30fFfa640b` (6 decimals)

-**DODOPMMIntegration:** `0x5BDc62f1ae7D630c37A8B363a1d49845356Ee72d` — reconciled with `docs/11-references/ADDRESS_MATRIX_AND_STATUS.md` (on-chain verification 2026-03-26); `compliantUSDT()` / `compliantUSDC()` return the canonical cUSDT/cUSDC above.
+**DODOPMMIntegration (live, traded):** `0x86ADA6Ef91A3B450F89f2b751e93B1b7A3218895` — confirmed live via on-chain probe (2026-04-22): `compliantUSDT()` / `compliantUSDC()` return the canonical cUSDT/cUSDC above; `pools[][]` mapping resolves to the live funded pool set below; `isRegisteredPool` is TRUE for all 8 pools listed under "PMM pools (live, traded)". `0x5BDc62f1ae7D630c37A8B363a1d49845356Ee72d` is a parallel deployment of the same source with different immutables and seeded but un-traded pools — do not wire dApps or routers to it.

-**PMM pools (live funded public):** cUSDT/cUSDC `0xff8d3b8fDF7B112759F076B69f4271D4209C0849` | cUSDT/USDT `0x6fc60DEDc92a2047062294488539992710b99D71` | cUSDC/USDC `0x9f74Be42725f2Aa072a9E0CdCce0E7203C510263` — see `docs/11-references/ADDRESS_MATRIX_AND_STATUS.md` / `PMM_DEX_ROUTING_STATUS.md`.
+**DODOPMMProvider (ILiquidityProvider, live):** `0x3f729632E9553EBacCdE2e9b4c8F2B285b014F2e` — `dodoIntegration() == 0x86ADA6Ef…`, `providerName() == "DODO PMM"`, `isKnownPool` TRUE for all 8 live pools. Use this address as `dodoLiquidityProvider` when deploying `EnhancedSwapRouter`; see `docs/11-references/PMM_DEX_ROUTING_STATUS.md`.
+
+**PMM pools (live, traded — 2026-04-22 on-chain probe):**
+- cUSDT/cUSDC `0x9e89bAe009adf128782E19e8341996c596ac40dC` (~983k cUSDT / ~1.016M cUSDC, asymmetric — actively traded)
+- cUSDT/USDT  `0x866Cb44b59303d8dc5f4F9E3E7A8e8b0bf238d66` (~1M / ~1M)
+- cUSDC/USDC  `0xc39B7D0F40838cbFb54649d327f49a6DAC964062` (~1M / ~1M)
+- cBTC/cUSDT  `0x67049e7333481e2cac91af61403ac7bddfab7bcd` (10k cBTC base / 9M cUSDT quote)
+- cBTC/cUSDC  `0x72f1a0794153c3b8a1e8a731f1d8e1a52cb10dc5` (10k cBTC base / 9M cUSDC quote)
+- WETH/USDC   `0xb53a0508940b1ff90f1aad4f6cb50a7012fe5593` (~10.1M USDC quote)
+- WETH/USDT   `0xe227f6c0520c0c6e8786fe56fa76c4914f861533` (~10.1M USDT quote)
+- cBTC/cXAUC  `0xf3e8a07d419b61f002114e64d79f7cf8f7989433` (10k cBTC base / 1.7k cXAUC quote)
+
+The earlier rule's pool addresses (`0xff8d3b8f…`, `0x6fc60D…`, `0x9f74Be…`) belong to the **parallel** integration `0x5BDc62f1…` (Stack B) and are seeded 10M/10M flat or 0/0 — they are not the live PMM trading set. Source-of-truth corrections to follow in `ADDRESS_MATRIX_AND_STATUS.md` and `PMM_DEX_ROUTING_STATUS.md`.
+
+**cBTC:** `0xe94260c555ac1d9d3cc9e1632883452ebdf0082e` (8 decimals) — base token of the three cBTC pools above.

 **cXAUC / cXAUT (XAU):** `0x290E52a8819A4fbD0714E517225429aA2B70EC6b`, `0x94e408E26c6FD8F4ee00b54dF19082FDA07dC96E` (6 decimals). **1 full token = 1 troy ounce Au** — not USD face value; see `EXPLORER_TOKEN_LIST_CROSSCHECK.md` section 5.1.

--- a/docs/11-references/ADDRESS_MATRIX_AND_STATUS.md
+++ b/docs/11-references/ADDRESS_MATRIX_AND_STATUS.md
@@ -1,7 +1,7 @@
 # Address Matrix and Status — Correlated Reference

-**Last Updated:** 2026-03-26  
-**Purpose:** Single correlated matrix of all existing contract, token, and pool addresses with deployment status. **On-chain verification (2026-03-26):** corrected Chain 138 PMM stack verified at `DODOPMMIntegration=0x5BDc62f1ae7D630c37A8B363a1d49845356Ee72d` and `DODOPMMProvider=0x5CAe6Ce155b7f08D3a956F5Dc82fC9945f29B381`; desired-state inventory is fully reconciled with `104` existing pools and `104` aligned routes.  
+**Last Updated:** 2026-04-22  
+**Purpose:** Single correlated matrix of all existing contract, token, and pool addresses with deployment status. **On-chain verification (2026-04-22):** the **live, traded** Chain 138 PMM stack is `DODOPMMIntegration=0x86ADA6Ef91A3B450F89f2b751e93B1b7A3218895` + `DODOPMMProvider=0x3f729632E9553EBacCdE2e9b4c8F2B285b014F2e`. A second parallel deployment (`DODOPMMIntegration=0x5BDc62f1ae7D630c37A8B363a1d49845356Ee72d` + `DODOPMMProvider=0x5CAe6Ce155b7f08D3a956F5Dc82fC9945f29B381`) exists with seeded but un-traded pools — do not wire dApps or routers to it. Earlier docs that cited the `0x5BDc62f1…` stack as canonical were superseded by this re-verification.  
 **Sources:** CONTRACT_ADDRESSES_REFERENCE, CHAIN138_TOKEN_ADDRESSES, LIQUIDITY_POOLS_MASTER_MAP, DEPLOYED_COINS_TOKENS_AND_NETWORKS, env examples, PRE_DEPLOYMENT_CHECKLIST.

 ---
@@ -108,12 +108,22 @@

 | Contract / pool | Address | Status | Notes |
 |-----------------|---------|--------|-------|
-| DODOPMMIntegration | `0x5BDc62f1ae7D630c37A8B363a1d49845356Ee72d` | ✅ | Corrected canonical integration; full JSON desired-state reconciled |
-| DODOPMMProvider | `0x5CAe6Ce155b7f08D3a956F5Dc82fC9945f29B381` | ✅ | Corrected canonical provider; 104 aligned routes |
+| DODOPMMIntegration (Stack A, live) | `0x86ADA6Ef91A3B450F89f2b751e93B1b7A3218895` | ✅ | Live, traded integration; backs all 8 active PMM pools (2026-04-22 on-chain probe) |
+| DODOPMMProvider (Stack A, live) | `0x3f729632E9553EBacCdE2e9b4c8F2B285b014F2e` | ✅ | `dodoIntegration() == 0x86ADA6Ef…`, `providerName() == "DODO PMM"`, `isKnownPool` TRUE for all 8 Stack A pools |
+| DODOPMMIntegration (Stack B, parallel) | `0x5BDc62f1ae7D630c37A8B363a1d49845356Ee72d` | ⚠ | Same source, different immutables; pools seeded but un-traded — do not wire dApps/routers to it |
+| DODOPMMProvider (Stack B, parallel) | `0x5CAe6Ce155b7f08D3a956F5Dc82fC9945f29B381` | ⚠ | Pairs with the Stack B integration; superseded by Stack A for canonical use |
 | PrivatePoolRegistry | `0xb27057B27db09e8Df353AF722c299f200519882A` | ✅ | Live private XAU pool registry |
-| Pool cUSDT/cUSDC | `0xff8d3b8fDF7B112759F076B69f4271D4209C0849` | ✅ | Funded live |
-| Pool cUSDT/USDT (official mirror) | `0x6fc60DEDc92a2047062294488539992710b99D71` | ✅ | Intended funded canonical pool; integration/provider mapping must be repointed if still on older empty pool |
-| Pool cUSDC/USDC (official mirror) | `0x9f74Be42725f2Aa072a9E0CdCce0E7203C510263` | ✅ | Canonical corrected-stack pool |
+| Pool cUSDT/cUSDC (Stack A, traded) | `0x9e89bAe009adf128782E19e8341996c596ac40dC` | ✅ | Live, asymmetric balances (≈983.9k cUSDT / ≈1.016M cUSDC) — actively traded |
+| Pool cUSDT/USDT (Stack A) | `0x866Cb44b59303d8dc5f4F9E3E7A8e8b0bf238d66` | ✅ | Live (≈1M / ≈1M) |
+| Pool cUSDC/USDC (Stack A) | `0xc39B7D0F40838cbFb54649d327f49a6DAC964062` | ✅ | Live (≈1M / ≈1M) |
+| Pool cBTC/cUSDT (Stack A) | `0x67049e7333481e2cac91af61403ac7bddfab7bcd` | ✅ | Live (10k cBTC / 9M cUSDT) |
+| Pool cBTC/cUSDC (Stack A) | `0x72f1a0794153c3b8a1e8a731f1d8e1a52cb10dc5` | ✅ | Live (10k cBTC / 9M cUSDC) |
+| Pool WETH/USDC (Stack A) | `0xb53a0508940b1ff90f1aad4f6cb50a7012fe5593` | ✅ | Live (≈10.1M USDC quote) |
+| Pool WETH/USDT (Stack A) | `0xe227f6c0520c0c6e8786fe56fa76c4914f861533` | ✅ | Live (≈10.1M USDT quote) |
+| Pool cBTC/cXAUC (Stack A) | `0xf3e8a07d419b61f002114e64d79f7cf8f7989433` | ✅ | Live (10k cBTC / 1.74k cXAUC) |
+| Pool cUSDT/cUSDC (Stack B, seeded) | `0xff8d3b8fDF7B112759F076B69f4271D4209C0849` | ⚠ | 10M / 10M flat — not traded; superseded by Stack A pool above |
+| Pool cUSDT/USDT (Stack B, seeded) | `0x6fc60DEDc92a2047062294488539992710b99D71` | ⚠ | 10M / 10M flat — not traded; superseded by Stack A pool above |
+| Pool cUSDC/USDC (Stack B, empty) | `0x9f74Be42725f2Aa072a9E0CdCce0E7203C510263` | ⚠ | 0 / 0 zero liquidity; superseded by Stack A pool above |
 | Pool cUSDT/cXAUC (public) | `0x1AA55E2001E5651349AfF5A63FD7A7Ae44f0F1b0` | ✅ | Funded live |
 | Pool cUSDC/cXAUC (public) | `0xEA9Ac6357CaCB42a83b9082B870610363B177cBa` | ✅ | Funded live |
 | Pool cEURT/cXAUC (public) | `0xbA99bc1eAAC164569d5AcA96C806934DDaF970Cf` | ✅ | Funded live |
@@ -121,7 +131,7 @@
 | Pool cUSDC/cXAUC (private) | `0x7867D58567948e5b9908F1057055Ee4440de0851` | ✅ | Funded live |
 | Pool cEURT/cXAUC (private) | `0x505403093826D494983A93b43Aa0B8601078A44e` | ✅ | Funded live |
 | LiquidityPoolETH (trustless) | — | ❌ | Placeholder 0x0 |
-| EnhancedSwapRouter | — | ❌ | Not deployed |
+| EnhancedSwapRouter | — | ⏳ | Pending Phase 3 LAN deploy; see `test-plans/phase3-enhancedswaprouter-deploy-command.md` (Stack A wiring) |

 ### 1.7 TransactionMirror / deployer

@@ -193,8 +203,8 @@ Bridges (CCIPWETH9 / CCIPWETH10) and LINK funding per runbook. Addresses in `smo

 | Env variable (Chain 138) | Canonical address |
 |--------------------------|-------------------|
-| DODO_PMM_INTEGRATION_ADDRESS | `0x5BDc62f1ae7D630c37A8B363a1d49845356Ee72d` |
-| DODO_PMM_PROVIDER_ADDRESS | `0x5CAe6Ce155b7f08D3a956F5Dc82fC9945f29B381` |
+| DODO_PMM_INTEGRATION_ADDRESS | `0x86ADA6Ef91A3B450F89f2b751e93B1b7A3218895` (Stack A, live) |
+| DODO_PMM_PROVIDER_ADDRESS | `0x3f729632E9553EBacCdE2e9b4c8F2B285b014F2e` (Stack A, live) |
 | PRIVATE_POOL_REGISTRY | `0xb27057B27db09e8Df353AF722c299f200519882A` |
 | POOL_CUSDTCUSDC | `0xff8d3b8fDF7B112759F076B69f4271D4209C0849` |
 | POOL_CUSDTUSDT | `0x6fc60DEDc92a2047062294488539992710b99D71` |
--- a/docs/11-references/PMM_DEX_ROUTING_STATUS.md
+++ b/docs/11-references/PMM_DEX_ROUTING_STATUS.md
@@ -1,16 +1,19 @@
 # PMM Liquidity Pools & DEX/DeFi Routing — Full System Status

-**Last Updated:** 2026-03-26  
+**Last Updated:** 2026-04-22  
 **Purpose:** Single reference for DEX/DeFi and PMM liquidity pool routing — what is designed, deployed, and in use.

 ---

-## Executive summary (updated 2026-03-26)
+## Executive summary (updated 2026-04-22)

- **DODOPMMIntegration** is **deployed** on Chain 138 at `0x5BDc62f1ae7D630c37A8B363a1d49845356Ee72d`. The corrected canonical stack now has **104 desired-state pools aligned**.
- **DODOPMMProvider** is **deployed** at `0x5CAe6Ce155b7f08D3a956F5Dc82fC9945f29B381` with **104/104 provider routes aligned** to the integration.
- **Live funded public pools** are: cUSDT/cUSDC (`0xff8d3b8fDF7B112759F076B69f4271D4209C0849`), cUSDT/USDT (`0x6fc60DEDc92a2047062294488539992710b99D71`), cUSDC/USDC (`0x9f74Be42725f2Aa072a9E0CdCce0E7203C510263`), cUSDT/cXAUC (`0x94316511621430423a2cff0C036902BAB4aA70c2`), cUSDC/cXAUC (`0x7867D58567948e5b9908F1057055Ee4440de0851`), cEURT/cXAUC (`0x505403093826D494983A93b43Aa0B8601078A44e`).
- **EnhancedSwapRouter** is **not deployed**; multi-provider DEX routing (Uniswap/Balancer/Curve/1inch) is not live.
+- **Two parallel DODOPMM deployments exist on Chain 138.** On-chain probe (2026-04-22) shows the **live, traded** stack is **Stack A**:
+  - **DODOPMMIntegration (Stack A)** `0x86ADA6Ef91A3B450F89f2b751e93B1b7A3218895` — 8 registered, actively-traded pools.
+  - **DODOPMMProvider (Stack A)** `0x3f729632E9553EBacCdE2e9b4c8F2B285b014F2e` — wired to Stack A integration; `isKnownPool` TRUE for all 8 Stack A pools.
+  - The **Stack B** stack (`DODOPMMIntegration=0x5BDc62f1…` / `DODOPMMProvider=0x5CAe6Ce1…`) is a parallel deployment with seeded but un-traded pools (10M/10M flat, cUSDC/USDC at 0/0). Do **not** wire dApps or routers to Stack B. Earlier docs that cited Stack B as canonical were superseded by this re-verification.
+- **Live funded, traded Stack-A pools (2026-04-22 probe):** cUSDT/cUSDC `0x9e89bAe0…`, cUSDT/USDT `0x866Cb44b…`, cUSDC/USDC `0xc39B7D0F…`, cBTC/cUSDT `0x67049e73…`, cBTC/cUSDC `0x72f1a079…`, WETH/USDC `0xb53a0508…`, WETH/USDT `0xe227f6c0…`, cBTC/cXAUC `0xf3e8a07d…`. The funded XAU pools `0x9431…`/`0x7867…`/`0x5054…` remain live but on the legacy XAU registry, not the Stack A integration.
+- **EnhancedSwapRouter** is **not yet deployed**; the Phase 3 LAN deploy command (Stack-A wiring) is staged in `test-plans/phase3-enhancedswaprouter-deploy-command.md` with `DODO_PMM_PROVIDER_ADDRESS=0x3f729632…` + `UNISWAP_V3_ROUTER=0xde9cd8ee…` + `BALANCER_VAULT=0x96423d7c…`. Multi-provider DEX routing (Uniswap V3 + Balancer + DODO via Stack A) goes live with this deploy.
+- **Phase 1 / 2 dApp work (2026-04-22):** the atomic-swap dApp at `https://atomic-swap.defi-oracle.io/` was failing because its quote handler ignored 4 of 6 protocols. PR #2 (mobile bridge + max-approve) and PR #4 (routing-honesty + protocol/executor mismatch chip) addressed the UI side; this stack-A canonicalization addresses the on-chain side.
 - **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.
@@ -45,10 +48,13 @@

 | Component | Status | Address / Notes |
 |-----------|--------|------------------|
-| **DODOPMMIntegration** | Deployed | `0x5BDc62f1ae7D630c37A8B363a1d49845356Ee72d` — corrected canonical integration. |
-| **PMM pools (desired-state)** | **104 aligned** | Full desired-state JSON reconciled; live funded public pools are listed in [LIQUIDITY_POOLS_MASTER_MAP](LIQUIDITY_POOLS_MASTER_MAP.md). |
-| **DODOPMMProvider** | **Deployed** | `0x5CAe6Ce155b7f08D3a956F5Dc82fC9945f29B381`; 104/104 routes aligned to the corrected integration. |
-| **EnhancedSwapRouter** | Not deployed | Deploy when Uniswap/Balancer pools exist on 138; configure quoter and Balancer poolId. |
+| **DODOPMMIntegration (Stack A, live)** | Deployed | `0x86ADA6Ef91A3B450F89f2b751e93B1b7A3218895` — canonical, actively traded; backs all 8 Stack-A pools. |
+| **DODOPMMProvider (Stack A, live)** | Deployed | `0x3f729632E9553EBacCdE2e9b4c8F2B285b014F2e`; `isKnownPool` TRUE for all 8 Stack-A pools; use as `dodoLiquidityProvider` for `EnhancedSwapRouter`. |
+| **DODOPMMIntegration (Stack B, parallel)** | Deployed | `0x5BDc62f1ae7D630c37A8B363a1d49845356Ee72d` — same source, different immutables; pools seeded but un-traded; do not wire to it. |
+| **DODOPMMProvider (Stack B, parallel)** | Deployed | `0x5CAe6Ce155b7f08D3a956F5Dc82fC9945f29B381` — pairs with Stack B integration; superseded by Stack A. |
+| **PMM pools (Stack A, traded)** | Live | 8 pools registered + traded. See [ADDRESS_MATRIX_AND_STATUS](ADDRESS_MATRIX_AND_STATUS.md) §1.6. |
+| **PMM pools (Stack B, seeded)** | Live but un-traded | 3 pools at flat 10M/10M (or 0/0). Superseded by Stack A. |
+| **EnhancedSwapRouter** | Pending deploy | Phase 3 LAN deploy command staged (`test-plans/phase3-enhancedswaprouter-deploy-command.md`). Deploys with UniV3 + Balancer + DODO Stack A wired; Curve/1inch slots inert. |
 | **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.