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.
| Account | Seeds | Created 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 nullifier | shield, pay, unshield |
event_authority | "__event_authority" | Never created; signs event CPI |
program_data | the program id, under the BPF Upgradeable Loader BPFLoaderUpgradeab1e11111111111111111111111 | The 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:
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 type | Discriminator (bytes) |
|---|---|
Config | 155, 12, 170, 224, 30, 250, 204, 130 |
Pool | 241, 154, 109, 4, 17, 177, 109, 188 |
Vault | 211, 8, 232, 43, 2, 152, 117, 119 |
Nullifier | 18, 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.
| Offset | Field | Rust type | Bytes | Meaning |
|---|---|---|---|---|
| 0 | discriminator | [u8; 8] | 8 | Anchor account discriminator |
| 8 | key | Pubkey | 32 | A public key set when the config was created |
| 40 | fee_bps | u16 | 2 | Fee in basis points, 0 to 10,000. pay requires fee = floor(price * fee_bps / 10000) |
| 42 | relayer_count | u8 | 1 | Number of live entries in relayers, 1 to 8 |
| 43 | relayers | [Pubkey; 8] | 256 | The relayers whose signature pay and unshield accept. Entries past relayer_count are the zero key |
| 299 | destination | Pubkey | 32 | The one address the storage vault pays out to |
| 331 | verifying_key_hash | [u8; 32] | 32 | SHA-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.
| Offset | Field | Rust type | Bytes | Meaning |
|---|---|---|---|---|
| 0 | discriminator | [u8; 8] | 8 | Anchor account discriminator |
| 8 | next_leaf_index | u64 | 8 | Index the next commitment is inserted at |
| 16 | root_index | u64 | 8 | Slot in roots holding the latest root |
| 24 | root_count | u64 | 8 | Number of filled slots in roots, at most 128 |
| 32 | filled_subtrees | [[u8; 32]; 26] | 832 | Per level, the last left-hand node written on the insertion path |
| 864 | zeroes | [[u8; 32]; 26] | 832 | Per level, the root of an empty subtree of that height |
| 1,696 | roots | [[u8; 32]; 128] | 4,096 | The 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 (
Poseidonof the level-25 zero with itself) inroots[0]androot_countat 1. - Every
shield,payandunshieldinserts its two output commitments, leaf by leaf, atnext_leaf_indexandnext_leaf_index + 1. Each leaf walks the 26 levels: on an even index the node is stored infilled_subtrees[level]and hashed withzeroes[level]; on an odd index it is hashed afterfilled_subtrees[level]. - After both leaves, the program advances
root_indexby one modulo 128, writes the root there, and raisesroot_countby 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.
| Vault | Seed | Receives from | Lamports leave by | To |
|---|---|---|---|---|
| Pool vault | "pool_vault" | shield: the depositor, by System Program transfer | pay (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 vault | Funding for the Irys uploads the prices paid for | The one destination address in Config |
| Fee vault | "fee" | pay: the fee, from the pool vault | No instruction debits it | None |
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.