Non-validating Nodes

setup guide for non-validating nodes

Non-validating node is a full node of the blockchain with full history. It connects to the blockchain network using p2p networking. The non-validating node can be used by exchange or wallet website to broadcast transactions, to query balances, to fetch transaction data using RPC interfaces.

Harmony blockchain uses a node type called explorer node to satisfy the above requirements. Since Harmony is a sharding blockchain, it is currently required to setup one node per shard.

Software Build

The current release branch is main for mainnet. Please follow the readme file on the harmony repo to build the latest software release from main branch if you plan to build the software from scratch.

Or you may download the prebuilt node binary released by Harmony team.


To setup node on public cloud, please try to follow this document for setup.

By default, the host needs to open up ports 6000, 9000, 9500, and 9800 for all the RPC and syncing functions. The default base port is 9000, all other ports are setup based on the base port.

  • 9000 port is used for blockchain consensus messages. (The base port)

  • 6000 port is used for blockchain state syncing. (base port - 3000)

  • 9500 port is used for SDK RPC service (base port + 500)

  • 9800 port is used for Websocket service (base port + 800)

The 9500, 9800 ports are only listened by localhost by default. If it is required for the host to accept external links, the -P command line option can be specified in to listen to public IP.

There is no need to have a valid BLS key for non-validating node as it won't join the consensus. Just create dummy blskey and pass file should be enough.

Machine Spec.

Non-validating node is a full node of the blockchain except for not joining consensus. It is expected to have the node software running on an AWS m5.large equivalent server (2 core, 8G RAM). The spec of m5.large can be found in this document.

A node needs to sync both beacon chain and the shard chain data. It is expected to have 500Gb disk for 6-9 months data storage per shard.

It is possible to run multiple node software on one host with separated directory. However, it currently requires >250G per shard of storage to run the node software and increasing ~25G per month per shard. Please plan your hard drive accordingly.

Run the Node

The following steps assume the non-validating node connected to mainnet shard 0 which is required for all exchange partners. The syncing of the mainnet blockchain DB will take quite some time. So, it is recommended to follow this guide to use DB snapshot for initial syncing.

download the software release

# assuming setup the non-validator node on shard 0
export SHARD=0
# create shard directory
mkdir -p ~/shard${SHARD}
pushd ~/shard${SHARD}
# download
curl -LO
chmod +x
# download harmony node binary
./ -d
mv -f staging/* .
# update system varibales
sudo ./ -s
# check the version of the node binary
./ -V

start the node software in foreground

you may start the software in the foreground for testing, initial checking if anything goes wrong. But for the production environment, it is recommended to use systemd service to start the harmony program in the background.

# create dummy key/pass files
mkdir .hmy/blskeys
touch .hmy/blskeys/bls.key
touch .hmy/blskeys/bls.pass
# download the db snapshot, this will take ~5-10 minutes
# setup rclone and clone db snapshot by following the doc.
# start node in foreground if you are using tmux/screen session
./ -S -T explorer -i 0
# check if harmony process is running
ps -ef | grep harmony
# check the harmony node running log
tail latest/zerolog-*.log
# go back to previous directory

The expected output is like the following if it is running in the foreground.

output of running non-validating node

Setup non-validating node for other shard, ex shard 1

Use a different base port if it is running on the same server

export SHARD=1
# please follow the commands in the previous section to start
# noted the node will be running on a different base port

Run the node in background using systemd

To have a long running node in the background on the host, it is recommended to use systemd servcie. A sample of the systemd service configuration is like the following. Create the file in /lib/systemd/system/harmony.service

Description=harmony service
ExecStart=/home/ec2-uesr/shard0/ -1PD -T explorer -i 0
sudo systemctl enable harmony.service
sudo systemctl start harmony.service
# check the running status of harmony service
systemctl status harmony
# check the log
journalctl -eu harmony

More info about systemd service can be found here.

Upgrade node software

When harmony had a new release of the binary, you may follow the instructions below to upgrade the binary.

stop harmony binary or service

# if you use systemd service
sudo systemctl stop harmony
# if you use in tmux
sudo killall
sudo killall harmony

redownload and harmony

export SHARD=0
pushd ~/shard${SHARD}
# download
curl -LO
chmod +x
# download harmony node binary
./ -d
mv -f staging/* .
# check version
./ -v
./ -V

restart harmony process

sudo systemctl start harmony
# check status
systemctl status harmony