分发(Distribution)

摘要

这个简单的分发机制描述了一种功能性方式，用于在验证者和委托人之间被动地分发奖励。需要注意的是，这种机制不像主动奖励分发机制那样精确分配资金，因此未来将会进行升级。

该机制的操作方式如下：收集的奖励会在全球范围内汇集，并被被动地分发给验证者和委托人。每个验证者都有机会对代表委托人收集的奖励收取佣金。费用直接收集到全球奖励池和验证者提案奖励池。由于被动记账的特性，当涉及到奖励分发率的参数发生变化时，奖励的提取也必须发生。

在提取时，必须提取其应得的最大金额，不留任何资金在池中。
在绑定、解绑或将代币重新委托到现有账户时，必须完全提取奖励（因为懒惰记账的规则已发生变化）。
当验证者选择更改奖励的佣金时，所有累积的佣金奖励必须同时提取。

上述场景已在 hooks.md 中覆盖。

此处概述的分发机制用于在验证者和关联委托人之间懒惰地分发以下奖励：

社会化分配的多代币费用
通货膨胀的质押资产供应
验证者对其委托人质押的所有奖励的佣金

费用会集中在一个全球池中。所使用的机制允许验证者和委托人独立且懒惰地提取他们的奖励。

不足之处

作为懒惰计算的一部分，每个委托人持有一个特定于每个验证者的累积项，用于估算他们在全球费用池中应得的代币的近似公平份额。

entitlement = delegator-accumulation / all-delegators-accumulation

在每个区块都有恒定且相等的奖励代币流入的情况下，这种分发机制将等同于主动分发（每个区块单独分发给所有委托人）。然而，这种情况不现实，因此会出现偏离主动分发的情况，偏差主要由奖励代币流入的波动以及其他委托人提取奖励的时机引起。

对质押的影响

在 BPoS 中，对 Atom 供应收取佣金的同时又允许 Atom 供应自动绑定（直接分配到验证者的质押）是有问题的。从根本上讲，这两种机制是互斥的。如果同时对质押代币应用佣金和自动绑定机制，那么每个区块中，质押代币在任何验证者及其委托人之间的分配都会发生变化。这就需要为每个区块的每个委托记录进行计算，这在计算上是昂贵的。

总之，我们只能选择 Atom 佣金和未绑定的 Atom 供应，或者绑定的 Atom 供应而不收取 Atom 佣金，我们选择实现前者。希望重新绑定其供应的利益相关者可以选择设置脚本定期提取并重新绑定奖励。

概念

当验证者被移除或请求提取时，验证者的佣金会被支付。佣金会在每次 BeginBlock 操作时计算并递增，以更新累计的费用金额。

当委托发生变化、被移除或请求提取时，奖励会分发给委托人。在奖励分发之前，所有在当前委托期间发生的验证者惩罚（slash）都会被应用。

F1 费用分发中的引用计数

在 F1 费用分发中，委托人收到的奖励是在他们撤回委托时计算的。这个计算必须读取奖励总和的项，其中奖励被划分为他们委托时结束的周期中的代币份额，以及为撤回而创建的最终周期。

此外，由于惩罚会改变委托所持代币的数量（但我们懒惰计算，只有在委托人取消委托时才计算），我们必须在委托人委托和撤回奖励之间发生的惩罚事件之前/之后分别计算奖励。因此，惩罚就像委托一样，引用由惩罚事件结束的周期。

所有不再被任何委托或任何惩罚引用的历史奖励记录，可以安全地删除，因为它们永远不会被读取（未来的委托和未来的惩罚将始终引用未来的周期）。这是通过跟踪每个历史奖励存储条目的引用计数来实现的。每次创建一个可能需要引用历史记录的新对象（委托或惩罚）时，引用计数都会增加。每次删除一个之前需要引用历史记录的对象时，引用计数都会减少。如果引用计数为零，则删除历史记录。

状态

FeePool

所有用于分发的全局跟踪参数都存储在 FeePool 中。奖励会被收集并添加到奖励池，并从此池中分配给验证者/委托人。

需要注意的是，奖励池持有小数代币（DecCoins），以允许从通货膨胀等操作中接收代币的分数部分。当代币从池中分发时，它们会被截断回 sdk.Coins，后者是不带小数的。

FeePool: 0x00 -> ProtocolBuffer(FeePool)

// coins with decimal
type DecCoins []DecCoin

type DecCoin struct {
    Amount math.LegacyDec
    Denom  string
}

https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/distribution/v1beta1/distribution.proto#L116-L123

验证者分发

每次发生以下情况时，相关验证者的分发信息都会更新：

委托给验证者的金额发生变化
任何委托人从验证者处提取奖励
验证者提取其佣金

ValidatorDistInfo: 0x02 | ValOperatorAddrLen (1 byte) | ValOperatorAddr -> ProtocolBuffer(validatorDistribution)

type ValidatorDistInfo struct {
    OperatorAddress     sdk.AccAddress
    SelfBondRewards     sdkmath.DecCoins
    ValidatorCommission types.ValidatorAccumulatedCommission
}

委托分发

每个委托分发只需要记录最后一次提取费用时的区块高度。因为每次委托的属性发生变化时（例如绑定代币等），必须提取费用，所以其属性将保持不变，委托人的累积因子可以通过仅知道最后一次提取的区块高度和当前属性来被动计算。

DelegationDistInfo: 0x02 | DelegatorAddrLen (1 byte) | DelegatorAddr | ValOperatorAddrLen (1 byte) | ValOperatorAddr -> ProtocolBuffer(delegatorDist)

type DelegationDistInfo struct {
    WithdrawalHeight int64    // last time this delegation withdrew rewards
}

参数

分发模块将其参数以 0x09 前缀存储在状态中，可以通过治理或具有权限的地址进行更新。

Params: 0x09 | ProtocolBuffer(Params)

https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/distribution/v1beta1/distribution.proto#L12-L42

Begin Block

在每个 BeginBlock 中，上一块中收到的所有费用会转移到分发模块的 ModuleAccount 账户。当委托人或验证者提取他们的奖励时，这些奖励会从 ModuleAccount 中取出。在 BeginBlock 时，收集的费用的不同索赔会按以下方式更新：

