@xchainjs/xchain-thorchain-query 0.1.0-alpha

package/lib/liquidity-pool.d.ts

@@ -0,0 +1,18 @@
+import { PoolDetail } from '@xchainjs/xchain-midgard/lib';
+import { Asset, BaseAmount } from '@xchainjs/xchain-util';
+import { BigNumber } from 'bignumber.js';
+/**
+ * Represent a Liquidity Pool in Thorchain
+ */
+export declare class LiquidityPool {
+    readonly pool: PoolDetail;
+    readonly assetBalance: BaseAmount;
+    readonly runeBalance: BaseAmount;
+    readonly decimals: number;
+    readonly asset: Asset;
+    readonly assetString: string;
+    readonly runeToAssetRatio: BigNumber;
+    readonly assetToRuneRatio: BigNumber;
+    constructor(pool: PoolDetail, decimals: number);
+    isAvailable(): boolean;
+}

package/lib/thorchain-cache.d.ts

@@ -0,0 +1,111 @@
+import { InboundAddressesItem } from '@xchainjs/xchain-midgard';
+import { Address, Asset, Chain } from '@xchainjs/xchain-util';
+import { BigNumber } from 'bignumber.js';
+import { CryptoAmount } from './crypto-amount';
+import { LiquidityPool } from './liquidity-pool';
+import { InboundDetail, SwapOutput } from './types';
+import { Midgard } from './utils/midgard';
+import { Thornode } from './utils/thornode';
+/**
+ * This class manages retrieving information from up to date Thorchain
+ */
+export declare class ThorchainCache {
+    readonly midgard: Midgard;
+    readonly thornode: Thornode;
+    private poolCache;
+    private asgardAssetsCache;
+    private inboundDetailCache;
+    private networkValuesCache;
+    private expirePoolCacheMillis;
+    private expireAsgardCacheMillis;
+    private expireInboundDetailsCacheMillis;
+    private expireNetworkValuesCacheMillis;
+    /**
+     * Contrustor to create a ThorchainCache
+     *
+     * @param midgard - an instance of the midgard API (could be pointing to stagenet,testnet,mainnet)
+     * @param expirePoolCacheMillis - how long should the pools be cached before expiry
+     * @param expireAsgardCacheMillis - how long should the inboundAsgard Addresses be cached before expiry
+     * @param expireInboundDetailsCacheMillis - how long should the InboundDetails be cached before expiry
+     * @param expireNetworkValuesCacheMillis - how long should the Mimir/Constants be cached before expiry
+     * @returns ThorchainCache
+     */
+    constructor(midgard: Midgard, thornode: Thornode, expirePoolCacheMillis?: number, expireAsgardCacheMillis?: number, expireInboundDetailsCacheMillis?: number, expireNetworkValuesCacheMillis?: number);
+    /**
+     * Gets the exchange rate of the from asset in terms on the to asset
+     *
+     * @param asset - cannot be RUNE.
+     * @returns Promise<BigNumber>
+     */
+    getExchangeRate(from: Asset, to: Asset): Promise<BigNumber>;
+    /**
+     * Gets the Liquidity Pool for a given Asset
+     *
+     * @param asset - cannot be RUNE, since Rune is the other side of each pool.
+     * @returns Promise<LiquidityPool>
+     */
+    getPoolForAsset(asset: Asset): Promise<LiquidityPool>;
+    /**
+     * Get all the Liquidity Pools currently cached.
+     * if the cache is expired, the pools wioll be re-fetched from midgard
+     *
+     * @returns Promise<Record<string, LiquidityPool>>
+     */
+    getPools(): Promise<Record<string, LiquidityPool>>;
+    /**
+     * Refreshes the Pool Cache
+     *
+     * NOTE: do not call refereshPoolCache() directly, call getPools() instead
+     * which will refresh the cache if it's expired
+     */
+    private refereshPoolCache;
+    /**
+     * Refreshes the asgardAssetsCache Cache
+     *
+     * NOTE: do not call refereshAsgardCache() directly, call getAsgardAssets() instead
+     * which will refresh the cache if it's expired
+     */
+    private refereshAsgardCache;
+    /**
+     * Refreshes the InboundDetailCache Cache
+     *
+     * NOTE: do not call refereshInboundDetailCache() directly, call getInboundDetails() instead
+     * which will refresh the cache if it's expired
+     */
+    private refereshInboundDetailCache;
+    /**
+     * Refreshes the NetworkValuesCache Cache
+     *
+     * NOTE: do not call refereshNetworkValuesCache() directly, call getNetworkValuess() instead
+     * which will refresh the cache if it's expired
+     */
+    private refereshNetworkValuesCache;
+    /**
+     *
+     *  Calcuate the expected slip, output & swapFee given the current pool depths
+     *
+     *  swapFee - the amount of asset lost  according to slip calculations
+     *  slip - the percent (0-1) of original amount lost to slipfees
+     *  output - the amount of asset expected from the swap   *
+     *
+     * @param inputAmount - CryptoAmount amount to swap from
+     * @param destinationAsset - destimation Asset to swap to
+     * @returns SwapOutput - swap output object - output - fee - slip
+     */
+    getExpectedSwapOutput(inputAmount: CryptoAmount, destinationAsset: Asset): Promise<SwapOutput>;
+    /**
+     * Returns the exchange of a CryptoAmount to a different Asset
+     *
+     * Ex. convert(input:100 BUSD, outAsset: BTC) -> 0.0001234 BTC
+     *
+     * @param input - amount/asset to convert to outAsset
+     * @param ouAsset - the Asset you want to convert to
+     * @returns CryptoAmount of input
+     */
+    convert(input: CryptoAmount, outAsset: Asset): Promise<CryptoAmount>;
+    getRouterAddressForChain(chain: Chain): Promise<Address>;
+    getInboundAddressesItems(): Promise<Record<string, InboundAddressesItem>>;
+    getInboundDetails(): Promise<Record<string, InboundDetail>>;
+    getNetworkValues(): Promise<Record<string, number>>;
+    getDeepestUSDPool(): Promise<LiquidityPool>;
+}

