From 1eed42d382968d32aa8c8e397bc6bb5c18eb940e Mon Sep 17 00:00:00 2001 From: Andrei Smirnov Date: Thu, 16 Oct 2025 08:15:04 +0300 Subject: [PATCH] edit commands --- CLAUDE.md | 26 ++- SUMMARY.md | 3 + .../advanced/add-operators.md | 92 +++++++++++ .../advanced/add-validators.md | 18 +- .../advanced/recreate-private-keys.md | 123 ++++++++++++++ .../advanced/remove-operators.md | 130 +++++++++++++++ learn/charon/charon-cli-reference.md | 154 +++++++++++++++++- 7 files changed, 525 insertions(+), 21 deletions(-) create mode 100644 advanced-and-troubleshooting/advanced/add-operators.md create mode 100644 advanced-and-troubleshooting/advanced/recreate-private-keys.md create mode 100644 advanced-and-troubleshooting/advanced/remove-operators.md diff --git a/CLAUDE.md b/CLAUDE.md index 9ebcf2a..096fe80 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -41,22 +41,33 @@ The repository contains two parallel directory structures: - **Active/Active Redundancy** - Multiple nodes can go offline while validator remains operational - **Non-custodial Architecture** - Private keys are never reconstructed in full +### Cluster Modification Commands +- **`charon alpha edit` commands** - Modify existing distributed validator cluster configurations + - `charon alpha edit add-validators` - Generate and add new validators to existing cluster + - `charon alpha edit add-operators` - Add new operators whilst keeping validator public keys unchanged + - `charon alpha edit remove-operators` - Remove operators whilst leaving all validators intact + - `charon alpha edit recreate-private-keys` - Create new private key shares whilst retaining operator identities and validator public keys +- **Ceremony Coordination** - Most edit commands require threshold or all operators to participate +- **Experimental Status** - These features should not be used in production (Mainnet) yet + ### Testing & Validation -- **`charon test` commands** - Comprehensive testing suite for cluster health - - `charon test beacon` - Test beacon node connectivity and performance - - `charon test validator` - Test validator client connectivity - - `charon test peers` - Test peer-to-peer connectivity within cluster - - `charon test infra` - Test infrastructure (disk, memory, network) +- **`charon alpha test` commands** - Comprehensive testing suite for cluster health + - `charon alpha test beacon` - Test beacon node connectivity and performance + - `charon alpha test validator` - Test validator client connectivity + - `charon alpha test peers` - Test peer-to-peer connectivity within cluster + - `charon alpha test infra` - Test infrastructure (disk, memory, network) - Add `--load-test` flag for performance testing ## Content Guidelines ### Documentation Standards +- Use British English variant (e.g., "whilst", "recognise", "optimise") throughout all documentation - Use clear, technical language appropriate for both developers and stakers - Include troubleshooting sections with specific error conditions and resolutions - Provide hardware/infrastructure requirements where applicable - Reference external tools and clients with proper links - Include security warnings for sensitive operations (private keys, production environments) +- Use GitBook-specific syntax (e.g., `{% hint style="warning" %}`, `{% hint style="info" %}`, `{% hint style="danger" %}`) ### File Organization - Keep related content together (e.g., all quickstart guides in `run-a-dv/start/`) @@ -84,7 +95,8 @@ The repository contains two parallel directory structures: - Ensure image references point to correct `.gitbook/assets/` paths ### Technical Accuracy -- Validate CLI command examples against latest Charon releases +- Validate CLI command examples against latest Charon releases (run `charon [command] --help` to get current flags and usage) - Verify threshold mathematics in cluster configuration tables - Cross-check API documentation with actual API specifications -- Ensure hardware requirements reflect current recommendations \ No newline at end of file +- Ensure hardware requirements reflect current recommendations +- Update internal documentation links to use relative paths with proper anchor links (e.g., `../../learn/charon/charon-cli-reference.md#section-name`) diff --git a/SUMMARY.md b/SUMMARY.md index eeac662..ef15ab5 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -55,6 +55,9 @@ * [Advanced Docker Configs](advanced-and-troubleshooting/advanced/adv-docker-configs.md) * [Beacon node authentication](advanced-and-troubleshooting/advanced/beacon-node-authentication.md) * [Adding Validators](advanced-and-troubleshooting/advanced/add-validators.md) + * [Adding Operators](advanced-and-troubleshooting/advanced/add-operators.md) + * [Removing Operators](advanced-and-troubleshooting/advanced/remove-operators.md) + * [Recreating Private Keys](advanced-and-troubleshooting/advanced/recreate-private-keys.md) * [Custom Graffiti](advanced-and-troubleshooting/advanced/custom-graffiti.md) * [Enable TLS Protocol](advanced-and-troubleshooting/advanced/enable-tls-protocol.md) * [Fallback Beacon Nodes](advanced-and-troubleshooting/advanced/fallback-beacon-nodes.md) diff --git a/advanced-and-troubleshooting/advanced/add-operators.md b/advanced-and-troubleshooting/advanced/add-operators.md new file mode 100644 index 0000000..83d964c --- /dev/null +++ b/advanced-and-troubleshooting/advanced/add-operators.md @@ -0,0 +1,92 @@ +--- +description: >- + Add operators to your existing distributed validator cluster using the charon alpha edit add-operators command. +--- + +# Adding Operators + +{% hint style="warning" %} +This is an experimental feature and should not be used in production (Mainnet) yet. +{% endhint %} + +You can add operators to your cluster using the `charon alpha edit add-operators` command. This operation keeps all validator public keys unchanged whilst adding new operators to the cluster. + +## Prerequisites + +1. Review the `edit add-operators` command [CLI reference](../../learn/charon/charon-cli-reference.md#add-operators-to-a-cluster). +2. **For existing operators**: Keep the DV node running during the process and ensure you have a copy of the current cluster lock file and validator private key shares. +3. **For new operators**: Obtain a copy of the existing cluster lock file from the existing operators and have your Charon ENR private key file ready. +4. Obtain the Charon ENR addresses of all new operators being added to the cluster. + +{% hint style="info" %} +The ceremony uses a different p2p relay from your running cluster to avoid conflicts. The default relay address is already configured differently, so no special action is required. +{% endhint %} + +## Adding Operators Process + +The examples below demonstrate adding new operators to an existing cluster. All existing operators must run this command, along with the new operators being added. + +### For Existing Operators + +```bash +# If you prefer running a pre-built charon binary +charon alpha edit add-operators --new-operator-enrs=enr:-JG4QH... --output-dir=output + +# Or, if you prefer running it in Docker +# (replace 'latest' with the most recent version if needed: https://hub.docker.com/r/obolnetwork/charon/tags) +docker run --rm -v "$(pwd):/opt/charon" obolnetwork/charon:latest alpha edit add-operators --new-operator-enrs=enr:-JG4QH... --private-key-file=/opt/charon/.charon/charon-enr-private-key --lock-file=/opt/charon/.charon/cluster-lock.json --validator-keys-dir=/opt/charon/.charon/validator_keys --output-dir=/opt/charon/output +``` + +### For New Operators + +New operators being added should run the same command but only need to provide their private key file and the cluster lock file (they won't have validator keys yet): + +```bash +# If you prefer running a pre-built charon binary +charon alpha edit add-operators --new-operator-enrs=enr:-JG4QH... --output-dir=output --lock-file=cluster-lock.json --private-key-file=charon-enr-private-key + +# Or, if you prefer running it in Docker +docker run --rm -v "$(pwd):/opt/charon" obolnetwork/charon:latest alpha edit add-operators --new-operator-enrs=enr:-JG4QH... --private-key-file=/opt/charon/charon-enr-private-key --lock-file=/opt/charon/cluster-lock.json --output-dir=/opt/charon/output +``` + +{% hint style="info" %} +To add multiple operators at once, provide a comma-separated list: `--new-operator-enrs=enr:-JG4QH...,enr:-JG4QK...,enr:-JG4QL...` +{% endhint %} + +This command will create a new cluster configuration with the additional operators whilst keeping all validator public keys unchanged. The new configuration will be saved in the `output` directory. + +## Making the DV Stack Use the New Configuration + +The example below is designed for the [CDVN repository](https://github.com/ObolNetwork/charon-distributed-validator-node), but the process is similar for other setups. + +1. To start using the new configuration (with the added operators), stop the current Charon and validator client instances: + +```bash +docker compose stop charon lodestar +``` + +2. Back up and remove the existing `.charon` directory, then move the `output` directory to `.charon`: + +```bash +mv .charon .charon-backup +mv output .charon +``` + +3. Restart the Charon and validator client instances: + +```bash +docker compose up -d charon lodestar +``` + +Lodestar's boot script (`lodestar/run.sh`) will automatically import all keys, removing any existing keys and cache. Charon will load the new `cluster-lock.json` and recognise all validators in the cluster with the updated operator set. + +{% hint style="warning" %} +All existing operators must fully shut down their cluster nodes before starting with the new configuration. The old cluster must be completely stopped before the new cluster with the expanded operator set can begin operating. Unlike add-validators, this is not a gradual migration. +{% endhint %} + +## Current Limitations + +- The new cluster configuration will not be reflected on the Launchpad. +- The new cluster configuration will have a new cluster hash, so the observability stack will display new cluster data under a different identifier. +- All operators (both existing and new) must participate in the add-operators ceremony for it to complete successfully. +- The cluster's threshold value remains unchanged after adding operators because the existing set of operators already possesses enough shares to create full signatures. diff --git a/advanced-and-troubleshooting/advanced/add-validators.md b/advanced-and-troubleshooting/advanced/add-validators.md index 5008aa2..b744e04 100644 --- a/advanced-and-troubleshooting/advanced/add-validators.md +++ b/advanced-and-troubleshooting/advanced/add-validators.md @@ -1,6 +1,6 @@ --- description: >- - Add validators to your existing distributed validator cluster using the charon alpha add-validators command. + Add validators to your existing distributed validator cluster using the charon alpha edit add-validators command. --- # Adding Validators @@ -9,12 +9,16 @@ description: >- This is an experimental feature available starting with Charon v1.6 and should not be used in production (Mainnet) yet. {% endhint %} -You can add validators to your cluster using the `charon alpha add-validators` command. The example below is designed for the default configuration provided by this repository and assumes that the stack uses the Lodestar validator client. +You can add validators to your cluster using the `charon alpha edit add-validators` command. The example below is designed for the default configuration provided by this repository and assumes that the stack uses the Lodestar validator client. ## Prerequisites -1. Review the `add-validators` command [CLI reference](https://docs.obol.org/docs/learn/charon/charon-cli-reference). -2. Ensure this folder contains a valid `.charon` directory currently used by the running node. Keep the DV node running during the process. +1. Review the `edit add-validators` command [CLI reference](../../learn/charon/charon-cli-reference.md#add-validators-to-a-cluster). +2. Keep the DV node running during the process and ensure you have a copy of the current cluster lock file and validator private key shares (or use `--unverified` if validator keys are not accessible). + +{% hint style="info" %} +The ceremony uses a different p2p relay from your running cluster to avoid conflicts. The default relay address is already configured differently, so no special action is required. +{% endhint %} ## Adding Validators Process @@ -22,11 +26,11 @@ The examples below are for adding 10 validators. You can use them with any numbe ```bash # If you prefer running a pre-built charon binary -charon alpha add-validators --num-validators 10 --withdrawal-addresses=0x --fee-recipient-addresses=0x --output-dir=output +charon alpha edit add-validators --num-validators 10 --withdrawal-addresses=0x --fee-recipient-addresses=0x --output-dir=output # Or, if you prefer running it in Docker # (replace 'latest' with the most recent version if needed: https://hub.docker.com/r/obolnetwork/charon/tags) -docker run --rm -v "$(pwd):/opt/charon" obolnetwork/charon:latest alpha add-validators --num-validators 10 --withdrawal-addresses=0x --fee-recipient-addresses=0x --data-dir=/opt/charon/.charon --output-dir=/opt/charon/output +docker run --rm -v "$(pwd):/opt/charon" obolnetwork/charon:latest alpha edit add-validators --num-validators 10 --withdrawal-addresses=0x --fee-recipient-addresses=0x --private-key-file=/opt/charon/.charon/charon-enr-private-key --lock-file=/opt/charon/.charon/cluster-lock.json --validator-keys-dir=/opt/charon/.charon/validator_keys --output-dir=/opt/charon/output ``` This command will create a new cluster configuration that includes both existing and new validators. It will also generate the necessary keys for the new validators and deposit data files. The new configuration will be saved in the `output` directory. @@ -64,5 +68,5 @@ Steps 1–3 must be performed independently by all node operators, likely at dif - The new cluster configuration will not be reflected on the Launchpad. - The new cluster configuration will have a new cluster hash, so the observability stack will display new cluster data under a different identifier. -- The `add-validators` command supports the KeyManager API (similar to the `dkg` command), but since it may not have direct access to the original private keys if they're not still in the `.charon` folder you are adding validators to, it cannot produce valid cluster lock signatures. In this case, you must use the `--unverified` flag, which means Charon does not hash and sign the new cluster lock file with all the private keys to prove their existence. This requires adding the `--no-verify` flag or `CHARON_NO_VERIFY=true` environment variable to the `charon run` command/container. +- If Charon has no access to the existing validator keys (for example, if they're stored in a remote KeyManager), you must use the `--unverified` flag. This flag allows the addition to proceed but skips hashing and signing the new cluster lock data. When using this flag, you must start `charon run` with the `--no-verify` flag or set the `CHARON_NO_VERIFY=true` environment variable. - If you use different validator clients, review the keys import script. The old keys in `.charon/validator_keys` remain unchanged, so verify that importing the same keys will not disrupt the validator client's state. diff --git a/advanced-and-troubleshooting/advanced/recreate-private-keys.md b/advanced-and-troubleshooting/advanced/recreate-private-keys.md new file mode 100644 index 0000000..375d6c0 --- /dev/null +++ b/advanced-and-troubleshooting/advanced/recreate-private-keys.md @@ -0,0 +1,123 @@ +--- +description: >- + Create new private key shares for your existing distributed validator cluster using the charon alpha edit recreate-private-keys command. +--- + +# Recreating Private Keys + +{% hint style="warning" %} +This is an experimental feature and should not be used in production (Mainnet) yet. +{% endhint %} + +You can recreate the private key shares for your cluster using the `charon alpha edit recreate-private-keys` command. This operation creates new private key shares to replace the existing validator private keys whilst retaining the same operator identities and validator public keys. + +## When to Use This Feature + +You might need to recreate private key shares in several scenarios: + +- **Security concerns**: If you suspect that private key shares may have been compromised +- **Key rotation**: As part of regular security practices to rotate cryptographic material +- **Recovery**: After a security incident where you want to refresh all key material +- **Compliance**: Meeting organisational policies that require periodic key rotation + +{% hint style="info" %} +This operation maintains the same validator public keys, so your validators remain registered on the beacon chain without any changes. Only the underlying private key shares held by operators are refreshed. +{% endhint %} + +## Prerequisites + +1. Review the `edit recreate-private-keys` command [CLI reference](../../learn/charon/charon-cli-reference.md#recreate-private-key-shares). +2. Keep the DV node running during the process and ensure you have a copy of the current cluster lock file and validator private key shares. +3. All operators in the cluster must participate in this ceremony. +4. Each operator must have their current validator private key shares available. + +{% hint style="info" %} +The ceremony uses a different p2p relay from your running cluster to avoid conflicts. The default relay address is already configured differently, so no special action is required. +{% endhint %} + +## Recreating Private Keys Process + +All operators must run this command simultaneously. The ceremony will coordinate between all operators to generate new private key shares. + +```bash +# If you prefer running a pre-built charon binary +charon alpha edit recreate-private-keys --output-dir=output + +# Or, if you prefer running it in Docker +# (replace 'latest' with the most recent version if needed: https://hub.docker.com/r/obolnetwork/charon/tags) +docker run --rm -v "$(pwd):/opt/charon" obolnetwork/charon:latest alpha edit recreate-private-keys --private-key-file=/opt/charon/.charon/charon-enr-private-key --lock-file=/opt/charon/.charon/cluster-lock.json --validator-keys-dir=/opt/charon/.charon/validator_keys --output-dir=/opt/charon/output +``` + +This command will: +1. Use the existing cluster configuration and operator identities +2. Generate new private key shares for all validators +3. Create a new cluster lock file with updated key shares +4. Save the new configuration in the `output` directory + +{% hint style="info" %} +The ceremony requires all operators to participate. If any operator is unavailable, the ceremony cannot complete. +{% endhint %} + +## Making the DV Stack Use the New Keys + +The example below is designed for the [CDVN repository](https://github.com/ObolNetwork/charon-distributed-validator-node), but the process is similar for other setups. + +{% hint style="danger" %} +**Critical Security Step**: All operators must coordinate to switch to the new keys at approximately the same time to avoid validation failures. Plan a maintenance window and communicate clearly with all operators. +{% endhint %} + +1. To start using the new keys, stop the current Charon and validator client instances: + +```bash +docker compose stop charon lodestar +``` + +2. Back up and remove the existing `.charon` directory, then move the `output` directory to `.charon`: + +```bash +mv .charon .charon-backup +mv output .charon +``` + +3. Restart the Charon and validator client instances: + +```bash +docker compose up -d charon lodestar +``` + +Lodestar's boot script (`lodestar/run.sh`) will automatically import all keys, removing any existing keys and cache. Charon will load the new `cluster-lock.json` with the recreated private key shares. + +{% hint style="warning" %} +All operators must fully shut down their existing cluster nodes before starting with the new configuration. The old cluster must be completely stopped before the new cluster with the recreated private keys can begin operating. Steps 1–3 must be performed by all node operators within a coordinated maintenance window to minimise downtime. +{% endhint %} + +## Verifying the New Configuration + +After all operators have restarted with the new keys, verify that: + +1. All Charon nodes are connected and healthy +2. The cluster is successfully producing attestations +3. No error messages appear in the logs related to signature verification + +```bash +# Check Charon logs +docker compose logs -f charon + +# Verify cluster health in the monitoring dashboard +# Check that all validators are attesting normally +``` + +## Security Best Practices + +- **Secure deletion**: After successfully transitioning to the new keys and verifying operation, securely delete the old key shares +- **Coordination**: Ensure all operators are prepared and available during the planned maintenance window +- **Communication**: Maintain clear communication channels between all operators throughout the process +- **Backup**: Keep the backup until you've verified that the cluster is operating normally with the new keys for at least several epochs + +## Current Limitations + +- The new cluster configuration will not be reflected on the Launchpad. +- The new cluster configuration will have a new cluster hash, so the observability stack will display new cluster data under a different identifier. +- All operators must participate in the ceremony; there is no option for partial participation. +- All operators must have their current validator private key shares available for the ceremony to succeed. +- The transition period requires coordination to minimise validator downtime. diff --git a/advanced-and-troubleshooting/advanced/remove-operators.md b/advanced-and-troubleshooting/advanced/remove-operators.md new file mode 100644 index 0000000..c561aad --- /dev/null +++ b/advanced-and-troubleshooting/advanced/remove-operators.md @@ -0,0 +1,130 @@ +--- +description: >- + Remove operators from your existing distributed validator cluster using the charon alpha edit remove-operators command. +--- + +# Removing Operators + +{% hint style="warning" %} +This is an experimental feature and should not be used in production (Mainnet) yet. +{% endhint %} + +You can remove operators from your cluster using the `charon alpha edit remove-operators` command. This operation leaves all validators intact whilst removing specified operators from the cluster. + +## Prerequisites + +1. Review the `edit remove-operators` command [CLI reference](../../learn/charon/charon-cli-reference.md#remove-operators-from-a-cluster). +2. **For remaining operators**: Keep the DV node running during the process and ensure you have a copy of the current cluster lock file and validator private key shares. +3. **For operators being removed**: A copy of the cluster lock file is required to participate in the ceremony (if participating). +4. Identify the Charon ENR addresses of the operators you wish to remove from the cluster. + +{% hint style="info" %} +The ceremony uses a different p2p relay from your running cluster to avoid conflicts. The default relay address is already configured differently, so no special action is required. +{% endhint %} + +## Understanding Fault Tolerance + +Before removing operators, it's crucial to understand your cluster's fault tolerance: + +- **Fault tolerance (f)** = `number of operators - threshold` +- If you're removing **more operators than the fault tolerance**, you must use the `--participating-operator-enrs` flag to specify which operators will participate in the ceremony. + +For example, if your cluster has 4 operators with a threshold of 3 (f=1), removing 2 operators requires specifying at least 3 participating operators. + +## Removing Operators Process + +### Standard Removal (Within Fault Tolerance) + +If you're removing operators within the fault tolerance, all remaining operators can participate automatically: + +```bash +# For remaining operators +charon alpha edit remove-operators --operator-enrs-to-remove=enr:-JG4QH... --output-dir=output + +# Docker version +docker run --rm -v "$(pwd):/opt/charon" obolnetwork/charon:latest alpha edit remove-operators --operator-enrs-to-remove=enr:-JG4QH... --private-key-file=/opt/charon/.charon/charon-enr-private-key --lock-file=/opt/charon/.charon/cluster-lock.json --validator-keys-dir=/opt/charon/.charon/validator_keys --output-dir=/opt/charon/output +``` + +### Advanced Removal (Exceeding Fault Tolerance) + +If you're removing more operators than the fault tolerance allows, you must specify participating operators: + +```bash +# For participating operators (both remaining and being removed) +charon alpha edit remove-operators --operator-enrs-to-remove=enr:-JG4QH...,enr:-JG4QK... --participating-operator-enrs=enr:-JG4QL...,enr:-JG4QM...,enr:-JG4QN... --output-dir=output + +# Docker version +docker run --rm -v "$(pwd):/opt/charon" obolnetwork/charon:latest alpha edit remove-operators --operator-enrs-to-remove=enr:-JG4QH...,enr:-JG4QK... --participating-operator-enrs=enr:-JG4QL...,enr:-JG4QM...,enr:-JG4QN... --private-key-file=/opt/charon/.charon/charon-enr-private-key --lock-file=/opt/charon/.charon/cluster-lock.json --validator-keys-dir=/opt/charon/.charon/validator_keys --output-dir=/opt/charon/output +``` + +{% hint style="info" %} +When using `--participating-operator-enrs`, you must have at least `threshold` number of operators participating. Operators being removed can participate if explicitly included in this list. +{% endhint %} + +### For Operators Being Removed + +Operators being removed have two options: + +1. **If participating** (when explicitly included in `--participating-operator-enrs`): Run the same command as other participants with the `--output-dir` flag +2. **If not participating**: Do not run the command at all; simply ignore the ceremony + +```bash +# For removed operators who are participating in the ceremony +charon alpha edit remove-operators --operator-enrs-to-remove=enr:-JG4QH... --participating-operator-enrs=enr:-JG4QH...,enr:-JG4QK...,enr:-JG4QL... --private-key-file=.charon/charon-enr-private-key --lock-file=.charon/cluster-lock.json --validator-keys-dir=.charon/validator_keys --output-dir=output +``` + +## Customising the Threshold + +By default, the new threshold is calculated as `ceil(n * 2 / 3)`, where `n` is the new number of operators. You can override this with the `--new-threshold` flag: + +```bash +charon alpha edit remove-operators --operator-enrs-to-remove=enr:-JG4QH... --new-threshold=3 --output-dir=output +``` + +{% hint style="danger" %} +Using a non-default threshold value decreases security. All operators must use the same value. Only override this if you fully understand the implications. +{% endhint %} + +## Making the DV Stack Use the New Configuration + +The example below is designed for the [CDVN repository](https://github.com/ObolNetwork/charon-distributed-validator-node), but the process is similar for other setups. + +### For Remaining Operators + +1. Stop the current Charon and validator client instances: + +```bash +docker compose stop charon lodestar +``` + +2. Back up and remove the existing `.charon` directory, then move the `output` directory to `.charon`: + +```bash +mv .charon .charon-backup +mv output .charon +``` + +3. Restart the Charon and validator client instances: + +```bash +docker compose up -d charon lodestar +``` + +{% hint style="warning" %} +All remaining operators must fully shut down their existing cluster nodes before starting with the new configuration. The old cluster must be completely stopped before the new cluster with the reduced operator set can begin operating. +{% endhint %} + +### For Removed Operators + +Operators who have been removed can safely shut down their nodes after the ceremony completes: + +```bash +docker compose down +``` + +## Current Limitations + +- The new cluster configuration will not be reflected on the Launchpad. +- The new cluster configuration will have a new cluster hash, so the observability stack will display new cluster data under a different identifier. +- All remaining operators must have valid validator keys to participate in the removal ceremony. +- When removing more operators than the fault tolerance, at least `threshold` operators must participate in the ceremony. diff --git a/learn/charon/charon-cli-reference.md b/learn/charon/charon-cli-reference.md index 2752946..daced55 100644 --- a/learn/charon/charon-cli-reference.md +++ b/learn/charon/charon-cli-reference.md @@ -576,28 +576,51 @@ You can also consider adding [alternative public relays](../../advanced-and-trou These commands are subject to breaking changes until they are moved outside of the `alpha` subcommand in a future release. -### Generate and add new validators to a cluster +### Edit cluster configuration -The `charon alpha 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. +The `charon alpha edit` commands allow you to modify existing distributed validator cluster configurations. + +```markdown +charon alpha edit --help +Subcommands allow users to modify existing distributed validator cluster configurations, such as adding and removing operators. + +Usage: + charon alpha edit [command] + +Available Commands: + add-operators Add new operators to an existing distributed validator cluster + add-validators Add new validators to an existing distributed validator cluster + recreate-private-keys Create new private key shares to replace existing validator private key shares + remove-operators Remove operators from an existing distributed validator cluster + +Flags: + -h, --help Help for edit + +Use "charon alpha edit [command] --help" for more information about a command. +``` + +#### 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. {% hint style="warning" %} It is not yet recommended to use this command for Mainnet clusters. {% endhint %} ```markdown -charon alpha add-validators --help +charon alpha edit add-validators --help Generates and appends new validator keys to an existing distributed validator cluster. Usage: - charon alpha add-validators [flags] + charon alpha edit add-validators [flags] Flags: - --data-dir string The source charon folder with existing cluster data (lock, validator_keys, etc.). (default ".charon") - --execution-client-rpc-endpoint string The address of the execution engine JSON-RPC API. + --execution-client-rpc-endpoint string Optional address of an execution engine JSON-RPC API. Used to validate smart contract signatures for Node Operators in the cluster. --fee-recipient-addresses strings Comma separated list of Ethereum addresses of the fee recipient for each validator. Either provide a single fee recipient address or fee recipient addresses for each validator. -h, --help Help for add-validators --keymanager-address string The keymanager URL to import validator keyshares. --keymanager-auth-token string Authentication bearer token to interact with keymanager API. Don't include the "Bearer" symbol, only include the api-token. + --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") @@ -608,15 +631,132 @@ Flags: --p2p-disable-reuseport Disables TCP port reuse for outgoing libp2p 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-relays strings Comma-separated list of libp2p relay URLs or multiaddrs. (default [https://0.relay.obol.tech,https://2.relay.obol.dev,https://1.relay.obol.tech]) + --p2p-relays strings Comma-separated list of libp2p relay URLs or multiaddrs. (default [https://0.relay.obol.tech,https://1.relay.obol.tech,https://2.relay.obol.dev]) --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. --p2p-udp-address strings Comma-separated list of listening UDP addresses (ip and port) for libP2P traffic. Empty default doesn't bind to local port therefore only supports outgoing connections. + --private-key-file string The path to the charon enr private key file. (default ".charon/charon-enr-private-key") --shutdown-delay duration Graceful shutdown delay. (default 1s) --timeout duration Timeout for the command, should be increased if the command times out. (default 1m0s) --unverified If charon has no access to the existing validator keys, this flag allows the addition to proceed, but skips hashing and signing the new cluster lock data. charon run must be started with --no-verify flag. + --validator-keys-dir string Path to the directory containing the validator private key share files and passwords. (default ".charon/validator_keys") --withdrawal-addresses strings Comma separated list of Ethereum addresses to receive the returned stake and accrued rewards for each validator. Either provide a single withdrawal address or withdrawal addresses for each validator. ``` +#### 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. + +{% hint style="warning" %} +This is an experimental feature and should not be used in production (Mainnet) yet. +{% endhint %} + +```markdown +charon alpha edit add-operators --help +Adds new operators to an existing distributed validator cluster, keeping validator public keys unchanged. + +Usage: + charon alpha edit add-operators [flags] + +Flags: + --execution-client-rpc-endpoint string Optional address of an execution engine JSON-RPC API. Used to validate smart contract signatures for Node Operators in the cluster. + -h, --help Help for add-operators + --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. + --new-operator-enrs strings Comma-separated list of the new operators to be added (Charon ENR addresses). + --no-verify Disables cluster definition and lock file verification. + --output-dir string The destination folder for the new cluster data. Must be empty. (default "distributed_validator") + --p2p-disable-reuseport Disables TCP port reuse for outgoing libp2p 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-relays strings Comma-separated list of libp2p relay URLs or multiaddrs. (default [https://4.relay.obol.dev]) + --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. + --p2p-udp-address strings Comma-separated list of listening UDP addresses (ip and port) for libP2P traffic. Empty default doesn't bind to local port therefore only supports outgoing connections. + --private-key-file string The path to the charon enr private key file. (default ".charon/charon-enr-private-key") + --shutdown-delay duration Graceful shutdown delay. (default 1s) + --timeout duration Timeout for the protocol, should be increased if protocol times out. (default 1m0s) + --validator-keys-dir string Path to the directory containing the validator private key share files and passwords. (default ".charon/validator_keys") +``` + +#### 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. + +{% hint style="warning" %} +This is an experimental feature and should not be used in production (Mainnet) yet. +{% endhint %} + +```markdown +charon alpha edit remove-operators --help +Removes operators from an existing distributed validator cluster, leaving all validators intact. + +Usage: + charon alpha edit remove-operators [flags] + +Flags: + --execution-client-rpc-endpoint string Optional address of an execution engine JSON-RPC API. Used to validate smart contract signatures for Node Operators in the cluster. + -h, --help Help for remove-operators + --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. + --new-threshold int Optional override of the new threshold required for signature reconstruction. Defaults to ceil(n*2/3) if zero. Warning, non-default values decrease security. All operators must use the same value. + --no-verify Disables cluster definition and lock file verification. + --operator-enrs-to-remove strings Comma-separated list of operators to be removed (Charon ENR addresses). + --output-dir string The destination folder for the new cluster data. Must be empty. Optional for removed operators. (default "distributed_validator") + --p2p-disable-reuseport Disables TCP port reuse for outgoing libp2p 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-relays strings Comma-separated list of libp2p relay URLs or multiaddrs. (default [https://4.relay.obol.dev]) + --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. + --p2p-udp-address strings Comma-separated list of listening UDP addresses (ip and port) for libP2P traffic. Empty default doesn't bind to local port therefore only supports outgoing connections. + --participating-operator-enrs strings Comma-separated list of operator ENRs participating in the ceremony. Required if --operator-enrs-to-remove specifies more operators to remove than the fault tolerance of the current cluster. + --private-key-file string The path to the charon enr private key file. (default ".charon/charon-enr-private-key") + --shutdown-delay duration Graceful shutdown delay. (default 1s) + --timeout duration Timeout for the protocol, should be increased if protocol times out. (default 1m0s) + --validator-keys-dir string Path to the directory containing the validator private key share files and passwords. (default ".charon/validator_keys") +``` + +#### 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. + +{% hint style="warning" %} +This is an experimental feature and should not be used in production (Mainnet) yet. +{% endhint %} + +```markdown +charon alpha edit recreate-private-keys --help +Creates new private key shares to replace the existing validator private keys while retaining the same operator identities. + +Usage: + charon alpha edit recreate-private-keys [flags] + +Flags: + --execution-client-rpc-endpoint string Optional address of an execution engine JSON-RPC API. Used to validate smart contract signatures for Node Operators in the cluster. + -h, --help Help for recreate-private-keys + --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. + --no-verify Disables cluster definition and lock file verification. + --output-dir string The destination folder for the new cluster artifacts. Must be empty. (default "distributed_validator") + --p2p-disable-reuseport Disables TCP port reuse for outgoing libp2p 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-relays strings Comma-separated list of libp2p relay URLs or multiaddrs. (default [https://4.relay.obol.dev]) + --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. + --p2p-udp-address strings Comma-separated list of listening UDP addresses (ip and port) for libP2P traffic. Empty default doesn't bind to local port therefore only supports outgoing connections. + --private-key-file string The path to the charon enr private key file. (default ".charon/charon-enr-private-key") + --shutdown-delay duration Graceful shutdown delay. (default 1s) + --timeout duration Timeout for the protocol, should be increased if protocol times out. (default 1m0s) + --validator-keys-dir string Path to the directory containing the validator private key share files and passwords. (default ".charon/validator_keys") +``` + ### Test your candidate distributed validator cluster Charon comes with a test suite for understanding the suitability and readiness of a given setup.