@atomiqlabs/sdk 8.8.3 → 8.9.1

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,9 +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
@@ -129,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,
@@ -160,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.
@@ -170,7 +173,20 @@ 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
+    },
+
+    /**
+     * If you set the option to `true` the chains for which the RPC is unresponsive are skipped and not initialized
+     *  letting the swapper continue with only the available chains with responsive RPCs
+     */
+    gracefullyHandleChainErrors?: boolean,
 };
 
 /**
@@ -307,6 +323,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
      */
@@ -362,6 +382,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);
         };
@@ -413,6 +440,7 @@ export class Swapper<T extends MultiChain> extends EventEmitter<{
                 pricing,
                 this._tokens[chainId],
                 versions,
+                lpApi,
                 {
                     getRequestTimeout: this.options.getRequestTimeout,
                     postRequestTimeout: this.options.postRequestTimeout,
@@ -428,6 +456,7 @@ export class Swapper<T extends MultiChain> extends EventEmitter<{
                 this._tokens[chainId],
                 versions,
                 this._bitcoinRpc,
+                lpApi,
                 {
                     getRequestTimeout: this.options.getRequestTimeout,
                     postRequestTimeout: this.options.postRequestTimeout,
@@ -444,6 +473,7 @@ export class Swapper<T extends MultiChain> extends EventEmitter<{
                 this._tokens[chainId],
                 versions,
                 lightningApi,
+                lpApi,
                 {
                     getRequestTimeout: this.options.getRequestTimeout,
                     postRequestTimeout: this.options.postRequestTimeout,
@@ -461,6 +491,7 @@ export class Swapper<T extends MultiChain> extends EventEmitter<{
                 versions,
                 versionedContracts,
                 this._bitcoinRpc,
+                lpApi,
                 {
                     getRequestTimeout: this.options.getRequestTimeout,
                     postRequestTimeout: this.options.postRequestTimeout,
@@ -475,6 +506,7 @@ export class Swapper<T extends MultiChain> extends EventEmitter<{
                 chainInterface,
                 pricing,
                 this._tokens[chainId],
+                lpApi,
                 {
                     getRequestTimeout: this.options.getRequestTimeout,
                     postRequestTimeout: this.options.postRequestTimeout,
@@ -489,6 +521,7 @@ export class Swapper<T extends MultiChain> extends EventEmitter<{
                 pricing,
                 this._tokens[chainId],
                 bitcoinRpc,
+                lpApi,
                 {
                     getRequestTimeout: this.options.getRequestTimeout,
                     postRequestTimeout: this.options.postRequestTimeout,
@@ -509,6 +542,7 @@ export class Swapper<T extends MultiChain> extends EventEmitter<{
                     versions,
                     versionedContracts,
                     bitcoinRpc,
+                    lpApi,
                     {
                         getRequestTimeout: this.options.getRequestTimeout,
                         postRequestTimeout: this.options.postRequestTimeout,
@@ -530,6 +564,7 @@ export class Swapper<T extends MultiChain> extends EventEmitter<{
                     versions,
                     lightningApi,
                     this.messenger,
+                    lpApi,
                     {
                         getRequestTimeout: this.options.getRequestTimeout,
                         postRequestTimeout: this.options.postRequestTimeout,
@@ -566,9 +601,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[]) => {
@@ -581,7 +616,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();
 
@@ -630,45 +665,52 @@ export class Swapper<T extends MultiChain> extends EventEmitter<{
                     reviver
                 } = this._chains[chainIdentifier];
 
-                const _chainInterface: any = chainInterface;
-                if(_chainInterface.verifyNetwork!=null) {
-                    await _chainInterface.verifyNetwork(this.bitcoinNetwork);
-                }
+                try {
+                    const _chainInterface: any = chainInterface;
+                    if(_chainInterface.verifyNetwork!=null) {
+                        await _chainInterface.verifyNetwork(this.bitcoinNetwork);
+                    }
 
-                for(let contractVersion in versionedContracts) {
-                    await versionedContracts[contractVersion].swapContract.start();
-                    this.logger.debug("init(): Intialized swap contract: "+chainIdentifier+` version: ${contractVersion}`);
-                }
+                    for(let contractVersion in versionedContracts) {
+                        await versionedContracts[contractVersion].swapContract.start();
+                        this.logger.debug("init(): Intialized swap contract: "+chainIdentifier+` version: ${contractVersion}`);
+                    }
 
-                await unifiedSwapStorage.init();
-                if(unifiedSwapStorage.storage instanceof IndexedDBUnifiedStorage) {
-                    //Try to migrate the data here
-                    const storagePrefix = chainIdentifier==="SOLANA" ?
-                        "SOLv4-"+this.bitcoinNetwork+"-Swaps-" :
-                        "atomiqsdk-"+this.bitcoinNetwork+chainIdentifier+"-Swaps-";
-                    await unifiedSwapStorage.storage.tryMigrate(
-                        [
-                            [storagePrefix+"FromBTC", SwapType.FROM_BTC],
-                            [storagePrefix+"FromBTCLN", SwapType.FROM_BTCLN],
-                            [storagePrefix+"ToBTC", SwapType.TO_BTC],
-                            [storagePrefix+"ToBTCLN", SwapType.TO_BTCLN]
-                        ],
-                        (obj: any) => {
-                            const swap = reviver(obj);
-                            if(swap._randomNonce==null) {
-                                const oldIdentifierHash = swap.getId();
-                                swap._randomNonce = randomBytes(16).toString("hex");
-                                const newIdentifierHash = swap.getId();
-                                this.logger.info("init(): Found older swap version without randomNonce, replacing, old hash: "+oldIdentifierHash+
-                                    " new hash: "+newIdentifierHash);
+                    await unifiedSwapStorage.init();
+                    if(unifiedSwapStorage.storage instanceof IndexedDBUnifiedStorage) {
+                        //Try to migrate the data here
+                        const storagePrefix = chainIdentifier==="SOLANA" ?
+                            "SOLv4-"+this.bitcoinNetwork+"-Swaps-" :
+                            "atomiqsdk-"+this.bitcoinNetwork+chainIdentifier+"-Swaps-";
+                        await unifiedSwapStorage.storage.tryMigrate(
+                            [
+                                [storagePrefix+"FromBTC", SwapType.FROM_BTC],
+                                [storagePrefix+"FromBTCLN", SwapType.FROM_BTCLN],
+                                [storagePrefix+"ToBTC", SwapType.TO_BTC],
+                                [storagePrefix+"ToBTCLN", SwapType.TO_BTCLN]
+                            ],
+                            (obj: any) => {
+                                const swap = reviver(obj);
+                                if(swap._randomNonce==null) {
+                                    const oldIdentifierHash = swap.getId();
+                                    swap._randomNonce = randomBytes(16).toString("hex");
+                                    const newIdentifierHash = swap.getId();
+                                    this.logger.info("init(): Found older swap version without randomNonce, replacing, old hash: "+oldIdentifierHash+
+                                        " new hash: "+newIdentifierHash);
+                                }
+                                return swap;
                             }
-                            return swap;
-                        }
-                    )
-                }
+                        )
+                    }
 
-                if(!this.options.noEvents) await unifiedChainEvents.start();
-                this.logger.debug("init(): Intialized events: "+chainIdentifier);
+                    await unifiedChainEvents.start(this.options.noEvents);
+                    this.logger.debug("init(): Initialized events: "+chainIdentifier);
+                } catch (e) {
+                    if(!this.options.gracefullyHandleChainErrors) throw e;
+                    this.logger.error(`init(): Failed to initialize ${chainIdentifier} (skipped): `, e);
+                    delete this._chains[chainIdentifier];
+                    return;
+                }
 
                 for(let key in wrappers) {
                     // this.logger.debug("init(): Initializing "+SwapType[key]+": "+chainIdentifier);
@@ -709,6 +751,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
      */
@@ -1521,6 +1570,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));
@@ -1634,7 +1686,7 @@ export class Swapper<T extends MultiChain> extends EventEmitter<{
         const bitcoinFeeRatePromise = options?.bitcoinFeeRate ?? wallet.getFeeRate();
 
         const swap = await this.createFromBTCSwapNew(
-            dstToken.chainId, dstAddress, dstToken.address, null, false, undefined, {
+            dstToken.chainId as C, dstAddress, dstToken.address, null, false, undefined, {
                 ...options,
                 sourceWalletUtxos: walletUtxosPromise,
                 bitcoinFeeRate: bitcoinFeeRatePromise
@@ -1673,14 +1725,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];
@@ -1694,7 +1746,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[]> = [];
@@ -1705,7 +1757,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());
         }
     }
 
@@ -1903,8 +1971,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());
@@ -1961,6 +2029,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
      *