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 enablesdebug_traceTransaction
,debug_traceBlockByNumber
, anddebug_traceBlockByHash
--ethapi=trace
- optional flag that enablestrace_filter
--ethapi=txpool
- optional flag that enablestxpool_content
,txpool_inspect
, andtxpool_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
, ormoonbase
(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 towasm
. 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 oftrace_filter
returns is500
-ethapi-trace-cache-duration <uint>
— sets the duration (in seconds) after which the cache oftrace_filter,
for a given block, is discarded. The default amount of time blocks are stored in the cache is300
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:
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):
# 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 to16000
. The minimum value is2000
, 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:
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:
- 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
- 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:
-
Clone the Moonbeam Runtime Overrides repository
git clone https://github.com/PureStake/moonbeam-runtime-overrides.git
-
Move the Wasm overrides into your on-chain data directory:
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
-
Delete the override files for the networks that you aren't running
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-*
-
Set user permissions for the overrides:
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 to16000
. The minimum value is2000
, 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.
[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.
| Created: October 22, 2021