@atomiqlabs/sdk 8.1.8 → 8.3.5

package/src/swaps/escrow_swaps/tobtc/IToBTCWrapper.ts

@@ -8,11 +8,35 @@ import {AmountData} from "../../../types/AmountData";
 
 export type IToBTCDefinition<T extends ChainType, W extends IToBTCWrapper<T, any>, S extends IToBTCSwap<T>> = SwapTypeDefinition<T, W, S>;
 
+/**
+ * Base class for wrappers of escrow-based Smart chain -> Bitcoin (on-chain & lightning) swaps
+ *
+ * @category Swaps/Smart chain → Bitcoin
+ */
 export abstract class IToBTCWrapper<
     T extends ChainType,
     D extends IToBTCDefinition<T, IToBTCWrapper<T, D>, IToBTCSwap<T, D>>,
     O extends ISwapWrapperOptions = ISwapWrapperOptions
 > extends IEscrowSwapWrapper<T, D, O> {
+    /**
+     * @internal
+     */
+    protected readonly tickSwapState = [ToBTCSwapState.CREATED, ToBTCSwapState.COMMITED, ToBTCSwapState.SOFT_CLAIMED];
+
+    /**
+     * @internal
+     */
+    readonly _pendingSwapStates = [
+        ToBTCSwapState.CREATED,
+        ToBTCSwapState.QUOTE_SOFT_EXPIRED,
+        ToBTCSwapState.COMMITED,
+        ToBTCSwapState.SOFT_CLAIMED,
+        ToBTCSwapState.REFUNDABLE
+    ];
+    /**
+     * @internal
+     */
+    readonly _refundableSwapStates = [ToBTCSwapState.REFUNDABLE];
 
     /**
      * Pre-fetches intermediary's reputation, doesn't throw, instead aborts via abortController and returns null
@@ -20,16 +44,17 @@ export abstract class IToBTCWrapper<
      * @param amountData
      * @param lp Intermediary
      * @param abortController
-     * @protected
      * @returns Intermediary's reputation or null if failed
      * @throws {IntermediaryError} If the intermediary vault doesn't exist
+     *
+     * @internal
      */
     protected preFetchIntermediaryReputation(
         amountData: Omit<AmountData, "amount">,
         lp: Intermediary,
         abortController: AbortController
     ): Promise<SingleChainReputationType | undefined> {
-        return lp.getReputation(this.chainIdentifier, this.contract, [amountData.token.toString()], abortController.signal).then(res => {
+        return lp.getReputation(this.chainIdentifier, this._contract, [amountData.token.toString()], abortController.signal).then(res => {
             if(res==null) throw new IntermediaryError("Invalid data returned - invalid LP vault");
             return res;
         }).catch(e => {
@@ -46,11 +71,12 @@ export abstract class IToBTCWrapper<
      * @param amountData
      * @param claimHash optional hash of the swap or null
      * @param abortController
-     * @protected
      * @returns Fee rate
+     *
+     * @internal
      */
     protected preFetchFeeRate(signer: string, amountData: Omit<AmountData, "amount">, claimHash: string | undefined, abortController: AbortController): Promise<string | undefined> {
-        return this.contract.getInitPayInFeeRate(signer, this.chain.randomAddress(), amountData.token, claimHash)
+        return this._contract.getInitPayInFeeRate(signer, this._chain.randomAddress(), amountData.token, claimHash)
             .catch(e => {
                 this.logger.warn("preFetchFeeRate(): Error: ", e);
                 abortController.abort(e);
@@ -58,44 +84,43 @@ export abstract class IToBTCWrapper<
             });
     }
 
-    public readonly pendingSwapStates = [
-        ToBTCSwapState.CREATED,
-        ToBTCSwapState.QUOTE_SOFT_EXPIRED,
-        ToBTCSwapState.COMMITED,
-        ToBTCSwapState.SOFT_CLAIMED,
-        ToBTCSwapState.REFUNDABLE
-    ];
-    public readonly tickSwapState = [ToBTCSwapState.CREATED, ToBTCSwapState.COMMITED, ToBTCSwapState.SOFT_CLAIMED];
-    public readonly refundableSwapStates = [ToBTCSwapState.REFUNDABLE];
-
+    /**
+     * @internal
+     */
     protected async processEventInitialize(swap: D["Swap"], event: InitializeEvent<T["Data"]>): Promise<boolean> {
-        if(swap.state===ToBTCSwapState.CREATED || swap.state===ToBTCSwapState.QUOTE_SOFT_EXPIRED) {
-            swap.state = ToBTCSwapState.COMMITED;
-            if(swap.commitTxId==null) swap.commitTxId = event.meta?.txId;
+        if(swap._state===ToBTCSwapState.CREATED || swap._state===ToBTCSwapState.QUOTE_SOFT_EXPIRED) {
+            swap._state = ToBTCSwapState.COMMITED;
+            if(swap._commitTxId==null) swap._commitTxId = event.meta?.txId;
             return true;
         }
         return false;
     }
 
+    /**
+     * @internal
+     */
     protected async processEventClaim(swap: D["Swap"], event: ClaimEvent<T["Data"]>): Promise<boolean> {
-        if(swap.state!==ToBTCSwapState.REFUNDED && swap.state!==ToBTCSwapState.CLAIMED) {
+        if(swap._state!==ToBTCSwapState.REFUNDED && swap._state!==ToBTCSwapState.CLAIMED) {
             await swap._setPaymentResult({
                 secret: event.result,
                 txId: Buffer.from(event.result, "hex").reverse().toString("hex")
             }).catch(e => {
                 this.logger.warn(`processEventClaim(): Failed to set payment result ${event.result}: `, e);
             });
-            swap.state = ToBTCSwapState.CLAIMED;
-            if(swap.claimTxId==null) swap.claimTxId = event.meta?.txId;
+            swap._state = ToBTCSwapState.CLAIMED;
+            if(swap._claimTxId==null) swap._claimTxId = event.meta?.txId;
             return true;
         }
         return false;
     }
 
+    /**
+     * @internal
+     */
     protected processEventRefund(swap: D["Swap"], event: RefundEvent<T["Data"]>): Promise<boolean> {
-        if(swap.state!==ToBTCSwapState.CLAIMED && swap.state!==ToBTCSwapState.REFUNDED) {
-            swap.state = ToBTCSwapState.REFUNDED;
-            if(swap.refundTxId==null) swap.refundTxId = event.meta?.txId;
+        if(swap._state!==ToBTCSwapState.CLAIMED && swap._state!==ToBTCSwapState.REFUNDED) {
+            swap._state = ToBTCSwapState.REFUNDED;
+            if(swap._refundTxId==null) swap._refundTxId = event.meta?.txId;
             return Promise.resolve(true);
         }
         return Promise.resolve(false);

package/src/swaps/escrow_swaps/tobtc/ln/ToBTCLNSwap.ts

@@ -34,25 +34,38 @@ const SNOWFLAKE_LIST: Set<string> = new Set([
 ]);
 
 /**
- * Smart Chain to Lightning Network BTC swap
- * @category Swaps
+ * Escrow based (HTLC) swap for Smart chains -> Bitcoin lightning
+ *
+ * @category Swaps/Smart chain → Lightning
  */
 export class ToBTCLNSwap<T extends ChainType = ChainType> extends IToBTCSwap<T, ToBTCLNDefinition<T>> {
-    private readonly usesClaimHashAsId: boolean;
-
-    protected outputToken: BtcToken<true> = BitcoinTokens.BTCLN;
     protected readonly TYPE = SwapType.TO_BTCLN;
+    /**
+     * @internal
+     */
+    protected readonly outputToken: BtcToken<true> = BitcoinTokens.BTCLN;
+    /**
+     * @internal
+     */
     protected readonly logger: LoggerType;
 
+    private readonly usesClaimHashAsId: boolean;
     private readonly confidence: number;
-    private readonly pr?: string;
-
-    readonly paymentHash?: string;
+    private pr?: string;
+    private secret?: string;
 
-    lnurl?: string;
-    successAction?: LNURLPaySuccessAction;
+    private lnurl?: string;
+    private successAction?: LNURLPaySuccessAction;
 
-    private secret?: string;
+    /**
+     * Sets the LNURL data for the swap
+     *
+     * @internal
+     */
+    _setLNURLData(lnurl: string, successAction?: LNURLPaySuccessAction) {
+        this.lnurl = lnurl;
+        this.successAction = successAction;
+    }
 
     constructor(wrapper: ToBTCLNWrapper<T>, init: ToBTCLNSwapInit<T["Data"]>);
     constructor(wrapper: ToBTCLNWrapper<T>, obj: any);
@@ -75,23 +88,30 @@ export class ToBTCLNSwap<T extends ChainType = ChainType> extends IToBTCSwap<T,
             this.usesClaimHashAsId = initOrObj.usesClaimHashAsId ?? false;
         }
 
-        const paymentHash = this.getPaymentHash();
-        if(paymentHash!=null) this.paymentHash = paymentHash.toString("hex");
         this.logger = getLogger("ToBTCLN("+this.getIdentifierHashString()+"): ");
         this.tryRecomputeSwapPrice();
     }
 
+    /**
+     * @inheritDoc
+     * @internal
+     */
     _setPaymentResult(result: { secret?: string; txId?: string }, check: boolean = false): Promise<boolean> {
         if(result==null) return Promise.resolve(false);
         if(result.secret==null) throw new IntermediaryError("No payment secret returned!");
+
+        const secretBuffer = Buffer.from(result.secret, "hex");
+        const hash = Buffer.from(sha256(secretBuffer));
+
         if(check) {
-            const secretBuffer = Buffer.from(result.secret, "hex");
-            const hash = Buffer.from(sha256(secretBuffer));
-            const claimHash = this.wrapper.contract.getHashForHtlc(hash);
+            const claimHash = this.wrapper._contract.getHashForHtlc(hash);
 
             const expectedClaimHash = Buffer.from(this.getClaimHash(), "hex");
             if(!claimHash.equals(expectedClaimHash)) throw new IntermediaryError("Invalid payment secret returned");
         }
+
+        this.pr ??= hash.toString("hex");
+
         this.secret = result.secret;
         return Promise.resolve(true);
     }
@@ -100,29 +120,40 @@ export class ToBTCLNSwap<T extends ChainType = ChainType> extends IToBTCSwap<T,
     //////////////////////////////
     //// Amounts & fees
 
+    /**
+     * @inheritDoc
+     */
     getOutputToken(): BtcToken<true> {
         return BitcoinTokens.BTCLN;
     }
 
+    /**
+     * @inheritDoc
+     */
     getOutput(): TokenAmount<T["ChainId"], BtcToken<true>> {
         if(this.pr==null || !this.pr.toLowerCase().startsWith("ln"))
-            return toTokenAmount(null, this.outputToken, this.wrapper.prices, this.pricingInfo);
+            return toTokenAmount(null, this.outputToken, this.wrapper._prices, this.pricingInfo);
         const parsedPR = bolt11Decode(this.pr);
         if(parsedPR.millisatoshis==null) throw new Error("Swap invoice has no msat amount field!");
         const amount = (BigInt(parsedPR.millisatoshis) + 999n) / 1000n;
-        return toTokenAmount(amount, this.outputToken, this.wrapper.prices, this.pricingInfo);
+        return toTokenAmount(amount, this.outputToken, this.wrapper._prices, this.pricingInfo);
     }
 
 
     //////////////////////////////
     //// Getters & utils
 
+    /**
+     * @inheritDoc
+     */
     getOutputTxId(): string | null {
-        return this.getLpIdentifier();
+        const paymentHash = this.getPaymentHash();
+        if(paymentHash==null) return null;
+        return paymentHash.toString("hex");
     }
 
     /**
-     * Returns the lightning BOLT11 invoice where the BTC will be sent to
+     * @inheritDoc
      */
     getOutputAddress(): string | null {
         return this.lnurl ?? this.pr ?? null;
@@ -136,15 +167,16 @@ export class ToBTCLNSwap<T extends ChainType = ChainType> extends IToBTCSwap<T,
     }
 
     /**
-     * Returns the confidence of the intermediary that this payment will succeed
-     * Value between 0 and 1, where 0 is not likely and 1 is very likely
+     * Returns the confidence of the intermediary that this payment will succeed.
+     *
+     * @returns Decimal value between 0 and 1, where 0 is not likely and 1 is very likely
      */
     getConfidence(): number {
         return this.confidence;
     }
 
     /**
-     * Checks whether a swap is likely to fail, based on the confidence as reported by the LP
+     * Checks whether a swap is likely to fail, based on the confidence as reported by the intermediary (LP)
      */
     willLikelyFail(): boolean {
         if(this.pr==null || !this.pr.toLowerCase().startsWith("ln")) return false;
@@ -163,8 +195,8 @@ export class ToBTCLNSwap<T extends ChainType = ChainType> extends IToBTCSwap<T,
     }
 
     /**
-     * Tries to detect if the target lightning invoice is a non-custodial mobile wallet, care must be taken
-     *  for such a wallet to be online when attempting to make a swap
+     * Tries to detect if the target lightning invoice is a non-custodial mobile wallet, extract care must be taken
+     *  for such a wallet **to be online** when attempting to make a swap sending to such a wallet
      */
     isPayingToNonCustodialWallet(): boolean {
         if(this.pr==null || !this.pr.toLowerCase().startsWith("ln")) return false;
@@ -177,32 +209,44 @@ export class ToBTCLNSwap<T extends ChainType = ChainType> extends IToBTCSwap<T,
         return false;
     }
 
-    getIdentifierHash(): Buffer {
+    /**
+     * @inheritDoc
+     * @internal
+     */
+    protected getIdentifierHash(): Buffer {
         const idBuffer: Buffer = this.usesClaimHashAsId
             ? Buffer.from(this.getClaimHash(), "hex")
             : this.getPaymentHash()!;
-        if(this.randomNonce==null) return idBuffer;
-        return Buffer.concat([idBuffer, Buffer.from(this.randomNonce, "hex")]);
+        if(this._randomNonce==null) return idBuffer;
+        return Buffer.concat([idBuffer, Buffer.from(this._randomNonce, "hex")]);
     }
 
-    getPaymentHash(): Buffer | null {
-        if(this.pr==null) return null;
+    /**
+     * @inheritDoc
+     * @internal
+     */
+    protected getLpIdentifier(): string {
+        if(this.pr==null) return this._data.getEscrowHash();
         if(this.pr.toLowerCase().startsWith("ln")) {
             const parsed = bolt11Decode(this.pr);
             if(parsed.tagsObject.payment_hash==null) throw new Error("Swap invoice has no payment hash field!");
-            return Buffer.from(parsed.tagsObject.payment_hash, "hex");
+            return parsed.tagsObject.payment_hash;
         }
-        return Buffer.from(this.pr, "hex");
+        return this.pr;
     }
 
-    protected getLpIdentifier(): string {
-        if(this.pr==null) return this.data.getEscrowHash();
+    /**
+     * Returns the payment hash of the swap, i.e. a payment hash of the lightning network invoice that
+     *  is about to be paid
+     */
+    getPaymentHash(): Buffer | null {
+        if(this.pr==null) return null;
         if(this.pr.toLowerCase().startsWith("ln")) {
             const parsed = bolt11Decode(this.pr);
             if(parsed.tagsObject.payment_hash==null) throw new Error("Swap invoice has no payment hash field!");
-            return parsed.tagsObject.payment_hash;
+            return Buffer.from(parsed.tagsObject.payment_hash, "hex");
         }
-        return this.pr;
+        return Buffer.from(this.pr, "hex");
     }
 
 
@@ -210,28 +254,28 @@ export class ToBTCLNSwap<T extends ChainType = ChainType> extends IToBTCSwap<T,
     //// LNURL-pay
 
     /**
-     * Is this an LNURL-pay swap?
+     * Whether this is an LNURL-pay swap
      */
     isLNURL(): boolean {
         return this.lnurl!=null;
     }
 
     /**
-     * Gets the used LNURL or null if this is not an LNURL-pay swap
+     * Gets the used LNURL-pay link or `null` if this is not an LNURL-pay swap
      */
     getLNURL(): string | null {
         return this.lnurl ?? null;
     }
 
     /**
-     * Checks whether this LNURL payment contains a success message
+     * Checks whether this LNURL-pay payment contains a success action
      */
     hasSuccessAction(): boolean {
         return this.successAction!=null;
     }
 
     /**
-     * Returns the success action after a successful payment, else null
+     * Returns the success action after a successful payment, else `null`
      */
     getSuccessAction(): LNURLDecodedSuccessAction | null {
         return LNURL.decodeSuccessAction(this.successAction, this.secret);
@@ -241,6 +285,9 @@ export class ToBTCLNSwap<T extends ChainType = ChainType> extends IToBTCSwap<T,
     //////////////////////////////
     //// Storage
 
+    /**
+     * @inheritDoc
+     */
     serialize(): any {
         return {
             ...super.serialize(),