Skip to main content
For SDK maintainers and indexer operators who run the kit by hand or from CI. It lists every tool and command, the conventions they share, and each command’s own --help, so you can find the flag you need and tell from an exit code whether your reader or the kit failed. The kit has three main command-line tools, two helper tools (the judge, which the target form of xdrcheck replay calls, and the value tagger), and a Makefile that runs them: make build builds all five, the replay adapters (baseline, wallet-backend-adapter, stellaretl) and xdrcheck-mutate, and links each into ./bin (Rust binaries always go to ./target, whatever CARGO_TARGET_DIR the shell exports). It ends by printing the line that puts them on your PATH:
The examples on this page write bare xdrcheck, xdrcheck-corpus and xdrlint for those binaries. Each section below has a short summary written by hand and then the tool’s own --help output, copied verbatim. The help blocks are generated: scripts/py/check_cli_reference.py compares them with the built binaries and fails when they drift (--write regenerates them), and it also checks that the table of make targets at the end lists exactly what make help prints.

Conventions shared by every tool

  • Exit codes. 0: the command did what it was asked and every check passed. 1: a check failed (an unexpected result, a mismatch, a missing finding). 2: the tool itself could not run (bad arguments, missing input, an integrity mismatch, an adapter or driver that broke its protocol). So 1 means the reader under test failed and 2 means the kit did.
  • Network. Only these commands use the network, and only to fetch pinned, hash-checked inputs: xdrcheck-corpus capture, xdrcheck-corpus refetch, xdrcheck-corpus fetch-goldens and xdrcheck conform fetch (all reached through make fetch or run by hand when adding entries). Everything else runs offline; make <target> OFFLINE=1 runs it inside a network namespace with loopback only (ci-isolation.md).
  • Nothing is filed upstream. No command files, comments on or reports anything to another project. xdrcheck findings issue writes a draft and prints the command a person would run.
  • Pins. --pins FILE (default pins.toml) is the single file of external versions. No tool reads a version from anywhere else, and xdrcheck pins check fails on any version named elsewhere.
  • Reports. --report writes results in the shared format xcc.report/v1 (corpus/schema/report.schema.json), the only format xdrcheck findings check and xdrcheck report read.
  • Public CI never uses it. See SECURITY.md and findings/README.md.

Cookbook: replay anything against anything

Each line below was run from the repository root after make fetch && make build, with export PATH="$PWD/bin:$PATH" (the --set public line as make verify-conformance-public, the run evidence/results/ is made from). After the fetch all run offline, except conform fetch --sdk, which fetches the checkout’s own dependencies. An entry ID glob’s * crosses /; --entries works the same in replay and conform run. --caps is replay’s alone: in conform run, select a CAP’s row with --entries 'cap-0040/*'. --input defaults to the first input the adapter declares, so it is needed only to pick another one. The --sdk copy of a driver is built outside the repository, where a version manager’s per-directory toolchain does not apply: put the pinned Go first on PATH (export PATH="$(go env GOROOT)/bin:$PATH", run in the repository) when your default go is older. --target-version names the indexer version in the report and, for the pipeline adapters, selects the commit to build; the baseline and template adapters run one fixed version and record the name you give.

Commands

xdrcheck-corpus

The global --corpus DIR (default corpus) selects the corpus root.

xdrcheck-corpus --help

xdrcheck-corpus verify --help

xdrcheck-corpus render --help

xdrcheck-corpus extract --help

xdrcheck-corpus normalise --help

xdrcheck-corpus skeleton --help

xdrcheck-corpus gen --help

xdrcheck-corpus gen-lake --help

xdrcheck-corpus chain-index --help

xdrcheck-corpus capture --help

xdrcheck-corpus mine --help

xdrcheck-corpus refetch --help

xdrcheck-corpus fetch-goldens --help

xdrcheck-corpus import-golden --help

xdrcheck-corpus synth --help

xdrcheck-corpus slice --help

xdrcheck-corpus coverage --help

xdrcheck-corpus index --help

xdrcheck-corpus guide-table --help

xdrcheck-corpus guide-claims --help

xdrcheck-corpus mainnet --help

xdrcheck-corpus scan --help

xdrcheck replay

Replay the corpus through an indexer’s adapter, or ledgers through a target or a rig. The full description is on its reference page.

xdrcheck replay --help

xdrcheck serve

Serve corpus ledgers as a SEP-54 layout, an object store, or a mock getLedgers. The full description is on its reference page.

xdrcheck serve --help

xdrcheck conform

Run the corpus through SDK conformance drivers. The full description is on its reference page.

xdrcheck conform --help

xdrcheck conform fetch --help

xdrcheck conform build --help

xdrcheck conform run --help

xdrcheck conform describe --help

xdrcheck conform check --help

xdrcheck conform diff --help

xdrcheck conform readiness --help

xdrcheck xcheck

The same transactions through two or more targets or versions; diff the fields both compute. The full description is on its reference page.

xdrcheck xcheck --help

xdrcheck find

Example transactions for a token, class, value tag, CAP, assumption or operation type. The full description is on its reference page.

xdrcheck find --help

xdrcheck data

The dataset: status, named ledger sets, ledger fetch, manifest, top-up plan. The full description is on its reference page.

xdrcheck data --help

xdrcheck repro

Pack a run’s result into a self-contained bundle, run a bundle, verify its input. The full description is on its reference page.

xdrcheck repro --help

xdrcheck runs

Validate run directories and compare two runs by cluster. The full description is on its reference page.

xdrcheck runs --help

xdrcheck report

Build, redact and diff reports.

xdrcheck report --help

xdrcheck report redact --help

xdrcheck report diff --help

xdrcheck mutate

Structure-aware mutants of corpus values through every reader. The full description is on its reference page.

xdrcheck mutate --help

xdrcheck mutate run --help

xdrcheck mutate replay --help

xdrcheck mutate minimise --help

xdrcheck mutate promote --help

xdrcheck pins

Check that every version used matches pins.toml.

xdrcheck pins --help

xdrcheck xdr

Diff XDR definition sets, watch upstream, generate driver ceilings and candidate rows.

xdrcheck xdr --help

xdrcheck xdr diff --help

xdrcheck xdr ceilings --help

xdrcheck xdr candidates --help

xdrcheck xdr watch --help

xdrlint

The rules: xdrlint rules. xdrlint runs the rules over Go packages and prints findings with rule IDs; it exits 1 when an unsuppressed finding at or above -fail-on exists, and 2 (with a warning) when none of the packages it loaded, nor anything they import, is go-stellar-sdk’s xdr package, since its rules then have nothing to analyse. The same analyzers run as a go vet tool (go vet -vettool=$(which xdrlint) ./...) and inside golangci-lint as a module plugin (make lint-plugin). Each rule has its own page under lint/docs/.

xdrlint -h

xdrcheck-judge

Facts from a ledger’s own entry changes, and verdicts on an indexer’s rows. What it computes: Judge.

xdrcheck-judge --help

xdrcheck-judge facts --help

xdrcheck-judge verdict --help

xdrcheck-tagger

Tag dangerous values in ledger bytes, partition by partition. What it computes: The mainnet scan.

xdrcheck-tagger --help

xdrcheck-tagger run --help

xdrcheck-tagger merge --help