proxmox/docs/03-deployment/LIQUIDITY_POOL_CONTROLS_RUNBOOK.md

Liquidity Pool Controls — Runbook

Last Updated: 2026-02-16
Status: Reference — operator guide for all liquidity pool controls

---

Overview

Liquidity pools in this project span multiple systems:

System	Contracts	Purpose
Trustless Bridge	LiquidityPoolETH	ETH/WETH liquidity for bridge releases
DODO / DEX	DODOPMMIntegration, PrivatePoolRegistry	cUSDT/cUSDC pools; XAU-anchored pools
Liquidity Manager	LiquidityManager, PoolManager	Provider routing; pool registration; asset config
Bridge Reserve	BridgeReserveCoordinator	Reserve coordination across pools

---

1. Trustless Bridge — LiquidityPoolETH

Contract: contracts/bridge/trustless/LiquidityPoolETH.sol
Ref: LIQUIDITY_PROVIDER_GUIDE

Controls

Action	Function	Role / Access
Provide ETH liquidity	provideLiquidity{value: amount}(AssetType.ETH)	Any address
Deposit WETH	depositWETH(amount)	Any address
Withdraw liquidity	withdrawLiquidity(amount, assetType)	LP share holder
Authorize release	authorizeRelease(address)	DEFAULT_ADMIN_ROLE
Set LP fee	Constructor / config	At deploy
Set min liquidity ratio	Constructor (e.g. 11000 bps = 110%)	At deploy

Admin Tasks

• Grant DEFAULT_ADMIN_ROLE to operators
• Authorize InboxETH to call release() for bridge claims
• Monitor getAvailableLiquidity(), getPoolStats() — ensure ratio ≥ 110%

---

2. DODO / DEX — DODOPMMIntegration

Contract: contracts/dex/DODOPMMIntegration.sol
Script: script/dex/DeployDODOPMMIntegration.s.sol

Controls

Action	Function	Role
Create cUSDT/USDT pool	createCUSDTUSDTPool(...)	POOL_MANAGER_ROLE
Create cUSDC/USDC pool	createCUSDCUSDCPool(...)	POOL_MANAGER_ROLE
Create cUSDT/cUSDC pool	createCUSDTCUSDCPool(...)	POOL_MANAGER_ROLE
Create generic pool	createPool(baseToken, quoteToken, ...)	POOL_MANAGER_ROLE
Add liquidity	addLiquidity(pool, baseAmount, quoteAmount)	Pool owner / approved
Register pool	registerPool(pool)	POOL_MANAGER_ROLE
Swap cUSDT↔USDT	swapCUSDTForUSDT, swapUSDTForCUSDT	Any
Swap cUSDC↔USDC	swapCUSDCForUSDC, swapUSDCForCUSDC	Any
Swap cUSDT↔cUSDC	swapCUSDTForCUSDC, swapUSDCForCUSDT	Any

Admin Tasks

• Grant POOL_MANAGER_ROLE to operators and DODOPMMProvider
• Create pools for cUSDT/USDT, cUSDC/USDC, cUSDT/cUSDC
• Add initial liquidity and configure lpFeeRate, k, initialPrice per pool
• Register pools in PrivatePoolRegistry if using PrivatePoolRegistry

---

3. PrivatePoolRegistry

Contract: contracts/dex/PrivatePoolRegistry.sol
Script: script/dex/DeployPrivatePoolRegistryAndPools.s.sol

Controls

Action	Function	Role
Register pool	registerPool(poolAddress, ...)	Registry admin
Add pool to registry	Used by DODOPMMIntegration.addLiquidity flow	Per runbook

---

4. PoolManager (Universal Asset Registry integration)

Contract: contracts/liquidity/PoolManager.sol

Controls

Action	Function	Role
Register existing pool	registerPool(pool, provider, tokenA, tokenB, liquidityUSD)	POOL_ADMIN_ROLE
Update pool liquidity	updatePoolLiquidity(pool, liquidityUSD)	POOL_ADMIN_ROLE
Set providers	setProviders(dodoProvider, uniswapV3Provider, curveProvider)	DEFAULT_ADMIN_ROLE
Check pool health	checkPoolHealth(pool)	View

Admin Tasks

• Grant POOL_ADMIN_ROLE to operators
• Set DODO, Uniswap V3, Curve provider addresses
• Register pools after deployment; update liquidity periodically

---

5. LiquidityManager

Contract: contracts/liquidity/LiquidityManager.sol

Controls

Action	Function	Role
Add provider	addProvider(provider, priority)	LIQUIDITY_ADMIN_ROLE
Remove provider	removeProvider(provider)	LIQUIDITY_ADMIN_ROLE
Configure asset	configureAsset(token, minAmountForPMM, maxSlippageBps, timeout, autoCreate, enabled)	LIQUIDITY_ADMIN_ROLE

Admin Tasks

• Grant LIQUIDITY_ADMIN_ROLE to operators
• Add DODOPMMProvider, other ILiquidityProvider impls
• Configure per-asset: minAmountForPMM, maxSlippageBps, timeout, autoCreate, enabled

