# 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.