# MEV Bot

An MEV (Maximal Extractable Value) bot written in Go that monitors the Arbitrum sequencer for potential swap opportunities and identifies profitable arbitrage opportunities.

## Overview

This bot monitors the Arbitrum sequencer for attempted swaps and analyzes them to determine if they are large enough to create price movements that can be exploited for arbitrage. It uses off-chain methods to calculate price movements using Uniswap V3 pricing functions.

## Features

- Real-time monitoring of Arbitrum sequencer
- Detection of potential swap transactions
- Market scanning for price movement analysis
- Uniswap V3 pricing calculations (price to tick, sqrtPriceX96 to tick, etc.)
- Arbitrage opportunity identification
- Optimized mathematical functions for improved performance (see [Mathematical Optimizations](docs/7_reference/MATH_OPTIMIZATIONS.md))

## Prerequisites

- Go 1.24 or higher
- Access to Arbitrum node

## Installation

```bash
go mod tidy
```

## Usage

```bash
go run cmd/mev-bot/main.go
```

## Configuration

Configuration files can be found in the `config/` directory.

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

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