@d8x/perpetuals-sdk 0.0.7 → 0.0.9

package/dist/brokerTool.js

@@ -19,11 +19,28 @@ const ethers_1 = require("ethers");
 const accountTrade_1 = __importDefault(require("./accountTrade"));
 /**
  * Functions for brokers to determine fees, deposit lots, and sign-up traders.
+ * This class requires a private key and executes smart-contract interactions that
+ * require gas-payments.
  */
 class BrokerTool extends writeAccessHandler_1.default {
     /**
      * Constructor
-     * @param {NodeSDKConfig} config Configuration object.
+     * @param {NodeSDKConfig} config Configuration object, see PerpetualDataHandler.
+     * readSDKConfig.
+     * @example
+     * import { BrokerTool, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
+     * async function main() {
+     *   console.log(BrokerTool);
+     *   // load configuration for testnet
+     *   const config = PerpetualDataHandler.readSDKConfig("testnet");
+     *   // BrokerTool (authentication required, PK is an environment variable with a private key)
+     *   const pk: string = <string>process.env.PK;
+     *   let brokTool = new BrokerTool(config, pk);
+     *   // Create a proxy instance to access the blockchain
+     *   await brokTool.createProxyInstance();
+     * }
+     * main();
+     *
      * @param {string} privateKey Private key of a broker.
      */
     constructor(config, privateKey) {
@@ -32,8 +49,23 @@ class BrokerTool extends writeAccessHandler_1.default {
     // Fee getters
     /**
      * Determine the exchange fee based on lots, traded volume, and D8X balance of this broker.
-     * This is the final exchange fee paid by the broker.
+     * This is the final exchange fee that this broker can offer to traders that trade through him.
      * @param {string} poolSymbolName Pool symbol name (e.g. MATIC, USDC, etc).
+     * @example
+     * import { BrokerTool, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
+     * async function main() {
+     *   console.log(BrokerTool);
+     *   // Setup (authentication required, PK is an environment variable with a private key)
+     *   const config = PerpetualDataHandler.readSDKConfig("testnet");
+     *   const pk: string = <string>process.env.PK;
+     *   let brokTool = new BrokerTool(config, pk);
+     *   await brokTool.createProxyInstance();
+     *   // get broker induced fee
+     *   let brokFee = await brokTool.getBrokerInducedFee("MATIC");
+     *   console.log(brokFee);
+     * }
+     * main();
+     *
      * @returns {number} Exchange fee for this broker, in decimals (i.e. 0.1% is 0.001)
      */
     getBrokerInducedFee(poolSymbolName) {
@@ -48,10 +80,25 @@ class BrokerTool extends writeAccessHandler_1.default {
     }
     /**
      * Determine the exchange fee based on lots purchased by this broker.
-     * The final exchange fee paid by the broker is equal to
+     * The final exchange fee that this broker can offer to traders that trade through him is equal to
      * maximum(brokerTool.getFeeForBrokerDesignation(poolSymbolName),  brokerTool.getFeeForBrokerVolume(poolSymbolName), brokerTool.getFeeForBrokerStake())
      * @param {string} poolSymbolName Pool symbol name (e.g. MATIC, USDC, etc).
      * @param {number=} lots Optional, designation to use if different from this broker's.
+     * @example
+     * import { BrokerTool, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
+     * async function main() {
+     *   console.log(BrokerTool);
+     *   // Setup (authentication required, PK is an environment variable with a private key)
+     *   const config = PerpetualDataHandler.readSDKConfig("testnet");
+     *   const pk: string = <string>process.env.PK;
+     *   let brokTool = new BrokerTool(config, pk);
+     *   await brokTool.createProxyInstance();
+     *   // get broker fee induced by lots
+     *   let brokFeeLots = await brokTool.getFeeForBrokerDesignation("MATIC");
+     *   console.log(brokFeeLots);
+     * }
+     * main();
+     *
      * @returns {number} Fee based solely on this broker's designation, in decimals (i.e. 0.1% is 0.001).
      */
     getFeeForBrokerDesignation(poolSymbolName, lots) {
@@ -73,9 +120,24 @@ class BrokerTool extends writeAccessHandler_1.default {
     }
     /**
      * Determine the exchange fee based on volume traded under this broker.
-     * The final exchange fee paid by the broker is equal to
+     * The final exchange fee that this broker can offer to traders that trade through him is equal to
      * maximum(brokerTool.getFeeForBrokerDesignation(poolSymbolName),  brokerTool.getFeeForBrokerVolume(poolSymbolName), brokerTool.getFeeForBrokerStake())
      * @param {string} poolSymbolName Pool symbol name (e.g. MATIC, USDC, etc).
+     * @example
+     * import { BrokerTool, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
+     * async function main() {
+     *   console.log(BrokerTool);
+     *   // Setup (authentication required, PK is an environment variable with a private key)
+     *   const config = PerpetualDataHandler.readSDKConfig("testnet");
+     *   const pk: string = <string>process.env.PK;
+     *   let brokTool = new BrokerTool(config, pk);
+     *   await brokTool.createProxyInstance();
+     *   // get broker fee induced by volume
+     *   let brokFeeVol = await brokTool.getFeeForBrokerVolume("MATIC");
+     *   console.log(brokFeeVol);
+     * }
+     * main();
+     *
      * @returns {number} Fee based solely on a broker's traded volume in the corresponding pool, in decimals (i.e. 0.1% is 0.001).
      */
     getFeeForBrokerVolume(poolSymbolName) {
@@ -90,9 +152,24 @@ class BrokerTool extends writeAccessHandler_1.default {
     }
     /**
      * Determine the exchange fee based on the current D8X balance in a broker's wallet.
-     * The final exchange fee paid by the broker is equal to
+     * The final exchange fee that this broker can offer to traders that trade through him is equal to
      * maximum(brokerTool.getFeeForBrokerDesignation(symbol, lots),  brokerTool.getFeeForBrokerVolume(symbol), brokerTool.getFeeForBrokerStake)
      * @param {string=} brokerAddr Address of the broker in question, if different from the one calling this function.
+     * @example
+     * import { BrokerTool, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
+     * async function main() {
+     *   console.log(BrokerTool);
+     *   // Setup (authentication required, PK is an environment variable with a private key)
+     *   const config = PerpetualDataHandler.readSDKConfig("testnet");
+     *   const pk: string = <string>process.env.PK;
+     *   let brokTool = new BrokerTool(config, pk);
+     *   await brokTool.createProxyInstance();
+     *   // get broker fee induced by staked d8x
+     *   let brokFeeStake = await brokTool.getFeeForBrokerStake("0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B");
+     *   console.log(brokFeeStake);
+     * }
+     * main();
+     *
      * @returns {number} Fee based solely on a broker's D8X balance, in decimals (i.e. 0.1% is 0.001).
      */
     getFeeForBrokerStake(brokerAddr) {
@@ -114,7 +191,30 @@ class BrokerTool extends writeAccessHandler_1.default {
      * Use this, for instance, to verify that the fee to be charged for a given order is as expected,
      * before and after signing it with brokerTool.signOrder.
      * This fee is equal or lower than the broker induced fee, provided the order is properly signed.
-     * @param {Order} order Order for which to determine the exchange fee. Not necessarily signed by this broker.
+     * @param {Order} order Order structure. As a minimum the structure needs to
+     * specify symbol, side, type and quantity.
+     * @example
+     * import { BrokerTool, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
+     * async function main() {
+     *   console.log(BrokerTool);
+     *   // Setup (authentication required, PK is an environment variable with a private key)
+     *   const config = PerpetualDataHandler.readSDKConfig("testnet");
+     *   const pk: string = <string>process.env.PK;
+     *   let brokTool = new BrokerTool(config, pk);
+     *   await brokTool.createProxyInstance();
+     *   // get exchange fee based on an order and trader
+     *   let order = {symbol: "ETH-USD-MATIC",
+     *       side: "BUY",
+     *       type: "MARKET",
+     *       quantity: 1,
+     *       timestamp: Date.now()
+     *    };
+     *    let exchFee = await brokTool.determineExchangeFee(order,
+     *        "0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B");
+     *   console.log(exchFee);
+     * }
+     * main();
+     *
      * @param {string} traderAddr Address of the trader for whom to determine the fee.
      * @returns {number} Fee in decimals (i.e. 0.1% is 0.001).
      */
@@ -133,6 +233,21 @@ class BrokerTool extends writeAccessHandler_1.default {
      * Exponentially weighted EMA of the total trading volume of all trades performed under this broker.
      * The weights are chosen so that in average this coincides with the 30 day volume.
      * @param {string} poolSymbolName Pool symbol name (e.g. MATIC, USDC, etc).
+     * @example
+     * import { BrokerTool, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
+     * async function main() {
+     *   console.log(BrokerTool);
+     *   // Setup (authentication required, PK is an environment variable with a private key)
+     *   const config = PerpetualDataHandler.readSDKConfig("testnet");
+     *   const pk: string = <string>process.env.PK;
+     *   let brokTool = new BrokerTool(config, pk);
+     *   await brokTool.createProxyInstance();
+     *   // get 30 day volume for broker
+     *   let brokVolume = await brokTool.getCurrentBrokerVolume("MATIC");
+     *   console.log(brokVolume);
+     * }
+     * main();
+     *
      * @returns {number} Current trading volume for this broker, in USD.
      */
     getCurrentBrokerVolume(poolSymbolName) {
@@ -150,6 +265,21 @@ class BrokerTool extends writeAccessHandler_1.default {
      * Total amount of collateral currency a broker has to deposit into the default fund to purchase one lot.
      * This is equivalent to the price of a lot expressed in a given pool's currency (e.g. MATIC, USDC, etc).
      * @param {string} poolSymbolName Pool symbol name (e.g. MATIC, USDC, etc).
+     * @example
+     * import { BrokerTool, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
+     * async function main() {
+     *   console.log(BrokerTool);
+     *   // Setup (authentication required, PK is an environment variable with a private key)
+     *   const config = PerpetualDataHandler.readSDKConfig("testnet");
+     *   const pk: string = <string>process.env.PK;
+     *   let brokTool = new BrokerTool(config, pk);
+     *   await brokTool.createProxyInstance();
+     *   // get lot price
+     *   let brokLotSize = await brokTool.getLotSize("MATIC");
+     *   console.log(brokLotSize);
+     * }
+     * main();
+     *
      * @returns {number} Broker lot size in a given pool's currency, e.g. in MATIC for poolSymbolName MATIC.
      */
     getLotSize(poolSymbolName) {
@@ -167,6 +297,21 @@ class BrokerTool extends writeAccessHandler_1.default {
      * Provides information on how many lots a broker purchased for a given pool.
      * This is relevant to determine the broker's fee tier.
      * @param {string} poolSymbolName Pool symbol name (e.g. MATIC, USDC, etc).
+     * @example
+     * import { BrokerTool, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
+     * async function main() {
+     *   console.log(BrokerTool);
+     *   // Setup (authentication required, PK is an environment variable with a private key)
+     *   const config = PerpetualDataHandler.readSDKConfig("testnet");
+     *   const pk: string = <string>process.env.PK;
+     *   let brokTool = new BrokerTool(config, pk);
+     *   await brokTool.createProxyInstance();
+     *   // get broker designation
+     *   let brokDesignation = await brokTool.getBrokerDesignation("MATIC");
+     *   console.log(brokDesignation);
+     * }
+     * main();
+     *
      * @returns {number} Number of lots purchased by this broker.
      */
     getBrokerDesignation(poolSymbolName) {
@@ -183,7 +328,22 @@ class BrokerTool extends writeAccessHandler_1.default {
      * Deposit lots to the default fund of a given pool.
      * @param {string} poolSymbolName Pool symbol name (e.g. MATIC, USDC, etc).
      * @param {number} lots Number of lots to deposit into this pool.
-     * @returns {ethers.providers.TransactionResponse} Transaction object.
+     * @example
+     * import { BrokerTool, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
+     * async function main() {
+     *   console.log(BrokerTool);
+     *   // Setup (authentication required, PK is an environment variable with a private key)
+     *   const config = PerpetualDataHandler.readSDKConfig("testnet");
+     *   const pk: string = <string>process.env.PK;
+     *   let brokTool = new BrokerTool(config, pk);
+     *   await brokTool.createProxyInstance();
+     *   // deposit to default fund
+     *   let respDeposit = await brokTool.brokerDepositToDefaultFund("MATIC",1);
+     *   console.log(respDeposit);
+     * }
+     * main();
+     *
+     * @returns {ethers.ContractTransaction} ContractTransaction object.
      */
     brokerDepositToDefaultFund(poolSymbolName, lots) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -197,11 +357,35 @@ class BrokerTool extends writeAccessHandler_1.default {
     }
     // Signatures
     /**
-     * Adds this broker's signature to an order so that it can be submitted by an approved trader.
+     * Adds this broker's signature to an order. An order signed by a broker is considered
+     * to be routed through this broker and benefits from the broker's fee conditions.
      * @param {Order} order Order to sign.
      * @param {string} traderAddr Address of trader submitting the order.
-     * @param {number} feeDecimals Fee that this broker is approving for the trader.
-     * @param {number} deadline Deadline for the order to be executed.
+     * @param {number} feeDecimals Fee that this broker imposes on this order.
+     * The fee is sent to the broker's wallet. Fee should be specified in decimals, e.g., 0.0001 equals 1bps.
+     * @param {number} deadline Deadline for the order to be executed. Specify deadline as a unix timestamp
+     * @example
+     * import { BrokerTool, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
+     * async function main() {
+     *   console.log(BrokerTool);
+     *   // Setup (authentication required, PK is an environment variable with a private key)
+     *   const config = PerpetualDataHandler.readSDKConfig("testnet");
+     *   const pk: string = <string>process.env.PK;
+     *   let brokTool = new BrokerTool(config, pk);
+     *   await brokTool.createProxyInstance();
+     *   // sign order
+     *   let order = {symbol: "ETH-USD-MATIC",
+     *       side: "BUY",
+     *       type: "MARKET",
+     *       quantity: 1,
+     *       timestamp: Date.now()
+     *    };
+     *    let signedOrder = await brokTool.signOrder(order, "0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B",
+     *        0.0001, 1669723339);
+     *   console.log(signedOrder);
+     * }
+     * main();
+     *
      * @returns {Order} An order signed by this broker, which can be submitted directly with AccountTrade.order.
      */
     signOrder(order, traderAddr, brokerFee, deadline) {
@@ -253,7 +437,9 @@ class BrokerTool extends writeAccessHandler_1.default {
     }
     // Transfer ownership
     /**
-     * Transfer ownership of a broker's status to a new wallet.
+     * Transfer ownership of a broker's status to a new wallet. This function transfers the values related to
+     * (i) trading volume and (ii) deposited lots to newAddress. The broker needs in addition to manually transfer
+     * his D8X holdings to newAddress. Until this transfer is completed, the broker will not have his current designation reflected at newAddress.
      * @param {string} poolSymbolName Pool symbol name (e.g. MATIC, USDC, etc).
      * @param {string} newAddress The address this broker wants to use from now on.
      * @returns {ethers.providers.TransactionResponse} ethers transaction object

package/dist/index.d.ts

@@ -5,7 +5,8 @@ import MarketData from "./marketData";
 import OrderReferrerTool from "./orderReferrerTool";
 import PerpetualDataHandler from "./perpetualDataHandler";
 import WriteAccessHandler from "./writeAccessHandler";
+import LiquidatorTool from "./liquidatorTool";
 export * from "./nodeSDKTypes";
 export * from "./utils";
 export * from "./d8XMath";
-export { AccountTrade, BrokerTool, LiquidityProviderTool, MarketData, OrderReferrerTool, PerpetualDataHandler, WriteAccessHandler, };
+export { AccountTrade, BrokerTool, LiquidityProviderTool, MarketData, OrderReferrerTool, PerpetualDataHandler, WriteAccessHandler, LiquidatorTool, };

package/dist/index.js

@@ -17,7 +17,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WriteAccessHandler = exports.PerpetualDataHandler = exports.OrderReferrerTool = exports.MarketData = exports.LiquidityProviderTool = exports.BrokerTool = exports.AccountTrade = void 0;
+exports.LiquidatorTool = exports.WriteAccessHandler = exports.PerpetualDataHandler = exports.OrderReferrerTool = exports.MarketData = exports.LiquidityProviderTool = exports.BrokerTool = exports.AccountTrade = void 0;
 const accountTrade_1 = __importDefault(require("./accountTrade"));
 exports.AccountTrade = accountTrade_1.default;
 const brokerTool_1 = __importDefault(require("./brokerTool"));
@@ -32,6 +32,8 @@ const perpetualDataHandler_1 = __importDefault(require("./perpetualDataHandler")
 exports.PerpetualDataHandler = perpetualDataHandler_1.default;
 const writeAccessHandler_1 = __importDefault(require("./writeAccessHandler"));
 exports.WriteAccessHandler = writeAccessHandler_1.default;
+const liquidatorTool_1 = __importDefault(require("./liquidatorTool"));
+exports.LiquidatorTool = liquidatorTool_1.default;
 // import {
 //   NodeSDKConfig,
 //   MarginAccount,

package/dist/liquidatorTool.d.ts

@@ -1,12 +1,28 @@
 import WriteAccessHandler from "./writeAccessHandler";
 import { NodeSDKConfig } from "./nodeSDKTypes";
 /**
- * Methods to liquidate traders.
+ * Functions to liquidate traders. This class requires a private key
+ * and executes smart-contract interactions that require gas-payments.
  */
 export default class LiquidatorTool extends WriteAccessHandler {
     /**
      * Constructs a LiquidatorTool instance for a given configuration and private key.
-     * @param {NodeSDKConfig} config Configuration object.
+     * @param {NodeSDKConfig} config Configuration object, see PerpetualDataHandler.
+     * readSDKConfig.
+     * @example
+     * import { LiquidatorTool, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
+     * async function main() {
+     *   console.log(LiquidatorTool);
+     *   // load configuration for testnet
+     *   const config = PerpetualDataHandler.readSDKConfig("testnet");
+     *   // LiquidatorTool (authentication required, PK is an environment variable with a private key)
+     *   const pk: string = <string>process.env.PK;
+     *   let lqudtrTool = new LiquidatorTool(config, pk);
+     *   // Create a proxy instance to access the blockchain
+     *   await lqudtrTool.createProxyInstance();
+     * }
+     * main();
+     *
      * @param {string} privateKey Private key of account that liquidates.
      */
     constructor(config: NodeSDKConfig, privateKey: string);
@@ -16,14 +32,48 @@ export default class LiquidatorTool extends WriteAccessHandler {
      * @param {string} traderAddr Address of the trader to be liquidated.
      * @param {string=} liquidatorAddr Address to be credited if the liquidation succeeds.
      * Defaults to the wallet used to execute the liquidation.
+     * @example
+     * import { LiquidatorTool, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
+     * async function main() {
+     *   console.log(LiquidatorTool);
+     *   // Setup (authentication required, PK is an environment variable with a private key)
+     *   const config = PerpetualDataHandler.readSDKConfig("testnet");
+     *   const pk: string = <string>process.env.PK;
+     *   let lqudtrTool = new LiquidatorTool(config, pk);
+     *   await lqudtrTool.createProxyInstance();
+     *   // liquidate trader
+     *   let liqAmount = await lqudtrTool.liquidateTrader("ETH-USD-MATIC",
+     *       "0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B");
+     *   console.log(liqAmount);
+     * }
+     * main();
+     *
      * @returns {number} Liquidated amount.
      */
     liquidateTrader(symbol: string, traderAddr: string, liquidatorAddr?: string): Promise<number>;
     /**
-     * Check if a trader is maintenance margin safe - if not, it can be liquidated.
+     * Check if the collateral of a trader is above the maintenance margin ("maintenance margin safe").
+     * If not, the position can be liquidated.
      * @param {string} symbol Symbol of the form ETH-USD-MATIC.
-     * @param {string} traderAddr Address of the trader whose position we want to assess.
+     * @param {string} traderAddr Address of the trader whose position you want to assess.
+     * @example
+     * import { LiquidatorTool, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
+     * async function main() {
+     *   console.log(LiquidatorTool);
+     *   // Setup (authentication required, PK is an environment variable with a private key)
+     *   const config = PerpetualDataHandler.readSDKConfig("testnet");
+     *   const pk: string = <string>process.env.PK;
+     *   let lqudtrTool = new LiquidatorTool(config, pk);
+     *   await lqudtrTool.createProxyInstance();
+     *   // check if trader can be liquidated
+     *   let safe = await lqudtrTool.isMaintenanceMarginSafe("ETH-USD-MATIC",
+     *       "0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B");
+     *   console.log(safe);
+     * }
+     * main();
+     *
      * @returns {boolean} True if the trader is maintenance margin safe in the perpetual.
+     * False means that the trader's position can be liquidated.
      */
     isMaintenanceMarginSafe(symbol: string, traderAddr: string): Promise<boolean>;
     /**
@@ -38,6 +88,21 @@ export default class LiquidatorTool extends WriteAccessHandler {
     /**
      * Total number of active accounts for this symbol, i.e. accounts with positions that are currently open.
      * @param {string} symbol Symbol of the form ETH-USD-MATIC.
+     * @example
+     * import { LiquidatorTool, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
+     * async function main() {
+     *   console.log(LiquidatorTool);
+     *   // Setup (authentication required, PK is an environment variable with a private key)
+     *   const config = PerpetualDataHandler.readSDKConfig("testnet");
+     *   const pk: string = <string>process.env.PK;
+     *   let lqudtrTool = new LiquidatorTool(config, pk);
+     *   await lqudtrTool.createProxyInstance();
+     *   // get number of active accounts
+     *   let accounts = await lqudtrTool.countActivePerpAccounts("ETH-USD-MATIC");
+     *   console.log(accounts);
+     * }
+     * main();
+     *
      * @returns {number} Number of active accounts.
      */
     countActivePerpAccounts(symbol: string): Promise<number>;
@@ -45,13 +110,43 @@ export default class LiquidatorTool extends WriteAccessHandler {
      * Get addresses of active accounts by chunks.
      * @param {string} symbol Symbol of the form ETH-USD-MATIC.
      * @param {number} from From which account we start counting (0-indexed).
-     * @param {number} to Until which account we count.
-     * @returns {string[]} Array of addresses.
+     * @param {number} to Until which account we count, non inclusive.
+     * @example
+     * import { LiquidatorTool, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
+     * async function main() {
+     *   console.log(LiquidatorTool);
+     *   // Setup (authentication required, PK is an environment variable with a private key)
+     *   const config = PerpetualDataHandler.readSDKConfig("testnet");
+     *   const pk: string = <string>process.env.PK;
+     *   let lqudtrTool = new LiquidatorTool(config, pk);
+     *   await lqudtrTool.createProxyInstance();
+     *   // get all active accounts in chunks
+     *   let accounts = await lqudtrTool.getActiveAccountsByChunks("ETH-USD-MATIC", 0, 4);
+     *   console.log(accounts);
+     * }
+     * main();
+     *
+     * @returns {string[]} Array of addresses at locations 'from', 'from'+1 ,..., 'to'-1.
      */
     getActiveAccountsByChunks(symbol: string, from: number, to: number): Promise<string[]>;
     /**
      * Addresses for all the active accounts in this perpetual symbol.
      * @param {string} symbol Symbol of the form ETH-USD-MATIC.
+     * @example
+     * import { LiquidatorTool, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
+     * async function main() {
+     *   console.log(LiquidatorTool);
+     *   // Setup (authentication required, PK is an environment variable with a private key)
+     *   const config = PerpetualDataHandler.readSDKConfig("testnet");
+     *   const pk: string = <string>process.env.PK;
+     *   let lqudtrTool = new LiquidatorTool(config, pk);
+     *   await lqudtrTool.createProxyInstance();
+     *   // get all active accounts
+     *   let accounts = await lqudtrTool.getAllActiveAccounts("ETH-USD-MATIC");
+     *   console.log(accounts);
+     * }
+     * main();
+     *
      * @returns {string[]} Array of addresses.
      */
     getAllActiveAccounts(symbol: string): Promise<string[]>;

package/dist/liquidatorTool.js

@@ -15,12 +15,28 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const writeAccessHandler_1 = __importDefault(require("./writeAccessHandler"));
 const d8XMath_1 = require("./d8XMath");
 /**
- * Methods to liquidate traders.
+ * Functions to liquidate traders. This class requires a private key
+ * and executes smart-contract interactions that require gas-payments.
  */
 class LiquidatorTool extends writeAccessHandler_1.default {
     /**
      * Constructs a LiquidatorTool instance for a given configuration and private key.
-     * @param {NodeSDKConfig} config Configuration object.
+     * @param {NodeSDKConfig} config Configuration object, see PerpetualDataHandler.
+     * readSDKConfig.
+     * @example
+     * import { LiquidatorTool, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
+     * async function main() {
+     *   console.log(LiquidatorTool);
+     *   // load configuration for testnet
+     *   const config = PerpetualDataHandler.readSDKConfig("testnet");
+     *   // LiquidatorTool (authentication required, PK is an environment variable with a private key)
+     *   const pk: string = <string>process.env.PK;
+     *   let lqudtrTool = new LiquidatorTool(config, pk);
+     *   // Create a proxy instance to access the blockchain
+     *   await lqudtrTool.createProxyInstance();
+     * }
+     * main();
+     *
      * @param {string} privateKey Private key of account that liquidates.
      */
     constructor(config, privateKey) {
@@ -32,6 +48,22 @@ class LiquidatorTool extends writeAccessHandler_1.default {
      * @param {string} traderAddr Address of the trader to be liquidated.
      * @param {string=} liquidatorAddr Address to be credited if the liquidation succeeds.
      * Defaults to the wallet used to execute the liquidation.
+     * @example
+     * import { LiquidatorTool, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
+     * async function main() {
+     *   console.log(LiquidatorTool);
+     *   // Setup (authentication required, PK is an environment variable with a private key)
+     *   const config = PerpetualDataHandler.readSDKConfig("testnet");
+     *   const pk: string = <string>process.env.PK;
+     *   let lqudtrTool = new LiquidatorTool(config, pk);
+     *   await lqudtrTool.createProxyInstance();
+     *   // liquidate trader
+     *   let liqAmount = await lqudtrTool.liquidateTrader("ETH-USD-MATIC",
+     *       "0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B");
+     *   console.log(liqAmount);
+     * }
+     * main();
+     *
      * @returns {number} Liquidated amount.
      */
     liquidateTrader(symbol, traderAddr, liquidatorAddr = "") {
@@ -49,10 +81,28 @@ class LiquidatorTool extends writeAccessHandler_1.default {
         });
     }
     /**
-     * Check if a trader is maintenance margin safe - if not, it can be liquidated.
+     * Check if the collateral of a trader is above the maintenance margin ("maintenance margin safe").
+     * If not, the position can be liquidated.
      * @param {string} symbol Symbol of the form ETH-USD-MATIC.
-     * @param {string} traderAddr Address of the trader whose position we want to assess.
+     * @param {string} traderAddr Address of the trader whose position you want to assess.
+     * @example
+     * import { LiquidatorTool, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
+     * async function main() {
+     *   console.log(LiquidatorTool);
+     *   // Setup (authentication required, PK is an environment variable with a private key)
+     *   const config = PerpetualDataHandler.readSDKConfig("testnet");
+     *   const pk: string = <string>process.env.PK;
+     *   let lqudtrTool = new LiquidatorTool(config, pk);
+     *   await lqudtrTool.createProxyInstance();
+     *   // check if trader can be liquidated
+     *   let safe = await lqudtrTool.isMaintenanceMarginSafe("ETH-USD-MATIC",
+     *       "0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B");
+     *   console.log(safe);
+     * }
+     * main();
+     *
      * @returns {boolean} True if the trader is maintenance margin safe in the perpetual.
+     * False means that the trader's position can be liquidated.
      */
     isMaintenanceMarginSafe(symbol, traderAddr) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -60,7 +110,7 @@ class LiquidatorTool extends writeAccessHandler_1.default {
                 throw Error("no proxy contract initialized. Use createProxyInstance().");
             }
             let perpID = LiquidatorTool.symbolToPerpetualId(symbol, this.symbolToPerpStaticInfo);
-            return yield this.proxyContract.isMaintenanceMarginSafe(perpID, traderAddr);
+            return yield this.proxyContract.isTraderMaintenanceMarginSafe(perpID, traderAddr);
         });
     }
     /**
@@ -82,6 +132,21 @@ class LiquidatorTool extends writeAccessHandler_1.default {
     /**
      * Total number of active accounts for this symbol, i.e. accounts with positions that are currently open.
      * @param {string} symbol Symbol of the form ETH-USD-MATIC.
+     * @example
+     * import { LiquidatorTool, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
+     * async function main() {
+     *   console.log(LiquidatorTool);
+     *   // Setup (authentication required, PK is an environment variable with a private key)
+     *   const config = PerpetualDataHandler.readSDKConfig("testnet");
+     *   const pk: string = <string>process.env.PK;
+     *   let lqudtrTool = new LiquidatorTool(config, pk);
+     *   await lqudtrTool.createProxyInstance();
+     *   // get number of active accounts
+     *   let accounts = await lqudtrTool.countActivePerpAccounts("ETH-USD-MATIC");
+     *   console.log(accounts);
+     * }
+     * main();
+     *
      * @returns {number} Number of active accounts.
      */
     countActivePerpAccounts(symbol) {
@@ -97,8 +162,23 @@ class LiquidatorTool extends writeAccessHandler_1.default {
      * Get addresses of active accounts by chunks.
      * @param {string} symbol Symbol of the form ETH-USD-MATIC.
      * @param {number} from From which account we start counting (0-indexed).
-     * @param {number} to Until which account we count.
-     * @returns {string[]} Array of addresses.
+     * @param {number} to Until which account we count, non inclusive.
+     * @example
+     * import { LiquidatorTool, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
+     * async function main() {
+     *   console.log(LiquidatorTool);
+     *   // Setup (authentication required, PK is an environment variable with a private key)
+     *   const config = PerpetualDataHandler.readSDKConfig("testnet");
+     *   const pk: string = <string>process.env.PK;
+     *   let lqudtrTool = new LiquidatorTool(config, pk);
+     *   await lqudtrTool.createProxyInstance();
+     *   // get all active accounts in chunks
+     *   let accounts = await lqudtrTool.getActiveAccountsByChunks("ETH-USD-MATIC", 0, 4);
+     *   console.log(accounts);
+     * }
+     * main();
+     *
+     * @returns {string[]} Array of addresses at locations 'from', 'from'+1 ,..., 'to'-1.
      */
     getActiveAccountsByChunks(symbol, from, to) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -112,13 +192,28 @@ class LiquidatorTool extends writeAccessHandler_1.default {
     /**
      * Addresses for all the active accounts in this perpetual symbol.
      * @param {string} symbol Symbol of the form ETH-USD-MATIC.
+     * @example
+     * import { LiquidatorTool, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
+     * async function main() {
+     *   console.log(LiquidatorTool);
+     *   // Setup (authentication required, PK is an environment variable with a private key)
+     *   const config = PerpetualDataHandler.readSDKConfig("testnet");
+     *   const pk: string = <string>process.env.PK;
+     *   let lqudtrTool = new LiquidatorTool(config, pk);
+     *   await lqudtrTool.createProxyInstance();
+     *   // get all active accounts
+     *   let accounts = await lqudtrTool.getAllActiveAccounts("ETH-USD-MATIC");
+     *   console.log(accounts);
+     * }
+     * main();
+     *
      * @returns {string[]} Array of addresses.
      */
     getAllActiveAccounts(symbol) {
         return __awaiter(this, void 0, void 0, function* () {
             // checks are done inside the intermediate functions
-            let totalAccoutns = yield this.countActivePerpAccounts(symbol);
-            return yield this.getActiveAccountsByChunks(symbol, 0, totalAccoutns - 1);
+            let totalAccounts = yield this.countActivePerpAccounts(symbol);
+            return yield this.getActiveAccountsByChunks(symbol, 0, totalAccounts);
         });
     }
 }