> ## 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 SDK maintainers

> The short path for an SDK or XDR-library team: copy a recipe, pin a corpus release, commit the list of failures you expect, and every corpus entry goes through your decoder on each pull request.

For maintainers of a Stellar SDK or XDR library in Go, JavaScript, Rust or Python. After this page your CI puts
every corpus entry through your decoder on each pull request, fails on a new divergence, and tells you when a
known one is fixed.

Each corpus entry carries bytes stellar-core emitted (or a marked synthetic value) and the values a correct reader
decodes from them. The expected values come from the bytes and the pinned oracle (rs-stellar-xdr), never from
another SDK. A defect found in one SDK becomes a regression test in yours.

**1. Pick the recipe for your language**

| Language | Recipe | Loader | Test step |
| - | - | - | - |
| Go | `examples/sdk-ci/go` | `packages/go` | `go test` in `xdrcheck/` |
| Rust | `examples/sdk-ci/rust` | `packages/rust` | `cargo test --manifest-path xdrcheck/Cargo.toml` |
| Python | `examples/sdk-ci/python` | `packages/python` | `python -m unittest` in `tests/corpus` |
| JavaScript | `examples/sdk-ci/js` | `packages/npm` | `npx xdrcheck-corpus-run --sdk .` |

The recipes need none of this repository's build. Go, Rust and Python need your SDK's language and a zstd
decoder; JavaScript installs the corpus release's npm runner.

**2. Copy it into your repository**

Copy `workflow.yml` to `.github/workflows/xdrcheck.yml` and the rest of the recipe where the workflow's header
comment says (`xdrcheck/` for Go, Rust and JavaScript; `tests/corpus/` for Python). The workflow downloads one corpus release pinned by version and sha256, and stops before reading anything if the
archive does not match.

**3. Write, review and commit the expected-failure list**

Run the test once with `XDRCHECK_WRITE_EXPECTED_FAILURES=1` (JavaScript: `--write-expected-failures FILE`).
Read each line, then commit the list with the pinned version. From then on the job fails on a failure the list
does not name (`NEW-FAILURE`) and on a listed failure that now passes (`UNEXPECTED-PASS`): remove that line in
the same change as the fix.

**4. Test an unreleased branch**

The recipes judge bytes only (decode, consume every byte, re-encode identically; Rust and Python also compare
the SEP-51 JSON). For decoded values, transaction parsing and the `api` operations, run
`xdrcheck conform run --sdk ../your-sdk-checkout` from a checkout of this repository
([SDK CI, section 8](https://docs.xdrcheck.dev/guides/sdk-ci.md#8-an-unreleased-sdk-branch-xdrcheck-conform-sdk)).

## When the job fails

| Line in the output | Meaning | What to do |
| - | - | - |
| `NEW-FAILURE` | an entry your SDK did not fail before now fails | a regression, or a corpus release with new entries: read the entry (`xdrcheck entry <id>`) and fix the decoder or add the line |
| `UNEXPECTED-PASS` | a listed failure now passes | remove its line in the same change |
| `NEW-UNREAD` | a variant was never read and the list does not name it `unread` | your SDK skipped a type; generate it, or list the variant as `unread` |
| `NOT-RUN` | a listed item the run does not have | a misspelt or stale line: remove it |
| a sha256 mismatch | the downloaded archive is not the pinned one | check the pin against the release's `SHA256SUMS` |

## Limits

* The loaders and the npm runner are not on a package registry. Pin them by commit or vendor them (one file each;
  Go: two).
* The recipes judge conformance level L0 (bytes). The levels above it need `xdrcheck conform` and a driver, which
  exist for Go, JavaScript, Rust and Python only.
* Entries of the `stress` tier are left out of the recipes: they are built to exhaust a reader without limits.

## Next

| To | Read |
| - | - |
| Read one entry field by field | [How to read a corpus entry](https://docs.xdrcheck.dev/start/read-an-entry.md) |
| See how a cell is judged | [Conformance](https://docs.xdrcheck.dev/architecture/conformance.md) |
| Set up the recipes, loaders and npm runner in full | [SDK CI](https://docs.xdrcheck.dev/guides/sdk-ci.md) |
| Use the GitHub Action instead | [CI recipes: conform](https://docs.xdrcheck.dev/guides/ci.md#3-sdk-maintainers-conform) |
| Prepare for the next protocol | [Protocol upgrade (SDK)](https://docs.xdrcheck.dev/guides/protocol-upgrade-sdk.md) |
| Look up a CAP's shapes | [CAP coverage](https://docs.xdrcheck.dev/caps/overview.md) |
| Write a driver | [Driver protocol and rules](https://docs.xdrcheck.dev/reference/driver-protocol.md) |
| See where each pinned SDK release stands | [SDK conformance matrix](https://docs.xdrcheck.dev/results/sdk-matrix.md) |


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