From d81486ea12da829239f4634e60810434d0943115 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ois=C3=ADn=20Kyne?= Date: Wed, 29 Nov 2023 20:35:50 +0000 Subject: [PATCH] Polishing for beta --- docs/charon/charon-cli-reference.md | 2 +- docs/int/quickstart/activate-dv.md | 39 ++++++------ .../quickstart/advanced/quickstart-combine.md | 61 +++--------------- docs/int/quickstart/alone/create-keys.md | 14 +++-- docs/int/quickstart/alone/deploy.md | 62 ++++++++++++++----- docs/int/quickstart/alone/test-locally.md | 2 +- docs/int/quickstart/quickstart-exit.md | 2 +- docs/int/quickstart/quickstart-mainnet.md | 53 ++++++++++------ docs/int/quickstart/update.md | 6 +- .../charon/charon-cli-reference.md | 2 +- .../int/quickstart/activate-dv.md | 39 ++++++------ .../quickstart/advanced/quickstart-combine.md | 61 +++--------------- .../int/quickstart/alone/create-keys.md | 14 +++-- .../int/quickstart/alone/deploy.md | 62 ++++++++++++++----- .../int/quickstart/alone/test-locally.md | 2 +- .../int/quickstart/quickstart-exit.md | 2 +- .../int/quickstart/quickstart-mainnet.md | 53 ++++++++++------ .../version-v0.18.0/int/quickstart/update.md | 6 +- 18 files changed, 252 insertions(+), 230 deletions(-) diff --git a/docs/charon/charon-cli-reference.md b/docs/charon/charon-cli-reference.md index 4407874e32..e0bae4a5f4 100644 --- a/docs/charon/charon-cli-reference.md +++ b/docs/charon/charon-cli-reference.md @@ -119,7 +119,7 @@ Usage: charon create dkg [flags] Flags: - --dkg-algorithm string DKG algorithm to use; default, keycast, frost (default "default") + --dkg-algorithm string DKG algorithm to use; default, frost (default "default") --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 dkg --name string Optional cosmetic cluster name diff --git a/docs/int/quickstart/activate-dv.md b/docs/int/quickstart/activate-dv.md index e7015532af..b60bd5b3fc 100644 --- a/docs/int/quickstart/activate-dv.md +++ b/docs/int/quickstart/activate-dv.md @@ -2,6 +2,7 @@ sidebar_position: 4 description: Activate the Distributed Validator using the deposit contract --- + import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; @@ -18,34 +19,36 @@ Once you have connected all of your charon clients together, synced all of your The `deposit-data.json` to be used to deposit will be located in each operator's `.charon` folder. The copies across every node should be identical and any of them can be uploaded. :::warning -If you are being given a `deposit-data.json` file that you didn't generate yourself, please take extreme care to ensure this operator has not given you a malicious `deposit-data.json` file that is not the one you expect. Cross reference the files from multiple operators if there is any doubt. Activating the wrong validator or an invalid deposit could result in complete theft or loss of funds. +If you are being given a `deposit-data.json` file that you didn't generate yourself, please take extreme care to ensure this operator has not given you a malicious `deposit-data.json` file that is not the one you expect. Cross reference the files from multiple operators if there is any doubt. Activating the wrong validator or an invalid deposit could result in complete theft or loss of funds. ::: Use any of the following tools to deposit. Please use the third-party tools at your own risk and always double check the staking contract address. -
  • Obol Distributed Validator Launchpad
    • -
  • ethereum.org Staking Launchpad
    • +     -
  • Obol Distributed Validator Launchpad (Soon)
    • -
  • ethereum.org Staking Launchpad
    • -
  • From a SAFE Multisig (Repeat these steps for every validator to deposit in your cluster) -
      -
    • From the SAFE UI, click on New Transaction then Transaction Builder to create a new custom transaction
      • -
    • Enter the beacon chain contract for Deposit on mainnet - you can find it here
      • -
    • Fill the transaction information
        • -
      • Set amount to 32 in ETH
        • -
      • Use your deposit-data.json to fill the required data : pubkey,withdrawal credentials,signature,deposit_data_root. Make sure to prefix the input with 0x to format them in bytes
        • +
      • Obol Distributed Validator Launchpad
        • +
      • ethereum.org Staking Launchpad
        • +
      • From a SAFE Multisig (Repeat these steps for every validator to deposit in your cluster)
        • +
          +
        • From the SAFE UI, click on New Transaction then Transaction Builder to create a new custom transaction
          • +
        • Enter the beacon chain contract for Deposit on mainnet - you can find it here
          • +
        • Fill the transaction information
          • +
        • Set amount to 32 in ETH
          • +
        • Use your deposit-data.json to fill the required data : pubkey,withdrawal credentials,signature,deposit_data_root. Make sure to prefix the input with 0x to format them in bytes
          • +
        • Click on Add transaction
          • +
        • Click on Create Batch
          • +
        • Click on Send Batch, you can click on Simulate to check if the transaction will execute successfully
          • +
        • Get the minimum threshold of signatures from the other addresses and execute the custom transaction
          • +
      -
    • Click on Add transaction
      • -
    • Click on Create Batch
      • -
    • Click on Send Batch, you can click on Simulate to check if the transaction will execute successfully
      • -
    • Get the minimum threshold of signatures from the other addresses and execute the custom transaction
      • -
    • -The activation process can take a minimum of 16 hours, with the maximum time to activation being dictated by the length of the activation queue, which can be weeks. \ No newline at end of file +The activation process can take a minimum of 16 hours, with the maximum time to activation being dictated by the length of the activation queue, which can be weeks. diff --git a/docs/int/quickstart/advanced/quickstart-combine.md b/docs/int/quickstart/advanced/quickstart-combine.md index 5dd6395288..1069e6f005 100644 --- a/docs/int/quickstart/advanced/quickstart-combine.md +++ b/docs/int/quickstart/advanced/quickstart-combine.md @@ -28,9 +28,9 @@ We suggest naming them clearly and distinctly, to avoid confusion. At the end of this process, you should have a tree like this: ```shell -$ tree ./validators-to-be-combined +$ tree ./cluster -validators-to-be-combined/ +cluster/ ├── node0 │   ├── charon-enr-private-key │   ├── cluster-lock.json @@ -82,65 +82,24 @@ Run the following command: ```sh # Combine a clusters private keys -docker run --rm -v "$(pwd):/opt/charon" obolnetwork/charon:v0.18.0 combine --cluster-dir /opt/charon/validators-to-be-combined +docker run --rm -v "$(pwd):/opt/charon" obolnetwork/charon:v0.18.0 combine --cluster-dir /opt/charon/cluster --output-dir /opt/charon/combined ``` This command will create one subdirectory for each validator private key that has been combined, named after its public key. ```shell -$ tree ./validators-to-be-combined - -validators-to-be-combined/ -├── 0x822c5310674f4fc4ec595642d0eab73d01c62b588f467da6f98564f292a975a0ac4c3a10f1b3a00ccc166a28093c2dcd -│   └── validator_keys -│   ├── keystore-0.json -│   └── keystore-0.txt -├── 0x8929b4c8af2d2eb222d377cac2aa7be950e71d2b247507d19b5fdec838f0fb045ea8910075f191fd468da4be29690106 -│   └── validator_keys -│   ├── keystore-0.json -│   └── keystore-0.txt -├── node0 -│   ├── charon-enr-private-key -│   ├── cluster-lock.json -│   ├── deposit-data.json -│   └── validator_keys -│   ├── keystore-0.json -│   ├── keystore-0.txt -│   ├── keystore-1.json -│   └── keystore-1.txt -├── node1 -│   ├── charon-enr-private-key -│   ├── cluster-lock.json -│   ├── deposit-data.json -│   └── validator_keys -│   ├── keystore-0.json -│   ├── keystore-0.txt -│   ├── keystore-1.json -│   └── keystore-1.txt -├── node2 -│   ├── charon-enr-private-key -│   ├── cluster-lock.json -│   ├── deposit-data.json -│   └── validator_keys -│   ├── keystore-0.json -│   ├── keystore-0.txt -│   ├── keystore-1.json -│   └── keystore-1.txt -└── node3 - ├── charon-enr-private-key - ├── cluster-lock.json - ├── deposit-data.json - └── validator_keys - ├── keystore-0.json - ├── keystore-0.txt - ├── keystore-1.json - └── keystore-1.txt +$ tree combined +combined +├── keystore-0.json +├── keystore-0.txt +├── keystore-1.json +└── keystore-1.txt ``` We can verify that the directory names are correct by looking at the lock file: ```shell -$ jq .distributed_validators[].distributed_public_key validators-to-be-combined/node0/cluster-lock.json +$ jq .distributed_validators[].distributed_public_key cluster/node0/cluster-lock.json "0x822c5310674f4fc4ec595642d0eab73d01c62b588f467da6f98564f292a975a0ac4c3a10f1b3a00ccc166a28093c2dcd" "0x8929b4c8af2d2eb222d377cac2aa7be950e71d2b247507d19b5fdec838f0fb045ea8910075f191fd468da4be29690106" ``` diff --git a/docs/int/quickstart/alone/create-keys.md b/docs/int/quickstart/alone/create-keys.md index aee5550cc6..97635851f3 100644 --- a/docs/int/quickstart/alone/create-keys.md +++ b/docs/int/quickstart/alone/create-keys.md @@ -26,7 +26,7 @@ Alternatively, the private key shares can be created in a lower-trust manner wit ## Create the key shares locally - + Create the artifacts needed to run a DV cluster by running the following command to setup the inputs for the DV. Check the Charon CLI reference for additional optional flags to set.

    @@ -37,20 +37,22 @@ Alternatively, the private key shares can be created in a lower-trust manner wit FEE_RECIPIENT_ADDR=[ENTER YOUR FEE RECIPIENT ADDRESS HERE]
    NB_NODES=[ENTER AMOUNT OF DESIRED NODES] +
    + NETWORK="goerli" Then, run this command to create all the key shares and cluster artifacts locally:

           
