Files

Krypto Kajun 52d555ccdf fix(critical): complete execution pipeline - all blockers fixed and operational

2025-11-04 10:24:34 -06:00

36 KiB

Raw Blame History

MEV Bot Codebase - Comprehensive Analysis Report

Project: MEV Bot for Arbitrum
Language: Go 1.25
Module: github.com/fraktal/mev-beta
Total Go Files: 362 (253 in pkg/, 31 in internal/, 4 in cmd/)
Total Lines of Code: ~100,000+ (just pkg/ packages)

1. COMPLETE DIRECTORY STRUCTURE & ORGANIZATION

Root-Level Directories

/home/administrator/projects/mev-beta/
├── bin/                      # Compiled binaries
├── bindings/                 # Smart contract ABI bindings (Go-ethereum generated)
│   ├── arbitrage/           # Arbitrage executor contracts
│   ├── balancer/            # Balancer protocol bindings
│   ├── contracts/           # Flash swap executors
│   ├── datafetcher/         # Data fetcher contracts
│   ├── interfaces/          # Interface definitions
│   ├── tokens/              # ERC20 and pool interfaces
│   └── uniswap/             # Uniswap V2/V3 bindings
├── broadcast/               # Foundry broadcast output
├── cache/                   # Runtime cache storage
├── cmd/                     # Main applications
│   ├── mev-bot/             # Primary MEV bot application (786 lines)
│   └── swap-cli/            # Swap CLI tool
├── config/                  # Configuration files (YAML)
├── contracts/               # Smart contract source code (Solidity)
├── data/                    # Data files and state
├── docker/                  # Docker configurations
├── docs/                    # Documentation (21 directories)
├── internal/                # Private internal packages (14 directories)
├── keystore/                # Encrypted key storage
├── lib/                     # Third-party libraries (OpenZeppelin, Forge-std)
├── logs/                    # Application logs and analytics
├── pkg/                     # Public library packages (47 directories)
├── scripts/                 # Utility and deployment scripts
├── tests/                   # Integration and test suites
├── vendor/                  # Vendored dependencies
└── wallets/                 # Wallet configuration storage

Core Directories (by importance)

pkg/ - Main library code (47 packages, 253 Go files):

pkg/
├── arbitrage/               # Core arbitrage detection and execution (17 files, ~7000+ LOC)
├── arbitrum/                # Arbitrum-specific integration (34 files, ~8000+ LOC)
├── dex/                     # DEX protocol implementations (11 files)
├── execution/               # Execution management (4 files)
├── monitor/                 # Arbitrum sequencer monitoring (1 file, 1351 LOC)
├── scanner/                 # Market event scanning (5 directories)
├── pools/                   # Pool discovery and management (1 file, 1065 LOC)
├── security/                # Security, encryption, key management (11 files)
├── transport/               # RPC provider management (3 files)
├── contracts/               # Smart contract interactions (2 files)
├── market/                  # Market data management (3 files)
├── events/                  # Event parsing and handling (1 file, 1806 LOC)
├── types/                   # Canonical type definitions (1 file, 148 LOC)
├── math/                    # Mathematical operations (3 files, 1010+ LOC)
├── validation/              # Input and output validation (2 files)
├── tokens/                  # Token metadata and management (2 files)
├── uniswap/                 # Uniswap V3-specific logic (6 files)
└── [35 other packages]      # Additional specialized packages

internal/ - Private application packages (14 directories, 31 files):

internal/
├── config/                  # Configuration management (2 files, 25k+ LOC)
├── logger/                  # Structured logging (multiple files)
├── monitoring/              # Internal monitoring infrastructure
├── ratelimit/               # Rate limiting implementations
├── auth/                    # Authentication handling
├── validation/              # Input validation rules
├── tokens/                  # Token definitions and constants
└── [7 other packages]       # Support and utility modules

cmd/ - Entry points (3 applications):

cmd/
├── mev-bot/
│   ├── main.go             # Primary entry point (786 lines)
│   ├── dex_integration.go   # DEX protocol setup
│   └── dashboard.go         # Dashboard functionality
└── swap-cli/
    └── main.go              # Swap CLI utility

2. ALL PACKAGES IN DETAIL

A. Core Arbitrage Engine (`pkg/arbitrage/` - 17 files, ~7000+ LOC)

Primary Files:

File	Lines	Purpose
`service.go`	1,995	ArbitrageService - main orchestration service, integrates all components
`executor.go`	1,641	ArbitrageExecutor - transaction execution and contract interaction
`flash_executor.go`	1,462	FlashSwapExecutor - flash swap execution logic
`multihop.go`	892	MultiHopScanner - multi-hop arbitrage path detection
`detection_engine.go`	953	ArbitrageDetectionEngine - opportunity discovery engine
`live_execution_framework.go`	1,005	LiveExecutionFramework - real-time execution framework
`database.go`	13,129	Database - opportunity and execution history persistence
`nonce_manager.go`	3,843	NonceManager - transaction nonce management

