Skip to main content
Much of the terminology used below, especially for units, may be confusing at first. Refer to the glossary for more details.

Structures for Market Interactions

ConfigParams

struct ConfigParams {
    uint256 quoteLotSizeInAtoms;
    uint256 baseLotSizeInAtoms;
    uint256 tickSizeInQuoteLotsPerBaseUnit;
    uint256 minLimitOrderAmountInBaseLots;
    FeeTier feeTier;
}
  • quoteLotSizeInAtoms: The smallest tradeable unit of the quote token, measured in atoms.
  • baseLotSizeInAtoms: The smallest tradeable unit of the base token, measured in atoms.
  • tickSizeInQuoteLotsPerBaseUnit: The minimum price increment for trading, expressed as a number of quote lots per base unit.
  • minLimitOrderAmountInBaseLots: Minimum allowable size for a limit order, measured in base lots.
  • feeTier: Defined in the FeeTier enum:
    enum FeeTier {
        LOW,
        MEDIUM,
        HIGH
    }
    

PostLimitOrderArgs

struct PostLimitOrderArgs {
    uint256 amountInBaseLots;
    uint256 priceInTicks;
    uint256 cancelTimestamp;
    Side side;
    LimitOrderType limitOrderType;
    Settlement settlement;
}
  • amountInBaseLots: The size of the order, measured in base lots.
  • priceInTicks: The price of the order, expressed in ticks (quote lots per base unit).
  • cancelTimestamp: Unix timestamp after which the order is automatically canceled; ignored if set to 0.
  • side: Defined in the Side enum:
    enum Side {
        BUY,
        SELL
    }
    
  • limitOrderType: Defined in the LimitOrderType enum. For GOOD_TILL_CANCELLED orders, the unmatched portion remains in the book until filled or canceled, while POST_ONLY orders are added only if they do not immediately match.
    enum LimitOrderType {
        GOOD_TILL_CANCELLED,
        POST_ONLY
    }
    
  • settlement: Defined in the Settlement enum.

PostLimitOrderResult

struct PostLimitOrderResult {
    uint256 orderId;
    uint256 amountPostedInBaseLots;
    int256 quoteTokenAmountTradedInAtoms;
    int256 baseTokenAmountTradedInAtoms;
}
  • orderId: A unique identifier for the submitted order.
  • amountPostedInBaseLots: The amount of the order that was successfully posted to the order book, measured in base lots.
  • quoteTokenAmountTradedInAtoms: The amount of quote tokens traded, measured in atoms; negative if outgoing, positive if incoming, and includes fees.
  • baseTokenAmountTradedInAtoms: The amount of base tokens traded, measured in atoms; negative if outgoing, positive if incoming.

PostFillOrderArgs

struct PostFillOrderArgs {
    uint256 amountInBaseLots;
    uint256 priceInTicks;
    Side side;
    FillOrderType fillOrderType;
    Settlement settlement;
}
  • amountInBaseLots: The size of the fill order, measured in base lots.
  • priceInTicks: The price of the fill order, expressed in ticks.
  • side: Defined in the Side enum:
    enum Side {
        BUY,
        SELL
    }
    
  • fillOrderType: Defined in the FillOrderType enum. FILL_OR_KILL orders are filled completely or not at all, while IMMEDIATE_OR_CANCEL orders are filled immediately if possible, with any remaining portion canceled.
    enum FillOrderType {
        FILL_OR_KILL,
        IMMEDIATE_OR_CANCEL
    }
    
  • settlement: Defined in the Settlement enum.

PostFillOrderResult

struct PostFillOrderResult {
    uint256 orderId;
    uint256 amountFilledInBaseLots;
    int256 quoteTokenAmountTradedInAtoms;
    int256 baseTokenAmountTradedInAtoms;
}
  • orderId: A unique identifier for the fill order.
  • amountFilledInBaseLots: The amount of the order that was successfully filled, measured in base lots.
  • quoteTokenAmountTradedInAtoms: The amount of quote tokens traded, measured in atoms; negative if outgoing, positive if incoming, and includes fees.
  • baseTokenAmountTradedInAtoms: The amount of base tokens traded, measured in atoms; negative if outgoing, positive if incoming.

ReduceArgs

struct ReduceArgs {
    uint256 orderId;
    uint256 amountInBaseLots;
    Settlement settlement;
}
  • orderId: The unique identifier of the order to be reduced.
  • amountInBaseLots: The amount by which the order should be reduced, measured in base lots.
  • settlement: Defined in the Settlement enum.

CancelArgs

struct CancelArgs {
    uint256[] orderIds;
    Settlement settlement;
}
  • orderIds: An array of unique identifiers for the orders to be canceled.
  • settlement: Defined in the Settlement enum.

Settlement

enum Settlement {
    INSTANT,
    ACCOUNT
}
  • INSTANT: Immediate token transfers upon cancel, reduce, or trade execution.
  • ACCOUNT: Updates internal account balances within the CLOB contracts without immediate token transfers.

Core Market and Metadata

CLOBStorage

struct CLOBStorage {
    MarketData marketData;
    Book book;
    AccountStorage accounts;
}
The CLOBStorage struct uses CLOBStorageLib as a global library for its functions.
  • marketData: Contains market metadata. See MarketData.
  • book: Represents the order book, including market and token configurations. See Book.
  • accounts: Manages user account balances and related data. See AccountStorage.

MarketData

struct MarketData {
    Header header;
    FeeData feeData;
}
The MarketData struct uses MarketDataLib as a global library for its functions.
  • header: Contains metadata about the market. See Header.
  • feeData: Holds information about fees collected and unclaimed. See FeeData.
struct Header {
    address factory;
    MarketStatus status;
}
  • factory: The address of the factory contract that created the market.
  • status: The current status of the market. See MarketStatus.

FeeData

struct FeeData {
    uint256 takerFeeBps;
    uint256 totalQuoteTokenFees;
    uint256 unclaimedQuoteTokenFees;
}
  • takerFeeBps: The taker fee rate, expressed in basis points.
  • totalQuoteTokenFees: The total amount of quote token fees collected, measured in quote atoms.
  • unclaimedQuoteTokenFees: The amount of quote token fees that have not yet been claimed, measured in quote atoms.

MarketStatus

enum MarketStatus {
    ACTIVE,
    INACTIVE
}
  • ACTIVE: Indicates that the market is currently active and operational.
  • INACTIVE: Indicates that the market is currently inactive and not operational.

MarketConfig

struct MarketConfig {
    uint256 minLimitOrderAmountInBaseLots;
    uint256 maxNumOrders;
    uint256 tickSizeInQuoteLotsPerBaseUnit;
}
  • minLimitOrderAmountInBaseLots: The minimum allowable size for a limit order, measured in base lots.
  • maxNumOrders: The maximum number of orders that can be present in the order book.
  • tickSizeInQuoteLotsPerBaseUnit: The minimum price increment for trading, expressed as a number of quote lots per base unit.

TokenConfig

struct TokenConfig {
    IERC20 quoteToken;
    IERC20 baseToken;
    uint256 quoteLotSizeInAtoms;
    uint256 baseLotSizeInAtoms;
    uint256 quoteLotsPerQuoteUnit;
    uint256 baseLotsPerBaseUnit;
}
  • quoteToken: The ERC20 token used as the quote currency.
  • baseToken: The ERC20 token used as the base currency.
  • quoteLotSizeInAtoms: The smallest tradeable unit of the quote token, measured in atoms.
  • baseLotSizeInAtoms: The smallest tradeable unit of the base token, measured in atoms.
  • quoteLotsPerQuoteUnit: The number of quote lots per quote unit.
  • baseLotsPerBaseUnit: The number of base lots per base unit.

Order Book Structures

Book

