Skip to main content
For SDK maintainers and pipeline operators who want to run one SDK or pipeline, at any version, over chosen real ledgers: a ledger range, one transaction, a named set, the ledgers of a CAP, or a known issue before and after its fix. 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: &lt;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’s summary.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

The issue’s ledger is testnet 5521432 from the corpus entry 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.
The dataset directory is --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

From a linter diagnostic to a replay:

Run directory

Every xdrcheck 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 is check|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:
For a pubnet ledger the README also gives the public lake URL of the object, so curl -s URL | sha256sum shows the bytes are the network’s own.

Worked example: js-stellar-sdk #1766 on a clean machine

Copy bundles/js-1766 anywhere a checkout of this repository and Node.js are, then one command:
And without the kit:
A bundle names no internal finding: its cluster key is the target’s own message, and dispositions are not copied into it.