Skip to main content
Gnosis Chain is moving to Gnosis EEZ

These guides cover running a node and a validator on Gnosis Chain as it runs today, and stay valid until the fork. At activation the validator set retires and nodes keep only an execution client. See the move to Gnosis EEZ.

Managing an existing validator? Go to Validator withdrawals or Voluntary exit.

Run Beacon Node: Teku

Version check

This page's content is up-to-date for Teku v26.4.0.

caution

The Beacon Node requires an Execution client in order to operate. See Step 2: Run Execution Client for more information.

Overview​

Teku is a consensus client built to meet institutional needs and security requirements. Built by PegaSys, an arm of ConsenSys, who are dedicated to building enterprise-ready clients and tools for interacting with the core Ethereum platform. More information on Teku.

Download Teku

Visit Teku's page on how to download Teku.

https://docs.teku.consensys.io/introduction

tip

Gnosis' maintains a repo with sample Teku Dockerfiles and configs

ContentLink
Release Pagehttps://github.com/ConsenSys/teku/releases
Docker Imageshttps://hub.docker.com/r/consensys/teku
Teku Docshttps://docs.teku.consensys.io/
Teku CLI Referencehttps://docs.teku.consensys.io/reference/cli

Checkpoint Sync​

We recommend the use of Checkpoint sync to sync your Beacon Node quickly, and avoid long range attacks.

Gnosis provides a checkpoint sync server at https://checkpoint.gnosischain.com.

# Usage
$ teku
  --checkpoint-sync-url https://checkpoint.gnosischain.com
More about Checkpoint Sync

Option 1: Run as a System Process​

Refer to Guide

Option 2: Run using Docker​

Images are referenced under the following pattern consensys/teku:{image-tag} with the image-tag referring to the image available on Docker Hub.

1. Folder Structure​

Create new folders:

mkdir -p /home/$USER/gnosis/consensus/data

Including the folders from your Execution client, your folder structure should now look like:

/home/$USER/gnosis/
├── jwtsecret/
├── execution/
└── consensus/
    └── data/

2. Docker Compose​

Modify your Compose file with your favorite text editor and add the consensus container. The file should now look like:

/home/$USER/gnosis/docker-compose.yml
version: "3"
services:

  execution:
    # From Step 2
    # ...

  consensus:
    user: "${PUID:-1000}"
    container_name: consensus
    image: consensys/teku:latest
    restart: always
    networks:
      - gnosis_net
    ports:
      - 9000:9000/tcp # p2p
      - 9000:9000/udp # p2p
      - 8008:8008/tcp # metrics
    expose:
      - 4000
    volumes:
      - /home/$USER/gnosis/consensus:/data
      - /home/$USER/gnosis/jwtsecret/jwt.hex:/jwt.hex
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    environment:
      - JAVA_OPTS=-Xmx4g
    command: |
      --network=gnosis
      --data-base-path=/data
      --data-storage-archive-frequency=2048
      --data-storage-mode=PRUNE
      --data-storage-non-canonical-blocks-enabled=false
      --log-destination=CONSOLE
      --logging=info
      --p2p-enabled=true
      --p2p-port=9000
      --p2p-peer-upper-bound=50
      --rest-api-enabled=true
      --rest-api-host-allowlist=*
      --rest-api-interface=0.0.0.0
      --rest-api-port=4000
      --rest-api-cors-origins=*
      --rest-api-docs-enabled=false
      --ee-endpoint=http://execution:8551
      --ee-jwt-secret-file=/jwt.hex
      --eth1-deposit-contract-max-request-size=8000
      --metrics-enabled=true
      --metrics-host-allowlist=*
      --metrics-interface=0.0.0.0
      --metrics-port=8008
      --checkpoint-sync-url=https://checkpoint.gnosischain.com
    logging:
      driver: "local"

networks:
  gnosis_net:
    name: gnosis_net

3. Environment Variables​

Add an .env file with your user id (id --user) in /home/$USER/gnosis/.env.

PUID=1000

4. Start Containers​

Start the consensus layer client listed in the compose file:

cd /home/$USER/gnosis
docker compose up -d

5. Monitor Logs​

Check your logs for each service (execution or consensus) with:

docker logs -f --tail 500 execution

6. Updating your Node​

To update, just pull the new images, then stop and restart your services:

cd /home/$USER/gnosis
docker compose pull
docker compose stop
docker compose up -d