Lagmeter

A Rust tool to compare Chainlink ETH/USD oracle prices vs Binance spot prices, measuring latency and accuracy metrics.

Overview

Lagmeter fetches historical Chainlink ETH/USD oracle updates from Ethereum mainnet and compares them against Binance ETH/USDT prices to measure:

• Delta (%): Price difference between oracle and Binance at each update
• Lag (s): Time between Binance price and oracle block timestamp
• Update spacing (s): Time between consecutive oracle updates

Features

• Fetch Chainlink AnswerUpdated events from Ethereum mainnet
• Fetch historical Binance klines data
• Align data using Polars asof join with backward strategy
• Generate comprehensive statistics and visualizations
• Export results as Parquet files and PNG charts

Installation

git clone <repository>
cd lagmeter
cargo build --release

Quick Start

# Make the example script executable
chmod +x example.sh

# Edit example.sh to add your Infura API key and set appropriate block numbers
# Then run the example
./example.sh

Finding Timestamps

To find the appropriate timestamps for your analysis period:

1. Convert dates to Unix timestamps:

   # On macOS/Linux
   date -j -f "%Y-%m-%d" "2024-01-01" "+%s"
   
   # On Linux
   date -d "2024-01-01" +%s

2. Use online timestamp converters:

   • https://www.epochconverter.com/
   • https://www.unixtimestamp.com/

3. Use the Ethereum RPC to find block timestamps:

   # Get block by number and extract timestamp
   curl -X POST -H "Content-Type: application/json" \
     --data '{"jsonrpc":"2.0","method":"eth_getBlockByNumber","params":["0x1234567", false],"id":1}' \
     https://mainnet.infura.io/v3/YOUR_API_KEY

Usage

1. Fetch Chainlink Oracle Data

cargo run --release -- fetch-oracle \
  --rpc https://mainnet.infura.io/v3/YOUR_API_KEY \
  --proxy 0x5f4eC3Df9cbd43714FE2740f5E3616155c5b8419 \
  --from-timestamp 1704067200 \
  --to-timestamp 1706745600 \
  --out data/ethusd_oracle.parquet

2. Fetch Binance Price Data

cargo run --release -- fetch-binance \
  --symbol ETHUSDT \
  --interval 1s \
  --from-timestamp 1704067200 \
  --to-timestamp 1706745600 \
  --out data/binance_ethusdt_1s.parquet

3. Align and Compute Metrics

cargo run --release -- align \
  --oracle data/ethusd_oracle.parquet \
  --binance data/binance_ethusdt_1s.parquet \
  --out data/aligned.parquet

4. Analyze and Generate Reports

cargo run --release -- analyze \
  --input data/aligned.parquet \
  --out reports/

Output

The analysis generates:

• summary.json: Key statistics (median, p95, p99 for lag, delta, and update spacing)
• aligned_data.csv: CSV export of aligned data for external plotting/analysis

Key Metrics

• Median lag: ~X seconds
• P95 lag: ~Y seconds
• P99 lag: ~Z seconds
• Median delta: ~A%
• P95 delta: ~B%
• P99 delta: ~C%
• Median update spacing: ~S seconds

Important Notes

USDT ≈ USD Assumption

This tool treats USDT as equivalent to USD. For higher precision, you could:

• Fetch USDT/USD price data and apply corrections
• Use a basket of stablecoins
• Document this assumption in your analysis

Timestamps

• Oracle data: Uses Unix timestamps to find corresponding block ranges for event filtering
• Binance data: Uses Unix timestamps (in seconds) for API calls
• Alignment: Oracle block timestamps are used for aligning with Binance data

Feed Address

The default proxy address (0x5f4eC3Df9cbd43714FE2740f5E3616155c5b8419) is the Chainlink ETH/USD feed on Ethereum mainnet. Verify this is the correct address for your analysis period.

Data Alignment

Uses a 5-second tolerance window for aligning oracle updates with Binance prices. Oracle updates without a matching Binance price within this window are excluded.

Dependencies

• ethers: Ethereum interaction and event parsing
• polars: Fast DataFrame operations and joins
• reqwest: HTTP client for Binance API
• clap: CLI argument parsing
• tokio: Async runtime

Example Results

Summary statistics:
  Total oracle updates: 12345
  Median lag: 12.34 s
  P95 lag: 45.67 s
  P99 lag: 89.12 s
  Median delta: 0.0234%
  P95 delta: 0.1234%
  P99 delta: 0.3456%
  Median update spacing: 300.00 s
  P95 update spacing: 600.00 s
  P99 update spacing: 1200.00 s

License

MIT License