Build-Flag Reference¶

Docs-site note (2026-07-11): 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 page includes the one-flag build shortcut (-Dprod) and a minimal recipe showing how little a deploy needs today — most of what used to be a long flag list is now baked into the binary itself. 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. Vote execution and BN254/Poseidon leaf crypto are unconditional — no flag selects an alternative; see Consensus.

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=fast

-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 clarity: crypto (ed25519, BLAKE3, BN254/alt_bn128, Poseidon) is unconditionally Vexor's own pure-Zig vex_crypto implementation, and the resulting binary links zero Firedancer symbols at runtime. See Consensus 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 produces byte-identical bank hashes with the current flag surface (446/446 vote KATs, both carriers canon, 1992/1992 golden replay).

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.

Always applied (target + optimize)¶

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

Flag	Value	Meaning
`--release=fast`	—	The canonical release mode (ReleaseFast). Note the value is inert: `build.zig` pins a preferred optimize mode, so `fast`, `safe` and `small` all yield the same binary — but omitting `--release` yields a Debug build, which is roughly 30× slower and falls behind the cluster tip. Verify from the artifact, not the flag: `strings <bin> \| grep -c 'reached unreachable code'` must be `0`.
`-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¶

Two consensus-critical behaviors are unconditional — no build flag selects an alternative, and there is no alternative code path to select:

Behavior	Status
Vote execution	Unconditional — Vexor's own vote program (marker: `voteforge`) is the sole executor.
BN254/Poseidon leaf crypto	Unconditional — Vexor's own pure-Zig `vex_crypto` backend.

-Dpure_zig remains an accepted build flag, but is a no-op — 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. 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 the only case, for every binary.	No — independent of `-Dprod`, but passed alongside it (`-Dprod -Dpure_zig`) on the canonical production build command

Vexor's vote program is Vexor-authored — implemented directly to the protocol's vote-program specification. It is proven correct through staged, gated differential validation (446/446 vote KATs, both carriers canon, 1992/1992 golden replay) before being trusted to run alone. 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.

Vexor's own pure-Zig ed25519 and BLAKE3 run unconditionally; see Consensus.

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`. 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 zero-hash tick rule, which provably can't false-reject a valid block) \| `full` (a stricter, protocol-conformant 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.

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=fast

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.