Ctrlk
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.10.0. 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
  deposit      Sign and fetch a new partial deposit.
  dkg          Participate in a Distributed Key Generation ceremony
  enr          Print the ENR that identifies this client
  exit         Exit a distributed validator.
  feerecipient Manage the preferred fee recipient addresses for the cluster.
  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.

List active validators

The charon exit active-validator-list command returns a list of all distributed validators in the specified cluster whose status is ACTIVE_ONGOING, meaning they can be exited.

The enr command

The standalone charon enr command prints an Ethereum Node Record (ENR) from the client's charon-enr-private-key. This serves as a public key that identifies this client to its peers.

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.

The deposit command

Activating a validator with an incorrect withdrawal address likely results in a loss of the funds. Take care when preparing alternative deposit data for a single validator client.

For unused, inactive validators in an existing cluster, you can prepare alternative deposit data for them, allowing you to use them as validators for a different withdrawal address than originally intended.

See the advanced guide for more.

Sign a deposit for an alternative withdrawal address

A threshold of node operators must run charon deposit sign with matching parameters, to enable a new deposit data to be fetched with charon deposit fetch.

Download a fully signed alternative deposit message

charon deposit fetch outputs a file .charon/deposit-data-<timestamp>.json for use with the Ethereum deposit contract.

The feerecipient command

The feerecipient command manages the preferred fee recipient addresses for the cluster. A threshold of operators must sign new builder registration messages to update the fee recipient, after which the aggregated result can be fetched and applied locally.

Sign new fee recipient builder registrations

The charon feerecipient sign command signs new builder registration messages to update the preferred fee recipient and publishes them to a remote API. A threshold of operators must run this command with matching parameters for the new fee recipient to take effect.

Fetch aggregated fee recipient builder registrations

Once enough operators have signed their partial builder registrations, the charon feerecipient fetch command fetches and aggregates those with quorum from the remote API, writing them to a local JSON overrides file. The charon run command will then use this overrides file to apply the updated fee recipients.

List current fee recipient details

The charon feerecipient list command displays the most recent builder registration for each validator, selecting the entry with the highest timestamp from the cluster lock file, the overrides file, or the remote API.

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.

Replace an operator in a cluster

The charon alpha edit replace-operator command replaces an operator in an existing distributed validator cluster, keeping validator public keys unchanged.

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.

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?