bea1903ac9
Some checks failed
Deploy to Phoenix / deploy (push) Has been cancelled
Co-authored-by: Cursor <cursoragent@cursor.com>
208 lines
8.8 KiB
Markdown
208 lines
8.8 KiB
Markdown
# 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](../../smom-dbis-138/docs/operations/LIQUIDITY_PROVIDER_GUIDE.md)
|
||
|
||
### 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](../../smom-dbis-138/docs/integration/DODO_PMM_INTEGRATION.md). For L2s: [CUSDT_CUSDC_MULTICHAIN_LIQUIDITY_RUNBOOK](../../smom-dbis-138/docs/deployment/CUSDT_CUSDC_MULTICHAIN_LIQUIDITY_RUNBOOK.md). |
|
||
|
||
---
|
||
|
||
## 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](../../smom-dbis-138/docs/deployment/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](../../smom-dbis-138/docs/operations/LIQUIDITY_PROVIDER_GUIDE.md)
|
||
- [DODO_PMM_INTEGRATION.md](../../smom-dbis-138/docs/integration/DODO_PMM_INTEGRATION.md)
|
||
- [bridge/trustless/LIQUIDITY_POOL_ECONOMICS.md](../../smom-dbis-138/docs/bridge/trustless/LIQUIDITY_POOL_ECONOMICS.md)
|
||
- [CUSDT_CUSDC_MULTICHAIN_LIQUIDITY_RUNBOOK.md](../../smom-dbis-138/docs/deployment/CUSDT_CUSDC_MULTICHAIN_LIQUIDITY_RUNBOOK.md)
|
||
- [OPTIONAL_FUTURE_DEPLOYMENTS_RUNBOOK.md](OPTIONAL_FUTURE_DEPLOYMENTS_RUNBOOK.md)
|