**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.
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 |
| 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.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. |
**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.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.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
| 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.
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.
