@arkade-os/sdk 0.4.26 → 0.4.27

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

@@ -19,7 +19,13 @@ export interface ReadonlyHDCapableIdentity extends ReadonlyIdentity {
      * concrete descriptor by replacing the `*` with a derivation index.
      */
     readonly descriptor: string;
-    /** True iff `descriptor` derives from this identity's xpub/seed. */
+    /**
+     * True iff `descriptor` derives from this identity's xpub/seed.
+     *
+     * @deprecated Prefer `DescriptorProvider.isOurs()` via
+     * `HDDescriptorProvider` for rotating HD wallets or
+     * `StaticDescriptorProvider` for legacy single-key wallets.
+     */
     isOurs(descriptor: string): boolean;
 }
 /**
@@ -37,8 +43,29 @@ export interface ReadonlyHDCapableIdentity extends ReadonlyIdentity {
  *    explicitly-non-rotating use cases.
  */
 export interface HDCapableIdentity extends ReadonlyHDCapableIdentity, Identity {
-    /** Signs each request with the key derived from its descriptor. */
+    /**
+     * Signs each request with the key derived from its descriptor.
+     *
+     * @deprecated Prefer `DescriptorProvider.signWithDescriptor()` via
+     * `HDDescriptorProvider` or `StaticDescriptorProvider`. Identities keep
+     * this method only as backing implementation for descriptor providers.
+     */
     signWithDescriptor(requests: DescriptorSigningRequest[]): Promise<Transaction[]>;
-    /** Signs a message using the key derived from `descriptor`. */
+    /**
+     * Signs a message using the key derived from `descriptor`.
+     *
+     * @deprecated Prefer `DescriptorProvider.signMessageWithDescriptor()` via
+     * `HDDescriptorProvider` or `StaticDescriptorProvider`. Identities keep
+     * this method only as backing implementation for descriptor providers.
+     */
     signMessageWithDescriptor(descriptor: string, message: Uint8Array, signatureType?: "schnorr" | "ecdsa"): Promise<Uint8Array>;
 }
+/**
+ * Structural type guard for {@link HDCapableIdentity}. Returns `true`
+ * when the value exposes the four members the HD wallet flow relies on:
+ * `descriptor`, `isOurs`, `signWithDescriptor`, and
+ * `signMessageWithDescriptor`. Used by callers that need to opt into
+ * the HD path (e.g. installing an `HDDescriptorProvider`) without
+ * coupling to a concrete identity class.
+ */
+export declare function isHDCapableIdentity(value: unknown): value is HDCapableIdentity;

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

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

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

@@ -117,15 +117,27 @@ export declare class SeedIdentity implements HDCapableIdentity {
      * 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}.
+     *
+     * @deprecated Prefer `DescriptorProvider.isOurs()` via
+     * `HDDescriptorProvider` for rotating HD wallets or
+     * `StaticDescriptorProvider` for legacy single-key wallets.
      */
     isOurs(descriptor: string): boolean;
     /**
      * Signs each request with the key derived from its descriptor.
      * Each descriptor must share this identity's seed ({@link isOurs}).
+     *
+     * @deprecated Prefer `DescriptorProvider.signWithDescriptor()` via
+     * `HDDescriptorProvider` or `StaticDescriptorProvider`. Identities keep
+     * this method only as backing implementation for descriptor providers.
      */
     signWithDescriptor(requests: DescriptorSigningRequest[]): Promise<Transaction[]>;
     /**
      * Signs a message with the key derived from `descriptor`.
+     *
+     * @deprecated Prefer `DescriptorProvider.signMessageWithDescriptor()` via
+     * `HDDescriptorProvider` or `StaticDescriptorProvider`. Identities keep
+     * this method only as backing implementation for descriptor providers.
      */
     signMessageWithDescriptor(descriptor: string, message: Uint8Array, signatureType?: "schnorr" | "ecdsa"): Promise<Uint8Array>;
     private derivePrivateKeyForDescriptor;
@@ -212,6 +224,10 @@ export declare class ReadonlyDescriptorIdentity implements ReadonlyHDCapableIden
      * HD descriptors match by account xpub; bare `tr(pubkey)` descriptors
      * fall back to comparing against the index-0 x-only pubkey. See
      * {@link descriptorIsOurs}.
+     *
+     * @deprecated Prefer `DescriptorProvider.isOurs()` via
+     * `HDDescriptorProvider` for rotating HD wallets or
+     * `StaticDescriptorProvider` for legacy single-key wallets.
      */
     isOurs(descriptor: string): boolean;
 }

package/dist/types/index.d.ts

