@arkade-os/sdk 0.4.27 → 0.4.28

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

@@ -1,306 +0,0 @@
-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/browser/service-worker-manager.d.ts

@@ -1,32 +0,0 @@
-type SetupServiceWorkerOptions = {
-    path: string;
-    updateViaCache?: ServiceWorkerUpdateViaCache;
-    autoReload?: boolean;
-    onNeedRefresh?: () => void;
-    onUpdated?: () => void;
-    debug?: boolean;
-    activationTimeoutMs?: number;
-};
-/**
- * Registers a service worker for the given path only once, attaches an
- * update/activation handshake (SKIP_WAITING + controllerchange reload), and
- * caches the registration promise for subsequent calls.
- *
- * @param pathOrOptions - Service worker script path or a configuration object.
- * @throws if service workers are not supported or registration fails.
- */
-export declare function setupServiceWorkerOnce(pathOrOptions: string | SetupServiceWorkerOptions): Promise<ServiceWorkerRegistration>;
-/**
- * Returns an active service worker instance, optionally ensuring a specific
- * script path is registered before resolving.
- *
- * @param path - Optional service worker script path to register and prefer.
- * @throws if service workers are not supported or no active worker is available.
- */
-export declare function getActiveServiceWorker(path?: string): Promise<ServiceWorker>;
-/**
- * Clears the cached registration promises.
- * Intended for tests to reset state between runs.
- */
-export declare const __resetServiceWorkerManager: () => void;
-export {};

package/dist/types/worker/browser/utils.d.ts

@@ -1,17 +0,0 @@
-export declare const DEFAULT_DB_NAME = "arkade-service-worker";
-export declare const DEFAULT_SERVICE_WORKER_ACTIVATION_TIMEOUT_MS = 10000;
-type SetupServiceWorkerOptions = {
-    path: string;
-    activationTimeoutMs?: number;
-};
-/**
- * setupServiceWorker sets up the service worker.
- * @param pathOrOptions - the path to the service worker script or setup options
- * @throws if service workers are not supported or activation fails
- * @example
- * ```typescript
- * const worker = await setupServiceWorker("/service-worker.js");
- * ```
- */
-export declare function setupServiceWorker(pathOrOptions: string | SetupServiceWorkerOptions): Promise<ServiceWorker>;
-export {};

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

@@ -1,7 +0,0 @@
-export declare const MESSAGE_BUS_NOT_INITIALIZED = "MessageBus not initialized";
-export declare class MessageBusNotInitializedError extends Error {
-    constructor();
-}
-export declare class ServiceWorkerTimeoutError extends Error {
-    constructor(detail: string);
-}

package/dist/types/worker/expo/index.d.ts

@@ -1,7 +0,0 @@
-export type { TaskItem, TaskResult, TaskQueue } from "./taskQueue.js";
-export { InMemoryTaskQueue } from "./taskQueue.js";
-export type { AsyncStorageLike } from "./asyncStorageTaskQueue.js";
-export { AsyncStorageTaskQueue } from "./asyncStorageTaskQueue.js";
-export type { TaskProcessor, TaskDependencies, CreateTaskDependenciesOptions, } from "./taskRunner.js";
-export { runTasks, createTaskDependencies } from "./taskRunner.js";
-export { contractPollProcessor, CONTRACT_POLL_TASK_TYPE } from "./processors/index.js";

package/dist/types/worker/expo/processors/contractPollProcessor.d.ts

@@ -1,19 +0,0 @@
-import type { TaskProcessor } from "../taskRunner.js";
-export declare const CONTRACT_POLL_TASK_TYPE = "contract-poll";
-/**
- * Polls the indexer for the latest VTXO state of every contract and
- * persists the results to the wallet repository.
- *
- * Replicates the polling subset of @see ContractManager.initialize:
- * 1. Load all contracts from the contract repository.
- * 2. Paginated fetch of every VTXO (including spent) from the indexer.
- * 3. Extend each VTXO with tapscript data.
- * 4. Save to the wallet repository.
- *
- * NOTE: the indexer query deliberately omits `spendableOnly`. Every
- * repository implements `saveVtxos` as an upsert with no batch delete,
- * so filtering to spendable-only would leave VTXOs that became spent
- * between polls marked as spendable forever. Fetching the full set lets
- * the upsert overwrite stale records with their latest state.
- */
-export declare const contractPollProcessor: TaskProcessor;

package/dist/types/worker/expo/processors/index.d.ts

@@ -1 +0,0 @@
-export { contractPollProcessor, CONTRACT_POLL_TASK_TYPE, } from "./contractPollProcessor.js";

package/dist/types/worker/expo/taskQueue.d.ts