-      docker run --rm -v "$(pwd):/opt/charon" obolnetwork/charon:v0.18.0 create cluster --name="mycluster" --withdrawal-addresses="{'${WITHDRAWAL_ADDR}'}" --fee-recipient-addresses="{'${FEE_RECIPIENT_ADDR}'}" --nodes="{'${NB_NODES}'}" --network goerli --num-validators=1
+      docker run --rm -v "$(pwd):/opt/charon" obolnetwork/charon:v0.18.0 create cluster --name="Quickstart Cluster" --withdrawal-addresses="{'${WITHDRAWAL_ADDR}'}" --fee-recipient-addresses="{'${FEE_RECIPIENT_ADDR}'}" --nodes="{'${NB_NODES}'}" --network="{'${NETWORK}'}" --num-validators=1 --cluster-dir="cluster"
    - - Go to the Obol Launchpad and select Create a distributed validator alone. Follow the steps to configure your DV cluster. + + Go to the Obol Goerli DV Launchpad and select Create a distributed validator alone. Follow the steps to configure your DV cluster.     -After successful completion, a subdirectory `.charon/cluster` should be created. In it are as many folders as nodes of the cluster. Each folder contains partial private keys that together make up the distributed validator described in `.charon/cluster/cluster-lock.json`. +After successful completion, a subdirectory `cluster/` should be created. In it are as many folders as nodes of the cluster. Each folder contains charon artifacts and partial private keys needed for each node of the cluster. -Once ready, you can move to [deploying this cluster physically](./deploy.md). \ No newline at end of file +Once you have made a backup of the `cluster/` folder, you can move to [deploying this cluster physically](./deploy.md). \ No newline at end of file diff --git a/docs/int/quickstart/alone/deploy.md b/docs/int/quickstart/alone/deploy.md index bdd5d3af8c..fba15ac129 100644 --- a/docs/int/quickstart/alone/deploy.md +++ b/docs/int/quickstart/alone/deploy.md @@ -4,23 +4,57 @@ description: Move the private key shares to the nodes and run the cluster --- # Deploy the cluster -To distribute your cluster physically and start the DV, each node needs a directory called `.charon` with one (or several) private key shares within it as per the structure below. +To distribute your cluster physically and start the DV, each node in the cluster needs one of the folders called `node*/` within the output of the `create cluster` command. These folders should be copied to a CDVN repo, and the folder renamed from `node0/` to `.charon/`. (Or you can override `charon run`'s default file locations) + +```log title="Output from create cluster" + +cluster +├── node0 +│ ├── charon-enr-private-key +│ ├── cluster-lock.json +│ ├── deposit-data.json +│ └── validator_keys +│ ├── keystore-0.json +│ └── keystore-0.txt +├── node1 +│ ├── charon-enr-private-key +│ ├── cluster-lock.json +│ ├── deposit-data.json +│ └── validator_keys +│ ├── keystore-0.json +│ └── keystore-0.txt +├── node2 +│ ├── charon-enr-private-key +│ ├── cluster-lock.json +│ ├── deposit-data.json +│ └── validator_keys +│ ├── keystore-0.json +│ └── keystore-0.txt +└── node3 + ├── charon-enr-private-key + ├── cluster-lock.json + ├── deposit-data.json + └── validator_keys + ├── keystore-0.json + └── keystore-0.txt ``` -├── .charon -│   ├── charon-enr-private-key -│   ├── cluster-lock.json -│   ├── deposit-data.json -│   └── validator_keys -│   ├── keystore-0.json -│   ├── keystore-0.txt -│   ├── ... -│   ├── keystore-N.json -│   └── keystore-N.txt + +```log title="Folder structure to be placed on each DV node" +└── .charon + ├── charon-enr-private-key + ├── cluster-lock.json + ├── deposit-data.json + └── validator_keys + ├── keystore-0.json + ├── keystore-0.txt + ├── ... + ├── keystore-N.json + └── keystore-N.txt ``` :point_right: Use the single node [docker compose](https://github.com/ObolNetwork/charon-distributed-validator-node), the kubernetes [manifests](https://github.com/ObolNetwork/charon-k8s-distributed-validator-node), or the [helm chart](https://github.com/ObolNetwork/helm-charts) example repos to get your nodes up and connected after loading the `.charon` folder artifacts into them appropriately. -:::warning -Right now, the `charon-distributed-node-cluster` repo [used earlier to create the private keys](./create-keys) outputs a folder structure like `.charon/ cluster/node0/validator_keys`. Make sure to grab the `./node0/*` folder, RENAME it to `.charon` and then move it to one of the single node repo above to have a working cluster as per the folder structure shown above. -::: \ No newline at end of file +:::caution +Right now, the `charon create cluster` command [used earlier to create the private keys](./create-keys) outputs a folder structure like `cluster/node*/`. Make sure to grab the `./node*/` folders, *rename* them to `.charon` and then move them to one of the single node repos above. Once all nodes are online, synced, and connected, you will be ready to activate your validator. +::: diff --git a/docs/int/quickstart/alone/test-locally.md b/docs/int/quickstart/alone/test-locally.md index f25eebecaa..17e43c4e8d 100644 --- a/docs/int/quickstart/alone/test-locally.md +++ b/docs/int/quickstart/alone/test-locally.md @@ -5,7 +5,7 @@ description: Test the solo cluster locally # Run a test cluster locally :::warning -This is a demo repo to understand how Distributed Validators work and is not suitable for a production deployment. +This is a demo repo to understand how Distributed Validators work and **is not suitable for a mainnet deployment**. This guide only runs one Execution Client, one Consensus Client, and 6 Distributed Validator Charon Client + Validator Client pairs on a single docker instance. As a consequence, if this machine fails, there will not be fault tolerance. diff --git a/docs/int/quickstart/quickstart-exit.md b/docs/int/quickstart/quickstart-exit.md index 704b992e3c..6d8c53f17f 100644 --- a/docs/int/quickstart/quickstart-exit.md +++ b/docs/int/quickstart/quickstart-exit.md @@ -1,5 +1,5 @@ --- -sidebar_position: 5 +sidebar_position: 6 description: Exit a validator --- diff --git a/docs/int/quickstart/quickstart-mainnet.md b/docs/int/quickstart/quickstart-mainnet.md index fa23b47591..d255f4a69d 100644 --- a/docs/int/quickstart/quickstart-mainnet.md +++ b/docs/int/quickstart/quickstart-mainnet.md @@ -5,21 +5,24 @@ description: Run a cluster on mainnet # Run a DV on mainnet -:::caution -Charon is in a beta state, and you should proceed only if you accept the risk, the [terms of use](https://obol.tech/terms.pdf), and have tested running a Distributed Validator on a testnet first. +:::warning +Charon is in a beta state, and **you should proceed only if you accept the risk, the [terms of use](https://obol.tech/terms.pdf), and have tested running a Distributed Validator on a testnet first**. -Distributed Validators created for goerli cannot be used on mainnet and vice versa, please take caution when creating, backing up, and activating mainnet validators. +Distributed Validators created for goerli cannot be used on mainnet and vice versa, please take caution when creating, backing up, and activating mainnet validators. Incorrect usage may result in a loss of funds. ::: This section is intended for users who wish to run their Distributed Validator on Ethereum mainnet. -### Pre-requisites +## Pre-requisites -- Ensure you have [docker](https://docs.docker.com/engine/install/) installed. -- Ensure you have [git](https://git-scm.com/downloads) installed. +- You have [enough up-to-spec nodes](../key-concepts.md#distributed-validator-threshold) for your mainnet deployment. +- Ensure you have [docker](https://docs.docker.com/engine/install/) installed on each node. +- Ensure you have [git](https://git-scm.com/downloads) installed on each node. - Make sure `docker` is running before executing the commands below. -### Steps +## Steps + +### Using charon-distributed-validator-node in full 1. Clone the [charon-distributed-validator-node](https://github.com/ObolNetwork/charon-distributed-validator-node) repo and `cd` into the directory. @@ -31,16 +34,23 @@ git clone https://github.com/ObolNetwork/charon-distributed-validator-node.git cd charon-distributed-validator-node ``` -2. If you have already cloned the repo, make sure that it is [up-to-date](./update). +2. If you have already cloned the repo previously, make sure that it is [up-to-date](./update). + +3. Copy the `.env.sample.mainnet` file to `.env` -3. Copy the `.env.sample` file to `.env` ``` cp -n .env.sample.mainnet .env ``` -Your DV stack is now mainnet ready 🎉 +4. Run the docker compose file -#### Remote mainnet beacon node +``` +docker compose up -d +``` + +Once your clients can connect and sync appropriately, your DV stack is now mainnet ready 🎉 + +### Using a remote mainnet beacon node :::caution Using a remote beacon node will impact the performance of your Distributed Validator and should be used sparingly. @@ -49,10 +59,13 @@ Using a remote beacon node will impact the performance of your Distributed Valid If you already have a mainnet beacon node running somewhere and you want to use that instead of running EL (`geth`) & CL (`lighthouse`) as part of the repo, you can disable these images. To do so, follow these steps: 1. Copy the `docker-compose.override.yml.sample` file + ``` cp -n docker-compose.override.yml.sample docker-compose.override.yml ``` + 2. Uncomment the `profiles: [disable]` section for both `geth` and `lighthouse`. The override file should now look like this + ``` services: geth: @@ -73,7 +86,9 @@ services: #- 5054:5054 # Metrics ... ``` + 3. Then, uncomment and set the `CHARON_BEACON_NODE_ENDPOINTS` variable in the `.env` file to your mainnet beacon node's URL + ``` ... # Connect to one or more external beacon nodes. Use a comma separated list excluding spaces. @@ -81,15 +96,13 @@ CHARON_BEACON_NODE_ENDPOINTS= ... ``` -#### Exit a mainnet distributed validator - -If you want to exit your mainnet validator, you need to uncomment and set the `EXIT_EPOCH` variable in the `.env` file +4. Restart your docker compose ``` -... -# Cluster wide consistent exit epoch. Set to latest for fork version, see `curl $BEACON_NODE/eth/v1/config/fork_schedule` -# Currently, the latest fork is capella (epoch: 194048) -EXIT_EPOCH=194048 -... +docker compose down +docker compose up -d ``` -Note that `EXIT_EPOCH` should be `194048` after the [shapella fork](https://blog.ethereum.org/2023/03/28/shapella-mainnet-announcement). + +### Exit a mainnet Distributed Validator + +If you want to exit your mainnet validator, refer to our [exit guide](./quickstart-exit.md). \ No newline at end of file diff --git a/docs/int/quickstart/update.md b/docs/int/quickstart/update.md index 3187bbc0bf..e6ca215bec 100644 --- a/docs/int/quickstart/update.md +++ b/docs/int/quickstart/update.md @@ -1,5 +1,5 @@ --- -sidebar_position: 6 +sidebar_position: 5 description: Update your DV cluster with the latest Charon release --- import Tabs from '@theme/Tabs'; @@ -14,7 +14,7 @@ To do this, follow these steps: ### Navigate to the node directory - + 
           
         cd charon-distributed-validator-node
@@ -22,7 +22,7 @@ To do this, follow these steps:
    - + 
           
         cd charon-distributed-validator-cluster
diff --git a/versioned_docs/version-v0.18.0/charon/charon-cli-reference.md b/versioned_docs/version-v0.18.0/charon/charon-cli-reference.md
index 4407874e32..e0bae4a5f4 100644
--- a/versioned_docs/version-v0.18.0/charon/charon-cli-reference.md
+++ b/versioned_docs/version-v0.18.0/charon/charon-cli-reference.md
@@ -119,7 +119,7 @@ Usage:
   charon create dkg [flags]
 
 Flags:
-      --dkg-algorithm string              DKG algorithm to use; default, keycast, frost (default "default")
+      --dkg-algorithm string              DKG algorithm to use; default, frost (default "default")
       --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 dkg
       --name string                       Optional cosmetic cluster name
diff --git a/versioned_docs/version-v0.18.0/int/quickstart/activate-dv.md b/versioned_docs/version-v0.18.0/int/quickstart/activate-dv.md
index e7015532af..b60bd5b3fc 100644
--- a/versioned_docs/version-v0.18.0/int/quickstart/activate-dv.md
+++ b/versioned_docs/version-v0.18.0/int/quickstart/activate-dv.md
@@ -2,6 +2,7 @@
 sidebar_position: 4
 description: Activate the Distributed Validator using the deposit contract
 ---
