@arkade-os/sdk 0.5.0-rc.0 → 0.5.0-rc.2

package/dist/contracts/handlers/index.cjs

@@ -1,38 +1,38 @@
 'use strict';
 
-var chunkHL7EC2Z5_cjs = require('../../chunk-HL7EC2Z5.cjs');
-require('../../chunk-6AFUNKK7.cjs');
+var chunk43FKNLX4_cjs = require('../../chunk-43FKNLX4.cjs');
+require('../../chunk-JZWLXNHV.cjs');
 require('../../chunk-5BLDMQED.cjs');
 
 
 
 Object.defineProperty(exports, "ArkadeContractHandler", {
   enumerable: true,
-  get: function () { return chunkHL7EC2Z5_cjs.ArkadeContractHandler; }
+  get: function () { return chunk43FKNLX4_cjs.ArkadeContractHandler; }
 });
 Object.defineProperty(exports, "BoardingContractHandler", {
   enumerable: true,
-  get: function () { return chunkHL7EC2Z5_cjs.BoardingContractHandler; }
+  get: function () { return chunk43FKNLX4_cjs.BoardingContractHandler; }
 });
 Object.defineProperty(exports, "DefaultContractHandler", {
   enumerable: true,
-  get: function () { return chunkHL7EC2Z5_cjs.DefaultContractHandler; }
+  get: function () { return chunk43FKNLX4_cjs.DefaultContractHandler; }
 });
 Object.defineProperty(exports, "DelegateContractHandler", {
   enumerable: true,
-  get: function () { return chunkHL7EC2Z5_cjs.DelegateContractHandler; }
+  get: function () { return chunk43FKNLX4_cjs.DelegateContractHandler; }
 });
 Object.defineProperty(exports, "VHTLCContractHandler", {
   enumerable: true,
-  get: function () { return chunkHL7EC2Z5_cjs.VHTLCContractHandler; }
+  get: function () { return chunk43FKNLX4_cjs.VHTLCContractHandler; }
 });
 Object.defineProperty(exports, "VHTLCV2ContractHandler", {
   enumerable: true,
-  get: function () { return chunkHL7EC2Z5_cjs.VHTLCV2ContractHandler; }
+  get: function () { return chunk43FKNLX4_cjs.VHTLCV2ContractHandler; }
 });
 Object.defineProperty(exports, "contractHandlers", {
   enumerable: true,
-  get: function () { return chunkHL7EC2Z5_cjs.contractHandlers; }
+  get: function () { return chunk43FKNLX4_cjs.contractHandlers; }
 });
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map

package/dist/contracts/handlers/index.d.cts

@@ -1,7 +1,7 @@
-export { n as ArkadeContractHandler, B as BoardingContractHandler, o as BoardingContractParams, D as DefaultContractHandler, q as DefaultContractParams, t as DelegateContractHandler, u as DelegateContractParams, x as VHTLCContractHandler, y as VHTLCContractParams, z as VHTLCV2ContractHandler, E as VHTLCV2ContractParams, F as contractHandlers } from '../../index-D3hmsuKs.cjs';
-import '../../index-Udm5V2xW.cjs';
+export { n as ArkadeContractHandler, B as BoardingContractHandler, o as BoardingContractParams, D as DefaultContractHandler, q as DefaultContractParams, t as DelegateContractHandler, u as DelegateContractParams, x as VHTLCContractHandler, y as VHTLCContractParams, z as VHTLCV2ContractHandler, E as VHTLCV2ContractParams, F as contractHandlers } from '../../index-W_oMcOmG.cjs';
+import '../../index-DUxufw76.cjs';
 import '@scure/btc-signer/utils.js';
 import '@scure/btc-signer/transaction.js';
 import '@scure/btc-signer';
 import '@scure/btc-signer/psbt.js';
-import '../../delegate-DLIOBQ5x.cjs';
+import '../../delegate-1yp1HyP7.cjs';

package/dist/contracts/handlers/index.d.ts

@@ -1,7 +1,7 @@
-export { n as ArkadeContractHandler, B as BoardingContractHandler, o as BoardingContractParams, D as DefaultContractHandler, q as DefaultContractParams, t as DelegateContractHandler, u as DelegateContractParams, x as VHTLCContractHandler, y as VHTLCContractParams, z as VHTLCV2ContractHandler, E as VHTLCV2ContractParams, F as contractHandlers } from '../../index-D9tXd-tN.js';
-import '../../index-Udm5V2xW.js';
+export { n as ArkadeContractHandler, B as BoardingContractHandler, o as BoardingContractParams, D as DefaultContractHandler, q as DefaultContractParams, t as DelegateContractHandler, u as DelegateContractParams, x as VHTLCContractHandler, y as VHTLCContractParams, z as VHTLCV2ContractHandler, E as VHTLCV2ContractParams, F as contractHandlers } from '../../index-Bem5vKzX.js';
+import '../../index-DUxufw76.js';
 import '@scure/btc-signer/utils.js';
 import '@scure/btc-signer/transaction.js';
 import '@scure/btc-signer';
 import '@scure/btc-signer/psbt.js';
