• Reading the docs…
Start trading

Program reference

Accounts

Every account privium_pool owns, with its size, address and byte layout. Offsets count Anchor’s 8-byte discriminator, so an account’s first field sits at byte 8.

Sizes and addresses#

Account Bytes Address Holds Discriminator
PoolConfig 176 pool The admin, the admission authority, the fee recipient, the Pool authority and the Pool's parameters. 1a6c0e7b74e6812b
LedgerRoot 2,696 ledger The committed root, its Crossing and slot, the Escape slot and the last 64 exits roots. 3a112bbc1fc9c8fa
AssetState 360 asset, mint One admitted mint: vault shards, queues, Ledger total, committed Exits, commitment sum, credited cuts and its last consolidation's loss. e9e584aaa9e162ab
DepositQueue 61,600 allocated keypair, recorded in AssetState One shard's ring of 512 deposit entries and its running totals. 1e1528c1543c6766
CrossingState 1,848 crossing, little-endian u64 k One Crossing: opener, lease, verified mids, Residual fills, consolidated mints and the DA accumulator. 19876c402ada11f6
Registry 920 registry The admitted measurements and up to four enclave keys, one per platform and epoch. 2fae6ef6b8b6fcda
MeasurementProposal 153 measurement, digest One proposed measurement, its source and build digests, and the slot from which it can activate. 9e6fe8fcbd83d93b
EnclaveKey 297 enclave, signing key One enclave epoch's keys through the three attestation stages. 6c050cc8d23472b6
Platform 141 platform, SHA256(compressed PCK) One admitted TDX platform: PCK, QE identity and TCB floor. 4d5ccc3abb625b0c
VerifierConfig 720 attestation-verifier The SP1 Groth16 key and the guest and root it binds. b067f8248aa7b0dc
CouncilConfig 632 council The Council key, the member keys and t. 6bb29c559c9c3651
EscapeState 976 escape The frozen root and the open Crossing's fills at the trigger. 8838e38d83fdaad9
EscapeRequest 800 escape-req, leaf index, mint One leaf's Escape request and the Council shares posted to it. f966cd799401533a
PaidRecord 9 exit, origin k, origin index; or escaped, leaf index, mint That one Exit or one Escape claim has paid. 0f6ad1ad6a31bbaa

Sizes include the discriminator. Addresses are PDAs of the program from the seeds shown, integers in seeds little endian, except DepositQueue. PoolConfig, LedgerRoot, AssetState, DepositQueue, CrossingState, Registry, VerifierConfig, CouncilConfig and EscapeState are zero-copy, laid out as C structs and read in place. MeasurementProposal, EnclaveKey, Platform, EscapeRequest and PaidRecord are Borsh. Every field of every account has a fixed size, so each offset below holds for every instance.

Two PDAs hold no data of their own: the Pool authority ["authority"], owner of every vault shard and the signer of every payout, and the event authority ["__event_authority"], the signer of the program’s event CPI.

Vault shards#

Each admitted mint has two vault shards, both token accounts of the mint owned by the Pool authority, in the mint’s own token program:

Shard Address Created by
0 the Pool authority’s associated token account: [authority, token_program, mint] under ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL the Associated Token Account program, before admit_asset
1 ["vault", mint, 1] under the program create_shard, sized for the mint’s required account extensions

admit_asset checks both addresses and that each vault belongs to the mint and the Pool authority with no delegate and no close authority, then records them in AssetState.vaults. Every instruction that moves a vault’s tokens checks the vault against that record and checks the same properties again.

Shard 0 is the shard Jupiter routes take as source and destination, and the shard commit pays fees from. consolidate_vault moves tokens into it from shard 1. Deposits land in either shard. release_exit, escape_claim and refund_deposit pay from shard 1 first and from shard 0 only for the rest, whichever shard a refunded deposit entered. SOL is held as wrapped SOL, and native payouts unwrap through a temporary token account (release_exit).

Deposit queues#

