• Reading the docs…
Start trading

SDK

Type reference

Every function, class, constant and type @privium/sdk exports, by entry point, and the decrypted plaintext types its calls return. Each table here is generated from the declarations of the shipped tarball, the contract it bundles included.

Entry points#

Import Holds
@privium/sdk The account class Privium, its call types and errors, the viewing, Receipt, history, Escape, chain-anchor, nonce and funding helpers, and everything in ./wire and ./crypto.
@privium/sdk/wire Byte encodings: integers, base58 and base64, the trade and extended Intent layouts, the balance leaf, the Crossing diff and the wire Reader.
@privium/sdk/crypto Key derivation from the one signature, Ed25519, HPKE, AES-GCM, Pedersen commitments, Merkle paths and the data availability accumulator.
@privium/sdk/fixtures Public test keys and a test wallet for a local API in fixture mode.
@privium/sdk/program The Anchor IDL of privium_pool as a typed constant.
@privium/sdk/contract The contract the SDK bundles: the API client, the zod schemas of every route and decrypted type, the encodings and the error envelope.
@privium/sdk/contract/fixtures The contract's fixture scenarios and sample data, for a local API in fixture mode.

Every entry point is an ES module. The package root re-exports ./wire and ./crypto in full, so their exports import from either path. ./contract and ./contract/fixtures re-export the bundled contract, @privium/contract and its fixtures, whole.

@privium/sdk#

