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

6
CLAUDE.md
View File

@@ -2,6 +2,11 @@
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
@@ -66,6 +71,7 @@ This is an MEV (Maximal Extractable Value) bot written in Go 1.24+ that monitors
- `@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

104
GEMINI.md
View File

@@ -2,6 +2,8 @@
This file contains context information for Gemini 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,84 +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
## Mathematical Implementation Details
### Uniswap V3 Pricing Functions
The core of the MEV bot's functionality relies on precise Uniswap V3 pricing calculations:
1. **sqrtPriceX96 to Price Conversion**
- Formula: `price = (sqrtPriceX96 / 2^96)^2`
- Implementation uses `math/big` for precision
- Critical for accurate price impact calculations
2. **Price to sqrtPriceX96 Conversion**
- Formula: `sqrtPriceX96 = sqrt(price) * 2^96`
- Used when initializing or updating pool states
- Requires careful handling of floating-point precision
3. **Tick Calculations**
- Formula: `tick = log_1.0001(sqrtPriceX96 / 2^96)^2`
- Ticks range from -887272 to 887272
- Used for discrete price levels in Uniswap V3
4. **Price Impact Calculations**
- Based on liquidity and amount being swapped
- Formula: `priceImpact = amountIn / liquidity`
- Critical for determining arbitrage profitability
### Precision Handling
- Uses `github.com/holiman/uint256` for precise uint256 arithmetic
- Implements proper rounding strategies
- Handles overflow and underflow conditions
- Maintains precision throughout calculations
## Performance Optimization Areas
### Concurrency Patterns
1. **Worker Pools**
- Used in `pkg/scanner` for concurrent event processing
- Configurable number of workers based on system resources
- Channel-based job distribution
2. **Pipeline Processing**
- Multi-stage processing in `pkg/market`
- Parallel processing of different transaction batches
- Backpressure handling through channel buffering
3. **Caching Strategies**
- Singleflight pattern to prevent duplicate requests
- Time-based expiration for cached pool data
- Memory-efficient data structures
### Low-Level Optimizations
1. **Memory Allocation Reduction**
- Object pooling for frequently created objects
- Pre-allocation of slices and maps when size is known
- Reuse of buffers and temporary variables
2. **Algorithmic Efficiency**
- O(1) lookups for cached pool data
- Efficient sorting and searching algorithms
- Minimal computational overhead in hot paths
3. **System-Level Optimizations**
- Proper tuning of Go's garbage collector
- NUMA-aware memory allocation (if applicable)
- CPU cache-friendly data access patterns
## Gemini's Primary Focus Areas
As Gemini, you're particularly skilled at:
@@ -109,30 +33,12 @@ As Gemini, you're particularly skilled at:
- Implementing precise Uniswap V3 pricing functions
- Optimizing mathematical calculations for performance
- Ensuring numerical stability and precision
- Creating efficient algorithms for arbitrage detection
2. **Optimizing Performance and Efficiency**
2. **Performance Optimization**
- Profiling and identifying bottlenecks in critical paths
- Reducing memory allocations in hot code paths
- Optimizing concurrency patterns for maximum throughput
- Tuning garbage collection for low-latency requirements
3. **Understanding Complex Uniswap V3 Pricing Functions**
- Implementing accurate tick and sqrtPriceX96 conversions
- Calculating price impact with proper precision handling
- Working with liquidity and fee calculations
- Handling edge cases in pricing mathematics
When working on this project, please focus on these areas where your strengths will be most beneficial.
4. **Implementing Concurrent and Parallel Processing Patterns**
- Designing efficient worker pool implementations
- Creating robust pipeline processing systems
- Managing synchronization primitives correctly
- Preventing race conditions and deadlocks
5. **Working with Low-Level System Operations**
- Optimizing memory usage and allocation patterns
- Tuning system-level parameters for performance
- Implementing efficient data structures for high-frequency access
- Working with CPU cache optimization techniques
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).

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).

125
QWEN.md
View File

@@ -2,6 +2,15 @@
This file contains context information for Qwen Code 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.
For Qwen Code-specific configuration, commands, and development guidelines, please refer to the [.qwen/](.qwen/) directory which contains:
- [.qwen/QWEN.md](.qwen/QWEN.md) - Complete Qwen Code configuration and context
- [.qwen/commands/](.qwen/commands/) - Slash commands for Qwen Code
- [.qwen/config/](.qwen/config/) - Configuration files for Qwen Code
- [.qwen/prompts/](.qwen/prompts/) - Qwen Code specific prompts
- [.qwen/scripts/](.qwen/scripts/) - Scripts for Qwen Code development workflow
## 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,111 +33,21 @@ This is an MEV (Maximal Extractable Value) bot written in Go 1.24+ that monitors
- `@prompts/` - AI prompts for development assistance
- `docs/` - Documentation
- `scripts/` - Scripts for building, testing, and deployment
- `.qwen/` - Qwen Code specific configuration and tools
## Technologies
- Go 1.24+
- Arbitrum sequencer monitoring via Ethereum JSON-RPC
- Uniswap V3 pricing functions (price to tick, sqrtPriceX96 to tick, etc.)
- Multiple transport mechanisms (shared memory, Unix sockets, TCP, WebSockets, gRPC)
- Concurrency patterns (worker pools, pipelines, fan-in/fan-out)
- Ethereum client library (github.com/ethereum/go-ethereum)
- Uint256 arithmetic (github.com/holiman/uint256)
- Rate limiting (golang.org/x/time/rate)
- Extended concurrency primitives (golang.org/x/sync)
- CLI framework (github.com/urfave/cli/v2)
- YAML parsing (gopkg.in/yaml.v3)
## Qwen Code's Primary Focus Areas
As Qwen Code, you're particularly skilled at:
## Core Components
1. **Mathematical Computations**
- Implementing precise Uniswap V3 pricing functions
- Ensuring numerical stability and precision
- Working with liquidity and fee calculations
### 1. Configuration Management (`internal/config`)
Handles loading configuration from YAML files with environment variable overrides. Supports multiple environments and rate limiting configurations for RPC endpoints.
2. **Algorithmic Implementation**
- Creating efficient algorithms for arbitrage detection
- Implementing accurate tick and sqrtPriceX96 conversions
- Calculating price impact with proper precision handling
### 2. Event Processing (`pkg/events`)
Parses Ethereum transactions to identify DEX interactions and extracts relevant event data including swap amounts, pool addresses, and pricing information.
When working on this project, please focus on these areas where your strengths will be most beneficial.
### 3. Market Pipeline (`pkg/market`)
Implements a multi-stage processing pipeline for transactions:
- Transaction decoding and event parsing
- Market analysis using Uniswap V3 math
- Arbitrage opportunity detection
### 4. Arbitrum Monitor (`pkg/monitor`)
Monitors the Arbitrum sequencer for new blocks and transactions, with rate limiting and concurrent processing support.
### 5. Market Scanner (`pkg/scanner`)
Uses a worker pool pattern to analyze market events for potential arbitrage opportunities with caching and concurrency support.
### 6. Uniswap Pricing (`pkg/uniswap`)
Implements Uniswap V3 pricing functions for converting between sqrtPriceX96, ticks, and actual prices.
## System Architecture
### Data Flow
1. Arbitrum Monitor detects new blocks and transactions
2. Events are parsed from transactions by the Event Parser
3. Transactions flow through the Market Pipeline for processing
4. Market Scanner analyzes events for arbitrage opportunities
5. Profitable opportunities are identified and potentially executed
### Concurrency Model
The system uses several concurrency patterns to achieve high throughput:
- Worker pools for parallel transaction processing
- Pipelines for multi-stage processing
- Fan-in/fan-out patterns for distributing work
- Rate limiting to prevent overwhelming RPC endpoints
- Caching with singleflight to prevent duplicate requests
### Communication Patterns
- Pipeline pattern for multi-stage transaction processing
- Worker pool pattern for concurrent event analysis
- Message passing through Go channels
- Shared memory access with proper synchronization
## Mathematical Implementation
### Uniswap V3 Pricing
The system implements precise Uniswap V3 pricing calculations:
- sqrtPriceX96 to price conversion: `price = (sqrtPriceX96 / 2^96)^2`
- Price to sqrtPriceX96 conversion: `sqrtPriceX96 = sqrt(price) * 2^96`
- Tick calculations: `tick = log_1.0001(sqrtPriceX96 / 2^96)^2`
- Price impact calculations using liquidity values
### Precision Handling
- Uses `github.com/holiman/uint256` for precise uint256 arithmetic
- Uses `math/big` for floating-point calculations when needed
- Implements proper rounding and precision handling
## Development Notes
- Focus on off-chain price movement calculations using precise Uniswap V3 mathematics
- Refer to official Uniswap V3 documentation for pricing functions and pool mechanics
- Implement market scanning functionality for potential arbitrage opportunities
- Follow the modular architecture with independent components
- Use the universal message bus for inter-module communication
- Adhere to the standards defined in @prompts/COMMON.md
- Pay attention to performance requirements (latency < 10 microseconds for critical path)
- Implement proper error handling with context wrapping and retry mechanisms
- Ensure comprehensive test coverage including unit tests, integration tests, and benchmarks
## Integration Points
- Configuration management via `internal/config`
- Event processing through `pkg/events` and `pkg/market`
- Communication layer via the pipeline pattern in `pkg/market`
- Data persistence through the market manager in `pkg/market`
- Monitoring and metrics collection via the logger in `internal/logger`
- Rate limiting via `internal/ratelimit`
## Performance Considerations
- Use worker pools for concurrent transaction processing
- Implement caching for pool data to reduce RPC calls
- Apply rate limiting to prevent exceeding RPC provider limits
- Use uint256 arithmetic for precise calculations
- Minimize memory allocations in hot paths
- Profile code regularly to identify bottlenecks
- Optimize critical path for sub-10 microsecond latency
## Testing Approach
- Unit tests for all mathematical functions and core logic
- Integration tests for component interactions
- Performance benchmarks for critical paths
- Property-based testing for mathematical correctness
- Mock external dependencies for deterministic testing
For complete development guidelines, system architecture details, and comprehensive configuration information, please refer to [CLAUDE.md](CLAUDE.md).

34
README.md
View File

@@ -49,11 +49,37 @@ Configuration files can be found in the `config/` directory.
├── go.mod # Go module definition
├── go.sum # Go module checksums
├── README.md # This file
└── QWEN.md # Qwen Code context file
├── .claude/ # Claude Code specific configuration and tools
├── .gemini/ # Gemini specific configuration and tools
├── .opencode/ # OpenCode specific configuration and tools
├── .qwen/ # Qwen Code specific configuration and tools
├── CLAUDE.md # Complete project documentation and Claude context (comprehensive example)
├── GEMINI.md # Gemini context (simplified, references CLAUDE.md)
├── OPENCODE.md # OpenCode context (simplified, references CLAUDE.md)
└── QWEN.md # Qwen Code context (simplified, references CLAUDE.md)
```
## Development
### AI Assistant CLI Configurations
This project is configured to work with multiple AI coding assistants, each with specialized expertise:
- **Claude** (`.claude/`) - System architecture, design patterns, and integration
- **OpenCode** (`.opencode/`) - Multi-language development and testing
- **Qwen Code** (`.qwen/`) - Mathematical computations and precision handling
- **Gemini** (`.gemini/`) - Performance optimization and concurrency
### Git Workflow
This project follows a comprehensive Git workflow with specific branch strategies, commit conventions, and automated checks. See [docs/GIT_WORKFLOW.md](docs/GIT_WORKFLOW.md) and [docs/BRANCH_STRATEGY.md](docs/BRANCH_STRATEGY.md) for detailed information.
Key aspects:
- **Branch Strategy**: `main`, `develop`, `feature/*`, `fix/*`, `release/*`, `hotfix/*`
- **Commit Messages**: Conventional commits format
- **Git Hooks**: Pre-commit and pre-push checks
- **Pull Requests**: Required for all merges to `main` and `develop`
### Prompts Directory
The `@prompts/` directory contains prompts that can be used with AI coding assistants for various development tasks.
@@ -61,10 +87,10 @@ The `@prompts/` directory contains prompts that can be used with AI coding assis
### Contributing
1. Fork the repository
2. Create a feature branch
3. Commit your changes
2. Create a feature branch following the branch naming conventions
3. Commit your changes with conventional commit messages
4. Push to the branch
5. Create a Pull Request
5. Create a Pull Request with detailed description
## License

7
docs/project-summary.md
View File

@@ -49,7 +49,10 @@ This document provides a summary of the MEV bot project structure and components
│ │ └── scanner.go
│ └── uniswap/
│ └── pricing.go
├── QWEN.md # Qwen Code context file
├── CLAUDE.md # Complete project documentation and Claude context (comprehensive example)
├── GEMINI.md # Gemini context (simplified, references CLAUDE.md)
├── OPENCODE.md # OpenCode context (simplified, references CLAUDE.md)
├── QWEN.md # Qwen Code context (simplified, references CLAUDE.md)
├── README.md # Project overview
└── scripts/ # Scripts for building, testing, and deployment
├── build.sh
@@ -100,4 +103,4 @@ This document provides a summary of the MEV bot project structure and components
## Development
Use the prompts in the `@prompts/` directory with your AI coding assistant for help with specific aspects of the project.
Use the prompts in the `@prompts/` directory with your AI coding assistant for help with specific aspects of the project. For complete documentation, refer to CLAUDE.md which contains the comprehensive project documentation.