Skip to main content
For SDK maintainers and indexer operators who pin the kit, and for whoever maintains it. After this page you know how corpus versions and releases work, what happens to the corpus and the tools at each protocol upgrade and in what order, which upstream sources are watched, and how a wrong entry is corrected. Each statement names the file, command or job that shows it holds.

1. What is kept current

2. Maintainer and support period

Sizing: Stellar protocol upgrades have come about every two months (six mainnet upgrades in the twelve months to November 2026). Testnet has led mainnet by 1 to 20 days, and the stable stellar-core release has led the mainnet vote by 26 to 45 days when the upgrade added XDR, by about 2 days for Protocol 24 and not at all for Protocol 29 (section 5.5). A one-year period spans several upgrades, not one; the procedure in section 5 is written to be repeated, with a one-day path for upgrades that change no XDR (section 5.2).

3. Versioning and releases

Release procedure:
  1. Every job of the full CI (.github/workflows/full.yml) green on the release commit. On a v* tag the same workflow runs every check and refuses a tag that is not on the default branch.
  2. A CHANGELOG.md entry: new entries, superseded entries, pin changes, known-divergence changes.
  3. A release archive: manifest, blobs, decoded sidecars, schemas, coverage report, checksums and build provenance. Entries built to stress a reader (the limits/ group, and entries whose known behaviour is a crash, a hang or a memory-capped run) sit in a separate stress/ directory of the archive and are excluded from a default run, because the archive is meant to run inside other projects’ CI. Small negative vectors stay in the default set: a reader must refuse them, and refusing them costs nothing (release.md).
  4. The archive is built from the committed tree only (git archive), and make release scans the extracted archive for machine paths and private names (release.md §4).
  5. Thin per-language packages that carry the archive and check its hash before use, so an SDK’s CI can run the corpus without a submodule (use-in-sdk-ci.md). None is on a package registry yet.
  6. A status update (section 11).

4. The kit’s own fail-closed gates

The kit follows the rule it recommends: it refuses what it does not know instead of guessing. The oracle refuses a ledger above corpus.json max_protocol (equal to pins.toml protocol.max_supported, 30 today) or above max_ledger_close_meta_version, with a typed error naming the value found and the maximum; corpus.json can lower that gate but never raise it above the protocol the build was made for (a higher max_protocol is refused with an error); drivers report an XDR arm their SDK does not know as union_arm_undeclared or enum_undeclared; xdrcheck pins check fails on any version named outside pins.toml and on any protocol or oracle-version constant in the kit’s own code that differs from it. Raising a gate is the procedure in section 5, never a one-line change. Details: docs/architecture.md. One deliberate exception: the tools that read the live network (xdrcheck-corpus capture and xdrcheck-corpus mine) read a ledger above max_protocol instead of refusing it, so a protocol upgrade made with little notice does not stop them on the day it matters (section 5.2). They warn, never make a corpus entry from such a ledger, and name any shape the pinned definitions cannot decode. The meta-version gate stays closed for them too.

5. Procedure for a protocol upgrade

Worked as Protocol 30 → 31; the same steps repeat for every upgrade. Each step has an output that can be inspected. The watch and nightly workflows named below run by hand only (workflow_dispatch); none has a schedule, so nothing runs unattended. Run them when a step calls for it, or make <target> on a workstation. Rules that hold throughout: released entries are never edited; entries at older protocols stay in the corpus and keep being verified; an expectation whose meaning changes at the new protocol becomes a new entry, with the protocol range stated on both. A LedgerCloseMeta version 3 has been discussed publicly and drafted on the stellar-xdr branch lcm_v3, but is in no stellar-core release. Meta versions are not protocol-gated, so it could arrive with or without a protocol bump. The kit is prepared: the meta-version gate refuses it until reviewed, the manifest records the meta version per variant, record framing is parsed by the kit’s own code, not by a library default, and the XDR watch reports the branch as a standing item on every run (section 5.6).

5.1 Protocol 31: what fails, and in what order to update

