• Reading the docs…
Start trading

SDK

disclose

privium.disclose builds a viewing bundle: the keys that open exactly one scope of the account’s history, the Crossings of that scope that hold the account’s entries, and a /v link that carries both in its fragment. It asks the enclave for those Crossings with signed status Intents, then builds the bundle in the caller’s process. A reader opens the bundle with readBundle, with no account and no wallet.

disclose.ts
const { items } = await privium.api.markets({ q: 'SOL', quote: 'USDC' })
const usdc = items[0].quote

const { link } = await privium.disclose({ kind: 'period', asset: usdc.mint, from: 1000n, to: 2000n })
const whole = await privium.disclose({ kind: 'account' })
console.log(link, whole.bundle.crossingRanges)

Parameters#

Parameter Type Meaning
scope ViewingScope What the bundle opens.

ViewingScope#

One of four scopes, by kind (Scopes).

The whole account, every asset:

Field Type Meaning
kind 'account' The scope.

One asset:

Field Type Meaning
kind 'asset' The scope.
asset string The asset's mint, base58.

One asset over Crossings from to to:

Field Type Meaning
kind 'period' The scope.
asset string The asset's mint, base58.
from bigint The first Crossing covered.
to bigint The last Crossing covered, at or after from and below 2^40.

One entry:

Field Type Meaning
kind 'entry' The scope.
asset string The asset's mint, base58.
crossing bigint The entry's Crossing.
entry number The entry's index within its Crossing.

What it does#

  1. Sets the span: a period’s from to to, an entry’s one Crossing, and every Crossing, 0 to 264−12^{64} - 1, for an account or an asset.
  2. Asks the enclave for the span’s entry Crossings with a status Intent, sent as openOrders sends it with a range: the span, with the scope’s asset for every scope but the account. The enclave answers with up to 256 Crossings of the span, through the last committed one, that hold the account’s entries (AccountHistory). An entry counts under its own asset: a fill under its pair’s base, its fee under the quote (What a Viewing key opens). While hasMore is true, the call asks again from nextFrom, each time a new status Intent under a fresh nonce.
  3. Joins those Crossings into ranges with compressCrossings and builds a version 2 bundle under the account’s viewing root: the scope’s keys and the ranges.
  4. Builds the link on the origin given to connect, https://privium.io when none was.

Each status Intent holds the account’s queue in the process and raises the instance’s nonce floor, as openOrders does (Nonces).

Returns#

Field Type Meaning
bundle ViewingBundle The viewing bundle.
link string The /v link, with the bundle in its fragment.

The bundle holds the viewing root for the account scope, the asset key for an asset, the fewest period tree nodes that cover exactly the span for a period (at most 78), and the entry’s own key for an entry, with the ranges of step 3. readBundle reads the Crossings those ranges list: the ones that held the scope’s entries when the bundle was built. A bundle built later lists the Crossings committed since. The link is the origin, /v and the bundle’s bytes in base64url in the fragment, which browsers do not send to a server.

ViewingBundle#

Field Type Meaning
version 1 | 2 2 (PVV2) when the bundle carries crossingRanges, as disclose builds it; 1 (PVV1) without them.
crossingRanges CrossingRange [] (optional) The Crossings of the scope that held the account's entries when the bundle was built, as ordered ranges that neither overlap nor touch; empty when there were none. Version 2 only. readBundle reads just these.
programId string The program the entries belong to, base58.
ownerIdHash Uint8Array SHA-256 of the account's auth public key, which each entry's decryption is bound to.
rootVersion number The viewing root's version: 1.
scope ViewingScope The scope the nodes open.
nodes ViewingNode [] The keys handed over: one node, or for a period its covering nodes.

CrossingRange#

Field Type Meaning
from bigint The range's first Crossing.
to bigint The range's last Crossing, inclusive.

ViewingNode#

Field Type Meaning
prefix bigint The node's path below the scope's root key, depth bits, most significant first.
depth number Levels below the scope's root key, 0 to 40.
key Uint8Array The node's key, 32 bytes.

Errors#

Code Stage Message
PROGRAM_UNAVAILABLE read The enclave quote has not been indexed yet. Retry when its attestation is available.
CONFIGURATION_REQUIRED read The API changed its Pool program. Reconnect explicitly.
DECRYPTION_FAILED read This envelope cannot be opened by this account.
INTAKE_UNAVAILABLE send The account registration is sealed and the intake is unreachable.
INTAKE_UNAVAILABLE read The account status intake is unreachable.
UPSTREAM_UNAVAILABLE read The enclave returned no account status.
UPSTREAM_UNAVAILABLE read The encrypted history cursor did not advance.

The status Intents raise what openOrders raises, and intake’s other errors throw ApiClientError. A nextFrom that does not move past the Crossing asked from throws UPSTREAM_UNAVAILABLE. The byte layer throws a plain Error (Errors from the byte layer):

  • Invalid status history range: a period’s to is before its from, before the status Intent is sealed.
  • Invalid viewing period: a period’s to is 2402^{40} or more.
  • Invalid viewing node: an entry’s crossing is 2402^{40} or more.
  • Integer exceeds u64: a period’s from is negative.
  • Expected 32 bytes, or a base58 error: asset is not a mint address.

readBundle#

Reads a page of the entries a bundle opens: the diffs of the bundle’s Crossings after a cursor, within its scope and an optional Crossing range. readBundle(bundle, api, cursor, range) takes a contract client or the API’s base URL; privium.readBundle(bundle, cursor) reads through the instance’s client, over the bundle’s whole scope.

read-bundle.ts
import { decodeHistory, readBundle, viewingFromFragment } from '@privium/sdk'

const bundle = viewingFromFragment(location.hash)
let cursor: string | undefined
for (;;) {
  const page = await readBundle(bundle, 'https://api.privium.io', cursor)
  console.log(decodeHistory(page.entries))
  cursor = page.cursor
  if (!page.hasMore) break
}

// Only Crossings 1000 to 1200 of what the bundle opens.
const span = await readBundle(bundle, 'https://api.privium.io', undefined, { fromCrossing: 1000n, toCrossing: 1200n })

It checks the bundle by encoding and decoding it, as Viewing links gives, and reads GET /v1/config. The span it reads is the bundle’s own, from to to for a period and the one Crossing of an entry, narrowed to range when given; a span that leaves none returns an empty page and reads no diff. Then it reads one page of GET /v1/ledger/diffs after cursor:

  • A version 2 bundle reads only the Crossings its ranges list within the span: the next 24 after cursor, asked for by number with the route’s crossings parameter. The page must return those Crossings in order, or the first of them when the API’s page budget ends it early; any other page throws a plain Error, INDEXER_UNAVAILABLE. With no listed Crossing left, the call returns an empty page and reads no diff.
  • A version 1 bundle lists no Crossings and reads every diff of the span after cursor.

For each diff, it:

  1. Reads the Commit record of the diff’s root with GET /v1/roots/{root}.
  2. When the diff’s Crossing directly follows the one before it on the page, checks that its previousRoot is that diff’s root.
  3. Checks the record’s root, program and Crossing against the diff and the bundle, and pins the record to the chain with verifyChainRoot: the Commit transaction, read through the RPC relay, holds the program’s signed commit of this root.
  4. Checks that the chunks join to the diff’s bytes and fold to the Commit’s data availability accumulator, then that the diff’s own header names the same root, Crossing and previous root as the page.
  5. Decrypts each entry the bundle’s keys open. Entries outside the scope, in a Crossing a version 2 bundle does not list, or under another account’s keys, are passed over.

A reader therefore reads only entries a Commit on chain sealed, each diff pinned to its own Commit, whoever serves the diffs (Viewing bundles at /v).

