Simple Arbitrage

A high-performance Rust library for detecting and simulating arbitrage opportunities across Uniswap V2 DEX pairs on Ethereum.

🌟 Overview

This library provides a modular, production-ready framework for:

• 🔍 Discovering arbitrage opportunities across DEX pairs
• ⚡ Parallel processing of blockchain blocks using Rayon
• 🔄 Smart caching with thread-safe operations
• 🧪 REVM-based execution simulation with accurate gas tracking
• 📊 Mathematical optimization using ternary search algorithms

Originally a 1,347-line monolithic example, now refactored into a well-organized library with 6 specialized modules and comprehensive documentation.

📊 Architecture

graph TB
    subgraph "Core Library Modules"
        PARALLEL[parallel/<br/>Block Processing]
        CACHE[cache/<br/>Smart Caching]
        SIMULATION[simulation/<br/>REVM Execution]
        STRATEGY[strategy/<br/>Algorithms]
        TYPES[types/<br/>Data Structures]
        UTILS[utils/<br/>Helpers]
    end

    subgraph "External Dependencies"
        RPC[RPC Provider<br/>Ethereum Node]
        REVM_LIB[REVM<br/>EVM Simulator]
    end

    PARALLEL --> CACHE
    PARALLEL --> SIMULATION
    PARALLEL --> STRATEGY
    PARALLEL --> UTILS

    CACHE --> TYPES
    SIMULATION --> TYPES
    STRATEGY --> TYPES
    UTILS --> TYPES

    SIMULATION --> REVM_LIB
    CACHE --> RPC

    style PARALLEL fill:#ffd699,color:#000
    style CACHE fill:#d4a5ff,color:#000
    style SIMULATION fill:#a5ffb8,color:#000
    style STRATEGY fill:#ffb3b3,color:#000
    style TYPES fill:#d4d4d4,color:#000
    style UTILS fill:#fff066,color:#000

Loading

📖 Full Architecture Documentation - Detailed diagrams and design patterns

🚀 Quick Start

Prerequisites

You'll need access to an Ethereum archive node with full historical state. Options include:

• Local node (Erigon, Reth, Geth archive mode)
• Remote RPC provider (Alchemy, Infura, QuickNode with archive access)
• Private network node (e.g., via Tailscale)

⚠️ Important: Update the RPC URL in examples to point to your node. The default URL in examples is a private Tailscale endpoint and won't work for you.

Installation

[dependencies]
simple-arbitrage = { path = "." }
tokio = { version = "1", features = ["full"] }
anyhow = "1.0"

Basic Usage

use simple_arbitrage::parallel::{
    process_block_range, ArbitrageStats, BlockProcessor,
};
use std::sync::Arc;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Setup RPC client
    let client = Arc::new(
        ProviderBuilder::new()
            .connect("http://localhost:8545")
            .await?
            .erased(),
    );

    // Create processor and stats
    let processor = BlockProcessor::new();
    let stats = ArbitrageStats::new();

    // Process blocks in parallel
    let results = process_block_range(
        22_200_000,     // start block
        22_210_000,     // end block
        client,
        processor.get_cache_clone(),
        processor.config.clone(),
        None,           // optional progress callback
        stats.clone(),
    );

    println!("Found {} profitable opportunities", stats.get_total());
    Ok(())
}

See examples/modular_arbitrage.rs for a complete example.

📦 Module Overview

🔄 parallel - Concurrent Block Processing

Orchestrates parallel arbitrage detection across multiple blocks using Rayon.

Key Features:

• Rayon-based parallel iteration
• Tokio async/sync bridging
• Progress tracking with callbacks
• Thread-safe statistics

Main Types:

• BlockProcessor - Coordinates block processing
• ArbitrageStats - Tracks profitable opportunities
• process_block_range() - Main entry point

---

💾 cache - Intelligent Pair Caching

Thread-safe caching layer with smart loading strategies.

