​

Architecture

​

System Overview

​

High-Level Architecture

​

Architecture Diagram Explanation

1. User submits order - Orderbook validates and stores in PostgreSQL
2. Autopilot queries orders - Creates auction every ~12-15 seconds
3. Auction sent to solvers - Multiple solver types compete:
   • Colocated: External partners run their own driver + solver
   • Non-colocated: CoW runs driver, solver provides solutions via API
   • Internal: Baseline and other built-in solvers
4. Solutions returned - Autopilot ranks by execution quality
5. Winner selected - Driver simulates and submits to chain
6. Settlement executes - Smart contract performs all trades atomically
7. Circuit breaker monitors - Ensures solvers behave correctly

​

Core Components

​

Orderbook

• Expose HTTP API for order submission and queries
• Validate EIP-712 signatures on incoming orders
• Check order viability (balance, approval, expiration)
• Store orders in PostgreSQL
• Provide quotes and fee estimates
• Filter invalid orders based on blockchain state
• Serve open orders to autopilot

• HTTP server: Axum
• Database: PostgreSQL via sqlx
• Blockchain: Alloy (Ethereum library)

• Multiple orderbook instances can run concurrently
• Each connects to the same PostgreSQL database
• Horizontally scalable to handle high API traffic

​

Autopilot

• Drive the protocol forward on a schedule (~12-15 second intervals)
• “Cut” auctions by determining boundaries and included orders
• Filter orders for validity (balance, approval, on-chain state)
• Apply fee policies to orders
• Send auction data to all configured solvers
• Collect solutions from drivers
• Rank solutions based on objective value (execution quality, gas costs)
• Select the winning solution(s)
• Instruct winning driver to submit on-chain
• Store auction and settlement data to database

• Async runtime: Tokio
• Database: PostgreSQL via sqlx
• Blockchain: Alloy

• Only one autopilot runs per network
• Acts as the central coordinator for the protocol

​

Driver

• Receive auctions from autopilot
• Fetch liquidity from multiple sources:
  • On-chain AMMs (Uniswap, Balancer, Curve, etc.)
  • Aggregator APIs (1inch, 0x, etc.)
  • Custom liquidity sources
• Forward auction to solver engine (if non-colocated)
• Receive solution from solver
• Encode solution to settlement calldata
• Simulate transaction to verify correctness
• Submit winning solution to settlement contract
• Handle transaction status and revert recovery

• HTTP server: Axum (receives auctions from autopilot)
• HTTP client: Reqwest (calls external solver APIs)
• Blockchain: Alloy

• Non-colocated: CoW runs driver, solver is external API
• Colocated: Solver partner runs their own driver instance

​

Solver Engine

• Receive auction data (orders + liquidity)
• Compute optimal routing and matching
• Find Coincidence of Wants (CoW) opportunities
• Optimize for execution quality (surplus, gas efficiency)
• Return solution to driver

​

Internal Solvers

• Finds direct CoW matches
• Routes through single AMM hops
• Simple but effective

• Smart order routing through Balancer
• Vault integration

​

External Colocated

• Full control over solver logic
• Run their own driver instance
• Direct submission to autopilot
• Full responsibility for solution quality

​

External Non-Colocated

• CoW handles liquidity fetching
• CoW handles simulation and submission
• Solver focuses only on optimization
• Lower operational burden

• Can be implemented in any language
• Communicates via HTTP JSON API
• Must conform to solver API specification

​

PostgreSQL Database

• Orders: User orders with signatures and metadata
• Quotes: Pre-submission price quotes and fee estimates
• Auctions: Historical auction data and included orders
• Settlements: Executed settlements with transaction hashes
• Competition: Solver competition results and rankings
• App Data: Order metadata and hooks (IPFS references)

• Orderbook: Writes orders, reads for API queries
• Autopilot: Reads valid orders, writes auctions and settlements
• Database migrations: Schema evolution via sqlx

• Supports multiple concurrent orderbook instances
• Single autopilot reads/writes auction state
• Indexed for efficient order querying by status, user, etc.

​

Circuit Breaker

• Monitor on-chain settlements
• Compare executed trades to auction outcomes
• Detect solver misbehavior:
  • Incorrect execution prices
  • Missing trades
  • Unauthorized trades
