edit commands

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
+- 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`)

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)

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.

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,24 +9,28 @@ 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
 
 The examples below are for adding 10 validators. You can use them with any number of validators you would like to add. Run the following command to collectively generate and add 10 new validators with other node operators (similar to DKG):
 
 ```bash
 # If you prefer running a pre-built charon binary
-charon alpha add-validators --num-validators 10 --withdrawal-addresses=0x<your_withdrawal_address> --fee-recipient-addresses=0x<your_fee_recipient_address> --output-dir=output
+charon alpha edit add-validators --num-validators 10 --withdrawal-addresses=0x<your_withdrawal_address> --fee-recipient-addresses=0x<your_fee_recipient_address> --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<your_withdrawal_address> --fee-recipient-addresses=0x<your_fee_recipient_address> --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<your_withdrawal_address> --fee-recipient-addresses=0x<your_fee_recipient_address> --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.