Skip to main content
Version: v1

Set Up a Node

This guide provides step-by-step instructions for setting up a ZIGChain testnet node, including configuration, system management, examples, and the reasoning behind each action.

Prerequisites​

Recommended Hardware Requirements

  • Core Processor: 8-core (4 physical core), x86_64 architecture
  • Memory: 32 GB RAM
  • Storage: 1 TB SSD
  • Network: Stable internet connection

Open Network Ports

Ensure the following ports are open:

  • 26656
  • 26657

Install zigchaind

Ensure that zigchain CLI or zigchaind is installed on your system. If not, follow this installation guide.

Initialize the Node​

To set up the local configuration files needed for the node to run, initialize the ZIGChain node.

This process creates essential files and directories inside $HOME/.zigchain.

To create the necessary configuration files, run:

zigchaind init <node_name> --chain-id <chain_id>
zigchaind init mynode --chain-id zigchain-1

If you get the error: genesis.json file already exists. You can remove the zigchain data rm -rf $HOME/.zigchain and run it again.

After initialization, the following directory structure is created:

~/.zigchain
├── config
│   ├── app.toml
│   ├── client.toml
│   ├── config.toml
│   ├── genesis.json
│   ├── node_key.json
│   └── priv_validator_key.json
└── data
    └── priv_validator_state.json

Download the Genesis File​

ZIGChain maintains a public repository containing the genesis file, seed nodes, and RPC nodes.

Download the latest genesis file for your network:

wget https://raw.githubusercontent.com/ZIGChain/networks/refs/heads/main/zigchain-1/genesis.json -O ~/.zigchain/config/genesis.json

Configure the Node​

Modify config.toml for network connectivity.

vim ~/.zigchain/config/config.toml

Key configuration parameters:

SettingValue
monikerYour node's name, (e.g., mynode)
log_levelinfo
seedsSee next section

You can adjust multiple settings as needed. For more details, refer to the CometBFT Configuration.

Set Up State Sync​

To sync up your node with the network, enable the State Sync service in the config.toml.

SNAP_RPC="https://public-zigchain-rpc.numia.xyz:443"
SEED_NODES="https://raw.githubusercontent.com/ZIGChain/networks/main/zigchain-1/seed-nodes.txt"
LATEST_HEIGHT=$(curl -s $SNAP_RPC/block | jq -r .result.block.header.height)
BLOCK_HEIGHT=$((LATEST_HEIGHT - 5000))
TRUST_HASH=$(curl -s "$SNAP_RPC/block?height=$BLOCK_HEIGHT" | jq -r .result.block_id.hash)

sed -i.bak -E \
    "s|^(enable[[:space:]]*=[[:space:]]*).*$|\1true| ; \
     s|^(rpc_servers[[:space:]]*=[[:space:]]*).*$|\1\"$SNAP_RPC,$SNAP_RPC\"| ; \
     s|^(trust_height[[:space:]]*=[[:space:]]*).*$|\1$BLOCK_HEIGHT| ; \
     s|^(trust_hash[[:space:]]*=[[:space:]]*).*$|\1\"$TRUST_HASH\"|" \
    "$HOME/.zigchain/config/config.toml"

Set Up Peers​

To connect your node to others in the network, update persistent peers in the config.toml.

persistent_peers = "<peer_id>@<peer_address>:26656"

Example:

persistent_peers = "dc9725eac15e7887a4b8deb4eddfbf4cf641778f@testnet-seed0.zigchain.com:26656"

Get the full list of peers from ZIGChain Networks and add them to the configuration file directly:

SEED_FILE=REPLACE-ME-WITH-SEED-FILE-PATH

wget $SEED_NODES -O $SEED_FILE

SEEDS=$(paste -sd, "$SEED_FILE")

sed -i -E "s|^(persistent_peers[[:space:]]*=[[:space:]]*).*|\1\"$SEEDS\"|" "$HOME/.zigchain/config/config.toml"

Set Up Minimum Gas Price​

Modify app.toml to set minimum gas price to 0.0025uzig.

vim ~/.zigchain/config/app.toml

