Understanding basic staking operations on Cosmos Blockchain

What is Staking? According to Coinbase learn

Staking serves a similar function to mining, in that it’s the process by which a network participant gets selected to add the latest batch of transactions to the blockchain and earn some crypto in exchange. Stakers also help establish which blocks are valid.

Staking is generally open to anyone who wants to participate. That said, becoming a full validator can require a minimum number of tokens, technical knowledge, and a dedicated computer that can perform validations day or night without downtime.

In order to simplify things users can delegate their tokens to a validator and still earn rewards without setting their own complicated infrastructure.

I’ve been exploring the Cosmos ecosystem for some time playing around with their Staking APIs. The Cosmos documentation is not that easy to understand and very spread throughout for someone who just wants to understand what is going on when users are executing different staking APIs. In this article, I will attempt to simplify those operations.

Cosmos staking consists of a bunch of operations but I will focus on the following:

1. Delegate: Delegates funds to a validator

2. Undelegate: Undelegate token from a validator

3. Withdraw Reward: Withdraws rewards which are generated by delegating tokens

4. Redelegate: Change the validator for the delegated tokens

Before we go into each operation in detail, there’s this concept of ModuleAccount which Cosmos based chains follow. These accounts are defined in the genesis file so whenever someone wants to run their own validator they would use this genesis file to set up the module account. For delegation purpose, there are three accounts that are important to us

• BONDED_TOKEN_POOL: When you delegate to a validator, the balance of these accounts increases.

• NON_BONDED_TOKEN_POOL: When you undelegate funds, the balance of this account increases (and the balance of the BONDED_TOKEN_POOL account decreases with the same amount). Your undelegated amount remains in this account till the bonding period passes.

• DISTRIBUTION: This account holds the rewards balance until a reward is withdrawn and the balance of this account gets decreased.

For cosmos mainnet

• BONDED_TOKEN_POOL: cosmos1fl48vsnmsdzcv85q5d2q4z5ajdha8yu34mf0eh

• NON_BONDED_TOKEN_POOL: cosmos1tygms3xhhs3yv487phx3dw4a95jn7t7lpm470r

• DISTRIBUTION: cosmos1jv65s3grqf6v6jl3dp4t6c9t9rk99cd88lyufl

Let’s deep dive into each of the operations.

Delegate

This operation is used to delegate tokens to a validator. It required a delegator address, validator address, and the number of tokens. Here’s how the message looks like

msgDeledate := staking.MsgDelegate {
    DelegatorAddress: "cosmos1yvtps9pzmr2wslyq3zv2zk5hn29eestlekwhsx",
    ValidatorAddress: "cosmosvaloper1sjllsnramtg3ewxqwwrwjxfgc4n4ef9u2lcnj0",
    Amount: "4000000uatom"
}

When we execute this transaction, the available balance gets reduced by the amount and it goes to the staked amount. Under the hood, the balance of the BONDED_TOKEN_POOL account increases by the same amount as tokens are transferred to this account.

Since the delegation has started, the rewards will keep accumulating in the DISTRIBUTION account and we will see that in the delegator’s account Staking Rewards balance.

Account

There’s another case, where the delegator account has an unclaimed reward. In addition to new delegation, the rewards will be auto claimed and the tokens will move from DISTRIBUTION account to the delegator account increasing the available balance of the delegator account.

Undelegate

This operation is used to undelegate the tokens from the validator. It requires a delegator address, a validator address, and an amount. Here’s how the message looks like

msgUndeledate := staking.MsgUndelegate {
    DelegatorAddress: "cosmos1yvtps9pzmr2wslyq3zv2zk5hn29eestlekwhsx",
    ValidatorAddress: "cosmosvaloper156gqf9837u7d4c4678yt3rl4ls9c5vuursrrzf",
    Amount: "564960243uatom"
}

When you execute this transaction, the token goes from BONDED_TOKEN_POOL to NON_BONDED_TOKEN_POOL, which increases the balance of NON_BONDED_TOKEN_POOL and decreases the balance of BONDED_TOKEN_POOL.

For a delegator, the staked balance gets decreased by the amount and the unbonded balance gets increased by the same amount. This doesn’t have any effect on the available balance. But if there’s a pending reward to be claimed, the reward will be auto-claimed and you will observe a similar behavior like Delegate.

After the Bonding period (21 days), the delegator’s available balance gets increased by the amount and the unbonded address gets decreased by the same amount. Tokens get moved from NON_BONDED_TOKEN_POOL to delegator.

Withdraw Reward

This operation is used to withdraw the current staking reward amount. It requires a delegator address and a validator address. Here’s how the message looks like

msgWithdraw := staking.MsgWithdrawDelegatorReward {
    DelegatorAddress: "cosmos1yvtps9pzmr2wslyq3zv2zk5hn29eestlekwhsx",
    ValidatorAddress: "cosmosvaloper156gqf9837u7d4c4678yt3rl4ls9c5vuursrrzf"
}

When we execute this transaction, the tokens are transferred from DISTRIBUTION account to the delegator address and the available balance of the delegator account gets increased by the rewards amount.

Redelegate

This operation is used to change the validator for delegating the tokens. It requires a delegator address, a source validation, a destination validator, and an amount. Here’s how the message looks like

msgRedelegate := staking.MsgBeginRedelegate {
    DelegatorAddress: "cosmos15t8tzmaevw063e7lud65dzr3sd74gn07uf3h8l",
    ValidatorSrcAddress: "cosmosvaloper1tflk30mq5vgqjdly92kkhhq3raev2hnz6eete3",
    ValidatorDstAddress: "cosmosvaloper1tflk30mq5vgqjdly92kkhhq3raev2hnz6eete3",
    Amount: "1000000uatom"
}

When we execute this transaction, there is no balance change in the Module accounts as we are redelegating the tokens. We just delegate that token amount to a new validator. In this event, we also auto-claim any existing reward like any other auto-claim event.

In case you want to understand more, check all the transactions listed in all operations and you will be able to see all the events in detail.

This is just the tip of the iceberg on what you can do in cosmos staking, but I hope this was helpful and makes clear how basic staking works in the Comsos realm.

---

I also write on Medium. Please subscribe if you prefer that.