@atomiqlabs/sdk 8.7.7 → 8.9.0

package/dist/swapper/Swapper.js

@@ -35,6 +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
  *
@@ -87,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);
         };
@@ -117,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,
@@ -153,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,
@@ -162,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,
@@ -189,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);
@@ -202,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;
@@ -270,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);
@@ -306,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
      */
@@ -343,7 +355,7 @@ class Swapper extends events_1.EventEmitter {
             throw new Error("Invalid chain identifier! Unknown chain: " + chainIdentifier);
         let candidates;
         const inBtc = swapType === SwapType_1.SwapType.TO_BTCLN || swapType === SwapType_1.SwapType.TO_BTC ? !amountData.exactIn : amountData.exactIn;
-        if (!inBtc) {
+        if (!inBtc || amountData.amount == null) {
             //Get candidates not based on the amount
             candidates = this.intermediaryDiscovery.getSwapCandidates(chainIdentifier, swapType, amountData.token);
         }
@@ -355,7 +367,7 @@ class Swapper extends events_1.EventEmitter {
             this.logger.warn("createSwap(): No valid intermediary found to execute the swap with, reloading intermediary database...");
             await this.intermediaryDiscovery.reloadIntermediaries();
             swapLimitsChanged = true;
-            if (!inBtc) {
+            if (!inBtc || amountData.amount == null) {
                 //Get candidates not based on the amount
                 candidates = this.intermediaryDiscovery.getSwapCandidates(chainIdentifier, swapType, amountData.token);
             }
@@ -441,10 +453,12 @@ class Swapper extends events_1.EventEmitter {
                         }
                         if (min != null && max != null) {
                             let msg = "Swap amount too high or too low! Try swapping a different amount.";
-                            if (min > amountData.amount)
-                                msg = "Swap amount too low! Try swapping a higher amount.";
-                            if (max < amountData.amount)
-                                msg = "Swap amount too high! Try swapping a lower amount.";
+                            if (amountData.amount != null) {
+                                if (min > amountData.amount)
+                                    msg = "Swap amount too low! Try swapping a higher amount.";
+                                if (max < amountData.amount)
+                                    msg = "Swap amount too high! Try swapping a lower amount.";
+                            }
                             reject(new RequestError_1.OutOfBoundsError(msg, 400, min, max));
                             return;
                         }
@@ -612,7 +626,7 @@ class Swapper extends events_1.EventEmitter {
             throw new Error("Invalid " + chainIdentifier + " address");
         recipient = this._chains[chainIdentifier].chainInterface.normalizeAddress(recipient);
         const amountData = {
-            amount,
+            amount: amount ?? undefined,
             token: tokenAddress,
             exactIn: !exactOut
         };
@@ -831,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));
@@ -907,6 +925,59 @@ class Swapper extends events_1.EventEmitter {
         }
         throw new Error("Unsupported swap type");
     }
+    /**
+     * A helper function to sweep all the funds from a given wallet in a single swap, after getting the quote you can
+     *  execute the swap by passing the returned `feeRate` and `utxos` to the {@link SpvFromBTCSwap.execute},
+     *  {@link SpvFromBTCSwap.getFundedPsbt} or {@link SpvFromBTCSwap.sendBitcoinTransaction} functions along
+     *  with `spendFully=true`.
+     *
+     * @example
+     * Create the swap first using this function
+     * ```ts
+     * const {swap, utxos, btcFeeRate} = await swapper.sweepBitcoinWallet(wallet, Tokens.CITREA.CBTC, dstAddress);
+     * ```
+     * Then execute it using one of these execution paths - ensure that you supply the returned `utxos`, `btcFeeRate`
+     *  params and also set `spendFully` to `true`!
+     *
+     * a) Execute and pass the returned utxos and btcFeeRate:
+     * ```ts
+     * await swap.execute(wallet, undefined, {feeRate: btcFeeRate, utxos: utxos, spendFully: true});
+     * ```
+     *
+     * b) Get funded PSBT to sign externally:
+     * ```ts
+     * const {psbt, psbtHex, psbtBase64, signInputs} = await swap.getFundedPsbt(wallet, btcFeeRate, undefined, utxos, true);
+     * // Sign the psbt at the specified signInputs indices
+     * const signedPsbt = ...;
+     * // Then submit back to the SDK
+     * await swap.submitPsbt(signedPsbt);
+     * ```
+     *
+     * c) Only sign and send the signed PSBT with the provided wallet:
+     * ```ts
+     * await swap.sendBitcoinTransaction(wallet, btcFeeRate, utxos, true);
+     * ```
+     */
+    async sweepBitcoinWallet(srcWallet, _dstToken, dstAddress, options) {
+        const dstToken = typeof (_dstToken) === "string" ? this.getToken(_dstToken) : _dstToken;
+        if (!(0, Token_1.isSCToken)(dstToken))
+            throw new Error("Destination token must be a smart chain token!");
+        const wallet = (0, BitcoinWalletUtils_1.toBitcoinWallet)(srcWallet, this._bitcoinRpc, this.bitcoinNetwork);
+        if (wallet.getUtxoPool == null)
+            throw new Error("Wallet needs to support the `getUtxoPool()` function!");
+        const walletUtxosPromise = wallet.getUtxoPool();
+        const bitcoinFeeRatePromise = options?.bitcoinFeeRate ?? wallet.getFeeRate();
+        const swap = await this.createFromBTCSwapNew(dstToken.chainId, dstAddress, dstToken.address, null, false, undefined, {
+            ...options,
+            sourceWalletUtxos: walletUtxosPromise,
+            bitcoinFeeRate: bitcoinFeeRatePromise
+        });
+        return {
+            swap,
+            utxos: await walletUtxosPromise,
+            btcFeeRate: Math.max(swap.minimumBtcFeeRate, await bitcoinFeeRatePromise)
+        };
+    }
     async getAllSwaps(chainId, signer) {
         const queryParams = [];
         if (signer != null)
@@ -923,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];
@@ -938,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];
@@ -951,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) {
@@ -1133,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());
     }
@@ -1188,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>;
 }