proxmox/docs/03-deployment/SINGLE_SIDED_LPS_PUBLIC_NETWORKS_RUNBOOK.md

Single-Sided LPs on Public Networks — Runbook (Aggregator and DEX Routing)

Purpose: Deploy cW / HUB* single-sided PMM (or AMM) pools on each public chain so aggregators and DEX routing can use them.

---

1. What to deploy

On each public chain:

• Pool type: One pool per cW* token against the chain’s hub stable (USDC or USDT).
• Single-sided: Liquidity is provided on the cW* side; the other side is filled by market/arbitrage (and optionally by a bot).
• Use case: Aggregator and DEX routing (1inch, 0x, ParaSwap, swap–bridge–swap, etc.) so that cW* ↔ USDC/USDT is routable on each chain.

---

2. Per-chain config (pool-matrix)

The source of truth is cross-chain-pmm-lps/config/pool-matrix.json:

• chains[chainId].hubStable: USDC or USDT for that chain.
• chains[chainId].poolsFirst: List of pools to deploy first (e.g. cWUSDT/USDC, cWUSDC/USDC, …).
• chains[chainId].poolsOptional: Optional extra quote stables (e.g. cWUSDT/USDT, cWUSDT/DAI).

---

3. Prerequisites per chain

1. cW tokens deployed* on that chain (addresses in .env or in cross-chain-pmm-lps/config/deployment-status.json).
2. Hub stable address (USDC or USDT) on that chain (from chain list or explorer).
3. DEX/factory on that chain:
   • DODO-style: DVM or PMM factory.
   • Uniswap V2: factory + router.
   • Uniswap V3: factory + NonfungiblePositionManager (or equivalent).
4. RPC URL and deployer key (or LP provider key) for that chain.

---

4. Steps per chain (checklist)

For each chain (e.g. 1, 56, 137, 10, 100, 25, 42161, 8453, 43114, 42220, 1111):

• 1. Set CW*_<CHAIN> and *_RPC (e.g. CWUSDT_MAINNET, ETHEREUM_MAINNET_RPC) in .env.
• 2. Resolve hub stable address (e.g. USDC on Ethereum: 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48).
• 3. Choose DEX: DODO PMM vs Uniswap V2 vs Uniswap V3 (per chain).
• 4. For each pair in poolsFirst (e.g. cWUSDT/USDC):
  • Create pool (factory.createPair or DVM.createDVM or V3 factory.createPool).
  • Add single-sided liquidity on the cW* side (or both sides with a 1:1 target).
• 5. Record pool address in cross-chain-pmm-lps/config/deployment-status.json under chains[chainId].pmmPools (each entry: base, quote, poolAddress or base_token, quote_token, pool_address).
• 5a. Update MCP allowlist for this chain: Run ./scripts/generate-mcp-allowlist-from-deployment-status.sh <chain_id> -o ai-mcp-pmm-controller/config/allowlist-<chain_id>.json (or merge into a multi-chain allowlist). So the dedicated MCP/AI can read and manage these pools. See MCP_AI_POOL_MANAGEMENT_PLAN_UPGRADES.md.
• 6. Register pool in token-aggregation API / indexer so quote and routing use it (set CHAIN_*_DODO_PMM_INTEGRATION or Uniswap factory env for that chain and run indexer).
• 6a. Uniswap (if used on this chain): List Uniswap V2/V3 pools (from factory events or indexer) and add them to the same MCP/API visibility: set CHAIN_*_UNISWAP_V2_FACTORY / CHAIN_*_UNISWAP_V3_FACTORY and run indexer; add Uniswap pools to MCP allowlist with profile uniswap_v2_pair or uniswap_v3_pool when that profile is available. See MCP_AI_POOL_MANAGEMENT_PLAN_UPGRADES.md §2.3.
• 7. (Optional) Enable bot for that chain (deviation watcher, rebalance). Bot can consume pool state from MCP or token-aggregation API; see plan upgrades § Bot–MCP–API integration.

---

5. Script stub: list pools to create

From repo root, run:

./scripts/list-single-sided-pools-by-chain.sh

This script reads cross-chain-pmm-lps/config/pool-matrix.json and prints, per chain, the list of cW / HUB* pools to create (and optional pools). Use the output to drive deployment (manual or via a deploy script that calls the appropriate factory on each chain).

---

6. Deployment status and MCP allowlist source

• Config: cross-chain-pmm-lps/config/deployment-status.json
• Fill for each chain:
  • cwTokens: e.g. { "cWUSDT": "0x...", "cWUSDC": "0x..." }
  • anchorAddresses: e.g. { "USDC": "0x...", "USDT": "0x..." }
  • pmmPools: array of { "base", "quote", "poolAddress", "feeBps", "k", ... } (or base_token, quote_token, pool_address)
• MCP allowlist generation: deployment-status.json is the source of truth for generating the MCP allowlist per chain. Run ./scripts/generate-mcp-allowlist-from-deployment-status.sh <chain_id> [-o path] to produce an allowlist fragment (pool_address, base_token, quote_token, profile) so the MCP/AI can read pool state on that chain.

---

7. References

• PMM_FULL_MESH_AND_PUBLIC_SINGLE_SIDED_PLAN.md — Overall plan (Chain 138 mesh + public single-sided).
• MCP_AI_POOL_MANAGEMENT_PLAN_UPGRADES.md — MCP/AI upgrades, allowlist sync, Uniswap, bot integration.
• cross-chain-pmm-lps/docs/02-pool-topology.md — Pool topology.
• cross-chain-pmm-lps/docs/06-deployment-recipe.md — Recipe and bot.
• PMM_DEX_ROUTING_STATUS.md — Routing status.