@atomiqlabs/sdk 8.1.8 → 8.3.5

package/dist/types/lnurl/LNURLWithdraw.d.ts

@@ -1,6 +1,7 @@
 /**
- * LNURL-withdraw request parameters
- * @category Bitcoin
+ * Response of the LNURL-withdraw link
+ *
+ * @category Lightning
  */
 export type LNURLWithdrawParams = {
     tag: "withdrawRequest";
@@ -14,15 +15,17 @@ export type LNURLWithdrawParams = {
     payLink?: string;
 };
 /**
- * LNURL-withdraw parameters with URL
- * @category Bitcoin
+ * Response of the LNURL-withdraw link with the added original url
+ *
+ * @category Lightning
  */
 export type LNURLWithdrawParamsWithUrl = LNURLWithdrawParams & {
     url: string;
 };
 /**
- * LNURL-withdraw specification
- * @category Bitcoin
+ * Parsed LNURL-withdraw specification
+ *
+ * @category Lightning
  */
 export type LNURLWithdraw = {
     type: "withdraw";
@@ -31,12 +34,16 @@ export type LNURLWithdraw = {
     params: LNURLWithdrawParamsWithUrl;
 };
 /**
- * Type guard for LNURL-withdraw
- * @category Bitcoin
+ * Type guard for {@link LNURLWithdraw}
+ *
+ * @category Lightning
+ * @internal
  */
 export declare function isLNURLWithdraw(value: any): value is LNURLWithdraw;
 /**
- * Type guard for LNURL-withdraw parameters
- * @category Bitcoin
+ * Type guard for {@link LNURLWithdrawParams}
+ *
+ * @category Lightning
+ * @internal
  */
 export declare function isLNURLWithdrawParams(obj: any): obj is LNURLWithdrawParams;

package/dist/types/lnurl/LNURLWithdraw.js

@@ -2,8 +2,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isLNURLWithdrawParams = exports.isLNURLWithdraw = void 0;
 /**
- * Type guard for LNURL-withdraw
- * @category Bitcoin
+ * Type guard for {@link LNURLWithdraw}
+ *
+ * @category Lightning
+ * @internal
  */
 function isLNURLWithdraw(value) {
     return (typeof value === "object" &&
@@ -15,8 +17,10 @@ function isLNURLWithdraw(value) {
 }
 exports.isLNURLWithdraw = isLNURLWithdraw;
 /**
- * Type guard for LNURL-withdraw parameters
- * @category Bitcoin
+ * Type guard for {@link LNURLWithdrawParams}
+ *
+ * @category Lightning
+ * @internal
  */
 function isLNURLWithdrawParams(obj) {
     return obj.tag === "withdrawRequest";

package/dist/types/wallets/LightningInvoiceCreateService.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Invoice getter callback for the {@link LightningInvoiceCreateService}
+ *
+ * @category Lightning
+ */
+export type LightningWalletCallback = (valueSats: number, abortSignal?: AbortSignal) => Promise<string>;
+/**
+ * Service that creates on-demand fixed amount bolt11 lightning network invoices, optionally
+ *  specifying minimum and maximum swappable sats amount. This used for exact input Smart chain ->
+ *  Lightning swaps.
+ *
+ * @category Lightning
+ */
+export type LightningInvoiceCreateService = {
+    getInvoice: LightningWalletCallback;
+    minMsats?: bigint;
+    maxMSats?: bigint;
+};
+/**
+ * Type guard for {@link LightningInvoiceCreateService}
+ *
+ * @internal
+ */
+export declare function isLightningInvoiceCreateService(obj: any): obj is LightningInvoiceCreateService;

package/dist/types/wallets/LightningInvoiceCreateService.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isLightningInvoiceCreateService = void 0;
+/**
+ * Type guard for {@link LightningInvoiceCreateService}
+ *
+ * @internal
+ */
+function isLightningInvoiceCreateService(obj) {
+    return typeof (obj) === "object" &&
+        typeof (obj.getInvoice) === "function" &&
+        (obj.minMsats == null || typeof (obj.minMsats) === "bigint") &&
+        (obj.maxMSats == null || typeof (obj.maxMSats) === "bigint");
+}
+exports.isLightningInvoiceCreateService = isLightningInvoiceCreateService;

package/dist/types/wallets/MinimalBitcoinWalletInterface.d.ts

@@ -1,7 +1,8 @@
 import { Transaction } from "@scure/btc-signer";
 /**
  * A type with minimum possible required data about a bitcoin wallet to be able to estimate fees and produce unsigned
- *  PSBTs
+ *  funded PSBTs with address's UTXOs
+ *
  * @category Bitcoin
  */
 export type MinimalBitcoinWalletInterface = {
@@ -10,6 +11,7 @@ export type MinimalBitcoinWalletInterface = {
 };
 /**
  * A type with minimum possible required data about a bitcoin wallet to be able to estimate fees and sign PSBTs
+ *
  * @category Bitcoin
  */
 export type MinimalBitcoinWalletInterfaceWithSigner = MinimalBitcoinWalletInterface & {

package/dist/types/wallets/MinimalLightningNetworkWalletInterface.d.ts

@@ -1,6 +1,8 @@
 /**
- * A type with minimum possible required functionality to be usable with lightning network swaps
- * @category Bitcoin
+ * A type with minimum possible required functionality to be usable with lightning network swaps, i.e.
+ *  a function to pay bolt11 lightning network invoices.
+ *
+ * @category Lightning
  */
 export type MinimalLightningNetworkWalletInterface = {
     payInvoice: (bolt11PaymentRequest: string) => Promise<string>;

package/dist/utils/BitcoinUtils.d.ts

@@ -4,6 +4,7 @@ import { BTC_NETWORK } from "@scure/btc-signer/utils";
 import { Buffer } from "buffer";
 import { Transaction } from "@scure/btc-signer";
 import { CoinselectAddressTypes } from "../bitcoin/coinselect2";
+export declare function fromOutputScript(network: BTC_NETWORK, outputScriptHex: string): string;
 export declare function toOutputScript(network: BTC_NETWORK, address: string): Buffer;
 export declare function toCoinselectAddressType(outputScript: Uint8Array): CoinselectAddressTypes;
 /**

package/dist/utils/BitcoinUtils.js

@@ -1,9 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.parsePsbtTransaction = exports.toCoinselectAddressType = exports.toOutputScript = void 0;
+exports.parsePsbtTransaction = exports.toCoinselectAddressType = exports.toOutputScript = exports.fromOutputScript = void 0;
 const utils_1 = require("@scure/btc-signer/utils");
 const buffer_1 = require("buffer");
 const btc_signer_1 = require("@scure/btc-signer");
+function fromOutputScript(network, outputScriptHex) {
+    return (0, btc_signer_1.Address)(network).encode(btc_signer_1.OutScript.decode(buffer_1.Buffer.from(outputScriptHex, "hex")));
+}
+exports.fromOutputScript = fromOutputScript;
 function toOutputScript(network, address) {
     const outputScript = (0, btc_signer_1.Address)(network).decode(address);
     switch (outputScript.type) {

package/dist/utils/SwapUtils.d.ts

@@ -11,7 +11,10 @@ import { OnchainForGasSwap } from "../swaps/trusted/onchain/OnchainForGasSwap";
 import { LnForGasSwap } from "../swaps/trusted/ln/LnForGasSwap";
 import { ISwap } from "../swaps/ISwap";
 /**
- * Type mapping from SwapType enum to specific swap class implementations
+ * Type mapping from SwapType enum to specific swap class implementations, it is important
+ *  to pass the chain type generic, since different chains support different swap protocols
+ *  for some directions.
+ *
  * @category Utilities
  */
 export type SwapTypeMapping<T extends ChainType> = {
@@ -26,6 +29,60 @@ export type SwapTypeMapping<T extends ChainType> = {
 };
 /**
  * Type guard to check if a swap is of a specific swap type
+ *
  * @category Utilities
  */
 export declare function isSwapType<T extends ChainType, S extends SwapType>(swap: ISwap<T>, swapType: S): swap is SwapTypeMapping<T>[S];
+/**
+ * Helper information about various swap protocol and their features:
+ * - `requiresInputWallet`: Whether a swap requires a connected wallet on the input chain able to sign
+ *  arbitrary transaction
+ * - `requiresOutputWallet`: Whether a swap requires a connected wallet on the output chain able to sign
+ *  arbitrary transactions
+ * - `supportsGasDrop`: Whether a swap supports the "gas drop" feature, allowing to user to receive a small
+ *  amount of native token as part of the swap when swapping to smart chains
+ *
+ * @category Core
+ */
+export declare const SwapProtocolInfo: {
+    readonly 2: {
+        readonly requiresInputWallet: true;
+        readonly requiresOutputWallet: false;
+        readonly supportsGasDrop: false;
+    };
+    readonly 3: {
+        readonly requiresInputWallet: true;
+        readonly requiresOutputWallet: false;
+        readonly supportsGasDrop: false;
+    };
+    readonly 0: {
+        readonly requiresInputWallet: false;
+        readonly requiresOutputWallet: true;
+        readonly supportsGasDrop: false;
+    };
+    readonly 1: {
+        readonly requiresInputWallet: false;
+        readonly requiresOutputWallet: true;
+        readonly supportsGasDrop: false;
+    };
+    readonly 6: {
+        readonly requiresInputWallet: true;
+        readonly requiresOutputWallet: false;
+        readonly supportsGasDrop: true;
+    };
+    readonly 7: {
+        readonly requiresInputWallet: false;
+        readonly requiresOutputWallet: false;
+        readonly supportsGasDrop: true;
+    };
+    readonly 4: {
+        readonly requiresInputWallet: false;
+        readonly requiresOutputWallet: false;
+        readonly supportsGasDrop: false;
+    };
+    readonly 5: {
+        readonly requiresInputWallet: false;
+        readonly requiresOutputWallet: false;
+        readonly supportsGasDrop: false;
+    };
+};

package/dist/utils/SwapUtils.js

@@ -1,9 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isSwapType = void 0;
+exports.SwapProtocolInfo = exports.isSwapType = void 0;
 const SwapType_1 = require("../enums/SwapType");
 /**
  * Type guard to check if a swap is of a specific swap type
+ *
  * @category Utilities
  */
 function isSwapType(swap, swapType) {
@@ -16,3 +17,56 @@ function isSwapType(swap, swapType) {
     return swap.getType() === swapType;
 }
 exports.isSwapType = isSwapType;
+/**
+ * Helper information about various swap protocol and their features:
+ * - `requiresInputWallet`: Whether a swap requires a connected wallet on the input chain able to sign
+ *  arbitrary transaction
+ * - `requiresOutputWallet`: Whether a swap requires a connected wallet on the output chain able to sign
+ *  arbitrary transactions
+ * - `supportsGasDrop`: Whether a swap supports the "gas drop" feature, allowing to user to receive a small
+ *  amount of native token as part of the swap when swapping to smart chains
+ *
+ * @category Core
+ */
+exports.SwapProtocolInfo = {
+    [SwapType_1.SwapType.TO_BTC]: {
+        requiresInputWallet: true,
+        requiresOutputWallet: false,
+        supportsGasDrop: false
+    },
+    [SwapType_1.SwapType.TO_BTCLN]: {
+        requiresInputWallet: true,
+        requiresOutputWallet: false,
+        supportsGasDrop: false
+    },
+    [SwapType_1.SwapType.FROM_BTC]: {
+        requiresInputWallet: false,
+        requiresOutputWallet: true,
+        supportsGasDrop: false
+    },
+    [SwapType_1.SwapType.FROM_BTCLN]: {
+        requiresInputWallet: false,
+        requiresOutputWallet: true,
+        supportsGasDrop: false
+    },
+    [SwapType_1.SwapType.SPV_VAULT_FROM_BTC]: {
+        requiresInputWallet: true,
+        requiresOutputWallet: false,
+        supportsGasDrop: true
+    },
+    [SwapType_1.SwapType.FROM_BTCLN_AUTO]: {
+        requiresInputWallet: false,
+        requiresOutputWallet: false,
+        supportsGasDrop: true
+    },
+    [SwapType_1.SwapType.TRUSTED_FROM_BTC]: {
+        requiresInputWallet: false,
+        requiresOutputWallet: false,
+        supportsGasDrop: false
+    },
+    [SwapType_1.SwapType.TRUSTED_FROM_BTCLN]: {
+        requiresInputWallet: false,
+        requiresOutputWallet: false,
+        supportsGasDrop: false
+    }
+};

package/dist/utils/TokenUtils.d.ts

@@ -1,11 +1,19 @@
 import { Token } from "../types/Token";
 /**
  * Converts a raw bigint amount to a human-readable string with decimals
+ *
+ * @param amount Amount in base units
+ * @param token Token
+ *
  * @category Utilities
  */
-export declare function toHumanReadableString(amount: bigint, currencySpec: Token): string;
+export declare function toHumanReadableString(amount: bigint, token: Token): string;
 /**
  * Parses a human-readable decimal string to a raw bigint amount
+ *
+ * @param amount Amount in base units
+ * @param token Token
+ *
  * @category Utilities
  */
-export declare function fromHumanReadableString(amount: string, currencySpec: Token): bigint | null;
+export declare function fromHumanReadableString(amount: string, token: Token): bigint | null;

package/dist/utils/TokenUtils.js

@@ -4,23 +4,31 @@ exports.fromHumanReadableString = exports.toHumanReadableString = void 0;
 const Utils_1 = require("./Utils");
 /**
  * Converts a raw bigint amount to a human-readable string with decimals
+ *
+ * @param amount Amount in base units
+ * @param token Token
+ *
  * @category Utilities
  */
-function toHumanReadableString(amount, currencySpec) {
+function toHumanReadableString(amount, token) {
     if (amount == null)
         return "";
-    return (0, Utils_1.toDecimal)(amount, currencySpec.decimals, undefined, currencySpec.displayDecimals);
+    return (0, Utils_1.toDecimal)(amount, token.decimals, undefined, token.displayDecimals);
 }
 exports.toHumanReadableString = toHumanReadableString;
 /**
  * Parses a human-readable decimal string to a raw bigint amount
+ *
+ * @param amount Amount in base units
+ * @param token Token
+ *
  * @category Utilities
  */
-function fromHumanReadableString(amount, currencySpec) {
+function fromHumanReadableString(amount, token) {
     if (amount === "" || amount == null)
         return null;
     try {
-        return (0, Utils_1.fromDecimal)(amount, currencySpec.decimals);
+        return (0, Utils_1.fromDecimal)(amount, token.decimals);
     }
     catch (e) {
         return null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atomiqlabs/sdk",
-  "version": "8.1.8",
+  "version": "8.3.5",
   "description": "atomiq labs SDK for cross-chain swaps between smart chains and bitcoin",
   "main": "./dist/index.js",
   "types:": "./dist/index.d.ts",
@@ -23,9 +23,9 @@
   "author": "adambor",
   "license": "ISC",
   "dependencies": {
-    "@atomiqlabs/base": "^13.1.4",
+    "@atomiqlabs/base": "^13.1.9",
     "@atomiqlabs/bolt11": "1.6.1",
-    "@atomiqlabs/btc-mempool": "^1.0.3",
+    "@atomiqlabs/btc-mempool": "^1.0.4",
     "@atomiqlabs/messenger-nostr": "^2.0.0",
     "@noble/ciphers": "^1.2.1",
     "@noble/hashes": "^1.7.1",

package/src/bitcoin/coinselect2/utils.ts

@@ -25,6 +25,12 @@ const TX_OUTPUT_P2WPKH = 22;
 const TX_OUTPUT_P2WSH = 34;
 const TX_OUTPUT_P2TR = 34;
 
+/**
+ * Defines a type of the address used by the wallet, for proper coinselection (as coinselection
+ *  depends on estimating the cost for spending the input + the cost of adding a change output)
+ *
+ * @category Bitcoin
+ */
 export type CoinselectAddressTypes = "p2sh-p2wpkh" | "p2wpkh" | "p2wsh" | "p2tr" | "p2pkh";
 
 export type CoinselectTxInput = {

package/src/bitcoin/wallet/BitcoinWallet.ts

@@ -11,6 +11,7 @@ import {BitcoinRpcWithAddressIndex} from "@atomiqlabs/base";
 
 /**
  * UTXO data structure for Bitcoin wallets
+ *
  * @category Bitcoin
  */
 export type BitcoinWalletUtxo = {
@@ -29,6 +30,7 @@ export type BitcoinWalletUtxo = {
 
 /**
  * Identifies the address type of a Bitcoin address
+ *
  * @category Bitcoin
  */
 export function identifyAddressType(address: string, network: BTC_NETWORK): CoinselectAddressTypes {
@@ -51,15 +53,17 @@ export function identifyAddressType(address: string, network: BTC_NETWORK): Coin
 const logger = getLogger("BitcoinWallet: ");
 
 /**
- * Abstract base class for Bitcoin wallet implementations
+ * Abstract base class for Bitcoin wallet implementations, using bitcoin rpc with address index
+ *  as a backend for fetching balances, UTXOs, etc.
+ *
  * @category Bitcoin
  */
 export abstract class BitcoinWallet implements IBitcoinWallet {
 
-    rpc: BitcoinRpcWithAddressIndex<any>;
-    network: BTC_NETWORK;
-    feeMultiplier: number;
-    feeOverride?: number;
+    protected readonly rpc: BitcoinRpcWithAddressIndex<any>;
+    protected readonly network: BTC_NETWORK;
+    protected feeMultiplier: number;
+    protected feeOverride?: number;
 
     constructor(mempoolApi: BitcoinRpcWithAddressIndex<any>, network: BTC_NETWORK, feeMultiplier: number = 1.25, feeOverride?: number) {
         this.rpc = mempoolApi;
@@ -68,6 +72,9 @@ export abstract class BitcoinWallet implements IBitcoinWallet {
         this.feeOverride = feeOverride;
     }
 
+    /**
+     * @inheritDoc
+     */
     async getFeeRate(): Promise<number> {
         if(this.feeOverride!=null) {
             return this.feeOverride;
@@ -75,14 +82,35 @@ export abstract class BitcoinWallet implements IBitcoinWallet {
         return Math.floor((await this.rpc.getFeeRate())*this.feeMultiplier);
     }
 
+    /**
+     * Internal helper function for sending a raw transaction through the underlying RPC
+     *
+     * @param rawHex Serialized bitcoin transaction in hexadecimal format
+     * @returns txId Transaction ID of the submitted bitcoin transaction
+     *
+     * @protected
+     */
     protected _sendTransaction(rawHex: string): Promise<string> {
         return this.rpc.sendRawTransaction(rawHex);
     }
 
+    /**
+     * Internal helper function for fetching the balance of the wallet given a specific bitcoin wallet address
+     *
+     * @param address
+     * @protected
+     */
     protected _getBalance(address: string): Promise<{ confirmedBalance: bigint; unconfirmedBalance: bigint }> {
         return this.rpc.getAddressBalances(address);
     }
 
+    /**
+     * Internal helper function for fetching the UTXO set of a given wallet address
+     *
+     * @param sendingAddress
+     * @param sendingAddressType
+     * @protected
+     */
     protected async _getUtxoPool(
         sendingAddress: string,
         sendingAddressType: CoinselectAddressTypes
@@ -121,6 +149,14 @@ export abstract class BitcoinWallet implements IBitcoinWallet {
         return utxoPool;
     }
 
+    /**
+     *
+     * @param sendingAccounts
+     * @param recipient
+     * @param amount
+     * @param feeRate
+     * @protected
+     */
     protected async _getPsbt(
         sendingAccounts: {
             pubkey: string,

package/src/bitcoin/wallet/IBitcoinWallet.ts

@@ -1,7 +1,8 @@
 import {Transaction} from "@scure/btc-signer";
 
 /**
- * Type guard to check if an object implements IBitcoinWallet
+ * Type guard to check if an object implements {@link IBitcoinWallet}
+ *
  * @category Bitcoin
  */
 export function isIBitcoinWallet(val: any): val is IBitcoinWallet {
@@ -18,24 +19,78 @@ export function isIBitcoinWallet(val: any): val is IBitcoinWallet {
 }
 
 /**
- * Interface for Bitcoin wallet operations
+ * Interface to be implemented by Bitcoin wallets
+ *
  * @category Bitcoin
  */
 export interface IBitcoinWallet {
+    /**
+     * Signs and broadcasts a transaction sending `amount` of sats to `address`, optionally with the
+     *  `feeRate` sats/vB fee rate.
+     *
+     * @param address Destination address of the transaction
+     * @param amount Amount of satoshis to send (1 BTC = 100,000,000 sats)
+     * @param feeRate Optional fee rate in sats/vB to use for the transaction
+     */
     sendTransaction(address: string, amount: bigint, feeRate?: number): Promise<string>;
+
+    /**
+     * Funds (populates the inputs) for a given PSBT from wallet's UTXO set
+     *
+     * @param psbt PSBT to add the inputs to
+     * @param feeRate Optional fee rate in sats/vB to use for the transaction
+     */
     fundPsbt(psbt: Transaction, feeRate?: number): Promise<Transaction>;
+
+    /**
+     * Signs inputs in the provided PSBT
+     *
+     * @param psbt A PSBT to sign
+     * @param signInputs Indices of the inputs to sign
+     */
     signPsbt(psbt: Transaction, signInputs: number[]): Promise<Transaction>;
 
+    /**
+     * Returns the current fee rate in sats/vB
+     */
     getFeeRate(): Promise<number>;
 
+    /**
+     * Estimates a total fee in satoshis for a given transaction
+     *
+     * @param address Destination address of the transaction
+     * @param amount Amount of satoshis to send (1 BTC = 100,000,000 sats)
+     * @param feeRate Optional fee rate in sats/vB to use for the transaction
+     */
     getTransactionFee(address: string, amount: bigint, feeRate?: number): Promise<number>;
+
+    /**
+     * Estimates a total fee in satoshis for a given transaction as identified by the PSBT
+     *
+     * @param psbt A PSBT to which additional inputs from wallet's UTXO set will be added and fee estimated
+     * @param feeRate Optional fee rate in sats/vB to use for the transaction
+     */
     getFundedPsbtFee(psbt: Transaction, feeRate?: number): Promise<number>;
 
+    /**
+     * Returns the bitcoin address suitable for receiving funds
+     */
     getReceiveAddress(): string;
+
+    /**
+     * Returns confirmed and unconfirmed balance in satoshis of the wallet
+     */
     getBalance(): Promise<{
         confirmedBalance: bigint,
         unconfirmedBalance: bigint
     }>;
+
+    /**
+     * Returns the maximum spendable balance in satoshis given a specific PSBT that should be funded
+     *
+     * @param psbt A PSBT to which additional inputs from wallet's UTXO set will be added and fee estimated
+     * @param feeRate Optional fee rate in sats/vB to use for the transaction
+     */
     getSpendableBalance(psbt?: Transaction, feeRate?: number): Promise<{
         balance: bigint,
         feeRate: number,