xdrcheck replay feeds corpus ledgers to your indexer through an input it already reads, waits for it to ingest
them, reads back what it stored, and compares that with the entry’s expect. Your indexer is not modified and needs
no test hook. The specification is Replay harness and
Adapter protocol; this page explains the mechanism.
One entry, from ledger server to verdict
Step 1: the ledger server
The server is a view over the corpus blobs. It never re-encodes a ledger.
The S3 proxy and the mock RPC log every request. That log is the delivery evidence: it tells an indexer that
hung on a ledger from a ledger that never reached it. GCS is not served yet; the stellar-etl adapter runs its own GCS
emulator over
sep54-dir.
Units. single serves one ledger at its real sequence (the default). chain serves a whole local-core scenario
from ledger 2 on one passphrase, a real hash chain, for indexers that need earlier state. stream renumbers ledgers
into one consecutive run (header ledgerSeq and matching lastModifiedLedgerSeq rewritten, as go-stellar-sdk’s
ingest/loadtest does); stream bytes are transformed, so stream results are used for load and memory tests only.
Passphrases. One pass per network passphrase, because readers verify transaction hashes against it.
Step 2: the adapter
An adapter is a small program that knows one indexer. It speaksxcc.adapter/1: one JSON request per line on
stdin, one response per line on stdout, stderr captured and never parsed. Five methods per session:
Observation rules that make verdicts trustworthy.
- Every address-bearing value carries
as_stored: the literal bytes or text the indexer keeps, with its encoding (strkey_text,version_byte_payload_hex,xdr_hex,raw_key_hex). The adapter never computes a base account from a muxed one or re-derives a strkey. The harness decodes stored values itself with a strict strkey decoder. - Amounts and 64-bit IDs are decimal strings. A float or fractional value goes literally into
amount_as_stored. - One stored record is one fact. The adapter never merges, splits or fills in records.
- A status never rests on log text.
refusedis accepted only if the gate was declared indescribe, the manifest confirms the entry is outside it, nothing was written for the ledger, and the process did not crash.
Step 3: matching
The matcher compares the observations with the entry’sexpect (docs/manifest.md section 6):
- Exact comparison: amounts, IDs and counts as decimal strings or integers. No tolerance, rounding or prefix match.
- Participants match by base address. A
base_onlyindexer’s muxed ID is not compared; abase_and_aliasindexer must report the expected one. Identity held only in muxed form is a wrong value. - Negative facts (
must_not_include, a movement withcount: 0) are checked only when the transaction itself was observed. A result made of negative facts alone is never a pass. - A fact the indexer’s declared scope excludes (each exclusion citing the indexer’s own source or documentation as
basis) isnot_applicablewith that reason.
matched, missing, wrong or not_applicable.
Step 4: classification
The first matching row decides (docs/replay-harness.md section 7):
--confirm K re-runs a non-pass unit K times; a result that changes is flaky. Every unit gets a fresh session,
a fresh ledger view and its own delivery evidence. The adapter’s process group runs under --memory-max and
--pids-max (a cgroup v2 scope where available).
Step 5: known divergences
An entry may declare that a target diverges in a version range (conformance.known_divergences, level replay).
For a run against target T at version V:
- Inside a declared range, the result must be the declared class and qualifier. A pass there is unexpected: the corpus no longer reproduces the defect.
- Outside every range, the result must be
pass. - For repositories without tags, the adapter resolves commit ranges (
A..Bon B’s first-parent history) inprepare.resolve_ranges.
xdrcheck replay --assert-known runs only the entries with a divergence for T. Exit 0: every result is the expected
one; 1: at least one unexpected result; 2: the harness could not run.
wallet-backend: the reference adapter
go/adapters/walletbackend, pinned in pins.toml [pipelines.wallet_backend].
- Build.
prepareclones wallet-backend, checks out the commit under test and builds it with Go 1.25.9. The binary is cached per commit. - Database. One TimescaleDB server per adapter process, from
timescale/timescaledb:2.28.2-pg17by digest. The container runs with--network none; wallet-backend and the adapter reach it through a Unix socket in a directory the adapter bind-mounts, so the same set-up works inside the offline wrapper. The data directory is a tmpfs. Each session gets a fresh database; TimescaleDB’s telemetry job is switched off. - Input.
sep54-s3(wallet-backend reads S3) orrpc. The ingest cursor is seeded toS − 1. - Observe. SQL against the session’s database, every query returning one JSON value. Rows map to participants, transactions, state changes and stored addresses.
- Envelope.
sdk_limit, from the go-stellar-sdk version in the commit’sgo.mod. Commits beforea9bac8d2decode at most Protocol 29 (pins.toml,max_decodable_protocol_before_a9bac8d2), so their Protocol 30 variants arenot_applicable, not failures.
make verify-replay, both inputs; the pull-request CI runs the rpc input):
Commits:
pins.toml [pipelines.wallet_backend]; results: evidence/results/replay-summary.json, identical on rpc and
sep54-s3. The entries are found from the manifest’s declared divergences, not listed in the script. The script
also asserts row by row: every variant the commit can decode has a scored row; pre-fix rows are exactly the declared
class; fixed and current rows pass; nothing is left behind.
The whole corpus on current wallet-backend (make replay-full, commit f0c00cf5): 319 entries per input, 302
pass, 7 mishandled, 5 dropped, 5 not run, the same on rpc and sep54-s3
(evidence/results/replay-summary.json). Per-entry rows: Replay results.
stellar-etl
go/adapters/stellaretl, v2.8.35 at 7e3fc9af, built with Go 1.27.3 and CGO_ENABLED=1 (stellar-etl links
go-stellar-xdr-json). stellar-etl reads only from a GCS datastore, so the adapter serves the sep54-dir layout
through fake-gcs-server v1.49.2 (the emulator go-stellar-sdk’s datastore tests use) on loopback, and runs every
export: export_ledgers, export_transactions, export_operations, export_effects, export_token_transfer,
export_contract_events, export_trades, export_ledger_entry_changes, export_assets,
export_ledger_transaction. It reads the JSON Lines back as observations. make replay-etl-known runs the entries
that declare a stellar-etl divergence. Details: stellar-etl adapter.
Real ledgers: service rigs and the judge
A corpus entry carries hand-checkedexpect. A real mainnet ledger does not. For those, the expected facts come from
xdrcheck-judge (crates/xdrcheck-judge), which reads the LedgerCloseMeta with rs-stellar-xdr and computes what
every transaction did from the ledger’s own entry changes, without go-stellar-sdk or any indexer’s code:
- balances from accounts, trustlines, claimable balances, liquidity-pool reserves and Stellar Asset Contract
[Balance, address]entries, split into fee, operation and refund parts, all in i128 (overflow isunknown, never a wrap); - a contract counts as a SAC only if its ID equals the asset’s contract ID under the passphrase; a contract that names itself “USDC” does not;
- an update with no prior state in the ledger is
unknown, never assumed zero.
xdrcheck replay --rig wallet-backend|stellar-etl --ledgers A-B --lake DIR --commit SHA runs the real pipeline over
lake-layout ledgers and exports its rows; xdrcheck-judge verdict --facts --rows compares them. Verdicts per
transaction: ok, missing, extra, wrong_value, duplicate, unknown, out_of_scope; per ledger skip and
halt. Each carries a stable class such as balance_change:wrong_value:int64_wrap. The judge’s own test plants one
bug per run in a toy indexer’s rows (dropped row, off-by-one amount, int64 wrap, credit on a failed transaction,
credit from a non-SAC event, skipped ledger, and more) and requires each to be flagged at its place.
Horizon (go/adapters/horizon) builds an unmodified stellar-horizon as a static binary and runs its own
db reingest range with the datastore ledger backend over a lake directory: no captive core, no history archive, no
network. It dumps the history tables and maps them to the judge’s rows. Details: Horizon rig.
How the harness tests itself
Your indexer
- Write an adapter: start from
go/adapters/minimal(Go) orexamples/adapter-ts(TypeScript), or copygo/adapters/baselinefor every observation kind. - Run
xdrcheck replay --corpus corpus --adapter <cmd> --target-version <commit> --report reports/x. - Read
reports/x/REPORT.md: every failing row with the entry, its CAPs, expected against observed, and the command that replays that entry alone.
Limits
- Stream-unit results never count as evidence; a failure seen in a stream must be reproduced as a single or chain.
sep54-dirreads are not logged, so delivery evidence exists only forsep54-s3andrpc.- The wallet-backend rig answers
simulateTransactiononly for a zero-argument contract call recorded in the run’s ledgers; token metadata read by simulation keeps wallet-backend’s defaults otherwise. - Horizon is not pinned in
pins.toml; a Horizon run names its version on the command line.