proxmox/docs/03-deployment/DEFI_AGGREGATOR_DEX_ROUTING_FLOWS_DIAGRAM.md

DeFi Aggregator and DEX Routing Flows — Visual Reference

Purpose: Single diagram of all DeFi aggregator and DEX routing flows for swaps (Chain 138, public chains, bridge, MCP/AI, and bots).

---

Full flow diagram (Mermaid)

flowchart TB
  subgraph Users["Entry points"]
    U1["User / Frontend / dApp"]
    U2["Swap–bridge–swap orchestrator"]
    U3["MCP / AI (pool management)"]
    U4["Deviation bot (cW* peg)"]
  end

  subgraph Aggregators["Aggregator & quote layer"]
    direction TB
    TA["Token-aggregation API<br/>GET /quote, /tokens, /tokens/:addr/pools<br/>Single-hop quote; indexes DODO + Uniswap"]
    BQ["Bridge quote API<br/>POST /api/bridge/quote<br/>sourceSwapQuote + bridge + destinationSwapQuote"]
    EXT["External aggregators<br/>1inch, 0x, ParaSwap<br/>(Chain 138 not supported until they add it)"]
    BA["Bridge aggregator (explorer backend)<br/>Li.Fi, Socket, Squid, Symbiosis, Relay, Stargate<br/>Bridge routes only"]
  end

  subgraph Chain138["Chain 138 (SMOM-DBIS-138)"]
    direction TB
    INT["DODOPMMIntegration<br/>createPool, addLiquidity, swapExactIn<br/>swapCUSDTForUSDC, swapCUSDTForUSDT, ..."]
    PROV["DODOPMMProvider<br/>getQuote, executeSwap<br/>registerPool; routes to integration"]
    MESH["Full mesh: 66 c* vs c* pools<br/>+ c* vs official USDT/USDC<br/>All routable via swapExactIn"]
    POOLS138["Pools: cUSDT/cUSDC, cUSDT/USDT, cUSDC/USDC<br/>+ full mesh when create-pmm-full-mesh-chain138.sh run"]
    INT --> POOLS138
    PROV --> INT
    MESH --> INT
  end

  subgraph PublicChains["Public chains (1, 56, 137, 10, 100, 25, 42161, 8453, 43114, 42220, 1111)"]
    direction TB
    CW["cW* / HUB single-sided pools<br/>cWUSDT/USDC, cWUSDC/USDC, ...<br/>Per pool-matrix.json"]
    DEX["Native DEXs<br/>Uniswap V2/V3, DODO (if official)<br/>Used for destination swap & aggregator routing"]
    CW --> DEX
  end

  subgraph Bridge["Bridge layer"]
    direction LR
    CCIP["CCIP (WETH9/WETH10)"]
    LIFI["Li.Fi / Socket / Squid<br/>Symbiosis / Relay / Stargate"]
    CCIP --> LIFI
  end

  subgraph Optional["Optional (when deployed)"]
    ESR["EnhancedSwapRouter<br/>Size/slippage-based: Dodoex, Uniswap, Balancer, Curve<br/>Multi-provider for Chain 138"]
    COORD["SwapBridgeSwapCoordinator<br/>Swap source → bridge → swap dest"]
    ESR --> INT
  end

  subgraph MCP_AI["MCP & AI (pool management)"]
    direction TB
    ALLOW["Allowlist (per chain)<br/>pool_address, base_token, quote_token, profile"]
    TOOLS["MCP tools: get_pool_state, identify_pool_interface<br/>quote_add_liquidity, add_liquidity, remove_liquidity"]
    ALLOW --> TOOLS
    TOOLS --> INT
    TOOLS --> CW
    TOOLS --> DEX
  end

  subgraph Bot["Bot (cross-chain-pmm-lps)"]
    direction TB
    WATCH["Deviation watcher<br/>IDLE / ABOVE_BAND / BELOW_BAND"]
    ACT["Actions: buy/sell T, inventory adjust<br/>Cooldown, circuit break"]
    WATCH --> ACT
    ACT --> CW
  end

  %% User flows
  U1 --> TA
  U1 --> BQ
  U1 --> EXT
  U1 --> BA
  TA --> PROV
  TA --> POOLS138
  BQ --> INT
  BQ --> Bridge
  BQ --> DEX
  U2 --> BQ
  Bridge --> PublicChains
  U3 --> ALLOW
  U4 --> WATCH
  U4 --> TA

---

Swap routing paths (sequence view)

