• Reading the docs…
Start trading

Concepts

Pool

The Pool is Privium’s custody: the privium_pool program holds every deposited token in per-asset vault shards owned by a program-derived authority. Only the program’s own instructions move those tokens, each one gated by a check the program runs itself.

What the program holds#

One program owns all of Privium’s on-chain state, so a Commit reads everything it checks without a cross-program call.

State Holds Concept
Pool the configuration, one asset state per admitted mint, the vault shards and their deposit queues this page
Ledger the Ledger root, and the state of the open Crossing Ledger, Crossing
Registry admitted enclave measurements and the attested enclave keys, each with its validity interval Coprocessor
Council configuration the Council key, each member’s verification key, nn and tt Council

The Pool’s configuration sets the vault shard count S=2S = 2, the batch interval Δ=4\Delta = 4 slots, the liveness window W=9,000W = 9{,}000 slots, the fee rate ϕ\phi (10 bps) and the fee recipient. Layouts and seeds are in Accounts.

Vault shards and the Pool authority#

Each admitted mint has two vault shards, both token accounts of that mint owned by the Pool authority. Shard 0 is the authority’s associated token account, which Jupiter’s router takes directly as swap source and destination, so every Residual swap and every fee payment runs from shard 0. Shard 1 is a program-derived token account of the same authority. Deposits land in either, the SDK choosing uniformly at random. Exit releases, Escape payouts and Escape refunds draw from shard 1 first and from shard 0 only when shard 1 cannot cover the payment, whichever shard a refunded deposit entered. That keeps shard 0 for the Crossing’s routes and fees, and a payout that empties one shard leaves every uncredited deposit refundable from the other. A mint’s vault balance VaV_a is the sum of its shards, and SOL is held as wrapped SOL, an ordinary mint.

The Pool authority is a program-derived address with no private key; only invoke_signed inside privium_pool signs for it. The vault balances are public token accounts. How each vault divides among traders is held in the Ledger. Pool shows each vault’s holdings per mint, live.

What moves tokens#

Instruction Moves Authorized by Gated by
deposit into a vault shard the SDK picks at random the depositing wallet no Escape active; room in the shard’s queue; the credit is the measured vault delta
consolidate_vault from shard 1 into shard 0 of the same mint the enclave the opening key’s signature over the Crossing, the mint and the amount, inside the Crossing’s lease; no Escape active; at most the asset’s committed Ledger total; once per mint per Crossing, whose Commit must carry the mint
route_residual out of shard 0 of the input mint, into shard 0 of the output mint the enclave its signature over the Residual order and the exact route accounts; spent at most the signed input; received at least the signed minimum; one Crossing spends no more of an asset than its committed Ledger total
commit the Crossing’s fees, from shard 0 of SOL or USDC to the fee recipient the enclave the signed Commit that states each amount (Commit)
release_exit an Exit’s amount to its destination anyone the Exit’s inclusion under a committed exits root; its release slot reached; paid once
refund_deposit an uncredited deposit back to its source, from either shard anyone Escape active; the entry lies past the last credited cut; paid once
escape_claim an owner’s last committed balance the claim proof, made with the owner’s escape key the leaf under the frozen root, tt Council shares and the claim proof bound to the destination; paid once

No other instruction signs for the authority. A route spends the authority’s signature only on the accounts the enclave signed, since the program recomputes the route’s hash over exactly what it invokes.

The deposit queue#

Every vault shard has a deposit queue: a ring of up to 512 entries waiting to be credited. deposit transfers the tokens, measures what the shard actually received, and appends an entry with that amount, the running cumulative amount, the slot, the source token account and the digest of an encrypted note, all folded into a running chain hash. The note is sealed to the enclave’s HPKE key and names the trader’s Ledger record. It stays in transaction data, so the public record shows an amount entering a shard and never which leaf it credits.

A deposit writes only its shard’s vault and queue and the source account, so deposits on different shards run in parallel; the SDK draws the shard uniformly at random. The whitepaper estimates the ceiling at 2,000 deposits per asset per block.

Each Commit names a cut per shard and takes up exactly the entries between the previous cut and the new one, so every deposit is taken up in one Crossing, once. A cut never moves backward or past the queue’s head, and the Commit’s deposits digest must match the chain hashes the program wrote at the cuts, so a deposit that never landed cannot be credited.