Every place where the kit encodes Protocol 30 fails loudly when the new protocol arrives; none passes silently. Order, mapped onto the steps of section 5:
  1. Now, before anything moves. The stellar-core runtime libraries are fetched from snapshot.ubuntu.com URLs, with the plain archive pool as the fallback, so a superseded Ubuntu -updates build cannot break make fetch. The testnet lake prefix in pins.toml [public_lake] (testnet/2025-12-18) goes stale at the testnet reset on 2026-12-16. It is a [[schedule]] event: xdrcheck pins check warns from two weeks before and fails from the day after until the prefix moves, and the network-state job fails as soon as testnet’s ledger sequence restarts. Move the prefix to the new epoch’s and run xdrcheck-corpus refetch (section 8).
  2. Step 1, shape freeze. Run the SDK releases built from the Protocol 31 XDR through xdrcheck conform run and xdrcheck conform diff. Such a release reports no protocol, so its refusals of Protocol 31 variants appear as failures in the diff: that is the readiness signal, not noise to suppress.
  3. Step 2, pin moves. Move the XDR definitions commit and rs-stellar-xdr first: fix the crates/xdrcheck-meta matches the compiler names, then the oracle-version constants xdrcheck pins check names. soroban_sdk is pinned at 29.0.1 for the test contracts (30.0.0 existed only as a release candidate when the pin was set): move it to the release that matches the new soroban-env-host, rebuild the contracts and confirm their hashes, or record why it stays.
  4. Step 10, raising the gates. In one change: protocol.max_supported = 31 and every constant xdrcheck pins check names. Each driver also needs a probe for a Protocol 31 feature (with its protocol in the probe table) and the Protocol 31 maximum of each sentinel enum, read from the XDR definitions at the new tag, not from an SDK: make xdr-ceilings writes them into all five drivers from the vendored definitions (or xdrcheck xdr ceilings --write --defs <tag> straight from stellar-xdr); the generator needs the Protocol 31 network settings and host before its ranges are raised.
  5. SDK pin moves. Each driver’s tests assert the protocol every pinned version reports (31 for a version with the Protocol 31 probes, 30 for one without), so a pin move that the driver cannot bound fails there first.

5.2 Number-only upgrades: the one-day path

Some upgrades change no XDR: Protocol 24 (a fix, about two days between the stable stellar-core release and the mainnet vote) and Protocol 29 (a security release, published after the vote). Section 5 is weeks of work; these need a day, and may need it with no notice. What the tools do before anyone acts. A ledger above max_protocol is read, not refused, by the tools that read the live network:
  • xdrcheck-corpus capture keeps the object and prints warning: ledger protocol 31 is above the supported maximum 30 .... With --entry it refuses before writing anything, because the corpus gate would refuse the entry.
  • xdrcheck-corpus mine decides such ledgers like any other, marks each kept one above_max_protocol, and counts them in mined.json.
  • A ledger that does not decode with the pinned definitions is a shape change, not a number-only upgrade. mine lists it under undecoded with the definition and value the bytes leave (for example TransactionMeta: no arm for 5) and goes on. capture keeps the object, as served, under &lt;cache>/beyond-gate/ (a testnet upgrade ledger does not stay available), and fails with that same message. Follow section 5.
  • The network-state job (make watch-network, section 5.5) fails the night a network’s current_protocol_version passes protocol.max_supported.
The path, once the upgrade is known to change no XDR. The upgrade changes no XDR when the stellar-xdr repository has no new tag and no change on its curr branch since the pinned tag, and a ledger at the new protocol decodes (the warnings above, with nothing undecoded):
  1. Move [stellar_core] to the release that supports the new protocol (version, commit, package URL and hashes, images) and run make fetch.
  2. Raise protocol.max_supported and every constant xdrcheck pins check names (section 5.1). With no new shapes, the drivers need only the new protocol number in their probe tables and enum ceilings; the generator needs the new protocol’s network settings and soroban-env-host, which the stellar-core release names.
  3. Regenerate (make verify-generate, then xdrcheck-corpus gen for the scenarios that run at the top protocol), and capture the upgrade ledger on both networks (xdrcheck-corpus capture <network> <ledger> --entry ..., now accepted).
  4. make verify-static verify-corpus verify-conformance, then release 31.0.0 (the release MAJOR is the protocol, section 3).
If step 2 needs a new probe because the release changed behaviour without changing XDR, the upgrade is not number-only: continue with section 5.

5.3 Pin moves and the latest-SDK canary

The pins that follow an upstream release carry a # renovate: datasource=... depName=... comment in pins.toml. Two things read that list:
  • renovate.json: a Renovate regex manager over pins.toml that opens one pull request per pin move, weekly; the Go modules move together with go/go.mod and lint/go.mod. The conformance driver directories are historical columns and are never bumped. Some moves need hand steps, which the pull request body lists (stellar-core’s package hashes and images, a crate’s Cargo.lock, a new driver column for an SDK).
  • xdrcheck pins latest: the same list against the newest stable release on npm, PyPI, the Go module proxy, crates.io and git tags, with no bot. --list prints the list offline.
The canary (make nightly-canary, workflow watch-canary.yml, run by hand) runs xdrcheck pins latest and reports each pin behind upstream. For each SDK family with a driver (JavaScript, Go, Python, Rust), when the newest release is not yet a pinned conformance column, it builds a throw-away canary column for that release outside the working tree, from the newest pinned column’s driver code, runs the curated corpus through both, and lists the cells whose verdict differs (xdrcheck conform diff). It reports drift and fails only when it cannot run, so it never blocks a pull request; its summary is the input to the pin-move pull request. XDRCHECK_CANARY_PLAN=1 stops after the plan.

5.4 The next-protocol stellar-core build

stellar-core’s next protocol exists on its master branch behind the configure flag --enable-next-protocol-version-unsafe-for-production, weeks before a release. The job (make vnext-core, run by hand, workflow vnext-core.yml) builds master that way in the pinned build container (pins.toml [images] vnext_build_base, with the toolchain stellar-core’s own testing Dockerfile uses), checks that the binary supports a ledger protocol above protocol.max_supported, and keeps the result by commit under ${XDRCHECK_CACHE:-~/.cache/xdrcheck}/stellar-core-vnext/<commit>/: pkg/usr/bin/stellar-core, its C++ runtime libraries in pkg/usr/lib/x86_64-linux-gnu/, and manifest.json (commit, flags, binary sha256, stellar-core version output, ledger protocol). The run uploads the same as its artefact. VNEXT_PLAN=1 prints the plan without building; the build itself takes about an hour. To emit next-protocol entries early with it, on a working branch that is never merged as it is:
  1. Point [stellar_core] at the build: binary_sha256 from manifest.json, version and commit from its commit. The generator checks the binary against binary_sha256 and takes it from XDRCHECK_STELLAR_CORE (its libraries from ../lib/x86_64-linux-gnu beside it), so export XDRCHECK_STELLAR_CORE=<cache>/stellar-core-vnext/<commit>/pkg/usr/bin/stellar-core.
  2. Raise protocol.max_supported to the build’s ledger protocol and every constant xdrcheck pins check names, and move rs-stellar-xdr to a version built from the stellar-xdr next branch: the oracle cannot read shapes the pinned definitions lack.
  3. Write the scenarios for the arms the next protocol adds and run xdrcheck-corpus gen on them. The entries made this way are drafts for the upgrade (section 5, step 5); they become corpus entries when the release they were made against is pinned.

5.5 Signals, lead times and dated events

Measured over Protocols 22 to 30, earliest first. Section 6 lists every watched source; these are the ones with a measurable lead before the testnet upgrade. Upgrades without XDR changes come with the least notice: about two days for Protocol 24, none for Protocol 29. Dated events in pins.toml. Each announced mainnet vote and testnet reset is a [[schedule]] table: the event, its date (UTC), the source of the date, the pin it changes (pin), the value that pin holds until then (until) and what to do afterwards (action). xdrcheck pins check, offline in every pull request, reads them against today: from 14 days before it warns, after the day it fails until the pin has moved, then reports the event as done until it is removed. --today YYYY-MM-DD shows what a given day will say. With --network (the network-state job, make watch-network, workflow watch-drift.yml) it also reads the Horizon root of mainnet and testnet and the status page’s scheduled maintenances: a network above protocol.max_supported or a reset testnet fails; a stale protocol.network_* pin, validators ready for a newer protocol, a status-page vote or reset that is not a [[schedule]] event, and an event less than 10 days away that the status page does not yet list each warn.

