Skip to content
Open app

ProtocolInstructions

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.

InstructionDiscriminatorSignerData bytes
initialize[175, 175, 109, 31, 13, 152, 155, 237]admin50
set_config[108, 158, 154, 175, 212, 98, 52, 66]admin50
open_inbox[210, 172, 188, 164, 4, 122, 231, 223]wallet40
rotate_inbox_key[201, 165, 115, 46, 57, 80, 165, 180]wallet40
buy_pass[57, 144, 218, 182, 67, 42, 234, 124]wallet43
post[223, 96, 234, 236, 158, 106, 145, 94]relay340 + payload
close_nullifiers[109, 92, 160, 8, 227, 29, 94, 112]anyone16

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

#AccountWritableSigner
0adminyesyesPays every rent. Must be the program's upgrade authority.
1configyesPDA "config", created with 83 bytes.
2poolyesPDA "pool", created with 2,920 bytes.
3vaultyesPDA "vault", created with 0 bytes, owned by the System Program.
4fee_vaultyesPDA "fee_vault", created with 0 bytes, owned by the System Program.
5program_dataThe program's ProgramData account.
6program5hJVoxABR1b9QqnQ7FfZDtY2fgNGkUsQtPBqjyBLPTU3
7system_program11111111111111111111111111111111

Arguments

configConfigArgs, 42 bytes
In Borsh, in this order: message_fee u64, relay_fee u64, protocol_share_bps u16, tiers [u32; 3], lengths [u16; 3], day_length_seconds u32, root_history_size u16.

Checks

  1. program_data.upgrade_authority_address is admin: else Unauthorized.
  2. program.programdata_address is program_data: else Unauthorized.
  3. 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:

  1. message_fee > 0, relay_fee > 0 and protocol_share_bps <= 10,000: else InvalidConfiguration.
  2. 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: else InsolventConfiguration.
  3. day_length_seconds > 0 and root_history_size between 1 and 64: else InvalidConfiguration.
  4. Every tier and every length is above zero: else InvalidConfiguration.
  5. tiers[0] < tiers[1] < tiers[2] and lengths[0] < lengths[1] < lengths[2]: else InvalidConfiguration.
  6. tiers[2] × lengths[2] × message_fee fits a u64: else ArithmeticOverflow.

set_config#

Replaces the configuration. Every field of Config except admin and bump takes the new value, the day length included.

Accounts

#AccountWritableSigner
0adminyes
1configyesPDA "config". Its admin must be the signer.
2poolPDA "pool". Checked by seeds and bump, otherwise unused.

Arguments. config: ConfigArgs, encoded as for initialize.

Checks

  1. config.admin is the signer: else Unauthorized.
  2. 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

#AccountWritableSigner
0walletyesyesPays the fee and the rent.
1inboxyesPDA "inbox", wallet. Created with 101 bytes.
2system_program
3event_authorityPDA "__event_authority"
4program5hJVoxABR1b9QqnQ7FfZDtY2fgNGkUsQtPBqjyBLPTU3

Arguments

inbox_key[u8; 32], 32 bytes
The X25519 public key, raw bytes.

Checks

  1. The inbox address holds no account. Anchor's init fails with the System Program's "already in use" error when the wallet has an Inbox; the API answers INBOX_ALREADY_OPEN.
  2. inbox_key is not 32 zero bytes: else InvalidInboxKey.

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

#AccountWritableSigner
0walletyesPays the fee.
1inboxyesPDA "inbox", wallet. Its wallet must be the signer.
2event_authorityPDA "__event_authority"
3program5hJVoxABR1b9QqnQ7FfZDtY2fgNGkUsQtPBqjyBLPTU3

Arguments

inbox_key[u8; 32], 32 bytes
The new X25519 public key.

Checks

  1. inbox_key is not 32 zero bytes: else InvalidInboxKey.
  2. inbox_key differs from the current key: else InboxKeyUnchanged.
  3. key_version + 1 fits a u32: else ArithmeticOverflow.

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

