docs: update consensus + attestation to released PQ architecture

Bring the user-facing docs in line with the released, semver-tagged post-quantum consensus + confidential-compute architecture, cross-checked against the actual code/tags. Consensus finality (consensus v1.26.0): - Quasar finality is the typed compact-certificate envelope (ConsensusCert), not the old "triple consensus" model. Four evidence kinds (Beam BLS / Pulsar M-LWE / Corona R-LWE / P3Q rollup), orthogonal LegKind x EvidenceMode axes, KeyEra (one group key per era, value-not-place), and the four operator postures (BLS_FAST / HYBRID_PQ_CHECKPOINT / STRICT_QUASAR / RECOVERY_MODE). - Fix the flat error that Pulsar is Ring-LWE: Pulsar is Module-LWE (FIPS-204 ML-DSA, luxfi/pulsar); Corona is Ring-LWE (Ringtail, luxfi/corona). - O(1) compaction (one group sig regardless of committee size). - Correct PQ precompile slots (0x012202/03/04/05) and stale go.mod pins (crypto v1.19.26, pulsar v1.1.5, corona v0.7.9). New page confidential-compute.mdx (+ nav): the luxfi/cc attestation verifier (one Verifier, orthogonal Kinds). Honest vendor matrix: AMD SEV-SNP and NVIDIA nvtrust are production; Intel TDX is a tracked stub. Custody (TEE) vs confidential-AI (NVIDIA GPU) use cases. Decomplect (architecture.mdx, wallet/security.mdx): dealerless PQ-threshold core + optional luxfi/mpc (CGGMP21/FROST) and luxfi/tee custody extensions; the core depends on neither. HSM (hsm/index.mdx, reference/lux-hsm.mdx): document all 16 registered backends (cloud KMS, PKCS#11/KMIP/YubiHSM/Nitrokey, hardware-wallet secure elements, air-gap, ML-DSA PQ, TR-31), the FIPS subset, and the cgo-gated backends. Bridge multi-vendor MPC (mpc/bridge.mdx): layered external-custodian cosigning (Utila/Fireblocks) as an optional institutional feature over native MPC; secrets via KMS; permissionless bridge runs on native MPC alone.
2026-09-24 00:25:32 +00:00 · 2026-06-27 14:31:57 -07:00
parent c843087a73
commit e41ef79c47
12 changed files with 753 additions and 217 deletions
@@ -59,3 +59,47 @@ Lux supports multiple virtual machine implementations:
 | EVM | Ethereum Virtual Machine | Smart contracts |
 | Sovereign L1 EVM | Customizable EVM | Enterprise apps |
 | Custom VMs | Purpose-built VMs | Specialized workloads |
+
+## Post-Quantum Security Architecture
+
+Lux's security model is **decomplected** — one dealerless post-quantum threshold
+core, with custody capabilities added as orthogonal, optional extensions. The
+core depends on **none** of the extensions.
+
+```
+                  ┌──────────────────────────────────────────┐
+                  │   Dealerless PQ-threshold consensus core  │
+                  │   luxfi/consensus · pulsar · corona       │
+                  │   (Quasar compact-cert finality)          │
+                  └──────────────────────────────────────────┘
+                       ▲                 ▲                ▲
+        optional ──────┘        optional ┘       depends on (one-way)
+   ┌─────────────────┐   ┌─────────────────┐   ┌────────────────────────┐
+   │   luxfi/mpc     │   │   luxfi/tee     │   │   luxfi/cc (attest)    │
+   │  MPC custody    │   │  TEE custody    │   │  one attestation       │
+   │  (CGGMP21/FROST)│   │  (attested      │   │  verifier, orthogonal  │
+   │                 │   │   enclave)      │   │  hardware Kinds        │
+   └─────────────────┘   └─────────────────┘   └────────────────────────┘
+```
+
+### One core, optional extensions
+
+- **Consensus core** — Quasar finality is a compact-certificate envelope built on
+  two dealerless-capable PQ threshold kernels: **Pulsar** (Module-LWE, FIPS-204
+  ML-DSA) and **Corona** (Ring-LWE, Ringtail). Corona's natively-dealerless
+  Pedersen DKG carries the permissionless-public guarantee. The core needs no
+  TEE and no external MPC vendor. See [Consensus](/consensus).
+- **`luxfi/mpc`** (v1.16.0) — optional MPC custody for bridge/institutional
+  signing (CGGMP21 for ECDSA, FROST for Schnorr/EdDSA). The consensus core does
+  not depend on it. See [MPC](/mpc) and [Wallet Security](/wallet/security).
+- **`luxfi/tee`** (v0.1.0) — optional TEE-backed threshold-signing *custody*
+  extension. Explicitly **not** required by the threshold core and **not** used on
+  the permissionless/dealerless production signing path; the dependency direction
+  is one-way (`tee → pulsar/corona/mpc`, never the reverse).
+- **`luxfi/cc`** (v0.1.0) — one attestation verifier, with orthogonal hardware
+  `Kind`s, shared by MPC custody, TEE custody, and confidential AI. It depends on
+  none of them. See [Confidential Compute](/confidential-compute).
+
+This is the seam: the permissionless chain runs on the dealerless PQ core alone;
+TEE and external-MPC custody are accelerators an operator opts into, never trust
+assumptions baked into the open validator set.
@@ -15,6 +15,35 @@ The Threshold VM substrate powers **M-Chain** (MPC ceremonies for bridge custody
 - **Multi-Protocol**: Supports multiple threshold protocols via a protocol registry
 - **Quota Management**: Per-chain daily signing limits

+## Threshold Signature Families
+
+Two distinct concerns share the word "threshold" and must not be conflated:
+
+**M-Chain MPC custody (external-wallet bridge signing).** For signing on
+external chains (Bitcoin, Ethereum, etc.) the bridge needs classical curve
+signatures, produced by classical MPC:
+
+| Protocol | Curve / scheme | Use |
+|----------|----------------|-----|
+| **CGGMP21** | secp256k1 ECDSA | Ethereum-compatible + Bitcoin bridge custody |
+| **FROST** | Schnorr / EdDSA (ed25519) | Schnorr-curve custody |
+
+These come from [`luxfi/mpc`](https://github.com/luxfi/mpc) (v1.16.0). They are
+**not** post-quantum — they exist to sign for chains whose validators expect
+classical signatures.
+
+**Consensus PQ threshold legs.** Lux's own [Quasar finality](/consensus) is
+sealed by two **post-quantum** lattice threshold kernels, each emitting one O(1)
+group signature:
+
+| Kernel | Library | Lattice family | Dealerless | FIPS posture |
+|--------|---------|----------------|------------|--------------|
+| **Pulsar (TALUS)** | [`luxfi/pulsar`](https://github.com/luxfi/pulsar) v1.2.0 | Module-LWE (ML-DSA-65) | keygen via committee/ceremony (Pulsar-MPC / Pulsar-TEE) | byte-equal to stock FIPS-204 |
+| **Corona (Ringtail)** | [`luxfi/corona`](https://github.com/luxfi/corona) v0.8.0 | Ring-LWE | natively dealerless (Pedersen DKG) | not FIPS |
+
+Corona's dealerless Pedersen DKG carries the permissionless-public guarantee; see
+[Post-Quantum Security](/post-quantum) for the full TALUS / Ringtail treatment.
+
 ## Configuration

 ```json
@@ -0,0 +1,162 @@
+---
+title: Confidential Compute
+description: One attestation verifier, orthogonal hardware Kinds — TEE/GPU remote attestation for custody and confidential AI on Lux
+icon: ShieldCheck
+---
+
+# Confidential Compute & Attestation
+
+Lux runs a single attestation primitive — **`luxfi/cc`** (`github.com/luxfi/cc`,
+package `attest`) — that verifies hardware-rooted remote attestation evidence
+from CPUs and GPUs. One `Verifier`, a set of orthogonal hardware **Kinds**.
+Everything that needs to prove "this code ran inside genuine, measured
+confidential hardware" goes through it: the MPC custody release gate, the
+optional TEE custody extension, and the confidential-AI / proof-of-AI control
+plane.
+
+<Callout>
+  Attestation is its own orthogonal concern. `luxfi/cc` depends on **none** of
+  its consumers — not `luxfi/mpc`, not `luxfi/tee`, not the AI stack. They
+  depend on it. This is the decomplected seam: one verifier, many callers.
+</Callout>
+
+## One Verifier, Orthogonal Kinds
+
+A `Kind` tags the evidence framing the verifier dispatches to. The caller
+supplies the `Kind` out-of-band (e.g. from an envelope's framing field), so the
+verifier never guesses from byte heuristics.
+
+```go
+// github.com/luxfi/cc/attest
+type Verifier interface {
+    Verify(ctx context.Context, evidence []byte, opts ...Option) (*VerifiedReport, error)
+}
+
+// Dispatch routes evidence to the verifier registered for kind.
+func Dispatch(ctx context.Context, kind Kind, evidence []byte, opts ...Option) (*VerifiedReport, error)
+```
+
+`Verify` means all of: the bytes parse as the claimed `Kind`, the signing key
+chains to the pinned vendor root, the report signature is cryptographically
+valid, and any caller-supplied policy options pass. On any failure the error is
+non-nil and the report pointer is nil — **callers must refuse the originating
+request**. A failed verify never falls back to "best effort".
+
+## Hardware Vendor Matrix
+
+The verifier is a multi-`Kind` framework. The vendors below are the set wired in
+the released `luxfi/cc` v0.1.0 — verified against `attest/verifier.go` and
+`attest/doc.go`.
+
+| Kind | Vendor | Hardware | Status | What is verified |
+|------|--------|----------|--------|------------------|
+| `KindSEVSNP` | `amd.sev.snp` | AMD SEV-SNP CPU | **Production** | Live VCEK fetch from AMD KDS; full ARK → ASK → VCEK chain + report-signature verify (via `google/go-sev-guest`) |
+| `KindNVTrust` | `nvidia.nras.v1` | NVIDIA GPU confidential compute | **Production** (local-RIM, cloud-free) | Parse GPU evidence envelope; verify NVIDIA-signed Reference Integrity Manifest (RIM) against the operator-pinned key; match every reported measurement to its signed golden value |
+| `KindTDX` | `intel.tdx` | Intel TDX CPU | **Landing** (tracked, returns `ErrNotImplemented`) | TDREPORT / quote via `go-tdx-guest` + Intel PCS |
+
+<Callout type="warn">
+  Honest status: AMD SEV-SNP and NVIDIA nvtrust are production verifiers today.
+  Intel TDX is a tracked stub — it returns `ErrNotImplemented` and refuses
+  loudly so a not-yet-implemented verifier can never silently pass. The
+  `Kind` framework is extensible; additional vendors are added by registering a
+  new `Kind` + verifier, not by changing any caller.
+</Callout>
+
+For NVIDIA there are two surfaces: the **local RIM-match** verifier (production,
+no cloud dependency — the operator pins the NVIDIA RIM signing key) and the
+remote `attest/nvidia.NRASClient` primitive that talks to NVIDIA's Remote
+Attestation Service. Device-certificate SPDM chaining is the remote NRAS path;
+the local path covers RIM-signature + measurement integrity.
+
+## The Verified Report
+
+Every successful verify yields a kind-agnostic `VerifiedReport`. The integrity
+anchor is `CompositeHash = sha256(Kind || canonical-verified-bytes)` — a release
+gate, scheduler, or indexer logs this as the attestation root, and two evidences
+with the same composite hash produced byte-identical verifier output.
+
+| Field | Meaning |
+|-------|---------|
+| `Kind` | The verifier that produced the report |
+| `Vendor` | Canonical issuer (`amd.sev.snp`, `intel.tdx`, `nvidia.nras.v1`) |
+| `Measurement` | The launch-measurement the hardware attests to (SEV-SNP 48-byte LD digest; TDX MRTD; NVIDIA per-driver+VBIOS digest) |
+| `ReportData` | The 64-byte caller-supplied challenge field — the caller proved freshness by binding their nonce here **before** attestation |
+| `ChipID` | Silicon identity (SEV-SNP VCEK `CHIP_ID`; TDX PCK descriptor; per-GPU UUID) |
+| `CompositeHash` | `sha256(Kind ‖ canonical bytes)` — the logged attestation root |
+
+## Policy Binding
+
+Verification policy is bound per-call with composable options. The caller binds
+the nonce it issued so the quote cannot be replayed, and pins a known-good
+launch measurement:
+
+```go
+report, err := attest.Dispatch(ctx, attest.KindSEVSNP, evidence,
+    attest.WithExpectedReportData(myNonce),        // refuse if the quote didn't bind my nonce
+    attest.WithExpectedMeasurement(goldenDigest),  // pin a known-good launch digest
+)
+if err != nil {
+    return fmt.Errorf("attestation refused: %w", err) // do NOT release, do NOT fall back
+}
+```
+
+For NVIDIA GPU evidence the operator supplies the signed RIM and the trust roots
+that may sign it; an **empty trust-root set is refused** — there is no insecure
+mode:
+
+```go
+report, err := attest.Dispatch(ctx, attest.KindNVTrust, evidence,
+    attest.WithNVTrustRIM(signedRIM),
+    attest.WithNVTrustTrustRoots(operatorPinnedKeys), // empty set → refuse
+)
+```
+
+### Trust anchors are pinned, never trusted from the evidence
+
+- AMD ARK/ASK ship embedded with `go-sev-guest`; the chain is validated to the
+  AMD root, never to a key carried in the evidence.
+- The NVIDIA RIM signing key is operator-supplied via `WithNVTrustTrustRoots` —
+  no insecure default.
+- Tests never hit the network: AMD KDS responses are pre-fetched and replayed.
+
+## Two Use Cases, One Verifier
+
+The same verifier serves two orthogonal control planes.
+
+<Cards>
+  <Card title="Custody — attested TEE signing">
+    The MPC custody release gate (`luxfi/mpc`) and the optional TEE custody
+    extension (`luxfi/tee`) verify a CPU attestation (`KindSEVSNP` /
+    `KindTDX`) before a signing key share is released into an enclave. The
+    composite hash is the audit root the release decision is logged against.
+  </Card>
+  <Card title="Confidential AI — proof of AI">
+    The confidential-AI control plane verifies a GPU attestation
+    (`KindNVTrust`) to prove an inference or training job ran on a genuine,
+    measured NVIDIA confidential-compute GPU with a known-good driver/VBIOS —
+    the hardware root under proof-of-AI.
+  </Card>
+</Cards>
+
+Neither use case is wired into the permissionless consensus core. Consensus
+finality (see [Consensus](/consensus)) is dealerless and PQ-threshold; TEE is an
+**optional accelerator** for custody, never a trust assumption in the open
+validator set.
+
+## Where It Sits
+
+```
+caller (KMS release gate · scheduler · AI trust-tier policy · indexer)
+  └── cc/attest.Verifier.Verify(ctx, evidence, opts...)      ◄── luxfi/cc
+        ├── SEV-SNP    → google/go-sev-guest + AMD KDS        (production)
+        ├── Intel TDX  → google/go-tdx-guest + Intel PCS      (landing)
+        └── NVIDIA GPU → attest/nvidia RIM-match (local)      (production)
+                         attest/nvidia.NRASClient (remote)    (primitive)
+```
+
+## Further Reading
+
+- [Architecture](/architecture) — the decomplected core + optional custody extensions
+- [Wallet Security](/wallet/security) — MPC custody and the TEE extension model
+- [MPC](/mpc) — CGGMP21 / FROST threshold custody
+- [Post-Quantum](/post-quantum) — why the consensus core needs no TEE
@@ -1,20 +1,23 @@
 ---
 title: Consensus
-description: Quasar — Lux's leaderless, post-quantum, sub-second finality consensus
+description: Quasar — Lux's leaderless, post-quantum, compact-certificate finality
 ---

 # Lux Consensus

 Lux runs **Quasar**, a leaderless DAG-native consensus engine with hybrid
-classical + post-quantum finality. Each round produces a `QuasarCert`
-that combines BLS12-381 aggregate signatures with two independent
-post-quantum proof paths (Pulsar threshold + ML-DSA identity), so a
-break of any single cryptographic primitive does not break finality.
+classical + post-quantum finality. Voting and DAG ordering produce a decision;
+finality is then sealed by a **typed compact-certificate envelope** that binds
+one or more cryptographic *evidence legs* to a single canonical finality
+message. A break of any single primitive does not break finality.
+
+Implementation: [`github.com/luxfi/consensus`](https://github.com/luxfi/consensus)
+`protocol/quasar/` (released **v1.26.0**).

 ## Quasar Sub-Protocols

-Each component owns one concern. They compose into two engine modes
-(linear chains and DAG chains).
+Each component owns one concern. They compose into two engine modes (linear
+chains and DAG chains).

 | Component | Role |
 |-----------|------|
@@ -22,13 +25,13 @@ Each component owns one concern. They compose into two engine modes
 | **Wave** | Per-round threshold voting with FPC (Fast Probabilistic Consensus) tie-breaking |
 | **Focus** | Confidence accumulation: `β` consecutive supermajority rounds yields local finality |
 | **Prism** | DAG geometry: cuts, frontiers, uniform peer sampling |
-| **Horizon** | DAG order theory: reachability, lowest-common-ancestor, transitive closure, skip lists |
+| **Horizon** | DAG order theory: reachability, lowest-common-ancestor, transitive closure |
 | **Flare** | DAG cert / skip classification via 2f+1 quorum |
 | **Ray** | Linear-chain finality driver (Wave + Focus + Sink) |
 | **Field** | DAG finality driver (Wave + safe-prefix commit) |
 | **Nova** | Linear-chain consensus mode — wraps Ray |
 | **Nebula** | DAG consensus mode — wraps Field |
-| **Quasar** | Threshold signing + epoch management (BLS + Pulsar + ML-DSA) |
+| **Quasar** | Compact-certificate finality: evidence legs + KeyEra + policy postures |

 ### Round flow

@@ -36,103 +39,130 @@ Each component owns one concern. They compose into two engine modes

 **DAG (Nebula):** Photon → Wave (per frontier vertex) → Flare → Horizon (safe prefix) → Field → Committer

-## QuasarCert: Hybrid Finality
+## Finality: the Compact-Certificate Envelope

-Each finalized round emits a `QuasarCert`:
+Finality is a `ConsensusCert` — a policy-gated aggregate quorum certificate.
+**Policy** declares which cryptographic legs are required; **certificate bytes**
+carry per-leg evidence; every leg proves the *same* weighted-quorum predicate
+over the *same* domain-separated finality message `M`.

-```go
-type QuasarCert struct {
-    BLS        []byte    // BLS12-381 aggregate (~48 B classical fast path)
-    Pulsar   []byte    // Pulsar/Ring-LWE 2-round threshold proof (~33 KB PQ)
-    MLDSAProof []byte    // Z-Chain Groth16 rollup of N × ML-DSA identity sigs (~192 B)
-    Epoch      uint64
-    Finality   time.Time
-    Validators int
-}
+The signed message `M` binds the full consensus tuple — chain id, epoch, height,
+round, block hash, validator-set root, policy id, required-legs root, signer
+root, cert profile — never the block hash alone. Required legs come from policy
+**only**, never from the certificate's own bytes; the cert's required-legs root
+is recomputed from policy and any mismatch is a hard reject.
+
+### Four evidence kinds
+
+The chain stores **one compact typed evidence per lane**, never N raw
+per-validator signatures.
+
+| Evidence kind | Family | Shape | Role |
+|---------------|--------|-------|------|
+| **Beam** | BLS12-381 (classical) | one aggregate | Fast classical aggregate |
+| **Pulsar** | Module-LWE, FIPS-204 ML-DSA (TALUS) | one threshold signature | Compact PQ threshold leg |
+| **Corona** | Ring-LWE (Ringtail), dealerless | one threshold signature | Second, independent PQ lattice leg |
+| **P3Q** | rollup over independent ML-DSA certs | root/proof over a cert set | Fallback (migration / recovery / bridge / audit) |
+
+Beam, Pulsar, and Corona are **O(1) in committee size** — one signature each.
+P3Q is the only O(N)-class object and is a fallback, never the normal finality
+object when a compact Pulsar leg is available.
+
+### Two orthogonal axes (decomplected)
+
+A leg's **kind** (what requirement it satisfies) and its **mode** (how that
+requirement is proven) are orthogonal and never braided:
+
+| Evidence kind | Leg kind (what) | Evidence mode (how) |
+|---------------|-----------------|---------------------|
+| Beam | `LegClassical` | `ClassicalAggregate` |
+| Pulsar | `LegPulsarMLDSA` | `ThresholdSig` |
+| Corona | `LegCoronaLattice` | `ThresholdSig` |
+| P3Q | `LegPulsarMLDSA` | `P3QRollup` |
+
+Pulsar and P3Q satisfy the **same** leg kind (the Module-LWE ML-DSA PQ-finality
+requirement) by **different** mechanisms — that is exactly the policy "OR":
+one required leg kind, two permitted modes.
+
+### KeyEra — one group key per era
+
+A threshold leg for a 1000-validator committee is **one** signature under **one
+group public key**, not 1000 per-validator signatures. A `KeyEra` is the
+registry record that pins that single group key to one validator-set era: which
+chain, which P-Chain-pinned signer set, which key-era id + generation, which
+scheme/parameter set.
+
+`KeyEra` is a *value qualified by its scheme*, not a place: **one** type and
+**one** boring verifier (`VerifyThresholdLeg`) serve **every** threshold lane —
+Pulsar (FIPS-204 ML-DSA group signature) and Corona (Ringtail). The chain does
+not care *how* the group signature was produced (TALUS MPC, an HSM ceremony, a
+TEE, or P3Q fallback); that is recorded in the era's `KeygenMode` for audit and
+is orthogonal to verification. The verifier stays in its lane: group sig, group
+key, `M`.
+
+### Compactness
+
+ML-DSA-65 signatures are ~3.3 KB each. A naive per-validator certificate is
+`48 + N × 3309` bytes — linear in validator count. The compact threshold leg
+replaces the `N × 3309` term with a **single** group signature, so the
+certificate for 1000 validators is the same size as for 4 — roughly **three
+orders of magnitude smaller** at 1000 validators.
+
+```
+naive O(N) cert  @ N=1000:  48 + 1000 × 3309  ≈ 3.3 MB
+compact O(1) cert:          one ML-DSA-65 group sig (~3.3 KB) + envelope header
 ```

-| Layer | Hardness | Role | Size |
-|-------|----------|------|------|
-| BLS12-381 aggregate | Classical co-CDH | Fast path | 48 B |
-| Pulsar (Ring-LWE) | Module-LWE | PQ threshold | ~33 KB |
-| ML-DSA-65 → Groth16 | Module-LWE + MSIS | PQ identity rollup | ~192 B |
+## Finality Postures (Policy Table)

-A QuasarCert verifies if **and only if** the configured layers all
-verify. Each layer is independently toggleable:
+The operator selects a finality posture per chain. Each posture is a concrete
+policy the envelope verifies under; the required leg **kinds** are committed into
+the cert's required-legs root, and the permitted **modes** live in the policy's
+allow-table.

-| Mode | Composition | Use case |
-|------|-------------|----------|
-| `BLSOnly` | BLS only | Classical fast path |
-| `BLSPlusMLDSA` | BLS + per-validator ML-DSA | Identity-bound PQ |
-| `BLSPlusCorona` | BLS + Pulsar threshold | Threshold-only PQ |
-| `BLSPlusGroth16` | BLS + Z-Chain Groth16 rollup | Compact PQ identity |
-| `TripleQuantum` | All three layers in parallel | Full Quasar |
+| Posture | Requires | Use case |
+|---------|----------|----------|
+| `BLS_FAST` | Beam only | Mempool / fast local block acceptance |
+| `HYBRID_PQ_CHECKPOINT` | Beam ∧ (Pulsar **or** P3Q) | Checkpoints: a compact Pulsar leg, or the P3Q fallback |
+| `STRICT_QUASAR` | Beam ∧ Pulsar ∧ Corona | Full dual-lattice **AND-mode** strict finality |
+| `RECOVERY_MODE` | Beam ∧ P3Q | Recovery / migration / bridge: independent ML-DSA certs, no Pulsar key |

-Selectable at runtime via the `CONSENSUS_PQ_MODE` env var or
-`config.PQMode` field.
-
-## Pulsar (Threshold Layer)
-
-The Pulsar layer is implemented by **Pulsar**
-(`github.com/luxfi/pulsar/threshold`) — Lux's variant with DKG2 and the
-Pulsar-SHA3 hash suite (KMAC over cSHAKE256, NIST SP 800-185).
-
-| Parameter | Value | Meaning |
-|-----------|-------|---------|
-| `M` | 8 | Module rank |
-| `N` | 7 | Min signers (threshold = 6 of 8) |
-| `LogN` | 8 | Ring degree = 256 |
-| `Q` | 0x1000000004A01 | 48-bit NTT-friendly prime |
-| Security (classical / quantum) | 2^142 / 2^130 | BDGL sieving + Grover |
-
-## Measured performance (Apple M1 Max, single round)
-
-| Mode | Sign | Aggregate | Verify | Cert | 10K certs |
-|------|------|-----------|--------|------|-----------|
-| BLS-only | 312 µs | 8.6 ms | 714 µs | 123 B | 1.17 MB |
-| BLS + ML-DSA | 369 µs | 8.5 ms | 3.4 ms | 69 KB | 665 MB |
-| BLS + Pulsar | 39 ms | 3.3 s | 1.6 ms | 33 KB | 318 MB |
-| Triple Quantum | 40 ms | 3.3 s | 4.3 ms | 102 KB | 981 MB |
-
-ZAP wire protocol (zero-copy, replaces JSON-RPC for inter-node messages):
-single-conn 114K TPS, 50 conns + batch 1000 = 20.26M TPS.
+In `STRICT_QUASAR`, Beam, Pulsar, and Corona all sign **one** canonical message
+`M` under **one** P-Chain-pinned era (AND-mode). A classical-only certificate is
+rejected under any posture that requires a PQ leg; classical evidence can satisfy
+only the classical leg and can never stand in for a required PQ leg.

 ## Properties

-**Liveness.** Round driver makes progress whenever a 2f+1 fraction of
-the network is reachable. No single leader.
+**Liveness.** The round driver makes progress whenever a 2f+1 fraction of the
+network is reachable. No single leader.

 **Safety.** Holds whenever fewer than f Byzantine validators participate
-(committee size 3f+1). The classical layer (BLS) and post-quantum
-layers (Pulsar / ML-DSA) sign the same payload, so an adversary that
-breaks one primitive still has to defeat the other layers.
+(committee size 3f+1). Every required leg signs the same domain-separated `M`,
+so an adversary that breaks one primitive still has to defeat the others.

-**PQ safety.** Even an attacker with full quantum capability cannot
-forge a triple-mode cert without breaking *both* Ring-LWE (Pulsar) and
-ML-DSA simultaneously — see [LP-105 §7](https://github.com/luxfi/lps/blob/main/LPs/lp-0110-quasar-consensus.md)
-and `~/work/lux/proofs/quasar-cert-soundness.tex` App. E for the
-parameter-tightness argument.
+**PQ safety.** Under `STRICT_QUASAR`, forging a certificate requires breaking
+**both** Module-LWE (Pulsar / ML-DSA) **and** Ring-LWE (Corona) simultaneously,
+in addition to BLS — two independent lattice families plus the classical leg.

-**Scalability.** Per-node communication is O(k) per round (committee
-size, not validator-set size). Quasar scales to thousands of validators
-without degrading finality.
+**Scalability.** Threshold legs are O(1) in committee size; the certificate does
+not grow with the validator set. Quasar scales to thousands of validators
+without degrading finality or cert size.

 ## Chain assignments

 | Chain | Engine | Why |
 |-------|--------|-----|
 | C-Chain (EVM) | Nova (linear) | Sequential smart-contract execution |
-| P-Chain (platform) | Nova (linear) | Ordered validator-set + staking transitions |
+| P-Chain (platform) | Nova (linear) | Ordered validator-set + staking transitions; pins signer-set eras |
 | X-Chain (UTXO) | Nebula (DAG) | High-throughput parallel asset transfers |
-| Q-Chain | Pulsar 2-round threshold | PQ consensus signing for Quasar |
-| M-Chain | CGGMP21 / FROST / Pulsar-general MPC | Bridge custody for external wallets, threshold signing ceremonies |
-| F-Chain | TFHE bootstrap-key generation, FHE compute | Encrypted EVM, encrypted ML inference |
-| Z-Chain | Groth16 over BLS12-381 | Roll N × ML-DSA-65 sigs into 192-byte proof |
+| M-Chain | MPC ceremonies (CGGMP21 / FROST) | Bridge custody for external wallets (per LP-134) |
+| F-Chain | FHE compute + TFHE bootstrap-key generation | Encrypted EVM, encrypted ML inference (per LP-134) |

 ## Further reading

- [LP-110 Quasar Consensus](https://github.com/luxfi/lps/blob/main/LPs/lp-0110-quasar-consensus.md)
- [LP-113 Wave Voting](https://github.com/luxfi/lps/blob/main/LPs/lp-0113-wave-voting.md)
- [LP-115 Horizon Finality](https://github.com/luxfi/lps/blob/main/LPs/lp-0115-horizon-finality.md)
+- [Post-Quantum Security](/post-quantum) — Pulsar (TALUS) and Corona (Ringtail) in depth
+- [Lux Quasar reference](/reference/lux-quasar) — the cert envelope, suites, and verifier
+- [Threshold VM](/chains/thresholdvm) — M-Chain MPC and F-Chain FHE
 - [`github.com/luxfi/consensus`](https://github.com/luxfi/consensus) — the implementation
- [Run a validator](/nodes/validator)
+- [Run a validator](/nodes)
@@ -5,7 +5,12 @@ index: true
 icon: ShieldCheck
 ---

-Lux HSM provides a single Go interface for signing and verification across five different backend providers — from cloud HSMs to post-quantum algorithms. All secrets are managed through [Lux KMS](/kms) — never stored as plaintext.
+Lux HSM (`github.com/luxfi/hsm`) provides a single Go interface (`Signer`) for
+signing and verification across **sixteen** backend providers — cloud KMS/HSM,
+networked and USB HSMs, hardware-wallet secure elements, air-gapped devices,
+banking key-blocks, and post-quantum ML-DSA. One factory, one interface, many
+backends. All secrets are managed through [Lux KMS](/kms) — never stored as
+plaintext.

 ## Core Interfaces

@@ -23,14 +28,58 @@ type PasswordProvider interface {

 ## Signing Providers

-| Provider | Algorithm | Use Case |
-|----------|-----------|----------|
-| `aws` | ECDSA P-256 via KMS | Production cloud signing |
-| `gcp` | EC_SIGN_P256_SHA256 | Production cloud signing |
-| `azure` | ES256 via Key Vault | Production cloud signing |
-| `zymbit` | ECDSA P-256 via Zymbit SCM | Edge/IoT hardware signing |
-| `mldsa` | ML-DSA-65 (FIPS 204) | Post-quantum signing |
-| `local` | ECDSA P-256 in-memory | Development and testing |
+All sixteen are registered in one factory — `hsm.NewSigner(provider, config)`.
+
+### Cloud KMS / HSM
+
+| Provider | Backend | Algorithm |
+|----------|---------|-----------|
+| `aws` | AWS KMS / CloudHSM | ECDSA P-256 (SigV4, no SDK) |
+| `gcp` | Google Cloud KMS | EC_SIGN_P256_SHA256 |
+| `azure` | Azure Key Vault / Managed HSM | ES256 |
+| `kmip` | Any KMIP 1.x HSM (Thales, Entrust, …) | KMIP `Sign` (requires cgo) |
+
+### Networked / USB HSM
+
+| Provider | Backend | Notes |
+|----------|---------|-------|
+| `pkcs11` | Any PKCS#11 token (Thales Luna, SoftHSM, …) | Universal HSM standard (requires cgo) |
+| `yubihsm` | YubiHSM 2 | aliases `yubico`, `yubi` |
+| `nitrokey` | Nitrokey HSM | OpenPGP/PKCS#11 secure element |
+| `zymbit` | Zymbit SCM / HSM6 | Edge/IoT; native threshold (`ThresholdHSM`) |
+
+### Hardware-wallet secure elements
+
+| Provider | Device |
+|----------|--------|
+| `ledger` | Ledger (Nano S/X/Stax) |
+| `trezor` | Trezor |
+| `coldcard` | Coldcard |
+| `keystone` | Keystone (air-gap QR) |
+| `gridplus` / `lattice` | GridPlus Lattice1 (SafeCard) |
+| `ngrave` | NGRAVE ZERO |
+| `foundation` | Foundation Passport |
+
+### Software, banking & post-quantum
+
+| Provider | Algorithm | Use |
+|----------|-----------|-----|
+| `mldsa` / `pq` / `post-quantum` | ML-DSA-44 / 65 / 87 (FIPS 204) | Post-quantum signing |
+| `tr31` | ANSI X9.143 / TR-31 key blocks | Banking / payments key wrapping |
+| `local` / `""` | ECDSA P-256 in-memory | Development and testing only |
+
+<Callout type="warn">
+  **FIPS posture.** `hsm.RequireFIPSProvider` admits only the FIPS-validated
+  backends: `aws`, `gcp`, `azure`, `yubihsm`, `pkcs11`, `kmip`. Wire it before
+  constructing a signer to fail closed on a non-FIPS provider. `local` is
+  development only — never production.
+</Callout>
+
+<Callout>
+  Build notes: `pkcs11` and `kmip` link a native library and require **cgo** (a
+  no-cgo build falls back to a stub that refuses to sign). The GridPlus Lattice1
+  Connect-API path is partial — track its status before production use.
+</Callout>

 ## Password Providers

@@ -82,13 +131,13 @@ func main() {
 │           │                     │            │
 │  ┌────────▼─────────────────────▼─────────┐ │
 │  │         Factory (NewSigner / etc)       │ │
-│  └────┬────┬────┬────┬────┬────┬──────────┘ │
-│       │    │    │    │    │    │             │
-│      AWS  GCP Azure Zymbit MLDSA Local      │
+│  └────┬───────────┬───────────┬───────────┘ │
+│       │           │           │              │
+│   Cloud KMS   Networked/    Hardware-wallet  │
+│   AWS·GCP·    USB HSM       secure elements  │
+│   Azure·KMIP  PKCS11·Yubi·  Ledger·Trezor·   │
+│               Nitro·Zymbit  Coldcard·...     │
+│                                              │
+│            + mldsa (PQ) · tr31 · local       │
 └─────────────────────────────────────────────┘
-         │    │    │    │
-    ┌────▼────▼────▼────▼────┐
-    │   Cloud / Hardware /    │
-    │   Software Backends     │
-    └─────────────────────────┘
 ```
@@ -32,6 +32,7 @@
    "hsm",
    "kms",
    "mpc",
+    "confidential-compute",
    "fhe",
    "lattice",
    "---Smart Contracts---",
@@ -24,6 +24,41 @@ The Lux Bridge uses MPC for threshold signing of cross-chain transfers. Each bri
 | CGGMP21 | secp256k1 | Ethereum, Lux, all EVM chains |
 | FROST | secp256k1 | Bitcoin (Taproot) |

+The native MPC threshold signature is the **complete, permissionless** signing
+path — it is sufficient on its own and requires no external custodian.
+
+## Layered External-Custodian Cosigning (optional, institutional)
+
+Regulated and institutional flows can require an **external custodian** to
+co-sign on top of the native MPC signature. This is opt-in compatibility for
+tenants who must keep a regulated custodian (e.g. Utila or Fireblocks) in the
+approval path; it is **not** part of the public permissionless bridge.
+
+| Vendor | Auth | Role |
+|--------|------|------|
+| **Utila** | service-account PEM | external approval workflow |
+| **Fireblocks** | RS256 JWT (API key + signed PEM) | external RAW-sign approval |
+
+How it composes, per swap:
+
+1. The SDK declares the required cosigners by **public identifier only**
+   (`org_id`, `api_key`, vault ids) — secret material **never crosses the wire**.
+2. The native MPC network produces its threshold signature first.
+3. Each declared custodian independently attests to the **same** transaction hash.
+4. **All listed must approve** — any rejection fails the swap.
+
+The custodian secret (Utila PEM, Fireblocks signing key) is fetched at dispatch
+time from **KMS**, keyed by the public identifier — never stored in the swap
+record and never sent by the client. The vendor set is an extensible family
+(adding one is a new `Kind` + dispatcher branch).
+
+<Callout>
+  Scope: external-custodian cosigning targets regulated/institutional custody.
+  The permissionless bridge runs on native MPC alone. The cosigner orchestration
+  is being decomplected into a standalone module so the permissionless bridge
+  carries none of it — see the architecture note on `luxfi/cosigner`.
+</Callout>
+
 ## Bridge Architecture

 ```
@@ -145,17 +145,61 @@ For existing users and applications:
  </Card>
 </Cards>

-## Quasar Consensus
+## Parallel Post-Quantum: Pulsar ∥ Corona

-Lux's Quasar consensus uses a **triple consensus** signature scheme combining three independent cryptographic families -- classical (BLS) and two post-quantum (Pulsar + ML-DSA):
+Quasar finality (see [Consensus](/consensus)) is sealed by a compact-certificate
+envelope whose post-quantum strength rests on **two independent lattice
+families**, each contributing one O(1) threshold signature:

-| Scheme | Family | Purpose |
-|--------|--------|---------|
-| BLS (BLS12-381) | Pairing-based (classical) | Aggregatable validator signatures for efficient block finalization |
-| Pulsar | Ring-LWE (post-quantum) | Threshold consensus signatures with lattice-based security |
-| ML-DSA-65 | FIPS 204 (post-quantum) | Per-validator identity signatures with Module-LWE security |
+| Leg | Library | Lattice family | Dealerless? | FIPS posture |
+|-----|---------|----------------|-------------|--------------|
+| **Pulsar** | [`luxfi/pulsar`](https://github.com/luxfi/pulsar) v1.2.0 | Module-LWE (ML-DSA-65) | keygen via committee / ceremony | **stock FIPS-204** — verifies under an unmodified ML-DSA verifier |
+| **Corona** | [`luxfi/corona`](https://github.com/luxfi/corona) v0.8.0 | Ring-LWE (Ringtail) | **natively dealerless** (Pedersen DKG) | not FIPS — a distinct lattice construction |

-All three paths run in parallel via `TripleSignRound1`. A **QuasarCert** is the finality certificate containing a BLS aggregate signature and aggregated PQ proof (Pulsar + ML-DSA). Blocks are final only when all three certificates verify. An attacker must break ECDL (BLS), Module-LWE (ML-DSA), and Module-SIS (Pulsar) simultaneously to forge a consensus vote.
+Under the `STRICT_QUASAR` posture both legs sign **one** canonical finality
+message under **one** P-Chain-pinned key-era (AND-mode), alongside the classical
+BLS aggregate. Forging finality means breaking **both** Module-LWE and Ring-LWE
+simultaneously — two unrelated lattice problems, not one.
+
+### Pulsar = TALUS threshold ML-DSA
+
+Pulsar's TALUS construction produces a threshold ML-DSA-65 signature that is
+**byte-identical to a single-party FIPS-204 signature** on the same message and
+public key — so a verifier needs no special threshold logic. It is built from a
+dealerless Shamir nonce DKG, a distributed `w1` derivation (CEF), and a real
+secure-comparison circuit (**CSCP**).
+
+<Callout>
+  **W-LEAK closed.** Earlier threshold-ML-DSA sketches leaked the rejection-
+  sampling boundary because a node had to form the `w0`/`w` decomposition in the
+  clear. Pulsar v1.2.0 replaces that with a real CSCP secure-comparison circuit:
+  no single node forms `w0`/`w`, and a mandatory verify-before-release step
+  prevents both forgery and leakage. CSCP is semi-honest — a malicious deviation
+  costs liveness only, never key material.
+</Callout>
+
+**The honest framing.** The known impossibility is *FROST-style additive*
+threshold ML-DSA, not threshold ML-DSA in general — TALUS routes around it with
+binding-commit (BCC) + CEF rather than additive nonce sharing. But a fully
+*dealerless key DKG* for ML-DSA is genuinely unreachable: an additive sum of
+FIPS secrets breaks the `S_η` norm bound (proven), so Pulsar key generation is a
+committee/ceremony step. Pulsar ships two custody profiles for that step —
+**Pulsar-MPC** (honest-majority N ≥ 2T−1) and **Pulsar-TEE** (attested enclave).
+Because Pulsar keygen is not dealerless, **Corona carries the dealerless,
+permissionless-public PQ guarantee**: Ringtail's Pedersen DKG needs no trusted
+dealer, which is what makes it sound for an open validator set.
+
+### Hybrid identity & transport
+
+Post-quantum strength is layered on classical primitives, never a clean
+replacement:
+
+- **Transport.** Node-to-node PQ-TLS 1.3 uses the **X-Wing** hybrid KEM
+  (X25519 + ML-KEM-768, negotiated as `X25519MLKEM768`) — Go 1.26's default.
+  Breaking it requires breaking both X25519 and ML-KEM-768.
+- **Identity.** Validator and account identity bind a classical key with
+  **ML-DSA-65** (hybrid signatures), so an identity forgery requires breaking
+  both the classical and the lattice scheme.

 ## Smart Account PQ Signing

@@ -163,11 +207,16 @@ EVM smart accounts (ERC-4337 / Safe) can verify post-quantum signatures on-chain

 | Precompile | Address | Purpose |
 |-----------|---------|---------|
-| `ML-DSA Verify` | `0x0b14` | Verify ML-DSA-65 signatures in Solidity |
-| `SLH-DSA Verify` | `0x0b15` | Verify SLH-DSA signatures in Solidity |
-| `Pulsar Verify` | `0x0b16` | Verify Pulsar ring signatures in Solidity |
+| `ML-DSA Verify` | `0x012202` | Verify single-party ML-DSA-65 (FIPS 204) signatures in Solidity |
+| `SLH-DSA Verify` | `0x012203` | Verify SLH-DSA (FIPS 205) signatures in Solidity |
+| `Pulsar Verify` | `0x012204` | Verify a Pulsar Module-LWE threshold signature (byte-equal to FIPS 204) |
+| `P3Q Verify` | `0x012205` | Rollup-commit verifier; kind-byte dispatch to Pulsar / Corona / Magnetar |

-The `SafeMLDSASigner` module implements ERC-1271 signature verification using ML-DSA-65, allowing Safe multisig wallets to authorize transactions with post-quantum keys. This works on the C-Chain and all sovereign L1 EVM chains with PQ precompiles enabled.
+See [PQ Crypto Precompiles](/precompile/pq-crypto) for the full slot map and gas
+schedule. The `SafeMLDSASigner` module implements ERC-1271 signature
+verification using ML-DSA-65, allowing Safe multisig wallets to authorize
+transactions with post-quantum keys. This works on the C-Chain and all sovereign
+L1 EVM chains with PQ precompiles enabled.

 ```solidity
 // Safe module: verify ML-DSA-65 via precompile
@@ -5,7 +5,7 @@ description: "Lux Quasar -- Post-Quantum Consensus Engine"

 ## Overview

-Lux Quasar is the consensus engine for the Lux network. It is a unified, leaderless, post-quantum protocol achieving sub-second 2-round finality with triple-certificate security (BLS12-381 aggregate signatures + Pulsar lattice-based threshold signatures + ML-DSA-65 identity signatures). All three paths run in parallel via `TripleSignRound1`. Quasar runs every chain in the Lux primary network -- Q, C, X, P -- and any dynamically registered chain.
+Lux Quasar is the consensus engine for the Lux network. It is a unified, leaderless, post-quantum protocol achieving sub-second finality. Finality is sealed by a **typed compact-certificate envelope** (`ConsensusCert`) that binds one or more cryptographic evidence legs — **Beam** (BLS12-381 classical aggregate), **Pulsar** (Module-LWE / FIPS-204 ML-DSA threshold), **Corona** (Ring-LWE / Ringtail threshold), and **P3Q** (rollup fallback) — to one canonical, domain-separated finality message under one P-Chain-pinned key-era. Quasar runs every chain in the Lux primary network -- C, X, P -- and any dynamically registered chain. See the [Quasar reference](/reference/lux-quasar) for the envelope, suites, and postures.

 **This is an original consensus protocol** built from first principles around Photonic Selection -- not derived from earlier metastable voting schemes.

@@ -29,7 +29,7 @@ There are two code locations:

 | Engine | Type | Location | Purpose | Status |
 |--------|------|----------|---------|--------|
-| **Quasar** | Triple PQ | `protocol/quasar/` + `node/consensus/quasar/` | Primary consensus for all chains. Triple BLS+Pulsar+ML-DSA signatures run in parallel via `TripleSignRound1`. 2-round finality. | Production |
+| **Quasar** | Compact-cert PQ | `protocol/quasar/` + `node/consensus/quasar/` | Primary finality for all chains. Compact-certificate envelope binding Beam (BLS) + Pulsar (M-LWE) + Corona (R-LWE) + P3Q legs to one message. Sub-second finality. | Production |
 | **Nova** | Linear chain | `protocol/nova/` | Linear blockchain consensus mode. Wraps the Ray driver with Wave voting. Used for C-Chain and P-Chain style linear progression. | Production |
 | **Wave** | Threshold voting | `protocol/wave/` | Core voting mechanism. Samples K peers, collects votes, checks alpha threshold, builds beta confidence. Supports FPC (Fast Probabilistic Consensus) for dynamic thresholds. | Production |
 | **Ray** | Linear driver | `protocol/ray/` | Low-level engine that drives Wave voting for linearly-ordered items. Source/Sink pattern. Nova wraps this. | Production |
@@ -42,7 +42,7 @@ There are two code locations:

 ## Quasar Algorithm -- Detailed Steps

-Quasar achieves triple quantum finality through parallel execution of classical and post-quantum signature paths (BLS + Pulsar + ML-DSA). The full algorithm:
+Quasar reaches a leaderless decision through photonic committee selection and Wave voting, then seals it with the compact-certificate envelope (Beam ∧ Pulsar ∧ Corona under `STRICT_QUASAR`). The full algorithm:

 ### Phase 0: Photonic Selection (Committee Formation)

@@ -61,38 +61,43 @@ Quasar achieves triple quantum finality through parallel execution of classical
 4. **FPC mode** (optional): Instead of fixed alpha, threshold theta is selected per-phase using a PRF over `[theta_min=0.5, theta_max=0.8]`, making the protocol more resistant to adaptive adversaries.
 5. Classical finality typically completes in 600-700ms.

-### Phase 2: QuasarCert Generation (Quantum Finality)
+### Phase 2: Compact-Certificate Finality

-All three paths execute **in parallel** immediately after classical decision (via `TripleSignRound1`):
+After the classical decision, finality is sealed by a `ConsensusCert` envelope.
+**Policy** declares the required cryptographic legs; certificate bytes carry the
+per-leg evidence; every leg proves the same weighted-quorum predicate over the
+same domain-separated finality message `M`. The chain stores **one compact typed
+evidence per lane**, never N raw per-validator signatures:

-**BLS Path (fast, classical):**
-1. Each validator signs the finality message (blockID + height + timestamp, 48 bytes) with their BLS12-381 key share.
-2. Signature shares are aggregated into a single 96-byte aggregate signature.
-3. Verification: reconstruct aggregate public key from signer bitset, verify aggregate signature.
-4. Requires 2/3+ validator weight.
+| Evidence kind | Family | Shape |
+|---------------|--------|-------|
+| **Beam** | BLS12-381 (classical) | one aggregate |
+| **Pulsar** | Module-LWE ML-DSA (TALUS) | one threshold signature |
+| **Corona** | Ring-LWE (Ringtail), dealerless | one threshold signature |
+| **P3Q** | rollup over independent ML-DSA certs | root/proof over a cert set (fallback) |

-**Pulsar Path (quantum-safe, 2-round):**
-1. **Round 1**: Each participating validator generates commitments (D matrix + MACs) using their Pulsar key share. Broadcast `Round1Data` to all other signers.
-2. **Round 2**: Each validator computes partial signatures using collected Round 1 data. Broadcast `Round2Data`.
-3. **Finalize**: Any validator aggregates Round 2 data into a threshold signature. Verify against the group public key.
-4. Requires t-of-n threshold (typically 2/3+1).
-5. Pulsar adds approximately 200-300ms for quantum finality.
+The operator selects a finality posture per chain. Each posture pins required
+leg **kinds** (committed into the cert's required-legs root) and permitted
+**modes** (in the policy allow-table):

-**ML-DSA Path (quantum-safe, identity proof):**
-1. Each validator signs the finality message with their ML-DSA-65 key (FIPS 204).
-2. ML-DSA signatures provide per-validator post-quantum identity binding.
-3. Aggregated alongside Pulsar into the PQ proof field of QuasarCert.
+| Posture | Requires |
+|---------|----------|
+| `BLS_FAST` | Beam |
+| `HYBRID_PQ_CHECKPOINT` | Beam ∧ (Pulsar **or** P3Q) |
+| `STRICT_QUASAR` | Beam ∧ Pulsar ∧ Corona (AND-mode) |
+| `RECOVERY_MODE` | Beam ∧ P3Q |

-**Block is final ONLY when all three certificates are valid:**
 ```go
-type CertBundle struct {
-    BLSAgg []byte  // 96B BLS aggregate signature
-    PQCert []byte  // Aggregated Pulsar + ML-DSA proof
-}
-
-isFinal := verifyBLS(blsAgg, quorum) && verifyPQ(pqCert, quorum)
+// A block is final iff every leg REQUIRED BY POLICY verifies over the same M.
+// Required legs come from policy ONLY, never from the certificate bytes.
+err := quasar.VerifyConsensusCert(cert, policy, validators, M)
+isFinal := err == nil
 ```

+Threshold legs (Pulsar, Corona) are O(1) in committee size — one group signature
+under one `KeyEra` group key regardless of validator count. A classical-only
+certificate is rejected under any posture that requires a PQ leg.
+
 ### Quantum Bundle Architecture (Async PQ Anchoring)

 For high-throughput scenarios, Quasar uses an async two-layer architecture:
@@ -138,7 +143,7 @@ For large validator sets, `GroupedEpochManager` splits validators into groups (d
 | **Post-quantum** | Security rests on lattice SVP hardness (2^160 operations). Both Pulsar threshold and ML-DSA identity signatures remain secure. |
 | **Attack window** |  &lt;= PQ round time ( &lt;=50ms on mainnet). |

-All three proofs (BLS, Pulsar, ML-DSA) are **REQUIRED** for Q-Chain validators in triple mode. `IsTripleMode()` returns true when all three are configured. The `Verify` method enforces strict triple-proof validation.
+Under the `STRICT_QUASAR` posture, the Beam, Pulsar, and Corona legs are all **REQUIRED** and verified over one canonical message `M`. Required legs come from policy only; the `VerifyConsensusCert` envelope rejects a certificate that is missing any required leg, or that offers classical evidence in place of a required PQ leg.

 ## Validator Selection and Identity

@@ -160,7 +165,7 @@ Performance-based weighting: successful consensus participation increases bright
 |-------|----------|---------|---------|
 | Node-ID | ed25519 | P2P transport authentication | `$HOME/.lux/node.key` |
 | Validator-BLS | BLS12-381 | Fast finality votes (classical) | `$HOME/.lux/bls.key` |
-| Validator-PQ | Pulsar (Ring-LWE) | Post-quantum threshold shares | `$HOME/.lux/rt.key` |
+| Validator-PQ | Pulsar (Module-LWE) / Corona (Ring-LWE) | Post-quantum threshold shares | `$HOME/.lux/rt.key` |
 | Validator-MLDSA | ML-DSA-65 (FIPS 204) | Post-quantum identity signatures | `$HOME/.lux/mldsa.key` |
 | Wallet (EVM) | secp256k1 or Lamport-XMSS | User transaction signatures | In wallet |
 | Wallet (X-Chain) | secp256k1 or ML-DSA | UTXO locking | In wallet |
@@ -181,16 +186,28 @@ DIDs generate full W3C DID Documents with verification methods, authentication,

 ## Post-Quantum Cryptography

-### Pulsar Threshold Signatures
+### Two PQ threshold kernels — Pulsar (M-LWE) and Corona (R-LWE)

- **Basis**: Ring-LWE (Ring Learning With Errors)
- **Protocol**: Native 2-round threshold signing
- **Library**: `github.com/luxfi/corona` v0.2.0
- **Round 1**: Generate D matrix + MACs, broadcast commitments
- **Round 2**: Compute partial signatures using collected Round 1 data
- **Finalize**: Aggregate partial signatures into threshold signature
+Quasar's post-quantum strength rests on **two independent lattice families**,
+each emitting one O(1) group signature. They are independent libraries with no
+import line between them; Quasar consumes them as parallel kernels.
+
+**Pulsar (TALUS)** — [`github.com/luxfi/pulsar`](https://github.com/luxfi/pulsar) v1.2.0
+
+- **Basis**: Module-LWE (ML-DSA-65, FIPS 204)
+- **Output**: threshold signature **byte-identical to a single-party FIPS-204
+  ML-DSA signature** — verifies under an unmodified ML-DSA verifier
+- **Construction**: dealerless Shamir nonce DKG + distributed `w1` (CEF) + real
+  CSCP secure-comparison (the W-LEAK is closed — no node forms `w0`/`w` in clear)
+- **Keygen profiles**: Pulsar-MPC (honest-majority N ≥ 2T−1) / Pulsar-TEE
+- **Verification**: `pulsarwire.VerifyBytes`
+
+**Corona (Ringtail)** — [`github.com/luxfi/corona`](https://github.com/luxfi/corona) v0.8.0
+
+- **Basis**: Ring-LWE (Ringtail; BKLMTT, ePrint 2024/1113)
+- **Dealerless**: native Pedersen DKG over `R_q` + proactive resharing — carries
+  the permissionless-public PQ guarantee (not FIPS)
 - **Verification**: `coronaThreshold.Verify(groupKey, message, signature)`
- **NTT acceleration**: GPU-accelerated Number Theoretic Transform (optional, via `ntt_c.go`)

 ### Verkle Witness Optimization

@@ -207,8 +224,9 @@ Quasar includes a Verkle witness system for hyper-efficient state verification:
 | Type | Algorithm | Usage |
 |------|-----------|-------|
 | `PQSignatureTypeMLDSA65` | NIST FIPS 204 ML-DSA-65 | Per-validator signatures (1952-byte public key) |
-| `PQSignatureTypeCorona` | Ring-LWE threshold | Quasar consensus threshold signatures |
-| `PQSignatureTypeHybrid` | Classical + PQ combined | Full Quasar triple proofs (BLS + Pulsar + ML-DSA) |
+| Pulsar threshold | Module-LWE threshold ML-DSA (TALUS) | Compact Pulsar finality leg (byte-equal to FIPS 204) |
+| Corona threshold | Ring-LWE threshold (Ringtail) | Compact Corona finality leg (dealerless) |
+| Hybrid | Classical + PQ combined | `STRICT_QUASAR` posture: Beam ∧ Pulsar ∧ Corona over one message |

 ## Configuration Parameters

@@ -270,7 +288,7 @@ consensus/
    nebula/         State sync protocol
    field/          Nebula field operations
    quasar/         Post-quantum finality engine
-      quasar.go     Signer (BLS+Pulsar+ML-DSA triple threshold)
+      quasar.go     Compact-cert envelope (Beam+Pulsar+Corona+P3Q legs)
      core.go       Quasar core (multi-chain block aggregator)
      engine.go     Engine interface implementation
      epoch.go      Epoch-based Pulsar key management
@@ -296,7 +314,7 @@ node/consensus/
  acceptor.go       Acceptor callback interface
  engine/chain/     Vote message types (wire: Chits)
  quasar/           Node-level Quasar integration
-    quasar.go       Binds P-Chain + Q-Chain into triple finality
+    quasar.go       Binds P-Chain signer-set eras into compact-cert finality
    types.go        Signature interfaces, CoronaCoordinator
  zap/              ZAP agentic consensus bridge
    bridge.go       Query/Response/Vote consensus
@@ -308,8 +326,11 @@ node/consensus/

 | Package | Version | Purpose |
 |---------|---------|---------|
-| `github.com/luxfi/crypto` | v1.17.40 | BLS12-381, threshold signatures, IPA/banderwagon |
-| `github.com/luxfi/corona` | v0.2.0 | Ring-LWE post-quantum threshold signatures |
+| `github.com/luxfi/crypto` | v1.19.26 | BLS12-381, threshold signatures, IPA/banderwagon |
+| `github.com/luxfi/pulsar` | v1.1.5 | Module-LWE (ML-DSA) threshold — Pulsar / TALUS kernel |
+| `github.com/luxfi/corona` | v0.7.9 | Ring-LWE post-quantum threshold signatures (Ringtail) |
+| `github.com/luxfi/magnetar` | v1.2.3 | SLH-DSA (FIPS 205) threshold kernel |
+| `github.com/luxfi/threshold` | v1.9.9 | Threshold protocol primitives |
 | `github.com/luxfi/database` | v1.17.42 | State storage |
 | `github.com/luxfi/ids` | v1.2.9 | Block/node/chain identifiers |
 | `github.com/luxfi/p2p` | v1.18.9 | Peer-to-peer networking |
@@ -476,7 +497,7 @@ for block := range engine.Finalized() {
 }
 ```

-### Node: Quasar with Triple Finality
+### Node: Quasar with PQ Finality

 ```go

@@ -31,8 +31,9 @@ Lux HSM (`github.com/luxfi/hsm`) is a **unified Go library** for hardware securi
 | Go | 1.26.1 |
 | License | Apache 2.0 |
 | Package Type | Library (no binary) |
-| Only Dependency | `github.com/luxfi/[email protected]7.40` |
+| Core Dependency | `github.com/luxfi/[email protected]9.0` |
 | Transitive | `github.com/cloudflare/[email protected]` (ML-DSA) |
+| Released tag | v1.1.4 |

 ## Core Concepts

@@ -54,15 +55,33 @@ type PasswordProvider interface {

 ### Signer Providers

-| Provider | Type | Algorithm | File |
-|----------|------|-----------|------|
-| `aws` | AWS KMS | ECDSA_SHA_256 | `signer_aws.go` |
+All registered in `factory.go` via one `NewSigner(provider, config)` entry point.
+
+| Provider | Type | Algorithm / notes | File |
+|----------|------|-------------------|------|
+| `aws` | AWS KMS / CloudHSM | ECDSA_SHA_256 (SigV4, no SDK) | `signer_aws.go` |
 | `gcp` | Google Cloud KMS | EC_SIGN_P256_SHA256 | `signer_gcp.go` |
-| `azure` | Azure Key Vault | ECDSA P-256 | `signer_azure.go` |
-| `zymbit` | Zymbit SCM | ECDSA P-256 (PKCS#11, port 6789) | `signer_zymbit.go` |
+| `azure` | Azure Key Vault / Managed HSM | ECDSA P-256 | `signer_azure.go` |
+| `kmip` | KMIP 1.x HSM | KMIP `Sign` (requires cgo) | `signer_kmip.go` |
+| `pkcs11` | PKCS#11 token (Luna, SoftHSM) | universal HSM standard (requires cgo) | `signer_pkcs11.go` |
+| `yubihsm` (`yubico`, `yubi`) | YubiHSM 2 | EC / Ed25519 | `signer_yubihsm.go` |
+| `nitrokey` | Nitrokey HSM | OpenPGP / PKCS#11 secure element | `signer_nitrokey.go` |
+| `zymbit` | Zymbit SCM | ECDSA P-256; native threshold | `signer_zymbit.go` |
+| `ledger` | Ledger | hardware-wallet secure element | `signer_ledger.go` |
+| `trezor` | Trezor | hardware-wallet secure element | `signer_trezor.go` |
+| `coldcard` | Coldcard | air-gappable hardware wallet | `signer_coldcard.go` |
+| `keystone` | Keystone | air-gap QR hardware wallet | `signer_keystone.go` |
+| `gridplus` / `lattice` | GridPlus Lattice1 | SafeCard (Connect-API partial) | `signer_gridplus.go` |
+| `ngrave` | NGRAVE ZERO | air-gap hardware wallet | `signer_ngrave.go` |
+| `foundation` | Foundation Passport | air-gap hardware wallet | `signer_foundation.go` |
 | `mldsa` / `pq` / `post-quantum` | Post-Quantum | ML-DSA-44/65/87 (FIPS 204) | `signer_mldsa.go` |
+| `tr31` | Banking key block | ANSI X9.143 / TR-31 key wrapping | `signer_tr31.go` |
 | `local` / `""` | In-Memory | ECDSA P-256 (dev only) | `signer_local.go` |

+**FIPS subset.** `RequireFIPSProvider` admits only `aws`, `gcp`, `azure`,
+`yubihsm`, `pkcs11`, `kmip` — wire it before constructing a signer to fail
+closed on a non-FIPS provider.
+
 ### Password Providers

 | Provider | Type | Env Vars |
@@ -208,7 +227,8 @@ Tests cover:
 | Attestation invalid | Wrong HSM key | Verify attestation key ID matches signing key |
 | GCP metadata 404 | Not on GCE/GKE | Use env/file provider locally, GCP only in cloud |
 | Azure MSI fail | No managed identity | Assign system or user-assigned managed identity |
-| `unknown signer provider` | Typo in provider name | Supported: aws, gcp, azure, zymbit, mldsa, pq, post-quantum, local |
+| `unknown signer provider` | Typo in provider name | Supported: aws, gcp, azure, kmip, pkcs11, yubihsm, nitrokey, zymbit, ledger, trezor, coldcard, keystone, gridplus/lattice, ngrave, foundation, mldsa/pq/post-quantum, tr31, local |
+| `pkcs11`/`kmip` always refuses | Built without cgo | Rebuild with `CGO_ENABLED=1`; the no-cgo build links a refuse-only stub |

 ## Related Skills

@@ -1,77 +1,145 @@
 ---
 title: "Lux Quasar"
-description: "The supermassive black hole at the center of the Lux post-quantum finality universe — pulls Pulsar (M-LWE) + Corona (R-LWE) + Magnetar (SLH-DSA) + BLS + Z-Chain Groth16 / P3Q into per-round finality certs. Defines QuasarCert wire format and Pulsar / Aurora / Polaris cert profiles."
+description: "Quasar finality — a typed compact-certificate envelope binding four evidence kinds (Beam · Pulsar · Corona · P3Q) to one canonical message under one P-Chain-pinned KeyEra. Defines the ConsensusCert envelope, the suite registry, and the four operator postures."
 ---

 ## Overview

-**Quasar** is the supermassive black hole at the center of the Lux
-post-quantum finality universe. Every consensus event in every Lux
-primary-network chain is pulled into a per-round `QuasarCert` — a
-PQ-finality certificate composed from the underlying threshold
-primitives (Pulsar M-LWE, Corona R-LWE, Magnetar SLH-DSA), the
-classical BLS aggregate fast-path, and the Z-Chain Groth16 / P3Q
-on-chain verifier roll-up. Nothing escapes Quasar's event horizon
-without going through PQ finality.
+**Quasar** is the post-quantum finality layer at the center of every Lux chain.
+A finalized round is sealed by a **`ConsensusCert`** — a policy-gated aggregate
+quorum certificate. Policy declares which cryptographic *legs* are required;
+certificate bytes carry the per-leg evidence; every leg proves the **same**
+weighted-quorum predicate over the **same** domain-separated finality message.

- **Repo**: [github.com/luxfi/quasar](https://github.com/luxfi/quasar)
- **Role**: Spec + profile registry + composition proofs
- **Not an implementation** — the consensus-engine binding lives at
-  [`luxfi/consensus/protocol/quasar/`](https://github.com/luxfi/consensus/tree/main/protocol/quasar)
+- **Implementation**: [`luxfi/consensus`](https://github.com/luxfi/consensus) `protocol/quasar/` (released **v1.26.0**)
+- **Threshold kernels**: [`luxfi/pulsar`](https://github.com/luxfi/pulsar) v1.2.0 (Module-LWE) · [`luxfi/corona`](https://github.com/luxfi/corona) v0.8.0 (Ring-LWE)

-## Cert Profiles
+## Four evidence kinds

-| Profile | Composition | Cert size (n=21) | Use case |
-|---|---|---|---|
-| **Pulsar** | BLS ‖ Pulsar | ~3.5 KB | PQ floor — single PQ kernel, smallest cert |
-| **Aurora** | BLS ‖ Pulsar ‖ Corona | ~37 KB | Intra-lattice diversity — two lattice constructions per cert |
-| **Polaris** | BLS ‖ Pulsar ‖ Corona ‖ Magnetar | ~53 KB | Maximum-assurance cross-family — lattice + hash-based |
+The chain stores **one compact typed evidence per lane**, never N raw
+per-validator signatures. These four names are the value-level vocabulary; the
+suite registry maps each concrete suite to its orthogonal axes.

-Each cert profile is independently selectable per-chain via
-`FinalitySchemeID` in `consensus/config/pq_mode.go`.
+| Evidence kind | Wire id | Family | Shape | Role |
+|---------------|---------|--------|-------|------|
+| **Beam** | `beam-bls` | BLS12-381 (classical) | one aggregate | Fast classical aggregate |
+| **Pulsar** | `pulsar-threshold-mldsa` | Module-LWE, FIPS-204 ML-DSA (TALUS) | one threshold sig | Compact PQ threshold leg |
+| **Corona** | `corona-ringtail` | Ring-LWE (Ringtail), dealerless | one threshold sig | Independent second PQ lattice leg |
+| **P3Q** | `p3q-mldsa-rollup` | rollup over independent ML-DSA certs | root/proof over a cert set | Fallback: migration / recovery / bridge / audit |

-## Primitives
+Beam, Pulsar, and Corona are **O(1) in committee size**. P3Q compresses a set of
+independent per-validator ML-DSA certs (the `MLDSACertSet`) — the always-
+available audit/challenge object, never the primary finality object when a
+compact Pulsar leg is live.

-| Primitive | Repo | Role | Pinned tag |
-|---|---|---|---|
-| Pulsar | [`luxfi/pulsar`](https://github.com/luxfi/pulsar) | Threshold ML-DSA-65 (M-LWE) | v1.0.9 |
-| Corona | [`luxfi/corona`](https://github.com/luxfi/corona) | Threshold R-LWE sibling | v0.4.0 |
-| Magnetar | [`luxfi/magnetar`](https://github.com/luxfi/magnetar) | Threshold SLH-DSA (research) | research |
-| BLS | [`luxfi/crypto/bls`](https://github.com/luxfi/crypto/tree/main/bls) | BLS12-381 aggregate classical fast-path | tracks crypto v1.19.x |
-| Z-Chain Groth16 | [`luxfi/chains/quantumvm`](https://github.com/luxfi/chains/tree/main/quantumvm) | Per-validator MLDSA Groth16 roll-up | v1.2.3+ |
+## Two orthogonal axes

-## QuasarCert wire format
+A leg's **kind** (what it satisfies) and **mode** (how it is proven) are
+orthogonal and never braided:
+
+| Evidence kind | `LegKind` (what) | `EvidenceMode` (how) |
+|---------------|------------------|----------------------|
+| Beam | `LegClassical` | `ClassicalAggregate` |
+| Pulsar | `LegPulsarMLDSA` | `ThresholdSig` |
+| Corona | `LegCoronaLattice` | `ThresholdSig` |
+| P3Q | `LegPulsarMLDSA` | `P3QRollup` |
+
+Pulsar and P3Q satisfy the **same** leg kind by **different** mechanisms — the
+policy "OR" (`Beam ∧ (Pulsar OR P3Q)`) is expressed at the mode level on a single
+required leg kind, never as an alternative leg.
+
+## Suite registry
+
+A *suite id* is a wire-stable string naming one concrete, parameterised scheme.
+The registry is the single authority mapping a suite id to its
+`(EvidenceKind, LegKind, EvidenceMode, param-set)` — verifiers resolve suites
+**only** through it, so no suite string can dispatch to the wrong verifier and an
+unknown suite is a hard reject.
+
+| Suite id | Kind | Param set |
+|----------|------|-----------|
+| `Lux-Beam-BLS12381-v1` | Beam | BLS12-381 |
+| `Lux-Pulsar-TALUS-MLDSA44` / `65` / `87` | Pulsar | ML-DSA-44 / 65 / 87 |
+| `Lux-Corona-Ringtail-L1` / `L3` / `L5-v1` | Corona | ML-DSA-44 / 65 / 87 security-level byte |
+| `Lux-P3Q-MLDSA{44,65,87}-Direct-v1` | P3Q | direct (raw set, PQ-safe, O(N), always verifiable) |
+| `Lux-P3Q-MLDSA65-STARK-v1` | P3Q | succinct, hash-based (PQ-safe, audit-gated) |
+| `Lux-P3Q-MLDSA65-Groth16-v1` | P3Q | succinct, classical assumption (audit-gated + policy opt-in) |
+
+## KeyEra — one group key per era
+
+A threshold leg for a 1000-validator committee is **one** signature under **one
+group public key**. A `KeyEra` pins that single group key to one validator-set
+era:

 ```go
-type QuasarCert struct {
-    BLS        []byte  // BLS12-381 aggregate, 48 B classical fast path
-    Pulsar     []byte  // Threshold ML-DSA-65 (always populated)
-    Corona     []byte  // Threshold R-LWE (Aurora / Polaris)
-    Magnetar   []byte  // Threshold SLH-DSA (Polaris only)
-    MLDSAProof []byte  // Z-Chain Groth16, ~192 B
-    Epoch      uint64
-    Finality   time.Time
-    Validators int
+type KeyEra struct {
+    ChainID      uint32   // matches ConsensusCert.ChainID
+    SignerSetID  [48]byte // P-Chain-pinned validator-set identity
+    KeyEraID     uint64   // advances on signer-set rotation
+    Generation   uint64   // advances on within-era key refresh / reshare
+    PChainHeight uint64   // height the signer set was pinned at
+    GroupPubKey  []byte   // the compact threshold GROUP key (scheme-interpreted)
+    SchemeID     string   // e.g. "Lux-Pulsar-TALUS-MLDSA65" | "Lux-Corona-Ringtail-L3-v1"
+    KeygenMode   string   // AUDIT only: "talus-mpc" | "ceremony" | "tee" | "p3q-rollup-fallback"
+    // ...
 }
 ```

-A valid cert MUST satisfy:
-1. Every populated leg verifies under its primitive's verifier
-2. The populated-leg set matches the profile selector exactly
-3. Validators equals the validator-set size at Epoch
-4. Domain separation enforced via context strings per leg
+`KeyEra` is a *value qualified by its scheme*, not a place: **one** type and
+**one** boring verifier (`VerifyThresholdLeg`) serve **every** threshold lane —
+Pulsar (FIPS-204 ML-DSA group sig, via `pulsarwire.VerifyBytes`) and Corona
+(Ringtail, via `coronaThreshold.Verify`). The chain does not care *how* the group
+key was produced; `KeygenMode` records that for audit and is orthogonal to
+verification.

-Full spec at `luxfi/quasar/SPEC.md`.
+## The four postures (policy table)

-## Naming canon
+The operator selects a finality posture per chain. The required leg **kinds** are
+committed into the cert's required-legs root; the permitted **modes** live in the
+policy's allow-table.

- Profiles: **Pulsar / Aurora / Polaris** (no "Syzygy")
- Primitives: **Pulsar / Corona / Magnetar** (no "Comet", no "Corona")
+| Posture | Requires | Use case |
+|---------|----------|----------|
+| `BLS_FAST` | Beam | Mempool / fast local block acceptance |
+| `HYBRID_PQ_CHECKPOINT` | Beam ∧ (Pulsar **or** P3Q) | Checkpoints |
+| `STRICT_QUASAR` | Beam ∧ Pulsar ∧ Corona | Full dual-lattice AND-mode strict finality |
+| `RECOVERY_MODE` | Beam ∧ P3Q | Recovery / migration / bridge (no Pulsar key) |
+
+`HYBRID_PQ_CHECKPOINT` and `RECOVERY_MODE` share the same required leg kinds
+(hence the same required-legs root); they are distinguished by their evidence-
+policy id (bound into the message) and their allow-table — the requirement
+commits the *kinds*, the policy id + allow-table commit the *modes*.
+
+## Verifier invariants
+
+The `ConsensusCert` verifier (`VerifyConsensusCert`) enforces, among others:
+
+- **Required legs come from policy only.** The cert's required-legs root is
+  recomputed from policy and checked; the cert may not assert its own required
+  set.
+- **The signed message binds the full consensus tuple** (chain id, epoch,
+  height, round, block hash, validator-set root, policy id, required-legs root,
+  signer root, cert profile) — never the block hash alone; cross-domain replay is
+  closed.
+- **Every required leg must appear exactly once;** a missing leg is a hard reject.
+- **Classical evidence can satisfy only a classical leg** — never a required PQ
+  leg; a classical-only cert is rejected under any posture requiring a PQ leg.
+- **SLH-DSA is never threshold-signed in production** (a Magnetar threshold-sig
+  leg is a hard reject).
+- **Threshold legs require signer accountability** (signer root, aggregate
+  weight, policy, session binding) or are rejected.
+- **Malformed bytes yield a typed error, never a panic and never unbounded work.**
+
+## Compactness
+
+ML-DSA-65 signatures are ~3.3 KB. A naive per-validator certificate is
+`48 + N × 3309` bytes; the compact threshold leg replaces the `N × 3309` term
+with a single group signature, so a 1000-validator cert is the same size as a
+4-validator cert — roughly three orders of magnitude smaller at N=1000.

 ## Cross-references

- [`luxfi/quasar/SPEC.md`](https://github.com/luxfi/quasar/blob/main/SPEC.md) — cert wire format
- [`luxfi/quasar/PROFILES.md`](https://github.com/luxfi/quasar/blob/main/PROFILES.md) — profile registry
- [`luxfi/quasar/PRIMITIVES.md`](https://github.com/luxfi/quasar/blob/main/PRIMITIVES.md) — primitive registry
- [LP-020](https://github.com/luxfi/LPs/blob/main/LP-020-quasar-consensus.md) — Quasar consensus LP
- [LP-105](https://github.com/luxfi/LPs/blob/main/LP-105-lux-stack-lexicon.md) — Lux stack lexicon
+- [Consensus](/consensus) — the engine and sub-protocols
+- [Post-Quantum](/post-quantum) — Pulsar (TALUS) and Corona (Ringtail) in depth
+- [`luxfi/consensus` `protocol/quasar/`](https://github.com/luxfi/consensus/tree/main/protocol/quasar)
+- [LPs](https://lps.lux.network) — the governing Lux Proposals
@@ -52,3 +52,31 @@ When using the CLI's encrypted key storage:
 - Minimum 12 characters
 - Passwords are hashed with Argon2 before use as encryption keys
 - Key material is encrypted with AES-256-GCM at rest
+
+## MPC & Threshold Custody
+
+For institutional and bridge custody, a key need never exist in one place. Lux
+custody is **decomplected**: one optional MPC custody module, plus an optional
+TEE custody extension, composed over a shared attestation verifier.
+
+| Module | Tag | Role |
+|--------|-----|------|
+| [`luxfi/mpc`](https://github.com/luxfi/mpc) | v1.16.0 | Threshold MPC custody — **CGGMP21** (secp256k1 ECDSA) and **FROST** (Schnorr / ed25519). t-of-n signing, DKG, resharing, refresh, and a policy engine. |
+| [`luxfi/tee`](https://github.com/luxfi/tee) | v0.1.0 | **Optional** TEE-backed threshold-signing custody extension (attested enclave). One-way dependency on the signing kernels; **not** required by the threshold core. |
+| [`luxfi/cc`](https://github.com/luxfi/cc) | v0.1.0 | One attestation verifier the custody modules call before releasing a key share into hardware. See [Confidential Compute](/confidential-compute). |
+
+<Callout>
+  The optional extension model: `luxfi/mpc` (MPC custody) and `luxfi/tee` (TEE
+  custody) are **add-ons**. The post-quantum consensus core depends on neither —
+  the permissionless chain runs dealerless without a TEE. Operators opt into MPC
+  or TEE custody for institutional key management; it is never a trust assumption
+  baked into the open validator set.
+</Callout>
+
+### Policy engine
+
+`luxfi/mpc` ships a Fireblocks/Utila-style policy engine for MPC wallets —
+per-transaction rules (amount caps, allow-lists, approval quorums) gate every
+signing request before the threshold ceremony runs. This is the in-house custody
+policy layer; external custodian co-signing (Utila / Fireblocks / regulated
+custodians) layers on top via the [bridge cosigner](/bridge) flow.