CrystalMarket

Each order book pair is deployed as a seperate composable, permissionless, and immutable contract.

Functions

highestBid

function highestBid() external view returns (uint256 highestBid)

Returns the current highest bid.

Return Values

Name	Type	Description
highestBid	uint256	Value of the highest bid.

lowestAsk

function lowestAsk() external view returns (uint256 lowestAsk)

Returns the current lowest bid.

Return Values

Name	Type	Description
lowestAsk	uint256	Value of the lowest ask.

latestUserId

function latestUserId() external view returns (uint256 latestUserId)

Returns the most recently assigned user ID.

Return Values

Name	Type	Description
latestUserId	uint256	Value of latestUserId

quoteAsset

function quoteAsset() external view returns (address quoteAsset)

Returns the contract address of the quote asset.

Return Values

Name	Type	Description
quoteAsset	address	Address of the quote asset

baseAsset

function baseAsset() external view returns (address baseAsset)

Returns the contract address of the base asset.

Return Values

Name	Type	Description
baseAsset	address	The address of the base asset

router

function router() external view returns (address router)

Returns the address of the router.

Return Values

Name	Type	Description
containi	address	The address of the router contract associated with this contract.

feeAddress

function feeAddress() external view returns (address feeAddress)

Returns the address that receives the fee.

Return Values

Name	Type	Description
feeAddress	address	The address designated to receive the contract fees.

fee

function fee() external view returns (uint256 fee)

Returns the taker order fee rate. To convert to percentage, the formula is (100,000-fee)/1,000. For example, a fee value of 99,970 would result in a fee rate of (100,000-99,970)/1,000 = 0.03%.

Return Values

Name	Type	Description
fee	uint256	The current fee

maxPrice

function maxPrice() external view returns (uint256 maxPrice)

Returns the maximum price for orders.

Return Values

Name	Type	Description
maxPrice	uint256	The maximum allowable price

scaleFactor

function scaleFactor() external view returns (uint256 scaleFactor)

Returns the factor used to scale prices within the contract.

Return Values

Name	Type	Description
scaleFactor	uint256	Multiplier or divisor used when scaling prices

minSize

function minSize() external view returns (uint256 minSize)

Returns the minimum trade/order size.

Return Values

Name	Type	Description
minSize	uint256	The minimum permissible quantity.

orders

function orders(uint256 price, uint256 orderId) external view returns (Order memory)

Retrieves an Order based on specified price and orderId.

Parameters

Name	Type	Description
price	uint256	The price level key
orderId	uint256	The order's unique identifier within price

Return Values

Name	Type	Description
order	Order	Order struct containing information about the specified order

priceLevels

function priceLevels(uint256 price) external view returns (PriceLevel memory)

Returns the PriceLevel.

Parameters

Name	Type	Description
price	uint256	Price key for the price level

Return Values

Name	Type	Description
priceLevel	PriceLevel	PriceLevel struct containing information at the specified price

userIdToAddress

function userIdToAddress(uint256 userId) external view returns (address userIdToAddress)

Returns the address mapped to userId.

Parameters

Name	Type	Description
userID	uint256	The userID

Return Values

Name	Type	Description
userIdToAddress	address	The address associated with the given userId

addressToUserId

function addressToUserId(address user) external view returns (uint256 addressToUserId)

Retrieves the user ID associated with a given address.

Parameters

Name	Type	Description
user	address	The address for which to retrieve the user ID

Return Values

Name	Type	Description
addressToUserId	uint256	The numeric user ID corresponding to user

accumulatedFeeQuote

function accumulatedFeeQuote(address user) external view returns (uint256 accumulatedFeeQuote)

Returns the accumulated quote-asset fees for a user.

Parameters

Name	Type	Description
user	address	The address of the retrieved quote-asset fees

Return Values

Name	Type	Description
accumulatedFeeQuote	uint256	Total acucmulated fee quote recorded for the user

accumulatedFeeBase

function accumulatedFeeBase(address user) external view returns (uint256 accumulatedFeeBase)

Returns the accumulated base-asset fees for a user.

Parameters

Name	Type	Description
user	address	The address of the user

Return Values

Name	Type	Description
accumulatedFeeBase	uint256	The total accumulated fee base recorded for the user

getPriceLevels

