Charon CLI reference

warning

The charon client is under heavy development, interfaces are subject to change until a first major version is published.

The following is a reference for charon version v0.9.0. Find the latest release on our Github.

Available Commands

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:
  bootnode    Start a discv5 bootnode server
  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 this client's Ethereum Node Record
  help        Help about any command
  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.

create subcommand

The create subcommand handles the creation of artifacts needed by charon to operate.

charon create --help
Create artifacts for a distributed validator cluster. These commands can be used to facilitate the creation of a distributed validator cluster between a group of operators by performing a distributed key generation ceremony, or they can be used to create a local cluster for single operator use cases.

Usage:
  charon create [command]

Available Commands:
  cluster     Create private keys and configuration files needed to run a distributed validator cluster locally
  dkg         Create the configuration for a new Distributed Key Generation ceremony using charon dkg
  enr         Create an Ethereum Node Record (ENR) private key to identify this charon client

Flags:
  -h, --help   Help for create

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

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.

charon create enr --help
Create an Ethereum Node Record (ENR) private key to identify this charon client

Usage:
  charon create enr [flags]

Flags:
      --data-dir string                The directory where charon will store all its internal data (default ".charon")
  -h, --help                           Help for enr
      --p2p-allowlist string           Comma-separated list of CIDR subnets for allowing only certain peer connections. Example: 192.168.0.0/16 would permit connections to peers on your local network only. The default is to accept all connections.
      --p2p-bootnode-relay             Enables using bootnodes as libp2p circuit relays. Useful if some charon nodes are not have publicly accessible.
      --p2p-bootnodes strings          Comma-separated list of discv5 bootnode URLs or ENRs. (default [http://bootnode.gcp.obol.tech:3640/enr])
      --p2p-bootnodes-from-lockfile    Enables using cluster lock ENRs as discv5 bootnodes. Allows skipping explicit bootnodes if key generation ceremony included correct IPs.
      --p2p-denylist string            Comma-separated list of CIDR subnets for disallowing certain peer connections. Example: 192.168.0.0/16 would disallow connections to peers on your local network. The default is to accept all connections.
      --p2p-external-hostname string   The DNS hostname advertised by libp2p. This may be used to advertise an external DNS.
      --p2p-external-ip string         The IP address advertised by libp2p. This may be used to advertise an external IP.
      --p2p-tcp-address strings        Comma-separated list of listening TCP addresses (ip and port) for libP2P traffic. (default [127.0.0.1:3610])
      --p2p-udp-address string         Listening UDP address (ip and port) for discv5 discovery. (default "127.0.0.1:3630")

Create a full cluster locally

charon create cluster creates a set of distributed validators locally, including the private keys, a cluster.lock file, and deposit and exit data. However, this command should only be used for solo use of distributed validators. To run a Distributed Validator with a group of operators, it is preferable to create these artifacts using the charon dkg command. That way, no single operator custodies all of the private keys to a distributed validator.

charon create cluster --help
Creates a local charon cluster configuration including validator keys, charon p2p keys, cluster-lock.json and a deposit-data.json. See flags for supported features.

Usage:
  charon create cluster [flags]

Flags:
      --clean                       Delete the cluster directory before generating it.
      --cluster-dir string          The target folder to create the cluster in. (default ".charon/cluster")
  -h, --help                        Help for cluster
      --network string              Ethereum network to create validators for. Options: mainnet, prater, kintsugi, kiln, gnosis. (default "prater")
  -n, --nodes int                   The number of charon nodes in the cluster. (default 4)
      --split-existing-keys         Split an existing validator's private key into a set of distributed validator private key shares. Does not re-create deposit data for this key.
      --split-keys-dir string       Directory containing keys to split. Expects keys in keystore-*.json and passwords in keystore-*.txt. Requires --split-existing-keys.
  -t, --threshold int               The threshold required for signature reconstruction. Minimum is n-(ceil(n/3)-1). (default 3)
      --withdrawal-address string   Ethereum address to receive the returned stake and accrued rewards. (default "0x0000000000000000000000000000000000000000")

Creating the configuration for a DKG Ceremony

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

charon create dkg --help
Create a cluster definition file that will be used by all participants of a DKG.

Usage:
  charon create dkg [flags]

Flags:
      --dkg-algorithm string           DKG algorithm to use; default, keycast, frost (default "default")
      --fee-recipient-address string   Optional Ethereum address of the fee recipient
  -h, --help                           Help for dkg
      --name string                    Optional cosmetic cluster name
      --network string                 Ethereum network to create validators for. Options: mainnet, prater, kintsugi, kiln, gnosis. (default "prater")
      --num-validators int             The number of distributed validators the cluster will manage (32ETH staked for each). (default 1)
      --operator-enrs strings          [REQUIRED] Comma-separated list of each operator's Charon ENR address.
      --output-dir string              The folder to write the output cluster-definition.json file to. (default ".charon")
  -t, --threshold int                  The threshold required for signature reconstruction. Minimum is n-(ceil(n/3)-1). (default 3)
      --withdrawal-address string      Withdrawal Ethereum address (default "0x0000000000000000000000000000000000000000")

Performing a DKG Ceremony

Th 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 and exit data for each new distributed validator. The command outputs the cluster.lock file and key shares for each Distributed Validator created.

charon dkg --help
Participate in a distributed key generation ceremony for a specific cluster definition that creates
distributed validator key shares and a final cluster lock configuration. Note that all other cluster operators should run
this command at the same time.

Usage:
  charon dkg [flags]

Flags:
      --data-dir string                The directory where charon will store all its internal data (default ".charon")
      --definition-file string         The path to the cluster definition file. (default ".charon/cluster-definition.json")
  -h, --help                           Help for dkg
      --log-format string              Log format; console, logfmt or json (default "console")
      --log-level string               Log level; debug, info, warn or error (default "info")
      --p2p-allowlist string           Comma-separated list of CIDR subnets for allowing only certain peer connections. Example: 192.168.0.0/16 would permit connections to peers on your local network only. The default is to accept all connections.
      --p2p-bootnode-relay             Enables using bootnodes as libp2p circuit relays. Useful if some charon nodes are not have publicly accessible.
      --p2p-bootnodes strings          Comma-separated list of discv5 bootnode URLs or ENRs. (default [http://bootnode.gcp.obol.tech:3640/enr])
      --p2p-bootnodes-from-lockfile    Enables using cluster lock ENRs as discv5 bootnodes. Allows skipping explicit bootnodes if key generation ceremony included correct IPs.
      --p2p-denylist string            Comma-separated list of CIDR subnets for disallowing certain peer connections. Example: 192.168.0.0/16 would disallow connections to peers on your local network. The default is to accept all connections.
      --p2p-external-hostname string   The DNS hostname advertised by libp2p. This may be used to advertise an external DNS.
      --p2p-external-ip string         The IP address advertised by libp2p. This may be used to advertise an external IP.
      --p2p-tcp-address strings        Comma-separated list of listening TCP addresses (ip and port) for libP2P traffic. (default [127.0.0.1:3610])
      --p2p-udp-address string         Listening UDP address (ip and port) for discv5 discovery. (default "127.0.0.1:3630")

Run the Charon middleware

This run command accepts a cluster.lock 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.

charon run --help
Starts the long-running Charon middleware process to perform distributed validator duties.

Usage:
  charon run [flags]

Flags:
      --beacon-node-endpoint string     Beacon node endpoint URL. Deprecated, please use beacon-node-endpoints.
      --beacon-node-endpoints strings   Comma separated list of one or more beacon node endpoint URLs.
      --builder-api                     Enables the builder api. Will only produce builder blocks. Builder API must also be enabled on the validator client. Beacon node must be connected to a builder-relay to access the builder network.
      --data-dir string                 The directory where charon will store all its internal data (default ".charon")
      --feature-set string              Minimum feature set to enable by default: alpha, beta, or stable. Warning: modify at own risk. (default "stable")
      --feature-set-disable strings     Comma-separated list of features to disable, overriding the default minimum feature set.
      --feature-set-enable strings      Comma-separated list of features to enable, overriding the default minimum feature set.
  -h, --help                            Help for run
      --jaeger-address string           Listening address for jaeger tracing.
      --jaeger-service string           Service name used for jaeger tracing. (default "charon")
      --lock-file string                The path to the cluster lock file defining distributed validator cluster. (default ".charon/cluster-lock.json")
      --log-format string               Log format; console, logfmt or json (default "console")
      --log-level string                Log level; debug, info, warn or error (default "info")
      --monitoring-address string       Listening address (ip and port) for the monitoring API (prometheus, pprof). (default "127.0.0.1:3620")
      --p2p-allowlist string            Comma-separated list of CIDR subnets for allowing only certain peer connections. Example: 192.168.0.0/16 would permit connections to peers on your local network only. The default is to accept all connections.
      --p2p-bootnode-relay              Enables using bootnodes as libp2p circuit relays. Useful if some charon nodes are not have publicly accessible.
      --p2p-bootnodes strings           Comma-separated list of discv5 bootnode URLs or ENRs. (default [http://bootnode.gcp.obol.tech:3640/enr])
      --p2p-bootnodes-from-lockfile     Enables using cluster lock ENRs as discv5 bootnodes. Allows skipping explicit bootnodes if key generation ceremony included correct IPs.
      --p2p-denylist string             Comma-separated list of CIDR subnets for disallowing certain peer connections. Example: 192.168.0.0/16 would disallow connections to peers on your local network. The default is to accept all connections.
      --p2p-external-hostname string    The DNS hostname advertised by libp2p. This may be used to advertise an external DNS.
      --p2p-external-ip string          The IP address advertised by libp2p. This may be used to advertise an external IP.
      --p2p-tcp-address strings         Comma-separated list of listening TCP addresses (ip and port) for libP2P traffic. (default [127.0.0.1:3610])
      --p2p-udp-address string          Listening UDP address (ip and port) for discv5 discovery. (default "127.0.0.1:3630")
      --simnet-beacon-mock              Enables an internal mock beacon node for running a simnet.
      --simnet-validator-mock           Enables an internal mock validator client when running a simnet. Requires simnet-beacon-mock.
      --validator-api-address string    Listening address (ip and port) for validator-facing traffic proxying the beacon-node API. (default "127.0.0.1:3600")