haedal-vault-sdk 1.5.0 → 1.7.0

package/README.md

@@ -42,39 +42,111 @@ sdk.senderAddress = '0x..'
 ```
 
 ## Function Description
+
+### Vaults Module vs VaultsV2 Module
+
+The SDK provides two coexisting vault modules, each designed for different types of liquidity pools:
+
+- **Vaults Module** (`sdk.Vaults`): Specialized module for CLMM (Constant Liquidity Market Maker) pools
+- **VaultsV2 Module** (`sdk.VaultsV2`): Specialized module for DLMM (Dynamic Liquidity Market Maker) pools
+
+Both modules coexist and serve different purposes:
+- **Vaults** is specifically designed for CLMM pool management
+- **VaultsV2** is specifically designed for DLMM pool management
+
+The modules maintain consistent method signatures and usage patterns, making it easy to use the appropriate module based on your pool type. The main differences are:
+
+1. **Pool Types**: Vaults supports CLMM pools, VaultsV2 supports DLMM pools
+2. **Target Use Cases**: Each module is optimized for its respective pool type
+3. **Data Structures**: Each module provides data structures tailored to their specific pool types
+
 ### 1. Queries
 #### 1. Get Pool List
 Retrieves a list of all available vaults pools.
+
+**Vaults Module:**
 ```typescript
 const poolList = await sdk.Vaults.getPoolList()
 ```
 
+**VaultsV2 Module:**
+```typescript
+const poolList = await sdk.VaultsV2.getPoolList()
+```
+
 #### 2. Get Specific Pool Details
 Fetches details of a specific pool using its poolId.
+
+**Vaults Module:**
 ```typescript
 const poolId="0x..."
 const pool = await sdk.Vaults.getPool(poolId)
 ```
 
-#### 3.Querying LP Holdings
-To query the LP (Liquidity Provider) token balance for a specific address in a particular pool
+**VaultsV2 Module:**
+```typescript
+const poolId="0x..."
+const pool = await sdk.VaultsV2.getPool(poolId)
+```
+
+#### 3. Querying LP Holdings
+To query the LP (Liquidity Provider) token balance for a specific address in a particular pool.
+
+**Vaults Module:**
 ```typescript
 const poolId="0x..." // The ID of the pool
 const address="0x..." // The address of the wallet
 const res = await sdk.Vaults.getOwnerVaultsBalance(address, poolId)
 ```
 
-#### 4. Get Specific Clmm Pool Details
-Fetches details of a specific pool using its poolId.
+**VaultsV2 Module:**
+```typescript
+const poolId="0x..." // The ID of the pool
+const address="0x..." // The address of the wallet
+const res = await sdk.VaultsV2.getOwnerVaultsBalance(address, poolId)
+```
+
+#### 4. Get Specific CLMM Pool Details
+Fetches details of a specific CLMM pool using its poolId.
 ```typescript
 const clmm_pool_id="0x..."
-  const res = await sdk.CetusClmmSDK.Pool.getPool(clmm_pool_id)
+const res = await sdk.CetusClmmSDK.Pool.getPool(clmm_pool_id)
+```
+
+#### 5. Get Specific DLMM Pool Details
+Fetches details of a specific DLMM pool using its poolId.
+```typescript
+const dlmm_pool_id="0x..."
+const res = await sdk.CetusDlmmSDK.Pool.getPool(dlmm_pool_id)
+```
+
+#### 6. VaultsV2 Additional Query Methods
+
+**Get Multiple Pools by IDs:**
+```typescript
+const poolIds = ["0x...", "0x..."]
+const pools = await sdk.VaultsV2.getAssignPoolList(poolIds)
+```
+
+**Get Market List:**
+```typescript
+const marketsTableId = "0x..."
+const markets = await sdk.VaultsV2.getMarketList(marketsTableId)
+```
+
+**Get Market Position List:**
+```typescript
+const positionTableId = "0x..."
+const positions = await sdk.VaultsV2.getMarketPositionList(positionTableId)
 ```
 
 ### 2. Deposit
 Deposits can be made using different modes. Below are examples of various deposit types.
+
 #### 1. Mode: FixedOneSide
 In this mode, one asset's amount is fixed, and the other is calculated automatically.
+
+**Vaults Module:**
 ```typescript
 const poolId="0x..."
 
@@ -93,8 +165,30 @@ const tx = await sdk.Vaults.buildDepositPayload({
     amount_b: result.deposit_amount_b,
 })    
 ```
+
+**VaultsV2 Module:**
+```typescript
+const poolId="0x..."
+
+// Pre-calculate deposit amounts based on the fixed asset
+const result = await sdk.VaultsV2.preCalculateDepositAmount( {
+    mode: 'FixedOneSide',
+    fixed_amount: toDecimalsAmount(1, 6).toString(),// // Fixed amount 
+    fixed_coin_a: true,// // Determines which asset is fixed
+    pool_id: poolId,
+})
+
+// Build the deposit transaction payload
+const tx = await sdk.VaultsV2.buildDepositPayload({
+    pool_id: poolId,
+    amount_a: result.deposit_amount_a,
+    amount_b: result.deposit_amount_b,
+})    
+```
 #### 2. Mode: FlexibleBoth
 Allows specifying amounts for both assets, and the system calculates the corresponding LP tokens.
+
+**Vaults Module:**
 ```typescript
 const poolId="0x..."
 