Export Signature Meaning
receipts receipts: { verify: typeof verifyReceipt } Receipt verification with no account: receipts.verify is verifyReceipt.
Wallet type Wallet The wallet adapter connect takes: a base58 public key, raw message signing and optional transaction signing.
Balance type Balance One verified balance: the asset, the amount and its opening, the decoded leaf and its position, with the snapshot's Crossing.
Balances type Balances A verified balance snapshot: the account's balances with the root, Crossing and slot they were checked against.
ConnectOptions type ConnectOptions What Privium.connect takes: the API's URL, the wallet and optional transport settings.
PrivateResult type PrivateResult = PrivateEvent A decrypted enclave reply: an order result, the account status, a signed Receipt, a registration, an Exit state or an Escape request.
ExitUpdate type ExitUpdate = Extract<PrivateResult, { kind: 'exit' }> One Exit piece's state: the exit kind of PrivateResult, as an exit's replies and watchExits carry it.
WatchExitsOptions type WatchExitsOptions What watchExits takes: an abort signal and the poll interval.
Submission type Submission A sealed Intent and its delivery: the nonce, the sealed bytes, whether intake accepted it and the decrypted replies.
ExitSubmission type ExitSubmission What exit returns: a Submission for each denominated piece, with the amount they carry and the remainder.
DEFAULT_MAX_SLIPPAGE_BPS DEFAULT_MAX_SLIPPAGE_BPS = 300, MAX_SLIPPAGE_BPS = 1000 300: the maximum slippage, in basis points, a market order takes when trade is given no maxSlippageBps.
SdkError class SdkError The error every SDK check throws, with a stable code and the stage that failed.
toBaseUnits toBaseUnits(value: string, decimals: number): bigint A decimal amount string as integer base units at an asset's decimals, exactly.
priceToUnits priceToUnits(value: string, exponent: number): bigint A decimal price string as the integer count of 10^exponent quote whole tokens per base whole token, exactly.
fromBaseUnits fromBaseUnits(amount: bigint, decimals: number): string Integer base units as a decimal string at an asset's decimals, trailing zeros dropped.
estimateFee estimateFee(quoteAmount: bigint, feeBps?: number | null): bigint The fee on a quote amount at feeBps basis points, rounded down to whole quote units.
Privium class Privium A connected account: its keys, the API client and every account call.
@privium/sdk/wire export * from '@privium/sdk/wire' Every export of @privium/sdk/wire, also importable from the package root.
@privium/sdk/crypto export * from '@privium/sdk/crypto' Every export of @privium/sdk/crypto, also importable from the package root.
VIEW_DEPTH VIEW_DEPTH = 40 Depth of each asset's period tree: 40 levels, one leaf per Crossing.
ViewingNode interface ViewingNode One node of a period tree: its prefix, depth and key.
ViewingScope type ViewingScope What a viewing bundle opens: the whole account, one asset, one asset over a span of Crossings, or one entry.
CrossingRange interface CrossingRange One inclusive span of Crossings that a version 2 viewing bundle lists.
ViewingBundle interface ViewingBundle The keys that open one scope of an account's history, with the program and owner they belong to.
deriveNode deriveNode(root: Uint8Array, prefix: bigint, depth: number): Uint8Array The period tree node at prefix and depth below a root key.
epochKey epochKey(root: Uint8Array, crossing: bigint): Uint8Array One Crossing's epoch key: the depth-40 node at that Crossing's index.
entryKey entryKey(epoch: Uint8Array, entry: number): Uint8Array One entry's key, from its epoch key and its index.
coveringNodes coveringNodes(root: Uint8Array, from: bigint, to: bigint): ViewingNode[] The fewest period tree nodes that cover exactly Crossings from to to, inclusive.
createViewingBundle createViewingBundle(programId: string, ownerIdHash: Uint8Array, viewRoot: Uint8Array, scope: ViewingScope, rootVersion?: number, crossingRanges?: CrossingRange[]): ViewingBundle A viewing bundle for a scope under a viewing root: version 2 with the Crossing ranges given, version 1 without. disclose calls it with the account's keys.
compressCrossings compressCrossings(crossings: bigint[]): CrossingRange[] Sorts Crossings, drops repeats and joins consecutive ones into the ranges a version 2 bundle carries.
encodeViewingBundle encodeViewingBundle(b: ViewingBundle): Uint8Array A bundle's wire bytes: PVV2 with its Crossing ranges, PVV1 without.
decodeViewingBundle decodeViewingBundle(data: Uint8Array): ViewingBundle Decodes PVV1 or PVV2 bundle bytes and checks that the nodes cover exactly the scope and the ranges sit inside it.
EncryptedEntry interface EncryptedEntry One encrypted history entry as a Crossing diff carries it.
entryAssociatedData entryAssociatedData(programId: string, e: EncryptedEntry): Uint8Array The associated data that binds an entry's ciphertext to its program, mint, Crossing, index, owner and root version.
keyFromBundle keyFromBundle(b: ViewingBundle, e: EncryptedEntry): Uint8Array An entry's key from a bundle; throws OUT_OF_SCOPE when the bundle does not cover the entry, or a version 2 bundle lists no range holding its Crossing.
readViewingEntry readViewingEntry(bundle: ViewingBundle, entry: EncryptedEntry): Promise<Uint8Array> Decrypts one entry with a bundle's keys and returns its plaintext bytes.
encryptEntry encryptEntry(programId: string, root: Uint8Array, e: Omit<EncryptedEntry, 'ciphertext'>, plaintext: Uint8Array): Promise<EncryptedEntry> Encrypts one entry under its key below a viewing root.
encodeEntry encodeEntry(e: EncryptedEntry): Uint8Array An entry's wire bytes.
decodeEntry decodeEntry(data: Uint8Array): EncryptedEntry Decodes an entry's wire bytes.
viewingLink viewingLink(bundle: ViewingBundle, origin: string): string The /v link of a bundle: the origin, /v and the bundle bytes in base64url in the fragment.
viewingFromFragment viewingFromFragment(fragment: string): ViewingBundle The bundle in a /v link's fragment, with or without its leading #.
ReceiptClaim type ReceiptClaim One claim as a signed Receipt states it: realized PnL, return, volume, fills, fees, ending equity or the assets traded.
ReceiptBody interface ReceiptBody The signed part of a Receipt.
Receipt interface Receipt A Receipt: its body and the enclave's signature.
encodeClaim encodeClaim(c: ReceiptClaim): Uint8Array One signed claim's bytes, as a Receipt body carries them; throws when a paired claim sets both or neither of exact and atLeast.
encodeReceiptBody encodeReceiptBody(r: ReceiptBody): Uint8Array A Receipt body's Borsh bytes.
receiptSigningBytes receiptSigningBytes(r: ReceiptBody): Uint8Array The message the enclave signs: privium/receipt/v1 and the encoded body.
signReceipt signReceipt(body: ReceiptBody, enclaveSeed: Uint8Array): Receipt Signs a Receipt body with an Ed25519 seed.
encodeReceipt encodeReceipt(r: Receipt): Uint8Array A Receipt's wire bytes: the length-prefixed body, then the 64-byte signature.
decodeReceipt decodeReceipt(data: Uint8Array): Receipt Decodes Receipt bytes and re-encodes them, throwing on any malformed or trailing byte.
receiptPseudonym receiptPseudonym(viewRoot: Uint8Array, label: string): Uint8Array The pseudonym a label gives under a viewing root.
receiptHolderSeed receiptHolderSeed(viewRoot: Uint8Array, label: string): Uint8Array The Ed25519 seed of the holder key a label gives under a viewing root.
ReceiptVerification type ReceiptVerification The outcome of verifying a Receipt: verified with the decoded Receipt, or the check that failed with its reason.
ReceiptPublicData interface ReceiptPublicData The two public records Receipt verification reads: an enclave key's registration and a committed root.
verifyReceipt verifyReceipt(value: Receipt | Uint8Array | string, data: ReceiptPublicData): Promise<ReceiptVerification> Verifies a Receipt from public records alone and returns its state.
receiptLink receiptLink(receipt: Receipt, origin: string): string The /r link of a Receipt: the origin, /r and the Receipt bytes in base64url in the fragment.
ReceiptRequestClaim type ReceiptRequestClaim One claim a Receipt request names: its kind, and its form, exact or atLeast with a threshold.
ReceiptRequest interface ReceiptRequest What receipt asks the enclave to sign: a span, claims, a label, the quote asset and the cost basis.
encodeRequestClaim encodeRequestClaim(c: ReceiptRequestClaim): Uint8Array One request claim's bytes: its kind's tag, then an option holding the threshold (none for an exact claim), nothing for fees, or the mint-list flag for assets.
encodeReceiptRequest encodeReceiptRequest(r: ReceiptRequest): Uint8Array A Receipt request's bytes, the payload of a receipt Intent.
decodeReceiptRequest decodeReceiptRequest(b: Uint8Array): ReceiptRequest Decodes a Receipt request.
receiptPublicData receiptPublicData(api: PriviumApi | string, options?: { programId: string; fixture?: boolean }): Promise<ReceiptPublicData> The ReceiptPublicData over an API that pins each record to the chain: an enclave record to its EnclaveKey account, a root to its Commit transaction.
readBundle readBundle(bundle: ViewingBundle, api: PriviumApi | string, cursor?: string, range?: { fromCrossing?: bigint; toCrossing?: bigint }): Promise<{ entries: Uint8Array[]; cursor: string; hasMore: boolean }> Reads one page of Ledger diffs from a cursor on, within the bundle's scope and an optional Crossing range (for a version 2 bundle, only the Crossings it lists), pins each to its Commit on chain and returns the entries the bundle opens.
HistoryEntry type HistoryEntry One decrypted history entry: a deposit, a fill, an Exit or a fee. The contract's HistoryEntry.
HistoryFilter interface HistoryFilter Which entries readHistory keeps: by asset, kind, Crossing span and dates.
filterHistory filterHistory(entries: HistoryEntry[], filter?: HistoryFilter): HistoryEntry[] The entries a filter keeps.
decodeHistory decodeHistory(entries: Uint8Array[]): HistoryEntry[] Parses decrypted entry bytes as history entries with the contract's schema.
historyCsv historyCsv(entries: HistoryEntry[]): string History entries as CSV, one row per entry.
readHistory readHistory(bundle: ViewingBundle, api: PriviumApi | string, cursor?: string, filter?: HistoryFilter): Promise<{ entries: HistoryEntry[]; cursor: string; hasMore: boolean }> Reads one page of the history a viewing bundle opens, from a cursor on and over the filter's Crossing span, and returns the typed entries the filter keeps.
EscapeClaimProof type EscapeClaimProof The proof that authorizes an Escape claim: r1, r2 and z.
programAddress programAddress(programId: string, seeds: Uint8Array[]): string The program address of seeds under a program, as Solana derives it: the first bump from 255 down whose hash is off the curve.
escapeRequestAddress escapeRequestAddress(programId: string, index: number, mint: string): string The EscapeRequest account address of a leaf position and mint: seeds escape-req, the position as a little-endian u32, and the mint.
EscapeClaimAccount interface EscapeClaimAccount The fields of an EscapeRequest account a claim reads.
decodeEscapeClaimAccount decodeEscapeClaimAccount(bytes: Uint8Array): EscapeClaimAccount Decodes the 800 bytes of an EscapeRequest account, its discriminator checked.
createEscapeClaimProof createEscapeClaimProof(input: { … }, randomness?: Uint8Array): EscapeClaimProof The claim proof for an amount and a destination, made with the account's escape key against a combined request.
verifyChainRoot verifyChainRoot(api: PriviumApi, anchor: Awaited<ReturnType<PriviumApi['root']>>, fixture?: boolean): Promise<void> Pins a Root record to its Commit: reads the transaction through the RPC relay and checks the signed commit it holds.
verifyEnclaveRegistration verifyEnclaveRegistration(api: PriviumApi, programId: string, enclave: Awaited<ReturnType<PriviumApi['enclave']>>, fixture?: boolean): Promise<void> Checks an enclave record against its EnclaveKey account, read through the RPC relay.
readLedgerRoot readLedgerRoot(api: PriviumApi, programId: string): Promise<{ root: string; crossing: string; slot: string; escape: boolean }> Reads the program's LedgerRoot account through the RPC relay: the committed root, its Crossing and slot, and whether the Escape is active.
verifyActiveEnclave verifyActiveEnclave(api: PriviumApi, programId: string, enclave: Awaited<ReturnType<PriviumApi['enclave']>>, fixture?: boolean): Promise<void> Checks that an enclave key holds a live slot of the program's Registry account, read through the RPC relay, before new secrets are sealed to it.
NONCE_COUNTER_BITS NONCE_COUNTER_BITS = 20 Random low bits in every nonce: 20.
nonceAt nonceAt(milliseconds: number, counter: number): bigint The nonce for a Unix time in milliseconds and a 20-bit counter.
nextNonce nextNonce(minimum?: bigint): bigint The process's next nonce: above the last it issued, above minimum, and at least the current time's.
FundingOrder interface FundingOrder An order's terms as fundingReservation reads them.
fundingReservation fundingReservation(order: FundingOrder): bigint What an order reserves: its base size for a sell; size × limit × (1 + fee) in quote units, rounded up, for a buy.
unreservedBalance unreservedBalance(balance: bigint, orders: readonly FundingOrder[]): bigint A balance less the reservations of the orders that draw on it.
PRIVIUM_POOL_IDL PRIVIUM_POOL_IDL: { … } The Anchor IDL of privium_pool: its address, instructions, accounts, events, errors and types.
PriviumPoolIdl type PriviumPoolIdl = typeof PRIVIUM_POOL_IDL The type of PRIVIUM_POOL_IDL.
DEFAULT_FEE_BPS DEFAULT_FEE_BPS = 10 φ in basis points that a config's feeBps takes when it names none.
MAX_PRICE_AGE_MS MAX_PRICE_AGE_MS = 75000 The oldest a Pyth price may be, in milliseconds, for a Crossing to clear at it and for a market order; the config serves it as maxPriceAgeMs.
PRV_TOKEN PRV_TOKEN: Readonly<{ … }> The $PRV mint as read on chain: name, symbol, mint, decimals, total supply in base units, both authorities revoked and metadata immutable (Fees and $PRV).

