docs(consensus/LLM.md): record PQ-finality verify-gate state + activation order

Supersede the stale Quasar-wrapper notes with the actual consensus/quasar verify
gate: dormant-by-default safety contract, files/tests, and the owner-gated
remaining-work map (producer+encoder export, gossip ingest, per-epoch validator
provider, config wiring, grace-window runbook) + mainnet activation order.
This commit is contained in:
zeekay
2026-06-28 07:50:58 -07:00
parent e15ac35c94
commit 2a08357dcb
+51
View File
@@ -68,3 +68,54 @@ Block arrives
## Recent Changes
- 2026-01-04: Created documentation files with Vote terminology
## consensus/quasar — PQ-finality VERIFY gate (2026-06-28)
Supersedes the stale "Quasar wrapper / CoronaCoordinator" notes above (that
subpackage did not exist in-tree). The current `consensus/quasar` package is the
node-side integration of `luxfi/consensus@v1.29.0`'s typed compact-cert finality
layer (`protocol/quasar.VerifyConsensusCert`). It wires the VERIFY half only.
Model: luxd finalizes on classical Snow every block; at CHECKPOINTS (height %
interval) a sampled committee's QuasarCert over the finalized digest is VERIFIED.
Default posture HYBRID_PQ = Beam(BLS) ∧ Pulsar (ML-DSA-65); STRICT_DUAL_PQ
(+Corona) / POLARIS (+Magnetar) configurable.
THE SAFETY CONTRACT — forward-dated, DORMANT by default:
- `Gate.VerifyAccepted` is the accept-path boundary. nil gate / `Activation.Height
== 0` / below-height / non-checkpoint => no-op; classical finality UNCHANGED.
- Activated at a checkpoint => REQUIRE a valid cert bound to the finalized block;
FAIL CLOSED (missing/mismatch/invalid => error from Accept, halts without
persisting). Activation is HEIGHT-ONLY (deterministic — no wall clock).
- Hooked in `vms/proposervm/post_fork_block.go Accept()` via
`vm.verifyQuasarFinality(b)`; the VM's `quasarGate` is nil in production today
(set via `SetQuasarGate`). Nothing wires it yet — that is the activation step.
Files: gate.go (Gate/ActivationConfig/bindCheck), policy.go (HYBRID_PQ default,
cert can't pick its own policy), validators.go (ConsensusValidatorSet: BLS+Pulsar
keys), store.go (MemCertStore), producer.go (committee-signer interface =
scaffolding; nil = verify-only), errors.go. Tests: gate_test.go (13, -race green:
dormant no-op, fail-closed, epoch/round/chain/height/block anti-replay, real-
verifier delegation, misconfigured-fails-closed).
REMAINING WORK to reach a live PQ-finality network (all owner-gated):
1. Producer service (pulsard): the per-validator committee cert signer. Needs
pulsar v1.7.1 (no-reconstruct hyperball signer) AND consensus to EXPORT the
currently package-private cert/payload ENCODERS (an external producer cannot
assemble a ConsensusCert envelope without them; this also unblocks an end-to-
end positive verify test).
2. Cert gossip/ingest -> MemCertStore (verify-before-store); MemCertStore needs
eviction below last-finalized height before this lands.
3. Production per-epoch `ValidatorSetProvider` from the P-Chain validator manager
+ KeyEra registry (BLS aggregate + Pulsar/Corona/Magnetar group keys per era).
4. Config-flag -> SetQuasarGate wiring (construct a non-nil gate from node config;
choose ChainID = sovereign/EVM chain id).
5. Cert-unavailability runbook + a bounded grace window (await cert N rounds)
before a checkpoint halts — fail-closed-after-decision can brick a chain if
gossip is down. REQUIRED before any forward-dated activation.
6. A proposervm Accept-path integration test (nil/dormant/activated).
Mainnet activation order (owner): deploy producer -> verify cert-gossip coverage
at checkpoints -> set Activation.Height to a forward-dated height with margin ->
roll via `kubectl patch sts luxd` OnDelete, 1 pod at a time. NEVER wipe /data/db,
NEVER pkill, NEVER blind-restart.