This guide is help you set up a Gnosischain Validator, this will cover the full set up on a local device installed with Ubuntu 20.04 LTS. We will be using Teku for consensus layer client and Nethermind for our Execution layer client.

Gnosischain merge is on the horizon, this guide is intended to be merge ready, the set up will cover steps and configuration needed to run post merge and today.

Gnosischain is using Ethereum’s Proof of Stake consensus with the Beacon chain to select validators, a GNO validator requires only 1 GNO to run and the hardware requirements are similar to Ethereum. This makes Gnosischain highly decentralised as it can be run locally without needing a data centre.

Hardware Requirements: Wired connection to a local device with at least 8GB memory (I am using 16GB with no issues), I would recommend starting with 1TB and to use higher grade SSDs or NVMe, as a node operator you're providing a service, so best to start with good hardware that will last and perform up to standard.

Assuming you have a fresh install of Ubuntu 20.04 LTS. Some experience with Linux will help, I’ve written this as best I can for those with minimal experience with the OS. Minimum install for security I would keep this as a dedicated device, some prefer a server but I find it easier to manage folders and files and mount USB’s with the UI.

Update Ubuntu

sudo apt update && sudo apt upgrade -y

Install curl and git

sudo apt install curl git -y

Install Docker

Install Docker instructions from here.

curl -fsSL https://get.docker.com -o get-docker.sh
sh get-docker.sh
sudo rm -r get-docker.sh
sudo usermod -aG docker $USER

Check installed with (if correct will output version)

docker --version

Install Docker Compose

Install Docker Compose instructions from here.

sudo curl -L "https://github.com/docker/compose/releases/download/v2.2.3/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose 
sudo chmod +x /usr/local/bin/docker-compose 
sudo ln -s /usr/local/bin/docker-compose /usr/bin/docker-compose

Check installed with (if correct will output version)

docker-compose --version

Default Ports for the clients used for EL & CL

sudo ufw allow 30303
sudo ufw deny 8545
sudo ufw deny 8551
sudo ufw allow 9000
sudo ufw enable

Check your firewall rules with

sudo ufw status

Port Forwarding (if running Locally)

Login to your router and update the firewall rules, will be slightly different depending on your provider you should check your manual.

Create a working directory for Gnosischain

cd
mkdir /home/$USER/gnosis
mkdir /home/$USER/gnosis/execution-data
mkdir /home/$USER/gnosis/consensus-data

Create JWT secret

We need to enable two-way communication between the execution layer and consensus layer, this is done via JWT secret (json web token), which is a secret key that is shared only between the two clients to authenticate one another.

mkdir /home/$USER/gnosis/jwtsecret
openssl rand -hex 32 | tr -d "\n" > "/home/$USER/gnosis/jwtsecret/jwtsecret.hex"

Create docker-compose.yml for node configuration

cd gnosis
nano docker-compose.yml

This is our docker-compose.yml for configuration of our execution and consensus layer clients, right now we will just fill in for Nethermind Execution layer.

Docker Image: nethermind/nethermind

Find releases Here:

version: "3.9"
services:
  execution:
    stop_grace_period: 30s
    container_name: execution-client
    restart: always
    image: nethermind/nethermind:1.14.6
    networks:
    - gnosischain
    volumes:
    - /home/$USER/gnosis/execution-data:/data
    - /home/$USER/gnosis/jwtsecret:/jwtsecret
    - /etc/timezone:/etc/timezone:ro
    - /etc/localtime:/etc/localtime:ro
    ports:
    - 30303:30303/tcp
    - 30303:30303/udp
    expose:
    - 8545
    - 8551
    command:
    - --config=xdai
    - --datadir=/data
    - --log=INFO
    - --Sync.SnapSync=false
    - --JsonRpc.Enabled=true
    - --JsonRpc.Host=0.0.0.0
    - --JsonRpc.Port=8545
    - --JsonRpc.EnabledModules=[Web3,Eth,Subscribe,Net,]
    - --JsonRpc.JwtSecretFile=/jwtsecret/jwtsecret.hex
    - --JsonRpc.EngineHost=0.0.0.0
    - --JsonRpc.EnginePort=8551
    - --Network.DiscoveryPort=30303
    - --HealthChecks.Enabled=false
    - --Pruning.CacheMb=2048
    logging:
      driver: json-file
      options:
        max-size: 10m
        max-file: "10"