Each vault shard has a DepositQueue of 61,600 bytes. A program can allocate at most 10,240 bytes through a CPI, so a queue is not a program address: it is an ordinary account allocated in full with privium_pool as owner and all-zero data. admit_asset initializes both queues of the mint (Anchor’s zero constraint: owned by the program, rent-exempt, discriminator still zero, and the two queues distinct) and records their addresses in AssetState.queues. From then on the recorded address is the only one any instruction accepts for that shard, and no instruction changes it.

A queue is a ring of 512 entries. The entry with sequence ss sits at index s mod 512s \bmod 512; head is the next sequence, and AssetState.consumed holds each shard’s credited cut. A deposit fails QueueFull while 512 entries wait to be credited, so no uncredited entry is ever overwritten. Each entry folds into the queue’s chain hash, which the Commit’s deposits digest is checked against. The refund bitmap marks each ring index whose entry refund_deposit has paid.

Account layouts#

PoolConfig#

["pool"], created by initialize. The setters write admin, admission_authority, fee_recipient, fee_rate_bps and escape_window_slots; every other field is fixed. Configuration lists the parameters with their values.

Offset Field Type Meaning
8 admin Pubkey Signs every admin instruction. The upgrade authority at initialization; set_admin changes it.
40 fee_recipient Pubkey Wallet whose associated token accounts each Commit pays fees to.
72 authority Pubkey The Pool authority PDA ["authority"], owner of every vault shard.
104 delta_slots u64 Δ, slots from a Commit to the next open_crossing: 4.
112 escape_window_slots u64 W, slots without a Commit after which trigger_escape succeeds.
120 lease_slots u64 Slots an opener holds a Crossing while its key stays current in the Registry.
128 max_price_age i64 Pyth price age limit in seconds: 75.
136 fee_rate_bps u16 Fee rate φ in basis points.
138 kappa_bps u16 κ: a mid is valid only with confidence at most this many basis points of its price. 25.
140 beta0_bps u16 β₀, the Residual bound's floor in basis points: 50.
142 authority_bump u8 Bump of the Pool authority PDA.
143 shards u8 Vault shards per asset: 2.
144 admission_authority Pubkey The key besides the admin that signs create_shard and admit_asset. The admin at initialization; set_admission_authority changes it.

LedgerRoot#

["ledger"], created by initialize with the empty root of the depth-32 Ledger tree: SHA256(0x00), hashed up 32 levels as SHA256(0x01 ‖ zz ‖ zz). commit writes it; trigger_escape sets escape_from_slot. Every Commit writes this account, so Commits run one at a time while deposits, which only read it, run beside them.

Offset Field Type Meaning
8 k u64 Index of the last committed Crossing; 0 before the first Commit.
16 last_commit_slot u64 Slot of the last Commit, or of initialize before the first.
24 escape_from_slot u64 Slot trigger_escape ran; 0 while no Escape is active.
32 root [u8; 32] The committed Ledger root.
64 da_commitment [u8; 32] The last Commit's data availability accumulator.
96 mids_hash [u8; 32] The last Commit's mids hash.
128 exit_ring_head u32 Exits roots written so far; the next goes to slot head mod 64.
132 registry_epoch u32 Reserved; 0.
136 exit_roots ExitRoot × 64 The exits roots of the last 64 Commits, a ring.

AssetState#

["asset", mint], created by admit_asset, once per mint. commit writes the totals, the commitment sum and the cuts; release_exit lowers pending_exits; consolidate_vault writes consolidated_k and consolidation_loss.

Offset Field Type Meaning
8 mint Pubkey The admitted mint.
40 token_program Pubkey Token or Token-2022, the mint's owner.
72 oracle_feed [u8; 32] The Pyth feed id the asset's mid is read from.
104 ledger_total u64 T_a, the asset's Ledger total at the last Commit, in base units.
112 pending_exits u64 X_a, committed Exits not yet released, in base units.
120 gamma [u8; 32] Γ_a, the sum of the asset's leaf commitments, ristretto255.
152 queues Pubkey × 2 The deposit queues of shards 0 and 1.
216 vaults Pubkey × 2 Vault shards 0 and 1.
280 transfer_hook Pubkey The admitted transfer hook program; the default key for none.
312 registry_index u32 The asset's index in Ledger leaves and Intents.
320 consumed u64 × 2 Per shard, the sequence credited up to: the last Commit's cut.
336 decimals u8 The mint's decimals.
337 bump u8 Bump of ["asset", mint].
338 flags u8 Bit 0: transfer fee extension. Bit 1: transfer hook extension.
344 consolidated_k u64 Crossing of the asset's last consolidate_vault; 0 before the first.
352 consolidation_loss u64 Base units that consolidation lost to the mint's transfer fee: shard 1's drop less shard 0's rise.