Key Features:

• Arc<Mutex> for thread safety
• Full load vs reserve-only updates
• Multicall batching (1000 pairs/call)
• High-level management API

Main Types:

• PairCache - Thread-safe cache wrapper
• CacheManager - High-level cache operations
• classify_pairs() - Smart loading strategy

---

🧪 simulation - REVM Execution Engine

EVM simulation infrastructure for accurate arbitrage execution testing.

Key Features:

• REVM-based execution
• Accurate gas tracking
• Account and storage setup
• Balance, transfer, and swap operations

Main Types:

• simulate_arbitrage_execution() - Full simulation
• GasMeter - Gas tracking
• EVM call wrappers (balance_of, swap, transfer)

---

📐 strategy - Mathematical Algorithms

Core algorithms for arbitrage detection and optimization.

Key Features:

• Mathematical inequality detection
• Ternary search optimization (O(log₃ n))
• U512 overflow prevention
• Configurable convergence epsilon

Main Types:

• find_arbitrage() - Detects opportunities
• find_optimal_amount() - Ternary search
• compute_profit() - Profit calculation

---

📋 types - Core Data Structures

Shared type definitions used across modules.

Key Features:

• PairInfo with reserve updates
• Solidity contract interfaces
• Type aliases for complex nested types

Main Types:

• PairInfo - Liquidity pool information
• AlloyCacheDB - REVM state type alias
• Contract interfaces (IUniswapV2Pair)

---

🛠️ utils - Helper Utilities

Common operations for pair grouping and combinations.

Key Features:

• WETH pair grouping
• Combination generation (C(n,2))
• Comprehensive unit tests

Main Functions:

• group_pairs_by_token() - Groups WETH pairs
• get_pair_combinations() - Generates combinations

⚡ Performance Features

• Parallel Processing: Rayon-based multi-threaded block processing
• Smart Caching: Full load vs reserve-only update strategies
• Multicall Batching: 1000 pairs per RPC call
• Lock-Free Stats: Atomic counters for statistics
• Overflow Prevention: U512 arithmetic in profit calculations
• Pre-Allocation: Exact capacity for vectors (C(n,2) combinations)
• Early Filtering: Minimum reserve checks (1 ETH threshold)

🔐 Thread Safety

The library is designed for safe concurrent execution:

graph LR
    subgraph "Shared State (Thread-Safe)"
        CACHE[Arc&lt;Mutex&lt;HashMap&gt;&gt;<br/>Pair Cache]
        STATS[Arc&lt;AtomicUsize&gt;<br/>Statistics]
        CONFIG[Arc&lt;Config&gt;<br/>Read-Only]
    end

    subgraph "Per-Thread (Isolated)"
        STATE1[REVM State 1]
        STATE2[REVM State 2]
        STATEN[REVM State N]
    end

    T1[Thread 1] --> CACHE
    T2[Thread 2] --> CACHE
    TN[Thread N] --> CACHE

    T1 --> STATS
    T2 --> STATS
    TN --> STATS

    T1 --> STATE1
    T2 --> STATE2
    TN --> STATEN

Loading

🧮 Algorithm Overview

Arbitrage Detection

Uses mathematical inequality to detect opportunities:

997² × reserve0_a × reserve1_b > 1000² × reserve1_a × reserve0_b

Where:

• 997 = Uniswap fee factor (0.3% fee)
• 1000 = Base factor
• Reserves arranged as: reserve1 = WETH, reserve0 = Token

Optimal Amount Finding

Implements ternary search to find the optimal input amount:

1. Initialize bounds: [1 wei, min(100×reserve, balance)]
2. Divide range into thirds
3. Evaluate profit at mid1 and mid2
4. Discard third with lower profit
5. Repeat until convergence (ε = 0.001 ETH)
6. Return amount with maximum profit

Complexity: O(log₃(range)) iterations

🧪 Testing

