The Merge is on the horizon for Gnosischain, The Gnosis beacon chain will merge with Gnosischain (formally xDai). Like Ethereum the old consensus network that handles execution, in this case POSDAO a proof-of-authority consensus, will be deprecated. Transitioning to fully decentralised and permission-less proof of stake network and moving towards parity with Ethereum.

This is intended to walk through migrating your existing setup to a Merge-ready state, if you used my old guide and are currently running a validator on Gnosischain with a similar setup. This assumes you are running GNO validators Locally on an Ubuntu 20.04 LTS device, Using Nethermind and Lighthouse clients, this guide will also continue using docker-compose.

If you have not setup a Gnosischain validator you should not follow this guide, I suggest this one to configure everything yourself or Nethermind Sedge which handles a lot of the configuration process.

Breakdown: we have 3 main goals to get merge ready along with updating to merge ready clients. This is taken from Ethereum Launchpad and will be similar for Gnosis-chain.

1.       Run an Execution client (If not already)

If you aren’t already you need to be running your own execution layer client (EL) alongside your consensus layer client (CL), Infura and alchemy will no longer work post merge.

2.       Create and add JWT token

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.

3.       Set Fee Recipient Address

The fee recipient is an Ethereum address nominated by a beacon chain validator to receive fees and tips from user transactions.

How to get merge ready

Step 1: Stop both EL and CL clients

*Note: as of writing we are still waiting on a gnosis chain merge ready version, keep an eye on announcements for the updated version and ensure we are updated to the correct one once ready. Find the merge supported images here *

and ensure that these are being used in your docker-compose.yml script

go to working directory of EL and stop the node, in my case

cd nethermind
sudo docker-compose down

Go to working directory of CL, beacon and validator node, in my case

cd gbc
sudo docker-compose down

Remove the old docker images for both EL & CL

sudo docker system prune -a

back up old docker-compose.yml files, as you may have some changes you want saved from previous build, in my case port changes.

Step 2: Re-arrange Directories

For ease of operation, it makes sense to our file structure should look like follows. we will also be running of one docker-compose.yml script.

Create main working directory and subdirectories

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

New Folder Structure

Step 3: Move EL Nethermind Data

Identify where your execution client (nethermind) data folder is, in my case

sudo mv -v /home/$USER/nethermind/* /home/$USER/gnosis/el-client/

This moves the contents of folder /nethermind into /el-client the folder nethermind_db houses the chain data that we needed to carry over. this needs to be mapped in docker-compose.yml

volumne:
- /home/$USER/gnosis/el-client/nethermind_db:/data
command:
- --datadir=/data

Move docker-compose.yml

We will move our docker-compose.yml to our working directory in gnosis. in this setup we will run of one script. Delete the old one (for nethermind) and backup for reference if need be.

Step 4: Create JWT authentication token

We need to generate our own JWT, enable and edit the config to make the CL and EL talk. This will be placed in jwtsecret in our working directory gnosis.

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

Step 5: Edit the Execution service

Add this to our execution service (Nethermind) docker-compose.yml, these are flags related to json web token required for a merge ready configuration.

    command:
    - --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

Mapping, its important our directory for blockchain data is mapped correctly, will need to change as follows

volumne:
- /home/$USER/gnosis/el-client/nethermind_db:/data
command:
--datadir=/data

These are the main changes, with the additional flags related to using our JWT secret. I would recommend grabbing the following script from here, and using in place of our execution service, which has the above additions included.

Step 5: Migrate Consensus data

Move our beacon node data

Identify where your old beacon node data is in my case

sudo mv -v /home/$USER/gbc/node_db/ /home/$USER/gnosis/cl-client/

This moves the folder node_db and its contents, which contains our beacon node data into new directory cl-client

Corresponding volume to map in docker-compose.yml

  volumes:
    - ./cl-client/node_db:/cl-client/data
  command:
    - --datadir=/cl-client/data

Move Validators

Identify where your old validator folder, imported validator keystores, is in my case

sudo mv -v /home/$USER/gbc/validators/ /home/$USER/gnosis/cl-client/

This moves the folder validators and its contents, which contain our imported keystores into the new directory cl-client

Corresponding volume to map in docker-compose.yml

 volumes:
    - ./cl-client/validators:/root/sbc/validators
 command:
    - --validators-dir=/root/sbc/validators

Step 6: Edit Consensus service

In my old guide, we were running a separate docker-compose script for the consensus client (beacon and validator node), we will be deleting that, as it will be incorporated into our docker-compose.yml in our main working directory gnosis

I would recommend grabbing the following script from here, and using in place of our consensus and validator service, below are some configuration we need to check

Replace checkpoint sync URL for consensus

- --checkpoint-sync-url=https://checkpoint.gnosischain.com

its recommended to use checkpoint sync post merge, one is currently hosted at https://checkpoint.gnosischain.com (may change in future)

It’s recommended to set the fee recipient on both the Validator Client validator and the Beacon node consensus services. This should be an Ethereum format address that you own, this is where fees from blocks proposed will go.

consensus

--execution-jwt=/jwtsecret/jwtsecret.hex
--suggested-fee-recipient <FeeRecipientAddress>

Validator

--suggested-fee-recipient <FeeRecipientAddress> 

Step 6: Restart the CL and EL Containers

take opportunity to update and restart your Ubuntu OS if you haven’t in a while

Grab new images

confirm in our docker-compose.yml that the docker images for the services are the latest or a merge ready version, this can be checked on announcements channels for gnosis or the client.

cd gnosis
sudo docker-compose pull

Restart Execution client (nethermind)

cd gnosis
sudo docker-compose up -d execution

Restart consensus client (lighthouse)

sudo docker-compose up -d consensus
sudo docker-compose up -d validator

Confirm running containers and logs

sudo docker ps -a
sudo docker-compose logs -f <consensus/validator/execution>

Note if you get errors related to docker-compose

Depending on how you installed docker-compose, such as following my old guide. I had errors before with the default version being 3.8 which needs to be changed to 3.3 in the docker-compose.yml.