# Magnetar v1.0 --- Normative specification This document is the normative specification of the two primitives shipped by `luxfi/magnetar` v1.0. Companion documents: - `README.md` --- introduction and headline tests. - `THBS-SPEC.md` --- detailed THBS-SE construction spec. - `DEPLOYMENT-RUNBOOK.md` --- operator runbook. - `BLOCKERS.md` --- v1.1 roadmap. ## 1. Primitives Magnetar v1.0 ships TWO primitives. Both produce FIPS 205 wire bytes that an unmodified verifier accepts. ### 1.0 Threshold SLH-DSA status (normative) Magnetar does NOT claim an efficient oracle-respecting thresholdization of SLH-DSA. Known theoretical barriers for extractable hash-based signatures (Kondi-Kumar-Vanegas, MPTS '26) imply that, in the no-dealer / no-preprocessing setting a public, leaderless, permissionless chain requires, threshold signing CANNOT be achieved by merely making black-box use of the random-oracle / hash function. A true threshold SLH-DSA signer would have to evaluate the FIPS 205 signing algorithm inside an active-secure MPC -- including the SHAKE/SHA-2/Keccak computations that derive `R`, the FORS secrets, the WOTS+ chains, and the authentication paths -- which is non-black-box use of the hash: research-grade and expected to be expensive (the **T-SLH-DSA-MPC** research track). Production Magnetar therefore implements threshold **CERTIFICATION** over **INDEPENDENT** FIPS 205 SLH-DSA signatures -- never threshold signing: - **Permissionless (production default):** the weighted quorum certificate in `luxfi/consensus` (`protocol/quasar/quorum_cert.go`). A quorum-weight subset of the validator set sign independently (1.1 below); a verifier checks the quorum predicate directly, or via a post-quantum STARK/FRI proof of those verifications (P3Q, `luxfi/p3q`). No key material is shared, reconstructed, or combined. - **Trusted-hardware / custody (opt-in production):** the TEE-attested combiner pool -- honest trust-relocation (a host enters the TCB), NOT MPC. See `BLOCKERS.md`. - **THBS-SE (1.2): RESEARCH-ONLY.** It reconstructs the FIPS 205 master at the public combiner every signature; it MUST NOT be presented as a no-reconstruction production threshold. See `BLOCKERS.md::MAGNETAR-STRICT-ATOM` (OPEN). ### 1.1 Per-validator standalone (public-BFT primary) API at `ref/go/pkg/magnetar/standalone.go`: ``` PerValidatorKeypair(params, rng) -> (sk, pk, error) ValidatorSign(sk, rng, message) -> ([]byte, error) ValidatorBatchVerify(params, pubs, msgs, sigs) -> ([]bool, error) BuildAggregateCert(params, signers, pubKeys, sigs) -> (*ValidatorAggregateCert, error) VerifyAggregateCert(cert, message, knownValidators) -> (count, error) ``` Semantics: - Each validator runs `PerValidatorKeypair` ONCE on its own host with its own RNG; persists `(sk_i, pk_i)`; registers `pk_i` in the validator-set commitment. - To sign message `m`: validator `i` computes `sigma_i = ValidatorSign(sk_i, nil, m)`. Output is the raw FIPS 205 signature bytes; deterministic when `rng` is nil (FIPS 205 SignDeterministic). - The consensus layer collects N `(sigma_i, pk_i, ValidatorID_i)` triples into a `ValidatorAggregateCert` via `BuildAggregateCert`. - `VerifyAggregateCert` returns the COUNT of valid signers. The quorum policy decision (count >= threshold) lives at the CONSUMER, NOT in the primitive. Trust model: - No DKG, no shared seed, no aggregator-in-TCB. - Per-validator slashing is attributable. - A post-quantum P3Q STARK/FRI proof (`luxfi/p3q`) compresses the N independent signatures plus the weighted-quorum predicate into one succinct quorum certificate; the rollup is a separate primitive (`luxfi/consensus` quorum_cert + `luxfi/p3q`). The earlier Groth16/bn254 rollup is classical (pairing-based) and is superseded for PQ finality. ### 1.2 THBS-SE (permissionless threshold) API at `ref/go/pkg/magnetar/thbsse.go`: ``` NewThbsSeKey(params, threshold, committee, rng) -> (*ThbsSeKey, error) ThbsSeRound1(params, share, binding, msg, guard, rng) -> (r1, r2, error) Combine(input ThbsSeCombineInput) -> (*Signature, []ThbsSeShareEvidence, error) NewThbsSeSlotGuard() -> *ThbsSeSlotGuard VerifyThbsSeEvidence(params, ev, msgPrior, msgNew, bindingPrior, bindingNew) -> bool VerifyThbsSeShareEvidence(params, ev, binding, msg) -> bool ``` Semantics: see `THBS-SPEC.md` for the full construction. Highlights: - t-of-n committee with `n > t` over-selection. - Slot binding flows into the cSHAKE256 commit transcript AND into the FIPS 205 ctx string. - PUBLIC COMBINER role; anyone with the public ThbsSeKey, the slot binding, the message, and >= t valid Round-1/Round-2 pairs can produce the FIPS 205 signature. - Equivocation and malformed-share evidence are wire-shaped typed blobs; pure-function third-party verifiers. ## 2. Parameter sets Per FIPS 205 sec 10.1 Table 2: | Mode | n (WOTS+ msg len) | PK | SK | Sig | Seed | |---|---|---|---|---|---| | `ModeM192s` (Magnetar-SHAKE-192s) | 24 | 48 | 96 | 16224 | 96 | | `ModeM192f` (Magnetar-SHAKE-192f) | 24 | 48 | 96 | 35664 | 96 | | `ModeM256s` (Magnetar-SHAKE-256s) | 32 | 64 | 128 | 29792 | 128 | Recommended production target: `ModeM192s` (smallest signatures at NIST PQ category 3, >=192-bit classical security). ## 3. Hash domain separation All cSHAKE calls use function-name `"Magnetar"` and one of the following customisation tags: | Tag | Purpose | Defined in | |---|---|---| | `MAGNETAR-THBSSE-SHARE-DEAL-V1` | Shamir coefficient stream + EvalPointFromID hash | `transcript.go` | | `MAGNETAR-THBSSE-SLOT-V1` | Slot binding -> 32-byte slot_id; message digest | `thbsse.go` | | `MAGNETAR-THBSSE-R1-COMMIT-V1` | Round-1 commit D_i; setup transcript | `thbsse.go` | | `MAGNETAR-THBSSE-SHARE-MAC-V1` | (reserved for share-MAC envelope) | `thbsse.go` | The protocol-wide domain-separation context is the ASCII string `"lux-magnetar-v1"` (`tagDomainSep`). The FIPS 205 ctx prefix for THBS-SE signatures is `"lux-magnetar-thbsse-v1"` followed by the 32-byte slot_id; total length 56 bytes, well under the FIPS 205 sec 10.2 limit of 255 bytes. ## 4. Byte-identity claims ### 4.1 Per-validator standalone `TestMagnetar_Wire_FIPS205Verifiable` pins: For any `(sk, message)` pair: stripping the canonical 11-byte MAGS wire header from `MarshalBinary(ValidatorSign(sk, nil, message))` recovers the unmodified FIPS 205 bytes that `cloudflare/circl/sign/slhdsa.Verify` accepts under `(sk.Pub, message, nil_ctx)`. ### 4.2 THBS-SE `TestThbsSE_Wire_FIPS205Verifiable` pins: For any `(key, binding, message)` triple and any `t` valid Round-1/Round-2 pairs: `Combine(...)` emits a `*Signature` whose `Bytes` field, fed DIRECTLY to `cloudflare/circl/sign/slhdsa.Verify` under `(key.PublicKey, message, ctxFromSlot(binding))`, is accepted. Additionally, `TestThbsSE_PublicCombiner_Determinism` pins that any two disjoint t-sized sub-quora of valid Round-2 reveals produce byte-equal final signatures. The public combiner is a PURE function of its inputs. ## 5. Slashing evidence wire shape ### 5.1 Equivocation evidence (ThbsSeEvidence) ``` type ThbsSeEvidence struct { SlotID [32]byte PartyID NodeID // [32]byte PriorDigest [32]byte PriorR1 ThbsSeRound1Msg PriorR2 ThbsSeRound2Msg NewDigest [32]byte NewR1 ThbsSeRound1Msg NewR2 ThbsSeRound2Msg } ``` Third-party verifier: `VerifyThbsSeEvidence(params, ev, msgPrior, msgNew, bindingPrior, bindingNew) -> bool`. ### 5.2 Malformed-share evidence (ThbsSeShareEvidence) ``` type ThbsSeShareEvidence struct { PartyID NodeID Reason ThbsSeShareEvidenceReason // {slot-mismatch, wire-size, commit-mismatch} ExpectedD [32]byte // for commit-mismatch ObservedD [32]byte // for commit-mismatch PartialSig []byte // for commit-mismatch / wire-size } ``` Third-party verifier: `VerifyThbsSeShareEvidence(params, ev, binding, msg) -> bool`. ## 6. Wire codec Magnetar v1.0 ships canonical MAGS (signature) and MAGG (group key) frames per `wire.go`: ``` Signature: GroupKey: magic(4) = 'M' 'A' 'G' 'S' magic(4) = 'M' 'A' 'G' 'G' version(2) = 0x0001 version(2) = 0x0001 mode(1) = {0x01..0x03} mode(1) = {0x01..0x03} len(4) = FIPS 205 sig size len(4) = FIPS 205 pk size payload = FIPS 205 sigEncode payload = FIPS 205 (seed||root) ``` Magic bytes are distinct from sibling protocols (pulsar PULS/PULG, corona CORS/CORG) so cross-protocol frames fail at the first dispatch. Stripping the 11-byte header recovers the unmodified FIPS 205 bytes any verifier accepts. ## 7. v1.0 open items See `BLOCKERS.md`: - `MAGNETAR-STRICT-ATOM-V11` --- the strict-invariant lift (no seed reconstruction even transiently). - `MAGNETAR-PVSS-DKG-V11` --- the leaderless PVSS-DKG setup variant (v1.0 ships deterministic-dealer reference; production routes through sibling `luxfi/threshold` DKG). - `MAGNETAR-PROOF-TRACK-V11` --- EasyCrypt + Lean track for the THBS-SE construction shape. - `MAGNETAR-DUDECT-V11` --- v1.1 dudect harness. - `MAGNETAR-EXTERNAL-AUDIT-V11` --- external cryptographer review.