feat(#85): header-propagation integrity gate + running-head divergence monitor#86
Merged
Merged
Conversation
…e monitor #85 item 1 (header propagation): tighten the block gossipsub TopicValidator so Lantern only ValidationAccepts - and therefore only re-propagates - blocks that fully consume the payload (no trailing bytes) and whose header round-trips through canonical CBOR to its declared CID. Propagation and ingestion now share one integrity bar; Lantern can't be turned into an amplifier for a malformed or fake-CID header. #85 item 2 / #80 part 2 (robust head discovery): new chain/headcheck package - a periodic running-head divergence monitor. It asks a diversity of INDEPENDENT head sources (counted by source Kind, so N URLs of one upstream count once) what epoch the head is at and checks agreement within a 3-block lookback. On a quorum of independent sources diverging from our gossip head it raises an eclipse/fork alarm. It never moves our head (gossip + #79 fork choice do that) and never makes a trusted RPC the head oracle - it only corroborates or disputes. Wired best-effort into pkg/daemon (Config.HeadCheckRPCs); disabled when empty so it can't sink head-tracking. TRUST-MODEL.md threat-model row updated to reflect the stacked tip defenses (#79 weight fork choice, #80 peer floor, #85 propagation gate + divergence monitor; F3 closes it on mainnet). Tests: chain/headcheck full suite (agreement, kind-diversity collapse, divergence alarm, insufficient-sources, median, start/stop); blockpub validator trailing- garbage + nil-header rejection. Full suite 44 pkgs green (-short, LANTERN_OFFLINE=1), build+vet+gofmt clean.
This was referenced Jul 1, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes the two concrete asks in #85 and the deferred half of #80.
#85 item 1 — header propagation
gossipsub already forwards a message to our mesh peers once the registered
TopicValidatorreturnsValidationAccept, so Lantern already propagates headers. This tightens that gate: the validator now (a) requires the message to consume the entire payload (rejects trailing bytes after a valid block) and (b) re-derives the header CID from a canonical CBOR re-encode. Propagation and ingestion now share one integrity bar, so a malformed header or a block under a fake CID is never re-gossiped. Full BLS / election-proof validation stays the consumer's job (needs ffi, out of scope for an F3-anchored light client — see TRUST-MODEL.md).#85 item 2 / #80 part 2 — robust head discovery
New
chain/headcheckpackage: a periodic running-head divergence monitor.Kind(so N URLs of the same upstream count once — genuine independence, mirroring the bootstrap quorum policy).OnResult).Wired best-effort into
pkg/daemonviaConfig.HeadCheckRPCs(disabled when empty, so it can't sink head-tracking).Trust model
TRUST-MODEL.md threat-model row for gossipsub eclipse updated to reflect the stacked tip defenses: #79 weight fork choice → must out-weight the real chain, #80 un-evictable trusted-peer floor → can't crowd out the peer table, #85 propagation gate + divergence monitor, and F3 fully closing the unfinalized tip on mainnet activation.
Tests
chain/headcheck: agreement, same-kind diversity collapse, divergence alarm, insufficient-sources, median, start/stop.blockpub: trailing-garbage + nil-header rejection through the propagation gate.-short,LANTERN_OFFLINE=1), build + vet + gofmt clean.Follow-ups (not in this PR)
cmd/lanternCLI flag (--headcheck-rpc) to exposeHeadCheckRPCson the standalone daemon path; embedded/programmatic start already supports it.