struct Book {
    MarketConfig marketConfig;
    TokenConfig tokenConfig;
    uint256 quoteTokenOpenInterestInAtoms;
    uint256 baseTokenOpenInterestInAtoms;
    uint256 nextOrderId;
    uint256 numBids;
    uint256 numAsks;
    RedBlackTree bidTree;
    RedBlackTree askTree;
    mapping(uint256 => Order) orders;
    mapping(uint256 => Limit) bidLimits;
    mapping(uint256 => Limit) askLimits;
}
The Book struct uses BookLib as a global library for its functions.
  • marketConfig: Configuration settings for the market. See MarketConfig.
  • tokenConfig: Configuration settings for the tokens. See TokenConfig.
  • quoteTokenOpenInterestInAtoms: The total open interest for the quote token, measured in atoms.
  • baseTokenOpenInterestInAtoms: The total open interest for the base token, measured in atoms.
  • nextOrderId: The identifier for the next order to be added to the book.
  • numBids: The number of bid orders currently in the book.
  • numAsks: The number of ask orders currently in the book.
  • bidTree: A red-black tree structure for managing bid prices. See RedBlackTree.
  • askTree: A red-black tree structure for managing ask prices. See RedBlackTree.
  • orders: A mapping of order IDs to their corresponding Order structs.
  • bidLimits: A mapping of bid price levels (in ticks) to their corresponding Limit structs.
  • askLimits: A mapping of ask price levels (in ticks) to their corresponding Limit structs. See Limit.

Order

struct Order {
    uint256 id;
    uint256 amountInBaseLots;
    uint256 priceInTicks;
    uint256 prevOrderId;
    uint256 nextOrderId;
    uint256 cancelTimestamp;
    Side side;
    address owner;
}
The Order struct uses OrderLib as a global library for its functions.
  • id: A unique identifier for the order.
  • amountInBaseLots: The size of the order, measured in base lots.
  • priceInTicks: The price of the order, expressed in ticks.
  • prevOrderId: The ID of the previous order in the linked list of orders at the same price level.
  • nextOrderId: The ID of the next order in the linked list of orders at the same price level.
  • cancelTimestamp: The timestamp after which the order is automatically canceled.
  • side: The side of the order, either BUY or SELL.
  • owner: The address of the account that owns the order.

Limit

struct Limit {
    uint256 priceInTicks;
    uint256 numOrders;
    uint256 totalVolumeInBaseLots;
    uint256 headOrder;
    uint256 tailOrder;
}
  • priceInTicks: The price level of the limit, expressed in ticks.
  • numOrders: The number of orders at this price level.
  • totalVolumeInBaseLots: The total volume of all orders at this price level, measured in base lots.
  • headOrder: The ID of the first order in the linked list of orders at this price level.
  • tailOrder: The ID of the last order in the linked list of orders at this price level.

RedBlackTree

struct RedBlackTree {
    uint256 root;
    uint256 size;
    uint256 minimum;
    uint256 maximum;
    mapping(uint256 => Node) nodes;
}
The RedBlackTree struct uses RedBlackTreeLib as a global library for its functions.
  • root: The key of the root node of the red-black tree.
  • size: The total number of nodes currently in the tree.
  • minimum: The key of the node with the smallest value in the tree.
  • maximum: The key of the node with the largest value in the tree.
  • nodes: A mapping of keys to their corresponding Node structs, representing the nodes in the tree.

Node

struct Node {
    uint256 key;
    uint256 parent;
    uint256 left;
    uint256 right;
    bool isRed;
}
  • key: The unique key associated with the node, typically representing a price level or order ID.
  • parent: The key of the parent node in the red-black tree.
  • left: The key of the left child node in the red-black tree.
  • right: The key of the right child node in the red-black tree.
  • isRed: A boolean indicating whether the node is red (true) or black (false), used to maintain tree balance.

Account Management Structures

AccountStorage

struct AccountStorage {
    mapping(address => Account) accounts;
}
The AccountStorage struct uses AccountLib as a global library for its functions.
  • accounts: A mapping of user addresses to their corresponding Account structs. See Account.

Account

struct Account {
    uint256 quoteTokenBalance;
    uint256 baseTokenBalance;
}
  • quoteTokenBalance: The balance of quote tokens held by the account, measured in atoms.
  • baseTokenBalance: The balance of base tokens held by the account, measured in atoms.
I