Centralize ZK constants and refactor withdrawal tests (ZK-002, ZK-003…

[xeladev4]

Summary

This PR centralizes ZK protocol constants across Noir circuits and TypeScript SDK, refactors withdrawal circuit tests into a dedicated module, adds circuit-adjacent Merkle root validation, and implements a negative tamper matrix for proof boundary validation.

• closes ZK-002: Centralize ZK constants for tree depth, field widths, zero-address semantics, and amount encoding #246
• closes ZK-003: Extract withdrawal test helpers and fixtures out of the monolithic circuit entrypoint #247
• closes ZK-034: Reject empty or non-canonical root values at the withdrawal proof boundary #278
• closes ZK-037: Build a negative test matrix for tampered recipient, relayer, denomination, and fee inputs #281

Changes

ZK-002: Centralize ZK Constants

• Created sdk/src/zk_constants.ts with centralized constants for:
  • MERKLE_TREE_DEPTH (20)
  • NOTE_SCALAR_BYTE_LENGTH (31)
  • MERKLE_NODE_BYTE_LENGTH (32)
  • ZERO_FIELD_HEX (64 zeros)
  • STELLAR_ZERO_ACCOUNT (GAAAAAAAA...WHF)
  • GROTH16_PROOF_BYTE_LENGTH (256)
  • BN254_FIELD_MODULUS and BN254_FIELD_BYTE_LENGTH
• Created circuits/lib/src/constants.nr with shared Noir constants
• Updated all SDK and circuit files to use centralized constants
• Removed magic numbers from encoding, merkle, witness, note, and proof modules

ZK-003: Refactor Withdrawal Circuit Tests

• Extracted withdrawal circuit tests from circuits/withdraw/src/main.nr into dedicated circuits/withdraw/src/tests.nr
• Added mod tests declaration in main.nr to import the test module
• Kept the public circuit interface stable
• Improved code organization and maintainability

ZK-034: Circuit-Adjacent Root Validation

• Added Merkle root validation in sdk/src/merkle.ts:
  • Rejects all-zero roots (empty root check)
  • Rejects non-canonical roots (>= field modulus)
• Extended WitnessValidationError with MERKLE_ROOT error code
• Added dedicated test suite in sdk/test/merkle_root_validation.test.ts

ZK-037: Negative Tamper Matrix

• Implemented negative test matrix in sdk/test/verification_harness.test.ts
• Tests tampering with one public input at a time:
  • recipient
  • relayer
  • denomination (amount)
  • fee
• Uses deterministic mock verifier to ensure proof verification fails for tampered inputs
• Protects the proof boundary against invalid public inputs

Testing

All existing tests should remain green after migration. New test suites added:

• sdk/test/merkle_root_validation.test.ts - root canonical and non-zero validation
• Extended sdk/test/verification_harness.test.ts - negative tamper matrix

Fixes

• ZK-002: Centralize ZK constants for tree depth, field widths, zero-address semantics, and amount encoding #246 (ZK-002)
• ZK-003: Extract withdrawal test helpers and fixtures out of the monolithic circuit entrypoint #247 (ZK-003)
• ZK-034: Reject empty or non-canonical root values at the withdrawal proof boundary #278 (ZK-034)
• ZK-037: Build a negative test matrix for tampered recipient, relayer, denomination, and fee inputs #281 (ZK-037)