@atomiqlabs/sdk 8.1.8 → 8.3.5

package/src/swapper/SwapperWithSigner.ts

@@ -26,6 +26,11 @@ import {BtcToken, SCToken, Token} from "../types/Token";
 import {LNURLWithdraw} from "../types/lnurl/LNURLWithdraw";
 import {LNURLPay} from "../types/lnurl/LNURLPay";
 import {MempoolApi, MempoolBitcoinRpc} from "@atomiqlabs/btc-mempool";
+import {Messenger} from "@atomiqlabs/base";
+import {LightningInvoiceCreateService} from "../types/wallets/LightningInvoiceCreateService";
+import {Intermediary} from "../intermediaries/Intermediary";
+import {SpvFromBTCOptions} from "../swaps/spv_swaps/SpvFromBTCWrapper";
+import {SwapTypeMapping} from "../utils/SwapUtils";
 
 /**
  * Chain and signer-specific wrapper for automatic signer injection into swap methods
@@ -33,28 +38,47 @@ import {MempoolApi, MempoolBitcoinRpc} from "@atomiqlabs/btc-mempool";
  */
 export class SwapperWithSigner<T extends MultiChain, ChainIdentifier extends ChainIds<T>> {
 
+    private readonly signer: T[ChainIdentifier]["Signer"];
+    /**
+     * Underlying single chain swapper instance
+     */
+    private readonly swapper: SwapperWithChain<T, ChainIdentifier>;
+
+    /**
+     * Smart chain identifier of this swapper with chain and signer
+     */
     readonly chainIdentifier: ChainIdentifier;
-    readonly swapper: SwapperWithChain<T, ChainIdentifier>;
-    readonly signer: T[ChainIdentifier]["Signer"];
 
+    /**
+     * Pricing API used by the SDK
+     */
     get prices(): SwapPriceWithChain<T, ChainIdentifier> {
         return this.swapper.prices;
     }
+    /**
+     * Intermediary discovery instance
+     */
     get intermediaryDiscovery(): IntermediaryDiscovery {
         return this.swapper.intermediaryDiscovery;
     }
-    get mempoolApi(): MempoolApi {
-        return this.swapper.mempoolApi;
-    }
-    get bitcoinRpc(): MempoolBitcoinRpc {
-        return this.swapper.bitcoinRpc;
-    }
-    get bitcoinNetwork(): BTC_NETWORK {
-        return this.swapper.bitcoinNetwork;
-    }
+    /**
+     * Miscellaneous utility functions
+     */
     get Utils(): SwapperUtils<T> {
         return this.swapper.Utils;
     }
+    /**
+     * 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
+     *
+     * Uses a `Record` type here, use the {@link SwapProtocolInfo} import for a literal readonly type, with
+     *  pre-filled exact values in the type.
+     */
     get SwapTypeInfo() {
         return this.swapper.SwapTypeInfo;
     }
@@ -65,6 +89,16 @@ export class SwapperWithSigner<T extends MultiChain, ChainIdentifier extends Cha
         this.chainIdentifier = swapper.chainIdentifier;
     }
 
+    /**
+     * Creates Smart chain -> Bitcoin ({@link SwapType.TO_BTC}) swap
+     *
+     * @param tokenAddress Token address to pay with
+     * @param address Recipient's bitcoin address
+     * @param amount Amount to send in token based units (if `exactIn=true`) or receive in satoshis (if `exactIn=false`)
+     * @param exactIn Whether to use exact in instead of exact out
+     * @param additionalParams Additional parameters sent to the LP when creating the swap
+     * @param options Additional options for the swap
+     */
     createToBTCSwap(
         tokenAddress: string,
         address: string,
@@ -77,6 +111,15 @@ export class SwapperWithSigner<T extends MultiChain, ChainIdentifier extends Cha
             .then(swap => wrapSwapWithSigner(swap, this.signer));
     }
 
