• m5a.large or any equivalent instance type

Bare Metal:

  • 16GB RAM

  • 4 vCPUs

  • At least 150 GB of storage - make sure it's extendable


Running a Gnosis Chiado Testnet node is pretty straightforward, as it is supported under both Openethereum and Nethermind clients. After consulting with the Gnosis team, we decided to switch from Openethereum to Nethermind because the client is more future-proof and running the node from scratch using it would be the best option overall.

We're going to assume you are already logged into your Virtual Machine as a privileged user or as the root user.

All we need to do in this case is download the Nethermind client and extract it as below (please make sure you have unzip installed):

Since the Eth 2.0 merge happened, the instructions changed a bit. We will now need to run 2 components: the Consensus Layer (Prysm) component and the Execution Layer (Nethermind) component.

The official docs are really well-written, allowing us to run a node without too many modifications. Please check https://docs.gnosischain.com/node/guide/.

I'll also give a quick rundown of the steps below:

First of all, we need to create the following directory structure - we will assume you are already in the /root directory:

mkdir gnosis && cd gnosis &&
mkdir jwtsecret && mkdir execution && mkdir consensus &&
cd consensus &&
mkdir data && mkdir keystores && mkdir validators &&
cd ..

After that, we will need to create a JWT token that will allow secure communication between the two layers (Consensus and Execution):

openssl rand -hex 32 | tr -d "\n" > "./jwtsecret/jwt.hex"

Now we can proceed with the steps for installing the Execution client (Nethermind):

This command will install the prerequisites:

sudo apt-get update && sudo apt-get install libsnappy-dev libc6-dev libc6 unzip -y

We can download the latest version of the Nethermind binary as below:


Unzip the binary:

unzip nethermind-1.17.1-120f4c8d-linux-x64.zip -d execution

Change directory into the execution directory:

cd execution

Run Nethermind:

/root/gnosis/execution/Nethermind.Runner --JsonRpc.Enabled true --config chiado_archive --Init.WebSocketsEnabled true --JsonRpc.Host --HealthChecks.Enabled true --HealthChecks.UIEnabled true --JsonRpc.EnabledModules Eth,Subscribe,Trace,TxPool,Web3,Personal,Proof,Net,Parity,Health,Rpc,Admin --JsonRpc.JwtSecretFile=../jwtsecret/jwtsecret --JsonRpc.EnginePort=8551 --Metrics.Enabled true --Metrics.ExposePort 9090

Now we can move on to installing the Consensus Layer client, Lighthouse:

Download the binary:

wget https://github.com/sigp/lighthouse/releases/download/v3.5.1/lighthouse-v3.5.1-x86_64-unknown-linux-gnu.tar.gz

Extract the binary:

tar -xvf lighthouse-v3.5.1-x86_64-unknown-linux-gnu.tar.gz --directory consensus

Change directory:

cd consensus

Create the folder named network_config inside consensus and download the Chiado config files:

mkdir network_config &&
cd network_config &&
wget https://github.com/gnosischain/configs/raw/main/chiado/config.yaml &&
wget https://github.com/gnosischain/configs/raw/main/chiado/genesis.ssz &&
wget https://github.com/gnosischain/configs/raw/main/chiado/deploy_block.txt

Run Lighthouse:

/root/gnosis/consensus/lighthouse --testnet-dir=/root/gnosis/consensus/network_config bn --disable-upnp --port=9000 --http --http-address= --http-port=4000 --target-peers=50 --boot-nodes=enr:-L64QOijsdi9aVIawMb5h5PWueaPM9Ai6P17GNPFlHzz7MGJQ8tFMdYrEx8WQitNKLG924g2Q9cCdzg54M0UtKa3QIKCMxaHYXR0bmV0c4j__________4RldGgykDE2cEMCAABv__________-CaWSCdjSCaXCEi5AaWYlzZWNwMjU2azGhA8CjTkD4m1s8FbKCN18LgqlYcE65jrT148vFtwd9U62SiHN5bmNuZXRzD4N0Y3CCIyiDdWRwgiMo,enr:-L64QKYKGQj5ybkfBxyFU5IEVzP7oJkGHJlie4W8BCGAYEi4P0mmMksaasiYF789mVW_AxYVNVFUjg9CyzmdvpyWQ1KCMlmHYXR0bmV0c4j__________4RldGgykDE2cEMCAABv__________-CaWSCdjSCaXCEi5CtNolzZWNwMjU2azGhAuA7BAwIijy1z81AO9nz_MOukA1ER68rGA67PYQ5pF1qiHN5bmNuZXRzD4N0Y3CCIyiDdWRwgiMo,enr:-Ly4QJJUnV9BxP_rw2Bv7E9iyw4sYS2b4OQZIf4Mu_cA6FljJvOeSTQiCUpbZhZjR4R0VseBhdTzrLrlHrAuu_OeZqgJh2F0dG5ldHOI__________-EZXRoMpAxNnBDAgAAb___________gmlkgnY0gmlwhIuQGnOJc2VjcDI1NmsxoQPT_u3IjDtB2r-nveH5DhUmlM8F2IgLyxhmwmqW4L5k3ohzeW5jbmV0cw-DdGNwgiMog3VkcIIjKA,enr:-MK4QCkOyqOTPX1_-F-5XVFjPclDUc0fj3EeR8FJ5-hZjv6ARuGlFspM0DtioHn1r6YPUXkOg2g3x6EbeeKdsrvVBYmGAYQKrixeh2F0dG5ldHOIAAAAAAAAAACEZXRoMpAxNnBDAgAAb___________gmlkgnY0gmlwhIuQGlWJc2VjcDI1NmsxoQKdW3-DgLExBkpLGMRtuM88wW_gZkC7Yeg0stYDTrlynYhzeW5jbmV0cwCDdGNwgiMog3VkcIIjKA==,enr:-Ly4QLYLNqrjvSxD3lpAPBUNlxa6cIbe79JqLZLFcZZjWoCjZcw-85agLUErHiygG2weRSCLnd5V460qTbLbwJQsfZkoh2F0dG5ldHOI__________-EZXRoMpAxNnBDAgAAb___________gmlkgnY0gmlwhKq7mu-Jc2VjcDI1NmsxoQP900YAYa9kdvzlSKGjVo-F3XVzATjOYp3BsjLjSophO4hzeW5jbmV0cw-DdGNwgiMog3VkcIIjKA,enr:-Ly4QCGeYvTCNOGKi0mKRUd45rLj96b4pH98qG7B9TCUGXGpHZALtaL2-XfjASQyhbCqENccI4PGXVqYTIehNT9KJMQgh2F0dG5ldHOI__________-EZXRoMpAxNnBDAgAAb___________gmlkgnY0gmlwhIuQrVSJc2VjcDI1NmsxoQP9iDchx2PGl3JyJ29B9fhLCvVMN6n23pPAIIeFV-sHOIhzeW5jbmV0cw-DdGNwgiMog3VkcIIjKA --execution-endpoints=http://localhost:8551 --execution-jwt=../jwtsecret/jwt.hex --eth1-endpoints=http://localhost:8545 --debug-level=info --suggested-fee-recipient=0x6926dBc198a99a47375d085dBc980c4312214374 --validator-monitor-auto --subscribe-all-subnets --import-all-attestations --metrics --metrics-port=5054 --metrics-address=

That's pretty much it. Your Gnosis Chiado Testnet node is now up and running. All you need to do now is wait for it to sync. You can check if the node is synced by running the API Call listed below from inside your environment. You are going to need to have the curl and jq packages installed for this, so make sure to install them beforehand.

curl -H "Content-Type: application/json" -d '{"id":1, "jsonrpc":"2.0", "method": "eth_syncing","params": []}' localhost:8545

If the result is false, it means that your node is fully synced.

Another way to check which block the node is at would be running:

curl -H "Content-Type: application/json" -d '{"id":1, "jsonrpc":"2.0", "method": "eth_blockNumber","params": []}' localhost:8545

The result should be a hex number (i.e 0x10c5815). If you convert it to a decimal number, you can compare it to the latest block listed on the Gnosis Chiado Testnet explorer: https://blockscout.chiadochain.net/

The usual RPC port for Gnosis Chain is 8545 and the WS port is the same, 8545.

In order to test the WS endpoint, we will need to install a package called node-ws.

An example WS call would look like this:

wscat --connect ws://localhost:8545
> {"id":1, "jsonrpc":"2.0", "method": "eth_blockNumber","params": []}

Monitoring Guidelines

In order to maintain a healthy node that passes the Integrity Protocol's checks, you should have a monitoring system in place. Blockchain nodes usually offer metrics regarding the node's behaviour and health - a popular way to offer these metrics is Prometheus-like metrics. The most popular monitoring stack, which is also open source, consists of:

  • Prometheus - scrapes and stores metrics as time series data (blockchain nodes cand send the metrics to it);

  • Grafana - allows querying, visualization and alerting based on metrics (can use Prometheus as a data source);

  • Alertmanager - handles alerting (can use Prometheus metrics as data for creating alerts);

  • Node Exporter - exposes hardware and kernel-related metrics (can send the metrics to Prometheus).

We will assume that Prometheus/Grafana/Alertmanager are already installed (we will provide a detailed guide of how to set up monitoring and alerting with the Prometheus + Grafana stack at a later time; for now, if you do not have the stack already installed, please follow this official basic guide here).

We recommend installing the Node Exporter utilitary since it offers valuable information regarding CPU, RAM & storage. This way, you will be able to monitor possible hardware bottlenecks, or to check if your node is underutilized - you could use these valuable insights to take decisions regarding scaling up/down the allocated hardware resources.

Below, you can find a script that installs Node Exporter as a systemd service.


# set the latest version