@@ -9,9 +9,9 @@ import { DefaultVtxo } from "./script/default.js";
 import { DelegateVtxo } from "./script/delegate.js";
 import { MessageHandler, RequestEnvelope, ResponseEnvelope, MessageBus } from "./worker/messageBus.js";
 import { VtxoScript, EncodedVtxoScript, TapLeafScript, TapTreeCoder, getSequence } from "./script/base.js";
-import { TxType, IWallet, IReadonlyWallet, BaseWalletConfig, WalletConfig, ReadonlyWalletConfig, ProviderClass, ArkTransaction, Coin, ExtendedCoin, ExtendedVirtualCoin, WalletBalance, SendBitcoinParams, SettleParams, Status, VirtualStatus, Outpoint, VirtualCoin, TxKey, GetVtxosFilter, TapLeaves, StorageConfig, isSpendable, isSubdust, isRecoverable, isExpired, Asset, Recipient, IssuanceParams, IssuanceResult, ReissuanceParams, BurnParams, AssetDetails, AssetMetadata, KnownMetadata } from "./wallet/index.js";
+import { TxType, IWallet, IReadonlyWallet, BaseWalletConfig, WalletConfig, WalletMode, ReadonlyWalletConfig, ProviderClass, ArkTransaction, Coin, ExtendedCoin, ExtendedVirtualCoin, WalletBalance, SendBitcoinParams, SettleParams, Status, VirtualStatus, Outpoint, VirtualCoin, TxKey, GetVtxosFilter, TapLeaves, StorageConfig, isSpendable, isSubdust, isRecoverable, isExpired, Asset, Recipient, IssuanceParams, IssuanceResult, ReissuanceParams, BurnParams, AssetDetails, AssetMetadata, KnownMetadata } from "./wallet/index.js";
 import { Batch } from "./wallet/batch.js";
-import { Wallet, ReadonlyWallet, waitForIncomingFunds, IncomingFunds } from "./wallet/wallet.js";
+import { Wallet, ReadonlyWallet, waitForIncomingFunds, IncomingFunds, DescriptorSigningProviderMissingError, MissingSigningDescriptorError } from "./wallet/wallet.js";
 import { TxTree, TxTreeNode } from "./tree/txTree.js";
 import { SignerSession, TreeNonces, TreePartialSigs } from "./tree/signingSession.js";
 import { Ramps } from "./wallet/ramps.js";
@@ -19,7 +19,7 @@ import { HDDescriptorProvider } from "./wallet/hdDescriptorProvider.js";
 import { isVtxoExpiringSoon, VtxoManager } from "./wallet/vtxo-manager.js";
 import type { IVtxoManager, SettlementConfig } from "./wallet/vtxo-manager.js";
 import { ServiceWorkerWallet, ServiceWorkerReadonlyWallet, DEFAULT_MESSAGE_TIMEOUTS } from "./wallet/serviceWorker/wallet.js";
-import type { MessageTimeouts } from "./wallet/serviceWorker/wallet.js";
+import type { MessageTimeouts, ServiceWorkerWalletMode } from "./wallet/serviceWorker/wallet.js";
 import { OnchainWallet } from "./wallet/onchain.js";
 import { setupServiceWorker } from "./worker/browser/utils.js";
 import { ESPLORA_URL, EsploraProvider, OnchainProvider, ExplorerTransaction } from "./providers/onchain.js";
@@ -49,11 +49,11 @@ import { DelegatorManagerImpl, IDelegatorManager } from "./wallet/delegator.js";
 export * from "./arkfee/index.js";
 export * as asset from "./extension/asset/index.js";
 import { ContractManager, ContractWatcher, contractHandlers, DefaultContractHandler, DelegateContractHandler, VHTLCContractHandler, encodeArkContract, decodeArkContract, contractFromArkContract, contractFromArkContractWithAddress, isArkContract } from "./contracts/index.js";
-import type { Contract, ContractVtxo, ContractState, ContractEvent, ContractEventCallback, ContractBalance, ContractWithVtxos, ContractHandler, PathSelection, PathContext, ContractManagerConfig, CreateContractParams, ContractWatcherConfig, ParsedArkContract, DefaultContractParams, DelegateContractParams, VHTLCContractParams } from "./contracts/index.js";
+import type { Contract, ContractVtxo, ContractState, ContractEvent, ContractEventCallback, ContractBalance, ContractWithVtxos, ContractHandler, PathSelection, PathContext, ExtendedContractVtxo, ContractManagerConfig, CreateContractParams, ContractWatcherConfig, ParsedArkContract, DefaultContractParams, DelegateContractParams, VHTLCContractParams } from "./contracts/index.js";
 import { IContractManager } from "./contracts/contractManager.js";
 import { timelockToSequence, sequenceToTimelock } from "./utils/timelock.js";
 import { closeDatabase, openDatabase } from "./repositories/indexedDB/manager.js";
 import { WalletMessageHandler, WalletNotInitializedError, ReadonlyWalletError, DelegatorNotConfiguredError } from "./wallet/serviceWorker/wallet-message-handler.js";
 import { MESSAGE_BUS_NOT_INITIALIZED, MessageBusNotInitializedError, ServiceWorkerTimeoutError } from "./worker/errors.js";
