217 lines
13 KiB
Markdown
217 lines
13 KiB
Markdown
//TODO update .rst
|
|
|
|
# Staking Module
|
|
|
|
## Overview
|
|
|
|
The Cosmos Hub is a Tendermint-based Delegated Proof of Stake (DPos) blockchain
|
|
system that serves as a backbone of the Cosmos ecosystem. It is operated and
|
|
secured by an open and globally decentralized set of validators. Tendermint is
|
|
a Byzantine fault-tolerant distributed protocol for consensus among distrusting
|
|
parties, in this case the group of validators which produce the blocks for the
|
|
Cosmos Hub. To avoid the nothing-at-stake problem, a validator in Tendermint
|
|
needs to lock up coins in a bond deposit. Each bond's atoms are illiquid, they
|
|
cannot be transferred - in order to become liquid, they must be unbonded, a
|
|
process which will take 3 weeks by default at Cosmos Hub launch. Tendermint
|
|
protocol messages are signed by the validator's private key and are therefor
|
|
attributable. Validators acting outside protocol specifications can be made
|
|
accountable through punishing by slashing (burning) their bonded Atoms. On the
|
|
other hand, validators are rewarded for their service of securing blockchain
|
|
network by the inflationary provisions and transactions fees. This incentivizes
|
|
correct behavior of the validators and provides the economic security of the
|
|
network.
|
|
|
|
The native token of the Cosmos Hub is called the Atom; becoming a validator of the
|
|
Cosmos Hub requires holding Atoms. However, not all Atom holders are validators
|
|
of the Cosmos Hub. More precisely, there is a selection process that determines
|
|
the validator set as a subset of all validators (Atom holders that
|
|
want to become a validator). The other option for Atom holders is to delegate
|
|
their atoms to validators, i.e., being a delegator. A delegator is an Atom
|
|
holder that has put its Atoms at stake by delegating it to a validator. By bonding
|
|
Atoms to secure the network (and taking a risk of being slashed in case of
|
|
misbehaviour), a user is rewarded with inflationary provisions and transaction
|
|
fees proportional to the amount of its bonded Atoms. The Cosmos Hub is
|
|
designed to efficiently facilitate a small numbers of validators (hundreds),
|
|
and large numbers of delegators (tens of thousands). More precisely, it is the
|
|
role of the Staking module of the Cosmos Hub to support various staking
|
|
functionality including validator set selection, delegating, bonding and
|
|
withdrawing Atoms, and the distribution of inflationary provisions and
|
|
transaction fees.
|
|
|
|
## Basic Terms and Definitions
|
|
|
|
* Cosmsos Hub - a Tendermint-based Delegated Proof of Stake (DPos)
|
|
blockchain system
|
|
* Atom - native token of the Cosmsos Hub
|
|
* Atom holder - an entity that holds some amount of Atoms
|
|
* Pool - Global object within the Cosmos Hub which accounts global state
|
|
including the total amount of bonded, unbonding, and unbonded atoms
|
|
* Validator Share - Share which a validator holds to represent its portion of
|
|
bonded, unbonding or unbonded atoms in the pool
|
|
* Delegation Share - Shares which a delegation bond holds to represent its
|
|
portion of bonded, unbonding or unbonded shares in a validator
|
|
* Bond Atoms - a process of locking Atoms in a delegation share which holds them
|
|
under protocol control.
|
|
* Slash Atoms - the process of burning atoms in the pool and assoiated
|
|
validator shares of a misbehaving validator, (not behaving according to the
|
|
protocol specification). This process devalues the worth of delegation shares
|
|
of the given validator
|
|
* Unbond Shares - Process of retrieving atoms from shares. If the shares are
|
|
bonded the shares must first remain in an inbetween unbonding state for the
|
|
duration of the unbonding period
|
|
* Redelegating Shares - Process of redelegating atoms from one validator to
|
|
another. This process is instantaneous, but the redelegated atoms are
|
|
retrospecively slashable if the old validator is found to misbehave for any
|
|
blocks before the redelegation. These atoms are simultaniously slashable
|
|
for any new blocks which the new validator misbehavess
|
|
* Validator - entity with atoms which is either actively validating the Tendermint
|
|
protocol (bonded validator) or vying to validate .
|
|
* Bonded Validator - a validator whose atoms are currently bonded and liable to
|
|
be slashed. These validators are to be able to sign protocol messages for
|
|
Tendermint consensus. At Cosmos Hub genesis there is a maximum of 100
|
|
bonded validator positions. Only Bonded Validators receive atom provisions
|
|
and fee rewards.
|
|
* Delegator - an Atom holder that has bonded Atoms to a validator
|
|
* Unbonding period - time required in the unbonding state when unbonding
|
|
shares. Time slashable to old validator after a redelegation. Time for which
|
|
validators can be slashed after an infraction. To provide the requisite
|
|
cryptoeconomic security guarantees, all of these must be equal.
|
|
* Atom provisions - The process of increasing the Atom supply. Atoms are
|
|
periodically created on the Cosmos Hub and issued to bonded Atom holders.
|
|
The goal of inflation is to incentize most of the Atoms in existence to be
|
|
bonded. Atoms are distributed unbonded and using the fee_distribution mechanism
|
|
* Transaction fees - transaction fee is a fee that is included in a Cosmsos Hub
|
|
transaction. The fees are collected by the current validator set and
|
|
distributed among validators and delegators in proportion to their bonded
|
|
Atom share
|
|
* Commission fee - a fee taken from the transaction fees by a validator for
|
|
their service
|
|
|
|
## The pool and the share
|
|
|
|
At the core of the Staking module is the concept of a pool which denotes a
|
|
collection of Atoms contributed by different Atom holders. There are three
|
|
pools in the Staking module: the bonded, unbonding, and unbonded pool. Bonded
|
|
Atoms are part of the global bonded pool. If a validator or delegator wants to
|
|
unbond its shares, these Shares are moved to the the unbonding pool for the
|
|
duration of the unbonding period. From here normally Atoms will be moved
|
|
directly into the delegators wallet, however under the situation thatn an
|
|
entire validator gets unbonded, the Atoms of the delegations will remain with
|
|
the validator and moved to the unbonded pool. For each pool, the total amount
|
|
of bonded, unbonding, or unbonded Atoms are tracked as well as the current
|
|
amount of issued pool-shares, the specific holdings of these shares by
|
|
validators are tracked in protocol by the validator object.
|
|
|
|
A share is a unit of Atom distribution and the value of the share
|
|
(share-to-atom exchange rate) can change during system execution. The
|
|
share-to-atom exchange rate can be computed as:
|
|
|
|
`share-to-atom-exchange-rate = size of the pool / ammount of issued shares`
|
|
|
|
Then for each validator (in a per validator data structure) the protocol keeps
|
|
track of the amount of shares the validator owns in a pool. At any point in
|
|
time, the exact amount of Atoms a validator has in the pool can be computed as
|
|
the number of shares it owns multiplied with the current share-to-atom exchange
|
|
rate:
|
|
|
|
`validator-coins = validator.Shares * share-to-atom-exchange-rate`
|
|
|
|
The benefit of such accounting of the pool resources is the fact that a
|
|
modification to the pool from bonding/unbonding/slashing of Atoms affects only
|
|
global data (size of the pool and the number of shares) and not the related
|
|
validator data structure, i.e., the data structure of other validators do not
|
|
need to be modified. This has the advantage that modifying global data is much
|
|
cheaper computationally than modifying data of every validator. Let's explain
|
|
this further with several small examples:
|
|
|
|
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
|
|
XXX TODO make way less verbose lets use bullet points to describe the example
|
|
XXX Also need to update to not include bonded atom provisions all atoms are
|
|
XXX redistributed with the fee pool now
|
|
|
|
We consider initially 4 validators p1, p2, p3 and p4, and that each validator
|
|
has bonded 10 Atoms to the bonded pool. Furthermore, let's assume that we have
|
|
issued initially 40 shares (note that the initial distribution of the shares,
|
|
i.e., share-to-atom exchange rate can be set to any meaningful value), i.e.,
|
|
share-to-atom-ex-rate = 1 atom per share. Then at the global pool level we
|
|
have, the size of the pool is 40 Atoms, and the amount of issued shares is
|
|
equal to 40. And for each validator we store in their corresponding data
|
|
structure that each has 10 shares of the bonded pool. Now lets assume that the
|
|
validator p4 starts process of unbonding of 5 shares. Then the total size of
|
|
the pool is decreased and now it will be 35 shares and the amount of Atoms is
|
|
35 . Note that the only change in other data structures needed is reducing the
|
|
number of shares for a validator p4 from 10 to 5.
|
|
|
|
Let's consider now the case where a validator p1 wants to bond 15 more atoms to
|
|
the pool. Now the size of the pool is 50, and as the exchange rate hasn't
|
|
changed (1 share is still worth 1 Atom), we need to create more shares, i.e. we
|
|
now have 50 shares in the pool in total. Validators p2, p3 and p4 still have
|
|
(correspondingly) 10, 10 and 5 shares each worth of 1 atom per share, so we
|
|
don't need to modify anything in their corresponding data structures. But p1
|
|
now has 25 shares, so we update the amount of shares owned by p1 in its
|
|
data structure. Note that apart from the size of the pool that is in Atoms, all
|
|
other data structures refer only to shares.
|
|
|
|
Finally, let's consider what happens when new Atoms are created and added to
|
|
the pool due to inflation. Let's assume that the inflation rate is 10 percent
|
|
and that it is applied to the current state of the pool. This means that 5
|
|
Atoms are created and added to the pool and that each validator now
|
|
proportionally increase it's Atom count. Let's analyse how this change is
|
|
reflected in the data structures. First, the size of the pool is increased and
|
|
is now 55 atoms. As a share of each validator in the pool hasn't changed, this
|
|
means that the total number of shares stay the same (50) and that the amount of
|
|
shares of each validator stays the same (correspondingly 25, 10, 10, 5). But
|
|
the exchange rate has changed and each share is now worth 55/50 Atoms per
|
|
share, so each validator has effectively increased amount of Atoms it has. So
|
|
validators now have (correspondingly) 55/2, 55/5, 55/5 and 55/10 Atoms.
|
|
|
|
The concepts of the pool and its shares is at the core of the accounting in the
|
|
Staking module. It is used for managing the global pools (such as bonding and
|
|
unbonding pool), but also for distribution of Atoms between validator and its
|
|
delegators (we will explain this in section X).
|
|
|
|
#### Delegator shares
|
|
|
|
A validator is, depending on its status, contributing Atoms to either the
|
|
unbonding or unbonded pool - the validator in turn holds some amount of pool
|
|
shares. Not all of a validator's Atoms (and respective shares) are necessarily
|
|
owned by the validator, some may be owned by delegators to that validator. The
|
|
mechanism for distribution of Atoms (and shares) between a validator and its
|
|
delegators is based on a notion of delegator shares. More precisely, every
|
|
validator is issuing (local) delegator shares
|
|
(`Validator.IssuedDelegatorShares`) that represents some portion of global
|
|
shares managed by the validator (`Validator.GlobalStakeShares`). The principle
|
|
behind managing delegator shares is the same as described in [Section](#The
|
|
pool and the share). We now illustrate it with an example.
|
|
|
|
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
|
|
XXX TODO make way less verbose lets use bullet points to describe the example
|
|
XXX Also need to update to not include bonded atom provisions all atoms are
|
|
XXX redistributed with the fee pool now
|
|
|
|
Let's consider 4 validators p1, p2, p3 and p4, and assume that each validator
|
|
has bonded 10 Atoms to the bonded pool. Furthermore, let's assume that we have
|
|
issued initially 40 global shares, i.e., that
|
|
`share-to-atom-exchange-rate = 1 atom per share`. So we will set
|
|
`GlobalState.BondedPool = 40` and `GlobalState.BondedShares = 40` and in the
|
|
Validator data structure of each validator `Validator.GlobalStakeShares = 10`.
|
|
Furthermore, each validator issued 10 delegator shares which are initially
|
|
owned by itself, i.e., `Validator.IssuedDelegatorShares = 10`, where
|
|
`delegator-share-to-global-share-ex-rate = 1 global share per delegator share`.
|
|
Now lets assume that a delegator d1 delegates 5 atoms to a validator p1 and
|
|
consider what are the updates we need to make to the data structures. First,
|
|
`GlobalState.BondedPool = 45` and `GlobalState.BondedShares = 45`. Then, for
|
|
validator p1 we have `Validator.GlobalStakeShares = 15`, but we also need to
|
|
issue also additional delegator shares, i.e.,
|
|
`Validator.IssuedDelegatorShares = 15` as the delegator d1 now owns 5 delegator
|
|
shares of validator p1, where each delegator share is worth 1 global shares,
|
|
i.e, 1 Atom. Lets see now what happens after 5 new Atoms are created due to
|
|
inflation. In that case, we only need to update `GlobalState.BondedPool` which
|
|
is now equal to 50 Atoms as created Atoms are added to the bonded pool. Note
|
|
that the amount of global and delegator shares stay the same but they are now
|
|
worth more as share-to-atom-exchange-rate is now worth 50/45 Atoms per share.
|
|
Therefore, a delegator d1 now owns:
|
|
|
|
`delegatorCoins = 5 (delegator shares) * 1 (delegator-share-to-global-share-ex-rate) * 50/45 (share-to-atom-ex-rate) = 5.55 Atoms`
|
|
|