@atomiqlabs/sdk 8.1.7 → 8.3.1

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,7 +33,8 @@ 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>[]> = {
@@ -33,26 +46,14 @@ export type TypedSwapperOptions<T extends readonly ChainInitializer<any, any, an
     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 +64,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) => {
@@ -127,6 +142,12 @@ class SwapperFactory {
             RedundantSwapPrice_1.RedundantSwapPrice.createFromTokenMap(options.pricingFeeDifferencePPM ?? 10000n, pricingAssets);
         return new Swapper_1.Swapper(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"]>;
 }