Skip to main content
Version: Next

Cluster Configuration

caution

These cluster definition and cluster lock files are a work in progress. The intention is for the files to be standardised for operating distributed validators via the EIP process when appropriate.

This document describes the configuration options for running a charon client (or cluster) locally or in production.

Cluster Definition File

A charon cluster is configured in two steps:

  • cluster-definition.json which defines the intended cluster configuration before keys have been created in a distributed key generation ceremony.
  • cluster-lock.json which includes and extends cluster-definition.json with distributed validator BLS public key shares.

The charon create dkg command is used to create cluster-definition.json file which is used as input to charon dkg.

The charon create cluster command combines both steps into one and just outputs the final cluster-lock.json without a DKG step.

The schema of the cluster-definition.json is defined as:

{
"name": "best cluster", // Optional cosmetic identifier
"operators": [
{
"address": "0x123..abfc", // ETH1 address of the operator
"enr": "enr://abcdef...12345", // Charon node ENR
"config_signature": "0x123456...abcdef", // EIP712 Signature of config_hash by ETH1 address priv key
"enr_signature": "0x123654...abcedf" // EIP712 Signature of ENR by ETH1 address priv key
}
],
"uuid": "1234-abcdef-1234-abcdef", // Random unique identifier.
"version": "v1.2.0", // Schema version
"timestamp": "2022-01-01T12:00:00+00:00", // Creation timestamp
"num_validators": 100, // Number of distributed validators to be created in cluster-lock.json
"threshold": 3, // Optional threshold required for signature reconstruction
"fee_recipient_address": "0x123..abfc", // ETH1 fee_recipient address
"withdrawal_address": "0x123..abfc", // ETH1 withdrawal address
"dkg_algorithm": "foo_dkg_v1", // Optional DKG algorithm for key generation
"fork_version": "0x00112233", // Chain/Network identifier
"config_hash": "abcfde...acbfed", // Hash of the static (non-changing) fields
"definition_hash": "abcdef...abcedef" // Final hash of all fields
}

The above cluster-definition.json is provided as input to the DKG which generates keys and the cluster-lock.json file.

Cluster Lock File

The cluster-lock.json has the following schema:

{
"cluster_definition": {...}, // Cluster definiition json, identical schema to above,
"distributed_validators": [ // Length equal to cluster_definition.num_validators.
{
"distributed_public_key": "0x123..abfc", // DV root pubkey
"public_shares": [ "abc...fed", "cfd...bfe"], // Length equal to cluster_definition.operators
"fee_recipient": "0x123..abfc" // Defaults to withdrawal address if not set, can be edited manually
}
],
"lock_hash": "abcdef...abcedef", // Config_hash plus distributed_validators
"signature_aggregate": "abcdef...abcedef" // BLS aggregate signature of the lock hash signed by each DV pubkey.
}