Secret Shared Validator ('SSV') is a unique technology that enables the distributed control and operation of an Ethereum validator.
SSV uses an MPC threshold scheme with a consensus layer on top (Istanbul BFT),
that governs the network.
Its core strength is in its robustness and fault tolerance which leads the way for an open network of staking operators
to run validators in a decentralized and trustless way.
This repo contains the spec for SSV.Network node.
SSV network message is called SSVMessage, it includes a MessageID and MsgType to route messages within the SSV node code, and, data for the actual message (QBFT/ pre/ Post consensus messages for example).
Any message data struct must be signed and nested within a signed message struct which follows the MessageSignature interface. A signed message structure includes the signature over the data structure, the signed root and signer list.
This type of message is used for all consensus messages
type Message struct {
MsgType MessageType
Height Height // QBFT instance Height
Round Round // QBFT round for which the msg is for
Identifier []byte // instance Identifier this msg belongs to
Data []byte
}Used for pre and post consensus sigantures for collecting partial BN signatures and then reconstructing them
type PartialSignatureMessage struct {
Type PartialSigMsgType
PartialSignature []byte // The beacon chain partial Signature for a duty
SigningRoot []byte // the root signed in PartialSignature
Signers []types.OperatorID
}The KeyManager interface has a function to sign roots, a slice of bytes. The root is computed over the original data structure (which follows the MessageRoot interface), domain and signature type.
Use ComputeSigningRoot and ComputeSignatureDomain functions for signing
func ComputeSigningRoot(data MessageRoot, domain SignatureDomain) ([]byte, error) {
dataRoot, err := data.GetRoot()
if err != nil {
return nil, errors.Wrap(err, "could not get root from MessageRoot")
}
ret := sha256.Sum256(append(dataRoot[:], domain...))
return ret[:], nil
}func ComputeSignatureDomain(domain DomainType, sigType SignatureType) SignatureDomain {
return SignatureDomain(append(domain, sigType...))
}Domain Constants:
| Domain | Value | Description |
|---|---|---|
| Primus Testnet | DomainType ("primus_testnet") | Domain for the the Primus testnet |
Signature type Constants:
| Signature Type | Value | Description |
|---|---|---|
| QBFTSignatureType | [] byte {1, 0, 0, 0} | SignedMessage specific signatures |
| PartialSignatureType | [] byte {2, 0, 0, 0} | PostConsensusMessage specific signatures |
| DKGSignatureType | [] byte {3, 0, 0, 0} | PostConsensusMessage specific signatures |
A validator instance is created for each validator independently, each validator will have multiple Runner for each beacon chain duty type (Attestations, Blocks, etc.) Duty runners are responsible for processing incoming messages and act upon them, completing a full beacon chain duty cycle.
Each duty starts by calling the StartNewDuty func in the respective Runner. StartNewDuty might return error if can't start a new duty, depending on the previous duty life cycle. As a general rule, when a runner is executing a duty in the consensus phase, a new duty can't start. Pre/ Post partial signature collection will not enable starting a new duty if not completed except if timed out.
Attestation Duty Full Cycle:
-> Wait to slot 1/3
-> Received new beacon chain duty
-> Check can start a new consensus instance
-> Come to consensus on duty + attestation data
-> Broadcast and collect partial signature to reconstruct signature
-> Reconstruct signature, broadcast to BN
Block Proposal Duty Full Cycle:
-> Received new beacon chain duty
-> Check can start a new consensus instance
-> Sign partial RANDAO and wait for other signatures
-> Come to consensus on duty + beacon block
-> Broadcast and collect partial signature to reconstruct signature
-> Reconstruct signature, broadcast to BN
Attestation Aggregator Duty Full Cycle:
-> Received new beacon chain duty
-> Check can start a new consensus instance
-> Sign partial selection proof and wait for other signatures
-> Wait to slot 2/3
-> Come to consensus on duty + aggregated selection proof
-> Broadcast and collect partial signature to reconstruct signature
-> Reconstruct signature, broadcast to BN
Sync Committee Duty Full Cycle:
-> Wait to slot 1/3
-> Received new beacon chain duty
-> Check can start a new consensus instance
-> Come to consensus on duty + sync message
-> Broadcast and collect partial signature to reconstruct signature
-> Reconstruct signature, broadcast to BN
Sync Committee Aggregator Duty Full Cycle:
-> Received new beacon chain duty
-> Check can start a new consensus instance
-> Locally get sync subcommittee indexes for slot
-> Partial sign contribution proofs (for each subcommittee) and wait for other signatures
-> wait to slot 2/3
-> Come to consensus on duty + contribution (for each subcommittee)
-> Broadcast and collect partial signature to reconstruct signature
-> Reconstruct signature, broadcast to BN
A runner holds a QBFT controller for processing QBFT messages and a State which keeps progress for all stages of duty execution: pre/ post consensus messages. Partial signatures are collected and reconstructed (when threshold reached) to be broadcasted to the BN network.
A share is generated and broadcasted publicly when a new SSV validator is registered to its operators. Shares include:
- Node ID: The Operator ID the share belongs to
- Validator Public Key
- Committee: An array of Nodes that constitute the SSV validator committee. A node must include it's NodeID and share public key.
- Domain
type Share struct {
OperatorID OperatorID
ValidatorPubKey ValidatorPK
SharePubKey []byte
Committee []*Operator
Quorum, PartialQuorum uint64
DomainType DomainType
Graffiti []byte
}A node represents a registered SSV operator, each node has a unique ID and encryption key which is used to encrypt assigned shares. NodeIDs are extremely important as they are used when splitting a validator key via Shamir-Secret-Sharing, later on they are used to verify messages and reconstruct signatures.
Shares use the Node data (for committee) to verify that incoming messages were signed by a committee member
type Node struct {
NodeID NodeID
PubKey []byte
}NodeID is unique to each node, starting from ID 1 and incrementally going froward. Each ValidatorPK has a committee of nodes, each with a unique ID, share and share public key.
f(x) = a0 + a1X + a2X^2+a3X^3 + ... + ak-1X^(k-1)
f(0) = a0 = secret
Share1 = f(NodeID1)
Share1 = f(NodeID1)
...
The spec tests are a generated as a json file that can be run in any implementation. They test the various flows within the SSV package, treating the consensus protocol as as black box.
To generate all json spec tests, run:
foo@bar:~$ go generate ./...Then run all tests