Key Structures

​

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;
}

• 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;
}

• header: Contains metadata about the market. See Header.
• feeData: Holds information about fees collected and unclaimed. See FeeData.

​

Header

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;
}

• 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;
}

• 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;
}

• 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;
}

• 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.