Skip to content

Commit

Permalink
docs(x/staking): update readme (#22216)
Browse files Browse the repository at this point in the history 
(cherry picked from commit db6a835)
  • Loading branch information
@JulianToledano @mergify
JulianToledano authored and mergify[bot] committed Oct 10, 2024
1 parent f4d3000 commit 1d295a7
Show file tree
Hide file tree
Showing 2 changed files with 45 additions and 43 deletions.
76 changes: 38 additions & 38 deletions x/staking/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -69,20 +69,20 @@ 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(math.Int)`
* LastTotalPower: `collections.NewPrefix(18)`

### UnbondingID

UnbondingID stores the ID of the latest unbonding operation. It enables creating unique IDs for unbonding operations, i.e., UnbondingID is incremented every time a new unbonding operation (validator unbonding, unbonding delegation, redelegation) is initiated.

* UnbondingID: `0x37 -> uint64`
* UnbondingID: `55`

### Params

The staking module stores its params in state with the prefix of `0x51`,
it can be updated with governance or the address with authority.

* Params: `0x51 | ProtocolBuffer(Params)`
* Params: `81`

```protobuf reference
https://github.com/cosmos/cosmos-sdk/blob/release/v0.52.x/x/staking/proto/cosmos/staking/v1beta1/staking.proto#L300-L328
Expand Down Expand Up @@ -117,18 +117,18 @@ 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)`
* ValidatorsByUnbondingID: `0x38 | UnbondingID -> 0x21 | OperatorAddrLen (1 byte) | OperatorAddr`
* Validators: `33 | OperatorAddrLen (1 byte) | OperatorAddr -> ProtocolBuffer(validator)`
* ValidatorsByConsAddr: `34 | ConsAddrLen (1 byte) | ConsAddr -> OperatorAddr`
* ValidatorsByPower: `23 | BigEndian(ConsensusPower) | OperatorAddrLen (1 byte) | OperatorAddr -> OperatorAddr`
* LastValidatorsPower: `17 | OperatorAddrLen (1 byte) | OperatorAddr -> ProtocolBuffer(ConsensusPower)`
* UnbondingIndex: `56 | UnbondingID -> 21 | OperatorAddrLen (1 byte) | OperatorAddr`

`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
future. Delegators can refer to the immutable operator of the validator, without
concern for the changing public key.

`ValidatorsByUnbondingID` is an additional index that enables lookups for
`UnbondingIndex` is an additional index that enables lookups for
validators by the unbonding IDs corresponding to their current unbonding.

`ValidatorByConsAddr` is an additional index that enables lookups for slashing.
Expand Down Expand Up @@ -161,9 +161,9 @@ https://github.com/cosmos/cosmos-sdk/blob/release/v0.52.x/x/staking/proto/cosmos
### Delegation

Delegations are identified by combining `DelegatorAddr` (the address of the delegator)
with the `ValidatorAddr` Delegators are indexed in the store as follows:
with the `ValidatorAddr`. Delegators are indexed in the store as follows:

* Delegation: `0x31 | DelegatorAddrLen (1 byte) | DelegatorAddr | ValidatorAddrLen (1 byte) | ValidatorAddr -> ProtocolBuffer(delegation)`
* Delegation: `49 | 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
Expand All @@ -183,7 +183,7 @@ validator and the number of shares issued so far:
`Shares per Token = validator.TotalShares() / validator.Tokens()`

Only the number of shares received is stored on the DelegationEntry. When a delegator then
Undelegates, the token amount they receive is calculated from the number of shares they currently
undelegates, the token amount they receive is calculated from the number of shares they currently
hold and the inverse exchange rate:

`Tokens per Share = validator.Tokens() / validatorShares()`
Expand All @@ -201,17 +201,17 @@ 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`
* UnbondingDelegationByUnbondingId: `0x38 | UnbondingId -> 0x32 | DelegatorAddrLen (1 byte) | DelegatorAddr | ValidatorAddrLen (1 byte) | ValidatorAddr`
* UnbondingDelegation: `50 | DelegatorAddrLen (1 byte) | DelegatorAddr | ValidatorAddrLen (1 byte) | ValidatorAddr -> ProtocolBuffer(unbondingDelegation)`
* UnbondingDelegationByValIndex: `51 | ValidatorAddrLen (1 byte) | ValidatorAddr | DelegatorAddrLen (1 byte) | DelegatorAddr -> nil`
* UnbondingIndex: `56 | UnbondingId -> 0x32 | DelegatorAddrLen (1 byte) | DelegatorAddr | ValidatorAddrLen (1 byte) | ValidatorAddr`
`UnbondingDelegation` is used in queries, to lookup all unbonding delegations for
a given delegator.

`UnbondingDelegationsFromValidator` is used in slashing, to lookup all
`UnbondingDelegationByValIndex` is used in slashing, to lookup all
unbonding delegations associated with a given validator that need to be
slashed.

