@symmetry-hq/funds-sdk
v0.1.80
Published
Software Development Kit for interacting with Symmetry Funds Program
Downloads
34
Readme
Vaults Sdk
Software Development Kit for interacting with Symmetry Vaults Program
Init
import { FundsSDK } from "@symmetry-hq/funds-sdk";
let vaultsSdk: FundsSDK = await FundsSDK.init(
// rpc connection
connection: Connection,
// wallet (optional, can be provided later, using setWallet()
wallet: Wallet,
);
// load list of supported tokens(returns TokenSettings array)
let tokens: TokenSettings[] = vaultsSdk.getTokenListData();
// get tokenId(tokenId in symmetry supported tokens) from mint
let tokenId = vaultsSdk.tokenIdFromMint(
"So11111111111111111111111111111111111111112"
);
// set wallet
vaultsSdk.setWallet(wallet: Wallet);
Create/Edit/Close Vault
Create Vault with specific settings and rules
Checkout Types and Full Example for more information on how settings should be provided.
let vault: Fund = await vaultsSdk.createFund(params: CreateFundParams);
Edit Vault (Only for actively managed vaults) Vault name and symbol can not be changed.
// Option 1 - (Simple) Directly set desired composition
await vaultsSdk
.simpleEditFund(vault: Fund, params: SimpleEditParams);
// Option 2 - (Advanced) Provide full settings with rules
await vaultsSdk
.editFund(vault: Fund, params: CreateFundParams);
Close Vault (Vault TVL == 0 & no active BuyStates is required)
await vaultsSdk.closeFund(vault: Fund);
Create/Update Metadata for Vaults token mint:
let tx: TransactionSignature[] = await vaultsSdk.setMetadata(
vault: Fund,
symbol: string,
name: string,
uri: string,
);
Load Vault(s)
Load specific vault from pubkey
let vault: Fund = await vaultsSdk.loadFromPubkey(pubkey: PublicKey);
Load vaults array based on filters (manager/host platform pubkey)
let vaults: Fund[] = await vaultsSdk.findFunds(filters: FilterOption[]);
let vaults: Fund[] = await vaultsSdk.findFunds([{
filterType: "manager"|"host",
filterPubkey: PublicKey
}]);
You can also load vaults' current compositions
let currentCompositions: CurrentComposition[] =
await vaultsSdk.getCurrentCompositions(vaults: Fund[]);
Buy Vault Tokens
There are three ways to buy a vault token.
Option 1 (Simple):
Buy vault with a single token (token should be in the vault composition)
// Fetch expected amount of Vault tokens after contribution
let expectedAmount = await vaultsSdk.computeMintAmountWithSingleToken(
vault: Fund,
token: PublicKey,
amount: number
);
// Contribute single token and mint Vault tokens
let tx: TransactionSignature = await vaultsSdk.buyWithSingleToken(
vault: Fund,
token: PublicKey,
amount: number
);
Option 2 (Simple): Contribute all tokens from vaults composition
Works for vaults with no more than 5 tokens Amounts for tokens should be provided in the same order tokens are present in vaults composition. Vaults composition can be found in Fund object of a vault, or using getCurrentCompositions()
// Fetch expected amount of Vault tokens after contribution
let expectedAmount: number = await vaultsSdk.computeMintAmount(
vault: Fund,
amounts: number[]
);
// Contribute tokens and mint Vault tokens
let tx: TransactionSignature = await vaultsSdk.buyFundInstant(
vault: Fund,
amounts: number[]
);
Option 3 (Advanced):
Users also have option to contribute USDC to the vault. Symmetry Engine will use that USDC to buy underlying tokens (rebalance usdc to vaults current composition based on their target weights) After rebalancing, vault tokens will be minted for user.
Step 1: Contribute USDC to Vault and create BuyState (Temporary on-chain account) Initially BuyState will have the information about users contribution.
let buyState: BuyState = await vaultsSdk.buyFund(
vault: Fund,
amountUsdc: number
);
Step 2: Rebalance BuyState: Buy underlying assets in the vault using contributed USDC. During rebalancing process, BuyState will store the information about already purchased assets, as well as remaining amount of USDC. Users can always force-rebalance their BuyState, but it is also done by Symmetry engine (BuyState will automatically rebalance within 3 minutes)
let txs: TransactionSignature[] = await vaultsSdk
.rebalanceBuyState(buyState: BuyState);
Step 3: Mint Vault Tokens & Close Buy State During this stage, all the assets acquired during rebalancing process will be added to the vault. Corresponding vault tokens will be minted for user, and circulating supply of the vault tokens will increase by same amount. After, it will safely close BuyState. Users can call force-mint function after 3 minutes, but Symmetry engine will also automatically handle this step. Rent for creating temporary account goes back to user.
let tx: TransactionSignature = await vaultsSdk
.mintFund(buyState: BuyState);
Helpers:
// Find active BuyStates for user that have been created after Step 1
let buyStates: BuyState[] = await vaultsSdk
.findActiveBuyStates(user: PublicKey);
// Fetch specific BuyState using its PublicKey
let buyState: BuyState[] = await vaultsSdk
.fetchBuyStateFromPubkey(pubkey: PublicKey);
// Claim Tokens from halted BuyState
// In a case where BuyState has been created more than 30 minutes ago,
// and mint was unsuccessful for some reason
// (no liquidity for token / oracle feed not live / chain congestion)
// contributed token(s) can be claimed back by user.
let tx = await vaultsSdk.claimTokensFromBuyState(pubkey: PublicKey)
Sell Vault
There are two ways to sell vault tokens.
Option 1 (Simple): Sell to a specific token (token should be in vaults composition)
// Fetch expected amount of received tokens.
let amount: number = await vaultsSdk.computeOutputAmountWithInstantBurn(
vault: Fund,
amount: number,
withdrawToken: PublicKey
);
// Burn/Sell Vault tokens.
let tx: TransactionSignature = await vaultsSdk.instantBurn(
vault: Fund,
amount: number,
withdrawToken: PublicKey
);
Option 2 (Advanced):
Users can directly claim their portion of the tokens from Vaults composition. They also have an option to rebalance those tokens to USDC before claiming.
Step 1: Burn Vault Tokens and create SellState (Temporary on-chain account) SellState is an on-chain account which has exactly same structure as Vault. Initially SellState will store vaults composition with amounts corresponding to users holdings. Circulating supply will decrease by burn amount and users Vault tokens will be burned. From here, this SellState is already independent from the original Vault. User can specify if they want to rebalance their to-be-claimed tokens to USDC
let sellState: Fund = await vaultsSdk
.sellFund(vault: Fund, amount: number, rebalance: boolean);
Step 2: Rebalance SellState(Vault): Rebalance underlying assets to USDC This step is optional, user can skip this step and directly claim underlying tokens. SellState-s have exact structure as Vaults so rebalance function is same for them. (Optional, only when rebalance == true)
let txs: TransactionSignature[] = await vaultsSdk
.rebalanceFund(sellState: Fund);
Step 3: Claim underlying tokens (or USDC) from SellState. After this step, SellState is closed and rent is collected by user.
let txs: TransactionSignature[] = await vaultsSdk
.claimTokens(sellState: Fund);
Helpers:
// Find active SellStates for user that have been created after Step 1
let sellStates: Fund[] = await vaultsSdk
.findActiveSellStates(user: PublicKey);
Automation
Automation on all vaults (Refilter/Reweight/Rebalance), as well as monitoring active Buy/Sell states and rebalancing them is done by Symmetry Engine, based on RefilterInterval, ReweightInterval, RebalanceInterval settings provided in vault rules. Platforms and Developers can run their own automation for their vaults using examples bellow. Managers can Force-(Refilter/Reweight/Rebalance) anytime.
Refilter Vault
Automatically selects assets based on provided rules in vault settings.
let txs: TransactionSignature = await vaultsSdk.refilterFund(vault: Fund);
Reweight Vault
Automatically updates target weights for assets based on provided rules.
let txs: TransactionSignature = await vaultsSdk.reweightFund(vault: Fund);
Rebalance Vault
Swap vault tokens using DEX aggregators to bring all tokens back to target weights.
let txs: TransactionSignature[] = await vaultsSdk.rebalanceFund(vault: Fund);
Other Helper Functions
Set priority fee:
await vaultsSdk.setPriorityFee(lamports: number);
Fetch User's Holdings:
let allHoldings = await vaultsSdk.fetchAllHoldings(user: PublicKey);
Get Oracle Prices
let txs: number[] = await vaultsSdk.getOraclePrices();
Retrieve TransactionInstruction Objects that can be called on vaults.
import { VaultInstructions } from "@symmetry-hq/funds-sdk";
let ix: TransactionInstruction = await VaultInstructions.closeVaultIx(...);
let ix: TransactionInstruction = await VaultInstructions.refilterVaultIx(...);
let ix: TransactionInstruction = await VaultInstructions.reweightVaultIx(...);
let ix: TransactionInstruction = await VaultInstructions.buyVaultWithSingleTokenIx(...);
let ix: TransactionInstruction = await VaultInstructions.instantBurnIx(...);
// and many more
Swap using Symmetry Vaults Liquidity
Users can swap and check available swap liquidity for a specific vault
Find out more at @symmetry-hq/liquidity-sdk
Full Example
Example shows how to create/buy/sell/rebalance/refilter/reweight a vault
Creating vault with following settings:
- Manager fee : 0.1% - Users pay 0.1% to vault manager when buying
- Is actively managed - Manager can edit vault settings and rules
- Asset Pool consists of 4 tokens - [USDC, SOL, BTC, ETH]
- Vault refilters underlying assets every week
- Vault reweights underlying assets every day
- Vault rebalances every 2 hours
- Vault rebalances when target and current weights differ by at least 5%
- Maximum allowed slippage on rebalance is 3% (compared to oracle price)
- Vault provides swap liquidity for a token if current weight is within 5% (rebalance) 50%(lpOffset) = 2.5% of target weight
- Vault has 1 rule:
- Select TOP 3 assets by 1 week average MarketCap,
- Weight chosen assets by square root of 1 day performance
- Automation is on (Symmetry Engine will Refilter/Reweight/Rebalance based on rules)
- Liquidity Provision is enabled.
import {
FundsSDK,
Fund,
BuyState,
FilterType,
FilterTime,
SortBy,
WeightType,
WeightTime
} from "@symmetry-hq/funds-sdk";
/* init vaults sdk */
let vaultsSdk: FundsSDK = await FundsSDK.init(
connection,
wallet
);
/* Create a vault (CreateFund + SetRules + Refilter&Reweight) */
let vault: Fund = await vaultsSdk.createFund({
name: "Solana Bitcoin Ethereum",
symbol: "SOLBTCETH",
uri: "",
hostPlatform: wallet.publicKey, // platform hosting UI
hostPlatformFee: 0, // fees on deposits for host
manager: wallet.publicKey, // vault manager
managerFee: 10, // deposit fee in bps: 10 = 0.1%
activelyManaged: 1, // actively managed
assetPool: [0, 1, 2, 3], // USDC, SOL, BTC, ETH
refilterInterval: 7 * 24 * 3600, // 1 week
reweightInterval: 24 * 3600, // 1 day
rebalanceInterval: 2 * 3600, // 2 hours
rebalanceThreshold: 500, // 5%
rebalanceSlippage: 300, // 3%
lpOffsetThreshold: 5000, // 50% of rebalance threshold
disableRebalance: 0, // Auto Rebalance is on
disableLp: 0, // Liquidity provision is on
rules: [{
filterBy: FilterType.MarketCap, // filter assets by marketcap
filterDays: FilterTime.Week, // by 1 week average of marketcap
sortBy: SortBy.DescendingOrder, // select top coins by marketcap
totalWeight: 100, // total weight of this rule
fixedAsset: 0, // (provide if filterBy is Fixed)
numAssets: 3, // select 3 assets
weightBy: WeightType.Performance, // weight by performance
weightDays: WeightTime.Day, // 1 day performance
weightExpo: 0.5, // square root of performance
excludeAssets: [0], // Exclude USDC when filtering
}],
});
/* 1. buy a vault with 50 USDC
2. rebalance buyState (buy underlying assets)
3. mint vault tokens */
let buyState1: BuyState = await vaultsSdk.buyFund(vault, 50);
let txsRebalanceBuyState1 = await vaultsSdk.rebalanceBuyState(buyState1);
let txMintFund1 = await vaultsSdk.mintFund(buyState1);
/* 1. buy a vault with 50 USDC without rebalancing
unspent amount will have *penalty* and counted as if rebalance
happend with maximum slippage (rebalanceSlippage = 3%)
2. mint vault tokens */
let buyState2: BuyState = await vaultsSdk.buyFund(vault, 50);
let txMintFund2 = await vaultsSdk.mintFund(buyState2);
/* 1. sell a vault
2. rebalance vault (to USDC)
3. claim tokens (USDC + tokens for which rebalance failed) */
let sellState1: Fund = await vaultsSdk.sellFund(vault, 0.4, true);
let txsRebalanceSellState = await vaultsSdk.rebalanceFund(sellState1);
let txsClaimTokens1 = await vaultsSdk.claimTokens(sellState);
/* 1. sell a vault without rebalancing
2. claim tokens (all tokens in a SellState) */
let sellState2: Fund = await vaultsSdk.sellFund(vault, 0.4, false);
let txsClaimTokens2 = await vaultsSdk.claimTokens(sellState2);
/* 1. Refilter vault (RefilterInterval seconds since last refilter)
2. Reweight vault (ReweightInterval seconds since last reweight)
3. Rebalance vault (RebalanceInterval seconds since last rebalanace) */
let txRefilter: TransactionSignature = await vaultsSdk.refilterFund(vault);
let txReweight: TransactionSignature = await vaultsSdk.reweightFund(vault);
let txsRebalance = await vaultsSdk.rebalanceFund(vault);
/* In some cases, when vault decides to remove token after refiltering,
and rebalance function sells it to USDC, vault might end up with
small amount of that token, for which it is unable to rebalance and
sell the full amount. Although it's possible to remove the "dust"
if user swaps equivalent amount of usdc (based on oracle price) for
the token, which is stuck in a vault. Meaning that vault will receive
USDC and user will receive token. RemoveDust will be triggered for
tokens with equivalent USD value < 0.005.
Amount of usdc to be swapped is computed in a following way:
max(tokenAmount * tokenPrice * 1.1 (for slippage purposes), 0.000001) */
let txsRemoveDust = await vault.removeDust();
Types
// Information about Token and its settings
type TokenSettings = {
id: number,
symbol: string,
name: string,
tokenMint: string,
decimals: number,
coingeckoId: string,
pdaTokenAccount: string,
oracleType: string,
oracleAccount: string,
oracleIndex: number,
oracleConfidencePct: number,
fixedConfidenceBps: number,
tokenSwapFeeBeforeTwBps: number,
tokenSwapFeeAfterTwBps: number,
isLive: boolean,
lpOn: boolean,
useCurveData: boolean,
additionalData: number[],
}
// Create/Edit Vault settings
type SimpleEditParams = {
managerFee: number, // manager fee in bps 100 = 1%
rebalanceInterval: number, // rebalance interval in seconds
rebalanceThreshold: number, // rebalance threshold in bps 100 = 1%
rebalanceSlippage: number, // rebalance slippage in bps 100 = 1%
lpOffsetThreshold: number, // liquidity provsion ... in bps
disableRebalance: boolean, // true for turning of automation
disableLp: boolean, // true for turining of lp
composition: {token: PublicKey, weight: number}[],
}
type CreateFundParams = {
name: string,
symbol: string,
uri: string, // metadata URI which stores name, symbol, logo.
hostPlatform: PublicKey, // platofrm hosting symmetry UI
hostPlatformFee: number, // deposit fee for host platform in bps
manager: PublicKey, // vault manager
managerFee: number, // deposit fee for manager in bps
activelyManaged: number, // 0 - Index, 1 - Actively Manged, 2 - Private
assetPool: number[], // Asset pool with tokenIds (check getTokenListData())
refilterInterval: number, // refilter interval in seconds
reweightInterval: number, // reweight interval in seconds
rebalanceInterval: number, // rebalance interval in seconds
rebalanceThreshold: number, // rebalance threshold in bps
rebalanceSlippage: number, // rebalance slippage in bps
lpOffsetThreshold: number, // liquidity provision .. in bps
disableRebalance: boolean, // true for disabling automaion
disableLp: boolean, // true for disabling liquidity provision
rules: Rule[],
}
type Rule = {
totalWeight: number, // (integer) - total weight of this rule (relative to other rules)
filterBy: FilterType, // FilterType.Fixed if you want this rule to have 1 specific asset
filterDays: FilterTime,
sortBy: SortBy,
fixedAsset: number, // id of token if you want this rule to have 1 specific asset
numAssets: number, // number of tokens for this rule (1 for specific asset)
weightBy: WeightType,
weightDays: WeightTime,
weightExpo: number, // (integer) expo multiplied by 100x. for ^0.5 use 500
excludeAssets: number[], // token ids to be excluded when filtering
}
export enum FilterType {
Fixed, // 0
MarketCap, // 1
Volume, // 2
Performance, // 3
}
export enum WeightType {
Fixed, // 0
MarketCap, // 1
Volume, // 2
Performance, // 3
}
export enum FilterTime {
Day, // 0
Week, // 1
Month, // 2
Quarter, // 3
HalfYear, // 4
Year, // 5
}
export enum WeightTime {
Day, // 0
Week, // 1
Month, // 2
Quarter, // 3
HalfYear, // 4
Year, // 5
}
export enum SortBy {
DescendingOrder, // 0
AscendingOrder, // 1
}
// Current Composition
type CurrentComposition = {
currentSupply: number,
fundTokenMint: PublicKey,
fundWorth: number,
rawPrice: number,
manager: PublicKey,
managerFee: number,
activelyManagded: boolean,
host: PublicKey,
hstFee: number,
currentComposition: CurrComp[],
rules: Rule[]
}
type CurrComp = {
mintAddress: PublicKey,
coingeckoId: string,
symbol: string,
symmetryTokenId: number,
lockedAmount: number,
oraclePrice: number,
usdValue: number,
currentWeight: number,
targetWeight: number
}
// Filter options for finding vaults:
type FundFilter = "manager" | "host";
type FilterOption = {
filterType: FundFilter,
filterPubkey: PublicKey,
}
// On-chain state account structure for Vaults and SellStates
type FundStateChainData = {
version: BN,
manager: PublicKey,
fundToken: PublicKey,
managerFee: BN,
supplyOutsanding: BN,
activelyManaged: BN,
activeBuyStates: BN,
sellState: BN,
rebalanceSellState: BN,
hostPubkey: PublicKey,
hostFee: BN,
numOfTokens: BN,
currentCompToken: BN[],
currentCompAmount: BN[],
lastRebalanceTime: BN[],
targetWeight: BN[],
weightSum: BN,
currentWeight: BN[],
fundWorth: BN,
lastUpdateTime: BN,
refilterInterval: BN,
reweightInterval: BN,
rebalanceInterval: BN,
rebalanceThreshold: BN,
rebalanceSlippage: BN,
lpOffsetThreshold: BN,
lastRefilterTime: BN,
lastReweightTime: BN,
rulesReady: BN,
assetPool: BN[],
numOfRules: BN,
rules: {
filterBy: BN,
filterDays: BN,
sortBy: BN,
totalWeight: BN,
fixedAsset: BN,
numAssets: BN,
weightBy: BN,
weightDays: BN,
weightExpo: BN,
excludeNum: BN,
excludeAssets: BN[],
ruleAssets: BN[],
}[],
numRuleTokens: BN,
ruleTokens: BN[],
ruleTokenWeights: BN[],
messageDigestFive: number[],
disableRebalance: BN,
disableLp: BN,
allowMultiAssetContribution: number,
symbolLength: number,
symbol: number[],
nameLength: number,
name: number[],
uriLength: number,
uri: number[],
extraBytes: number[],
}
// On-chain state account structure for BuyStates
type BuyStateChainData = {
fund: PublicKey,
buyer: PublicKey,
fundManager: PublicKey,
hostPlatform: PublicKey,
buyerFundTokenAccount: PublicKey,
usdcContributed: BN,
usdcLeft: BN,
token: BN[],
amountToSpend: BN[],
amountBought: BN[],
creationTimestamp: BN,
contributedValue: BN
}