Skip to main content

Interactive Guide

Before you start

Hey node runners, to provide a comprehensive guideline for both beginners and experienced node runners, we offer two paths for you to choose from for building your node: Interactive Guide and Step-by-Step.

Interactive Guide: By selecting the configurations below, you are given a general walk-through of setting up the node based on different Operating system, Network, Execution client and Consensus client. In the current version, CLI commands are given to run as system process. Recommended for experienced node runners.

Step-by-Step: A detailed flow on running a node. Options include running as system process and using docker. Recommended for beginners.

Select a configuration​

* disabled options: unsupported clients

Introduction​

At a high level, we'll walk through the following flow:

  1. Configure an execution node using an execution-layer client.
  2. Configure a beacon node using a consensus-layer client.
  3. Configure a validator and stake GNO (optional).

Review prerequisites and best practices​

Node typeBenefitsRequirements
Execution + beacon

  • Contributes to the security of Gnosis.

  • Lets you access the Gnosis network directly without having to trust a third party service.
  • Lets you run a validator post-Merge.

Check requirements section.

Validator

Lets you stake GNO, propose + validate blocks, earn staking rewards + transaction fee tips.

  • Everything above, plus...

  • Software: Validator client, browser-based crypto wallet (instructions below)

  • Hardware: (Recommended) A new machine that has never been connected to the internet that you can use to securely generate your mnemonic phrase and keypair

  • 1 GNO (Gnosis Mainnet)
  • 1 Testnet GNO (Chiado)

Step 1: Configure Server​

tip

Check out all recommended steps to configure server

Create the following folder structure on your disk, the entire tutorial will assume it:

📂gnosis
├── 📂 jwtsecret/
├── 📂 execution/
└── 📂 consensus/
    ├── 📂 data/
    ├── 📂 keystores/
    └── 📂 validators/
mkdir gnosis && cd gnosis &&
mkdir jwtsecret && mkdir execution && mkdir consensus &&
cd consensus &&
mkdir data && mkdir keystores && mkdir validators &&
cd ..

Generate JWT Secret

The HTTP connection between your beacon node and execution node needs to be authenticated using a JWT token.

Use a utility like OpenSSL to create the token via command:

openssl rand -hex 32 | tr -d "\n" > "./jwtsecret/jwt.hex"
Other ways to generate the jwt.hex file
  1. Use an execution or consensus client to generate the ./jwtsecret/jwt.hex file (check their documentation).
  2. Use an online generator like this. Copy and paste this value into a ./jwtsecret/jwt.hex file.

For options (1) and (3), create the file by running:


echo 'PLACE_HERE_YOUR_TOKEN' > ./jwtsecret/jwt.hex

tip

Place the jwt.hex file in the jwtsecret folder, so it can be referenced in the next steps as ../jwtsecret/jwt.hex for the consensus and execution clients.

Step 2: Run an Execution client​

In this step, you'll install an execution-layer client that the consensus-layer node will connect to.

  • Install dependencies

    sudo apt-get update && sudo apt-get install libsnappy-dev libc6-dev libc6 unzip -y

  • Copy the download link for Linux, MacOS or Arm64 package from the Nethermind download page.

  • Download Nethermind

    wget [URL_FROM_PREVIOUS_STEP]

  • Unzip the downloaded file

    unzip [FILE_NAME] -d execution

  • Get into the folder

    cd execution

  • Execute Nethermind

    ./nethermind \
        --config gnosis \
        --JsonRpc.Enabled true \
        --HealthChecks.Enabled true \
        --HealthChecks.UIEnabled true \
        --JsonRpc.EnginePort=8551 \
        --JsonRpc.JwtSecretFile=../jwtsecret/jwt.hex
Upgrading?

Remove AuraMerge.Enabled since it is now covered in the Merge.Enabled key.

Step 3: Run a Beacon Node​

  • Go to the lighhouse releases page and copy the url of the latest release based on your OS version.

  • Download the lighthouse-VERSION-ARQ.tar.gz binary.

    wget [URL_FROM_PREVIOUS_STEP]

  • Extract the downloaded file

    tar -xvf lighthouse-VERSION-ARQ.tar.gz --directory  consensus

  • Get into the folder

    cd consensus

  • Execute Lighthouse

    ./lighthouse \
    --network gnosis beacon_node \
    --datadir=data \
    --http \
    --execution-endpoint http://localhost:8551 \
    --execution-jwt ../jwtsecret/jwt.hex \
    --checkpoint-sync-url "https://checkpoint.gnosischain.com"

Step 4: Run a Validator​

Step 4a: Generate Validator Keys​

danger

We highly recommend generating keystores on a safe, completely offline device.

Securely backup your mnemonic, keystores, and password and keep them in a safe place.

tip

Learn more about keys and withdrawal credentials.

  • Copy the download link for Linux, MacOS or Arm64 package from the validator data generation tool.

  • Download the Validator Data Generation tool

    wget [URL_FROM_PREVIOUS_STEP]

  • Unzip the downloaded file

    tar -xvf [FILE_NAME]

  • Get into the folder

    cd deposit-cli-...

  • Execute Validator Data Generation tool and follow the instructions. In case of doubts, check the tool documentation.

    Tip: add the --eth1_withdrawal_address flag when creating your keys, pointing to an address you control.

    • If you want to generate a new mnemonic:

      ./deposit new-mnemonic --folder ../consensus/keystores

    • If you already have a mnemonic generated:

      ./deposit existing-mnemonic --folder ../consensus/keystores

      You will be asked for a mnemonic and index (key number).

  • Select the language of the UI and mnemonic.
  • Choose the number of validators. Remember: 1 GNO = 1 validator. You can run many validators in the same machine.
Choose gnosis on the network/chain name.
  • Create a password to encrypt the keys.
  • The mnemonic (seed phrase) will show on screen. Save it in a secure place (idealy offline).
  • Type your mnemonic to confirm in the tool.
  • Wait until the keys are created. Two types of files will be generated:
    • deposit_data-*.json
    • One keystore-*.json per validator
  • Save the location of the generated keys, and copy them in a backup USB memory or any other secure storage.
success

For custom setup and more instructions, check the Validator Data Generation tool documentation.

Step 4b: Run a Validator​

To run a validator, we need to first import the keys generated in the previous step.

  • In a new command line window, navigate to the consensus folder and execute Lighthouse validator client
  • To ease the import process, we will create a password.txt file containing the password used to encrypt the validator keys.
echo 'PLACE_HERE_YOUR_PASSWORD' > keystores/password.txt
  • Import the validator keys using lighthouse:
./lighthouse account_manager validator import \
    --network gnosis \
    --password-file keystores/password.txt \
    --reuse-password \
    --directory keystores \
    --datadir validators
  • Start your lighhouse validator:
./lighthouse validator_client \
    --network gnosis \
    --datadir validators \
    --enable-doppelganger-protection \
    --suggested-fee-recipient="0x0" \
    --metrics \
    --metrics-address=0.0.0.0 \
    --metrics-port=5064 \
    --graffiti "gnosis-docs-graffiti"

Replace suggested-fee-recipient with your Gnosis address. This fee recipient address will receive tips from user transactions from the block the validator proposed. If not set, the tips will be sent to zero address, that is burnt competely. It is strongly recommended that you configure this value in your setup. Learn more about suggested fee recipient flag in Lighthouse docs.

Replace graffiti with your own graffiti. It is an optional field that can be used to add a message to the block by the proposer.

Step 4c: Fund your validator​

Follow the instructions in the Fund Validator page.

Available options:

  1. Deposit UI
  2. Direct interaction with Contracts

Step 4d: Verify Validator​

After depositing and starting your validator, your validator will go through a process of becoming active.

Image: Process of Validator Activation

You can verify the status of your validators following these steps:

  1. Navigate to the deposit tool and click on the Validator Status tab.

  1. Upload your deposit_data.json file used during the deposit step.

  1. Check the status of all your validators included in the deposit_data.json file.

  1. Optionally, click on the import all validators into the Beacon Chain Explorer Dashboard to see detailed status of your validators.

  1. The Gnosis Beacon Chain Explorer is a fork of the Ethereum Beaconcha.in explorer.

See more about the validator statuses and Deposit Process in the Beaconcha.in Knowledge Base.

More Resources​