Distribution
The distribution
module is responsible for fee distribution, and staking token provision distribution. This simple distribution mechanism describes a functional way to passively distribute rewards between validators and delegators. Note that this mechanism does not distribute funds as precisely as active reward distribution mechanisms and can be upgraded in the future.
For more information, visit https://docs.cosmos.network/main/modules/distribution/
Message Types
Msg
defines the distribution Msg service.
service Msg {
// SetWithdrawAddress defines a method to change the withdraw address
// for a delegator (or validator self-delegation).
rpc SetWithdrawAddress(MsgSetWithdrawAddress) returns (MsgSetWithdrawAddressResponse);
// WithdrawDelegatorReward defines a method to withdraw rewards of delegator
// from a single validator.
rpc WithdrawDelegatorReward(MsgWithdrawDelegatorReward) returns (MsgWithdrawDelegatorRewardResponse);
// WithdrawValidatorCommission defines a method to withdraw the
// full commission to the validator address.
rpc WithdrawValidatorCommission(MsgWithdrawValidatorCommission) returns (MsgWithdrawValidatorCommissionResponse);
// FundCommunityPool defines a method to allow an account to directly
// fund the community pool.
rpc FundCommunityPool(MsgFundCommunityPool) returns (MsgFundCommunityPoolResponse);
}
MsgSetWithdrawAddress
MsgSetWithdrawAddress
sets the withdraw address for a delegator (or validator self-delegation).
message MsgSetWithdrawAddress {
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 withdraw_address = 2 [(cosmos_proto.scalar) = "cosmos.AddressString"];
}
MsgSetWithdrawAddressResponse
MsgSetWithdrawAddressResponse
defines the Msg/SetWithdrawAddress
response type.
message MsgSetWithdrawAddressResponse {}
MsgWithdrawDelegatorReward
MsgWithdrawDelegatorReward
represents delegation withdrawal to a delegator from a single validator.
message MsgWithdrawDelegatorReward {
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"];
}
MsgWithdrawDelegatorRewardResponse
MsgWithdrawDelegatorRewardResponse
defines the Msg/WithdrawDelegatorReward
response type.
message MsgWithdrawDelegatorRewardResponse {
// Since: cosmos-sdk 0.46
repeated cosmos.base.v1beta1.Coin amount = 1
[(gogoproto.nullable) = false, (gogoproto.castrepeated) = "github.com/cosmos/cosmos-sdk/types.Coins"];
}
MsgWithdrawValidatorCommission
MsgWithdrawValidatorCommission
withdraws the full commission to the validator address.
message MsgWithdrawValidatorCommission {
option (cosmos.msg.v1.signer) = "validator_address";
option (gogoproto.equal) = false;
option (gogoproto.goproto_getters) = false;
string validator_address = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
}
MsgWithdrawValidatorCommissionResponse
MsgWithdrawValidatorCommissionResponse
defines the Msg/WithdrawValidatorCommission
response type.
message MsgWithdrawValidatorCommissionResponse {
// Since: cosmos-sdk 0.46
repeated cosmos.base.v1beta1.Coin amount = 1
[(gogoproto.nullable) = false, (gogoproto.castrepeated) = "github.com/cosmos/cosmos-sdk/types.Coins"];
}
MsgFundCommunityPool
MsgFundCommunityPool
allows an account to directly fund the community pool.
message MsgFundCommunityPool {
option (cosmos.msg.v1.signer) = "depositor";
option (gogoproto.equal) = false;
option (gogoproto.goproto_getters) = false;
repeated cosmos.base.v1beta1.Coin amount = 1
[(gogoproto.nullable) = false, (gogoproto.castrepeated) = "github.com/cosmos/cosmos-sdk/types.Coins"];
string depositor = 2 [(cosmos_proto.scalar) = "cosmos.AddressString"];
}
MsgFundCommunityPoolResponse
MsgFundCommunityPoolResponse
defines the Msg/FundCommunityPool
response type.
message MsgFundCommunityPoolResponse {}
Queries
Query
defines the gRPC querier service for distribution module.
service Query {
// Params queries params of the distribution module.
rpc Params(QueryParamsRequest) returns (QueryParamsResponse) {
option (google.api.http).get = "/cosmos/distribution/v1beta1/params";
}
// ValidatorOutstandingRewards queries rewards of a validator address.
rpc ValidatorOutstandingRewards(QueryValidatorOutstandingRewardsRequest)
returns (QueryValidatorOutstandingRewardsResponse) {
option (google.api.http).get = "/cosmos/distribution/v1beta1/validators/"
"{validator_address}/outstanding_rewards";
}
// ValidatorCommission queries accumulated commission for a validator.
rpc ValidatorCommission(QueryValidatorCommissionRequest) returns (QueryValidatorCommissionResponse) {
option (google.api.http).get = "/cosmos/distribution/v1beta1/validators/"
"{validator_address}/commission";
}
// ValidatorSlashes queries slash events of a validator.
rpc ValidatorSlashes(QueryValidatorSlashesRequest) returns (QueryValidatorSlashesResponse) {
option (google.api.http).get = "/cosmos/distribution/v1beta1/validators/{validator_address}/slashes";
}
// DelegationRewards queries the total rewards accrued by a delegation.
rpc DelegationRewards(QueryDelegationRewardsRequest) returns (QueryDelegationRewardsResponse) {
option (google.api.http).get = "/cosmos/distribution/v1beta1/delegators/{delegator_address}/rewards/"
"{validator_address}";
}
// DelegationTotalRewards queries the total rewards accrued by a each
// validator.
rpc DelegationTotalRewards(QueryDelegationTotalRewardsRequest) returns (QueryDelegationTotalRewardsResponse) {
option (google.api.http).get = "/cosmos/distribution/v1beta1/delegators/{delegator_address}/rewards";
}
// DelegatorValidators queries the validators of a delegator.
rpc DelegatorValidators(QueryDelegatorValidatorsRequest) returns (QueryDelegatorValidatorsResponse) {
option (google.api.http).get = "/cosmos/distribution/v1beta1/delegators/"
"{delegator_address}/validators";
}
// DelegatorWithdrawAddress queries withdraw address of a delegator.
rpc DelegatorWithdrawAddress(QueryDelegatorWithdrawAddressRequest) returns (QueryDelegatorWithdrawAddressResponse) {
option (google.api.http).get = "/cosmos/distribution/v1beta1/delegators/"
"{delegator_address}/withdraw_address";
}
// CommunityPool queries the community pool coins.
rpc CommunityPool(QueryCommunityPoolRequest) returns (QueryCommunityPoolResponse) {
option (google.api.http).get = "/cosmos/distribution/v1beta1/community_pool";
}
}
QueryParamsRequest
QueryParamsRequest
is the request type for the Query/Params
RPC method.
message QueryParamsRequest {}
QueryParamsResponse
QueryParamsResponse
is the response type for the Query/Params
RPC method.
message QueryParamsResponse {
// params defines the parameters of the module.
Params params = 1 [(gogoproto.nullable) = false];
}
QueryValidatorOutstandingRewardsRequest
QueryValidatorOutstandingRewardsRequest
is the request type for the Query/ValidatorOutstandingRewards
RPC method.
message QueryValidatorOutstandingRewardsRequest {
// validator_address defines the validator address to query for.
string validator_address = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
}
QueryValidatorOutstandingRewardsResponse
QueryValidatorOutstandingRewardsResponse
is the response type for the Query/ValidatorOutstandingRewards
RPC method.
message QueryValidatorOutstandingRewardsResponse {
ValidatorOutstandingRewards rewards = 1 [(gogoproto.nullable) = false];
}
QueryValidatorCommissionRequest
QueryValidatorCommissionRequest
is the request type for the Query/ValidatorCommission
RPC method.
message QueryValidatorCommissionRequest {
// validator_address defines the validator address to query for.
string validator_address = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
}
QueryValidatorCommissionResponse
QueryValidatorCommissionResponse
is the response type for the Query/ValidatorCommission
RPC method.
message QueryValidatorCommissionResponse {
// commission defines the commision the validator received.
ValidatorAccumulatedCommission commission = 1 [(gogoproto.nullable) = false];
}
QueryValidatorSlashesRequest
QueryValidatorSlashesRequest
is the request type for the Query/ValidatorSlashes
RPC method.
message QueryValidatorSlashesRequest {
option (gogoproto.goproto_getters) = false;
option (gogoproto.goproto_stringer) = true;
// validator_address defines the validator address to query for.
string validator_address = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
// starting_height defines the optional starting height to query the slashes.
uint64 starting_height = 2;
// starting_height defines the optional ending height to query the slashes.
uint64 ending_height = 3;
// pagination defines an optional pagination for the request.
cosmos.base.query.v1beta1.PageRequest pagination = 4;
}
QueryValidatorSlashesResponse
QueryValidatorSlashesResponse
is the response type for the Query/ValidatorSlashes
RPC method.
message QueryValidatorSlashesResponse {
// slashes defines the slashes the validator received.
repeated ValidatorSlashEvent slashes = 1 [(gogoproto.nullable) = false];
// pagination defines the pagination in the response.
cosmos.base.query.v1beta1.PageResponse pagination = 2;
}
QueryDelegationRewardsRequest
QueryDelegationRewardsRequest
is the request type for the Query/DelegationRewards
RPC method.
message QueryDelegationRewardsRequest {
option (gogoproto.equal) = false;
option (gogoproto.goproto_getters) = false;
// delegator_address defines the delegator address to query for.
string delegator_address = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
// validator_address defines the validator address to query for.
string validator_address = 2 [(cosmos_proto.scalar) = "cosmos.AddressString"];
}
QueryDelegationRewardsResponse
QueryDelegationRewardsResponse
is the response type for the Query/DelegationRewards
RPC method.
message QueryDelegationRewardsResponse {
// rewards defines the rewards accrued by a delegation.
repeated cosmos.base.v1beta1.DecCoin rewards = 1
[(gogoproto.nullable) = false, (gogoproto.castrepeated) = "github.com/cosmos/cosmos-sdk/types.DecCoins"];
}
QueryDelegationTotalRewardsRequest
QueryDelegationTotalRewardsRequest
is the request type for the Query/DelegationTotalRewards
RPC method.
message QueryDelegationTotalRewardsRequest {
option (gogoproto.equal) = false;
option (gogoproto.goproto_getters) = false;
// delegator_address defines the delegator address to query for.
string delegator_address = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
}
QueryDelegationTotalRewardsResponse
QueryDelegationTotalRewardsResponse
is the response type for the Query/DelegationTotalRewards
RPC method.
message QueryDelegationTotalRewardsResponse {
// rewards defines all the rewards accrued by a delegator.
repeated DelegationDelegatorReward rewards = 1 [(gogoproto.nullable) = false];
// total defines the sum of all the rewards.
repeated cosmos.base.v1beta1.DecCoin total = 2
[(gogoproto.nullable) = false, (gogoproto.castrepeated) = "github.com/cosmos/cosmos-sdk/types.DecCoins"];
}
QueryDelegatorValidatorsRequest
QueryDelegatorValidatorsRequest
is the request type for the Query/DelegatorValidators
RPC method.
message QueryDelegatorValidatorsRequest {
option (gogoproto.equal) = false;
option (gogoproto.goproto_getters) = false;
// delegator_address defines the delegator address to query for.
string delegator_address = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
}
QueryDelegatorValidatorsResponse
QueryDelegatorValidatorsResponse
is the response type for the Query/DelegatorValidators
RPC method.
message QueryDelegatorValidatorsResponse {
option (gogoproto.equal) = false;
option (gogoproto.goproto_getters) = false;
// validators defines the validators a delegator is delegating for.
repeated string validators = 1;
}
QueryDelegatorWithdrawAddressRequest
QueryDelegatorWithdrawAddressRequest
is the request type for the Query/DelegatorWithdrawAddress
RPC method.
message QueryDelegatorWithdrawAddressRequest {
option (gogoproto.equal) = false;
option (gogoproto.goproto_getters) = false;
// delegator_address defines the delegator address to query for.
string delegator_address = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
}
QueryDelegatorWithdrawAddressResponse
QueryDelegatorWithdrawAddressResponse
is the response type for the Query/DelegatorWithdrawAddress
RPC method.
message QueryDelegatorWithdrawAddressResponse {
option (gogoproto.equal) = false;
option (gogoproto.goproto_getters) = false;
// withdraw_address defines the delegator address to query for.
string withdraw_address = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
}
QueryCommunityPoolRequest
QueryCommunityPoolRequest
is the request type for the Query/CommunityPool
RPC method.
message QueryCommunityPoolRequest {}
QueryCommunityPoolResponse
QueryCommunityPoolResponse
is the response type for the Query/CommunityPool
RPC method.
message QueryCommunityPoolResponse {
// pool defines community pool's coins.
repeated cosmos.base.v1beta1.DecCoin pool = 1
[(gogoproto.castrepeated) = "github.com/cosmos/cosmos-sdk/types.DecCoins", (gogoproto.nullable) = false];
}