mev-beta/docs/5_development/CONFIGURATION.md

# MEV Bot Configuration Documentation

## Overview

The MEV Bot uses YAML configuration files to control its behavior. Configuration values can be specified directly in the YAML files or loaded from environment variables using the `${VARIABLE_NAME}` syntax.

## Configuration Files

The application loads configuration from the following files in priority order:
1. `config/arbitrum_production.yaml` (if exists)
2. `config/local.yaml` (if exists)
3. `config/config.yaml` (default)

## Configuration Sections

### Arbitrum Configuration

```yaml
arbitrum:
  rpc_endpoint: "${ARBITRUM_RPC_ENDPOINT}"
  ws_endpoint: "${ARBITRUM_WS_ENDPOINT}"
  chain_id: 42161
  rate_limit:
    requests_per_second: 10
    max_concurrent: 5
    burst: 20
  fallback_endpoints:
    - url: "${ARBITRUM_INFURA_ENDPOINT}"
      rate_limit:
        requests_per_second: 5
        max_concurrent: 3
        burst: 10
```

**Parameters:**
- **rpc_endpoint** - Primary RPC endpoint for Arbitrum
- **ws_endpoint** - WebSocket endpoint for real-time event monitoring
- **chain_id** - Chain ID (42161 for Arbitrum mainnet)
- **rate_limit** - Rate limiting for RPC calls
  - **requests_per_second** - Maximum requests per second
  - **max_concurrent** - Maximum concurrent requests
  - **burst** - Burst size for rate limiting
- **fallback_endpoints** - List of fallback RPC endpoints

### Bot Configuration

```yaml
bot:
  enabled: true
  polling_interval: 1
  min_profit_threshold: 10.0
  gas_price_multiplier: 1.2
  max_workers: 10
  channel_buffer_size: 100
  rpc_timeout: 30
```

**Parameters:**
- **enabled** - Enable/disable the bot
- **polling_interval** - Polling interval in seconds
- **min_profit_threshold** - Minimum profit threshold in USD
- **gas_price_multiplier** - Gas price multiplier for faster transactions
- **max_workers** - Maximum concurrent workers
- **channel_buffer_size** - Buffer size for channels
- **rpc_timeout** - Timeout for RPC calls in seconds

### Uniswap Configuration

```yaml
uniswap:
  factory_address: "0x1F98431c8aD98523631AE4a59f267346ea31F984"
  position_manager_address: "0xC36442b4a4522E871399CD717aBDD847Ab11FE88"
  fee_tiers: [500, 3000, 10000]
  cache:
    enabled: true
    expiration: 300
    max_size: 10000
```

**Parameters:**
- **factory_address** - Uniswap V3 factory contract address
- **position_manager_address** - Position manager contract address
- **fee_tiers** - Supported fee tiers
- **cache** - Cache configuration
  - **enabled** - Enable/disable caching
  - **expiration** - Cache expiration time in seconds
  - **max_size** - Maximum cache size

### Logging Configuration

```yaml
log:
  level: "debug"
  format: "text"
  file: "logs/mev-bot.log"
```

**Parameters:**
- **level** - Log level (debug, info, warn, error)
- **format** - Log format (json, text)
- **file** - Log file path (empty for stdout)

### Database Configuration

```yaml
database:
  file: "mev-bot.db"
  max_open_connections: 10
  max_idle_connections: 5
```

**Parameters:**
- **file** - Database file path
- **max_open_connections** - Maximum open connections
- **max_idle_connections** - Maximum idle connections

### Ethereum Configuration

```yaml
ethereum:
  private_key: "${ETHEREUM_PRIVATE_KEY}"
  account_address: "${ETHEREUM_ACCOUNT_ADDRESS}"
  gas_price_multiplier: 1.2
```

**Parameters:**
- **private_key** - Private key for transaction signing
- **account_address** - Account address
- **gas_price_multiplier** - Gas price multiplier

### Contracts Configuration

