Tukar QA & Testing
A full QA pass covering repo hygiene, circuit soundness, contract unit tests, and on-chain behaviour (positive + negative) on Stellar testnet.
Test matrix from the last full run (all suites green)
| Type | Suite | Command | Result |
|---|---|---|---|
| Unit (contract) | pool (Rust) | cargo test in contracts/pool |
55/55 |
| Unit (contract) | all seven contract crates | cargo test per crate |
333 (pool 55, pool-enforced 82, pool-timelock 89, pool-accumulator 83, policy-registry 6, reserves 6, reserves-aggregate 12) |
| Unit (frontend) | client Merkle tree | npm run test:unit |
15/15 |
| Unit (circuit soundness) | negative (transfer + compliance) | npm run test:negative |
6/6 |
| Soundness (widened ASP) | multi-member allow-list, real proofs | npm run test:asp |
4/4 |
| Soundness (threshold disclosure) | prove amount ≤ threshold w/o revealing amount | npm run test:threshold |
4/4 |
| Soundness (two-sided range disclosure) | prove lower ≤ amount ≤ upper w/o revealing amount | npm run test:range |
5/5 |
| Soundness (aggregate disclosure) | prove Σ portfolio ≤ cap, bound to a registered audit request | npm run test:aggregate |
6/6 |
| Proving | valid / tampered / false-witness | npm run test:proving |
pass |
| Trusted setup | zkey ⇐ Hermez ptau | snarkjs zkey verify ×7 |
7/7 ZKey Ok |
| Integration (routing) | every route returns 200 and renders its key content | npx playwright test e2e/routes.spec.ts |
9/9 per browser |
| Integration (receiver UI) | withdrawn-note auto-hide + off-ramp to another corridor | npm run test:offramp |
9/9 |
| Integration (browser) | routes, a11y, edge inputs, failure, mobile, resilience | npm run test:e2e |
63 chromium in CI |
| Integration (bearer P2P) | export→wipe→import→withdraw | npm run test:bearer |
4/4 |
| Integration (QR) | decode bearer + request QR | npm run test:qr |
2/2 |
| Integration (landing) | links/CTA/no-errors | npm run test:landing |
5/5 |
| Integration (anchor UI) | in-UI SEP-10+24 on-ramp | npm run test:anchor |
5/5 |
| Integration (anchor SEPs) | SEP-1/10/6/24/31 | npm run sep:anchor |
5/5 |
Every suite in the matrix is green. Regression pass: all of the above were re-run together after each change.
The three disclosure-variant circuits (threshold, two-sided range, aggregate) are
compiled, multi-party-ceremony keyed, and their verifiers are deployed on testnet
and bound through the pool (disclose_threshold / disclose_range /
disclose_aggregate); each variant's soundness suite runs against its own artifacts.
CI (.github/workflows/ci.yml) automates the deterministic ones (unit, proving,
soundness) on every push; the live Playwright suites are manual pre-deploy gates
(they need a funded testnet key + the deployed site).
How to run the test suite
npm run circuit:all # compile + prove + verify the 4 core circuits (Groth16/BN254)
npm run test:proving # in-browser proving flow: valid / tampered / false-witness
npm run test:negative # circuit soundness: transfer + compliance violations rejected
npm run test:e2e # Playwright real-click e2e (drives the live site, real clicks)
# contract unit tests (in WSL/Linux):
cd contracts/pool && cargo test # 55/55
npm run circuit:allfetches the real Hermez phase-1 ptau (powersOfTau28_hez_final_14.ptau, ~19 MB) on first run and asserts each rebuilt zkey derives from it (snarkjs zkey verify). The build is therefore reproducibly waste-free, not generated from a local phase-1. See §5.
1. Repo hygiene ✅
- No secrets,
.ptau,.wtns, tool binaries, ornode_modulestracked. - Only the demo artifacts (
frontend/circuit/disclosure.wasm,.zkey, vk) are committed (needed to serve the browser demo). Largest tracked file 1.8 MB. - Contract IDs are consistent across README, the frontend, these docs, and
deployments/testnet.json(current poolCBIYQAC...DK2MHTWJ; older deployments are recorded underdeployments/testnet.json→pool.supersedes). LICENSE(Apache-2.0) present;test_snapshots/ignored.
2. Circuit soundness ✅
| Circuit | Positive | Negative (must reject) |
|---|---|---|
| disclosure | valid proof verifies | false witness rejected; tampered claim → verify false |
| transfer | valid proof verifies | broken value conservation rejected; forged nullifier rejected |
| compliance | valid proof verifies | source on deny-list rejected; non-member (wrong ASP root) rejected |
npm run test:negative → 6/6 passed. npm run test:proving → valid/tampered/
false-witness all behave correctly.
Manual circuit review (2026-06-30) complements the runtime negative tests by checking the Circom source for under-constrained signals (the soundness holes a passing happy-path can't reveal):
- Every private signal is constrained. In
transfer,compliance,disclosureandmerkleUpdate, eachsignal inputfeeds a===/<==constraint (Poseidon preimage, Merkle path, nullifier, or range), and no<--is left dangling. - All amounts are range-checked: transfer inputs and outputs to 248 bits (wrap-free value conservation, not just an inductive invariant); disclosure amount to 64 bits.
- Path indices are boolean-forced in
DualMux(s*(1-s)===0), so a malformed Merkle witness can't bend the path even if a caller skipsNum2Bits. merkleUpdateproves the slot is empty (leaf=0 must reproduce the publicoldRoot) and that the same private siblings yieldnewRoot. Siblings can't be faked (Poseidon CR + publicoldRoot).- Dummy JoinSplit inputs are sound: zero-value inputs skip Merkle membership
(
(root-r)*inAmount===0) but still bind a nullifier; the frontend draws the dummy'sprivKey/blindingfrom a CSPRNG per spend, so dummy nullifiers never collide across withdraws. NoNullifierUsedtrap, no value mint.
Result: no under-constrained signal or missing range check found.
3. Contract unit tests ✅
Read this caveat before reading the numbers. Every verifier in the Rust suites except one is
a stub: MockVerifier returns true for a proof of 256 zero bytes. That is the right tool
for testing the pool's own logic (binding, nullifier set, custody, admin gating) and it
proves nothing about Groth16. Cryptographic soundness is covered in three other places: the
one real-verifier test named below, the circuit negative suite
(scripts/test-negative.mjs, which asserts witness generation throws for broken value
conservation, a forged nullifier, a deny-listed source and a non-member source), and
scripts/test-fullprove.mjs, which mutates a public signal and asserts snarkjs rejects it.
The last two run in CI.
Three tests carry more weight than the rest:
real_verifier_wasm_accepts_real_proof_and_rejects_tamperedloads the deployed disclosure verifier WASM (byte-identical to the on-chain contract, hash indocs/ONCHAIN.md) and runs a real pairing check against a real proof, then flips one public signal and asserts the same proof no longer passes. It also pins the refusal shape: the real verifier traps rather than returningfalse, which is whyPool::verifyasserts the returned boolean instead of treating a successful call as success.transfer_public_inputs_are_bound_in_orderandwithdraw_public_inputs_bind_recipient_and_negative_amountread back the exact public input vector the pool hands the verifier on the paths that move money, asserting the recipient binding is recomputed on-chain and that the withdraw amount is bound to its field-negative. Before these, only the deposit-side compliance vector was asserted.
In contracts/pool, 55/55 passed (cargo test): deposit pulls USDC + records
commitment; withdraw releases the bound amount; mismatched-amount withdraw
rejected (AmountNotBound); transfer spends nullifiers + records outputs;
double-spend replay rejected (NullifierUsed); unknown root rejected
(UnknownRoot); disclose requires a known commitment; unknown-commitment disclose
rejected (UnknownCommitment); register_root_verified advances from the current
root and rejects an unknown or stale one (accumulator semantics); leaves are
stored on-chain in order (leaves()/leaf_count); poseidon_matches_circomlib
(on-chain Poseidon == circomlibjs poseidon([1,2])); and a poseidon_cost_probe
diagnostic. The admin register_root backdoor was removed, so the only way to
advance the root is a
merkleUpdate proof. The leaf inserted by register_root_verified must be a
commitment already recorded by a real deposit (or change-note output) and may be
inserted at most once. register_root_verified_rejects_undeposited_leaf
(UnknownCommitment) and register_root_verified_rejects_double_insert
(LeafAlreadyInserted) cover the unbacked-leaf drain defense. The merkleUpdate
leafIndex is now a public input the pool pins to its own LeafCount, so a
proof can't attest insertion at a different slot than the one stored (closes the
accumulator-griefing DoS). And deposit_rejects_duplicate_commitment
(DuplicateCommitment) covers the duplicate-deposit fund-lock fix. The I/O-count
pinning that closes the unpinned-split double-spend (T17) is covered by
transfer_rejects_shifted_io_split / withdraw_rejects_shifted_io_split
(BadIoCount).
What these unit tests do and don't cover.
cargo testruns against a mock verifier that returnstrue(test.rs), so it validates the pool's binding, authorization, state-machine and oracle-gate logic, not Groth16 soundness itself. Real proof verification (valid →true, tampered/false-witness → rejected) is covered separately bynpm run test:negative(circuit soundness, §2) and by the live on-chain results against the deployed Nethermind BN254 verifiers (§4). The two layers together cover the system end-to-end; neither alone does.
4. On-chain behaviour (Stellar testnet) ✅
Positive cases (all return true):
| Call | Contract | Result |
|---|---|---|
disclosure.verify |
CAYGUR...J4W4V |
true |
transfer.verify |
CACHZSW...3PUNE |
true |
compliance.verify |
CDXYGM3...XBCG2 |
true |
pool.deposit |
CBIYQAC...DK2MHTWJ |
success (moved real USDC in, bound to the commitment) |
pool.withdraw |
CBIYQAC...DK2MHTWJ |
success (released USDC, amount bound to negative public_amount) |
pool.register_root_verified |
CBIYQAC...DK2MHTWJ |
success (trustless root advance, merkleUpdate proof) |
pool.poseidon_hash(1,2) |
CBIYQAC...DK2MHTWJ |
0x115cc0f5...4417189a (circomlib-exact Poseidon on-chain) |
merkleUpdate.verify |
CCA3T54...S3X6H |
true |
Negative cases (all correctly rejected):
| Scenario | Expected error | Result |
|---|---|---|
disclosure.verify / transfer.verify tampered public input |
InvalidProof (#0) |
rejected ✅ |
pool.transfer valid proof but TAMPERED nullifiers (double-spend bypass) |
InvalidProof (#0) |
rejected ✅ |
pool.transfer replay (double-spend) |
NullifierUsed (#2) |
rejected ✅ |
pool.transfer with unknown root |
UnknownRoot (#1) |
rejected ✅ |
pool.withdraw amount ≠ proof public_amount |
AmountNotBound (#6) |
rejected ✅ |
register_root_verified with a FAKE new_root |
InvalidProof (#0) |
rejected ✅ |
pool.disclose of unknown commitment |
UnknownCommitment (#3) |
rejected ✅ (unit) |
The double-spend-bypass row is the important one: because the pool builds the verifier's public inputs from the typed nullifiers/commitments/root itself, a caller cannot present a valid proof while spending different nullifiers. The verification fails. This closes the binding gap found in QA.
State checks after the test transfer: pool.current_root = registered root,
commitment_count = 2, is_root_known(root) = true, is_nullifier_used(spent) = true.
5. Trusted setup is independently verifiable ✅
All seven deployed proving keys (frontend/circuit/*_final.zkey) derive from the
real Hermez perpetual Powers-of-Tau ceremony (powersOfTau28_hez_final_14.ptau),
so phase-1 has no locally-known toxic waste. This is not a claim to take on
faith. Anyone can check it:
# for each circuit c in {disclosure, compliance, merkleUpdate, transfer,
# thresholdDisclosure, aggregateDisclosure, rangeDisclosure}:
snarkjs zkey verify circuits/build/$c.r1cs circuits/build/pot14_hez.ptau \
frontend/circuit/${c}_final.zkey # => "ZKey Ok!"
ZKey Ok! for all seven (2^14 = 16384 ≥ transfer's 15884 constraints). The eighth circuit,
reserves (21471 constraints), is proved off the browser path and verifies the same way against
the larger Hermez powersOfTau28_hez_final_15. The build
scripts (build-circuit.sh, build-disclosure.sh) fetch this exact ptau and run the
same assertion, so a stale local-ptau key can never silently replace a deployed one.
The deployed keys are now the output of a multi-party phase-2 ceremony (3
contributions + a public beacon, transcripts in ceremony/<circuit>/); honest caveat:
the demo ran all rounds on one machine to prove the process, so the one-honest-party
guarantee needs genuinely independent contributors.
6. End-to-end UI (Playwright real-click)
npm run test:e2e runs the Playwright suite in e2e/ against the current Next.js app.
playwright.config.ts starts the server itself when the target is localhost, so the suite no
longer depends on a separately launched process, which was the cause of a round of phantom
404 failures.
A correction that belongs here rather than in a changelog. This section used to describe
scripts/e2e-playwright.mjs and claim 11/11 verified on 2026-07-03. That script drove the old
static frontend/ console over a hardcoded Windows Chrome path, and it had been dead for some
time without anyone noticing: frontend/ was reduced to circuit/ and tree.js in commit
1177e5e, and webapp/next.config.mjs now redirects /demo and /demo/* to /, so every
selector it used had ceased to exist. A green number in a document, for a script nobody could
run, against a page that had been deleted, is worse than no number. The script is gone and
npm run test:e2e is the real suite.
What runs where:
- In CI, a
browserjob runs the chromium specs that need no testnet writes and no secrets:routes,a11y,edge-inputs,failure,mobile,resilience. 63 tests, about 35 seconds against a realnext start. - Not in CI, and the reason is stated rather than hidden:
features,exhaustiveandp28-livesign real deposits with the shared testnet key, so concurrent jobs would collide on sequence numbers and spend its USDC;pushneeds a real Google Chrome binary andCRON_SECRET. Run those locally.
7. QR codes actually scan ✅ 2/2 live
npm run test:qr proves the bearer-note and payment-request QR codes the demo
renders decode back to the exact string a phone camera would read. That matters
because Tukar styles them with custom colors (dark #0a0705 on #f3ad79), not
plain black-on-white. The test loads the live demo, generates each QR, then decodes
the rendered PNG with jsQR over its raw pixels (the same algorithm a scanner
uses) and asserts decoded === the visible string.
Verified 2026-06-30 against the live deploy: 2/2. tukreq1:... (payment request)
and tukar1:... (bearer note, after a real on-chain deposit) both decode exactly,
with zero uncaught page errors. So the custom-styled QR remains camera-scannable.
8. Bearer note is real spendable money ✅ 4/4 live
npm run test:bearer proves the tukar1:... string a QR encodes is withdrawable value
on a device that has nothing but the string. Steps, on the live deploy:
(1) deposit a note on-chain, (2) export the bearer string, (3) wipe
the local session and import the bare string as a fresh holder (the pool
reconstructs the tree from chain), (4) withdraw it. Real tokens are released on-chain.
Verified 2026-06-30: 4/4, zero uncaught page errors. This isolates the genuine
P2P-handoff feature from the e2e's cross-wallet double-spend step (§6 case 9); both
now pass, because the transient-retry fix in sendTx removed the shared-key contention that
used to make the back-to-back on-chain step flake.
9. Landing page QA (Playwright real-click) ✅ 5/5 live
npm run test:landing checks the page a judge sees first: H1 value-prop, every
stellar.expert contract link points to a LIVE contract id (not a superseded one),
footer links deep-link to the named doc/circuit (/blob/main/docs/*.md,
/blob/main/circuits/*.circom) rather than the bare repo root, zero console
errors / failed requests on load + scroll, and the primary CTA real-click lands
in a working demo (prover reaches Ready).
Verified 2026-06-30 on the live deploy: 5/5, zero uncaught page errors. (Fixed this round: the footer links previously all pointed at the repo root, so "Architecture" didn't open ARCHITECTURE.md; now they deep-link.)
10. Per-page routing (Playwright)
e2e/routes.spec.ts walks every route the app actually serves: /, /sender, /receiver,
/operator, /regulator, /verify, /deck, /docs and one /docs/<slug> page. Each must
return a real 200, render its key content after hydration and its live Soroban reads, and finish
with no page errors and no non-benign network failures. It runs on chromium, firefox and webkit.
This replaced an older scripts/test-pages.mjs that drove a separate /demo/<step> console with
its own SPA rewrite. That console no longer exists: the Next.js unification moved every actor onto
its own route, and /demo now redirects to the landing page. The script was left behind pointing at
markup that had been deleted, so it failed on a 45s timeout while this document still claimed it
passed. Both the script and its npm run test:pages entry are gone, and the routing coverage it
once provided is what routes.spec.ts does now.
11. Anchor SEP integration (real, live) ✅
The fiat-edge anchor protocols are integrated against SDF's public reference
anchor (testanchor.stellar.org), no mocks:
npm run sep:anchor(scripts/sep-anchor.mjs) is 5/5 live: SEP-1 discovery → SEP-10 (sign the challenge → real JWT) → SEP-6/info→ SEP-24 interactive deposit (a real hosted USDC on-ramp URL) → SEP-31/info.npm run test:anchor(scripts/test-anchor.mjs) is 5/5 live, a real Playwright click of the demo's "Try a real anchor USDC on-ramp" button: it authenticates (SEP-10, signed by the demo key or Freighter) and opens a genuine SEP-24 deposit session at the anchor's hosted UI, from the browser.
Honest scope: SDF's testanchor is a reference anchor (no real KYC on testnet) and
it issues Circle testnet USDC (issuer GBBD47IF...), whereas the corridor demo is
pre-funded with a project USDC SAC (issuer GC7SWGHR...). So the on-ramp demonstrates
the live SEP flow; it is not the corridor's deposit source. A production deploy
would align the corridor's settlement asset to a licensed anchor's USDC (a partner +
KYC step, not code). Tukar also publishes its own SEP-1 stellar.toml
(/.well-known/stellar.toml, served with the SEP-1 CORS header).
Known limitations (by design, stated honestly)
- Merkle witness (path) computed off-chain; on-chain integrity enforced by the
merkleUpdateproof. There is no admin root backdoor. - Fiat anchor on/off-ramps mocked. The ASP allow-list is now a real configurable
policy (
scripts/build-asp.mjsfrom approved accounts + adminset_asp_root), soundness-tested bynpm run test:asp(4/4); 10 corridors. - Phase-2 of the trusted setup is now a multi-party ceremony (3 contributions + a public beacon; phase-1 is the real Hermez ceremony), and those ceremony keys are the deployed keys. Honest caveat: the demo ran all rounds on one machine to prove the process, so the one-honest-party guarantee needs genuinely independent parties.
- Contracts are not audited. Testnet only, no real assets.