@d8x/perpetuals-sdk 0.1.2 → 0.1.3

package/README.md

@@ -33,4 +33,5 @@ Node TypeScript SDK for D8X Perpetual Futures
 `yarn build`
 `yarn build:doc`
 `yarn login`
+`yarn version`
 `yarn publish`

package/dist/accountTrade.d.ts

@@ -218,5 +218,4 @@ export default class AccountTrade extends WriteAccessHandler {
      * @param {number} amount How much collateral to remove, in units of collateral currency, e.g. MATIC
      */
     removeCollateral(symbol: string, amount: number): Promise<ethers.ContractTransaction>;
-    swapForMockToken(symbol: string, amountToPay: string): Promise<any>;
 }

package/dist/accountTrade.js

@@ -12,7 +12,6 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-const ethers_1 = require("ethers");
 const d8XMath_1 = require("./d8XMath");
 const marketData_1 = __importDefault(require("./marketData"));
 const nodeSDKTypes_1 = require("./nodeSDKTypes");
@@ -342,25 +341,5 @@ class AccountTrade extends writeAccessHandler_1.default {
             });
         });
     }
-    swapForMockToken(symbol, amountToPay) {
-        return __awaiter(this, void 0, void 0, function* () {
-            if (this.signer == null) {
-                throw Error("no wallet initialized. Use createProxyInstance().");
-            }
-            let tokenAddress = this.getMarginTokenFromSymbol(symbol);
-            if (tokenAddress == undefined) {
-                throw Error("symbols not found");
-            }
-            let tokenToSwap = new Map(Object.entries(require("../config/mockSwap.json")));
-            let swapAddress = tokenToSwap.get(tokenAddress);
-            if (swapAddress == undefined) {
-                throw Error("No swap contract found for symbol.");
-            }
-            let contract = new ethers_1.ethers.Contract(swapAddress, nodeSDKTypes_1.MOCK_TOKEN_SWAP_ABI, this.signer.provider);
-            return yield contract.swapToMockToken({
-                value: ethers_1.ethers.utils.parseEther(amountToPay),
-            });
-        });
-    }
 }
 exports.default = AccountTrade;

package/dist/liquidityProviderTool.d.ts

@@ -78,7 +78,9 @@ export default class LiquidityProviderTool extends WriteAccessHandler {
      */
     addLiquidity(poolSymbolName: string, amountCC: number): Promise<ethers.ContractTransaction>;
     /**
-     * Remove liquidity from the pool. The address loses pool shares in return.
+     * Initiates a liquidity withdrawal from the pool
+     * It triggers a time-delayed unlocking of the given number of pool shares.
+     * The amount of pool shares to be unlocked is fixed by this call, but not their value in pool currency.
      * @param {string} poolSymbolName Name of pool symbol (e.g. MATIC).
      * @param {string} amountPoolShares Amount in pool-shares, removes everything if > available amount.
      * @example
@@ -90,13 +92,35 @@ export default class LiquidityProviderTool extends WriteAccessHandler {
      *   const pk: string = <string>process.env.PK;
      *   let lqudtProviderTool = new LiquidityProviderTool(config, pk);
      *   await lqudtProviderTool.createProxyInstance();
-     *   // remove liquidity
-     *   let respRemoveLiquidity = await lqudtProviderTool.removeLiquidity("MATIC", 0.1);
+     *   // initiate withdrawal
+     *   let respRemoveLiquidity = await lqudtProviderTool.initiateLiquidityWithdrawal("MATIC", 0.1);
      *   console.log(respRemoveLiquidity);
      * }
      * main();
      *
      * @return Transaction object.
      */
-    removeLiquidity(poolSymbolName: string, amountPoolShares: number): Promise<ethers.providers.TransactionResponse>;
+    initiateLiquidityWithdrawal(poolSymbolName: string, amountPoolShares: number): Promise<ethers.providers.TransactionResponse>;
+    /**
+     * Withdraws as much liquidity as there is available after a call to initiateLiquidityWithdrawal.
+     * The address loses pool shares in return.
+     * @param poolSymbolName
+     * @example
+     * import { LiquidityProviderTool, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
+     * async function main() {
+     *   console.log(LiquidityProviderTool);
+     *   // 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 lqudtProviderTool = new LiquidityProviderTool(config, pk);
+     *   await lqudtProviderTool.createProxyInstance();
+     *   // remove liquidity
+     *   let respRemoveLiquidity = await lqudtProviderTool.executeLiquidityWithdrawal("MATIC", 0.1);
+     *   console.log(respRemoveLiquidity);
+     * }
+     * main();
+     *
+     * @returns Transaction object.
+     */
+    executeLiquidityWithdrawal(poolSymbolName: string): Promise<ethers.providers.TransactionResponse>;
 }

