@arkade-os/sdk 0.4.22 → 0.4.23

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

@@ -1,3 +1,29 @@
+/**
+ * True iff `descriptor` is a Bitcoin mainnet descriptor (xpub-prefixed
+ * BIP32 key).
+ *
+ * Note: testnet, signet, regtest, mutinynet, and other non-mainnet
+ * networks all share the same `tpub` BIP32 version bytes — they cannot
+ * be distinguished from one another at the descriptor level. Callers
+ * that need a `Network` constants object for `expand()` pick
+ * `networks.bitcoin` vs `networks.testnet` themselves; callers that
+ * need the *actual* network the wallet is on must track that
+ * out-of-band.
+ */
+export declare function isMainnetDescriptor(descriptor: string): boolean;
+/**
+ * Shared "does `candidate` belong to the identity backed by
+ * `ourDescriptor`?" predicate.
+ *
+ * - HD descriptors (expanding to a `bip32` key) match by account xpub
+ *   on both sides — index-agnostic, so a wildcard template and any
+ *   concrete index under it all collapse to the same xpub.
+ * - Bare `tr(pubkey)` candidates fall back to comparing the candidate
+ *   pubkey against `ourXOnlyPubkey` (the cached pubkey on the identity
+ *   side, since pulling it from `ourDescriptor` would require an index
+ *   substitution the caller already performed).
+ */
+export declare function descriptorIsOurs(candidate: string, ourDescriptor: string, ourXOnlyPubkey: Uint8Array): boolean;
 /**
  * Check if a string is a descriptor of the shape `tr(...)`.
  *

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

@@ -13,12 +13,19 @@ export interface DescriptorSigningRequest {
  *
  * 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).
+ * - {@link HDDescriptorProvider}: rotates through HD-derived descriptors.
+ *
+ * The provider has no read accessor for "current" — it is a pure descriptor
+ * allocator. "What addresses am I currently bound to?" is a question the
+ * contract repository answers, not the provider.
  */
 export interface DescriptorProvider {
-    /** Returns the current signing descriptor. */
-    getSigningDescriptor(): string;
+    /**
+     * Allocate a new signing descriptor. For HD providers each call advances
+     * the internal index and returns a fresh descriptor; for single-key
+     * providers each call returns the same descriptor.
+     */
+    getNextSigningDescriptor(): Promise<string>;
     /** Checks if a descriptor belongs to this provider. */
     isOurs(descriptor: string): boolean;
     /** Signs transactions, each with its own descriptor-derived key. */

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

@@ -0,0 +1,44 @@
+import { Identity, ReadonlyIdentity } from ".";
+import { DescriptorSigningRequest } from "./descriptorProvider";
+import { Transaction } from "../utils/transaction";
+/**
+ * Read-side HD capability marker. Exposes the wildcard-suffixed account
+ * descriptor *template* and the descriptor-membership predicate, but no
+ * signing primitives — suitable for watch-only identities backed by an
+ * xpub.
+ *
+ * Extracted from {@link HDCapableIdentity} so that
+ * `ReadonlyDescriptorIdentity` can stand in for an HD wallet's read-only
+ * surface (template-aware, derives pubkeys at any index) without having
+ * to claim signing capability it cannot honour.
+ */
+export interface ReadonlyHDCapableIdentity extends ReadonlyIdentity {
+    /**
+     * The wildcard-suffixed account descriptor template
+     * (e.g. `tr([fp/86'/0'/0']xpub/0/*)`). Consumers materialize a
+     * concrete descriptor by replacing the `*` with a derivation index.
+     */
+    readonly descriptor: string;
+    /** True iff `descriptor` derives from this identity's xpub/seed. */
+    isOurs(descriptor: string): boolean;
+}
+/**
+ * Capability marker for identities that can be rotated through an HD
+ * derivation tree AND can sign at each rotated index.
+ *
+ * Deliberately does NOT extend `DescriptorProvider`: if an HD-capable
+ * identity were silently usable as a concrete descriptor source, callers
+ * could bypass receive rotation and unknowingly reuse a single address
+ * forever. To use this identity as a wallet's descriptor source, wrap
+ * it explicitly:
+ *
+ *  - `HDDescriptorProvider` — rotating, recommended for new wallets.
+ *  - `StaticDescriptorProvider` — pinned to a single key, for legacy or
+ *    explicitly-non-rotating use cases.
+ */
+export interface HDCapableIdentity extends ReadonlyHDCapableIdentity, Identity {
+    /** Signs each request with the key derived from its descriptor. */
+    signWithDescriptor(requests: DescriptorSigningRequest[]): Promise<Transaction[]>;
+    /** Signs a message using the key derived from `descriptor`. */
+    signMessageWithDescriptor(descriptor: string, message: Uint8Array, signatureType?: "schnorr" | "ecdsa"): Promise<Uint8Array>;
+}

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

@@ -52,4 +52,5 @@ export * from "./serialize";
 export { isDescriptor, normalizeToDescriptor, extractPubKey, parseHDDescriptor, } from "./descriptor";
 export type { ParsedHDDescriptor } from "./descriptor";
 export type { DescriptorProvider, DescriptorSigningRequest, } from "./descriptorProvider";
+export type { HDCapableIdentity, ReadonlyHDCapableIdentity, } from "./hdCapableIdentity";
 export { StaticDescriptorProvider } from "./staticDescriptorProvider";

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

@@ -1,7 +1,8 @@
-import { Identity, ReadonlyIdentity } from ".";
 import { Transaction } from "../utils/transaction";
 import { SignerSession } from "../tree/signingSession";
 import type { SerializedSigningIdentity, SerializedReadonlyIdentity } from "./serialize";
+import { DescriptorSigningRequest } from "./descriptorProvider";
+import { HDCapableIdentity, ReadonlyHDCapableIdentity } from "./hdCapableIdentity";
 /** Used for default BIP86 derivation with network selection. */
 export interface NetworkOptions {
     /**
@@ -11,12 +12,16 @@ export interface NetworkOptions {
      */
     isMainnet?: boolean;
 }
-/** Used for custom output descriptor derivation. */
+/** Used for a caller-supplied account-descriptor template. */
 export interface DescriptorOptions {
-    /** Custom output descriptor that determines the derivation path. */
+    /**
+     * Account-descriptor *template* — must end with the BIP-32 wildcard
+     * suffix `/*)`. Stored as-is on {@link SeedIdentity.descriptor} and
+     * read by HD providers to rotate through derivation indices.
+     */
     descriptor: string;
 }
-/** Either default BIP86 derivation (with optional network selection) or a custom descriptor. */
+/** Either default BIP86 derivation (with optional network selection) or a caller-supplied template. */
 export type SeedIdentityOptions = NetworkOptions | DescriptorOptions;
 /** Used for deriving an identity from a BIP39 mnemonic. */
 export type MnemonicOptions = SeedIdentityOptions & {
@@ -24,44 +29,77 @@ export type MnemonicOptions = SeedIdentityOptions & {
     passphrase?: string;
 };
 /**
- * Seed-based identity derived from a raw seed and an output descriptor.
+ * Seed-based identity derived from a raw seed and an account descriptor
+ * *template*.
  *
  * 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.
+ * standard BIP86 (Taproot) derivation by default; callers that need a
+ * different path supply the wildcard template directly.
  *
  * 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}.
+ * The identity holds the wildcard *template* (e.g.
+ * `tr([fp/86'/0'/0']xpub/0/*)`) on its public {@link descriptor}
+ * field. HD rotation reads it directly; consumers that need a
+ * concrete descriptor at a specific index materialize it themselves
+ * (see `HDDescriptorProvider` in the wallet layer).
+ *
+ * Exposes seed-level primitives (signing, derivation, the template)
+ * but is deliberately NOT a `DescriptorProvider`. Wrap it explicitly
+ * to get one:
+ *  - `HDDescriptorProvider` for rotating receive addresses.
+ *  - {@link StaticDescriptorProvider} for legacy, single-key behaviour.
+ *
+ * The split prevents a SeedIdentity from being silently used as a
+ * concrete descriptor source, which would defeat HD rotation without
+ * any compile-time signal that something was wrong.
  *
  * @example
  * ```typescript
  * const seed = mnemonicToSeedSync(mnemonic);
  *
- * // Testnet (BIP86 path m/86'/1'/0'/0/0)
+ * // Testnet (BIP86 wildcard descriptor m/86'/1'/0'/0/*)
  * const identity = SeedIdentity.fromSeed(seed, { isMainnet: false });
  *
- * // Mainnet (BIP86 path m/86'/0'/0'/0/0)
+ * // Mainnet (BIP86 wildcard descriptor m/86'/0'/0'/0/*)
  * const identity = SeedIdentity.fromSeed(seed, { isMainnet: true });
  *
- * // Custom descriptor
+ * // Caller-supplied wildcard descriptor (must end in `/*)`).
  * const identity = SeedIdentity.fromSeed(seed, { descriptor });
  * ```
  */
-export declare class SeedIdentity implements Identity {
+export declare class SeedIdentity implements HDCapableIdentity {
     private readonly derivedKey;
+    /**
+     * Wildcard account-descriptor template (e.g.
+     * `tr([fp/86'/0'/0']xpub/0/*)`). The canonical thing to pass
+     * through the system; consumers materialize a concrete descriptor
+     * at a specific index themselves (see `HDDescriptorProvider` in
+     * the wallet layer for the rotating-counter use case).
+     */
     readonly descriptor: string;
-    constructor(seed: Uint8Array, descriptor: string);
+    /**
+     * Constructs a SeedIdentity from a 64-byte seed and either a
+     * caller-supplied wildcard descriptor (`{ descriptor }`) or the
+     * default BIP86 path at the requested network (`{ isMainnet }`).
+     * Prefer the {@link fromSeed} factory for symmetry with
+     * {@link MnemonicIdentity.fromMnemonic}.
+     *
+     * Throws on a non-wildcard descriptor, an xpub mismatch with the
+     * seed, or a missing derivation path.
+     */
+    constructor(seed: Uint8Array, opts?: SeedIdentityOptions);
     /**
      * Creates a SeedIdentity from a raw 64-byte seed.
      *
      * Pass `{ isMainnet }` for default BIP86 derivation, or
-     * `{ descriptor }` for a custom derivation path.
+     * `{ descriptor }` for a caller-supplied account-descriptor
+     * template (the option's value must end with `/*)`).
      *
      * @param seed - 64-byte seed (typically from mnemonicToSeedSync)
-     * @param opts - Network selection or custom descriptor.
+     * @param opts - Network selection or descriptor template.
      */
     static fromSeed(seed: Uint8Array, opts?: SeedIdentityOptions): SeedIdentity;
     xOnlyPublicKey(): Promise<Uint8Array>;
@@ -70,9 +108,29 @@ export declare class SeedIdentity implements Identity {
     signMessage(message: Uint8Array, signatureType?: "schnorr" | "ecdsa"): Promise<Uint8Array>;
     signerSession(): SignerSession;
     /**
-     * Converts to a watch-only identity that cannot sign.
+     * Converts to a watch-only identity that cannot sign. Carries the
+     * template forward, so the readonly side stays HD-capable (can
+     * derive descriptors at any index without seed access).
      */
     toReadonly(): Promise<ReadonlyDescriptorIdentity>;
+    /**
+     * Returns true when `descriptor` is derived from this identity's seed.
+     * HD descriptors match by account xpub; bare `tr(pubkey)` descriptors
+     * match by raw pubkey. See {@link descriptorIsOurs}.
+     */
+    isOurs(descriptor: string): boolean;
+    /**
+     * Signs each request with the key derived from its descriptor.
+     * Each descriptor must share this identity's seed ({@link isOurs}).
+     */
+    signWithDescriptor(requests: DescriptorSigningRequest[]): Promise<Transaction[]>;
+    /**
+     * Signs a message with the key derived from `descriptor`.
+     */
+    signMessageWithDescriptor(descriptor: string, message: Uint8Array, signatureType?: "schnorr" | "ecdsa"): Promise<Uint8Array>;
+    private derivePrivateKeyForDescriptor;
+    private signTxWithKey;
+    private signMessageWithKey;
 }
 /**
  * Mnemonic-based identity derived from a BIP39 phrase.
@@ -96,40 +154,66 @@ export declare class MnemonicIdentity extends SeedIdentity {
      * Creates a MnemonicIdentity from a BIP39 mnemonic phrase.
      *
      * Pass `{ isMainnet }` for default BIP86 derivation, or
-     * `{ descriptor }` for a custom derivation path.
+     * `{ descriptor }` for a caller-supplied account-descriptor
+     * template (the option's value must end with `/*)`).
      *
      * @param phrase - BIP39 mnemonic phrase (12 or 24 words)
-     * @param opts - Network selection or custom descriptor, plus optional passphrase
+     * @param opts - Network selection or descriptor template, plus optional passphrase
      */
     static fromMnemonic(phrase: string, opts?: MnemonicOptions): MnemonicIdentity;
 }
 /**
- * Watch-only identity from an output descriptor.
+ * Watch-only HD identity from a descriptor *template*.
  *
  * Can derive public keys but cannot sign transactions. Use this for
- * watch-only wallets or when sharing identity information without
- * exposing private keys.
+ * watch-only wallets — given just an xpub-based template, the readonly
+ * side still rotates through HD indices.
+ *
+ * Constructed from a wildcard template (e.g.
+ * `tr([fp/86'/0'/0']xpub.../0/*)`); the {@link descriptor} field
+ * holds it for HD providers to consume.
  *
  * @example
  * ```typescript
- * const descriptor = "tr([fingerprint/86'/0'/0']xpub.../0/0)";
- * const readonly = ReadonlyDescriptorIdentity.fromDescriptor(descriptor);
- * const pubKey = await readonly.xOnlyPublicKey();
+ * const ro = ReadonlyDescriptorIdentity.fromDescriptor(
+ *   "tr([fp/86'/0'/0']xpub.../0/*)"
+ * );
+ * ro.descriptor;
+ * // => "tr([fp/86'/0'/0']xpub.../0/*)" — the template
  * ```
  */
-export declare class ReadonlyDescriptorIdentity implements ReadonlyIdentity {
+export declare class ReadonlyDescriptorIdentity implements ReadonlyHDCapableIdentity {
+    /**
+     * Index-0 expansion of {@link descriptor}. Both the x-only pubkey
+     * (taproot, returned by the library as 32 bytes) and the compressed
+     * pubkey (derived through the bip32 node when needed) are read off
+     * this on demand — no separate caches.
+     */
+    private readonly indexZero;
+    /**
+     * Wildcard account-descriptor template (e.g.
+     * `tr([fp/86'/0'/0']xpub/0/*)`). HD rotation consumers materialize
+     * a concrete descriptor at a specific index themselves.
+     */
     readonly descriptor: string;
-    private readonly xOnlyPubKey;
-    private readonly compressedPubKey;
     private constructor();
     /**
-     * Creates a ReadonlyDescriptorIdentity from an output descriptor.
+     * Creates a ReadonlyDescriptorIdentity from an account-descriptor
+     * *template* (must end with the BIP-32 wildcard suffix `/*)`).
      *
-     * @param descriptor - Taproot descriptor: tr([fingerprint/path']xpub.../child/path)
+     * @param descriptor - Wildcard-suffixed Taproot template
+     *   (`tr([fp/path']xpub.../child/*)`).
      */
     static fromDescriptor(descriptor: string): ReadonlyDescriptorIdentity;
     xOnlyPublicKey(): Promise<Uint8Array>;
     compressedPublicKey(): Promise<Uint8Array>;
+    /**
+     * Returns true when `descriptor` derives from this identity's xpub.
+     * HD descriptors match by account xpub; bare `tr(pubkey)` descriptors
+     * fall back to comparing against the index-0 x-only pubkey. See
+     * {@link descriptorIsOurs}.
+     */
+    isOurs(descriptor: string): boolean;
 }
 /**
  * Serialize a seed-backed signing identity into a

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

@@ -4,6 +4,11 @@ import type { Identity, ReadonlyIdentity } from ".";
  * service-worker boundary. All variants are structured-clone safe
  * (plain strings only — no functions or prototypes).
  *
+ * `descriptor` carries the wildcard *template* (e.g.
+ * `tr([fp/86'/0'/0']xpub.../0/*)`), not a concrete index — the
+ * receiving factories require a template, and storing it directly
+ * means nothing here has to convert concrete → template on rehydrate.
+ *
  * Adding a new variant is a source change in every worker build; keep
  * old variants around until all deployed workers handle them.
  */
@@ -23,6 +28,8 @@ export type SerializedSigningIdentity = {
 /**
  * Tagged envelope for a readonly identity transported across the
  * service-worker boundary. All variants are structured-clone safe.
+ * `descriptor` is the wildcard template (see
+ * {@link SerializedSigningIdentity}).
  */
 export type SerializedReadonlyIdentity = {
     type: "readonly-single-key";
@@ -57,6 +64,11 @@ export declare function serializeReadonlyIdentity(identity: ReadonlyIdentity): P
  * 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.
+ *
+ * Envelopes store the wildcard template directly (see
+ * `serializeSeedOwnedSigningIdentity` / `serializeSeedOwnedReadonlyIdentity`),
+ * so the `descriptor` field is passed straight through to the
+ * template-only factories.
  */
 export declare function hydrateIdentity(s: SerializedIdentity): Identity | ReadonlyIdentity;
 /**

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

@@ -11,7 +11,7 @@ export declare class StaticDescriptorProvider implements DescriptorProvider {
     private readonly pubKeyHex;
     constructor(identity: Identity, pubKeyHex: string);
     static create(identity: Identity): Promise<StaticDescriptorProvider>;
-    getSigningDescriptor(): string;
+    getNextSigningDescriptor(): Promise<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

@@ -15,6 +15,7 @@ import { Wallet, ReadonlyWallet, waitForIncomingFunds, IncomingFunds } from "./w
 import { TxTree, TxTreeNode } from "./tree/txTree";
 import { SignerSession, TreeNonces, TreePartialSigs } from "./tree/signingSession";
 import { Ramps } from "./wallet/ramps";
+import { HDDescriptorProvider } from "./wallet/hdDescriptorProvider";
 import { isVtxoExpiringSoon, VtxoManager } from "./wallet/vtxo-manager";
 import type { IVtxoManager, SettlementConfig } from "./wallet/vtxo-manager";
 import { ServiceWorkerWallet, ServiceWorkerReadonlyWallet, DEFAULT_MESSAGE_TIMEOUTS } from "./wallet/serviceWorker/wallet";
@@ -22,7 +23,7 @@ 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 { ELECTRUM_TCP_HOST, ELECTRUM_WS_URL, 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";
@@ -37,6 +38,7 @@ import { RestIndexerProvider, IndexerProvider, IndexerTxType, ChainTxType, PageR
 import { Nonces } from "./musig2/nonces";
 import { PartialSig } from "./musig2/sign";
 import { AnchorBumper, P2A } from "./utils/anchor";
+import { TxWeightEstimator, type VSize } from "./utils/txSizeEstimator";
 import { Unroll } from "./wallet/unroll";
 import { ArkError, maybeArkError } from "./providers/errors";
 import { validateVtxoTxGraph, validateConnectorsTxGraph } from "./tree/validation";
@@ -49,8 +51,9 @@ export * as asset from "./extension/asset";
 import { ContractManager, ContractWatcher, contractHandlers, DefaultContractHandler, DelegateContractHandler, VHTLCContractHandler, encodeArkContract, decodeArkContract, contractFromArkContract, contractFromArkContractWithAddress, isArkContract } from "./contracts";
 import type { Contract, ContractVtxo, ContractState, ContractEvent, ContractEventCallback, ContractBalance, ContractWithVtxos, ContractHandler, PathSelection, PathContext, ContractManagerConfig, CreateContractParams, ContractWatcherConfig, ParsedArkContract, DefaultContractParams, DelegateContractParams, VHTLCContractParams } from "./contracts";
 import { IContractManager } from "./contracts/contractManager";
+import { timelockToSequence, sequenceToTimelock } from "./contracts/handlers/helpers";
 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, 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, };
+export { Wallet, ReadonlyWallet, SingleKey, ReadonlySingleKey, SeedIdentity, MnemonicIdentity, ReadonlyDescriptorIdentity, isBatchSignable, OnchainWallet, Ramps, VtxoManager, HDDescriptorProvider, DelegatorManagerImpl, RestDelegatorProvider, ESPLORA_URL, EsploraProvider, ELECTRUM_WS_URL, ELECTRUM_TCP_HOST, 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, TxWeightEstimator, timelockToSequence, sequenceToTimelock, 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, VSize, 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

@@ -1,7 +1,39 @@
 import type { ElectrumWS } from "ws-electrumx-client";
-import type { Network } from "../networks";
+import type { Network, NetworkName } from "../networks";
 import type { Coin } from "../wallet";
 import type { ExplorerTransaction, OnchainProvider } from "./onchain";
+/**
+ * Default WebSocket Electrum endpoints. Mainnet, mutinynet, and signet
+ * point at Ark Labs–operated Fulcrum 2.1 deployments (which support
+ * `blockchain.transaction.broadcast_package` for atomic 1P1C TRUC
+ * relay; see `ElectrumOnchainProvider.broadcastTransaction`). Testnet
+ * defaults to Blockstream's public Fulcrum because Ark doesn't host
+ * it. Regtest assumes the `electrum-ws` websocat bridge from
+ * `vulpemventures/nigiri`.
+ *
+ * @example
+ * ```typescript
+ * import { ElectrumWS } from "ws-electrumx-client";
+ * import { ELECTRUM_WS_URL, ElectrumOnchainProvider, networks } from "@arkade-os/sdk";
+ *
+ * const ws = new ElectrumWS(ELECTRUM_WS_URL.bitcoin);
+ * const provider = new ElectrumOnchainProvider(ws, networks.bitcoin);
+ * ```
+ */
+export declare const ELECTRUM_WS_URL: Record<NetworkName, string>;
+/**
+ * Hostnames for Electrum endpoints reachable over raw TCP. Provided as
+ * a reference for Node-side consumers — the SDK's
+ * {@link ElectrumOnchainProvider} only speaks WebSocket because it has
+ * to run in browsers, so this map is informational only and not
+ * consumed by any built-in provider.
+ *
+ * Public Ark Labs Fulcrum instances expose:
+ *   - port 50001 — plain TCP (Electrum protocol)
+ *   - port 50002 — TCP + TLS (Electrum protocol)
+ *   - port 50003 — WebSocket (Electrum-over-WS, see {@link ELECTRUM_WS_URL})
+ */
+export declare const ELECTRUM_TCP_HOST: Record<NetworkName, string | null>;
 export type TransactionHistory = {
     tx_hash: string;
     height: number;
@@ -70,12 +102,46 @@ export declare class WsElectrumChainSource {
     private cachedTip;
     private headersSubscribePromise;
     constructor(ws: ElectrumWS, network: Network);
+    /**
+     * Send N requests in parallel and aggregate the results, replacement
+     * for `ws.batchRequest`. The library's batchRequest is implemented as
+     * `Promise.all` over individual request promises — when one element
+     * rejects, the others remain pending. When their (often error)
+     * responses arrive later, the library rejects them too, and nobody is
+     * awaiting them: the rejections become unhandled and crash the test
+     * runner / pollute production logs.
+     *
+     * `safeBatchRequest` issues each request through `ws.request` (so each
+     * has its own request-promise lifecycle), waits for all of them via
+     * `Promise.allSettled` (every promise gets an explicit handler), and
+     * then surfaces the first error if any failed. Same wall-clock cost
+     * as the library's batch (parallel send), no orphan rejections.
+     *
+     * Use this in place of `ws.batchRequest` for any call where one or
+     * more elements may legitimately error (e.g. electrs index lag
+     * surfacing as `missingheight` for a subset of heights/txids).
+     */
+    safeBatchRequest<T>(requests: {
+        method: string;
+        params: unknown[];
+    }[]): Promise<T[]>;
     fetchTransactions(txids: string[]): Promise<{
         txID: string;
         hex: string;
     }[]>;
     fetchVerboseTransaction(txid: string): Promise<VerboseTransaction>;
     fetchVerboseTransactions(txids: string[]): Promise<VerboseTransaction[]>;
+    /**
+     * Look up the block height of a confirmed transaction without relying
+     * on the verbose-tx endpoint. `blockchain.transaction.get_merkle` is
+     * part of the standard SPV protocol and is supported by both Fulcrum
+     * and electrs (whereas `blockchain.transaction.get` with verbose=true
+     * is Fulcrum-only). Returns `null` when the tx is in the mempool —
+     * electrs in that case rejects with a "not yet in a block" error.
+     */
+    fetchTxMerkle(txid: string): Promise<{
+        blockHeight: number;
+    } | null>;
     unsubscribeScriptStatus(script: Uint8Array): Promise<void>;
     subscribeScriptStatus(script: Uint8Array, callback: (scripthash: string, status: string | null) => void): Promise<void>;
     fetchHistories(scripts: Uint8Array[]): Promise<TransactionHistory[][]>;
@@ -130,19 +196,45 @@ export declare class WsElectrumChainSource {
     addressForScript(scriptHex: string): string | undefined;
 }
 /**
- * Electrum-based implementation of the OnchainProvider interface.
- * Replaces esplora polling with electrum subscriptions where possible.
+ * Electrum-based implementation of the {@link OnchainProvider} interface.
  *
- * @example
+ * Built around the subset of the Electrum protocol that both **Fulcrum**
+ * and **electrs** support — listunspent, get_history, transaction.get
+ * (non-verbose), transaction.get_merkle, block.header,
+ * headers.subscribe, scripthash.subscribe, estimatefee, relayfee, and
+ * broadcast. The verbose form of `transaction.get` is **not** used (it's
+ * Fulcrum-only and rejected by electrs); confirmation status is derived
+ * from `transaction.get_merkle` plus parsed block headers.
+ *
+ * Output amounts are derived from parsed raw transaction bytes (exact
+ * bigints), never the floating-point `value` fields some servers return.
+ *
+ * Atomic 1P1C package broadcast (TRUC / BIP 431) is supported via
+ * Fulcrum's `blockchain.transaction.broadcast_package`. There is **no
+ * fallback** to sequential parent-then-child broadcasts — TRUC packages
+ * with a zero-fee parent would silently fail, so the call surfaces an
+ * error against servers that don't support the method.
+ *
+ * @example Default URL via {@link ELECTRUM_WS_URL}
  * ```typescript
  * import { ElectrumWS } from "ws-electrumx-client";
- * import { ElectrumOnchainProvider } from "./providers/electrum";
- * import { networks } from "./networks";
+ * import {
+ *   ElectrumOnchainProvider,
+ *   ELECTRUM_WS_URL,
+ *   networks,
+ * } from "@arkade-os/sdk";
  *
- * const ws = new ElectrumWS("wss://electrum.blockstream.info:50004");
+ * const ws = new ElectrumWS(ELECTRUM_WS_URL.bitcoin);
  * const provider = new ElectrumOnchainProvider(ws, networks.bitcoin);
  *
  * const coins = await provider.getCoins("bc1q...");
+ * await provider.close();
+ * ```
+ *
+ * @example Custom server
+ * ```typescript
+ * const ws = new ElectrumWS("wss://my-fulcrum.example:50004");
+ * const provider = new ElectrumOnchainProvider(ws, networks.bitcoin);
  * ```
  */
 export declare class ElectrumOnchainProvider implements OnchainProvider {
@@ -178,15 +270,23 @@ export declare class ElectrumOnchainProvider implements OnchainProvider {
     }[]>;
     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.
+     * Resolve a list of `{tx_hash, height}` entries (as returned by the
+     * scripthash history endpoint) into ExplorerTransaction shape **without
+     * using the verbose-tx endpoint**, which only Fulcrum implements. We
+     * reconstruct everything the verbose response would have given us:
+     *   - vouts ← parse the raw tx (exact sat amounts, no float precision risk)
+     *   - block_time ← batch-fetch the block headers for the heights present
+     *   - addresses ← decode each output's scriptPubKey via @scure/btc-signer
+     */
+    private historyToExplorerTxs;
+    /**
+     * Build an ExplorerTransaction from a history entry plus the raw tx hex
+     * (when known) and a height→block_time map. Parse errors propagate —
+     * silently returning an empty vout would hide real outputs (e.g. a
+     * deposit) and is far worse for protocol-level money handling than
+     * failing the whole batch.
      */
-    private verboseToExplorer;
+    private buildExplorerTx;
     /**
      * Decode `address` into its scriptPubKey, throwing a clear error if the
      * input is malformed. @scure/btc-signer raises a generic decode error

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

@@ -2,6 +2,12 @@ import type { NetworkName } from "../networks";
 import { Coin } from "../wallet";
 /**
  * The default base URLs for esplora API providers.
+ *
+ * Mainnet, mutinynet, and signet point at Ark Labs–operated
+ * mempool deployments (mempool.space-compatible esplora API).
+ * Testnet falls back to the public mempool.space deployment
+ * because Ark doesn't host it. Regtest assumes a local nigiri
+ * stack on the standard port.
  */
 export declare const ESPLORA_URL: Record<NetworkName, string>;
 export type ExplorerTransaction = {