@atomiqlabs/sdk 8.1.8 → 8.3.5

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
+ *
+ * @category Pricing
  */
 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
 }

package/src/enums/SwapType.ts

@@ -1,15 +1,75 @@
-
 /**
- * Enum representing different types of swaps
+ * Enum representing different types of swap protocols used by atomiq.
+ *
  * @category Core
  */
 export enum SwapType {
+    /**
+     * Legacy escrow (PrTLC) based swap for Bitcoin -> Smart chains, requires manual initiation of the swap
+     *  on the destination chain.
+     *
+     * Handled by {@link FromBTCWrapper} & {@link FromBTCSwap}.
+     *
+     * Legacy swaps are only used on Solana!
+     */
     FROM_BTC=0,
+    /**
+     * Legacy escrow (HTLC) based swap for Bitcoin Lightning -> Smart chains, requires manual settlement of the swap on the
+     *  destination network once the lightning network payment is received by the LP
+     *
+     * Handled by {@link FromBTCLNWrapper} & {@link FromBTCLNSwap}.
+     *
+     * Legacy swaps are only used on Solana!
+     */
     FROM_BTCLN=1,
+    /**
+     * Escrow based (PrTLC) swap for Smart chains -> Bitcoin
+     *
+     * Handled by {@link ToBTCWrapper} & {@link ToBTCSwap}.
+     */
     TO_BTC=2,
+    /**
+     * Escrow based (HTLC) swap for Smart chains -> Bitcoin Lightning
+     *
+     * Handled by {@link ToBTCLNWrapper} & {@link ToBTCLNSwap}.
+     */
     TO_BTCLN=3,
+    /**
+     * Trusted swap for Bitcoin -> Smart chains, to be used for minor amounts to get gas tokens on the destination
+     *  chain, which is only needed for Solana, which still uses legacy swaps and doesn't support newer
+     *  {@link SPV_VAULT_FROM_BTC} & {@link FROM_BTCLN_AUTO} swaps.
+     *
+     * Handled by {@link OnchainForGasWrapper} & {@link OnchainForGasSwap}.
+     */
     TRUSTED_FROM_BTC=4,
+    /**
+     * Trusted swap for Bitcoin Lightning -> Smart chains, to be used for minor amounts to get gas tokens on the
+     *  destination chain, which is only needed for Solana, which still uses legacy swaps and doesn't support newer
+     *  {@link SPV_VAULT_FROM_BTC} & {@link FROM_BTCLN_AUTO} swaps.
+     *
+     * Handled by {@link LnForGasWrapper} & {@link LnForGasSwap}.
+     */
     TRUSTED_FROM_BTCLN=5,
+    /**
+     * New spv vault (UTXO-controlled vault) based swaps for Bitcoin -> Smart chain swaps not requiring any
+     *  initiation on the destination chain, and with the added possibility for the user to receive a
+     *  native token on the destination chain as part of the swap (a "gas drop" feature).
+     *
+     * Handled by {@link SpvFromBTCWrapper} & {@link SpvFromBTCSwap}.
+     *
+     * Used on all the supported chains except Solana!
+     */
     SPV_VAULT_FROM_BTC=6,
+    /**
+     * New escrow based (HTLC) swaps for Bitcoin Lightning -> Smart chain swaps not requiring manual
+     *  settlement on the destination by the user, and instead letting the LP initiate the escrow,
+     *  with the permissionless watchtower network managing the claiming of HTLC, with the swap secret
+     *  broadcasted over Nostr. Also adds a possibility for the user to receive a native token on the
+     *  destination chain as part of the swap (a "gas drop" feature).
+     *
+     * Handled by {@link FromBTCLNAutoWrapper} & {@link FromBTCLNAutoSwap}.
+     *
+     * Used on all the supported chains except Solana!
+     */
     FROM_BTCLN_AUTO=7
 }

package/src/errors/IntermediaryError.ts

@@ -1,9 +1,13 @@
 /**
  * An error or inconsistency in the intermediary's returned data, this will blacklist the intermediary
+ *
  * @category Errors
  */
 export class IntermediaryError extends Error {
 
+    /**
+     * Whether the error is recoverable and intermediary (LP) shouldn't be blacklisted for it
+     */
     recoverable: boolean;
     originalStack?: string;
 

package/src/errors/RequestError.ts

@@ -1,6 +1,7 @@
 
 /**
  * An error returned by the intermediary in a http response
+ *
  * @category Errors
  */
 export class RequestError extends Error {
@@ -18,7 +19,13 @@ export class RequestError extends Error {
         this.httpCode = httpCode;
     }
 
-    static parse(msg: string, httpCode: number): RequestError {
+    /**
+     * Parses a message + a response code returned by the intermediary (LP) as an error
+     *
+     * @param msg Raw response
+     * @param httpCode HTTP response status code
+     */
+    static parse(msg: string, httpCode: number): RequestError | OutOfBoundsError {
         try {
             const parsed = JSON.parse(msg);
             msg = parsed.msg;
@@ -34,11 +41,18 @@ export class RequestError extends Error {
 
 /**
  * An error indicating out of bounds (amount too high or too low) on swap initialization
+ *
  * @category Errors
  */
 export class OutOfBoundsError extends RequestError {
 
+    /**
+     * Swap minimum in base units of the token in which the quote was requested
+     */
     min: bigint;
+    /**
+     * Swap maximum in base units of the token in which the quote was requested
+     */
     max: bigint;
 
     constructor(msg: string, httpCode: number, min: bigint, max: bigint) {

package/src/errors/UserError.ts

@@ -1,5 +1,6 @@
 /**
  * An error on the user side, such as invalid address provided
+ *
  * @category Errors
  */
 export class UserError extends Error {

package/src/index.ts

@@ -3,6 +3,8 @@ export {
     BitcoinRpc,
     BitcoinRpcWithAddressIndex,
     BitcoinNetwork,
+    BtcHeader,
+    BtcStoredHeader,
     BtcRelay,
     ChainData,
     ChainInterface,
@@ -20,7 +22,8 @@ export {
     IStorageManager,
     StorageObject,
     SwapContract,
-    SwapData
+    SwapData,
+    AbstractSigner
 } from "@atomiqlabs/base";
 
 export {
@@ -29,10 +32,12 @@ export {
     MempoolApiError
 } from "@atomiqlabs/btc-mempool";
 
+export {
+    NostrMessenger
+} from "@atomiqlabs/messenger-nostr";
+
 export * from "./bitcoin/wallet/BitcoinWallet";
 export * from "./bitcoin/wallet/IBitcoinWallet";
-export * from "./types/wallets/MinimalBitcoinWalletInterface";
-export * from "./types/wallets/MinimalLightningNetworkWalletInterface";
 export * from "./bitcoin/wallet/SingleAddressBitcoinWallet";
 
 export {CoinselectAddressTypes} from "./bitcoin/coinselect2";
@@ -43,7 +48,6 @@ export * from "./enums/SwapDirection";
 export * from "./enums/SwapType";
 
 export * from "./errors/IntermediaryError";
-export * from "./errors/PaymentAuthError";
 export * from "./errors/RequestError";
 export * from "./errors/UserError";
 
@@ -119,9 +123,12 @@ export * from "./types/fees/PercentagePPM";
 export * from "./types/lnurl/LNURLPay";
 export * from "./types/lnurl/LNURLWithdraw";
 
+export * from "./types/wallets/MinimalBitcoinWalletInterface";
+export * from "./types/wallets/MinimalLightningNetworkWalletInterface";
+export * from "./types/wallets/LightningInvoiceCreateService";
+
 export * from "./types/AmountData";
 export * from "./types/CustomPriceFunction";
-export * from "./types/PriceInfoType";
 export * from "./types/SwapExecutionAction";
 export * from "./types/SwapWithSigner";
 export * from "./types/Token";

package/src/intermediaries/Intermediary.ts

@@ -6,7 +6,8 @@ import {tryWithRetries} from "../utils/RetryUtils";
 
 /**
  * Services offered by an intermediary
- * @category Pricing and LPs
+ *
+ * @category LPs
  */
 export type ServicesType = {
     [key in SwapType]?: SwapHandlerInfoType
@@ -14,7 +15,8 @@ export type ServicesType = {
 
 /**
  * Reputation data for an intermediary on a single chain
- * @category Pricing and LPs
+ *
+ * @category LPs
  */
 export type SingleChainReputationType = {
     [token: string]: {
@@ -31,21 +33,35 @@ export type SingleChainReputationType = {
 
 /**
  * Smart chain liquidity data
- * @category Pricing and LPs
+ *
+ * @category LPs
  */
 export type SCLiquidity = {
     [token: string]: bigint
 };
 
 /**
- * Represents a liquidity provider/intermediary
- * @category Pricing and LPs
+ * Represents an intermediary (liquidity provider)
+ *
+ * @category LPs
  */
 export class Intermediary {
 
+    /**
+     * Base URL where the intermediary is listening for HTTP requests
+     */
     readonly url: string;
+    /**
+     * Addresses of the intermediary on smart chains, used for checking the provided signatures
+     */
     readonly addresses: {[chainIdentifier: string]: string};
+    /**
+     * Swap protocol services offered by the intermediary
+     */
     readonly services: ServicesType;
+    /**
+     * Input/output swap bounds for various swap protocols offered by the intermediary
+     */
     readonly swapBounds: {
         [swapType in SwapType]?: {
             [chainIdentifier: string]: {
@@ -62,8 +78,21 @@ export class Intermediary {
             }
         }
     }
+    /**
+     * Reputation of the intermediary on different smart chains, this is only fetched
+     *  on-demand when creating a swap where reputation is checked
+     */
     reputation: { [chainIdentifier: string]: SingleChainReputationType } = {};
+    /**
+     * Liquidity of the intermediary across different smart chains, this is only fetched
+     *  on-demand when creating a swap where intermediary's liquidity is checked
+     */
     liquidity: { [chainIdentifier: string]: SCLiquidity } = {};
+    /**
+     * Data about a lightning network node used by this intermediary, if it offers lightning
+     *  network swaps, this is only fetched on-demand when creating a Bitcoin Lightning -> Smart chain
+     *  swap through the intermediary (which necessitates checking intermediary's channel capacities)
+     */
     lnData?: LNNodeLiquidity;
 
     constructor(
@@ -96,6 +125,13 @@ export class Intermediary {
         }
     }
 
+    /**
+     * Returns the input/output swap limit for given swap type, chain and token
+     *
+     * @param swapType Swap protocol service to check
+     * @param chainId Chain identifier of the smart chain to check
+     * @param tokenAddress Address of the token to check
+     */
     getSwapLimits(swapType: SwapType, chainId: string, tokenAddress: string): {input: {min?: bigint, max?: bigint}, output: {min?: bigint, max?: bigint}} | undefined {
         return this.swapBounds[swapType]?.[chainId]?.[tokenAddress];
     }
@@ -103,8 +139,8 @@ export class Intermediary {
     /**
      * Returns tokens supported by the intermediary, optionally constrained to the specific swap types
      *
-     * @param chainIdentifier
-     * @param swapTypesArr
+     * @param chainIdentifier Chain identifier of the smart chain to check
+     * @param swapTypesArr An array of swap type services to check
      * @private
      */
     private getSupportedTokens(chainIdentifier: string, swapTypesArr: SwapType[] = [
@@ -127,9 +163,10 @@ export class Intermediary {
     /**
      * Fetches, returns and saves the reputation of the intermediary, either for all or just for a single token
      *
-     * @param chainIdentifier
-     * @param swapContract
-     * @param tokens
+     * @param chainIdentifier Chain identifier of the chain on which to fetch the reputation
+     * @param swapContract Swap contract for the requested smart chain
+     * @param tokens An optional array of tokens to fetch the data for (by default it uses all tokens supported
+     *  by the intermediary)
      * @param abortSignal
      */
     async getReputation(
@@ -166,11 +203,11 @@ export class Intermediary {
     }
 
     /**
-     * Fetches, returns and saves the liquidity of the intermediaryfor a specific token
+     * Fetches, returns and saves the liquidity of the intermediary for a specific token
      *
-     * @param chainIdentifier
-     * @param swapContract
-     * @param token
+     * @param chainIdentifier Chain identifier of the chain on which to fetch the reputation
+     * @param swapContract Swap contract for the requested smart chain
+     * @param token Token address of the token to fetch the liquidity for
      * @param abortSignal
      */
     async getLiquidity(
@@ -191,11 +228,21 @@ export class Intermediary {
         return result;
     }
 
+    /**
+     * Checks whether the intermediary supports swaps of any tokens on the smart chain
+     *
+     * @param chainIdentifier Chain identifier of the smart chain
+     */
     supportsChain(chainIdentifier: string): boolean {
         if(this.addresses[chainIdentifier]==null) return false;
         return this.getSupportedTokens(chainIdentifier).size!==0;
     }
 
+    /**
+     * Returns intermediary's address on a given smart chain
+     *
+     * @param chainIdentifier Chain identifier of the smart chain
+     */
     getAddress(chainIdentifier: string) {
         return this.addresses[chainIdentifier];
     }