Token Basketing Module

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.

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, Token A and Token B, both collateralized by the same underlying asset have different numbers of decimal places (e.g. Token A has 3 decimal places, Token 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 Token A and a weight of 0.01 to Token B. This means that 1 unit of Token A is equal to 100 units of Token B, and the basket will be expressed in terms of Token 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 $\small \left(A_{amount} \times A_{weight}\right) + \left(B_{amount} \times B_{weight}\right) + \left(C_{amount} \times C_{weight}\right) \geq B_{<ID>\_<denom>.total\_amount\_issued}$. If the weights are not correctly configured, the governance proposal to update the basket weights will fail.

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.

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.

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.

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 B5/ABC tokens.

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.

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.

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.

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.

In order to create a proposal to add or modify entries in the Token Baskets module, an account must possess permission 59. Similarly, for voting on any of these proposals, an account must have permission 60. Additionally, permission 61 allows to perform some emergency actions on existing baskets.

TODO

Retrieve a single token basket based on its basket ID.

$BASKET_ID: The unique identifier of the token basket. The ID should be a positive integer.

Retrieve a single token basket based on its denomination B<ID>/<denom>.

$DENOM: The token denomination of the basket.

Retrieve token baskets based on a list of aggregated token denominations they carry and filter by staking derivatives.

$DENOMS: A comma-separated list of token denominations to filter the token baskets <denom>,....

$IS_DERIVATIVE: A boolean value that specifies whether the tokens should be staking derivatives or not. Accepts true or false.

Retrieve the historical mints (aggregated token deposits) of a token basket made within the past limits_period. Note that any older activity is automatically deleted.

$BASKET_ID: The unique identifier of the token basket. The ID should be a positive integer.

Retrieve the historical burns (aggregated token withdrawals) of a token basket made within the past limits_period. Note that any older activity is automatically deleted.

$BASKET_ID: The unique identifier of the token basket. The ID should be a positive integer.

Retrieve the historical swaps performed for a token basket within the past limits_period. Note that any older activity is automatically deleted.

$BASKET_ID: The unique identifier of the token basket. The ID should be a positive integer.