• Reading the docs…
Start trading

Concepts

Viewing key

A Viewing key opens part of a trader’s own Ledger history to a reader the trader chooses. Keys form a tree derived from the account’s viewing root, and a viewing bundle hands over exactly the nodes that cover one scope: the whole account, one asset, one asset over a period, or a single entry.

What a Viewing key opens#

Each deposit credit, fill, fee and Exit is an entry the Coprocessor writes into the diff of the Crossing that commits it, encrypted under that entry’s own key. A deposit credit and an Exit sit under their asset, a fill under its pair’s base asset, and the fill’s fee under its pair’s quote asset. The diff is published on Solana through log_diff and sealed by the Commit through its data availability digest. Each balance leaf of the Ledger also carries an owner component encrypted under the leaf key ku,a=F(vku,a,"balance")k_{u,a} = \mathsf{F}(vk_{u,a}, \texttt{"balance"}). Viewing keys derive both kinds of key. The leaf’s Council handle serves only the Escape and never a disclosure.

The key hierarchy#

Below the root, every key derives from its parent with F\mathsf{F}, HMAC-SHA-256 used as a pseudorandom function, so keys derive only downward: no node reveals its parent or its siblings.

Level Key Derived as
Viewing root vkuvk_u HKDF(σu,"privium/view/v1")\mathsf{HKDF}(\sigma_u, \texttt{"privium/view/v1"}), from the account’s one wallet signature σu\sigma_u
Asset vku,avk_{u,a} F(vku,"asset" ∥ a)\mathsf{F}(vk_u, \texttt{"asset"} \,\Vert\, a) for the mint aa
Period tree node v0,v1v_0, v_1 F(v,0)\mathsf{F}(v, 0) and F(v,1)\mathsf{F}(v, 1) for each node vv, from vku,avk_{u,a} down to depth 40
Epoch vku,a,evk_{u,a,e} the tree leaf at the 40-bit path equal to epoch ee
Entry ku,a,e,jk_{u,a,e,j} F(vku,a,e,"entry" ∥ j)\mathsf{F}(vk_{u,a,e}, \texttt{"entry"} \,\Vert\, j) for the entry’s index jj in that Crossing’s diff

An epoch is one Crossing, so period keys are exact to the Crossing, and 2402^{40} epochs never fill at any batch interval. Each entry is sealed with AES-256-GCM under the associated data (idprog,a,e,j,H(pkauth),v)(\mathsf{id}_{\mathrm{prog}}, a, e, j, \mathsf{H}(pk_{\mathrm{auth}}), v): the program, the mint, the Crossing, the index, the SHA-256 of the account’s auth public key and the root version vv. A ciphertext moved to another position, account or version no longer decrypts.

The viewing root rebuilds on any device from the wallet alone, beside the account’s other keys (Your account and keys). The SDK seals vkuvk_u to the enclave’s attested key in the account’s registration, sent before its first Intent, and in every deposit’s note. The enclave keeps it in the trader’s record and encrypts each new entry under that tree. It already reads balances in plaintext to run a Crossing, so holding vkuvk_u adds nothing to what it reads.

Scopes#

Scope Key handed over Size Opens
Whole account vkuvk_u 32 bytes every entry and balance leaf in every asset, entries written later included
One asset vku,avk_{u,a} 32 bytes every entry and the balance leaf of that asset, entries written later included
One asset over a period the covering nodes of that asset’s period tree at most 78 nodes the asset’s entries in exactly those Crossings
One entry ku,a,e,jk_{u,a,e,j} 32 bytes that entry alone

For a period [e0,e1][e_0, e_1] the SDK picks the minimal set of tree nodes whose subtrees cover exactly those epochs and no others. The set never exceeds 2D−2=782D - 2 = 78 nodes at depth D=40D = 40.

Viewing bundles at /v#

A viewing bundle holds the program id, the owner hash H(pkauth)\mathsf{H}(pk_{\mathrm{auth}}), the root version, the scope and its nodes, each a position in the tree (a prefix and a depth) with its 32-byte key, and the Crossings of the scope that hold the account’s entries, as ordered ranges. disclose in the SDK builds one, and its link carries it after /v#, which browsers never send to a server.

The ranges come from the enclave. It records which Crossings hold each account’s entries, under which asset, and reports them only in the account’s status, which a status Intent signed by the auth key requests and which is sealed to the account’s reply key. disclose asks for the scope’s span and asset, and the bundle carries the answer, so a reader fetches the diffs of those Crossings alone instead of every Crossing in the scope. The keys reach every entry of the scope, and the ranges name the Crossings that held entries when the bundle was built; a bundle built later names the Crossings committed since.

The SDK’s reader, readBundle, which /v runs in the reader’s browser, takes nothing on trust:

  1. The bundle. Its nodes must match its scope: one node at the top of the tree for an account or an asset, one node at depth 40 on the entry’s Crossing for one entry, and for a period up to 80 nodes that tile its Crossings exactly, with no gap, no overlap and nothing outside. Its ranges must be ordered, apart from one another, and inside a period’s span or on an entry’s Crossing. Any other bundle is malformed.
  2. Each diff’s Commit. It reads the Pool’s Ledger diffs of the Crossings the bundle lists, in Crossing order, up to 24 a page, asking for each by number (Ledger leaves and proofs). For each one, the root record must name the same root, the bundle’s program and the diff’s Crossing, and the root is pinned to its Commit transaction, read through the API’s RPC relay: a successful commit for that Crossing, directly after an Ed25519 verification of a valid signature over the Commit message naming the program, the Crossing, the root and the diff digest.
  3. Each diff’s bytes. The diff’s chunks must join into the diff served, their data availability accumulator must equal the digest the Commit signed (Data availability through log_diff), and the decoded diff must name the same root, Crossing and previous root. Where two Crossings on a page are consecutive, the later one’s previous root must be the earlier one’s root.
  4. Each entry. An entry outside the scope, in another asset, outside the period or the bundle’s ranges, at another position or under another root version, is passed over. Inside it, the entry key derives from the node above it, and the entry opens under its associated data with the bundle’s owner hash; an entry of another account fails authentication and is passed over.

A diff that fails step 2 or 3 stops the read. What the reader returns are entries the program accepted, each from a diff an accepted Commit sealed, with a cursor to the next page (readBundle).

What a holder can and cannot read#

A holder reads the plaintext of every entry the scope covers, and with a whole-account or asset key derives the balance leaf keys as well. Everything else stays encrypted to them:

Out of reach Why
Entries outside the scope, in any asset or period Keys derive only downward, so the bundle yields no key outside its own subtrees, and an entry under a key the reader never had is indistinguishable from a random one (security of F\mathsf{F} as a PRF and of the entry encryption)
Entries after a period ends Later epochs sit under tree nodes the reader was never given, so a period bundle keeps opening that period and nothing after it
Other accounts Each account’s tree hangs from its own root, and each entry’s associated data names its account
Open orders and scheduled Exit pieces They are no entries: the enclave keeps them in its private working state, off the diff (What stays off the diff), and returns them only to a status Intent the account’s auth key signs, sealed to the account’s reply key
Acting on the account A Viewing key signs no Intent, moves no token and claims no Escape: the auth and escape keys are separate derivations

A Viewing key discloses data. To state a fact about the data instead, such as a result over a span without the entries behind it, the trader issues a Receipt.