Instructions
Every instruction of the program, its accounts, its arguments, each check in order and what it moves.
The program has seven instructions. Each one's data is Anchor's 8-byte discriminator, sha256("global:<name>")[0..8], followed by its arguments in Borsh. Integers are little-endian. Every [u8; 32] that holds a field element (a commitment, a root, a nullifier) is a 32-byte big-endian scalar of the BN254 field.
| Instruction | Discriminator | Signer | Data bytes |
|---|---|---|---|
| initialize | [175, 175, 109, 31, 13, 152, 155, 237] | admin | 50 |
| set_config | [108, 158, 154, 175, 212, 98, 52, 66] | admin | 50 |
| open_inbox | [210, 172, 188, 164, 4, 122, 231, 223] | wallet | 40 |
| rotate_inbox_key | [201, 165, 115, 46, 57, 80, 165, 180] | wallet | 40 |
| buy_pass | [57, 144, 218, 182, 67, 42, 234, 124] | wallet | 43 |
| post | [223, 96, 234, 236, 158, 106, 145, 94] | relay | 340 + payload |
| close_nullifiers | [109, 92, 160, 8, 227, 29, 94, 112] | anyone | 16 |
Anchor validates the accounts before the handler runs: signers, writability, PDA seeds and bumps, owners and has_one links. A failure there raises one of Anchor's own errors (codes 2000 to 3999) before any check listed below. The handler checks then run in the order given, and each raises a program error. Every account is described on Program accounts.
How each transaction is built#
open_inbox, rotate_inbox_key and buy_pass are wallet-signed transactions that the API builds. POST /tx/open-inbox, POST /tx/rotate-inbox-key and POST /tx/buy-pass return an unsigned v0 transaction with the wallet as fee payer and only signer: a SetComputeUnitLimit and a SetComputeUnitPrice instruction, then the Talaria instruction. The API simulates it, sets the limit to ceil((units + 4,000) × 1.2) + 10,000 (at most 1,400,000), keeps it within 1,104 bytes so a wallet can append its own guards, and simulates the final transaction again before returning it. The wallet signs the bytes. The client sends them to POST /transactions/submit and follows GET /transactions/:id until it is confirmed. API reference gives the requests.
post is a Transaction V1 signed only by a relay. The relay simulates it at 1,400,000 compute units, then signs the final transaction with a limit of ceil(units × 1.15) + 5,000. The limit is carried in the V1 header's configuration, so the transaction holds one instruction. Log entry format gives its bytes.
initialize, set_config and close_nullifiers are signed by the admin or the keeper with their own keys.
initialize#
Creates Config, Pool, Vault and FeeVault, and sets the first configuration. Runs once: a second call fails because the accounts exist.
Accounts
| # | Account | Writable | Signer | |
|---|---|---|---|---|
| 0 | admin | yes | yes | Pays every rent. Must be the program's upgrade authority. |
| 1 | config | yes | PDA "config", created with 83 bytes. | |
| 2 | pool | yes | PDA "pool", created with 2,920 bytes. | |
| 3 | vault | yes | PDA "vault", created with 0 bytes, owned by the System Program. | |
| 4 | fee_vault | yes | PDA "fee_vault", created with 0 bytes, owned by the System Program. | |
| 5 | program_data | The program's ProgramData account. | ||
| 6 | program | 5hJVoxABR1b9QqnQ7FfZDtY2fgNGkUsQtPBqjyBLPTU3 | ||
| 7 | system_program | 11111111111111111111111111111111 |
Arguments
- configConfigArgs, 42 bytes
- In Borsh, in this order:
message_feeu64,relay_feeu64,protocol_share_bpsu16,tiers[u32; 3],lengths[u16; 3],day_length_secondsu32,root_history_sizeu16.
Checks
program_data.upgrade_authority_addressisadmin: elseUnauthorized.program.programdata_addressisprogram_data: elseUnauthorized.- The configuration is valid, checked as in Configuration checks.
Effects. Config is written with admin set to the signer. Pool starts empty: next_index 0, root_count 1, the empty subtrees of every level in filled_subtrees and the empty tree's root in roots[0]. The admin pays the rent-exempt minimum of all four accounts.
Configuration checks#
initialize and set_config check their ConfigArgs in this order:
message_fee > 0,relay_fee > 0andprotocol_share_bps <= 10,000: elseInvalidConfiguration.message_fee × (10,000 − protocol_share_bps) / 10,000 >= relay_fee, so the part of each message fee that reaches the Vault covers the relay fee: elseInsolventConfiguration.day_length_seconds > 0androot_history_sizebetween 1 and 64: elseInvalidConfiguration.- Every tier and every length is above zero: else
InvalidConfiguration. tiers[0] < tiers[1] < tiers[2]andlengths[0] < lengths[1] < lengths[2]: elseInvalidConfiguration.tiers[2] × lengths[2] × message_feefits a u64: elseArithmeticOverflow.
set_config#
Replaces the configuration. Every field of Config except admin and bump takes the new value, the day length included.
Accounts
| # | Account | Writable | Signer | |
|---|---|---|---|---|
| 0 | admin | yes | ||
| 1 | config | yes | PDA "config". Its admin must be the signer. | |
| 2 | pool | PDA "pool". Checked by seeds and bump, otherwise unused. |
Arguments. config: ConfigArgs, encoded as for initialize.
Checks
config.adminis the signer: elseUnauthorized.- The configuration is valid, checked as in Configuration checks.
Effects. The new values apply to the next instruction. Changing day_length_seconds changes the day number every pass and nullifier is read against. No lamports move beyond the transaction fee.
open_inbox#
Creates the wallet's Inbox with its first X25519 key.
Accounts
| # | Account | Writable | Signer | |
|---|---|---|---|---|
| 0 | wallet | yes | yes | Pays the fee and the rent. |
| 1 | inbox | yes | PDA "inbox", wallet. Created with 101 bytes. | |
| 2 | system_program | |||
| 3 | event_authority | PDA "__event_authority" | ||
| 4 | program | 5hJVoxABR1b9QqnQ7FfZDtY2fgNGkUsQtPBqjyBLPTU3 |
Arguments
- inbox_key[u8; 32], 32 bytes
- The X25519 public key, raw bytes.
Checks
- The
inboxaddress holds no account. Anchor'sinitfails with the System Program's "already in use" error when the wallet has an Inbox; the API answersINBOX_ALREADY_OPEN. inbox_keyis not 32 zero bytes: elseInvalidInboxKey.
Effects. Inbox is written with key_version 1 and the slot and time of the clock in opened_slot, opened_at and updated_at. The wallet pays the rent, 1,593,840 lamports on the measured validator. Emits InboxOpened.
rotate_inbox_key#
Replaces the wallet's inbox key with the next version. Messages already written to an older key stay readable by the keys derived for that version.
Accounts
| # | Account | Writable | Signer | |
|---|---|---|---|---|
| 0 | wallet | yes | Pays the fee. | |
| 1 | inbox | yes | PDA "inbox", wallet. Its wallet must be the signer. | |
| 2 | event_authority | PDA "__event_authority" | ||
| 3 | program | 5hJVoxABR1b9QqnQ7FfZDtY2fgNGkUsQtPBqjyBLPTU3 |
Arguments
- inbox_key[u8; 32], 32 bytes
- The new X25519 public key.
Checks
inbox_keyis not 32 zero bytes: elseInvalidInboxKey.inbox_keydiffers from the current key: elseInboxKeyUnchanged.key_version + 1fits a u32: elseArithmeticOverflow.
Effects. inbox_key takes the new key, key_version goes up by one and updated_at takes the clock's time. opened_slot and opened_at keep their values. Emits InboxKeyRotated. The SDK derives the new key for version key_version + 1, as Cryptography gives it.
buy_pass#
Sells a pass and appends it to the pool as one leaf.
Accounts
| # | Account | Writable | Signer | |
|---|---|---|---|---|
| 0 | wallet | yes | yes | Pays the fee and the price. |
| 1 | config | PDA "config" | ||
| 2 | pool | yes | PDA "pool" | |
| 3 | vault | yes | PDA "vault" | |
| 4 | fee_vault | yes | PDA "fee_vault" | |
| 5 | system_program | |||
| 6 | event_authority | PDA "__event_authority" | ||
| 7 | program | 5hJVoxABR1b9QqnQ7FfZDtY2fgNGkUsQtPBqjyBLPTU3 |
Arguments
- id_commitment[u8; 32], 32 bytes
Poseidon(secret)of the pass secret, big-endian. The secret never leaves the device.- tieru8, 1 byte
- Index into
Config.tiers: 0, 1 or 2. The API maps the tier idslight,dailyandfrequentto these indexes. - daysu16, 2 bytes
- One of
Config.lengths.
Checks
id_commitmentis below the BN254 field modulus: elseInvalidFieldElement.tierindexes a configured tier: elseInvalidTier.daysis one of the configured lengths: elseInvalidPassLength.- The clock's unix timestamp is not negative: else
InvalidClock. today + days − 1fits a u64: elseArithmeticOverflow.limit × days × message_feefits a u64: elseArithmeticOverflow.- The Poseidon hash of the leaf succeeds: else
InvalidFieldElement. next_index < 2^26: elsePoolFull.- The wallet holds the price. A shortfall fails the System Program transfer, and the API answers
INSUFFICIENT_FUNDS.
Effects. With today = floor(unix_timestamp / day_length_seconds), limit = tiers[tier] and expiry_day = today + days − 1:
- the leaf is
Poseidon(id_commitment, limit, expiry_day), withlimitandexpiry_dayas 32-byte big-endian scalars; - it is inserted at
next_index, the new root goes into the next ring position andnext_indexgoes up by one; price = limit × days × message_fee;floor(price × protocol_share_bps / 10,000)moves from the wallet toFeeVaultand the rest toVault(a transfer of 0 is skipped);- emits
PassPurchased.
The pass is valid from today through expiry_day inclusive: a pass of days days posts on days days, the day of purchase counted as the first. The circuit accepts a proof for day d when d <= expiry_day. Compute: 45,919 units, measured.
post#
Verifies a proof, spends a nullifier and pays the relay. The instruction is the Log entry.
Accounts
| # | Account | Writable | Signer | |
|---|---|---|---|---|
| 0 | relay | yes | yes | Pays the transaction fee and the Nullifier's rent. Receives the relay fee. |
| 1 | config | PDA "config" | ||
| 2 | pool | PDA "pool" | ||
| 3 | vault | yes | PDA "vault" | |
| 4 | nullifier | yes | PDA "nullifier", day as u64 LE, nullifier. | |
| 5 | system_program |
No account names the writer or the reader.
Arguments
- proof[u8; 256], 256 bytes
- Groth16 proof: negated A (64), B (128), C (64).
- root[u8; 32], 32 bytes
- The pool root the proof is made against, big-endian.
- dayu64, 8 bytes
- Today's day number.
- nullifier[u8; 32], 32 bytes
Poseidon(secret, day, counter), big-endian.- payloadVec<u8>, 4 + n bytes
- A u32 little-endian length, then the payload bytes.
The byte layout of the instruction and of the payload is on Log entry format.
Checks
dayequalsfloor(unix_timestamp / day_length_seconds): elseWrongDay(orInvalidClockfor a negative timestamp).rootis among the latestroot_history_sizeroots of the pool: elseUnknownRoot.- The payload is at least 251 bytes and its first byte is 1: else
InvalidPayload. - The
nullifieraccount is owned by the System Program and holds no data: elseSpentNullifier. - The proof verifies against the six public inputs
root,day,nullifier, the payload hash, and the relay address split in two: elseProofInvalid. - The relay holds the Nullifier's rent. A shortfall fails the System Program transfer, and the relay answers
INSUFFICIENT_FUNDS. - The Vault keeps its rent-exempt minimum for 0 bytes after paying
relay_fee: elseVaultInsufficientFunds, which the relay answers asVAULT_EMPTY, retryable.
The public inputs are built in the program from what it holds, so the relay cannot change them:
| Input | 32-byte big-endian value |
|---|---|
| root | root as given |
| day | day in the last 8 bytes |
| nullifier | nullifier as given |
| payload hash | a zero byte, then the first 31 bytes of SHA-256(payload) |
| relay low | 16 zero bytes, then bytes 16 to 31 of the relay's address |
| relay high | 16 zero bytes, then bytes 0 to 15 of the relay's address |
Effects
- The
nullifieraccount is created after the proof verifies: the relay tops it up to the rent-exempt minimum for 81 bytes (1,454,640 lamports on the measured validator, less any lamports already there), the account is allocated and assigned to the program, andday,nullifier,relayandbumpare written. relay_feemoves from the Vault to the relay, 7,500 lamports by development default.- No event is emitted. The payload stays in the instruction data.
Compute: 120,879 units, measured. A failed post changes nothing: the nullifier stays unspent. The SDK sends the part again with the same payload and nullifier, proving again for another relay or a newer root.
close_nullifiers#
Closes the Nullifier accounts of a finished day and returns each one's lamports to the relay that paid its rent. Anyone can call it; the keeper does.
Accounts
| # | Account | Writable | Signer | |
|---|---|---|---|---|
| 0 | caller | yes | Pays the transaction fee. | |
| 1 | config | PDA "config" | ||
| 2… | pairs | yes | Remaining accounts: a Nullifier, then the relay recorded in it, repeated. |
Arguments
- dayu64, 8 bytes
- The day to close.
Checks
day + 1 < today, so the day and the day after it have ended: elseDayNotClosable(ArithmeticOverflowwhenday + 1overflows).- The remaining accounts are not empty and their count is even: else
InvalidCloseAccounts. - For each pair, in order:
- both accounts are writable: else
InvalidCloseAccounts; - the Nullifier is owned by the program: else
InvalidCloseAccounts; - its data decodes as a Nullifier (Anchor's discriminator and deserialization errors otherwise);
- its
dayis the argument: elseInvalidCloseAccounts; - its
relayis the second account of the pair: elseInvalidCloseAccounts; - its address is the PDA of
"nullifier",day, its storednullifierandbump: elseInvalidCloseAccounts; - the relay's new balance fits a u64: else
ArithmeticOverflow.
- both accounts are writable: else
Effects. Each Nullifier's whole balance moves to its relay, the account is assigned to the System Program and its data is cut to 0 bytes. The caller receives nothing. Talaria calls it for every finished day.