Run A Node

Introduction

Here, we’ll be installing go-quai, the Go implementation of Quai Network. This tutorial is focused on Linux distributions and MacOS systems.

Running go-quai on Windows or WSL2 is not currently supported.

Requirements

Quai consists of many “slices,” or execution shards, that work together to form an overarching network. A global node runs all of these slices, while a slice node runs only a single slice. Running a slice node is recommended for most users.

The Golden Age Testnet only consists of a single slice. This makes global and single slice nodes effectively equivalent for the duration of the testnet.

To run a global node during the Golden Age Testnet, you’ll need a MacOS or Linux machine with the following specifications:

Fast CPU with 16+ cores

64GB+ RAM

Fast SSD with at least 3TB free space

10+ MBit/sec download Internet service

To run a slice node during the Golden Age Testnet, you’ll need a MacOS or Linux machine with the following specifications:

Fast CPU with 8+ cores

24GB+ RAM

Fast SSD with at least 1TB free space

10+ MBit/sec download Internet service

Install Dependencies

To run an instance of go-quai, you’ll need to install a few dependencies. You can install dependencies with your favorite package manager (apt, brew, etc.). The following dependencies are required to run a node:

Go v1.23.0+

Snap is not default installed on all Linux distros

  # install snapd if you don't have it already
  sudo apt install snapd

  # install go
  sudo snap install go --classic

If you’re not on Ubuntu or MacOS, instructions on how to install go directly can be found on the golang installation page.

Git, Make, and G++

Install git, make, and g++ with the following command:

# install git and make
sudo apt install git make g++

go-quai

Now that the dependencies are installed, we can clone the go-quai repository from the root directory.

git clone https://github.com/dominant-strategies/go-quai
cd go-quai

This command installs the main branch to your local machine. Unless you intend to develop, you must checkout the latest release.

You can find the latest release on the go-quai releases page. Then, check out the latest release with (replace the put-latest-release-here with the latest release number):

git checkout put-latest-release-here

For example (this is not the latest release, check the releases page for the latest release number)

git checkout v1.2.3

Node Configuration

Selecting a Node Type

There are two types of nodes in Quai: Global and Slice nodes.

Environment Variables

There are a few key variables required to run a Quai node. They will be passed as arguments in the start command.

quai-coinbases and qi-coinbases: the addresses in each ledger that block rewards and miner tips are paid to.
miner-preference: the percentage of block rewards that should be paid out on average in Quai or Qi tokens.
slices: the slices of the network that the node will run.

There are a number of more advanced parameters that can be passed as arguments that will not be covered in this article.

Configure Mining Addresses

Coinbases will be passed to the start command similar to below, with your own addresses for the chains that you intend to mine. You can generate addresses for each shard and ledger easily with Pelagus Wallet.

You must generate unique Quai and Qi addresses for each shard your node is running and pass them as coinbase flags to the run command. There is a unique coinbases flag for each ledger:

quai-coinbases: Coinbases for Quai ledger
qi-coinbases: Coinbases for Qi ledger

# single slice node running cyprus1, one quai address + one qi address
--node.quai-coinbases '0x0000000000000000000000000000000000000000'
--node.qi-coinbases '0x0080000000000000000000000000000000000000'

The Qi mining address starts with a “0x00…”, this is not to be confused with the Qi payment address. You can find the Qi mining address in the settings of the Pelagus Wallet.

Block Reward Prefernce

The Quai protocol can payout block rewards and miner tips in either Quai or Qi tokens. While miners have no ability to determine what token their miner tips are paid out in, the do have the ability to set their block reward payout token preference to either Quai or Qi.

Block reward token preference can be set using the miner-preference flag. The miner-preference flag is a percentage scale that can be set to values between 0 and 1, indicating the proportion of block rewards that should be paid out in Quai or Qi tokens.

Some examples:

0: 100% Quai preference, all block rewards are paid out in Quai
0.25: 3/1 Quai preference
0.5: Even split, on average block rewards are paid out equally in Quai and Qi
0.75: 3/1 Qi preference
1: 100% Qi preference, all block rewards are paid out in Qi

Pass the miner-preference flag in the start command with a value between 0 and 1 like below:

# no preference (default)
--node.miner-preference 0.5

# 100% Quai preference
--node.miner-preference 0

# 100% Qi preference
--node.miner-preference 1

Reward Lockup Period

The Quai protocol immediately pays out block rewards as blocks are mined, but are subject to a lockup period.

Quai Block rewards are sent to the coinbase of the miner after the lockup period has elapsed.
Qi Block reward tokens are sent to the coinbase of the miner and register as balance, but are deemed “not spendable” until they are unlocked.

The lockup period is configurable by miners using the --node.coinbase-lockup flag. The protocol provides additional incentives for miners to lock up their block rewards for a longer period of time.

The available values for --node.coinbase-lockup and their corresponding period and reward boost are:

