Trade

How fills are decided

From a batch's price vector to what one order receives, step by step.

A batch's clearing is a price vector and a few fill fractions. Every order's fill follows from those and the order's own fields, so anyone can compute it, and the program settles each order the same way.

The numbers involved

From the order

amountu64
Atoms of the sell token the order offers.
limitQ64.64
The least atoms of the buy token the order accepts per atom of the sell token.

From the batch

price(sell), price(buy)Q64.64
The cleared prices of the two tokens, in lamports per atom.
fraction(sell, buy)u64
The fill fraction for this direction, out of FILL_ONE = 1 << 63. A direction with no entry has fraction 0.
clearing_fee_bpsu16
The clearing fee, in basis points of the order's output.

A Q64.64 number is an integer that stands for itself divided by 2^64. Every division below rounds down.

Step 1: where the order stands

Compare the rate the batch gives with the order's limit. The rate for selling one token for another is price(sell) / price(buy). The program compares without dividing:

Text
price(sell) << 64    against    limit * price(buy)
ResultThe order isIt fills
greaterin the moneyin full, unless its direction is rationed
equalat its limitby the direction's fraction
lessout of the moneynothing

Step 2: whether it is rationed

Most orders that are in the money fill in full. Two kinds fill by a fraction:

  • An order exactly at its limit. Orders at the margin share what the batch has left for their direction.
  • An order in the money in a direction the band has pinned: the buy token is priced at the top of its band, or the sell token at the bottom of its band. The price would have moved further to balance the batch, the band stopped it, and the orders on the heavy side share what the other side offers.

Every rationed order in one direction gets the same fraction.

Text
filled = amount                                   // in the money, not rationed
filled = floor(amount * fraction / FILL_ONE)      // rationed

Step 3: what it receives

Text
gross = floor(filled * price(sell) / price(buy))
fee   = floor(gross * clearing_fee_bps / 10000)
net   = gross - fee

net atoms of the buy token go to the owner. amount - filled atoms of the sell token are the remainder.

A worked order

An order sells 1 SOL for a token with 6 decimals and accepts at least 190 of it. In atoms: amount = 1,000,000,000 lamports, and the limit is 0.19 atoms per lamport.

The batch clears the token at 5 lamports per atom, which is 200 tokens per SOL. wSOL's price is 1. The example uses a clearing fee of 5 basis points.

StepArithmeticResult
Standing1 against 0.19 × 5 = 0.95in the money
Rationedthe token is not at the top of its bandno, fills in full
Filledthe whole amount1,000,000,000 lamports
Gross1,000,000,000 × 1 / 5200,000,000 atoms
Fee200,000,000 × 5 / 10000100,000 atoms
Net200,000,000 − 100,000199,900,000 atoms, 199.9 tokens

Had the batch cleared the token at 5.5 lamports per atom, the rate would be 0.1818 atoms per lamport, under the limit of 0.19, and the order would not fill in that batch.

Orders between two tokens nobody else pairs

Prices are per token, and a clearing balances each token on its own: across the batch, what is paid in of a token covers what is paid out of it. An order from token A to token C fills when the batch has A wanted somewhere and C offered somewhere. One order may take the A and sell SOL, another may sell C for SOL, and a liquidity position may stand between. All of them trade at the one price vector, so the rate from A to C is price(A) / price(C) whatever path the tokens took.

The remainder

An order that fills in part, or not at all, keeps its remainder. When the order is settled, the remainder joins the open batch as the same order with the smaller amount, and it clears again there. This repeats until the order is filled, cancelled, or its expiry batch has passed, after which the remainder returns to the owner. See Place and cancel orders.

Liquidity in the same batch

Positions are part of the same clearing. Each pair's liquidity moves along its curve toward the cleared price of its two tokens and stops short of it by the pair's fee plus one basis point. It pays out one token and takes in the other at the cleared price. What positions pay out is what fills orders beyond the orders on the other side. The clearing conditions has the arithmetic.

Why a solver cannot choose your fill

A clearing has to meet the four conditions, and the proof checks them. Two of them bind fills directly. Under Limits, an order in the money that is not rationed fills in full. Under Maximal, a direction is held back only when the band pins it, and the two sides of a token are never held back together. The fraction for a direction is therefore set by the batch, and it is the same for every order in it.