Skip to main content
logo
BlogForum

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
Copy
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
Copy
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
Copy
message MsgCreateValidatorResponse {}

MsgEditValidator​

MsgEditValidator defines an SDK message for editing an existing validator.

tx.proto
Copy
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
Copy
message MsgEditValidatorResponse {}

MsgDelegate​

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

tx.proto
Copy
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
Copy
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
Copy
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
Copy
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
Copy
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
Copy
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
Copy
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
Copy
message MsgCancelUnbondingDelegationResponse{}

Queries​

Query defines the gRPC querier service.

query.proto
Copy
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
Copy
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
Copy
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
Copy
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
Copy
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
Copy
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
Copy
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
Copy
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
Copy
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
Copy
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
Copy
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
Copy
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
Copy
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
Copy
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
Copy
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
Copy
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
Copy
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
Copy
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
Copy
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
Copy
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
Copy
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
Copy
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
Copy
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
Copy
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
Copy
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
Copy
message QueryPoolRequest {}

QueryPoolResponse​

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

query.proto
Copy
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
Copy
message QueryParamsRequest {}

QueryParamsResponse​

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

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