@steerprotocol/sdk 1.27.0 → 1.28.0

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

@@ -0,0 +1,345 @@
+# calculateSwapAmount
+
+Calculates the optimal amount of input token that needs to be swapped to achieve balanced liquidity provision in a vault.
+
+## Overview
+
+When performing a single-asset deposit, the contract needs to determine how much of the input token should be swapped to the other token to maintain the optimal ratio for the vault. This function uses on-chain contract calculations to determine this amount with precision.
+
+## Function Signature
+
+```typescript
+async function calculateSwapAmount(
+  publicClient: PublicClient,
+  params: CalculateSwapAmountParams
+): Promise<SteerResponse<SwapAmountResponse>>
+```
+
+## Parameters
+
+### CalculateSwapAmountParams
+
+```typescript
+interface CalculateSwapAmountParams {
+  /** Amount of tokens being deposited */
+  depositAmount: bigint;
+  /** true if depositing token0, false if token1 */
+  isToken0: boolean;
+  /** Address of the vault */
+  vault: Address;
+  /** Address of the pool */
+  pool: Address;
+  /** Type of AMM */
+  ammType: AMMType;
+  /** Address of the single-asset deposit contract */
+  singleAssetDepositContract: Address;
+}
+```
+
+**Parameter Details:**
+
+- **`depositAmount`**: The total amount of tokens the user wants to deposit (in wei)
+- **`isToken0`**: Boolean indicating which token is being deposited:
+  - `true`: Depositing token0 (e.g., ETH in ETH/USDC pool)
+  - `false`: Depositing token1 (e.g., USDC in ETH/USDC pool)
+- **`vault`**: The target vault address where liquidity will be provided
+- **`pool`**: The underlying pool address (e.g., Uniswap V3 pool)
+- **`ammType`**: The type of AMM protocol (currently supports `AMMType.UniswapV3`)
+- **`singleAssetDepositContract`**: Address of the deployed single-asset deposit contract
+
+## Return Value
+
+### SwapAmountResponse
+
+```typescript
+interface SwapAmountResponse {
+  /** Amount to be swapped from the input token */
+  swapAmount: bigint;
+  /** Current sqrt price (used for internal calculation) */
+  sqrtPrice: bigint;
+}
+```
+
+**Response Details:**
+
+- **`swapAmount`**: The amount of input token that should be swapped (in wei)
+- **`sqrtPrice`**: Current sqrt price from the pool (Q96 format)
+
+## Examples
+
+### Basic Usage
+
+```typescript
+import { calculateSwapAmount, AMMType } from '@steerprotocol/sdk';
+import { parseEther } from 'viem';
+
+const result = await calculateSwapAmount(publicClient, {
+  depositAmount: parseEther('100'),
+  isToken0: true,
+  vault: '0xd6bac58d87772fa3a7400f15fd121b7edc30ce3c',
+  pool: '0xd19a1c8278d0420bfb2c825d99dc31ff86224607',
+  ammType: AMMType.UniswapV3,
+  singleAssetDepositContract: '0x9903C4ED61A71d0d5C322097adfF752d6339F871'
+});
+
+if (result.success) {
+  console.log('Swap amount:', result.data.swapAmount);
+  console.log('Current sqrt price:', result.data.sqrtPrice);
+  
+  // Convert to human-readable format
+  const swapAmountEther = formatEther(result.data.swapAmount);
+  console.log(`Should swap ${swapAmountEther} tokens`);
+} else {
+  console.error('Failed to calculate swap amount:', result.error);
+}
+```
+
+### Token1 Deposit
+
+```typescript
+// Depositing token1 instead of token0
+const result = await calculateSwapAmount(publicClient, {
+  depositAmount: parseEther('1000'),  // 1000 USDC
+  isToken0: false,                    // Depositing token1 (USDC)
+  vault: vaultAddress,
+  pool: poolAddress,
+  ammType: AMMType.UniswapV3,
+  singleAssetDepositContract: contractAddress
+});
+```
+
+### With Error Handling
+
+```typescript
+async function safeCalculateSwapAmount(params: CalculateSwapAmountParams) {
+  try {
+    const result = await calculateSwapAmount(publicClient, params);
+    
+    if (!result.success) {
+      throw new Error(`Swap calculation failed: ${result.error}`);
+    }
+    
+    // Validate reasonable swap amount (not more than 50% of deposit)
+    const swapPercentage = (result.data.swapAmount * 100n) / params.depositAmount;
+    if (swapPercentage > 50n) {
+      console.warn(`High swap percentage: ${swapPercentage}%`);
+    }
+    
+    return result.data;
+  } catch (error) {
+    console.error('Error calculating swap amount:', error);
+    throw error;
+  }
+}
+```
+
+## Algorithm Details
+
+The function calls the on-chain `calculateSwapAmount` function which:
+
+1. **Retrieves vault state**: Gets current token balances and reserves
+2. **Calculates optimal ratio**: Determines the ideal token ratio for the vault
+3. **Computes swap amount**: Calculates how much to swap to achieve this ratio
+4. **Returns results**: Provides both swap amount and current price
+
+### Mathematical Approach
+
+The calculation considers:
+- Current vault reserves (token0/token1 ratio)
+- Pool price (from sqrt price)
+- Deposit amount and token type
+- Optimal rebalancing to match vault strategy
+
+## Testing
+
+### Unit Test Example
+
+```typescript
+describe('calculateSwapAmount', () => {
+  it('should calculate correct swap amount for token0 deposit', async () => {
+    const mockPublicClient = {
+      readContract: jest.fn().mockResolvedValue([
+        parseEther('25'),  // swapAmount
+        BigInt('79228162514264337593543950336')  // sqrtPrice
+      ]),
+      getChainId: jest.fn().mockResolvedValue(137)
+    };
+
+    const result = await calculateSwapAmount(mockPublicClient, {
+      depositAmount: parseEther('100'),
+      isToken0: true,
+      vault: mockVaultAddress,
+      pool: mockPoolAddress,
+      ammType: AMMType.UniswapV3,
+      singleAssetDepositContract: mockContractAddress
+    });
+
+    expect(result.success).toBe(true);
+    expect(result.data.swapAmount).toBe(parseEther('25'));
+    expect(mockPublicClient.readContract).toHaveBeenCalledWith({
+      address: mockContractAddress,
+      abi: expect.any(Array),
+      functionName: 'calculateSwapAmount',
+      args: [
+        parseEther('100'),
+        true,
+        mockVaultAddress,
+        mockPoolAddress,
+        AMMType.UniswapV3
+      ]
+    });
+  });
+});
+```
+
+### Integration Test
+
+```typescript
+it('should work with real contracts', async () => {
+  const realClient = createPublicClient({
+    chain: polygon,
+    transport: http()
+  });
+
+  const result = await calculateSwapAmount(realClient, {
+    depositAmount: parseEther('1'),
+    isToken0: true,
+    vault: '0xd6bac58d87772fa3a7400f15fd121b7edc30ce3c', // Real vault
+    pool: '0xd19a1c8278d0420bfb2c825d99dc31ff86224607',  // Real pool
+    ammType: AMMType.UniswapV3,
+    singleAssetDepositContract: '0x9903C4ED61A71d0d5C322097adfF752d6339F871'
+  });
+
+  expect(result.success).toBe(true);
+  expect(result.data.swapAmount).toBeGreaterThan(0n);
+});
+```
+
+## Error Handling
+
+Common error scenarios and how to handle them:
+
+### Contract Errors
+
+```typescript
+// Contract not deployed or wrong address
+if (result.status === 500 && result.error?.includes('contract')) {
+  console.error('Contract not found. Check deployment address.');
+}
+
+// Invalid pool state
+if (result.error?.includes('pool')) {
+  console.error('Pool state invalid. Pool may be paused or have no liquidity.');
+}
+```
+
+### Parameter Validation
+
+```typescript
+function validateParams(params: CalculateSwapAmountParams): void {
+  if (params.depositAmount <= 0n) {
+    throw new Error('Deposit amount must be greater than 0');
+  }
+  
+  if (!params.vault || params.vault === '0x0000000000000000000000000000000000000000') {
+    throw new Error('Invalid vault address');
+  }
+  
+  if (!Object.values(AMMType).includes(params.ammType)) {
+    throw new Error('Unsupported AMM type');
+  }
+}
+```
+
+## Best Practices
+
+### 1. Cache Results When Appropriate
+
+```typescript
+// Cache swap calculations for repeated calls with same parameters
+const cache = new Map<string, SwapAmountResponse>();
+
+async function cachedCalculateSwapAmount(params: CalculateSwapAmountParams) {
+  const key = JSON.stringify(params);
+  
+  if (cache.has(key)) {
+    return { success: true, data: cache.get(key)! };
+  }
+  
+  const result = await calculateSwapAmount(publicClient, params);
+  if (result.success) {
+    cache.set(key, result.data);
+  }
+  
+  return result;
+}
+```
+
+### 2. Validate Reasonable Outputs
+
+```typescript
+function validateSwapAmount(swapAmount: bigint, depositAmount: bigint): boolean {
+  const percentage = (swapAmount * 100n) / depositAmount;
+  
+  // Warn if swap amount is more than 80% of deposit
+  if (percentage > 80n) {
+    console.warn(`High swap percentage: ${percentage}%. Check pool balance.`);
+    return false;
+  }
+  
+  // Warn if swap amount is less than 5% of deposit
+  if (percentage < 5n) {
+    console.warn(`Low swap percentage: ${percentage}%. Pool may be imbalanced.`);
+  }
+  
+  return true;
+}
+```
+
+### 3. Handle Network Issues
+
+```typescript
+async function robustCalculateSwapAmount(
+  params: CalculateSwapAmountParams,
+  retries = 3
+): Promise<SwapAmountResponse> {
+  for (let i = 0; i < retries; i++) {
+    try {
+      const result = await calculateSwapAmount(publicClient, params);
+      if (result.success) {
+        return result.data;
+      }
+      throw new Error(result.error);
+    } 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');
+}
+```
+
+## Related Functions
+
+- **[calculateLimitPrice](./calculateLimitPrice.md)** - Calculates slippage protection limits
+- **[simulateSwap](./simulateSwap.md)** - Simulates the actual swap operation  
+- **[estimateLpTokens](./estimateLpTokens.md)** - Estimates final LP tokens received
+
+## Contract Interface
+
+The function calls this smart contract method:
+
+```solidity
+function calculateSwapAmount(
+    uint256 depositAmount,
+    bool isToken0,
+    address vault,
+    address pool,
+    uint8 ammType
+) external view returns (uint256 swapAmount, uint160 sqrtPrice);
+```
+
+This ensures calculations are performed with the same logic as the actual deposit transaction.