OBOL Network - Easy Guide

This is intended to be a user-friendly guide for anyone with little experience, I will be updating this as the Phases open up throughout the Testnet, and include later Testnet’s with Obol here as well.


Obol Network

Obol Network is building technology for distributed validators (DVT) this essentially turns Ethereum Validators into a multi-sig, where a validator operates across a cluster of nodes in order to improve resilience (safety, liveness, or both) as compared to running a validator on a single node.

This opens the path to institutional staking as a validator can be secured to higher standards required by institutions.

This also democratises ETH staking, allowing users with much less than 32 $ETH required to run a single validator.

This is where Obol sits on the technology stack
This is where Obol sits on the technology stack

Obols distributed validators can connect to various consensus layer and execution layer clients forming a truly credible neutral layer.

If you want to dive deeper on Obol’s technology this is a great introduction by @solardefi. and the Docs can be found here.

Getting Started with Obol Testnet - Athena

Charon Distributed Validator Node

The First public Testnet Athena is now live (8th July 2022), Charon-Obol’s distributed validator client will be tested by a larger community of Node Operators.

Step I

You will need to run the Charon client briefly to generate an ENR private key for use in a scheduled Distributed Key Generation ceremony.

see the article on Athena Testnet, to find the form to fill if you wish to apply to join this Testnet

Hardware Requirements: Wired connection to a local device with at least 8GB memory (I am using 16GB with no issues) 4 core CPU, would recommend starting with 500GB at minimum, as a node operator you're providing a service, so best to start with good hardware that will last and perform up to standard.

This guide is assuming you have a fresh install of Ubuntu 20.04 LTS, I am running locally. Navigate to the terminal.

Update the device

sudo apt update && sudo apt upgrade -y

Install pre-requisite software

we need to install curl and git

sudo apt install curl git -y

Install docker

curl -fsSL https://get.docker.com -o get-docker.sh
sh get-docker.sh

change permissions and check you have installed correctly

sudo usermod -aG docker $USER
docker --version

Download Charon

git clone https://github.com/ObolNetwork/charon-distributed-validator-node.git

Generate your Charon ENR private key

change directory

cd charon-distributed-validator-node

run the following to generate your ENR private key

sudo docker run --rm -v "$(pwd):/opt/charon" ghcr.io/obolnetwork/charon:v0.8.1 create enr
if successful you should see something like this
if successful you should see something like this

Copy your ENR private key and back this up

you need this ENR key for your Testnet application. its a good idea to keep a backup copy locally and elsewhere. You can simply copy and save this to a text file.

Backup your Private key

make a backup of your private key, (do not submit this in your application)

The private key is stored in .charon within charon-distributed-validator-node folder, The file we are locking for is called charon-enr-private-key i’ve chosen to save a copy in Documents/backups.

Make the folder

mkdir /home/<user>/Documents/backups

Note: change to your username on your device.

sudo cp /home/<user>/charon-distributed-validator-node/.charon/charon-enr-private-key /home/<user>/Documents/backups

In order to freely move this (if you want to save to another device) we need to change permissions.

sudo chown <user>:<user> /home/<user>/Documents/backups/charon-enr-private-key

Step 2. Leader creates the DKG configuration file and distributes it to everyone else

Assigned cluster captain will do this stage

Cluster Captain- Create an .env file

cd charon-distributed-validator-cluster
cp .env.sample .env

Here we can cloned the example .env file which we can now see in our working directory, we will populate with our clusters unique details.

Cluster Captain- Open .env for editing our cluster details

We need to first get the ENR keys from each member in our cluster (IMPORTANT: these must match with the Private Keys created in Step 1, so make sure that the cluster members have double checked the correct file is in use)

Now open the env for editing in the terminal, to fill in our members unique ENR keys

nano .env 

Place ENR keys for each member (Cluster Captain first) separated by comma no space, include the ENR:- prefix like so

Cluster Captain- runs DKG configuration

Replace the following

$NAME = name of your cluster 
$FEE_RECIPIENT_ADDRESS = Eth address of our Deposit address
$WITHDRAWAL_ADDRESS = Eth address of our Deposit address

These can be set as variables, but I simply replaced into the command, Recommended to create a new ETH wallet to use as our deposit and fee address.

sudo docker run --rm -v "$(pwd):/opt/charon" --env-file .env obolnetwork/charon:v0.9.0 create dkg --name=$NAME --fee-recipient-address=$FEE_RECIPIENT_ADDRESS --withdrawal-address=$WITHDRAWAL_ADDRESS

Cluster Captain- Shares Configuration file with Cluster Members

Find the file in the directory

cd charon-distributed-validator-node/.charon
ls -la

Copy to our backups directory so we can extract and share with the other team members

sudo cp /home/<user>/charon-distributed-validator-node/.charon/cluster-definition.json /home/<user>/Documents/backups

Change permissions

sudo chown <user>:<user> /home/<user>/Documents/backups/cluster-definition.json

You should now be able to extract this file from your device and share with other Cluster members

Other Cluster members- Receive cluster-definition.json

Other cluster members should now receive the cluster-definition.json created by the Cluster captain. This should be placed in our ‘backups’ directory from Step 1.

Place in the working directory

sudo cp /home/<user>/Documents/backups/cluster-definition.json /home/<user>/charon-distributed-validator-node/.charon/

Confirm location with ls -la to see it there before moving on.

3. Run the DKG Ceremony

Now all members must run the DKG Ceremony at the same time, first all members prepare the following steps

  • Ensure cluster-definition.json is stored in the correct directory .charon

  • Ensure that our ENR is the same one Generated from the Step 1 and therefore matches our Private Key

  • All members are online and in the correct directory to run the same command

    cd charon-distributed-validator-node