package/dist/liquidityProviderTool.js

@@ -123,7 +123,9 @@ class LiquidityProviderTool extends writeAccessHandler_1.default {
         });
     }
     /**
-     * Remove liquidity from the pool. The address loses pool shares in return.
+     * Initiates a liquidity withdrawal from the pool
+     * It triggers a time-delayed unlocking of the given number of pool shares.
+     * The amount of pool shares to be unlocked is fixed by this call, but not their value in pool currency.
      * @param {string} poolSymbolName Name of pool symbol (e.g. MATIC).
      * @param {string} amountPoolShares Amount in pool-shares, removes everything if > available amount.
      * @example
@@ -135,21 +137,54 @@ class LiquidityProviderTool extends writeAccessHandler_1.default {
      *   const pk: string = <string>process.env.PK;
      *   let lqudtProviderTool = new LiquidityProviderTool(config, pk);
      *   await lqudtProviderTool.createProxyInstance();
-     *   // remove liquidity
-     *   let respRemoveLiquidity = await lqudtProviderTool.removeLiquidity("MATIC", 0.1);
+     *   // initiate withdrawal
+     *   let respRemoveLiquidity = await lqudtProviderTool.initiateLiquidityWithdrawal("MATIC", 0.1);
      *   console.log(respRemoveLiquidity);
      * }
      * main();
      *
      * @return Transaction object.
      */
