diff --git a/docs/spec/distribution/overview.md b/docs/spec/distribution/overview.md index 62cec2e76..7b912f282 100644 --- a/docs/spec/distribution/overview.md +++ b/docs/spec/distribution/overview.md @@ -4,23 +4,23 @@ This _simple_ distribution mechanism describes a functional way to passively distribute rewards between validator and delegators. Note that this mechanism does -not distribute funds in as precisely as active reward distribution and will therefor +not distribute funds in as precisely as active reward distribution and will therefore be upgraded in the future. The mechanism operates as follows. Collected rewards are pooled globally and divided out passively to validators and delegators. Each validator has the opportunity to charge commission to the delegators on the rewards collected on -behalf of the delegators by the validators. Fees are paid directly into a +behalf of the delegators by the validators. Fees are paid directly into a global reward pool, and validator proposer-reward pool. Due to the nature of -passive accounting whenever changes to parameters which affect the rate of reward -distribution occurs, withdrawal of rewards must also occur when: - - - withdrawing one must withdrawal the maximum amount they are entitled - too, leaving nothing in the pool, - - bonding, unbonding, or re-delegating tokens to an existing account a +passive accounting, whenever changes to parameters which affect the rate of reward +distribution occurs, withdrawal of rewards must also occur. + + - Whenever withdrawing, one must withdraw the maximum amount they are entitled + too, leaving nothing in the pool. + - Whenever bonding, unbonding, or re-delegating tokens to an existing account, a full withdrawal of the rewards must occur (as the rules for lazy accounting - change), - - a validator chooses to change the commission on rewards, all accumulated + change). + - Whenever a validator chooses to change the commission on rewards, all accumulated commission rewards must be simultaneously withdrawn. The above scenarios are covered in `triggers.md`. @@ -33,10 +33,8 @@ following rewards between validators and associated delegators: - validator commission on all rewards earned by their delegators stake Fees are pooled within a global pool, as well as validator specific -proposer-reward pools. The mechanisms used allow for validators and delegators -to independently and lazily withdrawn their rewards. - -Within this spec +proposer-reward pools. The mechanisms used allow for validators and delegators +to independently and lazily withdraw their rewards. As a part of the lazy computations, each validator and delegator holds an accumulation term which is used to estimate what their approximate fair portion @@ -47,18 +45,16 @@ is not the case, the approximation of owed rewards will deviate from the active distribution based on fluctuations of incoming reward tokens as well as timing of reward withdrawal by other delegators and validators from the reward pool. - ## Affect on Staking Charging commission on Atom provisions while also allowing for Atom-provisions to be auto-bonded (distributed directly to the validators bonded stake) is -problematic within DPoS. Fundamentally these two mechnisms are mutually -exclusive. If there are atoms commissions and auto-bonding Atoms, the portion +problematic within DPoS. Fundamentally these two mechnisms are mutually +exclusive. If there are Atom commissions and auto-bonding Atoms, the portion of Atoms the reward distribution calculation would become very large as the Atom portion for each delegator would change each block making a withdrawal of rewards for a delegator require a calculation for every single block since the last -withdrawal. In conclusion we can only have atom commission and unbonded atoms -provisions, or bonded atom provisions with no Atom commission, and we elect to +withdrawal. In conclusion, we can only have Atom commission and unbonded atoms +provisions or bonded atom provisions with no Atom commission, and we elect to implement the former. Stakeholders wishing to rebond their provisions may elect to set up a script to periodically withdraw and rebond rewards. - diff --git a/docs/spec/distribution/state.md b/docs/spec/distribution/state.md index 83e82f494..7dc011e95 100644 --- a/docs/spec/distribution/state.md +++ b/docs/spec/distribution/state.md @@ -33,7 +33,7 @@ type Global struct { ### Validator Distribution Validator distribution information for the relevant validator is updated each time: - 1. delegation amount to a validator are updated, + 1. delegation amount to a validator is 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. diff --git a/docs/spec/distribution/transactions.md b/docs/spec/distribution/transactions.md index 364346ff4..82f9e84f7 100644 --- a/docs/spec/distribution/transactions.md +++ b/docs/spec/distribution/transactions.md @@ -53,7 +53,7 @@ func GetDelegatorAllWithdraws(delegatorAddr sdk.AccAddress, height int64) DecCoi ## TxWithdrawValidator When a validator wishes to withdraw their rewards it must send -`TxWithdrawDelegation`. Note that parts of this transaction logic is also +`TxWithdrawValidatorRewards`. Note that parts of this transaction logic are also triggered each with any change in individual delegations, such as an unbond, redelegation, or delegation of additional tokens to a specific validator. This transaction withdraws the validators commission fee, as well as any rewards @@ -61,7 +61,7 @@ earning on their self-delegation. ``` type TxWithdrawValidatorRewards struct { - operatorAddr sdk.AccAddress // validator address to withdraw from + operatorAddr sdk.AccAddress // validator address to withdraw from withdrawAddr sdk.AccAddress // address to make the withdrawal to } @@ -92,7 +92,7 @@ func WithdrawValidatorRewards(operatorAddr, withdrawAddr sdk.AccAddress) The total amount of validator accum must be calculated in order to determine the amount of pool tokens which a validator is entitled to at a particular block. The accum is always additive to the existing accum. This term is to be -updates each time rewards are withdrawn from the system. +updated each time rewards are withdrawn from the system. ``` func (g Global) UpdateTotalValAccum(height int64, totalBondedTokens Dec) @@ -118,8 +118,8 @@ func (vi ValidatorDistInfo) UpdateTotalDelAccum(height int64, totalDelShares Dec ### Global pool to validator pool -Every time a validator or delegator make a withdraw or the validator is the -proposer and receives new tokens - the relevant validator must move tokens from +Every time a validator or delegator executes a withdrawal or the validator is the +proposer and receives new tokens, the relevant validator must move tokens from the passive global pool to their own pool. ``` @@ -141,7 +141,7 @@ func (vi ValidatorDistInfo) TakeAccum(g Global, height int64, totalBonded, vdTok ``` -### Delegation's withdrawal +### Delegation reward withdrawal For delegations (including validator's self-delegation) all rewards from reward pool are subject to commission rate from the operator of the validator. @@ -166,7 +166,7 @@ func (di DelegatorDistInfo) WithdrawRewards(g Global, vi ValidatorDistInfo, ``` -### Validators's commission withdrawal +### Validator commission withdrawal Similar to a delegator's entitlement, but with recipient shares based on the commission portion of bonded tokens. diff --git a/docs/spec/distribution/triggers.md b/docs/spec/distribution/triggers.md index 2938e674f..e3971ea99 100644 --- a/docs/spec/distribution/triggers.md +++ b/docs/spec/distribution/triggers.md @@ -22,5 +22,5 @@ Additionally the change and associated height must be recorded in a - triggered-by: `stake.Slash`, `stake.UpdateValidator` Whenever a validator is slashed or enters/leaves the validator group all of the -validator entitled reward tokens must be simultaniously withdrawn from -`Global.Pool` and added to `ValidatorDistInfo.Pool` +validator entitled reward tokens must be simultaneously withdrawn from +`Global.Pool` and added to `ValidatorDistInfo.Pool`.