```yaml
contracts:
  arbitrage_executor: "0x..."
  flash_swapper: "0x..."
  authorized_callers:
    - "${ETHEREUM_ACCOUNT_ADDRESS}"
  authorized_dexes:
    - "0x1F98431c8aD98523631AE4a59f267346ea31F984"
```

**Parameters:**
- **arbitrage_executor** - Arbitrage executor contract address
- **flash_swapper** - Flash swapper contract address
- **authorized_callers** - Authorized caller addresses
- **authorized_dexes** - Authorized DEX addresses

### Arbitrage Configuration

```yaml
arbitrage:
  enabled: true
  arbitrage_contract_address: "0x0000000000000000000000000000000000000000"
  flash_swap_contract_address: "0x0000000000000000000000000000000000000000"
  min_profit_wei: 10000000000000000
  min_roi_percent: 1.0
  min_significant_swap_size: 1000000000000000000
  slippage_tolerance: 0.005
  min_scan_amount_wei: 100000000000000000
  max_scan_amount_wei: 10000000000000000000
  max_gas_price_wei: 100000000000
  max_concurrent_executions: 3
  max_opportunities_per_event: 5
  opportunity_ttl: 30s
  max_path_age: 60s
  stats_update_interval: 30s
```

**Parameters:**
- **enabled** - Enable/disable arbitrage service
- **arbitrage_contract_address** - Arbitrage contract address
- **flash_swap_contract_address** - Flash swap contract address
- **min_profit_wei** - Minimum profit threshold in wei
- **min_roi_percent** - Minimum ROI percentage
- **min_significant_swap_size** - Minimum swap size to trigger analysis
- **slippage_tolerance** - Slippage tolerance
- **min_scan_amount_wei** - Minimum scan amount in wei
- **max_scan_amount_wei** - Maximum scan amount in wei
- **max_gas_price_wei** - Maximum gas price in wei
- **max_concurrent_executions** - Maximum concurrent executions
- **max_opportunities_per_event** - Maximum opportunities per swap event
- **opportunity_ttl** - Opportunity time-to-live
- **max_path_age** - Maximum age of arbitrage paths
- **stats_update_interval** - Statistics update interval

## Environment Variables

### Required Variables

1. **ARBITRUM_RPC_ENDPOINT** - Arbitrum RPC endpoint
2. **ARBITRUM_WS_ENDPOINT** - Arbitrum WebSocket endpoint
3. **ETHEREUM_PRIVATE_KEY** - Private key for transaction signing
4. **ETHEREUM_ACCOUNT_ADDRESS** - Account address
5. **CONTRACT_ARBITRAGE_EXECUTOR** - Arbitrage executor contract address
6. **CONTRACT_FLASH_SWAPPER** - Flash swapper contract address

### Optional Variables

1. **ARBITRUM_INFURA_ENDPOINT** - Fallback RPC endpoint
2. **MEV_BOT_ENCRYPTION_KEY** - Encryption key for secure operations

## Security Considerations

### Private Key Management
- Never store private keys in configuration files
- Always use environment variables for sensitive data
- Ensure proper file permissions on configuration files
- Regularly rotate keys according to security policies

### RPC Endpoint Security
- Use secure WebSocket connections (wss://)
- Validate endpoint URLs
- Implement rate limiting
- Use fallback endpoints for high availability

## Best Practices

### Configuration Management
1. Use environment-specific configuration files
2. Store sensitive data in environment variables
3. Validate configuration on application startup
4. Document all configuration parameters
5. Use descriptive parameter names
6. Provide sensible default values

### Performance Tuning
1. Adjust rate limiting based on provider limits
2. Tune worker pool sizes for your hardware
3. Optimize cache settings for memory usage
4. Monitor resource utilization
5. Scale configuration with network conditions

### Monitoring and Logging
1. Use appropriate log levels for different environments
2. Enable detailed logging in development
3. Use structured logging for easier analysis
4. Log important configuration parameters at startup
5. Monitor configuration-related metrics

## Example Configuration

See `config/arbitrage_example.yaml` for a complete example configuration with all parameters and environment variable usage.