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.

tx.proto

_17

service Msg {

_17

// SetWithdrawAddress defines a method to change the withdraw address

_17

// for a delegator (or validator self-delegation).

_17

rpc SetWithdrawAddress(MsgSetWithdrawAddress) returns (MsgSetWithdrawAddressResponse);

_17

_17

// WithdrawDelegatorReward defines a method to withdraw rewards of delegator

_17

// from a single validator.

_17

rpc WithdrawDelegatorReward(MsgWithdrawDelegatorReward) returns (MsgWithdrawDelegatorRewardResponse);

_17

_17

// WithdrawValidatorCommission defines a method to withdraw the

_17

// full commission to the validator address.

_17

rpc WithdrawValidatorCommission(MsgWithdrawValidatorCommission) returns (MsgWithdrawValidatorCommissionResponse);

_17

_17

// FundCommunityPool defines a method to allow an account to directly

_17

// fund the community pool.

_17

rpc FundCommunityPool(MsgFundCommunityPool) returns (MsgFundCommunityPoolResponse);

_17

}

MsgSetWithdrawAddress

MsgSetWithdrawAddress sets the withdraw address for a delegator (or validator self-delegation).

tx.proto

_9

message MsgSetWithdrawAddress {

_9

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

_9

_9

option (gogoproto.equal) = false;

_9

option (gogoproto.goproto_getters) = false;

_9

_9

string delegator_address = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];

_9

string withdraw_address = 2 [(cosmos_proto.scalar) = "cosmos.AddressString"];

_9

}

MsgSetWithdrawAddressResponse

MsgSetWithdrawAddressResponse defines the Msg/SetWithdrawAddress response type.

tx.proto

_1

message MsgSetWithdrawAddressResponse {}

MsgWithdrawDelegatorReward

MsgWithdrawDelegatorReward represents delegation withdrawal to a delegator from a single validator.

tx.proto

_9

message MsgWithdrawDelegatorReward {

_9

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

_9

_9

option (gogoproto.equal) = false;

_9

option (gogoproto.goproto_getters) = false;

_9

_9

string delegator_address = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];

_9

string validator_address = 2 [(cosmos_proto.scalar) = "cosmos.AddressString"];

_9

}

MsgWithdrawDelegatorRewardResponse

MsgWithdrawDelegatorRewardResponse defines the Msg/WithdrawDelegatorReward response type.

tx.proto

_5

message MsgWithdrawDelegatorRewardResponse {

_5

// Since: cosmos-sdk 0.46

_5

repeated cosmos.base.v1beta1.Coin amount = 1

_5

[(gogoproto.nullable) = false, (gogoproto.castrepeated) = "github.com/cosmos/cosmos-sdk/types.Coins"];

_5

}

MsgWithdrawValidatorCommission

MsgWithdrawValidatorCommission withdraws the full commission to the validator address.

tx.proto

_8

message MsgWithdrawValidatorCommission {

_8

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

_8

_8

option (gogoproto.equal) = false;

_8

option (gogoproto.goproto_getters) = false;

_8

_8

string validator_address = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];

_8

}

MsgWithdrawValidatorCommissionResponse

MsgWithdrawValidatorCommissionResponse defines the Msg/WithdrawValidatorCommission response type.

tx.proto

_5

message MsgWithdrawValidatorCommissionResponse {

_5

// Since: cosmos-sdk 0.46

_5

repeated cosmos.base.v1beta1.Coin amount = 1

_5

[(gogoproto.nullable) = false, (gogoproto.castrepeated) = "github.com/cosmos/cosmos-sdk/types.Coins"];

_5

}

MsgFundCommunityPool

MsgFundCommunityPool allows an account to directly fund the community pool.

tx.proto

_10

message MsgFundCommunityPool {

_10

option (cosmos.msg.v1.signer) = "depositor";

_10

_10

option (gogoproto.equal) = false;

_10

option (gogoproto.goproto_getters) = false;

_10

_10

repeated cosmos.base.v1beta1.Coin amount = 1

_10

[(gogoproto.nullable) = false, (gogoproto.castrepeated) = "github.com/cosmos/cosmos-sdk/types.Coins"];

_10

string depositor = 2 [(cosmos_proto.scalar) = "cosmos.AddressString"];

_10

}

MsgFundCommunityPoolResponse

MsgFundCommunityPoolResponse defines the Msg/FundCommunityPool response type.

tx.proto

_1

message MsgFundCommunityPoolResponse {}

Queries

Query defines the gRPC querier service for distribution module.

query.proto

_53

