# MEV Bot Project - Claude Context

This file contains context information for Claude 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

## System Architecture
The MEV Bot follows a modular architecture with clearly defined components that communicate through well-defined interfaces.

### Core Components and Their Responsibilities

1. **Arbitrum Monitor (`pkg/monitor`)**
   - Monitors the Arbitrum sequencer for new blocks
   - Extracts transactions from blocks
   - Applies rate limiting to RPC calls
   - Implements fallback mechanisms for RPC endpoints

2. **Event Parser (`pkg/events`)**
   - Identifies DEX interactions in transactions
   - Parses transaction data for relevant information
   - Supports multiple DEX protocols (Uniswap V2/V3, SushiSwap)
   - Extracts swap amounts, pool addresses, and pricing data

3. **Market Pipeline (`pkg/market`)**
   - Implements a multi-stage processing pipeline
   - Uses worker pools for concurrent processing
   - Handles transaction decoding and event parsing
   - Performs market analysis using Uniswap V3 math
   - Detects arbitrage opportunities

4. **Market Scanner (`pkg/scanner`)**
   - Analyzes market events for arbitrage opportunities
   - Uses concurrent worker pools for processing
   - Implements caching for pool data
   - Calculates price impact and profitability

5. **Uniswap Pricing (`pkg/uniswap`)**
   - Implements Uniswap V3 pricing calculations
   - Converts between sqrtPriceX96, ticks, and prices
   - Calculates price impact of swaps
   - Handles precision with uint256 arithmetic

### Communication Patterns
- Pipeline pattern for multi-stage processing
- Worker pool pattern for concurrent execution
- Message passing through Go channels
- Shared memory access with proper synchronization

## Claude's Primary Focus Areas
As Claude, you're particularly skilled at:

1. **Code Architecture and Design Patterns**
   - Implementing clean, maintainable architectures
   - Applying appropriate design patterns (pipeline, worker pool, etc.)
   - Creating well-structured interfaces between components
   - Ensuring loose coupling and high cohesion

2. **System Integration and APIs**
   - Designing clear APIs between components
   - Implementing proper data flow between modules
   - Creating robust configuration management
   - Building error handling and recovery mechanisms

3. **Writing Clear Documentation**
   - Documenting complex algorithms and mathematical calculations
   - Creating clear API documentation
   - Writing architectural decision records
   - Producing user guides and examples

4. **Implementing Robust Error Handling**
   - Using Go's error wrapping with context
   - Implementing retry mechanisms with exponential backoff
   - Handling timeouts appropriately
   - Creating comprehensive logging strategies

5. **Creating Maintainable and Scalable Code Structures**
   - Organizing code for easy testing and maintenance
   - Implementing performance monitoring and metrics
   - Designing for horizontal scalability
   - Ensuring code follows established patterns and conventions

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