@steerprotocol/sdk 1.27.0 → 1.28.0

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

@@ -0,0 +1,612 @@
+# simulateSwap
+
+Simulates swap operations to preview expected output amounts and price impact without executing the transaction on-chain.
+
+## Overview
+
+The `simulateSwap` function uses Uniswap V3's Quoter contract to accurately simulate swap operations. This allows users to preview the exact amounts they'll receive and the price impact before committing to a transaction. It's a crucial component of the single-asset deposit flow that provides transparency and helps prevent unexpected results.
+
+## Function Signatures
+
+### Basic Simulation
+
+```typescript
+async function simulateSwap(
+  publicClient: PublicClient,
+  params: SimulateSwapParams,
+  chainId: number
+): Promise<SteerResponse<SwapSimulationResponse>>
+```
+
+### Enhanced Simulation with Slippage Analysis
+
+```typescript
+async function simulateSwapWithSlippage(
+  publicClient: PublicClient,
+  params: SwapWithSlippageParams,
+  chainId: number
+): Promise<SteerResponse<SwapWithSlippageResponse>>
+```
+
+## Parameters
+
+### SimulateSwapParams
+
+```typescript
+interface SimulateSwapParams {
+  /** Address of the pool */
+  pool: Address;
+  /** Address that will receive the swap output (or address(this) for simulation) */
+  recipient: Address;
+  /** true if swapping token0 → token1, else false */
+  zeroForOne: boolean;
+  /** Value from calculateSwapAmount */
+  amountSpecified: bigint;
+  /** Slippage-adjusted limit price */
+  sqrtPriceLimitX96: bigint;
+  /** AMM type */
+  ammType: AMMType;
+  /** Input token address (required for Quoter) */
+  tokenIn: Address;
+  /** Output token address (required for Quoter) */
+  tokenOut: Address;
+  /** Pool fee (required for Quoter) */
+  fee: number;
+  /** Quoter contract address (optional - will use default if not provided) */
+  quoterAddress?: Address;
+}
+```
+
+### SwapWithSlippageParams
+
+```typescript
+interface SwapWithSlippageParams {
+  /** Address of the pool */
+  poolAddress: string;
+  /** Address that will receive the swap output */
+  recipient: string;
+  /** true if swapping token0 → token1, else false */
+  zeroForOne: boolean;
+  /** Amount to swap */
+  amountSpecified: bigint;
+  /** Slippage-adjusted limit price */
+  sqrtPriceLimitX96: bigint;
+  /** AMM type */
+  ammType: AMMType;
+  /** Input token address */
+  tokenIn: string;
+  /** Output token address */
+  tokenOut: string;
+  /** Pool fee */
+  fee: number;
+  /** Quoter contract address (optional) */
+  quoterAddress?: string;
+}
+```
+
+## Return Values
+
+### SwapSimulationResponse
+
+```typescript
+interface SwapSimulationResponse {
+  /** Final token0 amount after swap (negative = out, positive = in) */
+  amount0: bigint;
+  /** Final token1 amount after swap (negative = out, positive = in) */
+  amount1: bigint;
+  /** Pool price after the swap */
+  sqrtPriceX96After: bigint;
+}
+```
+
+### SwapWithSlippageResponse
+
+```typescript
+interface SwapWithSlippageResponse {
+  /** Current pool slot0 data */
+  currentSlot0: PoolSlot0;
+  /** Swap simulation results */
+  swapSimulation: SwapSimulationResponse;
+  /** Price slippage percentage (positive means price moved unfavorably) */
+  priceSlippagePercent: string;
+  /** Current price (derived from sqrtPriceX96) */
+  currentPrice: bigint;
+  /** Price after swap (derived from sqrtPriceX96After) */
+  priceAfter: bigint;
+}
+```
+
+## Examples
+
+### Basic Swap Simulation
+
+```typescript
+import { simulateSwap, AMMType } from '@steerprotocol/sdk';
+
+const result = await simulateSwap(publicClient, {
+  pool: '0xd19a1c8278d0420bfb2c825d99dc31ff86224607',
+  recipient: userAddress,
+  zeroForOne: true,                          // Swapping token0 for token1
+  amountSpecified: parseEther('10'),         // Swapping 10 token0
+  sqrtPriceLimitX96: calculatedPriceLimit,   // From calculateLimitPrice
+  ammType: AMMType.UniswapV3,
+  tokenIn: '0x7ceb23fd6bc0add59e62ac25578270cff1b9f619',   // WETH
+  tokenOut: '0xc708d6f2153933daa50b2d0758955be0a93a8fec',  // USDC
+  fee: 3000                                  // 0.3% fee tier
+}, 137); // Polygon chain ID
+
+if (result.success) {
+  console.log('Token0 delta:', result.data.amount0); // Should be -10 ETH
+  console.log('Token1 delta:', result.data.amount1); // Should be +X USDC
+  console.log('Price after swap:', result.data.sqrtPriceX96After);
+  
+  // Calculate received amount
+  const receivedAmount = result.data.zeroForOne 
+    ? result.data.amount1  // For token0->token1 swaps
+    : result.data.amount0; // For token1->token0 swaps
+    
+  console.log('Will receive:', formatUnits(receivedAmount, 6), 'USDC');
+} else {
+  console.error('Simulation failed:', result.error);
+}
+```
+
+### Enhanced Simulation with Slippage Analysis
+
+```typescript
+import { simulateSwapWithSlippage, AMMType } from '@steerprotocol/sdk';
+
+const result = await simulateSwapWithSlippage(publicClient, {
+  poolAddress: '0xd19a1c8278d0420bfb2c825d99dc31ff86224607',
+  recipient: userAddress,
+  zeroForOne: false,                         // Swapping token1 for token0
+  amountSpecified: parseUnits('1000', 6),    // Swapping 1000 USDC
+  sqrtPriceLimitX96: priceLimit,
+  ammType: AMMType.UniswapV3,
+  tokenIn: '0xc708d6f2153933daa50b2d0758955be0a93a8fec',   // USDC
+  tokenOut: '0x7ceb23fd6bc0add59e62ac25578270cff1b9f619',  // WETH
+  fee: 3000
+}, 137);
+
+if (result.success) {
+  const { swapSimulation, priceSlippagePercent, currentPrice, priceAfter } = result.data;
+  
+  console.log('Price slippage:', priceSlippagePercent + '%');
+  console.log('Current price:', formatEther(currentPrice));
+  console.log('Price after swap:', formatEther(priceAfter));
+  
+  // Check if slippage is acceptable
+  const slippage = parseFloat(priceSlippagePercent);
+  if (slippage > 2.0) {
+    console.warn(`High price impact: ${slippage}%`);
+  }
+  
+  // Get swap amounts
+  console.log('USDC in:', formatUnits(-swapSimulation.amount1, 6));
+  console.log('WETH out:', formatEther(swapSimulation.amount0));
+} else {
+  console.error('Enhanced simulation failed:', result.error);
+}
+```
+
+### Complete Single-Asset Deposit Simulation
+
+```typescript
+async function simulateCompleteDeposit(
+  depositParams: SingleAssetDepositParams,
+  poolAddress: Address
+) {
+  // Step 1: Calculate swap amount
+  const swapAmountResult = await calculateSwapAmount(publicClient, {
+    depositAmount: depositParams.assets,
+    isToken0: depositParams.isToken0,
+    vault: depositParams.vault,
+    pool: poolAddress,
+    ammType: depositParams.ammType,
+    singleAssetDepositContract: depositParams.singleAssetDepositContract!
+  });
+
+  if (!swapAmountResult.success) {
+    throw new Error('Failed to calculate swap amount');
+  }
+
+  // Step 2: Calculate price limit
+  const limitPriceResult = await calculateLimitPrice(publicClient, {
+    pool: poolAddress,
+    slippageBP: depositParams.swapSlippageBP,
+    zeroForOne: depositParams.isToken0,
+    ammType: depositParams.ammType,
+    token0: token0Address,
+    token1: token1Address
+  });
+
+  if (!limitPriceResult.success) {
+    throw new Error('Failed to calculate limit price');
+  }
+
+  // Step 3: Simulate the swap with detailed analysis
+  const simulationResult = await simulateSwapWithSlippage(publicClient, {
+    poolAddress: poolAddress,
+    recipient: depositParams.receiver,
+    zeroForOne: depositParams.isToken0,
+    amountSpecified: swapAmountResult.data.swapAmount,
+    sqrtPriceLimitX96: limitPriceResult.data,
+    ammType: depositParams.ammType,
+    tokenIn: depositParams.isToken0 ? token0Address : token1Address,
+    tokenOut: depositParams.isToken0 ? token1Address : token0Address,
+    fee: poolFee
+  }, chainId);
+
+  return {
+    swapAmount: swapAmountResult.data.swapAmount,
+    priceLimit: limitPriceResult.data,
+    simulation: simulationResult.data
+  };
+}
+```
+
+## Algorithm Details
+
+### Quoter Integration
+
+The function uses Uniswap V3's Quoter contract for accurate simulation:
+
+```typescript
+// Call Quoter's quoteExactInputSingle
+const result = await publicClient.call({
+  to: quoterAddress,
+  data: encodeFunctionData({
+    abi: UniswapV3QuoterABI,
+    functionName: 'quoteExactInputSingle',
+    args: [{
+      tokenIn: params.tokenIn,
+      tokenOut: params.tokenOut,
+      amountIn: params.amountSpecified,
+      fee: params.fee,
+      sqrtPriceLimitX96: params.sqrtPriceLimitX96
+    }]
+  })
+});
+
+// Decode the result
+const [amountOut, sqrtPriceX96After] = decodeFunctionResult({
+  abi: UniswapV3QuoterABI,
+  functionName: 'quoteExactInputSingle',
+  data: result.data
+});
+```
+
+### Amount Direction Logic
+
+```typescript
+// Convert quoter results to signed amounts
+let amount0: bigint, amount1: bigint;
+
+if (params.zeroForOne) {
+  // Swapping token0 for token1
+  amount0 = -params.amountSpecified; // negative (token0 out)
+  amount1 = amountOut;                // positive (token1 in)
+} else {
+  // Swapping token1 for token0
+  amount0 = amountOut;                // positive (token0 in)
+  amount1 = -params.amountSpecified;  // negative (token1 out)
+}
+```
+
+### Price Impact Calculation
+
+```typescript
+function calculatePriceSlippage(
+  priceBefore: Decimal,
+  priceAfter: Decimal,
+  zeroForOne: boolean
+): Decimal {
+  const priceChange = priceAfter.minus(priceBefore)
+    .dividedBy(priceBefore)
+    .times(100);
+  
+  // Return positive for unfavorable movement
+  return zeroForOne ? priceChange : priceChange.negated();
+}
+```
+
+## Testing
+
+### Unit Test Example
+
+```typescript
+describe('simulateSwap', () => {
+  it('should simulate token0->token1 swap correctly', async () => {
+    const mockQuoterResult = '0x' + 
+      '000000000000000000000000000000000000000000000000000000174876e800' + // amountOut
+      '000000000000000000000000000000000001000276a4d800000000000000000000'; // sqrtPriceX96After
+
+    const mockPublicClient = {
+      call: jest.fn().mockResolvedValue({ data: mockQuoterResult }),
+      chain: { id: 137 }
+    };
+
+    const result = await simulateSwap(mockPublicClient, {
+      pool: mockPoolAddress,
+      recipient: mockRecipient,
+      zeroForOne: true,
+      amountSpecified: parseEther('10'),
+      sqrtPriceLimitX96: BigInt('1000000000000000000000000000'),
+      ammType: AMMType.UniswapV3,
+      tokenIn: mockToken0Address,
+      tokenOut: mockToken1Address,
+      fee: 3000
+    }, 137);
+
+    expect(result.success).toBe(true);
+    expect(result.data.amount0).toBe(-parseEther('10')); // 10 token0 out
+    expect(result.data.amount1).toBeGreaterThan(0n);     // token1 received
+  });
+});
+```
+
+### Integration Test
+
+```typescript
+it('should work with real Quoter contract', async () => {
+  const realClient = createPublicClient({
+    chain: polygon,
+    transport: http()
+  });
+
+  const result = await simulateSwap(realClient, {
+    pool: '0xd19a1c8278d0420bfb2c825d99dc31ff86224607', // Real WETH/USDC pool
+    recipient: '0x0000000000000000000000000000000000000000',
+    zeroForOne: true,
+    amountSpecified: parseEther('0.1'), // 0.1 WETH
+    sqrtPriceLimitX96: BigInt('79228162514264337593543950336'),
+    ammType: AMMType.UniswapV3,
+    tokenIn: '0x7ceb23fd6bc0add59e62ac25578270cff1b9f619', // WETH
+    tokenOut: '0xc708d6f2153933daa50b2d0758955be0a93a8fec', // USDC
+    fee: 3000
+  }, 137);
+
+  expect(result.success).toBe(true);
+  expect(result.data.amount0).toBe(-parseEther('0.1'));
+  expect(result.data.amount1).toBeGreaterThan(0n);
+});
+```
+
+## Error Handling
+
+### Common Error Scenarios
+
+```typescript
+async function robustSimulateSwap(
+  params: SimulateSwapParams,
+  chainId: number,
+  retries = 3
+): Promise<SwapSimulationResponse> {
+  for (let i = 0; i < retries; i++) {
+    try {
+      const result = await simulateSwap(publicClient, params, chainId);
+      
+      if (!result.success) {
+        if (result.error?.includes('insufficient liquidity')) {
+          throw new Error('Pool has insufficient liquidity for this swap size');
+        }
+        
+        if (result.error?.includes('price limit')) {
+          throw new Error('Price would exceed slippage limit');
+        }
+        
+        if (result.error?.includes('quoter')) {
+          throw new Error('Quoter contract not available on this network');
+        }
+        
+        throw new Error(`Simulation failed: ${result.error}`);
+      }
+
+      // Validate results
+      if (result.data.amount0 === 0n && result.data.amount1 === 0n) {
+        throw new Error('Invalid simulation result - no amounts returned');
+      }
+
+      return result.data;
+    } catch (error) {
+      if (i === retries - 1) throw error;
+      
+      // Wait before retry
+      await new Promise(resolve => setTimeout(resolve, 1000 * (i + 1)));
+    }
+  }
+  
+  throw new Error('Max retries reached');
+}
+```
+
+### Parameter Validation
+
+```typescript
+function validateSimulateSwapParams(params: SimulateSwapParams): void {
+  if (!params.pool || params.pool === '0x0000000000000000000000000000000000000000') {
+    throw new Error('Invalid pool address');
+  }
+  
+  if (params.amountSpecified <= 0n) {
+    throw new Error('Amount specified must be greater than 0');
+  }
+  
+  if (params.sqrtPriceLimitX96 <= 0n) {
+    throw new Error('Sqrt price limit must be greater than 0');
+  }
+
+  if (params.fee <= 0) {
+    throw new Error('Pool fee must be greater than 0');
+  }
+
+  if (params.tokenIn === params.tokenOut) {
+    throw new Error('Token addresses must be different');
+  }
+}
+```
+
+## Best Practices
+
+### 1. Choose Appropriate Simulation Parameters
+
+```typescript
+// Recommended simulation settings
+const SIMULATION_CONFIGS = {
+  PREVIEW: {
+    recipient: '0x0000000000000000000000000000000000000000', // Null address for simulation
+    slippageTolerance: 50 // 0.5% for preview
+  },
+  PRODUCTION: {
+    recipient: userAddress, // Real recipient
+    slippageTolerance: 500  // 5% for actual swaps
+  }
+};
+
+function getSimulationConfig(mode: 'preview' | 'production') {
+  return SIMULATION_CONFIGS[mode.toUpperCase()];
+}
+```
+
+### 2. Cache Simulation Results
+
+```typescript
+interface SimulationCache {
+  timestamp: number;
+  result: SwapSimulationResponse;
+}
+
+const simulationCache = new Map<string, SimulationCache>();
+const CACHE_DURATION = 15000; // 15 seconds
+
+async function cachedSimulateSwap(
+  params: SimulateSwapParams,
+  chainId: number
+): Promise<SwapSimulationResponse> {
+  const key = JSON.stringify({ ...params, chainId });
+  const cached = simulationCache.get(key);
+  
+  if (cached && Date.now() - cached.timestamp < CACHE_DURATION) {
+    return cached.result;
+  }
+  
+  const result = await simulateSwap(publicClient, params, chainId);
+  if (!result.success) {
+    throw new Error(result.error);
+  }
+  
+  simulationCache.set(key, {
+    timestamp: Date.now(),
+    result: result.data
+  });
+  
+  return result.data;
+}
+```
+
+### 3. Monitor Price Impact
+
+```typescript
+function analyzeSwapImpact(
+  simulation: SwapWithSlippageResponse,
+  thresholds = { warning: 2.0, danger: 5.0 }
+): { level: 'safe' | 'warning' | 'danger'; message: string } {
+  const slippage = parseFloat(simulation.priceSlippagePercent);
+  
+  if (slippage > thresholds.danger) {
+    return {
+      level: 'danger',
+      message: `High price impact: ${slippage.toFixed(2)}%. Consider reducing swap size.`
+    };
+  }
+  
+  if (slippage > thresholds.warning) {
+    return {
+      level: 'warning',
+      message: `Moderate price impact: ${slippage.toFixed(2)}%. Monitor closely.`
+    };
+  }
+  
+  return {
+    level: 'safe',
+    message: `Low price impact: ${slippage.toFixed(2)}%.`
+  };
+}
+```
+
+## Utility Functions
+
+### determineSwapDirection
+
+```typescript
+export function determineSwapDirection(isToken0: boolean): boolean {
+  // If depositing token0, we need to swap some token0 to token1
+  // If depositing token1, we need to swap some token1 to token0
+  return isToken0;
+}
+```
+
+### validateSwapParams
+
+```typescript
+export function validateSwapParams(params: SimulateSwapParams): void {
+  if (!params.pool || params.pool === '0x0000000000000000000000000000000000000000') {
+    throw new Error('Invalid pool address');
+  }
+  
+  if (!params.recipient || params.recipient === '0x0000000000000000000000000000000000000000') {
+    throw new Error('Invalid recipient address');
+  }
+  
+  if (params.amountSpecified <= 0n) {
+    throw new Error('Amount specified must be greater than 0');
+  }
+  
+  if (params.sqrtPriceLimitX96 <= 0n) {
+    throw new Error('Sqrt price limit must be greater than 0');
+  }
+
+  if (!params.tokenIn || params.tokenIn === '0x0000000000000000000000000000000000000000') {
+    throw new Error('Invalid tokenIn address');
+  }
+
+  if (!params.tokenOut || params.tokenOut === '0x0000000000000000000000000000000000000000') {
+    throw new Error('Invalid tokenOut address');
+  }
+
+  if (params.fee <= 0) {
+    throw new Error('Pool fee must be greater than 0');
+  }
+}
+```
+
+## Related Functions
+
+- **[calculateSwapAmount](./calculateSwapAmount.md)** - Provides the amountSpecified input
+- **[calculateLimitPrice](./calculateLimitPrice.md)** - Provides the sqrtPriceLimitX96 input
+- **[estimateLpTokens](./estimateLpTokens.md)** - Uses the simulation results for LP estimation
+
+## Quoter Contract Interface
+
+The function interacts with this Quoter contract method:
+
+```solidity
+struct QuoteExactInputSingleParams {
+    address tokenIn;
+    address tokenOut;
+    uint256 amountIn;
+    uint24 fee;
+    uint160 sqrtPriceLimitX96;
+}
+
+function quoteExactInputSingle(QuoteExactInputSingleParams calldata params)
+    external
+    returns (
+        uint256 amountOut,
+        uint160 sqrtPriceX96After,
+        uint32 initializedTicksCrossed,
+        uint256 gasEstimate
+    );
+```
+
+This ensures simulation results match exactly what would happen in an actual swap transaction.