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, 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 moonbeamfoundation/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, debug_traceBlockByHash, and debug_traceCall
• --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
• --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

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:

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 INSERT_DOCKER_USER for the actual user that will run the docker command):

# chown to a specific user
chown INSERT_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 INSERT_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 INSERT_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 moonbeamfoundation/moonbeam docker image, you will need to use moonbeamfoundation/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 INSERT_YOUR_NODE_NAME in two different places
• Replace INSERT_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

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

docker run --network="host" -v "/var/lib/moonbeam-data:/data" \
-u $(id -u ${USER}):$(id -g ${USER}) \
moonbeamfoundation/moonbeam-tracing:v0.41.0-3300-d3e6 \
--base-path /data \
--chain moonbeam \
--name "INSERT_YOUR_NODE_NAME" \
--state-pruning archive \
--trie-cache-size 1073741824 \
--db-cache INSERT_RAM_IN_MB \
--ethapi debug,trace,txpool \
--wasm-runtime-overrides /moonbeam/moonbeam-substitutes-tracing \
--runtime-cache-size 64 \
-- \
--name "INSERT_YOUR_NODE_NAME (Embedded Relay)"

docker run --network="host" -v "/var/lib/moonriver-data:/data" \
-u $(id -u ${USER}):$(id -g ${USER}) \
moonbeamfoundation/moonbeam-tracing:v0.41.0-3300-d3e6 \
--base-path /data \
--chain moonriver \
--name INSERT_YOUR_NODE_NAME" \
--state-pruning archive \
--trie-cache-size 1073741824 \
--db-cache INSERT_RAM_IN_MB \
--ethapi debug,trace,txpool \
--wasm-runtime-overrides /moonbeam/moonriver-substitutes-tracing \
--runtime-cache-size 64 \
-- \
--name "INSERT_YOUR_NODE_NAME (Embedded Relay)"

docker run --network="host" -v "/var/lib/alphanet-data:/data" \
-u $(id -u ${USER}):$(id -g ${USER}) \
moonbeamfoundation/moonbeam-tracing:v0.42.1-3400-3ebd \
--base-path /data \
--chain alphanet \
--name "INSERT_YOUR_NODE_NAME" \
--state-pruning archive \
--trie-cache-size 1073741824 \
--db-cache INSERT_RAM_IN_MB \
--ethapi debug,trace,txpool \
--wasm-runtime-overrides /moonbeam/moonbase-substitutes-tracing \
--runtime-cache-size 64 \
-- \
--name "INSERT_YOUR_NODE_NAME (Embedded Relay)"

docker run --network="host" \
-u $(id -u ${USER}):$(id -g ${USER}) \
moonbeamfoundation/moonbeam-tracing:v0.41.0-3300-d3e6 \
--name "INSERT_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/moonbeam-foundation/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 INSERT_YOUR_NODE_NAME in two different places
• Replace INSERT_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

[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 \
     --state-pruning archive \
     --trie-cache-size 1073741824 \
     --db-cache INSERT_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 "INSERT_YOUR_NODE_NAME" \
     -- \
     --name "INSERT_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 \
     --state-pruning archive \
     --trie-cache-size 1073741824 \
     --db-cache INSERT_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 "INSERT_YOUR_NODE_NAME" \
     -- \
     --name "INSERT_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 \
     --state-pruning archive \
     --trie-cache-size 1073741824 \
     --db-cache INSERT_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 "INSERT_YOUR_NODE_NAME" \
     -- \
     --name "INSERT_YOUR_NODE_NAME (Embedded Relay)"

[Install]
WantedBy=multi-user.target

Run the Service¶

Register and start the service by running:

systemctl enable moonbeam.service
systemctl start moonbeam.service

And lastly, verify that 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.