cosmos-sdk/x/distribution/spec/01_concepts.md

35 lines
2.5 KiB
Markdown
Raw Normal View History

Docs: hide frontmatter, bugfixes (#5413) * encoding * working on baseapp doc * baseapp work * reorg * almost there * finish first draft * remove old files * module doc start * finish intro * working * workinnn * add transactions into core * hans comments * add transactions into core * working * gautier comments * clean * working * consolidate intro * querier * workiiiing * refactor for new module interface * karoly review * working on baseapp doc * baseapp work * reorg * almost there * finish first draft * remove old files * finish intro * workinnn * initial commit after rebase * query-lifecycle and started modules-interfaces * query-lifecycle first draft done * module interfaces first draft * rest and intro skeletons * rest and intro done * small edits and links * comments * revisions * cli.md comments * comments * minor edits * better flow for query lifecycle * add transactions into core * hans comments * add transactions into core * checkout master-docs files * deleted some * remove modules readme * cli.md comments * comments * module-interfaces comments * Merge PR #4857: Add Context concept doc * working * working * finish messages and queries * handler * querier * last comments! * punctuation * querier2 * consolidate intro * querier * workiiiing * refactor for new module interface * karoly review * working on baseapp doc * baseapp work * reorg * almost there * finish first draft * remove old files * finish intro * workinnn * initial commit after rebase * query-lifecycle and started modules-interfaces * query-lifecycle first draft done * module interfaces first draft * rest and intro skeletons * rest and intro done * small edits and links * comments * revisions * cli.md comments * comments * minor edits * better flow for query lifecycle * checkout master-docs files * deleted some * remove modules readme * cli.md comments * comments * module-interfaces comments * keeper * genesis * finish * Apply suggestions from code review Co-Authored-By: Hans Schoenburg <hschoenburg@users.noreply.github.com> * hans review * Update docs/core/baseapp.md Co-Authored-By: Hans Schoenburg <hschoenburg@users.noreply.github.com> * working * last comment * workin * Apply suggestions from code review * encoding and node * almost finish store * finish docs * fixes * fede comments + permalinks * hans review * add more permalinks * update docs theme version (#5239) * R4R: Docs Cleanup (#5246) * start * work * work * work * remove table of content * links intro * fix links * remove junk * cleanup * cleanup * work * finish cleanup * addback readmes * remove nft * fix links * remove dup * remove dup * remove dup * remove dup * remove dup * fix links * add subscribe events * refine rest * index page * sidebar * theme version * theme version * testing netlify * theme version * tooltip example * version * testing code embedding * reverting back * theme version * version * version * version * readme and version * cleanup * redo app anatomy * modules readme, theme version * theme version * fix modules list * theme version * new snippets * modules readme * update docs readme * modify synopsis * version * fix yaml * version * version * version * version * version * version * version * version * version * version * add hide banner * version * version * version * small fixes * modules readme, version * remove hotkeys dep, version * version * version * version * version * version * version * version * slight notice * fix links and hide * permalinks * small clean * version * resolve conflicts, add google analytics * fix merge remants * version * changelog 1/2 * Changelog: docs UI * version * remove merge conflicts * Code: Update link for Contributing to the docs to docs_readme * HTML/CSS: Update layout of homepage footer to match new layout in Figma * version * final modifs * modules, version * modules readme * link to module list from homepage * version * building modules link * version * version * fonts * version * version * fix link * fix package.json * links in explore sdk section * core concepts * version * change delimeters for frontmatter * frontmatter in comments * version * temp add tiny-cookie * fixed link issues * fixed styling issues, copy * hide frontmatter * hide frontmatter * layout fixes, padded ascii diagram * fira sans font for code
2019-12-17 03:44:44 -08:00
<!--
Final updates for new docs website (#5388) * consolidate intro * start anatomy of sdk app * wokring * working * querier * working * workiiiing * finish * add dep and makefile * Apply suggestions from code review Co-Authored-By: Alessio Treglia <quadrispro@ubuntu.com> * typo * typo * Apply suggestions from code review Co-Authored-By: Alexander Bezobchuk <alexanderbez@users.noreply.github.com> Co-Authored-By: Federico Kunze <31522760+fedekunze@users.noreply.github.com> Co-Authored-By: Alessio Treglia <quadrispro@ubuntu.com> Co-Authored-By: frog power 4000 <rigel.rozanski@gmail.com> * refactor for new module interface * karoly review * Apply suggestions from code review Co-Authored-By: Karoly Albert Szabo <szabo.karoly.a@gmail.com> Co-Authored-By: Federico Kunze <31522760+fedekunze@users.noreply.github.com> * encoding * working on baseapp doc * baseapp work * reorg * almost there * finish first draft * remove old files * module doc start * finish intro * working * workinnn * add transactions into core * hans comments * add transactions into core * working * gautier comments * clean * working * consolidate intro * querier * workiiiing * refactor for new module interface * karoly review * working on baseapp doc * baseapp work * reorg * almost there * finish first draft * remove old files * finish intro * workinnn * initial commit after rebase * query-lifecycle and started modules-interfaces * query-lifecycle first draft done * module interfaces first draft * rest and intro skeletons * rest and intro done * small edits and links * comments * revisions * cli.md comments * comments * minor edits * better flow for query lifecycle * add transactions into core * hans comments * add transactions into core * checkout master-docs files * deleted some * remove modules readme * cli.md comments * comments * module-interfaces comments * Merge PR #4857: Add Context concept doc * working * working * finish messages and queries * handler * querier * last comments! * punctuation * querier2 * consolidate intro * querier * workiiiing * refactor for new module interface * karoly review * working on baseapp doc * baseapp work * reorg * almost there * finish first draft * remove old files * finish intro * workinnn * initial commit after rebase * query-lifecycle and started modules-interfaces * query-lifecycle first draft done * module interfaces first draft * rest and intro skeletons * rest and intro done * small edits and links * comments * revisions * cli.md comments * comments * minor edits * better flow for query lifecycle * checkout master-docs files * deleted some * remove modules readme * cli.md comments * comments * module-interfaces comments * keeper * genesis * finish * Apply suggestions from code review Co-Authored-By: Hans Schoenburg <hschoenburg@users.noreply.github.com> * hans review * Update docs/core/baseapp.md Co-Authored-By: Hans Schoenburg <hschoenburg@users.noreply.github.com> * working * last comment * workin * Apply suggestions from code review * encoding and node * almost finish store * finish docs * fixes * fede comments + permalinks * hans review * add more permalinks * update docs theme version (#5239) * R4R: Docs Cleanup (#5246) * start * work * work * work * remove table of content * links intro * fix links * remove junk * cleanup * cleanup * work * finish cleanup * addback readmes * remove nft * fix links * remove dup * remove dup * remove dup * remove dup * remove dup * fix links * add subscribe events * refine rest * index page * sidebar * theme version * theme version * testing netlify * theme version * tooltip example * version * testing code embedding * reverting back * theme version * version * version * version * readme and version * cleanup * redo app anatomy * modules readme, theme version * theme version * fix modules list * theme version * new snippets * modules readme * update docs readme * modify synopsis * version * fix yaml * version * version * version * version * version * version * version * version * version * version * add hide banner * version * version * version * small fixes * modules readme, version * remove hotkeys dep, version * version * version * version * version * version * version * version * slight notice * fix links and hide * permalinks * small clean * version * resolve conflicts, add google analytics * fix merge remants * version * changelog 1/2 * Changelog: docs UI * version * remove merge conflicts * Code: Update link for Contributing to the docs to docs_readme * HTML/CSS: Update layout of homepage footer to match new layout in Figma * version * final modifs * modules, version * modules readme * link to module list from homepage * version * building modules link * version * version * fonts * version * Update post.sh
2019-12-11 09:35:27 -08:00
order: 1
Docs: hide frontmatter, bugfixes (#5413) * encoding * working on baseapp doc * baseapp work * reorg * almost there * finish first draft * remove old files * module doc start * finish intro * working * workinnn * add transactions into core * hans comments * add transactions into core * working * gautier comments * clean * working * consolidate intro * querier * workiiiing * refactor for new module interface * karoly review * working on baseapp doc * baseapp work * reorg * almost there * finish first draft * remove old files * finish intro * workinnn * initial commit after rebase * query-lifecycle and started modules-interfaces * query-lifecycle first draft done * module interfaces first draft * rest and intro skeletons * rest and intro done * small edits and links * comments * revisions * cli.md comments * comments * minor edits * better flow for query lifecycle * add transactions into core * hans comments * add transactions into core * checkout master-docs files * deleted some * remove modules readme * cli.md comments * comments * module-interfaces comments * Merge PR #4857: Add Context concept doc * working * working * finish messages and queries * handler * querier * last comments! * punctuation * querier2 * consolidate intro * querier * workiiiing * refactor for new module interface * karoly review * working on baseapp doc * baseapp work * reorg * almost there * finish first draft * remove old files * finish intro * workinnn * initial commit after rebase * query-lifecycle and started modules-interfaces * query-lifecycle first draft done * module interfaces first draft * rest and intro skeletons * rest and intro done * small edits and links * comments * revisions * cli.md comments * comments * minor edits * better flow for query lifecycle * checkout master-docs files * deleted some * remove modules readme * cli.md comments * comments * module-interfaces comments * keeper * genesis * finish * Apply suggestions from code review Co-Authored-By: Hans Schoenburg <hschoenburg@users.noreply.github.com> * hans review * Update docs/core/baseapp.md Co-Authored-By: Hans Schoenburg <hschoenburg@users.noreply.github.com> * working * last comment * workin * Apply suggestions from code review * encoding and node * almost finish store * finish docs * fixes * fede comments + permalinks * hans review * add more permalinks * update docs theme version (#5239) * R4R: Docs Cleanup (#5246) * start * work * work * work * remove table of content * links intro * fix links * remove junk * cleanup * cleanup * work * finish cleanup * addback readmes * remove nft * fix links * remove dup * remove dup * remove dup * remove dup * remove dup * fix links * add subscribe events * refine rest * index page * sidebar * theme version * theme version * testing netlify * theme version * tooltip example * version * testing code embedding * reverting back * theme version * version * version * version * readme and version * cleanup * redo app anatomy * modules readme, theme version * theme version * fix modules list * theme version * new snippets * modules readme * update docs readme * modify synopsis * version * fix yaml * version * version * version * version * version * version * version * version * version * version * add hide banner * version * version * version * small fixes * modules readme, version * remove hotkeys dep, version * version * version * version * version * version * version * version * slight notice * fix links and hide * permalinks * small clean * version * resolve conflicts, add google analytics * fix merge remants * version * changelog 1/2 * Changelog: docs UI * version * remove merge conflicts * Code: Update link for Contributing to the docs to docs_readme * HTML/CSS: Update layout of homepage footer to match new layout in Figma * version * final modifs * modules, version * modules readme * link to module list from homepage * version * building modules link * version * version * fonts * version * version * fix link * fix package.json * links in explore sdk section * core concepts * version * change delimeters for frontmatter * frontmatter in comments * version * temp add tiny-cookie * fixed link issues * fixed styling issues, copy * hide frontmatter * hide frontmatter * layout fixes, padded ascii diagram * fira sans font for code
2019-12-17 03:44:44 -08:00
-->
Final updates for new docs website (#5388) * consolidate intro * start anatomy of sdk app * wokring * working * querier * working * workiiiing * finish * add dep and makefile * Apply suggestions from code review Co-Authored-By: Alessio Treglia <quadrispro@ubuntu.com> * typo * typo * Apply suggestions from code review Co-Authored-By: Alexander Bezobchuk <alexanderbez@users.noreply.github.com> Co-Authored-By: Federico Kunze <31522760+fedekunze@users.noreply.github.com> Co-Authored-By: Alessio Treglia <quadrispro@ubuntu.com> Co-Authored-By: frog power 4000 <rigel.rozanski@gmail.com> * refactor for new module interface * karoly review * Apply suggestions from code review Co-Authored-By: Karoly Albert Szabo <szabo.karoly.a@gmail.com> Co-Authored-By: Federico Kunze <31522760+fedekunze@users.noreply.github.com> * encoding * working on baseapp doc * baseapp work * reorg * almost there * finish first draft * remove old files * module doc start * finish intro * working * workinnn * add transactions into core * hans comments * add transactions into core * working * gautier comments * clean * working * consolidate intro * querier * workiiiing * refactor for new module interface * karoly review * working on baseapp doc * baseapp work * reorg * almost there * finish first draft * remove old files * finish intro * workinnn * initial commit after rebase * query-lifecycle and started modules-interfaces * query-lifecycle first draft done * module interfaces first draft * rest and intro skeletons * rest and intro done * small edits and links * comments * revisions * cli.md comments * comments * minor edits * better flow for query lifecycle * add transactions into core * hans comments * add transactions into core * checkout master-docs files * deleted some * remove modules readme * cli.md comments * comments * module-interfaces comments * Merge PR #4857: Add Context concept doc * working * working * finish messages and queries * handler * querier * last comments! * punctuation * querier2 * consolidate intro * querier * workiiiing * refactor for new module interface * karoly review * working on baseapp doc * baseapp work * reorg * almost there * finish first draft * remove old files * finish intro * workinnn * initial commit after rebase * query-lifecycle and started modules-interfaces * query-lifecycle first draft done * module interfaces first draft * rest and intro skeletons * rest and intro done * small edits and links * comments * revisions * cli.md comments * comments * minor edits * better flow for query lifecycle * checkout master-docs files * deleted some * remove modules readme * cli.md comments * comments * module-interfaces comments * keeper * genesis * finish * Apply suggestions from code review Co-Authored-By: Hans Schoenburg <hschoenburg@users.noreply.github.com> * hans review * Update docs/core/baseapp.md Co-Authored-By: Hans Schoenburg <hschoenburg@users.noreply.github.com> * working * last comment * workin * Apply suggestions from code review * encoding and node * almost finish store * finish docs * fixes * fede comments + permalinks * hans review * add more permalinks * update docs theme version (#5239) * R4R: Docs Cleanup (#5246) * start * work * work * work * remove table of content * links intro * fix links * remove junk * cleanup * cleanup * work * finish cleanup * addback readmes * remove nft * fix links * remove dup * remove dup * remove dup * remove dup * remove dup * fix links * add subscribe events * refine rest * index page * sidebar * theme version * theme version * testing netlify * theme version * tooltip example * version * testing code embedding * reverting back * theme version * version * version * version * readme and version * cleanup * redo app anatomy * modules readme, theme version * theme version * fix modules list * theme version * new snippets * modules readme * update docs readme * modify synopsis * version * fix yaml * version * version * version * version * version * version * version * version * version * version * add hide banner * version * version * version * small fixes * modules readme, version * remove hotkeys dep, version * version * version * version * version * version * version * version * slight notice * fix links and hide * permalinks * small clean * version * resolve conflicts, add google analytics * fix merge remants * version * changelog 1/2 * Changelog: docs UI * version * remove merge conflicts * Code: Update link for Contributing to the docs to docs_readme * HTML/CSS: Update layout of homepage footer to match new layout in Figma * version * final modifs * modules, version * modules readme * link to module list from homepage * version * building modules link * version * version * fonts * version * Update post.sh
2019-12-11 09:35:27 -08:00
# Concepts
In Proof of Stake (PoS) blockchains, rewards gained from transaction fees are paid to validators. The fee distribution module fairly distributes the rewards to the validators' constituent delegators.
docs: x/distribution spec (#8928) * EndBlock => BeginBlock * Add high-level algorithm * Update documentation on params invariant * Comment fix * Update and extend BeginBlock documentation * Update hooks documentation * New intro to the concepts * Update messages documentation * Write in full sentences Co-authored-by: Robert Zaremba <robert@zaremba.ch> * spelling error * change link * slashing spec clarification * Revert "slashing spec clarification" This reverts commit b08b5a8533ca9d355a0afb0e58254b95487ce880. * Update x/distribution/spec/04_messages.md Co-authored-by: Robert Zaremba <robert@zaremba.ch> * Update x/distribution/spec/03_begin_block.md Co-authored-by: Federico Kunze <31522760+fedekunze@users.noreply.github.com> * update link to latest version * Update x/distribution/spec/04_messages.md Co-authored-by: Robert Zaremba <robert@zaremba.ch> * clarify note on removed validator * clarify validator removed hook * clarify validator created hook * clarify delegation modified/created hook * clarify slash hook * clarify possesive singular situation * clarify hooks.go * Move comment to clearer position * Update x/distribution/spec/01_concepts.md Co-authored-by: Barrie Byron <barrie.byron@tendermint.com> * clarifications in concepts file * Clarify introductory paragraphs * communitytax => community_tax * Apply suggestions from code review Co-authored-by: Barrie Byron <barrie.byron@tendermint.com> Co-authored-by: Robert Zaremba <robert@zaremba.ch> * Update delegator rewards descirption * Remove "this" * Fix error in non-proposer validator rewards spec * Clarify validator rewards high level description * Update x/distribution/spec/04_messages.md * Clarify what fees are * Misc grammar and style fixes * Apply suggestions from code review Co-authored-by: Barrie Byron <barrie.byron@tendermint.com> * Apply suggestions from code review Co-authored-by: Barrie Byron <barrie.byron@tendermint.com> Co-authored-by: Ethan Buchman <ethan@coinculture.info> Co-authored-by: Jack Zampolin <jack.zampolin@gmail.com> Co-authored-by: Marko <marbar3778@yahoo.com> Co-authored-by: Robert Zaremba <robert@zaremba.ch> Co-authored-by: Federico Kunze <31522760+fedekunze@users.noreply.github.com> Co-authored-by: Barrie Byron <barrie.byron@tendermint.com> Co-authored-by: Alessio Treglia <alessio@tendermint.com> Co-authored-by: Ethan Buchman <ethan@coinculture.info>
2021-05-03 11:40:34 -07:00
Rewards are calculated per period. The period is updated each time a validator's delegation changes, for example, when the validator receives a new delegation.
The rewards for a single validator can then be calculated by taking the total rewards for the period before the delegation started, minus the current total rewards.
To learn more, see the [F1 Fee Distribution paper](/docs/spec/fee_distribution/f1_fee_distr.pdf).
The commission to the validator is paid when the validator is removed or when the validator requests a withdrawal.
The commission is calculated and incremented at every `BeginBlock` operation to update accumulated fee amounts.
The rewards to a delegator are distributed when the delegation is changed or removed, or a withdrawal is requested.
docs: x/distribution spec (#8928) * EndBlock => BeginBlock * Add high-level algorithm * Update documentation on params invariant * Comment fix * Update and extend BeginBlock documentation * Update hooks documentation * New intro to the concepts * Update messages documentation * Write in full sentences Co-authored-by: Robert Zaremba <robert@zaremba.ch> * spelling error * change link * slashing spec clarification * Revert "slashing spec clarification" This reverts commit b08b5a8533ca9d355a0afb0e58254b95487ce880. * Update x/distribution/spec/04_messages.md Co-authored-by: Robert Zaremba <robert@zaremba.ch> * Update x/distribution/spec/03_begin_block.md Co-authored-by: Federico Kunze <31522760+fedekunze@users.noreply.github.com> * update link to latest version * Update x/distribution/spec/04_messages.md Co-authored-by: Robert Zaremba <robert@zaremba.ch> * clarify note on removed validator * clarify validator removed hook * clarify validator created hook * clarify delegation modified/created hook * clarify slash hook * clarify possesive singular situation * clarify hooks.go * Move comment to clearer position * Update x/distribution/spec/01_concepts.md Co-authored-by: Barrie Byron <barrie.byron@tendermint.com> * clarifications in concepts file * Clarify introductory paragraphs * communitytax => community_tax * Apply suggestions from code review Co-authored-by: Barrie Byron <barrie.byron@tendermint.com> Co-authored-by: Robert Zaremba <robert@zaremba.ch> * Update delegator rewards descirption * Remove "this" * Fix error in non-proposer validator rewards spec * Clarify validator rewards high level description * Update x/distribution/spec/04_messages.md * Clarify what fees are * Misc grammar and style fixes * Apply suggestions from code review Co-authored-by: Barrie Byron <barrie.byron@tendermint.com> * Apply suggestions from code review Co-authored-by: Barrie Byron <barrie.byron@tendermint.com> Co-authored-by: Ethan Buchman <ethan@coinculture.info> Co-authored-by: Jack Zampolin <jack.zampolin@gmail.com> Co-authored-by: Marko <marbar3778@yahoo.com> Co-authored-by: Robert Zaremba <robert@zaremba.ch> Co-authored-by: Federico Kunze <31522760+fedekunze@users.noreply.github.com> Co-authored-by: Barrie Byron <barrie.byron@tendermint.com> Co-authored-by: Alessio Treglia <alessio@tendermint.com> Co-authored-by: Ethan Buchman <ethan@coinculture.info>
2021-05-03 11:40:34 -07:00
Before rewards are distributed, all slashes to the validator that occurred during the current delegation are applied.
## Reference Counting in F1 Fee Distribution
docs: x/distribution spec (#8928) * EndBlock => BeginBlock * Add high-level algorithm * Update documentation on params invariant * Comment fix * Update and extend BeginBlock documentation * Update hooks documentation * New intro to the concepts * Update messages documentation * Write in full sentences Co-authored-by: Robert Zaremba <robert@zaremba.ch> * spelling error * change link * slashing spec clarification * Revert "slashing spec clarification" This reverts commit b08b5a8533ca9d355a0afb0e58254b95487ce880. * Update x/distribution/spec/04_messages.md Co-authored-by: Robert Zaremba <robert@zaremba.ch> * Update x/distribution/spec/03_begin_block.md Co-authored-by: Federico Kunze <31522760+fedekunze@users.noreply.github.com> * update link to latest version * Update x/distribution/spec/04_messages.md Co-authored-by: Robert Zaremba <robert@zaremba.ch> * clarify note on removed validator * clarify validator removed hook * clarify validator created hook * clarify delegation modified/created hook * clarify slash hook * clarify possesive singular situation * clarify hooks.go * Move comment to clearer position * Update x/distribution/spec/01_concepts.md Co-authored-by: Barrie Byron <barrie.byron@tendermint.com> * clarifications in concepts file * Clarify introductory paragraphs * communitytax => community_tax * Apply suggestions from code review Co-authored-by: Barrie Byron <barrie.byron@tendermint.com> Co-authored-by: Robert Zaremba <robert@zaremba.ch> * Update delegator rewards descirption * Remove "this" * Fix error in non-proposer validator rewards spec * Clarify validator rewards high level description * Update x/distribution/spec/04_messages.md * Clarify what fees are * Misc grammar and style fixes * Apply suggestions from code review Co-authored-by: Barrie Byron <barrie.byron@tendermint.com> * Apply suggestions from code review Co-authored-by: Barrie Byron <barrie.byron@tendermint.com> Co-authored-by: Ethan Buchman <ethan@coinculture.info> Co-authored-by: Jack Zampolin <jack.zampolin@gmail.com> Co-authored-by: Marko <marbar3778@yahoo.com> Co-authored-by: Robert Zaremba <robert@zaremba.ch> Co-authored-by: Federico Kunze <31522760+fedekunze@users.noreply.github.com> Co-authored-by: Barrie Byron <barrie.byron@tendermint.com> Co-authored-by: Alessio Treglia <alessio@tendermint.com> Co-authored-by: Ethan Buchman <ethan@coinculture.info>
2021-05-03 11:40:34 -07:00
In F1 fee distribution, the rewards a delegator receives are calculated when their delegation is withdrawn. This calculation must read the terms of the summation of rewards divided by the share of tokens from the period which they ended when they delegated, and the final period that was created for the withdrawal.
Additionally, as slashes change the amount of tokens a delegation will have (but we calculate this lazily,
only when a delegator un-delegates), we must calculate rewards in separate periods before / after any slashes
which occurred in between when a delegator delegated and when they withdrew their rewards. Thus slashes, like
delegations, reference the period which was ended by the slash event.
All stored historical rewards records for periods which are no longer referenced by any delegations
or any slashes can thus be safely removed, as they will never be read (future delegations and future
slashes will always reference future periods). This is implemented by tracking a `ReferenceCount`
along with each historical reward storage entry. Each time a new object (delegation or slash)
is created which might need to reference the historical record, the reference count is incremented.
Each time one object which previously needed to reference the historical record is deleted, the reference
count is decremented. If the reference count hits zero, the historical record is deleted.