Skip to main content
For SDK maintainers and indexer teams adding XDRCheck to their own CI. After this page you can pick the job that fits your code, copy it, keep an expected-failure list, and run the same checks offline on a workstation. Every Action mode downloads the prebuilt tools and corpus of one pinned release, checks each file against the release’s SHA256SUMS (and that file against your pin) before running, and writes a job summary with each failure, what the ledger holds, what your reader did and the command that reproduces it.

Expected-failure lists

A list names the entries your reader is known to get wrong, one per line. A run passes only when its failures are exactly the list: a new failure fails it, and so does a listed failure that now passes (remove its line in the same change as the fix). The format for replay is in section 4; for SDKs in SDK CI, section 7.

Before you start

  • No corpus release is published yet. Until one is, uses: OWNER/REPO@v30.0.0 and the pin helper have nothing to download: build from a checkout and use release-base with a local dist/ (make release, make dist-bin).
  • replay and conform need a Linux runner.
  • The kit’s own workflows are described on Architecture: CI; measured run times are on Timings.

GitHub Action

For indexer authors, SDK maintainers and Go teams who use GitHub Actions. One step in your workflow runs XDRCheck against your code from the prebuilt tools and corpus of one pinned release, with nothing to build and nothing of this repository to vendor: The action is action.yml at the repository root; action/run.sh does the work. Below, OWNER/REPO is this repository on GitHub.

1. What it does

  1. Downloads the release’s SHA256SUMS and, when you give sha256sums, checks its sha256 against your pin.
  2. Downloads the tools for the runner’s platform (and, for replay, the corpus archive) from the GitHub release v<corpus-version>, checks each against SHA256SUMS before extracting it, and the extracted corpus against its own SHA256SUMS (release.md §9). A mismatch stops the step before anything runs.
  3. Runs the mode, writes SUMMARY.md beside the tool’s own reports and appends it to the job summary: the result, the expected-failure check, and the failures with what the ledger holds, what your reader did and the command that reproduces each one.
  4. Uploads the report directory as an artifact (xdrcheck-<mode> by default), on failure too.
The step passes when the check passes. replay and conform need a Linux runner (xdrcheck is Linux-only); lint runs on Linux and macOS.

2. Indexer authors: replay

Your adapter is a small program that drives your indexer for the harness; start from the template go/adapters/minimal (or examples/adapter-ts for other languages) and keep it in your repository. Then:
To see it work before writing anything, run the template itself: the release ships it, and the tools’ directory is on PATH during the step, so adapter: minimal replays the template indexer (and adapter: demo the template with a planted bug, which fails with its repro commands in the job summary). The default input is sep54-dir: ledgers as a SEP-54 layout in a plain directory, no Docker and no network. input: sep54-s3 or rpc serve them through an S3-compatible store or a mock getLedgers instead, if that is how your indexer reads.

3. SDK maintainers: conform

conform runs from the action’s own checkout, which holds the driver tree and the corpus of that release; it fetches and builds the column’s driver (xdrcheck conform fetch, build) and runs it. The runner needs the driver’s toolchain (Node for js, Go for go, Rust for rust, Python for python). columns names columns of the driver sets (driver-protocol.md): the pinned SDK releases. The expected-failure list is the file xdrcheck conform run --write-expected-failures writes, with the rules of use-in-sdk-ci.md §7; without one, the corpus’s declared divergences are the baseline (xdrcheck conform check). A JavaScript SDK that wants to test its own build rather than a released version uses the npm package instead (use-in-sdk-ci.md), downloaded with the pin helper (fetch-release.sh --npm, release.md §9).

4. The expected-failure list for replay

An indexer keeps, in its own repository, the entry variants it is known to get wrong; the run then passes only when its failures are exactly that list:
Write the first list from a run and review it before committing it:
require-all-read makes an adapter that declares an envelope too narrow, or a harness that silently plans nothing, fail instead of passing on fewer entries.

5. Go teams: lint

xdrlint loads your packages with the Go toolchain, so the runner needs Go. Its diagnostics link to the rule pages of the same release. lint-args: -fail-on warning fails on warnings too.

6. Inputs and outputs

7. Pinning

