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 eventually there will be Moonbeam on Polkadot. Here's how these environments are named and their corresponding chain specification file names:

Network	Hosted By	Chain Name
Moonbase Alpha	PureStake	alphanet
Moonriver	Kusama	moonriver
Moonbeam	Polkadot	not available

This guide is meant for people with experience compiling Substrate based blockchain nodes. A parachain node is similar to a typical Substrate node, but there are some differences. A Substrate parachain node will 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.

Note

Moonbase Alpha is still considered an Alphanet, and as such will not have 100% uptime. The parachain will be purged from time to time. During the development of your application, make sure you implement a method to redeploy your contracts and accounts to a fresh parachain quickly. Chain purges will be announced via our Discord channel at least 24 hours in advance.

Requirements¶

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.

Moonbase Alpha

Component		Requirement
CPU		8 Cores (Fastest per core speed)
RAM		16 GB
SSD		50 GB (to start)
Firewall		P2P port must be open to incoming traffic: - Source: Any - Destination: 30333, 30334 TCP

Moonriver

Component		Requirement
CPU		8 Cores (Fastest per core speed)
RAM		16 GB
SSD		300 GB (to start)
Firewall		P2P port must be open to incoming traffic: - Source: Any - Destination: 30333, 30334 TCP

Note

If you don't see an Imported message (without the [Relaychain] tag) when running a node, you might need to double-check your port configuration.

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.

Default Ports for a Parachain Full-Node¶

Description		Port
P2P		30333 (TCP)
RPC		9933
WS		9944
Prometheus		9615

Default Ports of Embedded Relay Chain¶

Description		Port
P2P		30334 (TCP)
RPC		9934
WS		9945
Prometheus		9616

Installation Instructions - Docker¶

A Moonbeam node can be spun up quickly using Docker. For more information on installing Docker, please visit this page. At the time of writing, the Docker version used was 19.03.6. When connecting to Moonriver on Kusama, it will take a few days to completely sync the embedded Kusama relay chain. Make sure that your system meets the requirements.

Create a local directory to store the chain data:

Moonbase Alpha

mkdir /var/lib/alphanet-data

Moonriver

mkdir /var/lib/moonriver-data

Next, make sure you set the ownership and permissions accordingly for the local directory that stores the chain data. In this case, set the necessary permissions either for a specific or current user (replace DOCKER_USER for the actual user that will run the docker command):

Moonbase Alpha

# chown to a specific user
chown DOCKER_USER /var/lib/alphanet-data

# chown to current user
sudo chown -R $(id -u):$(id -g) /var/lib/alphanet-data

Moonriver

# chown to a specific user
chown DOCKER_USER /var/lib/moonriver-data

# chown to current user
sudo chown -R $(id -u):$(id -g) /var/lib/moonriver-data

Now, execute the docker run command. If you are setting up a collator node, make sure to follow the code snippets for "Collator". Note that you have to replace YOUR-NODE-NAME in two different places.

Full Node¶

Moonbase Alpha

docker run --network="host" -v "/var/lib/alphanet-data:/data" \
-u $(id -u ${USER}):$(id -g ${USER}) \
purestake/moonbeam:v0.9.1 \
--base-path=/data \
--chain alphanet \
--name="YOUR-NODE-NAME" \
--execution wasm \
--wasm-execution compiled \
--pruning archive \
--state-cache-size 1 \
-- \
--pruning archive \
--name="YOUR-NODE-NAME (Embedded Relay)"

Moonriver

docker run --network="host" -v "/var/lib/moonriver-data:/data" \
-u $(id -u ${USER}):$(id -g ${USER}) \
purestake/moonbeam:v0.9.1 \
--base-path=/data \
--chain moonriver \
--name="YOUR-NODE-NAME" \
--execution wasm \
--wasm-execution compiled \
--pruning archive \
--state-cache-size 1 \
-- \
--pruning archive \
--name="YOUR-NODE-NAME (Embedded Relay)"

Collator¶

Moonbase Alpha