package/lib/thorchain-query.d.ts

@@ -0,0 +1,138 @@
+import { Asset, Chain } from '@xchainjs/xchain-util';
+import { CryptoAmount } from './crypto-amount';
+import { ThorchainCache } from './thorchain-cache';
+import { ChainAttributes, EstimateSwapParams, TotalFees, TxDetails, TxStatus } from './types';
+/**
+ * THORChain Class for interacting with THORChain.
+ * Recommended main class to use for swapping with THORChain
+ * Has access to Midgard and THORNode data
+ */
+export declare class ThorchainQuery {
+    readonly thorchainCache: ThorchainCache;
+    private chainAttributes;
+    /**
+     * Contructor to create a ThorchainAMM
+     *
+     * @param thorchainCache - an instance of the ThorchainCache (could be pointing to stagenet,testnet,mainnet)
+     * @param chainAttributes - atrributes used to calculate waitTime & conf counting
+     * @returns ThorchainAMM
+     */
+    constructor(thorchainCache: ThorchainCache, chainAttributes?: Record<Chain, ChainAttributes>);
+    /**
+     * Provides a swap estimate for the given swap detail. Will check the params for errors before trying to get the estimate.
+     * Uses current pool data, works out inbound and outboud fee, affiliate fees and works out the expected wait time for the swap (in and out)
+     *
+     * @param params - amount to swap
+  
+     * @returns The SwapEstimate
+     */
+    estimateSwap(params: EstimateSwapParams, destinationAddress?: string, affiliateAddress?: string, interfaceID?: number): Promise<TxDetails>;
+    /**
+     * Basic Checks for swap information
+     * @param params
+     */
+    private isValidSwap;
+    /**
+     * Does the calculations for the swap.
+     * Used by estimateSwap
+     *
+     * @param params
+     * @param sourceInboundDetails
+     * @param destinationInboundDetails
+     * @param sourcePool
+     * @param destinationPool
+     * @returns
+     */
+    private calcSwapEstimate;
+    /**
+     *
+     * @param params - swap object
+     * @returns - constructed memo string
+     */
+    private constructSwapMemo;
+    /**
+     * Looks for errors or issues within swap prams before doing the swap.
+     *
+     *
+     * @param params
+     * @param estimate
+     * @param sourcePool
+     * @param sourceInboundDetails
+     * @param destinationPool
+     * @param destinationInboundDetails
+     * @returns
+     */
+    private getSwapEstimateErrors;
+    /**
+     *
+     * @param params
+     * @param estimate
+     * @returns
+     */
+    private checkCoverFees;
+    /**
+     * Convenience method to convert TotalFees to a different CryptoAmount
+     *
+     * TotalFees are always calculated and returned in RUNE, this method can
+     * be used to show the equivalent fees in another Asset Type
+     *
+     * @param fees: TotalFees - the fees you want to convert
+     * @param asset: Asset - the asset you want the fees converted to
+     * @returns TotalFees in asset
+     */
+    getFeesIn(fees: TotalFees, asset: Asset): Promise<TotalFees>;
+    /**
+     * Returns the exchange of a CryptoAmount to a different Asset
+     *
+     * Ex. convert(input:100 BUSD, outAsset: BTC) -> 0.0001234 BTC
+     *
+     * @param input - amount/asset to convert to outAsset
+     * @param ouAsset - the Asset you want to convert to
+     * @returns CryptoAmount of input
+     */
+    convert(input: CryptoAmount, outAsset: Asset): Promise<CryptoAmount>;
+    /**
+     * Finds the required confCount required for an inbound or outbound Tx to THORChain. Estimate based on Midgard data only.
+     *
+     * Finds the gas asset of the given asset (e.g. BUSD is on BNB), finds the value of asset in Gas Asset then finds the required confirmation count.
+     * ConfCount is then times by 6 seconds.
+     *
+     * @param inbound: CryptoAmount - amount/asset of the outbound amount.
+     * @returns time in seconds before a Tx is confirmed by THORChain
+     * @see https://docs.thorchain.org/chain-clients/overview
+     */
+    private confCounting;
+    /**
+     * Works out how long an outbound Tx will be held by THORChain before sending.
+     *
+     * @param outboundAmount: CryptoAmount  being sent.
+     * @returns required delay in seconds
+     * @see https://gitlab.com/thorchain/thornode/-/blob/develop/x/thorchain/manager_txout_current.go#L548
+     */
+    outboundDelay(outboundAmount: CryptoAmount): Promise<number>;
+    /**
+     * For a given in Tx Hash (as returned by THORChainAMM.DoSwap()), finds the status of any THORChain transaction
+     * This function should be polled.
+     * @param
+     * @param inboundTxHash - needed to determine transactions stage
+     * @param sourceChain - extra parameter
+     * @returns - object tx status
+     */
+    checkTx(inboundTxHash: string, sourceChain?: Chain): Promise<TxStatus>;
+    /** Stage 1  */
+    private checkTxDefined;
+    /** Stage 2, THORNode has seen it. See if observed only (conf counting) or it has been processed by THORChain  */
+    private checkObservedOnly;
+    /**
+     * Stage 3
+     * @param txStatus
+     * @param txData
+     * @param scheduledQueue
+     * @param scheduledQueueItem
+     * @param lastBlockHeight
+     * @returns
+     */
+    private checkOutboundQueue;
+    /** Stage 4 */
+    private checkOutboundTx;
+}

