Skip to content

consensus: add isolated Harmony HotStuff core - #3

Draft
Frozen wants to merge 13 commits into
devfrom
spike/hotstuff-core
Draft

consensus: add isolated Harmony HotStuff core#3
Frozen wants to merge 13 commits into
devfrom
spike/hotstuff-core

Conversation

@Frozen

@Frozen Frozen commented Aug 5, 2026

Copy link
Copy Markdown
Owner

Summary

  • add an isolated chained HotStuff core with broadcast vote collection, safety rules, pacemaker, BLS-backed QC, and verified timeout certificates
  • bind trusted state transitions to authority-issued VerifiedQC / VerifiedTC capabilities
  • add Harmony block and validator adapters
  • add a durable, synchronous, domain-bound safety store for vote and lock state
  • use canonical Harmony committee slots and exact decimal EPoS voting power for QC/TC quorum checks
  • keep validator-level leader rotation separate from BLS-slot certificate identities
  • add a dedicated versioned protobuf wire category for shadow HotStuff proposals and votes
  • bound and canonicalize wire block/member identities, packed QC signer evidence, signatures, bitmaps, and proposal payloads before dispatch
  • carry the configured empty-witness view-zero genesis trust root while requiring complete BLS witnesses for every ordinary QC
  • reserve worst-case QC evidence so every accepted maximum proposal still fits Harmony's 2 MiB pubsub frame cap
  • add disabled-by-default, domain-snapshotted HotStuff ingress on the existing bounded consensus pubsub queue without invoking the FBFT parser

Safety boundaries

  • safety state is synchronously persisted before a vote can be returned
  • QC/TC evidence is verified against the exact epoch/shard authority before state-machine or pacemaker transitions
  • wire proposal QCs remain raw BLSQC evidence; only QCAuthority.Verify can mint the capability accepted by the core
  • malformed, duplicate, unknown, non-canonical, and domain-mismatched certificate inputs fail closed
  • the quorum threshold is strictly greater than canonical two-thirds voting power
  • certificate formation errors are returned rather than treated as ordinary under-quorum results
  • decoded network data owns its byte slices and cannot alias libp2p/protobuf buffers
  • HotStuff ingress is disabled unless a typed handler is explicitly installed

Scope

This is still isolated/shadow infrastructure. It does not:

  • make HotStuff an authoritative block committer or finality source
  • change FBFT canonical block insertion or finality behavior
  • install a production shadow runtime or outbound vote/proposal broadcaster
  • add speculative/certified/finalized chain heads
  • add timeout/TC wire messages or epoch-transition lifecycle wiring
  • activate HotStuff on any network or configuration

A concrete shadow runtime remains a separate step. The proposal/QC codec in this PR is dormant: no production call site installs the handler or emits HotStuff proposal frames. The first runtime integration will observe only FBFT proposals that already passed full Blockchain.ValidateNewBlock validation and will enable only committee-wide HotStuff vote ingress. Independent network proposal/QC/TC ingress remains blocked pending deterministic epoch-boundary bootstrap, leader authentication, authority rollover, and a versioned full signed transcript.

That runtime must also require accepted blocks before pacemaker advancement, maintain one durable SafetyRules writer per local BLS key, self-deliver local votes before broadcasting, and use a bounded non-blocking observer queue. Mixed gate deployment must accept-and-relay recognized HotStuff traffic without dispatching it on disabled nodes.

Test plan

  • go test -count=20 -run '^TestHotStuffWire|^TestHotStuffShadowIngress' ./consensus/hotstuff/harmony ./node/harmony
  • go test -race -count=1 ./consensus/hotstuff/harmony ./node/harmony
  • go test -shuffle=on -count=10 ./consensus/hotstuff/...
  • go test -count=1 ./consensus/...
  • go test -count=1 ./node/...
  • go test -count=1 ./api/proto/...
  • go vet ./consensus/hotstuff/harmony ./node/harmony ./api/proto/...
  • make test
  • pinned protobuf regeneration hash comparison
  • independent correctness and concurrency reviews

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant