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 Lighthouse 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 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 decentralized 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.

1. Install Prerequisite Software

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

2. Firewall Settings

sudo ufw allow 30303
sudo ufw deny 8545
sudo ufw deny 8551
sudo ufw allow 12000/udp
sudo ufw allow 13000/tcp
sudo ufw enable

Check your firewall rules with

sudo ufw status

Port Forwarding (Recommended for Local Setup)

Login to your router and Port Forward the ports that should be Open, will be slightly different depending on your provider you should check your manual for the Router.

3. Execution Layer Node- Nethermind

Create a working directory for our nodes called gnosis

cd
mkdir /home/$USER/gnosis
mkdir /home/$USER/gnosis/el-client
mkdir /home/$USER/gnosis/cl-client

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 the Execution client.

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.15.0
    networks:
    - gnosischain
    volumes:
    - /home/$USER/gnosis/el-client:/el-client/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=/el-client/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.

4. Generate Keystores

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 /home/$USER/gnosis/keystore

Run the Generator to Create Keystore/s:

Note: good idea to disconnect from the Internet for extra security, just for 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

sudo docker run -it --rm -v /home/$USER/gnosis/keystore:/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.txt

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

this will now generate your keystore/s (validators keys) and place them in the directory /gnosis/keystore/validator_keys. along with deposit_data.json

Create File for your Decrypt Key

nano /home/$USER/gnosis/keystore/password.txt

This is our decrypt key that we created earlier, the password for our keystores.

Optional: Adding New Validators to your Node.

if we wish to add more validators at a later stage, we must replace the command new-mnemonic with existing-mnemonic

an additional flag must be added, --validator_start_index=START_NUM this number should be where you left, example if you made 10 validators keystores in 1st run, the START_NUM=10

BACK UP YOUR SEED PHRASE & PASSWORD. The seed is displayed when Generated after inputting your password (decrypt key). Your validator node can run multiple keys (from the same seed) do not use the same keys in another validator as this can result in Slashing.

5. Consensus Client - Lighthouse

The consensus client is our Beacon Node and Validator Node. Lighthouse will run theses as two separate containers.

Docker Image: sigp/lighthouse:

Find releases Here:

Create docker-compose.yml for consensus client

with the following services consensus: the beacon node, validator-import: to import our keystores, validator: the validator node

these 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:
    stop_grace_period: 30s
    container_name: consensus-client
    restart: always
    image: sigp/lighthouse:v3.3.0
    networks:
    - gnosischain
    volumes:
    - ./cl-client:/cl-client/data
    - ./jwtsecret:/jwtsecret
    ports:
    - 9000:9000/tcp
    - 9000:9000/udp
    - 5054:5054/tcp
    expose:
    - 4000
    command:
    - lighthouse
    - bn
    - --disable-upnp
    - --datadir=/cl-client/data
    - --port=9000
    - --http
    - --http-address=0.0.0.0
    - --http-port=4000
    - --network=gnosis
    - --target-peers=50
    - --execution-endpoints=http://execution:8551
    - --execution-jwt=/jwtsecret/jwtsecret.hex
    - --debug-level=info
    - --suggested-fee-recipient=<YOUR-FEE-RECIPIENT-ADDRESS>
    - --validator-monitor-auto
    - --subscribe-all-subnets
    - --import-all-attestations
    - --metrics
    - --metrics-port=5054
    - --metrics-address=0.0.0.0
    - --checkpoint-sync-url=https://checkpoint.gnosischain.com
    logging:
      driver: json-file
      options:
        max-size: 10m
        max-file: "10"
  validator:
    container_name: validator-client
    image: sigp/lighthouse:v3.3.0
    networks:
    - gnosischain
    ports:
    - 5056:5056
    volumes:
    - ./validator-data:/data
    command:
    - lighthouse
    - vc
    - --network=gnosis
    - --beacon-nodes=http://consensus:4000
    - --graffiti=<YOUR-CUSTOM-GRAFFITI>
    - --debug-level=info
    - --validators-dir=/data/validators
    - --suggested-fee-recipient=<YOUR-FEE-RECIPIENT-ADDRESS>
    - --metrics
    - --metrics-port=5056
    - --metrics-address=0.0.0.0
    logging:
      driver: json-file
      options:
        max-size: 10m
        max-file: "10"

--suggested-fee-recipient should be an Ethereum format address that you fully control, this is where fees from proposing blocks will go.

--graffiti can be whatever you want, this is text that will be written to blocks that you propose.

--checkpoint-sync-url this is to sync from a recent finalized checkpoint by connecting to another synced beacon node. This is substantially faster than syncing from genesis, and will speed up the process, one is currently hosted at https://checkpoint.gnosischain.com but may change in future. Recommended for post merge

Import the Keystores to your Validator

cd gnosis

sudo docker run   --volume $PWD/keystore:/var/lib/keystores   --volume $PWD/validator-data:/data   sigp/lighthouse   lighthouse account validator import   --datadir /data   --directory /var/lib/keystores   --password-file /var/lib/keystores/password.txt   --reuse-password --network gnosis

This is a one use container that will import our validator keys from /keystore to our validator node.

If you have errors check if your decrypt key in the earlier steps is correct (will be case sensitive, unnecessary spaces will result in error).

You should now have a folder ./validator-data/validators with the imported keystores

Run the Beacon chain Node

Go to working directory and start the Lighthouse Beacon Chain Node/ Consensus client

cd gnosis 
sudo docker-compose up -d consensus

View Logs for Consensus Client

sudo docker-compose logs -f consensus

This should Start the lighthouse beacon node logs, we should see confirmed connection to our execution endpoint and our jwtsecret file.

Beacon Node Syncing

Run the Validator Node

sudo docker-compose up -d validator

Check the Logs that everything is running okay.

sudo docker-compose logs -f validator 

At the start of the logs, it should find your validators in the directory it was imported, and if still syncing, you will need to wait until both the execution and consensus nodes have finished syncing.

Once the beacon node has finished syncing, the validator/s should be connected to beacon node and awaiting activation, if successful.

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) once both clients have finished syncing our validator/s awaiting deposit, we can proceed to the deposit.

6. Make Deposit

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 /keystore

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.