function getPriceLevels(bool isAscending, uint256 startPrice, uint256 distance) public view returns (bytes memory _orders)

Retrieves a list of initialized price levels and their respective sizes.

Parameters

Name	Type	Description
isAscending	boolean	If true, search for price levels in the space above startPrice, otherwise search below
startPrice	uint256	Start price, inclusive
distance	uint256	How many price increments to check

Return Values

Name	Type	Description
_orders	bytes memory	Byte string containing 32 byte chunks, with the first 16 bytes the price and last 16 bytes the sum of all order sizes at the price level

getPriceLevelsFromMid

function getPriceLevelsFromMid(uint256 distance) external view returns (uint256 _highestBid, uint256 _lowestAsk, bytes memory buyOrders, bytes memory sellOrders)

Retrieves a list of initialized price levels and their respective sizes starting from the bid-ask spread, searching both above and below.

Parameters

Name	Type	Description
distance	uint256	How many price increments to check each way

Return Values

Name	Type	Description
_highestBid	bytes memory	The price of the highest buy order
_lowestAsk	uint256	The price of the lowest sell order
buyOrders	bytes memory	Byte string representing all buy orders within distance of the bid-ask spread
sellOrders	bytes memory	Byte string representing all sell orders within distance of the bid-ask spread

getQuote

function getQuote(bool isBuy, bool isExactInput, uint256 size, uint256 worstPrice) external view returns (uint256 amountIn, uint256 amountOut)

Calculates the expected input/output amount of a trade with worstPrice as the worst acceptable price.

Parameters

Name	Type	Descsription
isBuy	bool	Buy order if true, otherwise sell order
isExactInput	bool	If true, input amount is specified, otherwise output amount is specified
size	uint256	Input/output size depending on isExactInput
worstPrice	uint256	Worst acceptable price at which order execution will terminate

Return Values

Name	Type	Description
amountIn	uint256	Calculated input amount
amountOut	uint256	Calculated output amount

changeMaxPrice

function changeMaxPrice(uint256 newMaxPrice) external 

Updates the maximum price of this market.

Parameters

Name	Type	Description
newMaxPrice	uint256	The new maximum price

changeFee

function changeFee(uint256 newFee) external

Updates the taker fee rate of this market. The maximum possible taker fee is 5%.

Parameters

Name	Type	Description
newFee	uint256	The new taker fee rate

changeGov

function changeGov(address newGov) external

Updates the governance address of this market. The governance address is the fee recipient and can change the maximum price and fee rate of this market.

Parameters

Name	Type	Description
newGov	address	The new governance address

marketOrder

function marketOrder(bool isBuy, bool isExactInput, bool isFromCaller, bool isToCaller, uint256 orderType, uint256 size, uint256 worstPrice, address caller, address referrer) external returns (uint256 amountIn, uint256 amountOut, uint256 id)

Places a taker order.

Parameters

Name	Type	Descsription
isBuy	bool	Buy order if true, otherwise sell order
isExactInput	bool	If true, input amount is specified, otherwise output amount is specified
isFromCaller	bool	If true, transfer tokens from the caller address, otherwise transfer tokens from msg.sender
isToCaller	bool	If true, transfer tokens to the caller address, otherwise transfer tokens to msg.sender
orderType	uint256	Order type (0 = partial fill, 1 = complete fill, 2 = market to limit)
size	uint256	Token amount to swap from/to depending on exactInput
worstPrice	uint256	Worst acceptable price
caller	address	Equal to msg.sender unless the caller is the router, in which this parameter would be the address that called the router
referrer	address	Referrer address

Return Values

Name	Type	Descsription
amountIn	uint256	Executed input amount
amountOut	uint256	Executed output amount
id	uint256	Limit order id if applicable

limitOrder

function limitOrder(bool isBuy, uint256 price, uint256 size, address from, address owner) external returns (uint256 id)

Places a post-only maker order.

Parameters

Name	Type	Descsription
isBuy	bool	Buy order if true, otherwise sell order
price	uint256	Limit price
size	uint256	Input token amount
from	address	Address to transfer tokens from, must be either caller or msg.sender
owner	address	Equal to msg.sender unless the caller is the router, in which this parameter would be the address that called the router

Return Values

Name	Type	Descsription
id	uint256	Limit order id

