proxmox/docs/03-deployment/ALL_MAINNET_PROTOCOL_COMPLETION_RUNBOOK.md

ALL Mainnet Protocol Completion Runbook

Status: Operator runbook
Scope: ALL Mainnet 651940 pool inventory, auto-rebalancing, and protocol support gates.
Canonical inputs: config/all-mainnet-pool-creation-matrix.json, config/allmainnet-non-dodo-protocol-surface.json

Current State

The pool matrix already contains the intended inventory surface. Treat it as the source of truth for what must be created, funded, canaried, and eventually promoted.

As of the current matrix:

Protocol	Rows	Required for spend	Main blocker
dodo_pmm	49	24	Remaining planned pools and non-production rows
single_sided_pmm	3	3	Pool creation and funding
uniswap_v2	5	3	One planned pool plus promotion evidence
uniswap_v3	1	1	Canary passed; keep adapter compatibility gated
balancer_weighted	11	0	Optional protocol inventory not deployed/imported
curve_stable	11	0	Optional protocol inventory not deployed/imported
sushiswap_v2	11	0	Optional protocol inventory not deployed/imported
oneinch_aggregator	11	0	Optional aggregator routes depend on live native liquidity first
aave_backstop	11	0	Optional backstop market not deployed/imported

config/allmainnet-non-dodo-protocol-surface.json currently publishes partial same-chain inventory and keeps only DODO enabled through EnhancedSwapRouterV2. Do not enable optional providers until their pool rows have real addresses, reserve reads, canary evidence, and route quotes.

Phase 1: Close Required Inventory

Work required rows first. Optional protocols should not distract from getting the spend mesh healthy.

1. Generate the live worklist:

node scripts/status/generate-all-mainnet-readiness.mjs

Read:

• reports/status/all-mainnet-deployment-readiness-worklist-latest.json
• reports/status/all-mainnet-production-gate-latest.json
• reports/status/all-mainnet-spend-readiness-latest.json

2. For every required row with status: planned, create or import the pool address.

Required blockers are usually one of:

• pool_not_created
• missing_base_address:*
• missing_quote_address:*
• missing_pool_address

For DODO rows, use the committed DODO infrastructure from the row:

• infrastructure.dvmFactory
• infrastructure.dvmFactoryAdapter
• infrastructure.dodoPmmIntegration

For Uniswap V2/V3 rows, use the committed factory/router/quoter or import the canonical address from verified on-chain deployment evidence. Do not invent placeholder pool addresses.

3. After creating or importing pools, run reserve reads:

node scripts/status/check-all-mainnet-required-pool-balances.mjs
node scripts/status/check-all-mainnet-required-pool-balances.mjs --update-matrix

Only use --update-matrix after reviewing the report. It promotes rows with live code and non-zero base/quote balances to live_read; it does not create, fund, or canary pools.

Phase 2: Fund and Canary

Funding should move in tiers, not straight to production.

Use each row's fundingTiersUsd:

• seed: proves transferability and reserve reads
• smoke: proves route quoteability and tiny swaps
• productionMinimum: minimum operating reserve before promotion

After funding, run:

node scripts/status/check-all-mainnet-required-pool-balances.mjs
node scripts/status/preflight-all-mainnet-canaries.mjs

Record successful canaries with:

node scripts/status/record-all-mainnet-canary-evidence.mjs

Promotion rule:

• planned -> create/import pool
• created -> fund both sides
• live_read -> canary both directions where applicable
• canary_passed -> operator review
• production -> public route eligible

Phase 3: Auto-Rebalancing

Auto-rebalancing should be conservative and evidence driven. It should not be allowed to create new exposure on rows that have not passed the production gate.

Minimum policy per row:

{
  "maxPriceImpactBps": 100,
  "minReserveUsd": 1000,
  "refillTriggerBps": 200,
  "pauseOnReserveReadFailure": true
}

Implementation shape:

1. Watch only rows with requiredForSpend: true and status live_read, canary_passed, or production.
2. Read live base/quote balances using check-all-mainnet-required-pool-balances.mjs.
3. Convert reserves to oracle ISO value using the same ISO peg rules used by scripts/verify/build-cw-public-price-table.py.
4. If either side is below minReserveUsd or outside refillTriggerBps, generate a rebalance intent.
5. Execute only after dry-run quote checks pass and maxPriceImpactBps is respected.
6. Record every action back into a report before changing matrix status.

Recommended first automation artifact:

scripts/status/plan-all-mainnet-rebalance.mjs

It should be read-only by default and write:

reports/status/all-mainnet-rebalance-plan-latest.json

The read-only planner is available now:

node scripts/status/plan-all-mainnet-rebalance.mjs

Only after that report is stable should an execution wrapper be added, for example:

scripts/deployment/execute-all-mainnet-rebalance.mjs

The execution wrapper must require an explicit --execute flag.

Phase 4: Enable All Protocols

Protocol enablement must follow native-liquidity order. Aggregators come last.

1. DODO PMM: Finish required DODO and single-sided PMM rows first. Keep DODO as the default router provider until other providers pass canaries.
2. Uniswap V2: Promote committed V2 rows with live reserve reads and canaries. Add the remaining planned V2 pool address or mark it explicitly deferred.
3. Uniswap V3: Keep the standalone V3 route recorded, but do not enable the enhanced-router V3 provider until the adapter quote incompatibility is fixed and canary evidence exists through the enhanced router path.
4. Balancer / Curve / Sushi: Import or deploy canonical factories, routers/vaults, pools, and pool IDs. Add addresses to the pool matrix before funding. No route generation from config-only rows.
5. 1inch: Enable only after DODO plus at least one native venue for the same pair is live. 1inch rows are aggregator-only and must not be the first source of liquidity truth.
6. Aave backstop: Treat as a reserve/backstop surface, not a swap venue. Enable after token markets, oracle config, caps, and pause controls are committed.

After each protocol wave:

bash scripts/verify/check-allmainnet-protocol-surface.sh
node scripts/status/generate-all-mainnet-readiness.mjs
bash scripts/validation/validate-config-files.sh

Production Gate

A row can become public-route eligible only when all of these are true:

• Real token addresses
• Real pool address with bytecode
• Required vault assignments complete
• Non-zero base and quote reserves
• Canary evidence recorded
• Route quote check passes
• Protocol surface has the provider enabled
• Status is production

The whole ALL Mainnet same-chain surface is production-ready only when:

jq -e '.status == "production_ready"' reports/status/all-mainnet-production-gate-latest.json

Until then, keep public routing constrained to canary-passed rows and explicitly disabled historical rows out of route generation.