Find the line containing minimum-gas-prices and update it:

minimum-gas-prices = "0.0025uzig"

Start the Node​

Starting the ZIGChain node initiates synchronization with the testnet, allowing it to connect to the network and participate in consensus.

To start the node, run the following command:

zigchaind start

Example Output:

5:11PM INF service start impl=Node module=server msg="Starting Node service"
5:11PM INF serve module=rpc-server msg="Starting RPC HTTP server on 127.0.0.1:26657"

Verify Node Status​

Check if the node is running and syncing correctly:

curl -s localhost:26657/status | grep -o '"sync_info":{[^}]*}' | sed 's/"sync_info"://' | json_pp

Example Output:

{
  "catching_up": false,
  "earliest_app_hash": "E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855",
  "earliest_block_hash": "BBAEC1030E0F1E5CC84E7AD90DBBF833092C21E5A7877ED5D0AC53333544AE86",
  "earliest_block_height": "1",
  "earliest_block_time": "2025-01-29T10:00:24.662688409Z",
  "latest_app_hash": "4C5CABFC67074A26CFEDAEFAE8C2CAEAF1FBD360868A00F2F5A844333ADA646C",
  "latest_block_hash": "4DE43846C6CD75C962B7A962DEC81D475F68F524DCA80E076497E1DBC1D51F69",
  "latest_block_height": "115789",
  "latest_block_time": "2025-02-09T16:26:42.581094257Z"
}

Key fields:

  • latest_block_height: Shows the current block height.
  • catching_up: Should be false when the node is fully synchronized.

Setting Up System Service and Logs​

Replace ZUSER with the username of the account running the blockchain node.

Create Log files for zigchaind​

Create log files and service file for the blockchain node.

ZUSER="zigchain"
sudo mkdir -p /var/log/zigchaind
sudo touch /var/log/zigchaind/main.log
sudo touch /var/log/zigchaind/error.log
sudo chown -R $ZUSER:$ZUSER /var/log/zigchaind
sudo touch /etc/systemd/system/zigchaind.service

Create a systemd file​

Create a configuration file for the blockchain node.

ZUSER="zigchain"
sudo bash -c "cat > /etc/systemd/system/zigchaind.service" << EOM
[Unit]
Description=zigchaind daemon
After=network-online.target

[Service]
User=$ZUSER
ExecStart=/home/$ZUSER/go/bin/zigchaind start --home=/home/$ZUSER/.zigchain
WorkingDirectory=/home/$ZUSER/go/bin
StandardOutput=file:/var/log/zigchaind/main.log
StandardError=file:/var/log/zigchaind/error.log
Restart=always
RestartSec=3
LimitNOFILE=4096

[Install]
WantedBy=multi-user.target
EOM

Starting a daemon​

Start the blockchain node as a daemon:

sudo systemctl enable zigchaind.service
sudo systemctl start zigchaind.service

Other useful commands​

sudo systemctl status zigchaind.service
sudo systemctl stop zigchaind.service
sudo systemctl restart zigchaind.service
sudo systemctl disable zigchaind.service

View the service logs:

tail -f /var/log/zigchaind/main.log

Activate log rotate for the logs​

Install logrotate:

sudo apt install logrotate -y

Set up the logrotate configuration:

LOGROTATE_CONF="/etc/logrotate.d/zigchaind"
ZUSER="zigchain"

sudo bash -c "cat > $LOGROTATE_CONF" <<EOL
/var/log/zigchaind/*.log {
  daily
  rotate 7
  compress
  missingok
  notifempty
  create 0640 $ZUSER $ZUSER
  sharedscripts
  postrotate
  systemctl restart zigchaind.service > /dev/null 2>&1 || true
  endscript
}
EOL

Test the logrotate configuration:

sudo logrotate -d $LOGROTATE_CONF

Force log rotation to ensure it works:

sudo logrotate -f $LOGROTATE_CONF
echo "Logrotate configuration for /var/log/zigchaind/ has been created and activated."

In production environments, it is recommended to implement a monitoring system to track logs and monitor the health of the blockchain node.

Last updated on