mirror of
https://github.com/luxfi/node.git
synced 2026-07-27 03:06:23 +00:00
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:
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user