xdrcheck replay has three forms:
xdrcheck replay --help prints the three usage lines; xdrcheck replay --target T --help and
xdrcheck replay --rig R --help print the flags of the other two forms.
Selection
Ledgers that no local lake holds are downloaded from the public lake into the ledger cache first (size and MD5
checked, as
xdrcheck data fetch does), unless --offline.
Targets and versions
The sweep programs are embedded in the
xdrcheck binary. Each (target, version) is built once into
$XDRCHECK_CACHE/targets/<target>/<version>/ (default ~/.cache/xdrcheck) and reused; a tag or full commit is never
rebuilt, a branch is re-resolved on every run (pass --offline to use the cached build), and a changed sweep
program is rebuilt. The run manifest records both the version asked for and the version built (for main, the Go
pseudo-version or the package version and ref).
The SDK sweeps need the target’s own toolchain: Go for go, Node.js 22.15 or newer and npm for js, Python 3
and the zstd command for python, Rust for rust. A missing toolchain is reported as not available: <tool> missing, with status unavailable and no rows; it is never a pass.
Pipeline targets
Pipeline targets run through two programs:
Every judge verdict other than
ok becomes a row with check judge-<kind> and the judge’s class; unknown (the
judge’s truth is incomplete) has verdict error, the others (missing, extra, wrong_value, duplicate,
skip, halt) fail.
A pipeline run whose rig did not ingest every ledger is partial: its rows are still judged (the judge turns a halt
into a row, so a known halt stays visible to clusters and run comparison), and the summary message counts the
ledgers not ingested (see work/rig/status.jsonl). A run whose rig wrote no status.jsonl, or ingested every
ledger and wrote an empty rows.jsonl, is failed.
Run states and exit codes
The run directory’ssummary.json has one of four states (run-directory.md):
Bad arguments also exit 2, before any run directory is written. The rig form (
--rig) exits as the rig does
(0, 1 or 2, above).
Worked example: a known issue, before and after its fix
cap-0038/pool-issuers-order-by-bytes-not-strkey;
the pool-share trustline in its transaction 2 has issuers whose strkey text order is the reverse of their byte
order. The fixed version parses it; the builder default that remains on both is noise by disposition.
The same transaction on mainnet-style input, any version:
issues.json
go/internal/hunt/issues/issues.json (schema schemas/issues.schema.json) maps a public issue to its target, the version before and after the fix, the corpus entry or ledger that shows it, the transaction, and the expected check and class. Only public issues belong there.
Dataset
The dataset is what the mainnet scan derived: the shape census per level and kind, the greedy covers, the token census and its leads, the kept-ledger index, the locate index, the value tags, the corpus entries and the public findings, plus named ledger sets.xdrcheck find and xdrcheck replay resolve their selections through it. A
dataset directory holds one manifest.json (schema schemas/dataset-manifest.schema.json, xcc.dataset/v1) that
points at those files with their size and sha256; large files are never copied.
--dataset, else $XDRCHECK_DATASET, else ~/.local/share/xdrcheck/dataset. The ledger cache is
--lake, else $XDRCHECK_LAKE, else <dataset>/lake.
The manifest
Tables:
shapes (every distinct shape per level G0–G3 and kind, with occurrences and first/last ledger),
census_summary, census_facts, tokens, covers, cover_summary, rare_tokens, value_extremes,
event_signatures, rare_results, rare_change_cells, kept_ledgers, kept_tx_shapes, kept_components,
scan_occurrences, scan_tx_shapes, scan_components, locate, tags, tag_summary, corpus_entries,
findings.
Sets: controls, kept, token-cover, g0-cover, cap-<n> (the corpus ledgers of each CAP captured from the network’s history), and
never-seen-generated (ledgers a local stellar-core closed for arms mainnet has not shown).
Worked example
fetch writes the lake layout (<partition>/<object>.xdr.zst) and an index.tsv (seq path size md5). Each
download is checked against Content-Length and the ETag (the public lake’s objects are single-part, so the
ETag is their MD5); a mismatch is retried with back-off and then reported, never written. At most 256 requests
are in flight (--parallel, default 64) and --rate caps requests per second (default 200). It is resumable: a
ledger already in the cache with its recorded size and MD5 is kept. With --from-local (default) a ledger a
read-only lake of the dataset holds is copied, not downloaded.
Keeping the data current: xdrcheck data update
update prints the plan of a top-up from the tip and runs nothing. The dataset is append-only: a top-up adds one
new block of every table for the ledgers after the tip (scan, census, token census, cover additions, locate, value
tags) and writes a new manifest version that lists the old files unchanged plus the new ones. A run directory
records the dataset version and the manifest’s sha256 it resolved its selection through, and old versions’ files
never change, so old runs stay reproducible.
find
xdrcheck find answers “which mainnet transactions show X?” with ledger, tx pairs that xdrcheck data fetch and
xdrcheck replay --tx take as they are. It reads the dataset’s plain index files (data.md); there is no
query engine.
Orders:
first and last by ledger, rarest by the census occurrences of the rarest matched token, random
with --seed.
Worked examples
Run directory
Everyxdrcheck replay --target run writes one directory. It is what the dashboard, xdrcheck repro pack, xdrcheck runs
and a CI job read; nothing else of a run is a contract. The JSON Schemas are in schemas, and the
xdrcheck binary carries a copy, so xdrcheck runs validate DIR checks a directory without a checkout.
Passes are not rows: a check that ran a million times and failed twice gives two rows and
tested: 1000000 in
the summary. With --tx, rows are limited to the selected transactions while the tested counts still cover the
whole ledgers (the summary’s message says so).
Cluster keys and dispositions
The key ischeck|class and leaves out the version, so the same defect has the same key at every version of the
target: xdrcheck runs compare A B lists the keys a fix removed (-) or a change brought (+). The class is the
target’s message with values removed (strkeys, hex, numbers, quoted strings), or a structured difference such as
rebuild-differs:cond:v2>v2.
A disposition says what a cluster is:
The public table (
go/internal/hunt/rundir/dispositions.tsv) holds noise rules only and never names a finding.
xdrcheck runs
validate checks each file against its schema and that verdicts.jsonl, clusters.json and summary.json count
the same rows (exit 1 on any problem). compare exits 1 when the two runs differ in their keys.
Example rows
repro
Use a bundle to hand one result to an SDK or pipeline maintainer: it holds the ledger, the transaction, the command and a standalone script, and runs on a clean machine.What a bundle holds
repro run checks every file’s sha256 and the ledger header hash, then runs the bundle’s command (an
xdrcheck replay --target … --ledger-file ledger/<seq>.xdr.zst --tx …) into BUNDLE/run, and looks for a row with the
expected check and class on the expected transaction. --version runs another version: a fixed version should give
NOT REPRODUCED.
repro verify recomputes the header hash (sha256 of the LedgerHeader equals the hash the LedgerCloseMeta
records), and runs the stellar-core commands when stellar-core is on PATH or in $XDRCHECK_STELLAR_CORE:
curl -s URL | sha256sum shows
the bytes are the network’s own.
Worked example: js-stellar-sdk #1766 on a clean machine
bundles/js-1766 anywhere a checkout of this repository and Node.js are, then one command: