Staking

The staking module is responsible for supporting an advanced Proof-of-Stake (PoS) system. In this system, holders of the native staking token of the chain can become validators and can delegate tokens to validators, ultimately determining the effective validator set for the system.

For more information, visit https://docs.cosmos.network/main/modules/staking/

Message Types

Msg defines the staking Msg service.

tx.proto

service Msg {
  // CreateValidator defines a method for creating a new validator.
  rpc CreateValidator(MsgCreateValidator) returns (MsgCreateValidatorResponse);

  // EditValidator defines a method for editing an existing validator.
  rpc EditValidator(MsgEditValidator) returns (MsgEditValidatorResponse);

  // Delegate defines a method for performing a delegation of coins
  // from a delegator to a validator.
  rpc Delegate(MsgDelegate) returns (MsgDelegateResponse);

  // BeginRedelegate defines a method for performing a redelegation
  // of coins from a delegator and source validator to a destination validator.
  rpc BeginRedelegate(MsgBeginRedelegate) returns (MsgBeginRedelegateResponse);

  // Undelegate defines a method for performing an undelegation from a
  // delegate and a validator.
  rpc Undelegate(MsgUndelegate) returns (MsgUndelegateResponse);

  // CancelUnbondingDelegation defines a method for performing canceling the unbonding delegation
  // and delegate back to previous validator.
  rpc CancelUnbondingDelegation(MsgCancelUnbondingDelegation) returns (MsgCancelUnbondingDelegationResponse);
}

MsgCreateValidator

MsgCreateValidator defines an SDK message for creating a new validator.

tx.proto

message MsgCreateValidator {
  // NOTE(fdymylja): this is a particular case in which
  // if validator_address == delegator_address then only one
  // is expected to sign, otherwise both are.
  option (cosmos.msg.v1.signer) = "delegator_address";
  option (cosmos.msg.v1.signer) = "validator_address";

  option (gogoproto.equal)           = false;
  option (gogoproto.goproto_getters) = false;

  Description     description         = 1 [(gogoproto.nullable) = false];
  CommissionRates commission          = 2 [(gogoproto.nullable) = false];
  string          min_self_delegation = 3 [
    (cosmos_proto.scalar)  = "cosmos.Int",
    (gogoproto.customtype) = "github.com/cosmos/cosmos-sdk/types.Int",
    (gogoproto.nullable)   = false
  ];
  string                   delegator_address = 4 [(cosmos_proto.scalar) = "cosmos.AddressString"];
  string                   validator_address = 5 [(cosmos_proto.scalar) = "cosmos.AddressString"];
  google.protobuf.Any      pubkey            = 6 [(cosmos_proto.accepts_interface) = "cosmos.crypto.PubKey"];
  cosmos.base.v1beta1.Coin value             = 7 [(gogoproto.nullable) = false];
}

MsgCreateValidatorResponse

MsgCreateValidatorResponse defines the Msg/CreateValidator response type.

tx.proto

message MsgCreateValidatorResponse {}

MsgEditValidator

MsgEditValidator defines an SDK message for editing an existing validator.

tx.proto

message MsgEditValidator {
  option (cosmos.msg.v1.signer) = "validator_address";

  option (gogoproto.equal)           = false;
  option (gogoproto.goproto_getters) = false;

  Description description       = 1 [(gogoproto.nullable) = false];
  string      validator_address = 2 [(cosmos_proto.scalar) = "cosmos.AddressString"];

  // We pass a reference to the new commission rate and min self delegation as
  // it's not mandatory to update. If not updated, the deserialized rate will be
  // zero with no way to distinguish if an update was intended.
  // REF: #2373
  string commission_rate = 3
      [(cosmos_proto.scalar) = "cosmos.Dec", (gogoproto.customtype) = "github.com/cosmos/cosmos-sdk/types.Dec"];
  string min_self_delegation = 4
      [(cosmos_proto.scalar) = "cosmos.Int", (gogoproto.customtype) = "github.com/cosmos/cosmos-sdk/types.Int"];
}

MsgEditValidatorResponse

MsgEditValidatorResponse defines the Msg/EditValidator response type.

tx.proto

message MsgEditValidatorResponse {}

MsgDelegate

MsgDelegate defines an SDK message for performing a delegation of coins from a delegator to a validator.

tx.proto

message MsgDelegate {
  option (cosmos.msg.v1.signer) = "delegator_address";

  option (gogoproto.equal)           = false;
  option (gogoproto.goproto_getters) = false;

  string                   delegator_address = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
  string                   validator_address = 2 [(cosmos_proto.scalar) = "cosmos.AddressString"];
  cosmos.base.v1beta1.Coin amount            = 3 [(gogoproto.nullable) = false];
}