-import '../../delegate-Dyn5L80J.js';
+import '../../delegate-BAX5QftB.js';

package/dist/contracts/handlers/index.js

@@ -1,5 +1,5 @@
-export { ArkadeContractHandler, BoardingContractHandler, DefaultContractHandler, DelegateContractHandler, VHTLCContractHandler, VHTLCV2ContractHandler, contractHandlers } from '../../chunk-KTU44AEH.js';
-import '../../chunk-PPG6W34P.js';
+export { ArkadeContractHandler, BoardingContractHandler, DefaultContractHandler, DelegateContractHandler, VHTLCContractHandler, VHTLCV2ContractHandler, contractHandlers } from '../../chunk-3R476TDV.js';
+import '../../chunk-ISO4TI5J.js';
 import '../../chunk-NSBPE2FW.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/{delegate-DLIOBQ5x.d.cts → delegate-1yp1HyP7.d.cts}

@@ -1,5 +1,5 @@
 import { Bytes } from '@scure/btc-signer/utils.js';
-import { w as RelativeTimelock, V as VtxoScript, x as TapLeafScript } from './index-Udm5V2xW.cjs';
+import { w as RelativeTimelock, V as VtxoScript, x as TapLeafScript } from './index-DUxufw76.cjs';
 
 /**
  * DefaultVtxo is the default implementation of a VtxoScript.

package/dist/{delegate-Dyn5L80J.d.ts → delegate-BAX5QftB.d.ts}

@@ -1,5 +1,5 @@
 import { Bytes } from '@scure/btc-signer/utils.js';
-import { w as RelativeTimelock, V as VtxoScript, x as TapLeafScript } from './index-Udm5V2xW.js';
+import { w as RelativeTimelock, V as VtxoScript, x as TapLeafScript } from './index-DUxufw76.js';
 
 /**
  * DefaultVtxo is the default implementation of a VtxoScript.

package/dist/{hdWalletCapable-Dt3MUiGE.d.cts → hdWalletCapable-CmEU0NP1.d.ts}

@@ -1,8 +1,8 @@
-import { w as RelativeTimelock, X as Network, Y as CSVMultisigTapscript, Z as BatchStartedEvent, _ as TreeSigningStartedEvent, $ as TxTree, a0 as TreeNoncesEvent, a1 as BatchFinalizationEvent, a2 as BatchFinalizedEvent, a3 as BatchFailedEvent, a4 as TreeTxEvent, a5 as TreeSignatureEvent, o as SettlementEvent, b as WalletConfig, W as WalletRepository, C as ContractRepository, a6 as DescriptorProvider, j as IContractManager, a7 as IReadonlyWallet, a8 as ReadonlyIdentity, a9 as OnchainProvider, u as ArkProvider, v as IndexerProvider, aa as DelegateProvider, ab as ReadonlyWalletConfig, J as IntentRepository, M as VirtualTxRepository, ac as ExitCaptureMode, ad as ExitDataSource, h as ActivityRegistry, ae as IReadonlyAssetManager, af as ContractSyncState, ag as RecipientArkadeAddressContext, G as GetArkadeInfoOptions, A as ArkadeInfo, c as ArkadeReader, ah as NetworkName, ai as ArkAddress, e as WalletBalance, f as GetVtxosFilter, N as NormalizedExtendedVirtualCoin, aj as ContractWithVtxos, ak as selectPendingRecoveryOutpoints, g as ArkTransaction, i as Activity, E as ExtendedCoin, al as Coin, B as ExtendedVirtualCoin, am as ContractManager, an as ContractManagerConfig, I as IWallet, a as Identity, k as GetNewAddressesOptions, l as NewAddress, ao as SettlementConfig, d as ArkadeBroadcaster, q as IAssetManager, ap as VtxoManager, m as IDelegateManager, S as SendBitcoinParams, n as SettleParams, R as Recipient, aq as SignerSession, ar as SignedIntent, as as Intent, p as SendParams, at as TimeHeight } from './index-Udm5V2xW.cjs';
+import { w as RelativeTimelock, X as Network, Y as CSVMultisigTapscript, Z as BatchStartedEvent, _ as TreeSigningStartedEvent, $ as TxTree, a0 as TreeNoncesEvent, a1 as BatchFinalizationEvent, a2 as BatchFinalizedEvent, a3 as BatchFailedEvent, a4 as TreeTxEvent, a5 as TreeSignatureEvent, o as SettlementEvent, b as WalletConfig, W as WalletRepository, C as ContractRepository, a6 as DescriptorProvider, j as IContractManager, a7 as IReadonlyWallet, a8 as ReadonlyIdentity, a9 as OnchainProvider, u as ArkProvider, v as IndexerProvider, aa as DelegateProvider, ab as ReadonlyWalletConfig, J as IntentRepository, M as VirtualTxRepository, ac as ExitCaptureMode, ad as ExitDataSource, h as ActivityRegistry, ae as IReadonlyAssetManager, af as ContractSyncState, ag as RecipientArkadeAddressContext, G as GetArkadeInfoOptions, A as ArkadeInfo, c as ArkadeReader, ah as NetworkName, ai as ArkAddress, e as WalletBalance, f as GetVtxosFilter, N as NormalizedExtendedVirtualCoin, aj as ContractWithVtxos, ak as selectPendingRecoveryOutpoints, g as ArkTransaction, i as Activity, E as ExtendedCoin, al as Coin, B as ExtendedVirtualCoin, am as ContractManager, an as ContractManagerConfig, I as IWallet, a as Identity, k as GetNewAddressesOptions, l as NewAddress, ao as SettlementConfig, d as ArkadeBroadcaster, q as IAssetManager, ap as VtxoManager, m as IDelegateManager, S as SendBitcoinParams, n as SettleParams, R as Recipient, aq as SignerSession, ar as SignedIntent, as as Intent, p as SendParams, at as TimeHeight } from './index-DUxufw76.js';
 import { Transaction } from '@scure/btc-signer';
 import { TransactionOutput } from '@scure/btc-signer/psbt.js';
 import { Bytes } from '@scure/btc-signer/utils.js';
-import { D as DefaultVtxo, a as DelegateVtxo } from './delegate-DLIOBQ5x.cjs';
+import { D as DefaultVtxo, a as DelegateVtxo } from './delegate-BAX5QftB.js';
 
 /** Wall-clock floor for `batchExpiry` outside regtest. */
 declare const DEFAULT_MIN_BATCH_EXPIRY_SECONDS = 86400n;
