# Deployment Runbook — luxfi/corona

> Operational guidance for deploying Corona (threshold Ring-LWE
> signing + Pedersen DKG + proactive resharing) in production
> validator sets. Discloses the v0.2 trust-model caveats and pins
> the safe operating envelope.

## Audience

- Validator operators bringing up a Corona-enabled Lux Quasar chain
  (or any chain consuming `github.com/luxfi/corona`).
- Coordinator-service operators running the witness-aggregator
  pattern.
- Security reviewers validating production posture against the
  honest framing in `PROOF-CLAIMS.md`.

## Trust-model disclosure (load-bearing)

### The v0.2 reconstruction-aggregator caveat

> **Operators MUST acknowledge this before running v0.2 in production
> on funds-bearing networks.**

Corona's combine procedure operates on Lagrange-aggregated `z_i =
y_i + c·s_i` responses. The aggregator computes
`z = Σ_{i ∈ Q} λ_i^Q · z_i` over `R_q^M`. The aggregator does NOT
reconstruct the master secret `s` in memory at any point during
normal signing — the Lagrange aggregation is over the partial
responses, not the shares themselves.

**However**, two distinct trust-model caveats apply:

1. **DKG bootstrap path is operator-chosen.** As of v0.7.5, the
   unqualified `keyera.Bootstrap` / `keyera.BootstrapWithSuite`
   defaults route through `BootstrapPedersen` (Pedersen-DKG over
   `R_q` + Path (a) noise flooding) so no single party ever holds
   the master secret `s` at any point in the ceremony. The legacy
   trusted-dealer ceremony path (where a single dealer instantiates
   `s` and Shamir-shares it to the committee, zeroing the in-memory
   copy before returning) is retained ONLY behind the explicit
   `keyera.BootstrapTrustedDealer` /
   `keyera.BootstrapTrustedDealerWithSuite` names for HSM/TEE
   ceremonies where the foundation explicitly chooses a non-
   distributed trust root. The latter path is acceptable for chain-
   launch ceremonies where the foundation's ceremony posture is
   audited and attested; it is NOT acceptable for permissionless
   re-anchoring, routine rotations, or any context where the
   dealer is not a publicly-attested entity.

2. **The aggregator process is in the trusted computing base.** An
   adversary who fully compromises the aggregator host
   (root-equivalent) during a signing session can observe `c` and
   `z_i` for all `i ∈ Q`, and can compute `s_Q = Σ λ_i · s_i` if it
   sees enough partial-response sets across distinct quorum subsets.
   (Note: this is weaker than Pulsar's v0.1 aggregator caveat, where
   the aggregator briefly reconstructs the master ML-DSA seed in
   memory; Corona's aggregator never reconstructs `s`.)

**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. **Bootstrap MPC ceremony hardening** (applies only to operators
   choosing the explicit `BootstrapTrustedDealer` path): foundation
   MPC ceremony at chain genesis uses commit-and-reveal entropy from
   genesis validators; dealer state is zeroed in place via
   `keyera/bootstrap_pedersen.go:bootstrapTrustedDealerImpl`.
   Ceremony participants are bound by the foundation's toxic-waste
   protocol. Operators on the default `BootstrapPedersen` path do
   NOT need this control because no party ever holds the master
   secret.
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. **TEE attestation (recommended)**: aggregator runs inside SGX,
   SEV-SNP, or TDX with remote attestation pinned to the
   reproducible build of `luxfi/corona v0.7.5`.
6. **Defense-in-depth**: validator-set rotation via Reshare (not
   Reanchor) is the routine path; Reanchor (new key era) is a rare
   governance event reserved for security-incident response.

### Bootstrap-Trust: two entrypoints (each), one decision

As of `v0.7.3`, Corona ships two **bootstrap** entrypoints; as of
`v0.7.4`, the same split applies to **reanchor**. **Operators MUST
choose one explicitly; the choice is load-bearing for the chain's
trust model.**

The same decision criteria apply to both lifecycle events:

- `Bootstrap` / `Reanchor` defaults to the **public-BFT-safe**
  Pedersen-DKG path (`BootstrapPedersen` / `ReanchorPedersen`). No
  party ever holds the master secret `s` at any point in the ceremony.
- `BootstrapTrustedDealer` / `ReanchorTrustedDealer` is the explicit
  opt-in for **HSM- or TEE-bound ceremonies** where the operator is
  prepared to vouch for a single dealer's host platform under audit.

#### Option A — `keyera.BootstrapPedersen` (public-BFT-safe, recommended)

- Routes the keygen ceremony through `dkg2/` (Pedersen-DKG over `R_q`).
- Every validator runs `dkg2.Round1` independently; no single party
  ever holds the master secret `s` at any point in the ceremony.
- Path (a) noise flooding (LP-073 §07 Mapping) produces a Corona-
  Sign-shaped public key `bTilde = Round_Xi(A·s + e'')` where each
  party contributes one Gaussian `e_j'` slice.
- Identifiable abort: a misbehaving sender is named in a signed
  `dkg2.Complaint` carrying re-checkable Pedersen evidence; the
  chain commits the abort transcript and stays at the previous epoch.
- **Use case**: any production deployment where the operator cannot
  vouch for the secrecy of a single dealer's host platform.
- **Security assumptions**:
  - Hiding under decisional MLWE on the wide concatenation `[A|B]`
    (Pedersen-DKG security; `papers/lp-073-pulsar §07`).
  - Per-party Gaussian flooding bound `σ'' = κ·σ_E·√n` covers the
    LWE leakage budget (Path (a) flood-bound, LP-073 §5).
  - Authenticated pairwise channels between every validator pair
    (consensus layer; in-process kernel derives material
    deterministically for KAT replay).
- **Trade-off**: one extra round versus the trusted-dealer path; an
  extra `M · n · (φ · log q)` bytes of broadcast (the per-party β_j
  contributions) bound into the transcript.

#### Option B — `keyera.BootstrapTrustedDealer` (legacy, ceremony-only)

- Single dealer instantiates `s`, runs Shamir share-out, hands shares
  to the committee, zeroes its in-memory copy of `s`.
- The dealer's host platform is in the trust boundary for the
  duration of the call.
- **Use case**: genesis ceremonies where the foundation explicitly
  chooses a non-distributed trust root (publicly observable HSM-
  bound ceremony with commit-and-reveal entropy from genesis
  validators, dealer state zeroed before ceremony close).
- **Honest framing**: this is the standard "toxic-waste" assumption
  common to setup ceremonies. It is acceptable for chain launch
  ceremonies where the foundation's ceremony posture is audited and
  attested; it is NOT acceptable for permissionless re-anchoring,
  routine rotations, or any context where the dealer is not a
  publicly-attested entity.

#### Decision matrix

The matrix below covers both lifecycle events that open a key era:
**Bootstrap** (chain genesis) and **Reanchor** (governance-gated new
era for security-event response). Resharing within an era is
**always** trustless — no decision needed there.

| Scenario | Recommended entrypoint |
|---|---|
| New mainnet chain launch (public BFT) | `Bootstrap` / `BootstrapPedersen` (foundation acts as one of n) |
| Foundation-audited HSM ceremony at chain genesis | `BootstrapTrustedDealer` (acceptable; document trust attestation) |
| Reanchor due to security incident, public BFT validator set | `Reanchor` / `ReanchorPedersen` (no single party should be retrusted) |
| Reanchor via HSM/TEE ceremony with audited trust posture | `ReanchorTrustedDealer` (acceptable only when the new dealer is publicly attested) |
| Routine validator-set rotation | Use `Reshare` (preserves GroupKey; no bootstrap, no decision) |
| Test / KAT replay | Either, with deterministic entropy |

**Default routing in code**: as of v0.7.5, **both** unqualified
`Bootstrap` / `BootstrapWithSuite` **and** `Reanchor` /
`ReanchorWithSuite` entrypoints route through Pedersen-DKG by
default. To use the legacy single-dealer path you MUST name
`BootstrapTrustedDealer` / `BootstrapTrustedDealerWithSuite` (or the
analogous Reanchor variant) explicitly. The safe default is
unqualified; the ceremony path requires an explicit name. This is
the **loud-name invariant**: any deployment that cannot tolerate the
dealer's trust boundary cannot accidentally inherit it; the explicit
opt-in is enforced at the call site.

**Structural constraint**: the public-BFT-safe path requires
`n >= 2 && t < n` (strictly less than). Deployments that need every
validator to sign (`t == n`) must select `BootstrapTrustedDealer`
explicitly; the unqualified `Bootstrap` will fail with
`ErrBootstrapPedersenShape` on `t == n`, surfacing the decision at
the call site rather than silently routing to the dealer path.

The decision is recorded in the era's genesis transcript via the
`HashSuiteID` and the Bootstrap mode tag; downstream auditors can
verify which path was taken without re-running the ceremony.

### What Corona's combine does NOT do

- Does NOT reconstruct the master secret `s` in aggregator memory
  during normal signing.
- Does NOT persist any per-party share to disk during signing.
- Does NOT leak any per-party share to any other process under
  normal operation.
- Does NOT survive a process crash with secret share material
  present beyond the Go runtime's normal garbage-collection cycle
  (best-effort zeroization via `reshare/keyshare.go:EraseShare` is
  invoked on activation and reshare-completion paths).

## Pre-deployment checklist

Before bringing up a Corona-enabled validator:

- [ ] Operator-readable acknowledgement of the v0.2 trust caveats
      above on file (RACI sign-off).
- [ ] Aggregator host meets items 1–4 above.
- [ ] If running on funds-bearing mainnet: item 5 (TEE attestation)
      satisfied OR documented compensating control approved by
      security review.
- [ ] `scripts/build.sh` exits 0 against the deployed binary's
      source tag (i.e., the binary you are deploying was built from
      a commit where the build gates were green).
- [ ] `scripts/test.sh` exits 0 against the deployed tag (KAT +
      integration + unit tests green).
- [ ] `scripts/regen-kats.sh --verify` exits 0 (cross-runtime
      byte-equality with the C++ port is intact).
- [ ] `CONSTANT-TIME-REVIEW.md` reviewed; all `(b)` entries either
      mitigated or accepted with documented compensating control.
- [ ] `PROOF-CLAIMS.md` §3 read and understood — Corona does NOT
      ship mechanized refinement; review reduces to code + KAT +
      academic construction analysis.
- [ ] `DESIGN.md` §"What is preserved across resharing" understood
      — distinguish Refresh (same set, fresh shares) from
      ReshareToNewSet (set rotation), distinguish Reshare (preserves
      key era) from Reanchor (new key era).
- [ ] Validator-set rotation policy documented (cadence, threshold
      changes, complaint-response procedures).

## At-runtime monitoring

The aggregator process should expose:

- A metric for every `threshold.Combine` invocation (counter +
  latency-histogram).
- A metric for every Lagrange aggregation step (counter; should
  match Combine invocations 1:1).
- A metric for every share zeroize call on the post-activation
  path (counter; should match activation completions 1:1).
- A metric for every Pedersen-mismatch complaint event (counter;
  should be 0 in honest deployments — spike indicates a malicious
  participant).
- A panic / signal handler that invokes `EraseShare` on the current
  generation's shares before exit.

Anomalous values (e.g., a spike in complaints without a corresponding
disqualification, or a zeroize counter trailing the activation
counter) should page immediately.

## Resharing operational procedure

Corona's resharing is the routine path for validator-set changes
within a key era. See `DESIGN.md` §"Three layers, one shipping path"
for the algorithmic detail; operational specifics:

1. **Cadence**: every epoch boundary or every validator-set change,
   whichever is more frequent. The consensus layer (Quasar)
   triggers resharing via the `keyera.Reshare` call.

2. **Round structure**: 3-round shape (commit → private deliveries →
   combine + activate). Each round has a timeout configured at the
   consensus layer; missed rounds trigger the complaint pipeline.

3. **Complaint handling**: per-pair Pedersen-style verification on
   the recipient side (`dkg2.go:VerifyShareAgainstCommits` /
   `reshare/commit.go:VerifyShareAgainstCommits`). Failure produces
   a signed evidence packet identifying the malicious sender.
   Disqualification quorum is configured at the consensus layer.

4. **Activation gate**: after the math completes, the new committee
   threshold-signs an activation message under the **unchanged**
   `(A, bTilde)`. Only on successful verification does the chain
   accept the new epoch. Failure → consensus falls back to the old
   committee + retries with a new transcript binding.

5. **Failure modes**:
   - Coordinator timeout / unavailable → consensus picks the next
     coordinator deterministically.
   - Resharing round fails (commit mismatch, bad share) → emit signed
     evidence; retry under new transcript binding next epoch.
   - Activation cert fails to verify → LSS Rollback to previous
     generation; chain stays at previous generation; signing
     continues under previous shares.
   - Multiple consecutive activation failures → governance reanchor:
     new key era, fresh ceremony, new group key.

## Migration paths

### v0.4.x → v0.5.x (submission-package addition)

This revision adds the NIST MPTC submission package documentation
(`SUBMISSION.md`, `NIST-SUBMISSION.md`, `SPEC.md`, `PATENTS.md`,
`PROOF-CLAIMS.md`, `TRUSTED-COMPUTING-BASE.md`, etc.). NO behavior
changes. KAT vectors are byte-identical. Production deployments can
upgrade in place; no validator-set rotation required.

### v0.5.x → v0.6.x (planned)

Planned: single-document `spec/corona.tex` consolidating the LaTeX
spec, parameter-set worksheet with lattice-estimator concrete
bounds, and second parameter set targeting NIST PQ Category 3.
Backward-compatible at the wire level; may add a new parameter-set
identifier.

### v0.6.x → v0.7.x (research, multi-month)

Planned: EasyCrypt theory shell for the construction-level
interchangeability claim; Lean 4 / Mathlib mechanization of the
Lagrange-aggregation identity over `R_q`. NO code changes; pure
proof artifact addition. Backward-compatible.

### v0.7.x → v0.8.x (research + audit)

Planned: dudect-style statistical CT validation harness; external
cryptographic audit (engaged lab). May surface findings requiring
patch-level remediation.

## Reference: cryptographer guidance

Corona does NOT ship a `CRYPTOGRAPHER-SIGN-OFF.md` at this submission
scaffolding revision. (Pulsar has one because Pulsar has an
EasyCrypt + Lean + Jasmin mechanized refinement chain that a
cryptographer signed off on. Corona's lighter proof tier does not
yet warrant analogous formal sign-off.) The roadmap to a Corona
sign-off lands with v0.7.0 (mechanized refinement) and v0.8.0
(external audit).

In the interim, the honest cryptographic posture is:

- **Construction soundness**: inherited from Boschini et al. ePrint
  2024/1113 (peer-reviewed academic prior art, IEEE S&P 2025).
- **Implementation soundness**: code review + KAT cross-validation
  Go ↔ C++ + fuzz harnesses + static per-path constant-time audit
  with zero `(c)` findings.
- **Lifecycle soundness**: production-tested via the consuming Quasar
  consensus layer; activation cert circuit-breaker is the
  load-bearing safety mechanism.

## Contact

- Operations: `ops@lux.network`
- Security: `security@lux.network`
- Submission package: `mptc@lux.network`

---

**Document metadata**

- Name: `DEPLOYMENT-RUNBOOK.md`
- Version: v0.4 (matches Corona v0.7.5; the unqualified
  `keyera.Bootstrap` and `keyera.BootstrapWithSuite` defaults are
  now routed through `BootstrapPedersen` for symmetry with the
  v0.7.4 Reanchor flip; the legacy trusted-dealer ceremony path is
  reachable only via the explicit `BootstrapTrustedDealer*` /
  `ReanchorTrustedDealer*` names)
- Date: 2026-05-21