5.6 Upgrade tooling: xdrcheck xdr

Four commands turn the XDR definitions into data, so the steps above start from a list instead of a reading (cli.md has every flag): Inputs to diff are a directory of .x files, a definitions JSON (.json or .json.zst, as rs-stellar-xdr’s generator writes it, e.g. the vendored crates/xdrcheck-corpus/data/xdr-definitions-v30.0.0.json.zst), pinned, or any stellar-xdr git ref (main, lcm_v3, a tag, a commit, refs/pull/N/head), fetched read-only into a blobless clone under $XDRCHECK_CACHE/src. --base-features/--head-features choose which gates are on (none, all, or a list; the defaults compare the release with the next protocol). Examples:
The XDR watch (make nightly-xdr-watch) runs by hand on a workstation. It never fails on what it finds. It writes one digest per upcoming protocol under reports-nightly/xdr-watch/ (digest-p<N>.md: standing items first, then every source with its status, CAPs, change and new-arm counts, and “new” when its result changed since the previous run), and candidates.patch with the candidate rows from main and the CAP documents. A CAP whose document names a protocol files under that protocol’s digest; everything else under the next one. The log (watch-log.jsonl, one line per source per run) is kept in the cache (XDRCHECK_XDR_WATCH_LOG) and copied beside the digests. The candidate patch is expected to fail make verify-coverage until the pinned definitions include its arms: it is the shopping list for steps 4 and 5, not a change to merge as it is. Reading the digest at each step:
  • Step 0, continuously. A new gated block on main appears under its CAP with the arms it adds, 6 to 14 weeks before testnet; a CAP document’s diff appears as soon as it is written. Changes that reach no root (contract cost types, peer-network messages) need no corpus work.
  • Step 1, core ships the protocol. make nightly-early-warning names, on its arms line, the arms stellar-core’s own XDR submodule has that the pins lack; a decode failure there is explained by that list. A fetch or layout failure is stellar-core’s repository moving, not a decode problem.
  • Steps 2 and 4, pins and CAP rows. After the XDR pin moves, xdrcheck xdr diff <old commit> pinned is the authoritative list of new shapes; merge the candidate rows that hold, with reasons, and make xdr-ceilings.
  • No XDR change. When xdrcheck xdr diff <old tag> <new tag> is empty (Protocol 24, Protocol 29), the upgrade is the number-only path: raise the gates, regenerate nothing.

6. Watch list

7. Differential mode

Differential review is two ordinary runs and a comparison: xdrcheck conform run on the pinned and on the candidate SDK version, then xdrcheck conform diff <matrix-a> <matrix-b>; or xdrcheck replay at two commits of an indexer, then xdrcheck report diff <report-a> <report-b>. The comparison lists only what changed: entries that newly pass, newly fail, or change class. It is how a pin move is reviewed before it is merged, how the readiness matrix is built before a mainnet vote, and how a maintainer sees exactly which entries a fix changed.

8. Testnet resets

Testnet is reset on a published schedule (the next one, 2026-12-16, is a pins.toml [[schedule]] event: section 5.5). A reset removes every testnet ledger from the network, and the public lake may drop the old epoch’s prefix. After the reset, xdrcheck pins check fails until [public_lake] testnet names the new epoch, and the network-state job fails as soon as testnet’s ledger sequence is below the highest ledger vendored from the pinned epoch.
  • Every testnet history entry is vendored with its lake key, object hash, object metadata and capture time (corpus/objects/testnet/), so the corpus stays complete after a reset.
  • Testnet sources are marked perishable: true with their epoch (manifest.md §4.4); ledger sequences repeat across epochs, so a locator from an old epoch is never reused as if current.
  • After a reset xdrcheck-corpus refetch reports a perishable object whose source has disappeared as gone without failing (a missing non-perishable object fails). The entry stays valid: its bytes, hashes and provenance are in the corpus. Captures from the new epoch are new variants.
  • After a reset every testnet sequence number starts again, so envelopes signed under the testnet passphrase may become valid on the new testnet for a while. Only test funds can be involved (threat-model.md).

