diff --git a/docs/charon/charon-cli-reference.md b/docs/charon/charon-cli-reference.md index 0527154974..e379a64925 100644 --- a/docs/charon/charon-cli-reference.md +++ b/docs/charon/charon-cli-reference.md @@ -358,4 +358,125 @@ Flags: --p2p-relays strings Comma-separated list of libp2p relay URLs or multiaddrs. (default [https://0.relay.obol.tech]) --p2p-tcp-address strings Comma-separated list of listening TCP addresses (ip and port) for libP2P traffic. Empty default doesn't bind to local port therefore only supports outgoing connections. ``` -You can also consider adding [alternative public relays](../faq/risks.md) to your cluster by specifying a list of `p2p-relays` in [`charon run`](#run-the-charon-middleware). \ No newline at end of file +You can also consider adding [alternative public relays](../faq/risks.md) to your cluster by specifying a list of `p2p-relays` in [`charon run`](#run-the-charon-middleware). + +## The `exit` subcommand + +The `exit` subcommands allows users to exit a validator currently existing in a Charon cluster. + +Considering the distributed nature of a Charon cluster, the `exit` commands enable users to submit their partially signed exit messages to a remote API, which will hold it for them until there are enough to be successfully aggregated in a fully signed exit message. + +Operators can then use the `exit` subcommand to fetch and broadcast the fully signed exit message to their Beacon Node. + +To facilitate custom deployments, the `exit` subcommands allow listing all the active validators contained in a cluster, as well as broadcasting pre-signed exit messages from a file. + +All of the commands require a valid lock file and `charon-enr-private-key` to authenticate requests to the remote API. + +In order to exit a validator, an operator needs to: + - run `charon exit sign`, which will sign a partial exit with the appropriate validator partial key, then store it in the remote API endpoint + - encourage at least `threshold-1` operators to do the same + - run `charon exit broadcast` to fetch and broadcast the full validator exit to the configured Beacon node. + +```markdown +Sign and broadcast distributed validator exit messages using a remote API. + +Usage: + charon exit [command] + +Available Commands: + active-validator-list List all active validators + broadcast Submit partial exit message for a distributed validator + fetch Fetch a signed exit message from the remote API + sign Sign partial exit message for a distributed validator + +Flags: + -h, --help Help for exit + +Use "charon exit [command] --help" for more information about a command. +``` + +### `exit active-validator-list` + +```markdown +Returns a list of all the DV in the specified cluster whose status is ACTIVE_ONGOING, i.e. can be exited. + +Usage: + charon exit active-validator-list [flags] + +Flags: + --beacon-node-url string Beacon node URL. + -h, --help Help for active-validator-list + --lock-file string The path to the cluster lock file defining the distributed validator cluster. (default ".charon/cluster-lock.json") + --log-color string Log color; auto, force, disable. (default "auto") + --log-format string Log format; console, logfmt or json (default "console") + --log-level string Log level; debug, info, warn or error (default "info") + --log-output-path string Path in which to write on-disk logs. + --plaintext Prints each active validator on a line, without any debugging or logging artifact. Useful for scripting. +``` + +### `exit broadcast` + +```markdown +Retrieves and broadcasts a fully signed validator exit message, aggregated with the available partial signatures retrieved from the publish-address. + +Usage: + charon exit broadcast [flags] + +Flags: + --beacon-node-url string Beacon node URL. + --exit-epoch uint Exit epoch at which the validator will exit, must be the same across all the partial exits. (default 162304) + --exit-from-file string Retrieves a signed exit message from a pre-prepared file instead of --publish-address. + -h, --help Help for broadcast + --lock-file string The path to the cluster lock file defining the distributed validator cluster. (default ".charon/cluster-lock.json") + --log-color string Log color; auto, force, disable. (default "auto") + --log-format string Log format; console, logfmt or json (default "console") + --log-level string Log level; debug, info, warn or error (default "info") + --log-output-path string Path in which to write on-disk logs. + --private-key-file string The path to the charon enr private key file. (default ".charon/charon-enr-private-key") + --publish-address string The URL of the remote API. (default "https://api.obol.tech") + --validator-keys-dir string Path to the directory containing the validator private key share files and passwords. (default ".charon/validator_keys") + --validator-public-key string Public key of the validator to exit, must be present in the cluster lock manifest. +``` + +### `exit sign` + +```markdown +Sign a partial exit message for a distributed validator and submit it to a remote API for aggregation. + +Usage: + charon exit sign [flags] + +Flags: + --beacon-node-url string Beacon node URL. + --exit-epoch uint Exit epoch at which the validator will exit, must be the same across all the partial exits. (default 162304) + -h, --help Help for sign + --lock-file string The path to the cluster lock file defining the distributed validator cluster. (default ".charon/cluster-lock.json") + --log-color string Log color; auto, force, disable. (default "auto") + --log-format string Log format; console, logfmt or json (default "console") + --log-level string Log level; debug, info, warn or error (default "info") + --log-output-path string Path in which to write on-disk logs. + --private-key-file string The path to the charon enr private key file. (default ".charon/charon-enr-private-key") + --publish-address string The URL of the remote API. (default "https://api.obol.tech") + --validator-keys-dir string Path to the directory containing the validator private key share files and passwords. (default ".charon/validator_keys") + --validator-public-key string Public key of the validator to exit, must be present in the cluster lock manifest. +``` + +### `exit fetch` + +```markdown +Fetches a fully signed exit message for a given validator from the remote API. + +Usage: + charon exit fetch [flags] + +Flags: + -h, --help Help for fetch + --lock-file string The path to the cluster lock file defining the distributed validator cluster. (default ".charon/cluster-lock.json") + --log-color string Log color; auto, force, disable. (default "auto") + --log-format string Log format; console, logfmt or json (default "console") + --log-level string Log level; debug, info, warn or error (default "info") + --log-output-path string Path in which to write on-disk logs. + --private-key-file string The path to the charon enr private key file. (default ".charon/charon-enr-private-key") + --publish-address string The URL of the remote API. (default "https://api.obol.tech") + --validator-public-key string Public key of the validator to exit, must be present in the cluster lock manifest. +``` \ No newline at end of file