• Jail misbehaving solvers
• Alert operators of anomalies

• Monitors blockchain events
• Cross-references with database auction records
• Automated solver disqualification on violations

​

Order Lifecycle

​

Step 1: Order Creation

1. User creates order in CoW Swap UI (or via API)
2. Order includes: tokens, amounts, limits, expiration, fees
3. User signs order with EIP-712 signature (off-chain, no gas)
4. Order submitted to orderbook API

​

Step 2: Order Validation

1. Orderbook verifies signature
2. Checks user has sufficient balance
3. Checks user has approved settlement contract
4. Validates order isn’t expired
5. Stores order in PostgreSQL with status “open”

​

Step 3: Auction Creation

1. Autopilot queries database for open orders
2. Re-validates orders against current blockchain state
3. Applies fee policies (protocol fees, partner fees)
4. Creates auction with valid orders
5. Stores auction to database

​

Step 4: Solver Competition

1. Autopilot sends auction to all configured solvers
2. Drivers fetch current liquidity from various sources
3. Solver engines compute optimal solutions
4. Solutions returned to autopilot within time limit

​

Step 5: Solution Ranking

1. Autopilot receives solutions from multiple solvers
2. Calculates objective value for each solution:
   • Execution quality (user surplus)
   • Gas costs
   • Risk factors
3. Ranks solutions
4. Selects winning solution(s)

​

Step 6: Settlement Execution

1. Autopilot instructs winning driver to submit
2. Driver simulates transaction to verify correctness
3. Driver submits transaction to settlement contract
4. Driver monitors transaction status
5. Transaction mined in 2-3 block window

​

Step 7: On-Chain Settlement

1. Pre-interactions: User hooks, approvals
2. Transfer in: Pull sell tokens from users
3. Main interactions: Execute AMM swaps, transfers
4. Transfer out: Send buy tokens to users
5. Post-interactions: User hooks, callbacks

​

Step 8: Post-Settlement

1. Orderbook observes settlement event
2. Updates order status to “filled” (or “partially filled”)
3. Circuit breaker verifies correct execution
4. Data stored for analytics and API queries

​

Auction Mechanism

​

Batch Auction Design

• MEV Protection: No single transaction can be frontrun
• Uniform Prices: All users in a batch get the same clearing price
• CoW Opportunities: Opposing orders can match directly
• Gas Efficiency: Multiple trades in one transaction

• Currently: ~12-15 seconds
• Target: Every block (~12 seconds on Ethereum)
• Configurable per network

​

Solver Competition

• Ensures best execution through market forces
• Prevents single point of failure
• Enables innovation in routing strategies
• Aligns incentives (better solutions = more rewards)

1. User surplus: Execution quality vs. limit price
2. Gas costs: Lower gas = better score
3. Risk: Penalize solutions likely to revert
4. Slippage: Prefer tighter execution

• Winning solver earns protocol fee portion
• Payment in ETH from protocol treasury
• Incentivizes high-quality solutions

​

Settlement Process

​

Settlement Contract Flow

// Simplified settlement flow
function settle(
    IERC20[] tokens,
    uint256[] clearingPrices,
    Trade[] trades,
    Interaction[] interactions
) external {
    // 1. Execute pre-interactions
    executeInteractions(interactions.pre);

    // 2. Transfer tokens in from users
    for (trade in trades) {
        transferFrom(trade.sellToken, trade.owner, trade.sellAmount);
    }

    // 3. Execute main interactions (swaps)
    executeInteractions(interactions.main);

    // 4. Transfer tokens out to users
    for (trade in trades) {
        transfer(trade.buyToken, trade.owner, trade.buyAmount);
    }

    // 5. Execute post-interactions
    executeInteractions(interactions.post);
}

• Pre: Approvals, oracle updates, custom user hooks
• Main: AMM swaps (Uniswap, Balancer, etc.), aggregator calls
• Post: User callbacks, cleanup, notifications

​

Transaction Submission

• Simulation fails: Solution rejected, auction re-run
• Transaction reverts: Driver retries with backup solution
• Timeout: Auction expires, orders return to orderbook

