@steerprotocol/sdk 1.27.0 → 1.28.0

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

@@ -0,0 +1,478 @@
+# Single-Asset Deposit API Reference
+
+Quick reference guide for all single-asset deposit functionality in the Steer SDK.
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [VaultClient Methods](#vaultclient-methods)
+- [Core Functions](#core-functions)
+- [Types Reference](#types-reference)
+- [Error Handling](#error-handling)
+- [Examples](#examples)
+
+## Quick Start
+
+```typescript
+import { SteerClient, AMMType } from '@steerprotocol/sdk';
+import { createPublicClient, createWalletClient, parseEther } from 'viem';
+
+// Initialize SteerClient
+const steerClient = new SteerClient({
+  environment: 'production',
+  client: publicClient,
+  walletClient: walletClient
+});
+
+// Preview and execute single-asset deposit
+const preview = await steerClient.vaults.previewSingleAssetDeposit(params, poolAddress);
+const result = await steerClient.vaults.singleAssetDeposit(params);
+```
+
+## VaultClient Methods
+
+### `previewSingleAssetDeposit(params, poolAddress)`
+
+Previews a complete single-asset deposit without executing it.
+
+**Returns:** `Promise<SteerResponse<SingleAssetDepositPreview>>`
+
+```typescript
+const preview = await steerClient.vaults.previewSingleAssetDeposit({
+  assets: parseEther('100'),
+  receiver: userAddress,
+  vault: vaultAddress,
+  isToken0: true,
+  depositSlippagePercent: 5n,
+  swapSlippageBP: 500,
+  ammType: AMMType.UniswapV3,
+}, poolAddress);
+```
+
+### `singleAssetDeposit(params)`
+
+Executes a single-asset deposit transaction.
+
+**Returns:** `Promise<SteerResponse<Hash>>`
+
+```typescript
+const result = await steerClient.vaults.singleAssetDeposit({
+  assets: parseEther('100'),
+  receiver: userAddress,
+  vault: vaultAddress,
+  isToken0: true,
+  depositSlippagePercent: 5n,
+  swapSlippageBP: 500,
+  ammType: AMMType.UniswapV3,
+});
+```
+
+### `prepareSingleAssetDepositTx(params)`
+
+Prepares transaction data without executing.
+
+**Returns:** `Promise<SteerResponse<TransactionData>>`
+
+### `validateSingleAssetDepositParams(params)`
+
+Validates parameters and throws descriptive errors.
+
+**Throws:** `Error` if parameters are invalid
+
+## Core Functions
+
+### calculateSwapAmount
+
+**[📖 Full Documentation](./calculateSwapAmount.md)**
+
+Calculates the optimal amount of input token to swap.
+
+```typescript
+import { calculateSwapAmount } from '@steerprotocol/sdk';
+
+const result = await calculateSwapAmount(publicClient, {
+  depositAmount: parseEther('100'),
+  isToken0: true,
+  vault: vaultAddress,
+  pool: poolAddress,
+  ammType: AMMType.UniswapV3,
+  singleAssetDepositContract: contractAddress
+});
+// Returns: { swapAmount: bigint, sqrtPrice: bigint }
+```
+
+### calculateLimitPrice
+
+**[📖 Full Documentation](./calculateLimitPrice.md)**
+
+Calculates slippage-protected price limits for swaps.
+
+```typescript
+import { calculateLimitPrice } from '@steerprotocol/sdk';
+
+const result = await calculateLimitPrice(publicClient, {
+  pool: poolAddress,
+  slippageBP: 500,
+  zeroForOne: true,
+  ammType: AMMType.UniswapV3,
+  token0: token0Address,
+  token1: token1Address
+});
+// Returns: sqrtPriceLimitX96 (bigint)
+```
+
+### simulateSwap
+
+**[📖 Full Documentation](./simulateSwap.md)**
+
+Simulates swap operations for preview and analysis.
+
+```typescript
+import { simulateSwap, simulateSwapWithSlippage } from '@steerprotocol/sdk';
+
+// Basic simulation
+const result = await simulateSwap(publicClient, {
+  pool: poolAddress,
+  recipient: userAddress,
+  zeroForOne: true,
+  amountSpecified: parseEther('50'),
+  sqrtPriceLimitX96: priceLimit,
+  ammType: AMMType.UniswapV3,
+  tokenIn: token0Address,
+  tokenOut: token1Address,
+  fee: 3000
+}, chainId);
+// Returns: { amount0: bigint, amount1: bigint, sqrtPriceX96After: bigint }
+
+// Enhanced simulation with slippage analysis
+const enhanced = await simulateSwapWithSlippage(publicClient, params, chainId);
+// Returns: Additional price impact analysis
+```
+
+### estimateLpTokens
+
+**[📖 Full Documentation](./estimateLpTokens.md)**
+
+Estimates LP tokens and final deposit amounts.
+
+```typescript
+import { estimateLpTokens } from '@steerprotocol/sdk';
+
+const result = await estimateLpTokens(publicClient, {
+  vault: vaultAddress,
+  originalAssets: parseEther('100'),
+  swapAmount: parseEther('50'),
+  swapResult: { amount0: -parseEther('50'), amount1: parseEther('150') },
+  isToken0: true
+});
+// Returns: { lpTokens: bigint, finalAmount0: bigint, finalAmount1: bigint }
+```
+
+## Types Reference
+
+### SingleAssetDepositParams
+
+```typescript
+interface SingleAssetDepositParams {
+  assets: bigint;                          // Amount to deposit
+  receiver: Address;                       // LP token recipient
+  vault: Address;                          // Target vault
+  isToken0: boolean;                       // Token type being deposited
+  depositSlippagePercent: bigint;          // Max slippage % for deposit
+  swapSlippageBP: number;                  // Max slippage BP for internal swap
+  ammType: AMMType;                        // AMM protocol type
+  singleAssetDepositContract?: Address;    // Contract address (optional)
+}
+```
+
+### AMMType
+
+```typescript
+enum AMMType {
+  UniswapV3 = 0,              // ✅ Fully supported
+  Algebra = 1,                // 🚧 Planned
+  AlgebraDirectional = 2,     // 🚧 Planned
+  AlgebraVE33 = 3,           // 🚧 Planned
+  AlgebraIntegral = 4        // 🚧 Planned
+}
+```
+
+### SingleAssetDepositPreview
+
+```typescript
+interface SingleAssetDepositPreview {
+  swapAmount: bigint;                      // Amount to be swapped
+  currentSqrtPrice: bigint;                // Current pool price
+  sqrtPriceLimitX96: bigint;               // Price limit for swap
+  swapSimulation: SwapWithSlippageResponse; // Detailed swap simulation
+  lpEstimation: LpTokenEstimationResponse; // LP token estimation
+  zeroForOne: boolean;                     // Swap direction
+}
+```
+
+## Error Handling
+
+### Common Response Pattern
+
+```typescript
+interface SteerResponse<T> {
+  data: T | null;
+  status: number;
+  success: boolean;
+  error?: string;
+}
+
+// Usage pattern
+const result = await someFunction();
+if (!result.success) {
+  console.error('Error:', result.error);
+  console.error('Status:', result.status);
+  return;
+}
+
+// Use result.data safely
+console.log('Success:', result.data);
+```
+
+### Error Categories
+
+| Status | Category | Description |
+|--------|----------|-------------|
+| 200 | Success | Operation completed successfully |
+| 400 | Client Error | Invalid parameters or user input |
+| 500 | Server Error | Contract error, network issue, or internal failure |
+
+### Common Error Messages
+
+```typescript
+// Parameter validation errors
+"Assets amount must be greater than 0"
+"Invalid vault address"
+"Slippage BP must be between 1 and 10000"
+
+// Contract interaction errors
+"Failed to calculate swap amount"
+"Pool has insufficient liquidity"
+"Price would exceed slippage limit"
+
+// Network/infrastructure errors
+"Contract not found. Check deployment address."
+"Unable to read token decimals. Check token addresses."
+```
+
+## Examples
+
+### Complete Flow Example
+
+```typescript
+async function performSingleAssetDeposit() {
+  try {
+    const params = {
+      assets: parseEther('100'),
+      receiver: userAddress,
+      vault: '0xd6bac58d87772fa3a7400f15fd121b7edc30ce3c',
+      isToken0: true,
+      depositSlippagePercent: 5n,
+      swapSlippageBP: 500,
+      ammType: AMMType.UniswapV3,
+    };
+    
+    const poolAddress = '0xd19a1c8278d0420bfb2c825d99dc31ff86224607';
+
+    // Step 1: Preview the deposit
+    console.log('Previewing deposit...');
+    const preview = await steerClient.vaults.previewSingleAssetDeposit(params, poolAddress);
+    
+    if (!preview.success) {
+      throw new Error(`Preview failed: ${preview.error}`);
+    }
+
+    // Step 2: Analyze the preview
+    const { swapAmount, lpEstimation, swapSimulation } = preview.data;
+    const priceImpact = parseFloat(swapSimulation.priceSlippagePercent);
+    
+    console.log(`Will swap ${formatEther(swapAmount)} tokens`);
+    console.log(`Expected LP tokens: ${formatEther(lpEstimation.lpTokens)}`);
+    console.log(`Price impact: ${priceImpact.toFixed(2)}%`);
+
+    // Step 3: Check if conditions are acceptable
+    if (priceImpact > 5.0) {
+      console.warn('High price impact detected. Consider reducing amount.');
+      return;
+    }
+
+    if (lpEstimation.lpTokens < parseEther('90')) {
+      console.warn('LP tokens below expected minimum.');
+      return;
+    }
+
+    // Step 4: Execute the deposit
+    console.log('Executing deposit...');
+    const result = await steerClient.vaults.singleAssetDeposit(params);
+    
+    if (!result.success) {
+      throw new Error(`Deposit failed: ${result.error}`);
+    }
+
+    console.log('Deposit successful!');
+    console.log('Transaction hash:', result.data);
+    
+    return result.data;
+  } catch (error) {
+    console.error('Single-asset deposit failed:', error);
+    throw error;
+  }
+}
+```
+
+### Individual Function Testing
+
+```typescript
+// Test each function independently
+async function testIndividualFunctions() {
+  const testParams = {
+    depositAmount: parseEther('10'),
+    isToken0: true,
+    vault: '0xd6bac58d87772fa3a7400f15fd121b7edc30ce3c',
+    pool: '0xd19a1c8278d0420bfb2c825d99dc31ff86224607',
+    ammType: AMMType.UniswapV3,
+    singleAssetDepositContract: '0x9903C4ED61A71d0d5C322097adfF752d6339F871'
+  };
+
+  // Test 1: Calculate swap amount
+  const swapResult = await calculateSwapAmount(publicClient, testParams);
+  console.log('Swap amount:', swapResult.success ? swapResult.data : swapResult.error);
+
+  if (!swapResult.success) return;
+
+  // Test 2: Calculate limit price
+  const limitResult = await calculateLimitPrice(publicClient, {
+    pool: testParams.pool,
+    slippageBP: 500,
+    zeroForOne: true,
+    ammType: testParams.ammType,
+    token0: '0x7ceb23fd6bc0add59e62ac25578270cff1b9f619',
+    token1: '0xc708d6f2153933daa50b2d0758955be0a93a8fec'
+  });
+  console.log('Limit price:', limitResult.success ? limitResult.data : limitResult.error);
+
+  if (!limitResult.success) return;
+
+  // Test 3: Simulate swap
+  const simResult = await simulateSwap(publicClient, {
+    pool: testParams.pool as Address,
+    recipient: '0x0000000000000000000000000000000000000000' as Address,
+    zeroForOne: true,
+    amountSpecified: swapResult.data.swapAmount,
+    sqrtPriceLimitX96: limitResult.data,
+    ammType: testParams.ammType,
+    tokenIn: '0x7ceb23fd6bc0add59e62ac25578270cff1b9f619' as Address,
+    tokenOut: '0xc708d6f2153933daa50b2d0758955be0a93a8fec' as Address,
+    fee: 3000
+  }, 137);
+  console.log('Swap simulation:', simResult.success ? simResult.data : simResult.error);
+
+  if (!simResult.success) return;
+
+  // Test 4: Estimate LP tokens
+  const lpResult = await estimateLpTokens(publicClient, {
+    vault: testParams.vault,
+    originalAssets: testParams.depositAmount,
+    swapAmount: swapResult.data.swapAmount,
+    swapResult: simResult.data,
+    isToken0: testParams.isToken0
+  });
+  console.log('LP estimation:', lpResult.success ? lpResult.data : lpResult.error);
+}
+```
+
+### Error Handling Pattern
+
+```typescript
+async function robustSingleAssetDeposit(params: SingleAssetDepositParams, poolAddress: Address) {
+  const maxRetries = 3;
+  let lastError: Error;
+
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      console.log(`Attempt ${attempt}/${maxRetries}`);
+
+      // Validate parameters first
+      steerClient.vaults.validateSingleAssetDepositParams(params);
+
+      // Preview with timeout
+      const previewPromise = steerClient.vaults.previewSingleAssetDeposit(params, poolAddress);
+      const timeoutPromise = new Promise((_, reject) => 
+        setTimeout(() => reject(new Error('Preview timeout')), 30000)
+      );
+
+      const preview = await Promise.race([previewPromise, timeoutPromise]) as any;
+
+      if (!preview.success) {
+        throw new Error(`Preview failed: ${preview.error}`);
+      }
+
+      // Check for reasonable results
+      if (preview.data.lpEstimation.lpTokens === 0n) {
+        throw new Error('Zero LP tokens estimated - check pool state');
+      }
+
+      // Execute deposit
+      const result = await steerClient.vaults.singleAssetDeposit(params);
+
+      if (!result.success) {
+        throw new Error(`Deposit execution failed: ${result.error}`);
+      }
+
+      return result.data; // Success!
+
+    } catch (error) {
+      lastError = error as Error;
+      console.error(`Attempt ${attempt} failed:`, error.message);
+
+      if (attempt < maxRetries) {
+        // Wait before retry with exponential backoff
+        const delay = Math.min(1000 * Math.pow(2, attempt - 1), 10000);
+        console.log(`Retrying in ${delay}ms...`);
+        await new Promise(resolve => setTimeout(resolve, delay));
+      }
+    }
+  }
+
+  throw new Error(`All ${maxRetries} attempts failed. Last error: ${lastError.message}`);
+}
+```
+
+## Chain Support
+
+| Network | Status | Contract Address |
+|---------|--------|------------------|
+| Polygon | ✅ Production | `0x9903C4ED61A71d0d5C322097adfF752d6339F871` |
+| Ethereum | 🚧 Planned | TBD |
+| Arbitrum | 🚧 Planned | TBD |
+| Base | 🚧 Planned | TBD |
+
+## Gas Optimization Tips
+
+1. **Batch Operations**: Use `prepareSingleAssetDepositTx` for batching multiple deposits
+2. **Preview First**: Always preview to avoid failed transactions
+3. **Optimal Slippage**: Use minimum acceptable slippage to reduce MEV impact
+4. **Pool Selection**: Choose pools with adequate liquidity for your deposit size
+
+## Security Considerations
+
+1. **Slippage Protection**: Built-in price limit enforcement prevents excessive slippage
+2. **Parameter Validation**: Client-side and contract-side validation
+3. **Simulation First**: Always simulate before execution to prevent unexpected outcomes
+4. **Reentrancy Protection**: Contract-level guards against reentrancy attacks
+
+## Support and Resources
+
+- **Main Documentation**: [README.md](../README.md)
+- **Function Details**: 
+  - [calculateSwapAmount](./calculateSwapAmount.md)
+  - [calculateLimitPrice](./calculateLimitPrice.md)
+  - [simulateSwap](./simulateSwap.md)
+  - [estimateLpTokens](./estimateLpTokens.md)
+- **GitHub Issues**: For bug reports and feature requests
+- **Discord**: For community support and discussions