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

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