• Reading the docs…
Start trading

Concepts

Crossing

A Crossing is one batch of the Pool’s trading. Whenever orders are sealed, as often as every 4 slots (about 0.8 s), the Coprocessor takes the Intents it holds, nets each pair at the oracle mid, fills opposing size against each other inside the Pool, sends only the net Residual to Jupiter, and closes the batch with one Commit.

The batch#

A Crossing goes on chain only when it has something to settle:

Work Counts when
A trade, cancel or Exit Intent intake accepted it since the last cutoff
A deposit its queue entry is past the last cut, to credit, or to refund when its note does not open
An Exit piece its release slot has come and the balance funds it
An expiry an open order’s expiry slot has passed
A resting order its limit lies within κ+β0\kappa + \beta_0, 75 bps, of Jupiter’s live price for the pair (β0\beta_0 is the route bound’s floor), checked every 25 slots (about 5 s)

Status and Receipt requests settle nothing and start no Crossing. With no work, nothing lands until 750 slots (about 2.5 minutes) after the last Commit, when the Coprocessor sends a heartbeat: open_crossing with no prices, one log_diff chunk and a Commit that carries no asset. It keeps the gap between Commits far inside the liveness window W=9,000W = 9{,}000 slots, so the gap measures the enclave’s liveness, not trading (Escape).

Crossing kk‘s cutoff t(k)t^{(k)} is the slot at which the Coprocessor begins it, never less than Δ=4\Delta = 4 slots after the last Commit landed: t(k)≥last_commit_slot+Δt^{(k)} \ge \texttt{last\_commit\_slot} + \Delta. While work waits, each Crossing begins as soon as Δ\Delta allows; after an idle stretch, at the slot work appears. An Intent the enclave has accepted before the cutoff is a candidate for Crossing kk; one that arrives later waits for k+1k+1, which begins Δ\Delta after Commit kk lands. Only one Crossing is open at a time: opening Crossing kk requires the program’s stored index to be k−1k-1 and Δ\Delta slots since the last Commit. The countdown the API serves gives the earliest cutoff an Intent sent now can make (Markets and prices).

Intake’s checks decide which Intents are eligible (Intent). Every account’s reservations are fixed before any pair runs, and a Crossing’s proceeds are credited after all pairs settle, ready to back new Intents from the next Crossing on.

The stages#

Stage Runs What it does
open_crossing on chain Reads the Pyth prices the batch needs, straight from the price accounts Pyth keeps on Solana: the pairs of its eligible Intents, and the USD marks of the assets its valid deposits credit. The program requires each account to be Pyth’s sponsored account for the asset’s feed, owned by the Pyth receiver and fully verified, marks each price valid or not by its age and confidence, stores price, confidence, exponent, publish time and validity with their hash, and records the opening enclave key.
Netting enclave Per pair, keeps the active Intents (buys with a limit at or above the mid, sells at or below it) and totals each side.
Clearing enclave Fixes the pair’s price at the mid the program stored, if the program marked it valid and it lies within κ\kappa of Jupiter’s live price.
Allocation enclave Fills the light side in full and shares the crossed size pro rata over the heavy side.
route_residual on chain One Jupiter swap per pair with a route-eligible remainder, from vault shard 0, inside the bound the enclave signs; the program measures and records the fill.
log_diff on chain Posts the Crossing’s ciphertext diff in chunks: rewritten leaves, decoys and per-asset proofs. The program folds them into an accumulator δ(k)\delta^{(k)}.
commit on chain Lands the new Ledger root, signed by the opening key, once the program has checked it against the stored mids, fills, deposits, δ(k)\delta^{(k)} and conservation of every asset. It pays the Crossing’s fees, in each pair’s quote asset, from vault shard 0 to the fee recipient.

The enclave crosses at the mids the program verified, read back from the Crossing’s state account. The on-chain stages run in order, each after the previous one confirms (about 150 ms under Alpenglow), with log_diff chunks going out as their inputs allow. The routes of one Crossing run one after another without waiting for confirmation between them. The shortest Crossing is about three slots plus the Jupiter round trips, and the next one opens no sooner than Δ\Delta after its Commit, so Crossings never overlap. If the opening enclave goes silent, a standby takes over under the Crossing lease.

A Crossing with no eligible Intent and no valid deposit to credit, a heartbeat among them, posts no prices and routes nothing: it runs open_crossing, the log_diff chunks of its diff and commit (What lands, per Crossing counts their transactions).

Clearing at the mid#

Each pair π=(a,q)\pi = (a, q) clears at one price, the Pyth price of aa in qq that open_crossing stored: pπ(k)=mπ(k)p^{(k)}_\pi = m^{(k)}_\pi. open_crossing reads it from the price accounts Pyth sponsors on Solana, which Pyth’s own pusher updates on a heartbeat of about a minute and on every move past the feed’s deviation threshold; Privium posts no price of its own. The pair trades only if three checks pass:

Check Made by Passes when
Age the program, at open_crossing each price was published no more than 75 seconds before the open, a bound set above Pyth’s one-minute heartbeat so a live feed passes
Confidence the program, at open_crossing each price’s confidence cc is tight, c/m≤κc/m \le \kappa with κ=25\kappa = 25 bps
Reference the enclave, before it crosses the mid lies within κ\kappa of Jupiter’s live price for the pair, which the enclave reads through its host

A pair that fails any check does not trade in that Crossing: neither crosses nor routes, and its Intents rest until it passes again, never filling against a stale price. The reference decides only whether a pair trades, never the price it clears at, so the most a host feeding a false one can do is make a pair skip a Crossing. A pair whose token has no Pyth sponsored feed routes its whole flow as the Residual.

The mid leaves the enclave no price to choose, and both sides of a cross save the same half-spread they would have paid the market.

With active buy size Q+Q^+ and active sell size Q−Q^-:

math
Xπ=min⁡(Q+,Q−),Rπ=Q+−Q−,Gπ=Q++Q−X_\pi = \min(Q^+, Q^-), \qquad R_\pi = Q^+ - Q^-, \qquad G_\pi = Q^+ + Q^-

XX is the crossed volume, RR the Residual (positive when the Pool buys base) and GG the active gross size. No allocation can cross more than XX, and every allocation that crosses XX fills the light side in full (Theorem 7.1).

Allocation#

The light side, the side with the smaller total, fills in full at the mid. The heavy side, with total QHQ_{\mathcal H}, shares XX in proportion to size:

math
fi=Xπ⋅xiQHf_i = X_\pi \cdot \frac{x_i}{Q_{\mathcal H}}

Fills are whole base units. Each heavy-side Intent takes the floor of its share, and the units left over go one each to the largest remainders, ties broken by H(σ(k) ∥ νi)\mathsf{H}(\sigma^{(k)} \,\|\, \nu_i), where σ(k)\sigma^{(k)} is a 32-byte seed the enclave draws at the cutoff and includes in the Commit. The fills add up to exactly XX, each is within one base unit of its exact share, and no choice of nonce can bias the tie-break.

Under pro rata a fill depends only on the eligible set: arriving earlier inside the batch gains nothing, and splitting an order or merging several leaves their total fill unchanged (Theorems 7.2 and 7.3). It is the only rule immune to both splitting and merging. Each heavy-side remainder xi−fix_i - f_i then joins the Residual if its limit clears the route’s worst admissible price, and otherwise rests until its expiry.

The crossing rate#

The crossing rate is the share of active gross size that never reaches the market:

math
γπ=2XπGπ∈[0,1],Gπ=2Xπ+∣Rπ∣\gamma_\pi = \frac{2X_\pi}{G_\pi} \in [0, 1], \qquad G_\pi = 2X_\pi + |R_\pi|

It sets what a Crossing saves. In the whitepaper’s cost model, measured against the mid with ff the per-unit DEX fee and hh the half-spread of public liquidity, the batch costs less through the Crossing than as separate swaps exactly when ϕ≤γπ(f+h)\phi \le \gamma_\pi (f + h) (Theorem 7.7). Price impact drops out of the comparison, because path-independent liquidity charges the same impact on the net as on the sum. A light-side trader pays less than trading alone whenever ϕ≤f+h\phi \le f + h.

ϕ\phi is the fee rate every fill pays, 0.10% (Fees).

What happens to one Intent#

The trader’s browser reads its own leaf at each Commit, checks its Merkle path against the root on chain and decrypts it; the crossed and routed parts of the fill come out of the balance change (Crossings and fills).

What each guarantee rests on#

Guarantee Rests on
Every fill is at a price no worse than its limit. Crosses happen at the mid only for Intents active there; routes only for limits that clear the bound, and the program reverts any swap outside it (Theorem 7.6).
Fills do not depend on arrival order inside the batch, or on splitting and merging orders. Pro rata allocation in the engine, whose measured build the Registry admits.
Every clearing price can be recomputed. open_crossing verifies and stores the mids, and the Commit binds their hash.
Pairs settle independently, in any order, and no balance goes below zero. Reservations fixed before any pair runs; each pair reads only its own Intents, its mid and the seed (Theorem 7.9).
An Intent formed before the cutoff can expect to gain at most κ\kappa of the price against the cross price. The batch is sealed before open_crossing reads the mid, and a pair crosses only within κ\kappa of a live price read after the seal (Proposition 7.12).