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

# Manifest and index format

> The corpus manifest and index: entries, variants, sources, expected values, validity, conformance levels and entry IDs.

For SDK maintainers who load corpus entries into their own tests, indexer operators who write an adapter or read
a replay report, and anyone who writes an entry. After it you can read any manifest file: what each field means,
how an expected value is matched against what your reader produced, and which checks every entry must pass.

Version 1. This document is normative for every tool, adapter and conformance driver that writes or reads corpus
entries. The machine-readable authority is the JSON Schema `corpus/schema/manifest-entry.schema.json` (schema ID
`xcc.manifest.entry/v1`; schema-set version in `corpus/schema/SCHEMA_VERSION`, 2 since `validity`, `flags` and the
entry index were added, §12). Where this text and the schema disagree, the schema wins and this text is a bug. This
document adds what a schema cannot say.

Companion pages: [`entry-ids.md`](#entry-ids) (the entry-ID registry and its grammar) and
[`authoring-entries.md`](https://docs.xdrcheck.dev/guides/add-corpus-entries#authoring-reference) (how to write an entry and the review checklist).

The words *must*, *must not* and *never* state requirements. Section numbers below are this document's own.

***

## 1. Purpose

One JSON file per **entry**. An entry describes one rare-but-valid (or, for negative entries, deliberately invalid)
pattern of Stellar ledger data: where its bytes came from, which CAP and protocol made it possible, and what a
correct reader must produce from it. The manifest files plus the blobs they point to are the whole corpus. Every
tool of the kit — the oracle, the generator, the replay harness, the conformance runner, the guide generator and
the coverage report — reads these files and nothing else.

Terms used throughout:

| Term | Meaning |
| - | - |
| reader | Any software under test that consumes the bytes: an SDK, an indexer, an ETL pipeline |
| oracle | The kit's decoder, built on the pinned rs-stellar-xdr (`stellar-xdr` crate); it produces the decoded sidecars and runs the checks of §11 |
| adapter | The component that drives one indexer for the replay harness and reports what the indexer stored as *observations* (`corpus/schema/adapter-protocol.schema.json`, `corpus/schema/observation.schema.json`) |
| driver | The component that runs one SDK version for the conformance runner (`corpus/schema/driver-protocol.schema.json`) |
| consumer | Anything that compares a reader's output with an entry: the replay harness's matcher, a conformance driver, the reference extractor |

### 1.1 Where the core facts live

Six facts identify every entry: its ID, CAP, protocol version, source, whether it is synthetic, and its expected
decoded values. They map onto the manifest like this:

| Fact | Manifest field(s) | Notes |
| - | - | - |
| entry ID | `id` | Stable, never reused (§5) |
| CAP | `caps` (and `caps_note` when empty) | CAP numbers as integers. A pattern no CAP introduced carries `caps: []` and a `caps_note` saying why, by design (§4.1) |
| protocol version | `protocol.introduced`, `variants[].protocol`, `variants[].header_protocol` | Three different facts that one number would blur: the first protocol that can emit the pattern; the protocol applied when these bytes were emitted; and, on upgrade ledgers, the header's protocol, which differs from the applied one (§4.2) |
| source | `variants[].source` | One of five typed provenance records (§4.4) |
| synthetic flag | `synthetic` | `true` only for bytes stellar-core did not emit |
| expected decoded values | `variants[].decoded` (the full decoded rendering) and `expect` (semantic facts and pinpointed values) | Three layers (§6.1) |

### 1.2 The worked examples

Three entries in `corpus/manifest/` are the worked examples quoted in this document (the corpus holds many more; `corpus/COVERAGE.md` lists them by CAP):

| Entry | Source | Shows |
| - | - | - |
| `cap-0040/signed-payload-signer-added` | one public testnet ledger (`history`) | a lake object and its blob; a signer compared in full; a whole-ledger transaction list; two indexer known divergences |
| `cap-0038/pool-issuers-order-by-bytes-not-strkey` | one public testnet ledger (`history`) | a focus that is not the first transaction; pinpoints into the transaction set; known divergences in four SDK families |
| `cap-0073/sac-trust-creates-trustline` | local stellar-core runs (`local-core`), four variants | shared `expect` with per-variant `derived` values; `only_if`; a chain index; a recorded golden mirror run |

## 2. Files and layout

What `corpus/` holds today:

```text theme={null}
corpus/
  plan.json                                        entry-ID registry (docs/entry-ids.md)
  schema/                                          JSON Schemas, SCHEMA_VERSION, examples/<schema>/valid-NN.json, invalid-NN.json
  manifest/<group>/<slug>.json                     one entry per file; the path equals the entry ID
  blobs/<aa>/<sha256>.xdr                          content-addressed raw XDR; <aa> = first two hex characters of the hash
  decoded/<aa>/<sha256>.json.zst                   decoded sidecar (SEP-51 XDR-JSON, zstd), one per blob, named by the blob's hash
  chains/<scenario>/p<NN>-<network>.json           chain index of one kept scenario run (§8.2)
  chains/<scenario>/p<NN>-<network>.meta.xdr.zst   that run's whole meta stream (zstd), for chains written by xdrcheck-corpus gen
  objects/<network>/<ledger>/<KEY>.xdr.zst         public data-lake objects vendored unmodified, each with capture.json
  index.json                                       flat entry index, one row per entry (§3.1; xdrcheck-corpus index)
```

Concretely: `corpus/manifest/cap-0040/signed-payload-signer-added.json`,
`corpus/blobs/58/582e694b96bf69f894763909a1b058c1a2523d5634f2e0947393cee9765f4e0e.xdr`,
`corpus/decoded/58/582e694b96bf69f894763909a1b058c1a2523d5634f2e0947393cee9765f4e0e.json.zst`, `corpus/chains/sac-trust/p28-testnet.json`,
`corpus/objects/testnet/4437357/capture.json`.

Rules:

* Paths inside an entry are relative to the corpus root (`corpus/`): `blob.path`, `decoded`, `source.scenario`,
  `source.object_path`. A `local-core` variant's `source.scenario` names its scenario file under `scenarios/`;
  a variant produced before the generator existed would instead point at its published driver under `evidence/`
  (relative to the repository root).
* Sidecars are stored **once per blob**: every variant whose blob is `blobs/<aa>/<sha256>.xdr`, in any entry, has
  `decoded: "decoded/<aa>/<sha256>.json.zst"`. The file is the oracle's SEP-51 JSON written compactly (no
  whitespace, object keys in the XDR field order the oracle emits, one trailing newline) and compressed as a single
  zstd frame (level 19, with the content checksum). `decoded_sha256` is the sha256 of the **uncompressed** JSON, so it
  does not depend on the zstd build. `xdrcheck-corpus render` writes these files and removes any file under `decoded/`
  that no variant references; `xdrcheck-corpus render --print <entry> [--variant <network>[@<protocol>]] [--pretty]`
  prints one variant's JSON, and `zstd -dc <file>` works too.
* `corpus/objects/` keeps captured public-lake objects byte-for-byte, with a `capture.json` that records the store,
  key, hashes, the store's object metadata and the commands used. A `history` entry's blob is cut from one of them
  (§4.5). Upgrade-ledger captures such as `corpus/objects/pubnet/30191538/capture.json` are kept there too.

Also in the corpus root: the corpus index `corpus.json` (§3) and the entry index `index.json` (§3.1); the generator's scenario files in `scenarios/`
(schema `corpus/schema/scenario.schema.json`; `scenarios/pr.list` names the ones regenerated on every pull
request); the guide's field-table source `fields.yaml` (schema `corpus/schema/fields.schema.json`); the generated
coverage report `coverage.json` and `COVERAGE.md` (`xdrcheck-corpus coverage`); the CAP inventory `caps.toml`; and the
bulk-tier checksum files under `bulk/` that `corpus.json` names.

## 3. The corpus index (corpus.json)

The corpus root carries one index file, corpus.json, validated by `corpus/schema/corpus-index.schema.json` (example:
`corpus/schema/examples/corpus-index/valid-01.json`). It is written by hand; its `pins` repeat `pins.toml`, and `make repo-checks` validates it against the files it names. A
complete example:

```json theme={null}
{
  "schema": "xcc.corpus/v1",
  "corpus_version": "30.0.0",
  "entry_schema": "xcc.manifest.entry/v1",
  "max_protocol": 30,
  "max_ledger_close_meta_version": 2,
  "pins": {
    "stellar_core": {"version": "30.0.0", "commit": "0e49751aa9ddf892302cca02cea7f3f5d97df9f1"},
    "xdr_definitions": {"tag": "v30.0", "commit": "4f524bbac80c781c06e4fb5fc93a2d0d331d6705"},
    "oracle": {"crate": "stellar-xdr", "version": "30.0.0", "commit": "3c2aa43d2ab54d429ae44aa5143d805bf5dba7e2"}
  },
  "tiers": {
    "curated": {"in_repository": true, "entries": 3, "blobs": 6, "bytes": 208420},
    "bulk": {
      "in_repository": false,
      "description": "stellar-core golden LedgerCloseMeta, tier current",
      "source": "https://github.com/stellar/stellar-core",
      "ref": "v30.0.0",
      "path": "test-lcm-current",
      "files": 866, "ledgers": 15306, "bytes": 78058472,
      "file_index": "bulk/core-v30.0.0-current.sha256"
    }
  },
  "checksums": {
    "algorithm": "sha256",
    "manifest": "manifest.sha256",
    "blobs": "implicit (file name is the hash)",
    "decoded": "variants[].decoded_sha256"
  },
  "generated_at": "2026-11-12T00:00:00Z"
}
```

| Field | Meaning |
| - | - |
| `schema` | Constant `xcc.corpus/v1` |
| `corpus_version` | `MAJOR.MINOR.PATCH`, optionally with a pre-release suffix; MAJOR is the highest protocol the corpus covers |
| `entry_schema` | The entry schema ID every entry declares (constant `xcc.manifest.entry/v1`) |
| `max_protocol`, `max_ledger_close_meta_version` | The fail-closed gate: tools refuse entries above these values instead of guessing |
| `pins` | The versions against which "decoded" and "core-emitted" are defined: stellar-core (version, commit), the XDR definitions (tag, commit) and the oracle crate (`stellar-xdr`, version, optional commit). Same content as the project's `pins.toml` |
| `tiers.curated` | The in-repository corpus: entry, blob and byte counts |
| `tiers.bulk` | The full stellar-core golden set, fetched by pinned ref and not stored in the repository: source, ref, path inside the source, file, ledger and byte counts (866 files, 15,306 ledgers, 78,058,472 bytes at stellar-core v30.0.0), and `file_index`, a `sha256sum`-format list of every file relative to the corpus root, so a fetch is verified offline afterwards |
| `checksums` | `algorithm` (`sha256`), `manifest` (a `sha256sum`-format file covering every manifest file, so a release archive is verifiable with standard tools), and optional notes on how `blobs` and `decoded` are covered |
| `generated_at` | The only timestamp; excluded from release reproducibility checks |

### 3.1 The entry index (index.json)

`corpus/index.json` lists every entry in one flat file, so a consumer with only `jq` or a JSON library finds an
entry's CAPs, kind, validity and bytes without walking `manifest/**`. It is generated: `xdrcheck-corpus index` writes it
from the manifest and `corpus/caps.toml`, `xdrcheck-corpus index --check` fails when it is stale, and `make repo-checks`
compares every row with its manifest file. Schema: `corpus/schema/entry-index.schema.json` (`xcc.index/v1`). The
manifest entry stays the authority; the index repeats only what is needed to find an entry and its bytes.

The file is `{"schema": "xcc.index/v1", "entries": [...]}` with one entry per line, sorted by ID. Each row:

| Field | Meaning |
| - | - |
| `id`, `title`, `kind`, `caps`, `protocol`, `synthetic` | As in the entry (§4.1). CAPs are always the array `caps`; there is no singular `cap` field anywhere in the corpus |
| `rows` | The coverage rows of `COVERAGE.md` the entry counts under: the row of each CAP in `caps` and the row named by the ID's group |
| `validity`, `flags` | The entry's negative-case class and bug-class flags (§9.5); `flags` is `[]` when the entry has none |
| `sources` | The distinct `source.kind` values of its variants, sorted; `[]` for `api` and `strkey` entries |
| `tier` | `curated`, or `stress` for the entries a release archive ships in its separate `stress/` root ([release.md](https://docs.xdrcheck.dev/guides/maintain-kit.md#release-and-channels) section 3) |
| `manifest` | The manifest file, `manifest/<id>.json` |
| `variants[]` | Per variant: `network`, `protocol`, `ledger_seq`, `xdr_type`, `validity` (the variant's own, else the entry's), `source` (its `source.kind`), `blob` (path), `sha256`, `bytes`, `decoded` (sidecar path, `null` when the bytes do not decode), `decoded_sha256`, and `focus` as in the manifest (§4.2) |

Paths are relative to the corpus root. Per-arm coverage is not repeated per entry (one ledger reaches hundreds of
arms); `xdrcheck-corpus coverage --arms --report FILE` lists the inputs that reach each arm. Typical queries:

```sh theme={null}
jq -r '.entries[] | select(.caps | index(27)) | .id' corpus/index.json                   # entries of CAP-27
jq -r '.entries[] | select(.validity == "malformed") | .id' corpus/index.json            # bytes that must not decode
jq -r '.entries[] | .variants[] | select(.network == "pubnet") | .blob' corpus/index.json # every pubnet blob
```

## 4. Entry fields

### 4.1 Top level

| Field | Req. | Meaning and rules |
| - | - | - |
| `schema` | yes | Constant `xcc.manifest.entry/v1` |
| `id` | yes | `<group>/<slug>`, lower case (§5). Must equal the file path under `corpus/manifest/` |
| `title` | yes | One line, 8 to 140 characters, plain language |
| `kind` | yes | `ledger` (one full `LedgerCloseMeta`), `xdr` (one standalone XDR value), `api` (an SDK-neutral call with an expected result, no blob), `strkey` (a text address vector), `spec` (a contract interface: a Wasm module or a bare `SCSpecEntry` stream, §9.4) |
| `caps` | yes | CAP numbers that introduced or changed the pattern, unique integers. May be empty only together with `caps_note` |
| `caps_note` | if `caps` is empty | Why there is no CAP: protocol-gated behaviour with no CAP (Protocol 29 shipped none), or a pure encoding rule. An empty `caps` with a note is the tag, not a missing one: the entries of the `classic`, `ledger`, `limits`, `strkey`, `xdr-strict`, `xdr-json` and `protocol-NN` groups describe behaviour that predates CAPs, shipped in a protocol upgrade without a CAP, or is an encoding rule, so no CAP number exists to put there. They are still tagged with their protocol (`protocol.introduced`) and counted under their group's row of `COVERAGE.md`. In corpus 30.0.0-dev that is 143 entries: `classic` 97, `strkey` 15, `ledger` 11, `xdr-strict` 11, `limits` 2, `protocol-15` 2, `protocol-01` 1, `protocol-02` 1, `protocol-09` 1, `protocol-29` 1, `xdr-json` 1 (the header of `COVERAGE.md` gives the current counts) |
| `protocol.introduced` | yes | First protocol at which stellar-core can emit the pattern. Taken from the XDR definitions and stellar-core at a tag, never from CAP prose |
| `protocol.removed` | no | First protocol at which stellar-core can no longer emit it (for example inflation) |
| `synthetic` | yes | `true` if stellar-core did not emit the bytes (hand-crafted). Bytes imported from core goldens, emitted by a local stellar-core, captured from network history, or cut contiguously out of such bytes are not synthetic |
| `negative` | no | `true` if a correct reader must reject the input. Implies `synthetic: true` (the schema enforces it). Default `false`. For kinds `ledger`, `xdr`, `spec` and `strkey` it is `true` exactly when `validity` is `malformed` or `invalid` |
| `validity` | yes\* | What a correct reader does with the input: `valid`, `malformed`, `invalid` or `acceptable` (§9.5) |
| `flags` | no | Bug classes the input exercises, from a closed list (§9.5); at least one when present |
| `shapes` | no | Tags for the structural variants the entry exercises; free vocabulary, kebab case, unique |
| `why` | yes | Why the pattern trips readers, in one or two sentences (at least 20 characters) |
| `fields` | no | Rows of the guide's field-by-field table that the entry demonstrates, split by the row's verdict: `validated`, `partially_validated`, `passed_through`. Row IDs have the form `VF-NN` or `VF-NNa` (pattern `^VF-[0-9]{2,3}[a-z]?$`). The status an entry lists a row under must equal the row's status in the field table (§11, check 7) |
| `variants` | for `ledger` and `xdr` | The bytes per network and protocol (§4.2). At least one |
| `api` | for `api` | The call (§9.1) |
| `strkey` | for `strkey` | The text vector (§9.2) |
| `expect` | yes | Expected facts shared by all variants (§6) |
| `conformance.levels` | no | Which of `L0`–`L4` apply (§10) |
| `conformance.known_divergences` | no | Readers known to get this entry wrong, by version range (§7) |
| `replay` | no | How the replay harness serves the entry (§8) |
| `related` | no | URLs: issues, pull requests, CAP sections, advisories |
| `added_in` | no | Corpus version (`MAJOR.MINOR.PATCH`) that first shipped the entry |
| `notes` | no | Free-text remarks for people; never read by a check |
| `reference` | no | What makes the expected value authoritative: `network` (bytes or behaviour of stellar-core), `protocol-rule` (a CAP or the XDR definitions), `spec` (a SEP, RFC 4506). The conformance report uses it to say what a divergence diverges *from* |
| `mirrors` | no | A recorded golden mirror run, provenance only (§4.7) |
| `core_behaviour` | no (negative entries) | What stellar-core itself does with a negative input: `accepts` (boolean, required), `value` (what it decodes the input to, when it accepts), `observed` (`executed` or `source-reading`, required), `evidence`. Where stellar-core is lenient and SDKs reject, the entry records it instead of pretending there is one right answer (§9.3); with `accepts: true` the stellar-core conformance column's acceptance is that column's expected outcome ([conformance-protocol.md](https://docs.xdrcheck.dev/reference/driver-protocol.md#conformance-rules) §4) |

\* The schema leaves `validity` optional so that an entry written before it existed still validates; `xdrcheck-corpus
verify` and `make repo-checks` require it on every corpus entry.

### 4.2 `variants[]`

A variant is the pattern's bytes on one network at one protocol. Its key is `(network, protocol)`; two variants of
one entry must not share a key.

| Field | Req. | Meaning and rules |
| - | - | - |
| `network` | yes | Passphrase family: `pubnet`, `testnet`, `core-test` (stellar-core's fixed unit-test passphrase `(V) (;,,;) (V)`), `none` (passphrase-independent values such as a bare `ScVal`). It names the passphrase, not the origin: a local standalone chain run on the public passphrase is `pubnet` with `source.kind: local-core` |
| `passphrase` | yes | The exact network passphrase; the empty string for `none` |
| `protocol` | yes | Protocol applied when stellar-core emitted the bytes |
| `header_protocol` | no | Ledger-header protocol, when it differs from the applied one. On an upgrade ledger the header already shows protocol N while its transactions were applied under N−1 ("upgrades are applied last" in the XDR definitions); the capture `corpus/objects/pubnet/30191538/capture.json` is such a ledger: header protocol 13, all 450 envelopes of the pre-Protocol-13 `tx_v0` form |
| `ledger_seq` | no | Real sequence number of the ledger |
| `xdr_type` | yes | Type name in the pinned XDR definitions: `LedgerCloseMeta`, `TransactionEnvelope`, `ScVal`, `LedgerEntry`, … |
| `validity` | no | This variant's validity (§9.5) when it differs from the entry's; absent means the entry's |
| `framing` | no | How the blob holds the value: `none` (default; the blob is one value of `xdr_type`) or `record-marked` (the blob is an RFC 5531 record-marked stream and the value is record `frame_index`). Only negative `xdr` entries may use `record-marked` — the record-mark error vectors (§9.3); the schema enforces it |
| `frame_index` | no | With `record-marked`: the zero-based record that holds the value (default 0). Requires `framing: "record-marked"` |
| `requires` | yes | XDR features of the pinned definitions that the bytes use and older definitions lack, so a reader built on older definitions cannot decode them: `stellar_value_signed_ms` (a `StellarValue` ext arm with a millisecond close time, arm 3 or 4, Protocol 30, CAP-88), `sc_address_type_muxed_contract` (an `SCAddress` of type `SC_ADDRESS_TYPE_MUXED_CONTRACT`, CAP-84); `[]` when none. Mandatory on every variant, so a consumer never has to guess from the protocol number. For a positive variant `verify` derives the list from the sidecar and fails unless it equals the stored one; a negative variant, whose bytes do not decode, states it by hand (`[]` unless its defect sits behind such a feature). `xdrcheck-corpus render` fills it. The conformance runner reads it to tell an SDK that cannot reach the value from one that gets it wrong |
| `json_roundtrip` | no | A declared exception to the JSON half of the round trip: `{"skip": true, "reason": "…"}` (both required) when the SEP-51 JSON of these bytes does not reproduce them, for example a signed-payload signer with an empty payload, whose strkey the pinned library does not parse back. The bytes must still round-trip and the sidecar is still rendered; only JSON → XDR is skipped, and `verify` fails the exception once the JSON round trip succeeds (it is stale). Not allowed on negative entries |
| `xdr_definitions` | no | Tag or commit of the XDR definitions the type name refers to |
| `blob` | yes | `sha256` (required), `bytes` (required, length), `path` (relative to the corpus root; omitted for bulk-tier entries fetched by hash). §4.5 |
| `slice_of` | no | For an `xdr` entry cut out of a `ledger` entry: `entry` (the parent's ID, required), `path` (JSON Pointer into the parent's decoded form, required), `byte_offset` |
| `decoded` | no\* | Path of the decoded sidecar, the SEP-51 XDR-JSON rendering the oracle produced: `decoded/<aa>/<blob sha256>.json.zst`, shared by every variant with that blob (§2) |
| `decoded_sha256` | no\* | sha256 of the sidecar's **uncompressed** JSON, so a tampered or regenerated sidecar is detected whatever the zstd build |
| `decoded_by` | no\* | Oracle library and version that produced the sidecar |
| `source` | yes | Provenance (§4.4) |
| `focus` | no | Where in a ledger the pattern is, so several entries can share one blob: `tx_index` (zero-based **apply order**: the index into the ledger's transaction processing list, which is the order of results and meta — not the position in the transaction set), `tx_hash`, `op_index`, `path` (JSON Pointer into the decoded form, so its transaction index counts in **transaction-set order**). The two indexes usually differ; see "Reading `focus`" below |
| `meta` | no\* | Meta versions and flag profile (§4.3) |
| `derived` | no | Passphrase- or run-dependent values (§4.6), and `derived.l1`, the values an SDK's object layer reads from the focus (§10.1) |
| `notes` | no | Remarks specific to this variant |

\* The schema leaves `decoded`, `decoded_sha256` and `decoded_by` optional, but `xdrcheck-corpus verify` requires them on
every non-negative `ledger` and `xdr` variant. It also requires `meta.profile` and both meta versions on every
`ledger` variant, because one ledger has several valid encodings (§4.3); a ledger with no transactions has no
`TransactionMeta`, so there `meta.transaction_meta_version` is left out.

Excerpt of `cap-0038/pool-issuers-order-by-bytes-not-strkey`: the focus transaction is third in apply order but
fourth in the transaction set, and the two indexes are not interchangeable:

```json theme={null}
"focus": {
  "tx_index": 2,
  "tx_hash": "0126748091930959a3aefac9296e1773b947f964a9b73f37ce856c4df32d346f",
  "op_index": 2,
  "path": "/v2/tx_set/v1/phases/0/v0/0/txset_comp_txs_maybe_discounted_fee/txs/3/tx/tx/operations/2/body/change_trust/line/pool_share/liquidity_pool_constant_product"
}
```

**Reading `focus`.** A ledger lists its transactions twice, in two orders. The transaction set
(`…/tx_set/…/txs/N` in the decoded form) is in **set order**: the order the set stores them in (for a generalized
set, phase by phase and component by component). The processing list (`…/tx_processing/N`), its results and its meta are in **apply order**:
the order stellar-core applied them. `focus.tx_index` and every `tx_index` in `expect` count in apply order;
`focus.path` and every `expect.values[].path` are JSON Pointers into the decoded form, so a number after `txs/` in
them counts in set order, and a number after `tx_processing/` in apply order. `cap-0027/muxed-source-id-zero` has
`"tx_index": 135` and `"path": "/v0/tx_set/txs/187/tx/tx/source_account"`: the same transaction, 136th applied and
188th in the set. To go from one to the other, match on the hash: `focus.tx_hash` is the hash of the envelope at
`path` and of the result at `tx_processing/<tx_index>` (`derived.tx_hashes` lists every hash in apply order).

### 4.3 `meta`: versions and flag profile

| Field | Meaning |
| - | - |
| `ledger_close_meta_version` | The `LedgerCloseMeta` arm (0, 1, 2, …) |
| `transaction_meta_version` | The `TransactionMeta` arm of the transactions in the blob (of the focus transaction when the variant has one). Left out for a ledger with no transactions, which has no `TransactionMeta` to read it from; such an entry states `expect.ledger.transactions: 0`, and a value stated there is an error |
| `core_meta_flags` | stellar-core configuration flags that change what meta is emitted |
| `profile` | Which flag set produced the bytes: `lake`, `golden-test` or `custom` |
| `golden_test` | Required when `profile` is `golden-test`: `core_tag`, `test_name` (the human test name from the golden index, not its hash), `flags_source` (source file and lines at the tag where the test sets its flags, for example `src/transactions/test/InvokeHostFunctionTests.cpp:219-225`) |

Profiles:

* `lake` — the flag set that the objects of the public data lake (written by Galexie) have: classic and fee events
  on, Soroban meta extension v1.
* `golden-test` — the flag set of one named stellar-core golden test, read from that test's source. There is no
  single stellar-core default: each test sets its own flags, so the test must be named.
* `custom` — any other set, listed in `core_meta_flags`.

Why the flags matter: classic-operation events and fee events exist only when the node ran with
`EMIT_CLASSIC_EVENTS` (Protocol 23 and later) or `BACKFILL_STELLAR_ASSET_EVENTS`; diagnostic events only with
`ENABLE_SOROBAN_DIAGNOSTIC_EVENTS`. Two honest emissions of the same ledger can therefore differ, and the manifest
must say which one a blob is. The golden-mirror runs in `evidence/golden-mirror/` measured it: the same Stellar Asset
Contract `trust` transaction differs from the golden in one path under the `lake` flags (the Soroban meta extension
arm) and in three under diagnostics-only flags (two transaction-level fee events missing), and in none under the
test's own flags. For `history` variants the lake does not record the flags; `source.written_by` records the
stellar-core version that wrote the object instead (§4.4).

### 4.4 `source`: six kinds

`source` is a tagged record; `kind` selects one of six shapes, each closed (no other keys allowed).

| `kind` | Required | Optional | Reproduce by |
| - | - | - | - |
| `core-golden` | `core_tag`, `core_commit`, `tier` (`current` or `next`), `file` (path inside the stellar-core repository), `file_sha256`, `frame_index`, `test_name` | `rng_seed` | `git show <core_tag>:<file>` in stellar-core, split the record marks, take record `frame_index` |
| `local-core` | `core_version`, `core_commit`, `scenario`, `step`, `config_sha256`, `reproducibility`, and at least one of `core_image_digest` (`sha256:<hex>`), `core_package` (`url`, `sha256`), `core_binary_sha256` | `scenario_sha256`, `close_time` (decimal string), `stream_sha256`, `frame_index`, `generated_by`, `soroban_resources`, `inputs[]` (`name`, `sha256`, optional `origin`), `regenerate`, `submission` (`endpoint`, `status`, `envelope_entry`), `core_role` | Run the `regenerate` command; compare as `reproducibility` says |
| `history` | `store`, `key`, `object_sha256`, `captured_at`, `written_by`, `regenerated` | `object_path`, `object_bytes`, `decompressed_sha256`, `decompressed_bytes`, `batch_index`, `blob_offset`, `object_metadata`, `refetch`, `perishable`, `selected_by` (`census`, `query_id`) | Run `refetch`, decompress, cut at `blob_offset` (§4.5) |
| `history-archive` | `store`, `object`, `object_sha256`, `byte_offset` | `refetch`, `perishable`, `file_kind` (`bucket` or `scp`) | Fetch the archive object and cut the record at `byte_offset` (bucket entries — the shape behind [henyey#3941](https://github.com/stellar-experimental/henyey/issues/3941)) |
| `synthetic` | `recipe` (how the bytes were built: a base entry plus an edit, or a literal construction), `reason` (why stellar-core cannot or would not emit them) | `base_entry` | Apply the recipe (schema `corpus/schema/recipe.schema.json`) |
| `contract-code` (`spec` entries) | `network`, `wasm_hash`, `upload_ledger`, `fetched_via`, `captured_at` | `perishable` | Read the CONTRACT\_CODE entry `wasm_hash` from the network (`getLedgerEntries`); its code is the blob |

Rules and meanings:

* `core-golden`: `frame_index` is the zero-based index of the record-marked `LedgerCloseMeta` in the golden file;
  `test_name` is the human-readable name from the golden index.
* `local-core`: `scenario` is the scenario file, `step` the step that produced this ledger, `config_sha256` the hash
  of the stellar-core configuration, `stream_sha256` the hash of the complete record-marked meta stream of the
  canonical run, `frame_index` this ledger's record in it, `generated_by` the tool and version that drove
  stellar-core, `inputs[]` other pinned inputs such as Soroban settings-upgrade sets.
* `reproducibility` is `byte-identical` or `normalised-identical`. Every local-core variant so far is
  `normalised-identical`: raw meta bytes are not byte-reproducible, because stellar-core writes timing values into
  diagnostic events and does not fix the order of ledger-entry changes. Two emissions are normalised-identical when
  they are byte-equal after the normalisation stellar-core's own `--check-lcm` applies (sort each ledger-entry
  change list in the places core sorts it, zero the `core_metrics` / `invoke_time_nsecs` diagnostic value). Observed
  in `evidence/local-core/out/compare.txt`: over three runs per passphrase, raw hashes differed on many ledgers
  while normalised hashes and ledger header hashes were identical on all 30.
* `submission` (optional) marks bytes that are stellar-core's answer to a submission, not ledger output: the refused
  `TransactionResult` its `/tx` endpoint returned (`endpoint: tx`, the `status` it answered with) for the envelope
  stored as the entry `envelope_entry`. `core_role` (optional; absent means `release`) names the binary that emitted
  the bytes: the pinned `release`, a `buildtests` build with test hooks, a `vnext` next-protocol build, or an
  `old-core` release replaying history. Both are optional and change no existing entry.
* `soroban_resources`: `not-applicable`, `declared` (the envelope's footprint and resource numbers were chosen by
  the scenario author, not produced by simulation) or `simulated`. The `trust` entry is `declared`, and its fee
  refund reflects that.
* `history`: `store` is the public SEP-54 store (for example `s3://aws-public-blockchain/v1.1/stellar/ledgers/pubnet`),
  `key` the object key, `object_sha256` the hash of the object as stored (compressed), `batch_index` the ledger's
  index inside the batch, `object_metadata` the store's user metadata exactly as returned.
* `written_by` (the stellar-core and exporter versions in the object's metadata) and `regenerated` are **required**
  for lake entries. `regenerated: true` means the object was written by a stellar-core newer than the ledger's
  protocol era: the public lake was rewritten by a recent stellar-core, so even Protocol 1–22 ledgers there carry
  `TransactionMeta` v4 with backfilled events (see the `transaction_meta_versions` of the old pubnet captures under
  `corpus/objects/pubnet/`). Such an entry is real stellar-core output for that ledger, but not the bytes a node
  emitted at the time.
* `selected_by` (optional) records that a census query chose the ledger: `census` is the census file, `query_id`
  the query. A `history-archive` source's `file_kind` (optional; absent means `bucket`) says whether the record is
  cut from a bucket file or an SCP history file.
* `object_path` names the vendored original lake object (`.xdr.zst`), kept so the harness can serve a history entry
  byte-identical to the public lake, at its original key.
* `perishable: true` marks sources that will disappear. Testnet is reset on a published schedule (next on
  2026-12-16); after a reset the vendored blob is the only copy.

Excerpt of `cap-0040/signed-payload-signer-added`, a `history` source:

```json theme={null}
"source": {
  "kind": "history",
  "store": "s3://aws-public-blockchain/v1.1/stellar/ledgers/testnet/2025-12-18",
  "key": "FFBC9DFF--4416000-4479999/FFBC4A92--4437357.xdr.zst",
  "object_sha256": "24fc6077579e6058512e35401c728288898e6c4fd550b8f26e0a5079aae4001b",
  "decompressed_sha256": "e9fe329be8a0c0a035db0dcbf0a5a01fdb99b9b14237cdc1a9fddae8a56c1846",
  "decompressed_bytes": 58268,
  "batch_index": 0,
  "blob_offset": 12,
  "written_by": "stellar-core 28.0.1 (947aad8413c189d85504acf72207e85eeda9b021); exporter 72ee2a9",
  "perishable": true,
  "regenerated": false
}
```

### 4.5 Blobs, and how a blob relates to its source

A blob is the exact XDR encoding of **one value** of `xdr_type`: no record mark, no compression, no base64, no batch
wrapper. Its file name is its sha256. The one exception is a negative variant with `framing: "record-marked"`: its
blob is a record-marked stream (4-byte marks, as stellar-core writes its meta streams), because the defect it pins
is in the marks themselves.

| Source | The blob is |
| - | - |
| `core-golden` | The payload of record `frame_index` of the golden file, without the 4-byte record mark |
| `local-core` | The payload of record `frame_index` of the run's meta stream, without the record mark |
| `history` | Bytes `[blob_offset, blob_offset + blob.bytes)` of the **decompressed** lake object |
| `history-archive` | The record at `byte_offset` of the archive object |
| `synthetic` | The bytes the recipe yields |

A lake object is a zstd-compressed `LedgerCloseMetaBatch \{ uint32 startSequence; uint32 endSequence;
LedgerCloseMeta ledgerCloseMetas&lt;>; \}`. With one ledger per batch (the public lake's layout) the blob starts at
offset 12 (two sequence numbers and the array length) and runs to the end. So: `object_sha256` → decompress →
`decompressed_sha256` → drop 12 bytes → `blob.sha256`. Both `history` entries satisfy it, which anyone can check
from the vendored objects:

```sh theme={null}
O=corpus/objects/testnet/4437357/FFBC4A92--4437357.xdr.zst
sha256sum "$O"                          # 24fc6077…e4001b = source.object_sha256
zstd -dc "$O" | sha256sum               # e9fe329b…1c1846 = source.decompressed_sha256
zstd -dc "$O" | tail -c +13 | sha256sum # 582e694b…7c4e0e = blob.sha256
```

(For `corpus/objects/testnet/5521432/FFABBFE7--5521432.xdr.zst` the last line gives `85eddc3b…722c08`, the blob of
`cap-0038/pool-issuers-order-by-bytes-not-strkey`.) The replay harness reverses the same step when it serves a
ledger (§8.3).

Sharing: several entries may name the same blob with different `focus` values. Entry bytes are never edited to
isolate a pattern; a smaller value cut out of a ledger is an `xdr` entry with `slice_of`, not an edit.

### 4.6 `derived` and `${derived.*}` substitution

`derived` holds what depends on the network passphrase or on one particular run, so that one `expect` block can
serve every variant. Measured on the 30-ledger twin runs of `evidence/local-core/` (`evidence/local-core/out/twin-diff.txt`):
**different** between testnet- and public-passphrase twins are every ledger, transaction-set and transaction hash,
every signature, every contract ID including the native asset contract's, contract-data keys and TTL key hashes;
**equal** are account keys derived from labels, muxed IDs, sequence numbers, liquidity-pool IDs, signer strkeys,
amounts, result codes, fees, close times, ledger sequences and blob lengths.

Reserved names, typed by the schema: `ledger_hash` (sha256 hex), `tx_hash` (the focus transaction's hash on this
network), `tx_hashes` (all transactions, apply order), `contracts` (name → contract address), `header` (below).
Other names are free; their values are strings, arrays or objects.

`header` holds values of the variant's ledger header as decimal strings: `ledger_version`, `total_coins`,
`fee_pool`, `base_fee`, `base_reserve` and `max_tx_set_size` (the schema allows no other key). `xdrcheck-corpus gen`
writes all six on every ledger variant, and `verify` checks each one present against the header in the blob
(`pinpoints`, §11 item 4). It lets one `expect` pin a header field that differs between variants. The Protocol 24
upgrade adds 31,879,035 stroops to the fee pool on the public passphrase only, so
`cap-0076/fee-pool-adjustment-on-public-passphrase` says `"equals": "${derived.header.fee_pool}"` and its variants
hold `"fee_pool": "41644474"` (public) and `"9765439"` (testnet). Substitution is textual (below), so a token
matches a header value that the decoded form holds as a string — the 64-bit `total_coins` and `fee_pool`; the
32-bit fields are JSON numbers there and are compared as literals.

Substitution: any **string** inside `expect` (and inside `api.input`) may contain `${derived.<path>}`, where `<path>`
is dot-separated keys or array indexes into the variant's `derived`. A consumer resolves the tokens per variant
before comparing. A token with no value in a variant is a manifest error. Substitution is textual, single-pass, and
applies to string values only (never to keys). The two fields typed as decimals, `expect.transactions[].fee_charged`
and `expect.movements[].amount`, accept either a decimal string or exactly one token.

Excerpt of `cap-0073/sac-trust-creates-trustline`, whose Protocol 28 and Protocol 30 variants charged different fees
and run under different contract IDs:

```json theme={null}
"derived": {
  "tx_hash": "8764718b70f14a572c9beb660460ba0485da1c7aa6f6960a8851f951e6be44e5",
  "contracts": {"sac_usdc": "CDIMMH4CNFBSU72EZCX6QVJVZ74APF4BESMFS47DELY6E2ZT2HW5BIF6", "native_sac": "…"},
  "accounts": {"owner": "GBBHMRREN277K2C32QTUCYXWE4HFP6FBRT7NVS74UVP24VUCWZ7CNYI6", "issuer": "…"},
  "assets": {"usdc": "USDC:GD7SJCVLFVJEJZ6LU4TV4PRZ34SPS7JAGX7CGNHNQH4S4QA7AJVSI43N"},
  "fee_charged": "74541"
}
```

and in the shared `expect`: `"hash": "${derived.tx_hash}"`, `"fee_charged": "${derived.fee_charged}"` (74541 at
Protocol 28, 34800 at Protocol 30), `"asset": "${derived.assets.usdc}"`.

### 4.7 The golden mirror and the `mirrors` record

**What the golden-mirror check does.** For every `local-core` variant, the structural skeleton of the variant's own focus transaction,
computed from its blob, is compared with the skeleton of one transaction of stellar-core's golden set at the pinned
tag (`corpus.json` `tiers.bulk`: the files listed in its `file_index`, read from the golden cache), computed from
that golden file. Nothing recorded is trusted: both skeletons are recomputed on every run.

The skeleton of a transaction keeps its shape and drops its values: every union arm name, enum value, boolean, array
length and `Symbol` value is kept, strkey-rendered addresses keep their version letter (`G`, `C`, `M`, `W`, …), and
every other leaf becomes its type name; the value is normalised first as in §4.4. It covers the envelope, result,
fee processing, the whole apply meta and post-apply fee processing of the focus transaction
(`xdrcheck-corpus skeleton <entry>` prints it).

Local-core variants are written under the lake profile and each golden under its own test's meta flags, so the golden-mirror check
compares the **profile-free** skeleton: from both sides it removes exactly the parts that exist only because a
meta flag is set (stellar-core v30.0.0 `src/transactions/EventManager.cpp` and `TransactionMeta.cpp`):

| Removed | Flag |
| - | - |
| `diagnostic_events` (transaction level and inside `soroban_meta`) | `ENABLE_SOROBAN_DIAGNOSTIC_EVENTS` |
| transaction-level `events` (fee events) and the `events` of every operation that is not a Soroban operation | `EMIT_CLASSIC_EVENTS` (`BACKFILL_STELLAR_ASSET_EVENTS` before Protocol 23) |
| `soroban_meta.ext` | `EMIT_SOROBAN_TRANSACTION_META_EXT_V1` |

Everything else stays, with no masks: envelope (preconditions, signatures, footprints), result, every ledger-entry
change, a Soroban operation's contract events and return value.

**What the skeleton does not see.** The skeleton masks every value, including the presence of an optional integer
(an operation's `set_flags` and `high_threshold` look alike whether set or not), flag and threshold values, and which
fields of an updated entry changed. Two transactions with equal skeletons can therefore apply different patterns: an
`AllowTrust` to "authorized to maintain liabilities" and one to "authorized", a no-op `BumpSequence` and a real one.
The golden-mirror check therefore compares a second measure as well, the **reduced shape tokens**: the tokens the mainnet scan's emitter
(`xdrcheck-corpus scan`, grammar `xcc.shape/v1`, rules `crates/xdrcheck-corpus/data/scan-rules-v1.toml`) writes for each
component of the transaction (envelope, authorization entries, result, fee processing, transaction meta, and one per
operation: its body, result, ledger-entry changes and contract events). They record optional presence, the set of
fields each updated entry changed, flag transitions (`flags=1>2`), operation-versus-effect relations, event signatures
and length classes. From both sides the golden-mirror check removes:

| Removed | Why |
| - | - |
| type-level tokens (kind `T`) | they record which types occur anywhere, including inside diagnostic events, so they cannot be attributed to a place |
| tokens of transaction-level and diagnostic events, `sorobanMeta.ext`, and the event signatures of operations that are not Soroban operations | the same meta-flag parts the profile-free skeleton removes (a v3 meta's `sorobanMeta.events` are contract events and stay) |
| `seqLedger` and `seqTime` in the list of an account's changed fields | stellar-core writes both on every sequence-number bump; whether they appear as changed depends only on whether the previous bump was in a ledger with another sequence number or close time (stellar-core's tests close ledgers at a fixed time), a property of the run, not of the transaction |

Nothing else is masked.

**What "agree" means, and what it does not.** A local-core entry and a golden are written by the same stellar-core
release but by different runs (other accounts, keys, ledger numbers, close times, setup and meta flags), so their bytes
are never equal and the golden-mirror check never compares bytes. It proves, for each mapped entry, that stellar-core's own test suite
emitted a transaction with the same profile-free skeleton and the same reduced shape tokens as the entry (the entry
matches a golden transaction); that is, the entry's shape is one stellar-core itself produces under `--check-lcm`.
Only these entries count as mapped. The operation tier is reported separately: for an entry that matches no
golden transaction it states that every operation has a golden operation of the same shape, which is not agreement of
the entry, and such an entry counts as unmapped. It does
not prove that values (amounts, keys, hashes, fees, ledger numbers) agree, and it says nothing about entries no golden
covers. Byte equality is checked only where both sides are the same bytes: the `ag1` check, the imported `core-golden`
entries against the named frame of the golden file at the pinned tag.

**The mapping: `corpus/mirrors.json`.** `xdrcheck-corpus verify --checks ag4 --write-mirrors` searches the whole golden set
and writes:

* `mapped` (the transaction tier): the local-core variants whose focus transaction has both the profile-free skeleton and
  the reduced shape tokens of a golden transaction, each with its golden (`file`, `frame_index`, `tx_index`: the first
  match in index order), and the entry's variants without one;
* `operations` (the operation tier), for the other entries: the variants every distinct operation of whose focus
  transaction has a golden operation of the same reduced shape, each operation shape (`op_type`, `shape`) with the golden
  transaction that holds it. This tier compares operations only: it says nothing about the envelope (memo,
  preconditions, signatures), fee processing or transaction-level meta, which is often where such an entry's pattern
  lies;
* `unmapped`: every local-core entry without a golden transaction, with the reason `no golden transaction of this shape;
  every operation has a golden operation of the same shape` (listed under `operations`), `no golden covers this shape`,
  or `no transaction: a ledger-level pattern` for upgrade and empty ledgers;
* `golden_operations`: every reduced operation shape of the golden set (its operation type, result, first golden and
  number of golden transactions). `xdrcheck-corpus coverage` adds the reverse coverage from the corpus alone (no golden
  cache): for each shape, whether an entry's focus transaction has an operation of that shape, and of which source;
  `corpus/COVERAGE.md` ("Golden operation shapes") lists the golden shapes no entry holds and `corpus/coverage.json`
  counts them (`golden_operation_shapes*`).

`counts` gives the totals; `corpus/coverage.json` repeats them (`entries_local_core_with_golden_mirror`,
`entries_local_core_without_golden_mirror`, `entries_local_core_with_golden_operations_only`).

`verify --checks ag4` produces:

* one row per listed variant: in the transaction tier, its profile-free skeleton and reduced shape tokens equal its
  golden's (a failure lists the differing paths and tokens); in the operation tier, its distinct operation shapes are
  exactly the listed ones and each listed golden transaction has an operation of that shape;
* one failing row per unlisted variant that the search now finds a golden transaction or golden operations for (the
  list is out of date);
* on a whole-corpus run, a `mirrors.json` row (every local-core entry is listed exactly once, nothing else is, and
  `golden_operations` equals a fresh computation) and a `floor:ag4` row, which fails when there is no golden-mirror variant row or
  when fewer entries pass than either tier lists.

**The `mirrors` record** of a manifest entry documents a separate mirror run made with the named golden test's own
meta flags and setup. It is provenance: the golden-mirror check does not read it, and its recorded hashes are evidence, not a check.

| Field | Req. | Meaning |
| - | - | - |
| `core_golden` | yes | `core_tag`, `file`, `file_sha256`, `test_name`, `frame_index`, `tx_index` (all required) |
| `flags` | yes | Meta flags the golden's test runs with (those set to true) |
| `flags_source` | yes | Where in the test source the flags are set (file and lines at the tag) |
| `settings_overrides` | no | Network settings copied from the test because they change the meta (for example `min_persistent_ttl`) |
| `scenario` | no | Scenario file and step of the mirror run |
| `skeleton_sha256` | if executed | Skeleton hash of the golden's focus transaction when the run was made |
| `run_skeletons` | if executed | Skeleton hash of the mirror run per network, as recorded |
| `state` | yes | `executed` (hashes recorded) or `planned` (declared, not yet run) |
| `evidence` | no | Where the mirror run's artefacts are |

`cap-0073/sac-trust-creates-trustline` carries such a record against
`test-lcm-current/InvokeHostFunctionTests/4c437318f87437c5.xdr` frame 42 at stellar-core v30.0.0; the runs are in
`evidence/golden-mirror/` (`evidence/golden-mirror/out/summary.tsv`).

## 5. Entry IDs

`id = <group>/<slug>`, optionally `.<member>` for one vector of a family; the manifest file is
`corpus/manifest/<group>/<slug>.json`. An ID never encodes a network, a variant's protocol or a source: those are
variant properties, and the same pattern on another network or protocol is a variant, not a new entry. IDs are born
only in `corpus/plan.json` and are permanent: a shipped entry's bytes never change, and a correction is a new entry
whose predecessor gets `notes` pointing to it.

The grammar, the groups (`cap-NNNN`, `protocol-NN`, `classic`, `ledger`, `limits`, `xdr-strict`, `xdr-json`,
`strkey`), families and members, stability and how to request a new ID are in [`entry-ids.md`](#entry-ids), which
is authoritative.

## 6. Expected values and how they are matched

### 6.1 Three layers

1. **Bytes** — `variants[].blob`. Re-encoding a decoded value must reproduce them (level L0).
2. **Decoded** — `variants[].decoded`: the SEP-51 XDR-JSON the oracle emits at the pinned library version, stored
   exactly as emitted and compared **as a JSON value**, never as text (SEP-51 encoding is canonical, but decoding
   accepts several spellings). Every path in the manifest is an RFC 6901 JSON Pointer into this document.
3. **Semantic expectations** — `expect`, shared by all variants after `${derived.*}` substitution.

`expect.values[]` connects layers 2 and 3: pinpoints `{path, equals, note?}` (`path` and `equals` required; `equals`
is any JSON value). The oracle asserts each against the sidecar during `verify`; conformance drivers at L2 assert the
same paths against their own projection. These are hand-written, so they check the oracle independently of the fact
that it is built on the same library as one of the SDKs under test. Excerpt of
`cap-0038/pool-issuers-order-by-bytes-not-strkey`:

```json theme={null}
{
  "path": "/v2/tx_set/v1/phases/0/v0/0/txset_comp_txs_maybe_discounted_fee/txs/3/tx/tx/operations/2/body/change_trust/line/pool_share/liquidity_pool_constant_product/asset_a/credit_alphanum4/issuer",
  "equals": "GDRQL6EF772CANMYX55HXMU463OLAX46ZRCPCWS4KVL66ZS4BYA7OYDL",
  "note": "Raw key e305f885…: sorts first as bytes, although its strkey sorts after the other issuer's …"
}
```

**Key-selected pinpoints.** stellar-core writes an operation's ledger-entry changes from an unordered map
(`LedgerTxn::Impl::getChanges`), so the position of one entry's change in a change list differs between runs and
passphrases. A pinpoint can therefore name the array element by its ledger key instead of its index:
`select: {in, key, change?}`, where `in` is a JSON Pointer to an array of `LedgerEntryChange`, `LedgerEntry` or
`LedgerKey` values, `key` is the SEP-51 JSON of the `LedgerKey`, and `change` (one of `created`, `updated`,
`removed`, `state`, `restored`) picks the change type; `path` is then relative to the selected element. Exactly
one element must match: a change whose entry has the key (a `removed` change whose key equals it) and the given
type, a ledger entry with the key, or a key equal to it. An entry has a key when every field of the key's arm is a
field of the entry's `data` arm with the same value (a `config_setting` key matches the entry whose arm is its
`config_setting_id`). Without `change`, a key with both a `state` and an `updated` change in the list matches
twice and fails. Tokens are allowed in `in` and `key`:

```json theme={null}
{
  "select": {
    "in": "/v2/tx_processing/0/tx_apply_processing/v4/operations/0/changes",
    "key": {"account": {"account_id": "${derived.accounts.P}"}},
    "change": "updated"
  },
  "path": "/updated/data/account/seq_num",
  "equals": "55834574848"
}
```

`verify` resolves the selection in each variant's sidecar before comparing; the conformance orchestrator resolves
it per variant when it loads the corpus, so a driver receives (and the verdict compares at) the plain pointer
`/v2/…/changes/<i>/updated/data/account/seq_num`.

`expect.reject` belongs to negative entries (§9.3); `expect.native` to level L3 (§6.9).

### 6.2 Whole-ledger receipts: `expect.ledger` and `expect.transactions`

`expect.ledger` counts, for the **whole ledger** (TransactionMeta v4 definitions):

| Count | Definition |
| - | - |
| `transactions` | Length of the transaction processing list |
| `operations` | Operations in the envelopes of those transactions (the inner transaction's for fee bumps). A failed transaction's operations count although it has no operation meta |
| `events` | Consensus events: transaction-level plus operation-level events (contract events included). Diagnostic events are never counted. For TransactionMeta v3 the events are those in the Soroban meta |
| `entry_changes` | All ledger-entry changes: fee processing, changes before and after, operation changes, post-apply fee processing, upgrade processing |

Because classic and fee events depend on node flags (§4.3), `events` is a property of the blob, not of the abstract
ledger. Each counter an adapter provides must equal the expected one.

`expect.transactions[]`, also whole-ledger: `index` (apply order, required), `hash`, `successful` (required),
`result_code` (the transaction result arm as XDR-JSON names it: `tx_success`, `tx_failed`,
`tx_fee_bump_inner_failed`, …), `operation_result_codes` (one per operation, `<operation>.<code>` in XDR-JSON names,
for example `set_options.success`), `fee_charged` (decimal string or `${derived.…}` token), and for fee bumps
`inner_hash`, `inner_successful`, `inner_result_code`. Listing every transaction with its hash and `successful` lets
the harness detect an indexer that silently skips failed transactions; `cap-0038/pool-issuers-order-by-bytes-not-strkey`
lists all 19, three of them `tx_failed`. A reader's transaction is found by hash: an absent hash is `missing`; each of
`successful`, `result_code`, `operation_result_codes` and `fee_charged` must be equal where the reader holds the
field, otherwise `wrong`. Adapters map their indexer's own result label to these names through a fixed table (the
wallet-backend indexer stores `TransactionResultCodeTxSuccess`, as its transcripts in
`evidence/wallet-backend-replay/` show); the observation carries the XDR-JSON name.

### 6.3 Scope and identity

**Transaction scope.**

* Apart from the receipts of §6.2, every fact belongs to one **transaction**: the variant's focus transaction
  (`focus.tx_hash`), or, when an item carries its own `tx_index`, the transaction at that index (resolved to a hash
  through `expect.transactions[].hash`). Facts are located by transaction hash. What a reader holds for *other*
  transactions of the same ledger never affects an entry's result.
* A reader's fact that carries no transaction locator (an indexer that cannot attribute a row to a transaction) is
  in scope only when the ledger has a single transaction. Otherwise it is listed as unattributed evidence and
  neither satisfies nor violates anything.
* Within the transaction, two groups of facts are **ambient** — every transaction causes them whatever its
  operations do: the fee (movement kinds `fee` and `fee_refund`; state-change kind `balance_changed` when a reader
  models balances as state changes) and the sequence-number bump (state-change kind `sequence_bumped`). TTL
  extensions (`ttl_extended`) are ambient too: the Soroban host extends the TTL of entries a call accesses whatever
  the call is for. Ambient facts satisfy an expectation that lists them, and are **never counted as extras**.

**Identity.**

* An account is identified by its **base** address (`G…` account, `C…` contract, `B…` claimable balance, `L…`
  liquidity pool). A muxed ID is extra routing information, never a different account (§6.5).
* `asset` is `native`, `CODE:ISSUER`, `liquidity_pool:<hex pool id>`, or a contract address. A classic asset and its
  Stellar Asset Contract address under the run's network passphrase are **the same asset**: the consumer computes
  the contract ID from the asset and the network ID itself and accepts either form (the wallet-backend indexer, for
  example, stores the contract address in its token column). Where an entry gives that address under
  `derived.contracts`, `verify` has checked it against the computed one. A contract address that is not the
  computed address of the expected asset is a different asset, whatever its events claim (§6.7, M-7).

### 6.4 Presence, extras and exactness

Every comparison yields one **fact result**: `ok`, `missing`, `wrong`, `forbidden_present` or `not_applicable`.

**Comparison is exact everywhere.** Amounts, IDs and counts are compared as decimal strings or integers: no
tolerance, no rounding, no case folding, no prefix matching. **Never compared:** a reader's own row identifiers,
ordering columns and operation identifiers, and any `<key>_as_stored` value (§6.6).

**Presence.**

* A listed item is **required**: a reader that models its kind must hold a matching fact. No candidate → `missing`.
* An item with `only_if: <modelling choice>` is required only of readers whose adapter declares that choice in its
  `describe` answer (`modelling` in `corpus/schema/adapter-protocol.schema.json`). For other readers it cannot be
  `missing`, and a matching fact they report anyway is allowed. The one choice defined in v1 is
  `initial_authorization_separate`: the reader records the authorisation state a trustline is created with as its
  own change, beside the creation.
* Facts of a kind or sub-kind the adapter does not model are `not_applicable` (§6.10).
* An item marked `unverified: "<reason>"` (a `participants.must_include` account, a `state_changes` item or a
  `movements` item) states something the reference extractor cannot derive from the bytes (§6.11), for example a
  modelling detail no ledger field carries. The author keeps it as documentation; it is `not_applicable` for every
  reader, and the facts it describes still count as accounted under the exactness flags.

**Extras.** A reader may hold more than an entry asserts. Extra facts are ignored unless they hit a must-not fact
(`participants.must_not_include` → `forbidden_present`; a movement with `count: 0` → `wrong`) or fall inside an
exactness scope:

| Flag | Scope | What counts as an extra (→ `wrong`) | What never counts |
| - | - | - | - |
| `participants.exact` | participants of the focus transaction | any participant whose base address is not in `must_include` | — |
| `state_changes_exact` | operation-level state changes of the focus transaction | any state change in scope that matches no listed item | ambient kinds (`balance_changed`, `sequence_bumped`, `ttl_extended`); a fact matching an `only_if` item; kinds the adapter does not model |
| `movements_exact` | value movements of the focus transaction | any movement in scope that matches no listed item, or more records than `count` | `fee`, `fee_refund` |

**Must-not facts need the transaction.** A `must_not_include` item or a `count: 0` movement also holds for a
reader that holds nothing at all. Such a fact is therefore `ok` only when the reader positively holds the
transaction (it is in the reader's transaction list, or some fact the reader provides is located in it); otherwise
it is `not_applicable`. A hit is `forbidden_present` or `wrong` either way. An entry passes only when at least one
fact that is not a must-not fact is `ok`.

All three default to `false`. The exactness flags are the general must-not mechanism ("this transaction created one
trustline and nothing else"). They are not a statement about fees: an indexer that stores the fee as a balance row
passes an entry whose `state_changes_exact` is true. The wallet-backend indexer at its fixed commits stores a fee
debit and an authorisation row beside the expected trustline creation (rows in `evidence/wallet-backend-731/`); under
these rules the fee row is ambient, the authorisation row matches the `only_if` item, and nothing is left over, so it
passes `cap-0073/sac-trust-creates-trustline`.

### 6.5 Participants

`expect.participants` says who the ledger meta shows was affected. Envelope-only claims are never participants.
It has `must_include` (accounts), `must_not_include` (`{address, because}`, both required) and `exact`.

An account is `{address, muxed_id?, on_chain_form?, roles?, unverified?}`:

* `address` (required) is the **base** address.
* `muxed_id` is a decimal string; `on_chain_form` is the address exactly as its on-chain form renders (`M…` or
  `W…` when muxed).
* `roles` explains why the account is a participant. The vocabulary is open (new values are a minor change):

  | Role | The address is |
  | - | - |
  | `source` | the account whose sequence number the transaction moved |
  | `fee_payer` | the account whose balance fee processing decreased |
  | `operation_source` | an operation's own source account |
  | `destination` | an account the transaction created |
  | `signer_owner` | an account whose signers changed |
  | `trustline_owner` | the owner of a trustline that was created, changed or removed |
  | `issuer` | the issuer of an asset the transaction touched |
  | `sponsor` | an account that sponsors a created entry or whose sponsoring count grew |
  | `contract` | a contract whose own entries (instance or data) changed |
  | `authorizer` | the address of a nonce entry the transaction created: its Soroban authorization was used. Nonce entries are bookkeeping, so no state change is recorded for them; the role is the only trace |
  | `liquidity_pool` | the `L…` address of a liquidity pool whose entry was created, changed or removed |
  | `claimable_balance` | the `B…` address of a claimable balance that was created or claimed |
  | `claimant` | an affected account named as a claimant of a claimable balance the transaction created or claimed |
  | `counterparty` | any other affected address. Pools and balances were recorded as `counterparty` before `liquidity_pool` and `claimable_balance` existed; that stays valid, since roles are advisory (P-4) |
* `unverified` (string): see §6.4.

| Rule | Statement |
| - | - |
| P-1 | For every `must_include` item, the reader's participant set for the transaction must contain an item whose **base address** equals `address`. An indexer that normalises to base accounts satisfies this directly (adapter declaration `muxed: base_only`) |
| P-2 | A reader that reports a `muxed_id` for a participant must report the expected `muxed_id` as a decimal string (or an `on_chain_form` equal to the expected `M…`/`W…`); reporting none is acceptable, with one exception. An indexer whose adapter declares that it also stores the muxed alias (`muxed: base_and_alias`) **must** report the expected `muxed_id` when the item states one and is not marked `unverified`: such an ID was read from the ledger by the reference extractor (§6.11), and a reader that claims to keep aliases and drops it is `wrong`. An item marked `unverified` is `not_applicable` for that comparison. With `muxed: base_only` the muxed ID is never compared |
| P-3 | An indexer that stores **only** the `M…` or `W…` form and cannot return the base address fails P-1 with `wrong` ("identity stored only in muxed form"), not `missing`. The base account must be present; the muxed form may be recorded too, never instead |
| P-4 | Roles are advisory. A reader is not failed for a missing or extra role unless its adapter declares that it models roles |
| P-5 | No item of `must_not_include` may appear, by base address, anywhere in what the reader holds for the transaction: participants, state-change accounts, movement endpoints, stored addresses. A hit is `forbidden_present`, reported with the item's `because`. Typical items: an address named only in an unmatched authorization entry, the destination of a failed transaction, an address fabricated from a memo, an account "credited" by a forged token event. One exception: a movement the entry itself lists in `movements` (an item with a `count` other than 0, `unverified` included) that states the forbidden address exactly as its `from` or `to` is the entry's own statement: a record matching that item in kind, asset, base endpoints and amount is not a hit for that address (M-7). An item that leaves the endpoint unstated, or states only the base of a forbidden muxed address, spares nothing |
| P-6 | With `exact: true`, the reader's set, reduced to base addresses, must equal `must_include` |

Readers differ in whether a called contract is a participant: the wallet-backend indexer recorded the Stellar Asset
Contract's address as one at commit `c152783c` and no longer does at `e967ce8b` (both runs in
`evidence/wallet-backend-731/`). Entries therefore list contracts under `must_include` only when the contract's own
ledger entries changed, and do not set `exact` on contract-call entries.

### 6.6 State changes

`expect.state_changes[]`: `\{kind, account, asset?, signer?, detail?, cause?, only_if?, tx_index?, op_index?,
unverified?\}`, with `kind` and `account` required. `kind` is one of a closed list of 29 (identical to the list in
`corpus/schema/observation.schema.json`): `account_created`, `account_removed`, `balance_changed`,
`trustline_created`, `trustline_removed`, `trustline_flags_changed`, `trustline_limit_changed`, `signer_added`,
`signer_removed`, `signer_changed`, `sponsorship_changed`, `offer_changed`, `liquidity_pool_created`,
`liquidity_pool_removed`, `liquidity_pool_changed`, `claimable_balance_created`, `claimable_balance_claimed`,
`contract_data_changed`, `contract_deployed`, `entry_restored`, `entry_evicted`, `data_entry_changed`,
`thresholds_changed`, `sequence_bumped`, `account_flags_changed`, `home_domain_changed`,
`inflation_destination_changed`, `ttl_extended`, `contract_code_created`.

`account` is the owner of the changed entry. Two kinds of entry have no address of their own, and their changes are
attributed by a fixed rule:

* **Contract code** (`contract_code_created`, `entry_restored` and `ttl_extended` of a contract-code entry): the
  source account of the transaction that caused the change (the account whose sequence number it moved; the inner
  transaction's source for a fee bump). `detail.wasm_hash` names the code.
* **TTL entries** (`ttl_extended`): a TTL entry is keyed by the sha256 of the key of the entry it belongs to. When
  that key is among the keys the transaction touched (its change lists or its Soroban footprint — the hash proves the
  match), a contract-data entry's TTL is its contract's and a contract-code entry's TTL follows the rule above; a TTL
  whose entry is not found is the source's too, with only `key_hash` in `detail`. A TTL extension makes no
  participant, and the kind is ambient (§6.3).

`signer` is `{type, key, payload_hex?, weight?}`: `type` is `ed25519`, `pre_auth_tx`, `hash_x` or
`ed25519_signed_payload`; `key` the canonical strkey (`G…`, `T…`, `X…`, `P…`); `payload_hex` lower-case hex;
`weight` 0–255. `tx_index` defaults to the focus transaction; `op_index` names the operation.

| Rule | Statement |
| - | - |
| S-1 | An expected item is matched by a reader's state change of the same `kind`, in the same transaction, for the same base `account`, and the same `asset` (§6.3, either form) when given. No such candidate → `missing` (or nothing, for an `only_if` item whose choice the reader does not declare) |
| S-2 | `signer`, when given, is compared in full: `type`, canonical strkey `key` (decoded by the harness from what the reader stored), `payload_hex`, `weight`. A stored value that is a prefix of the expected one is `wrong`, not a match. For a signer kind the adapter declares, the signer itself is required: a candidate that carries no signer, or a signer without a key, is `wrong`; `type`, `payload_hex` and `weight` are compared where the reader holds them |
| S-3 | `detail` keys are fixed per kind (table below). A stated key is compared only when the reader's fact carries the same key, by exact equality; a differing value is `wrong`. A reader that does not hold the key is not penalised |
| S-4 | `cause` explains a change that is not the obvious operation (`contract-call` for a trustline created by the Stellar Asset Contract). It is never compared with what the reader stored; an adapter's declared out-of-scope rules may select expected items by it ([adapter-protocol.md](https://docs.xdrcheck.dev/reference/adapter-protocol.md) §8.1), so state it consistently on every entry that shows the same kind of change |
| S-5 | `state_changes_exact: true`: after all items are matched, every reader state change of the focus transaction that is not ambient, did not match or fail an item, and is of a kind the adapter declares, is `wrong` ("unexpected `<kind>` for `<account>`"). Ambient kinds and facts matching `only_if` items are outside it. Without the flag such changes are ignored |
| S-6 | Never matched: a reader's own row identifiers, ordering columns or operation identifiers. The wallet-backend indexer's own state-change identifier differs between the contract path and an ordinary ChangeTrust for the same kind of change |
| S-7 | `balance_changed` is compared at the granularity of the transaction. The reference extractor states one net change per (transaction, account, asset); a reader may record one row per event or operation instead (one per mint, transfer or path hop), or the reverse. When the expected items and the reader's candidates for one transaction, base account and asset differ in number and no single candidate matches, the sums are compared: the expected `delta`s against the candidates' `delta`s. Equal sums match; different sums are `wrong`, with the two sums as the diff. Where both sides state `balance_after`, some expected value must also be held (the last event's balance is the net row's). When the counts agree, or a `delta` is missing or not an integer on either side, rows are compared one to one as above |

Matching order: for each item, collect the candidates (S-1). A candidate **matches** when every field the item states
and the candidate carries is equal (S-2, S-3). One or more matches → `ok`. For `balance_changed`, candidates that
differ only in `delta` or `balance_after` are then compared by their net (S-7). Candidates but no match → `wrong`,
listing each differing field with expected and observed value. Either way the candidates are *accounted* and are not
extras for S-5.

Excerpt of `cap-0040/signed-payload-signer-added`. The wallet-backend indexer stored this signer as 33 bytes, a
prefix of the correct 41 (S-2; transcripts in `evidence/wallet-backend-replay/`):

```json theme={null}
{
  "kind": "signer_added", "tx_index": 0, "op_index": 0,
  "account": {"address": "GBCK2RYYLIYOSHBEL2FQLAVRSHRH3GP3ID476SGKBV7BEZHMQ6NSBB7B"},
  "signer": {
    "type": "ed25519_signed_payload",
    "key": "PBCK2RYYLIYOSHBEL2FQLAVRSHRH3GP3ID476SGKBV7BEZHMQ6NSAAAAAAB55LN6AANMS",
    "payload_hex": "deadbe", "weight": 1
  },
  "detail": {"signer_ed25519_key": "GBCK2RYY…NSBB7B", "payload_bytes": 3, "signer_key_xdr_hex": "00000003…deadbe00"}
}
```

**One neutral vocabulary for a created trustline.** Whatever created it — a ChangeTrust operation or a Stellar Asset
Contract `trust` call — the facts are:

| Fact | Presence | Why |
| - | - | - |
| `trustline_created` for the owner and asset, `detail` `{balance, limit, flags, authorized, …}` | **required** | It is what the ledger shows: a created trustline entry |
| `trustline_flags_changed` for the same owner and asset, `detail` `{flags, authorized, initial: true}` | `only_if: initial_authorization_separate` | Some readers keep authorisation as its own history stream and record the state the trustline starts in. That is a modelling choice, not a ledger fact, so it is required only of readers that declare it |

`cap-0073/sac-trust-creates-trustline` states exactly these two items and sets `state_changes_exact: true`.

An adapter maps its indexer's model onto these kinds **one row to one fact**; it never merges two of the indexer's
rows into one fact or splits one into two. For the wallet-backend indexer: `TRUSTLINE/ADD` → `trustline_created`;
`BALANCE_AUTHORIZATION/SET` → `trustline_flags_changed` (and the adapter declares `initial_authorization_separate`,
because the indexer writes that row for every new trustline, including ordinary ChangeTrust ones);
`BALANCE/DEBIT` at transaction level → `balance_changed`, ambient.

**`detail` keys per kind.** The keys are closed per kind in the schema. Values are strings (decimal strings for
amounts), integers or booleans.

| Kind | Keys |
| - | - |
| `account_created` | `starting_balance`, `sponsor` |
| `account_removed` | `merged_into`, `balance_transferred` |
| `balance_changed` | `delta`, `balance_after`, `reason` |
| `trustline_created` | `balance`, `limit`, `flags`, `authorized`, `authorized_to_maintain_liabilities`, `clawback_enabled`, `sponsor`, `num_sub_entries_after`, `pool_strkey` |
| `trustline_removed` | `balance`, `pool_strkey` |
| `trustline_flags_changed` | `flags`, `authorized`, `authorized_to_maintain_liabilities`, `clawback_enabled`, `initial` |
| `trustline_limit_changed` | `limit`, `limit_before` |
| `signer_added`, `signer_removed`, `signer_changed` | `signer_key_xdr_hex`, `signer_ed25519_key`, `payload_bytes`, `weight_before`, `sponsor` |
| `sponsorship_changed` | `entry_type`, `sponsor_before`, `sponsor_after` |
| `offer_changed` | `offer_id`, `change`, `selling`, `buying`, `amount`, `price_n`, `price_d` |
| `liquidity_pool_created`, `liquidity_pool_changed` | `pool_id`, `pool_strkey`, `asset_a`, `asset_b`, `fee_bp`, `reserve_a`, `reserve_b`, `total_shares`, `pool_shares_trust_line_count`, `asset_a_issuer_key_hex`, `asset_b_issuer_key_hex` |
| `liquidity_pool_removed` | `pool_id`, `pool_strkey` |
| `claimable_balance_created` | `balance_id`, `amount`, `claimants`, `sponsor` |
| `claimable_balance_claimed` | `balance_id`, `amount` |
| `contract_data_changed` | `contract`, `key_xdr_hex`, `durability`, `change` |
| `contract_deployed` | `contract`, `executable`, `wasm_hash`, `asset` |
| `entry_restored`, `entry_evicted` | `entry_type`, `key_xdr_hex`, `wasm_hash` (contract code) |
| `data_entry_changed` | `name`, `value_hex`, `change` |
| `thresholds_changed` | `master_weight`, `low`, `medium`, `high` |
| `sequence_bumped` | `sequence_after` |
| `account_flags_changed` | `flags`, `flags_before`, `auth_required`, `auth_revocable`, `auth_immutable`, `auth_clawback_enabled` |
| `home_domain_changed` | `home_domain`, `home_domain_hex`, `home_domain_before` |
| `inflation_destination_changed` | `inflation_destination`, `inflation_destination_before`, `cleared` |
| `ttl_extended` | `entry_type`, `key_xdr_hex`, `key_hash`, `contract`, `wasm_hash`, `live_until_ledger`, `live_until_ledger_before` |
| `contract_code_created` | `wasm_hash`, `code_bytes` |

`flags` is the XDR `TrustLineFlags` bit mask; `authorized` and the two other booleans are its bits spelled out, so an
entry states both and either representation can be matched. On `account_flags_changed`, `flags` and `flags_before`
are the `AccountFlags` bit mask after and before, and `auth_required` (1), `auth_revocable` (2), `auth_immutable` (4)
and `auth_clawback_enabled` (8) are its bits after the change. `home_domain_hex` is the new home domain's bytes in
lower-case hex; `home_domain` and `home_domain_before` are the text after and before, given only where the bytes are
UTF-8 (`""` when empty). `inflation_destination` and `inflation_destination_before` are `G…` addresses; a cleared
destination has `cleared: true` and no `inflation_destination` (the named destination is not a participant: its own
entry did not change). On `ttl_extended`, `key_hash` is the TTL entry's key (hex), `key_xdr_hex` the XDR of the key
it belongs to (so `key_hash` is the sha256 of those bytes), `contract` its contract for contract data, and the
`live_until_ledger` values the ledger sequences after and before. `code_bytes` is the length of the uploaded code. Limits and balances are in the asset's smallest unit.
Where an indexer holds a value in another representation, its adapter reports the literal token under
`<key>_as_stored` and leaves `<key>` out; `_as_stored` values are shown as evidence and are not compared in v1. (The
wallet-backend indexer stores a trustline limit as the decimal `922337203685.4775807` — see
`evidence/wallet-backend-731/README.md` — and, in the ordinary ChangeTrust path only, repeats it on the
authorisation row; that is why no expectation states `limit` on `trustline_flags_changed`.)

### 6.7 Movements and routing

`expect.movements[]`: `{kind, asset, amount, from?, to?, routing?, count?, tx_index?, op_index?}`, with `kind`,
`asset` and `amount` required.

* `kind` ∈ `transfer`, `mint`, `burn`, `clawback`, `fee`, `fee_refund`.
* `asset` as in §6.3 (possibly a `${derived.…}` token).
* `amount` is a non-negative decimal string in the asset's smallest unit, or a `${derived.…}` token where it differs
  per variant (the same `trust` call was charged 74541 at Protocol 28 and 34800 at Protocol 30).
* `from`, `to` are accounts (§6.5).
* `count` (default 1) is how many records a reader must hold for this movement; it pins double-counting bugs.
* `routing` is the event's `to_muxed_id`, typed by `routing.type`: `absent` (key not present), `void` (key present,
  value Void — it occurs on pubnet, emitted by custom token contracts), `u64`, `text`, `bytes`; `routing.value`
  carries the value. stellar-core copies the transaction memo into this field for classic payments to unmuxed
  destinations, so `text` and `bytes` values are chosen by the sender and are never an address. Observed in the
  `evidence/local-core/` run: a payment whose text memo looks like the start of a `G…` address carries that text as
  `to_muxed_id` (`evidence/local-core/out/testnet/run-1/decoded/23-L25.json`), and one with a non-UTF-8 text memo
  carries those bytes (`evidence/local-core/out/testnet/run-1/decoded/24-L26.json`).

| Rule | Statement |
| - | - |
| M-1 | Each expected movement must be matched by exactly `count` reader records with the same kind, asset (§6.3), amount and base `from`/`to`. More records → `wrong`; fewer → `missing`. An amount the adapter reports as `amount_as_stored` must be a plain integer equal to `amount`. A matched item accounts only its matching records: another record with the same kind, asset and endpoints but a different amount or routing is left over, and is an extra under `movements_exact` |
| M-2 | `routing.type` `absent` and `void` both mean "no routing ID": a reader passes with none. A reader that reports a routing value must report the same type and value |
| M-3 | A reader must not turn a `text` or `bytes` routing value into an `M…` address (it would appear as a participant or as `to.on_chain_form`); the entry lists that address under `must_not_include` |
| M-4 | `count: 0` asserts the reader holds no such record (double-count, fabrication and forged-event pins): any record with that kind, asset and base `from`/`to` is `wrong`, whatever its amount or routing |
| M-5 | `movements_exact`: see §6.4. Fee movements are outside it |
| M-6 | Fee movements (`fee`, `fee_refund`) are matched only when listed, and only for adapters that declare the fee movement sub-kinds |
| M-7 | **The emitting contract decides whose movement it is.** A token-shaped event (`transfer`, `mint`, `burn`, `clawback`) is a movement of asset X only when the contract that emitted it **is** X: for a classic asset, the Stellar Asset Contract whose ID derives from that asset and the network ID; for a contract token, that contract's own address. An event from any other contract that merely names a classic asset in its topics is that contract's claim about its own token, and a reader that credits the classic asset from it is wrong. Entries that carry such an event pin it with `count: 0` on the classic asset and a `must_not_include` on the "recipient". A reader that publishes token events per emitting contract may record the event as a movement of the emitter's own token (asset = the emitting contract); the entry allows that with an `unverified` item for that asset, which `must_not_include` does not cover (P-5) |

### 6.8 Addresses

`expect.addresses[]`: `{strkey, type, xdr_bytes?, chars?}` (`strkey` and `type` required) — an address the reader
must be able to store and return unchanged. `type` ∈ `account`, `muxed_account`, `contract`, `muxed_contract`,
`claimable_balance`, `liquidity_pool`, `signed_payload`, `pre_auth_tx`, `hash_x`; `xdr_bytes` and `chars` give its
size. The harness asks the adapter for the stored form, decodes it itself, and compares the full string: the expected
strkey must be the full decoding of at least one stored value in the transaction; a stored value that carries the
same key material but decodes to a different or undecodable address (truncated, wrong type, payload dropped) is
`wrong`. Lengths that break fixed-width columns (SEP-0023): `M…` and `W…` 69 characters, `B…` 58, `P…` 69 to 165.
`cap-0040/signed-payload-signer-added` lists its 69-character `P…` signer (`xdr_bytes` 44).

### 6.9 Native conversion (L3)

`expect.native`: `{map_entries?, on_lossy_conversion?, bytes_preserved?}` — what an SDK's conversion of a value to
the language's native types must preserve. `map_entries` is the number of map entries that must survive;
`on_lossy_conversion` is the acceptable behaviour when the native type cannot hold the value: `error` or
`preserve_all`; `bytes_preserved` says byte values must come through unchanged. The case it was made for: a map
whose keys `1` (u32) and `"1"` (symbol) collide as native keys, which an SDK silently collapsed into one
([js-stellar-sdk#1789](https://github.com/stellar/js-stellar-sdk/issues/1789); reproduction in `evidence/js-1789/`).

### 6.10 "Not applicable" is not "dropped"

An adapter declares, in `describe`, the observation kinds and sub-kinds its indexer models (`supported`,
`subkinds`, and a `reason` when not supported). Expected facts of a kind or sub-kind the adapter does not model are
`not_applicable` and never count against it. An entry whose facts are all `not_applicable`, or whose only `ok` facts
are must-not facts (§6.4), produces no verdict about that reader. A fact the reader *does* model and does not hold
is `missing`, which is a drop.

### 6.11 The reference extractor

`xdrcheck-corpus extract <entry>` derives participants, state changes and movements from what stellar-core actually
changed, independently of any reader under test, and `verify` requires it to agree with the author's `expect`
(§11, check 8). Its rules, summarised:

* **Sources and their standing.** It reads ledger-entry changes (fee processing, changes before and after, operation
  changes, Soroban changes — written by core from real state deltas) and consensus events. Classic and fee events are
  a flag-dependent convenience view and are cross-checked, not trusted alone. Diagnostic events are non-consensus and
  attacker-influenced and are **never** read. The envelope is used for two things only: to label a change's `cause`
  with the operation type, and to attach a muxed alias to a participant the meta already established. It never adds
  a participant from the envelope.
* **Per transaction, in apply order.** The fee: in fee processing, the account whose balance decreased is the fee
  payer and the decrease is a `fee` movement; an increase in post-apply fee processing is a `fee_refund`. The outcome:
  successful iff the result arm is `tx_success` or `tx_fee_bump_inner_success`. Transaction-level changes: the
  account whose sequence number changed is the source; one-time signer removals are `signer_removed`. A **failed**
  transaction stops here: its participants are the fee payer and the source only, and every other address in its
  envelope is proposed as a `must_not_include` candidate.
* **Operation changes** (successful transactions): each change is classified by entry type and transition into the
  state-change kinds of §6.6; the owner of each changed entry becomes a participant with a role from the entry type
  (§6.5: a pool's or balance's own address is `liquidity_pool` / `claimable_balance`, an affected claimant of a
  balance created or claimed is `claimant`); a classic entry changed under an InvokeHostFunction operation gets
  `cause: contract-call`. Contract code and TTL entries are attributed as §6.6 says; a TTL extension adds no
  participant.
* **Events**: a token-shaped event yields a movement keyed on the contract that emitted it (M-7). If the emitter is
  the Stellar Asset Contract of a classic asset touched by the transaction (or of the native asset), the movement's
  asset is that classic asset; otherwise it is the emitting contract's own token, creates no classic balance fact,
  and an event that names a classic asset anyway is flagged as a forged asset claim with proposed `count: 0` and
  `must_not_include` facts. Only a `u64` routing value sets `to.muxed_id`, and it also attaches that muxed ID (and
  its `M…` form) to the participant as an alias, as the envelope's MuxedAccounts do.
* **Soroban authorization**: a created nonce entry proves that an address authenticated (role `authorizer`; no state
  change is recorded for the nonce entry). An
  address that appears only in authorization entries, with no nonce and no changed entry, is a `must_not_include`
  candidate: a Stellar Asset Contract transfer carrying unmatched authorization entries with void signatures still
  succeeded in the `evidence/local-core/` run (driver step `h:SAC-transfer-with-unmatched-auth`, ledger 30,
  `evidence/local-core/out/testnet/run-1/decoded/28-L30.json`).
* **No classic events in the blob** (a flag profile without them, or an old lake object without backfilled events):
  classic movements are derived from balance deltas per operation instead, and `movements_exact` is set only on the
  event basis.

The extractor proposes; the author decides; `verify` fails on any disagreement until the author resolves it by
reading the bytes again. Agreement means every value the author states is one the extractor derives, and equal:

* a participant's stated `muxed_id` or `on_chain_form`, a state change's stated `detail` key, and a movement
  endpoint's stated `muxed_id` must each be derived by the extractor with the same value — a stated value it does not
  derive is a disagreement, not a skip;
* an `only_if: initial_authorization_separate` item is confirmed against the `trustline_created` of the same
  transaction, account and asset: its `flags`, `authorized`, `authorized_to_maintain_liabilities` and
  `clawback_enabled` must equal the created trustline's, and `initial` must be `true`;
* roles are not compared (P-4);
* an item the author marks `unverified: "<reason>"` (§6.4) is not required — the honest way to keep a value no
  ledger field carries. Its facts still count as accounted under the exactness flags.

## 7. Known divergences

`conformance.known_divergences[]` records that a specific reader gets this entry wrong in a version range. Fields:
`target`, `versions`, `outcome` and `reference` are required; `level`, `qualifier`, `profile`, `detail`, `fixed_in`,
`status`, `observed`, `evidence`, `finding` and `match` are optional.

* `target`: package or repository (`@stellar/stellar-sdk`, `github.com/stellar/go-stellar-sdk`,
  `stellar/wallet-backend`).
* `versions`: a semver range for packages; for repositories without tags a commit range `A..B` (every commit from A
  to B inclusive on the default branch's first-parent history) or `..B` (everything up to and including B), each
  side 7 to 40 lower-case hex digits. A semver range is alternatives joined by `||`, each `*`, a hyphen range
  `A - B` (inclusive), or space-separated comparators (`=`, `<`, `<=`, `>`, `>=`, or a bare version meaning `=`); a
  version is `MAJOR[.MINOR[.PATCH]]` with an optional leading `v`, `-prerelease` and `+build`. Nothing else (`^`,
  `~`, `x` wildcards) is accepted: `verify --checks schema` fails a range that does not parse, because a consumer
  would otherwise match nothing and drop the divergence silently.
* `level`: `L0`–`L4` (§10) or `replay` (the replay harness).
* `outcome`: `reject` (a **valid** input was rejected), `accepts_invalid` (an invalid input was accepted), `crash`,
  `wrong_value`, `dropped`, `halt`, `hang`.
* `qualifier` (for `level: replay`): the exact result qualifier the harness must report inside the range. The harness
  reports each entry as pass, mishandled or dropped; mishandled carries `wrong_value`, `crash`, `hang` or `halt`;
  dropped carries `silent` (the ledger or transaction is absent with no error), `partial` (some expected facts are
  missing) or `refused` (a declared, verified refusal).
* `profile`: set when the divergence exists only under a non-default decode profile or sandbox (for example Rust
  `Limits::none()`).
* `detail`: what was seen. `reference`: a URL (issue, pull request, advisory). `fixed_in`: version or commit.
* `status`: `fixed`, `fixed_unreleased` (merged upstream, no release yet), `open`, `wont_fix`, `unreported`.
* `observed`: `executed` (run at a version inside the range), `source-reading`, `reported` (reported upstream and not
  re-run). A range that was only partly executed is split into two divergences — the executed part and the rest — so
  `observed: executed` never covers a version nobody ran. `cap-0038/pool-issuers-order-by-bytes-not-strkey` splits
  the Go SDK this way: `>=0.7.0 <0.7.2` executed at v0.7.1, and `<0.6.1` taken from release notes as `reported`.
* `evidence`: path or URL of the transcript or note that shows the divergence.
* `match`: details the observed conformance cell must also show for the divergence to count as observed, beyond the
  outcome class — `{reason?, envelopes_parsed?, rejected_tx_index?}`, at least one. `reason` is the driver's reason
  code (one of the driver protocol's `runResponse.reason.code` values); `envelopes_parsed` is how many envelopes the
  SDK parsed and `rejected_tx_index` an envelope (apply order) that must be among those it rejected, both for a
  divergence at level `L1` of a `ledger` entry and within the ledger's transactions; `rejected_tx_index` needs
  `outcome: reject`. `verify --checks schema` checks all of this. For example
  `"match": {"reason": "decode_error", "rejected_tx_index": 2}`.

Excerpt of `cap-0073/sac-trust-creates-trustline`:

```json theme={null}
{
  "target": "stellar/wallet-backend",
  "versions": "..764a4f5bcbff5abb0949d93da37f769063013ea0",
  "level": "replay",
  "outcome": "dropped",
  "qualifier": "partial",
  "reference": "https://github.com/stellar/wallet-backend/issues/731",
  "fixed_in": "c152783c054c765c8b51fd26ed313fd1ebc1c50c",
  "status": "fixed",
  "observed": "executed"
}
```

Semantics for the conformance runner and the harness: **inside** the range the divergence must be observed with that
outcome (and qualifier, when given); **outside** every range the reader must pass; a divergence that is observed but
not listed fails the run. A divergence that is `source-reading` or `reported` is asserted only after it has been
executed once; until then it is reported as "expected, unconfirmed".

In the public manifest `status: unreported` therefore appears only on divergences that are plainly not security-relevant (a strictness nit, a documentation gap), and each of those carries a `finding` ID so that the findings check can see that a record exists. `verify --checks schema` rejects a public entry whose divergence is `unreported` and has no `finding`.

## 8. The replay block

### 8.1 Fields

* `unit`: `single` (served alone at its real sequence) or `chain` (served as part of its scenario run, from the first
  ledger).
* `chain`: the chain ID when `unit` is `chain`.
* `requires_prior_state` (default `false`): `true` if a reader needs the earlier ledgers of the same chain for the
  entry to be meaningful (for example a balance update on an existing trustline). Such entries are replayed only
  inside their chain. For `cap-0073/sac-trust-creates-trustline` it is `false`: serving that one ledger gave the same
  wallet-backend rows as replaying its chain from ledger 2 (transcripts in `evidence/wallet-backend-731/`).
* `indexer_scope`: `all` (default) or `sdk-only` (entries indexers are not expected to ingest, such as very old
  protocols).

### 8.2 Chain indexes

Chain membership is recorded once, in the chain's index file `corpus/chains/<id>.json` (schema
`corpus/schema/chain-index.schema.json`; for example `corpus/chains/sac-trust/p28-testnet.json`, chain ID
`sac-trust/p28-testnet`): passphrase, protocol, flag profile, the stellar-core build, the settings applied, and every
ledger's sequence, blob hash and header hash. A chain is one run of one scenario on one passphrase at one target
protocol under one flag profile. The harness finds the chain a variant belongs to through its blob hash, so an entry
with variants in several chains needs no list in the manifest. A chain below Protocol 20 applies no Soroban settings:
its `settings.source` starts with `none` and `settings.files` is empty (every other chain lists at least one file).
A chain whose scenario fixes the apply order of a ledger group records, under `orders`, the group's first step ID
with the `${order_nonce}` the generator chose and the transaction-set shape its search used (`default` or `learned`);
`gen --check` repeats the search and reports a different nonce or shape as a difference.

Only the ledgers that hold an entry are vendored as blobs; the replay harness serves the rest of a chain from the
run's record-marked meta stream, which the index names under `stream` (`path`, `sha256`, `records`). Chains written
by `xdrcheck-corpus gen` keep that stream in the repository next to the index, as
`chains/<scenario>/p<NN>-<network>.meta.xdr.zst` (one zstd frame, level 19, with the content checksum); `stream.path`
is relative to the corpus root and `stream.sha256` is the sha256 of the **uncompressed** stream. The two
`sac-trust` chains name their raw stream under `evidence/` instead (relative to the repository root). Raw meta bytes
are not reproducible, so `xdrcheck-corpus gen` rewrites a committed chain's bytes only when a regeneration no longer
passes `gen --check` against it; otherwise it writes the committed stream's bytes again.

The harness may additionally place any entry in a renumbered *stream* for load and memory tests (ledger sequences
rewritten to make unrelated ledgers contiguous). That transformation is a report-time artefact: it is never recorded
in the manifest, the transformed bytes never enter the corpus, and stream results are never used for known-divergence
assertions.

### 8.3 How a ledger blob is served

A `LedgerCloseMeta` blob reaches an indexer through an input it already consumes. The corpus bytes are not changed.

* **SEP-54 object** (data-lake layout): the object value is the XDR of `LedgerCloseMetaBatch\{startSequence = seq,
  endSequence = seq, ledgerCloseMetas = [blob]\}` — 12 bytes (`seq`, `seq`, `1`, each a big-endian uint32) followed by
  the blob, zstd-compressed. For the two `history` entries this is byte-identical to the public lake's decompressed
  object (§4.5). The key follows the SEP-54 layout with one ledger per batch, at the ledger's real sequence for a
  `single` unit. The store root carries `.config.json` with the passphrase, `"version":"1.0"`, `"compression":"zstd"`,
  `"ledgersPerBatch":1` and `"batchesPerPartition":64000`. One store per passphrase.
* **`getLedgers` item** (the RPC method's v30.0.0 field types): `hash` (hex, the header hash stored in the blob, not
  recomputed), `sequence` (number), `ledgerCloseTime` (string, decimal seconds), `headerXdr` (base64 of the
  `LedgerHeaderHistoryEntry` inside the blob), `metadataXdr` (base64 of the blob, verbatim).
* Consumers require strictly consecutive sequences and none checks the previous-ledger hash, so a `single` unit at its
  real sequence is valid input. The passphrase is enforced through transaction hashes, so a run uses one passphrase.

## 9. `api`, `strkey` and negative entries

### 9.1 `api`

No blob. `api` is `{op, input, expect_xdr_hex?, expect_value?, expect_reject?}` with `op` and `input` required.

* `op` is an SDK-neutral name from a closed list, which each driver maps to its SDK's function: `asset.compare`,
  `liquidity_pool.id`, `liquidity_pool.asset`, `muxed_account.encode`, `muxed_account.decode`, `offer.manage_sell`,
  `offer.manage_buy`, `scval.from_native`, `scval.to_native`, `scval.sort_map`, `strkey.encode`, `strkey.decode`,
  `transaction.parse`, `transaction.hash`, `memo.text_roundtrip`, `address.to_strkey`, `address.from_sc_address`,
  `signer_key.to_strkey`, `scval.native_roundtrip`, `operation.object_roundtrip`, `xdrjson.decode`,
  `asset.from_operation`, `price.encode`, `xdr.custom_union_encode`. The list is the schema's `$defs/apiOp`, which the
  driver protocol schema references; it grows only with a schema minor version.
* `input` holds the arguments by name. An argument that must reach the SDK in a language-native numeric type is
  written `{"native": "number", "value": "…"}`, bytes as `{"hex": "…"}`, everything else as a string. Strings may
  contain `${derived.*}` tokens.
* `expect_xdr_hex` (lower-case hex), `expect_value` (any JSON value) or `expect_reject` (boolean) state the result.
  When `expect_reject: true` is given **together with** `expect_xdr_hex` or `expect_value`, either outcome conforms —
  the exact result, or a refusal ("exact or refuse").

Example: `\{"op": "offer.manage_sell", "input": \{"offer_id": \{"native": "number", "value": "9007199254740993"\}\},
"expect_reject": true\}`. The defect it pins
([js-stellar-sdk#1785](https://github.com/stellar/js-stellar-sdk/issues/1785)) is that the pre-fix SDK accepts a
number that is not a safe integer: the driver, building that JavaScript number, has already lost the last digit, and
the SDK then encodes …992 (reproduction in `evidence/js-1785/`). Shapes stellar-core rejects at submission, such as a
pool trustline with its assets in strkey order (rejected in the `evidence/local-core/` run, step
`e:pool-trust-WRONG-order` in `evidence/local-core/out/testnet/run-1/driver.json`), can never be core-emitted and are `api` entries or
synthetic negatives.

### 9.2 `strkey`

`strkey` is `{text, type?, payload_hex?, origin?}` with `text` required. `type` ∈ `account`, `muxed_account`,
`secret_seed`, `pre_auth_tx`, `hash_x`, `signed_payload`, `contract`, `muxed_contract`, `liquidity_pool`,
`claimable_balance`; `payload_hex` is the decoded payload; `origin` names the published document and vector label
(for example "SEP-0023 v1.4.0 invalid #15"). Invalid vectors carry `expect.reject`. The 30 published SEP-0023 v1.4.0
vectors are entries of the family `strkey/sep-0023-v1.4.0-vectors`.

### 9.3 Negative entries

`negative: true`, `synthetic: true`, and `expect.reject` = `{reason, note?, limits?}` with `reason` from a closed list:

| Class | Reasons |
| - | - |
| XDR strictness | `nonzero_padding`, `bool_range`, `optional_flag_range`, `enum_undeclared`, `union_arm_undeclared`, `length_exceeds_max`, `length_exceeds_input`, `trailing_bytes`, `depth`, `record_mark` |
| Strkey | `strkey_checksum`, `strkey_length`, `strkey_version`, `strkey_padding`, `strkey_noncanonical` |
| API | `value_out_of_range`, `ordering` |

A vector "one level beyond reader X's limit" is therefore accepted by the oracle unless the entry states X's boundary as `expect.reject.limits` = `{depth}` (an integer ≥ 1, in stellar-xdr units); the `reject` check then decodes at that depth.

**Record-mark vectors.** A vector whose fault is in the RFC 5531 record marks (the last-fragment bit clear, a mark
that declares more bytes than remain, a mark shorter or longer than its record's value) sets `framing:
"record-marked"` and `frame_index` on its variant (§4.2) and `reason: "record_mark"`. Its blob is the stream. The
oracle reads every mark of the stream — a mark fault anywhere rejects it — and decodes record `frame_index`, which
must hold exactly one value of `xdr_type`; a declared length that disagrees with that value is a mark fault too.
Conformance drivers receive the same input as `framing: "record-marked"` with `frame_index` (driver protocol). The
oracle's reason classes: a clear last-fragment bit is `record_mark`; a mark past the end of the stream, or shorter
than its value, is `record_mark` or `length_exceeds_input`; a mark longer than its value is `record_mark` or
`trailing_bytes`.

An "undeclared" vector must use a value that no pinned XDR definition declares: `SCVal` type 22 is
`SCV_EXECUTABLE_TAG` at Protocol 30, so undeclared-discriminant vectors use 23 or above. The two "undeclared" reasons
differ in practice: stellar-core's own decoder rejects an undeclared **union discriminant** but accepts an undeclared
value in a **plain enum field**, so `enum_undeclared` entries carry a `core_behaviour` block saying stellar-core
accepts. Observed with `stellar-core print-xdr` v30.0.0, one transcript per input:
`evidence/core-print-xdr/out/union-undeclared-scvaltype.txt` (rejected), `evidence/core-print-xdr/out/enum-undeclared-durability.txt` (accepted) and
`evidence/core-print-xdr/out/scv-executable-tag-22.txt` (type 22 decodes). The same folder shows it rejects non-zero padding
(`evidence/core-print-xdr/out/bytes-pad-nonzero.txt`), an optional flag of 2 (`evidence/core-print-xdr/out/optional-flag-2.txt`), trailing bytes
(`evidence/core-print-xdr/out/trailing-1.txt`) and over-long vectors (`evidence/core-print-xdr/out/signers-21.txt`).

A negative entry is never served to an indexer as a ledger. Where implementations legitimately differ — stellar-core's
own decoder reads a boolean of 2 as true (`evidence/core-print-xdr/out/bool-2.txt`) while the XDR rule admits only 0
and 1 (probe vector 6a of `evidence/sdk-matrix`) — the entry says so in `why`, and the divergence matrix reports the
split rather than a single verdict.

### 9.4 `spec`: contract interfaces

A `spec` entry is a contract interface (SEP-48): an `SCSpecEntry` stream with no frame between entries, held by a
Wasm module in its `contractspecv0` custom sections, or bare. Its one variant has `xdr_type: "SCSpecEntry"` and
`container`: `wasm` (the blob is the module, `blobs/<aa>/<sha256>.wasm`) or `xdr-stream` (the blob is the stream,
`.xdr`). Code read from a network carries `source.kind: "contract-code"` with the `network`, the `wasm_hash` (the
blob's sha256), the `upload_ledger` (the CONTRACT\_CODE entry's last-modified ledger), how it was fetched and when;
synthetic interfaces are built by `xdrcheck-corpus synth` from a `spec` recipe (SEP-51 JSON of each entry, encoded by
the oracle, then byte edits for the vectors the oracle refuses to encode).

`expect.spec` is read from the bytes by the corpus's own section reader (`xdrcheck_xdr::spec`) and written by
`xdrcheck-corpus render`; `verify --checks spec` reads the bytes again and fails on any difference:

| Field | Meaning |
| - | - |
| `sections` | `contractspecv0` custom sections in the module (Wasm only), names compared as raw bytes |
| `entries` | every whole entry, in stream order across all sections: `kind` (`function`, `struct`, `union`, `enum`, `error_enum`, `event`), `name`, `args` (`{name, type}` for function inputs, struct fields, union and enum cases, event params) and, for a function, `outputs` |
| `clean_end` | every section decodes to whole entries with nothing left over |

Types are written `u32`, `option<T>`, `result<T,E>`, `vec<T>`, `map<K,V>`, `tuple<A,B>`, `bytes_n<N>`,
`udt:<name>`; a union case's type is `void` or `tuple<…>`, an enum case's `=<value>`, an event param's
`<type>@topic_list` or `<type>@data`. SEP-48 stores an interface in **one** section, so an entry with more than
one section or a stream that does not end cleanly is negative (`expect.reject.reason` `spec_sections`,
`length_exceeds_input`, `trailing_bytes` or `length_exceeds_max`). A module with no spec section is a positive
entry with `sections: 0` and no entries: a reader may return an empty interface or report the absence as an
error, and both conform. `xdrcheck-corpus coverage --arms --universe SCSpecEntry` counts the `SCSpecEntry` arms the
spec entries reach.

### 9.5 Validity and flags: the negative-case vocabulary

Every entry states what a correct reader does with its input, in the vocabulary of the WebAssembly spec tests
(`malformed` against `invalid`) and Wycheproof (`valid`, `invalid`, `acceptable`, with bug-class flags):

| `validity` | Meaning | Entries today |
| - | - | - |
| `valid` | The input decodes and is accepted. Every ledger stellar-core wrote is valid | every `ledger` entry, positive `xdr`, `spec` and `strkey` entries, `api` calls with an exact result |
| `malformed` | The bytes (or text) must fail to decode: a decoder that returns a value is wrong | negative entries whose `expect.reject.reason` is a decoding rule (XDR strictness, strkey, spec sections cut short or with bytes left over); `api` refusals of a parse or decode call |
| `invalid` | The input decodes, and a validating reader must reject it | negative entries whose reason is `value_out_of_range`, `ordering` or `spec_sections`; `api` calls that must be refused on their arguments |
| `acceptable` | A reader may accept or reject, and both conform | `api` entries with `expect_reject` together with an exact result ("exact or refuse", §9.1) |

The schema ties `validity` to the other fields, so the two can never disagree: `negative: true` means `malformed`
or `invalid`, and a `malformed` or `invalid` entry of kind `ledger`, `xdr`, `spec` or `strkey` is `negative`;
`expect.reject.reason` `value_out_of_range`, `ordering` or `spec_sections` means `invalid`, any other reason
`malformed`; an `api` entry with `expect_reject` and an exact result is `acceptable`, with `expect_reject` alone
`malformed` or `invalid`, and without `expect_reject` `valid`. A variant may state its own `validity` when it
differs from the entry's; none does today.

`flags` names the bug classes, from a closed list. Every reject reason of §9.3 has the flag of the same name in
kebab case (`trailing_bytes` → `trailing-bytes`), and an entry with an `expect.reject.reason` carries that flag.
Further flags:

| Flag | Meaning |
| - | - |
| `core-lenient` | stellar-core's own decoder accepts the input (`core_behaviour.accepts: true`); set exactly then |
| `depth` | also on valid entries: nesting at or right below a depth limit (`limits/`) |
| `discriminant-type` | a union switched on a type XDR does not allow as a discriminant |
| `native-number-precision` | an integer passed as a language-native number that cannot hold it exactly (2^53 + 1) |
| `non-utf8-text` | text fields holding bytes that are not UTF-8 |

How a runner reads it: `valid` — decode (and, for `api`, the call) must succeed with the expected value;
`malformed` — the decoder must refuse the input (level L0); `invalid` — decoding may succeed, and the reader's
validating layer (object parse, API call) must refuse it; `acceptable` — either outcome conforms, but a returned
value must be the stated one. A reader that accepts a `malformed` or `invalid` input has the known-divergence
outcome `accepts_invalid` (§7).

## 10. Conformance levels by kind

`conformance.levels` lists which levels apply: L0 codec round-trip, L1 SDK object parse, L2 decoded values, L3
native conversion, L4 API call, `spec` the SDK's contract-spec reader, and `json` the XDR-JSON converters
(SEP-51: XDR to JSON, the JSON against the converter's own schema, JSON back to XDR;
[conformance-protocol.md](https://docs.xdrcheck.dev/reference/driver-protocol.md#conformance-rules) §2a).

| Kind | L0 | L1 | L2 | L3 | L4 | spec | json |
| - | - | - | - | - | - | - | - |
| `ledger` | decode and re-encode the `LedgerCloseMeta` | parse **every transaction envelope in the transaction set** through the SDK's transaction object, and read the ledger through the SDK's ledger reader where one exists | `expect.values` against the driver's projection | where `expect.native` exists | — | — | every positive variant, on the XDR-JSON columns |
| `xdr` | decode and re-encode the value | the SDK object for that type, if any | as above | as above | — | — | as above |
| `api` | — | — | — | — | the call | — | — |
| `strkey` | — | — | — | — | decode / encode | — | — |
| `spec` | — | — | — | — | — | the SDK's spec reader on the Wasm or stream: its entries against `expect.spec` | — |

The L1 rule for `ledger` entries is why `cap-0038/pool-issuers-order-by-bytes-not-strkey` is a single ledger entry
and needs no separate envelope slice: the defect shows when the SDK builds its transaction object from the envelope,
while the raw XDR codec round-trips it on every version tested (`evidence/js-1766/transcript-prefix.txt`; the
other SDKs as probe vectors 1a–1f of `evidence/sdk-matrix`).

### 10.1 `derived.l1`: what the object layer must read

`variants[].derived.l1` holds the values an SDK's object layer reads from the variant's **focus**, computed by
`verify` with the oracle; a driver reports the same keys at L1 and the runner compares them with these, and only
these. The key list is closed and every value is a string:

| Key | Value | Implied when |
| - | - | - |
| `memo_type` | `none`, `text`, `id`, `hash` or `return`: the focus transaction's memo arm (the inner transaction's for a fee bump) | there is a focus transaction |
| `operation_type` | the focus operation body's XDR-JSON snake\_case arm, for example `change_trust` | there is a focus operation |
| `operation_source` | the focus operation's own source as it is on chain (`G…`, or `M…` when muxed) | the operation has a source |
| `address` | the operation's counterpart account as it is on chain: `destination` of `create_account`, `payment` and both path payments; the `account_merge` destination; `trustor` of `allow_trust` and `set_trust_line_flags`; `from` of `clawback`; `sponsored_id` of `begin_sponsoring_future_reserves` | for those operation types |
| `muxed_id` | the muxed ID (decimal) of `address`, else of `operation_source` | one of them is muxed |
| `asset` | `native` or `CODE:ISSUER`: `asset` of `payment`, `set_trust_line_flags`, `clawback` and `create_claimable_balance`; `dest_asset` of both path payments; the `change_trust` line unless it is a pool share | for those operation types |
| `pool_id` | lower-case hex: the sha256 of a pool-share `change_trust` line's `LiquidityPoolParameters` XDR; `liquidity_pool_id` of `liquidity_pool_deposit` and `liquidity_pool_withdraw` | for those operation types |
| `offer_id` | decimal: `offer_id` of `manage_sell_offer` and `manage_buy_offer` (`0` for a new offer) | for those operation types |

The focus is: for a `ledger` variant, the transaction at `focus.tx_index` (found by its hash under the variant's
passphrase) and, when `focus.op_index` is given, that operation; for an `xdr` variant of type `TransactionEnvelope`,
the value and operation `focus.op_index`; for `Operation`, the value; for `Memo`, its memo type. Other variants imply
no keys. `verify` fails a variant whose `derived.l1` lacks a key the focus implies, carries one it does not, or holds
another value, and prints the expected object; `xdrcheck-corpus gen` writes it for the entries it generates. Excerpt of
`cap-0038/pool-issuers-order-by-bytes-not-strkey`, whose focus is a pool-share ChangeTrust:

```json theme={null}
"l1": {"memo_type": "none", "operation_type": "change_trust", "pool_id": "c2a730127d006897b021d6fcb279da68b4f65f9b6a408c74eb2cdd85ea862d5e"}
```

## 11. Checks beyond the JSON Schema

**What "round-trips" means, per kind.** The corpus promises that entries round-trip through rs-stellar-xdr. Stated
exactly:

| Entries | Check |
| - | - |
| `ledger`, and `xdr` that is not negative | decode with explicit limits → re-encode → identical bytes; JSON → XDR → identical bytes. Every such variant; the only exception is a variant that declares `json_roundtrip: {"skip": true, "reason": …}` (§4.2), which keeps the byte round trip and skips JSON → XDR — and fails if JSON → XDR in fact succeeds |
| `xdr` with `negative: true` | the decoder must **reject** the bytes with the entry's reason class, at `expect.reject.limits.depth` when the entry states it; a `record-marked` variant is read as a stream first (§9.3); a successful decode fails the check |
| `api`, `strkey` | no XDR blob exists, so there is nothing to round-trip. Where an `api` entry gives `expect_xdr_hex`, those bytes must decode as the stated type and re-encode identically; strkey vectors are checked with the pinned strkey library |

`verify` prints the three counts separately, so no entry is reported "skipped" without the rule that skips it. The same
round trip can be run by hand with the stock `stellar-xdr` CLI at the pinned version
(`cargo install --locked stellar-xdr --version 30.0.0 --features cli`); the oracle adds explicit limits and its own
record-mark parsing, it does not change what "round-trip" means:

```sh theme={null}
B=corpus/blobs/58/582e694b96bf69f894763909a1b058c1a2523d5634f2e0947393cee9765f4e0e.xdr
S=corpus/decoded/58/582e694b96bf69f894763909a1b058c1a2523d5634f2e0947393cee9765f4e0e.json.zst
for f in corpus/blobs/*/*.xdr; do [ "$(sha256sum < "$f" | cut -d' ' -f1)" = "$(basename "$f" .xdr)" ] && echo "ok $f"; done
stellar-xdr decode --type LedgerCloseMeta --input single --output json "$B" \
  | python3 -c "import json,sys; print(json.load(sys.stdin) == json.loads(sys.argv[1]))" "$(zstd -dc "$S")"   # True
zstd -dc "$S" | stellar-xdr encode --type LedgerCloseMeta --input json --output single | cmp - "$B" && echo identical
```

`xdrcheck-corpus verify` (checks selectable with `--checks`: `schema`, `hashes`, `roundtrip`, `reject`, `sidecar`,
`pinpoints`, the golden checks, `extractor`, `ids`, `orphans`) enforces what a schema cannot:

1. The file path equals `id`; IDs are unique and present in `corpus/plan.json`; variant keys `(network, protocol)`
   are unique per entry; every `ledger` variant has `meta.profile` and both meta versions, except that a ledger
   with no transactions (`expect.ledger.transactions: 0`) has no `meta.transaction_meta_version`.
2. Every blob exists, its name equals its sha256, and `blob.bytes` matches.
3. Decode with explicit limits, re-encode, byte equality; the sidecar is the one named by the blob's hash, its
   uncompressed JSON matches `decoded_sha256` and equals a fresh rendering as a JSON value; JSON → XDR reproduces
   the blob (exceptions listed in the entry).
4. `focus.path` and every `expect.values[].path` resolve, and the values are equal after substitution;
   `derived.ledger_hash` equals the header hash in the blob, and every `derived.header` value the blob's header
   field (§4.6); `derived.tx_hash` is recomputed from the envelope under
   `passphrase` (this proves the passphrase claim); `derived.contracts` entries that name a Stellar Asset Contract
   equal the computed address; `meta.transaction_meta_version` is the `TransactionMeta` arm in the blob (of the
   focus transaction, else the one every transaction shares) and is absent when the blob has no transactions.
5. The counting rules of §6.2 hold; `expect.transactions` matches the blob.
6. Source checks per kind: a golden variant's frame equals the golden file's record; a history variant's
   `decompressed_sha256` and `blob_offset` hold (§4.5); a history-archive variant's vendored object
   (`corpus/objects/<network>/history-archive/<checkpoint>/`, found by `source.object`) has the sha256 and size its
   `capture.json` and `source.object_sha256` state, its gunzipped sha256 is the bucket hash, the HAS file matches its
   recorded sha256 and size and lists the bucket, and the record mark at `byte_offset` frames exactly the blob; a
   local-core variant's stream and frame; and for a variant
   listed in a chain index, the index row's blob hash and header hash equal the variant's.
7. `fields` rows exist in the guide's field table, **and the status an entry lists a row under equals the row's
   status there** (the entry repeats the status only for readability; the table is the source, and a disagreement
   is an error). The guide's "demonstrated by" column is generated from these citations, never written by hand.
   `caps` exist in the CAP inventory; `protocol.introduced` ≤ every variant's `protocol`.
8. The reference extractor's output agrees with `expect.participants`, `state_changes` and `movements` (§6.11);
   disagreement is an error the author resolves.
9. Every `${derived.*}` token resolves in every variant.
10. `negative` entries have `expect.reject` and no `decoded`. Every entry states `validity`; an entry with an
    `expect.reject.reason` carries the flag of that name, and `core-lenient` is set exactly when
    `core_behaviour.accepts` is true (§9.5).
11. Per-kind `detail` keys, `only_if` values and the exactness rules of §6.4 are respected (the schema enforces the
    first two).
12. `variants[].requires` equals the features derived from the sidecar, and `variants[].derived.l1` the values the
    focus implies (§4.2, §10.1) — both in the `pinpoints` check.
13. Every known-divergence `versions` range parses (§7) — in the `schema` check.
14. Nothing is left over (`orphans`, whole-corpus runs only): every file under `blobs/` and `decoded/` belongs to a
    variant's blob, and every chain index under `chains/` has a ledger some variant uses or is named by an entry's
    `replay.chain`; a directory under `chains/` without a chain index fails too.
15. The golden-mirror check (`ag4`, needs the golden cache): every local-core variant that `corpus/mirrors.json` maps has the
    profile-free skeleton and the reduced shape tokens of its golden counterpart, and every variant it lists under
    `operations` has a golden operation of each of its operation shapes, all computed from the bytes; the list and
    its golden operation shapes are complete and current; there is at least one golden-mirror row, and no fewer entries pass
    than either tier lists (§4.7). That every local-core entry is listed is also checked without the golden cache,
    by `xdrcheck-corpus coverage --check`.

Without a build, `make repo-checks` validates every entry and chain index against its schema
and checks every blob's hash and length, every sidecar's path and the `decoded_sha256` of its uncompressed JSON, every vendored lake object's hash against
its `capture.json`, that every `corpus/…` or `evidence/…` path an entry cites exists (`scripts/py/check_corpus.py`),
and that every entry ID equals its path and is in the registry (`scripts/py/check_ids.py`). The decode, re-encode,
pinpoint, hash-recomputation and extractor checks are the oracle's (`make verify-static`, `make verify-corpus`).

## 12. Versioning and compatibility

* The schema ID carries a major version (`…/v1`). Within v1, adding optional fields, values in **open** vocabularies
  (`shapes`, roles) and new `source` kinds is a minor change. Consumers must ignore fields they do not know **only**
  in `detail`, `derived`, `notes` and `object_metadata`; everywhere else the schema is closed
  (`additionalProperties: false`), so a consumer that meets an unknown field knows its copy of the schema is older
  than the corpus and must stop.
* Adding a value to a **closed** enum (state-change kinds, movement kinds, reject reasons, divergence outcomes,
  `api` operations) is a minor schema version; the corpus index states the entry schema version so a consumer can
  refuse a corpus newer than it understands.
* Removing or renaming a field, or changing the matching rules of §6, is a new major version (`v2`), published side
  by side with v1 for one corpus major version.
* Entry IDs and blob bytes are covered by the stronger rule of §5: they never change.
* Schema-set version 2 (`corpus/schema/SCHEMA_VERSION`) added, within v1, the optional entry fields `validity` and
  `flags`, the optional variant field `validity`, and the entry index schema `entry-index.schema.json` (§3.1, §9.5).
  A strict v1 reader that refuses unknown fields must add the two fields; the corpus itself requires `validity` on
  every entry (§11, check 10).

## Entry IDs

This page gives the rules for entry IDs. `corpus/plan.json` holds them and `scripts/py/check_ids.py` enforces them.
The manifest format that uses them is specified in [`manifest.md`](https://docs.xdrcheck.dev/reference/manifest); how to write an entry is in
[`authoring-entries.md`](https://docs.xdrcheck.dev/guides/add-corpus-entries#authoring-reference).

### 1. The rule

**An entry ID is born in `corpus/plan.json` and nowhere else.** Every other document, schema example, fixture, rule
page, checklist item and CI job cites an ID that already exists there. A document that needs an entry that is not in
the plan adds a row to the plan first (section 5).

As the corpus is built the plan becomes the manifest: one manifest file per canonical ID, at
`corpus/manifest/<group>/<slug>.json` (for example `corpus/manifest/cap-0040/signed-payload-signer-added.json`).
From then on the manifest directory is the registry and the plan is its history.

### 2. Grammar

```text theme={null}
entry-id   = group "/" slug [ "." member ]
group      = "cap-" 4DIGIT | "protocol-" 2DIGIT | "classic" | "ledger" | "limits" | "strkey" | "xdr-strict" | "xdr-json"
slug       = lower-case words joined by "-"; may contain "." inside a version (sep-0023-v1.4.0-vectors)
member     = lower-case words joined by "-", or a 16-hex golden file key, or a vector label (9e1)
```

Every ID matches the manifest schema's pattern `^[a-z0-9]+(-[a-z0-9]+)*(/[a-z0-9]+([.-][a-z0-9]+)*)+$`
(`corpus/schema/manifest-entry.schema.json`). An ID never encodes a network, a protocol version of a variant, or a
source: those are variant properties. (`cap-0040/signed-payload-signer-added`, not `…-added-testnet`.)

#### Groups

| Group | Holds | Plan rows today |
| - | - | - |
| `cap-NNNN` | A pattern introduced or changed by that CAP; four digits, as in the stellar-protocol file names. An entry touching several CAPs lives under the one that first made the shape possible and lists the others in `caps` | 155, in 36 CAP groups |
| `protocol-NN` | Protocol-gated behaviour with no CAP (Protocol 29 shipped no CAPs but changed behaviour), and the ledgers at which a protocol or a meta version first appears (upgrade ledgers, including the cases where the header protocol and the applied protocol differ) | 12, in 10 groups |
| `classic` | Classic-protocol patterns that predate the CAP process or belong to no single CAP (memo and offer-ID encoding, maximum-length vectors, result codes) | 16 |
| `ledger` | Ledger-level shapes of a local chain: upgrade ledgers, configuration upgrades, header extensions, empty ledgers, meta flag profiles | 6 |
| `limits` | Reader-limit boundaries (nesting depth); positive entries | 13 |
| `xdr-strict` | Negative XDR: input a correct decoder must reject (plus the one `api` vector about refusing a non-integer discriminant) | 11 |
| `strkey` | Text address vectors: the published SEP-0023 vectors and synthetic gap vectors | 5 |
| `xdr-json` | XDR-JSON input vectors | 1 |

Entries in the cross-cutting groups have `caps: []` with a `caps_note`; the coverage report lists them under their
group so they are not read as uncovered CAPs.

There is no `api/` group and no `meta/` group. An `api` entry is filed under the group of the pattern it tests, with
`api-` at the start of its slug (`classic/api-offer-id-encoding`). A valid value is never filed under `xdr-strict`,
even when readers mishandle it (`cap-0046/scstring-and-scsymbol-non-utf8`).

There is no group for ledgers located by a census either (`docs/manifest.md` §4.4, `selected_by`). A real ledger
chosen because it holds several arms at once goes under `ledger/`, slug `real-arms-<network>-<sequence>`
(`ledger/real-arms-pubnet-30379767`); one that shows a single pattern is a `history` variant of that pattern's
existing entry.

### 3. Families

Some plan rows stand for several closely related vectors: the 30 published SEP-0023 vectors, six offer-ID inputs,
five golden files of one stellar-core test. One manifest entry is one pattern, and the manifest has no `vectors[]`
construct. So:

* A plan row with `vector_count` greater than 1 is a **family**. It lists its `members`.
* Each member becomes its own manifest entry with the ID `<family-id>.<member>`, generated from one source file.
  Examples: `strkey/sep-0023-v1.4.0-vectors.invalid-15`; `xdr-strict/trailing-bytes.transaction-envelope`;
  `cap-0058/create-contract-v2-constructor-golden.c2190f875f6f59fd`.
* The family ID itself is canonical and may be cited when every member is meant ("all SEP-0023 vectors"). It does
  not name a manifest file.
* Member names are: a descriptive slug where the member has an obvious one; the 16-hex file key for stellar-core
  goldens (the key changes with every protocol, so the manifest also records the human test name);
  `pubnet-<sequence>` or `testnet-<sequence>` for members captured from network history; the vector label of the
  cross-SDK matrix in `evidence/sdk-matrix/` where the family was imported from it and no better name exists
  (`cap-0084/api-muxed-address-field-order.9e1`).
* Member names of `cap-0046/scval-integer-extremes` (`v01`…`v06`) are placeholders until the recipe is written.

Today: 219 plan rows, of which 45 are families with 161 members. A row that is not a family is one entry. The corpus
therefore has 219 − 45 + 161 = **335 planned manifest entries**, and 380 canonical IDs (every row ID plus every
member ID; `python3 scripts/py/check_ids.py --list` prints them).

In prose, a glob over canonical IDs is allowed (`limits/scvec-nesting-*`, `strkey/sep-0023-v1.4.0-vectors.invalid-*`).
In data files (manifest, the guide's field table, fixtures, CI configuration) only exact canonical IDs appear.

### 4. Stability

* A canonical ID is permanent once an entry with that ID has shipped in a corpus release. Before the first release a
  rename is allowed only in a change that also updates every citation of the old ID.
* The bytes of a shipped entry never change. A corrected pattern gets a new ID; the old entry stays and is superseded
  in its `notes`.
* A golden member's 16-hex key changes at a protocol bump. The upgrade procedure adds new members for the new files
  and keeps the old ones; it does not rename.

### 5. Requesting a new ID

1. Search `corpus/plan.json` (and the member lists) first: the pattern may already exist under another name.
2. If it is new, add a row to `corpus/plan.json` with every key the plan schema (`corpus/schema/plan.schema.json`)
   requires: `id`, `kind`, `negative`, `caps`, `protocol_min`, `source`, `locator` (or the route to obtain one),
   `networks`, `synthetic`, `serves`, `pins`, `levels`, `replayable`, `priority`, `scenario`, `shape`,
   `vector_count`, `members`, `evidence`; `note` is optional. Say honestly what has been executed and what has not.
3. Run `make repo-checks`; the coverage report (`make verify-coverage`) picks the row up from the plan.
4. Only then cite the ID.

`scripts/py/check_ids.py` (part of `make repo-checks`) validates every plan row against the plan schema, rejects
duplicate IDs, and checks that every manifest file's `id` is canonical and equals its path and that every entry ID a
manifest file cites (`slice_of.entry`, `source.base_entry`) is canonical. The same rule binds the documentation,
the guide, the linter rule pages, the fixtures and the CI configuration: any entry ID they cite must be canonical.


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