networks:
  gnosischain:
    name: gnosischain_network

IMPORTANT: spacing is really important here, I’ve got this to be easily copy and pasted into a .txt file with the right syntax. If you have errors it may be due to this, and characters not being copied over correctly.

Write out and save, usually ctrl + o then ctrl + x

To Run the Node

go in to the correct directory and run with the following command

cd gnosis
sudo docker-compose up -d execution

Check the Logs

List running containers with the following command you should see your container for our execution client (with Nethermind) is live.

sudo docker ps -a 

sudo docker-compose logs -f <service name>

This starts the logs, service Name in this case should be ‘execution’ as specified in the docker-compose.yml file. The Container name is execution-client if we view logs with docker then sudo docker logs -f execution-client

Your Execution Node can take 1–3 Days to Sync depending on your Hardware, it took me just under 24Hrs, make sure this is running in the background to sync up. You can proceed to the next steps regardless.

Download the Key Generator

cd
sudo docker pull ghcr.io/gnosischain/validator-data-generator:latest

Create Folder for Key Storage

In our working directory

mkdir -p /home/$USER/gnosis/validator-data/keys
mkdir -p /home/$USER/gnosis/validator-data/secrets

Run the Generator to Create Keystore/s:

Note: good idea to disconnect from the Internet for extra security during this step

This will create a new mnemonic seed phrase where your keystores are derived from, place the amount of Validators you wish to create for <# of val>, your ETH address in place of <ETH-withdrawal-address>

sudo docker run -it --rm -v /home/$USER/gnosis/validator-data/keys:/keystore \
ghcr.io/gnosischain/validator-data-generator:latest new-mnemonic \
--num_validators=<# of Val> --mnemonic_language=english --chain=gnosis \
--folder=/keystore --eth1_withdrawal_address=<ETH-withdrawal-address>

You will be asked to enter a password of your choosing, this is our keystore decrypt key. Write this down as we need this later to create our password files.

You will then have the seed phrase generated, you must WRITE THIS DOWN AND STORE SECURELY

Once confirmed it will generate your keystore/s (validators keys) and place them in the directory /gnosis/validator-data/keys. along with deposit_data.json

Create File for your Decrypt Key

nano /home/$USER/gnosis/validator-data/secrets/<Keystore-Name>.txt

This is our decrypt key that we created earlier, enter it on the terminal and save, return to the terminal. NOTE: the password file must have the same name as the keystore file and we need a password file per keystore.

Example, if our keystore is named keystore-m_12381_3600_0_0_0-1668110061.json in the folder ./gnosis/validator-data/keys/.then we must have a file called keystore-m_12381_3600_0_0_0-1668110061.txt containing the decrypt key, in folder .gnosis/validator-data/secrets

The consensus client is our Beacon Node and Validator Node. Teku will run this as one container.

Create docker-compose.yml for consensus client

with the following service consensus: this includes the beacon node and validator node as one service/ one docker container

this will be added to our docker-compose.yml in /gnosis

cd gnosis
sudo nano docker-compose.yml

