Concept
The Token Basketing Module allows users to combine multiple individual derivatives with the same denomination into a single, easily tradable and exchangeable token. For example, KIRA native liquid staking derivatives V<ID>/<denom> that are issued when staking tokens in KIRA network and which are specific to the consensus node V<ID>, can be aggregated using a basket. An other use case would be to aggregate different foreign tokens such as various USD stablecoins like usdt or usdc (similarly to Curve’s 3pool), or IBC wrapped tokens, into a single, more easily tradable and stakable asset.
However, unlike common liquidity pools like Curve or Uniswap, Token Baskets do not depend on a bonding curve equation to determine the price and are simply based on fixed weights assigned to each individual token. They are only intended to consolidate the liquidity of tokens that are collateralized/pegged by the same underlying asset. In addition, one of the unique properties of Token Baskets compared to liquidity pools is that the list of tokens in the basket can be expanded or contracted over time, while the name of the basket token representing the aggregated assets remains the same.
Token Baskets facilitate token swaps, which are subject to daily limits and are executed at fixed ratios with a programmed slippage. The surplus between the actual exchange ratio and the slippage serves as an insurance fund controlled by governance to protect token holders in the event of a depeg. Overall, the Token Basketing Module is not intended to operate as an exchange, but rather as a tool for insurance and risk management, allowing users to distribute their risks among multiple assets with the same underlying peg.
Tokens Weight Assignment in Baskets
The specific tokens that can be deposited into a basket are pre-determined. To ensure that different tokens collateralized by the same underlying asset can be accurately represented in the basket, weights are assigned to each token. These weights define the corresponding amount of the underlying derivative for a given amount of the token. For example, a "USD fiat basket" can be created by assigning a weight of 1/3.6725 = 0.2722940776 to the United Arab Emirates dirham, which is pegged to 1 USD at a rate of 1 USD = 3.6725 AED. The weight of a token can also be used to unify the number of decimal places among multiple aggregate coins with different decimal places. For instance, if two tokens, A and B, both collateralized by the same underlying asset have different numbers of decimal places (e.g. A has 3 decimal places, B has 2 decimal places), weights we can be assigned to each token to unify their decimal places. For example, a weight of 1.00 can be assigned to A and a weight of 0.01 to B. This means that 1 unit of A is equal to 100 units of B, and the basket will be expressed in terms of A, which has 3 decimal places. This allows the basket to represent the underlying value of both tokens in a consistent way, using a single number of decimal places.
The governance must ensure that the weights of each token in the basket are properly configured to maintain the value of the issued basket tokens. Should the governance decide to re-configure one or many of the weight properties of the basket (for example due to peg changes), it is important to ensure that the sum of the products of the weight and amount of each token in the basket must be greater than or equal to the amount of issued basket tokens B<ID>/<denom> otherwise there will not be enough tokens in the basket to redeem. For example, if the basket B<ID> includes tokens A, B, and C, the governance must ensure that . If the weights are not correctly configured, the governance proposal to update the basket weights will fail.
How Users Deposits Translate to Basket Derivatives Tokens
When users deposit a combination of tokens A, B, C… which have the same underlying asset/peg <denom> into the corresponding basket B<ID>, they receive an amount of token B<ID>/<denom> which represent their weight-adjusted share of the total basket pool, similarly to Uniswap LP tokens. For instance, if a user deposits 100 units of token A with a weight of 0.5 into the basket B5/ABC, they will receive 50 units of tokens.
Maximum Weight-Adjusted Tokens Shares
To prevent scenarios where one or more of the aggregated tokens becomes worthless or loses its peg, a tokens_cap field sets the maximum percentage of the total weight-adjusted supply that can be deposited for a given aggregated token (default 1, or 100%). If the amount of tokens to be deposited or swapped would result in the tokens_cap being exceeded for any of the aggregated tokens, the transaction interacting with the basket will fail.
Control Over Deposits, Withdrawals, and Swaps
Token baskets include deposits, withdraws, and swaps boolean fields that can globally prohibit deposits, withdraws, or swaps of one or more specific tokens in the basket. These fields can be disabled without the need to go through a governance proposal, although only accounts with the permission
61 can perform this action. This is meant to allow necessary flexibility in managing the basket, i.e. responding to potential depeg scenarios or other time-sensitive issues with individual tokens which require quick intervention.
Baskets Transactional Limits
To prevent abuse or manipulation of the Token Baskets (i.e. infinite supply of one of the aggregated tokens being flooded into the basket until the tokens_cap is reached), Token Baskets have limits on the amount of tokens that can be minted (created), burned (redeemed for tokens), or swapped over a defined period limits_period. These limits are defined by the mints_max, burns_max, and swaps_max fields, respectively.
To prevent dust spam attacks, minimum amounts of the aggregate and basket tokens that must be minted, burned, or swapped in a single transaction are also defined by the mints_min, burns_min, and swaps_min fields, respectively. Transactions that do not meet these minimum amounts will not be processed.
How Withdrawals Maintain Basket Balance
The claim process is designed to ensure that the basket remains balanced at all time by calculating the ratio at which each token should be credited to the withdrawing user to restore, or at least improve, the proper weighting of the pool’s balances after a withdrawal. This means that the redemption of pooled tokens against the pool’s derivative will always be adjusted based on the current pool balances, potentially resulting in a higher proportion of a specific token if the pool is imbalanced due to previous selective swaps and withdrawals.
Aggregated Tokens Swapping Mechanisms
Token Baskets implement a simple swap mechanism that enables users to exchange one or multiple aggregated tokens for a set of specific ones. This function provides a convenient way for users to consolidate their holdings into a desired set of tokens. However, the swap incurs a fixed swap_fee and a variable slippage_fee with a minimum slippage-fee-min defined in the basket properties. The fees are calculated dynamically based on the degree to which the swap is disbalancing the basket. The greater the disbalance, the higher the "slippage" penalty will be. The slippage is a programmatic function and do not result from a changes in token value as seen in Liquidity Pools, as the value of all tokens remains constant.
A crucial aspect of the swap mechanism is that the sum of products of individual token amounts and their weights remain constant before and after the swap. This is expressed mathematically as:
This means that the cumulative value of the tokens in the basket remain unchanged (or slightly larger due to rounding errors). Any additional tokens due to the applied slippage is accounted for in the surplus, while the basket_swap_fee is be paid to the network as a fee reward. This ensures that the value of the basket remains constant, providing stability to the system.
Surplus, a Basket’s Insurance Funds
Unlike Uniswap, where swap fees are given to LP providers by issuing LP tokens proportionally, baskets swap fees paid by users and deposits from the governance are recorded in a separate surplus and do not issue additional basket tokens B<ID>/<denom>. These surplus serve as insurance funds to protect users against depeg events and can also collect any potential staking rewards yielded by aggregated tokens and "donations". In the event of a token losing its peg, the deposits, withdraws, and swaps properties of the depegged token may be set to false, and the governance will deposit the necessary amount of tokens from the surplus and/or the community treasury into the basket to re-adjust the weights, so that the remaining basket tokens B<ID>/<denom> can redeem the equivalent value in the form of all aggregate tokens. Although surplus funds are dedicated to their corresponding basket, the governance has the ability to redeem their entire content for redistribution to other baskets if necessary.
KIRA's Unique Staking Derivatives & Rewards Handling
The Token basketing module deals with a unique scenario regarding KIRA's staking derivatives V<ID>/<denom>, which accumulate block and fee rewards for their holders over time. Users pooling their V<ID>/<denom> tokens to the corresponding basket are only entitled to the block rewards accumulated by the basket on their behalf. However, it is important to note that, due to how the basket token operates, block rewards become mutualized once the derivative is pooled, meaning users may gain or lose some percentage of block rewards (compared to simply holding the individual V<ID>/<denom> itself) based on consensus nodes performance and commission rate. That being said, in KIRA, a consensus node cannot set it’s commission above 50% (or lower, depending on current network properties), hence any potential loss is minimized and should be viewed as a reasonable fee for the superior liquidity service offered by the basket.
Block Rewards: Staking derivative baskets do not track the B<ID>/<denom> holdings of individual users over time, nor do they issue new ones to account for block rewards. Instead, they accommodate the earnings from block rewards by adjusting the weight of the different V<ID>/<denom> pooled in the basket. As a result, the value that a B<ID>/<denom> can redeem for the pooled tokens increases over time as block rewards accumulate, while the total number of issued B<ID>/<denom> tokens remains unchanged.
Fee rewards: On the other hand, fee rewards are not accounted for and are simply sent to the pool's surplus insurance fund.
Parameters
Token Basket
BasketToken type
CLI syntax & examples
Each CLI command and proposal process in KIRA requires specific permissions. These permissions must be added to the account's whitelist or obtained as sudo permissions for direct changes. Refer to the
Roles & Permissions documentation for more details. $SIGNER represents the transaction signer's account name or address. For instructions on setting common flags as environment variables, such as $FLAGS_TX and $FLAGS_QR, see the
CLI flags configuration section
Governance
Transactions
sekaid tx basket
mint-basket-tokens
burn-basket-tokens
swap-basket-tokens
disable-basket-deposits
basket-claim-rewards
Deposit Aggregated Tokens
Deposit some aggregated tokens into the relevant basket using the mint-basket-tokens command and specifying the basket’s id $BASKET_ID.
Args
$BASKET_ID: Unique ID of the basket.
$DEPOSIT_AMOUNTS: Coin denomination and amount to be deposited. Single entry or comma-separated list in the format <amount><denom>.
Shell
Copy
sekaid tx basket mint-basket-tokens \
--from=$SIGNER $FLAGS_TX \
$BASKET_ID $DEPOSIT_AMOUNTS
Withdraw Aggregated Tokens
Withdraw some aggregated tokens from the relevant basket using the burn-basket-tokens command and specifying the basket’s id $BASKET_ID. This command will burn the corresponding amount of basket token $REDEMPTION.
Args
$BASKET_ID: Unique ID of the basket.
$REDEMPTION: Amount of basket token to be redeemed (burned) against some aggregated tokens in the format <amount><denom>.
Shell
Copy
sekaid tx basket burn-basket-tokens \
--from=$SIGNER $FLAGS_TX \
$BASKET_ID $REDEMPTION
Swap Basket Tokens
Swap one or many tokens within a basket for one or many other tokens using the swap-basket-tokens command, specifying the basket's id $BASKET_ID and alternating pairs of input token amounts and their corresponding desired output tokens. Ensure that for each $IN_AMOUNTn, there is a corresponding $OUT_TOKENn right after it.
Args
$BASKET_ID: Unique ID of the basket.
$IN_AMOUNTn: The amount of a token you want to swap from, where 'n' denotes the nth token. The format is <amount><denom>.
$OUT_TOKENn: The token you want to swap to, for the corresponding $IN_AMOUNT. The format is <denom>.
Bash
Copy
sekaid tx basket swap-basket-tokens \
--from=$SIGNER $FLAGS_TX \
$BASKET_ID $IN_AMOUNT1 $OUT_TOKEN1 $IN_AMOUNT2 $OUT_TOKEN2...
Disable Deposits, Withdrawals, and Swaps (emergency)
Global basket abilities can be disabled with the disable-basket-deposits, disable-basket-withdraws and disable-basket-swaps commands. It requires sudo permission
61 and by providing the basket’s id $BASKET_ID.
Args
$BASKET_ID: Unique ID of the basket.
$DISABLED: true to disable the ability.
Bash
Copy
sekaid tx basket disable-basket-deposits \
--from=$SIGNER $FLAGS_TX \
$BASKET_ID $DISABLED
Claim Derivatives Basket Rewards
Force staking derivative basket to claim outstanding rewards of one all or many aggregate V<ID> tokens using the basket-claim-rewards command and specifying the tokens $TOKENS.
Args
$TOKENS: A list of coins specifying the amount and denomination.
Bash
Copy
sekaid tx basket basket-claim-rewards \
--from=$SIGNER $FLAGS_TX \
$TOKENS
Queries
sekaid query basket
token-basket-by-denom - Query a single basket by denomination
token-basket-by-id - Query a single basket by id
token-baskets - List token baskets using filter
historical-mints - List basket historical mints performed within limits_period
historical-burns - List basket historical burns performed within limits_period
historical-swaps - List basket historical swaps performed within limits_period
Query Basket by Denomination
Retrieve a single token basket based on its denomination.
Args
$DENOM: The token denomination of the basket, formatted as B<ID>/<denom>.
Bash
Copy
sekaid query basket token-basket-by-denom $DENOM $FLAGS_QR | jq
Query Basket by ID
Retrieve details of a token basket using its unique ID.
Args
$BASKET_ID: The unique identifier of the token basket.
Bash
Copy
sekaid query basket token-basket-by-id $BASKET_ID $FLAGS_QR | jq
List Token Baskets
Retrieve token baskets by filtering them based on aggregated token denominations and staking derivatives.
Args
$DENOMS: A comma-separated list of token denominations.
$IS_DERIVATIVE: Specify if the tokens are staking derivatives (either true or false).
If $DENOMS is not provided, it returns all token baskets.
Bash
Copy
sekaid query basket token-baskets $DENOMS $IS_DERIVATIVE $FLAGS_QR | jq
Query Historical Mints
Retrieve a list of historical mints for a token basket within the specified limits_period.
Args
$BASKET_ID: The ID of the token basket.
Bash
Copy
sekaid query basket historical-mints $BASKET_ID $FLAGS_QR | jq
Query Historical Burns
Retrieve a list of historical burns for a token basket within the specified limits_period.
Args
$BASKET_ID: The ID of the token basket.
Bash
Copy
sekaid query basket historical-burns $BASKET_ID $FLAGS_QR | jq
Query Historical Swaps
Retrieve a list of historical swaps made in a token basket within the given limits_period.
Args
$BASKET_ID: The ID of the token basket.
Bash
Copy
sekaid query basket historical-swaps $BASKET_ID $FLAGS_QR | jq