Bundle data contracts

What a published run contains, how /benchmarks finds and reads it, and the exact data contract behind each chart. Wiring real data means publishing bundles in this format; no page code changes.

From engine to page

engine host (append-only)       verifier (anyone, read-only)              publication
manifest.json  intents.jsonl    rbench.verify → verified/metrics.json     rbench.publish --tier public → dist/<run>/
attempts.jsonl clock.jsonl      (recomputed from chain via your RPC)      rbench.index --dist dist → dist/index.json
                                                                          site: NEXT_PUBLIC_BENCH_INDEX_URL=<…>/index.json

The index: `rout-bench-index.v1`

Field	Meaning
`path`	Bundle folder, relative to `index.json`
`kind`	`verified_run` (E0, A1, A2, B, C) or `step0`
`run_id`, `protocol_id`, `protocol_version`, `experiment`, `title`	Identity, copied from the manifest and protocol
`tier`, `cluster`, `started_at`, `ended_at`, `verifier_version`	Provenance
`status`	`verified`, `integrity_failed`, `voided` or `superseded` (`STATUS.json` in the bundle)
`superseded_by`, `note`	Correction trail; runs are never removed
`synthetic`	`true` when the bundle holds a `SYNTHETIC` marker; production builds hide it
`files`, `sha256sums`	What can be downloaded, and the hash of `SHA256SUMS`

The index carries no metric values. Every number comes from a bundle's own metrics.json or step0.json, parsed against the Zod contracts in src/adapters/schemas.ts. A file that doesn't parse shows an error, never a guess.

Row schemas

Every field carries x-field-class: measured, engine-assigned, configured or computed (verifier only).

anchor-observation.v1.schema.json Anchor observation v1

Written by the verifier: the chain's slot for each anchor that has a signature. A mismatch with the engine's anchor.slot fails the run.

Field	Type	Class	Required
`intent_id`	string	—	yes
`signature`	string	—	yes
`found`	boolean	—	yes
`slot`	integer \| null	—	yes
`rpc_label`	string	—	yes

sha256 c6e4b483…a1867201

attempt.v1.schema.json Attempt v1

One row per signed copy sent to one provider.

Field	Type	Class	Required	Description
`run_id`	string	—	yes
`intent_id`	string	—	yes
`attempt_id`	string	engine-assigned	yes	Unique within the run.
`provider`	string	configured	yes	Submission provider label.
`endpoint_region`	string	—	yes
`signature`	string	measured	yes	This copy's signature (copies differ, so each is attributable).
`sent_mono_ns`	integer	measured	yes	Monotonic time the send call returned.
`send_result`	"accepted" \| "rejected" \| "timeout" \| "error"	measured	yes	Provider's synchronous answer only.
`send_error`	string \| null	—	—
`tip_lamports`	string	—	yes	Exact integer in base units, as a decimal string.

sha256 8e769980…bc3168e7

clock.v1.schema.json Clock sample v1

Periodic mapping between a host's monotonic clock and disciplined wall time.

Field	Type	Class	Required	Description
`run_id`	string	—	yes
`host_id`	string	—	yes
`mono_ns`	integer	—	yes
`wall_unix_ns`	integer	—	yes
`offset_ns`	integer	measured	yes	Offset reported by the time daemon.
`source`	string	—	yes

sha256 838608e8…0c64179b

intent.v1.schema.json Intent v1

One row per intent the engine created, including refused and failed ones. The denominator of every rate.

Field	Type	Class	Required	Description
`run_id`	string	—	yes
`intent_id`	string	engine-assigned	yes	Unique within the run; the dedup key.
`trace_id`	string	engine-assigned	yes	Joins engine spans for this intent.
`experiment`	"E0" \| "A1" \| "A2" \| "B" \| "C"	configured	yes	Experiment id.
`arm`	string	engine-assigned	yes	Arm chosen by the pre-registered randomizer.
`stratum`	object	measured	—
`host_id`	string	—	yes
`created_mono_ns`	integer	measured	yes	Host monotonic clock when the intent was created.
`decided_mono_ns`	integer \| null	measured	—	Monotonic time the strategy decided.
`signed_mono_ns`	integer \| null	measured	—	Monotonic time the first copy was signed.
`anchor`	object	—	yes	The on-chain reference that Δslot is measured from.
`engine_outcome`	"submitted" \| "refused" \| "expired_before_submit" \| "error"	measured	yes	What the engine did; landing is decided by the chain, not here.
`refusal_code`	string \| null	—	—
`side`	"probe" \| "buy" \| "sell"	—	yes
`mint`	string \| null	configured	—	Token mint, null for probes.
`size_raw`	string \| null	—	—	Exact integer in base units, as a decimal string.
`tip_lamports`	string	—	yes	Exact integer in base units, as a decimal string.
`slippage_bps`	integer \| null	—	—
`nonce_mode`	"durable_nonce" \| "recent_blockhash"	—	yes
`nonce_account`	string \| null	—	—
`quote`	object \| null	—	—	Pre-trade curve quote at the anchor slot, for fill quality.
`seq`	integer	engine-assigned	yes	Gap-free sequence number from 0 within the run. A gap means a hidden intent; the verifier fails the run.

