> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xdrcheck.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# For indexer authors and operators

> The short path for an indexer team: build the kit, replay the corpus through the adapter template, read the report, then point the adapter at your own indexer and run it in CI.

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](https://docs.xdrcheck.dev/architecture/replay.md).

**1. Build the kit once**

On Linux with [mise](https://mise.jdx.dev) and [rustup](https://rustup.rs):

```sh theme={null}
mise install
make toolchain && make fetch-replay && make build
export PATH="$PWD/bin:$PATH"
```

`make fetch-replay` is the only networked step; everything after it runs offline.

**2. See a failing indexer first**

```sh theme={null}
make demo
```

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](https://docs.xdrcheck.dev/quickstart.md).

**3. Replay the whole corpus through the adapter template**

```sh theme={null}
xdrcheck replay --adapter bin/minimal --target-version 0.1.0 --input sep54-dir --report reports/minimal
```

`--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.

* Go: [Go indexer](https://docs.xdrcheck.dev/guides/go-indexer.md) (`go/adapters/minimal`).
* Any other language: [Indexer in any language](https://docs.xdrcheck.dev/guides/any-language-indexer.md) (`examples/adapter-ts`).
* The messages in full: [Adapter protocol](https://docs.xdrcheck.dev/reference/adapter-protocol.md).
* Every observation kind in one adapter: [Baseline adapter](https://docs.xdrcheck.dev/reference/replay-harness.md#baseline-adapter). The
  wallet-backend adapter is `go/adapters/walletbackend`.

**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](https://docs.xdrcheck.dev/guides/ci.md#2-indexer-authors-replay).

## Reading a result

Each entry variant comes out in one class:

| Class | Your indexer |
| - | - |
| `pass` | stored every expected fact |
| `mishandled · crash`, `hang`, `halt`, `wrong_value` | crashed, timed out, stopped at the ledger, or stored a wrong or forbidden value |
| `dropped · silent`, `partial`, `refused` | went past the ledger holding nothing for it, missed a fact, or refused it at a gate it declared |
| `not_applicable`, `not_reached` | was not asked: outside the envelope its adapter declared, or stopped at an earlier ledger |
| `harness_fault` | nothing: the adapter or the harness failed, and the row says which |

The full list of classes and how each is decided is on [Replay, step 4](https://docs.xdrcheck.dev/architecture/replay.md#step-4-classification).
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](https://docs.xdrcheck.dev/reference/replay-target.md).

## Next

| To | Read |
| - | - |
| See what the harness serves and how it judges | [Replay](https://docs.xdrcheck.dev/architecture/replay.md) |
| Write the adapter | [Go indexer](https://docs.xdrcheck.dev/guides/go-indexer.md), [Indexer in any language](https://docs.xdrcheck.dev/guides/any-language-indexer.md) |
| Run it in CI | [CI recipes](https://docs.xdrcheck.dev/guides/ci.md#2-indexer-authors-replay) |
| Replay chosen mainnet ledgers through a pipeline | [Replay real ledgers](https://docs.xdrcheck.dev/reference/replay-target.md) |
| Check Go ingestion code | [Lint Go code](https://docs.xdrcheck.dev/guides/lint-go.md) |
| Harden the reader by design | [Hardening guide](https://docs.xdrcheck.dev/hardening/overview.md) |
| See what the pinned pipelines get wrong | [Replay results](https://docs.xdrcheck.dev/results/replay.md) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.