Skip to main content
For SDK maintainers who write or debug a driver, or read a conformance cell: the messages between xdrcheck conform and a driver, a small program that wraps exactly one SDK at exactly one version. After this page you can implement describe and run, choose the right outcome and reason, and know how the orchestrator turns an answer into a verdict. Three companions complete the protocol:

1. Roles

The driver reports what the SDK did; it never sees expected values and never reads the manifest. The orchestrator sends each request, judges the answer against the manifest and the entry’s known divergences, and writes the matrix. A driver therefore cannot pass a cell by agreeing with the expectation, and a missing fact is never read as agreement.

2. Transport

3. Messages

3.1 describe

Always first. The answer states what the driver can do, read from the installed package at run time:

3.2 run

One cell: one entry, one variant, one level, optionally one decode profile.
Inputs, by input.kind: The response echoes id, entry, level (and variant, profile when present) and gives an outcome, a typed reason unless the outcome is ok, and actual: what the SDK produced. The same ledger on js-stellar-sdk 17.2.0, which ordered pool asset issuers by strkey text (js-stellar-sdk#1766), and on 17.2.1, which fixed it:
(Hash lists shortened here; the full messages are valid-03.json, valid-04.json and valid-07.json in the examples folder.)

3.3 shutdown

{"xcc":"xcc.driver/1","id":N,"op":"shutdown"}; the driver answers {"ok": true} and exits.

3.4 protocol_error

A driver that cannot understand a request (a missing or unknown argument, bad hex, an unknown type name) answers with a protocol_error message for that request and keeps serving. It is never an SDK outcome. Conversely, a driver answer that breaks the protocol — not JSON, an unknown field, a wrong echo, an accepted cell without the evidence its level requires — is not trusted: the cell is not judged, the process is replaced and the command exits 2.

4. Levels

Which levels apply to which entry kind is in manifest.md §10.

5. Outcomes and reasons

Reasons are a closed list of codes in the schema, in groups: re-encoding mismatches (reencode_mismatch, object_reencode_mismatch, own_output_rejected, native_reencode_mismatch); decode refusals (decode_error, union_arm_undeclared, enum_undeclared, bool_range, optional_flag_range, nonzero_padding, trailing_bytes, length_exceeds_max, length_exceeds_input, depth); object and value refusals (object_validation, value_out_of_range, ordering, lossy_conversion_refused, unsupported_address_type); strkey refusals (strkey_checksum, strkey_length, strkey_version, strkey_padding, strkey_noncanonical, strkey_payload); faults (stack_overflow, out_of_memory, panic, internal_error); not-applicable reasons (type_not_generated, no_object_layer, no_native_layer, op_not_supported, value_not_representable, argument_type_not_accepted, schema_too_old); and other. The SDK’s own error text goes in reason.message and is never used for classification.

6. From outcomes to the matrix

The orchestrator turns each answer into a verdict against the manifest — conform, diverge (accepted, with bytes or values that differ from the manifest’s), accepts_invalid, reject_valid, crash or n_a — and a check against the entry’s known divergences for the column’s target, version and profile: inside a declared range the declared outcome is known, conform is unexpected-conform, anything else known-changed; outside every range conform stays conform and anything else is undeclared. xdrcheck conform check fails on undeclared, unexpected-conform and known-changed. A cell that differs from the manifest diverges from the network (the manifest’s expected values trace to core-emitted bytes); accepting columns whose results differ diverge from each other, which cross-sdk.md lists. The exact rules are in conformance-protocol.md §4–§5. Read a run from SUMMARY.md: only the rows where a column is wrong or the SDKs disagree, each with the expected value, every column’s answer and a repro command (conformance-protocol.md §5a). A cell answered n_a is not a read. A column whose every cell of an entry variant is n_a (or whose describe declares none of the levels the entry needs) never read that entry; xdrcheck conform run --require-all-read fails on it (conformance-protocol.md §5b), so a driver answers n_a only under the narrow rules of conformance-protocol.md §1. xdrcheck conform sdk-regression asserts three known js-stellar-sdk defects: on js@17.2.0, js@17.2.1 and js@17.3.0 each pre-fix cell of js-stellar-sdk#1766, #1785 and #1789 must be the declared divergence and each fixed cell must conform.

7. Writing a driver

  1. Create drivers/<language>/<version>/ with lock files that pin the SDK version listed in pins.toml [conformance.columns], and a Makefile with fetch, build, test and clean (drivers/README.md).
  2. Answer describe from the installed package: version, integrity, probes. Never hard-code the SDK version.
  3. Implement L0 first: decode by type name with the SDK’s strict entry point, re-encode, report reencoded_sha256 and consumed_bytes. Report lenient entry points that behave differently under lenient_entry_points.
  4. Add L1, L3 and the api operations the SDK can express, reporting exactly the facts conformance-protocol.md §3 requires.
  5. Optionally let the driver build from an SDK checkout, so the SDK’s maintainers can run xdrcheck conform --sdk PATH against an unreleased branch: the Makefile reads XDRCHECK_SDK_SOURCE, points the build at that directory, and leaves bin/xdrcheck-sdk-source naming it (drivers/README.md, “Building from an SDK checkout”). describe then reports the version the checkout declares.
  6. Add the column to its family’s file in drivers/sets.d/ (and to a set in drivers/sets.toml, or with [extend] in the same file), run xdrcheck conform build --columns '<sdk>@<version>' and xdrcheck conform run --columns '<sdk>@<version>' --report <dir>. Every divergence the run shows is declared on its entry before the column joins a public set; a defect not yet reported upstream goes through the private process in SECURITY.md first.
drivers/stub/ is a driver with canned answers and no SDK, used by the orchestrator’s own tests.

Conformance rules

For driver authors and for SDK maintainers who need to know exactly why a cell was judged as it was. This page is the normative part of the driver protocol xcc.driver/1 that a JSON schema cannot express: the names of the api operations’ arguments and results, the facts an accepted cell must carry, and how the orchestrator judges them. The message shapes are in corpus/schema/driver-protocol.schema.json; how drivers are installed and run is in drivers/README.md; the manifest fields the orchestrator compares against are in manifest.md. The messages, levels and outcomes are introduced in driver-protocol.md. A driver answer that is valid against the schema but breaks a rule on this page is a protocol error: the answer is not trusted, the cell is not judged, the driver process is replaced and xdrcheck conform run exits 2. A missing fact is never read as agreement.

1. Outcomes and n_a

  • An api operation the driver lists in describe.api_ops never answers n_a/op_not_supported. An operation it does not list answers exactly that.
  • A declared operation may answer n_a only with value_not_representable, argument_type_not_accepted or type_not_generated:
    • value_not_representable: an argument carries a native-type tag ({"native": …}) whose value the language type the tag maps to cannot hold (an integer wider than the widest integer the SDK’s parameter takes). An answer with this reason when no argument is tagged is a protocol error. The JavaScript drivers never use it for number: building the JavaScript number literal, already rounded, is the behaviour under test.
    • argument_type_not_accepted: an argument carries a native-type tag whose kind (number, string, bigint) the SDK parameter it is passed to does not take at all. The rule is precise:
      1. It applies only in a dynamically typed language, where the tag kind is the runtime type the driver passes (JavaScript: number, string, bigint; Python: int for number and bigint, float for a number with a fraction, str for string).
      2. “Does not take” is read from the SDK’s own published declaration of that parameter, in the installed package, before the call: the TypeScript declaration file for JavaScript (id: string takes only a string; offerId?: number | string takes a number or a string but not a bigint), the type annotation for Python (offer_id: int takes no string). The driver names the declaration it read.
      3. It is never decided from the SDK’s reaction to a value. If the declaration admits the tag’s kind, the value is passed and whatever the SDK does (accept, refuse, encode another value) is the outcome, judged as usual; an invalid value of an accepted kind ("0x10" to a string parameter) is never n_a.
      4. Statically typed drivers (Go, Java, Rust), whose parameter is one integer type, build that integer from the tag’s decimal text whatever its kind, as an application converts its input; they never use this reason (a value outside the type is value_not_representable).
      5. An answer with this reason when no argument is tagged is a protocol error.
      An entry chooses the tag its intent needs (the JavaScript number that is rounded before the SDK sees it, the decimal string a JavaScript muxed-account ID must be); columns whose SDK cannot take that kind are n_a, not failures.
    • type_not_generated: this SDK version lacks the function or generated type for a sub-case of the operation (for example no encoder for one strkey type: strkey.encode with a type whose version byte the SDK’s strkey package does not know is n_a/type_not_generated, never a refusal of the payload).
  • A strkey text (input kind strkey) is answered like strkey.decode: a driver that declares that op may answer it n_a only with type_not_generated.
  • A missing argument, an argument name not in the table below, or a malformed argument (wrong JSON type, bad hex, an unknown type or xdr_type value, an asset not spelled native or CODE:ISSUER) is answered with a protocol_error message for that request; the driver keeps serving. There are no aliases.

2. api vocabulary

Conventions:
  • Bytes: {"hex": "…"} in lower case, or a plain string under an argument name ending in _hex; {"native": "bytes", "hex": "…"} is the same.
  • Numbers and IDs in arguments: {"native": "number" | "string" | "bigint", "value": "<decimal>"}; a bare string is a native string. The tag says how an application would pass the value; an SDK parameter whose declaration does not take the tag’s kind answers n_a/argument_type_not_accepted (section 1).
  • IDs in results: decimal strings. Assets: native or CODE:ISSUER. Hashes and pool IDs: lower-case hex.
  • self_decode (accepted, rejected, not_checked) is required whenever the result has xdr_hex or a strkey: the SDK’s own decoder run on what the SDK produced. When it is rejected the outcome is diverge/own_output_rejected.
A strkey entry (input kind strkey) is answered like strkey.decode: value is the payload hex. xdr.custom_union_encode exercises an XDR library’s schema-definition path rather than a Stellar type: the driver defines a union named U over switch_on with one case per element of cases (case names c0, c1, …; a non-void arm is a field named value), encodes {discriminant, value} with it, and decodes the result with the same schema. A refusal while defining the schema or encoding is reject; an encoding its own decoder refuses is diverge/own_output_rejected with xdr_hex and self_decode: rejected; otherwise ok.

2a. The spec and json levels

spec. A spec entry’s request has input.kind: "spec", the container (wasm or xdr-stream), the blob’s path and, for a Wasm module, sections: where the corpus’s own section reader found each contractspecv0 payload (offset, length). A driver whose SDK has a Wasm reader (Spec.fromWasm in JavaScript, ContractSpec.from_wasm in Python, soroban_spec::read::from_wasm in Rust) ignores sections and gives the SDK the module. A driver whose SDK decodes entry streams but reads no Wasm (go-stellar-sdk) decodes the one listed section, and answers n_a/no_object_layer when there is none or several: which section to read is then the application’s choice, not the SDK’s. An accepted cell reports actual.spec.entries, each entry rendered from the SDK’s own objects as {kind, name, args[{name, type}], outputs} in the vocabulary of manifest.md §9.4; the engine compares them, in order, with expect.spec.entries. A Wasm with no spec section conforms both when the reader returns no entries and when it reports the absence as an error. More than one section, or a stream that does not end in whole entries, must be refused (spec_sections, trailing_bytes, length_exceeds_input, length_exceeds_max). The cross-SDK comparison fingerprints the entry list. json. Columns whose sets.toml entry lists levels = ["json"] are XDR-JSON converters. They get a json cell for every ledger and xdr variant (and no other level); no other column gets json cells. The request is the xdr input of L0. An accepted cell reports actual.json: json_sha256, the sha256 of the converter’s JSON in canonical form (object keys sorted by code point, no whitespace, strings escaping only ", \ and control characters as \u00XX, every other character as UTF-8, numbers as the converter wrote them); schema (valid, invalid with up to five schema_errors, or not_checked when the binding publishes no schema); roundtrip (identical, changed with roundtrip_sha256, refused with roundtrip_error, or not_supported when the binding has no JSON to XDR). The request carries the variant’s expected-value pointers as pinpoints, as at L2, and the converter returns its own JSON at each of them (actual.json.pinpoints); the orchestrator compares each with the manifest’s expect.values exactly as JSON, so a 64-bit integer written as a JSON number where SEP-51 and the manifest state a string is a wrong value (a mismatch makes the cell diverge). The ways a converter can be wrong are verdicts and lists in cross-sdk.md: schema_invalid (its JSON breaks its own schema), roundtrip_changed (its JSON comes back to other bytes), roundtrip_refused (it refuses the JSON it wrote) and cross-binding-different (accepting converters whose canonical JSON differs: a cross-SDK split of the json level). A known divergence of outcome wrong_value at level json matches schema_invalid and roundtrip_changed, one of outcome reject matches roundtrip_refused (and a refusal of the bytes), and the list cites its reference instead of marking the cell new.

The JavaScript SDK’s own XDR-JSON

Planned: this section is written with the change that builds it.

3. Evidence an accepted cell carries

An L1 reject on a ledger whose envelopes were reached carries object.transactions, envelopes_parsed, tx_hashes and a non-empty envelopes_rejected, with envelopes_parsed + rejected = transactions. A ledger that does not decode at all (an undeclared union arm, a depth or length refusal) is refused with that reason and no object.

Canonical L1 keys

Ledger inputs: Other inputs: tx_hash (envelopes), operation_types, operations, reencoded_sha256 (when the SDK object re-serialises; compared with the blob’s hash), derived. operation_types and derived.operation_type are XDR-JSON operation arms in snake case (change_trust, path_payment_strict_receive, invoke_host_function). derived keys are a closed list; every value is a string. A key outside the list is a protocol error. Each key is compared only with variants[].derived.l1.<key>, and a key the manifest states there must be reported. The ledger’s focus reports memo_type whenever the request names a focus transaction, and the operation keys when it also names an operation (focus.op_index).

The rebuild fact

Parsing a transaction and re-encoding the stored envelope cannot show a field the SDK’s object loses: most SDKs keep the envelope they parsed and write it back unchanged. The defect appears when an application rebuilds the transaction from the object (to change the fee, re-sign it, or after simulation), and the rebuilt transaction is another one: a dropped SorobanTransactionData, a lost minSeqNum, an ID that comes back different. The rebuild fact makes that check on every focus transaction of a ledger and on every TransactionEnvelope parsed under a passphrase. A driver whose SDK can rebuild a parsed transaction declares the entry point in describe.object_rebuild, and then reports rebuild in object.focus (ledgers) and in object (envelopes): the parsed transaction handed to the SDK’s builder, built, and hashed under the request’s passphrase. not_rebuilt is decided before the call, from the builder’s published declaration, never from the SDK’s reaction (as argument_type_not_accepted in section 1). The fact covers transactions, not a fee bump’s outer envelope. A builder that takes a fee per operation cannot express an inclusion fee (the fee less the Soroban resource fee) that is not a whole multiple of the operation count. A builder whose declaration requires time bounds cannot express a transaction without them. soroban_memo and soroban_muxed_source apply only to an SDK version whose build() declaration says it refuses them. The orchestrator judges the fact against the manifest only: a rebuilt hash must equal the network’s transaction hash (variants[].derived.tx_hash, or the focus’s tx_hash), and a refused diverges. not_rebuilt is not judged. A driver that declares object_rebuild and leaves the fact out of an accepted cell, or a driver that reports it without declaring it, is a protocol error. Every accepted rebuilt transaction must hash to the network’s transaction.

The native error fact

An ScError is a pair, the ScErrorType (which host subsystem failed: storage, budget, auth, …) and the ScErrorCode (exceeded_limit, missing_value, …), or a contract’s own u32 code. stellar-core writes such values into the diagnostic events of every failed Soroban transaction, where Error(Storage, ExceededLimit) (a footprint too small) and Error(Budget, ExceededLimit) (declared resources too low) share the code and differ only in the type. A native conversion that keeps only the code makes them the same value. At L3 a driver reports, for an scvError input, native.error: type and code as the XDR-JSON names the SDK’s native value carries (type contract with code the decimal contract code for a contract error), each left out when the native value does not carry it. The driver reads the native value only, never the XDR it came from: An entry states the expectation as expect.native.error ({"type": "storage", "code": "exceeded_limit"}); a native value that lacks the type or the code, or names another, diverges. The fact is left out of the cross-SDK fingerprint (section 4).

4. How the orchestrator judges

  • Values. An accepted value is compared with the manifest only. Integers are compared by value only where the manifest states an integer (a JSON integer, or a decimal string in canonical form): the driver’s value may then be a JSON integer or a canonical decimal string, never a string with leading zeros or a sign. Hex is compared without regard to case.
  • Exact or refuse. An api entry with expect_reject and expect_value or expect_xdr_hex conforms on a refusal, or on an acceptance whose result equals the expected one exactly; any other acceptance diverges.
  • Schema reach. A variant lists the XDR features its bytes need (requires, for example stellar_value_signed_ms); it is beyond a column’s reach only if the column’s describe reports the probe of a required feature as false (a feature name is its probe name). A variant without requires falls back to its protocol against the column’s xdr_schema.protocol; a column that reports no protocol has nothing beyond reach by protocol. Beyond reach the only expected outcome is a refusal at L0 (or at a higher level when L0 of the same column was refused; the only level of an api or strkey entry) for union_arm_undeclared or enum_undeclared, or strkey_version for a strkey text (the Rust stellar-xdr column reports such refusals as decode_error, which is accepted for it). That refusal is n_a; a crash or a refusal for another reason is a failure; an acceptance is judged as usual. Known divergences are not evaluated beyond reach, and a negative entry beyond reach is n_a.
  • stellar-core’s own reading. A negative entry whose core_behaviour.accepts is true records that stellar-core’s decoder accepts the input. The SDK columns must still refuse it, but on the stellar-core column (kind core) acceptance is the expected outcome: an acceptance that reads the whole input conforms.
  • Level cascade. When a column’s L0 cell for a variant is a known divergence, or a refusal beyond reach, its L1 and L2 cells for that variant are n_a (shown as n/a (L0)).
  • Known divergences match on the outcome class and on their declared detail: a known divergence of an L1 refusal on a ledger whose variant names a focus transaction is observed only if that transaction is among the rejected envelopes; a divergence’s match block (reason, envelopes_parsed, rejected_tx_index), when it has one, must equal the driver’s report. Otherwise the cell is known-changed.
  • Version ranges that do not parse stop the run (exit 2) and name the entry.
  • Decode profiles. A column with a profile runs every cell under limits the driver sets, not the SDK. The Rust stellar-xdr columns, whose library has no default limits, use two: limits-default is Limits { depth: <the host default>, len: <input length> }, the Soroban host’s default XDR depth (DEFAULT_XDR_RW_LIMITS in soroban-env-host/src/budget/limits.rs) with the length budget set to the input size; limits-none is Limits::none(), what the crate’s CLI uses.
  • Profiles. A known divergence’s profile is either a column’s decode profile (Rust limits-default, limits-none), asserted only on columns of that profile, or an address-space sandbox written address-space cap RLIMIT_AS <n> MiB|GiB. A memory-stress vector’s outcome under the default limits alone can depend on how much of a huge allocation the runtime happens to touch, so it is never judged there: every column of that divergence’s target runs the entry in a fresh process under that RLIMIT_AS cap (versions outside the divergence’s range too, which must then refuse cleanly), the divergence is asserted there, and the cell records the sandbox it ran under (sandbox in the matrix). Columns of other targets run the entry under the run’s limits. A divergence that shows only under one decode profile writes it before the cap, <decode profile> under address-space cap RLIMIT_AS <n> MiB|GiB (for example limits-none under address-space cap RLIMIT_AS 1 GiB): every column of the target still runs the entry under the cap, and the divergence is asserted on that decode profile’s columns only; the target’s other columns must refuse cleanly.
  • Not exercised. The matrix lists every known divergence the run did not assert: no selected column inside its range, or every cell inside it n_a.
  • Cross-SDK comparison. Accepting columns are grouped by a fingerprint of canonical JSON: L0 the re-encoding hash; L1 {transactions, operations, tx_hashes, focus.tx_hash, focus.derived} for a ledger and {tx_hash, operations, derived} otherwise, derived reduced to the keys the manifest states; L2 the pinpoints sorted by path; L3 {map_entries, bytes_preserved, reencoded_sha256}; L4 {value, xdr_hex}. A column without an object layer (n_a/no_object_layer) is not compared; an acceptance without a comparable value (stellar-core at L0) agrees with a single valued acceptance.
  • Left out of the cross-SDK comparison. Only the fingerprint keys above are compared between columns. These facts a driver reports are not, so two columns that differ only in them are listed as agreeing (fingerprint in go/internal/conform/verdict/matrix.go): L0 consumed_bytes, reencoded_hex and lenient_entry_points; L1 operation_types, focus.operation_types, events, reencoded_sha256, envelopes_parsed, envelopes_rejected and rebuild (the rebuild fact, which not every SDK can report), and every derived key the manifest does not state for the variant; L3 native.type, native.summary and native.error; L4 self_decode. Each column is still judged against the manifest on every fact the manifest states (L0 consumed_bytes against the blob’s length, for one).

4a. What the required columns do not show

The required set (drivers/sets.toml: js@17.4.0, go@v0.9.0, rust@30.0.0:limits-default, rust@30.0.0:limits-none) has three limits a reader of the matrix should know:
  • The Rust column is the oracle. The rust@30.0.0 columns run the stellar-xdr crate at 30.0.0, the same crate and version that writes and checks the corpus’s sidecars, pinpoints and round trips (pins.toml [rust] stellar_xdr). Their agreement with the manifest is the oracle agreeing with itself, not independent evidence; what they add is the decode profiles (section 4) and the refusals of negative entries.
  • Rust has no L1. The crate has no transaction object layer, so every L1 cell of the Rust columns is n_a/no_object_layer (one per variant the run selects, on both profiles), and the L1 cross-SDK comparison holds the JavaScript and Go columns only.
  • No floor on judged cells. Nothing requires a minimum number of judged cells per required column or level: a column whose cells are all n_a (out of reach, blocked by L0, no object layer) passes xdrcheck conform check without having judged anything. How many cells each column judged is read from matrix.json (cells, each with its column and verdict); no report states it per column. xdrcheck conform sdk-regression fails only on its own rows whose cell was not judged. A floor is not added here: it needs a count per column and level the matrix does not compute yet.

5. Checking a run: undeclared and pending divergences

xdrcheck conform check <matrix.json> fails on every cell whose check is undeclared, unexpected-conform or known-changed. An undeclared cell is a divergence no entry declares: a regression, a new defect, or a defect that is known but not yet reported upstream. An item for which the run has the cell but the cell is no longer undeclared is stale and fails the check, so the list cannot outlive what it acknowledges. The summary line counts the pending cells of each kind. In --mode acceptance pending cells fail like any other undeclared cell: in that mode every divergence must be declared on its entry. xdrcheck conform sdk-regression asserts three known js-stellar-sdk defects (js-stellar-sdk#1766, #1785, #1789) on js@17.2.0, js@17.2.1 and js@17.3.0: each pre-fix cell must be a known divergence observed inside its declared range, with the facts the assertion names, and each fixed cell must conform. Removing a declared divergence from its entry fails the assertion.

5a. What a run writes, and what to read first

xdrcheck conform run --report DIR writes SUMMARY.md next to matrix.json, matrix.md, cross-sdk.md, report.json, cells.ndjson and describe.json, and prints the same summary on stderr before the per-cell lines (stdout). The summary lists only the rows (entry, variant, level) that need a look, in this order: Each row gives the entry’s CAPs, the expected value in words, read from the manifest entry and its variant only (the blob’s length and hash at L0, the ledger’s counts and hashes at L1, the pinpoints at L2, the native facts at L3, the api expectation at L4, a refusal with its reason for a negative entry; matrix.json expectations, keyed "<entry> <variant> <level>"), each wrong column’s answer with the first difference the engine found, its known divergence and finding when the entry declares one, the columns that conform or are n/a, and the command that reruns just that row: xdrcheck conform run --columns '<wrong columns>' --entries '<entry>' --levels <level>. Cells n/a because the variant needs XDR newer than the column’s SDK has, refused cleanly (section 4, schema reach), are counted under the summary, not listed; matrix.md shows them as –. matrix.md is still the full grid. Under each group’s table, the rows where every column conforms or is n/a are folded into a collapsed block. cross-sdk.md lists the cross-SDK disagreements with the CAPs, the expected value, the columns the corpus says are wrong, their known divergence or finding, and a repro command.

5b. Expected-failure lists and the all-read check

Two options of xdrcheck conform run are for an SDK’s own CI (use-in-sdk-ci.md §7):
  • --write-expected-failures FILE writes the failing cells of one column (--columns <id>) as a list; --expected-failures FILE then passes only when that column’s failing cells are exactly the list. A failing cell is one whose verdict is not conform and not n_a, whether or not the corpus declares it as a known divergence. A failing cell the list does not name fails the run (NEW-FAILURE); a listed cell that conforms or is n/a fails it too (UNEXPECTED-PASS: remove the line), and so does a listed cell of a selected entry that the run does not have (NOT-RUN); a line for an entry the run did not select is ignored. With --expected-failures the list decides the exit code instead of the corpus’s declarations: 0 equal, 1 different, 2 the run could not run. The file has one item per line, <entry> <variant or -> <level or unread>; # starts a comment.
  • --require-all-read fails the run (exit 1) when a column never read a selected entry variant: no cell of the column for it got a driver answer other than n_a (a refusal or a crash is a read), because every level answered n_a or the column’s driver declares none of the levels the entry needs. With --expected-failures, an item the list names with the level unread does not fail it (NEW-UNREAD is one it does not name), and a listed unread item the column now reads fails the run whether or not the option is given. Without the option the run prints one line per column with such items and lists them in SUMMARY.md (matrix.json unread); it does not fail.

xcheck

For SDK maintainers who want to know whether their SDK reads real transactions the same way another SDK, or another version of their own, does. xdrcheck xcheck runs the same transactions through two or more SDK targets or versions and compares only the fields both computed. Each target parses every envelope with its own builder API and writes one row of fields per transaction; a field only one side produces is not compared.
Targets: go, js, python, rust (built and cached as in replay.md). The reference cut (which bytes are which transaction, in apply order) comes from xdrcheck itself, never from a target. Fields: transaction hash, operation count and types, source and fee source accounts (strkeys, M… when muxed), memo type and value, time bounds, fee, and per operation its source, destination, assets, amounts and price.

Normalisation rules

These rules are the whole of what xcheck forgives (xdrcheck xcheck --rules prints them):

Output

DIR/diffs.jsonl (one row per differing field: ledger, tx, field, both targets and values, the rule that applied), DIR/summary.json (per pair of targets: transactions compared, per field compared and differing), DIR/fields-<target>.jsonl (each target’s rows).

Worked example

Each line under a pair names a field (operation indexes as []) and how many of its comparisons differ; diffs.jsonl has every instance with both values.

Mutation

For SDK and indexer maintainers who want inputs beyond the corpus: xdrcheck mutate takes real corpus values, mutates them at the type level, runs every mutant through every conformance column and replay adapter, and reports where a reader disagrees with the oracle, with stellar-core, or with the other readers. It runs offline and is reproducible: the bytes of a mutant are a pure function of the source entry, the seed, the mutator and the place it acts on. The work is split in two:

Sources

Every valid (non-negative) ledger or xdr entry of the corpus up to --max-bytes, and, cut out of each ledger at their typed byte ranges, its first transaction envelopes and SCVals, so the value decoders of every SDK see real values of those types too.

Mutators

A valid-preserving mutant of a ledger has its dependent hashes recomputed (transaction hashes in the results, the transaction set hash, the result set hash, the header hash; the SCP signature cannot be redone without the validator’s key); --stale-hashes leaves them as they were. The ledger’s own protocol version and sequence number are not mutated. A mutant may stack up to three valid-preserving mutations; candidates are minimised to one. The oracle is the pinned stellar-xdr decoding strictly and re-encoding byte for byte. Two kinds of value are XDR-valid but not values stellar-core ever emits, and are marked on the mutant: text that breaks a protocol character rule (asset codes, symbols, home domains, data names), and ledgers whose parts no longer agree (a transaction set and processing list that differ, an operation result list that no longer matches its operations, an updated entry that no longer follows its own state). A reader may refuse those; a reader that halts on them is still reported, with the rule named.

Verdicts

Each (mutant, reader) pair ends in exactly one verdict: Replay adapters see the valid-preserving and metamorphic ledger mutants and their unmutated controls; the harness serves a ledger by decoding it, so a wire-invalid ledger cannot be delivered to them.

Triage

A candidate’s signature is (reader with its version, verdict, mutator, value type and generalised path). Nothing a run writes lands in the repository.

Commands

--as-limit takes one size for every column, or GLOB=SIZE pairs per column (for example rust@*=1G,go@*=1G): node-based drivers cannot start under a small address-space cap, so the JS columns are left out of one. run exits 0 when the run is whole (candidates may have been found) and 2 when the kit’s own tooling failed (the mutation engine, a driver protocol error, a harness fault) or a cell ended in no known verdict. --public writes into the repository’s corpus for an ID already planned). scripts/offline-run.sh xdrcheck mutate run … runs the whole thing with no network.