• Dynamic gas estimation based on network conditions
• Priority fees to ensure timely inclusion
• Solver pays gas upfront, reimbursed from protocol

​

Multi-Chain Deployment

​

Independent Deployments

• PostgreSQL database
• Orderbook API
• Autopilot instance
• Driver instances
• Settlement contract

• Orders on Ethereum don’t interact with Arbitrum orders
• Each network operates independently
• Same codebase, different configuration

​

Network-Specific Configuration

# Example configuration
chain_id = 1
node_url = "https://eth.llamarpc.com"
settlement_contract = "0x9008D19f58AAbD9eD0D60971565AA8510560ab41"
auction_duration = 15  # seconds
block_time = 12  # seconds

• Ethereum (1): Deepest liquidity, highest gas costs
• Gnosis (100): Fast, cheap, good for small trades
• Arbitrum (42161): L2 scaling, lower fees
• Base (8453): Growing ecosystem
• Polygon (137): Broad adoption
• More: Linea, BNB, Ink

​

Data Flow

​

Read Paths

User -> Orderbook API -> PostgreSQL -> Response

Autopilot -> PostgreSQL -> Filter -> Create Auction

Driver -> Uniswap API -> Cache -> Solver
Driver -> Balancer API -> Cache -> Solver
Driver -> 1inch API -> Cache -> Solver

​

Write Paths

User -> Orderbook API -> Validate -> PostgreSQL

Autopilot -> Create Auction -> PostgreSQL -> Send to Solvers

Driver -> Blockchain -> Settlement Contract -> Events -> Database

​

Technology Choices

​

Why Rust?

• Performance: Low latency critical for competitive auctions
• Memory Safety: Handles user funds - correctness is paramount
• Concurrency: Tokio enables efficient async operations
• Type Safety: Catch errors at compile time, not runtime

​

Why PostgreSQL?

• ACID transactions: Critical for order consistency
• Rich querying: Complex order filtering and joins
• Mature ecosystem: Reliable, well-understood
• Horizontal reads: Multiple orderbook instances

​

Why Alloy?

• Modern Ethereum library: Successor to ethers-rs
• Type-safe contracts: Generated Rust bindings
• Efficient encoding: Fast ABI encoding/decoding
• Async-first: Integrates with Tokio

​

Performance Characteristics

• Handles 100+ requests/second per instance
• Sub-100ms API response times
• Horizontally scalable

• Auctions every 12-15 seconds
• Processes 100+ orders per auction
• Solver timeout: 5-8 seconds

• Fetches liquidity from 10+ sources in parallel
• Simulation time: 1-2 seconds
• Submission time: 1-3 blocks

​

Security Considerations

​

Order Validation

• Signature verification: EIP-712 typed data
• Replay protection: Chain ID and settlement contract in signature
• Balance checks: Verify user has funds
• Approval checks: Verify user approved settlement contract

​

Solver Accountability

• Simulations: All solutions simulated before submission
• Circuit breaker: Monitors actual vs. expected outcomes
• Slashing: Misbehaving solvers lose stake and access
• Transparency: All settlements on-chain, verifiable

​

Database Security

• SQL injection: Parameterized queries via sqlx
• Access control: Database credentials restricted
• Encryption: Connections over TLS
• Backups: Regular automated backups

​

Monitoring and Observability

​

Logging

• Structured JSON logs via tracing
• Dynamic log level adjustment via UNIX socket
• Aggregated to centralized logging (Victoria Logs)

​

Metrics

• Prometheus metrics exposed on all services
• Dashboards in Grafana
• Key metrics:
  • Orders per second
  • Auction duration
  • Settlement success rate
  • Solver performance

​

Tracing

• Tokio-console support (playground only)
• Heap profiling with jemalloc
• Performance profiling tools

​

Next Steps

• Quickstart - Run the services locally
• Development Guide - Start contributing to the codebase
• API Reference - Integrate with the Orderbook API
• Solver Service - Learn about solver integration

​

Further Reading

• CoW Protocol Documentation - Protocol concepts and design
• Settlement Contract - Smart contract source code
• Solver Specification - Solver API details
• Research Papers - Academic publications on batch auctions