@arkade-os/sdk 0.4.19 → 0.4.21

package/dist/cjs/worker/messageBus.js

@@ -7,13 +7,20 @@ const ark_1 = require("../providers/ark");
 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");
+/**
+ * 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;
 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;
@@ -23,6 +30,8 @@ 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);
     }
@@ -58,6 +67,11 @@ 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()));
     }
@@ -84,7 +98,8 @@ 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) {
@@ -127,6 +142,12 @@ 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()) {
@@ -149,8 +170,9 @@ class MessageBus {
         const delegatorProvider = config.delegatorUrl
             ? new delegator_1.RestDelegatorProvider(config.delegatorUrl)
             : undefined;
-        if ("privateKey" in config.wallet) {
-            const identity = identity_1.SingleKey.fromHex(config.wallet.privateKey);
+        const serialized = (0, identity_1.normalizeSerializedIdentity)(config.wallet);
+        if ((0, identity_1.isSigningSerialized)(serialized)) {
+            const identity = (0, identity_1.hydrateIdentity)(serialized);
             const wallet = await wallet_1.Wallet.create({
                 identity,
                 arkServerUrl: config.arkServer.url,
@@ -164,23 +186,18 @@ class MessageBus {
             });
             return { wallet, arkProvider, readonlyWallet: wallet };
         }
-        else if ("publicKey" in config.wallet) {
-            const identity = identity_1.ReadonlySingleKey.fromPublicKey(base_1.hex.decode(config.wallet.publicKey));
-            const readonlyWallet = await wallet_1.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 = (0, identity_1.hydrateIdentity)(serialized);
+        const readonlyWallet = await wallet_1.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.
@@ -195,7 +212,7 @@ 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") {
@@ -206,7 +223,7 @@ 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");
             }
@@ -219,45 +236,60 @@ 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 errors_1.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 errors_1.ServiceWorkerTimeoutError) {
+                        this.attachLateDelivery(handlerPromise, event.source, id, handlerTag, messageType);
+                    }
                 }
             });
             return;
@@ -266,35 +298,53 @@ 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 errors_1.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 errors_1.ServiceWorkerTimeoutError(`Message handler timed out after ${this.messageTimeoutMs}ms (${label})`));
-            }, this.messageTimeoutMs);
+                reject(new errors_1.ServiceWorkerTimeoutError(`Message handler timed out after ${timeoutMs}ms (${label})`));
+            }, timeoutMs);
             promise.then((val) => {
                 self.clearTimeout(timer);
                 resolve(val);
@@ -304,6 +354,97 @@ 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.
@@ -327,3 +468,6 @@ class MessageBus {
     }
 }
 exports.MessageBus = MessageBus;
+function toError(value) {
+    return value instanceof Error ? value : new Error(String(value));
+}

package/dist/esm/contracts/contractWatcher.js

@@ -1,3 +1,4 @@
+import { isEventSourceError } from '../providers/utils.js';
 /**
  * Watches multiple contracts for virtual output state changes with resilient connection handling.
  *
@@ -250,13 +251,18 @@ export class ContractWatcher {
     }
     /**
      * Connect to the subscription.
+     *
+     * @param skipUpdate - Skip the leading `updateSubscription` call when
+     *   the caller has already established `subscriptionId`.
      */
