@arkade-os/sdk 0.4.18 → 0.4.20

package/dist/esm/wallet/wallet.js

@@ -63,6 +63,12 @@ export class ReadonlyWallet {
         this.walletRepository = walletRepository;
         this.contractRepository = contractRepository;
         this.delegatorProvider = delegatorProvider;
+        // Outpoints ("txid:vout") committed to an in-flight settle/send. Filtered
+        // from getVtxos() so concurrent callers (UI, VtxoManager auto-renewal,
+        // another send/settle racing the _txLock) can't reselect coins that are
+        // already on their way out. The set is in-memory only: a process crash
+        // clears it, and a stale entry only hides a VTXO (never spends one).
+        this._pendingSpendOutpoints = new Set();
         // 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.
@@ -303,6 +309,9 @@ export class ReadonlyWallet {
         return vtxos
             .flatMap((_) => _.vtxos)
             .filter((vtxo) => {
+            if (this._pendingSpendOutpoints.has(`${vtxo.txid}:${vtxo.vout}`)) {
+                return false;
+            }
             if (isSpendable(vtxo)) {
                 if (!f.withRecoverable &&
                     (isRecoverable(vtxo) || isExpired(vtxo))) {
@@ -754,6 +763,20 @@ export class ReadonlyWallet {
  * ```
  */
 export class Wallet extends ReadonlyWallet {
+    _addPendingSpends(inputs) {
+        for (const input of inputs) {
+            if ("virtualStatus" in input) {
+                this._pendingSpendOutpoints.add(`${input.txid}:${input.vout}`);
+            }
+        }
+    }
+    _removePendingSpends(inputs) {
+        for (const input of inputs) {
+            if ("virtualStatus" in input) {
+                this._pendingSpendOutpoints.delete(`${input.txid}:${input.vout}`);
+            }
+        }
+    }
     _withTxLock(fn) {
         let release;
         const lock = new Promise((r) => (release = r));
@@ -969,9 +992,15 @@ export class Wallet extends ReadonlyWallet {
                         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;
+                this._addPendingSpends(selected.inputs);
+                try {
+                    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;
+                }
+                finally {
+                    this._removePendingSpends(selected.inputs);
+                }
             });
         }
         return this.send({
@@ -1017,7 +1046,8 @@ export class Wallet extends ReadonlyWallet {
                 const tip = await this.onchainProvider.getChainTip();
                 chainTipHeight = tip.height;
             }
-            const boardingUtxos = (await this.getBoardingUtxos()).filter((utxo) => !hasBoardingTxExpired(utxo, boardingTimelock, chainTipHeight));
+            const boardingUtxos = (await this.getBoardingUtxos()).filter((utxo) => utxo.status.confirmed &&
+                !hasBoardingTxExpired(utxo, boardingTimelock, chainTipHeight));
             const filteredBoardingUtxos = [];
             for (const utxo of boardingUtxos) {
                 const inputFee = estimator.evalOnchainInput({
@@ -1041,10 +1071,10 @@ export class Wallet extends ReadonlyWallet {
                     weight: 0,
                     birth: vtxo.createdAt,
                     expiry: vtxo.virtualStatus.batchExpiry
-                        ? new Date(vtxo.virtualStatus.batchExpiry * 1000)
-                        : new Date(),
+                        ? new Date(vtxo.virtualStatus.batchExpiry)
+                        : undefined,
                 });
-                if (inputFee.value >= vtxo.value) {
+                if (inputFee.satoshis >= vtxo.value) {
                     // skip if fees are greater than the virtual output value
                     continue;
                 }
@@ -1152,11 +1182,29 @@ export class Wallet extends ReadonlyWallet {
             ...params.inputs.map((input) => `${input.txid}:${input.vout}`),
         ];
         const abortController = new AbortController();
+        let stream;
+        // Optimistically hide these inputs from concurrent getVtxos() callers
+        // while the settlement is in flight. Set before safeRegisterIntent so
+        // there's no window between intent registration and coin-visibility.
+        this._addPendingSpends(params.inputs);
         try {
-            const stream = this.arkProvider.getEventStream(abortController.signal, topics);
+            stream = this.arkProvider.getEventStream(abortController.signal, topics);
+            // Prime the iterator so the provider opens the SSE subscription
+            // before safeRegisterIntent can trigger server-side batch events.
+            const firstNext = stream.next();
+            // If settle exits before Batch.join consumes the primed result,
+            // keep the orphaned promise from surfacing as an unhandled rejection.
+            void firstNext.catch(() => { });
+            const primedStream = (async function* () {
+                const first = await firstNext;
+                if (!first.done) {
+                    yield first.value;
+                }
+                yield* stream;
+            })();
             const intentId = await this.safeRegisterIntent(intent, params.inputs);
             const handler = this.createBatchHandler(intentId, params.inputs, recipients, session);
-            const commitmentTxid = await Batch.join(stream, handler, {
+            const commitmentTxid = await Batch.join(primedStream, handler, {
                 abortController,
                 skipVtxoTreeSigning: !hasOffchainOutputs,
                 eventCallback: eventCallback
@@ -1180,23 +1228,28 @@ export class Wallet extends ReadonlyWallet {
             throw error;
         }
         finally {
-            // close the stream
+            // Clear state first so a synchronous handler firing from abort()
+            // never observes a stale pending-spend set.
+            this._removePendingSpends(params.inputs);
+            // close the stream — abort() fires the in-body handler if the
+            // generator has started iterating; return() also releases the
+            // eager resource if the body is still suspended or never ran
+            // (e.g. safeRegisterIntent threw before Batch.join was called).
             abortController.abort();
+            await stream?.return?.().catch(() => { });
         }
     }
     async handleSettlementFinalizationEvent(event, inputs, forfeitOutputScript, connectorsGraph) {
         // the signed forfeits transactions to submit
         const signedForfeits = [];
-        const vtxos = await this.getVtxos();
+        const isVtxo = (input) => "virtualStatus" in input;
         let settlementPsbt = Transaction.fromPSBT(base64.decode(event.commitmentTx));
         let hasBoardingUtxos = false;
         let connectorIndex = 0;
         const connectorsLeaves = connectorsGraph?.leaves() || [];
         for (const input of inputs) {
-            // check if the input is an offchain "virtual" coin
-            const vtxo = vtxos.find((vtxo) => vtxo.txid === input.txid && vtxo.vout === input.vout);
             // boarding input, we need to sign the settlement tx
-            if (!vtxo) {
+            if (!isVtxo(input)) {
                 for (let i = 0; i < settlementPsbt.inputsLength; i++) {
                     const settlementInput = settlementPsbt.getInput(i);
                     if (!settlementInput.txid ||
@@ -1220,7 +1273,7 @@ export class Wallet extends ReadonlyWallet {
                 }
                 continue;
             }
-            if (isRecoverable(vtxo) || isSubdust(vtxo, this.dustAmount)) {
+            if (isRecoverable(input) || isSubdust(input, this.dustAmount)) {
                 // recoverable or subdust coin, we don't need to create a forfeit tx
                 continue;
             }
@@ -1247,7 +1300,7 @@ export class Wallet extends ReadonlyWallet {
                     txid: input.txid,
                     index: input.vout,
                     witnessUtxo: {
-                        amount: BigInt(vtxo.value),
+                        amount: BigInt(input.value),
                         script: VtxoScript.decode(input.tapTree).pkScript,
                     },
                     sighashType: SigHash.DEFAULT,
@@ -1676,9 +1729,17 @@ export class Wallet extends ReadonlyWallet {
             outputs.push(Extension.create([assetPacket]).txOut());
         }
         const sentAmount = recipients.reduce((sum, r) => sum + r.amount, 0);
-        const { arkTxid, signedCheckpointTxs } = await this.buildAndSubmitOffchainTx(selectedCoins, outputs);
-        await this.updateDbAfterOffchainTx(selectedCoins, arkTxid, signedCheckpointTxs, sentAmount, BigInt(changeAmount), changeReceiver ? changeIndex : 0, changeReceiver?.assets);
-        return arkTxid;
+        // Optimistically hide selected coins from concurrent getVtxos() while
+        // the offchain tx is in flight.
+        this._addPendingSpends(selectedCoins);
+        try {
+            const { arkTxid, signedCheckpointTxs } = await this.buildAndSubmitOffchainTx(selectedCoins, outputs);
+            await this.updateDbAfterOffchainTx(selectedCoins, arkTxid, signedCheckpointTxs, sentAmount, BigInt(changeAmount), changeReceiver ? changeIndex : 0, changeReceiver?.assets);
+            return arkTxid;
+        }
+        finally {
+            this._removePendingSpends(selectedCoins);
+        }
     }
     /**
      * Build an offchain transaction from the given inputs and outputs,

package/dist/esm/worker/messageBus.js

@@ -2,15 +2,22 @@
 import { getActiveServiceWorker, setupServiceWorkerOnce, } from './browser/service-worker-manager.js';
 import { RestArkProvider } from '../providers/ark.js';
 import { RestDelegatorProvider } from '../providers/delegator.js';
-import { ReadonlySingleKey, SingleKey } from '../identity/index.js';
+import { hydrateIdentity, isSigningSerialized, normalizeSerializedIdentity, } from '../identity/index.js';
 import { ReadonlyWallet, Wallet } from '../wallet/wallet.js';
-import { hex } from "@scure/base";
 import { MessageBusNotInitializedError, ServiceWorkerTimeoutError, } from './errors.js';
+/**
+ * Grace period after a handler times out during which late handler
+ * completion is still delivered to the client. Once this expires,
+ * the bus sends an "Operation abandoned" error so the message id
+ * never goes silent indefinitely.
+ */
+const LATE_DELIVERY_GRACE_MS = 5 * 60000;
 export class MessageBus {
     /** Create the service-worker message bus with repositories and handler configuration. */
-    constructor(walletRepository, contractRepository, { messageHandlers, tickIntervalMs = 10000, messageTimeoutMs = 30000, debug = false, buildServices, }) {
+    constructor(walletRepository, contractRepository, { messageHandlers, tickIntervalMs = 10000, messageTimeoutMs = 30000, messageTimeoutOverrides = {}, debug = false, buildServices, }) {
         this.walletRepository = walletRepository;
         this.contractRepository = contractRepository;
+        this.lateDeliveries = new Set();
         this.running = false;
         this.tickTimeout = null;
         this.tickInProgress = false;
@@ -20,6 +27,8 @@ export class MessageBus {
         this.handlers = new Map(messageHandlers.map((u) => [u.messageTag, u]));
         this.tickIntervalMs = tickIntervalMs;
         this.messageTimeoutMs = messageTimeoutMs;
+        this.constructorTimeoutOverrides = { ...messageTimeoutOverrides };
+        this.messageTimeoutOverrides = { ...this.constructorTimeoutOverrides };
         this.debug = debug;
         this.buildServicesFn = buildServices ?? this.buildServices.bind(this);
     }
@@ -55,6 +64,11 @@ export class MessageBus {
             self.clearTimeout(this.tickTimeout);
             this.tickTimeout = null;
         }
+        for (const record of this.lateDeliveries) {
+            record.settled = true;
+            self.clearTimeout(record.deadline);
+        }
+        this.lateDeliveries.clear();
         self.removeEventListener("message", this.boundOnMessage);
         await Promise.all(Array.from(this.handlers.values()).map((updater) => updater.stop()));
     }
@@ -81,7 +95,8 @@ export class MessageBus {
             const now = Date.now();
             for (const updater of this.handlers.values()) {
                 try {
-                    const response = await this.withTimeout(updater.tick(now), `${updater.messageTag}:tick`);
+                    const tickLabel = `${updater.messageTag}:tick`;
+                    const response = await this.withTimeout(updater.tick(now), this.resolveTimeoutMs(tickLabel, updater.messageTag), tickLabel);
                     if (this.debug)
                         console.log(`[${updater.messageTag}] outgoing tick response:`, response);
                     if (response && response.length > 0) {
@@ -124,6 +139,12 @@ export class MessageBus {
             this.initialized = false;
             await Promise.all(Array.from(this.handlers.values()).map((h) => h.stop().catch(() => { })));
         }
+        // Recompute the active timeout map from scratch so a prior init's
+        // keys cannot linger after re-init with a smaller map.
+        this.messageTimeoutOverrides = {
+            ...this.constructorTimeoutOverrides,
+            ...(config.messageTimeouts ?? {}),
+        };
         const services = await this.buildServicesFn(config);
         // Start all handlers
         for (const updater of this.handlers.values()) {
@@ -146,8 +167,9 @@ export class MessageBus {
         const delegatorProvider = config.delegatorUrl
             ? new RestDelegatorProvider(config.delegatorUrl)
             : undefined;
-        if ("privateKey" in config.wallet) {
-            const identity = SingleKey.fromHex(config.wallet.privateKey);
+        const serialized = normalizeSerializedIdentity(config.wallet);
+        if (isSigningSerialized(serialized)) {
+            const identity = hydrateIdentity(serialized);
             const wallet = await Wallet.create({
                 identity,
                 arkServerUrl: config.arkServer.url,
@@ -161,23 +183,18 @@ export class MessageBus {
             });
             return { wallet, arkProvider, readonlyWallet: wallet };
         }
-        else if ("publicKey" in config.wallet) {
-            const identity = ReadonlySingleKey.fromPublicKey(hex.decode(config.wallet.publicKey));
-            const readonlyWallet = await ReadonlyWallet.create({
-                identity,
-                arkServerUrl: config.arkServer.url,
-                arkServerPublicKey: config.arkServer.publicKey,
-                indexerUrl: config.indexerUrl,
-                esploraUrl: config.esploraUrl,
-                storage,
-                delegatorProvider,
-                watcherConfig: config.watcherConfig,
-            });
-            return { readonlyWallet, arkProvider };
-        }
-        else {
-            throw new Error("Missing privateKey or publicKey in configuration object");
-        }
+        const identity = hydrateIdentity(serialized);
+        const readonlyWallet = await ReadonlyWallet.create({
+            identity,
+            arkServerUrl: config.arkServer.url,
+            arkServerPublicKey: config.arkServer.publicKey,
+            indexerUrl: config.indexerUrl,
+            esploraUrl: config.esploraUrl,
+            storage,
+            delegatorProvider,
+            watcherConfig: config.watcherConfig,
+        });
+        return { readonlyWallet, arkProvider };
     }
     onMessage(event) {
         // Keep the service worker alive while async work is pending.
@@ -192,7 +209,7 @@ export class MessageBus {
     async processMessage(event) {
         const { id, tag, broadcast } = event.data;
         if (tag === "PING") {
-            event.source?.postMessage({ id, tag: "PONG" });
+            this.deliverResponse(event.source, { id, tag: "PONG" }, { id, tag: "PONG" });
             return;
         }
         if (tag === "INITIALIZE_MESSAGE_BUS") {
@@ -203,7 +220,7 @@ export class MessageBus {
             // performs network calls (buildServices) and handler startup
             // that may legitimately exceed the message timeout.
             await this.waitForInit(event.data.config);
-            event.source?.postMessage({ id, tag });
+            this.deliverResponse(event.source, { id, tag }, { id, tag });
             if (this.debug) {
                 console.log("MessageBus initialized");
             }
@@ -216,45 +233,60 @@ export class MessageBus {
             // hanging forever. This happens when the browser kills and restarts
             // the service worker — the new instance has initialized=false and
             // messages arrive before INITIALIZE_MESSAGE_BUS is re-sent.
-            event.source?.postMessage({
+            const fallbackTag = tag ?? "unknown";
+            this.deliverResponse(event.source, {
                 id,
-                tag: tag ?? "unknown",
+                tag: fallbackTag,
                 error: new MessageBusNotInitializedError(),
-            });
+            }, { id, tag: fallbackTag });
             return;
         }
         if (!id || !tag) {
             if (this.debug)
                 console.error("Invalid message received, missing required fields:", event.data);
-            event.source?.postMessage({
+            const fallbackTag = tag ?? "unknown";
+            this.deliverResponse(event.source, {
                 id,
-                tag: tag ?? "unknown",
+                tag: fallbackTag,
                 error: new TypeError("Invalid message received, missing required fields"),
-            });
+            }, { id, tag: fallbackTag });
             return;
         }
+        const messageType = this.extractMessageType(event.data);
         if (broadcast) {
             const updaters = Array.from(this.handlers.values());
-            const results = await Promise.allSettled(updaters.map((updater) => this.withTimeout(updater.handleMessage(event.data), updater.messageTag)));
+            const entries = updaters.map((updater) => {
+                const label = this.labelFor(messageType, updater.messageTag);
+                const timeoutMs = this.resolveTimeoutMs(messageType, updater.messageTag);
+                const handlerPromise = updater.handleMessage(event.data);
+                const raced = updater.isLongRunning?.(event.data)
+                    ? handlerPromise
+                    : this.withTimeout(handlerPromise, timeoutMs, label);
+                return { updater, handlerPromise, raced };
+            });
+            const results = await Promise.allSettled(entries.map((e) => e.raced));
             results.forEach((result, index) => {
-                const updater = updaters[index];
+                const { updater, handlerPromise } = entries[index];
+                const handlerTag = updater.messageTag;
+                const context = { id, tag: handlerTag, messageType };
                 if (result.status === "fulfilled") {
                     const response = result.value;
-                    if (response) {
-                        event.source?.postMessage(response);
-                    }
+                    // Always deliver a response so the caller's message id
+                    // never goes silent. Handlers returning null/undefined
+                    // get an explicit ack envelope.
+                    this.deliverResponse(event.source, response ?? { id, tag: handlerTag }, context);
                 }
                 else {
                     if (this.debug)
-                        console.error(`[${updater.messageTag}] handleMessage failed`, result.reason);
-                    const error = result.reason instanceof Error
-                        ? result.reason
-                        : new Error(String(result.reason));
-                    event.source?.postMessage({
-                        id,
-                        tag: updater.messageTag,
-                        error,
-                    });
+                        console.error(`[${handlerTag}] handleMessage failed`, result.reason);
+                    const error = toError(result.reason);
+                    this.deliverResponse(event.source, { id, tag: handlerTag, error }, context);
+                    // If the error was a timeout, keep watching the
+                    // underlying handler and surface its eventual result
+                    // under the same id.
+                    if (result.reason instanceof ServiceWorkerTimeoutError) {
+                        this.attachLateDelivery(handlerPromise, event.source, id, handlerTag, messageType);
+                    }
                 }
             });
             return;
@@ -263,35 +295,53 @@ export class MessageBus {
         if (!updater) {
             if (this.debug)
                 console.warn(`[${tag}] unknown message tag, ignoring message`);
+            this.deliverResponse(event.source, {
+                id,
+                tag,
+                error: new Error(`Unknown handler tag: ${tag}`),
+            }, { id, tag, messageType });
             return;
         }
+        const label = this.labelFor(messageType, tag);
+        const timeoutMs = this.resolveTimeoutMs(messageType, tag);
+        const handlerPromise = updater.handleMessage(event.data);
+        const context = { id, tag, messageType };
         try {
-            const response = await this.withTimeout(updater.handleMessage(event.data), tag);
+            const response = updater.isLongRunning?.(event.data)
+                ? await handlerPromise
+                : await this.withTimeout(handlerPromise, timeoutMs, label);
             if (this.debug)
                 console.log(`[${tag}] outgoing response:`, response);
-            if (response) {
-                event.source?.postMessage(response);
-            }
+            // Always deliver a response so the caller's message id never
+            // goes silent. A handler returning null/undefined yields an
+            // explicit ack envelope.
+            this.deliverResponse(event.source, response ?? { id, tag }, context);
         }
         catch (err) {
             if (this.debug)
                 console.error(`[${tag}] handleMessage failed`, err);
-            const error = err instanceof Error ? err : new Error(String(err));
-            event.source?.postMessage({ id, tag, error });
+            const error = toError(err);
+            this.deliverResponse(event.source, { id, tag, error }, context);
+            // When we abandoned the handler via timeout, keep watching it
+            // so the client's message id eventually gets a final response.
+            if (err instanceof ServiceWorkerTimeoutError) {
+                this.attachLateDelivery(handlerPromise, event.source, id, tag, messageType);
+            }
         }
     }
     /**
      * Race `promise` against a timeout. Note: this does NOT cancel the
-     * underlying work — the original promise keeps running. This is safe
-     * here because only the caller (not the handler) posts the response.
+     * underlying work — the original promise keeps running. Call
+     * `attachLateDelivery` after catching the timeout to surface the
+     * eventual result so the message id does not go silent.
      */
-    withTimeout(promise, label) {
-        if (this.messageTimeoutMs <= 0)
+    withTimeout(promise, timeoutMs, label) {
+        if (timeoutMs <= 0)
             return promise;
         return new Promise((resolve, reject) => {
             const timer = self.setTimeout(() => {
-                reject(new ServiceWorkerTimeoutError(`Message handler timed out after ${this.messageTimeoutMs}ms (${label})`));
-            }, this.messageTimeoutMs);
+                reject(new ServiceWorkerTimeoutError(`Message handler timed out after ${timeoutMs}ms (${label})`));
+            }, timeoutMs);
             promise.then((val) => {
                 self.clearTimeout(timer);
                 resolve(val);
@@ -301,6 +351,97 @@ export class MessageBus {
             });
         });
     }
+    /**
+     * Extract the declared `type` from a request envelope (e.g. "SETTLE").
+     * Not every envelope carries a type (PING/INIT are special cased
+     * earlier), so this returns undefined for envelopes that lack one.
+     */
+    extractMessageType(data) {
+        const maybeType = data.type;
+        return typeof maybeType === "string" ? maybeType : undefined;
+    }
+    /**
+     * Resolve the timeout for an operation. Message-type overrides take
+     * precedence over handler-tag overrides, with the bus-wide default
+     * (`messageTimeoutMs`) as the final fallback.
+     */
+    resolveTimeoutMs(messageType, handlerTag) {
+        if (messageType &&
+            Object.prototype.hasOwnProperty.call(this.messageTimeoutOverrides, messageType)) {
+            return this.messageTimeoutOverrides[messageType];
+        }
+        if (Object.prototype.hasOwnProperty.call(this.messageTimeoutOverrides, handlerTag)) {
+            return this.messageTimeoutOverrides[handlerTag];
+        }
+        return this.messageTimeoutMs;
+    }
+    /**
+     * Build a human-readable label for timeout errors. Format:
+     * `"<MESSAGE_TYPE> via <HANDLER_TAG>"` when both are known, else the
+     * handler tag alone. Used so timeout errors name the operation the
+     * client actually triggered (e.g. SETTLE) rather than just the
+     * handler that received it (e.g. WALLET_UPDATER).
+     */
+    labelFor(messageType, handlerTag) {
+        return messageType ? `${messageType} via ${handlerTag}` : handlerTag;
+    }
+    /**
+     * Post a response to the originating client. When `source` is null
+     * (client tab closed, detached frame, etc.) the response cannot be
+     * delivered; we log the drop in debug mode so it is not invisible.
+     */
+    deliverResponse(source, response, context) {
+        if (!source) {
+            if (this.debug)
+                console.warn(`[${context.tag}] cannot deliver response: event.source is null`, {
+                    id: context.id,
+                    messageType: context.messageType,
+                });
+            return;
+        }
+        source.postMessage(response);
+    }
+    /**
+     * After a handler times out the client has already received a timeout
+     * error, but the handler keeps running. Attach a follow-up so the
+     * handler's eventual result (or error) is delivered under the same
+     * message id, or — if the handler never completes within
+     * {@link LATE_DELIVERY_GRACE_MS} — an "Operation abandoned" error is
+     * sent so the client's listener (if still attached) does not hang.
+     */
+    attachLateDelivery(handlerPromise, source, id, tag, messageType) {
+        const context = { id, tag, messageType };
+        const record = {
+            settled: false,
+            deadline: self.setTimeout(() => {
+                if (record.settled)
+                    return;
+                record.settled = true;
+                this.lateDeliveries.delete(record);
+                this.deliverResponse(source, {
+                    id,
+                    tag,
+                    error: new Error(`Operation abandoned: handler did not complete within ${LATE_DELIVERY_GRACE_MS}ms after timeout (${this.labelFor(messageType, tag)})`),
+                }, context);
+            }, LATE_DELIVERY_GRACE_MS),
+        };
+        this.lateDeliveries.add(record);
+        handlerPromise.then((response) => {
+            if (record.settled)
+                return;
+            record.settled = true;
+            self.clearTimeout(record.deadline);
+            this.lateDeliveries.delete(record);
+            this.deliverResponse(source, response ?? { id, tag }, context);
+        }, (err) => {
+            if (record.settled)
+                return;
+            record.settled = true;
+            self.clearTimeout(record.deadline);
+            this.lateDeliveries.delete(record);
+            this.deliverResponse(source, { id, tag, error: toError(err) }, context);
+        });
+    }
     /**
      * Returns the registered SW for the path.
      * It uses the functions in `service-worker-manager.ts` module.
@@ -323,3 +464,6 @@ export class MessageBus {
         return getActiveServiceWorker(path);
     }
 }
+function toError(value) {
+    return value instanceof Error ? value : new Error(String(value));
+}

package/dist/types/contracts/handlers/default.d.ts

@@ -10,7 +10,7 @@ export interface DefaultContractParams {
     csvTimelock: RelativeTimelock;
 }
 /**
- * Handler for default wallet virtual outputs.
+ * Handler for default wallet VTXOs.
  *
  * Default contracts use the standard forfeit + exit tapscript:
  * - forfeit: (Alice + Server) multisig for collaborative spending

package/dist/types/contracts/handlers/helpers.d.ts

@@ -9,7 +9,7 @@ export declare function timelockToSequence(timelock: RelativeTimelock): number;
  */
 export declare function sequenceToTimelock(sequence: number): RelativeTimelock;
 /**
- * Resolve wallet's role from explicit role or by matching pubkey.
+ * Resolve wallet's role from explicit role or by matching descriptor/pubkey.
  */
 export declare function resolveRole(contract: Contract, context: PathContext): "sender" | "receiver" | undefined;
 /**

package/dist/types/contracts/types.d.ts

@@ -96,13 +96,21 @@ export interface PathContext {
     /** Current block height, when known. */
     blockHeight?: number;
     /**
-     * Wallet public key encoded as 32-byte x-only hex.
-     * Used by handlers to determine the wallet's role in multi-party contracts.
+     * Wallet's descriptor for signing.
+     * Format: tr(pubkey) for static keys, tr([fingerprint/path']xpub/0/{index}) for HD.
+     * Used by handlers to determine wallet's role in multi-party contracts.
+     */
+    walletDescriptor?: string;
+    /**
+     * Wallet's public key (x-only, 32 bytes hex).
+     * @deprecated Use walletDescriptor instead.
      */
     walletPubKey?: string;
     /**
      * Explicit role override for multi-party contracts such as VHTLC.
-     * If not provided, the handler may derive the role from `walletPubKey`.
+     * If not provided, the handler may derive the role by matching
+     * {@link walletDescriptor} (preferred) — or {@link walletPubKey} as a
+     * fallback — against the contract's sender/receiver params.
      */
     role?: string;
     /** The specific virtual output being evaluated. */

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

@@ -0,0 +1,35 @@
+/**
+ * Check if a string is a descriptor of the shape `tr(...)`.
+ *
+ * This is a shape check only — it does not validate the inner key material.
+ * Use {@link expand} (via {@link extractPubKey} / {@link parseHDDescriptor})
+ * for full parsing. The guard rejects empty bodies and missing/trailing
+ * parentheses so callers can safely branch on descriptor vs. raw pubkey.
+ */
+export declare function isDescriptor(value: string): boolean;
+/**
+ * Normalize a value to descriptor format.
+ * If already a descriptor, return as-is. If hex pubkey, wrap as tr(pubkey).
+ * Throws when the value is empty or not a string so we never produce
+ * malformed descriptors like `tr()` that downstream parsers would reject.
+ */
+export declare function normalizeToDescriptor(value: string): string;
+/**
+ * Extract the public key from a simple descriptor.
+ * For simple descriptors (tr(pubkey)), extracts the pubkey using the library.
+ * For HD descriptors, throws — use DescriptorProvider to derive the key.
+ */
+export declare function extractPubKey(descriptor: string): string;
+/** Parsed HD descriptor components. */
+export interface ParsedHDDescriptor {
+    fingerprint: string;
+    basePath: string;
+    xpub: string;
+    derivationPath: string;
+}
+/**
+ * Parse an HD descriptor into its components.
+ * HD descriptors have the format: tr([fingerprint/path']xpub/derivation)
+ * Returns null if the descriptor is not in HD format.
+ */
+export declare function parseHDDescriptor(descriptor: string): ParsedHDDescriptor | null;