Tycho Simulation Server

An HTTP service that brokers Tycho protocol streams into on-demand quote simulations.

Description

The server ingests Tycho protocol updates, keeps an in-memory view of pool state, and exposes an HTTP API for requesting swap quotes or checking readiness. It runs on Axum atop Tokio and relies on the tycho-simulation crate for all pricing logic.

Features

• Background ingestion of Tycho protocol streams with TVL-based filtering.
• POST /simulate endpoint that returns laddered amount-out simulated quotes with rich metadata.
• GET /status endpoint for readiness polling (block height, pool count).
• Structured logging with tracing.
• Fully asynchronous execution with Tokio.

Prerequisites

• Rust (latest stable toolchain)
• Cargo

Installation

1. Clone the repository:

   git clone https://github.com/dewiz-xyz/tycho-simulation-server.git
   cd tycho-simulation-server

2. Configure the environment:

   cp .env.example .env

   Populate .env with your Tycho credentials and optional tuning knobs.
3. Build the binary:

   cargo build --release

Configuration

The following environment variables are read at startup:

• TYCHO_URL – Tycho API base URL (default: tycho-beta.propellerheads.xyz)
• TYCHO_API_KEY – API key for authenticated Tycho access (required)
• TVL_THRESHOLD – Minimum TVL (in native units) for adding a pool to the stream (default: 300)
• TVL_KEEP_RATIO – Fraction of TVL_THRESHOLD used to decide when to keep/remove pools (default: 0.2)
• PORT – HTTP port (default: 3000)
• HOST – Bind address (default: 127.0.0.1)
• RUST_LOG – Logging filter (default: info)
• QUOTE_TIMEOUT_MS – Wall-clock timeout for an entire quote request (default: 75)
• POOL_TIMEOUT_NATIVE_MS – Per-pool timeout for native integrations (default: 5)
• POOL_TIMEOUT_VM_MS – Per-pool timeout for VM-backed integrations (default: 25)
• REQUEST_TIMEOUT_MS – Request-level guard applied at handler, router adds +250ms headroom (default: 1800)
• TOKEN_REFRESH_TIMEOUT_MS – Timeout for refreshing token metadata from Tycho (default: 200)

HTTP API

POST /simulate

JSON body:

curl -X POST "http://localhost:3000/simulate" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "req-123",
    "token_in": "0x6b175474e89094c44da98b954eedeac495271d0f",
    "token_out": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "amounts": ["1000000000000000000", "5000000000000000000"]
  }'

Response body:

{
  "request_id": "req-123",
  "data": [
    {
      "pool": "uniswapv3-1",
      "pool_name": "UniswapV3::DAI/USDC",
      "pool_address": "0x...",
      "amounts_out": ["999000000", "4985000000"],
      "gas_used": [210000, 210000],
      "block_number": 19876543
    }
  ],
  "meta": {
    "status": "ready",
    "block_number": 19876543,
    "matching_pools": 4,
    "candidate_pools": 4,
    "total_pools": 412,
    "failures": []
  }
}

QuoteMeta.status communicates warm-up, validation, and partial-failure states—HTTP status codes remain 200 OK.

Timeout behavior:

• Handler-level timeout returns 200 OK with PartialFailure, includes request_id, block_number, total_pools, and a Timeout failure.
• Router-level timeout (rare fallback, applied only to /simulate) returns 200 OK with PartialFailure, request_id may be empty, block_number is 0, and total_pools is unset. Logs include scope="router_timeout".
  • /status is not subject to router-level timeouts.

GET /status

Returns readiness information for health checks and pollers:

{
  "status": "ready",
  "block": 19876543,
  "pools": 412
}

If the service is still ingesting initial state the endpoint responds with 503 Service Unavailable and "status": "warming_up".

Usage

Launch the server after exporting the necessary environment variables:

cargo run --release

The application binds to the configured HOST:PORT and begins streaming protocol data before serving HTTP requests.

Dependencies

• tycho-simulation – protocol stream and simulator client
• tokio – asynchronous runtime
• axum – HTTP router and extractors
• serde/serde_json – serialization
• anyhow – error propagation
• tracing & tracing-subscriber – structured logging

Project Structure

• src/api – router wiring for public endpoints
• src/config – environment loading and logging setup
• src/handlers – HTTP handlers (quote, status) and stream ingester
• src/models – request/response models and shared state
• src/services – stream builder and quote engine
• src/main.rs – application entrypoint

License

MIT