magnetar/THBS-SPEC.md

Magnetar THBS-SE v1.0 --- Threshold Hash-Based Signatures with Selected-Element Reconstruction

Subpackage: github.com/luxfi/magnetar/ref/go/pkg/magnetar Status: v1.0.0 normative spec.

What this is

THBS-SE is the ONE permissionless threshold construction shipped by Magnetar v1.0. A t-of-n committee produces a SINGLE FIPS 205-shaped signature on a slot-bound message; the public combiner role is open to any peer (anyone can run Combine); no host is in the TCB at sign time.

THBS-SE is the architectural counterpart of the per-validator standalone primitive (standalone.go): both produce FIPS 205 wire bytes that any unmodified verifier accepts. The per-validator standalone path is the public-BFT primary; THBS-SE is the permissionless threshold companion for deployments that need a single FIPS 205-shaped signature from a committee instead of N independent signatures.

Hard invariant (verbatim from user spec)

A revealed value is allowed only if it is also present in the final
SLH-DSA signature.

Reveal type	Allowed?	Notes
Per-round mask r_i	YES	Part of Round-2 PartialSig payload; legitimately public.
Masked share s'_i = share_i XOR r_i	YES	Part of Round-2 PartialSig payload; legitimately public. Combined with r_i recovers share_i, which is information-theoretically uniform-random with fewer than t leaves under GF(257) Shamir.
Round-1 commit hash D_i	YES	Public domain-separated hash.
Final FIPS 205 signature bytes	YES	The PUBLIC output of Combine.
SK.seed	NO	Forbidden in any party-local persistent form. Each party holds ONLY its Shamir leaf, never the seed.
SK.prf	NO	Derived from SK.seed.
Future-slot share material	NO	The slot guard refuses any same-slot re-emission. The share envelope is per-slot.
WOTS+ chain bases for unused chains	NO	(v1.1 strict-atom invariant.)
FORS leaves not selected by message digest	NO	(v1.1 strict-atom invariant.)
Public auth-path nodes	YES	Part of every SLH-DSA signature.

v1.0 ship state (honest open item)

The strictest formulation of the invariant --- "no party or combiner EVER reconstructs SK.seed, even transiently in memory" --- requires the v1.1 strict-atom-assembly path tracked at BLOCKERS.md::MAGNETAR-STRICT-ATOM-V11.

Magnetar v1.0 routes the final FIPS 205 byte production via the Magnetar-internal slhSignAtom engine (thbsse_assemble.go) on a master reconstructed by the PUBLIC COMBINER; the emitted bytes are byte-identical to circl/slhdsa.SignDeterministic on that same master (pinned by TestSlhdsaInternal_ByteEqualToCirclSign and TestThbsSE_StrictAtom_Combine_ByteIdentityToCircl). The master is briefly present in the public combiner's memory for one Sign call and is zeroized before return. The combiner role is PUBLIC --- anyone can be the combiner --- and there is no long-lived secret material outside party-local Shamir leaves. (The authoritative current description of this path is ASSEMBLE-INVARIANT.md; this is the RESEARCH-ONLY leg, not production --- see §1.0 of SPEC.md.)

This is materially stronger than a TEE-attested privileged-aggregator model (no host is in the TCB) and materially weaker than the strict invariant (a peer-local memory-disclosure adversary at exactly the combine moment could observe the seed).

Construction (v1.0 wire)

Setup

1. Sample SLH-DSA seed S.
2. Derive (PK, SK) = slhdsa.Scheme().DeriveKey(S).
3. Byte-wise Shamir-share S across (n, t) committee via GF(257).
4. Publish PK + committee + (n, t).
5. Erase S. The dealer is in the TCB FOR SETUP ONLY; once setup
   returns, no party including the dealer holds S.

Production deployments run the leaderless PVSS-DKG path via the sibling luxfi/threshold DKG package and feed the result into the same wire-shape share envelope. v1.0 reference ships a deterministic-dealer setup (NewThbsSeKey) for KAT determinism.

Sign Round 1 (party p_i, in parallel)

