> For the complete documentation index, see [llms.txt](https://docs.21x.eu/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.21x.eu/order-book/orderbook.md). # OrderBook ## Order Book > Order Book uses Diamond proxy pattern. There are three important facets from the user perspective. > > * OrderBookBuyFacet > * OrderBookSellFacet > * OrderBookCancelFacet > * OrderBookGeneralFacet ## OrderBookBuyFacet > Order Book Buy Facet - Allows to create buy trades between two, defined tokens compatible with ERC-20. *.Contract uses double linked list to store new buys and sells items* ### OrderBookBuyFacet - Methods #### newBuyOrder ```solidity function newBuyOrder(bytes orderData, bytes reportingData, bytes crossIdentifier) external nonpayable ``` * Function creates new buy order, * orderData param must fit structure, * this function has multiple executing scenarios depending on the current state of order book, * transfers collateral from the client address to the order book or seller address * only executable when contract is not paused * only executable when not called by the admin * reentrancy protected * does not follow Checks-Effects-Interactions pattern * for detailed explanation of orderData structure check the corresponding documentation **Parameters** | Name | Type | Description | | --------------- | ----- | ------------------------------------------------------------------------------------------------------------- | | orderData | bytes | New buy order data (Bits: buyQuantity 64 \| buyPrice 64 \| orderType 8 \| executionCondition 8 \| lifetime 8) | | reportingData | bytes | (Bits: ownerReportingId 32 \| decisionReportingId 32) | | crossIdentifier | bytes | any unique identifier or empty | ## OrderBookSellFacet > Order Book - Allows to create sell trades between two, defined tokens compatible with ERC-20. *Contract uses double linked list to store new buys and sells items* ### OrderBookSellFacet - Methods #### newSellOrder ```solidity function newSellOrder(bytes orderData, bytes reportingData, bytes crossIdentifier) external nonpayable ``` * Function creates new sell order * orderData param must fit structure, * this function has multiple executing scenarios depending on the current state of order book, * transfers collateral from the client address to the order book or seller address * only executable when contract is not paused * only executable when not called by the admin * reentrancy protected * does not follow Checks-Effects-Interactions pattern * for detailed explanation of orderData structure check the corresponding documentation **Parameters** | Name | Type | Description | | --------------- | ----- | ------------------------------------------------------------------------------------------------------------- | | orderData | bytes | New buy order data (Bits: buyQuantity 64 \| buyPrice 64 \| orderType 8 \| executionCondition 8 \| lifetime 8) | | reportingData | bytes | (Bits: ownerReportingId 32 \| decisionReportingId 32) | | crossIdentifier | bytes | any unique identifier or empty | ## OrderBookCancelFacet > Order Book Cancel Facet - Allows to cancel order based on provided orderId *Contract handles cancels for buy and sell orders* ### OrderBookCancelFacet - Methods #### cancelBuyOrder ```solidity function cancelBuyOrder(uint64 orderId) external nonpayable ``` * Function cancels given buy order based on provided id * Cancels buy order with given id. Transfers back collateral to the client address. * only executable when market is not closed and will cancel only if executed by order owner (client address) * reverts if orderId does not exist * follows Checks-Effects-Interactions pattern **Parameters** | Name | Type | Description | | ------- | ------ | ------------------ | | orderId | uint64 | Order id to cancel | #### cancelSellOrder ```solidity function cancelSellOrder(uint64 orderId) external nonpayable ``` * Function cancels given sell order based on provided idCancels sell order with given id. * Transfers back collateral to the client address. * only executable when market is not closed and will cancel only if executed by order owner (client address) * reverts when orderId does not exist * follows Checks-Effects-Interactions pattern\* **Parameters** | Name | Type | Description | | ------- | ------ | ------------------ | | orderId | uint64 | Order id to cancel | ## OrderBookGeneralFacet > Order Book General Facet - Allows to query order book for publicly available properties. *Contract mostly returns some useful values around order book* ### OrderBookGeneralFacet - Methods #### bestBidOffer ```solidity function bestBidOffer() external view returns (uint256) ``` * Return best bid offer and best ask offer *best buy = 128 bits (64 quantity | 64 price) | best sell = 128 bits (64 quantity | 64 price)* **Returns** | Name | Type | Description | | ---- | ------- | --------------------------- | | \_0 | uint256 | Returns best bid\&ask offer | #### bestFiftyOffers ```solidity function bestFiftyOffers() external view returns (uint256[], uint256[]) ``` * Return up to best 50 bids and asksIf there is less than 50 orders in either buy or sell side element 0 will be returned but \* arrays returned will always be fixed size *Description about returned variables- tuple with 2 arrays, with fixed size of 50 elements- (best\_bids\[50], best\_asks\[50])- each element represents order data (quantity and price)- each order is a 256 bit unsigned integer, bits 0...63 represents price, 64...127 quantity* **Returns** | Name | Type | Description | | ---- | ---------- | -------------------------- | | \_0 | uint256\[] | bids array of best 50 bids | | \_1 | uint256\[] | asks array of best 50 asks | #### countBuyOrders ```solidity function countBuyOrders() external view returns (uint256) ``` * Function counts active buy orders in the order book **Returns** | Name | Type | Description | | ---- | ------- | -------------------------------------- | | \_0 | uint256 | Returns count of all active buy orders | #### countSellOrders ```solidity function countSellOrders() external view returns (uint256) ``` * Function counts active sell orders in the order book **Returns** | Name | Type | Description | | ---- | ------- | --------------------------------------- | | \_0 | uint256 | Returns count of all active sell orders | #### getConfig ```solidity function getConfig() external view returns (struct LibOrderBookStructs.OrderBookConfig) ``` *Retrieves the configuration settings.* **Returns** | Name | Type | Description | | ---- | ----------------------------------- | --------------------------- | | \_0 | LibOrderBookStructs.OrderBookConfig | The configuration settings. | * Returned structure has following fields: ``` struct OrderBookConfig { Scales scales; uint64 makerCommission; uint64 takerCommission; uint64 marketMakerCommission; address quoteToken; address baseToken; address whitelist; address commissionWallet; address baseTokenFallbackWallet; address quoteTokenFallbackWallet; uint8 liquidityBand; bytes11 version; } struct Scales { TokenScales base; TokenScales quote; } struct TokenScales { uint128 nonNative; uint128 native; } ``` | Name | Type | Description | | ------------------------ | ------- | -------------------------------------------------------------------------------- | | scales | struct | holds information about scales for base and quote tokens | | makerCommission | uint64 | maker commission (fee) | | takerCommission | uint64 | taker commission (fee) | | marketMakerCommission | uint64 | market maker commission (fee) | | quoteToken | address | quote token contract address | | baseToken | address | base token contract address | | whitelist | address | whitelist contract address | | commissionWallet | address | account where all fees are transferred | | baseTokenFallbackWallet | address | account where funds are held if it was not possible to transfer it to the owner | | quoteTokenFallbackWallet | address | account where funds are held if it was not possible to transfer it to the ownere | | liquidityBand | uint8 | liquidity band to be compliant with ESMA | | version | bytes11 | version of the smart contract | #### getLiquidityBand ```solidity function getLiquidityBand() external view returns (uint8) ``` **Returns** | Name | Type | Description | | ---- | ----- | ---------------------------------------- | | \_0 | uint8 | Liquidity band - in compliance with ESMA | #### getOrderBookPhase ```solidity function getOrderBookPhase() external view returns (enum LibEnums.OrderBookPhases) ``` * Method informs about current Order Book phase **Returns** | Name | Type | Description | | ---- | ----------------------------- | ------------- | | \_0 | enum LibEnums.OrderBookPhases | current phase | * Returned enum has following fields: ``` enum OrderBookPhases { None, /// * The initial state before the order book is opened OpenForTrading, /// * The order book is open and orders can be placed and filled ClosedForTrading, /// * The order book is closed and no trading can occur ManualHalt, /// * Trading is halted manually by an administrator or owner AutomaticHalt /// *Trading is halted automatically due to predefined conditions } ``` #### getOrderDetails ```solidity function getOrderDetails(uint64 orderId) external view returns (struct LibOrderBookStructs.Order) ``` **Parameters** | Name | Type | Description | | ------- | ------ | -------------------------------------------- | | orderId | uint64 | Order id established during placing an order | **Returns** | Name | Type | Description | | ---- | ------------------------- | ------------------------- | | \_0 | LibOrderBookStructs.Order | struct with order details | * Retunrned structure has following fields: ``` struct Order { uint256 timestamp; uint64 quantity; uint64 price; uint64 clientId; uint64 orderId; uint64 prevOrderId; uint64 nextOrderId; uint32 crossIdentifier; LibEnums.OrderKind orderKind; uint8 lifetime; } ``` | Name | Type | Description | | --------------- | ------- | ------------------------------------------------------------------------- | | timestamp | uint256 | timestamp of an order, when it was placed | | quantity | uint64 | quantity of an order | | price | uint64 | price of an order | | clientId | uint64 | client identifier, assigned by whitelist contract | | orderId | uint64 | order identifier, assigned by order book | | prevOrderId | uint64 | prev order id in the order book | | nextOrderId | uint64 | next order Id in the order book | | crossIdentifier | uint32 | cross identifier which helps distinguish orders from the same party | | orderKind | enum | kept information about an order if it was BUY or SELL | | lifetime | uint8 | lifetime of an order in days, used for Good till date execution condition | #### getPreTradeControlConfig ```solidity function getPreTradeControlConfig() external view returns (struct LibOrderBookControl.OrderBookPreTradeStorage) ``` *Retrieves the current pre-trade control configuration.* **Returns** | Name | Type | Description | | ---- | -------------------------------------------- | ------------------------------------ | | \_0 | LibOrderBookControl.OrderBookPreTradeStorage | The pre-trade control configuration. | * Returned structure has following fields: ``` struct OrderBookPreTradeStorage { uint256 maxValue; uint128 minValue; uint64 priceCollarFactor; uint64 maxMatches; } ``` | Name | Type | Description | | ----------------- | ------- | -------------------------------------------------------------- | | maxValue | uint256 | maximum value of an order that can be placed | | minValue | uint128 | minimum value of an order that can be placed | | priceCollarFactor | uint64 | multiplier used during pre trade controls | | maxMatches | uint64 | maximum number of matches that can happen with one transaction | #### getStaticRefPrice ```solidity function getStaticRefPrice() external view returns (uint64) ``` *Retrieves the current static reference price.* **Returns** | Name | Type | Description | | ---- | ------ | --------------------------- | | \_0 | uint64 | The static reference price. | #### getVolatilityManagementConfig ```solidity function getVolatilityManagementConfig() external view returns (struct LibOrderBookControl.VolatilityManagementStorage) ``` *Retrieves the current volatility management configuration.* **Returns** | Name | Type | Description | | ---- | ----------------------------------------------- | ---------------------------------------- | | \_0 | LibOrderBookControl.VolatilityManagementStorage | The volatility management configuration. | * Returned structure has following fields: ``` struct VolatilityManagementStorage { uint64 dynamicRefPrice; uint64 staticThreshold; uint64 dynamicThreshold; bool isDynamicCheckEnabled; } ``` | Name | Type | Description | | --------------------- | ------ | --------------------------------------------------------------------------------- | | dynamicRefPrice | uint64 | The dynamic reference price considered also as last execution price on the market | | staticThreshold | uint64 | prevents drastic changes on the market, provided as a percentage value. | | dynamicThreshold | uint64 | prevents drastic changes on the market, provided as a percentage value | | isDynamicCheckEnabled | bool | configuration flag responsible for checking dynamic reference price | ### OrderBook - Events #### NewBuyInitiatedTrade ```solidity event NewBuyInitiatedTrade(address indexed buyer, address indexed seller, uint256 fromQuantity, uint256 toQuantity, uint64 price, uint64 indexed sellOrderId, uint256 buyerCommission, uint256 sellerCommission, uint64 tradeSeq, uint64 incomingBuyOrderId) ``` * Event emitted after new buy is initiated **Parameters** | Name | Type | Description | | --------------------- | ------- | ---------------------------------------------------- | | buyer `indexed` | address | Buyer address | | seller `indexed` | address | Seller address | | fromQuantity | uint256 | From quantity | | toQuantity | uint256 | To quantity | | price | uint64 | Price of trade | | sellOrderId `indexed` | uint64 | Sell id | | buyerCommission | uint256 | Buyer commission | | sellerCommission | uint256 | Seller commission | | tradeSeq | uint64 | Tarde sequence number | | incomingBuyOrderId | uint64 | unique identifier for the order that caused matching | #### NewBuyOrder ```solidity event NewBuyOrder(address indexed client, uint64 quantity, uint64 price, uint64 indexed orderId) ``` Event emitted after new buy order is added to list **Parameters** | Name | Type | Description | | ----------------- | ------- | ---------------------------------------- | | client `indexed` | address | Buyer address | | quantity | uint64 | Quantity of buy order | | price | uint64 | Price of buy order | | orderId `indexed` | uint64 | OrderId of buy order added by order book | #### NewSellInitiatedTrade ```solidity event NewSellInitiatedTrade(address indexed buyer, address indexed seller, uint256 fromQuantity, uint256 toQuantity, uint64 price, uint64 indexed buyOrderId, uint256 buyerCommission, uint256 sellerCommission, uint64 tradeSeq, uint256 reimbursement, uint64 incomingSellOrderId) ``` * Event emitted when sell initiated trade **Parameters** | Name | Type | Description | | -------------------- | ------- | ------------------------------------------------ | | buyer `indexed` | address | Buyer of trade | | seller `indexed` | address | Seller of trade | | fromQuantity | uint256 | From quantity | | toQuantity | uint256 | To quantity | | price | uint64 | Price of trade | | buyOrderId `indexed` | uint64 | Buy order id | | buyerCommission | uint256 | Buyer commission | | sellerCommission | uint256 | Seller commission | | tradeSeq | uint64 | Trade sequence number | | reimbursement | uint256 | Reimbursement amount | | incomingSellOrderId | uint64 | unique identifier of order which caused matching | #### NewSellOrder ```solidity event NewSellOrder(address indexed client, uint64 quantity, uint64 price, uint64 indexed orderId) ``` Event emitted after new sell order is added to list **Parameters** | Name | Type | Description | | ----------------- | ------- | ------------------------------------------ | | client `indexed` | address | Client address | | quantity | uint64 | Quantity of sell order | | price | uint64 | Price of sell order | | orderId `indexed` | uint64 | Order id of sell order added by order book | #### OrderReceived ```solidity event OrderReceived(address indexed client, uint64 indexed orderId, uint64 quantity, uint64 price, enum LibEnums.OrderKind side, bytes reportingData, uint64 crossIdentifier, enum LibEnums.OrderType orderType, enum LibEnums.OrderExecutionCondition executionCondition) ``` Event emitted when new order is received **Parameters** | Name | Type | Description | | ------------------ | ------------------------------------- | ------------------------------------------------------------------------------------------------------ | | client `indexed` | address | Client address | | orderId `indexed` | uint64 | unique identifier of an order | | quantity | uint64 | Quantity of the order | | price | uint64 | Limit price of the order | | side | enum LibEnums.OrderKind | Side of the order - buy / sell | | reportingData | bytes | Reporting data sent with order | | crossIdentifier | uint64 | Cross identifier of the order | | orderType | enum LibEnums.OrderType | Type of the order - market / limit | | executionCondition | enum LibEnums.OrderExecutionCondition | execution condition of order i.e GoodForDay, GoodTillDate, BookOrCancel, FillOrKill, ImmediateOrCancel | #### OrderRejected ```solidity event OrderRejected(address indexed client, uint64 indexed orderId, uint64 quantity, uint64 price, uint64 quantityNotExecuted, enum LibOrderBookEvents.RejectionReasons reason, enum LibEnums.OrderKind side) ``` **Parameters** | Name | Type | Description | | ------------------- | ---------------------------------------- | ------------------------------ | | client `indexed` | address | Client address | | orderId `indexed` | uint64 | unique order identifier | | quantity | uint64 | Quantity of the order | | price | uint64 | Limit price of the order | | quantityNotExecuted | uint64 | Quantity that was not executed | | reason | enum LibOrderBookEvents.RejectionReasons | Order rejection reason | | side | enum LibEnums.OrderKind | Side of the order - buy / sell | #### CancelOrder ```solidity event CancelOrder(address indexed client, uint64 quantity, uint64 price, uint64 indexed orderId, enum LibLinkedList.CancellationType cancellationType, address tokenAddress, address toAddress) ``` Event emitted after order is canceled by participant or admin. **Parameters** | Name | Type | Description | | ----------------- | ----------------------------------- | --------------------------------------- | | client `indexed` | address | Client address | | quantity | uint64 | Quantity of order | | price | uint64 | Price of order | | orderId `indexed` | uint64 | OrderId of order added by order book | | cancellationType | enum LibLinkedList.CancellationType | Type of cancellation | | tokenAddress | address | Token address | | toAddress | address | Address where collateral is transferred | ### OrderBook - Errors #### OrderBook\_ExcludedForAdmin ```solidity error OrderBook_ExcludedForAdmin() ``` * Error thrown when admin is trying to call function that is restricted to clients #### OrderBook\_ForbiddenDueToMarketStatus ```solidity error OrderBook_ForbiddenDueToMarketStatus(enum LibEnums.OrderBookPhases currentPhase) ``` * This error is thrown when an action is forbidden due to the current market status **Parameters** | Name | Type | Description | | ------------ | ----------------------------- | -------------------------------------------------------------------------- | | currentPhase | enum LibEnums.OrderBookPhases | The current phase of the order book that caused the action to be forbidden | #### OrderBook\_InvalidExecutionCondition ```solidity error OrderBook_InvalidExecutionCondition(uint8 executionCondition) ``` * Error thrown when order execution condition is not valid **Parameters** | Name | Type | Description | | ------------------ | ----- | ---------------------------- | | executionCondition | uint8 | execution condition provided | #### OrderBook\_InvalidInputOrderData ```solidity error OrderBook_InvalidInputOrderData() ``` * Error thrown when order data is not valid - can't be parsed #### OrderBook\_InvalidOrderKind ```solidity error OrderBook_InvalidOrderKind(enum LibEnums.OrderKind orderKind) ``` * Error thrown when order kind is not valid **Parameters** | Name | Type | Description | | --------- | ----------------------- | ------------------------ | | orderKind | enum LibEnums.OrderKind | order kind (buy or sell) | #### OrderBook\_InvalidOrderLifetime ```solidity error OrderBook_InvalidOrderLifetime() ``` * Error thrown when lifetime parameter within order data for GoodTillDate/BookOrCancel is greater than 90 #### OrderBook\_InvalidOrderType ```solidity error OrderBook_InvalidOrderType(uint8 orderType) ``` * Error thrown when order type is not valid **Parameters** | Name | Type | Description | | --------- | ----- | ------------- | | orderType | uint8 | type or order | #### OrderBook\_NotAllowedToBuy ```solidity error OrderBook_NotAllowedToBuy() ``` * Error thrown when client is not allowed to buy #### OrderBook\_NotAllowedToSell ```solidity error OrderBook_NotAllowedToSell() ``` * Error thrown when client is not allowed to sell #### OrderBook\_PreTradeControlOrderValueAboveMaxRange ```solidity error OrderBook_PreTradeControlOrderValueAboveMaxRange() ``` * Error thrown when order value (orderQuantity \* orderPrice) is above max range #### OrderBook\_PreTradeControlOrderValueBelowMinRange ```solidity error OrderBook_PreTradeControlOrderValueBelowMinRange() ``` * Error thrown when order value (orderQuantity \* orderPrice) is below min range #### OrderBook\_PreTradeControlOrderVolumeAboveMaxRange ```solidity error OrderBook_PreTradeControlOrderVolumeAboveMaxRange() ``` * Error thrown when order volume (orderQuantity \* referencePrice) is above max range #### OrderBook\_PreTradeControlOrderVolumeBelowMinRange ```solidity error OrderBook_PreTradeControlOrderVolumeBelowMinRange() ``` * Error thrown when order volume (orderQuantity \* referencePrice) is below min range #### OrderBook\_PreTradeControlPriceAboveMaxRange ```solidity error OrderBook_PreTradeControlPriceAboveMaxRange() ``` * Error thrown when order price is above max range #### OrderBook\_PreTradeControlPriceBelowMinRange ```solidity error OrderBook_PreTradeControlPriceBelowMinRange() ``` * Error thrown when order price is below min range #### OrderBook\_TickSize\_InvalidPrice ```solidity error OrderBook_TickSize_InvalidPrice(uint256 price, uint256 tickSize) ``` * Error thrown when price can be divided by the tick size with rest **Parameters** | Name | Type | Description | | -------- | ------- | --------------------------- | | price | uint256 | price provided | | tickSize | uint256 | ticksize for provided price | #### ReentrancyShield\_ReentrantCall ```solidity error ReentrancyShield_ReentrantCall() ``` * Error thrown on reentrant call #### SafeERC20FailedOperation ```solidity error SafeERC20FailedOperation(address token) ``` *An operation with an ERC-20 token failed.* **Parameters** | Name | Type | Description | | ----- | ------- | ------------------ | | token | address | address of a token | #### TransfersNotAccepted\_NativeCurrencyNotAccepted ```solidity error TransfersNotAccepted_NativeCurrencyNotAccepted() ``` Error thrown when some native currency is sent to contract #### AccessManaged\_Unauthorized ```solidity error AccessManaged_Unauthorized(address caller) ``` * Error thrown when caller is not authorized. **Parameters** | Name | Type | Description | | ------ | ------- | -------------------------- | | caller | address | address which caused error | **Parameters** | Name | Type | Description | | ------------ | ----------------------------- | -------------------------------------------------------------------------- | | currentPhase | enum LibEnums.OrderBookPhases | The current phase of the order book that caused the action to be forbidden | #### OrderBook\_InvalidClient ```solidity error OrderBook_InvalidClient() ``` * Error thrown when client is not allowed to access order #### OrderBook\_NoSuchOrderId ```solidity error OrderBook_NoSuchOrderId(uint64 orderId) ``` * Error thrown when code is trying to access an order with id that not exists in the order book **Parameters** | Name | Type | Description | | ------- | ------ | ------------------------- | | orderId | uint64 | provided order identifier | #### OrderBook\_NotAllowedToCancel ```solidity error OrderBook_NotAllowedToCancel() ``` * Error thrown when client is not allowed to cancel order --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.21x.eu/order-book/orderbook.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.