@atomiqlabs/sdk 8.8.3 → 8.9.0

package/dist/swapper/Swapper.d.ts

@@ -39,6 +39,7 @@ import { LNURLPay } from "../types/lnurl/LNURLPay";
 import { NotNever } from "../utils/TypeUtils";
 import { LightningInvoiceCreateService } from "../types/wallets/LightningInvoiceCreateService";
 import { SwapSide } from "../enums/SwapSide";
+import { IntermediaryAPI } from "../intermediaries/apis/IntermediaryAPI";
 import { BitcoinWalletUtxo, IBitcoinWallet } from "../bitcoin/wallet/IBitcoinWallet";
 import { MinimalBitcoinWalletInterface } from "../types/wallets/MinimalBitcoinWalletInterface";
 /**
@@ -99,8 +100,9 @@ export type SwapperOptions = {
     noTimers?: boolean;
     /**
      * By setting this flag, the swapper doesn't subscribe to on-chain events. To make sure the swap states are
-     *  properly updated you should call the {@link Swapper._syncSwaps} function periodically. This flag should be
-     *  set when you run an environment that doesn't support long-running timers and websocket connections - e.g.
+     *  properly updated you should either call the {@link Swapper._syncSwaps} function periodically, or use the
+     *  {@link Swapper._pollChainEvents} function to manually poll for on-chain events. This flag should be set
+     *  when you run an environment that doesn't support long-running timers and websocket connections - e.g.
      *  serverless environments like Azure Function Apps or AWS Lambda
      */
     noEvents?: boolean;
