Run a Node on Moonbeam¶

Introduction¶

With the release of Moonbase Alpha v6, you can spin up a node that connects to the Moonbase Alpha TestNet, syncs with a bootnode, provides local access your RPC endpoints, and even authors blocks on the parachain.

In our TestNet, the relay chain is hosted and run by PureStake. But as development progresses, there will also be deployments in Kusama and then Polkadot. Here's how these upcoming environments will be named and their corresponding chain specification files name:

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

This guide is meant for people with experience running Substrate based chains. Running a parachain is similar to running a Substrate node with a few differences. A Substrate parachain node will run two processes: one to sync the relay chain and one to sync the parachain. As such, many things are doubled, for example, the database directory, the ports used, the log lines, and more.

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.

Component		Requirement
CPU		8 Cores (early development phase - not optimized yet)
RAM		16 GB (early development phase - not optimized yet)
SSD		50 GB (to start in our TestNet)
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 Moonbase Alpha 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.

First, create a local directory to store the chain data:

mkdir /var/lib/alphanet-data

Next, set the necessary permissions either for a specific or current user (replace DOCKER_USER for the actual user that will run the docker command):

# 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

Note

Make sure you set the ownership and permissions accordingly for the local directory that stores the chain data.

Now, execute the docker run command. Note that you have to:

Replace YOUR-NODE-NAME in two different places.
For collators, replace PUBLIC_KEY with the public address that will be associated with collation activities.

Note

If you are setting up a collator node, make sure to follow the code snippets for "Collator".

Full Node¶

Ubuntu

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

MacOS

docker run -p 9933:9933 -p 9944:9944 -v "/var/lib/alphanet-data:/data" \
-u $(id -u ${USER}):$(id -g ${USER}) \
purestake/moonbeam:v0.7.0 \
--ws-external \
--rpc-external \
--rpc-cors all \
--base-path=/data \
--chain alphanet \
--name="YOUR-NODE-NAME" \
--execution wasm \
--wasm-execution compiled \
--in-peers 200 \
--out-peers 200 \
--pruning archive \
--state-cache-size 1 \
-- \
--pruning archive \
--name="YOUR-NODE-NAME (Embedded Relay)"

Collator¶

Ubuntu

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

MacOS

docker run -p 9933:9933 -p 9944:9944 -v "/var/lib/alphanet-data:/data" \
-u $(id -u ${USER}):$(id -g ${USER}) \
purestake/moonbeam:v0.7.0 \
--ws-external \
--rpc-external \
--base-path=/data \
--chain alphanet \
--name="YOUR-NODE-NAME" \
--collator \
--author-id PUBLIC_KEY \
--execution wasm \
--wasm-execution compiled \
--in-peers 200 \
--out-peers 200 \
--pruning archive \
--state-cache-size 1 \
-- \
--pruning archive \
--name="YOUR-NODE-NAME (Embedded Relay)"

Once Docker pulls the necessary images, your Moonbase Alpha full 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 are having issues with the default telemetry, you can add the flag --no-telemetry to run the full node without telemetry activated.

Note

You can specify a custom Prometheus port with the --promethues-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, including the P2P, RPC, 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 (TestNet) and a best block (local node synced state).

Full Node Starting

Once synced, you have a node of the Moonbase Alpha TestNet running locally!

Installation Instructions - Binary¶

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

Compiling the Binary¶

The following commands will build the latest release of the Moonbeam parachain.

First, let's start by cloning the moonbeam repo.

git clone https://github.com/PureStake/moonbeam
cd moonbeam

Let's check out the latest release:

git checkout tags/$(git tag | tail -1)

Next, install Substrate and all its prerequisites, including Rust, by executing:

curl https://getsubstrate.io -sSf | bash -s -- --fast

Lastly, build parachain binary:

cargo build --release

Compiling Binary

If a cargo not found error shows up in the terminal, manually add Rust to your system path or restart your system:

source $HOME/.cargo/env

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:

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

Next, create a directory to store the binary and data and set the necessary permissions:

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

Note

Make sure you set the ownership and permissions accordingly for the local directory that stores the chain data.

Now, copy the binary built in the last section to the created folder:

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

The next step is to create the systemd configuration file. 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
For collators, replace PUBLIC-KEY with the public key of your H160 Ethereum address created above
Name the file /etc/systemd/system/moonbeam.service

Note

If you are setting up a collator node, make sure to follow the code snippets for "Collator".

Full Node

[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 \
     --parachain-id 1000 \
     --port 30333 \
     --rpc-port 9933 \
     --ws-port 9944 \
     --pruning=archive \
     --state-cache-size 1 \
     --unsafe-rpc-external \
     --unsafe-ws-external \
     --rpc-methods=Safe \
     --rpc-cors all \
     --log rpc=info \
     --base-path /var/lib/alphanet-data \
     --chain alphanet \
     --name "YOUR-NODE-NAME" \
    --in-peers 200 \
    --out-peers 200 \
     -- \
     --port 30334 \
     --rpc-port 9934 \
     --ws-port 9945 \
     --pruning=archive \
     --name="YOUR-NODE-NAME (Embedded Relay)"

[Install]
WantedBy=multi-user.target

Collator

[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 \
     --parachain-id 1000 \
     --collator \
     --author-id PUBLIC_KEY \
     --port 30333 \
     --rpc-port 9933 \
     --ws-port 9944 \
     --pruning=archive \
     --state-cache-size 1 \
     --unsafe-rpc-external \
     --unsafe-ws-external \
     --rpc-methods=Safe \
     --log rpc=info \
     --base-path /var/lib/alphanet-data \
     --chain alphanet \
     --name "YOUR-NODE-NAME" \
     --in-peers 200 \
     --out-peers 200 \
     -- \
     --port 30334 \
     --rpc-port 9934 \
     --ws-port 9945 \
     --pruning=archive \
     --name="YOUR-NODE-NAME (Embedded Relay)"

[Install]
WantedBy=multi-user.target

Note

If you are having issues with the default telemetry, you can add the flag --no-telemetry to run the full node without telemetry activated.

Note

You can specify a custom Prometheus port with the --promethues-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 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 see current Moonbase Alpha telemetry information visiting this link.

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.

We Want to Hear From You¶

If you have any feedback regarding running a full node or any other Moonbeam-related topic, feel free to reach out through our official development Discord server.