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

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

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

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

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

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

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

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

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

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

function getLiquidityBand() external view returns (uint8)

Returns

Name	Type	Description
_0	uint8	Liquidity band - in compliance with ESMA

getOrderBookPhase

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

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

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

function getStaticRefPrice() external view returns (uint64)

Retrieves the current static reference price.

Returns

Name	Type	Description
_0	uint64	The static reference price.

getVolatilityManagementConfig

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

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

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

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

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

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

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

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

error OrderBook_ExcludedForAdmin()

• Error thrown when admin is trying to call function that is restricted to clients

OrderBook_ForbiddenDueToMarketStatus

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

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

error OrderBook_InvalidInputOrderData()

• Error thrown when order data is not valid - can't be parsed

OrderBook_InvalidOrderKind

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

error OrderBook_InvalidOrderLifetime()

• Error thrown when lifetime parameter within order data for GoodTillDate/BookOrCancel is greater than 90

OrderBook_InvalidOrderType

error OrderBook_InvalidOrderType(uint8 orderType)

• Error thrown when order type is not valid

Parameters

Name	Type	Description
orderType	uint8	type or order

OrderBook_NotAllowedToBuy

error OrderBook_NotAllowedToBuy()

• Error thrown when client is not allowed to buy

OrderBook_NotAllowedToSell

error OrderBook_NotAllowedToSell()

• Error thrown when client is not allowed to sell

OrderBook_PreTradeControlOrderValueAboveMaxRange

error OrderBook_PreTradeControlOrderValueAboveMaxRange()

• Error thrown when order value (orderQuantity * orderPrice) is above max range

OrderBook_PreTradeControlOrderValueBelowMinRange

error OrderBook_PreTradeControlOrderValueBelowMinRange()

• Error thrown when order value (orderQuantity * orderPrice) is below min range

OrderBook_PreTradeControlOrderVolumeAboveMaxRange

error OrderBook_PreTradeControlOrderVolumeAboveMaxRange()

• Error thrown when order volume (orderQuantity * referencePrice) is above max range

OrderBook_PreTradeControlOrderVolumeBelowMinRange

error OrderBook_PreTradeControlOrderVolumeBelowMinRange()

• Error thrown when order volume (orderQuantity * referencePrice) is below min range

OrderBook_PreTradeControlPriceAboveMaxRange

error OrderBook_PreTradeControlPriceAboveMaxRange()

• Error thrown when order price is above max range

OrderBook_PreTradeControlPriceBelowMinRange

error OrderBook_PreTradeControlPriceBelowMinRange()

• Error thrown when order price is below min range

OrderBook_TickSize_InvalidPrice

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

error ReentrancyShield_ReentrantCall()

• Error thrown on reentrant call

SafeERC20FailedOperation

error SafeERC20FailedOperation(address token)

An operation with an ERC-20 token failed.

Parameters

Name	Type	Description
token	address	address of a token

TransfersNotAccepted_NativeCurrencyNotAccepted

error TransfersNotAccepted_NativeCurrencyNotAccepted()

Error thrown when some native currency is sent to contract

AccessManaged_Unauthorized

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

error OrderBook_InvalidClient()

• Error thrown when client is not allowed to access order

OrderBook_NoSuchOrderId

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

error OrderBook_NotAllowedToCancel()

• Error thrown when client is not allowed to cancel order