cancelOrder

function cancelOrder(uint256 price, uint256 id, address to, address owner) external

Cancels an existing limit order.

Parameters

Name	Type	Descsription
price	uint256	Price of order to cancel
id	uint256	Id of order to cancel
to	address	Address to transfer remaining tokens to
owner	address	Equal to msg.sender unless the caller is the router, in which this parameter would be the address that called the router

Return Values

Name	Type	Descsription
size	uint256	Order size at cancel in terms of quote token multiplied by scale factor

registerUser

function registerUser(address caller) external returns (uint256 _latestUserId)

Allows an address to place limit orders, required to be called once per market. The router takes care of this automatically.

Parameters

Name	Type	Descsription
caller	address	Equal to msg.sender unless the caller is the router, in which this parameter would be the address that called the router

Return Values

Name	Type	Descsription
_latestUserId	uint256	The user's id, only used internally

claimFees

function claimFees(address caller) external

Claim accumulated referral fees and rebates for address caller.

Parameters

Name	Type	Descsription
caller	address	Equal to msg.sender unless the caller is the router, in which this parameter would be the address that called the router

batchOrders

function batchOrders(uint256[] calldata actions, uint256[] calldata prices, uint256[] calldata param1, address[] calldata param2, address owner) external returns (uint256[] memory returnData)

Executes multiple actions in a single transaction. Individual actions fail silently, returning 0 as the returnData value upon failure.

Parameters

Name	Type	Descsription
actions	address	List of actions to perform (0 = cancel, 1 = limit buy, 2 = limit sell, 3 = market buy, 4 = market sell)
prices	uint256[] calldata	The price level to place/cancel limit orders, or the worst acceptable price for market orders
param1	uint256[] calldata	The order size for market/limit orders or the id of the order to cancel
param2	address[] calldata	The address to transfer tokens from for market/limit orders, or the market to transfer tokens to for order cancelations. Must be either the router address or msg.sender
owner	address	Equal to msg.sender unless the caller is the router, in which this parameter would be the address that called the router

Return Values

Name	Type	Descsription
returnData	uint256[] memory	List of output amounts for market orders, ids for limit orders, and sizes at cancel for order cancellations

Fallback

The fallback function is gas-optimized and intended for use by market makers and other high frequency automated trading strategies. Calldata is in 32 byte chunks, with the first byte being the action (0 = cancel, 1 = limit buy, 2 = limit sell, 3 = market buy, 4 = market sell), trailing 10 bytes of the first 16 bytes being the price level to place/cancel limit orders, or the worst acceptable price for market orders, and last 16 bytes being the order size for market/limit orders or the id of the order to cancel. Each 32 byte chunk represents an action, and msg.sender is used as all address parameters for each action.

Events

OrderFilled

event OrderFilled(address indexed caller, uint256 amounts, uint256 info, bytes filled);

Emitted at the conclusion of a successful taker order.

Parameters

Name	Type	Description
caller	address indexed	The address of the user who placed the trade.
amounts	uint256	The first 16 bytes represent the input amount of the trade denominated in the input token. The last 16 bytes represent the output amount of the trade denominated in the output token.
info	uint256	The first bit of this value represents whether it is a buy or sell order (1 is buy). The last 16 bytes represent the last filled price of the order.
filled	bytes	Each 32 byte chunk of this bytes array represents a filled or partially filled maker order. The first 10 bytes represent the price of the order, next 6 represent the id, and last 16 represent the updated size of the order following the trade. Price is in the form of quote amount * scale factor / base amount, while size is in the form of quote amount * scale factor.

OrdersUpdated

event OrdersUpdated(address indexed caller, bytes orderData);

Emitted at the conclusion of a successful batch of limit order placement/cancelations.

Parameters

Name	Type	Description
caller	address indexed	The address of the user who is placing/canceling trades.
orderData	bytes	Each 32 byte chunk of this bytes array represents a newly placed or canceled maker order. The first bit represents the action (3 = cancel buy, 2 = cancel sell, 1 = buy, 0 = sell). The first 10 bytes excluding the first bit represent the price of the order, next 6 represent the id, and last 16 represent the size of the order or the size of the order prior to cancellation. Price is in the form of quote amount * scale factor / base amount, while size is in the form of quote amount * scale factor.