Query the Pool
This documentation is for version 3 of DeepBook. For documentation on version 2 of DeepBook, see DeepBookV2 docs.
The Pool shared object represents a market, such as a SUI/USDC market. That Pool is the only one representing that unique pairing (SUI/USDC) and the pairing is the only member of that particular Pool. See DeepBook Design to learn more about the structure of pools.
To perform trades, you pass a BalanceManager and TradeProof into the relevant Pool. Unlike Pools, BalanceManager shared objects can contain any type of token, such that the same BalanceManager can access multiple Pools to interact with many different trade pairings. See BalanceManager to learn more.
API
DeepBook exposes a set of endpoints that can be used to query any pool.
Check whitelist status
Accessor to check whether the pool is whitelisted.
public fun whitelisted<BaseAsset, QuoteAsset>(
self: &Pool<BaseAsset, QuoteAsset>,
): bool {
self.load_inner().state.governance().whitelisted()
}
Check quote quantity against base
Dry run to determine the quote quantity out for a given base quantity.
public fun get_quote_quantity_out<BaseAsset, QuoteAsset>(
self: &Pool<BaseAsset, QuoteAsset>,
base_quantity: u64,
clock: &Clock,
): (u64, u64, u64) {
self.get_quantity_out(base_quantity, 0, clock)
}
Check base quantity against quote
Dry run to determine the base quantity out for a given quote quantity.
public fun get_base_quantity_out<BaseAsset, QuoteAsset>(
self: &Pool<BaseAsset, QuoteAsset>,
quote_quantity: u64,
clock: &Clock,
): (u64, u64, u64) {
self.get_quantity_out(0, quote_quantity, clock)
}
Check quote quantity against quote or base
Dry run to determine the quantity out for a given base or quote quantity. Only one out of base or quote quantity should be non-zero. Returns the (base_quantity_out, quote_quantity_out, deep_quantity_required).
public fun get_quantity_out<BaseAsset, QuoteAsset>(
self: &Pool<BaseAsset, QuoteAsset>,
base_quantity: u64,
quote_quantity: u64,
clock: &Clock,
): (u64, u64, u64) {
let whitelist = self.whitelisted();
let self = self.load_inner();
let params = self.state.governance().trade_params();
let (taker_fee, _) = (params.taker_fee(), params.maker_fee());
let deep_price = self.deep_price.get_order_deep_price(whitelist);
self
.book
.get_quantity_out(
base_quantity,
quote_quantity,
taker_fee,
deep_price,
self.book.lot_size(),
clock.timestamp_ms(),
)
}
Check fee required
Returns the DEEP required for an order if it's a taker or maker given quantity and price (deep_required_taker, deep_required_maker).
public fun get_order_deep_required<BaseAsset, QuoteAsset>(
self: &Pool<BaseAsset, QuoteAsset>,
base_quantity: u64,
price: u64,
): (u64, u64) {
let order_deep_price = self.get_order_deep_price();
let self = self.load_inner();
let maker_fee = self.state.governance().trade_params().maker_fee();
let taker_fee = self.state.governance().trade_params().taker_fee();
let deep_quantity = order_deep_price.deep_quantity(
base_quantity,
math::mul(base_quantity, price),
);
(math::mul(taker_fee, deep_quantity), math::mul(maker_fee, deep_quantity))
}
Retrieve mid price for a pool
Returns the mid price of the pool.
public fun mid_price<BaseAsset, QuoteAsset>(
self: &Pool<BaseAsset, QuoteAsset>,
clock: &Clock,
): u64 {
self.load_inner().book.mid_price(clock.timestamp_ms())
}
Retrieve order IDs
Returns the order_id for all open orders for the balance_manager in the pool.
public fun account_open_orders<BaseAsset, QuoteAsset>(
self: &Pool<BaseAsset, QuoteAsset>,
balance_manager: &BalanceManager,
): VecSet<u128> {
let self = self.load_inner();
if (!self.state.account_exists(balance_manager.id())) {
return vec_set::empty()
};
self.state.account(balance_manager.id()).open_orders()
}
Retrieve prices and quantities for an order book
Returns vectors holding the prices (price_vec) and quantities (quantity_vec) for the level2 order book. The price_low and price_high are inclusive, all orders within the range are returned. is_bid is true for bids and false for asks.
public fun get_level2_range<BaseAsset, QuoteAsset>(
self: &Pool<BaseAsset, QuoteAsset>,
price_low: u64,
price_high: u64,
is_bid: bool,
clock: &Clock,
): (vector<u64>, vector<u64>) {
self
.load_inner()
.book
.get_level2_range_and_ticks(
price_low,
price_high,
constants::max_u64(),
is_bid,
clock.timestamp_ms(),
)
}
Returns vectors holding the prices (price_vec) and quantities (quantity_vec) for the level2 order book. ticks are the maximum number of ticks to return starting from best bid and best ask. (bid_price, bid_quantity, ask_price, ask_quantity) are returned as four vectors. The price vectors are sorted in descending order for bids and ascending order for asks.
public fun get_level2_ticks_from_mid<BaseAsset, QuoteAsset>(
self: &Pool<BaseAsset, QuoteAsset>,
ticks: u64,
clock: &Clock,
): (vector<u64>, vector<u64>, vector<u64>, vector<u64>) {
let self = self.load_inner();
let (bid_price, bid_quantity) = self
.book
.get_level2_range_and_ticks(
constants::min_price(),
constants::max_price(),
ticks,
true,
clock.timestamp_ms(),
);
let (ask_price, ask_quantity) = self
.book
.get_level2_range_and_ticks(
constants::min_price(),
constants::max_price(),
ticks,
false,
clock.timestamp_ms(),
);
(bid_price, bid_quantity, ask_price, ask_quantity)
}
Retrieve balances
Get all balances held in this pool.
public fun vault_balances<BaseAsset, QuoteAsset>(
self: &Pool<BaseAsset, QuoteAsset>,
): (u64, u64, u64) {
self.load_inner().vault.balances()
}
Retrieve pool ID
Get the ID of the pool given the asset types.
public fun get_pool_id_by_asset<BaseAsset, QuoteAsset>(
registry: &Registry,
): ID {
registry.get_pool_id<BaseAsset, QuoteAsset>()
}
Retrieve order information
Returns the Order struct using the order ID.
public fun get_order<BaseAsset, QuoteAsset>(
self: &Pool<BaseAsset, QuoteAsset>,
order_id: u128,
): Order {
self.load_inner().book.get_order(order_id)
}
Returns a vector of Order structs using a vector of order IDs.
public fun get_orders<BaseAsset, QuoteAsset>(
self: &Pool<BaseAsset, QuoteAsset>,
order_ids: vector<u128>,
): vector<Order> {
let mut orders = vector[];
let mut i = 0;
while (i < order_ids.length()) {
let order_id = order_ids[i];
orders.push_back(self.get_order(order_id));
i = i + 1;
};
orders
}
Returns a vector of Order structs for all orders that belong to a BalanceManager in the pool.
public fun get_account_order_details<BaseAsset, QuoteAsset>(
self: &Pool<BaseAsset, QuoteAsset>,
balance_manager: &BalanceManager,
): vector<Order> {
let acct_open_orders = self
.account_open_orders(balance_manager)
.into_keys();
self.get_orders(acct_open_orders)
}
Retrieve locked balance
Returns the locked balance for a BalanceManager in the pool (base_quantity, quote_quantity, deep_quantity).
public fun locked_balance<BaseAsset, QuoteAsset>(
self: &Pool<BaseAsset, QuoteAsset>,
balance_manager: &BalanceManager,
): (u64, u64, u64) {
let account_orders = self.get_account_order_details(balance_manager);
let self = self.load_inner();
if (!self.state.account_exists(balance_manager.id())) {
return (0, 0, 0)
};
let mut base_quantity = 0;
let mut quote_quantity = 0;
let mut deep_quantity = 0;
account_orders.do_ref!(|order| {
let maker_fee = self.state.history().historic_maker_fee(order.epoch());
let (base, quote, deep) = order.locked_balance(maker_fee);
base_quantity = base_quantity + base;
quote_quantity = quote_quantity + quote;
deep_quantity = deep_quantity + deep;
});
let settled_balances = self
.state
.account(balance_manager.id())
.settled_balances();
base_quantity = base_quantity + settled_balances.base();
quote_quantity = quote_quantity + settled_balances.quote();
deep_quantity = deep_quantity + settled_balances.deep();
(base_quantity, quote_quantity, deep_quantity)
}
Retrieve pool parameters
Returns the trade parameters for the pool (taker_fee, maker_fee, stake_required).
public fun pool_trade_params<BaseAsset, QuoteAsset>(
self: &Pool<BaseAsset, QuoteAsset>,
): (u64, u64, u64) {
let self = self.load_inner();
let taker_fee = self.state.governance().trade_params().taker_fee();
let maker_fee = self.state.governance().trade_params().maker_fee();
let stake_required = self
.state
.governance()
.trade_params()
.stake_required();
(taker_fee, maker_fee, stake_required)
}
Returns the book parameters for the pool (tick_size, lot_size, min_size).
public fun pool_book_params<BaseAsset, QuoteAsset>(
self: &Pool<BaseAsset, QuoteAsset>,
): (u64, u64, u64) {
let self = self.load_inner();
let tick_size = self.book.tick_size();
let lot_size = self.book.lot_size();
let min_size = self.book.min_size();
(tick_size, lot_size, min_size)
}
Returns the OrderDeepPrice struct for the pool, which determines the conversion for DEEP fees.
public fun get_order_deep_price<BaseAsset, QuoteAsset>(
self: &Pool<BaseAsset, QuoteAsset>,
): OrderDeepPrice {
let whitelist = self.whitelisted();
let self = self.load_inner();
self.deep_price.get_order_deep_price(whitelist)
}