MsgDelegateResponse

MsgDelegateResponse defines the Msg/Delegate response type.

tx.proto

message MsgDelegateResponse {}

MsgBeginRedelegate

MsgBeginRedelegate defines an SDK message for performing a redelegation of coins from a delegator and source validator to a destination validator.

tx.proto

message MsgBeginRedelegate {
  option (cosmos.msg.v1.signer) = "delegator_address";

  option (gogoproto.equal)           = false;
  option (gogoproto.goproto_getters) = false;

  string                   delegator_address     = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
  string                   validator_src_address = 2 [(cosmos_proto.scalar) = "cosmos.AddressString"];
  string                   validator_dst_address = 3 [(cosmos_proto.scalar) = "cosmos.AddressString"];
  cosmos.base.v1beta1.Coin amount                = 4 [(gogoproto.nullable) = false];
}

MsgBeginRedelegateResponse

MsgBeginRedelegateResponse defines the Msg/BeginRedelegate response type.

tx.proto

message MsgBeginRedelegateResponse {
  google.protobuf.Timestamp completion_time = 1 [(gogoproto.nullable) = false, (gogoproto.stdtime) = true];
}

MsgUndelegate

MsgUndelegate defines a SDK message for performing an undelegation from a delegate and a validator.

tx.proto

message MsgUndelegate {
  option (cosmos.msg.v1.signer) = "delegator_address";

  option (gogoproto.equal)           = false;
  option (gogoproto.goproto_getters) = false;

  string                   delegator_address = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
  string                   validator_address = 2 [(cosmos_proto.scalar) = "cosmos.AddressString"];
  cosmos.base.v1beta1.Coin amount            = 3 [(gogoproto.nullable) = false];
}

MsgUndelegateResponse

MsgUndelegateResponse defines the Msg/Undelegate response type.

tx.proto

message MsgUndelegateResponse {
  google.protobuf.Timestamp completion_time = 1 [(gogoproto.nullable) = false, (gogoproto.stdtime) = true];
}

MsgCancelUnbondingDelegation

MsgCancelUnbondingDelegation defines the SDK message for performing a cancel unbonding delegation for delegator.

tx.proto

message MsgCancelUnbondingDelegation{
  option (cosmos.msg.v1.signer) = "delegator_address";
  option (gogoproto.equal)           = false;
  option (gogoproto.goproto_getters) = false;

  string                   delegator_address = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
  string                   validator_address = 2 [(cosmos_proto.scalar) = "cosmos.AddressString"];
  // amount is always less than or equal to unbonding delegation entry balance 
  cosmos.base.v1beta1.Coin amount            = 3 [(gogoproto.nullable) = false];
  // creation_height is the height which the unbonding took place.
  int64 creation_height = 4;
}

MsgCancelUnbondingDelegationResponse

MsgCancelUnbondingDelegationResponse defines the Msg/CancelUnbondingDelegation response type.

tx.proto

message MsgCancelUnbondingDelegationResponse{}

Queries

Query defines the gRPC querier service.

query.proto

