@steerprotocol/sdk 1.31.0 → 2.0.0

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

@@ -1,612 +0,0 @@
-# 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.