Value	Period (blocks)	Period (days)	Reward Boost
`0`	7200	~0.41	+0%
`1`	30240	1.75	+4.17%
`2`	60480	3.5	+10%
`3`	120960	7	+25%

Pass the --node.coinbase-lockup flag in the start command like below:

# minimum lockup (default)
--node.coinbase-lockup 0

# maximum lockup
--node.coinbase-lockup 3

Slices

Set the node.slices flag in your run command to whichever slices of the network you would like to run.

In the codebase, a slice is identified by its region and zone index. Region and zone indices are 0-indexed and range from 0-2.

The Golden Age Testnet only supports the [0 0] slice.

# single slice node running cyprus1
--node.slices '[0 0]'

Genesis Nonce

To connect to the colosseum network, you must have the correct genesis nonce. The nonce acts as a sort of password that allows your node to correctly compute the first canonical block in the chain.

You’ll pass the genesis nonce to your node on start-up using the --node.genesis-nonce flag.

# Golden Age Testnet geneis nonce
--node.genesis-nonce 6224362036655375007

Starting a Node

Build

To start the node, we first need to build the source. You can build via Makefile by running the following command:

make go-quai

Start

Now that we’ve built the source and set out our variable flags, we can combine them to start the node.

To start your node, run the start command with the added genesis-nonce,quai-coinbases, qi-coinbases, coinbase-lockup, and node.slices flags that we covered above.

The coinbase values below are set to dummy values. If you do not replace them with your own addresses, you will not recieve block rewards.

./build/bin/go-quai start \
--node.slices '[0 0]' \
--node.genesis-nonce 6224362036655375007 \
--node.quai-coinbases '0x0000000000000000000000000000000000000000' \
--node.qi-coinbases '0x0080000000000000000000000000000000000000' \
--node.miner-preference 0.5 \
--node.coinbase-lockup 0

This will spin up a node using the values of the node.slices, node.quai-coinbases, node.qi-coinbases, and node.coinbase-lockup flags in your command. Logs should begin printing to the terminal.

Stop

Stopping your node should be done any time you make changes to your config file or prior to shutting your machine down. A node instance can terminated using CTRL+C.

If you’re running a miner, CTRL+C may not work. You must kill the miner process prior to stopping the node.

Other Node Operations

Starting a node will run all instances of go-quai in the foreground and also create a directory named nodelogs to store more specific logs from the node. Outputs from the node will be piped to a context specific .log file inside of the nodelogs directory. To view the log output for a specific location, use:

# view global logs (recommended)
tail -f nodelogs/global.log

# view specific region or zone logs
tail -f nodelogs/region-0.log
# OR
tail -f nodelogs/zone-0-0.log

Checking the node logs output is the best way to verify that your full node is running correctly. You can also easily view node logs in your favorite IDE or text editor.

The outputs of a node that has started correctly should look similar to below.

INFO   [10-02|19:42:12.077] Loading config from file: /root/.config/go-quai/config.toml
INFO   [10-02|19:42:12.108] Loading config from environment variables with prefix: 'GO_QUAI_'
INFO   [10-02|19:42:12.109] Global logger started                         fields.level=info path=./nodelogs/global.log
INFO   [10-02|19:42:12.137] Starting v0.19.0-pre on the lighthouse network
INFO   [10-02|19:42:12.137] node version                                  commit= date=
INFO   [10-02|19:42:12.867] node created: 12D3KooWKQgbSobfca6KnB55XZtMyntSaCNXTaTdoisPGzrgKFjA
INFO   [10-02|19:42:13.182] Coinbase Addresses: map[cyprus1:0x0000000000000000000000000000000000000000]
INFO   [10-02|19:42:13.469] Finished connecting miner endpoints
INFO   [10-02|19:42:14.576] Finished connecting miner endpoints
INFO   [10-02|19:42:14.577] starting P2P node...
INFO   [10-02|19:42:14.577] Starting metrics
INFO   [10-02|19:42:14.578] Event: 'Local address updated': /ip4/127.0.0.1/tcp/4001/p2p/12D3KooWKQgbSobfca6KnB55XZtMyntSaCNXTaTdoisPGzrgKFjA

To stop log outputs to the terminal, you can use CTRL+C.

Depending on what your node is currently doing, your logs may not look exactly the same as above.

If your node has started correctly, it will begin syncing chain state from peers. There are a few ways to check the progress of the sync.

From the command line, we can run the following command(s) to print the list of blocks that have been appended. Replace location-to-print-here.log with the file name of the logs you’d like to print.

# Print all appended blocks
cat nodelogs/location-to-print-here.log | grep Appended

# Continuously print new appended blocks
tail -f nodelogs/location-to-print-here.log | grep Appended

