Staking Vault JS SDK

The Chaos Finance Staking Vault JavaScript SDK provides a comprehensive interface for integrating Liquid Staking Derivatives (LSD) functionality into your SONIC applications. This SDK enables developers to easily implement staking, unstaking, and withdrawal operations with built-in error handling and transaction management.

Installation

To add Chaos Finance Staking Vault LSD into your application, run this in the terminal from the root directory of the application:

npm install @chaosfinance/svm-vault --save

Quick Start

1. Initialize the SDK

The first step developers should do is register REST endpoint, lsd program configs and wallet related functions. There are three functions involved: register, registerChain and registerWallet The register function is equivalent to executing both registerChain and registerWallet.

The registerChain function doesn't require a connected wallet, but both register and registerWallet do. Therefore, if your app needs to retrieve on-chain status before connecting wallet, you may call registerChain, then you are able to query global infos, such as lst apr, min stake amount, platform fee commission etc. If you got the wallet connected, you can call register or registerWallet to finish the process, so that you can call staking functions: stake, unstake, withdraw or user information functions.

register()

const wallet = // Get the wallet object that user selected
await wallet.connect()
 
// Register the provider with your RPC endpoint and project ID
// Your project identifier for off-chain analysis. e.g. 'chaos-finance' / 'fomoney'
// It's recommended to contact Chaos Finance to prevent identifier collisions.
register({
  restEndpoint: 'https://api.testnet.sonic.game', // Your RPC endpoint
  signTransaction:     (tx) => wallet.signTransaction(tx),
  signAllTransactions: (txs) => wallet.signAllTransactions(txs),
  publicKey: wallet.publicKey,
}, 'your-project-id');

registerChain()

registerChain(
    'https://api.testnet.sonic.game', // REST Endpoint
    
    // Project ID, Your project identifier for off-chain analysis. e.g. 'chaos-finance' / 'fomoney'
    // It's recommended to contact Chaos Finance to prevent identifier collisions.
    ''
)

registerWallet()

const wallet = // Get the wallet object that user selected
await wallet.connect()
 
// Register wallet functions
registerWallet(
  (tx) => wallet.signTransaction(tx),
  (txs) => wallet.signAllTransactions(txs),
  wallet.publicKey
);

updatePublicKey()

Set new public key when account changes.

const newPublicKey = new PublicKey(wallet.publicKey.toBytes()) 
updatePublicKey(newPublicKey)

2. Define Program IDs

Set up your program configuration:

const programIds = {
  lsdProgramId: 'staking vault program id',
   // Each staking vault has its own unique Stake Manager address,
   // which is created during the staking vault setup
  stakeManagerAddress: ''
};

the staking vault lsd program id and its stake manager address can be found here: Deployed Contract Addresses

3. Staking Operations

Stake Tokens

import { stakeToken } from '@chaosfinance/svm-vault';
 
try {
  const txHash = await stakeToken(100, programIds); // Stake 100 tokens
  console.log('Staking transaction:', txHash);
} catch (error) {
  console.error('Staking failed:', error.message);
}

Unstake LST Tokens

import { unstakeLstToken } from '@chaosfinance/svm-vault';
 
try {
  const txHash = await unstakeLstToken(50, programIds); // Unstake 50 LST tokens
  console.log('Unstaking transaction:', txHash);
} catch (error) {
  console.error('Unstaking failed:', error.message);
}

Withdraw Tokens

import { withdrawToken } from '@chaosfinance/svm-vault';
 
try {
  const txHash = await withdrawToken(programIds);
  console.log('Withdrawal transaction:', txHash);
} catch (error) {
  console.error('Withdrawal failed:', error.message);
}

const solBalance = await getUserSolBalance();
console.log('SOL Balance:', solBalance);

getUserStakingTokenBalance()

Returns the user's staking token balance.

const stakingBalance = await getUserStakingTokenBalance(programIds);
console.log('Staking Token Balance:', stakingBalance);

getUserLstBalance()

Returns the user's LST token balance.

const lstBalance = await getUserLstBalance(programIds);
console.log('LST Balance:', lstBalance);

getUserStakedAmount()

Returns the user's total staked amount in base tokens.

const stakedAmount = await getUserStakedAmount(programIds);
console.log('Total Staked Amount:', stakedAmount);

getUserWithdrawInfo()

Returns information about user's pending withdrawals.

Returns: WithdrawInfo object

interface WithdrawInfo {
  overallAmount: string;           // Total amount in withdrawal process
  claimableAmount: string;         // Amount ready to withdraw
  remainingTimeInSeconds: number;  // Time remaining until next withdrawal
}

const withdrawInfo = await getUserWithdrawInfo(programIds);
console.log('Withdrawal Info:', withdrawInfo);

Global Query Functions

getTotalLstAmount()

Returns the total LST amount in the pool.

const totalLst = await getTotalLstAmount(programIds);
console.log('Total LST in Pool:', totalLst);

getTotalStakedAmount()

Returns the total staked amount in the pool.

const totalStaked = await getTotalStakedAmount(programIds);
console.log('Total Staked in Pool:', totalStaked);

getLstRate()

Returns the current LST exchange rate.

const rate = await getLstRate(programIds);
// output: 1.09 which means 1 LST = 1.09 staking token

Before staking users can pre calculate the amount of LST they will receive by:

lstAmount = stakeAmount / rate
// e.g. 9.1743(LST) = 10 (staking token) / 1.09

The unstake amount of staking token that users will receive can be calculated with:

tokenAmount = unstakeLstAmount * rate
// e.g. 10.9(staking token) = 10 (LST) * 1.09

getLstApr()

Returns the current APR (Annual Percentage Rate).

const apr = await getLstApr(programIds, 0.09); // Default 9% APR
// output: 0.12 = 12%

getUserMinStakeAmount()

Returns the minimum stake amount required.

const amount = await getUserMinStakeAmount(programIds);

getUnbondingDuration()

Returns the unbonding duration in seconds.

const unbondingDurSec = await getUnbondingDuration(programIds);

getTokenProgramIds()

Returns the token program ID for a given mint address.

interface { // TokenProgramIds structure
    lsdTokenMintAddress: string;
    stakingTokenMintAddress: string;
}

const tokenProgramIds = await getTokenProgramIds(stakingVaultLsdTokenMintAddress);