mev-beta/CLAUDE.md

MEV Bot Project - Claude Code Configuration

This file contains comprehensive Claude Code configuration and context information for the MEV Bot project.

Note: For Claude-specific CLI configuration, commands, and development guidelines, please refer to the .claude/ directory which contains:

• .claude/CLAUDE.md - Complete Claude Code CLI configuration
• .claude/commands/ - Slash commands for Claude Code
• .claude/scripts/ - Scripts for Claude Code development workflow

🚀 Quick Start Commands

Essential Build & Test Commands

# Build the MEV bot binary
make build

# Run tests
make test

# Start development server with hot reload
./scripts/run.sh

# Build and run with logging
./scripts/build.sh && ./mev-bot start

# Check for Go modules issues
go mod tidy && go mod verify

# Run linter
golangci-lint run

# Run security analysis
gosec ./...

Development Workflow Commands

# Setup development environment
export ARBITRUM_RPC_ENDPOINT="wss://arbitrum-mainnet.core.chainstack.com/73bc682fe9c5bd23b42ef40f752fa89a"
export ARBITRUM_WS_ENDPOINT="wss://arbitrum-mainnet.core.chainstack.com/73bc682fe9c5bd23b42ef40f752fa89a"
export METRICS_ENABLED="false"

# Run with timeout for testing
timeout 30 ./mev-bot start

# Debug with verbose logging
LOG_LEVEL=debug ./mev-bot start

# Profile performance
go tool pprof http://localhost:6060/debug/pprof/profile

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
• .claude/ - Claude Code specific configuration and tools

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 & Code Style

Go Best Practices

• Error Handling: Always wrap errors with context using fmt.Errorf("operation failed: %w", err)
• Concurrency: Use worker pools for processing large datasets (see pkg/market/pipeline.go)
• Interfaces: Keep interfaces small and focused (1-3 methods maximum)
• Testing: Aim for >90% test coverage with table-driven tests
• Logging: Use structured logging with slog package
• Performance: Profile regularly with go tool pprof

Code Organization Rules

• File Size: Keep files under 500 lines (split larger files into logical components)
• Package Structure: Follow Go standard layout (cmd/, internal/, pkg/)
• Naming: Use Go naming conventions (PascalCase for exports, camelCase for private)
• Documentation: Document all exported functions with examples
• Constants: Group related constants in blocks with iota when appropriate

Required Checks Before Commit

# Run all checks before committing
make test && make lint && go mod tidy

# Security scan
gosec ./...

# Dependency vulnerability check
go list -json -m all | nancy sleuth

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.

🛠 Claude Code Optimization Settings

Workflow Preferences

• Always commit changes: Use git commit -am "descriptive message" after significant changes
• Branch naming: Use hyphens (feat-add-new-parser, fix-memory-leak)
• Context management: Use /compact to manage long conversations
• Parallel processing: Leverage Go's concurrency patterns extensively

File Organization Preferences

• Never save temporary files to root: Use /tmp/ or internal/temp/
• Log files: Always save to logs/ directory
• Test files: Place alongside source files with _test.go suffix
• Documentation: Keep in docs/ with clear naming

Performance Monitoring

# Enable metrics endpoint
export METRICS_ENABLED="true"
export METRICS_PORT="9090"

# Monitor memory usage
go tool pprof http://localhost:9090/debug/pprof/heap

# Monitor CPU usage
go tool pprof http://localhost:9090/debug/pprof/profile?seconds=30

# Monitor goroutines
go tool pprof http://localhost:9090/debug/pprof/goroutine

🔧 Environment Configuration

Required Environment Variables

# Arbitrum RPC Configuration
export ARBITRUM_RPC_ENDPOINT="wss://arbitrum-mainnet.core.chainstack.com/73bc682fe9c5bd23b42ef40f752fa89a"
export ARBITRUM_WS_ENDPOINT="wss://arbitrum-mainnet.core.chainstack.com/73bc682fe9c5bd23b42ef40f752fa89a"

# Application Configuration
export LOG_LEVEL="info"
export METRICS_ENABLED="false"
export METRICS_PORT="9090"

# Development Configuration
export GO_ENV="development"
export DEBUG="true"

Optional Environment Variables

# Performance Tuning
export GOMAXPROCS=4
export GOGC=100

# Logging Configuration
export LOG_FORMAT="json"
export LOG_OUTPUT="logs/mev-bot.log"

# Rate Limiting
export MAX_RPS=100
export RATE_LIMIT_BURST=200

📝 Commit Message Conventions

Format

type(scope): brief description

- Detailed explanation of changes
- Why the change was needed
- Any breaking changes or migration notes

🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>

Types

• feat: New feature implementation
• fix: Bug fix
• perf: Performance improvement
• refactor: Code restructuring without feature changes
• test: Adding or updating tests
• docs: Documentation updates
• build: Build system or dependency changes
• ci: CI/CD pipeline changes

🚨 Security Guidelines

Never Commit

• Private keys or wallet seeds
• API keys or secrets
• RPC endpoints with authentication
• Personal configuration files

Always Validate

• Input parameters for all functions
• RPC responses before processing
• Mathematical calculations for overflow
• Memory allocations for bounds

Security Commands

# Scan for secrets
git-secrets --scan

# Security audit
gosec ./...

# Dependency vulnerabilities
go list -json -m all | nancy sleuth

# Check for hardcoded credentials
grep -r "password\|secret\|key" --exclude-dir=.git .