paste the following into your terminal, after the execution services section, and before networks:

  consensus:
    container_name: consensus-client
    image: consensys/teku:latest
    restart: always
    command:
    - --network=gnosis
    - --initial-state=https://checkpoint.gnosischain.com
    - --data-beacon-path=/var/lib/teku/beacon
    - --data-path=/data										
    - --ee-endpoint=http://execution:8551
    - --ee-jwt-secret-file=/jwtsecret/jwtsecret.hex
    - --eth1-deposit-contract-max-request-size=8000
    - --log-destination=CONSOLE
    - --validator-keys=/data/keys:/data/secrets						
    - --validators-proposer-default-fee-recipient=<YOUR-ETH-ADDRESS>
    - --validators-keystore-locking-enabled=false
    - --validators-graffiti=<CUSTOM GRAFFITI>
    networks:
    - gnosischain
    ports:
    - 9000:9000 # p2p
    volumes:
    - ./validator-data:/data
    - ./consensus-data:/var/lib/teku
    - ./jwtsecret:/jwtsecret
    - /etc/timezone:/etc/timezone:ro
    - /etc/localtime:/etc/localtime:ro
    logging:
      driver: json-file
      options:
        max-size: 10m
        max-file: "10"

More Information on Teku Options can be found here, but this configuration works out the box.

https://docs.teku.consensys.net/en/latest/Reference/CLI/CLI-Syntax/

Run the Consensus Client Node

Go to working directory and run the Lighthouse Beacon Chain Node

cd gnosis 
sudo docker-compose up -d consensus

Check the Logs that everything is running okay.

sudo docker-compose logs -f consensus

If started successfully, it will start syncing. You should see in the logs on first start, It should detect jwtsecret file and our execution endpoint. Then loading <#number> validator keys which tells you the consensus client has successfully located your keystores.

At this point we are waiting for our Execution client and Consensus clients to finish syncing. This can take a while (12-24hrs or days depending on hardware). We need to wait until both EL and CL have finished syncing before proceeding to the next step.

Ensure your Consensus client (beacon node) is synced and running without errors and connected to the execution node.

Your Validator node should say beacon node synced, awaiting deposits. When ready you can make the Deposit using your deposit_data.json file in ./validator-data

Can now be done Via UI which is much easier: https://deposit.gnosischain.com/ there’s no need to convert to mGNO, as its done in the process. If you have GNO on Ethereum you will need to bridge to Gnosischain, you can Use the OmniBridge to move GNO from Ethereum.

This guide is help you set up a Gnosischain Validator, this will cover the full set up on a local device installed with Ubuntu 20.04 LTS. We will be using Teku for consensus layer client and Nethermind for our Execution layer client.

Gnosischain merge is on the horizon, this guide is intended to be merge ready, the set up will cover steps and configuration needed to run post merge and today.

Gnosischain is using Ethereum’s Proof of Stake consensus with the Beacon chain to select validators, a GNO validator requires only 1 GNO to run and the hardware requirements are similar to Ethereum. This makes Gnosischain highly decentralised as it can be run locally without needing a data centre.

Hardware Requirements: Wired connection to a local device with at least 8GB memory (I am using 16GB with no issues), I would recommend starting with 1TB and to use higher grade SSDs or NVMe, as a node operator you're providing a service, so best to start with good hardware that will last and perform up to standard.

Assuming you have a fresh install of Ubuntu 20.04 LTS. Some experience with Linux will help, I’ve written this as best I can for those with minimal experience with the OS. Minimum install for security I would keep this as a dedicated device, some prefer a server but I find it easier to manage folders and files and mount USB’s with the UI.

Update Ubuntu

sudo apt update && sudo apt upgrade -y

Install curl and git

sudo apt install curl git -y

Install Docker

Install Docker instructions from here.

curl -fsSL https://get.docker.com -o get-docker.sh
sh get-docker.sh
sudo rm -r get-docker.sh
sudo usermod -aG docker $USER

Check installed with (if correct will output version)

docker --version

Install Docker Compose

Install Docker Compose instructions from here.

sudo curl -L "https://github.com/docker/compose/releases/download/v2.2.3/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose 
sudo chmod +x /usr/local/bin/docker-compose 
sudo ln -s /usr/local/bin/docker-compose /usr/bin/docker-compose

Check installed with (if correct will output version)

docker-compose --version

Default Ports for the clients used for EL & CL

