How to Stake your Tokens

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.

Collators receive part of the block rewards as part of the token inflationary model. They can share these as staking rewards with their nominators, considering their percental contribution toward his stake in the network.

With the release of Moonbase Alpha v6, users of the network can now stake their tokens to nominate collators. This guide outlines all the steps to do so.

General Definitions

Some important parameters to understand in relation 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 can become a nominator
• Minimum nomination stake — minimum amount of total tokens staked a user must have to be in the set of nominators
• Minimum nomination — minimum amount of tokens to nominate other collators once a user is in the set of nominators
• Maximum nominators per collator — maximum number of nominators a collator can have
• Maximum collators per nominator — maximum number of collators a nominator can nominate
• Round — a specific number of blocks around which staking actions are enforced. For example, new nominations are enacted when the next round starts. When revoking nominations, funds are returned after a certain amount of rounds

Moonriver

Variable		Value
Minimum nomination stake		5 MOVR
Maximum nominators per collators		100
Maximum collators per nominator		25
Round		300 blocks (1 hours)
Bond duration		2 rounds

Moonbase Alpha

Variable		Value
Minimum nomination stake		5 DEV
Maximum nominators per collators		100
Maximum collators per nominator		25
Round		300 blocks (1 hours)
Bond duration		2 rounds

This guide will show you how to stake on Moonbase Alpha, but the same steps can be followed for Moonriver.

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 of the extrinsics associated with the nomination process:

Note

Extrinsics might change in the future as the staking pallet is updated.

• nominate(address collator, uint256 amount) — extrinsic to nominate a collator. The amount needs to be greater than the minimum nomination stake
• leaveNominators() — extrinsic to leave the set of nominators. Consequently, all ongoing nominations will be revoked
• nominatorBondLess(address collator, uint256 less) — extrinsic to reduce the amount of staked tokens for an already nominated collator. The amount must not decrease your overall total staked below the minimum nomination stake
• nominatorBondMore(address collator, uint256 more) — extrinsic to increase the amount of staked tokens for an already nominated collator
• revokeNomination(address collator) — extrinsic to remove an existing nomination

Retrieving the List of Collators

Before starting to stake tokens, it is important to retrieve the list of collators available in the network. To do so:

1. Head to the "Developer" tab
2. Click on "Chain State"
3. Choose the pallet to interact with. In this case, it is the parachainStaking pallet
4. Choose the state to query. In this case, it is the selectedCandidates or candidatePool state
5. Send the state query by clicking on the "+" button

Each extrinsic provides a different response:

• selectedCandidates — returns the current active set of collators, that is, the top 32 collators by total tokens staked (including nominations)
• candidatePool — returns the current list of all the collators, including those that are not in the active set

Get the Collator Nominator Count

First, you need to get the collator_nominator_count as you'll need to submit this parameter in a later transaction. To do so, you'll have to run the following JavaScript code snippet from within PolkadotJS:

// Simple script to get collator_nominator_count
// Remember to replace COLLATOR_ADDRESS with the address of desired collator.
const collatorAccount = 'COLLATOR_ADDRESS'; 
const collatorInfo = await api.query.parachainStaking.collatorState2(collatorAccount);
console.log(collatorInfo.toHuman()["nominators"].length);

1. Head to the "Developer" tab
2. Click on "JavaScript"
3. Copy the code from the previous snippet and paste it inside the code editor box
4. (Optional) Click the save icon and set a name for the code snippet, for example, "Get collator_nominator_count". This will save the code snippet locally
5. Click on the run button. This will execute the code from the editor box
6. Copy the result, as you'll need it when initiating a nomination

Get your Number of Existing Nominations

If you've never made a nomination from your address you can skip this section. However, if you're unsure how many existing nominations you have, you'll want to run the following JavaScript code snippet to get nomination_count from within PolkadotJS:

// Simple script to get your number of existing nominations.
// Remember to replace YOUR_ADDRESS_HERE with your nominator address.
const yourNominatorAccount = 'YOUR_ADDRESS_HERE'; 
const nominatorInfo = await api.query.parachainStaking.nominatorState2(yourNominatorAccount);
console.log(nominatorInfo.toHuman()["nominations"].length);

1. Head to the "Developer" tab
2. Click on "JavaScript"
3. Copy the code from the previous snippet and paste it inside the code editor box
4. (Optional) Click the save icon and set a name for the code snippet, for example, "Get existing nominations". This will save the code snippet locally
5. Click on the run button. This will execute the code from the editor box
6. Copy the result, as you'll need it when initiating a nomination

How to Nominate a Collator

This section goes over the process of nominating collators. The tutorial will use the following collators as a reference:

Variable		Address
Collator 1		0x4c5A56ed5A4FF7B09aA86560AfD7d383F4831Cce
Collator 2		0x623c9E50647a049F92090fe55e22cC0509872FB6

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.

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:

To nominate a collator, 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 parachainStaking 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 nominate extrinsic
4. Set the collator's address you want to nominate. In this case, it is set to 0x4c5A56ed5A4FF7B09aA86560AfD7d383F4831Cce
5. Set the number of tokens you want to stake
6. Input the collator_nominator_count you retrieved above from the JavaScript console
7. Input the nomination_count you retrieved from the Javascript console. This is 0 if you haven't yet nominated a collator
8. Click the "Submit Transaction" button and sign the transaction

Note

The parameters used in steps 6 and 7 are for gas estimation purposes and do not need to be exact. However, they should not be lower than the actual values.

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.

Here, provide the following information:

1. Choose the pallet you want to interact with. In this case, it is the parachainStaking pallet
2. Choose the state to query. In this case, it is the nominatorState
3. Make sure to enable the "include option" slider
4. Send the state query by clicking on the "+" button

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.

You can follow the same steps as described to nominate other collators in the network. For example, Alice nominated 0x623c9E50647a049F92090fe55e22cC0509872FB6 as well.

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, and 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, 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 parachainStaking 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 0x623c9E50647a049F92090fe55e22cC0509872FB6
5. Click the "Submit Transaction" button and sign the transaction

Once the transaction is confirmed, you can verify that your nomination was removed in the "Chain state" option under the "Developer" tab.

Here, provide the following information:

1. Choose the pallet you want to interact with. In this case, it is the parachainStaking pallet
2. Choose the state to query. In this case, it is the nominatorState state
3. Make sure to enable the "include options" slider
4. Send the state query by clicking on the "+" button

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:

Once the transaction is confirmed, your account should not be listed in the nominatorState 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 in this page.

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.0044 tokens after two payout rounds: