pulsar/docs/deployment.md

Deployment Runbook — luxfi/pulsar

Operational guidance for deploying Pulsar (threshold ML-DSA-65) in production validator sets. Discloses the v0.1 trust-model caveat mandated by the cryptographer sign-off (GATE-1) and pins the safe operating envelope.

TL;DR — which Combine variant for which deployment?

Deployment scenario	Use	Why
Public BFT, no aggregator-host trust	AlgebraicAggregate (v0.3)	No sk is materialised at any party. Protocol-correct by construction. v1.0.20 closes the byte-equality gap (BLOCKERS.md → PULSAR-V03-1 closure record): the v0.3 signature now verifies under stock cloudflare/circl mldsa65.Verify.
Public BFT, interop with stock FIPS 204	Combine (v0.1) inside a TEE	Signature byte-equals cloudflare/circl, accepted by any FIPS 204 verifier. The aggregator host enters the TCB for the brief window of one KeyFromSeed call. Use SGX / SEV-SNP / TDX with remote attestation.
M-Chain bridge custody (single operator, TEE in TCB by design)	Combine (v0.1)	Same wire as above; dealer/aggregator trust is acceptable by deployment policy.
A-Chain confidential compute (TEE-attested provider)	Combine (v0.1)	TEE is part of the AI-provider attestation envelope (see aivm).
Dev / test	Either	Both produce valid threshold signatures; choose by interop need.

Public-BFT graduation gate

v1.0.20 (commit 023a3ed) closes the gate. TestAlgebraic_FullCycle_n5_t3 PASSES — the v0.3 wire verifies under stock cloudflare/circl mldsa65.Verify. Regression-guard hardening shipped in v1.0.21 (267ec04) and v1.0.22 (29094a7). PULSAR-V03-1 closure record: BLOCKERS.md (closed-finding registry).

Audience

• Validator operators bringing up a Pulsar-enabled Lux chain (or any chain consuming github.com/luxfi/pulsar).
• Coordinator-service operators running the witness-aggregator pattern.
• Security reviewers validating production posture against the cryptographer sign-off (cryptographer-sign-off.md).

Trust-model disclosure (load-bearing)

The v0.1 reconstruction-aggregator caveat

Operators MUST acknowledge this before running v0.1 in production on funds-bearing networks. It is the GATE-1 deferred disclosure from the cryptographer sign-off.

Pulsar v1.0.8 ships the v0.1 reveal-and-aggregate flow as the runnable reference. In this flow, Combine (in ref/go/pkg/pulsar/threshold.go) briefly reassembles the master ML-DSA-65 seed in the aggregator process's memory by computing Lagrange reconstruction over the revealed partial signatures and invoking mldsa65.NewKeyFromSeed. The seed exists in memory only for the duration of a single KeyFromSeed call and is zeroized on every exit path via ref/go/pkg/pulsar/zeroize.go (zeroizeBytes / zeroizeSeed / zeroizeU16 / zeroizePrivateKey), including error paths.

TCB implication: the aggregator process is in the trusted computing base for that brief window. An adversary who fully compromises the aggregator host (root-equivalent) during that window observes the seed and can forge signatures going forward.

Operational mitigations (all production deployments MUST satisfy at least items 1–4):

1. Aggregator host hardening: dedicated host, no general-purpose workloads, no shared memory, no /proc access for non-root users, hugepages disabled (prevents same-page deduplication side-channels).
2. Memory isolation: the aggregator process runs with locked pages (mlock), core-dumps disabled (setrlimit RLIMIT_CORE=0), ptrace disabled (prctl PR_SET_DUMPABLE 0).
3. TEE attestation (recommended): aggregator runs inside SGX, SEV-SNP, or TDX with remote attestation pinned to the reproducible build of luxfi/pulsar v1.0.8.
4. Operational scope limits: aggregator role is a single-purpose process; no network listener beyond the consensus message bus; no shell access; no debugger attachment in production.
5. Defense-in-depth (v0.2 migration target): the v0.2 FSwA Lagrange-linearity flow eliminates the reconstruction step entirely. v0.2 is the high-assurance target and EasyCrypt N1 reduction is stated against it; v0.2 Jasmin sources type-check. Production migration v0.1 → v0.2 is on the roadmap (see ~/work/lux/lps/ROADMAP-CRYPTO-STACK.md).

What v0.1 does NOT do

• Does NOT persist the reconstructed seed to disk.
• Does NOT leak the seed to any other process under normal operation.
• Does NOT have a code path that copies the seed to a buffer that outlives the KeyFromSeed call.
• Does NOT survive a process crash with seed material present (the seed lives entirely on the stack of one goroutine; OS process teardown reclaims it).

The TCB equivalence is "aggregator process == single-party FIPS 204 signer". The distributed threshold property holds against the participating committee adversaries (any t-1 collusion among the n parties), but it does NOT extend to an attacker who compromises the aggregator host itself.

Pre-deployment checklist

Before bringing up a Pulsar-enabled validator:

• Operator-readable acknowledgement of the v0.1 trust caveat above on file (RACI sign-off).
• Aggregator host meets items 1–4 above.
• If running on funds-bearing mainnet: item 3 (TEE attestation) satisfied OR documented compensating control approved by security review.
• scripts/check-high-assurance.sh exits 0 against the deployed binary's source tag (i.e., the binary you are deploying was built from a commit where the high-assurance gates were green).
• cryptographer-sign-off.md reviewed; all four gates either satisfied or have a compensating control on file.
• Run go test -race ./ref/go/pkg/pulsar/ against the deployed tag; PASS.
• Run test/interoperability/ against the deployed tag; 19/19 N1 subtests PASS.

At-runtime monitoring

The aggregator process should expose:

• A metric for every Combine invocation (counter + latency-histogram).
• A metric for every zeroize call on the seed material (counter; should match Combine invocations 1:1).
• A panic / signal handler that wipes the seed memory before exit.

Anomalous values for the zeroize counter (lower than the Combine counter) indicate a missed cleanup path — page immediately.

v0.1 → v0.2 migration plan

See ~/work/lux/lps/ROADMAP-CRYPTO-STACK.md §Pulsar v0.2 milestones. The migration is backward-incompatible at the wire level (v0.2 partial-signature encoding differs) but byte-equivalent at the output (final FIPS 204 signature is identical). Coordinated validator-set rollover is required.

v0.2 transitional threshold — trust model

Status (v1.0.14): v0.2 ships in ref/go/pkg/pulsar/threshold_v02.go under the Transitional name. The wire protocol is honestly algebraic — parties hold polynomial-vector Shamir shares of (s_1, s_2, t_0) over GF(q), Round 1 commits w_i = A·y_i, an intermediate w-reveal pass exchanges per-party w_i under MAC, Round 2 contributes (z_i, cs2_i, ct0_i) algebraically. The aggregator side is NOT yet algebraic: TransitionalAggregate validates every commit-bind and MAC, then calls mldsa{44,65,87}.SignTo against the master sk packed in TransitionalSetup.SkBytes. This is the v0.2 honesty caveat the rename from Algebraic* to Transitional* exists to declare.

Two paths, two trust models

Pulsar v1.0.14 ships both trust-model targets in parallel:

• v0.1 reveal-and-aggregate path — pulsar.Combine in ref/go/pkg/pulsar/threshold.go. The aggregator briefly reconstructs the master ML-DSA seed (via Lagrange interpolation over byte-wise GF(257) shares) and emits the signature through mldsa{44,65,87}.SignTo. TEE-attestation is mandatory for funds-bearing networks; the aggregator process is in the trusted computing base for the duration of one sign call.

• v0.2 transitional path — pulsar.TransitionalAggregate in ref/go/pkg/pulsar/threshold_v02.go. The protocol-side wire shape is FROST-for-FSwA with polynomial-vector shares as the carrier; parties never broadcast a share of the master seed in any form. The aggregator side still holds the master sk via TransitionalSetup.SkBytes and signs with it — the per-party (Z, CS2, CT0) contributions are validated for commit-bind / MAC integrity but are NOT consumed by the inner sign step. The aggregator TCB at sign time is identical to v0.1; only the parties' side of the protocol is honestly algebraic. TransitionalAggregate enforces len(setup.SkBytes) > 0 — TestTransitional_DependsOnSkBytes pins this in code as the load-bearing v0.3 graduation criterion.

v0.2 trust model — when is it safe to deploy?

TransitionalAggregate IS safe to deploy when:

1. The aggregator host is already in the TCB by other means (TEE attestation pinned to a reproducible Pulsar build; HSM- custody; single-operator deployment where the operator already sees all key material).
2. M-Chain bridge custody where the bridge MPC node is the aggregator and TEE attestation is mandatory at the operator layer.
3. A-Chain confidential-compute subnets where the entire aggregator process runs inside SGX/TDX with remote attestation.

TransitionalAggregate is NOT safe to deploy when:

1. The aggregator host is not in the TCB (public adversarial deployment where any node may be compromised).
2. The validator set assumes "no single host holds the master sk ever" — v0.2 violates this at the aggregator's brief sign window.

