@arkade-os/sdk 0.3.0-alpha.8 → 0.3.0

package/dist/cjs/wallet/serviceWorker/utils.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_DB_NAME = void 0;
 exports.setupServiceWorker = setupServiceWorker;
+exports.DEFAULT_DB_NAME = "arkade-service-worker";
 /**
  * setupServiceWorker sets up the service worker.
  * @param path - the path to the service worker script

package/dist/cjs/wallet/serviceWorker/wallet.js

@@ -25,7 +25,7 @@ class ServiceWorkerWallet {
     }
     static async create(options) {
         // Default to IndexedDB for service worker context
-        const storage = options.storage || new indexedDB_1.IndexedDBStorageAdapter("wallet-db");
+        const storage = new indexedDB_1.IndexedDBStorageAdapter(options.dbName || utils_1.DEFAULT_DB_NAME, options.dbVersion);
         // Create repositories
         const walletRepo = new walletRepository_1.WalletRepositoryImpl(storage);
         const contractRepo = new contractRepository_1.ContractRepositoryImpl(storage);
@@ -34,7 +34,7 @@ class ServiceWorkerWallet {
             ? options.identity
             : null;
         if (!identity) {
-            throw new Error("ServiceWorkerWallet.create() requires a Identity that can expose its private key");
+            throw new Error("ServiceWorkerWallet.create() requires a Identity that can expose a single private key");
         }
         // Extract private key for service worker initialization
         const privateKey = identity.toHex();
@@ -77,13 +77,9 @@ class ServiceWorkerWallet {
         // Register and setup the service worker
         const serviceWorker = await (0, utils_1.setupServiceWorker)(options.serviceWorkerPath);
         // Use the existing create method
-        return await ServiceWorkerWallet.create({
-            arkServerPublicKey: options.arkServerPublicKey,
-            arkServerUrl: options.arkServerUrl,
-            esploraUrl: options.esploraUrl,
-            identity: options.identity,
+        return ServiceWorkerWallet.create({
+            ...options,
             serviceWorker,
-            storage: options.storage,
         });
     }
     // send a message and wait for a response
@@ -260,6 +256,9 @@ class ServiceWorkerWallet {
             return new Promise((resolve, reject) => {
                 const messageHandler = (event) => {
                     const response = event.data;
+                    if (response.id !== message.id) {
+                        return;
+                    }
                     if (!response.success) {
                         navigator.serviceWorker.removeEventListener("message", messageHandler);
                         reject(new Error(response.message));

package/dist/cjs/wallet/serviceWorker/worker.js

@@ -14,14 +14,17 @@ const base_1 = require("@scure/base");
 const indexedDB_1 = require("../../storage/indexedDB");
 const walletRepository_1 = require("../../repositories/walletRepository");
 const utils_1 = require("../utils");
+const utils_2 = require("./utils");
 /**
  * Worker is a class letting to interact with ServiceWorkerWallet from the client
  * it aims to be run in a service worker context
  */
 class Worker {
-    constructor(messageCallback = () => { }) {
+    constructor(dbName = utils_2.DEFAULT_DB_NAME, dbVersion = 1, messageCallback = () => { }) {
+        this.dbName = dbName;
+        this.dbVersion = dbVersion;
         this.messageCallback = messageCallback;
-        this.storage = new indexedDB_1.IndexedDBStorageAdapter("arkade-service-worker", 1);
+        this.storage = new indexedDB_1.IndexedDBStorageAdapter(dbName, dbVersion);
         this.walletRepository = new walletRepository_1.WalletRepositoryImpl(this.storage);
     }
     /**
@@ -57,6 +60,15 @@ class Worker {
             spent: allVtxos.filter((vtxo) => !(0, __1.isSpendable)(vtxo)),
         };
     }
+    /**
+     * Get all boarding utxos from wallet repository
+     */
+    async getAllBoardingUtxos() {
+        if (!this.wallet)
+            return [];
+        const address = await this.wallet.getBoardingAddress();
+        return await this.walletRepository.getUtxos(address);
+    }
     async start(withServiceWorkerUpdate = true) {
         self.addEventListener("message", async (event) => {
             await this.handleMessage(event);
@@ -107,6 +119,9 @@ class Worker {
         const txs = await this.wallet.getTransactionHistory();
         if (txs)
             await this.walletRepository.saveTransactions(address, txs);
+        // unsubscribe previous subscription if any
+        if (this.incomingFundsSubscription)
+            this.incomingFundsSubscription();
         // subscribe for incoming funds and notify all clients when new funds arrive
         this.incomingFundsSubscription = await this.wallet.notifyIncomingFunds(async (funds) => {
             if (funds.type === "vtxo") {
@@ -124,11 +139,19 @@ class Worker {
                     ...spentVtxos,
                 ]);
                 // notify all clients about the vtxo update
-                this.sendMessageToAllClients("VTXO_UPDATE", JSON.stringify({ newVtxos, spentVtxos }));
+                this.sendMessageToAllClients(response_1.Response.vtxoUpdate(newVtxos, spentVtxos));
             }
             if (funds.type === "utxo") {
+                const newUtxos = funds.coins.map((utxo) => (0, utils_1.extendCoin)(this.wallet, utxo));
+                if (newUtxos.length === 0) {
+                    this.sendMessageToAllClients(response_1.Response.utxoUpdate([]));
+                    return;
+                }
+                const boardingAddress = await this.wallet?.getBoardingAddress();
+                // save utxos using unified repository
+                await this.walletRepository.saveUtxos(boardingAddress, newUtxos);
                 // notify all clients about the utxo update
-                this.sendMessageToAllClients("UTXO_UPDATE", JSON.stringify(funds.coins));
+                this.sendMessageToAllClients(response_1.Response.utxoUpdate(funds.coins));
             }
         });
     }
@@ -285,7 +308,7 @@ class Worker {
         }
         try {
             const [boardingUtxos, spendableVtxos, sweptVtxos] = await Promise.all([
-                this.wallet.getBoardingUtxos(),
+                this.getAllBoardingUtxos(),
                 this.getSpendableVtxos(),
                 this.getSweptVtxos(),
             ]);
@@ -353,22 +376,21 @@ class Worker {
             return;
         }
         try {
-            let vtxos = await this.getSpendableVtxos();
-            if (!message.filter?.withRecoverable) {
-                if (!this.wallet)
-                    throw new Error("Wallet not initialized");
-                // exclude subdust and recoverable if we don't want recoverable
-                const notSubdust = (v) => {
-                    const dustAmount = this.wallet?.dustAmount;
-                    return dustAmount == null
-                        ? true
-                        : !(0, __1.isSubdust)(v, dustAmount);
-                };
-                vtxos = vtxos
-                    .filter(notSubdust)
-                    .filter((v) => !(0, __1.isRecoverable)(v));
-            }
-            event.source?.postMessage(response_1.Response.vtxos(message.id, vtxos));
+            const vtxos = await this.getSpendableVtxos();
+            const dustAmount = this.wallet.dustAmount;
+            const includeRecoverable = message.filter?.withRecoverable ?? false;
+            const filteredVtxos = includeRecoverable
+                ? vtxos
+                : vtxos.filter((v) => {
+                    if (dustAmount != null && (0, __1.isSubdust)(v, dustAmount)) {
+                        return false;
+                    }
+                    if ((0, __1.isRecoverable)(v)) {
+                        return false;
+                    }
+                    return true;
+                });
+            event.source?.postMessage(response_1.Response.vtxos(message.id, filteredVtxos));
         }
         catch (error) {
             console.error("Error getting vtxos:", error);
@@ -391,7 +413,7 @@ class Worker {
             return;
         }
         try {
-            const boardingUtxos = await this.wallet.getBoardingUtxos();
+            const boardingUtxos = await this.getAllBoardingUtxos();
             event.source?.postMessage(response_1.Response.boardingUtxos(message.id, boardingUtxos));
         }
         catch (error) {
@@ -513,15 +535,12 @@ class Worker {
                 event.source?.postMessage(response_1.Response.error(message.id, "Unknown message type"));
         }
     }
-    async sendMessageToAllClients(type, message) {
+    async sendMessageToAllClients(message) {
         self.clients
             .matchAll({ includeUncontrolled: true, type: "window" })
             .then((clients) => {
             clients.forEach((client) => {
-                client.postMessage({
-                    type,
-                    message,
-                });
+                client.postMessage(message);
             });
         });
     }

package/dist/cjs/wallet/unroll.js

@@ -1,13 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Unroll = void 0;
-const transaction_js_1 = require("@scure/btc-signer/transaction.js");
-const indexer_1 = require("../providers/indexer");
 const base_1 = require("@scure/base");
+const btc_signer_1 = require("@scure/btc-signer");
+const indexer_1 = require("../providers/indexer");
 const base_2 = require("../script/base");
-const psbt_js_1 = require("@scure/btc-signer/psbt.js");
 const txSizeEstimator_1 = require("../utils/txSizeEstimator");
 const wallet_1 = require("./wallet");
+const transaction_1 = require("../utils/transaction");
 var Unroll;
 (function (Unroll) {
     let StepType;
@@ -106,9 +106,7 @@ var Unroll;
             if (virtualTxs.txs.length === 0) {
                 throw new Error(`Tx ${nextTxToBroadcast.txid} not found`);
             }
-            const tx = transaction_js_1.Transaction.fromPSBT(base_1.base64.decode(virtualTxs.txs[0]), {
-                allowUnknownInputs: true,
-            });
+            const tx = transaction_1.Transaction.fromPSBT(base_1.base64.decode(virtualTxs.txs[0]));
             // finalize the tree transaction
             if (nextTxToBroadcast.type === indexer_1.ChainTxType.TREE) {
                 const input = tx.getInput(0);
@@ -197,11 +195,11 @@ var Unroll;
                     amount: BigInt(vtxo.value),
                     script: base_2.VtxoScript.decode(vtxo.tapTree).pkScript,
                 },
-                sighashType: transaction_js_1.SigHash.DEFAULT,
+                sighashType: btc_signer_1.SigHash.DEFAULT,
             });
-            txWeightEstimator.addTapscriptInput(64, spendingLeaf[1].length, psbt_js_1.TaprootControlBlock.encode(spendingLeaf[0]).length);
+            txWeightEstimator.addTapscriptInput(64, spendingLeaf[1].length, btc_signer_1.TaprootControlBlock.encode(spendingLeaf[0]).length);
         }
-        const tx = new transaction_js_1.Transaction({ allowUnknownInputs: true, version: 2 });
+        const tx = new transaction_1.Transaction({ version: 2 });
         for (const input of inputs) {
             tx.addInput(input);
         }

package/dist/cjs/wallet/utils.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.extendVirtualCoin = extendVirtualCoin;
+exports.extendCoin = extendCoin;
 function extendVirtualCoin(wallet, vtxo) {
     return {
         ...vtxo,
@@ -9,3 +10,11 @@ function extendVirtualCoin(wallet, vtxo) {
         tapTree: wallet.offchainTapscript.encode(),
     };
 }
+function extendCoin(wallet, utxo) {
+    return {
+        ...utxo,
+        forfeitTapLeafScript: wallet.boardingTapscript.forfeit(),
+        intentTapLeafScript: wallet.boardingTapscript.exit(),
+        tapTree: wallet.boardingTapscript.encode(),
+    };
+}

package/dist/cjs/wallet/vtxo-manager.js

@@ -0,0 +1,323 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VtxoManager = exports.DEFAULT_RENEWAL_CONFIG = void 0;
+exports.isVtxoExpiringSoon = isVtxoExpiringSoon;
+exports.getExpiringAndRecoverableVtxos = getExpiringAndRecoverableVtxos;
+const _1 = require(".");
+/**
+ * Default renewal configuration values
+ */
+exports.DEFAULT_RENEWAL_CONFIG = {
+    thresholdPercentage: 10,
+};
+function getDustAmount(wallet) {
+    return "dustAmount" in wallet ? wallet.dustAmount : 330n;
+}
+/**
+ * Filter VTXOs that are recoverable (swept and still spendable, or preconfirmed subdust)
+ *
+ * Recovery strategy:
+ * - Always recover swept VTXOs (they've been taken by the server)
+ * - Only recover subdust preconfirmed VTXOs (to avoid locking liquidity on settled VTXOs with long expiry)
+ *
+ * @param vtxos - Array of virtual coins to check
+ * @param dustAmount - Dust threshold to identify subdust
+ * @returns Array of recoverable VTXOs
+ */
+function getRecoverableVtxos(vtxos, dustAmount) {
+    return vtxos.filter((vtxo) => {
+        // Always recover swept VTXOs
+        if ((0, _1.isRecoverable)(vtxo)) {
+            return true;
+        }
+        // Recover preconfirmed subdust to consolidate small amounts
+        if (vtxo.virtualStatus.state === "preconfirmed" &&
+            (0, _1.isSubdust)(vtxo, dustAmount)) {
+            return true;
+        }
+        return false;
+    });
+}
+/**
+ * Get recoverable VTXOs including subdust coins if the total value exceeds dust threshold.
+ *
+ * Decision is based on the combined total of ALL recoverable VTXOs (regular + subdust),
+ * not just the subdust portion alone.
+ *
+ * @param vtxos - Array of virtual coins to check
+ * @param dustAmount - Dust threshold amount in satoshis
+ * @returns Object containing recoverable VTXOs and whether subdust should be included
+ */
+function getRecoverableWithSubdust(vtxos, dustAmount) {
+    const recoverableVtxos = getRecoverableVtxos(vtxos, dustAmount);
+    // Separate subdust from regular recoverable
+    const subdust = [];
+    const regular = [];
+    for (const vtxo of recoverableVtxos) {
+        if ((0, _1.isSubdust)(vtxo, dustAmount)) {
+            subdust.push(vtxo);
+        }
+        else {
+            regular.push(vtxo);
+        }
+    }
+    // Calculate totals
+    const regularTotal = regular.reduce((sum, vtxo) => sum + BigInt(vtxo.value), 0n);
+    const subdustTotal = subdust.reduce((sum, vtxo) => sum + BigInt(vtxo.value), 0n);
+    const combinedTotal = regularTotal + subdustTotal;
+    // Include subdust only if the combined total exceeds dust threshold
+    const shouldIncludeSubdust = combinedTotal >= dustAmount;
+    const vtxosToRecover = shouldIncludeSubdust ? recoverableVtxos : regular;
+    const totalAmount = vtxosToRecover.reduce((sum, vtxo) => sum + BigInt(vtxo.value), 0n);
+    return {
+        vtxosToRecover,
+        includesSubdust: shouldIncludeSubdust,
+        totalAmount,
+    };
+}
+/**
+ * Check if a VTXO is expiring soon based on threshold
+ *
+ * @param vtxo - The virtual coin to check
+ * @param thresholdMs - Threshold in milliseconds from now
+ * @returns true if VTXO expires within threshold, false otherwise
+ */
+function isVtxoExpiringSoon(vtxo, percentage) {
+    const { batchExpiry } = vtxo.virtualStatus;
+    if (!batchExpiry) {
+        return false; // it doesn't expire
+    }
+    const now = Date.now();
+    if (batchExpiry <= now) {
+        return false; // already expired
+    }
+    // It shouldn't happen, but let's be safe
+    if (!vtxo.createdAt) {
+        return false;
+    }
+    const duration = batchExpiry - vtxo.createdAt.getTime();
+    const softExpiry = batchExpiry - (duration * percentage) / 100;
+    return softExpiry > 0 && softExpiry <= now;
+}
+/**
+ * Filter VTXOs that are expiring soon or are recoverable/subdust
+ *
+ * @param vtxos - Array of virtual coins to check
+ * @param thresholdMs - Threshold in milliseconds from now
+ * @param dustAmount - Dust threshold amount in satoshis
+ * @returns Array of VTXOs expiring within threshold
+ */
+function getExpiringAndRecoverableVtxos(vtxos, percentage, dustAmount) {
+    return vtxos.filter((vtxo) => isVtxoExpiringSoon(vtxo, percentage) ||
+        (0, _1.isRecoverable)(vtxo) ||
+        (0, _1.isSubdust)(vtxo, dustAmount));
+}
+/**
+ * VtxoManager is a unified class for managing VTXO lifecycle operations including
+ * recovery of swept/expired VTXOs and renewal to prevent expiration.
+ *
+ * Key Features:
+ * - **Recovery**: Reclaim swept or expired VTXOs back to the wallet
+ * - **Renewal**: Refresh VTXO expiration time before they expire
+ * - **Smart subdust handling**: Automatically includes subdust VTXOs when economically viable
+ * - **Expiry monitoring**: Check for VTXOs that are expiring soon
+ *
+ * VTXOs become recoverable when:
+ * - The Ark server sweeps them (virtualStatus.state === "swept") and they remain spendable
+ * - They are preconfirmed subdust (to consolidate small amounts without locking liquidity on settled VTXOs)
+ *
+ * @example
+ * ```typescript
+ * // Initialize with renewal config
+ * const manager = new VtxoManager(wallet, {
+ *   enabled: true,
+ *   thresholdPercentage: 10
+ * });
+ *
+ * // Check recoverable balance
+ * const balance = await manager.getRecoverableBalance();
+ * if (balance.recoverable > 0n) {
+ *   console.log(`Can recover ${balance.recoverable} sats`);
+ *   const txid = await manager.recoverVtxos();
+ * }
+ *
+ * // Check for expiring VTXOs
+ * const expiring = await manager.getExpiringVtxos();
+ * if (expiring.length > 0) {
+ *   console.log(`${expiring.length} VTXOs expiring soon`);
+ *   const txid = await manager.renewVtxos();
+ * }
+ * ```
+ */
+class VtxoManager {
+    constructor(wallet, renewalConfig) {
+        this.wallet = wallet;
+        this.renewalConfig = renewalConfig;
+    }
+    // ========== Recovery Methods ==========
+    /**
+     * Recover swept/expired VTXOs by settling them back to the wallet's Ark address.
+     *
+     * This method:
+     * 1. Fetches all VTXOs (including recoverable ones)
+     * 2. Filters for swept but still spendable VTXOs and preconfirmed subdust
+     * 3. Includes subdust VTXOs if the total value >= dust threshold
+     * 4. Settles everything back to the wallet's Ark address
+     *
+     * Note: Settled VTXOs with long expiry are NOT recovered to avoid locking liquidity unnecessarily.
+     * Only preconfirmed subdust is recovered to consolidate small amounts.
+     *
+     * @param eventCallback - Optional callback to receive settlement events
+     * @returns Settlement transaction ID
+     * @throws Error if no recoverable VTXOs found
+     *
+     * @example
+     * ```typescript
+     * const manager = new VtxoManager(wallet);
+     *
+     * // Simple recovery
+     * const txid = await manager.recoverVtxos();
+     *
+     * // With event callback
+     * const txid = await manager.recoverVtxos((event) => {
+     *   console.log('Settlement event:', event.type);
+     * });
+     * ```
+     */
+    async recoverVtxos(eventCallback) {
+        // Get all VTXOs including recoverable ones
+        const allVtxos = await this.wallet.getVtxos({
+            withRecoverable: true,
+            withUnrolled: false,
+        });
+        // Get dust amount from wallet
+        const dustAmount = getDustAmount(this.wallet);
+        // Filter recoverable VTXOs and handle subdust logic
+        const { vtxosToRecover, includesSubdust, totalAmount } = getRecoverableWithSubdust(allVtxos, dustAmount);
+        if (vtxosToRecover.length === 0) {
+            throw new Error("No recoverable VTXOs found");
+        }
+        const arkAddress = await this.wallet.getAddress();
+        // Settle all recoverable VTXOs back to the wallet
+        return this.wallet.settle({
+            inputs: vtxosToRecover,
+            outputs: [
+                {
+                    address: arkAddress,
+                    amount: totalAmount,
+                },
+            ],
+        }, eventCallback);
+    }
+    /**
+     * Get information about recoverable balance without executing recovery.
+     *
+     * Useful for displaying to users before they decide to recover funds.
+     *
+     * @returns Object containing recoverable amounts and subdust information
+     *
+     * @example
+     * ```typescript
+     * const manager = new VtxoManager(wallet);
+     * const balance = await manager.getRecoverableBalance();
+     *
+     * if (balance.recoverable > 0n) {
+     *   console.log(`You can recover ${balance.recoverable} sats`);
+     *   if (balance.includesSubdust) {
+     *     console.log(`This includes ${balance.subdust} sats from subdust VTXOs`);
+     *   }
+     * }
+     * ```
+     */
+    async getRecoverableBalance() {
+        const allVtxos = await this.wallet.getVtxos({
+            withRecoverable: true,
+            withUnrolled: false,
+        });
+        const dustAmount = getDustAmount(this.wallet);
+        const { vtxosToRecover, includesSubdust, totalAmount } = getRecoverableWithSubdust(allVtxos, dustAmount);
+        // Calculate subdust amount separately for reporting
+        const subdustAmount = vtxosToRecover
+            .filter((v) => BigInt(v.value) < dustAmount)
+            .reduce((sum, v) => sum + BigInt(v.value), 0n);
+        return {
+            recoverable: totalAmount,
+            subdust: subdustAmount,
+            includesSubdust,
+            vtxoCount: vtxosToRecover.length,
+        };
+    }
+    // ========== Renewal Methods ==========
+    /**
+     * Get VTXOs that are expiring soon based on renewal configuration
+     *
+     * @param thresholdPercentage - Optional override for threshold percentage (0-100)
+     * @returns Array of expiring VTXOs, empty array if renewal is disabled or no VTXOs expiring
+     *
+     * @example
+     * ```typescript
+     * const manager = new VtxoManager(wallet, { enabled: true, thresholdPercentage: 10 });
+     * const expiringVtxos = await manager.getExpiringVtxos();
+     * if (expiringVtxos.length > 0) {
+     *   console.log(`${expiringVtxos.length} VTXOs expiring soon`);
+     * }
+     * ```
+     */
+    async getExpiringVtxos(thresholdPercentage) {
+        const vtxos = await this.wallet.getVtxos({ withRecoverable: true });
+        const percentage = thresholdPercentage ??
+            this.renewalConfig?.thresholdPercentage ??
+            exports.DEFAULT_RENEWAL_CONFIG.thresholdPercentage;
+        return getExpiringAndRecoverableVtxos(vtxos, percentage, getDustAmount(this.wallet));
+    }
+    /**
+     * Renew expiring VTXOs by settling them back to the wallet's address
+     *
+     * This method collects all expiring spendable VTXOs (including recoverable ones) and settles
+     * them back to the wallet, effectively refreshing their expiration time. This is the
+     * primary way to prevent VTXOs from expiring.
+     *
+     * @param eventCallback - Optional callback for settlement events
+     * @returns Settlement transaction ID
+     * @throws Error if no VTXOs available to renew
+     * @throws Error if total amount is below dust threshold
+     *
+     * @example
+     * ```typescript
+     * const manager = new VtxoManager(wallet);
+     *
+     * // Simple renewal
+     * const txid = await manager.renewVtxos();
+     *
+     * // With event callback
+     * const txid = await manager.renewVtxos((event) => {
+     *   console.log('Settlement event:', event.type);
+     * });
+     * ```
+     */
+    async renewVtxos(eventCallback) {
+        // Get all VTXOs (including recoverable ones)
+        const vtxos = await this.getExpiringVtxos();
+        if (vtxos.length === 0) {
+            throw new Error("No VTXOs available to renew");
+        }
+        const totalAmount = vtxos.reduce((sum, vtxo) => sum + vtxo.value, 0);
+        // Get dust amount from wallet
+        const dustAmount = getDustAmount(this.wallet);
+        // Check if total amount is above dust threshold
+        if (BigInt(totalAmount) < dustAmount) {
+            throw new Error(`Total amount ${totalAmount} is below dust threshold ${dustAmount}`);
+        }
+        const arkAddress = await this.wallet.getAddress();
+        return this.wallet.settle({
+            inputs: vtxos,
+            outputs: [
+                {
+                    address: arkAddress,
+                    amount: BigInt(totalAmount),
+                },
+            ],
+        }, eventCallback);
+    }
+}
+exports.VtxoManager = VtxoManager;