Ethereum Merge Guide - Lighthouse/Geth

Introduction

This guide is intended for anyone currently running mainnet for validators using Lighthouse/Geth. These updates are current as of Sep 4, 2022, installing Lighthouse-V3.1.0 and Geth -V.1.10.25.

After completing these updates, your validator will be ready for the Bellatrix hard fork ~Sep 6 and the mainnet merge ~Sep 15!

This guide is for informational purposes only. Always practice on testnet first.

Feel free to reach out to the EthStaker Discord if you have any questions.

Summary

  1. Update Geth installation, username, and directory

  2. Create JWT Token

  3. Geth

    1. Update Geth

    2. Add --authrpc.jwtsecret to geth.service file

  4. Lighthouse

    1. Update Lighthouse

    2. Add --execution-jwt and --execution-endpoint to lighthousebeacon.service file

    3. Add --suggested-fee-recipient to lighthousevalidator.service

New Guides and Improvements

There have been a few changes to Somer Esat's Guides over time, and we need to make a few updates to keep in line with best practice. The changes include:

1) Username changed from Goeth to Geth

2) Rename Geth directory from /var/lib/goethereum to /var/lib/geth

3) Remove Personal Package Archive (PPA) installation and switch to using curl

While PPA is convenient, You may not want Geth to update every time you run sudo apt update, especially if the latest version has a bug.

By usingcurl , you can choose which version to install and run.

Geth Changes

These changes won't affect the chain data, and geth will not need to re-sync.

1) Stop Geth:

sudo systemctl stop geth

2) Remove Geth:

sudo apt remove -y geth

3) Remove Geth PPA:

sudo add-apt-repository --remove ppa:ethereum/ethereum

4) Check latest version of Geth:

Find the most current update here.

This code in this guide is updated for v1.10.25 and current as of Sep 5, 2022.

5) Change to Home directory:

cd ~

6) Use curl to download latest version (be sure to update version):

curl -LO https://gethstore.blob.core.windows.net/builds/geth-linux-amd64-1.10.25-69568c55.tar.gz

7) Extract, Copy, and Clean up (update version):

tar xvf geth-linux-amd64-1.10.25-69568c55.tar.gz
cd geth-linux-amd64-1.10.25-69568c55
sudo cp geth /usr/local/bin
cd ~
rm geth-linux-amd64-1.10.25-69568c55.tar.gz
rm -r geth-linux-amd64-1.10.25-69568c55

8) Rename geth username and group (goeth -> geth):

sudo usermod -l geth goeth
sudo groupmod -n geth goeth

9) Rename geth directory to /var/lib/geth

sudo mv /var/lib/goethereum /var/lib/geth

10) Set permissions for data directory:

sudo chown -R geth:geth /var/lib/geth

11) Update other programs:

sudo apt -y update && sudo apt -y upgrade

Modify geth.service file

Note on Code Readability

This blob is simply informational, no need to copy any code from here.

This guide uses line breaks "\" to list each flag on it's own line and make the code easier to understand.

The two code examples below are identical, just with different layouts.

Single line layout:

ExecStart=/usr/local/bin/geth --mainnet --datadir /var/lib/geth --authrpc.jwtsecret /var/lib/jwtsecret/jwt.hex

Same code with line breaks:

ExecStart=/usr/local/bin/geth \
  --mainnet \
  --datadir /var/lib/geth \
  --authrpc.jwtsecret /var/lib/jwtsecret/jwt.hex

As you can see, the line breaks make the code more readable and clearly identifies each flag. This guide will use line breaks to make the service files more readable.

1) Open geth.service for editing:

sudo nano /etc/systemd/system/geth.service

2) Modify geth.service:

It's easiest to delete everything already in the file, then copy/paste the updated code

You can't highlight/delete in the terminal, so just tap delete or backspace.

3) Copy/Paste the following text into the empty geth.service file:

[Unit]
Description=Geth Execution Client (Mainnet)
After=network.target
Wants=network.target

[Service]
User=geth
Group=geth
Type=simple
Restart=always
RestartSec=5
ExecStart=/usr/local/bin/geth \
  --mainnet \
  --datadir /var/lib/geth \
  --authrpc.jwtsecret /var/lib/jwtsecret/jwt.hex

[Install]
WantedBy=default.target

Geth service file should look like this:

Once finished, use <CTRL+X> to Exit, <Y> to save, and <ENTER> to confirm

Your geth.service file should match this image

4) Reload Daemon:

sudo systemctl daemon-reload

5) Start Geth:

sudo systemctl start geth

6) Check Geth logs:

Geth logs will show an error until you create the JWT token in the next step.

sudo journalctl -fu geth.service

Create JWT Token

The JWT token is used by Execution Engine (Geth) and Consensus Client (Lighthouse) to securely communicate back and forth.

These steps will generated a random 32 byte hex that will be referenced by both clients.

