Create a DV With a Group

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.8.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

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.

Prepare an Execution and Consensus client

Before preparing the DappNode to take part in a Distributed Validator Cluster, you must ensure you have selected an execution client & consensus client on your DappNode under the 'Stakers' tab for the network you intend to validate.

1. Login to the DappNode Interface:

   
2. Click on the 'Stakers' tab on the left side, select an execution client (e.g. Geth) & consensus client (e.g. Lodestar) & click 'Apply changes'. This will start the syncing process which can take a number of hours.

   
3. Once the clients are finished syncing, it should reflect on your 'Dashboard' as shown below.

   

Install the Obol DappNode package

With a fully synced Ethereum node now running on the DappNode, the below steps will walk through installing the Obol package via an IPFS hash and preparing for a Distributed Key Generation ceremony. Future versions of this guide will download the package from the official DappNode DappStore once a stable 1.0 release is made.

1. Before installing the package, make sure you are installing the correct one, this depends on which network your creator configures the cluster on, Holesky or Mainnet. You can find the link to both packages below:

   • Holesky Repo

   • Mainnet Repo

2. Copy the latest IPFS hash from the release details dropdown.

   
3. Go back to DappNode Dashboard > Dappstore, select the 'Public' tab, and accept the terms & conditions before proceeding.

   
4. Paste the IPFS hash you copied from Github and click 'Search' (It may take a minute for the package to be found.) You will then be presented with the package installation page. Under the blue 'Install' button, click on 'Advanced Options' & toggle the button to 'Bypass only signed safe restriction'.

   
5. Click 'Install' & in the config mode page > select new cluster & submit. (if you already have the config URL, you can select URL option.)

   
6. Accept the terms & conditions and the install process will begin.

   

   
7. You should now be able to see the Holesky Obol package under the 'Packages' tab. Click on the package to see important details.

   
8. Under the 'Info' tab, you will see pre-generated ENRs, along with information such as the status of all five distributed validator clusters, their docker volumes & other menu options.

   
9. Select any of the ENRs listed that are not already in use. This ENR will be used in the next step.

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.

Installing Sedge

First you must install Sedge, please refer to the official Sedge installation guide to do so.

Check the install was successful

Run the below command to check if your have successfully installed sedge in your computer.

Expected output:

Create an ENR using charon:

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.

Join the cluster prepared by the creator

Use the Launchpad or CLI to join the cluster configuration generated by the creator:

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.)

   
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.

   
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.

Once the creator gives you the cluster-definition.json file and you place it in a .charon subdirectory, run:

and the DKG process should begin.

Follow this step if you are signing through the DV Launchpad, importing the cluster definition URL into the DappNode package's config & then running the DKG inside the DappNode, followed by cluster run.

1. After all operators have signed with their wallet and has provided an ENR from the DappNode info tab, the Launchpad will instruct operators to begin the DKG ceremony. Click continue & navigate to the 'Dappnode/Avado' tab where the cluster definition URL is presented.

   
2. To run the Distributed Key Generation ceremony using a DappNode, you must paste the cluster definition URL into the Obol Package interface. Go to the 'Config' tab, select 'URL' from the dropdown menu, paste the cluster definition URL you retrieved from the launchpad, into the validator cluster-*field which matches the cluster you took the ENR from. Example: If you picked ENR1 for signing, then you should paste the URL into Cluster-1. Finally, click the 'Update' button at the bottom of the page.

   

   

   
3. After DappNode records the cluster definition URL, go back to the 'Info' tab and restart the Charon container.

   
4. The node is now ready and will attempt to complete the DKG. You can monitor the DKG progress via the 'Logs' tab of the package. Once all clients in the cluster can establish a connection with one another and they each complete a handshake (confirm everyone has a matching cluster_definition_hash), the key generation ceremony begins.

   
5. Example of DKG ceremony competed log.

   

Create a DV Node Backup

It is important to back up all artefacts generated by the DKG ceremony, and your node ENR private key. The below steps will show you how to download your keys & node artefacts.

1. Navigate to the backup tab inside the Obol package.

   
2. Click on the 'Backup now' button and it will open a new chrome window with a 'file save' option. Select the path where you want to save the Backup tar file.

   
3. Double click to extract the tar file. There will be folders for each charon node (max 5). Navigate to each node folder, and all artefacts related to each node will be present.

   

   

Sedge does not currently support taking part in a DKG. Follow the instructions for Launchpad to take part in the DKG with Charon, and in Step 4 you will import these keys into Sedge.

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

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.

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

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

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).

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:

1. Stop your docker compose

1. Uncomment and set the CHARON_BEACON_NODE_ENDPOINTS variable in the .env file to your beacon node's URL

1. Uncomment EL=el-none and CL=cl-none variables in the .env file and comment EL=el-nethermind and CL=cl-lighthouse variables:

1. Start your docker compose

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.

1. The following command generates the artifacts required to deploy a distributed validator on the Hoodi 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.

   You should be shown a long list of configuration outputs with the following endings:

2. 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.

Sedge Import-key

Use the following command to import keys from the directory where the .charon dir is located.

Sedge 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.

Once 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.

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.

Use an Ansible playbook to start your node. See the repo here for further instructions.

Use a Helm to start your node. See the repo here for further instructions.

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.