package/lib/types.d.ts

@@ -0,0 +1,107 @@
+import { FeeOption } from '@xchainjs/xchain-client';
+import { InboundAddressesItem } from '@xchainjs/xchain-midgard';
+import { Address, Asset, BaseAmount } from '@xchainjs/xchain-util';
+import { BigNumber } from 'bignumber.js';
+import { CryptoAmount } from './crypto-amount';
+import { LiquidityPool } from './liquidity-pool';
+export declare type TotalFees = {
+    inboundFee: CryptoAmount;
+    swapFee: CryptoAmount;
+    outboundFee: CryptoAmount;
+    affiliateFee: CryptoAmount;
+};
+export declare type SwapEstimate = {
+    totalFees: TotalFees;
+    slipPercentage: BigNumber;
+    netOutput: CryptoAmount;
+    waitTimeSeconds: number;
+    canSwap: boolean;
+    errors: string[];
+};
+export declare type PoolCache = {
+    lastRefreshed: number;
+    pools: Record<string, LiquidityPool>;
+};
+export declare type AsgardCache = {
+    lastRefreshed: number;
+    inboundAddressesItems: Record<string, InboundAddressesItem>;
+};
+export declare type InboundDetailCache = {
+    lastRefreshed: number;
+    inboundDetails: Record<string, InboundDetail>;
+};
+export declare type NetworkValuesCache = {
+    lastRefreshed: number;
+    networkValues: Record<string, number>;
+};
+export declare type MidgardConfig = {
+    apiRetries: number;
+    midgardBaseUrls: string[];
+};
+export declare type EstimateSwapParams = {
+    input: CryptoAmount;
+    destinationAsset: Asset;
+    affiliateFeePercent?: number;
+    slipLimit?: BigNumber;
+};
+export declare type SwapOutput = {
+    output: CryptoAmount;
+    swapFee: CryptoAmount;
+    slip: BigNumber;
+};
+export declare type UnitData = {
+    liquidityUnits: BigNumber;
+    totalUnits: BigNumber;
+};
+export declare type LiquidityData = {
+    rune: BigNumber;
+    asset: BigNumber;
+};
+export declare type Block = {
+    current: number;
+    lastAdded: number;
+    fullProtection: number;
+};
+export declare type Coverage = {
+    poolRatio: BaseAmount;
+};
+export declare type InboundDetail = {
+    vault: string;
+    router?: string;
+    haltedChain: boolean;
+    haltedTrading: boolean;
+    haltedLP: boolean;
+    gas_rate: BigNumber;
+};
+export declare type ChainAttributes = {
+    blockReward: number;
+    avgBlockTimeInSecs: number;
+};
+export declare type ConstructMemo = {
+    input: CryptoAmount;
+    destinationAsset: Asset;
+    limit: BaseAmount;
+    destinationAddress: Address;
+    affiliateAddress: Address;
+    affiliateFee: BaseAmount;
+    feeOption?: FeeOption;
+    interfaceID: number;
+};
+export declare type TxDetails = {
+    memo: string;
+    toAddress: string;
+    expiry: Date;
+    txEstimate: SwapEstimate;
+};
+export declare enum TxStage {
+    INBOUND_CHAIN_UNCONFIRMED = 0,
+    CONF_COUNTING = 1,
+    TC_PROCESSING = 2,
+    OUTBOUND_QUEUED = 3,
+    OUTBOUND_CHAIN_UNCONFIRMED = 4,
+    OUTBOUND_CHAIN_CONFIRMED = 5
+}
+export declare type TxStatus = {
+    stage: TxStage;
+    seconds: number;
+};

