Circuit helpers

The main circuits share a small set of reusable circom templates, listed below.

Helpers

NoteCommitment Computes the commitment from (noteAddressHash, tokenId, value, metadata, label) via the Poseidon chain, where noteAddressHash = Poseidon(ownerAddress, noteSecret) is computed by the caller and supplied as a private input.

KeystoreLeaf Computes a keystore leaf from (ownerAddress, privateNullifyingKey, authDigest): it hashes the nullifying key (nullifyingKeyHash = Poseidon(privateNullifyingKey)), then emits keystoreLeaf = Poseidon(ownerAddress, nullifyingKeyHash, authDigest). The viewing key is not part of the leaf, and the revocable-key index is folded into authDigest off-circuit rather than passed in. Used for keystore membership proofs.

BinaryMerkleRoot Recomputes a Merkle root from leaf + siblings + index. Used for state-tree, keystore-tree, and ASP-tree membership.

ValueConservation Performs three checks at once: a global equality (the sum of the inputs must equal the sum of the outputs plus the public amountOut), a per-label bound (the outputs carrying label L may total at most the inputs carrying label L), and label inheritance (every output label must match some input label). It is self-defending with 128-bit range checks.

Num2Bits (from circomlib) Provides range checks: Num2Bits(128) for values, Num2Bits(160) for addresses.

Hardening constraints

• ValueConservation carries self-defending Num2Bits(128) guards internally.
• Output-label inheritance is enforced for zero-value outputs.
• tokenId is constrained to 160 bits in-circuit.

The on-chain verifiers and zkeys must come from the same deployment set as the SDK, because circuit signal layouts differ between sets and a mismatch produces invalid proofs.

Source: v2-monorepo/packages/circuits/circuits/templates/helpers/