9. Correcting and superseding entries

A superseded entry keeps being verified by the oracle, since its bytes and hashes are still true statements. The manifest has no machine-readable supersession field yet, so harness and conformance runs do not skip superseded entries automatically.

10. Growing the corpus

A new CAP is a scenario file (or another sourcing route), manifest entries and a coverage row; the workflow and review checklist are in CONTRIBUTING.md and authoring-entries.md.

11. Support channels and status updates

Release and channels

For anyone who pins a corpus release in CI, and for whoever cuts one. After this page you know what a release contains, how it is laid out, which channel to pin, and how to check its bytes before anything reads them; and how a release is built reproducibly. The release procedure around it (version numbers, changelog, what may never be in a release) is in maintenance.md §3; the files inside the corpus are specified in manifest.md. scripts/release.sh implements this page and make release runs it.

1. Name and version

The archive is xdrcheck-<version>.tar.gz with a single top-level directory xdrcheck-<version>/. <version> is the corpus version MAJOR.MINOR.PATCH, where MAJOR is the highest Stellar protocol the corpus covers: the first release is 30.0.0, covering Protocol 30. A consumer that pins ^30.0.0 (the npm package’s version is the corpus version) therefore never receives the release covering Protocol 31; moving to it is a deliberate change of the pin. The change rule for PROVENANCE.json’s xcc.release/v1 and the other schemas is in docs/architecture.md: every /v1 schema is closed from the first release, 30.0.0, on. The release version is corpus.json corpus_version with any pre-release suffix removed (30.0.0-dev gives 30.0.0), or VERSION=<x.y.z> given to the script. The script refuses a version that is not plain MAJOR.MINOR.PATCH or whose MAJOR differs from pins.toml protocol.max_supported, with one exception: a version MAJOR.MINOR.PATCH-rc.N whose MAJOR is one above it is a release of the -next channel (section 8).

2. Layout

Both corpus/ and stress/ are complete corpus roots: each holds corpus.json, plan.json, schema/, manifest/, blobs/, decoded/, chains/, the recipes of its own entries and manifest.sha256, so a tool that takes a corpus root (xdrcheck-corpus --corpus DIR) works on either one unchanged. A blob or chain reached from both roots is in both. Nothing else in the repository is in the archive: no tool source, no reports, no findings, no evidence transcripts.

3. Stress entries

Some entries are built to stress a reader: deep nesting, length prefixes far beyond the input, allocations sized from untrusted input. Run inside another project’s CI without limits they can exhaust its memory, stack or time (threat-model.md). They sit in stress/, so a consumer who runs corpus/ never meets them and one who wants them opts in by pointing at stress/. An entry is a stress entry when any of these holds; it is the same rule by which the conformance orchestrator runs an entry in a fresh driver process (driver-protocol.md §2):
  1. its ID is in the limits/ group;
  2. a known divergence at a conformance level (not replay) records the outcome crash or hang;
  3. a known divergence names an address-space sandbox as its profile (address-space cap RLIMIT_AS <n> MiB|GiB, conformance-protocol.md).
Negative entries that meet none of these (malformed strkeys, trailing bytes, bad discriminants) stay in corpus/: a correct reader rejects them cheaply. PROVENANCE.json lists the stress entry IDs.

4. Changes the release makes to the committed files

