@d8x/perpetuals-sdk 0.1.12 → 0.2.0

package/dist/esm/marketData.d.ts

@@ -0,0 +1,309 @@
+import { ethers } from "ethers";
+import "./nodeSDKTypes";
+import { ExchangeInfo, MarginAccount, NodeSDKConfig, Order, PerpetualState, PerpetualStaticInfo, PoolStaticInfo, SmartContractOrder } from "./nodeSDKTypes";
+import PerpetualDataHandler from "./perpetualDataHandler";
+import PriceFeeds from "./priceFeeds";
+/**
+ * Functions to access market data (e.g., information on open orders, information on products that can be traded).
+ * This class requires no private key and is blockchain read-only.
+ * No gas required for the queries here.
+ * @extends PerpetualDataHandler
+ */
+export default class MarketData extends PerpetualDataHandler {
+    /**
+     * Constructor
+     * @param {NodeSDKConfig} config Configuration object, see
+     * PerpetualDataHandler.readSDKConfig.
+     * @example
+     * import { MarketData, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
+     * async function main() {
+     *   console.log(MarketData);
+     *   // load configuration for testnet
+     *   const config = PerpetualDataHandler.readSDKConfig("testnet");
+     *   // MarketData (read only, no authentication needed)
+     *   let mktData = new MarketData(config);
+     *   // Create a proxy instance to access the blockchain
+     *   await mktData.createProxyInstance();
+     * }
+     * main();
+     *
+     */
+    constructor(config: NodeSDKConfig);
+    /**
+     * Initialize the marketData-Class with this function
+     * to create instance of D8X perpetual contract and gather information
+     * about perpetual currencies
+     * @param provider optional provider
+     */
+    createProxyInstance(provider?: ethers.providers.Provider): Promise<void>;
+    /**
+     * Get the proxy address
+     * @returns Address of the perpetual proxy contract
+     */
+    getProxyAddress(): string;
+    /**
+     * Convert the smart contract output of an order into a convenient format of type "Order"
+     * @param smOrder SmartContractOrder, as obtained e.g., by PerpetualLimitOrderCreated event
+     * @returns more convenient format of order, type "Order"
+     */
+    smartContractOrderToOrder(smOrder: SmartContractOrder): Order;
+    /**
+     * Get contract instance. Useful for event listening.
+     * @example
+     * import { MarketData, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
+     * async function main() {
+     *   console.log(MarketData);
+     *   // setup
+     *   const config = PerpetualDataHandler.readSDKConfig("testnet");
+     *   let mktData = new MarketData(config);
+     *   await mktData.createProxyInstance();
+     *   // Get contract instance
+     *   let proxy = await mktData.getReadOnlyProxyInstance();
+     *   console.log(proxy);
+     * }
+     * main();
+     *
+     * @returns read-only proxy instance
+     */
+    getReadOnlyProxyInstance(): ethers.Contract;
+    /**
+     * Information about the products traded in the exchange.
+     * @example
+     * import { MarketData, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
+     * async function main() {
+     *   console.log(MarketData);
+     *   // setup
+     *   const config = PerpetualDataHandler.readSDKConfig("testnet");
+     *   let mktData = new MarketData(config);
+     *   await mktData.createProxyInstance();
+     *   // Get exchange info
+     *   let info = await mktData.exchangeInfo();
+     *   console.log(info);
+     * }
+     * main();
+     *
+     * @returns {ExchangeInfo} Array of static data for all the pools and perpetuals in the system.
+     */
+    exchangeInfo(): Promise<ExchangeInfo>;
+    /**
+     * All open orders for a trader-address and a symbol.
+     * @param {string} traderAddr Address of the trader for which we get the open orders.
+     * @param {string} symbol Symbol of the form ETH-USD-MATIC.
+     * @example
+     * import { MarketData, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
+     * async function main() {
+     *   console.log(MarketData);
+     *   // setup
+     *   const config = PerpetualDataHandler.readSDKConfig("testnet");
+     *   let mktData = new MarketData(config);
+     *   await mktData.createProxyInstance();
+     *   // Get all open orders for a trader/symbol
+     *   let opOrder = await mktData.openOrders("0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B",
+     *       "ETH-USD-MATIC");
+     *   console.log(opOrder);
+     * }
+     * main();
+     *
+     * @returns {Array<Array<Order>, Array<string>>} Array of open orders and corresponding order-ids.
+     */
+    openOrders(traderAddr: string, symbol: string): Promise<{
+        orders: Order[];
+        orderIds: string[];
+    }>;
+    /**
+     * Information about the position open by a given trader in a given perpetual contract.
+     * @param {string} traderAddr Address of the trader for which we get the position risk.
+     * @param {string} symbol Symbol of the form ETH-USD-MATIC. Can also be the perpetual id as string
+     * @example
+     * import { MarketData, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
+     * async function main() {
+     *   console.log(MarketData);
+     *   // setup
+     *   const config = PerpetualDataHandler.readSDKConfig("testnet");
+     *   let mktData = new MarketData(config);
+     *   await mktData.createProxyInstance();
+     *   // Get position risk info
+     *   let posRisk = await mktData.positionRisk("0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B",
+     *       "ETH-USD-MATIC");
+     *   console.log(posRisk);
+     * }
+     * main();
+     *
+     * @returns {MarginAccount} Position risk of trader.
+     */
+    positionRisk(traderAddr: string, symbol: string): Promise<MarginAccount>;
+    /**
+     * Estimates what the position risk will be if a given order is executed.
+     * @param traderAddr Address of trader
+     * @param order Order to be submitted
+     * @param account Position risk before trade
+     * @param indexPriceInfo Index prices and market status (open/closed)
+     * @returns {MarginAccount} Position risk after trade
+     */
+    positionRiskOnTrade(traderAddr: string, order: Order, account?: MarginAccount, indexPriceInfo?: [number, number, boolean, boolean]): Promise<{
+        newPositionRisk: MarginAccount;
+        orderCost: number;
+    }>;
+    /**
+     * Estimates what the position risk will be if given amount of collateral is added/removed from the account.
+     * @param traderAddr Address of trader
+     * @param deltaCollateral Amount of collateral to add or remove (signed)
+     * @param currentPositionRisk Position risk before
+     * @returns {MarginAccount} Position risk after
+     */
+    positionRiskOnCollateralAction(deltaCollateral: number, account: MarginAccount, indexPriceInfo?: [number, number, boolean, boolean]): Promise<MarginAccount>;
+    protected static _getLiquidationParams(symbol: string, lockedInQC: number, signedPositionBC: number, marginCashCC: number, markPrice: number, collToQuoteConversion: number, symbolToPerpStaticInfo: Map<string, PerpetualStaticInfo>): [number, number | undefined, number];
+    /**
+     * Gets the wallet balance in the collateral currency corresponding to a given perpetual symbol.
+     * @param address Address to check
+     * @param symbol Symbol of the form ETH-USD-MATIC.
+     * @returns Balance
+     */
+    getWalletBalance(address: string, symbol: string): Promise<number>;
+    /**
+     * Gets the maximal order size to open positions (increase size),
+     * considering the existing position, state of the perpetual
+     * Ignores users wallet balance.
+     * @param side BUY or SELL
+     * @param positionRisk Current position risk (as seen in positionRisk)
+     * @returns Maximal trade size, not signed
+     */
+    maxOrderSizeForTrader(side: string, positionRisk: MarginAccount): Promise<number>;
+    /**
+     *
+     * @param side BUY_SIDE or SELL_SIDE
+     * @param symbol of the form ETH-USD-MATIC.
+     * @returns signed maximal position size in base currency
+     */
+    maxSignedPosition(side: string, symbol: string): Promise<number>;
+    /**
+     * Uses the Oracle(s) in the exchange to get the latest price of a given index in a given currency, if a route exists.
+     * @param {string} base Index name, e.g. ETH.
+     * @param {string} quote Quote currency, e.g. USD.
+     * @example
+     * import { MarketData, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
+     * async function main() {
+     *   console.log(MarketData);
+     *   // setup
+     *   const config = PerpetualDataHandler.readSDKConfig("testnet");
+     *   let mktData = new MarketData(config);
+     *   await mktData.createProxyInstance();
+     *   // get oracle price
+     *   let price = await mktData.getOraclePrice("ETH", "USD");
+     *   console.log(price);
+     * }
+     * main();
+     *
+     * @returns {number} Price of index in given currency.
+     */
+    getOraclePrice(base: string, quote: string): Promise<number | undefined>;
+    getOrderStatus(symbol: string, orderId: string): Promise<string>;
+    /**
+     * Get the current mark price
+     * @param symbol symbol of the form ETH-USD-MATIC
+     * @example
+     * import { MarketData, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
+     * async function main() {
+     *   console.log(MarketData);
+     *   // setup
+     *   const config = PerpetualDataHandler.readSDKConfig("testnet");
+     *   let mktData = new MarketData(config);
+     *   await mktData.createProxyInstance();
+     *   // get mark price
+     *   let price = await mktData.getMarkPrice("ETH-USD-MATIC");
+     *   console.log(price);
+     * }
+     * main();
+     *
+     * @returns mark price
+     */
+    getMarkPrice(symbol: string, indexPrices?: [number, number]): Promise<number>;
+    /**
+     * get the current price for a given quantity
+     * @param symbol symbol of the form ETH-USD-MATIC
+     * @param quantity quantity to be traded, negative if short
+     * @example
+     * import { MarketData, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
+     * async function main() {
+     *   console.log(MarketData);
+     *   // setup
+     *   const config = PerpetualDataHandler.readSDKConfig("testnet");
+     *   let mktData = new MarketData(config);
+     *   await mktData.createProxyInstance();
+     *   // get perpetual price
+     *   let price = await mktData.getPerpetualPrice("ETH-USD-MATIC", 1);
+     *   console.log(price);
+     * }
+     * main();
+     *
+     * @returns price (number)
+     */
+    getPerpetualPrice(symbol: string, quantity: number, indexPrices?: [number, number]): Promise<number>;
+    /**
+     * Query recent perpetual state from blockchain
+     * @param symbol symbol of the form ETH-USD-MATIC
+     * @param indexPrices S2 and S3 prices/isMarketOpen if not provided fetch via REST API
+     * @returns PerpetualState reference
+     */
+    getPerpetualState(symbol: string, indexPriceInfo?: [number, number, boolean, boolean]): Promise<PerpetualState>;
+    /**
+     * Query perpetual static info.
+     * This information is queried once at createProxyInstance-time and remains static after that.
+     * @param symbol symbol of the form ETH-USD-MATIC
+     * @returns PerpetualStaticInfo copy.
+     */
+    getPerpetualStaticInfo(symbol: string): PerpetualStaticInfo;
+    /**
+     * get the current mid-price for a perpetual
+     * @param symbol symbol of the form ETH-USD-MATIC
+     * @example
+     * import { MarketData, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
+     * async function main() {
+     *   console.log(MarketData);
+     *   // setup
+     *   const config = PerpetualDataHandler.readSDKConfig("testnet");
+     *   let mktData = new MarketData(config);
+     *   await mktData.createProxyInstance();
+     *   // get perpetual mid price
+     *   let midPrice = await mktData.getPerpetualMidPrice("ETH-USD-MATIC");
+     *   console.log(midPrice);
+     * }
+     * main();
+     *
+     * @returns {number} price
+     */
+    getPerpetualMidPrice(symbol: string): Promise<number>;
+    /**
+     * Query smart contract to get user orders and convert to user friendly order format.
+     * @param {string} traderAddr Address of trader.
+     * @param {ethers.Contract} orderBookContract Instance of order book.
+     * @returns {Order[]} Array of user friendly order struct.
+     * @ignore
+     */
+    protected openOrdersOnOrderBook(traderAddr: string, orderBookContract: ethers.Contract): Promise<Order[]>;
+    /**
+     *
+     * @param traderAddr Address of the trader
+     * @param orderBookContract Instance of order book contract
+     * @returns Array of order-id's
+     * @ignore
+     */
+    static orderIdsOfTrader(traderAddr: string, orderBookContract: ethers.Contract): Promise<string[]>;
+    /**
+     * Query the available margin conditional on the given (or current) index prices
+     * Result is in collateral currency
+     * @param traderAddr address of the trader
+     * @param symbol perpetual symbol of the form BTC-USD-MATIC
+     * @param indexPrices optional index prices, will otherwise fetch from REST API
+     * @returns available margin in collateral currency
+     */
+    getAvailableMargin(traderAddr: string, symbol: string, indexPrices?: [number, number]): Promise<number>;
+    /**
+     * Calculate a type of exchange loyality score based on trader volume
+     * @param traderAddr address of the trader
+     * @param brokerAddr address of the trader's broker or undefined
+     * @returns a loyality score (4 worst, 1 best)
+     */
+    getTraderLoyalityScore(traderAddr: string, brokerAddr?: string): Promise<number>;
+    static _exchangeInfo(_proxyContract: ethers.Contract, _poolStaticInfos: Array<PoolStaticInfo>, _symbolToPerpStaticInfo: Map<string, PerpetualStaticInfo>, _symbolList: Map<string, string>, _priceFeedGetter: PriceFeeds): Promise<ExchangeInfo>;
+}