# download and untar the binary
wget https://github.com/prometheus/node_exporter/releases/download/v${VERSION}/node_exporter-${VERSION}.linux-amd64.tar.gz
tar xvf node_exporter-*.tar.gz
sudo cp ./node_exporter-${VERSION}.linux-amd64/node_exporter /usr/local/bin/

# create system user
sudo useradd --no-create-home --shell /usr/sbin/nologin node_exporter

# change ownership of node exporter binary
sudo chown node_exporter:node_exporter /usr/local/bin/node_exporter

# remove temporary files
rm -rf ./node_exporter*

# create systemd service file
cat > /etc/systemd/system/node_exporter.service <<EOF
Description=Node Exporter

# enable the node exporter service and start it
sudo systemctl daemon-reload
sudo systemctl enable node_exporter.service
sudo systemctl start node_exporter.service

As a reminder, Node Exporter uses port 9100 by default, so be sure to expose this port to the machine which holds the Prometheus server. The same should be done for the metrics port(s) of the blockchain node (in this case, we should expose port 3000).

Having installed Node Exporter and having already exposed the node's metrics, these should be added as targets under the scrape_configs section in your Prometheus configuration file (i.e. /etc/prometheus/prometheus.yml), before reloading the new config (either by restarting or reloading the config - please check the official documentation). This should look similar to this:

  - job_name: 'gnosis-node'
    scrape_interval: 10s
    metrics_path: /monitoring
      - targets:
        - '<NODE0_IP>:3000'
        - '<NODE1_IP>:3000' # you can add any number of nodes as targets
  - job_name: 'gnosis-node-exporter'
    scrape_interval: 10s
    metrics_path: /metrics
      - targets:
        - '<NODE0_IP>:9100'
        - '<NODE1_IP>:9100' # you can add any number of nodes as targets

In the configuration file above, please replace:

  • <NODE0_IP> - node 0's IP

  • <NODE1_IP> - node 1's IP (you can add any number of nodes as targets)

  • ...

  • <NODEN_IP> - node N's IP (you can add any number of nodes as targets)

That being said, the most important metrics that should be checked are:

  • node_cpu_seconds_total - CPU metrics exposed by Node Exporter - for monitoring purposes, you could use the following expression:

    • 100 - (avg by (instance) (rate(node_cpu_seconds_total{job="gnosis-node-exporter",mode="idle"}[5m])) * 100), which means the average percentage of CPU usage over the last 5 minutes;

  • node_memory_MemTotal_bytes/node_memory_MemAvailable_bytes - RAM metrics exposed by Node Exporter - for monitoring purposes, you could use the following expression:

    • (node_memory_MemTotal_bytes{job="gnosis-node-exporter"} - node_memory_MemAvailable_bytes{job="gnosis-node-exporter"}) / 1073741824, which means the amount of RAM (in GB) used, excluding cache/buffers;

  • node_network_receive_bytes_total - network traffic metrics exposed by Node Exporter - for monitoring purposes, you could use the following expression:

    • rate(node_network_receive_bytes_total{job="gnosis-node-exporter"}[1m]), which means the average network traffic received, per second, over the last minute (in bytes);

  • node_filesystem_avail_bytes - FS metrics exposed by Node Exporter - for monitoring purposes, you could use the following expression:

    • node_filesystem_avail_bytes{job="gnosis-node-exporter",device="<DEVICE>"} / 1073741824, which means the filesystem space available to non-root users (in GB) for a certain device <DEVICE> (i.e. /dev/sda or wherever the blockchain data is stored) - this can be used to get an alert whenever the available space left is below a certain threshold (please be careful how you choose this threshold: if you have storage that can easily be increased - for example, EBS storage from AWS, you can set a lower threshold, but if you run your node on a bare metal machine which is not easily upgradable, you should set a higher treshold just to be sure you are able to find a solution before it fills up);

  • up - Prometheus automatically generated metrics - for monitoring purposes, you could use the following expression:

    • up{job="gnosis-node"}, which has 2 possible values: 1, if the node is up, or 0, if the node is down - this can be used to get an alert whenever the node goes down (i.e. it can be triggered at each restart of the node);

  • nethermind_blocks - this is a metric that can be used in order to check if the node is currently syncing with the network - for monitoring purposes, you could use the following expression:

    • increase(nethermind_blocks[1m]), which is going to show the latest block that has been received by the node - this can be used to get an alert whenever the node is not syncing blocks anymore (i.e less than 5 blocks in the past 5 minutes);

  • nethermind_sync_peers - for monitoring purposes, you could use the following expression:

    • nethermind_sync_peers{job="gnosis-node"}, which means the number of peers connected to the node - this can be used to get an alert whenever there are less peers than a certain threshold for a certain period of time (i.e. less than 3 peers for 5 minutes);

You can use the above metrics to create both Grafana dashboards and Alertmanager alerts.

Please make sure to also check the Official Documentation and the Github Repository posted above in order to make sure you are keeping your node up to date.

Last updated