privium_pool is the Anchor program that holds the Pool: the vault shards and deposit queues, the Ledger root, the Registry of enclave keys, the Council and the Escape. This page gives its identity, what its admin, its admission authority and its upgrade authority can change, the byte formats it verifies, and the compute its transactions measured.
Program#
| Program id | BH2ggvL6MxJ96zQhiuCdJDym84kN4RPpkf4bVJgZAVYe |
| Framework | Anchor 0.31.1, compiled for SBPF v0 |
| Instructions | 32, in Instructions |
| Accounts | 14 types, in Accounts |
| Events | 12, emitted through Anchor’s event CPI (Events) |
| Errors | 47 custom codes from 6000 (Errors) |
| IDL | PRIVIUM_POOL_IDL from @privium/sdk/program (SDK types) |
The Anchor IDL built with the program is the source of every table in this reference: instruction discriminators, account order and flags, seeds, layouts, events and errors. The SDK ships the same IDL.
The admin#
PoolConfig.admin is the Pool’s configuration key: it signs every instruction in the table below. initialize sets it to the key that held the program’s upgrade authority at that moment: the program read it from the canonical ProgramData account (seeds: the program id, under BPFLoaderUpgradeab1e11111111111111111111111) and required it to sign. From then on only set_admin, signed by the current admin, changes it; a later change of the upgrade authority leaves it as it is. The admin and the upgrade authority are both the vault of the governance multisig (Trust model).
| The admin signs | And sets |
|---|---|
set_admin |
the admin, any key but the default |
set_admission_authority |
the admission authority, any key but the default |
set_fee_recipient |
the fee recipient, any key but the default |
set_fee_rate |
the fee rate φ, 0 to 10,000 basis points |
set_escape_window |
the liveness window W, above zero |
create_shard, admit_asset |
a new mint’s vault shard 1 and its AssetState, as the admission authority can too |
initialize_registry |
once: the first admitted measurements, the key epoch length and the development gate |
configure_verifier |
once: the Groth16 verifying key, the guest identity and the Intel root hash |
initialize_council |
once: the Council |
admit_platform |
each platform and each renewal of it, with a Groth16 proof of its collateral, or on the development gate in a Registry initialized with it open |
reset_escape |
only before the first Commit: an Escape triggered at k = 0, when the Ledger holds no balance, is cleared and the liveness window restarts |
Fixed once set: Δ, the opener lease, the price age, κ, β₀ and the shard count; the Pool authority; the Registry’s key epoch length and development gate; and the verifier configuration. The Registry’s measurements only grow, through the upgrade authority’s proposals. The Council changes only through rotate_council, which of its current members sign, never the admin.
No admin instruction moves tokens. The Pool authority signs only inside consolidate_vault, route_residual, commit, release_exit, refund_deposit and escape_claim, each behind its own checks.
The admission authority#
PoolConfig.admission_authority is the one key besides the admin that can sign create_shard and admit_asset, and it signs no other instruction. initialize sets it to the admin, and only the admin changes it, with set_admission_authority. Admission creates the new mint’s own vault shard 1, AssetState and queue bindings; it moves no tokens and writes no other asset’s accounts.
Upgrade authority#
The program is deployed under Solana’s upgradeable loader, and its upgrade authority is the governance multisig’s vault, the same key as the admin, with a time lock (Trust model sets out its policy). The authority proposes each new enclave measurement with propose_measurement, which reads it afresh from ProgramData. The measurement enters the Registry only through activate_measurement, two escape windows after the proposal: 18,000 slots at (Attestation).
Configuration#
PoolConfig holds the Pool’s parameters. initialize accepts the fixed ones only at their values.
| Parameter | Field | Value | Changed by |
|---|---|---|---|
| Batch interval Δ | delta_slots |
4 slots | fixed |
| Liveness window W | escape_window_slots |
above zero | set_escape_window |
| Opener lease | lease_slots |
above zero | fixed |
| Pyth price age | max_price_age |
75 seconds | fixed |
| Confidence limit κ | kappa_bps |
25 basis points of the price | fixed |
| Residual bound floor β₀ | beta0_bps |
50 basis points | fixed |
| Fee rate φ | fee_rate_bps |
0 to 10,000 basis points | set_fee_rate |
| Fee recipient | fee_recipient |
a wallet | set_fee_recipient |
| Vault shards S | shards |
2 | fixed |
The program stores φ; the fee amounts a Commit pays are the ones its signed message states. The Registry holds the key epoch length and the measurements, and the Council’s account holds and . The layout is in PoolConfig.
Signature verification#
A program cannot call Solana’s signature precompiles, so it reads the precompile instruction the transaction carries just before it, through the Instructions sysvar. privium_pool accepts one shape only: the instruction at index current minus one belongs to the expected precompile, verifies exactly one signature, and points every offset into its own data at fixed positions.
| Bytes | Holds |
|---|---|
| 0 | signature count, 1 |
| 1 | padding, 0 |
| 2..4 | signature offset, 16 |
| 4..6 | signature instruction index, 0xFFFF (this instruction) |
| 6..8 | public key offset, 80 |
| 8..10 | public key instruction index, 0xFFFF |
| 10..12 | message offset: 112 for Ed25519, 113 for P-256 |
| 12..14 | message size, through the end of the data |
| 14..16 | message instruction index, 0xFFFF |
| 16..80 | signature |
| 80.. | public key: 32 bytes Ed25519, 33 bytes compressed P-256 |
| 112.. or 113.. | message |
A missing or different precompile instruction fails MissingSig; any other count or offset fails BadSigLayout.
| Precompile | Used by | Key accepted |
|---|---|---|
Ed25519 (Ed25519SigVerify111111111111111111111111111) |
open_crossing, consolidate_vault, route_residual, commit |
an admitted Registry key whose interval holds the current slot (UnknownEnclave, KeyExpired) |
secp256r1 (Secp256r1SigVerify1111111111111111111111111) |
verify_enclave_qe |
the Platform’s PCK, over the 384-byte QE report |
| secp256r1 | register_enclave |
the attestation key, over the 632-byte TD quote |
The enclave’s key is never a transaction signer, so any relayer can submit what the enclave signed.
Signed messages#
Every message starts with its domain tag and the program id, so a signature made for one message kind or one deployment never passes as another. Integers are little endian; keys, hashes and points are raw 32 bytes. Each layout must end exactly where the message ends (Message).
Open#
128 bytes, verified by open_crossing.
| Bytes | Field |
|---|---|
| 0..15 | privium/open/v1 |
| 15..47 | program id |
| 47..55 | key epoch, u64 |
| 55..63 | Crossing index k, u64 |
| 63..95 | relayer |
| 95 | mid count, u8, at most 8 |
| 96..128 | price inputs hash |
The price inputs hash is SHA256 over the Pyth values of each mid in remaining-account order, 60 bytes each: mint, price i64, confidence u64, exponent i32, publish time i64. It leaves validity out: open_crossing computes each mid’s validity from its own Clock and stores the mids hash, SHA256 over the same entries with each mid’s valid byte appended, 61 bytes per mid. A mid is valid when its price is positive, its publish time is no more than 75 seconds old and at most 1 second ahead, and its confidence is within 25 basis points of the price. The enclave reads the recorded mids and their validity back from the CrossingState before it crosses, and its Commit signs the stored hash.
Consolidate#
110 bytes, verified by consolidate_vault.
| Bytes | Field |
|---|---|
| 0..22 | privium/consolidate/v1 |
| 22..54 | program id |
| 54..62 | key epoch, u64 |
| 62..70 | Crossing index k, u64 |
| 70..102 | mint |
| 102..110 | amount, u64 |
Route#
216 bytes, verified by route_residual.
| Bytes | Field |
|---|---|
| 0..16 | privium/route/v1 |
| 16..48 | program id |
| 48..56 | key epoch, u64 |
| 56..64 | Crossing index k, u64 |
| 64..96 | pair identifier |
| 96..128 | input mint |
| 128..160 | output mint |
| 160..168 | input amount, u64: the most the route may spend |
| 168..176 | minimum output, u64 |
| 176..184 | deadline slot, u64 |
| 184..216 | route hash: SHA256(Jupiter program id ‖ instruction data ‖ each remaining account key, in order) |
route_residual invokes Jupiter (JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4) with exactly that data and those accounts, marking only the Pool authority as signer, and measures the spend and the receipt as the two shard 0 vaults’ deltas.
Commit#
A 294-byte header followed by 0 to 8 asset entries of 136 bytes, verified by commit. A heartbeat Commit has none.
| Bytes | Field |
|---|---|
| 0..17 | privium/commit/v1 |
| 17..49 | program id |
| 49..57 | key epoch, u64 |
| 57..65 | Crossing index k, u64 |
| 65..97 | prior Ledger root |
| 97..129 | new Ledger root |
| 129..161 | data availability accumulator |
| 161..193 | exits root |
| 193..197 | exits count, u32 |
| 197..229 | mids hash |
| 229..261 | fills hash |
| 261..293 | deposits digest |
| 293 | asset count, u8, 0 to 8 |
Each asset entry:
| Bytes | Field |
|---|---|
| 0..32 | mint |
| 32..40 | Ledger total , u64 |
| 40..48 | Exits added , u64 |
| 48..56 | fees , u64 |
| 56..64 | shard 0 cut, u64 |
| 64..72 | shard 1 cut, u64 |
| 72..104 | commitment delta , ristretto255 |
| 104..136 | aggregate opening , canonical scalar |
The fills hash is SHA256 over the fills route_residual recorded, 112 bytes each: pair, input mint, output mint, spent u64, received u64. The deposits digest is SHA256 over, for each asset in message order and each shard in turn, the chain hash of the queue entry just below the cut (32 zero bytes for a cut of 0).
For each asset the program checks the vault identity in base units: the two shards, after the fee payment, hold the Ledger total, the committed Exits not yet released and the deposits past the new cuts. The commitment check then weighs each asset by , SHA256 of privium/conserve/v1 ‖ SHA256() ‖ the asset’s Ledger index (u32) ‖ (u64), reduced to a scalar, and runs one ristretto255 multiscalar multiplication over every asset in the Commit:
Commit explains what the equation proves.
Data availability accumulator#
open_crossing seeds the accumulator as , with as a u64. Each log_diff advances it as , with the chunk index as a u32 counting from 0 and each chunk 1 to 3,800 bytes. commit requires at least one chunk and the signed accumulator equal to , then closes the CrossingState, so no chunk follows. A reader recomputes from the log_diff instruction data of the Crossing’s transactions and compares it with Committed.da.
Exit leaf#
Each Exit the enclave lists is a 105-byte leaf in the Commit’s exits tree:
| Bytes | Field |
|---|---|
| 0 | 0x02 |
| 1..9 | Crossing index k, u64 |
| 9..13 | Exit index, u32 |
| 13..21 | origin Crossing index, u64 |
| 21..25 | origin Exit index, u32 |
| 25..57 | mint |
| 57..89 | destination |
| 89..97 | amount, u64 |
| 97..105 | release slot, u64 |
The leaf hash is SHA256 of those bytes; each parent is SHA256(0x01 ‖ left ‖ right), with bit of the Exit index choosing the side at level , up to 32 levels. release_exit pays only from the release slot on, so the delay the enclave sampled for the Exit holds on chain. The root it proves against is the exits root stored for k among the last 64 Commits (LedgerRoot).
The origin is the Crossing and Exit index under which a Commit first listed the Exit, equal to k and the Exit index in that first leaf. A later Commit that lists the unpaid Exit again keeps the origin and every other field but k and the Exit index (Exit), and its counts only the Exits it lists for the first time. release_exit creates the PaidRecord at the origin, so an Exit pays once, whichever root its path proves against.
Events#
Every event goes out with emit_cpi!: the program invokes itself with the event as instruction data, signed by its ["__event_authority"] PDA. An event therefore sits in the transaction’s inner instructions and survives log truncation. Decoding is in Events.
Compute units#
Measured on the mainnet-faithful localnet for each instruction a user sends, each of a Crossing’s transactions, and a measurement upgrade’s proposal and activation. Each figure is the program’s own consumed line from a successful run, including the work of its CPIs (token transfers, Jupiter’s swap inside route_residual, the event CPI).
| Instruction | Runs | Compute units | Measured on |
|---|---|---|---|
deposit |
4 | 24,740 to 28,300 | SOL, USDC and the Token-2022 transfer-fee mint. |
release_exit |
1 | 47,503 | Native SOL. |
trigger_escape |
2 | 28,886 to 28,947 | With an open Crossing's Residual fill copied. |
refund_deposit |
1 | 17,018 | One uncredited deposit. |
escape_request |
1 | 28,623 | One leaf with its 32-sibling path. |
escape_claim |
1 | 75,343 | A claim split across the Residual's two assets. |
open_crossing |
3 | 44,255 to 45,755 | Two assets, each with a Pyth PriceUpdateV2 account. |
route_residual |
2 | 195,262 to 201,907 | A captured Jupiter route. |
log_diff |
2 | 1,686 | One chunk. |
commit |
2 | 73,655 to 78,919 | Two assets; the higher run pays both fees, lists an Exit and carries a fill. |