Program

Instructions

Every Geode instruction a client builds or decodes, with its arguments, its accounts in order, the checks it makes in the order the code makes them, what it moves and the event it emits.

Instruction data is Anchor's: the 8-byte instruction discriminator, then the arguments in Borsh, in the order listed. Fixed arrays are their bytes in order, u16 and u64 are little-endian, and each memo is a little-endian u32 length and its bytes. A 32-byte Field is a canonical BN254 scalar, big-endian. Below, p is the BN254 scalar field modulus.

Anchor validates the accounts before the handler runs: each PDA is checked against its seeds, each init account is created, signer and writable flags are enforced. The checks listed under each instruction are the handler's, in code order. Every error is in the one table on Errors.

The three spends (shield, pay, unshield) share one verification, run after their own checks:

  1. Public inputs are canonical

    root, both nullifiers, both commitments, publicAmount and bindingHash are each below the BN254 scalar modulus, or NonCanonicalField.

  2. Nullifiers differ

    nullifiers[0] != nullifiers[1], or DuplicateNullifier.

  3. Root is recent

    root is one of the first root_count entries of the root ring, or UnknownRoot.

  4. Tree has room

    next_leaf_index <= 2^26 - 2, or TreeFull.

  5. Proof verifies

    Groth16 verification over [root, nullifiers[0], nullifiers[1], commitments[0], commitments[1], publicAmount, bindingHash] against the compiled verifying key, or InvalidProof.

publicAmount and bindingHash are never arguments: the program computes both from the instruction's own arguments and accounts, so a proof verifies only for the exact amounts, network refund, receipt, memos, depositor, recipient and relayer it was made for. The binding formulas are in Binding hashes. After verification the spend inserts its two commitments into the tree (see Root ring) and emits its event as an event CPI.

The spend instructions end with two accounts Anchor's #[event_cpi] adds: event_authority (PDA "__event_authority") and program (the Geode program id).

shield

Moves amount lamports from the holder's wallet into the pool vault and inserts two output commitments. The wallet signs; it is the only Geode instruction a wallet signs. The proof spends two input notes, zero-value dummy notes allowed, so inputs + amount = outputs.

Discriminator: 220, 198, 253, 246, 231, 84, 147, 98.

ArgumentTypeMeaning and constraints
proofProofa [u8; 64], b [u8; 128], c [u8; 64]. Layout on Proof bytes
root[u8; 32]A root in the ring the inputs were proven against
nullifiers[[u8; 32]; 2]The two input nullifiers. Must differ
commitments[[u8; 32]; 2]The two output commitments
amountu64Lamports deposited. Greater than 0
memos[Vec<u8>; 2]One encrypted note memo per output, each at most 80 bytes
#AccountWritableSignerSeeds or constraint
0depositoryesyesThe holder's wallet. Pays amount and the two nullifier accounts' rent
1configPDA "config"
2poolyesPDA "pool"
3pool_vaultyesPDA "pool_vault"
4nullifier0yesinit, PDA "nullifier", nullifiers[0]
5nullifier1yesinit, PDA "nullifier", nullifiers[1]
6system_programSystem Program
7event_authorityPDA "__event_authority"
8programThe Geode program

Checks, in order:

  1. amount > 0, or InvalidAmount.
  2. Each memo is at most 80 bytes, or MemoTooLarge.
  3. publicAmount = amount as a field element. bindingHash is the shield binding over depositor, amount and the memo digest.
  4. The shared verification above.
  5. System Program transfer of amount from depositor to pool_vault.

Moves: amount lamports, depositor to pool vault. Two commitments enter the tree at the next two leaf indices. Two nullifier accounts are created.

Emits: Shielded.

pay

Spends two input notes, one of which may be a zero-amount dummy, to pay for one sealed file: the price to the storage vault, the fee to the fee vault, against a receipt naming the ciphertext root, bucket and term. The relayer signs, pays the transaction fee and the two nullifier accounts' rent, and receives the network refund relayer_refund from the pool vault. relayer_refund is not an argument: the program computes it as 2 * Rent::minimum_balance(8) + 5000 from the Rent sysvar. See POST /pay for the request the relayer turns into this instruction.

Discriminator: 119, 18, 216, 65, 192, 117, 122, 220.

ArgumentTypeMeaning and constraints
proofProofa [u8; 64], b [u8; 128], c [u8; 64]
root[u8; 32]A root in the ring
nullifiers[[u8; 32]; 2]The two input nullifiers. Must differ
commitments[[u8; 32]; 2]The two output commitments, zero-value notes included
receiptReceiptFieldsciphertext_root [u8; 32], bucket u64, term u8
priceu64Storage price in lamports. Greater than 0
feeu64Fee in lamports. Equals floor(price * fee_bps / 10000)
memos[Vec<u8>; 2]One encrypted note memo per output, each at most 80 bytes