Privium#

Member Signature Meaning
keys keys: AccountKeys The account's derived keys, secret halves included, held in memory only.
config config: Config The API's configuration, read at connect: program, parameters and the active enclave key.
api api: PriviumApi The contract client for the API, with the URL, fetch and scenario connect was given.
account account: { id: string; authPublicKey: Uint8Array } The account's display id and its auth public key.
receipts receipts: { … } Receipt verification against publicData, or against receiptPublicData over this API when none was given.
connect Privium.connect(options: ConnectOptions): Promise<Privium> Signs the account message with the wallet, verifies the signature and derives the account.
decodeEnvelope decodeEnvelope(envelope: string): Promise<PrivateResult> Opens one sealed reply under the account's reply key and returns it; an order result also enters the instance's order tracking.
trade trade(input: { … }): Promise<Submission> Builds, signs, seals and submits a market or limit order.
openOrders openOrders(range?: { from: bigint; to: bigint; asset?: string }): Promise<AccountStatus> Reads the account's status from the enclave: open orders, pending Exit pieces, the nonce watermark, the leaf positions and the entry Crossings of a history range.
pendingExits pendingExits(): Promise<PendingExit[]> The Exit pieces of a fresh status read.
cancel cancel(orderNonce: bigint, expirySlot?: bigint): Promise<Submission> Seals a cancel Intent that burns a resting order's nonce.
exit exit(input: { … }): Promise<ExitSubmission> Splits an amount into denominations and seals one exit Intent per piece, to an address or a Ring deposit.
previewExit previewExit(amount: bigint, denominationUnit: bigint): { pieces: bigint[]; remainder: bigint; meanDelaySlots: number } Splits an amount into denominations as an Exit does, with the mean delay.
deposit deposit(input: { asset: string; amount: string }): Promise<{ … }> Builds a deposit with a sealed note and hands it to the wallet.
disclose disclose(scope: ViewingScope): Promise<{ bundle: ViewingBundle; link: string }> Builds a viewing bundle for a scope, with the scope's entry Crossings the enclave lists and its /v link.
receipt receipt(request: ReceiptRequest): Promise<{ submission: Submission; receipt?: Receipt; link?: string }> Asks the enclave for a signed Receipt and returns it with its /r link.
readBalances readBalances(): Promise<Balances> Reads the account's current balances: its leaf positions from the enclave's status, those leaves with their paths from the API, each checked against the LedgerRoot account on chain.
lastKnownBalances lastKnownBalances(): Balances | undefined The last balance snapshot the instance verified, marked stale; undefined before the first.
recoverBalancesFromHistory recoverBalancesFromHistory(): Promise<Balances> Rebuilds the account's balances from the public diffs up to the root on chain, for an Escape on a device that holds no snapshot at the frozen root.
watchEvents watchEvents(signal?: AbortSignal, cursor?: string): AsyncGenerator<LiveEvent> Streams the API's live events.
watchFills watchFills(signal?: AbortSignal, cursor?: string): AsyncGenerator<PrivateResult> Streams this account's decrypted order results from the live events, each newer than the state the instance holds for its order.
watchExits watchExits(options?: WatchExitsOptions): AsyncGenerator<ExitUpdate> Follows the account's Exit pieces from scheduled through committed to released.
requestEscape requestEscape(input: { asset: string }): Promise<EscapeSubmission> Opens an Escape request for the account's frozen balance in one asset, through the keeper-paid relay.
claimEscape claimEscape(input: { request: string; destination: string }): Promise<EscapeSubmission> Proves and claims a combined Escape request's balance to a destination, through the keeper-paid relay.
watchEscape watchEscape(request: string, options?: { signal?: AbortSignal; pollIntervalMs?: number }): AsyncGenerator<EscapeRequest, void, unknown> Follows an Escape request through the Council's shares to its payment.
readHistory readHistory(filter?: HistoryFilter, cursor?: string): Promise<{ entries: HistoryEntry[]; cursor: string; hasMore: boolean }> Reads one page of the account's own history from a cursor on, over the filter's Crossing span: only the Crossings the enclave lists as holding the account's entries, decrypted and filtered.
readBundle readBundle(bundle: ViewingBundle, cursor?: string): Promise<{ entries: Uint8Array[]; cursor: string; hasMore: boolean }> Reads one page of the entries a viewing bundle opens from a cursor on, through this account's API.

Balances#

A verified balance snapshot, as readBalances, lastKnownBalances and recoverBalancesFromHistory return it.

Field Type Meaning
balances Balance [] The account's balance leaves under the root, each verified and decrypted.
root string The Ledger root the leaves were checked against, base64.
crossing string The Crossing whose Commit wrote that root.
slot string The slot of that Commit, as the LedgerRoot account records it.
cursor string The snapshot's Crossing again.
hasMore false Always false: one call reads the whole snapshot.
stale boolean false from a fresh read; true from lastKnownBalances, the snapshot kept through a failed refresh.

Balance#

One balance leaf of the account, decrypted and checked against the snapshot’s root.

Field Type Meaning
asset Asset The leaf's asset.
balance bigint The balance in base units.
opening Uint8Array The commitment's opening, 32 bytes.
leaf Leaf The decoded 225-byte balance leaf.
crossing string The Crossing of the snapshot it was read in.
position number The leaf's position in the Ledger tree.

PrivateResult#

A decrypted enclave reply, the contract’s PrivateEvent, by kind. An order reply is an OrderResult, a status reply an AccountStatus and an exit reply an ExitUpdate. The others:

receipt, a signed Receipt:

Field Type Meaning
receipt.kind "receipt" receipt.
receipt.state "signed" signed.
receipt.bytes Base64 The signed Receipt's wire bytes, base64. decodeReceipt reads them.

registered, the answer to the account’s registration:

Field Type Meaning
registered.kind "registered" registered.
registered.accountIndex number The account's private index in the Ledger, assigned once and never moved.

escape, an Escape request taken:

Field Type Meaning
escape.kind "escape" escape.
escape.state "requested" requested.

ExitUpdate#

One Exit piece’s state: the exit reply in each piece’s results, and what watchExits yields.

Field Type Meaning
exit.kind "exit" exit.
exit.nonce U64 The nonce of the piece's exit Intent.
exit.index integer or null The piece's index in its Crossing's exits root; null until a Commit lists it.
exit.state "requested", "scheduled", "committed", "released" scheduled in intake's answer, committed once a Commit lists the piece, released once it is paid (ExitFlowState).
exit.asset number The asset's Registry index.
exit.amount U64 The piece's amount in base units.
exit.destination Address The destination address.
exit.crossing U64 or null The Crossing whose exits root lists it; null until a Commit lists it.
exit.transaction Signature or null The release transaction; null until released.

HistoryEntry#

One decrypted history entry, the contract’s HistoryEntry, by kind.

deposit:

Field Type Meaning
deposit.id string The entry's id.
deposit.asset Address The mint deposited.
deposit.crossing U64 The Crossing that credited it.
deposit.time Timestamp When that Crossing committed.
deposit.kind "deposit" deposit.
deposit.amount U64 Base units credited.
deposit.transaction Signature The deposit transaction.

fill:

Field Type Meaning
fill.id string The entry's id.
fill.asset Address The asset whose history the entry belongs to.
fill.crossing U64 The Crossing that filled it.
fill.time Timestamp When that Crossing committed.
fill.kind "fill" fill.
fill.pair PairId The market's pair id, baseMint_quoteMint.
fill.size U64 Base units filled.
fill.crossed object or null The crossed part; null when none.
fill.crossed.size U64 Base units crossed inside the Pool.
fill.crossed.price Decimal The mid it crossed at, quote per base.
fill.routed object or null The routed part; null when none.
fill.routed.size U64 Base units routed through the Residual swap.
fill.routed.price Decimal The executed Residual price, quote per base.
fill.routed.transaction Signature The Residual swap transaction.
fill.fee object The fee on the fill.
fill.fee.mint Address The pair's quote asset.
fill.fee.amount U64 Quote base units.

exit:

Field Type Meaning
exit.id string The entry's id.
exit.asset Address The mint exited.
exit.crossing U64 The Crossing that debited it.
exit.time Timestamp When that Crossing committed.
exit.kind "exit" exit.
exit.amount U64 Base units debited.
exit.destination Address The address it pays.
exit.transaction Signature or null The release transaction; null here, since the debiting Crossing writes the entry before the release.
exit.state "requested", "scheduled", "committed", "released" committed: the Crossing that debits the piece and lists it writes the entry.

fee:

Field Type Meaning
fee.id string The entry's id.
fee.asset Address The quote asset charged.
fee.crossing U64 The Crossing that charged it.
fee.time Timestamp When that Crossing committed.
fee.kind "fee" fee.
fee.amount U64 Base units charged.
fee.orderId string or null The fill entry the fee was charged on; null when none.

EncryptedEntry#

Wire bytes: mint 32 ‖ Crossing u64 ‖ entry index u32 ‖ root version u32 ‖ nonce 12 ‖ ciphertext, length-prefixed. The associated data is program 32 ‖ mint 32 ‖ Crossing u64 ‖ entry index u32 ‖ owner id hash 32 ‖ root version u32.

Field Type Meaning
asset string The entry's mint, base58.
crossing bigint The Crossing that wrote it.
entry number Its index within the Crossing.
rootVersion number The viewing root version it is encrypted under.
ownerIdHash Uint8Array SHA-256 of the owner's auth public key. Absent from the wire bytes; the reader's bundle supplies it.
nonce Uint8Array The 12-byte AES-GCM nonce.
ciphertext Uint8Array The encrypted entry, with its tag.

EscapeClaimAccount#

What decodeEscapeClaimAccount reads from an EscapeRequest account (EscapeRequest): 800 bytes under its discriminator, the leaf position at byte 8, the mint at 12, the owner key, commitment and handle at 44, 76 and 108, the share count and the combined and claimed flags at 733 to 735, and the combined pair at 736 and 768. claimEscape reads the account through the RPC relay and decodes it with this.

Field Type Meaning
leafIndex number The leaf's Ledger position.
mint string The leaf's mint, base58.
ownerKey Uint8Array The owner's escape public key Y, 32 bytes. Only its holder can claim.
commitment Uint8Array The leaf's commitment C, 32 bytes.
handle Uint8Array The leaf's Council handle D, 32 bytes.
count number Council shares posted so far.
combined boolean true once t shares are combined into a and b; a claim needs it.
claimed boolean true once the claim has paid.
a Uint8Array The combined A, 32 bytes.
b Uint8Array The combined B, 32 bytes.

EscapeClaimProof#

The proof createEscapeClaimProof makes and escape_claim checks (DleqProof). Each field is 32 bytes; the relay takes them in base64.

Field Type Meaning
r1 Uint8Array The nonce commitment r·G, 32 bytes.
r2 Uint8Array The nonce commitment r·A, 32 bytes.
z Uint8Array The response r + e·y modulo the group order, a little-endian scalar of 32 bytes.

@privium/sdk/wire#

Export Signature Meaning
utf8 utf8(s: string): Uint8Array A string as UTF-8 bytes.
text text(b: Uint8Array): string UTF-8 bytes as a string; throws on invalid UTF-8.
b64 b64(b: Uint8Array): string Bytes as padded base64.
unb64 unb64(s: string): Uint8Array Decodes padded base64.
addressBytes addressBytes(s: string): Uint8Array A base58 Solana address as its 32 bytes.
address address(b: Uint8Array): string 32 bytes as a base58 Solana address.
hex hex(b: Uint8Array): string Bytes as lowercase hexadecimal.
unhex unhex(s: string): Uint8Array Decodes hexadecimal.
concat concat(...parts: Uint8Array[]): Uint8Array Joins byte arrays.
fixed fixed(b: Uint8Array, n: number): Uint8Array Returns the bytes when they are exactly n long, else throws.
equal equal(a: Uint8Array, b: Uint8Array): boolean Compares two byte arrays in time that depends only on their length.
uint uint(n: bigint | number, size: number, little?: boolean): Uint8Array An unsigned integer in size bytes, little endian unless little is false.
int int(n: bigint, size: number): Uint8Array A signed integer in size bytes, two's complement, little endian.
number number(b: Uint8Array, little?: boolean): bigint Reads an unsigned integer from bytes, little endian unless little is false.
bytes bytes(b: Uint8Array): Uint8Array Bytes behind a u32 length.
string string(s: string): Uint8Array A UTF-8 string behind a u32 length.
vector vector<T>(items: T[], encode: (v: T) => Uint8Array): Uint8Array Items behind a u32 count, each written by encode.
option option<T>(value: T | null, encode: (v: T) => Uint8Array): Uint8Array A 0 byte for null, or a 1 byte and the encoded value.
fragmentEncode fragmentEncode(data: Uint8Array): string Bytes as unpadded base64url, for a link fragment.
fragmentDecode fragmentDecode(value: string): Uint8Array Decodes a link fragment, with or without its leading #.
Reader class Reader Reads a wire message field by field and fails on truncation, oversized fields and trailing bytes.
TradeIntent interface TradeIntent A trade Intent's fields before signing.
encodeIntent encodeIntent(i: TradeIntent): Uint8Array A trade Intent's 73-byte signing body.
decodeIntent decodeIntent(data: Uint8Array): TradeIntent Decodes a 73-byte trade Intent body.
INTENT_PLAINTEXT_LENGTH INTENT_PLAINTEXT_LENGTH = 160 Bytes in a signed trade Intent before sealing: 160.
EXTENDED_INTENT_LENGTH EXTENDED_INTENT_LENGTH = 4096 Bytes in every signed extended Intent before sealing: 4,096.
encodeSignedIntent encodeSignedIntent(i: TradeIntent, signature: Uint8Array): Uint8Array The 160-byte signed trade plaintext: body, signature, zero padding.
decodeSignedIntent decodeSignedIntent(p: Uint8Array): { intent: TradeIntent; signature: Uint8Array } Splits a 160-byte signed trade plaintext into the Intent and its signature.
ExtendedIntent type ExtendedIntent An Intent of a kind other than trade: cancel, exit, receipt, register, escape or status.
encodeExtendedIntent encodeExtendedIntent(i: ExtendedIntent): Uint8Array An extended Intent's body: PVIX, version 2, the kind's tag, account, nonce, expiry and payload.
extendedSigningBytes extendedSigningBytes(i: ExtendedIntent): Uint8Array The message the auth key signs for an extended Intent: privium/extended-intent/v2 and the body.
encodeSignedExtendedIntent encodeSignedExtendedIntent(i: ExtendedIntent, signature: Uint8Array): Uint8Array The 4,096-byte signed extended plaintext: body length, body, signature, zero padding.
decodeSignedExtendedIntent decodeSignedExtendedIntent(p: Uint8Array): { intent: ExtendedIntent; signature: Uint8Array } Splits a 4,096-byte signed extended plaintext into the Intent and its signature.
Leaf interface Leaf A balance leaf's fields.
leafPublic leafPublic(l: Leaf): Uint8Array A leaf's 109 public bytes: kind, asset, version, owner tag, commitment and Council handle.
encodeLeaf encodeLeaf(l: Leaf): Uint8Array A balance leaf's 225 bytes.
decodeLeaf decodeLeaf(b: Uint8Array): Leaf Decodes a 225-byte balance leaf.
leafAssociatedData leafAssociatedData(program: Uint8Array, index: number, l: Leaf): Uint8Array The associated data of both leaf ciphertexts: program, position and the leaf's public bytes.
leafNonce leafNonce(index: number, version: bigint): Uint8Array The nonce of both leaf ciphertexts: position and version, big endian.
Diff interface Diff A Crossing diff's fields.
encodeDiff encodeDiff(d: Diff): Uint8Array A Crossing diff's PVD1 bytes; writes must be sorted by position.
decodeDiff decodeDiff(b: Uint8Array): Diff Decodes PVD1 diff bytes.

Integers are unsigned and little endian unless marked signed or big endian. Fixed-size fields carry no length; byte strings, strings and vectors carry a u32 length or count; an option is one byte, 0 or 1, before its value. Solana addresses are 32 raw bytes in binary and base58 in JSON. Binary fields over HTTP are padded base64, and links carry unpadded base64url in their fragment. WIRE.md in the package fixes every format, and vectors/v2.json holds the exact bytes for fixed inputs.

Reader#

Member Signature Meaning
data data: Uint8Array The message being read.
offset offset: number Bytes read so far.
constructor new Reader(data: Uint8Array) Starts reading data at offset 0.
take take(n: number): Uint8Array The next n bytes; throws past the end.
u u(n: number): bigint An unsigned little-endian integer of n bytes.
i i(n: number): bigint A signed little-endian integer of n bytes.
bytes bytes(max?: number): Uint8Array A u32 length-prefixed field of at most max bytes, 1 MiB when absent.
str str(max?: number): string A u32 length-prefixed UTF-8 string of at most max bytes, 4,096 when absent.
array array<T>(decode: (r: Reader) => T, max?: number): T[] A u32 count-prefixed array of at most max items, 65,536 when absent.
opt opt<T>(decode: (r: Reader) => T): T | null A 0 or 1 option tag and, after a 1, the value.
end end(): void Throws unless every byte was read.

TradeIntent#

The 73-byte signing body: account 32 ‖ base index u32 ‖ quote index u32 ‖ side u8 (1 buy, 255 sell) ‖ size u64 ‖ limit u64 ‖ expiry u64 ‖ nonce u64. The signed plaintext is the body, the auth key’s 64-byte Ed25519 signature over it and 23 zero bytes, 160 bytes in all, and 208 bytes sealed.

Field Type Meaning
account Uint8Array The account's auth public key, 32 bytes.
base number The base asset's Registry index.
quote number The quote asset's Registry index, never the base's.
side 'buy' | 'sell' buy or sell the base.
size bigint Base units of the base asset, above zero.
limit bigint The worst price accepted, in units of 10^priceExponent quote whole tokens per base whole token, above zero.
expiry bigint A slot: the Intent takes part only in Crossings whose cutoff is at or before it.
nonce bigint The Intent's nonce.

ExtendedIntent#

The body: PVIX ‖ version u8 (2) ‖ kind tag u8 ‖ account 32 ‖ nonce u64 ‖ expiry u64 ‖ payload. The signature covers privium/extended-intent/v2 ‖ body. The signed plaintext is the body’s length u32, the body, the 64-byte signature and zeros to 4,096 bytes, so every kind seals to the same length.

Kind Tag Payload after the common header
cancel 1 The resting order's nonce, u64.
exit 2 Asset index u32, amount u64, destination 32 bytes, destination kind u8 (0 address, 1 Ring).
receipt 3 The encoded ReceiptRequest, behind a u32 length.
register 4 The 161-byte deposit note, behind a u32 length.
escape 5 The Escape request bytes, behind a u32 length.
status 6 Nothing, or an inclusive history range: from u64 ‖ to u64, then the asset's mint, 32 bytes, when one is named.

cancel:

Field Type Meaning
kind 'cancel' The kind, which sets the tag byte.
account Uint8Array The account's auth public key, 32 bytes.
nonce bigint A fresh nonce, consumed when intake accepts the Intent.
expiry bigint The slot it expires at; 2^64 − 1 never expires.
orderNonce bigint The nonce of the resting order to cancel.

exit:

Field Type Meaning
kind 'exit' The kind, which sets the tag byte.
account Uint8Array The account's auth public key, 32 bytes.
nonce bigint A fresh nonce, consumed when intake accepts the Intent.
expiry bigint The slot it expires at; 2^64 − 1 never expires.
asset number The asset's Registry index.
amount bigint Base units to exit.
destination string The destination address, base58.
destinationKind 'address' | 'ring' address for any address, ring for a Helius Ring deposit.

receipt:

Field Type Meaning
kind 'receipt' The kind, which sets the tag byte.
account Uint8Array The account's auth public key, 32 bytes.
nonce bigint A fresh nonce, consumed when intake accepts the Intent.
expiry bigint The slot it expires at; 2^64 − 1 never expires.
request Uint8Array The encoded ReceiptRequest.

The request bytes: from u64 ‖ to u64 ‖ the claims vector ‖ label string ‖ quote mint 32 ‖ cost basis u8 (0 average, 1 FIFO). Each claim is its tag u8, 0 to 6 for realized PnL, return, volume, fill count, fees, ending equity and assets, then for tags 0, 1, 2, 3 and 5 an option of the claim’s integer (i128, i64, u128, u32 and u128): none for an exact claim, the threshold for an at-least one. Tag 4 carries nothing, and tag 6 one byte, 1 for the list of mints with their count, 0 for the count alone (ReceiptRequestClaim).

register:

Field Type Meaning
kind 'register' The kind, which sets the tag byte.
account Uint8Array The account's auth public key, 32 bytes.
nonce bigint A fresh nonce, consumed when intake accepts the Intent.
expiry bigint The slot it expires at; 2^64 − 1 never expires.
registration Uint8Array The encoded deposit note: the account's public keys.

escape:

Field Type Meaning
kind 'escape' The kind, which sets the tag byte.
account Uint8Array The account's auth public key, 32 bytes.
nonce bigint A fresh nonce, consumed when intake accepts the Intent.
expiry bigint The slot it expires at; 2^64 − 1 never expires.
request Uint8Array The Escape request bytes.

status, with its optional history range (openOrders):

Field Type Meaning
kind 'status' The kind, which sets the tag byte.
account Uint8Array The account's auth public key, 32 bytes.
nonce bigint A fresh nonce, consumed when intake accepts the Intent.
expiry bigint The slot it expires at; 2^64 − 1 never expires.
range object (optional) The history range the status lists entry Crossings for, under the same signature. Absent: Crossing 0 through the last committed, every asset.
range.from bigint The range's first Crossing.
range.to bigint The range's last Crossing, at or after from.
range.asset string (optional) A mint: list only Crossings holding the account's entries of that asset. Every asset when absent.

Leaf#

225 bytes: kind u8 (2) ‖ asset u32 ‖ version u64 ‖ owner tag 32 ‖ commitment 32 ‖ Council handle 32 ‖ Ledger ciphertext 60 ‖ owner ciphertext 56. Both ciphertexts take the nonce position u32 ‖ version u64, big endian, and the associated data program 32 ‖ position u32 ‖ the leaf’s first 109 bytes (A balance leaf).

Field Type Meaning
asset number The asset's Registry index.
version bigint The index of the Crossing that wrote the leaf.
ownerTag Uint8Array SHA-256 of privium/owner/v1, the escape public key, the salt, the mint and the version.
commitment Uint8Array The Pedersen commitment balance·G + opening·H, 32 bytes.
councilHandle Uint8Array The opening times the Council public key, 32 bytes: with the commitment, the ciphertext the Council decrypts.
ledgerCiphertext Uint8Array 60 bytes under the Ledger data key: the account index, balance and opening, with the tag.
ownerCiphertext Uint8Array 56 bytes under the owner's balance key: balance and opening, with the tag.

Diff#

PVD1 ‖ Crossing u64 ‖ previous root 32 ‖ root 32, then the vectors of cuts, writes, proofs and entries, then crossed and routed notional as u128 each (Data availability through log_diff). A write’s leaf is a 225-byte balance leaf, a 197-byte account record, or empty for a position the Crossing cleared. An account record is kind u8 (1) ‖ Crossing u64 ‖ AES-256-GCM ciphertext under the Ledger data key of the account’s private index u32, the five keys of its deposit note and its nonce watermark u64: a 172-byte plaintext, 197 bytes with the header and tag.

Field Type Meaning
crossing bigint The Crossing's index.
previousRoot Uint8Array The Ledger root before the Crossing.
root Uint8Array The Ledger root after it, which the Commit accepts.
cuts object[] The deposit queue cut per asset and vault shard.
cuts[].asset number The asset's Registry index.
cuts[].shard number The vault shard.
cuts[].sequence bigint The queue sequence the cut reaches.
writes object[] Every rewritten position, sorted by position.
writes[].index number The Ledger position.
writes[].leaf Uint8Array The new leaf's bytes; empty bytes empty the position.
proofs object[] Per asset, the aggregate values and proofs behind its conservation check.
proofs[].asset number The asset's Registry index.
proofs[].commitmentDelta Uint8Array The sum of the asset's leaf commitment changes, 32 bytes.
proofs[].aggregateOpening Uint8Array The sum of the asset's opening changes, 32 bytes.
proofs[].validityProof Uint8Array 128 bytes proving the rewritten leaves are well-formed ciphertexts.
proofs[].rangeProof Uint8Array The proof that every rewritten balance is in range.
entries Uint8Array[] The Crossing's encrypted history entries, each in its wire bytes.
crossedNotionalUsd bigint The Crossing's crossed notional, in millionths of a USD.
routedNotionalUsd bigint The Crossing's routed notional, in millionths of a USD.

@privium/sdk/crypto#

Export Signature Meaning
ACCOUNT_MESSAGE ACCOUNT_MESSAGE = "Privium account v1\nThis signature derives your Privium keys. It moves no funds." The message the wallet signs once to open the account.
SCALAR_ORDER SCALAR_ORDER: bigint The order of the ristretto255 group.
hash hash(...parts: Uint8Array[]): Uint8Array SHA-256 of the joined parts.
prf prf(key: Uint8Array, ...parts: Uint8Array[]): Uint8Array HMAC-SHA-256 of the joined parts under key.
scalar scalar(seed: Uint8Array): bigint A nonzero ristretto255 scalar from a seed: SHA-512, little endian, reduced mod (order − 1), plus 1.
PEDERSEN_H PEDERSEN_H: Uint8Array<ArrayBufferLike> & Uint8Array<ArrayBuffer> The Pedersen generator H: the ristretto255 element derived from SHA3-512 of the compressed base point.
commitment commitment(balance: bigint, opening: Uint8Array): Uint8Array The Pedersen commitment balance·G + opening·H.
AccountKeys interface AccountKeys The keys the one signature derives.
deriveAccountKeys deriveAccountKeys(signature: Uint8Array): AccountKeys The account's keys from the wallet's 64-byte signature of ACCOUNT_MESSAGE.
verifySignature verifySignature(signature: Uint8Array, message: Uint8Array, publicKey: Uint8Array): boolean Verifies an Ed25519 signature under RFC 8032's strict rules.
sign sign(message: Uint8Array, seed: Uint8Array): Uint8Array Signs a message with an Ed25519 seed.
assetKey assetKey(root: Uint8Array, mint: Uint8Array): Uint8Array An asset's viewing key under a viewing root.
balanceKey balanceKey(root: Uint8Array, mint: Uint8Array): Uint8Array The key of an asset's owner ciphertext under a viewing root.
ownerTag ownerTag(keys: AccountKeys, mint: Uint8Array, version: bigint): Uint8Array A balance leaf's owner tag for a mint and version.
suite suite: CipherSuite The HPKE suite: DHKEM(X25519, HKDF-SHA256), HKDF-SHA256 and AES-256-GCM.
AttestedKey interface AttestedKey The enclave key an Intent is sealed to, with the deployment and epoch it is bound to.
intentInfo intentInfo(key: AttestedKey, purpose?: string): Uint8Array The HPKE info for a purpose: privium/intent/v2, privium/deposit-note/v1 or privium/reply/v1, then program, epoch and quote hash.
hpkeSeal hpkeSeal(publicKey: Uint8Array, plaintext: Uint8Array, info: Uint8Array, aad?: Uint8Array<ArrayBuffer>, deterministicIkm?: Uint8Array): Promise<Uint8Array> Seals bytes to an X25519 public key with HPKE base mode: the 32-byte encapsulated key, then the ciphertext.
hpkeOpen hpkeOpen(privateKey: Uint8Array, ciphertext: Uint8Array, info: Uint8Array, aad?: Uint8Array<ArrayBuffer>): Promise<Uint8Array> Opens HPKE bytes with an X25519 private key.
sealIntent sealIntent(i: TradeIntent, keys: AccountKeys, enclave: AttestedKey): Promise<Uint8Array> Signs a trade Intent with the auth key and seals it to the enclave.
aesSeal aesSeal(key: Uint8Array, nonce: Uint8Array, plaintext: Uint8Array, aad: Uint8Array): Promise<Uint8Array> AES-256-GCM encryption with a 12-byte nonce and associated data.
aesOpen aesOpen(key: Uint8Array, nonce: Uint8Array, ciphertext: Uint8Array, aad: Uint8Array): Promise<Uint8Array> AES-256-GCM decryption; throws when the tag does not verify.
leafHash leafHash(leaf: Uint8Array): Uint8Array A Merkle leaf hash: SHA-256 of 0x00 and the leaf.
nodeHash nodeHash(left: Uint8Array, right: Uint8Array): Uint8Array A Merkle interior hash: SHA-256 of 0x01, left and right.
merkleRoot merkleRoot(leaf: Uint8Array, index: number, siblings: Uint8Array[]): Uint8Array The root a leaf and its 32 siblings give at a position.
verifyMerklePath verifyMerklePath(leaf: Uint8Array, index: number, siblings: Uint8Array[], root: Uint8Array): boolean Whether a leaf and its siblings give the expected root.
emptySiblings emptySiblings(): Uint8Array[] The 32 siblings of any position in an empty tree, bottom to top.
encryptLeaf encryptLeaf(input: { … }): Promise<Leaf> Builds a balance leaf: commitment, Council handle and both ciphertexts.
decryptLeaf decryptLeaf(data: Uint8Array, input: { … }): Promise<{ balance: bigint; opening: Uint8Array; leaf: Leaf }> Checks a leaf's Merkle path, decrypts its owner ciphertext and checks the commitment.
diffAccumulator diffAccumulator(program: Uint8Array, crossing: bigint, chunks: Uint8Array[]): Uint8Array The data availability accumulator of a Crossing's diff chunks.
DepositNote interface DepositNote The account's public keys, as a deposit note and a register Intent carry them.
encodeDepositNote encodeDepositNote(n: DepositNote): Uint8Array A deposit note's 161 bytes.
sealDepositNote sealDepositNote(n: DepositNote, enclave: AttestedKey): Promise<Uint8Array> Seals a deposit note to the enclave under the privium/deposit-note/v1 info.
decodeDepositNote decodeDepositNote(p: Uint8Array): DepositNote Decodes a 161-byte deposit note.
replySigningBytes replySigningBytes(plaintext: Uint8Array, context: AttestedKey): Uint8Array The message the enclave signs on a reply: privium/reply/v1, program, epoch and the reply's JSON.
sealReply sealReply(plaintext: Uint8Array, recipientPublicKey: Uint8Array, context: AttestedKey, signingSeed: Uint8Array): Promise<Uint8Array> Signs a reply and seals it to an account's reply key.
openReply openReply(sealed: Uint8Array, recipientSeed: Uint8Array, context: AttestedKey, signingKey: Uint8Array): Promise<Uint8Array> Opens a sealed reply with the account's note key, verifies the enclave's signature and returns the reply's JSON bytes.

HPKE is RFC 9180 base mode with DHKEM(X25519, HKDF-SHA256), HKDF-SHA256 and AES-256-GCM, with empty associated data; a sealed message is the 32-byte encapsulated key followed by the ciphertext and tag. The info string names the purpose (privium/intent/v2, privium/deposit-note/v1 or privium/reply/v1), then the program, the key epoch and the quote hash. The keys the one signature derives are AccountKeys.

AttestedKey#

Field Type Meaning
programId Uint8Array The program id, 32 bytes.
epoch bigint The enclave key epoch.
quoteHash Uint8Array The hash of the attestation quote registered for the epoch, 32 bytes.
hpkePublicKey Uint8Array The enclave's X25519 public key.

DepositNote#

161 bytes: version u8 (1) ‖ auth public key 32 ‖ viewing root 32 ‖ escape public key 32 ‖ owner salt 32 ‖ reply key 32.

Field Type Meaning
authPublicKey Uint8Array The auth public key.
viewRoot Uint8Array The viewing root, so the enclave can encrypt entries under the account's tree.
escapePublicKey Uint8Array The escape public key.
ownerSalt Uint8Array The owner tag salt.
replyPublicKey Uint8Array The X25519 key replies are sealed to.

@privium/sdk/fixtures#

Fixed, published test material: an enclave’s HPKE and signing keys, a test wallet, the account keys that wallet’s signature derives, and the payload builders that use them. Nothing in it holds or reaches funds.

Export Signature Meaning
fixtureEnclaveKeys fixtureEnclaveKeys: { … } The fixture enclave's public test keys: HPKE seed and key, signing seed and key.
fixtureWalletSeed fixtureWalletSeed: Uint8Array<ArrayBuffer> The test wallet's Ed25519 seed.
fixtureWallet fixtureWallet: { … } A Wallet that signs with the test seed.
fixtureAccountKeys fixtureAccountKeys: AccountKeys The account keys the test wallet's signature derives.
fixtureAccountIndex fixtureAccountIndex = 42 The account index the fixture enclave assigns: 42.
FixtureEnclave interface FixtureEnclave The enclave fields the fixture intake reads.
fixturePublicExit fixturePublicExit(crossing: string, index: number): PublicExit | undefined The public record of an Exit piece the fixture intake committed, by Crossing and index, or undefined.
fixturePrivateStates fixturePrivateStates(): readonly ['sealed', 'waiting', 'filled', 'resting', 'partly-filled', 'expired', 'cancelled', 'rejected'] The order states a fixture scenario can force.
fixtureHandleIntake fixtureHandleIntake(programId: string, enclave: FixtureEnclave, sealed: string, scenario?: string): Promise<{ envelopes: string[] }> The fixture enclave's intake: opens a sealed Intent with the test keys and returns sealed replies.
addressSignature addressSignature(label: string): string A base58 test signature for a label.
createFixtureLedger createFixtureLedger(programId: string, mint?: string, registryIndex?: number): Promise<{ … }> A test Crossing diff holding the test account's balance leaf and history entries.

FixtureEnclave#

Field Type Meaning
keyEpoch string The enclave key epoch.
quoteHash string The quote hash, base64.
signingKey string The enclave's signing key, base58.

@privium/sdk/program#

Export Signature Meaning
PRIVIUM_POOL_IDL PRIVIUM_POOL_IDL: { … } The Anchor IDL of privium_pool: its address, instructions, accounts, events, errors and types.
PriviumPoolIdl type PriviumPoolIdl = typeof PRIVIUM_POOL_IDL The type of PRIVIUM_POOL_IDL.

PriviumPoolIdl#

The type of PRIVIUM_POOL_IDL: every instruction, account, event, error and type of the IDL as literal types. The program itself is told in the Program reference.

@privium/sdk/contract#

The contract the tarball bundles, re-exported whole: the client behind privium.api, the zod schemas the API validates every request, response and decrypted reply with, and the encodings. A project imports it from the SDK and installs nothing else. Each schema is exported with its type under the same name, and a linked name opens its field table in the API reference or under Decrypted plaintext. The client is told in Base URL and versions.

Exports Holds
CONTRACT_VERSION, errors, ErrorCode, ApiError, Hash, Decimal, UnsignedDecimal, PairId, pairId, Countdown, Enclave, Params, Config, Health, AggregateMetric, Home, Asset, Market, MarketsQuery, Markets, Mid, MarketQuery, RouteBound, MarketPanel, Candle, CandlesQuery, Candles, ResidualSwap, Fee, Crossing, CrossingsQuery, Crossings, VaultAsset, Buyback, TokenPanel, NoFeedVenue, NoFeedRouting, AnonymityDay, Pool, Council, Liveness, Trust, Root, MerklePath, Leaf, LedgerDiff, CrossingList, LedgerQuery, LedgerDiffs, LedgerLeavesRequest, LedgerLeaves, IntakeRequest, IntakeAccepted, DepositBuildRequest, TransactionBuild, DepositStatus, Admission, EscapeRequest, EscapeBuildRequest, EscapeRelayRequest, EscapeSubmission, EncryptedEvent, LiveEvent, EventsQuery, RpcRequest, RpcResponse, OrderState, OrderResult, OpenOrder, PublicExit, PendingExit, AccountHistory, AccountStatus, PrivateEvent, AccountGate, ReceiptVerificationState, ViewingBundleState, DepositFlowState, ExitFlowState, HistoryEntry, RingLookup The zod schemas the API validates with: every request, response, query, event and decrypted plaintext, each with its type under the same name, the error table (errors, ErrorCode, ApiError) and CONTRACT_VERSION. A linked name opens its field table.
DEFAULT_FEE_BPS, MAX_PRICE_AGE_MS, PRV_TOKEN The product's fixed values: the default fee rate, the oldest price a Crossing clears at, and the $PRV mint's facts as read on chain. The SDK's root exports them too.
U64_MAX, Address, Signature, BaseUnits, U64, PositiveU64, Base64, Timestamp, PageQuery, PageInfo, page, paginate The shared scalars, as Encoding gives them, U64_MAX, and the page schema and helper every list route uses.
toBase64, fromBase64, toBase58, fromBase58, shortAddress Base58 and base64 with no dependencies, and shortAddress, an address cut to its first and last characters.
ApiClientError, HttpOptions, CallOptions, createHttp, Http ApiClientError, which every client method throws for an error envelope, and createHttp, the fetch core the client is built on, with its option types.
createClient, PriviumApi createClient(baseUrl, options), the typed client of every route that privium.api is, and its type PriviumApi.
ErrorStage, ApiErrorBody The error envelope's types.

