Staking documentation

.pages

@@ -4,6 +4,7 @@ arrange:
   - getting-started
   - networks
   - governance
+  - staking
   - integrations
   - dapps-list
   - node-operators

code-snippets/staking/staking-definitions.md

@@ -0,0 +1,10 @@
+Some important parameters to understand related to the staking system in Moonbeam include:
+
+-  **Collators** — block producers. They collect transactions from users and produce state transition proofs for the Relay Chain to validate. Have a stake in the network that get slashed if they misbehave
+-  **Nominators** — token holders who stake tokens vouching for specific collators. Any user that holds a minimum amount of tokens as [free balance](https://wiki.polkadot.network/docs/en/learn-accounts#balance-types)) can become a nominator
+-  **Minimum nomination stake** — is the minimum amount of total tokens staked a user needs to have to be in the set of nominators
+-  **Minimum nomination** — once a user is in the set of nominators, it is the minimum amount of tokens to nominate other collators
+-  **Maximumm nominators per collator** — maximum number of nominators a collator can have
+-  **Maximumm collators per nominator** — maximum number of collators a nominator can nominate
+-  **Round** — number of blocks in a round. Important parameter for reward distribution
+-  **Bond duration** — number of rounds that the staking rewards are delayed

staking/.pages

@@ -1,5 +1,4 @@
 title: Staking
 arrange:
   - overview.md
-  - mechanics.md
   - stake.md

staking/overview.md

@@ -3,34 +3,54 @@ title: Overview
 description: Moonbeam provides staking features where token holders nominate collators with their tokens and earn rewards
 ---
 
-# Staking  in Moonbeam
+# Staking in Moonbeam
 
 ![Staking Moonbeam Banner](/images/staking/staking-overview-banner.png)
 
 ## Introduction
 
-Moonbeam uses a block production mechanism based on [Polkadot's Proof-of-Stake model](https://wiki.polkadot.network/docs/en/learn-consensus), where there are collators and validators. [Collators](https://wiki.polkadot.network/docs/en/learn-collator) mantain parachains (in this case Moonbeam) by collecting transactions from users and producing state transition proofs for the Relay Chain [validators](https://wiki.polkadot.network/docs/en/learn-validator). 
+Moonbeam uses a block production mechanism based on [Polkadot's Proof-of-Stake model](https://wiki.polkadot.network/docs/en/learn-consensus) where there are collators and validators. [Collators](https://wiki.polkadot.network/docs/en/learn-collator) maintain parachains (in this case, Moonbeam) by collecting transactions from users and producing state transition proofs for the Relay Chain [validators](https://wiki.polkadot.network/docs/en/learn-validator).
 
-The collators set (nodes that produce blocks) are selected based on the stake the have in the network. And here is where staking comes in. 
+The collators set (nodes that produce blocks) are selected based on their stake in the network. And here is where staking comes in.
 
-Collators (and token holders if they nominate) have a stake in the network from which they get slashed if they misbehave. Therefore, the higher the stake, the higher the network security. But also, the higher the stake, the more likely that collator will get selected to produce a block and earn rewards, which they share with their nominators. In such a way, network members are incentivized to stake tokens to improve the overall security.
+Collators (and token holders if they nominate) have a stake in the network from which they get slashed if they misbehave. Therefore, the higher the stake, the higher the network security. The higher the stake, the more likely the collator will get selected to produce a block and earn rewards, which they share with their nominators. In such a way, network members are incentivized to stake tokens to improve the overall security.
 
 ## General Definitions
 
-Some important parameters to understand related ot the staking system in Moonbeam include:
-
- - **Collators** — block producers. They collect transactions from users and produce state transition proofs for the Relay Chain to validate. Have a stake in the network that get slashed if they misbehave
- - **Nominators** — token holders which stake tokens vouching for specific collators. Any user that holds a minimum amount of tokens (in [TODO balance](https://wiki.polkadot.network/docs/en/learn-accounts#balance-types)) can become a nominator
- - **Minimum nomination stake** — is the minimum amount of tokens a user needs to stake to become a nominator
- - **Minimum nomination** — once a user is a nominator, it is the minimum amount of tokens to nominate other collators
- - **Maximumm nominators per collator** —  maximum number of nominators a collator can have
- - **Maximumm collators per nominator** —  maximum number of collators a nominator can nominate
+--8<-- 'staking/staking-definitions.md'
 
 Currently, for Moonbase Alpha:
 
-|      Variable                  |   |                 Value                         |
-|:------------------------------:|:-:|:---------------------------------------------:|
-|Minimum nomination stake        |   | {{ networks.moonbase.staking.min_nom_stake }} |
-|Minimum nomination              |   | {{ networks.moonbase.staking.min_nom_amount}} |
-|Maximum nominators per collators|   | {{ networks.moonbase.staking.max_nom_per_col }} |
-|Maximum collators per nominator|   | {{ networks.moonbase.staking.max_col_per_nom }} |
+|             Variable             |     |                                                  Value                                                  |
+| :------------------------------: | :-: | :-----------------------------------------------------------------------------------------------------: |
+|     Minimum nomination stake     |     |                              {{ networks.moonbase.staking.min_nom_stake }}                              |
+|        Minimum nomination        |     |                              {{ networks.moonbase.staking.min_nom_amount}}                              |
+| Maximum nominators per collators |     |                             {{ networks.moonbase.staking.max_nom_per_col }}                             |
+| Maximum collators per nominator  |     |                             {{ networks.moonbase.staking.max_col_per_nom }}                             |
+| Maximum collators per nominator  |     |                             {{ networks.moonbase.staking.max_col_per_nom }}                             |
+|              Round               |     | {{ networks.moonbase.staking.round_blocks }} blocks ({{ networks.moonbase.staking.round_hours }} hours) |
+|          Bond duration           |     |                            {{ networks.moonbase.staking.bond_lock }} rounds                             |
+
+## Reward Distribution
+
+At the end of every round ({{ networks.moonbase.staking.round_blocks }} blocks) collators are rewarded for their work from {{ networks.moonbase.staking.bond_lock }} rounds ago.
+
+When collators join the set of collators, they establish a commission to charge their nominators for the service they provide. Therefore, the reward distribution goes as follows:
+
+-  The commission is taken out of the reward to be distributed
+-  The collator gets the rewards corresponding to their stake in the network, plus the commission
+-  The rest of the rewards is distributed among nominators by stake
+
+Mathematically speaking, for collators, the reward would look like this:
+
+![Staking Collator Reward](/images/staking/staking-overview-1.png)
+
+Where the stake corresponds to the amount of tokens bonded by the collator in respect to the total stake of that collator (accounting nominations).
+
+For each nominator, the reward would look like this:
+
+![Staking Nominator Reward](/images/staking/staking-overview-2.png)
+
+Where the stake corresponds to the amount of tokens bonded by each nominator in respect to the total stake of that collator.
+
+## Try it on Moonbase Alpha

staking/stake.md

@@ -5,11 +5,165 @@ description: A guide that shows how you can stake your tokens in Moonbeam by nom
 
 # How to Stake your Tokens
 
-![Staking Moonbeam Banner](/images/staking/staking-staje-banner.png)
+![Staking Moonbeam Banner](/images/staking/staking-stake-banner.png)
 
 ## Introduction
 
+Collators (block producers) with the highest stake in the network join the active pool of collators, from which they are selected to offer a block to the relay chain.
 
+Token holders can add to the collators' stake using their tokens, a process called nomination (also referred to as staking). When they do so, they are vouching for that specific collator, and their nomination is a signal of trust.
+
+When a collator does not behave appropriately, its stake in the network is slashed, affecting the tokens nominated by users as well (feature currently not available in Moonbase Alpha). If collators act accordingly, they'll receive block rewards as part of the inflationary model. They can share these as staking rewards with their nominators.
+
+With the release of [Moonbase Alpha v6](https://github.com/PureStake/moonbeam/releases/tag/v0.6.0), users of the network can now stake their tokens to nominate collators. This guide outlines all the steps to do so.
+
+## General Definitions
+
+--8<-- 'staking/staking-definitions.md'
+
+Currently, for Moonbase Alpha:
+
+|             Variable             |     |                                                  Value                                                  |
+| :------------------------------: | :-: | :-----------------------------------------------------------------------------------------------------: |
+|     Minimum nomination stake     |     |                              {{ networks.moonbase.staking.min_nom_stake }}                              |
+|        Minimum nomination        |     |                              {{ networks.moonbase.staking.min_nom_amount}}                              |
+| Maximum nominators per collators |     |                             {{ networks.moonbase.staking.max_nom_per_col }}                             |
+| Maximum collators per nominator  |     |                             {{ networks.moonbase.staking.max_col_per_nom }}                             |
+| Maximum collators per nominator  |     |                             {{ networks.moonbase.staking.max_col_per_nom }}                             |
+|              Round               |     | {{ networks.moonbase.staking.round_blocks }} blocks ({{ networks.moonbase.staking.round_hours }} hours) |
+|          Bond duration           |     |                            {{ networks.moonbase.staking.bond_lock }} rounds                             |
+
+## Extrinsics Definitions
+
+There are many extrinsics related to the staking pallet. So, all of them are not covered in this guide. However, this list defines all the extrinsics associated with the nomination process:
+
+!!! note
+    xtrinsics might change in the future as the staking pallet is updated.
+
+-  **joinNominators** — two inputs: address of collator to nominate and amount. Extrinsic to join the set of nominators and nominate your first collator. The amount must be at least {{ networks.moonbase.staking.min_nom_stake }} tokens
+-  **leaveNominators** — no inputs. Extrinsic to leave the set of nominators. Consequently, all ongoing nominations will be revoked
+-  **nominateNew** — two inputs: address of collator to nominate and amount. Extrinsic to nominate a new collator after already being part of the set of nominators (read `joinNominators` extrinsic). The amount must be at least {{ networks.moonbase.staking.min_nom_amount }} tokens
+-  **nominatorBondLess** — two inputs: address of a nominated collator and amount. Extrinsic to reduce the amount of staked tokens for an already nominated collator. The amount must not decrease your overall total staked below {{ networks.moonbase.staking.min_nom_stake }} tokens
+-  **nominatorBondMore** — two inputs: address of a nominated collator and amount. Extrinsic to increase the amount of staked tokens for an already nominated collator
+-  **revokeNomination** — one input: address of a nominated collator. Extrinsic to remove an existing nomination
+-  **switchNomination** — two inputs: address of an old nominated collator and address of the new collator to nominate. Extrinsic to switch an existing nomination from a nominated collator to a new collator. If you already nominate the new collator, this will increase the nomination amount
+
+## Retrieving the List of Collators
+
+Before you start staking tokens, it is important to retrieve the list of collators available in the network. To do so, navigate to "Chain state" under the "Developer" tab.
+
+![Staking Account](/images/staking/staking-stake-10.png)
+
+Here, you need to provide the following information:
+
+1. Choose the pallet you want to interact with. In this case, it is the `stake` pallet
+2. Choose the state to query. In this case, it is the `validators` or `candidatePool` state.
+3. Send the state query by clicking on the "+" button
+
+Each extrinsic provides a different response:
+
+-  **validators** — returns the current active set of collators, that is, the top {{ networks.moonbase.staking.max_collators }} collators by total tokens staked (including nominations)
+-  **candidatePool** — returns the current all of the collators, including those that are not in the active set
+
+![Staking Account](/images/staking/staking-stake-11.png)
+
+## How to Nominate a Collator
+
+This section goes over the process of nominating collators. The tutorial will use the following collators as reference:
+
+|  Variable  |     |                      Address                       |
+| :--------: | :-: | :------------------------------------------------: |
+| Collator 1 |     | {{ networks.moonbase.staking.collators.address1 }} |
+| Collator 2 |     | {{ networks.moonbase.staking.collators.address2 }} |
+
+To access staking features, you need to use the PolkadotJS Apps interface. To do so, you need to import/create an Ethereum-style account first (H160 address), which you can do by following [this guide](/integrations/wallets/polkadotjs/#creating-or-importing-an-h160-account).
+
+For this example, an account was imported and named with a super original name: Alice.
+
+Currently, everything related to staking needs to be accessed via the "Extrinsics" menu, under the "Developer" tab:
+
+![Staking Account](/images/staking/staking-stake-1.png)
+
+Here, you need to provide the following information:
+
+1. Select the account from which you want to stake your tokens
+2. Choose the pallet you want to interact with. In this case, it is the `stake` pallet
+3. Choose the extrinsic method to use for the transaction. This will determine the fields that need to fill in the following steps. In this case, it is the `joinNominators` extrinsic
+4. Set the collator's address you want to nominate. In this case, it is set to `{{ networks.moonbase.staking.collators.address1 }}`
+5. Set the number of tokens you want to stake
+6. Click the "Submit Transaction" button and sign the transaction
+
+![Staking Join Nominators Extrinsics](/images/staking/staking-stake-2.png)
+
+Once the transaction is confirmed, you can head back to the "Accounts" tab to verify that you have a reserved balance (equal to the number of tokens staked).
+
+To verify a nomination, you can navigate to "Chain state" under the "Developer" tab.
+
+![Staking Account and Chain State](/images/staking/staking-stake-3.png)
+
+Here, you need to provide the following information:
+
+1. Choose the pallet you want to interact with. In this case, it is the `stake` pallet
+2. Choose the state to query. In this case, it is the `nominators` state.
+3. Make sure to disable the "include option" slider
+4. Send the state query by clicking on the "+" button
+
+![Staking Chain State Query](/images/staking/staking-stake-4.png)
+
+In the response, you should see your account (in this case, Alice's account) with a list of the nominations. Each nomination contains the target address of the collator and the amount.
+
+To nominate your next collator, you need to repeat the same process as before, but this time using the `nominateNew` extrinsic (in step 3 of the "Extrinsics" instructions). In this example, Alice will nominate `{{ networks.moonbase.staking.collators.address2 }}` with 10 tokens:
+
+![Staking Nominate New Extrinsic](/images/staking/staking-stake-5.png)
+
+Once the transaction is confirmed, you can verify your new nomination in the "Chain state" option under the "Developer" tab:
+
+![Staking Nominate New Cain State](/images/staking/staking-stake-6.png)
+
+## How to Stop Nominations
+
+If you are already a nominator, you have two options to stop your nominations: using the `revokeNomination` extrinsic to unstake your tokens from a specific collator, or using the `leaveNominators` extrinsic to revoke all ongoing nominations.
+
+This example is a continuation of the previous section, meaning that it assumes that you have at least two active nominations.
+
+You can remove your nomination from a specific collator by navigating to the "Extrinsics" menu under the "Developer" tab. Here, you need to provide the following information:
+
+1. Select the account from which you want to remove your nomination
+2. Choose the pallet you want to interact with. In this case, it is the `stake` pallet
+3. Choose the extrinsic method to use for the transaction. This will determine the fields that need to fill in the following steps. In this case, it is the `revokeNomination` extrinsic
+4. Set the collator's address you want to remove your nomination from. In this case, it is set to `{{ networks.moonbase.staking.collators.address2 }}`
+5. Click the "Submit Transaction" button and sign the transaction
+
+![Staking Revoke Nomination Extrinsic](/images/staking/staking-stake-7.png)
+
+Once the transaction is confirmed, you can verify that your nomination was removed in the "Chain state" option under the "Developer" tab.
+
+Here, you need to provide the following information:
+
+1. Choose the pallet you want to interact with. In this case, it is the `stake` pallet
+2. Choose the state to query. In this case, it is the `nominators` state
+3. Make sure to disable the "include options" slider
+4. Send the state query by clicking on the "+" button
+
+![Staking Revoke Nomination Cain State](/images/staking/staking-stake-8.png)
+
+In the response, you should see your account (in this case, Alice's account) with a list of the nominations. Each nomination contains the target address of the collator, and the amount.
+
+As mentioned before, you can also remove all ongoing nominations with the `leaveNominators` extrinsic (in step 3 of the "Extrinsics" instructions). This extrinsic requires no input:
+
+![Staking Leave Nominatiors Extrinsic](/images/staking/staking-stake-9.png)
+
+Once the transaction is confirmed, your account should not be listed in the `nominators` state when queried, and you should have no reserved balance (related to staking).
+
+## Staking Rewards
+
+As collators receive rewards from block production, nominators get rewards as well. A brief overview on how the rewards are calculated can be found on [this page](/staking/overview/#reward-distribution).
+
+In summary, nominators will earn rewards based on their stake of the total nominations for the collator being rewarded (including the collator's stake as well).
+
+From the previous example, Alice was rewarded with `0.0021` tokens after a payout round:
+
+![Staking Reward Example](/images/staking/staking-stake-10.png)
 
 ## We Want to Hear From You