BUILD.md — reproducible build & software verification (GLI CSR v2.0 §2.2; GLI-19 §2.3.2–2.3.3; NJ 13:69E-1.28(c))

How the lab rebuilds every shipped artifact from source and obtains byte-identical SHA-256 digests to those in lab/FINGERPRINTS.json.

1. Pinned toolchain (recorded in `lab/FINGERPRINTS.json → toolchain`)

Tool	Version used for the recorded manifest	Notes
Node.js	v24.14.0 (x64, Linux 6.1)	Runtime for the collection tools and `rng-node`; does not influence TypeScript output, which depends only on `typescript` + `tsconfig`.
npm	11.9.0	`package-lock.json` pins every dependency (`npm ci`).
TypeScript	5.9.3 (from the lockfile: `typescript@^5.6.0` resolved to 5.9.3)	The only compiler on the certified path. `tsc` output is deterministic: no timestamps, no absolute paths (`tsconfig.base.json` has `"declaration": true`, no `sourceMap`, no `inlineSources`).
esbuild	not used in this repo	The vendored Slot Engine V2 bundles in `packages/games/vendor/slot-engine-v2/.mjs` were produced upstream by esbuild; they are shipped as-is with their sha256 in `packages/games/vendor/MANIFEST.json`* and are not rebuilt here (see `VENDOR.txt` for the upstream commit `29756275…`).
solc	not installed in this build environment	`packages/rng-session/contracts/RngAnchor.sol` (source fingerprinted) is not compiled by the build. The deployed verifier contracts live in `rain-risk-markets`; their bytecode is verified on Sourcify/Arbiscan (`docs/RNG.md` §0). To add bytecode fingerprints: `solc --optimize --runs 200 --metadata-hash none --bin RngAnchor.sol` (metadata hash stripped for determinism) and append to the manifest.
gcc	12.2.0	Only for the statistical suites (Dieharder, STS, TestU01) — not for any shipped artifact.
Python	3.11.2	`packages/rng-py` is pure Python (no build step); sources fingerprinted.

2. Deterministic build steps

git clone <repo> && cd rain-risk-markets/sdk-v2
git checkout <commit from lab/FINGERPRINTS.json → repo.commit>
node -v            # must print v24.14.0 (or the version recorded)
npm ci             # exact lockfile install
npm run lab:verify-build

npm run lab:verify-build (= lab/tools/verify-build.sh) does: npm run clean (removes every packages/*/dist) → npm run build (each workspace runs tsc -p tsconfig.esm.json [+ tsc -p tsconfig.cjs.json for rng-core; build.mjs for games, which only copies vendor files and emits the manifest check]) → node lab/tools/fingerprint.mjs --verify, which recomputes the SHA-256 of all 201 files in the manifest and exits 1 on any difference.

Recorded result (this machine, commit c146db32, 2026-09-13): two consecutive runs both printed fingerprints OK: 201 files identical to lab/FINGERPRINTS.json (files-digest ca7e4b96f4328483…). The build is byte-deterministic.

3. What is fingerprinted (`lab/FINGERPRINTS.json → scopes`)

Scope	Files	Contents
dist (compiled artifacts)	100	`packages/{rng-core,rng-session,rng-node,games,channels,markets}/dist/**` — `.js`, `.d.ts`, `dist/cjs/package.json`
source (certified path)	32	`packages/rng-core/src/`, `packages/rng-session/src/`, `packages/rng-node/src/`, `packages/rng-node/bin/`, `packages/rng-py/rain_rng/**`
vendored game engines	25	`packages/games/vendor/` (6 UMD engines, 4 Slot Engine V2 bundles, 8 game configs, `MANIFEST.json`, `VENDOR.txt`) + `packages/games/src/`
solidity	1	`packages/rng-session/contracts/RngAnchor.sol`
test vectors	7	`packages/rng-core/test/**` incl. `cavp-hmac-drbg-sha256.json`, `drbg-vectors.json`, `vectors.json`
lab tools	14	`lab/tools/**` (collection tools, analyzers, runners, TestU01 generators)
package manifests	22	root + per-package `package.json`, `tsconfig*.json`, `package-lock.json`

runtimeScope (packages/{rng-core,rng-session,rng-node}/dist/) is the subset rng-node verifies at startup and every 24 h when RAIN_FINGERPRINTS=<path to FINGERPRINTS.json> is set (RAIN_FINGERPRINTS_STRICT=1 → mismatch inhibits RNG output; see lab/RNG-DESCRIPTION.md §10 and packages/rng-node/src/selftest.ts).

4. Witnessed-compile alternative

If the lab prefers a witnessed compile (GLI CSR §2.2), the whole procedure in §2 takes < 3 minutes on a laptop; the only network access is npm ci (lockfile-pinned; an offline npm ci --offline from a vendored cache is possible). The lab's manifest is then compared with lab/FINGERPRINTS.json file-by-file (node lab/tools/fingerprint.mjs --verify).

5. Known non-determinism sources (none on the certified path)

git describe --dirty and generatedAt in the manifest header are informational and excluded from the files digest.
lab/results/** and lab/logs/** are excluded from the fingerprint scope (large, regenerated by seed).
packages/games/build.mjs copies vendor files verbatim; it does not transform them.

← Back to the package index · Rendered 2026-09-14 09:34 UTC from the repository copy; the markdown in the zip / repo is the document of record.

BUILD — REPRODUCIBLE BUILD, PINNED TOOLCHAIN