@arkade-os/sdk 0.4.27 → 0.4.29

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

@@ -1,248 +0,0 @@
-import { IWallet, WalletBalance, SendBitcoinParams, SettleParams, ArkTransaction, ExtendedCoin, ExtendedVirtualCoin, GetVtxosFilter, StorageConfig, IReadonlyWallet, IReadonlyAssetManager, IAssetManager, Recipient } from "../index.js";
-import { SettlementEvent } from "../../providers/ark.js";
-import { Identity, ReadonlyIdentity, type SerializedIdentity, type LegacySerializedIdentity } from "../../identity/index.js";
-import { WalletRepository } from "../../repositories/walletRepository.js";
-import { ContractRepository } from "../../repositories/contractRepository.js";
-import { RequestInitWallet, ResponseGetStatus, WalletUpdaterRequest, WalletUpdaterResponse } from "./wallet-message-handler.js";
-import type { IContractManager } from "../../contracts/contractManager.js";
-import type { IDelegatorManager } from "../delegator.js";
-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.
- *
- * This wallet uses a service worker as a backend to handle wallet logic,
- * providing secure key storage and transaction signing in web applications.
- * The service worker runs in a separate thread and can persist data between
- * browser sessions.
- *
- * @example
- * ```typescript
- * // SIMPLE: Recommended approach
- * const wallet = await ServiceWorkerWallet.setup({
- *   serviceWorkerPath: '/service-worker.js',
- *   arkServerUrl: 'https://arkade.computer',
- *   identity: MnemonicIdentity.fromMnemonic('abandon abandon...')
- * });
- *
- * // ADVANCED: Manual setup with service worker control
- * const serviceWorker = await setupServiceWorker("/service-worker.js");
- * const wallet = await ServiceWorkerWallet.create({
- *   serviceWorker,
- *   arkServerUrl: 'https://arkade.computer',
- *   identity: MnemonicIdentity.fromMnemonic('abandon abandon...')
- * });
- *
- * // Use like any other wallet
- * const address = await wallet.getAddress();
- * const balance = await wallet.getBalance();
- * ```
- */
-interface ServiceWorkerWalletOptions {
-    /** Optional Arkade server public key used to construct and validate Arkade addresses. */
-    arkServerPublicKey?: string;
-    /** Base URL of the Arkade server. */
-    arkServerUrl?: string;
-    /** Optional override for the indexer URL. */
-    indexerUrl?: string;
-    /** Optional override for the Esplora API URL. */
-    esploraUrl?: string;
-    /**
-     * Repository-backed storage configuration overrides.
-     * Defaults to IndexedDB if unset.
-     */
-    storage?: StorageConfig;
-    /** Identity used to derive addresses and optionally sign operations. */
-    identity: ReadonlyIdentity | Identity;
-    /** Optional delegation service URL. */
-    delegatorUrl?: string;
-    /**
-     * Override the default tag used for messages sent to and received from the service worker.
-     * @see DEFAULT_MESSAGE_TAG
-     */
-    walletUpdaterTag?: string;
-    /** Timeout used while bootstrapping the message bus inside the service worker. */
-    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">>;
-    /**
-     * Per-request timeout overrides for wallet-updater messages.
-     * @see DEFAULT_MESSAGE_TIMEOUTS
-     */
-    messageTimeouts?: MessageTimeouts;
-}
-/**
- * Options for creating a service-worker wallet with an existing worker instance.
- *
- * @see ServiceWorkerReadonlyWallet.create
- * @see ServiceWorkerWallet.create
- */
-export type ServiceWorkerWalletCreateOptions = ServiceWorkerWalletOptions & {
-    /** Existing service worker instance used for messaging. */
-    serviceWorker: ServiceWorker;
-};
-/**
- * Options for registering a service worker and then creating a wallet around it.
- *
- * @see ServiceWorkerReadonlyWallet.setup
- * @see ServiceWorkerWallet.setup
- */
-export type ServiceWorkerWalletSetupOptions = ServiceWorkerWalletOptions & {
-    /** Path to the service worker script to register. */
-    serviceWorkerPath: string;
-    /** Timeout while waiting for the service worker to activate. */
-    serviceWorkerActivationTimeoutMs?: number;
-};
-type MessageBusInitConfig = {
-    wallet: SerializedIdentity | LegacySerializedIdentity;
-    arkServer: {
-        url: string;
-        publicKey?: string;
-    };
-    delegatorUrl?: string;
-    indexerUrl?: string;
-    esploraUrl?: string;
-    timeoutMs?: number;
-    settlementConfig?: SettlementConfig | false;
-    walletMode?: ServiceWorkerWalletMode;
-    watcherConfig?: Partial<Omit<ContractWatcherConfig, "indexerProvider">>;
-    messageTimeouts?: Record<string, number>;
-};
-export declare class ServiceWorkerReadonlyWallet implements IReadonlyWallet {
-    readonly serviceWorker: ServiceWorker;
-    protected readonly messageTag: string;
-    readonly walletRepository: WalletRepository;
-    readonly contractRepository: ContractRepository;
-    readonly identity: ReadonlyIdentity;
-    private readonly _readonlyAssetManager;
-    protected initConfig: MessageBusInitConfig | null;
-    protected initWalletPayload: RequestInitWallet["payload"] | null;
-    protected messageBusTimeoutMs?: number;
-    protected messageTimeouts: Record<RequestType, number>;
-    protected arkServerUrl?: string;
-    protected arkServerPublicKey?: string;
-    protected delegatorUrl?: string;
-    protected indexerUrl?: string;
-    protected esploraUrl?: string;
-    protected watcherConfig?: Partial<Omit<ContractWatcherConfig, "indexerProvider">>;
-    protected settlementConfig?: SettlementConfig | false;
-    private reinitPromise;
-    private pingPromise;
-    private inflightRequests;
-    get assetManager(): IReadonlyAssetManager;
-    protected constructor(serviceWorker: ServiceWorker, identity: ReadonlyIdentity, walletRepository: WalletRepository, contractRepository: ContractRepository, messageTag: string);
-    private getTimeoutForRequest;
-    /**
-     * Create a readonly service-worker wallet bound to an already-registered worker.
-     *
-     * @param options - Service worker, identity, and backend configuration
-     * @returns Initialized readonly service-worker wallet
-     * @throws Error if service-worker initialization fails
-     */
-    static create(options: ServiceWorkerWalletCreateOptions): Promise<ServiceWorkerReadonlyWallet>;
-    /**
-     * Simplified setup method that handles service worker registration
-     * and wallet initialization automatically.
-     *
-     * @see ServiceWorkerReadonlyWallet.create
-     *
-     * @example
-     * ```typescript
-     * const wallet = await ServiceWorkerReadonlyWallet.setup({
-     *   serviceWorkerPath: '/service-worker.js',
-     *   arkServerUrl: 'https://arkade.computer',
-     *   identity: ReadonlySingleKey.fromPublicKey('your_public_key_hex')
-     * });
-     * ```
-     */
-    static setup(options: ServiceWorkerWalletSetupOptions): Promise<ServiceWorkerReadonlyWallet>;
-    private sendMessageDirect;
-    private sendMessageStreaming;
-    protected sendMessage(request: WalletUpdaterRequest): Promise<WalletUpdaterResponse>;
-    private pingServiceWorker;
-    private sendMessageWithRetry;
-    protected sendMessageWithEvents(request: WalletUpdaterRequest, onEvent: (response: WalletUpdaterResponse) => void, isComplete: (response: WalletUpdaterResponse) => boolean): Promise<WalletUpdaterResponse>;
-    /**
-     * Produce a serialized envelope for the wallet's identity. The base
-     * class always emits a readonly envelope; `ServiceWorkerWallet`
-     * overrides to emit a signing envelope.
-     */
-    protected serializeIdentity(): Promise<SerializedIdentity>;
-    /**
-     * Return the cached init config, or rebuild one from live instance
-     * state when the cache was never populated. Recovery path for
-     * SDK-factory-created wallets; manual constructor bypasses do not
-     * retain enough state here and will hit the "never initialized" throw.
-     */
-    protected buildInitConfig(): Promise<MessageBusInitConfig>;
-    /** Minimal INIT_WALLET payload used on reinitialize when the cache is gone. */
-    protected buildInitWalletPayload(): RequestInitWallet["payload"];
-    private reinitialize;
-    /** Clear cached wallet state from both the page and service worker storage. */
-    clear(): Promise<void>;
-    getAddress(): Promise<string>;
-    getBoardingAddress(): Promise<string>;
-    getBalance(): Promise<WalletBalance>;
-    getBoardingUtxos(): Promise<ExtendedCoin[]>;
-    /**
-     * Return service-worker wallet status, including connectivity and sync state.
-     *
-     * @returns Current service-worker wallet status payload including `walletInitalized` and `xOnlyPublicKey`
-     */
-    getStatus(): Promise<ResponseGetStatus["payload"]>;
-    getTransactionHistory(): Promise<ArkTransaction[]>;
-    getVtxos(filter?: GetVtxosFilter): Promise<ExtendedVirtualCoin[]>;
-    /**
-     * Trigger a wallet reload inside the service worker.
-     *
-     * @returns `true` when the wallet was reloaded
-     */
-    reload(): Promise<boolean>;
-    getContractManager(): Promise<IContractManager>;
-}
-export declare class ServiceWorkerWallet extends ServiceWorkerReadonlyWallet implements IWallet {
-    readonly serviceWorker: ServiceWorker;
-    readonly walletRepository: WalletRepository;
-    readonly contractRepository: ContractRepository;
-    readonly identity: Identity;
-    private readonly _assetManager;
-    private readonly hasDelegator;
-    protected constructor(serviceWorker: ServiceWorker, identity: Identity, walletRepository: WalletRepository, contractRepository: ContractRepository, messageTag: string, hasDelegator: boolean);
-    get assetManager(): IAssetManager;
-    protected serializeIdentity(): Promise<SerializedIdentity>;
-    static create(options: ServiceWorkerWalletCreateOptions): Promise<ServiceWorkerWallet>;
-    /**
-     * Simplified setup method that handles service worker registration
-     * and wallet initialization automatically.
-     *
-     * @example
-     * ```typescript
-     * const wallet = await ServiceWorkerWallet.setup({
-     *   serviceWorkerPath: '/service-worker.js',
-     *   arkServerUrl: 'https://arkade.computer',
-     *   identity: MnemonicIdentity.fromMnemonic('abandon abandon...')
-     * });
-     * ```
-     */
-    static setup(options: ServiceWorkerWalletSetupOptions): Promise<ServiceWorkerWallet>;
-    sendBitcoin(params: SendBitcoinParams): Promise<string>;
-    settle(params?: SettleParams, callback?: (event: SettlementEvent) => void): Promise<string>;
-    send(...recipients: [Recipient, ...Recipient[]]): Promise<string>;
-    getDelegatorManager(): Promise<IDelegatorManager | undefined>;
-    getVtxoManager(): Promise<IVtxoManager>;
-}
-export {};

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

@@ -1,19 +0,0 @@
-/**
- * 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/unroll.d.ts

@@ -1,114 +0,0 @@
-import { ChainTx, IndexerProvider } from "../providers/indexer.js";
-import { AnchorBumper } from "../utils/anchor.js";
-import { OnchainProvider } from "../providers/onchain.js";
-import { Outpoint } from "./index.js";
-import { Wallet } from "./wallet.js";
-import { Transaction } from "../utils/transaction.js";
-export declare namespace Unroll {
-    enum StepType {
-        UNROLL = 0,
-        WAIT = 1,
-        DONE = 2
-    }
-    /**
-     * Unroll step where the transaction has to be broadcasted in a 1C1P package
-     */
-    type UnrollStep = {
-        tx: Transaction;
-        pkg: [parent: string, child: string];
-    };
-    /**
-     * Wait step where the transaction has to be confirmed onchain
-     */
-    type WaitStep = {
-        txid: string;
-    };
-    /**
-     * Done step where the unrolling process is complete
-     */
-    type DoneStep = {
-        vtxoTxid: string;
-    };
-    type Step = ({
-        type: StepType.DONE;
-    } & DoneStep) | ({
-        type: StepType.UNROLL;
-    } & UnrollStep) | ({
-        type: StepType.WAIT;
-    } & WaitStep);
-    /**
-     * Manages the unrolling process of a virtual output back to the Bitcoin blockchain.
-     *
-     * The Session class implements an async iterator that processes the unrolling steps:
-     * 1. **WAIT**: Waits for a transaction to be confirmed onchain (if it's in mempool)
-     * 2. **UNROLL**: Broadcasts the next transaction in the chain to the blockchain
-     * 3. **DONE**: Indicates the unrolling process is complete
-     *
-     * The unrolling process works by traversing the transaction chain from the root (most recent)
-     * to the leaf (oldest), broadcasting each transaction that isn't already onchain.
-     *
-     * @example
-     * ```typescript
-     * const session = await Unroll.Session.create(vtxoOutpoint, bumper, explorer, indexer);
-     *
-     * // iterate over the steps
-     * for await (const doneStep of session) {
-     *   switch (doneStep.type) {
-     *     case Unroll.StepType.WAIT:
-     *       console.log(`Transaction ${doneStep.txid} confirmed`);
-     *       break;
-     *     case Unroll.StepType.UNROLL:
-     *       console.log(`Broadcasting transaction ${doneStep.tx.id}`);
-     *       break;
-     *     case Unroll.StepType.DONE:
-     *       console.log(`Unrolling complete for virtual output ${doneStep.vtxoTxid}`);
-     *       break;
-     *   }
-     * }
-     * ```
-     **/
-    class Session implements AsyncIterable<Step> {
-        readonly toUnroll: Outpoint & {
-            chain: ChainTx[];
-        };
-        readonly bumper: AnchorBumper;
-        readonly explorer: OnchainProvider;
-        readonly indexer: IndexerProvider;
-        /** Create an unroll session from a virtual output outpoint and its dependency chain. */
-        constructor(toUnroll: Outpoint & {
-            chain: ChainTx[];
-        }, bumper: AnchorBumper, explorer: OnchainProvider, indexer: IndexerProvider);
-        /** Create an unroll session by loading the virtual output chain from the indexer. */
-        static create(toUnroll: Outpoint, bumper: AnchorBumper, explorer: OnchainProvider, indexer: IndexerProvider): Promise<Session>;
-        /**
-         * Get the next step to be executed
-         * @returns The next step to be executed + the function to execute it
-         */
-        next(): Promise<Step & {
-            do: () => Promise<void>;
-        }>;
-        /**
-         * Iterate over the steps to be executed and execute them
-         * @returns An async iterator over the executed steps
-         */
-        [Symbol.asyncIterator](): AsyncIterator<Step>;
-    }
-    /**
-     * Complete the unroll of a virtual output by broadcasting the transaction that spends the CSV path.
-     * @param wallet the wallet owning the virtual output(s)
-     * @param vtxoTxids the txids of the virtual output(s) to complete unroll
-     * @param outputAddress the address to send the unrolled funds to
-     * @throws if the virtual output(s) are not fully unrolled, if the txids are not found, if the tx is not confirmed, if no exit path is found or not available
-     * @returns the txid of the transaction spending the unrolled funds
-     */
-    function completeUnroll(wallet: Wallet, vtxoTxids: string[], outputAddress: string): Promise<string>;
-}
-/**
- * Prepares the transaction that spends the CSV path to complete unrolling a VTXO.
- * @param wallet the wallet owning the VTXO(s)
- * @param vtxoTxIds the txids of the VTXO(s) to complete unroll
- * @param outputAddress the address to send the unrolled funds to
- * @throws if the VTXO(s) are not fully unrolled, if the txids are not found, if the tx is not confirmed, if no exit path is found or not available
- * @returns the transaction spending the unrolled funds
- */
-export declare function prepareUnrollTransaction(wallet: Wallet, vtxoTxIds: string[], outputAddress: string): Promise<Transaction>;

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

