add-validators instructions

Author: pinebit

README.md

@@ -1,8 +1,8 @@
-![Obol Logo](https://obol.tech/obolnetwork.png)
+![Obol Logo](https://obol.org/obolnetwork.png)
 
 <h1 align="center">Charon Distributed Validator Node</h1>
 
-This repo contains the [docker-compose](https://docs.docker.com/compose/) files needed to run one node in a [charon](https://github.com/ObolNetwork/charon) [Distributed Validator Cluster](https://docs.obol.tech/docs/int/key-concepts#distributed-validator-cluster).
+This repo contains the [docker-compose](https://docs.docker.com/compose/) files needed to run one node in a [charon](https://github.com/ObolNetwork/charon) [Distributed Validator Cluster](https://docs.obol.org/docs/int/key-concepts#distributed-validator-cluster).
 
 A distributed validator node is a machine running:
 
@@ -15,31 +15,52 @@ A distributed validator node is a machine running:
 
 # Quickstart
 
-Check the Obol [docs](https://docs.obol.tech/docs/start/quickstart_overview) for detailed instructions on how to get started using this repo.
+Check the Obol [docs](https://docs.obol.org/docs/start/quickstart_overview) for detailed instructions on how to get started using this repo.
 
-# Examples
+# Adding Validators
 
-A default example configuration of a full validator node is found in the root `docker-compose.yml` file.
+Starting with charon v1.6, you can add validators to your cluster using the `charon alpha add-validators` command. Note that this is an experimental feature and should not be used in production (Mainnet) yet. The example below is designed for the default configuration provided by this repository and assumes the stack uses the Lodestar validator client.
 
-The `examples/` directory is under development, you will find a collection of docker compose configuration files that demonstrate various clients and their configurations for running a Distributed Validator Node. These files are with filenames as {EC}-{CC}-{VC}.yml (where EC: Execution Client, CC: Consensus Client, VC: Validator Client). For example, if you wish to run a DV node with Geth EL, Teku CL and Lighthouse VC, you can run `geth_teku_lighthouse.yml`.
+1. Review the `add-validators` command [CLI reference](https://docs.obol.org/next/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.
+3. Run the following command to collectively generate and add 10 new validators with other node operators (similar to DKG):
 
-⚠️⚠️⚠️ **Important:**
-The configurations provided are meant for demonstration purposes only and may not be suitable for production environments.
-These examples are primarily intended for advanced users who are familiar with Docker and have a good understanding of execution and consensus clients.
-Please exercise caution when using them and ensure that you thoroughly review and customize the configurations according to your specific requirements.
+```sh
+charon alpha add-validators --num-validators 10 --withdrawal-addresses=0x<your_withdrawal_address> --fee-recipient-addresses=0x<your_fee_recipient_address>
+```
+
+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 `.charon-add-validators` directory.
 
-To run the default example, use the following command:
+4. To start using the new configuration (with the added validators), stop the current charon and validator client instances:
 
 ```sh
-docker compose up
+docker compose stop charon lodestar
 ```
 
-To run any of the other examples, found in `examples/` use the following command:
+5. Back up and remove the existing `.charon` directory, then move the `.charon-add-validators` directory to `.charon`:
 
 ```sh
-docker compose -f examples/nethermind_teku_lighthouse.yml up
+mv .charon .charon-backup
+mv .charon-add-validators .charon
 ```
 
+6. Restart the charon and validator client instances:
+
+```sh
+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 recognize all validators in the cluster.
+
+Steps 4–6 must be performed independently by all node operators, likely at different times. During this process, some nodes will use the old configuration and others the new one. Once the number of upgraded nodes reaches the BFT threshold, the newly added validators will begin participating in the cluster.
+
+## Current limitations:
+
+- The new cluster configuration will not be reflected in 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 does not have direct access to the keys, it cannot produce valid cluster lock signatures. In this case, you must use the `--unverified` flag, which produces empty signatures. This requires adding the `--no-verify` flag to the `charon run` command.
+- 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.
+
 # FAQs
 
-Check the Obol docs for frequent [errors and resolutions](https://docs.obol.tech/docs/faq/errors)
+Check the Obol docs for frequent [errors and resolutions](https://docs.obol.org/docs/faq/errors)