Skip to main content

CloberOrderBook

CloberOrderBook

MakeOrder

event MakeOrder(address sender, address user, uint64 rawAmount, uint32 claimBounty, uint256 orderIndex, uint16 priceIndex, uint8 options)

Emitted when an order is created.

Parameters

NameTypeDescription
senderaddressThe address who sent the tokens to make the order.
useraddressThe address with the rights to claim the proceeds of the order.
rawAmountuint64The ordered raw amount.
claimBountyuint32
orderIndexuint256The order index.
priceIndexuint16The price book index.
optionsuint8LSB: 0 - Ask, 1 - Bid.

TakeOrder

event TakeOrder(address sender, address user, uint16 priceIndex, uint64 rawAmount, uint8 options)

Emitted when an order takes from the order book.

Parameters

NameTypeDescription
senderaddressThe address who sent the tokens to take the order.
useraddressThe recipient address of the traded token.
priceIndexuint16The price book index.
rawAmountuint64The ordered raw amount.
optionsuint8MSB: 0 - Limit, 1 - Market / LSB: 0 - Ask, 1 - Bid.

CancelOrder

event CancelOrder(address user, uint64 rawAmount, uint256 orderIndex, uint16 priceIndex, bool isBid)

Emitted when an order is canceled.

Parameters

NameTypeDescription
useraddressThe owner of the order.
rawAmountuint64The raw amount remaining that was canceled.
orderIndexuint256The order index.
priceIndexuint16The price book index.
isBidboolThe flag indicating whether it's a bid order or an ask order.

ClaimOrder

event ClaimOrder(address claimer, address user, uint64 rawAmount, uint256 bountyAmount, uint256 orderIndex, uint16 priceIndex, bool isBase)

Emitted when the proceeds of an order is claimed.

Parameters

NameTypeDescription
claimeraddressThe address that initiated the claim.
useraddressThe owner of the order.
rawAmountuint64The ordered raw amount.
bountyAmountuint256The size of the claim bounty.
orderIndexuint256The order index.
priceIndexuint16The price book index.
isBaseboolThe flag indicating whether the user receives the base token or the quote token.

Flash

event Flash(address caller, address borrower, uint256 quoteAmount, uint256 baseAmount, uint256 earnedQuote, uint256 earnedBase)

Emitted when a flash-loan is taken.

Parameters

NameTypeDescription
calleraddressThe caller address of the flash-loan.
borroweraddressThe address of the flash loan token receiver.
quoteAmountuint256The amount of quote tokens the user has borrowed.
baseAmountuint256The amount of base tokens the user has borrowed.
earnedQuoteuint256The amount of quote tokens the protocol earned in quote tokens.
earnedBaseuint256The amount of base tokens the protocol earned in base tokens.

Order

struct Order {
uint64 amount;
uint32 claimBounty;
address owner;
}

BlockTradeLog

struct BlockTradeLog {
uint64 blockTime;
uint64 askVolume;
uint64 bidVolume;
uint16 open;
uint16 high;
uint16 low;
uint16 close;
}

limitOrder

function limitOrder(address user, uint16 priceIndex, uint64 rawAmount, uint256 baseAmount, uint8 options, bytes data) external payable returns (uint256)

Take orders better or equal to the given priceIndex and make an order with the remaining tokens.

msg.value will be used as the claimBounty.

Parameters

NameTypeDescription
useraddressThe taker/maker address.
priceIndexuint16The price book index.
rawAmountuint64The raw quote amount to trade, utilized by bids.
baseAmountuint256The base token amount to trade, utilized by asks.
optionsuint8LSB: 0 - Ask, 1 - Bid. Second bit: 1 - Post only.
databytesCustom callback data

Return Values

NameTypeDescription
[0]uint256The order index. If an order is not made type(uint256).max is returned instead.

getExpectedAmount

function getExpectedAmount(uint16 limitPriceIndex, uint64 rawAmount, uint256 baseAmount, uint8 options) external view returns (uint256, uint256)

Returns the expected input amount and output amount.

Parameters

NameTypeDescription
limitPriceIndexuint16The price index to take until.
rawAmountuint64The raw amount to trade. Bid & expendInput => Used as input amount. Bid & !expendInput => Not used. Ask & expendInput => Not used. Ask & !expendInput => Used as output amount.
baseAmountuint256The base token amount to trade. Bid & expendInput => Not used. Bid & !expendInput => Used as output amount. Ask & expendInput => Used as input amount. Ask & !expendInput => Not used.
optionsuint8LSB: 0 - Ask, 1 - Bid. Second bit: 1 - expend input.

marketOrder

function marketOrder(address user, uint16 limitPriceIndex, uint64 rawAmount, uint256 baseAmount, uint8 options, bytes data) external

Take opens orders until certain conditions are met.

Parameters

NameTypeDescription
useraddressThe taker address.
limitPriceIndexuint16The price index to take until.
rawAmountuint64The raw amount to trade. This value is used as the maximum input amount by bids and minimum output amount by asks.
baseAmountuint256The base token amount to trade. This value is used as the maximum input amount by asks and minimum output amount by bids.
optionsuint8LSB: 0 - Ask, 1 - Bid. Second bit: 1 - expend input.
databytesCustom callback data.

cancel

function cancel(address receiver, struct OrderKey[] orderKeys) external

Cancel orders.

The length of orderKeys must be controlled by the caller to avoid block gas limit exceeds.

Parameters

NameTypeDescription
receiveraddressThe address to receive canceled tokens.
orderKeysstruct OrderKey[]The order keys of the orders to cancel.

claim

function claim(address claimer, struct OrderKey[] orderKeys) external

Claim the proceeds of orders.

The length of orderKeys must be controlled by the caller to avoid block gas limit exceeds.

Parameters

NameTypeDescription
claimeraddressThe address to receive the claim bounties.
orderKeysstruct OrderKey[]The order keys of the orders to claim.

getClaimable

function getClaimable(struct OrderKey orderKey) external view returns (uint64 claimableRawAmount, uint256 claimableAmount, uint256 feeAmount, uint256 rebateAmount)

Get the claimable proceeds of an order.

Parameters

NameTypeDescription
orderKeystruct OrderKeyThe order key of the order.

Return Values

NameTypeDescription
claimableRawAmountuint64The claimable raw amount.
claimableAmountuint256The claimable amount after fees.
feeAmountuint256The maker fee to be paid on claim.
rebateAmountuint256The rebate to be received on claim.

flash

function flash(address borrower, uint256 quoteAmount, uint256 baseAmount, bytes data) external

Flash loan the tokens in the OrderBook.

Parameters

NameTypeDescription
borroweraddressThe address to receive the loan.
quoteAmountuint256The quote token amount to borrow.
baseAmountuint256The base token amount to borrow.
databytesThe user's custom callback data.

quoteUnit

function quoteUnit() external view returns (uint256)

Returns the quote unit amount.

Return Values

NameTypeDescription
[0]uint256The amount that one raw amount represent in quote tokens.

makerFee

function makerFee() external view returns (int24)

Returns the maker fee. Paid to the maker when negative, paid by the maker when positive. Every 10000 represents a 1% fee on trade volume.

Return Values

NameTypeDescription
[0]int24The maker fee. 100 = 1bp.

takerFee

function takerFee() external view returns (uint24)

Returns the take fee Paid by the taker. Every 10000 represents a 1% fee on trade volume.

Return Values

NameTypeDescription
[0]uint24The taker fee. 100 = 1bps.

orderToken

function orderToken() external view returns (address)

Returns the address of the order NFT contract.

Return Values

NameTypeDescription
[0]addressThe address of the order NFT contract.

quoteToken

function quoteToken() external view returns (address)

Returns the address of the quote token.

Return Values

NameTypeDescription
[0]addressThe address of the quote token.

baseToken

function baseToken() external view returns (address)

Returns the address of the base token.

Return Values

NameTypeDescription
[0]addressThe address of the base token.

getDepth

function getDepth(bool isBid, uint16 priceIndex) external view returns (uint64)

Returns the current total open amount at the given price.

Parameters

NameTypeDescription
isBidboolThe flag to choose which side to check the depth for.
priceIndexuint16The price book index.

Return Values

NameTypeDescription
[0]uint64The total open amount.

getFeeBalance

function getFeeBalance() external view returns (uint128 quote, uint128 base)

Returns the fee balance that has not been collected yet.

Return Values

NameTypeDescription
quoteuint128The current fee balance for the quote token.
baseuint128The current fee balance for the base token.

uncollectedHostFees

function uncollectedHostFees(address token) external view returns (uint256)

Returns the amount of tokens that can be collected by the host.

Parameters

NameTypeDescription
tokenaddressThe address of the token to be collected.

Return Values

NameTypeDescription
[0]uint256The amount of tokens that can be collected by the host.

uncollectedProtocolFees

function uncollectedProtocolFees(address token) external view returns (uint256)

Returns the amount of tokens that can be collected by the dao treasury.

Parameters

NameTypeDescription
tokenaddressThe address of the token to be collected.

Return Values