package/lib/utils/index.d.ts

@@ -0,0 +1,4 @@
+export { getSingleSwap, getDoubleSwap, calcNetworkFee } from './swap';
+export { getLiquidityProtectionData, getSlipOnLiquidity, getPoolShare, getLiquidityUnits } from './liquidity';
+export * from './midgard';
+export * from './thornode';

package/lib/utils/liquidity.d.ts

@@ -0,0 +1,32 @@
+import { BigNumber } from 'bignumber.js';
+import { LiquidityPool } from '../liquidity-pool';
+import { Block, LiquidityData, UnitData } from '../types';
+/**
+ *
+ * @param liquidity - asset amount added
+ * @param pool  - pool depths
+ * @returns liquidity units
+ */
+export declare const getLiquidityUnits: (liquidity: LiquidityData, pool: LiquidityPool) => BigNumber;
+/**
+ *
+ * @param unitData
+ * @param pool
+ * @returns
+ */
+export declare const getPoolShare: (unitData: UnitData, pool: LiquidityPool) => LiquidityData;
+/**
+ *
+ * @param liquidity
+ * @param pool
+ * @returns
+ */
+export declare const getSlipOnLiquidity: (liquidity: LiquidityData, pool: LiquidityPool) => BigNumber;
+/**
+ *
+ * @param liquidity
+ * @param pool
+ * @param block
+ * @returns
+ */
+export declare const getLiquidityProtectionData: (liquidity: LiquidityData, pool: LiquidityPool, block: Block) => number;

package/lib/utils/midgard.d.ts

