mev-beta/CLAUDE.md

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.