diff --git a/docs/configuration.md b/docs/configuration.md index 170070e2f..e876f704a 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -6,7 +6,7 @@ This document describes the configuration options for running a charon node and A charon cluster is configured in two steps: - `cluster-definition.json` which defines the intended cluster configuration without validator keys. -- `cluster-lock.json` which includes and extends `cluster-definition.json` with distributed validator bls public key shares. +- `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`. @@ -33,8 +33,12 @@ The schema of the `cluster-definition.json` is defined as: "timestamp": "2022-01-01T12:00:00+00:00", // Creation timestamp "num_validators": 100, // Number of distributed validators (n*32ETH staked) to be created in cluster.lock "threshold": 3, // Threshold required for signature reconstruction - "fee_recipient_address":"0x123..abfc", // ETH1 fee recipient address - "withdrawal_address": "0x123..abfc", // ETH1 withdrawal address + "validators": [ // Metadata related to each validator to be created + { + "fee_recipient_address":"0x123..abfc", // ETH1 fee recipient address + "withdrawal_address": "0x123..abfc" // ETH1 withdrawal address + } + ], "dkg_algorithm": "foo_dkg_v1" , // DKG algorithm for key generation "fork_version": "0x00112233", // Chain/network identifier "config_hash": "0xabcfde...acbfed", // Hash of the initial configuration fields excluding operator ENRs and signatures @@ -58,21 +62,34 @@ The `cluster-lock.json` has the following schema: "distributed_validators": [ // Length equal to num_validators (n*32ETH staked). { "distributed_public_key": "0x123..abfc", // DV root pubkey - "public_shares": [ "0x123..abfc", "0x123..abfc"], // The public share of each operator (length of num_operators) - "fee_recipient": "0x123..abfc" // Fee recipient address of this validator. Defaults to definition fee_recipient if empty. + "public_shares": ["0x123..abfc", "0x123..abfc"], // The public share of each operator (length of num_operators) + "deposit_data": {...}, // Deposit data to activate this validator + "builder_registration": {...} // Pre-generated signed builder registration for the validator } ], "lock_hash": "0xabcdef...abcedef", // Hash of the cluster definition and distributed validators. Uniquely identifies a cluster lock. - "signature_aggregate": "0xabcdef...abcedef" // BLS aggregate signature of the lock hash signed by all the key shares of all the distributed validators. Proves that the key shares exist and attested to being part of this cluster. + "signature_aggregate": "0xabcdef...abcedef", // BLS aggregate signature of the lock hash signed by all the key shares of all the distributed validators. Proves that the key shares exist and attested to being part of this cluster. + "node_signatures": ["0xabcdef...abcedef"] // Signatures of the lock hash by each operator. Proves that this lock file (and the validators) was generated by all the operators } ``` -`charon run` just requires a `cluster-lock.json` file to configure the cluster. +`charon run` just requires a `cluster-lock.json` file to configure the cluster. See the [cluster.DepositData](../cluster/deposit.go) and [cluster.BuilderRegistration](../cluster/registration.go) Go structs for more details +on how the an individual `distributed_validator` looks like. ### Cluster Config Change Log The following is the historical change log of the cluster config: -- `v1.4.0` **default**: +- `v1.7.0` **default**: + - Added the `builder_registration` structure to `distributed_validators` list in cluster lock. + - This enables distributed validators to submit pre-generated validator registrations that enables MEV-blocks. + - Added the `node_signatures` list to cluster lock which contains signatures of the lock hash signed by each individual node. +- `v1.6.0`: + - Add `deposit_data` structure to `distributed_validators` list in cluster lock. + - This allows anyone with access to the lock file to activate the validators, specifically, the **creator**. +- `v1.5.0`: + - Add the `validators` list to cluster definition that contains `fee_recipient_address` & `withdrawal_address` for each validator. + - This allows configuring multiple fee recipient and withdrawal addresses instead of a single address for all validators. +- `v1.4.0`: - Added the `creator` nested structure to the cluster definition proving who created the cluster definition (including non-operators). - Refactored operator `config_signature` EIP712 structure to distinguish between operator and creator `config_signatures`. - `v1.3.0`: