Search
Duplicate
Try Notion
🚧🚧
Delegators
Concept
Delegators are KIRA token holders who want to participate in network security by delegating assets as collateral to one or more consensus nodes' staking pools in exchange for a share of their revenue. Because delegators share revenue and responsibility with their chosen consensus nodes, they should carefully consider which nodes to delegate to and monitor their stakes regularly. Consensus nodes can also be delegators, but they are not required to. Staked assets are directly affected by the conduct of the elected nodes, so it is important for delegators to exercise diligence and diversification in their choices.
Native liquid staking
Consensus nodes on the Kira Network have staking pools that are designed equivalently to regular AMM liquidity pools like Uniswap, in order to achieve native liquid staking. When a certain number of tokens XYZ are deposited in the staking pool of a consensus node V1, an equal number of derivative tokens V1_XYZ are issued in return (similar to AMM LP tokens). These derivative tokens V1_XYZ can be freely moved and traded on and off-chain, while the underlying XYZ tokens remain staked. If V1 is slashed for double signing, the staked XYZ tokens can either be moved to the treasury, a governance spending pool or destroyed, while the derivative tokens V1_XYZ representing them would lose their 1-to-1 peg (similar to impermanent loss in AMM).
E.g.: If 50% of XYZ tokens staked with block proposer V1 get slashed, unstaking 2 V1_XYZ from V1's pool would only return 1 XYZ.
💡
Staking pools & consensus nodes status
In KIRA's network, each consensus node operates its own staking pool where delegators can stake their assets. The staking pool has a unique ID and is linked to the consensus node's address. The consensus node has control over the staking pool's status and can enable or disable it, as well as set the commission rate on block rewards. In addition, a consensus node can be active, inactive, paused, or jailed depending on its performance, behavior or choice. While it is important to understand that the status of the staking pool is independent of the status of the consensus node, if a consensus node's status is inactive, paused, or jailed , and/or if its staking pool is disabled, delegators are not able to delegate any additional tokens to that node’s staking pool. They will only be able to undelegate their existing stake.
For more information regarding consensus nodes status and ranking system please refer to the Consensus nodes ranks & statuses module. For more information regarding consensus nodes staking pool status please refer to the 🚧Consensus nodes & staking pools section.
Token Rate Registrar parameters
KIRA allows users to delegate and pay execution fees with any token that has been whitelisted by governance. To ensure proper network functionality and security, specific management rules and limitations are defined and curated for each foreign token, such as exchange rates and staking pool rewards allowance. These rules are monitored by the Token Rate Registrar module, which sets bounds on the staking mechanism through the use of three parameters:
stake_cap : Sets the maximum share (%) of staking reward a given token will be entitled per staking pool to prevent a malicious user from diluting the pool with any particular token in order to claim all the rewards. Setting specific shares also simplifies reward distribution by sidestepping the need to track how much eligible staking tokens are worth in terms of USD or KEX.
stake_min : Sets the minimum delegation and undelegation amount per transaction for a given token to prevent a dust spam attack where a malicious user would try to massively delay the block production by adding/withdrawing small amounts of tokens eligible for staking with many different accounts (c.f 🚧Fees and staking rewards distribution).
fee_rate : Sets the conversation rate for foreign tokens in terms of KEX to use them as execution fees. fee_rate is also used to determine if the stake_min value is respected in case of delegation or if min_delegation_pushout is reached when a staking pool reaches its maximum delegators capacity.
For more information regarding delegators staking rewards distribution please refer to this section of the 🚧Fees and staking rewards distribution module.
Staking pool registration rewards eligibility
Owning some staking pool's derivatives V1_XYZ is equivalent to having some token XYZ staked with consensus node V1. However, because the Cosmos SDK does not provide a hook on token transfers (yet?) and derivatives can be traded freely inside or outside the KIRA network, it is impossible to track staking pool delegators' shares in real time. To solve this problem, KIRA has implemented a registration mechanism where "offshore" delegators, such as users or smart contracts that acquired or received KIRA's native staking derivative tokens on the open market, can register those derivatives to the corresponding staking pool to earn rewards. Additionally, each staking pool performs a balance check on its current delegators whenever it receives rewards (whenever the consensus nodes produces a block) and will automatically deregister any registered delegators that do not hold more than the minimum stake_min of derivative tokens.
Rewards claiming & auto-compounding
Delegators can enable or disable the auto compounding mode for any token eligible for staking (as determined by the Token Rates Registrar). When enabled, rewards are automatically added to the delegator's stake. However, the corresponding staking derivatives are not sent to the delegator's address, as this would be too much of an overhead for the module to handle. Instead, they are simply accumulated in the staking pool and become claimable in the same way as rewards. In other words, when a user disables auto compounding, it will have to claim its rewards manually; when it is enabled, it will have to claim its newly issued staking derivatives manually.
Delegators push out
KIRA has a feature that protects against dust spam attacks by limiting the maximum number of delegators for each individual staking pool with a network property called max_delegators (which is set to 100 by default). If this maximum number of delegators is reached, new delegators will need to provide a higher stake than the smallest delegator in the pool in order to push them out. To prevent large stakeholders from easily pushing out smaller delegators from good consensus nodes, the minimum required stake to push out a delegator is set by the min_delegation_pushout property (which is a multiplier of the smallest stake value, 10 by default). This network property can be adjusted by KIRA's governance and increased as the network grows. When a delegator is pushed out, they automatically receive any outstanding rewards they are owed.
Unstaking & cooling period
A delegator can undelegate their stake at anytime to get back its original tokens. Any undelegation will trigger a fixed cooling period during which the stake remain locked and do not yield any reward. Once the cooling period expires, staked tokens XYZ can be claimed by providing the respective pool’s derivative V_XYZ which are then burned. The cooling period is the same for all staking tokens and defined by the governance through the following unstaking_period network property (1 month by default).
CLI functions description
x/multistaking
delegate - Delegate to a pool.
undelegate - Start undelegation from a pool.
claim-rewards - Claim rewards from a pool.
claim-undelegation - Claim matured undelegation.
set-compound-info - Set auto compounding mode.
register-delegator - Register as a pool delegator when acquiring pool derivatives externally.
query/multistaking
undelegations - Query all the undelegation records.
staking-pool-delegators - Query staking pool delegators.
compound-info - Query compound information of a delegator.
outstanding-rewards - Query outstanding rewards for a delegator.
pools - Query all existing staking pools and return their respective parameters (commission …) and current metrics (total staked tokens, total accumulated rewards, …)
query-delegations - Query all delegations and rewards by a delegator address and specific pool id / consensus node’s address
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
Delegatating / Undelegating
delegate locks <denom> token to a specific staking pool using the consensus node’s address and immediately return back the corresponding pool’s derivative V<id>_<denom> (<id> beeing the pool’s id). The total amount to be delegated cannot be lower than stake_min as defined by The token rates registrar or the transaction will fail. Consensus node’s address can be obtain using the validator/validators queries. Note that it is only possible to delegate to an active consensus node.
$VAL*
string
Consensus node’s address kiravaloper...
$COIN*
string
Comma-separated list of coins and their respective amount to delegate/undelegate in the format <amount><denom> (e.g. 20000ukex)
Bash
Copy
sekaid tx multistaking delegate \ --from=$SIGNER $FLAGS_TX \ $VAL $COIN
​
Bash
Copy
# Example sekaid tx multistaking delegate \ --from=$SIGNER $FLAGS_TX \ kiravaloper1h3f7w7ekjnpfcyjhktq06n4rl8yued9a0ap468 20000ukex
​
Undelegating burns corresponding V<id>_<denom> derivatives and triggers all outstanding rewards/compounds claims. Corresponding undelegated <denom> tokens are assigned with an undelegation ID which becomes claimable at the end of the unstaking_period (default : 1 month). The minimum amount to be undelegated cannot be lower than stake_min as defined by The token rates registrar and the remaining amount of shares in the balances should also NOT be smaller then stake_min otherwise the transaction will fail.
Bash
Copy
sekaid tx multistaking undelegate \ --from=$SIGNER $FLAGS_TX \ $VAL $COIN
​
Set compounding mode
Delegators can enable/disable auto compounding for one or all tokens using set-compound-info.
$ALL*
bool
Set compound mode on all tokens if set to true
$DENOM*
string
Set compound mode on the token <denom> (e.g. ukex)
Bash
Copy
sekaid tx multistaking set-compound-info \ --from=$SIGNER $FLAGS_TX \ $ALL $DENOM
​
Bash
Copy
# Example (setting auto compound only for ukex) sekaid tx multistaking set-compound-info \ --from=$SIGNER $FLAGS_TX \ false ukex
​
Claim rewards/derivatives & undelegations
All outstanding rewards (or corresponding derivatives if compounding is enabled) for a given delegator (signer) can be claimed using claim-rewards.
Bash
Copy
sekaid tx multistaking claim-rewards \ --from=$SIGNER $FLAGS_TX
​
Undelegations can be claimed using corresponding delegation ID and at the end of their respective unstaking_period.
$ID*
int
Undelegation ID
Bash
Copy
sekaid tx multistaking claim-undelegation \ --from=$SIGNER $FLAGS_TX \ $ID
​
Delegator registration
Users (or smart contracts) who acquired KIRA’s native staking derivative token in the open market can register as delegators to all respective staking pool using register-delegator. Only derivatives which respect their respective minimum staking amount requirement stake_min defined by the The token rates registrar will be eligible for staking.
Bash
Copy
sekaid tx multistaking register-delegator \ --from=$SIGNER $FLAGS_TX
​
Queries syntax & examples
$VAL*
string
Validator node’s address kiravaloper...
$DEL*
string
Delegator’s address
List information of a specific staking pool and all its delegators
All delegators of a specific staking pool (determined by the staking pool nodes address) can be obtain using the staking-pool-delegators query.
Bash
Copy
sekaid query multistaking staking-pool-delegators $VAL $FLAGS_QR | jq
​
List all staking pool information
All existing staking pools real time metrics and their respective parameters can be queried using the following CLI.
Bash
Copy
sekaid query multistaking pools $FLAGS_QR | jq
​
All pending undelegations
Pending undelegations information (ID …) can be obtain using the undelegations query.
Bash
Copy
sekaid query multistaking undelegations $FLAGS_QR | jq
​
Compounding information
Compounding information for a given delegator can be retrieved using the compound-info query.
$DEL*
bool
Delegator’s address
Bash
Copy
sekaid query multistaking compound-info $DEL $FLAGS_QR | jq
​
Oustanding rewards
All outstanding rewards for a given delegator can be retrieved using the outstanding-rewards query.
Bash
Copy
sekaid query multistaking outstanding-rewards $DEL $FLAGS_QR | jq
​