+
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
@@ -18,34 +19,36 @@ Once you have connected all of your charon clients together, synced all of your
 The `deposit-data.json` to be used to deposit will be located in each operator's `.charon` folder. The copies across every node should be identical and any of them can be uploaded.
 
 :::warning
-If you are being given a `deposit-data.json` file that you didn't generate yourself, please take extreme care to ensure this operator has not given you a malicious `deposit-data.json` file that is not the one you expect. Cross reference the files from multiple operators if there is any doubt. Activating the wrong validator or an invalid deposit could result in complete theft or loss of funds. 
+If you are being given a `deposit-data.json` file that you didn't generate yourself, please take extreme care to ensure this operator has not given you a malicious `deposit-data.json` file that is not the one you expect. Cross reference the files from multiple operators if there is any doubt. Activating the wrong validator or an invalid deposit could result in complete theft or loss of funds.
 :::
 
 Use any of the following tools to deposit. Please use the third-party tools at your own risk and always double check the staking contract address.
 
 
   
-    
  • Obol Distributed Validator Launchpad
    • 
-    
  • ethereum.org Staking Launchpad
    • 
+    
       
   
-    
  • Obol Distributed Validator Launchpad (Soon)
    • 
-    
  • ethereum.org Staking Launchpad
    • 
-    
  • From a SAFE Multisig (Repeat these steps for every validator to deposit in your cluster)
