Documentation
¶
Overview ¶
Package trustedroot produces and persists Lantern's TrustedRoot: a small in-memory tuple (Epoch, TipSetKey, TipSetCID, StateRoot, ParentMessageReceipts, ParentWeight, F3Instance, F3Cert, AncestorRoots) that the rest of the node treats as ground truth for "what the chain is right now."
The Build pipeline:
- Start from a hard-coded genesis CID and the F3 network manifest.
- Stream block headers from a HeaderSource, validate each via chain/header, build canonical tipsets.
- Stream F3 finality certificates from an F3CertSource, validate via chain/f3.
- Consolidate into a TrustedRoot at the highest F3-finalized epoch (or the head minus a safety buffer, pre-F3).
- Persist to BadgerDB so subsequent boots resume in seconds.
See docs/design/TRUSTED-ROOT.md for the full specification.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrNoCert = errors.New("f3 cert not yet available")
ErrNoCert is returned by F3CertSource.Cert when the requested instance is not yet finalized.
Functions ¶
Types ¶
type F3CertSource ¶
type F3CertSource interface {
// Cert returns the cert at the given instance, or (nil, ErrNoCert) if
// not yet finalized.
Cert(ctx context.Context, instance uint64) (*certs.FinalityCertificate, error)
// Latest returns the latest available cert; useful for figuring out
// how far back to walk.
Latest(ctx context.Context) (*certs.FinalityCertificate, error)
}
F3CertSource yields finality certificates starting at the requested instance.
type HeaderSource ¶
type HeaderSource interface {
// Tipset returns the tipset at the given epoch, or an error if it
// can't be produced. May skip null-round epochs by returning an empty
// block list.
Tipset(ctx context.Context, epoch abi.ChainEpoch) (*ltypes.TipSet, error)
// Head returns the current head epoch.
Head(ctx context.Context) (abi.ChainEpoch, error)
}
HeaderSource yields headers in epoch-ascending order. The default implementation in examples/historical/phase1 reads from a Lotus RPC; production code will swap in a libp2p header sync.
type InitialPowerTableLoader ¶
InitialPowerTableLoader supplies the seed power table referenced by the network manifest's InitialPowerTable CID. Phase 1 supplies this from the public Glif RPC (Filecoin.F3GetCertificate(0) gives the first cert whose base.PowerTable matches the manifest).
type Options ¶
type Options struct {
// Manifest is the F3 network manifest. Required.
Manifest *manifest.Manifest
// BeaconConfig is the DRAND verifier for current-network beacon entries.
// Optional: if nil, beacon-entry verification is skipped (useful for
// catching up to a tip without flagging every quicknet round).
BeaconConfig *beacon.Config
// MaxBacktrack limits how many epochs back from head we walk; default 30.
MaxBacktrack abi.ChainEpoch
// AncestorRootDepth: how many ancestor state roots to record. Default 100.
AncestorRootDepth int
}
Options configures a Build run.
type TrustedRoot ¶
type TrustedRoot struct {
// Chain identity at the selected tip.
Epoch abi.ChainEpoch
TipSetKey ltypes.TipSetKey
StateRoot cid.Cid
ParentMessageReceipts cid.Cid
ParentWeight ltypes.BigInt
BeaconRound uint64
// F3 finality witness. F3Cert may be nil pre-F3-finality.
F3Instance uint64
F3Cert *certs.FinalityCertificate
// Bookkeeping.
AcceptedAt time.Time
// AncestorRoots is the last N state roots (default 100) for state
// queries against recent past epochs.
AncestorRoots []cid.Cid
}
TrustedRoot is the small in-memory tuple the rest of the node treats as ground truth for "what the chain is right now."
func Build ¶
func Build( ctx context.Context, db *badger.DB, opts Options, headers HeaderSource, f3certs F3CertSource, initialPT InitialPowerTableLoader, ) (*TrustedRoot, error)
Build runs the Phase 1 trusted-root construction pipeline end-to-end:
- Load the initial power table for the manifest.
- Walk F3 certs forward, validating each.
- Select the head: the F3-finalized tip if available, else head - safety.
- Fetch the headers along the selected ancestry and validate each.
- Persist (if db != nil) and return the TrustedRoot.
func FromF3State ¶
func FromF3State(ctx context.Context, finalizedTSK ltypes.TipSetKey, finalizedEpoch abi.ChainEpoch, instance uint64, latest *certs.FinalityCertificate, headers HeaderSource) (*TrustedRoot, error)
FromF3State produces a TrustedRoot from an F3 subscriber's verified state. This is the Phase 6 "activated cert chain" path: instead of running the legacy Build pipeline against header sources, we trust the subscriber's `(Instance, LatestChain)` which was walked forward from the embedded anchor with full BLS-aggregate verification at every step.
`headers` is used to fetch the canonical tipset at the F3-finalized epoch so we can populate Lantern-side fields (StateRoot, ParentMessageReceipts, ParentWeight). Pass nil to defer those fields (acceptable when the caller only needs F3Instance / F3Cert).
Source Files