@@ -2013,11 +2013,55 @@ declare function selectVirtualCoins(coins: ExtendedVirtualCoin[], targetAmount:
     changeAmount: bigint;
 };
 /**
- * Wait for incoming funds to the wallet
+ * Raised when a wait is cancelled through its `AbortSignal` or `timeoutMs`.
+ *
+ * `name` is `"AbortError"`, matching both the platform convention and the
+ * `error.name === "AbortError"` checks the provider layer already makes, so a
+ * caller can treat DOM and SDK aborts identically.
+ */
+declare class AbortError extends Error {
+    constructor(message?: string);
+}
+/** Options for {@link waitForIncomingFunds}. */
+interface WaitForIncomingFundsOptions {
+    /**
+     * Cancels the wait. On abort the underlying subscription is stopped and
+     * the returned promise rejects — with the signal's `reason` when the
+     * caller supplied an `Error`, otherwise an {@link AbortError}.
+     */
+    signal?: AbortSignal;
+    /**
+     * Cancels the wait after this many milliseconds, rejecting with an
+     * {@link AbortError}. Equivalent to passing an `AbortSignal.timeout`
+     * signal, without requiring that API on the target platform.
+     */
+    timeoutMs?: number;
+}
+/**
+ * Wait for incoming funds to the wallet.
+ *
+ * This opens live network watchers (an onchain address subscription plus the
+ * wallet's indexer stream) and keeps them open until it settles. **Cancel it
+ * if you are not going to await it to completion** — pass a `signal` or a
+ * `timeoutMs`. Racing an uncancelled call against a timer (`Promise.race`)
+ * abandons the loser without stopping its watchers, and repeating that in a
+ * loop stacks subscriptions until the process exits.
+ *
  * @param wallet - The wallet to wait for incoming funds
+ * @param options - Cancellation options; see {@link WaitForIncomingFundsOptions}
  * @returns A promise that resolves the next new coins received by the wallet's address
+ * @throws {AbortError} If cancelled via `signal` or `timeoutMs`
+ * @example
+ * ```typescript
+ * // Wake early on a deposit, but give up after 30s and release the watchers.
+ * try {
+ *   const funds = await waitForIncomingFunds(wallet, { timeoutMs: 30_000 })
+ * } catch (e) {
+ *   if ((e as Error).name !== "AbortError") throw e
+ * }
+ * ```
  */
-declare function waitForIncomingFunds(wallet: Wallet): Promise<IncomingFunds>;
+declare function waitForIncomingFunds(wallet: Wallet, options?: WaitForIncomingFundsOptions): Promise<IncomingFunds>;
 
 /**
  * Capability a wallet exposes so descriptor-blind consumers — Boltz swaps and
@@ -2185,4 +2229,4 @@ interface AddressAllocationCapable {
 /** Structural type guard for {@link AddressAllocationCapable}. */
 declare function isAddressAllocationCapable(value: unknown): value is AddressAllocationCapable;
 
-export { type AddressAllocationCapable as A, type BatchExpiryPolicy as B, type CheckpointExitDelayPolicy as C, DEFAULT_MIN_BATCH_EXPIRY_SECONDS as D, isArkError as E, ForeignDescriptorError as F, isHDAllocationCapable as G, type HDWalletCapable as H, type IncomingFunds as I, isHDWalletCapable as J, maybeArkError as K, resolveBatchExpiryPolicy as L, MAX_USED_SIGNING_DESCRIPTORS_LOOK_AHEAD as M, resolveCheckpointExitDelayPolicy as N, resolveDescriptorSigner as O, type ProviderConnectionState as P, selectVirtualCoins as Q, ReadonlyWallet as R, SIGNET_MIN_CHECKPOINT_EXIT_DELAY_SECONDS as S, signingDescriptorIndex as T, strictSigningDescriptorIndex as U, waitForIncomingFunds as V, Wallet as W, type HDAllocationCapable as a, type ReceiveRotatorFactory as b, type ReceiveRotatorBootOpts as c, type ReceiveRotatorBoot as d, Batch as e, ArkError as f, ArkErrorName as g, type ArkadeCashClaimResult as h, ArkadeCashCreateError as i, type ArkadeCashUnclaimedReason as j, type ArkadeCashUnclaimedVtxo as k, type BoardingUtxoGroup as l, DEFAULT_MIN_CHECKPOINT_EXIT_DELAY_SECONDS as m, MUTINYNET_MIN_CHECKPOINT_EXIT_DELAY_SECONDS as n, type ProviderKind as o, ProviderUnavailableError as p, REGTEST_MIN_BATCH_EXPIRY_SECONDS as q, REGTEST_MIN_CHECKPOINT_EXIT_DELAY_SECONDS as r, type ServerInfoSource as s, ServerResponseMismatchError as t, WalletCannotAllocateAddressError as u, assertValidBatchExpiry as v, assertValidServerUnrollScript as w, defaultBatchExpiryPolicy as x, defaultCheckpointExitDelayPolicy as y, isAddressAllocationCapable as z };
+export { type AddressAllocationCapable as A, type BatchExpiryPolicy as B, type CheckpointExitDelayPolicy as C, DEFAULT_MIN_BATCH_EXPIRY_SECONDS as D, defaultCheckpointExitDelayPolicy as E, ForeignDescriptorError as F, isAddressAllocationCapable as G, type HDWalletCapable as H, type IncomingFunds as I, isArkError as J, isHDAllocationCapable as K, isHDWalletCapable as L, MAX_USED_SIGNING_DESCRIPTORS_LOOK_AHEAD as M, maybeArkError as N, resolveBatchExpiryPolicy as O, type ProviderConnectionState as P, resolveCheckpointExitDelayPolicy as Q, ReadonlyWallet as R, SIGNET_MIN_CHECKPOINT_EXIT_DELAY_SECONDS as S, resolveDescriptorSigner as T, selectVirtualCoins as U, signingDescriptorIndex as V, Wallet as W, strictSigningDescriptorIndex as X, waitForIncomingFunds as Y, type HDAllocationCapable as a, type ReceiveRotatorFactory as b, type ReceiveRotatorBootOpts as c, type ReceiveRotatorBoot as d, Batch as e, AbortError as f, ArkError as g, ArkErrorName as h, type ArkadeCashClaimResult as i, ArkadeCashCreateError as j, type ArkadeCashUnclaimedReason as k, type ArkadeCashUnclaimedVtxo as l, type BoardingUtxoGroup as m, DEFAULT_MIN_CHECKPOINT_EXIT_DELAY_SECONDS as n, MUTINYNET_MIN_CHECKPOINT_EXIT_DELAY_SECONDS as o, type ProviderKind as p, ProviderUnavailableError as q, REGTEST_MIN_BATCH_EXPIRY_SECONDS as r, REGTEST_MIN_CHECKPOINT_EXIT_DELAY_SECONDS as s, type ServerInfoSource as t, ServerResponseMismatchError as u, type WaitForIncomingFundsOptions as v, WalletCannotAllocateAddressError as w, assertValidBatchExpiry as x, assertValidServerUnrollScript as y, defaultBatchExpiryPolicy as z };

package/dist/{hdWalletCapable-D9tooZ6F.d.ts → hdWalletCapable-eJgaT-ec.d.cts}