-    removeLiquidity(poolSymbolName, amountPoolShares) {
+    initiateLiquidityWithdrawal(poolSymbolName, amountPoolShares) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this.proxyContract == null || this.signer == null) {
+                throw Error("no proxy contract or wallet initialized. Use createProxyInstance().");
+            }
+            let poolId = perpetualDataHandler_1.default._getPoolIdFromSymbol(poolSymbolName, this.poolStaticInfos);
+            let tx = yield this.proxyContract.withdrawLiquidity(poolId, (0, d8XMath_1.floatToDec18)(amountPoolShares), {
+                gasLimit: this.gasLimit,
+            });
+            return tx;
+        });
+    }
+    /**
+     * Withdraws as much liquidity as there is available after a call to initiateLiquidityWithdrawal.
+     * The address loses pool shares in return.
+     * @param poolSymbolName
+     * @example
+     * import { LiquidityProviderTool, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
+     * async function main() {
+     *   console.log(LiquidityProviderTool);
+     *   // 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 lqudtProviderTool = new LiquidityProviderTool(config, pk);
+     *   await lqudtProviderTool.createProxyInstance();
+     *   // remove liquidity
+     *   let respRemoveLiquidity = await lqudtProviderTool.executeLiquidityWithdrawal("MATIC", 0.1);
+     *   console.log(respRemoveLiquidity);
+     * }
+     * main();
+     *
+     * @returns Transaction object.
+     */
+    executeLiquidityWithdrawal(poolSymbolName) {
         return __awaiter(this, void 0, void 0, function* () {
             if (this.proxyContract == null || this.signer == null) {
                 throw Error("no proxy contract or wallet initialized. Use createProxyInstance().");
             }
             let poolId = perpetualDataHandler_1.default._getPoolIdFromSymbol(poolSymbolName, this.poolStaticInfos);
-            let tx = yield this.proxyContract.removeLiquidity(poolId, (0, d8XMath_1.floatToDec18)(amountPoolShares), {
+            let tx = yield this.proxyContract.executeLiquidityWithdrawal(poolId, {
                 gasLimit: this.gasLimit,
             });
             return tx;

package/dist/marketData.d.ts

@@ -279,5 +279,12 @@ export default class MarketData extends PerpetualDataHandler {
      */
     static orderIdsOfTrader(traderAddr: string, orderBookContract: ethers.Contract): Promise<string[]>;
     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>;
 }

package/dist/marketData.js

@@ -605,6 +605,47 @@ class MarketData extends perpetualDataHandler_1.default {
             return balanceCC - initalMarginCC;
         });
     }
+    /**
+     * 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, brokerAddr) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this.proxyContract == null) {
+                throw Error("no proxy contract or wallet initialized. Use createProxyInstance().");
+            }
+            // loop over all pools and query volumes
+            let brokerProm = [];
+            let traderProm = [];
+            for (let k = 0; k < this.poolStaticInfos.length; k++) {
+                if (brokerAddr != "" && brokerAddr != undefined) {
+                    let brkrVol = this.proxyContract.getCurrentBrokerVolume(this.poolStaticInfos[k].poolId, brokerAddr);
+                    brokerProm.push(brkrVol);
+                }
+                let trdrVol = this.proxyContract.getCurrentTraderVolume(this.poolStaticInfos[k].poolId, traderAddr);
+                traderProm.push(trdrVol);
+            }
+            // sum
+            let totalBrokerVolume = 0;
+            let totalTraderVolume = 0;
+            let brkrVol = yield Promise.all(brokerProm);
+            let trdrVol = yield Promise.all(traderProm);
+            for (let k = 0; k < this.poolStaticInfos.length; k++) {
+                if (brokerAddr != "" && brokerAddr != undefined) {
+                    totalBrokerVolume += (0, d8XMath_1.ABK64x64ToFloat)(brkrVol[k]);
+                }
+                totalTraderVolume += (0, d8XMath_1.ABK64x64ToFloat)(trdrVol[k]);
+            }
+            const volumeCap = 500000;
+            let score = totalBrokerVolume == 0 ? totalTraderVolume / volumeCap : totalBrokerVolume;
+            // 5 different equally spaced categories: (4 is best, 1 worst)
+            let rank4 = 1 + Math.floor(Math.min(score, 1 - 1e-15) * 4);
+            // desired ranking starts at 4 (worst) and ends at 1 (best)
+            return 5 - rank4;
+        });
+    }
     static _exchangeInfo(_proxyContract, _poolStaticInfos, _symbolToPerpStaticInfo, _symbolList, _priceFeedGetter) {
         return __awaiter(this, void 0, void 0, function* () {
             let nestedPerpetualIDs = yield perpetualDataHandler_1.default.getNestedPerpetualIds(_proxyContract);

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const D8X_SDK_VERSION = "0.1.2";
+export declare const D8X_SDK_VERSION = "0.1.3";

package/dist/version.js

@@ -1,4 +1,4 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.D8X_SDK_VERSION = void 0;
-exports.D8X_SDK_VERSION = "0.1.2";
+exports.D8X_SDK_VERSION = "0.1.3";

package/dist/writeAccessHandler.d.ts

@@ -40,4 +40,12 @@ export default class WriteAccessHandler extends PerpetualDataHandler {
      * @returns {string} Address of this wallet.
      */
     getAddress(): string;
+    /**
+     * Converts a given amount of chain native currency (test MATIC)
+     * into a mock token used for trading on testnet, with a rate of 1:100_000
+     * @param symbol Pool margin token e.g. MATIC
+     * @param amountToPay Amount in chain currency, e.g. "0.1" for 0.1 MATIC
+     * @returns
+     */
+    swapForMockToken(symbol: string, amountToPay: string): Promise<any>;
 }

package/dist/writeAccessHandler.js

@@ -101,5 +101,32 @@ class WriteAccessHandler extends perpetualDataHandler_1.default {
     getAddress() {
         return this.traderAddr;
     }
+    /**
+     * Converts a given amount of chain native currency (test MATIC)
+     * into a mock token used for trading on testnet, with a rate of 1:100_000
+     * @param symbol Pool margin token e.g. MATIC
+     * @param amountToPay Amount in chain currency, e.g. "0.1" for 0.1 MATIC
+     * @returns
+     */
+    swapForMockToken(symbol, amountToPay) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this.signer == null) {
+                throw Error("no wallet initialized. Use createProxyInstance().");
+            }
+            let tokenAddress = this.getMarginTokenFromSymbol(symbol);
+            if (tokenAddress == undefined) {
+                throw Error("symbols not found");
+            }
+            let tokenToSwap = new Map(Object.entries(require("../config/mockSwap.json")));
+            let swapAddress = tokenToSwap.get(tokenAddress);
+            if (swapAddress == undefined) {
+                throw Error("No swap contract found for symbol.");
+            }
+            let contract = new ethers_1.ethers.Contract(swapAddress, nodeSDKTypes_1.MOCK_TOKEN_SWAP_ABI, this.signer);
+            return yield contract.swapToMockToken({
+                value: ethers_1.ethers.utils.parseEther(amountToPay),
+            });
+        });
+    }
 }
 exports.default = WriteAccessHandler;

package/package.json