service Query {
  // Validators queries all validators that match the given status.
  rpc Validators(QueryValidatorsRequest) returns (QueryValidatorsResponse) {
    option (google.api.http).get = "/cosmos/staking/v1beta1/validators";
  }

  // Validator queries validator info for given validator address.
  rpc Validator(QueryValidatorRequest) returns (QueryValidatorResponse) {
    option (google.api.http).get = "/cosmos/staking/v1beta1/validators/{validator_addr}";
  }

  // ValidatorDelegations queries delegate info for given validator.
  rpc ValidatorDelegations(QueryValidatorDelegationsRequest) returns (QueryValidatorDelegationsResponse) {
    option (google.api.http).get = "/cosmos/staking/v1beta1/validators/{validator_addr}/delegations";
  }

  // ValidatorUnbondingDelegations queries unbonding delegations of a validator.
  rpc ValidatorUnbondingDelegations(QueryValidatorUnbondingDelegationsRequest)
      returns (QueryValidatorUnbondingDelegationsResponse) {
    option (google.api.http).get = "/cosmos/staking/v1beta1/validators/"
                                   "{validator_addr}/unbonding_delegations";
  }

  // Delegation queries delegate info for given validator delegator pair.
  rpc Delegation(QueryDelegationRequest) returns (QueryDelegationResponse) {
    option (google.api.http).get = "/cosmos/staking/v1beta1/validators/{validator_addr}/delegations/"
                                   "{delegator_addr}";
  }

  // UnbondingDelegation queries unbonding info for given validator delegator
  // pair.
  rpc UnbondingDelegation(QueryUnbondingDelegationRequest) returns (QueryUnbondingDelegationResponse) {
    option (google.api.http).get = "/cosmos/staking/v1beta1/validators/{validator_addr}/delegations/"
                                   "{delegator_addr}/unbonding_delegation";
  }

  // DelegatorDelegations queries all delegations of a given delegator address.
  rpc DelegatorDelegations(QueryDelegatorDelegationsRequest) returns (QueryDelegatorDelegationsResponse) {
    option (google.api.http).get = "/cosmos/staking/v1beta1/delegations/{delegator_addr}";
  }

  // DelegatorUnbondingDelegations queries all unbonding delegations of a given
  // delegator address.
  rpc DelegatorUnbondingDelegations(QueryDelegatorUnbondingDelegationsRequest)
      returns (QueryDelegatorUnbondingDelegationsResponse) {
    option (google.api.http).get = "/cosmos/staking/v1beta1/delegators/"
                                   "{delegator_addr}/unbonding_delegations";
  }

  // Redelegations queries redelegations of given address.
  rpc Redelegations(QueryRedelegationsRequest) returns (QueryRedelegationsResponse) {
    option (google.api.http).get = "/cosmos/staking/v1beta1/delegators/{delegator_addr}/redelegations";
  }

  // DelegatorValidators queries all validators info for given delegator
  // address.
  rpc DelegatorValidators(QueryDelegatorValidatorsRequest) returns (QueryDelegatorValidatorsResponse) {
    option (google.api.http).get = "/cosmos/staking/v1beta1/delegators/{delegator_addr}/validators";
  }

  // DelegatorValidator queries validator info for given delegator validator
  // pair.
  rpc DelegatorValidator(QueryDelegatorValidatorRequest) returns (QueryDelegatorValidatorResponse) {
    option (google.api.http).get = "/cosmos/staking/v1beta1/delegators/{delegator_addr}/validators/"
                                   "{validator_addr}";
  }

  // HistoricalInfo queries the historical info for given height.
  rpc HistoricalInfo(QueryHistoricalInfoRequest) returns (QueryHistoricalInfoResponse) {
    option (google.api.http).get = "/cosmos/staking/v1beta1/historical_info/{height}";
  }

  // Pool queries the pool info.
  rpc Pool(QueryPoolRequest) returns (QueryPoolResponse) {
    option (google.api.http).get = "/cosmos/staking/v1beta1/pool";
  }

  // Parameters queries the staking parameters.
  rpc Params(QueryParamsRequest) returns (QueryParamsResponse) {
    option (google.api.http).get = "/cosmos/staking/v1beta1/params";
  }
}

QueryValidatorsRequest

QueryValidatorsRequest is request type for Query/Validators RPC method.

query.proto

message QueryValidatorsRequest {
  // status enables to query for validators matching a given status.
  string status = 1;

  // pagination defines an optional pagination for the request.
  cosmos.base.query.v1beta1.PageRequest pagination = 2;
}

QueryValidatorsResponse

QueryValidatorsResponse is response type for the Query/Validators RPC method.

query.proto

message QueryValidatorsResponse {
  // validators contains all the queried validators.
  repeated Validator validators = 1 [(gogoproto.nullable) = false];

  // pagination defines the pagination in the response.
  cosmos.base.query.v1beta1.PageResponse pagination = 2;
}

QueryValidatorRequest

QueryValidatorRequest is response type for the Query/Validator RPC method.

query.proto

message QueryValidatorRequest {
  // validator_addr defines the validator address to query for.
  string validator_addr = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
}

QueryValidatorResponse

QueryValidatorResponse is response type for the Query/Validator RPC method.

query.proto

message QueryValidatorResponse {
  // validator defines the the validator info.
  Validator validator = 1 [(gogoproto.nullable) = false];
}

QueryValidatorDelegationsRequest

QueryValidatorDelegationsRequest is request type for the Query/ValidatorDelegations RPC method.

query.proto

message QueryValidatorDelegationsRequest {
  // validator_addr defines the validator address to query for.
  string validator_addr = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];

  // pagination defines an optional pagination for the request.
  cosmos.base.query.v1beta1.PageRequest pagination = 2;
}

QueryValidatorDelegationsResponse