@@ -113,8 +207,29 @@ const tx = await sdk.Vaults.buildDepositPayload({
 })    
 ```
 
+**VaultsV2 Module:**
+```typescript
+const poolId="0x..."
+
+const result = await sdk.VaultsV2.preCalculateDepositAmount({
+    mode: 'FlexibleBoth',
+    coin_amount_a: toDecimalsAmount(1, 6).toString(), // User-defined deposit amount for asset A
+    coin_amount_b: toDecimalsAmount(1, 9).toString(), // User-defined deposit amount for asset B
+    pool_id: poolId,
+})
+
+// Build the deposit transaction payload
+const tx = await sdk.VaultsV2.buildDepositPayload({
+    pool_id: poolId,
+    amount_a: result.deposit_amount_a,
+    amount_b: result.deposit_amount_b,
+})    
+```
+
 #### 3. Mode: OnlyCoinA or OnlyCoinB
 These modes allow depositing only one type of asset.
+
+**Vaults Module:**
 ```typescript
 const poolId="0x..."
 
@@ -131,11 +246,30 @@ const tx = await sdk.Vaults.buildDepositPayload({
 })    
 ```
 
+**VaultsV2 Module:**
+```typescript
+const poolId="0x..."
+
+const result = await sdk.VaultsV2.preCalculateDepositAmount( {
+    mode: 'OnlyCoinA',
+    coin_amount_a: toDecimalsAmount(1, 6).toString(), // Deposit only asset A
+})
+
+// Build the deposit transaction payload
+const tx = await sdk.VaultsV2.buildDepositPayload({
+    pool_id: poolId,
+    amount_a: result.deposit_amount_a,
+    amount_b: result.deposit_amount_b,
+})    
+```
+
 ### 3. Withdrawal
 Withdrawals can be performed in different modes, similar to deposits.
 
 #### 1. Mode: FixedOneSide (Withdraw by LP token amount)
 Withdraws assets based on a specified LP token amount.
+
+**Vaults Module:**
 ```typescript
 const poolId="0x..."
 
@@ -147,14 +281,27 @@ const tx = await sdk.Vaults.buildWithdrawPayload({
 })    
 ```
 
+**VaultsV2 Module:**
+```typescript
+const poolId="0x..."
+
+// Build the withdrawal transaction payload
+const tx = await sdk.VaultsV2.buildWithdrawPayload({
+    pool_id: poolId,
+    burn_lp_amount: result.burn_lp_amount,
+    mode: result.mode,
+})    
+```
+
 
 #### 2. Mode: OnlyCoinA  or OnlyCoinB (Withdraw by LP token amount)
 In this mode, the user specifies the amount of a single coin (either Coin A or Coin B) they wish to receive. 
 Example for OnlyCoinA:
+
+**Vaults Module:**
 ```typescript
 const poolId="0x..."
 
-
 // Build the withdrawal transaction payload
 const tx = await sdk.Vaults.buildWithdrawPayload({
     pool_id: poolId,
@@ -164,5 +311,61 @@ const tx = await sdk.Vaults.buildWithdrawPayload({
 });    
 ```
 
+**VaultsV2 Module:**
+```typescript
+const poolId="0x..."
 
+// Build the withdrawal transaction payload
+const tx = await sdk.VaultsV2.buildWithdrawPayload({
+    pool_id: poolId,
+    burn_lp_amount: result.burn_lp_amount, // Amount of LP tokens to burn
+    mode: result.mode, // Withdrawal mode ('OnlyCoinA')
+    slippage: "0.001" // Slippage tolerance when swapping the counterpart asset during the withdrawal
+});    
+```
 
+## Module Comparison Summary
+
+### Vaults Module (sdk.Vaults)
+- **Purpose**: Specialized vault module for CLMM pools
+- **Pool Support**: CLMM (Constant Liquidity Market Maker) pools only
+- **Key Features**: CLMM-optimized vault operations, fee collection, reward management
+- **Use Case**: Liquidity provision and management in CLMM pools
+
+### VaultsV2 Module (sdk.VaultsV2)
+- **Purpose**: Specialized vault module for DLMM pools
+- **Pool Support**: DLMM (Dynamic Liquidity Market Maker) pools only
+- **Key Features**: 
+  - DLMM-optimized vault operations
+  - DLMM market and position management
+  - DLMM-specific data structures
+  - Advanced query methods for DLMM markets and positions
+- **Use Case**: Liquidity provision and management in DLMM pools
+
+### Method Compatibility
+Both modules maintain consistent method signatures for core operations:
+- `getPoolList()` - Get list of available pools
+- `getPool(poolId)` - Get specific pool details
+- `getOwnerVaultsBalance(address, poolId)` - Query LP holdings
+- `preCalculateDepositAmount()` - Calculate deposit amounts
+- `buildDepositPayload()` - Build deposit transactions
+- `preCalculateWithdrawAmount()` - Calculate withdrawal amounts
+- `buildWithdrawPayload()` - Build withdrawal transactions
+
+### Module Selection Guide
+Choose the appropriate module based on your pool type:
+
+**For CLMM Pools:**
+- Use `sdk.Vaults` for all CLMM pool operations
+- Optimized for constant liquidity market maker pools
+- Provides traditional vault functionality
+
+**For DLMM Pools:**
+- Use `sdk.VaultsV2` for all DLMM pool operations  
+- Optimized for dynamic liquidity market maker pools
+- Provides advanced DLMM-specific features
+
+**Key Points:**
+- Both modules can be used simultaneously in the same application
+- Method signatures are consistent between modules for easy switching
+- Choose the module that matches your target pool type