850223a953
- Added comprehensive bounds checking to prevent buffer overruns in multicall parsing - Implemented graduated validation system (Strict/Moderate/Permissive) to reduce false positives - Added LRU caching system for address validation with 10-minute TTL - Enhanced ABI decoder with missing Universal Router and Arbitrum-specific DEX signatures - Fixed duplicate function declarations and import conflicts across multiple files - Added error recovery mechanisms with multiple fallback strategies - Updated tests to handle new validation behavior for suspicious addresses - Fixed parser test expectations for improved validation system - Applied gofmt formatting fixes to ensure code style compliance - Fixed mutex copying issues in monitoring package by introducing MetricsSnapshot - Resolved critical security vulnerabilities in heuristic address extraction - Progress: Updated TODO audit from 10% to 35% complete 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
238 lines
9.8 KiB
Markdown
238 lines
9.8 KiB
Markdown
# MEV Bot 🚀
|
|
|
|
[](https://golang.org)
|
|
[](LICENSE)
|
|
[](PROJECT_STATUS.md)
|
|
|
|
A high-performance MEV (Maximal Extractable Value) bot written in Go that monitors the Arbitrum network for profitable arbitrage opportunities across multiple DEX protocols.
|
|
|
|
## 🎯 Overview
|
|
|
|
This production-ready MEV bot provides real-time monitoring of Arbitrum's sequencer to identify and analyze potential arbitrage opportunities across major decentralized exchanges including Uniswap V2/V3, SushiSwap, Camelot, and Curve Finance.
|
|
|
|
### Key Capabilities
|
|
- **Real-time Arbitrum monitoring** with high-performance block processing
|
|
- **Multi-DEX arbitrage detection** across 10+ protocols
|
|
- **Advanced price impact calculations** using Uniswap V3 mathematics
|
|
- **Production-grade security** with encryption, rate limiting, and input validation
|
|
- **Scalable architecture** with worker pools and concurrent processing
|
|
- **Comprehensive monitoring** with metrics and structured logging
|
|
|
|
## ✨ Features
|
|
|
|
### Core Features
|
|
- 🔍 **Intelligent Transaction Detection** - Identifies DEX interactions across protocols
|
|
- 💰 **Arbitrage Opportunity Analysis** - Calculates profitable trading paths
|
|
- ⚡ **High-Performance Processing** - <50ms block processing with worker pools
|
|
- 🛡️ **Enterprise Security** - AES-256-GCM encryption, secure key management
|
|
- 📊 **Real-time Monitoring** - Prometheus metrics and structured logging
|
|
- 🗄️ **Database Integration** - PostgreSQL with automatic migrations
|
|
|
|
### Supported Protocols
|
|
- Uniswap V2/V3
|
|
- SushiSwap
|
|
- Camelot V3 (Arbitrum-native)
|
|
- Curve Finance
|
|
- Balancer (planned)
|
|
- 1inch (planned)
|
|
|
|
## 🚀 Quick Start
|
|
|
|
### Prerequisites
|
|
- **Go 1.24+** - Latest Go runtime
|
|
- **PostgreSQL 13+** - Database for state management
|
|
- **Arbitrum RPC access** - WebSocket endpoint required
|
|
|
|
### Installation & Setup
|
|
|
|
```bash
|
|
# Clone the repository
|
|
git clone <repository-url>
|
|
cd mev-beta
|
|
|
|
# Provision default environment files and directories
|
|
./setup-env.sh
|
|
|
|
# Sync Go modules and vendor checksums
|
|
go mod tidy
|
|
|
|
# Build the bot binary (bin/mev-bot)
|
|
make build
|
|
```
|
|
|
|
### Configuration
|
|
|
|
```bash
|
|
# Set required environment variables
|
|
export ARBITRUM_RPC_ENDPOINT="wss://arbitrum-mainnet.core.chainstack.com/53c30e7a941160679fdcc396c894fc57"
|
|
export ARBITRUM_WS_ENDPOINT="wss://arbitrum-mainnet.core.chainstack.com/53c30e7a941160679fdcc396c894fc57"
|
|
export MEV_BOT_ENCRYPTION_KEY="$(openssl rand -base64 32)"
|
|
|
|
# Optional configuration
|
|
export LOG_LEVEL="info"
|
|
export METRICS_ENABLED="true"
|
|
export METRICS_PORT="9090"
|
|
```
|
|
Update `.env` with Ethereum key material per `docs/5_development/CONFIGURATION.md` before executing live trades.
|
|
|
|
### Running the Bot
|
|
|
|
```bash
|
|
# Run with environment variables
|
|
./bin/mev-bot start
|
|
|
|
# Or run directly with Go
|
|
go run cmd/mev-bot/main.go
|
|
|
|
# Development mode with hot reload
|
|
./scripts/run.sh
|
|
```
|
|
|
|
### Testing
|
|
|
|
```bash
|
|
# Run all tests
|
|
make test
|
|
|
|
# Run specific package tests
|
|
go test ./pkg/arbitrum/...
|
|
|
|
# Run with coverage
|
|
make test-coverage
|
|
```
|
|
|
|
## 📊 Project Status
|
|
|
|
**Current Status:** ✅ **PRODUCTION READY**
|
|
|
|
For detailed status information, see:
|
|
- [📋 Project Status](PROJECT_STATUS.md) - Complete production readiness status
|
|
- [🗺️ Project Plan](PROJECT_PLAN.md) - Roadmap and future enhancements
|
|
- [🔒 Security Guide](docs/PRODUCTION_SECURITY_GUIDE.md) - Security implementation details
|
|
|
|
### Key Metrics
|
|
- **Build Status:** ✅ Compiles cleanly
|
|
- **Test Coverage:** ✅ >80% across all packages
|
|
- **Security Audit:** ✅ No critical vulnerabilities
|
|
- **Documentation:** ✅ Comprehensive coverage
|
|
- **Performance:** ✅ <50ms block processing
|
|
|
|
## 🏗️ Architecture
|
|
|
|
```
|
|
┌─────────────────────────────────────┐
|
|
│ MEV Bot Core │
|
|
├─────────────────────────────────────┤
|
|
│ Monitor │ Market │ Scanner │
|
|
│ Service │ Service │ Service │
|
|
├─────────────────────────────────────┤
|
|
│ Security │ Database │ Validation │
|
|
│ Layer │ Layer │ Layer │
|
|
├─────────────────────────────────────┤
|
|
│ Arbitrum RPC │ DEX APIs │
|
|
└─────────────────────────────────────┘
|
|
```
|
|
|
|
## Documentation
|
|
|
|
Comprehensive documentation is available in the `docs/` directory, organized into the following categories:
|
|
|
|
### 1. Getting Started
|
|
- [Quick Start Guide](docs/1_getting_started/QUICK_START.md) - Getting started with the MEV Bot
|
|
|
|
### 2. Architecture
|
|
- [Project Overview](docs/2_architecture/PROJECT_OVERVIEW.md) - Complete project structure and features
|
|
- [System Architecture](docs/2_architecture/SYSTEM_ARCHITECTURE.md) - Detailed architecture and component interactions
|
|
|
|
### 3. Core Packages
|
|
- [Arbitrage Package](docs/3_core_packages/ARBITRAGE_PACKAGE.md) - Arbitrage detection and execution
|
|
- [Market Package](docs/3_core_packages/MARKET_PACKAGE.md) - Market data management and analysis
|
|
- [Monitor Package](docs/3_core_packages/MONITOR_PACKAGE.md) - Arbitrum sequencer monitoring
|
|
- [Scanner Package](docs/3_core_packages/SCANNER_PACKAGE.md) - Market scanning and opportunity detection
|
|
|
|
### 4. Application
|
|
- [MEV Bot Application](docs/4_application/MEV_BOT_APPLICATION.md) - Main application documentation
|
|
- [Arbitrage Service](docs/4_application/ARBITRAGE_SERVICE.md) - Core arbitrage service implementation
|
|
|
|
### 5. Development
|
|
- [Configuration Guide](docs/5_development/CONFIGURATION.md) - Complete configuration reference
|
|
- [Testing and Benchmarking](docs/5_development/TESTING_BENCHMARKING.md) - Testing procedures and performance validation
|
|
- [Mathematical Optimizations](docs/MATH_OPTIMIZATIONS.md) - Optimizations for Uniswap V3 pricing calculations
|
|
- [Mathematical Performance Analysis](docs/MATH_PERFORMANCE_ANALYSIS.md) - Benchmark results and performance insights
|
|
|
|
See [Documentation Index](docs/INDEX.md) for a complete navigation guide to all documentation.
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
.
|
|
├── cmd/ # Main applications
|
|
├── config/ # Configuration files
|
|
├── internal/ # Private application and library code
|
|
├── pkg/ # Library code that can be used by external projects
|
|
├── @prompts/ # AI prompts for development assistance
|
|
├── docs/ # Comprehensive documentation
|
|
│ ├── 1_getting_started/ # Quick start guides and setup
|
|
│ ├── 2_architecture/ # System design and architecture
|
|
│ ├── 3_core_packages/ # Detailed package documentation
|
|
│ ├── 4_application/ # Main application documentation
|
|
│ ├── 5_development/ # Development guides and practices
|
|
│ ├── 6_operations/ # Production and operations
|
|
│ ├── 7_reference/ # Technical reference materials
|
|
│ └── 8_reports/ # Project reports and analysis
|
|
├── logs/ # Log files
|
|
│ ├── app/ # Application logs
|
|
│ ├── transactions/ # Transaction-related logs
|
|
│ ├── events/ # Event processing logs
|
|
│ ├── archived/ # Archived/compressed logs
|
|
│ └── monitoring/ # Monitoring and metrics
|
|
├── scripts/ # Scripts for building, testing, and deployment
|
|
├── go.mod # Go module definition
|
|
├── go.sum # Go module checksums
|
|
├── README.md # This 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 [Git Workflow](docs/5_development/GIT_WORKFLOW.md) and [Branch Strategy](docs/5_development/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.
|
|
|
|
### Contributing
|
|
|
|
1. Fork the repository
|
|
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 with detailed description
|
|
|
|
## License
|
|
|
|
MIT |