Skip to main content
For maintainers of a Stellar SDK or XDR library who want the corpus in their own CI. After this page you can choose a loader, copy a recipe, run the corpus through your decoder in your own language, and keep an expected-failure list that fails the build on a regression and on a fix the list does not yet show. The job downloads one pinned release archive (release.md) and checks its sha256; a test in your repository then puts every entry through your decoder with a small corpus loader. No submodule and none of this repository’s tools are needed. The test passes only when your failures are exactly your committed expected-failure list and every variant was read. Below, OWNER/REPO is this repository on GitHub. The loaders are not on a package registry. Pin one by commit of this repository (go get …/packages/go@<commit>, a cargo git dependency with rev, pip install "xdrcheck @ git+https://github.com/OWNER/REPO@<commit>#subdirectory=packages/python"), or vendor it: each is one source file (Go: two) with no dependency beyond a zstd decoder. The npm package.json is marked private, so npm publish is refused.

1. The corpus loaders

Every loader opens the same three things: a release archive xdrcheck-<version>.tar.gz (read in memory, never extracted; an expected sha256 can be given and must match), an extracted release, or a corpus directory holding index.json. It walks the flat entry index corpus/index.json (manifest.md §3.1); an entry of the stress tier is read from the release’s stress/ root (release.md §3). The same concepts in each language: The expected values come only from the corpus: the bytes stellar-core emitted and the oracle’s sidecar, never from another SDK.

2. The recipes: Go, Rust, Python

Each recipe is a test that the SDK keeps in its own repository (for example in xdrcheck/), with the SDK’s expected-failure list beside it and a workflow file. The test, for every entry outside the stress tier and every decodable() variant, at conformance level L0:
  • must_refuse(): conforms when the SDK’s decoder refuses the bytes; accepting them is a failure;
  • otherwise: conforms when the SDK decodes the bytes, consumes every byte, and re-encodes them to the identical bytes; where the SDK has SEP-51 JSON (Rust serde_json, Python to_json()) the decoded value’s JSON must also equal expected_json();
  • a type the SDK does not generate leaves the variant unread; a panic or an exception that is not a decode error is a failure (crash).
The run is compared with expected-failures.txt with the all-read rule on: the test fails on a failure the list does not name, on a listed failure that now conforms (remove its line in the same change as the fix), on a variant never read that the list does not name, and on a listed item the run does not have. Write the list once with XDRCHECK_WRITE_EXPECTED_FAILURES=1, review it, and commit it. Stress entries are left out: they are built to exhaust a reader without limits, and belong in a job that runs under limits. The workflow (each example’s workflow.yml) pins the corpus by version and sha256, downloads the release asset and checks it before anything reads it, then runs the test with XDRCHECK_CORPUS pointing at the archive:
Moving to a new corpus release is one change: both pins, and the list regenerated and reviewed. Go (examples/sdk-ci/go). corpus_test.go maps the corpus’s type names to go-stellar-sdk types, decodes with xdr.SafeUnmarshal (which refuses trailing bytes) and re-encodes with MarshalBinary; go-stellar-sdk has no SEP-51 JSON, so the expected value at L0 is the bytes. In the SDK’s repository its go.mod replaces github.com/stellar/go-stellar-sdk with ../. Against v0.9.0 every variant conforms and the list is empty; the same test against v0.7.1, which predates Protocol 30, prints a NEW-FAILURE for each Protocol 30 ledger (refused valid bytes: decoding LedgerCloseMetaV2: … decoding StellarValueExt …). Rust (examples/sdk-ci/rust). tests/corpus.rs decodes by TypeVariant with Limits::none() (the crate’s own command-line tool decodes so; the stress entries that need limits are not read), checks the re-encoding and compares serde_json::to_value of the decoded value with expected_json(). In the SDK’s repository the stellar-xdr dependency is the crate itself (path = ".."). Against 30.0.0 it lists one failure: xdr-strict/bool-value-2 none L0 (a bool encoded as 2 is accepted). Python (examples/sdk-ci/python). test_corpus.py decodes with stellar_sdk.xdr.<Type>.from_xdr_bytes (type names matched without regard to case: the corpus says ScVal, the SDK SCVal), checks that every byte was consumed with xdrlib3’s Unpacker.done() and re-encodes with to_xdr_bytes. With XDRCHECK_COMPARE_JSON=1 it also compares json.loads(to_json()) with expected_json(), as a separate level json with its own list lines. Its requirements.txt pins the SDK and its dependencies by hash; the workflow installs the SDK checkout itself over them. Against 17.0.1 the bytes list one failure, xdr-strict/bool-value-2 none L0. JavaScript (examples/sdk-ci/js). The workflow builds the SDK from the pull request’s own tree with the SDK’s own commands, installs the npm package of one pinned release (section 4) outside the SDK’s dependencies, checked by sha256, and runs xdrcheck-corpus-run --sdk . --expected-failures xdrcheck/expected-failures.txt --require-all-read against the package built in the step before. Against 17.4.0 the list is empty; the same list against the 16.x line fails with a NEW-FAILURE for each value nested deeper than its decoder allows. Run any of them here against the repository’s corpus, offline once make fetch-sdk has filled the caches: make sdk-ci-examples. make sdk-loaders runs the loaders’ own tests. How the recipes are tested here. make sdk-ci-recipes (examples/sdk-ci/check_recipes.py) lays out, for each language, a scratch SDK repository: the pinned SDK’s own source at its root (go-stellar-sdk from the Go module cache, rs-stellar-xdr from the cargo registry; for Python and JavaScript, whose sources are not in the caches, the pinned wheel and the built package stand for the checkout), the recipe’s files where its workflow says to copy them, and the wiring its comments ask for (replace github.com/stellar/go-stellar-sdk => ../; stellar-xdr = \{ path = ".." \} and cargo update -p stellar-xdr; the SDK installed over the hash-pinned dependencies; --sdk .). It then runs the workflow’s own test step, its run: text read from workflow.yml, with this repository’s corpus in place of the release download, offline. Each recipe must pass as committed and must fail with a NEW-FAILURE once the working tree diverges: the Go tree with its ScVal decoder patched to accept an undeclared value type, the 16.x JavaScript package in place of 17.4.0, and the Rust and Python lists emptied of the SDK’s one real divergence (a bool encoded as 2).

