Vaults Docs

Vaults is a system specifically designed to automatically manage user liquidity. It encompasses the timely reinvestment of fees and rewards, as well as rebalancing when necessary.

Vaults possesses the CLMM PositionNFT. When a user deposits tokens into Vaults, those tokens are utilized to provide liquidity within the positions held by Vaults.

As tokens are added to the respective positions, LP (Liquidity Provider) tokens are minted and allocated to users.

These LP tokens serve as a representation of the individual's share of liquidity within Vaults.

The Vaults SDK provides powerful interfaces for interacting with the 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/volatile-vaults-sdk

npm install volatile-vaults-sdk

or

bun install volatile-vaults-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

1. Queries

1. Get Pool List

Retrieves a list of all available vaults pools.

const poolList = await sdk.Vaults.getPoolList()

2. Get Specific Pool Details

Fetches details of a specific pool using its poolId.

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

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.

const clmm_pool_id="0x..."
  const res = await sdk.CetusClmmSDK.Pool.getPool(clmm_pool_id)

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.

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

2. Mode: FlexibleBoth

Allows specifying amounts for both assets, and the system calculates the corresponding LP tokens.

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

3. Mode: OnlyCoinA or OnlyCoinB

These modes allow depositing only one type of asset.

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

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.

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

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:

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
});