@@ -1,36 +0,0 @@
-import { Recipient } from "./index.js";
-import { type Coin, type ExtendedCoin, type ExtendedVirtualCoin, type VirtualCoin } from "../index.js";
-import type { Contract } from "../contracts/types.js";
-import { ReadonlyWallet } from "./wallet.js";
-import { Bytes } from "@scure/btc-signer/utils.js";
-export declare const DUST_AMOUNT = 546;
-export declare function extendCoin(wallet: {
-    boardingTapscript: ReadonlyWallet["boardingTapscript"];
-}, utxo: Coin): ExtendedCoin;
-/**
- * Extend a VirtualCoin with the tap scripts of whichever contract locks it.
- *
- * The second argument accepts either form, so each callsite passes what it
- * already has:
- * - a single `Contract` (when the caller already knows the owning contract,
- *   e.g. the contract manager iterating its own `scriptToContract` map), or
- * - a `ReadonlyMap<script, Contract>` (when the caller resolves by
- *   `vtxo.script`, populated by the indexer).
- *
- * Throws when no contract can be resolved — there is intentionally no
- * default-tapscript fallback. When the wallet owns multiple contracts
- * (default + delegate, several active vHTLCs, etc.) a default-tapscript path
- * silently stamps every VTXO with the same forfeit/intent data, overwriting
- * the correct data for any VTXO locked to a non-default contract. Callers
- * must feed a Contract or a populated script→Contract map; otherwise the
- * caller (typically `ContractManager.annotateVtxos`) should fetch the owning
- * contract first.
- */
-export declare function extendVirtualCoinForContract(vtxo: VirtualCoin, contractOrMap?: Contract | ReadonlyMap<string, Contract>): ExtendedVirtualCoin;
-export declare function getRandomId(): string;
-export declare function isValidArkAddress(address: string): boolean;
-type ValidatedRecipient = Required<Recipient> & {
-    script: Bytes;
-};
-export declare function validateRecipients(recipients: Recipient[], dustAmount: number): ValidatedRecipient[];
-export {};

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

