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 (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.

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.

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 swaps and withdrawals.

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.