sha256 91b09ce3…015365f6

observation.v1.schema.json Chain observation v1

Written by the verifier from an independent RPC. Never written by the engine.

Field	Type	Class	Required	Description
`run_id`	string	—	yes
`intent_id`	string	—	yes
`attempt_id`	string	—	yes
`signature`	string	—	yes
`status`	"landed_ok" \| "landed_err" \| "not_found"	computed	yes	From getSignatureStatuses / getTransaction.
`slot`	integer \| null	—	yes
`err`	string \| null	—	yes
`fee_lamports`	integer \| null	—	yes
`block_time`	integer \| null	—	—
`rpc_label`	string	—	yes
`commitment`	"confirmed" \| "finalized"	—	yes

sha256 1cbd121e…c2a53af5

protocol.v1.schema.json Pre-registered protocol v1

Hashed and published before the first intent. status=finalized requires every parameter and acceptance value to be non-null.

Field	Type	Class	Required	Description
`protocol_id`	string	—	yes
`version`	integer	—	yes
`experiment`	"S0" \| "STEP0" \| "E0" \| "A1" \| "A2" \| "B" \| "C"	—	yes
`status`	"draft" \| "finalized"	—	yes
`title`	string	—	yes
`hypothesis`	string	—	yes
`customer_value`	string	—	yes
`unit`	string	—	yes
`arms`	array	—	yes
`primary_metric`	object	—	yes
`secondary_metrics`	array	—	yes
`parameters`	object	—	yes	Numbers the analysis uses. null = not yet agreed.
`randomization`	object	—	yes
`denominator`	string	—	yes
`exclusions`	array	—	yes
`stopping_rule`	string	—	yes
`acceptance`	object	—	yes	Thresholds agreed with the partner. null = not yet agreed.
`redact_by_tier`	object	—	yes
`requires`	array	—	yes	Dependency ids from 14-backlog (e.g. E1, PARTNER-DATA).

sha256 1e55ba58…7fd31c7c

run-manifest.v1.schema.json Run manifest v1

One per run. Written before the first intent and never edited; the verifier refuses a run whose protocol hash does not match.

Field	Type	Class	Required	Description
`schema_version`	"1"	—	yes
`run_id`	string	engine-assigned	yes	Random UUIDv4, immutable.
`protocol_id`	string	configured	yes	Pre-registered protocol id.
`protocol_sha256`	string	computed	yes	rbench.io.protocol_hash of the finalized protocol file.
`tier`	"internal" \| "partner_confidential" \| "public"	configured	yes	Who may see this run's raw rows.
`cluster`	"mainnet-beta" \| "devnet" \| "testnet"	configured	yes	Solana cluster.
`started_at`	string	measured	yes	UTC wall time of the first intent.
`ended_at`	string \| null	measured	yes	UTC wall time of the last intent; null while running.
`engine`	object	—	yes
`hosts`	array	—	yes
`reference_rpc`	object	—	yes	Which independent RPC the verifier used. Never a URL with a key.
`operator`	string	—	yes	Who ran it: rout, a partner, or a third party.
`notes`	string	—	—
`schedule`	object \| null	configured	—	Slot range for scheduled probes (rbench.assign). Declared before the run; every scheduled slot in it must have an intent.

sha256 610b8c64…4a371d0f

Chart contracts

The same definitions appear under "About this chart" on every chart.

Chart	Question	Data	Uncertainty	Never
Landed within the window	How often does each path land in time?	metrics.json → arms[arm].landed_within_window {k, n, rate, ci} protocol.json → parameters.landing_window_slots, confidence	Wilson score interval at the protocol's confidence (rbench.stats.wilson). Whisker = interval; dot = k/n.	A bar (implies a total), an axis that starts above 0%, or a rate without k/n.
Difference between arms	Is the difference large enough to act on, and is it real?	metrics.json → comparisons[i].landed_within_window_difference {estimate, ci, cluster_bootstrap_ci, cluster_slots} protocol.json → acceptance.*	Two intervals per row: Newcombe hybrid score (independent intents) and cluster bootstrap over cluster_slots blocks. The gate uses the wider one; it is drawn darker.	Reading overlap of two separate rate intervals as a test; showing only the narrower interval.
Slots to inclusion	How soon after the trigger does a transaction land, across the whole tail?	intents.jsonl → intent_id, arm, anchor.slot observations.jsonl → intent_id, status, slot (verifier-written, independent RPC) metrics.json → arms[arm].delta_slot_quantiles (headline quantiles)	Curve is the empirical CDF. Quantile intervals come from metrics.json (distribution-free order statistics); a quantile without an interval is marked 'indicative'. The page recomputes the quantiles from rows and flags any mismatch with metrics.json.	A ms axis from cross-host clocks; a curve normalised to landed-only intents without saying so.
Δslot quantiles	What do p50, p90, p95 and p99 look like, and how sure are we?	metrics.json → arms[arm].delta_slot_quantiles[] {q, value, ci, note}	Order-statistic interval, or the verifier's 'indicative only' note when n is too small for one (p99 at 95% needs n ≥ 368).	A p99 printed without its interval or its 'indicative' flag.
Every intent, by outcome	Where do the failures go? Is anything hidden from the denominator?	metrics.json → arms[arm].classes {landed_ok, landed_err, not_landed, refused, expired_before_submit, engine_error} metrics.json → arms[arm].n_intents	Counts, no interval. The stack must sum to n_intents; the page checks and flags it.	Dropping refused, expired or engine-error intents.
Δslot shift	Among landed transactions, is one path earlier?	metrics.json → comparisons[i].delta_slot_shift {estimate, ci, method, caveat}	Seeded percentile bootstrap interval.	Showing the shift without the landing difference beside it (a faster arm that lands less often hasn't won).
Which route's copy landed	When one intent is sent through several routes, which one wins?	metrics.json → arms[arm].provider_win_share[route] {k, n, rate, ci}	Wilson interval. Valid as a paired comparison only under durable nonce, where exactly one copy can land.	Naming a provider without legal review and consent (legal review first).
By condition	Does the result hold under congestion, across leader-window positions and regions?	metrics.json → strata[key][] {arm, value, k, n, rate, ci}	Wilson interval per cell. Descriptive only: strata are not separate significance claims unless the protocol says so (Holm).	Promoting a single stratum to a headline.
Cost per landed transaction	What does each success cost, including what was spent on failures?	metrics.json → arms[arm].spend_lamports {fees_chain_observed, tips_engine_reported, per_landed_ok}	Point values (no interval in the verifier yet). Fees are chain-observed; tips are engine-reported until E7 lets the verifier match tip transfers.	Merging engine-reported tips into a 'verified' total.
Engine-reported timing	Where does time go inside the engine?	metrics.json → internal_latency_ns[span] {n, quantiles[]}	Order-statistic intervals. Not chain-verifiable: these are the operator's own timestamps.	Promoting these spans to a headline, or adding them to Δslot.
Protection gap	After outside buys cross a guard threshold, how long until the creator exits, and how much flow gets in?	step0.json → results[] {threshold_lamports, block0_cohort_counted_as, outcomes, share_crossed, gap_slots[], per_mint[]}	Order-statistic intervals on quantiles; Wilson on share crossed. Market-wide baseline, not any one platform's launches unless that platform supplies its mint list.	Presenting the market-wide baseline as one platform's launches.
Share of launches that crossed	How often does outside flow reach each threshold at all?	step0.json → results[] {threshold_lamports, share_crossed {k, n, ci}}	Wilson interval at the protocol's confidence.	A denominator other than every launch in the published list.

Page states

State	When	What the reader sees
Unconfigured	`NEXT_PUBLIC_BENCH_INDEX_URL` is empty	"No published runs on this deployment", with links to the method. Never an error.
Loading	Fetching index, bundle or rows (TanStack Query)	Skeleton at the content's final height; chart frames and questions render at once.
Empty	Index has no runs for this view	What would have to happen for a result to exist, and what to read meanwhile.
Error: network	Host unreachable or non-2xx	Inline error where the data belongs, the failing URL, Try again (Query refetch).
Error: format	A file fails its schema	"This file doesn't match the format this site reads", with the JSON path.
Integrity failed	`metrics.integrity_problems` is non-empty	Red banner listing each problem above all figures.
Synthetic	Bundle has `SYNTHETIC` and the dev build allows it	Warning banner and badge on every view. Production never shows these.
Disputed	Quantiles recomputed from rows differ from `metrics.json`	Red note naming each mismatch.

Search

Bundle data contracts

From engine to pageCopy Anchor Link

The index: rout-bench-index.v1Copy Anchor Link

Row schemasCopy Anchor Link

Chart contractsCopy Anchor Link

Page statesCopy Anchor Link

From engine to page

The index: `rout-bench-index.v1`

Row schemas

Chart contracts

Page states