@@ -1,24 +0,0 @@
-import { Recipient } from "./index.js";
-import { Transaction } from "../utils/transaction.js";
-import type { Network } from "../networks.js";
-export declare const ErrOffchainOutputNotFound: (address: string) => Error;
-export declare const ErrInvalidAssetOutputAmount: (got: bigint, want: bigint, assetId: string) => Error;
-export declare const ErrAssetGroupNotFound: (assetId: string) => Error;
-export declare const ErrAssetOutputNotFound: (assetId: string, outputIndex: number) => Error;
-export declare const ErrInvalidOnchainOutputAmount: (address: string) => Error;
-export declare const ErrInvalidOnchainOutputAssets: (address: string) => Error;
-export declare const ErrOnchainOutputNotFound: (address: string) => Error;
-export declare const ErrInvalidOffchainOutputAmount: (address: string) => Error;
-/**
- * Validates both offchain and onchain recipients.
- * Offchain recipients are checked against vtxo tree leaves for correct amounts and assets.
- * Onchain recipients are validated against the round transaction outputs (amounts and scripts)
- * via validateOnchainRecipient.
- *
- * @param commitmentTx - The commitment transaction to validate against
- * @param vtxoTreeLeaves - The vtxo tree leaves to validate against
- * @param recipients - The expected recipients to validate (both offchain and onchain)
- * @param network - Network for decoding onchain addresses (e.g. mainnet, testnet)
- * @throws {Error} if a recipient is not present or invalid in the vtxo tree or commitment tx
- */
-export declare function validateBatchRecipients(commitmentTx: Transaction, vtxoTreeLeaves: Transaction[], recipients: Recipient[], network: Network): void;