@@ -0,0 +1,47 @@
+import { Network } from '@xchainjs/xchain-client';
+import { Action, InboundAddressesItem, PoolDetail } from '@xchainjs/xchain-midgard';
+import { CryptoAmount } from '../crypto-amount';
+import { InboundDetail, MidgardConfig } from '../types';
+export declare class Midgard {
+    private config;
+    readonly network: Network;
+    private midgardApis;
+    constructor(network?: Network, config?: MidgardConfig);
+    private getMimirDetails;
+    /**
+     *
+     * @returns an array of Pools
+     */
+    getPools(): Promise<PoolDetail[]>;
+    getAllInboundAddresses(): Promise<InboundAddressesItem[]>;
+    /**
+     * Gets the Inbound Details
+     * @returns inbound details
+     */
+    getInboundDetails(): Promise<Record<string, InboundDetail>>;
+    private getConstantsDetails;
+    /**
+     *
+     * @returns the outbound Tx Value in RUNE (Basemount)
+     */
+    getScheduledOutboundValue(): Promise<CryptoAmount>;
+    /**
+     * Function that wraps Mimir and Constants to return the value from a given constant name. Searchs Mimir first.
+     *
+     * @param networkValueName the network value to be used to search the contsants
+     * @returns the mimir or constants value
+     */
+    getNetworkValues(): Promise<Record<string, number>>;
+    /**
+     * Gets the latest block using the Health endpoint within Midgard
+     *
+     * @returns
+     */
+    getLatestBlockHeight(): Promise<number>;
+    /**
+     * Gets actions related to a txID
+     * @param txHash transaction id
+     * @returns Type Action array of objects
+     */
+    getActions(txHash: string): Promise<Action[]>;
+}

package/lib/utils/swap.d.ts

@@ -0,0 +1,71 @@
+import { Asset, Chain } from '@xchainjs/xchain-util';
+import { BigNumber } from 'bignumber.js';
+import { CryptoAmount } from '../crypto-amount';
+import { LiquidityPool } from '../liquidity-pool';
+import { ThorchainCache } from '../thorchain-cache';
+import { SwapOutput } from '../types';
+/**
+ *
+ * @param inputAmount - amount to swap
+ * @param pool - Pool Data, RUNE and ASSET Depths
+ * @param toRune - Direction of Swap. True if swapping to RUNE.
+ * @returns
+ */
+export declare const getSwapFee: (inputAmount: CryptoAmount, pool: LiquidityPool, toRune: boolean) => CryptoAmount;
+/**
+ * Works out the swap slip for a given swap.
+ *
+ * @param inputAmount - amount to swap
+ * @param pool - Pool Data, RUNE and ASSET Depths
+ * @param toRune - Direction of Swap. True if swapping to RUNE.
+ * @returns The amount of slip. Needs to * 100 to get percentage.
+ */
+export declare const getSwapSlip: (inputAmount: CryptoAmount, pool: LiquidityPool, toRune: boolean) => BigNumber;
+/**
+ *
+ * @param inputAmount - amount to swap
+ * @param pool - Pool Data, RUNE and ASSET Depths
+ * @param toRune - Direction of Swap. True if swapping to RUNE.
+ * @returns The output amount
+ */
+export declare const getSwapOutput: (inputAmount: CryptoAmount, pool: LiquidityPool, toRune: boolean) => CryptoAmount;
+export declare const getDoubleSwapOutput: (inputAmount: CryptoAmount, pool1: LiquidityPool, pool2: LiquidityPool) => CryptoAmount;
+/**
+ *
+ * @param inputAmount - amount to swap
+ * @param pool - Pool Data, RUNE and ASSET Depths
+ * @returns swap output object - output - fee - slip
+ */
+export declare const getSingleSwap: (inputAmount: CryptoAmount, pool: LiquidityPool, toRune: boolean) => SwapOutput;
+export declare const getDoubleSwapSlip: (inputAmount: CryptoAmount, pool1: LiquidityPool, pool2: LiquidityPool) => BigNumber;
+export declare const getDoubleSwapFee: (inputAmount: CryptoAmount, pool1: LiquidityPool, pool2: LiquidityPool, thorchainCache: ThorchainCache) => Promise<CryptoAmount>;
+/**
+ *
+ * @param inputAmount - amount to swap
+ * @param pool - Pool Data, RUNE and ASSET Depths
+ * @param toRune - Direction of Swap. True if swapping to RUNE.
+ * @returns swap output object - output - fee - slip
+ */
+export declare const getDoubleSwap: (inputAmount: CryptoAmount, pool1: LiquidityPool, pool2: LiquidityPool, thorchainCache: ThorchainCache) => Promise<SwapOutput>;
+/**
+ * Works out the required inbound or outbound fee based on the chain.
+ * Call getInboundDetails to get the current gasRate
+ *
+ * @param sourceAsset
+ * @param gasRate
+ * @see https://dev.thorchain.org/thorchain-dev/thorchain-and-fees#fee-calcuation-by-chain
+ * @returns
+ */
+export declare const calcNetworkFee: (asset: Asset, gasRate: BigNumber) => CryptoAmount;
+/**
+ * Return the chain for a given Asset This method should live somewhere else.
+ * @param chain
+ * @returns the gas asset type for the given chain
+ */
+export declare const getChainAsset: (chain: Chain) => Asset;
+/**
+ *
+ * @param chain - input chain string
+ * @returns - returns correct chain from string
+ */
+export declare const getChain: (chain: string) => Chain;