+    /**
+     * Creates Smart chain -> Bitcoin Lightning ({@link SwapType.TO_BTCLN}) swap
+     *
+     * @param tokenAddress Token address to pay with
+     * @param paymentRequest BOLT11 lightning network invoice to be paid (needs to have a fixed amount), and the swap
+     *  amount is taken from this fixed amount, hence only exact output swaps are supported
+     * @param additionalParams Additional parameters sent to the LP when creating the swap
+     * @param options Additional options for the swap
+     */
     createToBTCLNSwap(
         tokenAddress: string,
         paymentRequest: string,
@@ -87,6 +130,16 @@ export class SwapperWithSigner<T extends MultiChain, ChainIdentifier extends Cha
             .then(swap => wrapSwapWithSigner(swap, this.signer));
     }
 
+    /**
+     * Creates Smart chain -> Bitcoin Lightning ({@link SwapType.TO_BTCLN}) swap via LNURL-pay link
+     *
+     * @param tokenAddress Token address to pay with
+     * @param lnurlPay LNURL-pay link to use for the payment
+     * @param amount Amount to send in token based units (if `exactIn=true`) or receive in satoshis (if `exactIn=false`)
+     * @param exactIn Whether to do an exact in swap instead of exact out
+     * @param additionalParams Additional parameters sent to the LP when creating the swap
+     * @param options Additional options for the swap
+     */
     createToBTCLNSwapViaLNURL(
         tokenAddress: string,
         lnurlPay: string | LNURLPay,
@@ -99,6 +152,57 @@ export class SwapperWithSigner<T extends MultiChain, ChainIdentifier extends Cha
             .then(swap => wrapSwapWithSigner(swap, this.signer));
     }
 
+    /**
+     * Creates Smart chain -> Bitcoin Lightning ({@link SwapType.TO_BTCLN}) swap via {@link LightningInvoiceCreateService}
+     *
+     * @param tokenAddress Token address to pay with
+     * @param service Invoice create service object which facilitates the creation of fixed amount LN invoices
+     * @param amount Amount to send in token based units (if `exactIn=true`) or receive in satoshis (if `exactIn=false`)
+     * @param exactIn Whether to do an exact in swap instead of exact out
+     * @param additionalParams Additional parameters sent to the LP when creating the swap
+     * @param options Additional options for the swap
+     */
+    createToBTCLNSwapViaInvoiceCreateService(
+        tokenAddress: string,
+        service: LightningInvoiceCreateService,
+        amount: bigint,
+        exactIn?: boolean,
+        additionalParams?: Record<string, any>,
+        options?: ToBTCLNOptions
+    ): Promise<SwapWithSigner<ToBTCLNSwap<T[ChainIdentifier]>>> {
+        return this.swapper.createToBTCLNSwapViaInvoiceCreateService(this.signer.getAddress(), tokenAddress, service, amount, exactIn, additionalParams, options)
+            .then(swap => wrapSwapWithSigner(swap, this.signer));
+    }
+
+    /**
+     * Creates Bitcoin -> Smart chain ({@link SwapType.SPV_VAULT_FROM_BTC}) swap
+     *
+     * @param tokenAddress Token address to receive
+     * @param amount Amount to send in satoshis (if `exactOut=false`) or receive in token based units (if `exactOut=true`)
+     * @param exactOut Whether to use a exact out instead of exact in
+     * @param additionalParams Additional parameters sent to the LP when creating the swap
+     * @param options Additional options for the swap
+     */
+    createFromBTCSwapNew(
+        tokenAddress: string,
+        amount: bigint,
+        exactOut?: boolean,
+        additionalParams?: Record<string, any>,
+        options?: SpvFromBTCOptions
+    ): Promise<SwapWithSigner<SpvFromBTCSwap<T[ChainIdentifier]>>> {
+        return this.swapper.createFromBTCSwapNew(this.signer.getAddress(), tokenAddress, amount, exactOut, additionalParams, options)
+            .then(swap => wrapSwapWithSigner(swap, this.signer));
+    }
+
+    /**
+     * Creates LEGACY Bitcoin -> Smart chain ({@link SwapType.FROM_BTC}) swap
+     *
+     * @param tokenAddress Token address to receive
+     * @param amount Amount to send in satoshis (if `exactOut=false`) or receive in token based units (if `exactOut=true`)
+     * @param exactOut Whether to use a exact out instead of exact in
+     * @param additionalParams Additional parameters sent to the LP when creating the swap
+     * @param options Additional options for the swap
+     */
     createFromBTCSwap(
         tokenAddress: string,
         amount: bigint,
@@ -110,6 +214,15 @@ export class SwapperWithSigner<T extends MultiChain, ChainIdentifier extends Cha
             .then(swap => wrapSwapWithSigner(swap, this.signer));
     }
 
