CLOB Architecture
Data Structures
Core data types used in the CLOB system
Data Structures
This document describes the data types used when interacting with the CLOB system.
Order
Represents an order returned by query functions.
| Field | Type | Description |
|---|---|---|
user | address | Wallet address that owns the order |
id | uint256 | Unique order identifier |
quantity | uint256 | Original order size in base currency units |
filled | uint256 | Amount already filled |
price | uint256 | Limit price (scaled) |
expiry | uint256 | Expiration timestamp (0 = no expiry) |
status | Status | Current order status |
orderType | OrderType | Limit or Market |
side | Side | Buy or Sell |
Useful calculations:
- Remaining quantity:
quantity - filled - Is active:
status == Open || status == PartiallyFilled
PoolKey
Identifies a trading pair.
| Field | Type | Description |
|---|---|---|
baseCurrency | address | Token being traded |
quoteCurrency | address | Token used for pricing |
Example pools:
| Base | Quote | Market |
|---|---|---|
| WETH | USDC | ETH/USDC |
| WBTC | USDC | BTC/USDC |
| ARB | WETH | ARB/ETH |
TradingRules
Trading parameters for a pool, returned by getTradingRules().
| Field | Description |
|---|---|
minTradeAmount | Smallest executable trade |
minAmountMovement | Quantity tick size (orders must be multiples) |
minPriceMovement | Price tick size (prices must be multiples) |
minOrderSize | Minimum order size |
maxOrderSize | Maximum order size (0 = unlimited) |
Enums
Side
| Value | Description |
|---|---|
Buy (0) | Bid side - buying base currency |
Sell (1) | Ask side - selling base currency |
OrderType
| Value | Description |
|---|---|
Limit (0) | Order with specified price |
Market (1) | Execute at best available prices |
Status
| Value | Description |
|---|---|
Open (0) | Active, unfilled |
PartiallyFilled (1) | Active, partially filled |
Filled (2) | Completely filled |
Cancelled (3) | Cancelled by user |
TimeInForce
| Value | Description |
|---|---|
GTC (0) | Good Till Cancel |
IOC (1) | Immediate or Cancel |
FOK (2) | Fill or Kill |
PostOnly (3) | Add liquidity only |
STPMode
| Value | Description |
|---|---|
None (0) | Allow self-trades |
CancelTaker (1) | Cancel incoming order |
CancelMaker (2) | Cancel resting order |
CancelBoth (3) | Cancel both orders |
QuoteResult
Returned by quote functions to preview trade execution.
| Field | Type | Description |
|---|---|---|
expectedAmountOut | uint256 | Expected output amount |
totalQuoteAmount | uint256 | Total quote currency involved |
executionPrice | uint256 | Execution price |
avgExecutionPrice | uint256 | Average execution price |
priceImpact | uint256 | Price impact in basis points |
fee | uint256 | Trading fee |
executable | bool | Whether order can execute |
message | string | Status/error message |
Usage:
QuoteResult memory quote = router.getQuote(
baseCurrency,
quoteCurrency,
OrderType.Market,
Side.Buy,
1 ether,
0
);
if (quote.executable) {
uint256 minOut = quote.expectedAmountOut * 99 / 100;
router.placeMarketOrder(pool, 1 ether, Side.Buy, user, minOut);
}PriceVolume
Aggregated data at a price level.
| Field | Type | Description |
|---|---|---|
price | uint256 | Price level |
volume | uint256 | Total volume at this price |
Usage:
// Get best bid
PriceVolume memory bestBid = router.getBestPrice(
baseCurrency,
quoteCurrency,
Side.Buy
);
// Get order book depth
PriceVolume[] memory asks = router.getNextBestPrices(
pool,
Side.Sell,
0,
10
);BatchOrder
Used for batch order placement.
| Field | Type | Description |
|---|---|---|
pool | PoolKey | Trading pair |
price | uint256 | Limit price |
quantity | uint256 | Order size |
side | Side | Buy or Sell |
timeInForce | TimeInForce | Order duration |
BatchOrderResult
Result of batch order operations.
| Field | Type | Description |
|---|---|---|
orderId | uint256 | Assigned order ID (0 if failed) |
success | bool | Whether order succeeded |
message | string | Error message if failed |