Ambient limit orders: Reversible Partial Fills and Knockout Settlement

Ambient limit orders can reverse a partial fill until the pool price crosses the order's knockout boundary. These orders use a defined liquidity range, so entering the range begins conversion without completing the trade. If price retreats before the terminal boundary, the token mix can move back toward the deposited asset. Crossing the terminal boundary triggers permanent removal of that liquidity from the curve. This locks the converted principal even if the pool price subsequently returns.

The short version: A filled order still needs a successful claim or recovery before its converted tokens reach the selected settlement balance.

Directional Execution Across a Range

Knockout bids and asks convert principal across a price range while sharing execution pro rata with other active pool liquidity. Posting earlier gives no first-in-first-out priority.

Bid Conversion

A bid normally rests below the pool price and commits the protocol's base token. Falling pool price converts that principal toward the quote token. The lower boundary is its knockout edge. Until price crosses that boundary, an in-range position still holds an evolving mixture of the pair's tokens.

Ask Conversion

An ask normally rests above the pool price and commits the protocol's quote token. Rising pool price converts its principal toward the base token, with the upper boundary completing execution. These directions follow the protocol's price convention. A chart showing the reciprocal exchange rate can make the displayed movement look reversed.

Can a Partial Fill Reverse?

An open knockout position's partial fill can reverse if pool price retreats before crossing its terminal boundary. Its current collateral mix does not establish a permanently completed purchase or sale.

Price Retreat Within the Range

A greater share of the desired token at one point therefore need not survive a later price move. The range remains part of the automated market maker, which continuously changes the collateral mix as swaps move its price.

Partial execution consequently differs from a settled partial trade on an order book. In an order book, a completed match fixes the executed portion. Here, the open position continues participating in conversion.

Removal Before Full Execution

Removing an open knockout position withdraws the collateral corresponding to its current state. When price lies inside the range, that principal includes both converted and unconverted tokens. Cancellation does not restore the original deposit composition. It ends the removed liquidity's participation, preserving the mixture payable when the removal executes.

The burn call must allow an inside-range removal when the order has partly converted. A request requiring price outside the range can fail in this state. The pool price when the burn executes determines the payout composition, so an earlier displayed mixture cannot fix the withdrawal amounts.

Ordinary Ranges and Permanently Filled Orders

An ordinary concentrated range remains eligible to trade again after price leaves and later re-enters it, while a completed knockout stays inactive. Both use range-based liquidity before knockout. Their behavior separates at the terminal crossing: the ordinary range retains its liquidity position, while the knockout removes that tranche from future trading. Repositioning an ordinary out-of-range position changes where its capital participates. A completed knockout instead holds converted principal for retrieval.

Order Management by Position State

A position's open or completed status determines which management action applies and whether its principal remains exposed to the pool's price movement. Minting creates or increases resting knockout liquidity. Burning removes open liquidity. Claiming and recovery retrieve principal after knockout, with different requirements for identifying the completed tranche.

Pool permissions can constrain minting and burning; claim and recovery do not use those mint or burn permission checks. A crossing can complete an order before its pending cancellation executes, leaving the burn inapplicable to that filled position.

Range Width and Execution Costs

A new knockout range must match the pool's configured tick width and satisfy its placement rules, while transaction execution and calldata determine network costs. A new knockout range must meet the pool's enabled settings and any required tick alignment. Arbitrary endpoints need not form a valid order. Placement, cancellation and retrieval involve transactions; claim history can increase their data requirements. Dynamic pool fees apply to swaps; the published knockout implementation returns principal without fee rewards on cancellation, claim or recovery. Waiting alone cannot complete an order whose pool price never crosses the terminal boundary.

Locked Principal and Settlement Balances

A recorded knockout fixes converted principal, while settlement determines whether its tokens enter a wallet or an exchange balance. The filled tranche stops trading before that payout.

Principal Conversion

Crossing the terminal boundary permanently removes that knockout liquidity from the trading curve. The protocol calculates the filled principal from the position's liquidity and range boundaries. A later pool price does not reconvert it. The payout quantity belongs to the converted token, so it cannot be compared directly with the original deposit quantity without accounting for the exchange rate and token units.

Payout Destination

Settlement settings can credit the recipient's wallet or the exchange's surplus collateral balance. Surplus collateral is an internal token balance, separate from both wallet holdings and open order liquidity. A wallet balance may therefore remain unchanged after successful retrieval into surplus. The relevant account credit establishes receipt at the selected destination. The position's on-chain knockout record establishes execution status, while the successful retrieval transaction and its token flows establish payout.

Open full-size image

Claim History and Recovery Limits

A claim relies on the relevant completed tranche's recorded history, while recovery uses its original timestamp to identify principal eligible for release. A tranche groups knockout liquidity under a particular creation time. That identity distinguishes older filled positions from later orders placed at the same boundary.

The protocol stores the latest knockout record directly. A claim for that record can use an empty proof; older records require the applicable Merkle history. A Merkle proof connects the earlier knockout record to the history the contract accepts. The need for proof data therefore follows the record's position in that history.

A later knockout at the same boundary can make prepared claim data stale before the transaction executes. Invalid proof data causes the claim to revert. Updated history can support a fresh claim, while recovery avoids that Merkle-proof dependency. Recovery still requires the correct pool, direction, range and original tranche timestamp. Claim and recovery also enforce the pool's minimum holding condition, timed from the position's creation or latest liquidity increase. It returns converted principal without a fee reward. It cannot cancel an open position or undo its completed conversion.

Successful retrieval clears the principal record, preventing another payout from it. A failed retrieval leaves its tokens unclaimed. The settlement credit makes those tokens available at the selected destination.

Updated · 8 Oct 2026