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