DepositQueue#

An allocated account, one per vault shard, recorded in AssetState.queues (Deposit queues). deposit appends; commit reads the cuts; refund_deposit sets refund bits.

Offset Field Type Meaning
8 mint Pubkey The asset's mint.
40 head u64 Sequence of the next entry, the count ever appended.
48 cum_amount u64 Σ^head, base units ever received by this shard's deposits.
56 chain_hash [u8; 32] Running hash over every entry.
88 refunded [u8; 64] One bit per ring slot, set when that slot's entry is refunded.
152 shard u8 The shard this queue serves, 0 or 1.
160 entries DepositEntry × 512 Ring of 512 entries; sequence s sits at s mod 512.

CrossingState#

["crossing", k] with k a little-endian u64, created by the first open_crossing of Crossing k, paid for by its relayer. consolidate_vault adds each consolidated mint, route_residual adds fills, log_diff advances the accumulator, and commit closes it and returns its rent to the relayer. The mids it held stay readable in the CrossingOpened event (Events).

Offset Field Type Meaning
8 k u64 Crossing index.
16 opened_slot u64 Slot of the first open.
24 lease_until u64 Last slot the current opener may consolidate, route or commit.
32 epoch u64 Key epoch of the current opener.
40 opener Pubkey Signing key of the enclave that holds the Crossing.
72 relayer Pubkey Relayer named in the latest open message; signs log_diff.
104 mids_hash [u8; 32] SHA256 over the recorded mids, 61 bytes each, the valid byte the program computed included. The Commit signs this hash.
136 da_digest [u8; 32] Data availability accumulator over the posted chunks.
168 next_chunk u32 Index the next log_diff chunk carries.
172 da_sealed u8 1 once committed.
173 fill_count u8 Residual fills recorded.
174 mid_count u8 Mids recorded.
176 fills ResidualFill × 8 Residual fills, up to 8, one per pair.
1072 mids VerifiedMid × 8 Verified mids, up to 8.
1584 consolidated_mints Pubkey × 8 Mints consolidated in this Crossing, up to 8; its Commit must carry each.
1840 consolidation_count u8 Consolidations recorded.

Registry#

["registry"], created by initialize_registry. register_enclave fills its key slots, one per platform and key epoch, and activate_measurement appends measurements; the key epoch length and the development gate stay as initialized.

Offset Field Type Meaning
8 keys RegisteredKey × 4 Up to four enclave keys.
648 measurements [u8; 32] × 8 Admitted measurements, each SHA256(MRTD ‖ RTMR0 ‖ RTMR1 ‖ RTMR2 ‖ XFAM): those initialize_registry set, then each activate_measurement appends.
904 key_epoch_slots u64 E_key, key epoch length in slots.
912 measurement_count u8 Measurements in use, 1 to 8.
913 key_count u8 Key slots filled, up to 4.
914 allow_dev_platforms u8 1 when admit_platform's development gate is open. Set at initialization; no instruction changes it.

MeasurementProposal#

["measurement", measurement], created by propose_measurement, once per measurement. activate_measurement marks it activated when it appends the measurement to the Registry.

Offset Field Type Meaning
8 authority Pubkey The upgrade authority that proposed it.
40 measurement [u8; 32] The proposed measurement.
72 source_commit [u8; 32] Digest of the source commit, as proposed.
104 manifest_digest [u8; 32] Digest of the build manifest, as proposed.
136 proposed_slot u64 The slot of the proposal.
144 activation_slot u64 proposed_slot plus twice the escape window at the proposal; activate_measurement runs from this slot on.
152 activated bool True once the measurement is in the Registry.

