Before an xOneRS release tarball can be published, ci/qualify-artifact.sh qualify can now run the recorded state-transition corpus through the exact binary inside the tarball. Each case must write the same bytes as the pinned geth-XDC evm t8n. One case that does not run or differs refuses the tarball, and nothing is recorded. This came in PR #998 (merged 2026-11-15).

The checksum, stamp and ELF checks of the same script are covered in how to verify a release artifact. This post covers the corpus step.

Why test the packaged binary?

A test run in the source tree proves the code. It does not prove the file that operators download: that file could come from a different build. The corpus step runs the binary that was unpacked from the tarball, without a rebuild. PR #998 links this to row 2 of issue #62: the same corpus through the exact packaged binary.

What does the corpus contain?

The corpus is conformance/vectors/t8n. Each directory is one evm t8n run: the inputs (alloc.json, env.json, txs.rlp, args.json with the fork and chain id) and the outputs of the pinned geth-XDC evm, exp-result.json and exp-alloc.json. There are three cases:

REFERENCE TABLEScroll to explore all columns →
Case What it runs
transfer one value transfer
create a contract creation (SSTORE in the init code, the runtime returned)
call-log-revert a call that writes a slot and emits LOG1, a call that reverts (status 0), a transfer

The README says the inputs are written by make.py, signed with the public test key of the test-junk mnemonic on chain id 51, and the outputs by record.sh <evm> from the pinned geth-XDC.

How does the gate run?

XONE_CORPUS=conformance/vectors/t8n ci/qualify-artifact.sh qualify <ledger> <tarball>...

For each case, the script runs the packaged binary as xone evm t8n with the case's inputs, fork and chain id, then compares result.json and alloc.json with exp-result.json and exp-alloc.json using cmp. The comparison is byte for byte (qualify-artifact.sh).

The script stops with an error when:

  • a case does not run ("did not run"),
  • the result differs ("result differs from the pinned geth"),
  • the post alloc differs ("post alloc differs from the pinned geth"),
  • the corpus directory has no case.

When every case passes, the ledger line of the tarball gets corpus=<n>. A tarball for another architecture is not run on the qualifying host; the script reads its stamp from the file and leaves the run to a host of that architecture.

What did the first run show?

PR #998 records one run: a debug build of xone, packed as a tarball, gave corpus=3 (transfer, create, call-log-revert). ci/test-qualify.sh adds four failing fixtures: a differing result, a differing alloc, a binary that fails, and an empty corpus.

What is not covered yet?

PR #998 leaves these for issue #62: a corpus per cryptographic backend (aarch64 and the portable paths), failure injection with a missing or corrupt backend, the container digest, and an inventory of test doubles in shipped artifacts. The published v0.1.0 binary predates the gate; a static rebuild is tracked in issue #894.

The collected competitor articles state no claim about qualifying a packaged binary against a reference corpus, so this post has no comparison table.

Frequently asked questions

What is the t8n corpus gate?

A step of ci/qualify-artifact.sh qualify that runs the recorded evm t8n cases through the binary inside the release tarball and requires byte-equal output to the pinned geth-XDC.

How many cases does the corpus have?

Three: transfer, create and call-log-revert. The ledger line records corpus=3 when all pass.

What happens when one case differs?

The script stops, the tarball is refused, and nothing is written to the ledger. publish then refuses any file whose digest is not in the ledger.

Was the v0.1.0 release qualified this way?

No. The corpus step came in PR #998 on 2026-11-15, after v0.1.0.

Sources