The archive is the committed tree of one commit, with exactly these changes:
  • corpus_version in corpus.json and coverage.json, and the version in the first paragraph of COVERAGE.md, are set to the release version (on every corpus root that has the file);
  • manifest.sha256 is written in each corpus root;
  • stress entries and the files only they reach are moved from corpus/ to stress/ (section 3), their recipes with them; a recipe whose entry is in neither root is left out;
  • corpus.json tiers.curated (entries, blobs, bytes) is set, in each root, to that root’s own counts, so corpus/ and stress/ each state what they hold; PROVENANCE.json entries repeats the per-root entry and blob counts;
  • plan.json, the entry-ID registry, keeps every row and each row’s description of the entry (kind, CAPs, protocol, sources, levels, shape, members) but loses the repository’s planning fields: priority, serves, locator and evidence. The plan schema (schema/plan.schema.json and its examples), which requires those fields, is left out of the archive; xdrcheck-corpus verify reads only the registry’s IDs.
make release runs the repository’s public-tree scan (scripts/py/check_public.py --tree) over the extracted archive with every rule and no exemption: no machine path, private name, internal planning label or requirement ID, and no report carrying a hostname.

5. Checksums and provenance

SHA256SUMS covers every file in the archive except itself, sorted by path, paths relative to the top-level directory:
Inside the corpus, blobs are named by their sha256 and each variant states its sidecar’s decoded_sha256 (manifest.md §2); manifest.sha256 covers the manifest files. PROVENANCE.json: PROVENANCE.json also states the channel (stable or next, section 8), and entries.next lists the next-protocol entry IDs of a -next release (empty in a stable one). The provenance is not signed yet; a release workflow would attach a signed build attestation for the archive’s sha256.

6. Reproducibility

The same commit gives a byte-identical archive with the same tool versions (those in PROVENANCE.json):
  • input is git archive <commit>, so only committed files are read and the working tree, untracked and ignored files never are;
  • every file and directory has the commit’s timestamp as its modification time, owner and group 0 with no names, mode 0644 for files and 0755 for directories and executables;
  • entries are sorted by name (tar --sort=name) in the POSIX ustar format, which has no access or change times;
  • the tar stream is compressed with gzip -n -9, which writes neither a file name nor a time.
make release builds the archive twice from the same commit, in separate directories, and fails unless both have the same sha256.

7. Checking a release

make release (scripts/release.sh all) builds the archive into dist/, then:
  1. builds it a second time and compares the sha256 of the two archives;
  2. extracts it into an empty directory, copies in only a built xdrcheck-corpus, checks SHA256SUMS, checks that every file a manifest of either root names (blobs/, decoded/, chains/ and recipes/ paths) is in that root (scripts/release.sh refs ARCHIVE runs this check alone), runs the public-tree scan over the extracted tree (section 4), and runs, with the network cut (scripts/offline-run.sh), xdrcheck-corpus --corpus <dir>/corpus verify and the same on <dir>/stress with every check except ag1 and ag3; those two compare golden entries with stellar-core’s own golden files, which are fetched by make fetch and are not in the archive, so they run in addition, with --goldens, when the golden cache is present;
  3. runs the npm package’s unit tests, packs it around the archive (dist/xdrcheck-<version>.tgz) and runs the whole corpus/ root through it against the pinned JavaScript SDK, also offline, with the entries’ declared divergences as the baseline (use-in-sdk-ci.md);
  4. checks the channel split (section 8) on a copy of the commit’s tree: one entry is made a next-protocol entry, and the stable archive must leave it out while the -next archive carries it and names it in PROVENANCE.json (scripts/release.sh channels runs this alone);
  5. writes dist/SHA256SUMS and the release provenance over every asset of the version in dist/ (section 9).
A -next release (make release VERSION=<MAJOR+1>.0.0-rc.N) runs steps 1, 2, 4 and 5; it has no npm package. Steps: scripts/release.sh build [OUT_DIR], scripts/release.sh check, scripts/release.sh refs ARCHIVE, scripts/release.sh npm, scripts/release.sh channels, scripts/release.sh version. The commit is COMMIT=<rev> (default HEAD). Publishing the archive or a package is a separate, manual step.

8. Channels: stable and -next

