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 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 , the root sits in the program’s Ledger root account beside 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 of trader in asset is a twisted ElGamal ciphertext under the Council key , whose first half is a Pedersen commitment:
is fresh at every write. and are the generators of Solana’s ZK ElGamal stack, so the commitments are byte-compatible with its proof program. hides 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 | 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 | 32 | the Pedersen commitment to |
| Council handle | 32 | with , the ciphertext the Council decrypts |
| Enclave ciphertext | 60 | AES-256-GCM under the Ledger data key : the trader’s account index, and |
| Owner ciphertext | 56 | AES-256-GCM under the owner leaf key : and |
Both AES-256-GCM layers take the leaf’s public part (program id, position, kind, asset, version, owner tag, , ) 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 .
Who reads what#
| Reader | Key | Reads |
|---|---|---|
| Anyone | none | the root; each leaf’s asset, version, and ; per asset, the total the vault already shows |
| The owner | , derived from the viewing root, which one wallet signature derives | their own balances and openings, checked against |
| A Viewing key holder | the keys the owner hands over | exactly the scope those keys cover (Viewing key) |
| The Coprocessor | , which the Council releases only to admitted enclaves | every leaf and record, in enclave memory |
| The Council | of shares of the secret behind | a leaf its owner claims in an Escape, to that owner alone |
The Council’s threshold decryption yields , which confirms the value a claim states; it never has to search for . Fewer than 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 , and for every asset the deltas sum to the public flows:
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 leaves of each carried asset are rewritten (What an observer sees). Each rewritten leaf gets fresh randomness , 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:
A chunk out of order is rejected. The Commit carries 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 , 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 , 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:
- From the account’s one wallet signature, the SDK derives the viewing root, each asset key and each owner leaf key .
- 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.
- It reads from the Ledger root account on chain, and requires the enclave’s answer to name the same root.
- 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 . - It decrypts the owner ciphertext with ; the GCM tag authenticates it against the leaf’s public part.
- It checks 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.