• Reading the docs…
Start trading

Concepts

Residual

The Residual is the part of a Crossing the Pool cannot fill inside itself: per pair, the net of active buy and sell size left after crossing. It reaches public liquidity as one Jupiter swap from vault shard 0, inside a slippage bound the enclave signs, and the program checks the outcome against the Pool’s own vault balances.

From net size to routed size#

After allocation, each heavy-side Intent ii has a remainder xi−fix_i - f_i, and the remainders add up to ∣Rπ∣|R_\pi|, where Rπ=Q+−Q−R_\pi = Q^+ - Q^- (Crossing). A positive RR means the Pool buys base, a negative one that it sells.

For each pair with R≠0R \neq 0, the Coprocessor takes a fresh Jupiter quote in the Residual’s direction and sets the bound βπ(k)\beta^{(k)}_\pi from it, never below the floor β0=50\beta_0 = 50 bps. The bound fixes the worst admissible prices around the mid mm:

math
pˉ+=m (1+β) for a buy,pˉ−=m (1−β) for a sell\bar p^{+} = m\,(1+\beta) \ \text{for a buy}, \qquad \bar p^{-} = m\,(1-\beta) \ \text{for a sell}

A remainder is route-eligible when its limit clears that price: ℓi≥pˉ+\ell_i \ge \bar p^{+} for a buy, ℓi≤pˉ−\ell_i \le \bar p^{-} for a sell. The routed size R~π\tilde R_\pi is the sum of the route-eligible remainders, so ∣R~∣≤∣R∣|\tilde R| \le |R|. A remainder that is not route-eligible rests, unfilled, for the next Crossing until its expiry.

The swap#

The Pool trades exact-input in both directions, so it always knows what it spends:

Residual Pool spends from vault shard 0 Pool receives at least
Sell, R<0R < 0 ∣R~∣\lvert \tilde R \rvert base units of aa ⌈∣R~∣⋅m(1−β)⌉\lceil \lvert \tilde R \rvert \cdot m(1-\beta) \rceil of qq
Buy, R>0R > 0 ⌈R~⋅m⌉\lceil \tilde R \cdot m \rceil of qq ⌈R~/(1+β)⌉\lceil \tilde R / (1+\beta) \rceil base units of aa

The route comes from Jupiter’s /swap/v2/build, which returns raw Metis-routed instructions with no Jupiter swap fee. The request names the Pool authority as taker and the output mint’s vault shard 0 as destination, with the relayer paying transaction fees, so the swap runs from one Pool vault to another and never through a wallet. Shard 0 is the authority’s associated token account, which lets Jupiter use it as source and destination directly.

Before it signs, the enclave checks that the instruction calls Jupiter, that Jupiter’s own minimum output is at least the bound, and that the only Pool token accounts in the route are the two shard-0 vaults. The relayer simulates the route; one that hits Solana’s CPI depth or instruction limits is rebuilt without the DEX that hit them.

What the enclave signs#

The enclave signs a Residual order with its signing key skCsk_C under the domain tag privium/route/v1. The order binds the Crossing index kk, the pair and input mint, the exact input, the minimum output, a deadline of slot t(k)+Δt^{(k)} + \Delta, and the route hash

math
hroute=H(Jupiter program id ∥ instruction data ∥ account keys)h_{\text{route}} = \mathsf{H}(\text{Jupiter program id} \,\|\, \text{instruction data} \,\|\, \text{account keys})

over exactly what the swap will invoke. The domain tag keeps a route signature from ever passing as a Commit or a Crossing open. The byte layout is in Signed messages.

What the program checks#

route_residual runs the swap, then trusts only what it can measure:

  1. The signature is by the key that opened Crossing kk, over an order naming kk, and the current slot is within the deadline.
  2. The program hashes the Jupiter program id, the instruction data and every account key it is about to invoke, and the result must equal the signed route hash. A relayer cannot substitute a route, and the authority’s signature reaches only accounts the enclave approved.
  3. The program invokes Jupiter, signing as the Pool authority, reloads both shard-0 vaults and measures: spent is the input vault’s drop, received the output vault’s rise.
  4. Spent must be at most the signed input and received at least the signed minimum, or the transaction reverts.
  5. The Crossing’s total spent of the input asset, with what a consolidation of that asset lost to a transfer fee in the same Crossing, must stay within that asset’s committed Ledger total, so committed Exits awaiting release and deposits not yet credited stay in the vault whatever a route does.
  6. The program records spent and received for the pair in the Crossing’s state account.

The check reads Pool-owned vaults before and after the swap, so it holds whichever DEXs the route passes through. A pair’s Residual that cannot be routed, because Jupiter returns no route for it or its swap does not land, leaves that pair’s routed remainders resting for the next Crossing, and the Crossing’s crossed fills commit as usual.

How the routed part is priced and allocated#

The enclave settles on the recorded fill, and the Commit binds the hash of every fill recorded for the Crossing, so the Ledger credits routed traders with exactly what the market delivered. Routed traders share the measured amounts in proportion to their routed remainders.

  • Buy Residual. The Pool spends the mid value of R~\tilde R and receives somewhat less base than R~\tilde R. Routed buyers share the base received; the shortfall rests or expires with their Intents.
  • Sell Residual. Routed sellers give ∣R~∣|\tilde R| of base between them and share the quote received.
  • Price. The average routed price lies inside [pˉ−,pˉ+][\bar p^{-}, \bar p^{+}], so every routed fill is within its limit, up to one base unit of rounding.
  • Crossed and routed together. An Intent with both parts pays the volume-weighted average of the mid and the routed price, each within its limit.
  • Fee. The routed part pays the same fee as a crossed fill, priced at the executed Residual price (Fees).

Order and exposure#

Each pair’s Residual is a separate swap. The routes of one Crossing all write its state account, so they land one after another, without waiting for confirmation between them, and a leader can place them in one block.

A Residual shows that the Pool traded a net amount in one pair in one Crossing. It names no wallet and no trader (What an observer sees). The signed minimum holds every routed fill to within β\beta of the mid whatever lands around the swap, so the routed part of a Crossing keeps all but at most β m ∣R~∣\beta\, m\, |\tilde R| of its mid value, against β m Gπ\beta\, m\, G_\pi for the same orders sent as separate swaps with the same tolerance (Theorem 7.11). Since ∣R∣=(1−γπ) Gπ|R| = (1-\gamma_\pi)\, G_\pi, that bound tightens as the crossing rate rises.