@arkade-os/sdk 0.4.6 → 0.4.8

package/dist/esm/wallet/wallet.js

@@ -57,6 +57,19 @@ export 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 ReadonlyAssetManager(this.indexerProvider);
     }
@@ -84,6 +97,24 @@ export class ReadonlyWallet {
         const indexerProvider = config.indexerProvider || new RestIndexerProvider(indexerUrl);
         const info = await arkProvider.getInfo();
         const network = 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 || ESPLORA_URL[info.network];
         // Use provided onchainProvider instance or create a new one
@@ -658,6 +689,20 @@ export class ReadonlyWallet {
  * ```
  */
 export 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) {
@@ -667,6 +712,13 @@ export 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 = {
@@ -805,40 +857,42 @@ export 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 = 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 = 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,
@@ -846,6 +900,9 @@ export 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
@@ -1347,6 +1404,9 @@ export 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/esm/worker/errors.js

@@ -0,0 +1,12 @@
+export class MessageBusNotInitializedError extends Error {
+    constructor() {
+        super("MessageBus not initialized");
+        this.name = "MessageBusNotInitializedError";
+    }
+}
+export class ServiceWorkerTimeoutError extends Error {
+    constructor(detail) {
+        super(detail);
+        this.name = "ServiceWorkerTimeoutError";
+    }
+}

package/dist/esm/worker/messageBus.js

@@ -5,6 +5,7 @@ import { RestDelegatorProvider } from '../providers/delegator.js';
 import { ReadonlySingleKey, SingleKey } from '../identity/index.js';
 import { ReadonlyWallet, Wallet } from '../wallet/wallet.js';
 import { hex } from "@scure/base";
+import { MessageBusNotInitializedError, ServiceWorkerTimeoutError, } from './errors.js';
 export class MessageBus {
     constructor(walletRepository, contractRepository, { messageHandlers, tickIntervalMs = 10000, messageTimeoutMs = 30000, debug = false, buildServices, }) {
         this.walletRepository = walletRepository;
@@ -180,6 +181,10 @@ export 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");
@@ -204,7 +209,7 @@ export class MessageBus {
             event.source?.postMessage({
                 id,
                 tag: tag ?? "unknown",
-                error: new Error("MessageBus not initialized"),
+                error: new MessageBusNotInitializedError(),
             });
             return;
         }
@@ -275,7 +280,7 @@ export 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 ServiceWorkerTimeoutError(`Message handler timed out after ${this.messageTimeoutMs}ms (${label})`));
             }, this.messageTimeoutMs);
             promise.then((val) => {
                 self.clearTimeout(timer);

package/dist/types/identity/seedIdentity.d.ts

@@ -3,8 +3,11 @@ import { Transaction } from "../utils/transaction";
 import { SignerSession } from "../tree/signingSession";
 /** Use default BIP86 derivation with network selection. */
 export interface NetworkOptions {
-    /** Mainnet (coin type 0) or testnet (coin type 1). */
-    isMainnet: boolean;
+    /**
+     * Mainnet (coin type 0) or testnet (coin type 1).
+     * @default true
+     */
+    isMainnet?: boolean;
 }
 /** Use a custom output descriptor for derivation. */
 export interface DescriptorOptions {

package/dist/types/index.d.ts

@@ -16,7 +16,7 @@ import { TxTree, TxTreeNode } from "./tree/txTree";
 import { SignerSession, TreeNonces, TreePartialSigs } from "./tree/signingSession";
 import { Ramps } from "./wallet/ramps";
 import { isVtxoExpiringSoon, VtxoManager } from "./wallet/vtxo-manager";
-import type { SettlementConfig } from "./wallet/vtxo-manager";
+import type { IVtxoManager, SettlementConfig } from "./wallet/vtxo-manager";
 import { ServiceWorkerWallet, ServiceWorkerReadonlyWallet } from "./wallet/serviceWorker/wallet";
 import { OnchainWallet } from "./wallet/onchain";
 import { setupServiceWorker } from "./worker/browser/utils";
@@ -47,6 +47,7 @@ import { ContractManager, ContractWatcher, contractHandlers, DefaultContractHand
 import type { Contract, ContractVtxo, ContractState, ContractEvent, ContractEventCallback, ContractBalance, ContractWithVtxos, ContractHandler, PathSelection, PathContext, ContractManagerConfig, CreateContractParams, ContractWatcherConfig, ParsedArkContract, DefaultContractParams, DelegateContractParams, VHTLCContractParams } from "./contracts";
 import { IContractManager } from "./contracts/contractManager";
 import { closeDatabase, openDatabase } from "./repositories/indexedDB/manager";
-import { WalletMessageHandler } from "./wallet/serviceWorker/wallet-message-handler";
-export { Wallet, ReadonlyWallet, SingleKey, ReadonlySingleKey, SeedIdentity, MnemonicIdentity, ReadonlyDescriptorIdentity, OnchainWallet, Ramps, VtxoManager, DelegatorManagerImpl, RestDelegatorProvider, ESPLORA_URL, EsploraProvider, RestArkProvider, RestIndexerProvider, ArkAddress, DefaultVtxo, DelegateVtxo, VtxoScript, VHTLC, TxType, IndexerTxType, ChainTxType, SettlementEventType, setupServiceWorker, MessageBus, WalletMessageHandler, ServiceWorkerWallet, ServiceWorkerReadonlyWallet, decodeTapscript, MultisigTapscript, CSVMultisigTapscript, ConditionCSVMultisigTapscript, ConditionMultisigTapscript, CLTVMultisigTapscript, TapTreeCoder, ArkPsbtFieldKey, ArkPsbtFieldKeyType, setArkPsbtField, getArkPsbtFields, CosignerPublicKey, VtxoTreeExpiry, VtxoTaprootTree, ConditionWitness, buildOffchainTx, verifyTapscriptSignatures, waitForIncomingFunds, hasBoardingTxExpired, combineTapscriptSigs, isVtxoExpiringSoon, isValidArkAddress, ArkNote, networks, closeDatabase, openDatabase, IndexedDBWalletRepository, IndexedDBContractRepository, InMemoryWalletRepository, InMemoryContractRepository, MIGRATION_KEY, migrateWalletRepository, requiresMigration, getMigrationStatus, rollbackMigration, WalletRepositoryImpl, ContractRepositoryImpl, Intent, BIP322, TxTree, P2A, Unroll, Transaction, ArkError, maybeArkError, Batch, validateVtxoTxGraph, validateConnectorsTxGraph, buildForfeitTx, isRecoverable, isSpendable, isSubdust, isExpired, getSequence, ContractManager, ContractWatcher, contractHandlers, DefaultContractHandler, DelegateContractHandler, VHTLCContractHandler, encodeArkContract, decodeArkContract, contractFromArkContract, contractFromArkContractWithAddress, isArkContract, };
-export type { Identity, ReadonlyIdentity, IWallet, IReadonlyWallet, BaseWalletConfig, WalletConfig, ReadonlyWalletConfig, ProviderClass, ArkTransaction, Coin, ExtendedCoin, ExtendedVirtualCoin, WalletBalance, SendBitcoinParams, SettleParams, Status, VirtualStatus, Outpoint, VirtualCoin, TxKey, TapscriptType, ArkTxInput, OffchainTx, TapLeaves, IncomingFunds, SeedIdentityOptions, MnemonicOptions, NetworkOptions, DescriptorOptions, IndexerProvider, PageResponse, BatchInfo, ChainTx, CommitmentTx, TxHistoryRecord, Vtxo, VtxoChain, Tx, OnchainProvider, ArkProvider, SettlementEvent, FeeInfo, ArkInfo, SignedIntent, Output, TxNotification, ExplorerTransaction, BatchFinalizationEvent, BatchFinalizedEvent, BatchFailedEvent, TreeSigningStartedEvent, TreeNoncesEvent, BatchStartedEvent, TreeTxEvent, TreeSignatureEvent, ScheduledSession, PaginationOptions, SubscriptionResponse, SubscriptionHeartbeat, SubscriptionEvent, Network, NetworkName, ArkTapscript, RelativeTimelock, EncodedVtxoScript, TapLeafScript, SignerSession, TreeNonces, TreePartialSigs, GetVtxosFilter, SettlementConfig, Asset, Recipient, IssuanceParams, IssuanceResult, ReissuanceParams, BurnParams, AssetDetails, AssetMetadata, KnownMetadata, Nonces, PartialSig, ArkPsbtFieldCoder, TxTreeNode, AnchorBumper, StorageConfig, Contract, ContractVtxo, ContractState, ContractEvent, ContractEventCallback, ContractBalance, ContractWithVtxos, ContractHandler, IContractManager, PathSelection, PathContext, ContractManagerConfig, CreateContractParams, ContractWatcherConfig, ParsedArkContract, DefaultContractParams, DelegateContractParams, VHTLCContractParams, MessageHandler, RequestEnvelope, ResponseEnvelope, IDelegatorManager, DelegatorProvider, DelegateInfo, DelegateOptions, WalletRepository, ContractRepository, MigrationStatus, };
+import { WalletMessageHandler, WalletNotInitializedError, ReadonlyWalletError, DelegatorNotConfiguredError } from "./wallet/serviceWorker/wallet-message-handler";
+import { MessageBusNotInitializedError, ServiceWorkerTimeoutError } from "./worker/errors";
+export { Wallet, ReadonlyWallet, SingleKey, ReadonlySingleKey, SeedIdentity, MnemonicIdentity, ReadonlyDescriptorIdentity, OnchainWallet, Ramps, VtxoManager, DelegatorManagerImpl, RestDelegatorProvider, ESPLORA_URL, EsploraProvider, RestArkProvider, RestIndexerProvider, ArkAddress, DefaultVtxo, DelegateVtxo, VtxoScript, VHTLC, TxType, IndexerTxType, ChainTxType, SettlementEventType, setupServiceWorker, MessageBus, WalletMessageHandler, WalletNotInitializedError, ReadonlyWalletError, DelegatorNotConfiguredError, MessageBusNotInitializedError, ServiceWorkerTimeoutError, ServiceWorkerWallet, ServiceWorkerReadonlyWallet, decodeTapscript, MultisigTapscript, CSVMultisigTapscript, ConditionCSVMultisigTapscript, ConditionMultisigTapscript, CLTVMultisigTapscript, TapTreeCoder, ArkPsbtFieldKey, ArkPsbtFieldKeyType, setArkPsbtField, getArkPsbtFields, CosignerPublicKey, VtxoTreeExpiry, VtxoTaprootTree, ConditionWitness, buildOffchainTx, verifyTapscriptSignatures, waitForIncomingFunds, hasBoardingTxExpired, combineTapscriptSigs, isVtxoExpiringSoon, isValidArkAddress, ArkNote, networks, closeDatabase, openDatabase, IndexedDBWalletRepository, IndexedDBContractRepository, InMemoryWalletRepository, InMemoryContractRepository, MIGRATION_KEY, migrateWalletRepository, requiresMigration, getMigrationStatus, rollbackMigration, WalletRepositoryImpl, ContractRepositoryImpl, Intent, BIP322, TxTree, P2A, Unroll, Transaction, ArkError, maybeArkError, Batch, validateVtxoTxGraph, validateConnectorsTxGraph, buildForfeitTx, isRecoverable, isSpendable, isSubdust, isExpired, getSequence, ContractManager, ContractWatcher, contractHandlers, DefaultContractHandler, DelegateContractHandler, VHTLCContractHandler, encodeArkContract, decodeArkContract, contractFromArkContract, contractFromArkContractWithAddress, isArkContract, };
+export type { Identity, ReadonlyIdentity, IWallet, IReadonlyWallet, BaseWalletConfig, WalletConfig, ReadonlyWalletConfig, ProviderClass, ArkTransaction, Coin, ExtendedCoin, ExtendedVirtualCoin, WalletBalance, SendBitcoinParams, SettleParams, Status, VirtualStatus, Outpoint, VirtualCoin, TxKey, TapscriptType, ArkTxInput, OffchainTx, TapLeaves, IncomingFunds, SeedIdentityOptions, MnemonicOptions, NetworkOptions, DescriptorOptions, IndexerProvider, PageResponse, BatchInfo, ChainTx, CommitmentTx, TxHistoryRecord, Vtxo, VtxoChain, Tx, OnchainProvider, ArkProvider, SettlementEvent, FeeInfo, ArkInfo, SignedIntent, Output, TxNotification, ExplorerTransaction, BatchFinalizationEvent, BatchFinalizedEvent, BatchFailedEvent, TreeSigningStartedEvent, TreeNoncesEvent, BatchStartedEvent, TreeTxEvent, TreeSignatureEvent, ScheduledSession, PaginationOptions, SubscriptionResponse, SubscriptionHeartbeat, SubscriptionEvent, Network, NetworkName, ArkTapscript, RelativeTimelock, EncodedVtxoScript, TapLeafScript, SignerSession, TreeNonces, TreePartialSigs, GetVtxosFilter, SettlementConfig, IVtxoManager, Asset, Recipient, IssuanceParams, IssuanceResult, ReissuanceParams, BurnParams, AssetDetails, AssetMetadata, KnownMetadata, Nonces, PartialSig, ArkPsbtFieldCoder, TxTreeNode, AnchorBumper, StorageConfig, Contract, ContractVtxo, ContractState, ContractEvent, ContractEventCallback, ContractBalance, ContractWithVtxos, ContractHandler, IContractManager, PathSelection, PathContext, ContractManagerConfig, CreateContractParams, ContractWatcherConfig, ParsedArkContract, DefaultContractParams, DelegateContractParams, VHTLCContractParams, MessageHandler, RequestEnvelope, ResponseEnvelope, IDelegatorManager, DelegatorProvider, DelegateInfo, DelegateOptions, WalletRepository, ContractRepository, MigrationStatus, };

package/dist/types/wallet/serviceWorker/wallet-message-handler.d.ts

@@ -1,10 +1,19 @@
 import { SettlementEvent } from "../../providers/ark";
 import type { Contract, ContractEvent, ContractWithVtxos, GetContractsFilter, PathSelection } from "../../contracts";
 import type { CreateContractParams, GetAllSpendingPathsOptions, GetSpendablePathsOptions } from "../../contracts/contractManager";
-import { ArkTransaction, AssetDetails, BurnParams, ExtendedCoin, GetVtxosFilter, IssuanceParams, IssuanceResult, IWallet, Recipient, ReissuanceParams, SendBitcoinParams, SettleParams, WalletBalance } from "../index";
+import { ArkTransaction, AssetDetails, BurnParams, ExtendedCoin, ExtendedVirtualCoin, GetVtxosFilter, IssuanceParams, IssuanceResult, IWallet, Recipient, ReissuanceParams, SendBitcoinParams, SettleParams, WalletBalance } from "../index";
 import { DelegateInfo } from "../../providers/delegator";
 import { MessageHandler, RequestEnvelope, ResponseEnvelope } from "../../worker/messageBus";
 import { Transaction } from "../../utils/transaction";
+export declare class WalletNotInitializedError extends Error {
+    constructor();
+}
+export declare class ReadonlyWalletError extends Error {
+    constructor();
+}
+export declare class DelegatorNotConfiguredError extends Error {
+    constructor();
+}
 export declare const DEFAULT_MESSAGE_TAG = "WALLET_UPDATER";
 export type RequestInitWallet = RequestEnvelope & {
     type: "INIT_WALLET";
@@ -236,6 +245,14 @@ export type ResponseSettleEvent = ResponseEnvelope & {
     type: "SETTLE_EVENT";
     payload: SettlementEvent;
 };
+export type ResponseRecoverVtxosEvent = ResponseEnvelope & {
+    type: "RECOVER_VTXOS_EVENT";
+    payload: SettlementEvent;
+};
+export type ResponseRenewVtxosEvent = ResponseEnvelope & {
+    type: "RENEW_VTXOS_EVENT";
+    payload: SettlementEvent;
+};
 export type ResponseUtxoUpdate = ResponseEnvelope & {
     broadcast: true;
     type: "UTXO_UPDATE";
@@ -355,8 +372,68 @@ export type ResponseGetDelegateInfo = ResponseEnvelope & {
         info: DelegateInfo;
     };
 };
-export type WalletUpdaterRequest = RequestInitWallet | RequestSettle | RequestSendBitcoin | RequestGetAddress | RequestGetBoardingAddress | RequestGetBalance | RequestGetVtxos | RequestGetBoardingUtxos | RequestGetTransactionHistory | RequestGetStatus | RequestClear | RequestReloadWallet | RequestSignTransaction | RequestCreateContract | RequestGetContracts | RequestGetContractsWithVtxos | RequestUpdateContract | RequestDeleteContract | RequestGetSpendablePaths | RequestGetAllSpendingPaths | RequestIsContractManagerWatching | RequestSend | RequestGetAssetDetails | RequestIssue | RequestReissue | RequestBurn | RequestDelegate | RequestGetDelegateInfo;
-export type WalletUpdaterResponse = ResponseEnvelope & (ResponseInitWallet | ResponseSettle | ResponseSettleEvent | ResponseSendBitcoin | ResponseGetAddress | ResponseGetBoardingAddress | ResponseGetBalance | ResponseGetVtxos | ResponseGetBoardingUtxos | ResponseGetTransactionHistory | ResponseGetStatus | ResponseClear | ResponseReloadWallet | ResponseUtxoUpdate | ResponseVtxoUpdate | ResponseSignTransaction | ResponseCreateContract | ResponseGetContracts | ResponseGetContractsWithVtxos | ResponseUpdateContract | ResponseDeleteContract | ResponseGetSpendablePaths | ResponseGetAllSpendingPaths | ResponseIsContractManagerWatching | ResponseContractEvent | ResponseSend | ResponseGetAssetDetails | ResponseIssue | ResponseReissue | ResponseBurn | ResponseDelegate | ResponseGetDelegateInfo);
+export type RequestRecoverVtxos = RequestEnvelope & {
+    type: "RECOVER_VTXOS";
+};
+export type ResponseRecoverVtxos = ResponseEnvelope & {
+    type: "RECOVER_VTXOS_SUCCESS";
+    payload: {
+        txid: string;
+    };
+};
+export type RequestGetRecoverableBalance = RequestEnvelope & {
+    type: "GET_RECOVERABLE_BALANCE";
+};
+export type ResponseGetRecoverableBalance = ResponseEnvelope & {
+    type: "RECOVERABLE_BALANCE";
+    payload: {
+        recoverable: string;
+        subdust: string;
+        includesSubdust: boolean;
+        vtxoCount: number;
+    };
+};
+export type RequestGetExpiringVtxos = RequestEnvelope & {
+    type: "GET_EXPIRING_VTXOS";
+    payload: {
+        thresholdMs?: number;
+    };
+};
+export type ResponseGetExpiringVtxos = ResponseEnvelope & {
+    type: "EXPIRING_VTXOS";
+    payload: {
+        vtxos: ExtendedVirtualCoin[];
+    };
+};
+export type RequestRenewVtxos = RequestEnvelope & {
+    type: "RENEW_VTXOS";
+};
+export type ResponseRenewVtxos = ResponseEnvelope & {
+    type: "RENEW_VTXOS_SUCCESS";
+    payload: {
+        txid: string;
+    };
+};
+export type RequestGetExpiredBoardingUtxos = RequestEnvelope & {
+    type: "GET_EXPIRED_BOARDING_UTXOS";
+};
+export type ResponseGetExpiredBoardingUtxos = ResponseEnvelope & {
+    type: "EXPIRED_BOARDING_UTXOS";
+    payload: {
+        utxos: ExtendedCoin[];
+    };
+};
+export type RequestSweepExpiredBoardingUtxos = RequestEnvelope & {
+    type: "SWEEP_EXPIRED_BOARDING_UTXOS";
+};
+export type ResponseSweepExpiredBoardingUtxos = ResponseEnvelope & {
+    type: "SWEEP_EXPIRED_BOARDING_UTXOS_SUCCESS";
+    payload: {
+        txid: string;
+    };
+};
+export type WalletUpdaterRequest = RequestInitWallet | RequestSettle | RequestSendBitcoin | RequestGetAddress | RequestGetBoardingAddress | RequestGetBalance | RequestGetVtxos | RequestGetBoardingUtxos | RequestGetTransactionHistory | RequestGetStatus | RequestClear | RequestReloadWallet | RequestSignTransaction | RequestCreateContract | RequestGetContracts | RequestGetContractsWithVtxos | RequestUpdateContract | RequestDeleteContract | RequestGetSpendablePaths | RequestGetAllSpendingPaths | RequestIsContractManagerWatching | RequestSend | RequestGetAssetDetails | RequestIssue | RequestReissue | RequestBurn | RequestDelegate | RequestGetDelegateInfo | RequestRecoverVtxos | RequestGetRecoverableBalance | RequestGetExpiringVtxos | RequestRenewVtxos | RequestGetExpiredBoardingUtxos | RequestSweepExpiredBoardingUtxos;
+export type WalletUpdaterResponse = ResponseEnvelope & (ResponseInitWallet | ResponseSettle | ResponseSettleEvent | ResponseSendBitcoin | ResponseGetAddress | ResponseGetBoardingAddress | ResponseGetBalance | ResponseGetVtxos | ResponseGetBoardingUtxos | ResponseGetTransactionHistory | ResponseGetStatus | ResponseClear | ResponseReloadWallet | ResponseUtxoUpdate | ResponseVtxoUpdate | ResponseSignTransaction | ResponseCreateContract | ResponseGetContracts | ResponseGetContractsWithVtxos | ResponseUpdateContract | ResponseDeleteContract | ResponseGetSpendablePaths | ResponseGetAllSpendingPaths | ResponseIsContractManagerWatching | ResponseContractEvent | ResponseSend | ResponseGetAssetDetails | ResponseIssue | ResponseReissue | ResponseBurn | ResponseDelegate | ResponseGetDelegateInfo | ResponseRecoverVtxos | ResponseRecoverVtxosEvent | ResponseGetRecoverableBalance | ResponseGetExpiringVtxos | ResponseRenewVtxos | ResponseRenewVtxosEvent | ResponseGetExpiredBoardingUtxos | ResponseSweepExpiredBoardingUtxos);
 export declare class WalletMessageHandler implements MessageHandler<WalletUpdaterRequest, WalletUpdaterResponse> {
     readonly messageTag: string;
     private wallet;

package/dist/types/wallet/serviceWorker/wallet.d.ts

@@ -6,6 +6,7 @@ import { ContractRepository } from "../../repositories/contractRepository";
 import { RequestInitWallet, ResponseGetStatus, WalletUpdaterRequest, WalletUpdaterResponse } from "./wallet-message-handler";
 import type { IContractManager } from "../../contracts/contractManager";
 import type { IDelegatorManager } from "../delegator";
+import type { IVtxoManager } from "../vtxo-manager";
 type PrivateKeyIdentity = Identity & {
     toHex(): string;
 };
@@ -82,6 +83,8 @@ export declare class ServiceWorkerReadonlyWallet implements IReadonlyWallet {
     protected initWalletPayload: RequestInitWallet["payload"] | null;
     protected messageBusTimeoutMs?: number;
     private reinitPromise;
+    private pingPromise;
+    private inflightRequests;
     get assetManager(): IReadonlyAssetManager;
     protected constructor(serviceWorker: ServiceWorker, identity: ReadonlyIdentity, walletRepository: WalletRepository, contractRepository: ContractRepository, messageTag: string);
     static create(options: ServiceWorkerWalletCreateOptions): Promise<ServiceWorkerReadonlyWallet>;
@@ -108,7 +111,11 @@ export declare class ServiceWorkerReadonlyWallet implements IReadonlyWallet {
      */
     static setup(options: ServiceWorkerWalletSetupOptions): Promise<ServiceWorkerReadonlyWallet>;
     private sendMessageDirect;
+    private sendMessageStreaming;
     protected sendMessage(request: WalletUpdaterRequest): Promise<WalletUpdaterResponse>;
+    private pingServiceWorker;
+    private sendMessageWithRetry;
+    protected sendMessageWithEvents(request: WalletUpdaterRequest, onEvent: (response: WalletUpdaterResponse) => void, isComplete: (response: WalletUpdaterResponse) => boolean): Promise<WalletUpdaterResponse>;
     private reinitialize;
     clear(): Promise<void>;
     getAddress(): Promise<string>;
@@ -157,5 +164,6 @@ export declare class ServiceWorkerWallet extends ServiceWorkerReadonlyWallet imp
     settle(params?: SettleParams, callback?: (event: SettlementEvent) => void): Promise<string>;
     send(...recipients: Recipient[]): Promise<string>;
     getDelegatorManager(): Promise<IDelegatorManager | undefined>;
+    getVtxoManager(): Promise<IVtxoManager>;
 }
 export {};

package/dist/types/wallet/vtxo-manager.d.ts

@@ -145,7 +145,21 @@ export declare function getExpiringAndRecoverableVtxos(vtxos: ExtendedVirtualCoi
  * }
  * ```
  */
-export declare class VtxoManager implements AsyncDisposable {
+export interface IVtxoManager {
+    recoverVtxos(eventCallback?: (event: SettlementEvent) => void): Promise<string>;
+    getRecoverableBalance(): Promise<{
+        recoverable: bigint;
+        subdust: bigint;
+        includesSubdust: boolean;
+        vtxoCount: number;
+    }>;
+    getExpiringVtxos(thresholdMs?: number): Promise<ExtendedVirtualCoin[]>;
+    renewVtxos(eventCallback?: (event: SettlementEvent) => void): Promise<string>;
+    getExpiredBoardingUtxos(): Promise<ExtendedCoin[]>;
+    sweepExpiredBoardingUtxos(): Promise<string>;
+    dispose(): Promise<void>;
+}
+export declare class VtxoManager implements AsyncDisposable, IVtxoManager {
     readonly wallet: IWallet;
     /** @deprecated Use settlementConfig instead */
     readonly renewalConfig?: RenewalConfig | undefined;
@@ -153,10 +167,12 @@ export declare class VtxoManager implements AsyncDisposable {
     private contractEventsSubscription?;
     private readonly contractEventsSubscriptionReady;
     private disposePromise?;
-    private pollIntervalId?;
+    private pollTimeoutId?;
     private knownBoardingUtxos;
     private sweptBoardingUtxos;
     private pollInProgress;
+    private consecutivePollFailures;
+    private static readonly MAX_BACKOFF_MS;
     constructor(wallet: IWallet, 
     /** @deprecated Use settlementConfig instead */
     renewalConfig?: RenewalConfig | undefined, settlementConfig?: SettlementConfig | false);
@@ -323,12 +339,18 @@ export declare class VtxoManager implements AsyncDisposable {
     /** Returns the wallet's identity for transaction signing. */
     private getIdentity;
     private initializeSubscription;
+    /** Computes the next poll delay, applying exponential backoff on failures. */
+    private getNextPollDelay;
     /**
      * 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.
      */
     private startBoardingUtxoPoll;
+    private schedulePoll;
     private pollBoardingUtxos;
     /**
      * Auto-settle new (unexpired) boarding UTXOs into the Ark.

package/dist/types/wallet/wallet.d.ts

@@ -171,6 +171,14 @@ export declare class Wallet extends ReadonlyWallet implements IWallet {
     private _vtxoManager?;
     private _vtxoManagerInitializing?;
     private _walletAssetManager?;
+    /**
+     * 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.
+     */
+    private _txLock;
+    private _withTxLock;
     /** @deprecated Use settlementConfig instead */
     readonly renewalConfig: Required<Omit<WalletConfig["renewalConfig"], "enabled">> & {
         enabled: boolean;
@@ -209,6 +217,7 @@ export declare class Wallet extends ReadonlyWallet implements IWallet {
      */
     sendBitcoin(params: SendBitcoinParams): Promise<string>;
     settle(params?: SettleParams, eventCallback?: (event: SettlementEvent) => void): Promise<string>;
+    private _settleImpl;
     private handleSettlementFinalizationEvent;
     /**
      * @implements Batch.Handler interface.
@@ -247,6 +256,7 @@ export declare class Wallet extends ReadonlyWallet implements IWallet {
      * ```
      */
     send(...args: Recipient[]): Promise<string>;
+    private _sendImpl;
     /**
      * Build an offchain transaction from the given inputs and outputs,
      * sign it, submit to the ark provider, and finalize.

package/dist/types/worker/errors.d.ts

@@ -0,0 +1,6 @@
+export declare class MessageBusNotInitializedError extends Error {
+    constructor();
+}
+export declare class ServiceWorkerTimeoutError extends Error {
+    constructor(detail: string);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkade-os/sdk",
-  "version": "0.4.6",
+  "version": "0.4.8",
   "description": "Bitcoin wallet SDK with Taproot and Ark integration",
   "type": "module",
   "main": "./dist/cjs/index.js",