MatchingEngine

The MatchingEngine contract is an on-chain matching engine for executing orders. It allows users to trade assets using limit and market orders.

State Variables

Name	Type	Description
feeTo	address	Address of the fee recipient.
feeDenom	uint256	Denominator for calculating the fee.
feeNum	uint256	Numerator for calculating the fee.
orderbookFactory	address	Address of the orderbook factory contract.
lFeeToken	address	Address of the listing fee token.
lFeeAmount	uint256	Listing fee token amount in 1e18.
membership	address	Address of the membership contract.
accountant	address	Address of the accountant contract.

Events

OrderCanceled

Event emitted when an order is canceled.

Name	Type	Description
orderbook	address	The address of the orderbook contract.
id	uint256	The ID of the canceled order.
isBid	bool	Flag indicating whether the order is a bid or ask.
owner	address	The address of the order owner.

OrderMatched

Event emitted when an order is matched.

Name	Type	Description
orderbook	address	The address of the orderbook contract.
id	uint256	The ID of the matched order.
isBid	bool	Flag indicating whether the order is a bid or ask.
sender	address	The address of the sender executing the order.
owner	address	The address of the order owner.
amount	uint256	The amount of the order executed.
price	uint256	The price at which the order was matched.

PairAdded

Event emitted when a trading pair is added to the orderbook.

Name	Type	Description
orderbook	address	The address of the orderbook contract.
base	address	The address of the base asset in the trading pair.
quote	address	The address of the quote asset in the trading pair.

Functions

initialize

initialize(
    address orderbookFactory_,
    address feeToken_,
    uint256 feeAmountOne_
) external onlyRole(DEFAULT_ADMIN_ROLE) initializer

Initializes the matching engine with the orderbook factory and listing requirements.

Parameters

Parameter	Type	Description
orderbookFactory_	address	Address of the orderbook factory contract.
feeToken_	address	Address of the listing fee token.
feeAmountOne_	uint256	Listing fee token amount in 1e18 (scaled decimal).

Requirements:

• The caller must have the DEFAULT_ADMIN_ROLE.

setListingFee

solidityCopy codefunction setListingFee(
    address feeToken_,
    uint256 feeAmountOne_
) external onlyRole(DEFAULT_ADMIN_ROLE)

Sets the listing requirements.

Parameters

Name	Type	Description
feeToken_	address	Address of the listing fee token.
feeAmountOne_	uint256	Listing fee token amount in 1e18 (scaled decimal).

Requirements:

• The caller must have the DEFAULT_ADMIN_ROLE.

setOrderbookFactory

solidityCopy codefunction setOrderbookFactory(
    address orderbookFactory_
) external onlyRole(DEFAULT_ADMIN_ROLE)

Sets the address of the orderbook factory.

Parameter	Type	Description
orderbookFactory_	address	Address of the orderbook factory contract.

Requirements:

• The caller must have the DEFAULT_ADMIN_ROLE.

setMembership

solidityCopy codefunction setMembership(
    address membership_
) external onlyRole(DEFAULT_ADMIN_ROLE)

Sets the address of the membership contract.

• membership_(address): Address of the membership contract.

Requirements:

• The caller must have the DEFAULT_ADMIN_ROLE.

setAccountant

solidityCopy codefunction setAccountant(
    address accountant_
) external onlyRole(DEFAULT_ADMIN_ROLE)

Sets the address of the accountant contract.

• accountant_(address): Address of the accountant contract.

Requirements:

• The caller must have the DEFAULT_ADMIN_ROLE.

setFee

solidityCopy codefunction setFee(
    uint256 feeNum_,
    uint256 feeDenom_
) external onlyRole(DEFAULT_ADMIN_ROLE)

Sets the fee numerator and denominator of trading.

• feeNum_(uint256): The numerator of the fee fraction.

• feeDenom_(uint256): The denominator of the fee fraction.

Requirements:

• The caller must have the DEFAULT_ADMIN_ROLE.

• The fee numerator and denominator must be valid.

setFeeTo

solidityCopy codefunction setFeeTo(address feeTo_) external onlyRole(DEFAULT_ADMIN_ROLE)

Sets the fee recipient.

• feeTo_(address): Address of the fee recipient.

Requirements:

• The caller must have the DEFAULT_ADMIN_ROLE.

marketBuy

solidityCopy codefunction marketBuy(
    address base,
    address quote,
    uint256 amount,
    bool isMaker,
    uint32 n,
    uint32 uid
) external returns (bool)

Executes a market buy order, buying the base asset using the quote asset at the best available price in the orderbook up to n orders, and makes an order at the market price.

Parameters

Parameter	Type	Description
base	address	Address of the base asset for the trading pair.
quote	address	Address of the quote asset for the trading pair.
amount	uint256	The amount of quote asset to be used for the market buy order.
isMaker	bool	Boolean indicating if an order should be made at the market price in the orderbook.
n	uint32	The maximum number of orders to match in the orderbook.
uid	uint32	User ID associated with the order (optional).

Returns

• true if the order was successfully executed, otherwise false.

marketSell

solidityCopy codefunction marketSell(
    address base,
    address quote,
    uint256 amount,
    bool isMaker,
    uint32 n,
    uint32 uid
) external returns (bool)

Executes a market sell order, selling the base asset for the quote asset at the best available price in the orderbook up to n orders, and makes an order at the market price.

Parameters

Name	Type	Description
base	address	Address of the base asset for the trading pair.
quote	address	Address of the quote asset for the trading pair.
amount	uint256	The amount of quote asset to be used for the market buy order.
isMaker	bool	Boolean indicating if an order should be made at the market price in the orderbook.
n	uint32	The maximum number of orders to match in the orderbook.
uid	uint32	User ID associated with the order (optional).