sequenceDiagram
  participant U as User / dApp
  participant API as Token-aggregation API
  participant Prov as DODOPMMProvider
  participant Int as DODOPMMIntegration
  participant Pool as PMM Pool (138)
  participant Br as Bridge / Quote API
  participant Dest as Destination DEX / cW* pool

  Note over U,Dest: Flow A: Same-chain swap (Chain 138)
  U->>API: GET /quote?chainId=138&tokenIn&tokenOut&amountIn
  API->>Prov: (indexed pool)
  API-->>U: amountOut, poolAddress
  U->>Int: approve(tokenIn); swapExactIn(pool, tokenIn, amountIn, minOut)
  Int->>Pool: sellBase or sellQuote
  Pool-->>Int: amountOut
  Int-->>U: transfer tokenOut

  Note over U,Dest: Flow B: Swap–bridge–swap
  U->>Br: POST /api/bridge/quote (source=138, dest, token, amount)
  Br->>API: source quote (138)
  Br->>Dest: destination quote (public chain)
  Br-->>U: sourceSwapQuote, bridgeRoute, destinationSwapQuote
  U->>Int: swap on 138 (optional)
  U->>Br: bridge tx (CCIP / Li.Fi / …)
  U->>Dest: swap on destination (optional)

  Note over U,Dest: Flow C: MCP / AI pool management
  participant MCP as MCP (allowlist)
  U->>MCP: get_pool_state(pool_address)
  MCP->>Int: RPC getPoolConfig, getPoolReserves, getMidPrice
  Int-->>MCP: config, reserves, price
  MCP-->>U: state (for rebalance / add liquidity decision)

---

Flow descriptions (key paths)

Flow	Path	Notes
Same-chain swap (138)	User → Token-aggregation API (GET /quote) → DODOPMMProvider.getQuote / executeSwap → DODOPMMIntegration (swapExactIn or legacy swap) → Pool	Single-hop; full mesh supported via swapExactIn.
Same-chain swap (public)	User → External aggregator (1inch, 0x, ParaSwap) or token-aggregation (if chain indexed) → Native DEX (Uniswap/DODO) or cW* / HUB pool	cW* pools used when deployed and indexed.
Swap–bridge–swap	User → POST /api/bridge/quote → sourceSwapQuote (138: DODOPMMIntegration) → Bridge (CCIP / Li.Fi / …) → destinationSwapQuote (public DEX or cW* pool)	Optional SwapBridgeSwapCoordinator for one-tx.
Bridge only	User → GET /api/v1/bridge/routes, token-mapping → Bridge (CCIP, etc.)	No DEX swap on 138 or destination.
MCP reads pool state	AI/MCP → Allowlist → get_pool_state (RPC) → DODOPMMIntegration (138) or cW* pool or Uniswap (public)	One MCP per chain or multi-chain allowlist.
MCP / AI maintenance	AI → MCP quote_add_liquidity / add_liquidity / remove_liquidity → DODOPMMIntegration or public DEX	Dedicated MCP/AI for Dodoex + Uniswap pool management.
Bot peg maintenance	Bot → Deviation watcher (pool vs oracle) → buy/sell cW* or inventory adjust → cW* / HUB pools on public chain	State machine: IDLE, ABOVE_BAND, BELOW_BAND, COOLDOWN, CIRCUIT_BREAK.
Multi-provider (future)	User / Contract → EnhancedSwapRouter → DODOPMMProvider + Uniswap + Balancer + Curve (by size/slippage) → Pools on 138	When EnhancedSwapRouter deployed and pools exist.

---

Component summary

Component	Role in routing
Token-aggregation API	Single-hop quote aggregator over indexed DODO (and Uniswap) on 138 and configured public chains.
DODOPMMIntegration	Creates pools, adds liquidity, executes swaps (legacy pairs + swapExactIn for full mesh).
DODOPMMProvider	Routing front: getQuote, executeSwap; registers pools; uses integration for execution.
Bridge quote API	Orchestrates source swap + bridge + destination swap; uses token-aggregation or destination DEX for quotes.
External aggregators	1inch, 0x, ParaSwap: multi-DEX routing on supported chains; 138 not supported until they add it.
Bridge aggregator	Explorer backend: Li.Fi, Socket, etc., for bridge routes only.
MCP	Read (and optionally execute) pool state and liquidity ops; allowlist per chain or multi-chain.
Bot	Maintains cW* peg on public chains via single-sided cW* / HUB pools; deviation and inventory.
EnhancedSwapRouter	(Optional) Multi-provider router on 138 when Uniswap/Balancer/Curve pools exist.

---

References

• DEX_AND_AGGREGATORS_CHAIN138_EXPLAINER.md
• PMM_DEX_ROUTING_STATUS.md
• PMM_FULL_MESH_AND_PUBLIC_SINGLE_SIDED_PLAN.md
• MCP_AI_POOL_MANAGEMENT_PLAN_UPGRADES.md