# Continuously print appended blocks across all chains
tail -f nodelogs/* | grep Appended

The output should look similar to below:

INFO   [09-18|10:18:17.273] Appended new block                       number=[102 1934 40392] hash=0x0000067368b679ce7994dbd6e3dfe93a5e5fe16642a6083604fd405556836cbe difficulty=405369 uncles=0 txs=0 etxs=0 gas=0 gasLimit=5000000 root=0x7df4c77d1463a5e4c7d5f5446476e34df01cf14b6226b7d83ccab072bc302edc order=2 location=[0 0] elapsed=2.019ms
INFO   [09-18|10:18:17.736] Appended new block                       number=[102 1934 40393] hash=0x0000285b7ffa020c8f9f5f8832381593170d1d7618ad2fae8202350a0d81acac difficulty=405875 uncles=0 txs=0 etxs=0 gas=0 gasLimit=5000000 root=0x81954cf5d93a979890641acffe7496965ff4602ad2b24d24ab5356ba52072c39 order=2 location=[0 0] elapsed=1.933ms
INFO   [09-18|10:18:17.803] Appended new block                       number=[102 1934 40394] hash=0x00000d6f0d100a8d254088090876a6ab911720af7e7bc6454f5d1a01417f786f difficulty=406382 uncles=0 txs=0 etxs=0 gas=0 gasLimit=5000000 root=0x8eb0b430e2df8f91a180b6f29fea46430c9014ccde42fa538df62bf3251dff03 order=2 location=[0 0] elapsed=2.005ms
INFO   [09-18|10:18:18.511] Appended new block                       number=[102 1934 40395] hash=0x00001211f391c0a162701ad0dcbdef47f4efe96b3fb5f77e1f0b75b6ff439312 difficulty=406889 uncles=0 txs=0 etxs=0 gas=0 gasLimit=5000000 root=0xc810b3d05f9a9b7f4fee3da271d3544cba26b6368f84ee5e5e885cbe4fd11cab order=2 location=[0 0] elapsed=2.147ms

To check the progress of your node’s sync, compare the number of the latest block output from the above command to the current height of the chain you’re running on the Quai node stats page.

If your node temporarily stops appending during sync, do not stop it. Allow it to continue running, and only reach out for support if the node has not appended a block for over 1 hour.

Initiating the node update process while the node or manager are currently running could cause issues. Make sure to stop all processes before updating.

To update a node, first make sure to stop all instances of go-quai before proceeding.

After stopping the node, you should pull any updated code using:

git fetch --all

Checkout the latest release of go-quai:

git checkout put-latest-release-here

Finally, rebuild the source using:

make go-quai

After pulling any new code and rebuilding the source, you can safely restart the node and continue running.

Resetting your node and clearing your database will remove any state you have synced. This is a non-reversible action and any commands noted below should be utilized with caution.

Developers and node runners may find that situations arise where they need to completely clear your node of synced state or do a full reset in the case of an issue or bug. A full reset of a node involves stopping the node, clearing the current nodelogs, and removing all synced state.

Reminder, resetting your node is non-reversible and should only be done if you understand the implications of removing all synced state.

For Linux Machines, we’ll remove the nodelogs directory and the base ~/.local/share/go-quai directory which contains all synced state. To do this, run the following command:

rm -rf nodelogs ~/.local/share/go-quai

After running the above command, the node has been fully reset and is ready to be restarted.

Common reasons for syncing from a snapshot include:

Reducing syncing times
Restarting a node on a new machine/drive

Please be aware that when you are syncing from a snapshot, you are trusting the contents of the snapshot. For your node to fully verify the network, you must sync from genesis.

To restore your node’s database from a snapshot you’ll first need to stop your node. You can then download the latest official snapshot from the official snapshot link or from the CLI by running:

wget https://storage.googleapis.com/colosseum-db/goldenage_backups/quai-goldenage-backup.tgz

To restore your database from a snapshot, use:

  # Remove current db
  # This command will permanently delete all state that you have synced thus far
  rm -rf ~/.local/share/go-quai

  # Expand compressed db
  tar -xvf quai-goldenage-backup.tgz

  # Copy db into db directory
  cp -r quai-goldenage-backup ~/.local/share/go-quai

Client

Miner

Development

Introduction

Requirements

Fast CPU with 16+ cores

64GB+ RAM

Fast SSD with at least 3TB free space

10+ MBit/sec download Internet service

Fast CPU with 8+ cores

24GB+ RAM

Fast SSD with at least 1TB free space

10+ MBit/sec download Internet service

Install Dependencies

Node Configuration

Selecting a Node Type

Environment Variables

Starting a Node

Build

Start

Stop

Other Node Operations

Client

Miner

Development

​Introduction

​Requirements

Fast CPU with 16+ cores

64GB+ RAM

Fast SSD with at least 3TB free space

10+ MBit/sec download Internet service

Fast CPU with 8+ cores

24GB+ RAM

Fast SSD with at least 1TB free space

10+ MBit/sec download Internet service

​Install Dependencies

​Node Configuration

​Selecting a Node Type

​Environment Variables

​Starting a Node

​Build

​Start

​Stop

​Other Node Operations

Introduction

Requirements

Install Dependencies

Node Configuration

Selecting a Node Type

Environment Variables

Starting a Node

Build

Start

Stop

Other Node Operations