Skip to content

Offline Tooling — Golden Replay

Docs-site note: Describes the offline-replay mechanism at a conceptual level — how it's invoked and what guarantees it gives, not a specific incident's slot numbers or internal paths. Grounded in vex-fd's own environment-variable handling; the methodology and its cited proof numbers come from Why Byte-Faithful and the Parity & Fidelity Audit.

Vexor's core byte-fidelity discipline is an offline golden replay: re-run a range of already-rooted slots with no network connection, from a local snapshot, and confirm the resulting bank hashes match the cluster's exactly. Every consensus-path change is gated behind this before it ships. This page covers the mechanism vex-fd itself provides for driving that replay — not a separate binary, but the same vex-fd executable run in a distinct, network-silent mode.

Why offline, not live

Testing a consensus change live risks the one thing a validator can't take back: a wrong vote. Offline replay lets a change be checked against real, cluster-produced blocks — with the real answer (the cluster's bank hash) known in advance — without the validator ever touching the network, submitting a vote, or being observable by any peer. It's the same idea as a reference-implementation differential test, run against the validator's own past history instead of a synthetic vector set.

The methodology's proven result: an offline golden replay spanning 1992 canonical slots across an epoch boundary, bank hashes byte-identical to the live cluster's, is the standing gate every consensus change passes before deploy. See Why Byte-Faithful for the full rationale and Parity & Fidelity Audit for the audited record.

How it's invoked

Offline replay is driven entirely by environment variables on the normal vex-fd binary — there is no separate replay tool to install.

Env Role
VEX_LEDGER_REPLAY=<start>:<count> Requests a replay starting at slot <start> for <count> slots, reading from local ledger/snapshot data rather than the network.
VEX_SNAPSHOT_OFFLINE Boots from a local snapshot directory (paired with --snapshots <dir>) instead of fetching one from the network.
VEX_LEDGER_REPLAY_CANON=<file> Optional canonical-chain filter — points at a file listing the canonical slot sequence to replay, disambiguating which fork to walk when local ledger data covers more than one.

Setting either VEX_LEDGER_REPLAY or VEX_SNAPSHOT_OFFLINE puts the binary into offline mode, which changes its behavior in two load-bearing ways:

  • The runtime config self-bake is skipped entirely. Vexor's normal boot path fills in a table of proven production environment defaults; offline mode skips that step by design, so a replay run reflects exactly the environment it was given — "offline stays lean."
  • The metrics reporter refuses to start. No telemetry, no network calls — offline replay is network-silent by construction, not by operator discipline. See Observability: the never-crash contract.

A generic invocation shape (illustrative — substitute your own slot range and snapshot directory):

VEX_SNAPSHOT_OFFLINE=1 VEX_LEDGER_REPLAY=<start_slot>:<slot_count> \
vex-fd run --testnet --snapshots <local-snapshot-dir> --ledger <local-ledger-dir>

What a pass/fail looks like

A replay run reprocesses each requested slot and compares the resulting bank hash against the one already recorded for that slot (from the original live run or from the cluster). Byte-identical bank hashes across the whole requested range is a pass; any divergence identifies the first slot where behavior parted ways with the canonical result — which is exactly the signal a consensus-path change is checked against before it's allowed to deploy.

See also

  • Why Byte-Faithful — the full golden-replay methodology and why an offline gate is the right discipline for a validator.
  • Parity & Fidelity Audit — the audited, cited replay results.
  • vex-fd Commands — the rest of the CLI surface, including the xdp-selftest diagnostic.
  • Observability — the offline guard that keeps replay network-silent.