# 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 (<$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** | 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 |