@steerprotocol/sdk 1.27.0 → 1.28.0

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

@@ -0,0 +1,585 @@
+# estimateLpTokens
+
+Estimates the amount of LP tokens that will be received and the actual token amounts that will be deposited after a single-asset deposit operation.
+
+## Overview
+
+After calculating the swap amount and simulating the swap, this function determines how many LP tokens the user will receive and what the final token allocation will be. It uses the vault's share calculation logic to provide accurate estimates that match the actual deposit transaction.
+
+## Function Signature
+
+```typescript
+async function estimateLpTokens(
+  publicClient: PublicClient,
+  params: EstimateLpTokensParams
+): Promise<SteerResponse<LpTokenEstimationResponse>>
+```
+
+## Parameters
+
+### EstimateLpTokensParams
+
+```typescript
+interface EstimateLpTokensParams {
+  /** Address of the vault */
+  vault: Address;
+  /** Original deposit amount */
+  originalAssets: bigint;
+  /** Amount that was swapped internally */
+  swapAmount: bigint;
+  /** Tokens received from the swap (amount0 and amount1) */
+  swapResult: SwapSimulationResponse;
+  /** true if original deposit was token0, false if token1 */
+  isToken0: boolean;
+}
+```
+
+**Parameter Details:**
+
+- **`vault`**: Target vault address where the liquidity will be deposited
+- **`originalAssets`**: The original amount deposited by the user (before any swaps)
+- **`swapAmount`**: The amount that was internally swapped (from `calculateSwapAmount`)
+- **`swapResult`**: The result of the swap simulation containing amount0 and amount1 deltas
+- **`isToken0`**: Boolean indicating which token the user originally deposited
+
+## Return Value
+
+### LpTokenEstimationResponse
+
+```typescript
+interface LpTokenEstimationResponse {
+  /** Estimated amount of LP tokens to be received */
+  lpTokens: bigint;
+  /** Final amount of token0 that will be deposited */
+  finalAmount0: bigint;
+  /** Final amount of token1 that will be deposited */
+  finalAmount1: bigint;
+}
+```
+
+**Response Details:**
+
+- **`lpTokens`**: The estimated LP tokens the user will receive
+- **`finalAmount0`**: Actual amount of token0 that will be deposited into the vault
+- **`finalAmount1`**: Actual amount of token1 that will be deposited into the vault
+
+## Examples
+
+### Basic Usage
+
+```typescript
+import { estimateLpTokens } from '@steerprotocol/sdk';
+
+// After performing swap calculation and simulation
+const swapResult = {
+  amount0: -parseEther('50'),  // 50 token0 out (negative)
+  amount1: parseEther('150')   // 150 token1 in (positive)
+};
+
+const result = await estimateLpTokens(publicClient, {
+  vault: '0xd6bac58d87772fa3a7400f15fd121b7edc30ce3c',
+  originalAssets: parseEther('100'),  // User deposited 100 token0
+  swapAmount: parseEther('50'),       // 50 token0 was swapped
+  swapResult: swapResult,
+  isToken0: true                      // Original deposit was token0
+});
+
+if (result.success) {
+  console.log('Estimated LP tokens:', result.data.lpTokens);
+  console.log('Final token0 amount:', result.data.finalAmount0);
+  console.log('Final token1 amount:', result.data.finalAmount1);
+  
+  // Calculate effective exchange rate
+  const totalValue = result.data.finalAmount0 + result.data.finalAmount1;
+  const lpTokensPerValue = result.data.lpTokens / totalValue;
+  console.log('LP tokens per value unit:', lpTokensPerValue);
+} else {
+  console.error('Failed to estimate LP tokens:', result.error);
+}
+```
+
+### Token1 Deposit Example
+
+```typescript
+// User deposits token1 instead of token0
+const swapResult = {
+  amount0: parseEther('75'),    // 75 token0 in (positive)
+  amount1: -parseEther('25')    // 25 token1 out (negative)
+};
+
+const result = await estimateLpTokens(publicClient, {
+  vault: vaultAddress,
+  originalAssets: parseEther('100'),  // User deposited 100 token1
+  swapAmount: parseEther('25'),       // 25 token1 was swapped
+  swapResult: swapResult,
+  isToken0: false                     // Original deposit was token1
+});
+```
+
+### Complete Single-Asset Deposit Flow
+
+```typescript
+async function completeSingleAssetEstimation(
+  publicClient: PublicClient,
+  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: Simulate the swap
+  const swapSimResult = await simulateSwap(publicClient, {
+    pool: poolAddress,
+    recipient: depositParams.receiver,
+    zeroForOne: depositParams.isToken0,
+    amountSpecified: swapAmountResult.data.swapAmount,
+    sqrtPriceLimitX96: /* calculated limit price */,
+    ammType: depositParams.ammType,
+    tokenIn: /* token address */,
+    tokenOut: /* token address */,
+    fee: /* pool fee */
+  }, chainId);
+
+  if (!swapSimResult.success) {
+    throw new Error('Failed to simulate swap');
+  }
+
+  // Step 3: Estimate LP tokens
+  const lpEstimate = await estimateLpTokens(publicClient, {
+    vault: depositParams.vault,
+    originalAssets: depositParams.assets,
+    swapAmount: swapAmountResult.data.swapAmount,
+    swapResult: swapSimResult.data,
+    isToken0: depositParams.isToken0
+  });
+
+  return lpEstimate;
+}
+```
+
+## Algorithm Details
+
+The function implements the vault's share calculation logic:
+
+### 1. Calculate Final Token Amounts
+
+```typescript
+// For token0 deposits
+const finalAmount0 = originalAssets - swapAmount + Math.abs(swapResult.amount0);
+const finalAmount1 = Math.abs(swapResult.amount1);
+
+// For token1 deposits  
+const finalAmount0 = Math.abs(swapResult.amount0);
+const finalAmount1 = originalAssets - swapAmount + Math.abs(swapResult.amount1);
+```
+
+### 2. Get Vault State
+
+```typescript
+// Retrieve current vault reserves and total supply
+const [totalSupply, tokenBalances] = await Promise.all([
+  publicClient.readContract({
+    address: vault,
+    abi: vaultAbi,
+    functionName: 'totalSupply'
+  }),
+  publicClient.readContract({
+    address: vault,
+    abi: vaultAbi,
+    functionName: 'getTotalAmounts'
+  })
+]);
+```
+
+### 3. Calculate Shares Using Helper Contract
+
+```typescript
+const [shares, amount0Used, amount1Used] = await publicClient.readContract({
+  address: helperContract,
+  abi: helperAbi,
+  functionName: 'getShares',
+  args: [
+    totalSupply,
+    tokenBalances[0],  // total0
+    tokenBalances[1],  // total1
+    finalAmount0,      // amount0Desired
+    finalAmount1,      // amount1Desired
+    0n,                // amount0Min
+    0n,                // amount1Min
+    0n                 // minShares
+  ]
+});
+```
+
+## Share Calculation Logic
+
+The `getShares` function implements different logic based on vault state:
+
+### Empty Vault (First Deposit)
+
+```typescript
+if (totalSupply === 0n) {
+  shares = Math.max(amount0Desired, amount1Desired);
+  amount0Used = amount0Desired;
+  amount1Used = amount1Desired;
+}
+```
+
+### Single Token Vault
+
+```typescript
+// Vault only has token1
+if (total0 === 0n) {
+  shares = (amount1Desired * totalSupply) / total1;
+  amount1Used = Math.ceil((shares * total1) / totalSupply);
+  amount0Used = 0n;
+}
+
+// Vault only has token0
+if (total1 === 0n) {
+  shares = (amount0Desired * totalSupply) / total0;
+  amount0Used = Math.ceil((shares * total0) / totalSupply);
+  amount1Used = 0n;
+}
+```
+
+### Balanced Vault
+
+```typescript
+// Both tokens present - calculate cross product
+const cross = Math.min(
+  amount0Desired * total1,
+  amount1Desired * total0
+);
+
+// Round up amounts
+amount0Used = Math.ceil((cross - 1n) / total1) + 1n;
+amount1Used = Math.ceil((cross - 1n) / total0) + 1n;
+
+shares = (cross * totalSupply) / (total0 * total1);
+```
+
+## Testing
+
+### Unit Test Example
+
+```typescript
+describe('estimateLpTokens', () => {
+  it('should estimate LP tokens for balanced deposit', async () => {
+    const mockTotalSupply = parseEther('1000');
+    const mockTokenBalances = [parseEther('500'), parseEther('500')];
+    const mockHelperResponse = [
+      parseEther('100'),  // shares
+      parseEther('50'),   // amount0Used
+      parseEther('50')    // amount1Used
+    ];
+
+    const mockPublicClient = {
+      readContract: jest.fn()
+        .mockResolvedValueOnce(mockTotalSupply)
+        .mockResolvedValueOnce(mockTokenBalances)
+        .mockResolvedValueOnce(mockHelperResponse),
+      getChainId: jest.fn().mockResolvedValue(137)
+    };
+
+    const result = await estimateLpTokens(mockPublicClient, {
+      vault: mockVaultAddress,
+      originalAssets: parseEther('100'),
+      swapAmount: parseEther('50'),
+      swapResult: {
+        amount0: -parseEther('50'),
+        amount1: parseEther('50')
+      },
+      isToken0: true
+    });
+
+    expect(result.success).toBe(true);
+    expect(result.data.lpTokens).toBe(parseEther('100'));
+    expect(result.data.finalAmount0).toBe(parseEther('50'));
+    expect(result.data.finalAmount1).toBe(parseEther('50'));
+  });
+});
+```
+
+### Integration Test
+
+```typescript
+it('should work with real vault contracts', async () => {
+  const realClient = createPublicClient({
+    chain: polygon,
+    transport: http()
+  });
+
+  const result = await estimateLpTokens(realClient, {
+    vault: '0xd6bac58d87772fa3a7400f15fd121b7edc30ce3c', // Real vault
+    originalAssets: parseEther('1'),
+    swapAmount: parseEther('0.5'),
+    swapResult: {
+      amount0: -parseEther('0.5'),
+      amount1: parseEther('500') // Assuming USDC conversion
+    },
+    isToken0: true
+  });
+
+  expect(result.success).toBe(true);
+  expect(result.data.lpTokens).toBeGreaterThan(0n);
+});
+```
+
+## Error Handling
+
+### Common Error Scenarios
+
+```typescript
+async function safeEstimateLpTokens(params: EstimateLpTokensParams) {
+  try {
+    // Validate parameters
+    if (params.originalAssets <= 0n) {
+      throw new Error('Original assets must be greater than 0');
+    }
+
+    if (params.swapAmount > params.originalAssets) {
+      throw new Error('Swap amount cannot exceed original assets');
+    }
+
+    const result = await estimateLpTokens(publicClient, params);
+    
+    if (!result.success) {
+      if (result.error?.includes('vault')) {
+        throw new Error('Vault contract error. Check vault address and status.');
+      }
+      
+      if (result.error?.includes('helper')) {
+        throw new Error('Helper contract not found. Check deployment.');
+      }
+      
+      throw new Error(`LP estimation failed: ${result.error}`);
+    }
+
+    // Validate reasonable results
+    if (result.data.lpTokens === 0n) {
+      throw new Error('Zero LP tokens calculated. Check deposit amounts.');
+    }
+
+    return result.data;
+  } catch (error) {
+    console.error('Error estimating LP tokens:', error);
+    throw error;
+  }
+}
+```
+
+### Parameter Validation
+
+```typescript
+function validateEstimationParams(params: EstimateLpTokensParams): void {
+  if (!params.vault || params.vault === '0x0000000000000000000000000000000000000000') {
+    throw new Error('Invalid vault address');
+  }
+
+  if (params.originalAssets <= 0n) {
+    throw new Error('Original assets must be greater than 0');
+  }
+
+  if (params.swapAmount < 0n) {
+    throw new Error('Swap amount cannot be negative');
+  }
+
+  if (params.swapAmount > params.originalAssets) {
+    throw new Error('Swap amount cannot exceed original assets');
+  }
+
+  if (!params.swapResult || (!params.swapResult.amount0 && !params.swapResult.amount1)) {
+    throw new Error('Invalid swap result');
+  }
+}
+```
+
+## Best Practices
+
+### 1. Validate Results
+
+```typescript
+function validateLpEstimation(
+  estimation: LpTokenEstimationResponse,
+  originalDeposit: bigint
+): boolean {
+  // Check that final amounts are reasonable
+  const totalFinalValue = estimation.finalAmount0 + estimation.finalAmount1;
+  
+  // Final value should be close to original deposit (within swap slippage)
+  const valueRatio = (totalFinalValue * 100n) / originalDeposit;
+  if (valueRatio < 90n || valueRatio > 110n) {
+    console.warn(`Unusual value ratio: ${valueRatio}%`);
+    return false;
+  }
+
+  // LP tokens should be proportional to deposit
+  if (estimation.lpTokens === 0n) {
+    console.error('Zero LP tokens estimated');
+    return false;
+  }
+
+  return true;
+}
+```
+
+### 2. Handle Edge Cases
+
+```typescript
+async function robustEstimateLpTokens(
+  params: EstimateLpTokensParams
+): Promise<LpTokenEstimationResponse> {
+  // Handle very small deposits
+  if (params.originalAssets < 1000n) {
+    console.warn('Very small deposit detected. Results may be imprecise.');
+  }
+
+  // Handle edge case where no swap occurred
+  if (params.swapAmount === 0n) {
+    console.info('No swap required for this deposit.');
+  }
+
+  const result = await estimateLpTokens(publicClient, params);
+  
+  if (!result.success) {
+    throw new Error(result.error);
+  }
+
+  // Handle edge case where vault is nearly empty
+  if (result.data.lpTokens === result.data.finalAmount0 || 
+      result.data.lpTokens === result.data.finalAmount1) {
+    console.info('First deposit detected - LP tokens equal to max input amount.');
+  }
+
+  return result.data;
+}
+```
+
+### 3. Cache Vault State
+
+```typescript
+interface VaultStateCache {
+  timestamp: number;
+  totalSupply: bigint;
+  token0Balance: bigint;
+  token1Balance: bigint;
+}
+
+const vaultCache = new Map<Address, VaultStateCache>();
+const VAULT_CACHE_DURATION = 10000; // 10 seconds
+
+async function getVaultState(vault: Address): Promise<{
+  totalSupply: bigint;
+  token0Balance: bigint;
+  token1Balance: bigint;
+}> {
+  const cached = vaultCache.get(vault);
+  
+  if (cached && Date.now() - cached.timestamp < VAULT_CACHE_DURATION) {
+    return {
+      totalSupply: cached.totalSupply,
+      token0Balance: cached.token0Balance,
+      token1Balance: cached.token1Balance
+    };
+  }
+
+  // Fetch fresh data
+  const [totalSupply, tokenBalances] = await Promise.all([
+    publicClient.readContract({
+      address: vault,
+      abi: vaultAbi,
+      functionName: 'totalSupply'
+    }),
+    publicClient.readContract({
+      address: vault,
+      abi: vaultAbi,
+      functionName: 'getTotalAmounts'
+    })
+  ]);
+
+  const state = {
+    totalSupply: totalSupply as bigint,
+    token0Balance: tokenBalances[0] as bigint,
+    token1Balance: tokenBalances[1] as bigint
+  };
+
+  vaultCache.set(vault, {
+    ...state,
+    timestamp: Date.now()
+  });
+
+  return state;
+}
+```
+
+## Mathematical Formulas
+
+### Share Calculation Formula
+
+The general formula for calculating shares in a proportional vault:
+
+```typescript
+// For balanced vaults
+shares = min(
+  (amount0Desired * totalSupply) / vault.token0Balance,
+  (amount1Desired * totalSupply) / vault.token1Balance
+)
+
+// Actual amounts used
+amount0Used = (shares * vault.token0Balance) / totalSupply
+amount1Used = (shares * vault.token1Balance) / totalSupply
+```
+
+### Cross Product Method
+
+For precise calculations when both tokens are present:
+
+```typescript
+cross = min(
+  amount0Desired * vault.token1Balance,
+  amount1Desired * vault.token0Balance
+)
+
+shares = (cross * totalSupply) / (vault.token0Balance * vault.token1Balance)
+```
+
+## Related Functions
+
+- **[calculateSwapAmount](./calculateSwapAmount.md)** - Determines the swap amount needed
+- **[simulateSwap](./simulateSwap.md)** - Provides the swap result input for this function
+- **[getVaultReserves](./getVaultReserves.md)** - Utility function to get vault state
+
+## Helper Contract Interface
+
+The function uses this helper contract method:
+
+```solidity
+function getShares(
+    uint256 _totalSupply,
+    uint256 total0,
+    uint256 total1,
+    uint256 amount0Desired,
+    uint256 amount1Desired,
+    uint256 amount0Min,
+    uint256 amount1Min,
+    uint256 minShares
+) external pure returns (
+    uint256 shares,
+    uint256 amount0Used,
+    uint256 amount1Used
+);
+```
+
+This ensures the estimation matches exactly what the vault contract will calculate during the actual deposit.