Merge pull request #20 from ObolNetwork/oisin/0-4-0

Release version 0.4.0 of docs

docs/dv/01_introducing-charon.md

@@ -4,7 +4,7 @@ description: Charon -  The Distributed Validator Client
 
 # Introducing Charon
 
-This section introduces and outlines the Charon DVT middleware. For additional context regarding distributed validator technology, see [this section](http://localhost:3000/docs/int/key-concepts#distributed-validator) of the key concept page.
+This section introduces and outlines the Charon middleware. For additional context regarding distributed validator technology, see [this section](../int/key-concepts#distributed-validator) of the key concept page.
 
 ### What is Charon?
 
@@ -22,5 +22,5 @@ The below graphic visually outlines the internal functionalies of Charon.
 The `charon` client is in an early alpha state, and is not ready for mainnet, see [here](https://github.com/ObolNetwork/charon#supported-consensus-layer-clients) for the latest on charon's readiness.
 
 ```
-docker run ghcr.io/obolnetwork/charon:v0.3.0 --help
+docker run ghcr.io/obolnetwork/charon:v0.4.0 --help
 ```

docs/dv/02_validator-creation.md

@@ -19,14 +19,14 @@ To create a distributed validator cluster, you and your group of operators need
     - They review the terms of the cluster configuration.
     - The submit the ENR of their charon client.
     - They sign both the hash of the cluster config and their charon ENR to indicate acceptance of the terms 
-3. Once all operators have submitted signatures for the cluster configuration and ENRs, they can all download the cluster manifest file. 
-4. Every operator loads this cluster manifest file into `charon dkg`. The manifest provides the charon process with the information it needs to complete the DKG ceremony with the other charon clients. 
+3. Once all operators have submitted signatures for the cluster configuration and ENRs, they can all download the cluster definition file. 
+4. Every operator loads this cluster definition file into `charon dkg`. The definition provides the charon process with the information it needs to complete the DKG ceremony with the other charon clients. 
 5. Once all charon clients can communicate with one another, the DKG process completes. All operators end up with:
-    - A manifest lockfile, which contains the original cluster configuration data, combined with the newly generated group public keys and their associated threshold verifiers. This file is needed by the `charon run` command. 
+    - A cluster lockfile, which contains the original cluster configuration data, combined with the newly generated group public keys and their associated threshold verifiers. This file is needed by the `charon run` command. 
     - Validator deposit data
     - Validator exit data
     - Validator private key shares 
-6. Operators can now take backups of the generated private key shares and manifest.lock file. 
-7. All operators load the keys and manifests generated in the ceremony, into their staking deployments.
+6. Operators can now take backups of the generated private key shares and definition.lock file. 
+7. All operators load the keys and cluster lockfiles generated in the ceremony, into their staking deployments.
 8. Operators can run a performance test of the configured cluster to ensure connectivity between all operators at a reasonable latency is observed.
 9. Once all readiness tests have passed, one operator activates the distributed validator(s) with an on-chain deposit.

docs/dv/04_middleware-daemon.md

@@ -2,33 +2,16 @@
 description: Deployment Architecture for a Distributed Validator Client
 ---
 
-# Middleware daemon
+# Middleware Architecture
 
-The Charon daemon serves as a consensus layer API middleware and connects to the Obol peer-to-peer network to discover it's counterpart Charon nodes.
+<p align="center"><img src="/img/DistributedValidatorCluster.svg" /></p>
+
+The Charon daemon sits as a middleware between the consensus layer's [beacon node API](https://ethereum.github.io/beacon-APIs/) and any downstream validator clients. 
 
 ### Operation
 
 The middleware strives to be stateless and statically configured through 777 file systems. The lack of a control-plane API for online reconfiguration is deliberate to keep operations simple and secure by default.
 
-A single instance of the middleware can participate in multiple distributed validator clusters. The amount of validators per middleware is bound by risk management and hardware limits (CPU, memory, bandwidth), but there is no hardcoded limit.
-
 The daemon offers a config reload instruction through Unix signals which is useful to join or leave Obol clusters on-the-fly without interruption.
 
 The `charon` package will initially be available as a Docker image and through binary builds. An APT package with a systemd integration is planned.
-
-### Initialization
-
-An instance of Charon requires the following pieces of information at minimum in order to operate.
-
-- A DV cluster manifest file in the to be confirmed EIP format. This file contains the required information a DV client needs for joining a Distributed Validator Cluster. This file includes:
-  - The total number of shares of the key and the required threshold for reconstruction.
-  - An SECP256K1 key pair in an ENR format for Obol consensus messages, this key is signed by the corresponding operators validator key share to legitimise it.
-  - A list of all ENR public keys of other operators participating in the cluster.
-  - The group public keys representing each distributed validator in the cluster to the Ethereum network.
-- Access to an Ethereum Consensus API
-  - It is recommended to run at least one Ethereum Consensus client for each Charon middleware client.
-  - Any [compliant](https://ethereum.github.io/beacon-APIs/) Beacon node implementation should work – try to establish client diversity.
-  - These consensus clients need to be connected to at least one Ethereum Execution clients for block production.
-- The public IP address and port the charon client will operate on
-  - For now, we make the (naive) assumption that the address will be static.
-  - Charon will attempt to auto-discover its address on first use by enumerating network interfaces and using [STUN](https://datatracker.ietf.org/doc/html/rfc5389).

docs/dv/06_peer-discovery.md

@@ -4,36 +4,34 @@ description: How do distributed validator clients communicate with one another s
 
 # Peer discovery
 
-In order to maintain security, middleware clients need to be able to authenticate one another. We achieve this by giving each middleware client something they can use that other clients in the cluster will be able to recognise as legitimate.
+In order to maintain security and sybil-resistance, charon clients need to be able to authenticate one another. We achieve this by giving each charon client a public/private key pair that they can sign with such that other clients in the cluster will be able to recognise them as legitimate no matter which IP address they communicate from.
 
-At the end of a [DVK generation ceremony](./02_validator-creation.md#stages-of-creating-a-distributed-validator), each operator will have a number of files outputted by their CLI program/browser based on how many distributed validators the group chose to generate together.
+At the end of a [DKG ceremony](./02_validator-creation.md#stages-of-creating-a-distributed-validator), each operator will have a number of files outputted by their charon client based on how many distributed validators the group chose to generate together.
 
 These files are:
 
-- **Validator keystore(s):** These files will be loaded into the operator's validator client and each file represents one share of a distributed validator.
-- **A distributed validator cluster manifest:** This file contains the configuration a distributed validator client like charon needs to join a cluster capable of operating a number of distributed validators.
+- **Validator keystore(s):** These files will be loaded into the operator's validator client and each file represents one share of a Distributed Validator.
+- **A distributed validator cluster lock file:** This `cluster.lock` file contains the configuration a distributed validator client like charon needs to join a cluster capable of operating a number of distributed validators.
+- **Validator deposit and exit data:** These files are used to activate and deactivate (exit) a distributed validator on the Ethereum network. 
 
 ### Authenticating a distributed validator client
 
-During the final stage of the DVK ceremony, after the validator key shares are generated for each operator, the ceremony program will generate a random SECP256K1 key pair to be used by a Charon client for its ENR. The program will sign this ENR public key with every keystore this validator will service, to indicate to all other operators that this randomly generated key is directly authorised by the current operator to communicate at the consensus layer for their distributed validator key shares.
+Before a DKG process begins, all operators must run `charon create enr`, or just `charon enr`, to create or get the Ethereum Node Record for their client. These ENRs are included in the configuration of a key generation ceremony. 
 
-This sensitive ENR private key, and the general configuration of the distributed validator cluster will be the outputs of a DVK ceremony known shorthand as a `cluster manifest`.
+The file that outlines a DKG ceremony is known as a [`cluster_definition`](./08_distributed-validator-cluster-manifest.md) file. This file is passed to `charon dkg` which uses it to create private keys, a cluster lock file and deposit and exit data for the configured number of distributed validators. The cluster.lock file will be made available to `charon run`, and the validator key stores will be made available to the configured validator client. 
 
-This manifest file will be made available to a charon client, and the validator key stores will be made available to the configured validator client. When charon starts up and ingests its configuration from the manifest file, it will use the provided keypair for its ENR. If it's configured IP address is different from what is embedded in the ENR to begin with, it reissues the ENR as needed and begins to establish connections with the other operators in the cluster as recorded in the manifest file.
+When `charon run` starts up and ingests its configuration from the `cluster.lock` file, it checks if it's observed/configured public IP address differs from what is listed in the lock file. If it is different; it updates the IP address, increments the nonce of the ENR and reissues it before beginning to establish connections with the other operators in the cluster.
 
 #### Node database
 
-Obol DV clusters are permissioned networks with a fully meshed topology. Each node will permanently store the ENRs of all other known Obol nodes in their node database.
+Distributed Validator Clusters are permissioned networks with a fully meshed topology. Each node will permanently store the ENRs of all other known Obol nodes in their node database.
 
-Unlike with node databases of public permissionless networks (such as [Go-Ethereum](https://pkg.go.dev/github.com/ethereum/[email protected]/p2p/enode#DB)), there is no inbuilt eviction logic – the database will keep growing indefinitely.
+Unlike with node databases of public permissionless networks (such as [Go-Ethereum](https://pkg.go.dev/github.com/ethereum/[email protected]/p2p/enode#DB)), there is no inbuilt eviction logic – the database will keep growing indefinitely. This is acceptable as the number of operators in a cluster is expected to stay constant. Mutable cluster operators will be introduced in future. 
 
 #### Node discovery
 
-In early versions of Charon, operator nodes will be seeded in the node database from cluster manifest files. Updates to the node database can be made in realtime as a Charon client receives messages from these authorised ENRs containing a higher nonce value than present in our node database, usually representing an IP address update.
+At boot, a charon client will ingest it's configured `cluster.lock` file. This file contains a list of ENRs of the client's peers. The client will attempt to establish a connection with these peers, and will perform a handshake if they connect. 
 
-In the future, Charon is intended to discover counterparty nodes using the [discv5](https://github.com/ethereum/devp2p/blob/master/discv5/discv5.md) protocol. All DVCs connecting to the Obol Network will join a public node discovery peer-to-peer network to find the latest ENR records for their DV peers.
+However, the IP addresses within an ENR can become stale. This could result in a cluster not being able to establish a connection with all nodes. To be tolerant to operator IP addresses changing, charon also supports the [discv5](https://github.com/ethereum/devp2p/blob/master/discv5/discv5.md) discovery protocol. This allows a charon client to find another operator that might have moved IP address, but still retains the same ENR private key.
 
-This dynamic discovery serves two purposes:
 
-- Bootstrapping a node database in the event of data loss when peers no longer listen on the IP addresseses specified in the manifest and need to be located.
-- Periodically refreshing ENRs to follow IP address changes, e.g. AWS EC2 IPs or NAT on residential broadband.

docs/dv/07_p2p-interface.md

@@ -7,5 +7,7 @@ description: Connectivity between Charon instances
 The Charon P2P interface loosely follows the [Eth2 beacon P2P interface](https://github.com/ethereum/consensus-specs/blob/dev/specs/phase0/p2p-interface.md).
 
 - Transport: TCP over IPv4/IPv6.
+- Identity: [Ethereum Node Records](https://eips.ethereum.org/EIPS/eip-778). 
 - Handshake: [noise-libp2p](https://github.com/libp2p/specs/tree/master/noise) with `secp256k1` keys.
-  - Nodes must have their keys authorized in a [cluster manifest](./08_distributed-validator-cluster-manifest.md) in order for the handshake to succeed.
+  - Each charon client must have their ENR public key authorized in a [cluster.lock](./08_distributed-validator-cluster-manifest.md) file in order for the client handshake to succeed.
+- Discovery: [Discv5](https://github.com/ethereum/devp2p/blob/master/discv5/discv5.md).