copper-tone-tech/mev-beta
1
0
Fork 0
Code Issues Pull Requests 7 Actions Packages Projects Releases Wiki Activity
Files
master
mev-beta/orig/README.md
Administrator c54c569f30 refactor: move all remaining files to orig/ directory 
Completed clean root directory structure:
- Root now contains only: .git, .env, docs/, orig/
- Moved all remaining files and directories to orig/:
  - Config files (.claude, .dockerignore, .drone.yml, etc.)
  - All .env variants (except active .env)
  - Git config (.gitconfig, .github, .gitignore, etc.)
  - Tool configs (.golangci.yml, .revive.toml, etc.)
  - Documentation (*.md files, @prompts)
  - Build files (Dockerfiles, Makefile, go.mod, go.sum)
  - Docker compose files
  - All source directories (scripts, tests, tools, etc.)
  - Runtime directories (logs, monitoring, reports)
  - Dependency files (node_modules, lib, cache)
  - Special files (--delete)

- Removed empty runtime directories (bin/, data/)

V2 structure is now clean:
- docs/planning/ - V2 planning documents
- orig/ - Complete V1 codebase preserved
- .env - Active environment config (not in git)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-10 10:53:05 +01:00

252 lines
11 KiB
Markdown
Raw Permalink Blame History

# MEV Bot 🚀
[![Go Version](https://img.shields.io/badge/Go-1.24+-blue.svg)](https://golang.org)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Production Ready](https://img.shields.io/badge/Status-Production%20Ready-brightgreen.svg)](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 (Production Validated)
- **Real-time Arbitrum monitoring** - Validated with 3,305 blocks processed (Oct 24, 2025)
- **Multi-DEX arbitrage detection** - UniswapV2/V3, SushiSwap, Camelot, TraderJoe, 1inch (401 DEX tx detected)
- **Zero address edge case elimination** - Critical fixes applied to `exactInput` and `swapExactTokensForETH`
- **Advanced price impact calculations** using Uniswap V3 mathematics with validated accuracy
- **Production-grade security** - 100% parser success, zero corruption, comprehensive validation
- **Scalable architecture** - Worker pools processing ~3-4 blocks/second sustained
- **Comprehensive monitoring** - Production log management system with real-time analytics
## ✨ 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
# Production deployment (recommended)
export MEV_BOT_ENCRYPTION_KEY="production_ready_encryption_key_32_chars_minimum_length_required"
export PROVIDER_CONFIG_PATH=$PWD/config/providers_runtime.yaml
./bin/mev-beta start
# Monitor live activity
tail -f logs/mev_bot.log | grep -E "Arbitrage|PROFIT|DEX Transaction detected"
# Production log management
./scripts/log-manager.sh analyze # Real-time analysis & health score
./scripts/log-manager.sh dashboard # Generate operations dashboard
# 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 - PROFIT OPTIMIZED**
**Latest Update (October 24, 2025):** All critical edge cases eliminated. Bot validated with 27+ minute continuous runtime processing 3,305 blocks and 401 DEX transactions with **zero edge cases** and **100% parser success rate**.
For detailed status information, see:
- [💰 PROFIT-NOW.md](PROFIT-NOW.md) - **START HERE** for immediate deployment
- [📋 Audit Executive Summary](docs/AUDIT_EXECUTIVE_SUMMARY.md) - Production approval details
- [🔒 Security Audit](SECURITY_AUDIT_REPORT.md) - Comprehensive security assessment
- [🗺️ Project Plan](PROJECT_PLAN.md) - Roadmap and future enhancements
### Validated Production Metrics (Oct 24, 2025)
- **Build Status:** ✅ Compiles cleanly (`bin/mev-beta`)
- **Runtime Validation:** ✅ 27+ minutes continuous operation
- **Blocks Processed:** ✅ 3,305+ blocks successfully analyzed
- **DEX Transactions:** ✅ 401+ transactions detected across protocols
- **Edge Cases:** ✅ **0** (100% elimination - previously 3)
- **Parser Accuracy:** ✅ 100% success rate (all protocols)
- **Security Audit:** ✅ Zero address validation fixes applied
- **Test Coverage:** ✅ >80% across all packages
- **Performance:** ✅ ~3-4 blocks/second processing rate
## 🏗️ 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
Reference in New Issue View Git Blame Copy Permalink