Parent Class PerpetualDataHandler

PerpetualDataHandler

Parent class for MarketData and WriteAccessHandler that handles common data and chain operations.

Kind: global class

• PerpetualDataHandler

  • new PerpetualDataHandler(config)

  • instance

    • .getOrderBookContract(symbol) ⇒

    • .getPerpetuals(ids, overrides) ⇒

    • .getLiquidityPools(fromIdx, toIdx, overrides) ⇒

    • ._fillSymbolMaps()

    • .getSymbolFromPoolId(poolId) ⇒ symbol

    • .getPoolIdFromSymbol(symbol) ⇒ number

    • .getPerpIdFromSymbol(symbol) ⇒ number

    • .getSymbolFromPerpId(perpId) ⇒ string

    • .symbol4BToLongSymbol(sym) ⇒ string

    • .fetchPriceSubmissionInfoForPerpetual(symbol) ⇒

    • .getIndexSymbols(symbol) ⇒

    • .fetchLatestFeedPriceInfo(symbol) ⇒

    • .getPriceIds(symbol) ⇒

    • .getPerpetualSymbolsInPool(poolSymbol) ⇒

    • .getAllOpenOrders(symbol) ⇒

    • .numberOfOpenOrders(symbol) ⇒ number

    • .pollLimitOrders(symbol, numElements, [startAfter]) ⇒

    • .getPoolStaticInfoIndexFromSymbol(symbol) ⇒

    • .getMarginTokenFromSymbol(symbol) ⇒

    • .getMarginTokenDecimalsFromSymbol(symbol) ⇒

    • .getABI(contract) ⇒

  • static

    • .getPerpetualStaticInfo(_proxyContract, nestedPerpetualIDs, symbolList) ⇒

    • .nestedIDsToChunks(chunkSize, nestedIDs) ⇒ Array.<Array.<number>>

    • ._getLiquidityPools(ids, _proxyContract, _symbolList, overrides) ⇒

    • ._getPerpetuals(ids, _proxyContract, _symbolList, overrides) ⇒

    • .getMarginAccount(traderAddr, symbol, symbolToPerpStaticInfo, _proxyContract, _pxS2S3, overrides) ⇒

    • .getMarginAccounts(traderAddrs, symbols, symbolToPerpStaticInfo, _multicall, _proxyContract, _pxS2S3s, overrides) ⇒

    • ._calculateLiquidationPrice(symbol, traderState, S2, symbolToPerpStaticInfo) ⇒

    • .symbolToPerpetualId(symbol, symbolToPerpStaticInfo) ⇒

    • .toSmartContractOrder(order, traderAddr, symbolToPerpetualMap) ⇒

    • .fromSmartContratOrderToClientOrder(scOrder, parentChildIds) ⇒

    • .toClientOrder(order, parentChildIds) ⇒

    • .fromClientOrder(obOrder) ⇒

    • ._orderTypeToFlag(order) ⇒

    • .readSDKConfig(configNameOrfileLocation, version) ⇒

    • .getConfigByName(name, version) ⇒

    • .getConfigByLocation(filename, version) ⇒

    • .getConfigByChainId(chainId, version) ⇒

    • .getAvailableConfigs() ⇒

    • ._getABIFromContract(contract, functionName) ⇒

    • .checkOrder(order, traderAccount, perpStaticInfo)

    • .fromClientOrderToTypeSafeOrder(order) ⇒

new PerpetualDataHandler(config)

Constructor

Param	Type	Description
config	NodeSDKConfig	Configuration object, see PerpetualDataHandler.readSDKConfig.

perpetualDataHandler.getOrderBookContract(symbol) ⇒

Returns the order-book contract for the symbol if found or fails

Kind: instance method of PerpetualDataHandler Returns:

order book contract for the perpetual

Param	Description
symbol	symbol of the form ETH-USD-MATIC

perpetualDataHandler.getPerpetuals(ids, overrides) ⇒

Get perpetuals for the given ids from onchain

Kind: instance method of PerpetualDataHandler Returns:

