The pool
The tree every pass is a leaf of, how a purchase joins it, and how a proof points into it.
The pool is every pass ever bought, as leaves of one Poseidon Merkle tree of height 26. A proof says that its pass is one of these leaves and nothing more. The tree lives in one account, Pool, and the SOL that passes paid lives beside it in the Vault and the FeeVault.
The tree in one account#
The program keeps no leaves on chain. It keeps what an incremental tree needs to append the next leaf and to know its recent roots:
- The next index: the position the next leaf takes. Leaves are appended left to right and never move.
- The filled subtrees: one node per level, 26 in all: the left sibling a new leaf meets at that level on its way to the root.
- The ring of recent roots: the last 64 roots, each written when a leaf was appended, with a pointer to the newest.
Program accounts gives the account's fields and size.
Zero leaves#
An empty leaf is 0. Each level's empty node is the Poseidon hash of the empty node below it, taken twice, so the empty tree has one fixed root. initialize writes the empty nodes into the filled subtrees and the empty root as the first root in the ring. The SDK computes the same values, and the program's copies are generated from the circuit's build.
Poseidon here is BN254 with the x⁵ S-box, inputs and outputs as 32-byte big-endian field elements, the same function the circuit uses. On chain it runs in Solana's Poseidon syscall.
Capacity#
The tree holds 226 leaves: 67,108,864 passes. A purchase into a full tree fails with PoolFull.
How a pass joins the pool#
buy_pass takes the wallet's id_commitment, a tier and a length in days, and in one instruction:
Prices it
The price is the tier's daily limit × the days × the message fee. With the development defaults, a 25-a-day pass for 30 days costs 0.0075 SOL. Passes lists every price.
Computes the leaf
Today is the chain's Unix time divided by the configured day length, rounded down. The expiry day is today plus the days bought, minus one, so a pass of N days covers today and the N - 1 days after it. The leaf is
Poseidon(id_commitment, limit, expiry_day), whereid_commitmentisPoseidon(secret)of a pass secret only the wallet's keys derive. Theid_commitmentmust be a BN254 field element, or the purchase fails withInvalidFieldElement.Appends it
The leaf takes the next index. Walking up the levels, each node is hashed with its filled subtree or with that level's empty node, the filled subtrees are updated, and the new root is written into the ring.
Splits the payment
The protocol's share of the price goes to the
FeeVaultand the rest to theVault, both from the buying wallet.Emits PassPurchased
The event carries the leaf and everything the indexer needs to serve it.
A pass is valid on every day from its purchase day through its expiry day, inclusive.
The PassPurchased event#
PassPurchased is emitted through Anchor's event CPI, so it survives log truncation.
- indexu64
- The leaf's position in the tree.
- leaf[u8; 32]
Poseidon(id_commitment, limit, expiry_day).- root[u8; 32]
- The root after this leaf was appended.
- id_commitment[u8; 32]
- The commitment the wallet supplied.
- daily_limitu32
- The tier's messages a day.
- expiry_dayu64
- The last day the pass is valid.
- purchased_dayu64
- The day of the purchase.
- daysu16
- The length bought.
- price_lamportsu64
- What the wallet paid.
- purchaserpubkey
- The buying wallet.
- slotu64
- The slot of the purchase.
- block_timei64
- The chain's Unix time at the purchase.
A purchase is public: which wallet bought which leaf, when and for how much. What a pass sends afterwards is not, because a proof never reveals which leaf it holds.
The Vault and the FeeVault#
Both are program addresses with no data, owned by the system program, and no key signs for either.
- The
Vaultholds what each pass paid toward its messages. On everypostit pays the relay the relay fee, 7,500 lamports by development default, and it always keeps its own rent-exempt minimum. Apostthe Vault cannot pay fails withVaultInsufficientFunds, which the relay answers asVAULT_EMPTY, retryable. - The
FeeVaultreceives the protocol's share of each sale, rounded down. No instruction withdraws from it. TALARIA covers what the share is for.
Configuration requires that the message fee, less the protocol's share of it, covers the relay fee, so the price of every pass covers the relay fee of every message it can send. Configuration gives the rule.
Why every client builds its own path#
A proof needs the Merkle path from the pass's leaf to a root. The pool account does not store leaves, so the path is built from the leaves the indexer read from PassPurchased events.
Asking the indexer for one path would tell it which leaf is the asker's. So every client downloads every leaf from GET /pool/leaves, rebuilds the whole tree on its own device, checks that its root equals the root GET /pool reports, and reads its own path from it. The indexer serves the same leaves to everyone and learns nothing about which one anyone holds.
Recent roots and UnknownRoot#
A proof is made against one root. post accepts it if that root is among the latest roots the configuration admits: the root history size, at most 64. The ring always holds the last 64; the configuration decides how many of them count.
Every purchase writes a new root. If enough passes are bought between the moment a client built its path and the moment its post executes that its root has left the accepted history, the post fails with UnknownRoot and nothing lands. The nullifier is not recorded, so the writer loses nothing: the client downloads the new leaves, builds a new path to the current root, proves again and sends. The SDK also refuses to prove when the tree it built does not match the pool's current root, with UNKNOWN_ROOT, which is retryable.
Errors lists UnknownRoot, PoolFull and the rest.