@arkade-os/sdk 0.4.18 → 0.4.20

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

@@ -0,0 +1,28 @@
+import { Transaction } from "../utils/transaction";
+/** A signing request that pairs a descriptor with a transaction. */
+export interface DescriptorSigningRequest {
+    /** Descriptor identifying which key to sign with */
+    descriptor: string;
+    /** Transaction to sign */
+    tx: Transaction;
+    /** Specific input indexes to sign (signs all if omitted) */
+    inputIndexes?: number[];
+}
+/**
+ * Provider interface for descriptor-based signing.
+ *
+ * Implementations include:
+ * - {@link StaticDescriptorProvider}: wraps a legacy {@link Identity} with a single key.
+ * - HD-wallet provider: signs with keys derived from an xpub-based descriptor
+ *   (planned — tracked separately from this interface).
+ */
+export interface DescriptorProvider {
+    /** Returns the current signing descriptor. */
+    getSigningDescriptor(): string;
+    /** Checks if a descriptor belongs to this provider. */
+    isOurs(descriptor: string): boolean;
+    /** Signs transactions, each with its own descriptor-derived key. */
+    signWithDescriptor(requests: DescriptorSigningRequest[]): Promise<Transaction[]>;
+    /** Signs a message using the key derived from the descriptor. */
+    signMessageWithDescriptor(descriptor: string, message: Uint8Array, type?: "schnorr" | "ecdsa"): Promise<Uint8Array>;
+}

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

