LaconicNetwork/cosmos-sdk
7
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 2 Wiki Activity

docs: Improve markdownlint configuration (#11104)

Browse Source 
## Description

Closes: #9404



---

### Author Checklist

*All items are required. Please add a note to the item if the item is not applicable and
please add links to any relevant follow up issues.*

I have...

- [x] included the correct [type prefix](https://github.com/commitizen/conventional-commit-types/blob/v3.0.0/index.json) in the PR title
- [ ] added `!` to the type prefix if API or client breaking change
- [x] targeted the correct branch (see [PR Targeting](https://github.com/cosmos/cosmos-sdk/blob/master/CONTRIBUTING.md#pr-targeting))
- [x] provided a link to the relevant issue or specification
- [ ] followed the guidelines for [building modules](https://github.com/cosmos/cosmos-sdk/blob/master/docs/building-modules)
- [ ] included the necessary unit and integration [tests](https://github.com/cosmos/cosmos-sdk/blob/master/CONTRIBUTING.md#testing)
- [ ] added a changelog entry to `CHANGELOG.md`
- [ ] included comments for [documenting Go code](https://blog.golang.org/godoc)
- [ ] updated the relevant documentation or specification
- [x] reviewed "Files changed" and left comments if necessary
- [x] confirmed all CI checks have passed

### Reviewers Checklist

*All items are required. Please add a note if the item is not applicable and please add
your handle next to the items reviewed if you only reviewed selected items.*

I have...

- [ ] confirmed the correct [type prefix](https://github.com/commitizen/conventional-commit-types/blob/v3.0.0/index.json) in the PR title
- [ ] confirmed `!` in the type prefix if API or client breaking change
- [ ] confirmed all author checklist items have been addressed 
- [ ] reviewed state machine logic
- [ ] reviewed API design and naming
- [ ] reviewed documentation is accurate
- [ ] reviewed tests and test coverage
- [ ] manually tested (if applicable)
This commit is contained in:
Julien Robert
2022-02-10 12:07:01 +00:00
committed by GitHub
parent b1f9a117f7
commit 58597139fa
212 changed files with 3792 additions and 3755 deletions
Download Patch File Download Diff File Expand all files Collapse all files
x/staking/README.md
+1 -1
View File
@@ -4,4 +4,4 @@ order: 0
# Staking
- [Staking](spec/README.md) - Proof-of-Stake layer for public blockchains.
* [Staking](spec/README.md) - Proof-of-Stake layer for public blockchains.
x/staking/spec/01_state.md
+31 -31
View File
@@ -13,31 +13,31 @@ Pool is used for tracking bonded and not-bonded token supply of the bond denomin
LastTotalPower tracks the total amounts of bonded tokens recorded during the previous end block.
Store entries prefixed with "Last" must remain unchanged until EndBlock.
- LastTotalPower: `0x12 -> ProtocolBuffer(sdk.Int)`
* LastTotalPower: `0x12 -> ProtocolBuffer(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") -> legacy_amino(params)`
* Params: `Paramsspace("staking") -> legacy_amino(params)`
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.1/proto/cosmos/staking/v1beta1/staking.proto#L230-L241
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.1/proto/cosmos/staking/v1beta1/staking.proto#L230-L241>
## Validator
Validators can have one of three statuses
- `Unbonded`: The validator is not in the active set. They cannot sign blocks and do not earn
* `Unbonded`: The validator is not in the active set. They cannot sign blocks and do not earn
rewards. They can receive delegations.
- `Bonded`": Once the validator receives sufficient bonded tokens they automtically join the
* `Bonded`": Once the validator receives sufficient bonded tokens they automtically join the
active set during [`EndBlock`](./05_end_block.md#validator-set-changes) and their status is updated to `Bonded`.
They are signing blocks and receiving rewards. They can receive further delegations.
They can be slashed for misbehavior. Delegators to this validator who unbond their delegation
must wait the duration of the UnbondingTime, a chain-specific param, during which time
they are still slashable for offences of the source validator if those offences were committed
during the period of time that the tokens were bonded.
- `Unbonding`: When a validator leaves the active set, either by choice or due to slashing, jailing or
* `Unbonding`: When a validator leaves the active set, either by choice or due to slashing, jailing or
tombstoning, an unbonding of all their delegations begins. All delegations must then wait the UnbondingTime
before their tokens are moved to their accounts from the `BondedPool`.
@@ -49,10 +49,10 @@ required lookups for slashing and validator-set updates. A third special index
throughout each block, unlike the first two indices which mirror the validator
records within a block.
- Validators: `0x21 | OperatorAddrLen (1 byte) | OperatorAddr -> ProtocolBuffer(validator)`
- ValidatorsByConsAddr: `0x22 | ConsAddrLen (1 byte) | ConsAddr -> OperatorAddr`
- ValidatorsByPower: `0x23 | BigEndian(ConsensusPower) | OperatorAddrLen (1 byte) | OperatorAddr -> OperatorAddr`
- LastValidatorsPower: `0x11 | OperatorAddrLen (1 byte) | OperatorAddr -> ProtocolBuffer(ConsensusPower)`
* Validators: `0x21 | OperatorAddrLen (1 byte) | OperatorAddr -> ProtocolBuffer(validator)`
* ValidatorsByConsAddr: `0x22 | ConsAddrLen (1 byte) | ConsAddr -> OperatorAddr`
* ValidatorsByPower: `0x23 | BigEndian(ConsensusPower) | OperatorAddrLen (1 byte) | OperatorAddr -> OperatorAddr`
* LastValidatorsPower: `0x11 | OperatorAddrLen (1 byte) | OperatorAddr -> ProtocolBuffer(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
@@ -75,23 +75,23 @@ is updated during the validator set update process which takes place in [`EndBlo
Each validator's state is stored in a `Validator` struct:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/staking.proto#L65-L99
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/staking.proto#L65-L99>
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/staking.proto#L24-L63
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/staking.proto#L24-L63>
## Delegation
Delegations are identified by combining `DelegatorAddr` (the address of the delegator)
with the `ValidatorAddr` Delegators are indexed in the store as follows:
- Delegation: `0x31 | DelegatorAddrLen (1 byte) | DelegatorAddr | ValidatorAddrLen (1 byte) | ValidatorAddr -> ProtocolBuffer(delegation)`
* Delegation: `0x31 | DelegatorAddrLen (1 byte) | DelegatorAddr | ValidatorAddrLen (1 byte) | ValidatorAddr -> ProtocolBuffer(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.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/staking.proto#L159-L170
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/staking.proto#L159-L170>
### Delegator Shares
@@ -120,8 +120,8 @@ detected.
`UnbondingDelegation` are indexed in the store as:
- UnbondingDelegation: `0x32 | DelegatorAddrLen (1 byte) | DelegatorAddr | ValidatorAddrLen (1 byte) | ValidatorAddr -> ProtocolBuffer(unbondingDelegation)`
- UnbondingDelegationsFromValidator: `0x33 | ValidatorAddrLen (1 byte) | ValidatorAddr | DelegatorAddrLen (1 byte) | DelegatorAddr -> nil`
* UnbondingDelegation: `0x32 | DelegatorAddrLen (1 byte) | DelegatorAddr | ValidatorAddrLen (1 byte) | ValidatorAddr -> ProtocolBuffer(unbondingDelegation)`
* UnbondingDelegationsFromValidator: `0x33 | ValidatorAddrLen (1 byte) | ValidatorAddr | DelegatorAddrLen (1 byte) | DelegatorAddr -> 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
@@ -130,7 +130,7 @@ slashed.
A UnbondingDelegation object is created every time an unbonding is initiated.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/staking.proto#L172-L198
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/staking.proto#L172-L198>
## Redelegation
@@ -142,9 +142,9 @@ committed by the source validator.
`Redelegation` are indexed in the store as:
- Redelegations: `0x34 | DelegatorAddrLen (1 byte) | DelegatorAddr | ValidatorAddrLen (1 byte) | ValidatorSrcAddr | ValidatorDstAddr -> ProtocolBuffer(redelegation)`
- RedelegationsBySrc: `0x35 | ValidatorSrcAddrLen (1 byte) | ValidatorSrcAddr | ValidatorDstAddrLen (1 byte) | ValidatorDstAddr | DelegatorAddrLen (1 byte) | DelegatorAddr -> nil`
- RedelegationsByDst: `0x36 | ValidatorDstAddrLen (1 byte) | ValidatorDstAddr | ValidatorSrcAddrLen (1 byte) | ValidatorSrcAddr | DelegatorAddrLen (1 byte) | DelegatorAddr -> nil`
* Redelegations: `0x34 | DelegatorAddrLen (1 byte) | DelegatorAddr | ValidatorAddrLen (1 byte) | ValidatorSrcAddr | ValidatorDstAddr -> ProtocolBuffer(redelegation)`
* RedelegationsBySrc: `0x35 | ValidatorSrcAddrLen (1 byte) | ValidatorSrcAddr | ValidatorDstAddrLen (1 byte) | ValidatorDstAddr | DelegatorAddrLen (1 byte) | DelegatorAddr -> nil`
* RedelegationsByDst: `0x36 | ValidatorDstAddrLen (1 byte) | ValidatorDstAddr | ValidatorSrcAddrLen (1 byte) | ValidatorSrcAddr | DelegatorAddrLen (1 byte) | 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`,
@@ -153,12 +153,12 @@ 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 occur under the situation that:
- the (re)delegator already has another immature redelegation in progress
* the (re)delegator already has another immature 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
* and, the (re)delegator is attempting to create a _new_ redelegation
where the source validator for this new redelegation is `Validator X`.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/staking.proto#L200-L228
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/staking.proto#L200-L228>
## Queues
@@ -167,8 +167,8 @@ 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:
- 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.
@@ -178,25 +178,25 @@ element.
For the purpose of tracking progress of unbonding delegations the unbonding
delegations queue is kept.
- UnbondingDelegation: `0x41 | format(time) -> []DVPair`
* UnbondingDelegation: `0x41 | format(time) -> []DVPair`
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/staking.proto#L123-L133
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/staking.proto#L123-L133>
### RedelegationQueue
For the purpose of tracking progress of redelegations the redelegation queue is
kept.
- RedelegationQueue: `0x42 | format(time) -> []DVVTriplet`
* RedelegationQueue: `0x42 | format(time) -> []DVVTriplet`
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/staking.proto#L140-L152
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/staking.proto#L140-L152>
### ValidatorQueue
For the purpose of tracking progress of unbonding validators the validator
queue is kept.
- ValidatorQueueTime: `0x43 | format(time) -> []sdk.ValAddress`
* ValidatorQueueTime: `0x43 | format(time) -> []sdk.ValAddress`
The stored object as each key is an array of validator operator addresses from
which the validator object can be accessed. Typically it is expected that only
@@ -208,7 +208,7 @@ that multiple validators exist in the queue at the same location.
HistoricalInfo objects are stored and pruned at each block such that the staking keeper persists
the `n` most recent historical info defined by staking module parameter: `HistoricalEntries`.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/staking.proto#L15-L22
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/staking.proto#L15-L22>
At each BeginBlock, the staking keeper will persist the current Header and the Validators that committed
the current block in a `HistoricalInfo` object. The Validators are sorted on their address to ensure that
x/staking/spec/02_state_transitions.md
+45 -45
View File
@@ -24,44 +24,44 @@ directly between all the states, except for from `Bonded` to `Unbonded`.
The following transition occurs when a validator's ranking in the `ValidatorPowerIndex` surpasses
that of the `LastValidator`.
- 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
* 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:
- 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
* 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`
* 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`
Jailed validators are not present in any of the following stores:
- the power store (from consensus power to address)
* the power store (from consensus power to address)
## Delegations
@@ -69,49 +69,49 @@ Jailed validators are not present in any of the following stores:
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`
* 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
- 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
* 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
* 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.
* 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
- transfer the tokens from the `NotBondedPool` `ModuleAccount` to the delegator `Account`
* 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 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,
* 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`
* 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`
* record the token amount in an new entry in the relevant `Redelegation`
From when a redelegation begins until it completes, the delegator is in a state of "pseudo-unbonding", and can still be
slashed for infractions that occured before the redelegation began.
@@ -120,7 +120,7 @@ slashed for infractions that occured before the redelegation began.
When a redelegations complete the following occurs:
- remove the entry from the `Redelegation` object
* remove the entry from the `Redelegation` object
## Slashing
@@ -128,13 +128,13 @@ When a redelegations complete the following occurs:
When a Validator is slashed, the following occurs:
- The total `slashAmount` is calculated as the `slashFactor` (a chain parameter) \* `TokensFromConsensusPower`,
* The total `slashAmount` is calculated as the `slashFactor` (a chain parameter) \* `TokensFromConsensusPower`,
the total number of tokens bonded to the validator at the time of the infraction.
- Every unbonding delegation and pseudo-unbonding redelegation such that the infraction occured before the unbonding or
* Every unbonding delegation and pseudo-unbonding redelegation such that the infraction occured before the unbonding or
redelegation began from the validator are slashed by the `slashFactor` percentage of the initialBalance.
- Each amount slashed from redelegations and unbonding delegations is subtracted from the
* Each amount slashed from redelegations and unbonding delegations is subtracted from the
total slash amount.
- The `remaingSlashAmount` is then slashed from the validator's tokens in the `BondedPool` or
* The `remaingSlashAmount` is then slashed from the validator's tokens in the `BondedPool` or
`NonBondedPool` depending on the validator's status. This reduces the total supply of tokens.
In the case of a slash due to any infraction that requires evidence to submitted (for example double-sign), the slash
x/staking/spec/03_messages.md
+56 -56
View File
@@ -11,20 +11,20 @@ In this section we describe the processing of the staking messages and the corre
A validator is created using the `MsgCreateValidator` message.
The validator must be created with an initial delegation from the operator.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L16-L17
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L16-L17>
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L35-L51
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L35-L51>
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
@@ -36,16 +36,16 @@ in the first end-block.
The `Description`, `CommissionRate` of a validator can be updated using the
`MsgEditValidator` message.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L19-L20
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L19-L20>
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L56-L76
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L56-L76>
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.
@@ -55,16 +55,16 @@ 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`.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L22-L24
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L22-L24>
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L81-L90
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L81-L90>
This message is expected to fail if:
- the validator does not exist
- the `Amount` `Coin` has a denomination different than one defined by `params.BondDenom`
- the exchange rate is invalid, meaning the validator has no tokens (due to slashing) but there are outstanding shares
- the amount delegated is less than the minimum allowed delegation
* the validator does not exist
* the `Amount` `Coin` has a denomination different than one defined by `params.BondDenom`
* the exchange rate is invalid, meaning the validator has no tokens (due to slashing) but there are outstanding shares
* the amount delegated is less than the minimum allowed delegation
If an existing `Delegation` object for provided addresses does not already
exist then it is created as part of this message otherwise the existing
@@ -87,32 +87,32 @@ will not be added to the power index until it is unjailed.
The `MsgUndelegate` message allows delegators to undelegate their tokens from
validator.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L30-L32
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L30-L32>
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L112-L121
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L112-L121>
This message returns a response containing the completion time of the undelegation:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L123-L126
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L123-L126>
This message is expected to fail if:
- 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`
* 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.
![Unbond sequence](../../../docs/uml/svg/unbond_sequence.svg)
@@ -122,33 +122,33 @@ The redelegation command allows delegators to instantly switch validators. Once
the unbonding period has passed, the redelegation is automatically completed in
the EndBlocker.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L26-L28
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L26-L28>
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L95-L105
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L95-L105>
This message returns a response containing the completion time of the redelegation:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L107-L110
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L107-L110>
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 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`
* 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.
![Begin redelegation sequence](../../../docs/uml/svg/begin_redelegation_sequence.svg)
x/staking/spec/05_end_block.md
+9 -9
View File
@@ -15,12 +15,12 @@ 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
* 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
* 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
* 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
@@ -62,9 +62,9 @@ switched from `types.Unbonding` to
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
* 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
@@ -72,6 +72,6 @@ Complete the unbonding of all mature `UnbondingDelegations.Entries` within the
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
* remove the mature entry from `Redelegation.Entries`
* remove the `Redelegation` object from the store if there are no
remaining entries.
x/staking/spec/06_hooks.md
+16 -16
View File
@@ -9,19 +9,19 @@ occurred within staking. These events can be registered to execute either
right `Before` or `After` the staking event (as per the hook name). The
following hooks can registered with staking:
- `AfterValidatorCreated(Context, ValAddress) error`
- called when a validator is created
- `BeforeValidatorModified(Context, ValAddress) error`
- called when a validator's state is changed
- `AfterValidatorRemoved(Context, ConsAddress, ValAddress) error`
- called when a validator is deleted
- `AfterValidatorBonded(Context, ConsAddress, ValAddress) error`
- called when a validator is bonded
- `AfterValidatorBeginUnbonding(Context, ConsAddress, ValAddress) error`
- called when a validator begins unbonding
- `BeforeDelegationCreated(Context, AccAddress, ValAddress) error`
- called when a delegation is created
- `BeforeDelegationSharesModified(Context, AccAddress, ValAddress) error`
- called when a delegation's shares are modified
- `BeforeDelegationRemoved(Context, AccAddress, ValAddress) error`
- called when a delegation is removed
* `AfterValidatorCreated(Context, ValAddress) error`
* called when a validator is created
* `BeforeValidatorModified(Context, ValAddress) error`
* called when a validator's state is changed
* `AfterValidatorRemoved(Context, ConsAddress, ValAddress) error`
* called when a validator is deleted
* `AfterValidatorBonded(Context, ConsAddress, ValAddress) error`
* called when a validator is bonded
* `AfterValidatorBeginUnbonding(Context, ConsAddress, ValAddress) error`
* called when a validator begins unbonding
* `BeforeDelegationCreated(Context, AccAddress, ValAddress) error`
* called when a delegation is created
* `BeforeDelegationSharesModified(Context, AccAddress, ValAddress) error`
* called when a delegation's shares are modified
* `BeforeDelegationRemoved(Context, AccAddress, ValAddress) error`
* called when a delegation is removed
x/staking/spec/07_events.md
+2 -2
View File
@@ -61,7 +61,7 @@ The staking module emits the following events:
| message | action | begin_unbonding |
| message | sender | {senderAddress} |
- [0] Time is formatted in the RFC3339 standard
* [0] Time is formatted in the RFC3339 standard
### MsgBeginRedelegate
@@ -75,4 +75,4 @@ The staking module emits the following events:
| message | action | begin_redelegate |
| message | sender | {senderAddress} |
- [0] Time is formatted in the RFC3339 standard
* [0] Time is formatted in the RFC3339 standard
x/staking/spec/README.md
+22 -22
View File
@@ -24,32 +24,32 @@ network.
## Contents
1. **[State](01_state.md)**
- [Pool](01_state.md#pool)
- [LastTotalPower](01_state.md#lasttotalpower)
- [Params](01_state.md#params)
- [Validator](01_state.md#validator)
- [Delegation](01_state.md#delegation)
- [UnbondingDelegation](01_state.md#unbondingdelegation)
- [Redelegation](01_state.md#redelegation)
- [Queues](01_state.md#queues)
- [HistoricalInfo](01_state.md#historicalinfo)
* [Pool](01_state.md#pool)
* [LastTotalPower](01_state.md#lasttotalpower)
* [Params](01_state.md#params)
* [Validator](01_state.md#validator)
* [Delegation](01_state.md#delegation)
* [UnbondingDelegation](01_state.md#unbondingdelegation)
* [Redelegation](01_state.md#redelegation)
* [Queues](01_state.md#queues)
* [HistoricalInfo](01_state.md#historicalinfo)
2. **[State Transitions](02_state_transitions.md)**
- [Validators](02_state_transitions.md#validators)
- [Delegations](02_state_transitions.md#delegations)
- [Slashing](02_state_transitions.md#slashing)
* [Validators](02_state_transitions.md#validators)
* [Delegations](02_state_transitions.md#delegations)
* [Slashing](02_state_transitions.md#slashing)
3. **[Messages](03_messages.md)**
- [MsgCreateValidator](03_messages.md#msgcreatevalidator)
- [MsgEditValidator](03_messages.md#msgeditvalidator)
- [MsgDelegate](03_messages.md#msgdelegate)
- [MsgUndelegate](03_messages.md#msgundelegate)
- [MsgBeginRedelegate](03_messages.md#msgbeginredelegate)
* [MsgCreateValidator](03_messages.md#msgcreatevalidator)
* [MsgEditValidator](03_messages.md#msgeditvalidator)
* [MsgDelegate](03_messages.md#msgdelegate)
* [MsgUndelegate](03_messages.md#msgundelegate)
* [MsgBeginRedelegate](03_messages.md#msgbeginredelegate)
4. **[Begin-Block](04_begin_block.md)**
- [Historical Info Tracking](04_begin_block.md#historical-info-tracking)
* [Historical Info Tracking](04_begin_block.md#historical-info-tracking)
5. **[End-Block](05_end_block.md)**
- [Validator Set Changes](05_end_block.md#validator-set-changes)
- [Queues](05_end_block.md#queues-)
* [Validator Set Changes](05_end_block.md#validator-set-changes)
* [Queues](05_end_block.md#queues-)
6. **[Hooks](06_hooks.md)**
7. **[Events](07_events.md)**
- [EndBlocker](07_events.md#endblocker)
- [Msg's](07_events.md#msg's)
* [EndBlocker](07_events.md#endblocker)
* [Msg's](07_events.md#msg's)
8. **[Parameters](08_params.md)**