Program

Circuit and setup

The Geode spend circuit signal by signal, every hash the program and the proof share, the proof's byte layout, the measured cost of proving and the trusted setup behind the verifying key.

One circuit proves every spend. backend/circuits/geode.circom (Circom 2.2.3, circomlib 2.0.5) defines the template Geode(depth), instantiated as Geode(26): two input notes are consumed and two output notes created in a depth-26 binary Poseidon tree. shield, pay and unshield verify the same circuit; they differ only in the publicAmount and bindingHash the program computes. See The proof that pays for the design.

Public signals

Seven public signals, in this order. The program passes them to the verifier in the same order.

#SignalValue
1rootA root from the pool's root ring
2inputNullifier[0]Nullifier of input 0 (nullifiers[0])
3inputNullifier[1]Nullifier of input 1 (nullifiers[1])
4outputCommitment[0]Commitment of output 0 (commitments[0])
5outputCommitment[1]Commitment of output 1 (commitments[1])
6publicAmountSigned value entering or leaving the pool, computed by the program
7bindingHashHash of the instruction's external data, computed by the program

The circuit has no public outputs.

Private signals

SignalShapeMeaning
inputAmount[2]Lamports in each input note, 64-bit
inputSpendingKey[2]The holder's spending key for each input
inputBlinding[2]Blinding of each input note
inputPathElements[2][26]Merkle siblings of each input, leaf level first
inputPathIndices[2][26]Path direction bits of each input, least significant first
outputAmount[2]Lamports in each output note, 64-bit
outputOwner[2]Owner hash of each output note
outputBlinding[2]Blinding of each output note

Constraints

For each input i and output i:

  • inputAmount[i] and outputAmount[i] decompose into 64 bits (Num2Bits(64)).
  • Each inputPathIndices[i][level] is boolean. Their binary value, least significant bit first, is the input's leafIndex.
  • At each level, the pair (left, right) is (node, sibling) for bit 0 and (sibling, node) for bit 1, and the next node is Poseidon(left, right).
  • When inputAmount[i] is nonzero, the computed path root equals root. A zero-value input is a dummy note: its membership is not required, while its commitment and nullifier stay fully constrained.
  • inputNullifier[i] and outputCommitment[i] equal their formulas below.

Across the spend: inputNullifier[0] != inputNullifier[1], the value equation holds, and bindingHash is constrained through bindingSquare <== bindingHash * bindingHash, an internal signal that adds no public input. The build refuses an R1CS in which that square was optimized out.

Note formulas

All hashes are circomlib Poseidon over the BN254 scalar field, the same parameters as the program's Poseidon syscall (Bn254X5).

Text
owner      = Poseidon(spendingKey)
commitment = Poseidon(amount, owner, blinding)
nullifier  = Poseidon(commitment, leafIndex, Poseidon(spendingKey, commitment, leafIndex))
node       = Poseidon(left, right)

The nullifier includes the leaf index, so a note's nullifier exists once its leaf index is known from its event. The holder recomputes each note's owner from the spending key; see Keys and Notes and the pool.

Value equation and publicAmount

Text
inputAmount[0] + inputAmount[1] + publicAmount = outputAmount[0] + outputAmount[1]   (mod p)

p is the BN254 scalar field modulus, 21888242871839275222246405745257275088548364400416034343698204186575808495617. The program computes publicAmount from its own arguments:

InstructionpublicAmount
shieldamount
payp - (price + fee + relayer_refund)
unshieldp - (amount + relayer_refund)

relayer_refund is the network refund the program computes from the Rent sysvar and moves to the relayer; see pay.

A u64 value enters as a 32-byte big-endian scalar with the value in its last 8 bytes; p - x is that scalar subtracted from the modulus.

Limbs

Every 32-byte value that enters a Poseidon hash (an address, the ciphertext root, the memo digest) is split into two limbs: High is its first 16 bytes and Low its last 16 bytes, each read as a big-endian integer below 2128. In the program each limb is a 32-byte scalar with the 16 bytes in its low half.

Receipt

The receipt names the file and what was bought, not who paid; the relayer enters the payment binding instead. Its formula and term codes are in The proof that pays.

Binding hashes

bindingHash is Poseidon over a domain tag and the instruction's external data, computed by the program from the instruction's arguments and accounts and, for pay and unshield, relayer_refund; the three formulas are in The proof that pays. The chain package computes the same values with shieldBindingHash, payBindingHash and unshieldBindingHash.

