The book and the pool's mid
How the pool's reserves set the one price every cross uses, which resting orders a new order crosses, and what each side pays and receives.
A market has one sealed book and one sealed pool, stored together and encrypted to the cluster alone. The book holds the resting dark orders. The pool holds the liquidity. Every cross in the book happens at one price, the pool's mid, and that price is read from the pool inside the same computation that fills the order.
The pool's mid
The mid is the ratio of the pool's two reserves.
mid = floor(pool_quote * 2^32 / pool_base)It is a price in the market's unit: quote atoms per base atom, times 2^32. See Units. The reserves are sealed, so the mid is sealed too. It is computed afresh at the start of every order's computation, from the reserves as the previous computation left them.
The product is taken in 128 bits and the mid must fit 64. While it does not, every order is void: see How an order is processed.
The mid has no spread. A buy and a sell that cross trade at the same price.
Why the price needs no oracle
The price of a cross is not brought in from outside the market. The computation that processes an order receives the book, and the pool's reserves are part of it. The mid is derived from those reserves and used in the same computation, before anything is written back. No account, feed or party supplies a price, and nobody sees the one that was used.
The only price the chain shows is the mid revealed at each sounding.
How the mid moves
The mid changes only when the reserves change, and three things change them:
- A sweep. A swap's remainder trading against the curve adds one token to the pool and takes the other out. This is the only trade that moves the price.
- Adding liquidity. Both tokens enter in the pool's ratio.
- Removing liquidity. Both tokens leave in the pool's ratio.
Adding and removing change the pool's depth and keep its ratio, up to the rounding of one atom. Their formulas are in Liquidity.
A cross moves no reserve, whatever its size. Neither does resting, collecting, cancelling, a deal, a deposit or a withdrawal. A dark order therefore fills with no price impact, and a block that crosses in full leaves the mid exactly where it was.
The book's slots
The book has a fixed number of slots, each holding one resting dark order. The count is in Limits. A slot holds five sealed values:
| Value | Unit | Meaning |
|---|---|---|
side | bid or ask | A bid buys base, an ask sells it. |
limit | price | The resting order's limit. |
remaining | base atoms | What it can still trade. |
locked | quote atoms (bid), base atoms (ask) | What its owner put up and has not yet paid. |
proceeds | base atoms (bid), quote atoms (ask) | What it has received and its owner has not yet collected. |
Which slots are taken is public: the market's account lists, for each slot, the sequence number of the order resting there. What a slot holds is not.
A dark order takes a slot only if something of it rests. It is assigned the lowest free slot when it is processed. If it crosses in full, or is void, the slot stays free and the order is closed. An order that does rest holds its slot until it is cancelled, by its owner or, after its expiry, by anyone. Every dark order has an expiry at most a day ahead, so every slot can be freed within a day: see Expiry.
When every slot is taken, a dark order reaching the head of the queue is returned: see Orders closed without a computation.
Crossing
An order crosses when it is processed, as the step before it sweeps or rests. Both swaps and dark orders cross. A resting order is crossed only by an order being processed: two resting orders do not trade with each other.
The incoming order crosses a resting order when all three hold:
the resting order is on the opposite side
the incoming limit admits the mid: buy: mid <= limit sell: mid >= limit
the resting limit admits the mid: bid: limit >= mid ask: limit <= midThe computation checks every slot, in slot order, and fills against each one that qualifies until the incoming order has nothing left.
The fill
fill = min(incoming remaining, resting remaining)
q = floor(fill * mid / 2^32)fill base trades for q quote. The price is the mid for both sides, whatever their limits. A limit decides whether an order trades, never the price it trades at.
What each side pays
Each side pays the cross fee on q, in quote. Its rate and rounding are in Fees.
the buyer pays q + cross_fee quote, and receives fill base
the seller delivers fill base, and receives q - cross_fee quoteThis holds whichever of the two is resting. The two fees, 2 * cross_fee, are added to the market's sealed protocol fees. The quote crossed, q, is added to the crossed volume of the current sounding interval.
Proceeds of a resting order
The incoming order settles into its owner's balance in the same computation. The resting order settles inside its slot:
resting ask: remaining -= fill
locked -= fill
proceeds += q - cross_fee (quote)
resting bid: remaining -= fill
locked -= q + cross_fee
proceeds += fill (base)Proceeds accrue in the slot across every cross, sealed. The owner of a resting order is not a party to the transaction that crosses it and its balance is not written. Collect moves the proceeds to the balance and Cancel moves the proceeds and whatever is still locked: see Collect and cancel.
The pool under the book
The book and the pool serve one order in sequence. A swap first takes whatever the book offers at the mid, with no price impact, and only its remainder reaches the curve, where it moves the price. A dark order takes the same crosses and leaves the rest waiting at the mid for the next order on the other side. The pool prices both and fills what the book cannot: see Liquidity.