copper-tone-tech/mev-beta
1
0
Fork 0
Code Issues Pull Requests 7 Actions Packages Projects Releases Wiki Activity

docs(architecture): update AI assistant documentation and project structure

Browse Source 
Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
This commit is contained in:
Krypto Kajun
2025-09-14 10:10:39 -05:00
parent a410f637cd
commit 5db7587923
6 changed files with 72 additions and 346 deletions
Download Patch File Download Diff File Expand all files Collapse all files

142
OPENCODE.md
View File

@@ -2,6 +2,8 @@
This file contains context information for OpenCode about the MEV Bot project.
**Note:** For a comprehensive understanding of the project structure, development guidelines, and AI assistant configuration, please refer to [CLAUDE.md](CLAUDE.md), which contains the complete project documentation.
## 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.
@@ -24,124 +26,6 @@ This is an MEV (Maximal Extractable Value) bot written in Go 1.24+ that monitors
- `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:
@@ -149,30 +33,12 @@ As OpenCode, you're particularly skilled at:
- 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
When working on this project, please focus on these areas where your strengths will be most beneficial.
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.
For complete development guidelines, system architecture details, and comprehensive configuration information, please refer to [CLAUDE.md](CLAUDE.md).