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

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

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