Skip to content

How We Track Upstream

Docs-site note (2026-07-15): Why Byte-Faithful Parity explains the three-way ground-truth method (deployed source, anchored Agave release, pinned Firedancer cross-check) used to verify any individual claim of correctness — read that page for the method itself. This page is about a different, adjacent question: since Agave and Firedancer are both moving targets, which version of each do we actually track, and when and how do we move the anchor forward? Getting that discipline wrong — anchoring too early to an unstable pre-release, or too late to a version the cluster has already moved past — would undermine the parity claim regardless of how careful the byte-level verification is.

The anchor: newest testnet release, not mainnet, not "latest tag"

Vexor's byte-for-byte target is whatever Agave release the live testnet cluster is actually running — not mainnet (Vexor is testnet-only; see FAQ), and not simply the newest tag Anza has published, if the cluster hasn't moved onto it yet.

The reasoning: parity is meaningful only relative to the network you're actually voting alongside. A validator that byte-matches a release nobody is running yet isn't proving anything about its ability to stay in consensus today. So the anchor is re-checked, and moved if needed, every time a new release ships — and the check is "what does the majority of the testnet cluster run," not "what is the highest version number available."

In practice this means a newly tagged alpha or beta release is watched and reconciled against (any behavioral differences noted, any relevant fixes back-ported into the audit trail) before it becomes the anchor, but the anchor itself doesn't move to it until it's actually what the cluster is running. Anchoring early to a pre-release that gets superseded before the cluster adopts it would mean chasing a target that was never real.

Where the version truth comes from

Consistent with the three-way ground-truth method, the answer to "what does Agave actually do" is never taken from a cached note or a prior audit — it's re-read from source at the anchored commit, every time. Two consequences of that:

  • A stale audit is worse than no audit. If Agave ships a change to a code path Vexor has already "verified," the old verification is void until it's re-checked against the new source — it doesn't get to stay marked done on the strength of a prior pass.
  • Firedancer is a cross-check, not a tiebreaker in Agave's favor. When Agave and Firedancer (an independent second canonical implementation) agree on a behavior, that agreement is treated as the specification. When they disagree, that's a stop signal that gets resolved with source-level investigation before any Vexor code is written or changed — never assumed to be "Agave is right because it's primary."

Feature gates and SIMDs — tracking what hasn't turned on yet

Solana's protocol evolves through feature gates — changes that exist in client code but stay dormant on-chain until the network votes to activate them, often originating from a SIMD (Solana Improvement Document) proposal. Two failure modes are both worth watching for with a feature gate:

  1. A dormant feature turns out to matter the moment it activates, and being unready for it produces exactly the kind of "worked yesterday, diverges today" incident this site's postmortems document. The mitigation is proving dormant code paths correct ahead of activation, with golden-vector known-answer tests extracted from Agave's own internals — see Parity & Fidelity Audit → SVM crypto syscalls for a concrete example (a serializer for a not-yet-activated SIMD, fully KAT-covered before the network turns it on).
  2. A feature that looked null/inactive on testnet is re-checked, not assumed to stay that way — the state of a feature gate is re-verified against the live cluster whenever it becomes relevant to an investigation, rather than trusted from a note written at an earlier point in time.

What "tracking upstream" does not mean

  • It does not mean vendoring or forking Agave/Firedancer code. Vexor is an independent, from-scratch Zig implementation; Agave and Firedancer are read as behavioral references, reimplemented independently, and verified byte-for-byte against their output — see Attribution & License for exactly what "reference, not fork" means and how that reimplementation is tracked file-by-file in the project's provenance ledger.
  • It does not mean adopting every upstream change immediately. Non-consensus-affecting changes (performance work, internal refactors, tooling) are evaluated on their own merits, not pulled in reflexively just because upstream did them. What's non-negotiable is staying byte-faithful on the surfaces that are actually consensus- or interop-load-bearing — the bank hash, the wire encodings, the RPC JSON — which is the boundary Why Byte-Faithful Parity draws explicitly.
  • It does not mean assuming a past fix still holds. As demonstrated in the incident postmortems, a fix that was correct when it shipped can be silently invalidated by an unrelated later change, either upstream or local. Structurally-related prior fixes get re-verified against current source as part of investigating any new, related issue — never assumed intact by default.

See also