Parameter Type Meaning
bundle ViewingBundle The viewing bundle to read with.
api PriviumApi | string A contract client, or the API's base URL.
cursor string (optional) A cursor a previous page returned: the read continues after it. Absent, it starts at the first diff in range.
range { fromCrossing?: bigint; toCrossing?: bigint } (optional) The Crossings to read, fromCrossing to toCrossing inclusive, either end open when absent. A period or entry scope narrows it to its own Crossings, and a version 2 bundle reads only the Crossings it lists.
Field Type Meaning
entries Uint8Array[] The plaintext bytes of each entry the bundle opens on this page, in diff order.
cursor string Where the page ended, at its last diff: pass it to read the next page.
hasMore boolean true while the bundle's listed Crossings in range remain after this page (for version 1, any diffs in range): call again with cursor.

While hasMore is true, call again with the cursor the page returned. Once it is false, a version 2 bundle has read every Crossing it lists, and a version 1 bundle’s cursor later reads only the Crossings committed since.

Each entry is the JSON bytes of a HistoryEntry; decodeHistory parses them, and readHistory does both steps. The diffs carry one entry per deposit credit, fill, fee and Exit, so a bundle opens those and nothing else: open orders and scheduled Exit pieces stay off the diff in the enclave’s working state, and only the account reads them, with openOrders.

A diff that fails step 3 throws a plain Error, ROOT_NOT_ON_CHAIN, and one that fails step 2 or 4 throws MERKLE_PROOF_INVALID. A bundle that does not decode throws MALFORMED_BUNDLE before any request. The API’s refusals throw ApiClientError: INDEXER_UNAVAILABLE from the diff route, ROOT_NOT_ON_CHAIN when the API holds no Commit for a root, and the RPC relay’s own refusals.

Function Does
viewingLink(bundle, origin) The link: origin, without a trailing slash, then /v# and the bundle’s bytes in base64url.
viewingFromFragment(fragment) The bundle from a link’s fragment, with or without its #.
encodeViewingBundle(bundle) The bundle’s bytes: PVV2 for version 2, PVV1 for version 1.
decodeViewingBundle(bytes) The bundle from its bytes, either version.
compressCrossings(crossings) Crossings as the ranges a version 2 bundle carries: sorted, repeats dropped and consecutive Crossings joined. A Crossing below 0 or at 2402^{40} or more throws Invalid history Crossing.

The bytes: PVV1 or PVV2 ‖ program 32 ‖ owner id hash 32 ‖ root version u32 ‖ scope tag u8 (0 account, 1 asset, 2 period, 3 entry) ‖ the scope’s mint 32, then a period’s from u64 ‖ to u64 or an entry’s Crossing u64 ‖ index u32 ‖ the node vector, each node prefix u64 ‖ depth u8 ‖ key 32. Version 2 appends the vector of ranges, each from u64 ‖ to u64.

Decoding checks the tag, a root version of at least 1, the scope’s tag and bounds, and that the nodes cover exactly the scope: the root node (prefix 0, depth 0) for an account or an asset, the entry’s Crossing at depth 40 for an entry, and for a period nodes that tile from to to with no gap or overlap. For version 2 it checks that each range runs from a Crossing to one at or after it, below 2402^{40}, with at least one Crossing between it and the range before; that a period’s ranges sit inside its span; and that an entry’s range is its own Crossing. An empty list decodes: the bundle lists no Crossing. A bundle that fails throws a plain Error, MALFORMED_BUNDLE. More than 80 nodes or 65,536 ranges throw Wire array exceeds limit, truncated bytes Truncated wire message and extra bytes Trailing wire bytes. The /v page’s states are in ViewingBundleState.

Parameter Type Meaning
bundle ViewingBundle The viewing bundle.
origin string The site origin, such as https://privium.io; a trailing slash is dropped.
Parameter Type Meaning
fragment string A /v link's fragment, with or without its #.