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

triggers, endblock, transactions

This commit is contained in:
rigelrozanski 2018-08-08 15:03:43 -04:00
parent 2d613cefe7
commit a0e05a8f03
4 changed files with 21 additions and 206 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
docs/spec/distribution/end_block.md
View File

@ -3,10 +3,10 @@
At each endblock, the fees received are sorted to the proposer, community fund, 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 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 validator (and their delegators) receives between 1% and 5% of fee rewards, the
reserve tax is then charged, then the remainder is distributed proportionally reserve community tax is then charged, then the remainder is distributed
by voting power to all bonded validators independent of whether they voted proportionally by voting power to all bonded validators independent of whether
(social distribution). Note the social distribution is applied to proposer they voted (social distribution). Note the social distribution is applied to
validator in addition to the proposer reward. proposer validator in addition to the proposer reward.
The amount of proposer reward is calculated from pre-commits Tendermint The amount of proposer reward is calculated from pre-commits Tendermint
messages in order to incentivize validators to wait and include additional messages in order to incentivize validators to wait and include additional

16
docs/spec/distribution/future_improvements.md
View File

@ -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.

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

@ -131,17 +131,12 @@ fulfilled the entitled fees for the various scenarios can be calculated.
```golang ```golang
type DistributionScenario interface { type DistributionScenario interface {
DistributorTokens() DecCoins // current tokens from distributor DistributorTokens() DecCoins // current tokens from distributor
DistributorCumulativeTokens() DecCoins // total tokens ever received DistributorShares() sdk.Dec // current shares
DistributorPrevReceivedTokens() DecCoins // last value of tokens received RecipientAccum() sdk.Dec
DistributorShares() sdk.Dec // current shares RecipientShares() sdk.Dec // current shares
DistributorPrevShares() sdk.Dec // shares last block
RecipientAdjustment() sdk.Dec ModifyAccums(withdrawal sdk.Dec) // proceedure to modify adjustment factors
RecipientShares() sdk.Dec // current shares
RecipientPrevShares() sdk.Dec // shares last block
ModifyAdjustments(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 func (d DistributionScenario) GlobalCount(height int64) sdk.Dec
return d.DistributorShares() * height 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 recipient/distributor shares and recipient withdrawals. The adjustment factor
must be modified whenever the recipient withdraws from the distributor or the must be modified whenever the recipient withdraws from the distributor or the
distributor's/recipient's shares are changed. 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. 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 #### Delegation's entitlement to ValidatorDistribution.ProposerPool
@ -272,43 +215,6 @@ shares is taken as the effective delegation shares less the validator's
commission. 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 #### 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. 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 #### 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. 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)
``` ```

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

@ -1,26 +1,14 @@
# Triggers # 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 ## Create or modify delegation distribution
- triggered-by: `stake.TxDelegate`, `stake.TxBeginRedelegate`, `stake.TxBeginUnbonding` - 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 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 added, or the withdrawal has taken place. This is achieved by setting
the height which the bond was added. Additionally the `AdjustmentPool` and `DelegatorDist.WithdrawalHeight` to the relevant height, withdrawing any
`AdjustmentProposerPool` must be set to the equivalent values of remaining fees, and setting `DelegatorDist.Accum` and
`DelegationDistribution.SimplePool()` and `DelegatorDist.ProposerAccum` to 0.
`DelegationDistribution.SimpleProposerPool()` for the height of delegation.
## Commission rate change ## 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 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`
## 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.