diff --git a/docs/spec/distribution/end_block.md b/docs/spec/distribution/end_block.md index bc6847ef4b..19c9e83021 100644 --- a/docs/spec/distribution/end_block.md +++ b/docs/spec/distribution/end_block.md @@ -3,10 +3,10 @@ At each endblock, the fees received are sorted to the proposer, community fund, and global pool. When the validator is the proposer of the round, that validator (and their delegators) receives between 1% and 5% of fee rewards, the -reserve tax is then charged, then the remainder is distributed proportionally -by voting power to all bonded validators independent of whether they voted -(social distribution). Note the social distribution is applied to proposer -validator in addition to the proposer reward. +reserve community tax is then charged, then the remainder is distributed +proportionally by voting power to all bonded validators independent of whether +they voted (social distribution). Note the social distribution is applied to +proposer validator in addition to the proposer reward. The amount of proposer reward is calculated from pre-commits Tendermint messages in order to incentivize validators to wait and include additional diff --git a/docs/spec/distribution/future_improvements.md b/docs/spec/distribution/future_improvements.md deleted file mode 100644 index 954fb4d623..0000000000 --- a/docs/spec/distribution/future_improvements.md +++ /dev/null @@ -1,16 +0,0 @@ -## Future Improvements - -### Power Change - -Within the current implementation all power changes ever made are indefinitely stored -within the current state. In the future this state should be trimmed on an epoch basis. Delegators -which will have not withdrawn their fees will be penalized in some way, depending on what is -computationally feasible this may include: - - burning non-withdrawn fees - - requiring more expensive withdrawal costs which include proofs from archive nodes of historical state - -In addition or as an alternative it may make sense to implement a "rolling" epoch which cycles through -all the delegators in small groups (for example 5 delegators per block) and just runs the withdrawal transaction -at standard rates and takes transaction fees from the withdrawal amount. - - diff --git a/docs/spec/distribution/transactions.md b/docs/spec/distribution/transactions.md index 1401c3b851..7816757e53 100644 --- a/docs/spec/distribution/transactions.md +++ b/docs/spec/distribution/transactions.md @@ -131,17 +131,12 @@ fulfilled the entitled fees for the various scenarios can be calculated. ```golang type DistributionScenario interface { - DistributorTokens() DecCoins // current tokens from distributor - DistributorCumulativeTokens() DecCoins // total tokens ever received - DistributorPrevReceivedTokens() DecCoins // last value of tokens received - DistributorShares() sdk.Dec // current shares - DistributorPrevShares() sdk.Dec // shares last block + DistributorTokens() DecCoins // current tokens from distributor + DistributorShares() sdk.Dec // current shares + RecipientAccum() sdk.Dec + RecipientShares() sdk.Dec // current shares - RecipientAdjustment() sdk.Dec - RecipientShares() sdk.Dec // current shares - RecipientPrevShares() sdk.Dec // shares last block - - ModifyAdjustments(withdrawal sdk.Dec) // proceedure to modify adjustment factors + ModifyAccums(withdrawal sdk.Dec) // proceedure to modify adjustment factors } ``` @@ -169,18 +164,9 @@ func (d DistributionScenario) RecipientCount(height int64) sdk.Dec func (d DistributionScenario) GlobalCount(height int64) sdk.Dec return d.DistributorShares() * height -func (d DistributionScenario) SimplePool() DecCoins - return d.RecipientCount() / d.GlobalCount() * d.DistributorCumulativeTokens - -func (d DistributionScenario) ProjectedPool(height int64) DecCoins - return d.RecipientPrevShares() * (height-1) - / (d.DistributorPrevShares() * (height-1)) - * d.DistributorCumulativeTokens - + d.RecipientShares() / d.DistributorShares() - * d.DistributorPrevReceivedTokens() ``` -The `DistributionScenario` _adjustment_ terms account for changes in +The `DistributionScenario` _accum_ terms account for changes in recipient/distributor shares and recipient withdrawals. The adjustment factor must be modified whenever the recipient withdraws from the distributor or the distributor's/recipient's shares are changed. @@ -218,49 +204,6 @@ shares should be taken as true number of global bonded shares. The recipients shares should be taken as the bonded tokens less the validator's commission. ``` -type DelegationFromGlobalPool struct { - DelegationShares sdk.Dec - ValidatorCommission sdk.Dec - ValidatorBondedTokens sdk.Dec - ValidatorDelegatorShareExRate sdk.Dec - PoolBondedTokens sdk.Dec - Global Global - ValDistr ValidatorDistribution - DelDistr DelegatorDistribution -} - -func (d DelegationFromGlobalPool) DistributorTokens() DecCoins - return d.Global.Pool - -func (d DelegationFromGlobalPool) DistributorCumulativeTokens() DecCoins - return d.Global.EverReceivedPool - -func (d DelegationFromGlobalPool) DistributorPrevReceivedTokens() DecCoins - return d.Global.PrevReceivedPool - -func (d DelegationFromGlobalPool) DistributorShares() sdk.Dec - return d.PoolBondedTokens - -func (d DelegationFromGlobalPool) DistributorPrevShares() sdk.Dec - return d.Global.PrevBondedTokens - -func (d DelegationFromGlobalPool) RecipientShares() sdk.Dec - return d.DelegationShares * d.ValidatorDelegatorShareExRate() * - d.ValidatorBondedTokens() * (1 - d.ValidatorCommission) - -func (d DelegationFromGlobalPool) RecipientPrevShares() sdk.Dec - return d.DelDistr.PrevTokens - -func (d DelegationFromGlobalPool) RecipientAdjustment() sdk.Dec - return d.DelDistr.Adjustment - -func (d DelegationFromGlobalPool) ModifyAdjustments(withdrawal sdk.Dec) - d.ValDistr.Adjustment += withdrawal - d.DelDistr.Adjustment += withdrawal - d.global.Adjustment += withdrawal - SetValidatorDistribution(d.ValDistr) - SetDelegatorDistribution(d.DelDistr) - SetGlobal(d.Global) ``` #### Delegation's entitlement to ValidatorDistribution.ProposerPool @@ -272,43 +215,6 @@ shares is taken as the effective delegation shares less the validator's commission. ``` -type DelegationFromProposerPool struct { - DelegationShares sdk.Dec - ValidatorCommission sdk.Dec - ValidatorDelegatorShares sdk.Dec - ValDistr ValidatorDistribution - DelDistr DelegatorDistribution -} - -func (d DelegationFromProposerPool) DistributorTokens() DecCoins - return d.ValDistr.ProposerPool - -func (d DelegationFromProposerPool) DistributorCumulativeTokens() DecCoins - return d.ValDistr.EverReceivedProposerReward - -func (d DelegationFromProposerPool) DistributorPrevReceivedTokens() DecCoins - return d.ValDistr.PrevReceivedProposerReward - -func (d DelegationFromProposerPool) DistributorShares() sdk.Dec - return d.ValidatorDelegatorShares - -func (d DelegationFromProposerPool) DistributorPrevShares() sdk.Dec - return d.ValDistr.PrevDelegatorShares - -func (d DelegationFromProposerPool) RecipientShares() sdk.Dec - return d.DelegationShares * (1 - d.ValidatorCommission) - -func (d DelegationFromProposerPool) RecipientPrevShares() sdk.Dec - return d.DelDistr.PrevShares - -func (d DelegationFromProposerPool) RecipientAdjustment() sdk.Dec - return d.DelDistr.AdjustmentProposer - -func (d DelegationFromProposerPool) ModifyAdjustments(withdrawal sdk.Dec) - d.ValDistr.AdjustmentProposer += withdrawal - d.DelDistr.AdjustmentProposer += withdrawal - SetValidatorDistribution(d.ValDistr) - SetDelegatorDistribution(d.DelDistr) ``` #### Validators's commission entitlement to Global.Pool @@ -317,43 +223,6 @@ Similar to a delegator's entitlement, but with recipient shares based on the commission portion of bonded tokens. ``` -type CommissionFromGlobalPool struct { - ValidatorBondedTokens sdk.Dec - ValidatorCommission sdk.Dec - PoolBondedTokens sdk.Dec - Global Global - ValDistr ValidatorDistribution -} - -func (c CommissionFromGlobalPool) DistributorTokens() DecCoins - return c.Global.Pool - -func (c CommissionFromGlobalPool) DistributorCumulativeTokens() DecCoins - return c.Global.EverReceivedPool - -func (c CommissionFromGlobalPool) DistributorPrevReceivedTokens() DecCoins - return c.Global.PrevReceivedPool - -func (c CommissionFromGlobalPool) DistributorShares() sdk.Dec - return c.PoolBondedTokens - -func (c CommissionFromGlobalPool) DistributorPrevShares() sdk.Dec - return c.Global.PrevBondedTokens - -func (c CommissionFromGlobalPool) RecipientShares() sdk.Dec - return c.ValidatorBondedTokens() * c.ValidatorCommission - -func (c CommissionFromGlobalPool) RecipientPrevShares() sdk.Dec - return c.ValDistr.PrevBondedTokens * c.ValidatorCommission - -func (c CommissionFromGlobalPool) RecipientAdjustment() sdk.Dec - return c.ValDistr.Adjustment - -func (c CommissionFromGlobalPool) ModifyAdjustments(withdrawal sdk.Dec) - c.ValDistr.Adjustment += withdrawal - c.Global.Adjustment += withdrawal - SetValidatorDistribution(c.ValDistr) - SetGlobal(c.Global) ``` #### Validators's commission entitlement to ValidatorDistribution.ProposerPool @@ -362,38 +231,5 @@ Similar to a delegators entitlement to the proposer pool, but with recipient shares based on the commission portion of the total delegator shares. ``` -type CommissionFromProposerPool struct { - ValidatorDelegatorShares sdk.Dec - ValidatorCommission sdk.Dec - ValDistr ValidatorDistribution -} - -func (c CommissionFromProposerPool) DistributorTokens() DecCoins - return c.ValDistr.ProposerPool - -func (c CommissionFromProposerPool) DistributorCumulativeTokens() DecCoins - return c.ValDistr.EverReceivedProposerReward - -func (c CommissionFromProposerPool) DistributorPrevReceivedTokens() DecCoins - return c.ValDistr.PrevReceivedProposerReward - -func (c CommissionFromProposerPool) DistributorShares() sdk.Dec - return c.ValidatorDelegatorShares - -func (c CommissionFromProposerPool) DistributorPrevShares() sdk.Dec - return c.ValDistr.PrevDelegatorShares - -func (c CommissionFromProposerPool) RecipientShares() sdk.Dec - return c.ValidatorDelegatorShares * (c.ValidatorCommission) - -func (c CommissionFromProposerPool) RecipientPrevShares() sdk.Dec - return c.ValDistr.PrevDelegatorShares * (c.ValidatorCommission) - -func (c CommissionFromProposerPool) RecipientAdjustment() sdk.Dec - return c.ValDistr.AdjustmentProposer - -func (c CommissionFromProposerPool) ModifyAdjustments(withdrawal sdk.Dec) - c.ValDistr.AdjustmentProposer += withdrawal - SetValidatorDistribution(c.ValDistr) ``` diff --git a/docs/spec/distribution/triggers.md b/docs/spec/distribution/triggers.md index 8800609a44..93358fe2e7 100644 --- a/docs/spec/distribution/triggers.md +++ b/docs/spec/distribution/triggers.md @@ -1,26 +1,14 @@ # Triggers -## Create validator distribution - - - triggered-by: validator entering bonded validator group (`stake.bondValidator()`) - -Whenever a new validator is added to the Tendermint validator set they are -entitled to begin earning rewards of atom provisions and fees. At this point -`ValidatorDistribution.Pool()` must be zero (as the validator has not yet -earned any rewards) meaning that the initial value for `validator.Adjustment` -must be set to the value of `validator.SimplePool()` for the height which the -validator is added on the validator set. - ## Create or modify delegation distribution - triggered-by: `stake.TxDelegate`, `stake.TxBeginRedelegate`, `stake.TxBeginUnbonding` The pool of a new delegator bond will be 0 for the height at which the bond was -added. This is achieved by setting `DelegationDistribution.WithdrawalHeight` to -the height which the bond was added. Additionally the `AdjustmentPool` and -`AdjustmentProposerPool` must be set to the equivalent values of -`DelegationDistribution.SimplePool()` and -`DelegationDistribution.SimpleProposerPool()` for the height of delegation. +added, or the withdrawal has taken place. This is achieved by setting +`DelegatorDist.WithdrawalHeight` to the relevant height, withdrawing any +remaining fees, and setting `DelegatorDist.Accum` and +`DelegatorDist.ProposerAccum` to 0. ## Commission rate change @@ -29,3 +17,10 @@ the height which the bond was added. Additionally the `AdjustmentPool` and If a validator changes its commission rate, all commission on fees must be simultaneously withdrawn using the transaction `TxWithdrawValidator` +## Change in Validator State + + - triggered-by: `stake.Slash`, `stake.UpdateValidator` + +Whenever a validator is slashed or enters/leaves the validator group +`ValidatorUpdate` information must be recorded in order to properly calculate +the accum factors.