+    /**
+     * Creates LEGACY Bitcoin Lightning -> Smart chain ({@link SwapType.FROM_BTCLN}) swap
+     *
+     * @param tokenAddress Token address to receive
+     * @param amount Amount to send in satoshis (if `exactOut=false`) or receive in token based units (if `exactOut=true`)
+     * @param exactOut Whether to use a exact out instead of exact in
+     * @param additionalParams Additional parameters sent to the LP when creating the swap
+     * @param options Additional options for the swap
+     */
     createFromBTCLNSwap(
         tokenAddress: string,
         amount: bigint,
@@ -121,6 +234,16 @@ export class SwapperWithSigner<T extends MultiChain, ChainIdentifier extends Cha
             .then(swap => wrapSwapWithSigner(swap, this.signer));
     }
 
+    /**
+     * Creates LEGACY Bitcoin Lightning -> Smart chain ({@link SwapType.FROM_BTCLN}) swap, withdrawing from
+     *  an LNURL-withdraw link
+     *
+     * @param tokenAddress Token address to receive
+     * @param lnurl LNURL-withdraw link to pull the funds from
+     * @param amount Amount to send in satoshis (if `exactOut=false`) or receive in token based units (if `exactOut=true`)
+     * @param exactOut Whether to use a exact out instead of exact in
+     * @param additionalParams Additional parameters sent to the LP when creating the swap
+     */
     createFromBTCLNSwapViaLNURL(
         tokenAddress: string,
         lnurl: string | LNURLWithdraw,
@@ -132,6 +255,15 @@ export class SwapperWithSigner<T extends MultiChain, ChainIdentifier extends Cha
             .then(swap => wrapSwapWithSigner(swap, this.signer));
     }
 
+    /**
+     * Creates Bitcoin Lightning -> Smart chain ({@link SwapType.FROM_BTCLN_AUTO}) swap
+     *
+     * @param tokenAddress Token address to receive
+     * @param amount Amount to send in satoshis (if `exactOut=false`) or receive in token based units (if `exactOut=true`)
+     * @param exactOut Whether to use a exact out instead of exact in
+     * @param additionalParams Additional parameters sent to the LP when creating the swap
+     * @param options Additional options for the swap
+     */
     createFromBTCLNSwapNew(
         tokenAddress: string,
         amount: bigint,
@@ -143,6 +275,17 @@ export class SwapperWithSigner<T extends MultiChain, ChainIdentifier extends Cha
             .then(swap => wrapSwapWithSigner(swap, this.signer));
     }
 
+    /**
+     * Creates Bitcoin Lightning -> Smart chain ({@link SwapType.FROM_BTCLN_AUTO}) swap, withdrawing from
+     *  an LNURL-withdraw link
+     *
+     * @param tokenAddress Token address to receive
+     * @param lnurl LNURL-withdraw link to pull the funds from
+     * @param amount Amount to send in satoshis (if `exactOut=false`) or receive in token based units (if `exactOut=true`)
+     * @param exactOut Whether to use a exact out instead of exact in
+     * @param additionalParams Additional parameters sent to the LP when creating the swap
+     * @param options Additional options for the swap
+     */
     createFromBTCLNSwapNewViaLNURL(
         tokenAddress: string,
         lnurl: string | LNURLWithdraw,
@@ -155,19 +298,58 @@ export class SwapperWithSigner<T extends MultiChain, ChainIdentifier extends Cha
             .then(swap => wrapSwapWithSigner(swap, this.signer));
     }
 