@@ -130,7 +132,7 @@ export type SwapperOptions = {
      *  want to only create a swap, and then later on retrieve it with the `swapper.getSwapById()` function.
      *
      * Setting this to `false` means the SDK only saves and persists swaps that are considered initiated, i.e. when
-     *  `commit()`, `execute()` or `waitTillPayment` is called (or their respective txs... prefixed variations). This
+     *  `commit()`, `execute()` or `waitTillPayment()` is called (or their respective txs... prefixed variations). This
      *  might save calls to the persistent storage for swaps that are never initiated. This is useful in e.g.
      *  frontend implementations where the frontend holds the swap object reference until it is initiated anyway, not
      *  necessitating the saving of the swap data to the persistent storage until it is actually initiated.
@@ -141,6 +143,13 @@ export type SwapperOptions = {
      *  (as checked from multiple server sources) it adjusts the `Date.now()` function to return proper actual time.
      */
     automaticClockDriftCorrection?: boolean;
+    /**
+     * Used in centralized API deployments to allow higher rate limits from LPs
+     */
+    signedKeyBasedAuth?: {
+        certificate: string;
+        privateKey: string;
+    };
 };
 /**
  * Type representing multiple blockchain configurations
@@ -248,6 +257,10 @@ export declare class Swapper<T extends MultiChain> extends EventEmitter<{
      * Pricing API used by the SDK
      */
     readonly prices: ISwapPrice<T>;
+    /**
+     * API for contacting LPs
+     */
+    readonly lpApi: IntermediaryAPI;
     /**
      * Intermediary discovery instance
      */
@@ -267,6 +280,10 @@ export declare class Swapper<T extends MultiChain> extends EventEmitter<{
      * Initializes the swap storage and loads existing swaps, needs to be called before any other action
      */
     init(): Promise<void>;
+    /**
+     * Whether the SDK is initialized (after {@link init} is called)
+     */
+    isInitialized(): boolean;
     /**
      * Stops listening for onchain events and closes this Swapper instance
      */
@@ -553,6 +570,14 @@ export declare class Swapper<T extends MultiChain> extends EventEmitter<{
      * Returns all swaps for the specific chain, and optionally also for a specific signer's address
      */
     getAllSwaps<C extends ChainIds<T>>(chainId: C, signer?: string): Promise<ISwap<T[C]>[]>;
+    /**
+     * Returns all swaps which are pending (i.e. not in their final state yet)
+     */
+    getPendingSwaps(): Promise<ISwap[]>;
+    /**
+     * Returns swaps which are pending (i.e. not in their final state yet) for the specific chain, and optionally also for a specific signer's address
+     */
+    getPendingSwaps<C extends ChainIds<T>>(chainId: C, signer?: string): Promise<ISwap<T[C]>[]>;
     /**
      * Returns all swaps where an action is required (either claim or refund)
      */
@@ -614,6 +639,14 @@ export declare class Swapper<T extends MultiChain> extends EventEmitter<{
      * @param signer Optional signer to only run swap sync for swaps initiated by this signer
      */
     _syncSwaps<C extends ChainIds<T>>(chainId?: C, signer?: string): Promise<void>;
+    /**
+     * When the swapper is initiated with the `noEvents` config this function allows you to manually poll for on-chain
+     *  events. It returns an events cursor which you should save and pass to the next call to the `poll()` function.
+     *
+     * @param chainId Chain for which to poll the chain events listener for
+     * @param lastEventCursorState Event cursor state returned from the last call to the `poll()` function
+     */
+    _pollChainEvents<C extends ChainIds<T>>(chainId: C, lastEventCursorState?: any): Promise<any>;
     /**
      * Recovers swaps from on-chain historical data.
      *

package/dist/swapper/Swapper.js

@@ -35,7 +35,9 @@ const LNURLPay_1 = require("../types/lnurl/LNURLPay");
 const RetryUtils_1 = require("../utils/RetryUtils");
 const IEscrowSwap_1 = require("../swaps/escrow_swaps/IEscrowSwap");
 const LightningInvoiceCreateService_1 = require("../types/wallets/LightningInvoiceCreateService");
+const IntermediaryAPI_1 = require("../intermediaries/apis/IntermediaryAPI");
 const BitcoinWalletUtils_1 = require("../utils/BitcoinWalletUtils");
+const SignedKeyBasedAuth_1 = require("../intermediaries/auth/SignedKeyBasedAuth");
 /**
  * Core orchestrator for all atomiq swap operations
  *
@@ -88,6 +90,10 @@ class Swapper extends events_1.EventEmitter {
             this._tokensByTicker[chainId] ??= {};
             this._tokens[chainId][tokenData.address] = this._tokensByTicker[chainId][tokenData.ticker] = tokenData;
         }
+        const lpApi = new IntermediaryAPI_1.IntermediaryAPI(this.options.signedKeyBasedAuth != null
+            ? (0, SignedKeyBasedAuth_1.getSignedKeyBasedAuthHandler)(this.options.signedKeyBasedAuth.certificate, this.options.signedKeyBasedAuth.privateKey)
+            : undefined);
+        this.lpApi = lpApi;
         this.swapStateListener = (swap) => {
             this.emit("swapState", swap);
         };
@@ -118,35 +124,35 @@ class Swapper extends events_1.EventEmitter {
             const unifiedSwapStorage = new UnifiedSwapStorage_1.UnifiedSwapStorage(storageHandler, this.options.noSwapCache);
             const unifiedChainEvents = new UnifiedSwapEventListener_1.UnifiedSwapEventListener(unifiedSwapStorage, chainEvents);
             const wrappers = {};
-            wrappers[SwapType_1.SwapType.TO_BTCLN] = new ToBTCLNWrapper_1.ToBTCLNWrapper(key, unifiedSwapStorage, unifiedChainEvents, chainInterface, pricing, this._tokens[chainId], versions, {
+            wrappers[SwapType_1.SwapType.TO_BTCLN] = new ToBTCLNWrapper_1.ToBTCLNWrapper(key, unifiedSwapStorage, unifiedChainEvents, chainInterface, pricing, this._tokens[chainId], versions, lpApi, {
                 getRequestTimeout: this.options.getRequestTimeout,
                 postRequestTimeout: this.options.postRequestTimeout,
                 saveUninitializedSwaps: this.options.saveUninitializedSwaps,
             });
-            wrappers[SwapType_1.SwapType.TO_BTC] = new ToBTCWrapper_1.ToBTCWrapper(key, unifiedSwapStorage, unifiedChainEvents, chainInterface, pricing, this._tokens[chainId], versions, this._bitcoinRpc, {
+            wrappers[SwapType_1.SwapType.TO_BTC] = new ToBTCWrapper_1.ToBTCWrapper(key, unifiedSwapStorage, unifiedChainEvents, chainInterface, pricing, this._tokens[chainId], versions, this._bitcoinRpc, lpApi, {
                 getRequestTimeout: this.options.getRequestTimeout,
                 postRequestTimeout: this.options.postRequestTimeout,
                 saveUninitializedSwaps: this.options.saveUninitializedSwaps,
                 bitcoinNetwork: this._btcNetwork
             });
-            wrappers[SwapType_1.SwapType.FROM_BTCLN] = new FromBTCLNWrapper_1.FromBTCLNWrapper(key, unifiedSwapStorage, unifiedChainEvents, chainInterface, pricing, this._tokens[chainId], versions, lightningApi, {
+            wrappers[SwapType_1.SwapType.FROM_BTCLN] = new FromBTCLNWrapper_1.FromBTCLNWrapper(key, unifiedSwapStorage, unifiedChainEvents, chainInterface, pricing, this._tokens[chainId], versions, lightningApi, lpApi, {
                 getRequestTimeout: this.options.getRequestTimeout,
                 postRequestTimeout: this.options.postRequestTimeout,
                 saveUninitializedSwaps: this.options.saveUninitializedSwaps,
                 unsafeSkipLnNodeCheck: this.bitcoinNetwork === base_1.BitcoinNetwork.TESTNET4 || this.bitcoinNetwork === base_1.BitcoinNetwork.REGTEST
             });
-            wrappers[SwapType_1.SwapType.FROM_BTC] = new FromBTCWrapper_1.FromBTCWrapper(key, unifiedSwapStorage, unifiedChainEvents, chainInterface, pricing, this._tokens[chainId], versions, versionedContracts, this._bitcoinRpc, {
+            wrappers[SwapType_1.SwapType.FROM_BTC] = new FromBTCWrapper_1.FromBTCWrapper(key, unifiedSwapStorage, unifiedChainEvents, chainInterface, pricing, this._tokens[chainId], versions, versionedContracts, this._bitcoinRpc, lpApi, {
                 getRequestTimeout: this.options.getRequestTimeout,
                 postRequestTimeout: this.options.postRequestTimeout,
                 saveUninitializedSwaps: this.options.saveUninitializedSwaps,
                 bitcoinNetwork: this._btcNetwork
             });
-            wrappers[SwapType_1.SwapType.TRUSTED_FROM_BTCLN] = new LnForGasWrapper_1.LnForGasWrapper(key, unifiedSwapStorage, unifiedChainEvents, chainInterface, pricing, this._tokens[chainId], {
+            wrappers[SwapType_1.SwapType.TRUSTED_FROM_BTCLN] = new LnForGasWrapper_1.LnForGasWrapper(key, unifiedSwapStorage, unifiedChainEvents, chainInterface, pricing, this._tokens[chainId], lpApi, {
                 getRequestTimeout: this.options.getRequestTimeout,
                 postRequestTimeout: this.options.postRequestTimeout,
                 saveUninitializedSwaps: this.options.saveUninitializedSwaps,
             });
-            wrappers[SwapType_1.SwapType.TRUSTED_FROM_BTC] = new OnchainForGasWrapper_1.OnchainForGasWrapper(key, unifiedSwapStorage, unifiedChainEvents, chainInterface, pricing, this._tokens[chainId], bitcoinRpc, {
+            wrappers[SwapType_1.SwapType.TRUSTED_FROM_BTC] = new OnchainForGasWrapper_1.OnchainForGasWrapper(key, unifiedSwapStorage, unifiedChainEvents, chainInterface, pricing, this._tokens[chainId], bitcoinRpc, lpApi, {
                 getRequestTimeout: this.options.getRequestTimeout,
                 postRequestTimeout: this.options.postRequestTimeout,
                 saveUninitializedSwaps: this.options.saveUninitializedSwaps,
@@ -154,7 +160,7 @@ class Swapper extends events_1.EventEmitter {
             });
             // This is gated on the default version of the contracts
             if (spvVaultContract != null) {
-                wrappers[SwapType_1.SwapType.SPV_VAULT_FROM_BTC] = new SpvFromBTCWrapper_1.SpvFromBTCWrapper(key, unifiedSwapStorage, unifiedChainEvents, chainInterface, pricing, this._tokens[chainId], versions, versionedContracts, bitcoinRpc, {
+                wrappers[SwapType_1.SwapType.SPV_VAULT_FROM_BTC] = new SpvFromBTCWrapper_1.SpvFromBTCWrapper(key, unifiedSwapStorage, unifiedChainEvents, chainInterface, pricing, this._tokens[chainId], versions, versionedContracts, bitcoinRpc, lpApi, {
                     getRequestTimeout: this.options.getRequestTimeout,
                     postRequestTimeout: this.options.postRequestTimeout,
                     saveUninitializedSwaps: this.options.saveUninitializedSwaps,
@@ -163,7 +169,7 @@ class Swapper extends events_1.EventEmitter {
             }
             // This is gated on the default version of the contracts
             if (swapContract.supportsInitWithoutClaimer) {
-                wrappers[SwapType_1.SwapType.FROM_BTCLN_AUTO] = new FromBTCLNAutoWrapper_1.FromBTCLNAutoWrapper(key, unifiedSwapStorage, unifiedChainEvents, chainInterface, pricing, this._tokens[chainId], versions, lightningApi, this.messenger, {
+                wrappers[SwapType_1.SwapType.FROM_BTCLN_AUTO] = new FromBTCLNAutoWrapper_1.FromBTCLNAutoWrapper(key, unifiedSwapStorage, unifiedChainEvents, chainInterface, pricing, this._tokens[chainId], versions, lightningApi, this.messenger, lpApi, {
                     getRequestTimeout: this.options.getRequestTimeout,
                     postRequestTimeout: this.options.postRequestTimeout,
                     saveUninitializedSwaps: this.options.saveUninitializedSwaps,
@@ -190,10 +196,10 @@ class Swapper extends events_1.EventEmitter {
         });
         const contracts = (0, Utils_1.objectMap)(chainsData, (data) => data.versions ?? { [data.defaultVersion ?? "v1"]: { swapContract: data.swapContract, spvVaultContract: data.spvVaultContract } });
         if (options.intermediaryUrl != null) {
-            this.intermediaryDiscovery = new IntermediaryDiscovery_1.IntermediaryDiscovery(contracts, options.registryUrl, Array.isArray(options.intermediaryUrl) ? options.intermediaryUrl : [options.intermediaryUrl], options.getRequestTimeout);
+            this.intermediaryDiscovery = new IntermediaryDiscovery_1.IntermediaryDiscovery(contracts, lpApi, options.registryUrl, Array.isArray(options.intermediaryUrl) ? options.intermediaryUrl : [options.intermediaryUrl], options.getRequestTimeout);
         }
         else {
-            this.intermediaryDiscovery = new IntermediaryDiscovery_1.IntermediaryDiscovery(contracts, options.registryUrl, undefined, options.getRequestTimeout);
+            this.intermediaryDiscovery = new IntermediaryDiscovery_1.IntermediaryDiscovery(contracts, lpApi, options.registryUrl, undefined, options.getRequestTimeout);
         }
         this.intermediaryDiscovery.on("removed", (intermediaries) => {
             this.emit("lpsRemoved", intermediaries);
@@ -203,7 +209,7 @@ class Swapper extends events_1.EventEmitter {
         });
     }
     async _init() {
-        this.logger.debug("init(): Initializing swapper...");
+        this.logger.debug("init(): Initializing swapper");
         const abortController = new AbortController();
         const promises = [];
         let automaticClockDriftCorrectionPromise = undefined;
@@ -271,8 +277,7 @@ class Swapper extends events_1.EventEmitter {
                         return swap;
                     });
                 }
-                if (!this.options.noEvents)
-                    await unifiedChainEvents.start();
+                await unifiedChainEvents.start(this.options.noEvents);
                 this.logger.debug("init(): Intialized events: " + chainIdentifier);
                 for (let key in wrappers) {
                     // this.logger.debug("init(): Initializing "+SwapType[key]+": "+chainIdentifier);
@@ -307,6 +312,12 @@ class Swapper extends events_1.EventEmitter {
             throw e;
         }
     }
+    /**
+     * Whether the SDK is initialized (after {@link init} is called)
+     */
+    isInitialized() {
+        return this.initialized;
+    }
     /**
      * Stops listening for onchain events and closes this Swapper instance
      */
@@ -834,6 +845,10 @@ class Swapper extends events_1.EventEmitter {
      * @param options Options for the swap
      */
     swap(_srcToken, _dstToken, _amount, exactIn, src, dst, options) {
+        if (typeof (src) === "string")
+            src = this.Utils.stripAddress(src);
+        if (typeof (dst) === "string")
+            dst = this.Utils.stripAddress(dst);
         const srcToken = typeof (_srcToken) === "string" ? this.getToken(_srcToken) : _srcToken;
         const dstToken = typeof (_dstToken) === "string" ? this.getToken(_dstToken) : _dstToken;
         const amount = _amount == null ? null : (typeof (_amount) === "bigint" ? _amount : (0, Utils_1.fromDecimal)(_amount, exactIn ? srcToken.decimals : dstToken.decimals));
@@ -979,7 +994,7 @@ class Swapper extends events_1.EventEmitter {
             return await unifiedSwapStorage.query([queryParams], reviver);
         }
     }
-    async getActionableSwaps(chainId, signer) {
+    async getPendingSwaps(chainId, signer) {
         if (chainId == null) {
             const res = await Promise.all(Object.keys(this._chains).map((chainId) => {
                 const { unifiedSwapStorage, reviver, wrappers } = this._chains[chainId];
@@ -994,7 +1009,7 @@ class Swapper extends events_1.EventEmitter {
                 }
                 return unifiedSwapStorage.query(queryParams, reviver);
             }));
-            return res.flat().filter(swap => swap.requiresAction());
+            return res.flat();
         }
         else {
             const { unifiedSwapStorage, reviver, wrappers } = this._chains[chainId];
@@ -1007,7 +1022,15 @@ class Swapper extends events_1.EventEmitter {
                 swapTypeQueryParams.push({ key: "state", value: wrapper._pendingSwapStates });
                 queryParams.push(swapTypeQueryParams);
             }
-            return (await unifiedSwapStorage.query(queryParams, reviver)).filter(swap => swap.requiresAction());
+            return await unifiedSwapStorage.query(queryParams, reviver);
+        }
+    }
+    async getActionableSwaps(chainId, signer) {
+        if (chainId == null) {
+            return (await this.getPendingSwaps()).filter(swap => swap.requiresAction());
+        }
+        else {
+            return (await this.getPendingSwaps(chainId, signer)).filter(swap => swap.requiresAction());
         }
     }
     async getRefundableSwaps(chainId, signer) {
@@ -1189,8 +1212,8 @@ class Swapper extends events_1.EventEmitter {
             removeSwaps.push(...result.removeSwaps);
         }
         this.logger.debug("_syncSwaps(): Done syncing " + swaps.length + " swaps, saving " + changedSwaps.length + " changed swaps, removing " + removeSwaps.length + " swaps!");
-        await unifiedSwapStorage.saveAll(changedSwaps);
-        await unifiedSwapStorage.removeAll(removeSwaps);
+        await unifiedSwapStorage.saveAll(changedSwaps, true);
+        await unifiedSwapStorage.removeAll(removeSwaps, true);
         changedSwaps.forEach(swap => swap._emitEvent());
         removeSwaps.forEach(swap => swap._emitEvent());
     }
@@ -1244,6 +1267,19 @@ class Swapper extends events_1.EventEmitter {
             await this.syncSwapsForChain(chainId, signer);
         }
     }
+    /**
+     * When the swapper is initiated with the `noEvents` config this function allows you to manually poll for on-chain
+     *  events. It returns an events cursor which you should save and pass to the next call to the `poll()` function.
+     *
+     * @param chainId Chain for which to poll the chain events listener for
+     * @param lastEventCursorState Event cursor state returned from the last call to the `poll()` function
+     */
+    async _pollChainEvents(chainId, lastEventCursorState) {
+        const chain = this._chains[chainId];
+        if (chain == null)
+            throw new Error(`Invalid chain id ${chainId}!`);
+        return chain.unifiedChainEvents.poll(lastEventCursorState);
+    }
     /**
      * Recovers swaps from on-chain historical data.
      *

package/dist/swapper/SwapperUtils.d.ts

@@ -100,6 +100,14 @@ export declare class SwapperUtils<T extends MultiChain> {
         max?: TokenAmount;
         amount?: TokenAmount;
     } | null;
+    /**
+     * Strips the URL encoding around `bitcoin:` and `lightning:` addresses, leaving just the raw address
+     *
+     * @param addressString Address to strip
+     *
+     * @returns Raw clean address
+     */
+    stripAddress(addressString: string): string;
     /**
      * Returns a random PSBT that can be used for fee estimation for SPV vault (UTXO-controlled vault) based swaps
      *  {@link SwapType.SPV_VAULT_FROM_BTC}, the last output (the LP output) is omitted to allow for coinselection
@@ -151,11 +159,11 @@ export declare class SwapperUtils<T extends MultiChain> {
      */
     randomSigner<ChainIdentifier extends ChainIds<T>>(chainIdentifier: ChainIdentifier): T[ChainIdentifier]["Signer"];
     /**
-     * Returns a random address for a given smart chain
+     * Returns a random address for a given smart chain or bitcoin
      *
      * @param chainIdentifier
      */
-    randomAddress<ChainIdentifier extends ChainIds<T>>(chainIdentifier: ChainIdentifier): string;
+    randomAddress<ChainIdentifier extends ChainIds<T>>(chainIdentifier: ChainIdentifier | "BITCOIN"): string;
     /**
      * Signs and broadcasts the supplied smart chain transaction
      *
@@ -175,6 +183,14 @@ export declare class SwapperUtils<T extends MultiChain> {
      * @param onBeforePublish Callback invoked before a transaction is sent (invoked for every transaction to be sent)
      */
     sendSignedAndConfirm<ChainIdentifier extends ChainIds<T>>(chainIdentifier: ChainIdentifier, txs: T[ChainIdentifier]["SignedTXType"][], abortSignal?: AbortSignal, onBeforePublish?: (txId: string, rawTx: string) => Promise<void>): Promise<string[]>;
+    /**
+     * Prepares a set of unsigned transactions for signing, by adding required nonces or recent blockhashes, might
+     *  also add hints of account deployment on e.g. Starknet
+     *
+     * @param chainIdentifier A chain for which to prepare the txs
+     * @param txs Transactions to prepare
+     */
+    prepareUnsignedTransactions<ChainIdentifier extends ChainIds<T>>(chainIdentifier: ChainIdentifier, txs: T[ChainIdentifier]["TX"][]): Promise<T[ChainIdentifier]["TX"][]>;
     /**
      * Serializes an unsigned smart chain transaction
      *

package/dist/swapper/SwapperUtils.js

@@ -284,6 +284,22 @@ class SwapperUtils {
             return resultLightningInvoice;
         return this.parseSmartchainAddress(addressString);
     }
+    /**
+     * Strips the URL encoding around `bitcoin:` and `lightning:` addresses, leaving just the raw address
+     *
+     * @param addressString Address to strip
+     *
+     * @returns Raw clean address
+     */
+    stripAddress(addressString) {
+        if (addressString.startsWith("lightning:") || addressString.startsWith("bitcoin:")) {
+            addressString = addressString.substring(addressString.indexOf(":") + 1);
+            const delimeterIndex = addressString.indexOf("?");
+            if (delimeterIndex !== -1)
+                addressString = addressString.substring(0, delimeterIndex);
+        }
+        return addressString;
+    }
     /**
      * Returns a random PSBT that can be used for fee estimation for SPV vault (UTXO-controlled vault) based swaps
      *  {@link SwapType.SPV_VAULT_FROM_BTC}, the last output (the LP output) is omitted to allow for coinselection
@@ -397,11 +413,18 @@ class SwapperUtils {
         return this.root._chains[chainIdentifier].chainInterface.randomSigner();
     }
     /**
-     * Returns a random address for a given smart chain
+     * Returns a random address for a given smart chain or bitcoin
      *
      * @param chainIdentifier
      */
     randomAddress(chainIdentifier) {
+        if (chainIdentifier === "BITCOIN") {
+            // Return random p2wkh address
+            return (0, btc_signer_1.Address)(this.bitcoinNetwork).encode({
+                type: "wpkh",
+                hash: (0, Utils_1.randomBytes)(20)
+            });
+        }
         if (this.root._chains[chainIdentifier] == null)
             throw new Error("Invalid chain identifier! Unknown chain: " + chainIdentifier);
         return this.root._chains[chainIdentifier].chainInterface.randomAddress();
@@ -433,6 +456,21 @@ class SwapperUtils {
             throw new Error("Invalid chain identifier! Unknown chain: " + chainIdentifier);
         return this.root._chains[chainIdentifier].chainInterface.sendSignedAndConfirm(txs, true, abortSignal, false, onBeforePublish);
     }
+    /**
+     * Prepares a set of unsigned transactions for signing, by adding required nonces or recent blockhashes, might
+     *  also add hints of account deployment on e.g. Starknet
+     *
+     * @param chainIdentifier A chain for which to prepare the txs
+     * @param txs Transactions to prepare
+     */
+    prepareUnsignedTransactions(chainIdentifier, txs) {
+        if (this.root._chains[chainIdentifier] == null)
+            throw new Error("Invalid chain identifier! Unknown chain: " + chainIdentifier);
+        const chainInterface = this.root._chains[chainIdentifier].chainInterface;
+        if (chainInterface.prepareTxs == null)
+            throw new Error("Chain doesn't support tx preparation, chainId: " + chainIdentifier);
+        return chainInterface.prepareTxs(txs);
+    }
     /**
      * Serializes an unsigned smart chain transaction
      *

package/dist/swaps/ISwap.d.ts

@@ -13,6 +13,7 @@ import { SwapExecutionAction } from "../types/SwapExecutionAction";
 import { LoggerType } from "../utils/Logger";
 import { PriceInfoType } from "../types/PriceInfoType";
 import { SwapStateInfo } from "../types/SwapStateInfo";
+import { SwapExecutionStep } from "../types/SwapExecutionStep";
 /**
  * Initialization data for creating a swap
  *
@@ -124,6 +125,12 @@ export declare abstract class ISwap<T extends ChainType = ChainType, D extends S
      * @internal
      */
     _contractVersion?: string;
+    /**
+     * Storage specific metadata that can be used for e.g. optimistic concurrency
+     *
+     * @internal
+     */
+    _meta?: any;
     /**
      * Event emitter emitting `"swapState"` event when swap's state changes
      */
@@ -163,12 +170,6 @@ export declare abstract class ISwap<T extends ChainType = ChainType, D extends S
      * @internal
      */
     protected waitTillState(targetState: S, type?: "eq" | "gte" | "neq", abortSignal?: AbortSignal): Promise<void>;
-    /**
-     * Returns a list of steps or transactions required to finish and settle the swap
-     *
-     * @param options Additional options for executing the swap
-     */
-    abstract txsExecute(options?: any): Promise<SwapExecutionAction<T>[]>;
     /**
      * Executes the swap with the provided wallet, the exact arguments for this functions differ for various swap
      *  types. Check the `execute()` function signature in the respective swap class to see the required arguments.
@@ -185,6 +186,12 @@ export declare abstract class ISwap<T extends ChainType = ChainType, D extends S
      * @internal
      */
     protected tryRecomputeSwapPrice(): void;
+    /**
+     * Returns the specific state along with the human-readable description of that state
+     *
+     * @internal
+     */
+    protected _getStateInfo(state: S): SwapStateInfo<S>;
     /**
      * Re-fetches & revalidates the price data based on the current market prices
      */
@@ -209,6 +216,13 @@ export declare abstract class ISwap<T extends ChainType = ChainType, D extends S
      * @internal
      */
     protected checkSigner(signer: T["Signer"] | string): void;
+    /**
+     * Await and prepares a list of passed transactions
+     *
+     * @param txsPromise
+     * @internal
+     */
+    protected prepareTransactions(txsPromise: Promise<T["TX"][]>): Promise<T["TX"][]>;
     /**
      * Returns an escrow hash of the swap
      *
@@ -312,10 +326,57 @@ export declare abstract class ISwap<T extends ChainType = ChainType, D extends S
      */
     getStateInfo(): SwapStateInfo<S>;
     /**
-     * Returns a state-dependent set of actions for the user to execute, or empty array if there is currently
-     *  no action required from the user to execute.
+     * Returns a current state-dependent action for the user to execute, or `undefined` if there is no more action
+     *  required for this swap - this means that the swap is probably finished (either expired, failed or settled).
+     *
+     * @param options Optional options argument for the additional action context (i.e. passing bitcoin wallet info to
+     *  get funded PSBTs or passing the externally-generated swap secret), see the actual type in the respective swap
+     *  classes
+     */
+    abstract getExecutionAction(options?: any): Promise<SwapExecutionAction | undefined>;
+    /**
+     * Returns a list of execution steps the user has to go through for a given swap, to see the possible execution
+     *  steps check out {@link SwapExecutionStep}.
+     *
+     * @param options Optional options argument for the additional steps context (i.e. automatic settlement timeout),
+     *  see the actual type in the respective swap classes
+     */
+    abstract getExecutionSteps(options?: any): Promise<SwapExecutionStep[]>;
+    /**
+     * Returns the current action and the full execution steps for a given swap. Prefer this to calling
+     *  {@link getExecutionSteps} and {@link getExecutionAction} separately - if called sequentially they might
+     *  return the respective steps/actions in different states if you hit the state transition boundary.
+     *
+     * @param options Optional options argument for the additional execution status context, see the actual type in
+     *  the respective swap classes
+     */
+    abstract getExecutionStatus(options?: {
+        skipBuildingAction?: boolean;
+    } & any): Promise<{
+        steps: SwapExecutionStep[];
+        currentAction: SwapExecutionAction | undefined;
+        stateInfo: SwapStateInfo<S>;
+    }>;
+    /**
+     * Submits signed transactions obtained from the execution action back to the swap.
+     *
+     * @remarks This endpoint will also wait till the submitted transactions are confirmed (on a smart-chain side)
+     *  and till the swap state change is observed from the authoritative chain/intermediary state.
+     *
+     *  If invalid transactions are submitted, i.e. sending a simple noop or transfer transaction instead of the
+     *  expected tx, this call may wait indefinitely unless aborted via the AbortSignal.
+     *
+     * @param txs Signed transactions
+     * @param abortSignal Abort signal
+     * @param requiredStates Optional list of states that the swap has to be in for the transactions to be
+     *  submitted, else throws
+     * @param idempotent Whether the tx submission should be handled idempotently, meaning if any of the supplied
+     *  transactions are already processed as e.g. init, claim, refund or execution transactions the function just
+     *  returns these transaction IDs without actually submitting them
+     *
+     * @internal
      */
-    abstract getCurrentActions(): Promise<SwapExecutionAction<T>[]>;
+    abstract _submitExecutionTransactions(txs: (T["SignedTXType"] | string | any)[], abortSignal?: AbortSignal, requiredStates?: S[], idempotent?: boolean): Promise<string[]>;
     /**
      * Returns output amount of the swap, user receives this much
      */

package/dist/swaps/ISwap.js

@@ -99,6 +99,7 @@ class ISwap {
             this.createdAt = swapInitOrObj.createdAt ?? swapInitOrObj.expiry;
             this._randomNonce = swapInitOrObj.randomNonce;
             this._contractVersion = swapInitOrObj.contractVersion;
+            this._meta = swapInitOrObj._meta;
         }
         if (this.version !== this.currentVersion) {
             this.upgradeVersion();
@@ -159,6 +160,18 @@ class ISwap {
             }
         }
     }
+    /**
+     * Returns the specific state along with the human-readable description of that state
+     *
+     * @internal
+     */
+    _getStateInfo(state) {
+        return {
+            state: state,
+            name: this.swapStateName(state),
+            description: this.swapStateDescription[state]
+        };
+    }
     /**
      * Re-fetches & revalidates the price data based on the current market prices
      */
@@ -225,6 +238,18 @@ class ISwap {
         if ((typeof (signer) === "string" ? signer : signer.getAddress()) !== this._getInitiator())
             throw new Error("Invalid signer provided!");
     }
+    /**
+     * Await and prepares a list of passed transactions
+     *
+     * @param txsPromise
+     * @internal
+     */
+    async prepareTransactions(txsPromise) {
+        const txs = await txsPromise;
+        if (this.wrapper._chain.prepareTxs == null)
+            return txs;
+        return await this.wrapper._chain.prepareTxs(txs);
+    }
     /**
      * Sets this swap as initiated
      * @internal
@@ -269,11 +294,7 @@ class ISwap {
      * Returns the current state of the swap along with the human-readable description of the state
      */
     getStateInfo() {
-        return {
-            state: this._state,
-            name: this.swapStateName(this._state),
-            description: this.swapStateDescription[this._state]
-        };
+        return this._getStateInfo(this._state);
     }
     //////////////////////////////
     //// Storage
@@ -331,7 +352,8 @@ class ISwap {
             exactIn: this.exactIn,
             createdAt: this.createdAt,
             randomNonce: this._randomNonce,
-            contractVersion: this._contractVersion
+            contractVersion: this._contractVersion,
+            _meta: this._meta
         };
     }
     //////////////////////////////

package/dist/swaps/ISwapWrapper.d.ts

@@ -9,6 +9,7 @@ import { SwapType } from "../enums/SwapType";
 import { UnifiedSwapStorage } from "../storage/UnifiedSwapStorage";
 import { SCToken } from "../types/Token";
 import { PriceInfoType } from "../types/PriceInfoType";
+import { IntermediaryAPI } from "../intermediaries/apis/IntermediaryAPI";
 export declare const DEFAULT_MAX_PARALLEL_SWAP_TICKS = 50;
 export declare const DEFAULT_MAX_PARALLEL_SWAP_SYNCS = 50;
 /**
@@ -132,6 +133,11 @@ export declare abstract class ISwapWrapper<T extends ChainType, D extends SwapTy
     readonly _tokens: {
         [tokenAddress: string]: SCToken<T["ChainId"]>;
     };
+    /**
+     * LP API Used to communicate with the LPs
+     * @internal
+     */
+    readonly _lpApi: IntermediaryAPI;
     /**
      * Chain identifier string of this wrapper
      */
@@ -142,7 +148,7 @@ export declare abstract class ISwapWrapper<T extends ChainType, D extends SwapTy
     readonly events: EventEmitter<{
         swapState: [D["Swap"]];
     }>;
-    constructor(chainIdentifier: T["ChainId"], unifiedStorage: UnifiedSwapStorage<T>, unifiedChainEvents: UnifiedSwapEventListener<T>, chain: T["ChainInterface"], prices: ISwapPrice, tokens: WrapperCtorTokens, options: O, events?: EventEmitter<{
+    constructor(chainIdentifier: T["ChainId"], unifiedStorage: UnifiedSwapStorage<T>, unifiedChainEvents: UnifiedSwapEventListener<T>, chain: T["ChainInterface"], prices: ISwapPrice, tokens: WrapperCtorTokens, lpApi: IntermediaryAPI, options: O, events?: EventEmitter<{
         swapState: [ISwap];
     }>);
     /**
@@ -282,4 +288,8 @@ export declare abstract class ISwapWrapper<T extends ChainType, D extends SwapTy
      * @internal
      */
     _getPendingSwap(id: string): D["Swap"] | null;
+    /**
+     * @internal
+     */
+    _getSignerAddress(signer?: string | T["Signer"] | T["NativeSigner"]): Promise<string | undefined>;
 }