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:
Public inputs are canonical
root, both nullifiers, both commitments,publicAmountandbindingHashare each below the BN254 scalar modulus, orNonCanonicalField.Nullifiers differ
nullifiers[0] != nullifiers[1], orDuplicateNullifier.Root is recent
rootis one of the firstroot_countentries of the root ring, orUnknownRoot.Tree has room
next_leaf_index <= 2^26 - 2, orTreeFull.Proof verifies
Groth16 verification over
[root, nullifiers[0], nullifiers[1], commitments[0], commitments[1], publicAmount, bindingHash]against the compiled verifying key, orInvalidProof.
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.
| Argument | Type | Meaning and constraints |
|---|---|---|
proof | Proof | a [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 |
amount | u64 | Lamports deposited. Greater than 0 |
memos | [Vec<u8>; 2] | One encrypted note memo per output, each at most 80 bytes |
| # | Account | Writable | Signer | Seeds or constraint |
|---|---|---|---|---|
| 0 | depositor | yes | yes | The holder's wallet. Pays amount and the two nullifier accounts' rent |
| 1 | config | PDA "config" | ||
| 2 | pool | yes | PDA "pool" | |
| 3 | pool_vault | yes | PDA "pool_vault" | |
| 4 | nullifier0 | yes | init, PDA "nullifier", nullifiers[0] | |
| 5 | nullifier1 | yes | init, PDA "nullifier", nullifiers[1] | |
| 6 | system_program | System Program | ||
| 7 | event_authority | PDA "__event_authority" | ||
| 8 | program | The Geode program |
Checks, in order:
amount > 0, orInvalidAmount.- Each memo is at most 80 bytes, or
MemoTooLarge. publicAmount = amountas a field element.bindingHashis the shield binding overdepositor,amountand the memo digest.- The shared verification above.
- System Program transfer of
amountfromdepositortopool_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.
| Argument | Type | Meaning and constraints |
|---|---|---|
proof | Proof | a [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 |
receipt | ReceiptFields | ciphertext_root [u8; 32], bucket u64, term u8 |
price | u64 | Storage price in lamports. Greater than 0 |
fee | u64 | Fee 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.
| # | Account | Writable | Signer | Seeds or constraint |
|---|---|---|---|---|
| 0 | relayer | yes | yes | Must be in config.relayers. Pays the two nullifier accounts' rent; receives relayer_refund |
| 1 | config | PDA "config" | ||
| 2 | pool | yes | PDA "pool" | |
| 3 | pool_vault | yes | PDA "pool_vault" | |
| 4 | storage_vault | yes | PDA "storage" | |
| 5 | fee_vault | yes | PDA "fee" | |
| 6 | nullifier0 | yes | init, PDA "nullifier", nullifiers[0] | |
| 7 | nullifier1 | yes | init, PDA "nullifier", nullifiers[1] | |
| 8 | system_program | System Program | ||
| 9 | event_authority | PDA "__event_authority" | ||
| 10 | program | The Geode program |
Checks, in order:
relayeris inconfig.relayers, orUnauthorizedRelayer.price > 0, orInvalidAmount.receipt.bucketis a power of two in[65536, 67108864]andreceipt.term <= 2, orInvalidReceipt.- Each memo is at most 80 bytes, or
MemoTooLarge. fee == floor(price * fee_bps / 10000), computed with a 128-bit intermediate, orInvalidFee.relayer_refund = 2 * minimum_balance(8) + 5000from the Rent sysvar, without overflow, orArithmeticOverflow.total = price + fee + relayer_refundwithout overflow, orArithmeticOverflow.receiptis the receipt ofciphertext_root,bucketandterm.publicAmount = p - total.bindingHashis the pay binding overreceipt,price,fee,relayer_refund,relayerand the memo digest.- The shared verification above.
- Insert both commitments, emit
PaidV2. - Move
pricefrom the pool vault to the storage vault, thenfeefrom the pool vault to the fee vault, thenrelayer_refundfrom the pool vault torelayer. Each debit leaves the vault at or above its rent-exempt minimum, orInsufficientPoolFunds; each credit is checked for overflow, orArithmeticOverflow.
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.
| Argument | Type | Meaning and constraints |
|---|---|---|
proof | Proof | a [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 |
recipient | Pubkey | Destination of the lamports. Equals the recipient_account key and is not the pool vault |
amount | u64 | Lamports withdrawn. Greater than 0 |
memos | [Vec<u8>; 2] | One encrypted note memo per output, each at most 80 bytes |
| # | Account | Writable | Signer | Seeds or constraint |
|---|---|---|---|---|
| 0 | relayer | yes | yes | Must be in config.relayers. Pays the two nullifier accounts' rent; receives relayer_refund |
| 1 | config | PDA "config" | ||
| 2 | pool | yes | PDA "pool" | |
| 3 | pool_vault | yes | PDA "pool_vault" | |
| 4 | recipient_account | yes | Unchecked account; compared to recipient before lamports move | |
| 5 | nullifier0 | yes | init, PDA "nullifier", nullifiers[0] | |
| 6 | nullifier1 | yes | init, PDA "nullifier", nullifiers[1] | |
| 7 | system_program | System Program | ||
| 8 | event_authority | PDA "__event_authority" | ||
| 9 | program | The Geode program |
Checks, in order:
relayeris inconfig.relayers, orUnauthorizedRelayer.amount > 0, orInvalidAmount.recipient == recipient_account, orInvalidRecipient.recipient != pool_vault, orInvalidRecipient.- Each memo is at most 80 bytes, or
MemoTooLarge. relayer_refund = 2 * minimum_balance(8) + 5000from the Rent sysvar, without overflow, orArithmeticOverflow.total = amount + relayer_refundwithout overflow, orArithmeticOverflow.publicAmount = p - total.bindingHashis the unshield binding overrecipient,amount,relayer_refund,relayerand the memo digest.- The shared verification above.
- Insert both commitments, emit
UnshieldedV2. - Move
amountfrom the pool vault torecipient_account, thenrelayer_refundfrom the pool vault torelayer. Each debit leaves the vault at or above its rent-exempt minimum, orInsufficientPoolFunds; each credit is checked for overflow, orArithmeticOverflow.
Moves: amount pool vault to recipient, relayer_refund pool vault to relayer. Two commitments enter the tree. Two nullifier accounts are created.
Emits: UnshieldedV2.