Run A Node
Here, we'll be installing go-quai, the Go implementation of a Quai Network Node. This article is focused for Linux Distributions and MacOS systems. If you're running Windows, this may require additional environment config related to WSL2.
To run an instance of
go-quai
, you'll need to install these programs first:To download the node program files, you'll need to install git. Instructions on how to download git can be found on the Git Guides.
Running an instance of Quai Network also requires your machine has Go version 1.19.0 or higher. Directions on how to install Go can be found in the Golang development guide.
You can verify your install and version by running:
go version
Add Go to the
$PATH
environment variable by running:export PATH=$PATH:/usr/local/go/bin
Now that you've installed the base dependencies, we can go ahead and clone the go-quai repo. We recommend making a directory to house all of your Quai related repositories for easy access.
cd path/to/directory
mkdir quai
Now that we've made our parent directory, we can navigate to it and download the repository.
cd quai
git clone https://github.com/dominant-strategies/go-quai
cd go-quai
This command checks out the main branch to your local.
After you've successfully installed go-quai, you'll need to configure your node. The
network.env.dist
is a boilerplate node configuration file. Copy the boilerplate file into network.env
so that we can create our own custom config.cp network.env.dist network.env
The
network.env
file houses a number of important parameters that we will configure to run our node correctly. The variables listed below will need to be set correctly for every experience level.LOCATION_COINBASE
: the address in each chain (location) that mining rewards are paid to.NETWORK
: the network (testnet, devnet, etc.) your node is running on.THREADS
: the number of CPU threads your node can utilize.
This file also contains a number of more advanced parameters that will not be covered in this article.
Open the config file in your favorite text editor or IDE, such as VSCode. If you are mining, replace the dummy coinbase addresses with your own for the chains that you intend to mine. If you do not do this, your mining rewards will not be sent to the your addresses.
Set the
NETWORK
variable to the network you plan on running. Set the THREADS
to your desired number, but note using more than 80% of the cores on your machine will likely result in performance issues.To start the node, we first need to build the source. Building
go-quai
requires both go and a C-compiler. You can easily install a C-compiler using your favorite package manager.After installing the dependencies, you can build via Makefile by running:
make go-quai
Now that we've built the source, we need to decide which type of node to run. As detailed in the Node Overview page, users can opt for either a full or slice node depending on individual use case and hardware.
Full nodes validate all of the chains within Quai Network. To spin up a full node run:
make run-all
In the codebase, Quai Network's blockchains are identified as regions 0-2 and zones 0-2 within each region.
Slice | Region Identification | Zone Identification |
---|---|---|
Prime - Cyprus - Cyprus1 | 0 | 0 |
Prime - Cyprus - Cyprus2 | 0 | 1 |
Prime - Cyprus - Cyprus3 | 0 | 2 |
Prime - Paxos - Paxos1 | 1 | 0 |
Prime - Paxos - Paxos2 | 1 | 1 |
Prime - Paxos - Paxos3 | 1 | 2 |
Prime - Hydra - Hydra1 | 2 | 0 |
Prime - Hydra - Hydra2 | 2 | 1 |
Prime - Hydra - Hydra3 | 2 | 2 |
Slice nodes validate a subset of three chains within Quai Network. When starting a slice node, you'll have to specify the specific slice you want to run. To spin up a Prime, Cyprus, and Cyprus-1 slice node, you'll need to set the region and zone values in the config file:
REGION=0
ZONE=0
Then run the following command to start the slice node:
make run-slice
Node operators should self-select the slice least latent to them, in order to minimize their uncle rate and maximize network bandwidth. Providing an initial suggestion for geographic organization will expidite the minimization of latency.

Starting a node will run all instances of
go-quai
in the background and create a directory named nodelogs
. Outputs from the node will be piped to a context specific .log file inside of nodelogs
. To view the last 100 lines of log output for a specific location, use:tail -n 100 nodelogs/prime.log
# OR
tail -n 100 nodelogs/region-2.log
# OR
tail -n 100 nodelogs/zone-0-0.log
If you're running a slice node, logs will only populate in the contexts the slice node is validating.
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, we recommend using this method.
The outputs of a node that is running correctly should look like:
INFO [01-30|19:55:15.397] Starting Quai 0.1.0-pre.0 on local testnet
INFO [01-30|19:55:15.414] Maximum peer count ETH=50 total=50
WARN [01-30|19:55:15.460] Disable transaction unindexing for archive node
INFO [01-30|19:55:15.460] Enabling recording of key preimages since archive mode is used
INFO [01-30|19:55:15.460] Set global gas cap cap=50,000,000
INFO [01-30|19:55:15.460] Allocated trie memory caches clean=307.00MiB dirty=0.00B
INFO [01-30|19:55:15.461] Allocated cache and file handles database=/Users/user/Library/Quai/local/zone-0-0/quai/chaindata cache=512.00MiB handles=5120
INFO [01-30|19:55:17.727] Opened ancient database database=/Users/user/Library/Quai/local/zone-0-0/quai/chaindata/ancient readonly=false
INFO [01-30|19:55:17.728] Writing custom genesis block
Depending on what your node is currently doing, your logs may not look exactly the same as above.
Stopping your node should be done any time you make changes to your config file or prior to shutting your machine down. A full node instance can be terminated by running:
make stop
This will kill all instances of
go-quai
on your machine. This can sometimes take a few seconds to complete.Making sure your node is running correctly is crucial to both the functionality of any dependent infrastructure and the network as a whole.
To update a node, first make sure to kill all instances of go-quai using the above stop command.
After stopping the node, you should pull any updated code using:
git pull origin main
and 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.
Initiating the node update process while the node or manager are currently running could cause issues. Make sure to stop all processes before updating.
Last modified 9d ago