Skip to content

TRUST-MODEL.md §2.1 overstates header validation (claims election-proof verify; code checks presence only) #81

Description

@Reiers

Problem

TRUST-MODEL.md §2.1 (Header chain) claims:

Every header walked back to genesis ... has its BLS signature, election proof, ticket, parent linkage, and weight re-verified against the local copy of the previous header. The header validator (chain/header/header.go) refuses any header that fails any of these checks.

The code does not deliver all of that on the live path:

  • chain/header/header.go::ValidateHeader checks structure, signature presence, parent linkage, height — but does not cryptographically verify the election proof (line ~153 only checks ElectionProof == nil, i.e. presence, not VRF validity). There is no VRF / winning-PoSt verification anywhere (correctly — that path needs filecoin-ffi/Rust, which Lantern deliberately does not pull).
  • The live gossip head path (net/blockingest) calls only the lighter checks (CBOR shape, sig presence, CID re-derive, parent linkage, height fence). The strict ValidateHeader is referenced as a compile-time check but is not the gate on the running head.
  • Weight-based fork choice is also not enforced on the running head (tracked in Running-head fork choice: heaviest-ParentWeight + periodic re-quorum (not boot-only) #79).

So the doc overstates what is verified. This matters because external reviewers (e.g. FilOz) read the trust model against the source.

Fix

Rewrite TRUST-MODEL.md §2.1 to state precisely what is verified vs not:

  • What IS verified: BLS signature, parent linkage, CID re-derivation, height/shape, F3 cert BLS-aggregate (§2.2), DRAND (§2.3), state-block CIDs (§2.4).
  • What is NOT verified (by design, no-ffi law): election-proof VRF validity and winning-PoSt — Lantern is an F3-anchored light client, not a full re-executing validator.
  • Note the running-head fork-choice/quorum status and link Running-head fork choice: heaviest-ParentWeight + periodic re-quorum (not boot-only) #79.

Acceptance

Context: caught while answering zenground0 (fil-curio-dev, 2026-06-30) on head-agreement / fork selection.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationp2Medium prioritysecuritySecurity finding or hardening

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions