proxmox/docs/11-references/PMM_DEX_ROUTING_STATUS.md

# PMM Liquidity Pools & DEX/DeFi Routing — Full System Status

**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-04-22)

- **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 **deployed** at `0xE6Cc7643ae2A4C720A28D8263BC4972905d7DE0f` on Chain 138 (Phase 3, 2026-04-22, EVM version Paris per `[profile.chain138]` in `smom-dbis-138/foundry.toml`). Wired immutables: UniV3 `0xde9cD8ee…`, Dodoex `0x86ADA6Ef…` (Stack A), Balancer `0x96423d7C…`, 1inch `0x500B84b1…`, Curve disabled. `dodoLiquidityProvider = 0x3f729632…`. **11 DODO pools registered** in `dodoPoolAddresses[tokenA][tokenB]` bidirectionally (8 at deploy + 3 cBTC pools added Phase 3j 2026-04-22). Curve and 1inch slots remain inert; Balancer wiring is configured but functional pool ids must be set per-pair via `setBalancerPoolId(...)` before Balancer routing engages.
- **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.

---

## 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)** | Desired-state full mesh with live funded public stable/XAU pools | 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 (<$10k) → Uniswap V3 / Dodoex; Medium ($10k–$100k) → Dodoex → Balancer → Uniswap V3; Large (>$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 (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** | Deployed | `0xE6Cc7643ae2A4C720A28D8263BC4972905d7DE0f` on Chain 138 (Phase 3, 2026-04-22, EVM Paris). UniV3 + Balancer + DODO Stack A wired; Curve/1inch slots inert; 11 DODO pools registered (8 at deploy + 3 cBTC pools Phase 3j). Balancer pool ids still pending per-pair `setBalancerPoolId(...)`. |
| **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 | EnhancedSwapRouter is now deployed; backend can resolve DODO-registered pairs through `swapTokenToToken(...)`. Multi-provider routing (UniV3 / Balancer / 1inch) needs per-pair pool/quoter config before it engages. |

### 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) | Partial — router deployed, only DODO Stack-A active | EnhancedSwapRouter `0xE6Cc7643…` exposes `swapTokenToToken(tokenIn,tokenOut,amountIn,minOut)`; routes for the 11 registered DODO pairs work today. UniV3 / Balancer / 1inch slots wired but not yet driving liquidity (no pools / no pool ids). |
| 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** | Corrected canonical stack deployed; 104 desired-state pools aligned; live funded public stable/XAU pools available. |
| **DEX routing (EnhancedSwapRouter)** | Partial | Contract deployed at `0xE6Cc7643…`; DODO Stack-A path live for 11 pairs; UniV3/Balancer/1inch slots wired but inactive (no native pools / no pool ids 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)** | Partial | Router deployed; decision logic can drive DODO Stack-A leg today. UniV3 / Balancer / 1inch arms inactive until pools/quoter/poolId are configured. |
| **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:** Configure Balancer pool ids per pair (`setBalancerPoolId(...)`) and add UniV3/1inch-routable native pools on Chain 138 to activate the non-DODO arms of the router.
- **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 |