WIP: First pass at adding to glossary and readme

README.md

@@ -7,27 +7,31 @@ Distributed Validators (DV) are a technique for distributing the job of an Ether
 ### Motivation
 
 #### Traditional Validator Client Setup
+
 Ethereum validators participate in the [proof-of-stake (PoS) protocol](https://github.com/ethereum/consensus-specs) by signing messages (such as blocks or attestations) using their staking private key. The staking key is accessible only by the validator client software, which schedules the creation & signing of messages according to the duties assigned to the validator. Some risks involved in a traditional validator client setup are:
+
 - The staking private key resides in one location. If an adversary gains access to this key, it can create conflicting messages that result in slashing of the validator's deposit.
-    - Stakers who do not operate their own validator need to hand over their staking private key to the operator. They must trust the operator for the security of their staking private key.
+  - Stakers who do not operate their own validator need to hand over their staking private key to the operator. They must trust the operator for the security of their staking private key.
 - If the validator client software is unable to create timely messages to perform validator duties, the validator suffers an inactivity leak that reduces its balance.
-    - This could happen due to causes such as software crashes, loss of network connection, hardware faults, etc.
+  - This could happen due to causes such as software crashes, loss of network connection, hardware faults, etc.
 - If the Beacon Node to which the validator client is connected has a fault, a validator may end up following a minority fork resulting it appearing to be offline to the rest of the PoS protocol.
 
 #### Distributed Validator Protocol
+
 The Distributed Validator protocol presents a solution to mitigate the risks & concerns associated with traditional, single Validator Client setups. In addition, this protocol can be used to enable advanced staking setups such as decentralized staking pools.
 
 ### Basic Concepts
 
 **Note**: Refer to the [glossary](glossary.md) for an explanation of new terms introduced in the Distributed Validator specifications.
 
 The two fundamental concepts behind Distributed Validators are:
-- **consensus**: the responsibilities of a single validator are split among several co-validators, who must work together to reach agreement on how to vote before signing any message.
-- ***M-of-N* threshold signatures**: the validator's staking key is split into *N* pieces and each of the co-validators holds a share. When at least *M* of the co-validators reach consensus on how to vote, they each sign the message with their share and a combined signature can be reconstructed from the shares.
 
-Ethereum proof-of-stake uses the BLS signature scheme, in which the private keys can be *M-of-N* secret-shared (using Shamir secret sharing) to implement *M-of-N* threshold signatures.
+- **consensus**: the responsibilities of a single validator are split among several operators, who must work together to reach agreement on how to vote before signing any message.
+- **_M-of-N_ threshold signatures**: the validator's staking key is split into _N_ pieces and each of the operators holds a share. When at least _M_ of the operators reach consensus on how to vote, they each sign the message with their share and a combined signature can be reconstructed from the shares.
+
+Ethereum proof-of-stake uses the BLS signature scheme, in which the private keys can be _M-of-N_ secret-shared (using Shamir secret sharing) to implement _M-of-N_ threshold signatures.
 
-By combining a suitable (safety-favouring) consensus algorithm with an *M-of-N* threshold signature scheme, the DV protocol ensures that agreement is backed up by cryptography and at least *M* co-validators agree about any decision.
+By combining a suitable (safety-favouring) consensus algorithm with an _M-of-N_ threshold signature scheme, the DV protocol ensures that agreement is backed up by cryptography and at least _M_ operators agree about any decision.
 
 ### Resources
 
@@ -37,33 +41,58 @@ The following are existing implementations of Distributed Validator technology (
 
 - [`python-ssv`](https://github.com/dankrad/python-ssv): A proof-of-concept implementation of the distributed validator protocol in Python that interacts with the [Prysm Ethereum client](https://github.com/prysmaticlabs/prysm).
 - [`ssv`](https://github.com/bloxapp/ssv): An implementation of the distributed validator protocol in Go that interacts with the [Prysm Ethereum client](https://github.com/prysmaticlabs/prysm).
+- [`charon`](https://github.com/ObolNetwork/charon): An implementation of the protocol in Go that supports all clients that can validate over the [Beacon RESTful APIs](https://ethereum.github.io/beacon-APIs/#/ValidatorRequiredApi)
 
 #### Documents
+
 - [Distributed Validator Architecture Video Introduction](https://www.youtube.com/watch?v=awBX1SrXOhk)
 
 ### General Architecture
 
 ![General Architecture](figures/general-architecture.png)
 
 This specification presents a way to implement Distributed Validator Client software as middleware between the Beacon Node (BN) and Validator Client (VC):
+
 - all communication between the BN and VC is intercepted by the DVC in order for it to provide the additional DV functionality.
 - the BN & VC are unaware of the presence of the DVC, i.e., they think they are connected to each other as usual.
 
 ### Assumptions
-- We assume *N* total nodes and an *M-of-N* threshold signature scheme.
-    - For general compatibility with BFT consensus protocols, we assume that `M = (2 * N / 3) + 1`.
-- This specification assumes [some leader-based safety-favoring consensus protocol](src/dvspec/consensus.py) for the Co-Validators to decide on signing upon the same attestation/block. We assume that the consensus protocol runs successfully with *M* correct nodes out of *N* total nodes.
+
+- We assume _N_ total nodes and an _M-of-N_ threshold signature scheme.
+  - For general compatibility with BFT consensus protocols, we assume that `M = (2 * N / 3) + 1`.
+- This specification assumes [some leader-based safety-favoring consensus protocol](src/dvspec/consensus.py) for the operators to decide on signing upon the same attestation/block. We assume that the consensus protocol runs successfully with _M_ correct nodes out of _N_ total nodes.
 - We assume the usual prerequisites for safe operation of the Validator Client, such as an up-to-date anti-slashing database, correct system clock, etc.
-- We disregard the voting on the "correct" Ethereum fork for now - this functionality will be added in a future update.
+- We disregard voting on the "correct" Ethereum fork for now - this functionality will be added in a future update.
 
 ### Desired Guarantees
+
 - **Safety (against key theft)**:
-    - The Validator's staking private key is secure unless security is compromised at more than *M* of the *N* Co-Validators.
-- **Safety (against slashing)**: 
-    - Under the assumption of an asynchronous network, the Validator is never slashed unless more than 1/3rd of the Co-Validators are Byzantine.
-    - Under the assumption of a synchronous network, the Validator is never slashed unless more than 2/3rds of the Co-Validators are Byzantine.
-- **Liveness**: The protocol will eventually produce a new attestation/block under partially synchronous network unless more than 1/3rd of the Co-Validators are Byzantine.
+  - The Validator's staking private key is secure unless security is compromised at more than _M_ of the _N_ operators.
+- **Safety (against slashing)**:
+  - Under the assumption of an asynchronous network, the Validator is never slashed unless more than 1/3rd of the operators are Byzantine.
+  - Under the assumption of a synchronous network, the Validator is never slashed unless more than 2/3rds of the operators are Byzantine.
+- **Liveness**: The protocol will eventually produce a new attestation/block under partially synchronous network unless more than 1/3rd of the operators are Byzantine.
 
 ## Specification
 
 Technical details about the specification are described in [`src/dvspec/`](src/dvspec/).
+
+## Developer Getting Started
+
+This repo relies on [Python](https://www.python.org/), and uses [venv](https://docs.python.org/3/library/venv.html) to manage its dependencies.
+
+To get started with this repo using [make](https://www.gnu.org/software/make/manual/make.html), run the following commands:
+
+```sh
+# Create virtual environment, download dependencies
+make install
+
+# Lint the specs
+make venv_lint
+
+# Execute the spec tests
+make venv_test
+
+# Get help
+make help
+```

glossary.md

@@ -4,18 +4,37 @@
 
 - **Validator**: A public key participating in proof-of-stake validation of Ethereum. In Phase 0, validators are expected to perform attestation & block proposal duties for beacon chain blocks.
 - **Validator Client (VC)**: Software to perform the duties of Validators. The VC has access to the private key of the Validators.
+- **Consensus Client (CC)**: A consensus client's duty is to run the proof of stake consensus layer of Ethereum, often referred to as the beacon chain. Examples of Consensus clients include:
+
+  - [Prysm](https://docs.prylabs.network/docs/how-prysm-works/beacon-node)
+  - [Teku](https://docs.teku.consensys.net/en/stable/)
+  - [Lighthouse](https://lighthouse-book.sigmaprime.io/api-bn.html)
+  - [Nimbus](https://nimbus.guide/)
+  - [Lodestar](https://github.com/ChainSafe/lodestar)
+
+- **Execution Client (EC)**: An execution client (formerly known as an Eth1 client) specialises in running the EVM and managing the transaction pool for the Ethereum network. These clients provide execution payloads to consensus clients for inclusion into blocks. Examples of execution clients include:
+
+  - [Go-Ethereum](https://geth.ethereum.org/)
+  - [Nethermind](https://docs.nethermind.io/nethermind/)
+  - [Erigon](https://github.com/ledgerwatch/erigon)
 
 ## Distributed Validator Concepts
 
-- **Distributed Validator (DV)**: A group of participants collboratively performing the duties of a Validator. The Validator's private key is secret-shared among the participants so that a complete signature cannot be formed without some majority threshold of participants.
-- **Co-Validator**: A threshold BLS public key participating in the DV protocol for a *particular* Validator.
-- **Distributed Validator Client (DVC)**: Software to participate as a Co-Validator by running the DV protocol (or, to participate as multiple Co-Validators that are each associated with a different Validator). The DVC has access to the private key(s) of the Co-Validator(s), which is(are) the secret-shared threshold private key of the respective Validator(s).
+- **Distributed Validator (DV)**: A group of participants collboratively performing the duties of a single Validator on the Ethereum network. The Validator's private key is secret-shared among the participants so that a complete signature cannot be formed without some majority threshold of participants.
+- **Distributed Validator Client (DVC)**: Software to participate as an operator of one or more distributed validators by running the DV protocol. The DVC has access to an SECP256K1 key that serves as its authentication to its peers, along with a distributed validator client certificate, which authorises this DVC to act on behalf of a given distributed validator key share.
+- **Distributed Validator Node**: A distributed validator node is the set of clients an operator needs to configure and run to fulfil the duties of a Distributed Validator Operator. An operator may also run redundant execution and consensus clients, an execution payload relayer like [mev-boost](https://github.com/flashbots/mev-boost), or other monitoring or telemetry services on the same hardware to ensure optimal performance.
+- **Distributed Validator Cluster**: A distributed validator cluster is a collection of distributed validator nodes connected together to service a set of distributed validators generated during a DVK ceremony.
+- **Distributed Validator Key**: A distributed validator key is one persistent BLS public key emulated by a group of distributed validator key shares completing threshold signing together.
+- **Distributed Validator Key Share**: A distributed validator key share is one BLS private key that is part of the collection of shares that together can sign on behalf of the group distributed validator public key.
+- **Distributed Validator Key Generation Ceremony**: A distributed key generation ceremony where a number of parties can come together to trustlessly create a distributed validator key, its associated deposit and exit data, and each parties' distributed validator key share and DVC certificate.
+- **Distributed Validator Client Certificate**: A distributed validator client communicates across the internet to connect to its counterparty peers. However each DVC needs a means of authenticating its counterparties, and confirming they have the authorisation to act on behalf of a given key share. A DVC authenticates itself to its peers with an SECP256K1 key pair. Secondly, it proves it has the authorisation to act on behalf of a given key share by presenting a signed message from its key share, known as a DVC certificate.
 
 ## Example
 
 An illustrative example for usage of terms described above:
+
 - Ethereum Validator with pubkey `0xa5c91...` is operated as a Distributed Validator.
-- 4 Co-Validators are participating in the Distributed Validator for Validator `0xa5c91...`. 
-- The private key associated with `0xa5c91...` is split using *3-of-4* secret-sharing among the 4 Co-Validators such that a *3-of-4* threshold signature scheme is setup.
-    - In simpler terms, the private key for `0xa5c91...` is split into 4 pieces, each in the custody of one of the Co-Validators such that at least 3 of them have to collaborate to produce a signature from `0xa5c91...`.
-- Each Co-Validator is running the Distributed Validator Client software to participate the in the Distributed Validator.
+- 4 Operators are participating in the Distributed Validator Cluster for Validator `0xa5c91...`.
+- The private key associated with `0xa5c91...` was generated during a distributed validator key generation ceremony using _3-of-4_ secret-sharing among the 4 operators such that a _3-of-4_ threshold signature scheme is setup.
+  - In simpler terms, the private key for `0xa5c91...` is split into 4 pieces, each in the custody of one of the operators such that at least 3 of them have to collaborate to produce a signature from `0xa5c91...`.
+- Each operator is running a Distributed Validator Node to participate the in the Distributed Validator Cluster.

src/dvspec/README.md

@@ -3,9 +3,9 @@
 ## Organization
 
 The specifications are organized as follows:
-- [`spec.py` - distributed validator specification](spec.py) defines the behavior of a Co-Validator regarding attestation & block production processes.
+- [`spec.py` - distributed validator specification](spec.py) defines the behavior of a distributed validator client regarding attestation & block production processes.
 - [`eth_node_interface.py` - Ethereum node interface](eth_node_interface.py) describes the interface to communicate with the associated Beacon Node (BN) & Validator Client (VC).
-- [`consensus.py` - consensus specification](consensus.py) describes the basic structure for the consensus protocol used between Co-Validators.
+- [`consensus.py` - consensus specification](consensus.py) describes the basic structure for the consensus protocol used between DVCs.
 - [`networking.py` - networking specification](networking.py) defines the required networking logic between Distributed Validator Clients.
 - [`utils/` - utilities](utils/) contain type definitions and misc. helper functions for the specification.
 
@@ -20,9 +20,9 @@ The basic operation of the DVC is as follows:
 1. Request duties from the BN at the start of every epoch
 2. Schedule serving of the received duties at the appropriate times
 3. Serve a duty when triggered by:
-    1. Forming consensus with other Co-Validators over the data to be signed
+    1. Forming consensus with other operators over the data to be signed
     2. Caching the decided data to provide to the VC's request for data to be signed for this duty, and responding to the VC's request using the cached data
-    3. Capturing the threshold signed data from the VC's response and broadcasting it to other Co-Validators
+    3. Capturing the threshold signed data from the VC's response and broadcasting it to other Distributed Validator Client peers
     4. Re-combination of threshold signed data after receiving enough threshold signed data shares
 
 ### Anti-Slashing Measures at the DVC