Simplex QuorumCertificate and BLS aggregator #4091

samliok · 2025-07-16T13:52:12Z

Why this should be merged

Implements the simplex QuorumCertificate, QCDeserializer and SignatureAggregator interfaces. This allows simplex to parse, aggregate and verify quorum certificates(ex. finalizations and notarizations) during execution.

How this works

Builds on top of the BLSVerifier to handle BLS signatures and public keys.
The bytes of a QC are serialized with the Codec

How this was tested

Added unit tests to qc_test.go.

Need to be documented in RELEASES.md?

no

simplex/quorum.go

samliok · 2025-07-16T21:06:29Z

simplex/qc.go

+
+	bytes, err := Codec.Marshal(CodecVersion, serializedQC)
+	if err != nil {
+		panic(fmt.Errorf("failed to marshal QC: %w", err))


todo: don't panic, update the simplex interface to allow an error return value

If we replace the codec usage with canoto, then we won't need to change the interface

StephenButtolph

I didn't review the tests yet, will look though the tests after these are addressed.

simplex/qc.go

StephenButtolph · 2025-07-21T20:05:02Z

simplex/qc.go

+
+	bytes, err := Codec.Marshal(CodecVersion, serializedQC)
+	if err != nil {
+		panic(fmt.Errorf("failed to marshal QC: %w", err))


If we replace the codec usage with canoto, then we won't need to change the interface

StephenButtolph · 2025-07-21T20:08:09Z

simplex/qc.go

+type SerializedQC struct {
+	Sig     []byte           `serialize:"true"`
+	Signers []simplex.NodeID `serialize:"true"`
+}


Why do we serialize the full list of nodeIDs? Shouldn't we be using a bitset to indicate participation similarly to warp?

using a bitset would be nice, but the implementation feels kind of gross. I'd need to store a canonical ordering of nodes in the blsVerifier to deserialize the bitset, as well as a mapping of nodeIDs to indices in the QC in order to serialize.

I noticed warp has a IndexedValidator for creating the bitset, and some helper functions to create a canonical ordering to read the bitset. Is all this complexity needed just to reduce the size of the serializedQC? Even if we have 100 nodes thats only 2000 bytes or ~.002 mbs potentially saved

simplex/qc.go

StephenButtolph · 2025-07-21T20:16:15Z

simplex/qc.go

+// Verify checks if the quorum certificate is valid by verifying the aggregated signature against the signers' public keys.
+func (qc *QC) Verify(msg []byte) error {
+	pks := make([]*bls.PublicKey, 0, len(qc.signers))
+	quorum := simplex.Quorum(len(qc.verifier.nodeID2PK))
+	if len(qc.signers) != quorum {
+		return fmt.Errorf("%w: expected %d signers but got %d", errUnexpectedSigners, quorum, len(qc.signers))
+	}


Are there checks somewhere else that verify that the same signer isn't included multiple times?

If so we should document that assumption here. If not we need to add that.

Simplex checks for:

Finalization

Notarization

Empty notarization

During the regular Simplex admission path.

Though now when I quickly skimmed through the code, I think we can process an un-verified notarization through the replication path, oops... @samliok can you confirm?

I think we should be prudent and double check this here in the avalanchego side as well.

So a couple notes after looking a bit deeper.

We do check if multiple nodes have signed twice in simplex see here. Although it's probably a better idea to do it here in Verify(and potentially remove the check in simplex)?

We don't verify notarizations/finalizations through the replication path. Created an issue

Noticed we don't add re-add replication task if block verification fails. Issue

We may possible add a signature for the wrong digest when creating a notarization. Issue

I'll tackle these issues on this simplex side, plus added checking for double signers in avalanchego.

StephenButtolph · 2025-07-21T20:25:28Z

simplex/qc.go

+}
+
+type SerializedQC struct {
+	Sig     []byte           `serialize:"true"`


By using []byte for the signature, the serialized format will need to include the length of the signature. (or if we switch this to canoto, will at least require us to verify the length).

This is why in warp we specify the length here explicitly:

Suggested change

Sig []byte `serialize:"true"`

Sig [bls.SignatureLen]byte `serialize:"true"`

it weird though bls.SignatureToBytes(*bls.Signature) []byte doesn't return a fixed length byte array. Shouldn't it always return an array of bls.SignatureLen 🤷

added

simplex/qc.go

StephenButtolph · 2025-07-21T20:31:51Z

simplex/qc.go

+// Aggregate aggregates the provided signatures into a quorum certificate.
+// It requires at least a quorum of signatures to succeed.
+// If any signature is from a signer not in the membership set, it returns an error.
+func (a SignatureAggregator) Aggregate(signatures []simplex.Signature) (simplex.QuorumCertificate, error) {


This probably doesn't need to include any handling of duplicates, as it should be unexpected for simplex to provide duplicates here (imo).

StephenButtolph · 2025-07-21T20:32:20Z

simplex/qc.go

+	if len(signatures) < quorumSize {
+		return nil, fmt.Errorf("%w: expected %d signatures but got %d", errUnexpectedSigners, quorumSize, len(signatures))
+	}


Is this defence-in-depth? I wouldn't expect simplex to ever call this function without sufficient signers.

yep, simplex checks the signers before calling aggregate

Let's double check the QC is valid (no double signing, enough signers) here as well.

Copilot AI review requested due to automatic review settings July 16, 2025 13:52

samliok requested a review from StephenButtolph as a code owner July 16, 2025 13:52

github-project-automation bot added this to avalanchego Jul 16, 2025

This comment was marked as outdated.

Sign in to view

Add simplex QC and BLS Aggregator + tests

76629dd

samliok force-pushed the simplex-quorum branch from 3cfdc9c to 76629dd Compare July 16, 2025 13:55

samliok added 2 commits July 16, 2025 09:58

merge conflicts

de08c8c

consistent error

f4fd1ee

yacovm reviewed Jul 16, 2025

View reviewed changes

simplex/quorum.go Outdated Show resolved Hide resolved

simplex/quorum.go Outdated Show resolved Hide resolved

simplex/quorum.go Outdated Show resolved Hide resolved

simplex/quorum.go Outdated Show resolved Hide resolved

simplex/quorum.go Outdated Show resolved Hide resolved

samliok added 3 commits July 16, 2025 16:11

rename

1b4f583

use pointers

b4f082c

use codec.marshalling

1df2a5b

samliok commented Jul 16, 2025

View reviewed changes

remove register type

e092d2e

yacovm previously approved these changes Jul 16, 2025

View reviewed changes

samliok and others added 2 commits July 18, 2025 11:32

inline check

041faeb

Merge branch 'master' into simplex-quorum

d9c800e

StephenButtolph reviewed Jul 21, 2025

View reviewed changes

use canoto

63eb798

samliok and others added 4 commits July 22, 2025 17:14

duplicate signers, fixed byte array, dont copy bls verifier

4a423ba

lint

2a037aa

ensure converting to id doesn't panic

5ad5888

Merge branch 'master' into simplex-quorum

b2811dc

	Sig []byte `serialize:"true"`
	Sig [bls.SignatureLen]byte `serialize:"true"`

Simplex QuorumCertificate and BLS aggregator #4091

Are you sure you want to change the base?

Simplex QuorumCertificate and BLS aggregator #4091

Conversation

samliok commented Jul 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Why this should be merged

How this works

How this was tested

Need to be documented in RELEASES.md?

Uh oh!

This comment was marked as outdated.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

StephenButtolph left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

yacovm Jul 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

samliok Jul 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

samliok Jul 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

samliok commented Jul 16, 2025 •

edited

Loading

yacovm Jul 21, 2025 •

edited

Loading

samliok Jul 22, 2025 •

edited

Loading

samliok Jul 21, 2025 •

edited

Loading