Run the test suite:

# Run all tests
cargo test

# Run specific module tests
cargo test --lib cache
cargo test --lib utils

# Run with output
cargo test -- --nocapture

📖 Examples

Run the Modular Example

cargo run --example modular_arbitrage

Other Examples

The examples/ directory contains various demonstration scripts:

• modular_arbitrage.rs - Clean example using refactored library
• 110725_simulation3.rs - Original monolithic implementation
• 110725_simulation2.rs - Intermediate version
• 110725_simulation.rs - Earlier version

🔧 Configuration

Customize behavior via BlockProcessorConfig:

use simple_arbitrage::parallel::{BlockProcessor, BlockProcessorConfig};
use alloy::primitives::{address, U256};

let config = BlockProcessorConfig {
    weth_address: address!("c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"),
    account_address: address!("18B06aaF27d44B756FCF16Ca20C1f183EB49111f"),
    balance: U256::from(1_000_000_000_000_000_000_000_000u128), // 1M ETH
};

let processor = BlockProcessor::with_config(config);

📊 Statistics Tracking

Monitor arbitrage opportunities across parallel workers:

let stats = ArbitrageStats::new();

// ... process blocks ...

println!("Total profitable opportunities: {}", stats.get_total());

Thread-safe atomic counters ensure accurate statistics across parallel execution.

🐛 Debugging

Enable detailed logging:

// Add to Cargo.toml
tracing-subscriber = "0.3"

// In your code
tracing_subscriber::fmt::init();

Log levels:

• debug - Skipped pairs, cache hits/misses
• warn - Non-critical failures
• error - Critical errors

📝 Documentation

• Architecture Diagrams - Visual overview with Mermaid diagrams
• Refactoring Summary - Details of the refactoring process
• API Docs - Generate with cargo doc --open

🔍 How It Works

1. Pair Discovery

• Reads recently active pair addresses from cached data
• Filters for pairs with swaps in last ~10k blocks (~1 day)

2. Smart Caching

• First encounter: Full load (addresses, symbols, decimals, reserves)
• Already cached: Reserve-only update via multicall
• Thread-safe shared cache across parallel workers

3. Arbitrage Detection

• Groups pairs by non-WETH token
• Generates all combinations C(n,2) for each token
• Tests both directions (A→B and B→A)
• Filters by minimum reserves (≥1 ETH)
• Mathematical inequality check for arbitrage

4. Optimization

• Ternary search finds optimal input amount
• Evaluates profit function at midpoints
• Converges to maximum profit amount

5. Simulation

• REVM executes trades in simulated environment
• Tracks gas for all operations
• Calculates net profit after gas costs
• Returns (profit, gas_used) tuple

6. Statistics

• Atomic counters track profitable opportunities
• Progress callbacks for monitoring
• Per-block timing and results

🚧 Limitations

• Uniswap V2 Only: Currently supports only Uniswap V2 pairs
• Two-Pool Arbitrage: Limited to simple two-pool arbitrage loops
• No Flash Loans: Assumes available balance for trades
• Historical Data: Requires pre-cached pair addresses
• Gas Price: Uses simple base_fee + priority_fee model

🔮 Future Enhancements

• Multi-hop arbitrage (3+ pools)
• Flash loan integration
• Uniswap V3 support
• Cross-DEX arbitrage (Sushiswap, Curve, etc.)
• Real-time mempool monitoring
• MEV protection strategies
• Configurable gas price strategies
• Web UI for monitoring

📄 License

This project is provided as-is for educational and research purposes.

🙏 Acknowledgments

Built with:

• Alloy - Ethereum types and RPC
• REVM - Rust EVM implementation
• Rayon - Data parallelism
• Tokio - Async runtime

---

⚠️ Disclaimer: This software is for educational purposes only. Using it for actual trading involves significant financial risk. Always test thoroughly and understand the code before deploying with real funds.