From 5ef0f5d70ea2cc62c28d3ddfd8ba06f7e0e1b547 Mon Sep 17 00:00:00 2001 From: rigelrozanski Date: Wed, 15 Aug 2018 23:33:26 -0400 Subject: [PATCH] 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)