@arkade-os/sdk 0.4.22 → 0.4.24

package/dist/esm/wallet/wallet.js

@@ -11,7 +11,7 @@ import { buildForfeitTx } from '../forfeit.js';
 import { validateConnectorsTxGraph, validateVtxoTxGraph, } from '../tree/validation.js';
 import { validateBatchRecipients } from './validation.js';
 import { isBatchSignable } from '../identity/index.js';
-import { isExpired, isRecoverable, isSpendable, isSubdust, TxType, } from './index.js';
+import { DEFAULT_ARKADE_SERVER_URL, isExpired, isRecoverable, isSpendable, isSubdust, TxType, } from './index.js';
 import { createAssetPacket, selectCoinsWithAsset, selectedCoinsToAssetInputs, } from './asset.js';
 import { VtxoScript } from '../script/base.js';
 import { CSVMultisigTapscript } from '../script/tapscript.js';
@@ -32,8 +32,10 @@ import { DelegatorManagerImpl, findDestinationOutputIndex, } from './delegator.j
 import { IndexedDBContractRepository, IndexedDBWalletRepository, } from '../repositories/index.js';
 import { ContractManager } from '../contracts/contractManager.js';
 import { contractHandlers } from '../contracts/handlers/index.js';
-import { timelockToSequence } from '../contracts/handlers/helpers.js';
+import { timelockToSequence } from '../utils/timelock.js';
 import { clearSyncCursor, updateWalletState } from '../utils/syncCursors.js';
+import { validateVtxosForScript } from '../contracts/vtxoOwnership.js';
+export const getArkadeServerUrl = ({ arkServerUrl, }) => arkServerUrl || DEFAULT_ARKADE_SERVER_URL;
 // 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.
@@ -120,10 +122,7 @@ export 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 RestArkProvider(config.arkServerUrl);
+                return new RestArkProvider(getArkadeServerUrl(config));
             })();
         // Extract arkServerUrl from provider if not explicitly provided
         const arkServerUrl = config.arkServerUrl || arkProvider.serverUrl;
@@ -302,7 +301,7 @@ export 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);
                 }
             }
