Build-Flag Reference¶

Docs-site note (rewritten 2026-07-11, updated 2026-07-12 for Stage 8): This is an exhaustive reference of every -D build flag in Vexor's build.zig, what each enables, its default, and whether it ships in the standard build. Every row is read directly from build.zig and the canonical build/deploy references it's gated by. This rewrite adds the one-flag build shortcut (-Dprod), a minimal recipe showing how little a deploy needs today, and a history note on the now-completed vote-program cutover (see Consensus (no longer flag-gated)) — most of what used to be a long flag list is now baked into the binary itself, and the Sig-derived vote oracle + Firedancer Ballet crypto backend that used to be flag-gated have both been removed from the tree outright. For the runtime (VEX_* env var) side of that story, see the Environment Variable Reference.

Testnet only. Vexor is a testnet-only, 0.9.x pre-production validator client. The build and deploy commands on this page produce the recommended testnet configuration — nothing here implies mainnet readiness.

How to read this page¶

Vexor's binary is configured at build time with zig build -D<flag>=<value>. Every flag in build.zig defaults to false (or its listed default), so a bare zig build is a minimal/forensic-floor binary, not a production one.

Two-gate model. Many flags are comptime gates only — they compile a capability in, but historically it stayed dormant until a matching runtime environment variable (VEX_*) was also set at deploy time. That's still true for a handful of experimental features, but for the flags that matter for a normal voting deploy, the runtime side is now also defaulted on inside the binary (see Environment Variable Reference) — so building the flag in is, in practice, enough.

Category legend: operational = shipped in -Dprod but not itself a consensus input (liveness/production plumbing); perf = throughput/latency, bank-hash-neutral; ledger = blockstore; networking = liveness/citizenship, never touches consensus; forensic = diagnostic/escape-hatch, not part of a normal deploy. (There used to be a consensus-required category — flags whose absence caused a bank-hash divergence — but as of 2026-07-12 the two flags that lived there, -Dsig_vote and -Dballet_bn254, have both been removed; see Consensus (no longer flag-gated).)

The one-flag build — `-Dprod -Dpure_zig`¶

A single -Dprod bundles the eight flags a production voting deploy needs into one switch:

zig build -Dprod -Dpure_zig -Dcpu=znver4 --release=safe

-Dprod turns on: leader_mode, repair_stake_weighting, parallel_exec, fec_dedup, watchdog, status_cache, use_native_quic_votes, vex_ledger.

-Dpure_zig is kept on the command line for compatibility but is now a no-op: crypto (ed25519, BLAKE3, BN254/alt_bn128, Poseidon) is unconditionally Vexor's own pure-Zig vex_crypto implementation — the Firedancer Ballet backend -Dpure_zig used to override no longer exists in build.zig at all (removed 2026-07-12, commit a4da7e8), and the resulting binary links zero Firedancer symbols at runtime either way. See Consensus (no longer flag-gated) and Performance below for the per-flag detail, and Building Vexor for the full rationale.

Each remaining flag stays individually overridable — -Dprod -Dpure_zig -Dfec_dedup=false builds everything else on and drops just that one.
-Dprod and -Dpure_zig both default off, so a bare zig build (neither flag) is unchanged — useful for the test suite and for isolating a single flag during a bisect.
Validated: an offline replay produced byte-identical bank hashes across the flag-surface reductions described in this page (446/446 vote KATs, both carriers canon, 1992/1992 golden replay) — dropping sig_vote/vote_ab/vote_live/the ballet_* flags was a code-surface cleanup, not a behavior change.

This is now the recommended way to build Vexor. The per-flag tables below still apply — -Dprod is exactly the union of the flags in Operational, Performance, Ledger, and one Networking flag (use_native_quic_votes) further down this page. -Dpure_zig is documented as its own row in Consensus (no longer flag-gated).

Always applied (target + optimize)¶

Not -D feature flags, but passed on every production build:

Flag	Value	Meaning
`--release=safe`	—	Optimized with safety checks — the canonical release mode. A Debug build is significantly slower and falls behind the cluster tip.
`-Dcpu=<target>`	e.g. `znver4`	Target the host's CPU ISA. `znver4` (AMD EPYC Zen 4) unlocks AVX-512, SHA-NI, VAES; pick the flag matching your CPU generation.

Consensus (no longer flag-gated)¶

This page used to have a "Consensus-required" section listing the flags whose absence produced a bank-hash divergence. As of 2026-07-12 there are none — the two consensus-critical choices that used to be build flags are now unconditional, with no alternative code path left to select instead:

