# 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

```go
// 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