Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs(x/staking): update readme (backport #22216) #22221

Merged
merged 1 commit into from
Oct 10, 2024
Merged

docs(x/staking): update readme (backport #22216) #22221

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
76 changes: 38 additions & 38 deletions x/staking/README.md
View file
Open in desktop
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
Open in desktop
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
Loading