Skip to main content
xdrcheck conform puts every corpus entry through every pinned SDK version and writes a matrix entry × SDK@version × level. Each cell is judged against the manifest, never against another SDK. The specification is Driver protocol and Conformance protocol.

One cell, from request to check

Step 1: the driver

A driver is a small program in the SDK’s language that wraps exactly one SDK at exactly one version (drivers/<language>/<version>/). It speaks xcc.driver/1: one JSON request per line on stdin, one response per line on stdout. It never sees expected values and never reads the manifest. It reports what the SDK did; the orchestrator judges. A driver therefore cannot pass a cell by agreeing with the expectation. describe answers from the installed package at run time:
  • sdk.version must equal the column’s pin in pins.toml [conformance.columns], or the column is not run and the command exits 2.
  • xdr_schema.probes: what the SDK’s generated XDR can represent, probed from its enums at start-up, for example sc_address_type_muxed_contract (CAP-84) and stellar_value_signed_ms (CAP-88). A variant that requires a feature the SDK lacks is beyond reach: the only accepted outcome is a clean refusal (union_arm_undeclared, enum_undeclared), recorded n_a. A crash is still a failure.
  • object_parsers, native_converters: the entry points per XDR type, for example {"TransactionEnvelope": "TransactionBuilder.fromXdr"}.
Each driver process runs under a per-request timeout (default 20 s plus 20 s per MiB), a memory cap (default 1 GiB) and no network. A driver that dies is recorded crash and replaced. Entries built to stress a reader run in a fresh process each.

Step 2: what one cell checks

Driver outcomes: ok, diverge (accepted, and the driver itself saw a mismatch), reject (refused through the SDK’s normal error channel), crash (fault-class error or dead process), n_a (no API for this level, under narrow rules). Refusal reasons are a closed list of codes (decode_error, trailing_bytes, length_exceeds_max, union_arm_undeclared, ordering, strkey_checksum, stack_overflow, …). The SDK’s error text is kept in reason.message and never used to classify.

Step 3: verdicts and checks

The orchestrator turns each answer into a verdict against the manifest: conform, diverge (accepted with bytes or values that differ), accepts_invalid, reject_valid, crash or n_a. It then checks the verdict against the entry’s declared divergences for the column’s target, version and profile: xdrcheck conform check fails on undeclared, unexpected-conform and known-changed. So a run fails on a new divergence, and also when a declared defect no longer shows where it should (the fix landed in an earlier version than declared, or the corpus stopped reproducing it). A declared divergence (conformance.known_divergences[] in the entry): target (for example stellar/js-stellar-sdk), versions (a range), level, the expected outcome, and optionally a match block (reason, envelopes_parsed, rejected_tx_index) the driver’s report must equal, the upstream reference, and fixed_in. Diverges from the network, diverges from each other. A cell that differs from the manifest diverges from the network: the manifest’s values trace to stellar-core’s bytes. Accepting columns are also grouped by a fingerprint of what they returned (L0 the re-encoding hash; L1 transactions, operations and hashes; L2 the pinpoints; L3 the map entries and re-encoding; L4 the value and bytes). Columns that accept and disagree are listed in cross-sdk.md.

The columns

drivers/sets.toml defines named sets; each column is one SDK at one version (and for Rust one decode profile). The Rust decode profiles. The stellar-xdr crate has no default limits, so its columns run under two: limits-default (the Soroban host’s default XDR limits, DEFAULT_XDR_RW_LIMITS in soroban-env-host, with the length budget set to the input size) and limits-none (Limits::none(), what the crate’s CLI uses). The stellar-core column. core@30.0.0 (drivers/core) runs the pinned stellar-core binary offline as a decoder (stellar-core print-xdr, and dump-xdr on a one-record stream for LedgerCloseMeta). It answers L0 only. It shows how stellar-core decodes bytes, not what core admits to the network. A negative entry that core’s decoder accepts records core_behaviour.accepts: true; the SDK columns must still refuse it. Result: 346 cells agree, 0 diverge, 96 not run (evidence/results/conformance-matrix.json, totals).

The three js-stellar-sdk regressions

make verify-conformance-js (every pull request) runs the js-stellar-sdk defects on js@17.2.0, js@17.2.1 and js@17.3.0, without the rest of the matrix. Each pre-fix cell must be the declared divergence observed inside its range, with the facts the assertion names; each fixed cell must conform. Removing a declared divergence from its entry fails the run. Evidence: evidence/js-1766/, evidence/js-1785/, evidence/js-1789/.

A defect in one SDK becomes a check on the others

Entries are SDK-neutral. When a defect is found in one SDK, its entry runs on every column of every family on the next run. findings/SIBLINGS.md records the result per defect class and family, read from executed cells (34 classes × 9 families: 38 reproduce, 43 not affected, the rest not run or outside the runs). Example, liquidity-pool asset order compared as strkey text instead of bytes: For your SDK this means: a defect someone found in another language is already a cell in your column. If your SDK has it, your next run shows it as a new failure.

Using it in your SDK’s CI

Two ways, both offline after one download:
  1. Your own test, your own language. A loader (packages/go, packages/rust, packages/python, packages/npm) opens one pinned release archive, checks its sha256, and yields each entry’s blob (refused unless its sha256 and length match), its expected SEP-51 JSON, and whether a decoder must refuse it. Recipes: examples/sdk-ci/.
  2. The full matrix. xdrcheck conform run --columns '<your column>'. For an unreleased branch of a Go, Rust or Python SDK, run xdrcheck conform fetch, build and run with --columns <id> --sdk <checkout>.
The expected-failure list. xdrcheck conform run --columns <id> --write-expected-failures FILE records your column’s failing cells, one line per cell (<entry> <variant or -> <level>), committed in your repository. With --expected-failures FILE the run passes only when the failing cells equal the list: a new failure fails (NEW-FAILURE), a listed cell that now passes fails (UNEXPECTED-PASS: remove the line when you fix the bug). --require-all-read fails when your column never read an entry variant (every level n_a). Guides: Run the corpus in your SDK’s CI, Using the corpus in an SDK’s CI.

What a run writes

xdrcheck conform run --report DIR: SUMMARY.md (only rows that need a look: new divergences, known divergences, SDK disagreements, each with the expected value, every column’s answer and a rerun command), matrix.json, matrix.md, cross-sdk.md, report.json, cells.ndjson, describe.json.

Limits

  • The Rust column is the oracle. rust@30.0.0 runs the same crate that writes the corpus sidecars. Its agreement is the oracle agreeing with itself; what it adds is the decode profiles and refusals of negative entries. Pinpoints (hand-written) are the independent check.
  • Rust has no L1. The crate has no transaction object layer; the L1 comparison holds JavaScript and Go only.
  • No floor on judged cells. A column whose every cell is n_a passes conform check. Use --require-all-read to catch it.
  • Java and .NET are not driven. Their rows in findings/SIBLINGS.md come from records, not executed cells.
Related: Driver protocol and rules, SDK matrix.