# 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

```bash
# 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

```bash
# 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](docs/planning/02_PROTOCOL_SUPPORT_REQUIREMENTS.md) 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](docs/planning/04_PROFITABILITY_PLAN.md) for details.

## Testing

### Coverage Requirements

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

```bash
# 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](docs/planning/03_TESTING_REQUIREMENTS.md) 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

```bash
# Run full CI/CD locally
make validate

# Quick pre-commit check
make pre-commit

# Format and test
make fmt test
```

See [CI/CD Setup](docs/planning/05_CI_CD_SETUP.md) for details.

## Configuration

### Environment Variables

```bash
# 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:

```bash
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](docs/planning/00_V2_MASTER_PLAN.md) - Complete architecture
- [Modularity Requirements](docs/planning/01_MODULARITY_REQUIREMENTS.md) - Component independence
- [Protocol Support](docs/planning/02_PROTOCOL_SUPPORT_REQUIREMENTS.md) - DEX protocols
- [Testing Requirements](docs/planning/03_TESTING_REQUIREMENTS.md) - Test coverage
- [Profitability Plan](docs/planning/04_PROFITABILITY_PLAN.md) - MEV strategy
- [CI/CD Setup](docs/planning/05_CI_CD_SETUP.md) - Pipeline details
- [CLAUDE.md](CLAUDE.md) - Project guidance for Claude Code

## License

[Your License Here]

## Support

- GitHub Issues: [Issues](https://github.com/your-org/mev-bot/issues)
- Documentation: [docs/](docs/)

---

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