github.com/Finschia/finschia-sdk@v0.48.1/x/distribution/spec/README.md (about)

     1  <!--
     2  order: 0
     3  title: Distribution Overview
     4  parent:
     5    title: "distribution"
     6  -->
     7  
     8  # `distribution`
     9  
    10  ## Overview
    11  
    12  This _simple_ distribution mechanism describes a functional way to passively
    13  distribute rewards between validators and delegators. Note that this mechanism does
    14  not distribute funds in as precisely as active reward distribution mechanisms and
    15  will therefore be upgraded in the future.
    16  
    17  The mechanism operates as follows. Collected rewards are pooled globally and
    18  divided out passively to validators and delegators. Each validator has the
    19  opportunity to charge commission to the delegators on the rewards collected on
    20  behalf of the delegators. Fees are collected directly into a global reward pool
    21  and validator proposer-reward pool. Due to the nature of passive accounting,
    22  whenever changes to parameters which affect the rate of reward distribution
    23  occurs, withdrawal of rewards must also occur.
    24  
    25  - Whenever withdrawing, one must withdraw the maximum amount they are entitled
    26     to, leaving nothing in the pool.
    27  - Whenever bonding, unbonding, or re-delegating tokens to an existing account, a
    28     full withdrawal of the rewards must occur (as the rules for lazy accounting
    29     change).
    30  - Whenever a validator chooses to change the commission on rewards, all accumulated
    31     commission rewards must be simultaneously withdrawn.
    32  
    33  The above scenarios are covered in `hooks.md`.
    34  
    35  The distribution mechanism outlined herein is used to lazily distribute the
    36  following rewards between validators and associated delegators:
    37  
    38  - multi-token fees to be socially distributed
    39  - proposer reward pool
    40  - inflated atom provisions
    41  - validator commission on all rewards earned by their delegators stake
    42  
    43  Fees are pooled within a global pool, as well as validator specific
    44  proposer-reward pools. The mechanisms used allow for validators and delegators
    45  to independently and lazily withdraw their rewards.
    46  
    47  ## Shortcomings
    48  
    49  As a part of the lazy computations, each delegator holds an accumulation term
    50  specific to each validator which is used to estimate what their approximate
    51  fair portion of tokens held in the global fee pool is owed to them.
    52  
    53  ```
    54  entitlement = delegator-accumulation / all-delegators-accumulation
    55  ```
    56  
    57  Under the circumstance that there was constant and equal flow of incoming
    58  reward tokens every block, this distribution mechanism would be equal to the
    59  active distribution (distribute individually to all delegators each block).
    60  However, this is unrealistic so deviations from the active distribution will
    61  occur based on fluctuations of incoming reward tokens as well as timing of
    62  reward withdrawal by other delegators.
    63  
    64  If you happen to know that incoming rewards are about to significantly increase,
    65  you are incentivized to not withdraw until after this event, increasing the
    66  worth of your existing _accum_. See [#2764](https://github.com/cosmos/cosmos-sdk/issues/2764)
    67  for further details.
    68  
    69  ## Effect on Staking
    70  
    71  Charging commission on Atom provisions while also allowing for Atom-provisions
    72  to be auto-bonded (distributed directly to the validators bonded stake) is
    73  problematic within BPoS. Fundamentally, these two mechanisms are mutually
    74  exclusive. If both commission and auto-bonding mechanisms are simultaneously
    75  applied to the staking-token then the distribution of staking-tokens between
    76  any validator and its delegators will change with each block. This then
    77  necessitates a calculation for each delegation records for each block -
    78  which is considered computationally expensive.
    79  
    80  In conclusion, we can only have Atom commission and unbonded atoms
    81  provisions or bonded atom provisions with no Atom commission, and we elect to
    82  implement the former. Stakeholders wishing to rebond their provisions may elect
    83  to set up a script to periodically withdraw and rebond rewards.
    84  
    85  ## Contents
    86  
    87  1. **[Concepts](01_concepts.md)**
    88      - [Reference Counting in F1 Fee Distribution](01_concepts.md#reference-counting-in-f1-fee-distribution)
    89  2. **[State](02_state.md)**
    90  3. **[Begin Block](03_begin_block.md)**
    91  4. **[Messages](04_messages.md)**
    92      - [MsgSetWithdrawAddress](04_messages.md#msgsetwithdrawaddress)
    93      - [MsgWithdrawDelegatorReward](04_messages.md#msgwithdrawdelegatorreward)
    94          - [Withdraw Validator Rewards All](04_messages.md#withdraw-validator-rewards-all)
    95      - [Common calculations](04_messages.md#common-calculations-)
    96  5. **[Hooks](05_hooks.md)**
    97      - [Create or modify delegation distribution](05_hooks.md#create-or-modify-delegation-distribution)
    98      - [Commission rate change](05_hooks.md#commission-rate-change)
    99      - [Change in Validator State](05_hooks.md#change-in-validator-state)
   100  6. **[Events](06_events.md)**
   101      - [BeginBlocker](06_events.md#beginblocker)
   102      - [Handlers](06_events.md#handlers)
   103  7. **[Parameters](07_params.md)**