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

Merge PR #4599: Supply module spec 

* supply spec

* update spec

* update other modules

* update distr

* update spec according to latest refactors

* Apply suggestions from code review

Co-Authored-By: Alexander Bezobchuk <alexanderbez@users.noreply.github.com>

* updated spec

* Apply suggestions from code review

Co-Authored-By: Marko <marbar3778@yahoo.com>

* final updates

* Apply suggestions from code review

Co-Authored-By: Alessio Treglia <quadrispro@ubuntu.com>

* word wrap in supply concepts

* edits to concepts
This commit is contained in:
Federico Kunze 2019-07-01 18:47:55 +02:00 committed by frog power 4000
parent ce0c0946b6
commit 5d5f0149a4
16 changed files with 356 additions and 303 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
docs/spec/README.md
View File

@ -6,12 +6,12 @@ SDK applications hold this state in a Merkle store. Updates to
the store may be made during transactions and at the beginning and end of every
block.
### SDK specifications:
## SDK specifications
- [Store](./store) - The core Merkle store that holds the state.
- [Bech32](./addresses/bech32.md) - Address format for Cosmos SDK applications.
### Modules specifications:
## Modules specifications
- [Auth](./auth) - The structure and authentication of accounts and transactions.
- [Bank](./bank) - Sending tokens.
@ -23,11 +23,11 @@ block.
- [Mint](./mint) - Staking token provision creation.
- [Params](./params) - Globally available parameter store.
- [IBC](./ibc) - Inter-Blockchain Communication (IBC) protocol.
- [Supply](./supply) - Total supply of the chain.
### Interchain standards
## Interchain standards
- [ICS30](./_ics/ics-030-signed-messages.md) - Signed messages standard.
-
For details on the underlying blockchain and p2p protocols, see
the [Tendermint specification](https://github.com/tendermint/tendermint/tree/develop/docs/spec).

35
docs/spec/distribution/02_state.md
View File

@ -1,20 +1,20 @@
## State
# State
### FeePool
## FeePool
All globally tracked parameters for distribution are stored within
`FeePool`. Rewards are collected and added to the reward pool and
distributed to validators/delegators from here.
distributed to validators/delegators from here.
Note that the reward pool holds decimal coins (`DecCoins`) to allow
for fractions of coins to be received from operations like inflation.
When coins are distributed from the pool they are truncated back to
`sdk.Coins` which are non-decimal.
Note that the reward pool holds decimal coins (`DecCoins`) to allow
for fractions of coins to be received from operations like inflation.
When coins are distributed from the pool they are truncated back to
`sdk.Coins` which are non-decimal.
- FeePool: `0x00 -> amino(FeePool)`
- FeePool: `0x00 -> amino(FeePool)`
```golang
// coins with decimal
// coins with decimal
type DecCoins []DecCoin
type DecCoin struct {
@ -30,15 +30,16 @@ type FeePool struct {
}
```
### Validator Distribution
## Validator Distribution
Validator distribution information for the relevant validator is updated each time:
1. delegation amount to a validator is updated,
1. delegation amount to a validator is updated,
2. a validator successfully proposes a block and receives a reward,
3. any delegator withdraws from a validator, or
3. any delegator withdraws from a validator, or
4. the validator withdraws it's commission.
- ValidatorDistInfo: `0x02 | ValOperatorAddr -> amino(validatorDistribution)`
- ValidatorDistInfo: `0x02 | ValOperatorAddr -> amino(validatorDistribution)`
```golang
type ValidatorDistInfo struct {
@ -51,15 +52,15 @@ type ValidatorDistInfo struct {
}
```
### Delegation Distribution
## Delegation Distribution
Each delegation distribution only needs to record the height at which it last
withdrew fees. Because a delegation must withdraw fees each time it's
properties change (aka bonded tokens etc.) its properties will remain constant
and the delegator's _accumulation_ factor can be calculated passively knowing
only the height of the last withdrawal and its current properties.
- DelegationDistInfo: ` 0x02 | DelegatorAddr | ValOperatorAddr -> amino(delegatorDist)`
only the height of the last withdrawal and its current properties.
- DelegationDistInfo: `0x02 | DelegatorAddr | ValOperatorAddr -> amino(delegatorDist)`
```golang
type DelegationDistInfo struct {

23
docs/spec/distribution/03_end_block.md
View File

@ -1,35 +1,26 @@
# End Block
At each endblock, the fees received are allocated to the proposer, community fund,
and global pool. When the validator is the proposer of the round, that
validator (and their delegators) receives between 1% and 5% of fee rewards, the
reserve community tax is then charged, then the remainder is distributed
proportionally by voting power to all bonded validators independent of whether
they voted (social distribution). Note the social distribution is applied to
proposer validator in addition to the proposer reward.
At each `EndBlock`, the fees received are transferred to the distribution `ModuleAccount`, as it's the account the one who keeps track of the flow of coins in (as in this case) and out the module. The fees are also allocated to the proposer, community fund and global pool. When the validator is the proposer of the round, that validator (and their delegators) receives between 1% and 5% of fee rewards, the reserve community tax is then charged, then the remainder is distributed proportionally by voting power to all bonded validators independent of whether they voted (social distribution). Note the social distribution is applied to proposer validator in addition to the proposer reward.
The amount of proposer reward is calculated from pre-commits Tendermint
messages in order to incentivize validators to wait and include additional
pre-commits in the block. All provision rewards are added to a provision reward
pool which validator holds individually
(`ValidatorDistribution.ProvisionsRewardPool`).
The amount of proposer reward is calculated from pre-commits Tendermint messages in order to incentivize validators to wait and include additional pre-commits in the block. All provision rewards are added to a provision reward pool which validator holds individually (`ValidatorDistribution.ProvisionsRewardPool`).
```
```go
func AllocateTokens(feesCollected sdk.Coins, feePool FeePool, proposer ValidatorDistribution,
sumPowerPrecommitValidators, totalBondedTokens, communityTax,
proposerCommissionRate sdk.Dec)
SendCoins(FeeCollectorAddr, DistributionModuleAccAddr, feesCollected)
feesCollectedDec = MakeDecCoins(feesCollected)
proposerReward = feesCollectedDec * (0.01 + 0.04
* sumPowerPrecommitValidators / totalBondedTokens)
commission = proposerReward * proposerCommissionRate
proposer.PoolCommission += commission
proposer.PoolCommission += commission
proposer.Pool += proposerReward - commission
communityFunding = feesCollectedDec * communityTax
feePool.CommunityFund += communityFunding
poolReceived = feesCollectedDec - proposerReward - communityFunding
feePool.Pool += poolReceived

26
docs/spec/distribution/04_messages.md
View File

@ -7,7 +7,7 @@ When a delegator wishes to withdraw their rewards it must send
triggered each with any change in individual delegations, such as an unbond,
redelegation, or delegation of additional tokens to a specific validator.
```golang
```go
type MsgWithdrawDelegationRewardsAll struct {
DelegatorAddr sdk.AccAddress
}
@ -15,7 +15,7 @@ type MsgWithdrawDelegationRewardsAll struct {
func WithdrawDelegationRewardsAll(delegatorAddr, withdrawAddr sdk.AccAddress)
height = GetHeight()
withdraw = GetDelegatorRewardsAll(delegatorAddr, height)
AddCoins(withdrawAddr, withdraw.TruncateDecimal())
SendCoins(distributionModuleAcc, withdrawAddr, withdraw.TruncateDecimal())
func GetDelegatorRewardsAll(delegatorAddr sdk.AccAddress, height int64) DecCoins
@ -45,7 +45,7 @@ func GetDelegatorRewardsAll(delegatorAddr sdk.AccAddress, height int64) DecCoins
under special circumstances a delegator may wish to withdraw rewards from only
a single validator.
```golang
```go
type MsgWithdrawDelegationReward struct {
DelegatorAddr sdk.AccAddress
ValidatorAddr sdk.ValAddress
@ -66,7 +66,7 @@ func WithdrawDelegationReward(delegatorAddr, validatorAddr, withdrawAddr sdk.Acc
validator.Tokens, validator.DelegatorShares, validator.Commission)
SetFeePool(feePool)
AddCoins(withdrawAddr, withdraw.TruncateDecimal())
SendCoins(distributionModuleAcc, withdrawAddr, withdraw.TruncateDecimal())
```
@ -77,9 +77,9 @@ When a validator wishes to withdraw their rewards it must send
triggered each with any change in individual delegations, such as an unbond,
redelegation, or delegation of additional tokens to a specific validator. This
transaction withdraws the validators commission fee, as well as any rewards
earning on their self-delegation.
earning on their self-delegation.
```
```go
type MsgWithdrawValidatorRewardsAll struct {
OperatorAddr sdk.ValAddress // validator address to withdraw from
}
@ -101,9 +101,9 @@ func WithdrawValidatorRewardsAll(operatorAddr, withdrawAddr sdk.AccAddress)
withdraw += commission
SetFeePool(feePool)
AddCoins(withdrawAddr, withdraw.TruncateDecimal())
SendCoins(distributionModuleAcc, withdrawAddr, withdraw.TruncateDecimal())
```
## Common calculations
### Update total validator accum
@ -113,7 +113,7 @@ the amount of pool tokens which a validator is entitled to at a particular
block. The accum is always additive to the existing accum. This term is to be
updated each time rewards are withdrawn from the system.
```
```go
func (g FeePool) UpdateTotalValAccum(height int64, totalBondedTokens Dec) FeePool
blocks = height - g.TotalValAccumUpdateHeight
g.TotalValAccum += totalDelShares * blocks
@ -129,7 +129,7 @@ other delegators for that validator. The accum is always additive to
the existing accum. This term is to be updated each time a
withdrawal is made from a validator.
```
``` go
func (vi ValidatorDistInfo) UpdateTotalDelAccum(height int64, totalDelShares Dec) ValidatorDistInfo
blocks = height - vi.TotalDelAccumUpdateHeight
vi.TotalDelAccum += totalDelShares * blocks
@ -144,7 +144,7 @@ the proposer and receives new tokens, the relevant validator must move tokens
from the passive global pool to their own pool. It is at this point that the
commission is withdrawn
```
```go
func (vi ValidatorDistInfo) TakeFeePoolRewards(g FeePool, height int64, totalBonded, vdTokens, commissionRate Dec) (
vi ValidatorDistInfo, g FeePool)
@ -171,7 +171,7 @@ func (vi ValidatorDistInfo) TakeFeePoolRewards(g FeePool, height int64, totalBon
For delegations (including validator's self-delegation) all rewards from reward
pool have already had the validator's commission taken away.
```
```go
func (di DelegationDistInfo) WithdrawRewards(g FeePool, vi ValidatorDistInfo,
height int64, totalBonded, vdTokens, totalDelShares, commissionRate Dec) (
di DelegationDistInfo, g FeePool, withdrawn DecCoins)
@ -196,7 +196,7 @@ func (di DelegationDistInfo) WithdrawRewards(g FeePool, vi ValidatorDistInfo,
Commission is calculated each time rewards enter into the validator.
```
```go
func (vi ValidatorDistInfo) WithdrawCommission(g FeePool, height int64,
totalBonded, vdTokens, commissionRate Dec) (
vi ValidatorDistInfo, g FeePool, withdrawn DecCoins)

36
docs/spec/governance/01_concepts.md
View File

@ -23,27 +23,6 @@ Any Atom holder, whether bonded or unbonded, can submit proposals by sending a
`TxGovProposal` transaction. Once a proposal is submitted, it is identified by
its unique `proposalID`.
### Proposal filter (minimum deposit)
To prevent spam, proposals must be submitted with a deposit in Atoms. Voting
period will not start as long as the proposal's deposit is smaller than the
minimum deposit `MinDeposit`.
When a proposal is submitted, it has to be accompanied by a deposit that must
be strictly positive but can be inferior to `MinDeposit`. Indeed, the submitter
need not pay for the entire deposit on its own. If a proposal's deposit is
strictly inferior to `MinDeposit`, other Atom holders can increase the
proposal's deposit by sending a `TxGovDeposit` transaction. Once the proposal's deposit reaches `MinDeposit`, it enters voting period.
If proposal's deposit does not reach `MinDeposit` before `MaxDepositPeriod`, proposal closes and nobody can deposit on it anymore.
### Deposit refund
There is one instance where Atom holders that deposits can be refunded:
* If the proposal is accepted.
Then, deposits will automatically be refunded to their respective depositor.
### Proposal types
In the initial version of the governance module, there are two types of
@ -64,6 +43,21 @@ governance module (eg. `ParamChangeProposal`), which then execute the respective
module's proposal handler when a proposal passes. This custom handler may perform
arbitrary state changes.
## Deposit
To prevent spam, proposals must be submitted with a deposit in the coins defined in the `MinDeposit` param. The voting period will not start until the proposal's deposit equals `MinDeposit`.
When a proposal is submitted, it has to be accompanied by a deposit that must be strictly positive, but can be inferior to `MinDeposit`. The submitter doesn't need to pay for the entire deposit on their own. If a proposal's deposit is inferior to `MinDeposit`, other token holders can increase the proposal's deposit by sending a `Deposit` transaction. The deposit is kept in an escrow in the governance `ModuleAccount` until the proposal is finalized (passed or rejected).
Once the proposal's deposit reaches `MinDeposit`, it enters voting period. If proposal's deposit does not reach `MinDeposit` before `MaxDepositPeriod`, proposal closes and nobody can deposit on it anymore.
### Deposit refund and burn
When a the a proposal finalized, the coins from the deposit are either refunded or burned, according to the final tally of the proposal:
* If the proposal is approved or if it's rejected but _not_ vetoed, deposits will automatically be refunded to their respective depositor (transferred from the governance `ModuleAccount`).
* When the proposal is vetoed with a supermajority, deposits be burned from the governance `ModuleAccount`.
## Vote
### Participants

2
docs/spec/governance/03_messages.md
View File

@ -23,6 +23,7 @@ set in the governance module.
* Decrease balance of sender by `InitialDeposit`
* If `MinDeposit` is reached:
* Push `proposalID` in `ProposalProcessingQueue`
* Transfer `InitialDeposit` from the `Proposer` to the governance `ModuleAccount`
A `TxGovSubmitProposal` transaction can be handled according to the following
pseudocode.
@ -88,6 +89,7 @@ type TxGovDeposit struct {
* Increase `proposal.TotalDeposit` by sender's `deposit`
* If `MinDeposit` is reached:
* Push `proposalID` in `ProposalProcessingQueueEnd`
* Transfer `Deposit` from the `proposer` to the governance `ModuleAccount`
A `TxGovDeposit` transaction has to go through a number of checks to be valid.
These checks are outlined in the following pseudocode.

4
docs/spec/mint/02_state.md
View File

@ -6,7 +6,7 @@ The minter is a space for holding current inflation information.
- Minter: `0x00 -> amino(minter)`
```golang
```go
type Minter struct {
Inflation sdk.Dec // current annual inflation rate
AnnualProvisions sdk.Dec // current annual exptected provisions
@ -19,7 +19,7 @@ Minting params are held in the global params store.
- Params: `mint/params -> amino(params)`
```golang
```go
type Params struct {
MintDenom string // type of coin to mint
InflationRateChange sdk.Dec // maximum annual change in inflation rate

4
docs/spec/mint/03_begin_block.md
View File

@ -26,6 +26,7 @@ NextInflationRate(params Params, bondedRatio sdk.Dec) (inflation sdk.Dec) {
}
return inflation
}
```
## NextAnnualProvisions
@ -40,8 +41,7 @@ NextAnnualProvisions(params Params, totalSupply sdk.Dec) (provisions sdk.Dec) {
## BlockProvision
Calculate the provisions generated for each block based on current
annual provisions
Calculate the provisions generated for each block based on current annual provisions. The provisions are then minted by the `mint` module's `ModuleMinterAccount` and then transferred to the `auth`'s `FeeCollector` `ModuleAccount`.
```
BlockProvision(params Params) sdk.Coin {

98
docs/spec/staking/01_state.md
View File

@ -1,37 +1,19 @@
# State
## Pool
The pool tracks the total amounts of tokens (each staking denom is tracked
separately) and their state (bonded or loose).
Note: `NotBondedTokens` _includes_ both tokens in an `unbonding` state as well
as fully `unbonded` state.
- Pool: `0x01 -> amino(pool)`
```golang
type Pool struct {
NotBondedTokens sdk.Int // tokens not associated with any bonded validator
BondedTokens sdk.Int // reserve of bonded tokens
}
```
## LastTotalPower
LastTotalPower tracks the total amounts of bonded tokens recorded during the previous
end block.
LastTotalPower tracks the total amounts of bonded tokens recorded during the previous end block.
- LastTotalPower: `0x12 -> amino(sdk.Int)`
- LastTotalPower: `0x12 -> amino(sdk.Int)`
## Params
Params is a module-wide configuration structure that stores system parameters
and defines overall functioning of the staking module.
- Params: `Paramsspace("staking") -> amino(params)`
- Params: `Paramsspace("staking") -> amino(params)`
```golang
```go
type Params struct {
UnbondingTime time.Duration // time duration of unbonding
MaxValidators uint16 // maximum number of validators
@ -48,12 +30,12 @@ additional indices are maintained per validator object in order to fulfill
required lookups for slashing and validator-set updates. A third special index
(`LastValidatorPower`) is also maintained which however remains constant
throughout each block, unlike the first two indices which mirror the validator
records within a block.
records within a block.
- Validators: `0x21 | OperatorAddr -> amino(validator)`
- ValidatorsByConsAddr: `0x22 | ConsAddr -> OperatorAddr`
- ValidatorsByPower: `0x23 | BigEndian(ConsensusPower) | OperatorAddr -> OperatorAddr`
- LastValidatorsPower: `0x11 OperatorAddr -> amino(ConsensusPower)
- LastValidatorsPower: `0x11 OperatorAddr -> amino(ConsensusPower)`
`Validators` is the primary index - it ensures that each operator can have only one
associated validator, where the public key of that validator can change in the
@ -63,7 +45,7 @@ concern for the changing public key.
`ValidatorByConsAddr` is an additional index that enables lookups for slashing.
When Tendermint reports evidence, it provides the validator address, so this
map is needed to find the operator. Note that the `ConsAddr` corresponds to the
address which can be derived from the validator's `ConsPubKey`.
address which can be derived from the validator's `ConsPubKey`.
`ValidatorsByPower` is an additional index that provides a sorted list o
potential validators to quickly determine the current active set. Here
@ -72,12 +54,11 @@ ConsensusPower is validator.Tokens/10^6. Note that all validators where
`LastValidatorsPower` is a special index that provides a historical list of the
last-block's bonded validators. This index remains constant during a block but
is updated during the validator set update process which takes place in [end
block](end_block.md).
is updated during the validator set update process which takes place in [`EndBlock`](./04_end_block.md).
Each validator's state is stored in a `Validator` struct:
```golang
```go
type Validator struct {
OperatorAddress sdk.ValAddress // address of the validator's operator; bech encoded in JSON
ConsPubKey crypto.PubKey // the consensus public key of the validator; bech encoded in JSON
@ -116,17 +97,17 @@ type Description struct {
Delegations are identified by combining `DelegatorAddr` (the address of the delegator)
with the `ValidatorAddr` Delegators are indexed in the store as follows:
- Delegation: ` 0x31 | DelegatorAddr | ValidatorAddr -> amino(delegation)`
- Delegation: `0x31 | DelegatorAddr | ValidatorAddr -> amino(delegation)`
Stake holders may delegate coins to validators; under this circumstance their
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
the transaction is the owner of the bond.
```golang
```go
type Delegation struct {
DelegatorAddr sdk.AccAddress
ValidatorAddr sdk.ValAddress
DelegatorAddr sdk.AccAddress
ValidatorAddr sdk.ValAddress
Shares sdk.Dec // delegation shares received
}
```
@ -139,9 +120,9 @@ detected.
`UnbondingDelegation` are indexed in the store as:
- UnbondingDelegation: ` 0x32 | DelegatorAddr | ValidatorAddr ->
- UnbondingDelegation: `0x32 | DelegatorAddr | ValidatorAddr ->
amino(unbondingDelegation)`
- UnbondingDelegationsFromValidator: ` 0x33 | ValidatorAddr | DelegatorAddr ->
- UnbondingDelegationsFromValidator: `0x33 | ValidatorAddr | DelegatorAddr ->
nil`
The first map here is used in queries, to lookup all unbonding delegations for
@ -151,7 +132,7 @@ slashed.
A UnbondingDelegation object is created every time an unbonding is initiated.
```golang
```go
type UnbondingDelegation struct {
DelegatorAddr sdk.AccAddress // delegator
ValidatorAddr sdk.ValAddress // validator unbonding from operator addr
@ -172,13 +153,13 @@ The bonded tokens worth of a `Delegation` may be instantly redelegated from a
source validator to a different validator (destination validator). However when
this occurs they must be tracked in a `Redelegation` object, whereby their
shares can be slashed if their tokens have contributed to a Byzantine fault
committed by the source validator.
committed by the source validator.
`Redelegation` are indexed in the store as:
- Redelegations: `0x34 | DelegatorAddr | ValidatorSrcAddr | ValidatorDstAddr -> amino(redelegation)`
- RedelegationsBySrc: `0x35 | ValidatorSrcAddr | ValidatorDstAddr | DelegatorAddr -> nil`
- RedelegationsByDst: `0x36 | ValidatorDstAddr | ValidatorSrcAddr | DelegatorAddr -> nil`
- Redelegations: `0x34 | DelegatorAddr | ValidatorSrcAddr | ValidatorDstAddr -> amino(redelegation)`
- RedelegationsBySrc: `0x35 | ValidatorSrcAddr | ValidatorDstAddr | DelegatorAddr -> nil`
- RedelegationsByDst: `0x36 | ValidatorDstAddr | ValidatorSrcAddr | 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 `ValidatorSrcAddr`,
@ -186,12 +167,13 @@ while the third map is for slashing based on the `ValidatorDstAddr`.
A redelegation object is created every time a redelegation occurs. To prevent
"redelegation hopping" redelegations may not occure under the situation that:
- the (re)delegator already has another unmature redelegation in progress
with a destination to a validator (let's call it `Validator X`)
- and, the (re)delegator is attempting to create a _new_ redelegation
where the source validator for this new redelegation is `Validator-X`.
```golang
- the (re)delegator already has another unmature redelegation in progress
with a destination to a validator (let's call it `Validator X`)
- and, the (re)delegator is attempting to create a _new_ redelegation
where the source validator for this new redelegation is `Validator-X`.
```go
type Redelegation struct {
DelegatorAddr sdk.AccAddress // delegator
ValidatorSrcAddr sdk.ValAddress // validator redelegation source operator addr
@ -213,47 +195,47 @@ type RedelegationEntry struct {
All queues objects are sorted by timestamp. The time used within any queue is
first rounded to the nearest nanosecond then sorted. The sortable time format
used is a slight modification of the RFC3339Nano and uses the the format string
`"2006-01-02T15:04:05.000000000"`. Notably this format:
`"2006-01-02T15:04:05.000000000"`. Notably this format:
- right pads all zeros
- drops the time zone info (uses UTC)
- right pads all zeros
- drops the time zone info (uses UTC)
In all cases, the stored timestamp represents the maturation time of the queue
element.
element.
### UnbondingDelegationQueue
For the purpose of tracking progress of unbonding delegations the unbonding
delegations queue is kept.
delegations queue is kept.
- UnbondingDelegation: `0x41 | format(time) -> []DVPair`
```
```go
type DVPair struct {
DelegatorAddr sdk.AccAddress
ValidatorAddr sdk.ValAddress
DelegatorAddr sdk.AccAddress
ValidatorAddr sdk.ValAddress
}
```
### RedelegationQueue
For the purpose of tracking progress of redelegations the redelegation queue is
kept.
kept.
- UnbondingDelegation: `0x42 | format(time) -> []DVVTriplet`
```
```go
type DVVTriplet struct {
DelegatorAddr sdk.AccAddress
ValidatorSrcAddr sdk.ValAddress
ValidatorDstAddr sdk.ValAddress
DelegatorAddr sdk.AccAddress
ValidatorSrcAddr sdk.ValAddress
ValidatorDstAddr sdk.ValAddress
}
```
### ValidatorQueue
For the purpose of tracking progress of unbonding validators the validator
queue is kept.
queue is kept.
- ValidatorQueueTime: `0x43 | format(time) -> []sdk.ValAddress`

123
docs/spec/staking/02_state_transitions.md
View File

@ -2,96 +2,107 @@
This document describes the state transition operations pertaining to:
- Validators
- Delegations
- Slashing
1. [Validators](./02_state_transitions.md#validators)
2. [Delegations](./02_state_transitions.md#delegations)
3. [Slashing](./02_state_transitions.md#slashing)
## Validators
State transitions in validators are performed on every [`EndBlock`](./04_end_block.md#validator-set-changes) in order to check for changes in the active `ValidatorSet`.
### Non-Bonded to Bonded
When a validator is bonded from any other state the following operations occur:
- set `validator.Status` to `Bonded`
- update the `Pool` object with tokens moved from `NotBondedTokens` to `BondedTokens`
- delete record the existing record from `ValidatorByPowerIndex`
- add an new updated record to the `ValidatorByPowerIndex`
- update the `Validator` object for this validator
- if it exists, delete any `ValidatorQueue` record for this validator
- set `validator.Status` to `Bonded`
- send the `validator.Tokens` from the `NotBondedTokens` to the `BondedPool` `ModuleAccount`
- delete the existing record from `ValidatorByPowerIndex`
- add a new updated record to the `ValidatorByPowerIndex`
- update the `Validator` object for this validator
- if it exists, delete any `ValidatorQueue` record for this validator
### Bonded to Unbonding
When a validator begins the unbonding process the following operations occur:
- update the `Pool` object with tokens moved from `BondedTokens` to `NotBondedTokens`
- set `validator.Status` to `Unbonding`
- delete record the existing record from `ValidatorByPowerIndex`
- add an new updated record to the `ValidatorByPowerIndex`
- update the `Validator` object for this validator
- insert a new record into the `ValidatorQueue` for this validator
When a validator begins the unbonding process the following operations occur:
- send the `validator.Tokens` from the `BondedPool` to the `NotBondedTokens` `ModuleAccount`
- set `validator.Status` to `Unbonding`
- delete the existing record from `ValidatorByPowerIndex`
- add a new updated record to the `ValidatorByPowerIndex`
- update the `Validator` object for this validator
- insert a new record into the `ValidatorQueue` for this validator
### Unbonding to Unbonded
A validator moves from unbonding to unbonded when the `ValidatorQueue` object
moves from bonded to unbonded
- update the `Validator` object for this validator
- set `validator.Status` to `Unbonded`
### Jail/Unjail
- update the `Validator` object for this validator
- set `validator.Status` to `Unbonded`
### Jail/Unjail
when a validator is jailed it is effectively removed from the Tendermint set.
this process may be also be reversed. the following operations occur:
- set `Validator.Jailed` and update object
- if jailed delete record from `ValidatorByPowerIndex`
- if unjailed add record to `ValidatorByPowerIndex`
- set `Validator.Jailed` and update object
- if jailed delete record from `ValidatorByPowerIndex`
- if unjailed add record to `ValidatorByPowerIndex`
## Delegations
### Delegate
When a delegation occurs both the validator and the delegtion objects are affected
- determine the delegators shares based on tokens delegated and the validator's exchange rate
- remove tokens from the sending account
- add shares the delegation object or add them to a created validator object
- add new delegator shares and update the `Validator` object
- update the `Pool` object appropriately if tokens have moved into a bonded validator
- delete record the existing record from `ValidatorByPowerIndex`
- add an new updated record to the `ValidatorByPowerIndex`
#### Unbond Delegation
When a delegation occurs both the validator and the delegation objects are affected
- determine the delegators shares based on tokens delegated and the validator's exchange rate
- remove tokens from the sending account
- add shares the delegation object or add them to a created validator object
- add new delegator shares and update the `Validator` object
- transfer the `delegation.Amount` from the delegator's account to the `BondedPool` or the `NotBondedPool` `ModuleAccount` depending if the `validator.Status` is `Bonded` or not
- delete the existing record from `ValidatorByPowerIndex`
- add an new updated record to the `ValidatorByPowerIndex`
### Begin Unbonding
As a part of the Undelegate and Complete Unbonding state transitions Unbond
Delegation may be called.
- subtract the unbonded shares from delegator
- update the delegation or remove the delegation if there are no more shares
- if the delegation is the operator of the validator and no more shares exist
then trigger a jail validator
- update the validator with removed the delegator shares and associated coins, update
the pool for any shifts between bonded and non-bonded tokens.
- remove the validator if it is unbonded and there are no more delegation shares.
Delegation may be called.
### Undelegate
When an delegation occurs both the validator and the delegtion objects are affected
- perform an unbond delegation
- if the validator is unbonding or bonded add the tokens to an
`UnbondingDelegation` Entry
- if the validator is unbonded send the tokens directly to the withdraw
account
- subtract the unbonded shares from delegator
- if the validator is `Unbonding` or `Bonded` add the tokens to an `UnbondingDelegation` Entry
- if the validator is `Unbonded` send the tokens directly to the withdraw
account
- update the delegation or remove the delegation if there are no more shares
- if the delegation is the operator of the validator and no more shares exist then trigger a jail validator
- update the validator with removed the delegator shares and associated coins
- if the validator state is `Bonded`, transfer the `Coins` worth of the unbonded
shares from the `BondedPool` to the `NotBondedPool` `ModuleAccount`
- remove the validator if it is unbonded and there are no more delegation shares.
### Complete Unbonding
For undelegations which do not complete immediately, the following operations
occur when the unbonding delegation queue element matures:
- remove the entry from the `UnbondingDelegation` object
- withdraw the tokens to the delegator withdraw address
- remove the entry from the `UnbondingDelegation` object
- transfer the tokens from the `NotBondedPool` `ModuleAccount` to the delegator `Account`
### Begin Redelegation
Redelegations affect the delegation, source and destination validators.
- perform an unbond delegation from the source validator
- using the generated tokens perform a Delegate to the destination
validator
- record the token amount in an new entry in the relevant `Redelegation`
Redelegations affect the delegation, source and destination validators.
- perform an `unbond` delegation from the source validator to retrieve the tokens worth of the unbonded shares
- using the unbonded tokens, `Delegate` them to the destination validator
- if the `sourceValidator.Status` is `Bonded`, and the `destinationValidator` is not, transfer the newly delegated tokens from the `BondedPool` to the `NotBondedPool` `ModuleAccount`
- otherwise, if the `sourceValidator.Status` is not `Bonded`, and the `destinationValidator` is `Bonded`, transfer the newly delegated tokens from the `NotBondedPool` to the `BondedPool` `ModuleAccount`
- record the token amount in an new entry in the relevant `Redelegation`
### Complete Redelegation
When a redelegations complete the following occurs:
- remove the entry from the `Redelegation` object
- remove the entry from the `Redelegation` object
TODO TODO TOFU TODO
## Slashing
### Slash Validator

168
docs/spec/staking/03_messages.md
View File

@ -1,14 +1,12 @@
# Messages
In this section we describe the processing of the staking messages and the
corresponding updates to the state. All created/modified state objects
specified by each message are defined within [state.md](state.md).
In this section we describe the processing of the staking messages and the corresponding updates to the state. All created/modified state objects specified by each message are defined within the [state](./02_state.md) section.
## MsgCreateValidator
A validator is created using the `MsgCreateValidator` message.
A validator is created using the `MsgCreateValidator` message.
```golang
```go
type MsgCreateValidator struct {
Description Description
Commission Commission
@ -20,30 +18,28 @@ type MsgCreateValidator struct {
}
```
This message is expected to fail if:
This message is expected to fail if:
- another validator with this operator address is already registered
- another validator with this pubkey is already registered
- the initial self-delegation tokens are of a denom not specified as the bonding denom
- the commission parameters are faulty, namely:
- `MaxRate` is either > 1 or < 0
- the initial `Rate` is either negative or > `MaxRate`
- the initial `MaxChangeRate` is either negative or > `MaxRate`
- the description fields are too large
- another validator with this operator address is already registered
- another validator with this pubkey is already registered
- the initial self-delegation tokens are of a denom not specified as the
bonding denom
- the commission parameters are faulty, namely:
- `MaxRate` is either > 1 or < 0
- the initial `Rate` is either negative or > `MaxRate`
- the initial `MaxChangeRate` is either negative or > `MaxRate`
- the description fields are too large
This message creates and stores the `Validator` object at appropriate indexes.
Additionally a self-delegation is made with the initial tokens delegation
tokens `Delegation`. The validator always starts as unbonded but may be bonded
in the first end-block.
in the first end-block.
## MsgEditValidator
The `Description`, `CommissionRate` of a validator can be updated using the
`MsgEditCandidacy`.
```golang
```go
type MsgEditCandidacy struct {
Description Description
ValidatorAddr sdk.ValAddress
@ -51,77 +47,70 @@ type MsgEditCandidacy struct {
}
```
This message is expected to fail if:
This message is expected to fail if:
- the initial `CommissionRate` is either negative or > `MaxRate`
- the `CommissionRate` has already been updated within the previous 24 hours
- the `CommissionRate` is > `MaxChangeRate`
- the description fields are too large
- the initial `CommissionRate` is either negative or > `MaxRate`
- the `CommissionRate` has already been updated within the previous 24 hours
- the `CommissionRate` is > `MaxChangeRate`
- the description fields are too large
This message stores the updated `Validator` object.
This message stores the updated `Validator` object.
## MsgDelegate
Within this message the delegator provides coins, and in return receives
some amount of their validator's (newly created) delegator-shares that are
assigned to `Delegation.Shares`.
assigned to `Delegation.Shares`.
```golang
```go
type MsgDelegate struct {
DelegatorAddr sdk.AccAddress
ValidatorAddr sdk.ValAddress
Delegation sdk.Coin
DelegatorAddr sdk.AccAddress
ValidatorAddr sdk.ValAddress
Amount sdk.Coin
}
```
This message is expected to fail if:
This message is expected to fail if:
- the validator is does not exist
- the validator is jailed
- the validator is does not exist
- the validator is jailed
- the `Amount` `Coin` has a denomination different than one defined by `params.BondDenom`
If an existing `Delegation` object for provided addresses does not already
exist than it is created as part of this message otherwise the existing
`Delegation` is updated to include the newly received shares.
`Delegation` is updated to include the newly received shares.
## MsgBeginUnbonding
The begin unbonding message allows delegators to undelegate their tokens from
validator.
validator.
```golang
```go
type MsgBeginUnbonding struct {
DelegatorAddr sdk.AccAddress
ValidatorAddr sdk.ValAddress
SharesAmount sdk.Dec
DelegatorAddr sdk.AccAddress
ValidatorAddr sdk.ValAddress
Amount sdk.Coin
}
```
This message is expected to fail if:
This message is expected to fail if:
- the delegation doesn't exist
- the validator doesn't exist
- the delegation has less shares than `SharesAmount`
- existing `UnbondingDelegation` has maximum entries as defined by
params.MaxEntries
- the delegation doesn't exist
- the validator doesn't exist
- the delegation has less shares than the ones worth of `Amount`
- existing `UnbondingDelegation` has maximum entries as defined by `params.MaxEntries`
- the `Amount` has a denomination different than one defined by `params.BondDenom`
When this message is processed the following actions occur:
- validator's `DelegatorShares` and the delegation's `Shares` are both reduced
by the message `SharesAmount`
- calculate the token worth of the shares remove that amount tokens held
within the validator
- with those removed tokens, if the validator is:
- bonded - add them to an entry in `UnbondingDelegation` (create
`UnbondingDelegation` if it doesn't exist) with a completion time a full
unbonding period from the current time. Update pool shares to reduce
BondedTokens and increase NotBondedTokens by token worth of the shares.
- unbonding - add them to an entry in `UnbondingDelegation` (create
`UnbondingDelegation` if it doesn't exist) with the same completion time
as the validator (`UnbondingMinTime`).
- unbonded - then send the coins the message `DelegatorAddr`
- if there are no more `Shares` in the delegation, then the delegation object
is removed from the store
- under this situation if the delegation is the validator's self-delegation
then also jail the validator.
- validator's `DelegatorShares` and the delegation's `Shares` are both reduced by the message `SharesAmount`
- calculate the token worth of the shares remove that amount tokens held within the validator
- with those removed tokens, if the validator is:
- `Bonded` - add them to an entry in `UnbondingDelegation` (create `UnbondingDelegation` if it doesn't exist) with a completion time a full unbonding period from the current time. Update pool shares to reduce BondedTokens and increase NotBondedTokens by token worth of the shares.
- `Unbonding` - add them to an entry in `UnbondingDelegation` (create `UnbondingDelegation` if it doesn't exist) with the same completion time as the validator (`UnbondingMinTime`).
- `Unbonded` - then send the coins the message `DelegatorAddr`
- if there are no more `Shares` in the delegation, then the delegation object is removed from the store
- under this situation if the delegation is the validator's self-delegation then also jail the validator.
## MsgBeginRedelegate
@ -129,43 +118,32 @@ The redelegation command allows delegators to instantly switch validators. Once
the unbonding period has passed, the redelegation is automatically completed in
the EndBlocker.
```golang
```go
type MsgBeginRedelegate struct {
DelegatorAddr sdk.AccAddress
ValidatorSrcAddr sdk.ValAddress
ValidatorDstAddr sdk.ValAddress
SharesAmount sdk.Dec
DelegatorAddr sdk.AccAddress
ValidatorSrcAddr sdk.ValAddress
ValidatorDstAddr sdk.ValAddress
Amount sdk.Coin
}
```
This message is expected to fail if:
This message is expected to fail if:
- the delegation doesn't exist
- the source or destination validators don't exist
- the delegation has less shares than `SharesAmount`
- the source validator has a receiving redelegation which
is not matured (aka. the redelegation may be transitive)
- existing `Redelegation` has maximum entries as defined by
params.MaxEntries
- the delegation doesn't exist
- the source or destination validators don't exist
- the delegation has less shares than the ones worth of `Amount`
- the source validator has a receiving redelegation which is not matured (aka. the redelegation may be transitive)
- existing `Redelegation` has maximum entries as defined by `params.MaxEntries`
- the `Amount` `Coin` has a denomination different than one defined by `params.BondDenom`
When this message is processed the following actions occur:
- the source validator's `DelegatorShares` and the delegations `Shares` are
both reduced by the message `SharesAmount`
- calculate the token worth of the shares remove that amount tokens held
within the source validator.
- if the source validator is:
- bonded - add an entry to the `Redelegation` (create
`Redelegation` if it doesn't exist) with a completion time a full
unbonding period from the current time. Update pool shares to reduce
BondedTokens and increase NotBondedTokens by token worth of the shares
(this may be effectively reversed in the next step however).
- unbonding - add an entry to the `Redelegation` (create `Redelegation` if
it doesn't exist) with the same completion time as the validator
(`UnbondingMinTime`).
- unbonded - no action required in this step
- Delegate the token worth to the destination validator, possibly moving
tokens back to the bonded state.
- if there are no more `Shares` in the source delegation, then the source
delegation object is removed from the store
- under this situation if the delegation is the validator's self-delegation
then also jail the validator.
- the source validator's `DelegatorShares` and the delegations `Shares` are both reduced by the message `SharesAmount`
- calculate the token worth of the shares remove that amount tokens held within the source validator.
- if the source validator is:
- `Bonded` - add an entry to the `Redelegation` (create `Redelegation` if it doesn't exist) with a completion time a full unbonding period from the current time. Update pool shares to reduce BondedTokens and increase NotBondedTokens by token worth of the shares (this may be effectively reversed in the next step however).
- `Unbonding` - add an entry to the `Redelegation` (create `Redelegation` if it doesn't exist) with the same completion time as the validator (`UnbondingMinTime`).
- `Unbonded` - no action required in this step
- Delegate the token worth to the destination validator, possibly moving tokens back to the bonded state.
- if there are no more `Shares` in the source delegation, then the source delegation object is removed from the store
- under this situation if the delegation is the validator's self-delegation then also jail the validator.

42
docs/spec/staking/04_end_block.md
View File

@ -1,7 +1,7 @@
# End-Block
# End-Block
Each abci end block call, the operations to update queues and validator set
changes are specified to execute.
changes are specified to execute.
## Validator Set Changes
@ -11,23 +11,25 @@ validators are also returned back to Tendermint for inclusion in the Tendermint
validator set which is responsible for validating Tendermint messages at the
consensus layer. Operations are as following:
- the new validator set is taken as the top `params.MaxValidators` number of
validators retrieved from the ValidatorsByPower index
- the previous validator set is compared with the new validator set
- missing validators begin unbonding
- new validator are instantly bonded
- the new validator set is taken as the top `params.MaxValidators` number of
validators retrieved from the ValidatorsByPower index
- the previous validator set is compared with the new validator set:
- missing validators begin unbonding and their `Tokens` are transferred from the
`BondedPool` to the `NotBondedPool` `ModuleAccount`
- new validators are instantly bonded and their `Tokens` are transferred from the
`NotBondedPool` to the `BondedPool` `ModuleAccount`
In all cases, any validators leaving or entering the bonded validator set or
changing balances and staying within the bonded validator set incur an update
message which is passed back to Tendermint.
## Queues
## Queues
Within staking, certain state-transitions are not instantaneous but take place
over a duration of time (typically the unbonding period). When these
transitions are mature certain operations must take place in order to complete
the state operation. This is achieved through the use of queues which are
checked/processed at the end of each block.
checked/processed at the end of each block.
### Unbonding Validators
@ -36,7 +38,7 @@ being jailed, or not having sufficient bonded tokens) it begins the unbonding
process along with all its delegations begin unbonding (while still being
delegated to this validator). At this point the validator is said to be an
unbonding validator, whereby it will mature to become an "unbonded validator"
after the unbonding period has passed.
after the unbonding period has passed.
Each block the validator queue is to be checked for mature unbonding validators
(namely with a completion time <= current time). At this point any mature
@ -48,16 +50,18 @@ delegations, the `validator.Status` is switched from `sdk.Unbonding` to
### Unbonding Delegations
Complete the unbonding of all mature `UnbondingDelegations.Entries` within the
`UnbondingDelegations` queue with the following procedure:
- transfer the balance coins to the delegator's wallet address
- remove the mature entry from `UnbondingDelegation.Entries`
- remove the `UnbondingDelegation` object from the store if there are no
remaining entries.
`UnbondingDelegations` queue with the following procedure:
- transfer the balance coins to the delegator's wallet address
- remove the mature entry from `UnbondingDelegation.Entries`
- remove the `UnbondingDelegation` object from the store if there are no
remaining entries.
### Redelegations
Complete the unbonding of all mature `Redelegation.Entries` within the
`Redelegations` queue with the following procedure:
- remove the mature entry from `Redelegation.Entries`
- remove the `Redelegation` object from the store if there are no
remaining entries.
`Redelegations` queue with the following procedure:
- remove the mature entry from `Redelegation.Entries`
- remove the `Redelegation` object from the store if there are no
remaining entries.

60
docs/spec/supply/01_concepts.md Normal file
View File

@ -0,0 +1,60 @@
# Concepts
## Supply
The `supply` module:
- passively tracks the total supply of coins within a chain,
- provides a pattern for modules to hold/interact with `Coins`, and
- introduces the invariant check to verify a chain's total supply.
### Total Supply
The total `Supply` of the network is equal to the sum of all coins from the
account. The total supply is updated every time a `Coin` is minted (eg: as part
of the inflation mechanism) or burned (eg: due to slashing or if a governance
proposal is vetoed).
## Module Accounts
The supply module introduces a new type of `auth.Account` which can be used by
modules to allocate tokens and in special cases mint or burn tokens. At a base
level these module accounts are capable of sending/receiving tokens to and from
`auth.Account`s and other module accounts. This design replaces previous
alternative designs where, to hold tokens, modules would burn the incoming
tokens from the sender account, and then track those tokens internally. Later,
in order to send tokens, the module would need to effectively mint tokens
within a destination account. The new design removes duplicate logic between
modules to perform this accounting.
The `ModuleAccount` interface is defined as follows:
```go
type ModuleAccount interface {
auth.Account // same methods as the Account interface
GetName() string // name of the module; used to obtain the address
GetPermission() string // permission of module account (minter/burner/holder)
}
```
The supply `Keeper` also introduces new wrapper functions for the auth `Keeper`
and the bank `Keeper` that are related to `ModuleAccount`s in order to be able
to:
- Get and set `ModuleAccount`s by providing the `Name`.
- Send coins from and to other `ModuleAccount`s or standard `Account`s
(`BaseAccount` or `VestingAccount`) by passing only the `Name`.
- `Mint` or `Burn` coins for a `ModuleAccount` (restricted to its permissions).
### Permissions
Each `ModuleAccount` has a different set of permissions that provide different
object capabilities to perform certain actions. Permissions need to be
registered upon the creation of the supply `Keeper` so that every time a
`ModuleAccount` calls the allowed functions, the `Keeper` can lookup the
permission to that specific account and perform or not the action.
The available permissions are:
- `Basic`: is allowed to only transfer its coins to other accounts.
- `Minter`: allows for a module to mint a specific amount of coins as well as perform the `Basic` permissioned actions.
- `Burner`: allows for a module to burn a specific amount of coins as well as perform the `Basic` permissioned actions.

13
docs/spec/supply/02_state.md Normal file
View File

@ -0,0 +1,13 @@
# State
## Supply
The `Supply` is a passive tracker of the supply of the chain:
- Supply: `0x0 -> amino(Supply)`
```go
type Supply struct {
Total sdk.Coins // total supply of tokens registered on the chain
}
```

7
docs/spec/supply/03_future_improvements.md Normal file
View File

@ -0,0 +1,7 @@
# Future improvements
The current supply module only keeps track of the total supply of coins held in the network.
Future improvements may also include other types of supply such as:
* **Register Supply:** Register a concrete supply type in order to track it passively on the chain.

10
docs/spec/supply/README.md Normal file
View File

@ -0,0 +1,10 @@
# Supply Specification
## Contents
1. **[Concept](./01_concepts.md)**
- [Supply](./01_concepts.md#supply)
- [Module Accounts](./01_concepts.md#module-accounts)
2. **[State](./02_state.md)**
- [Supply](./02_state.md#supply)
3. **[Future Improvements](./03_future_improvements.md)**