Program
Events
Every event a client decodes from the Geode program, with each field and type, and how to read them from a transaction's inner instructions.
The program emits one event per spend: Shielded, PaidV2 and UnshieldedV2. The IDL also carries Paid and Unshielded, which earlier versions of the program emitted from pay and unshield, so older transactions still decode (see Earlier events). Each is emitted with Anchor's emit_cpi!: the program invokes itself, signed by its "__event_authority" PDA, with the event as instruction data. An event therefore lives in the transaction's inner instructions, never in its logs, and is part of the transaction: when an instruction fails after emitting, the event rolls back with it.
Spend events carry the tree state after both insertions: root is the root after the second commitment, and leaf_indices are the explicit indices of commitments[0] and commitments[1]. A reader that appends commitments at leaf_indices in event order rebuilds the tree the relayer serves at GET /tree.
Reading events
Fetch the transaction
Read the confirmed transaction with its metadata. For a v0 transaction, resolve account indexes over the static keys, then
meta.loadedAddresses.writable, thenmeta.loadedAddresses.readonly.Find the self-invocation
In
meta.innerInstructions, take each inner instruction whose program id is the Geode program.Skip the event-CPI tag
The first 8 bytes of its data are Anchor's event-CPI tag. Skip them.
Decode the event
The next 8 bytes are the event discriminator below. The rest is the event's fields in Borsh, in the order listed.
import { BorshEventCoder, utils, type Idl } from '@coral-xyz/anchor'
import { GEODE_IDL } from '@geode/chain'
const coder = new BorshEventCoder(GEODE_IDL as unknown as Idl)
const keys = [
...tx.transaction.message.staticAccountKeys,
...(tx.meta.loadedAddresses?.writable ?? []),
...(tx.meta.loadedAddresses?.readonly ?? []),
]
for (const group of tx.meta.innerInstructions ?? []) {
for (const inner of group.instructions) {
if (!keys[inner.programIdIndex]?.equals(programId)) continue
const data = utils.bytes.bs58.decode(inner.data)
const event = coder.decode(Buffer.from(data.subarray(8)).toString('base64'))
if (event) console.log(event.name, event.data)
}
}Field encoding in Borsh: Pubkey and [u8; 32] are their 32 bytes, u64 is 8 bytes little-endian, u8 is one byte, and each memo in [Vec<u8>; 2] is a little-endian u32 length and its bytes.
Shielded
Emitted by shield. Discriminator: 241, 61, 122, 176, 176, 134, 122, 191.
| Field | Type | Meaning |
|---|---|---|
depositor | Pubkey | The wallet that signed and paid |
commitments | [[u8; 32]; 2] | The two output commitments |
leaf_indices | [u64; 2] | Leaf index of each commitment |
nullifiers | [[u8; 32]; 2] | The two input nullifiers spent |
root | [u8; 32] | Tree root after both insertions |
amount | u64 | Lamports moved into the pool vault |
memos | [Vec<u8>; 2] | The encrypted note memo of each output |
PaidV2
Emitted by pay. Discriminator: 209, 0, 6, 66, 30, 83, 246, 155.
| Field | Type | Meaning |
|---|---|---|
relayer | Pubkey | The relayer that signed |
commitments | [[u8; 32]; 2] | The two output commitments |
leaf_indices | [u64; 2] | Leaf index of each commitment |
nullifiers | [[u8; 32]; 2] | The two input nullifiers spent |
root | [u8; 32] | Tree root after both insertions |
receipt | [u8; 32] | The receipt of ciphertext_root, bucket and term, as the program computed it |
ciphertext_root | [u8; 32] | The sealed file's ciphertext root |
bucket | u64 | The ciphertext bucket in bytes |
term | u8 | 0 30 days, 1 1 year, 2 permanent |
price | u64 | Lamports moved to the storage vault |
fee | u64 | Lamports moved to the fee vault |
relayer_refund | u64 | The network refund: lamports moved from the pool vault to the relayer |
memos | [Vec<u8>; 2] | The encrypted note memo of each output |
The receipt is the value POST /upload and GET /receipt/:id refer to; the receipt's networkLamports is this event's relayer_refund.
UnshieldedV2
Emitted by unshield. Discriminator: 37, 164, 175, 242, 43, 81, 114, 43.
| Field | Type | Meaning |
|---|---|---|
relayer | Pubkey | The relayer that signed |
recipient | Pubkey | The account that received the lamports |
commitments | [[u8; 32]; 2] | The two output commitments |
leaf_indices | [u64; 2] | Leaf index of each commitment |
nullifiers | [[u8; 32]; 2] | The two input nullifiers spent |
root | [u8; 32] | Tree root after both insertions |
amount | u64 | Lamports moved from the pool vault to the recipient |
relayer_refund | u64 | The network refund: lamports moved from the pool vault to the relayer |
memos | [Vec<u8>; 2] | The encrypted note memo of each output |
Earlier events
Paid and Unshielded are what pay and unshield emitted before the program carried the network refund. The program no longer emits them; the IDL keeps them so a reader decodes the transactions that hold them. Each has the fields of its successor in the same order, without relayer_refund; no refund moved in those transactions, and the relayer reports their receipts with networkLamports "0".
| Event | Discriminator | Successor |
|---|---|---|
Paid | 240, 193, 17, 238, 238, 210, 129, 235 | PaidV2 |
Unshielded | 141, 41, 20, 125, 56, 78, 86, 205 | UnshieldedV2 |
A reader that rebuilds the tree appends the commitments of all five: Shielded, PaidV2, Paid, UnshieldedV2 and Unshielded.