Token Rates Registrar

The Token Rate Registrar in Kira Network allows governance to whitelist foreign tokens, set exchange rates, and define limits on staking rewards distribution in order to maintain the relevance and value of KEX. This enables users to pay execution fees with any whitelisted token, providing easy onboarding for new users directly from foreign networks without requiring them to use centralized exchanges to acquire KEX or deanonymize themselves. The Token Rate Registrar also allows governance to define the distribution of incentives to maintain the relevance and value of KEX, ensuring that the native token remains attractive and desirable for users and stakeholders to hold and use. By incentivizing participation and holding, the network is able to maintain a high level of security and value.

The stake_token property determines whether or not a specific token can be used as collateral by delegators on the KIRA Network. If the stake_token property for a token is set to true, then users will be able to stake that token and earn rewards. If it is set to false, then it will not be possible to stake the token and no rewards will be distributed.

The fee_payment property determines if a given token can be used to pay transaction fees on the Kira Network, provided the enable_foreign_fee_payments network property is enabled. If the fee_payment property is set to true, then users will be able to use that token to pay transaction fees based on its fee_rate parameter, which sets the exchange rate for the token. By allowing users to pay transaction fees with a variety of different tokens, the network can be more accessible and user-friendly, providing an easy onboarding process for new users and allowing them to pay fees without having to acquire the native KEX token.

fee_rate sets the exchange rates for whitelisted tokens in terms of KEX. Token Rates Registrar is not meant to track the market price of assets accurately as this would be too much of an overhead, but rather provides an easy way to convert between tokens and KEX as a way to protect against transaction spam. For example, if the fee_rate for token u<denom> is 2, it means that 2 ukex is equal to 1 u<denom>. If the minimum fee payment, as defined by the min_tx_fee network property, is 100 ukex, then to make a transfer, the transaction fee should be set to at least 50 u<denom> tokens. Rates can also be expressed as decimals. For example, a rate of 0.1 would mean that 0.1 ukex is equal to 1 u<denom>. In this case, the minimum transaction fee payment in our example would be 1000 u<denom> tokens.

Any token eligible for staking has a corresponding stake_cap parameter which sets the maximum percentage of staking rewards that it is entitled to receive from a staking pool. For example, if the stake_cap for BTC is set to 0.1 (10%), then no matter how much BTC is staked in the pool, only 10% of incoming rewards will be allocated and shared among BTC delegators. This is to prevent a malicious user from diluting the pool with a large amount of a particular token in order to claim all the rewards for themselves. By setting specific shares for each token, the reward distribution process is made simpler and more efficient, as it eliminates the need to track the market value of the staking tokens in terms of a fiat currency such as USD or KEX.

The cumulative stake_cap for all whitelisted tokens in Token Rates Registrar cannot exceed 1.0 (100%). Any additions or updates to a token's stake_cap must adhere to this limit. If the combined reward caps surpasses 1.0, the stake_token property of any new token cannot be set to true. For tokens where stake_token is set to false, staking is not permitted—only unstaking. Such tokens also don't receive any rewards (equivalent to fee_rate of 0).

The stake_min property sets the minimum amount of token a user can delegate or undelegate per transaction to prevent a dust spam attack where a malicious user would try to massively delay the block production by adding/withdrawing small amounts of staking tokens with many different accounts (c.f Fees and staking rewards distribution).

Tokens, once registered in the Token Registrar, cannot be removed because of potential complexities when they're involved in other modules, like Consensus nodes & staking pools. To address this, an invalidated flag is available for each token entry. When this flag is set to true, it serves as a metadata signal indicating that the token is no longer active within the network, even though it doesn't impose any operational restrictions on the token itself. Conversely, when the flag is set to false, it suggests that the token remains active and can be used according to the other parameters' values.

In order to create a proposal to add or modify entries in the Token Registrar, an account must possess permission 18 or 8. Similarly, for voting on any of the Token Registrar proposals, an account must have permission 19.

The proposal-upsert-rate command can be used by accounts with permission 18 to create or update a token alias through a proposal process. To vote on an alias proposal, an account must have permission 19 .

Accounts with sudo permission 8 can use the upsert-rate CLI to create or modify token rate without a proposal.