From 338b49b2cd66b8660681dc8a93364677d34c2b7a Mon Sep 17 00:00:00 2001 From: Aleksandr Bezobchuk Date: Sun, 11 Nov 2018 15:51:27 -0500 Subject: [PATCH 1/7] Slight distribution spec cleanup --- docs/spec/distribution/overview.md | 45 +++++++++++++++--------------- 1 file changed, 23 insertions(+), 22 deletions(-) diff --git a/docs/spec/distribution/overview.md b/docs/spec/distribution/overview.md index 28b1bbeddf..281a90af8c 100644 --- a/docs/spec/distribution/overview.md +++ b/docs/spec/distribution/overview.md @@ -2,56 +2,57 @@ ## 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 therefore -be upgraded in the future. +This _simple_ distribution mechanism describes a functional way to passively +distribute rewards between validators and delegators. Note, that this mechanism does +not distribute funds in as precisely as active reward distribution mechanisms 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 -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. +behalf of the delegators. Fees are collected 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. - - 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 +- 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). - - Whenever a validator chooses to change the commission on rewards, all accumulated +- Whenever a validator chooses to change the commission on rewards, all accumulated commission rewards must be simultaneously withdrawn. The above scenarios are covered in `hooks.md`. -The distribution mechanism outlines herein is used to lazily distribute the +The distribution mechanism outlines herein are 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 + +- multi-token fees to be socially distributed +- proposer reward pool +- inflated atom provisions +- 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 withdraw their rewards. -## Shortcomings +## 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 fee pool is owed to them. +fair portion of tokens held in the global fee pool is owed to them. ``` entitlement = delegator-accumulation / all-delegators-accumulation ``` -Under the circumstance that there were constant and equal flow of incoming +Under the circumstance that there were constant and equal flows 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 +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. +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 From 795a76d489cba5db65141f2006f09e37141d79f8 Mon Sep 17 00:00:00 2001 From: Aleksandr Bezobchuk Date: Sun, 11 Nov 2018 15:53:43 -0500 Subject: [PATCH 2/7] More cleanup --- docs/spec/distribution/overview.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/spec/distribution/overview.md b/docs/spec/distribution/overview.md index 281a90af8c..ce8e7c29cc 100644 --- a/docs/spec/distribution/overview.md +++ b/docs/spec/distribution/overview.md @@ -54,7 +54,7 @@ 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, +If you happen to know that incoming rewards are about significantly go up, you are incentivized to not withdraw until after this event, increasing the worth of your existing _accum_. @@ -62,12 +62,12 @@ worth of your existing _accum_. 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 mechanisms 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 +of Atoms in 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. +to set up a script to periodically withdraw and rebond rewards. From 46b331de07e884106f2b5364f2723c8839159d49 Mon Sep 17 00:00:00 2001 From: Aleksandr Bezobchuk Date: Tue, 13 Nov 2018 09:02:19 -0500 Subject: [PATCH 3/7] Address PR review --- docs/spec/distribution/overview.md | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/docs/spec/distribution/overview.md b/docs/spec/distribution/overview.md index ce8e7c29cc..4d01d2d136 100644 --- a/docs/spec/distribution/overview.md +++ b/docs/spec/distribution/overview.md @@ -3,7 +3,7 @@ ## Overview This _simple_ distribution mechanism describes a functional way to passively -distribute rewards between validators and delegators. Note, that this mechanism does +distribute rewards between validators and delegators. Note that this mechanism does not distribute funds in as precisely as active reward distribution mechanisms and will therefore be upgraded in the future. @@ -16,7 +16,7 @@ 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. + to, 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). @@ -54,20 +54,21 @@ 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 go up, +If you happen to know that incoming rewards are about to significantly go up, you are incentivized to not withdraw until after this event, increasing the -worth of your existing _accum_. +worth of your existing _accum_. See [#2764](https://github.com/cosmos/cosmos-sdk/issues/2764) +for further details. ## 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 mechanisms are mutually -exclusive. If there are Atom commissions and auto-bonding Atoms, the portion -of Atoms in 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 +problematic within BPoS. Fundamentally, these two mechanisms are mutually +exclusive. If there are both commissions and auto-bonding on the staking token, +the amount of staking tokens each validator and delegator has would change each +block, so we would have to iterate through all of them. + +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. From 9118cd7e13c17d8c212c14011a2b573366d57398 Mon Sep 17 00:00:00 2001 From: Rigel Date: Wed, 14 Nov 2018 11:58:00 -0500 Subject: [PATCH 4/7] Update docs/spec/distribution/overview.md Co-Authored-By: alexanderbez --- docs/spec/distribution/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spec/distribution/overview.md b/docs/spec/distribution/overview.md index 4d01d2d136..f4ada0089b 100644 --- a/docs/spec/distribution/overview.md +++ b/docs/spec/distribution/overview.md @@ -25,7 +25,7 @@ occurs, withdrawal of rewards must also occur. The above scenarios are covered in `hooks.md`. -The distribution mechanism outlines herein are used to lazily distribute the +The distribution mechanism outlined herein is used to lazily distribute the following rewards between validators and associated delegators: - multi-token fees to be socially distributed From 4b5be088c46cdc8c8ea7b88086d5951bf37304a9 Mon Sep 17 00:00:00 2001 From: Rigel Date: Wed, 14 Nov 2018 11:58:26 -0500 Subject: [PATCH 5/7] Update docs/spec/distribution/overview.md Co-Authored-By: alexanderbez --- docs/spec/distribution/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spec/distribution/overview.md b/docs/spec/distribution/overview.md index f4ada0089b..ee13967735 100644 --- a/docs/spec/distribution/overview.md +++ b/docs/spec/distribution/overview.md @@ -47,7 +47,7 @@ fair portion of tokens held in the global fee pool is owed to them. entitlement = delegator-accumulation / all-delegators-accumulation ``` -Under the circumstance that there were constant and equal flows of incoming +Under the circumstance that there was 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 From b1a1f192fba5873955313730966e1711fe9aa977 Mon Sep 17 00:00:00 2001 From: Rigel Date: Wed, 14 Nov 2018 11:58:55 -0500 Subject: [PATCH 6/7] Update docs/spec/distribution/overview.md Co-Authored-By: alexanderbez --- docs/spec/distribution/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spec/distribution/overview.md b/docs/spec/distribution/overview.md index ee13967735..e6391db7b8 100644 --- a/docs/spec/distribution/overview.md +++ b/docs/spec/distribution/overview.md @@ -54,7 +54,7 @@ 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 to significantly go up, +If you happen to know that incoming rewards are about to significantly increase, you are incentivized to not withdraw until after this event, increasing the worth of your existing _accum_. See [#2764](https://github.com/cosmos/cosmos-sdk/issues/2764) for further details. From bba7a3053dd0251e7a8fa07c29b07b6441483a34 Mon Sep 17 00:00:00 2001 From: Alexander Bezobchuk Date: Wed, 14 Nov 2018 13:26:31 -0500 Subject: [PATCH 7/7] Update overview.md --- docs/spec/distribution/overview.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/spec/distribution/overview.md b/docs/spec/distribution/overview.md index e6391db7b8..8cbe9355a8 100644 --- a/docs/spec/distribution/overview.md +++ b/docs/spec/distribution/overview.md @@ -64,9 +64,11 @@ for further details. 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 BPoS. Fundamentally, these two mechanisms are mutually -exclusive. If there are both commissions and auto-bonding on the staking token, -the amount of staking tokens each validator and delegator has would change each -block, so we would have to iterate through all of them. +exclusive. If both commission and auto-bonding mechanisms are simultaneously +applied to the staking-token then the distribution of staking-tokens between +any validator and its delegators will change with each block. This then +necessitates a calculation for each delegation records for each block - +which is considered computationally expensive. In conclusion, we can only have Atom commission and unbonded atoms provisions or bonded atom provisions with no Atom commission, and we elect to