Two channels: the set every reader must pass, and an advisory set for the coming protocol. A next-protocol entry is one whose protocol.introduced, or the protocol of one of its variants, is above max_supported (shapes from stellar-core’s next-protocol build, for example). The stable channel leaves such entries out, and every blob, sidecar and chain only they reach; the -next channel carries them. A -next release refuses to build while the corpus has no next-protocol entry, so the channel never repeats the stable one under another name. A GitHub release for a -next tag is marked as a pre-release. Moving from -next to stable happens when the protocol is released and max_supported is raised: the next stable major then carries those entries.

9. Release assets, prebuilt binaries and the pin helper

A version’s assets, built into dist/ and attached to the GitHub release of its tag: The tools per platform: On macOS xdrcheck runs without the Linux process controls it uses on Linux (a parent-death signal for the processes it starts, cgroup memory limits), so the replay harness’s memory bound is not enforced there; the macOS builds are cross-compiled and not exercised by the kit’s own CI. xdrcheck-corpus, the corpus author’s tool, is built for Linux only; on macOS run it in the container image (section 10). The Go tools are static; xdrcheck-corpus links against the C library of the machine that built it (the release workflow builds it on Ubuntu 24.04). The binaries are reproducible: the same commit and toolchains give byte-identical archives. make dist-bin builds every platform of DIST_PLATFORMS (default all four) whose tools all build on this machine, says for each one it leaves out what is missing (a Rust target or cross C toolchain, typically), and with DIST_STRICT=1 fails instead. It refuses to call the binaries the commit’s when the tools’ sources differ from it under DIST_STRICT=1, and otherwise records source.dirty: true in BUILDINFO.json. make release-assets (scripts/dist.sh assemble) rewrites SHA256SUMS and the provenance over everything of the version in dist/, checks every asset against them, and runs the image smoke test (section 10). scripts/dist.sh verify DIR checks a downloaded or assembled set. The release workflow (.github/workflows/release.yml) runs on a version tag: make release on one runner, make dist-bin with DIST_STRICT=1 on an x86-64 runner (linux-amd64 and both macOS archives) and an arm64 runner (linux-arm64), then make release-assets over all of it. Its result is one workflow artifact, xdrcheck-release-<tag>, holding exactly the files to attach. The workflow only reads the repository, so attaching is the maintainers’ step, after they have looked at the run:
The pin helper. A consumer’s CI pins a version, and better also the sha256 of its SHA256SUMS, and downloads only what it needs with action/fetch-release.sh (bash, curl, tar, sha256sum or shasum; Linux and macOS). Every asset is checked against SHA256SUMS before it is extracted, the corpus also against its own SHA256SUMS, and the script prints XDRCHECK_CORPUS=… and XDRCHECK_BIN=… lines for $GITHUB_ENV or eval:
OWNER/REPO is this repository on GitHub. Options: --npm for the npm package, --repo OWNER/REPO for a fork’s releases, --base URL|DIR for a mirror or a local dist/. The GitHub Action (github-action.md) uses the same script.

10. Container image

release/Dockerfile builds an image of one version from its release assets, with nothing compiled inside: the first stage checks the corpus archive and the Linux binaries of the target architecture against SHA256SUMS and unpacks them, the corpus also against its own SHA256SUMS; the second copies them onto the same base, pinned by digest (debian:trixie-slim@sha256:…), as a non-root user. The image holds the release’s layout under /opt/xdrcheck (corpus/, stress/, pins.toml, PROVENANCE.json) with the tools in /opt/xdrcheck/bin on PATH, and works there, so the tools’ default --corpus corpus is the bundled corpus:
make dist-image (scripts/dist.sh image) builds it locally as xdrcheck-dist:<version> from dist/ with the network off, and smoke-tests it with no network: every tool starts, xdrcheck-corpus verify --checks schema,ids,hashes passes on the bundled corpus, the demo adapter’s replay of the CAP-15 and CAP-27 entries finds its planted bug, and the minimal adapter’s replay of the same entries passes. It then removes the image (KEEP_IMAGE=1 keeps it). The release workflow runs the same test; it does not push the image to a registry.