134 lines
6.4 KiB
Markdown
134 lines
6.4 KiB
Markdown
# MEV Bot Project - Qwen Code Context
|
|
|
|
This file contains context information for Qwen Code 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
|
|
- `cmd/mev-bot/main.go` - Entry point for the MEV bot application
|
|
- `internal/` - Private application and library code
|
|
- `internal/config` - Configuration management using YAML files with environment variable overrides
|
|
- `internal/logger` - Logging functionality
|
|
- `internal/ratelimit` - Rate limiting implementations for RPC calls
|
|
- `internal/utils` - Utility functions
|
|
- `pkg/` - Library code that can be used by external projects
|
|
- `pkg/events` - Event parsing and processing for DEX interactions
|
|
- `pkg/market` - Market data handling, pool management, and pipeline processing
|
|
- `pkg/monitor` - Arbitrum sequencer monitoring with concurrency support
|
|
- `pkg/scanner` - Market scanning functionality with concurrent worker pools
|
|
- `pkg/test` - Test utilities and helpers
|
|
- `pkg/uniswap` - Uniswap V3 specific pricing functions and calculations
|
|
- `config/` - Configuration files (YAML format with development and production variants)
|
|
- `@prompts/` - AI prompts for development assistance
|
|
- `docs/` - Documentation
|
|
- `scripts/` - Scripts for building, testing, and deployment
|
|
|
|
## 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)
|
|
|
|
## Core Components
|
|
|
|
### 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. Event Processing (`pkg/events`)
|
|
Parses Ethereum transactions to identify DEX interactions and extracts relevant event data including swap amounts, pool addresses, and pricing information.
|
|
|
|
### 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 |