diff --git a/docusaurus.config.ts b/docusaurus.config.ts index c8055fa7..2f79bfeb 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -285,7 +285,7 @@ const config: Config = { theme: prismThemes.github, defaultLanguage: 'typescript', darkTheme: prismThemes.dracula, - additionalLanguages: ['json', 'bash', 'javascript', 'python', 'solidity'], + additionalLanguages: ['json', 'bash', 'javascript', 'python', 'solidity', 'ini'], }, } satisfies Preset.ThemeConfig, } diff --git a/operator/alternative-key-management/dvt/img/ssv_dkg_flow.png b/operator/alternative-key-management/dvt/img/ssv_dkg_flow.png new file mode 100644 index 00000000..6462d462 Binary files /dev/null and b/operator/alternative-key-management/dvt/img/ssv_dkg_flow.png differ diff --git a/operator/alternative-key-management/dvt/ssv-dkg.mdx b/operator/alternative-key-management/dvt/ssv-dkg.mdx new file mode 100644 index 00000000..cbc6b7c0 --- /dev/null +++ b/operator/alternative-key-management/dvt/ssv-dkg.mdx @@ -0,0 +1,236 @@ +--- +title: DKG Ceremony +description: Create distributed validators on SSV Network through a DKG ceremony and register them in your StakeWise Vault via the DVT Relayer. +--- + +import Image from '@theme/IdealImage' + +# DKG Ceremony + +In the DKG ceremony, the SSV operators generate the validator key shares together. The full private key is never constructed on any machine. The ceremony is run with [`ssv-dkg` ↗](https://github.com/ssvlabs/ssv-dkg) and involves two roles: + +- **Operators** — each runs a long-lived `ssv-dkg` service to take part in ceremonies. +- **Initiator** — triggers the ceremony and collects its outputs. It can be one of the Operators or a separate entity. + +ssv dkg flow + +## How Vaults Use the DKG Ceremony + +Setting up your Vault's validators across a cluster of SSV operators involves several stages: + +1. **Generating the validator's key shares.** The operators run a DKG ceremony that produces the validator's public key and one private key share per operator, each encrypted to that operator's RSA public key and written to `keyshares.json`. +2. **Registering the validator on the SSV Network.** The validator's public key and encrypted shares from `keyshares.json` are registered on the SSV Network. Each operator's Sidecar can then read its own share. +3. **Depositing the validator's stake on the Beacon Chain.** Each Sidecar reads its share, signs the deposit message, and sends its signature share to the Relayer, which combines the shares into the full deposit signature. The Operator Service then submits the deposit data to the Vault. + +This guide covers the DKG setup with StakeWise Vaults. It assumes the Initiator is one of the operators and the ultimate owner of the setup. + +## Step 1: Run the DKG Service + +Each operator runs a long-lived `ssv-dkg` service to take part in DKG ceremonies. It is separate from the SSV node (which performs the validator's ongoing duties, such as attestations and proposals) and reuses the operator's existing key. + +:::custom-info[Minimum Requirements] +`ssv-dkg` relies heavily on cryptography, so computational power has a major impact on its performance. Demand rises with the number of validators created at once. + +- **Minimum:** an [AWS `t3.medium` ↗](https://aws.amazon.com/ec2/instance-types/) or equivalent machine dedicated to DKG. +- **Recommended:** an AWS `t3.large` or higher tier. + +Minimum Docker resource allocation: + +```yaml +deploy: + resources: + limits: + cpus: "1" + memory: 500M +``` +::: + +1. Create an `operator.config.yaml` in the same folder as your `encrypted_private_key.json` and `password` files: + +```yaml +privKey: /data/encrypted_private_key.json +privKeyPassword: /data/password +operatorID: 1 # your SSV operator ID +port: 3030 +logLevel: info +logFilePath: /data/debug.log +outputPath: /data/output +``` + +2. Start the service: + +```bash +docker run --restart unless-stopped --name ssv_dkg -p 3030:3030 \ + -v "$(pwd)":/data -u `id -u $USER` -it \ + "ssvlabs/ssv-dkg:v3.0.3" start-operator --configPath /data/operator.config.yaml +``` + +:::custom-warning[Expose the DKG Port] +The Initiator connects to your endpoint during a ceremony. Expose the port you configured on the machine firewall and in the Docker container command. Otherwise, your DKG node will not be available. +::: + +## Step 2: Generate the Key Shares + +:::custom-tips[Webapp or CLI] +This guide uses the [SSV webapp ↗](https://app.ssv.network), which generates the `ssv-dkg` command with the operators data and config already filled in. The Initiator can also run `ssv-dkg init` directly by building a custom `operators_info.json`. See SSV's [ssv-dkg client guide ↗](https://docs.ssv.network/stakers/tools/ssv-dkg-client/). +::: + +1. In the webapp, open **Operators → Validator Clusters → Create a cluster** and select your cluster's operators (search by **ID** or name; minimum 4). They must be **DKG-enabled**, meaning they run `ssv-dkg start-operator` (Step 1) with a reachable endpoint. +2. Choose **Generate new key shares → Offline → DKG**. +3. Set the number of validators and the **Withdrawal Address** to your **Vault contract address**, then confirm. +4. Copy the generated command and run it on a machine with Docker. The webapp pre-fills `--owner`, `--nonce`, `--withdrawAddress`, `--operatorIDs`, and `--operatorsInfo` (each operator's ID, RSA key, and endpoint). + +
+Example generated command + +```bash +docker pull ssvlabs/ssv-dkg:v3.0.3 && docker run --rm -v "$(pwd)":/ssv-dkg/data -it \ + "ssvlabs/ssv-dkg:v3.0.3" init \ + --owner --nonce \ + --withdrawAddress \ + --operatorIDs 1,2,3,4 \ + --operatorsInfo '[{"id":1,"public_key":"LS0t...","ip":"https://5.4.3.2:3030"}, ...]' \ + --network hoodi --validators 1 --outputPath ./data --tlsInsecure +``` + +
+ +For every flag and what it does, see SSV's [command-line reference ↗](https://docs.ssv.network/stakers/tools/ssv-dkg-client/commands-and-config/#base-initiator-options). + +The ceremony writes a `ceremony-/` directory with `keyshares.json`, `deposit_data.json`, and `proofs.json`: + +
+Ceremony output + +``` +ceremony-/ +├─ -0x/ +│ ├─ deposit_data.json # Deposit data to activate the validator — not used by StakeWise (the Vault deposits) +│ ├─ keyshares.json # Encrypted shares, to register on SSV +│ └─ proof.json # Proof used to reshare to new operators later +├─ deposit_data.json # Aggregated across all validators +├─ keyshares.json # Aggregated across all validators +└─ proofs.json # Aggregated across all validators +``` + +The `keyshares.json` holds each share encrypted to its operator's RSA key. For the full format, see SSV's [`keyshares.json` structure ↗](https://docs.ssv.network/developers/security/keyshares-structure). + +
+ +:::custom-tips[Keep the Proofs] +Back up `proofs.json`. It lets you reshare the cluster to a different set of operators later without running a new ceremony. +::: + +## Step 3: Register the Key Shares + +The Initiator registers the key shares on SSV so the encrypted shares are published on-chain, where the Sidecars read each operator's share. **You do not deposit here:** in the StakeWise flow the **Vault** deposits later, once it has accumulated enough assets, through the Relayer (Step 6), not via the Ethereum Launchpad. + +After the ceremony, the webapp shows a **Deposit Validator** step and a **Register Validator** step: + +1. **Skip the Launchpad deposit.** Click **"My validator has been activated"** to unlock registration. You are *not* depositing 32 ETH yourself. +2. Click **Register Validator**, upload the ceremony's **`keyshares.json`**, and complete registration (Fund the Cluster → Approve SSV → Register Validator), the same [registration steps](/operator/alternative-key-management/dvt/ssv-split-keys#register-validator) as Split Keys. + +## Step 4: Run the DVT Sidecar + +Each operator runs one [DVT Sidecar ↗](https://github.com/stakewise/dvt-operator-sidecar) on the machine running their node. SSV publishes each operator's encrypted key share on-chain (in the `ValidatorAdded` event log), so in SSV mode the Sidecar does **not** read the share from a local file. Instead, it reads its encrypted share from on-chain and decrypts it with the operator's RSA key. It then signs the deposit and exit messages and submits the signature shares to the Relayer. + +1. Create the `.env` file from the repository's template: + +```bash +cp .env.example .env +``` + +2. Set the values for your SSV operator: + +```ini +# Network: mainnet or hoodi +NETWORK=mainnet + +# DVT cluster type +CLUSTER_TYPE=SSV + +# URL of your DVT Relayer +RELAYER_ENDPOINT=http://relayer + +# This operator's SSV key (same files used to run the node and the DKG service). +# This is the RSA operator key used to DECRYPT the on-chain share — not a validator key share. +SSV_OPERATOR_KEY_FILE=encrypted_private_key.json +SSV_OPERATOR_PASSWORD_FILE=password +# This operator's SSV operator ID +SSV_OPERATOR_ID=1 + +# Execution and consensus client endpoints (the execution endpoint is used to read the on-chain shares) +EXECUTION_ENDPOINT=http://execution:8545 +CONSENSUS_ENDPOINT=http://consensus:5052 +``` + +3. Run the container: + +```bash +docker run \ + -u $(id -u):$(id -g) \ + --env-file .env \ + -v $(pwd)/data:/data \ + europe-west4-docker.pkg.dev/stakewiselabs/public/dvt-operator-sidecar:v2.1.0 +``` + +## Step 5: Run the DVT Relayer + +The Initiator runs one [DVT Relayer ↗](https://github.com/stakewise/dvt-relayer) that serves the whole cluster. It collects the Sidecars' signature shares, reconstructs the full signatures, and serves the registration data to the Operator Service. It holds the Vault's Validators Manager wallet to sign registrations, but never has access to the validator key shares. + +1. Create the `.env` from the repository's template: + +```bash +cp .env.example .env +``` + +2. In a `data/` directory, place the files the Relayer reads: + + - `validators-manager-key.json` and `validators-manager-password.txt` — the keystore and password for the Ethereum wallet set as your Vault's [Validators Manager](/operator/validators-manager). This is an externally owned account (EOA) that signs registration transactions, not a validator signing key. + - `public_keys.txt` — the distributed validator **public** keys, one per line. Take the `pubkey` of each validator from the ceremony's `deposit_data.json`. + +3. Set the values (file paths point inside the mounted `/data`): + +```ini +# API server +RELAYER_HOST=0.0.0.0 +RELAYER_PORT=8000 + +# BLS signature threshold — must match your cluster's threshold +SIGNATURE_THRESHOLD=3 + +# Network: mainnet or hoodi +NETWORK=mainnet + +# Execution and consensus client endpoints +EXECUTION_ENDPOINT=https://execution +CONSENSUS_ENDPOINT=https://consensus + +# Validator public keys to register, one per line +PUBLIC_KEYS_FILE=/data/public_keys.txt + +# The Validators Manager wallet that signs registrations +VALIDATORS_MANAGER_KEY_FILE=/data/validators-manager-key.json +VALIDATORS_MANAGER_PASSWORD_FILE=/data/validators-manager-password.txt +``` + +4. Pull and run the Relayer: + +```bash +export DVT_RELAYER_VERSION=v1.1.0 +docker run --rm -ti \ + --env-file .env \ + -v $(pwd)/data:/data \ + -p 8000:8000 \ + europe-west4-docker.pkg.dev/stakewiselabs/public/dvt-relayer:$DVT_RELAYER_VERSION +``` + +## Step 6: Start the Operator Service + +Because the Operator Service has no keystores, the Initiator starts it in Relayer mode, pointing at the DVT Relayer: + +```bash +./operator start-relayer +``` + +The Operator Service polls the Relayer for validators that have all required signatures and registers them in the Vault contract. At that moment the **Vault deposits its pooled ETH**, and the validator is created on the Beacon Chain. Once it activates, the SSV operators perform its duties using their shares. diff --git a/operator/alternative-key-management/dvt/ssv-setup.mdx b/operator/alternative-key-management/dvt/ssv-setup.mdx index 1db9e6ce..3b334ccc 100644 --- a/operator/alternative-key-management/dvt/ssv-setup.mdx +++ b/operator/alternative-key-management/dvt/ssv-setup.mdx @@ -1,59 +1,52 @@ --- title: SSV Setup -description: Run validators using SSV Network's distributed validator technology with StakeWise Vaults. +description: Run validators with SSV Network's distributed validator technology and StakeWise Vaults. --- # SSV Setup -[SSV Network ↗](https://ssv.network) is a permissionless DVT network that provides a simple infrastructure for splitting and distributing a validator key into multiple key shares to run a validator across multiple non-trusting nodes. +[SSV Network ↗](https://ssv.network) is a permissionless DVT network that distributes validator management across a cluster of non-trusting nodes running on multiple machines. The result is active redundancy, fault tolerance, and non-custodial operation. -In this guide, you will: +Each operator runs an **SSV node** — the software that implements the SSV protocol and communicates with the network's smart contracts. It connects to the operator's consensus and execution clients, receives encrypted key shares, and performs validator duties (attestations and proposals) using only a **share** of the validator key: a threshold of shares is enough to produce a valid signature. -1. Generate encrypted operator keys -2. Run your own SSV node -3. Register as an SSV operator -4. Distribute your validator keys to cluster operators +You can run your validators on the SSV Network in two ways, which differ in how the validator key is created: -## Prerequisites +- [Split Keys](/operator/alternative-key-management/dvt/ssv-split-keys) — generate a full validator key, then split it into shares and distribute them to the operators. The Operator Service has access to the full key and uses it to register new validators. +- [DKG Ceremony](/operator/alternative-key-management/dvt/ssv-dkg) — SSV operators generate the key shares together through a ceremony. The full private key is never constructed on any machine, at any point in its lifecycle. The Operator Service has no access to the key shares. The registration of the new validators happens through the DVT Relayer. + +## Become SSV Operator + +If you run your own infrastructure and want to benefit from SSV DVT, you must become an SSV operator. + +Becoming an SSV operator involves generating an operator key, running the node software, and registering the operator through the [SSV webapp ↗](https://app.ssv.network/connect). + +### Prerequisites Before proceeding, ensure you have the following: -1. Install [Docker Engine ↗](https://docs.docker.com/engine/install/) -2. Ensure Docker is running: +1. Install [Docker Engine ↗](https://docs.docker.com/engine/install/). Verify it is running: ```bash docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES ``` -3. [Create Vault →](/operator/create-regular-vault) -4. Operator Service [installed →](/operator/launch-operator-service#installation) - -:::custom-notes[Hardware Requirements] -SSV node requires (in addition to your beacon/execution nodes): **2 cores**, **2GB RAM**, **20GB storage**, **>8K IOPS**. See [full requirements ↗](https://docs.ssv.network/operators/operator-node/node-setup/hardware-requirements). -::: +2. [Create Vault](/operator/create-regular-vault) +3. [Launch Operator Service](/operator/launch-operator-service#installation) -## Become SSV Operator - -To join the SSV network as an operator, you must run an SSV node—the software that implements the SSV protocol and communicates with the network's smart contracts. It connects to your beacon and execution clients, receives encrypted KeyShares, and collaborates with other operators in a DVT cluster to perform validator duties—without ever holding the full private key. - -Becoming an SSV Operator involves generating keys, running the node software, and then registering as an operator through the [SSV webapp ↗](https://app.ssv.network/connect) to start earning rewards. - -While there are different [setup options ↗](https://docs.ssv.network/operators/operator-node/node-setup/#other-setup-options) with the [SSV Stack ↗](https://docs.ssv.network/operators/operator-node/node-setup/) being the most straightforward option, this guide covers **Manual Setup** offering full customization and control. Let's get started rocket. - -### Step 1: Generate Operator Keys (Encrypted) +### Step 1: Generate Operator Keys The most secure way to run your Operator node is to generate an encrypted key pair. This way, your **Public Key** and **Secret Key** will be encrypted with a password of your choosing. -#### Password File +**Password File** -You will need to create a file (named `password` in this example) containing the password you choose for your Secret Key: +You will need to create a file named `password` containing the password you choose for your Secret Key: ```bash echo "" >> password ``` -#### Key Pair Generation and Encryption +**Key Pair Generation and Encryption** -The node Docker image will generate keys for you, then encrypt them with a password you provide, using the following command: +The node Docker image will generate and encrypt keys with a password you provide: ```bash docker run --name ssv-node-key-generation \ @@ -64,7 +57,7 @@ docker run --name ssv-node-key-generation \ && docker rm ssv-node-key-generation ``` -This command will generate `encrypted_private_key.json` containing your encrypted Operator Key and the Public Key needed for registration. +The Docker command outputs `encrypted_private_key.json` to your current directory:
encrypted_private_key.json @@ -80,19 +73,24 @@ This command will generate `encrypted_private_key.json` containing your encrypte
-:::custom-notes[Public Key] -Pay close attention to the **pubkey** field in the output, as it contains the public key needed to register the Operator later on the SSV network. -To extract just the public key value, run: +The file contains your operator's RSA key pair: + +- **Private key** — encrypted with your password; the SSV node uses it to decrypt its assigned validator key shares. +- **Public key** (`pubkey`) — stored in plaintext; you use it to register the operator on SSV. + +To print the `pubkey`, run: + ```bash grep -o '"pubkey":"[^"]*"' encrypted_private_key.json ``` -::: -### Step 2: Run SSV Node +:::custom-warning[Back Up Your Operator Key] +Back up `encrypted_private_key.json` and `password` on a separate device. If either file is lost, you will permanently lose access to your Operator. +::: -#### Create Configuration File +### Step 2: Create Configuration File -Create a `config.yaml` file and replace the placeholders (`ETH2_NODE`, `ETH1_WEBSOCKET_ADDRESS`, `ENCRYPTED_PRIVATE_KEY_JSON`, `PASSWORD_FILE`) with your actual values. +Copy the `config.yaml` file below and replace the placeholders with your real values. Make sure your `ETH1Addr` endpoint uses **WebSocket**, not HTTP.
config.yaml @@ -164,16 +162,10 @@ SSVAPIPort: 16000
-:::custom-warning[WebSocket Required] -Make sure your `ETH1Addr` endpoint is communicating over WebSocket and not over HTTP in order to support subscriptions and notifications. -::: - -#### Start the Node +### Step 3: Start the Node :::custom-warning[Potential Slashing] -Do not run multiple instances of SSV Node with the same set operator keys. - -This does not increase validator resiliency and **could lead to validator slashing** 🔥. +Do not run multiple SSV Node instances with the same operator keys. This does not improve resiliency and could lead to validator slashing. ::: To start your node, run the following Docker command in the same folder you created the `config.yaml` file in the previous step: @@ -188,27 +180,21 @@ CONFIG_PATH=/config.yaml -p 13001:13001 -p 12001:12001/udp -p 15000:15000 -p 160 -it "ssvlabs/ssv-node:latest" make BUILD_PATH="/go/bin/ssvnode" start-node ``` -:::custom-notes[Running in Background] -This command shows container logs to verify startup. Press Ctrl-c to detach—the node will restart automatically due to `--restart unless-stopped`. To run in background, add `-d` after `docker run`. -::: - -#### Peer-to-peer Ports Configuration and Firewall +It launches the SSV node, which connects to your beacon and execution clients, joins the SSV network, and streams its logs to your terminal as it starts up and begins performing duties. -When you set up your firewall on your SSV node machine, make sure to expose the ports that you set in the container creation command. -The defaults are **12001 UDP** and **13001 TCP**. Additional ones are **15000 TCP** for Metrics and **16000 TCP** for Health endpoint. +**Peer-to-peer Ports Configuration and Firewall** -If you don't want to use the default ports, they can be changed in your `config.yaml` file. Be aware, they **must be changed on the container creation command** as well. +On your firewall, open the ports set in the run command: **13001 TCP** and **12001 UDP** for peer-to-peer traffic, plus **15000 TCP** (metrics) and **16000 TCP** (health). To use different ports, change them in both `config.yaml` and the run command. :::custom-notes[Best Practices] -Ensure optimal performance and correctness of your node by following recommendations such as multiple endpoints for failover for EL and CL clients, `./data/db` folder backup, weighted attestation data, parallel submissions, and Doppelganger protection to prevent double-signing. -The complete guide can be found [here ↗](https://docs.ssv.network/operators/operator-node/node-setup/best-practices). +A validator's performance depends on its participation rate — a function of your setup configuration, adequate [hardware resources ↗](https://docs.ssv.network/operators/operator-node/node-setup/hardware-requirements), which scale with the number of validators, and the other [best practices ↗](https://docs.ssv.network/operators/operator-node/node-setup/best-practices) SSV recommends. ::: -### Step 3: Register on SSV Network +### Step 4: Register on SSV Network + +Before your operator can be selected for a cluster, it must be registered on SSV Network. Registration adds it to the registry and gives it an **operator ID** — the identifier you use to select it when distributing a validator to a cluster. -After successfully running an SSV node, an operator must register it to the SSV Network in order to be discoverable by validators. -You'll need your **operator public key** (generated in Step 1) and your desired **operator fee** ([more on fees ↗](https://docs.ssv.network/learn/protocol-overview/tokenomics/fees)). The wallet address you use to register will be the only address with management permissions. -Follow these steps using the SSV Network [web app ↗](https://app.ssv.network): +You'll need your **operator public key** `pubkey` (from Step 1) and a wallet — the wallet you register with becomes the operator's only management address. Follow these steps using the SSV Network [web app ↗](https://app.ssv.network): 1. Click **Join As Operator** @@ -218,7 +204,11 @@ Follow these steps using the SSV Network [web app ↗](https://app.ssv.network): SSV Setup -3. Paste your **Operator Public Key** from the previous step and click **Register Operator** +3. Paste your **Operator Public Key** and click **Register Operator** + +:::custom-info[Private vs. Public] +The operator you registered is meant to run your Vault's validators alongside the other cluster members. By default an operator is **Public** — anyone can register validators to it. To keep other stakers out, switch **Operator Status** to **Private** ([permissioned ↗](https://docs.ssv.network/learn/network-overview/operators/permissioned-operators/)): then only the wallets you whitelist can register validators to it — i.e. assign it a share of a distributed validator. +::: SSV Setup @@ -226,10 +216,6 @@ Follow these steps using the SSV Network [web app ↗](https://app.ssv.network): SSV Setup -:::custom-notes[Operator Fee] -Your fee (in SSV tokens) is charged per validator that selects you. Earnings accumulate in your balance and can be withdrawn anytime. You can update your fee later—decreases take effect immediately, increases require a waiting period to [protect stakers ↗](https://docs.ssv.network/operators/operator-onboarding/update-fee). -::: - 5. Double-check everything and click **Confirm** SSV Setup @@ -237,98 +223,10 @@ Your fee (in SSV tokens) is charged per validator that selects you. Earnings acc SSV Setup -7. Congratulations 🥳. Your Operator is successfully registered, and stakers can now choose it to operate their validators. +7. Congratulations trophy. Your operator is registered and ready to be added to a cluster — select it when you distribute your validators. SSV Setup :::custom-notes[Operator Management] -Once registered, you can apply for the [Verified Operator Program ↗](https://docs.ssv.network/operators/operator-onboarding/verified-operators) to earn this badge Verifiedand signal trustworthiness to stakers. You can also set [operator metadata ↗](https://docs.ssv.network/operators/operator-management/setting-operator-metadata) like description and name, [update fees ↗](https://docs.ssv.network/operators/operator-management/updating-operator-fees), enable [permissioned mode ↗](https://docs.ssv.network/operators/operator-onboarding/permissioned-operators) to restrict validator registration to whitelisted addresses only, and [more ↗](https://docs.ssv.network/operators/operator-management). -::: - -## Split Validator Keys Among Operators - -This section walks you through distributing your StakeWise validator keys to a cluster of SSV operators using the SSV webapp. -The process involves selecting operators, generating encrypted keyshares offline using the CLI, and completing registration through the webapp. - -### Select Operators and Generate Keyshares - -1. Download the ssv-keys CLI for your system from the [releases page ↗](https://github.com/ssvlabs/ssv-keys/releases) - -```bash -# macOS -curl -L https://github.com/ssvlabs/ssv-keys/releases/latest/download/ssv-keys-mac -o ssv-keys -chmod +x ssv-keys # Make the file executable - -# Linux -curl -L https://github.com/ssvlabs/ssv-keys/releases/latest/download/ssv-keys-linux -o ssv-keys -chmod +x ssv-keys -``` - -2. Press **Distribute Validators** -SSV Setup - -3. Select **Generate new key shares** -SSV Setup - -4. Choose the cluster size and operators to run your validator, and click **Next** -SSV Setup - -5. Select the **Offline** method to split your key -SSV Setup - -6. Select **Command Line Interface**, copy the command provided with all values pre-filled (operator keys, IDs, your wallet address, and nonce), and press **Next** -SSV Setup - -7. Run the copied command in your terminal - -```bash -./ssv-keys-mac --operator-keys=LS0tLS1CRUdJTiB... --operator-ids=5,6,7,8 --owner-address=0xf27...10aD9 --owner-nonce=0 -``` - -When prompted, provide: -```bash {11} -✔ Enter the path to your keystore file or directory containing multiple keystore files … /Users/user/.stakewise/0x43aee97f4122b4982915bcfd3d6acd0758fd1b52/keystores/keystore-m_12381_3600_0_0_0-1763993024.json -✔ Provide the keystore file password … ******************** <- type keystores password here -✔ Please provide a target path to generate the output to … /Users/user/ssv-keys/ - -1/1 ✅ keystore-m_12381_3600_0_0_0-1763993024.json - -1 of 1 keystore files successfully validated. 0 failed validation - -Generating Keyshares file, this might take a few minutes do not close terminal. -Key distribution successful! Find your key shares file at: -/Users/user/ssv-keys/keyshares-1763995534.json -``` -This splits your validator key into encrypted shares using Shamir Secret Sharing (SSS), with each share encrypted for a specific operator. - -### Complete Registration - -8. Upload the generated **KeyShares File** -SSV Setup - -9. Click **Next** -SSV Setup - -10. Choose your funding period. The required SSV amount depends on your selected operators' fees and duration. -SSV Setup - -11. Review cluster fees and acknowledge the risks, then click **Next**. -SSV Setup - -:::custom-warning[Liquidation Risk] -Understand [how fees are managed ↗](https://docs.ssv.network/operators/operator-management/updating-operator-fees) and keep your cluster balance above the **Liquidation Collateral** threshold. If liquidated, your validators will stop being operated, which could lead to penalties on the Beacon Chain. [Learn more ↗](https://docs.ssv.network/learn/protocol-overview/tokenomics/liquidations) +You can update your operator's settings — fee, metadata, and more — at any time. See [operator management ↗](https://docs.ssv.network/operators/operator-management). ::: - -:::custom-warning[Critical - Stop Other Validator Clients] -Ensure you have shut down any existing validator clients running this key before proceeding. Running the same validator key on multiple systems simultaneously will result in slashing. -::: -12. Acknowledge the risk and click **Next** -SSV Setup - -13. The next screen presents a summary of your validator setup. -Review transaction details and complete two transactions: - 1. Click **Approve SSV** and confirm in your wallet - 2. Click **Register Validator** and confirm in your wallet -SSV Setup - -14. Congratulations! 🎉 Your validator is now registered on the SSV network and being managed by your selected operators. diff --git a/operator/alternative-key-management/dvt/ssv-split-keys.mdx b/operator/alternative-key-management/dvt/ssv-split-keys.mdx new file mode 100644 index 00000000..ce1e2c79 --- /dev/null +++ b/operator/alternative-key-management/dvt/ssv-split-keys.mdx @@ -0,0 +1,102 @@ +--- +title: Split Keys +description: Distribute an existing StakeWise validator key to a cluster of SSV operators by splitting it into encrypted shares. +--- + +# Split Keys + +You create a full validator key, break it into encrypted pieces (shares), and give them to a group of SSV operators who run the validator for you. You keep the full key. + +This flow suits two kinds of scenarios: + +- **You run the SSV nodes yourself** — you, or a small group, run them across several machines. +- **You'd rather not run any servers** — you pick ready-made operators from the SSV marketplace and pay them in SSV tokens, and they run your validators. + +## Select Operators + +1. In the SSV webapp, open **Run a Distributed Validator**: click **Distribute Validators** on the "Join the SSV Network" landing (new accounts), or go to **Validator Clusters → Create a cluster** if you already have an operator or cluster. + +2. Select **Generate new key shares** +SSV Setup + +3. Choose the cluster size and select your operators, then click **Next**. Search for an operator by **ID** or name. +SSV Setup + +:::custom-warning[Private Operators Must Whitelist You] +A padlock icon next to an operator means it's **private** (permissioned). You can only select it if the wallet you're creating the cluster with is whitelisted in that operator's settings. For your own operators, whitelist your wallet; for third-party private operators, ask them to whitelist you. +::: + +## Generate Key Shares + +4. Download the ssv-keys CLI for your system from the [releases page ↗](https://github.com/ssvlabs/ssv-keys/releases) + +```bash +# macOS +curl -L https://github.com/ssvlabs/ssv-keys/releases/latest/download/ssv-keys-mac -o ssv-keys +chmod +x ssv-keys # Make the file executable + +# Linux +curl -L https://github.com/ssvlabs/ssv-keys/releases/latest/download/ssv-keys-linux -o ssv-keys +chmod +x ssv-keys +``` + +5. Select the **Offline** method to split your key +SSV Setup + +6. Select **Command Line Interface**, copy the command provided with all values pre-filled (operator keys, IDs, your wallet address, and nonce), and press **Next** +SSV Setup + +7. Run the copied command in your terminal + +```bash +./ssv-keys-mac --operator-keys=LS0tLS1CRUdJTiB... --operator-ids=5,6,7,633 --owner-address=0xf27...10aD9 --owner-nonce=0 +``` + +When prompted, provide: +```bash +✔ Enter the path to your keystore file or directory containing multiple keystore files … /Users/user/.stakewise/0x43aee97f4122b4982915bcfd3d6acd0758fd1b52/keystores/keystore-m_12381_3600_0_0_0-1763993024.json +✔ Provide the keystore file password … ******************** <- type keystores password here +✔ Please provide a target path to generate the output to … /Users/user/ssv-keys/ + +1/1 ✅ keystore-m_12381_3600_0_0_0-1763993024.json + +1 of 1 keystore files successfully validated. 0 failed validation + +Generating Keyshares file, this might take a few minutes do not close terminal. +Key distribution successful! Find your key shares file at: +/Users/user/ssv-keys/keyshares-1763995534.json +``` +This splits your validator key into encrypted shares using Shamir's Secret Sharing (SSS), with each share encrypted for a specific operator. + +## Register Validator + +8. Upload the generated **KeyShares File** +SSV Setup + +9. Click **Next** +SSV Setup + +10. Choose your funding period. The required SSV amount depends on your selected operators' fees and duration. +SSV Setup + +11. Review cluster fees and acknowledge the risks, then click **Next**. +SSV Setup + +:::custom-warning[Liquidation Risk] +Understand [how fees are managed ↗](https://docs.ssv.network/operators/operator-management/updating-operator-fees) and keep your cluster balance above the **Liquidation Collateral** threshold. If liquidated, your validators will stop being operated, which could lead to penalties on the Beacon Chain. [Learn more ↗](https://docs.ssv.network/learn/protocol-overview/tokenomics/liquidations) +::: + +12. Acknowledge the risk and click **Next** +SSV Setup + +:::custom-warning[Critical: Stop Other Validator Clients] +Before this final registration, shut down any existing validator client running this key. Once the SSV operators start signing with their shares, running the same key elsewhere will result in slashing. +::: + +13. The next screen presents a summary of your validator setup. +Review transaction details and complete two transactions: + 1. Click **Approve SSV** and confirm in your wallet + 2. Click **Register Validator** and confirm in your wallet +SSV Setup + +14. Congratulations! 🎉 Your validator is now registered on the SSV Network and being managed by your selected operators. diff --git a/sidebarsOperator.ts b/sidebarsOperator.ts index ea387772..86619550 100644 --- a/sidebarsOperator.ts +++ b/sidebarsOperator.ts @@ -43,7 +43,18 @@ const sidebars: SidebarsConfig = { id: 'alternative-key-management/dvt/overview', }, items: [ - 'alternative-key-management/dvt/ssv-setup', + { + type: 'category', + label: 'SSV', + link: { + type: 'doc', + id: 'alternative-key-management/dvt/ssv-setup', + }, + items: [ + 'alternative-key-management/dvt/ssv-split-keys', + 'alternative-key-management/dvt/ssv-dkg', + ], + }, 'alternative-key-management/dvt/obol-setup', ], }, diff --git a/static/img/confirm-tx.png b/static/img/confirm-tx.png index 917675a2..0487b2e3 100644 Binary files a/static/img/confirm-tx.png and b/static/img/confirm-tx.png differ diff --git a/static/img/distribute-validator-keys-1.png b/static/img/distribute-validator-keys-1.png index e6099895..7f1c7f29 100644 Binary files a/static/img/distribute-validator-keys-1.png and b/static/img/distribute-validator-keys-1.png differ diff --git a/static/img/distribute-validator-keys-10.png b/static/img/distribute-validator-keys-10.png index 85755432..01db6009 100644 Binary files a/static/img/distribute-validator-keys-10.png and b/static/img/distribute-validator-keys-10.png differ diff --git a/static/img/distribute-validator-keys-11.png b/static/img/distribute-validator-keys-11.png index 8ffab046..0d3832ac 100644 Binary files a/static/img/distribute-validator-keys-11.png and b/static/img/distribute-validator-keys-11.png differ diff --git a/static/img/distribute-validator-keys-2.png b/static/img/distribute-validator-keys-2.png index dc555b07..de952b0e 100644 Binary files a/static/img/distribute-validator-keys-2.png and b/static/img/distribute-validator-keys-2.png differ diff --git a/static/img/distribute-validator-keys-3.png b/static/img/distribute-validator-keys-3.png index 1a930a72..4403c0e4 100644 Binary files a/static/img/distribute-validator-keys-3.png and b/static/img/distribute-validator-keys-3.png differ diff --git a/static/img/distribute-validator-keys-4.png b/static/img/distribute-validator-keys-4.png index 38ec7645..e1344163 100644 Binary files a/static/img/distribute-validator-keys-4.png and b/static/img/distribute-validator-keys-4.png differ diff --git a/static/img/distribute-validator-keys-5.png b/static/img/distribute-validator-keys-5.png index 4a94deba..0725e8a4 100644 Binary files a/static/img/distribute-validator-keys-5.png and b/static/img/distribute-validator-keys-5.png differ diff --git a/static/img/distribute-validator-keys-6.png b/static/img/distribute-validator-keys-6.png index a61c86e6..3408210a 100644 Binary files a/static/img/distribute-validator-keys-6.png and b/static/img/distribute-validator-keys-6.png differ diff --git a/static/img/distribute-validator-keys-7.png b/static/img/distribute-validator-keys-7.png index 5ce55532..9d33a1ce 100644 Binary files a/static/img/distribute-validator-keys-7.png and b/static/img/distribute-validator-keys-7.png differ diff --git a/static/img/distribute-validator-keys-8.png b/static/img/distribute-validator-keys-8.png index 46b99c32..1dca07ab 100644 Binary files a/static/img/distribute-validator-keys-8.png and b/static/img/distribute-validator-keys-8.png differ diff --git a/static/img/distribute-validator-keys-9.png b/static/img/distribute-validator-keys-9.png index 2c783d42..fd702393 100644 Binary files a/static/img/distribute-validator-keys-9.png and b/static/img/distribute-validator-keys-9.png differ diff --git a/static/img/ssv-setup-1.png b/static/img/ssv-setup-1.png index d6eb268b..6ce2f654 100644 Binary files a/static/img/ssv-setup-1.png and b/static/img/ssv-setup-1.png differ diff --git a/static/img/ssv-setup-2.png b/static/img/ssv-setup-2.png index c4ea2aac..6bc09ecc 100644 Binary files a/static/img/ssv-setup-2.png and b/static/img/ssv-setup-2.png differ diff --git a/static/img/ssv-setup-3.png b/static/img/ssv-setup-3.png index 19d9205a..d93d0697 100644 Binary files a/static/img/ssv-setup-3.png and b/static/img/ssv-setup-3.png differ diff --git a/static/img/ssv-setup-4.png b/static/img/ssv-setup-4.png index 71520739..afe5feaf 100644 Binary files a/static/img/ssv-setup-4.png and b/static/img/ssv-setup-4.png differ diff --git a/static/img/ssv-setup-5.png b/static/img/ssv-setup-5.png index 02a29a0c..cfe6e54a 100644 Binary files a/static/img/ssv-setup-5.png and b/static/img/ssv-setup-5.png differ diff --git a/static/img/ssv-setup-6.png b/static/img/ssv-setup-6.png index 4b5f9279..ff5b1c0d 100644 Binary files a/static/img/ssv-setup-6.png and b/static/img/ssv-setup-6.png differ