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

Arbitrage Package Documentation

Overview

The arbitrage package provides comprehensive arbitrage detection, execution, and management capabilities for the MEV Bot application. It implements sophisticated arbitrage algorithms, secure transaction execution, MEV competition analysis, and persistent data storage.

Core Components

ArbitrageService Structure

The main arbitrage service with comprehensive MEV detection:

1. Client - Ethereum client for blockchain interaction
2. Logger - Structured logging
3. Config - Arbitrage configuration
4. KeyManager - Secure key management
5. MultiHopScanner - Multi-hop arbitrage scanning
6. Executor - Arbitrage transaction execution
7. MarketManager - Market data management
8. TokenCache - Pool token caching
9. State Management - Service lifecycle control
10. Statistics - Performance metrics
11. Database - Data persistence

ArbitrageExecutor Structure

Manages the execution of arbitrage opportunities using smart contracts:

1. Client - Ethereum client
2. Logger - Structured logging
3. KeyManager - Secure key management
4. CompetitionAnalyzer - MEV competition analysis
5. Contracts - Smart contract instances
6. Addresses - Contract addresses
7. Configuration - Execution parameters
8. Transaction Options - Transactor configuration

SQLiteDatabase Structure

Implements ArbitrageDatabase using SQLite:

1. DB - SQLite database connection
2. Logger - Structured logging

Arbitrage Service

Service Management

NewArbitrageService(client *ethclient.Client, logger *logger.Logger, config *config.ArbitrageConfig, keyManager *security.KeyManager, database ArbitrageDatabase) (*ArbitrageService, error)

Creates a new sophisticated arbitrage service:

1. Context Creation - Sets up service context
2. Scanner Initialization - Creates multi-hop scanner
3. Executor Creation - Initializes arbitrage executor
4. Market Manager - Sets up market managers
5. Statistics - Initializes service statistics
6. Token Cache - Creates token caching layer

Start() error

Begins the simplified arbitrage service:

1. State Validation - Checks service state
2. Worker Startup - Starts background workers
3. Monitoring - Begins blockchain monitoring
4. Market Sync - Starts market data synchronization
5. Statistics - Begins statistics updating

Stop() error

Stops the arbitrage service:

1. State Validation - Checks service state
2. Context Cancellation - Cancels service context
3. Worker Shutdown - Stops background workers
4. Cleanup - Performs necessary cleanup

Event Processing

ProcessSwapEvent(event *SimpleSwapEvent) error

Processes a swap event for arbitrage opportunities:

1. Significance Check - Determines if swap is significant
2. Opportunity Detection - Scans for arbitrage paths
3. Validation - Validates opportunities
4. Execution - Executes profitable opportunities

isSignificantSwap(event *SimpleSwapEvent) bool

Checks if a swap is large enough to create arbitrage opportunities:

1. Amount Conversion - Converts to absolute values
2. Threshold Comparison - Compares against minimum size
3. Decision Making - Returns significance determination

detectArbitrageOpportunities(event *SimpleSwapEvent) error

Scans for arbitrage opportunities triggered by an event:

1. Token Determination - Identifies involved tokens
2. Amount Calculation - Calculates scan amounts
3. Path Scanning - Uses scanner to find paths
4. Opportunity Conversion - Converts paths to opportunities
5. Validation - Validates opportunities
6. Opportunity Processing - Processes valid opportunities

Opportunity Management

executeOpportunity(opportunity *ArbitrageOpportunity)

Executes a single arbitrage opportunity:

1. Expiration Check - Validates opportunity expiration
2. Parameter Preparation - Prepares execution parameters
3. Execution - Executes arbitrage transaction
4. Result Processing - Processes execution results

isValidOpportunity(path *ArbitragePath) bool

Determines if an arbitrage opportunity is valid:

1. Profit Check - Validates minimum profit threshold
2. ROI Check - Validates minimum ROI percentage
3. Age Check - Validates path age
4. Gas Profitability - Checks profitability after gas

calculateScanAmount(event *SimpleSwapEvent, token common.Address) *big.Int

Calculates the amount to use for scanning:

