Skip to main content

Book Key

Understanding the BookKey​

Clober offers an efficient order book system for complex digital asset exchanges. At the heart of this system is the BookManager contract, which plays a crucial role in identifying and managing each orderbook.

BookKey serves as a unique identifier for orderbooks within the BookManager. This structure consists of the base currency, quote currency, unit size, fee policies for the maker and taker, and hooks. Let's dive deeper into each element.

BookKey Structure​

/**
 * @notice This structure represents a unique identifier for a book in the BookManager.
 * @param base The base currency of the book
 * @param unit_size The unit size of the book
 * @param quote The quote currency of the book
 * @param maker_policy The maker fee policy of the book
 * @param hooks The hooks contract of the book
 * @param taker_policy The taker fee policy of the book
 */
#[derive(Copy, Drop, Hash, Serde)]
pub struct BookKey {
    pub base: ContractAddress,
    pub quote: ContractAddress,
    pub hooks: Hooks,
    pub unit_size: u64,
    pub maker_policy: FeePolicy,
    pub taker_policy: FeePolicy,
}

Attributes of BookKey​

  • base: Token address of the base asset. For example, ETH is the base asset of the ETH-USDC market.
  • unit_size: The trading unit size in the order book. It affects trade precision and the minimum/maximum tradeable quantity.
  • quote: Token address of the quote asset. For example, USDC is the quote asset of the ETH-USDC market.
  • maker_policy: Fee policy for the maker orders.
  • hooks: A contract enabling custom logic execution at various trading stages, facilitating the expansion of order book functionalities.
  • taker_policy: Fee policy for the taker orders.

Book Id​

BookManager communicates with users using the hashed value of the book_key, called book_id, because the BookKey itself contains too much data to transmit. The book_id is generated by hashing the BookKey struct with the Poseidon Hash function, then taking the first 187 bits of the resulting value.

#[generate_trait]
pub impl BookKeyImpl of BookKeyTrait {
    fn to_id(self: BookKey) -> felt252 {
        let hash = PoseidonTrait::new().update_with(self).finalize();
        // @dev Use 187 bits of the hash as the key.
        (hash.into() & 0x7ffffffffffffffffffffffffffffffffffffffffffffff_u256).try_into().unwrap()
    }
}