QueryValidatorDelegationsResponse is response type for the Query/ValidatorDelegations RPC method.

query.proto

message QueryValidatorDelegationsResponse {
  repeated DelegationResponse delegation_responses = 1
      [(gogoproto.nullable) = false, (gogoproto.castrepeated) = "DelegationResponses"];

  // pagination defines the pagination in the response.
  cosmos.base.query.v1beta1.PageResponse pagination = 2;
}

QueryValidatorUnbondingDelegationsRequest

QueryValidatorUnbondingDelegationsRequest is required type for the Query/ValidatorUnbondingDelegations RPC method.

query.proto

message QueryValidatorUnbondingDelegationsRequest {
  // validator_addr defines the validator address to query for.
  string validator_addr = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];

  // pagination defines an optional pagination for the request.
  cosmos.base.query.v1beta1.PageRequest pagination = 2;
}

QueryValidatorUnbondingDelegationsResponse

QueryValidatorUnbondingDelegationsResponse is response type for the Query/ValidatorUnbondingDelegations RPC method.

query.proto

message QueryValidatorUnbondingDelegationsResponse {
  repeated UnbondingDelegation unbonding_responses = 1 [(gogoproto.nullable) = false];

  // pagination defines the pagination in the response.
  cosmos.base.query.v1beta1.PageResponse pagination = 2;
}

QueryDelegationRequest

QueryDelegationRequest is request type for the Query/Delegation RPC method.

query.proto

message QueryDelegationRequest {
  option (gogoproto.equal)           = false;
  option (gogoproto.goproto_getters) = false;

  // delegator_addr defines the delegator address to query for.
  string delegator_addr = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];

  // validator_addr defines the validator address to query for.
  string validator_addr = 2 [(cosmos_proto.scalar) = "cosmos.AddressString"];
}

QueryDelegationResponse

QueryDelegationResponse is response type for the Query/Delegation RPC method.

query.proto

message QueryDelegationResponse {
  // delegation_responses defines the delegation info of a delegation.
  DelegationResponse delegation_response = 1;
}

QueryUnbondingDelegationRequest

QueryUnbondingDelegationRequest is request type for the Query/UnbondingDelegation RPC method.

query.proto

message QueryUnbondingDelegationRequest {
  option (gogoproto.equal)           = false;
  option (gogoproto.goproto_getters) = false;

  // delegator_addr defines the delegator address to query for.
  string delegator_addr = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];

  // validator_addr defines the validator address to query for.
  string validator_addr = 2 [(cosmos_proto.scalar) = "cosmos.AddressString"];
}

QueryUnbondingDelegationResponse

QueryUnbondingDelegationResponse is response type for the Query/UnbondingDelegation RPC method.

query.proto

message QueryUnbondingDelegationResponse {
  // unbond defines the unbonding information of a delegation.
  UnbondingDelegation unbond = 1 [(gogoproto.nullable) = false];
}

QueryDelegatorDelegationsRequest

QueryDelegatorDelegationsRequest is request type for the Query/DelegatorDelegations RPC method.

query.proto

message QueryDelegatorDelegationsRequest {
  option (gogoproto.equal)           = false;
  option (gogoproto.goproto_getters) = false;

  // delegator_addr defines the delegator address to query for.
  string delegator_addr = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];

  // pagination defines an optional pagination for the request.
  cosmos.base.query.v1beta1.PageRequest pagination = 2;
}

QueryDelegatorDelegationsResponse

QueryDelegatorDelegationsResponse is response type for the Query/DelegatorDelegations RPC method.

query.proto

message QueryDelegatorDelegationsResponse {
  // delegation_responses defines all the delegations' info of a delegator.
  repeated DelegationResponse delegation_responses = 1 [(gogoproto.nullable) = false];

  // pagination defines the pagination in the response.
  cosmos.base.query.v1beta1.PageResponse pagination = 2;
}

QueryDelegatorUnbondingDelegationsRequest

QueryDelegatorUnbondingDelegationsRequest is request type for the Query/DelegatorUnbondingDelegations RPC method.

query.proto

message QueryDelegatorUnbondingDelegationsRequest {
  option (gogoproto.equal)           = false;
  option (gogoproto.goproto_getters) = false;

  // delegator_addr defines the delegator address to query for.
  string delegator_addr = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];

  // pagination defines an optional pagination for the request.
  cosmos.base.query.v1beta1.PageRequest pagination = 2;
}

QueryDelegatorUnbondingDelegationsResponse

