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.
Last updated
Was this helpful?
version-v1.5 (current)
This quickstart guide will walk you through creating a Distributed Validator Cluster with a number of other node operators.
Last updated
Was this helpful?
Was this helpful?
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 Sedge, or Charon's Distributed Validator Node (CDVN) starter repo:
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.5.2 create enrYou 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-FY4N0Y3CCDhqDdWRwgg4uPlease 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.
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.
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.
Go to the DV Launchpad
Connect your wallet
Select Create a Cluster with a group then Get Started.
Follow the flow and accept the advisories.
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.
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.
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.
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.
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.
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.
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.) \
Copy and run the docker command on the screen into your terminal. It will retrieve the remote cluster details and begin the DKG process. \
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.
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.
Now that the DKG has been completed, all operators can start their nodes.
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.
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{% hint style="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. {% endhint %}
If at any point you need to turn off your node, you can run:
# Shut down the currently running Distributed Validator Node
docker compose downYou 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). {% endtab %}
{% tab title="Sedge" %} To prepare a Distributed Validator node using sedge, we will use the sedge generate command to prepare a docker-compose file of our preferred clients, sedge import-key to import the artifacts created during the DKG ceremony, and sedge run to begin running the node.
Sedge generate​
With Sedge installed, and the DKG complete, it’s time to deploy a Distributed Validator. Using the sedge generate command and its subcommands, Sedge will create a Docker Compose file needed to run the validator node.
The following command generates the artifacts required to deploy a distributed validator on the Holesky network, using Teku as the validator client, Prysm as the consensus client, and Geth as the execution client. For additional supported client combinations, refer to the documentation here.
sedge generate full-node --validator=teku --consensus=prysm --execution=geth --network=holesky --distributedYou should be shown a long list of configuration outputs with the following endings:
2024-09-20 12:56:15 -- [INFO] Generation of files successfully, happy staking! You can use now 'sedge run' to start the setup.Explore the config files.
You should now see a sedge-data directory created in the folder where you ran the sedge generate command. To view the directory contents, use the ls command.
ls sedge-data
> docker-compose.yml jwtsecretSedge Import-key​
Use the following command to import keys from the directory where the .charon dir is located.
sedge import-key --from ./ holesky tekuSedge Run​
After confirming the configurations and ensuring all files are in place, use the sedge run command to deploy the DV docker containers. Sedge will then begin pulling all the required Docker images.
> sedge run
2024-09-20 13:11:49 -- [INFO] [Logger Init] Log level: info
2024-09-20 13:11:49 -- [WARN] A new Version of sedge is available. Please update to the latest Version. See https://github.com/NethermindEth/sedge/releases for more information. Latest detected tag: fatal: not a git repository (or any of the parent directories): .git
2024-09-20 13:11:50 -- [INFO] Setting up containers
2024-09-20 13:11:50 -- [INFO] Running command: docker compose -f /sedge/sedge-data/docker-compose.yml build
2024-09-20 13:11:50 -- [INFO] Running command: docker compose -f /sedge-data/docker-compose.yml pull
[+] Pulling 16/44
⠇ consensus [⣀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀] Pulling 20.8s
â ™ b003b463d750 Downloading [===============> ] 32.9kB/103.7kB 14.2s
â ™ fe5ca62666f0 Waiting 14.2s
â ™ b02a7525f878 Waiting 14.2s
â ™ fcb6f6d2c998 Waiting 14.2s
â ™ e8c73c638ae9 Waiting 14.2s
â ™ 1e3d9b7d1452 Waiting 14.2s
â ™ 4aa0ea1413d3 Waiting 14.2s
â ™ 7c881f9ab25e Waiting 14.2s
â ™ 5627a970d25e Waiting 14.2s
â ™ 5cf83054c259 Waiting 14.2s
â ™ fec68abcb14d Waiting 14.2s
â ™ 4d5ad547ce94 Waiting 14.2s
â ™ e1ea80853e89 Waiting 14.2s
â ™ 17b1d7e8d99a Waiting 14.2s
â ™ 841a2fc14521 Waiting 14.2s
â ™ 55b44d28dd62 Waiting 14.2s
â ™ f3e3115c6547 Pulling fs layer 14.2s
â ™ 3cec53649029 Waiting 14.2s
â ™ 01739568079a Waiting 14.2s
â ™ c6bd24b188db Waiting 14.2s
â ™ fe8d2e9c9467 Waiting 14.2s
â ™ c151008cbec0 Waiting 14.2s
â ™ de1ef6c90686 Waiting 14.2s
â ™ 03d09d97b125 Waiting 14.2s
✔ execution Pulled 9.3s
✔ a258b2a6b59a Pull complete 1.5s
✔ a2d6cf6afda3 Pull complete 1.7s
✔ a3dd8256fc41 Pull complete 6.9sOnce all docker images are pulled, sedge will create & start the containers to run all the required clients. See below for example output of the progress.
✔ 8db8b5d461a7 Pull complete 24.1s
✔ 2288b86b1d5f Pull complete 24.3s
✔ 4becb7b9a44b Pull complete 24.3s
✔ 4f4fb700ef54 Pull complete 24.3s
✔ 5c35e3728c84 Pull complete 35.1s
2024-09-20 13:12:45 -- [INFO] Running command: docker compose -f /sedge-data/docker-compose.yml create
[+] Creating 7/7
✔ Network sedge-network Created 0.1s
✔ Container sedge-dv-client Created 0.4s
✔ Container sedge-consensus-client Created 0.4s
✔ Container sedge-execution-client Created 0.4s
✔ Container sedge-mev-boost Created 0.4s
✔ Container sedge-validator-blocker Created 0.4s
✔ Container sedge-validator-client Created 0.1s
2024-09-20 13:12:45 -- [INFO] Running command: docker compose -f /sedge-data/docker-compose.yml up -d
[+] Running 4/5
✔ Container sedge-consensus-client Started 1.0s
â § Container sedge-validator-blocker Waiting 130.8s
✔ Container sedge-dv-client Started 1.0s
✔ Container sedge-execution-client Started 1.3s
✔ Container sedge-mev-boost Started Given time, the execution and consensus clients should complete syncing, and if a Distributed Validator has already been activated, the node should begin to validate.
If you encounter issues with using Sedge as part of a DV cluster, consider consulting the Sedge docs directly, or opening an issue or pull request if appropriate. {% endtab %}
{% tab title="Ansible" %} Use an ansible playbook to start your node. See the repo here for further instructions. {% endtab %}
{% tab title="Helm" %} Use a Helm to start your node. See the repo here for further instructions. {% endtab %}
{% tab title="Kubernetes" %} Use Kubernetes manifests to start your Charon client and validator client. These manifests expect an existing Beacon Node Endpoint to connect to. See the repo here for further instructions. {% endtab %} {% endtabs %} {% endtab %}
{% tab title="Existing Beacon Node" %} {% hint style="warning" %} Using a remote beacon node will impact the performance of your Distributed Validator and should be used sparingly. {% endhint %}
If you already have a beacon node running somewhere and you want to use that instead of running an EL (nethermind) & CL (lighthouse) as part of the example repo, you can disable these images. To do so, follow these steps:
Copy the docker-compose.override.yml.sample file
sh
cp -n docker-compose.override.yml.sample docker-compose.override.ymlUncomment the profiles: [disable] section for both nethermind and lighthouse. The override file should now look like this
services:
nethermind:
# Disable nethermind
profiles: [disable]
# Bind nethermind internal ports to host ports
#ports:
#- 8545:8545 # JSON-RPC
#- 8551:8551 # AUTH-RPC
#- 6060:6060 # Metrics
lighthouse:
# Disable lighthouse
profiles: [disable]
# Bind lighthouse internal ports to host ports
#ports:
#- 5052:5052 # HTTP
#- 5054:5054 # Metrics
...Then, uncomment and set the CHARON_BEACON_NODE_ENDPOINTS variable in the .env file to your beacon node's URL
...
# Connect to one or more external beacon nodes. Use a comma separated list excluding spaces.
CHARON_BEACON_NODE_ENDPOINTS=<YOUR_REMOTE_BEACON_NODE_URL>
...Restart your docker compose
docker compose down
docker compose up -dIn 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.