-    createTrustedLNForGasSwap(amount: bigint, trustedIntermediaryUrl?: string): Promise<LnForGasSwap<T[ChainIdentifier]>> {
-        return this.swapper.createTrustedLNForGasSwap(this.signer.getAddress(), amount, trustedIntermediaryUrl);
+    /**
+     * Creates a trusted Bitcoin Lightning -> Smart chain ({@link SwapType.TRUSTED_FROM_BTCLN}) gas swap
+     *
+     * @param amount Amount of native token to receive, in base units
+     * @param trustedIntermediaryOrUrl  URL or Intermediary object of the trusted intermediary to use, otherwise uses default
+     * @throws {Error} If no trusted intermediary specified
+     */
+    createTrustedLNForGasSwap(amount: bigint, trustedIntermediaryOrUrl?: Intermediary | string): Promise<LnForGasSwap<T[ChainIdentifier]>> {
+        return this.swapper.createTrustedLNForGasSwap(this.signer.getAddress(), amount, trustedIntermediaryOrUrl);
     }
 
-    createTrustedOnchainForGasSwap(amount: bigint, refundAddress?: string, trustedIntermediaryUrl?: string): Promise<OnchainForGasSwap<T[ChainIdentifier]>> {
-        return this.swapper.createTrustedOnchainForGasSwap(this.signer.getAddress(), amount, refundAddress, trustedIntermediaryUrl);
+    /**
+     * Creates a trusted Bitcoin -> Smart chain ({@link SwapType.TRUSTED_FROM_BTC}) gas swap
+     *
+     * @param amount Amount of native token to receive, in base units
+     * @param refundAddress Bitcoin refund address, in case the swap fails the funds are refunded here
+     * @param trustedIntermediaryOrUrl URL or Intermediary object of the trusted intermediary to use, otherwise uses default
+     * @throws {Error} If no trusted intermediary specified
+     */
+    createTrustedOnchainForGasSwap(amount: bigint, refundAddress?: string, trustedIntermediaryOrUrl?: Intermediary | string): Promise<OnchainForGasSwap<T[ChainIdentifier]>> {
+        return this.swapper.createTrustedOnchainForGasSwap(this.signer.getAddress(), amount, refundAddress, trustedIntermediaryOrUrl);
     }
 
+    /**
+     * @internal
+     */
     create(srcToken: BtcToken<true>, dstToken: SCToken<ChainIdentifier>, amount: bigint, exactIn: boolean, lnurlWithdraw?: string | LNURLWithdraw): Promise<(SupportsSwapType<T[ChainIdentifier], SwapType.FROM_BTCLN_AUTO> extends true ? FromBTCLNAutoSwap<T[ChainIdentifier]> : FromBTCLNSwap<T[ChainIdentifier]>)>;
+    /**
+     * @internal
+     */
     create(srcToken: BtcToken<false>, dstToken: SCToken<ChainIdentifier>, amount: bigint, exactIn: boolean): Promise<(SupportsSwapType<T[ChainIdentifier], SwapType.SPV_VAULT_FROM_BTC> extends true ? SpvFromBTCSwap<T[ChainIdentifier]> : FromBTCSwap<T[ChainIdentifier]>)>;
+    /**
+     * @internal
+     */
     create(srcToken: SCToken<ChainIdentifier>, dstToken: BtcToken<false>, amount: bigint, exactIn: boolean, address: string): Promise<ToBTCSwap<T[ChainIdentifier]>>;
+    /**
+     * @internal
+     */
     create(srcToken: SCToken<ChainIdentifier>, dstToken: BtcToken<true>, amount: bigint, exactIn: boolean, lnurlPay: string | LNURLPay): Promise<ToBTCLNSwap<T[ChainIdentifier]>>;
-    create(srcToken: SCToken<ChainIdentifier>, dstToken: BtcToken<true>, amount: undefined, exactIn: false, lightningInvoice: string): Promise<ToBTCLNSwap<T[ChainIdentifier]>>;
+    /**
+     * Creates a swap from srcToken to dstToken, of a specific token amount, either specifying input amount (exactIn=true)
+     *  or output amount (exactIn=false), NOTE: For regular -> BTC-LN (lightning) swaps the passed amount is ignored and
+     *  invoice's pre-set amount is used instead.
+     *
+     * @param srcToken Source token of the swap, user pays this token
+     * @param dstToken Destination token of the swap, user receives this token
+     * @param amount Amount of the swap
+     * @param exactIn Whether the amount specified is an input amount (exactIn=true) or an output amount (exactIn=false)
+     * @param addressLnurlLightningInvoice Bitcoin on-chain address, lightning invoice, LNURL-pay to pay or
+     *  LNURL-withdrawal to withdraw money from
+     */
+    create(srcToken: SCToken<ChainIdentifier>, dstToken: BtcToken<true>, amount: undefined, exactIn: false, addressLnurlLightningInvoice: string): Promise<ToBTCLNSwap<T[ChainIdentifier]>>;
     /**
      * Creates a swap from srcToken to dstToken, of a specific token amount, either specifying input amount (exactIn=true)
      *  or output amount (exactIn=false), NOTE: For regular -> BTC-LN (lightning) swaps the passed amount is ignored and
@@ -213,6 +395,16 @@ export class SwapperWithSigner<T extends MultiChain, ChainIdentifier extends Cha
         return this.swapper.getSwapById(id, this.signer.getAddress());
     }
 
+    /**
+     * Returns the swap with a proper return type, or `undefined` if not found or has wrong type
+     *
+     * @param id An ID of the swap ({@link ISwap.getId})
+     * @param swapType Type of the swap
+     */
+    async getTypedSwapById<S extends SwapType>(id: string, swapType: S): Promise<SwapTypeMapping<T[ChainIdentifier]>[S] | undefined> {
+        return this.swapper.getTypedSwapById<S>(id, swapType, this.signer.getAddress());
+    }
+
     /**
      * Synchronizes swaps from chain, this is usually ran when SDK is initialized, deletes expired quotes
      */
@@ -220,6 +412,37 @@ export class SwapperWithSigner<T extends MultiChain, ChainIdentifier extends Cha
         return this.swapper._syncSwaps(this.signer.getAddress());
     }
 
+    /**
+     * Recovers swaps from on-chain historical data.
+     *
+     * Please note that the recovered swaps might not be complete (i.e. missing amounts or addresses), as some
+     *  of the swap data is purely off-chain and can never be recovered purely from on-chain data. This
+     *  functions tries to recover as much swap data as possible.
+     *
+     * @param startBlockheight Optional starting blockheight for swap data recovery, will only check swaps
+     *  initiated after this blockheight
+     */
+    async recoverSwaps(startBlockheight?: number): Promise<ISwap<T[ChainIdentifier]>[]> {
+        return this.swapper.recoverSwaps(this.signer.getAddress(), startBlockheight);
+    }
+
+    /**
+     * Returns the {@link Token} object for a given token
+     *
+     * @param tickerOrAddress Token to return the object for, can use multiple formats:
+     *  - a) token ticker, such as `"BTC"`, `"SOL"`, etc.
+     *  - b) token ticker prefixed with smart chain identifier, such as `"SOLANA-SOL"`, `"SOLANA-USDC"`, etc.
+     *  - c) token address
+     */
+    getToken(tickerOrAddress: string): Token<ChainIdentifier> {
+        return this.swapper.getToken(tickerOrAddress);
+    }
+
+    /**
+     * Returns whether the SDK supports a given swap type on this chain based on currently known LPs
+     *
+     * @param swapType Swap protocol type
+     */
     supportsSwapType<
         Type extends SwapType
     >(swapType: Type): SupportsSwapType<T[ChainIdentifier], Type> {
@@ -227,16 +450,34 @@ export class SwapperWithSigner<T extends MultiChain, ChainIdentifier extends Cha
     }
 
     /**
-     * Returns type of the swap based on input and output tokens specified
-     *
-     * @param srcToken
-     * @param dstToken
+     * @internal
      */
     getSwapType(srcToken: BtcToken<true>, dstToken: SCToken<ChainIdentifier>): (SupportsSwapType<T[ChainIdentifier], SwapType.FROM_BTCLN_AUTO> extends true ? SwapType.FROM_BTCLN_AUTO : SwapType.FROM_BTCLN);
+    /**
+     * @internal
+     */
     getSwapType(srcToken: BtcToken<false>, dstToken: SCToken<ChainIdentifier>): (SupportsSwapType<T[ChainIdentifier], SwapType.SPV_VAULT_FROM_BTC> extends true ? SwapType.SPV_VAULT_FROM_BTC : SwapType.FROM_BTC);
+    /**
+     * @internal
+     */
     getSwapType(srcToken: SCToken<ChainIdentifier>, dstToken: BtcToken<false>): SwapType.TO_BTC;
+    /**
+     * @internal
+     */
     getSwapType(srcToken: SCToken<ChainIdentifier>, dstToken: BtcToken<true>): SwapType.TO_BTCLN;
+    /**
+     * Returns type of the swap based on input and output tokens specified
+     *
+     * @param srcToken Source token
+     * @param dstToken Destination token
+     */
     getSwapType(srcToken: Token<ChainIdentifier>, dstToken: Token<ChainIdentifier>): SwapType.FROM_BTCLN_AUTO | SwapType.FROM_BTCLN | SwapType.SPV_VAULT_FROM_BTC | SwapType.FROM_BTC | SwapType.TO_BTC | SwapType.TO_BTCLN;
+    /**
+     * Returns type of the swap based on input and output tokens specified
+     *
+     * @param srcToken Source token
+     * @param dstToken Destination token
+     */
     getSwapType(srcToken: Token<ChainIdentifier>, dstToken: Token<ChainIdentifier>): SwapType.FROM_BTCLN_AUTO | SwapType.FROM_BTCLN | SwapType.SPV_VAULT_FROM_BTC | SwapType.FROM_BTC | SwapType.TO_BTC | SwapType.TO_BTCLN {
         return this.swapper.getSwapType(srcToken, dstToken);
     }
@@ -244,8 +485,8 @@ export class SwapperWithSigner<T extends MultiChain, ChainIdentifier extends Cha
     /**
      * Returns minimum/maximum limits for inputs and outputs for a swap between given tokens
      *
-     * @param srcToken
-     * @param dstToken
+     * @param srcToken Source token
+     * @param dstToken Destination token
      */
     getSwapLimits<A extends Token<ChainIdentifier>, B extends Token<ChainIdentifier>>(srcToken: A, dstToken: B): {
         input: {min: TokenAmount<string, A>, max?: TokenAmount<string, A>},
@@ -262,38 +503,4 @@ export class SwapperWithSigner<T extends MultiChain, ChainIdentifier extends Cha
         return this.swapper.getSwapCounterTokens(token, input);
     }
 
-
-    ///////////////////////////////////
-    /// Deprecated
-
-    /**
-     * Returns swap bounds (minimums & maximums) for different swap types & tokens
-     * @deprecated Use getSwapLimits() instead!
-     */
-    getSwapBounds(): SwapBounds {
-        return this.swapper.getSwapBounds();
-    }
-
-    /**
-     * Returns maximum possible swap amount
-     * @deprecated Use getSwapLimits() instead!
-     *
-     * @param type      Type of the swap
-     * @param token     Token of the swap
-     */
-    getMaximum(type: SwapType, token: string): bigint {
-        return this.swapper.getMaximum(type, token);
-    }
-
-    /**
-     * Returns minimum possible swap amount
-     * @deprecated Use getSwapLimits() instead!
-     *
-     * @param type      Type of swap
-     * @param token     Token of the swap
-     */
-    getMinimum(type: SwapType, token: string): bigint {
-        return this.swapper.getMinimum(type, token);
-    }
-
 }