QueryDelegatorUnbondingDelegationsResponse is response type for the Query/DelegatorUnbondingDelegations RPC method.

query.proto

message QueryDelegatorUnbondingDelegationsResponse {
  repeated UnbondingDelegation unbonding_responses = 1 [(gogoproto.nullable) = false];

  // pagination defines the pagination in the response.
  cosmos.base.query.v1beta1.PageResponse pagination = 2;
}

QueryRedelegationsRequest

QueryRedelegationsRequest is request type for the Query/Redelegations RPC method.

query.proto

message QueryRedelegationsRequest {
  option (gogoproto.equal)           = false;
  option (gogoproto.goproto_getters) = false;

  // delegator_addr defines the delegator address to query for.
  string delegator_addr = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];

  // src_validator_addr defines the validator address to redelegate from.
  string src_validator_addr = 2 [(cosmos_proto.scalar) = "cosmos.AddressString"];

  // dst_validator_addr defines the validator address to redelegate to.
  string dst_validator_addr = 3 [(cosmos_proto.scalar) = "cosmos.AddressString"];

  // pagination defines an optional pagination for the request.
  cosmos.base.query.v1beta1.PageRequest pagination = 4;
}

QueryRedelegationsResponse

QueryRedelegationsResponse is response type for the Query/Redelegations RPC method.

query.proto

message QueryRedelegationsResponse {
  repeated RedelegationResponse redelegation_responses = 1 [(gogoproto.nullable) = false];

  // pagination defines the pagination in the response.
  cosmos.base.query.v1beta1.PageResponse pagination = 2;
}

QueryDelegatorValidatorsRequest

QueryDelegatorValidatorsRequest is request type for the Query/DelegatorValidators RPC method.

query.proto

message QueryDelegatorValidatorsRequest {
  option (gogoproto.equal)           = false;
  option (gogoproto.goproto_getters) = false;

  // delegator_addr defines the delegator address to query for.
  string delegator_addr = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];

  // pagination defines an optional pagination for the request.
  cosmos.base.query.v1beta1.PageRequest pagination = 2;
}

QueryDelegatorValidatorsResponse

QueryDelegatorValidatorsResponse is response type for the Query/DelegatorValidators RPC method.

query.proto

message QueryDelegatorValidatorsResponse {
  // validators defines the the validators' info of a delegator.
  repeated Validator validators = 1 [(gogoproto.nullable) = false];

  // pagination defines the pagination in the response.
  cosmos.base.query.v1beta1.PageResponse pagination = 2;
}

QueryDelegatorValidatorRequest

QueryDelegatorValidatorRequest is request type for the Query/DelegatorValidator RPC method.

query.proto

message QueryDelegatorValidatorRequest {
  option (gogoproto.equal)           = false;
  option (gogoproto.goproto_getters) = false;

  // delegator_addr defines the delegator address to query for.
  string delegator_addr = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];

  // validator_addr defines the validator address to query for.
  string validator_addr = 2 [(cosmos_proto.scalar) = "cosmos.AddressString"];
}

QueryDelegatorValidatorResponse

QueryDelegatorValidatorResponse response type for the Query/DelegatorValidator RPC method.

query.proto

message QueryDelegatorValidatorResponse {
  // validator defines the the validator info.
  Validator validator = 1 [(gogoproto.nullable) = false];
}

QueryHistoricalInfoRequest

QueryHistoricalInfoRequest is request type for the Query/HistoricalInfo RPC method.

query.proto

message QueryHistoricalInfoRequest {
  // height defines at which height to query the historical info.
  int64 height = 1;
}

QueryHistoricalInfoResponse

QueryHistoricalInfoResponse is response type for the Query/HistoricalInfo RPC method.

query.proto

message QueryHistoricalInfoResponse {
  // hist defines the historical info at the given height.
  HistoricalInfo hist = 1;
}

QueryPoolRequest

QueryPoolRequest is request type for the Query/Pool RPC method.

query.proto

message QueryPoolRequest {}

QueryPoolResponse

QueryPoolResponse is response type for the Query/Pool RPC method.

query.proto

message QueryPoolResponse {
  // pool defines the pool info.
  Pool pool = 1 [(gogoproto.nullable) = false];
}

QueryParamsRequest

QueryParamsRequest is request type for the Query/Params RPC method.

query.proto

message QueryParamsRequest {}

QueryParamsResponse

QueryParamsResponse is response type for the Query/Params RPC method.

query.proto

message QueryParamsResponse {
  // params holds all the parameters of this module.
  Params params = 1 [(gogoproto.nullable) = false];
}