EnclaveKey#

["enclave", signing_key], created by stage_enclave at stage 0 and advanced by verify_enclave_qe (stage 1) and register_enclave (stage 2). The record stays on chain after its epoch, so a signature made under it stays checkable.

Offset Field Type Meaning
8 epoch u64 Key epoch e.
16 signing_key Pubkey Ed25519 key pk_C.
48 hpke_key [u8; 32] X25519 key ek_C.
80 release_key [u8; 32] ristretto255 key Y_E.
112 anchor_slot u64 The recent slot whose hash the report data binds.
120 platform Pubkey The Platform the quote must come from.
152 report_data [u8; 64] The 64 bytes the quote must carry: SHA256("privium/attest/v1" ‖ program id ‖ e ‖ anchor slot ‖ its slot hash ‖ pk_C ‖ ek_C ‖ Y_E) ‖ 32 zero bytes.
216 ak_hash [u8; 32] SHA256 of the attestation key and QE authentication data, from the QE report. Written at stage 1.
248 measurement [u8; 32] The quote's measurement. Written at stage 2.
280 valid_from u64 e × E_key.
288 valid_until u64 (e + 1) × E_key.
296 stage u8 0 staged, 1 QE report verified, 2 admitted.

Platform#

["platform", SHA256(pck)], created by admit_platform, once per PCK.

Offset Field Type Meaning
8 pck [u8; 33] The PCK public key, compressed P-256.
41 fmspc [u8; 6] The platform family, FMSPC.
47 min_tcb_svn [u8; 16] The lowest TEE TCB SVN accepted, per component.
63 qe_signer [u8; 32] The Quoting Enclave's MRSIGNER.
95 qe_product u16 The Quoting Enclave's ISVPRODID.
97 qe_svn u16 The lowest Quoting Enclave ISVSVN accepted.
99 expires_at i64 The earliest collateral expiry, Unix seconds. Staging and quote checks fail after it.
107 tcb_status u8 0, UpToDate.
108 dev bool True when admitted through the development gate.
109 verifier Pubkey The VerifierConfig account at admission.

VerifierConfig#

["attestation-verifier"], created empty by initialize_registry and written once by configure_verifier.

Offset Field Type Meaning
8 root_hash [u8; 32] SHA256 of the Intel root CA certificate the guest verifies against.
40 guest_id [u8; 32] The DCAP guest's SP1 verification key; the proof's first public input.
72 alpha [u8; 64] α in G1.
136 beta [u8; 128] β in G2, negated.
264 gamma [u8; 128] γ in G2.
392 delta [u8; 128] δ in G2.
520 ic [u8; 64] × 3 Three G1 points, for the two public inputs.
712 configured u8 1 once configure_verifier has run.

CouncilConfig#

["council"], created by initialize_council and rewritten by each rotate_council, which moves it to the next Council epoch under the same Council key. council_log names the same address, so the Council’s transcript is listed under it from the first message of key generation on, before this account exists.

Offset Field Type Meaning
8 epoch u64 Council epoch: as initialize_council set it, one higher after each rotate_council. trigger_escape records it in EscapeState.
16 joint_key [u8; 32] The Council key P_C, ristretto255.
48 verification_keys [u8; 32] × 9 Member verification keys S_j = s_j·P_C; the first n are used.
336 signer_keys Pubkey × 9 Member Ed25519 keys, each signing its member's Council transcript messages; the first n are used.
624 n u8 Members, 1 to 9.
625 threshold u8 t, with 2t greater than n.

EscapeState#

["escape"], created by trigger_escape. It exists only once the Escape is active, and nothing writes it after.

Offset Field Type Meaning
8 frozen_root [u8; 32] The Ledger root at the trigger; requests prove against it.
40 trigger_slot u64 Slot of the trigger.
48 last_commit_slot u64 Slot of the last Commit before it.
56 crossing u64 Index of the last committed Crossing.
64 council_epoch u64 Council epoch at the trigger; shares come from it.
72 fills ResidualFill × 8 Residual fills of the open Crossing k + 1 at the trigger.
968 fill_count u8 Fills copied.

