CQ1 Routing Engine

The Routing Problem

For a trade like SOL → USDC, the router must evaluate:

• Direct paths: Dozens of pools across multiple DEXs
• 2-hop paths: SOL → BONK → USDC, SOL → USDT → USDC, etc.
• 3-hop paths: Combinations through intermediate tokens
• Split routes: Distributing volume across multiple paths

Each path involves different pool types (AMM, CLMM, Stable) with varying liquidity depths and fee structures.

Traditional routers evaluate thousands of paths sequentially. CQ1 evaluates millions simultaneously.

---

Parallel Pathfinding

The routing engine processes all viable paths concurrently:

flowchart TB
    Request["Request: SOL → USDC"]
    
    subgraph Parallel["Parallel Evaluation"]
        Direct["Direct Paths<br/>Raydium · Orca · Meteora"]
        TwoHop["2-Hop Routes<br/>via BONK · USDT · JUP"]
        ThreeHop["3-Hop Routes<br/>Complex paths"]
    end
    
    Result["Optimal Route + Split Allocation"]
    
    Request --> Parallel
    Direct & TwoHop & ThreeHop --> Result
    
    style Parallel fill:#f0fdfa,stroke:#0d9488
    style Result fill:#0d9488,color:#fff

All paths scored and ranked simultaneously. Best combination returned.

---

Waterfill Algorithm

Large trades create slippage when pushed through a single pool. The waterfill algorithm treats liquidity pools as containers with different depths and "fills" them in order of price efficiency.

Example: 10,000 USDC → SOL

flowchart LR
    subgraph Analysis["Pool Analysis"]
        R["Raydium CLMM<br/>████████████"]
        O["Orca Whirlpool<br/>████████"]
        M["Meteora DLMM<br/>█████"]
    end
    
    subgraph Split["Optimal Split"]
        S1["60% → Raydium"]
        S2["25% → Orca"]
        S3["15% → Meteora"]
    end
    
    Result["Minimized Slippage"]
    
    Analysis --> Split --> Result
    
    style Result fill:#0d9488,color:#fff

The algorithm evaluates all viable split combinations and returns the allocation with the highest total output.

---

Execution Flow

sequenceDiagram
    autonumber
    participant User
    participant API
    participant Cache
    participant Engine as Routing Engine
    participant Redis
    participant Math as Math Core

    User->>API: GET /quote (src, dst, amount)
    API->>Cache: Fetch epoch, token layouts
    Cache-->>API: System state
    
    API->>Engine: Find optimal route
    Note right of Engine: Parallel path evaluation<br/>Waterfill optimization
    Engine-->>API: Route plan + splits
    
    loop For each hop
        API->>Redis: GET buffer:{pool_id}
        Redis-->>API: Binary state
        API->>Math: Calculate output
        Math-->>API: {output, fee, impact}
    end
    
    API-->>User: Quote response

Two-phase approach:

• Routing engine handles path enumeration and split optimization
• Math core handles precision arithmetic using exact on-chain formulas

---

DEX Adapters

The CQ1 Engine uses an adapter pattern to support multiple DEX protocols through a uniform interface.

Standard Interface

compute_amount_out(state, amount) → {output, fee, impact}

Each adapter handles protocol-specific math internally while exposing consistent output to the routing engine.

Supported Protocols

Raydium

Orca

Meteora

Adding New Protocols

New DEX integrations require only a new adapter implementing the standard interface. Core routing logic remains unchanged.

---

Precision Math

All calculations use:

• BigNumber (BN): Arbitrary precision integer math
• Exact curve implementations: Matching on-chain programs

Quotes match on-chain execution exactly. No estimates, no approximations.