quasar/SPEC.md

QuasarCert — Wire Format Specification

Authoritative wire-format definition for the Quasar certificate. Pinned spec; implementations across luxfi/consensus, luxfi/chains, luxfi/node, and luxfi/evm MUST encode/decode against this definition byte-identical.

Version

v1.0.0 (2026-05-18). Hash-stable wire bytes. Backward-incompatible changes require a major-version bump in this document and a coordinated multi-repo cascade.

Go struct

package quasar

import "time"

// QuasarCert is the wire-format finality certificate for one
// Lux consensus round. The set of populated legs is determined
// by the active cert profile (see PROFILES.md).
type QuasarCert struct {
    // BLS is the BLS12-381 aggregate signature over the round
    // digest from the validator set. 48 bytes when present.
    // Always present on the Pulsar / Aurora / Polaris profiles
    // (classical fast path).
    BLS []byte

    // Pulsar is the threshold ML-DSA-65 signature produced by
    // luxfi/pulsar v1.0.x. Byte-identical to single-party FIPS 204
    // ML-DSA-65.Sign output on the same (group public key, round
    // digest). Always present on the Pulsar / Aurora / Polaris
    // profiles.
    Pulsar []byte

    // Corona is the threshold R-LWE signature produced by
    // luxfi/corona v0.4.x. Present on the Aurora and Polaris
    // profiles. Empty on the Pulsar profile.
    Corona []byte

    // Magnetar is the threshold SLH-DSA / hash-based signature.
    // Present on the Polaris profile only. Empty otherwise.
    // (SLH-DSA threshold is research-stage per PRIMITIVES.md;
    // production-grade ratification is on the roadmap.)
    Magnetar []byte

    // MLDSAProof is a Z-Chain Groth16 proof rolling up N per-
    // validator ML-DSA-65 identity signatures into ~192 bytes.
    // Present on profiles that include the Z-Chain witness path.
    // Empty when degraded to per-validator MLDSA mode.
    MLDSAProof []byte

    // Epoch is the validator-set epoch this cert was minted under.
    Epoch uint64

    // Finality is the wall-clock timestamp at which the cert was
    // finalized by the consensus engine. Advisory; do not consume
    // for state-machine logic.
    Finality time.Time

    // Validators is the validator-set size at the time the cert
    // was minted. Used to size BLS aggregate verification and the
    // Z-Chain Groth16 circuit instance.
    Validators int
}

The canonical definition lives at luxfi/consensus/protocol/quasar/types.go:40. Spec and code MUST agree byte-for-byte.

Encoding

QuasarCert is encoded via luxfi/consensus/protocol/quasar/corona_gob.go, a native binary encoder (not Go's gob). The native encoder is ~1.01× the size of gob (see cert_size_compare_test.go) but is deterministic, language-agnostic, and stable across Go versions.

Verification

A valid QuasarCert MUST satisfy ALL of the following:

1. Every populated leg verifies under its primitive's verifier:
   • BLS: BLS12-381 aggregate verifier vs the validator set's BLS public keys at Epoch
   • Pulsar: FIPS 204 ML-DSA-65 Verify(group_pk, digest, ctx, sig) with ctx = "lux-quasar-cert-v1"
   • Corona: Corona threshold verifier vs the Corona group pubkey
   • Magnetar: SLH-DSA threshold verifier vs the Magnetar group pubkey
   • MLDSAProof: Groth16 verifier vs the Z-Chain VK pinned for Epoch
2. The profile's populated leg set matches the configured FinalitySchemeID for the chain (see PROFILES.md). A cert that populates more or fewer legs than the profile dictates is malformed.
3. Validators equals the validator-set size at Epoch. A cert that lies about the validator count is malformed.

Cert size (production params, n=21 validators)

Profile	BLS	Pulsar	Corona	Magnetar	MLDSAProof	Total
Pulsar	48 B	3309 B	0	0	192 B	~3549 B
Aurora	48 B	3309 B	~33 KB	0	192 B	~37 KB
Polaris	48 B	3309 B	~33 KB	~16 KB	192 B	~53 KB

Sizes for Corona / Magnetar legs are dominated by the underlying threshold-signature wire format (Corona ~33 KB native binary per ~/work/lux/consensus/CLAUDE.md measurement; Magnetar bound by the SLH-DSA SHAKE-192s parameter set ~16 KB).

10K-cert storage projections live in consensus/CLAUDE.md "Cert-size honest accounting".

Domain separation

All ML-DSA / SLH-DSA primitives sign under explicit FIPS 204 §5 context strings:

Context	Used by
lux-quasar-cert-v1	Pulsar leg of the cert
lux-corona-cert-v1	Corona leg of the cert
lux-magnetar-cert-v1	Magnetar leg of the cert (when populated)
lux-quasar-zchain-witness-v1	per-validator MLDSA signed into Groth16

Domain separation prevents cross-leg replay between profiles.

Wire-format stability commitment

This spec is stable. Implementations MUST NOT add, remove, or reorder fields without a coordinated cascade:

1. Bump spec version
2. Cascade through luxfi/consensus, luxfi/chains, luxfi/node, luxfi/evm simultaneously
3. Republish all consumer tags

The cert format is the load-bearing cross-primitive contract; changes are not negotiable in isolation.