# 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
- **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

```bash
# Clone the repository
git clone <repository-url>
cd mev-beta

# Install dependencies
go mod tidy

# Build the bot
make build

### Configuration

```bash
# Set required environment variables
export ARBITRUM_RPC_ENDPOINT="wss://arbitrum-mainnet.core.chainstack.com/f69d14406bc00700da9b936504e1a870"
export MEV_BOT_ENCRYPTION_KEY="$(openssl rand -base64 32)"

# Optional configuration
export LOG_LEVEL="info"
export METRICS_ENABLED="true"
export METRICS_PORT="9090"
```

### 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
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out
```

## 📊 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