Protocol

The clearing conditions

The four conditions a clearing meets, exactly as the guest program checks them.

A clearing is valid when it meets four conditions. The solver searches for a result that meets them, the guest program checks them inside the zkVM, and the program verifies the proof of that check. All three use the same Rust crate for the arithmetic, so the numbers a solver posts, the program settles and the guest proves are the same numbers.

What is checked

The guest receives three things.

InputWhat it holds
The input recordsEvery order placed in or cancelled from the batch, in order. Their running hash is the batch's input hash.
The stateThe band, the clearing fee, each batch token's last proven price, and each batch pair's fee, tick spacing, price, tick, liquidity and initialized ticks. Its hash is the batch's state hash.
The resultOne price per batch token, the clearing fee collected per token, and up to 16 fill fractions. Its hash is the result hash.

The batch tokens are the tokens of the batch's orders plus any the solver adds, 16 at most. The batch pairs are every pair whose two tokens are both batch tokens. The program requires all of them and no others, so a solver cannot leave a pair's liquidity out of a batch.

The open orders of a batch are its placed orders less its cancelled ones.

Units

QuantityTypeMeaning
Priceu128, Q64.64Lamports per atom of the token. wSOL is token index 0 and its price is always 1 << 64.
Limitu128, Q64.64Least atoms of the buy token per atom of the sell token.
Fill fractionu64Out of FILL_ONE = 1 << 63.
Fee ratesu16Basis points.

Intermediate products are 256-bit. Every division rounds down unless a line says up.

The band

Every price is inside its token's band around the last proven price:

Text
lo = floor(last * (10000 - band_bps) / 10000)
hi = floor(last * (10000 + band_bps) / 10000)
lo <= price <= hi

The program checks this when the clearing is posted, and the guest checks it again.

1. Conservation

For every batch token, what the batch is supplied with covers what it pays out. Orders selling the token supply it, and so do pairs whose liquidity pays it out. Orders buying the token take it, and so do pairs whose liquidity takes it in.

Text
IN  = sum of filled        over orders selling the token
    + sum of net           over pairs paying the token out
OUT = sum of gross         over orders buying the token
    + sum of in            over pairs taking the token in

IN >= OUT
IN - OUT <= 2 * n + 2 + IN / 1,000,000

n counts the orders that sell or buy the token and the segments of the pairs it is in. The second line is the tolerance: a clearing may leave at most that many atoms of the token unspent.

The guest also checks the fee the result reports for the token: it equals the sum of fee over the orders buying that token.

2. Limits

An order fills only at its limit or better, and an order priced better than its limit fills in full unless its direction is rationed. The guest computes each order's fill from the price vector and the fractions by the rules on How fills are decided, so a result has no way to state a fill that breaks them.

3. Liquidity on its curve

Each batch pair ends where its liquidity, its fee and the price vector put it.

A pair of tokens x and y holds concentrated liquidity on ticks, with Q64.64 square-root prices. The pair's price is atoms of y per atom of x. The price vector gives the pair one square-root price, and the pair's fee gives one factor:

Text
sqrt_raw = isqrt((price(x) << 128) / price(y))
f        = isqrt(((10000 - fee_bps - 1) << 128) / 10000)

sqrt_raw is the cleared price of the pair. f is the square root of 1 less the pair's fee and one basis point more, in Q64.64. The pair moves from its current sqrt_price toward sqrt_raw and stops short of it by that factor:

Text
sqrt_raw > sqrt_price:   sqrt_target = max(floor(sqrt_raw * f / 2^64), sqrt_price)     the price rises
sqrt_raw < sqrt_price:   sqrt_target = min(ceil(sqrt_raw * 2^64 / f), sqrt_price)      the price falls
sqrt_raw = sqrt_price:   sqrt_target = sqrt_price

The pair trades only as far as the batch's price beats its own marginal price by its fee plus one basis point. A cleared price within that distance of the pair's price leaves sqrt_target at sqrt_price, and the pair trades nothing. The one basis point covers the rounding between the curve's amounts and the amounts at the cleared price.

The pair steps from sqrt_price to sqrt_target, one segment per stretch between initialized ticks. For a segment with active liquidity L, when the price rises the pair sells x and buys y:

Text
out     = the curve's change in x across the segment, rounded down
curve   = the curve's change in y across the segment, rounded up
fee     = floor(out * fee_bps / 10000)
net     = out - fee
in      = floor(net * price(x) / price(y)), or curve if that is larger
surplus = in - curve

When the price falls, x and y trade places: out and fee are in y, curve, in and surplus are in x, and in = floor(net * price(y) / price(x)), or curve if that is larger.

The pair pays out the sum of net and takes in the sum of in. It sells what it delivers at the cleared price, and with the move ending at sqrt_target that price covers what the curve asks. Each segment credits the positions active in it: fee in the token paid out and surplus in the token taken in, each as floor(amount * 2^64 / L) of fee growth.

surplus is the difference between trading along the curve and trading the whole move at the cleared price. In a pool that prices from its reserves, an arbitrageur collects that difference each time the price moves. Here the pair trades the move at the cleared price and the difference is credited to the positions. What a position earns follows one position through it.

The guest recomputes every pair's move from the state and the price vector and requires the result to match.

4. Maximal

The clearing fills as much as the batch allows inside the band. The guest checks it from the fill fractions:

  • For every token, either every rationed order selling it fills in full, or every rationed order buying it does. Both sides of a token are never held back at once.
  • A direction whose fraction is under FILL_ONE while it holds back orders that are in the money is pinned by the band in that direction: the buy token is at the top of its band, or the sell token at the bottom. wSOL has no band and never pins a direction.

With conservation inside its tolerance, a price vector that passes both is the market-clearing solution of the batch: the price at which supply and demand for every token balance across all orders and all liquidity at once. It is the dual solution of the optimal routing problem over the whole batch.

What the proof commits to

When all four hold, the guest commits 104 bytes of public values:

Text
batch_id: u64 LE  ||  input_hash: [u8; 32]  ||  state_hash: [u8; 32]  ||  result_hash: [u8; 32]

prove_batch reads the input hash and state hash from the batch, recomputes the result hash from the stored result, and verifies the Groth16 proof over those bytes. A proof made for another input, another state or another result does not verify. The guest program and verifying a batch yourself shows how to recompute each hash and run the check.

State that changes under a solver

A solver solves against the state it read, and passes that state's hash with its clearing. If a position was added or removed in between, the live state hashes differently and the program refuses the clearing with StateHashMismatch. The solver reads again and solves again.