How to setup a Q Root Node

Basic Configuration

Clone the repository

Linux, macOS, other Unix-like systems:

git clone

Windows (if you don't have git installed):

# Download the contents of the Git repository
Invoke-WebRequest -Uri -OutFile

# Extract the contents of the ZIP file
Expand-Archive -Path -DestinationPath .

# Remove the ZIP file
Remove-Item -Path

and go to the /testnet-rootnode directory

Linux, macOS, other Unix-like systems:

cd testnet-public-tools/testnet-rootnode


Set-Location -Path "testnet-public-tools\testnet-rootnode"

This directory contains the docker-compose.yaml file for quick launching of the root node with preconfigurations using .env file (which can be created from .env.example file).

Note: ** If git is not installed on your machine, you can manually copy all files from public repo testnet-public-tools onto your machine. Using git is much more comfortable, since it allows pulling file updates with one single command.

Set Password for Keystore File

To act as a root node, your node needs a keypair to sign transactions and L0 governance messages. First, create a /keystore directory with

Linux, macOS, other Unix-like systems:

mkdir keystore


New-Item -ItemType Directory -Name "keystore"

then create a file pwd.txt

Linux, macOS, other Unix-like systems:

nano keystore/pwd.txt


notepad.exe .\keystore\pwd.txt

then set a password that will be used for future account unlocking by entering it into pwd.txt. The password needs to be entered at the beginning of the file. Save your changes with CTRL+O, then close nano with CTRL+X (if you use a different editor, commands might be different).

Generate a Keypair

Copy .env.example to .env and in /testnet-rootnode directory:

Linux, macOS, other Unix-like systems:

cp .env.example .env


# This will copy the .env.example file to a new file named .env.
Copy-Item -Path ".\env.example" -Destination ".\env"

Assuming you are in /testnet-rootnode directory, issue this command in order to generate a keypair:

docker-compose run --rm --entrypoint "geth account new --datadir=/data --password=/data/keystore/pwd.txt" testnet-rootnode

The output of this command should look like this:

Your new key was generated

Public address of the key:   0xb3FF24F818b0ff6Cc50de951bcB8f86b52287dac
Path of the secret key file: /data/keystore/UTC--2021-01-18T11-36-28.705754426Z--b3ff24f818b0ff6cc50de951bcb8f86b52287dac

- You can share your public address with anyone. Others need it to interact with you.
- You must NEVER share the secret key with anyone! The key controls access to your funds!
- You must BACKUP your key file! Without the key, it's impossible to access account funds!
- You must REMEMBER your password! Without the password, it's impossible to decrypt the key!

This way, a new private key is generated and stored in docker container in data/keystore directory encrypted with password from pwd.txt file. In our example, 0xb3FF24F818b0ff6Cc50de951bcB8f86b52287DAc (you will have a different value) is the address corresponding to the newly generated private key.

Alternatively, you can generate a secret key pair and corresponding file here and save it to the /keystore directory manually. Also you may use create-geth-private-key.js script in /js-tools folder.

Whether you chose to provide your own vanity keys or use the above command to create a keypair, please ensure that the directory /keystore contains the following files:

|   ...
|   ...
β”” keystore
  |   UTC--2021-01-18T11-36-28.705754426Z--b3ff24f818b0ff6cc50de951bcb8f86b52287dac
  |   pwd.txt

Note: ** Following our example, pwd.txt contains the password to encrypted file "UTC--2021-01-18T11-36-28.705754426Z--b3ff24f818b0ff6cc50de951bcb8f86b52287dac" in clear text.

If you want to change the password in the future, you need to stop the node first.

docker-compose down

Then start password reset procedure with

docker-compose run testnet-rootnode --datadir /data account update 0xb3ff24f818b0ff6cc50de951bcb8f86b52287dac

Note: ** You need to remove address 0xb3ff24f818b0ff6cc50de951bcb8f86b52287dac and add your account address instead.

Configure Node

Edit environment file in /testnet-rootnode directory:

Linux, macOS, other Unix-like systems:

nano .env


#This will open the .env file in Notepad for editing. If you prefer to use a different text editor, replace notepad.exe with the appropriate command for your editor.
notepad.exe .\env

Enter your (newly created) root node address without leading 0x here:

# your q address here (without leading 0x)

Then add your machines public IP address (please make sure your machine is reachable at the corresponding IP since it's required for discoverability by other network participants) here:

# your public IP address here

Optionally choose a port for p2p protocol or just leave default value (use different ports for every node you are running):

# the port you want to use for p2p communication (default is 30313)

The resulting .env file should look somehow like this:

# docker image for q client

# your q address here (without leading 0x)

# your public IP address here

# the port you want to use for p2p communication (default is 30313)

# extra bootnode you want to use

Add your Root Node to

If you want your root node to report to the network statistics, you can add an additional flag to the node entrypoint within file /testnet-rootnode/docker-compose.yaml, it should look like this:

  entrypoint: ["geth", "--ethstats=<Your_RootNode_Name>:<Testnet_access_key>", "--datadir=/data", ...]

<Your_RootNode_Name> can be chosen arbitrarily. It will be displayed in the statistics and could be something like "OurCoolCompany - 0xABC123". You can use special characters, emojis as well as spaces. We would appreciate to include the beginning of your Root Node Q address, so there is a link between your client and your address.

In order to find out the <Testnet_access_key> please join Q Discord Server and find stats key in πŸ”‘β”‚testnet-key channel.

Launch Root Node

Now launch your root node using docker-compose file in rootnode directory:

docker-compose up -d

Check your nodes real-time logs with the following command:

docker-compose logs -f --tail "100"

Find additional peers

In case your client can't connect with the default configuration, we recommend that you add an additional flag referring to one of our additional peers ($BOOTNODE1_ADDR, $BOOTNODE2_ADDRor $BOOTNODE3_ADDR) within docker-compose.yaml file:

  entrypoint: ["geth", "--bootnodes=$BOOTNODE1_ADDR,$BOOTNODE2_ADDR,$BOOTNODE3_ADDR", "--datadir=/data", ...]

Get Q Tokens

In order to become a root node, you will need to make an onchain proposal to add yourself to the root node panel. You need Q tokens for this. For Q testnet, you can get some Q using the faucet. Check the faucet documentation for more information. Finally, please verify that tokens were sent by looking up your address within Block Explorer.

Put Stake in Rootnodes Contract

As was mentioned previously, you should put stake to rootnodes contract in order to become a rootnode.

You can use the dApp "Your HQ" that can be found at Go to Staking -> Root Node Staking for stake management. Also, you may want to check our Staking documentation.

Updating Q-Client & Docker Images

To upgrade the node follow the instructions Upgrade Node