Run a Node on Moonbeam¶

Introduction¶

Running a full node on a Moonbeam-based network allows you to connect to the network, sync with a bootnode, obtain local access to RPC endpoints, author blocks on the parachain, and more.

There are multiple deployments of Moonbeam, including the Moonbase Alpha TestNet, Moonriver on Kusama, and Moonbeam on Polkadot. Here's how these environments are named and their corresponding chain specification file names:

Requirements¶

Running a parachain node is similar to a typical Substrate node, but there are some differences. A Substrate parachain node is a bigger build because it contains code to run the parachain itself, as well as code to sync the relay chain, and facilitate communication between the two. As such, this build is quite large and may take over 30 min and require 32GB of memory.

The minimum specs recommended to run a node are shown in the following table. For our Kusama and Polkadot MainNet deployments, disk requirements will be higher as the network grows.

Running Ports¶

As stated before, the relay/parachain nodes will listen on multiple ports. The default Substrate ports are used in the parachain, while the relay chain will listen on the next higher port.

The only ports that need to be open for incoming traffic are those designated for P2P. Collators must not have RPC or WS ports opened.

Default Ports for a Parachain Full-Node¶

Default Ports of Embedded Relay Chain¶

Installation¶

There are a couple different guides to help you get started running a Moonbeam-based node:

• Using Docker - this method provides a quick and easy way to get started with a Docker container
• Using Systemd - this method is recommended for those with experience compiling a Substrate node

Debug, Trace and TxPool APIs¶

You can also gain access to some non-standard RPC methods by running a tracing node, which allow developers to inspect and debug transactions during runtime. Tracing nodes use a different Docker image than a standard Moonbase Alpha, Moonriver, or Moonbeam node. Check out the Run a Tracing Node guide and be sure to switch to the right network tab throughout the instructions. Then to interact with your tracing node, check out the Debug & Trace guide.

Lazy Loading¶

Lazy loading lets a Moonbeam node operate while downloading network state in the background, eliminating the need to wait for full synchronization before use. You can activate lazy loading with the following flag:

• --lazy-loading-remote-rpc - allows lazy loading by relying on a specified RPC for network state until the node is fully synchronized e.g. --lazy-loading-remote-rpc 'INSERT-RPC-URL'

Upon spooling up a node with this feature, you'll see output like the following:

You can further customize your use of the lazy loading functionality with the following optional parameters:

• --lazy-loading-block - specifies a block hash from which to start loading data. If not provided, the latest block will be used
• --lazy-loading-delay-between-requests - the delay (in milliseconds) between RPC requests when using lazy loading. This parameter controls the amount of time to wait between consecutive RPC requests. This can help manage request rate and avoid overwhelming the server. Default value is 100 milliseconds
• --lazy-loading-max-retries-per-request - the maximum number of retries for an RPC request when using lazy loading. Default value is 10 retries
• --lazy-loading-runtime-override - path to a WASM file to override the runtime when forking. If not provided, it will fetch the runtime from the block being forked
• --lazy-loading-state-overrides - path to a JSON file containing state overrides to be applied when forking

The state overrides file should define the respective pallet, storage item, and value that you seek to override as follows:

[
 {
     "pallet": "System",
     "storage": "SelectedCandidates",
     "value": "0x04f24ff3a9cf04c71dbc94d0b566f7a27b94566cac"
 }
]

Logs and Troubleshooting¶

You will see logs from both the relay chain and the parachain. The relay chain will be prefixed by [Relaychain], while the parachain has no prefix.

P2P Ports Not Open¶

If you don't see an Imported message (without the [Relaychain] tag), you need to check the P2P port configuration. P2P port must be open to incoming traffic.

In Sync¶

Both chains must be in sync at all times, and you should see either Imported or Idle messages and have connected peers.

Genesis Mismatching¶

The Moonbase Alpha TestNet may need to be purged and upgraded once in a while. Consequently, you may see the following message:

DATE [Relaychain] Bootnode with peer id `ID` is on a different
chain (our genesis: GENESIS_ID theirs: OTHER_GENESIS_ID)

This typically means that you are running an older version and will need to upgrade.

We announce the upgrades (and corresponding chain purge) via our Discord channel at least 24 hours in advance.

Instructions for purging chain data will vary slightly depending on how you spun up your node:

• For Docker, you can check out the Purge Your Node section of the Using Docker page
• For Systemd, you can take a look at the Purge Your Node section of the Using Systemd page