# Staking Module

## Basic Terms and Definitions

- Cosmsos Hub - a Tendermint-based Proof of Stake blockchain system
- Atom - native token of the Cosmsos Hub
- Atom holder - an entity that holds some amount of Atoms 
- Candidate - an Atom holder that is actively involved in Tendermint blockchain protocol (running Tendermint Full Node
TODO: add link to Full Node definition) and is competing with other candidates to be elected as a Validator 
(TODO: add link to Validator definition))
- Validator - a candidate that is currently selected among a set of candidates to be able to sign protocol messages 
in the Tendermint consensus protocol 
- Delegator - an Atom holder that has bonded any of its Atoms by delegating them to a validator (or a candidate) 
- Bonding Atoms - a process of locking Atoms in a bond deposit (putting Atoms under protocol control).
Atoms are always bonded through a validator (or candidate) process. Bonded atoms can be slashed (burned) in case a 
validator process misbehaves (does not behave according to a protocol specification). Atom holder can regain access 
to its bonded Atoms (if they are not slashed in the meantime), i.e., they can be moved to its account, 
after Unbonding period has expired. 
- Unbonding period - a period of time after which Atom holder gains access to its bonded Atoms (they can be withdrawn 
to a user account) or they can re-delegate  
- Inflationary provisions - inflation is a process of increasing Atom supply. Atoms are being created in the process of 
(Cosmos Hub) blocks creation. Owners of bonded atoms are rewarded for securing network with inflationary provisions 
proportional to it's bonded Atom share.
- Transaction fees - transaction fee is a fee that is included in the Cosmsos Hub transactions. The fees are collected 
by the current validator set and distributed among validators and delegators in proportion to it's bonded Atom share.       
- Commission fee - a fee taken from the transaction fees by a validator for it's service 

## The pool and the share

At the core of the Staking module is the concept of a pool which denotes collection of Atoms contributed by different 
Atom holders. There are two global pools in the Staking module: bonded pool and unbonded pool. Bonded Atoms are part 
of the global bonded pool. On the other side, if a candidate or delegator wants to unbond its Atoms, those Atoms are 
kept in the unbonding pool for a duration of the unbonding period. In the Staking module, a pool is logical concept, 
i.e., there is no pool data structure that would be responsible for managing pool resources. Instead, it is managed 
in a distributed way. More precisely, at the global level, for each pool, we track only the total amount of 
(bonded or unbonded) Atoms and a current amount of issued shares. A share is a unit of Atom distribution and the 
value of the share (share-to-atom exchange rate) is changing during the system execution. The 
share-to-atom exchange rate can be computed as:

`share-to-atom-ex-rate = size of the pool / ammount of issued shares`

Then for each candidate (in a per candidate data structure) we keep track of an amount of shares the candidate is owning 
in a pool. At any point in time, the exact amount of Atoms a candidate has in the pool
can be computed as the number of shares it owns multiplied with the share-to-atom exchange rate:

`candidate-coins = candidate.Shares * share-to-atom-ex-rate`

The benefit of such accounting of the pool resources is the fact that a modification to the pool because of 
bonding/unbonding/slashing/provisioning of atoms affects only global data (size of the pool and the number of shares) 
and the related validator/candidate data structure, i.e., the data structure of other validators do not need to be 
modified. Let's explain this further with several small examples: 

We consider initially 4 validators p1, p2, p3 and p4, and that each validator has bonded 10 Atoms 
to a 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 the 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 candidate is, depending on it's status, contributing Atoms to either the bonded or unbonded pool, and in return gets  
some amount of (global) pool shares. Note that not all those Atoms (and respective shares) are owned by the candidate 
as some Atoms could be delegated to a candidate. The mechanism for distribution of Atoms (and shares) between a 
candidate and it's delegators is based on a notion of delegator shares. More precisely, every candidate is issuing 
(local) delegator shares (`Candidate.IssuedDelegatorShares`) that represents some portion of global shares 
managed by the candidate (`Candidate.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.

Lets consider 4 validators p1, p2, p3 and p4, and assume that each validator has bonded 10 Atoms to a bonded pool. 
Furthermore, lets assume that we have issued initially 40 global shares, i.e., that `share-to-atom-ex-rate = 1 atom per 
share`. So we will `GlobalState.BondedPool = 40` and `GlobalState.BondedShares = 40` and in the Candidate data structure 
of each validator `Candidate.GlobalStakeShares = 10`. Furthermore, each validator issued 10 delegator 
shares which are initially owned by itself, i.e., `Candidate.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 `Candidate.GlobalStakeShares = 15`, but we also need to issue also additional delegator shares, 
i.e., `Candidate.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-ex-rate is now worth 50/45 Atoms per share. Therefore, a delegator d1 now owns 

`delegatorCoins = 10 (delegator shares) * 1 (delegator-share-to-global-share-ex-rate) * 50/45 (share-to-atom-ex-rate) = 100/9 Atoms`