@atomiqlabs/sdk 8.1.8 → 8.3.5

package/src/intermediaries/IntermediaryDiscovery.ts

@@ -1,6 +1,6 @@
 import {Intermediary, ServicesType} from "./Intermediary";
 import {SwapType} from "../enums/SwapType";
-import {SignatureVerificationError, SwapContract} from "@atomiqlabs/base";
+import {SwapContract} from "@atomiqlabs/base";
 import {EventEmitter} from "events";
 import {Buffer} from "buffer";
 import {bigIntMax, bigIntMin, extendAbortController} from "../utils/Utils";
@@ -10,8 +10,9 @@ import {httpGet} from "../http/HttpUtils";
 import {tryWithRetries} from "../utils/RetryUtils";
 
 /**
- * Swap handler type enum for intermediary communication
- * @category Pricing and LPs
+ * Swap handler type mapping for intermediary communication
+ *
+ * @category LPs
  */
 export enum SwapHandlerType {
     TO_BTC = "TO_BTC",
@@ -26,7 +27,8 @@ export enum SwapHandlerType {
 
 /**
  * Swap handler information type
- * @category Pricing and LPs
+ *
+ * @category LPs
  */
 export type SwapHandlerInfoType = {
     swapFeePPM: number,
@@ -47,7 +49,8 @@ type InfoHandlerResponseEnvelope = {
 
 /**
  * Token bounds (min/max) for swaps
- * @category Pricing and LPs
+ *
+ * @category LPs
  */
 export type TokenBounds = {
     [token: string]: {
@@ -57,16 +60,18 @@ export type TokenBounds = {
 }
 
 /**
- * Multi-chain token bounds
- * @category Pricing and LPs
+ * Multi-chain token bounds (min/max) for swaps
+ *
+ * @category LPs
  */
 export type MultichainTokenBounds = {
     [chainId: string]: TokenBounds
 }
 
 /**
- * Swap bounds by type
- * @category Pricing and LPs
+ * Swap bounds by swap protocol type
+ *
+ * @category LPs
  */
 export type SwapBounds = {
     [key in SwapType]?: TokenBounds
@@ -74,7 +79,8 @@ export type SwapBounds = {
 
 /**
  * Multi-chain swap bounds
- * @category Pricing and LPs
+ *
+ * @category LPs
  */
 export type MultichainSwapBounds = {
     [key in SwapType]?: MultichainTokenBounds
@@ -82,7 +88,7 @@ export type MultichainSwapBounds = {
 
 /**
  * Converts SwapHandlerType (represented as string & used in REST API communication with intermediaries) to regular
- *  SwapType
+ *  {@link SwapType}
  *
  * @param swapHandlerType
  */
@@ -104,11 +110,13 @@ function swapHandlerTypeToSwapType(swapHandlerType: SwapHandlerType): SwapType {
             return SwapType.SPV_VAULT_FROM_BTC;
         case SwapHandlerType.FROM_BTCLN_AUTO:
             return SwapType.FROM_BTCLN_AUTO;
+        default:
+            return SwapType.TRUSTED_FROM_BTCLN;
     }
 }
 
 /**
- * A default intermediary comparator, only takes to announced fee into consideration
+ * A default intermediary comparator, only takes the announced fee into consideration
  *
  * @param swapType
  * @param tokenAddress
@@ -147,22 +155,41 @@ const REGISTRY_URL = "https://api.github.com/repos/adambor/SolLightning-registry
 const DEFAULT_CHAIN = "SOLANA";
 
 /**
- * Discovery service for available liquidity providers/intermediaries
- * @category Pricing and LPs
+ * Discovery service for available intermediaries (liquidity providers)
+ *
+ * @category LPs
  */
 export class IntermediaryDiscovery extends EventEmitter {
 
+    /**
+     * A current list of active intermediaries
+     */
     intermediaries: Intermediary[] = [];
 
+    /**
+     * Swap contracts for checking intermediary signatures
+     */
     swapContracts: {[key: string]: SwapContract};
+    /**
+     * Registry URL used as a source for the list of intermediaries, this should be a link to a
+     *  github-hosted JSON file
+     */
     registryUrl: string;
 
+    /**
+     * Timeout for the HTTP handshake (/info) requests sent to the intermediaries
+     */
     httpRequestTimeout?: number;
     /**
-     * Maximum time (in millis) to wait for other LP's responses after the first one was founds
+     * Maximum time (in millis) to wait for other intermediary's responses after the first one was founds
      */
     maxWaitForOthersTimeout?: number;
 
+    /**
+     * The intermediary URLs passed in the constructor, to be used instead of querying the registry
+     *
+     * @private
+     */
     private overrideNodeUrls?: string[];
 
     constructor(
@@ -283,9 +310,13 @@ export class IntermediaryDiscovery extends EventEmitter {
     }
 
     /**
-     * Returns the intermediary at the provided URL, either from the already fetched list of LPs or fetches the data on-demand
+     * Returns the intermediary at the provided URL, either from the already fetched list of LPs
+     *  or fetches the data on-demand, by sending the handshake HTTP request (/info) to the LP.
      *
-     * @param url
+     * Doesn't save the fetched intermediary to the list of intermediaries if it isn't already
+     *  part of the known intermediaries
+     *
+     * @param url Base URL of the intermediary, which accepts HTTP requests
      * @param abortSignal
      */
     getIntermediary(url: string, abortSignal?: AbortSignal): Promise<Intermediary | null> {
@@ -296,6 +327,7 @@ export class IntermediaryDiscovery extends EventEmitter {
 
     /**
      * Reloads the saves a list of intermediaries
+     *
      * @param abortSignal
      */
     async reloadIntermediaries(abortSignal?: AbortSignal): Promise<void> {
@@ -334,6 +366,9 @@ export class IntermediaryDiscovery extends EventEmitter {
         return this.reloadIntermediaries(abortSignal);
     }
 
+    /**
+     * Returns known swap bounds (in satoshis - BTC) by aggregating values from all known intermediaries
+     */
     getMultichainSwapBounds(): MultichainSwapBounds {
         const bounds: MultichainSwapBounds = {};
 
@@ -366,7 +401,7 @@ export class IntermediaryDiscovery extends EventEmitter {
     }
 
     /**
-     * Returns aggregate swap bounds (in sats - BTC) as indicated by the intermediaries
+     * Returns aggregate swap bounds (in satoshis - BTC) as indicated by the intermediaries
      */
     getSwapBounds(chainIdentifier: string): SwapBounds {
         const bounds: SwapBounds = {};
@@ -397,15 +432,15 @@ export class IntermediaryDiscovery extends EventEmitter {
     }
 
     /**
-     * Returns the aggregate swap minimum (in sats - BTC) for a specific swap type & token
+     * Returns the aggregate swap minimum (in satoshis - BTC) for a specific swap type & token
      *  as indicated by the intermediaries
      *
-     * @param chainIdentifier
-     * @param swapType
-     * @param token
+     * @param chainIdentifier Chain identifier of the smart chain
+     * @param swapType Swap protocol type
+     * @param tokenAddress Token address
      */
-    getSwapMinimum(chainIdentifier: string, swapType: SwapType, token: any): number | null {
-        const tokenStr = token.toString();
+    getSwapMinimum(chainIdentifier: string, swapType: SwapType, tokenAddress: string): number | null {
+        const tokenStr = tokenAddress.toString();
         return this.intermediaries.reduce<number | null>((prevMin: number | null, intermediary: Intermediary) => {
             const swapService = intermediary.services[swapType];
             if(swapService==null) return prevMin;
@@ -417,15 +452,15 @@ export class IntermediaryDiscovery extends EventEmitter {
     }
 
     /**
-     * Returns the aggregate swap maximum (in sats - BTC) for a specific swap type & token
+     * Returns the aggregate swap maximum (in satoshis - BTC) for a specific swap type & token
      *  as indicated by the intermediaries
      *
-     * @param chainIdentifier
-     * @param swapType
-     * @param token
+     * @param chainIdentifier Chain identifier of the smart chain
+     * @param swapType Swap protocol type
+     * @param tokenAddress Token address
      */
-    getSwapMaximum(chainIdentifier: string, swapType: SwapType, token: any): number | null {
-        const tokenStr = token.toString();
+    getSwapMaximum(chainIdentifier: string, swapType: SwapType, tokenAddress: string): number | null {
+        const tokenStr = tokenAddress.toString();
         return this.intermediaries.reduce<number | null>((prevMax: number | null, intermediary: Intermediary) => {
             const swapService = intermediary.services[swapType];
             if(swapService==null) return prevMax;
@@ -439,13 +474,13 @@ export class IntermediaryDiscovery extends EventEmitter {
     /**
      * Returns swap candidates for a specific swap type & token address
      *
-     * @param chainIdentifier
-     * @param swapType
-     * @param tokenAddress
+     * @param chainIdentifier Chain identifier of the smart chain
+     * @param swapType Swap protocol type
+     * @param tokenAddress Token address
      * @param amount Amount to be swapped in sats - BTC
      * @param count How many intermediaries to return at most
      */
-    getSwapCandidates(chainIdentifier: string, swapType: SwapType, tokenAddress: any, amount?: bigint, count?: number): Intermediary[] {
+    getSwapCandidates(chainIdentifier: string, swapType: SwapType, tokenAddress: string, amount?: bigint, count?: number): Intermediary[] {
         const candidates = this.intermediaries.filter(e => {
             const swapService = e.services[swapType];
             if(swapService==null) return false;

package/src/prices/RedundantSwapPrice.ts

@@ -13,7 +13,8 @@ import {tryWithRetries} from "../utils/RetryUtils";
 
 /**
  * Asset configuration for redundant swap pricing
- * @category Pricing and LPs
+ *
+ * @category Pricing
  */
 export type RedundantSwapPriceAssets<T extends MultiChain> = {
     binancePair?: string,
@@ -49,10 +50,20 @@ const logger = getLogger("RedundantSwapPrice: ");
 /**
  * Swap price API using multiple price sources, handles errors on the APIs and automatically switches between them, such
  *  that there always is a functional API
- * @category Pricing and LPs
+ *
+ * @category Pricing
  */
 export class RedundantSwapPrice<T extends MultiChain> extends ICachedSwapPrice<T> {
 
+    /**
+     * Creates a new {@link RedundantSwapPrice} instance from an asset list and other data, using all
+     *  the available price providers: {@link BinancePriceProvider}, {@link OKXPriceProvider},
+     *  {@link CoinGeckoPriceProvider}, {@link CoinPaprikaPriceProvider}, {@link KrakenPriceProvider}
+     *
+     * @param maxAllowedFeeDiffPPM Maximum allowed price difference between returned swap prices & market prices
+     * @param assets Specifications of the assets
+     * @param cacheTimeout Timeout of the internal cache holding prices
+     */
     static createFromTokenMap<T extends MultiChain>(maxAllowedFeeDiffPPM: bigint, assets: RedundantSwapPriceAssets<T>, cacheTimeout?: number): RedundantSwapPrice<T> {
         const priceApis = [
             new BinancePriceProvider(assets.map(coinData => {
@@ -90,8 +101,8 @@ export class RedundantSwapPrice<T extends MultiChain> extends ICachedSwapPrice<T
         return new RedundantSwapPrice(maxAllowedFeeDiffPPM, assets, priceApis, cacheTimeout);
     }
 
-    coinsDecimals: CoinDecimals<T> = {};
-    priceApis: {
+    protected coinsDecimals: CoinDecimals<T> = {};
+    protected priceApis: {
         priceApi: IPriceProvider<T>,
         operational?: boolean
     }[];
@@ -174,7 +185,7 @@ export class RedundantSwapPrice<T extends MultiChain> extends ICachedSwapPrice<T
      * @param chainIdentifier
      * @param token
      * @param abortSignal
-     * @private
+     * @protected
      */
     protected fetchPrice<C extends ChainIds<T>>(chainIdentifier: C, token: string, abortSignal?: AbortSignal): Promise<bigint> {
         return tryWithRetries(async () => {
@@ -193,12 +204,14 @@ export class RedundantSwapPrice<T extends MultiChain> extends ICachedSwapPrice<T
         }, undefined, RequestError, abortSignal);
     }
 
+    /**
+     * @inheritDoc
+     */
     protected getDecimals<C extends ChainIds<T>>(chainIdentifier: C, token: string): number | null {
         if(this.coinsDecimals[chainIdentifier]==null) return null;
         return this.coinsDecimals[chainIdentifier]?.[token.toString()] ?? null;
     }
 
-
     /**
      * Fetches BTC price in USD in parallel from multiple maybe operational price APIs
      *
@@ -228,6 +241,13 @@ export class RedundantSwapPrice<T extends MultiChain> extends ICachedSwapPrice<T
         }
     }
 
+    /**
+     * Fetches the USD prices, first tries to use the operational price API (if any) and if that fails it falls back
+     *  to using maybe operational price APIs
+     *
+     * @param abortSignal
+     * @protected
+     */
     protected fetchUsdPrice(abortSignal?: AbortSignal): Promise<number> {
         return tryWithRetries(() => {
             const operationalPriceApi = this.getOperationalPriceApi();

package/src/prices/SingleSwapPrice.ts

@@ -3,8 +3,9 @@ import {ICachedSwapPrice} from "./abstract/ICachedSwapPrice";
 import {ChainIds, MultiChain} from "../swapper/Swapper";
 
 /**
- * Swap price API using single price source
- * @category Pricing and LPs
+ * Swap price API using a single price source
+ *
+ * @category Pricing
  */
 export class SingleSwapPrice<T extends MultiChain> extends ICachedSwapPrice<T> {
 
@@ -29,17 +30,19 @@ export class SingleSwapPrice<T extends MultiChain> extends ICachedSwapPrice<T> {
     }
 
     /**
-     * Returns the decimal places of the specified token, or -1 if token should be ignored, returns null if
-     *  token is not found
-     *
-     * @param chainIdentifier
-     * @param token
-     * @protected
+     * @inheritDoc
      */
     protected getDecimals<C extends ChainIds<T>>(chainIdentifier: C, token: string): number | null {
         return this.priceProvider.getDecimals(chainIdentifier, token.toString());
     }
 
+    /**
+     * Fetches BTC price in USD
+     *
+     * @param abortSignal
+     * @protected
+     * @returns token price in uSats (micro sats)
+     */
     protected fetchUsdPrice(abortSignal?: AbortSignal): Promise<number> {
         return this.priceProvider.getUsdPrice(abortSignal);
     }

package/src/prices/SwapPriceWithChain.ts

@@ -6,7 +6,8 @@ import {PriceInfoType} from "../types/PriceInfoType";
 
 /**
  * Chain-specific wrapper for swap pricing
- * @category Pricing and LPs
+ *
+ * @category Pricing
  */
 export class SwapPriceWithChain<T extends MultiChain, ChainIdentifier extends ChainIds<T>> {
 
@@ -27,21 +28,21 @@ export class SwapPriceWithChain<T extends MultiChain, ChainIdentifier extends Ch
      * @param satsBaseFee Base fee in sats (BTC) as reported by the intermediary
      * @param feePPM PPM fee rate as reported by the intermediary
      * @param paidToken Amount of token to be paid to the swap
-     * @param token
-     * @param abortSignal
-     * @param preFetchedPrice Already pre-fetched price
+     * @param tokenAddress Token address to be paid
+     * @param abortSignal Abort signal
+     * @param preFetchedPrice An optional price pre-fetched with {@link preFetchPrice}
      */
     public async isValidAmountSend(
         amountSats: bigint,
         satsBaseFee: bigint,
         feePPM: bigint,
         paidToken: bigint,
-        token: string,
+        tokenAddress: string,
         abortSignal?: AbortSignal,
         preFetchedPrice?: bigint
     ): Promise<PriceInfoType> {
         return this.swapPrice.isValidAmountSend<ChainIdentifier>(
-            this.chainIdentifier, amountSats, satsBaseFee, feePPM, paidToken, token, abortSignal, preFetchedPrice
+            this.chainIdentifier, amountSats, satsBaseFee, feePPM, paidToken, tokenAddress, abortSignal, preFetchedPrice
         );
     }
 
@@ -52,39 +53,52 @@ export class SwapPriceWithChain<T extends MultiChain, ChainIdentifier extends Ch
      * @param satsBaseFee Base fee in sats (BTC) as reported by the intermediary
      * @param feePPM PPM fee rate as reported by the intermediary
      * @param receiveToken Amount of token to be received from the swap
-     * @param token
-     * @param abortSignal
-     * @param preFetchedPrice Already pre-fetched price
+     * @param tokenAddress Token address to be received
+     * @param abortSignal Abort signal
+     * @param preFetchedPrice An optional price pre-fetched with {@link preFetchPrice}
      */
     public async isValidAmountReceive(
         amountSats: bigint,
         satsBaseFee: bigint,
         feePPM: bigint,
         receiveToken: bigint,
-        token: string,
+        tokenAddress: string,
         abortSignal?: AbortSignal,
         preFetchedPrice?: bigint
     ): Promise<PriceInfoType> {
         return this.swapPrice.isValidAmountReceive<ChainIdentifier>(
-            this.chainIdentifier, amountSats, satsBaseFee, feePPM, receiveToken, token, abortSignal, preFetchedPrice
+            this.chainIdentifier, amountSats, satsBaseFee, feePPM, receiveToken, tokenAddress, abortSignal, preFetchedPrice
         );
     }
 
-    public preFetchPrice(token: string, abortSignal?: AbortSignal): Promise<bigint> {
-        return this.swapPrice.preFetchPrice<ChainIdentifier>(this.chainIdentifier, token, abortSignal);
+    /**
+     * Pre-fetches the pricing data for a given token, such that further calls to {@link isValidAmountReceive} or
+     *  {@link isValidAmountSend} are quicker and don't need to wait for the price fetch
+     *
+     * @param tokenAddress Token address
+     * @param abortSignal Abort signal
+     */
+    public preFetchPrice(tokenAddress: string, abortSignal?: AbortSignal): Promise<bigint> {
+        return this.swapPrice.preFetchPrice<ChainIdentifier>(this.chainIdentifier, tokenAddress, abortSignal);
     }
 
+    /**
+     * Pre-fetches the Bitcoin USD price data, such that further calls to {@link getBtcUsdValue},
+     *  {@link getTokenUsdValue} or {@link getUsdValue} are quicker and don't need to wait for the price fetch
+     *
+     * @param abortSignal
+     */
     public preFetchUsdPrice(abortSignal?: AbortSignal): Promise<number> {
         return this.swapPrice.preFetchUsdPrice(abortSignal);
     }
 
     /**
-     * Returns amount of {toToken} that are equivalent to {fromAmount} satoshis
+     * Returns amount of `toToken` that is equivalent to `fromAmount` satoshis
      *
-     * @param fromAmount        Amount of satoshis
-     * @param toToken           Token
+     * @param fromAmount Amount of satoshis
+     * @param toToken Token address
      * @param abortSignal
-     * @param preFetchedPrice
+     * @param preFetchedPrice An optional price pre-fetched with {@link preFetchPrice}
      * @throws {Error} when token is not found
      */
     public async getFromBtcSwapAmount(
@@ -99,12 +113,12 @@ export class SwapPriceWithChain<T extends MultiChain, ChainIdentifier extends Ch
     }
 
     /**
-     * Returns amount of satoshis that are equivalent to {fromAmount} of {fromToken}
+     * Returns amount of satoshis that are equivalent to `fromAmount` of `fromToken`
      *
      * @param fromAmount Amount of the token
-     * @param fromToken Token
+     * @param fromToken Token address
      * @param abortSignal
-     * @param preFetchedPrice Pre-fetched swap price if available
+     * @param preFetchedPrice An optional price pre-fetched with {@link preFetchPrice}
      * @throws {Error} when token is not found
      */
     public async getToBtcSwapAmount(
@@ -121,30 +135,53 @@ export class SwapPriceWithChain<T extends MultiChain, ChainIdentifier extends Ch
     /**
      * Returns whether the token should be ignored and pricing for it not calculated
      *
-     * @param tokenAddress
+     * @param tokenAddress Token address
      * @throws {Error} if token is not found
      */
     public shouldIgnore(tokenAddress: string): boolean {
         return this.swapPrice.shouldIgnore<ChainIdentifier>(this.chainIdentifier, tokenAddress);
     }
 
+    /**
+     * Returns the USD value of the bitcoin amount
+     *
+     * @param btcSats Bitcoin amount in satoshis
+     * @param abortSignal
+     * @param preFetchedUsdPrice An optional price pre-fetched with {@link preFetchUsdPrice}
+     */
     public async getBtcUsdValue(
         btcSats: bigint,
         abortSignal?: AbortSignal,
-        preFetchedPrice?: number
+        preFetchedUsdPrice?: number
     ): Promise<number> {
-        return this.swapPrice.getBtcUsdValue(btcSats, abortSignal, preFetchedPrice);
+        return this.swapPrice.getBtcUsdValue(btcSats, abortSignal, preFetchedUsdPrice);
     }
 
+    /**
+     * Returns the USD value of the smart chain token amount
+     *
+     * @param tokenAmount Amount of the token in base units
+     * @param tokenAddress Token address
+     * @param abortSignal
+     * @param preFetchedUsdPrice An optional price pre-fetched with {@link preFetchUsdPrice}
+     */
     public async getTokenUsdValue(
         tokenAmount: bigint,
-        token: string,
+        tokenAddress: string,
         abortSignal?: AbortSignal,
-        preFetchedPrice?: number
+        preFetchedUsdPrice?: number
     ): Promise<number> {
-        return this.swapPrice.getTokenUsdValue(this.chainIdentifier, tokenAmount, token, abortSignal, preFetchedPrice);
+        return this.swapPrice.getTokenUsdValue(this.chainIdentifier, tokenAmount, tokenAddress, abortSignal, preFetchedUsdPrice);
     }
 
+    /**
+     * Returns the USD value of the token amount
+     *
+     * @param amount Amount in base units of the token
+     * @param token Token to fetch the usd price for
+     * @param abortSignal
+     * @param preFetchedUsdPrice An optional price pre-fetched with {@link preFetchUsdPrice}
+     */
     public getUsdValue(
         amount: bigint,
         token: Token<ChainIdentifier>,

package/src/prices/abstract/IPriceProvider.ts

@@ -2,7 +2,7 @@ import {ChainIds, MultiChain} from "../../swapper/Swapper";
 
 /**
  * Coin type definition for price providers
- * @category Pricing and LPs
+ * @category Pricing
  */
 export type CoinType = {
     coinId: string;
@@ -11,7 +11,7 @@ export type CoinType = {
 
 /**
  * Constructor coin types for price providers
- * @category Pricing and LPs
+ * @category Pricing
  */
 export type CtorCoinTypes<T extends MultiChain> = {
     coinId?: string,
@@ -25,7 +25,7 @@ export type CtorCoinTypes<T extends MultiChain> = {
 
 /**
  * Coin types mapping by chain
- * @category Pricing and LPs
+ * @category Pricing
  */
 export type CoinTypes<T extends MultiChain> = {
     [chainId in keyof T]?: {
@@ -35,7 +35,7 @@ export type CoinTypes<T extends MultiChain> = {
 
 /**
  * Abstract base class for price provider implementations
- * @category Pricing and LPs
+ * @category Pricing
  */
 export abstract class IPriceProvider<T extends MultiChain> {