Key Types:

ArbitrageService {
    client *ethclient.Client
    keyManager *security.KeyManager
    multiHopScanner *MultiHopScanner
    executor *ArbitrageExecutor
    exchangeRegistry *exchanges.ExchangeRegistry
    detectionEngine *ArbitrageDetectionEngine
    flashExecutor *FlashSwapExecutor
    liveFramework *LiveExecutionFramework
    marketManager *market.MarketManager
    poolDiscovery *pools.PoolDiscovery
}

ArbitrageExecutor {
    client *ethclient.Client
    keyManager *security.KeyManager
    exchangeRegistry *exchanges.ExchangeRegistry
    detectionEngine *ArbitrageDetectionEngine
    arbitrageContract *arbitrage.ArbitrageExecutor
    flashSwapContract *flashswap.BaseFlashSwapper
}

ArbitrageDetectionEngine {
    registry *exchanges.ExchangeRegistry
    calculator *math.ArbitrageCalculator
    gasEstimator math.GasEstimator
    scanWorkers *WorkerPool
    pathWorkers *WorkerPool
}

Main Methods:

service.Start() - Initialize and start arbitrage service
service.StartLiveMode(ctx) - Enable real-time execution
executor.ExecuteArbitrage(ctx, params) - Execute single opportunity
flashExecutor.ExecuteArbitrage(ctx, opportunity) - Execute via flash swap
engine.Start(ctx) - Start detection engine scanning

B. Arbitrum Integration (`pkg/arbitrum/` - 34 files, ~8000+ LOC)

Primary Files:

File	Lines	Purpose
`l2_parser.go`	1,985	L2Parser - advanced transaction parsing for Arbitrum L2
`abi_decoder.go`	1,116	AbiDecoder - decode complex multicall transactions
`parser.go`	967	Parser - basic transaction parsing
`event_monitor.go`	658	EventMonitor - monitor L2 events
`connection.go`	266	ConnectionManager - RPC connection management
`swap_pipeline.go`	844	SwapPipeline - pipeline for swap processing
`profitability_tracker.go`	624	Track profitability metrics
`token_metadata.go`	490	Token metadata caching
`market_discovery.go`	360	Pool and market discovery

Key Types:

ArbitrumL2Parser {
    client *ethclient.Client
    logger *logger.Logger
    abiDecoder *AbiDecoder
    tokenMetadata *TokenMetadataService
}

AbiDecoder {
    protocols map[string]*ProtocolDecoder
    tokenCache map[common.Address]string
}

ConnectionManager {
    config *config.ArbitrumConfig
    logger *logger.Logger
    clients []*ethclient.Client
    rateLimiters map[string]*rate.Limiter
}

Main Methods:

parser.ParseTransaction(tx *types.Transaction) - Parse L2 transaction
abiDecoder.DecodeFunction(data []byte) - Decode function calls
connectionManager.GetClientWithRetry(ctx, retries) - Get RPC client with retry logic

C. Market Monitoring (`pkg/monitor/` - 1 file, 1351 LOC)

ArbitrumMonitor

type ArbitrumMonitor struct {
    config *config.ArbitrumConfig
    client *ethclient.Client
    connectionManager *arbitrum.ConnectionManager
    l2Parser *arbitrum.ArbitrumL2Parser
    marketMgr *market.MarketManager
    scanner *scanner.Scanner
    pipeline *market.Pipeline
}

Main Methods:

NewArbitrumMonitor(...) - Create monitor with all dependencies
Start(ctx context.Context) - Start monitoring sequencer
Subscribes to Arbitrum blocks and parses transactions
Feeds parsed transactions to market scanner
Manages rate limiting and connection health

D. Market Scanning (`pkg/scanner/` - 5 subdirectories)

Main Scanner (concurrent.go - 1351 LOC):

type Scanner struct {
    marketScanner *market.MarketScanner
    swapAnalyzer *swap.SwapAnalyzer
    liquidityAnalyzer *analysis.LiquidityAnalyzer
    workerPool chan chan events.Event
    workers []*EventWorker
}

Sub-packages:

market/ - MarketScanner for pool and token pair analysis
swap/ - SwapAnalyzer for swap event analysis
analysis/ - LiquidityAnalyzer for liquidity calculations
common/ - Shared types and utilities
test/ - Test utilities

Processing Flow:

Receives events from monitor
Distributes to worker pool
MarketScanner analyzes token pairs
SwapAnalyzer detects swaps
LiquidityAnalyzer calculates liquidity changes
Results fed to arbitrage service

E. DEX Protocol Implementations (`pkg/dex/` - 11 files)

Supported Protocols:

File	Protocol	Purpose
`uniswap_v3.go`	Uniswap V3	V3 pool math and swaps
`config.go`	All	DEX configuration
`analyzer.go`	All	Multi-protocol analysis
`balancer.go`	Balancer	Balancer vault integration
`curve.go`	Curve	Curve stableswap math
`sushiswap.go`	SushiSwap	SushiSwap V2 integration
`registry.go`	All	DEX registry management
`decoder.go`	All	Transaction decoding
`types.go`	All	Type definitions

Key Types:

DexRegistry {
    supportedExchanges map[string]*ExchangeConfig
    pools map[common.Address]*PoolConfig
}

PoolConfig {
    Address common.Address
    Protocol string
    Fee int64
    Tokens []common.Address
}

F. Security & Key Management (`pkg/security/` - 11 files, ~5000+ LOC)

Key Components:

File	Lines	Purpose
`keymanager.go`	1,841	Secure key generation, storage, signing
`audit_analyzer.go`	1,646	Audit log analysis
`rate_limiter.go`	1,411	Rate limiting and DoS protection
`performance_profiler.go`	1,316	Performance monitoring
`anomaly_detector.go`	1,069	Anomaly detection for suspicious activity
`monitor.go`	565	Security monitoring

Key Types:

KeyManager {
    keystorePath string
    encryptionKey string
    keyRotationDays int
    maxSigningRate int
}

RateLimiter {
    transactionRPS int
    rpcRPS int
    maxBurstSize int
}

AnomalyDetector {
    baselineMetrics map[string]float64
    thresholds map[string]float64
}

G. Event Parsing & Processing (`pkg/events/` - 1 file, 1806 LOC)

EventParser

type EventParser struct {
    swapEventSignature common.Hash
    liquidityEventSignature common.Hash
    syncEventSignature common.Hash
    logger *logger.Logger
}

Parsed Events:

Swap events (Uniswap V2/V3, SushiSwap)
Liquidity addition/removal (Mint, Burn)
Sync events (Reserve changes)
Flash events (Flash swap callbacks)

H. RPC Provider Management (`pkg/transport/` - 3 files, ~1500 LOC)

UnifiedProviderManager

type UnifiedProviderManager struct {
    readOnlyPool *ProviderPool      // For non-state-changing calls
    executionPool *ProviderPool     // For transaction submission
    testingPool *ProviderPool       // For test calls
    rateLimiters map[string]*rate.Limiter
}

type ProviderPool struct {
    endpoints []*ProviderEndpoint
    currentIndex int
    health map[string]HealthMetrics
}

Features:

Multi-pool architecture (read-only, execution, testing)
Automatic failover and health checking
Per-endpoint rate limiting
Connection pooling and reuse

I. Execution Management (`pkg/execution/` - 4 files)

Key Components:

executor.go - Main execution orchestration
alerts.go - Alert management and notifications
flashloan_providers.go - Flash loan provider interfaces
queue.go - Execution queue management

J. Pool Discovery & Management (`pkg/pools/` - 1 file, 1065 LOC)

PoolDiscovery

type PoolDiscovery struct {
    rpcClient *ethclient.Client
    pools map[common.Address]*Pool
    exchanges map[string]*Exchange
    logger *logger.Logger
}

type Pool struct {
    Address common.Address
    Token0, Token1 common.Address
    Fee uint32
    Protocol string
    Liquidity *big.Int
    LastUpdated time.Time
}

Features:

Cache-based pool discovery
JSON persistence
Protocol detection
Reserve tracking

K. Mathematical Operations (`pkg/math/` - 3 files, 1010+ LOC)

Key Modules:

exchange_math.go - Exchange math for all protocols
ArbitrageCalculator - Profit and slippage calculations
DecimalConverter - Precise decimal handling

Capabilities:

Uniswap V3 tick-to-price conversion
Multi-hop route calculation
Gas cost estimation
Slippage calculation
Price impact modeling

L. Validation (`pkg/validation/` - 2 files)

input_validator.go - Input validation for parameters
price_impact_validator.go - Validate price impacts before execution

M. Types & Interfaces (`pkg/types/` and others)

Canonical ArbitrageOpportunity (pkg/types/types.go):

type ArbitrageOpportunity struct {
    ID string
    Path []string
    Pools []string
    AmountIn, Profit, NetProfit *big.Int
    GasEstimate *big.Int
    ROI float64
    Confidence float64
    PriceImpact float64
    TokenIn, TokenOut common.Address
    Timestamp int64
    DetectedAt, ExpiresAt time.Time
    Quantities *OpportunityQuantities
}