@@ -1,50 +0,0 @@
-/**
- * A task item represents a unit of work in the inbox.
- */
-export interface TaskItem {
-    id: string;
-    type: string;
-    data: Record<string, unknown>;
-    createdAt: number;
-}
-/**
- * A task result represents the outcome of processing a task item.
- */
-export interface TaskResult {
-    id: string;
-    taskItemId: string;
-    type: string;
-    status: "success" | "failed" | "noop";
-    data?: Record<string, unknown>;
-    executedAt: number;
-}
-/**
- * Persistence layer for handing off work between foreground and background.
- *
- * - **Inbox**: tasks waiting to be processed.
- * - **Outbox**: results produced by processors, waiting to be consumed.
- */
-export interface TaskQueue {
-    addTask(task: TaskItem): Promise<void>;
-    removeTask(id: string): Promise<void>;
-    getTasks(type?: string): Promise<TaskItem[]>;
-    clearTasks(): Promise<void>;
-    pushResult(result: TaskResult): Promise<void>;
-    getResults(): Promise<TaskResult[]>;
-    acknowledgeResults(ids: string[]): Promise<void>;
-}
-/**
- * In-memory TaskQueue for testing and lightweight use.
- * State is lost when the process exits.
- */
-export declare class InMemoryTaskQueue implements TaskQueue {
-    private inbox;
-    private outbox;
-    addTask(task: TaskItem): Promise<void>;
-    removeTask(id: string): Promise<void>;
-    getTasks(type?: string): Promise<TaskItem[]>;
-    clearTasks(): Promise<void>;
-    pushResult(result: TaskResult): Promise<void>;
-    getResults(): Promise<TaskResult[]>;
-    acknowledgeResults(ids: string[]): Promise<void>;
-}

package/dist/types/worker/expo/taskRunner.d.ts

@@ -1,66 +0,0 @@
-import type { TaskItem, TaskResult, TaskQueue } from "./taskQueue.js";
-import type { WalletRepository } from "../../repositories/walletRepository.js";
-import type { ContractRepository } from "../../repositories/contractRepository.js";
-import type { IndexerProvider } from "../../providers/indexer.js";
-import type { ArkProvider } from "../../providers/ark.js";
-import type { ExtendedVirtualCoin, VirtualCoin } from "../../wallet/index.js";
-import type { Contract } from "../../contracts/types.js";
-/**
- * Shared dependencies injected into every processor at runtime.
- *
- * `extendVtxo` requires the owning contract — processors must resolve each
- * vtxo's `script` to a known contract (via the contract repository) before
- * calling this. The strict signature prevents the footgun where a missing
- * contract silently falls back to the wallet's default tapscript.
- */
-export interface TaskDependencies {
-    walletRepository: WalletRepository;
-    contractRepository: ContractRepository;
-    indexerProvider: IndexerProvider;
-    arkProvider: ArkProvider;
-    extendVtxo: (vtxo: VirtualCoin, contract: Contract) => ExtendedVirtualCoin;
-}
-/**
- * A stateless unit that handles one type of task item.
- *
- * Processors must not keep in-memory state across invocations —
- * all coordination lives in the @see TaskQueue and repositories.
- *
- * The `TDeps` parameter defaults to @see TaskDependencies but
- * can be overridden for domain-specific processors (e.g. swap processing).
- */
-export interface TaskProcessor<TDeps = TaskDependencies> {
-    readonly taskType: string;
-    execute(item: TaskItem, deps: TDeps): Promise<Omit<TaskResult, "id" | "executedAt">>;
-}
-/**
- * Run all pending tasks from the queue through matching processors.
- *
- * For each task in the inbox:
- * 1. Find the processor whose `taskType` matches `task.type`.
- * 2. Execute it, producing a @see TaskResult.
- * 3. Push the result to the outbox and remove the task from the inbox.
- *
- * Tasks with no matching processor produce a `"noop"` result.
- * Processor errors produce a `"failed"` result with the error message.
- */
-export declare function runTasks<TDeps = TaskDependencies>(queue: TaskQueue, processors: TaskProcessor<TDeps>[], deps: TDeps): Promise<TaskResult[]>;
-/**
- * Options for @see createTaskDependencies.
- */
-export interface CreateTaskDependenciesOptions {
-    walletRepository: WalletRepository;
-    contractRepository: ContractRepository;
-    indexerProvider: IndexerProvider;
-    arkProvider: ArkProvider;
-}
-/**
- * Build the @see TaskDependencies needed by task processors
- * (e.g. `src/worker/expo/processors/contractPollProcessor.ts`)
- *
- * This is the same construction that `defineExpoBackgroundTask` does
- * internally, extracted so that consumers with custom schedulers
- * (e.g. bare React Native with `react-native-background-fetch`)
- * can build deps without depending on Expo.
- */
-export declare function createTaskDependencies(options: CreateTaskDependenciesOptions): TaskDependencies;