收取储备社区税。
剩余部分按投票权比例分配给所有已绑定的验证者。

分发方案

假设 fees 为上一块中收取的总费用，包括质押的通货膨胀奖励。所有费用在区块期间会被收集到一个特定的模块账户中。在 BeginBlock 时，它们会被转移到“分发”模块账户中。不会发生其他代币发送操作。相反，每个账户有权获得的奖励会被存储，并且可以通过 FundCommunityPool、WithdrawValidatorCommission 和 WithdrawDelegatorReward 消息触发提取。

奖励到社区池

社区池将获得 community_tax * fees，加上验证者获得奖励后剩余的任何零头（这些奖励总是四舍五入到最接近的整数值）。

奖励到验证者

提案者不会获得额外的奖励。所有费用会按照验证者的共识权重（包括提案者）在所有已绑定的验证者之间按比例分配。

powFrac = validator power / total bonded validator power
voteMul = 1 - community_tax

所有验证者会收到 fees * voteMul * powFrac 的奖励。

奖励到委托人

每个验证者的奖励会分配给其委托人。验证者的自委托也被视为普通委托，并在分配计算中一同处理。

验证者可以设置一个佣金率。佣金率是可调整的，但每个验证者必须设定一个最大佣金率和每日最大增长率。这些最大限制不可被突破，以防止验证者突然提高佣金率，从而获取所有奖励，保护委托人的利益。

示例分发

在该示例中，底层共识引擎按照验证者相对于整个绑定权重的比例选择区块提案者。

假设所有验证者在其提议的区块中包含 pre-commits 的表现均等，保持 (pre_commits included) / (total bonded validator power) 恒定，则验证者的摊销区块奖励为：

(delegator proportion of the validator power / validator power) * (validator power / total bonded power)
  * (1 - community tax rate) * (1 - validator commission rate)
= (delegator proportion of the validator power / total bonded power) * (1 -
community tax rate) * (1 - validator commission rate)

消息

MsgSetWithdrawAddress

默认情况下，提取地址为委托人地址。若要更改提取地址，委托人必须发送 MsgSetWithdrawAddress 消息。仅当参数 WithdrawAddrEnabled 设置为 true 时，才能更改提取地址。

提取地址不能是任何模块账户。这些账户在初始化时被添加到 distribution 记录器 (keeper) 的 blockedAddrs 数组中，因此被阻止用作提取地址。

响应：

https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/distribution/v1beta1/tx.proto#L49-L60

func (k Keeper) SetWithdrawAddr(ctx context.Context, delegatorAddr sdk.AccAddress, withdrawAddr sdk.AccAddress) error
	if k.blockedAddrs[withdrawAddr.String()] {
		fail with "`{withdrawAddr}` is not allowed to receive external funds"
	}

	if !k.GetWithdrawAddrEnabled(ctx) {
		fail with `ErrSetWithdrawAddrDisabled`
	}

	k.SetDelegatorWithdrawAddr(ctx, delegatorAddr, withdrawAddr)

MsgWithdrawDelegatorReward

委托人可以提取其奖励。在 distribution 模块内部，此交易会同时移除先前的委托及其相关奖励，相当于委托人重新创建了相同数额的新委托。奖励会立即从 distribution ModuleAccount 发送至提取地址。任何余数（因小数截断产生的剩余部分）都会转入 community pool。

委托的起始区块高度会被设置为当前的验证人周期 (validator period)，并且前一个周期的引用计数 (reference count) 会递减。提取的金额会从 ValidatorOutstandingRewards 变量中扣除。

在 F1 分配机制中，总奖励按 validator period 计算，委托人按其在验证人中的 stake 比例获得相应奖励。在基础 F1 机制中，所有委托人在某两个周期 (A 和 B) 之间应得的总奖励按以下方式计算：设 R(X) 为周期 X 之前的累积总奖励，除以当时的质押 stake 数量。计算委托人奖励：R(X) * delegator_stake。计算 A 到 B 之间所有委托人应得的奖励总额：(R(B) - R(A)) * total_stake。

然而，上述计算方式未考虑削减 (slashing) 事件的影响。

考虑削减影响时，需要进行迭代计算。设 F(X) 为某个削减事件在周期 X 发生时，验证人被削减的比例。如果验证人在 P1, ..., PN 这些周期被削减，并且 A < P1 < PN < B，则 distribution 模块计算单个委托人的奖励 T(A, B) 如下：

stake := initial stake
rewards := 0
previous := A
for P in P1, ..., PN`:
    rewards = (R(P) - previous) * stake
    stake = stake * F(P)
    previous = P
rewards = rewards + (R(B) - R(PN)) * stake

历史奖励的计算是通过回溯所有削减 (slashes)，并在每个步骤衰减 (attenuate) 委托人的 stake 来完成的。最终计算出的 stake 等同于实际委托中的质押代币数量，但可能会因四舍五入误差 (rounding errors) 产生一定的误差范围。

响应:

https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/distribution/v1beta1/tx.proto#L66-L77

WithdrawValidatorCommission

验证人 (validator) 可以发送 WithdrawValidatorCommission 消息来提取其累积的佣金 (commission)。佣金在每个区块的 BeginBlock 阶段计算，因此提取时无需迭代计算。提取的金额将从该验证人的 ValidatorOutstandingRewards 变量中扣除。

仅支持提取整数金额 (integer amounts)，如果累积奖励包含小数部分 (decimals)，提取前会进行截断 (truncated)，剩余部分可在后续继续提取。

FundCommunityPool

该消息 (FundCommunityPool) 直接将代币从发送方转入社区资金池 (community pool)。

如果指定金额无法从发送方账户成功转账至分发模块账户 (distribution module account)，则交易将失败。

func (k Keeper) FundCommunityPool(ctx context.Context, amount sdk.Coins, sender sdk.AccAddress) error {
  if err := k.bankKeeper.SendCoinsFromAccountToModule(ctx, sender, types.ModuleName, amount); err != nil {
    return err
  }

  feePool, err := k.FeePool.Get(ctx)
  if err != nil {
    return err
  }

  feePool.CommunityPool = feePool.CommunityPool.Add(sdk.NewDecCoinsFromCoins(amount...)...)
	
  if err := k.FeePool.Set(ctx, feePool); err != nil {
    return err
  }

  return nil
}

常见的分发操作

这些操作涉及多个不同的消息

Initialize delegation

每当更改 delegation 时，奖励将被提取，并且 delegation 将被重新初始化。初始化 delegation 会增加 validator period，并记录 delegation 的起始周期。

// initialize starting info for a new delegation
func (k Keeper) initializeDelegation(ctx context.Context, val sdk.ValAddress, del sdk.AccAddress) {
    // period has already been incremented - we want to store the period ended by this delegation action
    previousPeriod := k.GetValidatorCurrentRewards(ctx, val).Period - 1

	// increment reference count for the period we're going to track
	k.incrementReferenceCount(ctx, val, previousPeriod)

	validator := k.stakingKeeper.Validator(ctx, val)
	delegation := k.stakingKeeper.Delegation(ctx, del, val)

	// calculate delegation stake in tokens
	// we don't store directly, so multiply delegation shares * (tokens per share)
	// note: necessary to truncate so we don't allow withdrawing more rewards than owed
	stake := validator.TokensFromSharesTruncated(delegation.GetShares())
	k.SetDelegatorStartingInfo(ctx, val, del, types.NewDelegatorStartingInfo(previousPeriod, stake, uint64(ctx.BlockHeight())))
}

MsgUpdateParams

Distribution 模块参数可以通过 MsgUpdateParams 更新，更新操作可以通过治理提案完成，签名者将始终是 gov 模块账户地址。

https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/distribution/v1beta1/tx.proto#L133-L147

如果以下情况发生，消息处理可能会失败：

如果签名者不是 gov 模块账户地址，消息处理将失败。

钩子(Hooks)

此模块可以调用的可用钩子。

创建或修改 `delegation` 分配。

触发者: staking.MsgDelegate, staking.MsgBeginRedelegate, staking.MsgUndelegate

之前

delegation 奖励被提取到委托人的提取地址。奖励包括当前周期，不包括起始周期。
validator period 被递增。validator period 递增是因为验证人的权重和份额分配可能发生了变化。
委托人起始周期的引用计数被递减。

之后

delegation 的起始高度设置为上一个周期。由于 Before-hook，这个周期是委托人最后一次获得奖励的周期。

验证者创建。

触发者: staking.MsgCreateValidator

当创建 validator 时，以下 validator 变量将被初始化：

历史奖励
当前累计奖励
累计佣金
总未支付奖励
周期

默认情况下，除 period 外，所有值都设置为 0，period 设置为 1。

验证者移除

触发者: staking.RemoveValidator

未支付的佣金将发送到验证人的自我委托提取地址。剩余的委托人奖励将发送到社区费用池。注意：只有当验证人没有剩余的委托时，它才会被移除。此时，所有未支付的委托人奖励将被提取，任何剩余的奖励都将是微不足道的金额。

验证者被惩罚

触发者：staking.Slash
当前验证人周期的引用计数被递增。引用计数递增是因为惩罚事件已创建对它的引用。
validator period 被递增。
惩罚事件将被存储以供后续使用。惩罚事件将在计算委托人奖励时被引用。

事件

Distribution 模块会发出以下事件：

BeginBlocker

类型

属性键

属性值

proposer_reward

validator

{validatorAddress}

proposer_reward

reward

{proposerReward}

commission

amount

{commissionAmount}

commission

validator

{validatorAddress}

rewards

amount

{rewardAmount}

rewards

validator

{validatorAddress}

Handlers

MsgSetWithdrawAddress

类型

属性键

属性值

set_withdraw_address

withdraw_address

{withdrawAddress}

message

module

distribution

message

action

set_withdraw_address

message

sender

{senderAddress}

MsgWithdrawDelegatorReward

类型

属性键

属性值

withdraw_rewards

amount

{rewardAmount}

withdraw_rewards

validator

{validatorAddress}

message

module

distribution

message

action

withdraw_delegator_reward

message

sender

{senderAddress}

MsgWithdrawValidatorCommission

类型

属性键

属性值

withdraw_commission

amount

{commissionAmount}

message

module

distribution

message

action

withdraw_validator_commission

message

sender

{senderAddress}

Parameters

Distribution 模块包含以下参数：

键

类型

示例

communitytax

string (dec)

"0.020000000000000000" [0]

withdrawaddrenabled

bool

true

:::note The reserve pool is the pool of collected funds for use by governance taken via the CommunityTax. Currently with the Cosmos SDK, tokens collected by the CommunityTax are accounted for but unspendable. :::

[0] communitytax 必须是正数，并且不能超过 1.00。
baseproposerreward 和 bonusproposerreward 是在 v0.47 中已弃用的参数，不再使用。

:::note reserve pool 是通过 CommunityTax 收取的资金池，用于治理。目前，在 Cosmos SDK 中，通过 CommunityTax 收取的代币已被记账，但无法使用。:::

客户端

CLI

用户可以使用 CLI 查询和与 distribution 模块进行交互。

Query

query命令允许用户查询 distribution 状态。

simd query distribution --help

commission

commission 命令允许用户按地址查询验证人佣金奖励。

simd query distribution commission [address] [flags]

示例:

simd query distribution commission cosmosvaloper1...

示例输出:

commission:
- amount: "1000000.000000000000000000"
  denom: stake

community-pool

community-pool 命令允许用户查询社区池中的所有代币余额。

simd query distribution community-pool [flags]

示例:

simd query distribution community-pool

示例输出:

pool:
- amount: "1000000.000000000000000000"
  denom: stake

params

params 命令允许用户查询 distribution 模块的参数。

simd query distribution params [flags]

示例:

simd query distribution params

示例输出:

base_proposer_reward: "0.000000000000000000"
bonus_proposer_reward: "0.000000000000000000"
community_tax: "0.020000000000000000"
withdraw_addr_enabled: true

rewards

rewards 命令允许用户查询委托人奖励。用户可以选择性地包括验证人地址，以查询从特定验证人获得的奖励。

simd query distribution rewards [delegator-addr] [validator-addr] [flags]

示例:

simd query distribution rewards cosmos1...

示例输出:

rewards:
- reward:
  - amount: "1000000.000000000000000000"
    denom: stake
  validator_address: cosmosvaloper1..
total:
- amount: "1000000.000000000000000000"
  denom: stake

slashes

slashes 命令允许用户查询给定区块范围内的所有惩罚记录。

simd query distribution slashes [validator] [start-height] [end-height] [flags]

示例:

simd query distribution slashes cosmosvaloper1... 1 1000

示例输出:

pagination:
  next_key: null
  total: "0"
slashes:
- validator_period: 20,
  fraction: "0.009999999999999999"

validator-outstanding-rewards

The validator-outstanding-rewards 命令允许用户查询验证人及其所有委托的所有未提取（未提取）的奖励。

simd query distribution validator-outstanding-rewards [validator] [flags]

示例:

simd query distribution validator-outstanding-rewards cosmosvaloper1...

示例输出:

rewards:
- amount: "1000000.000000000000000000"
  denom: stake

validator-distribution-info

validator-distribution-info 命令允许用户查询验证人的佣金和自我委托奖励。

simd query distribution validator-distribution-info cosmosvaloper1...
```

Example Output:

```yml
commission:
- amount: "100000.000000000000000000"
  denom: stake
operator_address: cosmosvaloper1...
self_bond_rewards:
- amount: "100000.000000000000000000"
  denom: stake
```

#### Transactions

The `tx` commands allow users to interact with the `distribution` module.

```shell
simd tx distribution --help
```

##### fund-community-pool

The `fund-community-pool` command allows users to send funds to the community pool.

```shell
simd tx distribution fund-community-pool [amount] [flags]
```

Example:

```shell
simd tx distribution fund-community-pool 100stake --from cosmos1...
```

##### set-withdraw-addr

The `set-withdraw-addr` command allows users to set the withdraw address for rewards associated with a delegator address.

```shell
simd tx distribution set-withdraw-addr [withdraw-addr] [flags]
```

Example:

```shell
simd tx distribution set-withdraw-addr cosmos1... --from cosmos1...
```

##### withdraw-all-rewards

The `withdraw-all-rewards` command allows users to withdraw all rewards for a delegator.

```shell
simd tx distribution withdraw-all-rewards [flags]
```

Example:

```shell
simd tx distribution withdraw-all-rewards --from cosmos1...
```

##### withdraw-rewards

The `withdraw-rewards` command allows users to withdraw all rewards from a given delegation address,
and optionally withdraw validator commission if the delegation address given is a validator operator and the user proves the `--commission` flag.

```shell
simd tx distribution withdraw-rewards [validator-addr] [flags]
```

Example:

```shell
simd tx distribution withdraw-rewards cosmosvaloper1... --from cosmos1... --commission
```

### gRPC

A user can query the `distribution` module using gRPC endpoints.

#### Params

The `Params` endpoint allows users to query parameters of the `distribution` module.

Example:

```shell
grpcurl -plaintext \
    localhost:9090 \
    cosmos.distribution.v1beta1.Query/Params
```

Example Output:

```json
{
  "params": {
    "communityTax": "20000000000000000",
    "baseProposerReward": "00000000000000000",
    "bonusProposerReward": "00000000000000000",
    "withdrawAddrEnabled": true
  }
}
```

#### ValidatorDistributionInfo

The `ValidatorDistributionInfo` queries validator commission and self-delegation rewards for validator.

Example:

```shell
grpcurl -plaintext \
    -d '{"validator_address":"cosmosvalop1..."}' \
    localhost:9090 \
    cosmos.distribution.v1beta1.Query/ValidatorDistributionInfo
```

Example Output:

```json
{
  "commission": {
    "commission": [
      {
        "denom": "stake",
        "amount": "1000000000000000"
      }
    ]
  },
  "self_bond_rewards": [
    {
      "denom": "stake",
      "amount": "1000000000000000"
    }
  ],
  "validator_address": "cosmosvalop1..."
}
```

#### ValidatorOutstandingRewards

The `ValidatorOutstandingRewards` endpoint allows users to query rewards of a validator address.

Example:

```shell
grpcurl -plaintext \
    -d '{"validator_address":"cosmosvalop1.."}' \
    localhost:9090 \
    cosmos.distribution.v1beta1.Query/ValidatorOutstandingRewards
```

Example Output:

```json
{
  "rewards": {
    "rewards": [
      {
        "denom": "stake",
        "amount": "1000000000000000"
      }
    ]
  }
}
```

#### ValidatorCommission

The `ValidatorCommission` endpoint allows users to query accumulated commission for a validator.

Example:

```shell
grpcurl -plaintext \
    -d '{"validator_address":"cosmosvalop1.."}' \
    localhost:9090 \
    cosmos.distribution.v1beta1.Query/ValidatorCommission
```

Example Output:

```json
{
  "commission": {
    "commission": [
      {
        "denom": "stake",
        "amount": "1000000000000000"
      }
    ]
  }
}
```

#### ValidatorSlashes

The `ValidatorSlashes` endpoint allows users to query slash events of a validator.

Example:

```shell
grpcurl -plaintext \
    -d '{"validator_address":"cosmosvalop1.."}' \
    localhost:9090 \
    cosmos.distribution.v1beta1.Query/ValidatorSlashes
```

Example Output:

```json
{
  "slashes": [
    {
      "validator_period": "20",
      "fraction": "0.009999999999999999"
    }
  ],
  "pagination": {
    "total": "1"
  }
}
```

#### DelegationRewards

The `DelegationRewards` endpoint allows users to query the total rewards accrued by a delegation.

Example:

```shell
grpcurl -plaintext \
    -d '{"delegator_address":"cosmos1...","validator_address":"cosmosvalop1..."}' \
    localhost:9090 \
    cosmos.distribution.v1beta1.Query/DelegationRewards
```

Example Output:

