@arkade-os/sdk 0.4.19 → 0.4.21

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

@@ -0,0 +1,84 @@
+import type { Identity, ReadonlyIdentity } from ".";
+/**
+ * Tagged envelope for a signing identity transported across the
+ * service-worker boundary. All variants are structured-clone safe
+ * (plain strings only — no functions or prototypes).
+ *
+ * Adding a new variant is a source change in every worker build; keep
+ * old variants around until all deployed workers handle them.
+ */
+export type SerializedSigningIdentity = {
+    type: "single-key";
+    privateKey: string;
+} | {
+    type: "seed";
+    seed: string;
+    descriptor: string;
+} | {
+    type: "mnemonic";
+    mnemonic: string;
+    descriptor: string;
+    passphrase?: string;
+};
+/**
+ * Tagged envelope for a readonly identity transported across the
+ * service-worker boundary. All variants are structured-clone safe.
+ */
+export type SerializedReadonlyIdentity = {
+    type: "readonly-single-key";
+    publicKey: string;
+} | {
+    type: "readonly-descriptor";
+    descriptor: string;
+};
+export type SerializedIdentity = SerializedSigningIdentity | SerializedReadonlyIdentity;
+/** Type guard — true for signing envelopes, false for readonly envelopes. */
+export declare function isSigningSerialized(s: SerializedIdentity): s is SerializedSigningIdentity;
+/**
+ * Serialize a signing identity into a structured-clone safe envelope for
+ * transport across the service-worker boundary.
+ *
+ * Supports SDK-owned signing identities directly. For custom identities, a
+ * duck-typed `toHex()` fallback preserves compatibility with existing
+ * `SingleKey`-like implementations.
+ */
+export declare function serializeSigningIdentity(identity: Identity): SerializedSigningIdentity;
+/**
+ * Serialize a readonly identity into a structured-clone safe envelope.
+ *
+ * Works for any `ReadonlyIdentity` via `compressedPublicKey()`. When called
+ * with a signing identity, produces a readonly envelope (never ships signing
+ * material) — callers that need to preserve signing capability across the
+ * boundary must use {@link serializeSigningIdentity}.
+ */
+export declare function serializeReadonlyIdentity(identity: ReadonlyIdentity): Promise<SerializedReadonlyIdentity>;
+/**
+ * Rehydrate a serialized identity envelope back into an identity instance.
+ * The return type is the union of signing and readonly; use
+ * {@link isSigningSerialized} on the envelope before hydration if the caller
+ * needs to know which side it ends up on.
+ */
+export declare function hydrateIdentity(s: SerializedIdentity): Identity | ReadonlyIdentity;
+/**
+ * Legacy untagged shape emitted by page builds prior to the tagged
+ * SerializedIdentity envelope. Retained so newer workers can still accept
+ * older pages during a rolling upgrade. Slated for removal in the next major.
+ *
+ * @deprecated Use {@link SerializedIdentity}.
+ */
+export type LegacySerializedIdentity = {
+    privateKey: string;
+} | {
+    publicKey: string;
+};
+/**
+ * Accept either a modern {@link SerializedIdentity} envelope or a legacy
+ * `{ privateKey }` / `{ publicKey }` shape and normalize to a
+ * {@link SerializedIdentity}. Emits a one-time deprecation warning when a
+ * legacy shape is seen.
+ *
+ * Intended for the worker-side boundary; new page builds always emit tagged
+ * envelopes via {@link serializeSigningIdentity} /
+ * {@link serializeReadonlyIdentity}.
+ */
+export declare function normalizeSerializedIdentity(shape: SerializedIdentity | LegacySerializedIdentity): SerializedIdentity;

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

@@ -1,7 +1,12 @@
+export type ManagedEventSourceIterator = AsyncGenerator<MessageEvent, void, unknown> & {
+    close(): void;
+};
 /**
- * Creates an async iterator over EventSource messages that attaches listeners
- * eagerly (at call time) rather than lazily (at first .next() call).
- * This ensures events are buffered immediately, preventing race conditions
- * where events arrive before iteration begins.
+ * Creates a close-aware EventSource async iterator.
+ *
+ * Listeners attach eagerly so events are buffered before the first next() call.
+ * close() closes the EventSource, removes listeners, and wakes any pending
+ * next() even when the browser does not emit an error from EventSource.close().
  */
-export declare function eventSourceIterator(eventSource: EventSource): AsyncGenerator<MessageEvent, void, unknown>;
+export declare function eventSourceIterator(eventSource: EventSource): ManagedEventSourceIterator;
+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/wallet/wallet.d.ts

@@ -8,7 +8,7 @@ import { ArkProvider, SettlementEvent, SignedIntent } from "../providers/ark";
 import { SignerSession } from "../tree/signingSession";
 import { Identity, ReadonlyIdentity } from "../identity";
 import { ArkTransaction, Coin, ExtendedCoin, ExtendedVirtualCoin, GetVtxosFilter, IAssetManager, IReadonlyAssetManager, IReadonlyWallet, IWallet, ReadonlyWalletConfig, Recipient, SendBitcoinParams, SettleParams, WalletBalance, WalletConfig } from ".";
-import { CSVMultisigTapscript } from "../script/tapscript";
+import { CSVMultisigTapscript, RelativeTimelock } from "../script/tapscript";
 import { SettlementConfig, VtxoManager } from "./vtxo-manager";
 import { Intent } from "../intent";
 import { IndexerProvider } from "../providers/indexer";
@@ -44,9 +44,10 @@ export declare class ReadonlyWallet implements IReadonlyWallet {
     protected readonly watcherConfig?: ReadonlyWalletConfig["watcherConfig"];
     private readonly _assetManager;
     private _syncVtxosInflight?;
+    readonly walletContractTimelocks: RelativeTimelock[];
     protected _pendingSpendOutpoints: Set<string>;
     get assetManager(): IReadonlyAssetManager;
-    protected constructor(identity: ReadonlyIdentity, network: Network, onchainProvider: OnchainProvider, indexerProvider: IndexerProvider, arkServerPublicKey: Bytes, offchainTapscript: DefaultVtxo.Script | DelegateVtxo.Script, boardingTapscript: DefaultVtxo.Script, dustAmount: bigint, walletRepository: WalletRepository, contractRepository: ContractRepository, delegatorProvider?: DelegatorProvider | undefined, watcherConfig?: ReadonlyWalletConfig["watcherConfig"]);
+    protected constructor(identity: ReadonlyIdentity, network: Network, onchainProvider: OnchainProvider, indexerProvider: IndexerProvider, arkServerPublicKey: Bytes, offchainTapscript: DefaultVtxo.Script | DelegateVtxo.Script, boardingTapscript: DefaultVtxo.Script, dustAmount: bigint, walletRepository: WalletRepository, contractRepository: ContractRepository, delegatorProvider?: DelegatorProvider | undefined, watcherConfig?: ReadonlyWalletConfig["watcherConfig"], walletContractTimelocks?: RelativeTimelock[]);
     /**
      * Protected helper to set up shared wallet configuration.
      * Extracts common logic used by both ReadonlyWallet.create() and Wallet.create().
@@ -65,6 +66,7 @@ export declare class ReadonlyWallet implements IReadonlyWallet {
         contractRepository: ContractRepository;
         info: import("../providers/ark").ArkInfo;
         delegatorProvider: DelegatorProvider | undefined;
+        walletContractTimelocks: RelativeTimelock[];
     }>;
     /**
      * Create a readonly wallet for querying balances, addresses, and history.
@@ -75,8 +77,8 @@ export declare class ReadonlyWallet implements IReadonlyWallet {
     static create(config: ReadonlyWalletConfig): Promise<ReadonlyWallet>;
     get arkAddress(): ArkAddress;
     /**
-     * Get the contract script for the wallet's default address.
-     * This is the pkScript hex, used to identify the wallet in ContractManager.
+     * Get the pkScript hex for the wallet's primary offchain address.
+     * For the full wallet-owned script set registered in ContractManager, use getWalletScripts().
      */
     get defaultContractScript(): string;
     /** Returns the wallet's Arkade address. */
@@ -125,7 +127,6 @@ export declare class ReadonlyWallet implements IReadonlyWallet {
     /**
      * Get all pkScript hex strings for the wallet's own addresses
      * (both delegate and non-delegate, current and historical).
-     * Falls back to only the current script if ContractManager is not yet initialized.
      */
     getWalletScripts(): Promise<string[]>;
     /**
@@ -229,7 +230,7 @@ export declare class Wallet extends ReadonlyWallet implements IWallet {
     readonly settlementConfig: SettlementConfig | false;
     protected constructor(identity: Identity, network: Network, onchainProvider: OnchainProvider, arkProvider: ArkProvider, indexerProvider: IndexerProvider, arkServerPublicKey: Bytes, offchainTapscript: DefaultVtxo.Script | DelegateVtxo.Script, boardingTapscript: DefaultVtxo.Script, serverUnrollScript: CSVMultisigTapscript.Type, forfeitOutputScript: Bytes, forfeitPubkey: Bytes, dustAmount: bigint, walletRepository: WalletRepository, contractRepository: ContractRepository, 
     /** @deprecated Use settlementConfig */
-    renewalConfig?: WalletConfig["renewalConfig"], delegatorProvider?: DelegatorProvider, watcherConfig?: WalletConfig["watcherConfig"], settlementConfig?: WalletConfig["settlementConfig"]);
+    renewalConfig?: WalletConfig["renewalConfig"], delegatorProvider?: DelegatorProvider, watcherConfig?: WalletConfig["watcherConfig"], settlementConfig?: WalletConfig["settlementConfig"], walletContractTimelocks?: RelativeTimelock[]);
     get assetManager(): IAssetManager;
     getVtxoManager(): Promise<VtxoManager>;
     dispose(): Promise<void>;