From 97397e63da63e6effaeb4542187e8fb3ef022b0b Mon Sep 17 00:00:00 2001 From: rigelrozanski Date: Wed, 8 Aug 2018 13:09:51 -0400 Subject: [PATCH 01/18] simple distribution overview --- docs/spec/simple-distribution/end_block.md | 36 ++ .../future_improvements.md | 16 + docs/spec/simple-distribution/overview.md | 64 +++ docs/spec/simple-distribution/state.md | 100 +++++ docs/spec/simple-distribution/transactions.md | 399 ++++++++++++++++++ docs/spec/simple-distribution/triggers.md | 31 ++ 6 files changed, 646 insertions(+) create mode 100644 docs/spec/simple-distribution/end_block.md create mode 100644 docs/spec/simple-distribution/future_improvements.md create mode 100644 docs/spec/simple-distribution/overview.md create mode 100644 docs/spec/simple-distribution/state.md create mode 100644 docs/spec/simple-distribution/transactions.md create mode 100644 docs/spec/simple-distribution/triggers.md diff --git a/docs/spec/simple-distribution/end_block.md b/docs/spec/simple-distribution/end_block.md new file mode 100644 index 000000000..bc6847ef4 --- /dev/null +++ b/docs/spec/simple-distribution/end_block.md @@ -0,0 +1,36 @@ +# End Block + +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. + +The amount of proposer reward is calculated from pre-commits Tendermint +messages in order to incentivize validators to wait and include additional +pre-commits in the block. All provision rewards are added to a provision reward +pool which validator holds individually +(`ValidatorDistribution.ProvisionsRewardPool`). + +``` +func SortFees(feesCollected sdk.Coins, global Global, proposer ValidatorDistribution, + sumPowerPrecommitValidators, totalBondedTokens, communityTax sdk.Dec) + + feesCollectedDec = MakeDecCoins(feesCollected) + proposerReward = feesCollectedDec * (0.01 + 0.04 + * sumPowerPrecommitValidators / totalBondedTokens) + proposer.ProposerPool += proposerReward + + communityFunding = feesCollectedDec * communityTax + global.CommunityFund += communityFunding + + poolReceived = feesCollectedDec - proposerReward - communityFunding + global.Pool += poolReceived + global.EverReceivedPool += poolReceived + global.LastReceivedPool = poolReceived + + SetValidatorDistribution(proposer) + SetGlobal(global) +``` diff --git a/docs/spec/simple-distribution/future_improvements.md b/docs/spec/simple-distribution/future_improvements.md new file mode 100644 index 000000000..954fb4d62 --- /dev/null +++ b/docs/spec/simple-distribution/future_improvements.md @@ -0,0 +1,16 @@ +## 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/simple-distribution/overview.md b/docs/spec/simple-distribution/overview.md new file mode 100644 index 000000000..62cec2e76 --- /dev/null +++ b/docs/spec/simple-distribution/overview.md @@ -0,0 +1,64 @@ +# Distribution + +## Overview + +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 +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 +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 + 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 + commission rewards must be simultaneously withdrawn. + +The above scenarios are covered in `triggers.md`. + +The distribution mechanism outlines herein is used to lazily distribute the +following rewards between validators and associated delegators: + - multi-token fees to be socially distributed, + - proposer reward pool, + - inflated atom provisions, and + - 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 + +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 +of tokens held in the global pool is owed to them. This approximation of owed +rewards would be equivalent to the active distribution under the situation that +there was a constant flow of incoming reward tokens every block. Because this +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 +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 +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/simple-distribution/state.md b/docs/spec/simple-distribution/state.md new file mode 100644 index 000000000..7865c085e --- /dev/null +++ b/docs/spec/simple-distribution/state.md @@ -0,0 +1,100 @@ +## 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)` + +```golang +// coins with decimal +type DecCoins []DecCoin + +type DecCoin struct { + Amount sdk.Dec + Denom string +} + +type Global struct { + PrevBondedTokens sdk.Dec // bonded token amount for the global pool on the previous block + Adjustment sdk.Dec // global adjustment factor for lazy calculations + Pool DecCoins // funds for all validators which have yet to be withdrawn + PrevReceivedPool DecCoins // funds added to the pool on the previous block + EverReceivedPool DecCoins // total funds ever added to the pool + CommunityFund 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)` + +```golang +type ValidatorDistribution struct { + CommissionWithdrawalHeight int64 // last time this validator withdrew commission + Adjustment sdk.Dec // global pool adjustment factor + ProposerAdjustment DecCoins // proposer pool adjustment factor + ProposerPool DecCoins // reward pool collected from being the proposer + EverReceivedProposerReward DecCoins // all rewards ever collected from being the proposer + PrevReceivedProposerReward DecCoins // previous rewards collected from being the proposer + PrevBondedTokens sdk.Dec // bonded token amount on the previous block + PrevDelegatorShares sdk.Dec // amount of delegator shares for the validator on the previous block +} +``` + +### Delegation Distribution + +Each delegation holds multiple adjustment factors to specify its entitlement to +the rewards from a validator. `AdjustmentPool` is used to passively calculate +each bonds entitled fees from the `RewardPool`. `AdjustmentPool` is used to +passively calculate each bonds entitled fees from +`ValidatorDistribution.ProposerRewardPool` + + - DelegatorDistribution: ` 0x02 | DelegatorAddr | ValOwnerAddr -> amino(delegatorDist)` + +```golang +type DelegatorDist struct { + WithdrawalHeight int64 // last time this delegation withdrew rewards + Adjustment sdk.Dec // fee provisioning adjustment factor + AdjustmentProposer DecCoins // proposers pool adjustment factor + PrevTokens sdk.Dec // bonded tokens held by the delegation on the previous block + PrevShares sdk.Dec // delegator shares held by the delegation on the previous block +} +``` + +### Power Change + +Every instance that the voting power changes, information about the state of +the validator set during the change must be recorded as a `PowerChange` for +other validators to run through. Each power change is indexed by its block +height. + + - PowerChange: `0x03 | amino(Height) -> amino(validatorDist)` + +```golang +type PowerChange struct { + Height int64 // block height at change + ValidatorBondedTokens sdk.Dec // following used to create distribution scenarios + ValidatorDelegatorShares sdk.Dec + ValidatorDelegatorShareExRate sdk.Dec + ValidatorCommission sdk.Dec + PoolBondedTokens sdk.Dec + Global Global + ValDistr ValidatorDistribution + DelegationShares sdk.Dec + DelDistr DelegatorDistribution +} +``` diff --git a/docs/spec/simple-distribution/transactions.md b/docs/spec/simple-distribution/transactions.md new file mode 100644 index 000000000..1401c3b85 --- /dev/null +++ b/docs/spec/simple-distribution/transactions.md @@ -0,0 +1,399 @@ +# Transactions + +## TxWithdrawDelegation + +When a delegator wishes to withdraw their transaction fees it must send +`TxWithdrawDelegation`. 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. + +Each time a withdrawal is made by a recipient the adjustment term must be +modified for each block with a change in distributors shares since the time of +last withdrawal. This is accomplished by iterating over all relevant +`PowerChange`'s stored in distribution state. + + +```golang +type TxWithdrawDelegation struct { + delegatorAddr sdk.AccAddress + withdrawAddr sdk.AccAddress // address to make the withdrawal to +} + +func WithdrawDelegator(delegatorAddr, withdrawAddr sdk.AccAddress) + entitlement = GetDelegatorEntitlement(delegatorAddr) + AddCoins(withdrawAddr, totalEntitlment.TruncateDecimal()) + +func GetDelegatorEntitlement(delegatorAddr sdk.AccAddress) DecCoins + + // compile all the distribution scenarios + delegations = GetDelegations(delegatorAddr) + DelDistr = GetDelegationDistribution(delegation.DelegatorAddr, + delegation.ValidatorAddr) + pcs = GetPowerChanges(DelDistr.WithdrawalHeight) + + // update all adjustment factors for each delegation since last withdrawal + for pc = range pcs + for delegation = range delegations + DelDistr = GetDelegationDistribution(delegation.DelegatorAddr, + delegation.ValidatorAddr) + pc.ProcessPowerChangeDelegation(delegation, DelDistr) + + // collect all entitled fees + entitlement = 0 + for delegation = range delegations + global = GetGlobal() + pool = GetPool() + DelDistr = GetDelegationDistribution(delegation.DelegatorAddr, + delegation.ValidatorAddr) + ValDistr = GetValidatorDistribution(delegation.ValidatorAddr) + validator = GetValidator(delegation.ValidatorAddr) + + scenerio1 = NewDelegationFromGlobalPool(delegation, validator, + pool, global, ValDistr, DelDistr) + scenerio2 = NewDelegationFromProvisionPool(delegation, validator, + ValDistr, DelDistr) + entitlement += scenerio1.WithdrawalEntitlement() + entitlement += scenerio2.WithdrawalEntitlement() + + return entitlement + +func (pc PowerChange) ProcessPowerChangeDelegation(delegation sdk.Delegation, + DelDistr DelegationDistribution) + + // get the historical scenarios + scenario1 = pc.DelegationFromGlobalPool(delegation, DelDistr) + scenario2 = pc.DelegationFromProvisionPool(delegation, DelDistr) + + // process the adjustment factors + scenario1.UpdateAdjustmentForPowerChange(pc.Height) + scenario2.UpdateAdjustmentForPowerChange(pc.Height) +``` + +## TxWithdrawValidator + +When a validator wishes to withdraw their transaction fees it must send +`TxWithdrawDelegation`. Note that parts of this transaction logic is 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 rewards, as well as any rewards +earning on their self-delegation. + +```golang +type TxWithdrawValidator struct { + ownerAddr sdk.AccAddress // validator address to withdraw from + withdrawAddr sdk.AccAddress // address to make the withdrawal to +} + +func WithdrawalValidator(ownerAddr, withdrawAddr sdk.AccAddress) + + // update the delegator adjustment factors and also withdrawal delegation fees + entitlement = GetDelegatorEntitlement(ownerAddr) + + // update the validator adjustment factors for commission + ValDistr = GetValidatorDistribution(ownerAddr.ValidatorAddr) + pcs = GetPowerChanges(ValDistr.CommissionWithdrawalHeight) + for pc = range pcs + pc.ProcessPowerChangeCommission() + + // withdrawal validator commission rewards + global = GetGlobal() + pool = GetPool() + ValDistr = GetValidatorDistribution(delegation.ValidatorAddr) + validator = GetValidator(delegation.ValidatorAddr) + + scenerio1 = NewCommissionFromGlobalPool(validator, + pool, global, ValDistr) + scenerio2 = CommissionFromProposerPool(validator, ValDistr) + entitlement += scenerio1.WithdrawalEntitlement() + entitlement += scenerio2.WithdrawalEntitlement() + + AddCoins(withdrawAddr, totalEntitlment.TruncateDecimal()) + +func (pc PowerChange) ProcessPowerChangeCommission() + + // get the historical scenarios + scenario1 = pc.CommissionFromGlobalPool() + scenario2 = pc.CommissionFromProposerPool() + + // process the adjustment factors + scenario1.UpdateAdjustmentForPowerChange(pc.Height) + scenario2.UpdateAdjustmentForPowerChange(pc.Height) +``` + +## Common Calculations + +### Distribution scenario + +A common form of abstracted calculations exists between validators and +delegations attempting to withdrawal their rewards, either from `Global.Pool` +or from `ValidatorDistribution.ProposerPool`. With the following interface +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 + + RecipientAdjustment() sdk.Dec + RecipientShares() sdk.Dec // current shares + RecipientPrevShares() sdk.Dec // shares last block + + ModifyAdjustments(withdrawal sdk.Dec) // proceedure to modify adjustment factors +} +``` + +#### Entitled reward from distribution scenario + +The entitlement to the distributor's tokens held can be accounted for lazily. +To begin this calculation we must determine the recipient's _simple pool_ and +_projected pool_. The simple pool represents a lazy accounting of what a +recipient's entitlement to the distributor's tokens would be if all recipients +for that distributor had static shares (equal to the current shares), and no +recipients had ever withdrawn their entitled rewards. The projected pool +represents the anticipated recipient's entitlement to the distributors tokens +based on the current blocks token input (for example fees reward received) to +the distributor, and the distributor's tokens and shares of the previous block +assuming that neither had changed in the current block. Using the simple and +projected pools we can determine all cumulative changes which have taken place +outside of the recipient and adjust the recipient's _adjustment factor_ to +account for these changes and ultimately keep track of the correct entitlement +to the distributors tokens. + +``` +func (d DistributionScenario) RecipientCount(height int64) sdk.Dec + return v.RecipientShares() * height + +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 +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. + - When the shares of the recipient is changed the adjustment factor is + increased/decreased by the difference between the _simple_ and _projected_ + pools. In other words, the cumulative difference in the shares if the shares + has been the new shares as opposed to the old shares for the entire duration of + the blockchain up the previous block. + - When a recipient makes a withdrawal the adjustment factor is increased by the + withdrawal amount. + +``` +func (d DistributionScenario) UpdateAdjustmentForPowerChange(height int64) + simplePool = d.SimplePool() + projectedPool = d.ProjectedPool(height) + AdjustmentChange = simplePool - projectedPool + if AdjustmentChange > 0 + d.ModifyAdjustments(AdjustmentChange) + +func (d DistributionScenario) WithdrawalEntitlement() DecCoins + entitlement = d.SimplePool() - d.RecipientAdjustment() + d.ModifyAdjustments(entitlement) + return entitlement +``` + +### Distribution scenarios + +Note that the distribution scenario structures are found in `state.md`. + +#### Delegation's entitlement to Global.Pool + +For delegations (including validator's self-delegation) all fees from fee pool +are subject to commission rate from the owner of the validator. The global +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 + +Delegations (including validator's self-delegation) are still subject +commission on the rewards gained from the proposer pool. Global shares in this +context is actually the validators total delegations shares. The recipient's +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 + +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 + +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/simple-distribution/triggers.md b/docs/spec/simple-distribution/triggers.md new file mode 100644 index 000000000..8800609a4 --- /dev/null +++ b/docs/spec/simple-distribution/triggers.md @@ -0,0 +1,31 @@ +# 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. + +## Commission rate change + + - triggered-by: `stake.TxEditValidator` + +If a validator changes its commission rate, all commission on fees must be +simultaneously withdrawn using the transaction `TxWithdrawValidator` + From eb6f51ed459ad49073f907199b118ca23e0acffc Mon Sep 17 00:00:00 2001 From: rigelrozanski Date: Wed, 8 Aug 2018 13:28:30 -0400 Subject: [PATCH 02/18] piggy bank state --- docs/spec/simple-distribution/state.md | 56 ++++++-------------------- 1 file changed, 12 insertions(+), 44 deletions(-) diff --git a/docs/spec/simple-distribution/state.md b/docs/spec/simple-distribution/state.md index 7865c085e..757287004 100644 --- a/docs/spec/simple-distribution/state.md +++ b/docs/spec/simple-distribution/state.md @@ -23,11 +23,8 @@ type DecCoin struct { } type Global struct { - PrevBondedTokens sdk.Dec // bonded token amount for the global pool on the previous block - Adjustment sdk.Dec // global adjustment factor for lazy calculations + Accum sdk.Dec // global accumulation factor for lazy calculations Pool DecCoins // funds for all validators which have yet to be withdrawn - PrevReceivedPool DecCoins // funds added to the pool on the previous block - EverReceivedPool DecCoins // total funds ever added to the pool CommunityFund DecCoins // pool for community funds yet to be spent } ``` @@ -44,57 +41,28 @@ Validator distribution information for the relevant validator is updated each ti ```golang type ValidatorDistribution struct { - CommissionWithdrawalHeight int64 // last time this validator withdrew commission - Adjustment sdk.Dec // global pool adjustment factor - ProposerAdjustment DecCoins // proposer pool adjustment factor - ProposerPool DecCoins // reward pool collected from being the proposer - EverReceivedProposerReward DecCoins // all rewards ever collected from being the proposer - PrevReceivedProposerReward DecCoins // previous rewards collected from being the proposer - PrevBondedTokens sdk.Dec // bonded token amount on the previous block - PrevDelegatorShares sdk.Dec // amount of delegator shares for the validator on the previous block + CommissionWithdrawalHeight int64 // last time this validator withdrew commission + Accum sdk.Dec // global pool accumulation factor + ProposerAccum sdk.Dec // proposer pool accumulation factor + ProposerPool DecCoins // reward pool collected from being the proposer } ``` ### Delegation Distribution -Each delegation holds multiple adjustment factors to specify its entitlement to -the rewards from a validator. `AdjustmentPool` is used to passively calculate -each bonds entitled fees from the `RewardPool`. `AdjustmentPool` is used to -passively calculate each bonds entitled fees from +Each delegation holds multiple accumulation factors to specify its entitlement to +the rewards from a validator. `Accum` is used to passively calculate +each bonds entitled rewards from the `RewardPool`. `AccumProposer` is used to +passively calculate each bonds entitled rewards from `ValidatorDistribution.ProposerRewardPool` - DelegatorDistribution: ` 0x02 | DelegatorAddr | ValOwnerAddr -> amino(delegatorDist)` ```golang type DelegatorDist struct { - WithdrawalHeight int64 // last time this delegation withdrew rewards - Adjustment sdk.Dec // fee provisioning adjustment factor - AdjustmentProposer DecCoins // proposers pool adjustment factor - PrevTokens sdk.Dec // bonded tokens held by the delegation on the previous block - PrevShares sdk.Dec // delegator shares held by the delegation on the previous block + WithdrawalHeight int64 // last time this delegation withdrew rewards + Accum sdk.Dec // reward provisioning accumulation factor + AccumProposer sdk.Dec // proposers pool accumulation factor } ``` -### Power Change - -Every instance that the voting power changes, information about the state of -the validator set during the change must be recorded as a `PowerChange` for -other validators to run through. Each power change is indexed by its block -height. - - - PowerChange: `0x03 | amino(Height) -> amino(validatorDist)` - -```golang -type PowerChange struct { - Height int64 // block height at change - ValidatorBondedTokens sdk.Dec // following used to create distribution scenarios - ValidatorDelegatorShares sdk.Dec - ValidatorDelegatorShareExRate sdk.Dec - ValidatorCommission sdk.Dec - PoolBondedTokens sdk.Dec - Global Global - ValDistr ValidatorDistribution - DelegationShares sdk.Dec - DelDistr DelegatorDistribution -} -``` From 2d613cefe7da94d9e9bdd30314e914c1447c499f Mon Sep 17 00:00:00 2001 From: rigelrozanski Date: Wed, 8 Aug 2018 14:24:38 -0400 Subject: [PATCH 03/18] move lamborghini distribution to subfolder --- .../WIP-lamborghini-distribution/README.md | 2 + .../end_block.md | 0 .../example_sheet/distribution.xlsx | Bin .../future_improvements.md | 0 .../WIP-lamborghini-distribution/overview.md | 54 ++++++++++ .../WIP-lamborghini-distribution/state.md | 100 ++++++++++++++++++ .../transactions.md | 0 .../WIP-lamborghini-distribution}/triggers.md | 0 docs/spec/distribution/overview.md | 54 ++++++---- docs/spec/distribution/state.md | 56 +++------- docs/spec/simple-distribution/overview.md | 64 ----------- docs/spec/simple-distribution/state.md | 68 ------------ 12 files changed, 200 insertions(+), 198 deletions(-) create mode 100644 docs/spec/distribution/WIP-lamborghini-distribution/README.md rename docs/spec/{simple-distribution => distribution/WIP-lamborghini-distribution}/end_block.md (100%) rename docs/spec/distribution/{ => WIP-lamborghini-distribution}/example_sheet/distribution.xlsx (100%) rename docs/spec/{simple-distribution => distribution/WIP-lamborghini-distribution}/future_improvements.md (100%) create mode 100644 docs/spec/distribution/WIP-lamborghini-distribution/overview.md create mode 100644 docs/spec/distribution/WIP-lamborghini-distribution/state.md rename docs/spec/{simple-distribution => distribution/WIP-lamborghini-distribution}/transactions.md (100%) rename docs/spec/{simple-distribution => distribution/WIP-lamborghini-distribution}/triggers.md (100%) delete mode 100644 docs/spec/simple-distribution/overview.md delete mode 100644 docs/spec/simple-distribution/state.md diff --git a/docs/spec/distribution/WIP-lamborghini-distribution/README.md b/docs/spec/distribution/WIP-lamborghini-distribution/README.md new file mode 100644 index 000000000..c09042f7f --- /dev/null +++ b/docs/spec/distribution/WIP-lamborghini-distribution/README.md @@ -0,0 +1,2 @@ +Please note that this folder is a WIP specification for an advanced fee distribution +mechanism which is not set to be implemented. diff --git a/docs/spec/simple-distribution/end_block.md b/docs/spec/distribution/WIP-lamborghini-distribution/end_block.md similarity index 100% rename from docs/spec/simple-distribution/end_block.md rename to docs/spec/distribution/WIP-lamborghini-distribution/end_block.md diff --git a/docs/spec/distribution/example_sheet/distribution.xlsx b/docs/spec/distribution/WIP-lamborghini-distribution/example_sheet/distribution.xlsx similarity index 100% rename from docs/spec/distribution/example_sheet/distribution.xlsx rename to docs/spec/distribution/WIP-lamborghini-distribution/example_sheet/distribution.xlsx diff --git a/docs/spec/simple-distribution/future_improvements.md b/docs/spec/distribution/WIP-lamborghini-distribution/future_improvements.md similarity index 100% rename from docs/spec/simple-distribution/future_improvements.md rename to docs/spec/distribution/WIP-lamborghini-distribution/future_improvements.md diff --git a/docs/spec/distribution/WIP-lamborghini-distribution/overview.md b/docs/spec/distribution/WIP-lamborghini-distribution/overview.md new file mode 100644 index 000000000..5e28e8b3b --- /dev/null +++ b/docs/spec/distribution/WIP-lamborghini-distribution/overview.md @@ -0,0 +1,54 @@ +# Distribution + +## Overview + +Collected fees are pooled globally and divided out passively to validators and +delegators. Each validator has the opportunity to charge commission to the +delegators on the fees collected on behalf of the delegators by the validators. +Fees are paid directly into a global fee pool, and validator proposer-reward +pool. Due to the nature of passive accounting whenever changes to parameters +which affect the rate of fee distribution occurs, withdrawal of fees 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 + full withdrawal of the fees must occur (as the rules for lazy accounting + change), + - a validator chooses to change the commission on fees, all accumulated + commission fees must be simultaneously withdrawn. + +The above scenarios are covered in `triggers.md`. + +The distribution mechanism outlines herein is used to lazily distribute the +following between validators and associated delegators: + - multi-token fees to be socially distributed, + - proposer reward pool, + - inflated atom provisions, and + - 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. As a part of the lazy +computations adjustment factors must be maintained for each validator and +delegator to determine the true proportion of fees in each pool which they are +entitled too. Adjustment factors are updated every time a validator or +delegator's voting power changes. Validators and delegators must withdraw all +fees they are entitled too before they can change their portion of bonded +Atoms. + +## 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 +of Atoms the fee distribution calculation would become very large as the Atom +portion for each delegator would change each block making a withdrawal of fees +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 +implement the former. Stakeholders wishing to rebond their provisions may elect +to set up a script to periodically withdraw and rebond fees. + diff --git a/docs/spec/distribution/WIP-lamborghini-distribution/state.md b/docs/spec/distribution/WIP-lamborghini-distribution/state.md new file mode 100644 index 000000000..7865c085e --- /dev/null +++ b/docs/spec/distribution/WIP-lamborghini-distribution/state.md @@ -0,0 +1,100 @@ +## 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)` + +```golang +// coins with decimal +type DecCoins []DecCoin + +type DecCoin struct { + Amount sdk.Dec + Denom string +} + +type Global struct { + PrevBondedTokens sdk.Dec // bonded token amount for the global pool on the previous block + Adjustment sdk.Dec // global adjustment factor for lazy calculations + Pool DecCoins // funds for all validators which have yet to be withdrawn + PrevReceivedPool DecCoins // funds added to the pool on the previous block + EverReceivedPool DecCoins // total funds ever added to the pool + CommunityFund 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)` + +```golang +type ValidatorDistribution struct { + CommissionWithdrawalHeight int64 // last time this validator withdrew commission + Adjustment sdk.Dec // global pool adjustment factor + ProposerAdjustment DecCoins // proposer pool adjustment factor + ProposerPool DecCoins // reward pool collected from being the proposer + EverReceivedProposerReward DecCoins // all rewards ever collected from being the proposer + PrevReceivedProposerReward DecCoins // previous rewards collected from being the proposer + PrevBondedTokens sdk.Dec // bonded token amount on the previous block + PrevDelegatorShares sdk.Dec // amount of delegator shares for the validator on the previous block +} +``` + +### Delegation Distribution + +Each delegation holds multiple adjustment factors to specify its entitlement to +the rewards from a validator. `AdjustmentPool` is used to passively calculate +each bonds entitled fees from the `RewardPool`. `AdjustmentPool` is used to +passively calculate each bonds entitled fees from +`ValidatorDistribution.ProposerRewardPool` + + - DelegatorDistribution: ` 0x02 | DelegatorAddr | ValOwnerAddr -> amino(delegatorDist)` + +```golang +type DelegatorDist struct { + WithdrawalHeight int64 // last time this delegation withdrew rewards + Adjustment sdk.Dec // fee provisioning adjustment factor + AdjustmentProposer DecCoins // proposers pool adjustment factor + PrevTokens sdk.Dec // bonded tokens held by the delegation on the previous block + PrevShares sdk.Dec // delegator shares held by the delegation on the previous block +} +``` + +### Power Change + +Every instance that the voting power changes, information about the state of +the validator set during the change must be recorded as a `PowerChange` for +other validators to run through. Each power change is indexed by its block +height. + + - PowerChange: `0x03 | amino(Height) -> amino(validatorDist)` + +```golang +type PowerChange struct { + Height int64 // block height at change + ValidatorBondedTokens sdk.Dec // following used to create distribution scenarios + ValidatorDelegatorShares sdk.Dec + ValidatorDelegatorShareExRate sdk.Dec + ValidatorCommission sdk.Dec + PoolBondedTokens sdk.Dec + Global Global + ValDistr ValidatorDistribution + DelegationShares sdk.Dec + DelDistr DelegatorDistribution +} +``` diff --git a/docs/spec/simple-distribution/transactions.md b/docs/spec/distribution/WIP-lamborghini-distribution/transactions.md similarity index 100% rename from docs/spec/simple-distribution/transactions.md rename to docs/spec/distribution/WIP-lamborghini-distribution/transactions.md diff --git a/docs/spec/simple-distribution/triggers.md b/docs/spec/distribution/WIP-lamborghini-distribution/triggers.md similarity index 100% rename from docs/spec/simple-distribution/triggers.md rename to docs/spec/distribution/WIP-lamborghini-distribution/triggers.md diff --git a/docs/spec/distribution/overview.md b/docs/spec/distribution/overview.md index 5e28e8b3b..62cec2e76 100644 --- a/docs/spec/distribution/overview.md +++ b/docs/spec/distribution/overview.md @@ -2,26 +2,31 @@ ## Overview -Collected fees are pooled globally and divided out passively to validators and -delegators. Each validator has the opportunity to charge commission to the -delegators on the fees collected on behalf of the delegators by the validators. -Fees are paid directly into a global fee pool, and validator proposer-reward -pool. Due to the nature of passive accounting whenever changes to parameters -which affect the rate of fee distribution occurs, withdrawal of fees must also -occur when: +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 +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 +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 - full withdrawal of the fees must occur (as the rules for lazy accounting + full withdrawal of the rewards must occur (as the rules for lazy accounting change), - - a validator chooses to change the commission on fees, all accumulated - commission fees must be simultaneously withdrawn. + - 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`. The distribution mechanism outlines herein is used to lazily distribute the -following between validators and associated delegators: +following rewards between validators and associated delegators: - multi-token fees to be socially distributed, - proposer reward pool, - inflated atom provisions, and @@ -29,26 +34,31 @@ following between validators and associated delegators: 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. As a part of the lazy -computations adjustment factors must be maintained for each validator and -delegator to determine the true proportion of fees in each pool which they are -entitled too. Adjustment factors are updated every time a validator or -delegator's voting power changes. Validators and delegators must withdraw all -fees they are entitled too before they can change their portion of bonded -Atoms. +to independently and lazily withdrawn their rewards. + +Within this spec + +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 +of tokens held in the global pool is owed to them. This approximation of owed +rewards would be equivalent to the active distribution under the situation that +there was a constant flow of incoming reward tokens every block. Because this +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 -of Atoms the fee distribution calculation would become very large as the Atom -portion for each delegator would change each block making a withdrawal of fees +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 implement the former. Stakeholders wishing to rebond their provisions may elect -to set up a script to periodically withdraw and rebond fees. +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 7865c085e..757287004 100644 --- a/docs/spec/distribution/state.md +++ b/docs/spec/distribution/state.md @@ -23,11 +23,8 @@ type DecCoin struct { } type Global struct { - PrevBondedTokens sdk.Dec // bonded token amount for the global pool on the previous block - Adjustment sdk.Dec // global adjustment factor for lazy calculations + Accum sdk.Dec // global accumulation factor for lazy calculations Pool DecCoins // funds for all validators which have yet to be withdrawn - PrevReceivedPool DecCoins // funds added to the pool on the previous block - EverReceivedPool DecCoins // total funds ever added to the pool CommunityFund DecCoins // pool for community funds yet to be spent } ``` @@ -44,57 +41,28 @@ Validator distribution information for the relevant validator is updated each ti ```golang type ValidatorDistribution struct { - CommissionWithdrawalHeight int64 // last time this validator withdrew commission - Adjustment sdk.Dec // global pool adjustment factor - ProposerAdjustment DecCoins // proposer pool adjustment factor - ProposerPool DecCoins // reward pool collected from being the proposer - EverReceivedProposerReward DecCoins // all rewards ever collected from being the proposer - PrevReceivedProposerReward DecCoins // previous rewards collected from being the proposer - PrevBondedTokens sdk.Dec // bonded token amount on the previous block - PrevDelegatorShares sdk.Dec // amount of delegator shares for the validator on the previous block + CommissionWithdrawalHeight int64 // last time this validator withdrew commission + Accum sdk.Dec // global pool accumulation factor + ProposerAccum sdk.Dec // proposer pool accumulation factor + ProposerPool DecCoins // reward pool collected from being the proposer } ``` ### Delegation Distribution -Each delegation holds multiple adjustment factors to specify its entitlement to -the rewards from a validator. `AdjustmentPool` is used to passively calculate -each bonds entitled fees from the `RewardPool`. `AdjustmentPool` is used to -passively calculate each bonds entitled fees from +Each delegation holds multiple accumulation factors to specify its entitlement to +the rewards from a validator. `Accum` is used to passively calculate +each bonds entitled rewards from the `RewardPool`. `AccumProposer` is used to +passively calculate each bonds entitled rewards from `ValidatorDistribution.ProposerRewardPool` - DelegatorDistribution: ` 0x02 | DelegatorAddr | ValOwnerAddr -> amino(delegatorDist)` ```golang type DelegatorDist struct { - WithdrawalHeight int64 // last time this delegation withdrew rewards - Adjustment sdk.Dec // fee provisioning adjustment factor - AdjustmentProposer DecCoins // proposers pool adjustment factor - PrevTokens sdk.Dec // bonded tokens held by the delegation on the previous block - PrevShares sdk.Dec // delegator shares held by the delegation on the previous block + WithdrawalHeight int64 // last time this delegation withdrew rewards + Accum sdk.Dec // reward provisioning accumulation factor + AccumProposer sdk.Dec // proposers pool accumulation factor } ``` -### Power Change - -Every instance that the voting power changes, information about the state of -the validator set during the change must be recorded as a `PowerChange` for -other validators to run through. Each power change is indexed by its block -height. - - - PowerChange: `0x03 | amino(Height) -> amino(validatorDist)` - -```golang -type PowerChange struct { - Height int64 // block height at change - ValidatorBondedTokens sdk.Dec // following used to create distribution scenarios - ValidatorDelegatorShares sdk.Dec - ValidatorDelegatorShareExRate sdk.Dec - ValidatorCommission sdk.Dec - PoolBondedTokens sdk.Dec - Global Global - ValDistr ValidatorDistribution - DelegationShares sdk.Dec - DelDistr DelegatorDistribution -} -``` diff --git a/docs/spec/simple-distribution/overview.md b/docs/spec/simple-distribution/overview.md deleted file mode 100644 index 62cec2e76..000000000 --- a/docs/spec/simple-distribution/overview.md +++ /dev/null @@ -1,64 +0,0 @@ -# Distribution - -## Overview - -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 -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 -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 - 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 - commission rewards must be simultaneously withdrawn. - -The above scenarios are covered in `triggers.md`. - -The distribution mechanism outlines herein is used to lazily distribute the -following rewards between validators and associated delegators: - - multi-token fees to be socially distributed, - - proposer reward pool, - - inflated atom provisions, and - - 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 - -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 -of tokens held in the global pool is owed to them. This approximation of owed -rewards would be equivalent to the active distribution under the situation that -there was a constant flow of incoming reward tokens every block. Because this -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 -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 -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/simple-distribution/state.md b/docs/spec/simple-distribution/state.md deleted file mode 100644 index 757287004..000000000 --- a/docs/spec/simple-distribution/state.md +++ /dev/null @@ -1,68 +0,0 @@ -## 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)` - -```golang -// coins with decimal -type DecCoins []DecCoin - -type DecCoin struct { - Amount sdk.Dec - Denom string -} - -type Global struct { - Accum sdk.Dec // global accumulation factor for lazy calculations - Pool DecCoins // funds for all validators which have yet to be withdrawn - CommunityFund 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)` - -```golang -type ValidatorDistribution struct { - CommissionWithdrawalHeight int64 // last time this validator withdrew commission - Accum sdk.Dec // global pool accumulation factor - ProposerAccum sdk.Dec // proposer pool accumulation factor - ProposerPool DecCoins // reward pool collected from being the proposer -} -``` - -### Delegation Distribution - -Each delegation holds multiple accumulation factors to specify its entitlement to -the rewards from a validator. `Accum` is used to passively calculate -each bonds entitled rewards from the `RewardPool`. `AccumProposer` is used to -passively calculate each bonds entitled rewards from -`ValidatorDistribution.ProposerRewardPool` - - - DelegatorDistribution: ` 0x02 | DelegatorAddr | ValOwnerAddr -> amino(delegatorDist)` - -```golang -type DelegatorDist struct { - WithdrawalHeight int64 // last time this delegation withdrew rewards - Accum sdk.Dec // reward provisioning accumulation factor - AccumProposer sdk.Dec // proposers pool accumulation factor -} -``` - From a0e05a8f0373d4b123200c98c60f9517484f22dd Mon Sep 17 00:00:00 2001 From: rigelrozanski Date: Wed, 8 Aug 2018 15:03:43 -0400 Subject: [PATCH 04/18] triggers, endblock, transactions --- docs/spec/distribution/end_block.md | 8 +- docs/spec/distribution/future_improvements.md | 16 -- docs/spec/distribution/transactions.md | 176 +----------------- docs/spec/distribution/triggers.md | 27 ++- 4 files changed, 21 insertions(+), 206 deletions(-) delete mode 100644 docs/spec/distribution/future_improvements.md diff --git a/docs/spec/distribution/end_block.md b/docs/spec/distribution/end_block.md index bc6847ef4..19c9e8302 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 954fb4d62..000000000 --- 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 1401c3b85..7816757e5 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 8800609a4..93358fe2e 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. From 5285489977f5126b1f9a954d0e7c80cb75229da5 Mon Sep 17 00:00:00 2001 From: rigelrozanski Date: Wed, 8 Aug 2018 23:43:40 -0400 Subject: [PATCH 05/18] general updates --- docs/spec/distribution/state.md | 49 +++++++---- docs/spec/distribution/transactions.md | 108 ++++--------------------- docs/spec/distribution/triggers.md | 14 ++-- 3 files changed, 58 insertions(+), 113 deletions(-) diff --git a/docs/spec/distribution/state.md b/docs/spec/distribution/state.md index 757287004..115782594 100644 --- a/docs/spec/distribution/state.md +++ b/docs/spec/distribution/state.md @@ -23,9 +23,10 @@ type DecCoin struct { } type Global struct { - Accum sdk.Dec // global accumulation factor for lazy calculations - Pool DecCoins // funds for all validators which have yet to be withdrawn - CommunityFund DecCoins // pool for community funds yet to be spent + 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 } ``` @@ -41,28 +42,48 @@ Validator distribution information for the relevant validator is updated each ti ```golang type ValidatorDistribution struct { - CommissionWithdrawalHeight int64 // last time this validator withdrew commission - Accum sdk.Dec // global pool accumulation factor - ProposerAccum sdk.Dec // proposer pool accumulation factor - ProposerPool DecCoins // reward pool collected from being the proposer + 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 holds multiple accumulation factors to specify its entitlement to -the rewards from a validator. `Accum` is used to passively calculate -each bonds entitled rewards from the `RewardPool`. `AccumProposer` is used to -passively calculate each bonds entitled rewards from -`ValidatorDistribution.ProposerRewardPool` +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)` ```golang type DelegatorDist struct { WithdrawalHeight int64 // last time this delegation withdrew rewards - Accum sdk.Dec // reward provisioning accumulation factor - AccumProposer sdk.Dec // proposers pool accumulation factor } ``` +### 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)` + +```golang +type ValidatorUpdate struct { + Height int64 // block height of update + NewCommissionRate sdk.Dec // commission rate at this height +} +``` diff --git a/docs/spec/distribution/transactions.md b/docs/spec/distribution/transactions.md index 7816757e5..7d6bcc752 100644 --- a/docs/spec/distribution/transactions.md +++ b/docs/spec/distribution/transactions.md @@ -1,3 +1,16 @@ + + + +Each delegation holds multiple accumulation factors to specify its entitlement to +the rewards from a validator. `Accum` is used to passively calculate +each bonds entitled rewards from the `RewardPool`. `AccumProposer` is used to +passively calculate each bonds entitled rewards from +`ValidatorDistribution.ProposerRewardPool` + + + + + # Transactions ## TxWithdrawDelegation @@ -10,7 +23,7 @@ redelegation, or delegation of additional tokens to a specific validator. Each time a withdrawal is made by a recipient the adjustment term must be modified for each block with a change in distributors shares since the time of last withdrawal. This is accomplished by iterating over all relevant -`PowerChange`'s stored in distribution state. +`ValidatorUpdate`'s stored in distribution state. ```golang @@ -57,7 +70,7 @@ func GetDelegatorEntitlement(delegatorAddr sdk.AccAddress) DecCoins return entitlement -func (pc PowerChange) ProcessPowerChangeDelegation(delegation sdk.Delegation, +func (pc ValidatorUpdate) ProcessPowerChangeDelegation(delegation sdk.Delegation, DelDistr DelegationDistribution) // get the historical scenarios @@ -109,7 +122,7 @@ func WithdrawalValidator(ownerAddr, withdrawAddr sdk.AccAddress) AddCoins(withdrawAddr, totalEntitlment.TruncateDecimal()) -func (pc PowerChange) ProcessPowerChangeCommission() +func (pc ValidatorUpdate) ProcessPowerChangeCommission() // get the historical scenarios scenario1 = pc.CommissionFromGlobalPool() @@ -122,75 +135,6 @@ func (pc PowerChange) ProcessPowerChangeCommission() ## Common Calculations -### Distribution scenario - -A common form of abstracted calculations exists between validators and -delegations attempting to withdrawal their rewards, either from `Global.Pool` -or from `ValidatorDistribution.ProposerPool`. With the following interface -fulfilled the entitled fees for the various scenarios can be calculated. - -```golang -type DistributionScenario interface { - DistributorTokens() DecCoins // current tokens from distributor - DistributorShares() sdk.Dec // current shares - RecipientAccum() sdk.Dec - RecipientShares() sdk.Dec // current shares - - ModifyAccums(withdrawal sdk.Dec) // proceedure to modify adjustment factors -} -``` - -#### Entitled reward from distribution scenario - -The entitlement to the distributor's tokens held can be accounted for lazily. -To begin this calculation we must determine the recipient's _simple pool_ and -_projected pool_. The simple pool represents a lazy accounting of what a -recipient's entitlement to the distributor's tokens would be if all recipients -for that distributor had static shares (equal to the current shares), and no -recipients had ever withdrawn their entitled rewards. The projected pool -represents the anticipated recipient's entitlement to the distributors tokens -based on the current blocks token input (for example fees reward received) to -the distributor, and the distributor's tokens and shares of the previous block -assuming that neither had changed in the current block. Using the simple and -projected pools we can determine all cumulative changes which have taken place -outside of the recipient and adjust the recipient's _adjustment factor_ to -account for these changes and ultimately keep track of the correct entitlement -to the distributors tokens. - -``` -func (d DistributionScenario) RecipientCount(height int64) sdk.Dec - return v.RecipientShares() * height - -func (d DistributionScenario) GlobalCount(height int64) sdk.Dec - return d.DistributorShares() * height - -``` - -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. - - When the shares of the recipient is changed the adjustment factor is - increased/decreased by the difference between the _simple_ and _projected_ - pools. In other words, the cumulative difference in the shares if the shares - has been the new shares as opposed to the old shares for the entire duration of - the blockchain up the previous block. - - When a recipient makes a withdrawal the adjustment factor is increased by the - withdrawal amount. - -``` -func (d DistributionScenario) UpdateAdjustmentForPowerChange(height int64) - simplePool = d.SimplePool() - projectedPool = d.ProjectedPool(height) - AdjustmentChange = simplePool - projectedPool - if AdjustmentChange > 0 - d.ModifyAdjustments(AdjustmentChange) - -func (d DistributionScenario) WithdrawalEntitlement() DecCoins - entitlement = d.SimplePool() - d.RecipientAdjustment() - d.ModifyAdjustments(entitlement) - return entitlement -``` ### Distribution scenarios @@ -206,17 +150,6 @@ shares should be taken as the bonded tokens less the validator's commission. ``` ``` -#### Delegation's entitlement to ValidatorDistribution.ProposerPool - -Delegations (including validator's self-delegation) are still subject -commission on the rewards gained from the proposer pool. Global shares in this -context is actually the validators total delegations shares. The recipient's -shares is taken as the effective delegation shares less the validator's -commission. - -``` -``` - #### Validators's commission entitlement to Global.Pool Similar to a delegator's entitlement, but with recipient shares based on the @@ -224,12 +157,3 @@ commission portion of bonded tokens. ``` ``` - -#### Validators's commission entitlement to ValidatorDistribution.ProposerPool - -Similar to a delegators entitlement to the proposer pool, but with recipient -shares based on the commission portion of the total delegator shares. - -``` -``` - diff --git a/docs/spec/distribution/triggers.md b/docs/spec/distribution/triggers.md index 93358fe2e..0e02f0431 100644 --- a/docs/spec/distribution/triggers.md +++ b/docs/spec/distribution/triggers.md @@ -6,21 +6,21 @@ The pool of a new delegator bond will be 0 for the height at which the bond was 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. +`DelegatorDist.WithdrawalHeight` to the height of the triggering transaction. ## Commission rate change - triggered-by: `stake.TxEditValidator` If a validator changes its commission rate, all commission on fees must be -simultaneously withdrawn using the transaction `TxWithdrawValidator` +simultaneously withdrawn using the transaction `TxWithdrawValidator`. +Additionally the change and associated height must be recorded in a +`ValidatorUpdate` state record. ## 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. +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 `ValidatorDistribution.Pool` From e7ebe35b0a530bf470c4c0351cc369821e123541 Mon Sep 17 00:00:00 2001 From: rigelrozanski Date: Thu, 9 Aug 2018 00:34:19 -0400 Subject: [PATCH 06/18] updating transactions --- docs/spec/distribution/transactions.md | 95 +++++++++++++++++--------- 1 file changed, 61 insertions(+), 34 deletions(-) diff --git a/docs/spec/distribution/transactions.md b/docs/spec/distribution/transactions.md index 7d6bcc752..30ea6ab46 100644 --- a/docs/spec/distribution/transactions.md +++ b/docs/spec/distribution/transactions.md @@ -1,16 +1,3 @@ - - - -Each delegation holds multiple accumulation factors to specify its entitlement to -the rewards from a validator. `Accum` is used to passively calculate -each bonds entitled rewards from the `RewardPool`. `AccumProposer` is used to -passively calculate each bonds entitled rewards from -`ValidatorDistribution.ProposerRewardPool` - - - - - # Transactions ## TxWithdrawDelegation @@ -42,14 +29,14 @@ func GetDelegatorEntitlement(delegatorAddr sdk.AccAddress) DecCoins delegations = GetDelegations(delegatorAddr) DelDistr = GetDelegationDistribution(delegation.DelegatorAddr, delegation.ValidatorAddr) - pcs = GetPowerChanges(DelDistr.WithdrawalHeight) + vus = GetValidatorUpdates(DelDistr.WithdrawalHeight) // update all adjustment factors for each delegation since last withdrawal - for pc = range pcs + for vu = range vus for delegation = range delegations DelDistr = GetDelegationDistribution(delegation.DelegatorAddr, delegation.ValidatorAddr) - pc.ProcessPowerChangeDelegation(delegation, DelDistr) + vu.ProcessPowerChangeDelegation(delegation, DelDistr) // collect all entitled fees entitlement = 0 @@ -70,16 +57,16 @@ func GetDelegatorEntitlement(delegatorAddr sdk.AccAddress) DecCoins return entitlement -func (pc ValidatorUpdate) ProcessPowerChangeDelegation(delegation sdk.Delegation, +func (vu ValidatorUpdate) ProcessPowerChangeDelegation(delegation sdk.Delegation, DelDistr DelegationDistribution) // get the historical scenarios - scenario1 = pc.DelegationFromGlobalPool(delegation, DelDistr) - scenario2 = pc.DelegationFromProvisionPool(delegation, DelDistr) + scenario1 = vu.DelegationFromGlobalPool(delegation, DelDistr) + scenario2 = vu.DelegationFromProvisionPool(delegation, DelDistr) // process the adjustment factors - scenario1.UpdateAdjustmentForPowerChange(pc.Height) - scenario2.UpdateAdjustmentForPowerChange(pc.Height) + scenario1.UpdateAdjustmentForPowerChange(vu.Height) + scenario2.UpdateAdjustmentForPowerChange(vu.Height) ``` ## TxWithdrawValidator @@ -91,7 +78,7 @@ redelegation, or delegation of additional tokens to a specific validator. This transaction withdraws the validators commission rewards, as well as any rewards earning on their self-delegation. -```golang +``` type TxWithdrawValidator struct { ownerAddr sdk.AccAddress // validator address to withdraw from withdrawAddr sdk.AccAddress // address to make the withdrawal to @@ -104,9 +91,9 @@ func WithdrawalValidator(ownerAddr, withdrawAddr sdk.AccAddress) // update the validator adjustment factors for commission ValDistr = GetValidatorDistribution(ownerAddr.ValidatorAddr) - pcs = GetPowerChanges(ValDistr.CommissionWithdrawalHeight) - for pc = range pcs - pc.ProcessPowerChangeCommission() + vus = GetValidatorUpdates(ValDistr.CommissionWithdrawalHeight) + for vu = range vus + vu.ProcessPowerChangeCommission() // withdrawal validator commission rewards global = GetGlobal() @@ -122,38 +109,78 @@ func WithdrawalValidator(ownerAddr, withdrawAddr sdk.AccAddress) AddCoins(withdrawAddr, totalEntitlment.TruncateDecimal()) -func (pc ValidatorUpdate) ProcessPowerChangeCommission() +func (vu ValidatorUpdate) ProcessPowerChangeCommission() // get the historical scenarios - scenario1 = pc.CommissionFromGlobalPool() - scenario2 = pc.CommissionFromProposerPool() + scenario1 = vu.CommissionFromGlobalPool() + scenario2 = vu.CommissionFromProposerPool() // process the adjustment factors - scenario1.UpdateAdjustmentForPowerChange(pc.Height) - scenario2.UpdateAdjustmentForPowerChange(pc.Height) + scenario1.UpdateAdjustmentForPowerChange(vu.Height) + scenario2.UpdateAdjustmentForPowerChange(vu.Height) ``` ## Common Calculations -### Distribution scenarios +### Update total validator accum -Note that the distribution scenario structures are found in `state.md`. +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. +This term is to be updated during a validator withdrawal. -#### Delegation's entitlement to Global.Pool +``` +func (g Global) UpdateTotalValAccum() + +TODO + +``` + +### Update total delegator accum + +Each delegation holds multiple accumulation factors to specify its entitlement to +the rewards from a validator. `Accum` is used to passively calculate +each bonds entitled rewards from the `RewardPool`. `AccumProposer` is used to +passively calculate each bonds entitled rewards from +`ValidatorDistribution.ProposerRewardPool` + +``` +TODO +``` + +### Global Pool to Validator Pool + +Everytime a validator or delegator make a withdraw or the validator is the +proposer and receives new tokens - the relavent validator must move tokens from +the passive global pool to thier own pool. + +``` +TODO +``` + + +### Delegation's entitlement to ValidatorDistribution.Pool For delegations (including validator's self-delegation) all fees from fee pool are subject to commission rate from the owner of the validator. The global 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. +Each delegation holds multiple accumulation factors to specify its entitlement to +the rewards from a validator. `Accum` is used to passively calculate +each bonds entitled rewards from the `RewardPool`. `AccumProposer` is used to +passively calculate each bonds entitled rewards from +`ValidatorDistribution.ProposerRewardPool` + ``` +TODO ``` -#### Validators's commission entitlement to Global.Pool +### Validators's commission entitlement to ValidatorDistribution.Pool Similar to a delegator's entitlement, but with recipient shares based on the commission portion of bonded tokens. ``` +TODO ``` From 5e5fad454849131246c30796f22e6de0d0a4e96a Mon Sep 17 00:00:00 2001 From: rigelrozanski Date: Tue, 14 Aug 2018 13:45:13 -0400 Subject: [PATCH 07/18] txs --- docs/spec/distribution/transactions.md | 43 +++++++++++++++++--------- 1 file changed, 29 insertions(+), 14 deletions(-) diff --git a/docs/spec/distribution/transactions.md b/docs/spec/distribution/transactions.md index 30ea6ab46..b8de54ca5 100644 --- a/docs/spec/distribution/transactions.md +++ b/docs/spec/distribution/transactions.md @@ -122,30 +122,43 @@ func (vu ValidatorUpdate) ProcessPowerChangeCommission() ## Common Calculations - ### Update total validator accum 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. -This term is to be updated during a validator withdrawal. +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. ``` -func (g Global) UpdateTotalValAccum() - -TODO - +func (g Global) UpdateTotalValAccum(height int64, totalBondedTokens Dec) + blocks = height - g.TotalValAccumUpdateHeight + g.TotalValAccum += totalDelShares * blocks ``` ### Update total delegator accum -Each delegation holds multiple accumulation factors to specify its entitlement to -the rewards from a validator. `Accum` is used to passively calculate -each bonds entitled rewards from the `RewardPool`. `AccumProposer` is used to -passively calculate each bonds entitled rewards from -`ValidatorDistribution.ProposerRewardPool` +The total amount of delegator accum must be updated in order to determine the +amount of pool tokens which each delegator is entitled to, relative to the +other delegators for that validator. The accum is always additive to +the existing accum. This term is to be updated each time a +withdrawal is made from a validator. ``` -TODO +func (vd ValidatorDistribution) UpdateTotalDelAccum(height int64, totalDelShares Dec) + blocks = height - vd.TotalDelAccumUpdateHeight + vd.TotalDelAccum += totalDelShares * blocks +``` + +### Delegator accum + +Each delegation has a passively calculated accumulation factor to specify its +entitlement to the rewards from a validator. `Accum` is used to passively +calculate each bonds entitled rewards from the `Validator.Pool`. + +``` +func (dd DelegatorDist) Accum(height int64, delegatorShares Dec) Dec + blocks = height - dd.WithdrawalHeight + return delegatorShares * blocks ``` ### Global Pool to Validator Pool @@ -155,7 +168,9 @@ proposer and receives new tokens - the relavent validator must move tokens from the passive global pool to thier own pool. ``` -TODO +func (dd DelegatorDist) ValidatorUpdate(g Global, totalBondedShares, height int64, Tokens Dec) Dec + + g.UpdateTotalValAccum(height, totalBondedShares) ``` From 360eb75c8e6cbc11ac7b7ae885a8bb3f7d11db20 Mon Sep 17 00:00:00 2001 From: rigelrozanski Date: Tue, 14 Aug 2018 23:33:40 -0400 Subject: [PATCH 08/18] working --- docs/spec/distribution/transactions.md | 45 +++++++++++++++----------- 1 file changed, 26 insertions(+), 19 deletions(-) diff --git a/docs/spec/distribution/transactions.md b/docs/spec/distribution/transactions.md index b8de54ca5..22e4e4077 100644 --- a/docs/spec/distribution/transactions.md +++ b/docs/spec/distribution/transactions.md @@ -120,14 +120,14 @@ func (vu ValidatorUpdate) ProcessPowerChangeCommission() scenario2.UpdateAdjustmentForPowerChange(vu.Height) ``` -## Common Calculations +## Common calculations ### Update total validator accum 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. +updates each time rewards are withdrawn from the system. ``` func (g Global) UpdateTotalValAccum(height int64, totalBondedTokens Dec) @@ -135,7 +135,7 @@ func (g Global) UpdateTotalValAccum(height int64, totalBondedTokens Dec) g.TotalValAccum += totalDelShares * blocks ``` -### Update total delegator accum +### Update validator's accums The total amount of delegator accum must be updated in order to determine the amount of pool tokens which each delegator is entitled to, relative to the @@ -149,7 +149,7 @@ func (vd ValidatorDistribution) UpdateTotalDelAccum(height int64, totalDelShares vd.TotalDelAccum += totalDelShares * blocks ``` -### Delegator accum +### Get delegator accum Each delegation has a passively calculated accumulation factor to specify its entitlement to the rewards from a validator. `Accum` is used to passively @@ -161,37 +161,44 @@ func (dd DelegatorDist) Accum(height int64, delegatorShares Dec) Dec return delegatorShares * blocks ``` -### Global Pool to Validator Pool +### Global pool to validator pool Everytime a validator or delegator make a withdraw or the validator is the proposer and receives new tokens - the relavent validator must move tokens from the passive global pool to thier own pool. ``` -func (dd DelegatorDist) ValidatorUpdate(g Global, totalBondedShares, height int64, Tokens Dec) Dec - +func (vd ValidatorDistribution) TakeAccum(g Global, height int64, totalBonded, vdTokens Dec) g Global g.UpdateTotalValAccum(height, totalBondedShares) + g.UpdateValAccum(height, totalBondedShares) + + // update the validators pool + blocks = height - vd.GlobalWithdrawalHeight + accum = blocks * vdTokens + withdrawalTokens := g.Pool * accum / g.TotalValAccum + + vd.Pool += withdrawalTokens + g.Pool -= withdrawalTokens + + return g ``` -### Delegation's entitlement to ValidatorDistribution.Pool +### Delegation's withdrawal For delegations (including validator's self-delegation) all fees from fee pool -are subject to commission rate from the owner of the validator. The global -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. - -Each delegation holds multiple accumulation factors to specify its entitlement to -the rewards from a validator. `Accum` is used to passively calculate -each bonds entitled rewards from the `RewardPool`. `AccumProposer` is used to -passively calculate each bonds entitled rewards from -`ValidatorDistribution.ProposerRewardPool` +are subject to commission rate from the owner of the validator. ``` -TODO +func (dd DelegatorDist) WithdrawalRewards(g Global, vd ValidatorDistribution, + height int64, totalBonded, vdTokens Dec) g Global + + vd.TakeAccum(g, height, totalBonded, vdTokens) + + ``` -### Validators's commission entitlement to ValidatorDistribution.Pool +### Validators's commission withdrawal Similar to a delegator's entitlement, but with recipient shares based on the commission portion of bonded tokens. From 37ed3b1a6eae69e2f8a361849c01417c6fa598ce Mon Sep 17 00:00:00 2001 From: rigelrozanski Date: Wed, 15 Aug 2018 04:12:44 -0400 Subject: [PATCH 09/18] agasg --- docs/spec/distribution/transactions.md | 40 ++++++++++++++++---------- 1 file changed, 25 insertions(+), 15 deletions(-) diff --git a/docs/spec/distribution/transactions.md b/docs/spec/distribution/transactions.md index 22e4e4077..cf10d8e2e 100644 --- a/docs/spec/distribution/transactions.md +++ b/docs/spec/distribution/transactions.md @@ -149,18 +149,6 @@ func (vd ValidatorDistribution) UpdateTotalDelAccum(height int64, totalDelShares vd.TotalDelAccum += totalDelShares * blocks ``` -### Get delegator accum - -Each delegation has a passively calculated accumulation factor to specify its -entitlement to the rewards from a validator. `Accum` is used to passively -calculate each bonds entitled rewards from the `Validator.Pool`. - -``` -func (dd DelegatorDist) Accum(height int64, delegatorShares Dec) Dec - blocks = height - dd.WithdrawalHeight - return delegatorShares * blocks -``` - ### Global pool to validator pool Everytime a validator or delegator make a withdraw or the validator is the @@ -177,6 +165,7 @@ func (vd ValidatorDistribution) TakeAccum(g Global, height int64, totalBonded, v accum = blocks * vdTokens withdrawalTokens := g.Pool * accum / g.TotalValAccum + g.TotalValAccum -= accumm vd.Pool += withdrawalTokens g.Pool -= withdrawalTokens @@ -191,10 +180,18 @@ are subject to commission rate from the owner of the validator. ``` func (dd DelegatorDist) WithdrawalRewards(g Global, vd ValidatorDistribution, - height int64, totalBonded, vdTokens Dec) g Global + height int64, totalBonded, vdTokens, totalDelShares, commissionRate Dec) (g Global, withdrawn Dec) - vd.TakeAccum(g, height, totalBonded, vdTokens) + vd.UpdateTotalDelAccum(height, totalDelShares) + g = vd.TakeAccum(g, height, totalBonded, vdTokens) + blocks = height - dd.WithdrawalHeight + accum = delegatorShares * blocks * (1 - commissionRate) + + withdrawalTokens := vd.Pool * accum / cd.TotalDelAccum + vd.Pool -= withdrawalTokens + vd.TotalDelAccum -= accum + return withdrawalTokens ``` @@ -204,5 +201,18 @@ Similar to a delegator's entitlement, but with recipient shares based on the commission portion of bonded tokens. ``` -TODO +func (dd DelegatorDist) WithdrawalCommission(g Global, vd ValidatorDistribution, + height int64, totalBonded, vdTokens, totalDelShares, commissionRate Dec) g Global + + vd.UpdateTotalDelAccum(height, totalDelShares) + g = vd.TakeAccum(g, height, totalBonded, vdTokens) + + blocks = height - vd.CommissionWithdrawalHeight + accum = delegatorShares * blocks * (commissionRate) + + withdrawalTokens := vd.Pool * accum / cd.TotalDelAccum + + vd.Pool -= withdrawalTokens + vd.TotalDelAccum -= accum + ``` From 31d5348c4ae164a187f3670ddf4535045d758444 Mon Sep 17 00:00:00 2001 From: rigelrozanski Date: Wed, 15 Aug 2018 20:03:39 -0400 Subject: [PATCH 10/18] txs pretty much ready --- docs/spec/distribution/transactions.md | 21 +++++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/docs/spec/distribution/transactions.md b/docs/spec/distribution/transactions.md index cf10d8e2e..4e8ad92e4 100644 --- a/docs/spec/distribution/transactions.md +++ b/docs/spec/distribution/transactions.md @@ -133,6 +133,7 @@ updates each time rewards are withdrawn from the system. func (g Global) UpdateTotalValAccum(height int64, totalBondedTokens Dec) blocks = height - g.TotalValAccumUpdateHeight g.TotalValAccum += totalDelShares * blocks + g.TotalValAccumUpdateHeight = height ``` ### Update validator's accums @@ -147,6 +148,7 @@ withdrawal is made from a validator. func (vd ValidatorDistribution) UpdateTotalDelAccum(height int64, totalDelShares Dec) blocks = height - vd.TotalDelAccumUpdateHeight vd.TotalDelAccum += totalDelShares * blocks + vd.TotalDelAccumUpdateHeight = height ``` ### Global pool to validator pool @@ -162,6 +164,7 @@ func (vd ValidatorDistribution) TakeAccum(g Global, height int64, totalBonded, v // update the validators pool blocks = height - vd.GlobalWithdrawalHeight + vd.GlobalWithdrawalHeight = height accum = blocks * vdTokens withdrawalTokens := g.Pool * accum / g.TotalValAccum @@ -179,19 +182,22 @@ For delegations (including validator's self-delegation) all fees from fee pool are subject to commission rate from the owner of the validator. ``` -func (dd DelegatorDist) WithdrawalRewards(g Global, vd ValidatorDistribution, +func (dd DelegatorDist) WithdrawRewards(g Global, vd ValidatorDistribution, height int64, totalBonded, vdTokens, totalDelShares, commissionRate Dec) (g Global, withdrawn Dec) vd.UpdateTotalDelAccum(height, totalDelShares) g = vd.TakeAccum(g, height, totalBonded, vdTokens) blocks = height - dd.WithdrawalHeight + dd.WithdrawalHeight = height accum = delegatorShares * blocks * (1 - commissionRate) - withdrawalTokens := vd.Pool * accum / cd.TotalDelAccum + withdrawalTokens := vd.Pool * accum / vd.TotalDelAccum + vd.TotalDelAccum -= accum + vd.Pool -= withdrawalTokens vd.TotalDelAccum -= accum - return withdrawalTokens + return g, withdrawalTokens ``` @@ -201,18 +207,21 @@ Similar to a delegator's entitlement, but with recipient shares based on the commission portion of bonded tokens. ``` -func (dd DelegatorDist) WithdrawalCommission(g Global, vd ValidatorDistribution, - height int64, totalBonded, vdTokens, totalDelShares, commissionRate Dec) g Global +func (vd ValidatorDist) WithdrawCommission(g Global, vd ValidatorDistribution, + height int64, totalBonded, vdTokens, totalDelShares, commissionRate Dec) (g Global, withdrawn Dec) vd.UpdateTotalDelAccum(height, totalDelShares) g = vd.TakeAccum(g, height, totalBonded, vdTokens) blocks = height - vd.CommissionWithdrawalHeight + vd.CommissionWithdrawalHeight = height accum = delegatorShares * blocks * (commissionRate) - withdrawalTokens := vd.Pool * accum / cd.TotalDelAccum + withdrawalTokens := vd.Pool * accum / vd.TotalDelAccum + vd.TotalDelAccum -= accum vd.Pool -= withdrawalTokens vd.TotalDelAccum -= accum + return g, withdrawalTokens ``` From 5ef0f5d70ea2cc62c28d3ddfd8ba06f7e0e1b547 Mon Sep 17 00:00:00 2001 From: rigelrozanski Date: Wed, 15 Aug 2018 23:33:26 -0400 Subject: [PATCH 11/18] finalize txs --- docs/spec/distribution/transactions.md | 122 ++++++++----------------- 1 file changed, 39 insertions(+), 83 deletions(-) diff --git a/docs/spec/distribution/transactions.md b/docs/spec/distribution/transactions.md index 4e8ad92e4..fbae152eb 100644 --- a/docs/spec/distribution/transactions.md +++ b/docs/spec/distribution/transactions.md @@ -2,124 +2,80 @@ ## TxWithdrawDelegation -When a delegator wishes to withdraw their transaction fees it must send +When a delegator wishes to withdraw their rewards it must send `TxWithdrawDelegation`. 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. -Each time a withdrawal is made by a recipient the adjustment term must be -modified for each block with a change in distributors shares since the time of -last withdrawal. This is accomplished by iterating over all relevant -`ValidatorUpdate`'s stored in distribution state. - - ```golang type TxWithdrawDelegation struct { delegatorAddr sdk.AccAddress withdrawAddr sdk.AccAddress // address to make the withdrawal to } -func WithdrawDelegator(delegatorAddr, withdrawAddr sdk.AccAddress) - entitlement = GetDelegatorEntitlement(delegatorAddr) +func WithdrawFromDelegator(delegatorAddr, withdrawAddr sdk.AccAddress) + height = GetHeight() + withdraw = GetDelegatorAllWithdraws(delegatorAddr, height) AddCoins(withdrawAddr, totalEntitlment.TruncateDecimal()) -func GetDelegatorEntitlement(delegatorAddr sdk.AccAddress) DecCoins +func GetDelegatorAllWithdraws(delegatorAddr sdk.AccAddress, height int64) DecCoins - // compile all the distribution scenarios + // get all distribution scenarios delegations = GetDelegations(delegatorAddr) - DelDistr = GetDelegationDistribution(delegation.DelegatorAddr, - delegation.ValidatorAddr) - vus = GetValidatorUpdates(DelDistr.WithdrawalHeight) - // update all adjustment factors for each delegation since last withdrawal - for vu = range vus - for delegation = range delegations - DelDistr = GetDelegationDistribution(delegation.DelegatorAddr, - delegation.ValidatorAddr) - vu.ProcessPowerChangeDelegation(delegation, DelDistr) - - // collect all entitled fees - entitlement = 0 + // collect all entitled rewards + withdraw = 0 + pool = stake.GetPool() + global = GetGlobal() for delegation = range delegations - global = GetGlobal() - pool = GetPool() - DelDistr = GetDelegationDistribution(delegation.DelegatorAddr, + delDistr = GetDelegationDistribution(delegation.DelegatorAddr, delegation.ValidatorAddr) - ValDistr = GetValidatorDistribution(delegation.ValidatorAddr) + valDistr = GetValidatorDistribution(delegation.ValidatorAddr) validator = GetValidator(delegation.ValidatorAddr) - scenerio1 = NewDelegationFromGlobalPool(delegation, validator, - pool, global, ValDistr, DelDistr) - scenerio2 = NewDelegationFromProvisionPool(delegation, validator, - ValDistr, DelDistr) - entitlement += scenerio1.WithdrawalEntitlement() - entitlement += scenerio2.WithdrawalEntitlement() - - return entitlement + global, ddWithdraw = delDistr.WithdrawRewards(global, valDistr, height, pool.BondedTokens, + validator.Tokens, validator.DelegatorShares, validator.Commission) + withdraw += ddWithdraw -func (vu ValidatorUpdate) ProcessPowerChangeDelegation(delegation sdk.Delegation, - DelDistr DelegationDistribution) - - // get the historical scenarios - scenario1 = vu.DelegationFromGlobalPool(delegation, DelDistr) - scenario2 = vu.DelegationFromProvisionPool(delegation, DelDistr) - - // process the adjustment factors - scenario1.UpdateAdjustmentForPowerChange(vu.Height) - scenario2.UpdateAdjustmentForPowerChange(vu.Height) + SetGlobal(global) + return withdraw ``` ## TxWithdrawValidator -When a validator wishes to withdraw their transaction fees it must send +When a validator wishes to withdraw their rewards it must send `TxWithdrawDelegation`. Note that parts of this transaction logic is 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 rewards, as well as any rewards +transaction withdraws the validators commission fee, as well as any rewards earning on their self-delegation. ``` type TxWithdrawValidator struct { - ownerAddr sdk.AccAddress // validator address to withdraw from + operatorAddr sdk.AccAddress // validator address to withdraw from withdrawAddr sdk.AccAddress // address to make the withdrawal to } -func WithdrawalValidator(ownerAddr, withdrawAddr sdk.AccAddress) +func WithdrawFromValidator(operatorAddr, withdrawAddr sdk.AccAddress) - // update the delegator adjustment factors and also withdrawal delegation fees - entitlement = GetDelegatorEntitlement(ownerAddr) - - // update the validator adjustment factors for commission - ValDistr = GetValidatorDistribution(ownerAddr.ValidatorAddr) - vus = GetValidatorUpdates(ValDistr.CommissionWithdrawalHeight) - for vu = range vus - vu.ProcessPowerChangeCommission() - - // withdrawal validator commission rewards + height = GetHeight() global = GetGlobal() pool = GetPool() ValDistr = GetValidatorDistribution(delegation.ValidatorAddr) validator = GetValidator(delegation.ValidatorAddr) - scenerio1 = NewCommissionFromGlobalPool(validator, - pool, global, ValDistr) - scenerio2 = CommissionFromProposerPool(validator, ValDistr) - entitlement += scenerio1.WithdrawalEntitlement() - entitlement += scenerio2.WithdrawalEntitlement() - + // withdraw self-delegation + withdraw = GetDelegatorAllWithdraws(validator.OperatorAddr, height) + + // withdrawal validator commission rewards + global, commission = valDistr.WithdrawCommission(global, valDistr, height, pool.BondedTokens, + validator.Tokens, validator.DelegatorShares, validator.Commission) + withdraw += commission + SetGlobal(global) + AddCoins(withdrawAddr, totalEntitlment.TruncateDecimal()) - -func (vu ValidatorUpdate) ProcessPowerChangeCommission() - - // get the historical scenarios - scenario1 = vu.CommissionFromGlobalPool() - scenario2 = vu.CommissionFromProposerPool() - - // process the adjustment factors - scenario1.UpdateAdjustmentForPowerChange(vu.Height) - scenario2.UpdateAdjustmentForPowerChange(vu.Height) ``` - + ## Common calculations ### Update total validator accum @@ -153,9 +109,9 @@ func (vd ValidatorDistribution) UpdateTotalDelAccum(height int64, totalDelShares ### Global pool to validator pool -Everytime a validator or delegator make a withdraw or the validator is the -proposer and receives new tokens - the relavent validator must move tokens from -the passive global pool to thier own 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 +the passive global pool to their own pool. ``` func (vd ValidatorDistribution) TakeAccum(g Global, height int64, totalBonded, vdTokens Dec) g Global @@ -178,12 +134,12 @@ func (vd ValidatorDistribution) TakeAccum(g Global, height int64, totalBonded, v ### Delegation's withdrawal -For delegations (including validator's self-delegation) all fees from fee pool -are subject to commission rate from the owner of the validator. +For delegations (including validator's self-delegation) all rewards from reward pool +are subject to commission rate from the operator of the validator. ``` func (dd DelegatorDist) WithdrawRewards(g Global, vd ValidatorDistribution, - height int64, totalBonded, vdTokens, totalDelShares, commissionRate Dec) (g Global, withdrawn Dec) + height int64, totalBonded, vdTokens, totalDelShares, commissionRate Dec) (g Global, withdrawn DecCoins) vd.UpdateTotalDelAccum(height, totalDelShares) g = vd.TakeAccum(g, height, totalBonded, vdTokens) @@ -208,7 +164,7 @@ commission portion of bonded tokens. ``` func (vd ValidatorDist) WithdrawCommission(g Global, vd ValidatorDistribution, - height int64, totalBonded, vdTokens, totalDelShares, commissionRate Dec) (g Global, withdrawn Dec) + height int64, totalBonded, vdTokens, totalDelShares, commissionRate Dec) (g Global, withdrawn DecCoins) vd.UpdateTotalDelAccum(height, totalDelShares) g = vd.TakeAccum(g, height, totalBonded, vdTokens) From 8fc9b95929a48a538c2f320d3eedeebf94082cc0 Mon Sep 17 00:00:00 2001 From: rigelrozanski Date: Wed, 15 Aug 2018 23:49:07 -0400 Subject: [PATCH 12/18] pending --- PENDING.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/PENDING.md b/PENDING.md index 6cc6ce10c..c0971cf80 100644 --- a/PENDING.md +++ b/PENDING.md @@ -63,6 +63,7 @@ IMPROVEMENTS * [tests] \#1806 CLI tests are now behind the build flag 'cli_test', so go test works on a new repo * [x/gov] Initial governance parameters can now be set in the genesis file * [x/stake] \#1815 Sped up the processing of `EditValidator` txs. +* [spec] Added simple piggy bank distribution spec BUG FIXES * \#1666 Add intra-tx counter to the genesis validators @@ -85,4 +86,4 @@ BUG FIXES * \#1666 Add intra-tx counter to the genesis validators * [tests] \#1551: Fixed invalid LCD test JSON payload in `doIBCTransfer` * \#1787 Fixed bug where Tally fails due to revoked/unbonding validator -* [basecoin] Fixes coin transaction failure and account query [discussion](https://forum.cosmos.network/t/unmarshalbinarybare-expected-to-read-prefix-bytes-75fbfab8-since-it-is-registered-concrete-but-got-0a141dfa/664/6) \ No newline at end of file +* [basecoin] Fixes coin transaction failure and account query [discussion](https://forum.cosmos.network/t/unmarshalbinarybare-expected-to-read-prefix-bytes-75fbfab8-since-it-is-registered-concrete-but-got-0a141dfa/664/6) From 3c564c01b911e51f2428452b3489b3303ac14b9c Mon Sep 17 00:00:00 2001 From: rigelrozanski Date: Thu, 16 Aug 2018 16:41:32 -0400 Subject: [PATCH 13/18] clearer names, missing commission logic --- docs/spec/distribution/state.md | 14 ++--- docs/spec/distribution/transactions.md | 83 ++++++++++++++------------ docs/spec/distribution/triggers.md | 4 +- 3 files changed, 55 insertions(+), 46 deletions(-) diff --git a/docs/spec/distribution/state.md b/docs/spec/distribution/state.md index 115782594..83e82f494 100644 --- a/docs/spec/distribution/state.md +++ b/docs/spec/distribution/state.md @@ -38,10 +38,10 @@ Validator distribution information for the relevant validator is updated each ti 3. any delegator withdraws from a validator, or 4. the validator withdraws it's commission. - - ValidatorDistribution: `0x02 | ValOwnerAddr -> amino(validatorDistribution)` + - ValidatorDistInfo: `0x02 | ValOperatorAddr -> amino(validatorDistribution)` ```golang -type ValidatorDistribution struct { +type ValidatorDistInfo struct { CommissionWithdrawalHeight int64 // last height this validator withdrew commission GlobalWithdrawalHeight int64 // last height this validator withdrew from the global pool @@ -60,10 +60,10 @@ 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)` + - DelegatorDistInfo: ` 0x02 | DelegatorAddr | ValOperatorAddr -> amino(delegatorDist)` ```golang -type DelegatorDist struct { +type DelegatorDistInfo struct { WithdrawalHeight int64 // last time this delegation withdrew rewards } ``` @@ -76,14 +76,14 @@ Every instance that a validator: - is slashed, or - changes its commission rate, -information about the state change must be recorded as a `ValidatorUpdate`. +information about the state change to each validator must be recorded as a `ValidatorUpdate`. Each power change is indexed by validator and its block height. - - ValidatorUpdate: `0x03 | ValOwnerAddr | amino(Height) -> amino(ValidatorUpdate)` + - ValidatorUpdate: `0x03 | ValOperatorAddr | amino(Height) -> amino(ValidatorUpdate)` ```golang type ValidatorUpdate struct { Height int64 // block height of update - NewCommissionRate sdk.Dec // commission rate at this height + OldCommissionRate sdk.Dec // commission rate at this height } ``` diff --git a/docs/spec/distribution/transactions.md b/docs/spec/distribution/transactions.md index fbae152eb..364346ff4 100644 --- a/docs/spec/distribution/transactions.md +++ b/docs/spec/distribution/transactions.md @@ -8,12 +8,12 @@ triggered each with any change in individual delegations, such as an unbond, redelegation, or delegation of additional tokens to a specific validator. ```golang -type TxWithdrawDelegation struct { +type TxWithdrawDelegationRewards struct { delegatorAddr sdk.AccAddress withdrawAddr sdk.AccAddress // address to make the withdrawal to } -func WithdrawFromDelegator(delegatorAddr, withdrawAddr sdk.AccAddress) +func WithdrawDelegationRewards(delegatorAddr, withdrawAddr sdk.AccAddress) height = GetHeight() withdraw = GetDelegatorAllWithdraws(delegatorAddr, height) AddCoins(withdrawAddr, totalEntitlment.TruncateDecimal()) @@ -28,14 +28,23 @@ func GetDelegatorAllWithdraws(delegatorAddr sdk.AccAddress, height int64) DecCoi pool = stake.GetPool() global = GetGlobal() for delegation = range delegations - delDistr = GetDelegationDistribution(delegation.DelegatorAddr, + delInfo = GetDelegationDistInfo(delegation.DelegatorAddr, delegation.ValidatorAddr) - valDistr = GetValidatorDistribution(delegation.ValidatorAddr) + valInfo = GetValidatorDistInfo(delegation.ValidatorAddr) validator = GetValidator(delegation.ValidatorAddr) - global, ddWithdraw = delDistr.WithdrawRewards(global, valDistr, height, pool.BondedTokens, + // get all commission rate changes since last withdraw + vus = GetValidatorUpdates(delegation.ValidatorAddr, delInfo.WithdrawalHeight) + + for vu = range vus { + global, diWithdraw = delInfo.WithdrawRewards(global, valInfo, vu.Height, pool.BondedTokens, + validator.Tokens, validator.DelegatorShares, vu.OldCommissionRate) + withdraw += diWithdraw + } + + global, diWithdraw = delInfo.WithdrawRewards(global, valInfo, height, pool.BondedTokens, validator.Tokens, validator.DelegatorShares, validator.Commission) - withdraw += ddWithdraw + withdraw += diWithdraw SetGlobal(global) return withdraw @@ -51,24 +60,24 @@ transaction withdraws the validators commission fee, as well as any rewards earning on their self-delegation. ``` -type TxWithdrawValidator struct { +type TxWithdrawValidatorRewards struct { operatorAddr sdk.AccAddress // validator address to withdraw from withdrawAddr sdk.AccAddress // address to make the withdrawal to } -func WithdrawFromValidator(operatorAddr, withdrawAddr sdk.AccAddress) +func WithdrawValidatorRewards(operatorAddr, withdrawAddr sdk.AccAddress) height = GetHeight() global = GetGlobal() pool = GetPool() - ValDistr = GetValidatorDistribution(delegation.ValidatorAddr) + ValInfo = GetValidatorDistInfo(delegation.ValidatorAddr) validator = GetValidator(delegation.ValidatorAddr) // withdraw self-delegation withdraw = GetDelegatorAllWithdraws(validator.OperatorAddr, height) // withdrawal validator commission rewards - global, commission = valDistr.WithdrawCommission(global, valDistr, height, pool.BondedTokens, + global, commission = valInfo.WithdrawCommission(global, valInfo, height, pool.BondedTokens, validator.Tokens, validator.DelegatorShares, validator.Commission) withdraw += commission SetGlobal(global) @@ -101,10 +110,10 @@ the existing accum. This term is to be updated each time a withdrawal is made from a validator. ``` -func (vd ValidatorDistribution) UpdateTotalDelAccum(height int64, totalDelShares Dec) - blocks = height - vd.TotalDelAccumUpdateHeight - vd.TotalDelAccum += totalDelShares * blocks - vd.TotalDelAccumUpdateHeight = height +func (vi ValidatorDistInfo) UpdateTotalDelAccum(height int64, totalDelShares Dec) + blocks = height - vi.TotalDelAccumUpdateHeight + vi.TotalDelAccum += totalDelShares * blocks + vi.TotalDelAccumUpdateHeight = height ``` ### Global pool to validator pool @@ -114,18 +123,18 @@ proposer and receives new tokens - the relevant validator must move tokens from the passive global pool to their own pool. ``` -func (vd ValidatorDistribution) TakeAccum(g Global, height int64, totalBonded, vdTokens Dec) g Global +func (vi ValidatorDistInfo) TakeAccum(g Global, height int64, totalBonded, vdTokens Dec) g Global g.UpdateTotalValAccum(height, totalBondedShares) g.UpdateValAccum(height, totalBondedShares) // update the validators pool - blocks = height - vd.GlobalWithdrawalHeight - vd.GlobalWithdrawalHeight = height + blocks = height - vi.GlobalWithdrawalHeight + vi.GlobalWithdrawalHeight = height accum = blocks * vdTokens withdrawalTokens := g.Pool * accum / g.TotalValAccum g.TotalValAccum -= accumm - vd.Pool += withdrawalTokens + vi.Pool += withdrawalTokens g.Pool -= withdrawalTokens return g @@ -138,21 +147,21 @@ For delegations (including validator's self-delegation) all rewards from reward are subject to commission rate from the operator of the validator. ``` -func (dd DelegatorDist) WithdrawRewards(g Global, vd ValidatorDistribution, +func (di DelegatorDistInfo) WithdrawRewards(g Global, vi ValidatorDistInfo, height int64, totalBonded, vdTokens, totalDelShares, commissionRate Dec) (g Global, withdrawn DecCoins) - vd.UpdateTotalDelAccum(height, totalDelShares) - g = vd.TakeAccum(g, height, totalBonded, vdTokens) + vi.UpdateTotalDelAccum(height, totalDelShares) + g = vi.TakeAccum(g, height, totalBonded, vdTokens) - blocks = height - dd.WithdrawalHeight - dd.WithdrawalHeight = height + blocks = height - di.WithdrawalHeight + di.WithdrawalHeight = height accum = delegatorShares * blocks * (1 - commissionRate) - withdrawalTokens := vd.Pool * accum / vd.TotalDelAccum - vd.TotalDelAccum -= accum + withdrawalTokens := vi.Pool * accum / vi.TotalDelAccum + vi.TotalDelAccum -= accum - vd.Pool -= withdrawalTokens - vd.TotalDelAccum -= accum + vi.Pool -= withdrawalTokens + vi.TotalDelAccum -= accum return g, withdrawalTokens ``` @@ -163,21 +172,21 @@ Similar to a delegator's entitlement, but with recipient shares based on the commission portion of bonded tokens. ``` -func (vd ValidatorDist) WithdrawCommission(g Global, vd ValidatorDistribution, - height int64, totalBonded, vdTokens, totalDelShares, commissionRate Dec) (g Global, withdrawn DecCoins) +func (vi ValidatorDistInfo) WithdrawCommission(g Global, height int64, + totalBonded, vdTokens, totalDelShares, commissionRate Dec) (g Global, withdrawn DecCoins) - vd.UpdateTotalDelAccum(height, totalDelShares) - g = vd.TakeAccum(g, height, totalBonded, vdTokens) + vi.UpdateTotalDelAccum(height, totalDelShares) + g = vi.TakeAccum(g, height, totalBonded, vdTokens) - blocks = height - vd.CommissionWithdrawalHeight - vd.CommissionWithdrawalHeight = height + blocks = height - vi.CommissionWithdrawalHeight + vi.CommissionWithdrawalHeight = height accum = delegatorShares * blocks * (commissionRate) - withdrawalTokens := vd.Pool * accum / vd.TotalDelAccum - vd.TotalDelAccum -= accum + withdrawalTokens := vi.Pool * accum / vi.TotalDelAccum + vi.TotalDelAccum -= accum - vd.Pool -= withdrawalTokens - vd.TotalDelAccum -= accum + vi.Pool -= withdrawalTokens + vi.TotalDelAccum -= accum return g, withdrawalTokens ``` diff --git a/docs/spec/distribution/triggers.md b/docs/spec/distribution/triggers.md index 0e02f0431..2938e674f 100644 --- a/docs/spec/distribution/triggers.md +++ b/docs/spec/distribution/triggers.md @@ -6,7 +6,7 @@ The pool of a new delegator bond will be 0 for the height at which the bond was added, or the withdrawal has taken place. This is achieved by setting -`DelegatorDist.WithdrawalHeight` to the height of the triggering transaction. +`DelegatorDistInfo.WithdrawalHeight` to the height of the triggering transaction. ## Commission rate change @@ -23,4 +23,4 @@ Additionally the change and associated height must be recorded in a 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 `ValidatorDistribution.Pool` +`Global.Pool` and added to `ValidatorDistInfo.Pool` From 6e3e57e23e695680d8414509072c51abe1dccde9 Mon Sep 17 00:00:00 2001 From: Christopher Goes Date: Mon, 20 Aug 2018 17:50:13 +0200 Subject: [PATCH 14/18] Typos; tiny wording changes --- docs/spec/distribution/overview.md | 36 ++++++++++++-------------- docs/spec/distribution/state.md | 2 +- docs/spec/distribution/transactions.md | 14 +++++----- docs/spec/distribution/triggers.md | 4 +-- 4 files changed, 26 insertions(+), 30 deletions(-) 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`. From b32285ec3b11aea53beb79d5fcd4c2488881d038 Mon Sep 17 00:00:00 2001 From: rigelrozanski Date: Thu, 23 Aug 2018 03:19:21 -0400 Subject: [PATCH 15/18] commission actively calculated, withdrawDelegationReward Tx --- docs/spec/distribution/end_block.md | 12 ++-- docs/spec/distribution/state.md | 25 +------ docs/spec/distribution/transactions.md | 92 +++++++++++++++----------- 3 files changed, 64 insertions(+), 65 deletions(-) diff --git a/docs/spec/distribution/end_block.md b/docs/spec/distribution/end_block.md index 19c9e8302..952d1832a 100644 --- a/docs/spec/distribution/end_block.md +++ b/docs/spec/distribution/end_block.md @@ -1,6 +1,6 @@ # End Block -At each endblock, the fees received are sorted to the proposer, community fund, +At each endblock, the fees received are allocated 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 community tax is then charged, then the remainder is distributed @@ -15,13 +15,17 @@ pool which validator holds individually (`ValidatorDistribution.ProvisionsRewardPool`). ``` -func SortFees(feesCollected sdk.Coins, global Global, proposer ValidatorDistribution, - sumPowerPrecommitValidators, totalBondedTokens, communityTax sdk.Dec) +func AllocateFees(feesCollected sdk.Coins, global Global, proposer ValidatorDistribution, + sumPowerPrecommitValidators, totalBondedTokens, communityTax, + proposerCommissionRate sdk.Dec) feesCollectedDec = MakeDecCoins(feesCollected) proposerReward = feesCollectedDec * (0.01 + 0.04 * sumPowerPrecommitValidators / totalBondedTokens) - proposer.ProposerPool += proposerReward + + commission = proposerReward * proposerCommissionRate + proposer.PoolCommission += commission + proposer.Pool += proposerReward - commission communityFunding = feesCollectedDec * communityTax global.CommunityFund += communityFunding diff --git a/docs/spec/distribution/state.md b/docs/spec/distribution/state.md index 7dc011e95..3e3669789 100644 --- a/docs/spec/distribution/state.md +++ b/docs/spec/distribution/state.md @@ -42,10 +42,9 @@ Validator distribution information for the relevant validator is updated each ti ```golang type ValidatorDistInfo 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) + Pool DecCoins // rewards owed to delegators, commission has already been charged (includes proposer reward) + PoolCommission DecCoins // commission collected by this validator (pending withdrawal) TotalDelAccumUpdateHeight int64 // last height which the total delegator accum was updated TotalDelAccum sdk.Dec // total proposer pool accumulation factor held by delegators @@ -67,23 +66,3 @@ type DelegatorDistInfo 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 to each validator must be recorded as a `ValidatorUpdate`. -Each power change is indexed by validator and its block height. - - - ValidatorUpdate: `0x03 | ValOperatorAddr | amino(Height) -> amino(ValidatorUpdate)` - -```golang -type ValidatorUpdate struct { - Height int64 // block height of update - OldCommissionRate sdk.Dec // commission rate at this height -} -``` diff --git a/docs/spec/distribution/transactions.md b/docs/spec/distribution/transactions.md index 82f9e84f7..2ed12d2c3 100644 --- a/docs/spec/distribution/transactions.md +++ b/docs/spec/distribution/transactions.md @@ -1,9 +1,9 @@ # Transactions -## TxWithdrawDelegation +## TxWithdrawDelegationRewards When a delegator wishes to withdraw their rewards it must send -`TxWithdrawDelegation`. Note that parts of this transaction logic are also +`TxWithdrawDelegationRewards`. 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. @@ -16,7 +16,7 @@ type TxWithdrawDelegationRewards struct { func WithdrawDelegationRewards(delegatorAddr, withdrawAddr sdk.AccAddress) height = GetHeight() withdraw = GetDelegatorAllWithdraws(delegatorAddr, height) - AddCoins(withdrawAddr, totalEntitlment.TruncateDecimal()) + AddCoins(withdrawAddr, withdraw.TruncateDecimal()) func GetDelegatorAllWithdraws(delegatorAddr sdk.AccAddress, height int64) DecCoins @@ -33,15 +33,6 @@ func GetDelegatorAllWithdraws(delegatorAddr sdk.AccAddress, height int64) DecCoi valInfo = GetValidatorDistInfo(delegation.ValidatorAddr) validator = GetValidator(delegation.ValidatorAddr) - // get all commission rate changes since last withdraw - vus = GetValidatorUpdates(delegation.ValidatorAddr, delInfo.WithdrawalHeight) - - for vu = range vus { - global, diWithdraw = delInfo.WithdrawRewards(global, valInfo, vu.Height, pool.BondedTokens, - validator.Tokens, validator.DelegatorShares, vu.OldCommissionRate) - withdraw += diWithdraw - } - global, diWithdraw = delInfo.WithdrawRewards(global, valInfo, height, pool.BondedTokens, validator.Tokens, validator.DelegatorShares, validator.Commission) withdraw += diWithdraw @@ -50,7 +41,38 @@ func GetDelegatorAllWithdraws(delegatorAddr sdk.AccAddress, height int64) DecCoi return withdraw ``` -## TxWithdrawValidator +## TxWithdrawDelegationReward + +under special circumstances a delegator may wish to withdraw rewards from only +a single validator. + +```golang +type TxWithdrawDelegationReward struct { + delegatorAddr sdk.AccAddress + validatorAddr sdk.AccAddress + withdrawAddr sdk.AccAddress // address to make the withdrawal to +} + +func WithdrawDelegationReward(delegatorAddr, validatorAddr, withdrawAddr sdk.AccAddress) + height = GetHeight() + + // get all distribution scenarios + pool = stake.GetPool() + global = GetGlobal() + delInfo = GetDelegationDistInfo(delegatorAddr, + validatorAddr) + valInfo = GetValidatorDistInfo(validatorAddr) + validator = GetValidator(validatorAddr) + + global, withdraw = delInfo.WithdrawRewards(global, valInfo, height, pool.BondedTokens, + validator.Tokens, validator.DelegatorShares, validator.Commission) + + SetGlobal(global) + AddCoins(withdrawAddr, withdraw.TruncateDecimal()) +``` + + +## TxWithdrawValidatorRewards When a validator wishes to withdraw their rewards it must send `TxWithdrawValidatorRewards`. Note that parts of this transaction logic are also @@ -78,11 +100,11 @@ func WithdrawValidatorRewards(operatorAddr, withdrawAddr sdk.AccAddress) // withdrawal validator commission rewards global, commission = valInfo.WithdrawCommission(global, valInfo, height, pool.BondedTokens, - validator.Tokens, validator.DelegatorShares, validator.Commission) + validator.Tokens, validator.Commission) withdraw += commission SetGlobal(global) - AddCoins(withdrawAddr, totalEntitlment.TruncateDecimal()) + AddCoins(withdrawAddr, withdraw.TruncateDecimal()) ``` ## Common calculations @@ -118,12 +140,13 @@ func (vi ValidatorDistInfo) UpdateTotalDelAccum(height int64, totalDelShares Dec ### Global pool to validator pool -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. +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. It is at this point that the +commission is withdrawn ``` -func (vi ValidatorDistInfo) TakeAccum(g Global, height int64, totalBonded, vdTokens Dec) g Global +func (vi ValidatorDistInfo) TakeAccum(g Global, height int64, totalBonded, vdTokens, commissionRate Dec) g Global g.UpdateTotalValAccum(height, totalBondedShares) g.UpdateValAccum(height, totalBondedShares) @@ -132,9 +155,11 @@ func (vi ValidatorDistInfo) TakeAccum(g Global, height int64, totalBonded, vdTok vi.GlobalWithdrawalHeight = height accum = blocks * vdTokens withdrawalTokens := g.Pool * accum / g.TotalValAccum + commission := withdrawalTokens * commissionRate g.TotalValAccum -= accumm - vi.Pool += withdrawalTokens + vi.PoolCommission += commission + vi.PoolCommissionFree += withdrawalTokens - commission g.Pool -= withdrawalTokens return g @@ -143,19 +168,19 @@ func (vi ValidatorDistInfo) TakeAccum(g Global, height int64, totalBonded, vdTok ### 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. +For delegations (including validator's self-delegation) all rewards from reward +pool have already had the validator's commission taken away. ``` func (di DelegatorDistInfo) WithdrawRewards(g Global, vi ValidatorDistInfo, height int64, totalBonded, vdTokens, totalDelShares, commissionRate Dec) (g Global, withdrawn DecCoins) vi.UpdateTotalDelAccum(height, totalDelShares) - g = vi.TakeAccum(g, height, totalBonded, vdTokens) + g = vi.TakeAccum(g, height, totalBonded, vdTokens, commissionRate) blocks = height - di.WithdrawalHeight di.WithdrawalHeight = height - accum = delegatorShares * blocks * (1 - commissionRate) + accum = delegatorShares * blocks withdrawalTokens := vi.Pool * accum / vi.TotalDelAccum vi.TotalDelAccum -= accum @@ -168,25 +193,16 @@ func (di DelegatorDistInfo) WithdrawRewards(g Global, vi ValidatorDistInfo, ### Validator commission withdrawal -Similar to a delegator's entitlement, but with recipient shares based on the -commission portion of bonded tokens. +Commission is calculated each time rewards enter into the validator. ``` func (vi ValidatorDistInfo) WithdrawCommission(g Global, height int64, - totalBonded, vdTokens, totalDelShares, commissionRate Dec) (g Global, withdrawn DecCoins) + totalBonded, vdTokens, commissionRate Dec) (g Global, withdrawn DecCoins) - vi.UpdateTotalDelAccum(height, totalDelShares) - g = vi.TakeAccum(g, height, totalBonded, vdTokens) + g = vi.TakeAccum(g, height, totalBonded, vdTokens, commissionRate) - blocks = height - vi.CommissionWithdrawalHeight - vi.CommissionWithdrawalHeight = height - accum = delegatorShares * blocks * (commissionRate) - - withdrawalTokens := vi.Pool * accum / vi.TotalDelAccum - vi.TotalDelAccum -= accum - - vi.Pool -= withdrawalTokens - vi.TotalDelAccum -= accum + withdrawalTokens := vi.PoolCommission + vi.PoolCommission = 0 return g, withdrawalTokens ``` From cce4cbc9ec9bac54dc4d8b214b7efee585034ffc Mon Sep 17 00:00:00 2001 From: rigelrozanski Date: Thu, 23 Aug 2018 04:02:26 -0400 Subject: [PATCH 16/18] expand on shortcomings of the system --- docs/spec/distribution/overview.md | 30 +++++++++++++++++++++--------- 1 file changed, 21 insertions(+), 9 deletions(-) diff --git a/docs/spec/distribution/overview.md b/docs/spec/distribution/overview.md index 7b912f282..e4308a21d 100644 --- a/docs/spec/distribution/overview.md +++ b/docs/spec/distribution/overview.md @@ -36,20 +36,32 @@ 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 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 -of tokens held in the global pool is owed to them. This approximation of owed -rewards would be equivalent to the active distribution under the situation that -there was a constant flow of incoming reward tokens every block. Because this -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. +## Shortcomings + +As a part of the lazy computations, each delegator holds an accumulation term +specific to each validator which is used to estimate what their approximate +fair portion of tokens held in the global pool is owed to them. + +``` +entitlement = delegator-accumulation / all-delegators-accumulation +``` + +Under the circumstance that there were constant and equal flow of incoming +reward tokens every block, this distribution mechanism would be equal to the +active distribution (distribute individually to all delegators each block). +However this is unrealistic so deviations from the active distribution will +occur based on fluctuations of incoming reward tokens as well as timing of +reward withdrawal by other delegators. + +If you happen to know that incoming rewards are about significantly move up, +you are incentivized to not withdraw until after this event, increasing the +worth of your existing _accum_. ## 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 +problematic within DPoS. Fundamentally these two mechanisms 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 From 222597165e5ae84936da4d3393a7a39d7845173d Mon Sep 17 00:00:00 2001 From: rigelrozanski Date: Tue, 28 Aug 2018 18:23:57 -0400 Subject: [PATCH 17/18] trigger -> hooks --- docs/spec/distribution/{triggers.md => hooks.md} | 2 +- docs/spec/distribution/overview.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) rename docs/spec/distribution/{triggers.md => hooks.md} (98%) diff --git a/docs/spec/distribution/triggers.md b/docs/spec/distribution/hooks.md similarity index 98% rename from docs/spec/distribution/triggers.md rename to docs/spec/distribution/hooks.md index e3971ea99..e1a18ef59 100644 --- a/docs/spec/distribution/triggers.md +++ b/docs/spec/distribution/hooks.md @@ -1,4 +1,4 @@ -# Triggers +# Hooks ## Create or modify delegation distribution diff --git a/docs/spec/distribution/overview.md b/docs/spec/distribution/overview.md index e4308a21d..13a4ea3f1 100644 --- a/docs/spec/distribution/overview.md +++ b/docs/spec/distribution/overview.md @@ -23,7 +23,7 @@ distribution occurs, withdrawal of rewards must also occur. - 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`. +The above scenarios are covered in `hooks.md`. The distribution mechanism outlines herein is used to lazily distribute the following rewards between validators and associated delegators: From 5c600f2e2b66884723892ba53a0d6f780e2364fe Mon Sep 17 00:00:00 2001 From: rigelrozanski Date: Mon, 3 Sep 2018 15:49:36 -0400 Subject: [PATCH 18/18] jae comments --- docs/spec/distribution/transactions.md | 45 ++++++++++++++------------ 1 file changed, 25 insertions(+), 20 deletions(-) diff --git a/docs/spec/distribution/transactions.md b/docs/spec/distribution/transactions.md index 2ed12d2c3..0b89ae44e 100644 --- a/docs/spec/distribution/transactions.md +++ b/docs/spec/distribution/transactions.md @@ -1,24 +1,24 @@ # Transactions -## TxWithdrawDelegationRewards +## TxWithdrawDelegationRewardsAll When a delegator wishes to withdraw their rewards it must send -`TxWithdrawDelegationRewards`. Note that parts of this transaction logic are also +`TxWithdrawDelegationRewardsAll`. 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. ```golang -type TxWithdrawDelegationRewards struct { +type TxWithdrawDelegationRewardsAll struct { delegatorAddr sdk.AccAddress withdrawAddr sdk.AccAddress // address to make the withdrawal to } -func WithdrawDelegationRewards(delegatorAddr, withdrawAddr sdk.AccAddress) +func WithdrawDelegationRewardsAll(delegatorAddr, withdrawAddr sdk.AccAddress) height = GetHeight() - withdraw = GetDelegatorAllWithdraws(delegatorAddr, height) + withdraw = GetDelegatorRewardsAll(delegatorAddr, height) AddCoins(withdrawAddr, withdraw.TruncateDecimal()) -func GetDelegatorAllWithdraws(delegatorAddr sdk.AccAddress, height int64) DecCoins +func GetDelegatorRewardsAll(delegatorAddr sdk.AccAddress, height int64) DecCoins // get all distribution scenarios delegations = GetDelegations(delegatorAddr) @@ -72,22 +72,22 @@ func WithdrawDelegationReward(delegatorAddr, validatorAddr, withdrawAddr sdk.Acc ``` -## TxWithdrawValidatorRewards +## TxWithdrawValidatorRewardsAll When a validator wishes to withdraw their rewards it must send -`TxWithdrawValidatorRewards`. Note that parts of this transaction logic are also +`TxWithdrawValidatorRewardsAll`. 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 earning on their self-delegation. ``` -type TxWithdrawValidatorRewards struct { +type TxWithdrawValidatorRewardsAll struct { operatorAddr sdk.AccAddress // validator address to withdraw from withdrawAddr sdk.AccAddress // address to make the withdrawal to } -func WithdrawValidatorRewards(operatorAddr, withdrawAddr sdk.AccAddress) +func WithdrawValidatorRewardsAll(operatorAddr, withdrawAddr sdk.AccAddress) height = GetHeight() global = GetGlobal() @@ -96,7 +96,7 @@ func WithdrawValidatorRewards(operatorAddr, withdrawAddr sdk.AccAddress) validator = GetValidator(delegation.ValidatorAddr) // withdraw self-delegation - withdraw = GetDelegatorAllWithdraws(validator.OperatorAddr, height) + withdraw = GetDelegatorRewardsAll(validator.OperatorAddr, height) // withdrawal validator commission rewards global, commission = valInfo.WithdrawCommission(global, valInfo, height, pool.BondedTokens, @@ -117,10 +117,11 @@ block. The accum is always additive to the existing accum. This term is to be updated each time rewards are withdrawn from the system. ``` -func (g Global) UpdateTotalValAccum(height int64, totalBondedTokens Dec) +func (g Global) UpdateTotalValAccum(height int64, totalBondedTokens Dec) Global blocks = height - g.TotalValAccumUpdateHeight g.TotalValAccum += totalDelShares * blocks g.TotalValAccumUpdateHeight = height + return g ``` ### Update validator's accums @@ -132,10 +133,11 @@ the existing accum. This term is to be updated each time a withdrawal is made from a validator. ``` -func (vi ValidatorDistInfo) UpdateTotalDelAccum(height int64, totalDelShares Dec) +func (vi ValidatorDistInfo) UpdateTotalDelAccum(height int64, totalDelShares Dec) ValidatorDistInfo blocks = height - vi.TotalDelAccumUpdateHeight vi.TotalDelAccum += totalDelShares * blocks vi.TotalDelAccumUpdateHeight = height + return vi ``` ### Global pool to validator pool @@ -146,9 +148,10 @@ from the passive global pool to their own pool. It is at this point that the commission is withdrawn ``` -func (vi ValidatorDistInfo) TakeAccum(g Global, height int64, totalBonded, vdTokens, commissionRate Dec) g Global +func (vi ValidatorDistInfo) TakeAccum(g Global, height int64, totalBonded, vdTokens, commissionRate Dec) ( + vi ValidatorDistInfo, g Global) + g.UpdateTotalValAccum(height, totalBondedShares) - g.UpdateValAccum(height, totalBondedShares) // update the validators pool blocks = height - vi.GlobalWithdrawalHeight @@ -162,7 +165,7 @@ func (vi ValidatorDistInfo) TakeAccum(g Global, height int64, totalBonded, vdTok vi.PoolCommissionFree += withdrawalTokens - commission g.Pool -= withdrawalTokens - return g + return vi, g ``` @@ -173,7 +176,8 @@ pool have already had the validator's commission taken away. ``` func (di DelegatorDistInfo) WithdrawRewards(g Global, vi ValidatorDistInfo, - height int64, totalBonded, vdTokens, totalDelShares, commissionRate Dec) (g Global, withdrawn DecCoins) + height int64, totalBonded, vdTokens, totalDelShares, commissionRate Dec) ( + di DelegatorDistInfo, g Global, withdrawn DecCoins) vi.UpdateTotalDelAccum(height, totalDelShares) g = vi.TakeAccum(g, height, totalBonded, vdTokens, commissionRate) @@ -187,7 +191,7 @@ func (di DelegatorDistInfo) WithdrawRewards(g Global, vi ValidatorDistInfo, vi.Pool -= withdrawalTokens vi.TotalDelAccum -= accum - return g, withdrawalTokens + return di, g, withdrawalTokens ``` @@ -197,12 +201,13 @@ Commission is calculated each time rewards enter into the validator. ``` func (vi ValidatorDistInfo) WithdrawCommission(g Global, height int64, - totalBonded, vdTokens, commissionRate Dec) (g Global, withdrawn DecCoins) + totalBonded, vdTokens, commissionRate Dec) ( + vi ValidatorDistInfo, g Global, withdrawn DecCoins) g = vi.TakeAccum(g, height, totalBonded, vdTokens, commissionRate) withdrawalTokens := vi.PoolCommission vi.PoolCommission = 0 - return g, withdrawalTokens + return vi, g, withdrawalTokens ```