@arkade-os/sdk 0.4.19 → 0.4.20

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

@@ -0,0 +1,18 @@
+import { Identity } from ".";
+import { DescriptorProvider, DescriptorSigningRequest } from "./descriptorProvider";
+import { Transaction } from "../utils/transaction";
+/**
+ * Wraps a legacy Identity (single-key) as a DescriptorProvider.
+ * The descriptor is always a simple tr(pubkey) format.
+ */
+export declare class StaticDescriptorProvider implements DescriptorProvider {
+    private readonly identity;
+    private readonly descriptor;
+    private readonly pubKeyHex;
+    constructor(identity: Identity, pubKeyHex: string);
+    static create(identity: Identity): Promise<StaticDescriptorProvider>;
+    getSigningDescriptor(): string;
+    isOurs(descriptor: string): boolean;
+    signWithDescriptor(requests: DescriptorSigningRequest[]): Promise<Transaction[]>;
+    signMessageWithDescriptor(descriptor: string, message: Uint8Array, type?: "schnorr" | "ecdsa"): Promise<Uint8Array>;
+}

package/dist/types/index.d.ts

@@ -22,6 +22,8 @@ import type { MessageTimeouts } from "./wallet/serviceWorker/wallet";
 import { OnchainWallet } from "./wallet/onchain";
 import { setupServiceWorker } from "./worker/browser/utils";
 import { ESPLORA_URL, EsploraProvider, OnchainProvider, ExplorerTransaction } from "./providers/onchain";
+import { ElectrumOnchainProvider, WsElectrumChainSource } from "./providers/electrum";
+import type { TransactionHistory as ElectrumTransactionHistory, BlockHeader as ElectrumBlockHeader, Unspent as ElectrumUnspent } from "./providers/electrum";
 import { RestArkProvider, ArkProvider, SettlementEvent, SettlementEventType, ArkInfo, SignedIntent, Output, TxNotification, BatchFinalizationEvent, BatchFinalizedEvent, BatchFailedEvent, TreeSigningStartedEvent, TreeNoncesEvent, BatchStartedEvent, TreeTxEvent, TreeSignatureEvent, ScheduledSession, FeeInfo } from "./providers/ark";
 import { DelegatorProvider, DelegateInfo, DelegateOptions, RestDelegatorProvider } from "./providers/delegator";
 import { CLTVMultisigTapscript, ConditionCSVMultisigTapscript, ConditionMultisigTapscript, CSVMultisigTapscript, decodeTapscript, MultisigTapscript, TapscriptType, ArkTapscript, RelativeTimelock } from "./script/tapscript";
@@ -50,5 +52,5 @@ import { IContractManager } from "./contracts/contractManager";
 import { closeDatabase, openDatabase } from "./repositories/indexedDB/manager";
 import { WalletMessageHandler, WalletNotInitializedError, ReadonlyWalletError, DelegatorNotConfiguredError } from "./wallet/serviceWorker/wallet-message-handler";
 import { MESSAGE_BUS_NOT_INITIALIZED, MessageBusNotInitializedError, ServiceWorkerTimeoutError } from "./worker/errors";
-export { Wallet, ReadonlyWallet, SingleKey, ReadonlySingleKey, SeedIdentity, MnemonicIdentity, ReadonlyDescriptorIdentity, isBatchSignable, OnchainWallet, Ramps, VtxoManager, DelegatorManagerImpl, RestDelegatorProvider, ESPLORA_URL, EsploraProvider, 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, 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, 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, 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, DelegatorManagerImpl, RestDelegatorProvider, ESPLORA_URL, EsploraProvider, 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, 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, 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, };

package/dist/types/providers/electrum.d.ts

@@ -0,0 +1,212 @@
+import type { ElectrumWS } from "ws-electrumx-client";
+import type { Network } from "../networks";
+import type { Coin } from "../wallet";
+import type { ExplorerTransaction, OnchainProvider } from "./onchain";
+export type TransactionHistory = {
+    tx_hash: string;
+    height: number;
+    fee?: number;
+};
+export type BlockHeader = {
+    height: number;
+    hex: string;
+};
+export type Unspent = {
+    txid: string;
+    vout: number;
+    witnessUtxo: {
+        script: Uint8Array;
+        value: bigint;
+    };
+};
+type VerboseTransaction = {
+    txid: string;
+    confirmations: number;
+    blockhash?: string;
+    blocktime?: number;
+    time?: number;
+    /** Raw transaction hex. Bitcoin Core's getrawtransaction <tx> 1 always
+     *  includes this; we use it to derive exact satoshi amounts instead of
+     *  multiplying the floating-point `value` field by 1e8. */
+    hex?: string;
+    vout: {
+        n: number;
+        value: number;
+        scriptPubKey: {
+            addresses?: string[];
+            address?: string;
+            hex: string;
+        };
+    }[];
+    vin: {
+        txid: string;
+        vout: number;
+    }[];
+};
+type HeaderSubscribeResult = {
+    height: number;
+    hex: string;
+};
+/**
+ * WebSocket-based Electrum chain source using ws-electrumx-client.
+ * Provides low-level methods for the Electrum protocol.
+ *
+ * @example
+ * ```typescript
+ * import { ElectrumWS } from "ws-electrumx-client";
+ * import { WsElectrumChainSource } from "./providers/electrum";
+ * import { networks } from "./networks";
+ *
+ * const ws = new ElectrumWS("wss://electrum.blockstream.info:50004");
+ * const chain = new WsElectrumChainSource(ws, networks.bitcoin);
+ *
+ * const history = await chain.fetchHistories([script]);
+ * await chain.close();
+ * ```
+ */
+export declare class WsElectrumChainSource {
+    private ws;
+    private network;
+    private cachedTip;
+    private headersSubscribePromise;
+    constructor(ws: ElectrumWS, network: Network);
+    fetchTransactions(txids: string[]): Promise<{
+        txID: string;
+        hex: string;
+    }[]>;
+    fetchVerboseTransaction(txid: string): Promise<VerboseTransaction>;
+    fetchVerboseTransactions(txids: string[]): Promise<VerboseTransaction[]>;
+    unsubscribeScriptStatus(script: Uint8Array): Promise<void>;
+    subscribeScriptStatus(script: Uint8Array, callback: (scripthash: string, status: string | null) => void): Promise<void>;
+    fetchHistories(scripts: Uint8Array[]): Promise<TransactionHistory[][]>;
+    fetchHistory(script: Uint8Array): Promise<TransactionHistory[]>;
+    fetchBlockHeaders(heights: number[]): Promise<BlockHeader[]>;
+    fetchBlockHeader(height: number): Promise<BlockHeader>;
+    /**
+     * Returns the current chain tip and keeps it fresh via a single
+     * server-side subscription. Subsequent calls return the cached tip
+     * (updated by background notifications) without round-tripping to the
+     * server. Previously each call issued `blockchain.headers.subscribe` as
+     * a regular request, leaving a stale subscription on the server every
+     * time — under polling that adds up. ws-electrumx-client deduplicates
+     * `subscribe()` by method+params, so registering once is enough.
+     */
+    subscribeHeaders(): Promise<HeaderSubscribeResult>;
+    estimateFees(targetNumberBlocks: number): Promise<number>;
+    broadcastTransaction(txHex: string): Promise<string>;
+    /**
+     * Submit a package of raw transactions atomically via Fulcrum's
+     * `blockchain.transaction.broadcast_package` method, the on-the-wire
+     * equivalent of bitcoind's `submitpackage` RPC.
+     *
+     * Required for TRUC (BIP 431) 1P1C relay where the parent has zero
+     * (or below-minfee) fee and depends on the child to pay for both via
+     * CPFP — sequential broadcast cannot work in that case because the
+     * parent would be rejected from the mempool on its own.
+     *
+     * @param txHexes - Topologically sorted raw transactions; child must
+     *                  be the last element. Currently must be a 1P1C pair
+     *                  (length 2). Parents may not depend on each other.
+     * @returns The child transaction id (the last entry in the array),
+     *          computed locally — `broadcast_package` itself returns
+     *          `{success, errors}` rather than a txid.
+     * @throws If the server does not implement `broadcast_package` (e.g.
+     *         ElectrumX, or older Fulcrum, or Fulcrum backed by bitcoind
+     *         < v28.0.0). Callers must surface this clearly to users —
+     *         this method does NOT silently fall back to sequential
+     *         broadcasts because doing so would let TRUC packages fail
+     *         in subtle ways.
+     * @throws If the server returns `success=false`, surfacing the
+     *         underlying mempool rejection in the error message.
+     */
+    broadcastPackage(txHexes: string[]): Promise<string>;
+    getRelayFee(): Promise<number>;
+    close(): Promise<void>;
+    waitForAddressReceivesTx(addr: string): Promise<void>;
+    listUnspents(addr: string): Promise<Unspent[]>;
+    /**
+     * Get the address string for a script output, if decodable.
+     */
+    addressForScript(scriptHex: string): string | undefined;
+}
+/**
+ * Electrum-based implementation of the OnchainProvider interface.
+ * Replaces esplora polling with electrum subscriptions where possible.
+ *
+ * @example
+ * ```typescript
+ * import { ElectrumWS } from "ws-electrumx-client";
+ * import { ElectrumOnchainProvider } from "./providers/electrum";
+ * import { networks } from "./networks";
+ *
+ * const ws = new ElectrumWS("wss://electrum.blockstream.info:50004");
+ * const provider = new ElectrumOnchainProvider(ws, networks.bitcoin);
+ *
+ * const coins = await provider.getCoins("bc1q...");
+ * ```
+ */
+export declare class ElectrumOnchainProvider implements OnchainProvider {
+    private ws;
+    private network;
+    private chain;
+    constructor(ws: ElectrumWS, network: Network);
+    getCoins(address: string): Promise<Coin[]>;
+    getFeeRate(): Promise<number | undefined>;
+    /**
+     * Broadcast a single transaction or a TRUC (BIP 431) 1P1C package
+     * atomically.
+     *
+     * **Server requirements for 1P1C packages:** the backing Electrum
+     * server must implement `blockchain.transaction.broadcast_package`
+     * (Fulcrum ≥ 1.10) and be backed by bitcoind ≥ v28.0.0. ElectrumX
+     * does not implement this method. There is **no fallback** to
+     * sequential parent-then-child broadcast: TRUC packages typically
+     * have a zero-fee parent and would be rejected from the mempool on
+     * their own, so a fallback would silently fail in subtle ways.
+     * Callers receiving a "method not found" error here should route
+     * through a different provider for that submission.
+     *
+     * @param txs - One transaction (single broadcast) or two
+     *              topologically-sorted transactions (parent first,
+     *              child last) for 1P1C package relay.
+     * @returns The broadcast txid (or the child txid for 1P1C packages).
+     */
+    broadcastTransaction(...txs: string[]): Promise<string>;
+    getTxOutspends(txid: string): Promise<{
+        spent: boolean;
+        txid: string;
+    }[]>;
+    getTransactions(address: string): Promise<ExplorerTransaction[]>;
+    /**
+     * Map an electrum verbose transaction to the ExplorerTransaction shape.
+     *
+     * Output values are derived from the raw transaction hex when available,
+     * never from the floating-point `value` field returned by the daemon.
+     * That field has 8 decimal places and `Math.round(value * 1e8)` is safe
+     * in the common case but a footgun for protocol-level money handling —
+     * the raw bytes are exact.
+     */
+    private verboseToExplorer;
+    /**
+     * Decode `address` into its scriptPubKey, throwing a clear error if the
+     * input is malformed. @scure/btc-signer raises a generic decode error
+     * which is hard to map back to user input — this wraps it.
+     */
+    private encodeAddress;
+    getTxStatus(txid: string): Promise<{
+        confirmed: false;
+    } | {
+        confirmed: true;
+        blockTime: number;
+        blockHeight: number;
+    }>;
+    getChainTip(): Promise<{
+        height: number;
+        time: number;
+        hash: string;
+    }>;
+    watchAddresses(addresses: string[], eventCallback: (txs: ExplorerTransaction[]) => void): Promise<() => void>;
+    /** Close the underlying WebSocket connection. */
+    close(): Promise<void>;
+}
+export {};

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