@privium/sdk/contract/fixtures#

The contract’s fixtures, re-exported whole: named sample states and the sample data for each, built from the same schemas as every response.

Exports Holds
SCENARIOS, Scenario, FIXTURE_TIME, hash, PROGRAM_ID, assets, markets, enclave, countdown, feeRecipient, config, crossings, home, marketPanel, fixturePrice, candles, pool, trust, ledgerDiffs, transactionBuild, depositStatus, escapeRequest, errorFixtures, uiFixtures, ringAddresses, ringLookup, publicExit, pairFixtures The API's fixture mode as data: every scenario name, the sample markets, assets, Crossings, Pool, Trust and Ledger diffs, one error envelope per code, and the plaintext samples the app's private screens draw.
fixtureAddress, fixtureSignature, fixtureTransaction Deterministic sample addresses and signatures from a seed, and transaction bytes no wallet or RPC accepts.

Decrypted plaintext#

The contract’s types for what the calls return once they have decrypted it locally. No route returns any of them in the clear.

AccountGate#

The account’s gate in the app, from no wallet to ready.

Value Meaning
no-wallet No wallet is connected.
no-account A wallet is connected and the account message is not signed yet.
no-balance The account holds no balance yet: deposit first.
ready The account can trade.
escape The Escape is active and trading is closed.
indexer-unreachable The indexer is unreachable: balances show as of the last verified Crossing.

AccountStatus#

What openOrders returns.

Field Type Meaning
history AccountHistory The Crossings of the status Intent's history range that hold the account's entries: Crossing 0 through the last committed, every asset, when it named no range.
kind "status" status.
watermark U64 The account's spent-through nonce: every nonce at or below it is consumed.
ledger object Where the account's leaves stand at the Commit the status was read against.
ledger.crossing U64 The Crossing whose Commit set that root.
ledger.root Hash The Ledger root the positions hold under; readBalances reads LedgerRoot and requires the same root and Crossing.
ledger.positions integer[] The positions of the account's current balance leaves, which readBalances fetches through POST /v1/ledger/leaves, up to 256 a request.
openOrders OpenOrder[] The account's resting and partly filled orders.
pendingExits PendingExit[] The account's Exit pieces with their state.

AccountHistory#

The entry Crossings of a status’s history range, which disclose and readHistory read before fetching diffs. An entry counts under its own asset: a deposit credit and an Exit under theirs, a fill under its pair’s base and its fee under the quote.

Field Type Meaning
from U64 The first Crossing of the range asked for.
to U64 The last Crossing of the range, capped at the last committed Crossing.
entryCrossings U64[] Up to 256 Crossings of the range that hold the account's entries, ascending; with an asset named, those holding entries of that asset.
hasMore boolean true when the range holds more such Crossings than this list: ask again from nextFrom.
nextFrom U64 or null One past the last listed Crossing while hasMore is true; null otherwise.

OpenOrder#

Field Type Meaning
id string The order's id.
nonce U64 The order's nonce. cancel takes it as a bigint.
pair PairId The market's pair id, baseMint_quoteMint.
side "buy", "sell" buy or sell the base.
remainingSize U64 Base units not yet filled.
limit PositiveU64 The limit, in units of 10^priceExponent quote whole tokens per base whole token.
expirySlot U64 The slot the order expires at.
state "resting", "partly-filled" resting, or partly-filled once part of it has filled.

PendingExit#

One Exit piece, as pendingExits returns it.

Field Type Meaning
id string The piece's id.
nonce U64 The nonce of the exit Intent that carried the piece.
index integer or null The piece's index in its Crossing's exits root; null until a Commit lists it.
asset Address The mint.
amount PositiveU64 The piece's amount in base units: one denomination.
destination Address The address the piece pays.
releaseSlot U64 or null The release slot the enclave sampled: the first Crossing opened at or after it lists the piece. null while requested.
crossing U64 or null The Crossing whose exits root lists the piece; null until a Commit lists it.
state "requested", "scheduled", "committed", "released" scheduled, committed or released (ExitFlowState).
transaction Signature or null The release transaction; null until released.

OrderState#

Value Meaning
sealed Sealed and sent to the Coprocessor.
waiting Accepted and waiting for Crossing crossing.
filled Filled in full.
resting Resting across Crossings with nothing filled yet, until its limit is met, it expires or it is cancelled.
partly-filled Part filled; the rest keeps resting, and the order stays partly-filled at each Crossing that gives it no new fill.
expired Reached its expiry; what remained unfilled is released.
cancelled Cancelled by a cancel Intent.
rejected Refused by the enclave; reason says why.

OrderResult#

An order’s state, in a Submission’s results and on watchFills, each newer than the last the instance holds for the order (Order tracking).

Field Type Meaning
kind "order" order.
id string The order's id.
nonce U64 The order's nonce.
state OrderState The order's state.
crossing U64 or null The Crossing the state refers to; null while sealed.
reason "unfunded", "stale-price", "bad-limit", "below-minimum" or null Why the enclave rejected the order: unfunded (the unreserved balance does not cover it) or below-minimum (its size is under one denomination unit of the base); null unless rejected.
filledBase U64 Base units filled so far.
crossed object or null The crossed part, filled inside the Pool at the mid; null when none.
crossed.size U64 Base units crossed.
crossed.price Decimal The mid it crossed at, quote per base.
routed object or null The routed part, filled through the pair's Residual swap; null when none.
routed.size U64 Base units routed.
routed.price Decimal The executed Residual price, quote per base.
routed.transaction Signature The Residual swap transaction.
fee object or null The fee charged; null before any fill.
fee.mint Address The pair's quote asset.
fee.amount U64 Quote base units.

DepositFlowState#

Value Meaning
building The deposit transaction is being built.
signing The wallet is signing it.
sent Sent and not landed yet.
landed Landed in the deposit queue and not credited yet.
credited Credited to the balance by a Commit.
refunded Refunded to its source after the Escape opened.

ExitFlowState#

Value Meaning
requested Signed and sent; the enclave has not sampled its release slot yet.
scheduled Accepted: the enclave holds its sampled release slot, shown to the owner alone, and its amount stays reserved in the balance. Nothing is on chain.
committed Debited and listed in the exits root of the first Commit whose Crossing opened at or after its release slot; releasable from then.
released Paid to the destination.

ReceiptVerificationState#

The /r page’s states; receipts.verify returns all but verifying.

Value Meaning
verifying The checks are running.
verified Every check passed.
unknown-enclave-key The signing key was not admitted at the signed slot.
signature-invalid The enclave signature does not verify.
root-not-on-chain The ending root is not the one the Commit of the span's last Crossing accepted.
malformed The Receipt bytes do not decode.

ViewingBundleState#

The /v page’s states.

Value Meaning
decrypting Entries are being read and decrypted.
opened The covered entries are decrypted.
out-of-scope The entry asked for lies outside the bundle's scope.
malformed The bundle bytes do not decode.