`UnbondingDelegationByUnbondingId` is an additional index that enables
`UnbondingIndex` is an additional index that enables
lookups for unbonding delegations by the unbonding IDs of the containing
unbonding delegation entries.

Expand All @@ -232,23 +232,23 @@ 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`
* RedelegationByUnbondingId: `0x38 | UnbondingId -> 0x34 | DelegatorAddrLen (1 byte) | DelegatorAddr | ValidatorAddrLen (1 byte) | ValidatorSrcAddr | ValidatorDstAddr`
* Redelegations: `52 | DelegatorAddrLen (1 byte) | DelegatorAddr | ValidatorAddrLen (1 byte) | ValidatorSrcAddr | ValidatorDstAddrLen (1 byte) | ValidatorDstAddr -> ProtocolBuffer(redelegation)`
* RedelegationsByValSrc: `53 | ValidatorSrcAddrLen (1 byte) | ValidatorSrcAddr | ValidatorDstAddrLen (1 byte) | ValidatorDstAddr | DelegatorAddrLen (1 byte) | DelegatorAddr -> nil`
* RedelegationsByValDst: `54 | ValidatorDstAddrLen (1 byte) | ValidatorDstAddr | ValidatorSrcAddrLen (1 byte) | ValidatorSrcAddr | DelegatorAddrLen (1 byte) | DelegatorAddr -> nil`
* RedelegationByUnbondingId: `56 | UnbondingId -> 0x34 | DelegatorAddrLen (1 byte) | DelegatorAddr | ValidatorAddrLen (1 byte) | ValidatorSrcAddr | ValidatorDstAddr`

`Redelegations` is used for queries, to lookup all redelegations for a given
delegator.

`RedelegationsBySrc` is used for slashing based on the `ValidatorSrcAddr`.
`RedelegationsByValSrc` is used for slashing based on the `ValidatorSrcAddr`.

`RedelegationsByDst` is used for slashing based on the `ValidatorDstAddr`
`RedelegationsByValDst` is used for slashing based on the `ValidatorDstAddr`

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`,
while the third map is for slashing based on the `ValidatorDstAddr`.

`RedelegationByUnbondingId` is an additional index that enables
`UnbondingIndex` is an additional index that enables
lookups for redelegations by the unbonding IDs of the containing
redelegation entries.

Expand Down Expand Up @@ -317,7 +317,7 @@ element.
For the purpose of tracking progress of unbonding delegations the unbonding
delegations queue is kept.

* UnbondingDelegation: `0x41 | format(time) -> []DVPair`
* UnbondingQueue: `65 | format(time) -> []DVPair`

```protobuf reference
https://github.com/cosmos/cosmos-sdk/blob/release/v0.52.x/x/staking/proto/cosmos/staking/v1beta1/staking.proto#L159-L173
Expand All @@ -328,7 +328,7 @@ https://github.com/cosmos/cosmos-sdk/blob/release/v0.52.x/x/staking/proto/cosmos
For the purpose of tracking progress of redelegations the redelegation queue is
kept.

* RedelegationQueue: `0x42 | format(time) -> []DVVTriplet`
* RedelegationQueue: `66 | format(time) -> []DVVTriplet`

```protobuf reference
https://github.com/cosmos/cosmos-sdk/blob/release/v0.52.x/x/staking/proto/cosmos/staking/v1beta1/staking.proto#L175-L191
Expand All @@ -339,7 +339,7 @@ https://github.com/cosmos/cosmos-sdk/blob/release/v0.52.x/x/staking/proto/cosmos
For the purpose of tracking progress of unbonding validators the validator
queue is kept.

* ValidatorQueueTime: `0x43 | format(time) -> []sdk.ValAddress`
* ValidatorQueue: `67 | format(time) -> []sdk.ValAddress`

The stored object by each key is an array of validator operator addresses from
which the validator object can be accessed. Typically it is expected that only
Expand All @@ -348,7 +348,7 @@ that multiple validators exist in the queue at the same location.

#### ValidatorConsensusKeyRotationRecordQueueKey

For the purpose of tracking progress or consensus pubkey rotations the `ValidatorConsensusKeyRotationRecordQueueKey` kept.
For the purpose of tracking progress of consensus pubkey rotations, the `ValidatorConsensusKeyRotationRecordQueueKey` is kept.

* ValidatorConsensusKeyRotationRecordQueueKey: `103 | format(time) -> types.ValAddrsOfRotatedConsKeys`

