Documentation for qbft, ssv, and types.

[jose-ssv-labs]

Replaces #496

[greptile-apps]

Greptile Summary

This PR adds comprehensive documentation for the qbft, ssv, and types modules, including new README.md files with architectural overviews, component descriptions, code snippets, and supporting diagrams (class diagrams, BPMN flow, duty flow). The documentation is a valuable addition for understanding the codebase, but several issues need to be addressed before merging.

Key findings:

• Factual error in types/docs/README.md: the section "ValidatorConsensusData and BeaconVote" incorrectly refers to the type as `BeaconDuty` (line 111) instead of the correct `BeaconVote`, which could mislead readers looking for that type.
• Incorrect description in types/docs/README.md: `OperatorSigner` is described as a "structure" when it is an interface, inconsistent with how `BeaconSigner` is described in the same section.
• Missing word in types/docs/README.md: "the Data should an encoded" is missing "be".
• Typo in section heading in types/docs/README.md: MessagID should be MessageID.
• Multiple typos in ssv/README.md: "thhe", "Pre-Consenus", "require a the", "Luckly", "over an a prior".
• Grammar errors in qbft/docs/README.md: "All of this fields" and duplicate "the the QBFT".

Confidence Score: 4/5

• This is a documentation-only PR with no code changes; safe to merge after fixing the identified typos and the one factual error (BeaconDuty → BeaconVote).
• No production code is modified. The content is generally accurate and well-structured. Score is 4 rather than 5 due to a factual error that names a non-existent type (BeaconDuty) and an incorrect interface/structure characterisation for OperatorSigner, both of which could mislead developers using the docs as a reference.
• types/docs/README.md requires the most attention due to the factual type-name error and the incorrect interface description.

Important Files Changed

Filename	Overview
types/docs/README.md	New documentation for the types module — contains a factual error (refers to BeaconDuty instead of BeaconVote), a missing word ("should an encoded"), a section heading typo (MessagID), and incorrectly describes OperatorSigner as a "structure" rather than an interface.
ssv/README.md	New top-level SSV module documentation — good overview of the system model and duty execution flow, but contains several typos: "thhe", "Pre-Consenus", "require a the", "Luckly", and "over an a prior".
qbft/README.md	Updated QBFT README with a Mermaid flowchart overview and BPMN diagram appendix — well-structured but minor HTML attribute comma syntax issue in the img tag.
qbft/docs/README.md	New QBFT module documentation — clear descriptions of key structs and their relationships; two minor textual errors ("All of this fields" and duplicate "the the") found.
ssv/docs/README.md	New SSV module documentation covering Network, BeaconNode, Runner, DutyRunners, Validator, and Committee — content is accurate and well-written with no notable issues.

Sequence Diagram

sequenceDiagram
    participant O as Operator
    participant R as Runner
    participant BN as BeaconNode
    participant QBFT as QBFT Controller
    participant N as P2P Network

    O->>R: StartDuty()
    alt Has Pre-Consensus phase (Proposer / Aggregator / SyncCommitteeContribution)
        R->>N: Broadcast PartialSignatureMessage (Pre-Consensus)
        N-->>R: Receive threshold of PartialSignatureMessages
        R->>BN: Fetch duty data (e.g. BeaconBlock, AggregateAndProof)
    end

    R->>QBFT: StartInstance(height, value)
    QBFT->>N: Broadcast Proposal (if leader)
    N-->>QBFT: Receive Proposal
    QBFT->>N: Broadcast Prepare
    N-->>QBFT: Receive quorum of Prepares
    QBFT->>N: Broadcast Commit
    N-->>QBFT: Receive quorum of Commits
    QBFT->>N: Broadcast Decided (aggregated Commits)

    R->>N: Broadcast PartialSignatureMessage (Post-Consensus)
    N-->>R: Receive threshold of PartialSignatureMessages
    R->>BN: Submit reconstructed validator signature

Loading

_{Last reviewed commit: 4ab1145}

[greptile-apps]

Typo in section heading: MessagID should be MessageID

The heading uses MessagID (missing the e) instead of the correct MessageID.

Suggested change

	`MessagID` is an identifier that is composed by:
	## MessageID

[greptile-apps]

Incorrect type name: BeaconDuty should be BeaconVote

This section is titled "ValidatorConsensusData and BeaconVote", but line 111 refers to the type as BeaconDuty — a type that does not exist. The correct name is BeaconVote.

Suggested change

	But what objects do the operators propose in the consensus protocol? It can be a `ValidatorConsensusData` or a `BeaconDuty`.
	The `ValidatorConsensusData` holds the associated duty, a blockchain version (e.g. as Phase0, Altair, Bellatrix, Capella, and Deneb), and an encoded object related to the duty (e.g. an AttestationData, a BeaconBlock). This structure is used for all except the `CommitteeDuty`.
	The `BeaconVote` contains a blockchain head vote (LMD GHOST vote) and a source and target votes (Casper FFG). It's used for the `CommitteeDuty`.

[greptile-apps]

Missing word: "should be an encoded"

The sentence reads "the Data should an encoded qbft.Message object" — it is missing the word "be".