service Query {

_53

// Params queries params of the distribution module.

_53

rpc Params(QueryParamsRequest) returns (QueryParamsResponse) {

_53

option (google.api.http).get = "/cosmos/distribution/v1beta1/params";

_53

}

_53

_53

// ValidatorOutstandingRewards queries rewards of a validator address.

_53

rpc ValidatorOutstandingRewards(QueryValidatorOutstandingRewardsRequest)

_53

returns (QueryValidatorOutstandingRewardsResponse) {

_53

option (google.api.http).get = "/cosmos/distribution/v1beta1/validators/"

_53

"{validator_address}/outstanding_rewards";

_53

}

_53

_53

// ValidatorCommission queries accumulated commission for a validator.

_53

rpc ValidatorCommission(QueryValidatorCommissionRequest) returns (QueryValidatorCommissionResponse) {

_53

option (google.api.http).get = "/cosmos/distribution/v1beta1/validators/"

_53

"{validator_address}/commission";

_53

}

_53

_53

// ValidatorSlashes queries slash events of a validator.

_53

rpc ValidatorSlashes(QueryValidatorSlashesRequest) returns (QueryValidatorSlashesResponse) {

_53

option (google.api.http).get = "/cosmos/distribution/v1beta1/validators/{validator_address}/slashes";

_53

}

_53

_53

// DelegationRewards queries the total rewards accrued by a delegation.

_53

rpc DelegationRewards(QueryDelegationRewardsRequest) returns (QueryDelegationRewardsResponse) {

_53

option (google.api.http).get = "/cosmos/distribution/v1beta1/delegators/{delegator_address}/rewards/"

_53

"{validator_address}";

_53

}

_53

_53

// DelegationTotalRewards queries the total rewards accrued by a each

_53

// validator.

_53

rpc DelegationTotalRewards(QueryDelegationTotalRewardsRequest) returns (QueryDelegationTotalRewardsResponse) {

_53

option (google.api.http).get = "/cosmos/distribution/v1beta1/delegators/{delegator_address}/rewards";

_53

}

_53

_53

// DelegatorValidators queries the validators of a delegator.

_53

rpc DelegatorValidators(QueryDelegatorValidatorsRequest) returns (QueryDelegatorValidatorsResponse) {

_53

option (google.api.http).get = "/cosmos/distribution/v1beta1/delegators/"

_53

"{delegator_address}/validators";

_53

}

_53

_53

// DelegatorWithdrawAddress queries withdraw address of a delegator.

_53

rpc DelegatorWithdrawAddress(QueryDelegatorWithdrawAddressRequest) returns (QueryDelegatorWithdrawAddressResponse) {

_53

option (google.api.http).get = "/cosmos/distribution/v1beta1/delegators/"

_53

"{delegator_address}/withdraw_address";

_53

}

_53

_53

// CommunityPool queries the community pool coins.

_53

rpc CommunityPool(QueryCommunityPoolRequest) returns (QueryCommunityPoolResponse) {

_53

option (google.api.http).get = "/cosmos/distribution/v1beta1/community_pool";

_53

}

_53

}

QueryParamsRequest

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

query.proto

_1

message QueryParamsRequest {}

QueryParamsResponse

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

query.proto

_4

message QueryParamsResponse {

_4

// params defines the parameters of the module.

_4

Params params = 1 [(gogoproto.nullable) = false];

_4

}

QueryValidatorOutstandingRewardsRequest

QueryValidatorOutstandingRewardsRequest is the request type for the Query/ValidatorOutstandingRewards RPC method.

query.proto

_4

message QueryValidatorOutstandingRewardsRequest {

_4

// validator_address defines the validator address to query for.

_4

string validator_address = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];

_4

}

QueryValidatorOutstandingRewardsResponse

QueryValidatorOutstandingRewardsResponse is the response type for the Query/ValidatorOutstandingRewards RPC method.

query.proto

_3

message QueryValidatorOutstandingRewardsResponse {

_3

ValidatorOutstandingRewards rewards = 1 [(gogoproto.nullable) = false];

_3

}

QueryValidatorCommissionRequest

QueryValidatorCommissionRequest is the request type for the Query/ValidatorCommission RPC method.

query.proto

_4

message QueryValidatorCommissionRequest {

_4

// validator_address defines the validator address to query for.

_4

string validator_address = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];

_4

}

QueryValidatorCommissionResponse

QueryValidatorCommissionResponse is the response type for the Query/ValidatorCommission RPC method.

query.proto

_4

message QueryValidatorCommissionResponse {

_4

// commission defines the commision the validator received.

_4

ValidatorAccumulatedCommission commission = 1 [(gogoproto.nullable) = false];

_4

}

QueryValidatorSlashesRequest

QueryValidatorSlashesRequest is the request type for the Query/ValidatorSlashes RPC method.

query.proto

_13

message QueryValidatorSlashesRequest {

_13

option (gogoproto.goproto_getters) = false;

_13

option (gogoproto.goproto_stringer) = true;

_13

_13

// validator_address defines the validator address to query for.

_13

string validator_address = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];

_13

// starting_height defines the optional starting height to query the slashes.

_13

uint64 starting_height = 2;

_13

// starting_height defines the optional ending height to query the slashes.

_13

uint64 ending_height = 3;

_13

// pagination defines an optional pagination for the request.

_13

cosmos.base.query.v1beta1.PageRequest pagination = 4;

_13

}

QueryValidatorSlashesResponse

QueryValidatorSlashesResponse is the response type for the Query/ValidatorSlashes RPC method.

query.proto

_7

message QueryValidatorSlashesResponse {

_7

// slashes defines the slashes the validator received.

_7

repeated ValidatorSlashEvent slashes = 1 [(gogoproto.nullable) = false];

_7

_7

// pagination defines the pagination in the response.

_7

cosmos.base.query.v1beta1.PageResponse pagination = 2;

_7

}

QueryDelegationRewardsRequest

QueryDelegationRewardsRequest is the request type for the Query/DelegationRewards RPC method.

query.proto

_9

message QueryDelegationRewardsRequest {

_9

option (gogoproto.equal) = false;

_9

option (gogoproto.goproto_getters) = false;

_9

_9

// delegator_address defines the delegator address to query for.

_9

string delegator_address = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];

_9

// validator_address defines the validator address to query for.

_9

string validator_address = 2 [(cosmos_proto.scalar) = "cosmos.AddressString"];

_9

}

QueryDelegationRewardsResponse

QueryDelegationRewardsResponse is the response type for the Query/DelegationRewards RPC method.

query.proto

_5

message QueryDelegationRewardsResponse {

_5

// rewards defines the rewards accrued by a delegation.

_5

repeated cosmos.base.v1beta1.DecCoin rewards = 1

_5

[(gogoproto.nullable) = false, (gogoproto.castrepeated) = "github.com/cosmos/cosmos-sdk/types.DecCoins"];

_5

}

QueryDelegationTotalRewardsRequest

QueryDelegationTotalRewardsRequest is the request type for the Query/DelegationTotalRewards RPC method.

query.proto

_6

message QueryDelegationTotalRewardsRequest {

_6

option (gogoproto.equal) = false;

_6

option (gogoproto.goproto_getters) = false;

_6

// delegator_address defines the delegator address to query for.

_6

string delegator_address = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];

_6

}

QueryDelegationTotalRewardsResponse

QueryDelegationTotalRewardsResponse is the response type for the Query/DelegationTotalRewards RPC method.

query.proto

_7

message QueryDelegationTotalRewardsResponse {

_7

// rewards defines all the rewards accrued by a delegator.

_7

repeated DelegationDelegatorReward rewards = 1 [(gogoproto.nullable) = false];

_7

// total defines the sum of all the rewards.

_7

repeated cosmos.base.v1beta1.DecCoin total = 2

_7

[(gogoproto.nullable) = false, (gogoproto.castrepeated) = "github.com/cosmos/cosmos-sdk/types.DecCoins"];

_7

}

QueryDelegatorValidatorsRequest

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

query.proto

_7

message QueryDelegatorValidatorsRequest {

_7

option (gogoproto.equal) = false;

_7

option (gogoproto.goproto_getters) = false;

_7

_7

// delegator_address defines the delegator address to query for.

_7

string delegator_address = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];

_7

}

QueryDelegatorValidatorsResponse

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

query.proto

_7

message QueryDelegatorValidatorsResponse {

_7

option (gogoproto.equal) = false;

_7

option (gogoproto.goproto_getters) = false;

_7

_7

// validators defines the validators a delegator is delegating for.

_7

repeated string validators = 1;

_7

}

QueryDelegatorWithdrawAddressRequest

QueryDelegatorWithdrawAddressRequest is the request type for the Query/DelegatorWithdrawAddress RPC method.

query.proto

_7

message QueryDelegatorWithdrawAddressRequest {

_7

option (gogoproto.equal) = false;

_7

option (gogoproto.goproto_getters) = false;

_7

_7

// delegator_address defines the delegator address to query for.

_7

string delegator_address = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];

_7

}

QueryDelegatorWithdrawAddressResponse

QueryDelegatorWithdrawAddressResponse is the response type for the Query/DelegatorWithdrawAddress RPC method.

query.proto

_7

message QueryDelegatorWithdrawAddressResponse {

_7

option (gogoproto.equal) = false;

_7

option (gogoproto.goproto_getters) = false;

_7

_7

// withdraw_address defines the delegator address to query for.

_7

string withdraw_address = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];

_7

}

QueryCommunityPoolRequest

QueryCommunityPoolRequest is the request type for the Query/CommunityPool RPC method.

query.proto

_1

message QueryCommunityPoolRequest {}

QueryCommunityPoolResponse

QueryCommunityPoolResponse is the response type for the Query/CommunityPool RPC method.

query.proto

_5

message QueryCommunityPoolResponse {

_5

// pool defines community pool's coins.

_5

repeated cosmos.base.v1beta1.DecCoin pool = 1

_5

[(gogoproto.castrepeated) = "github.com/cosmos/cosmos-sdk/types.DecCoins", (gogoproto.nullable) = false];

_5

}