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.
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:
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
- Create
drivers/<language>/<version>/with lock files that pin the SDK version listed inpins.toml[conformance.columns], and aMakefilewithfetch,build,testandclean(drivers/README.md). - Answer
describefrom the installed package: version, integrity, probes. Never hard-code the SDK version. - Implement L0 first: decode by type name with the SDK’s strict entry point, re-encode, report
reencoded_sha256andconsumed_bytes. Report lenient entry points that behave differently underlenient_entry_points. - Add L1, L3 and the
apioperations the SDK can express, reporting exactly the facts conformance-protocol.md §3 requires. - Optionally let the driver build from an SDK checkout, so the SDK’s maintainers can run
xdrcheck conform --sdk PATHagainst an unreleased branch: theMakefilereadsXDRCHECK_SDK_SOURCE, points the build at that directory, and leavesbin/xdrcheck-sdk-sourcenaming it (drivers/README.md, “Building from an SDK checkout”).describethen reports the version the checkout declares. - Add the column to its family’s file in
drivers/sets.d/(and to a set indrivers/sets.toml, or with[extend]in the same file), runxdrcheck conform build --columns '<sdk>@<version>'andxdrcheck 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 inSECURITY.mdfirst.
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 protocolxcc.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
apioperation the driver lists indescribe.api_opsnever answersn_a/op_not_supported. An operation it does not list answers exactly that. - A declared operation may answer
n_aonly withvalue_not_representable,argument_type_not_acceptedortype_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 fornumber: 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:- It applies only in a dynamically typed language, where the tag kind is the runtime type the driver passes
(JavaScript:
number,string,bigint; Python:intfornumberandbigint,floatfor anumberwith a fraction,strforstring). - “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: stringtakes only a string;offerId?: number | stringtakes a number or a string but not a bigint), the type annotation for Python (offer_id: inttakes no string). The driver names the declaration it read. - 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 nevern_a. - 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). - An answer with this reason when no argument is tagged is a protocol error.
numberthat is rounded before the SDK sees it, the decimal string a JavaScript muxed-account ID must be); columns whose SDK cannot take that kind aren_a, not failures. - It applies only in a dynamically typed language, where the tag kind is the runtime type the driver passes
(JavaScript:
-
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.encodewith atypewhose version byte the SDK’s strkey package does not know isn_a/type_not_generated, never a refusal of the payload).
-
- A strkey text (input kind
strkey) is answered likestrkey.decode: a driver that declares that op may answer itn_aonly withtype_not_generated. - A missing argument, an argument name not in the table below, or a malformed argument (wrong JSON type, bad hex,
an unknown
typeorxdr_typevalue, an asset not spellednativeorCODE:ISSUER) is answered with aprotocol_errormessage 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 answersn_a/argument_type_not_accepted(section 1). - IDs in results: decimal strings. Assets:
nativeorCODE:ISSUER. Hashes and pool IDs: lower-case hex. self_decode(accepted,rejected,not_checked) is required whenever the result hasxdr_hexor a strkey: the SDK’s own decoder run on what the SDK produced. When it isrejectedthe outcome isdiverge/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. Aspec 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 droppedSorobanTransactionData, 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
AnScError 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
apientry withexpect_rejectandexpect_valueorexpect_xdr_hexconforms 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 examplestellar_value_signed_ms); it is beyond a column’s reach only if the column’sdescribereports the probe of a required feature asfalse(a feature name is its probe name). A variant withoutrequiresfalls back to its protocol against the column’sxdr_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 anapiorstrkeyentry) forunion_arm_undeclaredorenum_undeclared, orstrkey_versionfor a strkey text (the Ruststellar-xdrcolumn reports such refusals asdecode_error, which is accepted for it). That refusal isn_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 isn_a. - stellar-core’s own reading. A negative entry whose
core_behaviour.acceptsistruerecords that stellar-core’s decoder accepts the input. The SDK columns must still refuse it, but on the stellar-core column (kindcore) 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 asn/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
matchblock (reason,envelopes_parsed,rejected_tx_index), when it has one, must equal the driver’s report. Otherwise the cell isknown-changed. - Version ranges that do not parse stop the run (exit 2) and name the entry.
- Decode profiles. A column with a
profileruns every cell under limits the driver sets, not the SDK. The Ruststellar-xdrcolumns, whose library has no default limits, use two:limits-defaultisLimits { depth: <the host default>, len: <input length> }, the Soroban host’s default XDR depth (DEFAULT_XDR_RW_LIMITSinsoroban-env-host/src/budget/limits.rs) with the length budget set to the input size;limits-noneisLimits::none(), what the crate’s CLI uses. - Profiles. A known divergence’s
profileis either a column’s decode profile (Rustlimits-default,limits-none), asserted only on columns of that profile, or an address-space sandbox writtenaddress-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 thatRLIMIT_AScap (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 (sandboxin 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 examplelimits-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,derivedreduced 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
(
fingerprintingo/internal/conform/verdict/matrix.go): L0consumed_bytes,reencoded_hexandlenient_entry_points; L1operation_types,focus.operation_types,events,reencoded_sha256,envelopes_parsed,envelopes_rejectedandrebuild(the rebuild fact, which not every SDK can report), and everyderivedkey the manifest does not state for the variant; L3native.type,native.summaryandnative.error; L4self_decode. Each column is still judged against the manifest on every fact the manifest states (L0consumed_bytesagainst 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.0columns run thestellar-xdrcrate 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) passesxdrcheck conform checkwithout having judged anything. How many cells each column judged is read frommatrix.json(cells, each with itscolumnandverdict); no report states it per column.xdrcheck conform sdk-regressionfails 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 ofxdrcheck conform run are for an SDK’s own CI (use-in-sdk-ci.md §7):
--write-expected-failures FILEwrites the failing cells of one column (--columns <id>) as a list;--expected-failures FILEthen passes only when that column’s failing cells are exactly the list. A failing cell is one whose verdict is notconformand notn_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-failuresthe 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-readfails 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 thann_a(a refusal or a crash is a read), because every level answeredn_aor the column’s driver declares none of the levels the entry needs. With--expected-failures, an item the list names with the levelunreaddoes not fail it (NEW-UNREADis one it does not name), and a listedunreaditem 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 inSUMMARY.md(matrix.jsonunread); 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.
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
[]) 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.