Suggested change

	If the `MsgType` is of consensus type, then the `Data` should an encoded `qbft.Message` object. Else (if it's of partial signature type), it should be an encoded [`PartialSignatureMessages`](#partialsignaturemessages) object.
	If the `MsgType` is of consensus type, then the `Data` should be an encoded `qbft.Message` object. Else (if it's of partial signature type), it should be an encoded [`PartialSignatureMessages`](#partialsignaturemessages) object.

[greptile-apps]

Incorrect description: OperatorSigner is an interface, not a structure

The previous paragraph correctly describes BeaconSigner as an "interface". For consistency and accuracy, OperatorSigner should also be described as an "interface", not a "structure".

Suggested change

	`BeaconSigner` is an interface that provides methods for creating beacon signatures. Apart from signing, it servers as a slashing protection by providing a method to check if an attestation is slashable.
	The `OperatorSigner` is a similar interface but performs signing for network messages.

[greptile-apps]

Multiple typos in this section

Several typos are present:

• Line 31: "require a the Pre-Consenus" → should be "require the Pre-Consensus"
• Line 40: "thhe time" → should be "the time"
• Line 43: "maximizing the chance of voting" (minor, acceptable)

Suggested change

	The Ethereum duties that require a the Pre-Consenus phase are the Proposer, Aggregation and Sync Committee Contribution duties. The other duties (Attestation and Sync Committee) start from step 2 of the above diagram (without needing to provide any signature). In the Pre-Consensus phase:
	- the Proposer duty should construct the validator's signature over the `Epoch` number to build the `RANDAO` object.
	- the Aggregator duty should construct the validator's signature over the `Slot` number to submit an `AggregateSelectionProof`.
	- the Sync Committee Contributor duty should, for each committee index, construct the validator's signature over the `SyncAggregatorSelectionData` object to check if it's an aggregator.
	To reconstruct the validators signature, at minimum a *threshold* amount of signatures is needed. In our case, this *threshold* is $\lfloor \frac{N+f}{2} \rfloor + 1$ (or $2f+1$ in case $N = 3f+1$).
	### Duty start time
	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.
	- For the Aggregation and Sync Committee Contribution duties, the protocol should be executed after two thirds (2/3) of the slot duration, i.e. 8 seconds. This helps maximizing the collection of Attestation and Sync Committee votes.
	The Ethereum duties that require the Pre-Consensus phase are the Proposer, Aggregation and Sync Committee Contribution duties. The other duties (Attestation and Sync Committee) start from step 2 of the above diagram (without needing to provide any signature). In the Pre-Consensus phase:
	- the Proposer duty should construct the validator's signature over the `Epoch` number to build the `RANDAO` object.
	- the Aggregator duty should construct the validator's signature over the `Slot` number to submit an `AggregateSelectionProof`.
	- the Sync Committee Contributor duty should, for each committee index, construct the validator's signature over the `SyncAggregatorSelectionData` object to check if it's an aggregator.
	To reconstruct the validators signature, at minimum a *threshold* amount of signatures is needed. In our case, this *threshold* is $\lfloor \frac{N+f}{2} \rfloor + 1$ (or $2f+1$ in case $N = 3f+1$).
	### Duty start time
	Within the duty's slot, the 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.
	- For the Aggregation and Sync Committee Contribution duties, the protocol should be executed after two thirds (2/3) of the slot duration, i.e. 8 seconds. This helps maximizing the collection of Attestation and Sync Committee votes.

[greptile-apps]

Multiple typos in this section

• Line 52: "over an a prior known data" → remove the extra article: "over a prior known data"
• Line 57: "Luckly" → should be "Luckily"

Suggested change

	Both duties are only composed by the Pre-Consensus phase since only a signature construction is needed over an a prior 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).
	Both duties are only composed by the Pre-Consensus phase since only a signature construction is needed over a prior 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. Luckily, 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).

[greptile-apps]

Grammatical error: "All of this fields" should be "All of these fields"

Suggested change

Notice that there's no field for the sender (`OperatorID`), the signature or the proposed data (that must be included in the Proposal message and may be included in the Round-Change message). All of this fields are included in the upper wrapper (`types.SignedSSVMessage`). This is useful to detach the whole proposed data from the signature. Notice, however, that the signature is still binded to the proposed data by the field `Root` which is the hash of the data.

Notice that there's no field for the sender (`OperatorID`), the signature or the proposed data (that must be included in the Proposal message and may be included in the Round-Change message). All of these fields are included in the upper wrapper (`types.SignedSSVMessage`). This is useful to detach the whole proposed data from the signature. Notice, however, that the signature is still binded to the proposed data by the field `Root` which is the hash of the data.

[greptile-apps]

Duplicate word: "the the QBFT protocol"

The phrase "to start the the QBFT protocol" contains a duplicated "the".

Suggested change

	It has methods to start the the QBFT protocol and to process a message. Once processing a message, it also performs a message validation as described in the formal specification.
	It has methods to start the QBFT protocol and to process a message. Once processing a message, it also performs a message validation as described in the formal specification.

[GalRogozinski]

Also maybe move some contents from the main README to the docs (not in this PR), and add links to the docs.

The main README should be brief with an explanation on how to run the tests

[GalRogozinski]

this is actually the slot number

[GalRogozinski]

this isn't clear

[GalRogozinski]

make this clear

[GalRogozinski]

maybe explain what identifier is made of?

[GalRogozinski]

I think this field is a historic relic, not sure it is needed anymore...

[GalRogozinski]

I think this is in the paper as optional, no?

[GalRogozinski]

We need to check if this task was done

[GalRogozinski]

Suggested change

	Within the duty's slot, thhe time at which the operators should start the duty depends on the duty type.
	Within the duty's slot, the time at which the operators should start the duty depends on the duty type.