Expand All @@ -361,9 +361,6 @@ the present store info and append the `ValAddress` to the array and set it back
https://github.com/cosmos/cosmos-sdk/blob/release/v0.52.x/x/staking/proto/cosmos/staking/v1beta1/staking.proto#L420-L424
```




## State Transitions

### Validators
Expand Down Expand Up @@ -401,7 +398,7 @@ When a validator begins the unbonding process the following operations occur:
#### Unbonding to Unbonded

A validator moves from unbonding to unbonded when the `ValidatorQueue` object
moves from bonded to unbonded
moves from bonded to unbonded.

* update the `Validator` object for this validator
* set `validator.Status` to `Unbonded`
Expand All @@ -423,7 +420,7 @@ Jailed validators are not present in any of the following stores:

#### Delegate

When a delegation occurs both the validator and the delegation objects are affected
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
Expand Down Expand Up @@ -894,10 +891,12 @@ following hooks can registered with staking:
* called when a delegation is created
* `BeforeDelegationSharesModified(Context, AccAddress, ValAddress) error`
* called when a delegation's shares are modified
* `AfterDelegationModified(Context, AccAddress, ValAddress) error`
* called when a delegation is created or modified
* `BeforeDelegationRemoved(Context, AccAddress, ValAddress) error`
* called when a delegation is removed
* `AfterDelegationModified(Context, AccAddress, ValAddress) error`
* called when a delegation is created or modified
* `BeforeValidatorSlashed(Context, sdk.ValAddress, math.LegacyDec) error`
* called when a validator is slashed
* `AfterUnbondingInitiated(Context, UnbondingID)`
* called when an unbonding operation (validator unbonding, unbonding delegation, redelegation) was initiated
* `AfterConsensusPubKeyUpdate(ctx Context, oldpubkey, newpubkey types.PubKey, fee sdk.Coin)`
Expand All @@ -916,11 +915,9 @@ The staking module emits the following events:
| complete_unbonding | validator | {validatorAddress} |
| complete_unbonding | delegator | {delegatorAddress} |
| complete_redelegation | amount | {totalRedelegationAmount} |
| complete_redelegation | delegator | {delegatorAddress} |
| complete_redelegation | source_validator | {srcValidatorAddress} |
| complete_redelegation | destination_validator | {dstValidatorAddress} |
| complete_redelegation | delegator | {delegatorAddress} |

## Msg's

### MsgCreateValidator

Expand All @@ -947,7 +944,9 @@ The staking module emits the following events:
| Type | Attribute Key | Attribute Value |
| -------- | ------------- | ------------------ |
| delegate | validator | {validatorAddress} |
| delegate | delegator | {delegatorAddress} |
| delegate | amount | {delegationAmount} |
| delegate | new_shares | {newShares} |
| message | module | staking |
| message | action | delegate |
| message | sender | {senderAddress} |
Expand All @@ -957,6 +956,7 @@ The staking module emits the following events:
| Type | Attribute Key | Attribute Value |
| ------- | ------------------- | ------------------ |
| unbond | validator | {validatorAddress} |
| unbond | delegator | {delegatorAddress} |
| unbond | amount | {unbondAmount} |
| unbond | completion_time [0] | {completionTime} |
| message | module | staking |
Expand Down
12 changes: 7 additions & 5 deletions x/staking/types/params.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,10 +19,11 @@ const (
// TODO: Justify our choice of default here.
DefaultUnbondingTime time.Duration = time.Hour * 24 * 7 * 3

// Default maximum number of bonded validators
// DefaultMaxValidators is the default maximum number of bonded validators.
DefaultMaxValidators uint32 = 100

// Default maximum entries in a UBD/RED pair
// DefaultMaxEntries is the default maximum number of entries
// in a UBD (Unbonding Delegation) or RED (Redelegation) pair.
DefaultMaxEntries uint32 = 7
)

Expand Down Expand Up @@ -63,7 +64,7 @@ func DefaultParams() Params {
)
}

// unmarshal the current staking params value from store key or panic
// MustUnmarshalParams unmarshal the current staking params value from store key or panic
func MustUnmarshalParams(cdc *codec.LegacyAmino, value []byte) Params {
params, err := UnmarshalParams(cdc, value)
if err != nil {
Expand All @@ -73,7 +74,7 @@ func MustUnmarshalParams(cdc *codec.LegacyAmino, value []byte) Params {
return params
}

// unmarshal the current staking params value from store key
// UnmarshalParams unmarshal the current staking params value from store key
func UnmarshalParams(cdc *codec.LegacyAmino, value []byte) (params Params, err error) {
err = cdc.Unmarshal(value, &params)
if err != nil {
Expand All @@ -83,7 +84,7 @@ func UnmarshalParams(cdc *codec.LegacyAmino, value []byte) (params Params, err e
return
}

// validate a set of params
// Validate validates a set of params
func (p Params) Validate() error {
if err := validateUnbondingTime(p.UnbondingTime); err != nil {
return err
Expand Down Expand Up @@ -181,6 +182,7 @@ func validateBondDenom(i interface{}) error {
return nil
}

// ValidatePowerReduction validates the PowerReduction parameter.
func ValidatePowerReduction(i interface{}) error {
v, ok := i.(math.Int)
if !ok {
Expand Down

0 comments on commit 1d295a7

Please sign in to comment.