TukarDocumentationTesting and verification

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:all fetches 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, or node_modules tracked.
  • 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 pool CBIYQAC...DK2MHTWJ; older deployments are recorded under deployments/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, disclosure and merkleUpdate, each signal input feeds 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 skips Num2Bits.
  • merkleUpdate proves the slot is empty (leaf=0 must reproduce the public oldRoot) and that the same private siblings yield newRoot. Siblings can't be faked (Poseidon CR + public oldRoot).
  • 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's privKey/blinding from a CSPRNG per spend, so dummy nullifiers never collide across withdraws. No NullifierUsed trap, 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_tampered loads the deployed disclosure verifier WASM (byte-identical to the on-chain contract, hash in docs/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 returning false, which is why Pool::verify asserts the returned boolean instead of treating a successful call as success.
  • transfer_public_inputs_are_bound_in_order and withdraw_public_inputs_bind_recipient_and_negative_amount read 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 test runs against a mock verifier that returns true (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 by npm 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 browser job 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 real next start.
  • Not in CI, and the reason is stated rather than hidden: features, exhaustive and p28-live sign real deposits with the shared testnet key, so concurrent jobs would collide on sequence numbers and spend its USDC; push needs a real Google Chrome binary and CRON_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 merkleUpdate proof. 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.mjs from approved accounts + admin set_asp_root), soundness-tested by npm 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.