Skip to main content

Controller

The Controller contract is a high-level abstraction layer that facilitates essential interactions between users and Clober’s core contract, BookManager. Through this interface, users can conveniently and intuitively perform various order-related actions within a single contract. For example, by leveraging Starknet’s MultiCall, they can open a Book, create limit orders (Make, Limit), consume liquidity with market orders (Take, Spend), claim proceeds from executed orders (Claim), or cancel any unfilled portion of those orders (Cancel)—all through a single endpoint.

Simplified Order Management

By interacting with the BookManager via the Controller interface, users can reduce overall system complexity.

Support for Various Order Actions

  • Open: Initiates a new Book, users can configure parameters such as quote, base, fee, and hook, enabling them to conduct a wide range of trades using that particular Book.
fn open(
    ref self: TContractState,
    book_key: BookKey,
    hook_data: Span<felt252>,
    deadline: u64
) -> felt252
  • Make: Creates a limit order at a specific price (tick) by supplying a certain quote amount as liquidity.
fn make(
    ref self: TContractState,
    book_id: felt252,
    tick: Tick,
    quote_amount: u256,
    hook_data: Span<felt252>,
    deadline: u64
) -> felt252
  • Limit: Similar to Make, but it also executes a Take on the opposite Book simultaneously. This logic mirrors the traditional Limit Order concept found on centralized exchanges (CEXs).
fn limit(
    ref self: TContractState,
    take_book_id: felt252,
    make_book_id: felt252,
    limit_price: u256,
    tick: Tick,
    quote_amount: u256,
    take_hook_data: Span<felt252>,
    make_hook_data: Span<felt252>,
    deadline: u64
) -> felt252
  • Take: Executes a market order that consumes liquidity from existing limit orders. Within a single call, it can move through multiple ticks to acquire the required amount of quote tokens. The Controller automatically obtains the necessary base tokens from the user.
fn take(
    ref self: TContractState,
    book_id: felt252,
    limit_price: u256,
    quote_amount: u256,
    max_base_amount: u256,
    hook_data: Span<felt252>,
    deadline: u64
)
  • Spend: Similar to "Take," but here you first commit a certain amount of base tokens, using them to execute a market order and thereby acquire quote tokens.
fn spend(
    ref self: TContractState,
    book_id: felt252,
    limit_price: u256,
    base_amount: u256,
    min_quote_amount: u256,
    hook_data: Span<felt252>,
    deadline: u64
)
  • Claim: Allows users to claim base tokens obtained from previously executed orders, thereby realizing the profits from a completed trade.
fn claim(
    ref self: TContractState,
    order_id: felt252,
    hook_data: Span<felt252>,
    deadline: u64
)
  • Cancel: Cancels unfilled (or partially filled) orders and returns the remaining quote tokens to the user.
fn cancel(
    ref self: TContractState,
    order_id: felt252,
    left_quote_amount: u256,
    hook_data: Span<felt252>,
    deadline: u64
)

State Query Functions

Internally referencing the BookManager, the Controller provides pre-trade state information through several functions:

  • get_depth: Retrieves the available quote liquidity for a given Book and tick.
/**
 * @notice Returns the depth of a book
 * @param book_id The id of the book
 * @param tick The tick of the book
 * @return The depth of the book in quote amount
 */
fn get_depth(self: @TContractState, book_id: felt252, tick: Tick) -> u64
  • get_highest_price: Returns the highest order price in the Book.
/**
 * @notice Returns the highest price of a book
 * @param book_id The id of the book
 * @return The highest price of the book with 2**96 precision
 */
fn get_highest_price(self: @TContractState, book_id: felt252) -> u256
  • get_order: Provides details for a given order_id, including the order’s provider, price, remaining quote amount, and claimable base amount.
/**
 * @notice Returns the details of an order
 * @param order_id The id of the order
 * @return provider The address of the provider of the order
 * @return price The price of the order with 2**96 precision
 * @return open_amount The open quote amount of the order
 * @return claimable_amount The claimable base amount of the order
 */
fn get_order(
    self: @TContractState,
    order_id: felt252
) -> (ContractAddress, u256, u256, u256)

Armed with this information, users can accurately assess the order book’s state before executing trades, making more informed decisions.

Tick-Price Conversion Support:

The Controller supports functions for converting between ticks and prices:

  • from_price: Converts a given price (with 2**96 precision) into a tick value.
/**
 * @notice Converts a price to a tick
 * @param price The price to convert
 * @return The tick
 */
fn from_price(self: @TContractState, price: u256) -> Tick
  • to_price: Converts a tick value back into a price (2**96 precision).
/**
 * @notice Converts a tick to a price
 * @param tick The tick to convert
 * @return The price with 2**96 precision
 */
fn to_price(self: @TContractState, tick: Tick) -> u256

This feature frees users from manually managing tick calculations, enabling more intuitive price handling.