NameTypeDescription
[0]uint256The amount of tokens that can be collected by the dao treasury.

isEmpty

function isEmpty(bool isBid) external view returns (bool)

Returns whether the order book is empty or not.

Parameters

NameTypeDescription
isBidboolThe flag to choose which side to check the emptiness of.

Return Values

NameTypeDescription
[0]boolWhether the order book is empty or not on that side.

getOrder

function getOrder(struct OrderKey orderKey) external view returns (struct CloberOrderBook.Order)

Returns the order information.

Parameters

NameTypeDescription
orderKeystruct OrderKeyThe order key of the order.

Return Values

NameTypeDescription
[0]struct CloberOrderBook.OrderThe order struct of the given order key.

bestPriceIndex

function bestPriceIndex(bool isBid) external view returns (uint16)

Returns the lowest ask price index or the highest bid price index.

Parameters

NameTypeDescription
isBidboolReturns the lowest ask price if false, highest bid price if true.

Return Values

NameTypeDescription
[0]uint16The current price index. If the order book is empty, it will revert.

blockTradeLogIndex

function blockTradeLogIndex() external view returns (uint16)

Returns the current block trade log index.

Return Values

NameTypeDescription
[0]uint16The current block trade log index.

blockTradeLogs

function blockTradeLogs(uint16 index) external view returns (struct CloberOrderBook.BlockTradeLog)

Returns the block trade log for a certain index.

Parameters

NameTypeDescription
indexuint16The block trade log index used to query the block trade log.

Return Values

NameTypeDescription
[0]struct CloberOrderBook.BlockTradeLogThe queried block trade log.

priceBook

function priceBook() external view returns (address)

Returns the address of the price book.

Return Values

NameTypeDescription
[0]addressThe address of the price book.

rawToBase

function rawToBase(uint64 rawAmount, uint16 priceIndex, bool roundingUp) external view returns (uint256)

Converts a raw amount to its corresponding base amount using a given price index.

Parameters

NameTypeDescription
rawAmountuint64The raw amount to be converted.
priceIndexuint16The index of the price to be used for the conversion.
roundingUpboolSpecifies whether the result should be rounded up or down.

Return Values

NameTypeDescription
[0]uint256The converted base amount.

rawToQuote

function rawToQuote(uint64 rawAmount) external view returns (uint256)

Converts a raw amount to its corresponding quote amount.

Parameters

NameTypeDescription
rawAmountuint64The raw amount to be converted.

Return Values

NameTypeDescription
[0]uint256The converted quote amount.

baseToRaw

function baseToRaw(uint256 baseAmount, uint16 priceIndex, bool roundingUp) external view returns (uint64)

Converts a base amount to its corresponding raw amount using a given price index.

Parameters

NameTypeDescription
baseAmountuint256The base amount to be converted.
priceIndexuint16The index of the price to be used for the conversion.
roundingUpboolSpecifies whether the result should be rounded up or down.

Return Values

NameTypeDescription
[0]uint64The converted raw amount.

quoteToRaw

function quoteToRaw(uint256 quoteAmount, bool roundingUp) external view returns (uint64)

Converts a quote amount to its corresponding raw amount.

Parameters

NameTypeDescription
quoteAmountuint256The quote amount to be converted.
roundingUpboolSpecifies whether the result should be rounded up or down.

Return Values

NameTypeDescription
[0]uint64The converted raw amount.

collectFees

function collectFees(address token, address destination) external

Collects fees for either the protocol or host.

Parameters

NameTypeDescription
tokenaddressThe token address to collect. It should be the quote token or the base token.
destinationaddressThe destination address to transfer fees. It should be the dao treasury address or the host address.

changeOrderOwner

function changeOrderOwner(struct OrderKey orderKey, address newOwner) external

Change the owner of the order.

Only the OrderToken contract can call this function.

Parameters

NameTypeDescription
orderKeystruct OrderKeyThe order key of the order.
newOwneraddressThe new owner address.

indexToPrice

function indexToPrice(uint16 priceIndex) external view returns (uint256)

Converts the price index into the actual price.

Parameters

NameTypeDescription
priceIndexuint16The price book index.

Return Values

NameTypeDescription
[0]uint256price The actual price.

priceToIndex

function priceToIndex(uint256 price, bool roundingUp) external view returns (uint16 index, uint256 correctedPrice)

Returns the price book index closest to the provided price.

Parameters

NameTypeDescription
priceuint256Provided price.
roundingUpboolDetermines whether to round up or down.

Return Values

NameTypeDescription
indexuint16The price book index.
correctedPriceuint256The actual price for the price book index.