diff --git a/CLAUDE.md b/CLAUDE.md index 65743b6..8a0d9cc 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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 diff --git a/GEMINI.md b/GEMINI.md index bd12448..57e8756 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -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. \ No newline at end of file +For complete development guidelines, system architecture details, and comprehensive configuration information, please refer to [CLAUDE.md](CLAUDE.md). \ No newline at end of file diff --git a/OPENCODE.md b/OPENCODE.md index 79dfca2..cf6c0b8 100644 --- a/OPENCODE.md +++ b/OPENCODE.md @@ -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. \ No newline at end of file +For complete development guidelines, system architecture details, and comprehensive configuration information, please refer to [CLAUDE.md](CLAUDE.md). \ No newline at end of file diff --git a/QWEN.md b/QWEN.md index f4bda27..36a7493 100644 --- a/QWEN.md +++ b/QWEN.md @@ -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 \ No newline at end of file +For complete development guidelines, system architecture details, and comprehensive configuration information, please refer to [CLAUDE.md](CLAUDE.md). \ No newline at end of file diff --git a/README.md b/README.md index 6173bf8..1cc5741 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/docs/project-summary.md b/docs/project-summary.md index 6aec63d..211c27f 100644 --- a/docs/project-summary.md +++ b/docs/project-summary.md @@ -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. \ No newline at end of file +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. \ No newline at end of file