Running go-quai on Windows or WSL2 is not currently supported.
Requirements
To run a Quai Network node, the following specifications are suggested:Fast CPU with 8+ cores
16GB+ RAM
Fast SSD with at least 1TB free space
10+ MBit/sec download Internet service
Install Dependencies
1
Go v1.23.0+
Snap is not default installed on all Linux distros
2
Git, Make, and G++
Install git, make, and g++ with the following command:
Node Configuration
Start
Mainnet (Colosseum)
Mainnet (Colosseum)
Mainnet Testnet (Orchard)
Mainnet Testnet (Orchard)
The Orchard testnet requires using the
orchard
branch of go-quai. Using any other branch or tag will result in sync issues or genesis incompatibility.Local Developer Network
Local Developer Network
The coinbase values above are set to dummy values. If you do not replace them
with your own addresses, you will not receive block rewards.
node.slices
, node.quai-coinbases
, node.qi-coinbases
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 usingCTRL+C
.
If you’re running a miner,
CTRL+C
may not work. You must kill the miner
process prior to stopping the node.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
andqi-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.
1
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 ledgerqi-coinbases
: Coinbases for Qi ledger
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.
2
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 Quai0.25
: 3/1 Quai preference0.5
: Even split, on average block rewards are paid out equally in Quai and Qi0.75
: 3/1 Qi preference1
: 100% Qi preference, all block rewards are paid out in Qi
miner-preference
flag in the start
command with a value between 0 and 1 like below:3
Reward Lockup Period
The Quai protocol immediately pays out block rewards as blocks are mined, but are subject to a lockup period.
*Base maturity periodPass the
- 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.
--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* | 241,920 | 2 weeks | +0% |
1 | 1,555,200 | 3 months | +3.5% |
2 | 3,110,400 | 6 months | +10% |
3 | 6,220,800 | 12 months | +25% |
--node.coinbase-lockup
flag in the start
command like below:4
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 Colosseum Mainnet and Orchard Testnet only support the
[0 0]
slice.5
Network Environment & Genesis Nonce
To connect to Quai, you must have the correct genesis nonce for the intended network. The nonce acts as a 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 Options for
--node.genesis-nonce
flag.--node.environment
are: "colosseum"
(mainnet), "orchard"
(mainnet testnet), "garden"
(mainnet devnet), and "local"
.Environment | Description | Genesis Nonce |
---|---|---|
colosseum | Mainnet | 23621466532946281564673705261963422 |
orchard | Mainnet testnet | 62242624366553750196964614682162313 |
local | Local development | N/A |
Check Log Output
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:
Depending on what your node is currently doing, your logs may not look exactly the same as above.
Checking Sync Progress
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. Replacelocation-to-print-here.log
with the file name of the logs you’d like to print.
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.
Update Your Node
Initiating the node update process while the node or manager are currently running could cause issues. Make sure to stop all processes before updating.
Reset and Clear
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.
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:Create Backup/Snapshot
You can create your own backup or snapshot to:- Store for later.
- Move to another machine.
-
Shut down the node cleanly. You can use
ctrl+c
. -
Remove the peer db. It is stored in the genesis hash folder.
-
Compress the database for smaller storage and faster transfers.
Download and Sync from Snapshot
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 database from a snapshot, use: