@atomiqlabs/sdk 8.1.7 → 8.3.1

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,5 +1,7 @@
 /**
- * A type with minimum possible required functionality to be usable with lightning network swaps
+ * 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 Bitcoin
  */
 export type MinimalLightningNetworkWalletInterface = {

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,58 @@ 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
+ */
+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,54 @@ 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
+ */
+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.7",
+  "version": "8.3.1",
   "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/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,

package/src/bitcoin/wallet/SingleAddressBitcoinWallet.ts

@@ -6,15 +6,16 @@ import {identifyAddressType, BitcoinWallet} from "./BitcoinWallet";
 import {BitcoinRpcWithAddressIndex} from "@atomiqlabs/base";
 
 /**
- * Bitcoin wallet implementation for single-address scenarios
+ * Bitcoin wallet implementation deriving a single address from a WIF encoded private key
+ *
  * @category Bitcoin
  */
 export class SingleAddressBitcoinWallet extends BitcoinWallet {
 
-    readonly privKey?: Uint8Array;
-    readonly pubkey: Uint8Array;
-    readonly address: string;
-    readonly addressType: CoinselectAddressTypes;
+    protected readonly privKey?: Uint8Array;
+    protected readonly pubkey: Uint8Array;
+    protected readonly address: string;
+    protected readonly addressType: CoinselectAddressTypes;
 
     constructor(
         mempoolApi: BitcoinRpcWithAddressIndex<any>,
@@ -41,12 +42,20 @@ export class SingleAddressBitcoinWallet extends BitcoinWallet {
         this.addressType = identifyAddressType(this.address, network);
     }
 
-    protected toBitcoinWalletAccounts(): {pubkey: string, address: string, addressType: CoinselectAddressTypes}[] {
+    /**
+     * Returns all the wallet addresses controlled by the wallet
+     *
+     * @protected
+     */
+    protected toBitcoinWalletAccounts(): [{pubkey: string, address: string, addressType: CoinselectAddressTypes}] {
         return [{
             pubkey: Buffer.from(this.pubkey).toString("hex"), address: this.address, addressType: this.addressType
         }];
     }
 
+    /**
+     * @inheritDoc
+     */
     async sendTransaction(address: string, amount: bigint, feeRate?: number): Promise<string> {
         if(!this.privKey) throw new Error("Not supported.");
         const {psbt, fee} = await super._getPsbt(this.toBitcoinWalletAccounts(), address, Number(amount), feeRate);
@@ -57,6 +66,9 @@ export class SingleAddressBitcoinWallet extends BitcoinWallet {
         return await super._sendTransaction(txHex);
     }
 
+    /**
+     * @inheritDoc
+     */
     async fundPsbt(inputPsbt: Transaction, feeRate?: number): Promise<Transaction> {
         const {psbt} = await super._fundPsbt(this.toBitcoinWalletAccounts(), inputPsbt, feeRate);
         if(psbt==null) {
@@ -65,6 +77,9 @@ export class SingleAddressBitcoinWallet extends BitcoinWallet {
         return psbt;
     }
 
+    /**
+     * @inheritDoc
+     */
     async signPsbt(psbt: Transaction, signInputs: number[]): Promise<Transaction> {
         if(!this.privKey) throw new Error("Not supported.");
         for(let signInput of signInputs) {
@@ -73,19 +88,32 @@ export class SingleAddressBitcoinWallet extends BitcoinWallet {
         return psbt;
     }
 
+    /**
+     * @inheritDoc
+     */
     async getTransactionFee(address: string, amount: bigint, feeRate?: number): Promise<number> {
         const {fee} = await super._getPsbt(this.toBitcoinWalletAccounts(), address, Number(amount), feeRate);
         return fee;
     }
 
+    /**
+     * @inheritDoc
+     */
     async getFundedPsbtFee(basePsbt: Transaction, feeRate?: number): Promise<number> {
         const {fee} = await super._fundPsbt(this.toBitcoinWalletAccounts(), basePsbt, feeRate);
         return fee;
     }
 
+    /**
+     * @inheritDoc
+     */
     getReceiveAddress(): string {
         return this.address;
     }
+
+    /**
+     * @inheritDoc
+     */
     getBalance(): Promise<{
         confirmedBalance: bigint,
         unconfirmedBalance: bigint
@@ -93,6 +121,9 @@ export class SingleAddressBitcoinWallet extends BitcoinWallet {
         return this._getBalance(this.address);
     }
 
+    /**
+     * @inheritDoc
+     */
     getSpendableBalance(psbt?: Transaction, feeRate?: number): Promise<{
         balance: bigint,
         feeRate: number,
@@ -101,6 +132,11 @@ export class SingleAddressBitcoinWallet extends BitcoinWallet {
         return this._getSpendableBalance([{address: this.address, addressType: this.addressType}], psbt, feeRate);
     }
 
+    /**
+     * Generates a new random private key WIF that can be used to instantiate the bitcoin wallet instance
+     *
+     * @returns A WIF encoded bitcoin private key
+     */
     static generateRandomPrivateKey(network?: BTC_NETWORK): string {
          return WIF(network).encode(randomPrivateKeyBytes());
     }

package/src/enums/FeeType.ts

@@ -1,9 +1,16 @@
 
 /**
  * Enum representing types of fees in a swap
+ *
  * @category Pricing and LPs
  */
 export enum FeeType {
+    /**
+     * Swap fee taken by the LP
+     */
     SWAP = 0,
+    /**
+     * Network fee to cover the transactions on the destination (output) network
+     */
     NETWORK_OUTPUT = 1
 }

package/src/enums/SwapAmountType.ts

@@ -1,9 +1,16 @@
 
 /**
  * Enum representing whether the swap amount is exact input or exact output
+ *
  * @category Core
  */
 export enum SwapAmountType {
+    /**
+     * Swap amount specified in the input token
+     */
     EXACT_IN = 1,
+    /**
+     * Swap amount specified in the output token
+     */
     EXACT_OUT = 0
 }

package/src/enums/SwapDirection.ts

@@ -1,9 +1,16 @@
 
 /**
  * Enum representing the direction of a swap (from or to Bitcoin)
+ *
  * @category Core
  */
 export enum SwapDirection {
+    /**
+     * Swaps from bitcoin to smart chains (Solana, Starknet, EVM, etc.)
+     */
     FROM_BTC=0,
+    /**
+     * Swaps from smart chains (Solana, Starknet, EVM, etc.) to bitcoin
+     */
     TO_BTC=1
 }