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

  1. 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, then meta.loadedAddresses.readonly.

  2. Find the self-invocation

    In meta.innerInstructions, take each inner instruction whose program id is the Geode program.

  3. Skip the event-CPI tag

    The first 8 bytes of its data are Anchor's event-CPI tag. Skip them.

  4. 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.

TypeScript
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.

FieldTypeMeaning
depositorPubkeyThe 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
amountu64Lamports 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.

FieldTypeMeaning
relayerPubkeyThe 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
bucketu64The ciphertext bucket in bytes
termu80 30 days, 1 1 year, 2 permanent
priceu64Lamports moved to the storage vault
feeu64Lamports moved to the fee vault
relayer_refundu64The 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.

FieldTypeMeaning
relayerPubkeyThe relayer that signed
recipientPubkeyThe 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
amountu64Lamports moved from the pool vault to the recipient
relayer_refundu64The 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".

EventDiscriminatorSuccessor
Paid240, 193, 17, 238, 238, 210, 129, 235PaidV2
Unshielded141, 41, 20, 125, 56, 78, 86, 205UnshieldedV2

A reader that rebuilds the tree appends the commitments of all five: Shielded, PaidV2, Paid, UnshieldedV2 and Unshielded.