mev-beta/docs/MEV_BOT_APPLICATION.md

MEV Bot Application Documentation

Overview

The MEV Bot is a Go application that monitors the Arbitrum sequencer for swap opportunities and executes arbitrage strategies to capture Maximal Extractable Value (MEV). The application provides two main modes of operation: continuous monitoring and one-time scanning.

Command Line Interface

The application uses the urfave/cli/v2 library for command line parsing. It supports the following commands:

start - Start the MEV Bot

Starts the MEV bot in continuous monitoring mode. The bot will:

1. Connect to the Arbitrum network
2. Monitor the sequencer for Uniswap V3 swap events
3. Detect arbitrage opportunities
4. Execute profitable trades
5. Log statistics and performance metrics

Usage:

./mev-bot start

scan - Scan for Opportunities

Performs a one-time scan for arbitrage opportunities without executing trades. This mode is useful for:

1. Testing the detection algorithms
2. Analyzing market conditions
3. Validating configuration parameters

Usage:

./mev-bot scan

Application Flow

1. Configuration Loading

The application loads configuration from YAML files in the following priority order:

1. config/arbitrum_production.yaml (if exists)
2. config/local.yaml (if exists)
3. config/config.yaml (default)

2. Environment Validation

Before connecting to the network, the application validates:

• RPC endpoint URL format and security
• Required environment variables
• Network connectivity

3. Component Initialization

The application initializes the following components:

• Logger - Structured logging system
• Metrics Collector - Performance metrics collection
• Ethereum Client - Connection to Arbitrum network
• Key Manager - Secure key management
• Arbitrage Database - SQLite database for persistence
• Arbitrage Service - Core arbitrage detection and execution engine

4. Service Startup

The arbitrage service is started with:

• Blockchain monitoring
• Statistics collection
• Market data synchronization

5. Operation Mode

Continuous Mode (start)

• Runs indefinitely until interrupted
• Monitors for swap events in real-time
• Executes profitable arbitrage opportunities
• Updates statistics periodically
• Handles graceful shutdown on interrupt signals

Scan Mode (scan)

• Runs for a fixed duration (30 seconds)
• Detects arbitrage opportunities without execution
• Reports findings to console and logs
• Exits after scan completion

Environment Variables

Required Variables

1. MEV_BOT_ENCRYPTION_KEY - Encryption key for secure key management
   • Must be set for both modes
   • Should be a strong, randomly generated key

Optional Variables

1. MEV_BOT_KEYSTORE_PATH - Path to keystore directory (default: "keystore")
2. MEV_BOT_AUDIT_LOG - Path to audit log file (default: "logs/audit.log")
3. MEV_BOT_BACKUP_PATH - Path to backup directory (default: "backups")
4. MEV_BOT_ALLOW_LOCALHOST - Allow localhost RPC endpoints (default: false)
5. METRICS_ENABLED - Enable metrics server (default: false)
6. METRICS_PORT - Port for metrics server (default: "9090")

Security Features

Key Management

• Encrypted storage of private keys
• Key rotation policies
• Rate limiting for transaction signing
• Session timeout mechanisms
• Audit logging for all key operations

RPC Endpoint Validation

• URL format validation
• Scheme validation (http, https, ws, wss)
• Hostname validation
• localhost restriction in production

Secure Operations

• All sensitive operations require encryption key
• No plaintext key storage
• Secure memory handling

Logging and Monitoring

Log Levels

• Debug - Detailed debugging information
• Info - General operational information
• Warn - Warning conditions
• Error - Error conditions

Metrics Collection

When enabled, the application exposes metrics via HTTP server:

• Performance metrics
• Arbitrage statistics
• Resource utilization

Statistics

The application tracks and reports:

• Opportunities detected
• Executions attempted
• Successful executions
• Total profit realized
• Gas costs incurred

Graceful Shutdown

The application handles shutdown signals (SIGINT, SIGTERM) gracefully:

1. Stops blockchain monitoring
2. Waits for ongoing operations to complete
3. Flushes logs and metrics
4. Reports final statistics
5. Cleans up resources

Error Handling

Critical Errors

• Configuration loading failures
• Network connection failures
• Key management initialization failures
• Service startup failures

Recoverable Errors

• Individual transaction failures
• Temporary network issues
• Contract call failures
• Database operation failures

Performance Considerations

Resource Management

• Connection pooling for Ethereum client
• Efficient memory usage
• Goroutine management
• Context-based cancellation

Scalability

• Configurable concurrency limits
• Rate limiting for RPC calls
• Database connection pooling
• Efficient caching mechanisms

Testing and Validation

Unit Testing

• Individual function testing
• Edge case validation
• Error condition testing

Integration Testing

• End-to-end workflow testing
• Network interaction validation
• Performance benchmarking

Deployment

Production Deployment

1. Set required environment variables
2. Configure production YAML file
3. Ensure secure key storage
4. Monitor logs and metrics
5. Regular backup of database and keystore

Development Deployment

1. Use local configuration
2. Enable debug logging
3. Use testnet endpoints
4. Monitor development metrics

Troubleshooting

Common Issues

1. Missing Encryption Key

   • Error: "MEV_BOT_ENCRYPTION_KEY environment variable is required"
   • Solution: Set the encryption key environment variable

2. RPC Connection Failure

   • Error: "failed to connect to Ethereum client"
   • Solution: Verify RPC endpoint URL and network connectivity

3. Configuration Errors

   • Error: "failed to load config"
   • Solution: Check configuration file format and required fields

4. Permission Issues

   • Error: File access denied
   • Solution: Verify file permissions and user privileges

Log Analysis

• Check INFO level logs for operational status
• Check WARN level logs for potential issues
• Check ERROR level logs for failures
• Use DEBUG level for detailed troubleshooting

Best Practices

Security

• Never commit encryption keys to version control
• Use strong, randomly generated encryption keys
• Regularly rotate keys according to policy
• Monitor audit logs for suspicious activity

Performance

• Monitor resource usage
• Tune configuration parameters for your environment
• Use appropriate RPC endpoint with sufficient rate limits
• Regularly backup database and keystore

Operations

• Monitor logs for errors and warnings
• Enable metrics for performance tracking
• Regularly review statistics for optimization opportunities
• Test configuration changes in development first