docker run --network="host" -v "/var/lib/alphanet-data:/data" \
-u $(id -u ${USER}):$(id -g ${USER}) \
purestake/moonbeam:v0.9.1 \
--base-path=/data \
--chain alphanet \
--name="YOUR-NODE-NAME" \
--validator \
--execution wasm \
--wasm-execution compiled \
--pruning archive \
--state-cache-size 1 \
-- \
--pruning archive \
--name="YOUR-NODE-NAME (Embedded Relay)"

Moonriver

docker run --network="host" -v "/var/lib/moonriver-data:/data" \
-u $(id -u ${USER}):$(id -g ${USER}) \
purestake/moonbeam:v0.9.1 \
--base-path=/data \
--chain moonriver \
--name="YOUR-NODE-NAME" \
--validator \
--execution wasm \
--wasm-execution compiled \
--pruning archive \
--state-cache-size 1 \
-- \
--pruning archive \
--name="YOUR-NODE-NAME (Embedded Relay)"

If you're using MacOS, you can find all the code snippets here.

Once Docker pulls the necessary images, your full Moonbeam (or Moonriver) node will start, displaying lots of information, such as the chain specification, node name, role, genesis state, and more:

Full Node Starting

Note

If you want to run an RPC endpoint, to connect polkadot.js.org, or to run your own application, use the flags --unsafe-rpc-external and/or --unsafe-ws-external to run the full node with external access to the RPC ports. More details are available by running moonbeam --help.

Note

You can specify a custom Prometheus port with the --prometheus-port XXXX flag (replacing XXXX with the actual port number). This is possible for both the parachain and embedded relay chain.

The command above will enable all exposed ports required for basic operation, including the P2P, and Prometheus (telemetry) ports. This command is compatible to use with the Gantree Node Watchdog telemetry. If you want to expose specific ports, enable those on the Docker run command line as shown below. However, doing so will block the Gantree Node Watchdog (telemetry) container from accessing the moonbeam container, so don't do this when running a collator unless you understand docker networking.

docker run -p 30334:30334 -p 30333:30333 -p 9933:9933 -p 9944:9944 #rest of code goes here

During the syncing process, you will see messages from both the embedded relay chain and the parachain (without a tag). These messages display a target block (live network state) and a best block (local node synced state).

Full Node Starting

Note

It will take a few days to completely sync the embedded Kusama relay chain. Make sure that your system meets the requirements.

If you followed the installation instructions for Moonbase Alpha, once synced, you will have a node of the Moonbase Alpha TestNet running locally!

If you followed the installation instructions for Moonriver, once synced, you will be connected to peers and see blocks being produced on the Moonriver network! Note that in this case you need to also sync to the Kusama relay chain, which might take a few days.

Installation Instructions - Binary¶

This section goes through the process of using the release binary and running a Moonbeam full node as a systemd service. The following steps were tested on an Ubuntu 18.04 installation. Moonbeam may work with other Linux flavors, but Ubuntu is currently the only tested version.

To manually build the binaries yourself, check out the Compile Moonbeam Binary guide.

Use the Release Binary¶

There are a couple ways to get started with the Moonbeam binary. You can compile the binary yourself, but the whole process can take around 30 minutes to install the dependencies and build the binary. If you're interested in going this route, check out the Compile the Binary page of our documentation.

Or you can use the release binary to get started right away.

Use wget to grab the latest release binary:

Moonbase Alpha

wget https://github.com/PureStake/moonbeam/releases/download/v0.9.1/moonbeam

Moonriver

wget https://github.com/PureStake/moonbeam/releases/download/v0.9.1/moonbeam

To verify that you have downloaded the correct version, you can run sha256sum moonbeam in your terminal, you should receive the following output:

Moonbase Alpha

de4cbbd849b70b2215d5fc9b67f5841d985c6bad496940a2eb3f15534e6f735f

Moonriver

de4cbbd849b70b2215d5fc9b67f5841d985c6bad496940a2eb3f15534e6f735f

Once you've retrieved the binary, you can use it to run the systemd service.

Running the Systemd Service¶

The following commands will set up everything regarding running the service.

First, let's create a service account to run the service:

Moonbase Alpha

adduser moonbase_service --system --no-create-home

