Vaults Docs

This SDK is published by Haedal.

haeVault helps users maximize their on-chain yields. The volatile vault is an initial type of its vault strategies, which is specifically designed to automatically manage user liquidity in CLMM DEX. It encompasses the timely reinvestment of fees and rewards, as well as rebalancing when necessary.

Volatile vaults manage CLMM positions in particular DEXes. When a user deposits tokens into a vault, the newly deposited token will be added into vault-managing positions as new liquidity.

As liquidity is added to a particular vault, corresponding vault LP tokens will be minted to users. These LP tokens serve as a representation of the individual's share of liquidity within the particular vault.

This SDK provides powerful interfaces for interacting with the volatile vaults system, enabling pool queries, deposits, and withdrawals. The flexible deposit and withdrawal modes allow users to handle different liquidity scenarios efficiently

Installation

To start using the Vaults SDK, you need to first install it in your TypeScript project. You can add it to your project via npm, yarn or bun:

npm link: https://www.npmjs.com/package/haedal-vault-sdk

npm install haedal-vault-sdk

or

bun install haedal-vault-sdk

1. Initializing the SDK

Initialize the SDK with the necessary configuration parameters. Typically, this involves setting up the network and API keys if required:

• Mainnet:

const MainnetSDK = initVaultSDK({ env: 'mainnet'})

• Testnet:

const TestnetSDK = initVaultSDK({ env: 'testnet'})

2. Set Wallet Address

After linking the wallet, the wallet address must be set in the SDK:

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:

const poolList = await sdk.Vaults.getPoolList()

VaultsV2 Module:

const poolList = await sdk.VaultsV2.getPoolList()

2. Get Specific Pool Details

Fetches details of a specific pool using its poolId.

Vaults Module:

const poolId="0x..."
const pool = await sdk.Vaults.getPool(poolId)

VaultsV2 Module:

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:

const poolId="0x..." // The ID of the pool
const address="0x..." // The address of the wallet
const res = await sdk.Vaults.getOwnerVaultsBalance(address, poolId)

VaultsV2 Module:

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.

const clmm_pool_id="0x..."
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.

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:

const poolIds = ["0x...", "0x..."]
const pools = await sdk.VaultsV2.getAssignPoolList(poolIds)

Get Market List:

const marketsTableId = "0x..."
const markets = await sdk.VaultsV2.getMarketList(marketsTableId)

Get Market Position List:

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:

const poolId="0x..."

// Pre-calculate deposit amounts based on the fixed asset
const result = await sdk.Vaults.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.Vaults.buildDepositPayload({
    pool_id: poolId,
    amount_a: result.deposit_amount_a,
    amount_b: result.deposit_amount_b,
})    

VaultsV2 Module:

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:

const poolId="0x..."

const result = await sdk.Vaults.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.Vaults.buildDepositPayload({
    pool_id: poolId,
    amount_a: result.deposit_amount_a,
    amount_b: result.deposit_amount_b,
})    

VaultsV2 Module:

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:

const poolId="0x..."

const result = await sdk.Vaults.preCalculateDepositAmount( {
    mode: 'OnlyCoinA',
    coin_amount_a: toDecimalsAmount(1, 6).toString(), // Deposit only asset A
})

// Build the deposit transaction payload
const tx = await sdk.Vaults.buildDepositPayload({
    pool_id: poolId,
    amount_a: result.deposit_amount_a,
    amount_b: result.deposit_amount_b,
})    

VaultsV2 Module:

const poolId="0x..."

// Example 1: Single coin deposit without rebalancing (re_balance = false or undefined)
const result = await sdk.VaultsV2.preCalculateDepositAmount( {
    mode: 'OnlyCoinA',
    coin_amount_a: toDecimalsAmount(1, 6).toString(), // Deposit only asset A
    re_balance: false, // Optional: false for single coin deposit only
})

// 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,
})    

// Example 2: Single coin deposit with automatic rebalancing (re_balance = true)
const resultWithRebalance = await sdk.VaultsV2.preCalculateDepositAmount( {
    mode: 'OnlyCoinA',
    coin_amount_a: toDecimalsAmount(1, 6).toString(), // Deposit amount for asset A
    re_balance: true, // Enable automatic rebalancing to match coin A and coin B
})

// Build the deposit transaction payload with rebalance information
const txWithRebalance = await sdk.VaultsV2.buildDepositPayload({
    pool_id: poolId,
    amount_a: resultWithRebalance.deposit_amount_a,
    amount_b: resultWithRebalance.deposit_amount_b,
    re_balance: resultWithRebalance.re_balance, // Include rebalance swap information
})    


// Example 3: OnlyCoinB mode with rebalancing
const resultOnlyCoinB = await sdk.VaultsV2.preCalculateDepositAmount( {
    mode: 'OnlyCoinB',
    coin_amount_b: toDecimalsAmount(1, 9).toString(), // Deposit amount for asset B
    re_balance: true, // Enable automatic rebalancing
})

const txOnlyCoinB = await sdk.VaultsV2.buildDepositPayload({
    pool_id: poolId,
    amount_a: resultOnlyCoinB.deposit_amount_a,
    amount_b: resultOnlyCoinB.deposit_amount_b,
    re_balance: resultOnlyCoinB.re_balance,
})    

Note on re_balance parameter (VaultsV2 only):

• When re_balance is true: The system will automatically calculate and swap a portion of the deposited coin to balance both coin A and coin B according to the pool's ratio. This ensures optimal liquidity provision.
• When re_balance is false or undefined: Only the specified single coin will be deposited, with the other coin amount set to 0. This is a pure single-coin deposit without rebalancing.

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:

const poolId="0x..."

// Build the withdrawal transaction payload
const tx = await sdk.Vaults.buildWithdrawPayload({
    pool_id: poolId,
    burn_lp_amount: result.burn_lp_amount,
    mode: result.mode,
})    

VaultsV2 Module:

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:

const poolId="0x..."

// Build the withdrawal transaction payload
const tx = await sdk.Vaults.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
});    

VaultsV2 Module:

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