forked from MystenLabs/sui
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
[docs] Deepbook v3 (MystenLabs#18530)
## Description Updates the deepbook documentation ## Test plan How did you test the new or updated feature? --- ## Release notes Check each box that your changes affect. If none of the boxes relate to your changes, release notes aren't required. For each box you select, include information after the relevant heading that describes the impact of your changes that a user might notice and any actions they must take to implement updates. - [ ] Protocol: - [ ] Nodes (Validators and Full nodes): - [ ] Indexer: - [ ] JSON-RPC: - [ ] GraphQL: - [ ] CLI: - [ ] Rust SDK:
- Loading branch information
1 parent
b7ea0bb
commit e02a1c9
Showing
24 changed files
with
1,047 additions
and
22 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,25 @@ | ||
| import { useLocation } from "@docusaurus/router"; | ||
| import useGlobalData from '@docusaurus/useGlobalData'; | ||
| import Link from '@docusaurus/Link'; | ||
|
|
||
| export function DBV() { | ||
| const location = useLocation(); | ||
| const isV3 = location.pathname.includes("v3"); | ||
|
|
||
| function DBLink() { | ||
| return <Link href={isV3 ? "/standards/deepbookv2" : "/standards/deepbookv3"}>DeepBook{isV3 ? "V2" : "V3"} docs</Link> | ||
| } | ||
|
|
||
| return ( | ||
| <> | ||
| This documentation is for <b>version {isV3 ? "3" : "2"}</b> of DeepBook. DeepBook{isV3 ? "V3" : "V2"} is currently available in {isV3 ? "Devnet and Testnet" : "Mainnet"}. For documentation on version {isV3 ? "2" : "3"} of DeepBook, see <DBLink />. | ||
| </> | ||
| ) | ||
|
|
||
| } | ||
|
|
||
| :::info | ||
|
|
||
| <DBV /> | ||
|
|
||
| ::: |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,25 @@ | ||
| --- | ||
| title: DeepBookV2 | ||
| description: A central limit order book that offers features and functionality for marketplaces on Sui. Token exchanges leveraging the layer can feature transparency, a full range of trading options, and customer privacy. | ||
| --- | ||
|
|
||
| {@include: ../snippets/deepbook.mdx} | ||
|
|
||
| As Sui's first native liquidity layer, DeepBook provides token trading activity. Token exchanges leveraging the layer can feature transparency, a full range of trading options, and customer privacy. DeepBook operates as a decentralized and permissionless environment to support token trades. | ||
|
|
||
| DeepBook is open for community development. You can use the [Sui Improvement Proposals](https://github.com/sui-foundation/sips?ref=blog.sui.io) (SIPs) process to suggest changes to make DeepBook better. | ||
|
|
||
| DeepBook does not include an end-user interface for token trading. Rather, it offers built-in trading functionality that can support token trades from decentralized exchanges, wallets, or other apps. You can leverage its SDK to build functionality for token trades and price queries. | ||
|
|
||
| ## Liquidity support | ||
|
|
||
| Similar to order books for other market places, DeepBook's central limit order book (CLOB) architecture enables you to enter market and limit orders. You can sell SUI tokens, referred to as an "ask," can set your price, referred to as a limit order, or sell at the market's going rate. If you are seeking to buy SUI, referred to as a "bid," you can pay the current market price or set a limit amount you're willing to pay. Limit orders only get fulfilled if the CLOB finds a match between a buyer and seller. | ||
|
|
||
| If you put in a limit order for 1,000 SUI, and no single seller is currently offering that quantity of tokens, DeepBook automatically pools the current asks to meet the quantity of your bid. | ||
|
|
||
| ## Transparency and privacy | ||
|
|
||
| As a CLOB, DeepBook works like a digital ledger, logging bids and asks in chronological order and automatically finding matches between the two sides. It takes into account user parameters on trades such as prices. | ||
|
|
||
| The digital ledger is open so people can view the trades and prices, giving clear proof of fairness. You can use this transparency to create metrics and dashboards to monitor trading activity. | ||
|
|
3 changes: 2 additions & 1 deletion
3
docs/content/standards/deepbook/design.mdx → docs/content/standards/deepbookv2/design.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
4 changes: 3 additions & 1 deletion
4
docs/content/standards/deepbook/orders.mdx → docs/content/standards/deepbookv2/orders.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
3 changes: 2 additions & 1 deletion
3
docs/content/standards/deepbook/pools.mdx → docs/content/standards/deepbookv2/pools.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
3 changes: 2 additions & 1 deletion
3
...ent/standards/deepbook/query-the-pool.mdx → ...t/standards/deepbookv2/query-the-pool.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
3 changes: 2 additions & 1 deletion
3
...ent/standards/deepbook/routing-a-swap.mdx → ...t/standards/deepbookv2/routing-a-swap.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
3 changes: 2 additions & 1 deletion
3
...ent/standards/deepbook/trade-and-swap.mdx → ...t/standards/deepbookv2/trade-and-swap.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,40 @@ | ||
| --- | ||
| title: DeepBookV3 | ||
| description: A central limit order book that offers features and functionality for marketplaces on Sui. Token exchanges leveraging the layer can feature transparency, a full range of trading options, and customer privacy. | ||
| --- | ||
|
|
||
| {@include: ../snippets/deepbook.mdx} | ||
|
|
||
| DeepBook is a next-generation decentralized central limit order book (CLOB) built on Sui. DeepBook leverages Sui's parallel execution and low transaction fees to bring a highly performant, low-latency exchange on chain. | ||
|
|
||
| The latest version delivers new features including flash loans, governance, improved account abstraction, and enhancements to the existing matching engine. This version also introduces its own tokenomics with the [DEEP token](https://suiscan.xyz/mainnet/coin/0xdeeb7a4662eec9f2f3def03fb937a663dddaa2e215b8078a284d026b7946c270::deep::DEEP/txs), which you can stake for additional benefits. | ||
|
|
||
| DeepBook does not include an end-user interface for token trading. Rather, it offers built-in trading functionality that can support token trades from decentralized exchanges, wallets, or other apps. The available SDK abstracts away a lot of the complexities of interacting with the chain and building programmable transaction blocks, lowering the barrier of entry for active market making. | ||
|
|
||
| ## DeepBook tokenomics | ||
|
|
||
| The DEEP token is used to pay for trading fees on the exchange. Future upgrades will allow users to pay trading fees using the input token, but owning, using, and staking DEEP will continue to provide benefits to active DeepBook traders on the Sui network. | ||
|
|
||
| Users that stake DEEP can enjoy taker and maker incentives. Taker incentives can reduce trading fees by half, dropping them to as low as 0.25 basis points (bps) on stable pairs and 2.5 bps on volatile pairs. Maker incentives are rebates earned based on maker volume generated. | ||
|
|
||
| ## Liquidity support | ||
|
|
||
| Similar to order books for other market places, DeepBook's CLOB architecture enables you to enter market and limit orders. You can sell SUI tokens, referred to as an "ask," can set your price, referred to as a limit order, or sell at the market's going rate. If you are seeking to buy SUI, referred to as a "bid," you can pay the current market price or set a limit price. Limit orders only get fulfilled if the CLOB finds a match between a buyer and seller. | ||
|
|
||
| If you put in a limit order for 1,000 SUI, and no single seller is currently offering that quantity of tokens, DeepBook automatically pools the current asks to meet the quantity of your bid. | ||
|
|
||
| ## Transparency and privacy | ||
|
|
||
| As a CLOB, DeepBook works like a digital ledger, logging bids and asks in chronological order and automatically finding matches between the two sides. It takes into account user parameters on trades such as prices. | ||
|
|
||
| The digital ledger is open so people can view the trades and prices, giving clear proof of fairness. You can use this transparency to create metrics and dashboards to monitor trading activity. | ||
|
|
||
| ## Documentation | ||
|
|
||
| This documentation outlines the design of DeepBook, its public endpoints, and provides guidance for integrations. The SDK abstracts away a lot of the complexities of interacting with the chain and building programmable transaction blocks, lowering the barrier of entry for active market making. | ||
|
|
||
| ## Open source | ||
|
|
||
| DeepBook is open for community development. You can use the [Sui Improvement Proposals](https://github.com/sui-foundation/sips?ref=blog.sui.io) (SIPs) process to suggest changes to make DeepBook better. | ||
|
|
||
| [DeepBook repository on GitHub](https://github.com/MystenLabs/deepbookv3). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,115 @@ | ||
| --- | ||
| title: BalanceManager | ||
| description: Learn about the balance manager and how it works | ||
| --- | ||
|
|
||
| {@include: ../../snippets/deepbook.mdx} | ||
|
|
||
| The `BalanceManager` shared object holds all balances for different assets. To perform trades, pass a combination of `BalanceManager` and `TradeProof` into a [pool](./design.mdx#pool). `TradeProof`s are generated in one of two ways, either by the `BalanceManager` owner directly, or by any `TradeCap` owner. The owner can generate a `TradeProof` without the risk of equivocation. The `TradeCap` owner, because it's an owned object, risks equivocation when generating a `TradeProof`. Generally, a high frequency trading engine trades as the default owner. | ||
|
|
||
| With exception to swaps, all interactions with DeepBook require a `BalanceManager` as one of its inputs. When orders are matched, funds are transferred to or from the `BalanceManager`. You can use a single `BalanceManager` between all pools. | ||
|
|
||
| ## API | ||
|
|
||
| Following are the different public functions that the `BalanceManager` exposes. | ||
|
|
||
| ### Create a `BalanceManager` | ||
|
|
||
| The `new()` function creates a `BalanceManager` hot potato (a struct with no abilities). Combine it with `share`, or else the transaction fails. You can combine the transaction with deposit calls, allowing you to create, deposit, then share the balance manager in one transaction. | ||
|
|
||
| ```move | ||
| /// Create a new Balance Manager. | ||
| public fun new(ctx: &mut TxContext): BalanceManager; | ||
| /// Share the balance manager. | ||
| public fun share(balance_manager: BalanceManager); | ||
| ``` | ||
|
|
||
| ### Mint a `TradeCap` | ||
|
|
||
| The owner of a `BalanceManager` can mint a `TradeCap` and send it to another address. Upon receipt, that address will have the capability to place orders with this `BalanceManager`. The address owner cannot deposit or withdraw funds, however. The maximum number of `TradeCap` that can be assigned for a `BalanceManager` is `1000`. If this limit is reached, one or more existing `TradeCap` must be revoked before minting new ones. | ||
|
|
||
| ```move | ||
| /// Mint a `TradeCap`, only owner can mint a `TradeCap`. | ||
| public fun mint_trade_cap( | ||
| balance_manager: &mut BalanceManager, | ||
| ctx: &mut TxContext | ||
| ): TradeCap | ||
| /// Revoke a `TradeCap`. Only the owner can revoke a `TradeCap`. | ||
| public fun revoke_trade_cap( | ||
| balance_manager: &mut BalanceManager, | ||
| trade_cap_id: &ID, | ||
| ctx: &TxContext | ||
| ) | ||
| ``` | ||
|
|
||
| ### Generate a `TradeProof` | ||
|
|
||
| To call any function that requires a balance check or transfer, the user must provide their `BalanceManager` as well as a `TradeProof`. There are two ways to generate a trade proof, one used by the owner and another used by a `TradeCap` owner. | ||
|
|
||
| ```move | ||
| /// Generate a `TradeProof` by the owner. The owner does not require a capability | ||
| /// and can generate TradeProofs without the risk of equivocation. | ||
| public fun generate_proof_as_owner( | ||
| balance_manager: &mut BalanceManager, | ||
| ctx: &TxContext | ||
| ): TradeProof | ||
| /// Generate a `TradeProof` with a `TradeCap`. | ||
| /// Risk of equivocation since `TradeCap` is an owned object. | ||
| public fun generate_proof_as_trader( | ||
| balance_manager: &mut BalanceManager, | ||
| trade_cap: &TradeCap, | ||
| ctx: &TxContext | ||
| ): TradeProof | ||
| ``` | ||
|
|
||
| ### Deposit funds | ||
|
|
||
| Only the owner can deposit funds into the `BalanceManager`. | ||
|
|
||
| ```move | ||
| /// Deposit funds to a balance_manager. Only owner can call this directly. | ||
| public fun deposit<T>( | ||
| balance_manager: &mut BalanceManager, | ||
| coin: Coin<T>, | ||
| ctx: &mut TxContext, | ||
| ) | ||
| ``` | ||
|
|
||
| ### Withdraw funds | ||
|
|
||
| Only the owner can withdraw funds from the `BalanceManager`. | ||
|
|
||
| ```move | ||
| /// Withdraw funds from a balance_manager. Only owner can call this directly. | ||
| /// If withdraw_all is true, amount is ignored and full balance withdrawn. | ||
| /// If withdraw_all is false, withdraw_amount is withdrawn. | ||
| public fun withdraw<T>( | ||
| balance_manager: &mut BalanceManager, | ||
| withdraw_amount: u64, | ||
| ctx: &mut TxContext, | ||
| ): Coin<T> | ||
| public fun withdraw_all<T>( | ||
| balance_manager: &mut BalanceManager, | ||
| ctx: &mut TxContext, | ||
| ): Coin<T> | ||
| ``` | ||
|
|
||
| ### Read endpoints | ||
|
|
||
| ```move | ||
| /// Validate that this `TradeProof` can access the balance manager's funds. | ||
| public fun validate_proof(balance_manager: &BalanceManager, proof: &TradeProof) | ||
| /// Returns the balance of a Coin in an balance_manager. | ||
| public fun balance<T>(balance_manager: &BalanceManager): u64 | ||
| /// Returns the owner of the balance_manager. | ||
| public fun owner(balance_manager: &BalanceManager): address | ||
| /// Returns the owner of the balance_manager. | ||
| public fun id(balance_manager: &BalanceManager): ID | ||
| ``` |
Oops, something went wrong.