Moonriver

adduser moonriver_service --system --no-create-home

Next, create a directory to store the binary and data. Make sure you set the ownership and permissions accordingly for the local directory that stores the chain data.:

Moonbase Alpha

mkdir /var/lib/alphanet-data
chown moonbase_service /var/lib/alphanet-data

Moonriver

mkdir /var/lib/moonriver-data
chown moonriver_service /var/lib/moonriver-data

Now, copy the binary built in the last section to the created folder. If you compiled the binary yourself, you'll need to copy the binary in the target directory (./target/release/moonbeam). Otherwise, copy the Moonbeam binary in the root:

Moonbase Alpha

cp ./moonbeam /var/lib/alphanet-data

Moonriver

cp ./moonbeam /var/lib/moonriver-data

The next step is to create the systemd configuration file. If you are setting up a collator node, make sure to follow the code snippets for "Collator". Note that you have to:

Replace YOUR-NODE-NAME in two different places
Double-check that the binary is in the proper path as described below (ExecStart)
Double-check the base path if you've used a different directory
Name the file /etc/systemd/system/moonbeam.service

Full Node¶

Moonbase Alpha

[Unit]
Description="Moonbase Alpha systemd service"
After=network.target
StartLimitIntervalSec=0

[Service]
Type=simple
Restart=on-failure
RestartSec=10
User=moonbase_service
SyslogIdentifier=moonbase
SyslogFacility=local7
KillSignal=SIGHUP
ExecStart=/var/lib/alphanet-data/moonbeam \
     --port 30333 \
     --rpc-port 9933 \
     --ws-port 9944 \
     --pruning=archive \
     --state-cache-size 1 \
     --base-path /var/lib/alphanet-data \
     --chain alphanet \
     --name "YOUR-NODE-NAME" \
     -- \
     --port 30334 \
     --rpc-port 9934 \
     --ws-port 9945 \
     --pruning=archive \
     --name="YOUR-NODE-NAME (Embedded Relay)"

[Install]
WantedBy=multi-user.target

Moonriver

[Unit]
Description="Moonriver systemd service"
After=network.target
StartLimitIntervalSec=0

[Service]
Type=simple
Restart=on-failure
RestartSec=10
User=moonriver_service
SyslogIdentifier=moonriver
SyslogFacility=local7
KillSignal=SIGHUP
ExecStart=/var/lib/moonriver-data/moonbeam \
     --port 30333 \
     --rpc-port 9933 \
     --ws-port 9944 \
     --pruning=archive \
     --state-cache-size 1 \
     --base-path /var/lib/moonriver-data \
     --chain moonriver \
     --name "YOUR-NODE-NAME" \
     -- \
     --port 30334 \
     --rpc-port 9934 \
     --ws-port 9945 \
     --pruning=archive \
     --name="YOUR-NODE-NAME (Embedded Relay)"

[Install]
WantedBy=multi-user.target

Collator¶

Moonbase Alpha

[Unit]
Description="Moonbase Alpha systemd service"
After=network.target
StartLimitIntervalSec=0

[Service]
Type=simple
Restart=on-failure
RestartSec=10
User=moonbase_service
SyslogIdentifier=moonbase
SyslogFacility=local7
KillSignal=SIGHUP
ExecStart=/var/lib/alphanet-data/moonbeam \
     --validator \
     --port 30333 \
     --rpc-port 9933 \
     --ws-port 9944 \
     --pruning=archive \
     --state-cache-size 1 \
     --base-path /var/lib/alphanet-data \
     --chain alphanet \
     --name "YOUR-NODE-NAME" \
     -- \
     --port 30334 \
     --rpc-port 9934 \
     --ws-port 9945 \
     --pruning=archive \
     --name="YOUR-NODE-NAME (Embedded Relay)"

[Install]
WantedBy=multi-user.target

Moonriver

[Unit]
Description="Moonriver systemd service"
After=network.target
StartLimitIntervalSec=0