3. KEY ARCHITECTURAL PATTERNS & DESIGN DECISIONS

A. Layered Architecture

┌─────────────────────────────────────────────┐
│         Smart Contract Layer                │ (bindings/)
│   (Arbitrage Executor, Flash Swappers)     │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│      Execution Layer                        │
│   (pkg/arbitrage/executor.go)              │
│   (pkg/arbitrage/flash_executor.go)        │
│   (pkg/execution/)                         │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│    Detection & Analysis Layer               │
│   (pkg/arbitrage/detection_engine.go)      │
│   (pkg/scanner/)                           │
│   (pkg/dex/)                               │
│   (pkg/math/)                              │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│    Event Collection & Parsing Layer         │
│   (pkg/monitor/)                           │
│   (pkg/arbitrum/l2_parser.go)             │
│   (pkg/events/)                            │
│   (pkg/arbitrum/abi_decoder.go)           │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│    Infrastructure Layer                     │
│   (pkg/transport/)                         │
│   (pkg/pools/)                             │
│   (pkg/arbitrum/connection.go)            │
│   (pkg/security/)                          │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│    Ethereum RPC / Arbitrum L2               │
└─────────────────────────────────────────────┘

B. Data Flow Pipeline

Arbitrum Block Stream (WebSocket)
            ↓
    ArbitrumMonitor.Start()
            ↓
    L2Parser.ParseTransaction()
    ├─ Decode multicall with AbiDecoder
    ├─ Extract function calls
    └─ Identify swap operations
            ↓
    EventParser.ParseEvents()
    ├─ Decode logs from transaction receipt
    ├─ Extract swap/liquidity events
    └─ Parse pool state changes
            ↓
    Scanner.ProcessEvents()
    ├─ MarketScanner analyzes token pairs
    ├─ SwapAnalyzer detects swaps
    └─ Identifies liquidity opportunities
            ↓
    ArbitrageService monitors results
    ├─ MultiHopScanner finds multi-hop paths
    ├─ ArbitrageDetectionEngine ranks opportunities
    └─ Feeds to execution layer
            ↓
    ArbitrageExecutor.ExecuteArbitrage()
    ├─ Simulates transaction
    ├─ Estimates gas
    ├─ Creates and signs tx
    └─ Submits to Arbitrum
            ↓
    Results logged and persisted

C. Concurrency Model

Worker Pool Pattern:

Market scanner uses configurable worker pools
Each worker processes events independently
Non-blocking channel communication
Graceful shutdown with WaitGroup

Rate Limiting:

Per-RPC-endpoint rate limiters
Global transaction rate limiting
Burst allowances for spikes
Automatic backoff on failures

Thread Safety:

RWMutex for cache access
Atomic counters for metrics
Context-based cancellation
Proper synchronization in shutdown

D. Configuration Management

Multi-Environment Support:

Environment        Config File               Env Variable
─────────────────────────────────────────────────────────
development        config/local.yaml         GO_ENV=development
                   config/config.yaml
staging           config/config.staging.yaml GO_ENV=staging
production        config/arbitrum_production.yaml GO_ENV=production

Config Hierarchy:

YAML configuration file (base settings)
Environment variable overrides
Runtime configuration adjustments
Per-endpoint overrides (providers.yaml)

4. MAIN WORKFLOWS & DATA FLOWS

A. Startup Workflow (main.go - 786 lines)

Sequence:

Load environment and configuration (debug steps 1-20)
Initialize logger with configured level
Validate RPC endpoints
Initialize metrics collector
Create unified provider manager (read-only, execution, testing pools)
Create key manager for transaction signing
Initialize pool discovery from cache
~~(Disabled) Pool discovery background task~~
Create market manager
Create market scanner with worker pools
Create arbitrage service
Start monitor loop
Setup graceful shutdown handlers
Block on signal or error

Key Features:

20 debug checkpoints for troubleshooting
Modular initialization allowing selective startup
Comprehensive error handling
Pool discovery optimized (skip expensive discovery to avoid startup hang)

B. Real-Time Monitoring Loop

ArbitrumMonitor.Start()

Infinite Loop:
├─ Subscribe to new blocks (WebSocket or polling)
├─ Fetch block transactions
├─ For each transaction:
│  ├─ Call L2Parser.ParseTransaction()
│  │  ├─ Extract function calls with AbiDecoder
│  │  └─ Identify swap patterns
│  ├─ Fetch transaction receipt
│  ├─ Call EventParser.ParseEvents()
│  │  ├─ Decode log topics
│  │  └─ Extract pool state changes
│  ├─ Create events.Event objects
│  └─ Send to Scanner worker pool
└─ Handle errors and continue