@@ -1,8 +1,8 @@
-import { w as RelativeTimelock, X as Network, Y as CSVMultisigTapscript, Z as BatchStartedEvent, _ as TreeSigningStartedEvent, $ as TxTree, a0 as TreeNoncesEvent, a1 as BatchFinalizationEvent, a2 as BatchFinalizedEvent, a3 as BatchFailedEvent, a4 as TreeTxEvent, a5 as TreeSignatureEvent, o as SettlementEvent, b as WalletConfig, W as WalletRepository, C as ContractRepository, a6 as DescriptorProvider, j as IContractManager, a7 as IReadonlyWallet, a8 as ReadonlyIdentity, a9 as OnchainProvider, u as ArkProvider, v as IndexerProvider, aa as DelegateProvider, ab as ReadonlyWalletConfig, J as IntentRepository, M as VirtualTxRepository, ac as ExitCaptureMode, ad as ExitDataSource, h as ActivityRegistry, ae as IReadonlyAssetManager, af as ContractSyncState, ag as RecipientArkadeAddressContext, G as GetArkadeInfoOptions, A as ArkadeInfo, c as ArkadeReader, ah as NetworkName, ai as ArkAddress, e as WalletBalance, f as GetVtxosFilter, N as NormalizedExtendedVirtualCoin, aj as ContractWithVtxos, ak as selectPendingRecoveryOutpoints, g as ArkTransaction, i as Activity, E as ExtendedCoin, al as Coin, B as ExtendedVirtualCoin, am as ContractManager, an as ContractManagerConfig, I as IWallet, a as Identity, k as GetNewAddressesOptions, l as NewAddress, ao as SettlementConfig, d as ArkadeBroadcaster, q as IAssetManager, ap as VtxoManager, m as IDelegateManager, S as SendBitcoinParams, n as SettleParams, R as Recipient, aq as SignerSession, ar as SignedIntent, as as Intent, p as SendParams, at as TimeHeight } from './index-Udm5V2xW.js';
+import { w as RelativeTimelock, X as Network, Y as CSVMultisigTapscript, Z as BatchStartedEvent, _ as TreeSigningStartedEvent, $ as TxTree, a0 as TreeNoncesEvent, a1 as BatchFinalizationEvent, a2 as BatchFinalizedEvent, a3 as BatchFailedEvent, a4 as TreeTxEvent, a5 as TreeSignatureEvent, o as SettlementEvent, b as WalletConfig, W as WalletRepository, C as ContractRepository, a6 as DescriptorProvider, j as IContractManager, a7 as IReadonlyWallet, a8 as ReadonlyIdentity, a9 as OnchainProvider, u as ArkProvider, v as IndexerProvider, aa as DelegateProvider, ab as ReadonlyWalletConfig, J as IntentRepository, M as VirtualTxRepository, ac as ExitCaptureMode, ad as ExitDataSource, h as ActivityRegistry, ae as IReadonlyAssetManager, af as ContractSyncState, ag as RecipientArkadeAddressContext, G as GetArkadeInfoOptions, A as ArkadeInfo, c as ArkadeReader, ah as NetworkName, ai as ArkAddress, e as WalletBalance, f as GetVtxosFilter, N as NormalizedExtendedVirtualCoin, aj as ContractWithVtxos, ak as selectPendingRecoveryOutpoints, g as ArkTransaction, i as Activity, E as ExtendedCoin, al as Coin, B as ExtendedVirtualCoin, am as ContractManager, an as ContractManagerConfig, I as IWallet, a as Identity, k as GetNewAddressesOptions, l as NewAddress, ao as SettlementConfig, d as ArkadeBroadcaster, q as IAssetManager, ap as VtxoManager, m as IDelegateManager, S as SendBitcoinParams, n as SettleParams, R as Recipient, aq as SignerSession, ar as SignedIntent, as as Intent, p as SendParams, at as TimeHeight } from './index-DUxufw76.cjs';
 import { Transaction } from '@scure/btc-signer';
 import { TransactionOutput } from '@scure/btc-signer/psbt.js';
 import { Bytes } from '@scure/btc-signer/utils.js';
-import { D as DefaultVtxo, a as DelegateVtxo } from './delegate-Dyn5L80J.js';
+import { D as DefaultVtxo, a as DelegateVtxo } from './delegate-1yp1HyP7.cjs';
 
 /** Wall-clock floor for `batchExpiry` outside regtest. */
 declare const DEFAULT_MIN_BATCH_EXPIRY_SECONDS = 86400n;
@@ -2013,11 +2013,55 @@ declare function selectVirtualCoins(coins: ExtendedVirtualCoin[], targetAmount:
     changeAmount: bigint;
 };
 /**
- * Wait for incoming funds to the wallet
+ * Raised when a wait is cancelled through its `AbortSignal` or `timeoutMs`.
+ *
+ * `name` is `"AbortError"`, matching both the platform convention and the
+ * `error.name === "AbortError"` checks the provider layer already makes, so a
+ * caller can treat DOM and SDK aborts identically.
+ */
+declare class AbortError extends Error {
+    constructor(message?: string);
+}
+/** Options for {@link waitForIncomingFunds}. */
+interface WaitForIncomingFundsOptions {
+    /**
+     * Cancels the wait. On abort the underlying subscription is stopped and
+     * the returned promise rejects — with the signal's `reason` when the
+     * caller supplied an `Error`, otherwise an {@link AbortError}.
+     */
+    signal?: AbortSignal;
+    /**
+     * Cancels the wait after this many milliseconds, rejecting with an
+     * {@link AbortError}. Equivalent to passing an `AbortSignal.timeout`
+     * signal, without requiring that API on the target platform.
+     */
+    timeoutMs?: number;
+}
+/**
+ * Wait for incoming funds to the wallet.
+ *
+ * This opens live network watchers (an onchain address subscription plus the
+ * wallet's indexer stream) and keeps them open until it settles. **Cancel it
+ * if you are not going to await it to completion** — pass a `signal` or a
+ * `timeoutMs`. Racing an uncancelled call against a timer (`Promise.race`)
+ * abandons the loser without stopping its watchers, and repeating that in a
+ * loop stacks subscriptions until the process exits.
+ *
  * @param wallet - The wallet to wait for incoming funds
+ * @param options - Cancellation options; see {@link WaitForIncomingFundsOptions}
  * @returns A promise that resolves the next new coins received by the wallet's address
+ * @throws {AbortError} If cancelled via `signal` or `timeoutMs`
+ * @example
+ * ```typescript
+ * // Wake early on a deposit, but give up after 30s and release the watchers.
+ * try {
+ *   const funds = await waitForIncomingFunds(wallet, { timeoutMs: 30_000 })
+ * } catch (e) {
+ *   if ((e as Error).name !== "AbortError") throw e
+ * }
+ * ```
  */
