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

• 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

​

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?

​

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

​

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