@atomiqlabs/sdk 8.1.8 → 8.3.5

package/dist/swaps/escrow_swaps/frombtc/ln_auto/FromBTCLNAutoSwap.d.ts

@@ -18,7 +18,7 @@ import { LNURLWithdraw } from "../../../../types/lnurl/LNURLWithdraw";
 import { PriceInfoType } from "../../../../types/PriceInfoType";
 /**
  * State enum for FromBTCLNAuto swaps
- * @category Swaps
+ * @category Swaps/Lightning → Smart chain
  */
 export declare enum FromBTCLNAutoSwapState {
     FAILED = -4,
@@ -31,11 +31,11 @@ export declare enum FromBTCLNAutoSwapState {
     CLAIM_CLAIMED = 3
 }
 export type FromBTCLNAutoSwapInit<T extends SwapData> = IEscrowSwapInit<T> & {
-    pr: string;
-    secret: string;
+    pr?: string;
+    secret?: string;
     initialSwapData: T;
-    btcAmountSwap: bigint;
-    btcAmountGas: bigint;
+    btcAmountSwap?: bigint;
+    btcAmountGas?: bigint;
     gasSwapFeeBtc: bigint;
     gasSwapFee: bigint;
     gasPricingInfo?: PriceInfoType;
@@ -44,47 +44,125 @@ export type FromBTCLNAutoSwapInit<T extends SwapData> = IEscrowSwapInit<T> & {
     lnurlCallback?: string;
 };
 export declare function isFromBTCLNAutoSwapInit<T extends SwapData>(obj: any): obj is FromBTCLNAutoSwapInit<T>;
+/**
+ * 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. Permissionless watchtower network
+ *  handles 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).
+ *
+ * @category Swaps/Lightning → Smart chain
+ */
 export declare class FromBTCLNAutoSwap<T extends ChainType = ChainType> extends IEscrowSwap<T, FromBTCLNAutoDefinition<T>> implements IAddressSwap, ISwapWithGasDrop<T>, IClaimableSwap<T, FromBTCLNAutoDefinition<T>, FromBTCLNAutoSwapState> {
+    protected readonly TYPE: SwapType.FROM_BTCLN_AUTO;
+    /**
+     * @internal
+     */
     protected readonly logger: LoggerType;
+    /**
+     * @internal
+     */
     protected readonly inputToken: BtcToken<true>;
-    protected readonly TYPE = SwapType.FROM_BTCLN_AUTO;
-    protected readonly lnurlFailSignal: AbortController;
-    protected readonly pr: string;
-    protected readonly secret: string;
-    protected initialSwapData: T["Data"];
-    protected readonly btcAmountSwap: bigint;
-    protected readonly btcAmountGas: bigint;
-    protected readonly gasSwapFeeBtc: bigint;
-    protected readonly gasSwapFee: bigint;
-    gasPricingInfo?: PriceInfoType;
-    lnurl?: string;
-    lnurlK1?: string;
-    lnurlCallback?: string;
-    prPosted?: boolean;
-    protected getSwapData(): T["Data"];
+    private readonly lnurlFailSignal;
+    private readonly usesClaimHashAsId;
+    private readonly initialSwapData;
+    private readonly btcAmountSwap?;
+    private readonly btcAmountGas?;
+    private readonly gasSwapFeeBtc;
+    private readonly gasSwapFee;
+    private readonly gasPricingInfo?;
+    /**
+     * In case the swap is recovered from on-chain data, the pr saved here is just a payment hash,
+     *  as it is impossible to retrieve the actual lightning network invoice paid purely from on-chain
+     *  data
+     * @private
+     */
+    private pr?;
+    private secret?;
+    private lnurl?;
+    private lnurlK1?;
+    private lnurlCallback?;
+    private prPosted?;
+    private broadcastTickCounter;
+    /**
+     * Sets the LNURL data for the swap
+     *
+     * @internal
+     */
+    _setLNURLData(lnurl: string, lnurlK1: string, lnurlCallback: string): void;
     constructor(wrapper: FromBTCLNAutoWrapper<T>, init: FromBTCLNAutoSwapInit<T["Data"]>);
     constructor(wrapper: FromBTCLNAutoWrapper<T>, obj: any);
+    /**
+     * @inheritDoc
+     * @internal
+     */
+    protected getSwapData(): T["Data"];
+    /**
+     * @inheritDoc
+     * @internal
+     */
     protected upgradeVersion(): void;
     /**
-     * In case swapFee in BTC is not supplied it recalculates it based on swap price
-     * @protected
+     * @inheritDoc
+     * @internal
      */
     protected tryRecomputeSwapPrice(): void;
+    /**
+     * @inheritDoc
+     */
     refreshPriceData(): Promise<void>;
+    /**
+     * @inheritDoc
+     * @internal
+     */
     _getEscrowHash(): string | null;
+    /**
+     * @inheritDoc
+     * @internal
+     */
     _getInitiator(): string;
+    /**
+     * @inheritDoc
+     */
     getId(): string;
+    /**
+     * @inheritDoc
+     */
     getOutputAddress(): string | null;
+    /**
+     * @inheritDoc
+     */
     getOutputTxId(): string | null;
+    /**
+     * @inheritDoc
+     */
     requiresAction(): boolean;
+    /**
+     * @inheritDoc
+     * @internal
+     */
     protected getIdentifierHashString(): string;
-    protected getPaymentHash(): Buffer;
+    /**
+     * Returns the payment hash of the swap and lightning network invoice, or `null` if not known (i.e. if
+     *  the swap was recovered from on-chain data, the payment hash might not be known)
+     *
+     * @internal
+     */
+    protected getPaymentHash(): Buffer | null;
+    /**
+     * @inheritDoc
+     */
     getInputAddress(): string | null;
-    getInputTxId(): string;
+    /**
+     * @inheritDoc
+     */
+    getInputTxId(): string | null;
     /**
      * Returns the lightning network BOLT11 invoice that needs to be paid as an input to the swap
      */
     getAddress(): string;
+    /**
+     * @inheritDoc
+     */
     getHyperlink(): string;
     /**
      * Returns the timeout time (in UNIX milliseconds) when the swap will definitelly be considered as expired
@@ -95,29 +173,123 @@ export declare class FromBTCLNAutoSwap<T extends ChainType = ChainType> extends
      * Returns timeout time (in UNIX milliseconds) when the swap htlc will expire
      */
     getHtlcTimeoutTime(): number | null;
+    /**
+     * @inheritDoc
+     */
     isFinished(): boolean;
+    /**
+     * @inheritDoc
+     */
     isClaimable(): boolean;
+    /**
+     * @inheritDoc
+     */
     isSuccessful(): boolean;
+    /**
+     * @inheritDoc
+     */
     isFailed(): boolean;
+    /**
+     * @inheritDoc
+     */
     isQuoteExpired(): boolean;
+    /**
+     * @inheritDoc
+     */
     isQuoteSoftExpired(): boolean;
+    /**
+     * @inheritDoc
+     */
     _verifyQuoteDefinitelyExpired(): Promise<boolean>;
-    verifyQuoteValid(): Promise<boolean>;
-    protected getLightningInvoiceSats(): bigint;
-    protected getWatchtowerFeeAmountBtc(): bigint;
-    protected getInputSwapAmountWithoutFee(): bigint;
-    protected getInputGasAmountWithoutFee(): bigint;
-    protected getInputAmountWithoutFee(): bigint;
+    /**
+     * @inheritDoc
+     */
+    _verifyQuoteValid(): Promise<boolean>;
+    /**
+     * Returns the satoshi amount of the lightning network invoice, or `null` if the lightning network
+     *  invoice is not known (i.e. when the swap was recovered from on-chain data, the paid invoice
+     *  cannot be recovered because it is purely off-chain)
+     *
+     * @internal
+     */
+    protected getLightningInvoiceSats(): bigint | null;
+    /**
+     * Returns the watchtower fee paid in BTC satoshis, or null if known (i.e. if the swap was recovered from
+     *  on-chain data)
+     *
+     * @protected
+     */
+    protected getWatchtowerFeeAmountBtc(): bigint | null;
+    /**
+     * Returns the input amount for the actual swap (excluding the input amount used to cover the "gas drop"
+     *  part of the swap), excluding fees
+     *
+     * @internal
+     */
+    protected getInputSwapAmountWithoutFee(): bigint | null;
+    /**
+     * Returns the input amount purely for the "gas drop" part of the swap (this much BTC in sats will be
+     *  swapped into the native gas token on the destination chain), excluding fees
+     *
+     * @internal
+     */
+    protected getInputGasAmountWithoutFee(): bigint | null;
+    /**
+     * Get total btc amount in sats on the input, excluding the swap fee and watchtower fee
+     *
+     * @internal
+     */
+    protected getInputAmountWithoutFee(): bigint | null;
+    /**
+     * Returns the "would be" output amount if the swap charged no swap fee
+     *
+     * @internal
+     */
     protected getOutputAmountWithoutFee(): bigint;
+    /**
+     * @inheritDoc
+     */
     getInputToken(): BtcToken<true>;
+    /**
+     * @inheritDoc
+     */
     getInput(): TokenAmount<T["ChainId"], BtcToken<true>>;
+    /**
+     * @inheritDoc
+     */
     getInputWithoutFee(): TokenAmount<T["ChainId"], BtcToken<true>>;
+    /**
+     * @inheritDoc
+     */
     getOutputToken(): SCToken<T["ChainId"]>;
+    /**
+     * @inheritDoc
+     */
     getOutput(): TokenAmount<T["ChainId"], SCToken<T["ChainId"]>, true>;
+    /**
+     * @inheritDoc
+     */
     getGasDropOutput(): TokenAmount<T["ChainId"], SCToken<T["ChainId"]>, true>;
+    /**
+     * Returns the swap fee charged by the intermediary (LP) on this swap
+     *
+     * @internal
+     */
     protected getSwapFee(): Fee<T["ChainId"], BtcToken<true>, SCToken<T["ChainId"]>>;
+    /**
+     * Returns the fee to be paid to watchtowers on the destination chain to automatically
+     *  process and settle this swap without requiring any user interaction
+     *
+     * @internal
+     */
     protected getWatchtowerFee(): Fee<T["ChainId"], BtcToken<true>, SCToken<T["ChainId"]>>;
+    /**
+     * @inheritDoc
+     */
     getFee(): Fee<T["ChainId"], BtcToken<true>, SCToken<T["ChainId"]>>;
+    /**
+     * @inheritDoc
+     */
     getFeeBreakdown(): [
         {
             type: FeeType.SWAP;
@@ -128,6 +300,7 @@ export declare class FromBTCLNAutoSwap<T extends ChainType = ChainType> extends
             fee: Fee<T["ChainId"], BtcToken<true>, SCToken<T["ChainId"]>>;
         }
     ];
+    private isValidSecretPreimage;
     /**
      * Executes the swap with the provided bitcoin lightning network wallet or LNURL
      *
@@ -135,6 +308,8 @@ export declare class FromBTCLNAutoSwap<T extends ChainType = ChainType> extends
      *  link, wallet is not required and the LN invoice can be paid externally as well (just pass null or undefined here)
      * @param callbacks Callbacks to track the progress of the swap
      * @param options Optional options for the swap like feeRate, AbortSignal, and timeouts/intervals
+     * @param secret A swap secret to broadcast to watchtowers, generally only needed if the swap
+     *  was recovered from on-chain data, or the pre-image was generated outside the SDK
      *
      * @returns {boolean} Whether a swap was settled automatically by swap watchtowers or requires manual claim by the
      *  user, in case `false` is returned the user should call `swap.claim()` to settle the swap on the destination manually
@@ -146,78 +321,126 @@ export declare class FromBTCLNAutoSwap<T extends ChainType = ChainType> extends
         abortSignal?: AbortSignal;
         lightningTxCheckIntervalSeconds?: number;
         maxWaitTillAutomaticSettlementSeconds?: number;
-    }): Promise<boolean>;
+    }, secret?: string): Promise<boolean>;
+    /**
+     * @inheritDoc
+     */
     txsExecute(): Promise<{
         name: "Payment";
         description: string;
-        chain: string;
+        chain: "LIGHTNING";
         txs: {
+            type: "BOLT11_PAYMENT_REQUEST";
             address: string;
             hyperlink: string;
         }[];
     }[]>;
     /**
-     * Checks whether the LP received the LN payment and we can continue by committing & claiming the HTLC on-chain
+     * Checks whether the LP received the LN payment
      *
      * @param save If the new swap state should be saved
+     *
+     * @internal
      */
     _checkIntermediaryPaymentReceived(save?: boolean): Promise<boolean | null>;
+    /**
+     * Checks and overrides the swap data for this swap. This is used to set the swap data from
+     *  on-chain events.
+     *
+     * @param data Swap data of the escrow swap
+     * @param save If the new data should be saved
+     *
+     * @internal
+     */
     _saveRealSwapData(data: T["Data"], save?: boolean): Promise<boolean>;
     /**
      * Checks the data returned by the intermediary in the payment auth request
      *
      * @param data Parsed swap data as returned by the intermediary
-     * @protected
+     *
      * @throws {IntermediaryError} If the returned are not valid
      * @throws {Error} If the swap is already committed on-chain
+     *
+     * @private
      */
-    protected checkIntermediaryReturnedData(data: T["Data"]): Promise<void>;
+    private checkIntermediaryReturnedData;
     /**
-     * Waits till an LN payment is received by the intermediary and client can continue commiting & claiming the HTLC
+     * Waits till a lightning network payment is received by the intermediary, and the intermediary
+     *  initiates the swap HTLC on the smart chain side. After the HTLC is initiated you can wait
+     *  for an automatic settlement by the watchtowers with the {@link waitTillClaimed} function,
+     *  or settle manually using the {@link claim} or {@link txsClaim} functions.
+     *
+     * If this swap is using an LNURL-withdraw link as input, it automatically posts the
+     *  generated invoice to the LNURL service to pay it.
      *
      * @param onPaymentReceived Callback as for when the LP reports having received the ln payment
-     * @param checkIntervalSeconds How often to poll the intermediary for answer (default 5 seconds)
      * @param abortSignal Abort signal to stop waiting for payment
+     * @param checkIntervalSeconds How often to poll the intermediary for answer (default 5 seconds)
      */
     waitForPayment(onPaymentReceived?: (txId: string) => void, checkIntervalSeconds?: number, abortSignal?: AbortSignal): Promise<boolean>;
+    /**
+     * Waits till the intermediary (LP) initiates the swap HTLC escrow on the destination smart chain side
+     *
+     * @param checkIntervalSeconds How often to check via a polling watchdog
+     * @param abortSignal Abort signal
+     *
+     * @internal
+     */
     protected waitTillCommited(checkIntervalSeconds?: number, abortSignal?: AbortSignal): Promise<void>;
     /**
-     * Returns transactions required for claiming the HTLC and finishing the swap by revealing the HTLC secret
-     *  (hash preimage)
+     * @inheritDoc
      *
      * @param _signer Optional signer address to use for claiming the swap, can also be different from the initializer
-     * @throws {Error} If in invalid state (must be CLAIM_COMMITED)
+     * @param secret A swap secret to use for the claim transaction, generally only needed if the swap
+     *  was recovered from on-chain data, or the pre-image was generated outside the SDK
+     *
+     * @throws {Error} If in invalid state (must be {@link FromBTCLNAutoSwapState.CLAIM_COMMITED})
      */
-    txsClaim(_signer?: T["Signer"] | T["NativeSigner"]): Promise<T["TX"][]>;
+    txsClaim(_signer?: T["Signer"] | T["NativeSigner"], secret?: string): Promise<T["TX"][]>;
     /**
-     * Claims and finishes the swap
+     * @inheritDoc
      *
      * @param _signer Signer to sign the transactions with, can also be different to the initializer
      * @param abortSignal Abort signal to stop waiting for transaction confirmation
+     * @param onBeforeTxSent
+     * @param secret A swap secret to use for the claim transaction, generally only needed if the swap
+     *  was recovered from on-chain data, or the pre-image was generated outside the SDK
      */
-    claim(_signer: T["Signer"] | T["NativeSigner"], abortSignal?: AbortSignal): Promise<string>;
+    claim(_signer: T["Signer"] | T["NativeSigner"], abortSignal?: AbortSignal, onBeforeTxSent?: (txId: string) => void, secret?: string): Promise<string>;
     /**
-     * Waits till the swap is successfully claimed
+     * 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
-     * @throws {Error} If swap is in invalid state (must be BTC_TX_CONFIRMED)
+     * @param secret A swap secret to broadcast to watchtowers, generally only needed if the swap
+     *  was recovered from on-chain data, or the pre-image was generated outside the SDK
+     *
+     * @throws {Error} If swap is in invalid state (must be {@link FromBTCLNAutoSwapState.CLAIM_COMMITED})
      * @throws {Error} If the LP refunded sooner than we were able to claim
      * @returns {boolean} whether the swap was claimed in time or not
      */
-    waitTillClaimed(maxWaitTimeSeconds?: number, abortSignal?: AbortSignal): Promise<boolean>;
+    waitTillClaimed(maxWaitTimeSeconds?: number, abortSignal?: AbortSignal, secret?: string): Promise<boolean>;
     /**
-     * Is this an LNURL-withdraw swap?
+     * Whether this swap uses an LNURL-withdraw link
      */
     isLNURL(): boolean;
     /**
-     * Gets the used LNURL or null if this is not an LNURL-withdraw swap
+     * Gets the used LNURL or `null` if this is not an LNURL-withdraw swap
      */
     getLNURL(): string | null;
     /**
-     * Pay the generated lightning network invoice with LNURL-withdraw
+     * Pay the generated lightning network invoice with an LNURL-withdraw link, this
+     *  is useful when you want to display a lightning payment QR code and also want to
+     *  allow payments using LNURL-withdraw NFC cards.
+     *
+     * Note that the swap needs to be created **without** an LNURL to begin with for this function
+     *  to work. If this swap is already using an LNURL-withdraw link, this function throws.
      */
     settleWithLNURLWithdraw(lnurl: string | LNURLWithdraw): Promise<void>;
+    /**
+     * @inheritDoc
+     */
     serialize(): any;
     /**
      * Checks the swap's state on-chain and compares it to its internal state, updates/changes it according to on-chain
@@ -226,11 +449,49 @@ export declare class FromBTCLNAutoSwap<T extends ChainType = ChainType> extends
      * @private
      */
     private syncStateFromChain;
-    _shouldFetchCommitStatus(): boolean;
+    /**
+     * @inheritDoc
+     * @internal
+     */
+    _shouldFetchOnchainState(): boolean;
+    /**
+     * @inheritDoc
+     * @internal
+     */
     _shouldFetchExpiryStatus(): boolean;
+    /**
+     * @inheritDoc
+     * @internal
+     */
     _shouldCheckIntermediary(): boolean;
+    /**
+     * @inheritDoc
+     * @internal
+     */
     _sync(save?: boolean, quoteDefinitelyExpired?: boolean, commitStatus?: SwapCommitState, skipLpCheck?: boolean): Promise<boolean>;
-    private broadcastTickCounter;
-    _broadcastSecret(noCheckExpiry?: boolean): Promise<void>;
+    /**
+     * @inheritDoc
+     * @internal
+     */
+    _forciblySetOnchainState(commitStatus: SwapCommitState): Promise<boolean>;
+    /**
+     * Broadcasts the swap secret to the underlying data propagation layer (e.g. Nostr by default)
+     *
+     * @param noCheckExpiry Whether a swap expiration check should be skipped broadcasting
+     * @param secret An optional secret pre-image for the swap to broadcast
+     *
+     * @internal
+     */
+    _broadcastSecret(noCheckExpiry?: boolean, secret?: string): Promise<void>;
+    /**
+     * @inheritDoc
+     * @internal
+     */
     _tick(save?: boolean): Promise<boolean>;
+    /**
+     * Forcibly sets the swap secret pre-image from on-chain data
+     *
+     * @internal
+     */
+    _setSwapSecret(secret: string): void;
 }