Protocol
The proof that pays
How one Groth16 proof spends shielded notes for exactly one upload, and what the program checks before any SOL moves.
A Geode payment is a zero-knowledge proof. It shows that its maker owns unspent notes in the pool worth the price, without saying which, and it is bound to one upload's receipt, one price, one fee, one network refund, one relayer and the change notes' memos. The relayer submits it; the program verifies it and moves the SOL. The holder's wallet is not in the transaction.
- Seal
- Quote
- Prove
- Pay
- Store
- Open
What the proof states
Made on the holder's device from the circuit described in Circuit and setup, the proof states, without revealing the notes:
- Each real input note is a commitment in the pool's tree under
root. - Its maker knows the spending key that owns each input.
nullifiersare those inputs' nullifiers, and they differ.outputCommitmentsare well-formed commitments of the outputs.- Inputs plus the public amount equal outputs, every amount a 64-bit integer.
- It was made for this
bindingHash.
Its seven public inputs, in order:
| # | Public input | Set by |
|---|---|---|
| 1 | root | The client: a root in the pool's ring of the last 128. |
| 2 | nullifiers[0] | The client. |
| 3 | nullifiers[1] | The client. |
| 4 | outputCommitments[0] | The client. |
| 5 | outputCommitments[1] | The client. |
| 6 | publicAmount | The program, from the instruction's amounts. See Notes and the pool. |
| 7 | bindingHash | The program, from the instruction's arguments. |
The program never accepts the last two from the caller. It computes them, and a proof made for any other amount or binding does not verify.
The receipt
The receipt names one upload:
receipt = Poseidon(ciphertextRootHigh, ciphertextRootLow, bucket, termCode)ciphertextRootis the SHA-256 of the sealed bytes, split into two 16-byte big-endian halves. See Sealing.bucketis the bucket size in bytes: a power of two from 65,536 to 67,108,864.termCodeis0for30d,1for1y,2forpermanent.
The relayer uploads the ciphertext to Irys tagged Geode-Receipt with this value and accepts only bytes whose SHA-256 and length match it. The receipt is the link between the pay transaction and the upload, and the only one.
Binding hashes
Every 32-byte value (an address, the memo digest) enters as two 16-byte big-endian halves, written High and Low. The memo digest is SHA-256(u32be(len0) ‖ memo0 ‖ u32be(len1) ‖ memo1).
| Instruction | bindingHash |
|---|---|
shield | Poseidon(1, depositorHigh, depositorLow, amount, memoHashHigh, memoHashLow) |
pay | Poseidon(2, receipt, price, fee, refund, relayerHigh, relayerLow, memoHashHigh, memoHashLow) |
unshield | Poseidon(3, recipientHigh, recipientLow, amount, refund, relayerHigh, relayerLow, memoHashHigh, memoHashLow) |
refund is the network refund: twice the rent-exempt minimum of an 8-byte nullifier account, read by the program from the cluster's Rent sysvar, plus 5,000 lamports. The program computes it; the client takes it from the quote as networkLamports.
So a pay proof is good for one receipt, at one price, fee and network refund, submitted by one relayer, with one pair of change memos. Changing any of them, or replaying the proof under another instruction, fails verification.
What the program checks, in order
For pay:
- Anchor creates the two nullifier accounts; one that exists fails the transaction.
- The signer is one of the configured relayers.
priceis above zero; the bucket and term are valid.- Each memo is at most 80 bytes.
feeequalsprice × feeBps / 10,000rounded down.- It computes the network refund, the receipt, the binding hash and the public amount
-(price + fee + refund). - Every public input is a canonical field element, the nullifiers differ, the root is in the ring and the tree has room.
- The Groth16 proof verifies against the program's verifying key.
- The two output commitments are inserted and the new root recorded; the
PaidV2event is emitted. - From the pool vault,
pricemoves to the storage vault,feeto the fee vault and the network refund to the relayer.
Any failure reverts all of it. The full list per instruction, with error codes, is in Instructions.
What it costs to verify
A pay consumes 226,238 compute units, verified on Solana's alt_bn128 syscalls through groth16-solana; every instruction's figures are in Compute and size.