• Reading the docs…
Start trading

Program reference

privium_pool

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 tt 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 W=9,000W = 9{,}000 (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 EkeyE_{\mathrm{key}} and the measurements, and the Council’s account holds nn and tt. 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 TaT_a, u64
40..48 Exits added ΔXa\Delta X_a, u64
48..56 fees ΔFa\Delta F_a, u64
56..64 shard 0 cut, u64
64..72 shard 1 cut, u64
72..104 commitment delta ΔΓa\Delta\Gamma_a, ristretto255
104..136 aggregate opening RaR_a, 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 zaz_a, SHA256 of privium/conserve/v1 ‖ SHA256(MkM_k) ‖ the asset’s Ledger index (u32) ‖ TaT_a (u64), reduced to a scalar, and runs one ristretto255 multiscalar multiplication over every asset in the Commit:

math
∑aza(Γa+ΔΓa)−(∑azaTa)G−(∑azaRa)H=O\sum_{a} z_a \big(\Gamma_a + \Delta\Gamma_a\big) - \Big(\sum_{a} z_a T_a\Big) G - \Big(\sum_{a} z_a R_a\Big) H = O

Commit explains what the equation proves.

Data availability accumulator#

open_crossing seeds the accumulator as δ0=SHA256(privium/da/v1 ∥ idprog ∥ k)\delta_0 = \mathrm{SHA256}(\texttt{privium/da/v1} \,\|\, \mathsf{id}_{\mathrm{prog}} \,\|\, k), with kk as a u64. Each log_diff advances it as δ←SHA256(δ ∥ i ∥ chunki)\delta \leftarrow \mathrm{SHA256}(\delta \,\|\, i \,\|\, \mathit{chunk}_i), with the chunk index ii 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 δ\delta, then closes the CrossingState, so no chunk follows. A reader recomputes δ\delta 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 jj of the Exit index choosing the side at level jj, 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 ΔXa\Delta X_a 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.