Returns

• true if the order was successfully executed, otherwise false.

limitBuy

solidityCopy codefunction limitBuy(
    address base,
    address quote,
    uint256 amount,
    uint256 at,
    bool isMaker,
    uint32 n,
    uint32 uid
) external returns (bool)

Executes a limit buy order, places a limit order in the orderbook for buying the base asset using the quote asset at a specified price, and makes an order at the limit price.

Parameters

Name	Type	Description
base	address	Address of the base asset for the trading pair.
quote	address	Address of the quote asset for the trading pair.
amount	uint256	The amount of quote asset to be used for the market buy order.
isMaker	bool	Boolean indicating if an order should be made at the market price in the orderbook.
n	uint32	The maximum number of orders to match in the orderbook.
uid	uint32	User ID associated with the order (optional).

Returns

• true if the order was successfully executed, otherwise false.

limitSell

solidityCopy codefunction limitSell(
    address base,
    address quote,
    uint256 amount,
    uint256 at,
    bool isMaker,
    uint32 n,
    uint32 uid
) external returns (bool)

Executes a limit sell order, places a limit order in the orderbook for selling the base asset for the quote asset at a specified price, and makes an order at the limit price.

Parameters

Name	Type	Description
base	address	Address of the base asset for the trading pair.
quote	address	Address of the quote asset for the trading pair.
amount	uint256	The amount of quote asset to be used for the market buy order.
isMaker	bool	Boolean indicating if an order should be made at the market price in the orderbook.
n	uint32	The maximum number of orders to match in the orderbook.
uid	uint32	User ID associated with the order (optional).

Returns

• true if the order was successfully executed, otherwise false.

makeBuy

solidityCopy codefunction makeBuy(
    address base,
    address quote,
    uint256 amount,
    uint256 at,
    uint32 uid
) external returns (bool)

Stores a bid order in the orderbook for the base asset using the quote asset, with a specified price at.

Parameters

Name	Type	Description
base	address	Address of the base asset for the trading pair.
quote	address	Address of the quote asset for the trading pair.
amount	uint256	The amount of quote asset to be used for the bid order.
at	uint256	The price at which the bid order will be stored in the bid-ask spread.
uid	uint32	User ID associated with the order (optional).

Returns

• true if the order was successfully executed, otherwise false.

makeSell

solidityCopy codefunction makeSell(
    address base,
    address quote,
    uint256 amount,
    uint256 at,
    uint32 uid
) external returns (bool)

Stores an ask order in the orderbook for the quote asset using the base asset, with a specified price at.

Parameters

Name	Type	Description
base	address	Address of the base asset for the trading pair.
quote	address	Address of the quote asset for the trading pair.
amount	uint256	The amount of quote asset to be used for the bid order.
at	uint256	The price at which the bid order will be stored in the bid-ask spread.
uid	uint32	User ID associated with the order (optional).

Returns

• true if the order was successfully executed, otherwise false.

addPair

solidityCopy codefunction addPair(
    address base,
    address quote
) external returns (address book)

Creates an orderbook for a new trading pair and returns its address.

Parameters

Parameter	Type	Description
base	address	Address of the base asset for the trading pair.
quote	address	Address of the quote asset for the trading pair.

Returns

• book: The address of the newly created orderbook.

cancelOrder

solidityCopy codefunction cancelOrder(
    address orderbook,
    uint256 orderId,
    bool isBid,
    uint32 uid
) external returns (bool)

Cancels an order in an orderbook by the given order ID and order type.

Parameters

Name	Type	Description
orderbook	address	The address of the orderbook to cancel the order in.
orderId	uint256	The ID of the order to cancel.
isBid	bool	Boolean indicating if the order to cancel is an ask order (false for bid order).
uid	uint32	User ID associated with the order (optional).

Returns

• true if the order was successfully canceled, otherwise false.

getOrderbookById

solidityCopy codefunction getOrderbookById(uint256 id) external view returns (address)

Returns the address of the orderbook with the given ID.

Parameters

Name	Type	Description
id	uint256	The ID of the orderbook to retrieve

Returns

• The address of the orderbook.

getBaseQuote

solidityCopy codefunction getBaseQuote(address orderbook) external view returns (address base, address quote)

Returns the base and quote asset addresses for the given orderbook.

Parameters

Name	Type	Description
orderbook	address	The address of the orderbook to retrieve assets for.

Returns

Name	Type	Description
base	address	The address of the base asset.
quote	address	The address of the quote asset.

getFee

solidityCopy codefunction getFee() external view returns (uint256 numerator, uint256 denominator)

Returns the fee numerator and denominator.

Returns:

• numerator(uint256): The fee numerator.

• denominator(uint256): The fee denominator.

getFeeTo

solidityCopy codefunction getFeeTo() external view returns (address)

Returns the address of the fee recipient.

Returns:

• The address of the fee recipient.

getOrderbookFactory

solidityCopy codefunction getOrderbookFactory() external view returns (address)

Returns the address of the orderbook factory contract.

Returns:

• The address of the orderbook factory contract.

getListingFee

solidityCopy codefunction getListingFee() external view returns (address, uint256)

Returns the listing fee token address and amount.

Returns:

• feeToken(address): The address of the listing fee token.

• feeAmount(uint256): The listing fee token amount.

getMembership

solidityCopy codefunction getMembership() external view returns (address)

Returns the address of the membership contract.

Returns:

• The address of the membership contract.

getAccountant

solidityCopy codefunction getAccountant() external view returns (address)

Returns the address of the accountant contract.

Returns:

• The address of the accountant contract.