@atomiqlabs/sdk 8.7.7 → 8.9.0

package/src/storage/IUnifiedStorage.ts

@@ -16,11 +16,12 @@ export type QueryParams = {
 };
 
 /**
- * Base type for stored objects, every storage object MUST have an `id` field
+ * Base type for stored objects, every storage object MUST have an `id` field. The object might also specify a `_meta`
+ *  field which gets carried to the delete/save operations (and can be used to implement optimistic concurrency)
  *
  * @category Storage
  */
-export type UnifiedStoredObject = {id: string} & any;
+export type UnifiedStoredObject = {id: string, _meta?: any} & any;
 
 /**
  * Defines simple indexes (for queries that use a single key)
@@ -64,32 +65,72 @@ export interface IUnifiedStorage<I extends UnifiedStorageIndexes, C extends Unif
      *  - [[condition1, condition2]] - returns all rows where condition1 AND condition2 is met
      *  - [[condition1], [condition2]] - returns all rows where condition1 OR condition2 is met
      *  - [[condition1, condition2], [condition3]] - returns all rows where (condition1 AND condition2) OR condition3 is met
+     *
+     * You can also add an optional `_meta` field in the returned unified storage object which gets attached to that
+     *  returned object and will be present for subsequent saves and removal of this object, if you specify the `_meta`
+     *  field here, you need to explicitly handle it in the all the saving and remove functions and not simply serialize
+     *  it into the storage
+     *
      * @param params
      */
     query(params: Array<Array<QueryParams>>): Promise<Array<UnifiedStoredObject>>;
 
     /**
      * Saves an object to storage, updating indexes as needed
+     *
+     * If the object contains a `_meta` field, this will be also present in the to-be-saved value, to mutate the `_meta`
+     *  field of the object that is saved, you can mutate the `_meta` field directly on the passed value, which then
+     *  gets reflected automatically in the existing object. The mutated `_meta` field is copied even if the function
+     *  throws, hence the implementations must be careful with setting the `_meta` field on the still in-flight requests
+     *  that might fail.
+     *
      * @param value Object to save (must have an id property)
      */
     save(value: UnifiedStoredObject): Promise<void>;
 
     /**
      * Saves multiple objects to storage in a batch operation
+     *
+     * If the objects contain a `_meta` field, this will be also present in the to-be-saved values, to mutate the `_meta`
+     *  field of the objects that are saved, you can mutate the `_meta` field directly on the passed values, which then
+     *  gets reflected automatically in the existing objects. The mutated `_meta` field is copied even if the function
+     *  throws, hence the implementations must be careful with setting the `_meta` field on the still in-flight requests
+     *  that might fail.
+     *
      * @param value Array of objects to save
+     * @param lenient In lenient mode the persistency layer doesn't throw on individual swap failures due to
+     *  optimistic concurrency, or other (implementation specific), this flag is to be used when the saving of the swap
+     *  isn't mission-critical for executing next steps (e.g. in tick or sync loops)
      */
-    saveAll(value: UnifiedStoredObject[]): Promise<void>;
+    saveAll(value: UnifiedStoredObject[], lenient?: boolean): Promise<void>;
 
     /**
      * Removes an object from storage
+     *
+     * If the object contains a `_meta` field, this will be also present in the to-be-removed value, to mutate the `_meta`
+     *  field of the object that is saved, you can mutate the `_meta` field directly on the passed value, which then
+     *  gets reflected automatically in the existing object. The mutated `_meta` field is copied even if the function
+     *  throws, hence the implementations must be careful with setting the `_meta` field on the still in-flight requests
+     *  that might fail.
+     *
      * @param value Object to remove (must have an id property)
      */
     remove(value: UnifiedStoredObject): Promise<void>;
 
     /**
      * Removes multiple objects from storage in a batch operation
+     *
+     * If the objects contain a `_meta` field, this will be also present in the to-be-removed values, to mutate the `_meta`
+     *  field of the objects that are saved, you can mutate the `_meta` field directly on the passed values, which then
+     *  gets reflected automatically in the existing objects. The mutated `_meta` field is copied even if the function
+     *  throws, hence the implementations must be careful with setting the `_meta` field on the still in-flight requests
+     *  that might fail.
+     *
      * @param value Array of objects to remove
+     * @param lenient In lenient mode the persistency layer doesn't throw on individual swap failures due to
+     *  optimistic concurrency, or other (implementation specific), this flag is to be used when the saving of the swap
+     *  isn't mission-critical for executing next steps (e.g. in tick or sync loops)
      */
