DeepBook Protocol

DeepBook is a decentralized central limit order book (CLOB) built natively on Sui. It provides efficient on-chain trading with minimal MEV and high throughput.

Overview

DeepBook enables:

Order Book Trading: Limit and market orders
Atomic Matching: Instant order matching in a single transaction
Low Latency: Leveraging Sui’s parallel execution
Deep Liquidity: Aggregated order book for all trading pairs
MEV Protection: Fair order execution

Core Modules

clob_v2.move

The main CLOB implementation (v2 is the current version). Key Types:

struct Pool<BaseAsset, QuoteAsset> has key {
    id: UID,
    bids: CritbitTree<TickLevel>,
    asks: CritbitTree<TickLevel>,
    // ... other fields
}

struct Order has store {
    order_id: u64,
    price: u64,
    quantity: u64,
    is_bid: bool,
    owner: address,
    // ... other fields
}

Key Functions:

// Create new pool
public fun create_pool<BaseAsset, QuoteAsset>(
    tick_size: u64,
    lot_size: u64,
    min_size: u64,
    ctx: &mut TxContext
): Pool<BaseAsset, QuoteAsset>

// Place limit order
public fun place_limit_order<BaseAsset, QuoteAsset>(
    pool: &mut Pool<BaseAsset, QuoteAsset>,
    price: u64,
    quantity: u64,
    is_bid: bool,
    account_cap: &AccountCap,
    ctx: &mut TxContext
): u64 // returns order_id

// Place market order
public fun place_market_order<BaseAsset, QuoteAsset>(
    pool: &mut Pool<BaseAsset, QuoteAsset>,
    quantity: u64,
    is_bid: bool,
    base_coin: Coin<BaseAsset>,
    quote_coin: Coin<QuoteAsset>,
    clock: &Clock,
    ctx: &mut TxContext
): (Coin<BaseAsset>, Coin<QuoteAsset>)

// Cancel order
public fun cancel_order<BaseAsset, QuoteAsset>(
    pool: &mut Pool<BaseAsset, QuoteAsset>,
    order_id: u64,
    account_cap: &AccountCap
): (u64, u64) // returns (base_quantity, quote_quantity)

// Get best bid price
public fun best_bid_price<BaseAsset, QuoteAsset>(
    pool: &Pool<BaseAsset, QuoteAsset>
): Option<u64>

// Get best ask price
public fun best_ask_price<BaseAsset, QuoteAsset>(
    pool: &Pool<BaseAsset, QuoteAsset>
): Option<u64>

custodian_v2.move

Manages user accounts and balances within DeepBook. Key Types:

struct AccountCap has key, store {
    id: UID,
    owner: address,
}

struct Account<BaseAsset, QuoteAsset> has store {
    available_balance: Balance<BaseAsset>,
    locked_balance: Balance<BaseAsset>,
    // ... other fields
}

Key Functions:

// Create account
public fun create_account(ctx: &mut TxContext): AccountCap

// Deposit
public fun deposit<Asset>(
    account_cap: &AccountCap,
    coin: Coin<Asset>,
    custodian: &mut Custodian
)

// Withdraw
public fun withdraw<Asset>(
    account_cap: &AccountCap,
    amount: u64,
    custodian: &mut Custodian,
    ctx: &mut TxContext
): Coin<Asset>

order_query.move

Provides read-only functions for querying order book state. Key Functions:

// Get orders for account
public fun get_orders<BaseAsset, QuoteAsset>(
    pool: &Pool<BaseAsset, QuoteAsset>,
    account_cap: &AccountCap
): vector<Order>

// Get market price
public fun get_market_price<BaseAsset, QuoteAsset>(
    pool: &Pool<BaseAsset, QuoteAsset>
): u64

// Get order book depth
public fun get_level2_book_status<BaseAsset, QuoteAsset>(
    pool: &Pool<BaseAsset, QuoteAsset>,
    price_low: u64,
    price_high: u64,
    side: u8
): (vector<u64>, vector<u64>) // returns (prices, quantities)

Usage Examples

Create a Trading Pool

use deepbook::clob_v2;
use sui::coin::{Coin, SUI};

struct USDC has drop {}

public fun create_sui_usdc_pool(ctx: &mut TxContext) {
    let pool = clob_v2::create_pool<SUI, USDC>(
        1_000_000, // tick_size: 0.001 USDC
        1_000_000, // lot_size: 0.001 SUI
        1_000_000, // min_size: 0.001 SUI
        ctx
    );
    
    transfer::share_object(pool);
}

Place Limit Order

use deepbook::clob_v2;
use deepbook::custodian_v2;

public fun place_bid(
    pool: &mut Pool<SUI, USDC>,
    account_cap: &AccountCap,
    price: u64,
    quantity: u64,
    ctx: &mut TxContext
) {
    let order_id = clob_v2::place_limit_order(
        pool,
        price,
        quantity,
        true, // is_bid
        account_cap,
        ctx
    );
    
    // Order placed, order_id can be used to cancel
}

Place Market Order

