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.