certusone
/
cosmos-sdk
mirror of https://github.com/certusone/cosmos-sdk.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

docs/spec/staking: clean up state.md

This commit is contained in:
Ethan Buchman 2018-06-15 02:53:00 -07:00
parent cab0a9bbae
commit 1b93f468bc
1 changed files with 91 additions and 71 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

98
docs/spec/staking/state.md
View File

@ -1,15 +1,15 @@
## State ## State
### Pool ### Pool
- index: n/a single-record
- key: `01`
- value: `amino(pool)`
The pool is a space for all dynamic global state of the Cosmos Hub. It tracks The pool is a space for all dynamic global state of the Cosmos Hub. It tracks
information about the total amounts of Atoms in all states, representative information about the total amounts of Atoms in all states, representative
validator shares for stake in the global pools, moving Atom inflation validator shares for stake in the global pools, moving Atom inflation
information, etc. information, etc.
- stored object:
```golang ```golang
type Pool struct { type Pool struct {
LooseUnbondedTokens int64 // tokens not associated with any validator LooseUnbondedTokens int64 // tokens not associated with any validator
@ -32,13 +32,12 @@ type PoolShares struct {
``` ```
### Params ### Params
- index: n/a single-record - key: `00`
- value: `amino(params)`
Params is global data structure that stores system parameters and defines Params is global data structure that stores system parameters and defines
overall functioning of the stake module. overall functioning of the stake module.
- stored object:
```golang ```golang
type Params struct { type Params struct {
InflationRateChange sdk.Rat // maximum annual change in inflation rate InflationRateChange sdk.Rat // maximum annual change in inflation rate
@ -53,26 +52,34 @@ type Params struct {
### Validator ### Validator
val owner address: SDK account addresss of the owner of the validator :) Validators are identified according to the `ValOwnerAddr`,
tm val pubkey: Public Key of the Tendermint Validator an SDK account address for the owner of the validator.
- map1: <val owner address> -> <validator> Validators also have a `ValTendermintAddr`, the address
- map2: <tm val address> -> <val owner address> of the public key of the validator.
- map3: <power | block height | block tx > -> <val owner address>
map1 is the main lookup. each owner can have only one validator. Validators are indexed in the store using the following maps:
delegators point to an immutable owner
owners can change their TM val pubkey
need map2 so we can do lookups for slashing !
need map3 so we have sorted vals to know the top 100
----------- - Validators: `0x02 | ValOwnerAddr -> amino(validator)`
- ValidatorsByPubKey: `0x03 | ValTendermintAddr -> ValOwnerAddr`
- ValidatorsByPower: `0x05 | power | blockHeight | blockTx -> ValOwnerAddr`
`Validators` is the primary index - it ensures that each owner can have only one
associated validator, where the public key of that validator can change in the
future. Delegators can refer to the immutable owner of the validator, without
concern for the changing public key.
`ValidatorsByPubKey` is a secondary index that enables lookups for slashing.
When Tendermint reports evidence, it provides the validator address, so this
map is needed to find the owner.
`ValidatorsByPower` is a secondary index that provides a sorted list of
potential validators to quickly determine the current active set. For instance,
the first 100 validators in this list can be returned with every EndBlock.
The `Validator` holds the current state and some historical actions of the The `Validator` holds the current state and some historical actions of the
validator. validator.
- stored object:
```golang ```golang
type Validator struct { type Validator struct {
ConsensusPubKey crypto.PubKey // Tendermint consensus pubkey of validator ConsensusPubKey crypto.PubKey // Tendermint consensus pubkey of validator
@ -114,15 +121,16 @@ type Description struct {
### Delegation ### Delegation
- map1: < delegator address | val owner address > -> < delegation > Delegations are identified by combining `DelegatorAddr` (the address of the delegator) with the ValOwnerAddr
Delegators are indexed in the store as follows:
- Delegation: ` 0x0A | DelegatorAddr | ValOwnerAddr -> amino(delegation)`
Atom holders may delegate coins to validators; under this circumstance their Atom holders may delegate coins to validators; under this circumstance their
funds are held in a `Delegation` data structure. It is owned by one funds are held in a `Delegation` data structure. It is owned by one
delegator, and is associated with the shares for one validator. The sender of delegator, and is associated with the shares for one validator. The sender of
the transaction is the owner of the bond. the transaction is the owner of the bond.
- stored object:
```golang ```golang
type Delegation struct { type Delegation struct {
Shares sdk.Rat // delegation shares recieved Shares sdk.Rat // delegation shares recieved
@ -132,18 +140,25 @@ type Delegation struct {
### UnbondingDelegation ### UnbondingDelegation
- map1: < prefix-unbonding | delegator address | val owner address > -> < unbonding delegation > Shares in a `Delegation` can be unbonded, but they must for some time exist as an `UnbondingDelegation`,
- map2: < prefix-unbonding | val owner address | delegator address > -> nil where shares can be reduced if Byzantine behaviour is detected.
map1 for queries. `UnbondingDelegation` are indexed in the store as:
map2 for eager slashing
- UnbondingDelegationByDelegator: ` 0x0B | DelegatorAddr | ValOwnerAddr ->
amino(unbondingDelegation)`
- UnbondingDelegationByValOwner: ` 0x0C | ValOwnerAddr | DelegatorAddr | ValOwnerAddr ->
nil`
The first map here is used in queries, to lookup all unbonding delegations for
a given delegator, while the second map is used in slashing, to lookup all
unbonding delegations associated with a given validator that need to be
slashed.
A UnbondingDelegation object is created every time an unbonding is initiated. A UnbondingDelegation object is created every time an unbonding is initiated.
The unbond must be completed with a second transaction provided by the The unbond must be completed with a second transaction provided by the
delegation owner after the unbonding period has passed. delegation owner after the unbonding period has passed.
- stored object:
```golang ```golang
type UnbondingDelegation struct { type UnbondingDelegation struct {
Tokens sdk.Coins // the value in Atoms of the amount of shares which are unbonding Tokens sdk.Coins // the value in Atoms of the amount of shares which are unbonding
@ -153,16 +168,23 @@ type UnbondingDelegation struct {
### Redelegation ### Redelegation
- map1: < prefix-redelegation | delegator address | from val owner address | to Shares in a `Delegation` can be rebonded to a different validator, but they must for some time exist as a `Redelegation`,
val owner address > -> < redelegation > where shares can be reduced if Byzantine behaviour is detected. This is tracked
- map2: < prefix-redelegation | from val owner address | to as moving a delegation from a `FromValOwnerAddr` to a `ToValOwnerAddr`.
val owner address | delegator > -> nil
- map2: < prefix-redelegation | to val owner address | from
val owner address | delegator > -> nil
map1: queries `Redelegation` are indexed in the store as:
map2: slash for from validator
map3: slash for to validator - Redelegations: `0x0D | DelegatorAddr | FromValOwnerAddr | ToValOwnerAddr ->
amino(redelegation)`
- RedelegationsBySrc: `0x0E | FromValOwnerAddr | ToValOwnerAddr |
DelegatorAddr -> nil`
- RedelegationsByDst: `0x0F | ToValOwnerAddr | FromValOwnerAddr | DelegatorAddr
-> nil`
The first map here is used for queries, to lookup all redelegations for a given
delegator. The second map is used for slashing based on the FromValOwnerAddr,
while the third map is for slashing based on the ToValOwnerAddr.
A redelegation object is created every time a redelegation occurs. The A redelegation object is created every time a redelegation occurs. The
redelegation must be completed with a second transaction provided by the redelegation must be completed with a second transaction provided by the
@ -170,8 +192,6 @@ delegation owner after the unbonding period has passed. The destination
delegation of a redelegation may not itself undergo a new redelegation until delegation of a redelegation may not itself undergo a new redelegation until
the original redelegation has been completed. the original redelegation has been completed.
- stored object:
```golang ```golang
type Redelegation struct { type Redelegation struct {
SourceShares sdk.Rat // amount of source shares redelegating SourceShares sdk.Rat // amount of source shares redelegating