1. Amount Extraction - Gets relevant swap amount
2. Scaling - Scales amount for scanning
3. Bounds Checking - Applies minimum and maximum limits

calculateUrgency(path *ArbitragePath) int

Calculates urgency level for an opportunity:

1. ROI Calculation - Base urgency from ROI
2. Profit Scaling - Adjusts for profit magnitude
3. Range Clamping - Ensures 1-10 range

rankOpportunities(opportunities []*ArbitrageOpportunity)

Ranks arbitrage opportunities:

1. Urgency Sorting - Sorts by urgency level
2. Profit Secondary - Sorts by estimated profit
3. Stable Sort - Maintains relative order

Execution Management

calculateMinOutput(opportunity *ArbitrageOpportunity) *big.Int

Calculates minimum output with slippage:

1. Expected Output - Calculates expected output
2. Slippage Application - Applies slippage tolerance
3. Result Calculation - Returns minimum output

processExecutionResult(result *ExecutionResult)

Processes execution results:

1. Statistics Update - Updates service statistics
2. Database Storage - Saves execution to database
3. Logging - Logs execution results

Monitoring and Statistics

blockchainMonitor()

Monitors the Arbitrum sequencer:

1. Monitor Creation - Creates Arbitrum monitor
2. Fallback Handling - Implements block polling fallback
3. Status Monitoring - Provides continuous status updates

statsUpdater()

Updates service statistics:

1. Ticker Setup - Sets up periodic updates
2. Statistics Logging - Logs current statistics
3. Cleanup - Handles graceful shutdown

logStats()

Logs current service statistics:

1. Data Retrieval - Gets current statistics
2. Success Rate - Calculates success rate
3. Formatted Logging - Logs formatted statistics

GetStats() *ArbitrageStats

Returns current service statistics:

1. Locking - Acquires read lock
2. Copy Creation - Creates statistics copy
3. Return - Returns statistics copy

Arbitrage Executor

Initialization

NewArbitrageExecutor(client *ethclient.Client, logger *logger.Logger, keyManager *security.KeyManager, arbitrageAddr common.Address, flashSwapAddr common.Address) (*ArbitrageExecutor, error)

Creates a new arbitrage executor:

1. Contract Creation - Creates contract instances
2. Key Management - Gets active private key
3. Network ID - Retrieves chain ID
4. Transactor Setup - Creates transactor options
5. Configuration - Sets default parameters

Execution Management

ExecuteArbitrage(ctx context.Context, params *ArbitrageParams) (*ExecutionResult, error)

Executes an arbitrage opportunity using flash swaps:

1. MEV Analysis - Analyzes competition
2. Bidding Strategy - Calculates optimal bid
3. Validation - Validates execution parameters
4. Gas Update - Updates gas pricing
5. Parameter Preparation - Prepares flash swap parameters
6. Execution - Executes flash swap arbitrage
7. Confirmation - Waits for confirmation
8. Result Processing - Processes execution results

validateExecution(ctx context.Context, params *ArbitrageParams) error

Validates arbitrage execution parameters:

1. Profit Threshold - Checks minimum profit
2. Path Validation - Validates arbitrage path
3. Pool Liquidity - Validates pool liquidity
4. Gas Pricing - Validates gas price

executeFlashSwapArbitrage(ctx context.Context, params *FlashSwapParams) (*types.Transaction, error)

Executes the flash swap arbitrage transaction:

1. Deadline Setting - Sets transaction deadline
2. Gas Estimation - Estimates gas requirements
3. Parameter Setting - Configures transaction options
4. Execution - Executes flash swap
5. Logging - Logs transaction submission

MEV Competition

competitionAnalyzer Integration

The executor integrates with MEV competition analysis:

1. Opportunity Analysis - Analyzes MEV competition
2. Bidding Strategy - Calculates optimal bidding
3. Gas Pricing - Applies competitive gas pricing
4. Success Probability - Estimates execution probability

Transaction Management

waitForConfirmation(ctx context.Context, txHash common.Hash) (*types.Receipt, error)

Waits for transaction confirmation:

1. Timeout Setup - Configures timeout
2. Polling Loop - Polls for receipt
3. Receipt Return - Returns confirmed receipt

updateGasPrice(ctx context.Context) error

Updates gas price based on network conditions:

1. Suggestion Retrieval - Gets suggested gas price
2. Premium Application - Applies execution premium
3. Limit Checking - Ensures within maximum
4. Update - Updates transactor options

Profit Calculation

calculateActualProfit(ctx context.Context, receipt *types.Receipt) (*big.Int, error)

Calculates actual profit from transaction receipt:

1. Event Parsing - Parses arbitrage events
2. Balance Analysis - Analyzes balance changes
3. Profit Calculation - Calculates net profit
4. Gas Adjustment - Adjusts for gas costs

IsProfitableAfterGas(path *ArbitragePath, gasPrice *big.Int) bool

Checks if execution is profitable after gas costs:

1. Gas Cost - Calculates gas costs
2. Net Profit - Calculates net profit
3. Threshold Check - Compares with minimum threshold

Database Management

SQLite Implementation

NewSQLiteDatabase(dbPath string, logger *logger.Logger) (*SQLiteDatabase, error)

Creates a new SQLite database for arbitrage data:

1. Connection - Opens SQLite database
2. Table Creation - Creates necessary tables
3. Index Creation - Creates performance indexes
4. Return - Returns database instance

createTables() error

Creates the necessary database tables:

1. Schema Definition - Defines table schemas
2. Table Creation - Creates tables
3. Index Creation - Creates indexes
4. Error Handling - Handles creation errors

Data Persistence

SaveOpportunity(ctx context.Context, opportunity *ArbitrageOpportunity) error

Saves an arbitrage opportunity to the database:

1. JSON Marshaling - Converts to JSON
2. Query Execution - Inserts opportunity data
3. Logging - Logs save operation

SaveExecution(ctx context.Context, result *ExecutionResult) error

Saves an arbitrage execution result to the database:

1. JSON Marshaling - Converts to JSON
2. Query Execution - Inserts execution data
3. Logging - Logs save operation

GetExecutionHistory(ctx context.Context, limit int) ([]*ExecutionResult, error)

Retrieves historical arbitrage executions:

1. Query Execution - Queries execution history
2. Row Processing - Processes result rows
3. JSON Unmarshaling - Converts from JSON
4. Return - Returns execution results

Pool Data Management

SavePoolData(ctx context.Context, poolData *SimplePoolData) error

Saves pool data to the database:

1. Query Execution - Inserts or replaces pool data
2. Logging - Logs save operation

GetPoolData(ctx context.Context, poolAddress common.Address) (*SimplePoolData, error)

Retrieves pool data from the database:

1. Query Execution - Queries pool data
2. Row Processing - Processes result row
3. Data Parsing - Parses numeric data
4. Return - Returns pool data

Statistics

GetOpportunityCount(ctx context.Context) (int64, error)

Returns the total number of opportunities detected:

1. Query Execution - Counts opportunities
2. Return - Returns count

GetExecutionCount(ctx context.Context) (int64, error)

Returns the total number of executions attempted:

1. Query Execution - Counts executions
2. Return - Returns count

GetSuccessfulExecutionCount(ctx context.Context) (int64, error)

Returns the number of successful executions:

1. Query Execution - Counts successful executions
2. Return - Returns count

GetTotalProfit(ctx context.Context) (string, error)

Returns the total profit realized from all successful executions:

1. Query Execution - Sums successful profits
2. Return - Returns total profit

Data Structures

ArbitrageOpportunity Structure

Represents a detected arbitrage opportunity:

• ID - Unique identifier
• Path - Arbitrage path information
• TriggerEvent - Event that triggered opportunity
• DetectedAt - Detection timestamp
• EstimatedProfit - Estimated profit in wei
• RequiredAmount - Input amount required
• Urgency - Priority level (1-10)
• ExpiresAt - Expiration timestamp

ExecutionResult Structure

Represents the result of an arbitrage execution:

• TransactionHash - Transaction hash
• GasUsed - Gas units consumed
• GasPrice - Gas price used
• ProfitRealized - Actual profit realized
• Success - Execution success status
• Error - Error information
• ExecutionTime - Execution duration
• Path - Arbitrage path

