Skip to main content
Version: v0.6.0

Cluster Configuration

warning

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 Configuration Files

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 which includes and extends cluster_definition.json with distributed validator bls public key shares and verifiers.

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:

{
"version": "v1.0.0", // Schema version
"num_validators": 100, // Number of validators to create in cluster.lock
"threshold": 3, // Optional threshold required for signature reconstruction
"uuid": "1234-abcdef-1234-abcdef", // Random unique identifier
"name": "best cluster", // Optional name field, cosmetic.
"fee_recipient_address":"0x123..abfc",// ETH1 fee_recipient address
"withdrawal_address": "0x123..abfc", // ETH1 withdrawal address
"algorithm": "foo_dkg_v1" , // Optional DKG algorithm
"fork_version": "0x00112233", // Fork version lock, enum of known values
"operators": [
{
"address": "0x123..abfc", // ETH1 operator identify address
"enr": "enr://abcdef...12345", // charon client ENR
"signature": "123456...abcdef", // Signature of enr by ETH1 address priv key
"nonce": 1 // Nonce of signature
}
],
"definition_hash": "abcdef...abcedef",// Hash of above field (except free text)
"operator_signatures": [ // Operator signatures (seals) of definition hash
"123456...abcdef",
"123456...abcdef"
]
}

The above cluster_definition.json is provided as input to the DKG which generates keys and the cluster_lock.json file.

The cluster_lock.json has the following schema:

{
"cluster_definition": {...}, // Cluster definiition json, identical schema to above,
"distributed_validators": [ // Length equaled to num_validators.
{
"distributed_public_key": "0x123..abfc", // DV root pubkey
"threshold_verifiers": [ "oA8Z...2XyT", "g1q...icu"], // length of threshold
"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.
}