@atomiqlabs/sdk 8.1.8 → 8.3.5

package/dist/swapper/SwapperFactory.d.ts

@@ -5,6 +5,18 @@ import { SwapType } from "../enums/SwapType";
 import { SwapTypeMapping } from "../utils/SwapUtils";
 import { CustomPriceFunction } from "../types/CustomPriceFunction";
 import { MempoolApi, MempoolBitcoinRpc } from "@atomiqlabs/btc-mempool";
+/**
+ * Token definitions for a specific chain
+ */
+type TypedChainTokens<T extends ChainInitializer<any, any, any>> = {
+    [val in keyof T["tokens"]]: SCToken<T["chainId"]>;
+};
+/**
+ * Token resolver for a specific chain
+ */
+type TypedChainTokenResolver<T extends ChainInitializer<any, any, any>> = {
+    getToken: (address: string) => SCToken<T["chainId"]>;
+};
 type ChainTypeDict<T extends ChainInitializer<any, any, any>> = {
     [K in T["chainId"]]: T["chainType"];
 };
@@ -21,38 +33,51 @@ type OptionsDict<T extends ChainInitializer<any, any, any>> = {
 };
 type GetAllOptions<T extends readonly ChainInitializer<any, any, any>[]> = (T extends readonly [infer First extends ChainInitializer<any, any, any>, ...infer Rest extends ChainInitializer<any, any, any>[]] ? OptionsDict<First> & GetAllOptions<Rest> : unknown);
 /**
- * Configuration options for creating a typed Swapper instance
+ * Configuration options for creating a Swapper instance
+ *
  * @category Core
  */
 export type TypedSwapperOptions<T extends readonly ChainInitializer<any, any, any>[]> = {
+    /**
+     * A dictionary with chain-specific settings, like RPC URLs and others
+     */
     chains: GetAllOptions<T>;
-    chainStorageCtor?: <T extends StorageObject>(name: string) => IStorageManager<T>;
+    /**
+     * A function callback to retrieve a specific named storage container for key-value persistency. If not present, the
+     *  default browser Local Storage adapter is used. When you use the SDK in non-browser based environments you need
+     *  to provide this callback such that the SDK is able to use a custom storage adapter.
+     *
+     * @param storageName Name of the container to retrieve
+     */
+    chainStorageCtor?: <T extends StorageObject>(storageName: string) => IStorageManager<T>;
+    /**
+     * Maximum allowed pricing difference between intermediary (LP) returned rate and current market rate. In
+     *  parts-per-million, e.g. 2% is written as `20000`.
+     */
     pricingFeeDifferencePPM?: bigint;
+    /**
+     * Optional pricing function to use instead of default pricing APIs. See {@link CustomPriceFunction} for details.
+     */
     getPriceFn?: CustomPriceFunction;
+    /**
+     * Mempool API instance or URLs to use, if not provided the defaults will be used for the specified bitcoin network
+     */
     mempoolApi?: MempoolApi | MempoolBitcoinRpc | string | string[];
+    /**
+     * Data propagation messenger instance to use for broadcasting data to watchtowers. By default, a Nostr-based
+     *  messenger is used.
+     */
     messenger?: Messenger;
 } & SwapperOptions;
 /**
- * Token resolver for a specific chain
- * @category Core
- */
-export type TypedChainTokenResolver<T extends ChainInitializer<any, any, any>> = {
-    getToken: (address: string) => SCToken<T["chainId"]>;
-};
-/**
- * Token resolvers for all chains
+ * Token resolvers for all chains, resolve tokens based on their address
+ *
  * @category Core
  */
 export type TypedTokenResolvers<T extends readonly ChainInitializer<any, any, any>[]> = (T extends readonly [infer First extends ChainInitializer<any, any, any>, ...infer Rest extends ChainInitializer<any, any, any>[]] ? TokenResolverDict<First> & TypedTokenResolvers<Rest> : unknown);
