Documentation for Staking Module #1951

kianenigma · 2019-03-09T14:11:36Z

For this.

Notes:

What to do for Extensibility
~~Add links to a rustdoc once we have one?~~ Some added, rest need a new update on rustdoc
~~More/Other usage examples.~~

parity-cla-bot · 2019-03-09T14:11:38Z

It looks like @kianenigma signed our Contributor License Agreement. 👍

Many thanks,

Parity Technologies CLA Bot

bkchr

That is a really good documentation! :)

bkchr · 2019-03-11T10:25:22Z

srml/staking/README.adoc

+ - Once a new era is triggered, rewards are paid to the validators and the associated nominators. 
+   - The validator can declare an amount that does not get shared with the nominators at each reward payout through their `ValidatorPrefs`. This value gets deducted from the total reward that can be paid. The remaining portion is split among the validator and all of the nominators who had a vote for this validator, proportional to their staked value. 
+  - All entities who receive a reward have the option to choose their reward destination, through the `Payee` storage, to be one of the following: 
+    - Controller account.


This is not displayed as sub-listing.

sure? looks good to me :-?

srml/staking/README.adoc

bkchr · 2019-03-11T10:35:35Z

srml/staking/README.adoc

+
+### Election algorithm details.
+
+Current election algorithm is implemented based on Phragmen. The reference implementation can be found [here](https://github.com/w3f/consensus/tree/master/NPoS).


I would rather link to a more formal description of the algorithm? (if there is any).

It's like, we have this implementation in rust, but if you don't understand rust, just read the implementation in language xy (in this case python) to better understand what is happening :D

The problem is, that a specific language is often not that well suited for explaining high level algorithms.

afaik the only resource is this single python script. I have a yet open PR on that repo that adds a lot of comments to the code to make it more readable.
w3f/consensus#7

gavofyork · 2019-03-11T11:37:38Z

srml/staking/README.adoc

+
+Any account pair successfully placed at stake can accept three possible roles, namely: `validate`, `nominate` or simply `chill`. Note that during the process of accepting these roles, the _controller_ account is always responsible for declaring interest and the _stash_ account stays untouched, without directly interacting in any operation. 
+
+A **validator** takes the role of either validating blocks or ensuring their finality, maintaining the veracity of the network in other words. A validator should avoid both any sort of malicious misbehavior and going offline. Unlike nominating, bonded accounts that state interest in being a validator do NOT get immediately chosen as a validator. Instead, they are declared as a _candidate_ and they _might_ get elected at the _next **era**_ as a validator. The result of election is determined by nominators and their votes. An account can become a validator via the `validate()` call.


not really true; nominators aren't guaranteed to nominate any more than validators are guaranteed to validate. it could be that a nominator only nominates validators that are not chosen. it could also be that the optimisation algorithm doesn't select a nominator's stake to back a validator, even if the validator does become active.

Unlike nominating, bonded accounts that state interest in being a validator do NOT get immediately chosen as a validator ...

Agreed. This is wrong + creates confusion (referring to specifically the bold part.)

srml/staking/README.adoc

srml/staking/src/lib.rs

kianenigma · 2019-03-12T16:00:08Z

This now also complies with the final template of the SRML docs (to a high extent).
@bkchr I would consider this either ready to merge or placed onice to be merged with the rest of the doc PRs.

srml/staking/src/lib.rs

srml/staking/src/phragmen.rs

srml/staking/src/lib.rs

bkchr · 2019-03-15T07:22:49Z

srml/staking/src/lib.rs

+//! 
+//! # References
+//! 
+//! 1. This document is written as a more verbose version of the original [Staking.md](../Staking.md) file. Some sections, are taken directly from the aforementioned document.


Didn't you remove this file in the last pr?

Ugh, the intention was to maintain that as well. Though Gavin said he is also ok with the old one not being kept if everything is covered in a new doc.

I will still keep this section and see where the missing file is + if it is recoverable.

srml/staking/src/lib.rs

joepetrowski

Just some typos and sentence structure stuff to fix

srml/staking/src/lib.rs

joepetrowski · 2019-03-15T07:20:51Z

srml/staking/src/lib.rs

+//! # Staking Module
+//! 
+//! <!-- Original author of paragraph: @gavofyork -->
+//! The staking module is the means by which a set of network maintainers (known as "authorities" in some contexts and "validators" in others) are chosen based upon those who voluntarily place funds under deposit. Under deposit, those funds are rewarded under normal operation but are held at pain of "slash" (expropriation) should they be found not to bee discharging their duties properly. 


"Under deposit, those funds are rewarded" - Are the funds rewarded, or the maintainer? I think it should either say that the staked pot increases or the maintainer is rewarded, but rewarding funds is strange.

let's settle for fund owner? though maintainer is also clear.

I actually think this is clear enough. This is the very frst section and using less keywords makes mroe sense. Funds are placed. Funds are rewarded. poeriod.

Of course, if anyone would read the full doc they would never confuse where the rewards are going.

In fact, funds can end of rewarding either the maintainer, or the fund intself (being being forwarded to the stash account directly).

How about, "those funds' owners are rewarded..."

This actually makes it clear that,

The funds can have multiple owners (the maintainer plus the nominators).

It is the beneficiaries who are being rewarded, not the funds.

Funds are placed. Funds are rewarded. poeriod.

It doesn't make sense to reward an inanimate object. To me, a reward implies gratification of some sort, and "funds" can't feel gratification, but their owners are happy to receive the additional funds.

srml/staking/src/lib.rs

joepetrowski · 2019-03-15T07:28:45Z

srml/staking/src/lib.rs

+//! 
+//! #### Staking 
+//! 
+//! Almost any interaction with the staking module requires at least one account to become **bonded**, also known as being a **staker**. For this, all that it is needed is a secondary _**stash account**_ which will hold the staked funds. Henceforth, the former account that initiated the interest is called the **controller** and the latter, holding the funds, is named the **stash**. Also, note that this implies that entering the staking process requires an _account pair_, one of which to take the role of the controller and one to be the frozen stash account (any value locked in stash cannot be used, hence called _frozen_). This process in the public API is mostly referred to as _bonding_ via the `bond()` function. 


"one to take the role of the controller" (remove 'of which')

It sounds ok to me but I am quite bad with formal English and trust that you have a reason.

It doesn't make sense because you have an account pair. There are two accounts, but one (singular) pair. To make it explicit, you could say, "one account to take..."

srml/staking/src/lib.rs

kianenigma · 2019-03-15T09:57:34Z

@joepetrowski @bkchr I believe all of your comments are addressed, except for the ones not collapsed where I've added sth to the discussion.

shawntabrizi · 2019-03-14T22:04:45Z

srml/staking/src/lib.rs

+//! # Staking Module
+//! 
+//! <!-- Original author of paragraph: @gavofyork -->
+//! The staking module is the means by which a set of network maintainers (known as "authorities" in some contexts and "validators" in others) are chosen based upon those who voluntarily place funds under deposit. Under deposit, those funds are rewarded under normal operation but are held at pain of "slash" (expropriation) should they be found not to bee discharging their duties properly. 


Move this under the "Overview" section header
We standardized the following line at the end of the overview section

For using the timestamp module you need to implement the following [Trait] (//links to the trait). Supported dispatchables are documented in the [Call] enum."

bkchr

Some small nits.

bkchr · 2019-03-15T14:52:49Z

srml/staking/src/lib.rs

+//! are chosen based upon those who voluntarily place funds under deposit. Under deposit, those funds are rewarded under
+//! normal operation but are held at pain of "slash" (expropriation) should the staked maintainer be found not to be 
+//! discharging their duties properly. 
+//! You can start using the Staking module by implementing the staking [`Trait`].


Please also link to the Call enum. See timestamp as an example.

bkchr · 2019-03-15T15:00:17Z

srml/staking/src/lib.rs

+//! 
+//! ## Interface
+//! 
+//! ### Types


We removed this in all the other documentations

srml/staking/src/lib.rs

bkchr · 2019-03-25T07:59:30Z

Superseded by #2078

* WIP: SRML Example Module README * add newlines * review-fix: Change const to let. Explain generic usage more * refactor: Remove example steps 2 and 3. User can refer to other examples to figure it out * fix: Update to incorporate approved approach of staking module docs in PR #1951 * fix: Move into expandable Details arrow and fix syntax so appears correctly in rust docs * fix: Fix linting * docs: Add Public Dispatchable functions * fix: Rearrange to use Simple Code Snippet and Examples from SRML * fix: Remove duplicate Dispatchable Functions section * fix: Remove Implementation Details as requested by Gav

* WIP: SRML Example Module README * add newlines * review-fix: Change const to let. Explain generic usage more * refactor: Remove example steps 2 and 3. User can refer to other examples to figure it out * fix: Update to incorporate approved approach of staking module docs in PR paritytech#1951 * fix: Move into expandable Details arrow and fix syntax so appears correctly in rust docs * fix: Fix linting * docs: Add Public Dispatchable functions * fix: Rearrange to use Simple Code Snippet and Examples from SRML * fix: Remove duplicate Dispatchable Functions section * fix: Remove Implementation Details as requested by Gav

kianenigma added 3 commits March 9, 2019 14:59

initial doc for the staking module

aa83f22

Remove md style links.

b9d09bb

Remove todos.

7df2b19

This comment has been minimized.

Sign in to view

Add rust code types

28b959b

kianenigma added A0-please_review Pull request needs code review. M3-docs labels Mar 9, 2019

devops-parity added the A4-gotissues label Mar 9, 2019

bkchr approved these changes Mar 11, 2019

View reviewed changes

bkchr reviewed Mar 11, 2019

View reviewed changes

gavofyork reviewed Mar 11, 2019

View reviewed changes

srml/staking/README.adoc Outdated Show resolved Hide resolved

kianenigma force-pushed the kiz-document-staking branch 2 times, most recently from 2b9cb6d to 28b959b Compare March 11, 2019 15:09

kianenigma and others added 3 commits March 11, 2019 16:10

Rename and fix review notes.

91be68b

Add new md file

5912ff5

Final touches.

64ca546

kianenigma requested a review from gavofyork March 11, 2019 15:17

kianenigma mentioned this pull request Mar 11, 2019

How to estimate validator and nominator rewards? #1910

Closed

kianenigma added 6 commits March 11, 2019 18:29

Migrate compleatly to rustdoc

a8ba78e

Update link

982d7e8

Fix heading

4a572a2

Merge branch 'master' into kiz-document-staking

ea5ae00

Final touches wrt the new template.

89682a6

Remove empty prereq.

956ec96

bkchr reviewed Mar 12, 2019

View reviewed changes

srml/staking/src/lib.rs Outdated Show resolved Hide resolved

srml/staking/src/lib.rs Outdated Show resolved Hide resolved

Fix more reviews

2879e1d

4meta5 reviewed Mar 12, 2019

View reviewed changes

srml/staking/src/lib.rs Outdated Show resolved Hide resolved

bkchr reviewed Mar 15, 2019

View reviewed changes

srml/staking/src/phragmen.rs Outdated Show resolved Hide resolved

bkchr reviewed Mar 15, 2019

View reviewed changes

srml/staking/src/lib.rs Outdated Show resolved Hide resolved

bkchr reviewed Mar 15, 2019

View reviewed changes

joepetrowski suggested changes Mar 15, 2019

View reviewed changes

Fix another set of reviews

e739361

devops-parity added the A4-gotissues label Mar 15, 2019

joepetrowski approved these changes Mar 15, 2019

View reviewed changes

shawntabrizi approved these changes Mar 15, 2019

View reviewed changes

shawntabrizi added A0-please_review Pull request needs code review. and removed A4-gotissues labels Mar 15, 2019

bkchr approved these changes Mar 15, 2019

View reviewed changes

Clean up a lot of the misleading language.

aa4994e

devops-parity added the A4-gotissues label Mar 15, 2019

shawntabrizi reviewed Mar 15, 2019

View reviewed changes

srml/staking/src/lib.rs Outdated Show resolved Hide resolved

shawntabrizi reviewed Mar 15, 2019

View reviewed changes

srml/staking/src/lib.rs Outdated Show resolved Hide resolved

shawntabrizi added 2 commits March 15, 2019 17:40

Update srml/staking/src/lib.rs

1fee935

Update srml/staking/src/lib.rs

1848306

shawntabrizi reviewed Mar 15, 2019

View reviewed changes

srml/staking/src/lib.rs Outdated Show resolved Hide resolved

shawntabrizi and others added 2 commits March 15, 2019 17:44

Update srml/staking/src/lib.rs

117eb93

Final fixes

f9144b2

kianenigma mentioned this pull request Mar 21, 2019

Self-Vote for Staking (among others.) #2078

Merged

bkchr closed this Mar 25, 2019

shawntabrizi deleted the kiz-document-staking branch March 27, 2019 14:23

kianenigma restored the kiz-document-staking branch March 27, 2019 14:48

shawntabrizi deleted the kiz-document-staking branch March 29, 2019 22:03


		### Election algorithm details.

		Current election algorithm is implemented based on Phragmen. The reference implementation can be found [here](https://github.com/w3f/consensus/tree/master/NPoS).


		Any account pair successfully placed at stake can accept three possible roles, namely: `validate`, `nominate` or simply `chill`. Note that during the process of accepting these roles, the _controller_ account is always responsible for declaring interest and the _stash_ account stays untouched, without directly interacting in any operation.

		A validator takes the role of either validating blocks or ensuring their finality, maintaining the veracity of the network in other words. A validator should avoid both any sort of malicious misbehavior and going offline. Unlike nominating, bonded accounts that state interest in being a validator do NOT get immediately chosen as a validator. Instead, they are declared as a _candidate_ and they _might_ get elected at the _next era_ as a validator. The result of election is determined by nominators and their votes. An account can become a validator via the `validate()` call.

Documentation for Staking Module #1951

Documentation for Staking Module #1951

Uh oh!

Conversation

kianenigma commented Mar 9, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment has been minimized.

parity-cla-bot commented Mar 9, 2019

Uh oh!

bkchr left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kianenigma commented Mar 12, 2019

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

joepetrowski left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kianenigma commented Mar 15, 2019

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bkchr left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

kianenigma commented Mar 9, 2019 •

edited

Loading

bkchr commented Mar 25, 2019 •

edited

Loading