array of PerpetualData converted into decimals

Param	Description
ids	perpetual ids
overrides	optional

perpetualDataHandler.getLiquidityPools(fromIdx, toIdx, overrides) ⇒

Get liquidity pools data

Kind: instance method of PerpetualDataHandler Returns:

array of LiquidityPoolData converted into decimals

Param	Description
fromIdx	starting index (>=1)
toIdx	to index (inclusive)
overrides	optional

perpetualDataHandler._fillSymbolMaps()

Called when initializing. This function fills this.symbolToTokenAddrMap, and this.nestedPerpetualIDs and this.symbolToPerpStaticInfo

Kind: instance method of PerpetualDataHandler

perpetualDataHandler.getSymbolFromPoolId(poolId) ⇒ symbol

Get pool symbol given a pool Id.

Kind: instance method of PerpetualDataHandler Returns: symbol -

Pool symbol, e.g. "USDC".

Param	Type	Description
poolId	number	Pool Id.

perpetualDataHandler.getPoolIdFromSymbol(symbol) ⇒ number

Get pool Id given a pool symbol. Pool IDs start at 1.

Kind: instance method of PerpetualDataHandler Returns: number -

Pool Id.

Param	Type	Description
symbol	string	Pool symbol.

perpetualDataHandler.getPerpIdFromSymbol(symbol) ⇒ number

Get perpetual Id given a perpetual symbol.

Kind: instance method of PerpetualDataHandler Returns: number -

Perpetual Id.

Param	Type	Description
symbol	string	Perpetual symbol, e.g. "BTC-USD-MATIC".

perpetualDataHandler.getSymbolFromPerpId(perpId) ⇒ string

Get the symbol in long format of the perpetual id

Kind: instance method of PerpetualDataHandler Returns: string -

Symbol

Param	Type	Description
perpId	number	perpetual id

perpetualDataHandler.symbol4BToLongSymbol(sym) ⇒ string

Kind: instance method of PerpetualDataHandler Returns: string -

Long symbol

Param	Type	Description
sym	string	Short symbol

perpetualDataHandler.fetchPriceSubmissionInfoForPerpetual(symbol) ⇒

Get PriceFeedSubmission data required for blockchain queries that involve price data, and the corresponding triangulated prices for the indices S2 and S3

Kind: instance method of PerpetualDataHandler Returns:

PriceFeedSubmission and prices for S2 and S3. [S2price, 0] if S3 not defined.

Param	Description
symbol	pool symbol of the form "ETH-USD-MATIC"

perpetualDataHandler.getIndexSymbols(symbol) ⇒

Get the symbols required as indices for the given perpetual

Kind: instance method of PerpetualDataHandler Returns:

name of underlying index prices, e.g. ["MATIC-USD", ""]

Param	Description
symbol	of the form ETH-USD-MATIC, specifying the perpetual

perpetualDataHandler.fetchLatestFeedPriceInfo(symbol) ⇒

Get the latest prices for a given perpetual from the offchain oracle networks

Kind: instance method of PerpetualDataHandler Returns:

array of price feed updates that can be submitted to the smart contract and corresponding price information

Param	Description
symbol	perpetual symbol of the form BTC-USD-MATIC

perpetualDataHandler.getPriceIds(symbol) ⇒

Get list of required pyth price source IDs for given perpetual

Kind: instance method of PerpetualDataHandler Returns:

list of required pyth price sources for this perpetual

Param	Description
symbol	perpetual symbol, e.g., BTC-USD-MATIC

perpetualDataHandler.getPerpetualSymbolsInPool(poolSymbol) ⇒

Get perpetual symbols for a given pool

Kind: instance method of PerpetualDataHandler Returns:

array of perpetual symbols in this pool

Param	Description
poolSymbol	pool symbol such as "MATIC"

perpetualDataHandler.getAllOpenOrders(symbol) ⇒

All the orders in the order book for a given symbol that are currently open.

Kind: instance method of PerpetualDataHandler Returns:

Array with all open orders and their IDs.

Param	Type	Description
symbol	string	Symbol of the form ETH-USD-MATIC.

Example

import { OrderExecutorTool, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
async function main() {
  console.log(OrderExecutorTool);
  // setup (authentication required, PK is an environment variable with a private key)
  const config = PerpetualDataHandler.readSDKConfig("cardona");
  const pk: string = <string>process.env.PK;
  let orderTool = new OrderExecutorTool(config, pk);
  await orderTool.createProxyInstance();
  // get all open orders
  let openOrders = await orderTool.getAllOpenOrders("ETH-USD-MATIC");
  console.log(openOrders);
}
main();

perpetualDataHandler.numberOfOpenOrders(symbol) ⇒ number

Total number of limit orders for this symbol, excluding those that have been cancelled/removed.

Kind: instance method of PerpetualDataHandler Returns: number -

Number of open orders.

Param	Type	Description
symbol	string	Symbol of the form ETH-USD-MATIC.

Example

import { OrderExecutorTool, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
async function main() {
  console.log(OrderExecutorTool);
  // setup (authentication required, PK is an environment variable with a private key)
  const config = PerpetualDataHandler.readSDKConfig("cardona");
  const pk: string = <string>process.env.PK;
  let orderTool = new OrderExecutorTool(config, pk);
  await orderTool.createProxyInstance();
  // get all open orders
  let numberOfOrders = await orderTool.numberOfOpenOrders("ETH-USD-MATIC");
  console.log(numberOfOrders);
}
main();

perpetualDataHandler.pollLimitOrders(symbol, numElements, [startAfter]) ⇒

Get a list of active conditional orders in the order book. This a read-only action and does not incur in gas costs.

Kind: instance method of PerpetualDataHandler Returns:

Array of orders and corresponding order IDs

Param	Type	Description
symbol	string	Symbol of the form ETH-USD-MATIC.
numElements	number	Maximum number of orders to poll.
[startAfter]	string	Optional order ID from where to start polling. Defaults to the first order.

Example

import { OrderExecutorTool, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
async function main() {
  console.log(OrderExecutorTool);
  // setup (authentication required, PK is an environment variable with a private key)
  const config = PerpetualDataHandler.readSDKConfig("cardona");
  const pk: string = <string>process.env.PK;
  let orderTool = new OrderExecutorTool(config, pk);
  await orderTool.createProxyInstance();
  // get all open orders
  let activeOrders = await orderTool.pollLimitOrders("ETH-USD-MATIC", 2);
  console.log(activeOrders);
}
main();

perpetualDataHandler.getPoolStaticInfoIndexFromSymbol(symbol) ⇒

Gets the pool index (starting at 0 in exchangeInfo, not ID!) corresponding to a given symbol.

Kind: instance method of PerpetualDataHandler Returns:

Pool index

Param	Description
symbol	Symbol of the form ETH-USD-MATIC

perpetualDataHandler.getMarginTokenFromSymbol(symbol) ⇒

Kind: instance method of PerpetualDataHandler Returns:

Address of the corresponding token

Param	Description
symbol	Symbol of the form USDC

perpetualDataHandler.getMarginTokenDecimalsFromSymbol(symbol) ⇒

Kind: instance method of PerpetualDataHandler Returns:

Decimals of the corresponding token

Param	Description
symbol	Symbol of the form USDC

perpetualDataHandler.getABI(contract) ⇒

Get ABI for LimitOrderBook, Proxy, or Share Pool Token

Kind: instance method of PerpetualDataHandler Returns:

ABI for the requested contract

Param	Description
contract	name of contract: proxy

PerpetualDataHandler.getPerpetualStaticInfo(_proxyContract, nestedPerpetualIDs, symbolList) ⇒

Collect all perpetuals static info

Kind: static method of PerpetualDataHandler Returns:

array with PerpetualStaticInfo for each perpetual

Param	Type	Description
_proxyContract	ethers.Contract	perpetuals contract with getter
nestedPerpetualIDs	Array.<Array.<number>>	perpetual id-array for each pool
symbolList	Map.<string, string>	mapping of symbols to convert long-format <-> blockchain-format

PerpetualDataHandler.nestedIDsToChunks(chunkSize, nestedIDs) ⇒ Array.<Array.<number>>

Breaks up an array of nested arrays into chunks of a specified size.

Kind: static method of PerpetualDataHandler Returns: Array.<Array.<number>> -

An array of subarrays, each containing chunkSize or fewer elements from nestedIDs.

Param	Type	Description
chunkSize	number	The size of each chunk.
nestedIDs	Array.<Array.<number>>	The array of nested arrays to chunk.

PerpetualDataHandler._getLiquidityPools(ids, _proxyContract, _symbolList, overrides) ⇒

Query perpetuals

Kind: static method of PerpetualDataHandler Returns:

array of PerpetualData converted into decimals

Param	Description
ids	perpetual ids
_proxyContract	proxy contract instance
_symbolList	symbol mappings to convert the bytes encoded symbol name to string
overrides	optional

PerpetualDataHandler._getPerpetuals(ids, _proxyContract, _symbolList, overrides) ⇒

Query perpetuals

Kind: static method of PerpetualDataHandler Returns:

array of PerpetualData converted into decimals

Param	Description
ids	perpetual ids
_proxyContract	proxy contract instance
_symbolList	symbol mappings to convert the bytes encoded symbol name to string
overrides	optional

PerpetualDataHandler.getMarginAccount(traderAddr, symbol, symbolToPerpStaticInfo, _proxyContract, _pxS2S3, overrides) ⇒

Get trader state from the blockchain and parse into a human-readable margin account

Kind: static method of PerpetualDataHandler Returns:

A Margin account

Param	Description
traderAddr	Trader address
symbol	Perpetual symbol
symbolToPerpStaticInfo	Symbol to perp static info mapping
_proxyContract	Proxy contract instance
_pxS2S3	Prices [S2, S3]
overrides	Optional overrides for eth_call

PerpetualDataHandler.getMarginAccounts(traderAddrs, symbols, symbolToPerpStaticInfo, _multicall, _proxyContract, _pxS2S3s, overrides) ⇒

Get trader states from the blockchain and parse into a list of human-readable margin accounts

Kind: static method of PerpetualDataHandler Returns:

List of margin accounts

Param	Description
traderAddrs	List of trader addresses
symbols	List of symbols
symbolToPerpStaticInfo	Symbol to perp static info mapping
_multicall	Multicall3 contract instance
_proxyContract	Proxy contract instance
_pxS2S3s	List of price pairs, [[S2, S3] (1st perp), [S2, S3] (2nd perp), ... ]
overrides	Optional eth_call overrides

PerpetualDataHandler._calculateLiquidationPrice(symbol, traderState, S2, symbolToPerpStaticInfo) ⇒

Liquidation price

Kind: static method of PerpetualDataHandler Returns:

liquidation mark-price, corresponding collateral/quote conversion

Param	Description
symbol	symbol of the form BTC-USD-MATIC
traderState	BigInt array according to smart contract
S2	number, index price S2
symbolToPerpStaticInfo	mapping symbol->PerpStaticInfo

PerpetualDataHandler.symbolToPerpetualId(symbol, symbolToPerpStaticInfo) ⇒

Finds the perpetual id for a symbol of the form

--. The function first converts the token names into bytes4 representation

Kind: static method of PerpetualDataHandler Returns:

perpetual id or it fails

Param	Description
symbol	symbol (e.g., BTC-USD-MATC)
symbolToPerpStaticInfo	map that contains the bytes4-symbol to PerpetualStaticInfo including id mapping

PerpetualDataHandler.toSmartContractOrder(order, traderAddr, symbolToPerpetualMap) ⇒

Transform the convenient form of the order into a smart-contract accepted type of order

Kind: static method of PerpetualDataHandler Returns:

SmartContractOrder

Param	Description
order	order type
traderAddr	address of the trader
symbolToPerpetualMap	mapping of symbol to perpetual Id

PerpetualDataHandler.fromSmartContratOrderToClientOrder(scOrder, parentChildIds) ⇒

Converts a smart contract order to a client order

Kind: static method of PerpetualDataHandler Returns:

Client order that can be submitted to the corresponding LOB

Param	Description
scOrder	Smart contract order
parentChildIds	Optional parent-child dependency

PerpetualDataHandler.toClientOrder(order, parentChildIds) ⇒

Converts a user-friendly order to a client order

Kind: static method of PerpetualDataHandler Returns:

Client order that can be submitted to the corresponding LOB

Param	Description
order	Order
parentChildIds	Optional parent-child dependency

PerpetualDataHandler.fromClientOrder(obOrder) ⇒

Converts an order as stored in the LOB smart contract into a user-friendly order type

Kind: static method of PerpetualDataHandler Returns:

User friendly order struct

Param	Description
obOrder	Order-book contract order type

PerpetualDataHandler._orderTypeToFlag(order) ⇒

Determine the correct order flags based on the order-properties. Checks for some misspecifications.

Kind: static method of PerpetualDataHandler Returns:

BigNumber flags

Param	Description
order	order type

PerpetualDataHandler.readSDKConfig(configNameOrfileLocation, version) ⇒

Get NodeSDKConfig from a chain ID, known config name, or custom file location..

Kind: static method of PerpetualDataHandler Returns:

NodeSDKConfig

Param	Description
configNameOrfileLocation	Name of a known default config, or chain ID, or json-file with required variables for config
version	Config version number. Defaults to highest version if name or chain ID are not unique

PerpetualDataHandler.getConfigByName(name, version) ⇒

Get a NodeSDKConfig from its name

Kind: static method of PerpetualDataHandler Returns:

NodeSDKConfig

Param	Description
name	Name of the known config
version	Version of the config. Defaults to highest available.

PerpetualDataHandler.getConfigByLocation(filename, version) ⇒

Get a NodeSDKConfig from a json file.

Kind: static method of PerpetualDataHandler Returns:

NodeSDKConfig

Param	Description
filename	Location of the file
version	Version of the config. Defaults to highest available.

PerpetualDataHandler.getConfigByChainId(chainId, version) ⇒

Get a NodeSDKConfig from its chain Id

Kind: static method of PerpetualDataHandler Returns:

NodeSDKConfig

Param	Description
chainId	Chain Id
version	Version of the config. Defaults to highest available.

PerpetualDataHandler.getAvailableConfigs() ⇒

Get available configurations in a Set. You can use the output to determine the config file that you get via 'let config = PerpetualDataHandler.readSDKConfig(196);'

Kind: static method of PerpetualDataHandler Returns:

set of chain-ids and name separated by ;

Example

import { PerpetualDataHandler } from '@d8x/perpetuals-sdk';
async function main() {
  const configs = PerpetualDataHandler.getAvailableConfigs();
  console.log(configs);
  // output of the form:
  // Set(2) { '1101; zkevm', `196; xlayer'}
}
main();

PerpetualDataHandler._getABIFromContract(contract, functionName) ⇒

Get the ABI of a function in a given contract

Kind: static method of PerpetualDataHandler Returns:

Function ABI as a single JSON string

Param	Description
contract	A contract instance, e.g. this.proxyContract
functionName	Name of the function whose ABI we want

PerpetualDataHandler.checkOrder(order, traderAccount, perpStaticInfo)

Performs basic validity checks on a given order

Kind: static method of PerpetualDataHandler

Param	Description
order	Order struct
traderAccount	Trader account
perpStaticInfo	Symbol to perpetual info map

PerpetualDataHandler.fromClientOrderToTypeSafeOrder(order) ⇒

Converts a client order (with BigNumberish types) to a type-safe order (with number/bigint types)

Kind: static method of PerpetualDataHandler Returns:

Order that can be submitted to the corresponding LOB via ethers v6 or viem

Param	Description
order	Client order