@arkade-os/sdk 0.4.22 → 0.4.24

package/dist/cjs/wallet/wallet.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Wallet = exports.ReadonlyWallet = void 0;
+exports.Wallet = exports.ReadonlyWallet = exports.getArkadeServerUrl = void 0;
 exports.selectVirtualCoins = selectVirtualCoins;
 exports.waitForIncomingFunds = waitForIncomingFunds;
 const base_1 = require("@scure/base");
@@ -37,8 +37,11 @@ const delegator_1 = require("./delegator");
 const repositories_1 = require("../repositories");
 const contractManager_1 = require("../contracts/contractManager");
 const handlers_1 = require("../contracts/handlers");
-const helpers_1 = require("../contracts/handlers/helpers");
+const timelock_1 = require("../utils/timelock");
 const syncCursors_1 = require("../utils/syncCursors");
+const vtxoOwnership_1 = require("../contracts/vtxoOwnership");
+const getArkadeServerUrl = ({ arkServerUrl, }) => arkServerUrl || _1.DEFAULT_ARKADE_SERVER_URL;
+exports.getArkadeServerUrl = getArkadeServerUrl;
 // Historical unilateral exit delay for mainnet (~7 days in seconds).
 // Kept so existing wallets can still discover and spend VTXOs sent to the
 // legacy address after arkd starts advertising a different delay.
@@ -53,7 +56,7 @@ function dedupeTimelocks(timelocks) {
     const seen = new Set();
     const deduped = [];
     for (const timelock of timelocks) {
-        const sequence = (0, helpers_1.timelockToSequence)(timelock).toString();
+        const sequence = (0, timelock_1.timelockToSequence)(timelock).toString();
         if (seen.has(sequence))
             continue;
         seen.add(sequence);
@@ -125,10 +128,7 @@ class ReadonlyWallet {
         // Use provided arkProvider instance or create a new one from arkServerUrl
         const arkProvider = config.arkProvider ||
             (() => {
-                if (!config.arkServerUrl) {
-                    throw new Error("Either arkProvider or arkServerUrl must be provided");
-                }
-                return new ark_1.RestArkProvider(config.arkServerUrl);
+                return new ark_1.RestArkProvider((0, exports.getArkadeServerUrl)(config));
             })();
         // Extract arkServerUrl from provider if not explicitly provided
         const arkServerUrl = config.arkServerUrl || arkProvider.serverUrl;
@@ -307,7 +307,7 @@ class ReadonlyWallet {
                 continue;
             if (vtxo.assets) {
                 for (const a of vtxo.assets) {
-                    const current = assetBalances.get(a.assetId) ?? 0;
+                    const current = assetBalances.get(a.assetId) ?? 0n;
                     assetBalances.set(a.assetId, current + a.amount);
                 }
             }
@@ -649,7 +649,7 @@ class ReadonlyWallet {
             watcherConfig: this.watcherConfig,
         });
         for (const csvTimelock of this.walletContractTimelocks) {
-            const csvTimelockStr = (0, helpers_1.timelockToSequence)(csvTimelock).toString();
+            const csvTimelockStr = (0, timelock_1.timelockToSequence)(csvTimelock).toString();
             const defaultScript = new default_1.DefaultVtxo.Script({
                 pubKey: this.offchainTapscript.options.pubKey,
                 serverPubKey: this.offchainTapscript.options.serverPubKey,
@@ -1129,12 +1129,12 @@ class Wallet extends ReadonlyWallet {
             for (const [, assets] of assetInputs) {
                 for (const asset of assets) {
                     const existing = allAssets.get(asset.assetId) ?? 0n;
-                    allAssets.set(asset.assetId, existing + BigInt(asset.amount));
+                    allAssets.set(asset.assetId, existing + asset.amount);
                 }
             }
             outputAssets = [];
             for (const [assetId, amount] of allAssets) {
-                outputAssets.push({ assetId, amount: Number(amount) });
+                outputAssets.push({ assetId, amount });
             }
         }
         const recipients = params.outputs.map((output, i) => ({
@@ -1569,7 +1569,7 @@ class Wallet extends ReadonlyWallet {
      * const txid = await wallet.send({
      *     address: 'ark1q...',
      *     amount: 1000, // (optional, default to dust) btc amount to send to the output
-     *     assets: [{ assetId: 'abc123...', amount: 50 }] // (optional) list of assets to send
+     *     assets: [{ assetId: 'abc123...', amount: 50n }] // (optional) list of assets to send
      * });
      * ```
      */
@@ -1600,7 +1600,7 @@ class Wallet extends ReadonlyWallet {
                 continue;
             }
             for (const receiverAsset of recipient.assets) {
-                let amountToSelect = BigInt(receiverAsset.amount);
+                let amountToSelect = receiverAsset.amount;
                 // check if existing change covers the needed amount
                 const existingChange = assetChanges.get(receiverAsset.assetId) ?? 0n;
                 if (existingChange >= amountToSelect) {
@@ -1627,7 +1627,7 @@ class Wallet extends ReadonlyWallet {
                                 continue;
                             }
                             const existing = assetChanges.get(a.assetId) ?? 0n;
-                            assetChanges.set(a.assetId, existing + BigInt(a.amount));
+                            assetChanges.set(a.assetId, existing + a.amount);
                         }
                     }
                 }
@@ -1647,7 +1647,7 @@ class Wallet extends ReadonlyWallet {
                 if (coin.assets) {
                     for (const asset of coin.assets) {
                         const existing = assetChanges.get(asset.assetId) ?? 0n;
-                        assetChanges.set(asset.assetId, existing + BigInt(asset.amount));
+                        assetChanges.set(asset.assetId, existing + asset.amount);
                     }
                 }
             }
@@ -1669,7 +1669,7 @@ class Wallet extends ReadonlyWallet {
                 if (coin.assets) {
                     for (const asset of coin.assets) {
                         const existing = assetChanges.get(asset.assetId) ?? 0n;
-                        assetChanges.set(asset.assetId, existing + BigInt(asset.amount));
+                        assetChanges.set(asset.assetId, existing + asset.amount);
                     }
                 }
             }
@@ -1684,7 +1684,7 @@ class Wallet extends ReadonlyWallet {
             const changeAssets = [];
             for (const [assetId, amount] of assetChanges) {
                 if (amount > 0n) {
-                    changeAssets.push({ assetId, amount: Number(amount) });
+                    changeAssets.push({ assetId, amount });
                 }
             }
             changeIndex = outputs.length;
@@ -1831,7 +1831,7 @@ class Wallet extends ReadonlyWallet {
                 }
             }
             const createdAt = Date.now();
-            const addr = this.arkAddress.encode();
+            const primaryAddr = this.arkAddress.encode();
             // Only save a change virtual output for preconfirmed coins (those with a batchExpiry).
             // Inputs without a batchExpiry are already settled/unrolled and don't need tracking.
             let changeVtxo;
@@ -1858,8 +1858,45 @@ class Wallet extends ReadonlyWallet {
                     script: base_1.hex.encode(this.offchainTapscript.pkScript),
                 };
             }
-            await this.walletRepository.saveVtxos(addr, changeVtxo ? [...spentVtxos, changeVtxo] : spentVtxos);
-            await this.walletRepository.saveTransactions(addr, [
+            // Route spent rows to their owning contract bucket. The wallet's
+            // primary contract is registered with the manager at boot, so
+            // `addrByScript` already includes it; in a multi-contract spend
+            // each input may belong to a different contract.
+            const contracts = await cm.getContracts();
+            const addrByScript = new Map(contracts.map((c) => [c.script, c.address]));
+            const spentByScript = new Map();
+            for (const v of spentVtxos) {
+                if (!v.script) {
+                    throw new Error(`Wallet.updateDbAfterOffchainTx: spent VTXO ${v.txid}:${v.vout} has no script`);
+                }
+                const arr = spentByScript.get(v.script) ?? [];
+                arr.push(v);
+                spentByScript.set(v.script, arr);
+            }
+            const byAddress = new Map();
+            for (const [script, vtxos] of spentByScript) {
+                // User-initiated send path: a wrong-script row here means the
+                // wallet is about to record ownership against the wrong
+                // contract — fail loudly rather than persist inconsistent state.
+                (0, vtxoOwnership_1.validateVtxosForScript)(vtxos, script, "Wallet.updateDbAfterOffchainTx");
+                const targetAddr = addrByScript.get(script);
+                if (!targetAddr) {
+                    throw new Error(`Wallet.updateDbAfterOffchainTx: no contract owns script ${script}`);
+                }
+                const bucket = byAddress.get(targetAddr) ?? [];
+                bucket.push(...vtxos);
+                byAddress.set(targetAddr, bucket);
+            }
+            // Change is always primary-script by construction.
+            if (changeVtxo) {
+                const bucket = byAddress.get(primaryAddr) ?? [];
+                bucket.push(changeVtxo);
+                byAddress.set(primaryAddr, bucket);
+            }
+            for (const [addr, vtxos] of byAddress) {
+                await this.walletRepository.saveVtxos(addr, vtxos);
+            }
+            await this.walletRepository.saveTransactions(primaryAddr, [
                 {
                     key: {
                         boardingTxid: "",
@@ -1875,12 +1912,12 @@ class Wallet extends ReadonlyWallet {
         }
         catch (e) {
             console.warn("error saving offchain tx to repository", e);
+            throw e;
         }
     }
     // mark virtual outputs as spent/settled, remove boarding inputs
     async updateDbAfterSettle(inputs, commitmentTxid) {
         try {
-            const addr = this.arkAddress.encode();
             const boardingAddress = await this.getBoardingAddress();
             const spentVtxos = [];
             const inputArkTxIds = new Set();
@@ -1913,7 +1950,38 @@ class Wallet extends ReadonlyWallet {
                 }
             }
             if (spentVtxos.length > 0) {
-                await this.walletRepository.saveVtxos(addr, spentVtxos);
+                // Route settled rows to their owning contract bucket. In a
+                // multi-contract settle the inputs may belong to several
+                // contracts; the wallet's primary contract is registered with
+                // the manager at boot, so its address is in `addrByScript`
+                // alongside the rest.
+                const contracts = await cm.getContracts();
+                const addrByScript = new Map(contracts.map((c) => [c.script, c.address]));
+                const byAddress = new Map();
+                const byScript = new Map();
+                for (const v of spentVtxos) {
+                    if (!v.script) {
+                        throw new Error(`Wallet.updateDbAfterSettle: spent VTXO ${v.txid}:${v.vout} has no script`);
+                    }
+                    const arr = byScript.get(v.script) ?? [];
+                    arr.push(v);
+                    byScript.set(v.script, arr);
+                }
+                for (const [script, vtxos] of byScript) {
+                    // User-initiated settle path: refuse to record a settle
+                    // against the wrong script.
+                    (0, vtxoOwnership_1.validateVtxosForScript)(vtxos, script, "Wallet.updateDbAfterSettle");
+                    const targetAddr = addrByScript.get(script);
+                    if (!targetAddr) {
+                        throw new Error(`Wallet.updateDbAfterSettle: no contract owns script ${script}`);
+                    }
+                    const bucket = byAddress.get(targetAddr) ?? [];
+                    bucket.push(...vtxos);
+                    byAddress.set(targetAddr, bucket);
+                }
+                for (const [bucketAddr, vtxos] of byAddress) {
+                    await this.walletRepository.saveVtxos(bucketAddr, vtxos);
+                }
             }
             if (boardingUtxoToRemove.size > 0) {
                 const currentUtxos = await this.walletRepository.getUtxos(boardingAddress);
@@ -1927,6 +1995,7 @@ class Wallet extends ReadonlyWallet {
         }
         catch (e) {
             console.warn("error updating repository after settle", e);
+            throw e;
         }
     }
 }

package/dist/cjs/worker/expo/processors/contractPollProcessor.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.contractPollProcessor = exports.CONTRACT_POLL_TASK_TYPE = void 0;
+const vtxoOwnership_1 = require("../../../contracts/vtxoOwnership");
 exports.CONTRACT_POLL_TASK_TYPE = "contract-poll";
 /**
  * Polls the indexer for the latest VTXO state of every contract and
@@ -43,8 +44,12 @@ exports.contractPollProcessor = {
                 hasMore = page ? vtxos.length === pageSize : false;
                 pageIndex++;
             }
-            await walletRepository.saveVtxos(contract.address, allVtxos);
-            vtxosSaved += allVtxos.length;
+            // Skip wrong-script rows (legacy duplicates or indexer drift)
+            // before persisting; the loop must keep going for the remaining
+            // contracts even when one row is rejected.
+            const filtered = (0, vtxoOwnership_1.warnAndFilterVtxosForScript)(allVtxos, contract.script, "contractPollProcessor");
+            await walletRepository.saveVtxos(contract.address, filtered);
+            vtxosSaved += filtered.length;
             contractsProcessed++;
         }
         return {

package/dist/esm/contracts/arkcontract.js

@@ -1,5 +1,6 @@
 import { hex } from "@scure/base";
 import { contractHandlers } from './handlers/index.js';
+import { DEFAULT_ARKADE_HRP } from '../wallet/index.js';
 /**
  * Prefix for arkcontract strings.
  */
@@ -115,7 +116,7 @@ export function contractFromArkContract(encoded, options = {}) {
  * @param options - Additional options
  * @returns A complete Contract object
  */
-export function contractFromArkContractWithAddress(encoded, serverPubKey, addressPrefix, options = {}) {
+export function contractFromArkContractWithAddress(encoded, serverPubKey, addressPrefix = DEFAULT_ARKADE_HRP, options = {}) {
     const parsed = decodeArkContract(encoded);
     const handler = contractHandlers.getOrThrow(parsed.type);
     const params = parsed.data;

package/dist/esm/contracts/contractManager.js

@@ -3,6 +3,7 @@ import { ContractWatcher } from './contractWatcher.js';
 import { contractHandlers } from './handlers/index.js';
 import { extendVirtualCoinForContract } from '../wallet/utils.js';
 import { advanceSyncCursor, computeSyncWindow, cursorCutoff, getSyncCursor, } from '../utils/syncCursors.js';
+import { filterVtxosForScript, warnAndFilterVtxosForScript, } from './vtxoOwnership.js';
 const DEFAULT_PAGE_SIZE = 500;
 /**
  * Central manager for contract lifecycle and operations.
@@ -354,9 +355,19 @@ export class ContractManager {
         const contracts = opts?.scripts
             ? await this.getContracts({ script: opts.scripts })
             : undefined;
+        // Only forward an explicit window when the caller supplied one. An
+        // empty `{ after: undefined, before: undefined }` would short-circuit
+        // both the cursor-derived `?after=` query in `syncContracts` (because
+        // `??` doesn't fire on a non-nullish object) AND the cursor-advance
+        // gate (which requires `options.window === undefined`), turning every
+        // `refreshVtxos()` call into an unbounded full re-scan whose cursor
+        // never moves forward.
+        const hasExplicitWindow = opts?.after !== undefined || opts?.before !== undefined;
         await this.syncContracts({
             contracts,
-            window: { after: opts?.after, before: opts?.before },
+            window: hasExplicitWindow
+                ? { after: opts?.after, before: opts?.before }
+                : undefined,
         });
     }
     /**
@@ -399,7 +410,11 @@ export class ContractManager {
         this.emitEvent(event);
     }
     async getVtxosForContracts(contracts) {
-        const res = await Promise.all(contracts.map(({ script, address }) => this.config.walletRepository.getVtxos(address).then((vtxos) => vtxos.map((vtxo) => ({
+        const res = await Promise.all(contracts.map(({ script, address }) => this.config.walletRepository.getVtxos(address).then((vtxos) => 
+        // Address buckets may carry legacy duplicate rows from
+        // other contracts that once shared the same address —
+        // gate by script so the wrong-script row never wins.
+        filterVtxosForScript(vtxos, script).map((vtxo) => ({
             ...vtxo,
             contractScript: script,
         })))));
@@ -467,7 +482,14 @@ export class ContractManager {
             });
         }
         for (const [addr, contractVtxos] of byContract) {
-            await this.config.walletRepository.saveVtxos(addr, contractVtxos);
+            // The bucket is keyed by contract address, so the script filter
+            // here is the same as the contract's. Skip wrong-script rows
+            // rather than crash the reconcile loop.
+            const contract = contracts.find((c) => c.address === addr);
+            const filtered = warnAndFilterVtxosForScript(contractVtxos, contract.script, "ContractManager.reconcilePendingFrontier");
+            if (filtered.length === 0)
+                continue;
+            await this.config.walletRepository.saveVtxos(addr, filtered);
         }
     }
     async fetchContractVxosFromIndexer(contracts, pageSize, syncWindow) {
@@ -477,7 +499,10 @@ export class ContractManager {
             result.set(contractScript, vtxos);
             const contract = contracts.find((c) => c.script === contractScript);
             if (contract) {
-                await this.config.walletRepository.saveVtxos(contract.address, vtxos);
+                const filtered = warnAndFilterVtxosForScript(vtxos, contract.script, "ContractManager.fetchContractVxosFromIndexer");
+                if (filtered.length === 0)
+                    continue;
+                await this.config.walletRepository.saveVtxos(contract.address, filtered);
             }
         }
         return result;

package/dist/esm/contracts/contractWatcher.js

@@ -1,5 +1,6 @@
 import { extendVirtualCoinForContract } from '../wallet/utils.js';
 import { isEventSourceError } from '../providers/utils.js';
+import { filterVtxosForScript } from './vtxoOwnership.js';
 /**
  * Watches multiple contracts for virtual output state changes with resilient connection handling.
  *
@@ -87,7 +88,10 @@ export class ContractWatcher {
      */
     async seedLastKnownVtxos(state) {
         try {
-            const cached = await this.config.walletRepository.getVtxos(state.contract.address);
+            // Apply the same script gate used by getContractVtxos so a legacy
+            // wrong-script row in the address bucket can't seed the baseline
+            // and then look "spent" on the first poll.
+            const cached = filterVtxosForScript(await this.config.walletRepository.getVtxos(state.contract.address), state.contract.script);
             for (const vtxo of cached) {
                 if (vtxo.isSpent)
                     continue;
@@ -166,8 +170,10 @@ export class ContractWatcher {
             return true;
         })
             .map(async (state) => {
-            // Use contract address as cache key
-            const cached = await repo.getVtxos(state.contract.address);
+            // Use contract address as cache key. Legacy address buckets
+            // can contain rows from other contracts; gate by script before
+            // converting so a wrong-script row never reaches the watcher.
+            const cached = filterVtxosForScript(await repo.getVtxos(state.contract.address), state.contract.script);
             if (cached.length > 0) {
                 // Convert to ContractVtxo with contractScript
                 const contractVtxos = cached.map((v) => ({

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

@@ -1,6 +1,7 @@
 import { hex } from "@scure/base";
 import { DefaultVtxo } from '../../script/default.js';
-import { isCsvSpendable, sequenceToTimelock, timelockToSequence, } from './helpers.js';
+import { isCsvSpendable } from './helpers.js';
+import { sequenceToTimelock, timelockToSequence } from '../../utils/timelock.js';
 import { normalizeToDescriptor, extractPubKey, } from '../../identity/descriptor.js';
 /**
  * Extract pubkey bytes from a descriptor or hex string.

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

@@ -1,7 +1,8 @@
 import { hex } from "@scure/base";
 import { DelegateVtxo } from '../../script/delegate.js';
 import { DefaultVtxo } from '../../script/default.js';
-import { isCsvSpendable, sequenceToTimelock, timelockToSequence, } from './helpers.js';
+import { isCsvSpendable } from './helpers.js';
+import { sequenceToTimelock, timelockToSequence } from '../../utils/timelock.js';
 /**
  * Handler for delegate wallet virtual outputs.
  *

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

@@ -1,4 +1,4 @@
-import * as bip68 from "bip68";
+import { sequenceToTimelock } from '../../utils/timelock.js';
 import { isDescriptor, extractPubKey } from '../../identity/descriptor.js';
 /**
  * Extract raw hex pubkey from a value that may be a descriptor or raw hex.
@@ -16,27 +16,6 @@ function extractRawPubKey(value) {
         return undefined;
     }
 }
-/**
- * Convert RelativeTimelock to BIP68 sequence number.
- */
-export function timelockToSequence(timelock) {
-    return bip68.encode(timelock.type === "blocks"
-        ? { blocks: Number(timelock.value) }
-        : { seconds: Number(timelock.value) });
-}
-/**
- * Convert BIP68 sequence number back to RelativeTimelock.
- */
-export function sequenceToTimelock(sequence) {
-    const decoded = bip68.decode(sequence);
-    if ("blocks" in decoded && decoded.blocks !== undefined) {
-        return { type: "blocks", value: BigInt(decoded.blocks) };
-    }
-    if ("seconds" in decoded && decoded.seconds !== undefined) {
-        return { type: "seconds", value: BigInt(decoded.seconds) };
-    }
-    throw new Error(`Invalid BIP68 sequence: ${sequence}`);
-}
 /**
  * Resolve wallet's role from explicit role or by matching descriptor/pubkey.
  */

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

@@ -1,6 +1,7 @@
 import { hex } from "@scure/base";
 import { VHTLC } from '../../script/vhtlc.js';
-import { isCltvSatisfied, isCsvSpendable, resolveRole, sequenceToTimelock, timelockToSequence, } from './helpers.js';
+import { isCltvSatisfied, isCsvSpendable, resolveRole } from './helpers.js';
+import { sequenceToTimelock, timelockToSequence } from '../../utils/timelock.js';
 /**
  * Handler for Virtual Hash Time Lock Contract (VHTLC).
  *

package/dist/esm/contracts/vtxoOwnership.js

@@ -0,0 +1,53 @@
+/**
+ * Tier 1 helpers that enforce VTXO ownership at call sites that already know
+ * the intended contract script. Address-keyed repositories may still hand back
+ * legacy duplicate rows under the wrong bucket; these helpers gate reads and
+ * writes so a wrong-script row never wins.
+ *
+ * `script` is the authoritative ownership key. Equality is strict: a missing
+ * or empty `vtxo.script` never matches.
+ */
+export function vtxoOutpoint(vtxo) {
+    return `${vtxo.txid}:${vtxo.vout}`;
+}
+export function isVtxoForScript(vtxo, script) {
+    return !!vtxo.script && vtxo.script === script;
+}
+export function filterVtxosForScript(vtxos, script) {
+    return vtxos.filter((v) => isVtxoForScript(v, script));
+}
+/**
+ * Background/indexer sync flavour: drop wrong-script rows and log enough
+ * context to identify each rejection. Returns only matching rows so the
+ * caller can keep going.
+ */
+export function warnAndFilterVtxosForScript(vtxos, script, context) {
+    const matches = [];
+    const rejected = [];
+    for (const v of vtxos) {
+        if (isVtxoForScript(v, script)) {
+            matches.push(v);
+        }
+        else {
+            rejected.push(`${vtxoOutpoint(v)}(script=${v.script ?? ""})`);
+        }
+    }
+    if (rejected.length > 0) {
+        console.warn(`${context}: dropped ${rejected.length} wrong-script VTXO(s) for script ${script}: ${rejected.join(", ")}`);
+    }
+    return matches;
+}
+/**
+ * User-initiated transaction/signing flavour: throw before persisting or
+ * signing inconsistent ownership state. Silently skipping here would hide a
+ * serious bug in the wallet's spend path.
+ */
+export function validateVtxosForScript(vtxos, script, context) {
+    const mismatches = vtxos.filter((v) => !isVtxoForScript(v, script));
+    if (mismatches.length === 0)
+        return;
+    const detail = mismatches
+        .map((v) => `${vtxoOutpoint(v)}(script=${v.script ?? ""})`)
+        .join(", ");
+    throw new Error(`${context}: refusing to persist ${mismatches.length} VTXO(s) whose script does not match ${script}: ${detail}`);
+}

package/dist/esm/identity/descriptor.js

@@ -1,7 +1,72 @@
-import { expand, networks, } from "@bitcoinerlab/descriptors-scure";
+import { expand, networks } from "@bitcoinerlab/descriptors-scure";
 import { hex } from "@scure/base";
-function inferNetwork(descriptor) {
-    return descriptor.includes("tpub") ? networks.testnet : networks.bitcoin;
+/**
+ * True iff `descriptor` is a Bitcoin mainnet descriptor (xpub-prefixed
+ * BIP32 key).
+ *
+ * Note: testnet, signet, regtest, mutinynet, and other non-mainnet
+ * networks all share the same `tpub` BIP32 version bytes — they cannot
+ * be distinguished from one another at the descriptor level. Callers
+ * that need a `Network` constants object for `expand()` pick
+ * `networks.bitcoin` vs `networks.testnet` themselves; callers that
+ * need the *actual* network the wallet is on must track that
+ * out-of-band.
+ */
+export function isMainnetDescriptor(descriptor) {
+    return !descriptor.includes("tpub");
+}
+/**
+ * Shared "does `candidate` belong to the identity backed by
+ * `ourDescriptor`?" predicate.
+ *
+ * - HD descriptors (expanding to a `bip32` key) match by account xpub
+ *   on both sides — index-agnostic, so a wildcard template and any
+ *   concrete index under it all collapse to the same xpub.
+ * - Bare `tr(pubkey)` candidates fall back to comparing the candidate
+ *   pubkey against `ourXOnlyPubkey` (the cached pubkey on the identity
+ *   side, since pulling it from `ourDescriptor` would require an index
+ *   substitution the caller already performed).
+ */
+export function descriptorIsOurs(candidate, ourDescriptor, ourXOnlyPubkey) {
+    if (!isDescriptor(candidate))
+        return false;
+    try {
+        const candidateInfo = expand({
+            descriptor: candidate,
+            network: isMainnetDescriptor(candidate)
+                ? networks.bitcoin
+                : networks.testnet,
+        }).expansionMap?.["@0"];
+        if (!candidateInfo)
+            return false;
+        if (candidateInfo.bip32) {
+            const ourBip32 = expand({
+                descriptor: ourDescriptor,
+                network: isMainnetDescriptor(ourDescriptor)
+                    ? networks.bitcoin
+                    : networks.testnet,
+            }).expansionMap?.["@0"]?.bip32;
+            if (!ourBip32)
+                return false;
+            return ourBip32.toBase58() === candidateInfo.bip32.toBase58();
+        }
+        if (candidateInfo.pubkey) {
+            // For tr() the library hands back a 32-byte x-only key, but
+            // strip a leading parity byte defensively so a 33-byte
+            // compressed key (mismatched length) doesn't silently
+            // false-negative against our 32-byte x-only side.
+            const candidatePub = candidateInfo.pubkey.length === 33
+                ? candidateInfo.pubkey.subarray(1)
+                : candidateInfo.pubkey;
+            if (candidatePub.length !== ourXOnlyPubkey.length)
+                return false;
+            return hex.encode(candidatePub) === hex.encode(ourXOnlyPubkey);
+        }
+        return false;
+    }
+    catch {
+        return false;
+    }
 }
 /**
  * Check if a string is a descriptor of the shape `tr(...)`.
@@ -43,7 +108,9 @@ export function extractPubKey(descriptor) {
     if (!isDescriptor(descriptor)) {
         return descriptor;
     }
-    const network = inferNetwork(descriptor);
+    const network = isMainnetDescriptor(descriptor)
+        ? networks.bitcoin
+        : networks.testnet;
     const expansion = expand({ descriptor, network });
     if (!expansion.expansionMap) {
         throw new Error("Cannot extract pubkey from descriptor: expansion failed.");
@@ -70,7 +137,9 @@ export function parseHDDescriptor(descriptor) {
     }
     let expansion;
     try {
-        const network = inferNetwork(descriptor);
+        const network = isMainnetDescriptor(descriptor)
+            ? networks.bitcoin
+            : networks.testnet;
         expansion = expand({ descriptor, network });
     }
     catch {

package/dist/esm/identity/hdCapableIdentity.js

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