The Coprocessor reads each entry from the transaction that made it, whether a wallet called deposit directly or another program called it, and moves a cut only over consecutive entries it has read in full. An entry it cannot read yet holds its shard’s cut just before it until a later Crossing; the asset’s other shard and every other asset commit as usual.

A deposit whose note does not open under the enclave’s key, does not decode as a note with valid keys, or disagrees with the registration the Ledger already holds for its account credits no balance and never holds up the Crossing. The cut passes it with the rest, and the same Commit lists its amount as an Exit to the owner of the source token account, as the program recorded it at the deposit, due at once, so in that Commit’s conservation check the amount moves from the uncredited deposits into XaX_a. release_exit pays it like any committed Exit, and the deposit reads refunded once it is paid (Deposit states).

While an Escape is active, deposit fails and refund_deposit returns each entry past the last cut to the source it records. The trader’s side is in Deposits.

Assets the Pool admits#

The admin, or the admission authority the admin names in PoolConfig, admits each mint (The admission authority): create_shard creates its vault shard 1, and admit_asset creates its asset state and records its two deposit queues, allocated beforehand at fixed size. A mint is admitted when each of its token extensions has a treatment (next section). Its asset state records the token program and decimals, the admitted extensions, the Pyth feed (a pair on a mint with no feed routes its whole flow as the Residual), and what the last Commit attested: the Ledger total TaT_a, the committed Exits not yet released XaX_a, the commitment accumulator Γa\Gamma_a, and how many entries each shard has had credited.

Token and Token-2022#

Each vault uses its mint’s own token program, recorded in the asset state, and every transfer goes through transfer_checked, which serves both programs and is the form Token-2022 extensions require.

Extension Treatment
TransferFeeConfig Deposits and routes credit the measured vault delta, never the amount sent. A consolidation from shard 1 to shard 0 records what the fee took, and the Crossing that moved it charges that amount across the asset’s Ledger balances, in proportion to their size
TransferHook Admitted with the one hook program admit_asset names for the mint; every transfer of the mint carries the extra accounts the hook requires
ConfidentialTransfer Vaults hold the public balance; private entry and exit happen in a Ring or confidential account around the Pool
InterestBearingConfig Held in raw base units; interest is display only
PermanentDelegate, NonTransferable, ScaledUiAmount Not admitted: conservation needs vault balances that move only through Pool instructions, in base units that never rescale

The Pool verifies no ZK ElGamal proof. Vaults move public amounts, and the Ledger’s confidentiality rests on the enclave and the Council.

Conservation#

At every Commit the program checks one identity per touched asset, exact in base units:

math
Ta+Xa+∑j<S(Σa,jhead−Σa,j(c))=∑j<SVa,j(9.2)T_a + X_a + \sum_{j<S}\left(\Sigma^{\text{head}}_{a,j} - \Sigma^{(c)}_{a,j}\right) = \sum_{j<S} V_{a,j} \tag{9.2}

TaT_a is the Ledger total the Commit attests, XaX_a the committed Exits not yet released, Σa,jhead\Sigma^{\text{head}}_{a,j} shard jj‘s cumulative deposited amount, Σa,j(c)\Sigma^{(c)}_{a,j} the cumulative amount at its last credited entry, and Va,jV_{a,j} the shard’s balance. At every committed root, each vault token is a committed balance, a committed Exit awaiting release, or a deposit not yet credited.

Fees have no term. The Commit that charges them pays them from shard 0 to the fee recipient in the same instruction, so none stays in a vault; Fees and $PRV follows them from there.

The identity stays exact while other instructions land between the enclave’s snapshot and its Commit: the enclave signs deltas, release_exit lowers XaX_a together with the vault, and a late deposit enters both sides through Σhead\Sigma^{\text{head}}. Residual fills move the vaults only while their Crossing is open, and its Commit absorbs them into TaT_a. Because one Crossing’s routes, with what its consolidation of an asset lost to a transfer fee, spend at most TaT_a of that asset, committed Exits and uncredited deposits stay in the vault whatever a route returns.

The release rules in the table above rest on the program alone, whatever the enclave does. That the Ledger’s balances add up to TaT_a rests on the enclave’s arithmetic, and the Commit’s commitment check enforces it on the committed values (Commit). Trust model sets out each guarantee.