docs: Update x/staking spec (#8395)

* Finish updating state

* Add messages

* Update events

* proto-gen

* Update proto/cosmos/staking/v1beta1/staking.proto

Co-authored-by: Anil Kumar Kammari <[email protected]>

* progo-gen

* Update Msg with slash

* Rerun proto docs

Co-authored-by: Anil Kumar Kammari <[email protected]>
Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>

Author: 3 people

docs/core/proto-docs.md

@@ -27,12 +27,15 @@ message CommissionRates {
   option (gogoproto.equal)            = true;
   option (gogoproto.goproto_stringer) = false;
 
+  // rate is the commission rate charged to delegators, as a fraction.
   string rate     = 1 [(gogoproto.customtype) = "github.com/cosmos/cosmos-sdk/types.Dec", (gogoproto.nullable) = false];
+  // max_rate defines the maximum commission rate which validator can ever charge, as a fraction.
   string max_rate = 2 [
     (gogoproto.moretags)   = "yaml:\"max_rate\"",
     (gogoproto.customtype) = "github.com/cosmos/cosmos-sdk/types.Dec",
     (gogoproto.nullable)   = false
   ];
+  // max_change_rate defines the maximum daily increase of the validator commission, as a fraction.
   string max_change_rate = 3 [
     (gogoproto.moretags)   = "yaml:\"max_change_rate\"",
     (gogoproto.customtype) = "github.com/cosmos/cosmos-sdk/types.Dec",
@@ -45,7 +48,9 @@ message Commission {
   option (gogoproto.equal)            = true;
   option (gogoproto.goproto_stringer) = false;
 
+  // commission_rates defines the initial commission rates to be used for creating a validator.
   CommissionRates           commission_rates = 1 [(gogoproto.embed) = true, (gogoproto.nullable) = false];
+  // update_time is the last time the commission rate was changed.
   google.protobuf.Timestamp update_time      = 2
       [(gogoproto.nullable) = false, (gogoproto.stdtime) = true, (gogoproto.moretags) = "yaml:\"update_time\""];
 }
@@ -55,10 +60,15 @@ message Description {
   option (gogoproto.equal)            = true;
   option (gogoproto.goproto_stringer) = false;
 
+  // moniker defines a human-readable name for the validator.
   string moniker          = 1;
+  // identity defines an optional identity signature (ex. UPort or Keybase).
   string identity         = 2;
+  // website defines an optional website link.
   string website          = 3;
+  // security_contact defines an optional email for security contact.
   string security_contact = 4 [(gogoproto.moretags) = "yaml:\"security_contact\""];
+  // details define other optional details.
   string details          = 5;
 }
 
@@ -75,22 +85,33 @@ message Validator {
   option (gogoproto.goproto_stringer) = false;
   option (gogoproto.goproto_getters)  = false;
 
+  // operator_address defines the address of the validator's operator; bech encoded in JSON.
   string              operator_address = 1 [(gogoproto.moretags) = "yaml:\"operator_address\""];
+  // consensus_pubkey is the consensus public key of the validator, as a Protobuf Any.
   google.protobuf.Any consensus_pubkey = 2
       [(cosmos_proto.accepts_interface) = "cosmos.crypto.PubKey", (gogoproto.moretags) = "yaml:\"consensus_pubkey\""];
+  // jailed defined whether the validator has been jailed from bonded status or not.
   bool       jailed = 3;
+  // status is the validator status (bonded/unbonding/unbonded).
   BondStatus status = 4;
+  // tokens define the delegated tokens (incl. self-delegation).
   string tokens = 5 [(gogoproto.customtype) = "github.com/cosmos/cosmos-sdk/types.Int", (gogoproto.nullable) = false];
+  // delegator_shares defines total shares issued to a validator's delegators.
   string delegator_shares = 6 [
     (gogoproto.moretags)   = "yaml:\"delegator_shares\"",
     (gogoproto.customtype) = "github.com/cosmos/cosmos-sdk/types.Dec",
     (gogoproto.nullable)   = false
   ];
+  // description defines the description terms for the validator.
   Description               description      = 7 [(gogoproto.nullable) = false];
+  // unbonding_height defines, if unbonding, the height at which this validator has begun unbonding.
   int64                     unbonding_height = 8 [(gogoproto.moretags) = "yaml:\"unbonding_height\""];
+  // unbonding_time defines, if unbonding, the min time for the validator to complete unbonding.
   google.protobuf.Timestamp unbonding_time   = 9
       [(gogoproto.nullable) = false, (gogoproto.stdtime) = true, (gogoproto.moretags) = "yaml:\"unbonding_time\""];
+  // commission defines the commission parameters.
   Commission commission          = 10 [(gogoproto.nullable) = false];
+  // min_self_delegation is the validator's self declared minimum self delegation.
   string     min_self_delegation = 11 [
     (gogoproto.moretags)   = "yaml:\"min_self_delegation\"",
     (gogoproto.customtype) = "github.com/cosmos/cosmos-sdk/types.Int",
@@ -164,8 +185,11 @@ message Delegation {
   option (gogoproto.goproto_getters)  = false;
   option (gogoproto.goproto_stringer) = false;
 
+  // delegator_address is the bech32-encoded address of the delegator.
   string delegator_address = 1 [(gogoproto.moretags) = "yaml:\"delegator_address\""];
+  // validator_address is the bech32-encoded address of the validator.
   string validator_address = 2 [(gogoproto.moretags) = "yaml:\"validator_address\""];
+  // shares define the delegation shares received.
   string shares = 3 [(gogoproto.customtype) = "github.com/cosmos/cosmos-sdk/types.Dec", (gogoproto.nullable) = false];
 }
 
@@ -176,8 +200,11 @@ message UnbondingDelegation {
   option (gogoproto.goproto_getters)  = false;
   option (gogoproto.goproto_stringer) = false;
 
+  // delegator_address is the bech32-encoded address of the delegator.
   string                            delegator_address = 1 [(gogoproto.moretags) = "yaml:\"delegator_address\""];
+  // validator_address is the bech32-encoded address of the validator.
   string                            validator_address = 2 [(gogoproto.moretags) = "yaml:\"validator_address\""];
+  // entries are the unbonding delegation entries.
   repeated UnbondingDelegationEntry entries = 3 [(gogoproto.nullable) = false]; // unbonding delegation entries
 }
 
@@ -186,14 +213,18 @@ message UnbondingDelegationEntry {
   option (gogoproto.equal)            = true;
   option (gogoproto.goproto_stringer) = false;
 
+  // creation_height is the height which the unbonding took place.
   int64                     creation_height = 1 [(gogoproto.moretags) = "yaml:\"creation_height\""];
+  // completion_time is the unix time for unbonding completion.
   google.protobuf.Timestamp completion_time = 2
       [(gogoproto.nullable) = false, (gogoproto.stdtime) = true, (gogoproto.moretags) = "yaml:\"completion_time\""];
+  // initial_balance defines the tokens initially scheduled to receive at completion.
   string initial_balance = 3 [
     (gogoproto.customtype) = "github.com/cosmos/cosmos-sdk/types.Int",
     (gogoproto.nullable)   = false,
     (gogoproto.moretags)   = "yaml:\"initial_balance\""
   ];
+  // balance defines the tokens to receive at completion.
   string balance = 4 [(gogoproto.customtype) = "github.com/cosmos/cosmos-sdk/types.Int", (gogoproto.nullable) = false];
 }
 
@@ -202,14 +233,18 @@ message RedelegationEntry {
   option (gogoproto.equal)            = true;
   option (gogoproto.goproto_stringer) = false;
 
+  // creation_height  defines the height which the redelegation took place.
   int64                     creation_height = 1 [(gogoproto.moretags) = "yaml:\"creation_height\""];
+  // completion_time defines the unix time for redelegation completion.
   google.protobuf.Timestamp completion_time = 2
       [(gogoproto.nullable) = false, (gogoproto.stdtime) = true, (gogoproto.moretags) = "yaml:\"completion_time\""];
+  // initial_balance defines the initial balance when redelegation started.
   string initial_balance = 3 [
     (gogoproto.customtype) = "github.com/cosmos/cosmos-sdk/types.Int",
     (gogoproto.nullable)   = false,
     (gogoproto.moretags)   = "yaml:\"initial_balance\""
   ];
+  // shares_dst is the amount of destination-validator shares created by redelegation.
   string shares_dst = 4
       [(gogoproto.customtype) = "github.com/cosmos/cosmos-sdk/types.Dec", (gogoproto.nullable) = false];
 }
@@ -221,9 +256,13 @@ message Redelegation {
   option (gogoproto.goproto_getters)  = false;
   option (gogoproto.goproto_stringer) = false;
 
+  // delegator_address is the bech32-encoded address of the delegator.
   string                     delegator_address     = 1 [(gogoproto.moretags) = "yaml:\"delegator_address\""];
+  // validator_src_address is the validator redelegation source operator address.
   string                     validator_src_address = 2 [(gogoproto.moretags) = "yaml:\"validator_src_address\""];
+  // validator_dst_address is the validator redelegation destination operator address.
   string                     validator_dst_address = 3 [(gogoproto.moretags) = "yaml:\"validator_dst_address\""];
+  // entries are the redelegation entries.
   repeated RedelegationEntry entries               = 4 [(gogoproto.nullable) = false]; // redelegation entries
 }
 
@@ -232,11 +271,16 @@ message Params {
   option (gogoproto.equal)            = true;
   option (gogoproto.goproto_stringer) = false;
 
+  // unbonding_time is the time duration of unbonding.
   google.protobuf.Duration unbonding_time = 1
       [(gogoproto.nullable) = false, (gogoproto.stdduration) = true, (gogoproto.moretags) = "yaml:\"unbonding_time\""];
+  // max_validators is the maximum number of validators.
   uint32 max_validators     = 2 [(gogoproto.moretags) = "yaml:\"max_validators\""];
+  // max_entries is the max entries for either unbonding delegation or redelegation (per pair/trio).
   uint32 max_entries        = 3 [(gogoproto.moretags) = "yaml:\"max_entries\""];
+  // historical_entries is the number of historical entries to persist.
   uint32 historical_entries = 4 [(gogoproto.moretags) = "yaml:\"historical_entries\""];
+  // bond_denom defines the bondable coin denomination.
   string bond_denom         = 5 [(gogoproto.moretags) = "yaml:\"bond_denom\""];
 }