Skip to main content
Version: v1.2.0

Create a DV With a Group

This quickstart guide will walk you through creating a Distributed Validator Cluster with a number of other node operators.

Pre-requisites​

  • A basic knowledge of Ethereum nodes and validators.
  • A machine that meets the minimum requirements for the network you intend to validate.
  • If you are taking part using a DappNode:
    • A computer with an up to date version of DappNode's software and an internet connection.
  • If you are taking part using Sedge, or Charon's Distributed Validator Node (CDVN) starter repo:
    • Ensure you have git installed.
    • Ensure you have docker installed.
    • Make sure docker is running before executing the commands below.

Step 1: Get your ENR​

In order to prepare for a distributed key generation ceremony, you need to create an ENR for your Charon client. This ENR is a public/private key pair that allows the other Charon clients in the DKG to identify and connect to your node. If you are creating a cluster but not taking part as a node operator in it, you can skip this step.

# Clone the repo
git clone https://github.com/ObolNetwork/charon-distributed-validator-node.git
# Change directory
cd charon-distributed-validator-node/
# Use docker to create an ENR. Backup the file `.charon/charon-enr-private-key`.
docker run --rm -v "$(pwd):/opt/charon" obolnetwork/charon:v1.2.0 create enr

You should expect to see a console output like this:

Created ENR private key: .charon/charon-enr-private-key
enr:-JG4QGQpV4qYe32QFUAbY1UyGNtNcrVMip83cvJRhw1brMslPeyELIz3q6dsZ7GblVaCjL_8FKQhF6Syg-O_kIWztimGAYHY5EvPgmlkgnY0gmlwhH8AAAGJc2VjcDI1NmsxoQKzMe_GFPpSqtnYl-mJr8uZAUtmkqccsAx7ojGmFy-FY4N0Y3CCDhqDdWRwgg4u
warning

Please make sure to create a backup of the private key at .charon/charon-enr-private-key. Be careful not to commit it to git! If you lose this file you won't be able to take part in the DKG ceremony nor start the DV cluster successfully.

tip

If instead of being shown your enr you see an error saying permission denied then you may need to update your docker permissions to allow the command to run successfully.

For Step 2 of the quickstart:

  • Select the Creator tab if you are coordinating the creation of the cluster (this role holds no position of privilege in the cluster, it only sets the initial terms of the cluster that the other operators agree to).
  • Select the Operator tab if you are accepting an invitation to operate a node in a cluster, proposed by the cluster creator.

Step 2: Create a cluster or accept an invitation to a cluster​

Collect addresses, configure the cluster, share the invitation

Before starting the cluster creation process, you will need to collect an Ethereum address for each operator in the cluster. They will need to be able to sign messages through MetaMask with this address. (Broader wallet support will be added in future.) With these addresses in hand, go through the cluster creation flow.

You will use the Launchpad to create an invitation, and share it with the operators. This video shows the flow within the DV Launchpad

The following are the steps for creating a cluster.

  1. Go to the DV Launchpad

  2. Connect your wallet

    Connect your wallet

  3. Select Create a Cluster with a group then Get Started.

    Get started
  4. Follow the flow and accept the advisories.
  5. Configure the Cluster

    • Input the Cluster Name & Cluster Size (i.e. number of operators in the cluster). The threshold will update automatically, it shows the number of nodes that need to be functioning for the validator(s) to stay active.

  6. Input the Ethereum addresses for each operator that you collected previously. If you will be taking part as an operator, click the "Use My Address" button for Operator 1.

    • Select the desired amount of validators (32 ETH each) the cluster will run. (Note that the mainnet launchpad is restricted to one validator for now.)

    • If you are taking part in the cluster, enter the ENR you generated in step one in the "What is your charon client's ENR?" field.

    • Enter the Principal address which should receive the principal 32 ETH and the accrued consensus layer rewards when the validator is exited. This can optionally be set to the contract address of a multisig / splitter contract.

    • Enter the Fee Recipient address to which the execution layer rewards will go. This can be the same as the principal address, or it can be a different address. This can optionally be set to the contract address of a multisig / splitter contract.

  7. Click Create Cluster Configuration. Review that all the details are correct, and press Confirm and Sign You will be prompted to sign two or three transactions with your MetaMask wallet. These are:

    • The config_hash. This is a hashed representation of the details of this cluster, to ensure everyone is agreeing to an identical setup.

    • The operator_config_hash. This is your acceptance of the terms and conditions of participating as a node operator.

    • Your ENR. Signing your ENR authorises the corresponding private key to act on your behalf in the cluster.

  8. Share your cluster invite link with the operators. Following the link will show you a screen waiting for other operators to accept the configuration you created.

    Invite Operators

  9. You can use the link to monitor how many of the operators have already signed their approval of the cluster configuration and submitted their ENR.

Once every participating operator is ready, the next step is the distributed key generation amongst the operators.

  • If you are not planning on operating a node, and were only configuring the cluster for the operators, your journey ends here. Well done!
  • If you are one of the cluster operators, continue to the next step.

Step 3: Run the Distributed Key Generation (DKG) ceremony​

tip

For the DKG to complete, all operators need to be running the command simultaneously. It helps if operators can agree on a certain time or schedule a video call for them to all run the command together.

  1. Once all operators successfully signed, your screen will automatically advance to the next step and look like this. Click Continue. (If you closed the tab, you can always go back to the invite link shared by the leader and connect your wallet.) Config Signing Success
  2. Copy and run the docker command on the screen into your terminal. It will retrieve the remote cluster details and begin the DKG process. Run the DKG
  3. Assuming the DKG is successful, a number of artefacts will be created in the .charon folder of the node. These include:
    • A deposit-data.json file. This contains the information needed to activate the validator on the Ethereum network.
    • A cluster-lock.json file. This contains the information needed by Charon to operate the distributed validator cluster with its peers.
    • A validator_keys/ folder. This folder contains the private key shares and passwords for the created distributed validators.
danger

Please make sure to create a backup of your .charon/ folder. If you lose your private keys you won't be able to start the DV cluster successfully and may risk your validator deposit becoming unrecoverable. Ensure every operator has their .charon folder securely and privately backed up before activating any validators.

info

The cluster-lock and deposit-data files are identical for each operator, if lost, they can be copied from one operator to another.

Now that the DKG has been completed, all operators can start their nodes.

Step 4: Start your Distributed Validator Node​

With the DKG ceremony over, the last phase before activation is to prepare your node for validating over the long term.

The CDVN repository is configured to sync an execution layer client (Nethermind) and a consensus layer client (Lighthouse) using Docker Compose, further client combinations can be prepared using Sedge. You can also leverage alternative ways to run a node such as Ansible, Helm, or Kubernetes manifests.

info

Currently, the CDVN repo has defaults for the Holesky testnet and for mainnet.

Start by copying the appropriate .env.sample.<NETWORK> file to .env, and modifying values as needed.

# To prepare the node for the Holesky test network
# Copy ".env.sample.holesky", renaming it ".env"
cp .env.sample.holesky .env


# To prepare the node for the main Ethereum network
# Copy ".env.sample.mainnet", renaming it ".env"
cp .env.sample.mainnet .env


In the same folder where you created your ENR in Step 1, and ran the DKG in Step 3, start your node in the DV cluster with docker compose.

```shell

# To be run from the ./charon-distributed-validator-node folder
# Spin up a Distributed Validator Node with a Validator Client
docker compose up -d
warning

Do not start this node until the DKG is complete, as the charon container will interfere with the charon instance attempting to take part in the DKG ceremony.

If at any point you need to turn off your node, you can run:

# Shut down the currently running Distributed Validator Node
docker compose down

You should use the Grafana dashboard that accompanies the quickstart repo to see whether your cluster is healthy.

# Open Grafana dashboard
open http://localhost:3000/d/d6qujIJVk/

In particular you should check:

  • That your Charon client can connect to the configured beacon client.
  • That your Charon client can connect to all peers directly.
  • That your validator client is connected to Charon, and has the private keys it needs loaded and accessible. Most components in the dashboard have some help text there to assist you in understanding your cluster performance. You might notice that there are logs indicating that a validator cannot be found and that APIs are returning 404. This is to be expected at this point, as the validator public keys listed in the lock file have not been deposited and acknowledged on the consensus layer yet (usually it takes ~16 hours after the deposit is made).
tip

In a Distributed Validator Cluster, it is important to have a low latency connection to your peers. Charon clients will use the NAT protocol to attempt to establish a direct connection to one another automatically. If this doesn't happen, you should port forward Charon's p2p port to the public internet to facilitate direct connections. The default port to expose is :3610. Read more about Charon's networking here.

If you have gotten to this stage, every node is up, synced and connected, congratulations. You can now move forward to activating your validator to begin staking.