-    removeAll(value: UnifiedStoredObject[]): Promise<void>;
+    removeAll(value: UnifiedStoredObject[], lenient?: boolean): Promise<void>;
 
 }

package/src/storage/UnifiedSwapStorage.ts

@@ -104,18 +104,35 @@ export class UnifiedSwapStorage<T extends ChainType> {
      */
     async save<S extends ISwap<T>>(value: S): Promise<void> {
         if(!this.noWeakRefMap) this.weakRefCache.set(value.getId(), new WeakRef<ISwap<T>>(value));
-        await this.storage.save(value.serialize());
+        const serialized = value.serialize();
+        try {
+            await this.storage.save(serialized);
+        } finally {
+            value._meta = serialized._meta;
+        }
         value._persisted = true;
     }
 
     /**
      * Saves multiple swaps to storage in a batch operation
      * @param values Array of swaps to save
+     * @param lenient In lenient mode the underlying persistent layer doesn't throw on individual swap failures due to
+     *  optimistic concurrency, or other (implementation specific), this flag is to be used when the saving of the swap
+     *  isn't mission-critical for executing next steps (e.g. in tick or sync loops)
      */
-    async saveAll<S extends ISwap<T>>(values: S[]): Promise<void> {
+    async saveAll<S extends ISwap<T>>(values: S[], lenient?: boolean): Promise<void> {
         if(!this.noWeakRefMap) values.forEach(value => this.weakRefCache.set(value.getId(), new WeakRef<ISwap<T>>(value)));
-        await this.storage.saveAll(values.map(obj => obj.serialize()));
-        values.forEach(value => value._persisted = true);
+        const serialized = values.map(obj => obj.serialize());
+        try {
+            await this.storage.saveAll(serialized, lenient);
+        } finally {
+            values.forEach((value, index) => {
+                value._meta = serialized[index]._meta;
+            });
+        }
+        values.forEach((value) => {
+            value._persisted = true;
+        });
     }
 
     /**
@@ -124,18 +141,35 @@ export class UnifiedSwapStorage<T extends ChainType> {
      */
     async remove<S extends ISwap<T>>(value: S): Promise<void> {
         if(!this.noWeakRefMap) this.weakRefCache.delete(value.getId());
-        await this.storage.remove(value.serialize());
+        const serialized = value.serialize();
+        try {
+            await this.storage.remove(serialized);
+        } finally {
+            value._meta = serialized._meta;
+        }
         value._persisted = false;
     }
 
     /**
      * Removes multiple swaps from storage in a batch operation
      * @param values Array of swaps to remove
+     * @param lenient In lenient mode the underlying persistent layer doesn't throw on individual swap failures due to
+     *  optimistic concurrency, or other (implementation specific), this flag is to be used when the saving of the swap
+     *  isn't mission-critical for executing next steps (e.g. in tick or sync loops)
      */
-    async removeAll<S extends ISwap<T>>(values: S[]): Promise<void> {
+    async removeAll<S extends ISwap<T>>(values: S[], lenient?: boolean): Promise<void> {
         if(!this.noWeakRefMap) values.forEach(value => this.weakRefCache.delete(value.getId()));
-        await this.storage.removeAll(values.map(obj => obj.serialize()));
-        values.forEach(value => value._persisted = false);
+        const serialized = values.map(obj => obj.serialize());
+        try {
+            await this.storage.removeAll(serialized, lenient);
+        } finally {
+            values.forEach((value, index) => {
+                value._meta = serialized[index]._meta;
+            });
+        }
+        values.forEach((value) => {
+            value._persisted = false;
+        });
     }
 
 }

package/src/swapper/Swapper.ts

@@ -65,6 +65,11 @@ import {NotNever} from "../utils/TypeUtils";
 import {IEscrowSwap} from "../swaps/escrow_swaps/IEscrowSwap";
 import {LightningInvoiceCreateService, isLightningInvoiceCreateService} from "../types/wallets/LightningInvoiceCreateService";
 import {SwapSide} from "../enums/SwapSide";
+import {IntermediaryAPI} from "../intermediaries/apis/IntermediaryAPI";
+import {BitcoinWalletUtxo, BitcoinWalletUtxoBase, IBitcoinWallet} from "../bitcoin/wallet/IBitcoinWallet";
+import {MinimalBitcoinWalletInterface} from "../types/wallets/MinimalBitcoinWalletInterface";
+import {toBitcoinWallet} from "../utils/BitcoinWalletUtils";
+import {getSignedKeyBasedAuthHandler} from "../intermediaries/auth/SignedKeyBasedAuth";
 
 /**
  * Configuration options for the Swapper
@@ -126,8 +131,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,
@@ -157,7 +163,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.
@@ -167,7 +173,14 @@ export type SwapperOptions = {
      * Automatically checks system time on initialize, if the system time drifts too far from the actual time
      *  (as checked from multiple server sources) it adjusts the `Date.now()` function to return proper actual time.
      */
-    automaticClockDriftCorrection?: boolean
+    automaticClockDriftCorrection?: boolean,
+    /**
+     * Used in centralized API deployments to allow higher rate limits from LPs
+     */
+    signedKeyBasedAuth?: {
+        certificate: string,
+        privateKey: string
+    }
 };
 
 /**
@@ -304,6 +317,10 @@ export 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
      */
@@ -359,6 +376,13 @@ export class Swapper<T extends MultiChain> extends EventEmitter<{
             this._tokens[chainId][tokenData.address] = this._tokensByTicker[chainId][tokenData.ticker] = tokenData;
         }
 
+        const lpApi = new IntermediaryAPI(
+            this.options.signedKeyBasedAuth!=null
+                ? getSignedKeyBasedAuthHandler(this.options.signedKeyBasedAuth.certificate, this.options.signedKeyBasedAuth.privateKey)
+                : undefined
+        );
+        this.lpApi = lpApi;
+
         this.swapStateListener = (swap: ISwap) => {
             this.emit("swapState", swap);
         };
@@ -410,6 +434,7 @@ export class Swapper<T extends MultiChain> extends EventEmitter<{
                 pricing,
                 this._tokens[chainId],
                 versions,
+                lpApi,
                 {
                     getRequestTimeout: this.options.getRequestTimeout,
                     postRequestTimeout: this.options.postRequestTimeout,
@@ -425,6 +450,7 @@ export class Swapper<T extends MultiChain> extends EventEmitter<{
                 this._tokens[chainId],
                 versions,
                 this._bitcoinRpc,
+                lpApi,
                 {
                     getRequestTimeout: this.options.getRequestTimeout,
                     postRequestTimeout: this.options.postRequestTimeout,
@@ -441,6 +467,7 @@ export class Swapper<T extends MultiChain> extends EventEmitter<{
                 this._tokens[chainId],
                 versions,
                 lightningApi,
+                lpApi,
                 {
                     getRequestTimeout: this.options.getRequestTimeout,
                     postRequestTimeout: this.options.postRequestTimeout,
@@ -458,6 +485,7 @@ export class Swapper<T extends MultiChain> extends EventEmitter<{
                 versions,
                 versionedContracts,
                 this._bitcoinRpc,
+                lpApi,
                 {
                     getRequestTimeout: this.options.getRequestTimeout,
                     postRequestTimeout: this.options.postRequestTimeout,
@@ -472,6 +500,7 @@ export class Swapper<T extends MultiChain> extends EventEmitter<{
                 chainInterface,
                 pricing,
                 this._tokens[chainId],
+                lpApi,
                 {
                     getRequestTimeout: this.options.getRequestTimeout,
                     postRequestTimeout: this.options.postRequestTimeout,
@@ -486,6 +515,7 @@ export class Swapper<T extends MultiChain> extends EventEmitter<{
                 pricing,
                 this._tokens[chainId],
                 bitcoinRpc,
+                lpApi,
                 {
                     getRequestTimeout: this.options.getRequestTimeout,
                     postRequestTimeout: this.options.postRequestTimeout,
@@ -506,6 +536,7 @@ export class Swapper<T extends MultiChain> extends EventEmitter<{
                     versions,
                     versionedContracts,
                     bitcoinRpc,
+                    lpApi,
                     {
                         getRequestTimeout: this.options.getRequestTimeout,
                         postRequestTimeout: this.options.postRequestTimeout,
@@ -527,6 +558,7 @@ export class Swapper<T extends MultiChain> extends EventEmitter<{
                     versions,
                     lightningApi,
                     this.messenger,
+                    lpApi,
                     {
                         getRequestTimeout: this.options.getRequestTimeout,
                         postRequestTimeout: this.options.postRequestTimeout,
@@ -563,9 +595,9 @@ export class Swapper<T extends MultiChain> extends EventEmitter<{
 
         const contracts = objectMap(chainsData, (data) => data.versions ?? {[data.defaultVersion ?? "v1"]: {swapContract: data.swapContract, spvVaultContract: data.spvVaultContract}});
         if(options.intermediaryUrl!=null) {
-            this.intermediaryDiscovery = new IntermediaryDiscovery(contracts, options.registryUrl, Array.isArray(options.intermediaryUrl) ? options.intermediaryUrl : [options.intermediaryUrl], options.getRequestTimeout);
+            this.intermediaryDiscovery = new IntermediaryDiscovery(contracts, lpApi, options.registryUrl, Array.isArray(options.intermediaryUrl) ? options.intermediaryUrl : [options.intermediaryUrl], options.getRequestTimeout);
         } else {
-            this.intermediaryDiscovery = new IntermediaryDiscovery(contracts, options.registryUrl, undefined, options.getRequestTimeout);
+            this.intermediaryDiscovery = new IntermediaryDiscovery(contracts, lpApi, options.registryUrl, undefined, options.getRequestTimeout);
         }
 
         this.intermediaryDiscovery.on("removed", (intermediaries: Intermediary[]) => {
@@ -578,7 +610,7 @@ export class Swapper<T extends MultiChain> extends EventEmitter<{
     }
 
     private async _init(): Promise<void> {
-        this.logger.debug("init(): Initializing swapper...");
+        this.logger.debug("init(): Initializing swapper");
 
         const abortController = new AbortController();
 
@@ -664,7 +696,7 @@ export class Swapper<T extends MultiChain> extends EventEmitter<{
                     )
                 }
 
-                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) {
@@ -706,6 +738,13 @@ export class Swapper<T extends MultiChain> extends EventEmitter<{
         }
     }
 
+    /**
+     * Whether the SDK is initialized (after {@link init} is called)
+     */
+    isInitialized(): boolean {
+        return this.initialized;
+    }
+
     /**
      * Stops listening for onchain events and closes this Swapper instance
      */
@@ -745,7 +784,7 @@ export class Swapper<T extends MultiChain> extends EventEmitter<{
             quote: Promise<S>,
             intermediary: Intermediary
         }[]>,
-        amountData: AmountData,
+        amountData: { amount?: bigint, token: string, exactIn: boolean },
         swapType: SwapType,
         maxWaitTimeMS: number = 2000
     ): Promise<S> {
@@ -755,7 +794,7 @@ export class Swapper<T extends MultiChain> extends EventEmitter<{
 
         const inBtc: boolean = swapType===SwapType.TO_BTCLN || swapType===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);
         } else {
@@ -769,7 +808,7 @@ export class Swapper<T extends MultiChain> extends EventEmitter<{
             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);
             } else {
@@ -859,8 +898,10 @@ export class Swapper<T extends MultiChain> extends 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 OutOfBoundsError(msg, 400, min, max));
                             return;
                         }
@@ -1102,7 +1143,7 @@ export class Swapper<T extends MultiChain> extends EventEmitter<{
         chainIdentifier: ChainIdentifier,
         recipient: string,
         tokenAddress: string,
-        amount: bigint,
+        amount: bigint | null,
         exactOut: boolean = false,
         additionalParams: Record<string, any> | undefined = this.options.defaultAdditionalParameters,
         options?: SpvFromBTCOptions
@@ -1112,7 +1153,7 @@ export class Swapper<T extends MultiChain> extends EventEmitter<{
         if(!this._chains[chainIdentifier].chainInterface.isValidAddress(recipient, true)) throw new Error("Invalid "+chainIdentifier+" address");
         recipient = this._chains[chainIdentifier].chainInterface.normalizeAddress(recipient);
         const amountData = {
-            amount,
+            amount: amount ?? undefined,
             token: tokenAddress,
             exactIn: !exactOut
         };
@@ -1516,6 +1557,9 @@ export class Swapper<T extends MultiChain> extends EventEmitter<{
         dst: string |  LNURLPay | LightningInvoiceCreateService,
         options?: FromBTCLNOptions | SpvFromBTCOptions | FromBTCOptions | ToBTCOptions | (ToBTCLNOptions & {comment?: string}) | FromBTCLNAutoOptions
     ): Promise<ISwap<T[C]>> {
+        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) as Token<C> : _srcToken;
         const dstToken = typeof(_dstToken)==="string" ? this.getToken(_dstToken) as Token<C> : _dstToken;
         const amount = _amount==null ? null : (typeof(_amount)==="bigint" ? _amount : fromDecimal(_amount, exactIn ? srcToken.decimals : dstToken.decimals));
@@ -1576,6 +1620,73 @@ export class Swapper<T extends MultiChain> extends 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<C extends ChainIds<T>>(
+        srcWallet: IBitcoinWallet | MinimalBitcoinWalletInterface,
+        _dstToken: SCToken<C> | string,
+        dstAddress: string,
+        options?: SpvFromBTCOptions
+    ): Promise<{
+        swap: SpvFromBTCSwap<T[C]>,
+        utxos: BitcoinWalletUtxo[],
+        btcFeeRate: number
+    }> {
+        const dstToken = typeof(_dstToken)==="string" ? this.getToken(_dstToken) as Token<C> : _dstToken;
+        if(!isSCToken<C>(dstToken)) throw new Error("Destination token must be a smart chain token!");
+
+        const wallet = 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 as C, dstAddress, dstToken.address, null, false, undefined, {
+                ...options,
+                sourceWalletUtxos: walletUtxosPromise,
+                bitcoinFeeRate: bitcoinFeeRatePromise
+            }
+        );
+
+        return {
+            swap,
+            utxos: await walletUtxosPromise,
+            btcFeeRate: Math.max(swap.minimumBtcFeeRate, await bitcoinFeeRatePromise)
+        };
+    }
+
     /**
      * Returns all swaps
      */
@@ -1601,14 +1712,14 @@ export class Swapper<T extends MultiChain> extends EventEmitter<{
     }
 
     /**
-     * Returns all swaps where an action is required (either claim or refund)
+     * Returns all swaps which are pending (i.e. not in their final state yet)
      */
-    getActionableSwaps(): Promise<ISwap[]>;
+    getPendingSwaps(): Promise<ISwap[]>;
     /**
-     * Returns swaps where an action is required (either claim or refund) for the specific chain, and optionally also for a specific signer's address
+     * 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
      */
-    getActionableSwaps<C extends ChainIds<T>>(chainId: C, signer?: string): Promise<ISwap<T[C]>[]>;
-    async getActionableSwaps<C extends ChainIds<T>>(chainId?: C, signer?: string): Promise<ISwap[]> {
+    getPendingSwaps<C extends ChainIds<T>>(chainId: C, signer?: string): Promise<ISwap<T[C]>[]>;
+    async getPendingSwaps<C extends ChainIds<T>>(chainId?: C, signer?: string): Promise<ISwap[]> {
         if(chainId==null) {
             const res: ISwap[][] = await Promise.all(Object.keys(this._chains).map((chainId) => {
                 const {unifiedSwapStorage, reviver, wrappers} = this._chains[chainId];
@@ -1622,7 +1733,7 @@ export class Swapper<T extends MultiChain> extends EventEmitter<{
                 }
                 return unifiedSwapStorage.query(queryParams, reviver);
             }));
-            return res.flat().filter(swap => swap.requiresAction());
+            return res.flat();
         } else {
             const {unifiedSwapStorage, reviver, wrappers} = this._chains[chainId];
             const queryParams: Array<QueryParams[]> = [];
@@ -1633,7 +1744,23 @@ export class Swapper<T extends MultiChain> extends 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);
+        }
+    }
+
+    /**
+     * Returns all swaps where an action is required (either claim or refund)
+     */
+    getActionableSwaps(): Promise<ISwap[]>;
+    /**
+     * Returns swaps where an action is required (either claim or refund) for the specific chain, and optionally also for a specific signer's address
+     */
+    getActionableSwaps<C extends ChainIds<T>>(chainId: C, signer?: string): Promise<ISwap<T[C]>[]>;
+    async getActionableSwaps<C extends ChainIds<T>>(chainId?: C, signer?: string): Promise<ISwap[]> {
+        if(chainId==null) {
+            return (await this.getPendingSwaps()).filter(swap => swap.requiresAction());
+        } else {
+            return (await this.getPendingSwaps(chainId, signer)).filter(swap => swap.requiresAction());
         }
     }
 
@@ -1831,8 +1958,8 @@ export class Swapper<T extends MultiChain> extends EventEmitter<{
         }
 
         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());
@@ -1889,6 +2016,20 @@ export class Swapper<T extends MultiChain> extends EventEmitter<{
         }
     }
 
+    /**
+     * 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<C extends ChainIds<T>>(chainId: C, lastEventCursorState?: any): Promise<any> {
+        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/src/swapper/SwapperUtils.ts

@@ -337,6 +337,22 @@ export class SwapperUtils<T extends MultiChain> {
         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: string): string {
+        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
@@ -477,11 +493,18 @@ export class SwapperUtils<T extends MultiChain> {
     }
 
     /**
-     * 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 {
+        if(chainIdentifier==="BITCOIN") {
+            // Return random p2wkh address
+            return Address(this.bitcoinNetwork).encode({
+                type: "wpkh",
+                hash: randomBytes(20)
+            });
+        }
         if(this.root._chains[chainIdentifier]==null) throw new Error("Invalid chain identifier! Unknown chain: "+chainIdentifier);
         return this.root._chains[chainIdentifier].chainInterface.randomAddress();
     }
@@ -524,6 +547,23 @@ export class SwapperUtils<T extends MultiChain> {
         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 extends ChainIds<T>>(
+        chainIdentifier: ChainIdentifier,
+        txs: T[ChainIdentifier]["TX"][]
+    ): Promise<T[ChainIdentifier]["TX"][]> {
+        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
      *