Documentation #496
Documentation #496
Conversation
MatheusFranco99
added
the
documentation
| - there's a connection to a **Beacon node** that provides duties' related data (e.g. an attestation vote) and allows the node to submit signed data to the blockchain. | ||
| - there's a connection to the **Beacon network** that provides information about the blockchain (e.g. the current slot and fork version). |
There was a problem hiding this comment.
Seems Beacon network isn't even mentioned in this document ... and it kind of begs the question of how Beacon network is different from Beacon node. Plus (from what I've gathered in the code) Beacon network is just a bunch of data pulled together (and a bunch of functions that compute something on that data) - which is quite a low level implementation detail that isn't desirable to have in high-level overview docs anyway.
So, I would just probably omit the whole section:
- there's a connection to the Beacon network that provides information about the blockchain (e.g. the current slot and fork version).
| Within the duty's slot, thhe time at which the operators should start the duty depends on the duty type. | ||
|
|
||
| - For the Proposer duty, the protocol should be executed as soon as the slot starts (so no delay). | ||
| - For the Attestation and Sync Committee duties, the protocol should be executed after one third (1/3) of the slot duration, i.e. 4 seconds. This helps maximizing the chance of voting for the most recent proposed block. |
There was a problem hiding this comment.
for the most recent proposed block
Just to verify my understanding,
is the most recent proposed block the same as most likely block to win in Ethereum consensus of this slot in this context ? Perhaps worth clarifying this. Plus, I assume it's 1/3 and not 1/2 or 3/4 or something because there is a time bound (which is probabilistic) on how much we can delay the execution of this duty for the Validator in question to actually perform it (as opposed to miss it) ? Also would appreciate clarification.
| - `ValidatorRegistration`: to perform the registration of the validator to the blockchain. | ||
| - `VoluntaryExit`: to exit the validator from the blockchain. |
There was a problem hiding this comment.
the blockchain -> Ethereum blockchain ?
| - `ValidatorRegistration`: to perform the registration of the validator to the blockchain. | ||
| - `VoluntaryExit`: to exit the validator from the blockchain. | ||
|
|
||
| Both duties are only composed by the Pre-Consensus phase since only a signature construction is needed over an a prior known data. |
There was a problem hiding this comment.
perhaps signature construction is needed over an a prior known data. -> signature construction is needed over a priori known data.
| Regarding the duties' start time, both should start at the beginning of the slot. | ||
|
|
||
| ## The Committee duty | ||
| Since the committee may manage several validators, many Attestation duties may need to be performed in the same slot. This represents a workload concern. Luckly, we have that all consensus executions for each attestation duty agree on the same data (the Casper FFG and LMD GHOST votes). Therefore, we can perform a single consensus execution for all validators assigned in the same slot (though a unique Post-Consensus phase is required for each). |
There was a problem hiding this comment.
for each attestation duty -> for each Attestation duty
all validators assigned in the same slot -> all validators assigned Attestation duty in the same slot
though a unique Post-Consensus phase is required for each -> though a unique Post-Consensus phase is required for each of those duties to be carried out fully
| @@ -0,0 +1,54 @@ | |||
| # Documentation | |||
There was a problem hiding this comment.
Maybe also Documentation -> Class diagram
|
|
||
| `BeaconNode` is an interface that allows the node to fetch duty data (e.g. an Attestation vote and a block to be proposed) and to submit a signed data (e.g. a signed Attestation vote and a signed block). | ||
|
|
||
| It also provides a method to get the blockchain domain (a sequence of bytes used in signatures that identifies the blockchain) and it holds a `BeaconNetwork` that provides information about the blockchain such as the current slot and fork version. |
There was a problem hiding this comment.
identifies the blockchain -> identifies the blockchain, eg. mainnet / holesky / ...
|
|
||
| ## BeaconNetwork | ||
|
|
||
| `BeaconNetwork` is a type that allows accessing information about the blockchain, e.g. such as the current slot, the number of seconds per slot, and the fork version. |
There was a problem hiding this comment.
Based on what I see in the code,
perhaps worth noting that BeaconNetwork does not need to send requests to ETH2 node (or any requests at all) and is rather just a struct of data bundled together + some compute on this data (executions over some constants and values provided to it when asked to do this computation).
| - `ValidatorRegistrationRunner` | ||
| - `VoluntaryExitRunner` | ||
|
|
||
| Each implementation of `Runner` performs its associated duty type, as suggested by their names. A notable difference is that a `CommitteeRunner` object will only execute one `CommitteeDuty` throughout its life. Other `CommitteeRunner` objects will be created to execute upcoming `CommitteeDuties`. For the other runners, they will execute all duties of their associated types during its life. |
There was a problem hiding this comment.
Perhaps clarify why the Runners differ in this behavior of
- some execute all the duties
- others are just 1-time performers
| Our **system model** is composed of a set of replicas $N$ (a committee of operators), out of which at most $f = \lfloor \frac{N-1}{3} \rfloor$ may be faulty. I.e., we are dealing with the optimal resiliency for the **Byzantine Fault Tolerance (BFT)** model. | ||
|
|
||
| This **committee** is assigned to a set of **validators**, from whom the duties must be executed. For each validator, the private key is shared in a way that each operator holds a **private share key** and its associated public key. Moreover, each operator holds a **network private and public key** for authentication in the network communication. |
There was a problem hiding this comment.
Haven't seen this mentioned in this PR, but seems pretty important for general understanding of the whole system:
- how does the process of grouping Operators into Committees look like ? And then Validators are distributed across those Committees somehow ?
- or is it that Validators are grouped into Committees and then Operators are assigned to serve specific committee(s) ?
The way this section currently describes it is incomplete and kind of confuses me even more:
This committee is assigned to a set of validators, from whom the duties must be executed.
There was a problem hiding this comment.
My current understanding is:
- User chooses Operators he desires (to operate his shares), this bunch of Operators essentially constitutes a Commitee
- this Committee entity ^ could have already existed in the network (originally created by another User in the past) - in which case we don't need to create a 2nd Committee (which will be processed by it's own set of QBFT instances) and can just bundle 2 or more Validators from independent users together; otherwise (Commitee doesn't exist yet) it's created to serve this 1 User for now
- and the whole point of having this Commitee thing is that QBFT iterations are run once per Commitee (as opposed to once per Validator - which seems to be the case for current mainnet setup)
- there is also a concept of Topic(s)/Subnet(s) Operators use to actually send messages around (aka pub-sub in libp2p); to reduce the amount of messages sent across SSV network I assume there needs to be some sort of mapping to distribute Commitees into Topics (which this SIP seems to be describing)
is that about right, or is there more to it ? Regardless, would be nice to have it written down somewhere (at least as short high-level summary)
Overview
This PR adds and updates the repository's documentation.
It updates the repository's main
README.mdand thep2pdocumentation files. It also adds documentation for theqbft,ssv, andtypesmodules.