Program

Accounts

Every account the Geode program owns, with each field, its type and size, the seeds of every PDA, and where each vault's lamports go.

The program owns four account types: one Config, one Pool, three Vault accounts and one Nullifier per spent note. Beside them is Anchor's event authority PDA, which signs the program's event CPI and holds no data. Every account the program creates starts with Anchor's 8-byte account discriminator.

PDA seeds

Every PDA is derived from the program id (see Program id). Seeds are the exact bytes below.

AccountSeedsCreated by
config"config"The program, once
pool"pool"The program, once
pool_vault"pool_vault"The program, once
storage_vault"storage"The program, once
fee_vault"fee"The program, once
nullifier0, nullifier1"nullifier", then the 32-byte big-endian nullifiershield, pay, unshield
event_authority"__event_authority"Never created; signs event CPI
program_datathe program id, under the BPF Upgradeable Loader BPFLoaderUpgradeab1e11111111111111111111111The loader

The IDL carries the constant seeds. It carries none for the nullifier PDAs, which depend on an instruction argument, and none for program_data. Clients derive them as the chain package does:

TypeScript
import { PublicKey } from '@solana/web3.js'

const pda = (seed: string) => PublicKey.findProgramAddressSync([Buffer.from(seed)], programId)[0]
const config = pda('config'), pool = pda('pool'), poolVault = pda('pool_vault')
const storageVault = pda('storage'), feeVault = pda('fee'), eventAuthority = pda('__event_authority')

const nullifierPda = (nullifier: Uint8Array /* 32 bytes, big-endian */) =>
  PublicKey.findProgramAddressSync([Buffer.from('nullifier'), nullifier], programId)[0]

const programData = PublicKey.findProgramAddressSync(
  [programId.toBuffer()],
  new PublicKey('BPFLoaderUpgradeab1e11111111111111111111111'),
)[0]

The chain package exports these as derivePdas, nullifierPda and programDataPda.

Account discriminators

Account typeDiscriminator (bytes)
Config155, 12, 170, 224, 30, 250, 204, 130
Pool241, 154, 109, 4, 17, 177, 109, 188
Vault211, 8, 232, 43, 2, 152, 117, 119
Nullifier18, 56, 142, 165, 181, 158, 187, 133

Config

A Borsh account at seed "config", allocated at Config::SPACE = 363 bytes. A client reads fee_bps to check a quote's fee, relayers to know which signers pay and unshield accept, and verifying_key_hash to match the verifying key.

OffsetFieldRust typeBytesMeaning
0discriminator[u8; 8]8Anchor account discriminator
8keyPubkey32A public key set when the config was created
40fee_bpsu162Fee in basis points, 0 to 10,000. pay requires fee = floor(price * fee_bps / 10000)
42relayer_countu81Number of live entries in relayers, 1 to 8
43relayers[Pubkey; 8]256The relayers whose signature pay and unshield accept. Entries past relayer_count are the zero key
299destinationPubkey32The one address the storage vault pays out to
331verifying_key_hash[u8; 32]32SHA-256 of the circuit's verification_key.json bytes, from the verifying key compiled into the program

The relayer list holds one to eight distinct nonzero keys (MAX_RELAYERS = 8).

Pool

A zero-copy account (#[account(zero_copy(unsafe))], #[repr(C)]) at seed "pool". It is read and written in place through AccountLoader, so the tree state never occupies the 4 KiB SBF stack frame. Its size is 8 + size_of::<Pool>() = 5,792 bytes, which the program asserts at compile time stays within the 10,240-byte limit for an account created by init.

OffsetFieldRust typeBytesMeaning
0discriminator[u8; 8]8Anchor account discriminator
8next_leaf_indexu648Index the next commitment is inserted at
16root_indexu648Slot in roots holding the latest root
24root_countu648Number of filled slots in roots, at most 128
32filled_subtrees[[u8; 32]; 26]832Per level, the last left-hand node written on the insertion path
864zeroes[[u8; 32]; 26]832Per level, the root of an empty subtree of that height
1,696roots[[u8; 32]; 128]4,096The root ring

The tree is a binary Poseidon tree of depth 26 (TREE_DEPTH), so it holds 67,108,864 leaves. Leaves and nodes are canonical BN254 scalars, 32 bytes big-endian. A node is Poseidon(left, right). zeroes[0] is 0 and zeroes[l + 1] = Poseidon(zeroes[l], zeroes[l]); caching them saves 26 hashes on every insertion.

Root ring

roots keeps the 128 most recent roots (ROOT_HISTORY). A spend's root argument must equal one of the first root_count entries.

  • The ring starts with the empty-tree root (Poseidon of the level-25 zero with itself) in roots[0] and root_count at 1.
  • Every shield, pay and unshield inserts its two output commitments, leaf by leaf, at next_leaf_index and next_leaf_index + 1. Each leaf walks the 26 levels: on an even index the node is stored in filled_subtrees[level] and hashed with zeroes[level]; on an odd index it is hashed after filled_subtrees[level].
  • After both leaves, the program advances root_index by one modulo 128, writes the root there, and raises root_count by one up to 128. One root enters the ring per two commitments; the root between the two leaves is never stored.

The pool keeps the last 128 roots; a proof's root is accepted until 128 later spends have replaced it. A proof prepared against an older root is refused with UnknownRoot; the client refreshes its tree from GET /tree and proves again. A spend is refused with TreeFull once next_leaf_index exceeds 226 - 2, the last index with room for two leaves.

Vaults

The three vaults are Vault accounts: 8 bytes, the discriminator only, owned by the program. No key signs for them. Lamports leave a vault only through the program's direct debit in move_lamports, which refuses a debit that would leave the vault below the rent-exempt minimum for its 8 bytes (read from the Rent sysvar at the time of the call) with InsufficientPoolFunds, and refuses a transfer from an account to itself with InvalidRecipient.

VaultSeedReceives fromLamports leave byTo
Pool vault"pool_vault"shield: the depositor, by System Program transferpay (price, fee and relayer_refund), unshield (amount and relayer_refund)pay: storage vault, fee vault and the signing relayer. unshield: the proof-bound recipient and the signing relayer
Storage vault"storage"pay: the price, from the pool vaultFunding for the Irys uploads the prices paid forThe one destination address in Config
Fee vault"fee"pay: the fee, from the pool vaultNo instruction debits itNone

The pool vault backs every unspent note. The storage vault holds storage prices until they fund the Irys uploads they paid for. The fee vault accrues Geode's fee, set by Config.fee_bps.

Nullifier

One Nullifier account per spent input note, 8 bytes, the discriminator only. Its address is the PDA of "nullifier" and the 32-byte big-endian nullifier. Every shield, pay and unshield creates two with Anchor init, one per input, including zero-value dummy inputs. Creating an account that already exists fails, so a nullifier is spendable once: a replayed spend is refused by the System Program during account creation, before the program's checks run (see Errors outside the program). The signer pays the rent: the depositor in shield, the relayer in pay and unshield, where the network refund (relayer_refund) repays the relayer from the pool vault in the same instruction (see Instructions). Nullifier accounts are never closed.

Rent

The program fixes no rent figures. Every account created by init is funded at the cluster's rent-exempt minimum for its size (363 bytes for Config, 5,792 for Pool, 8 for each vault and nullifier), the vault floor in move_lamports reads Rent::get() on every debit, and pay and unshield read it again for relayer_refund.