-    
      
-    
    • From the SAFE UI, click on New Transaction then Transaction Builder to create a new custom transaction
      • 
-    
    • Enter the beacon chain contract for Deposit on mainnet - you can find it here
      • 
-    
    • Fill the transaction information
      • 
     
        
-    
      • Set amount to 32 in ETH
        • 
-    
      • Use your deposit-data.json to fill the required data : pubkey,withdrawal credentials,signature,deposit_data_root. Make sure to prefix the input with 0x to format them in bytes
        • 
+      
      • Obol Distributed Validator Launchpad
        • 
+      
      • ethereum.org Staking Launchpad
        • 
+      
      • From a SAFE Multisig (Repeat these steps for every validator to deposit in your cluster)
        • 
+      
          
+        
        • From the SAFE UI, click on New Transaction then Transaction Builder to create a new custom transaction
          • 
+        
        • Enter the beacon chain contract for Deposit on mainnet - you can find it here
          • 
+        
        • Fill the transaction information
          • 
+        
        • Set amount to 32 in ETH
          • 
+        
        • Use your deposit-data.json to fill the required data : pubkey,withdrawal credentials,signature,deposit_data_root. Make sure to prefix the input with 0x to format them in bytes
          • 
+        
        • Click on Add transaction
          • 
+        
        • Click on Create Batch
          • 
+        
        • Click on Send Batch, you can click on Simulate to check if the transaction will execute successfully
          • 
+        
        • Get the minimum threshold of signatures from the other addresses and execute the custom transaction
          • 
+      
        
     
      
-    
    • Click on Add transaction
      • 
-    
    • Click on Create Batch
      • 
-    
    • Click on Send Batch, you can click on Simulate to check if the transaction will execute successfully
      • 
-    
    • Get the minimum threshold of signatures from the other addresses and execute the custom transaction
      • 
-    
    • 
       
     
 
-The activation process can take a minimum of 16 hours, with the maximum time to activation being dictated by the length of the activation queue, which can be weeks.
\ No newline at end of file
+The activation process can take a minimum of 16 hours, with the maximum time to activation being dictated by the length of the activation queue, which can be weeks.
diff --git a/versioned_docs/version-v0.18.0/int/quickstart/advanced/quickstart-combine.md b/versioned_docs/version-v0.18.0/int/quickstart/advanced/quickstart-combine.md
index 5dd6395288..1069e6f005 100644
--- a/versioned_docs/version-v0.18.0/int/quickstart/advanced/quickstart-combine.md
+++ b/versioned_docs/version-v0.18.0/int/quickstart/advanced/quickstart-combine.md
@@ -28,9 +28,9 @@ We suggest naming them clearly and distinctly, to avoid confusion.
 At the end of this process, you should have a tree like this:
 
 ```shell
-$ tree ./validators-to-be-combined
+$ tree ./cluster
 
-validators-to-be-combined/
+cluster/
 ├── node0
 │   ├── charon-enr-private-key
 │   ├── cluster-lock.json
@@ -82,65 +82,24 @@ Run the following command:
 
 ```sh
 # Combine a clusters private keys