-/**
- * Token definitions for a specific chain
- * @category Core
- */
-export type TypedChainTokens<T extends ChainInitializer<any, any, any>> = {
-    [val in keyof T["tokens"]]: SCToken<T["chainId"]>;
-};
 /**
  * All tokens including Bitcoin tokens
+ *
  * @category Core
  */
 export type TypedTokens<T extends readonly ChainInitializer<any, ChainType, any>[]> = GetAllTokens<T> & {
@@ -63,24 +88,47 @@ export type TypedTokens<T extends readonly ChainInitializer<any, ChainType, any>
 };
 /**
  * Type alias for a Swapper instance with typed chain support
+ *
  * @category Core
  */
 export type TypedSwapper<T extends readonly ChainInitializer<any, ChainType, any>[]> = Swapper<ToMultichain<T>>;
 /**
- * Type alias for a specific swap type on a chain
+ * Type alias for a specific swap type
+ *
  * @category Core
  */
 export type TypedSwap<T extends ChainInitializer<any, ChainType, any>, S extends SwapType> = SwapTypeMapping<T["chainType"]>[S];
 /**
  * Factory class for creating and initializing Swapper instances with typed chain support
+ *
  * @category Core
  */
 export declare class SwapperFactory<T extends readonly ChainInitializer<any, ChainType, any>[]> {
     readonly initializers: T;
+    /**
+     * All available tokens for the atomiq SDK
+     */
     Tokens: TypedTokens<T>;
+    /**
+     * Token resolvers for various smart chains supported by the SDK, allow fetching tokens based on their addresses
+     */
     TokenResolver: TypedTokenResolvers<T>;
     constructor(initializers: T);
+    /**
+     * Returns a new swapper instance with the passed options.
+     *
+     * The swapper returned here is not yet initialized, be sure to call {@link Swapper.init}, before
+     *  calling any other functions in the swapper instance.
+     *
+     * @param options Options for customizing the swapper instance
+     */
     newSwapper(options: TypedSwapperOptions<T>): TypedSwapper<T>;
+    /**
+     * Returns a new and already initialized swapper instance with the passed options. There is no need
+     *  to call {@link Swapper.init} anymore.
+     *
+     * @param options Options for customizing the swapper instance
+     */
     newSwapperInitialized(options: TypedSwapperOptions<T>): Promise<TypedSwapper<T>>;
 }
 export {};

package/dist/swapper/SwapperFactory.js

@@ -48,14 +48,21 @@ const nostrUrls = [
 ];
 /**
  * Factory class for creating and initializing Swapper instances with typed chain support
+ *
  * @category Core
  */
 class SwapperFactory {
     constructor(initializers) {
         this.initializers = initializers;
+        /**
+         * All available tokens for the atomiq SDK
+         */
         this.Tokens = {
             BITCOIN: Token_1.BitcoinTokens
         };
+        /**
+         * Token resolvers for various smart chains supported by the SDK, allow fetching tokens based on their addresses
+         */
         this.TokenResolver = {};
         this.initializers = initializers;
         initializers.forEach(initializer => {
@@ -78,6 +85,14 @@ class SwapperFactory {
             };
         });
     }
+    /**
+     * Returns a new swapper instance with the passed options.
+     *
+     * The swapper returned here is not yet initialized, be sure to call {@link Swapper.init}, before
+     *  calling any other functions in the swapper instance.
+     *
+     * @param options Options for customizing the swapper instance
+     */
     newSwapper(options) {
         options.bitcoinNetwork ??= base_1.BitcoinNetwork.MAINNET;
         options.storagePrefix ??= "atomiqsdk-" + options.bitcoinNetwork + "-";
@@ -86,13 +101,13 @@ class SwapperFactory {
         options.registryUrl ??= registries[options.bitcoinNetwork];
         let bitcoinRpc;
         if (options.mempoolApi != null) {
-            bitcoinRpc = options.mempoolApi instanceof btc_mempool_1.MempoolBitcoinRpc ? options.mempoolApi : new btc_mempool_1.MempoolBitcoinRpc(options.mempoolApi);
+            bitcoinRpc = options.mempoolApi instanceof btc_mempool_1.MempoolBitcoinRpc ? options.mempoolApi : new btc_mempool_1.MempoolBitcoinRpc(options.mempoolApi, options.bitcoinNetwork);
         }
         else {
             const urls = mempoolUrls[options.bitcoinNetwork];
             if (urls == null)
                 throw new Error(`No pre-configured urls for ${base_1.BitcoinNetwork[options.bitcoinNetwork]} network were found, please explicitly pass mempoolApi parameter!`);
-            bitcoinRpc = new btc_mempool_1.MempoolBitcoinRpc(urls);
+            bitcoinRpc = new btc_mempool_1.MempoolBitcoinRpc(urls, options.bitcoinNetwork);
         }
         const pricingAssets = [];
         Object.keys(SmartChainAssets_1.SmartChainAssets).forEach((ticker) => {
@@ -125,8 +140,14 @@ class SwapperFactory {
                 };
             }), options.getPriceFn)) :
             RedundantSwapPrice_1.RedundantSwapPrice.createFromTokenMap(options.pricingFeeDifferencePPM ?? 10000n, pricingAssets);
-        return new Swapper_1.Swapper(bitcoinRpc, chains, swapPricing, pricingAssets, options.messenger, options);
+        return new Swapper_1.Swapper(bitcoinRpc, bitcoinRpc, (btcRelay) => new btc_mempool_1.MempoolBtcRelaySynchronizer(btcRelay, bitcoinRpc), chains, swapPricing, pricingAssets, options.messenger, options);
     }
+    /**
+     * Returns a new and already initialized swapper instance with the passed options. There is no need
+     *  to call {@link Swapper.init} anymore.
+     *
+     * @param options Options for customizing the swapper instance
+     */
     async newSwapperInitialized(options) {
         const swapper = this.newSwapper(options);
         await swapper.init();

package/dist/swapper/SwapperUtils.d.ts

@@ -9,43 +9,51 @@ import { SCToken } from "../types/Token";
 import { LNURLWithdraw } from "../types/lnurl/LNURLWithdraw";
 import { LNURLPay } from "../types/lnurl/LNURLPay";
 /**
- * Utility class providing helper methods for swap operations
+ * Utility class providing helper methods for address parsing, token balances, serialization
+ *  and other miscellaneous things.
+ *
  * @category Core
  */
 export declare class SwapperUtils<T extends MultiChain> {
     readonly bitcoinNetwork: BTC_NETWORK;
     private readonly root;
     constructor(root: Swapper<T>);
+    /**
+     * Checks whether a passed address is a valid address on the smart chain
+     *
+     * @param address Address
+     * @param chainId Smart chain identifier string to check the address for
+     */
     isValidSmartChainAddress(address: string, chainId?: ChainIds<T>): boolean;
     /**
-     * Returns true if string is a valid BOLT11 bitcoin lightning invoice
+     * Checks whether an address is a valid BOLT11 bitcoin lightning invoice
      *
-     * @param lnpr
+     * @param address Address to check
      */
-    isLightningInvoice(lnpr: string): boolean;
+    isLightningInvoice(address: string): boolean;
     /**
-     * Returns true if string is a valid bitcoin address
+     * Checks whether an address is a valid bitcoin address
      *
-     * @param addr
+     * @param address Address to check
      */
-    isValidBitcoinAddress(addr: string): boolean;
+    isValidBitcoinAddress(address: string): boolean;
     /**
-     * Returns true if string is a valid BOLT11 bitcoin lightning invoice WITH AMOUNT
+     * Checks whether an address is a valid BOLT11 bitcoin lightning invoice WITH AMOUNT
      *
-     * @param lnpr
+     * @param address Address to check
      */
-    isValidLightningInvoice(lnpr: string): boolean;
+    isValidLightningInvoice(address: string): boolean;
     /**
-     * Returns true if string is a valid LNURL (no checking on type is performed)
+     * Checks whether an address is a valid LNURL (no checking on type is performed)
      *
-     * @param lnurl
+     * @param address Address to check
      */
-    isValidLNURL(lnurl: string): boolean;
+    isValidLNURL(address: string): boolean;
     /**
      * Returns type and data about an LNURL
      *
-     * @param lnurl
-     * @param shouldRetry
+     * @param lnurl LNURL link to check, can be either `pay` or `withdraw` type
+     * @param shouldRetry Optional whether HTTP requests should retried on failure
      */
     getLNURLTypeAndData(lnurl: string, shouldRetry?: boolean): Promise<LNURLPay | LNURLWithdraw | null>;
     /**
@@ -60,12 +68,12 @@ export declare class SwapperUtils<T extends MultiChain> {
     private parseLightningInvoice;
     private parseSmartchainAddress;
     /**
-     * General parser for bitcoin addresses, LNURLs, lightning invoices, smart chain addresses, also fetches LNURL data
-     *  (hence returns Promise)
+     * General parser for bitcoin addresses, LNURLs, lightning invoices, smart chain addresses. Also fetches LNURL data
+     *  (hence async and returns Promise).
      *
      * @param addressString Address to parse
      * @throws {Error} Error in address parsing
-     * @returns Address data or null if address doesn't conform to any known format
+     * @returns Address data or `null` if address doesn't conform to any known format
      */
     parseAddress(addressString: string): Promise<{
         address: string;
@@ -78,11 +86,11 @@ export declare class SwapperUtils<T extends MultiChain> {
     } | null>;
     /**
      * Synchronous general parser for bitcoin addresses, LNURLs, lightning invoices, smart chain addresses, doesn't fetch
-     *  LNURL data, reports swapType: null instead to prevent returning a Promise
+     *  LNURL data, returns `swapType: null` instead to prevent returning a Promise
      *
      * @param addressString Address to parse
      * @throws {Error} Error in address parsing
-     * @returns Address data or null if address doesn't conform to any known format
+     * @returns Address data or `null` if address doesn't conform to any known format
      */
     parseAddressSync(addressString: string): {
         address: string;
@@ -93,18 +101,21 @@ export declare class SwapperUtils<T extends MultiChain> {
         amount?: TokenAmount;
     } | null;
     /**
-     * Returns a random PSBT that can be used for fee estimation, the last output (the LP output) is omitted
-     *  to allow for coinselection algorithm to determine maximum sendable amount there
+     * Returns a random PSBT that can be used for fee estimation for SPV vault (UTXO-controlled vault) based swaps
+     *  {@link SwapType.SPV_VAULT_FROM_BTC}, the last output (the LP output) is omitted to allow for coinselection
+     *  algorithm to determine maximum sendable amount there
      *
-     * @param chainIdentifier
-     * @param includeGasToken   Whether to return the PSBT also with the gas token amount (increases the vSize by 8)
+     * @param chainIdentifier Smart chain to swap to
+     * @param includeGasToken Whether to return the PSBT also with the gas token amount (increases the vSize by 8)
      */
     getRandomSpvVaultPsbt<ChainIdentifier extends ChainIds<T>>(chainIdentifier: ChainIdentifier, includeGasToken?: boolean): Transaction;
     /**
      * Returns the spendable balance of a bitcoin wallet
      *
-     * @param wallet
-     * @param targetChain
+     * @param wallet Bitcoin wallet to check the spendable balance for, can either be a simple
+     *  bitcoin address string or a wallet object
+     * @param targetChain Destination smart chain for the swap, the ensures proper spendable balance
+     *  is estimated taking into consideration different swap primitives available on different chains
      * @param options Additional options
      */
     getBitcoinSpendableBalance(wallet: string | IBitcoinWallet | MinimalBitcoinWalletInterface, targetChain?: ChainIds<T>, options?: {
@@ -116,14 +127,15 @@ export declare class SwapperUtils<T extends MultiChain> {
         feeRate: number;
     }>;
     /**
-     * Returns the maximum spendable balance of the wallet, deducting the fee needed to initiate a swap for native balances
+     * Returns the maximum spendable balance of the smart chain wallet, deducting the fee needed
+     *  to initiate a swap for native balances
      */
     getSpendableBalance<ChainIdentifier extends ChainIds<T>>(wallet: string | T[ChainIdentifier]["Signer"] | T[ChainIdentifier]["NativeSigner"], token: SCToken<ChainIdentifier>, options?: {
         feeMultiplier?: number;
         feeRate?: any;
     }): Promise<TokenAmount>;
     /**
-     * Returns the address of the native currency of the chain
+     * Returns the address of the native currency of the smart chain
      */
     getNativeToken<ChainIdentifier extends ChainIds<T>>(chainIdentifier: ChainIdentifier): SCToken<ChainIdentifier>;
     /**
@@ -140,14 +152,49 @@ export declare class SwapperUtils<T extends MultiChain> {
     randomAddress<ChainIdentifier extends ChainIds<T>>(chainIdentifier: ChainIdentifier): string;
     /**
      * Signs and broadcasts the supplied smart chain transaction
+     *
+     * @param chainIdentifier Smart chain identifier string
+     * @param signer Signer to use for signing the transactions
+     * @param txs An array of transactions to sign
+     * @param abortSignal Abort signal
+     * @param onBeforePublish Callback invoked before a transaction is sent (invoked for every transaction to be sent)
      */
     sendAndConfirm<ChainIdentifier extends ChainIds<T>>(chainIdentifier: ChainIdentifier, signer: T[ChainIdentifier]["NativeSigner"] | T[ChainIdentifier]["Signer"], txs: T[ChainIdentifier]["TX"][], abortSignal?: AbortSignal, onBeforePublish?: (txId: string, rawTx: string) => Promise<void>): Promise<string[]>;
     /**
      * Broadcasts already signed smart chain transactions
+     *
+     * @param chainIdentifier Smart chain identifier string
+     * @param txs An array of already signed transactions
+     * @param abortSignal Abort signal
+     * @param onBeforePublish Callback invoked before a transaction is sent (invoked for every transaction to be sent)
      */
     sendSignedAndConfirm<ChainIdentifier extends ChainIds<T>>(chainIdentifier: ChainIdentifier, txs: T[ChainIdentifier]["SignedTXType"][], abortSignal?: AbortSignal, onBeforePublish?: (txId: string, rawTx: string) => Promise<void>): Promise<string[]>;
+    /**
+     * Serializes an unsigned smart chain transaction
+     *
+     * @param chainIdentifier Smart chain string identifier
+     * @param tx An unsigned transaction to serialize
+     */
     serializeUnsignedTransaction<ChainIdentifier extends ChainIds<T>>(chainIdentifier: ChainIdentifier, tx: T[ChainIdentifier]["TX"]): Promise<string>;
+    /**
+     * Deserializes an unsigned smart chain transaction
+     *
+     * @param chainIdentifier Smart chain string identifier
+     * @param tx Serialized unsigned transaction
+     */
     deserializeUnsignedTransaction<ChainIdentifier extends ChainIds<T>>(chainIdentifier: ChainIdentifier, tx: string): Promise<T[ChainIdentifier]["TX"]>;
+    /**
+     * Serializes a signed smart chain transaction
+     *
+     * @param chainIdentifier Smart chain string identifier
+     * @param tx A signed transaction to serialize
+     */
     serializeSignedTransaction<ChainIdentifier extends ChainIds<T>>(chainIdentifier: ChainIdentifier, tx: T[ChainIdentifier]["SignedTXType"]): Promise<string>;
+    /**
+     * Deserializes a signed smart chain transaction
+     *
+     * @param chainIdentifier Smart chain string identifier
+     * @param tx Serialized signed transaction
+     */
     deserializeSignedTransaction<ChainIdentifier extends ChainIds<T>>(chainIdentifier: ChainIdentifier, tx: string): Promise<T[ChainIdentifier]["SignedTXType"]>;
 }