> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xdrcheck.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# `xdrcheck replay --target`: any target, any version, any ledger

> xdrcheck replay --target: an SDK or pipeline at any version against chosen ledgers, transactions, sets, CAPs or issues; the dataset, find, the run directory and repro bundles.

For SDK maintainers and pipeline operators who want to run one SDK or pipeline, at any version, over chosen real
ledgers: a ledger range, one transaction, a named set, the ledgers of a CAP, or a known issue before and after its
fix.

`xdrcheck replay` has three forms:

| Form | Selected by | Runs | Writes |
| - | - | - | - |
| corpus | `--adapter` ([replay-harness.md](https://docs.xdrcheck.dev/reference/replay-harness.md)) | corpus entries through an indexer adapter, judged against the entries' expected values | a report |
| target (this page) | any of `--target`, `--issue`, `--tx`, `--ledgers`, `--set`, `--cap`, `--ledger-file` | **real ledgers** (mainnet, testnet or corpus) through **one target at one version** | a run directory ([run-directory.md](#run-directory)) |
| rig | `--rig wallet-backend\|stellar-etl\|horizon` ([Pipeline targets](#pipeline-targets)) | one service rig directly | the rig's raw output, not a run directory |

`xdrcheck replay --help` prints the three usage lines; `xdrcheck replay --target T --help` and
`xdrcheck replay --rig R --help` print the flags of the other two forms.

```text theme={null}
xdrcheck replay --target TARGET --version VERSION  SELECTION...  [--out DIR] [--network pubnet|testnet]
           [--dataset DIR] [--lake DIR] [--corpus DIR] [--offline] [--rebuild] [--force]
           [--dispositions FILE] [--fail-on DISPOSITION]
```

## Selection

| Flag | Selects |
| - | - |
| `--ledgers 30941181,30941857` or `--ledgers 100-200` or `--ledgers @file` | whole ledgers |
| `--tx 30941181:51` | one transaction: the ledger and the 0-based position of the transaction in the ledger's apply order (the order of its transaction results). Repeatable. Rows of the other transactions of that ledger are dropped |
| `--tx <64-hex hash>` (with `--ledgers`) | a transaction by hash, searched in the selected ledgers |
| `--set NAME` | a named set of the dataset ([data.md](#dataset), `xdrcheck data sets`) |
| `--cap 38` | the corpus ledgers of every entry that names CAP 38, on `--network` |
| `--issue js-stellar-sdk#1766` | a known issue from `issues.json`: its ledger, its transaction, its target, and by default its pre-fix version (`--fixed` for the fixed one) |
| `--ledger-file FILE` | a ledger object you have: a zstd `LedgerCloseMetaBatch` (a lake object) or a raw `LedgerCloseMeta` named `SEQ.xdr` |

Ledgers that no local lake holds are downloaded from the public lake into the ledger cache first (size and MD5
checked, as `xdrcheck data fetch` does), unless `--offline`.

## Targets and versions

| Target | What runs | `--version` |
| - | - | - |
| `go` | the Go sweep against `github.com/stellar/go-stellar-sdk`: codec, txnbuild parse, hash, re-encode, operation and transaction rebuild, every `ingest.LedgerTransaction` helper, byte-presence checks, token-transfer modes, `VerifyEvents`, Stellar Asset Contract events | a tag (`v0.9.0`), a commit, a branch (`main`), or a local checkout (a `replace` directive) |
| `js` | the JS sweep against `@stellar/stellar-sdk`: codec, parse, hash, re-encode, operation and transaction rebuild, JSON round trip, `Operation.fromXDRObject`, `scValToNative` | an npm version, a commit or branch of `stellar/js-stellar-sdk`, or a local checkout |
| `python` | the Python sweep against `stellar-sdk`: codec, parse, hash, re-encode, JSON round trip | a PyPI version, a commit or branch of `StellarCN/py-stellar-base`, or a local checkout |
| `rust` | the Rust sweep against `stellar-xdr`: codec, transaction extraction, serde JSON round trip | a crates.io version, a commit or branch of `stellar/rs-stellar-xdr`, or a local checkout |
| `wallet-backend`, `stellar-etl`, `horizon` | the pipeline's rig ingests the ledgers into its database and exports rows; the judge compares the rows with facts it computes from the ledger itself | whatever the rig accepts (a commit or tag) |

The sweep programs are embedded in the `xdrcheck` binary. Each (target, version) is built once into
`$XDRCHECK_CACHE/targets/<target>/<version>/` (default `~/.cache/xdrcheck`) and reused; a tag or full commit is never
rebuilt, a branch is re-resolved on every run (pass `--offline` to use the cached build), and a changed sweep
program is rebuilt. The run manifest records both the version asked for and the version built (for `main`, the Go
pseudo-version or the package version and ref).

The SDK sweeps need the target's own toolchain: Go for `go`, Node.js 22.15 or newer and npm for `js`, Python 3
and the `zstd` command for `python`, Rust for `rust`. A missing toolchain is reported as `not available: &lt;tool>
missing`, with status `unavailable` and no rows; it is never a pass.

### Pipeline targets

Pipeline targets run through two programs:

| Program | Found as | Called as |
| - | - | - |
| rig | this binary's `xdrcheck replay --rig <target>` (the service rigs), or the command in `$XDRCHECK_RIG_WALLET_BACKEND` (`_STELLAR_ETL`, `_HORIZON`) | `RIG --ledgers @LIST --commit V --lake LAKE --network P --fetch none --out DIR`; it builds the pipeline at V, ingests the listed ledgers (ascending) from the lake-layout directory into one database and writes `DIR/rows.jsonl` in the judge's row schema; it also writes `DIR/status.jsonl` (`ingested`, `halted`, `skipped` or `harness_fault` per ledger); exit 0 every ledger was ingested, 1 a ledger halted or was skipped (rows are still judged), 2 a harness fault |
| judge | `$XDRCHECK_JUDGE`, else `xdrcheck-judge` on `PATH` | `JUDGE facts --root LAKE --list LEDGERS --network P -o FACTS.jsonl`, then `JUDGE verdict --facts FACTS.jsonl --rows ROWS.jsonl -o VERDICTS.jsonl` |

Every judge verdict other than `ok` becomes a row with check `judge-<kind>` and the judge's class; `unknown` (the
judge's truth is incomplete) has verdict `error`, the others (`missing`, `extra`, `wrong_value`, `duplicate`,
`skip`, `halt`) `fail`.

A pipeline run whose rig did not ingest every ledger is `partial`: its rows are still judged (the judge turns a halt
into a row, so a known halt stays visible to clusters and run comparison), and the summary message counts the
ledgers not ingested (see `work/rig/status.jsonl`). A run whose rig wrote no `status.jsonl`, or ingested every
ledger and wrote an empty `rows.jsonl`, is `failed`.

## Run states and exit codes

The run directory's `summary.json` has one of four states ([run-directory.md](#run-directory)):

| State | Meaning | Exit |
| - | - | - |
| `complete` | the run ran over every selected ledger (whatever it found) | 0, or 1 with `--fail-on D` when a cluster has disposition D |
| `partial` | a pipeline rig did not ingest every ledger; the rows of the run are judged but do not cover every ledger | 2 |
| `failed` | the run could not run: a build or run failure, a ledger that could not be fetched or is not local with `--offline`, a rig without per-ledger status, or no rows from fully ingested ledgers | 2 |
| `unavailable` | the target is not available on this machine (a missing toolchain); no rows, never a pass | 3 |

Bad arguments also exit 2, before any run directory is written. The rig form (`--rig`) exits as the rig does
(0, 1 or 2, above).

## Worked example: a known issue, before and after its fix

```text theme={null}
$ xdrcheck replay --issue js-stellar-sdk#1766 --out runs/1766-prefix
built js 17.2.0 (~/.cache/xdrcheck/targets/js/17.2.0)
xdrcheck js@17.2.0: complete (rows limited to the selected transactions; tested counts cover whole ledgers); 2 rows in 2 clusters -> runs/1766-prefix
  candidate            1  op-decode|Error:Assets are not in lexicographic order
  candidate            1  tx-parse|Error:Assets are not in lexicographic order

$ xdrcheck replay --issue js-stellar-sdk#1766 --fixed --out runs/1766-fixed
built js 17.2.1 (~/.cache/xdrcheck/targets/js/17.2.1)
xdrcheck js@17.2.1: complete (rows limited to the selected transactions; tested counts cover whole ledgers); 1 rows in 1 clusters -> runs/1766-fixed
  builder-default      1  tx-rebuild|rebuild-throws:TimeBounds has to be set or you must call setTimeout(TimeoutInfinite).

$ xdrcheck runs compare runs/1766-prefix runs/1766-fixed
A js@17.2.0
B js@17.2.1
-      1      0  op-decode|Error:Assets are not in lexicographic order
+      0      1  tx-rebuild|rebuild-throws:TimeBounds has to be set or you must call setTimeout(TimeoutInfinite).
-      1      0  tx-parse|Error:Assets are not in lexicographic order
```

The issue's ledger is testnet 5521432 from the corpus entry `cap-0038/pool-issuers-order-by-bytes-not-strkey`;
the pool-share trustline in its transaction 2 has issuers whose strkey text order is the reverse of their byte
order. The fixed version parses it; the builder default that remains on both is noise by disposition.

The same transaction on mainnet-style input, any version:

```text theme={null}
xdrcheck replay --target go --version v0.9.0 --tx 30941181:51
xdrcheck replay --target go --version main   --tx 30941181:51
xdrcheck replay --target go --version ../go-stellar-sdk --ledgers 30941100-30941199
```

## `issues.json`

`go/internal/hunt/issues/issues.json` (schema `schemas/issues.schema.json`) maps a public issue to its target, the version before and after the fix, the corpus entry or ledger that shows it, the transaction, and the expected check and class. Only public issues belong there.

## Dataset

The dataset is what the mainnet scan derived: the shape census per level and kind, the greedy covers, the token
census and its leads, the kept-ledger index, the locate index, the value tags, the corpus entries and the public
findings, plus named ledger sets. `xdrcheck find` and `xdrcheck replay` resolve their selections through it. A
dataset directory holds one `manifest.json` (schema `schemas/dataset-manifest.schema.json`, `xcc.dataset/v1`) that
**points at** those files with their size and sha256; large files are never copied.

```text theme={null}
xdrcheck data status   [--dataset DIR] [--verify]
xdrcheck data sets     [--dataset DIR] [--show NAME]
xdrcheck data fetch    (--ledgers LIST | --set NAME) [--out DIR] [--network pubnet|testnet] [--parallel N] [--rate R] [--from-local=false]
xdrcheck data manifest --root NAME=PATH... [--out DIR] [--version V] [--corpus DIR] [--findings DIR] [--no-hash]
xdrcheck data update   [--dataset DIR] [--to LEDGER]
```

The dataset directory is `--dataset`, else `$XDRCHECK_DATASET`, else `~/.local/share/xdrcheck/dataset`. The ledger cache is
`--lake`, else `$XDRCHECK_LAKE`, else `<dataset>/lake`.

### The manifest

| Key | What |
| - | - |
| `version`, `tip_ledger`, `network`, `created` | the dataset version and the newest ledger its census counted |
| `roots` | named directories: `derived` (census, covers, tokens, leads, kept-ledger index), `kept` (a lake-layout directory of kept ledgers), `scan` (the full scan's per-block Parquet), `hunt` (locate index, value tags, generated ledgers). `$XDRCHECK_DATASET_ROOT_<NAME>` moves a root, so one manifest serves machines whose data lives elsewhere |
| `lakes` | read-only lake-layout directories searched for a ledger before the cache |
| `tables` | per table: format (`tsv` with a header line, optionally zstd; `parquet`; `locate-index`), its files as `${root}/path` with bytes and sha256, or a glob whose checksums are the scan's own `MANIFEST.json` files, columns taken from file names, or `missing` with the reason (the producer has not run) |
| `sets` | per named set: a file of ledgers (`unit: ledger`) or of `ledger<TAB>tx_index` (`unit: tx`), its count |

Tables: `shapes` (every distinct shape per level G0–G3 and kind, with occurrences and first/last ledger),
`census_summary`, `census_facts`, `tokens`, `covers`, `cover_summary`, `rare_tokens`, `value_extremes`,
`event_signatures`, `rare_results`, `rare_change_cells`, `kept_ledgers`, `kept_tx_shapes`, `kept_components`,
`scan_occurrences`, `scan_tx_shapes`, `scan_components`, `locate`, `tags`, `tag_summary`, `corpus_entries`,
`findings`.

Sets: `controls`, `kept`, `token-cover`, `g0-cover`, `cap-<n>` (the corpus ledgers of each CAP captured from the network's history), and
`never-seen-generated` (ledgers a local stellar-core closed for arms mainnet has not shown).

### Worked example

```text theme={null}
$ xdrcheck data manifest --out ~/.local/share/xdrcheck/dataset --version 2026-11-17.1 \
    --root derived=/srv/xdrcheck/derived --root kept=/srv/xdrcheck/kept --root scan=/srv/xdrcheck/scan --root hunt=/srv/xdrcheck/hunt
dataset 2026-11-17.1, tip 65505999: 22 tables, 25 sets -> ~/.local/share/xdrcheck/dataset/manifest.json

$ xdrcheck data status
dataset   2026-11-17.1 (2026-11-17T13:36:23Z)
network   pubnet
tip       ledger 65505999
…
tables:
  kept_tx_shapes     tsv       1 files  715.8 MB  size-ok
  locate             missing: the locate index has not been built (xdrcheck-corpus scan locate-build)
  shapes             tsv      32 files    1.9 GB  size-ok
  tags               tsv       1 files  113.5 MB  size-ok
  tokens             tsv       1 files  616.3 KB  size-ok
…
$ xdrcheck data sets
cap-38                         2 tx      corpus examples of CAP 38 from pubnet history
controls                      21 ledger  control ledgers: each holds a property a check must flag
g0-cover                   98594 ledger  the fewest ledgers that show every G0 shape at least once
never-seen-generated           -  not available: the core generator has not produced ledgers
token-cover                 8116 tx      the fewest transactions that show every token at least once
…
$ xdrcheck find --class 'V|u64band' --limit 5 --format ledgers > ledgers.txt
$ xdrcheck data fetch --ledgers @ledgers.txt --out ./lake --from-local=false
5 ledgers into ./lake in 0.8s: map[ok:5], 158.9 KB downloaded
$ xdrcheck data fetch --ledgers @ledgers.txt --out ./lake
5 ledgers into ./lake in 0.0s: map[have:5], 0 B downloaded
```

`fetch` writes the lake layout (`<partition>/<object>.xdr.zst`) and an `index.tsv` (`seq path size md5`). Each
download is checked against `Content-Length` and the `ETag` (the public lake's objects are single-part, so the
ETag is their MD5); a mismatch is retried with back-off and then reported, never written. At most 256 requests
are in flight (`--parallel`, default 64) and `--rate` caps requests per second (default 200). It is resumable: a
ledger already in the cache with its recorded size and MD5 is kept. With `--from-local` (default) a ledger a
read-only lake of the dataset holds is copied, not downloaded.

### Keeping the data current: `xdrcheck data update`

`update` prints the plan of a top-up from the tip and runs nothing. The dataset is append-only: a top-up adds one
new block of every table for the ledgers after the tip (scan, census, token census, cover additions, locate, value
tags) and writes a new manifest version that lists the old files unchanged plus the new ones. A run directory
records the dataset version and the manifest's sha256 it resolved its selection through, and old versions' files
never change, so old runs stay reproducible.

## find

`xdrcheck find` answers "which mainnet transactions show X?" with `ledger`, `tx` pairs that `xdrcheck data fetch` and
`xdrcheck replay --tx` take as they are. It reads the dataset's plain index files ([data.md](#dataset)); there is no
query engine.

```text theme={null}
xdrcheck find (--token T | --class K|C | --token-contains S | --tag TAG | --cap N | --assumption KEY | --op TYPE | --set NAME)
         [--order first|last|rarest|random] [--limit N] [--seed N] [--source auto|locate|kept]
         [--format tsv|json|ledgers] [--dataset DIR] [--corpus DIR]
xdrcheck find --list-assumptions
```

| Selector | Answered from | | | |
| - | - | - | - | - |
| `--token` (text \`K | class | path`, or the 32-hex token id), `--class K | class\` | the locate index (every transaction in all history, through `xdrcheck-corpus scan locate`), else the kept-ledger index (kept ledgers only; a note says so) |
| `--token-contains S` | the kept-ledger index | | | |
| `--tag TAG` (`u64>=2^63`, `text:nonutf8`, `token_event:nonsac:*`, …) | the value tags; a trailing `*` matches a prefix | | | |
| `--cap N` | the corpus ledgers captured from network history whose entry names the CAP (any network), and the dataset's `cap-N` set; local-core ledgers are left out, since their sequence numbers name unrelated network ledgers (`replay --cap` runs them from the corpus) | | | |
| `--assumption KEY` | an xdrlint assumption key (the `assumption` field of a diagnostic), mapped to a tag, a token class or a token substring by `go/internal/hunt/find/assumptions.json`; an unmapped key is reported as not available | | | |
| `--op TYPE` | the operation types of the kept-ledger index (`PAYMENT`, `LIQUIDITY_POOL_DEPOSIT`, …) | | | |
| `--set NAME` | a named set | | | |

Orders: `first` and `last` by ledger, `rarest` by the census occurrences of the rarest matched token, `random`
with `--seed`.

| Exit | Meaning |
| - | - |
| 0 | results |
| 1 | no results |
| 2 | bad arguments |
| 3 | the source it needs is not available |

### Worked examples

```text theme={null}
$ xdrcheck find --class 'V|u64band' --limit 5
note: stopped at the first matches in ledger order: the matched count is a lower bound (use --order last or rarest for the full count)
note: locate index: not available: table locate missing (…); answered from the kept-ledger index (kept ledgers only)
5 transactions matched (kept-ledger index); 5 shown, order first
ledger	tx	match	occurrences	source
30941181	51	class:V|u64band	287792	kept
30941857	13	class:V|u64band	287792	kept
30942182	43	class:V|u64band	287792	kept
30942415	11	class:V|u64band	916285	kept
30942541	35	class:V|u64band	916285	kept

$ xdrcheck find --cap 38 --limit 3
3 transactions matched (corpus); 3 shown, order first
ledger	tx	match	occurrences	source
5521432	2	testnet corpus cap-0038/pool-issuers-order-by-bytes-not-strkey		corpus
38115806	5	pubnet corpus protocol-18/upgrade-ledger-header-18-claim-atom-v0		corpus
41232715	19	pubnet corpus cap-0038/claim-atoms-pool-and-order-book-mixed		corpus

$ xdrcheck find --op LIQUIDITY_POOL_DEPOSIT --limit 2
ledger	tx	match	occurrences	source
38115811	134	op:LIQUIDITY_POOL_DEPOSIT		kept
38115811	402	op:LIQUIDITY_POOL_DEPOSIT		kept

$ xdrcheck find --list-assumptions
text-to-db:memo              tag text:nonutf8                         strings (memos among them) with invalid UTF-8
…
```

From a linter diagnostic to a replay:

```text theme={null}
xdrcheck find --assumption text-to-db:memo --limit 20 --format ledgers > l.txt
xdrcheck replay --target wallet-backend --version <commit> --ledgers @l.txt
```

## Run directory

Every `xdrcheck replay --target` run writes one directory. It is what the dashboard, `xdrcheck repro pack`, `xdrcheck runs`
and a CI job read; nothing else of a run is a contract. The JSON Schemas are in `schemas`, and the
`xdrcheck` binary carries a copy, so `xdrcheck runs validate DIR` checks a directory without a checkout.

| File | Schema | Content | |
| - | - | - | - |
| `manifest.json` | `run-manifest.schema.json` (`xcc.run/v1`) | tool and version; the dataset version (and the manifest's sha256) the selection went through, or `null`; target; version asked for, version built and where from; network; the selection; every input ledger with its object key and sha256; the command line; host (operating system, architecture, CPUs; the host name only with `XDRCHECK_REPORT_HOST=1`); start and finish | |
| `verdicts.jsonl` | `run-verdict.schema.json` (one object per line) | one row per result that is not a pass: `ledger`, `tx` (0-based apply order; `null` for a ledger-level row), `tx_hash`, `op` (`null` when the row is about the whole transaction), `op_type`, `check`, `class`, `verdict` (`fail`, `error`, `unavailable`), `evidence` (`detail`: the message, values stripped from the class only) | |
| `clusters.json` | `run-clusters.schema.json` (`xcc.run.clusters/v1`) | rows grouped by \`check | class`: counts of rows, transactions and ledgers, first and last ledger, operation types, rows per dataset stratum, up to five examples, `disposition`, `note`, `finding\` |
| `summary.json` | `run-summary.schema.json` (`xcc.run.summary/v1`) | `status` (`complete`, `partial`, `unavailable`, `failed`) and `message`; rows per verdict; per check how often it ran and how often it did not pass; clusters per disposition; cost (wall, CPU, build seconds, ledgers, transactions) | |
| `work/` | none | the target's raw output, build and run logs, the input list, the reference cut; useful for debugging, not stable | |

Passes are not rows: a check that ran a million times and failed twice gives two rows and `tested: 1000000` in
the summary. With `--tx`, rows are limited to the selected transactions while the tested counts still cover the
whole ledgers (the summary's message says so).

### Cluster keys and dispositions

The key is `check|class` and leaves out the version, so the same defect has the same key at every version of the
target: `xdrcheck runs compare A B` lists the keys a fix removed (`-`) or a change brought (`+`). The class is the
target's message with values removed (strkeys, hex, numbers, quoted strings), or a structured difference such as
`rebuild-differs:cond:v2>v2`.

A disposition says what a cluster is:

| Disposition | Meaning |
| - | - |
| `candidate` | nothing explains it: look at it |
| `by-design`, `builder-default`, `dialect`, `expected-refusal`, `recipe-artefact`, `harness` | noise that the target's own documentation or design explains |

The public table (`go/internal/hunt/rundir/dispositions.tsv`) holds noise rules only and never names a finding.

### `xdrcheck runs`

```text theme={null}
$ xdrcheck runs validate runs/1766-prefix runs/1766-fixed
valid runs/1766-prefix
valid runs/1766-fixed
$ xdrcheck runs compare runs/1766-prefix runs/1766-fixed
A js@17.2.0
B js@17.2.1
-      1      0  op-decode|Error:Assets are not in lexicographic order
+      0      1  tx-rebuild|rebuild-throws:TimeBounds has to be set or you must call setTimeout(TimeoutInfinite).
-      1      0  tx-parse|Error:Assets are not in lexicographic order
```

`validate` checks each file against its schema and that `verdicts.jsonl`, `clusters.json` and `summary.json` count
the same rows (exit 1 on any problem). `compare` exits 1 when the two runs differ in their keys.

### Example rows

```text theme={null}
{"ledger":5521432,"tx":2,"tx_hash":"0126748091930959a3aefac9296e1773b947f964a9b73f37ce856c4df32d346f","op":null,"op_type":"changeTrust","check":"tx-parse","class":"Error:Assets are not in lexicographic order","verdict":"fail","evidence":{"detail":"Error: Assets are not in lexicographic order"}}
{"ledger":5521432,"tx":2,"tx_hash":"0126748091930959a3aefac9296e1773b947f964a9b73f37ce856c4df32d346f","op":2,"op_type":"changeTrust","check":"op-decode","class":"Error:Assets are not in lexicographic order","verdict":"fail","evidence":{"detail":"Error: Assets are not in lexicographic order"}}
```

## repro

Use a bundle to hand one result to an SDK or pipeline maintainer: it holds the ledger, the transaction, the command
and a standalone script, and runs on a clean machine.

| Command | Does |
| - | - |
| `xdrcheck repro pack` | cuts one result out of a run directory into a self-contained directory |
| `xdrcheck repro run` | runs the bundle on another machine and says whether the result came back |
| `xdrcheck repro verify` | checks that the input is a real ledger that stellar-core accepts |

```text theme={null}
xdrcheck repro pack RUN_DIR --cluster 'CHECK|CLASS' [--tx LEDGER:INDEX] [--out DIR]
xdrcheck repro run BUNDLE [--version V] [--out DIR]
xdrcheck repro verify BUNDLE
```

### What a bundle holds

| File | What |
| - | - |
| `bundle.json` | schema `xcc.bundle/v1` (`schemas/bundle.schema.json`): target, the version asked for and the version built, network, cluster key, ledger, transaction and its hash, the expected verdict (`check`, `class`), the one command that reproduces it, the standalone script, every input file with its sha256, the ledger header hash and the stellar-core commands |
| `ledger/<seq>.xdr.zst` | the ledger object, byte for byte as the run read it (for a pubnet ledger, the public lake's object) |
| `meta-<seq>.xdr` | the same `LedgerCloseMeta` as a one-record stream, the form `stellar-core dump-xdr` reads |
| `tx.envelope.b64` | the transaction's envelope (when the result is about a transaction) |
| `tx.meta.b64` | the transaction's meta (same condition); the JS and Python scripts convert its contract values with `scValToNative` / `scval.to_native` |
| `repro.mjs`, `main.go`, `repro.py` or `main.rs` | a standalone script of at most 20 lines that shows the result with the SDK alone (SDK targets) |
| `README.md` | the same, in words |

`repro run` checks every file's sha256 and the ledger header hash, then runs the bundle's command (an
`xdrcheck replay --target … --ledger-file ledger/<seq>.xdr.zst --tx …`) into `BUNDLE/run`, and looks for a row with the
expected check and class on the expected transaction. `--version` runs another version: a fixed version should give
`NOT REPRODUCED`.

| Exit | `repro run` result |
| - | - |
| 0 | `REPRODUCED` |
| 1 | `NOT REPRODUCED` |
| 2 | the replay could not run |
| 3 | the target is not available on the machine |

`repro verify` recomputes the header hash (sha256 of the `LedgerHeader` equals the hash the `LedgerCloseMeta`
records), and runs the stellar-core commands when `stellar-core` is on `PATH` or in `$XDRCHECK_STELLAR_CORE`:

```text theme={null}
stellar-core dump-xdr --compact meta-<seq>.xdr          # core's own decoder reads the whole LedgerCloseMeta
stellar-core print-xdr --filetype tx --base64 tx.envelope.b64
```

For a pubnet ledger the README also gives the public lake URL of the object, so `curl -s URL | sha256sum` shows
the bytes are the network's own.

### Worked example: js-stellar-sdk #1766 on a clean machine

```text theme={null}
$ xdrcheck replay --issue js-stellar-sdk#1766 --out runs/1766
$ xdrcheck repro pack runs/1766 --cluster 'tx-parse|Error:Assets are not in lexicographic order' --out bundles/js-1766
bundle bundles/js-1766: js 17.2.0, ledger 5521432 tx 2, expect tx-parse Error:Assets are not in lexicographic order
  reproduce: xdrcheck repro run bundles/js-1766
```

Copy `bundles/js-1766` anywhere a checkout of this repository and Node.js are, then one command:

```text theme={null}
$ xdrcheck repro run bundles/js-1766
$ xdrcheck replay --target js --version 17.2.0 --network testnet --ledger-file …/ledger/5521432.xdr.zst --out …/run --force --tx 5521432:2
built js 17.2.0 (~/.cache/xdrcheck/targets/js/17.2.0)
xdrcheck js@17.2.0: complete (rows limited to the selected transactions; tested counts cover whole ledgers); 2 rows in 2 clusters -> …/run
  candidate            1  op-decode|Error:Assets are not in lexicographic order
  candidate            1  tx-parse|Error:Assets are not in lexicographic order
REPRODUCED tx-parse Error:Assets are not in lexicographic order on ledger 5521432 tx 2 with js 17.2.0

$ xdrcheck repro run bundles/js-1766 --version 17.2.1 --out /tmp/fixed | tail -1
NOT REPRODUCED tx-parse Error:Assets are not in lexicographic order on ledger 5521432 tx 2 with js 17.2.1

$ xdrcheck repro verify bundles/js-1766
ok   files match bundle.json; ledger 5521432 header hashes to 99efd5ab770fe7f4369735804f6d2c2e372020ff832e0c8cc1ae8ff7b35e4bec
```

And without the kit:

```text theme={null}
$ cd bundles/js-1766 && npm install @stellar/stellar-sdk@17.2.0 && node repro.mjs
tx-parse throws Error: Assets are not in lexicographic order
op-decode throws Error: Assets are not in lexicographic order
```

A bundle names no internal finding: its cluster key is the target's own message, and dispositions are not copied
into it.


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