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.
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#
- Sets the span: a period’s
fromtoto, an entry’s one Crossing, and every Crossing, 0 to , for an account or an asset. - Asks the enclave for the span’s entry Crossings with a status Intent, sent as
openOrderssends 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). WhilehasMoreistrue, the call asks again fromnextFrom, each time a new status Intent under a fresh nonce. - Joins those Crossings into ranges with
compressCrossingsand builds a version 2 bundle under the account’s viewing root: the scope’s keys and the ranges. - Builds the link on the
origingiven toconnect,https://privium.iowhen 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’stois before itsfrom, before the status Intent is sealed.Invalid viewing period: a period’stois or more.Invalid viewing node: an entry’scrossingis or more.Integer exceeds u64: a period’sfromis negative.Expected 32 bytes, or a base58 error:assetis 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.
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’scrossingsparameter. 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 plainError,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:
- Reads the Commit record of the diff’s root with
GET /v1/roots/{root}. - When the diff’s Crossing directly follows the one before it on the page, checks that its
previousRootis that diff’s root. - 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 signedcommitof this root. - 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.
- 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.
Viewing links#
| 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 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 , 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 #. |