To run the Ceremony, all members at the same time.

sudo docker run --rm -v "$(pwd):/opt/charon" obolnetwork/charon:v0.9.0 dkg --p2p-bootnode-relay
If successful, it will connect to all peers/Cluster team members
If successful, it will connect to all peers/Cluster team members

Possible Errors
The will connect to all cluster members, errors can occur if other Peers/cluster members use the incorrect ENR key

other members have the incorrect ENR
other members have the incorrect ENR
If you have an Incorrect ENR
If you have an Incorrect ENR

Back up the Files created by each member

a number of artefacts will be created in the .charon folder. Which should now be backed up

validator_keys/ folder. Unique to each member

deposit-data.json and cluster-lock.json are the same across all members, the Cluster captain should back this up, but good practice that all members do.

sudo cp /home/<user>/charon-distributed-validator-node/.charon/cluster-lock.json /home/<user>/Documents/backups
sudo cp /home/<user>/charon-distributed-validator-node/.charon/deposit-data.json /home/<user>/Documents/backups

Back up the Validator Keys Folder

4. Start the Distributed Validator Cluster

Set up Port Forwarding

All Members will need to open Ports 30303 & 3610 on their Router - in Port Forwarding settings.

This will be different depending on internet provider and router but generally you can log onto your router settings on a browser by typing into the search bar

This should prompt a log in screen, and you should find your log in details on your router device.

Your local device IP: which is the local IP of the device you will run Obol, find on the settings with, IPv4 address is what to look for

Set up Rules - something like this

Install docker-compose

In home directory Install Docker Compose

sudo apt install docker-compose -y

Edit the docker-compose.yml Configuration file

We need to edit the version of our config file, to 3.3

Option 1 - via the UI

Open this file, in your ‘distributed-charon-validator-node’ folder, right click and open via text. Change version: to 3.3 and Save

should look like this after editing
should look like this after editing

Option 2- Via terminal

cd charon-distributed-validator-node
nano docker-compose.yml

Change this to 3.3 and Write out (ctrl+o) then Exit (ctrl+x)

version: “3.3”

Run the docker containers

Close the terminal and open a new terminal

Change into the working directory

cd charon-distributed-validator-node
sudo docker-compose up -d
You should see something like this at the end, after a few minutes if successful
You should see something like this at the end, after a few minutes if successful

View Logs & Confirm running

Check running containers

sudo docker ps -a 

To View the logs run the following on separate terminals windows for easier management

ETH 1 - Client- GETH Logs

sudo docker logs charon-distributed-validator-node_geth_1 -f

ETH 2- Client- Lighthouse Logs

sudo docker logs charon-distributed-validator-node_lighthouse_1 -f

Obol Charon Client- Logs

sudo docker logs charon-distributed-validator-node_charon_1 -f

This one I don’t think will work until we have the rest synced, will return to this later
at this stage and lets wait until all teams GETH and Lighthouse Nodes are synced.

5. Make Deposit

After your cluster teams nodes have all Synced, depending on hardware used can vary but currently on goerli less than 12hrs.

Get Goerli ETH

The best way to get enough Goerli ETH is from the ETH staker community, you will need to join the discord and get verified by Bright ID in order to claim from the ‘Faucet Channel’

Add Goerli Network to Metamask on networks, by enabling ‘test networks’ in the settings

Cluster Captain - MAKE THE DEPOSIT

Cluster Captain makes the deposit

First the deposit-data.json needs to be edited for the launchpad to accept the file, Open with text editor and replace the following.

Ethereum Staking LaunchpadWe can head over to the ETH2 staking launchpad UI for the easiest way to make the deposit.

You will have to run through the tutorial explaining the risks and commitments of Ethereum staking to get to the end where you can add your deposit-data.json (edited with the config changes earlier) and finally make the deposit.

Save the Transactions IDs for reference, you can now wait for the deposit to be accepted on the Beacon chain which takes around 12-24 Hrs.

Updating Charon

Shut down node containers

cd charon-distributed-validator-node
sudo docker-compose down

At this point it could be a good time to update and restart your OS

Pull the Latest image

cd charon-distributed-validator-node
sudo git reset --hard
sudo git pull

Check the version for docker-compose in the docker-compose.yml, change the version from 3.8 to 3.3 again if needed

sudo nano docker-compose.yml

Restart the containers

sudo docker-compose up -d

Logs and Checks

sudo docker-compose logs --tail 100 -f

To check if some peers are not online

sudo docker logs charon-distributed-validator-node-charon-1 2>&1 | grep 'absent'

To check specific client only, you can replace geth/teku/lighthouse/charon

sudo docker logs charon-distributed-validator-node_<charon>_1 -f

Check all containers are running

sudo docker ps -a

you should see something like so

TEKU Problem

Teku keystore file /path/to/keystore-*.json.lock already in use

There is an error that is due to Teku not shutting down gracefully and not deleting the lock file it created to protect the keystore file. I’ve encountered this twice with two different cluster team members, here is a way to solve, expanded on here

Edit the docker-compose.yml with the following flag, this disables the lock file.

--validators-keystore-locking-enabled=false Like so

Another method is to simply delete the lock file in the location specified in the logs from the error, and start up the node again. however, might be likely to encounter this more than once and with a cluster of multiple, disabling this would reduce downtime.

Subscribe to GLCstaked
Receive the latest updates directly to your inbox.
Mint this entry as an NFT to add it to your collection.
This entry has been permanently stored onchain and signed by its creator.