@@ -5,3 +5,4 @@
  * where events arrive before iteration begins.
  */
 export declare function eventSourceIterator(eventSource: EventSource): AsyncGenerator<MessageEvent, void, unknown>;
+export declare function isEventSourceError(error: unknown): error is Error;

package/dist/types/wallet/serviceWorker/wallet-message-handler.d.ts

@@ -18,11 +18,19 @@ export declare const DEFAULT_MESSAGE_TAG = "WALLET_UPDATER";
 export type RequestInitWallet = RequestEnvelope & {
     type: "INIT_WALLET";
     payload: {
-        key: {
+        /**
+         * Legacy per-request key material. Ignored by the current handler —
+         * identity hydration happens during INITIALIZE_MESSAGE_BUS. Retained
+         * for wire compatibility with older workers that may still read it.
+         * Slated for removal in the next major.
+         *
+         * @deprecated Identity is now carried by INITIALIZE_MESSAGE_BUS.
+         */
+        key?: {
             privateKey: string;
         } | {
             publicKey: string;
-        };
+        } | {};
         arkServerUrl: string;
         arkServerPublicKey?: string;
     };
@@ -481,6 +489,7 @@ export declare class WalletMessageHandler implements MessageHandler<WalletUpdate
     private scheduleForNextTick;
     private requireWallet;
     private tagged;
+    isLongRunning(message: WalletUpdaterRequest): boolean;
     handleMessage(message: WalletUpdaterRequest): Promise<WalletUpdaterResponse>;
     private handleInitWallet;
     private handleGetBalance;

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

@@ -1,6 +1,6 @@
 import { IWallet, WalletBalance, SendBitcoinParams, SettleParams, ArkTransaction, ExtendedCoin, ExtendedVirtualCoin, GetVtxosFilter, StorageConfig, IReadonlyWallet, IReadonlyAssetManager, IAssetManager, Recipient } from "..";
 import { SettlementEvent } from "../../providers/ark";
-import { Identity, ReadonlyIdentity } from "../../identity";
+import { Identity, ReadonlyIdentity, type SerializedIdentity, type LegacySerializedIdentity } from "../../identity";
 import { WalletRepository } from "../../repositories/walletRepository";
 import { ContractRepository } from "../../repositories/contractRepository";
 import { RequestInitWallet, ResponseGetStatus, WalletUpdaterRequest, WalletUpdaterResponse } from "./wallet-message-handler";
@@ -11,9 +11,6 @@ import type { ContractWatcherConfig } from "../../contracts/contractWatcher";
 type RequestType = WalletUpdaterRequest["type"];
 export type MessageTimeouts = Partial<Record<RequestType, number>>;
 export declare const DEFAULT_MESSAGE_TIMEOUTS: Readonly<Record<RequestType, number>>;
-type PrivateKeyIdentity = Identity & {
-    toHex(): string;
-};
 /**
  * Service Worker-based wallet implementation for browser environments.
  *
@@ -102,11 +99,7 @@ export type ServiceWorkerWalletSetupOptions = ServiceWorkerWalletOptions & {
     serviceWorkerActivationTimeoutMs?: number;
 };
 type MessageBusInitConfig = {
-    wallet: {
-        privateKey: string;
-    } | {
-        publicKey: string;
-    };
+    wallet: SerializedIdentity | LegacySerializedIdentity;
     arkServer: {
         url: string;
         publicKey?: string;
@@ -117,6 +110,7 @@ type MessageBusInitConfig = {
     timeoutMs?: number;
     settlementConfig?: SettlementConfig | false;
     watcherConfig?: Partial<Omit<ContractWatcherConfig, "indexerProvider">>;
+    messageTimeouts?: Record<string, number>;
 };
 export declare class ServiceWorkerReadonlyWallet implements IReadonlyWallet {
     readonly serviceWorker: ServiceWorker;
@@ -129,6 +123,13 @@ export declare class ServiceWorkerReadonlyWallet implements IReadonlyWallet {
     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;
@@ -165,6 +166,21 @@ export declare class ServiceWorkerReadonlyWallet implements IReadonlyWallet {
     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>;
@@ -195,8 +211,9 @@ export declare class ServiceWorkerWallet extends ServiceWorkerReadonlyWallet imp
     readonly identity: Identity;
     private readonly _assetManager;
     private readonly hasDelegator;
-    protected constructor(serviceWorker: ServiceWorker, identity: PrivateKeyIdentity, walletRepository: WalletRepository, contractRepository: ContractRepository, messageTag: string, hasDelegator: boolean);
+    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

package/dist/types/wallet/vtxo-manager.d.ts

@@ -400,6 +400,8 @@ export declare class VtxoManager implements AsyncDisposable, IVtxoManager {
     private getBoardingOutputScript;
     /** Returns the onchain provider for fee estimation and broadcasting. */
     private getOnchainProvider;
+    /** Returns the Ark provider for intent fee and server info lookups. */
+    private getArkProvider;
     /** Returns the Bitcoin network configuration from the wallet. */
     private getNetwork;
     /** Returns the wallet's identity for transaction signing. */

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

@@ -1,4 +1,5 @@
 import { ArkProvider } from "../providers/ark";
+import { type SerializedIdentity, type LegacySerializedIdentity } from "../identity";
 import { ReadonlyWallet, Wallet } from "../wallet/wallet";
 import type { SettlementConfig } from "../wallet/vtxo-manager";
 import type { ContractWatcherConfig } from "../contracts/contractWatcher";
@@ -45,11 +46,29 @@ export interface MessageHandler<REQ extends RequestEnvelope = RequestEnvelope, R
      * Handle routed messages from the clients
      **/
     handleMessage(message: REQ): Promise<RES | null>;
+    /**
+     * Optional opt-out from the bus-level message timeout.
+     *
+     * Long-running flows (e.g. settlement) surrender control to remote peers
+     * and can legitimately sit idle for longer than `messageTimeoutMs`. When
+     * this returns true, the bus awaits `handleMessage` without a deadline.
+     * Defaults to false.
+     */
+    isLongRunning?(message: REQ): boolean;
 }
 type Options = {
     messageHandlers: MessageHandler[];
     tickIntervalMs?: number;
     messageTimeoutMs?: number;
+    /**
+     * Per-operation timeout overrides. Keys are either message types
+     * (e.g. "SETTLE") or handler tags (e.g. "WALLET_UPDATER"). Message-type
+     * matches take precedence over tag matches. Unspecified operations use
+     * `messageTimeoutMs`. These are treated as defaults: any map supplied
+     * via `INITIALIZE_MESSAGE_BUS` overrides per-key and is re-applied on
+     * every (re-)init.
+     */
+    messageTimeoutOverrides?: Record<string, number>;
     debug?: boolean;
     buildServices?: (config: Initialize["config"]) => Promise<{
         arkProvider: ArkProvider;
@@ -61,11 +80,7 @@ type Initialize = {
     type: "INITIALIZE_MESSAGE_BUS";
     id: string;
     config: {
-        wallet: {
-            privateKey: string;
-        } | {
-            publicKey: string;
-        };
+        wallet: SerializedIdentity | LegacySerializedIdentity;
         arkServer: {
             url: string;
             publicKey?: string;
@@ -75,6 +90,12 @@ type Initialize = {
         esploraUrl?: string;
         settlementConfig?: SettlementConfig | false;
         watcherConfig?: Partial<Omit<ContractWatcherConfig, "indexerProvider">>;
+        /**
+         * Page-supplied per-operation timeout map. Keys are message types
+         * (e.g. "SETTLE"). Overrides constructor-supplied
+         * `messageTimeoutOverrides` per-key; re-applied on every init.
+         */
+        messageTimeouts?: Record<string, number>;
     };
 };
 export declare class MessageBus {
@@ -83,6 +104,9 @@ export declare class MessageBus {
     private handlers;
     private tickIntervalMs;
     private messageTimeoutMs;
+    private readonly constructorTimeoutOverrides;
+    private messageTimeoutOverrides;
+    private lateDeliveries;
     private running;
     private tickTimeout;
     private tickInProgress;
@@ -91,7 +115,7 @@ export declare class MessageBus {
     private readonly buildServicesFn;
     private readonly boundOnMessage;
     /** Create the service-worker message bus with repositories and handler configuration. */
-    constructor(walletRepository: WalletRepository, contractRepository: ContractRepository, { messageHandlers, tickIntervalMs, messageTimeoutMs, debug, buildServices, }: Options);
+    constructor(walletRepository: WalletRepository, contractRepository: ContractRepository, { messageHandlers, tickIntervalMs, messageTimeoutMs, messageTimeoutOverrides, debug, buildServices, }: Options);
     /** Start the message bus and attach service-worker event listeners. */
     start(): Promise<void>;
     /** Stop the message bus, cancel ticks, and stop all registered handlers. */
@@ -104,10 +128,46 @@ export declare class MessageBus {
     private processMessage;
     /**
      * Race `promise` against a timeout. Note: this does NOT cancel the
-     * underlying work — the original promise keeps running. This is safe
-     * here because only the caller (not the handler) posts the response.
+     * underlying work — the original promise keeps running. Call
+     * `attachLateDelivery` after catching the timeout to surface the
+     * eventual result so the message id does not go silent.
      */
     private withTimeout;
+    /**
+     * Extract the declared `type` from a request envelope (e.g. "SETTLE").
+     * Not every envelope carries a type (PING/INIT are special cased
+     * earlier), so this returns undefined for envelopes that lack one.
+     */
+    private extractMessageType;
+    /**
+     * Resolve the timeout for an operation. Message-type overrides take
+     * precedence over handler-tag overrides, with the bus-wide default
+     * (`messageTimeoutMs`) as the final fallback.
+     */
+    private resolveTimeoutMs;
+    /**
+     * Build a human-readable label for timeout errors. Format:
+     * `"<MESSAGE_TYPE> via <HANDLER_TAG>"` when both are known, else the
+     * handler tag alone. Used so timeout errors name the operation the
+     * client actually triggered (e.g. SETTLE) rather than just the
+     * handler that received it (e.g. WALLET_UPDATER).
+     */
+    private labelFor;
+    /**
+     * Post a response to the originating client. When `source` is null
+     * (client tab closed, detached frame, etc.) the response cannot be
+     * delivered; we log the drop in debug mode so it is not invisible.
+     */
+    private deliverResponse;
+    /**
+     * After a handler times out the client has already received a timeout
+     * error, but the handler keeps running. Attach a follow-up so the
+     * handler's eventual result (or error) is delivered under the same
+     * message id, or — if the handler never completes within
+     * {@link LATE_DELIVERY_GRACE_MS} — an "Operation abandoned" error is
+     * sent so the client's listener (if still attached) does not hang.
+     */
+    private attachLateDelivery;
     /**
      * Returns the registered SW for the path.
      * It uses the functions in `service-worker-manager.ts` module.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkade-os/sdk",
-  "version": "0.4.19",
+  "version": "0.4.20",
   "description": "TypeScript SDK for building Bitcoin wallets using the Arkade protocol",
   "type": "module",
   "main": "./dist/cjs/index.js",
@@ -87,7 +87,8 @@
     "@scure/base": "2.0.0",
     "@scure/bip39": "2.0.1",
     "@scure/btc-signer": "2.0.1",
-    "bip68": "1.0.4"
+    "bip68": "1.0.4",
+    "ws-electrumx-client": "1.0.5"
   },
   "devDependencies": {
     "@types/better-sqlite3": "7.6.13",