Run a Tracing Node

Introduction

Geth's debug and txpool APIs and OpenEthereum's trace module provide non-standard RPC methods for getting a deeper insight into transaction processing. As part of Moonbeam's goal of providing a seamless Ethereum experience for developers, there is support for some of these non-standard RPC methods. Supporting these RPC methods is an important milestone because many projects, such as The Graph or Blockscout, rely on them to index blockchain data.

To use the supported RPC methods, you need to run a tracing node, which is slightly different than running a full node. There is a different Docker image, called purestake/moonbeam-tracing that needs to be used for tracing. Additional flags will also need to be used to tell the node which of the non-standard features to support.

This guide will show you how to get started running a tracing node on Moonbeam with the debug, txpool, and tracing flags enabled.

Checking Prerequisites

Similarly to running a regular node, you can spin up a tracing node using Docker or Systemd. If you choose to use Docker, you must install Docker if you haven't already. At the time of writing, the Docker version used was 19.03.6.

Tracing Node Flags

Spinning up a debug, txpool, or tracing node is similar to running a full node. However, there are some additional flags that you may want to enable specific tracing features:

• --ethapi=debug - optional flag that enables debug_traceTransaction, debug_traceBlockByNumber, and debug_traceBlockByHash
• --ethapi=trace - optional flag that enables trace_filter
• --ethapi=txpool - optional flag that enables txpool_content, txpool_inspect, and txpool_status
• --wasm-runtime-overrides=<path/to/overrides> - required flag for tracing that specifies the path where the local Wasm runtimes are stored. If you're using Docker, the path is as follows: /moonbeam/<network>-substitutes-tracing. Accepts the network as a parameter: moonbeam, moonriver, or moonbase (for development nodes and Moonbase Alpha)
• --runtime-cache-size 64 - required flag that configures the number of different runtime versions preserved in the in-memory cache to 64
• --execution=wasm - sets the execution strategy that should be used by all execution contexts to wasm. In other words, this enables usage of the Wasm binary stored on-chain
• --ethapi-trace-max-count <uint> — sets the maximum number of trace entries to be returned by the node. The default maximum number of trace entries a single request of trace_filter returns is 500
• -ethapi-trace-cache-duration <uint> — sets the duration (in seconds) after which the cache of trace_filter, for a given block, is discarded. The default amount of time blocks are stored in the cache is 300 seconds

Note

If you want to run an RPC endpoint, to connect to Polkadot.js Apps, 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.

Run a Tracing Node with Docker

If you haven't previously run a standard full Moonbeam node, you will need to setup a directory to store chain data:

MoonbeamMoonriverMoonbase Alpha

mkdir /var/lib/moonbeam-data

mkdir /var/lib/moonriver-data

mkdir /var/lib/alphanet-data

Before getting started, you'll need to set the necessary permissions either for a specific or current user (replace DOCKER_USER for the actual user that will run the docker command):

MoonbeamMoonriverMoonbase Alpha

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

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

# 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

# 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

Instead of the standard purestake/moonbeam docker image, you will need to use purestake/moonbeam-tracing image. The latest supported version can be found on the Docker Hub for the moonbeam-tracing image.

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

• Replace YOUR-NODE-NAME in two different places
• Replace <50% RAM in MB> for 50% of the actual RAM your server has. For example, for 32 GB RAM, the value must be set to 16000. The minimum value is 2000, but it is below the recommended specs

Note

For client versions prior to v0.27.0, the --state-pruning flag was named --pruning.

For client versions prior to v0.30.0, --rpc-port was used to specify the port for HTTP connections and --ws-port was used to specify the port for WS connections. As of client v0.30.0, the --rpc-port has been deprecated and the --ws-port flag is for both HTTP and WS connections. Similarly, the --rpc-max-connections flag has been deprecated and is now hardcoded to 100. You can use --ws-max-connections to adjust the combined HTTP and WS connection limit.

The complete command for running a tracing node is as follows:

MoonbeamMoonriverMoonbase AlphaMoonbeam Dev Node

docker run --network="host" -v "/var/lib/moonbeam-data:/data" \
-u $(id -u ${USER}):$(id -g ${USER}) \
purestake/moonbeam-tracing:v0.31.1-2302-latest \
--base-path=/data \
--chain moonbeam \
--name="YOUR-NODE-NAME" \
--state-pruning archive \
--trie-cache-size 0 \
--db-cache <50% RAM in MB> \
--ethapi=debug,trace,txpool \
--wasm-runtime-overrides=/moonbeam/moonbeam-substitutes-tracing \
--runtime-cache-size 64 \
-- \
--execution wasm \
--name="YOUR-NODE-NAME (Embedded Relay)"

docker run --network="host" -v "/var/lib/moonriver-data:/data" \
-u $(id -u ${USER}):$(id -g ${USER}) \
purestake/moonbeam-tracing:v0.31.1-2302-latest \
--base-path=/data \
--chain moonriver \
--name="YOUR-NODE-NAME" \
--state-pruning archive \
--trie-cache-size 0 \
--db-cache <50% RAM in MB> \
--ethapi=debug,trace,txpool \
--wasm-runtime-overrides=/moonbeam/moonriver-substitutes-tracing \
--runtime-cache-size 64 \
-- \
--execution wasm \
--name="YOUR-NODE-NAME (Embedded Relay)"

docker run --network="host" -v "/var/lib/alphanet-data:/data" \
-u $(id -u ${USER}):$(id -g ${USER}) \
purestake/moonbeam-tracing:v0.31.1-2302-latest \
--base-path=/data \
--chain alphanet \
--name="YOUR-NODE-NAME" \
--state-pruning archive \
--trie-cache-size 0 \
--db-cache <50% RAM in MB> \
--ethapi=debug,trace,txpool \
--wasm-runtime-overrides=/moonbeam/moonbase-substitutes-tracing \
--runtime-cache-size 64 \
-- \
--execution wasm \
--name="YOUR-NODE-NAME (Embedded Relay)"

docker run --network="host" \
-u $(id -u ${USER}):$(id -g ${USER}) \
purestake/moonbeam-tracing:v0.31.1-2302-latest \
--name="YOUR-NODE-NAME" \
--ethapi=debug,trace,txpool \
--wasm-runtime-overrides=/moonbeam/moonbase-substitutes-tracing \
--runtime-cache-size 64 \
--dev

You should see a terminal log similar to the following if you spun up a Moonbase Alpha tracing node:

Run a Tracing Node with Systemd

When you run a node using Systemd, you'll need to start off by setting up the Moonbeam binary. To do so you'll need to follow the instructions on the Run a Node on Moonbeam Using Systemd page. In general, you'll need to:

1. Setup the Moonbeam binary by following the Release Binary instructions. Or if you want to compile the binary yourself, you can follow the Compile the Binary instructions
2. Follow the instructions in the Setup the Service instructions

Once you've finished going through the instructions in those specific sections, you can continue on to the below instructions.

Setup the Wasm Overrides

You'll need to create a directory for the Wasm runtime overrides and obtain them from the Moonbeam Runtime Overrides repository on GitHub.

You can clone the repository to any location on your local machine. For simplicity, you can use the directory where you're storing on-chain data. To set up the Wasm override files, you can take the following steps:

1. Clone the Moonbeam Runtime Overrides repository

   git clone https://github.com/PureStake/moonbeam-runtime-overrides.git
   

2. Move the Wasm overrides into your on-chain data directory:

   MoonbeamMoonriverMoonbase Alpha

   mv moonbeam-runtime-overrides/wasm /var/lib/moonbeam-data
   

   mv moonbeam-runtime-overrides/wasm /var/lib/moonriver-data
   

   mv moonbeam-runtime-overrides/wasm /var/lib/alphanet-data
   

3. Delete the override files for the networks that you aren't running

   MoonbeamMoonriverMoonbase Alpha

   rm /var/lib/moonbeam-data/wasm/moonriver-runtime-* &&  rm /var/lib/moonbeam-data/wasm/moonbase-runtime-*
   

   rm /var/lib/moonriver-data/wasm/moonbeam-runtime-* &&  rm /var/lib/moonriver-data/wasm/moonbase-runtime-*
   

   rm /var/lib/alphanet-data/wasm/moonbeam-runtime-* &&  rm /var/lib/alphanet-data/wasm/moonriver-runtime-*
   

4. Set user permissions for the overrides:

   MoonbeamMoonriverMoonbase Alpha

   chmod +x /var/lib/moonbeam-data/wasm/*
   chown moonbeam_service /var/lib/moonbeam-data/wasm/*
   

   chmod +x /var/lib/moonriver-data/wasm/*
   chown moonriver_service /var/lib/moonriver-data/wasm/*
   

   chmod +x /var/lib/alphanet-data/wasm/*
   chown moonbase_service /var/lib/alphanet-data/wasm/*
   

Create the Configuration File

The next step is to create the systemd configuration file, you'll need to:

• Replace YOUR-NODE-NAME in two different places
• Replace <50% RAM in MB> for 50% of the actual RAM your server has. For example, for 32 GB RAM, the value must be set to 16000. The minimum value is 2000, but it is below the recommended specs
• 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

Note

For client versions prior to v0.27.0, the --state-pruning flag was named --pruning.

For client versions prior to v0.30.0, --rpc-port was used to specify the port for HTTP connections and --ws-port was used to specify the port for WS connections. As of client v0.30.0, the --rpc-port has been deprecated and the --ws-port flag is for both HTTP and WS connections. Similarly, the --rpc-max-connections flag has been deprecated and is now hardcoded to 100. You can use --ws-max-connections to adjust the combined HTTP and WS connection limit.

MoonbeamMoonriverMoonbase Alpha

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

[Service]
Type=simple
Restart=on-failure
RestartSec=10
User=moonbeam_service
SyslogIdentifier=moonbeam
SyslogFacility=local7
KillSignal=SIGHUP
ExecStart=/var/lib/moonbeam-data/moonbeam \
     --execution wasm \
     --state-pruning=archive \
     --trie-cache-size 0 \
     --db-cache <50% RAM in MB> \
     --base-path /var/lib/moonbeam-data \
     --ethapi=debug,trace,txpool \
     --wasm-runtime-overrides=/var/lib/moonbeam-data/wasm \
     --runtime-cache-size 64 \
     --chain moonbeam \
     --name "YOUR-NODE-NAME" \
     -- \
     --execution wasm \
     --name="YOUR-NODE-NAME (Embedded Relay)"

[Install]
WantedBy=multi-user.target

[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 \
     --execution wasm \
     --state-pruning=archive \
     --trie-cache-size 0 \
     --db-cache <50% RAM in MB> \
     --base-path /var/lib/moonriver-data \
     --ethapi=debug,trace,txpool \
     --wasm-runtime-overrides=/var/lib/moonriver-data/wasm \
     --runtime-cache-size 64 \
     --chain moonriver \
     --name "YOUR-NODE-NAME" \
     -- \
     --execution wasm \
     --name="YOUR-NODE-NAME (Embedded Relay)"

[Install]
WantedBy=multi-user.target

[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 \
     --execution wasm \
     --state-pruning=archive \
     --trie-cache-size 0 \
     --db-cache <50% RAM in MB> \
     --base-path /var/lib/alphanet-data \
     --ethapi=debug,trace,txpool \
     --wasm-runtime-overrides=/var/lib/alphanet-data/wasm \
     --runtime-cache-size 64 \
     --chain alphanet \
     --name "YOUR-NODE-NAME" \
     -- \
     --execution wasm \
     --name="YOUR-NODE-NAME (Embedded Relay)"

[Install]
WantedBy=multi-user.target

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.

Run the Service

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

You can also run the following command to see logs of the tracing node spinning up:

journalctl -f -u moonbeam.service

Your terminal should display logs similar to the following:

Using a Tracing Node

To explore the different non-standard RPC methods available on Moonbeam, and how to use these methods with a tracing node, check out the Debug & Trace guide.

Last update: April 19, 2023
| Created: October 22, 2021