sudo ufw allow 30303
sudo ufw deny 8545
sudo ufw deny 8551
sudo ufw allow 9000
sudo ufw enable

Check your firewall rules with

sudo ufw status

Port Forwarding (if running Locally)

Login to your router and update the firewall rules, will be slightly different depending on your provider you should check your manual.

Create a working directory for Gnosischain

cd
mkdir /home/$USER/gnosis
mkdir /home/$USER/gnosis/execution-data
mkdir /home/$USER/gnosis/consensus-data

Create JWT secret

We need to enable two-way communication between the execution layer and consensus layer, this is done via JWT secret (json web token), which is a secret key that is shared only between the two clients to authenticate one another.

mkdir /home/$USER/gnosis/jwtsecret
openssl rand -hex 32 | tr -d "\n" > "/home/$USER/gnosis/jwtsecret/jwtsecret.hex"

Create docker-compose.yml for node configuration

cd gnosis
nano docker-compose.yml

This is our docker-compose.yml for configuration of our execution and consensus layer clients, right now we will just fill in for Nethermind Execution layer.

Docker Image: nethermind/nethermind

Find releases Here:

version: "3.9"
services:
  execution:
    stop_grace_period: 30s
    container_name: execution-client
    restart: always
    image: nethermind/nethermind:1.14.6
    networks:
    - gnosischain
    volumes:
    - /home/$USER/gnosis/execution-data:/data
    - /home/$USER/gnosis/jwtsecret:/jwtsecret
    - /etc/timezone:/etc/timezone:ro
    - /etc/localtime:/etc/localtime:ro
    ports:
    - 30303:30303/tcp
    - 30303:30303/udp
    expose:
    - 8545
    - 8551
    command:
    - --config=xdai
    - --datadir=/data
    - --log=INFO
    - --Sync.SnapSync=false
    - --JsonRpc.Enabled=true
    - --JsonRpc.Host=0.0.0.0
    - --JsonRpc.Port=8545
    - --JsonRpc.EnabledModules=[Web3,Eth,Subscribe,Net,]
    - --JsonRpc.JwtSecretFile=/jwtsecret/jwtsecret.hex
    - --JsonRpc.EngineHost=0.0.0.0
    - --JsonRpc.EnginePort=8551
    - --Network.DiscoveryPort=30303
    - --HealthChecks.Enabled=false
    - --Pruning.CacheMb=2048
    logging:
      driver: json-file
      options:
        max-size: 10m
        max-file: "10"
networks:
  gnosischain:
    name: gnosischain_network

IMPORTANT: spacing is really important here, I’ve got this to be easily copy and pasted into a .txt file with the right syntax. If you have errors it may be due to this, and characters not being copied over correctly.

Write out and save, usually ctrl + o then ctrl + x

To Run the Node

go in to the correct directory and run with the following command

cd gnosis
sudo docker-compose up -d execution

Check the Logs

List running containers with the following command you should see your container for our execution client (with Nethermind) is live.

sudo docker ps -a 

sudo docker-compose logs -f <service name>

This starts the logs, service Name in this case should be ‘execution’ as specified in the docker-compose.yml file. The Container name is execution-client if we view logs with docker then sudo docker logs -f execution-client

Your Execution Node can take 1–3 Days to Sync depending on your Hardware, it took me just under 24Hrs, make sure this is running in the background to sync up. You can proceed to the next steps regardless.

Download the Key Generator

cd
sudo docker pull ghcr.io/gnosischain/validator-data-generator:latest

Create Folder for Key Storage

In our working directory

mkdir -p /home/$USER/gnosis/validator-data/keys
mkdir -p /home/$USER/gnosis/validator-data/secrets

Run the Generator to Create Keystore/s:

Note: good idea to disconnect from the Internet for extra security during this step

This will create a new mnemonic seed phrase where your keystores are derived from, place the amount of Validators you wish to create for <# of val>, your ETH address in place of <ETH-withdrawal-address>