3. npm: what the runner checks

The npm package carries the release archive itself and a runner, xdrcheck-corpus-run, that puts chosen entries through the JavaScript SDK under test. It is built from a release with npm pack and installed from the local tarball. Each selected entry’s bytes go through the SDK’s own generated XDR classes at the byte level (conformance level L0, manifest.md §10): The expected outcome comes from the bytes and the entry only. The reason class is read from the message of js-xdr’s decode error (XdrError in the SDK 17 line; TypeError: XDR Read Error: … in the SDK 16 line); where the message does not say which of two constructs failed (an unknown enum value is an undeclared enum value or an undeclared union arm), either class matches. Baseline: expected divergences. An entry records the readers known to get it wrong (conformance.known_divergences). The runner takes the records whose target is the name of the SDK package under test, whose level is L0 or absent, that name no sandbox profile, and whose versions range holds the SDK’s version. When the SDK shows the outcome such a record predicts (reject of valid bytes, with its match reason if it names one; accepts_invalid; wrong_value for a re-encoding that differs; crash or hang for a stack overflow), the variant is KNOWN: expected, printed with the record’s reference, not a failure. Each variant is one of: Before reading anything the runner checks the archive’s sha256 against the one the package was packed for, and each blob’s sha256 and length against its manifest entry; a mismatch is a tool error. Decoded values, transaction parsing and the api calls (levels L1 to L4) are judged by xdrcheck conform (conformance-protocol.md), which this package does not replace. Exit codes are the kit’s: 0 no selected variant failed, 1 a variant failed (with --expected-failures: the run differs from the list; with --require-all-read: a variant was not read), 2 the runner could not run (bad arguments, no SDK found, a checksum mismatch, a known divergence whose version range does not parse). The last lines of a run account for every variant: entries N: … passed, … known divergences, … fixed, … failed, … unread, … skipped and all read: R of T ledger and xdr variants read.

4. npm: building the package

or, from an existing archive, packages/npm/pack.sh dist/xdrcheck-30.0.0.tar.gz dist. The package version is the corpus version. Its contents: The package has no dependencies and needs Node 24 (the pinned pins.toml [js] node).

5. npm: in the SDK’s CI

Keep the .tgz where the CI can reach it without the network (a vendored file, a cache keyed by its sha256, or a release asset fetched in a separate step) and install it next to the SDK under test:
The same from code: import { openRelease, entries, loadSDK, runEntry } from "xdrcheck".

6. npm: proof that it runs offline

