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.
| Input | What it holds |
|---|---|
| The input records | Every order placed in or cancelled from the batch, in order. Their running hash is the batch's input hash. |
| The state | The 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 result | One 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
| Quantity | Type | Meaning |
|---|---|---|
| Price | u128, Q64.64 | Lamports per atom of the token. wSOL is token index 0 and its price is always 1 << 64. |
| Limit | u128, Q64.64 | Least atoms of the buy token per atom of the sell token. |
| Fill fraction | u64 | Out of FILL_ONE = 1 << 63. |
| Fee rates | u16 | Basis 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:
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.
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,000n 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:
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:
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:
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_ONEwhile 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:
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.