-export { Wallet, ReadonlyWallet, SingleKey, ReadonlySingleKey, SeedIdentity, MnemonicIdentity, ReadonlyDescriptorIdentity, isBatchSignable, OnchainWallet, Ramps, VtxoManager, HDDescriptorProvider, DelegatorManagerImpl, RestDelegatorProvider, ESPLORA_URL, EsploraProvider, ELECTRUM_WS_URL, ELECTRUM_TCP_HOST, ElectrumOnchainProvider, WsElectrumChainSource, RestArkProvider, RestIndexerProvider, ArkAddress, DefaultVtxo, DelegateVtxo, VtxoScript, VHTLC, TxType, IndexerTxType, ChainTxType, SettlementEventType, setupServiceWorker, MessageBus, WalletMessageHandler, WalletNotInitializedError, ReadonlyWalletError, DelegatorNotConfiguredError, MESSAGE_BUS_NOT_INITIALIZED, MessageBusNotInitializedError, ServiceWorkerTimeoutError, ServiceWorkerWallet, ServiceWorkerReadonlyWallet, DEFAULT_MESSAGE_TIMEOUTS, decodeTapscript, MultisigTapscript, CSVMultisigTapscript, ConditionCSVMultisigTapscript, ConditionMultisigTapscript, CLTVMultisigTapscript, TapTreeCoder, ArkPsbtFieldKey, ArkPsbtFieldKeyType, setArkPsbtField, getArkPsbtFields, CosignerPublicKey, VtxoTreeExpiry, VtxoTaprootTree, ConditionWitness, buildOffchainTx, verifyTapscriptSignatures, waitForIncomingFunds, hasBoardingTxExpired, combineTapscriptSigs, isVtxoExpiringSoon, isValidArkAddress, ArkNote, networks, closeDatabase, openDatabase, IndexedDBWalletRepository, IndexedDBContractRepository, InMemoryWalletRepository, InMemoryContractRepository, MIGRATION_KEY, migrateWalletRepository, requiresMigration, getMigrationStatus, rollbackMigration, WalletRepositoryImpl, ContractRepositoryImpl, Intent, BIP322, TxTree, P2A, Unroll, Transaction, TxWeightEstimator, timelockToSequence, sequenceToTimelock, ArkError, maybeArkError, Batch, validateVtxoTxGraph, validateConnectorsTxGraph, buildForfeitTx, isRecoverable, isSpendable, isSubdust, isExpired, getSequence, ContractManager, ContractWatcher, contractHandlers, DefaultContractHandler, DelegateContractHandler, VHTLCContractHandler, encodeArkContract, decodeArkContract, contractFromArkContract, contractFromArkContractWithAddress, isArkContract, };
-export type { Identity, ReadonlyIdentity, BatchSignableIdentity, SignRequest, IWallet, IReadonlyWallet, BaseWalletConfig, WalletConfig, ReadonlyWalletConfig, ProviderClass, ArkTransaction, Coin, ExtendedCoin, ExtendedVirtualCoin, WalletBalance, SendBitcoinParams, SettleParams, Status, VirtualStatus, Outpoint, VirtualCoin, TxKey, TapscriptType, ArkTxInput, OffchainTx, TapLeaves, IncomingFunds, SeedIdentityOptions, MnemonicOptions, NetworkOptions, DescriptorOptions, IndexerProvider, PageResponse, BatchInfo, ChainTx, CommitmentTx, TxHistoryRecord, Vtxo, VtxoChain, Tx, OnchainProvider, ArkProvider, SettlementEvent, FeeInfo, ArkInfo, SignedIntent, Output, TxNotification, ExplorerTransaction, ElectrumTransactionHistory, ElectrumBlockHeader, ElectrumUnspent, BatchFinalizationEvent, BatchFinalizedEvent, BatchFailedEvent, TreeSigningStartedEvent, TreeNoncesEvent, BatchStartedEvent, TreeTxEvent, TreeSignatureEvent, ScheduledSession, PaginationOptions, SubscriptionResponse, SubscriptionHeartbeat, SubscriptionEvent, Network, NetworkName, ArkTapscript, RelativeTimelock, EncodedVtxoScript, TapLeafScript, SignerSession, TreeNonces, TreePartialSigs, GetVtxosFilter, SettlementConfig, IVtxoManager, Asset, Recipient, IssuanceParams, IssuanceResult, ReissuanceParams, BurnParams, AssetDetails, AssetMetadata, KnownMetadata, Nonces, PartialSig, ArkPsbtFieldCoder, TxTreeNode, AnchorBumper, VSize, StorageConfig, Contract, ContractVtxo, ContractState, ContractEvent, ContractEventCallback, ContractBalance, ContractWithVtxos, ContractHandler, IContractManager, PathSelection, PathContext, ContractManagerConfig, CreateContractParams, ContractWatcherConfig, ParsedArkContract, DefaultContractParams, DelegateContractParams, VHTLCContractParams, MessageHandler, RequestEnvelope, ResponseEnvelope, MessageTimeouts, IDelegatorManager, DelegatorProvider, DelegateInfo, DelegateOptions, WalletRepository, ContractRepository, MigrationStatus, };
+export { Wallet, ReadonlyWallet, SingleKey, ReadonlySingleKey, SeedIdentity, MnemonicIdentity, ReadonlyDescriptorIdentity, isBatchSignable, OnchainWallet, Ramps, VtxoManager, HDDescriptorProvider, DelegatorManagerImpl, RestDelegatorProvider, ESPLORA_URL, EsploraProvider, ELECTRUM_WS_URL, ELECTRUM_TCP_HOST, ElectrumOnchainProvider, WsElectrumChainSource, RestArkProvider, RestIndexerProvider, ArkAddress, DefaultVtxo, DelegateVtxo, VtxoScript, VHTLC, TxType, IndexerTxType, ChainTxType, SettlementEventType, setupServiceWorker, MessageBus, WalletMessageHandler, WalletNotInitializedError, ReadonlyWalletError, DelegatorNotConfiguredError, MESSAGE_BUS_NOT_INITIALIZED, MessageBusNotInitializedError, ServiceWorkerTimeoutError, ServiceWorkerWallet, ServiceWorkerReadonlyWallet, DEFAULT_MESSAGE_TIMEOUTS, decodeTapscript, MultisigTapscript, CSVMultisigTapscript, ConditionCSVMultisigTapscript, ConditionMultisigTapscript, CLTVMultisigTapscript, TapTreeCoder, ArkPsbtFieldKey, ArkPsbtFieldKeyType, setArkPsbtField, getArkPsbtFields, CosignerPublicKey, VtxoTreeExpiry, VtxoTaprootTree, ConditionWitness, buildOffchainTx, verifyTapscriptSignatures, waitForIncomingFunds, hasBoardingTxExpired, combineTapscriptSigs, isVtxoExpiringSoon, isValidArkAddress, ArkNote, networks, closeDatabase, openDatabase, IndexedDBWalletRepository, IndexedDBContractRepository, InMemoryWalletRepository, InMemoryContractRepository, MIGRATION_KEY, migrateWalletRepository, requiresMigration, getMigrationStatus, rollbackMigration, WalletRepositoryImpl, ContractRepositoryImpl, Intent, BIP322, TxTree, P2A, Unroll, Transaction, TxWeightEstimator, timelockToSequence, sequenceToTimelock, ArkError, maybeArkError, DescriptorSigningProviderMissingError, MissingSigningDescriptorError, Batch, validateVtxoTxGraph, validateConnectorsTxGraph, buildForfeitTx, isRecoverable, isSpendable, isSubdust, isExpired, getSequence, ContractManager, ContractWatcher, contractHandlers, DefaultContractHandler, DelegateContractHandler, VHTLCContractHandler, encodeArkContract, decodeArkContract, contractFromArkContract, contractFromArkContractWithAddress, isArkContract, };
+export type { Identity, ReadonlyIdentity, BatchSignableIdentity, SignRequest, IWallet, IReadonlyWallet, BaseWalletConfig, WalletConfig, WalletMode, ReadonlyWalletConfig, ProviderClass, ArkTransaction, Coin, ExtendedCoin, ExtendedVirtualCoin, WalletBalance, SendBitcoinParams, SettleParams, Status, VirtualStatus, Outpoint, VirtualCoin, TxKey, TapscriptType, ArkTxInput, OffchainTx, TapLeaves, IncomingFunds, SeedIdentityOptions, MnemonicOptions, NetworkOptions, DescriptorOptions, IndexerProvider, PageResponse, BatchInfo, ChainTx, CommitmentTx, TxHistoryRecord, Vtxo, VtxoChain, Tx, OnchainProvider, ArkProvider, SettlementEvent, FeeInfo, ArkInfo, SignedIntent, Output, TxNotification, ExplorerTransaction, ElectrumTransactionHistory, ElectrumBlockHeader, ElectrumUnspent, BatchFinalizationEvent, BatchFinalizedEvent, BatchFailedEvent, TreeSigningStartedEvent, TreeNoncesEvent, BatchStartedEvent, TreeTxEvent, TreeSignatureEvent, ScheduledSession, PaginationOptions, SubscriptionResponse, SubscriptionHeartbeat, SubscriptionEvent, Network, NetworkName, ArkTapscript, RelativeTimelock, EncodedVtxoScript, TapLeafScript, SignerSession, TreeNonces, TreePartialSigs, GetVtxosFilter, SettlementConfig, IVtxoManager, Asset, Recipient, IssuanceParams, IssuanceResult, ReissuanceParams, BurnParams, AssetDetails, AssetMetadata, KnownMetadata, Nonces, PartialSig, ArkPsbtFieldCoder, TxTreeNode, AnchorBumper, VSize, StorageConfig, Contract, ContractVtxo, ContractState, ContractEvent, ContractEventCallback, ContractBalance, ContractWithVtxos, ContractHandler, IContractManager, PathSelection, ExtendedContractVtxo, PathContext, ContractManagerConfig, CreateContractParams, ContractWatcherConfig, ParsedArkContract, DefaultContractParams, DelegateContractParams, VHTLCContractParams, MessageHandler, RequestEnvelope, ResponseEnvelope, MessageTimeouts, ServiceWorkerWalletMode, IDelegatorManager, DelegatorProvider, DelegateInfo, DelegateOptions, WalletRepository, ContractRepository, MigrationStatus, };

