Circuit specification

Source: circuits/ghost.circom · Circom 2.2.2 · Groth16 / BN254 · 6,175 constraints · Merkle depth 20.

Statement

Given public inputs (root, mintHi, mintLo, minBalance, appScope, nullifierMode, challenge, expiresAt), the prover knows private inputs (identitySecret, walletKey, balance, pathElements[20], pathIndices[20]) such that:

idCommit = Poseidon(1, identitySecret)
wkCommit = Poseidon(2, walletKey)
leaf     = Poseidon(3, idCommit, wkCommit, mintHi, mintLo, balance)
MerkleRoot(leaf, pathElements, pathIndices) == root          // Poseidon(2) per level
balance    ∈ [0, 2^64)                                        // Num2Bits(64)
minBalance ∈ [0, 2^64)                                        // Num2Bits(64)
balance >= minBalance                                         // GreaterEqThan(64)
pathIndices[i] ∈ {0,1},  nullifierMode ∈ {0,1}
nullifier = Poseidon(4, nullifierMode ? walletKey : identitySecret, appScope, nullifierMode)

challenge and expiresAt are additionally squared into dummy signals so they are explicitly constrained (Groth16 binds all public inputs regardless; this is defence in depth against tooling that might prune unused inputs).

Public signals (order emitted by snarkjs)

These are defined once in packages/sdk/src/core/constants.ts (PUBLIC_SIGNALS).

Design notes

• Domain separation. Every Poseidon use has a distinct leading tag (1–6). Leaves use Poseidon with 6 inputs and inner nodes Poseidon with 2 inputs; different widths use different round constants, which prevents leaf/node confusion.
• No leaf index in the nullifier. Snapshots are shuffled each time; the nullifier depends only on secrets and appScope, so it is stable across snapshots and position-independent.
• Path index malleability (choosing a different index bit order for the same leaf) does not matter: the nullifier does not depend on position.
• Mint as two limbs. A 32-byte public key exceeds the ~254-bit field; two 128-bit limbs are lossless. The verifier recomputes the limbs from the mint it requested.
• Range checks. Without Num2Bits(64), a prover could pick balance such that the comparator's internal subtraction wraps modulo p. Both operands are range-checked before comparison.

Trusted setup

snarkjs powersoftau verify on the phase-1 file passes, and snarkjs zkey verify (R1CS + ptau + zkey) passes and is run by the build script. Artifact hashes are recorded in packages/sdk/artifacts/manifest.json:

⚠️ A single-party phase 2 means the person who ran the build could, in principle, have kept the toxic waste and could forge proofs. Before production, run a multi-party phase-2 ceremony (e.g. with snarkjs zkey contribute chained across independent participants, or a hosted ceremony tool) and finish with a public, unpredictable beacon (e.g. a future Solana blockhash). Rebuilding changes the verification key — every verifier must update.

Rebuilding

# Linux/macOS: install circom 2.2.x; Windows: the script uses tools/circom.exe
curl -L -o tools/ppot_0080_14.ptau https://pse-trusted-setup-ppot.s3.eu-central-1.amazonaws.com/pot28_0080/ppot_0080_14.ptau
npm run circuits:build                 # add -- --skip-ptau-verify to skip the slow phase-1 check

The script compiles, sets up, verifies the zkey and copies ghost.wasm, ghost_final.zkey, verification_key.json and manifest.json into packages/sdk/artifacts/ and app/public/circuits/.

Performance