SDKAPI
Edit

CLI Reference

A go-based middleware client for taking part in Distributed Validator clusters.

The following is a reference for Charon version v1.7.1. Find the latest release on our Github.

The following are the top-level commands available to use.

charon --help
Charon enables the operation of Ethereum validators in a fault tolerant manner by splitting the validating keys across a group of trusted parties using threshold cryptography.

Usage:
  charon [command]

Available Commands:
  alpha       Alpha subcommands provide early access to in-development features
  combine     Combine the private key shares of a distributed validator cluster into a set of standard validator private keys
  completion  Generate the autocompletion script for the specified shell
  create      Create artifacts for a distributed validator cluster
  dkg         Participate in a Distributed Key Generation ceremony
  enr         Print the ENR that identifies this client
  exit        Exit a distributed validator.
  help        Help about any command
  relay       Start a libp2p relay server
  run         Run the charon middleware client
  version     Print version and exit

Flags:
  -h, --help   Help for charon

Use "charon [command] --help" for more information about a command.

The create command

The create command handles the creation of artifacts needed by Charon to operate.

Creating an ENR for Charon

An enr is an Ethereum Node Record. It is used to identify this Charon client to its other counterparty Charon clients across the internet.

Create a full cluster locally

The charon create cluster command creates a set of distributed validators locally; including the private keys, a cluster-lock.json file, and deposit data. This command should only be used for solo-operation of distributed validators. To run a distributed validator cluster with a group of operators, it is preferable to create these artifacts using the DV Launchpad and the charon dkg command. That way, no single operator custodies all of the private keys to a distributed validator.

This command produces new distributed validator private keys or handles and splits pre-existing traditional validator private keys, please use caution and keep these private keys securely backed up and secret.

Creating the configuration for a DKG Ceremony

This charon create dkg command creates a cluster_definition.json file used for the charon dkg command.

The dkg command

Performing a DKG Ceremony

The charon dkg command takes a cluster_definition.json file that instructs Charon on the terms of a new distributed validator cluster to be created. Charon establishes communication with the other nodes identified in the file, performs a distributed key generation ceremony to create the required threshold private keys, and signs deposit data for each new distributed validator. The command outputs the cluster-lock.json file and key shares for each Distributed Validator created.

The run command

Run the Charon middleware

This run command accepts a cluster-lock.json file that was created either via a charon create cluster command or charon dkg. This lock file outlines the nodes in the cluster and the distributed validators they operate on behalf of.

The exit command

A running Charon client will aggregate and broadcast signed exit messages it receives from its validator client immediately. These exit commands are instead used to pre-sign exit messages for an active distributed validator, to save to disk, or to broadcast; once enough of the operators of the cluster have submitted their partial exit signatures. Fully signed exit messages give a user or protocol a guarantee that they can exit an active validator at any point in future without the further assistance of the cluster's operators. In future, execution-layer initiated exits will provide an even stronger guarantee that a validator can be exited by the withdrawal address it belongs to.

Pre-sign exit messages for active validators

This command requires Charon to access the distributed validator's private keys, please use caution and keep these private keys securely backed up and secret.

The default publish-address for this command sends signed exit messages to Obol's API for aggregation and distribution. Exit signatures are stored in line with Obol's terms and contiditions.

This command submits partial exit signatures to the remote API for aggregation. The required flags are --beacon-node-url and --validator-public-key of the validator you wish to exit. An exit message can only be signed for a validator that is fully deposited and assigned a validator index.

Delete exit message

Delete a previously signed exit message for a given validator from the remote API. The required flag is either --validator-public-key of the validator message you wish to delete or --all to delete all validators' exit message.

Download fully signed exit messages for cold storage

Once enough operators have submitted their partial signatures for an active validator, you can use the charon exit fetch command to download the complete exit message to a file for safe keeping. This file can be given to a delegator who wants a guarantee that they can exit the distributed validator if need be.

Broadcast a signed exit message

The charon exit broadcast subcommand can be used to broadcast either a signed exit message from a file that was downloaded via the fetch command, or it can retrieve and broadcast an exit message directly from the API.

The combine command

Combine distributed validator key shares into a single validator key

The combine command combines many validator key shares into a single Ethereum validator key.

This command requires Charon to access the distributed validator's private keys, please use caution and keep these private keys securely backed up and secret.

To run this command, one needs at least a threshold number of node operator's .charon directories, which need to be organized into a single folder:

That is, each operator .charon directory must be placed in a parent directory, and renamed to avoid conflicts.

If for example the lock file defines 2 validators, each validator_keys directory must contain exactly 4 files, a JSON and TXT file for each validator.

Those files must be named with an increasing index associated with the validator in the lock file, starting from 0.

The chosen folder name does not matter, as long as it's different from .charon.

At the end of the process combine will create a new directory specified by --output-dir containing the traditional validator private keystore.

By default, the combine command will refuse to overwrite any private key that is already present in the destination directory.

To force the process, use the --force flag.

The generated private keys are in the standard EIP-2335 format, and can be imported in any Ethereum validator client that supports it.

Ensure your distributed validator cluster is completely shut down for at least two epochs before starting a replacement validator or you are likely to be slashed.

Host a relay

Relays run a libp2p circuit relay server that allows Charon clusters to perform peer discovery and for Charon clients behind strict NAT gateways to be communicated with. If you want to self-host a relay for your cluster(s) the following command will start one.

You can also consider adding alternative public relays to your cluster by specifying a list of p2p-relays in charon run.

Experimental commands

These commands are subject to breaking changes until they are moved outside of the alpha subcommand in a future release.

Edit cluster configuration

The charon alpha edit commands allow you to modify existing distributed validator cluster configurations.

Add validators to a cluster

The charon alpha edit add-validators command allows you to generate new validators and add them to an existing cluster. This process is very similar to the charon dkg ceremony, which requires all node operators to participate, because under the hood it runs the same DKG protocol with additional actions and verifications.

This is an alpha feature and is not yet recommended for production use.

Add operators to a cluster

The charon alpha edit add-operators command adds new operators to an existing distributed validator cluster whilst keeping all validator public keys unchanged. All existing operators and new operators must participate in this ceremony.

This is an alpha feature and is not yet recommended for production use.

Remove operators from a cluster

The charon alpha edit remove-operators command removes operators from an existing distributed validator cluster whilst leaving all validators intact. Remaining operators must participate in this ceremony.

This is an alpha feature and is not yet recommended for production use.

Recreate private key shares

The charon alpha edit recreate-private-keys command creates new private key shares to replace the existing validator private keys whilst retaining the same operator identities and validator public keys. All operators must participate in this ceremony.

This is an alpha feature and is not yet recommended for production use.

Replace an operator in a cluster

The charon alpha edit replace-operator command replaces an existing operator in a distributed validator cluster with a new operator, whilst keeping all validators intact. All remaining and new operators must participate in this ceremony.

This is an alpha feature and is not yet recommended for production use.

Test your candidate distributed validator cluster

Charon comes with a test suite for understanding the suitability and readiness of a given setup.

Test all

Test beacon node

Test infra

Test MEV

Test Charon peers

Test validator client

PreviousCharon NetworkingNextFurther Reading

Last updated

Was this helpful?