```json
{
  "rewards": [
    {
      "denom": "stake",
      "amount": "1000000000000000"
    }
  ]
}
```

#### DelegationTotalRewards

The `DelegationTotalRewards` endpoint allows users to query the total rewards accrued by each validator.

Example:

```shell
grpcurl -plaintext \
    -d '{"delegator_address":"cosmos1..."}' \
    localhost:9090 \
    cosmos.distribution.v1beta1.Query/DelegationTotalRewards
```

Example Output:

```json
{
  "rewards": [
    {
      "validatorAddress": "cosmosvaloper1...",
      "reward": [
        {
          "denom": "stake",
          "amount": "1000000000000000"
        }
      ]
    }
  ],
  "total": [
    {
      "denom": "stake",
      "amount": "1000000000000000"
    }
  ]
}
```

#### DelegatorValidators

The `DelegatorValidators` endpoint allows users to query all validators for given delegator.

Example:

```shell
grpcurl -plaintext \
    -d '{"delegator_address":"cosmos1..."}' \
    localhost:9090 \
    cosmos.distribution.v1beta1.Query/DelegatorValidators
```

Example Output:

```json
{
  "validators": ["cosmosvaloper1..."]
}
```

#### DelegatorWithdrawAddress

The `DelegatorWithdrawAddress` endpoint allows users to query the withdraw address of a delegator.

Example:

```shell
grpcurl -plaintext \
    -d '{"delegator_address":"cosmos1..."}' \
    localhost:9090 \
    cosmos.distribution.v1beta1.Query/DelegatorWithdrawAddress
```

Example Output:

```json
{
  "withdrawAddress": "cosmos1..."
}
```

#### CommunityPool

The `CommunityPool` endpoint allows users to query the community pool coins.

Example:

```shell
grpcurl -plaintext \
    localhost:9090 \
    cosmos.distribution.v1beta1.Query/CommunityPool
```

Example Output:

```json
{
  "pool": [
    {
      "denom": "stake",
      "amount": "1000000000000000000"
    }
  ]
}
```

Previous危机(Crisis)Next证据(Evidence)

Last updated 1 month ago

分发(Distribution)

摘要

在提取时，必须提取其应得的最大金额，不留任何资金在池中。
在绑定、解绑或将代币重新委托到现有账户时，必须完全提取奖励（因为懒惰记账的规则已发生变化）。
当验证者选择更改奖励的佣金时，所有累积的佣金奖励必须同时提取。

上述场景已在 hooks.md 中覆盖。

此处概述的分发机制用于在验证者和关联委托人之间懒惰地分发以下奖励：

社会化分配的多代币费用
通货膨胀的质押资产供应
验证者对其委托人质押的所有奖励的佣金

费用会集中在一个全球池中。所使用的机制允许验证者和委托人独立且懒惰地提取他们的奖励。

不足之处

作为懒惰计算的一部分，每个委托人持有一个特定于每个验证者的累积项，用于估算他们在全球费用池中应得的代币的近似公平份额。

entitlement = delegator-accumulation / all-delegators-accumulation

如果你知道即将大幅增加奖励，你将被激励在此事件发生后再提取奖励，从而增加你现有累积的价值。有关更多细节，请参见。

对质押的影响

概念

在权益证明（PoS）区块链中，来自交易费用的奖励支付给验证者。费用分发模块将奖励公平地分配给验证者的组成委托人。奖励是按周期计算的。每次验证者的委托发生变化时，周期会更新，例如，当验证者接收到新的委托时。然后，可以通过计算周期前的总奖励减去当前总奖励来计算单个验证者的奖励。欲了解更多信息，请参阅。

当验证者被移除或请求提取时，验证者的佣金会被支付。佣金会在每次 BeginBlock 操作时计算并递增，以更新累计的费用金额。

当委托发生变化、被移除或请求提取时，奖励会分发给委托人。在奖励分发之前，所有在当前委托期间发生的验证者惩罚（slash）都会被应用。

F1 费用分发中的引用计数

状态

FeePool

所有用于分发的全局跟踪参数都存储在 FeePool 中。奖励会被收集并添加到奖励池，并从此池中分配给验证者/委托人。

FeePool: 0x00 -> ProtocolBuffer(FeePool)

// coins with decimal
type DecCoins []DecCoin

type DecCoin struct {
    Amount math.LegacyDec
    Denom  string
}

https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/distribution/v1beta1/distribution.proto#L116-L123

验证者分发

每次发生以下情况时，相关验证者的分发信息都会更新：

委托给验证者的金额发生变化
任何委托人从验证者处提取奖励
验证者提取其佣金

ValidatorDistInfo: 0x02 | ValOperatorAddrLen (1 byte) | ValOperatorAddr -> ProtocolBuffer(validatorDistribution)

type ValidatorDistInfo struct {
    OperatorAddress     sdk.AccAddress
    SelfBondRewards     sdkmath.DecCoins
    ValidatorCommission types.ValidatorAccumulatedCommission
}

委托分发

DelegationDistInfo: 0x02 | DelegatorAddrLen (1 byte) | DelegatorAddr | ValOperatorAddrLen (1 byte) | ValOperatorAddr -> ProtocolBuffer(delegatorDist)

type DelegationDistInfo struct {
    WithdrawalHeight int64    // last time this delegation withdrew rewards
}

参数

分发模块将其参数以 0x09 前缀存储在状态中，可以通过治理或具有权限的地址进行更新。

Params: 0x09 | ProtocolBuffer(Params)

https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/distribution/v1beta1/distribution.proto#L12-L42

Begin Block

收取储备社区税。
剩余部分按投票权比例分配给所有已绑定的验证者。

分发方案

参见以了解参数的描述。

奖励到社区池

社区池将获得 community_tax * fees，加上验证者获得奖励后剩余的任何零头（这些奖励总是四舍五入到最接近的整数值）。

奖励到验证者

提案者不会获得额外的奖励。所有费用会按照验证者的共识权重（包括提案者）在所有已绑定的验证者之间按比例分配。

powFrac = validator power / total bonded validator power
voteMul = 1 - community_tax

所有验证者会收到 fees * voteMul * powFrac 的奖励。