-declare function waitForIncomingFunds(wallet: Wallet): Promise<IncomingFunds>;
+declare function waitForIncomingFunds(wallet: Wallet, options?: WaitForIncomingFundsOptions): Promise<IncomingFunds>;
 
 /**
  * Capability a wallet exposes so descriptor-blind consumers — Boltz swaps and
@@ -2185,4 +2229,4 @@ interface AddressAllocationCapable {
 /** Structural type guard for {@link AddressAllocationCapable}. */
 declare function isAddressAllocationCapable(value: unknown): value is AddressAllocationCapable;
 
-export { type AddressAllocationCapable as A, type BatchExpiryPolicy as B, type CheckpointExitDelayPolicy as C, DEFAULT_MIN_BATCH_EXPIRY_SECONDS as D, isArkError as E, ForeignDescriptorError as F, isHDAllocationCapable as G, type HDWalletCapable as H, type IncomingFunds as I, isHDWalletCapable as J, maybeArkError as K, resolveBatchExpiryPolicy as L, MAX_USED_SIGNING_DESCRIPTORS_LOOK_AHEAD as M, resolveCheckpointExitDelayPolicy as N, resolveDescriptorSigner as O, type ProviderConnectionState as P, selectVirtualCoins as Q, ReadonlyWallet as R, SIGNET_MIN_CHECKPOINT_EXIT_DELAY_SECONDS as S, signingDescriptorIndex as T, strictSigningDescriptorIndex as U, waitForIncomingFunds as V, Wallet as W, type HDAllocationCapable as a, type ReceiveRotatorFactory as b, type ReceiveRotatorBootOpts as c, type ReceiveRotatorBoot as d, Batch as e, ArkError as f, ArkErrorName as g, type ArkadeCashClaimResult as h, ArkadeCashCreateError as i, type ArkadeCashUnclaimedReason as j, type ArkadeCashUnclaimedVtxo as k, type BoardingUtxoGroup as l, DEFAULT_MIN_CHECKPOINT_EXIT_DELAY_SECONDS as m, MUTINYNET_MIN_CHECKPOINT_EXIT_DELAY_SECONDS as n, type ProviderKind as o, ProviderUnavailableError as p, REGTEST_MIN_BATCH_EXPIRY_SECONDS as q, REGTEST_MIN_CHECKPOINT_EXIT_DELAY_SECONDS as r, type ServerInfoSource as s, ServerResponseMismatchError as t, WalletCannotAllocateAddressError as u, assertValidBatchExpiry as v, assertValidServerUnrollScript as w, defaultBatchExpiryPolicy as x, defaultCheckpointExitDelayPolicy as y, isAddressAllocationCapable as z };
+export { type AddressAllocationCapable as A, type BatchExpiryPolicy as B, type CheckpointExitDelayPolicy as C, DEFAULT_MIN_BATCH_EXPIRY_SECONDS as D, defaultCheckpointExitDelayPolicy as E, ForeignDescriptorError as F, isAddressAllocationCapable as G, type HDWalletCapable as H, type IncomingFunds as I, isArkError as J, isHDAllocationCapable as K, isHDWalletCapable as L, MAX_USED_SIGNING_DESCRIPTORS_LOOK_AHEAD as M, maybeArkError as N, resolveBatchExpiryPolicy as O, type ProviderConnectionState as P, resolveCheckpointExitDelayPolicy as Q, ReadonlyWallet as R, SIGNET_MIN_CHECKPOINT_EXIT_DELAY_SECONDS as S, resolveDescriptorSigner as T, selectVirtualCoins as U, signingDescriptorIndex as V, Wallet as W, strictSigningDescriptorIndex as X, waitForIncomingFunds as Y, type HDAllocationCapable as a, type ReceiveRotatorFactory as b, type ReceiveRotatorBootOpts as c, type ReceiveRotatorBoot as d, Batch as e, AbortError as f, ArkError as g, ArkErrorName as h, type ArkadeCashClaimResult as i, ArkadeCashCreateError as j, type ArkadeCashUnclaimedReason as k, type ArkadeCashUnclaimedVtxo as l, type BoardingUtxoGroup as m, DEFAULT_MIN_CHECKPOINT_EXIT_DELAY_SECONDS as n, MUTINYNET_MIN_CHECKPOINT_EXIT_DELAY_SECONDS as o, type ProviderKind as p, ProviderUnavailableError as q, REGTEST_MIN_BATCH_EXPIRY_SECONDS as r, REGTEST_MIN_CHECKPOINT_EXIT_DELAY_SECONDS as s, type ServerInfoSource as t, ServerResponseMismatchError as u, type WaitForIncomingFundsOptions as v, WalletCannotAllocateAddressError as w, assertValidBatchExpiry as x, assertValidServerUnrollScript as y, defaultBatchExpiryPolicy as z };

