mev-beta/QWEN.md

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