certusone
/
cosmos-sdk
mirror of https://github.com/certusone/cosmos-sdk.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

general updates

This commit is contained in:
rigelrozanski 2018-08-08 23:43:40 -04:00
parent a0e05a8f03
commit 5285489977
3 changed files with 58 additions and 113 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

47
docs/spec/distribution/state.md
View File

@ -23,9 +23,10 @@ type DecCoin struct {
} }
type Global struct { type Global struct {
Accum sdk.Dec // global accumulation factor for lazy calculations 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 Pool DecCoins // funds for all validators which have yet to be withdrawn
CommunityFund DecCoins // pool for community funds yet to be spent 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 ```golang
type ValidatorDistribution struct { type ValidatorDistribution struct {
CommissionWithdrawalHeight int64 // last time this validator withdrew commission CommissionWithdrawalHeight int64 // last height this validator withdrew commission
Accum sdk.Dec // global pool accumulation factor
ProposerAccum sdk.Dec // proposer pool accumulation factor GlobalWithdrawalHeight int64 // last height this validator withdrew from the global pool
ProposerPool DecCoins // reward pool collected from being the proposer 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 ### Delegation Distribution
Each delegation holds multiple accumulation factors to specify its entitlement to Each delegation distribution only needs to record the height at which it last
the rewards from a validator. `Accum` is used to passively calculate withdrew fees. Because a delegation must withdraw fees each time it's
each bonds entitled rewards from the `RewardPool`. `AccumProposer` is used to properties change (aka bonded tokens etc.) its properties will remain constant
passively calculate each bonds entitled rewards from and the delegator's _accumulation_ factor can be calculated passively knowing
`ValidatorDistribution.ProposerRewardPool` only the height of the last withdrawal and its current properties.
- DelegatorDistribution: ` 0x02 | DelegatorAddr | ValOwnerAddr -> amino(delegatorDist)` - DelegatorDistribution: ` 0x02 | DelegatorAddr | ValOwnerAddr -> amino(delegatorDist)`
```golang ```golang
type DelegatorDist struct { type DelegatorDist struct {
WithdrawalHeight int64 // last time this delegation withdrew rewards 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
}
```

108
docs/spec/distribution/transactions.md
View File

@ -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 # Transactions
## TxWithdrawDelegation ## 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 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 modified for each block with a change in distributors shares since the time of
last withdrawal. This is accomplished by iterating over all relevant last withdrawal. This is accomplished by iterating over all relevant
`PowerChange`'s stored in distribution state. `ValidatorUpdate`'s stored in distribution state.
```golang ```golang
@ -57,7 +70,7 @@ func GetDelegatorEntitlement(delegatorAddr sdk.AccAddress) DecCoins
return entitlement return entitlement
func (pc PowerChange) ProcessPowerChangeDelegation(delegation sdk.Delegation, func (pc ValidatorUpdate) ProcessPowerChangeDelegation(delegation sdk.Delegation,
DelDistr DelegationDistribution) DelDistr DelegationDistribution)
// get the historical scenarios // get the historical scenarios
@ -109,7 +122,7 @@ func WithdrawalValidator(ownerAddr, withdrawAddr sdk.AccAddress)
AddCoins(withdrawAddr, totalEntitlment.TruncateDecimal()) AddCoins(withdrawAddr, totalEntitlment.TruncateDecimal())
func (pc PowerChange) ProcessPowerChangeCommission() func (pc ValidatorUpdate) ProcessPowerChangeCommission()
// get the historical scenarios // get the historical scenarios
scenario1 = pc.CommissionFromGlobalPool() scenario1 = pc.CommissionFromGlobalPool()
@ -122,75 +135,6 @@ func (pc PowerChange) ProcessPowerChangeCommission()
## Common Calculations ## 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 ### 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 #### Validators's commission entitlement to Global.Pool
Similar to a delegator's entitlement, but with recipient shares based on the 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.
```
```

14
docs/spec/distribution/triggers.md
View File

@ -6,21 +6,21 @@
The pool of a new delegator bond will be 0 for the height at which the bond was 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 added, or the withdrawal has taken place. This is achieved by setting
`DelegatorDist.WithdrawalHeight` to the relevant height, withdrawing any `DelegatorDist.WithdrawalHeight` to the height of the triggering transaction.
remaining fees, and setting `DelegatorDist.Accum` and
`DelegatorDist.ProposerAccum` to 0.
## Commission rate change ## Commission rate change
- triggered-by: `stake.TxEditValidator` - triggered-by: `stake.TxEditValidator`
If a validator changes its commission rate, all commission on fees must be 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 ## Change in Validator State
- triggered-by: `stake.Slash`, `stake.UpdateValidator` - triggered-by: `stake.Slash`, `stake.UpdateValidator`
Whenever a validator is slashed or enters/leaves the validator group Whenever a validator is slashed or enters/leaves the validator group all of the
`ValidatorUpdate` information must be recorded in order to properly calculate validator entitled reward tokens must be simultaniously withdrawn from
the accum factors. `Global.Pool` and added to `ValidatorDistribution.Pool`