Rate Limiting:

Per-endpoint rate limits enforced
Burst tolerance for spike handling
Automatic backoff on 429 responses

C. Event Processing & Arbitrage Detection

Scanner.ProcessEvent() Flow:

Event Received (Swap, Liquidity, Sync)
        ↓
Dispatch to EventWorker
        ↓
MarketScanner.AnalyzeEvent()
├─ Update pool state
├─ Calculate price impact
└─ Track liquidity changes
        ↓
SwapAnalyzer.AnalyzeSwap()
├─ Detect arbitrage patterns
├─ Identify price discrepancies
└─ Calculate potential profits
        ↓
Send results to Market Manager
        ↓
ArbitrageService monitors results
├─ MultiHopScanner finds multi-hop opportunities
├─ DetectionEngine ranks by profitability
├─ Filter by confidence and risk
└─ Queue for execution

D. Arbitrage Execution Flow

LiveExecutionFramework.ExecuteOpportunity()

Opportunity Detected
        ↓
Validate opportunity (amount, slippage, confidence)
        ↓
Get execution client from provider manager
        ↓
ArbitrageExecutor prepares transaction:
├─ Select best path (if multi-hop)
├─ Estimate gas with simulation
├─ Calculate slippage
├─ Check profitability after gas
├─ Create transaction parameters
└─ Use KeyManager to sign
        ↓
Submit to Arbitrum via execution endpoint
        ↓
Wait for receipt (max 60 seconds)
        ↓
Parse receipt for execution results
        ↓
Log execution and update statistics

5. EXTERNAL DEPENDENCIES & INTEGRATIONS

Go Module Dependencies

Primary:
├─ github.com/ethereum/go-ethereum v1.16.3
│  ├─ ethclient (RPC interaction)
│  ├─ crypto (key operations)
│  ├─ types (transaction types)
│  └─ abi/bind (contract binding)
├─ github.com/gorilla/websocket v1.5.3 (WebSocket)
├─ github.com/holiman/uint256 v1.3.2 (256-bit integers)
├─ github.com/joho/godotenv v1.5.1 (env loading)
├─ github.com/urfave/cli/v2 v2.27.5 (CLI)
└─ gopkg.in/yaml.v3 (YAML parsing)

Database:
├─ github.com/lib/pq v1.10.9 (PostgreSQL)
└─ github.com/mattn/go-sqlite3 v1.14.32 (SQLite)

Cryptography:
└─ golang.org/x/crypto v0.42.0

Rate Limiting:
└─ golang.org/x/time v0.10.0

Testing:
└─ github.com/stretchr/testify v1.11.1

Smart Contract Integrations

Generated Bindings (bindings/):

Arbitrage Executor contract
Flash Swap contracts (Uniswap V2/V3)
ERC20 token interface
Uniswap V3 Pool interface
Balancer Vault interface

Key Contracts:

Arbitrage Executor - custom arbitrage execution logic
Flash Swappers - flash loan-based arbitrage
Token interfaces - ERC20 operations

Current Contract Addresses:

Tracked in config/deployed_contracts.yaml
Configurable per environment

6. CONFIGURATION MANAGEMENT APPROACH

Configuration Files

Primary Config (config/arbitrum_production.yaml):

tokens:
  weth: {address, decimals, coingecko_id}
  usdc: {address, decimals, is_stable}
  [20+ major tokens defined]

dex_configs:
  uniswap_v3: {factory, router, fee_tiers}
  uniswap_v2: {factory, router}
  sushiswap: {factory, router}
  curve: {registry, controller}

arbitrage:
  min_profit_threshold: 0.1%
  max_slippage: 0.5%
  max_gas_price: 50 gwei
  max_position_size: 100 ETH

Provider Configuration (config/providers.yaml):

read_only_pool:
  endpoints:
    - url: "https://..."
      name: "primary"
      priority: 1
      max_rps: 50
    - url: "https://..."
      name: "secondary"
      priority: 2
      max_rps: 30

execution_pool:
  endpoints:
    - url: "https://..."
      priority: 1
      max_rps: 20

testing_pool:
  endpoints:
    - url: "https://..."
      priority: 1
      max_rps: 10

Environment Variables

Required:

GO_ENV={development|staging|production}
MEV_BOT_ENCRYPTION_KEY=<32-byte key>
MEV_BOT_KEYSTORE_PATH=keystore
ARBITRUM_RPC_ENDPOINT=wss://...
ARBITRUM_WS_ENDPOINT=wss://...

Optional:

LOG_LEVEL={debug|info|warn|error}
METRICS_ENABLED={true|false}
METRICS_PORT=9090
DEBUG=true
GOMAXPROCS=4

