@atomiqlabs/sdk 8.1.8 → 8.3.5

package/src/swaps/trusted/onchain/OnchainForGasWrapper.ts

@@ -18,11 +18,36 @@ export type OnchainForGasWrapperOptions = ISwapWrapperOptions & {
 
 export type OnchainForGasSwapTypeDefinition<T extends ChainType> = SwapTypeDefinition<T, OnchainForGasWrapper<T>, OnchainForGasSwap<T>>;
 
+/**
+ * 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
+ *
+ * @category Swaps/Trusted Gas Swaps
+ */
 export class OnchainForGasWrapper<T extends ChainType> extends ISwapWrapper<T, OnchainForGasSwapTypeDefinition<T>, OnchainForGasWrapperOptions> {
-    public readonly TYPE = SwapType.TRUSTED_FROM_BTC;
-    public readonly swapDeserializer = OnchainForGasSwap;
+    public readonly TYPE: SwapType.TRUSTED_FROM_BTC = SwapType.TRUSTED_FROM_BTC;
+    /**
+     * @internal
+     */
+    readonly _swapDeserializer = OnchainForGasSwap;
+
+    /**
+     * @internal
+     */
+    readonly _pendingSwapStates = [OnchainForGasSwapState.PR_CREATED];
+    /**
+     * @internal
+     */
+    protected readonly tickSwapState = undefined;
+    /**
+     * @internal
+     */
+    protected processEvent = undefined;
 
-    readonly btcRpc: BitcoinRpcWithAddressIndex<any>;
+    /**
+     * @internal
+     */
+    readonly _btcRpc: BitcoinRpcWithAddressIndex<any>;
 
     /**
      * @param chainIdentifier
@@ -47,30 +72,31 @@ export class OnchainForGasWrapper<T extends ChainType> extends ISwapWrapper<T, O
         events?: EventEmitter<{swapState: [ISwap]}>
     ) {
         super(chainIdentifier, unifiedStorage, unifiedChainEvents, chain, prices, tokens, options, events);
-        this.btcRpc = btcRpc;
+        this._btcRpc = btcRpc;
     }
 
     /**
-     * Returns a newly created swap, receiving 'amount' base units of gas token
+     * Returns a newly created trusted Bitcoin on-chain -> Smart chain swap, receiving
+     *  the specified amount of native token on the destination chain.
      *
-     * @param signer
-     * @param amount            Amount you wish to receive in base units
-     * @param lpOrUrl           Intermediary/Counterparty swap service Intermediary object or raw url
-     * @param refundAddress     Bitcoin address to receive refund on in case the counterparty cannot execute the swap
+     * @param recipient Address of the recipient on the smart chain destination chain
+     * @param amount Amount of native token to receive in base units
+     * @param lpOrUrl Intermediary (LP) to use for the swap
+     * @param refundAddress Bitcoin address to receive refund on in case the intermediary (LP) cannot execute the swap
      */
-    async create(signer: string, amount: bigint, lpOrUrl: Intermediary | string, refundAddress?: string): Promise<OnchainForGasSwap<T>> {
+    async create(recipient: string, amount: bigint, lpOrUrl: Intermediary | string, refundAddress?: string): Promise<OnchainForGasSwap<T>> {
         if(!this.isInitialized) throw new Error("Not initialized, call init() first!");
 
         const lpUrl = typeof(lpOrUrl)==="string" ? lpOrUrl : lpOrUrl.url;
 
-        const token = this.chain.getNativeCurrencyAddress();
+        const token = this._chain.getNativeCurrencyAddress();
 
         const resp = await TrustedIntermediaryAPI.initTrustedFromBTC(this.chainIdentifier, lpUrl, {
-            address: signer,
+            address: recipient,
             amount,
             refundAddress,
             token
-        }, this.options.getRequestTimeout);
+        }, this._options.getRequestTimeout);
 
         if(resp.total !== amount) throw new IntermediaryError("Invalid total returned");
 
@@ -79,7 +105,7 @@ export class OnchainForGasWrapper<T extends ChainType> extends ISwapWrapper<T, O
                 {swapFeePPM: 10000, swapBaseFee: 10} :
                 lpOrUrl.services[SwapType.TRUSTED_FROM_BTC],
             false, resp.amountSats,
-            amount, this.chain.getNativeCurrencyAddress(), {}
+            amount, this._chain.getNativeCurrencyAddress(), {}
         );
 
         const quote = new OnchainForGasSwap(this, {
@@ -88,7 +114,7 @@ export class OnchainForGasWrapper<T extends ChainType> extends ISwapWrapper<T, O
             address: resp.btcAddress,
             inputAmount: resp.amountSats,
             outputAmount: resp.total,
-            recipient: signer,
+            recipient,
             refundAddress,
             pricingInfo,
             url: lpUrl,
@@ -102,8 +128,4 @@ export class OnchainForGasWrapper<T extends ChainType> extends ISwapWrapper<T, O
         return quote;
     }
 
-    public readonly pendingSwapStates = [OnchainForGasSwapState.PR_CREATED];
-    public readonly tickSwapState = undefined;
-    protected processEvent = undefined;
-
 }

package/src/types/AmountData.ts

@@ -1,5 +1,6 @@
 /**
- * Simple amount definition for swap operations
+ * Amount, token and exact input object for initiating swap operations
+ *
  * @category Tokens
  */
 export type AmountData = {

package/src/types/CustomPriceFunction.ts

@@ -1,5 +1,11 @@
 /**
- * Custom pricing callback function type
- * @category Pricing and LPs
+ * Custom pricing callback function type, fetches the USD price for the provided array
+ *  of token tickers.
+ *
+ * @param tickers Tickers of the tokens to fetch USD price for
+ * @param abortSignal Abort signal
+ * @returns USD prices of the passed tickers in the order that they were passed
+ *
+ * @category Pricing
  */
 export type CustomPriceFunction = (tickers: string[], abortSignal?: AbortSignal) => Promise<number[]>;

package/src/types/PriceInfoType.ts

@@ -2,7 +2,7 @@ import {toBigInt} from "../utils/Utils";
 
 /**
  * Pricing information for swap validation
- * @category Pricing and LPs
+ * @category Pricing
  */
 export type PriceInfoType = {
     isValid: boolean,
@@ -16,7 +16,7 @@ export type PriceInfoType = {
 
 /**
  * Type guard for PriceInfoType
- * @category Pricing and LPs
+ * @category Pricing
  */
 export function isPriceInfoType(obj: any): obj is PriceInfoType {
     return obj != null &&
@@ -31,7 +31,7 @@ export function isPriceInfoType(obj: any): obj is PriceInfoType {
 
 /**
  * Serializes PriceInfoType for storage
- * @category Pricing and LPs
+ * @category Pricing
  */
 export function serializePriceInfoType(obj: PriceInfoType | undefined): any {
     if (obj == null) return null;
@@ -48,7 +48,7 @@ export function serializePriceInfoType(obj: PriceInfoType | undefined): any {
 
 /**
  * Deserializes PriceInfoType from storage
- * @category Pricing and LPs
+ * @category Pricing
  */
 export function deserializePriceInfoType(obj: any): PriceInfoType | undefined {
     if (obj == null) return;

package/src/types/SwapExecutionAction.ts

@@ -1,8 +1,100 @@
 import {ChainType} from "@atomiqlabs/base";
+import {Transaction} from "@scure/btc-signer";
 
-export type SwapExecutionAction<T extends ChainType> = {
-    name: "Payment" | "Commit" | "Claim",
+/**
+ * Swap execution action requiring a payment of the provided bolt11 lightning network invoice
+ *
+ * @category Swap Actions
+ */
+export type SwapExecutionActionLightning = {
+    name: "Payment",
     description: string,
-    chain: "LIGHTNING" | "BITCOIN" | T["ChainId"],
-    txs: any[]
-};
+    chain: "LIGHTNING",
+    txs: {
+        type: "BOLT11_PAYMENT_REQUEST",
+        address: string,
+        hyperlink: string
+    }[]
+}
+
+/**
+ * Swap execution action on on-chain Bitcoin, has following types:
+ * - `"ADDRESS"` - Destination bitcoin address and BTC amount to be sent
+ * - `"FUNDED_PSBT"` - A ready to sign PSBT with the inputs populated from the provided bitcoin wallet address
+ * - `"RAW_PSBT"` - Raw PSBT without the inputs, the implementor needs to add the input UTXOs before signing
+ *  the transaction
+ *
+ * @category Swap Actions
+ */
+export type SwapExecutionActionBitcoin<
+    T extends "ADDRESS" | "FUNDED_PSBT" | "RAW_PSBT" = "ADDRESS" | "FUNDED_PSBT" | "RAW_PSBT"
+> = {
+    name: "Payment",
+    description: string,
+    chain: "BITCOIN",
+    txs: (T extends "ADDRESS" ? {
+        type: "ADDRESS",
+        amount: number,
+        address: string,
+        hyperlink: string
+    } : T extends "FUNDED_PSBT" ? {
+        type: "FUNDED_PSBT",
+        psbt: Transaction,
+        psbtHex: string,
+        psbtBase64: string,
+        signInputs: number[]
+    } : {
+        type: "RAW_PSBT",
+        psbt: Transaction,
+        psbtHex: string,
+        psbtBase64: string,
+        in1sequence: number
+    })[]
+}
+
+/**
+ * Swap execution action for committing (initiating) the escrow on the smart chain side
+ *
+ * @category Swap Actions
+ */
+export type SwapExecutionActionCommit<T extends ChainType> = {
+    name: "Commit",
+    description: string,
+    chain: T["ChainId"],
+    txs: T["TX"][]
+}
+
+/**
+ * Swap execution action for claiming (settling) the swap on the smart chain side
+ *
+ * @category Swap Actions
+ */
+export type SwapExecutionActionClaim<T extends ChainType> = {
+    name: "Claim",
+    description: string,
+    chain: T["ChainId"],
+    txs: T["TX"][]
+}
+
+/**
+ * Swap execution action for refunding the swap on the smart chain side after it fails
+ *
+ * @category Swap Actions
+ */
+export type SwapExecutionActionRefund<T extends ChainType> = {
+    name: "Refund",
+    description: string,
+    chain: T["ChainId"],
+    txs: T["TX"][]
+}
+
+/**
+ * Swap execution action, a single step in the swapping process
+ *
+ * @category Swap Actions
+ */
+export type SwapExecutionAction<T extends ChainType> = SwapExecutionActionLightning |
+    SwapExecutionActionBitcoin |
+    SwapExecutionActionCommit<T> |
+    SwapExecutionActionClaim<T> |
+    SwapExecutionActionRefund<T>;

package/src/types/SwapWithSigner.ts

@@ -3,10 +3,13 @@ import {ChainType} from "@atomiqlabs/base";
 import {IToBTCSwap} from "../swaps/escrow_swaps/tobtc/IToBTCSwap";
 import {IFromBTCSelfInitSwap} from "../swaps/escrow_swaps/frombtc/IFromBTCSelfInitSwap";
 import {FromBTCLNSwap} from "../swaps/escrow_swaps/frombtc/ln/FromBTCLNSwap";
+import {FromBTCLNAutoSwap} from "../swaps/escrow_swaps/frombtc/ln_auto/FromBTCLNAutoSwap";
+import {SpvFromBTCSwap} from "../swaps/spv_swaps/SpvFromBTCSwap";
 
 /**
- * Proxy type that auto-injects signer into swap methods
- * @category Swaps
+ * Proxy type that auto-injects a smart chain signer into swap methods
+ *
+ * @category Swaps/Base
  */
 export type SwapWithSigner<T extends ISwap> = {
     [K in keyof T]:
@@ -19,12 +22,13 @@ export type SwapWithSigner<T extends ISwap> = {
 
 /**
  * Wraps a swap with automatic signer injection for methods like commit, refund, and claim
+ *
  * @category Swaps
+ * @internal
  */
 export function wrapSwapWithSigner<C extends ChainType, T extends ISwap<C>>(swap: T, signer: C["Signer"]): SwapWithSigner<T> {
     return new Proxy(swap, {
         get: (target, prop, receiver) => {
-            // Override the "sayGoodbye" method
             if (prop === "commit") {
                 if(swap instanceof IToBTCSwap || swap instanceof IFromBTCSelfInitSwap) {
                     return (abortSignal?: AbortSignal, skipChecks?: boolean) =>
@@ -38,7 +42,7 @@ export function wrapSwapWithSigner<C extends ChainType, T extends ISwap<C>>(swap
                 }
             }
             if (prop === "claim") {
-                if(swap instanceof IFromBTCSelfInitSwap) {
+                if(swap instanceof IFromBTCSelfInitSwap || swap instanceof FromBTCLNAutoSwap || swap instanceof SpvFromBTCSwap) {
                     return (abortSignal?: AbortSignal) =>
                         swap.claim(signer, abortSignal);
                 }

package/src/types/Token.ts

@@ -1,5 +1,6 @@
 /**
- * Bitcoin token type (on-chain or lightning)
+ * Bitcoin token type (BTC on on-chain or lightning)
+ *
  * @category Tokens
  */
 export type BtcToken<L = boolean> = {
@@ -12,7 +13,8 @@ export type BtcToken<L = boolean> = {
 };
 
 /**
- * Type guard for BtcToken
+ * Type guard for {@link BtcToken} (token on the bitcoin network - lightning or on-chain)
+ *
  * @category Tokens
  */
 export function isBtcToken(obj: any): obj is BtcToken {
@@ -26,6 +28,7 @@ export function isBtcToken(obj: any): obj is BtcToken {
 
 /**
  * Predefined Bitcoin token constants
+ *
  * @category Tokens
  */
 export const BitcoinTokens: {
@@ -47,8 +50,10 @@ export const BitcoinTokens: {
         name: "Bitcoin (lightning L2)"
     }
 };
+
 /**
- * Smart Chain token type
+ * Token on the smart chain
+ *
  * @category Tokens
  */
 export type SCToken<ChainIdentifier extends string = string> = {
@@ -62,7 +67,7 @@ export type SCToken<ChainIdentifier extends string = string> = {
 }
 
 /**
- * Type guard for SCToken
+ * Type guard for {@link SCToken} (token on the smart chain)
  * @category Tokens
  */
 export function isSCToken(obj: any): obj is SCToken {
@@ -77,12 +82,14 @@ export function isSCToken(obj: any): obj is SCToken {
 
 /**
  * Union type for all token types (BTC or smart chain)
+ *
  * @category Tokens
  */
 export type Token<ChainIdentifier extends string = string> = BtcToken | SCToken<ChainIdentifier>;
 
 /**
- * Type guard for Token
+ * Type guard for an union {@link Token} type, encompassing all tokens (BTC or smart chain)
+ *
  * @category Tokens
  */
 export function isToken(obj: any): obj is Token {

package/src/types/TokenAmount.ts

@@ -5,6 +5,7 @@ import {toDecimal} from "../utils/Utils";
 
 /**
  * Represents a token amount along with its formatted values and USD valuation helpers
+ *
  * @category Tokens
  */
 export type TokenAmount<
@@ -68,7 +69,9 @@ export type TokenAmount<
 
 /**
  * Factory function to create a TokenAmount
+ *
  * @category Tokens
+ * @internal
  */
 export function toTokenAmount<
     ChainIdentifier extends string = string,

package/src/types/fees/Fee.ts

@@ -3,9 +3,10 @@ import {TokenAmount} from "../TokenAmount";
 import {Token} from "../Token";
 
 /**
- * Represents a fee in both source and destination tokens, as well as providing USD valuation helpers and
+ * Fee represented in both, source and destination tokens, as well as providing USD valuation helpers and
  *  fee composition
- * @category Pricing and LPs
+ *
+ * @category Pricing
  */
 export type Fee<
     ChainIdentifier extends string = string,

package/src/types/fees/FeeBreakdown.ts

@@ -2,8 +2,9 @@ import {FeeType} from "../../enums/FeeType";
 import {Fee} from "./Fee";
 
 /**
- * Breakdown of fees by type (swap fee vs network fee)
- * @category Pricing and LPs
+ * Breakdown of fees by type (swap fee, network fee, etc.)
+ *
+ * @category Pricing
  */
 export type FeeBreakdown<ChainIdentifier extends string = string> = {
     type: FeeType,

package/src/types/fees/PercentagePPM.ts

@@ -1,6 +1,7 @@
 /**
  * Parts-per-million fee representation with conversion helpers
- * @category Pricing and LPs
+ *
+ * @category Pricing
  */
 export type PercentagePPM = {
     ppm: bigint,
@@ -11,7 +12,8 @@ export type PercentagePPM = {
 
 /**
  * Converts parts-per-million to percentage representation
- * @category Pricing and LPs
+ *
+ * @category Pricing
  */
 export function ppmToPercentage(ppm: bigint): PercentagePPM {
     const percentage = Number(ppm) / 10_000;

package/src/types/lnurl/LNURLPay.ts

@@ -1,6 +1,7 @@
 /**
- * LNURL-pay request parameters
- * @category Bitcoin
+ * Response of the LNURL-pay link
+ *
+ * @category Lightning
  */
 export type LNURLPayParams = {
     tag: "payRequest";
@@ -14,14 +15,16 @@ export type LNURLPayParams = {
 }
 
 /**
- * LNURL-pay parameters with URL
- * @category Bitcoin
+ * Response of the LNURL-pay link with the added original url
+ *
+ * @category Lightning
  */
 export type LNURLPayParamsWithUrl = LNURLPayParams & { url: string };
 
 /**
- * LNURL-pay specification
- * @category Bitcoin
+ * Parsed LNURL-pay specification
+ *
+ * @category Lightning
  */
 export type LNURLPay = {
     type: "pay",
@@ -35,16 +38,20 @@ export type LNURLPay = {
 }
 
 /**
- * Type guard for LNURL-pay parameters
- * @category Bitcoin
+ * Type guard for {@link LNURLPayParams}
+ *
+ * @category Lightning
+ * @internal
  */
 export function isLNURLPayParams(obj: any): obj is LNURLPayParams {
     return obj.tag === "payRequest";
 }
 
 /**
- * Type guard for LNURL-pay
- * @category Bitcoin
+ * Type guard for {@link LNURLPay}
+ *
+ * @category Lightning
+ * @internal
  */
 export function isLNURLPay(value: any): value is LNURLPay {
     return (
@@ -62,8 +69,9 @@ export function isLNURLPay(value: any): value is LNURLPay {
 }
 
 /**
- * Decoded LNURL-pay success action
- * @category Bitcoin
+ * Decoded LNURL-pay success action, revealed after a lightning payment is finished
+ *
+ * @category Lightning
  */
 export type LNURLDecodedSuccessAction = {
     description: string,

package/src/types/lnurl/LNURLWithdraw.ts

@@ -1,6 +1,7 @@
 /**
- * LNURL-withdraw request parameters
- * @category Bitcoin
+ * Response of the LNURL-withdraw link
+ *
+ * @category Lightning
  */
 export type LNURLWithdrawParams = {
     tag: "withdrawRequest";
@@ -15,14 +16,16 @@ export type LNURLWithdrawParams = {
 }
 
 /**
- * LNURL-withdraw parameters with URL
- * @category Bitcoin
+ * Response of the LNURL-withdraw link with the added original url
+ *
+ * @category Lightning
  */
 export type LNURLWithdrawParamsWithUrl = LNURLWithdrawParams & { url: string };
 
 /**
- * LNURL-withdraw specification
- * @category Bitcoin
+ * Parsed LNURL-withdraw specification
+ *
+ * @category Lightning
  */
 export type LNURLWithdraw = {
     type: "withdraw",
@@ -32,8 +35,10 @@ export type LNURLWithdraw = {
 }
 
 /**
- * Type guard for LNURL-withdraw
- * @category Bitcoin
+ * Type guard for {@link LNURLWithdraw}
+ *
+ * @category Lightning
+ * @internal
  */
 export function isLNURLWithdraw(value: any): value is LNURLWithdraw {
     return (
@@ -47,8 +52,10 @@ export function isLNURLWithdraw(value: any): value is LNURLWithdraw {
 }
 
 /**
- * Type guard for LNURL-withdraw parameters
- * @category Bitcoin
+ * Type guard for {@link LNURLWithdrawParams}
+ *
+ * @category Lightning
+ * @internal
  */
 export function isLNURLWithdrawParams(obj: any): obj is LNURLWithdrawParams {
     return obj.tag === "withdrawRequest";

package/src/types/wallets/LightningInvoiceCreateService.ts

@@ -0,0 +1,30 @@
+/**
+ * Invoice getter callback for the {@link LightningInvoiceCreateService}
+ *
+ * @category Lightning
+ */
+export type LightningWalletCallback = (valueSats: number, abortSignal?: AbortSignal) => Promise<string>;
+/**
+ * Service that creates on-demand fixed amount bolt11 lightning network invoices, optionally
+ *  specifying minimum and maximum swappable sats amount. This used for exact input Smart chain ->
+ *  Lightning swaps.
+ *
+ * @category Lightning
+ */
+export type LightningInvoiceCreateService = {
+    getInvoice: LightningWalletCallback,
+    minMsats?: bigint,
+    maxMSats?: bigint
+};
+
+/**
+ * Type guard for {@link LightningInvoiceCreateService}
+ *
+ * @internal
+ */
+export function isLightningInvoiceCreateService(obj: any): obj is LightningInvoiceCreateService {
+    return typeof (obj) === "object" &&
+        typeof (obj.getInvoice) === "function" &&
+        (obj.minMsats == null || typeof (obj.minMsats) === "bigint") &&
+        (obj.maxMSats == null || typeof (obj.maxMSats) === "bigint");
+}

package/src/types/wallets/MinimalBitcoinWalletInterface.ts

@@ -2,7 +2,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 = {
@@ -12,6 +13,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/src/types/wallets/MinimalLightningNetworkWalletInterface.ts

@@ -1,6 +1,8 @@
 /**
- * A type with minimum possible required functionality to be usable with lightning network swaps
- * @category Bitcoin
+ * 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 Lightning
  */
 export type MinimalLightningNetworkWalletInterface = {
     payInvoice: (bolt11PaymentRequest: string) => Promise<string>

package/src/utils/BitcoinUtils.ts

@@ -3,6 +3,11 @@ import {Buffer} from "buffer";
 import {Address, OutScript, Transaction} from "@scure/btc-signer";
 import {CoinselectAddressTypes} from "../bitcoin/coinselect2";
 
+
+export function fromOutputScript(network: BTC_NETWORK, outputScriptHex: string): string {
+    return Address(network).encode(OutScript.decode(Buffer.from(outputScriptHex, "hex")));
+}
+
 export function toOutputScript(network: BTC_NETWORK, address: string): Buffer {
     const outputScript = Address(network).decode(address);
     switch(outputScript.type) {