sudo docker run -it --rm -v /home/$USER/gnosis/validator-data/keys:/keystore \
ghcr.io/gnosischain/validator-data-generator:latest new-mnemonic \
--num_validators=<# of Val> --mnemonic_language=english --chain=gnosis \
--folder=/keystore --eth1_withdrawal_address=<ETH-withdrawal-address>

You will be asked to enter a password of your choosing, this is our keystore decrypt key. Write this down as we need this later to create our password files.

You will then have the seed phrase generated, you must WRITE THIS DOWN AND STORE SECURELY

Once confirmed it will generate your keystore/s (validators keys) and place them in the directory /gnosis/validator-data/keys. along with deposit_data.json

Create File for your Decrypt Key

nano /home/$USER/gnosis/validator-data/secrets/<Keystore-Name>.txt

This is our decrypt key that we created earlier, enter it on the terminal and save, return to the terminal. NOTE: the password file must have the same name as the keystore file and we need a password file per keystore.

Example, if our keystore is named keystore-m_12381_3600_0_0_0-1668110061.json in the folder ./gnosis/validator-data/keys/.then we must have a file called keystore-m_12381_3600_0_0_0-1668110061.txt containing the decrypt key, in folder .gnosis/validator-data/secrets

The consensus client is our Beacon Node and Validator Node. Teku will run this as one container.

Create docker-compose.yml for consensus client

with the following service consensus: this includes the beacon node and validator node as one service/ one docker container

this will be added to our docker-compose.yml in /gnosis

cd gnosis
sudo nano docker-compose.yml

paste the following into your terminal, after the execution services section, and before networks:

  consensus:
    container_name: consensus-client
    image: consensys/teku:latest
    restart: always
    command:
    - --network=gnosis
    - --initial-state=https://checkpoint.gnosischain.com
    - --data-beacon-path=/var/lib/teku/beacon
    - --data-path=/data										
    - --ee-endpoint=http://execution:8551
    - --ee-jwt-secret-file=/jwtsecret/jwtsecret.hex
    - --eth1-deposit-contract-max-request-size=8000
    - --log-destination=CONSOLE
    - --validator-keys=/data/keys:/data/secrets						
    - --validators-proposer-default-fee-recipient=<YOUR-ETH-ADDRESS>
    - --validators-keystore-locking-enabled=false
    - --validators-graffiti=<CUSTOM GRAFFITI>
    networks:
    - gnosischain
    ports:
    - 9000:9000 # p2p
    volumes:
    - ./validator-data:/data
    - ./consensus-data:/var/lib/teku
    - ./jwtsecret:/jwtsecret
    - /etc/timezone:/etc/timezone:ro
    - /etc/localtime:/etc/localtime:ro
    logging:
      driver: json-file
      options:
        max-size: 10m
        max-file: "10"

More Information on Teku Options can be found here, but this configuration works out the box.

https://docs.teku.consensys.net/en/latest/Reference/CLI/CLI-Syntax/

Run the Consensus Client Node

Go to working directory and run the Lighthouse Beacon Chain Node

cd gnosis 
sudo docker-compose up -d consensus

Check the Logs that everything is running okay.

sudo docker-compose logs -f consensus

If started successfully, it will start syncing. You should see in the logs on first start, It should detect jwtsecret file and our execution endpoint. Then loading <#number> validator keys which tells you the consensus client has successfully located your keystores.

At this point we are waiting for our Execution client and Consensus clients to finish syncing. This can take a while (12-24hrs or days depending on hardware). We need to wait until both EL and CL have finished syncing before proceeding to the next step.

Ensure your Consensus client (beacon node) is synced and running without errors and connected to the execution node.

Your Validator node should say beacon node synced, awaiting deposits. When ready you can make the Deposit using your deposit_data.json file in ./validator-data

Can now be done Via UI which is much easier: https://deposit.gnosischain.com/ there’s no need to convert to mGNO, as its done in the process. If you have GNO on Ethereum you will need to bridge to Gnosischain, you can Use the OmniBridge to move GNO from Ethereum.