-    async connect() {
+    async connect(skipUpdate = false) {
         if (!this.isWatching)
             return;
         this.connectionState = "connecting";
         try {
-            await this.updateSubscription();
+            if (!skipUpdate) {
+                await this.updateSubscription();
+            }
             // Poll immediately after connection to sync state
             await this.pollAllContracts();
             this.connectionState = "connected";
@@ -267,7 +273,12 @@ export class ContractWatcher {
                 // indefinitely and block the caller.
                 // Error management must be implemented to ensure the connection
                 // is restored and events are fired.
-                console.error(e);
+                if (isEventSourceError(e)) {
+                    console.debug("ContractWatcher subscription disconnected; reconnecting");
+                }
+                else {
+                    console.error(e);
+                }
                 this.connectionState = "disconnected";
                 this.eventCallback?.({
                     type: "connection_reset",
@@ -382,11 +393,30 @@ export class ContractWatcher {
         }
     }
     async tryUpdateSubscription() {
+        const hadSubscription = this.subscriptionId !== undefined;
         try {
             await this.updateSubscription();
         }
         catch (error) {
             // nothing, the connection will be retried later
+            return;
+        }
+        // Cold start: `startWatching` may have run with zero scripts,
+        // leaving `listenLoop` parked behind the reconnect timer. Kick
+        // `connect` now so streaming resumes without waiting on the
+        // backoff. `skipUpdate` avoids re-issuing `subscribeForScripts`.
+        const justGotSubscription = !hadSubscription && this.subscriptionId !== undefined;
+        const listenerParked = this.connectionState === "disconnected" ||
+            this.connectionState === "reconnecting";
+        if (this.isWatching && justGotSubscription && listenerParked) {
+            if (this.reconnectTimeoutId) {
+                clearTimeout(this.reconnectTimeoutId);
+                this.reconnectTimeoutId = undefined;
+            }
+            this.reconnectAttempts = 0;
+            this.connect(true).catch((error) => {
+                console.warn("ContractWatcher cold-start connect failed:", error);
+            });
         }
     }
     /**

package/dist/esm/contracts/handlers/default.js

@@ -1,8 +1,15 @@
 import { hex } from "@scure/base";
 import { DefaultVtxo } from '../../script/default.js';
 import { isCsvSpendable, sequenceToTimelock, timelockToSequence, } from './helpers.js';
+import { normalizeToDescriptor, extractPubKey, } from '../../identity/descriptor.js';
 /**
- * Handler for default wallet virtual outputs.
+ * Extract pubkey bytes from a descriptor or hex string.
+ */
+function extractPubKeyBytes(value) {
+    return hex.decode(extractPubKey(normalizeToDescriptor(value)));
+}
+/**
+ * Handler for default wallet VTXOs.
  *
  * Default contracts use the standard forfeit + exit tapscript:
  * - forfeit: (Alice + Server) multisig for collaborative spending
@@ -26,8 +33,8 @@ export const DefaultContractHandler = {
             ? sequenceToTimelock(Number(params.csvTimelock))
             : DefaultVtxo.Script.DEFAULT_TIMELOCK;
         return {
-            pubKey: hex.decode(params.pubKey),
-            serverPubKey: hex.decode(params.serverPubKey),
+            pubKey: extractPubKeyBytes(params.pubKey),
+            serverPubKey: extractPubKeyBytes(params.serverPubKey),
             csvTimelock,
         };
     },

package/dist/esm/contracts/handlers/helpers.js

@@ -1,4 +1,21 @@
 import * as bip68 from "bip68";
+import { isDescriptor, extractPubKey } from '../../identity/descriptor.js';
+/**
+ * Extract raw hex pubkey from a value that may be a descriptor or raw hex.
+ * Returns undefined for HD descriptors or unparseable values so role
+ * resolution stays best-effort and never throws.
+ */
+function extractRawPubKey(value) {
+    if (!isDescriptor(value)) {
+        return value.toLowerCase();
+    }
+    try {
+        return extractPubKey(value).toLowerCase();
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Convert RelativeTimelock to BIP68 sequence number.
  */
@@ -21,21 +38,46 @@ export function sequenceToTimelock(sequence) {
     throw new Error(`Invalid BIP68 sequence: ${sequence}`);
 }
 /**
- * Resolve wallet's role from explicit role or by matching pubkey.
+ * Resolve wallet's role from explicit role or by matching descriptor/pubkey.
  */
 export function resolveRole(contract, context) {
     // Explicit role takes precedence
     if (context.role === "sender" || context.role === "receiver") {
         return context.role;
     }
-    // Try to match wallet pubkey against contract params
-    if (context.walletPubKey) {
-        if (context.walletPubKey === contract.params.sender) {
+    const senderKey = contract.params.sender
+        ? extractRawPubKey(contract.params.sender)
+        : undefined;
+    const receiverKey = contract.params.receiver
+        ? extractRawPubKey(contract.params.receiver)
+        : undefined;
+    const matchRole = (rawWalletKey) => {
+        if (!rawWalletKey)
+            return undefined;
+        if (senderKey && rawWalletKey === senderKey) {
             return "sender";
         }
-        if (context.walletPubKey === contract.params.receiver) {
+        if (receiverKey && rawWalletKey === receiverKey) {
             return "receiver";
         }
+        return undefined;
+    };
+    // Try the preferred descriptor first. If it cannot be resolved
+    // (for example an HD descriptor without derivation support), fall back
+    // to walletPubKey for backward compatibility.
+    if (context.walletDescriptor) {
+        const walletDescriptorKey = extractRawPubKey(context.walletDescriptor);
+        const matchedRole = matchRole(walletDescriptorKey);
+        if (matchedRole) {
+            return matchedRole;
+        }
+        if (!walletDescriptorKey && context.walletPubKey) {
+            return matchRole(extractRawPubKey(context.walletPubKey));
+        }
+        return undefined;
+    }
+    if (context.walletPubKey) {
+        return matchRole(extractRawPubKey(context.walletPubKey));
     }
     return undefined;
 }

package/dist/esm/contracts/handlers/vhtlc.js

@@ -49,7 +49,8 @@ export const VHTLCContractHandler = {
     /**
      * Select spending path based on context.
      *
-     * Role is determined from `context.role` or by matching `context.walletPubKey`
+     * Role is determined from `context.role` or by matching
+     * `context.walletDescriptor` (preferred) / `context.walletPubKey`
      * against sender/receiver in contract params.
      */
     selectPath(script, contract, context) {
@@ -98,7 +99,8 @@ export const VHTLCContractHandler = {
     /**
      * Get all possible spending paths (no timelock checks).
      *
-     * Role is determined from `context.role` or by matching `context.walletPubKey`
+     * Role is determined from `context.role` or by matching
+     * `context.walletDescriptor` (preferred) / `context.walletPubKey`
      * against sender/receiver in contract params.
      */
     getAllSpendingPaths(script, contract, context) {

package/dist/esm/identity/descriptor.js

@@ -0,0 +1,92 @@
+import { expand, networks, } from "@bitcoinerlab/descriptors-scure";
+import { hex } from "@scure/base";
+function inferNetwork(descriptor) {
+    return descriptor.includes("tpub") ? networks.testnet : networks.bitcoin;
+}
+/**
+ * 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 function isDescriptor(value) {
+    if (typeof value !== "string")
+        return false;
+    if (!value.startsWith("tr(") || !value.endsWith(")"))
+        return false;
+    // body length > 0 after stripping "tr(" and ")"
+    return value.length > "tr()".length;
+}
+/**
+ * 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 function normalizeToDescriptor(value) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new Error("normalizeToDescriptor: expected a non-empty string value");
+    }
+    if (isDescriptor(value)) {
+        return value;
+    }
+    return `tr(${value})`;
+}
+/**
+ * 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 function extractPubKey(descriptor) {
+    if (!isDescriptor(descriptor)) {
+        return descriptor;
+    }
+    const network = inferNetwork(descriptor);
+    const expansion = expand({ descriptor, network });
+    if (!expansion.expansionMap) {
+        throw new Error("Cannot extract pubkey from descriptor: expansion failed.");
+    }
+    const key = expansion.expansionMap["@0"];
+    // HD descriptors (have a bip32 key) require DescriptorProvider for derivation
+    if (key?.bip32) {
+        throw new Error("Cannot extract pubkey from HD descriptor without derivation. " +
+            "Use DescriptorProvider to derive the key from the xpub.");
+    }
+    if (!key?.pubkey) {
+        throw new Error("Cannot extract pubkey from descriptor: no key found.");
+    }
+    return hex.encode(key.pubkey);
+}
+/**
+ * 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 function parseHDDescriptor(descriptor) {
+    if (!isDescriptor(descriptor)) {
+        return null;
+    }
+    let expansion;
+    try {
+        const network = inferNetwork(descriptor);
+        expansion = expand({ descriptor, network });
+    }
+    catch {
+        return null;
+    }
+    const key = expansion.expansionMap?.["@0"];
+    if (!key?.masterFingerprint ||
+        !key.originPath ||
+        !key.keyPath ||
+        !key.bip32) {
+        return null;
+    }
+    return {
+        fingerprint: hex.encode(key.masterFingerprint),
+        basePath: key.originPath.replace(/^\//, ""),
+        xpub: key.bip32.toBase58(),
+        derivationPath: key.keyPath.replace(/^\//, ""),
+    };
+}

package/dist/esm/identity/descriptorProvider.js

@@ -0,0 +1 @@
+export {};