chore: sync all changes to Gitea

- Config, docs, scripts, and backup manifests - Submodule refs unchanged (m = modified content in submodules) Made-with: Cursor
2026-03-02 11:37:34 -08:00
parent ed85135249
commit b3a8fe4496
883 changed files with 73580 additions and 4796 deletions
--- a/docs/03-deployment/ADD_LIQUIDITY_PMM_CHAIN138_RUNBOOK.md
+++ b/docs/03-deployment/ADD_LIQUIDITY_PMM_CHAIN138_RUNBOOK.md
@@ -0,0 +1,49 @@
+# Add Liquidity to PMM Pools (Chain 138) — Runbook
+
+**Purpose:** Add base/quote liquidity to the three DODO PMM pools on Chain 138 (cUSDT/cUSDC, cUSDT/USDT, cUSDC/USDC).
+
+**Prerequisites:**
+- Deployer has **cUSDT** and **cUSDC** (and optional official USDT/USDC) balance on Chain 138.
+- `smom-dbis-138/.env` has: `PRIVATE_KEY`, `RPC_URL_138`, `DODO_PMM_INTEGRATION_ADDRESS` (or `DODO_PMM_INTEGRATION`), pool addresses and amounts.
+
+---
+
+## 1. Set pool addresses and amounts in .env
+
+Add or set in `smom-dbis-138/.env`:
+
+```bash
+# Pool addresses (from PRE_DEPLOYMENT_CHECKLIST / create-all-pmm-pools-chain138.sh)
+POOL_CUSDTCUSDC=0x9fcB06Aa1FD5215DC0E91Fd098aeff4B62fEa5C8
+POOL_CUSDTUSDT=0xa3Ee6091696B28e5497b6F491fA1e99047250c59
+POOL_CUSDCUSDC=0x90bd9Bf18Daa26Af3e814ea224032d015db58Ea5
+
+# Amounts (6 decimals; e.g. 1000000 = 1 USDT/USDC)
+ADD_LIQUIDITY_BASE_AMOUNT=1000000
+ADD_LIQUIDITY_QUOTE_AMOUNT=1000000
+```
+
+Optional per-pool overrides: `ADD_LIQUIDITY_CUSDTCUSDC_BASE`, `ADD_LIQUIDITY_CUSDTCUSDC_QUOTE`, etc.
+
+---
+
+## 2. Run the add-liquidity script
+
+From repo root (or from `smom-dbis-138` with `RPC_URL_138` and `DODO_PMM_INTEGRATION` set):
+
+```bash
+cd smom-dbis-138
+source .env
+forge script script/dex/AddLiquidityPMMPoolsChain138.s.sol:AddLiquidityPMMPoolsChain138 \
+  --rpc-url "$RPC_URL_138" --broadcast --private-key "$PRIVATE_KEY" --with-gas-price 1000000000
+```
+
+Ensure the deployer has approved (or the script will approve) base/quote tokens to `DODOPMMIntegration` and has sufficient balance for the chosen amounts.
+
+---
+
+## 3. References
+
+- [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
@@ -2,10 +2,14 @@

 **Last Updated:** 2026-02-12

+**Full deployment order:** For the canonical sequence (prerequisites → core → PMM/pools → provider → optional → cW* → verification) and remaining recommendations, see [DEPLOYMENT_ORDER_OF_OPERATIONS.md](DEPLOYMENT_ORDER_OF_OPERATIONS.md).
+
+**Deployment safety:** Use **RPC_URL_138** (Core only, from `smom-dbis-138/.env`) for all deployments; never use Public RPC. All secrets from **`smom-dbis-138/.env`** only. Run a gas/cost estimate before deploy (e.g. `cd smom-dbis-138 && ./scripts/deployment/calculate-costs-consolidated.sh`). **Do not deploy when transactions are stuck** — clear tx pool (`./scripts/clear-all-transaction-pools.sh`), wait ~60s, then retry; use scripts that check nonce when available.
+
 ## 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".
- **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), [CONTRACT_INVENTORY_AND_VERIFICATION](../11-references/CONTRACT_INVENTORY_AND_VERIFICATION.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`.

 ## RPC Routing Summary
@@ -19,13 +23,16 @@ Chain 138 uses two standard env vars: **RPC_URL_138** (Core, admin/deploy) and *

 ## Prerequisites

-1. **Network access** to Chain 138 RPC (set `RPC_URL_138` in .env, e.g. http://192.168.11.211:8545 for Core)  
+1. **.env check (keys only, no secrets printed):** From repo root: `./scripts/deployment/preflight-chain138-deploy.sh` (RPC, dotenv, nonce). Or from smom-dbis-138: `./scripts/deployment/check-env-required.sh` — verifies `PRIVATE_KEY`, `RPC_URL`, `RPC_URL_138` and optional PMM/mainnet/CCIP vars. Use **`smom-dbis-138/.env`** only for deploy secrets.
+2. **Network access** to Chain 138 RPC (set `RPC_URL_138` in .env, e.g. http://192.168.11.211:8545 for Core)  
   - Run from a host on the same LAN as Proxmox, or via VPN  
   - WSL/remote dev environments may get "No route to host" if not on network

-2. **PRIVATE_KEY** in `smom-dbis-138/.env` (deployer wallet with gas; same wallet holds LINK for bridge fees)
+3. **PRIVATE_KEY** in `smom-dbis-138/.env` (deployer wallet with gas; same wallet holds LINK for bridge fees)

-3. **Foundry** (`forge`) installed
+4. **Foundry** (`forge`) installed
+
+5. **Test all contracts before deploy (Phase 0.8):** Run `./scripts/deployment/test-all-contracts-before-deploy.sh` from repo root. This runs `forge build` and `forge test` in smom-dbis-138. Use `--dry-run` to print commands only; `--alltra` to include alltra-lifi-settlement; `--no-match "Fork|Mainnet|Integration|e2e"` for unit tests only. See [DEPLOYMENT_ORDER_OF_OPERATIONS](DEPLOYMENT_ORDER_OF_OPERATIONS.md) § Phase 0.8.

 ### Deprecated bridge (R4)

@@ -90,7 +97,31 @@ forge script script/smart-accounts/DeploySmartAccountsKit.s.sol --rpc-url $RPC_U

 ## TransactionMirror (Chain 138)

-**Script:** `script/DeployTransactionMirror.s.sol`. If `forge script` fails with "Failed to decode constructor arguments", deploy via `forge create`:
+**Script:** `script/DeployTransactionMirror.s.sol`. **Deployed address:** Set in `smom-dbis-138/.env` as `TRANSACTION_MIRROR_ADDRESS` from the script output (e.g. past deploys: `0xE362aa10D3Af1A16880A799b78D18F923403B55a`, `0x4eeF36BBaf706C6da5859cF9B34E9934fEC3E006`).
+
+**Recommended:** Use the combined script; it **always checks nonce**, **validates RPC is active (chainId 138)**, uses **proper gas** (1 gwei min), and loads the **correct dotenv** (`smom-dbis-138/.env` + `config/ip-addresses.conf` for RPC fallbacks).
+
+**Required in `smom-dbis-138/.env`:** `PRIVATE_KEY`, `RPC_URL_138` (Core RPC, 192.168.11.211:8545). No Public fallback for deployments. Optional: `GAS_PRICE` or `GAS_PRICE_138` (default 1000000000). Before deploying: if Core was read-only, run `./scripts/maintenance/make-rpc-vmids-writable-via-ssh.sh` then `./scripts/maintenance/health-check-rpc-2101.sh`. See [RPC_2101_READONLY_FIX.md](RPC_2101_READONLY_FIX.md).
+
+**If you see "Known transaction" or "Replacement transaction underpriced":** Clear the tx pool then retry: `./scripts/clear-all-transaction-pools.sh` (or RPC-only; see script). Run from a host that can reach `RPC_URL_138` (same LAN/VPN):
+
+```bash
+./scripts/deployment/deploy-transaction-mirror-and-pmm-pool-after-txpool-clear.sh
+```
+
+This deploys TransactionMirror and creates the DODO cUSDT/cUSDC PMM pool, then runs on-chain verification. **Core RPC only** (no Public fallback). If Core is unreachable, fix read-only and health first (see RPC_2101_READONLY_FIX.md). Options: `--dry-run` (env, RPC, nonce only); `--force` (skip RPC check).
+
+**Skip stuck nonce manually:** Set `NEXT_NONCE` to the next nonce (e.g. `13370`) so the script uses `vm.setNonce` and deploys at a new address; then set `TRANSACTION_MIRROR_ADDRESS` in `.env` to the logged address. The combined script already sets `NEXT_NONCE` from pending nonce.
+
+Or run the two forge commands manually (ensure RPC is Chain 138 and nonce is correct):
+```bash
+cd smom-dbis-138 && source .env
+# Optional: export NEXT_NONCE=<pending nonce> if avoiding a stuck tx
+forge script script/DeployTransactionMirror.s.sol:DeployTransactionMirror --rpc-url "$RPC_URL_138" --broadcast --private-key "$PRIVATE_KEY" --with-gas-price 1000000000
+forge script script/dex/CreateCUSDTCUSDCPool.s.sol:CreateCUSDTCUSDCPool --rpc-url "$RPC_URL_138" --broadcast --private-key "$PRIVATE_KEY" --with-gas-price 1000000000
+```
+
+If `forge script` fails with "Failed to decode constructor arguments", deploy via `forge create`:

 ```bash
 cd smom-dbis-138
@@ -230,9 +261,9 @@ Deploy the [Stabilizer](../../smom-dbis-138/contracts/bridge/trustless/integrati

 ## Contract Verification (Blockscout)

-Use the **Forge Verification Proxy** for `forge verify-contract` (Blockscout expects `module`/`action` in query; Forge sends JSON only).
+Use the **Forge Verification Proxy** for `forge verify-contract` (Blockscout expects `module`/`action` in query; Forge sends JSON only). The verification script uses **canonical addresses** from `smom-dbis-138/.env` and `config/ip-addresses.conf` (ORACLE_PROXY, AGGREGATOR_ADDRESS, CCIP_SENDER, CCIPWETH9_BRIDGE_CHAIN138, etc.); run from a host on LAN that can reach Blockscout (192.168.11.140:4000).

-**Preferred: orchestrated script (starts proxy if needed, timeout 600s):**
+**Preferred: orchestrated script (starts proxy if needed, timeout 900s default):**
 ```bash
 source smom-dbis-138/.env 2>/dev/null
 ./scripts/verify/run-contract-verification-with-proxy.sh
--- a/docs/03-deployment/DEPLOYMENT_ORDER_OF_OPERATIONS.md
+++ b/docs/03-deployment/DEPLOYMENT_ORDER_OF_OPERATIONS.md
@@ -0,0 +1,194 @@
+# Full Deployment Order of Operations
+
+**Last Updated:** 2026-02-28  
+**Purpose:** Single canonical sequence for deploying and completing the system: prerequisites → Chain 138 core → PMM/pools → provider → optional → cW* → verification. Use this as the master order; other runbooks give per-step detail.
+
+**Related:** [RECOMMENDATIONS_AND_FIXES_BEFORE_DEPLOY.md](RECOMMENDATIONS_AND_FIXES_BEFORE_DEPLOY.md) (all recommendations & fixes before deploy) | [PRE_DEPLOYMENT_CHECKLIST.md](PRE_DEPLOYMENT_CHECKLIST.md) (PMM/pools focus) | [CONTRACT_DEPLOYMENT_RUNBOOK.md](CONTRACT_DEPLOYMENT_RUNBOOK.md) (per-script detail) | [RECOMMENDATIONS_OPERATOR_CHECKLIST.md](../00-meta/RECOMMENDATIONS_OPERATOR_CHECKLIST.md) (R1–R24)
+
+---
+
+## Deployment safety (required practices)
+
+Before any Chain 138 deployment, follow these four rules:
+
+| Rule | Requirement |
+|------|-------------|
+| **Correct RPC** | Use **only** `RPC_URL_138` from `smom-dbis-138/.env` for deployments. It must point to **Core RPC** (VMID 2101, `http://192.168.11.211:8545`). **Never** use `RPC_URL_138_PUBLIC` or Public RPC for deploying — Public is for bridge/monitoring/frontend only. See [RPC_ENDPOINTS_MASTER](../04-configuration/RPC_ENDPOINTS_MASTER.md). |
+| **Correct dotenv** | All deployment secrets (`PRIVATE_KEY`, `RPC_URL_138`, `GAS_PRICE_138`, contract addresses) come from **`smom-dbis-138/.env`** only. Do not source a different .env for deploy. Env check: `cd smom-dbis-138 && ./scripts/deployment/check-env-required.sh`. From repo root, pre-flight: `./scripts/deployment/preflight-chain138-deploy.sh`. |
+| **Gas API / cost estimate** | Before deploying, run a **gas/cost estimation** for accurate deployment costs. **Chain 138:** minimum gas is 1 gwei; use `cd smom-dbis-138 && ./scripts/deployment/calculate-costs-consolidated.sh` (or see [DEPLOYMENT_GAS_COSTS_REALTIME](../11-references/DEPLOYMENT_GAS_COSTS_REALTIME.md), [GAS_API_INTEGRATION_SUMMARY](../06-besu/GAS_API_INTEGRATION_SUMMARY.md)) to estimate total cost. For **other chains** (e.g. mainnet), use Etherscan/Infura Gas API where available. |
+| **Do not deploy when stuck** | Check deployer **nonce** (pending vs latest). If there are pending/stuck transactions, run `./scripts/clear-all-transaction-pools.sh` then wait **~60s** before deploying. Prefer scripts that **check nonce** (e.g. `./scripts/deployment/deploy-transaction-mirror-and-pmm-pool-after-txpool-clear.sh`). If you see "Replacement transaction underpriced" or "Known transaction", do **not** retry until the tx pool is cleared and nonce is consistent. |
+
+---
+
+## Overview
+
+| Phase | Scope | When |
+|-------|--------|------|
+| **0** | Prerequisites & gates | Before any deploy |
+| **1** | Chain 138 core (if not already deployed) | One-time or refresh |
+| **2** | TransactionMirror + PMM pools (Chain 138) | Required for PMM routing |
+| **3** | Liquidity + DODOPMMProvider | After pools exist |
+| **4** | Optional: EnhancedSwapRouter, trustless, CCIP other chains | When dependencies exist |
+| **5** | cW* edge pools (11 public chains) | When cW* tokens and infra exist |
+| **6** | Post-deploy verification & recommendations | After each phase and ongoing |
+
+---
+
+## Phase 0 — Prerequisites (do first)
+
+Execute in any order where no dependency; all must be satisfied before Phase 1–2.
+
+| # | Item | Action |
+|---|------|--------|
+| 0.1 | **RPC 2101 (Core) writable** | If read-only: `./scripts/maintenance/make-rpc-vmids-writable-via-ssh.sh` then `./scripts/maintenance/health-check-rpc-2101.sh`. See [RPC_2101_READONLY_FIX.md](RPC_2101_READONLY_FIX.md). |
+| 0.2 | **Deployer wallet funded (Chain 138)** | ≥ ~0.006 ETH (recommended 1–2 ETH). Check: `cd smom-dbis-138 && ./scripts/deployment/check-balances-gas-and-deploy.sh`. |
+| 0.3 | **Env configured** | `smom-dbis-138/.env` only: `PRIVATE_KEY`, `RPC_URL_138` (Core); for PMM: `DODO_PMM_INTEGRATION_ADDRESS=0x79cdbaFBaA0FdF9F55D26F360F54cddE5c743F7D`. Optional: `GAS_PRICE_138`, `GAS_PRICE`. Run: `cd smom-dbis-138 && ./scripts/deployment/check-env-required.sh`. Or from repo root: `./scripts/deployment/preflight-chain138-deploy.sh`. |
+| 0.4 | **Gas / cost estimate** | Run cost estimate before deploy: `cd smom-dbis-138 && ./scripts/deployment/calculate-costs-consolidated.sh` (or see [DEPLOYMENT_GAS_COSTS_REALTIME](../11-references/DEPLOYMENT_GAS_COSTS_REALTIME.md)). Chain 138 uses min 1 gwei; script gives estimated total cost. |
+| 0.5 | **POOL_MANAGER_ROLE** | Deployer must have POOL_MANAGER_ROLE on DODOPMMIntegration for pool creation and provider registration. |
+| 0.6 | **No stuck transactions** | If nonce has pending txs or "Replacement transaction underpriced": run `./scripts/clear-all-transaction-pools.sh` then wait ~60s. Use Core RPC only (no Public fallback). Prefer deploy scripts that check nonce (e.g. `deploy-transaction-mirror-and-pmm-pool-after-txpool-clear.sh`). |
+| 0.7 | **Foundry** | `forge` in PATH; `cd smom-dbis-138 && forge build` succeeds. |
+| 0.8 | **Test all contracts** | Run **before** any deploy: `./scripts/deployment/test-all-contracts-before-deploy.sh`. Runs `forge build` and `forge test` in smom-dbis-138 (includes **GRU c* integration tests**: `GRUCompliantTokensRegistryTest`); optionally alltra-lifi-settlement. Use `--dry-run` to print commands only. See [CONTRACT_DEPLOYMENT_RUNBOOK](CONTRACT_DEPLOYMENT_RUNBOOK.md) § Test before deploy. |
+
+---
+
+## Phase 1 — Chain 138 core (if not already deployed)
+
+If core contracts are already deployed (36/38 present per verification), skip to Phase 2. Otherwise follow this order.
+
+| # | Item | Script / command | Depends on |
+|---|------|------------------|------------|
+| 1.1 | **Phased core** | `01_DeployCore.s.sol` → set `UNIVERSAL_ASSET_REGISTRY`, `GOVERNANCE_CONTROLLER` in .env → `02_DeployBridges.s.sol` | Phase 0 |
+| 1.2 | **Or: unified deploy** | `./scripts/deployment/deploy-contracts-unified.sh --mode ordered` | Phase 0 |
+| 1.3 | **CCIP WETH9 bridge** | `GAS_PRICE=1000000000 ./scripts/deploy-and-configure-weth9-bridge-chain138.sh`; set `CCIPWETH9_BRIDGE_CHAIN138` | Phase 0 |
+| 1.4 | **Deterministic (CREATE2) core** | `forge script script/deploy/DeployDeterministicCore.s.sol --rpc-url $RPC_URL_138 --broadcast --private-key $PRIVATE_KEY --with-gas-price 1000000000` | Phase 0 |
+
+**Gas:** Always use `--with-gas-price 1000000000` (1 gwei) for Chain 138. See [CONTRACT_DEPLOYMENT_RUNBOOK.md](CONTRACT_DEPLOYMENT_RUNBOOK.md).
+
+---
+
+## Phase 2 — TransactionMirror and PMM pools (Chain 138)
+
+Required for PMM routing. Full steps: [PRE_DEPLOYMENT_CHECKLIST.md](PRE_DEPLOYMENT_CHECKLIST.md) §3.
+
+**Run Phase 2 (and optional register c* + verify) in one go:** `./scripts/deployment/run-all-next-steps-chain138.sh` — preflight → mirror+pool → register c* as GRU → verify. Use `--skip-mirror` for pool-only (set `TRANSACTION_MIRROR_ADDRESS` in .env first). See [NEXT_STEPS_INDEX](../00-meta/NEXT_STEPS_INDEX.md) §3.
+
+| # | Item | Command / script |
+|---|------|------------------|
+| 2.1 | **TransactionMirror** | `./scripts/deployment/deploy-transaction-mirror-and-pmm-pool-after-txpool-clear.sh` (deploys mirror + cUSDT/cUSDC pool), or run `DeployTransactionMirror.s.sol` only. Set `TRANSACTION_MIRROR_ADDRESS` in .env. If deploy fails with CreateCollision, see [TRANSACTION_MIRROR_CHAIN138_COLLISION_FIX.md](TRANSACTION_MIRROR_CHAIN138_COLLISION_FIX.md); use `--skip-mirror` for pool-only. |
+| 2.2 | **PMM pools (all three)** | Either: (a) after 2.1 run `CreateCUSDTUSDTPool.s.sol` and `CreateCUSDCUSDCPool.s.sol`, or (b) `./scripts/deployment/create-all-pmm-pools-chain138.sh` (all three). Use Core RPC only. |
+| 2.3 | **Record pool addresses** | Note each pool address for Phase 3 (DODOPMMProvider registration). |
+| 2.4 | **Register c* as GRU (ERC-2535 integration)** | Set c* and token addresses in .env: `./scripts/deployment/set-dotenv-c-tokens-and-register-gru.sh` (or `--no-register` to only update .env). Then run RegisterGRUCompliantTokens (script runs it unless `--no-register`). **If registration reverts (empty data):** the proxy implementation may be older — upgrade first: `cd smom-dbis-138 && forge script script/deploy/UpgradeUniversalAssetRegistry.s.sol --rpc-url $RPC_URL_138 --broadcast --private-key $PRIVATE_KEY --with-gas-price 1000000000` (requires UPGRADER_ROLE). Then grant REGISTRAR_ROLE if needed (see script comment) and re-run set-dotenv script. See [GRU_M00_DIAMOND_FACET_MAP](../04-configuration/GRU_M00_DIAMOND_FACET_MAP.md); [GRU_M00_DIAMOND_REVIEW_GAPS_AND_RECOMMENDATIONS](../04-configuration/GRU_M00_DIAMOND_REVIEW_GAPS_AND_RECOMMENDATIONS.md). |
+
+---
+
+## Phase 3 — Liquidity and DODOPMMProvider
+
+| # | Item | Action |
+|---|------|--------|
+| 3.1 | **Add liquidity (optional)** | Per pool: approve base/quote to DODOPMMIntegration, then `addLiquidity(pool, baseAmount, quoteAmount)`. See [DODO_PMM_INTEGRATION.md](../../smom-dbis-138/docs/integration/DODO_PMM_INTEGRATION.md). |
+| 3.2 | **Deploy DODOPMMProvider** | `forge script script/liquidity/DeployDODOPMMProvider.s.sol:DeployDODOPMMProvider --rpc-url $RPC_URL_138 --broadcast --private-key $PRIVATE_KEY --with-gas-price 1000000000`. Set `DODO_PMM_PROVIDER_ADDRESS` in .env. |
+| 3.3 | **Register pools** | For each pool (cUSDT/cUSDC, cUSDT/USDT, cUSDC/USDC): call `provider.registerPool(tokenIn, tokenOut, poolAddress)` (via cast or script). |
+| 3.4 | **Token-aggregation** | Set `CHAIN_138_DODO_PMM_INTEGRATION` where the token-aggregation service runs; ensure indexer runs so API exposes pools. |
+| 3.5 | **MCP allowlist (optional)** | Use `ai-mcp-pmm-controller/config/allowlist-138.json` (Chain 138 pools). Run with `ALLOWLIST_PATH=config/allowlist-138.json CHAIN=138`. See [README-allowlist-138.md](../../ai-mcp-pmm-controller/config/README-allowlist-138.md). |
+
+---
+
+## Phase 4 — Optional: EnhancedSwapRouter, trustless, CCIP other chains
+
+Only when dependencies exist (Uniswap/Balancer on 138, or mainnet/other-chain RPC and env).
+
+| # | Item | When / command |
+|---|------|----------------|
+| 4.1 | **EnhancedSwapRouter (Chain 138)** | When Uniswap V3 / Balancer pools exist on 138: deploy with chain-138–aware script (env quoter/poolId); configure post-deploy. See CONTRACT_DEPLOYMENT_RUNBOOK § EnhancedSwapRouter. |
+| 4.2 | **Trustless stack (Lockbox138 + Mainnet)** | When Mainnet RPC and keys available: deploy trustless bridge contracts; set INBOX_ETH, BOND_MANAGER, etc. See [OPTIONAL_DEPLOYMENTS_START_HERE.md](../07-ccip/OPTIONAL_DEPLOYMENTS_START_HERE.md) §2C. |
+| 4.3 | **CCIP other chains (Gnosis, Celo, Wemix)** | Deploy WETH bridges per chain; add destinations 138↔chain; fund LINK. See [CONFIG_READY_CHAINS_COMPLETION_RUNBOOK.md](../07-ccip/CONFIG_READY_CHAINS_COMPLETION_RUNBOOK.md). |
+| 4.4 | **LINK on Mainnet relay** | [RELAY_BRIDGE_ADD_LINK_SUPPORT_RUNBOOK.md](../07-ccip/RELAY_BRIDGE_ADD_LINK_SUPPORT_RUNBOOK.md). |
+
+---
+
+## Phase 5 — cW* edge pools (11 public chains)
+
+Design and pool matrix: [POOLS_AND_NETWORKS_FULL_DESIGN.md](../11-references/POOLS_AND_NETWORKS_FULL_DESIGN.md). Per chain: deploy cW* tokens (or bridge), then create 6 “poolsFirst” + optional pools per [pool-matrix.json](../../cross-chain-pmm-lps/config/pool-matrix.json) and [06-deployment-recipe.md](../../cross-chain-pmm-lps/docs/06-deployment-recipe.md).
+
+| # | Item | Action |
+|---|------|--------|
+| 5.1 | **Per-chain RPC and env** | Set `CHAIN_*_RPC_URL`, `CHAIN_*_DODO_PMM_INTEGRATION` (or pool source) for each of 1, 10, 25, 56, 100, 137, 42161, 42220, 43114, 8453, 1111 if indexing via token-aggregation. |
+| 5.2 | **Deploy and fund** | Per chain: deploy or bridge cW* tokens; create and fund PMM pools per pool-matrix; add to MCP allowlist per chain if using MCP. |
+
+---
+
+## Phase 6 — Post-deploy verification and recommendations
+
+After each deployment phase and periodically.
+
+| # | Item | Command / doc |
+|---|------|----------------|
+| 6.1 | **On-chain verification (Chain 138)** | `./scripts/verify/check-contracts-on-chain-138.sh [RPC_URL]`. Target 38/38 when TransactionMirror and all three PMM pools exist. |
+| 6.2 | **Blockscout verification** | When Blockscout reachable: `./scripts/verify/run-contract-verification-with-proxy.sh`. See [BLOCKSCOUT_VERIFICATION_GUIDE.md](../08-monitoring/BLOCKSCOUT_VERIFICATION_GUIDE.md). |
+| 6.3 | **Update address docs** | Update [CONTRACT_ADDRESSES_REFERENCE.md](../11-references/CONTRACT_ADDRESSES_REFERENCE.md), [LIQUIDITY_POOLS_MASTER_MAP.md](../11-references/LIQUIDITY_POOLS_MASTER_MAP.md) with new pool and provider addresses. |
+| 6.4 | **Recommendations (R1–R24)** | Follow [RECOMMENDATIONS_OPERATOR_CHECKLIST.md](../00-meta/RECOMMENDATIONS_OPERATOR_CHECKLIST.md): verify on Blockscout, keep address refs updated, use correct RPC/gas, manage nonce, runbooks in sync, monitoring, testing, token mapping. |
+| 6.5 | **Full recommendations list** | Optional and ongoing: [ALL_RECOMMENDATIONS_AND_IMPROVEMENTS_LIST.md](../00-meta/ALL_RECOMMENDATIONS_AND_IMPROVEMENTS_LIST.md) (~139 items, 20 sections); [OPERATOR_READY_CHECKLIST.md](../00-meta/OPERATOR_READY_CHECKLIST.md) for copy-paste commands. |
+
+---
+
+## Remaining recommendations and suggestions to complete
+
+Beyond the deployment order above, these are the main recommendation buckets. Complete as part of operations or when rolling out new features.
+
+### Operator checklist (R1–R24)
+
+- **Verification & source of truth (R1–R3):** Verify every contract on Blockscout; keep CONTRACT_ADDRESSES_REFERENCE and inventory updated; run check-contracts-on-chain-138.sh.
+- **Security and secrets (R4–R7):** Use only canonical CCIPWETH9Bridge; never commit .env/keys; restrict deployer and RPC access.
+- **Deployment (R8–R11):** Set RPC_URL_138 (Core); use gas 1 gwei on 138; phased core order (01 → 02); manage nonce if tx stuck.
+- **Docs and runbooks (R12–R13):** Keep runbooks in sync with scripts and Blockscout URL; document addresses per chain.
+- **Automation and CI (R14–R16):** Run verification after deploy in CI; consider env/config per environment.
+- **Monitoring and ops (R17–R18):** Monitor bridge/oracle events; ensure Blockscout and /api are up.
+- **Testing and quality (R19–R20):** Run forge test before deploy; NatSpec on public functions.
+- **Config and DNS (R21–R22):** The Order/NPMplus proxy when deployed; document blocks #2–#6 if decided.
+- **Quick wins (R23):** Progress indicators, --dry-run, config validation.
+- **Token mapping (R24):** Keep config/token-mapping.json as single source of truth.
+
+**Doc:** [RECOMMENDATIONS_OPERATOR_CHECKLIST.md](../00-meta/RECOMMENDATIONS_OPERATOR_CHECKLIST.md).
+
+### Full recommendations list (~139 items)
+
+- **Proxmox / validated set:** Secure .env and validator keys, SSH key auth, firewall, VLANs, metrics, health, backup, runbooks (items 1–11 high; 12–20 medium; 21–35 low/quick wins).
+- **Code quality & scripts:** Shebang, set -euo pipefail, script headers, shellcheck, consolidation, lib, perf (36–43).
+- **Documentation:** Quick refs, decision trees, config templates, consolidation, API docs (44–47, 68–74).
+- **Security & config:** Audit, validation, scanning, RBAC, config validation, templates, tests, CI (48–57).
+- **Monitoring & DX:** Logging, metrics, health, DevContainer, backup review (58–67).
+- **Placeholders & codebase:** Canonical addresses env-only, AlltraAdapter fee, smart accounts, quote Fabric chainId, .bak deprecation (87–91).
+- **Other:** GRU M00 Diamond spine, CMC/CoinGecko submission, optional naming, Vault System Master Plan.
+
+**Doc:** [ALL_RECOMMENDATIONS_AND_IMPROVEMENTS_LIST.md](../00-meta/ALL_RECOMMENDATIONS_AND_IMPROVEMENTS_LIST.md). **Execution plan:** [COMPLETE_REQUIRED_OPTIONAL_RECOMMENDED_INDEX.md](../00-meta/COMPLETE_REQUIRED_OPTIONAL_RECOMMENDED_INDEX.md).
+
+### Copy-paste operator commands
+
+For a single page of exact commands (CCIP bridges, LINK relay, Blockscout verify, 502 fix, DODO PMM, trustless, full operator tasks): [OPERATOR_READY_CHECKLIST.md](../00-meta/OPERATOR_READY_CHECKLIST.md).
+
+---
+
+## Quick reference — deployment order summary
+
+1. **Prerequisites:** RPC writable (Core only), deployer funded, **smom-dbis-138/.env** (no other dotenv), gas/cost estimate run, POOL_MANAGER_ROLE, **no stuck txs** (clear pool if needed), forge build.
+2. **Chain 138 core:** 01_DeployCore → set env → 02_DeployBridges (or unified script); WETH9 bridge; deterministic if needed.
+3. **PMM:** TransactionMirror + create all three PMM pools (cUSDT/cUSDC, cUSDT/USDT, cUSDC/USDC).
+4. **Provider:** Add liquidity (optional) → deploy DODOPMMProvider → register pools → token-aggregation env → MCP allowlist (optional).
+5. **Optional:** EnhancedSwapRouter (when Uniswap/Balancer on 138), trustless stack, CCIP other chains, LINK relay.
+6. **cW*:** Per chain: deploy/bridge cW* tokens, create and fund pools per pool-matrix.
+7. **Verify & recommendations:** check-contracts-on-chain-138.sh, Blockscout verify, update address docs, R1–R24, full recommendations list.
+
+---
+
+## References
+
+| Doc | Purpose |
+|-----|---------|
+| [PRE_DEPLOYMENT_CHECKLIST.md](PRE_DEPLOYMENT_CHECKLIST.md) | PMM/pools/prerequisites and scripts |
+| [CONTRACT_DEPLOYMENT_RUNBOOK.md](CONTRACT_DEPLOYMENT_RUNBOOK.md) | Per-script detail, gas, RPC, TransactionMirror |
+| [REQUIRED_FIXES_AND_DEPLOYMENTS_STATUS.md](REQUIRED_FIXES_AND_DEPLOYMENTS_STATUS.md) | RPC fix, missing contracts, completion steps |
+| [RECOMMENDATIONS_OPERATOR_CHECKLIST.md](../00-meta/RECOMMENDATIONS_OPERATOR_CHECKLIST.md) | R1–R24 |
+| [ALL_RECOMMENDATIONS_AND_IMPROVEMENTS_LIST.md](../00-meta/ALL_RECOMMENDATIONS_AND_IMPROVEMENTS_LIST.md) | ~139 items |
+| [OPERATOR_READY_CHECKLIST.md](../00-meta/OPERATOR_READY_CHECKLIST.md) | Copy-paste commands |
+| [COMPLETE_REQUIRED_OPTIONAL_RECOMMENDED_INDEX.md](../00-meta/COMPLETE_REQUIRED_OPTIONAL_RECOMMENDED_INDEX.md) | Full plan execution order |
+| [FULL_PARALLEL_EXECUTION_ORDER.md](../00-meta/FULL_PARALLEL_EXECUTION_ORDER.md) | Waves for parallel execution |
--- a/docs/03-deployment/NEXT_STEPS_PMM_FULL_PARITY_AND_ALL_POOLS.md
+++ b/docs/03-deployment/NEXT_STEPS_PMM_FULL_PARITY_AND_ALL_POOLS.md
@@ -0,0 +1,118 @@
+# Next Steps: Full Parity and Deploy All PMM Pools
+
+**Last Updated:** 2026-02-28  
+**Purpose:** Ordered list of steps to achieve full PMM parity and deploy all DODO PMM pools (Chain 138 first, then multichain).
+
+---
+
+## Current state
+
+| Scope | DODOPMMIntegration | Pools (cUSDT/cUSDC, cUSDT/USDT, cUSDC/USDC) | DODOPMMProvider | Liquidity |
+|-------|--------------------|-----------------------------------------------|-----------------|-----------|
+| **Chain 138** | Deployed (`0x79cdbaFBaA0FdF9F55D26F360F54cddE5c743F7D`) | Created (addresses in .env / LIQUIDITY_POOLS_MASTER_MAP) | Deployed (`0x8EF6657D2a86c569F6ffc337EE6b4260Bd2e59d0`) | **Zero** (pools empty) |
+| **L2s (BSC, Polygon, Base, etc.)** | Script exists (`deploy-pmm-all-l2s.sh`) | Not created | Not deployed | N/A |
+| **cW* mesh (11 chains)** | Design only | 111 pools in design | Not deployed | N/A |
+
+**Full parallel runner (Phase 1 + Phase 2):** From `smom-dbis-138/` run `./scripts/deployment/run-pmm-full-parity-all-phases.sh`. Phase 1 creates the three PMM pools in parallel, registers them with DODOPMMProvider, then adds liquidity if `ADD_LIQUIDITY_BASE_AMOUNT` and `ADD_LIQUIDITY_QUOTE_AMOUNT` are set. Phase 2 runs each L2 (BSC, Polygon, Base, etc.) in parallel: deploy cUSDT/cUSDC then DODOPMMIntegration per chain. Use `RUN_PHASE1=0` or `RUN_PHASE2=0` to skip a phase; `DRY_RUN=1` to print only.
+
+**References:** [PMM_DEX_ROUTING_STATUS.md](../11-references/PMM_DEX_ROUTING_STATUS.md), [POOLS_AND_NETWORKS_FULL_DESIGN.md](../11-references/POOLS_AND_NETWORKS_FULL_DESIGN.md), [PRE_DEPLOYMENT_CHECKLIST.md](PRE_DEPLOYMENT_CHECKLIST.md), [LIQUIDITY_POOLS_MASTER_MAP.md](../11-references/LIQUIDITY_POOLS_MASTER_MAP.md).
+
+---
+
+## Phase 1: Chain 138 — Verify, add liquidity, and go live
+
+1. **Confirm RPC and deployer**
+   - Use **Core RPC** only: `RPC_URL_138` (e.g. `http://192.168.11.211:8545`). See [REQUIRED_FIXES_AND_DEPLOYMENTS_STATUS.md](REQUIRED_FIXES_AND_DEPLOYMENTS_STATUS.md).
+   - If Core was read-only: `./scripts/maintenance/make-rpc-vmids-writable-via-ssh.sh` then `./scripts/maintenance/health-check-rpc-2101.sh`.
+   - Ensure deployer has gas and `POOL_MANAGER_ROLE` on DODOPMMIntegration.
+
+2. **Verify or create the three PMM pools**
+   - Pools (from PRE_DEPLOYMENT_CHECKLIST / .env):  
+     - cUSDT/cUSDC: `0x9fcB06Aa1FD5215DC0E91Fd098aeff4B62fEa5C8`  
+     - cUSDT/USDT: `0xa3Ee6091696B28e5497b6F491fA1e99047250c59`  
+     - cUSDC/USDC: `0x90bd9Bf18Daa26Af3e814ea224032d015db58Ea5`
+   - If any pool is missing on-chain, create it:
+     - `forge script script/dex/CreateCUSDTCUSDCPool.s.sol:CreateCUSDTCUSDCPool --rpc-url "$RPC_URL_138" --broadcast --private-key "$PRIVATE_KEY"`
+     - `forge script script/dex/CreateCUSDTUSDTPool.s.sol:CreateCUSDTUSDTPool --rpc-url "$RPC_URL_138" --broadcast --private-key "$PRIVATE_KEY"`
+     - `forge script script/dex/CreateCUSDCUSDCPool.s.sol:CreateCUSDCUSDCPool --rpc-url "$RPC_URL_138" --broadcast --private-key "$PRIVATE_KEY"`
+   - Or use `./scripts/setup-dodo-pools.sh` (creates cUSDT/USDT and cUSDC/USDC; ensure OFFICIAL_USDT_ADDRESS and OFFICIAL_USDC_ADDRESS are set in .env for Chain 138).
+
+3. **Register pools with DODOPMMProvider** (if not already)
+   - Set in .env: `POOL_CUSDTCUSDC`, `POOL_CUSDTUSDT`, `POOL_CUSDCUSDC`.
+   - Run: `forge script script/liquidity/RegisterDODOPools.s.sol:RegisterDODOPools --rpc-url "$RPC_URL_138" --broadcast --private-key "$PRIVATE_KEY"`.
+
+4. **Add liquidity to all three pools**
+   - Approve base/quote tokens to `DODOPMMIntegration` (`0x79cdbaFBaA0FdF9F55D26F360F54cddE5c743F7D`).
+   - Call `DODOPMMIntegration.addLiquidity(pool, baseAmount, quoteAmount)` for each pool. See [DODO_PMM_INTEGRATION.md](../../smom-dbis-138/docs/integration/DODO_PMM_INTEGRATION.md).
+   - **Forge script:** `forge script script/dex/AddLiquidityPMMPoolsChain138.s.sol:AddLiquidityPMMPoolsChain138 --rpc-url "$RPC_URL_138" --broadcast --private-key "$PRIVATE_KEY"` with env `ADD_LIQUIDITY_BASE_AMOUNT` and `ADD_LIQUIDITY_QUOTE_AMOUNT` (e.g. `1000000e6`). Or use **full-parity runner:** `./scripts/deployment/run-pmm-full-parity-all-phases.sh` (Phase 1 creates pools in parallel, registers, then adds liquidity when amounts are set).
+
+5. **Optional: Deploy EnhancedSwapRouter (Chain 138)**
+   - Only after Uniswap/Balancer (or other DEX) pools exist on 138; configure quoter and pool IDs. See [PMM_DEX_ROUTING_STATUS.md](../11-references/PMM_DEX_ROUTING_STATUS.md) §5.
+
+6. **Update docs**
+   - Set [PMM_DEX_ROUTING_STATUS.md](../11-references/PMM_DEX_ROUTING_STATUS.md) to “pools created” and “liquidity added” when done.
+   - Re-run `./scripts/verify/check-contracts-on-chain-138.sh` and fix any missing addresses (e.g. TransactionMirror, pool addresses in .env).
+
+---
+
+## Phase 2: Multichain — Deploy DODOPMMIntegration and pools on L2s
+
+7. **Deploy cUSDT and cUSDC on each target chain** (if not already)
+   - Chains: BSC (56), Polygon (137), Base (8453), Optimism (10), Arbitrum (42161), Avalanche (43114), Cronos (25), Gnosis (100). See [CUSDT_CUSDC_MULTICHAIN_LIQUIDITY_RUNBOOK.md](../../smom-dbis-138/docs/deployment/CUSDT_CUSDC_MULTICHAIN_LIQUIDITY_RUNBOOK.md).
+   - From `smom-dbis-138/`: `./scripts/deployment/deploy-cusdt-cusdc-all-chains.sh` or run `DeployCompliantUSDT.s.sol` and `DeployCompliantUSDC.s.sol` per chain with that chain’s RPC and chain ID.
+   - Record addresses in .env (e.g. `CUSDT_ADDRESS_137`, `CUSDC_ADDRESS_137` for Polygon).
+
+8. **Deploy DODOPMMIntegration on each L2**
+   - From `smom-dbis-138/`: `./scripts/deployment/deploy-pmm-all-l2s.sh` (optionally with `--chain bsc polygon base` or set `DEPLOY_PMM_L2S_FILTER` in .env).
+   - Requires per-chain: `*_DODO_VENDING_MACHINE_ADDRESS` (or `DODO_VENDING_MACHINE_ADDRESS`), `*_OFFICIAL_USDT_ADDRESS`, `*_OFFICIAL_USDC_ADDRESS`; optional per-chain compliant addresses.
+   - Save each `DODOPMM_INTEGRATION_<CHAIN>` (or equivalent) in .env.
+
+9. **Create the three PMM pool types on each L2**
+   - For each chain where DODOPMMIntegration is deployed: call `createCUSDTCUSDCPool`, `createCUSDTUSDTPool`, `createCUSDCUSDCPool` (or equivalent) via Forge script parameterized by that chain’s RPC and integration address.
+   - No single “create-all-pools-all-chains” script today; either add one or loop over chains and run the same Create* pool scripts with chain-specific env.
+
+10. **Deploy DODOPMMProvider (and register pools) on each L2**
+    - Deploy provider per chain (e.g. `DeployDODOPMMProvider.s.sol` with that chain’s RPC), then run RegisterDODOPools with that chain’s pool addresses.
+
+11. **Add liquidity on each L2**
+    - Same as Step 4, per chain: approve tokens to the integration, then `addLiquidity` for each pool.
+
+---
+
+## Phase 3: Chain 138 — Remaining pools (blocked until tokens exist)
+
+12. **XAU and cEURT pools (blocked until tokens exist)**
+    - Deploy or obtain **XAU** and **cEURT** on Chain 138.
+    - Create public PMM pools: cUSDT/XAU, cUSDC/XAU, cEURT/XAU via `createPool(baseToken, quoteToken, ...)` on DODOPMMIntegration.
+    - Create private stabilization pools (PrivatePoolRegistry): cUSDT↔XAU, cUSDC↔XAU, cEURT↔XAU. See [POOLS_AND_NETWORKS_FULL_DESIGN.md](../11-references/POOLS_AND_NETWORKS_FULL_DESIGN.md) and [LIQUIDITY_POOLS_MASTER_MAP.md](../11-references/LIQUIDITY_POOLS_MASTER_MAP.md).
+
+13. **Bridge LP (optional)**
+    - Deploy full trustless stack including **LiquidityPoolETH** and fund it when swap–bridge–swap is required. See [DEX_AND_CROSS_CHAIN_CONTRACTS_NEEDED.md](../11-references/DEX_AND_CROSS_CHAIN_CONTRACTS_NEEDED.md).
+
+---
+
+## Phase 4: Cross-chain cW* PMM mesh (design / recipe only; not deployed)
+
+14. **cW* edge pools on 11 public chains**
+    - 111 pools (66 first + 45 optional) across Ethereum, BSC, Polygon, Base, Optimism, Arbitrum, Avalanche, Cronos, Gnosis, Celo, Wemix. See [POOLS_AND_NETWORKS_FULL_DESIGN.md](../11-references/POOLS_AND_NETWORKS_FULL_DESIGN.md) and [cross-chain-pmm-lps/docs/06-deployment-recipe.md](../../cross-chain-pmm-lps/docs/06-deployment-recipe.md).
+    - Prerequisites: cW* tokens and infrastructure on each chain; then deploy and fund per deployment recipe. Not in scope for “all PMM pools” parity until cW* is deployed.
+
+---
+
+## Summary checklist (full parity = Phase 1 + Phase 2)
+
+| # | Step | Script / command |
+|---|------|------------------|
+| 1 | RPC + deployer ready (138) | `health-check-rpc-2101.sh`, `check-balances-gas-and-deploy.sh` |
+| 2 | Verify or create 3 pools (138) | `CreateCUSDTCUSDCPool.s.sol`, `CreateCUSDTUSDTPool.s.sol`, `CreateCUSDCUSDCPool.s.sol` or `setup-dodo-pools.sh` |
+| 3 | Register pools with DODOPMMProvider (138) | `RegisterDODOPools.s.sol` |
+| 4 | Add liquidity to 3 pools (138) | `addLiquidity(pool, baseAmount, quoteAmount)` via cast or Forge script |
+| 5 | Optional: EnhancedSwapRouter (138) | When DEX pools exist on 138 |
+| 6 | Update PMM/routing docs | PMM_DEX_ROUTING_STATUS, CONTRACT_ADDRESSES_REFERENCE |
+| 7 | Deploy cUSDT/cUSDC on L2s | `deploy-cusdt-cusdc-all-chains.sh` or per-chain Forge scripts |
+| 8 | Deploy DODOPMMIntegration on L2s | `deploy-pmm-all-l2s.sh` |
+| 9 | Create 3 pool types on each L2 | Per-chain Forge Create* pool scripts |
+| 10 | Deploy DODOPMMProvider + register (each L2) | `DeployDODOPMMProvider.s.sol`, `RegisterDODOPools.s.sol` per chain |
+| 11 | Add liquidity on each L2 | Same as Step 4, per chain |
+
+**Full parity** for “all PMM pools” in the current design means: **Chain 138** — three pools created, registered, and **funded**; **each target L2** — integration deployed, three pools created, provider deployed and registered, and pools funded. Phase 3 (XAU/cEURT) and Phase 4 (cW* mesh) extend beyond this baseline.
--- a/docs/03-deployment/PRE_DEPLOYMENT_CHECKLIST.md
+++ b/docs/03-deployment/PRE_DEPLOYMENT_CHECKLIST.md
@@ -0,0 +1,175 @@
+# Pre-Deployment Checklist — DODO PMM, Pools, Provider, Router & APIs
+
+**Last Updated:** 2026-02-28  
+**Purpose:** Single source of truth for component status and ordered steps required before deployment (Chain 138).
+
+**See also:** [DEPLOYMENT_ORDER_OF_OPERATIONS.md](DEPLOYMENT_ORDER_OF_OPERATIONS.md) — full deployment order (Phase 0–6) and remaining recommendations.
+
+### Deployment safety (required)
+
+- **Correct RPC:** Use only **Core RPC** (`RPC_URL_138` = VMID 2101, e.g. `http://192.168.11.211:8545`). Never use Public RPC for deployments. Set in `smom-dbis-138/.env`.
+- **Correct dotenv:** All secrets from **`smom-dbis-138/.env`** only. Check: `cd smom-dbis-138 && ./scripts/deployment/check-env-required.sh`. Pre-flight from repo root: `./scripts/deployment/preflight-chain138-deploy.sh`.
+- **Gas / cost estimate:** Run `cd smom-dbis-138 && ./scripts/deployment/calculate-costs-consolidated.sh` (or see [DEPLOYMENT_GAS_COSTS_REALTIME](../11-references/DEPLOYMENT_GAS_COSTS_REALTIME.md)) before deploying for accurate cost estimates.
+- **Do not deploy when stuck:** If nonce has pending txs or you see "Replacement transaction underpriced", run `./scripts/clear-all-transaction-pools.sh` then wait ~60s before deploying. Prefer scripts that check nonce (e.g. `deploy-transaction-mirror-and-pmm-pool-after-txpool-clear.sh`).
+
+---
+
+## 1. Component status (current state)
+
+| Component | Status | Address / Notes |
+|-----------|--------|-----------------|
+| **DODOPMMIntegration** | ✅ Deployed | Chain 138: `0x79cdbaFBaA0FdF9F55D26F360F54cddE5c743F7D` (Mock DVM). |
+| **PMM pools (cUSDT/cUSDC, cUSDT/USDT, cUSDC/USDC)** | ✅ Created | cUSDT/cUSDC: `0x9fcB06Aa1FD5215DC0E91Fd098aeff4B62fEa5C8`; cUSDT/USDT: `0xa3Ee6091696B28e5497b6F491fA1e99047250c59`; cUSDC/USDC: `0x90bd9Bf18Daa26Af3e814ea224032d015db58Ea5`. |
+| **DODOPMMProvider** | ✅ Deployed | `0x8EF6657D2a86c569F6ffc337EE6b4260Bd2e59d0`; all three pools registered via `script/liquidity/RegisterDODOPools.s.sol`. |
+| **EnhancedSwapRouter** | ❌ Not deployed | Mainnet-only script today; for Chain 138 deploy when Uniswap/Balancer pools exist; set quoter/poolId. |
+| **Token-aggregation API** | ✅ Implemented, runnable | Single-hop quotes; can index DODO once pools exist (set `CHAIN_138_DODO_PMM_INTEGRATION`). |
+| **Bridge quote (swap+bridge+swap)** | ✅ Implemented | `POST /api/bridge/quote`; on-chain coordinator optional. |
+| **Cross-chain cW* mesh** | Design/tooling only | Edge pools and bots not deployed. |
+
+---
+
+## 2. Prerequisites before running deployment
+
+- [ ] **RPC 2101 (Core) writable**  
+  If Core was read-only: run  
+  `./scripts/maintenance/make-rpc-vmids-writable-via-ssh.sh` then  
+  `./scripts/maintenance/health-check-rpc-2101.sh`.  
+  See [RPC_2101_READONLY_FIX.md](RPC_2101_READONLY_FIX.md).
+
+- [ ] **Deployer wallet funded (Chain 138)**  
+  At least ~0.006 ETH (5M gas × 1 gwei + buffer). Recommended 1–2 ETH.  
+  Check: `./scripts/deployment/check-balances-gas-and-deploy.sh` (from `smom-dbis-138`).
+
+- [ ] **Env set in `smom-dbis-138/.env` only**  
+  Required: `PRIVATE_KEY`, `RPC_URL_138` (must be Core RPC, not Public).  
+  For PMM: `DODO_PMM_INTEGRATION_ADDRESS=0x79cdbaFBaA0FdF9F55D26F360F54cddE5c743F7D`.  
+  Optional: `GAS_PRICE_138` or `GAS_PRICE` (default 1 gwei).  
+  After TransactionMirror deploy: set `TRANSACTION_MIRROR_ADDRESS` from script output.  
+  Verify: `cd smom-dbis-138 && ./scripts/deployment/check-env-required.sh`.
+
+- [ ] **Gas / cost estimate run**  
+  Before deploying: `cd smom-dbis-138 && ./scripts/deployment/calculate-costs-consolidated.sh` for estimated deployment cost (Chain 138 min gas 1 gwei).
+
+- [ ] **Deployer has POOL_MANAGER_ROLE on DODOPMMIntegration**  
+  Pool creation and (if used) DODOPMMProvider registration require this role.
+
+- [ ] **No stuck transactions**  
+  Do not deploy if there are pending/stuck txs. If you see "Replacement transaction underpriced" or stuck nonce: run `./scripts/clear-all-transaction-pools.sh` then wait ~60s before re-running deploy. Use scripts that check nonce when available.
+
+---
+
+## 3. Steps to complete before deployment (in order)
+
+### Step 1: Deploy TransactionMirror (if not already deployed)
+
+```bash
+cd smom-dbis-138
+export RPC_URL_138="${RPC_URL_138:-http://192.168.11.211:8545}"
+forge script script/DeployTransactionMirror.s.sol:DeployTransactionMirror \
+  --rpc-url "$RPC_URL_138" --broadcast --private-key "$PRIVATE_KEY" --with-gas-price 1000000000
+```
+
+- Save the logged TransactionMirror address to `smom-dbis-138/.env` as `TRANSACTION_MIRROR_ADDRESS`.
+
+### Step 2: Create PMM pools (cUSDT/cUSDC, cUSDT/USDT, cUSDC/USDC)
+
+Use **Core RPC only** (no Public fallback). Either use the combined script (Step 2a) or run each pool script (Step 2b).
+
+**2a) Combined (TransactionMirror + cUSDT/cUSDC pool only):**
+
+```bash
+./scripts/deployment/deploy-transaction-mirror-and-pmm-pool-after-txpool-clear.sh
+```
+
+This deploys TransactionMirror then creates **only** the cUSDT/cUSDC pool. For the other two pools use 2b.
+
+**2b) Create each pool manually** (e.g. after 2a, or if mirror already deployed):
+
+```bash
+cd smom-dbis-138
+export DODO_PMM_INTEGRATION="${DODO_PMM_INTEGRATION_ADDRESS:-0x79cdbaFBaA0FdF9F55D26F360F54cddE5c743F7D}"
+export RPC_URL_138="${RPC_URL_138:-http://192.168.11.211:8545}"
+export GAS_PRICE="${GAS_PRICE_138:-${GAS_PRICE:-1000000000}}"
+
+# cUSDT/cUSDC
+forge script script/dex/CreateCUSDTCUSDCPool.s.sol:CreateCUSDTCUSDCPool \
+  --rpc-url "$RPC_URL_138" --broadcast --private-key "$PRIVATE_KEY" --with-gas-price "$GAS_PRICE"
+
+# cUSDT/USDT
+forge script script/dex/CreateCUSDTUSDTPool.s.sol:CreateCUSDTUSDTPool \
+  --rpc-url "$RPC_URL_138" --broadcast --private-key "$PRIVATE_KEY" --with-gas-price "$GAS_PRICE"
+
+# cUSDC/USDC
+forge script script/dex/CreateCUSDCUSDCPool.s.sol:CreateCUSDCUSDCPool \
+  --rpc-url "$RPC_URL_138" --broadcast --private-key "$PRIVATE_KEY" --with-gas-price "$GAS_PRICE"
+```
+
+If you see “Replacement transaction underpriced”, wait for the pending tx to be mined or clear the tx pool, then retry (optionally with higher gas). After each creation, note the pool address for Step 4.
+
+### Step 3: Add liquidity to pools (optional but recommended)
+
+Use `DODOPMMIntegration.addLiquidity(pool, baseAmount, quoteAmount)` for each pool. Approve base/quote tokens to the integration contract first. See [DODO_PMM_INTEGRATION.md](../../smom-dbis-138/docs/integration/DODO_PMM_INTEGRATION.md).
+
+### Step 4: Deploy DODOPMMProvider and register pools
+
+```bash
+cd smom-dbis-138
+forge script script/liquidity/DeployDODOPMMProvider.s.sol:DeployDODOPMMProvider \
+  --rpc-url "$RPC_URL_138" --broadcast --private-key "$PRIVATE_KEY" --with-gas-price "$GAS_PRICE"
+```
+
+Save the logged address as `DODO_PMM_PROVIDER_ADDRESS` in `.env`. Then, for each pool (cUSDT/cUSDC, cUSDT/USDT, cUSDC/USDC), call:
+
+```solidity
+provider.registerPool(tokenIn, tokenOut, poolAddress);
+```
+
+(e.g. via `cast send` or a small script) so that `getQuote` / `executeSwap` work for those pairs.
+
+### Step 5: EnhancedSwapRouter (optional, when Uniswap/Balancer exist on 138)
+
+Current deploy script is mainnet-only (`block.chainid == 1`). For Chain 138:
+
+- When Uniswap V3 / Balancer pools exist on 138, add or use a Chain-138–aware deploy script (env-based quoter/poolId).
+- Run with `--rpc-url $RPC_URL_138` and configure quoter and Balancer poolId after deploy.  
+  See [CONTRACT_DEPLOYMENT_RUNBOOK.md](CONTRACT_DEPLOYMENT_RUNBOOK.md) § EnhancedSwapRouter.
+
+### Step 6: Token-aggregation API (DODO indexing)
+
+- Ensure `CHAIN_138_DODO_PMM_INTEGRATION=0x79cdbaFBaA0FdF9F55D26F360F54cddE5c743F7D` (or equivalent) is set where the token-aggregation service runs. Optional: `CHAIN_138_DODO_POOL_MANAGER`, `CHAIN_138_DODO_VENDING_MACHINE` (see token-aggregation `.env.example` and [dex-factories.ts](../../smom-dbis-138/services/token-aggregation/src/config/dex-factories.ts)).
+- Once pools exist, the service can index DODO pools from DODOPMMIntegration and expose single-hop quotes.
+
+### Step 7: On-chain verification
+
+After any new deployment:
+
+```bash
+./scripts/verify/check-contracts-on-chain-138.sh [RPC_URL]
+```
+
+Target: all expected addresses (e.g. 38/38 when TransactionMirror and DODO cUSDT/cUSDC pool are present). Update [REQUIRED_FIXES_AND_DEPLOYMENTS_STATUS.md](REQUIRED_FIXES_AND_DEPLOYMENTS_STATUS.md) and [CONTRACT_ADDRESSES_REFERENCE.md](../11-references/CONTRACT_ADDRESSES_REFERENCE.md) with new pool and provider addresses.
+
+---
+
+## 4. Script reference
+
+| Script | Purpose |
+|--------|---------|
+| `scripts/deployment/deploy-transaction-mirror-and-pmm-pool-after-txpool-clear.sh` | Deploy TransactionMirror + create cUSDT/cUSDC pool (Core RPC only). |
+| `smom-dbis-138/script/dex/CreateCUSDTCUSDCPool.s.sol` | Create cUSDT/cUSDC pool. |
+| `smom-dbis-138/script/dex/CreateCUSDTUSDTPool.s.sol` | Create cUSDT/USDT pool. |
+| `smom-dbis-138/script/dex/CreateCUSDCUSDCPool.s.sol` | Create cUSDC/USDC pool. |
+| `smom-dbis-138/script/liquidity/DeployDODOPMMProvider.s.sol` | Deploy DODOPMMProvider (then register pools). |
+| `smom-dbis-138/script/bridge/trustless/DeployEnhancedSwapRouter.s.sol` | Deploy EnhancedSwapRouter (mainnet-only; Chain 138 needs env/config). |
+| `scripts/verify/check-contracts-on-chain-138.sh` | Verify expected contract addresses on Chain 138. |
+
+---
+
+## 5. References
+
+- [POOLS_AND_NETWORKS_FULL_DESIGN.md](../11-references/POOLS_AND_NETWORKS_FULL_DESIGN.md) — Every pool and network in the full design (61 pools, 6 networks).
+- [REQUIRED_FIXES_AND_DEPLOYMENTS_STATUS.md](REQUIRED_FIXES_AND_DEPLOYMENTS_STATUS.md) — RPC fix, missing contracts, completion steps.
+- [UNDEPLOYED_CONTRACTS_PRE_DEPLOYMENT_TASKS.md](UNDEPLOYED_CONTRACTS_PRE_DEPLOYMENT_TASKS.md) — Dry-run and validation tasks.
+- [PMM_DEX_ROUTING_STATUS.md](../11-references/PMM_DEX_ROUTING_STATUS.md) — Full PMM/DEX routing status.
+- [DODO_PMM_INTEGRATION.md](../../smom-dbis-138/docs/integration/DODO_PMM_INTEGRATION.md) — Pool creation, liquidity, swap usage.
+- [CONTRACT_DEPLOYMENT_RUNBOOK.md](CONTRACT_DEPLOYMENT_RUNBOOK.md) — EnhancedSwapRouter & DODOPMMProvider config.
--- a/docs/03-deployment/RECOMMENDATIONS_AND_FIXES_BEFORE_DEPLOY.md
+++ b/docs/03-deployment/RECOMMENDATIONS_AND_FIXES_BEFORE_DEPLOY.md
@@ -0,0 +1,141 @@
+# Recommendations and Fixes Before Deploying Smart Contracts and PMM Pools
+
+**Last Updated:** 2026-02-27  
+**Purpose:** Single checklist of all **recommendations** and **required fixes** to complete before deploying smart contracts and PMM pools on Chain 138 (and related chains). Use this with [DEPLOYMENT_ORDER_OF_OPERATIONS.md](DEPLOYMENT_ORDER_OF_OPERATIONS.md) and [PRE_DEPLOYMENT_CHECKLIST.md](PRE_DEPLOYMENT_CHECKLIST.md).
+
+**Related:** [TODOS_CONSOLIDATED](../00-meta/TODOS_CONSOLIDATED.md) § First (0a–0c) | [CONTRACT_DEPLOYMENT_RUNBOOK.md](CONTRACT_DEPLOYMENT_RUNBOOK.md) | [RECOMMENDATIONS_OPERATOR_CHECKLIST](../00-meta/RECOMMENDATIONS_OPERATOR_CHECKLIST.md)
+
+**Run all checkable items:** `./scripts/deployment/run-before-deploy-checks.sh` ([§7](#7-run-all-checkable-items-one-script)).
+
+---
+
+## 1. Mandatory fixes and checks (do first)
+
+These must be satisfied before **any** Chain 138 deployment. Run preflight once; repeat if RPC, env, or nonce change.
+
+| # | Item | Action / fix |
+|---|------|--------------|
+| **1.1** | **Run preflight** | From repo root: `./scripts/deployment/preflight-chain138-deploy.sh [--cost]`. Verifies: dotenv exists, required env keys, RPC returns chainId 0x8a (138), deployer nonce (warns if stuck). Use `--cost` for gas/cost estimate. |
+| **1.2** | **Core RPC = IP:port, not FQDN** | In `smom-dbis-138/.env` set `RPC_URL_138=http://192.168.11.211:8545` (Core RPC, VMID 2101). Do **not** use `https://rpc-core.d-bis.org` for deployment (DNS/tunnel can fail). See [RPC_ENDPOINTS_MASTER](../04-configuration/RPC_ENDPOINTS_MASTER.md), [TODOS_CONSOLIDATED](../00-meta/TODOS_CONSOLIDATED.md) § 0b. |
+| **1.3** | **Deployer gas (Chain 138)** | Ensure deployer has ≥ ~0.006 ETH (recommended 1–2 ETH). Check: `RPC_URL_138=http://192.168.11.211:8545 ./scripts/deployment/check-deployer-balance-chain138-and-funding-plan.sh` or `cd smom-dbis-138 && ./scripts/deployment/check-balances-gas-and-deploy.sh`. |
+| **1.4** | **Env from smom-dbis-138/.env only** | All deploy secrets from **`smom-dbis-138/.env`** only. Required: `PRIVATE_KEY`, `RPC_URL_138`. For PMM: `DODO_PMM_INTEGRATION_ADDRESS=0x79cdbaFBaA0FdF9F55D26F360F54cddE5c743F7D`. Optional: `GAS_PRICE_138`, `GAS_PRICE` (default 1 gwei). Verify: `cd smom-dbis-138 && ./scripts/deployment/check-env-required.sh`. |
+| **1.5** | **No stuck transactions** | If nonce has pending txs or you see "Replacement transaction underpriced": run `./scripts/clear-all-transaction-pools.sh` then wait **~60s** before deploying. Prefer scripts that check nonce (e.g. `deploy-transaction-mirror-and-pmm-pool-after-txpool-clear.sh`). |
+| **1.6** | **RPC 2101 (Core) writable** | If Core was read-only: `./scripts/maintenance/make-rpc-vmids-writable-via-ssh.sh` then `./scripts/maintenance/health-check-rpc-2101.sh`. See [RPC_2101_READONLY_FIX.md](RPC_2101_READONLY_FIX.md). |
+| **1.7** | **Test all contracts** | Run **before** any deploy: `./scripts/deployment/test-all-contracts-before-deploy.sh`. Use `--dry-run` to print commands; `--no-match "Fork|Mainnet|Integration|e2e"` for unit-only; `--alltra` to include alltra-lifi-settlement. See [DEPLOYMENT_ORDER_OF_OPERATIONS](DEPLOYMENT_ORDER_OF_OPERATIONS.md) § Phase 0.8. |
+| **1.8** | **Gas / cost estimate** | Before deploying: `cd smom-dbis-138 && ./scripts/deployment/calculate-costs-consolidated.sh` (Chain 138 min gas 1 gwei). See [DEPLOYMENT_GAS_COSTS_REALTIME](../11-references/DEPLOYMENT_GAS_COSTS_REALTIME.md). |
+| **1.9** | **POOL_MANAGER_ROLE** | Deployer must have `POOL_MANAGER_ROLE` on DODOPMMIntegration for pool creation and DODOPMMProvider registration. |
+| **1.10** | **Foundry** | `forge` in PATH; `cd smom-dbis-138 && forge build` succeeds. |
+
+---
+
+## 2. Deployment safety (four rules)
+
+| Rule | Requirement |
+|------|-------------|
+| **Correct RPC** | Use **only** `RPC_URL_138` from `smom-dbis-138/.env` for deployments. Must point to **Core RPC** (VMID 2101, `http://192.168.11.211:8545`). Never use Public RPC for deploying. |
+| **Correct dotenv** | All deployment secrets from **`smom-dbis-138/.env`** only. Do not source a different .env for deploy. |
+| **Gas / cost** | Run gas/cost estimation before deploying (e.g. `calculate-costs-consolidated.sh`). Chain 138 minimum gas 1 gwei. |
+| **Do not deploy when stuck** | Clear tx pool, wait ~60s; use scripts that check nonce when available. |
+
+---
+
+## 3. Identified gaps to fix or confirm before deploy
+
+| Gap | Location / scope | Fix / action |
+|-----|------------------|--------------|
+| **Wemix (1111) token addresses** | config/token-mapping-multichain.json | Confirm WETH, USDT, USDC on [scan.wemix.com/tokens](https://scan.wemix.com/tokens); update config and WEMIX_TOKEN_VERIFICATION.md if different; run `validate-config-files.sh`. |
+| **Canonical addresses** | token-aggregation, .env | Canonical token addresses (e.g. CUSDC_ADDRESS_138, CUSDT_ADDRESS_138) in env or smart-contracts-master.json; token-aggregation uses env override. See [REQUIRED_FIXES_UPDATES_GAPS](../REQUIRED_FIXES_UPDATES_GAPS.md) §3. |
+| **AlltraAdapter setBridgeFee** | AlltraAdapter.sol | Fee configurable via `setBridgeFee(uint256)`; operator calls after deploy. Set `ALLTRA_BRIDGE_FEE`, `ALLTRA_ADAPTER_CHAIN138` in .env. |
+| **Smart accounts / Paymaster** | DeploySmartAccountsKit | Script reads `ENTRY_POINT`, `SMART_ACCOUNT_FACTORY`, `PAYMASTER` from env. Deploy ERC-4337 contracts separately and set in .env. |
+| **Quote service FABRIC_CHAIN_ID** | bridge/quote-service | Uses `FABRIC_CHAIN_ID` from env (default 999). Set when Fabric is live. |
+| **CCIPWETH9Bridge** | Env / runbook | Use only canonical bridge (e.g. `0x971c...`); do **not** use deprecated `0x89dd...`. Set `CCIPWETH9_BRIDGE_CHAIN138` in env. See RECOMMENDATIONS_OPERATOR_CHECKLIST R4. |
+| **Token mapping** | config/token-mapping.json | Single source of truth for 138↔Mainnet; when adding tokens update token-mapping.json and optionally CHAIN138_TOKEN_ADDRESSES. R24. |
+
+---
+
+## 4. Token deployments remaining (prerequisites for full token/PMM coverage)
+
+If you plan to deploy **additional** tokens or vaults after core + PMM, ensure prerequisites and order. Full list: [TOKEN_CONTRACT_DEPLOYMENTS_REMAINING](../11-references/TOKEN_CONTRACT_DEPLOYMENTS_REMAINING.md).
+
+| Category | Prerequisite | Notes |
+|----------|-------------|--------|
+| **DeployCompliantFiatTokens (cEURC, cEURT, cGBP*, cAUD*, cJPY*, cCHF*, cCADC, cXAU*)** | `CREATE2_FACTORY_ADDRESS` (e.g. from DeployDeterministicCore) | Use Core RPC (IP:port). After deploy: update CHAIN138_TOKEN_ADDRESSES and env. |
+| **Optional cCADT** | Add to DeployCompliantFiatTokens.s.sol if needed | Tether-style CAD. |
+| **Vault ac* / vdc* / sdc*** | Base tokens deployed (e.g. cUSDC, cUSDT, then extra compliant) | DeployAcVdcSdcVaults; extend for each new base. |
+| **cW* on public chains** | Per-chain RPC, bridge, pool-matrix | Design in POOLS_AND_NETWORKS_FULL_DESIGN; pool-matrix in cross-chain-pmm-lps. |
+| **ACADT / ALL Mainnet** | Alltra ecosystem | No script in repo; address TBD when Alltra adds CAD token. |
+
+---
+
+## 5. PMM-specific: before adding liquidity and provider
+
+| # | Item | Action |
+|---|------|--------|
+| 5.1 | **DODOPMMIntegration** | Already deployed: `0x79cdbaFBaA0FdF9F55D26F360F54cddE5c743F7D`. Ensure `DODO_PMM_INTEGRATION_ADDRESS` set in .env. |
+| 5.2 | **PMM pools (all three)** | cUSDT/cUSDC, cUSDT/USDT, cUSDC/USDC must be **created** (CreateCUSDTCUSDCPool, CreateCUSDTUSDTPool, CreateCUSDCUSDCPool). Use Core RPC only. |
+| 5.3 | **DODOPMMProvider** | Deploy via DeployDODOPMMProvider.s.sol; set `DODO_PMM_PROVIDER_ADDRESS` in .env. Register each pool: `provider.registerPool(tokenIn, tokenOut, poolAddress)`. |
+| 5.4 | **Liquidity (optional)** | Per pool: approve base/quote to DODOPMMIntegration, then `addLiquidity(pool, baseAmount, quoteAmount)`. See [DODO_PMM_INTEGRATION](../../smom-dbis-138/docs/integration/DODO_PMM_INTEGRATION.md). |
+| 5.5 | **Token-aggregation** | Set `CHAIN_138_DODO_PMM_INTEGRATION` where token-aggregation runs so API indexes DODO pools. |
+
+---
+
+## 6. Operator recommendations (R1–R24) — before and after deploy
+
+**Before deploy:** R8 (RPC Core), R9 (gas 1 gwei), R10 (phased core order), R11 (nonce if stuck), R19 (forge test).
+
+**After deploy:** R1 (verify on Blockscout), R2 (update CONTRACT_ADDRESSES_REFERENCE, ADDRESS_MATRIX_AND_STATUS), R3 (run check-contracts-on-chain-138.sh), R12–R13 (runbooks and per-chain docs).
+
+**Security:** R4 (canonical CCIPWETH9Bridge only), R5 (never commit .env/keys), R7 (restrict deployer and RPC access).
+
+**Ongoing:** R17 (monitor bridge/oracle events), R18 (Blockscout and /api up), R24 (token-mapping.json source of truth).
+
+Full list: [RECOMMENDATIONS_OPERATOR_CHECKLIST](../00-meta/RECOMMENDATIONS_OPERATOR_CHECKLIST.md).
+
+---
+
+## 7. Run all checkable items (one script)
+
+From repo root, run every check that can be automated (preflight, env, forge build, contract tests, config validation). Optionally include gas estimate, alltra e2e, and on-chain verification.
+
+```bash
+# All checkable items (unit tests only; ~1–2 min)
+./scripts/deployment/run-before-deploy-checks.sh
+
+# With gas/cost estimate
+./scripts/deployment/run-before-deploy-checks.sh --cost
+
+# With alltra-lifi-settlement tests (longer)
+./scripts/deployment/run-before-deploy-checks.sh --alltra
+
+# With on-chain verification (Chain 138)
+./scripts/deployment/run-before-deploy-checks.sh --on-chain
+```
+
+The script reports **PASS** or **FAIL** per step and exits 0 only if all steps pass. Remaining items (deployer gas, POOL_MANAGER_ROLE, RPC writable if needed) require operator/LAN; see §1 and §2.
+
+---
+
+## 8. Quick command reference
+
+| Action | Command |
+|--------|---------|
+| Preflight (RPC, env, nonce, optional cost) | `./scripts/deployment/preflight-chain138-deploy.sh [--cost]` |
+| Deployer balance / funding plan (Chain 138) | `RPC_URL_138=http://192.168.11.211:8545 ./scripts/deployment/check-deployer-balance-chain138-and-funding-plan.sh` |
+| Env check (smom-dbis-138) | `cd smom-dbis-138 && ./scripts/deployment/check-env-required.sh` |
+| Test all contracts | `./scripts/deployment/test-all-contracts-before-deploy.sh` (options: `--dry-run`, `--no-match "Fork|Mainnet|Integration|e2e"`, `--alltra`) |
+| Gas/cost estimate | `cd smom-dbis-138 && ./scripts/deployment/calculate-costs-consolidated.sh` |
+| Clear stuck tx pool | `./scripts/clear-all-transaction-pools.sh` then wait ~60s |
+| On-chain verification (Chain 138) | `./scripts/verify/check-contracts-on-chain-138.sh [RPC_URL]` |
+| Config validation | `bash scripts/validation/validate-config-files.sh` |
+
+---
+
+## 9. References
+
+- [DEPLOYMENT_ORDER_OF_OPERATIONS.md](DEPLOYMENT_ORDER_OF_OPERATIONS.md) — Phase 0–6 full order
+- [PRE_DEPLOYMENT_CHECKLIST.md](PRE_DEPLOYMENT_CHECKLIST.md) — PMM/pools steps and script reference
+- [CONTRACT_DEPLOYMENT_RUNBOOK.md](CONTRACT_DEPLOYMENT_RUNBOOK.md) — Per-script detail and test-before-deploy
+- [TODOS_CONSOLIDATED](../00-meta/TODOS_CONSOLIDATED.md) — First (0a–0c), token deployments (T1–T7), high/medium priority
+- [REQUIRED_FIXES_UPDATES_GAPS](../REQUIRED_FIXES_UPDATES_GAPS.md) — Build/code placeholders and gaps (all done or documented)
+- [TOKEN_CONTRACT_DEPLOYMENTS_REMAINING](../11-references/TOKEN_CONTRACT_DEPLOYMENTS_REMAINING.md) — Remaining token deployments by category
+- [OPERATOR_READY_CHECKLIST](../00-meta/OPERATOR_READY_CHECKLIST.md) — Copy-paste commands for operator/LAN tasks
--- a/docs/03-deployment/REQUIRED_FIXES_AND_DEPLOYMENTS_STATUS.md
+++ b/docs/03-deployment/REQUIRED_FIXES_AND_DEPLOYMENTS_STATUS.md
@@ -0,0 +1,42 @@
+# Required Fixes and Deployments — Status
+
+**Last Updated:** 2026-02-28
+
+## Required fixes
+
+### 1. RPC 2101 (Core) — read-only filesystem
+
+- **Status:** Not fixed (host storage I/O errors).
+- **Fix before deploying:** Run `./scripts/maintenance/make-rpc-vmids-writable-via-ssh.sh` then `./scripts/maintenance/health-check-rpc-2101.sh`. No Public RPC fallback for contract deployments.
+- **Fix:** See [RPC_2101_READONLY_FIX.md](RPC_2101_READONLY_FIX.md).
+
+### 2. Stuck transactions
+
+- **Scripts:** `./scripts/clear-all-transaction-pools.sh` (validators + 2101 + 2201); `./scripts/clear-rpc-2201-txpool.sh`. Deploy script sets `NEXT_NONCE` from pending nonce automatically.
+
+---
+
+## On-chain verification (Chain 138)
+
+**Last run (2026-03-01):** `./scripts/verify/check-contracts-on-chain-138.sh` (use Core RPC URL or run from LAN).  
+**Result:** **38 present, 0 missing** (38 addresses). TransactionMirror: `0x7131F887DBEEb2e44c1Ed267D2A68b5b83285afc`. DODO cUSDT/cUSDC pool: `0x9fcB06Aa1FD5215DC0E91Fd098aeff4B62fEa5C8` (created). **DeployCompliantFiatTokens** was run 2026-02-27 (10 tokens: cEURC, cEURT, cGBPC, cGBPT, cAUDC, cJPYC, cCHFC, cCADC, cXAUC, cXAUT); see [CHAIN138_TOKEN_ADDRESSES](../11-references/CHAIN138_TOKEN_ADDRESSES.md).
+
+---
+
+## Deployments (Chain 138)
+
+| Item | Address | Status |
+|------|---------|--------|
+| TransactionMirror | `0x7131F887DBEEb2e44c1Ed267D2A68b5b83285afc` | Deployed 2026-02-27. Set `TRANSACTION_MIRROR_ADDRESS` in smom-dbis-138/.env. |
+| DODO cUSDT/cUSDC pool | 0x9fcB06Aa1FD5215DC0E91Fd098aeff4B62fEa5C8 | Created (all three PMM pools exist). Add liquidity via [ADD_LIQUIDITY_PMM_CHAIN138_RUNBOOK](ADD_LIQUIDITY_PMM_CHAIN138_RUNBOOK.md). |
+| Compliant Fiat (10 tokens) | See CHAIN138_TOKEN_ADDRESSES | Deployed via DeployCompliantFiatTokens 2026-02-27. |
+
+---
+
+## Completion (run from LAN)
+
+0. **If Core RPC was read-only:** `./scripts/maintenance/make-rpc-vmids-writable-via-ssh.sh` then `./scripts/maintenance/health-check-rpc-2101.sh` (must pass). See [RPC_2101_READONLY_FIX.md](RPC_2101_READONLY_FIX.md).
+1. Optional: `./scripts/clear-all-transaction-pools.sh` then wait 60s if nonce stuck.
+2. `./scripts/deployment/deploy-transaction-mirror-and-pmm-pool-after-txpool-clear.sh` (Core RPC only; checks nonce, RPC, gas; deploys mirror then pool).
+3. Set `TRANSACTION_MIRROR_ADDRESS` in `smom-dbis-138/.env` to the logged address.
+4. `./scripts/verify/check-contracts-on-chain-138.sh` (pass Core RPC URL or use RPC_URL_138) — target 38 present when both confirmed.
--- a/docs/03-deployment/RPC_2101_READONLY_FIX.md
+++ b/docs/03-deployment/RPC_2101_READONLY_FIX.md
@@ -0,0 +1,57 @@
+# RPC 2101 (Core) — Read-only filesystem fix
+
+**VMID 2101** (192.168.11.211, Chain 138 Core RPC) can fail with Besu in a crash loop and **port 8545 connection refused**. Root cause observed: **Read-only file system** on `/data/besu/database/`.
+
+## Cause
+
+- **Kernel I/O errors** on the host (Proxmox 192.168.11.11): `Buffer I/O error on device dm-*`, `EXT4-fs: failed to convert unwritten extents`, `potential data loss`.
+- ext4 remounts the filesystem **read-only** to avoid further corruption. Besu then fails with:  
+  `RocksDBException: While appending to file: /data/besu/database/... : Read-only file system`.
+- Besu may also crash at startup with **JNA**: `UnsatisfiedLinkError: Failed to create temporary file for ... libjnidispatch.so: Read-only file system` — JNA needs a writable temp dir (e.g. `/tmp` or `java.io.tmpdir`); if the whole root is ro, startup fails before RPC binds.
+
+## Before deploying contracts
+
+Contract deployments use **Core RPC only** (no Public fallback). Fix read-only and verify health first:
+
+1. **Fix read-only:** `./scripts/maintenance/make-rpc-vmids-writable-via-ssh.sh`
+2. **Health check:** `./scripts/maintenance/health-check-rpc-2101.sh` (must pass)
+3. **Deploy:** `./scripts/deployment/deploy-transaction-mirror-and-pmm-pool-after-txpool-clear.sh`
+
+If you get **"Known transaction"** (stuck tx at deployer nonce), clear the Core RPC tx pool: `./scripts/clear-all-transaction-pools.sh` then retry deploy.
+
+## Fixing 2101 (operator)
+
+1. **SSH to Proxmox host:** `ssh root@192.168.11.11`
+2. **Check kernel logs for I/O errors:**  
+   `dmesg | grep -E "Buffer I/O|EXT4-fs|dm-"`  
+   Identify which dm-* (LV) is affected; `ls -la /dev/mapper/pve-vm--2101--disk--0` shows 2101’s device (e.g. dm-45).
+3. **Storage health:** Check LVM and disks (e.g. `lvs`, `pvs`, `smartctl` on underlying disks). Replace or repair failing hardware.
+4. **Remount read-write (only if storage is known good):**
+   - Stop the container: `pct stop 2101`
+   - From the host, the container root is mounted by Proxmox; after fixing storage you may need to run `fsck` on the LV or reboot the host. If the filesystem was remounted ro due to transient error, sometimes a container stop/start helps (host remounts the LV).
+   - Start the container: `pct start 2101`
+   - Inside container verify: `pct exec 2101 -- touch /data/besu/database/.write_test && rm /data/besu/database/.write_test`
+5. **Restart Besu RPC:**  
+   `pct exec 2101 -- systemctl restart besu-rpc.service`  
+   Then: `./scripts/check-network-rpc-138.sh 192.168.11.211 8545`
+
+### If still read-only after make-writable
+
+If `make-rpc-vmids-writable-via-ssh.sh` completes but inside the container **`/tmp`, `/data/besu/database`, or `/data/besu/tmp`** are still read-only (`touch` fails with "Read-only file system"):
+
+- **e2fsck** may have reported `Error writing file system info: Input/output error` — the **underlying storage** (LV or disk on the host) may be failing.
+- **Thin pool 100% full:** CT 2101 (and other RPC nodes) use the LVM thin pool **pve/data**. If the pool is 100% full (`lvs pve/data` shows Data% 100.00), writes can fail and the kernel may remount the filesystem read-only. **Fix:** On the Proxmox host, extend the pool if the VG has free space: `lvextend -L +80G pve/data` (adjust size). Then re-run make-writable and restart the container. Alternatively migrate the CT to another pool (e.g. thin1) or free space by removing/moving other LVs.
+- On the Proxmox host: check `dmesg | grep -E 'I/O error|dm-|ext4'`, and run `smartctl` / LVM checks on the storage backing the CT. If the LV or disk has persistent I/O errors, fix or replace storage, then re-run `make-rpc-vmids-writable-via-ssh.sh`, or migrate the CT to healthy storage.
+
+## TransactionMirror address
+
+Set `TRANSACTION_MIRROR_ADDRESS` in `smom-dbis-138/.env` from the deploy script output. A previous deploy used **0xE362aa10D3Af1A16880A799b78D18F923403B55a**; use the script output as source of truth.
+
+## Scripts
+
+- **Make Core writable (fix read-only):** `./scripts/maintenance/make-rpc-vmids-writable-via-ssh.sh` — run first when 2101 is read-only.
+- **Health check:** `./scripts/maintenance/health-check-rpc-2101.sh` — container, service, port, RPC eth_chainId/eth_blockNumber, and database writability.
+- **Fix/restart Besu:** `./scripts/maintenance/fix-core-rpc-2101.sh` [--dry-run] [--restart-only].
+- **Check/start RPC service:** `./scripts/check-and-start-rpc-2101.sh` (cannot fix read-only; only restarts the service).
+- **Network check:** `./scripts/check-network-rpc-138.sh [HOST] [PORT]` (default 192.168.11.211 8545).
+- **Deploy (Core only):** `./scripts/deployment/deploy-transaction-mirror-and-pmm-pool-after-txpool-clear.sh`. No Public fallback; fix Core first.
--- a/docs/03-deployment/TRANSACTION_MIRROR_CHAIN138_COLLISION_FIX.md
+++ b/docs/03-deployment/TRANSACTION_MIRROR_CHAIN138_COLLISION_FIX.md
@@ -0,0 +1,62 @@
+# TransactionMirror Chain 138 — CreateCollision and skip-mirror steps
+
+**Purpose:** If `deploy-transaction-mirror-and-pmm-pool-after-txpool-clear.sh` fails with **CreateCollision** (contract already at expected address), use this to fix and proceed to pool creation only.
+
+---
+
+## Address from CreateCollision trace
+
+When the deploy fails, the trace shows the address that already has code:
+
+| Address | Role |
+|---------|------|
+| **0xC7f2Cf4845C6db0e1a1e91ED41Bcd0FcC1b0E141** | Expected TransactionMirror address (deployer + nonce 13410). If CreateCollision occurs, a contract is already deployed here. |
+
+**Lookup on Chain 138:**  
+`cast code 0xC7f2Cf4845C6db0e1a1e91ED41Bcd0FcC1b0E141 --rpc-url $RPC_URL_138`  
+
+- If code length > 2 (i.e. not `0x`): contract exists; use it as the mirror and skip deploy.
+- If code length = 2: no contract at that address on current RPC state; deploy may have failed for another reason, or state differs (e.g. different node).
+
+---
+
+## Exact env + script steps
+
+### Option A — Use existing mirror and run pool-only
+
+1. **Set the mirror address in .env** (if the collision address has code on your RPC):
+
+   ```bash
+   # In smom-dbis-138/.env
+   TRANSACTION_MIRROR_ADDRESS=0xC7f2Cf4845C6db0e1a1e91ED41Bcd0FcC1b0E141
+   ```
+
+2. **Run the script with --skip-mirror** (only creates the cUSDT/cUSDC PMM pool):
+
+   ```bash
+   ./scripts/deployment/deploy-transaction-mirror-and-pmm-pool-after-txpool-clear.sh --skip-mirror
+   ```
+
+3. **Or run without --skip-mirror:**  
+   If `TRANSACTION_MIRROR_ADDRESS` is set and that address has code on chain, the script **skips** the TransactionMirror deploy and proceeds to pool creation.
+
+### Option B — Deploy a new TransactionMirror (different address)
+
+If you need a new mirror (e.g. that address is wrong or empty):
+
+1. Clear any stuck nonce: `./scripts/clear-all-transaction-pools.sh` then wait ~60s.
+2. Do **not** set `TRANSACTION_MIRROR_ADDRESS` (or unset it).
+3. Run the full script again (no `--skip-mirror`). The next deploy will use the current nonce and a new address.
+
+---
+
+## Script options (reference)
+
+| Option | Effect |
+|--------|--------|
+| (none) | Deploy TransactionMirror (if not skipped), then create PMM pool. |
+| `--skip-mirror` | Skip mirror deploy; only create PMM pool. Requires `TRANSACTION_MIRROR_ADDRESS` in .env. |
+| `--dry-run` | Print commands only; no deploy. |
+| `--force` | Skip RPC reachability check. |
+
+Skip logic (no flag): if `TRANSACTION_MIRROR_ADDRESS` is set in .env and that address has code on Chain 138, the script skips the mirror deploy and continues to pool creation.
--- a/docs/03-deployment/UNDEPLOYED_CONTRACTS_PRE_DEPLOYMENT_TASKS.md
+++ b/docs/03-deployment/UNDEPLOYED_CONTRACTS_PRE_DEPLOYMENT_TASKS.md
@@ -0,0 +1,116 @@
+# Undeployed Contracts — Pre-Deployment Tasks
+
+**Last Updated:** 2026-02-28  
+**Execution summary (2026-02-27):** On-chain verification **36/38**. Two missing: TransactionMirror (set `TRANSACTION_MIRROR_ADDRESS` in .env from script output) and DODO cUSDT/cUSDC pool (0x9fcB...). **Deploy uses Core RPC only.** Before deploy: if Core was read-only, run `./scripts/maintenance/make-rpc-vmids-writable-via-ssh.sh` then `./scripts/maintenance/health-check-rpc-2101.sh`. See [REQUIRED_FIXES_AND_DEPLOYMENTS_STATUS.md](REQUIRED_FIXES_AND_DEPLOYMENTS_STATUS.md), [RPC_2101_READONLY_FIX.md](RPC_2101_READONLY_FIX.md).
+
+**Execution summary (2026-02-26):** **All runnable tasks executed.** Env check, unified deploy dry-run, PMM pool dry-run, on-chain verification (36/36), deploy-optional-future-all --dry-run, fund-ccip-bridges-with-link --dry-run, check-balances-gas-and-deploy.sh, get-multichain-gas-prices.sh all completed. Mainnet dry-run and TransactionMirror simulate started (mainnet compiles CCIP bridges; run to completion when mainnet RPC is responsive). Previous: 1.x wallet/gas, 2.x gas API and estimates, 3.1 unified deploy dry-run (RPC + init fixes in smom-dbis-138), 3.2 DeployDeterministicCore simulated, 3.3 PMM pool script dry-run, 3.4 TransactionMirror, 3.6 optional-future, 3.7 fund-ccip dry-run, 4.6 on-chain verification (36/36). Optional env vars added to `smom-dbis-138/.env` when missing: `DODO_PMM_INTEGRATION_ADDRESS`, `QUOTE_TOKEN_ADDRESS`, `WETH_ADDRESS_138` (public addresses only). PMM and unified deploy dry-runs now work with .env only (no inline env). Remaining: 3.5 mainnet dry-run (run when mainnet RPC is reachable); 4.1–4.5 post-deploy validation when components are deployed.
+
+**Source:** [AI_AGENTS_57XX_MCP_CONTRACTS_AND_CHAINS.md](../02-architecture/AI_AGENTS_57XX_MCP_CONTRACTS_AND_CHAINS.md), [DEX_AND_CROSS_CHAIN_CONTRACTS_NEEDED.md](../11-references/DEX_AND_CROSS_CHAIN_CONTRACTS_NEEDED.md), [DEPLOYED_CONTRACTS_OVERVIEW](../../smom-dbis-138/docs/deployment/DEPLOYED_CONTRACTS_OVERVIEW.md), [deployment-status.json](../../cross-chain-pmm-lps/config/deployment-status.json)
+
+This checklist covers: **testing** anything not yet deployed, **checking deployer wallet gas**, **using the gas API to estimate deployment costs**, and **dry-running deployments** before live execution.
+
+**Optional env vars (add/set when needed):** In `smom-dbis-138/.env`, if missing, add (public addresses only): `DODO_PMM_INTEGRATION_ADDRESS=0x79cdbaFBaA0FdF9F55D26F360F54cddE5c743F7D`, `QUOTE_TOKEN_ADDRESS=0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2`, `WETH_ADDRESS_138=0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2` so PMM pool script and dry-runs work with .env only. Check: `./scripts/deployment/check-env-required.sh`.
+
+---
+
+## 1. Check deployer wallet for gas
+
+- [x] **1.1** Resolve deployer address from env:
+  ```bash
+  cd smom-dbis-138 && cast wallet address $PRIVATE_KEY
+  ```
+- [x] **1.2** Run balance check (Chain 138 + all networks the script supports):
+  ```bash
+  cd smom-dbis-138
+  ./scripts/deployment/check-balances-gas-and-deploy.sh
+  ```
+  Uses Infura/gas API where available; reports native token balance and estimated cost for 5M gas per chain. See [FUNDING_AND_DEPLOYMENT_CHECKLIST](FUNDING_AND_DEPLOYMENT_CHECKLIST.md).
+- [x] **1.3** Chain 138: ensure deployer has at least ~0.006 ETH (5M gas × 1 gwei + buffer). Recommended 1–2 ETH. If balance is 0, fund from genesis alloc or validator (see FUNDING_AND_DEPLOYMENT_CHECKLIST §2).
+- [x] **1.4** Mainnet / L2: ensure deployer has sufficient native token per chain for any planned deployments (see [DEPLOYMENT_GAS_COSTS_REALTIME](../11-references/DEPLOYMENT_GAS_COSTS_REALTIME.md) for recommended balances).
+
+---
+
+## 2. Use gas API to estimate all deployment costs
+
+- [x] **2.1** Fetch current gas prices (Etherscan for mainnet, defaults/RPC for others):
+  ```bash
+  cd smom-dbis-138
+  ./scripts/deployment/get-multichain-gas-prices.sh
+  ```
+  Output can be sourced or used to update cost estimates.
+- [x] **2.2** (Optional) Update doc with latest estimates:
+  ```bash
+  ./scripts/deployment/update-gas-estimates.sh
+  ```
+  Updates [DEPLOYMENT_GAS_COSTS_REALTIME](../11-references/DEPLOYMENT_GAS_COSTS_REALTIME.md) (or script’s target doc).
+- [x] **2.3** Estimate gas for **undeployed** items (by chain): TransactionMirror simulated via `forge script` (no broadcast); DeployDeterministicCore reported ~10.67M gas. For pool creation use `cast estimate` on DODOPMMIntegration with `createCUSDTCUSDCPool`/`createPool` args when ready. EnhancedSwapRouter/DODOPMMProvider: run script dry-run when implemented.
+- [x] **2.4** Sum estimated cost per chain and confirm deployer balance ≥ sum + buffer (e.g. 20–30%): Confirmed via check-balances-gas-and-deploy.sh; Chain 138 sufficient; mainnet/L2 need funding for full deploy.
+
+---
+
+## 3. Dry-run deployments
+
+- [x] **3.1** Chain 138 — unified deploy (no broadcast): Run `./scripts/deployment/deploy-contracts-unified.sh --dry-run --rpc-url $RPC_URL_138`. RPC check uses 10s timeout; init.sh LOG_LEVEL fix applied so script runs with .env loaded.
+  ```bash
+  cd smom-dbis-138
+  ./scripts/deployment/deploy-contracts-unified.sh --dry-run --rpc-url "http://192.168.11.211:8545"
+  ```
+- [x] **3.2** Chain 138 — phased core (dry-run if script supports): Simulated `forge script script/deploy/DeployDeterministicCore.s.sol --rpc-url $RPC_URL_138` (no `--broadcast`); script ran successfully with gas estimate.
+  ```bash
+  forge script script/deploy/DeployDeterministicCore.s.sol --rpc-url $RPC_URL_138
+  ```
+- [x] **3.3** Chain 138 — PMM pool creation (dry-run): Set `DODO_PMM_INTEGRATION_ADDRESS` and `QUOTE_TOKEN_ADDRESS` (e.g. WETH `0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2`), then run `DRY_RUN=true CHAIN_ID=138 ./scripts/create-all-dodo-pools-from-token-api.sh`. Script accepts `DODO_PMM_INTEGRATION` or `DODO_PMM_INTEGRATION_ADDRESS`. With Token API unavailable it reports "Pools created: 0"; with API running it would list tokens and log `[DRY RUN] Would createPool ...`. Document: [DODO_PMM_INTEGRATION](../../smom-dbis-138/docs/integration/DODO_PMM_INTEGRATION.md), [DODO_PMM_NEXT_STEPS](../../smom-dbis-138/docs/bridge/DODO_PMM_NEXT_STEPS.md).
+- [x] **3.4** Chain 138 — TransactionMirror (optional): Run without `--broadcast` to simulate: `forge script script/DeployTransactionMirror.s.sol:DeployTransactionMirror --rpc-url $RPC_URL_138`. See [CONTRACT_DEPLOYMENT_RUNBOOK](CONTRACT_DEPLOYMENT_RUNBOOK.md) § TransactionMirror.
+- [ ] **3.5** Mainnet — dry-run (if deploying anything new): Requires `PRIVATE_KEY`, `ETHEREUM_MAINNET_RPC` in .env. Run from environment with mainnet RPC access. Script validates tools, env, addresses, and compiles CCIP bridges.
+  ```bash
+  ./scripts/deployment/dry-run-mainnet-deployment.sh
+  ```
+  Or per-script: `forge script script/... --rpc-url $MAINNET_RPC --dry-run`.
+- [x] **3.6** Optional/future deployments (dry-run only):
+  ```bash
+  cd smom-dbis-138
+  ./scripts/deployment/deploy-optional-future-all.sh --dry-run
+  ```
+- [x] **3.7** Bridge/LINK funding (dry-run):
+  ```bash
+  ./scripts/deployment/fund-ccip-bridges-with-link.sh --link 10 --dry-run
+  ```
+
+---
+
+## 4. Test anything not deployed (validation / unit / script)
+
+- [ ] **4.1** **PMM pools (Chain 138):** Create cUSDT/cUSDC pool with `forge script script/dex/CreateCUSDTCUSDCPool.s.sol:CreateCUSDTCUSDCPool --rpc-url $RPC_URL_138 --broadcast --private-key $PRIVATE_KEY --with-gas-price 1000000000` (script: `smom-dbis-138/script/dex/CreateCUSDTCUSDCPool.s.sol`). Requires POOL_MANAGER_ROLE on DODOPMMIntegration. If you see "Replacement transaction underpriced", a tx is pending at that nonce; wait for it to be mined or clear mempool, then retry with same or higher gas. After creation, test: `getMidPrice`, `getOraclePrice`, `getBaseReserve`, `getQuoteReserve` on pool address; confirm MCP `dodo.get_pool_state` and `dodo.identify_pool_interface` work with that address in allowlist.
+- [ ] **4.2** **DODOPMMProvider:** Not deployed; implementation placeholder. When implemented, add unit tests and a script dry-run for deployment.
+- [ ] **4.3** **TransactionMirror (Chain 138):** Deploy with `forge script script/DeployTransactionMirror.s.sol:DeployTransactionMirror --rpc-url $RPC_URL_138 --broadcast --private-key $PRIVATE_KEY --with-gas-price 1000000000`. If you see "Known transaction", the tx may be pending or already mined; check code at the logged address. Then test mirror receive path.
+- [ ] **4.4** **EnhancedSwapRouter:** Not deployed. When Uniswap/Balancer pools exist on 138, run deploy script with `--dry-run` and test quote path.
+- [ ] **4.5** **cW* tokens and PMM pools on public chains (1, 56, 137, etc.):** No addresses in deployment-status. No deployment from this repo yet. When you have a deployment path (bridge + factory or DODO), run gas estimate and dry-run per chain.
+- [x] **4.6** **On-chain verification (38 addresses):** After any new deployment, run:
+  ```bash
+  ./scripts/verify/check-contracts-on-chain-138.sh [RPC_URL]
+  ```
+  Includes TransactionMirror and DODO cUSDT/cUSDC pool in the list. Last run: 36 present, 2 missing; see [REQUIRED_FIXES_AND_DEPLOYMENTS_STATUS](REQUIRED_FIXES_AND_DEPLOYMENTS_STATUS.md).
+
+---
+
+## 5. Summary — undeployed items (for cost and dry-run scope)
+
+| Chain | Item | Action for estimate / dry-run |
+|-------|------|-------------------------------|
+| **138** | PMM pools (cUSDT/cUSDC, cUSDT/USDT, cUSDC/USDC) | Estimate: `createPool` / `createCUSDTCUSDCPool` gas. Dry-run: pool-creation script or `cast send --dry-run`. |
+| **138** | TransactionMirror | `forge script` or `forge create` with `--dry-run` / `cast estimate`. |
+| **138** | DODOPMMProvider | When implemented: script dry-run + unit tests. |
+| **138** | EnhancedSwapRouter | When pools exist: script dry-run. |
+| **1** | (Trustless stack deployed; no new DODO from repo) | Gas estimate only if adding contracts. |
+| **56, 137, 10, 100, 25, 42161, 8453, 42220, 1111, 43114** | cW* tokens, PMM pools | When deployment path exists: per-chain gas estimate + deploy script dry-run. |
+
+---
+
+## 6. References
+
+- [CONTRACT_DEPLOYMENT_RUNBOOK](CONTRACT_DEPLOYMENT_RUNBOOK.md) — Chain 138 gas price, RPC, TransactionMirror.
+- [FUNDING_AND_DEPLOYMENT_CHECKLIST](FUNDING_AND_DEPLOYMENT_CHECKLIST.md) — Balance check, funding sources.
+- [DEPLOYMENT_GAS_COSTS_REALTIME](../11-references/DEPLOYMENT_GAS_COSTS_REALTIME.md) — Gas API, cost table.
+- [check-balances-gas-and-deploy.sh](../../smom-dbis-138/scripts/deployment/check-balances-gas-and-deploy.sh) — Balance + gas report.
+- [get-multichain-gas-prices.sh](../../smom-dbis-138/scripts/deployment/get-multichain-gas-prices.sh) — Gas prices for cost estimates.
+- [TODO_TASK_LIST_MASTER](../00-meta/TODO_TASK_LIST_MASTER.md) § Undeployed contracts pre-deployment — Master checklist link.
--- a/docs/03-deployment/sankofa-studio.env.example
+++ b/docs/03-deployment/sankofa-studio.env.example
@@ -0,0 +1,44 @@
+# Sankofa Studio (FusionAI Creator) — production .env for VMID 7805
+# Copy to fusionai-production.env and set values. Use with deploy-sankofa-studio-lxc.sh:
+#   ENV_FILE=/path/to/fusionai-production.env ./scripts/deployment/deploy-sankofa-studio-lxc.sh
+# See: docs/03-deployment/SANKOFA_STUDIO_DEPLOYMENT.md
+
+# Artifact storage (persistent path inside container; ensure volume in compose or host path)
+FUSIONAI_ARTIFACT_ROOT=/data/artifacts
+
+# Redis (docker-compose service name)
+FUSIONAI_REDIS_URL=redis://redis:6379/0
+
+# API URL (for worker and webhooks; use internal or public)
+FUSIONAI_API_URL=http://api:8000
+
+# Service URLs (internal; docker-compose service names)
+FUSIONAI_AUDIO_SERVICE_URL=http://audio:8001
+FUSIONAI_IMAGE_SERVICE_URL=http://image:8002
+FUSIONAI_VIDEO_ASSEMBLY_SERVICE_URL=http://video:8003
+FUSIONAI_UE5_EXPORT_SERVICE_URL=http://ue5_export:8004
+
+# Optional: require API key for POST /jobs, run, approve, cancel
+# FUSIONAI_API_KEY=your-secret-key
+
+# Optional: TTS backend (stub | piper | elevenlabs)
+# FUSIONAI_TTS_BACKEND=stub
+# FUSIONAI_ELEVENLABS_API_KEY=...
+# FUSIONAI_ELEVENLABS_VOICE_ID=...
+
+# Optional: Image backend (stub | openai | replicate)
+# FUSIONAI_IMAGE_BACKEND=stub
+# OPENAI_API_KEY=...
+# REPLICATE_API_TOKEN=...
+
+# Optional: completion webhook
+# FUSIONAI_COMPLETION_WEBHOOK_URL=https://...
+# FUSIONAI_WEBHOOK_RETRIES=2
+
+# Optional: rate limit (0 = no limit)
+# FUSIONAI_RATE_LIMIT_PER_MINUTE=0
+
+# Runner timeouts (seconds)
+# FUSIONAI_STAGE_TIMEOUT_SECONDS=300
+# FUSIONAI_JOB_TIMEOUT_SECONDS=3600
+# FUSIONAI_SERVICE_RETRIES=3