@@ -1123,12 +1122,12 @@ export 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) => ({
@@ -1563,7 +1562,7 @@ export 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
      * });
      * ```
      */
@@ -1594,7 +1593,7 @@ export 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) {
@@ -1621,7 +1620,7 @@ export 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);
                         }
                     }
                 }
@@ -1641,7 +1640,7 @@ export 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);
                     }
                 }
             }
@@ -1663,7 +1662,7 @@ export 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);
                     }
                 }
             }
@@ -1678,7 +1677,7 @@ export 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;
@@ -1825,7 +1824,7 @@ export 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;
@@ -1852,8 +1851,45 @@ export class Wallet extends ReadonlyWallet {
                     script: 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.
+                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: "",
@@ -1869,12 +1905,12 @@ export 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();
@@ -1907,7 +1943,38 @@ export 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.
+                    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);
@@ -1921,6 +1988,7 @@ export class Wallet extends ReadonlyWallet {
         }
         catch (e) {
             console.warn("error updating repository after settle", e);
+            throw e;
         }
     }
 }

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

@@ -1,3 +1,4 @@
+import { warnAndFilterVtxosForScript } from '../../../contracts/vtxoOwnership.js';
 export const CONTRACT_POLL_TASK_TYPE = "contract-poll";
 /**
  * Polls the indexer for the latest VTXO state of every contract and
@@ -40,8 +41,12 @@ export const 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 = warnAndFilterVtxosForScript(allVtxos, contract.script, "contractPollProcessor");
+            await walletRepository.saveVtxos(contract.address, filtered);
+            vtxosSaved += filtered.length;
             contractsProcessed++;
         }
         return {

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

@@ -88,7 +88,7 @@ export declare function contractFromArkContract(encoded: string, options?: {
  * @param options - Additional options
  * @returns A complete Contract object
  */
-export declare function contractFromArkContractWithAddress(encoded: string, serverPubKey: Uint8Array, addressPrefix: string, options?: {
+export declare function contractFromArkContractWithAddress(encoded: string, serverPubKey: Uint8Array, addressPrefix?: string, options?: {
     label?: string;
     state?: "active" | "inactive";
     metadata?: Record<string, unknown>;

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

@@ -1,13 +1,4 @@
-import { RelativeTimelock } from "../../script/tapscript";
 import { Contract, PathContext } from "../types";
-/**
- * Convert RelativeTimelock to BIP68 sequence number.
- */
-export declare function timelockToSequence(timelock: RelativeTimelock): number;
-/**
- * Convert BIP68 sequence number back to RelativeTimelock.
- */
-export declare function sequenceToTimelock(sequence: number): RelativeTimelock;
 /**
  * Resolve wallet's role from explicit role or by matching descriptor/pubkey.
  */

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

@@ -0,0 +1,25 @@
+import type { VirtualCoin } from "../wallet";
+/**
+ * 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 declare function vtxoOutpoint(vtxo: Pick<VirtualCoin, "txid" | "vout">): string;
+export declare function isVtxoForScript(vtxo: Pick<VirtualCoin, "script">, script: string): boolean;
+export declare function filterVtxosForScript<T extends Pick<VirtualCoin, "script">>(vtxos: T[], script: string): T[];
+/**
+ * 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 declare function warnAndFilterVtxosForScript<T extends Pick<VirtualCoin, "txid" | "vout" | "script">>(vtxos: T[], script: string, context: string): T[];
+/**
+ * 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 declare function validateVtxosForScript(vtxos: Array<Pick<VirtualCoin, "txid" | "vout" | "script">>, script: string, context: string): void;

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

@@ -1,3 +1,29 @@
+/**
+ * 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 declare function isMainnetDescriptor(descriptor: string): boolean;
+/**
+ * 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 declare function descriptorIsOurs(candidate: string, ourDescriptor: string, ourXOnlyPubkey: Uint8Array): boolean;
 /**
  * Check if a string is a descriptor of the shape `tr(...)`.
  *

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

@@ -13,12 +13,19 @@ export interface DescriptorSigningRequest {
  *
  * Implementations include:
  * - {@link StaticDescriptorProvider}: wraps a legacy {@link Identity} with a single key.
- * - HD-wallet provider: signs with keys derived from an xpub-based descriptor
- *   (planned — tracked separately from this interface).
+ * - {@link HDDescriptorProvider}: rotates through HD-derived descriptors.
+ *
+ * The provider has no read accessor for "current" — it is a pure descriptor
+ * allocator. "What addresses am I currently bound to?" is a question the
+ * contract repository answers, not the provider.
  */
 export interface DescriptorProvider {
-    /** Returns the current signing descriptor. */
-    getSigningDescriptor(): string;
+    /**
+     * Allocate a new signing descriptor. For HD providers each call advances
+     * the internal index and returns a fresh descriptor; for single-key
+     * providers each call returns the same descriptor.
+     */
+    getNextSigningDescriptor(): Promise<string>;
     /** Checks if a descriptor belongs to this provider. */
     isOurs(descriptor: string): boolean;
     /** Signs transactions, each with its own descriptor-derived key. */

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

@@ -0,0 +1,44 @@
+import { Identity, ReadonlyIdentity } from ".";
+import { DescriptorSigningRequest } from "./descriptorProvider";
+import { Transaction } from "../utils/transaction";
+/**
+ * Read-side HD capability marker. Exposes the wildcard-suffixed account
+ * descriptor *template* and the descriptor-membership predicate, but no
+ * signing primitives — suitable for watch-only identities backed by an
+ * xpub.
+ *
+ * Extracted from {@link HDCapableIdentity} so that
+ * `ReadonlyDescriptorIdentity` can stand in for an HD wallet's read-only
+ * surface (template-aware, derives pubkeys at any index) without having
+ * to claim signing capability it cannot honour.
+ */
+export interface ReadonlyHDCapableIdentity extends ReadonlyIdentity {
+    /**
+     * The wildcard-suffixed account descriptor template
+     * (e.g. `tr([fp/86'/0'/0']xpub/0/*)`). Consumers materialize a
+     * concrete descriptor by replacing the `*` with a derivation index.
+     */
+    readonly descriptor: string;
+    /** True iff `descriptor` derives from this identity's xpub/seed. */
+    isOurs(descriptor: string): boolean;
+}
+/**
+ * Capability marker for identities that can be rotated through an HD
+ * derivation tree AND can sign at each rotated index.
+ *
+ * Deliberately does NOT extend `DescriptorProvider`: if an HD-capable
+ * identity were silently usable as a concrete descriptor source, callers
+ * could bypass receive rotation and unknowingly reuse a single address
+ * forever. To use this identity as a wallet's descriptor source, wrap
+ * it explicitly:
+ *
+ *  - `HDDescriptorProvider` — rotating, recommended for new wallets.
+ *  - `StaticDescriptorProvider` — pinned to a single key, for legacy or
+ *    explicitly-non-rotating use cases.
+ */
+export interface HDCapableIdentity extends ReadonlyHDCapableIdentity, Identity {
+    /** Signs each request with the key derived from its descriptor. */
+    signWithDescriptor(requests: DescriptorSigningRequest[]): Promise<Transaction[]>;
+    /** Signs a message using the key derived from `descriptor`. */
+    signMessageWithDescriptor(descriptor: string, message: Uint8Array, signatureType?: "schnorr" | "ecdsa"): Promise<Uint8Array>;
+}

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

@@ -52,4 +52,5 @@ export * from "./serialize";
 export { isDescriptor, normalizeToDescriptor, extractPubKey, parseHDDescriptor, } from "./descriptor";
 export type { ParsedHDDescriptor } from "./descriptor";
 export type { DescriptorProvider, DescriptorSigningRequest, } from "./descriptorProvider";
+export type { HDCapableIdentity, ReadonlyHDCapableIdentity, } from "./hdCapableIdentity";
 export { StaticDescriptorProvider } from "./staticDescriptorProvider";

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

@@ -1,7 +1,8 @@
-import { Identity, ReadonlyIdentity } from ".";
 import { Transaction } from "../utils/transaction";
 import { SignerSession } from "../tree/signingSession";
 import type { SerializedSigningIdentity, SerializedReadonlyIdentity } from "./serialize";
+import { DescriptorSigningRequest } from "./descriptorProvider";
+import { HDCapableIdentity, ReadonlyHDCapableIdentity } from "./hdCapableIdentity";
 /** Used for default BIP86 derivation with network selection. */
 export interface NetworkOptions {
     /**
@@ -11,12 +12,16 @@ export interface NetworkOptions {
      */
     isMainnet?: boolean;
 }
-/** Used for custom output descriptor derivation. */
+/** Used for a caller-supplied account-descriptor template. */
 export interface DescriptorOptions {
-    /** Custom output descriptor that determines the derivation path. */
+    /**
+     * Account-descriptor *template* — must end with the BIP-32 wildcard
+     * suffix `/*)`. Stored as-is on {@link SeedIdentity.descriptor} and
+     * read by HD providers to rotate through derivation indices.
+     */
     descriptor: string;
 }
-/** Either default BIP86 derivation (with optional network selection) or a custom descriptor. */
+/** Either default BIP86 derivation (with optional network selection) or a caller-supplied template. */
 export type SeedIdentityOptions = NetworkOptions | DescriptorOptions;
 /** Used for deriving an identity from a BIP39 mnemonic. */
 export type MnemonicOptions = SeedIdentityOptions & {
@@ -24,44 +29,77 @@ export type MnemonicOptions = SeedIdentityOptions & {
     passphrase?: string;
 };
 /**
- * Seed-based identity derived from a raw seed and an output descriptor.
+ * Seed-based identity derived from a raw seed and an account descriptor
+ * *template*.
  *
  * This is the recommended identity type for most applications. It uses
- * standard BIP86 (Taproot) derivation by default and stores an output
- * descriptor for interoperability with other wallets.
+ * standard BIP86 (Taproot) derivation by default; callers that need a
+ * different path supply the wildcard template directly.
  *
  * Prefer this (or @see MnemonicIdentity) over `SingleKey` for new
  * integrations — `SingleKey` exists for backward compatibility with
  * raw nsec-style keys.
  *
- * For descriptor-based signing, wrap with {@link StaticDescriptorProvider}.
+ * The identity holds the wildcard *template* (e.g.
+ * `tr([fp/86'/0'/0']xpub/0/*)`) on its public {@link descriptor}
+ * field. HD rotation reads it directly; consumers that need a
+ * concrete descriptor at a specific index materialize it themselves
+ * (see `HDDescriptorProvider` in the wallet layer).
+ *
+ * Exposes seed-level primitives (signing, derivation, the template)
+ * but is deliberately NOT a `DescriptorProvider`. Wrap it explicitly
+ * to get one:
+ *  - `HDDescriptorProvider` for rotating receive addresses.
+ *  - {@link StaticDescriptorProvider} for legacy, single-key behaviour.
+ *
+ * The split prevents a SeedIdentity from being silently used as a
+ * concrete descriptor source, which would defeat HD rotation without
+ * any compile-time signal that something was wrong.
  *
  * @example
  * ```typescript
  * const seed = mnemonicToSeedSync(mnemonic);
  *
- * // Testnet (BIP86 path m/86'/1'/0'/0/0)
+ * // Testnet (BIP86 wildcard descriptor m/86'/1'/0'/0/*)
  * const identity = SeedIdentity.fromSeed(seed, { isMainnet: false });
  *
- * // Mainnet (BIP86 path m/86'/0'/0'/0/0)
+ * // Mainnet (BIP86 wildcard descriptor m/86'/0'/0'/0/*)
  * const identity = SeedIdentity.fromSeed(seed, { isMainnet: true });
  *
- * // Custom descriptor
+ * // Caller-supplied wildcard descriptor (must end in `/*)`).
  * const identity = SeedIdentity.fromSeed(seed, { descriptor });
  * ```
  */
-export declare class SeedIdentity implements Identity {
+export declare class SeedIdentity implements HDCapableIdentity {
     private readonly derivedKey;
+    /**
+     * Wildcard account-descriptor template (e.g.
+     * `tr([fp/86'/0'/0']xpub/0/*)`). The canonical thing to pass
+     * through the system; consumers materialize a concrete descriptor
+     * at a specific index themselves (see `HDDescriptorProvider` in
+     * the wallet layer for the rotating-counter use case).
+     */
     readonly descriptor: string;
-    constructor(seed: Uint8Array, descriptor: string);
+    /**
+     * Constructs a SeedIdentity from a 64-byte seed and either a
+     * caller-supplied wildcard descriptor (`{ descriptor }`) or the
+     * default BIP86 path at the requested network (`{ isMainnet }`).
+     * Prefer the {@link fromSeed} factory for symmetry with
+     * {@link MnemonicIdentity.fromMnemonic}.
+     *
+     * Throws on a non-wildcard descriptor, an xpub mismatch with the
+     * seed, or a missing derivation path.
+     */
+    constructor(seed: Uint8Array, opts?: SeedIdentityOptions);
     /**
      * Creates a SeedIdentity from a raw 64-byte seed.
      *
      * Pass `{ isMainnet }` for default BIP86 derivation, or
-     * `{ descriptor }` for a custom derivation path.
+     * `{ descriptor }` for a caller-supplied account-descriptor
+     * template (the option's value must end with `/*)`).
      *
      * @param seed - 64-byte seed (typically from mnemonicToSeedSync)
-     * @param opts - Network selection or custom descriptor.
+     * @param opts - Network selection or descriptor template.
      */
     static fromSeed(seed: Uint8Array, opts?: SeedIdentityOptions): SeedIdentity;
     xOnlyPublicKey(): Promise<Uint8Array>;
@@ -70,9 +108,29 @@ export declare class SeedIdentity implements Identity {
     signMessage(message: Uint8Array, signatureType?: "schnorr" | "ecdsa"): Promise<Uint8Array>;
     signerSession(): SignerSession;
     /**
-     * Converts to a watch-only identity that cannot sign.
+     * Converts to a watch-only identity that cannot sign. Carries the
+     * template forward, so the readonly side stays HD-capable (can
+     * derive descriptors at any index without seed access).
      */
     toReadonly(): Promise<ReadonlyDescriptorIdentity>;
+    /**
+     * Returns true when `descriptor` is derived from this identity's seed.
+     * HD descriptors match by account xpub; bare `tr(pubkey)` descriptors
+     * match by raw pubkey. See {@link descriptorIsOurs}.
+     */
+    isOurs(descriptor: string): boolean;
+    /**
+     * Signs each request with the key derived from its descriptor.
+     * Each descriptor must share this identity's seed ({@link isOurs}).
+     */
+    signWithDescriptor(requests: DescriptorSigningRequest[]): Promise<Transaction[]>;
+    /**
+     * Signs a message with the key derived from `descriptor`.
+     */
+    signMessageWithDescriptor(descriptor: string, message: Uint8Array, signatureType?: "schnorr" | "ecdsa"): Promise<Uint8Array>;
+    private derivePrivateKeyForDescriptor;
+    private signTxWithKey;
+    private signMessageWithKey;
 }
 /**
  * Mnemonic-based identity derived from a BIP39 phrase.
@@ -96,40 +154,66 @@ export declare class MnemonicIdentity extends SeedIdentity {
      * Creates a MnemonicIdentity from a BIP39 mnemonic phrase.
      *
      * Pass `{ isMainnet }` for default BIP86 derivation, or
-     * `{ descriptor }` for a custom derivation path.
+     * `{ descriptor }` for a caller-supplied account-descriptor
+     * template (the option's value must end with `/*)`).
      *
      * @param phrase - BIP39 mnemonic phrase (12 or 24 words)
-     * @param opts - Network selection or custom descriptor, plus optional passphrase
+     * @param opts - Network selection or descriptor template, plus optional passphrase
      */
     static fromMnemonic(phrase: string, opts?: MnemonicOptions): MnemonicIdentity;
 }
 /**
- * Watch-only identity from an output descriptor.
+ * Watch-only HD identity from a descriptor *template*.
  *
  * Can derive public keys but cannot sign transactions. Use this for
- * watch-only wallets or when sharing identity information without
- * exposing private keys.
+ * watch-only wallets — given just an xpub-based template, the readonly
+ * side still rotates through HD indices.
+ *
+ * Constructed from a wildcard template (e.g.
+ * `tr([fp/86'/0'/0']xpub.../0/*)`); the {@link descriptor} field
+ * holds it for HD providers to consume.
  *
  * @example
  * ```typescript
- * const descriptor = "tr([fingerprint/86'/0'/0']xpub.../0/0)";
- * const readonly = ReadonlyDescriptorIdentity.fromDescriptor(descriptor);
- * const pubKey = await readonly.xOnlyPublicKey();
+ * const ro = ReadonlyDescriptorIdentity.fromDescriptor(
+ *   "tr([fp/86'/0'/0']xpub.../0/*)"
+ * );
+ * ro.descriptor;
+ * // => "tr([fp/86'/0'/0']xpub.../0/*)" — the template
  * ```
  */
-export declare class ReadonlyDescriptorIdentity implements ReadonlyIdentity {
+export declare class ReadonlyDescriptorIdentity implements ReadonlyHDCapableIdentity {
+    /**
+     * Index-0 expansion of {@link descriptor}. Both the x-only pubkey
+     * (taproot, returned by the library as 32 bytes) and the compressed
+     * pubkey (derived through the bip32 node when needed) are read off
+     * this on demand — no separate caches.
+     */
+    private readonly indexZero;
+    /**
+     * Wildcard account-descriptor template (e.g.
+     * `tr([fp/86'/0'/0']xpub/0/*)`). HD rotation consumers materialize
+     * a concrete descriptor at a specific index themselves.
+     */
     readonly descriptor: string;
-    private readonly xOnlyPubKey;
-    private readonly compressedPubKey;
     private constructor();
     /**
-     * Creates a ReadonlyDescriptorIdentity from an output descriptor.
+     * Creates a ReadonlyDescriptorIdentity from an account-descriptor
+     * *template* (must end with the BIP-32 wildcard suffix `/*)`).
      *
-     * @param descriptor - Taproot descriptor: tr([fingerprint/path']xpub.../child/path)
+     * @param descriptor - Wildcard-suffixed Taproot template
+     *   (`tr([fp/path']xpub.../child/*)`).
      */
     static fromDescriptor(descriptor: string): ReadonlyDescriptorIdentity;
     xOnlyPublicKey(): Promise<Uint8Array>;
     compressedPublicKey(): Promise<Uint8Array>;
+    /**
+     * Returns true when `descriptor` derives from this identity's xpub.
+     * HD descriptors match by account xpub; bare `tr(pubkey)` descriptors
+     * fall back to comparing against the index-0 x-only pubkey. See
+     * {@link descriptorIsOurs}.
+     */
+    isOurs(descriptor: string): boolean;
 }
 /**
  * Serialize a seed-backed signing identity into a