#AccountWritableSigner
0walletyesyesPays the fee and the price.
1configPDA "config"
2poolyesPDA "pool"
3vaultyesPDA "vault"
4fee_vaultyesPDA "fee_vault"
5system_program
6event_authorityPDA "__event_authority"
7program5hJVoxABR1b9QqnQ7FfZDtY2fgNGkUsQtPBqjyBLPTU3

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 ids light, daily and frequent to these indexes.
daysu16, 2 bytes
One of Config.lengths.

Checks

  1. id_commitment is below the BN254 field modulus: else InvalidFieldElement.
  2. tier indexes a configured tier: else InvalidTier.
  3. days is one of the configured lengths: else InvalidPassLength.
  4. The clock's unix timestamp is not negative: else InvalidClock.
  5. today + days − 1 fits a u64: else ArithmeticOverflow.
  6. limit × days × message_fee fits a u64: else ArithmeticOverflow.
  7. The Poseidon hash of the leaf succeeds: else InvalidFieldElement.
  8. next_index < 2^26: else PoolFull.
  9. 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), with limit and expiry_day as 32-byte big-endian scalars;
  • it is inserted at next_index, the new root goes into the next ring position and next_index goes up by one;
  • price = limit × days × message_fee; floor(price × protocol_share_bps / 10,000) moves from the wallet to FeeVault and the rest to Vault (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

#AccountWritableSigner
0relayyesyesPays the transaction fee and the Nullifier's rent. Receives the relay fee.
1configPDA "config"
2poolPDA "pool"
3vaultyesPDA "vault"
4nullifieryesPDA "nullifier", day as u64 LE, nullifier.
5system_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

  1. day equals floor(unix_timestamp / day_length_seconds): else WrongDay (or InvalidClock for a negative timestamp).
  2. root is among the latest root_history_size roots of the pool: else UnknownRoot.
  3. The payload is at least 251 bytes and its first byte is 1: else InvalidPayload.
  4. The nullifier account is owned by the System Program and holds no data: else SpentNullifier.
  5. The proof verifies against the six public inputs root, day, nullifier, the payload hash, and the relay address split in two: else ProofInvalid.
  6. The relay holds the Nullifier's rent. A shortfall fails the System Program transfer, and the relay answers INSUFFICIENT_FUNDS.
  7. The Vault keeps its rent-exempt minimum for 0 bytes after paying relay_fee: else VaultInsufficientFunds, which the relay answers as VAULT_EMPTY, retryable.

The public inputs are built in the program from what it holds, so the relay cannot change them:

Input32-byte big-endian value
rootroot as given
dayday in the last 8 bytes
nullifiernullifier as given
payload hasha zero byte, then the first 31 bytes of SHA-256(payload)
relay low16 zero bytes, then bytes 16 to 31 of the relay's address
relay high16 zero bytes, then bytes 0 to 15 of the relay's address

Effects

  • The nullifier account 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, and day, nullifier, relay and bump are written.
  • relay_fee moves 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

#AccountWritableSigner
0calleryesPays the transaction fee.
1configPDA "config"
2…pairsyesRemaining accounts: a Nullifier, then the relay recorded in it, repeated.

Arguments

dayu64, 8 bytes
The day to close.

Checks

  1. day + 1 < today, so the day and the day after it have ended: else DayNotClosable (ArithmeticOverflow when day + 1 overflows).
  2. The remaining accounts are not empty and their count is even: else InvalidCloseAccounts.
  3. For each pair, in order:
    1. both accounts are writable: else InvalidCloseAccounts;
    2. the Nullifier is owned by the program: else InvalidCloseAccounts;
    3. its data decodes as a Nullifier (Anchor's discriminator and deserialization errors otherwise);
    4. its day is the argument: else InvalidCloseAccounts;
    5. its relay is the second account of the pair: else InvalidCloseAccounts;
    6. its address is the PDA of "nullifier", day, its stored nullifier and bump: else InvalidCloseAccounts;
    7. the relay's new balance fits a u64: else ArithmeticOverflow.

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.