package/dist/types/wallet/hdDescriptorProvider.d.ts

@@ -2,6 +2,7 @@ import { DescriptorProvider, DescriptorSigningRequest } from "../identity/descri
 import { HDCapableIdentity } from "../identity/hdCapableIdentity.js";
 import { WalletRepository } from "../repositories/walletRepository.js";
 import { Transaction } from "../utils/transaction.js";
+import { ReceiveRotatorBoot, ReceiveRotatorBootOpts, ReceiveRotatorFactory } from "./walletReceiveRotator.js";
 /**
  * HD-wallet {@link DescriptorProvider} that allocates a fresh signing
  * descriptor on every call. The provider holds no notion of "current" — it
@@ -29,7 +30,7 @@ import { Transaction } from "../utils/transaction.js";
  * // next: tr([fp/86'/0'/0']xpub/0/1)
  * ```
  */
-export declare class HDDescriptorProvider implements DescriptorProvider {
+export declare class HDDescriptorProvider implements DescriptorProvider, ReceiveRotatorFactory {
     private readonly identity;
     private readonly walletRepository;
     private constructor();
@@ -48,6 +49,19 @@ export declare class HDDescriptorProvider implements DescriptorProvider {
      * index.
      */
     getNextSigningDescriptor(): Promise<string>;
+    /**
+     * Re-derive the descriptor at the most recently allocated index
+     * WITHOUT advancing — i.e. read the same descriptor
+     * `getNextSigningDescriptor` last returned. Returns `undefined`
+     * when no descriptor has ever been allocated on this repo.
+     *
+     * Used by the boot path to keep the wallet's display address
+     * stable across restarts: when no tagged display contract exists
+     * (e.g. a fresh wallet that hasn't rotated yet, or a wallet whose
+     * baseline-only repo carries no rotation history), the boot should
+     * re-derive the existing index rather than burn a new one.
+     */
+    getCurrentSigningDescriptor(): Promise<string | undefined>;
     /**
      * Returns true when the given descriptor is derivable from this wallet's
      * seed. Delegates to the underlying identity, which handles both HD and
@@ -62,6 +76,13 @@ export declare class HDDescriptorProvider implements DescriptorProvider {
     signWithDescriptor(requests: DescriptorSigningRequest[]): Promise<Transaction[]>;
     /** Signs a message using the key derived from `descriptor`. */
     signMessageWithDescriptor(descriptor: string, message: Uint8Array, signatureType?: "schnorr" | "ecdsa"): Promise<Uint8Array>;
+    /**
+     * HD providers participate in receive rotation. The default
+     * factory boot (contract-repo lookup → allocate fresh descriptor)
+     * is exactly what we want, so this just delegates to
+     * {@link WalletReceiveRotator.defaultBoot}.
+     */
+    createReceiveRotator(opts: ReceiveRotatorBootOpts): Promise<ReceiveRotatorBoot | undefined>;
     /**
      * Substitute the wildcard in the identity's account-descriptor template
      * with a concrete index, going through the descriptors-scure parser

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

@@ -1,6 +1,7 @@
 import { Bytes } from "@scure/btc-signer/utils.js";
 import { ArkProvider, Output, SettlementEvent } from "../providers/ark.js";
 import { Identity, ReadonlyIdentity } from "../identity/index.js";
+import { DescriptorProvider } from "../identity/descriptorProvider.js";
 import { RelativeTimelock } from "../script/tapscript.js";
 import { EncodedVtxoScript, TapLeafScript } from "../script/base.js";
 import { RenewalConfig, SettlementConfig } from "./vtxo-manager.js";
@@ -15,6 +16,30 @@ import { DelegatorProvider } from "../providers/delegator.js";
 export declare const DEFAULT_ARKADE_SERVER_URL: "https://arkade.computer";
 export declare const DEFAULT_ARKADE_HRP: "ark";
 export declare const DEFAULT_NETWORK_NAME: "bitcoin";
+/**
+ * Wallet receive-address strategy.
+ *
+ * - `'auto'` *(default)*: **short-term** — currently identical to
+ *   `'static'`. The `'auto'` name is reserved for a future change that
+ *   will re-enable identity-probing once HD rotation has matured in
+ *   the field. Until then, opt into HD explicitly via `'hd'` or a
+ *   {@link DescriptorProvider}.
+ *   *(See `TODO(hd-maturation)` in
+ *   `src/wallet/walletReceiveRotator.ts:resolveDescriptorProvider` for
+ *   the flip-back criteria.)*
+ * - `'static'`: never rotate. The wallet uses one receive address derived
+ *   from `identity.xOnlyPublicKey()`.
+ * - `'hd'`: must rotate, using the built-in HD provider derived from the
+ *   identity. Throws at `Wallet.create` if the identity isn't HD-capable
+ *   or its descriptor isn't rangeable — no silent fallback.
+ * - A {@link DescriptorProvider} instance: rotate via the supplied
+ *   provider on every incoming VTXO. The wallet does not probe the
+ *   identity; the caller is responsible for ensuring the identity can
+ *   sign for whatever pubkey the provider returns. Errors thrown by the
+ *   provider propagate — there is no silent fallback for an explicit
+ *   provider.
+ */
+export type WalletMode = "auto" | "static" | "hd" | DescriptorProvider;
 /**
  * Base configuration options shared by all wallet types.
  *
@@ -164,6 +189,15 @@ export interface WalletConfig extends ReadonlyWalletConfig {
      * @see SettlementConfig
      */
     settlementConfig?: SettlementConfig | false;
+    /**
+     * Receive-address strategy. Pass `'static'`, `'hd'`, or a
+     * {@link DescriptorProvider} instance to drive rotation; omit (or
+     * pass `'auto'`) for the built-in auto-detect behaviour. See
+     * {@link WalletMode}.
+     *
+     * @defaultValue `'auto'`
+     */
+    walletMode?: WalletMode;
 }
 /**
  * Repository implementations used to store wallet and contract state.

package/dist/types/wallet/inputSignerRouter.d.ts

@@ -0,0 +1,35 @@
+import { Transaction } from "@scure/btc-signer";
+import { Identity } from "../identity/index.js";
+import { ContractRepository } from "../repositories/contractRepository.js";
+import { DescriptorProvider } from "../identity/descriptorProvider.js";
+export interface InputSigningJob {
+    /** Index in the source transaction. */
+    index: number;
+    /**
+     * Script used to identify the owning contract. For normal inputs this
+     * is the input's witnessUtxo script. For arkTx inputs this is the
+     * source VTXO script, because the witnessUtxo carries the checkpoint
+     * script instead.
+     */
+    lookupScript: Uint8Array;
+}
+export interface InputSignerRouterDeps {
+    identity: Identity;
+    contractRepository: ContractRepository;
+    descriptorProvider?: DescriptorProvider;
+    boardingPkScript: Uint8Array;
+}
+/**
+ * Routes PSBT inputs to the correct signer based on the owning contract.
+ * Inputs whose script matches a `default`/`delegate` contract with a
+ * non-baseline owner are sent to {@link DescriptorProvider}; everything
+ * else (baseline-owned contracts, non-default/non-delegate contracts,
+ * and the boarding script) is sent to {@link Identity}. Inputs with no
+ * matching contract and no boarding match are silently skipped, matching
+ * how the wallet historically handled cosigner/connector inputs.
+ */
+export declare class InputSignerRouter {
+    private readonly deps;
+    constructor(deps: InputSignerRouterDeps);
+    sign(tx: Transaction, jobs: InputSigningJob[]): Promise<Transaction>;
+}

package/dist/types/wallet/serviceWorker/wallet.d.ts

@@ -10,6 +10,7 @@ import type { IVtxoManager, SettlementConfig } from "../vtxo-manager.js";
 import type { ContractWatcherConfig } from "../../contracts/contractWatcher.js";
 type RequestType = WalletUpdaterRequest["type"];
 export type MessageTimeouts = Partial<Record<RequestType, number>>;
+export type ServiceWorkerWalletMode = "auto" | "static" | "hd";
 export declare const DEFAULT_MESSAGE_TIMEOUTS: Readonly<Record<RequestType, number>>;
 /**
  * Service Worker-based wallet implementation for browser environments.
@@ -68,6 +69,14 @@ interface ServiceWorkerWalletOptions {
     messageBusTimeoutMs?: number;
     /** Optional settlement configuration forwarded to the worker wallet. */
     settlementConfig?: SettlementConfig | false;
+    /**
+     * Receive-address strategy forwarded to the worker wallet.
+     *
+     * Service workers can only receive serializable configuration, so the
+     * descriptor-provider object form accepted by `Wallet.create()` is not
+     * supported here.
+     */
+    walletMode?: ServiceWorkerWalletMode;
     /** Optional contract watcher configuration forwarded to the worker wallet. */
     watcherConfig?: Partial<Omit<ContractWatcherConfig, "indexerProvider">>;
     /**
@@ -109,6 +118,7 @@ type MessageBusInitConfig = {
     esploraUrl?: string;
     timeoutMs?: number;
     settlementConfig?: SettlementConfig | false;
+    walletMode?: ServiceWorkerWalletMode;
     watcherConfig?: Partial<Omit<ContractWatcherConfig, "indexerProvider">>;
     messageTimeouts?: Record<string, number>;
 };

package/dist/types/wallet/signingErrors.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Thrown when a rotated contract (default or delegate) is missing the
+ * metadata.signingDescriptor required to route it to a descriptor-aware
+ * signer.
+ */
+export declare class MissingSigningDescriptorError extends Error {
+    readonly contractScript: string;
+    readonly contractType: "default" | "delegate";
+    readonly name = "MissingSigningDescriptorError";
+    constructor(contractScript: string, contractType: "default" | "delegate");
+}
+/**
+ * Thrown when an input needs descriptor-aware signing but no
+ * DescriptorProvider was wired into the wallet.
+ */
+export declare class DescriptorSigningProviderMissingError extends Error {
+    readonly name = "DescriptorSigningProviderMissingError";
+    constructor();
+}

package/dist/types/wallet/wallet.d.ts

@@ -19,6 +19,9 @@ import { DelegatorProvider } from "../providers/delegator.js";
 import { DelegateVtxo } from "../script/delegate.js";
 import { IDelegatorManager } from "./delegator.js";
 import { ContractManager } from "../contracts/contractManager.js";
+import { WalletReceiveRotator } from "./walletReceiveRotator.js";
+import { DescriptorProvider } from "../identity/descriptorProvider.js";
+import { DescriptorSigningProviderMissingError, MissingSigningDescriptorError } from "./signingErrors.js";
 export declare const getArkadeServerUrl: ({ arkServerUrl, }: {
     arkServerUrl?: string;
 }) => string;
@@ -30,13 +33,13 @@ export type IncomingFunds = {
     newVtxos: ExtendedVirtualCoin[];
     spentVtxos: ExtendedVirtualCoin[];
 };
+export { DescriptorSigningProviderMissingError, MissingSigningDescriptorError };
 export declare class ReadonlyWallet implements IReadonlyWallet {
     readonly identity: ReadonlyIdentity;
     readonly network: Network;
     readonly onchainProvider: OnchainProvider;
     readonly indexerProvider: IndexerProvider;
     readonly arkServerPublicKey: Bytes;
-    readonly offchainTapscript: DefaultVtxo.Script | DelegateVtxo.Script;
     readonly boardingTapscript: DefaultVtxo.Script;
     readonly dustAmount: bigint;
     readonly walletRepository: WalletRepository;
@@ -50,7 +53,20 @@ export declare class ReadonlyWallet implements IReadonlyWallet {
     readonly walletContractTimelocks: RelativeTimelock[];
     protected _pendingSpendOutpoints: Set<string>;
     get assetManager(): IReadonlyAssetManager;
+    /**
+     * Backing field for the active receive tapscript. Read via the
+     * public `offchainTapscript` getter; written only by
+     * {@link Wallet.setOffchainTapscriptForRotation}, which
+     * {@link WalletReceiveRotator.rotate} is the sole intended caller of.
+     */
+    protected _offchainTapscript: DefaultVtxo.Script | DelegateVtxo.Script;
     protected constructor(identity: ReadonlyIdentity, network: Network, onchainProvider: OnchainProvider, indexerProvider: IndexerProvider, arkServerPublicKey: Bytes, offchainTapscript: DefaultVtxo.Script | DelegateVtxo.Script, boardingTapscript: DefaultVtxo.Script, dustAmount: bigint, walletRepository: WalletRepository, contractRepository: ContractRepository, delegatorProvider?: DelegatorProvider | undefined, watcherConfig?: ReadonlyWalletConfig["watcherConfig"], walletContractTimelocks?: RelativeTimelock[]);
+    /**
+     * Currently-active receive tapscript. Read-only from the outside;
+     * mutated only via {@link Wallet.setOffchainTapscriptForRotation}
+     * by {@link WalletReceiveRotator.rotate}.
+     */
+    get offchainTapscript(): DefaultVtxo.Script | DelegateVtxo.Script;
     /**
      * Protected helper to set up shared wallet configuration.
      * Extracts common logic used by both ReadonlyWallet.create() and Wallet.create().
@@ -215,6 +231,32 @@ export declare class Wallet extends ReadonlyWallet implements IWallet {
     private _vtxoManager?;
     private _vtxoManagerInitializing?;
     private _walletAssetManager?;
+    /**
+     * HD receive rotator. Owns the {@link DescriptorProvider}, the
+     * `vtxo_received` subscription, and the rotate-and-register
+     * lifecycle. Absent in `walletMode: 'static'` and for SingleKey
+     * wallets under `'auto'`. Wired in via the constructor; the actual
+     * subscription is installed lazily on first `getVtxoManager()` so
+     * the contract manager is up first.
+     */
+    private _receiveRotator?;
+    private _receiveRotatorInstalled;
+    /**
+     * Descriptor-aware signer used by {@link _signerRouter} to sign
+     * inputs locked by rotated pubkeys. Same instance the rotator owns;
+     * stashed here so the spending paths don't have to reach inside the
+     * rotator. Undefined for static / non-HD-capable wallets — those
+     * paths only ever take the identity-sign branch.
+     */
+    private readonly _descriptorProvider?;
+    private readonly _signerRouter;
+    /**
+     * @internal Sole write path for `offchainTapscript` after construction.
+     * Called by {@link WalletReceiveRotator.rotate} once the rotated
+     * display contract has been persisted. External code must treat
+     * `offchainTapscript` as read-only.
+     */
+    setOffchainTapscriptForRotation(tapscript: DefaultVtxo.Script | DelegateVtxo.Script): void;
     /**
      * Async mutex that serializes all operations submitting VTXOs to the Arkade
      * server (`settle`, `send`, `sendBitcoin`). This prevents VtxoManager's
@@ -233,7 +275,7 @@ export declare class Wallet extends ReadonlyWallet implements IWallet {
     readonly settlementConfig: SettlementConfig | false;
     protected constructor(identity: Identity, network: Network, onchainProvider: OnchainProvider, arkProvider: ArkProvider, indexerProvider: IndexerProvider, arkServerPublicKey: Bytes, offchainTapscript: DefaultVtxo.Script | DelegateVtxo.Script, boardingTapscript: DefaultVtxo.Script, serverUnrollScript: CSVMultisigTapscript.Type, forfeitOutputScript: Bytes, forfeitPubkey: Bytes, dustAmount: bigint, walletRepository: WalletRepository, contractRepository: ContractRepository, 
     /** @deprecated Use settlementConfig */
-    renewalConfig?: WalletConfig["renewalConfig"], delegatorProvider?: DelegatorProvider, watcherConfig?: WalletConfig["watcherConfig"], settlementConfig?: WalletConfig["settlementConfig"], walletContractTimelocks?: RelativeTimelock[]);
+    renewalConfig?: WalletConfig["renewalConfig"], delegatorProvider?: DelegatorProvider, watcherConfig?: WalletConfig["watcherConfig"], settlementConfig?: WalletConfig["settlementConfig"], walletContractTimelocks?: RelativeTimelock[], receiveRotator?: WalletReceiveRotator, descriptorProvider?: DescriptorProvider);
     get assetManager(): IAssetManager;
     getVtxoManager(): Promise<VtxoManager>;
     dispose(): Promise<void>;
@@ -297,6 +339,13 @@ export declare class Wallet extends ReadonlyWallet implements IWallet {
      * @param session - Optional musig2 signing session. When omitted, signing steps are skipped.
      */
     createBatchHandler(intentId: string, inputs: ExtendedCoin[], expectedRecipients: Recipient[], session?: SignerSession): Batch.Handler;
+    /**
+     * Build {@link InputSigningJob}s for a tx whose signable inputs can be
+     * resolved from their own `witnessUtxo.script`. Inputs without a
+     * `witnessUtxo` are silently omitted, mirroring the wallet's
+     * historical silent-skip behaviour for cosigner/connector inputs.
+     */
+    private inputSigningJobsFromWitnessUtxos;
     safeRegisterIntent(intent: SignedIntent<Intent.RegisterMessage>, inputs: ExtendedCoin[]): Promise<string>;
     makeRegisterIntentSignature(coins: ExtendedCoin[], outputs: TransactionOutput[], onchainOutputsIndexes: number[], cosignerPubKeys: string[], validAt?: number): Promise<SignedIntent<Intent.RegisterMessage>>;
     makeDeleteIntentSignature(coins: ExtendedCoin[]): Promise<SignedIntent<Intent.DeleteMessage>>;