7. TESTING INFRASTRUCTURE

Test Organization

tests/
├── integration/          # Integration tests
│   ├── fork_test.go     # Arbitrum fork testing
│   └── [other tests]
├── cache/               # Cache-related tests
├── contracts/           # Contract interaction tests
└── scenarios/           # Test scenarios

pkg/*/..._test.go        # Unit tests colocated with source

Test Coverage

Test Files by Package:

arbitrage/: flash_executor_test.go, live_execution_framework_test.go, multihop_test.go
arbitrum/: connection_test.go, parser_test.go, abi_fuzz_test.go
scanner/: concurrent_test.go
security/: keymanager_test.go
validation/: pool_validator_test.go (1155 lines)

Build & Test Commands

make build              # Build binary
make test              # Run all tests
make test-coverage     # Coverage report
make test-integration  # Integration tests only

8. BUILD & DEPLOYMENT SETUP

Build System

Tool: Make (Makefile - 16+ KB)

Main Targets:

build                  # Compile binary
build-mm              # Build market manager example
build-swap-cli        # Build swap CLI
run                   # Build and run
test                  # Run tests
test-coverage         # Generate coverage
lint                  # Run linter (golangci-lint)
simulate-profit       # Run profitability simulator
security-scan         # Security analysis
clean                 # Clean build artifacts

Docker Support

Dockerfile (minimal):

Based on Go 1.25
Copies source and builds
Runs mev-bot start

docker-compose.test.yml:

PostgreSQL for state
Redis for caching (optional)
Arbitrum node (hardhat/anvil)

Production Logging

Log Architecture (scripts/log-manager.sh):

logs/
├── mev_bot.log           # Main application log
├── mev_bot_errors.log    # Error-specific log
├── mev_bot_performance.log # Performance metrics
├── analytics/            # Real-time analysis
│   ├── analysis_*.json   # Comprehensive metrics
│   └── dashboard_*.html  # Operations dashboard
├── health/               # Health monitoring
├── archives/             # Compressed rotated logs
└── rotated/              # Rotated log files (gzip)

Features:

Real-time health scoring (97.97/100)
Corruption detection
Multi-channel alerting
Background monitoring daemon
Advanced rotation and compression

9. RECENT CHANGES & CURRENT STATE

Recent Major Changes (from git status)

Modified Files (Key Changes):

.env.production - Production environment config
cmd/mev-bot/main.go - Startup sequence and debug points
config/arbitrum_production.yaml - Token configurations
internal/config/config.go - Configuration loading
pkg/arbitrage/service.go - Core service updates
pkg/arbitrage/multihop.go - Multi-hop scanner
pkg/monitor/concurrent.go - Monitoring integration
pkg/scanner/concurrent.go - Event processing
pkg/arbitrum/l2_parser.go - Transaction parsing

Known Issues & Workarounds

Startup Hang (Fixed in main.go):

Pool discovery loop made 190 RPC calls
Some calls to DiscoverPoolsForTokenPair() hung
Solution: Skip discovery loop during startup
Pools loaded from cache (314 pools)
Background discovery can run after startup

Pool Parsing Improvements:

Enhanced ABI decoding for multicall
Fallback parsing for edge cases
Token address validation

Configuration Optimization:

Separated read-only, execution, and testing pools
Per-endpoint rate limiting
Health check integration

Untracked Files (Build Artifacts, Cache, Docs)

?? .golangci-cache/         # Linter cache
?? logs/                    # Log files and analytics
?? docs/                    # Generated documentation
?? config/bot_config*.yaml  # Generated configs
?? bindings/datafetcher/    # Generated contract bindings
?? pkg/datafetcher/         # Generated code
?? pkg/utils/               # Utility code

10. CRITICAL COMPONENTS SUMMARY

Top 10 Most Important Files (by LOC and impact)

Rank	File	LOC	Role
1	`pkg/arbitrage/service.go`	1,995	Main orchestration service
2	`pkg/arbitrum/l2_parser.go`	1,985	Transaction parsing
3	`pkg/security/keymanager.go`	1,841	Key management & signing
4	`pkg/events/parser.go`	1,806	Event extraction
5	`pkg/security/audit_analyzer.go`	1,646	Audit & compliance
6	`pkg/arbitrage/executor.go`	1,641	Execution logic
7	`pkg/arbitrage/flash_executor.go`	1,462	Flash swap execution
8	`pkg/security/rate_limiter.go`	1,411	Rate limiting
9	`pkg/monitor/concurrent.go`	1,351	Sequencer monitoring
10	`pkg/security/performance_profiler.go`	1,316	Performance tracking

Critical Data Paths

Block → Transaction → Swap Event:
- ArbitrumMonitor.Start()
- → L2Parser.ParseTransaction()
- → EventParser.ParseEvents()
- → Scanner.ProcessEvent()
Event → Opportunity → Execution:
- Scanner results
- → ArbitrageService.AnalyzeOpportunity()
- → MultiHopScanner.FindPaths()
- → ArbitrageDetectionEngine.RankOpportunities()
- → ArbitrageExecutor.ExecuteArbitrage()
Transaction Signing & Submission:
- KeyManager.GetAccount()
- → KeyManager.SignTransaction()
- → ethclient.SendTransaction()

11. ACTUAL vs DOCUMENTED STATE

Implementation Notes

What Actually Happens:

Security manager is disabled during startup (commented out, debugging hang)
Pool discovery background task is skipped (replaced with cache-only loading)
20 debug checkpoints added to main.go for troubleshooting
Provider manager uses 3-pool architecture (read-only, execution, testing)
Event processing is event-driven not block-based
Configuration is multi-file with runtime overrides

What Docs Say vs Reality:

Docs: "Pool discovery running" → Reality: Cache-only on startup
Docs: "Comprehensive security" → Reality: Security manager disabled
Docs: "Real-time monitoring" → Reality: Polling + WebSocket hybrid

Performance Characteristics

Processing Latency: Transaction parse → Opportunity detect: ~10-50ms (depending on complexity)
Rate Limits: Read: 50 RPS, Execution: 20 RPS, Testing: 10 RPS (per config)
Memory: ~200-500MB typical operation (with pool cache)
Worker Threads: Configurable, default 4-8 (via MaxWorkers config)

12. INTERACTION DIAGRAM

┌─────────────────────┐
│   Arbitrum L2       │
│    (Sequencer)      │
└──────────┬──────────┘
           │ Blocks (WebSocket/Polling)
           ▼
┌──────────────────────────────────────┐
│      ArbitrumMonitor                 │
│  - Subscribe to blocks               │
│  - Fetch transaction details         │
└───┬──────────────────────────────────┘
    │
    ├──→ L2Parser
    │    ├─ AbiDecoder (multicall)
    │    └─ Extract functions
    │
    └──→ EventParser
         ├─ Decode logs
         └─ Extract events (Swap, Liquidity)
                │
                ▼
    ┌─────────────────────────────┐
    │    Scanner (Workers)        │
    ├─ MarketScanner             │
    ├─ SwapAnalyzer              │
    └─ LiquidityAnalyzer         │
         │
         ▼
    ┌─────────────────────────────┐
    │  ArbitrageService           │
    ├─ MultiHopScanner           │
    ├─ DetectionEngine           │
    └─ Statistics                │
         │
         ▼
    ┌─────────────────────────────┐
    │  ArbitrageExecutor          │
    ├─ Simulate transaction       │
    ├─ Estimate gas              │
    └─ Execute via contract      │
         │
         ├──→ Arbitrage Executor Contract
         │
         ├──→ Flash Swap Contract
         │
         └──→ KeyManager (Sign)
              └──→ TransactionSubmitter
                   └──→ Arbitrum (Submit)

13. CONFIGURATION LOADING SEQUENCE

main.go startup():
├─ Load GO_ENV from environment (default: "development")
├─ Select config file:
│  ├─ if GO_ENV == "production": config/arbitrum_production.yaml
│  ├─ if GO_ENV == "staging": config/staging.yaml
│  └─ else (development): config/local.yaml OR config/config.yaml
├─ Load YAML into Config struct
├─ Parse Arbitrum section (RPC endpoints, chain ID)
├─ Parse Bot section (polling interval, workers, buffers)
├─ Parse Uniswap section (factory, router addresses)
├─ Parse Contracts section (executor, flash loan addresses)
├─ Parse Arbitrage section (profit thresholds, slippage)
├─ Load environment variable overrides
└─ Validate all required fields

Config struct hierarchy:

Config {
  Arbitrum {
    ReadingEndpoints []EndpointConfig
    ExecutionEndpoints []EndpointConfig
    FallbackEndpoints []EndpointConfig
    RateLimit RateLimitConfig
  }
  Bot {
    Enabled bool
    PollingInterval int
    MaxWorkers int
  }
  Contracts {
    ArbitrageExecutor string
    FlashSwappers []string
  }
  Arbitrage {
    MinProfit string
    MaxSlippage float64
    MaxGasPrice string
  }
}

CONCLUSION

The MEV Bot is a sophisticated, production-grade arbitrage detection and execution system with:

✓ Modular architecture - Independent, testable components ✓ High-throughput design - Worker pools, concurrent processing ✓ Comprehensive security - Key management, rate limiting, audit logs ✓ Multi-protocol support - Uniswap V2/V3, SushiSwap, Curve, Balancer ✓ Real-time monitoring - WebSocket and polling support ✓ Robust error handling - Retry logic, fallback providers, circuit breakers ✓ Production logging - Real-time analytics, health scoring, dashboards ✓ Flexible configuration - YAML + environment variables ✓ Extensive testing - Unit, integration, fork tests ✓ Smart contract integration - Direct contract execution via bindings

Known Limitations:

Pool discovery disabled at startup (cached pools only) to avoid hang
Security manager disabled (for debugging)
Single-threaded main loop (blocking RPC calls in monitor)
No persistent state for opportunities (in-memory only)

Opportunities for Enhancement:

Add persistent database for opportunity history
Implement MEV protection (MEV-Inspect, Flashbots)
Multi-chain support (Ethereum, Polygon)
Advanced path finding (dynamic programming)
Machine learning for opportunity ranking

36 KiB Raw Blame History

MEV Bot Codebase - Comprehensive Analysis Report

1. COMPLETE DIRECTORY STRUCTURE & ORGANIZATION

Root-Level Directories

Core Directories (by importance)

2. ALL PACKAGES IN DETAIL

A. Core Arbitrage Engine (pkg/arbitrage/ - 17 files, ~7000+ LOC)

B. Arbitrum Integration (pkg/arbitrum/ - 34 files, ~8000+ LOC)

C. Market Monitoring (pkg/monitor/ - 1 file, 1351 LOC)

D. Market Scanning (pkg/scanner/ - 5 subdirectories)

E. DEX Protocol Implementations (pkg/dex/ - 11 files)

F. Security & Key Management (pkg/security/ - 11 files, ~5000+ LOC)

G. Event Parsing & Processing (pkg/events/ - 1 file, 1806 LOC)

H. RPC Provider Management (pkg/transport/ - 3 files, ~1500 LOC)

I. Execution Management (pkg/execution/ - 4 files)

J. Pool Discovery & Management (pkg/pools/ - 1 file, 1065 LOC)

K. Mathematical Operations (pkg/math/ - 3 files, 1010+ LOC)

L. Validation (pkg/validation/ - 2 files)

M. Types & Interfaces (pkg/types/ and others)

3. KEY ARCHITECTURAL PATTERNS & DESIGN DECISIONS

A. Layered Architecture

B. Data Flow Pipeline

C. Concurrency Model

D. Configuration Management

4. MAIN WORKFLOWS & DATA FLOWS

A. Startup Workflow (main.go - 786 lines)

B. Real-Time Monitoring Loop

C. Event Processing & Arbitrage Detection

D. Arbitrage Execution Flow

5. EXTERNAL DEPENDENCIES & INTEGRATIONS

Go Module Dependencies

Smart Contract Integrations

6. CONFIGURATION MANAGEMENT APPROACH

Configuration Files

Environment Variables

7. TESTING INFRASTRUCTURE

Test Organization

Test Coverage

Build & Test Commands

8. BUILD & DEPLOYMENT SETUP

Build System

Docker Support

Production Logging

9. RECENT CHANGES & CURRENT STATE

Recent Major Changes (from git status)

Known Issues & Workarounds

Untracked Files (Build Artifacts, Cache, Docs)

10. CRITICAL COMPONENTS SUMMARY

Top 10 Most Important Files (by LOC and impact)

Critical Data Paths

11. ACTUAL vs DOCUMENTED STATE

Implementation Notes

Performance Characteristics

12. INTERACTION DIAGRAM

13. CONFIGURATION LOADING SEQUENCE

CONCLUSION

36 KiB

Raw Blame History

A. Core Arbitrage Engine (`pkg/arbitrage/` - 17 files, ~7000+ LOC)

B. Arbitrum Integration (`pkg/arbitrum/` - 34 files, ~8000+ LOC)

C. Market Monitoring (`pkg/monitor/` - 1 file, 1351 LOC)

D. Market Scanning (`pkg/scanner/` - 5 subdirectories)

E. DEX Protocol Implementations (`pkg/dex/` - 11 files)

F. Security & Key Management (`pkg/security/` - 11 files, ~5000+ LOC)

G. Event Parsing & Processing (`pkg/events/` - 1 file, 1806 LOC)

H. RPC Provider Management (`pkg/transport/` - 3 files, ~1500 LOC)

I. Execution Management (`pkg/execution/` - 4 files)

J. Pool Discovery & Management (`pkg/pools/` - 1 file, 1065 LOC)

K. Mathematical Operations (`pkg/math/` - 3 files, 1010+ LOC)

L. Validation (`pkg/validation/` - 2 files)

M. Types & Interfaces (`pkg/types/` and others)