mev-beta/docs/8_reports/decimal_precision_policy.md

Decimal Precision and Rounding Policy

Document Version: 1.0 Last Updated: October 2025 Scope: MEV Bot Mathematical Operations and Financial Calculations

Executive Summary

This document establishes the comprehensive decimal precision and rounding policies for the MEV Bot project. These policies ensure mathematical accuracy, prevent precision loss, and maintain consistency across all financial calculations and arbitrage operations.

1. Core Precision Requirements

1.1 Fundamental Principle

All financial calculations MUST use the UniversalDecimal type to maintain arbitrary precision and prevent floating-point precision loss.

1.2 Precision Standards

• Minimum Precision: All calculations must achieve ≤1 basis point (0.01%) error tolerance
• Target Precision: 0.0000 basis points error for exchange pricing calculations
• Critical Operations: Arbitrage profit calculations require perfect precision (0 rounding error)

1.3 Prohibited Types

The following types are PROHIBITED for financial calculations:

• float32 / float64 - Risk of precision loss
• int / int64 - Cannot represent fractional amounts
• Standard library big.Float without decimal context - Lacks token-aware precision

2. UniversalDecimal Implementation

2.1 Structure

type UniversalDecimal struct {
    Value    *big.Int  // Precise integer representation
    Decimals uint8     // Number of decimal places (e.g., 18 for ETH, 6 for USDC)
    Symbol   string    // Token symbol for context and debugging
}

2.2 Creation Guidelines

// ✅ CORRECT: Always specify decimals and symbol
ethAmount, err := math.NewUniversalDecimal(
    big.NewInt(1000000000000000000), // 1 ETH in wei
    18,    // ETH has 18 decimals
    "ETH", // Symbol for context
)

// ❌ INCORRECT: Using float64
var amount float64 = 1.5 // Risk of precision loss

2.3 Conversion Rules

1. From String: Always use DecimalConverter.FromString() with proper decimals
2. To String: Use DecimalConverter.ToHumanReadable() for display
3. Cross-Decimal Operations: Automatic normalization to common decimal base

3. Exchange-Specific Precision Policies

3.1 Uniswap V2

• Price Calculation: price = reserve1 / reserve0 with decimal normalization
• Precision Target: 0.0000 bp error
• Decimal Handling: Automatic scaling to 18-decimal precision for calculations
• Token Support: ETH (18), USDC (6), WBTC (8), USDT (6)

3.2 Uniswap V3

• Price Calculation: From sqrtPriceX96 using price = (sqrtPriceX96 / 2^96)^2
• Precision Target: 0.0000 bp error
• Decimal Adjustment: Account for token decimal differences (e.g., ETH=18, USDC=6)
• Special Handling: Concentrated liquidity positions maintain full precision

3.3 Curve Finance

• Price Calculation: Stable swap formula with decimal normalization
• Precision Target: 0.0000 bp error
• Stable Pairs: USDC/USDT, DAI/USDC with 1:1 expectation
• Decimal Policy: Normalize to 18 decimals for calculation, convert back for display

3.4 Balancer

• Price Calculation: Weighted formula price = (reserve1/weight1) / (reserve0/weight0)
• Precision Target: 0.0000 bp error
• Weight Handling: Use big.Float for weight calculations, convert to UniversalDecimal
• Common Pools: 80/20 ETH/USDC, 60/40 WBTC/ETH

4. Arbitrage Calculation Policies

4.1 Profit Calculation

// Profit calculation with full precision
func calculateProfit(amountIn, amountOut *UniversalDecimal) (*UniversalDecimal, error) {
    // Ensure same decimal precision
    normalizedIn := normalize(amountIn, 18)
    normalizedOut := normalize(amountOut, 18)

    // Calculate gross profit
    profit := normalizedOut.Sub(normalizedIn)

    // Return with appropriate symbol
    return NewUniversalDecimal(profit.Value, 18, "PROFIT")
}

4.2 ROI Calculation

// ROI = (profit / amountIn) * 10000 (in basis points)
func calculateROI(profit, amountIn *UniversalDecimal) float64 {
    // Use big.Float only for final percentage calculation
    profitFloat := new(big.Float).SetInt(profit.Value)
    amountFloat := new(big.Float).SetInt(amountIn.Value)

    roi := new(big.Float).Quo(profitFloat, amountFloat)
    roi.Mul(roi, big.NewFloat(10000.0)) // Convert to basis points

    result, _ := roi.Float64()
    return result
}

4.3 Gas Cost Integration

• Gas costs MUST be calculated in wei (18 decimals)
• Convert to token decimals only for final profit calculation
• Net profit = Gross profit - Gas costs (both in same decimal precision)

5. Rounding Policies

5.1 Default Rounding

