@arkade-os/sdk 0.4.26 → 0.4.27

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

@@ -0,0 +1,306 @@
+import { DescriptorProvider } from "../identity/descriptorProvider.js";
+import { ContractRepository } from "../repositories/contractRepository.js";
+import { WalletRepository } from "../repositories/walletRepository.js";
+import { IContractManager } from "../contracts/contractManager.js";
+import { DefaultVtxo } from "../script/default.js";
+import { DelegateVtxo } from "../script/delegate.js";
+import type { WalletConfig } from "./index.js";
+/**
+ * Inputs the wallet hands to a {@link ReceiveRotatorFactory} when
+ * asking it to construct the rotator at boot. The factory uses these
+ * to look up the wallet's current display contract (or allocate a
+ * fresh receive descriptor). Note: no `offchainTapscript` here — the
+ * factory's job is allocation, not script construction. The wallet's
+ * orchestrator (`WalletReceiveRotator.resolveBoot`) handles the
+ * tapscript rebuild on top of the factory's result.
+ */
+export interface ReceiveRotatorBootOpts {
+    walletRepository: WalletRepository;
+    contractRepository: ContractRepository;
+    serverPubKey: Uint8Array;
+    /**
+     * Expected contract family ("default" or "delegate"). When provided,
+     * boot will only consider contracts of this type when looking up the
+     * wallet's current display contract, preventing a default wallet from
+     * accidentally picking up a delegate contract or vice versa.
+     */
+    expectedContractType?: "default" | "delegate";
+    /**
+     * Logger to receive rotation-failure + backoff diagnostics. Defaults
+     * to `console` when omitted. Any object implementing
+     * {@link Logger.error} works (winston, pino, Sentry breadcrumbs,
+     * the runtime's own logger).
+     */
+    logger?: Logger;
+}
+/**
+ * Output of {@link ReceiveRotatorFactory.createReceiveRotator}: the
+ * constructed rotator paired with the receive pubkey it resolved at
+ * boot (either the existing tagged display contract's pubkey, or a
+ * freshly allocated one).
+ */
+export interface ReceiveRotatorBoot {
+    rotator: WalletReceiveRotator;
+    receivePubkey: Uint8Array;
+}
+/**
+ * Result returned by {@link WalletReceiveRotator.resolveBoot} to the
+ * wallet: the rotator plus the offchain tapscript the wallet should
+ * actually use (rebuilt to the resolved boot pubkey when it differs
+ * from the identity's static pubkey), plus the {@link DescriptorProvider}
+ * the rotator was built around. The wallet retains the provider so
+ * spending paths can route per-input signing through
+ * {@link DescriptorProvider.signWithDescriptor} instead of the
+ * identity's index-0 key.
+ */
+export interface ReceiveRotatorBootResult {
+    rotator: WalletReceiveRotator;
+    offchainTapscript: DefaultVtxo.Script | DelegateVtxo.Script;
+    provider: DescriptorProvider;
+}
+/**
+ * Opt-in extension to {@link DescriptorProvider} for providers that
+ * drive HD receive rotation. Implemented by {@link HDDescriptorProvider}
+ * out of the box; custom providers (HSMs, external signers, …) can also
+ * implement it when they want to participate.
+ *
+ * Kept out of the core `DescriptorProvider` interface so providers that
+ * only do allocation + signing don't have to know about the wallet's
+ * receive lifecycle. The wallet detects support via
+ * {@link hasReceiveRotatorFactory} (a duck-typed `instanceof`-style
+ * check) and falls back to {@link WalletReceiveRotator.defaultBoot}
+ * when the provider doesn't implement the extension.
+ */
+export interface ReceiveRotatorFactory {
+    createReceiveRotator(opts: ReceiveRotatorBootOpts): Promise<ReceiveRotatorBoot | undefined>;
+}
+/** Type guard: does this provider implement {@link ReceiveRotatorFactory}? */
+export declare function hasReceiveRotatorFactory(provider: DescriptorProvider): provider is DescriptorProvider & ReceiveRotatorFactory;
+/**
+ * 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 declare 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 declare class NonRangeableDescriptorError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Minimal logging surface the rotator needs. `console` satisfies it
+ * out of the box; SDK consumers can pass a structured logger
+ * (winston / pino / Sentry adapter) via {@link ReceiveRotatorBootOpts}
+ * to capture rotation failures + backoff diagnostics through their
+ * own pipeline.
+ */
+export interface Logger {
+    error(message: string, ...args: unknown[]): void;
+}
+/**
+ * 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 declare const ROTATION_MAX_BACKOFF_MS = 60000;
+/**
+ * Narrow surface the rotator needs from the wallet at runtime: the
+ * mutable display tapscript, the display contract's script hex, the
+ * contract manager (for subscribing + registering rotated contracts),
+ * and the display address (for the contract's `address` field).
+ *
+ * Kept as an interface so the rotator module avoids a circular
+ * dependency on `wallet.ts`. `Wallet` implements this surface
+ * structurally — no `implements` clause is required.
+ */
+export interface RotatableWallet {
+    readonly defaultContractScript: string;
+    readonly network: {
+        hrp: string;
+    };
+    readonly arkServerPublicKey: Uint8Array;
+    readonly offchainTapscript: DefaultVtxo.Script | DelegateVtxo.Script;
+    /**
+     * @internal Sole sanctioned write path for `offchainTapscript`
+     * after construction. The rotator calls this once per rotation
+     * after persisting the new display contract.
+     */
+    setOffchainTapscriptForRotation(tapscript: DefaultVtxo.Script | DelegateVtxo.Script): void;
+    getContractManager(): Promise<IContractManager>;
+    getAddress(): Promise<string>;
+}
+/**
+ * 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 declare class WalletReceiveRotator {
+    private readonly provider;
+    private unsubscribe?;
+    private chain;
+    /**
+     * Script of the most-recent tagged display contract — populated
+     * either from the boot-time repo lookup or from the previous
+     * `rotate()` call within this session. The next `rotate()` marks
+     * this contract `inactive` once the new tagged contract is in
+     * place. `undefined` means the wallet's current display is the
+     * untagged index-0 baseline (no rotation has happened yet on this
+     * repo), and the baseline must NOT be deactivated.
+     */
+    private currentTaggedScript;
+    /**
+     * 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.
+     */
+    private consecutiveFailures;
+    /**
+     * 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.
+     */
+    private nextRotationAllowedAt;
+    private readonly logger;
+    private constructor();
+    /**
+     * 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 resolveBoot(config: WalletConfig, setup: ReceiveRotatorBootOpts & {
+        offchainTapscript: DefaultVtxo.Script | DelegateVtxo.Script;
+    }): Promise<ReceiveRotatorBootResult | undefined>;
+    /**
+     * 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 defaultBoot(provider: DescriptorProvider, opts: ReceiveRotatorBootOpts): Promise<ReceiveRotatorBoot>;
+    /**
+     * 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.
+     */
+    install(wallet: RotatableWallet): Promise<void>;
+    /**
+     * 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.
+     */
+    private runRotateWithBackoff;
+    /**
+     * 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.
+     */
+    drain(): Promise<void>;
+    /**
+     * 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.
+     */
+    dispose(): Promise<void>;
+    /**
+     * 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.
+     */
+    private rotate;
+}
+/**
+ * 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 declare function rebuildTapscript(current: DefaultVtxo.Script | DelegateVtxo.Script, pubKey: Uint8Array): DefaultVtxo.Script | DelegateVtxo.Script;

package/dist/types/worker/messageBus.d.ts

@@ -89,6 +89,7 @@ type Initialize = {
         indexerUrl?: string;
         esploraUrl?: string;
         settlementConfig?: SettlementConfig | false;
+        walletMode?: "auto" | "static" | "hd";
         watcherConfig?: Partial<Omit<ContractWatcherConfig, "indexerProvider">>;
         /**
          * Page-supplied per-operation timeout map. Keys are message types

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkade-os/sdk",
-  "version": "0.4.26",
+  "version": "0.4.27",
   "description": "TypeScript SDK for building Bitcoin wallets using the Arkade protocol",
   "type": "module",
   "main": "./dist/cjs/index.js",