@arkade-os/sdk 0.4.6 → 0.4.8

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

@@ -148,43 +148,6 @@ function getExpiringAndRecoverableVtxos(vtxos, thresholdMs, dustAmount) {
         ((0, _1.isSpendable)(vtxo) && (0, _1.isExpired)(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,
- *   thresholdMs: 86400000
- * });
- *
- * // 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, 
     /** @deprecated Use settlementConfig instead */
@@ -194,6 +157,7 @@ class VtxoManager {
         this.knownBoardingUtxos = new Set();
         this.sweptBoardingUtxos = new Set();
         this.pollInProgress = false;
+        this.consecutivePollFailures = 0;
         // Normalize: prefer settlementConfig, fall back to renewalConfig, default to enabled
         if (settlementConfig !== undefined) {
             this.settlementConfig = settlementConfig;
@@ -582,6 +546,25 @@ class VtxoManager {
                     return;
                 }
                 this.renewVtxos().catch((e) => {
+                    if (e instanceof Error) {
+                        if (e.message.includes("No VTXOs available to renew")) {
+                            // Not an error, just no VTXO eligible for renewal.
+                            return;
+                        }
+                        if (e.message.includes("is below dust threshold")) {
+                            // Not an error, just below dust threshold.
+                            // As more VTXOs are received, the threshold will be raised.
+                            return;
+                        }
+                        if (e.message.includes("VTXO_ALREADY_REGISTERED") ||
+                            e.message.includes("duplicated input")) {
+                            // VTXO is already being used in a concurrent
+                            // user-initiated operation. Skip silently — the
+                            // wallet's tx lock serializes these, but the
+                            // renewal will retry on the next cycle.
+                            return;
+                        }
+                    }
                     console.error("Error renewing VTXOs:", e);
                 });
                 delegatorManager
@@ -597,19 +580,36 @@ class VtxoManager {
             return undefined;
         }
     }
+    /** Computes the next poll delay, applying exponential backoff on failures. */
+    getNextPollDelay() {
+        if (this.settlementConfig === false)
+            return 0;
+        const baseMs = this.settlementConfig.pollIntervalMs ??
+            exports.DEFAULT_SETTLEMENT_CONFIG.pollIntervalMs;
+        if (this.consecutivePollFailures === 0)
+            return baseMs;
+        const backoff = Math.min(baseMs * Math.pow(2, this.consecutivePollFailures), VtxoManager.MAX_BACKOFF_MS);
+        return backoff;
+    }
     /**
      * Starts a polling loop that:
      * 1. Auto-settles new boarding UTXOs into Ark
      * 2. Sweeps expired boarding UTXOs (when boardingUtxoSweep is enabled)
+     *
+     * Uses setTimeout chaining (not setInterval) so a slow/blocked poll
+     * cannot stack up and the next delay can incorporate backoff.
      */
     startBoardingUtxoPoll() {
         if (this.settlementConfig === false)
             return;
-        const intervalMs = this.settlementConfig.pollIntervalMs ??
-            exports.DEFAULT_SETTLEMENT_CONFIG.pollIntervalMs;
-        // Run once immediately, then on interval
+        // Run once immediately, then schedule next
         this.pollBoardingUtxos();
-        this.pollIntervalId = setInterval(() => this.pollBoardingUtxos(), intervalMs);
+    }
+    schedulePoll() {
+        if (this.settlementConfig === false)
+            return;
+        const delay = this.getNextPollDelay();
+        this.pollTimeoutId = setTimeout(() => this.pollBoardingUtxos(), delay);
     }
     async pollBoardingUtxos() {
         // Guard: wallet must support boarding UTXO + sweep operations
@@ -619,6 +619,7 @@ class VtxoManager {
         if (this.pollInProgress)
             return;
         this.pollInProgress = true;
+        let hadError = false;
         try {
             // Settle new (unexpired) UTXOs first, then sweep expired ones.
             // Sequential to avoid racing for the same UTXOs.
@@ -626,6 +627,7 @@ class VtxoManager {
                 await this.settleBoardingUtxos();
             }
             catch (e) {
+                hadError = true;
                 console.error("Error auto-settling boarding UTXOs:", e);
             }
             const sweepEnabled = this.settlementConfig !== false &&
@@ -638,13 +640,21 @@ class VtxoManager {
                 catch (e) {
                     if (!(e instanceof Error) ||
                         !e.message.includes("No expired boarding UTXOs")) {
+                        hadError = true;
                         console.error("Error auto-sweeping boarding UTXOs:", e);
                     }
                 }
             }
         }
         finally {
+            if (hadError) {
+                this.consecutivePollFailures++;
+            }
+            else {
+                this.consecutivePollFailures = 0;
+            }
             this.pollInProgress = false;
+            this.schedulePoll();
         }
     }
     /**
@@ -661,7 +671,13 @@ class VtxoManager {
         // accidentally settling expired UTXOs (which would conflict with sweep).
         let expiredSet;
         try {
-            const expired = await this.getExpiredBoardingUtxos();
+            const boardingTimelock = this.getBoardingTimelock();
+            let chainTipHeight;
+            if (boardingTimelock.type === "blocks") {
+                const tip = await this.getOnchainProvider().getChainTip();
+                chainTipHeight = tip.height;
+            }
+            const expired = boardingUtxos.filter((utxo) => (0, arkTransaction_1.hasBoardingTxExpired)(utxo, boardingTimelock, chainTipHeight));
             expiredSet = new Set(expired.map((u) => `${u.txid}:${u.vout}`));
         }
         catch {
@@ -687,9 +703,9 @@ class VtxoManager {
     }
     async dispose() {
         this.disposePromise ?? (this.disposePromise = (async () => {
-            if (this.pollIntervalId) {
-                clearInterval(this.pollIntervalId);
-                this.pollIntervalId = undefined;
+            if (this.pollTimeoutId) {
+                clearTimeout(this.pollTimeoutId);
+                this.pollTimeoutId = undefined;
             }
             const subscription = await this.contractEventsSubscriptionReady;
             this.contractEventsSubscription = undefined;
@@ -702,3 +718,4 @@ class VtxoManager {
     }
 }
 exports.VtxoManager = VtxoManager;
+VtxoManager.MAX_BACKOFF_MS = 5 * 60 * 1000; // 5 minutes

package/dist/cjs/wallet/wallet.js

@@ -62,6 +62,19 @@ class ReadonlyWallet {
         this.walletRepository = walletRepository;
         this.contractRepository = contractRepository;
         this.delegatorProvider = delegatorProvider;
+        // Guard: detect identity/server network mismatch for descriptor-based identities.
+        // This duplicates the check in setupWalletConfig() so that subclasses
+        // bypassing the factory still get the safety net.
+        if ("descriptor" in identity) {
+            const descriptor = identity.descriptor;
+            const identityIsMainnet = !descriptor.includes("tpub");
+            const serverIsMainnet = network.bech32 === "bc";
+            if (identityIsMainnet !== serverIsMainnet) {
+                throw new Error(`Network mismatch: identity uses ${identityIsMainnet ? "mainnet" : "testnet"} derivation ` +
+                    `but wallet network is ${serverIsMainnet ? "mainnet" : "testnet"}. ` +
+                    `Create identity with { isMainnet: ${serverIsMainnet} } to match.`);
+            }
+        }
         this.watcherConfig = watcherConfig;
         this._assetManager = new asset_manager_1.ReadonlyAssetManager(this.indexerProvider);
     }
@@ -89,6 +102,24 @@ class ReadonlyWallet {
         const indexerProvider = config.indexerProvider || new indexer_1.RestIndexerProvider(indexerUrl);
         const info = await arkProvider.getInfo();
         const network = (0, networks_1.getNetwork)(info.network);
+        // Guard: detect identity/server network mismatch for seed-based identities.
+        // A mainnet descriptor (xpub, coin type 0) connected to a testnet server
+        // (or vice versa) means wrong derivation path → wrong keys → potential fund loss.
+        if ("descriptor" in config.identity) {
+            const descriptor = config.identity.descriptor;
+            const identityIsMainnet = !descriptor.includes("tpub");
+            const serverIsMainnet = info.network === "bitcoin";
+            if (identityIsMainnet && !serverIsMainnet) {
+                throw new Error(`Network mismatch: identity uses mainnet derivation (coin type 0) ` +
+                    `but Ark server is on ${info.network}. ` +
+                    `Create identity with { isMainnet: false } to use testnet derivation.`);
+            }
+            if (!identityIsMainnet && serverIsMainnet) {
+                throw new Error(`Network mismatch: identity uses testnet derivation (coin type 1) ` +
+                    `but Ark server is on mainnet. ` +
+                    `Create identity with { isMainnet: true } or omit isMainnet (defaults to mainnet).`);
+            }
+        }
         // Extract esploraUrl from provider if not explicitly provided
         const esploraUrl = config.esploraUrl || onchain_1.ESPLORA_URL[info.network];
         // Use provided onchainProvider instance or create a new one
@@ -664,6 +695,20 @@ exports.ReadonlyWallet = ReadonlyWallet;
  * ```
  */
 class Wallet extends ReadonlyWallet {
+    _withTxLock(fn) {
+        let release;
+        const lock = new Promise((r) => (release = r));
+        const prev = this._txLock;
+        this._txLock = lock;
+        return prev.then(async () => {
+            try {
+                return await fn();
+            }
+            finally {
+                release();
+            }
+        });
+    }
     constructor(identity, network, networkName, onchainProvider, arkProvider, indexerProvider, arkServerPublicKey, offchainTapscript, boardingTapscript, serverUnrollScript, forfeitOutputScript, forfeitPubkey, dustAmount, walletRepository, contractRepository, 
     /** @deprecated Use settlementConfig */
     renewalConfig, delegatorProvider, watcherConfig, settlementConfig) {
@@ -673,6 +718,13 @@ class Wallet extends ReadonlyWallet {
         this.serverUnrollScript = serverUnrollScript;
         this.forfeitOutputScript = forfeitOutputScript;
         this.forfeitPubkey = forfeitPubkey;
+        /**
+         * Async mutex that serializes all operations submitting VTXOs to the Ark
+         * server (`settle`, `send`, `sendBitcoin`). This prevents VtxoManager's
+         * background renewal from racing with user-initiated transactions for the
+         * same VTXO inputs.
+         */
+        this._txLock = Promise.resolve();
         this.identity = identity;
         // Backwards-compatible: keep renewalConfig populated for any code reading it
         this.renewalConfig = {
@@ -811,40 +863,42 @@ class Wallet extends ReadonlyWallet {
             throw new Error("Invalid Ark address " + params.address);
         }
         if (params.selectedVtxos && params.selectedVtxos.length > 0) {
-            const selectedVtxoSum = params.selectedVtxos
-                .map((v) => v.value)
-                .reduce((a, b) => a + b, 0);
-            if (selectedVtxoSum < params.amount) {
-                throw new Error("Selected VTXOs do not cover specified amount");
-            }
-            const changeAmount = selectedVtxoSum - params.amount;
-            const selected = {
-                inputs: params.selectedVtxos,
-                changeAmount: BigInt(changeAmount),
-            };
-            const outputAddress = address_1.ArkAddress.decode(params.address);
-            const outputScript = BigInt(params.amount) < this.dustAmount
-                ? outputAddress.subdustPkScript
-                : outputAddress.pkScript;
-            const outputs = [
-                {
-                    script: outputScript,
-                    amount: BigInt(params.amount),
-                },
-            ];
-            // add change output if needed
-            if (selected.changeAmount > 0n) {
-                const changeOutputScript = selected.changeAmount < this.dustAmount
-                    ? this.arkAddress.subdustPkScript
-                    : this.arkAddress.pkScript;
-                outputs.push({
-                    script: changeOutputScript,
-                    amount: BigInt(selected.changeAmount),
-                });
-            }
-            const { arkTxid, signedCheckpointTxs } = await this.buildAndSubmitOffchainTx(selected.inputs, outputs);
-            await this.updateDbAfterOffchainTx(selected.inputs, arkTxid, signedCheckpointTxs, params.amount, selected.changeAmount, selected.changeAmount > 0n ? outputs.length - 1 : 0);
-            return arkTxid;
+            return this._withTxLock(async () => {
+                const selectedVtxoSum = params
+                    .selectedVtxos.map((v) => v.value)
+                    .reduce((a, b) => a + b, 0);
+                if (selectedVtxoSum < params.amount) {
+                    throw new Error("Selected VTXOs do not cover specified amount");
+                }
+                const changeAmount = selectedVtxoSum - params.amount;
+                const selected = {
+                    inputs: params.selectedVtxos,
+                    changeAmount: BigInt(changeAmount),
+                };
+                const outputAddress = address_1.ArkAddress.decode(params.address);
+                const outputScript = BigInt(params.amount) < this.dustAmount
+                    ? outputAddress.subdustPkScript
+                    : outputAddress.pkScript;
+                const outputs = [
+                    {
+                        script: outputScript,
+                        amount: BigInt(params.amount),
+                    },
+                ];
+                // add change output if needed
+                if (selected.changeAmount > 0n) {
+                    const changeOutputScript = selected.changeAmount < this.dustAmount
+                        ? this.arkAddress.subdustPkScript
+                        : this.arkAddress.pkScript;
+                    outputs.push({
+                        script: changeOutputScript,
+                        amount: BigInt(selected.changeAmount),
+                    });
+                }
+                const { arkTxid, signedCheckpointTxs } = await this.buildAndSubmitOffchainTx(selected.inputs, outputs);
+                await this.updateDbAfterOffchainTx(selected.inputs, arkTxid, signedCheckpointTxs, params.amount, selected.changeAmount, selected.changeAmount > 0n ? outputs.length - 1 : 0);
+                return arkTxid;
+            });
         }
         return this.send({
             address: params.address,
@@ -852,6 +906,9 @@ class Wallet extends ReadonlyWallet {
         });
     }
     async settle(params, eventCallback) {
+        return this._withTxLock(() => this._settleImpl(params, eventCallback));
+    }
+    async _settleImpl(params, eventCallback) {
         if (params?.inputs) {
             for (const input of params.inputs) {
                 // validate arknotes inputs
@@ -1353,6 +1410,9 @@ class Wallet extends ReadonlyWallet {
      * ```
      */
     async send(...args) {
+        return this._withTxLock(() => this._sendImpl(...args));
+    }
+    async _sendImpl(...args) {
         if (args.length === 0) {
             throw new Error("At least one receiver is required");
         }

package/dist/cjs/worker/errors.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServiceWorkerTimeoutError = exports.MessageBusNotInitializedError = void 0;
+class MessageBusNotInitializedError extends Error {
+    constructor() {
+        super("MessageBus not initialized");
+        this.name = "MessageBusNotInitializedError";
+    }
+}
+exports.MessageBusNotInitializedError = MessageBusNotInitializedError;
+class ServiceWorkerTimeoutError extends Error {
+    constructor(detail) {
+        super(detail);
+        this.name = "ServiceWorkerTimeoutError";
+    }
+}
+exports.ServiceWorkerTimeoutError = ServiceWorkerTimeoutError;

package/dist/cjs/worker/messageBus.js

@@ -8,6 +8,7 @@ const delegator_1 = require("../providers/delegator");
 const identity_1 = require("../identity");
 const wallet_1 = require("../wallet/wallet");
 const base_1 = require("@scure/base");
+const errors_1 = require("./errors");
 class MessageBus {
     constructor(walletRepository, contractRepository, { messageHandlers, tickIntervalMs = 10000, messageTimeoutMs = 30000, debug = false, buildServices, }) {
         this.walletRepository = walletRepository;
@@ -183,6 +184,10 @@ class MessageBus {
     }
     async processMessage(event) {
         const { id, tag, broadcast } = event.data;
+        if (tag === "PING") {
+            event.source?.postMessage({ id, tag: "PONG" });
+            return;
+        }
         if (tag === "INITIALIZE_MESSAGE_BUS") {
             if (this.debug) {
                 console.log("Init Command received");
@@ -207,7 +212,7 @@ class MessageBus {
             event.source?.postMessage({
                 id,
                 tag: tag ?? "unknown",
-                error: new Error("MessageBus not initialized"),
+                error: new errors_1.MessageBusNotInitializedError(),
             });
             return;
         }
@@ -278,7 +283,7 @@ class MessageBus {
             return promise;
         return new Promise((resolve, reject) => {
             const timer = self.setTimeout(() => {
-                reject(new Error(`Message handler timed out after ${this.messageTimeoutMs}ms (${label})`));
+                reject(new errors_1.ServiceWorkerTimeoutError(`Message handler timed out after ${this.messageTimeoutMs}ms (${label})`));
             }, this.messageTimeoutMs);
             promise.then((val) => {
                 self.clearTimeout(timer);

package/dist/esm/identity/seedIdentity.js

@@ -102,7 +102,7 @@ export class SeedIdentity {
     static fromSeed(seed, opts) {
         const descriptor = hasDescriptor(opts)
             ? opts.descriptor
-            : buildDescriptor(seed, opts.isMainnet);
+            : buildDescriptor(seed, opts.isMainnet ?? true);
         return new SeedIdentity(seed, descriptor);
     }
     async xOnlyPublicKey() {
@@ -190,7 +190,7 @@ export class MnemonicIdentity extends SeedIdentity {
         const seed = mnemonicToSeedSync(phrase, passphrase);
         const descriptor = hasDescriptor(opts)
             ? opts.descriptor
-            : buildDescriptor(seed, opts.isMainnet);
+            : buildDescriptor(seed, opts.isMainnet ?? true);
         return new MnemonicIdentity(seed, descriptor);
     }
 }

package/dist/esm/index.js

@@ -39,7 +39,8 @@ export * as asset from './extension/asset/index.js';
 // Contracts
 import { ContractManager, ContractWatcher, contractHandlers, DefaultContractHandler, DelegateContractHandler, VHTLCContractHandler, encodeArkContract, decodeArkContract, contractFromArkContract, contractFromArkContractWithAddress, isArkContract, } from './contracts/index.js';
 import { closeDatabase, openDatabase } from './repositories/indexedDB/manager.js';
-import { WalletMessageHandler } from './wallet/serviceWorker/wallet-message-handler.js';
+import { WalletMessageHandler, WalletNotInitializedError, ReadonlyWalletError, DelegatorNotConfiguredError, } from './wallet/serviceWorker/wallet-message-handler.js';
+import { MessageBusNotInitializedError, ServiceWorkerTimeoutError, } from './worker/errors.js';
 export { 
 // Wallets
 Wallet, ReadonlyWallet, SingleKey, ReadonlySingleKey, SeedIdentity, MnemonicIdentity, ReadonlyDescriptorIdentity, OnchainWallet, Ramps, VtxoManager, DelegatorManagerImpl, RestDelegatorProvider, 
@@ -50,7 +51,7 @@ ArkAddress, DefaultVtxo, DelegateVtxo, VtxoScript, VHTLC,
 // Enums
 TxType, IndexerTxType, ChainTxType, SettlementEventType, 
 // Service Worker
-setupServiceWorker, MessageBus, WalletMessageHandler, ServiceWorkerWallet, ServiceWorkerReadonlyWallet, 
+setupServiceWorker, MessageBus, WalletMessageHandler, WalletNotInitializedError, ReadonlyWalletError, DelegatorNotConfiguredError, MessageBusNotInitializedError, ServiceWorkerTimeoutError, ServiceWorkerWallet, ServiceWorkerReadonlyWallet, 
 // Tapscript
 decodeTapscript, MultisigTapscript, CSVMultisigTapscript, ConditionCSVMultisigTapscript, ConditionMultisigTapscript, CLTVMultisigTapscript, TapTreeCoder, 
 // Ark PSBT fields

package/dist/esm/wallet/serviceWorker/wallet-message-handler.js

@@ -1,6 +1,24 @@
 import { RestIndexerProvider } from '../../providers/indexer.js';
 import { isExpired, isRecoverable, isSpendable, isSubdust, } from '../index.js';
 import { extendCoin, extendVirtualCoin } from '../utils.js';
+export class WalletNotInitializedError extends Error {
+    constructor() {
+        super("Wallet handler not initialized");
+        this.name = "WalletNotInitializedError";
+    }
+}
+export class ReadonlyWalletError extends Error {
+    constructor() {
+        super("Read-only wallet: operation requires signing");
+        this.name = "ReadonlyWalletError";
+    }
+}
+export class DelegatorNotConfiguredError extends Error {
+    constructor() {
+        super("Delegator not configured");
+        this.name = "DelegatorNotConfiguredError";
+    }
+}
 export const DEFAULT_MESSAGE_TAG = "WALLET_UPDATER";
 export class WalletMessageHandler {
     /**
@@ -21,7 +39,31 @@ export class WalletMessageHandler {
         this.walletRepository = repositories.walletRepository;
     }
     async stop() {
-        // optional cleanup and persistence
+        if (this.incomingFundsSubscription) {
+            this.incomingFundsSubscription();
+            this.incomingFundsSubscription = undefined;
+        }
+        if (this.contractEventsSubscription) {
+            this.contractEventsSubscription();
+            this.contractEventsSubscription = undefined;
+        }
+        // Dispose the wallet to stop VtxoManager background tasks
+        // (auto-renewal, boarding UTXO polling) and ContractWatcher.
+        try {
+            if (this.wallet) {
+                await this.wallet.dispose();
+            }
+            else if (this.readonlyWallet) {
+                await this.readonlyWallet.dispose();
+            }
+        }
+        catch (_) {
+            // best-effort teardown
+        }
+        this.wallet = undefined;
+        this.readonlyWallet = undefined;
+        this.arkProvider = undefined;
+        this.indexerProvider = undefined;
     }
     async tick(_now) {
         const results = await Promise.allSettled(this.onNextTick.map((fn) => fn()));
@@ -44,7 +86,7 @@ export class WalletMessageHandler {
     }
     requireWallet() {
         if (!this.wallet) {
-            throw new Error("Read-only wallet: operation requires signing");
+            throw new ReadonlyWalletError();
         }
         return this.wallet;
     }
@@ -66,7 +108,7 @@ export class WalletMessageHandler {
         if (!this.readonlyWallet) {
             return this.tagged({
                 id,
-                error: new Error("Wallet handler not initialized"),
+                error: new WalletNotInitializedError(),
             });
         }
         try {
@@ -294,7 +336,7 @@ export class WalletMessageHandler {
                     const wallet = this.requireWallet();
                     const delegatorManager = await wallet.getDelegatorManager();
                     if (!delegatorManager) {
-                        throw new Error("Delegator not configured");
+                        throw new DelegatorNotConfiguredError();
                     }
                     const info = await delegatorManager.getDelegateInfo();
                     return this.tagged({
@@ -303,6 +345,83 @@ export class WalletMessageHandler {
                         payload: { info },
                     });
                 }
+                case "RECOVER_VTXOS": {
+                    const wallet = this.requireWallet();
+                    const vtxoManager = await wallet.getVtxoManager();
+                    const txid = await vtxoManager.recoverVtxos((e) => {
+                        this.scheduleForNextTick(() => this.tagged({
+                            id,
+                            type: "RECOVER_VTXOS_EVENT",
+                            payload: e,
+                        }));
+                    });
+                    return this.tagged({
+                        id,
+                        type: "RECOVER_VTXOS_SUCCESS",
+                        payload: { txid },
+                    });
+                }
+                case "GET_RECOVERABLE_BALANCE": {
+                    const wallet = this.requireWallet();
+                    const vtxoManager = await wallet.getVtxoManager();
+                    const balance = await vtxoManager.getRecoverableBalance();
+                    return this.tagged({
+                        id,
+                        type: "RECOVERABLE_BALANCE",
+                        payload: {
+                            recoverable: balance.recoverable.toString(),
+                            subdust: balance.subdust.toString(),
+                            includesSubdust: balance.includesSubdust,
+                            vtxoCount: balance.vtxoCount,
+                        },
+                    });
+                }
+                case "GET_EXPIRING_VTXOS": {
+                    const wallet = this.requireWallet();
+                    const vtxoManager = await wallet.getVtxoManager();
+                    const vtxos = await vtxoManager.getExpiringVtxos(message.payload.thresholdMs);
+                    return this.tagged({
+                        id,
+                        type: "EXPIRING_VTXOS",
+                        payload: { vtxos },
+                    });
+                }
+                case "RENEW_VTXOS": {
+                    const wallet = this.requireWallet();
+                    const vtxoManager = await wallet.getVtxoManager();
+                    const txid = await vtxoManager.renewVtxos((e) => {
+                        this.scheduleForNextTick(() => this.tagged({
+                            id,
+                            type: "RENEW_VTXOS_EVENT",
+                            payload: e,
+                        }));
+                    });
+                    return this.tagged({
+                        id,
+                        type: "RENEW_VTXOS_SUCCESS",
+                        payload: { txid },
+                    });
+                }
+                case "GET_EXPIRED_BOARDING_UTXOS": {
+                    const wallet = this.requireWallet();
+                    const vtxoManager = await wallet.getVtxoManager();
+                    const utxos = await vtxoManager.getExpiredBoardingUtxos();
+                    return this.tagged({
+                        id,
+                        type: "EXPIRED_BOARDING_UTXOS",
+                        payload: { utxos },
+                    });
+                }
+                case "SWEEP_EXPIRED_BOARDING_UTXOS": {
+                    const wallet = this.requireWallet();
+                    const vtxoManager = await wallet.getVtxoManager();
+                    const txid = await vtxoManager.sweepExpiredBoardingUtxos();
+                    return this.tagged({
+                        id,
+                        type: "SWEEP_EXPIRED_BOARDING_UTXOS_SUCCESS",
+                        payload: { txid },
+                    });
+                }
                 default:
                     console.error("Unknown message type", message);
                     throw new Error("Unknown message");
@@ -478,6 +597,17 @@ export class WalletMessageHandler {
                 }
             });
         await this.ensureContractEventBroadcasting();
+        // Eagerly start the VtxoManager so its background tasks (auto-renewal,
+        // boarding UTXO polling/sweep) run inside the service worker without
+        // waiting for a client to send a vtxo-manager message first.
+        if (this.wallet) {
+            try {
+                await this.wallet.getVtxoManager();
+            }
+            catch (error) {
+                console.error("Error starting VtxoManager:", error);
+            }
+        }
     }
     async handleSettle(message) {
         const wallet = this.requireWallet();
@@ -520,7 +650,7 @@ export class WalletMessageHandler {
         const wallet = this.requireWallet();
         const delegatorManager = await wallet.getDelegatorManager();
         if (!delegatorManager) {
-            throw new Error("Delegator not configured");
+            throw new DelegatorNotConfiguredError();
         }
         const { vtxoOutpoints, destination, delegateAt } = message.payload;
         const allVtxos = await wallet.getVtxos();
@@ -547,7 +677,7 @@ export class WalletMessageHandler {
     }
     async handleGetVtxos(message) {
         if (!this.readonlyWallet) {
-            throw new Error("Wallet handler not initialized");
+            throw new WalletNotInitializedError();
         }
         const vtxos = await this.getSpendableVtxos();
         const dustAmount = this.readonlyWallet.dustAmount;