Skip to main content
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 (the entry-ID registry and its grammar) and authoring-entries.md (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:

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:

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

2. Files and layout

What corpus/ holds today:
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:

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

4. Entry fields

4.1 Top level

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

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

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. 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:
(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:
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): 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: 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. 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, 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:
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:
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): 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: 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):
  • unverified (string): see §6.4.
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. 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/):
One neutral vocabulary for a created trustline. Whatever created it — a ChangeTrust operation or a Stellar Asset Contract trust call — the facts are: 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. 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).

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; 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:
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) 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: 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: 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): 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: 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 §2a). 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: 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:

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: 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:
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; how to write an entry is in authoring-entries.md.

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

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

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.