@steerprotocol/sdk 1.27.0 → 1.28.0

package/src/base/vault/deposit/types.ts

@@ -0,0 +1,49 @@
+import { Address } from 'viem';
+import { VaultDetails, AlgebraVaultDetails } from '../../../types.js';
+
+export interface VaultDepositParams {
+  vaultAddress: Address;
+  amount0Desired: bigint;
+  amount1Desired: bigint;
+  slippage: number; // percentage as decimal (e.g. 0.01 for 1%)
+  to?: Address; // optional, defaults to sender
+  isSteerPeriphery?: boolean; // optional, determines whether to use steer periphery or vault directly
+  chainId?: number; // optional, required when isSteerPeriphery is true to determine which chain's periphery to use
+}
+
+export interface DepositRatioResponse {
+  ratio: string;
+  token0Balance: bigint;
+  token1Balance: bigint;
+  token0Decimals: bigint;
+  token1Decimals: bigint;
+  vaultDetails: VaultDetails | AlgebraVaultDetails;
+  isAlgebraVault: boolean;
+}
+
+export interface Chain {
+  id: number;
+}
+
+export interface Token {
+  id: Address;
+  decimals: string;
+  symbol: string;
+  name: string;
+}
+
+export interface Pool {
+  id: Address;
+  token0: Token;
+  token1: Token;
+  feeTier: number;
+}
+
+export interface PoolInstanceParams {
+  vaultAddress: Address;
+  chain: Chain;
+  isAlgebraPool: boolean;
+  isAlgebraDirectionPool: boolean;
+  isPoolSharkPool: boolean;
+  isAlgebraIntegralPool: boolean;
+} 

package/src/base/vault/single-asset/README.md

@@ -0,0 +1,541 @@
+# Single-Asset Deposit Module
+
+The Single-Asset Deposit module provides comprehensive functionality for depositing a single token into liquidity vaults while automatically balancing the token pair through internal swaps.
+
+## Overview
+
+Traditional liquidity deposits require users to provide both tokens (e.g., ETH and USDC) in the correct ratio. Single-asset deposits simplify this process by allowing users to deposit only one token, while the contract automatically:
+
+1. **Calculates optimal swap amount** - Determines how much of the input token to swap
+2. **Applies slippage protection** - Sets price limits to prevent excessive slippage
+3. **Simulates the swap** - Previews expected outcomes before execution
+4. **Estimates LP tokens** - Calculates the final LP tokens to be received
+5. **Executes the deposit** - Performs the swap and deposit in a single transaction
+
+## Quick Start
+
+### Using VaultClient (Recommended)
+
+```typescript
+import { SteerClient, AMMType } from '@steerprotocol/sdk';
+import { createPublicClient, createWalletClient, parseEther } from 'viem';
+import { polygon } from 'viem/chains';
+
+// Initialize clients
+const publicClient = createPublicClient({
+  chain: polygon,
+  transport: http()
+});
+
+const walletClient = createWalletClient({
+  chain: polygon,
+  transport: http()
+});
+
+// Create SteerClient
+const steerClient = new SteerClient({
+  environment: 'production',
+  client: publicClient,
+  walletClient: walletClient
+});
+
+// Preview single-asset deposit
+const preview = await steerClient.vaults.previewSingleAssetDeposit({
+  assets: parseEther('100'),           // Deposit 100 tokens
+  receiver: userAddress,               // Address to receive LP tokens
+  vault: vaultAddress,                 // Target vault address
+  isToken0: true,                      // Depositing token0 (set false for token1)
+  depositSlippagePercent: 5n,          // 5% max slippage for deposit
+  swapSlippageBP: 500,                 // 5% max slippage for internal swap
+  ammType: AMMType.UniswapV3,          // AMM protocol type
+}, poolAddress);
+
+if (preview.success) {
+  console.log('Expected LP tokens:', preview.data.lpEstimation.lpTokens);
+  console.log('Swap amount:', preview.data.swapAmount);
+  console.log('Price impact:', preview.data.swapSimulation.priceSlippagePercent);
+  
+  // Execute the deposit
+  const result = await steerClient.vaults.singleAssetDeposit({
+    assets: parseEther('100'),
+    receiver: userAddress,
+    vault: vaultAddress,
+    isToken0: true,
+    depositSlippagePercent: 5n,
+    swapSlippageBP: 500,
+    ammType: AMMType.UniswapV3,
+  });
+  
+  if (result.success) {
+    console.log('Transaction hash:', result.data);
+  }
+}
+```
+
+### Using SingleAssetDepositClient Directly
+
+```typescript
+import { SingleAssetDepositClient, AMMType } from '@steerprotocol/sdk';
+
+const client = new SingleAssetDepositClient(publicClient, walletClient);
+
+// Preview deposit
+const preview = await client.previewDeposit(params, poolAddress);
+
+// Execute deposit
+const result = await client.deposit(params);
+
+// Prepare transaction without executing
+const txData = await client.prepareDepositTx(params);
+```
+
+## API Reference
+
+### VaultClient Methods
+
+#### `previewSingleAssetDeposit(params, poolAddress)`
+
+Previews a single-asset deposit by running all simulation steps without executing the transaction.
+
+**Parameters:**
+- `params: SingleAssetDepositParams` - Deposit parameters
+- `poolAddress: Address` - Address of the pool
+
+**Returns:** `Promise<SteerResponse<SingleAssetDepositPreview>>`
+
+**Example:**
+```typescript
+const preview = await vaultClient.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.
+
+**Parameters:**
+- `params: SingleAssetDepositParams` - Deposit parameters
+
+**Returns:** `Promise<SteerResponse<Hash>>`
+
+**Example:**
+```typescript
+const result = await vaultClient.singleAssetDeposit({
+  assets: parseEther('100'),
+  receiver: userAddress,
+  vault: vaultAddress,
+  isToken0: true,
+  depositSlippagePercent: 5n,
+  swapSlippageBP: 500,
+  ammType: AMMType.UniswapV3,
+});
+```
+
+#### `prepareSingleAssetDepositTx(params)`
+
+Prepares a single-asset deposit transaction without executing it. Useful for batching or custom execution.
+
+**Parameters:**
+- `params: SingleAssetDepositParams` - Deposit parameters
+
+**Returns:** `Promise<SteerResponse<TransactionData>>`
+
+**Example:**
+```typescript
+const txData = await vaultClient.prepareSingleAssetDepositTx(params);
+// Use txData for custom transaction execution or batching
+```
+
+#### `validateSingleAssetDepositParams(params)`
+
+Validates single-asset deposit parameters and throws descriptive errors for invalid inputs.
+
+**Parameters:**
+- `params: SingleAssetDepositParams` - Parameters to validate
+
+**Throws:** `Error` if parameters are invalid
+
+## Core Functions Documentation
+
+### calculateSwapAmount
+
+Calculates the optimal amount of input token to swap for balanced liquidity provision.
+
+```typescript
+import { calculateSwapAmount, AMMType } from '@steerprotocol/sdk';
+
+const result = await calculateSwapAmount(publicClient, {
+  depositAmount: parseEther('100'),
+  isToken0: true,
+  vault: vaultAddress,
+  pool: poolAddress,
+  ammType: AMMType.UniswapV3,
+  singleAssetDepositContract: contractAddress
+});
+
+if (result.success) {
+  console.log('Swap amount:', result.data.swapAmount);
+  console.log('Current sqrt price:', result.data.sqrtPrice);
+}
+```
+
+**Key Features:**
+- Uses on-chain contract calculation for precision
+- Considers current vault reserves and pool state
+- Returns both swap amount and current pool price
+- Supports multiple AMM types
+
+### calculateLimitPrice
+
+Calculates slippage-protected price limits for the internal swap operation.
+
+```typescript
+import { calculateLimitPrice, AMMType } from '@steerprotocol/sdk';
+
+const result = await calculateLimitPrice(publicClient, {
+  pool: poolAddress,
+  slippageBP: 500,           // 5% slippage tolerance
+  zeroForOne: true,          // Swap direction
+  ammType: AMMType.UniswapV3,
+  token0: token0Address,
+  token1: token1Address
+});
+
+if (result.success) {
+  console.log('Price limit:', result.data);
+}
+```
+
+**Key Features:**
+- High-precision arithmetic using Decimal.js
+- Direction-aware slippage calculation
+- Supports token decimal differences
+- Compatible with Uniswap V3 and Algebra variants
+
+### simulateSwap
+
+Simulates the internal swap to preview expected output amounts and price impact.
+
+```typescript
+import { simulateSwap, AMMType } from '@steerprotocol/sdk';
+
+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);
+
+if (result.success) {
+  console.log('Amount0 delta:', result.data.amount0);
+  console.log('Amount1 delta:', result.data.amount1);
+  console.log('Price after swap:', result.data.sqrtPriceX96After);
+}
+```
+
+**Key Features:**
+- Uses Uniswap V3 Quoter for accurate simulation
+- No gas consumption (simulation only)
+- Returns expected output amounts
+- Provides post-swap price information
+
+### simulateSwapWithSlippage
+
+Enhanced swap simulation that includes price impact analysis.
+
+```typescript
+import { simulateSwapWithSlippage, AMMType } from '@steerprotocol/sdk';
+
+const result = await simulateSwapWithSlippage(publicClient, {
+  poolAddress: poolAddress,
+  recipient: userAddress,
+  zeroForOne: true,
+  amountSpecified: parseEther('50'),
+  sqrtPriceLimitX96: priceLimit,
+  ammType: AMMType.UniswapV3,
+  tokenIn: token0Address,
+  tokenOut: token1Address,
+  fee: 3000
+}, chainId);
+
+if (result.success) {
+  console.log('Price slippage:', result.data.priceSlippagePercent + '%');
+  console.log('Current price:', result.data.currentPrice);
+  console.log('Price after swap:', result.data.priceAfter);
+}
+```
+
+### estimateLpTokens
+
+Estimates the final amount of LP tokens that will be received after the deposit.
+
+```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
+});
+
+if (result.success) {
+  console.log('LP tokens:', result.data.lpTokens);
+  console.log('Final amount0:', result.data.finalAmount0);
+  console.log('Final amount1:', result.data.finalAmount1);
+}
+```
+
+**Key Features:**
+- Uses vault's `getShares` calculation
+- Considers current vault reserves
+- Handles edge cases (empty vault, single-token vaults)
+- Returns actual amounts that will be deposited
+
+## Types Reference
+
+### SingleAssetDepositParams
+
+```typescript
+interface SingleAssetDepositParams {
+  assets: bigint;                          // Amount of input token
+  receiver: Address;                       // LP token recipient
+  vault: Address;                          // Target vault
+  isToken0: boolean;                       // true for token0, false for token1
+  depositSlippagePercent: bigint;          // Max slippage % for deposit
+  swapSlippageBP: number;                  // Max slippage BP for swap
+  ammType: AMMType;                        // AMM protocol type
+  singleAssetDepositContract?: Address;    // Contract address (optional)
+}
+```
+
+### 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
+}
+```
+
+### AMMType
+
+```typescript
+enum AMMType {
+  UniswapV3 = 0,              // Fully supported
+  Algebra = 1,                // Planned
+  AlgebraDirectional = 2,     // Planned
+  AlgebraVE33 = 3,           // Planned
+  AlgebraIntegral = 4        // Planned
+}
+```
+
+## Error Handling
+
+The module uses consistent error handling with descriptive messages:
+
+```typescript
+const result = await client.previewDeposit(params, poolAddress);
+
+if (!result.success) {
+  console.error('Deposit failed:', result.error);
+  console.error('Status code:', result.status);
+  // Handle specific error cases
+  
+  if (result.status === 500) {
+    // Server/contract error
+  } else if (result.status === 400) {
+    // Invalid parameters
+  }
+}
+```
+
+Common error scenarios:
+- **Invalid Parameters**: Zero amounts, invalid addresses, excessive slippage
+- **Pool State Issues**: Empty pools, insufficient liquidity
+- **Simulation Failures**: Price impact too high, swap would fail
+- **Contract Errors**: Insufficient allowance, contract not deployed
+
+## Testing
+
+### Unit Testing Individual Functions
+
+```typescript
+import { calculateSwapAmount, AMMType } from '@steerprotocol/sdk';
+
+describe('calculateSwapAmount', () => {
+  it('should calculate correct swap amount', async () => {
+    const result = await calculateSwapAmount(publicClient, {
+      depositAmount: parseEther('100'),
+      isToken0: true,
+      vault: mockVaultAddress,
+      pool: mockPoolAddress,
+      ammType: AMMType.UniswapV3,
+      singleAssetDepositContract: mockContractAddress
+    });
+
+    expect(result.success).toBe(true);
+    expect(result.data.swapAmount).toBeGreaterThan(0n);
+  });
+});
+```
+
+### Integration Testing
+
+```typescript
+import { SteerClient } from '@steerprotocol/sdk';
+
+describe('Single Asset Deposit Integration', () => {
+  let steerClient: SteerClient;
+
+  beforeEach(() => {
+    const publicClient = createPublicClient({ /* config */ });
+    const walletClient = createWalletClient({ /* config */ });
+    steerClient = new SteerClient({
+      environment: 'production',
+      client: publicClient,
+      walletClient: walletClient
+    });
+  });
+
+  it('should complete full deposit workflow', async () => {
+    const preview = await steerClient.vaults.previewSingleAssetDeposit(
+      params, 
+      poolAddress
+    );
+    
+    expect(preview.success).toBe(true);
+    expect(preview.data.lpEstimation.lpTokens).toBeGreaterThan(0n);
+    
+    // Execute deposit based on preview
+    const result = await steerClient.vaults.singleAssetDeposit(params);
+    expect(result.success).toBe(true);
+  });
+});
+```
+
+## Best Practices
+
+### 1. Always Preview Before Executing
+
+```typescript
+// ✅ Good: Preview first
+const preview = await client.previewDeposit(params, poolAddress);
+if (preview.success && preview.data.lpEstimation.lpTokens > minExpectedTokens) {
+  await client.deposit(params);
+}
+
+// ❌ Bad: Execute without preview
+await client.deposit(params);
+```
+
+### 2. Handle Slippage Appropriately
+
+```typescript
+// ✅ Good: Reasonable slippage tolerances
+const params = {
+  // ...
+  depositSlippagePercent: 5n,    // 5% max for deposit
+  swapSlippageBP: 500,          // 5% max for internal swap
+};
+
+// ❌ Bad: Excessive slippage tolerance
+const params = {
+  // ...
+  depositSlippagePercent: 50n,   // 50% is too high
+  swapSlippageBP: 5000,         // 50% is too high
+};
+```
+
+### 3. Validate Inputs
+
+```typescript
+// ✅ Good: Validate before processing
+try {
+  client.validateDepositParams(params);
+  const result = await client.deposit(params);
+} catch (error) {
+  console.error('Invalid parameters:', error.message);
+}
+```
+
+### 4. Monitor Price Impact
+
+```typescript
+const preview = await client.previewDeposit(params, poolAddress);
+if (preview.success) {
+  const priceImpact = parseFloat(preview.data.swapSimulation.priceSlippagePercent);
+  
+  if (priceImpact > 5.0) {
+    console.warn(`High price impact: ${priceImpact}%`);
+    // Consider reducing deposit amount or waiting for better conditions
+  }
+}
+```
+
+## Supported Networks
+
+Currently supports:
+- **Polygon** - Full support with deployed contracts
+- **Ethereum** - Contract deployment pending
+- **Arbitrum** - Contract deployment pending
+
+Additional networks will be supported as contracts are deployed.
+
+## Gas Optimization
+
+The single-asset deposit is optimized for gas efficiency:
+
+- **Single Transaction**: Swap and deposit in one transaction
+- **Minimal State Changes**: Efficient storage operations
+- **Batch Operations**: Multiple deposits can be batched
+- **Preparation Mode**: Prepare transactions for later execution
+
+## Security Considerations
+
+- **Slippage Protection**: Built-in price limit enforcement
+- **Reentrancy Guards**: Contract-level protection
+- **Parameter Validation**: Client-side and contract validation
+- **Simulation First**: Always simulate before execution
+
+## Troubleshooting
+
+### Common Issues
+
+**1. "Insufficient liquidity" error**
+- Check pool has adequate liquidity for the swap size
+- Reduce deposit amount or increase slippage tolerance
+
+**2. "Price impact too high" error**
+- The swap would cause excessive price movement
+- Reduce deposit amount or wait for better market conditions
+
+**3. "Invalid vault address" error**
+- Ensure vault address is correct and vault is active
+- Check vault supports the tokens you're trying to deposit
+
+**4. Contract not found**
+- Verify contract is deployed on the target network
+- Check the contract address in deployments configuration
+
+For additional support, please refer to the main SDK documentation or contact the development team.