mev-beta/docs/7_reference/UNISWAP_PRICING.md

Uniswap V3 Pricing Functions Documentation

Overview

This document provides comprehensive documentation for the Uniswap V3 pricing functions implemented in the MEV bot project. These functions are critical for calculating price conversions between sqrtPriceX96 format and standard price representations.

Files

pricing.go - Core Pricing Functions

This file contains the original implementations of Uniswap V3 pricing functions:

Functions

1. **SqrtPriceX96ToPrice(sqrtPriceX96 big.Int) big.Float

   • Converts a sqrtPriceX96 value to a standard price representation
   • Formula: price = (sqrtPriceX96 / 2^96)^2
   • Returns a *big.Float for precision

2. **PriceToSqrtPriceX96(price big.Float) big.Int

   • Converts a standard price to sqrtPriceX96 format
   • Formula: sqrtPriceX96 = sqrt(price) * 2^96
   • Returns a *big.Int

3. *TickToSqrtPriceX96(tick int) big.Int

   • Converts a tick value to sqrtPriceX96
   • Formula: sqrtPriceX96 = 1.0001^(tick/2) * 2^96

4. *SqrtPriceX96ToTick(sqrtPriceX96 big.Int) int

   • Converts sqrtPriceX96 to a tick value
   • Formula: tick = 2 * log_1.0001(sqrtPriceX96 / 2^96)

5. *GetTickAtSqrtPrice(sqrtPriceX96 uint256.Int) int

   • Calculates the tick for a given sqrtPriceX96 using uint256
   • Wrapper around SqrtPriceX96ToTick

6. GetNextTick(currentTick int, tickSpacing int) int

   • Calculates the next initialized tick based on tick spacing

7. GetPreviousTick(currentTick int, tickSpacing int) int

   • Calculates the previous initialized tick based on tick spacing

cached.go - Optimized Pricing Functions with Constant Caching

This file contains optimized versions of the pricing functions that cache expensive constant calculations:

Key Optimization

The primary optimization is caching the constants 2^96 and 2^192 to avoid recalculating them on every function call.

Functions

1. **SqrtPriceX96ToPriceCached(sqrtPriceX96 big.Int) big.Float

   • Optimized version of SqrtPriceX96ToPrice using cached constants
   • Performance improvement: ~24% faster than original

2. **PriceToSqrtPriceX96Cached(price big.Float) big.Int

   • Optimized version of PriceToSqrtPriceX96 using cached constants
   • Performance improvement: ~12% faster than original

Implementation Details

• Uses sync.Once to ensure constants are initialized only once
• Constants q96 and q192 are calculated once and reused
• Maintains mathematical precision while improving performance

optimized.go - Alternative Optimization Approaches

This file contains experimental optimization approaches:

Functions

1. **SqrtPriceX96ToPriceOptimized(sqrtPriceX96 big.Int) big.Float

   • Alternative optimization using different mathematical approaches

2. **PriceToSqrtPriceX96Optimized(price big.Float) big.Int

   • Alternative optimization using different mathematical approaches

contracts.go - Uniswap V3 Contract Interface

This file provides interfaces for interacting with Uniswap V3 pool contracts:

Key Components

1. UniswapV3Pool - Interface for interacting with Uniswap V3 pools
2. PoolState - Represents the current state of a pool
3. UniswapV3Pricing - Provides pricing calculations

Functions

• GetPoolState - Fetches current pool state
• GetPrice - Calculates price for token pairs
• CalculateAmountOut - Implements concentrated liquidity math for swaps

Mathematical Background

sqrtPriceX96 Format

Uniswap V3 uses a fixed-point representation for square root prices:

• sqrtPriceX96 = sqrt(price) * 2^96
• This allows for precise calculations without floating-point errors
• Prices are represented as token1/token0

Tick System

Uniswap V3 uses a tick system for price ranges:

• Ticks are spaced logarithmically
• Formula: tick = log_1.0001(price)
• Each tick represents a price movement of 0.01%

Performance Considerations

Benchmark Results

The optimized functions show significant performance improvements:

1. SqrtPriceX96ToPriceCached: 24% faster (1192 ns/op → 903.8 ns/op)
2. PriceToSqrtPriceX96Cached: 12% faster (1317 ns/op → 1158 ns/op)

Memory Allocations

Optimized functions reduce memory allocations by 20-33% through constant caching.

Usage Examples

// Convert sqrtPriceX96 to price
sqrtPrice := big.NewInt(79228162514264337593543950336) // 2^96
price := SqrtPriceX96ToPriceCached(sqrtPrice)

// Convert price to sqrtPriceX96
priceFloat := big.NewFloat(1.0)
sqrtPriceX96 := PriceToSqrtPriceX96Cached(priceFloat)

Testing

Each function is thoroughly tested with:

• Unit tests in *_test.go files
• Round-trip conversion accuracy tests
• Property-based testing for mathematical correctness
• Benchmark tests for performance verification

Best Practices

1. Use cached versions for repeated calculations
2. Always validate input parameters
3. Handle big.Int overflow conditions
4. Use appropriate precision for financial calculations
5. Profile performance in the context of your application