> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kuru.io/llms.txt
> Use this file to discover all available pages before exploring further.

# OrderBook Contract

> Central limit order book with integrated AMM liquidity and price-time priority matching.

## Data Structures

* **Order** — `{ address owner, uint96 size, uint40 prev, uint40 next, uint40 flippedId, uint32 price, uint32 flippedPrice, bool isBuy }`
* **PricePoint** — `{ uint40 head, uint40 tail }`
* **TreeUint24** — Tree structure for active price points

## Core Functions

### Order Placement

```solidity theme={null}
function addBuyOrder(uint32 _price, uint96 _size, bool _postOnly) external
function addSellOrder(uint32 _price, uint96 _size, bool _postOnly) external
```

Places limit buy/sell orders. Matches against resting orders first. If `_postOnly` is true, reverts if any portion matches immediately.

### Flip Orders

```solidity theme={null}
function addFlipBuyOrder(uint32 _price, uint32 _flippedPrice, uint96 _size, bool _provisionOrRevert) external
function addFlipSellOrder(uint32 _price, uint32 _flippedPrice, uint96 _size, bool _provisionOrRevert) external
```

Places flip orders that create opposite-side orders on fill. `_flippedPrice` must be better than `_price`. If `_provisionOrRevert` is false, reverts if best price equals current book best.

### Market Orders

```solidity theme={null}
function placeAndExecuteMarketBuy(uint96 _quoteSize, uint96 _minOut, bool _isMargin, bool _isFOK) external payable
function placeAndExecuteMarketSell(uint96 _size, uint96 _minOut, bool _isMargin, bool _isFOK) external payable
```

Executes market orders against resting liquidity. Supports ERC20–ERC20, NATIVE–ERC20, and ERC20–NATIVE pairs. `_isFOK` enforces fill-or-kill behavior.

### Cancellation

```solidity theme={null}
function batchCancelOrders(uint40[] calldata _orderIds) external
function batchCancelFlipOrders(uint40[] calldata _orderIds) external
```

Batch cancels regular or flip orders. Idempotent—safe to call multiple times.

### Liquidity Provision

```solidity theme={null}
function addPairedLiquidity(uint32 _bidPrice, uint32 _askPrice, uint96 _bidSize, uint96 _askSize) external
function batchProvisionLiquidity(uint32[] calldata _prices, uint96[] calldata _sizes, bool[] calldata _isBid) external
```

Adds liquidity to the AMM vault. `addPairedLiquidity` sets bid/ask prices and sizes. Batch function allows provisioning multiple price points at once.

### View Functions

```solidity theme={null}
function bestBidAsk() external view returns (uint32, uint32)
function getL2Book() external view returns (bytes)
function getL2Book(uint32 _bidPricePoints, uint32 _askPricePoints) external view returns (bytes)
function getMarketParams() external view returns (MarketParams memory)
```

Returns best bid/ask prices, L2 order book depth, and market configuration parameters.

## Market States

* `ACTIVE` — Full operations enabled
* `SOFT_PAUSED` — Only cancels, deposits, withdrawals allowed
* `HARD_PAUSED` — All operations halted

## Order Types

| Type | Description    | prev     | next     |
| ---- | -------------- | -------- | -------- |
| A    | Single order   | NULL     | NULL     |
| B    | Head with next | NULL     | NON-NULL |
| C    | Middle order   | NON-NULL | NON-NULL |
| D    | Tail order     | NON-NULL | NULL     |

## Events

### OrderCreated

```solidity theme={null}
event OrderCreated(
    uint40 indexed orderId,
    address indexed owner,
    uint96 size,
    uint32 price,
    bool isBuy
);
```

Emitted when a new limit order is placed on the order book.

### FlipOrderCreated

```solidity theme={null}
event FlipOrderCreated(
    uint40 indexed orderId,
    uint40 indexed flippedId,
    address indexed owner,
    uint96 size,
    uint32 price,
    uint32 flippedPrice,
    bool isBuy
);
```

Emitted when a flip order is created. `flippedId` is the order ID that will be created on the opposite side when this order fills.

### Trade

```solidity theme={null}
event Trade(
    uint40 orderId,
    address indexed maker,
    bool isBuy,
    uint32 price,
    uint96 updatedSize,
    address indexed taker,
    address indexed origin,
    uint96 filledSize
);
```

Emitted for each order fill. `updatedSize` is the remaining size after fill. `origin` is the original transaction sender (supports meta-transactions).

### OrderCanceled

```solidity theme={null}
event OrderCanceled(
    uint40 indexed orderId,
    address indexed owner,
    uint96 size,
    uint32 price,
    bool isBuy
);
```

Emitted when an order is successfully canceled. Returns the full order size before cancellation.

### MarketStateUpdated

```solidity theme={null}
event MarketStateUpdated(
    MarketState prevState,
    MarketState newState
);
```

Emitted when market state changes (ACTIVE, SOFT\_PAUSED, or HARD\_PAUSED).