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 incorpus/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
Whatcorpus/ holds today:
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. Alocal-corevariant’ssource.scenarionames its scenario file underscenarios/; a variant produced before the generator existed would instead point at its published driver underevidence/(relative to the repository root). - Sidecars are stored once per blob: every variant whose blob is
blobs/<aa>/<sha256>.xdr, in any entry, hasdecoded: "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_sha256is the sha256 of the uncompressed JSON, so it does not depend on the zstd build.xdrcheck-corpus renderwrites these files and removes any file underdecoded/that no variant references;xdrcheck-corpus render --print <entry> [--variant <network>[@<protocol>]] [--pretty]prints one variant’s JSON, andzstd -dc <file>works too. corpus/objects/keeps captured public-lake objects byte-for-byte, with acapture.jsonthat records the store, key, hashes, the store’s object metadata and the commands used. Ahistoryentry’s blob is cut from one of them (§4.5). Upgrade-ledger captures such ascorpus/objects/pubnet/30191538/capture.jsonare kept there too.
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 bycorpus/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:
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 incore_meta_flags.
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_indexis the zero-based index of the record-markedLedgerCloseMetain the golden file;test_nameis the human-readable name from the golden index.local-core:scenariois the scenario file,stepthe step that produced this ledger,config_sha256the hash of the stellar-core configuration,stream_sha256the hash of the complete record-marked meta stream of the canonical run,frame_indexthis ledger’s record in it,generated_bythe tool and version that drove stellar-core,inputs[]other pinned inputs such as Soroban settings-upgrade sets.reproducibilityisbyte-identicalornormalised-identical. Every local-core variant so far isnormalised-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-lcmapplies (sort each ledger-entry change list in the places core sorts it, zero thecore_metrics/invoke_time_nsecsdiagnostic value). Observed inevidence/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 refusedTransactionResultits/txendpoint returned (endpoint: tx, thestatusit answered with) for the envelope stored as the entryenvelope_entry.core_role(optional; absent meansrelease) names the binary that emitted the bytes: the pinnedrelease, abuildtestsbuild with test hooks, avnextnext-protocol build, or anold-corerelease 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) orsimulated. Thetrustentry isdeclared, and its fee refund reflects that.history:storeis the public SEP-54 store (for examples3://aws-public-blockchain/v1.1/stellar/ledgers/pubnet),keythe object key,object_sha256the hash of the object as stored (compressed),batch_indexthe ledger’s index inside the batch,object_metadatathe store’s user metadata exactly as returned.written_by(the stellar-core and exporter versions in the object’s metadata) andregeneratedare required for lake entries.regenerated: truemeans 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 carryTransactionMetav4 with backfilled events (see thetransaction_meta_versionsof the old pubnet captures undercorpus/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:censusis the census file,query_idthe query. Ahistory-archivesource’sfile_kind(optional; absent meansbucket) says whether the record is cut from a bucket file or an SCP history file.object_pathnames 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: truemarks 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.
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 ofxdr_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<>; \}. 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:
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:
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 reasonno golden transaction of this shape; every operation has a golden operation of the same shape(listed underoperations),no golden covers this shape, orno transaction: a ledger-level patternfor 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 coverageadds 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 andcorpus/coverage.jsoncounts 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.jsonrow (every local-core entry is listed exactly once, nothing else is, andgolden_operationsequals a fresh computation) and afloor:ag4row, which fails when there is no golden-mirror variant row or when fewer entries pass than either tier lists.
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
- Bytes —
variants[].blob. Re-encoding a decoded value must reproduce them (level L0). - 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. - 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:
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 owntx_index, the transaction at that index (resolved to a hash throughexpect.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
feeandfee_refund; state-change kindbalance_changedwhen a reader models balances as state changes) and the sequence-number bump (state-change kindsequence_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.
- 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). assetisnative,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 underderived.contracts,verifyhas 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 itsdescribeanswer (modellingincorpus/schema/adapter-protocol.schema.json). For other readers it cannot bemissing, and a matching fact they report anyway is allowed. The one choice defined in v1 isinitial_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>"(aparticipants.must_includeaccount, astate_changesitem or amovementsitem) 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 isnot_applicablefor every reader, and the facts it describes still count as accounted under the exactness flags.
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_idis a decimal string;on_chain_formis the address exactly as its on-chain form renders (M…orW…when muxed). -
rolesexplains 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_restoredandttl_extendedof 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_hashnames 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 onlykey_hashindetail. 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/):
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.assetas in §6.3 (possibly a${derived.…}token).amountis a non-negative decimal string in the asset’s smallest unit, or a${derived.…}token where it differs per variant (the sametrustcall was charged 74541 at Protocol 28 and 34800 at Protocol 30).from,toare accounts (§6.5).count(default 1) is how many records a reader must hold for this movement; it pins double-counting bugs.routingis the event’sto_muxed_id, typed byrouting.type:absent(key not present),void(key present, value Void — it occurs on pubnet, emitted by custom token contracts),u64,text,bytes;routing.valuecarries the value. stellar-core copies the transaction memo into this field for classic payments to unmuxed destinations, sotextandbytesvalues are chosen by the sender and are never an address. Observed in theevidence/local-core/run: a payment whose text memo looks like the start of aG…address carries that text asto_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, indescribe, 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
causewith 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
feemovement; an increase in post-apply fee processing is afee_refund. The outcome: successful iff the result arm istx_successortx_fee_bump_inner_success. Transaction-level changes: the account whose sequence number changed is the source; one-time signer removals aresigner_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 amust_not_includecandidate. - 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 isclaimant); a classic entry changed under an InvokeHostFunction operation getscause: 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: 0andmust_not_includefacts. Only au64routing value setsto.muxed_id, and it also attaches that muxed ID (and itsM…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 amust_not_includecandidate: a Stellar Asset Contract transfer carrying unmatched authorization entries with void signatures still succeeded in theevidence/local-core/run (driver steph: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_exactis set only on the event basis.
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_idoron_chain_form, a state change’s stateddetailkey, and a movement endpoint’s statedmuxed_idmust 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_separateitem is confirmed against thetrustline_createdof the same transaction, account and asset: itsflags,authorized,authorized_to_maintain_liabilitiesandclawback_enabledmust equal the created trustline’s, andinitialmust betrue; - 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 rangeA..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 rangeA - B(inclusive), or space-separated comparators (=,<,<=,>,>=, or a bare version meaning=); a version isMAJOR[.MINOR[.PATCH]]with an optional leadingv,-prereleaseand+build. Nothing else (^,~,xwildcards) is accepted:verify --checks schemafails a range that does not parse, because a consumer would otherwise match nothing and drop the divergence silently.level:L0–L4(§10) orreplay(the replay harness).outcome:reject(a valid input was rejected),accepts_invalid(an invalid input was accepted),crash,wrong_value,dropped,halt,hang.qualifier(forlevel: replay): the exact result qualifier the harness must report inside the range. The harness reports each entry as pass, mishandled or dropped; mishandled carrieswrong_value,crash,hangorhalt; dropped carriessilent(the ledger or transaction is absent with no error),partial(some expected facts are missing) orrefused(a declared, verified refusal).profile: set when the divergence exists only under a non-default decode profile or sandbox (for example RustLimits::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 — soobserved: executednever covers a version nobody ran.cap-0038/pool-issuers-order-by-bytes-not-strkeysplits the Go SDK this way:>=0.7.0 <0.7.2executed at v0.7.1, and<0.6.1taken from release notes asreported.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.reasonis the driver’s reason code (one of the driver protocol’srunResponse.reason.codevalues);envelopes_parsedis how many envelopes the SDK parsed andrejected_tx_indexan envelope (apply order) that must be among those it rejected, both for a divergence at levelL1of aledgerentry and within the ledger’s transactions;rejected_tx_indexneedsoutcome: reject.verify --checks schemachecks all of this. For example"match": {"reason": "decode_error", "rejected_tx_index": 2}.
cap-0073/sac-trust-creates-trustline:
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) orchain(served as part of its scenario run, from the first ledger).chain: the chain ID whenunitischain.requires_prior_state(defaultfalse):trueif 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. Forcap-0073/sac-trust-creates-trustlineit isfalse: serving that one ledger gave the same wallet-backend rows as replaying its chain from ledger 2 (transcripts inevidence/wallet-backend-731/).indexer_scope:all(default) orsdk-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 filecorpus/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
ALedgerCloseMeta 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 twohistoryentries 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 asingleunit. The store root carries.config.jsonwith the passphrase,"version":"1.0","compression":"zstd","ledgersPerBatch":1and"batchesPerPartition":64000. One store per passphrase. getLedgersitem (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 theLedgerHeaderHistoryEntryinside the blob),metadataXdr(base64 of the blob, verbatim).- Consumers require strictly consecutive sequences and none checks the previous-ledger hash, so a
singleunit 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.
opis 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.inputholds 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) orexpect_reject(boolean) state the result. Whenexpect_reject: trueis given together withexpect_xdr_hexorexpect_value, either outcome conforms — the exact result, or a refusal (“exact or refuse”).
\{"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:
- The file path equals
id; IDs are unique and present incorpus/plan.json; variant keys(network, protocol)are unique per entry; everyledgervariant hasmeta.profileand both meta versions, except that a ledger with no transactions (expect.ledger.transactions: 0) has nometa.transaction_meta_version. - Every blob exists, its name equals its sha256, and
blob.bytesmatches. - Decode with explicit limits, re-encode, byte equality; the sidecar is the one named by the blob’s hash, its
uncompressed JSON matches
decoded_sha256and equals a fresh rendering as a JSON value; JSON → XDR reproduces the blob (exceptions listed in the entry). focus.pathand everyexpect.values[].pathresolve, and the values are equal after substitution;derived.ledger_hashequals the header hash in the blob, and everyderived.headervalue the blob’s header field (§4.6);derived.tx_hashis recomputed from the envelope underpassphrase(this proves the passphrase claim);derived.contractsentries that name a Stellar Asset Contract equal the computed address;meta.transaction_meta_versionis theTransactionMetaarm in the blob (of the focus transaction, else the one every transaction shares) and is absent when the blob has no transactions.- The counting rules of §6.2 hold;
expect.transactionsmatches the blob. - Source checks per kind: a golden variant’s frame equals the golden file’s record; a history variant’s
decompressed_sha256andblob_offsethold (§4.5); a history-archive variant’s vendored object (corpus/objects/<network>/history-archive/<checkpoint>/, found bysource.object) has the sha256 and size itscapture.jsonandsource.object_sha256state, its gunzipped sha256 is the bucket hash, the HAS file matches its recorded sha256 and size and lists the bucket, and the record mark atbyte_offsetframes 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. fieldsrows 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.capsexist in the CAP inventory;protocol.introduced≤ every variant’sprotocol.- The reference extractor’s output agrees with
expect.participants,state_changesandmovements(§6.11); disagreement is an error the author resolves. - Every
${derived.*}token resolves in every variant. negativeentries haveexpect.rejectand nodecoded. Every entry statesvalidity; an entry with anexpect.reject.reasoncarries the flag of that name, andcore-lenientis set exactly whencore_behaviour.acceptsis true (§9.5).- Per-kind
detailkeys,only_ifvalues and the exactness rules of §6.4 are respected (the schema enforces the first two). variants[].requiresequals the features derived from the sidecar, andvariants[].derived.l1the values the focus implies (§4.2, §10.1) — both in thepinpointscheck.- Every known-divergence
versionsrange parses (§7) — in theschemacheck. - Nothing is left over (
orphans, whole-corpus runs only): every file underblobs/anddecoded/belongs to a variant’s blob, and every chain index underchains/has a ledger some variant uses or is named by an entry’sreplay.chain; a directory underchains/without a chain index fails too. - The golden-mirror check (
ag4, needs the golden cache): every local-core variant thatcorpus/mirrors.jsonmaps has the profile-free skeleton and the reduced shape tokens of its golden counterpart, and every variant it lists underoperationshas 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, byxdrcheck-corpus coverage --check.
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 newsourcekinds is a minor change. Consumers must ignore fields they do not know only indetail,derived,notesandobject_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,
apioperations) 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 fieldsvalidityandflags, the optional variant fieldvalidity, and the entry index schemaentry-index.schema.json(§3.1, §9.5). A strict v1 reader that refuses unknown fields must add the two fields; the corpus itself requiresvalidityon 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 incorpus/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
^[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 novectors[]
construct. So:
- A plan row with
vector_countgreater than 1 is a family. It lists itsmembers. - 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>ortestnet-<sequence>for members captured from network history; the vector label of the cross-SDK matrix inevidence/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.
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
- Search
corpus/plan.json(and the member lists) first: the pattern may already exist under another name. - If it is new, add a row to
corpus/plan.jsonwith 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;noteis optional. Say honestly what has been executed and what has not. - Run
make repo-checks; the coverage report (make verify-coverage) picks the row up from the plan. - 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.