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`).

The matrix now includes the full GRU Wave 1 wrapped set:

- `cWEURC`
- `cWEURT`
- `cWGBPC`
- `cWGBPT`
- `cWAUDC`
- `cWJPYC`
- `cWCHFC`
- `cWCADC`
- `cWXAUC`
- `cWXAUT`

This is a design / deployment queue update, not proof that those pools are live.

---

## 3. Prerequisites per chain

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

---

## 4. Steps per chain (checklist)

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

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

---

## 5. Script stub: list pools to create

From repo root, run:

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

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

For the GRU-specific operator queue, use:

```bash
bash scripts/verify/check-gru-v2-deployment-queue.sh
```

---

## 6. Deployment status and MCP allowlist source

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

---

## 7. References

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