Mechanism
The cross
How revealed orders and LP quotes are matched at Popen, step by step, with a worked example.
The cross runs once per lull, after Popen is captured. It is split into permissionless steps. Tally classifies the revealed orders, in batches. Finalize crosses the book. Claim settles each ticket. Anyone can send these steps, and Lull's crank sends them.
Loading the Scaled UI multiplier…
1. Classify#
Each revealed order gets a class at Popen:
| Class | Condition | Takes part in |
|---|---|---|
| None | the limit is not met at Popen | nothing; fully refunded |
| A | the limit is met at Popen, but not at the worst LP price | matching only |
| B | the limit is met at Popen and at the worst LP price | matching and the LP leg |
The worst LP price is Popen × (1 + s_hi) for a buy and Popen × (1 − s_hi) for a sell. Here s_hi is the widest revealed spread among the quotes that would absorb the order: quotes with a max base for buys, and quotes with a max quote for sells. Market-on-open orders are always class B. If no quote was revealed on that side, every eligible order is class B.
Limits are compared with the Pyth price exactly, by integer cross-multiplication.
2. Find the heavy side#
Buys are heavy if their eligible USDC is at least the USDC value of the eligible sells at Popen. Otherwise sells are heavy.
- The light side fills completely at Popen.
- The heavy side shares the matched volume pro rata across classes A and B, by amount.
3. The LP leg#
Class B on the heavy side then takes what the LP quotes offer, cheapest spread first, with ties in reveal order. Each quote fills at its own price.
- Buy-heavy: class B's leftover USDC buys AAPLx from LPs at Popen × (1 + spread), until the USDC or the quotes run out. No LP sells more than its max base.
- Sell-heavy: class B's leftover AAPLx sells to LPs at Popen × (1 − spread), until the AAPLx or the quotes run out. No LP spends more than its max quote.
Anything left unfilled is refunded at claim.
4. Settle#
Each class on the heavy side stores three totals: what it paid (debit), what it received (credit), and its total locked amount (weight). An order in that class settles as:
debit = ⌈amount × class debit / class weight⌉
credit = ⌊amount × class credit / class weight⌋
The rest of its lock is refunded. Light-side orders settle at Popen directly.
Debits round up and credits round down, so no token is ever created. The dust, at most 1 raw unit per order, stays in the vault.
Worked example#
The numbers are hypothetical and shown in shares and USDC. On chain the same math runs in raw units, with the Scaled UI multiplier folded into the price (see Units), so results can differ by a raw unit of rounding.
Popen is $200.00 per share. The revealed book:
| Ticket | Revealed |
|---|---|
| Alice | buy, market on open, 6,000 USDC |
| Dan | buy, market on open, 2,000 USDC |
| Bob | buy, limit on open at $201.00, 2,000 USDC |
| Carol | sell, market on open, 25 shares |
| LP 1 | spread 50 bps, max base 10 shares |
| LP 2 | spread 100 bps, max base 5 shares |
Classify. The widest spread on the selling side is 100 bps, so the worst LP price for buyers is $202.00. Alice and Dan are class B. Bob's $201.00 limit is met at $200.00 but not at $202.00, so Bob is class A.
Heavy side. Eligible buys total 10,000 USDC. Carol's 25 shares are worth 5,000 USDC at Popen, so buys are heavy. Carol, on the light side, sells all 25 shares for 5,000 USDC.
Pro rata. The matched 5,000 USDC and 25 shares split by amount. Class A (2,000 of 10,000) pays 1,000 USDC for 5 shares. Class B (8,000 of 10,000) pays 4,000 USDC for 20 shares.
LP leg. Class B has 4,000 USDC left. LP 1 sells 10 shares at $201.00 for 2,010 USDC, which leaves 1,990. LP 2 sells 5 shares at $202.00 for 1,010 USDC, which leaves 980. No quotes remain, so 980 USDC is refunded. In total, class B pays 7,020 USDC for 35 shares.
Settle.
| Ticket | Locked | Pays | Receives | Refunded |
|---|---|---|---|---|
| Alice | 6,000 USDC | 5,265 USDC | 26.25 shares | 735 USDC |
| Dan | 2,000 USDC | 1,755 USDC | 8.75 shares | 245 USDC |
| Bob | 2,000 USDC | 1,000 USDC | 5 shares | 1,000 USDC |
| Carol | 25 shares | 25 shares | 5,000 USDC | none |
| LP 1 | 10 shares | 10 shares | 2,010 USDC | none |
| LP 2 | 5 shares | 5 shares | 1,010 USDC | none |
Sellers and LPs deliver 40 shares, and buyers receive 40. Buyers pay 8,020 USDC, and sellers and LPs receive 8,020. Alice and Dan pay about $200.57 per share on average. Bob pays $200.00 and stays within his limit. He takes no LP liquidity, even though LP 1's $201.00 was within his limit. That is the cost of the class rule explained below.
Properties of every cross#
- Matched buy equals matched sell: the AAPLx that sellers and LPs deliver reaches buyers, and the USDC likewise, within 1 raw unit per order.
- Neither token is created.
- Limits hold, on the LP leg too, up to rounding of 2 raw units of each token.
- No LP fills beyond its max size, and every LP gets at least its quoted price.
- The light side fills in full.
- A wider quote never fills while a cheaper one still has room.
Why it works this way#
- Pro rata, not time priority. Time priority would reward revealing early, and early reveals are exactly the information Lull keeps hidden as long as it can.
- Classes, not per-order LP checks. Checking each limit against the LP price that actually clears is circular, because the clearing spread depends on which orders take part. The widest revealed spread is known before the tally. Using it keeps every limit safe and lets the tally run in batches. The cost is that some limit orders just above Popen take no LP liquidity, like Bob's.