Hadal
Start trading
  • OverviewStart
  • QuickstartStart
  • What is sealed and what is seenStart
  • Sealed balancesConcepts
  • Sealed ordersConcepts
  • The book and the pool's midConcepts
  • DealsConcepts
  • SoundingsConcepts
Concepts

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.

text
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:

ValueUnitMeaning
sidebid or askA bid buys base, an ask sells it.
limitpriceThe resting order's limit.
remainingbase atomsWhat it can still trade.
lockedquote atoms (bid), base atoms (ask)What its owner put up and has not yet paid.
proceedsbase 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:

text
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 <= mid

The computation checks every slot, in slot order, and fills against each one that qualifies until the incoming order has nothing left.

The fill

text
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.

text
the buyer pays       q + cross_fee   quote, and receives fill base
the seller delivers  fill base, and receives  q - cross_fee  quote

This 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:

text
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.

Next