mev-beta/docs/3_core_packages/CONFIG_PACKAGE.md

Configuration Package Documentation

Overview

The configuration package provides a centralized configuration management system for the MEV Bot application. It handles loading configuration from YAML files, expanding environment variables, and validating configuration parameters.

Core Components

Config Structure

The main configuration structure contains all application settings:

1. Arbitrum - Arbitrum node configuration
2. Bot - Bot operational parameters
3. Uniswap - Uniswap protocol settings
4. Log - Logging configuration
5. Database - Database settings
6. Ethereum - Ethereum account configuration
7. Contracts - Smart contract addresses
8. Arbitrage - Arbitrage service configuration

Configuration Loading

The package provides a Load function that:

1. Reads configuration from a YAML file
2. Expands environment variables in the configuration
3. Applies environment variable overrides
4. Returns a validated configuration structure

Environment Variable Expansion

The package supports two formats for environment variable expansion:

• ${VARIABLE_NAME} - Standard format
• $VARIABLE_NAME - Simplified format

When environment variables are not set, they expand to empty strings to prevent invalid YAML.

Environment Variable Overrides

The package provides automatic overrides for key configuration parameters through environment variables:

• ARBITRUM_RPC_ENDPOINT - Primary RPC endpoint
• ARBITRUM_WS_ENDPOINT - WebSocket endpoint
• ARBITRUM_FALLBACK_ENDPOINTS - Comma-separated fallback endpoints
• RPC_REQUESTS_PER_SECOND - Rate limit requests per second
• RPC_MAX_CONCURRENT - Maximum concurrent requests
• BOT_MAX_WORKERS - Maximum bot workers
• BOT_CHANNEL_BUFFER_SIZE - Channel buffer size
• ETHEREUM_PRIVATE_KEY - Private key for transactions
• ETHEREUM_ACCOUNT_ADDRESS - Account address
• ETHEREUM_GAS_PRICE_MULTIPLIER - Gas price multiplier
• CONTRACT_ARBITRAGE_EXECUTOR - Arbitrage executor contract
• CONTRACT_FLASH_SWAPPER - Flash swapper contract

Configuration Structures

ArbitrumConfig

• RPCEndpoint - Primary RPC endpoint URL
• WSEndpoint - WebSocket endpoint URL
• ChainID - Chain identifier (42161 for Arbitrum)
• RateLimit - Rate limiting configuration
• FallbackEndpoints - List of fallback RPC endpoints

EndpointConfig

• URL - RPC endpoint URL
• RateLimit - Rate limiting for this endpoint

RateLimitConfig

• RequestsPerSecond - Maximum requests per second
• MaxConcurrent - Maximum concurrent requests
• Burst - Burst size for rate limiting

BotConfig

• Enabled - Enable/disable bot
• PollingInterval - Polling interval in seconds
• MinProfitThreshold - Minimum profit threshold in USD
• GasPriceMultiplier - Gas price multiplier
• MaxWorkers - Maximum concurrent workers
• ChannelBufferSize - Channel buffer size
• RPCTimeout - RPC call timeout in seconds

UniswapConfig

• FactoryAddress - Uniswap factory contract address
• PositionManagerAddress - Position manager address
• FeeTiers - Supported fee tiers
• Cache - Cache configuration

CacheConfig

• Enabled - Enable/disable caching
• Expiration - Cache expiration in seconds
• MaxSize - Maximum cache size

LogConfig

• Level - Log level (debug, info, warn, error)
• Format - Log format (json, text)
• File - Log file path

DatabaseConfig

• File - Database file path
• MaxOpenConnections - Maximum open connections
• MaxIdleConnections - Maximum idle connections

EthereumConfig

• PrivateKey - Private key for transactions
• AccountAddress - Account address
• GasPriceMultiplier - Gas price multiplier

ContractsConfig

• ArbitrageExecutor - Arbitrage executor contract address
• FlashSwapper - Flash swapper contract address
• AuthorizedCallers - Authorized caller addresses
• AuthorizedDEXes - Authorized DEX addresses

ArbitrageConfig

• Enabled - Enable/disable arbitrage service
• ArbitrageContractAddress - Arbitrage contract address
• FlashSwapContractAddress - Flash swap contract address
• MinProfitWei - Minimum profit in wei
• MinROIPercent - Minimum ROI percentage
• MinSignificantSwapSize - Minimum significant swap size
• SlippageTolerance - Slippage tolerance
• MinScanAmountWei - Minimum scan amount in wei
• MaxScanAmountWei - Maximum scan amount in wei
• MaxGasPriceWei - Maximum gas price in wei
• MaxConcurrentExecutions - Maximum concurrent executions
• MaxOpportunitiesPerEvent - Maximum opportunities per event
• OpportunityTTL - Opportunity time-to-live
• MaxPathAge - Maximum path age
• StatsUpdateInterval - Statistics update interval
• PoolDiscoveryConfig - Pool discovery configuration

PoolDiscoveryConfig

• Enabled - Enable/disable pool discovery
• BlockRange - Block range for scanning
• PollingInterval - Polling interval
• FactoryAddresses - DEX factory addresses
• MinLiquidityWei - Minimum liquidity threshold
• CacheSize - Cache size
• CacheTTL - Cache time-to-live

Functions

Load(filename string) (*Config, error)

Loads configuration from a YAML file:

1. Reads the file
2. Expands environment variables
3. Parses YAML
4. Applies environment variable overrides
5. Returns validated configuration

expandEnvVars(s string) string

Expands environment variables in a string using regex pattern matching.

OverrideWithEnv()

Applies environment variable overrides to the configuration.

ValidateEnvironmentVariables() error

Validates all required environment variables:

• Checks for required variables
• Validates RPC endpoint URLs
• Validates numeric values
• Ensures proper formatting

validateRPCEndpoint(endpoint string) error

Validates RPC endpoint URLs:

• Checks for valid schemes (http, https, ws, wss)
• Validates hostname
• Restricts localhost in production
• Prevents empty endpoints

Security Features

Environment Variable Validation

• Validates all required environment variables
• Checks RPC endpoint URL formats
• Ensures proper numeric value ranges
• Prevents invalid configuration states

RPC Endpoint Security

• Validates URL schemes
• Restricts localhost usage in production
• Checks for valid hostnames
• Prevents empty endpoints

Private Key Protection

• Ensures private key is provided
• Validates account address format
• Prevents empty private key values

Best Practices

Configuration Management

1. Use environment-specific configuration files
2. Store sensitive data in environment variables
3. Validate configuration at startup
4. Document all configuration parameters
5. Provide sensible defaults

Security

1. Never store private keys in configuration files
2. Use secure RPC endpoints (https, wss)
3. Validate all external inputs
4. Restrict localhost usage in production
5. Regularly audit configuration access

Performance

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

Error Handling

Configuration Loading Errors

• File read failures
• YAML parsing errors
• Environment variable expansion issues
• Validation failures

Validation Errors

• Missing required variables
• Invalid URL formats
• Out-of-range numeric values
• Empty required fields

Testing

Unit Tests

• Configuration loading and parsing
• Environment variable expansion
• Validation logic
• Override functionality

Integration Tests

• End-to-end configuration loading
• Environment variable integration
• Security validation
• Performance testing

Future Improvements

Enhanced Features

1. Configuration hot reloading
2. Remote configuration sources
3. Configuration versioning
4. Advanced validation rules
5. Configuration migration tools

Security Enhancements

1. Encrypted configuration values
2. Configuration signing and verification
3. Role-based configuration access
4. Audit logging for configuration changes
5. Secure configuration distribution