MEV Bot V2

A production-ready MEV (Maximal Extractable Value) bot for Arbitrum that leverages sequencer access to execute profitable arbitrage trades ahead of the chain.

Project Status: V2 Architecture Implementation

This repository is currently in V2 implementation phase. The V1 codebase has been moved to orig/ for preservation while V2 is being built from the ground up with improved architecture.

Current State:

• V1 implementation: orig/ (frozen for reference)
• V2 planning documents: docs/planning/
• V2 implementation: pkg/, cmd/, internal/ (in progress)
• CI/CD pipeline: Fully configured with 100% coverage enforcement

Quick Start

Prerequisites

• Go 1.25+
• Git
• Docker (optional)
• Access to Arbitrum RPC endpoint

Installation

# Clone the repository
git clone https://github.com/your-org/mev-bot.git
cd mev-bot

# Install development tools
make install-tools

# Install git hooks
./scripts/install-git-hooks.sh

# Build the application (when ready)
make build

Development

# Run tests with 100% coverage enforcement
make test-coverage

# Run linters
make lint

# Format code
make fmt

# Run full validation (CI/CD locally)
make validate

# Run benchmarks
make bench

Architecture

V2 Improvements Over V1

1. Per-Protocol Parsers - Individual parsers for each DEX (UniswapV2, UniswapV3, Curve, etc.)
2. Multi-Index Cache - O(1) lookups by address, token pair, protocol, and liquidity
3. 100% Test Coverage - Enforced in CI/CD pipeline
4. Comprehensive Validation - Multi-layer validation at parser, monitor, and scanner layers
5. Observable by Default - Prometheus metrics, structured logging, health monitoring
6. Sequencer Front-Running - Direct sequencer access for 100-500ms time advantage

Directory Structure

mev-bot/
├── cmd/                      # Application entry points
│   └── mev-bot/             # Main application
├── pkg/                      # Public library code
│   ├── types/               # Core data types (SwapEvent, PoolInfo, errors)
│   ├── parsers/             # Protocol-specific parsers
│   ├── cache/               # Multi-index pool cache
│   ├── validation/          # Validation pipeline
│   ├── observability/       # Logging and metrics
│   ├── arbitrage/           # Arbitrage detection
│   └── execution/           # Trade execution
├── internal/                 # Private application code
├── docs/                     # Documentation
│   └── planning/            # V2 planning documents
│       ├── 00_V2_MASTER_PLAN.md
│       ├── 01_MODULARITY_REQUIREMENTS.md
│       ├── 02_PROTOCOL_SUPPORT_REQUIREMENTS.md
│       ├── 03_TESTING_REQUIREMENTS.md
│       ├── 04_PROFITABILITY_PLAN.md
│       └── 05_CI_CD_SETUP.md
├── orig/                     # V1 codebase (reference)
├── .github/                  # GitHub Actions CI/CD
├── Makefile                  # Build automation
└── CLAUDE.md                 # Project guidance

Supported Protocols

V2 supports 13+ DEX protocols on Arbitrum:

• Uniswap V2 - Constant product AMM
• Uniswap V3 - Concentrated liquidity
• Uniswap V4 - (Planned)
• Curve - StableSwap
• Balancer V2 - Weighted pools
• Balancer V3 - (If deployed)
• Kyber Classic - Dynamic reserves
• Kyber Elastic - Concentrated liquidity
• Camelot V2 - Dynamic fees
• Camelot V3 - Algebra V1/V1.9/Integral/Directional

See Protocol Support Requirements for details.

Profitability

Target Metrics

• Latency: < 50ms from sequencer event to execution
• Success Rate: > 85% of executed trades profitable
• Average Profit: > 0.05 ETH per trade (after gas)
• Daily Volume: 50-200 trades per day
• ROI: > 20% monthly on deployed capital

Key Features

1. Sequencer Front-Running - Read pending transactions 100-500ms before on-chain
2. Multi-Hop Arbitrage - Find 2-4 hop profitable paths
3. Batch Execution - Save gas by combining opportunities
4. Dynamic Gas Optimization - Intelligent gas pricing
5. Risk Management - Slippage protection, circuit breakers, position sizing

See Profitability Plan for details.

Testing

Coverage Requirements

100% test coverage is mandatory and enforced in CI/CD.

# Run tests with coverage enforcement
make test-coverage

# Run specific tests
go test -v ./pkg/parsers/...

# Run benchmarks
make bench

Test Types

• Unit Tests - Every function tested independently
• Integration Tests - Components working together
• Decimal Precision Tests - Exact decimal handling validation
• Performance Benchmarks - Parser < 5ms, Detection < 10ms
• Edge Case Tests - Boundary conditions
• Concurrency Tests - Race detection

See Testing Requirements for details.

CI/CD Pipeline

Automated Checks

Every commit runs:

1. Pre-Flight - Branch naming, commit message format
2. Build - Compilation, dependency verification
3. Code Quality - 40+ linters (golangci-lint), security scanning
4. Unit Tests - 100% coverage enforcement (non-negotiable)
5. Integration Tests - Component interaction validation
6. Performance - Benchmark targets
7. Modularity - Component independence verification

Local Development

# Run full CI/CD locally
make validate

# Quick pre-commit check
make pre-commit

# Format and test
make fmt test

See CI/CD Setup for details.

Configuration

Environment Variables

# Arbitrum RPC
export ARBITRUM_RPC_ENDPOINT="wss://arb1.arbitrum.io/feed"
export ARBITRUM_WS_ENDPOINT="wss://arb1.arbitrum.io/feed"

# Application
export LOG_LEVEL="info"
export METRICS_ENABLED="true"
export METRICS_PORT="9090"

# Arbitrage
export MIN_PROFIT_USD="50.0"
export MAX_HOPS="4"
export MAX_GAS_PRICE="500000000000"

Contributing

Branch Naming

All V2 development MUST use feature branches:

feature/v2/<component>/<task-id>-<description>

# Examples:
feature/v2/parsers/P2-002-uniswap-v2-base
feature/v2/cache/P3-001-address-index
feature/v2/validation/P4-001-validation-rules

Commit Messages

type(scope): brief description

- Detailed explanation
- Why the change was needed
- Any breaking changes

🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>

Types: feat, fix, perf, refactor, test, docs, build, ci

Pull Requests

1. Create feature branch from feature/v2-prep
2. Make changes with tests (100% coverage required)
3. Run make validate locally
4. Push and create PR to feature/v2-prep
5. Wait for CI/CD to pass (all checks must be green)
6. Get 1 approval
7. Merge (squash and merge preferred)

Documentation

• V2 Master Plan - Complete architecture
• Modularity Requirements - Component independence
• Protocol Support - DEX protocols
• Testing Requirements - Test coverage
• Profitability Plan - MEV strategy
• CI/CD Setup - Pipeline details
• CLAUDE.md - Project guidance for Claude Code

License

[Your License Here]

Support

• GitHub Issues: Issues
• Documentation: docs/

---

Built with Claude Code | 100% Test Coverage | Production Ready