@@ -46,4 +46,10 @@ export interface BatchSignableIdentity extends Identity {
 /** Type guard for identities that support batch signing. */
 export declare function isBatchSignable(identity: Identity): identity is BatchSignableIdentity;
 export * from "./singleKey";
-export * from "./seedIdentity";
+export type { NetworkOptions, DescriptorOptions, SeedIdentityOptions, MnemonicOptions, } from "./seedIdentity";
+export { SeedIdentity, MnemonicIdentity, ReadonlyDescriptorIdentity, } from "./seedIdentity";
+export * from "./serialize";
+export { isDescriptor, normalizeToDescriptor, extractPubKey, parseHDDescriptor, } from "./descriptor";
+export type { ParsedHDDescriptor } from "./descriptor";
+export type { DescriptorProvider, DescriptorSigningRequest, } from "./descriptorProvider";
+export { StaticDescriptorProvider } from "./staticDescriptorProvider";

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

@@ -1,6 +1,7 @@
 import { Identity, ReadonlyIdentity } from ".";
 import { Transaction } from "../utils/transaction";
 import { SignerSession } from "../tree/signingSession";
+import type { SerializedSigningIdentity, SerializedReadonlyIdentity } from "./serialize";
 /** Used for default BIP86 derivation with network selection. */
 export interface NetworkOptions {
     /**
@@ -27,14 +28,14 @@ export type MnemonicOptions = SeedIdentityOptions & {
  *
  * This is the recommended identity type for most applications. It uses
  * standard BIP86 (Taproot) derivation by default and stores an output
- * descriptor for interoperability with other wallets. The descriptor
- * format is HD-ready, allowing future support for multiple addresses
- * and change derivation.
+ * descriptor for interoperability with other wallets.
  *
  * Prefer this (or @see MnemonicIdentity) over `SingleKey` for new
  * integrations — `SingleKey` exists for backward compatibility with
  * raw nsec-style keys.
  *
+ * For descriptor-based signing, wrap with {@link StaticDescriptorProvider}.
+ *
  * @example
  * ```typescript
  * const seed = mnemonicToSeedSync(mnemonic);
@@ -50,7 +51,6 @@ export type MnemonicOptions = SeedIdentityOptions & {
  * ```
  */
 export declare class SeedIdentity implements Identity {
-    protected readonly seed: Uint8Array;
     private readonly derivedKey;
     readonly descriptor: string;
     constructor(seed: Uint8Array, descriptor: string);
@@ -131,3 +131,40 @@ export declare class ReadonlyDescriptorIdentity implements ReadonlyIdentity {
     xOnlyPublicKey(): Promise<Uint8Array>;
     compressedPublicKey(): Promise<Uint8Array>;
 }
+/**
+ * Serialize a seed-backed signing identity into a
+ * {@link SerializedSigningIdentity} envelope without exposing the
+ * underlying secret material on the public instance surface.
+ *
+ * Called by {@link serializeSigningIdentity}; application code should
+ * prefer that public dispatcher instead of calling this directly. This
+ * helper is deliberately kept out of the `src/identity` barrel so it is
+ * not part of the package's public export surface.
+ *
+ * Secret-surface trade-off: the resulting envelope carries master-seed
+ * material — the BIP39 mnemonic (+ optional passphrase) for
+ * `MnemonicIdentity` or the raw 64-byte seed for `SeedIdentity`. A party
+ * that reads this envelope can derive any key under the HD tree, not
+ * just the key currently in use. The pre-change `SingleKey` flow only
+ * shipped one derived private key and therefore had a smaller blast
+ * radius. This is an intentional design trade to preserve class and
+ * descriptor identity across the page / service-worker boundary; the
+ * page already holds the same material so that it can re-initialize a
+ * killed worker. Transport is same-origin `postMessage` only. See the
+ * threat-model note in `src/worker/browser/README.md`.
+ *
+ * @internal
+ */
+export declare function serializeSeedOwnedSigningIdentity(identity: SeedIdentity): SerializedSigningIdentity;
+/**
+ * Downgrade a seed-backed or descriptor-backed identity into a readonly
+ * descriptor envelope. Always produces a descriptor-only shape — secret
+ * material never crosses this path, even if the input is a signing
+ * identity.
+ *
+ * Deliberately kept out of the `src/identity` barrel; consumers should go
+ * through {@link serializeReadonlyIdentity}.
+ *
+ * @internal
+ */
+export declare function serializeSeedOwnedReadonlyIdentity(identity: SeedIdentity | ReadonlyDescriptorIdentity): SerializedReadonlyIdentity;

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

@@ -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

@@ -224,6 +224,9 @@ export declare class VtxoManager implements AsyncDisposable, IVtxoManager {
     private consecutivePeriodicSettleFailures;
     private static readonly PERIODIC_SETTLE_COOLDOWN_MS;
     private static readonly PERIODIC_SETTLE_MAX_BACKOFF_MS;
+    private lastVtxoSpentRefreshTimestamp;
+    private vtxoSpentRefreshPromise?;
+    private static readonly VTXO_SPENT_REFRESH_COOLDOWN_MS;
     constructor(wallet: IWallet, 
     /** @deprecated Use settlementConfig instead */
     renewalConfig?: RenewalConfig | undefined, settlementConfig?: SettlementConfig | false);
@@ -397,11 +400,23 @@ 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. */
     private getIdentity;
     private initializeSubscription;
+    /**
+     * VTXO_ALREADY_SPENT means the server's authoritative view of VTXO state
+     * is ahead of ours — cross-instance race, pre-lock snapshot drift, or an
+     * SSE gap left stale data in the local cache. Silent-swallowing guarantees
+     * the same error on the next cycle because nothing reconciles the cache,
+     * so instead we trigger a full refreshVtxos() to advance the global sync
+     * cursor. Throttled to prevent a buggy indexer from causing a refresh
+     * storm.
+     */
+    private maybeRefreshAfterVtxoSpent;
     /** Computes the next poll delay, applying exponential backoff on failures. */
     private getNextPollDelay;
     /**

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

@@ -44,6 +44,7 @@ export declare class ReadonlyWallet implements IReadonlyWallet {
     protected readonly watcherConfig?: ReadonlyWalletConfig["watcherConfig"];
     private readonly _assetManager;
     private _syncVtxosInflight?;
+    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"]);
     /**
@@ -217,6 +218,8 @@ export declare class Wallet extends ReadonlyWallet implements IWallet {
      * same VTXO inputs.
      */
     private _txLock;
+    private _addPendingSpends;
+    private _removePendingSpends;
     private _withTxLock;
     /** @deprecated Use settlementConfig instead */
     readonly renewalConfig: Required<Omit<WalletConfig["renewalConfig"], "enabled">> & {