packages/npm/check.sh (run by make release) does what an SDK’s CI does, in an empty directory with the network cut by scripts/offline-run.sh: it installs the pinned @stellar/stellar-sdk (pins.toml [js] stellar_sdk, 17.4.0) from the JavaScript driver’s committed lock file and the npm cache make fetch filled, installs the package from its local tarball, and runs the release’s whole corpus/ root through it. It must pass: every variant conforms or is a declared known divergence of 17.4.0. Its transcript, with the repository path shortened to $REPO and the per-variant lines cut:
packages/npm/check.sh PACKAGE_TGZ 'cap-0073/*' runs a selection the same way. The same runner against an SDK version that an entry records a divergence for prints KNOWN for it, for example the 16.x line refusing a ledger nested beyond its decoding depth:

7. An expected-failure list and the all-read check

An SDK that runs the corpus through xdrcheck conform (any language with a driver, driver-protocol.md) can keep, in its own repository, the list of cells its column is known to get wrong. The run then passes only when the SDK’s failures are exactly that list:
  • a failure the list does not name fails the run (NEW-FAILURE): a regression;
  • a listed cell that now conforms, or is n/a, fails the run too (UNEXPECTED-PASS): a bug was fixed, and its line must be removed in the same change, so the list only ever shrinks with real fixes and never hides a later regression;
  • a listed cell of a selected entry that the run does not have fails it (NOT-RUN): a misspelt or stale line. Lines for entries the run did not select (--entries) are ignored, so one list serves partial runs.
A failure is a cell whose verdict is not conform and not n_a, whether or not the corpus declares it as a known divergence of that SDK: the list is the SDK’s own account of where it stands. The list is per column. Generate it once from a run, review it, and commit it:
--require-all-read guards against an SDK silently skipping entries: an entry variant the column never read, because every level of it was answered n/a or the driver declares none of the levels the entry needs, fails the run (NEW-UNREAD). An SDK that legitimately cannot read some entries (an api operation it has no function for, an ID wider than its integer type) lists them in the same file with the level unread; a listed one that the column now reads fails the run like an unexpected pass. Without the option unread entries are only reported, one line per column on stderr and in SUMMARY.md. The file has one item per line, <entry> <variant or -> <level or unread>, the variant - for an entry without variants; # starts a comment. The generated file comments each line with what the column did and the divergence the corpus declares, when it declares one. A run of go@v0.7.1 on three entry groups writes (lines cut):
and the check against it prints expected failures go@v0.7.1: 8 still as listed, 0 new failures, 0 new unread, 0 unexpected passes, 0 listed but not run. Exit codes with --expected-failures: 0 the run equals the list, 1 it differs, 2 the run could not run. The rules are in conformance-protocol.md §5b.

8. An unreleased SDK branch: xdrcheck conform --sdk

The recipes above judge the bytes (L0). The full conformance matrix (object parsing, decoded values, native conversion, the api operations, every known divergence) runs through xdrcheck conform with a driver (driver-protocol.md), and a maintainer can point a Go, Rust or Python column at a checkout of the SDK instead of its pinned release, to test a branch before tagging it:
The same works for rust@30.0.0:limits-default with an rs-stellar-xdr checkout and python@17.0.1 with a py-stellar-base checkout. The committed driver is never changed: the column is built in a private copy of its driver directory with a cache of its own (drivers/README.md, “Building from an SDK checkout”), describe reports the checkout’s own version (Go: (devel)), and SUMMARY.md names the checkout. Known divergences are still judged against the column’s pinned version, so a bug the branch fixes shows as unexpected-conform, and an expected-failure list shows it as UNEXPECTED-PASS: remove the line in the same change. For the JavaScript SDK, the npm runner’s --sdk . does the same for the bytes (section 5).

9. Limits

  • The recipes and the npm runner judge level L0 only: decode, every byte consumed, identical re-encoding, and (Rust, Python with XDRCHECK_COMPARE_JSON=1) the SEP-51 JSON. Decoded field values, transaction parsing, native conversion and the api operations need xdrcheck conform (section 8).
  • api, strkey and spec entries have no bytes to decode and are skipped by the recipes.
  • The stress tier is not run by the recipes. Run it in a separate job under memory and time limits (--stress in section 5).
  • xdrcheck conform --sdk builds from a checkout for Go, Rust and Python. For JavaScript, the npm runner’s --sdk . covers the bytes only.
  • Known divergences are judged against a column’s pinned version, so a branch that fixes one shows it as UNEXPECTED-PASS until you remove the line.