Skip to main content
For SDK and XDR-library maintainers preparing a release for a new protocol. After this page you can run the next protocol’s shapes through your SDK before the release, track the update as a shrinking expected-failure list, and test the unreleased branch at every conformance level. When a protocol changes the XDR, each SDK regenerates its types and ships a release. XDRCheck turns “the SDK can now decode Protocol N” into a CI check: real bytes for the new shapes, the value each must decode to, and a job that fails until the SDK reads them. Section 1 is a block you can paste into an “SDK Updates for Protocol N Compatibility” issue, with N replaced by the protocol number and OWNER/REPO by this repository on GitHub. Section 2 explains each piece it links to. How new shapes reach the corpus before the mainnet vote is on maintenance.md §5.

1. The block to paste

2. The pieces

The versioned corpus. A release’s major version is the protocol it covers (release.md §8): N.0.0 is stable and holds every entry of the released protocols; N.0.0-rc.K is the advisory -next channel, published before Protocol N is released, with the next protocol’s entries added. Each release has a SHA256SUMS; pin its sha256 next to the version, and the pin helper action/fetch-release.sh checks every byte before anything reads it (release.md §9):
It sets XDRCHECK_RELEASE (the extracted release) and XDRCHECK_CORPUS. Moving from the -rc to the stable release when the protocol ships is one change of the pin. The CI recipe per language (use-in-sdk-ci.md): Each recipe pins the corpus by version and sha256. To test the coming protocol, point the version at the -rc release:
The expected-failure list workflow (use-in-sdk-ci.md §7). Against the -rc corpus, before the SDK has the new XDR, the run lists the Protocol N entries as new failures. That list is the to-do list of the update. Commit it, regenerate the types, and remove lines as entries start to pass; the run fails on a line that now passes, so the list only shrinks with real fixes. When the list holds no Protocol N line, the SDK decodes every shape the corpus has for that protocol.
The GitHub Action, conform mode (github-action.md §3) runs the corpus through the conformance drivers of the SDK releases the corpus release pins, at every level (decoded values, transaction parsing, native conversion, the api operations), from prebuilt tools:
An unreleased branch: xdrcheck conform --sdk (use-in-sdk-ci.md §8). In a checkout of this repository, a Go, Rust or Python column builds from your SDK checkout instead of its pinned release, so the regenerated types can be tested at every level before the release is tagged:
Which released versions are ready. After a run over every pinned SDK version, xdrcheck conform readiness writes a table with one row per SDK version and one column per protocol and per CAP: full, partial n of m, refuses new arms (the version predates the shapes and refuses them cleanly) or not run:

3. When it fails, and limits

  • A -next release is advisory. Its next-protocol entries come from stellar-core’s next-protocol build and can change before the protocol is released; pin the stable N.0.0 once it exists.
  • The recipes judge bytes (level L0). Decoded values, transaction parsing and the api operations need xdrcheck conform (the Action’s conform mode, or --sdk on a checkout).
  • xdrcheck conform --sdk builds Go, Rust and Python checkouts; for a JavaScript checkout use the npm runner with --sdk ., which covers bytes only.
  • No corpus release is published yet. Until one is, run the recipes against a checkout of this repository (make sdk-ci-examples) and read N.0.0-rc.K as the release you will pin.