mev-beta/docs/planning/01_CRITICAL-001_Integer_Overflow_Fix_Plan.md

CRITICAL-001: Integer Overflow Vulnerabilities - Detailed Fix Plan

Issue ID: CRITICAL-001
Category: Security
Priority: Critical
Status: In Progress
Generated: October 9, 2025
Estimate: 4-6 hours

Overview

This plan addresses multiple integer overflow vulnerabilities found throughout the codebase where unsafe conversions from uint64 to uint32 or int64 occur. These conversions can lead to integer overflow, causing unexpected behavior and potential security vulnerabilities.

Affected Files and Lines

• pkg/arbitrum/l2_parser.go:827 - uint64 to uint32 conversion
• pkg/validation/input_validator.go:556 - Gas calculation overflow
• pkg/validation/input_validator.go:552 - Gas calculation overflow
• pkg/transport/benchmarks.go:271 - Memory usage calculation
• pkg/security/transaction_security.go:248 - Gas cost calculation
• pkg/profitcalc/profit_calc.go:251 - Gas limit conversion
• pkg/profitcalc/profit_calc.go:178 - Additional gas cost
• pkg/mev/competition.go:207 - Total cost calculation
• pkg/mev/competition.go:179 - Total cost calculation
• pkg/mev/competition.go:144 - Gas cost calculation
• pkg/math/arbitrage_calculator.go:296 - Total gas conversion
• pkg/contracts/executor.go:364 - Nonce conversion
• pkg/arbitrum/profitability_tracker.go:479 - Average profit calculation

Implementation Tasks

1. Create Safe Conversion Package

Task ID: CRITICAL-001.1
Time Estimate: 1 hour
Dependencies: None

Create a new package pkg/security/safe_conversions.go with the following functions:

// SafeUint64ToUint32 converts uint64 to uint32 with overflow check
func SafeUint64ToUint32(value uint64) (uint32, error)

// SafeUint64ToInt64 converts uint64 to int64 with bounds check
func SafeUint64ToInt64(value uint64) (int64, error)

// SafeUint64ToUint32WithDefault converts uint64 to uint32 with overflow check and default value
func SafeUint64ToUint32WithDefault(value uint64, defaultValue uint32) uint32

Implementation Details:

• Check if value exceeds math.MaxUint32 for uint32 conversion
• Return error if overflow would occur
• Include proper error messages with context

2. Add Bounds Checking for All Conversions

Task ID: CRITICAL-001.2
Time Estimate: 2 hours
Dependencies: CRITICAL-001.1

For each affected file, replace unsafe conversions with safe ones:

• In pkg/arbitrum/l2_parser.go:827: Replace direct uint32(value) with safe conversion
• In pkg/validation/input_validator.go:556 and 552: Check gas calculations for overflow
• In pkg/transport/benchmarks.go:271: Validate memory usage calculations
• In pkg/security/transaction_security.go:248: Ensure gas cost calculations are safe
• In pkg/profitcalc/profit_calc.go:251 and 178: Secure gas limit calculations
• In pkg/mev/competition.go:207, 179, 144: Validate total cost calculations
• In pkg/math/arbitrage_calculator.go:296: Check total gas conversion
• In pkg/contracts/executor.go:364: Secure nonce conversion
• In pkg/arbitrum/profitability_tracker.go:479: Validate average profit calculation

3. Update Calculation Functions

Task ID: CRITICAL-001.3
Time Estimate: 1.5 hours
Dependencies: CRITICAL-001.1, CRITICAL-001.2

Update all calculation functions to use safe conversions and implement overflow detection:

• Add pre-checks before arithmetic operations that could cause overflow
• Use math/big for critical operations where precision is paramount
• Implement error propagation for overflow conditions

4. Add Unit Tests for Overflow Detection

Task ID: CRITICAL-001.4
Time Estimate: 1 hour
Dependencies: CRITICAL-001.1

Create comprehensive unit tests for each safe conversion function:

• Test with maximum valid values
• Test with values that would cause overflow
• Test with edge cases (0, 1, MaxUint32, etc.)
• Test error handling and recovery

Test Structure:

func TestSafeUint64ToUint32(t *testing.T) {
    tests := []struct {
        name          string
        input         uint64
        expected      uint32
        expectError   bool
    }{
        // Define test cases
    }
    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            // Execute tests
        })
    }
}

5. Update Error Handling

Task ID: CRITICAL-001.5
Time Estimate: 0.5 hours
Dependencies: CRITICAL-001.2

For each conversion site, implement proper error handling:

• Return errors appropriately from functions
• Log overflow detection for monitoring
• Implement graceful degradation where possible
• Add circuit breakers for critical overflow scenarios

Testing Strategy

• Unit tests for each conversion function
• Integration tests for affected components
• Fuzz testing for edge cases
• Performance impact assessment

Code Review Checklist

• All unsafe conversions replaced with safe ones
• Proper error handling implemented
• Unit tests cover all conversion paths
• Performance impact is acceptable
• Error messages are informative
• Documentation updated

Rollback Strategy

If issues arise after deployment:

1. Revert the safe conversion changes
2. Temporarily disable the functionality causing overflow
3. Monitor system stability

Success Metrics

• Zero integer overflow errors in logs
• All unit tests pass
• No performance degradation >5%
• All affected functions handle edge cases correctly