• Method: Round to nearest, ties to even (banker's rounding)
• Application: Final display values only
• Internal Calculations: NO rounding until final result

5.2 Precision Preservation

// ✅ CORRECT: Preserve precision during calculations
result := amount1.Add(amount2).Multiply(price).Subtract(gasCost)

// ❌ INCORRECT: Intermediate rounding
step1 := round(amount1.Add(amount2))  // Loses precision
step2 := round(step1.Multiply(price)) // Compounds error

5.3 Display Rounding

// For UI display only
func formatForDisplay(amount *UniversalDecimal, decimals int) string {
    humanReadable := converter.ToHumanReadable(amount)
    return fmt.Sprintf("%."+strconv.Itoa(decimals)+"f", humanReadable)
}

6. Error Tolerance Standards

6.1 Basis Point Definitions

• 1 basis point (bp) = 0.01% = 0.0001 in decimal
• Acceptable Error: ≤ 1 bp for production operations
• Target Error: 0.0000 bp for exchange pricing
• Maximum Error: 10 bp triggers automatic rejection

6.2 Validation Requirements

// Error calculation for validation
func calculateErrorBP(expected, actual *UniversalDecimal) float64 {
    if expected.Value.Cmp(big.NewInt(0)) == 0 {
        return 0.0 // Perfect if both are zero
    }

    diff := new(big.Int).Sub(actual.Value, expected.Value)
    if diff.Sign() < 0 {
        diff.Neg(diff)
    }

    // Convert to basis points
    diffFloat := new(big.Float).SetInt(diff)
    expectedFloat := new(big.Float).SetInt(expected.Value)

    errorFloat := new(big.Float).Quo(diffFloat, expectedFloat)
    errorFloat.Mul(errorFloat, big.NewFloat(10000.0))

    result, _ := errorFloat.Float64()
    return result
}

7. Testing and Validation

7.1 Regression Test Requirements

• All exchange calculations must pass regression tests
• Profit calculations must maintain precision over time
• Cross-decimal operations must preserve accuracy

7.2 Audit Standards

# Run comprehensive math audit
./bin/math-audit audit --vectors default --verbose

# Expected output:
# Total Tests: 10
# Passed: 10
# Failed: 0
# Overall Status: PASS

7.3 Continuous Validation

• Automated regression tests in CI/CD pipeline
• Weekly precision audits in production
• Alert system for precision degradation

8. Implementation Guidelines

8.1 Code Review Checklist

• All financial calculations use UniversalDecimal
• Proper decimal precision specified for each token
• No intermediate rounding in calculations
• Error tolerance meets standards (≤1 bp)
• Comprehensive test coverage

8.2 Performance Considerations

• UniversalDecimal operations are more expensive than float64
• Cache frequently used conversions
• Optimize hot paths while maintaining precision
• Profile critical calculation paths

8.3 Migration Guidelines

// When migrating from float64 to UniversalDecimal
// OLD:
price := float64(reserve1) / float64(reserve0)

// NEW:
price, err := converter.Divide(
    reserve1,           // *UniversalDecimal
    reserve0,           // *UniversalDecimal
    18,                 // Result decimals
    "PRICE",           // Result symbol
)

9. Monitoring and Alerting

9.1 Precision Monitoring

• Real-time error tracking in basis points
• Alert when error > 0.5 bp for any exchange
• Daily precision reports for audit trail

9.2 Failure Response

1. Error > 1 bp: Automatic calculation retry
2. Error > 5 bp: Disable affected exchange temporarily
3. Error > 10 bp: Emergency stop and manual review

10. Documentation Requirements

10.1 Code Documentation

// CalculateArbitrageProfit calculates the net profit for an arbitrage opportunity
// maintaining full decimal precision throughout the calculation process.
//
// Precision Policy:
// - All intermediate calculations preserve full precision
// - Final result normalized to 18 decimals
// - Error tolerance: ≤ 1 basis point
//
// Parameters:
//   amountIn: Input amount with proper token decimals
//   amountOut: Output amount with proper token decimals
//   gasCost: Gas cost in wei (18 decimals)
//
// Returns:
//   *UniversalDecimal: Net profit with 18 decimal precision
//   error: Any calculation errors
func CalculateArbitrageProfit(amountIn, amountOut, gasCost *UniversalDecimal) (*UniversalDecimal, error)

10.2 Change Management

• All precision policy changes require architecture review
• Backward compatibility testing for precision changes
• Version control for decimal precision standards

11. Conclusion

This decimal precision policy ensures the MEV Bot maintains mathematical accuracy and prevents costly precision errors. All team members must adhere to these standards, and any deviations require explicit approval and documentation.

Key Takeaways:

1. Always use UniversalDecimal for financial calculations
2. Target 0.0000 bp error for exchange pricing
3. Never round intermediate calculations
4. Validate precision with comprehensive testing
5. Monitor precision in production continuously

---

Document Approval:

• Technical Lead: ✅ Approved
• Architecture Review: ✅ Approved
• Security Review: ✅ Approved
• Date: October 2025