Run A Node
How to start and run a Quai Network 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.
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.
To run a global node during the Iron Age Testnet, you’ll need a MacOS or Ubuntu 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 Iron Age Testnet, you’ll need a MacOS or Ubuntu 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.22.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.
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:
git checkout put-latest-release-here
For example (this not the latest release, check the releases page for the latest release number)
git checkout v1.2.3-rc.4
Node Configuration
Selecting a Node Type
There are two types of nodes in Quai: Global and Slice nodes.
Global nodes validate every shard in the network, i.e. Prime, all Region chains, and all Zone chains. Running a global node is only recommended for users who:
- have more available computing power (strong CPU, more RAM, large SSD, etc.)
- want to easily switch between shards for mining
- want to provide chain data as an RPC service
Slice nodes validate a “slice” of all shards in the network. A slice is defined as the smallest set of shards a node can validate trustlessly, i.e. the Prime chain, any one Region chain, and any one Zone chain under the selected Region chain. A slice node validates only the shards in that slice, and runs lighter non-validation processes for all other shards in the network. Running a slice node is recommended for users who:
- have less available computing power (less RAM, small SSD, etc.)
- are not switching their miners between shards
- are not providing chain data as an RPC service
Environment Variables
After you’ve successfully installed go-quai, you’ll need to configure your node. Go-quai uses a config.toml
file to configure the node. If this is your first time running go-quai, you’ll need to run the following commands to build the node and populate the config file:
# build go-quai
make go-quai
# populate config file
./build/bin/go-quai config
You only need to run this command once the first time you run go-quai. Once the config file has been created, you can skip this step. Running the command again will not overwrite the config file.
After running the above command, a config file will be created in the following directories (depending on your operating system):
bash > ~/.config/go-quai/config.toml
The config.toml
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.
environment
: the network (testnet, devnet, etc.) your node is running on.coinbases
: the addresses in each chain (location) that mining rewards are paid to. Note that you must have one address per slice you are running.slices
: the slices of the network that the node will run.
Open the Config File
Open the config.toml
file with your favorite text editor.
# edit with nano
nano ~/.config/go-quai/config.toml
# open in vscode to edit
cd ~/.config/go-quai/
code .
# edit network.env with vim
vim ~/.config/go-quai/config.toml
Set Environment
Set the environment
variable to the network you plan on running. Available network options can be found in the network specifications page.
environment = 'colosseum'
Set Mining Addresses
If you are mining, insert the coinbase addresses similar to below with your own for the chains that you intend to mine. You can generate addresses for each shard easily with Pelagus Wallet or Koala Wallet.
You must generate a unique address for each coinbase
entry that maps to a slice your node is running, i.e. generate a Cyprus-1 address and paste it in the coinbases
field if you’re running the slice [0 0]
. You must enter a unique address for each additional entry.
[global node]
coinbases = '0x00a3e45aa16163F2663015b6695894D918866d19,0x01a3e45aa16163F2663015b6695894D918866d19,0x02a3e45aa16163F2663015b6695894D918866d19,0x10a3e45aa16163F2663015b6695894D918866d19,0x11a3e45aa16163F2663015b6695894D918866d19,0x12a3e45aa16163F2663015b6695894D918866d19,0x20a3e45aa16163F2663015b6695894D918866d19,0x21a3e45aa16163F2663015b6695894D918866d19,0x22a3e45aa16163F2663015b6695894D918866d19'
[single slice node]
coinbases = '0x00a3e45aa16163F2663015b6695894D918866d19'
[multi slice node (3 slices)]
coinbases = '0x00a3e45aa16163F2663015b6695894D918866d19,0x01a3e45aa16163F2663015b6695894D918866d19,0x02a3e45aa16163F2663015b6695894D918866d19'
Set Slices
Set the slices
parameter to whichever slices of the network you would like to run. The number of slices you specify should match the number and order of addresses you specified in the coinbases
field.
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.
[global node]
slices = '[0 0],[0 1],[0 2],[1 0],[1 1],[1 2],[2 0],[2 1],[2 2]'
[single slice node]
slices = '[0 0]'
[multi slice node (3 slices)]
slices = '[0 0],[0 1],[0 2]'
Running a slice node will start node processes for all chains, but only validate state in the chains you specify.
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
We already already ran the above build command in the Environment Variables section. It is not required to run the build command again, but it can be a good practice, especially after pulling a new version or making your own changes.
Start
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 global node or slice node depending on individual use case and hardware.
To start your node, simply run:
./build/bin/go-quai start
This will spin up a node using the configuration we set in the config.toml
file. 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
.
CTRL+C
may not work. You must kill the miner process prior to stopping the node.Latency Optimization
Node operators should self-select the slice least latent to them (geographically closest to them). This will help maximize their mining rewards, minimize uncle rate, and reduce communication time between nodes.
Below is an initial suggestion for geographic organization, which will generally expedite the minimization of latency.
Other Node Operations
Was this page helpful?