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/](.claude/) directory which contains:
- [.claude/CLAUDE.md](.claude/CLAUDE.md) - Complete Claude Code CLI configuration
- [.claude/commands/](.claude/commands/) - Slash commands for Claude Code
- [.claude/scripts/](.claude/scripts/) - Scripts for Claude Code development workflow

## 🚀 Quick Start Commands

### Essential Build & Test Commands
```bash
# 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
```bash
# Setup development environment
export ARBITRUM_RPC_ENDPOINT="wss://arbitrum-mainnet.core.chainstack.com/f69d14406bc00700da9b936504e1a870"
export ARBITRUM_WS_ENDPOINT="wss://arbitrum-mainnet.core.chainstack.com/f69d14406bc00700da9b936504e1a870"
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
```bash
# 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
```bash
# 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
```bash
# Arbitrum RPC Configuration
export ARBITRUM_RPC_ENDPOINT="wss://arbitrum-mainnet.core.chainstack.com/f69d14406bc00700da9b936504e1a870"
export ARBITRUM_WS_ENDPOINT="wss://arbitrum-mainnet.core.chainstack.com/f69d14406bc00700da9b936504e1a870"

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