mev-beta/OPENCODE.md

# MEV Bot Project - OpenCode Context

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

## Code Quality and Testing Standards

### Go Best Practices
1. **Error Handling**
   - Use Go's error wrapping with context: `fmt.Errorf("failed to process transaction: %w", err)`
   - Implement retry mechanisms with exponential backoff for transient failures
   - Handle timeouts appropriately with context cancellation
   - Log errors at appropriate levels (debug, info, warn, error)

2. **Concurrency Safety**
   - Use mutexes correctly to protect shared data
   - Avoid race conditions with proper synchronization
   - Use channels for communication between goroutines
   - Implement graceful shutdown procedures

3. **Code Structure**
   - Follow idiomatic Go patterns and conventions
   - Use clear, descriptive names for variables, functions, and types
   - Organize code into logical packages with clear responsibilities
   - Implement interfaces for loose coupling between components

4. **Performance Considerations**
   - Minimize memory allocations in hot paths
   - Use appropriate data structures for the task
   - Profile code regularly to identify bottlenecks
   - Follow the performance requirements (latency < 10 microseconds for critical path)

### Testing Standards
1. **Unit Testing**
   - Write tests for all functions and methods
   - Use table-driven tests for multiple test cases
   - Mock external dependencies for deterministic testing
   - Test edge cases and boundary conditions

2. **Integration Testing**
   - Test component interactions and data flow
   - Verify correct behavior with real (or realistic) data
   - Test error conditions and recovery mechanisms
   - Validate configuration loading and environment variable overrides

3. **Property-Based Testing**
   - Use property-based testing for mathematical functions
   - Verify invariants and mathematical relationships
   - Test with randomized inputs to find edge cases
   - Ensure numerical stability and precision

4. **Benchmarking**
   - Create benchmarks for performance-critical code paths
   - Measure latency and throughput for core functionality
   - Compare performance before and after optimizations
   - Identify bottlenecks in the processing pipeline

### Documentation Standards
1. **Code Comments**
   - Comment all exported functions, types, and variables
   - Explain complex algorithms and mathematical calculations
   - Document any non-obvious implementation decisions
   - Keep comments up-to-date with code changes

2. **API Documentation**
   - Provide clear usage examples for public APIs
   - Document expected inputs and outputs
   - Explain error conditions and return values
   - Include performance characteristics where relevant

3. **Architecture Documentation**
   - Maintain up-to-date architectural diagrams
   - Document data flow between components
   - Explain design decisions and trade-offs
   - Provide deployment and configuration guides

## Debugging and Troubleshooting

### Common Issues and Solutions
1. **Rate Limiting Problems**
   - Monitor RPC call rates and adjust configuration
   - Implement proper fallback mechanisms for RPC endpoints
   - Use caching to reduce duplicate requests

2. **Concurrency Issues**
   - Use race detection tools during testing
   - Implement proper locking for shared data
   - Avoid deadlocks with careful resource ordering

3. **Precision Errors**
   - Use appropriate data types for mathematical calculations
   - Validate results against known test cases
   - Handle overflow and underflow conditions properly

### Debugging Tools and Techniques
1. **Logging**
   - Use structured logging with appropriate levels
   - Include contextual information in log messages
   - Implement log sampling for high-frequency events

2. **Profiling**
   - Use Go's built-in profiling tools (pprof)
   - Monitor CPU, memory, and goroutine usage
   - Identify hot paths and optimization opportunities

3. **Testing Utilities**
   - Use the test utilities in `pkg/test`
   - Create realistic test data for validation
   - Implement integration tests for end-to-end validation

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

1. **Writing and Debugging Go Code**
   - Implementing clean, idiomatic Go code
   - Following established patterns and conventions
   - Debugging complex concurrency issues
   - Optimizing code for performance and readability

2. **Implementing Test Cases and Ensuring Code Quality**
   - Writing comprehensive unit and integration tests
   - Implementing property-based tests for mathematical functions
   - Creating performance benchmarks for critical paths
   - Ensuring proper error handling and recovery

3. **Following Established Coding Patterns and Conventions**
   - Using appropriate design patterns (worker pools, pipelines, etc.)
   - Following Go's idiomatic patterns and best practices
   - Implementing consistent error handling and logging
   - Maintaining code organization and package structure

4. **Identifying and Fixing Bugs**
   - Debugging race conditions and concurrency issues
   - Identifying performance bottlenecks
   - Fixing precision errors in mathematical calculations
   - Resolving configuration and deployment issues

5. **Ensuring Code is Well-Structured and Readable**
   - Organizing code into logical packages with clear responsibilities
   - Using clear, descriptive naming conventions
   - Implementing proper abstraction and encapsulation
   - Maintaining consistency across the codebase

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