Skip to content

Commit

Permalink
[docs] DBv3 updates (#19704)
Browse files Browse the repository at this point in the history
## Description 

Describe the changes or additions included in this PR.

## 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:
- [ ] REST API:
  • Loading branch information
ronny-mysten authored Oct 9, 2024
1 parent 4412f8f commit 4cebe03
Show file tree
Hide file tree
Showing 3 changed files with 178 additions and 17 deletions.
9 changes: 8 additions & 1 deletion docs/content/standards/deepbookv3-sdk.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,14 @@
title: DeepBookV3 SDK
---

The DeepBook typescript SDK abstracts away the transaction calls, allowing for direct interactions with the DeepBook package. To use the SDK in your projects, install the `@mysten/deepbook` package.
The DeepBook typescript SDK abstracts away the transaction calls, allowing for direct interactions with the DeepBook package.

- [SDK Repository](https://github.com/MystenLabs/sui/tree/main/sdk/deepbook-v3)
- [NPM version](https://www.npmjs.com/package/@mysten/deepbook-v3)

## Install

To use the SDK in your projects, install the `@mysten/deepbook` package.

```sh npm2yarn
npm install @mysten/deepbook-v3
Expand Down
106 changes: 91 additions & 15 deletions docs/content/standards/deepbookv3-sdk/pools.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -13,9 +13,58 @@ The DeepBookV3 SDK exposes functions that you can call to read the state of a po
Decimal adjust all input quantities. All outputs are decimal adjusted.
:::

### account

Use `account` to retrieve the account information for a `BalanceManager` in a pool, which has the following form:

```tsx
{
epoch: '511',
open_orders: {
constants: [
'170141211130585342296014727715884105730',
'18446744092156295689709543266',
'18446744092156295689709543265'
]
},
taker_volume: 0,
maker_volume: 0,
active_stake: 0,
inactive_stake: 0,
created_proposal: false,
voted_proposal: null,
unclaimed_rebates: { base: 0, quote: 0, deep: 0 },
settled_balances: { base: 0, quote: 0, deep: 0 },
owed_balances: { base: 0, quote: 0, deep: 0 }
}
```

**Parameters**

- `poolKey`: String that identifies the pool to query.
- `balanceManagerKey`: key of the balance manager defined in the SDK.

```tsx
async account(poolKey: string, managerKey: string) {}
```

### accountOpenOrders

Use `accountOpenOrders` to retrieve open orders for the balance manager and pool with the IDs you provide. The call returns a `Promise` that contains an array of open order IDs.

**Parameters**

- `poolKey`: String that identifies the pool to query.
- `managerKey`: String that identifies the balance manager to query.

```tsx
async accountOpenOrders(poolKey: string, managerKey: string) {}
```

### checkManagerBalance

Use `checkManagerBalance` to check the balance manager for a specific coin. The call returns a `Promise` in the form:

```
{
coinType: string,
Expand Down Expand Up @@ -62,7 +111,6 @@ Use `getOrder` to retrieve an order's information. The call returns a `Promise`
async getOrder(poolKey: string, orderId: string) {}
```


### getQuoteQuantityOut

Use `getQuoteQuantityOut` to retrieve the quote quantity out for the base quantity you provide. The call returns a `Promise` in the form:
Expand Down Expand Up @@ -131,19 +179,6 @@ where `deepRequired` is the amount of DEEP required for the dry run.
async getQuantityOut(poolKey: string, baseQuantity: number, quoteQuantity: number) {}
```

### accountOpenOrders

Use `accountOpenOrders` to retrieve open orders for the balance manager and pool with the IDs you provide. The call returns a `Promise` that contains an array of open order IDs.

**Parameters**

- `poolKey`: String that identifies the pool to query.
- `managerKey`: String that identifies the balance manager to query.

```tsx
async accountOpenOrders(poolKey: string, managerKey: string) {}
```

### getLevel2Range

Use `getLevel2Range` to retrieve level 2 order book within the boundary price range you provide. The call returns a `Promise` in the form:
Expand Down Expand Up @@ -186,10 +221,51 @@ Use `getLevel2TicksFromMid` to retrieve level 2 order book ticks from mid-price
async getLevel2TicksFromMid(poolKey: string, ticks: number) {}
```

### lockedBalance

Use `lockedBalance` to retrieve a `BalanceManager` locked balance in the pool. The call returns a `Promise` in the `Order` struct, which has the following form:

```tsx
{
base: 5.5,
quote: 2,
deep: 0.15,
}
```

**Parameters**

`poolKey`: String that identifies the pool to query. `balanceManagerKey`: key of the balance manager defined in the SDK.

```tsx
async lockedBalance(poolKey: string, balanceManagerKey: string) {}
```

### poolTradeParams

Use `poolTradeParams` to retrieve the trade params for the pool, which has the following form:

```tsx
{
takerFee: 0.001,
makerFee: 0.0005,
stakeRequired: 100,
}
```

**Parameters**

- `poolKey`: String that identifies the pool to query.

```tsx
async poolTradeParams(poolKey: string) {}
```

### vaultBalances

Use `vaultBalances` to get the vault balances for a pool with the ID you provide. The call returns a `Promise` in the form:
```

```tsx
{
base: number,
quote: number,
Expand Down
80 changes: 79 additions & 1 deletion docs/content/standards/deepbookv3/query-the-pool.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,18 @@ public fun get_quantity_out<BaseAsset, QuoteAsset>(
): (u64, u64, u64)
```

### 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`).

```move
public fun get_order_deep_required<BaseAsset, QuoteAsset>(
self: &Pool<BaseAsset, QuoteAsset>,
base_quantity: u64,
price: u64,
): (u64, u64)
```

### Retrieve mid price for a pool

Returns the mid price of the pool.
Expand Down Expand Up @@ -111,10 +123,76 @@ public fun vault_balances<BaseAsset, QuoteAsset>(
): (u64, u64, u64)
```

### Retrieve Pool ID
### Retrieve pool ID

Get the ID of the pool given the asset types.

```move
public fun get_pool_id_by_asset<BaseAsset, QuoteAsset>(registry: &Registry): ID
```

### Retrieve order information

Returns the `Order` struct using the order ID.

```move
public fun get_order<BaseAsset, QuoteAsset>(
self: &Pool<BaseAsset, QuoteAsset>,
order_id: u128,
): Order
```

Returns a vector of `Order` structs using a vector of order IDs.

```move
public fun get_orders<BaseAsset, QuoteAsset>(
self: &Pool<BaseAsset, QuoteAsset>,
order_ids: vector<u128>,
): vector<Order>
```

Returns a vector of `Order` structs for all orders that belong to a `BalanceManager` in the pool.

```move
public fun get_account_order_details<BaseAsset, QuoteAsset>(
self: &Pool<BaseAsset, QuoteAsset>,
balance_manager: &BalanceManager,
): vector<Order>
```

### Retrieve locked balance

Returns the locked balance for a `BalanceManager` in the pool (`base_quantity`, `quote_quantity`, `deep_quantity`).

```move
public fun locked_balance<BaseAsset, QuoteAsset>(
self: &Pool<BaseAsset, QuoteAsset>,
balance_manager: &BalanceManager,
): (u64, u64, u64)
```

### Retrieve pool parameters

Returns the trade parameters for the pool (`taker_fee`, `maker_fee`, `stake_required`).

```move
public fun pool_trade_params<BaseAsset, QuoteAsset>(
self: &Pool<BaseAsset, QuoteAsset>,
): (u64, u64, u64)
```

Returns the book parameters for the pool (`tick_size`, `lot_size`, `min_size`).

```move
public fun pool_book_params<BaseAsset, QuoteAsset>(
self: &Pool<BaseAsset, QuoteAsset>,
): (u64, u64, u64)
```

Returns the `OrderDeepPrice` struct for the pool, which determines the conversion for DEEP fees.

```move
public fun get_order_deep_price<BaseAsset, QuoteAsset>(
self: &Pool<BaseAsset, QuoteAsset>,
): OrderDeepPrice
```

0 comments on commit 4cebe03

Please sign in to comment.