• Reading the docs…
Start trading

Concepts

Escape

The Escape is the way out of the Pool that needs no enclave. If no Commit lands for more than WW = 9,000 slots (about 30 minutes), anyone can open it, and every owner takes their last committed balance out of the vaults with the Council’s re-encryption shares and their own escape key.

When it opens#

The Coprocessor commits each Crossing that settles something and, with nothing to settle, sends a heartbeat Commit 750 slots after the last (The batch). A live enclave keeps the gap to about 750 slots at most, so the gap since the last Commit measures the enclave’s liveness, not trading activity. WW spans twelve heartbeat intervals and is far longer than the few transactions a Coprocessor failover takes, so neither a quiet Pool nor a routine failover opens it.

Once the current slot passes the last Commit’s slot plus WW, any account can call trigger_escape. Privium’s keeper calls it as soon as the window passes. Trust shows the last Commit slot and the slots left until an Escape could open.

What the trigger fixes#

trigger_escape puts the Pool in Escape mode and writes EscapeState:

Fixed at trigger What it is
Frozen root ρ(k⋆)\rho^{(k^\star)} The Ledger root of the last accepted Commit, Crossing k⋆k^\star. Every request proves its leaf against it.
Last Commit and trigger k⋆k^\star, the slot its Commit landed and the slot of the trigger.
Council epoch The Council whose shares every request takes.
Recorded fills If Crossing k⋆+1k^\star + 1 was open with Residual legs already executed, each leg’s input mint, output mint and measured amounts spent and got. The program caps what one Crossing spends of an asset at TaT_a, so these always settle.

Each asset’s Ledger total TaT_a and each shard’s deposit cut stay in the asset’s state where the last Commit wrote them; no Commit lands after the trigger, so they hold for the whole Escape. From then on the program rejects every Commit, open_crossing, consolidate_vault, route_residual and deposit. Intents and exit requests not yet in a committed root carry no tokens and lapse, and the balances they would have changed are paid as committed.

The queues settle#

Two public queues settle through permissionless instructions, which the keeper cranks and anyone can call:

  • Deposits not yet credited. refund_deposit returns each queue entry past the cut to the source token account the entry records.
  • Exits already committed. release_exit keeps paying every Exit listed in a committed exits root, exactly as before the trigger (Exit).

Claiming a balance#

  1. Request. The SDK’s requestEscape takes the owner’s leaf in that asset, with its Merkle path, from a balance snapshot at the frozen root: the one the device already holds, or else a rebuild of the whole Ledger from the public diffs up to Crossing k⋆k^\star, whose root it checks against the frozen root in the Ledger root account. It checks that the snapshot’s root is the frozen root and that the leaf’s owner tag is the owner’s, then hands the 225-byte leaf, its index, the path and the tag’s opening (Yu,ςu)(Y_u, \varsigma_u), the escape public key and the owner salt, to the API’s relay. The relay checks the path against the frozen root again and submits escape_request with the keeper’s key as fee payer. The program checks that the leaf is a balance leaf of the named asset, verifies the path to ρ(k⋆)\rho^{(k^\star)}, recomputes the tag from the opening, the mint and the leaf’s version, and opens an EscapeRequest at an address derived from the leaf index and the mint. It holds the leaf’s commitment CC, its Council handle DD and YuY_u. One request opens per leaf and asset, and the relay answers a repeated request with the one already open. The leaf is already public in its Commit’s diff, so the request adds only the opening.
  2. Shares. Each Council member’s node watches the chain for open requests and posts its re-encryption share of DD toward YuY_u with escape_share, bound to the program and the request’s address (What the Council does). The program checks each share’s proof against that member’s verification key, takes one share per member under the request’s Council epoch, and at the tt-th valid share stores the combined pair (A,B)(A, B).
  3. Claim. The SDK’s claimEscape reads the EscapeRequest from chain, checks its address and that its pair is combined, and takes the balance bb from the owner’s own decrypted leaf. It checks bG=(C−B)+yuAbG = (C - B) + y_u A and makes the proof that log⁡GYu=log⁡AZ\log_G Y_u = \log_A Z for Z=bG−(C−B)Z = bG - (C - B), which only the holder of yuy_u can make, and only for the true bb. The proof’s context holds the program, the request, its mint and the destination, so whoever submits the claim cannot redirect it. The relay submits escape_claim with the keeper’s fee payer, one group of accounts for each asset the payout touches, and creates the destination’s token accounts where they are missing.
  4. Pay. The program recomputes ZZ, verifies the proof, pays by the settlement rule below, marks the request claimed and creates the PaidRecord for the leaf and asset, whose existence blocks a second claim. Each amount leaves vault shard 1 first and shard 0 for the rest: SOL as lamports to the destination address, any other token to the destination’s token account for that mint.

The SDK’s watchEscape follows a request from requested through collecting and claimable to paid, the progress GET /v1/escape/requests/{address} serves. Neither the request nor the claim carries a signature of the owner’s or takes a wallet prompt: the request needs only the leaf and its opening, and the claim is authorized by its proof. The calls are members of Privium, and the relay is on Escape requests and claims.

The escape key comes from the same wallet signature as every other key of the account (Your account and keys), so a trader who keeps their wallet keeps their way out. In the app, Account’s Escape panel shows the request’s progress (The Escape).

The settlement rule#

A claim of bb units of asset aa pays

math
⌊b Ta−SaTa⌋ units of a,⌊b gotℓTa⌋ units of out(ℓ) for each recorded leg ℓ that spent a\Big\lfloor b\,\frac{T_a - S_a}{T_a} \Big\rfloor \text{ units of } a, \qquad \Big\lfloor b\,\frac{\mathrm{got}_\ell}{T_a} \Big\rfloor \text{ units of } \mathrm{out}(\ell) \text{ for each recorded leg } \ell \text{ that spent } a

where SaS_a is the total the recorded legs spent of aa, plus what a consolidation of aa in the open Crossing lost to a transfer fee. With Sa=0S_a = 0, as when no Crossing is open, the claim pays bb units of aa. Otherwise every holder of aa takes a share of the open legs in proportion to committed balance. Each leg’s rate gotℓ/spentℓ\mathrm{got}_\ell / \mathrm{spent}_\ell is its executed price, which the enclave’s signed bound keeps close to the oracle mid (Residual), so each claimant receives their committed balance in value at that price. The floors only round down.

Why every owner is paid their last committed balance#

At trigger each vault holds exactly what the Escape owes. From the conservation check at committed roots (Commit) and the recorded legs,

math
Va=Ta+Xa+Padep−Sa+∑ℓ: out(ℓ)=agotℓV_a = T_a + X_a + P^{\mathrm{dep}}_a - S_a + \sum_{\ell :\, \mathrm{out}(\ell) = a} \mathrm{got}_\ell

with XaX_a the committed Exits not yet released and PadepP^{\mathrm{dep}}_a the deposits not yet credited. Refunds pay exactly PadepP^{\mathrm{dep}}_a, committed Exits exactly XaX_a, and claims at most the rest. In Escape mode nothing else moves a vault.

Guarantee Rests on
A claim is for the leaf’s committed balance, exactly the Merkle path to ρ(k⋆)\rho^{(k^\star)}, the share and claim proofs, and Commit authenticity, under which every leaf’s handle encrypts its committed balance
A payout goes only to a destination the holder of yuy_u chose the discrete-log assumption, and the destination inside the proof’s context
Each leaf and asset is paid at most once the PaidRecord created in the payout’s own transaction
Every claim, refund and committed Exit is payable the vault identity above, with claims in aa summing to at most TaT_a
Every owner who requests is paid tt Council members landing their shares on chain

The first four hold with every Council member acting against the owners. Custody in the Escape rests on the chain, the frozen root, the published proofs and the owner’s key, and the Council supplies availability. Anyone can re-verify every share and claim from chain data (Checking an Escape’s shares).

The shares posted for an owner reveal nothing about the balance to anyone without yuy_u, and owners who never claim keep their balances confidential. A claimed amount appears on chain as a vault transfer, as an Exit does.