e4c9dda0fd
Some checks failed
Deploy to Phoenix / deploy (push) Has been cancelled
- Marked submodules ai-mcp-pmm-controller, explorer-monorepo, and smom-dbis-138 as dirty to reflect recent changes. - Updated documentation to clarify operator script usage, including dotenv loading and task execution instructions. - Enhanced the README and various index files to provide clearer navigation and task completion guidance. Made-with: Cursor
15 KiB
15 KiB
MCP and AI Plan Upgrades — Dodoex and Uniswap Liquidity Pool Management
Purpose: Upgrades to the PMM full-mesh and single-sided LP plans so that MCPs and AIs dedicated to managing and maintaining all Dodoex (DODO PMM) and Uniswap liquidity pools are explicitly covered and operational.
Status: All planned upgrades (§2) and all additional recommendations (§5) are implemented. See §4 and §5.1 for implementation details. Optional tasks index: OPTIONAL_TASKS_CHECKLIST.md.
Related: PMM_FULL_MESH_AND_PUBLIC_SINGLE_SIDED_PLAN.md, AI_AGENTS_57XX_MCP_CONTRACTS_AND_CHAINS.md, POOL_ACCESS_DASHBOARD_API_MCP.md.
1. Current state (what plans already assume)
| Component | Role | Plan coverage today |
|---|---|---|
| ai-mcp-pmm-controller | Read pool state (getMidPrice, reserves, k, fee); optional quote/add/remove liquidity | Allowlist per chain; one chain per MCP instance; profile dodo_pmm_v2_like for Chain 138 Mock DVM |
| Token-aggregation API | Index DODO (and Uniswap when env set); single-hop quote; tokens/pools discovery | Chain 138 + optional public chains via CHAIN_*_DODO_PMM_INTEGRATION, CHAIN_*_RPC_URL |
| cross-chain-pmm-lps bot | Deviation watcher; buy/sell to compress δ; inventory adjust; circuit break | Design only; not wired to MCP or API for automation |
| EnhancedSwapRouter | Multi-provider routing (Dodoex, Uniswap, Balancer, Curve) | Not deployed; no MCP/API integration specified |
2. Upgrades to the plans
2.1 Full-mesh and single-sided plans (PMM_FULL_MESH_AND_PUBLIC_SINGLE_SIDED_PLAN)
| Upgrade | Description |
|---|---|
| Allowlist sync with mesh | After running create-pmm-full-mesh-chain138.sh, automatically or semi-automatically update the MCP allowlist (e.g. ai-mcp-pmm-controller/config/allowlist-138.json) with every new pool (pool_address, base_token, quote_token, profile). Document a script or MCP tool that: (1) reads DODOPMMIntegration.getAllPools() and getPoolConfig(pool) on Chain 138, (2) writes the allowlist so the MCP can read state for all mesh pools without manual entry. |
| Per-chain allowlist for public cW pools* | When single-sided cW* / HUB pools are deployed on a public chain, extend the plan to: (1) add a per-chain MCP allowlist (or multi-chain allowlist) so the dedicated MCP/AI can read pool state on that chain; (2) document the mapping from cross-chain-pmm-lps/config/deployment-status.json (and pool-matrix) to the MCP config so one source of truth drives both deployment and MCP visibility. |
| Uniswap pool indexing and maintenance | Where the plan says "DODO PMM or Uniswap V2/V3 per chain": (1) add an explicit Uniswap pool creation and indexing path: set CHAIN_*_UNISWAP_V2_FACTORY / CHAIN_*_UNISWAP_V3_FACTORY and run the token-aggregation indexer so Uniswap pools appear in the API; (2) add a maintenance subsection: who (or which AI/MCP) is responsible for adding liquidity, rebalancing, or pausing on Uniswap pools on each chain; (3) if an AI/MCP is dedicated to Uniswap pools, define its inputs (API quote, pool state from indexer or RPC) and allowed actions (e.g. quote only vs. submit tx). |
| Bot–MCP–API integration | In the single-sided plan (and cross-chain-pmm-lps): (1) specify that the deviation bot (v1/v2) can consume pool state from the MCP (e.g. dodo.get_pool_state for each allowlisted pool) or from the token-aggregation API (e.g. /api/v1/tokens/:address/pools, reserve/price from indexer); (2) specify that the bot’s actions (e.g. trigger buy/sell to compress δ) are either executed by the same AI that uses the MCP or by a separate executor that receives signals from the MCP/AI; (3) add circuit-break and cooldown to the MCP/API so the AI can read "pool in CIRCUIT_BREAK" or "cooldown until block X" and avoid sending trades. |
| Dedicated “pool manager” MCP/AI scope | Add a short subsection: Dedicated MCP/AI for Dodoex and Uniswap pool management. Scope: (1) Dodoex (Chain 138 + public cW):* MCP tools for read state, quote add/remove liquidity; allowlist kept in sync with full mesh and single-sided deployments; (2) Uniswap (per chain where used): Same idea—allowlist or indexer-driven list of Uniswap V2/V3 pools; MCP or API to read pool state and optionally quote; (3) Maintenance tasks: Document that this MCP/AI is the designated reader (and optionally executor) for rebalancing, add/remove liquidity, and responding to deviation alerts within policy (slippage, size, circuit break). |
2.2 RUNBOOK and script upgrades (SINGLE_SIDED_LPS_PUBLIC_NETWORKS_RUNBOOK)
| Upgrade | Description |
|---|---|
| Post-deploy: update MCP allowlist | In the runbook checklist, add a step: "After deploying cW* / HUB pools on chain X, update the MCP allowlist for chain X (or the multi-chain config) with pool_address, base_token, quote_token, and profile so the dedicated MCP/AI can read and manage those pools." |
| Post-deploy: update deployment-status.json | Already implied; make it explicit that deployment-status.json is the source for MCP allowlist generation (script: given chainId, read deployment-status and output allowlist fragment). |
| List Uniswap pools per chain | If Uniswap is used on a chain, add a step to list Uniswap V2/V3 pools (from factory events or indexer) and add them to the same MCP/API visibility (allowlist or indexer config) so one MCP/AI can "see" both DODO and Uniswap pools. |
2.3 AI_AGENTS_57XX and POOL_ACCESS_DASHBOARD_API_MCP
| Upgrade | Description |
|---|---|
| Multi-chain MCP | Document an option for one MCP server that supports multiple chains: e.g. allowlist contains chainId per pool, and the MCP uses the appropriate RPC per chain when calling get_pool_state or quote_add_liquidity. This reduces the need to run one MCP instance per chain for Dodoex + Uniswap. |
| Uniswap pool profile | Add a pool profile (e.g. uniswap_v2_pair or uniswap_v3_pool) to the MCP: expected view methods (getReserves, token0, token1, or slot0, liquidity, etc.) so the MCP can read Uniswap pool state and expose it to the same AI that manages DODO pools. |
| Dashboard and API alignment | State that the token-aggregation API and the MCP should expose the same set of pools for a given chain (DODO + Uniswap once indexed): so the "custom dashboard" and the MCP/AI use one source of truth (allowlist + indexer config) and stay in sync. |
| Automation triggers | Document how the dedicated AI is triggered: (1) Scheduled: cron or scheduler calls MCP/API to get state, then decides rebalance/add/remove; (2) Event-driven: indexer or chain watcher emits "reserve delta" or "price deviation" and triggers the AI; (3) Manual: operator asks the AI (via MCP) for a quote or recommendation, then executes manually. |
3. Summary: what to add to the “above” plans
- PMM_FULL_MESH_AND_PUBLIC_SINGLE_SIDED_PLAN: Allowlist sync with full mesh; per-chain allowlist for cW*; Uniswap indexing and maintenance; bot–MCP–API integration; dedicated MCP/AI scope for Dodoex + Uniswap.
- SINGLE_SIDED_LPS_PUBLIC_NETWORKS_RUNBOOK: Post-deploy MCP allowlist update; deployment-status as source for allowlist; Uniswap pool listing where applicable.
- AI_AGENTS_57XX / POOL_ACCESS: Multi-chain MCP option; Uniswap pool profile; dashboard/API alignment; automation triggers (scheduled, event-driven, manual).
4. Completed upgrades (implemented)
| Upgrade | Status | Implementation |
|---|---|---|
| Allowlist sync with mesh | Done | Script scripts/generate-mcp-allowlist-from-chain138.sh: reads allPools(uint256) and poolConfigs(pool) via RPC; outputs allowlist JSON. Use -o ai-mcp-pmm-controller/config/allowlist-138.json to write. Documented in PMM plan §1.5. |
| Per-chain allowlist from deployment-status | Done | Script scripts/generate-mcp-allowlist-from-deployment-status.sh <chain_id> [-o path]: reads deployment-status.json pmmPools for that chain; outputs allowlist fragment with limits. Documented in SINGLE_SIDED runbook §5a, §6. |
| Post-deploy MCP allowlist step | Done | Runbook §5a: run generate-mcp-allowlist-from-deployment-status.sh after deploying cW* / HUB pools. |
| deployment-status as source for allowlist | Done | Runbook §6: explicit that deployment-status.json is source of truth; script generates allowlist from it. |
| Uniswap pool listing / indexing step | Done | Runbook §6a: set CHAIN_UNISWAP env, run indexer; add Uniswap pools to MCP allowlist with profile when available. |
| Uniswap pool profile | Done | Added uniswap_v2_pair and uniswap_v3_pool to ai-mcp-pmm-controller/config/pool_profiles.json with expected methods. MCP server must implement reading these methods when profile is used. |
| PMM plan: Uniswap, Bot–MCP, Pool Manager | Done | Plan §2.7 (Uniswap indexing and maintenance), §2.8 (Bot–MCP–API integration), §2.9 (Dedicated MCP/AI scope); §1.5 (Allowlist sync with mesh). |
| Multi-chain MCP, dashboard alignment, automation | Done | AI_AGENTS_57XX_MCP_ADDENDUM.md: multi-chain allowlist/RPC, Uniswap profile reference, dashboard/API alignment, automation triggers (scheduled, event-driven, manual). |
5. Additional recommendations
| # | Recommendation | Priority | Notes |
|---|---|---|---|
| 1 | Implement multi-chain allowlist in MCP server | High | Extend ai-mcp-pmm-controller to accept chainId per pool and select RPC by chain so one server can serve Chain 138 and all public cW* chains. |
| 2 | Wire MCP get_pool_state to Uniswap profiles | High | In the MCP tool implementation, when profile is uniswap_v2_pair or uniswap_v3_pool, call getReserves/slot0/liquidity and return normalized state (reserves, derived price) for the AI. |
| 3 | Expose circuit-break and cooldown in API or MCP | Medium | Add an endpoint or MCP tool that returns bot state (IDLE, ABOVE_BAND, BELOW_BAND, COOLDOWN, CIRCUIT_BREAK) and cooldown-until block/time so the AI does not submit trades during cooldown or circuit-break. Source: cross-chain-pmm-lps peg-bands and bot state. |
| 4 | Event-driven trigger for bot/AI | Medium | When token-aggregation indexer or a chain watcher detects reserve delta or price deviation beyond a threshold, emit an event or call a webhook that triggers the dedicated AI to fetch state (via MCP/API) and decide rebalance; keeps reaction time low without polling. |
| 5 | Single allowlist file for multi-chain | Low | Allow one JSON file to contain pools for multiple chains (array of { chainId, pools }) so the MCP can load one file and serve all chains; merge output of generate-mcp-allowlist-from-chain138.sh and generate-mcp-allowlist-from-deployment-status.sh per chain into one manifest. |
| 6 | Rate limits and gas caps in MCP | Medium | Enforce allowlist limits (max_slippage_bps, max_single_tx_notional_usd, cooldown_seconds, gas_cap_gwei) in the MCP server when the AI requests quote or execute; reject or cap out-of-policy requests. |
| 7 | Audit trail for AI-driven txs | Medium | Log all MCP tool calls (get_pool_state, quote_add_liquidity, add_liquidity, etc.) and any executed txs (tx hash, pool, amount, chain) for audit and incident review. |
| 8 | EnhancedSwapRouter integration with MCP | Low | When EnhancedSwapRouter is deployed on Chain 138, add it to the MCP/API so the AI can reason about multi-provider routing (Dodoex vs Uniswap vs Balancer) and optionally trigger swaps through the router. |
5.1 Implementation status (all completed)
| # | Implementation |
|---|---|
| 1 | Multi-chain allowlist: config/server.py supports allowlist format chains: [ { chainId, pools } ] and per-pool chain_id. RPC per chain via env RPC_138, RPC_137, etc. or RPC_BY_CHAIN_PATH (JSON file). _get_web3(chain_id) caches Web3 per chain. |
| 2 | Uniswap get_pool_state: In dodo_get_pool_state, profiles uniswap_v2_pair and uniswap_v3_pool use getReserves/slot0/liquidity; return normalized state (reserves, mid_price, liquidity_base/quote). |
| 3 | Circuit-break and cooldown: GET /bot_state and MCP tool dodo.get_bot_state return bot state from BOT_STATE_PATH (JSON). Example: config/bot_state.example.json. Optional params.pool for per-pool state. |
| 4 | Event-driven trigger: POST /webhook/trigger accepts JSON body { "reason", "chain_id", "pool" }; returns 202 and logs. Wire indexer/watcher to POST here; AI can poll MCP or react to webhook. |
| 5 | Single multi-chain allowlist: Allowlist format supports chains: [ { chainId, pools } ]. Script scripts/merge-mcp-allowlist-multichain.sh -o path merges Chain 138 and other chains into one file. |
| 6 | Rate limits and gas caps: _check_limits_and_cooldown() enforces notional, cooldown_seconds (via COOLDOWN_STATE_PATH), gas_cap_gwei, max_slippage_bps. Used in dodo_simulate_action; use _record_trade_ts(pool) after writes. |
| 7 | Audit trail: Every MCP tool response goes through _audit_and_return(); logs to AUDIT_LOG_PATH (JSONL) and logger. |
| 8 | EnhancedSwapRouter stub: MCP tool dodo.get_router_quote returns configured: true/false from ENHANCED_SWAP_ROUTER_ADDRESS. Add contract calls when router is deployed. |
6. Next steps (operator / runtime)
After implementation, operators can:
- Multi-chain MCP: Set
ALLOWLIST_PATHto a multi-chain file (fromscripts/merge-mcp-allowlist-multichain.sh -o path); setRPC_138,RPC_137, etc. orRPC_BY_CHAIN_PATH. - Bot state: Set
BOT_STATE_PATHto a JSON file (seeai-mcp-pmm-controller/config/bot_state.example.json); update it from your peg-bands/bot or leave default. - Audit / cooldown: Set
AUDIT_LOG_PATHandCOOLDOWN_STATE_PATHif you want persistent audit log and cooldown ledger. - Webhook: Wire your indexer or chain watcher to
POST /webhook/triggerwith{ "reason", "chain_id", "pool" }when reserve or price deviation exceeds threshold. - EnhancedSwapRouter: When the router is deployed on Chain 138, set
ENHANCED_SWAP_ROUTER_ADDRESSand extenddodo.get_router_quotein the MCP server to call the router contract.
7. References
- PMM_FULL_MESH_AND_PUBLIC_SINGLE_SIDED_PLAN.md
- SINGLE_SIDED_LPS_PUBLIC_NETWORKS_RUNBOOK.md
- AI_AGENTS_57XX_MCP_CONTRACTS_AND_CHAINS.md
- AI_AGENTS_57XX_DEPLOYMENT_PLAN.md
- POOL_ACCESS_DASHBOARD_API_MCP.md
- DEX_AND_AGGREGATORS_CHAIN138_EXPLAINER.md
- DEFI_AGGREGATOR_DEX_ROUTING_FLOWS_DIAGRAM.md — Mermaid diagram of all DeFi aggregator and DEX routing flows for swaps
- AI_AGENTS_57XX_MCP_ADDENDUM.md — Multi-chain MCP, Uniswap profile, automation triggers
- OPTIONAL_TASKS_CHECKLIST.md — Consolidated optional tasks (Done / Pending)