• Reading the docs…
Start trading

Concepts

Ledger

The Ledger holds every trader’s balances: one encrypted leaf per trader per asset, under a single Merkle root that the program stores and each Commit advances once per Crossing. The chain holds the root and each leaf’s commitment; the owner, the enclave and the Council each read a leaf through a layer of their own.

The tree#

The Ledger is a sparse binary Merkle tree of depth 32, with 2322^{32} positions. It hashes with SHA-256 under RFC 6962 domain separation (prefix 0x00 for a leaf, 0x01 for an interior node), so a leaf can never pass as a node. After Crossing kk, the root ρ(k)\rho^{(k)} sits in the program’s Ledger root account beside kk and the slot of the last Commit.

Two kinds of leaf share the tree. A trader record, one per trader, holds the trader’s private account index, the five keys of its registration (auth key, viewing root, escape key, owner-tag salt and reply key) and its nonce watermark, encrypted under the Ledger data key, so only an admitted enclave reads it. Every record is 197 bytes, written when the account first enters the Ledger and rewritten only when its watermark moves. A balance leaf, one per trader per asset, holds a balance. The enclave knows each trader by its private index, which never moves, so a leaf changing position changes nothing about whose it is.

Every write places a leaf at a position drawn uniformly at random among the free ones and empties the position it held, so a position says nothing about arrival order or a leaf’s earlier versions. The Ledger’s on-chain footprint does not grow with traders: it is the root account and a fixed state per asset. The leaves live in Solana’s transaction history, posted through log_diff.

A balance leaf#

The balance bb of trader uu in asset aa is a twisted ElGamal ciphertext under the Council key PCP_{\mathcal{C}}, whose first half is a Pedersen commitment:

math
C=b G+r H,D=r PCC = b\,G + r\,H, \qquad D = r\,P_{\mathcal{C}}

rr is fresh at every write. GG and HH are the generators of Solana’s ZK ElGamal stack, so the commitments are byte-compatible with its proof program. CC hides bb perfectly, binds it under the discrete logarithm assumption in ristretto255, and adds: one group equation checks the sum of an asset’s leaves against a total.

A balance leaf is exactly 225 bytes:

Field Bytes Holds
Kind and asset index 1 + 4 the leaf’s type and its asset, public so each asset’s leaves sum against that asset’s vault
Version 8 the index of the Crossing that wrote the leaf
Owner tag ψ\psi 32 a hiding commitment to the owner’s escape key, salt, mint and version, fresh at every version, opened only in the owner’s Escape request
Commitment CC 32 the Pedersen commitment to bb
Council handle DD 32 with CC, the ciphertext the Council decrypts
Enclave ciphertext 60 AES-256-GCM under the Ledger data key kLk_L: the trader’s account index, bb and rr
Owner ciphertext 56 AES-256-GCM under the owner leaf key ku,ak_{u,a}: bb and rr

Both AES-256-GCM layers take the leaf’s public part (program id, position, kind, asset, version, owner tag, CC, DD) as associated data, so neither opens once moved to another leaf, position, version or deployment. Each nonce is the leaf’s position and version, a pair that never recurs under one key. Balances are integers in [0,264)[0, 2^{64}).

Who reads what#

Reader Key Reads
Anyone none the root; each leaf’s asset, version, CC and DD; per asset, the total the vault already shows
The owner ku,ak_{u,a}, derived from the viewing root, which one wallet signature derives their own balances and openings, checked against CC
A Viewing key holder the keys the owner hands over exactly the scope those keys cover (Viewing key)
The Coprocessor kLk_L, which the Council releases only to admitted enclaves every leaf and record, in enclave memory
The Council tt of nn shares of the secret behind PCP_{\mathcal{C}} a leaf its owner claims in an Escape, to that owner alone

The Council’s threshold decryption yields C−sD=bGC - sD = bG, which confirms the value a claim states; it never has to search for bb. Fewer than tt members together learn nothing. Each Commit publishes the sum of an asset’s openings, which reveals that asset’s total and nothing more.

How a leaf changes#

A leaf changes only inside a Crossing, in the enclave, and the change lands with that Crossing’s Commit. A deposit credit raises a leaf, a fill moves the trader’s base and quote leaves, and a fee or an Exit lowers one. Every debit needs an Intent or Exit request its owner signed (Intent), every balance stays in [0,264)[0, 2^{64}), and for every asset the deltas sum to the public flows:

math
∑uΔu,a(k)=Da(k)+Φa(k)−Xa(k)−Fa(k)−La(k)\sum_{u} \Delta^{(k)}_{u,a} = D^{(k)}_a + \Phi^{(k)}_a - X^{(k)}_a - F^{(k)}_a - L^{(k)}_a

that is, the deposits credited, plus the net flow of the Crossing’s recorded Residual fills, minus the Exits listed for the first time, the fees charged and what a consolidation of the asset lost to a transfer fee, all five recorded by the program.

The Crossing rewrites every leaf with a nonzero delta, every record whose watermark moved, and decoys drawn from the asset’s other live leaves, so that at least m0=64m_0 = 64 leaves of each carried asset are rewritten (What an observer sees). Each rewritten leaf gets fresh randomness (C+ζH, D+ζPC)(C + \zeta H,\ D + \zeta P_{\mathcal{C}}), a new owner tag, new ciphertexts and a fresh random position, so an observer cannot tell a changed leaf from a decoy or follow one from position to position.

Data availability through log_diff#

Before signing a Commit, the Coprocessor posts the Crossing’s diff on Solana. It carries:

  • the previous and new roots, and the deposit cuts: how far each vault shard’s deposit queue in each asset is credited;
  • every rewritten position with its new leaf, balance leaves and trader records alike, and every position the Crossing emptied;
  • per asset, the commitment delta, the aggregate opening, and the proofs that each rewritten leaf is a well-formed ciphertext of an in-range balance;
  • the encrypted entries, one per deposit credit, fill, fee and Exit, that account history and Viewing keys decrypt;
  • the Crossing’s crossed and routed notional in USD.

The diff goes up in chunks of up to 3,700 bytes, one log_diff instruction each, and the program folds them in order into an accumulator in the Crossing’s state account:

math
δk,0=H(privium/da/v1 ∥ idprog ∥ k),δk,j+1=H(δk,j ∥ j ∥ chunkj)\delta_{k,0} = \mathsf{H}(\texttt{privium/da/v1} \,\|\, \mathsf{id}_{\mathrm{prog}} \,\|\, k), \qquad \delta_{k,j+1} = \mathsf{H}(\delta_{k,j} \,\|\, j \,\|\, \mathsf{chunk}_j)

A chunk out of order is rejected. The Commit carries δk\delta_k in its signed message and is accepted only if that value equals the accumulator, which it then seals. An accepted Commit therefore means the diff the enclave signed is exactly the logged chunks in order, under the collision resistance of SHA-256.

Every committed Ledger state, every root and every inclusion proof can be rebuilt by anyone from Solana’s transaction history alone, without the Coprocessor. Privium’s indexer replays the diffs, checks each root against the Ledger root account and each diff against δk\delta_k, and stops serving any Crossing whose data does not reproduce the root on chain. Its store is a cache of the chain.

What stays off the diff#

The enclave’s working state is no part of the diff: each account’s open orders, its scheduled Exit pieces, the Intents intake has accepted, and the accounting frame of every Crossing that Receipts are computed from. The Coprocessor keeps it outside the enclave as a checkpoint encrypted under kLk_L, written after each Commit and bound to that Commit’s Crossing and root. An enclave takes up a checkpoint only once the public diffs it has replayed reach that same root on chain, so the working state it answers from always continues a committed root. An account reads its own part of it, open orders and Exit pieces, through a status Intent, answered to the account alone (Intent kinds).

Reading your own balances#

The browser reads each balance from the account’s current leaves and checks it against the chain before showing it:

  1. From the account’s one wallet signature, the SDK derives the viewing root, each asset key and each owner leaf key ku,ak_{u,a}.
  2. It asks the enclave, in a status Intent answered sealed to the account alone, for the positions of the account’s balance leaves under the root it last committed.
  3. It reads ρ(k)\rho^{(k)} from the Ledger root account on chain, and requires the enclave’s answer to name the same root.
  4. It fetches the leaves at those positions, each with its 32 sibling hashes, from the public leaf route (POST /v1/ledger/leaves), recomputes the root from each leaf and its siblings in the order the bits of the leaf’s position give, and compares it with ρ(k)\rho^{(k)}.
  5. It decrypts the owner ciphertext with ku,ak_{u,a}; the GCM tag authenticates it against the leaf’s public part.
  6. It checks C=bG+rHC = bG + rH with the opening it just decrypted.

The read touches only the account’s own current leaves, so it costs the same however many Crossings the Ledger has committed, and a new device needs only the wallet. The leaf request names positions and a root; the account reaches only the enclave, sealed. A mirror that serves an altered or outdated leaf fails step 4 or step 5, so no mirror needs trust. While the Escape is active the root is frozen, and a device without a snapshot at that root rebuilds the Ledger from the public diffs and checks the rebuilt root against the frozen one (Claiming a balance). The enclave, the SDK and an Escape claim compute the root with the same function. Your account and keys shows where this runs in the app, and readBalances gives each request.