> ## 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.

# Conformance driver protocol and rules

> xcc.driver/1, the messages between the conformance runner and a driver that runs one SDK version; the runner's outcomes, evidence and judging rules; xcheck and mutation.

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:

| Page | Covers |
| - | - |
| `corpus/schema/driver-protocol.schema.json` | The message shapes (JSON Schema 2020-12); worked messages in `corpus/schema/examples/driver-protocol/`. Where this page and the schema disagree, the schema wins |
| [conformance-protocol.md](#conformance-rules) | The normative rules a schema cannot express: the `api` operation vocabulary, the facts an accepted cell must carry, `n_a` rules, and how the orchestrator judges cells and checks a run |
| `drivers/README.md` | Driver directories, the `Makefile` contract (`fetch`, `build`, `test`), column sets, how the orchestrator starts and supervises drivers, and the output files |

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

| Rule | Requirement |
| - | - |
| Framing | One JSON object per line (NDJSON) on stdio. Requests on the driver's stdin; exactly one response per request on stdout, echoing the request `id` and the protocol tag `"xcc": "xcc.driver/1"`. stderr is free-form diagnostics, captured and never parsed |
| Start | The orchestrator starts the column's `run` command (by convention `bin/xdrcheck-driver`) in the driver directory, with no network, and sends one request at a time |
| Processes | One long-lived process serves a column's cells serially; columns run in parallel (`--jobs`). Entries built to stress a reader (the `limits/` group, and any entry with a known divergence of outcome `crash` or `hang`) run in a fresh process each |
| Limits | Per driver process: `--timeout` per request (default 20 s, plus as much again per MiB of input), `--memory-max` (default 1 GiB) and an optional address-space cap (`--as-limit`) |
| Death | A driver that dies, or is killed at the timeout or the memory cap, is recorded as `crash` by the orchestrator (reason `process_died`, `timeout` or `out_of_memory`) and replaced |

## 3. Messages

### 3.1 `describe`

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

```json theme={null}
{"xcc":"xcc.driver/1","id":1,"op":"describe"}
```

| Field | Meaning |
| - | - |
| `driver` | Driver name and version; `adapter` names the API generation it bridges (for example `js-v17`) |
| `sdk` | `ecosystem`, `package`, `version` (must equal the column's pin, or the column is not run and the command exits 2), `integrity` of the installed artefact, and the resolved `dependencies` that decide decoding |
| `runtime` | Language runtime name and version, OS, architecture, decode thread stack size |
| `xdr_schema` | What the SDK's generated XDR can represent, probed from its enums at start-up, not inferred from the version: named `probes` (at least `sc_address_type_muxed_contract` and `stellar_value_signed_ms`), the highest `protocol` whose probes pass (omitted when the SDK declares an enum member beyond the highest protocol the kit knows, so nothing is excused by protocol), and optionally the decodable `types` |
| `levels` | The levels it answers (§4); a level not declared is recorded `n_a` without a request |
| `object_parsers`, `native_converters` | L1 and L3 entry points per XDR type, for example `{"TransactionEnvelope": "TransactionBuilder.fromXdr"}` |
| `api_ops` | The `api` operations it implements ([conformance-protocol.md §2](#conformance-rules)) |
| `decode` | The L0 `entry_point`, the SDK's `default_depth`, whether the entry point itself rejects trailing bytes (`checks_consumed_length`), and named decode `profiles` (Rust: `limits-default`, `limits-none`) |

### 3.2 `run`

One cell: one entry, one variant, one level, optionally one decode profile.

```json theme={null}
{"xcc":"xcc.driver/1","id":7,"op":"run","entry":"cap-0038/pool-issuers-order-by-bytes-not-strkey","variant":"testnet","level":"L1","input":{"kind":"xdr","xdr_type":"LedgerCloseMeta","path":"/corpus/blobs/85/85….xdr","passphrase":"Test SDF Network ; September 2015"}}
```

Inputs, by `input.kind`:

| `kind` | Fields |
| - | - |
| `xdr` | `xdr_type`; the bytes as `path` (absolute, opened read-only) or inline `xdr_hex`; `framing` (`none`, or `record-marked` with `frame_index`); `passphrase` for parsers that compute hashes; `focus` (transaction and operation index); `pinpoints` (L2: JSON Pointers whose values to return) |
| `api` | `api_op`, `args` (the entry's `api.input` verbatim, with native-type tags), `passphrase` |
| `strkey` | `text`, optional `declared_type` |

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:

```json theme={null}
{"xcc":"xcc.driver/1","id":7,"op":"run","entry":"cap-0038/pool-issuers-order-by-bytes-not-strkey","variant":"testnet","level":"L1","outcome":"reject","reason":{"code":"ordering","message":"Assets are not in lexicographic order","error_class":"Error","entry_point":"TransactionBuilder.fromXdr"},"actual":{"object":{"transactions":19,"envelopes_parsed":18,"tx_hashes":["92203c07…","e63b9ca4…"],"envelopes_rejected":[{"tx_index":2,"tx_hash":"0126748091930959a3aefac9296e1773b947f964a9b73f37ce856c4df32d346f","code":"ordering","message":"Assets are not in lexicographic order"}]}}}
```

```json theme={null}
{"xcc":"xcc.driver/1","id":8,"op":"run","entry":"cap-0038/pool-issuers-order-by-bytes-not-strkey","variant":"testnet","level":"L1","outcome":"ok","actual":{"object":{"transactions":19,"envelopes_parsed":19,"operations":21,"tx_hashes":["92203c07…","e63b9ca4…","01267480…"],"focus":{"tx_hash":"0126748091930959a3aefac9296e1773b947f964a9b73f37ce856c4df32d346f","operation_types":["change_trust","change_trust","change_trust"],"derived":{"operation_type":"change_trust","pool_id":"c2a730127d006897b021d6fcb279da68b4f65f9b6a408c74eb2cdd85ea862d5e"}}}}}
```

(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

| Level | Question | Example failure |
| - | - | - |
| **L0** codec | Decode the bytes as the named type and re-encode: identical, and all bytes consumed? | a Protocol 30 ledger on a pre-Protocol 30 SDK; trailing bytes accepted |
| **L1** object | Does the SDK's high-level layer take it? For a ledger, every envelope in the transaction set goes through the SDK's transaction parser | js-stellar-sdk#1766: the bytes round-trip, `TransactionBuilder.fromXdr` throws |
| **L2** values | Does the SDK's decoded value equal the oracle's at the requested pinpoints? | a 64-bit ID through a float |
| **L3** native | Does the SDK's native conversion keep the value? | js-stellar-sdk#1789: colliding map keys silently merged |
| **L4** API | For `api` and `strkey` entries: does building or encoding produce the expected bytes or the expected refusal? | js-stellar-sdk#1785: an offer ID re-encoded as a different ID |
| **spec** contract interface | For `spec` entries: does the SDK's contract-spec reader return the entries the bytes hold, and refuse a module with several `contractspecv0` sections or a stream that does not end cleanly? | a reader that takes the first of two sections shows half the interface |
| **json** XDR-JSON | On the XDR-JSON columns, for every ledger and xdr variant: does the converter's SEP-51 JSON validate against its own schema and come back to the same bytes, and do converters agree? | a `StringM` escaped beyond its schema's `maxLength` |

Which levels apply to which entry kind is in [manifest.md §10](https://docs.xdrcheck.dev/reference/manifest.md).

## 5. Outcomes and reasons

| `outcome` | Meaning |
| - | - |
| `ok` | The SDK accepted the input and the level's operation completed |
| `diverge` | The SDK accepted the input and the driver itself saw a self-evident mismatch (for example its re-encoding differs, or its own decoder rejects what it just encoded) |
| `reject` | The SDK refused the input through its normal error channel and the process is healthy |
| `crash` | A fault-class error was caught in process; the orchestrator assigns `crash` itself when the process dies. A driver never reports a stack overflow, out-of-memory or panic as `reject` |
| `n_a` | The SDK has no API for this level, type or operation, under the narrow rules of [conformance-protocol.md §1](#conformance-rules) |

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](#conformance-rules). 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](#conformance-rules)).

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](#conformance-rules)), so a driver answers `n_a` only under the narrow rules
of [conformance-protocol.md §1](#conformance-rules).

`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](#conformance-rules) 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`](https://docs.xdrcheck.dev/reference/manifest). The messages, levels and outcomes are introduced in
[`driver-protocol.md`](https://docs.xdrcheck.dev/reference/driver-protocol).

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`.

| op | arguments (required unless in brackets) | `value` | `xdr_hex` |
| - | - | - | - |
| `asset.compare` | `asset_a`, `asset_b` | integer -1, 0 or 1 | — |
| `liquidity_pool.id` | `asset_a`, `asset_b`, \[`fee` = 30] | pool ID hex | — |
| `liquidity_pool.asset` | `asset_a`, `asset_b`, \[`fee` = 30] | pool ID hex | `ChangeTrustAsset` |
| `muxed_account.encode` | `account` (G…), `id` (tagged) | `M…` strkey | `MuxedAccount` |
| `muxed_account.decode` | `text` (M…) | `{"account": "G…", "id": "<decimal>"}` | — |
| `offer.manage_sell`, `offer.manage_buy` | `offer_id` (tagged), \[`selling` = `native`], \[`buying` = `USD:GA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ`], \[`amount` = `"1"`], \[`price` = `"1"`] | the offer ID read back from the encoded operation, decimal string | `Operation` |
| `scval.from_native` | `value` (JSON, tagged leaves), \[`type`] | for a map, the list of keys `"<arm>:<text>"` in the resulting order; else that single string | `ScVal` |
| `scval.sort_map` | `keys` (list of `"u32:10"`, `"bytes:0a"`, `"symbol:a"`, `"string:b"`, or `{"xdr_hex": …}`) | the keys in the resulting order, same form | `ScVal` |
| `scval.to_native` | `xdr_hex` (`ScVal`) | `{"map_entries": n}` for a map, else the native value as JSON (64-bit and wider as decimal strings, bytes as hex) | — |
| `scval.native_roundtrip` | `xdr_hex` (`ScVal`), \[`type`] | boolean: bytes preserved | the `ScVal` produced |
| `strkey.encode` | `type` (the schema's strkey type enum), `payload_hex` | strkey text | — |
| `strkey.decode` | `text`, \[`type`] | payload hex | — |
| `transaction.parse` | `xdr_hex` (`TransactionEnvelope`), `passphrase` | `{"tx_hash": "<hex>", "operations": n}` | the re-encoded envelope |
| `transaction.hash` | `xdr_hex`, `passphrase` | hash hex | — |
| `memo.text_roundtrip` | `xdr_hex` (`Memo`) | hex of the native text's bytes as the SDK holds them | the re-encoded `Memo` |
| `address.to_strkey` | `xdr_hex`, \[`xdr_type` = `MuxedAccount`, or `AccountId`] | strkey | — |
| `address.from_sc_address` | `xdr_hex` (`ScAddress`) | strkey | — |
| `signer_key.to_strkey` | `xdr_hex` (`SignerKey`) | strkey | — |
| `operation.object_roundtrip` | `xdr_hex` (`Operation`) | boolean: bytes preserved | the rebuilt `Operation` |
| `asset.from_operation` | `xdr_hex` (`Asset`) | `{"type", "code", "issuer"}` | — |
| `xdrjson.decode` | `xdr_type`, `json` | — | the value's XDR |
| `xdr.custom_union_encode` | `switch_on` (the discriminant's XDR type: `int`, `unsigned int`, `hyper`, `unsigned hyper`, `float`, `double` or `bool`), `cases` (list of `{"discriminant", "arm"}`: a tagged discriminant, and `void` or one of the `switch_on` type names), `discriminant` (tagged), \[`value` (tagged): the payload when the selected arm is not `void`] | the discriminant as the SDK's own decoder reads it back, as text (`String()` of the native value; 64-bit as decimal) | the encoded union |
| `price.encode` | defined with the first entry that uses it | | |

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](https://docs.xdrcheck.dev/reference/manifest.md); 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

| Level and input | Required on `ok` |
| - | - |
| L0, any value | `actual.reencoded_sha256`, `actual.consumed_bytes`; the stellar-core column (kind `core`), which decodes and prints but never re-encodes, carries `consumed_bytes` alone, and it must equal the input's length |
| L1, a ledger (`LedgerCloseMeta`) | `object.transactions`, `envelopes_parsed` (equal to `transactions`), `operations`, `tx_hashes` (one per parsed envelope); `object.focus` when the request's focus names a transaction (`tx_index`), with `focus.rebuild` when the driver declares `object_rebuild` |
| L1, a `TransactionEnvelope` | `object.tx_hash` (when the request carries a passphrase), `operation_types`, `operations`, `reencoded_sha256`, `derived`; `rebuild` under a passphrase when the driver declares `object_rebuild` |
| L1, any other value with an object layer | `object.derived` (`{}` when the object yields nothing) |
| L3 | `actual.native` with `type`, `bytes_preserved`, and `map_entries` when the entry states a map's entry count; `native.error` for an `scvError` value (the native error fact) |
| L4 | `actual.api` with `value` and `xdr_hex` as the table in section 2 defines them, and `self_decode` as above |

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:

| key | shape | required on | compared with |
| - | - | - | - |
| `transactions` | integer: envelopes in the transaction set | ok, reject | `expect.ledger.transactions` |
| `envelopes_parsed` | integer | ok, reject | on ok, equal to `transactions` |
| `operations` | integer: operations of every parsed envelope (a fee bump counts its inner transaction's) | ok | `expect.ledger.operations` |
| `tx_hashes` | lower-case hex, the SDK's hash of each parsed envelope in apply order (the order of the ledger's transaction processing list); a rejected envelope is left out; `[]` when there is none | ok, reject | on ok, equal as an ordered list to `variants[].derived.tx_hashes` |
| `envelopes_rejected` | `{tx_index, tx_hash, code, message}`: apply-order index, the hash the ledger records for it, the reason code | reject | a known divergence's declared detail |
| `focus` | `{tx_hash, operation_types[], derived{}}` for the transaction at the request's `focus.tx_index` (apply order); `derived` describes the operation at `focus.op_index` | ok, when the request names a focus transaction | `tx_hash` with `variants[].derived.tx_hash`; `derived` as below |

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.

| key | value |
| - | - |
| `operation_type` | the operation's XDR-JSON arm |
| `operation_source` | the operation's own source account, when it has one (not the transaction's), as a strkey (`M…` when muxed) |
| `pool_id` | the liquidity pool ID (a change-trust to a pool share; a pool deposit or withdrawal), lower-case hex |
| `asset` | `native` or `CODE:ISSUER`: the line of a change-trust to an asset; the asset of a payment, set-trust-line-flags, clawback or create-claimable-balance; the destination asset of a path payment |
| `address` | the counterpart, as a strkey: the destination of create-account, payment, path payments and account-merge; the trustor of allow-trust and set-trust-line-flags; the `from` of clawback; the sponsored account of begin-sponsoring-future-reserves |
| `muxed_id` | the decimal ID of a muxed `address`, else of a muxed `operation_source` |
| `offer_id` | the offer ID of a manage-offer operation, decimal |
| `memo_type` | `none`, `text`, `id`, `hash` or `return`, of the focus transaction (a fee bump's inner transaction) |

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.

| field | value |
| - | - |
| `entry_point` | the builder entry point, equal to `describe.object_rebuild` |
| `outcome` | `rebuilt` (with `tx_hash`), `refused` (with `message`: the builder threw on a transaction its declaration can express), or `not_rebuilt` (with `reason`) |
| `reason` | `fee_bump`; `no_time_bounds`; `fee_not_per_operation`; `soroban_memo`; `soroban_muxed_source` |
| `differs` | diagnostic only: the `Transaction` fields whose encoding differs between the parsed and the rebuilt transaction |

`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.

| SDK | `object_rebuild` | Recipe |
| - | - | - |
| JavaScript (16.x and 17.x) | `TransactionBuilder.cloneFrom` | `cloneFrom(tx)`, then `setSorobanData` with the envelope's `SorobanTransactionData`, because `cloneFrom`'s declaration says it does not clone that data; then `build()` |
| Go | `txnbuild.NewTransaction` | the SDK has no clone API, so the recipe is the driver's. It uses only what the parsed object exposes: source account and sequence number (`IncrementSequenceNum` false), the parsed operations, the memo, and the inclusion fee per operation. The inclusion fee is `MaxFee` less the resource fee the parsed Soroban operation's own `BuildTransactionExt` carries. The parsed transaction has no getter for its preconditions beyond `Timebounds()`, so they are read through the SDK's converter, `Preconditions.FromXDR` on the object's `ToXDR()`; a precondition lost there cannot show here |
| Python | not declared | `TransactionBuilder.from_xdr` returns the parsed envelope, not a builder; the SDK's `Transaction` is the typed model itself, and L1 already re-encodes it from its fields |
| Rust | not declared | no object layer (section 4a) |

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:

| SDK | `scvError` native value | Read as |
| - | - | - |
| JavaScript (16.x and 17.x) | `scValToNative`: `{type: "contract", code}`, or `{type: "system", code, value}` for every other type | `contract` and its code; otherwise any string property naming an `ScErrorType` (`sceStorage` or `storage`) or an `ScErrorCode` (`scecExceededLimit` or `exceeded_limit`) |
| Python | `scval.to_native` returns the `SCVal` itself | its `SCError`: type and code |
| Go, Rust | no native layer (`n_a/no_native_layer`) | — |

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.

| Listed as | When | Where it comes from |
| - | - | - |

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.

| Exit | `xdrcheck conform check` |
| - | - |
| 0 | pass |
| 1 | failing or stale cells |
| 2 | the check could not run |

`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:

| Kind | Rows |
| - | - |
| new | a cell `xdrcheck conform check` fails on: a divergence no entry declares, a declared divergence the cell no longer matches, or a cell that conforms inside a declared range |
| known divergences | every wrong cell is a declared known divergence |
| SDKs disagree | no column is wrong against the corpus, but the latest columns of the SDKs disagree (a value the corpus does not state) |

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](https://docs.xdrcheck.dev/guides/sdk-ci.md)):

* `--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.

```text theme={null}
xdrcheck xcheck --target TARGET@VERSION --target TARGET@VERSION [...]  (--ledgers L | --tx L:I | --set NAME | --ledger-file F)
           [--out DIR] [--network pubnet|testnet] [--rules]
```

Targets: `go`, `js`, `python`, `rust` (built and cached as in [replay.md](https://docs.xdrcheck.dev/reference/replay-target.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):

| Rule | Fields | Equal |
| - | - | - |
| `op-type` | `operations[].type` | names without case and underscores: `ManageSellOffer`, `manageSellOffer`, `manage_sell_offer`; the `revoke*Sponsorship` spellings are one name |
| `amount` | amounts, limits, send and destination amounts | exact decimals: `10`, `10.0`, `10.0000000`, `1E1` |
| `price` | `operations[].price` | exact reduced fractions (`1/2`, `2/4`, `0.5`); a decimal with k fractional digits equals a fraction it is within 10^-k of |
| `time-bounds` | `time_bounds` | absent, and min = max = 0 |
| `hex` | `hash`, hash and return memos | lower-case hex |
| `integer` | `fee`, `op_count` | as numbers |
| `text` | accounts, assets, memo text | exactly |

### 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).

| Exit | Meaning |
| - | - |
| 0 | nothing differs |
| 1 | a field differs |
| 2 | the comparison could not run |
| 3 | a target is not available |

### Worked example

```text theme={null}
$ xdrcheck xcheck --target js@17.4.0 --target python@17.0.1 --ledgers 30941181,30941857 --out xc
js@17.4.0 vs python@17.0.1: 143 transactions, 0 fields differ
-> xc (diffs.jsonl, summary.json)
```

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:

| Part | What it does |
| - | - |
| `xdrcheck-mutate` (Rust, `crates/xdrcheck-mutate`) | Reads corpus values with a schema-driven reader built from the pinned `stellar-xdr` crate's own XDR definitions, keeping every node's byte range; applies mutators; checks each mutant with the oracle and the reference extractor; writes the mutants as a corpus of their own |

### 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 `SCVal`s, so the value decoders of every SDK see
real values of those types too.

### Mutators

| Class | Mutators | The oracle |
| - | - | - |
| 2, metamorphic | `change-permute` (each operation's change list reordered across ledger keys only: every change of one key keeps its relative order, and a `STATE` or `RESTORED` change stays next to the `UPDATED` or `REMOVED` change of the same entry), `timing` (the `core_metrics` timing values zeroed or altered) | must accept, and the reference extractor's facts must equal the original's |
| 3, wire-invalid | `bool-2`, `opt-flag-2`, `padding-nonzero`, `disc-unknown`, `enum-range`, `len-over-remaining`, `len-over-max`, `truncate`, `trailing`, each written at the byte offset of a typed value | must refuse |

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:

| Verdict | Meaning |
| - | - |
| `accepts-invalid` | the reader accepted a mutant the oracle and stellar-core refuse |
| `refuses-valid` | the reader refused, at the XDR level, a mutant the oracle and stellar-core accept |
| `halt` | the reader crashed, timed out, ran out of memory, panicked or stopped ingesting |
| `wrong-fact` | the reader accepted but re-encoded different bytes, or reported facts the oracle does not give |
| `order-dependent` | a metamorphic mutant changed what the reader reports |
| `cross-reader-split` | the oracle and stellar-core disagree on the mutant (it is quarantined as an oracle question), and the SDKs split too; the readers outside the group spanning the most SDKs are in the split |
| `reader-consensus` | every SDK that ran (two families or more) disagrees with the oracle the same way, but stellar-core sides with the oracle: the SDKs share a mistake against the network's reading; reported in a section of its own |
| `conform`, `n_a`, `refused`, `flaky`, `inherited`, `oracle-question`, `reference` | not findings: the reader agrees; the input is beyond the reader's reach; the reader refused a value that breaks a protocol rule, or an object layer refused a protocol-invalid value; flaky; the reader fails the unmutated control the same way; the oracle cannot judge (stellar-core disagrees with it, or every SDK agrees against it and stellar-core did not run); the stellar-core column itself |

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

```text theme={null}
xdrcheck mutate run [--seed N] [--budget N] [--columns all|none|GLOBS] [--adapters all|none|NAMES] [--entries GLOBS]
               [--classes …] [--mutators …] [--max-bytes N] [--stale-hashes] [--no-suppress] [--minimise N]
               [--timeout D] [--memory-max SIZE] [--as-limit SIZE|GLOB=SIZE,…] [--adapter-memory-max SIZE] [--adapter-deadline D]
xdrcheck mutate replay   --entry SOURCE [--variant N] --seed N --mutation IDS [--readers …] [--print READER]
xdrcheck mutate minimise --entry SOURCE [--variant N] --seed N --mutation IDS --reader R [--readers …]
xdrcheck mutate promote  --entry SOURCE [--variant N] --seed N --mutation IDS --id NEW_ID [--into DIR] [--public]
```

`--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.


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