奖励到委托人

每个验证者的奖励会分配给其委托人。验证者的自委托也被视为普通委托，并在分配计算中一同处理。

验证者应得但尚未提取的奖励存储在 ValidatorAccumulatedCommission，而委托人应得的奖励存储在 ValidatorCurrentRewards。方案用于计算委托人的奖励，该计算发生在委托人提取奖励或更新委托时，因此不会在 BeginBlock 期间处理。

示例分发

在该示例中，底层共识引擎按照验证者相对于整个绑定权重的比例选择区块提案者。

假设所有验证者在其提议的区块中包含 pre-commits 的表现均等，保持 (pre_commits included) / (total bonded validator power) 恒定，则验证者的摊销区块奖励为：

(delegator proportion of the validator power / validator power) * (validator power / total bonded power)
  * (1 - community tax rate) * (1 - validator commission rate)
= (delegator proportion of the validator power / total bonded power) * (1 -
community tax rate) * (1 - validator commission rate)

消息

MsgSetWithdrawAddress

提取地址不能是任何模块账户。这些账户在初始化时被添加到 distribution 记录器 (keeper) 的 blockedAddrs 数组中，因此被阻止用作提取地址。

响应：

https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/distribution/v1beta1/tx.proto#L49-L60

func (k Keeper) SetWithdrawAddr(ctx context.Context, delegatorAddr sdk.AccAddress, withdrawAddr sdk.AccAddress) error
	if k.blockedAddrs[withdrawAddr.String()] {
		fail with "`{withdrawAddr}` is not allowed to receive external funds"
	}

	if !k.GetWithdrawAddrEnabled(ctx) {
		fail with `ErrSetWithdrawAddrDisabled`
	}

	k.SetDelegatorWithdrawAddr(ctx, delegatorAddr, withdrawAddr)

MsgWithdrawDelegatorReward

然而，上述计算方式未考虑削减 (slashing) 事件的影响。

stake := initial stake
rewards := 0
previous := A
for P in P1, ..., PN`:
    rewards = (R(P) - previous) * stake
    stake = stake * F(P)
    previous = P
rewards = rewards + (R(B) - R(PN)) * stake

响应:

https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/distribution/v1beta1/tx.proto#L66-L77

WithdrawValidatorCommission

仅支持提取整数金额 (integer amounts)，如果累积奖励包含小数部分 (decimals)，提取前会进行截断 (truncated)，剩余部分可在后续继续提取。

FundCommunityPool

该消息 (FundCommunityPool) 直接将代币从发送方转入社区资金池 (community pool)。

如果指定金额无法从发送方账户成功转账至分发模块账户 (distribution module account)，则交易将失败。

func (k Keeper) FundCommunityPool(ctx context.Context, amount sdk.Coins, sender sdk.AccAddress) error {
  if err := k.bankKeeper.SendCoinsFromAccountToModule(ctx, sender, types.ModuleName, amount); err != nil {
    return err
  }

  feePool, err := k.FeePool.Get(ctx)
  if err != nil {
    return err
  }

  feePool.CommunityPool = feePool.CommunityPool.Add(sdk.NewDecCoinsFromCoins(amount...)...)
	
  if err := k.FeePool.Set(ctx, feePool); err != nil {
    return err
  }

  return nil
}

常见的分发操作

这些操作涉及多个不同的消息

Initialize delegation

每当更改 delegation 时，奖励将被提取，并且 delegation 将被重新初始化。初始化 delegation 会增加 validator period，并记录 delegation 的起始周期。

// initialize starting info for a new delegation
func (k Keeper) initializeDelegation(ctx context.Context, val sdk.ValAddress, del sdk.AccAddress) {
    // period has already been incremented - we want to store the period ended by this delegation action
    previousPeriod := k.GetValidatorCurrentRewards(ctx, val).Period - 1

	// increment reference count for the period we're going to track
	k.incrementReferenceCount(ctx, val, previousPeriod)

	validator := k.stakingKeeper.Validator(ctx, val)
	delegation := k.stakingKeeper.Delegation(ctx, del, val)

	// calculate delegation stake in tokens
	// we don't store directly, so multiply delegation shares * (tokens per share)
	// note: necessary to truncate so we don't allow withdrawing more rewards than owed
	stake := validator.TokensFromSharesTruncated(delegation.GetShares())
	k.SetDelegatorStartingInfo(ctx, val, del, types.NewDelegatorStartingInfo(previousPeriod, stake, uint64(ctx.BlockHeight())))
}

MsgUpdateParams

Distribution 模块参数可以通过 MsgUpdateParams 更新，更新操作可以通过治理提案完成，签名者将始终是 gov 模块账户地址。

https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/distribution/v1beta1/tx.proto#L133-L147

如果以下情况发生，消息处理可能会失败：

如果签名者不是 gov 模块账户地址，消息处理将失败。

钩子(Hooks)

此模块可以调用的可用钩子。

创建或修改 `delegation` 分配。

触发者: staking.MsgDelegate, staking.MsgBeginRedelegate, staking.MsgUndelegate

之前

delegation 奖励被提取到委托人的提取地址。奖励包括当前周期，不包括起始周期。
validator period 被递增。validator period 递增是因为验证人的权重和份额分配可能发生了变化。
委托人起始周期的引用计数被递减。

之后

delegation 的起始高度设置为上一个周期。由于 Before-hook，这个周期是委托人最后一次获得奖励的周期。

验证者创建。

触发者: staking.MsgCreateValidator

当创建 validator 时，以下 validator 变量将被初始化：

历史奖励
当前累计奖励
累计佣金
总未支付奖励
周期

默认情况下，除 period 外，所有值都设置为 0，period 设置为 1。

验证者移除

触发者: staking.RemoveValidator

验证者被惩罚

触发者：staking.Slash
当前验证人周期的引用计数被递增。引用计数递增是因为惩罚事件已创建对它的引用。
validator period 被递增。
惩罚事件将被存储以供后续使用。惩罚事件将在计算委托人奖励时被引用。

事件

Distribution 模块会发出以下事件：

BeginBlocker

类型

属性键

属性值

proposer_reward

validator

{validatorAddress}

proposer_reward

reward

{proposerReward}

commission

amount

{commissionAmount}

commission

validator

{validatorAddress}

rewards

amount

{rewardAmount}

rewards

validator

{validatorAddress}

Handlers

MsgSetWithdrawAddress

类型

属性键

属性值

set_withdraw_address

withdraw_address

{withdrawAddress}

message

module

distribution

message

action

set_withdraw_address

message

sender

{senderAddress}

MsgWithdrawDelegatorReward

类型

属性键

属性值

withdraw_rewards

amount

{rewardAmount}

withdraw_rewards

validator

{validatorAddress}

message

module

distribution

message

action

withdraw_delegator_reward

message

sender

{senderAddress}

MsgWithdrawValidatorCommission

类型

属性键

属性值

withdraw_commission

amount

{commissionAmount}

message

module

distribution

message

action

withdraw_validator_commission

message

sender

{senderAddress}

Parameters

Distribution 模块包含以下参数：

键

类型

示例

communitytax

string (dec)

"0.020000000000000000" [0]

withdrawaddrenabled

bool

true

[0] communitytax 必须是正数，并且不能超过 1.00。
baseproposerreward 和 bonusproposerreward 是在 v0.47 中已弃用的参数，不再使用。

:::note reserve pool 是通过 CommunityTax 收取的资金池，用于治理。目前，在 Cosmos SDK 中，通过 CommunityTax 收取的代币已被记账，但无法使用。:::

客户端

CLI

用户可以使用 CLI 查询和与 distribution 模块进行交互。

Query

query命令允许用户查询 distribution 状态。

simd query distribution --help

commission

commission 命令允许用户按地址查询验证人佣金奖励。

simd query distribution commission [address] [flags]

示例:

simd query distribution commission cosmosvaloper1...

示例输出:

commission:
- amount: "1000000.000000000000000000"
  denom: stake

community-pool

community-pool 命令允许用户查询社区池中的所有代币余额。

simd query distribution community-pool [flags]

示例:

simd query distribution community-pool

示例输出:

pool:
- amount: "1000000.000000000000000000"
  denom: stake

params

params 命令允许用户查询 distribution 模块的参数。

simd query distribution params [flags]

示例:

simd query distribution params

示例输出:

base_proposer_reward: "0.000000000000000000"
bonus_proposer_reward: "0.000000000000000000"
community_tax: "0.020000000000000000"
withdraw_addr_enabled: true

rewards

rewards 命令允许用户查询委托人奖励。用户可以选择性地包括验证人地址，以查询从特定验证人获得的奖励。

simd query distribution rewards [delegator-addr] [validator-addr] [flags]

示例:

simd query distribution rewards cosmos1...

示例输出:

rewards:
- reward:
  - amount: "1000000.000000000000000000"
    denom: stake
  validator_address: cosmosvaloper1..
total:
- amount: "1000000.000000000000000000"
  denom: stake

slashes

slashes 命令允许用户查询给定区块范围内的所有惩罚记录。

simd query distribution slashes [validator] [start-height] [end-height] [flags]

示例:

simd query distribution slashes cosmosvaloper1... 1 1000

示例输出:

pagination:
  next_key: null
  total: "0"
slashes:
- validator_period: 20,
  fraction: "0.009999999999999999"

validator-outstanding-rewards

The validator-outstanding-rewards 命令允许用户查询验证人及其所有委托的所有未提取（未提取）的奖励。

simd query distribution validator-outstanding-rewards [validator] [flags]

示例:

simd query distribution validator-outstanding-rewards cosmosvaloper1...

示例输出:

rewards:
- amount: "1000000.000000000000000000"
  denom: stake

validator-distribution-info

validator-distribution-info 命令允许用户查询验证人的佣金和自我委托奖励。

simd query distribution validator-distribution-info cosmosvaloper1...
```

