Merge pull request #12 from ethereum/describe-dvc-slashing-db

Describe DVC slashing DB

Author: CarlBeek

README.md

@@ -19,21 +19,21 @@ The Distributed Validator protocol presents a solution to mitigate the risks & c
 
 ### 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 to implement *M-of-N* threshold signatures.
 
-**Note**: Refer to the [glossary](glossary.md) for an explanation of new terms introduced in the Distributed Validator specifications.
-
 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.
 
 ### Resources
 
 #### Implementations
 
-The following are existing implementations of DIstributed Validator technology (but not necessarily implementations of this specification).
+The following are existing implementations of Distributed Validator technology (but not necessarily implementations of this specification).
 
 - [`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).
@@ -64,18 +64,6 @@ This specification presents a way to implement Distributed Validator Client soft
     - Under the assumption of a synchronous network, the Validator is never slashed unless more than 1/3rd 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.
 
-## Spec
-
-The specifications are organized as follows:
-- The [distributed validator specification](src/dvspec/spec.py) defines the behavior of a Co-Validator regarding attestation & block production processes.
-- The [Ethereum node interface](src/dvspec/eth_node_interface.py) describes the interface to communicate with the associated Beacon Node & Validator Client.
-- The [consensus specification](src/dvspec/consensus.py) describes the basic structure for the consensus protocol used between Co-Validators.
-- The [networking specification](src/dvspec/networking.py) defines the required networking logic between Distributed Validator Clients.
-
-### Attestation Production Process
-
-![UML for Attestation Production Process](figures/dv-attestation-production-process.png)
-
-### Block Production Process
+## Specification
 
-![UML for Block Production Process](figures/dv-block-production-process.png)
+Technical details about the specification are described in [`src/dvspec/`](src/dvspec/).

src/dvspec/README.md

@@ -0,0 +1,47 @@
+# Ethereum Distributed Validator Specification
+
+## 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.
+- [`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.
+- [`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.
+
+## Operation of Distributed Validator Client (DVC)
+
+### Communication between DVC and VC
+The BN & VC communicate over HTTP in accordance with the [Ethereum Beacon Node API](https://github.com/ethereum/beacon-APIs/). The DV protocol is designed such that the DVC can operate as middleware between the BN & VC. Both the BN & VC are unaware of the presence of the DVC - they communicate with the DVC as they would with each other.
+
+The [interaction between the BN & VC](https://github.com/ethereum/beacon-APIs/blob/master/validator-flow.md) is driven by the VC, i.e., the VC starts the interaction by making the appropriate request at the BN's HTTP server. In this way, the VC never accepts incoming requests and does not host a server. The lack of a server prevents the DVC from instructing the VC to sign data whenever consensus is formed for a duty's data. The DVC instead caches the decided data for the duty, and responds to the VC's request for the duty's data using the cached value. If the DVC has not formed consensus over a duty's data when the VC makes a request for that duty's data, the HTTP request is "hung" until consensus is formed. This can be supported by the VC with appropriate parameter changes in the HTTP request it makes, without any implementation changes.
+
+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
+    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
+    4. Re-combination of threshold signed data after receiving enough threshold signed data shares
+
+### Anti-Slashing Measures at the DVC
+VCs have an in-built slashing protection mechanism called the "slashing database" (a misnomer for "anti-slashing database"). The slashing database stores information about the messages that have been signed by the Validator. When new messages are to be signed, they are first checked against the slashing DB to ensure that a slashable pair of messages will not be produced (see - slashing rules for [attestations](https://github.com/ethereum/consensus-specs/blob/master/specs/phase0/beacon-chain.md#is_slashable_attestation_data) & [blocks](https://github.com/ethereum/consensus-specs/blob/master/specs/phase0/beacon-chain.md#proposer-slashings)). 
+
+While forming consensus over data, it is essential for the DVC to check the validity of the data against this slashing DB. However, since the DVC does not have direct access to the VC's slashing DB, it has to maintain a local cache of its state. The slashing DB at the DVC operates as follows:
+1. When initializing the setup, the DVC requires input about the state of the VC's slashing DB. When provided, the DVC will initialize a local slashing DB of its own with the given state.
+2. While forming consensus, the DVC checks that the proposed consensus value is not slashable against its slashing DB.
+3. When a consensus value is decided, the DVC adds the value to its slashing DB.
+
+The initialization process can be carried out without change to the VC: with the VC and DVC shut down, manually export the VC's slashing DB and import it in the DVC. Automatic initialization of the DVC is not possible without changes to the VC implementation (this is a WIP feature in active discussion).
+
+
+## Sequence Diagrams
+
+### Attestation Production Process
+
+![UML for Attestation Production Process](figures/dv-attestation-production-process.png)
+
+### Block Production Process
+
+![UML for Block Production Process](figures/dv-block-production-process.png)