Refactor/architecture and tooling

[nol4lej]

Refactor the tooling so the repository can be maintained

19 commits. 63 files, +5410/-1996. No circuit changed — every .r1cs and .zkey byte-identical to the manifest, verified before and after each phase.

What was wrong

scripts/ was 7 shell scripts and 4 TypeScript files with nothing shared. Three failures were being swallowed:

Script	Bug	Measured
setup.sh	curl -L without -f	HTTP error → 182 bytes of XML cached as a ptau, forever
setup.sh	Fallback mirror unreachable	set -e kills the script at exit 6; the mirror never runs
release.sh	git ls-remote guard fails open	Absent tag = 2, unreachable remote = 128, treated identically → a network blip reads as "tag is free" and publishes

build.sh also ran snarkjs with > /dev/null 2>&1, so a failed ceremony step looked like a successful one.

What changed

All 7 shell scripts are now TypeScript. Zero .sh remain. Seven shared modules under scripts/lib/ (circuits, paths, log, run, manifest, note, vk-hash) replace what was copied across files. The circuit list lived in five places; it now lives in one, and PUBLIC_SIGNALS is derived from the signal layouts rather than maintained beside them.

run() exits on failure; tryRun() returns a status. That distinction is what closes the three bugs above.

Two layering fixes: NoteCrypto moved from test/helpers/ to scripts/lib/ — it's the reference implementation of note cryptography, with a build script among its consumers, so the old scripts/ → test/ edge pointed backwards. And setup.ts gained a try/finally, so a mid-ceremony failure no longer strands _0000.zkey/_0001.zkey.

Tests: 159 → 254

The additions cover what had no coverage: run()'s error path, manifest rotation (ROTATE_CIRCUIT, previously unreachable in any test), the note primitives, and the strict-mode guards.

Two pre-existing tests passed without artifacts present — return instead of this.skip(), reporting green on nothing. Both now respect CIRCUITS_REQUIRE_ARTIFACTS. Four Poseidon tests asserted only != 0; they now pin real vectors.

Every fix here was confirmed by reintroducing the bug and watching the test fail.

Documentation

~35 errors. The consequential one: value_proof's public signal order was documented backwards. Circom emits signal output before public inputs, so owner_hash is signal 0 — verified against value_proof.sym. Anyone building a verifier from those docs would produce proofs that fail with no diagnostic.

Also: value_proof listed at ~300 constraints (real: 1151), unshield at 16,033 (real: 16,903), a constraint-breakdown table with its two rows inverted, private_link — a deleted circuit — in two tables, 11 broken commands, 9 broken links, and documented pre-commit hooks that don't exist.

test/docs.test.ts now checks numbers against the .r1cs and manifest, that every documented pnpm run X exists, and that every relative link resolves. The ~300 figure had survived three written explanations of why it was wrong; prose alone doesn't hold.

License

The published package contradicted itself: package.json said Apache-2.0, npm/package.json.template said GPL-3.0. Worse, LICENSE was 17 lines — the per-file header Apache suggests, not the license text. Every release shipped with no actual terms.

Now GPL-3.0-or-later throughout, with the full 690-line text. Four tests keep the five sources in agreement.

Verification

pnpm check clean. 254 passing. pnpm run build-all reproduces all 15 artifacts at their manifest sha256. release:dry green.

Two things worth knowing. The ceremony is not deterministic — two runs give two different vk_hash values. I confirmed the old shell behaved identically, so this is inherent to zkey contribute, not a regression from the port; release:restore recovers the published keys from npm with sha256 verification.

And release/ is desynced from keys/. Pre-existing, untouched here, worth a look before the next publish.