-docker run --rm -v "$(pwd):/opt/charon" obolnetwork/charon:v0.18.0 combine --cluster-dir /opt/charon/validators-to-be-combined
+docker run --rm -v "$(pwd):/opt/charon" obolnetwork/charon:v0.18.0 combine --cluster-dir /opt/charon/cluster --output-dir /opt/charon/combined
 ```
 
 This command will create one subdirectory for each validator private key that has been combined, named after its public key.
  
 ```shell
-$ tree ./validators-to-be-combined
-
-validators-to-be-combined/
-├── 0x822c5310674f4fc4ec595642d0eab73d01c62b588f467da6f98564f292a975a0ac4c3a10f1b3a00ccc166a28093c2dcd
-│   └── validator_keys
-│       ├── keystore-0.json
-│       └── keystore-0.txt
-├── 0x8929b4c8af2d2eb222d377cac2aa7be950e71d2b247507d19b5fdec838f0fb045ea8910075f191fd468da4be29690106
-│   └── validator_keys
-│       ├── keystore-0.json
-│       └── keystore-0.txt
-├── node0
-│   ├── charon-enr-private-key
-│   ├── cluster-lock.json
-│   ├── deposit-data.json
-│   └── validator_keys
-│       ├── keystore-0.json
-│       ├── keystore-0.txt
-│       ├── keystore-1.json
-│       └── keystore-1.txt
-├── node1
-│   ├── charon-enr-private-key
-│   ├── cluster-lock.json
-│   ├── deposit-data.json
-│   └── validator_keys
-│       ├── keystore-0.json
-│       ├── keystore-0.txt
-│       ├── keystore-1.json
-│       └── keystore-1.txt
-├── node2
-│   ├── charon-enr-private-key
-│   ├── cluster-lock.json
-│   ├── deposit-data.json
-│   └── validator_keys
-│       ├── keystore-0.json
-│       ├── keystore-0.txt
-│       ├── keystore-1.json
-│       └── keystore-1.txt
-└── node3
-    ├── charon-enr-private-key
-    ├── cluster-lock.json
-    ├── deposit-data.json
-    └── validator_keys
-        ├── keystore-0.json
-        ├── keystore-0.txt
-        ├── keystore-1.json
-        └── keystore-1.txt
+$ tree combined
+combined
+├── keystore-0.json
+├── keystore-0.txt
+├── keystore-1.json
+└── keystore-1.txt
 ```
 
 We can verify that the directory names are correct by looking at the lock file:
 
 ```shell
