Guides

DeepBook

Here you can read about DeepBook - the order book on Sui.

Suggest Edits

Overview

DeepBook is the first order book on Sui, representing its liquidity layer and creating a decentralized and permissionless environment to support token trades. It doesn't have a ready-made user interface but rather offers built-in trading functionality that can support token trades from decentralized exchanges, wallets, or other apps via its SDK.

DeepBook has a central limit order book (CLOB) design that enables market and limit orders. One can:

  • sell SUI tokens, or make an ask;
  • reset one's price, or make a limit order;
  • sell SUI tokens at the market's current rate;
  • buy SUI tokens, or make a bid;
  • pay the current market price;
  • set a limit amount at which one is willing to pay.

📘

Limit orders only get fulfilled if the CLOB finds a match between a buyer and seller. If no such match is found, DeepBook automatically pools the asks to meet the quantity of the proposed bid.

DeepBook operates principally as a digital ledger, logging bids and asks in chronological order and automatically finding matches between them.

Design

In its architecture, DeepBook leverages Sui's Narwhal and Bullshark engine to minimize contention and achieve high throughput through transaction parallelization (for more info on transactions, read this article).

DeepBook employs a super-efficient approach to storing orders:

  1. Each pool stores the unfilled maker orders.
  2. Taker orders are filled instantaneously within the same transaction the order is submitted.
  3. Bid and ask orders are stored separately, each with a two-level nested crit-bit tree.
  4. Pool is the central structure in DeepBook. A globally shared Pool is established for every trading pair of base-and-quote assets, managing open orders on the order book and overseeing orders' placement, cancellation, and settlement. This structure allows transactions across different trading pairs to be parallelized, optimizing throughput. The first-level crit-bit tree is ordered using the price of the maker order, and the second-level crit-bit tree is ordered using the order ID of the maker order, as shown in the figure below.

  1. Orders are prioritized by value, as shown in the figure below.

Orders are placed following these arrangements:

  1. DeepBook supports the placement of market orders and limit orders.
  2. When users submit a market order, it is matched against the existing maker orders on the order book instantaneously in the same transaction upon submission of the market order.
  3. When users submit a limit order, it is first matched against the existing maker orders as a taker order.
  4. If the order cannot be fully filled, the remaining quantity can either be injected as a maker order or be dropped, depending on the configuration of the limit order.

Functions

The table below lists the functions DeepBook supports.

FunctionDescription
Place OrderMaking a bid or an ask order. In DeepBook, there are two types of orders: limit orders and market orders.
For a limit order, you need to create a custodian account the first time you interact with a particular pool and deposit assets to the pool.
Cancel OrderCanceling the previously placed order.
Cancel All OrdersCanceling all limit orders under a certain account capacity.
Match OrderThe process where a taker order is submitted to the CLOB and immediately matched with existing maker orders in the same transaction.
Batch Cancel OrdersCanceling multiple limit orders to save gas costs.
Track OrderDeepBook efficiently tracks maker orders, allowing users to query order status via the Sui RPC call and subscribe to an event stream for updates on order status changes, including OrderPlaced, OrderFilled, and OrderCanceled events.
Query PoolQuerying order, pool, and user account status using API.
Route SwapTo use the smart routing functionality, the optimal route must be found. The route uses a Depth-First Search (DFS) algorithm to find all the routes in the swap pools and a dry run to simulate how much token one can get from each route. The function will return the best route that can provide the maximum tokens.
Create PoolCreating a DeepBook Pool.
Limit OrderPutting restrictions on a limit order. There are four types of restrictions that you could put on limit orders.
NO_RESTRICTION: 0

Fill as much as possible in the current transaction as a taker, and inject the remaining as a maker order.

IMMEDIATE_OR_CANCEL: 1

Fill as much quantity as possible in the current transaction as a taker, and cancel the rest of the order.

FILL_OR_KILL: 2

Only fill if the entire order size can be filled as a taker in the current transaction. Otherwise, abort the entire transaction.

POST_OR_ABORT: 3

Only proceed if the entire order size can be posted to the order book as a maker in the current transaction. Otherwise, abort the entire transaction.
Deposit AssetTraders could deposit base/quote assets into their custodian account and later use it to place limit orders.

Updated 5 months ago