chore: update submodule references and documentation

- Marked submodules ai-mcp-pmm-controller, explorer-monorepo, and smom-dbis-138 as dirty to reflect recent changes. - Updated documentation to clarify operator script usage, including dotenv loading and task execution instructions. - Enhanced the README and various index files to provide clearer navigation and task completion guidance. Made-with: Cursor
2026-03-04 02:03:08 -08:00
parent 70eadb7bf0
commit e4c9dda0fd
246 changed files with 17774 additions and 93 deletions
--- a/docs/03-deployment/ADD_LIQUIDITY_PMM_CHAIN138_RUNBOOK.md
+++ b/docs/03-deployment/ADD_LIQUIDITY_PMM_CHAIN138_RUNBOOK.md
@@ -66,6 +66,7 @@ Ensure the deployer has approved (or the script will approve) base/quote tokens

 ## 3. References

+- [PMM_POOLS_FUNDING_PLAN.md](PMM_POOLS_FUNDING_PLAN.md) — Full funding plan (three pools, amounts, cast commands, checklist)
 - [DODO_PMM_INTEGRATION.md](../../smom-dbis-138/docs/integration/DODO_PMM_INTEGRATION.md) — `addLiquidity(pool, baseAmount, quoteAmount)`
 - [PRE_DEPLOYMENT_CHECKLIST](PRE_DEPLOYMENT_CHECKLIST.md) § Step 3
 - [DEPLOYMENT_ORDER_OF_OPERATIONS](DEPLOYMENT_ORDER_OF_OPERATIONS.md) § Phase 3.1
--- a/docs/03-deployment/CONTRACT_DEPLOYMENT_RUNBOOK.md
+++ b/docs/03-deployment/CONTRACT_DEPLOYMENT_RUNBOOK.md
@@ -9,6 +9,7 @@
 ## Chain 138 deployment requirements (learned 2026-02-12)

 - **Gas price:** Chain 138 enforces a minimum gas price. Always use **`--with-gas-price 1000000000`** (1 gwei) for `forge script` and `forge create` when deploying to Chain 138; otherwise transactions fail with "Gas price below configured minimum gas price".
+- **Gas 32xxx when deploying:** If you see gas-related RPC errors (e.g. -32000, execution reverted, or out of gas), add **`--gas-estimate-multiplier 150`** (or 200) to `forge script ... --broadcast` so the broadcast uses a higher gas limit. See [RPC_ERRORS_32001_32602.md](../09-troubleshooting/RPC_ERRORS_32001_32602.md).
 - **On-chain check:** After deployments, run `./scripts/verify/check-contracts-on-chain-138.sh` (uses `RPC_URL_138`; optional URL arg). Address list comes from `config/smart-contracts-master.json` when available. See [CONTRACT_ADDRESSES_REFERENCE](../11-references/CONTRACT_ADDRESSES_REFERENCE.md), [ADDRESS_MATRIX_AND_STATUS](../11-references/ADDRESS_MATRIX_AND_STATUS.md).
 - **TransactionMirror:** The deploy script can hit a Forge broadcast constructor-args decode error. If so, deploy manually: `forge create contracts/mirror/TransactionMirror.sol:TransactionMirror --constructor-args <ADMIN_ADDRESS> --rpc-url $RPC_URL_138 --private-key $PRIVATE_KEY --gas-price 1000000000`.

@@ -291,6 +292,7 @@ BLOCKSCOUT_URL=http://192.168.11.140:4000 node forge-verification-proxy/server.j
 | `No route to host` | Dev machine cannot reach RPC (RPC_URL_138, e.g. 192.168.11.211:8545) | Run from machine on LAN or VPN; or set RPC_URL_138=https://rpc-core.d-bis.org |
 | `PRIVATE_KEY not set` | Missing in .env | Add deployer key to smom-dbis-138/.env |
 | `Gas price below configured minimum gas price` | Chain 138 minimum gas not met | Use `--with-gas-price 1000000000` for all `forge script` / `forge create` on Chain 138 |
+| RPC -32xxx / out of gas when deploying | Gas estimate too low or estimation failed | Use `--gas-estimate-multiplier 150` (or 200) with `forge script ... --broadcast`; ensure deployer has enough ETH. See [RPC_ERRORS_32001_32602.md](../09-troubleshooting/RPC_ERRORS_32001_32602.md). |
 | `Failed to decode constructor arguments` (TransactionMirror) | Forge broadcast decode bug | Deploy via `forge create ... --constructor-args <ADMIN> --gas-price 1000000000` |
 | `pam_chauthtok failed` (Blockscout) | Container PAM restriction | Use Proxmox Web UI: Container 5000 → Options → Password |
 | `pvesm not found` (verify-storage) | Script must run ON Proxmox host | `ssh root@r630-01` then run script |