Example Output:

```yml
commission:
- amount: "100000.000000000000000000"
  denom: stake
operator_address: cosmosvaloper1...
self_bond_rewards:
- amount: "100000.000000000000000000"
  denom: stake
```

#### Transactions

The `tx` commands allow users to interact with the `distribution` module.

```shell
simd tx distribution --help
```

##### fund-community-pool

The `fund-community-pool` command allows users to send funds to the community pool.

```shell
simd tx distribution fund-community-pool [amount] [flags]
```

Example:

```shell
simd tx distribution fund-community-pool 100stake --from cosmos1...
```

##### set-withdraw-addr

The `set-withdraw-addr` command allows users to set the withdraw address for rewards associated with a delegator address.

```shell
simd tx distribution set-withdraw-addr [withdraw-addr] [flags]
```

Example:

```shell
simd tx distribution set-withdraw-addr cosmos1... --from cosmos1...
```

##### withdraw-all-rewards

The `withdraw-all-rewards` command allows users to withdraw all rewards for a delegator.

```shell
simd tx distribution withdraw-all-rewards [flags]
```

Example:

```shell
simd tx distribution withdraw-all-rewards --from cosmos1...
```

##### withdraw-rewards

The `withdraw-rewards` command allows users to withdraw all rewards from a given delegation address,
and optionally withdraw validator commission if the delegation address given is a validator operator and the user proves the `--commission` flag.

```shell
simd tx distribution withdraw-rewards [validator-addr] [flags]
```

Example:

```shell
simd tx distribution withdraw-rewards cosmosvaloper1... --from cosmos1... --commission
```

### gRPC

A user can query the `distribution` module using gRPC endpoints.

#### Params

The `Params` endpoint allows users to query parameters of the `distribution` module.

Example:

```shell
grpcurl -plaintext \
    localhost:9090 \
    cosmos.distribution.v1beta1.Query/Params
```

Example Output:

```json
{
  "params": {
    "communityTax": "20000000000000000",
    "baseProposerReward": "00000000000000000",
    "bonusProposerReward": "00000000000000000",
    "withdrawAddrEnabled": true
  }
}
```

#### ValidatorDistributionInfo

The `ValidatorDistributionInfo` queries validator commission and self-delegation rewards for validator.

Example:

```shell
grpcurl -plaintext \
    -d '{"validator_address":"cosmosvalop1..."}' \
    localhost:9090 \
    cosmos.distribution.v1beta1.Query/ValidatorDistributionInfo
```

Example Output:

```json
{
  "commission": {
    "commission": [
      {
        "denom": "stake",
        "amount": "1000000000000000"
      }
    ]
  },
  "self_bond_rewards": [
    {
      "denom": "stake",
      "amount": "1000000000000000"
    }
  ],
  "validator_address": "cosmosvalop1..."
}
```

#### ValidatorOutstandingRewards

The `ValidatorOutstandingRewards` endpoint allows users to query rewards of a validator address.

Example:

```shell
grpcurl -plaintext \
    -d '{"validator_address":"cosmosvalop1.."}' \
    localhost:9090 \
    cosmos.distribution.v1beta1.Query/ValidatorOutstandingRewards
```

Example Output:

```json
{
  "rewards": {
    "rewards": [
      {
        "denom": "stake",
        "amount": "1000000000000000"
      }
    ]
  }
}
```

#### ValidatorCommission

The `ValidatorCommission` endpoint allows users to query accumulated commission for a validator.

Example:

```shell
grpcurl -plaintext \
    -d '{"validator_address":"cosmosvalop1.."}' \
    localhost:9090 \
    cosmos.distribution.v1beta1.Query/ValidatorCommission
```

Example Output:

```json
{
  "commission": {
    "commission": [
      {
        "denom": "stake",
        "amount": "1000000000000000"
      }
    ]
  }
}
```

#### ValidatorSlashes

The `ValidatorSlashes` endpoint allows users to query slash events of a validator.

Example:

```shell
grpcurl -plaintext \
    -d '{"validator_address":"cosmosvalop1.."}' \
    localhost:9090 \
    cosmos.distribution.v1beta1.Query/ValidatorSlashes
```

Example Output:

```json
{
  "slashes": [
    {
      "validator_period": "20",
      "fraction": "0.009999999999999999"
    }
  ],
  "pagination": {
    "total": "1"
  }
}
```

#### DelegationRewards

The `DelegationRewards` endpoint allows users to query the total rewards accrued by a delegation.

Example:

```shell
grpcurl -plaintext \
    -d '{"delegator_address":"cosmos1...","validator_address":"cosmosvalop1..."}' \
    localhost:9090 \
    cosmos.distribution.v1beta1.Query/DelegationRewards
```

Example Output:

```json
{
  "rewards": [
    {
      "denom": "stake",
      "amount": "1000000000000000"
    }
  ]
}
```

#### DelegationTotalRewards

The `DelegationTotalRewards` endpoint allows users to query the total rewards accrued by each validator.

Example:

```shell
grpcurl -plaintext \
    -d '{"delegator_address":"cosmos1..."}' \
    localhost:9090 \
    cosmos.distribution.v1beta1.Query/DelegationTotalRewards
```

Example Output:

```json
{
  "rewards": [
    {
      "validatorAddress": "cosmosvaloper1...",
      "reward": [
        {
          "denom": "stake",
          "amount": "1000000000000000"
        }
      ]
    }
  ],
  "total": [
    {
      "denom": "stake",
      "amount": "1000000000000000"
    }
  ]
}
```

#### DelegatorValidators

The `DelegatorValidators` endpoint allows users to query all validators for given delegator.

Example:

```shell
grpcurl -plaintext \
    -d '{"delegator_address":"cosmos1..."}' \
    localhost:9090 \
    cosmos.distribution.v1beta1.Query/DelegatorValidators
```

Example Output:

```json
{
  "validators": ["cosmosvaloper1..."]
}
```

#### DelegatorWithdrawAddress

The `DelegatorWithdrawAddress` endpoint allows users to query the withdraw address of a delegator.

Example:

```shell
grpcurl -plaintext \
    -d '{"delegator_address":"cosmos1..."}' \
    localhost:9090 \
    cosmos.distribution.v1beta1.Query/DelegatorWithdrawAddress
```

Example Output:

```json
{
  "withdrawAddress": "cosmos1..."
}
```

#### CommunityPool

The `CommunityPool` endpoint allows users to query the community pool coins.

Example:

```shell
grpcurl -plaintext \
    localhost:9090 \
    cosmos.distribution.v1beta1.Query/CommunityPool
```

Example Output:

```json
{
  "pool": [
    {
      "denom": "stake",
      "amount": "1000000000000000000"
    }
  ]
}
```

Previous危机(Crisis)Next证据(Evidence)

Last updated 1 month ago

摘要

不足之处

对质押的影响

目录

概念

F1 费用分发中的引用计数

状态

FeePool

验证者分发

委托分发

参数

Begin Block

分发方案

奖励到社区池

奖励到验证者

奖励到委托人

示例分发

消息

MsgSetWithdrawAddress

MsgWithdrawDelegatorReward

WithdrawValidatorCommission

FundCommunityPool

常见的分发操作

Initialize delegation

MsgUpdateParams

钩子(Hooks)

创建或修改 delegation 分配。

之前

之后

验证者创建。

验证者移除

验证者被惩罚

事件

BeginBlocker

Handlers

MsgSetWithdrawAddress

MsgWithdrawDelegatorReward

MsgWithdrawValidatorCommission

Parameters

客户端

CLI

Query

摘要

不足之处

对质押的影响

目录

概念

F1 费用分发中的引用计数

状态

FeePool

验证者分发

委托分发

参数

Begin Block

分发方案

奖励到社区池

奖励到验证者

奖励到委托人

示例分发

消息

MsgSetWithdrawAddress

MsgWithdrawDelegatorReward

WithdrawValidatorCommission

FundCommunityPool

常见的分发操作

Initialize delegation

MsgUpdateParams

钩子(Hooks)

创建或修改 delegation 分配。

之前

之后

验证者创建。

验证者移除

验证者被惩罚

事件

BeginBlocker

Handlers

MsgSetWithdrawAddress

MsgWithdrawDelegatorReward

MsgWithdrawValidatorCommission

创建或修改 `delegation` 分配。

创建或修改 `delegation` 分配。