Skip to main content
For authors and operators of software that reads Stellar ledgers into a store: wallet-backend, stellar-etl, Horizon or your own. After this page you have replayed the corpus through an adapter, know how to point the adapter at your indexer, and can run the same replay on every pull request. The replay harness serves corpus ledgers to your unmodified indexer through an input it already reads, waits for it to ingest them, and compares what it stored with each entry’s expected values. Your indexer talks to the harness through a small adapter: a program that speaks JSON lines over stdin and stdout. How that works step by step is on Replay.
1

Build the kit once

On Linux with mise and rustup:
make fetch-replay is the only networked step; everything after it runs offline.
2

See a failing indexer first

The demo replays the fee-bump and muxed-account entries through a small indexer with one planted bug (it skips failed transactions). The report, reports-demo/REPORT.md, shows each entry it got wrong, what the ledger holds against what it stored, and the command that replays that entry alone. Expected output is on Quickstart.
3

Replay the whole corpus through the adapter template

--input is how the ledgers reach the indexer: sep54-dir (the SEP-54 layout in a directory, no Docker), sep54-s3 (the same layout behind an S3 API, needs Docker) or rpc (a mock stellar-rpc getLedgers). The run ends with one line: rows per class, failures and harness faults. The template must pass.
4

Point the adapter at your indexer

Copy the template into your own module and fill in the places marked REPLACE: how to start your indexer on the harness’s ledgers, and how to read back what it stored.
5

Run it on every pull request

The GitHub Action runs the same replay from a pinned corpus release, with an expected-failure list that keeps known failures from failing the build until they are fixed: CI recipes: replay.

Reading a result

Each entry variant comes out in one class: The full list of classes and how each is decided is on Replay, step 4. A run exits 0 when no row fails, 1 when one does, and 2 when the harness itself could not run. Exit 2 usually means a tool was not built (make build) or the adapter’s command line is wrong (--selftest checks it).

Limits

  • The harness, the rigs and xdrcheck replay run on Linux only.
  • A verdict covers only the observation kinds your adapter reports. The template reports receipts and transactions; participants, state changes, movements and addresses are added kind by kind.
  • The corpus holds rare shapes, not traffic volume. For real mainnet ledgers through wallet-backend, stellar-etl or Horizon, use the service rigs: Replay real ledgers.

Next