Skip to main content
For an SDK maintainer or an indexer author trying the kit for the first time. After this page you have read a corpus entry from a fresh clone, watched the replay harness catch a planted indexer bug, and know where each tool lives. Part 1 needs a clone and Python 3. Part 2 fetches pinned dependencies once and builds the tools; after that every step runs offline.

Part 1: read the corpus (offline, no build)

The corpus is plain files: corpus/index.json lists every entry, and each entry points at its XDR bytes and its expected decoded value. The Python loader in packages/python uses only the standard library (and the zstd command or the zstandard module for the decoded sidecars).
1

Open the corpus

From the root of a clone:
v.blob() checks the bytes against the sha256 and length in the index; v.expected_json() returns the SEP-51 JSON value a correct decoder must produce.
2

Find the entries of a CAP

Each entry names its CAPs. CAP coverage lists them all, with the pattern, protocol, origin and source ledger of each. How to read a corpus entry walks one entry field by field.

Part 2: fetch once, build, run (Linux)

You need mise and rustup.
1

Toolchains, the one networked step, and the build

The first fetch and build take a few minutes. Every later step runs offline; add OFFLINE=1 to a make target to enforce it.
2

Run the demo

It replays the fee-bump (CAP-15) and muxed-account (CAP-27) entries through a small indexer whose planted bug skips failed transactions. Output of the replay step on this commit (one row per entry variant, then the first failure in full; binary paths shortened):
make demo exits 0 when the replay finds the planted bug. The bug is the block marked SEEDED BUG in go/adapters/demo/main.go; remove it and the same replay passes.
3

Compute the judge's facts for a corpus ledger

The judge reads a ledger with rs-stellar-xdr and states, from the ledger’s own entry changes, what each transaction did. For the signed-payload entry above:
make build builds the judge and the tagger into target/release/ with the rest of the Rust workspace, but does not link them into ./bin.
4

Show an entry

Prints the entry’s CAPs, protocol, validity, why readers get it wrong, its variants with their blobs, and the expected values every reader must agree with. --decoded testnet prints that variant’s SEP-51 JSON; xdrcheck entry --cap 40 lists the entries of a CAP.
5

Find captured ledgers of a CAP

Without a dataset, find --cap answers from the corpus alone. With the mainnet dataset installed (Mainnet scan), the same command and --token, --class and --tag answer from every transaction of mainnet history.

Requirements

Every version the kit builds against or tests is pinned in pins.toml.

If it does not work

A tool is missing or at another version than pins.toml. Run mise install again from the repository root, and check that rustup is on your PATH.
The replay exited with something other than 1. Read reports-demo/replay.log. Exit code 2 means the harness itself could not run, for example because a tool was not built: run make build again.
The replay harness, the rigs and the conformance runner are Linux-only. On macOS you can read the corpus, lint Go code (Lint Go code) and use the corpus in an SDK’s CI (SDK CI).

Next steps