receipt.bucket is a power of two from 65,536 through 67,108,864 bytes. receipt.term is 0 (30 days), 1 (1 year) or 2 (permanent). See Terms and quotes.

#AccountWritableSignerSeeds or constraint
0relayeryesyesMust be in config.relayers. Pays the two nullifier accounts' rent; receives relayer_refund
1configPDA "config"
2poolyesPDA "pool"
3pool_vaultyesPDA "pool_vault"
4storage_vaultyesPDA "storage"
5fee_vaultyesPDA "fee"
6nullifier0yesinit, PDA "nullifier", nullifiers[0]
7nullifier1yesinit, PDA "nullifier", nullifiers[1]
8system_programSystem Program
9event_authorityPDA "__event_authority"
10programThe Geode program

Checks, in order:

  1. relayer is in config.relayers, or UnauthorizedRelayer.
  2. price > 0, or InvalidAmount.
  3. receipt.bucket is a power of two in [65536, 67108864] and receipt.term <= 2, or InvalidReceipt.
  4. Each memo is at most 80 bytes, or MemoTooLarge.
  5. fee == floor(price * fee_bps / 10000), computed with a 128-bit intermediate, or InvalidFee.
  6. relayer_refund = 2 * minimum_balance(8) + 5000 from the Rent sysvar, without overflow, or ArithmeticOverflow.
  7. total = price + fee + relayer_refund without overflow, or ArithmeticOverflow.
  8. receipt is the receipt of ciphertext_root, bucket and term. publicAmount = p - total. bindingHash is the pay binding over receipt, price, fee, relayer_refund, relayer and the memo digest.
  9. The shared verification above.
  10. Insert both commitments, emit PaidV2.
  11. Move price from the pool vault to the storage vault, then fee from the pool vault to the fee vault, then relayer_refund from the pool vault to relayer. Each debit leaves the vault at or above its rent-exempt minimum, or InsufficientPoolFunds; each credit is checked for overflow, or ArithmeticOverflow.

The lamport moves come after the event CPI, so no CPI runs over directly modified balances. A failed move rolls back the whole instruction, event included.

Moves: price pool vault to storage vault, fee pool vault to fee vault, relayer_refund pool vault to relayer. Two commitments enter the tree. Two nullifier accounts are created.

Emits: PaidV2.

unshield

Spends two input notes, one of which may be a zero-amount dummy, to send amount lamports from the pool vault to a recipient. The relayer signs, pays the transaction fee and the two nullifier accounts' rent, and receives relayer_refund from the pool vault, computed as in pay; the recipient does not sign. See POST /unshield.

Discriminator: 21, 228, 55, 24, 194, 10, 21, 22.

ArgumentTypeMeaning and constraints
proofProofa [u8; 64], b [u8; 128], c [u8; 64]
root[u8; 32]A root in the ring
nullifiers[[u8; 32]; 2]The two input nullifiers. Must differ
commitments[[u8; 32]; 2]The two output commitments
recipientPubkeyDestination of the lamports. Equals the recipient_account key and is not the pool vault
amountu64Lamports withdrawn. Greater than 0
memos[Vec<u8>; 2]One encrypted note memo per output, each at most 80 bytes
#AccountWritableSignerSeeds or constraint
0relayeryesyesMust be in config.relayers. Pays the two nullifier accounts' rent; receives relayer_refund
1configPDA "config"
2poolyesPDA "pool"
3pool_vaultyesPDA "pool_vault"
4recipient_accountyesUnchecked account; compared to recipient before lamports move
5nullifier0yesinit, PDA "nullifier", nullifiers[0]
6nullifier1yesinit, PDA "nullifier", nullifiers[1]
7system_programSystem Program
8event_authorityPDA "__event_authority"
9programThe Geode program

Checks, in order:

  1. relayer is in config.relayers, or UnauthorizedRelayer.
  2. amount > 0, or InvalidAmount.
  3. recipient == recipient_account, or InvalidRecipient.
  4. recipient != pool_vault, or InvalidRecipient.
  5. Each memo is at most 80 bytes, or MemoTooLarge.
  6. relayer_refund = 2 * minimum_balance(8) + 5000 from the Rent sysvar, without overflow, or ArithmeticOverflow.
  7. total = amount + relayer_refund without overflow, or ArithmeticOverflow.
  8. publicAmount = p - total. bindingHash is the unshield binding over recipient, amount, relayer_refund, relayer and the memo digest.
  9. The shared verification above.
  10. Insert both commitments, emit UnshieldedV2.
  11. Move amount from the pool vault to recipient_account, then relayer_refund from the pool vault to relayer. Each debit leaves the vault at or above its rent-exempt minimum, or InsufficientPoolFunds; each credit is checked for overflow, or ArithmeticOverflow.

Moves: amount pool vault to recipient, relayer_refund pool vault to relayer. Two commitments enter the tree. Two nullifier accounts are created.

Emits: UnshieldedV2.