@d8x/perpetuals-sdk 0.0.7 → 0.0.9

package/src/marketData.ts

@@ -16,10 +16,29 @@ import PerpetualDataHandler from "./perpetualDataHandler";
 import { SmartContractOrder, Order } from "./nodeSDKTypes";
 
 /**
+ * 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.
  */
 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();
+   *
+   */
   public constructor(config: NodeSDKConfig) {
     super(config);
   }
@@ -31,6 +50,20 @@ export default class MarketData extends PerpetualDataHandler {
 
   /**
    * 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
    */
   public getReadOnlyProxyInstance(): ethers.Contract {
@@ -42,6 +75,20 @@ export default class MarketData extends PerpetualDataHandler {
 
   /**
    * 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.
    */
   public async exchangeInfo(): Promise<ExchangeInfo> {
@@ -55,6 +102,29 @@ export default class MarketData extends PerpetualDataHandler {
    * 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
+   * // 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");
+   * @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.
    */
   public async openOrders(traderAddr: string, symbol: string): Promise<{ orders: Order[]; orderIds: string[] }> {
@@ -62,15 +132,38 @@ export default class MarketData extends PerpetualDataHandler {
     let orderBookContract = this.getOrderBookContract(symbol);
     let [orders, digests] = await Promise.all([
       this.openOrdersOnOrderBook(traderAddr, orderBookContract),
-      this.orderIdsOfTrader(traderAddr, orderBookContract),
+      MarketData.orderIdsOfTrader(traderAddr, orderBookContract),
     ]);
     return { orders: orders, orderIds: digests };
   }
 
   /**
-   * Information about the position open by a given trader in a given perpetual contract.
+   * Information about the positions 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.
+   * @example
+   * // 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");
+   * @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}
    */
   public async positionRisk(traderAddr: string, symbol: string): Promise<MarginAccount> {
@@ -90,6 +183,20 @@ export default class MarketData extends PerpetualDataHandler {
    * 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.
    */
   public async getOraclePrice(base: string, quote: string): Promise<number | undefined> {
@@ -103,6 +210,20 @@ export default class MarketData extends PerpetualDataHandler {
   /**
    * 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
    */
   public async getMarkPrice(symbol: string): Promise<number> {
@@ -116,6 +237,20 @@ export default class MarketData extends PerpetualDataHandler {
    * 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)
    */
   public async getPerpetualPrice(symbol: string, quantity: number): Promise<number> {
@@ -151,12 +286,12 @@ export default class MarketData extends PerpetualDataHandler {
 
   /**
    *
-   * @param traderAddr address of the trader
-   * @param orderBookContract instance of order book contract
-   * @returns array of order-id's
+   * @param traderAddr Address of the trader
+   * @param orderBookContract Instance of order book contract
+   * @returns Array of order-id's
    * @ignore
    */
-  protected async orderIdsOfTrader(traderAddr: string, orderBookContract: ethers.Contract): Promise<string[]> {
+  public static async orderIdsOfTrader(traderAddr: string, orderBookContract: ethers.Contract): Promise<string[]> {
     let digestsRaw: string[] = await orderBookContract.limitDigestsOfTrader(traderAddr, 0, 15);
     let k: number = 0;
     let digests: string[] = [];

package/src/nodeSDKTypes.ts

@@ -9,6 +9,11 @@ export const COLLATERAL_CURRENCY_QUOTE = 0;
 export const COLLATERAL_CURRENCY_BASE = 1;
 export const COLLATERAL_CURRENCY_QUANTO = 2;
 export const PERP_STATE_STR = ["INVALID", "INITIALIZING", "NORMAL", "EMERGENCY", "CLEARED"];
+export const PerpetualStateINVALID = 0;
+export const PerpetualStateINITIALIZING = 1;
+export const PerpetualStateNORMAL = 2;
+export const PerpetualStateEMERGENCY = 3;
+export const PerpetualStateCLEARED = 4;
 export const ZERO_ADDRESS = constants.AddressZero;
 export const ZERO_ORDER_ID = constants.HashZero;
 

package/src/orderReferrerTool.ts

@@ -3,12 +3,17 @@ import { BUY_SIDE, NodeSDKConfig, Order, SELL_SIDE, ZERO_ADDRESS, ZERO_ORDER_ID
 import { ethers } from "ethers";
 
 /**
- * Methods to execute existing orders from the limit order book.
+ * Functions to execute existing conditional orders from the limit order book. This class
+ * requires a private key and executes smart-contract interactions that require
+ * gas-payments.
  */
 export default class OrderReferrerTool extends WriteAccessHandler {
   /**
    * Constructor.
-   * @param {NodeSDKConfig} config Configuration object.
+   * @param {NodeSDKConfig} config Configuration object, see PerpetualDataHandler.readSDKConfig.
+   * @example
+   * const config = PerpetualDataHandler.readSDKConfig("testnet")
+   *
    * @param {string} privateKey Private key of the wallet that executes the conditional orders.
    */
   public constructor(config: NodeSDKConfig, privateKey: string) {
@@ -16,7 +21,7 @@ export default class OrderReferrerTool extends WriteAccessHandler {
   }
 
   /**
-   * Executes an order by symbol and ID. This action interacts with the blockchain and incurs in gas costs.
+   * Executes an order by symbol and ID. This action interacts with the blockchain and incurs gas costs.
    * @param {string} symbol Symbol of the form ETH-USD-MATIC.
    * @param {string} orderId ID of the order to be executed.
    * @param {string=} referrerAddr Address of the wallet to be credited for executing the order,

package/src/perpetualDataHandler.ts

@@ -29,6 +29,8 @@ import {
   DEFAULT_CONFIG_TESTNET_NAME,
   DEFAULT_CONFIG_TESTNET,
   ONE_64x64,
+  PerpetualStateINITIALIZING,
+  PerpetualStateINVALID,
 } from "./nodeSDKTypes";
 import { fromBytes4HexString, to4Chars, combineFlags, containsFlag } from "./utils";
 import {
@@ -130,6 +132,10 @@ export default class PerpetualDataHandler {
 
       for (let k = 0; k < perpetualIDs.length; k++) {
         let perp = await proxyContract.getPerpetual(perpetualIDs[k]);
+        if (perp.state == PerpetualStateINVALID || perp.state == PerpetualStateINITIALIZING) {
+          // only active perpetuals
+          continue;
+        }
         let base = fromBytes4HexString(perp.S2BaseCCY);
         let quote = fromBytes4HexString(perp.S2QuoteCCY);
         let base3 = fromBytes4HexString(perp.S3BaseCCY);
@@ -475,7 +481,7 @@ export default class PerpetualDataHandler {
       fLimitPrice = floatToABK64x64(order.limitPrice);
     }
 
-    let iDeadline = order.deadline == undefined ? Date.now() + ORDER_MAX_DURATION_SEC : order.deadline;
+    let iDeadline = order.deadline == undefined ? Date.now() / 1000 + ORDER_MAX_DURATION_SEC : order.deadline;
     let fTriggerPrice = order.stopPrice == undefined ? BigNumber.from(0) : floatToABK64x64(order.stopPrice);
     if (order.reduceOnly != undefined && order.reduceOnly == true) {
     }
@@ -491,8 +497,8 @@ export default class PerpetualDataHandler {
       fLimitPrice: fLimitPrice,
       fTriggerPrice: fTriggerPrice,
       fLeverage: order.leverage == undefined ? BigNumber.from(0) : floatToABK64x64(order.leverage),
-      iDeadline: BigNumber.from(iDeadline),
-      createdTimestamp: BigNumber.from(order.timestamp),
+      iDeadline: BigNumber.from(Math.round(iDeadline)),
+      createdTimestamp: BigNumber.from(Math.round(order.timestamp)),
     };
     return smOrder;
   }