@steerprotocol/sdk 1.27.0 → 1.28.0

package/src/base/vault/single-asset/estimateLpTokens.ts

@@ -0,0 +1,393 @@
+import type { Address, PublicClient } from 'viem';
+import { abis } from '../../../const/deployments/abis.js';
+import { getContractAddressByChainIdAndContractName } from '../../../const/network.js';
+import { SteerResponse } from '../../../types.js';
+import type { EstimateLpTokensParams, LpTokenEstimationResponse } from './types.js';
+
+// Use the vault ABI for reading vault state
+const VAULT_ABI = abis.QuickSwapUniv3MultiPositionLiquidityManager;
+
+/**
+ * Estimates the amount of LP tokens that will be received based on the final token amounts
+ * This calculation follows the Solidity getShares implementation from the vault contract
+ * 
+ * @param publicClient - Viem public client for blockchain reads
+ * @param params - Parameters for LP token estimation
+ * @returns Promise resolving to the estimated LP tokens and final amounts
+ * 
+ * @example
+ * ```typescript
+ * const result = await estimateLpTokens(publicClient, {
+ *   vault: '0x...',
+ *   originalAssets: parseEther('100'),
+ *   swapAmount: parseEther('50'),
+ *   swapResult: { amount0: -parseEther('50'), amount1: parseEther('150') },
+ *   isToken0: true
+ * });
+ * 
+ * if (result.success) {
+ *   console.log('Estimated LP tokens:', result.data.lpTokens);
+ *   console.log('Final amount0:', result.data.finalAmount0);
+ *   console.log('Final amount1:', result.data.finalAmount1);
+ * }
+ * ```
+ */
+export async function estimateLpTokens(
+  publicClient: PublicClient,
+  params: EstimateLpTokensParams
+): Promise<SteerResponse<LpTokenEstimationResponse>> {
+  try {
+    // Calculate final amounts based on original deposit and swap results
+    const finalAmount0 = params.isToken0 
+      ? params.originalAssets - params.swapAmount + (params.swapResult.amount0 < 0n ? -params.swapResult.amount0 : params.swapResult.amount0)
+      : (params.swapResult.amount0 < 0n ? -params.swapResult.amount0 : params.swapResult.amount0);
+      
+    const finalAmount1 = params.isToken0
+      ? (params.swapResult.amount1 < 0n ? -params.swapResult.amount1 : params.swapResult.amount1)
+      : params.originalAssets - params.swapAmount + (params.swapResult.amount1 < 0n ? -params.swapResult.amount1 : params.swapResult.amount1);
+
+    // Get vault reserves and total supply
+    const [totalSupply, tokenBalances] = await Promise.all([
+      publicClient.readContract({
+        address: params.vault,
+        abi: [ {
+          "inputs": [],
+          "name": "totalSupply",
+          "outputs": [
+            {
+              "internalType": "uint256",
+              "name": "",
+              "type": "uint256"
+            }
+          ],
+          "stateMutability": "view",
+          "type": "function"
+        },],
+        functionName: 'totalSupply'
+      }) as Promise<bigint>,
+      
+      // Get token0 address first, then balance
+      publicClient.readContract({
+        address: params.vault,
+        abi: [ {
+          "inputs": [],
+          "name": "getTotalAmounts",
+          "outputs": [
+            {
+              "internalType": "uint256",
+              "name": "total0",
+              "type": "uint256"
+            },
+            {
+              "internalType": "uint256",
+              "name": "total1",
+              "type": "uint256"
+            }
+          ],
+          "stateMutability": "view",
+          "type": "function"
+        },],
+        functionName: 'getTotalAmounts'
+      })
+    ])
+
+    const chainId = await  publicClient.getChainId();
+    const helper = getContractAddressByChainIdAndContractName(
+      chainId,
+      'Helper'
+    )
+
+    const [shares, amount0Used, amount1Used] = await publicClient.readContract({
+      address: helper as Address,
+      abi:  [{
+        "inputs": [
+          {
+            "internalType": "uint256",
+            "name": "_totalSupply",
+            "type": "uint256"
+          },
+          {
+            "internalType": "uint256",
+            "name": "total0",
+            "type": "uint256"
+          },
+          {
+            "internalType": "uint256",
+            "name": "total1",
+            "type": "uint256"
+          },
+          {
+            "internalType": "uint256",
+            "name": "amount0Desired",
+            "type": "uint256"
+          },
+          {
+            "internalType": "uint256",
+            "name": "amount1Desired",
+            "type": "uint256"
+          },
+          {
+            "internalType": "uint256",
+            "name": "amount0Min",
+            "type": "uint256"
+          },
+          {
+            "internalType": "uint256",
+            "name": "amount1Min",
+            "type": "uint256"
+          },
+          {
+            "internalType": "uint256",
+            "name": "minShares",
+            "type": "uint256"
+          }
+        ],
+        "name": "getShares",
+        "outputs": [
+          {
+            "internalType": "uint256",
+            "name": "shares",
+            "type": "uint256"
+          },
+          {
+            "internalType": "uint256",
+            "name": "amount0Used",
+            "type": "uint256"
+          },
+          {
+            "internalType": "uint256",
+            "name": "amount1Used",
+            "type": "uint256"
+          }
+        ],
+        "stateMutability": "pure",
+        "type": "function"
+      }],
+      functionName: 'getShares',
+      args: [
+        totalSupply,
+        tokenBalances[0],
+        tokenBalances[1],
+        finalAmount0,
+        finalAmount1,
+        0n, // amount0Min = 0 as requested
+        0n, // amount1Min = 0 as requested
+        0n  // minShares = 0
+      ]
+    })
+
+
+    return {
+      data: {
+        lpTokens: shares,
+        finalAmount0: amount0Used,
+        finalAmount1: amount1Used
+      },
+      status: 200,
+      success: true
+    };
+  } catch (error) {
+    return {
+      data: null,
+      status: 500,
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to estimate LP tokens'
+    };
+  }
+}
+
+/**
+ * Calculates shares (LP tokens) based on deposit amounts and vault reserves
+ * This is a TypeScript implementation of the Solidity getShares function
+ * 
+ * @param totalSupply - Current total supply of LP tokens
+ * @param total0 - Current balance of token0 in vault
+ * @param total1 - Current balance of token1 in vault
+ * @param amount0Desired - Desired amount of token0 to deposit
+ * @param amount1Desired - Desired amount of token1 to deposit
+ * @param amount0Min - Minimum amount of token0 (set to 0n)
+ * @param amount1Min - Minimum amount of token1 (set to 0n)
+ * @param minShares - Minimum shares required (set to 0n)
+ * @returns Object with shares, amount0Used, and amount1Used
+ */
+export function getShares(
+  totalSupply: bigint,
+  total0: bigint,
+  total1: bigint,
+  amount0Desired: bigint,
+  amount1Desired: bigint,
+  amount0Min: bigint,
+  amount1Min: bigint,
+  minShares: bigint
+): { shares: bigint; amount0Used: bigint; amount1Used: bigint } {
+  // If total supply > 0, vault can't be empty.
+  if (!(totalSupply === 0n || total0 > 0n || total1 > 0n)) {
+    throw new Error('Invalid vault state');
+  }
+
+  let shares: bigint;
+  let amount0Used: bigint = 0n;
+  let amount1Used: bigint = 0n;
+
+  if (totalSupply === 0n) {
+    // For first deposit, just use the amounts desired
+    amount0Used = amount0Desired;
+    amount1Used = amount1Desired;
+    shares = amount0Used > amount1Used ? amount0Used : amount1Used;
+    
+    if (shares < minShares) {
+      throw new Error('Insufficient shares for minimum requirement');
+    }
+  } else if (total0 === 0n) {
+    // Vault only has token1
+    shares = mulDiv(amount1Desired, totalSupply, total1);
+    amount1Used = mulDivRoundingUp(shares, total1, totalSupply);
+    amount0Used = 0n;
+  } else if (total1 === 0n) {
+    // Vault only has token0
+    shares = mulDiv(amount0Desired, totalSupply, total0);
+    amount0Used = mulDivRoundingUp(shares, total0, totalSupply);
+    amount1Used = 0n;
+  } else {
+    // Both tokens present - calculate cross product
+    const cross = min(amount0Desired * total1, amount1Desired * total0);
+
+    if (cross === 0n) {
+      throw new Error('Invalid deposit ratio - cross product is zero');
+    }
+
+    // Round up amounts
+    amount0Used = ((cross - 1n) / total1) + 1n;
+    amount1Used = ((cross - 1n) / total0) + 1n;
+
+    shares = mulDiv(cross, totalSupply, total0) / total1;
+  }
+
+  // Validate requirements
+  if (shares === 0n) {
+    throw new Error('Zero shares calculated');
+  }
+  if (amount0Used < amount0Min) {
+    throw new Error('Amount0 used less than minimum');
+  }
+  if (amount1Used < amount1Min) {
+    throw new Error('Amount1 used less than minimum');
+  }
+
+  return { shares, amount0Used, amount1Used };
+}
+
+/**
+ * Multiplies two BigInt values and divides by a third (a * b / c)
+ * Equivalent to Solidity's FullMath.mulDiv
+ */
+function mulDiv(a: bigint, b: bigint, c: bigint): bigint {
+  if (c === 0n) {
+    throw new Error('Division by zero');
+  }
+  return (a * b) / c;
+}
+
+/**
+ * Multiplies two BigInt values, divides by a third, and rounds up
+ * Equivalent to Solidity's FullMath.mulDivRoundingUp
+ */
+function mulDivRoundingUp(a: bigint, b: bigint, c: bigint): bigint {
+  if (c === 0n) {
+    throw new Error('Division by zero');
+  }
+  const result = (a * b) / c;
+  const remainder = (a * b) % c;
+  return remainder > 0n ? result + 1n : result;
+}
+
+/**
+ * Returns the minimum of two BigInt values
+ */
+function min(a: bigint, b: bigint): bigint {
+  return a < b ? a : b;
+}
+
+/**
+ * Gets the current vault reserves for both tokens
+ * 
+ * @param publicClient - Viem public client for blockchain reads
+ * @param vaultAddress - Address of the vault
+ * @returns Promise resolving to [token0Balance, token1Balance, totalSupply]
+ */
+export async function getVaultReserves(
+  publicClient: PublicClient,
+  vaultAddress: `0x${string}`
+): Promise<SteerResponse<{ token0Balance: bigint; token1Balance: bigint; totalSupply: bigint }>> {
+  try {
+    const [totalSupply, token0Address, token1Address] = await Promise.all([
+      publicClient.readContract({
+        address: vaultAddress,
+        abi: VAULT_ABI,
+        functionName: 'totalSupply'
+      }) as Promise<bigint>,
+      
+      publicClient.readContract({
+        address: vaultAddress,
+        abi: VAULT_ABI,
+        functionName: 'token0'
+      }) as Promise<`0x${string}`>,
+      
+      publicClient.readContract({
+        address: vaultAddress,
+        abi: VAULT_ABI,
+        functionName: 'token1'
+      }) as Promise<`0x${string}`>
+    ]);
+
+    const [token0Balance, token1Balance] = await Promise.all([
+      publicClient.readContract({
+        address: token0Address,
+        abi: [
+          {
+            type: 'function',
+            name: 'balanceOf',
+            inputs: [{ name: 'account', type: 'address', internalType: 'address' }],
+            outputs: [{ name: '', type: 'uint256', internalType: 'uint256' }],
+            stateMutability: 'view'
+          }
+        ],
+        functionName: 'balanceOf',
+        args: [vaultAddress]
+      }) as Promise<bigint>,
+      
+      publicClient.readContract({
+        address: token1Address,
+        abi: [
+          {
+            type: 'function',
+            name: 'balanceOf',
+            inputs: [{ name: 'account', type: 'address', internalType: 'address' }],
+            outputs: [{ name: '', type: 'uint256', internalType: 'uint256' }],
+            stateMutability: 'view'
+          }
+        ],
+        functionName: 'balanceOf',
+        args: [vaultAddress]
+      }) as Promise<bigint>
+    ]);
+
+    return {
+      data: {
+        token0Balance,
+        token1Balance,
+        totalSupply
+      },
+      status: 200,
+      success: true
+    };
+  } catch (error) {
+    return {
+      data: null,
+      status: 500,
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to get vault reserves'
+    };
+  }
+} 
+

