@arkade-os/sdk 0.4.26 → 0.4.27

package/dist/esm/wallet/walletReceiveRotator.js

@@ -0,0 +1,540 @@
+import { expand, networks } from "@bitcoinerlab/descriptors-scure";
+import { equalBytes } from "@scure/btc-signer/utils.js";
+import { hex } from "@scure/base";
+import { isMainnetDescriptor } from "../identity/descriptor.js";
+import { isHDCapableIdentity } from "../identity/hdCapableIdentity.js";
+import { DefaultVtxo } from "../script/default.js";
+import { DelegateVtxo } from "../script/delegate.js";
+import { timelockToSequence } from "../utils/timelock.js";
+import { HDDescriptorProvider } from "./hdDescriptorProvider.js";
+/** Type guard: does this provider implement {@link ReceiveRotatorFactory}? */
+export function hasReceiveRotatorFactory(provider) {
+    return (typeof provider
+        .createReceiveRotator === "function");
+}
+function hasPeekableDescriptor(provider) {
+    return (typeof provider
+        .getCurrentSigningDescriptor === "function");
+}
+/**
+ * Sentinel value stored in `contract.metadata.source` to identify the
+ * wallet's current display contract. Borrowed from btcpay-arkade's
+ * source-tagging pattern: every contract records "where and why it was
+ * generated", and the wallet only cares about the ones it generated for
+ * its own receive address.
+ *
+ * Tagging makes the boot lookup unambiguous — the rotator filters on
+ * `metadata.source === WALLET_RECEIVE_SOURCE` rather than on "any active
+ * default contract", so a contract repo that also holds default contracts
+ * created for other reasons (legacy timelock variants, external
+ * integrations) doesn't confuse the wallet's display state.
+ */
+export const WALLET_RECEIVE_SOURCE = "wallet-receive";
+/**
+ * Thrown when a descriptor expected to be rangeable (have a wildcard
+ * leaf) cannot produce a leaf pubkey. Surfaces from the rotator's
+ * `defaultBoot` path so `resolveBoot` can distinguish a legitimate
+ * incompatibility (silent fallback under `walletMode: 'auto'`) from
+ * any other runtime failure.
+ */
+export class NonRangeableDescriptorError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "NonRangeableDescriptorError";
+    }
+}
+/**
+ * Cap on the exponential backoff applied to repeated rotation
+ * failures. After this delay, every fresh `vtxo_received` event
+ * re-attempts a rotation at this rate until one succeeds (which
+ * resets the counter) or the wallet is disposed.
+ */
+export const ROTATION_MAX_BACKOFF_MS = 60000;
+/**
+ * Owns the wallet's HD receive-rotation lifecycle.
+ *
+ * The rotator is constructed only when the wallet's `walletMode`
+ * resolves to a {@link DescriptorProvider}; static wallets and
+ * non-HD-capable wallets under `'auto'` never see one.
+ *
+ * Lifecycle:
+ * 1. `resolveBoot()` — pre-Wallet-construction. Resolves the provider
+ *    from `walletMode`, then either reuses the existing display
+ *    contract's pubkey (if any) or allocates the first descriptor.
+ *    Returns the rotator paired with the boot pubkey.
+ * 2. `install(wallet)` — post-`getVtxoManager()`. Subscribes to
+ *    `vtxo_received` on the contract manager and routes matching events
+ *    through the rotation chain.
+ * 3. `dispose()` — tears down the subscription and drains any in-flight
+ *    rotation so the contract manager can be disposed cleanly.
+ *
+ * This class follows the dotnet-sdk's split of responsibilities: the
+ * provider is a pure rotating allocator; "what address am I currently
+ * bound to?" is answered by querying the contract repository, not by
+ * asking the provider.
+ */
+export class WalletReceiveRotator {
+    constructor(provider, priorTaggedScript, logger) {
+        this.provider = provider;
+        this.chain = Promise.resolve();
+        /**
+         * Consecutive rotation failures since the last successful rotate.
+         * Drives an exponential backoff (capped at
+         * {@link ROTATION_MAX_BACKOFF_MS}) so a broken provider can't make
+         * the rotator hammer `getNextSigningDescriptor` + `createContract`
+         * on every inbound VTXO. Reset to zero on a successful rotate.
+         */
+        this.consecutiveFailures = 0;
+        /**
+         * Unix-ms timestamp before which incoming `vtxo_received` events
+         * skip the rotation attempt entirely. Zero means "no backoff
+         * active" — the next event can rotate immediately.
+         */
+        this.nextRotationAllowedAt = 0;
+        this.currentTaggedScript = priorTaggedScript;
+        this.logger = logger ?? console;
+    }
+    /**
+     * Phase 1 — pre-Wallet-construction. Resolves `walletMode` to a
+     * {@link DescriptorProvider}, then asks that provider to construct
+     * the rotator (delegated through
+     * {@link DescriptorProvider.createReceiveRotator}, which falls back
+     * to {@link defaultBoot} when the provider doesn't override it).
+     *
+     * Returns the rotator paired with the offchain tapscript the wallet
+     * should actually install (rebuilt to the resolved receive pubkey
+     * when it differs from the identity's static pubkey), or
+     * `undefined` when the wallet should stay on the static path.
+     *
+     * Errors during pubkey resolution propagate when:
+     * - `walletMode === 'hd'` (caller asked for HD; loud failure expected).
+     * - `walletMode` is a {@link DescriptorProvider} (caller supplied an
+     *   explicit allocator; silently degrading would hide misconfig).
+     *
+     * Errors are silently swallowed (returning `undefined`) only under
+     * `walletMode: 'auto'` with the built-in HD provider, to preserve
+     * backwards compatibility with wallets whose identity descriptor
+     * isn't actually rangeable.
+     */
+    static async resolveBoot(config, setup) {
+        const provider = await resolveDescriptorProvider(config, setup.walletRepository);
+        if (!provider)
+            return undefined;
+        const allowSilentFallback = (config.walletMode ?? "auto") === "auto";
+        const expectedContractType = setup.offchainTapscript instanceof DelegateVtxo.Script
+            ? "delegate"
+            : "default";
+        const factoryOpts = {
+            walletRepository: setup.walletRepository,
+            contractRepository: setup.contractRepository,
+            serverPubKey: setup.serverPubKey,
+            expectedContractType,
+        };
+        let boot;
+        try {
+            boot = hasReceiveRotatorFactory(provider)
+                ? await provider.createReceiveRotator(factoryOpts)
+                : await WalletReceiveRotator.defaultBoot(provider, factoryOpts);
+        }
+        catch (e) {
+            // Only swallow non-rangeable-descriptor errors, and only
+            // under `walletMode: 'auto'`. Explicit HD/`DescriptorProvider`
+            // callers always see the failure.
+            if (allowSilentFallback &&
+                e instanceof NonRangeableDescriptorError) {
+                return undefined;
+            }
+            throw e;
+        }
+        if (!boot)
+            return undefined;
+        // Rebuild the offchain tapscript with the resolved receive
+        // pubkey. Skipping the rebuild when pubkeys already match keeps
+        // the tapscript instance stable for static / first-boot paths
+        // (no allocation churn, no observable change for callers
+        // that retain the reference across `Wallet.create`).
+        const offchainTapscript = equalBytes(boot.receivePubkey, setup.offchainTapscript.options.pubKey)
+            ? setup.offchainTapscript
+            : rebuildTapscript(setup.offchainTapscript, boot.receivePubkey);
+        return { rotator: boot.rotator, offchainTapscript, provider };
+    }
+    /**
+     * Default factory-shaped boot any
+     * {@link ReceiveRotatorFactory.createReceiveRotator} implementation
+     * can delegate to. Pulls the wallet's current display contract from
+     * the contract repository (or allocates a fresh receive descriptor
+     * via the provider when no tagged display contract exists), and
+     * returns the rotator paired with the resolved receive pubkey.
+     *
+     * Used internally by `resolveBoot` when the provider doesn't
+     * implement {@link ReceiveRotatorFactory}. Exported so providers
+     * that *do* override can still invoke the default work for the
+     * parts of the boot path they don't want to customise. Tapscript
+     * construction is intentionally NOT in here — that's the
+     * orchestrator's job.
+     */
+    static async defaultBoot(provider, opts) {
+        const existing = await pickActiveReceive(opts.contractRepository, opts.serverPubKey, opts.expectedContractType);
+        if (existing) {
+            return {
+                rotator: new WalletReceiveRotator(provider, existing.script, opts.logger),
+                receivePubkey: existing.pubKey,
+            };
+        }
+        // No tagged display contract on this repo. Avoid burning a
+        // fresh HD index per restart: re-derive the descriptor at the
+        // most recently allocated index when the provider supports it
+        // (HD-style allocators do; static / one-shot providers don't
+        // and fall through to a regular allocation, which is a no-op
+        // for them anyway).
+        let descriptor;
+        if (hasPeekableDescriptor(provider)) {
+            descriptor = await provider.getCurrentSigningDescriptor();
+        }
+        descriptor ?? (descriptor = await provider.getNextSigningDescriptor());
+        return {
+            rotator: new WalletReceiveRotator(provider, undefined, opts.logger),
+            receivePubkey: deriveLeafPubkey(descriptor),
+        };
+    }
+    /**
+     * Phase 2 — post-`getVtxoManager()`. Subscribe to `vtxo_received`
+     * and trigger a rotation whenever the currently-active display
+     * contract receives funds. Old display contracts remain `active`
+     * in the repo so earlier shared addresses keep crediting this
+     * wallet.
+     */
+    async install(wallet) {
+        const manager = await wallet.getContractManager();
+        this.unsubscribe = manager.onContractEvent((event) => {
+            if (event.type !== "vtxo_received")
+                return;
+            if (event.contractScript !== wallet.defaultContractScript)
+                return;
+            // Serialise rotations: each `vtxo_received` event is its
+            // own rotation trigger (BIP-44-style: one receive ⇒ one
+            // fresh address), so two rapid events on the same script
+            // are *expected* to burn two consecutive HD indices. The
+            // chain here only prevents the rotate → rebuild →
+            // createContract sequences from interleaving; it does not
+            // — and intentionally does not — dedupe events on the same
+            // script. `runRotateWithBackoff` owns the failure handling
+            // — it logs, increments the consecutive-failure counter,
+            // and gates future attempts behind exponential backoff so
+            // a broken provider can't make the rotator hammer
+            // `createContract` on every event.
+            this.chain = this.chain
+                .catch(() => undefined)
+                .then(() => this.runRotateWithBackoff(wallet));
+        });
+    }
+    /**
+     * Run a single rotation attempt, applying exponential backoff on
+     * failure. Public-shaped behavior:
+     * - During a backoff window: log + skip (no `rotate()` call).
+     * - On success: reset failure count and backoff.
+     * - On failure: increment counter, schedule next attempt at
+     *   `min(2^consecutiveFailures * 1s, ROTATION_MAX_BACKOFF_MS)`.
+     *
+     * Errors are deliberately swallowed (logged, not rethrown) so the
+     * surrounding `chain` Promise never settles to rejected — the next
+     * `vtxo_received` event must still get a chance to run.
+     */
+    async runRotateWithBackoff(wallet) {
+        const now = Date.now();
+        if (now < this.nextRotationAllowedAt) {
+            this.logger.error("WalletReceiveRotator: skipping rotation (in backoff)", {
+                consecutiveFailures: this.consecutiveFailures,
+                retryInMs: this.nextRotationAllowedAt - now,
+            });
+            return;
+        }
+        try {
+            await this.rotate(wallet);
+            this.consecutiveFailures = 0;
+            this.nextRotationAllowedAt = 0;
+        }
+        catch (err) {
+            this.consecutiveFailures += 1;
+            // 2^1=2s, 2^2=4s, … capped at ROTATION_MAX_BACKOFF_MS (60s).
+            // `Math.min` on the exponent prevents `2 ** 1024` overflow
+            // for pathologically long failure streaks.
+            const exponent = Math.min(this.consecutiveFailures, 16);
+            const backoffMs = Math.min(2 ** exponent * 1000, ROTATION_MAX_BACKOFF_MS);
+            this.nextRotationAllowedAt = Date.now() + backoffMs;
+            this.logger.error("WalletReceiveRotator: rotation failed", err, {
+                consecutiveFailures: this.consecutiveFailures,
+                nextAttemptInMs: backoffMs,
+            });
+        }
+    }
+    /**
+     * Wait for any in-flight rotation to complete. Useful in tests
+     * that need to observe the post-rotation state after dispatching
+     * a `vtxo_received` event synchronously; production code rarely
+     * needs to call this directly.
+     */
+    async drain() {
+        await this.chain.catch(() => undefined);
+    }
+    /**
+     * Tear down the subscription first so no late `vtxo_received` event
+     * can queue work on a disposing wallet, then drain any in-flight
+     * rotation so its `createContract` finishes before the contract
+     * manager itself disposes.
+     */
+    async dispose() {
+        if (this.unsubscribe) {
+            try {
+                this.unsubscribe();
+            }
+            catch {
+                // best-effort teardown
+            }
+            finally {
+                this.unsubscribe = undefined;
+            }
+        }
+        await this.chain.catch(() => undefined);
+    }
+    /**
+     * Allocate the next descriptor, swap it into the wallet's active
+     * offchain tapscript, register the new tagged contract, and retire
+     * the previous tagged contract (if any) by setting its state to
+     * `inactive`. The contract watcher keeps watching inactive
+     * contracts until their VTXOs are spent, so funds in flight at the
+     * old display address are not lost — only the address stops being
+     * advertised.
+     *
+     * Contract type matches the wallet's tapscript shape: a default
+     * wallet rotates to a new `default` contract, a delegate wallet to
+     * a new `delegate` contract.
+     *
+     * The first rotation on a fresh wallet does NOT deactivate
+     * anything: `currentTaggedScript` is `undefined` because the wallet
+     * was displaying the untagged index-0 baseline, which must stay
+     * active forever.
+     */
+    async rotate(wallet) {
+        // Build the new tapscript + derived strings entirely locally,
+        // so the wallet's visible state (`offchainTapscript`,
+        // `defaultContractScript`, `getAddress()`) doesn't change
+        // until the contract registration has succeeded. If
+        // `createContract` throws partway, the wallet is still
+        // displaying the OLD (registered) address — no
+        // unwatched-display-window.
+        const descriptor = await this.provider.getNextSigningDescriptor();
+        const pubKey = deriveLeafPubkey(descriptor);
+        const newTapscript = rebuildTapscript(wallet.offchainTapscript, pubKey);
+        const newScript = hex.encode(newTapscript.pkScript);
+        const newAddress = newTapscript
+            .address(wallet.network.hrp, wallet.arkServerPublicKey)
+            .encode();
+        const manager = await wallet.getContractManager();
+        const csvTimelock = newTapscript.options.csvTimelock ??
+            DefaultVtxo.Script.DEFAULT_TIMELOCK;
+        const csvTimelockStr = timelockToSequence(csvTimelock).toString();
+        const serverPubKeyHex = hex.encode(newTapscript.options.serverPubKey);
+        const baseParams = {
+            script: newScript,
+            address: newAddress,
+            state: "active",
+            // Persist the materialized signing descriptor alongside the
+            // source tag. The wallet's spending paths read this at sign
+            // time to route inputs locked by a rotated pubkey through
+            // `DescriptorProvider.signWithDescriptor` instead of the
+            // identity's index-0 key. Without it, post-rotation sends
+            // produce unsigned PSBTs that the server rejects with
+            // `INVALID_PSBT_INPUT (5): missing tapscript spend sig`.
+            metadata: {
+                source: WALLET_RECEIVE_SOURCE,
+                signingDescriptor: descriptor,
+            },
+        };
+        if (newTapscript instanceof DelegateVtxo.Script) {
+            await manager.createContract({
+                ...baseParams,
+                type: "delegate",
+                params: {
+                    pubKey: hex.encode(pubKey),
+                    serverPubKey: serverPubKeyHex,
+                    delegatePubKey: hex.encode(newTapscript.options.delegatePubKey),
+                    csvTimelock: csvTimelockStr,
+                },
+            });
+        }
+        else {
+            await manager.createContract({
+                ...baseParams,
+                type: "default",
+                params: {
+                    pubKey: hex.encode(pubKey),
+                    serverPubKey: serverPubKeyHex,
+                    csvTimelock: csvTimelockStr,
+                },
+            });
+        }
+        // Persistence succeeded — commit the new tapscript to the
+        // wallet's visible state. From this point onward
+        // `wallet.defaultContractScript` and `getAddress()` reflect
+        // the rotated identity. `setOffchainTapscriptForRotation` is
+        // the only write path; the field is read-only otherwise.
+        wallet.setOffchainTapscriptForRotation(newTapscript);
+        // Retire the previous tagged contract (if any). The order
+        // matters: deactivate FIRST, then update `currentTaggedScript`,
+        // so that if `setContractState` throws the next rotation will
+        // retry deactivating the same orphaned contract instead of
+        // racing forward and orphaning the new one.
+        const previousTagged = this.currentTaggedScript;
+        if (previousTagged !== undefined && previousTagged !== newScript) {
+            await manager.setContractState(previousTagged, "inactive");
+        }
+        this.currentTaggedScript = newScript;
+    }
+}
+/**
+ * Extract the x-only (32-byte) pubkey from a materialized HD descriptor.
+ *
+ * `expand()` populates `@0.pubkey` for non-ranged descriptors (including
+ * HD ones where a concrete child index has been substituted for the
+ * wildcard). This sidesteps `extractPubKey`, which intentionally rejects
+ * any descriptor carrying a `bip32` key because it was designed for
+ * static `tr(pubkey)` inputs.
+ */
+function deriveLeafPubkey(descriptor) {
+    const network = isMainnetDescriptor(descriptor)
+        ? networks.bitcoin
+        : networks.testnet;
+    // `expand` raises when the descriptor still carries a wildcard or
+    // is otherwise non-rangeable. Wrap so callers (most importantly
+    // `resolveBoot`'s silent-fallback path) can branch on a typed
+    // error class instead of grepping `err.message`.
+    let expansion;
+    try {
+        expansion = expand({ descriptor, network });
+    }
+    catch (e) {
+        throw new NonRangeableDescriptorError(`Cannot derive leaf pubkey from descriptor (length=${descriptor.length}): ` +
+            `ensure the descriptor is materialized (no wildcard) and parsable.`, { cause: e });
+    }
+    const key = expansion.expansionMap?.["@0"];
+    if (!key?.pubkey) {
+        // Avoid interpolating the descriptor itself: it normally
+        // contains an xpub, but a misconfigured caller could pass an
+        // xprv, and error messages surface in logs / crash reporters /
+        // Sentry. The length is enough context for debugging.
+        throw new NonRangeableDescriptorError(`Cannot derive leaf pubkey from descriptor (length=${descriptor.length}): ` +
+            `descriptor parsed but no '@0' pubkey was found in the expansion map. ` +
+            `The rotator expects a materialized tr(xpub/.../*) shape; ensure the ` +
+            `descriptor has no wildcard and that its key resolves into the '@0' slot.`);
+    }
+    return key.pubkey;
+}
+/**
+ * Rebuild the given offchain tapscript with a different owner pubkey,
+ * preserving its {@link DelegateVtxo.Script} vs {@link DefaultVtxo.Script}
+ * shape and all other options.
+ *
+ * Exported because the wallet's boot path also needs to rebuild the
+ * initial tapscript when the resolved boot pubkey differs from the
+ * identity's default pubkey.
+ */
+export function rebuildTapscript(current, pubKey) {
+    if (current instanceof DelegateVtxo.Script) {
+        return new DelegateVtxo.Script({ ...current.options, pubKey });
+    }
+    return new DefaultVtxo.Script({ ...current.options, pubKey });
+}
+/**
+ * Look up the most-recently-created active tagged display contract that
+ * this wallet itself generated. Returns the contract's pubkey + script,
+ * or `undefined` when no such contract exists — the caller should treat
+ * that as "fresh wallet (or static-only history) on this repo" and
+ * allocate a new descriptor.
+ *
+ * Filters by `serverPubKey` so a contract repo seeded against a different
+ * server doesn't accidentally resurrect an unrelated pubkey, and by the
+ * `metadata.source` sentinel so untagged baseline contracts (and
+ * contracts created by other code paths — legacy timelock registrations,
+ * external integrations) are not mistaken for the wallet's display
+ * address.
+ *
+ * When `expectedType` is provided, only contracts of that type are considered,
+ * preventing a "default" wallet from accidentally picking up a "delegate" contract
+ * or vice versa.
+ */
+async function pickActiveReceive(contractRepository, serverPubKey, expectedType) {
+    // Both `default` and `delegate` contract types can be the wallet's
+    // display address (delegate wallets use the delegate variant). The
+    // `metadata.source` tag is the discriminator that says "this is the
+    // one I generated for myself."
+    const candidates = await contractRepository.getContracts({
+        type: expectedType ? [expectedType] : ["default", "delegate"],
+        state: "active",
+    });
+    const serverPubKeyHex = hex.encode(serverPubKey);
+    const matching = candidates
+        .filter((c) => c.params.serverPubKey === serverPubKeyHex &&
+        c.metadata?.source === WALLET_RECEIVE_SOURCE)
+        .sort((a, b) => b.createdAt - a.createdAt);
+    const newest = matching[0];
+    if (!newest?.params.pubKey)
+        return undefined;
+    try {
+        return {
+            pubKey: hex.decode(newest.params.pubKey),
+            script: newest.script,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Resolve the polymorphic `walletMode` config field into a concrete
+ * {@link DescriptorProvider} (or `undefined` for the static path).
+ *
+ * - `'auto'` *(default)*: **short-term**, behaves like `'static'` — no
+ *   HD rotation. See the `TODO` below for the criteria to flip this
+ *   back to the identity-probing behaviour.
+ * - `'static'`: returns `undefined`.
+ * - A {@link DescriptorProvider} instance: returns it as-is.
+ * - `'hd'`: builds the built-in HD provider from the identity. Throws
+ *   if the identity isn't HD-capable or the descriptor isn't rangeable —
+ *   no silent fallback.
+ */
+async function resolveDescriptorProvider(config, walletRepository) {
+    const mode = config.walletMode ?? "auto";
+    // TODO(hd-maturation): TEMPORARY — collapse `'auto'` into `'static'`
+    // until the HD receive-rotation pipeline has soaked in the field.
+    // Flip `'auto'` back to its identity-probing behaviour once:
+    //   1. At least one consumer (btcpay-arkade, arkade-os/wallet,
+    //      Fulmine) has been running with `walletMode: 'hd'` against
+    //      mainnet for ≥ 1 month with no rotation-induced fund-loss
+    //      or address-drift reports.
+    //   2. The test `default ('auto') currently behaves like 'static'`
+    //      in `test/walletHdRotation.test.ts` is flipped in the same
+    //      commit (it's the explicit gate — flipping the default
+    //      MUST flip the test).
+    //   3. The `WalletMode` docstring in `src/wallet/index.ts` is
+    //      updated to drop the "behaves like 'static' for now" notice.
+    if (mode === "static" || mode === "auto")
+        return undefined;
+    if (typeof mode !== "string") {
+        // Caller supplied a DescriptorProvider directly.
+        return mode;
+    }
+    // mode === 'hd'
+    if (!isHDCapableIdentity(config.identity)) {
+        throw new Error("walletMode 'hd' requires an HD-capable identity " +
+            "(SeedIdentity / MnemonicIdentity with a rangeable BIP-32 " +
+            "descriptor) or an explicit DescriptorProvider.");
+    }
+    try {
+        return await HDDescriptorProvider.create(config.identity, walletRepository);
+    }
+    catch (e) {
+        throw new Error("walletMode 'hd' failed to initialize: " +
+            (e instanceof Error ? e.message : String(e)), { cause: e });
+    }
+}

package/dist/esm/worker/messageBus.js

@@ -179,6 +179,7 @@ export class MessageBus {
                 storage,
                 delegatorProvider,
                 settlementConfig: config.settlementConfig,
+                walletMode: config.walletMode,
                 watcherConfig: config.watcherConfig,
             });
             return { wallet, arkProvider, readonlyWallet: wallet };

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

@@ -8,6 +8,23 @@ export type RefreshVtxosOptions = {
     scripts?: string[];
     after?: number;
     before?: number;
+    /**
+     * When true and `scripts` is not set, refresh every contract in
+     * the repository — including those marked `inactive` and those
+     * that have dropped out of the watcher's active set. Useful for
+     * "did anyone send funds to a stale rotated display address?"
+     * audits.
+     *
+     * Because this is a *superset* of the watcher's watched set, the
+     * cursor invariant still holds and the cursor advances normally
+     * (unless an explicit `after` / `before` window is also supplied).
+     *
+     * Ignored when `scripts` is set (the explicit list already
+     * specifies what to refresh, regardless of contract state).
+     *
+     * @defaultValue `false`
+     */
+    includeInactive?: boolean;
 };
 export interface IContractManager extends Disposable {
     /**
@@ -320,9 +337,22 @@ export declare class ContractManager implements IContractManager {
     /**
      * Force refresh virtual outputs from the indexer.
      *
-     * Without options, re-fetches every contract and advances the global cursor.
-     * With options, narrows the refresh to specific scripts and/or a time window.
-     * Subset refreshes (scripts filter) intentionally do not advance the cursor.
+     * Without options, re-fetches every contract in the watcher's
+     * watched set and advances the global cursor.
+     *
+     * `scripts` narrows the refresh to a specific list (subset query —
+     * cursor is not advanced because contracts outside the list may
+     * have data we'd skip).
+     *
+     * `includeInactive: true` (and no `scripts`) widens the refresh to
+     * every contract in the repository, including ones marked
+     * `inactive` and ones that have dropped out of the watcher's
+     * active set. This is a *superset* of the watched set, so the
+     * cursor invariant still holds and the cursor advances normally.
+     *
+     * `after` / `before` apply a caller-supplied time window. The
+     * cursor never advances on a windowed query because the window
+     * may skip data outside its bounds.
      */
     refreshVtxos(opts?: RefreshVtxosOptions): Promise<void>;
     refreshOutpoints(outpoints: Outpoint[]): Promise<void>;

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

@@ -1,6 +1,6 @@
 import { Bytes } from "@scure/btc-signer/utils.js";
 import { EncodedVtxoScript, TapLeafScript, VtxoScript } from "../script/base.js";
-import { VirtualCoin, TapLeaves } from "../wallet/index.js";
+import { ExtendedVirtualCoin, VirtualCoin, TapLeaves } from "../wallet/index.js";
 import { ContractFilter } from "../repositories/index.js";
 /**
  * Contract state indicating whether it should be actively monitored.
@@ -70,6 +70,23 @@ export type ContractVtxo = VirtualCoin & Partial<TapLeaves & EncodedVtxoScript>
     extraWitness?: Bytes[];
     contractScript: string;
 };
+/**
+ * A {@link ContractVtxo} with all taproot annotation fields required.
+ *
+ * Mirrors the {@link ExtendedVirtualCoin} / {@link VirtualCoin} split:
+ * - {@link ContractVtxo} carries `TapLeaves` and `EncodedVtxoScript` as
+ *   `Partial<>` because VTXOs fetched raw from the indexer do not yet have
+ *   taproot data.
+ * - `ExtendedContractVtxo` narrows those fields to required, guaranteeing
+ *   that `annotateVtxos` has run and the taproot leaves are present.
+ *
+ * Use this type (instead of {@link ContractVtxo}) wherever the compiler
+ * should enforce that annotation has happened — e.g. `saveVtxos` and
+ * forfeit transaction construction.
+ */
+export type ExtendedContractVtxo = ExtendedVirtualCoin & {
+    contractScript: string;
+};
 /**
  * Result of path selection, including the tapleaf to use and any extra witness data.
  */
@@ -218,7 +235,7 @@ export type GetContractsFilter = ContractFilter;
  */
 export type ContractWithVtxos = {
     contract: Contract;
-    vtxos: ContractVtxo[];
+    vtxos: ExtendedContractVtxo[];
 };
 /**
  * Summary of a contract's balance.

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

@@ -18,6 +18,13 @@ export interface DescriptorSigningRequest {
  * 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.
+ *
+ * Providers that want to participate in HD receive rotation can also
+ * implement the wallet-side `ReceiveRotatorFactory` interface (see
+ * `src/wallet/walletReceiveRotator.ts`). That extension is opt-in — the
+ * core `DescriptorProvider` contract intentionally stays free of
+ * wallet-specific concerns so HSM-backed and other minimal providers
+ * don't have to know about the receive-rotation lifecycle.
  */
 export interface DescriptorProvider {
     /**