Former flag	Status	What replaced it
`-Dsig_vote`	Removed (Stage 8, commit `34ffb4e`, 2026-07-12)	Vote execution is unconditional voteforge (Vexor's own vote program) — no flag selects it, and the Sig-derived alternative it used to gate no longer exists in the tree.
`-Dballet_bn254`	Removed (commit `a4da7e8`, 2026-07-12, pre-dates Stage 8)	BN254/Poseidon leaf crypto is unconditionally Vexor's pure-Zig `vex_crypto` backend — no flag, and the Firedancer Ballet alternative it used to gate no longer exists in the tree.

-Dpure_zig remains an accepted build flag, but is now a no-op for the same reason — there is nothing left for it to override:

Flag	Default	What it enables	In `-Dprod`
`-Dpure_zig`	`false`	No-op, kept for build-command compatibility/self-documentation. Crypto (ed25519, BLAKE3, BN254/alt_bn128, Poseidon) is unconditionally Vexor's own `src/vex_crypto/` pure-Zig implementation regardless of this flag — the `ballet_` flags it used to force off were deleted from `build.zig` outright, not just defaulted off. Zero Firedancer symbols linked, always. Still requires `VEX_ALLOW_NO_BN254=1` at deploy time (see Environment Variable Reference) — the boot guard's "no Ballet BN254 linked" case is now the only* case, for every binary.	No — independent of `-Dprod`, but passed alongside it (`-Dprod -Dpure_zig`) on the canonical production build command

History. Vexor's vote program is Vexor-authored — a from-scratch rewrite derived from Agave 4.2 semantics. During development, a Sig-derived implementation (linked by -Dsig_vote) served as a differential-test/shadow oracle validating the rewrite byte-for-byte; -Dvote_ab armed the A/B harness and -Dvote_live (Stage 7) flipped production traffic onto voteforge while keeping the oracle running as a shadow-checker. Stage 8 (2026-07-12, commit 34ffb4e) deleted the oracle and all three flags (−31,181 lines) once voteforge's own gates (446/446 vote KATs, both carriers canon, 1992/1992 golden replay) were sufficient on their own. See The Vote Program for the full story.

Operational¶

Shipped in -Dprod, not consensus inputs themselves, but load-bearing for a validator to actually produce blocks and stay supervised in production.

Flag	Default	What it enables	In `-Dprod`
`-Dleader_mode`	`false`	Enable the block-production tick loop in replay (broadcast is gated separately, and transaction-bearing production is not yet enabled — see status).	Yes
`-Dwatchdog`	`false`	Spawn a liveness watchdog thread, observation-only by default. Restart-on-wedge needs `VEX_WATCHDOG_RESTART`, which is baked on by default at runtime.	Yes

Performance¶

Bank-hash-neutral throughput/latency wins. Several are two-gate: the build flag compiles the capability in, and a runtime env var arms it. As of the current binary, the arming envs for parallel_exec and fec_dedup are baked on by default at runtime (see Environment Variable Reference) — building with -Dprod is now sufficient for those two. status_cache is the one exception: it still requires an explicit VEXOR_STATUS_CACHE=1 at deploy time.

-Dballet_ed25519 and -Dballet_blake3 (Firedancer Ballet AVX-512 leaf-crypto perf flags) no longer exist — removed with the rest of the Ballet backend (commit a4da7e8, 2026-07-12). Vexor's own pure-Zig ed25519 and BLAKE3 run unconditionally; see Consensus (no longer flag-gated).

Flag	Default	What it enables	Arming env	Baked at runtime?	In `-Dprod`
`-Drepair_stake_weighting`	`false`	Stake-weight repair-peer selection — decides whom to ask for a missing shred, never what is accepted, so it has no consensus impact. Off = round-robin.	—	n/a	Yes
`-Dparallel_exec`	`false`	Wave-barrier parallel transaction execution over a persistent worker pool. Marker: `WavePool`. Its old precondition, `-Dsig_vote`, no longer exists — voteforge reads canonical LOCAL SlotHashes, so the wave path is safe unconditionally.	`VEX_PARALLEL_EXEC`	Yes, default `1`	Yes
`-Dfec_dedup`	`false`	Ed25519 FEC-set signature-dedup cache in the verify tile — the first shred of a FEC set runs signature verify, siblings skip it.	`VEXOR_ED25519_FEC_DEDUP`	Yes, default `1`	Yes
`-Dstatus_cache`	`false`	Cross-block `AlreadyProcessed` recent-signature cache, needed for transaction-bearing block production. Bank-hash-neutral.	`VEXOR_STATUS_CACHE`	No — must set explicitly	Yes
`-Djemalloc`	`true`	Link jemalloc as the allocator (returns freed pages to the OS; linked as a real dependency so capability-stripping can't remove it). Default on.	—	n/a	(default-on regardless)
`-Dtwo_tier`	`true`	Two-tier AccountsDB read/commit path. Default on.	—	n/a	(default-on regardless)

Ledger¶

Flag	Default	What it enables	Arming env	Baked at runtime?	In `-Dprod`
`-Dvex_ledger`	`false`	Wire VexLedger, Vexor's Zig-native blockstore (shreds + metadata persisted under `--ledger`). Comptime-dead and byte-identical when off. See VexLedger.	`VEX_LEDGER` (+ tunables)	Yes, default `1`	Yes

Networking¶

Liveness / network-citizenship features. None of these touch bank hash or consensus. -Duse_native_quic_votes is the one exception that ships in -Dprod today (it runs automatically once built, no separate arming env); the rest are separate opt-ins, each with its own soak history, and are not in -Dprod.

Flag	Default	What it enables	Arming env	In `-Dprod`
`-Duse_native_quic_votes`	`false`	Route votes through a native QUIC TPU client (mTLS identity, staked QoS), with a UDP/curl fallback so a QUIC hiccup can't cause delinquency. Runs automatically once built — no separate arming env.	—	Yes
`-Dduplicate_shred`	`false`	Push `DuplicateShred` (CRDS type 9) equivocation proofs over gossip. Detection always compiles in; this arms the outbound push.	`VEX_DUPLICATE_SHRED`	No
`-Dturbine_retransmit`	`false`	Retransmit received shreds to this node's turbine-tree children after a successful insert. Currently hardcoded off in `build.zig` — there is no live build option wired to turn it on yet, so this is inert regardless of the runtime env.	`VEX_TURBINE_RETRANSMIT` (inert until the build gate is wired)	No
`-Dgeyser`	`false`	Geyser-style streaming plugin — account/slot notifications over a unix socket, wait-free and drop-on-full so it can never block consensus.	`VEX_GEYSER`	No
`-Drpc_store`	`false`	Populate the RPC block/transaction-history stores on the replay path. Reads are always wired; this gates only the replay-path population.	`VEX_RPC_STORE`	No

Forensic / escape-hatch / scaffold¶

Diagnostic builds and A/B escape hatches. None of these are in -Dprod; not part of a normal deploy.

Flag	Default	What it enables
`-Dverify_ticks`	`zerohash`	Block tick-validity level: `off` (no check, escape hatch) \| `zerohash` (default — the validated rc.1 zero-hash tick rule, which provably can't false-reject a valid block) \| `full` (stricter Agave/Firedancer-style check, still soak-gated).
`-Dsentinel_node`	`false`	Firedancer-style sentinel-node bank tree — placeholder banks for slots whose parent isn't yet known. Staged, not landed.
`-Dsig_clock`	`false`	Live per-vote-account `last_timestamp` source for the Clock sysvar estimate, vs. a fork-aware cache snapshot.
`-Dlegacy_pins`	`false`	Use the old inline core-pinning literals instead of the declarative topology table — an instant escape hatch if the topology table is ever suspect.
`-Dalpenglow`	`false`	Scaffold awareness for the Alpenglow consensus migration. Off = TowerBFT-only, which is what testnet runs today — Vexor has no live Alpenglow/Votor path.
`-Djeprof`	`false`	Embed jemalloc heap-profiling into the binary — diagnostic boots only.

The internal differential-oracle flags that used to exist behind the vote-program rewrite (-Dsig_vote, -Dvote_ab, -Dvote_live — see Consensus (no longer flag-gated) above) are gone, not just omitted — the oracle they built was deleted from the tree in Stage 8 (2026-07-12). A -Dgit_hash build-stamp flag and CI-tooling scaffolding remain and are intentionally omitted here because they are not part of any normal build a validator operator would run.

Minimal recipe¶

Between -Dprod on the build side and the runtime baked-defaults on the deploy side, a standard voting deploy no longer needs a long flag list. What's actually left to decide is: which binary, which keys, which network address, and (if applicable) your hardware layout.

Build once:

zig build -Dprod -Dpure_zig -Dcpu=znver4 --release=safe

Deploy:

VEX_BINARY=<pinned> VEX_ALLOW_NO_BN254=1 VEX_ENABLE_AFXDP=1 VEX_FRESH_SNAPSHOT=1 VEX_PARALLEL_EXEC=1 \
VEX_PARALLEL_EXEC_CORES=25,26 VEX_TASKSET_CORES=<mask> bash deploy.sh dev

VEX_BINARY, VEX_PARALLEL_EXEC_CORES, and VEX_TASKSET_CORES are machine-specific and are never baked — you supply them for your own box (see Hardware for how the core layout maps to a given CPU). VEX_ENABLE_AFXDP, VEX_FRESH_SNAPSHOT, and VEX_PARALLEL_EXEC are shown explicitly for clarity, but VEX_PARALLEL_EXEC is also one of the baked feature envs the binary defaults on if you leave it unset (see Environment Variable Reference). VEX_ALLOW_NO_BN254=1 is required for a -Dpure_zig binary — it tells the BN254 boot guard that no Firedancer Ballet BN254 library is linked by design (see Building Vexor). deploy.sh also needs your --identity, --vote-account, and --public-ip — those are validator-identity settings, not build/feature flags, and are covered in full on Deploying Vexor.

Everything else — the ledger write path, FEC-set dedup, repair tuning, fork-switch handling, vote refresh, the watchdog restart policy — is filled in automatically by the binary the first time it runs, unless you explicitly override one with =0. See the Environment Variable Reference for the complete baked-default list and what each flag actually does.