Skip to main content

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 ↗ 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.

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.

IconMinimum 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 ↗ or equivalent machine dedicated to DKG.
  • Recommended: an AWS t3.large or higher tier.

Minimum Docker resource allocation:

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:
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
  1. Start the service:
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
IconExpose 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​

IconWebapp or CLI

This guide uses the SSV webapp ↗, 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 ↗.

  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
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 <YOUR_SSV_WALLET> --nonce <NONCE> \
  --withdrawAddress <YOUR_VAULT_ADDRESS> \
  --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 ↗.

The ceremony writes a ceremony-<timestamp>/ directory with keyshares.json, deposit_data.json, and proofs.json:

Ceremony output
ceremony-<timestamp>/
├─ <nonce>-0x<validator public key>/
│  ├─ 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 ↗.

IconKeep 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 SSV 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 as Split Keys.

Step 4: Run the DVT Sidecar​

Each operator runs one DVT 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:
cp .env.example .env
  1. Set the values for your SSV operator:
# 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
  1. Run the container:
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 ↗ 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:
cp .env.example .env

  1. 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. 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.

  2. Set the values (file paths point inside the mounted /data):

# 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
  1. Pull and run the Relayer:
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:

./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.

Last updated on