-$ jq .distributed_validators[].distributed_public_key  validators-to-be-combined/node0/cluster-lock.json
+$ jq .distributed_validators[].distributed_public_key  cluster/node0/cluster-lock.json
 "0x822c5310674f4fc4ec595642d0eab73d01c62b588f467da6f98564f292a975a0ac4c3a10f1b3a00ccc166a28093c2dcd"
 "0x8929b4c8af2d2eb222d377cac2aa7be950e71d2b247507d19b5fdec838f0fb045ea8910075f191fd468da4be29690106"
 ```
diff --git a/versioned_docs/version-v0.18.0/int/quickstart/alone/create-keys.md b/versioned_docs/version-v0.18.0/int/quickstart/alone/create-keys.md
index aee5550cc6..97635851f3 100644
--- a/versioned_docs/version-v0.18.0/int/quickstart/alone/create-keys.md
+++ b/versioned_docs/version-v0.18.0/int/quickstart/alone/create-keys.md
@@ -26,7 +26,7 @@ Alternatively, the private key shares can be created in a lower-trust manner wit
 ## Create the key shares locally
 
 
-  
+  
     Create the artifacts needed to run a DV cluster by running the following command to setup the inputs for the DV.
     Check the Charon CLI reference for additional optional flags to set.
     

    
@@ -37,20 +37,22 @@ Alternatively, the private key shares can be created in a lower-trust manner wit
       FEE_RECIPIENT_ADDR=[ENTER YOUR FEE RECIPIENT ADDRESS HERE]
       
    
       NB_NODES=[ENTER AMOUNT OF DESIRED NODES]
+      
    
+      NETWORK="goerli"
    Then, run this command to create all the key shares and cluster artifacts locally:

           
-      docker run --rm -v "$(pwd):/opt/charon" obolnetwork/charon:v0.18.0 create cluster --name="mycluster" --withdrawal-addresses="{'${WITHDRAWAL_ADDR}'}" --fee-recipient-addresses="{'${FEE_RECIPIENT_ADDR}'}" --nodes="{'${NB_NODES}'}" --network goerli --num-validators=1
+      docker run --rm -v "$(pwd):/opt/charon" obolnetwork/charon:v0.18.0 create cluster --name="Quickstart Cluster" --withdrawal-addresses="{'${WITHDRAWAL_ADDR}'}" --fee-recipient-addresses="{'${FEE_RECIPIENT_ADDR}'}" --nodes="{'${NB_NODES}'}" --network="{'${NETWORK}'}" --num-validators=1 --cluster-dir="cluster"
    - - Go to the Obol Launchpad and select Create a distributed validator alone. Follow the steps to configure your DV cluster. + + Go to the Obol Goerli DV Launchpad and select Create a distributed validator alone. Follow the steps to configure your DV cluster.     -After successful completion, a subdirectory `.charon/cluster` should be created. In it are as many folders as nodes of the cluster. Each folder contains partial private keys that together make up the distributed validator described in `.charon/cluster/cluster-lock.json`. +After successful completion, a subdirectory `cluster/` should be created. In it are as many folders as nodes of the cluster. Each folder contains charon artifacts and partial private keys needed for each node of the cluster. -Once ready, you can move to [deploying this cluster physically](./deploy.md). \ No newline at end of file +Once you have made a backup of the `cluster/` folder, you can move to [deploying this cluster physically](./deploy.md). \ No newline at end of file diff --git a/versioned_docs/version-v0.18.0/int/quickstart/alone/deploy.md b/versioned_docs/version-v0.18.0/int/quickstart/alone/deploy.md index bdd5d3af8c..fba15ac129 100644 --- a/versioned_docs/version-v0.18.0/int/quickstart/alone/deploy.md +++ b/versioned_docs/version-v0.18.0/int/quickstart/alone/deploy.md @@ -4,23 +4,57 @@ description: Move the private key shares to the nodes and run the cluster --- # Deploy the cluster -To distribute your cluster physically and start the DV, each node needs a directory called `.charon` with one (or several) private key shares within it as per the structure below. +To distribute your cluster physically and start the DV, each node in the cluster needs one of the folders called `node*/` within the output of the `create cluster` command. These folders should be copied to a CDVN repo, and the folder renamed from `node0/` to `.charon/`. (Or you can override `charon run`'s default file locations) + +```log title="Output from create cluster" + +cluster +├── node0 +│ ├── charon-enr-private-key +│ ├── cluster-lock.json +│ ├── deposit-data.json +│ └── validator_keys +│ ├── keystore-0.json +│ └── keystore-0.txt +├── node1 +│ ├── charon-enr-private-key +│ ├── cluster-lock.json +│ ├── deposit-data.json +│ └── validator_keys +│ ├── keystore-0.json +│ └── keystore-0.txt +├── node2 +│ ├── charon-enr-private-key +│ ├── cluster-lock.json +│ ├── deposit-data.json +│ └── validator_keys +│ ├── keystore-0.json +│ └── keystore-0.txt +└── node3 + ├── charon-enr-private-key + ├── cluster-lock.json + ├── deposit-data.json + └── validator_keys + ├── keystore-0.json + └── keystore-0.txt ``` -├── .charon -│   ├── charon-enr-private-key -│   ├── cluster-lock.json -│   ├── deposit-data.json -│   └── validator_keys -│   ├── keystore-0.json -│   ├── keystore-0.txt -│   ├── ... -│   ├── keystore-N.json -│   └── keystore-N.txt + +```log title="Folder structure to be placed on each DV node" +└── .charon + ├── charon-enr-private-key + ├── cluster-lock.json + ├── deposit-data.json + └── validator_keys + ├── keystore-0.json + ├── keystore-0.txt + ├── ... + ├── keystore-N.json + └── keystore-N.txt ``` :point_right: Use the single node [docker compose](https://github.com/ObolNetwork/charon-distributed-validator-node), the kubernetes [manifests](https://github.com/ObolNetwork/charon-k8s-distributed-validator-node), or the [helm chart](https://github.com/ObolNetwork/helm-charts) example repos to get your nodes up and connected after loading the `.charon` folder artifacts into them appropriately. -:::warning -Right now, the `charon-distributed-node-cluster` repo [used earlier to create the private keys](./create-keys) outputs a folder structure like `.charon/ cluster/node0/validator_keys`. Make sure to grab the `./node0/*` folder, RENAME it to `.charon` and then move it to one of the single node repo above to have a working cluster as per the folder structure shown above. -::: \ No newline at end of file +:::caution +Right now, the `charon create cluster` command [used earlier to create the private keys](./create-keys) outputs a folder structure like `cluster/node*/`. Make sure to grab the `./node*/` folders, *rename* them to `.charon` and then move them to one of the single node repos above. Once all nodes are online, synced, and connected, you will be ready to activate your validator. +::: diff --git a/versioned_docs/version-v0.18.0/int/quickstart/alone/test-locally.md b/versioned_docs/version-v0.18.0/int/quickstart/alone/test-locally.md index f25eebecaa..17e43c4e8d 100644 --- a/versioned_docs/version-v0.18.0/int/quickstart/alone/test-locally.md +++ b/versioned_docs/version-v0.18.0/int/quickstart/alone/test-locally.md @@ -5,7 +5,7 @@ description: Test the solo cluster locally # Run a test cluster locally :::warning -This is a demo repo to understand how Distributed Validators work and is not suitable for a production deployment. +This is a demo repo to understand how Distributed Validators work and **is not suitable for a mainnet deployment**. This guide only runs one Execution Client, one Consensus Client, and 6 Distributed Validator Charon Client + Validator Client pairs on a single docker instance. As a consequence, if this machine fails, there will not be fault tolerance. diff --git a/versioned_docs/version-v0.18.0/int/quickstart/quickstart-exit.md b/versioned_docs/version-v0.18.0/int/quickstart/quickstart-exit.md index 704b992e3c..6d8c53f17f 100644 --- a/versioned_docs/version-v0.18.0/int/quickstart/quickstart-exit.md +++ b/versioned_docs/version-v0.18.0/int/quickstart/quickstart-exit.md @@ -1,5 +1,5 @@ --- -sidebar_position: 5 +sidebar_position: 6 description: Exit a validator --- diff --git a/versioned_docs/version-v0.18.0/int/quickstart/quickstart-mainnet.md b/versioned_docs/version-v0.18.0/int/quickstart/quickstart-mainnet.md index fa23b47591..d255f4a69d 100644 --- a/versioned_docs/version-v0.18.0/int/quickstart/quickstart-mainnet.md +++ b/versioned_docs/version-v0.18.0/int/quickstart/quickstart-mainnet.md @@ -5,21 +5,24 @@ description: Run a cluster on mainnet # Run a DV on mainnet -:::caution -Charon is in a beta state, and you should proceed only if you accept the risk, the [terms of use](https://obol.tech/terms.pdf), and have tested running a Distributed Validator on a testnet first. +:::warning +Charon is in a beta state, and **you should proceed only if you accept the risk, the [terms of use](https://obol.tech/terms.pdf), and have tested running a Distributed Validator on a testnet first**. -Distributed Validators created for goerli cannot be used on mainnet and vice versa, please take caution when creating, backing up, and activating mainnet validators. +Distributed Validators created for goerli cannot be used on mainnet and vice versa, please take caution when creating, backing up, and activating mainnet validators. Incorrect usage may result in a loss of funds. ::: This section is intended for users who wish to run their Distributed Validator on Ethereum mainnet. -### Pre-requisites +## Pre-requisites -- Ensure you have [docker](https://docs.docker.com/engine/install/) installed. -- Ensure you have [git](https://git-scm.com/downloads) installed. +- You have [enough up-to-spec nodes](../key-concepts.md#distributed-validator-threshold) for your mainnet deployment. +- Ensure you have [docker](https://docs.docker.com/engine/install/) installed on each node. +- Ensure you have [git](https://git-scm.com/downloads) installed on each node. - Make sure `docker` is running before executing the commands below. -### Steps +## Steps + +### Using charon-distributed-validator-node in full 1. Clone the [charon-distributed-validator-node](https://github.com/ObolNetwork/charon-distributed-validator-node) repo and `cd` into the directory. @@ -31,16 +34,23 @@ git clone https://github.com/ObolNetwork/charon-distributed-validator-node.git cd charon-distributed-validator-node ``` -2. If you have already cloned the repo, make sure that it is [up-to-date](./update). +2. If you have already cloned the repo previously, make sure that it is [up-to-date](./update). + +3. Copy the `.env.sample.mainnet` file to `.env` -3. Copy the `.env.sample` file to `.env` ``` cp -n .env.sample.mainnet .env ``` -Your DV stack is now mainnet ready 🎉 +4. Run the docker compose file -#### Remote mainnet beacon node +``` +docker compose up -d +``` + +Once your clients can connect and sync appropriately, your DV stack is now mainnet ready 🎉 + +### Using a remote mainnet beacon node :::caution Using a remote beacon node will impact the performance of your Distributed Validator and should be used sparingly. @@ -49,10 +59,13 @@ Using a remote beacon node will impact the performance of your Distributed Valid If you already have a mainnet beacon node running somewhere and you want to use that instead of running EL (`geth`) & CL (`lighthouse`) as part of the repo, you can disable these images. To do so, follow these steps: 1. Copy the `docker-compose.override.yml.sample` file + ``` cp -n docker-compose.override.yml.sample docker-compose.override.yml ``` + 2. Uncomment the `profiles: [disable]` section for both `geth` and `lighthouse`. The override file should now look like this + ``` services: geth: @@ -73,7 +86,9 @@ services: #- 5054:5054 # Metrics ... ``` + 3. Then, uncomment and set the `CHARON_BEACON_NODE_ENDPOINTS` variable in the `.env` file to your mainnet beacon node's URL + ``` ... # Connect to one or more external beacon nodes. Use a comma separated list excluding spaces. @@ -81,15 +96,13 @@ CHARON_BEACON_NODE_ENDPOINTS= ... ``` -#### Exit a mainnet distributed validator - -If you want to exit your mainnet validator, you need to uncomment and set the `EXIT_EPOCH` variable in the `.env` file +4. Restart your docker compose ``` -... -# Cluster wide consistent exit epoch. Set to latest for fork version, see `curl $BEACON_NODE/eth/v1/config/fork_schedule` -# Currently, the latest fork is capella (epoch: 194048) -EXIT_EPOCH=194048 -... +docker compose down +docker compose up -d ``` -Note that `EXIT_EPOCH` should be `194048` after the [shapella fork](https://blog.ethereum.org/2023/03/28/shapella-mainnet-announcement). + +### Exit a mainnet Distributed Validator + +If you want to exit your mainnet validator, refer to our [exit guide](./quickstart-exit.md). \ No newline at end of file diff --git a/versioned_docs/version-v0.18.0/int/quickstart/update.md b/versioned_docs/version-v0.18.0/int/quickstart/update.md index 3187bbc0bf..e6ca215bec 100644 --- a/versioned_docs/version-v0.18.0/int/quickstart/update.md +++ b/versioned_docs/version-v0.18.0/int/quickstart/update.md @@ -1,5 +1,5 @@ --- -sidebar_position: 6 +sidebar_position: 5 description: Update your DV cluster with the latest Charon release --- import Tabs from '@theme/Tabs'; @@ -14,7 +14,7 @@ To do this, follow these steps: ### Navigate to the node directory - + 
           
         cd charon-distributed-validator-node
@@ -22,7 +22,7 @@ To do this, follow these steps:
    - + 
           
         cd charon-distributed-validator-cluster