--- a/docs/03-deployment/DEFI_AGGREGATOR_DEX_ROUTING_FLOWS_DIAGRAM.md
+++ b/docs/03-deployment/DEFI_AGGREGATOR_DEX_ROUTING_FLOWS_DIAGRAM.md
@@ -0,0 +1,170 @@
+# DeFi Aggregator and DEX Routing Flows — Visual Reference
+
+**Purpose:** Single diagram of all DeFi aggregator and DEX routing flows for swaps (Chain 138, public chains, bridge, MCP/AI, and bots).
+
+---
+
+## Full flow diagram (Mermaid)
+
+```mermaid
+flowchart TB
+  subgraph Users["Entry points"]
+    U1["User / Frontend / dApp"]
+    U2["Swap–bridge–swap orchestrator"]
+    U3["MCP / AI (pool management)"]
+    U4["Deviation bot (cW* peg)"]
+  end
+
+  subgraph Aggregators["Aggregator & quote layer"]
+    direction TB
+    TA["Token-aggregation API<br/>GET /quote, /tokens, /tokens/:addr/pools<br/>Single-hop quote; indexes DODO + Uniswap"]
+    BQ["Bridge quote API<br/>POST /api/bridge/quote<br/>sourceSwapQuote + bridge + destinationSwapQuote"]
+    EXT["External aggregators<br/>1inch, 0x, ParaSwap<br/>(Chain 138 not supported until they add it)"]
+    BA["Bridge aggregator (explorer backend)<br/>Li.Fi, Socket, Squid, Symbiosis, Relay, Stargate<br/>Bridge routes only"]
+  end
+
+  subgraph Chain138["Chain 138 (SMOM-DBIS-138)"]
+    direction TB
+    INT["DODOPMMIntegration<br/>createPool, addLiquidity, swapExactIn<br/>swapCUSDTForUSDC, swapCUSDTForUSDT, ..."]
+    PROV["DODOPMMProvider<br/>getQuote, executeSwap<br/>registerPool; routes to integration"]
+    MESH["Full mesh: 66 c* vs c* pools<br/>+ c* vs official USDT/USDC<br/>All routable via swapExactIn"]
+    POOLS138["Pools: cUSDT/cUSDC, cUSDT/USDT, cUSDC/USDC<br/>+ full mesh when create-pmm-full-mesh-chain138.sh run"]
+    INT --> POOLS138
+    PROV --> INT
+    MESH --> INT
+  end
+
+  subgraph PublicChains["Public chains (1, 56, 137, 10, 100, 25, 42161, 8453, 43114, 42220, 1111)"]
+    direction TB
+    CW["cW* / HUB single-sided pools<br/>cWUSDT/USDC, cWUSDC/USDC, ...<br/>Per pool-matrix.json"]
+    DEX["Native DEXs<br/>Uniswap V2/V3, DODO (if official)<br/>Used for destination swap & aggregator routing"]
+    CW --> DEX
+  end
+
+  subgraph Bridge["Bridge layer"]
+    direction LR
+    CCIP["CCIP (WETH9/WETH10)"]
+    LIFI["Li.Fi / Socket / Squid<br/>Symbiosis / Relay / Stargate"]
+    CCIP --> LIFI
+  end
+
+  subgraph Optional["Optional (when deployed)"]
+    ESR["EnhancedSwapRouter<br/>Size/slippage-based: Dodoex, Uniswap, Balancer, Curve<br/>Multi-provider for Chain 138"]
+    COORD["SwapBridgeSwapCoordinator<br/>Swap source → bridge → swap dest"]
+    ESR --> INT
+  end
+
+  subgraph MCP_AI["MCP & AI (pool management)"]
+    direction TB
+    ALLOW["Allowlist (per chain)<br/>pool_address, base_token, quote_token, profile"]
+    TOOLS["MCP tools: get_pool_state, identify_pool_interface<br/>quote_add_liquidity, add_liquidity, remove_liquidity"]
+    ALLOW --> TOOLS
+    TOOLS --> INT
+    TOOLS --> CW
+    TOOLS --> DEX
+  end
+
+  subgraph Bot["Bot (cross-chain-pmm-lps)"]
+    direction TB
+    WATCH["Deviation watcher<br/>IDLE / ABOVE_BAND / BELOW_BAND"]
+    ACT["Actions: buy/sell T, inventory adjust<br/>Cooldown, circuit break"]
+    WATCH --> ACT
+    ACT --> CW
+  end
+
+  %% User flows
+  U1 --> TA
+  U1 --> BQ
+  U1 --> EXT
+  U1 --> BA
+  TA --> PROV
+  TA --> POOLS138
+  BQ --> INT
+  BQ --> Bridge
+  BQ --> DEX
+  U2 --> BQ
+  Bridge --> PublicChains
+  U3 --> ALLOW
+  U4 --> WATCH
+  U4 --> TA
+```
+
+---
+
+## Swap routing paths (sequence view)
+
+```mermaid
+sequenceDiagram
+  participant U as User / dApp
+  participant API as Token-aggregation API
+  participant Prov as DODOPMMProvider
+  participant Int as DODOPMMIntegration
+  participant Pool as PMM Pool (138)
+  participant Br as Bridge / Quote API
+  participant Dest as Destination DEX / cW* pool
+
+  Note over U,Dest: Flow A: Same-chain swap (Chain 138)
+  U->>API: GET /quote?chainId=138&tokenIn&tokenOut&amountIn
+  API->>Prov: (indexed pool)
+  API-->>U: amountOut, poolAddress
+  U->>Int: approve(tokenIn); swapExactIn(pool, tokenIn, amountIn, minOut)
+  Int->>Pool: sellBase or sellQuote
+  Pool-->>Int: amountOut
+  Int-->>U: transfer tokenOut
+
+  Note over U,Dest: Flow B: Swap–bridge–swap
+  U->>Br: POST /api/bridge/quote (source=138, dest, token, amount)
+  Br->>API: source quote (138)
+  Br->>Dest: destination quote (public chain)
+  Br-->>U: sourceSwapQuote, bridgeRoute, destinationSwapQuote
+  U->>Int: swap on 138 (optional)
+  U->>Br: bridge tx (CCIP / Li.Fi / …)
+  U->>Dest: swap on destination (optional)
+
+  Note over U,Dest: Flow C: MCP / AI pool management
+  participant MCP as MCP (allowlist)
+  U->>MCP: get_pool_state(pool_address)
+  MCP->>Int: RPC getPoolConfig, getPoolReserves, getMidPrice
+  Int-->>MCP: config, reserves, price
+  MCP-->>U: state (for rebalance / add liquidity decision)
+```
+
+---
+
+## Flow descriptions (key paths)
+
+| Flow | Path | Notes |
+|------|------|--------|
+| **Same-chain swap (138)** | User → Token-aggregation API (GET /quote) → DODOPMMProvider.getQuote / executeSwap → DODOPMMIntegration (swapExactIn or legacy swap) → Pool | Single-hop; full mesh supported via swapExactIn. |
+| **Same-chain swap (public)** | User → External aggregator (1inch, 0x, ParaSwap) or token-aggregation (if chain indexed) → Native DEX (Uniswap/DODO) or cW* / HUB pool | cW* pools used when deployed and indexed. |
+| **Swap–bridge–swap** | User → POST /api/bridge/quote → sourceSwapQuote (138: DODOPMMIntegration) → Bridge (CCIP / Li.Fi / …) → destinationSwapQuote (public DEX or cW* pool) | Optional SwapBridgeSwapCoordinator for one-tx. |
+| **Bridge only** | User → GET /api/v1/bridge/routes, token-mapping → Bridge (CCIP, etc.) | No DEX swap on 138 or destination. |
+| **MCP reads pool state** | AI/MCP → Allowlist → get_pool_state (RPC) → DODOPMMIntegration (138) or cW* pool or Uniswap (public) | One MCP per chain or multi-chain allowlist. |
+| **MCP / AI maintenance** | AI → MCP quote_add_liquidity / add_liquidity / remove_liquidity → DODOPMMIntegration or public DEX | Dedicated MCP/AI for Dodoex + Uniswap pool management. |
+| **Bot peg maintenance** | Bot → Deviation watcher (pool vs oracle) → buy/sell cW* or inventory adjust → cW* / HUB pools on public chain | State machine: IDLE, ABOVE_BAND, BELOW_BAND, COOLDOWN, CIRCUIT_BREAK. |
+| **Multi-provider (future)** | User / Contract → EnhancedSwapRouter → DODOPMMProvider + Uniswap + Balancer + Curve (by size/slippage) → Pools on 138 | When EnhancedSwapRouter deployed and pools exist. |
+
+---
+
+## Component summary
+
+| Component | Role in routing |
+|-----------|------------------|
+| **Token-aggregation API** | Single-hop quote aggregator over indexed DODO (and Uniswap) on 138 and configured public chains. |
+| **DODOPMMIntegration** | Creates pools, adds liquidity, executes swaps (legacy pairs + swapExactIn for full mesh). |
+| **DODOPMMProvider** | Routing front: getQuote, executeSwap; registers pools; uses integration for execution. |
+| **Bridge quote API** | Orchestrates source swap + bridge + destination swap; uses token-aggregation or destination DEX for quotes. |
+| **External aggregators** | 1inch, 0x, ParaSwap: multi-DEX routing on supported chains; 138 not supported until they add it. |
+| **Bridge aggregator** | Explorer backend: Li.Fi, Socket, etc., for bridge routes only. |
+| **MCP** | Read (and optionally execute) pool state and liquidity ops; allowlist per chain or multi-chain. |
+| **Bot** | Maintains cW* peg on public chains via single-sided cW* / HUB pools; deviation and inventory. |
+| **EnhancedSwapRouter** | (Optional) Multi-provider router on 138 when Uniswap/Balancer/Curve pools exist. |
+
+---
+
+## References
+
+- [DEX_AND_AGGREGATORS_CHAIN138_EXPLAINER.md](../04-configuration/DEX_AND_AGGREGATORS_CHAIN138_EXPLAINER.md)
+- [PMM_DEX_ROUTING_STATUS.md](../11-references/PMM_DEX_ROUTING_STATUS.md)
+- [PMM_FULL_MESH_AND_PUBLIC_SINGLE_SIDED_PLAN.md](PMM_FULL_MESH_AND_PUBLIC_SINGLE_SIDED_PLAN.md)
+- [MCP_AI_POOL_MANAGEMENT_PLAN_UPGRADES.md](MCP_AI_POOL_MANAGEMENT_PLAN_UPGRADES.md)
--- a/docs/03-deployment/EXPLORER_FRONTEND_404_FIX_RUNBOOK.md
+++ b/docs/03-deployment/EXPLORER_FRONTEND_404_FIX_RUNBOOK.md
@@ -0,0 +1,144 @@
+# Explorer frontend 404 fix — runbook
+
+**Date:** 2026-03-02  
+**Issue:** Root path (`/`) at https://explorer.d-bis.org returns 404 "Page not found".  
+**Cause:** Nginx proxies `/` to Blockscout :4000; Blockscout is API-only and has no route for GET `/`.
+
+**Status:** ✅ **FIXED** (2026-03-02). Nginx now serves the custom frontend from `/var/www/html` for `/` and SPA paths; `/api/v1/` and `/api/config/*` preserved. All endpoints verified 200.
+
+---
+
+## 1. How the UI is supposed to be served
+
+This deployment uses a **custom frontend** (SolaceScanScout), not the built-in Blockscout web UI:
+
+- **Static frontend:** Built files under `/var/www/html/` on VMID 5000:
+  - `index.html` (main SPA shell, contains "SolaceScanScout")
+  - `explorer-spa.js`, `favicon.ico`, `apple-touch-icon.png`, `/snap/`, etc.
+- **Blockscout (port 4000):** API only. The Phoenix router has no route for `GET /`; it serves `/api/*` and returns 404 for `/`.
+- **Nginx:** Should serve the static frontend for `/` and SPA paths, and proxy only `/api/`, `/api/v1/`, `/api/config/*`, `/health` to the appropriate backends (Blockscout :4000, token-aggregation :3001, or static config files).
+
+**Relevant docs/config:**
+
+- `explorer-monorepo/scripts/fix-nginx-serve-custom-frontend.sh` — nginx config that serves `/var/www/html` for `/` and SPA paths.
+- `explorer-monorepo/scripts/fix-nginx-conflicts-vmid5000.sh` — current “conflicts” config: proxies `location /` to :4000 (no static root).
+- `explorer-monorepo/scripts/deploy-frontend-to-vmid5000.sh` — deploys frontend files and can apply the custom-frontend nginx config.
+- `docs/archive/fixes/BLOCKSCOUT_WEB_INTERFACE_404_FIX.md` — historical 404 investigation.
+- `explorer-monorepo/docs/BLOCKSCOUT_START_AND_BUILD.md` — Blockscout container/assets; UI in this setup is the custom frontend, not Blockscout’s own UI.
+
+---
+
+## 2. What we confirmed on VMID 5000
+
+- **Custom frontend present:** `/var/www/html/index.html` exists (~60KB), contains "SolaceScanScout"; `explorer-spa.js`, favicon, `/snap/`, etc. are present.
+- **Blockscout logs:** For `GET /` to :4000, Blockscout logs:  
+  `Phoenix.Router.NoRouteError`, "no route found for GET / (BlockScoutWeb.Router)". So 404 for `/` is expected when nginx sends `/` to Blockscout.
+- **Live nginx:** HTTPS server block has `location / { proxy_pass http://127.0.0.1:4000; }` with **no** `root` / `try_files` for the frontend. So every request to `/` is proxied to Blockscout and returns 404.
+
+Conclusion: the frontend files are in place; the **nginx config** is wrong (proxy-only for `/` instead of serving static files).
+
+---
+
+## 3. Fix: make nginx serve the custom frontend for `/`
+
+Apply a config that, for the HTTPS (and optionally HTTP) server block:
+
+1. Serves **`/`** from `/var/www/html` (e.g. `location = /` with `root /var/www/html` and `try_files /index.html =404`).
+2. Serves **SPA paths** (e.g. `/address`, `/tx`, `/blocks`, …) from the same root with `try_files $uri $uri/ /index.html`.
+3. Keeps **`/api/`**, **`/api/v1/`**, **`/api/config/*`**, **`/snap/`**, **`/health`** as they are (proxy or alias).
+
+**Option A — Apply the full custom-frontend script (recommended)**
+
+From the repo root, from a host that can SSH to the Proxmox node for VMID 5000 (e.g. r630-02):
+
+```bash
+# Set Proxmox host (r630-02)
+export PROXMOX_R630_02=192.168.11.12   # or PROXMOX_HOST_R630_02
+
+# Apply nginx config that serves / and SPA from /var/www/html
+cd /home/intlc/projects/proxmox/explorer-monorepo
+# Copy script into VM and run (requires pct exec)
+EXPLORER_VM_HOST=root@192.168.11.12 bash scripts/apply-nginx-explorer-fix.sh
+```
+
+Or run the fix script **inside** VMID 5000 (e.g. after copying it in):
+
+```bash
+# From Proxmox host
+pct exec 5000 -- bash /path/to/fix-nginx-serve-custom-frontend.sh
+```
+
+**Option B — Manual nginx change (HTTPS server block only)**
+
+On VMID 5000, edit `/etc/nginx/sites-enabled/blockscout`. In the `server { listen 443 ... }` block, **replace** the single:
+
+```nginx
+location / {
+    proxy_pass http://127.0.0.1:4000;
+    ...
+}
+```
+
+with something equivalent to:
+
+```nginx
+# Serve custom frontend for root
+location = / {
+    root /var/www/html;
+    add_header Cache-Control "no-store, no-cache, must-revalidate";
+    try_files /index.html =404;
+}
+
+# SPA paths — serve index.html for client-side routing
+location ~ ^/(address|tx|block|token|tokens|blocks|transactions|bridge|weth|watchlist|nft|home|analytics|operator)(/|$) {
+    root /var/www/html;
+    try_files /index.html =404;
+    add_header Cache-Control "no-store, no-cache, must-revalidate";
+}
+
+# All other non-API paths — static files and SPA fallback
+location / {
+    root /var/www/html;
+    try_files $uri $uri/ /index.html;
+}
+```
+
+Keep all existing `location /api/`, `location /api/v1/`, `location /api/config/`, `location /snap/`, `location /health` blocks unchanged and **before** the catch-all `location /` (so API and config still proxy correctly).
+
+Then:
+
+```bash
+nginx -t && systemctl reload nginx
+```
+
+---
+
+## 4. Verify
+
+- From LAN:  
+  `curl -sk -H "Host: explorer.d-bis.org" https://192.168.11.140:443/`  
+  should return **200** with HTML containing "SolaceScanScout" (or similar), not "Page not found".
+- Public:  
+  `https://explorer.d-bis.org/` should show the explorer UI.
+- API unchanged:  
+  `curl -s http://192.168.11.140:4000/api/v2/stats` and `https://explorer.d-bis.org/api/v2/stats` should still return JSON.
+
+---
+
+## 5. Summary
+
+| Item | Status |
+|------|--------|
+| How UI is served | Custom static frontend in `/var/www/html/` (index.html + SPA); Blockscout :4000 is API-only. |
+| Frontend files on VMID 5000 | Present; `index.html` contains SolaceScanScout. |
+| Blockscout logs for GET `/` | NoRouteError for GET `/` — expected when nginx proxies `/` to :4000. |
+| Nginx fix | Serve `/` and SPA paths from `root /var/www/html` and `try_files`; proxy only `/api/` (and specific locations) to :4000. |
+| Script to apply | `fix-nginx-serve-custom-frontend.sh` or `apply-nginx-explorer-fix.sh`; or apply the manual snippet above. |
+
+---
+
+## 6. Completion (2026-03-02)
+
+- **Applied:** `apply-nginx-explorer-fix.sh` (via `EXPLORER_VM_HOST=root@192.168.11.12`).  
+- **Script updated:** `fix-nginx-serve-custom-frontend.sh` now includes `location /api/v1/` (token-aggregation :3001) and `location = /api/config/token-list` / `location = /api/config/networks` (static JSON) so config and token-aggregation are not lost on re-apply.  
+- **Verification:** From LAN, all return 200: `/` (frontend HTML), `/api/config/token-list`, `/api/config/networks`, `/api/v2/stats`, `/api/v1/chains`.
--- a/docs/03-deployment/MCP_AI_POOL_MANAGEMENT_PLAN_UPGRADES.md
+++ b/docs/03-deployment/MCP_AI_POOL_MANAGEMENT_PLAN_UPGRADES.md
@@ -0,0 +1,126 @@
+# MCP and AI Plan Upgrades — Dodoex and Uniswap Liquidity Pool Management
+
+**Purpose:** Upgrades to the PMM full-mesh and single-sided LP plans so that **MCPs and AIs dedicated to managing and maintaining** all Dodoex (DODO PMM) and Uniswap liquidity pools are explicitly covered and operational.
+
+**Status:** All planned upgrades (§2) and all additional recommendations (§5) are **implemented**. See §4 and §5.1 for implementation details. Optional tasks index: [OPTIONAL_TASKS_CHECKLIST.md](../00-meta/OPTIONAL_TASKS_CHECKLIST.md).
+
+**Related:** [PMM_FULL_MESH_AND_PUBLIC_SINGLE_SIDED_PLAN.md](PMM_FULL_MESH_AND_PUBLIC_SINGLE_SIDED_PLAN.md), [AI_AGENTS_57XX_MCP_CONTRACTS_AND_CHAINS.md](../02-architecture/AI_AGENTS_57XX_MCP_CONTRACTS_AND_CHAINS.md), [POOL_ACCESS_DASHBOARD_API_MCP.md](../11-references/POOL_ACCESS_DASHBOARD_API_MCP.md).
+
+---
+
+## 1. Current state (what plans already assume)
+
+| Component | Role | Plan coverage today |
+|-----------|------|----------------------|
+| **ai-mcp-pmm-controller** | Read pool state (getMidPrice, reserves, k, fee); optional quote/add/remove liquidity | Allowlist per chain; one chain per MCP instance; profile `dodo_pmm_v2_like` for Chain 138 Mock DVM |
+| **Token-aggregation API** | Index DODO (and Uniswap when env set); single-hop quote; tokens/pools discovery | Chain 138 + optional public chains via `CHAIN_*_DODO_PMM_INTEGRATION`, `CHAIN_*_RPC_URL` |
+| **cross-chain-pmm-lps bot** | Deviation watcher; buy/sell to compress δ; inventory adjust; circuit break | Design only; not wired to MCP or API for automation |
+| **EnhancedSwapRouter** | Multi-provider routing (Dodoex, Uniswap, Balancer, Curve) | Not deployed; no MCP/API integration specified |
+
+---
+
+## 2. Upgrades to the plans
+
+### 2.1 Full-mesh and single-sided plans (PMM_FULL_MESH_AND_PUBLIC_SINGLE_SIDED_PLAN)
+
+| Upgrade | Description |
+|---------|-------------|
+| **Allowlist sync with mesh** | After running `create-pmm-full-mesh-chain138.sh`, **automatically or semi-automatically** update the MCP allowlist (e.g. `ai-mcp-pmm-controller/config/allowlist-138.json`) with every new pool (pool_address, base_token, quote_token, profile). Document a script or MCP tool that: (1) reads `DODOPMMIntegration.getAllPools()` and `getPoolConfig(pool)` on Chain 138, (2) writes the allowlist so the MCP can read state for all mesh pools without manual entry. |
+| **Per-chain allowlist for public cW* pools** | When single-sided cW* / HUB pools are deployed on a public chain, extend the plan to: (1) add a **per-chain MCP allowlist** (or multi-chain allowlist) so the dedicated MCP/AI can read pool state on that chain; (2) document the mapping from `cross-chain-pmm-lps/config/deployment-status.json` (and pool-matrix) to the MCP config so one source of truth drives both deployment and MCP visibility. |
+| **Uniswap pool indexing and maintenance** | Where the plan says "DODO PMM or Uniswap V2/V3 per chain": (1) add an explicit **Uniswap pool creation and indexing** path: set `CHAIN_*_UNISWAP_V2_FACTORY` / `CHAIN_*_UNISWAP_V3_FACTORY` and run the token-aggregation indexer so Uniswap pools appear in the API; (2) add a **maintenance** subsection: who (or which AI/MCP) is responsible for adding liquidity, rebalancing, or pausing on Uniswap pools on each chain; (3) if an AI/MCP is dedicated to Uniswap pools, define its **inputs** (API quote, pool state from indexer or RPC) and **allowed actions** (e.g. quote only vs. submit tx). |
+| **Bot–MCP–API integration** | In the **single-sided** plan (and cross-chain-pmm-lps): (1) specify that the **deviation bot** (v1/v2) can consume **pool state from the MCP** (e.g. `dodo.get_pool_state` for each allowlisted pool) or from the **token-aggregation API** (e.g. `/api/v1/tokens/:address/pools`, reserve/price from indexer); (2) specify that the bot’s **actions** (e.g. trigger buy/sell to compress δ) are either executed by the same AI that uses the MCP or by a separate executor that receives signals from the MCP/AI; (3) add **circuit-break and cooldown** to the MCP/API so the AI can read "pool in CIRCUIT_BREAK" or "cooldown until block X" and avoid sending trades. |
+| **Dedicated “pool manager” MCP/AI scope** | Add a short subsection: **Dedicated MCP/AI for Dodoex and Uniswap pool management.** Scope: (1) **Dodoex (Chain 138 + public cW*):** MCP tools for read state, quote add/remove liquidity; allowlist kept in sync with full mesh and single-sided deployments; (2) **Uniswap (per chain where used):** Same idea—allowlist or indexer-driven list of Uniswap V2/V3 pools; MCP or API to read pool state and optionally quote; (3) **Maintenance tasks:** Document that this MCP/AI is the **designated** reader (and optionally executor) for rebalancing, add/remove liquidity, and responding to deviation alerts within policy (slippage, size, circuit break). |
+
+### 2.2 RUNBOOK and script upgrades (SINGLE_SIDED_LPS_PUBLIC_NETWORKS_RUNBOOK)
+
+| Upgrade | Description |
+|---------|-------------|
+| **Post-deploy: update MCP allowlist** | In the runbook checklist, add a step: "After deploying cW* / HUB pools on chain X, update the MCP allowlist for chain X (or the multi-chain config) with pool_address, base_token, quote_token, and profile so the dedicated MCP/AI can read and manage those pools." |
+| **Post-deploy: update deployment-status.json** | Already implied; make it explicit that `deployment-status.json` is the **source for MCP allowlist generation** (script: given chainId, read deployment-status and output allowlist fragment). |
+| **List Uniswap pools per chain** | If Uniswap is used on a chain, add a step to list Uniswap V2/V3 pools (from factory events or indexer) and add them to the same MCP/API visibility (allowlist or indexer config) so one MCP/AI can "see" both DODO and Uniswap pools. |
+
+### 2.3 AI_AGENTS_57XX and POOL_ACCESS_DASHBOARD_API_MCP
+
+| Upgrade | Description |
+|---------|-------------|
+| **Multi-chain MCP** | Document an option for **one MCP server** that supports **multiple chains**: e.g. allowlist contains `chainId` per pool, and the MCP uses the appropriate RPC per chain when calling `get_pool_state` or `quote_add_liquidity`. This reduces the need to run one MCP instance per chain for Dodoex + Uniswap. |
+| **Uniswap pool profile** | Add a **pool profile** (e.g. `uniswap_v2_pair` or `uniswap_v3_pool`) to the MCP: expected view methods (getReserves, token0, token1, or slot0, liquidity, etc.) so the MCP can read Uniswap pool state and expose it to the same AI that manages DODO pools. |
+| **Dashboard and API alignment** | State that the **token-aggregation API** and the **MCP** should expose **the same set of pools** for a given chain (DODO + Uniswap once indexed): so the "custom dashboard" and the MCP/AI use one source of truth (allowlist + indexer config) and stay in sync. |
+| **Automation triggers** | Document how the dedicated AI is **triggered**: (1) **Scheduled:** cron or scheduler calls MCP/API to get state, then decides rebalance/add/remove; (2) **Event-driven:** indexer or chain watcher emits "reserve delta" or "price deviation" and triggers the AI; (3) **Manual:** operator asks the AI (via MCP) for a quote or recommendation, then executes manually. |
+
+---
+
+## 3. Summary: what to add to the “above” plans
+
+- **PMM_FULL_MESH_AND_PUBLIC_SINGLE_SIDED_PLAN:** Allowlist sync with full mesh; per-chain allowlist for cW*; Uniswap indexing and maintenance; bot–MCP–API integration; dedicated MCP/AI scope for Dodoex + Uniswap.
+- **SINGLE_SIDED_LPS_PUBLIC_NETWORKS_RUNBOOK:** Post-deploy MCP allowlist update; deployment-status as source for allowlist; Uniswap pool listing where applicable.
+- **AI_AGENTS_57XX / POOL_ACCESS:** Multi-chain MCP option; Uniswap pool profile; dashboard/API alignment; automation triggers (scheduled, event-driven, manual).
+
+---
+
+## 4. Completed upgrades (implemented)
+
+| Upgrade | Status | Implementation |
+|---------|--------|----------------|
+| **Allowlist sync with mesh** | Done | Script `scripts/generate-mcp-allowlist-from-chain138.sh`: reads `allPools(uint256)` and `poolConfigs(pool)` via RPC; outputs allowlist JSON. Use `-o ai-mcp-pmm-controller/config/allowlist-138.json` to write. Documented in PMM plan §1.5. |
+| **Per-chain allowlist from deployment-status** | Done | Script `scripts/generate-mcp-allowlist-from-deployment-status.sh <chain_id> [-o path]`: reads `deployment-status.json` pmmPools for that chain; outputs allowlist fragment with limits. Documented in SINGLE_SIDED runbook §5a, §6. |
+| **Post-deploy MCP allowlist step** | Done | Runbook §5a: run generate-mcp-allowlist-from-deployment-status.sh after deploying cW* / HUB pools. |
+| **deployment-status as source for allowlist** | Done | Runbook §6: explicit that deployment-status.json is source of truth; script generates allowlist from it. |
+| **Uniswap pool listing / indexing step** | Done | Runbook §6a: set CHAIN_*_UNISWAP_* env, run indexer; add Uniswap pools to MCP allowlist with profile when available. |
+| **Uniswap pool profile** | Done | Added `uniswap_v2_pair` and `uniswap_v3_pool` to `ai-mcp-pmm-controller/config/pool_profiles.json` with expected methods. MCP server must implement reading these methods when profile is used. |
+| **PMM plan: Uniswap, Bot–MCP, Pool Manager** | Done | Plan §2.7 (Uniswap indexing and maintenance), §2.8 (Bot–MCP–API integration), §2.9 (Dedicated MCP/AI scope); §1.5 (Allowlist sync with mesh). |
+| **Multi-chain MCP, dashboard alignment, automation** | Done | [AI_AGENTS_57XX_MCP_ADDENDUM.md](../02-architecture/AI_AGENTS_57XX_MCP_ADDENDUM.md): multi-chain allowlist/RPC, Uniswap profile reference, dashboard/API alignment, automation triggers (scheduled, event-driven, manual). |
+
+---
+
+## 5. Additional recommendations
+
+| # | Recommendation | Priority | Notes |
+|---|-----------------|----------|--------|
+| 1 | **Implement multi-chain allowlist in MCP server** | High | Extend ai-mcp-pmm-controller to accept `chainId` per pool and select RPC by chain so one server can serve Chain 138 and all public cW* chains. |
+| 2 | **Wire MCP get_pool_state to Uniswap profiles** | High | In the MCP tool implementation, when profile is `uniswap_v2_pair` or `uniswap_v3_pool`, call getReserves/slot0/liquidity and return normalized state (reserves, derived price) for the AI. |
+| 3 | **Expose circuit-break and cooldown in API or MCP** | Medium | Add an endpoint or MCP tool that returns bot state (IDLE, ABOVE_BAND, BELOW_BAND, COOLDOWN, CIRCUIT_BREAK) and cooldown-until block/time so the AI does not submit trades during cooldown or circuit-break. Source: cross-chain-pmm-lps peg-bands and bot state. |
+| 4 | **Event-driven trigger for bot/AI** | Medium | When token-aggregation indexer or a chain watcher detects reserve delta or price deviation beyond a threshold, emit an event or call a webhook that triggers the dedicated AI to fetch state (via MCP/API) and decide rebalance; keeps reaction time low without polling. |
+| 5 | **Single allowlist file for multi-chain** | Low | Allow one JSON file to contain pools for multiple chains (array of { chainId, pools }) so the MCP can load one file and serve all chains; merge output of generate-mcp-allowlist-from-chain138.sh and generate-mcp-allowlist-from-deployment-status.sh per chain into one manifest. |
+| 6 | **Rate limits and gas caps in MCP** | Medium | Enforce allowlist `limits` (max_slippage_bps, max_single_tx_notional_usd, cooldown_seconds, gas_cap_gwei) in the MCP server when the AI requests quote or execute; reject or cap out-of-policy requests. |
+| 7 | **Audit trail for AI-driven txs** | Medium | Log all MCP tool calls (get_pool_state, quote_add_liquidity, add_liquidity, etc.) and any executed txs (tx hash, pool, amount, chain) for audit and incident review. |
+| 8 | **EnhancedSwapRouter integration with MCP** | Low | When EnhancedSwapRouter is deployed on Chain 138, add it to the MCP/API so the AI can reason about multi-provider routing (Dodoex vs Uniswap vs Balancer) and optionally trigger swaps through the router. |
+
+### 5.1 Implementation status (all completed)
+
+| # | Implementation |
+|---|----------------|
+| 1 | **Multi-chain allowlist:** `config/server.py` supports allowlist format `chains: [ { chainId, pools } ]` and per-pool `chain_id`. RPC per chain via env `RPC_138`, `RPC_137`, etc. or `RPC_BY_CHAIN_PATH` (JSON file). `_get_web3(chain_id)` caches Web3 per chain. |
+| 2 | **Uniswap get_pool_state:** In `dodo_get_pool_state`, profiles `uniswap_v2_pair` and `uniswap_v3_pool` use getReserves/slot0/liquidity; return normalized state (reserves, mid_price, liquidity_base/quote). |
+| 3 | **Circuit-break and cooldown:** `GET /bot_state` and MCP tool `dodo.get_bot_state` return bot state from `BOT_STATE_PATH` (JSON). Example: `config/bot_state.example.json`. Optional `params.pool` for per-pool state. |
+| 4 | **Event-driven trigger:** `POST /webhook/trigger` accepts JSON body `{ "reason", "chain_id", "pool" }`; returns 202 and logs. Wire indexer/watcher to POST here; AI can poll MCP or react to webhook. |
+| 5 | **Single multi-chain allowlist:** Allowlist format supports `chains: [ { chainId, pools } ]`. Script `scripts/merge-mcp-allowlist-multichain.sh -o path` merges Chain 138 and other chains into one file. |
+| 6 | **Rate limits and gas caps:** `_check_limits_and_cooldown()` enforces notional, cooldown_seconds (via `COOLDOWN_STATE_PATH`), gas_cap_gwei, max_slippage_bps. Used in `dodo_simulate_action`; use `_record_trade_ts(pool)` after writes. |
+| 7 | **Audit trail:** Every MCP tool response goes through `_audit_and_return()`; logs to `AUDIT_LOG_PATH` (JSONL) and logger. |
+| 8 | **EnhancedSwapRouter stub:** MCP tool `dodo.get_router_quote` returns `configured: true/false` from `ENHANCED_SWAP_ROUTER_ADDRESS`. Add contract calls when router is deployed. |
+
+---
+
+## 6. Next steps (operator / runtime)
+
+After implementation, operators can:
+
+1. **Multi-chain MCP:** Set `ALLOWLIST_PATH` to a multi-chain file (from `scripts/merge-mcp-allowlist-multichain.sh -o path`); set `RPC_138`, `RPC_137`, etc. or `RPC_BY_CHAIN_PATH`.
+2. **Bot state:** Set `BOT_STATE_PATH` to a JSON file (see `ai-mcp-pmm-controller/config/bot_state.example.json`); update it from your peg-bands/bot or leave default.
+3. **Audit / cooldown:** Set `AUDIT_LOG_PATH` and `COOLDOWN_STATE_PATH` if you want persistent audit log and cooldown ledger.
+4. **Webhook:** Wire your indexer or chain watcher to `POST /webhook/trigger` with `{ "reason", "chain_id", "pool" }` when reserve or price deviation exceeds threshold.
+5. **EnhancedSwapRouter:** When the router is deployed on Chain 138, set `ENHANCED_SWAP_ROUTER_ADDRESS` and extend `dodo.get_router_quote` in the MCP server to call the router contract.
+
+---
+
+## 7. References
+
+- [PMM_FULL_MESH_AND_PUBLIC_SINGLE_SIDED_PLAN.md](PMM_FULL_MESH_AND_PUBLIC_SINGLE_SIDED_PLAN.md)
+- [SINGLE_SIDED_LPS_PUBLIC_NETWORKS_RUNBOOK.md](SINGLE_SIDED_LPS_PUBLIC_NETWORKS_RUNBOOK.md)
+- [AI_AGENTS_57XX_MCP_CONTRACTS_AND_CHAINS.md](../02-architecture/AI_AGENTS_57XX_MCP_CONTRACTS_AND_CHAINS.md)
+- [AI_AGENTS_57XX_DEPLOYMENT_PLAN.md](../02-architecture/AI_AGENTS_57XX_DEPLOYMENT_PLAN.md)
+- [POOL_ACCESS_DASHBOARD_API_MCP.md](../11-references/POOL_ACCESS_DASHBOARD_API_MCP.md)
+- [DEX_AND_AGGREGATORS_CHAIN138_EXPLAINER.md](../04-configuration/DEX_AND_AGGREGATORS_CHAIN138_EXPLAINER.md)
+- [DEFI_AGGREGATOR_DEX_ROUTING_FLOWS_DIAGRAM.md](DEFI_AGGREGATOR_DEX_ROUTING_FLOWS_DIAGRAM.md) — Mermaid diagram of all DeFi aggregator and DEX routing flows for swaps
+- [AI_AGENTS_57XX_MCP_ADDENDUM.md](../02-architecture/AI_AGENTS_57XX_MCP_ADDENDUM.md) — Multi-chain MCP, Uniswap profile, automation triggers
+- [OPTIONAL_TASKS_CHECKLIST.md](../00-meta/OPTIONAL_TASKS_CHECKLIST.md) — Consolidated optional tasks (Done / Pending)
--- a/docs/03-deployment/PHASE_C_CW_AND_EDGE_POOLS_RUNBOOK.md
+++ b/docs/03-deployment/PHASE_C_CW_AND_EDGE_POOLS_RUNBOOK.md
@@ -0,0 +1,37 @@
+# Phase C — cW* Tokens and Edge Pools Runbook
+
+**Last Updated:** 2026-03-04  
+**Purpose:** Execute Phase C of REMAINING_DEPLOYMENTS_FOR_FULL_NETWORK_COVERAGE: deploy or bridge cW* tokens and create/fund PMM edge pools on public chains for full SBS and arbitrage.
+
+**Prerequisites:** Phase A (hub liquidity on 138) and Phase B (CCIP bridges + LINK) should be done or in progress.
+
+---
+
+## C.1 Deploy or bridge cW* tokens per chain
+
+Chains: 1, 56, 137, 10, 42161, 8453, 43114, 100, 25, 42220, 1111.  
+Tokens: cWUSDT, cWUSDC, cWAUSDT, cWEURC, cWEURT, cWUSDW (per pool-matrix).
+
+**Steps:** (1) Use cross-chain-pmm-lps config/chains.json and pool-matrix.json. (2) Deploy CompliantWrappedToken (cW*) per chain or use bridge; set addresses in deployment-status.json and smom-dbis-138/.env. (3) Ref: TOKEN_CONTRACT_DEPLOYMENTS_REMAINING §3, CW_DEPLOY_AND_WIRE_RUNBOOK.
+
+---
+
+## C.2 Create and fund PMM edge pools per chain
+
+**Steps:** (1) From pool-matrix poolsFirst (e.g. cWUSDT/USDC), create DODO PMM or Uniswap pools per chain. (2) Add initial liquidity. (3) Record pool addresses in deployment-status.json chains[chainId].pmmPools. (4) Ensure token-aggregation/heatmap use deployment-status.
+
+**Ref:** LIQUIDITY_POOLS_MASTER_MAP § Public-chain cW*, pool-matrix.json.
+
+---
+
+## C.3 (Optional) Stabilization bot and peg bands
+
+Run deviation watcher and peg-band config from cross-chain-pmm-lps when cW* and edge pools are live.
+
+---
+
+## Quick ref
+
+- Pool matrix: cross-chain-pmm-lps/config/pool-matrix.json
+- Deployment status: cross-chain-pmm-lps/config/deployment-status.json
+- Recipe: cross-chain-pmm-lps/docs/06-deployment-recipe.md
--- a/docs/03-deployment/PHASE_D_OPTIONAL_CHECKLIST.md
+++ b/docs/03-deployment/PHASE_D_OPTIONAL_CHECKLIST.md
@@ -0,0 +1,50 @@
+# Phase D — Optional Extended Coverage Checklist
+
+**Last Updated:** 2026-03-04  
+**Purpose:** Checklist for Phase D of [REMAINING_DEPLOYMENTS_FOR_FULL_NETWORK_COVERAGE.md](REMAINING_DEPLOYMENTS_FOR_FULL_NETWORK_COVERAGE.md): XAU, vaults, ALL Mainnet, and trustless stack.
+
+---
+
+## D.1 XAU token + XAU-anchored pools (Chain 138)
+
+| Step | Action | Ref |
+|------|--------|-----|
+| D.1.1 | Deploy XAU token on Chain 138 (or use oracle-backed representation). | [LIQUIDITY_POOLS_MASTER_MAP](../11-references/LIQUIDITY_POOLS_MASTER_MAP.md) §2, §5 |
+| D.1.2 | Create cUSDT/XAU, cUSDC/XAU, cEURT/XAU PMM pools (public and/or private stabilization). | [VAULT_SYSTEM_MASTER_TECHNICAL_PLAN](../02-architecture/VAULT_SYSTEM_MASTER_TECHNICAL_PLAN.md) |
+| D.1.3 | Register private stabilization pools in PrivatePoolRegistry; configure Stabilizer. | CONTRACT_DEPLOYMENT_RUNBOOK § Private stabilization pools |
+
+**Env:** `XAU_ADDRESS_138`, `cEURT_ADDRESS_138`, `DODOPMM_INTEGRATION_ADDRESS`.
+
+---
+
+## D.2 Vault ac* / vdc* / sdc* for new base tokens
+
+| Step | Action | Ref |
+|------|--------|-----|
+| D.2.1 | Deploy vault contracts for cEURC, cEURT, etc. (ac*, vdc*, sdc*). | [TOKEN_CONTRACT_DEPLOYMENTS_REMAINING](../11-references/TOKEN_CONTRACT_DEPLOYMENTS_REMAINING.md) §5 |
+| D.2.2 | Wire vaults to reserve/backing and oracle feeds. | VAULT_SYSTEM_MASTER_TECHNICAL_PLAN |
+
+---
+
+## D.3 ALL Mainnet (651940)
+
+| Step | Action | Ref |
+|------|--------|-----|
+| D.3.1 | ACADT/ACADC when Alltra adds CAD token. | TOKEN_CONTRACT_DEPLOYMENTS_REMAINING §2, §4 |
+| D.3.2 | D-WIN W tokens on 138/651940 if desired. | Same |
+
+---
+
+## D.4 Mainnet trustless stack
+
+| Step | Action | Ref |
+|------|--------|-----|
+| D.4.1 | Deploy LiquidityPoolETH, InboxETH, BondManager on mainnet for trustless bridge liquidity. | [OPTIONAL_DEPLOYMENTS_START_HERE](../07-ccip/OPTIONAL_DEPLOYMENTS_START_HERE.md) §C |
+
+---
+
+## References
+
+- [REMAINING_DEPLOYMENTS_FOR_FULL_NETWORK_COVERAGE.md](REMAINING_DEPLOYMENTS_FOR_FULL_NETWORK_COVERAGE.md) Phase D
+- [LIQUIDITY_POOLS_MASTER_MAP](../11-references/LIQUIDITY_POOLS_MASTER_MAP.md)
+- [VAULT_SYSTEM_MASTER_TECHNICAL_PLAN](../02-architecture/VAULT_SYSTEM_MASTER_TECHNICAL_PLAN.md)
--- a/docs/03-deployment/PMM_FULL_MESH_AND_PUBLIC_SINGLE_SIDED_PLAN.md
+++ b/docs/03-deployment/PMM_FULL_MESH_AND_PUBLIC_SINGLE_SIDED_PLAN.md
@@ -0,0 +1,159 @@
+# PMM Full Mesh (Chain 138) and Single-Sided LPs (Public Networks) — Plan
+
+**Purpose:** Define and run the full PMM pool mesh on Chain 138 and the single-sided LP deployment on public networks for aggregator and DEX routing.
+
+---
+
+## Part 1 — Chain 138: Full PMM mesh
+
+### 1.1 Scope
+
+- **c* vs c* mesh:** All pairwise pools between the 12 compliant tokens: cUSDT, cUSDC, cEURC, cEURT, cGBPC, cGBPT, cAUDC, cJPYC, cCHFC, cCADC, cXAUC, cXAUT.
+  - Number of pairs: **66** (12 choose 2).
+- **c* vs official (optional):** Each c* vs official USDT and vs official USDC on Chain 138 (if addresses are set).
+  - Adds up to **24** pools (12×2) when both official tokens are configured.
+- **Already created:** The three legacy pools (cUSDT/cUSDC, cUSDT/USDT, cUSDC/USDC) are created separately; the script skips any pair that already has a pool.
+
+### 1.2 Contracts and roles
+
+| Contract | Address (Chain 138) | Role |
+|----------|---------------------|------|
+| DODOPMMIntegration | `0x79cdbaFBaA0FdF9F55D26F360F54cddE5c743F7D` | `createPool(base, quote, ...)`; `swapExactIn(pool, tokenIn, amountIn, minAmountOut)` for generic routing |
+| DODOPMMProvider | `0x8EF6657D2a86c569F6ffc337EE6b4260Bd2e59d0` | `registerPool(tokenIn, tokenOut, pool)`; `executeSwap` uses `swapExactIn` for any registered pool |
+
+- Deployer (or the account that holds **POOL_MANAGER_ROLE** on the integration and **POOL_MANAGER_ROLE** on the provider) must run pool creation and registration.
+- **Generic routing:** `DODOPMMIntegration.swapExactIn` allows any registered pool to be used for swaps; `DODOPMMProvider.executeSwap` routes through it when the pair is not one of the six legacy pairs.
+
+### 1.3 How to create the full mesh
+
+From repo root (or from `smom-dbis-138/`):
+
+```bash
+# Ensure .env has: PRIVATE_KEY, RPC_URL_138, DODO_PMM_INTEGRATION_ADDRESS, DODO_PMM_PROVIDER_ADDRESS
+
+# Create all c* vs c* pools and register with provider (and optionally c* vs official USDT/USDC)
+./scripts/create-pmm-full-mesh-chain138.sh
+
+# Only c* vs c* (no official USDT/USDC pairs)
+MESH_ONLY_C_STAR=1 ./scripts/create-pmm-full-mesh-chain138.sh
+
+# Preview only (no transactions)
+DRY_RUN=1 ./scripts/create-pmm-full-mesh-chain138.sh
+```
+
+- The script uses `DODOPMMIntegration.createPool(base, quote, lpFeeRate, initialPrice, k, isOpenTWAP)` with defaults: `lpFeeRate=3`, `initialPrice=1e18`, `k=0.5e18`, `isOpenTWAP=false`.
+- After each pool is created, it calls `DODOPMMProvider.registerPool(base, quote, pool)` so the pool is used for quotes and execution.
+
+### 1.4 Funding the mesh
+
+- Pools are created empty. Add liquidity per pool via `DODOPMMIntegration.addLiquidity(pool, baseAmount, quoteAmount)`.
+- See [PMM_POOLS_FUNDING_PLAN.md](PMM_POOLS_FUNDING_PLAN.md) and [ADD_LIQUIDITY_PMM_CHAIN138_RUNBOOK.md](ADD_LIQUIDITY_PMM_CHAIN138_RUNBOOK.md).
+- For the full mesh, prioritize funding the most-used pairs (e.g. cUSDT/cUSDC, cUSDT/USDT, cUSDC/USDC, then other c* vs c* and c* vs official).
+
+### 1.5 Allowlist sync with mesh (MCP/AI)
+
+After running `create-pmm-full-mesh-chain138.sh`, update the MCP allowlist so the dedicated MCP/AI can read state for all mesh pools without manual entry:
+
+- **Script:** `./scripts/generate-mcp-allowlist-from-chain138.sh` reads `DODOPMMIntegration.allPools(uint256)` and `poolConfigs(pool)` via RPC and outputs allowlist JSON (chain 138, profile `dodo_pmm_v2_like`).
+- **Write to MCP config:** `./scripts/generate-mcp-allowlist-from-chain138.sh -o ai-mcp-pmm-controller/config/allowlist-138.json`
+- **Requires:** `RPC_URL_138`, `DODO_PMM_INTEGRATION_ADDRESS` (or source `smom-dbis-138/.env`). See [MCP_AI_POOL_MANAGEMENT_PLAN_UPGRADES.md](MCP_AI_POOL_MANAGEMENT_PLAN_UPGRADES.md).
+
+---
+
+## Part 2 — Public networks: Single-sided LPs for aggregator and DEX routing
+
+### 2.1 Goal
+
+On **each public chain** (Ethereum, BSC, Polygon, Arbitrum, Base, Optimism, Gnosis, Avalanche, Cronos, Celo, Wemix), deploy **single-sided PMM (or equivalent) pools** of the form **cW* / HUB**, where:
+
+- **cW*** = bridged compliant wrapped tokens (cWUSDT, cWUSDC, cWEURC, cWEURT, etc.).
+- **HUB** = the chain’s main stable (e.g. USDC or USDT per chain).
+
+These pools are used for:
+
+- **Aggregator and DEX routing:** So 1inch, 0x, ParaSwap, and other DEX aggregators can route through cW* / HUB for swap and bridge flows.
+- **Peg stabilization:** Single-sided liquidity on the cW* side; the other side is filled by market/arbitrage.
+
+### 2.2 Topology and config
+
+- **Pool topology:** One pool per **cW*** per chain against the chain’s **hub stable** (and optionally extra stables). See [cross-chain-pmm-lps/docs/02-pool-topology.md](../../cross-chain-pmm-lps/docs/02-pool-topology.md).
+- **Matrix:** [cross-chain-pmm-lps/config/pool-matrix.json](../../cross-chain-pmm-lps/config/pool-matrix.json) defines per chain:
+  - `hubStable` (USDC or USDT),
+  - `poolsFirst`: cW* / HUB pools to deploy first,
+  - `poolsOptional`: extra quote stables (e.g. USDT, DAI, BUSD) if needed for routing.
+
+### 2.3 Chains and hub stables (from pool-matrix)
+
+| ChainId | Network | Hub stable | Priority pools |
+|---------|---------|------------|----------------|
+| 1 | Ethereum Mainnet | USDC | cWUSDT/USDC, cWUSDC/USDC, cWEURC/USDC, cWEURT/USDC, cWUSDW/USDC, cWAUSDT/USDC |
+| 56 | BSC | USDT | cWUSDT/USDT, cWUSDC/USDT, … |
+| 137 | Polygon | USDC | cWUSDT/USDC, cWUSDC/USDC, … |
+| 10 | Optimism | USDC | same pattern |
+| 100 | Gnosis | USDC | same + optional mUSD |
+| 25 | Cronos | USDT | cW* / USDT |
+| 42161 | Arbitrum One | USDC | cW* / USDC |
+| 8453 | Base | USDC | cW* / USDC |
+| 43114 | Avalanche | USDC | cW* / USDC |
+| 42220 | Celo | USDC | cW* / USDC |
+| 1111 | Wemix | USDT | cW* / USDT |
+
+### 2.4 Deployment steps (per chain)
+
+1. **Deploy or confirm cW* tokens** on that chain (e.g. via DeployCWTokens or existing addresses).
+2. **Resolve HUB stable address** (USDC or USDT) on that chain from your config or chain list.
+3. **Create cW* / HUB pool** on the chain’s DEX:
+   - If the chain uses a **DODO-style PMM**: deploy or use a DVM/factory and create a pool (base = cW*, quote = HUB) with single-sided deposit on the cW* side.
+   - If the chain uses **Uniswap V2/V3** or another AMM: create a pair/pool and add single-sided liquidity on the cW* side (or use a vault that supports single-sided).
+4. **Register pool** in your indexer/aggregator config (token-aggregation, explorer, or external aggregator) so routes use the new pool.
+5. **Optional:** Run the **bot** (deviation watcher, rebalancing) as in [cross-chain-pmm-lps/docs/06-deployment-recipe.md](../../cross-chain-pmm-lps/docs/06-deployment-recipe.md).
+
+### 2.5 Deployment status and script stub
+
+- **Status:** Per-chain cW* addresses and PMM pool addresses are tracked in [cross-chain-pmm-lps/config/deployment-status.json](../../cross-chain-pmm-lps/config/deployment-status.json). Fill `cwTokens`, `anchorAddresses` (HUB), and `pmmPools` as you deploy.
+- **Script stub:** Use [SINGLE_SIDED_LPS_PUBLIC_NETWORKS_RUNBOOK.md](SINGLE_SIDED_LPS_PUBLIC_NETWORKS_RUNBOOK.md) for a step-by-step runbook and a shell stub that outputs the list of pools to create per chain from `pool-matrix.json`.
+
+### 2.6 Aggregator and DEX routing
+
+- Once cW* / HUB pools exist and are indexed, aggregators (1inch, 0x, ParaSwap, etc.) can include them in routing when they support that chain.
+- For **swap–bridge–swap** and **quote APIs**, point destination-chain quote to the chain’s DEX that hosts the cW* / HUB pools so that routes use these pools for cW* ↔ HUB.
+
+### 2.7 Uniswap pool indexing and maintenance
+
+Where the plan uses **Uniswap V2/V3** on a chain (instead of or in addition to DODO PMM):
+
+- **Indexing:** Set `CHAIN_*_UNISWAP_V2_FACTORY` / `CHAIN_*_UNISWAP_V3_FACTORY` (and optional `_ROUTER`, `_START_BLOCK`) in the token-aggregation service env and run the indexer so Uniswap pools appear in the API (`/api/v1/tokens`, `/api/v1/quote`, `/api/v1/tokens/:address/pools`).
+- **Maintenance:** Designate who (or which AI/MCP) is responsible for adding liquidity, rebalancing, or pausing on Uniswap pools on each chain. The dedicated MCP/AI (see §2.9) can use the same allowlist or indexer-driven list for Uniswap pools; define **inputs** (API quote, pool state from indexer or RPC) and **allowed actions** (quote only vs. submit tx) per policy. See [MCP_AI_POOL_MANAGEMENT_PLAN_UPGRADES.md](MCP_AI_POOL_MANAGEMENT_PLAN_UPGRADES.md) §2.1.
+
+### 2.8 Bot–MCP–API integration
+
+For the **deviation bot** (cross-chain-pmm-lps v1/v2) that maintains the cW* peg on public chains:
+
+- **Pool state source:** The bot can consume pool state from (1) the **MCP** (e.g. `dodo.get_pool_state` for each allowlisted pool) or (2) the **token-aggregation API** (e.g. `GET /api/v1/tokens/:address/pools`, reserve/price from indexer). Use one source of truth per chain so the bot and the MCP/AI stay aligned.
+- **Actions:** Bot actions (buy/sell to compress δ, inventory adjust) can be executed by the same AI that uses the MCP or by a **separate executor** that receives signals from the MCP/AI. Document which component is authorized to submit txs (and under which circuit-break/cooldown rules).
+- **Circuit-break and cooldown:** Expose "pool in CIRCUIT_BREAK" or "cooldown until block X" in the MCP or API (e.g. from peg-bands config or bot state) so the AI can avoid sending trades when the pool is in cooldown or circuit-break. See [cross-chain-pmm-lps/spec/bot-state-machine.md](../../cross-chain-pmm-lps/spec/bot-state-machine.md).
+
+### 2.9 Dedicated MCP/AI for Dodoex and Uniswap pool management
+
+A single **dedicated MCP/AI** is the designated reader (and optionally executor) for managing and maintaining all Dodoex and Uniswap liquidity pools:
+
+- **Dodoex (Chain 138 + public cW*):** MCP tools for read state (`get_pool_state`), quote add/remove liquidity; allowlist kept in sync with full mesh (script §1.5) and single-sided deployments (script `generate-mcp-allowlist-from-deployment-status.sh`). One MCP instance per chain or multi-chain allowlist with `chainId` per pool.
+- **Uniswap (per chain where used):** Allowlist or indexer-driven list of Uniswap V2/V3 pools; MCP or API to read pool state (profile `uniswap_v2_pair` / `uniswap_v3_pool` when implemented) and optionally quote. Same MCP/AI can manage both DODO and Uniswap pools for that chain.
+- **Maintenance tasks:** This MCP/AI is the **designated** reader (and optionally executor) for rebalancing, add/remove liquidity, and responding to deviation alerts within policy (slippage, size, circuit break). See [MCP_AI_POOL_MANAGEMENT_PLAN_UPGRADES.md](MCP_AI_POOL_MANAGEMENT_PLAN_UPGRADES.md) and [AI_AGENTS_57XX_MCP_ADDENDUM.md](../02-architecture/AI_AGENTS_57XX_MCP_ADDENDUM.md).
+
+---
+
+## References
+
+| Document | Purpose |
+|----------|---------|
+| [PMM_POOLS_FUNDING_PLAN.md](PMM_POOLS_FUNDING_PLAN.md) | Funding Chain 138 PMM pools (amounts, cast commands) |
+| [ADD_LIQUIDITY_PMM_CHAIN138_RUNBOOK.md](ADD_LIQUIDITY_PMM_CHAIN138_RUNBOOK.md) | Add liquidity to DODO PMM on Chain 138 |
+| [SINGLE_SIDED_LPS_PUBLIC_NETWORKS_RUNBOOK.md](SINGLE_SIDED_LPS_PUBLIC_NETWORKS_RUNBOOK.md) | Single-sided LPs on public chains (runbook + script stub) |
+| [MCP_AI_POOL_MANAGEMENT_PLAN_UPGRADES.md](MCP_AI_POOL_MANAGEMENT_PLAN_UPGRADES.md) | MCP and AI upgrades for Dodoex and Uniswap pool management |
+| [DEFI_AGGREGATOR_DEX_ROUTING_FLOWS_DIAGRAM.md](DEFI_AGGREGATOR_DEX_ROUTING_FLOWS_DIAGRAM.md) | Mermaid: all DeFi aggregator and DEX routing flows for swaps |
+| [LIQUIDITY_POOLS_MASTER_MAP.md](../11-references/LIQUIDITY_POOLS_MASTER_MAP.md) | Pool addresses and status |
+| [cross-chain-pmm-lps/README.md](../../cross-chain-pmm-lps/README.md) | cW* single-sided PMM mesh design |
+| [cross-chain-pmm-lps/docs/02-pool-topology.md](../../cross-chain-pmm-lps/docs/02-pool-topology.md) | Pool topology (cW* / HUB) |
+| [cross-chain-pmm-lps/docs/06-deployment-recipe.md](../../cross-chain-pmm-lps/docs/06-deployment-recipe.md) | Deployment recipe and bot |
+| [PMM_DEX_ROUTING_STATUS.md](../11-references/PMM_DEX_ROUTING_STATUS.md) | PMM/DEX routing status |
--- a/docs/03-deployment/PMM_POOLS_FUNDING_PLAN.md
+++ b/docs/03-deployment/PMM_POOLS_FUNDING_PLAN.md
@@ -0,0 +1,154 @@
+# PMM Pools Funding Plan - Chain 138
+
+**Purpose:** Step-by-step plan to fund the three DODO PMM liquidity pools on Chain 138.
+**Deployer:** `0x4A666F96fC8764181194447A7dFdb7d471b301C8`
+**Integration:** `DODOPMMIntegration` at `0x79cdbaFBaA0FdF9F55D26F360F54cddE5c743F7D`
+
+---
+
+## 1. The three pools
+
+| Pool | Base token | Quote token | Pool address | Fund when |
+|------|------------|-------------|--------------|-----------|
+| **1. cUSDT/cUSDC** | cUSDT | cUSDC | `0x9fcB06Aa1FD5215DC0E91Fd098aeff4B62fEa5C8` | Deployer has cUSDT + cUSDC (mintable) |
+| **2. cUSDT/USDT** | cUSDT | USDT (official) | `0xa3Ee6091696B28e5497b6F491fA1e99047250c59` | Deployer has cUSDT + official USDT |
+| **3. cUSDC/USDC** | cUSDC | USDC (official) | `0x90bd9Bf18Daa26Af3e814ea224032d015db58Ea5` | Deployer has cUSDC + official USDC |
+
+- **Pool 1** uses only c* tokens; you can mint both on Chain 138 and fund fully.
+- **Pools 2 and 3** need "official" USDT/USDC on 138 (set in DODOPMMIntegration at deploy time). If those are deployer-owned mocks, mint them too; otherwise fund only from existing balance.
+
+---
+
+## 2. Token addresses (Chain 138)
+
+| Token | Address | Mintable by deployer? |
+|-------|---------|------------------------|
+| cUSDT | `0x93E66202A11B1772E55407B32B44e5Cd8eda7f22` | Yes (owner) |
+| cUSDC | `0xf22258f57794CC8E06237084b353Ab30fFfa640b` | Yes (owner) |
+| Official USDT | From integration: cast call INT "officialUSDT()(address)" | Depends (check owner) |
+| Official USDC | From integration: cast call INT "officialUSDC()(address)" | Depends (check owner) |
+
+---
+
+## 3. Current state (as of 2026-03-02)
+
+- **Pool 1 (cUSDT/cUSDC):** Already funded with 500,000 cUSDT and 500,000 cUSDC (single addLiquidity tx).
+- **Pools 2 and 3:** Not funded yet (require deployer balance of official USDT/USDC on 138).
+- **Deployer c* supply:** 1M+ of each c* minted (including cUSDT, cUSDC) via mint-all-c-star-138.sh and earlier mints.
+
+---
+
+## 4. Funding plan options
+
+### Plan A - Fund only Pool 1 (cUSDT/cUSDC) - recommended first
+
+Use only cUSDT and cUSDC; no official USDT/USDC needed.
+
+| Step | Action | Command / notes |
+|------|--------|------------------|
+| 1 | Ensure deployer has enough cUSDT and cUSDC | Mint if needed: ./scripts/mint-for-liquidity.sh or ./scripts/mint-all-c-star-138.sh [amount] |
+| 2 | Decide amount per side (base units, 6 decimals) | e.g. 1M each = 1000000000000 (1e12) |
+| 3 | Approve integration to spend cUSDT and cUSDC | See section 5 below (cast) or run add-liquidity script |
+| 4 | Add liquidity to Pool 1 | addLiquidity(POOL_CUSDTCUSDC, baseAmount, quoteAmount) via cast or Forge script |
+
+### Plan B - Fund all three pools
+
+Requires deployer to hold official USDT and USDC on Chain 138 (in addition to cUSDT/cUSDC).
+
+| Step | Action | Command / notes |
+|------|--------|------------------|
+| 1 | Check deployer balances | ./scripts/deployment/check-deployer-balance-chain138-and-funding-plan.sh |
+| 2 | Mint cUSDT/cUSDC (and official USDT/USDC if deployer is owner) | ./scripts/mint-for-liquidity.sh; mint official tokens if contracts allow |
+| 3 | Set .env amounts | ADD_LIQUIDITY_BASE_AMOUNT, ADD_LIQUIDITY_QUOTE_AMOUNT; optionally per-pool overrides |
+| 4 | Add liquidity to all three pools | Forge script (if it compiles) or three separate cast addLiquidity calls |
+
+### Plan C - "Half of balance" rule (from existing doc)
+
+Use 50% of deployer cUSDT and cUSDC for liquidity; keep the rest for gas/other use.
+
+1. Run: RPC_URL_138=<rpc> ./scripts/deployment/check-deployer-balance-chain138-and-funding-plan.sh
+2. Copy the printed ADD_LIQUIDITY_BASE_AMOUNT and ADD_LIQUIDITY_QUOTE_AMOUNT (half of current balances) into smom-dbis-138/.env
+3. Add liquidity (Pool 1 only if you do not have official USDT/USDC) per section 5.
+
+---
+
+## 5. Commands to add liquidity
+
+**Prereqs:** smom-dbis-138/.env with PRIVATE_KEY, RPC_URL_138. Deployer must hold at least the amounts you add.
+
+### Option 1 - Cast (reliable; use if Forge script fails)
+
+From repo root, with smom-dbis-138/.env sourced:
+
+```bash
+cd smom-dbis-138 && source .env
+
+INT=0x79cdbaFBaA0FdF9F55D26F360F54cddE5c743F7D
+POOL1=0x9fcB06Aa1FD5215DC0E91Fd098aeff4B62fEa5C8
+CUSDT=0x93E66202A11B1772E55407B32B44e5Cd8eda7f22
+CUSDC=0xf22258f57794CC8E06237084b353Ab30fFfa640b
+RPC="$RPC_URL_138"
+MAX=0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
+
+# Approve (once per token)
+cast send "$CUSDT" "approve(address,uint256)" "$INT" "$MAX" --rpc-url "$RPC" --private-key "$PRIVATE_KEY" --legacy --gas-limit 100000
+cast send "$CUSDC" "approve(address,uint256)" "$INT" "$MAX" --rpc-url "$RPC" --private-key "$PRIVATE_KEY" --legacy --gas-limit 100000
+
+# Add liquidity to Pool 1 (amounts in base units, 6 decimals; e.g. 1M = 1000000000000)
+BASE_AMOUNT=1000000000000
+QUOTE_AMOUNT=1000000000000
+cast send "$INT" "addLiquidity(address,uint256,uint256)" "$POOL1" "$BASE_AMOUNT" "$QUOTE_AMOUNT" --rpc-url "$RPC" --private-key "$PRIVATE_KEY" --legacy --gas-limit 500000
+```
+
+### Option 2 - Forge script (if it compiles)
+
+```bash
+cd smom-dbis-138 && source .env
+export POOL_CUSDTCUSDC=0x9fcB06Aa1FD5215DC0E91Fd098aeff4B62fEa5C8
+export ADD_LIQUIDITY_BASE_AMOUNT=1000000000000
+export ADD_LIQUIDITY_QUOTE_AMOUNT=1000000000000
+
+forge script script/dex/AddLiquidityPMMPoolsChain138.s.sol:AddLiquidityPMMPoolsChain138 \
+  --rpc-url "$RPC_URL_138" --broadcast --private-key "$PRIVATE_KEY" --with-gas-price 1000000000 --legacy
+```
+
+### Option 3 - Mint and add in one go (Pool 1 only)
+
+```bash
+./scripts/mint-for-liquidity.sh --add-liquidity
+```
+
+Uses half of minted amounts for Pool 1; requires DODO_PMM_INTEGRATION and pool addresses set in smom-dbis-138/.env.
+
+---
+
+## 6. Suggested amounts (Pool 1)
+
+| Goal | Base (cUSDT) | Quote (cUSDC) | Base units each (6 decimals) |
+|------|----------------|----------------|------------------------------|
+| Light | 100,000 | 100,000 | 100000000000 |
+| Medium | 500,000 | 500,000 | 500000000000 |
+| Heavy | 1,000,000 | 1,000,000 | 1000000000000 |
+| Already added | 500,000 | 500,000 | (done) |
+
+You can run the Add liquidity step multiple times to add more (e.g. another 500k/500k for Pool 1).
+
+---
+
+## 7. Checklist summary
+
+- [ ] 1. Run check-deployer-balance-chain138-and-funding-plan.sh and note half-balance amounts.
+- [ ] 2. Mint cUSDT/cUSDC if needed: ./scripts/mint-for-liquidity.sh or ./scripts/mint-all-c-star-138.sh
+- [ ] 3. (Optional) If funding Pools 2 and 3: obtain or mint official USDT/USDC on 138; approve integration.
+- [ ] 4. Approve cUSDT and cUSDC to DODOPMMIntegration (see section 5 Option 1).
+- [ ] 5. Add liquidity to Pool 1 (and optionally Pools 2 and 3) via cast or Forge script.
+- [ ] 6. Verify on explorer: pool balances or LP tokens for deployer.
+
+---
+
+## 8. References
+
+- ADD_LIQUIDITY_PMM_CHAIN138_RUNBOOK.md - Add-liquidity runbook
+- docs/11-references/DEPLOYER_WALLET_FUNDING_PLAN_PMM_POOLS.md - Deployer balances and 50% rule
+- docs/11-references/LIQUIDITY_POOLS_MASTER_MAP.md - Pool addresses and status
+- docs/11-references/TOKENS_AND_NETWORKS_MINTABLE_TO_DEPLOYER.md - How to mint c* on 138
--- a/docs/03-deployment/REMAINING_DEPLOYMENTS_FOR_FULL_NETWORK_COVERAGE.md
+++ b/docs/03-deployment/REMAINING_DEPLOYMENTS_FOR_FULL_NETWORK_COVERAGE.md
@@ -0,0 +1,146 @@
+# Remaining Deployments for Full Network Coverage
+
+**Last Updated:** 2026-03-04  
+**Purpose:** Ordered list of remaining deployments to achieve **maximum effective execution across all networks** (13-chain hub model: Chain 138 + 12 edge/alt). Use after [REQUIRED_FIXES_GAPS_AND_DEPLOYMENTS_LIST](../00-meta/REQUIRED_FIXES_GAPS_AND_DEPLOYMENTS_LIST.md) and [DEPLOYMENT_ORDER_OF_OPERATIONS](DEPLOYMENT_ORDER_OF_OPERATIONS.md).
+
+**Routing context:** [routing-matrix-13x13.json](../../smom-dbis-138/real-robinhood/data/routing-matrix-13x13.json) — 138↔Celo (42220) **B/SBS** (CCIP bridges deployed 2026-03-04); 138↔Wemix (1111) **TBD** (deployer needs 0.4 WEMIX). Full coverage = all 13 chains with bridge + liquidity where designed.
+
+---
+
+## Phase execution status (2026-03-04)
+
+| Phase | Step | Status | Notes |
+|-------|------|--------|-------|
+| A | A.1 Mint cUSDT/cUSDC (138) | ⚠️ Blocked | Mint script now uses `GAS_PRICE_138`; with 500 gwei first tx accepted but confirmation times out while block production is stalled. When blocks advance, run `mint-for-liquidity.sh` (use `GAS_PRICE_138=500000000000` if “Replacement transaction underpriced”). |
+| A | A.2 Add liquidity PMM (138) | ⏳ Pending | After A.1 succeeds; run `mint-for-liquidity.sh --add-liquidity` or AddLiquidityPMMPoolsChain138. |
+| B | B.1 Celo CCIP bridges | ✅ Done | Deployed; 0xD3AD6831aacB5386B8A25BB8D8176a6C8a026f04 (WETH9), 0xa4B9DD039565AeD9641D45b57061f99d9cA6Df08 (WETH10); .env updated; complete-config Celo→138 OK. |
+| B | B.2 Wemix CCIP bridges | ⏳ Blocked | Deployer 0 WEMIX; need 0.4 WEMIX then run `deploy-bridges-config-ready-chains.sh wemix`. |
+| B | **Gnosis CCIP bridges** | ✅ Done (2026-03-04) | Deployed: WETH9 `0x4ab39b5BaB7b463435209A9039bd40Cf241F5a82`, WETH10 `0xC15ACdBAC59B3C7Cb4Ea4B3D58334A4b143B4b44`; .env updated. |
+| B | B.3 Fund CCIP with LINK | ⏳ Ready | Run `fund-ccip-bridges-with-link.sh` (dry-run done). |
+| C | C.1–C.2 cW* + edge pools | 📋 Runbook | [PHASE_C_CW_AND_EDGE_POOLS_RUNBOOK.md](PHASE_C_CW_AND_EDGE_POOLS_RUNBOOK.md). |
+| D | D.1–D.4 Optional XAU/vaults/trustless | 📋 Checklist | [PHASE_D_OPTIONAL_CHECKLIST.md](PHASE_D_OPTIONAL_CHECKLIST.md). |
+
+**Latest run (same session):** A.1 mint retry → timeout again (Chain 138 RPC). complete-config → Step A/B still fail (138 tx timeout or destination already set). Gnosis bridges deployed ✅. fund-ccip → failed (Chain 138 Invalid params; other chains: insufficient LINK or gas). Cronos deploy skipped (set CRONOS_RPC and CCIP_ROUTER_CRONOS in .env).
+
+---
+
+## Status to continue (run these before Phase A mint/deploy)
+
+| Item | Status | Action |
+|------|--------|--------|
+| **Core RPC 2101** | ✅ Healthy (container, besu-rpc, port 8545, chain 138, DB writable) | None. Use `RPC_URL_138=http://192.168.11.211:8545`. |
+| **Tx pool** | May repopulate after clear | Run `./scripts/clear-all-transaction-pools.sh`; if mint fails with “Replacement transaction underpriced”, use `GAS_PRICE_138=500000000000` (500 gwei) when running mint. |
+| **Validators** | 1000–1004 active (1004 restarted 2026-03-04) | If 1004 fails again: `ssh root@192.168.11.10 'pct exec 1004 -- systemctl restart besu-validator'`. |
+| **Block production** | Stalled (blocks not advancing) | **Blocker for confirmations.** Run `./scripts/monitoring/monitor-blockchain-health.sh`; when blocks advance, mint/add-liquidity txs will confirm. |
+
+**Next steps in order:** (1) Ensure blocks are advancing (all 5 validators active, wait for sync). (2) `cd smom-dbis-138 && ./scripts/mint-for-liquidity.sh` (optionally `GAS_PRICE_138=500000000000` if pool has a stuck tx). (3) After mint confirms, optionally `--add-liquidity`. See [CORE_RPC_2101_2102_TXPOOL_ADMIN_STATUS.md](../04-configuration/CORE_RPC_2101_2102_TXPOOL_ADMIN_STATUS.md) §7–8.
+
+---
+
+## Current state (verified)
+
+| Area | Status |
+|------|--------|
+| Chain 138 core + PMM | 38/38 contracts; DODOPMMIntegration + 3 pools (cUSDT/cUSDC, cUSDT/USDT, cUSDC/USDC) created; DODOPMMProvider deployed. |
+| Chain 138 liquidity | **0** in pools — deployer WETH/cUSDT/cUSDC = 0; add liquidity blocked until mint/fund. |
+| CCIP 138 → 1, 56, 137, 10, 42161, 43114, 8453, 100, 25, **42220 (Celo)** | Configured (B/SBS). Celo CCIP bridges deployed 2026-03-04; Gnosis, Cronos config-ready; Wemix (1111) **TBD** (need 0.4 WEMIX). |
+| Alltra 138 ↔ 651940 | ALT path live. |
+| cW* on public chains | Addresses in .env / design; **deployment-status.json empty** — no cW* pool addresses. |
+| LINK for CCIP | Fund bridges per lane so cross-chain messages execute. |
+
+---
+
+## Phase A — Hub liquidity (Chain 138)
+
+**Goal:** Enable swap execution on Chain 138 (cUSDT↔cUSDC and future pairs).
+
+| Step | Action | Ref |
+|------|--------|-----|
+| A.1 | **Mint cUSDT and cUSDC to deployer** (owner mint). | [TOKENS_AND_NETWORKS_MINTABLE_TO_DEPLOYER](../11-references/TOKENS_AND_NETWORKS_MINTABLE_TO_DEPLOYER.md) §1. Use `./scripts/mint-for-liquidity.sh` in smom-dbis-138 (or `mint-to-750m.sh`). |
+| A.2 | **Add liquidity to PMM pools** (cUSDT/cUSDC first; then cUSDT/USDT, cUSDC/USDC if official tokens exist on 138). Set `ADD_LIQUIDITY_*` in smom-dbis-138/.env; run AddLiquidityPMMPoolsChain138 or `mint-for-liquidity.sh --add-liquidity`. | [ADD_LIQUIDITY_PMM_CHAIN138_RUNBOOK](ADD_LIQUIDITY_PMM_CHAIN138_RUNBOOK.md) |
+| A.3 | **(Optional)** Mint other c* (cEURC, cEURT, cGBP*, etc.) for future pools / bridge; extend PMM mesh if desired. | [TOKEN_CONTRACT_DEPLOYMENTS_REMAINING](../11-references/TOKEN_CONTRACT_DEPLOYMENTS_REMAINING.md) §1; DeployCompliantFiatTokens already run (10 tokens). |
+
+**Pre-checks:** `./scripts/deployment/preflight-chain138-deploy.sh`; `RPC_URL_138=http://192.168.11.211:8545 ./scripts/deployment/check-deployer-balance-chain138-and-funding-plan.sh`.
+
+---
+
+## Phase B — Bridge coverage (all 13 chains)
+
+**Goal:** Turn **TBD** into **B/SBS** for Celo and Wemix; ensure LINK-funded lanes so routes execute.
+
+| Step | Action | Ref |
+|------|--------|-----|
+| B.1 | **Celo (42220):** Deploy CCIP WETH9/WETH10 bridges on Celo; add 138↔Celo destinations on both sides; fund bridges with LINK. | [CONFIG_READY_CHAINS_COMPLETION_RUNBOOK](../07-ccip/CONFIG_READY_CHAINS_COMPLETION_RUNBOOK.md). Preflight: `./scripts/deployment/preflight-config-ready-chains.sh celo`. Deploy: `./scripts/deployment/deploy-bridges-config-ready-chains.sh celo`; then `complete-config-ready-chains.sh`. |
+| B.2 | **Wemix (1111):** Same as B.1 for Wemix. Confirm WETH/USDT/USDC addresses on scan.wemix.com; set in token-mapping and .env. | Same runbook; `deploy-bridges-config-ready-chains.sh wemix`. [REQUIRED_FIXES_GAPS_AND_DEPLOYMENTS_LIST](../00-meta/REQUIRED_FIXES_GAPS_AND_DEPLOYMENTS_LIST.md) §2.2 (Wemix tokens). |
+| B.3 | **Fund all CCIP bridges with LINK** (138 and each destination). Run `./scripts/deployment/fund-ccip-bridges-with-link.sh` (dry-run first). | [CCIP_BRIDGE_DESTINATIONS_AND_LINK_FUNDING](../../smom-dbis-138/docs/deployment/CCIP_BRIDGE_DESTINATIONS_AND_LINK_FUNDING.md) |
+| B.4 | **(Optional)** LINK support on Mainnet relay for LINK transfers. | [RELAY_BRIDGE_ADD_LINK_SUPPORT_RUNBOOK](../07-ccip/RELAY_BRIDGE_ADD_LINK_SUPPORT_RUNBOOK.md) |
+
+**Outcome:** 138↔1, 56, 137, 10, 42161, 43114, 8453, 100, 25, **42220**, **1111** all B/SBS; 138↔651940 remains ALT. Routing matrix TBD cells removed.
+
+---
+
+## Phase C — Public-chain cW* and edge pools
+
+**Goal:** Enable swap-bridge-swap and arbitrage on **public chains** (cW* tokens + DODO/Uniswap edge pools per pool-matrix).
+
+| Step | Action | Ref |
+|------|--------|-----|
+| C.1 | **Deploy or bridge cW* tokens** per chain (1, 56, 137, 10, 42161, 8453, 43114, 100, 25, 42220, 1111). Use cross-chain-pmm-lps token-map and deployment recipe; record addresses in deployment-status.json and .env. | [PHASE_C_CW_AND_EDGE_POOLS_RUNBOOK](PHASE_C_CW_AND_EDGE_POOLS_RUNBOOK.md), [TOKEN_CONTRACT_DEPLOYMENTS_REMAINING](../11-references/TOKEN_CONTRACT_DEPLOYMENTS_REMAINING.md) §3 |
+| C.2 | **Create and fund PMM edge pools** (cW*/USDC, cW*/USDT, etc.) per [pool-matrix.json](../../cross-chain-pmm-lps/config/pool-matrix.json). Populate deployment-status.json with pool addresses. | [PHASE_C_CW_AND_EDGE_POOLS_RUNBOOK](PHASE_C_CW_AND_EDGE_POOLS_RUNBOOK.md), [LIQUIDITY_POOLS_MASTER_MAP](../11-references/LIQUIDITY_POOLS_MASTER_MAP.md) § Public-chain cW* |
+| C.3 | **Stabilization bot / peg bands** (optional): Run bot and peg-band config from cross-chain-pmm-lps for cW* peg maintenance. | [cross-chain-pmm-lps/README.md](../../cross-chain-pmm-lps/README.md) |
+
+**Outcome:** Each public chain has cW* and edge pools so SBS and arbitrage can execute on both 138 and edge.
+
+---
+
+## Phase D — Optional (extended coverage)
+
+| Step | Action | Ref |
+|------|--------|-----|
+| D.1 | **XAU token + XAU-anchored pools (138):** Deploy XAU; create cUSDT/XAU, cUSDC/XAU, cEURT/XAU PMM pools and private stabilization pools. | [PHASE_D_OPTIONAL_CHECKLIST](PHASE_D_OPTIONAL_CHECKLIST.md), [LIQUIDITY_POOLS_MASTER_MAP](../11-references/LIQUIDITY_POOLS_MASTER_MAP.md) §2, §5 |
+| D.2 | **Vault ac* / vdc* / sdc*** for new base tokens (cEURC, cEURT, etc.). | [PHASE_D_OPTIONAL_CHECKLIST](PHASE_D_OPTIONAL_CHECKLIST.md), [TOKEN_CONTRACT_DEPLOYMENTS_REMAINING](../11-references/TOKEN_CONTRACT_DEPLOYMENTS_REMAINING.md) §5 |
+| D.3 | **ALL Mainnet (651940):** ACADT/ACADC when Alltra adds CAD; D-WIN W on 138/651940 if desired. | [PHASE_D_OPTIONAL_CHECKLIST](PHASE_D_OPTIONAL_CHECKLIST.md) |
+| D.4 | **Mainnet trustless stack:** LiquidityPoolETH, InboxETH, BondManager on mainnet for trustless bridge liquidity. | [PHASE_D_OPTIONAL_CHECKLIST](PHASE_D_OPTIONAL_CHECKLIST.md), [OPTIONAL_DEPLOYMENTS_START_HERE](../07-ccip/OPTIONAL_DEPLOYMENTS_START_HERE.md) §C |
+
+---
+
+## Execution order (recommended)
+
+1. **A.1 → A.2** (mint + add liquidity on 138) so hub has executable liquidity.
+2. **B.1 → B.2 → B.3** (Celo + Wemix CCIP + LINK fund) so all 13 chains are routable and bridges can execute.
+3. **C.1 → C.2** (cW* + edge pools) so public chains have full SBS and arbitrage.
+4. **D.** as needed for XAU, vaults, and optional chains/tokens.
+
+---
+
+## Quick command reference
+
+| Task | Command / script |
+|------|------------------|
+| Preflight (138) | `./scripts/deployment/preflight-chain138-deploy.sh` |
+| Mint cUSDT/cUSDC (138) | `cd smom-dbis-138 && ./scripts/mint-for-liquidity.sh` |
+| Mint + add liquidity | `./scripts/mint-for-liquidity.sh --add-liquidity` |
+| Preflight (config-ready chains) | `cd smom-dbis-138 && ./scripts/deployment/preflight-config-ready-chains.sh [celo|wemix|all]` |
+| Deploy bridges (Celo/Wemix) | `./scripts/deployment/deploy-bridges-config-ready-chains.sh [celo|wemix|all]` |
+| Complete destinations | `./scripts/deployment/complete-config-ready-chains.sh` |
+| Fund CCIP with LINK | `./scripts/deployment/fund-ccip-bridges-with-link.sh` |
+| Add liquidity runbook | [ADD_LIQUIDITY_PMM_CHAIN138_RUNBOOK](ADD_LIQUIDITY_PMM_CHAIN138_RUNBOOK.md) |
+
+---
+
+## Phase runbooks
+
+- **Phase C (cW* + edge pools):** [PHASE_C_CW_AND_EDGE_POOLS_RUNBOOK.md](PHASE_C_CW_AND_EDGE_POOLS_RUNBOOK.md)
+- **Phase D (optional XAU, vaults, trustless):** [PHASE_D_OPTIONAL_CHECKLIST.md](PHASE_D_OPTIONAL_CHECKLIST.md)
+
+---
+
+## References
+
+- [REQUIRED_FIXES_GAPS_AND_DEPLOYMENTS_LIST](../00-meta/REQUIRED_FIXES_GAPS_AND_DEPLOYMENTS_LIST.md)
+- [DEPLOYMENT_ORDER_OF_OPERATIONS](DEPLOYMENT_ORDER_OF_OPERATIONS.md)
+- [TOKENS_AND_NETWORKS_MINTABLE_TO_DEPLOYER](../11-references/TOKENS_AND_NETWORKS_MINTABLE_TO_DEPLOYER.md)
+- [DEPLOYED_TOKENS_BRIDGES_LPS_AND_ROUTING_STATUS](../11-references/DEPLOYED_TOKENS_BRIDGES_LPS_AND_ROUTING_STATUS.md)
+- [CONFIG_READY_CHAINS_COMPLETION_RUNBOOK](../07-ccip/CONFIG_READY_CHAINS_COMPLETION_RUNBOOK.md)
+- [LIQUIDITY_POOLS_MASTER_MAP](../11-references/LIQUIDITY_POOLS_MASTER_MAP.md)
+- [TODOS_CONSOLIDATED](../00-meta/TODOS_CONSOLIDATED.md)
--- a/docs/03-deployment/SINGLE_SIDED_LPS_PUBLIC_NETWORKS_RUNBOOK.md
+++ b/docs/03-deployment/SINGLE_SIDED_LPS_PUBLIC_NETWORKS_RUNBOOK.md
@@ -0,0 +1,86 @@
+# Single-Sided LPs on Public Networks — Runbook (Aggregator and DEX Routing)
+
+**Purpose:** Deploy **cW* / HUB** single-sided PMM (or AMM) pools on each public chain so aggregators and DEX routing can use them.
+
+---
+
+## 1. What to deploy
+
+On each public chain:
+
+- **Pool type:** One pool per **cW*** token against the chain’s **hub stable** (USDC or USDT).
+- **Single-sided:** Liquidity is provided on the **cW*** side; the other side is filled by market/arbitrage (and optionally by a bot).
+- **Use case:** Aggregator and DEX routing (1inch, 0x, ParaSwap, swap–bridge–swap, etc.) so that cW* ↔ USDC/USDT is routable on each chain.
+
+---
+
+## 2. Per-chain config (pool-matrix)
+
+The source of truth is **cross-chain-pmm-lps/config/pool-matrix.json**:
+
+- **chains[chainId].hubStable:** USDC or USDT for that chain.
+- **chains[chainId].poolsFirst:** List of pools to deploy first (e.g. `cWUSDT/USDC`, `cWUSDC/USDC`, …).
+- **chains[chainId].poolsOptional:** Optional extra quote stables (e.g. `cWUSDT/USDT`, `cWUSDT/DAI`).
+
+---
+
+## 3. Prerequisites per chain
+
+1. **cW* tokens deployed** on that chain (addresses in `.env` or in `cross-chain-pmm-lps/config/deployment-status.json`).
+2. **Hub stable address** (USDC or USDT) on that chain (from chain list or explorer).
+3. **DEX/factory** on that chain:
+   - DODO-style: DVM or PMM factory.
+   - Uniswap V2: factory + router.
+   - Uniswap V3: factory + NonfungiblePositionManager (or equivalent).
+4. **RPC URL** and **deployer key** (or LP provider key) for that chain.
+
+---
+
+## 4. Steps per chain (checklist)
+
+For each chain (e.g. 1, 56, 137, 10, 100, 25, 42161, 8453, 43114, 42220, 1111):
+
+- [ ] 1. Set `CW*_<CHAIN>` and `*_RPC` (e.g. `CWUSDT_MAINNET`, `ETHEREUM_MAINNET_RPC`) in `.env`.
+- [ ] 2. Resolve hub stable address (e.g. USDC on Ethereum: `0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48`).
+- [ ] 3. Choose DEX: DODO PMM vs Uniswap V2 vs Uniswap V3 (per chain).
+- [ ] 4. For each pair in `poolsFirst` (e.g. cWUSDT/USDC):
+  - [ ] Create pool (factory.createPair or DVM.createDVM or V3 factory.createPool).
+  - [ ] Add single-sided liquidity on the cW* side (or both sides with a 1:1 target).
+- [ ] 5. Record pool address in `cross-chain-pmm-lps/config/deployment-status.json` under `chains[chainId].pmmPools` (each entry: `base`, `quote`, `poolAddress` or `base_token`, `quote_token`, `pool_address`).
+- [ ] 5a. **Update MCP allowlist for this chain:** Run `./scripts/generate-mcp-allowlist-from-deployment-status.sh <chain_id> -o ai-mcp-pmm-controller/config/allowlist-<chain_id>.json` (or merge into a multi-chain allowlist). So the dedicated MCP/AI can read and manage these pools. See [MCP_AI_POOL_MANAGEMENT_PLAN_UPGRADES.md](MCP_AI_POOL_MANAGEMENT_PLAN_UPGRADES.md).
+- [ ] 6. Register pool in token-aggregation API / indexer so quote and routing use it (set `CHAIN_*_DODO_PMM_INTEGRATION` or Uniswap factory env for that chain and run indexer).
+- [ ] 6a. **Uniswap (if used on this chain):** List Uniswap V2/V3 pools (from factory events or indexer) and add them to the same MCP/API visibility: set `CHAIN_*_UNISWAP_V2_FACTORY` / `CHAIN_*_UNISWAP_V3_FACTORY` and run indexer; add Uniswap pools to MCP allowlist with profile `uniswap_v2_pair` or `uniswap_v3_pool` when that profile is available. See [MCP_AI_POOL_MANAGEMENT_PLAN_UPGRADES.md](MCP_AI_POOL_MANAGEMENT_PLAN_UPGRADES.md) §2.3.
+- [ ] 7. (Optional) Enable bot for that chain (deviation watcher, rebalance). Bot can consume pool state from MCP or token-aggregation API; see plan upgrades § Bot–MCP–API integration.
+
+---
+
+## 5. Script stub: list pools to create
+
+From repo root, run:
+
+```bash
+./scripts/list-single-sided-pools-by-chain.sh
+```
+
+This script reads **cross-chain-pmm-lps/config/pool-matrix.json** and prints, per chain, the list of **cW* / HUB** pools to create (and optional pools). Use the output to drive deployment (manual or via a deploy script that calls the appropriate factory on each chain).
+
+---
+
+## 6. Deployment status and MCP allowlist source
+
+- **Config:** [cross-chain-pmm-lps/config/deployment-status.json](../../cross-chain-pmm-lps/config/deployment-status.json)
+- Fill for each chain:
+  - **cwTokens:** e.g. `{ "cWUSDT": "0x...", "cWUSDC": "0x..." }`
+  - **anchorAddresses:** e.g. `{ "USDC": "0x...", "USDT": "0x..." }`
+  - **pmmPools:** array of `{ "base", "quote", "poolAddress", "feeBps", "k", ... }` (or `base_token`, `quote_token`, `pool_address`)
+- **MCP allowlist generation:** `deployment-status.json` is the **source of truth** for generating the MCP allowlist per chain. Run `./scripts/generate-mcp-allowlist-from-deployment-status.sh <chain_id> [-o path]` to produce an allowlist fragment (pool_address, base_token, quote_token, profile) so the MCP/AI can read pool state on that chain.
+
+---
+
+## 7. References
+
+- [PMM_FULL_MESH_AND_PUBLIC_SINGLE_SIDED_PLAN.md](PMM_FULL_MESH_AND_PUBLIC_SINGLE_SIDED_PLAN.md) — Overall plan (Chain 138 mesh + public single-sided).
+- [MCP_AI_POOL_MANAGEMENT_PLAN_UPGRADES.md](MCP_AI_POOL_MANAGEMENT_PLAN_UPGRADES.md) — MCP/AI upgrades, allowlist sync, Uniswap, bot integration.
+- [cross-chain-pmm-lps/docs/02-pool-topology.md](../../cross-chain-pmm-lps/docs/02-pool-topology.md) — Pool topology.
+- [cross-chain-pmm-lps/docs/06-deployment-recipe.md](../../cross-chain-pmm-lps/docs/06-deployment-recipe.md) — Recipe and bot.
+- [PMM_DEX_ROUTING_STATUS.md](../11-references/PMM_DEX_ROUTING_STATUS.md) — Routing status.