cosmos-sdk/docs/spec/distribution/state.md

State

Global

All globally tracked parameters for distribution are stored within Global. Rewards are collected and added to the reward pool and distributed to validators/delegators from here.

Note that the reward pool holds decimal coins (DecCoins) to allow for fractions of coins to be received from operations like inflation. When coins are distributed from the pool they are truncated back to sdk.Coins which are non-decimal.

• Global: 0x00 -> amino(global)

// coins with decimal 
type DecCoins []DecCoin

type DecCoin struct {
    Amount sdk.Dec
    Denom  string
}

type Global struct {
    TotalValAccumUpdateHeight  int64    // last height which the total validator accum was updated
    TotalValAccum              sdk.Dec  // total valdator accum held by validators
    Pool                       DecCoins // funds for all validators which have yet to be withdrawn
    CommunityPool              DecCoins // pool for community funds yet to be spent
}

Validator Distribution

Validator distribution information for the relevant validator is updated each time:

1. delegation amount to a validator are updated,
2. a validator successfully proposes a block and receives a reward,
3. any delegator withdraws from a validator, or
4. the validator withdraws it's commission.

• ValidatorDistribution: 0x02 | ValOwnerAddr -> amino(validatorDistribution)

type ValidatorDistribution struct {
    CommissionWithdrawalHeight int64    // last height this validator withdrew commission

    GlobalWithdrawalHeight     int64    // last height this validator withdrew from the global pool
    Pool                       DecCoins // reward pool collected held within this validator (includes proposer rewards)

    TotalDelAccumUpdateHeight  int64    // last height which the total delegator accum was updated
    TotalDelAccum              sdk.Dec  // total proposer pool accumulation factor held by delegators
}

Delegation Distribution

Each delegation distribution only needs to record the height at which it last withdrew fees. Because a delegation must withdraw fees each time it's properties change (aka bonded tokens etc.) its properties will remain constant and the delegator's accumulation factor can be calculated passively knowing only the height of the last withdrawal and its current properties.

• DelegatorDistribution: 0x02 | DelegatorAddr | ValOwnerAddr -> amino(delegatorDist)

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

Validator Update

Every instance that a validator:

• enters into the bonded state,
• leaves the bonded state,
• is slashed, or
• changes its commission rate,

information about the state change must be recorded as a ValidatorUpdate. Each power change is indexed by validator and its block height.

• ValidatorUpdate: 0x03 | ValOwnerAddr | amino(Height) -> amino(ValidatorUpdate)

type ValidatorUpdate struct {
    Height                        int64     // block height of update
    NewCommissionRate             sdk.Dec   // commission rate at this height
}