research: Poseidon constraint attribution across all three circuits

[alexandre-mrt]

Summary

Nightly research loop, queue item #2 (docs/research/EXPERIMENTS.md). Measures the exact
non-linear R1CS constraint contribution of every Poseidon arity, one depth-20 Merkle-tree level,
and every range-check/comparator gadget Veil's circuits are built from, via isolated micro-circuits
under circuits/bench-gadgets/, then cross-validates the attribution by reconstructing each real
circuit's total (sum(gadget cost × call count)) against the independently-measured baseline in
docs/research/BASELINE.md.

• Poseidon accounts for 78–95% of non-linear constraints across transfer.circom,
  compliance.circom, and withdraw.circom.
• The 20-level Merkle path alone is 76–81% of non-linear constraints in the two circuits that
  have one — bigger than every direct commitment/nullifier/credential-leaf hash combined.
• Reconstruction is exact (transfer, withdraw non-linear) or within 3/6,057 constraints
  (compliance) — fully explained by top-level glue constraints the isolated gadgets don't include.
• Did not attempt an actual Poseidon2 swap: no circom Poseidon2 circuit template is reachable
  from the npm registry, and the reference material to hand-write one safely (round constants,
  round structure) lives on GitHub/IACR ePrint — both blocked by this environment's egress policy.
• Reconfirmed queue item feat: Veil privacy payment protocol — full stack MVP #1 (on-chain gas) is blocked by a confirmed organization network
  policy (403 on github.com and fullnode.testnet.sui.io, verified via direct curl), not a
  toolchain gap — re-ranked down in EXPERIMENTS.md accordingly.
• Found and validated circom2 (an npm-published WASM build of the circom compiler) as a
  GitHub-free toolchain — reproduces the existing baseline byte-for-byte, used to rebuild and
  re-run the full circuit test suite.

No protocol circuit was modified. All new gadgets live in circuits/bench-gadgets/, never
wired into the build, deployment, or frontend — so this PR carries no soundness/leakage/negative-test
obligation (nothing new enters the protocol).

Full writeup: docs/research/2026-08-25-poseidon-constraint-attribution.md

What changed

• circuits/bench-gadgets/*.circom — 12 single-gadget micro-circuits (Poseidon arities 2–5,
  Num2Bits(64/8), comparators, MultiMux1(2), one Merkle-tree level).
• scripts/bench/gadget-attribution.mjs — reusable benchmark: compiles every gadget, reconstructs
  each real circuit's constraint total from the parts, and (--prove) times real Groth16 proofs
  for a representative subset.
• docs/research/BASELINE.md — new "Constraint attribution (by gadget)" section.
• docs/research/LEDGER.md — new row (KEEP).
• docs/research/EXPERIMENTS.md — re-ranked: Merkle-depth-vs-anonymity-set moved above the
  Poseidon2 swap; on-chain gas demoted with an explicit "don't re-attempt without a policy change"
  note; added an item for adopting circom2 as the documented toolchain.
• circuits/package-lock.json — incidental lockfile sync (snarkjs range already pinned in
  package.json; npm install corrected a stale entry in the lock).

Test plan

• node --experimental-vm-modules test/transfer.test.mjs — 43/43 pass
• node --experimental-vm-modules test/withdraw.test.mjs — 35/35 pass
• node --experimental-vm-modules test/compliance.test.mjs — 30/30 pass
• bun run src/test-converter.ts — 109/109 pass
• bun run src/test-compliance-utils.ts — 67/67 pass
• bunx vitest run (frontend) — 19/19 pass
• sui move test — NOT RUN, sui CLI unavailable in this environment (confirmed network
  policy block, same as queue item feat: Veil privacy payment protocol — full stack MVP #1 — pre-existing, unrelated to this change)
• node scripts/bench/gadget-attribution.mjs and --prove — reproduced live, output matches
  the report

---

Generated by Claude Code