package/dist/{index-D9tXd-tN.d.ts → index-Bem5vKzX.d.ts}

@@ -1,5 +1,5 @@
-import { bn as ContractHandler, w as RelativeTimelock, bz as Discoverable, V as VtxoScript, x as TapLeafScript, df as TapscriptDeriving } from './index-Udm5V2xW.js';
-import { D as DefaultVtxo, a as DelegateVtxo } from './delegate-Dyn5L80J.js';
+import { bn as ContractHandler, w as RelativeTimelock, bz as Discoverable, V as VtxoScript, x as TapLeafScript, df as TapscriptDeriving } from './index-DUxufw76.js';
+import { D as DefaultVtxo, a as DelegateVtxo } from './delegate-BAX5QftB.js';
 import { Bytes } from '@scure/btc-signer/utils.js';
 
 /**

package/dist/{index-Udm5V2xW.d.cts → index-DUxufw76.d.cts}

@@ -1730,6 +1730,8 @@ type ExplorerTransaction = {
     status: {
         confirmed: boolean;
         block_time: number;
+        /** Set by Esplora; the electrum provider omits it. */
+        block_height?: number;
     };
 };
 interface OnchainProvider {
@@ -1807,7 +1809,14 @@ interface OnchainProvider {
     /**
      * Fetch the current chain tip.
      *
-     * @returns Current chain height, block time, and block hash
+     * @returns Current chain height, median-time-past, and block hash
+     * @remarks
+     * `time` is the tip's **median-time-past**, not the header's own `nTime`.
+     * BIP-113 evaluates seconds-typed `OP_CHECKLOCKTIMEVERIFY` /
+     * `OP_CHECKSEQUENCEVERIFY` against MTP, which lags the tip by roughly an
+     * hour; the header time may sit two hours ahead of it. An implementation
+     * returning the header time calls a timelock mature before the network
+     * does — surfacing as a broadcast the node rejects, not as a bug here.
      */
     getChainTip(): Promise<{
         height: number;
@@ -1840,6 +1849,16 @@ declare class EsploraProvider implements OnchainProvider {
     private baseUrl;
     readonly pollingInterval: number;
     readonly forcePolling: boolean;
+    /**
+     * Live {@link watchAddresses} subscriptions, keyed by their address set.
+     *
+     * Concurrent watchers over the same addresses share one transport, so a
+     * caller that opens watchers in a loop — or leaks them by abandoning
+     * {@link waitForIncomingFunds} — costs one entry in a `Set` rather than
+     * another WebSocket plus another full-history polling loop. Entries are
+     * dropped once their last subscriber stops.
+     */
+    private readonly addressWatches;
     constructor(baseUrl?: string, opts?: {
         /** Polling interval in milliseconds. */
         pollingInterval?: number;
@@ -1854,6 +1873,12 @@ declare class EsploraProvider implements OnchainProvider {
         txid?: string;
     }[]>;
     getTransactions(address: string): Promise<ExplorerTransaction[]>;
+    /**
+     * Activity counts for an address, without its transactions — orders of
+     * magnitude smaller than `/address/{addr}/txs`, which is what makes it
+     * usable as a change probe for the polling fallback.
+     */
+    private getAddressStats;
     getRawTransaction(txid: string): Promise<Uint8Array>;
     getTxStatus(txid: string): Promise<{
         confirmed: false;
@@ -1862,7 +1887,34 @@ declare class EsploraProvider implements OnchainProvider {
         blockTime: number;
         blockHeight: number;
     }>;
+    /**
+     * Watch a set of addresses over the explorer's WebSocket, degrading to HTTP
+     * polling whenever the socket is unavailable and returning to the socket as
+     * soon as it can be re-established.
+     *
+     * Concurrent calls covering the same address set share one transport. The
+     * returned function releases **this** subscription only; the transport is
+     * torn down when the last subscriber releases it. Calling it more than once
+     * is a no-op.
+     *
+     * @param addresses - Addresses to monitor; order is not significant
+     * @param callback - Invoked with transactions seen after the watch started
+     * @returns A function releasing this subscription
+     * @remarks
+     * The HTTP fallback fetches full address history per address per cycle,
+     * which is dramatically more expensive than the socket — so callers should
+     * release watches they no longer need rather than relying on sharing.
+     * @see {@link waitForIncomingFunds} for the cancellation-aware wallet-level helper
+     */
     watchAddresses(addresses: string[], callback: (txs: ExplorerTransaction[]) => void): Promise<() => void>;
+    /**
+     * Bring up one shared address watch: a WebSocket subscription where the
+     * explorer supports it, degrading to HTTP polling when it doesn't.
+     *
+     * @param addresses - Addresses this watch covers
+     * @param onTeardown - Invoked when the watch retires, to drop the registry entry
+     */
+    private createAddressWatch;
     getChainTip(): Promise<{
         height: number;
         time: number;

package/dist/{index-Udm5V2xW.d.ts → index-DUxufw76.d.ts}

@@ -1730,6 +1730,8 @@ type ExplorerTransaction = {
     status: {
         confirmed: boolean;
         block_time: number;
+        /** Set by Esplora; the electrum provider omits it. */
+        block_height?: number;
     };
 };
 interface OnchainProvider {
@@ -1807,7 +1809,14 @@ interface OnchainProvider {
     /**
      * Fetch the current chain tip.
      *
-     * @returns Current chain height, block time, and block hash
+     * @returns Current chain height, median-time-past, and block hash
+     * @remarks
+     * `time` is the tip's **median-time-past**, not the header's own `nTime`.
+     * BIP-113 evaluates seconds-typed `OP_CHECKLOCKTIMEVERIFY` /
+     * `OP_CHECKSEQUENCEVERIFY` against MTP, which lags the tip by roughly an
+     * hour; the header time may sit two hours ahead of it. An implementation
+     * returning the header time calls a timelock mature before the network
+     * does — surfacing as a broadcast the node rejects, not as a bug here.
      */
     getChainTip(): Promise<{
         height: number;
@@ -1840,6 +1849,16 @@ declare class EsploraProvider implements OnchainProvider {
     private baseUrl;
     readonly pollingInterval: number;
     readonly forcePolling: boolean;
+    /**
+     * Live {@link watchAddresses} subscriptions, keyed by their address set.
+     *
+     * Concurrent watchers over the same addresses share one transport, so a
+     * caller that opens watchers in a loop — or leaks them by abandoning
+     * {@link waitForIncomingFunds} — costs one entry in a `Set` rather than
+     * another WebSocket plus another full-history polling loop. Entries are
+     * dropped once their last subscriber stops.
+     */
+    private readonly addressWatches;
     constructor(baseUrl?: string, opts?: {
         /** Polling interval in milliseconds. */
         pollingInterval?: number;
@@ -1854,6 +1873,12 @@ declare class EsploraProvider implements OnchainProvider {
         txid?: string;
     }[]>;
     getTransactions(address: string): Promise<ExplorerTransaction[]>;
+    /**
+     * Activity counts for an address, without its transactions — orders of
+     * magnitude smaller than `/address/{addr}/txs`, which is what makes it
+     * usable as a change probe for the polling fallback.
+     */
+    private getAddressStats;
     getRawTransaction(txid: string): Promise<Uint8Array>;
     getTxStatus(txid: string): Promise<{
         confirmed: false;
@@ -1862,7 +1887,34 @@ declare class EsploraProvider implements OnchainProvider {
         blockTime: number;
         blockHeight: number;
     }>;
+    /**
+     * Watch a set of addresses over the explorer's WebSocket, degrading to HTTP
+     * polling whenever the socket is unavailable and returning to the socket as
+     * soon as it can be re-established.
+     *
+     * Concurrent calls covering the same address set share one transport. The
+     * returned function releases **this** subscription only; the transport is
+     * torn down when the last subscriber releases it. Calling it more than once
+     * is a no-op.
+     *
+     * @param addresses - Addresses to monitor; order is not significant
+     * @param callback - Invoked with transactions seen after the watch started
+     * @returns A function releasing this subscription
+     * @remarks
+     * The HTTP fallback fetches full address history per address per cycle,
+     * which is dramatically more expensive than the socket — so callers should
+     * release watches they no longer need rather than relying on sharing.
+     * @see {@link waitForIncomingFunds} for the cancellation-aware wallet-level helper
+     */
     watchAddresses(addresses: string[], callback: (txs: ExplorerTransaction[]) => void): Promise<() => void>;
+    /**
+     * Bring up one shared address watch: a WebSocket subscription where the
+     * explorer supports it, degrading to HTTP polling when it doesn't.
+     *
+     * @param addresses - Addresses this watch covers
+     * @param onTeardown - Invoked when the watch retires, to drop the registry entry
+     */
+    private createAddressWatch;
     getChainTip(): Promise<{
         height: number;
         time: number;

package/dist/{index-D3hmsuKs.d.cts → index-W_oMcOmG.d.cts}

@@ -1,5 +1,5 @@
-import { bn as ContractHandler, w as RelativeTimelock, bz as Discoverable, V as VtxoScript, x as TapLeafScript, df as TapscriptDeriving } from './index-Udm5V2xW.cjs';
-import { D as DefaultVtxo, a as DelegateVtxo } from './delegate-DLIOBQ5x.cjs';
+import { bn as ContractHandler, w as RelativeTimelock, bz as Discoverable, V as VtxoScript, x as TapLeafScript, df as TapscriptDeriving } from './index-DUxufw76.cjs';
+import { D as DefaultVtxo, a as DelegateVtxo } from './delegate-1yp1HyP7.cjs';
 import { Bytes } from '@scure/btc-signer/utils.js';
 
 /**