EscapeRequest#

["escape-req", leaf_index, mint] with the leaf index a little-endian u32, created by escape_request. escape_share appends shares and combines them; escape_claim marks it claimed.

Offset Field Type Meaning
8 leaf_index u32 The leaf's position in the Ledger tree.
12 mint Pubkey The leaf's mint.
44 owner_key [u8; 32] The owner's escape public key Y.
76 commitment [u8; 32] The leaf's commitment C.
108 handle [u8; 32] The leaf's Council handle D.
140 council_epoch u64 Council epoch the shares come from.
148 members [u8; 9] Members who posted, in order.
157 shares_a [u8; 32] × 9 Posted A_j, in the same order.
445 shares_b [u8; 32] × 9 Posted B_j, in the same order.
733 count u8 Shares posted.
734 combined bool True once t shares are combined into A and B.
735 claimed bool True once paid.
736 a [u8; 32] Combined A, the Lagrange-weighted sum of the A_j.
768 b [u8; 32] Combined B, the Lagrange-weighted sum of the B_j.

PaidRecord#

Nine bytes created at the moment of a payment, so a second payment of the same item fails when it tries to create the account again: ["exit", origin_k, origin_index] (u64 and u32, little endian), the Exit’s origin, for release_exit, ["escaped", leaf_index, mint] for escape_claim.

Offset Field Type Meaning
8 paid bool True once paid. The account's existence already marks the payment taken.

Nested structs#

Offsets count from the start of the struct, laid out as its account lays it out.

ExitRoot#

One slot of LedgerRoot.exit_roots, 40 bytes.

Offset Field Type Meaning
0 k u64 Crossing whose Commit listed the Exits.
8 root [u8; 32] The exits root; all zeros pays nothing.

DepositEntry#

One entry of DepositQueue.entries, 120 bytes.

Offset Field Type Meaning
0 amount u64 Base units the vault received.
8 cum_amount u64 The queue's cumulative amount through this entry.
16 slot u64 Slot the deposit landed in.
24 source Pubkey Token account the deposit came from; a refund returns to it.
56 note_hash [u8; 32] SHA256("privium/note/v1" ‖ note).
88 chain_hash [u8; 32] SHA256(previous chain hash ‖ amount ‖ slot ‖ note_hash).

ResidualFill#

One fill in CrossingState.fills and EscapeState.fills, 112 bytes.

Offset Field Type Meaning
0 in_mint Pubkey Mint the route spent.
32 out_mint Pubkey Mint the route received.
64 pair [u8; 32] Pair identifier from the signed route; one fill per pair per Crossing.
96 spent u64 Measured decrease of the input mint's shard 0.
104 got u64 Measured increase of the output mint's shard 0.

VerifiedMid#

One mid in CrossingState.mids, 64 bytes.

Offset Field Type Meaning
0 mint Pubkey Asset the price is for.
32 price i64 Pyth price, in units of 10^exponent.
40 confidence u64 Pyth confidence, in the same units.
48 publish_time i64 Pyth publish time, Unix seconds.
56 exponent i32 Pyth exponent.
60 valid u8 1 when the price is positive, published within max_price_age seconds (at most 1 second ahead) and its confidence is within κ; otherwise 0.

RegisteredKey#

One key slot of Registry.keys, 128 bytes.

Offset Field Type Meaning
0 signing_key Pubkey Ed25519 key pk_C that signs opens, consolidations, routes and Commits.
32 hpke_key [u8; 32] X25519 key ek_C that Intents and notes are sealed to.
64 release_key [u8; 32] ristretto255 key Y_E the Council re-encrypts the Ledger data key to.
96 epoch u64 Key epoch e.
104 valid_from u64 First slot the key signs in, e × E_key.
112 valid_until u64 First slot past its epoch, (e + 1) × E_key.
120 admitted u8 1 for an admitted key.
128 platform Pubkey The Platform account the key's quote came from. The Registry holds one key per platform and epoch.