Memos

Each spend carries exactly two memos, one per output, each at most 80 bytes. Their layout is in Notes and the pool and their digest in The proof that pays.

Proof bytes

The Proof argument is 256 bytes of uncompressed, big-endian alt_bn128 coordinates, as the syscall takes them. Over the relayer API each part travels as base64.

PartBytesLayout
a64x, then -y over the BN254 base field: q - y mod q
b128x.c1, x.c0, y.c1, y.c0: each Fq2 coordinate imaginary coefficient first
c64x, y

q is the BN254 base field modulus, 21888242871839275222246405745257275088696311157297823662689037894645226208583. From a snarkjs proof: a = pi_a[0] || q - pi_a[1], b = pi_b[0][1] || pi_b[0][0] || pi_b[1][1] || pi_b[1][0], c = pi_c[0] || pi_c[1]. The chain package's proofToSolana produces this layout.

Measured figures

ItemValue
CompilerCircom 2.2.3, --O1
Constraints32,982 (15,600 nonlinear, 17,382 linear)
Wires33,043
Public inputs7
geode.wasm2,587,255 bytes
geode_final.zkey16,161,264 bytes
Setup elapsed67.879 seconds

Proving times, measured on 2026-11-16 in Node 22.23.4 with snarkjs 0.7.6, single-thread, witness generation included:

SpendSeconds
shield3.842
pay3.701
unshield3.671

The browser proves with the same artifacts; prove() defaults to single-thread and keeps the witness in the page.

Trusted setup

The proving key is a Groth16 setup in two phases, recorded in circuits/build/setup.json and circuits/build/beacon.json.

  1. Phase 1

    PSE's perpetual powers of tau, ppot_0080_16.ptau (power 16, 75,590,802 bytes), from pse-trusted-setup-ppot.s3.eu-central-1.amazonaws.com/pot28_0080/. SHA-256 ed3622a7c79b0b49aadd134ebbc5b77df8c8c59bccebdfd0d9bf2c1a51561cf9.

  2. Geode phase 2 contribution

    One contribution named "Geode phase 2 contribution", from 64 bytes of fresh OS entropy, completed 2026-11-15T21:20:48Z. Contribution hash b8359ef98fccc1a93593beb4ae1dfabe6445dd9d180dd1a005d0b2cb842d7282fc13ee1d5a88c46782a380322cdfb815d41f74b8b7434e43da577dfbb86941c1.

  3. drand beacon

    After the contribution, the build chose drand round 6644889 (two rounds past the latest at that moment, still in the future), waited for it, and applied its randomness a8ecda1424db4d8d781253d6616bd3c82e0dfb87c1d1345fd9d6aad5d3095923 as the beacon with iteration exponent 10. The build checked that the SHA-256 of the round's signature equals its randomness. Beacon contribution hash aba047e6f69a00a46f252cd3d895bec936d262382bc85ebe393b3710ef7258178def271e3f5168ef5e65051802c3fd37424b7f9350c0e1acdf15be6d8a3acfae. The drand chain is the default beacon, chain hash 8990e7a9aaed2ffed73dbd7092123d6f289930540d7651336225dc172e51b2ce; the full response is in beacon.json.

  4. Verification

    snarkjs zkey verify of geode_final.zkey against the R1CS and the phase 1 file passed (zkeyVerified: true).

  5. Verifying key

    The verification key was exported from the final zkey. SHA-256 of verification_key.json: 558266a13602598f4bc82dd8d6c4e62e56b2876a13c80bdb3ff1efaee13e5e19. The same hash is compiled into the program and stored in Config.verifying_key_hash.

The Rust verifying key (verifying_key.rs), the browser artifacts and verification_key.json all come from the same final zkey.

Artifacts

The web app serves the proving artifacts at its /circuits/ route. GET /config returns their base as artifactsUrl.

FileBytes
/circuits/geode.wasm2,587,255
/circuits/geode_final.zkey16,161,264
/circuits/verification_key.json4,332

A manifest.json beside them lists each file's byte length and SHA-256.

TypeScript
import { prove } from '@geode/chain'

const result = await prove(witness, {
  wasm: '/circuits/geode.wasm',
  zkey: '/circuits/geode_final.zkey',
})