@steerprotocol/sdk 1.26.0 → 1.28.0

package/src/base/vault/single-asset/readmes/calculateLimitPrice.md

@@ -0,0 +1,455 @@
+# calculateLimitPrice
+
+Calculates slippage-protected price limits for internal swap operations during single-asset deposits.
+
+## Overview
+
+When performing the internal swap as part of a single-asset deposit, it's crucial to set appropriate price limits to prevent excessive slippage. This function calculates the sqrt price limit that protects against unfavorable price movements while allowing the swap to execute successfully.
+
+## Function Signature
+
+```typescript
+async function calculateLimitPrice(
+  publicClient: PublicClient,
+  params: CalculateLimitPriceParams
+): Promise<SteerResponse<bigint>>
+```
+
+## Parameters
+
+### CalculateLimitPriceParams
+
+```typescript
+interface CalculateLimitPriceParams {
+  /** Address of the pool */
+  pool: Address;
+  /** Slippage tolerance in basis points */
+  slippageBP: number;
+  /** true if swapping token0 for token1, false otherwise */
+  zeroForOne: boolean;
+  /** Type of AMM */
+  ammType: AMMType;
+  /** Address of token0 */
+  token0: Address;
+  /** Address of token1 */
+  token1: Address;
+}
+```
+
+**Parameter Details:**
+
+- **`pool`**: The pool address where the swap will occur
+- **`slippageBP`**: Slippage tolerance in basis points (e.g., 500 = 5%)
+- **`zeroForOne`**: Swap direction - true for token0→token1, false for token1→token0
+- **`ammType`**: AMM protocol type (currently supports `AMMType.UniswapV3`)
+- **`token0`**: Address of token0 in the pool
+- **`token1`**: Address of token1 in the pool
+
+## Return Value
+
+Returns `Promise<SteerResponse<bigint>>` where the data is the sqrt price limit in X96 format.
+
+**Response Data:**
+- **`sqrtPriceLimitX96`**: The calculated price limit in Uniswap's Q96 fixed-point format
+
+## Examples
+
+### Basic Usage
+
+```typescript
+import { calculateLimitPrice, AMMType } from '@steerprotocol/sdk';
+
+const result = await calculateLimitPrice(publicClient, {
+  pool: '0xd19a1c8278d0420bfb2c825d99dc31ff86224607',
+  slippageBP: 500,        // 5% slippage tolerance
+  zeroForOne: true,       // Swapping token0 for token1
+  ammType: AMMType.UniswapV3,
+  token0: '0x7ceb23fd6bc0add59e62ac25578270cff1b9f619',
+  token1: '0xc708d6f2153933daa50b2d0758955be0a93a8fec'
+});
+
+if (result.success) {
+  console.log('Price limit:', result.data);
+  
+  // Use this limit in swap operations
+  const swapParams = {
+    // ... other params
+    sqrtPriceLimitX96: result.data
+  };
+} else {
+  console.error('Failed to calculate limit price:', result.error);
+}
+```
+
+### Different Slippage Tolerances
+
+```typescript
+// Conservative slippage (1%)
+const conservativeResult = await calculateLimitPrice(publicClient, {
+  pool: poolAddress,
+  slippageBP: 100,        // 1% slippage
+  zeroForOne: true,
+  ammType: AMMType.UniswapV3,
+  token0: token0Address,
+  token1: token1Address
+});
+
+// Moderate slippage (5%)
+const moderateResult = await calculateLimitPrice(publicClient, {
+  pool: poolAddress,
+  slippageBP: 500,        // 5% slippage
+  zeroForOne: true,
+  ammType: AMMType.UniswapV3,
+  token0: token0Address,
+  token1: token1Address
+});
+
+// High slippage (10%)
+const highResult = await calculateLimitPrice(publicClient, {
+  pool: poolAddress,
+  slippageBP: 1000,       // 10% slippage
+  zeroForOne: true,
+  ammType: AMMType.UniswapV3,
+  token0: token0Address,
+  token1: token1Address
+});
+```
+
+### Reverse Direction Swap
+
+```typescript
+// For token1 → token0 swaps
+const result = await calculateLimitPrice(publicClient, {
+  pool: poolAddress,
+  slippageBP: 500,
+  zeroForOne: false,      // Swapping token1 for token0
+  ammType: AMMType.UniswapV3,
+  token0: token0Address,
+  token1: token1Address
+});
+```
+
+## Algorithm Details
+
+The function implements high-precision slippage protection using Decimal.js:
+
+### 1. Get Current Pool State
+
+```typescript
+// Retrieves current sqrt price from pool's slot0
+const slot0Data = await getPoolState(publicClient, {
+  poolAddress: params.pool,
+  isAlgebraPool: params.ammType === AMMType.Algebra,
+  // ... other flags
+});
+```
+
+### 2. Apply Slippage Protection
+
+The slippage protection logic varies by swap direction:
+
+**For zeroForOne swaps (token0 → token1):**
+- User wants to ensure they get at least the expected amount of token1
+- Price limit is set to a lower value (less favorable rate)
+- Formula: `adjustedQuote = currentQuote * (10000 - slippageBP) / 10000`
+
+**For oneForZero swaps (token1 → token0):**
+- User wants to ensure they don't pay too much token1
+- Price limit is set to a higher value (maximum acceptable rate)
+- Formula: `adjustedQuote = currentQuote * (10000 + slippageBP) / 10000`
+
+### 3. High-Precision Arithmetic
+
+Uses Decimal.js for all calculations to prevent precision loss:
+
+```typescript
+// Configure Decimal.js for financial precision
+Decimal.config({ 
+  precision: 50,
+  rounding: Decimal.ROUND_DOWN
+});
+
+const currentQuote = getQuoteFromSqrtRatioX96(
+  sqrtPriceX96,
+  baseAmount,
+  token0,
+  token1
+);
+```
+
+## Testing
+
+### Unit Test Example
+
+```typescript
+describe('calculateLimitPrice', () => {
+  it('should calculate correct limit price for zeroForOne swap', async () => {
+    const mockSlot0 = [
+      BigInt('79228162514264337593543950336'), // sqrtPriceX96
+      0,    // tick
+      0,    // observationIndex
+      1,    // observationCardinality
+      1,    // observationCardinalityNext
+      0,    // feeProtocol
+      true  // unlocked
+    ];
+
+    const mockPublicClient = {
+      readContract: jest.fn()
+        .mockResolvedValueOnce(mockSlot0)  // slot0 call
+        .mockResolvedValueOnce(18)         // token0 decimals
+        .mockResolvedValueOnce(6),         // token1 decimals
+      getChainId: jest.fn().mockResolvedValue(137)
+    };
+
+    const result = await calculateLimitPrice(mockPublicClient, {
+      pool: mockPoolAddress,
+      slippageBP: 500,  // 5%
+      zeroForOne: true,
+      ammType: AMMType.UniswapV3,
+      token0: mockToken0Address,
+      token1: mockToken1Address
+    });
+
+    expect(result.success).toBe(true);
+    expect(result.data).toBeGreaterThan(0n);
+    // Price limit should be lower than current price for zeroForOne
+    expect(result.data).toBeLessThan(BigInt('79228162514264337593543950336'));
+  });
+});
+```
+
+### Integration Test with Real Pool
+
+```typescript
+it('should work with real pool data', async () => {
+  const realClient = createPublicClient({
+    chain: polygon,
+    transport: http()
+  });
+
+  const result = await calculateLimitPrice(realClient, {
+    pool: '0xd19a1c8278d0420bfb2c825d99dc31ff86224607', // Real WETH/USDC pool
+    slippageBP: 300,  // 3%
+    zeroForOne: true,
+    ammType: AMMType.UniswapV3,
+    token0: '0x7ceb23fd6bc0add59e62ac25578270cff1b9f619', // WETH
+    token1: '0xc708d6f2153933daa50b2d0758955be0a93a8fec'  // USDC
+  });
+
+  expect(result.success).toBe(true);
+  expect(result.data).toBeGreaterThan(0n);
+});
+```
+
+## Error Handling
+
+### Common Error Scenarios
+
+```typescript
+async function safeCalculateLimitPrice(params: CalculateLimitPriceParams) {
+  try {
+    const result = await calculateLimitPrice(publicClient, params);
+    
+    if (!result.success) {
+      if (result.error?.includes('pool state')) {
+        throw new Error('Pool is in invalid state. May be paused or uninitialized.');
+      }
+      
+      if (result.error?.includes('decimals')) {
+        throw new Error('Unable to read token decimals. Check token addresses.');
+      }
+      
+      throw new Error(`Limit price calculation failed: ${result.error}`);
+    }
+    
+    return result.data;
+  } catch (error) {
+    console.error('Error calculating limit price:', error);
+    throw error;
+  }
+}
+```
+
+### Parameter Validation
+
+```typescript
+function validateLimitPriceParams(params: CalculateLimitPriceParams): void {
+  if (!params.pool || params.pool === '0x0000000000000000000000000000000000000000') {
+    throw new Error('Invalid pool address');
+  }
+  
+  if (params.slippageBP <= 0 || params.slippageBP > 10000) {
+    throw new Error('Slippage BP must be between 1 and 10000');
+  }
+  
+  if (!params.token0 || !params.token1) {
+    throw new Error('Token addresses are required');
+  }
+  
+  if (params.token0 === params.token1) {
+    throw new Error('Token addresses must be different');
+  }
+}
+```
+
+## Best Practices
+
+### 1. Choose Appropriate Slippage Tolerances
+
+```typescript
+// Recommended slippage tolerances based on scenarios
+const SLIPPAGE_TOLERANCES = {
+  CONSERVATIVE: 100,   // 1% - For stable pools or small amounts
+  MODERATE: 500,       // 5% - For most use cases
+  HIGH: 1000,          // 10% - For volatile pools or large amounts
+  EMERGENCY: 2000      // 20% - Only for emergency situations
+};
+
+function getRecommendedSlippage(
+  poolVolatility: 'low' | 'medium' | 'high',
+  swapSize: 'small' | 'medium' | 'large'
+): number {
+  if (poolVolatility === 'low' && swapSize === 'small') {
+    return SLIPPAGE_TOLERANCES.CONSERVATIVE;
+  }
+  
+  if (poolVolatility === 'high' || swapSize === 'large') {
+    return SLIPPAGE_TOLERANCES.HIGH;
+  }
+  
+  return SLIPPAGE_TOLERANCES.MODERATE;
+}
+```
+
+### 2. Cache Price Calculations
+
+```typescript
+interface PriceLimitCache {
+  timestamp: number;
+  sqrtPriceLimitX96: bigint;
+}
+
+const priceCache = new Map<string, PriceLimitCache>();
+const CACHE_DURATION = 30000; // 30 seconds
+
+async function cachedCalculateLimitPrice(
+  params: CalculateLimitPriceParams
+): Promise<bigint> {
+  const key = JSON.stringify(params);
+  const cached = priceCache.get(key);
+  
+  if (cached && Date.now() - cached.timestamp < CACHE_DURATION) {
+    return cached.sqrtPriceLimitX96;
+  }
+  
+  const result = await calculateLimitPrice(publicClient, params);
+  if (!result.success) {
+    throw new Error(result.error);
+  }
+  
+  priceCache.set(key, {
+    timestamp: Date.now(),
+    sqrtPriceLimitX96: result.data
+  });
+  
+  return result.data;
+}
+```
+
+### 3. Dynamic Slippage Based on Market Conditions
+
+```typescript
+async function getDynamicSlippage(
+  pool: Address,
+  baseSlippageBP: number
+): Promise<number> {
+  try {
+    // Get recent price volatility (implementation depends on your data source)
+    const volatility = await getPoolVolatility(pool);
+    
+    // Adjust slippage based on volatility
+    let adjustedSlippage = baseSlippageBP;
+    
+    if (volatility > 0.05) { // 5% volatility
+      adjustedSlippage = Math.min(baseSlippageBP * 2, 2000); // Cap at 20%
+    } else if (volatility < 0.01) { // 1% volatility
+      adjustedSlippage = Math.max(baseSlippageBP * 0.5, 50); // Minimum 0.5%
+    }
+    
+    return adjustedSlippage;
+  } catch (error) {
+    // Fallback to base slippage if volatility data unavailable
+    return baseSlippageBP;
+  }
+}
+```
+
+## Mathematical Details
+
+### Q96 Fixed-Point Format
+
+Uniswap V3 uses Q96 fixed-point arithmetic for price representation:
+
+```typescript
+// Q96 means 96 fractional bits
+const Q96 = 2n ** 96n;
+
+// Convert price to Q96 format
+function priceToSqrtPriceX96(price: number): bigint {
+  const sqrtPrice = Math.sqrt(price);
+  return BigInt(Math.floor(sqrtPrice * (2 ** 96)));
+}
+
+// Convert from Q96 format to price
+function sqrtPriceX96ToPrice(sqrtPriceX96: bigint): number {
+  const sqrtPrice = Number(sqrtPriceX96) / (2 ** 96);
+  return sqrtPrice ** 2;
+}
+```
+
+### Price Calculation Formula
+
+For a token pair, the price is derived from sqrtPriceX96:
+
+```typescript
+// Price of token1 in terms of token0
+const price = (sqrtPriceX96 / Q96) ** 2;
+
+// For tokens with different decimals
+const adjustedPrice = price * (10 ** (decimals0 - decimals1));
+```
+
+## Related Functions
+
+- **[calculateSwapAmount](./calculateSwapAmount.md)** - Calculates optimal swap amount
+- **[simulateSwap](./simulateSwap.md)** - Uses the calculated limit price for swap simulation
+- **[getPoolSlot0](./getPoolSlot0.md)** - Retrieves current pool state data
+
+## Utility Functions
+
+### getQuoteFromSqrtRatioX96
+
+```typescript
+function getQuoteFromSqrtRatioX96(
+  sqrtRatioX96: Decimal,
+  baseAmount: Decimal,
+  baseToken: Address,
+  quoteToken: Address
+): Decimal {
+  // High-precision price quote calculation
+  if (sqrtRatioX96.lte(UINT128_MAX)) {
+    const ratioX192 = sqrtRatioX96.mul(sqrtRatioX96);
+    return baseToken < quoteToken
+      ? mulDiv(ratioX192, baseAmount, Q192)
+      : mulDiv(Q192, baseAmount, ratioX192);
+  } else {
+    const ratioX128 = mulDiv(sqrtRatioX96, sqrtRatioX96, Q64);
+    return baseToken < quoteToken
+      ? mulDiv(ratioX128, baseAmount, Q128)
+      : mulDiv(Q128, baseAmount, ratioX128);
+  }
+}
+```
+
+This function ensures calculations match Solidity implementations exactly.