Usage

Creating SDK Instance

To start using the SDK in your dApp, you first need to create an instance of it. This instance provides the primary functionality to interact with the Orbs dTWAP protocol.

import { constructSDK } from "@orbs-network/twap-sdk";

const twapSDK = constructSDK({
  config
});

Note: To obtain a config object, you must contact Orbs and setup your desired parameters, along with deploying the appropriate contracts.

Example of a dTWAP config object:

{
   "chainName": "eth",
   "chainId": 1,
   "twapVersion": 4,
   "twapAddress": "0x0000000000000000000000000000000000000000",
   "lensAddress": "0x0000000000000000000000000000000000000000",
   "bidDelaySeconds": 60,
   "minChunkSizeUsd": 100,
   "name": "DexSwap",
   "partner": "Orbs:TWAP:DexSwap",
   "exchangeAddress": "0x0000000000000000000000000000000000000000",
   "exchangeType": "ParaswapExchange",
   "pathfinderKey": ""
}

Derived Swap Values

The derivedSwapValues function takes the inputs from the UI and derives all the values required for the TWAP order.

const derivedSwapValues = twapSDK.derivedSwapValues({
  srcAmount,          // user input src amount in bigint format
  price,              // optional: user input limit price 
  customChunks,       // optional: user input number of chunks
  customDuration,     // optional: user input duration
  customFillDelay,    // optional: user input fill delay
  isLimitPanel,       // boolean for whether user select limit panel
  oneSrcTokenUsd,     // USD value of 1 src token
  srcDecimals,        // number of decimals of src token
  destDecimals,       // number of decimals for dest token
  isMarketOrder,      // boolean for whether user selected market order
});

The following arguments customChunks, customDuration and customFillDelay all have default values, so only pass these in if the user specifies them in the UI.

Prepare Order Arguments

The prepareOrderArgs function takes the values from derivedSwapValues and parses them into arguments for the dTWAP contract method.

const askParams = twapSDK.prepareOrderArgs({
  destTokenMinAmount: derivedSwapValues.destTokenMinAmount,
  srcChunkAmount: derivedSwapValues.srcChunkAmount,
  deadline: derivedSwapValues.deadline,
  fillDelay: derivedSwapValues.fillDelay,
  srcAmount,            // user input src amount in bigint format
  srcTokenAddress,      // src token address
  destTokenAddress,     // dest token address
});

Order Deadline

You can use orderDeadline to get the deadline of an order to display to the user. This needs to be updated at an interval with the current time.

const deadline = twapSDK.orderDeadline(
  currentTime,    // The current time as number e.g. Date.now()
  duration        // The duration from derivedSwapValues
)

Get Orders

Returns a list of all a user's orders.

const orders = await twapSDK.getOrders(
  account,        // The user account
  signal          // optional: abort signal
)

Wait For Orders Update

Retries fetching the user’s orders until the specific order is found. This function is useful after creating a new order, when you want to wait for confirmation that the new order has been successfully created.

const updatedOrders = await twapSDK.waitForOrdersUpdate(
  orderId,        // The order Id to find
  account         // The user account
);

Best Practices

Limit Deadline

When the user selects the limit panel we suggest to set the default deadline of the order to 1 week and if TWAP, set it to undefined as it will be derived from the chunks and fill delay.

Warnings

partialFill
minFillDelay
maxFillDelay
minDuration
maxDuration
tradeSize

The derivedSwapValues SDK function returns a warnings object containing the boolean properties above.

We recommend displaying a message to the user in the UI for each of these warnings if they are true.