1) Create directory to store the JWT file:

sudo mkdir -p /var/lib/jwtsecret

2) Generate the JWT hex file using openssl:

openssl rand -hex 32 | sudo tee /var/lib/jwtsecret/jwt.hex > /dev/null

3) Use ls (list) to confirm the hex file exists at /var/lib/jwtsecret:

ls /var/lib/jwtsecret

If the terminal responds with "jwt.hex" as shown below, then the JWT token was successfully created and stored at /var/lib/jwtsecret

Update Lighthouse

Check the most current Lighthouse release here.

This guide demonstrates updating to v3.1.0. If a newer version is available, you will need to update the code to the current version on the release page

1) Change directory to the Home folder:

cd ~

2) Remove any old lighthouse file that may exist:

Note: You might get an error if the files don't exist. No worries, just continue.

rm lighthouse
rm -r lighthouse

Download Lighthouse software (update version):

curl -LO https://github.com/sigp/lighthouse/releases/download/v3.1.0/lighthouse-v3.1.0-x86_64-unknown-linux-gnu.tar.gz

3) Stop Lighthouse services:

sudo systemctl stop lighthousevalidator && sudo systemctl stop lighthousebeacon

4) Extract binary from archive (update version):

tar xvf lighthouse-v3.1.0-x86_64-unknown-linux-gnu.tar.gz

5) Copy binary into /usr/local/bin:

sudo cp lighthouse /usr/local/bin

6) Start Lighthouse services:

sudo systemctl start lighthousebeacon && sudo systemctl start lighthousevalidator

7) Remove old files (update version):

rm lighthouse-v3.1.0-x86_64-unknown-linux-gnu.tar.gz
rm lighthouse

Congratulations, Lighthouse is now running on the most current version!

Update Beacon config file

1) Stop Beacon:

sudo systemctl stop lighthousebeacon

2) Open the beacon service file for editing:

sudo nano /etc/systemd/system/lighthousebeacon.service

Copy/paste the following into the terminal:

Delete everything in the file and copy the text below

[Unit]
Description=Lighthouse Consensus Client BN (Mainnet)
Wants=network-online.target
After=network-online.target

[Service]
User=lighthousebeacon
Group=lighthousebeacon
Type=simple
Restart=always
RestartSec=5
ExecStart=/usr/local/bin/lighthouse bn \
  --network mainnet \
  --datadir /var/lib/lighthouse \
  --http \
  --execution-endpoint http://127.0.0.1:8551 \
  --execution-jwt /var/lib/jwtsecret/jwt.hex

[Install]
WantedBy=multi-user.target

Beacon file should look like this:

Once finished, use <CTRL+X> to Exit, <Y> to save, and <ENTER> to confirm

Your beacon file should match this image

2) Reload the daemon:

sudo systemctl daemon-reload

3) Restart Beacon:

sudo systemctl restart lighthousebeacon

Update Validator config file

After the merge, your validator will receive tips from any blocks you propose. It is important that you send tips to a valid Ethereum address you can access.

Be sure to update the --suggested-fee-recipient flag as shown below

1) Open the lighthousevalidator.service file for editing:

sudo nano /etc/systemd/system/lighthousevalidator.service

2) Copy/Paste the information below into the terminal

Delete everything in the file and copy the text below.

Don't forget to update the --suggested-fee-recipient

[Unit]
Description=Lighthouse Consensus Client VC (Mainnet)
Wants=network-online.target
After=network-online.target

[Service]
User=lighthousevalidator
Group=lighthousevalidator
Type=simple
Restart=always
RestartSec=5
ExecStart=/usr/local/bin/lighthouse vc \
  --network mainnet \
  --datadir /var/lib/lighthouse \
  --suggested-fee-recipient YourFeeRecipientAddress

[Install]
WantedBy=multi-user.target

Once finished, use <CTRL+X> to Exit, <Y> to save, and <ENTER> to confirm

Merge-ready lighthousebeacon.service file:

The following screenshot shows the fee address set as 0x8fCF8DB7Afaa8C865B693bEeD5858712ABBE4DDb

Your validator file should match this image (with different fee address)

3) Reload daemon:

sudo systemctl daemon-reload

4) Restart Lighthouse Validator:

sudo systemctl restart lighthousevalidator

Check Logs & Status

You can open multiple terminal windows if you'd like to view all 3 logs at once.

Sometimes it helps to maximize the terminal window so you can read the logs more clearly. All services should be running without errors and appear "ready for merge"

1) Check Geth output:

sudo journalctl -fu geth.service

2) Check Beacon output:

sudo journalctl -fu lighthousebeacon.service

3) Check Validator output:

sudo journalctl -fu lighthousevalidator.service

Ready For Merge

Congrats! You're all set for the Bellatrix hard fork on Sep 6, and the merge ~Sep 15!

NextUpdate Geth

Last updated