package/src/base/vault/single-asset/index.ts

@@ -0,0 +1,85 @@
+// Export all types
+export * from './types.js';
+
+// Export individual functions for separate testing and usage
+export { calculateSwapAmount } from './calculateSwapAmount.js';
+export { calculateLimitPrice, getPoolSlot0 } from './calculateLimitPrice.js';
+export { simulateSwap, determineSwapDirection, validateSwapParams } from './simulateSwap.js';
+export { estimateLpTokens, getVaultReserves } from './estimateLpTokens.js';
+
+// Export the main client
+export { SingleAssetDepositClient } from './singleAssetDeposit.js';
+
+/**
+ * @fileoverview Single-Asset Deposit Module
+ * 
+ * This module provides comprehensive functionality for single-asset deposits into liquidity vaults.
+ * The process allows users to deposit only one token (token0 or token1), while the contract 
+ * internally performs a swap to balance the token pair before depositing into the vault.
+ * 
+ * ## Architecture
+ * 
+ * The single-asset deposit process is broken down into separate, testable functions:
+ * 
+ * 1. **calculateSwapAmount** - Determines how much of the input token needs to be swapped
+ * 2. **calculateLimitPrice** - Calculates slippage protection limits for the internal swap
+ * 3. **simulateSwap** - Simulates the swap to preview expected output amounts
+ * 4. **estimateLpTokens** - Estimates the final LP tokens that will be received
+ * 5. **SingleAssetDepositClient** - Main orchestrator that combines all steps
+ * 
+ * ## Supported AMM Types
+ * 
+ * Currently supports:
+ * - UniswapV3 (fully implemented)
+ * - Algebra variants (planned for future implementation)
+ * 
+ * ## Example Usage
+ * 
+ * ```typescript
+ * import { SingleAssetDepositClient, AMMType } from '@steerprotocol/sdk';
+ * import { parseEther } from 'viem';
+ * 
+ * // Initialize the client
+ * const client = new SingleAssetDepositClient(publicClient, walletClient);
+ * 
+ * // Preview the deposit
+ * const preview = await client.previewDeposit({
+ *   assets: parseEther('100'),
+ *   receiver: userAddress,
+ *   vault: vaultAddress,
+ *   isToken0: true,
+ *   depositSlippagePercent: 5n,
+ *   swapSlippageBP: 500,
+ *   ammType: AMMType.UniswapV3,
+ *   singleAssetDepositContract: contractAddress
+ * }, poolAddress);
+ * 
+ * if (preview.success) {
+ *   console.log('Expected LP tokens:', preview.data.lpEstimation.lpTokens);
+ *   
+ *   // Execute the deposit
+ *   const result = await client.deposit(params);
+ *   if (result.success) {
+ *     console.log('Transaction hash:', result.data);
+ *   }
+ * }
+ * ```
+ * 
+ * ## Testing Individual Functions
+ * 
+ * Each function can be tested separately:
+ * 
+ * ```typescript
+ * import { calculateSwapAmount, AMMType } from '@steerprotocol/sdk';
+ * 
+ * // Test swap amount calculation
+ * const result = await calculateSwapAmount(publicClient, {
+ *   depositAmount: parseEther('100'),
+ *   isToken0: true,
+ *   vault: vaultAddress,
+ *   pool: poolAddress,
+ *   ammType: AMMType.UniswapV3,
+ *   singleAssetDepositContract: contractAddress
+ * });
+ * ```
+ */