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. |