@@ -33,7 +33,7 @@
   },
   "name": "@d8x/perpetuals-sdk",
   "description": "Node TypeScript SDK for D8X Perpetual Futures",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "directories": {

package/src/accountTrade.ts

@@ -359,23 +359,4 @@ export default class AccountTrade extends WriteAccessHandler {
       value: this.PRICE_UPDATE_FEE_GWEI * priceFeedData.priceFeedVaas.length,
     });
   }
-
-  public async swapForMockToken(symbol: string, amountToPay: string) {
-    if (this.signer == null) {
-      throw Error("no wallet initialized. Use createProxyInstance().");
-    }
-    let tokenAddress = this.getMarginTokenFromSymbol(symbol);
-    if (tokenAddress == undefined) {
-      throw Error("symbols not found");
-    }
-    let tokenToSwap = new Map<string, string>(Object.entries(require("../config/mockSwap.json")));
-    let swapAddress = tokenToSwap.get(tokenAddress);
-    if (swapAddress == undefined) {
-      throw Error("No swap contract found for symbol.");
-    }
-    let contract = new ethers.Contract(swapAddress, MOCK_TOKEN_SWAP_ABI, this.signer.provider);
-    return await contract.swapToMockToken({
-      value: ethers.utils.parseEther(amountToPay),
-    });
-  }
 }

package/src/liquidityProviderTool.ts

@@ -116,7 +116,9 @@ export default class LiquidityProviderTool extends WriteAccessHandler {
   }
 
   /**
-   * Remove liquidity from the pool. The address loses pool shares in return.
+   * Initiates a liquidity withdrawal from the pool
+   * It triggers a time-delayed unlocking of the given number of pool shares.
+   * The amount of pool shares to be unlocked is fixed by this call, but not their value in pool currency.
    * @param {string} poolSymbolName Name of pool symbol (e.g. MATIC).
    * @param {string} amountPoolShares Amount in pool-shares, removes everything if > available amount.
    * @example
@@ -128,15 +130,15 @@ export default class LiquidityProviderTool extends WriteAccessHandler {
    *   const pk: string = <string>process.env.PK;
    *   let lqudtProviderTool = new LiquidityProviderTool(config, pk);
    *   await lqudtProviderTool.createProxyInstance();
-   *   // remove liquidity
-   *   let respRemoveLiquidity = await lqudtProviderTool.removeLiquidity("MATIC", 0.1);
+   *   // initiate withdrawal
+   *   let respRemoveLiquidity = await lqudtProviderTool.initiateLiquidityWithdrawal("MATIC", 0.1);
    *   console.log(respRemoveLiquidity);
    * }
    * main();
    *
    * @return Transaction object.
    */
