mev-beta/GEMINI.md

MEV Bot Project - Gemini Context

This file contains context information for Gemini about the MEV Bot project.

Project Overview

This is an MEV (Maximal Extractable Value) bot written in Go 1.24+ that monitors the Arbitrum sequencer for potential swap opportunities. When a potential swap is detected, the bot scans the market to determine if the swap is large enough to move the price using off-chain methods.

Project Structure

• cmd/ - Main applications (specifically cmd/mev-bot/main.go)
• internal/ - Private application and library code
  • internal/config - Configuration management
  • internal/logger - Logging functionality
  • internal/ratelimit - Rate limiting implementations
  • internal/utils - Utility functions
• pkg/ - Library code that can be used by external projects
  • pkg/events - Event processing system
  • pkg/market - Market data handling
  • pkg/monitor - Arbitrum sequencer monitoring
  • pkg/scanner - Market scanning functionality
  • pkg/test - Test utilities and helpers
  • pkg/uniswap - Uniswap V3 specific implementations
• config/ - Configuration files
• @prompts/ - AI prompts for development assistance
• docs/ - Documentation
• scripts/ - Scripts for building, testing, and deployment

Key Integration Points

• Refer to @prompts/COMMON.md for core requirements and integration points
• Follow the modular architecture with independent components
• Use the universal message bus for inter-module communication
• Adhere to the standards defined in the project plan

Development Guidelines

• Focus on implementing the features outlined in the project plan
• Ensure all code follows Go best practices
• Write comprehensive tests for all functionality
• Document all public APIs and complex algorithms
• Follow the performance requirements outlined in COMMON.md

Mathematical Implementation Details

Uniswap V3 Pricing Functions

The core of the MEV bot's functionality relies on precise Uniswap V3 pricing calculations:

1. sqrtPriceX96 to Price Conversion

   • Formula: price = (sqrtPriceX96 / 2^96)^2
   • Implementation uses math/big for precision
   • Critical for accurate price impact calculations

2. Price to sqrtPriceX96 Conversion

   • Formula: sqrtPriceX96 = sqrt(price) * 2^96
   • Used when initializing or updating pool states
   • Requires careful handling of floating-point precision

3. Tick Calculations

   • Formula: tick = log_1.0001(sqrtPriceX96 / 2^96)^2
   • Ticks range from -887272 to 887272
   • Used for discrete price levels in Uniswap V3

4. Price Impact Calculations

   • Based on liquidity and amount being swapped
   • Formula: priceImpact = amountIn / liquidity
   • Critical for determining arbitrage profitability

Precision Handling

• Uses github.com/holiman/uint256 for precise uint256 arithmetic
• Implements proper rounding strategies
• Handles overflow and underflow conditions
• Maintains precision throughout calculations

Performance Optimization Areas

Concurrency Patterns

1. Worker Pools

   • Used in pkg/scanner for concurrent event processing
   • Configurable number of workers based on system resources
   • Channel-based job distribution

2. Pipeline Processing

   • Multi-stage processing in pkg/market
   • Parallel processing of different transaction batches
   • Backpressure handling through channel buffering

3. Caching Strategies

   • Singleflight pattern to prevent duplicate requests
   • Time-based expiration for cached pool data
   • Memory-efficient data structures

Low-Level Optimizations

1. Memory Allocation Reduction

   • Object pooling for frequently created objects
   • Pre-allocation of slices and maps when size is known
   • Reuse of buffers and temporary variables

2. Algorithmic Efficiency

   • O(1) lookups for cached pool data
   • Efficient sorting and searching algorithms
   • Minimal computational overhead in hot paths

3. System-Level Optimizations

   • Proper tuning of Go's garbage collector
   • NUMA-aware memory allocation (if applicable)
   • CPU cache-friendly data access patterns

Gemini's Primary Focus Areas

As Gemini, you're particularly skilled at:

1. Algorithmic Implementations and Mathematical Computations

   • Implementing precise Uniswap V3 pricing functions
   • Optimizing mathematical calculations for performance
   • Ensuring numerical stability and precision
   • Creating efficient algorithms for arbitrage detection

2. Optimizing Performance and Efficiency

   • Profiling and identifying bottlenecks in critical paths
   • Reducing memory allocations in hot code paths
   • Optimizing concurrency patterns for maximum throughput
   • Tuning garbage collection for low-latency requirements

3. Understanding Complex Uniswap V3 Pricing Functions

   • Implementing accurate tick and sqrtPriceX96 conversions
   • Calculating price impact with proper precision handling
   • Working with liquidity and fee calculations
   • Handling edge cases in pricing mathematics

4. Implementing Concurrent and Parallel Processing Patterns

   • Designing efficient worker pool implementations
   • Creating robust pipeline processing systems
   • Managing synchronization primitives correctly
   • Preventing race conditions and deadlocks

5. Working with Low-Level System Operations

   • Optimizing memory usage and allocation patterns
   • Tuning system-level parameters for performance
   • Implementing efficient data structures for high-frequency access
   • Working with CPU cache optimization techniques

When working on this project, please focus on these areas where your strengths will be most beneficial.