Skip to content

Run a Collator on Moonbeam

Collator Moonbeam Banner

Introduction

Collators are members of the network that maintain the parachains they take part in. They run a full node (for both their particular parachain and the relay chain), and they produce the state transition proof for relay chain validators.

Users can spin up full nodes on Moonbase Alpha and Moonriver and activate the collate feature to participate in the ecosystem as collators.

Moonbeam uses the Nimbus Parachain Consensus Framework. This provides a two-step filter to allocate collators to a block production slot:

  • The parachain staking filter selects the top 32 collators on Moonbase Alpha and the top 40 collators on Moonriver in terms of tokens staked in each network. This filtered pool is called selected candidates, and selected candidates are rotated every round
  • The fixed size subset filter picks a pseudo-random subset of the previously selected candidates for each block production slot

This guide will take you through the following steps:

Technical Requirements

From a technical perspective, collators must meet the following requirements:

  • Have a full node running with the collation options. To do so, follow the spin up a full node tutorial, considering the specific code snippets for collators
  • Enable the telemetry server for your full node. To do so, follow the telemetry tutorial

Accounts and Staking Requirements

Similar to Polkadot validators, you need to create an account. For Moonbeam, this is an H160 account or basically an Ethereum style account from which you hold the private keys. In addition, you will need a minimum amount of tokens staked to be considered eligible (become a candidate). Only a certain amount of the top collators by nominated stake will be in the active set.

Variable Value
Bond Amount 1000 DEV
Active set size 32 collators
Variable Value
Bond Amount 1000 MOVR
Active set size 40 collators

Account in Polkadot.js

A collator has an account associated with its collation activities. This account mapped to an author ID to identify him as a block producer and send the payouts from block rewards.

Currently, you have two ways of proceeding in regards having an account in Polkadot.js:

  • Importing an existing (or create a new) H160 account from external wallets or services such as MetaMask and MathWallet
  • Create a new H160 account with Polkadot.js

Once you have an H160 account imported to Polkadot.js, you should see it under the "Accounts" tab. Make sure you have your public address at hand (PUBLIC_KEY), as it is needed to configure your deploy your full node with the collation options.

Account in Polkadot.js

Become a Collator Candidate

Before getting started, it's important to note some of the timings of different actions related to collation activities:

Variable Value
Join/leave collator candidates 2 rounds (4 hours)
Add/remove nominations 1 rounds (2 hours)
Rewards payouts (after current round) 2 rounds (4 hours)
Variable Value
Join/leave collator candidates 2 rounds (4 hours)
Add/remove nominations 1 rounds (2 hours)
Rewards payouts (after current round) 2 rounds (4 hours)

Note

The values presented in the previous table are subject to change in future releases.

Get the Size of the Candidate Pool

First, you need to get the candidatePool size (this can change thru governance) 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 Polkadot.js:

// Simple script to get candidate pool size
const candidatePool = await api.query.parachainStaking.candidatePool();
console.log(`Candidate pool size is: ${candidatePool.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 candidatePool size". 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 joining the candidate pool

Get Number of Candidates

Join the Candidate Pool

Once your node is running and in sync with the network, you become a collator candidate (and join the candidate pool). Depending on which network you are connected to, head to Polkadot.js for Moonbase Alpha or Moonriver and take the following steps:

  1. Navigate to the "Developers" tab and click on "Extrinsics"
  2. Select the account you want to be associated with your collation activities
  3. Confirm your collator account is funded with at least the minimum stake required plus some extra for transaction fees
  4. Select parachainStaking pallet under the "submit the following extrinsics" menu
  5. Open the drop-down menu, which lists all the possible extrinsics related to staking, and select the joinCandidates() function
  6. Set the bond to at least the minimum amount to be considered a collator candidate. Only collator bond counts for this check. Additional nominations do not count
  7. Set the candidate count as the candidate pool size. To learn how to retrieve this value, check this section
  8. Submit the transaction. Follow the wizard and sign the transaction using the password you set for the account

Join Collators pool Polkadot.js

Note

Function names and the minimum bond requirement are subject to change in future releases.

As mentioned before, only the top 32 collators on Moonbase Alpha and the top 40 collators on Moonriver by nominated stake will be in the active set.

Stop Collating

Similar to Polkadot's chill() function, to leave the collator's candidate pool, follow the same steps as before but select the leaveCandidates() function in step 5.

Session Keys

With the release of Moonbase Alpha v8, collators will sign blocks using an author ID, which is basically a session key. To match the Substrate standard, Moonbeam collator's session keys are SR25519. This guide will show you how you can create/rotate your session keys associated to your collator node.

First, make sure you're running a collator node and you have exposed the RPC ports. Once you have your collator node running, your terminal should print similar logs:

Collator Terminal Logs

Next, session keys can be rotated by sending an RPC call to the HTTP endpoint with the author_rotateKeys method. For reference, if your collator's HTTP endpoint is at port 9933, the JSON-RPC call might look like this:

curl http://127.0.0.1:9933 -H \
"Content-Type:application/json;charset=utf-8" -d \
  '{
    "jsonrpc":"2.0",
    "id":1,
    "method":"author_rotateKeys",
    "params": []
  }'

The collator node should respond with the corresponding public key of the new author ID (session key).

Collator Terminal Logs RPC Rotate Keys

Make sure you write down this public key of the author ID. Next, this will be mapped to an H160 Ethereum-styled address to which the block rewards are paid.

Map Author ID to your Account

Once you've generated your author ID (session keys), the next step is to map it to your H160 account (an Ethereum-styled address). Make sure you hold the private keys to this account, as this is where the block rewards are paid out to.

There is a bond that is sent when mapping your author ID with your account. This bond is per author ID registered. The bond set is as follows:

  • Moonbase Alpha - 100 DEV tokens
  • Moonriver - 100 MOVR tokens.

The authorMapping module has the following extrinsics programmed:

  • addAssociation(address authorID) — maps your author ID to the H160 account from which the transaction is being sent, ensuring is the true owner of its private keys. It requires a bond
  • clearAssociation(address authorID) — clears the association of an author ID to the H160 account from which the transaction is being sent, which needs to be the owner of that author ID. Also refunds the bond
  • updateAssociation(address oldAuthorID, address newAuthorID) — updates the mapping from an old author ID to a new one. Useful after a key rotation or migration. It executes both the add and clear association extrinsics atomically, enabling key rotation without needing a second bond

The module also adds the following RPC calls (chain state):

  • mapping(address optionalAuthorID) — displays all mappings stored on-chain, or only that related to the input if provided

Mapping Extrinsic

To map your author ID to your account, you need to be inside the candidate pool. Once you are a collator candidate, you need to send a mapping extrinsic (transaction). Note that this will bond tokens per author ID registered. To do so, take the following steps:

  1. Head to the "Developer" tab
  2. Select the "Extrinsics" option
  3. Choose the account that you want to map your author ID to be associated with, from which you'll sign this transaction
  4. Select the authorMapping extrinsic
  5. Set the method to addAssociation()
  6. Enter the author ID. In this case, it was obtained via the RPC call author_rotateKeys in the previous section
  7. Click on "Submit Transaction"

Author ID Mapping to Account Extrinsic

If the transaction is successful, you will see a confirmation notification on your screen. If not, make sure you've joined the candidate pool.

Author ID Mapping to Account Extrinsic Successful

Checking the Mappings

You can also check the current on-chain mappings by verifying the chain state. To do so, take the following steps:

  1. Head to the "Developer" tab
  2. Select the "Chain state" option
  3. Choose authorMapping as the state to query
  4. Select the mappingWithDeposit method
  5. Provide an author ID to query. Optinally, you can disable the slider to retrieve all mappings
  6. Click on the "+" button to send the RPC call

Author ID Mapping Chain State

You should be able to see the H160 account associated with the author ID provided. If no author ID was included, this would return all the mappings stored on-chain.