Documentation
¶
Overview ¶
Package crosscheck implements the VM-bridge auditor (#98).
The VM bridge (vm/bridge) is normally a PRODUCTION dependency: it computes post-execution state roots for block production. This package turns the same connection into an AUDITOR for the read path: it periodically asks the operator's own Forest/Lotus node for the canonical tipset at a settled depth and compares it against Lantern's header-store view. A mismatch means Lantern's head path and the operator's full node disagree about the canonical chain - a state-root level attack, an eclipse, or a bug - and is worth a loud alarm.
Why this is honest trust-wise (TRUST-MODEL 4.x): the bridge is the operator's own node, already trusted for block production. Using it to CROSS-CHECK adds no new trust; the read path stays 100% local and is never answered by the bridge. The check is observe-only: a divergence alarms (log + counter + dashboard) but never blocks or rewrites Lantern's head. This delivers most of the practical security value of full re-execution (#89 Stage C) at ~zero cost, and doubles as the vector generator Stage C will need.
Sampling: checks run at a fixed interval (default 60s) against depth head-K (default 3 epochs) so legitimate near-tip reorgs don't produce false alarms. Null rounds are skipped (heights must match to compare).
Index ¶
Constants ¶
const DefaultDepth = 3
DefaultDepth is how many epochs behind head the check targets. 3 epochs (~90s) is deep enough that honest near-tip reorgs have settled, shallow enough that an attack alarms within ~2 minutes.
const DefaultInterval = 60 * time.Second
DefaultInterval is the default wall-clock spacing between checks.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Checker ¶
type Checker struct {
// contains filtered or unexported fields
}
Checker periodically cross-checks the local canonical chain against the operator's bridge node. Observe-only: never mutates local state.
func (*Checker) CheckOnce ¶
CheckOnce performs one cross-check. Exposed for tests and for a dashboard "check now" action.
type Config ¶
type Config struct {
Bridge RPC
Source Source
Interval time.Duration // 0 => DefaultInterval
Depth int // 0 => DefaultDepth
// OnDiverge, when set, fires on every confirmed divergence (after
// the height-match guard). Wire alerts/notifications here.
OnDiverge func(epoch abi.ChainEpoch, ours, theirs string)
}
Config wires a Checker.
type RPC ¶
type RPC interface {
RawJSONRPC(ctx context.Context, method string, params json.RawMessage) (json.RawMessage, error)
Provenance() string
}
RPC is the bridge surface the checker needs. vm/bridge.ForestBridge (and the Bridge interface) satisfy it.
Source Files