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.

  1. Seal
  2. Quote
  3. Prove
  4. Pay
  5. Store
  6. Open
Every file, from your device to Irys. Dashed: what the chain sees. Solid: what stays with you.

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:

  1. Each real input note is a commitment in the pool's tree under root.
  2. Its maker knows the spending key that owns each input.
  3. nullifiers are those inputs' nullifiers, and they differ.
  4. outputCommitments are well-formed commitments of the outputs.
  5. Inputs plus the public amount equal outputs, every amount a 64-bit integer.
  6. It was made for this bindingHash.

Its seven public inputs, in order:

#Public inputSet by
1rootThe client: a root in the pool's ring of the last 128.
2nullifiers[0]The client.
3nullifiers[1]The client.
4outputCommitments[0]The client.
5outputCommitments[1]The client.
6publicAmountThe program, from the instruction's amounts. See Notes and the pool.
7bindingHashThe 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:

Text
receipt = Poseidon(ciphertextRootHigh, ciphertextRootLow, bucket, termCode)
  • ciphertextRoot is the SHA-256 of the sealed bytes, split into two 16-byte big-endian halves. See Sealing.
  • bucket is the bucket size in bytes: a power of two from 65,536 to 67,108,864.
  • termCode is 0 for 30d, 1 for 1y, 2 for permanent.

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).

InstructionbindingHash
shieldPoseidon(1, depositorHigh, depositorLow, amount, memoHashHigh, memoHashLow)
payPoseidon(2, receipt, price, fee, refund, relayerHigh, relayerLow, memoHashHigh, memoHashLow)
unshieldPoseidon(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:

  1. Anchor creates the two nullifier accounts; one that exists fails the transaction.
  2. The signer is one of the configured relayers.
  3. price is above zero; the bucket and term are valid.
  4. Each memo is at most 80 bytes.
  5. fee equals price × feeBps / 10,000 rounded down.
  6. It computes the network refund, the receipt, the binding hash and the public amount -(price + fee + refund).
  7. Every public input is a canonical field element, the nullifiers differ, the root is in the ring and the tree has room.
  8. The Groth16 proof verifies against the program's verifying key.
  9. The two output commitments are inserted and the new root recorded; the PaidV2 event is emitted.
  10. From the pool vault, price moves to the storage vault, fee to 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.