-  public async removeLiquidity(
+  public async initiateLiquidityWithdrawal(
     poolSymbolName: string,
     amountPoolShares: number
   ): Promise<ethers.providers.TransactionResponse> {
@@ -144,7 +146,39 @@ export default class LiquidityProviderTool extends WriteAccessHandler {
       throw Error("no proxy contract or wallet initialized. Use createProxyInstance().");
     }
     let poolId = PerpetualDataHandler._getPoolIdFromSymbol(poolSymbolName, this.poolStaticInfos);
-    let tx = await this.proxyContract.removeLiquidity(poolId, floatToDec18(amountPoolShares), {
+    let tx = await this.proxyContract.withdrawLiquidity(poolId, floatToDec18(amountPoolShares), {
+      gasLimit: this.gasLimit,
+    });
+    return tx;
+  }
+
+  /**
+   * Withdraws as much liquidity as there is available after a call to initiateLiquidityWithdrawal.
+   * The address loses pool shares in return.
+   * @param poolSymbolName
+   * @example
+   * import { LiquidityProviderTool, PerpetualDataHandler } from '@d8x/perpetuals-sdk';
+   * async function main() {
+   *   console.log(LiquidityProviderTool);
+   *   // 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 lqudtProviderTool = new LiquidityProviderTool(config, pk);
+   *   await lqudtProviderTool.createProxyInstance();
+   *   // remove liquidity
+   *   let respRemoveLiquidity = await lqudtProviderTool.executeLiquidityWithdrawal("MATIC", 0.1);
+   *   console.log(respRemoveLiquidity);
+   * }
+   * main();
+   *
+   * @returns Transaction object.
+   */
+  public async executeLiquidityWithdrawal(poolSymbolName: string): Promise<ethers.providers.TransactionResponse> {
+    if (this.proxyContract == null || this.signer == null) {
+      throw Error("no proxy contract or wallet initialized. Use createProxyInstance().");
+    }
+    let poolId = PerpetualDataHandler._getPoolIdFromSymbol(poolSymbolName, this.poolStaticInfos);
+    let tx = await this.proxyContract.executeLiquidityWithdrawal(poolId, {
       gasLimit: this.gasLimit,
     });
     return tx;

package/src/marketData.ts

@@ -750,6 +750,46 @@ export default class MarketData extends PerpetualDataHandler {
     return balanceCC - initalMarginCC;
   }
 
+  /**
+   * 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)
+   */
+  public async getTraderLoyalityScore(traderAddr: string, brokerAddr?: string) : Promise<number> {
+    if (this.proxyContract == null) {
+      throw Error("no proxy contract or wallet initialized. Use createProxyInstance().");
+    }
+    // loop over all pools and query volumes
+    let brokerProm : Array<Promise<BigNumber>>= [];
+    let traderProm : Array<Promise<BigNumber>>= [];
+    for(let k=0; k<this.poolStaticInfos.length; k++) {
+      if (brokerAddr!="" && brokerAddr!=undefined) {
+        let brkrVol = this.proxyContract.getCurrentBrokerVolume(this.poolStaticInfos[k].poolId, brokerAddr);
+        brokerProm.push(brkrVol);
+      }
+      let trdrVol = this.proxyContract.getCurrentTraderVolume(this.poolStaticInfos[k].poolId, traderAddr);
+      traderProm.push(trdrVol);
+    }
+    // sum
+    let totalBrokerVolume = 0;
+    let totalTraderVolume = 0;
+    let brkrVol = await Promise.all(brokerProm);
+    let trdrVol = await Promise.all(traderProm);
+    for(let k=0; k<this.poolStaticInfos.length; k++) {
+      if (brokerAddr!="" && brokerAddr!=undefined) {
+        totalBrokerVolume += ABK64x64ToFloat(brkrVol[k]);
+      }
+      totalTraderVolume += ABK64x64ToFloat(trdrVol[k]);
+    }
+    const volumeCap = 500_000;
+    let score = totalBrokerVolume==0 ? totalTraderVolume/volumeCap : totalBrokerVolume;
+    // 5 different equally spaced categories: (4 is best, 1 worst)
+    let rank4 = 1+Math.floor(Math.min(score,1-1e-15)*4);
+    // desired ranking starts at 4 (worst) and ends at 1 (best)
+    return 5-rank4;
+  }
+
   public static async _exchangeInfo(
     _proxyContract: ethers.Contract,
     _poolStaticInfos: Array<PoolStaticInfo>,

package/src/version.ts

@@ -1 +1 @@
-export const D8X_SDK_VERSION = "0.1.2";
+export const D8X_SDK_VERSION = "0.1.3";

package/src/writeAccessHandler.ts

@@ -1,6 +1,6 @@
 import { BigNumber, ethers } from "ethers";
 import { floatToDec18 } from "./d8XMath";
-import { ERC20_ABI, MAX_UINT_256, NodeSDKConfig } from "./nodeSDKTypes";
+import { ERC20_ABI, MAX_UINT_256, MOCK_TOKEN_SWAP_ABI, NodeSDKConfig } from "./nodeSDKTypes";
 import PerpetualDataHandler from "./perpetualDataHandler";
 
 /**
@@ -93,4 +93,30 @@ export default class WriteAccessHandler extends PerpetualDataHandler {
   public getAddress(): string {
     return this.traderAddr;
   }
+
+  /**
+   * Converts a given amount of chain native currency (test MATIC)
+   * into a mock token used for trading on testnet, with a rate of 1:100_000
+   * @param symbol Pool margin token e.g. MATIC
+   * @param amountToPay Amount in chain currency, e.g. "0.1" for 0.1 MATIC
+   * @returns
+   */
+  public async swapForMockToken(symbol: string, amountToPay: string) {
+    if (this.signer == null) {
+      throw Error("no wallet initialized. Use createProxyInstance().");
+    }
+    let tokenAddress = this.getMarginTokenFromSymbol(symbol);
+    if (tokenAddress == undefined) {
+      throw Error("symbols not found");
+    }
+    let tokenToSwap = new Map<string, string>(Object.entries(require("../config/mockSwap.json")));
+    let swapAddress = tokenToSwap.get(tokenAddress);
+    if (swapAddress == undefined) {
+      throw Error("No swap contract found for symbol.");
+    }
+    let contract = new ethers.Contract(swapAddress, MOCK_TOKEN_SWAP_ABI, this.signer);
+    return await contract.swapToMockToken({
+      value: ethers.utils.parseEther(amountToPay),
+    });
+  }
 }