package/lib/utils/thornode.d.ts

@@ -0,0 +1,26 @@
+import { Network } from '@xchainjs/xchain-client';
+import { LastBlock, Pool, TxOutItem, TxResponse } from '@xchainjs/xchain-thornode';
+export declare type ThornodeConfig = {
+    apiRetries: number;
+    thornodeBaseUrls: string[];
+};
+export declare class Thornode {
+    private config;
+    private network;
+    private transactionsApi;
+    private queueApi;
+    private networkApi;
+    private poolsApi;
+    constructor(network?: Network, config?: ThornodeConfig);
+    /**
+     * Returns the oubound transactions held by THORChain due to outbound delay
+     * May be empty if there are no transactions
+     *
+     * @returns {ScheduledQueueItem} Array
+     *
+     */
+    getscheduledQueue(): Promise<TxOutItem[]>;
+    getTxData(txHash: string): Promise<TxResponse>;
+    getLastBlock(height?: number): Promise<LastBlock[]>;
+    getPools(): Promise<Pool[]>;
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@xchainjs/xchain-thorchain-query",
+  "version": "0.1.0-alpha",
+  "license": "MIT",
+  "description": "Thorchain query module that is resposible for estimating swap calculations and add/remove liquidity for thorchain ",
+  "keywords": [
+    "XChain",
+    "Thorchain-query"
+  ],
+  "author": "THORChain",
+  "homepage": "https://github.com/xchainjs/xchainjs-lib#readme",
+  "main": "lib/index.js",
+  "module": "lib/index.esm.js",
+  "typings": "lib/index.d.ts",
+  "directories": {
+    "lib": "lib",
+    "test": "__tests__"
+  },
+  "files": [
+    "lib"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:xchainjs/xchainjs-lib.git"
+  },
+  "scripts": {
+    "clean": "rimraf lib/**",
+    "build": "yarn clean && rollup -c",
+    "test": "jest",
+    "e2e": "jest --config jest.config.e2e.js",
+    "lint": "eslint \"{src,__tests__}/**/*.ts\" --fix --max-warnings 0",
+    "prepublishOnly": "yarn build",
+    "postversion": "git push --follow-tags"
+  },
+  "devDependencies": {
+    "@xchainjs/xchain-client": "^0.13.0",
+    "@xchainjs/xchain-midgard": "^0.1.0-alpha2",
+    "@xchainjs/xchain-thornode": "^0.1.0-alpha4",
+    "@xchainjs/xchain-util": "^0.9.0",
+    "axios": "^0.25.0",
+    "axios-retry": "^3.2.5",
+    "bignumber.js": "^9.0.0",
+    "rimraf": "~3.0.2"
+  },
+  "peerDependencies": {
+    "@xchainjs/xchain-client": "^0.13.0",
+    "@xchainjs/xchain-midgard": "^0.1.0-alpha2",
+    "@xchainjs/xchain-thornode": "^0.1.0-alpha4",
+    "@xchainjs/xchain-util": "^0.9.0",
+    "axios": "^0.25.0",
+    "axios-retry": "^3.2.5",
+    "bignumber.js": "^9.0.0",
+    "rimraf": "~3.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}