uses: OWNER/REPO@v30.0.0 fixes the action and, by default, the release. uses: OWNER/REPO@v30 follows the newest 30.x action (the major tag moves with each release, release.md §9); then set corpus-version, so a new corpus reaches your CI only when you change the pin. For a supply-chain pin, use the action at a full commit SHA and set sha256sums. Moving to the next protocol’s corpus (v31) is always a change of your pin, never a surprise.

8. Testing the action

make action-selftest runs action.yml step by step against the release in dist/ (make release, then make dist-bin) through action/simulate.py, a local stand-in for the runner that executes the composite steps as written (the expressions they use, the runner’s output and summary files, the artifact upload as a copy). Every mode and failure path is a case: a passing and a failing replay, the expected-failure list and each status that fails it, the all-read check, a corrupted asset and a wrong SHA256SUMS pin refused before anything runs, lint’s SARIF output, and, with SELFTEST_CONFORM=1 after make fetch-sdk, a conformance run.

9. When the step fails

The uploaded artifact (xdrcheck-<mode>) holds the full reports, including the adapter’s stderr.

Replay real ledgers in CI

For SDK maintainers who want real mainnet ledgers, not only corpus entries, in their CI. This recipe runs xdrcheck replay --set controls against a branch of an SDK on every push and pull request: the same ledgers each time, from a pinned dataset version, and a failed build when the branch shows a class of failure the released version does not.

What gets pinned

Make the dataset archive once, where the full dataset is:

The job (GitHub Actions, in the SDK’s repository)

This is the Go SDK; for JavaScript set up Node.js, check out js-stellar-sdk, build it (npm ci && npm run build) and use --target js; for Python use --target python with a checkout of py-stellar-base.
runs compare --new-only exits 1 when the branch has a cluster key the released version does not (+ lines), and 0 when the branch only removes some (- lines, a fix). A released SDK already shows candidates on real ledgers, so failing on every candidate (replay --fail-on candidate) is only useful together with a dispositions file (--dispositions FILE, kept in the SDK’s repository) that names the accepted ones. The exported dataset becomes a public release asset. Export only a set whose ledgers you are willing to publish (xdrcheck data export --set NAME). Any cluster in the job’s run directory can be packed into a bundle (xdrcheck repro pack run --cluster KEY, repro.md) that reproduces it on a laptop with one command. Limits: the job needs the network to fetch ledgers from the public lake on a cold cache (the actions/cache step keeps them afterwards). --target takes go, js, python, rust and the service rigs (replay.md); the comparison is by cluster key, so a branch that changes a failure’s details without changing its class is not reported.

Offline and memory

For anyone running the kit’s checks in CI or on a workstation who needs to know that a run used no network and stayed within a memory bound. Two wrappers enforce this. Both were exercised on Debian 13, kernel 6.12, cgroup v2. Add OFFLINE=1 to a make target to run it under the network wrapper.

No network: scripts/offline-run.sh

Runs a command in a private network namespace with only a loopback interface (unshare --user --map-root-user --net). Local servers (stellar-core’s HTTP port, the mock RPC, the object store) keep working on loopback; nothing can reach the internet. Verified: an HTTPS request fails to connect, and a socket binds on 127.0.0.1. A container’s published ports are not on that loopback, so the wrapper sets XDRCHECK_OBJSTORE=binary unless the caller set it: the replay harness’s object store then runs as the pinned SeaweedFS image’s own weed executable (same digest) inside the namespace. Fallback where unprivileged user namespaces are disabled: XDRCHECK_OFFLINE_FALLBACK=docker with a pinned toolbox image runs the command in a container with --network none. Dependencies are fetched beforehand by make fetch, the only networked step.

Memory: scripts/limit-run.sh

Runs a command under a memory limit. The two behave differently on purpose: the memory-bound test runs under the cgroup limit (what a container runtime does), and negative vectors with huge length prefixes are also run under the address-space limit, where an implementation that pre-allocates fails visibly instead of being killed. Reports record which mechanism was used. Limits: the wrappers are verified on the machine above, not yet on hosted CI runners. The network namespace needs unprivileged user namespaces; where they are disabled, use the Docker fallback.