package/src/swaps/IAddressSwap.ts

@@ -1,6 +1,7 @@
 /**
- * Type guard to check if an object is an IAddressSwap
- * @category Swaps
+ * Type guard to check if an object is an {@link IAddressSwap}
+ *
+ * @category Swaps/Types
  */
 export function isIAddressSwap(obj: any): obj is IAddressSwap {
     return obj!=null &&
@@ -10,11 +11,20 @@ export function isIAddressSwap(obj: any): obj is IAddressSwap {
 
 /**
  * Interface for swaps which require a user to send funds to a specific address
- * @category Swaps
+ *
+ * @category Swaps/Types
  */
 export interface IAddressSwap {
 
+    /**
+     * An address to which the user needs to send funds on the source chain
+     */
     getAddress(): string;
+
+    /**
+     * A hyperlink representation of the address + amount that the user needs to sends on the source chain.
+     *  This is suitable to be displayed in a form of QR code.
+     */
     getHyperlink(): string;
 
 }

package/src/swaps/IBTCWalletSwap.ts

@@ -8,8 +8,9 @@ import {TokenAmount} from "../types/TokenAmount";
 import {BtcToken} from "../types/Token";
 
 /**
- * Type guard to check if an object is an IBTCWalletSwap
- * @category Swaps
+ * Type guard to check if an object is an {@link IBTCWalletSwap}
+ *
+ * @category Swaps/Types
  */
 export function isIBTCWalletSwap(obj: any): obj is IBTCWalletSwap {
     return obj!=null &&
@@ -23,17 +24,18 @@ export function isIBTCWalletSwap(obj: any): obj is IBTCWalletSwap {
 
 /**
  * Interface for swaps requiring Bitcoin wallet interaction
- * @category Swaps
+ *
+ * @category Swaps/Types
  */
 export interface IBTCWalletSwap {
 
     /**
      * Returns the PSBT that is already funded with wallet's UTXOs (runs a coin-selection algorithm to choose UTXOs to use),
      *  also returns inputs indices that need to be signed by the wallet before submitting the PSBT back to the SDK with
-     *  `swap.submitPsbt()`
+     *  {@link submitPsbt}
      *
      * @param _bitcoinWallet Sender's bitcoin wallet
-     * @param feeRate Optional fee rate for the transaction, needs to be at least as big as {minimumBtcFeeRate} field
+     * @param feeRate Optional fee rate in sats/vB for the transaction
      * @param additionalOutputs additional outputs to add to the PSBT - can be used to collect fees from users
      */
     getFundedPsbt(
@@ -45,26 +47,36 @@ export interface IBTCWalletSwap {
     /**
      * Submits a PSBT signed by the wallet back to the SDK
      *
-     * @param psbt A psbt - either a Transaction object or a hex or base64 encoded PSBT string
+     * @param psbt A PSBT, either a Transaction object or a hex or base64 encoded PSBT string
      */
     submitPsbt(psbt: Transaction | string): Promise<string>;
 
-
+    /**
+     * Estimates a bitcoin on-chain fee paid for the bitcoin swap transaction
+     *
+     * @param wallet Sender's bitcoin wallet
+     * @param feeRate Optional fee rate in sats/vB for the transaction
+     */
     estimateBitcoinFee(wallet: IBitcoinWallet | MinimalBitcoinWalletInterface, feeRate?: number): Promise<TokenAmount<any, BtcToken<false>> | null>;
 
-
+    /**
+     * Sends a swap bitcoin transaction via the passed bitcoin wallet
+     *
+     * @param wallet Sender's bitcoin wallet
+     * @param feeRate Optional fee rate in sats/vB for the transaction
+     */
     sendBitcoinTransaction(
         wallet: IBitcoinWallet | MinimalBitcoinWalletInterfaceWithSigner,
         feeRate?: number
     ): Promise<string>;
 
     /**
-     * Waits till the bitcoin transaction confirms
+     * Waits till the bitcoin transaction gets the required number of confirmations
      *
      * @param updateCallback Callback called when txId is found, and also called with subsequent confirmations
      * @param checkIntervalSeconds How often to check the bitcoin transaction
      * @param abortSignal Abort signal
-     * @throws {Error} if in invalid state (must be CLAIM_COMMITED)
+     * @throws {Error} if in invalid state
      */
     waitForBitcoinTransaction(
         updateCallback?: (txId?: string, confirmations?: number, targetConfirmations?: number, txEtaMs?: number) => void,
@@ -72,6 +84,10 @@ export interface IBTCWalletSwap {
         abortSignal?: AbortSignal,
     ): Promise<string>;
 
+    /**
+     * Returns the number of confirmations required for the bitcoin transaction for this swap
+     *  to complete and settle
+     */
     getRequiredConfirmationsCount(): number;
 
 }

package/src/swaps/IClaimableSwap.ts

@@ -3,8 +3,9 @@ import {ISwap} from "./ISwap";
 import {ISwapWrapper, SwapTypeDefinition} from "./ISwapWrapper";
 
 /**
- * Type guard to check if an object is an IClaimableSwap
- * @category Swaps
+ * Type guard to check if an object is an {@link IClaimableSwap}
+ *
+ * @category Swaps/Types
  */
 export function isIClaimableSwap(obj: any): obj is IClaimableSwap {
     return obj!=null &&
@@ -14,8 +15,10 @@ export function isIClaimableSwap(obj: any): obj is IClaimableSwap {
 }
 
 /**
- * Interface for swaps that can be claimed
- * @category Swaps
+ * Interface for swaps that can end up in a claimable state, requiring the user to claim the
+ *  assets on the destination chain.
+ *
+ * @category Swaps/Types
  */
 export interface IClaimableSwap<
     T extends ChainType = ChainType,
@@ -23,8 +26,40 @@ export interface IClaimableSwap<
     S extends number = number
 > extends ISwap<T, D, S> {
 
+    /**
+     * Checks whether a swap currently requires a manual claiming (settlement)
+     */
     isClaimable(): boolean;
-    txsClaim(_signer?: T["Signer"] | T["NativeSigner"]): Promise<T["TX"][]>;
-    claim(_signer?: T["Signer"] | T["NativeSigner"], abortSignal?: AbortSignal): Promise<string>;
+
+    /**
+     * Returns transactions for settling (claiming) the swap if the swap requires manual settlement, you can check
+     *  so with {@link isClaimable}. After sending the transaction manually be sure to call the {@link waitTillClaimed}
+     *  function to wait till the claim transaction is observed, processed by the SDK and state of the swap
+     *  properly updated.
+     *
+     * @param _signer Address of the signer to create the settlement (claim) transactions for
+     */
+    txsClaim(_signer?: string | T["Signer"] | T["NativeSigner"]): Promise<T["TX"][]>;
+
+    /**
+     * Settles the swap by claiming the funds on the destination chain if the swap requires manual settlement,
+     *  you can check so with {@link isClaimable}
+     *
+     * @param _signer Signer to use for signing the settlement transactions
+     * @param abortSignal Abort signal
+     * @param onBeforeTxSent Optional callback triggered before the claim transaction is broadcasted
+     */
+    claim(_signer?: T["Signer"] | T["NativeSigner"], abortSignal?: AbortSignal, onBeforeTxSent?: (txId: string) => void): Promise<string>;
+
+    /**
+     * Waits till the swap is successfully settled (claimed), should be called after sending the claim (settlement)
+     *  transactions manually to wait till the SDK processes the settlement and updates the swap state accordingly
+     *
+     * @param maxWaitTimeSeconds Maximum time in seconds to wait for the swap to be settled
+     * @param abortSignal AbortSignal
+     *
+     * @returns {boolean} whether the swap was claimed in time or not
+     */
+    waitTillClaimed(maxWaitTimeSeconds?: number, abortSignal?: AbortSignal): Promise<boolean>;
 
 }

package/src/swaps/IClaimableSwapWrapper.ts

@@ -1,9 +1,18 @@
 import {ISwap} from "./ISwap";
 import {IClaimableSwap} from "./IClaimableSwap";
 
-
+/**
+ * Interface for a swap wrapper for swaps that can end up in a claimable state, requiring the user to claim the
+ *  assets on the destination chain.
+ *
+ * @category Swaps/Abstract
+ */
 export interface IClaimableSwapWrapper<T extends ISwap & IClaimableSwap = ISwap & IClaimableSwap> {
 
-    claimableSwapStates: T["state"][];
+    /**
+     * A list of swap states when the swap is potentially claimable
+     * @internal
+     */
+    _claimableSwapStates: T["_state"][];
 
 }