Every instruction of privium_pool. Each one a user sends has a full entry: its accounts and arguments, every check in order with the error it raises, and what it writes, emits and measured. The instructions the Coprocessor, the Council and the admin send sit in one table per group.
Summary#
| Instruction | Group | Discriminator |
|---|---|---|
deposit |
Deposits and Intents | f223c68952e1f2b6 |
post_intent |
Deposits and Intents | 3d11421cdb457934 |
release_exit |
Exits | 233781d312431070 |
trigger_escape |
Escape | 4dbdc25868ae6da3 |
refund_deposit |
Escape | 13134e32bb0aa2e5 |
escape_request |
Escape | c0cd57de4fdbf7ea |
escape_claim |
Escape | 4dfb9a5eb4493af1 |
open_crossing |
Crossing | e323f053a4b93227 |
consolidate_vault |
Crossing | 70917df37e3ca743 |
route_residual |
Crossing | a8cfa0f7952f8971 |
log_diff |
Crossing | 710e0fab930a6c14 |
commit |
Crossing | df8c8ea5e5d09c4a |
initialize |
Configuration | afaf6d1f0d989bed |
set_admin |
Configuration | fba300345bc2bb5c |
set_admission_authority |
Configuration | b0d3b9f103d0f484 |
set_fee_recipient |
Configuration | e312d72aedf69742 |
set_fee_rate |
Configuration | 35f38941088c9e06 |
set_escape_window |
Configuration | 7ac74e3265cc8f9d |
create_shard |
Configuration | f4993a8bfa0022c0 |
admit_asset |
Configuration | a09b9d514720f211 |
reset_escape |
Configuration | 59d11a983267e2bd |
initialize_registry |
Attestation | bdb51411ae39f93b |
configure_verifier |
Attestation | fbbd11263036c567 |
admit_platform |
Attestation | 2030024c7b022d25 |
stage_enclave |
Attestation | 73c947e0f7e4aa2b |
verify_enclave_qe |
Attestation | 0ea7bf258ab3c4ea |
register_enclave |
Attestation | d4aefbeb34918da8 |
propose_measurement |
Attestation | a339177af5e5cbfb |
activate_measurement |
Attestation | 8249c6e1b2069176 |
initialize_council |
Council | b6f55a2430f048f7 |
council_log |
Council | f2293dc33a4610e0 |
rotate_council |
Council | 20a38e1131f89441 |
escape_share |
Council | e0b6f21340426ebd |
An instruction’s data is its 8-byte discriminator followed by its arguments in Borsh, in the order its entry lists them.
How to read an entry:
- Accounts are listed in the order the instruction takes them, with the flags the IDL sets. Remaining accounts follow them and are described under the instruction that takes any.
- Anchor checks the listed accounts before the handler runs: signers, owners, discriminators, seeds,
has_onerelations, fixed addresses, and the creation of each account marked as created. Those failures carry Anchor’s own codes (Errors). An account created byinitfails to create when it already exists, which is how the program refuses a second payment, a second request or a second trigger. - The handler’s checks run in the order listed. The first that fails ends the instruction with the error named, and the whole transaction reverts.
- A valid vault is a token account of the asset’s token program and mint, owned by the Pool authority, with no delegate and no close authority.
- Compute is the measured figure from Compute units.
Deposits and Intents#
deposit#
Moves a wallet’s tokens into one of an asset’s two vault shards and queues the amount for the next Commit to credit. The API builds a wallet’s deposit transaction (POST /v1/deposits/build), and the SDK sends it (deposit).
Signers: owner, the owner or delegate of source.
| # | Account | Flags | Address | Meaning |
|---|---|---|---|---|
| 0 | owner |
read, signer | Owner or delegate of source; authorizes the transfer. |
|
| 1 | ledger |
read | PDA: "ledger" |
LedgerRoot, read for an active Escape. |
| 2 | asset |
read | The mint's AssetState. | |
| 3 | queue |
writable | AssetState.queues[shard]. | |
| 4 | mint |
read | AssetState.mint. | |
| 5 | source |
writable | The token account the tokens leave, of the asset's mint. | |
| 6 | vault |
writable | AssetState.vaults[shard]. | |
| 7 | token_program |
read | AssetState.token_program. | |
| 8 | event_authority |
read | PDA: "__event_authority" |
PDA ["__event_authority"], the signer of the program's event CPI. |
| 9 | program |
read | privium_pool itself, the target of its event CPI. |
| Argument | Type | Meaning |
|---|---|---|
shard |
u8 |
Vault shard, 0 or 1. |
amount |
u64 |
Base units sent, above zero. The entry records what the vault received. |
note |
bytes |
The sealed deposit note, 48 to 1,024 bytes. Only its hash is stored. |
Remaining accounts: the accounts the mint’s transfer hook needs, appended to the transfer in order.
Checks:
amountis above zero andnoteis 48 to 1,024 bytes:NoteTooLong.- No Escape is active:
EscapeActive. shardis 0 or 1:Accounts.queueandvaultare the AssetState’s for that shard,mintandtoken_programare its own, andsourceholds its mint:Accounts.- Fewer than 512 of the shard’s entries wait to be credited:
QueueFull. transfer_checkedmovesamountfromsourcetovaultunderowner’s signature; a failure there is the token program’s own error. The credit is the vault’s balance after the transfer minus before:Mathif it fell.
Writes: the queue entry at head mod 512: the credited amount, the queue’s new cumulative amount, the slot, source, the note hash SHA256(privium/note/v1 ‖ note) and the new chain hash SHA256(previous ‖ amount ‖ slot ‖ note hash), amount and slot as u64 little endian. It clears that index’s refund bit and advances head. A mint with a transfer fee credits what the vault received. Emits: Deposited.
A deposit writes only its queue, its vault and the source, so deposits on different shards run in parallel. The note stays in the instruction data; the queue keeps only its hash. Another program can make the deposit through a cross-program call: the Coprocessor reads deposit from a transaction’s inner instructions as well as its top level (The deposit queue).
Compute: as measured in Compute units.
post_intent#
Carries a sealed Intent on chain: the sealed bytes ride in the instruction data (Intent).
Signers: payer, any key.
| # | Account | Flags | Address | Meaning |
|---|---|---|---|---|
| 0 | payer |
read, signer | Any fee payer. |
| Argument | Type | Meaning |
|---|---|---|
sealed |
bytes |
The HPKE-sealed Intent: 208 bytes for a trade, 4,144 for every other kind. |
Checks:
sealedis 208 or 4,144 bytes:Message.
Writes: nothing. Only the fee payer is writable, so post_intent transactions from different payers run in parallel.
Exits#
release_exit#
Pays an Exit that a Commit listed, from its release slot on. Anyone can send it; Privium’s keeper sends it for each Exit (GET /v1/exits/{crossing}/{index}).
Signers: payer.
| # | Account | Flags | Address | Meaning |
|---|---|---|---|---|
| 0 | payer |
writable, signer | Any fee payer; pays the PaidRecord's rent. For native SOL, receives the unwrapped lamports and sends exactly the amount to destination. |
|
| 1 | pool |
read | PDA: "pool" |
PoolConfig, read for the Pool authority. |
| 2 | ledger |
read | PDA: "ledger" |
LedgerRoot, read for the exits root ring. |
| 3 | asset |
writable | The mint's AssetState; its committed Exits fall by the amount. | |
| 4 | mint |
read | AssetState.mint. | |
| 5 | destination |
writable | The address the Exit leaf names. | |
| 6 | recipient |
writable | For native SOL, destination itself. Otherwise a token account of the mint owned by destination. |
|
| 7 | vault_0 |
writable | Vault shard 0, drawn after shard 1. | |
| 8 | vault_1 |
writable | Vault shard 1, drawn first. | |
| 9 | authority |
read | PDA: "authority" |
The Pool authority PDA; signs the payout. |
| 10 | token_program |
read | AssetState.token_program. | |
| 11 | record |
writable | PDA: "exit", argument args.origin_k, argument args.origin_index |
PaidRecord at ["exit", origin_k as u64 LE, origin_index as u32 LE], created; a second release of the Exit, under any exits root that lists it, finds it in use. |
| 12 | system_program |
read | 11111111111111111111111111111111 |
The System program: it creates record and carries the native SOL transfer to destination. |
| 13 | event_authority |
read | PDA: "__event_authority" |
PDA ["__event_authority"], the signer of the program's event CPI. |
| 14 | program |
read | privium_pool itself, the target of its event CPI. |
| Argument | Type | Meaning |
|---|---|---|
args |
ExitArgs |
The Exit leaf's fields and its path. |
ExitArgs
| Field | Type | Meaning |
|---|---|---|
k |
u64 |
Crossing whose exits root the path proves against. |
index |
u32 |
The Exit's index in that exits tree. |
origin_k |
u64 |
Crossing whose Commit first listed the Exit. With origin_index it addresses the PaidRecord, the same for every root that lists the Exit. |
origin_index |
u32 |
The Exit's index in that first exits tree. |
amount |
u64 |
Base units paid, above zero. |
release_slot |
u64 |
First slot the Exit pays in. |
path |
Vec of [u8; 32] |
Siblings to the exits root, bottom to top, at most 32. |
Remaining accounts: for native SOL, first a temporary token account: wrapped SOL, owned by the Pool authority, empty, and neither vault shard; it receives the payment and is closed to payer. The accounts the mint’s transfer hook needs follow it, or make up the whole list for any other mint.
Checks: record sits at the Exit’s origin, the same for every exits root that lists the Exit (Exit leaf), so a second release fails when record is created, before any check below.
- An exits root for
kis among the last 64 Commits’ and is not zero:Proof. mintis the AssetState’s:Accounts.- The current slot is at least
release_slot, andamountis above zero:NotReady. - The path has at most 32 siblings and leads from the Exit leaf to that root (Exit leaf):
Proof. - For native SOL,
recipientisdestination; otherwiserecipientis a token account of the mint, under the asset’s token program, owned bydestination:Accounts. mint,token_program,vault_0andvault_1are the AssetState’s; for native SOL, the temporary account qualifies:Accounts.- The payment comes from shard 1 first and shard 0 for the rest, each a valid vault (
Accounts), and the two cover it:Conservation. - The committed Exits fall by
amount:Math.
For native SOL, the temporary account is then closed to payer, which receives the unwrapped lamports and the account’s rent, and the program sends exactly amount lamports from payer to destination with a System transfer that payer signs. The destination receives the committed amount and nothing more; the rent stays with the payer.
Writes: record, paid; the AssetState’s committed Exits. Emits: ExitReleased.
Compute: as measured in Compute units.
Escape#
The program’s side of the Escape that users send: opening it, refunding uncredited deposits, and requesting and claiming a balance. Between a request and its claim, the Council posts its re-encryption shares with escape_share (Council). Privium’s relay submits requests and claims with its keeper paying (POST /v1/escape/relay).
trigger_escape#
Opens the Escape once no Commit has landed for W slots. Anyone can send it; Privium’s keeper sends it as soon as the window passes.
Signers: payer.
| # | Account | Flags | Address | Meaning |
|---|---|---|---|---|
| 0 | payer |
writable, signer | Any fee payer; pays EscapeState's rent. | |
| 1 | pool |
read | PDA: "pool" |
PoolConfig, read for W. |
| 2 | ledger |
writable | PDA: "ledger" |
LedgerRoot; its escape_from_slot is set. |
| 3 | council |
read | PDA: "council" |
CouncilConfig, read for its epoch. |
| 4 | crossing |
read | The address ["crossing", k + 1]: the open CrossingState, or the empty address when none was opened. |
|
| 5 | escape |
writable | PDA: "escape" |
EscapeState, created. |
| 6 | system_program |
read | 11111111111111111111111111111111 |
The System program, for the account created here. |
| 7 | event_authority |
read | PDA: "__event_authority" |
PDA ["__event_authority"], the signer of the program's event CPI. |
| 8 | program |
read | privium_pool itself, the target of its event CPI. |
Checks: a second trigger fails when escape is created.
- No Escape is active, and the current slot is past the last Commit’s slot plus W:
NotReady(Mathif that sum overflows a u64). crossingis["crossing", LedgerRoot.k + 1]:Accounts.- When that account belongs to the program, it is a CrossingState for that index with at most 8 fills:
Accounts. Its fills are copied.
Writes: EscapeState with the frozen root, the trigger slot, the last Commit’s slot, the last committed index, the Council epoch and the open Crossing’s fills; LedgerRoot.escape_from_slot. From here deposit, open_crossing, consolidate_vault, route_residual, commit and rotate_council fail with EscapeActive. Emits: EscapeTriggered.
Compute: as measured in Compute units.
refund_deposit#
Returns a deposit no Commit credited to the token account it came from. Anyone can send it while the Escape is active.
Signers: none beyond the fee payer.
| # | Account | Flags | Address | Meaning |
|---|---|---|---|---|
| 0 | pool |
read | PDA: "pool" |
PoolConfig, read for the Pool authority. |
| 1 | ledger |
read | PDA: "ledger" |
LedgerRoot, read for an active Escape. |
| 2 | asset |
read | The mint's AssetState. | |
| 3 | queue |
writable | The deposit queue holding the entry. | |
| 4 | vault_0 |
writable | Vault shard 0, drawn after shard 1. | |
| 5 | vault_1 |
writable | Vault shard 1, drawn first. | |
| 6 | source |
writable | The token account the entry records. | |
| 7 | mint |
read | AssetState.mint. | |
| 8 | authority |
read | PDA: "authority" |
The Pool authority PDA; signs the refund. |
| 9 | token_program |
read | AssetState.token_program. |
| Argument | Type | Meaning |
|---|---|---|
sequence |
u64 |
The entry's sequence in its queue. |
Remaining accounts: the accounts the mint’s transfer hook needs.
Checks:
- The Escape is active:
NotEscape. - The queue serves shard 0 or 1 and is the AssetState’s for that shard, the queue’s mint,
mintandtoken_programare the AssetState’s, andsequencelies from the credited cut to below the head, within the last 512 entries:Accounts. - The entry is not refunded yet:
AlreadyPaid. sourceis the token account the entry recorded:Accounts.vault_0andvault_1are the AssetState’s vault shards, each a valid vault:Accounts.- The refund comes from shard 1 first and shard 0 for the rest, whichever shard the deposit entered, and the two cover it:
Conservation.
Writes: the entry’s credited amount moves to source with transfer_checked, signed by the Pool authority; the entry’s refund bit is set. A refund draws on both shards, so an earlier payout that emptied the shard a deposit entered leaves the deposit refundable.
Compute: as measured in Compute units.
escape_request#
Opens a request for one balance leaf under the frozen root. Anyone holding the leaf’s escape public key and owner salt can open it; only the matching escape secret can claim it.
Signers: payer.
| # | Account | Flags | Address | Meaning |
|---|---|---|---|---|
| 0 | payer |
writable, signer | Any fee payer; pays the EscapeRequest's rent. | |
| 1 | ledger |
read | PDA: "ledger" |
LedgerRoot, read for an active Escape. |
| 2 | escape |
read | PDA: "escape" |
EscapeState, holding the frozen root and Council epoch. |
| 3 | council |
read | PDA: "council" |
CouncilConfig. |
| 4 | asset |
read | AssetState of the leaf's asset. | |
| 5 | mint |
read | AssetState.mint. | |
| 6 | request |
writable | PDA: "escape-req", argument args.leaf_index, mint |
EscapeRequest at ["escape-req", leaf_index as u32 LE, mint], created. |
| 7 | system_program |
read | 11111111111111111111111111111111 |
The System program, for the account created here. |
| Argument | Type | Meaning |
|---|---|---|
args |
EscapeRequestArgs |
The leaf, its index and path, and the owner's escape key and salt. |
EscapeRequestArgs
| Field | Type | Meaning |
|---|---|---|
leaf_index |
u32 |
The leaf's position in the Ledger tree. |
leaf |
bytes |
The 225-byte balance leaf. |
path |
Vec of [u8; 32] |
Exactly 32 siblings, bottom to top. |
owner_key |
[u8; 32] |
The owner's escape public key Y. |
salt |
[u8; 32] |
The owner salt behind the leaf's owner tag. |
The leaf bytes the program reads (Ledger):
| Bytes | Field |
|---|---|
| 0 | kind, 2 |
| 1..5 | asset index, u32 |
| 5..13 | version, u64 |
| 13..45 | owner tag |
| 45..77 | commitment |
| 77..109 | Council handle |
Checks: one request per leaf and mint: a second fails when request is created. escape exists only from the trigger on, so a request before it fails Anchor’s account check.
- The Escape is active:
NotEscape. - The leaf is 225 bytes of kind 2, and its path of exactly 32 siblings leads from SHA256(
0x00‖ leaf), with parents SHA256(0x01‖ left ‖ right) and bit ofleaf_indexchoosing the side at level , to the frozen root:Proof. mintis the AssetState’s, and the leaf’s asset index is its Ledger index:Accounts.- The owner tag is SHA256(
privium/owner/v1‖owner_key‖salt‖ mint ‖ version):Proof. owner_keyis a valid ristretto255 point and not zero, and the leaf’s commitment and handle are valid points:Proof.
Writes: the EscapeRequest with the leaf index, mint, owner key, commitment, handle and the Council epoch frozen at the trigger.
Compute: as measured in Compute units.
escape_claim#
Pays a combined request’s balance to the destination its claim proof names. The relayer pays the fee; the owner authorizes the payout through the proof, which binds the destination.
Signers: payer.
| # | Account | Flags | Address | Meaning |
|---|---|---|---|---|
| 0 | payer |
writable, signer | Any fee payer; pays the PaidRecord's rent. For native SOL, receives the unwrapped lamports and sends exactly the payout to destination. |
|
| 1 | pool |
read | PDA: "pool" |
PoolConfig, read for the Pool authority. |
| 2 | ledger |
read | PDA: "ledger" |
LedgerRoot, read for an active Escape. |
| 3 | escape |
read | PDA: "escape" |
EscapeState, holding the frozen fills. |
| 4 | request |
writable | The combined EscapeRequest; marked claimed. | |
| 5 | destination |
read | The address the claim proof binds; receives every payout. | |
| 6 | authority |
read | PDA: "authority" |
The Pool authority PDA; signs the payouts. |
| 7 | record |
writable | PDA: "escaped", request.leaf_index, request.mint |
PaidRecord at ["escaped", leaf_index as u32 LE, mint], created; a second claim finds it in use. |
| 8 | system_program |
read | 11111111111111111111111111111111 |
The System program: it creates record and carries a native SOL payout to destination. |
| 9 | event_authority |
read | PDA: "__event_authority" |
PDA ["__event_authority"], the signer of the program's event CPI. |
| 10 | program |
read | privium_pool itself, the target of its event CPI. |
| Argument | Type | Meaning |
|---|---|---|
amount |
u64 |
The balance b the proof opens, in base units of the request's mint. |
proof |
DleqProof |
Proof under the owner's escape key that the leaf decrypts to amount, bound to the program, the request, its mint and destination. |
DleqProof
| Field | Type | Meaning |
|---|---|---|
r1 |
[u8; 32] |
Commitment for Y = y·G. |
r2 |
[u8; 32] |
Commitment for Z = y·A. |
z |
[u8; 32] |
Response for y, a canonical scalar. |
Remaining accounts: seven per asset the claim pays, one group per mint, the groups in any order:
| # | Account |
|---|---|
| 0 | the asset’s AssetState |
| 1 | the mint |
| 2 | the recipient: destination itself for native SOL, otherwise its token account of the mint |
| 3 | vault shard 1 |
| 4 | vault shard 0 |
| 5 | the mint’s token program |
| 6 | for native SOL, a temporary wrapped SOL account as in release_exit; any account otherwise |
Checks: one claim per request: a second fails when record is created.
- The Escape is active:
NotEscape. - The request is combined and not claimed:
RequestState. - With , the proof shows and for one , under the challenge from SHA256(
privium/claim/v1‖ ‖ ‖ ‖ ‖ ‖ ‖ program id ‖ request ‖ mint ‖ destination) reduced to a scalar:ClaimProof, orProoffor an invalid point or a non-canonical response. - The remaining accounts come in sevens, with a group for the request’s mint:
Accounts. - With the mint’s Ledger total and what the frozen fills spent of it, plus what a consolidation of the mint lost to its transfer fee in the open Crossing,
amountis at most , is above zero, and is at most :Conservation. - For each payout above zero, the mint’s group holds its AssetState and token program, and the recipient passes the same checks as in
release_exit:Accounts. Each is paid from shard 1 first and shard 0 for the rest:Conservationif they fall short. A native SOL payout unwraps topayer, which sends exactly the payout todestination, as inrelease_exit.
The payouts follow the settlement rule (Escape): of the request’s mint, and for each frozen fill out of that mint, of the fill’s output mint, summed per mint.
Writes: the request, claimed; record, paid. Emits: EscapeClaimed.
Compute: as measured in Compute units.
Crossing#
One Crossing on chain is a run of transactions the Coprocessor’s relayer sends: open_crossing, any consolidate_vault and route_residual it needs, the log_diff chunks, then commit. Every one but log_diff is checked against an enclave’s Ed25519 signature in the instruction before it (Signature verification), over the message laid out in Signed messages; when that instruction or its key does not pass, it fails MissingSig, BadSigLayout, UnknownEnclave or KeyExpired. The opener is the key that opened the Crossing, under its key epoch. Crossing tells the whole cycle.
| Instruction | Signed by | Checks and changes | In full |
|---|---|---|---|
open_crossing |
relayer; the enclave key's Ed25519 signature in the instruction before |
Requires no active Escape (EscapeActive), k = LedgerRoot.k + 1 at least Δ slots after the last Commit (OutOfOrder), the Open message for the key's epoch, k and relayer (Message), and one AssetState and Pyth price account per mid, at most eight (Accounts), each price account the Pyth push oracle's sponsored account for the asset's oracle_feed at shard 0, owned by the Pyth receiver, a fully verified PriceUpdateV2 on that feed (Price), whose price inputs hash to the signed value (MidsMismatch). Records each mid with the validity the program computes, the opener, the relayer and the lease, and seeds the accumulator. A reopen requires the lease passed or the opener's key no longer current in the Registry (NotOpener) and the recorded mids (MidsMismatch), and keeps the mids, fills and accumulator. Emits CrossingOpened. |
Crossing |
consolidate_vault |
any fee payer; the opener's Ed25519 signature in the instruction before | Requires no active Escape (EscapeActive), the open Crossing (OutOfOrder), its opener within the lease (NotOpener), no earlier consolidation of the mint in this Crossing (ConsolidationReplay) and fewer than eight in it (RouteCap), the Consolidate message for that epoch, Crossing and mint with an amount above zero (Message), the asset's vault shards (Accounts) and an amount at most its Ledger total (RouteCap). Moves the amount from vault shard 1 to shard 0, signed by the Pool authority, then requires shard 1 to have fallen by exactly the amount and shard 0 to have risen by no more (Conservation), and the Crossing's routed spend of the mint plus the difference within its Ledger total (RouteCap). Records the difference, the transfer fee the move lost, with the Crossing in AssetState, and the mint in CrossingState; emits VaultConsolidated. |
Pool |
route_residual |
any fee payer; the opener's Ed25519 signature in the instruction before | Requires no active Escape (EscapeActive), the Route message (Message) for the open Crossing (OutOfOrder) under its opener within the lease (NotOpener) before the deadline slot (ResidualExpired), the two mints' shard 0 vaults (Accounts), fewer than eight fills and none for the pair (RouteCap), valid mids for both mints (Price) and the route hash over Jupiter's program id, the data and the remaining account keys (RouteMismatch). Invokes Jupiter as the Pool authority, then requires the measured spend at most the signed input and the measured receipt at least the signed minimum (Slippage), and the Crossing's spend of the input mint, with what a consolidation of it lost in this Crossing, within its Ledger total (RouteCap). Records the fill; emits ResidualRouted. |
Residual |
log_diff |
relayer |
Requires CrossingState.relayer as signer (Anchor's has_one), a Crossing not committed, index equal to the next chunk and 1 to 3,800 bytes (DaMismatch). Advances the accumulator to SHA256(previous ‖ index ‖ chunk); the chunk stays in instruction data. |
Ledger |
commit |
relayer; the opener's Ed25519 signature in the instruction before |
Requires the Commit message with at most 8 asset entries, none for a heartbeat (Message, Accounts), no active Escape (EscapeActive), k = LedgerRoot.k + 1 under the key's epoch (OutOfOrder), the stored prior root (StaleRoot), the opener within the lease (NotOpener), the recorded mids, fills and accumulator after at least one chunk (MidsMismatch, FillsMismatch, DaMismatch), eight accounts per entry, each mint once (Accounts), cuts inside each queue (Cut), each asset's vault identity (Conservation) with valid commitment points and a canonical opening (Proof), every recorded fill's mints and every consolidated mint among the entries (Accounts), the commitment equation (Conservation) and the deposits digest (DepositsMismatch). Pays the fees, credits the cuts, stores the root, accumulator, mids hash and exits root, closes the CrossingState to relayer, which signs and receives its rent, and emits Committed. |
Commit |
commit#
Each asset entry of the Commit message takes eight remaining accounts, in message order: the asset’s AssetState, the mint, vault shard 0, vault shard 1, shard 0’s and shard 1’s deposit queues, the fee recipient’s associated token account for the mint, and the mint’s token program. For an entry whose fee is above zero, transfer_checked moves exactly that amount from vault shard 0 to that token account, signed by the Pool authority, before the vaults are read for the conservation check. The token account is the one the program derives from PoolConfig.fee_recipient, the token program and the mint (Accounts otherwise), and it must exist when commit pays into it. The Commit transaction therefore opens with one Associated Token Account CreateIdempotent instruction per asset entry, for the fee recipient PoolConfig names at that moment, ahead of the Ed25519 instruction and commit; for an account that exists already it does nothing, and a new fee recipient’s accounts exist from its first Commit on. Fees and $PRV follows the fees from there.
Every mint consolidate_vault moved in the Crossing must be among the asset entries (Accounts), so the Commit’s conservation check covers both of its shards.
A heartbeat Commit, which the Coprocessor sends when nothing has settled for 750 slots, has no asset entry and no remaining account, and its transaction creates no token account. The program runs the same order, root, opener, mids, fills and data availability checks, finds no asset to conserve, stores the new root and its slot, and seals the Crossing (The batch).
Configuration#
PoolConfig.admin signs every instruction here but initialize, which the program’s upgrade authority signs and which makes that key the admin and the admission authority. create_shard and admit_asset take either the admin or PoolConfig.admission_authority. None of them moves tokens. The admin lists what the admin can change and what stays fixed.
| Instruction | Signed by | Checks and changes | In full |
|---|---|---|---|
initialize |
payer, admin |
Requires admin to be the upgrade authority the program's ProgramData records (Unauthorized), Δ = 4, a price age of 75 seconds, κ = 25 and β₀ = 50 basis points, W and the lease above zero, and φ at most 10,000 basis points (Configuration). Creates PoolConfig with admin as both the admin and the admission authority, and LedgerRoot with the empty root. Runs once. |
The admin |
set_admin |
admin |
Requires a key other than the default (Configuration). Writes PoolConfig.admin: from then on that key signs every admin instruction, set_admin included, and the key it replaces signs none. |
The admin |
set_admission_authority |
admin |
Requires a key other than the default (Configuration). Writes PoolConfig.admission_authority, the one key besides the admin that can sign create_shard and admit_asset. |
The admission authority |
set_fee_recipient |
admin |
Requires a key other than the default (Configuration). Writes PoolConfig.fee_recipient; from the next Commit on, fees go to that wallet's associated token accounts. |
Fees and $PRV |
set_fee_rate |
admin |
Requires bps at most 10,000 (Configuration). Writes PoolConfig.fee_rate_bps; each Commit pays the fee amounts its signed message states. |
Fees |
set_escape_window |
admin |
Requires slots above zero (Configuration). Writes PoolConfig.escape_window_slots, which trigger_escape and propose_measurement read. |
Escape |
create_shard |
payer, admin; admin is the admin or the admission authority |
Requires admin to be PoolConfig.admin or PoolConfig.admission_authority (Unauthorized). Creates a mint's vault shard 1 at ["vault", mint, 1]: a token account of the mint's token program, owned by the Pool authority and sized for the extensions the mint requires on its accounts. A second call finds the address in use. |
Pool |
admit_asset |
payer, admin; admin is the admin or the admission authority |
Requires admin to be PoolConfig.admin or PoolConfig.admission_authority (Unauthorized), the mint owned by token_program, vault shard 0 at the Pool authority's associated token account and shard 1 at ["vault", mint, 1], each of the mint, owned by the Pool authority, with no delegate and no close authority, and two distinct zeroed queues (Accounts). Accepts TransferFeeConfig, TransferHook with the hook program the arguments name, MintCloseAuthority, and the confidential transfer, interest-bearing, metadata and group extensions; any other extension fails (Extension). Creates AssetState, once per mint, and binds both queues to it. |
Pool |
reset_escape |
admin |
Requires admin to be PoolConfig.admin and an active Escape at k = 0, before any Commit (NotReady): the frozen root is empty and no Ledger balance exists to claim. Clears LedgerRoot.escape_from_slot, sets last_commit_slot to the current slot, so the liveness window restarts there, and closes EscapeState to the admin. |
The admin |
Attestation#
How an enclave key enters the Registry: a platform once per processor and collateral period, with the admin’s signature, then each key epoch in three stages. And how a new measurement enters it: proposed by the upgrade authority, activated by anyone two escape windows later. Attestation and reproducible builds explains what each check establishes.
| Instruction | Signed by | Checks and changes | In full |
|---|---|---|---|
initialize_registry |
payer, admin |
Requires E_key above zero and one to eight measurements (Configuration). Creates the Registry with the development gate, E_key and those measurements, and an unconfigured VerifierConfig. Runs once; no instruction changes the gate or E_key afterwards. |
Attestation |
configure_verifier |
admin |
Requires three ic points, a nonzero Intel root hash and guest identity, and a verifier not configured yet (Configuration). Writes the SP1 Groth16 verifying key, the guest identity and the root hash into VerifierConfig, once. |
Reproducing the builds |
admit_platform |
payer, admin; admin is the admin, on both paths |
Requires admin to be PoolConfig.admin (Anchor's has_one) on every admission and renewal, pck_hash to be SHA256 of pck, TCB status UpToDate, collateral unexpired and a compressed PCK (Platform). Then either a 256-byte Groth16 proof that verifies under VerifierConfig, with the configured guest identity and SHA256 of the journal the program rebuilds from the configured values and the arguments as public inputs (Configuration before configure_verifier, Proof), or, with dev, a Registry initialized with the development gate open (Unauthorized). Creates the Platform, once per PCK. On an existing Platform the same checks renew it: the PCK, the verifier and the development classification must match the record, the expiry must be later (PlatformRenewal), and the expiry, FMSPC, TCB and QE fields are rewritten. |
Attestation |
stage_enclave |
payer |
Requires an unexpired Platform (Platform), a valid ristretto255 release key (Proof), no zero key (Configuration), an anchor slot among the 512 SlotHashes holds (ReportData) and the current or the next key epoch (KeyExpired). Creates the EnclaveKey at stage 0 with the three keys, the platform, the interval from e × E_key to (e + 1) × E_key and the report data its quote must carry. Any fee payer can stage; the record's address is the signing key's. |
Attestation |
verify_enclave_qe |
any fee payer; the PCK's secp256r1 signature in the instruction before | Requires stage 0 (Stage), a secp256r1 instruction of the fixed shape (MissingSig, BadSigLayout) whose key is the unexpired Platform's PCK (Platform), over a 384-byte QE report (QuoteFormat) with the Platform's MRSIGNER and ISVPRODID and at least its ISVSVN (Platform) and report data ending in 32 zero bytes (ReportData). Records the attestation key's hash; stage 1. |
Attestation |
register_enclave |
any fee payer; the attestation key's secp256r1 signature in the instruction before | Requires stage 1 on an unexpired Platform (Stage), a secp256r1 instruction of the fixed shape (MissingSig, BadSigLayout) over a 632-byte TDX quote, version 4, with an ECDSA P-256 key (QuoteFormat) that is the key the QE report certified (AkEncoding, AkBinding), TEE TCB SVN at the Platform's floor (Platform), DEBUG clear (DebugTd), owner fields and RTMR3 zero (OwnerFields), a measurement the Registry admits (Measurement), the staged report data (ReportData) and the current or the next key epoch (KeyExpired). Clears the platform's keys of earlier epochs whose interval has ended, then enters the keys in the slot the platform holds for that epoch, superseding the key there, or else in a free slot or one whose interval has ended (Configuration when none is); stage 2; emits EnclaveAdmitted. |
Attestation |
propose_measurement |
payer, authority |
Requires authority to be the upgrade authority the program's ProgramData records now (Unauthorized), three nonzero digests (Configuration) and a measurement the Registry does not admit (MeasurementExists). Creates the 153-byte MeasurementProposal with the digests and an activation slot of the current slot plus twice W; emits MeasurementProposed. Each measurement is proposed once. |
Attestation |
activate_measurement |
any fee payer | Requires a proposal not activated (MeasurementExists), its activation slot reached (MeasurementPending), a measurement the Registry does not admit yet (MeasurementExists) and fewer than eight in it (Configuration). Appends the measurement to the Registry and marks the proposal activated; admitted keys, their intervals and the earlier measurements stay as they are. Emits MeasurementActivated. |
Attestation |
Council#
The Council’s account, its public transcript, its move to a new epoch, and its part in the Escape: one re-encryption share per member for each request (Council).
| Instruction | Signed by | Checks and changes | In full |
|---|---|---|---|
initialize_council |
payer, admin |
Requires n from 1 to 9 with one signer key each and 2t greater than n (Configuration), a valid nonzero Council key (Proof, Configuration), valid nonzero verification keys and distinct signer keys (Proof, Configuration), and verification keys that form one t-of-n sharing: the first t interpolate to H at zero and each later key equals their interpolation at its member number (Proof). Creates CouncilConfig, once. |
Council |
council_log |
payer |
Requires a payload of at most 2,048 bytes (Configuration). Writes nothing; emits CouncilTranscript with the signer and the payload, and lists the transaction under the Council's address ["council"], before CouncilConfig exists and after. |
The Council |
rotate_council |
any fee payer; at least t of the current members' signer keys, as remaining accounts | Requires no active Escape (EscapeActive), the next Council epoch with the same Council key (Configuration), and at least t of the current members' signer keys signing among the remaining accounts (Unauthorized); the new members, t and keys pass the checks of initialize_council. Rewrites CouncilConfig with the new epoch, n, t, verification keys and signer keys. |
Council |
escape_share |
any fee payer; the share's proof, not a signature, authenticates the member | Requires the request's Council epoch to be the Council's and the trigger's, a request neither combined nor claimed, and a member from 1 to n who has not posted (RequestState), then the member's re-encryption proof against its verification key (Share, or Proof for an invalid point or a non-canonical response). Records the share; the share that brings the count to t combines the posted shares with their Lagrange weights. |
The Council |