1. Sample per-round mask r_i.
2. Compute D_i = cSHAKE256(r_i || s'_i || tau)
   where s'_i = share_i XOR r_i
     and tau = SlotBinding.Encode() || msg || party_id.
3. Broadcast (party_id, slot_id, D_i, availability_bit).
4. Persist (slot_id, H(slot_id || msg)) in local SlotGuard.
   Refuse if the same slot_id is already used for a different digest.

Sign Round 2 (party p_i, after Round-1 quorum is observable)

1. Reveal PartialSig = r_i || s'_i.
2. Idempotent replay: re-issuing Round 1+2 for the same
   (slot_id, msg) returns the persisted (R1, R2). A genuine
   equivocation attempt (same slot_id, different msg) raises
   *ThbsSeEquivocationError without emitting the second R1.

Combine (anyone, public)

1. Collect >= t Round-2 reveals.
2. For each, re-derive D_i from PartialSig + slot_binding + msg + party_id.
   Mismatch produces ThbsSeShareEvidence with reason=ThbsSeShareCommitMismatch.
3. Recover share_i = mask XOR masked_share via byte-wise XOR.
4. Lagrange-interpolate the seed via thbsseReconstructGF over GF(257).
5. Bind to slot via FIPS 205 ctx = tagThbsSeCtxPrefix || slot_id (32 bytes);
   total <= 255B per FIPS 205 sec 10.2.
6. Call slhdsa.SignDeterministic(seed, msg, ctx).
7. Zeroize seed + intermediate buffers.
8. Return Signature{Mode, FIPS 205 wire bytes}.

Verify (anyone, public)

Standard FIPS 205 slhdsa.Verify(pk, msg, sig, ctx). The v1.0 reference exposes this as VerifyBytesCtx (wire.go) for stateless dispatch --- no Magnetar code path on the verifier side.

Slot binding

Every signature is bound to the slot tuple (chain_id, epoch, slot, height, committee_id, message_domain). The binding flows into:

1. The cSHAKE256 commit transcript (so the same committee cannot reuse the same share material on a different message).
2. The FIPS 205 ctx string at sign time (so any verifier holding the slot tuple can derive ctx independently).

Wire layout (canonical, big-endian):

chain_id_len(4) || chain_id ||
epoch(8) || slot(8) || height(8) ||
committee_id_len(4) || committee_id ||
message_domain_len(4) || message_domain

The 32-byte slot_id = cSHAKE256(encode(binding), 32, "MAGNETAR-THBSSE-SLOT-V1") is the canonical key in the local slot guard and the payload of the FIPS 205 ctx string.

Slashing evidence

Equivocation

A party that signs two distinct messages at the same slot binding raises *ThbsSeEquivocationError carrying:

SlotID, PartyID,
PriorDigest, PriorR1, PriorR2,
NewDigest, NewR1, NewR2

The wire-shaped ThbsSeEvidence blob is the on-chain transmission shape. VerifyThbsSeEvidence is the canonical third-party verifier: pure function with no committee state required.

Malformed share

Combine emits typed ThbsSeShareEvidence for the following malformations:

• ThbsSeShareSlotMismatch --- the Round-2 reveal carries a slot ID that does not match the binding.
• ThbsSeShareWireSize --- the PartialSig is the wrong number of bytes for the SLH-DSA mode.
• ThbsSeShareCommitMismatch --- the Round-1 commit does not re-derive from the Round-2 reveal under the slot binding and message.

VerifyThbsSeShareEvidence is the third-party verifier; pure function.

Over-selected committee

With (n, t) and n > t, up to n - t silent withholders are tolerated. The Lagrange basis is determined by ANY t evaluation points, so disjoint sub-quora of size t produce byte-equal final signatures (the public combiner is a PURE function of its inputs). The 8-th test gate TestThbsSE_PublicCombiner_Determinism pins this.

API surface

• NewThbsSeKey(params, threshold, committee, rng) -> (*ThbsSeKey, error)
• ThbsSeRound1(params, share, binding, msg, guard, rng) -> (r1, r2, error)
• Combine(input ThbsSeCombineInput) -> (*Signature, []ThbsSeShareEvidence, error)
• ThbsSeSlotGuard + NewThbsSeSlotGuard, Record, Has
• VerifyThbsSeEvidence(params, ev, msgPrior, msgNew, bindingPrior, bindingNew) -> bool
• VerifyThbsSeShareEvidence(params, ev, binding, msg) -> bool

Stateless wire dispatch (consumed by luxfi/threshold/pkg/thresholdd):

• VerifyBytes(gpkBytes, message, sigBytes) -> bool
• VerifyBytesCtx(gpkBytes, message, ctx, sigBytes) -> bool

Test gates

The 8 mandated test gates plus 2 bonus correctness checks:

Gate	Test	Status
1	TestThbsSE_Wire_FIPS205Verifiable (3 modes)	PASS
2	TestThbsSE_RejectSeedReveal	PASS
3	TestThbsSE_RejectUnselectedFORS	PASS
4	TestThbsSE_RejectUnselectedWOTS	PASS
5	TestThbsSE_SlotReuseRejected	PASS
6	TestThbsSE_OverselectedCommittee	PASS
7	TestThbsSE_SlotBindingDomainSeparation	PASS
8	BenchmarkThbsSE_Sign_5of7 (192f < 100 ms/op)	PASS
bonus	TestThbsSE_PublicCombiner_Determinism	PASS
KAT	TestKAT_ThbsSe (n=7, t=4, 3 modes, 3 messages)	PASS

Citations

• McGrew, D., Wallace, C. and Whyte, W. (2019). Threshold Hash-Based Signatures. IACR ePrint 2019/793.
• Cozzo, D. and Smart, N. P. (2019). Sharing the LUOV. EUROCRYPT.
• Bonte, C., Smart, N. P. and Tan, T. (2023). Threshold SPHINCS+.
• Schoenmakers, B. (1999). A simple publicly verifiable secret sharing scheme and its application to electronic voting. CRYPTO.
• Shamir, A. (1979). How to share a secret. CACM.
• NIST FIPS 205 (2024). Stateless Hash-Based Digital Signature Standard.