Skip to main content
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
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).
tx.proto
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.
tx.proto
message MsgSetWithdrawAddressResponse {}

​
MsgWithdrawDelegatorReward

MsgWithdrawDelegatorReward represents delegation withdrawal to a delegator from a single validator.
tx.proto
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.
tx.proto
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.
tx.proto
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.
tx.proto
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.
tx.proto
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.
tx.proto
message MsgFundCommunityPoolResponse {}

​
Queries

Query defines the gRPC querier service for distribution module.
query.proto
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.
query.proto
message QueryParamsRequest {}

​
QueryParamsResponse

QueryParamsResponse is the response type for the Query/Params RPC method.
query.proto
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.
query.proto
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.
query.proto
message QueryValidatorOutstandingRewardsResponse {
  ValidatorOutstandingRewards rewards = 1 [(gogoproto.nullable) = false];
}

​
QueryValidatorCommissionRequest

QueryValidatorCommissionRequest is the request type for the Query/ValidatorCommission RPC method.
query.proto
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.
query.proto
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.
query.proto
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.
query.proto
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.
query.proto
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.
query.proto
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.
query.proto
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.
query.proto
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.
query.proto
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.
query.proto
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.
query.proto
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.
query.proto
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.
query.proto
message QueryCommunityPoolRequest {}

​
QueryCommunityPoolResponse

QueryCommunityPoolResponse is the response type for the Query/CommunityPool RPC method.
query.proto
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];
}