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 archivexdrcheck-<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 inxdrcheck/), 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, Pythonto_json()) the decoded value’s JSON must also equalexpected_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).
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:
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
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 throughxdrcheck 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.
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):
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:
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 theapioperations needxdrcheck conform(section 8). api,strkeyandspecentries have no bytes to decode and are skipped by the recipes.- The
stresstier is not run by the recipes. Run it in a separate job under memory and time limits (--stressin section 5). xdrcheck conform --sdkbuilds 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-PASSuntil you remove the line.