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:
- Every job of the full CI (
.github/workflows/full.yml) green on the release commit. On av*tag the same workflow runs every check and refuses a tag that is not on the default branch. - A
CHANGELOG.mdentry: new entries, superseded entries, pin changes, known-divergence changes. - 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 separatestress/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). - The archive is built from the committed tree only (
git archive), andmake releasescans the extracted archive for machine paths and private names (release.md §4). - 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.
- 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 abovecorpus.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:
- 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
-updatesbuild cannot breakmake fetch. The testnet lake prefix inpins.toml[public_lake](testnet/2025-12-18) goes stale at the testnet reset on 2026-12-16. It is a[[schedule]]event:xdrcheck pins checkwarns 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 runxdrcheck-corpus refetch(section 8). - Step 1, shape freeze. Run the SDK releases built from the Protocol 31 XDR through
xdrcheck conform runandxdrcheck 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. - Step 2, pin moves. Move the XDR definitions commit and rs-stellar-xdr first: fix the
crates/xdrcheck-metamatches the compiler names, then the oracle-version constantsxdrcheck pins checknames.soroban_sdkis 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. - Step 10, raising the gates. In one change:
protocol.max_supported = 31and every constantxdrcheck pins checknames. 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-ceilingswrites them into all five drivers from the vendored definitions (orxdrcheck xdr ceilings --write --defs <tag>straight from stellar-xdr); the generator needs the Protocol 31 network settings and host before its ranges are raised. - 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 abovemax_protocol is read, not refused, by the tools that
read the live network:
xdrcheck-corpus capturekeeps the object and printswarning: ledger protocol 31 is above the supported maximum 30 .... With--entryit refuses before writing anything, because the corpus gate would refuse the entry.xdrcheck-corpus minedecides such ledgers like any other, marks each kept oneabove_max_protocol, and counts them inmined.json.- A ledger that does not decode with the pinned definitions is a shape change, not a number-only upgrade.
minelists it underundecodedwith the definition and value the bytes leave (for exampleTransactionMeta: no arm for 5) and goes on.capturekeeps the object, as served, under<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’scurrent_protocol_versionpassesprotocol.max_supported.
curr branch since the pinned tag, and a ledger at the new
protocol decodes (the warnings above, with nothing undecoded):
- Move
[stellar_core]to the release that supports the new protocol (version, commit, package URL and hashes, images) and runmake fetch. - Raise
protocol.max_supportedand every constantxdrcheck pins checknames (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. - Regenerate (
make verify-generate, thenxdrcheck-corpus genfor the scenarios that run at the top protocol), and capture the upgrade ledger on both networks (xdrcheck-corpus capture <network> <ledger> --entry ..., now accepted). make verify-static verify-corpus verify-conformance, then release31.0.0(the release MAJOR is the protocol, section 3).
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 overpins.tomlthat opens one pull request per pin move, weekly; the Go modules move together withgo/go.modandlint/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’sCargo.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.--listprints the list offline.
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:
- Point
[stellar_core]at the build:binary_sha256frommanifest.json,versionandcommitfrom its commit. The generator checks the binary againstbinary_sha256and takes it fromXDRCHECK_STELLAR_CORE(its libraries from../lib/x86_64-linux-gnubeside it), so exportXDRCHECK_STELLAR_CORE=<cache>/stellar-core-vnext/<commit>/pkg/usr/bin/stellar-core. - Raise
protocol.max_supportedto the build’s ledger protocol and every constantxdrcheck pins checknames, and move rs-stellar-xdr to a version built from the stellar-xdrnextbranch: the oracle cannot read shapes the pinned definitions lack. - Write the scenarios for the arms the next protocol adds and run
xdrcheck-corpus genon 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:
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-warningnames, on itsarmsline, the arms stellar-core’s own XDR submodule has that the pins lack; adecodefailure there is explained by that list. Afetchorlayoutfailure 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> pinnedis the authoritative list of new shapes; merge the candidate rows that hold, with reasons, andmake 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 apins.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
historyentry 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: truewith 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 refetchreports a perishable object whose source has disappeared asgonewithout 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 inCONTRIBUTING.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 isxdrcheck-<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
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 instress/, 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):
- its ID is in the
limits/group; - a known divergence at a conformance level (not
replay) records the outcomecrashorhang; - a known divergence names an address-space sandbox as its profile (
address-space cap RLIMIT_AS <n> MiB|GiB, conformance-protocol.md).
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_versionincorpus.jsonandcoverage.json, and the version in the first paragraph ofCOVERAGE.md, are set to the release version (on every corpus root that has the file);manifest.sha256is written in each corpus root;- stress entries and the files only they reach are moved from
corpus/tostress/(section 3), their recipes with them; a recipe whose entry is in neither root is left out; corpus.jsontiers.curated(entries,blobs,bytes) is set, in each root, to that root’s own counts, socorpus/andstress/each state what they hold;PROVENANCE.jsonentriesrepeats 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,locatorandevidence. The plan schema (schema/plan.schema.jsonand its examples), which requires those fields, is left out of the archive;xdrcheck-corpus verifyreads 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:
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 inPROVENANCE.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
0644for files and0755for 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:
- builds it a second time and compares the sha256 of the two archives;
- extracts it into an empty directory, copies in only a built
xdrcheck-corpus, checksSHA256SUMS, checks that every file a manifest of either root names (blobs/,decoded/,chains/andrecipes/paths) is in that root (scripts/release.sh refs ARCHIVEruns 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 verifyand the same on<dir>/stresswith every check exceptag1andag3; those two compare golden entries with stellar-core’s own golden files, which are fetched bymake fetchand are not in the archive, so they run in addition, with--goldens, when the golden cache is present; - runs the npm package’s unit tests, packs it around the archive (
dist/xdrcheck-<version>.tgz) and runs the wholecorpus/root through it against the pinned JavaScript SDK, also offline, with the entries’ declared divergences as the baseline (use-in-sdk-ci.md); - 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
-nextarchive carries it and names it inPROVENANCE.json(scripts/release.sh channelsruns this alone); - writes
dist/SHA256SUMSand the release provenance over every asset of the version indist/(section 9).
-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 intodist/ 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:
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.