ArbitrageParams Structure

Contains parameters for arbitrage execution:

• Path - Arbitrage path
• InputAmount - Input token amount
• MinOutputAmount - Minimum output amount
• Deadline - Transaction deadline
• FlashSwapData - Flash swap data

SimpleSwapEvent Structure

Represents a swap event for arbitrage detection:

• TxHash - Transaction hash
• PoolAddress - Pool contract address
• Token0/Token1 - Token addresses
• Amount0/Amount1 - Swap amounts
• SqrtPriceX96 - Price after swap
• Liquidity - Pool liquidity
• Tick - Current tick
• BlockNumber - Block number
• LogIndex - Log index
• Timestamp - Event timestamp

SimplePoolData Structure

Represents basic pool information:

• Address - Pool contract address
• Token0/Token1 - Token addresses
• Fee - Pool fee tier
• Liquidity - Current liquidity
• SqrtPriceX96 - Square root price
• Tick - Current tick
• BlockNumber - Block number
• TxHash - Transaction hash
• LogIndex - Log index
• LastUpdated - Last update timestamp

Security Features

Key Management Integration

The arbitrage package integrates with secure key management:

1. Private Key Protection - Secure key storage
2. Transaction Signing - Secure transaction signing
3. Key Rotation - Automated key rotation
4. Audit Logging - Security audit trails

MEV Competition Analysis

Advanced MEV competition analysis:

1. Gas Pricing - Competitive gas pricing strategies
2. Success Probability - Execution probability estimation
3. Profit Optimization - Net profit maximization
4. Risk Management - Risk-adjusted bidding

Transaction Security

Secure transaction execution:

1. Gas Limiting - Maximum gas protection
2. Price Capping - Maximum price protection
3. Validation - Pre-execution validation
4. Recovery - Error recovery mechanisms

Performance Optimization

Concurrent Processing

The arbitrage service implements efficient concurrent processing:

1. Worker Pools - Background worker management
2. Channel Communication - Efficient data flow
3. Context Management - Proper cancellation
4. Resource Cleanup - Graceful resource release

Database Optimization

SQLite database optimization:

1. Indexing - Performance indexes
2. Batch Operations - Efficient batch processing
3. Connection Management - Proper connection handling
4. Query Optimization - Optimized query patterns

Memory Management

Efficient memory usage:

1. Object Reuse - Minimize allocations
2. Cache Management - Token caching
3. Garbage Collection - Efficient cleanup
4. Resource Pooling - Resource reuse

Best Practices

Arbitrage Strategy

1. Significance Filtering - Filter significant swaps
2. Multi-hop Scanning - Comprehensive path finding
3. Profit Validation - Validate profitability
4. Risk Management - Manage execution risks
5. Gas Optimization - Optimize gas usage

Security

1. Key Management - Secure key handling
2. Transaction Validation - Validate all transactions
3. Access Control - Restrict unauthorized access
4. Audit Logging - Comprehensive logging
5. Error Handling - Graceful error recovery

Performance

1. Concurrent Processing - Maximize throughput
2. Caching - Efficient data caching
3. Database Optimization - Optimized storage
4. Resource Management - Efficient resource use
5. Monitoring - Continuous performance monitoring

Future Improvements

Enhanced Features

1. Machine Learning - Predictive arbitrage models
2. Cross-Chain - Multi-chain arbitrage
3. Advanced Analytics - Sophisticated analysis
4. Real-time Updates - WebSocket integration
5. Automated Optimization - Self-tuning parameters

Performance Enhancements

1. Algorithmic Improvements - Faster path finding
2. Memory Optimization - Reduced allocations
3. Database Scaling - Distributed storage
4. Network Optimization - Efficient RPC usage
5. Batch Processing - Enhanced batching

Security Improvements

1. Advanced Validation - Enhanced validation
2. Rate Limiting - Sophisticated rate limiting
3. Access Control - Enhanced access controls
4. Audit Enhancement - Comprehensive auditing
5. Threat Detection - Advanced threat detection