public fun swap_sui_for_usdc(
    pool: &mut Pool<SUI, USDC>,
    sui_coin: Coin<SUI>,
    clock: &Clock,
    ctx: &mut TxContext
): Coin<USDC> {
    let quantity = coin::value(&sui_coin);
    
    let (remaining_sui, usdc) = clob_v2::place_market_order(
        pool,
        quantity,
        true, // buying USDC with SUI (bid)
        sui_coin,
        coin::zero<USDC>(ctx),
        clock,
        ctx
    );
    
    // Handle remaining SUI if any
    if (coin::value(&remaining_sui) > 0) {
        transfer::public_transfer(remaining_sui, tx_context::sender(ctx));
    } else {
        coin::destroy_zero(remaining_sui);
    };
    
    usdc
}

Cancel Order

public fun cancel_my_order(
    pool: &mut Pool<SUI, USDC>,
    order_id: u64,
    account_cap: &AccountCap,
    ctx: &mut TxContext
) {
    let (base_returned, quote_returned) = clob_v2::cancel_order(
        pool,
        order_id,
        account_cap
    );
    
    // Funds returned to account balance
}

Query Order Book

use deepbook::order_query;

public fun get_best_prices<BaseAsset, QuoteAsset>(
    pool: &Pool<BaseAsset, QuoteAsset>
): (Option<u64>, Option<u64>) {
    let best_bid = clob_v2::best_bid_price(pool);
    let best_ask = clob_v2::best_ask_price(pool);
    
    (best_bid, best_ask)
}

public fun get_order_book_depth<BaseAsset, QuoteAsset>(
    pool: &Pool<BaseAsset, QuoteAsset>,
    price_low: u64,
    price_high: u64
): (vector<u64>, vector<u64>) {
    order_query::get_level2_book_status(
        pool,
        price_low,
        price_high,
        0 // 0 for bids, 1 for asks
    )
}

Account Management

Create Account

use deepbook::custodian_v2;

public fun setup_trading_account(ctx: &mut TxContext) {
    let account_cap = custodian_v2::create_account(ctx);
    transfer::public_transfer(account_cap, tx_context::sender(ctx));
}

Deposit Funds

public fun deposit_funds<Asset>(
    account_cap: &AccountCap,
    coin: Coin<Asset>,
    custodian: &mut Custodian
) {
    custodian_v2::deposit(account_cap, coin, custodian);
}

Withdraw Funds

public fun withdraw_funds<Asset>(
    account_cap: &AccountCap,
    amount: u64,
    custodian: &mut Custodian,
    ctx: &mut TxContext
): Coin<Asset> {
    custodian_v2::withdraw(
        account_cap,
        amount,
        custodian,
        ctx
    )
}

Price Levels and Matching

DeepBook uses:

Tick Size: Minimum price increment
Lot Size: Minimum quantity increment
Price-Time Priority: Orders matched by price, then timestamp
Post-Only Orders: Optional for market makers
Fill-or-Kill: Optional for immediate execution

Best Practices

Use AccountCap: Always use account capabilities for custody
Handle Partial Fills: Market orders may be partially filled
Check Slippage: Monitor price impact for large orders
Cancel Stale Orders: Clean up unfilled orders
Query Before Trading: Check order book depth and spread

Integration Example

module my_dex::trader {
    use deepbook::clob_v2::{Self, Pool};
    use deepbook::custodian_v2::{Self, AccountCap};
    use sui::coin::{Self, Coin};
    use sui::sui::SUI;
    
    struct USDC has drop {}
    
    public fun init_and_trade(
        pool: &mut Pool<SUI, USDC>,
        sui_payment: Coin<SUI>,
        clock: &Clock,
        ctx: &mut TxContext
    ) {
        // Create account if needed
        let account_cap = custodian_v2::create_account(ctx);
        
        // Execute market order
        let (remaining_sui, usdc) = clob_v2::place_market_order(
            pool,
            coin::value(&sui_payment),
            true,
            sui_payment,
            coin::zero<USDC>(ctx),
            clock,
            ctx
        );
        
        // Transfer results
        transfer::public_transfer(usdc, tx_context::sender(ctx));
        transfer::public_transfer(remaining_sui, tx_context::sender(ctx));
        transfer::public_transfer(account_cap, tx_context::sender(ctx));
    }
}

JSON-RPC API

Rust SDK

GraphQL API

Framework

DeepBook Protocol

Overview

Core Modules

clob_v2.move

custodian_v2.move

order_query.move

Usage Examples

Create a Trading Pool

Place Limit Order

Place Market Order

Cancel Order

Query Order Book

Account Management

Create Account

Deposit Funds

Withdraw Funds

Price Levels and Matching

Best Practices

Integration Example

Resources

​Overview

​Core Modules

​clob_v2.move

​custodian_v2.move

​order_query.move

​Usage Examples

​Create a Trading Pool

​Place Limit Order

​Place Market Order

​Cancel Order

​Query Order Book

​Account Management

​Create Account

​Deposit Funds

​Withdraw Funds

​Price Levels and Matching

​Best Practices

​Integration Example

​Resources

Overview

Core Modules

clob_v2.move

custodian_v2.move

order_query.move

Usage Examples

Create a Trading Pool

Place Limit Order

Place Market Order

Cancel Order

Query Order Book

Account Management

Create Account

Deposit Funds

Withdraw Funds

Price Levels and Matching

Best Practices

Integration Example

Resources