[Service]
Type=simple
Restart=on-failure
RestartSec=10
User=moonriver_service
SyslogIdentifier=moonriver
SyslogFacility=local7
KillSignal=SIGHUP
ExecStart=/var/lib/moonriver-data/moonbeam \
     --validator \
     --port 30333 \
     --rpc-port 9933 \
     --ws-port 9944 \
     --pruning=archive \
     --state-cache-size 1 \
     --base-path /var/lib/moonriver-data \
     --chain moonriver \
     --name "YOUR-NODE-NAME" \
     -- \
     --port 30334 \
     --rpc-port 9934 \
     --ws-port 9945 \
     --pruning=archive \
     --name="YOUR-NODE-NAME (Embedded Relay)"

[Install]
WantedBy=multi-user.target

Note

You can specify a custom Prometheus port with the --prometheus-port XXXX flag (replacing XXXX with the actual port number). This is possible for both the parachain and embedded relay chain.

Almost there! Register and start the service by running:

systemctl enable moonbeam.service
systemctl start moonbeam.service

And lastly, verify the service is running:

systemctl status moonbeam.service

Service Status

You can also check the logs by executing:

journalctl -f -u moonbeam.service

Service Logs

Advanced Flags and Options¶

With the release of Moonbase Alpha v7, nodes also provide access to some non-standard RPC methods, which allow developers to inspect and debug transactions during runtime. Currently, two features are available:

Geth debug API: more specifically, the debug_traceTransaction method. This will attempt to run the transaction in the same manner as it was executed. You can read more about this RPC method in this link
OpenEthereum trace module: more specifically, the trace_filter method. This returns the trace matching a specific filter provided as input to the RPC call. You can read more about this RPC method in this link

The features mentioned above can be activated using the following flags:

--ethapi=debug: enables the Geth debug API for the debug_traceTransaction RPC call
--ethapi=trace: enables the OpenEthereum trace module for the trace_filter RPC call

Note

Debug/Trace features are still being actively developed. Because these requests are very CPU-demanding, it is recommended to run the node with the --execution=Native flag. This will use the native runtime included as part of the node executable instead of the Wasm binary stored on-chain.

You can combine both flags when running a node.

By default, the maximum number of trace entries a single request of trace_filter is allowed to return is 500. A request exceeding this limit will return an error. You can set a different maximum limit with the following flag:

--ethapi-trace-max-count <uint>: sets the maximum number of trace entries to be returned by the node

Blocks processed by requests are temporarily stored on cache for a certain amount of time (default is 300 seconds), after which they are deleted. You can set a different time for deletion with the following flag:

-ethapi-trace-cache-duration <uint>: sets the duration (in seconds) after which the cache of trace_filter, for a given block, is discarded

Updating the Client¶

As Moonbeam development continues, it will sometimes be necessary to upgrade your node software. Node operators will be notified on our Discord channel when upgrades are available and whether they are necessary (some client upgrades are optional). The upgrade process is straightforward and is the same for a full node or collator.

First, stop the docker container or systemd service:

sudo docker stop `CONTAINER_ID`
# or
sudo systemctl stop moonbeam

Then, install the new version by repeating the steps described before, making sure that you are using the latest tag available. After updating, you can start the service again.

Purging the Chain¶

Occasionally Moonbase Alpha might be purged and reset around major upgrades. As always, node operators will be notified in advance (via our Discord channel) if this upgrade is accompanied by a purge. You can also purge your node if your individual data directory becomes corrupted.

To do so, first stop the docker container or systemd service:

sudo docker stop `CONTAINER_ID`
# or
sudo systemctl stop moonbeam

Next, remove the content of the folder where the chain data is stored (both for the parachain and relay chain):

sudo rm -rf /var/lib/alphanet-data/*

Lastly, install the newest version by repeating the steps described before, making sure you are using the latest tag available. If so, you can start a new node with a fresh data directory.

Telemetry¶

To enable your Moonbase Alpha or Moonriver node's telemetry server, you can follow this tutorial.

Running telemetry on a full node is not necessary. However, it is a requirement to do so for collators.

Also, you can check out current Moonbase Alpha telemetry and Moonriver telemetry data.

Logs and Troubleshooting¶

You will see logs from both the relay chain as well as 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 is often upgraded. 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.