---

6. DODOPMMProvider

Contract: contracts/liquidity/providers/DODOPMMProvider.sol
Depends: DODOPMMIntegration

Controls

Action	Function	Role
Create pool (via integration)	createOptimalPool(tokenIn, tokenOut, ...)	DODOPMMIntegration.POOL_MANAGER_ROLE
Get quote	getQuote(tokenIn, tokenOut, amountIn)	View
Execute swap	executeSwap(tokenIn, tokenOut, amountIn, minAmountOut)	Caller (bridge/orchestration)

---

7. Liquidity Pool Funding Summary

Pool / system	Status	How to fund
CCIP WETH9 / WETH10 (Chain 138)	✅ Funded	Deployer needs LINK; transfer to bridge addresses. Example: cast send $LINK "transfer(address,uint256)" $WETH9_BRIDGE $(cast --to-wei 10 ether) --rpc-url $RPC_URL_138 --private-key $PRIVATE_KEY --gas-limit 100000 --gas-price 1000000000. Recommended: 10 LINK per bridge. Mint LINK first: ./scripts/mint-tokens-for-deployer.sh --amount-link=50000.
Trustless LiquidityPoolETH (Mainnet)	✅ Unblocked	ETHEREUM_MAINNET_RPC set to https://ethereum.publicnode.com; Mainnet contracts deployed (see *_MAINNET in smom-dbis-138/.env). Run: smom-dbis-138/scripts/deployment/phase6-provide-liquidity.sh. Env: LIQUIDITY_POOL (or LIQUIDITY_POOL_ETH_MAINNET), RESERVE_SYSTEM, ETHEREUM_MAINNET_RPC, LIQUIDITY_AMOUNT (ETH), RESERVE_AMOUNT (USDT).
DODO PMM (Chain 138)	✅ Mock DVM deployed	DODOPMMIntegration at DODO_PMM_INTEGRATION_ADDRESS; create pools via createCUSDTUSDTPool, createCUSDCUSDCPool; add liquidity via addLiquidity(pool, baseAmount, quoteAmount). See DODO_PMM_INTEGRATION. For L2s: CUSDT_CUSDC_MULTICHAIN_LIQUIDITY_RUNBOOK.

---

8. Liquidity Pool Controls Checklist

Post-Deploy (DODO)

1. Deploy DODOPMMIntegration
2. Grant POOL_MANAGER_ROLE to admin and DODOPMMProvider
3. Create pools: cUSDT/USDT, cUSDC/USDC, cUSDT/cUSDC
4. Add initial liquidity
5. Register pools in PoolManager and/or PrivatePoolRegistry

Post-Deploy (Trustless Bridge)

1. Deploy LiquidityPoolETH
2. Authorize InboxETH to release
3. LPs call provideLiquidity/depositWETH
4. Monitor ratio; block withdrawals if below 110%

Ongoing

Task	Frequency	Command / Action
Update pool liquidity (PoolManager)	Daily / on events	updatePoolLiquidity(pool, liquidityUSD)
Check pool health	Daily	checkPoolHealth(pool)
Monitor trustless bridge ratio	Continuous	getPoolStats(); alert if < 110%
Configure new assets (LiquidityManager)	As needed	configureAsset(...)
Add/remove providers	As needed	addProvider, removeProvider

---

9. Integration with Token Aggregation

The token-aggregation service reads pool data from DB (PoolRepository) and reports via CMC/CoinGecko endpoints. Pool data can be:

• Populated by indexer (on-chain events)
• Synced manually or via cron from PoolManager / DODO pools
• Stored in pool_repo table; token-aggregation serves /report/cmc, /report/coingecko

---

10. Multi-Chain Deployment (cUSDT/cUSDC, Uniswap, Balancer, Curve)

For deploying cUSDT/cUSDC to other chains (BSC, Polygon, Base, etc.), creating Dodo PMM on L2s, and adding Uniswap V3, Balancer, and Curve pools:

• CUSDT_CUSDC_MULTICHAIN_LIQUIDITY_RUNBOOK.md — Full runbook: Phase 1 deploy tokens per chain, Phase 2 Dodo PMM (L2s), Phase 3 Uniswap (helper script create-uniswap-v3-pool-cusdt-cusdc.sh), Phase 4–5 Balancer/Curve, Phase 6 other protocols.
• Scripts: smom-dbis-138/scripts/deployment/deploy-cusdt-cusdc-all-chains.sh, deploy-pmm-all-l2s.sh, create-uniswap-v3-pool-cusdt-cusdc.sh.

---

References

• LIQUIDITY_PROVIDER_GUIDE
• DODO_PMM_INTEGRATION.md
• bridge/trustless/LIQUIDITY_POOL_ECONOMICS.md
• CUSDT_CUSDC_MULTICHAIN_LIQUIDITY_RUNBOOK.md
• OPTIONAL_FUTURE_DEPLOYMENTS_RUNBOOK.md