For deployments in the "NOT safe" bucket, use v0.1 Combine behind an explicit TEE attestation layer at the consumer (the wire shape is mature, the TCB caveat is well-documented in the v0.1 disclosure section above), OR wait for v0.3.

v0.3 milestone — graduation gate

The v0.3 work removes the SkBytes field from TransitionalSetup entirely. The graduation gate is one bit:

When TransitionalAggregate no longer needs setup.SkBytes — i.e. when it emits the FIPS 204 signature directly from the aggregated per-party (Z, CS2, CT0) contributions — the v0.3 milestone is met.

Operationally this is tracked by TestTransitional_DependsOnSkBytes in threshold_v02_test.go. The test currently PASSES (because TransitionalAggregate does depend on SkBytes); when v0.3 lands, that test FAILS, and the failure is the load-bearing red flag that the v0.3 graduation is complete. At that point:

1. Drop the SkBytes field from TransitionalSetup.
2. Rename TransitionalAggregate → AlgebraicAggregate (forward-only, no compat alias — the discipline matches the v1.0.14 Algebraic → Transitional rename).
3. Rewrite the file-header honesty block.
4. Replace TestTransitional_DependsOnSkBytes with the v0.3 no-sk-access AST guard already shipping in TestAlgebraic_NoSkAccess.

PULSAR-V03-1 byte-equality closed in v1.0.20 (commit 023a3ed). Closure record: BLOCKERS.md.

What v0.2 buys today (v1.0.14)

• No seed-share leakage at parties: polynomial-vector shares are the only secret material parties hold. A PolyKeyShare is information-theoretically (t-1)-secret against any coalition of fewer than t parties.
• Wire-shape stability: the v0.2 message flow (commit / intermediate w-reveal / sign-contribute / aggregate) is stable across v0.2 → v0.3. Consensus integrators that adopt the v0.2 protocol surface today get the message routing right; v0.3 only changes the cryptographic content of TransitionalAggregate → AlgebraicAggregate.
• Identifiable-abort gates: every MAC and commit-bind check in TransitionalAggregate emits AbortEvidence on tamper detection, matching v0.1's complaint taxonomy.

What v0.2 does NOT yet do (v1.0.14)

• The inner sign step still uses the master FIPS 204 packed sk via TransitionalSetup.SkBytes. The aggregator TCB at sign time is identical to v0.1. The v0.3 patch removes SkBytes from TransitionalSetup and emits the signature from the aggregated per-party contributions directly.
• The byte-equality test (v0.2 transitional signature byte-equal to stock FIPS 204 ML-DSA on the same y aggregate) is delivered via the transitional path; the v0.3 pure-algebraic emission requires a self-contained FIPS 204 sign-side polynomial-ring implementation in mldsa_lattice.go (NTT, Montgomery, decompose, MakeHint) that currently has a subtle Montgomery-scaling discrepancy against cloudflare/circl's internal package — see threshold_v02.go header for the diagnosis.

Reference: Cryptographer gates

The four gates from cryptographer-sign-off.md:

Gate	Status
GATE-1 — Aggregator trust runbook disclosure	CLOSED by this document.
GATE-2 — SUBMISSION.md cross-link to two-variant disclosure	CLOSED in SUBMISSION.md "Headline claim" + "What to read first" §12.
GATE-3 — dudect 10⁹-sample run	CLOSED — scripts/nightly.sh runs the submission-grade harness; results check into ct/dudect/results/. Per-push smoke runs at 10⁵ samples per proof-claims.md §3.2.
GATE-4 — Minor doc nits	CLOSED: 89.7% → 84.2% coverage corrected in SUBMISSION.md; Ed25519 → ML-DSA-65 in spec/pulsar.tex §Identifiable abort; proof-claims.md §3.2 dudect cross-link added; zeroize.go row added.

Contact

• Operations: [email protected]
• Security: [email protected]
• Submission package: [email protected]

---

Document metadata

• Name: deployment.md
• Version: v0.3 (matches Pulsar v1.0.22)
• Closes: cryptographer-sign-off.md GATE-1.
• v1.0.14: renamed v0.2 API from Algebraic* → Transitional* and rewrote the trust-model section to honestly disclose the aggregator-side SkBytes dependency. The v0.2 wire protocol is algebraic; the v0.2 aggregator is not.
• v1.0.20–v1.0.22: PULSAR-V03-1 closure — v0.3 AlgebraicAggregate emits a signature byte-equal to single-party FIPS 204 ML-DSA-65 under stock cloudflare/circl mldsa65.Verify.