Range order

A concentrated-liquidity position that sits entirely on one side of the price is already a limit order: as the price crosses its range, it converts from one token to the other. On its own it converts back if the price returns. The range-order hook takes a filled order out of the pool in the same swap that fills it, so the fill stays filled.

For the steps in the app, see Place a range order.

Placing an order#

Orders are placed through the hook. The hook holds each order as a one-sided position in the pool.

• The owner chooses the range, in multiples of the pool's tick spacing.
• The range sits entirely on one side of the current price, so the order holds one token.
• Many owners' orders and ordinary LP positions share the same pool.

Filling#

The swap that takes the price all the way through an order's range converts the order completely. In that swap's afterSwap, the hook takes the order's liquidity out of the pool. A filled order is no longer in the pool, so it can't convert back when the price returns.

One swap takes out at most 24 orders. If a swap crosses more, anyone can take out the rest with fill(key, zeroForOne, boundary) while the price is still past them.

The hook's own call to PoolManager doesn't trigger its own callbacks. The crossing swap's transaction pays the gas for the removal.

Claiming#

The owner claims a filled order's proceeds whenever they like.

Cancelling#

An unfilled order can be cancelled. The owner gets the order's tokens back.

For routers#

A range-order pool routes like any other v4 pool. The hook has no swap returns-delta flag, so a swap gets exactly what the pool's curve gives. A swap that fills orders costs more gas, and the Quoter's gasEstimate includes it.

Flags#

The hook has afterInitialize and afterSwap, plus afterAddLiquidity, afterRemoveLiquidity and both of their returns-delta flags for the buyback share.