Types
SpotPool / OrderBook Types
OrderId (type)
solidity
type OrderId is uint128;
An OrderId is unique only within a single market. The same value can refer to different orders across markets, and resting and pending/stop orders are numbered independently. Always pair an OrderId with its market to identify an order.
Order (struct)
solidity
struct Order {
OrderId orderId;
bool isBid;
address owner;
uint64 userData;
uint256 price;
uint256 fullQuantity;
uint256 quantityRemaining;
uint64 expireTimestampNs;
}
OrderBookLevel (struct)
solidity
struct OrderBookLevel {
uint256 price;
uint256 quantity;
}
OrderType (enum)
| Value | Description |
|---|---|
NormalOrder | Order will be filled or placed into the book depending on current state |
FillOrKill | Order will only execute if it can be fully filled immediately, otherwise rejected |
ImmediateOrCancel | Order will fill as much as possible immediately, remaining quantity is cancelled |
PostOnly | Order will be rejected if any portion would fill immediately (maker-only) |
SelfMatchingOption (enum)
| Value | Description |
|---|---|
CancelTaker | Cancel the taker order if it would match against own maker order |
CancelMaker | Cancel the maker order if taker would match against it, then continue matching |
PlaceOrderRequest (struct)
One order in a batch placement. Mirrors the per-order arguments of placeOrder; the order owner is supplied once by the batch entrypoint — the caller for placeOrders, the owner argument for placeOrdersFor — rather than per request.
solidity
struct PlaceOrderRequest {
bool isBid;
uint64 userData;
uint256 price;
uint256 quantity;
uint64 expireTimestampNs;
OrderType orderType;
SelfMatchingOption selfMatchingOption;
address builder;
uint96 builderFeeBpsTimes1k;
}
| Field | Type | Description |
|---|---|---|
isBid | bool | True for a buy (bid) order, false for a sell (ask) order |
userData | uint64 | Arbitrary 64-bit user data attached to the order |
price | uint256 | Limit price; must be a multiple of tickSize |
quantity | uint256 | Order quantity; must be >= minQuantity and a multiple of lotSize |
expireTimestampNs | uint64 | Expiration timestamp in nanoseconds (must be a future value) |
orderType | OrderType | Execution type: NormalOrder, FillOrKill, ImmediateOrCancel, or PostOnly |
selfMatchingOption | SelfMatchingOption | Behavior when the order would match against the owner's own orders |
builder | address | Optional builder address that earns a fee on this order's fills. address(0) for none. |
builderFeeBpsTimes1k | uint96 | Per-order builder fee rate in BPS_TIMES_1K units. Must be 0 when builder is address(0). |
ReduceOrderRequest (struct)
One reduction in a batch reduce (reduceOrders / reduceOrdersFor).
solidity
struct ReduceOrderRequest {
OrderId orderId;
uint256 newQuantityRemaining;
}
| Field | Type | Description |
|---|---|---|
orderId | OrderId | The order to reduce |
newQuantityRemaining | uint256 | The new remaining quantity; must be >= minQuantity and lot-aligned |
AmendOrderRequest (struct)
One amend — the order to cancel plus the replacement to place. Shared by amendOrder / amendOrderFor (one request) and amendOrders / amendOrdersFor (an array of requests).
solidity
struct AmendOrderRequest {
OrderId oldOrderId;
bool alwaysPlace;
PlaceOrderRequest newOrder;
}
| Field | Type | Description |
|---|---|---|
oldOrderId | OrderId | The resting order to cancel, then replace |
alwaysPlace | bool | Race handling for an oldOrderId already filled/cancelled by the time the tx lands. false (default) reverts AmendOldOrderGone and places nothing; true skips the (impossible) cancel and places newOrder anyway (opt-in upsert). |
newOrder | PlaceOrderRequest | The replacement order to place; owned by the amend caller (or the operator-declared owner on the ...For paths) |
OrderBookParameters (struct)
solidity
struct OrderBookParameters {
uint256 tickSize;
uint256 minQuantity;
uint256 lotSize;
}
| Field | Type | Description |
|---|---|---|
tickSize | uint256 | Minimum price increment in quote token units |
minQuantity | uint256 | Minimum order quantity in base token units |
lotSize | uint256 | Minimum quantity increment in base token units |
SpotPoolParameters (struct)
solidity
struct SpotPoolParameters {
uint256 takerFeeBpsTimes1k;
uint256 makerFeeBpsTimes1k;
address feeRecipient;
uint256 maxBuilderFeeBpsTimes1k;
}
| Field | Type | Description |
|---|---|---|
takerFeeBpsTimes1k | uint256 | Taker fee rate in basis points x 1000 (1 BPS = 1000) |
makerFeeBpsTimes1k | uint256 | Maker fee rate in basis points x 1000 (1 BPS = 1000) |
feeRecipient | address | Address that receives collected trading fees |
maxBuilderFeeBpsTimes1k | uint256 | Protocol-wide cap on per-user→builder approvals (BPS_TIMES_1K). 0 disables Builder Codes. |
TokenLockBreakdown (struct)
Returned per token by getLockedTokenBreakdown. The three fields are exhaustive and disjoint — their sum equals the pool's on-chain balance of the token.
solidity
struct TokenLockBreakdown {
uint256 principalLocked;
uint256 lockedSurplus;
uint256 leftover;
}
| Field | Type | Description |
|---|---|---|
principalLocked | uint256 | Principal locked by resting orders — the tradeable amount they would pay out if fully filled, before fees. |
lockedSurplus | uint256 | Everything locked above principal: the maker + builder fee reserve, price-improvement over-lock (refunded to the owner on cancel/removal), and rounding dust. Not purely protocol revenue. |
leftover | uint256 | Token held by the pool but not locked on the book: free (withdrawable) vault balances, fees already accrued to the fee recipient, and any direct transfers. |
MidpointEmaParameters (struct)
Configuration for the EMA-smoothed midpoint trigger feed emitted on MarkPriceUpdated. The smoothing factor is the load-bearing protection against single-block midpoint manipulation — an attacker would need to sustain a manipulated raw midpoint across multiple intervals to drag the EMA past a stop's trigger band.
solidity
struct MidpointEmaParameters {
uint256 updateIntervalSec;
uint256 emaSmoothingAlpha;
}
| Field | Type | Description |
|---|---|---|
updateIntervalSec | uint256 | How often the EMA advances by one step, in seconds. Must be > 0 and <= 86400 (one day). |
emaSmoothingAlpha | uint256 | EMA smoothing factor scaled by 1e18. Must be in (0, 1e18]. Higher = less smoothing. |
Stop Order Types
PendingOrderType (enum)
| Value | Description |
|---|---|
LIMIT | Triggered order uses a user-specified limit price |
MARKET | Triggered order uses a slippage-adjusted limit price computed from the mark price |
Operator (enum)
| Value | Description |
|---|---|
GTE | Triggers when mark price is greater than or equal to trigger price |
LTE | Triggers when mark price is less than or equal to trigger price |
PendingOrder (struct)
solidity
struct PendingOrder {
bool isBid;
address owner;
uint64 userData;
uint256 quantity;
}
PendingOrderWithTrigger (struct)
solidity
struct PendingOrderWithTrigger {
PendingOrder order;
PendingOrderType orderType;
uint256 triggerPrice;
Operator triggerOperator;
uint256 limitPrice;
address builder;
uint96 builderFeeBpsTimes1k;
}
| Field | Type | Description |
|---|---|---|
order | PendingOrder | Core order parameters (side, owner, userData, quantity) |
orderType | PendingOrderType | Whether this is a LIMIT or MARKET order |
triggerPrice | uint256 | The EMA midpoint threshold that activates this order |
triggerOperator | Operator | GTE or LTE comparison against the mark price |
limitPrice | uint256 | Limit price for LIMIT orders. Must be exactly 0 for MARKET orders. |
builder | address | Optional builder address that earns a fee on the triggered IOC order's fills. address(0) for none. See Builder Codes. |
builderFeeBpsTimes1k | uint96 | Per-order builder fee rate in BPS_TIMES_1K units. Must be 0 when builder is address(0). |
StoredPendingOrder (struct)
The on-chain representation of a pending order. Returned by registry view functions.
solidity
struct StoredPendingOrder {
PendingOrderWithTrigger orderWithTrigger;
OrderId orderId;
uint256 somiPaid;
}
| Field | Type | Description |
|---|---|---|
orderWithTrigger | PendingOrderWithTrigger | The original order specification |
orderId | OrderId | Globally unique pending-order identifier |
somiPaid | uint256 | SOMI paid at creation. Refunded on cancel, consumed on trigger. |