@arkade-os/sdk 0.4.48 → 0.4.49

package/dist/adapters/expo.cjs

@@ -1,19 +1,19 @@
 'use strict';
 
-var chunkENDNQPZA_cjs = require('../chunk-ENDNQPZA.cjs');
-require('../chunk-EB3ALGTM.cjs');
-require('../chunk-7TXSPRN5.cjs');
+var chunkXOLH3LFO_cjs = require('../chunk-XOLH3LFO.cjs');
+require('../chunk-QDXQULVM.cjs');
+require('../chunk-E7HB3GKK.cjs');
 require('../chunk-5BLDMQED.cjs');
 
 
 
 Object.defineProperty(exports, "ExpoArkProvider", {
   enumerable: true,
-  get: function () { return chunkENDNQPZA_cjs.ExpoArkProvider; }
+  get: function () { return chunkXOLH3LFO_cjs.ExpoArkProvider; }
 });
 Object.defineProperty(exports, "ExpoIndexerProvider", {
   enumerable: true,
-  get: function () { return chunkENDNQPZA_cjs.ExpoIndexerProvider; }
+  get: function () { return chunkXOLH3LFO_cjs.ExpoIndexerProvider; }
 });
 //# sourceMappingURL=expo.cjs.map
 //# sourceMappingURL=expo.cjs.map

package/dist/adapters/expo.d.cts

@@ -1,5 +1,5 @@
-import { k as RestArkProvider, i as SettlementEvent, T as TxNotification, l as RestIndexerProvider, m as SubscriptionResponse } from '../ark-CjE0KkGp.cjs';
-export { n as ArkProvider, o as IndexerProvider } from '../ark-CjE0KkGp.cjs';
+import { k as RestArkProvider, i as SettlementEvent, T as TxNotification, l as RestIndexerProvider, m as SubscriptionResponse } from '../ark-nkSiPYNf.cjs';
+export { n as ArkProvider, o as IndexerProvider } from '../ark-nkSiPYNf.cjs';
 import '@scure/btc-signer/transaction.js';
 import '@scure/btc-signer/utils.js';
 import '@scure/btc-signer/psbt.js';

package/dist/adapters/expo.d.ts

@@ -1,5 +1,5 @@
-import { k as RestArkProvider, i as SettlementEvent, T as TxNotification, l as RestIndexerProvider, m as SubscriptionResponse } from '../ark-CjE0KkGp.js';
-export { n as ArkProvider, o as IndexerProvider } from '../ark-CjE0KkGp.js';
+import { k as RestArkProvider, i as SettlementEvent, T as TxNotification, l as RestIndexerProvider, m as SubscriptionResponse } from '../ark-nkSiPYNf.js';
+export { n as ArkProvider, o as IndexerProvider } from '../ark-nkSiPYNf.js';
 import '@scure/btc-signer/transaction.js';
 import '@scure/btc-signer/utils.js';
 import '@scure/btc-signer/psbt.js';

package/dist/adapters/expo.js

@@ -1,6 +1,6 @@
-export { ExpoArkProvider, ExpoIndexerProvider } from '../chunk-XFMGIFBL.js';
-import '../chunk-BHHLRZCS.js';
-import '../chunk-ZDDBTFVO.js';
+export { ExpoArkProvider, ExpoIndexerProvider } from '../chunk-HN25T276.js';
+import '../chunk-CPO2UB7L.js';
+import '../chunk-EFNLTS6Q.js';
 import '../chunk-NSBPE2FW.js';
 //# sourceMappingURL=expo.js.map
 //# sourceMappingURL=expo.js.map

package/dist/adapters/indexedDB.cjs

@@ -1,9 +1,9 @@
 'use strict';
 
-var chunkENZ4YPR2_cjs = require('../chunk-ENZ4YPR2.cjs');
-require('../chunk-EB3ALGTM.cjs');
-require('../chunk-5XMVTK5S.cjs');
-require('../chunk-7TXSPRN5.cjs');
+var chunk2LAJ3RTH_cjs = require('../chunk-2LAJ3RTH.cjs');
+require('../chunk-QDXQULVM.cjs');
+require('../chunk-LJQ2VQBE.cjs');
+require('../chunk-E7HB3GKK.cjs');
 require('../chunk-5BLDMQED.cjs');
 
 // src/storage/indexedDB.ts
@@ -11,7 +11,7 @@ var IndexedDBStorageAdapter = class {
   dbName;
   version;
   db = null;
-  constructor(dbName, version = chunkENZ4YPR2_cjs.DB_VERSION) {
+  constructor(dbName, version = chunk2LAJ3RTH_cjs.DB_VERSION) {
     this.dbName = dbName;
     this.version = version;
   }

package/dist/adapters/indexedDB.js

@@ -1,7 +1,7 @@
-import { DB_VERSION } from '../chunk-NYR5H6GR.js';
-import '../chunk-BHHLRZCS.js';
-import '../chunk-4VVTRPH3.js';
-import '../chunk-ZDDBTFVO.js';
+import { DB_VERSION } from '../chunk-5QVBJUOG.js';
+import '../chunk-CPO2UB7L.js';
+import '../chunk-MBSYQ3WX.js';
+import '../chunk-EFNLTS6Q.js';
 import '../chunk-NSBPE2FW.js';
 
 // src/storage/indexedDB.ts

package/dist/{ark-CjE0KkGp.d.cts → ark-nkSiPYNf.d.cts}

@@ -1912,12 +1912,19 @@ type RefreshVtxosOptions = {
     includeInactive?: boolean;
 };
 /**
- * A single `Discoverable` handler's `discoverAt` rejection, captured during
- * a {@link IContractManager.scanContracts} run instead of aborting the loop.
+ * A single `Discoverable` handler's discovery failure, captured during a
+ * {@link IContractManager.scanContracts} run instead of aborting the loop.
+ *
+ * TODO(next major): rename `index` → `fromIndex` so the pair reads
+ * `fromIndex`/`toIndex`. It stays `index` here only to keep this exported
+ * shape backward-compatible.
  */
 interface HandlerError {
     handler: string;
+    /** The failed index, or the first index of a failed `discoverRange` window. */
     index: number;
+    /** Inclusive end of a failed `discoverRange` window; absent for a single index. */
+    toIndex?: number;
     error: unknown;
 }
 /**
@@ -1941,7 +1948,7 @@ interface ScanResult {
      * when the scan closed a genuine gap.
      */
     truncatedAt?: number;
-    /** Per-handler `discoverAt` failures. Non-empty implies `truncatedAt` is set. */
+    /** Per-handler discovery failures. Non-empty implies `truncatedAt` is set. */
     handlerErrors: HandlerError[];
 }
 /**
@@ -1951,11 +1958,13 @@ interface ScanContractsOptions {
     /** Default 20. A non-positive / non-integer value throws. */
     gapLimit?: number;
     /**
-     * Number of HD indices probed concurrently per window (default
-     * {@link DEFAULT_SCAN_BATCH}). Pure latency knob: the gap loop stays
-     * gap-limit bounded and the discovered set is identical regardless of
-     * batch size. A non-positive / non-integer value throws. Ignored when
-     * `hd` is false (the static pass probes only index 0).
+     * Number of HD indices probed per window (default
+     * {@link DEFAULT_SCAN_BATCH}). The gap loop stays gap-limit bounded and
+     * the discovered set is identical regardless of batch size; the window is
+     * also the unit a batching handler ({@link Discoverable.discoverRange})
+     * collapses into one request, so it doubles as the batch width. A
+     * non-positive / non-integer value throws. Ignored when `hd` is false (the
+     * static pass probes only index 0).
      */
     batchSize?: number;
     /** HD mode → unbounded gap loop guided by the gap counter; false → probe only index 0 (single static pass). */
@@ -2092,11 +2101,12 @@ interface IContractManager extends Disposable {
      * resets the gap counter, so swap discovery keeps the HD window open.
      *
      * Error contract (safety-critical — see spec §4):
-     * - A handler's `discoverAt` rejecting is **collected** into
-     *   `handlerErrors` and makes its index *indeterminate*: it never
-     *   advances the gap counter, and the scan **stops verifying** there
-     *   rather than closing a window it never observed close. It still
-     *   never throws.
+     * - A handler's discovery rejecting is **collected** into `handlerErrors`
+     *   and makes its index *indeterminate*: it never advances the gap
+     *   counter, and the scan **stops verifying** there rather than closing a
+     *   window it never observed close. A batched
+     *   {@link Discoverable.discoverRange} failure makes its whole requested
+     *   range indeterminate. It still never throws.
      * - A fatal operational error — `materialize()` throwing, or
      *   `createContract` rejecting — **propagates** out of `scanContracts`
      *   (it invalidates the gap-window signal, so a silent truncation
@@ -2316,21 +2326,27 @@ declare class ContractManager implements IContractManager {
      * Safety-critical invariants (spec §2.C / §4):
      * - `opts.materialize(i)` throwing is structural/fatal: it is NOT
      *   wrapped — it propagates and aborts the scan.
-     * - A `discoverAt` rejection is collected into `handlerErrors` and makes
-     *   its index *indeterminate*: it does NOT advance the gap counter, and
-     *   the scan stops verifying there, reporting `truncatedAt`. Only an index
+     * - A discovery rejection is collected into `handlerErrors` and makes its
+     *   index *indeterminate*: it does NOT advance the gap counter, and the
+     *   scan stops verifying there, reporting `truncatedAt`. Only an index
      *   every handler answered for can be a confirmed miss.
      * - `persistAndWatchContract` rejecting is operational/fatal and
-     *   propagates (only `discoverAt` is guarded).
-     * - Within an index the handler probes run concurrently (independent
-     *   network reads); their hits are persisted sequentially in
-     *   `discoverables` order to preserve the first-wins collision tie-break.
-     * - Indices are probed `batchSize` at a time (a second concurrency layer
-     *   over the per-index probes), but each window is CAPPED to
+     *   propagates (only the handler calls are guarded).
+     * - A handler exposing {@link Discoverable.discoverRange} is asked for the
+     *   whole window in ONE call instead of one per index — the batching that
+     *   keeps a large restore from bursting into an operator's rate limiter.
+     *   Its failures are therefore range-wide: every index in the window goes
+     *   indeterminate and truncation lands on the window's first index. Its
+     *   answer must cover every requested index; an incomplete map is treated
+     *   as a rejection (see `Discoverable.discoverRange`).
+     * - Handlers are probed concurrently (independent network reads); their
+     *   hits are persisted sequentially in `discoverables` order to preserve
+     *   the first-wins collision tie-break.
+     * - Indices are probed `batchSize` at a time, but each window is CAPPED to
      *   `gapLimit - unused` indices — the most a serial scan could still reach
      *   before the gap window is guaranteed to close. So every index probed in
      *   a window is one a one-index-at-a-time scan would also reach: nothing is
-     *   over-scanned, nothing is discarded, and `materialize`/`discoverAt` are
+     *   over-scanned, nothing is discarded, and `materialize`/discovery are
      *   invoked on exactly the same index set. The window's hits are still
      *   processed strictly in ascending index order, so the discovered set,
      *   persisted rows, `highestConfirmedUsedIndex`, and `handlerErrors` are
@@ -2339,8 +2355,12 @@ declare class ContractManager implements IContractManager {
      *   can surface hits above the failed index that a serial scan would never
      *   have reached, so a truncated batched scan discovers a superset — never
      *   a subset — of the serial one.
+     * - The whole scan runs inside one coalesced subscription scope, so N
+     *   discovered contracts cost ONE `subscribeForScripts` instead of N
+     *   growing ones (see {@link ContractWatcher.withCoalescedSubscription}).
      */
     scanContracts(opts: ScanContractsOptions): Promise<ScanResult>;
+    private runScan;
     /**
      * Get contracts with optional filters.
      *
@@ -2770,6 +2790,27 @@ interface DiscoveryDeps {
  */
 interface Discoverable {
     discoverAt(index: number, descriptor: string, deps: DiscoveryDeps): Promise<DiscoveredContract[]>;
+    /**
+     * Optional: answer for a whole scan window in one batched round-trip.
+     * The scanner prefers it over per-index `discoverAt` calls when present,
+     * which is what keeps a 10-index window to 1-2 indexer requests instead
+     * of one per index. Handlers whose source is inherently per-address (e.g.
+     * boarding, on Esplora) implement only `discoverAt`.
+     *
+     * **All-or-nothing per call.** Either resolve with a map covering *every*
+     * requested index (empty array = confirmed miss), or reject — a handler
+     * whose inner chunk fails partway must discard the partial results and
+     * reject, because a missing index would otherwise read as "no funds here"
+     * and let restore close its gap window on a failed request. The scanner
+     * enforces this rather than trusting it: an incomplete map is treated as a
+     * rejection, making the whole requested range indeterminate (hits present
+     * in it are still persisted) and truncating the scan at the range's first
+     * index. Indices that were not requested are ignored.
+     */
+    discoverRange?(entries: readonly {
+        index: number;
+        descriptor: string;
+    }[], deps: DiscoveryDeps): Promise<Map<number, DiscoveredContract[]>>;
 }
 /** Duck-typed guard (mirrors `hasReceiveRotatorFactory`). */
 declare function isDiscoverable(handler: ContractHandler<unknown> | undefined): handler is ContractHandler<unknown> & Discoverable;
@@ -2931,6 +2972,9 @@ declare class ContractWatcher {
     private reconnectAttempts;
     private reconnectTimeoutId?;
     private failsafePollIntervalId?;
+    /** See {@link withCoalescedSubscription}. */
+    private subscriptionBatchDepth;
+    private subscriptionUpdateDeferred;
     /**
      * Create a contract watcher with the given providers and polling settings.
      *
@@ -3025,6 +3069,24 @@ declare class ContractWatcher {
      * Poll specific contracts and emit events for changes.
      */
     private pollContracts;
+    /**
+     * Run `fn` with subscription updates coalesced into a single
+     * `subscribeForScripts` on the way out.
+     *
+     * {@link addContract} re-subscribes eagerly (the watcher may already be
+     * running), and every subscribe posts the *whole* accumulated script list —
+     * so a restore scan that discovers N contracts sends N growing POSTs,
+     * quadratic in script-slots. Inside this scope those updates are only
+     * marked dirty, flushed once on the way out (success and error path alike).
+     *
+     * A contract added inside the scope is therefore not streaming until the
+     * flush. Nothing in the watcher closes that window — the failsafe poll
+     * replays repository state and cannot see VTXOs no one has fetched yet. The
+     * one caller, `scanContracts`, is covered because `Wallet.restore` follows
+     * it with a bulk `refreshVtxos`. A new caller must provide its own
+     * equivalent catch-up, or keep the scope short enough not to need one.
+     */
+    withCoalescedSubscription<T>(fn: () => Promise<T>): Promise<T>;
     private tryUpdateSubscription;
     /**
      * Update the subscription with scripts that should be watched.
@@ -4965,4 +5027,4 @@ declare namespace ProtoTypes {
     export {  };
 }
 
-export { type ReadonlyIdentity as $, type ArkTransaction as A, type VirtualTxRepository as B, type ContractRepository as C, type VirtualTx as D, type ExtendedCoin as E, type VtxoBranch as F, type GetVtxosFilter as G, ChainedTxType as H, type IWallet as I, type BatchStartedEvent as J, type TreeSigningStartedEvent as K, TxTree as L, type TreeNoncesEvent as M, type NormalizedExtendedVirtualCoin as N, type Outpoint as O, type BatchFinalizationEvent as P, type BatchFinalizedEvent as Q, type Recipient as R, type SendBitcoinParams as S, type TxNotification as T, type BatchFailedEvent as U, VtxoScript as V, type WalletRepository as W, type TreeTxEvent as X, type TreeSignatureEvent as Y, type DescriptorProvider as Z, type IReadonlyWallet as _, type Identity as a, ChainTxType as a$, type Network as a0, type OnchainProvider as a1, type DelegateProvider as a2, type ReadonlyWalletConfig as a3, type ExitCaptureMode as a4, type ExitDataSource as a5, type IReadonlyAssetManager as a6, type ContractSyncState as a7, type NetworkName as a8, type ArkInfo as a9, type BurnParams as aA, type RenewVtxosOptions as aB, type ContractWithVtxos as aC, type PathSelection as aD, type ContractEvent as aE, type AssetDetails as aF, type IssuanceResult as aG, type DelegateInfo as aH, type MigrationGlobalSkipReason as aI, type MigrationLegSkipReason as aJ, type SignerStatus as aK, type StorageConfig as aL, type IVtxoManager as aM, type ExplorerTransaction as aN, type EncodedVtxoScript as aO, type Status as aP, type ChainTx as aQ, type PathContext as aR, type ActivityIntent as aS, type ActivityResolver as aT, type ArkIntentState as aU, type ArkTapscript as aV, type AssetMetadata as aW, type BaseWalletConfig as aX, type BatchInfo as aY, type BatchSignableIdentity as aZ, CLTVMultisigTapscript as a_, ArkAddress as aa, type Coin as ab, ContractManager as ac, CSVMultisigTapscript as ad, type SettlementConfig as ae, VtxoManager as af, type SignerSession as ag, type SignedIntent as ah, Intent as ai, type TimeHeight as aj, type DescriptorSigningRequest as ak, Transaction as al, type IntentFeeConfig as am, type OffchainInput as an, FeeAmount as ao, type OnchainInput as ap, type FeeOutput as aq, type ContractWatcherConfig as ar, type Asset as as, type FeeInfo as at, type CreateContractParams as au, type GetContractsFilter as av, type GetSpendablePathsOptions as aw, type GetAllSpendingPathsOptions as ax, type IssuanceParams as ay, type ReissuanceParams as az, type WalletConfig as b, type VtxoChain as b$, type CommitmentTx as b0, ConditionCSVMultisigTapscript as b1, ConditionMultisigTapscript as b2, type ContractBalance as b3, type ContractEventCallback as b4, type ContractHandler as b5, type ContractManagerConfig as b6, type ContractState as b7, type ContractVtxo as b8, ContractWatcher as b9, type PageResponse as bA, type PaginationOptions as bB, PartialSig as bC, type ProviderClass as bD, RestDelegateProvider as bE, RestDelegatorProvider as bF, type ScanContractsOptions as bG, type ScanResult as bH, type ScheduledSession as bI, SettlementEventType as bJ, type SignRequest as bK, type SignerClassification as bL, type SignerSet as bM, type SubscriptionEvent as bN, type SubscriptionHeartbeat as bO, type TapLeaves as bP, TapTreeCoder as bQ, TapscriptType as bR, type TreeNonces as bS, type TreePartialSigs as bT, type Tx as bU, type TxHistoryRecord as bV, type TxKey as bW, type TxTreeNode as bX, TxType as bY, type VirtualStatus as bZ, type Vtxo as b_, DelegateManagerImpl as ba, type DelegateOptions as bb, DelegatorManagerImpl as bc, type DelegatorProvider as bd, type DeprecatedSignerMigrationReport as be, type DeprecatedSignerReport as bf, DigestMismatchError as bg, type Discoverable as bh, type DiscoveredContract as bi, type DiscoveryDeps as bj, ESPLORA_URL as bk, EsploraProvider as bl, type ExitChainResolver as bm, type ExtendedContractVtxo as bn, type GroupMembership as bo, type HandlerError as bp, type IDelegatorManager as bq, INTENT_TERMINAL_STATES as br, IndexerTxType as bs, type KnownMetadata as bt, type MigrateDeprecatedSignerOptions as bu, type MigrationLegReport as bv, type MigrationVtxoRef as bw, MultisigTapscript as bx, type Nonces as by, type Output as bz, type WalletBalance as c, type VtxoType as c0, type WalletMode as c1, boardingResolver as c2, canRecoverOnchain as c3, canSpendOffchain as c4, classifyAgainstSignerSet as c5, classifyContractSigner as c6, createDefaultActivityRegistry as c7, createExitChainResolver as c8, decodeTapscript as c9, getNetwork as ca, getSequence as cb, hasTerminalSpend as cc, isBatchSignable as cd, isCooperativelyMigratable as ce, isDiscoverable as cf, isExpired as cg, isPastExpiry as ch, isRecoverable as ci, isSpendable as cj, isSubdust as ck, isTerminalIntentState as cl, isVirtualCoin as cm, isVtxoExpiringSoon as cn, networks as co, signerSetFromInfo as cp, toXOnlySignerHex as cq, type TapscriptDeriving as cr, ActivityRegistry as d, type Activity as e, type IContractManager as f, type IDelegateManager as g, type SettleParams as h, type SettlementEvent as i, type IAssetManager as j, RestArkProvider as k, RestIndexerProvider as l, type SubscriptionResponse as m, type ArkProvider as n, type IndexerProvider as o, type RelativeTimelock as p, type TapLeafScript as q, type VirtualCoin as r, type Contract as s, type ExtendedVirtualCoin as t, type VtxoRepositoryKey as u, type WalletState as v, type ContractFilter as w, type IntentRepository as x, type ArkIntent as y, type IntentFilter as z };
+export { type NetworkName as $, type ArkTransaction as A, type BatchStartedEvent as B, type ContractRepository as C, type TreeTxEvent as D, type ExtendedCoin as E, type TreeSignatureEvent as F, type GetVtxosFilter as G, type DescriptorProvider as H, type IWallet as I, type IReadonlyWallet as J, type ReadonlyIdentity as K, type Network as L, type DelegateProvider as M, type NormalizedExtendedVirtualCoin as N, type OnchainProvider as O, type ReadonlyWalletConfig as P, type IntentRepository as Q, type Recipient as R, type SendBitcoinParams as S, type TxNotification as T, type VirtualTxRepository as U, VtxoScript as V, type WalletRepository as W, type ExitCaptureMode as X, type ExitDataSource as Y, type IReadonlyAssetManager as Z, type ContractSyncState as _, type Identity as a, ChainTxType as a$, type ArkInfo as a0, ArkAddress as a1, type Coin as a2, ContractManager as a3, CSVMultisigTapscript as a4, type SettlementConfig as a5, VtxoManager as a6, type SignerSession as a7, type SignedIntent as a8, Intent as a9, type BurnParams as aA, type RenewVtxosOptions as aB, type ContractWithVtxos as aC, type PathSelection as aD, type ContractEvent as aE, type AssetDetails as aF, type IssuanceResult as aG, type DelegateInfo as aH, type MigrationGlobalSkipReason as aI, type MigrationLegSkipReason as aJ, type SignerStatus as aK, type StorageConfig as aL, type IVtxoManager as aM, type ExplorerTransaction as aN, type EncodedVtxoScript as aO, type Status as aP, type ChainTx as aQ, type PathContext as aR, type ActivityIntent as aS, type ActivityResolver as aT, type ArkIntentState as aU, type ArkTapscript as aV, type AssetMetadata as aW, type BaseWalletConfig as aX, type BatchInfo as aY, type BatchSignableIdentity as aZ, CLTVMultisigTapscript as a_, type TimeHeight as aa, type VtxoRepositoryKey as ab, type WalletState as ac, type ContractFilter as ad, type ArkIntent as ae, type IntentFilter as af, type Outpoint as ag, type VirtualTx as ah, type VtxoBranch as ai, ChainedTxType as aj, type DescriptorSigningRequest as ak, Transaction as al, type IntentFeeConfig as am, type OffchainInput as an, FeeAmount as ao, type OnchainInput as ap, type FeeOutput as aq, type ContractWatcherConfig as ar, type Asset as as, type FeeInfo as at, type CreateContractParams as au, type GetContractsFilter as av, type GetSpendablePathsOptions as aw, type GetAllSpendingPathsOptions as ax, type IssuanceParams as ay, type ReissuanceParams as az, type WalletConfig as b, type VtxoChain as b$, type CommitmentTx as b0, ConditionCSVMultisigTapscript as b1, ConditionMultisigTapscript as b2, type ContractBalance as b3, type ContractEventCallback as b4, type ContractHandler as b5, type ContractManagerConfig as b6, type ContractState as b7, type ContractVtxo as b8, ContractWatcher as b9, type PageResponse as bA, type PaginationOptions as bB, PartialSig as bC, type ProviderClass as bD, RestDelegateProvider as bE, RestDelegatorProvider as bF, type ScanContractsOptions as bG, type ScanResult as bH, type ScheduledSession as bI, SettlementEventType as bJ, type SignRequest as bK, type SignerClassification as bL, type SignerSet as bM, type SubscriptionEvent as bN, type SubscriptionHeartbeat as bO, type TapLeaves as bP, TapTreeCoder as bQ, TapscriptType as bR, type TreeNonces as bS, type TreePartialSigs as bT, type Tx as bU, type TxHistoryRecord as bV, type TxKey as bW, type TxTreeNode as bX, TxType as bY, type VirtualStatus as bZ, type Vtxo as b_, DelegateManagerImpl as ba, type DelegateOptions as bb, DelegatorManagerImpl as bc, type DelegatorProvider as bd, type DeprecatedSignerMigrationReport as be, type DeprecatedSignerReport as bf, DigestMismatchError as bg, type Discoverable as bh, type DiscoveredContract as bi, type DiscoveryDeps as bj, ESPLORA_URL as bk, EsploraProvider as bl, type ExitChainResolver as bm, type ExtendedContractVtxo as bn, type GroupMembership as bo, type HandlerError as bp, type IDelegatorManager as bq, INTENT_TERMINAL_STATES as br, IndexerTxType as bs, type KnownMetadata as bt, type MigrateDeprecatedSignerOptions as bu, type MigrationLegReport as bv, type MigrationVtxoRef as bw, MultisigTapscript as bx, type Nonces as by, type Output as bz, type WalletBalance as c, type VtxoType as c0, type WalletMode as c1, boardingResolver as c2, canRecoverOnchain as c3, canSpendOffchain as c4, classifyAgainstSignerSet as c5, classifyContractSigner as c6, createDefaultActivityRegistry as c7, createExitChainResolver as c8, decodeTapscript as c9, getNetwork as ca, getSequence as cb, hasTerminalSpend as cc, isBatchSignable as cd, isCooperativelyMigratable as ce, isDiscoverable as cf, isExpired as cg, isPastExpiry as ch, isRecoverable as ci, isSpendable as cj, isSubdust as ck, isTerminalIntentState as cl, isVirtualCoin as cm, isVtxoExpiringSoon as cn, networks as co, signerSetFromInfo as cp, toXOnlySignerHex as cq, type TapscriptDeriving as cr, ActivityRegistry as d, type Activity as e, type IContractManager as f, type IDelegateManager as g, type SettleParams as h, type SettlementEvent as i, type IAssetManager as j, RestArkProvider as k, RestIndexerProvider as l, type SubscriptionResponse as m, type ArkProvider as n, type IndexerProvider as o, type RelativeTimelock as p, type TapLeafScript as q, type VirtualCoin as r, type Contract as s, type ExtendedVirtualCoin as t, type TreeSigningStartedEvent as u, TxTree as v, type TreeNoncesEvent as w, type BatchFinalizationEvent as x, type BatchFinalizedEvent as y, type BatchFailedEvent as z };

package/dist/{ark-CjE0KkGp.d.ts → ark-nkSiPYNf.d.ts}

@@ -1912,12 +1912,19 @@ type RefreshVtxosOptions = {
     includeInactive?: boolean;
 };
 /**
- * A single `Discoverable` handler's `discoverAt` rejection, captured during
- * a {@link IContractManager.scanContracts} run instead of aborting the loop.
+ * A single `Discoverable` handler's discovery failure, captured during a
+ * {@link IContractManager.scanContracts} run instead of aborting the loop.
+ *
+ * TODO(next major): rename `index` → `fromIndex` so the pair reads
+ * `fromIndex`/`toIndex`. It stays `index` here only to keep this exported
+ * shape backward-compatible.
  */
 interface HandlerError {
     handler: string;
+    /** The failed index, or the first index of a failed `discoverRange` window. */
     index: number;
+    /** Inclusive end of a failed `discoverRange` window; absent for a single index. */
+    toIndex?: number;
     error: unknown;
 }
 /**
@@ -1941,7 +1948,7 @@ interface ScanResult {
      * when the scan closed a genuine gap.
      */
     truncatedAt?: number;
-    /** Per-handler `discoverAt` failures. Non-empty implies `truncatedAt` is set. */
+    /** Per-handler discovery failures. Non-empty implies `truncatedAt` is set. */
     handlerErrors: HandlerError[];
 }
 /**
@@ -1951,11 +1958,13 @@ interface ScanContractsOptions {
     /** Default 20. A non-positive / non-integer value throws. */
     gapLimit?: number;
     /**
-     * Number of HD indices probed concurrently per window (default
-     * {@link DEFAULT_SCAN_BATCH}). Pure latency knob: the gap loop stays
-     * gap-limit bounded and the discovered set is identical regardless of
-     * batch size. A non-positive / non-integer value throws. Ignored when
-     * `hd` is false (the static pass probes only index 0).
+     * Number of HD indices probed per window (default
+     * {@link DEFAULT_SCAN_BATCH}). The gap loop stays gap-limit bounded and
+     * the discovered set is identical regardless of batch size; the window is
+     * also the unit a batching handler ({@link Discoverable.discoverRange})
+     * collapses into one request, so it doubles as the batch width. A
+     * non-positive / non-integer value throws. Ignored when `hd` is false (the
+     * static pass probes only index 0).
      */
     batchSize?: number;
     /** HD mode → unbounded gap loop guided by the gap counter; false → probe only index 0 (single static pass). */
@@ -2092,11 +2101,12 @@ interface IContractManager extends Disposable {
      * resets the gap counter, so swap discovery keeps the HD window open.
      *
      * Error contract (safety-critical — see spec §4):
-     * - A handler's `discoverAt` rejecting is **collected** into
-     *   `handlerErrors` and makes its index *indeterminate*: it never
-     *   advances the gap counter, and the scan **stops verifying** there
-     *   rather than closing a window it never observed close. It still
-     *   never throws.
+     * - A handler's discovery rejecting is **collected** into `handlerErrors`
+     *   and makes its index *indeterminate*: it never advances the gap
+     *   counter, and the scan **stops verifying** there rather than closing a
+     *   window it never observed close. A batched
+     *   {@link Discoverable.discoverRange} failure makes its whole requested
+     *   range indeterminate. It still never throws.
      * - A fatal operational error — `materialize()` throwing, or
      *   `createContract` rejecting — **propagates** out of `scanContracts`
      *   (it invalidates the gap-window signal, so a silent truncation
@@ -2316,21 +2326,27 @@ declare class ContractManager implements IContractManager {
      * Safety-critical invariants (spec §2.C / §4):
      * - `opts.materialize(i)` throwing is structural/fatal: it is NOT
      *   wrapped — it propagates and aborts the scan.
-     * - A `discoverAt` rejection is collected into `handlerErrors` and makes
-     *   its index *indeterminate*: it does NOT advance the gap counter, and
-     *   the scan stops verifying there, reporting `truncatedAt`. Only an index
+     * - A discovery rejection is collected into `handlerErrors` and makes its
+     *   index *indeterminate*: it does NOT advance the gap counter, and the
+     *   scan stops verifying there, reporting `truncatedAt`. Only an index
      *   every handler answered for can be a confirmed miss.
      * - `persistAndWatchContract` rejecting is operational/fatal and
-     *   propagates (only `discoverAt` is guarded).
-     * - Within an index the handler probes run concurrently (independent
-     *   network reads); their hits are persisted sequentially in
-     *   `discoverables` order to preserve the first-wins collision tie-break.
-     * - Indices are probed `batchSize` at a time (a second concurrency layer
-     *   over the per-index probes), but each window is CAPPED to
+     *   propagates (only the handler calls are guarded).
+     * - A handler exposing {@link Discoverable.discoverRange} is asked for the
+     *   whole window in ONE call instead of one per index — the batching that
+     *   keeps a large restore from bursting into an operator's rate limiter.
+     *   Its failures are therefore range-wide: every index in the window goes
+     *   indeterminate and truncation lands on the window's first index. Its
+     *   answer must cover every requested index; an incomplete map is treated
+     *   as a rejection (see `Discoverable.discoverRange`).
+     * - Handlers are probed concurrently (independent network reads); their
+     *   hits are persisted sequentially in `discoverables` order to preserve
+     *   the first-wins collision tie-break.
+     * - Indices are probed `batchSize` at a time, but each window is CAPPED to
      *   `gapLimit - unused` indices — the most a serial scan could still reach
      *   before the gap window is guaranteed to close. So every index probed in
      *   a window is one a one-index-at-a-time scan would also reach: nothing is
-     *   over-scanned, nothing is discarded, and `materialize`/`discoverAt` are
+     *   over-scanned, nothing is discarded, and `materialize`/discovery are
      *   invoked on exactly the same index set. The window's hits are still
      *   processed strictly in ascending index order, so the discovered set,
      *   persisted rows, `highestConfirmedUsedIndex`, and `handlerErrors` are
@@ -2339,8 +2355,12 @@ declare class ContractManager implements IContractManager {
      *   can surface hits above the failed index that a serial scan would never
      *   have reached, so a truncated batched scan discovers a superset — never
      *   a subset — of the serial one.
+     * - The whole scan runs inside one coalesced subscription scope, so N
+     *   discovered contracts cost ONE `subscribeForScripts` instead of N
+     *   growing ones (see {@link ContractWatcher.withCoalescedSubscription}).
      */
     scanContracts(opts: ScanContractsOptions): Promise<ScanResult>;
+    private runScan;
     /**
      * Get contracts with optional filters.
      *
@@ -2770,6 +2790,27 @@ interface DiscoveryDeps {
  */
 interface Discoverable {
     discoverAt(index: number, descriptor: string, deps: DiscoveryDeps): Promise<DiscoveredContract[]>;
+    /**
+     * Optional: answer for a whole scan window in one batched round-trip.
+     * The scanner prefers it over per-index `discoverAt` calls when present,
+     * which is what keeps a 10-index window to 1-2 indexer requests instead
+     * of one per index. Handlers whose source is inherently per-address (e.g.
+     * boarding, on Esplora) implement only `discoverAt`.
+     *
+     * **All-or-nothing per call.** Either resolve with a map covering *every*
+     * requested index (empty array = confirmed miss), or reject — a handler
+     * whose inner chunk fails partway must discard the partial results and
+     * reject, because a missing index would otherwise read as "no funds here"
+     * and let restore close its gap window on a failed request. The scanner
+     * enforces this rather than trusting it: an incomplete map is treated as a
+     * rejection, making the whole requested range indeterminate (hits present
+     * in it are still persisted) and truncating the scan at the range's first
+     * index. Indices that were not requested are ignored.
+     */
+    discoverRange?(entries: readonly {
+        index: number;
+        descriptor: string;
+    }[], deps: DiscoveryDeps): Promise<Map<number, DiscoveredContract[]>>;
 }
 /** Duck-typed guard (mirrors `hasReceiveRotatorFactory`). */
 declare function isDiscoverable(handler: ContractHandler<unknown> | undefined): handler is ContractHandler<unknown> & Discoverable;
@@ -2931,6 +2972,9 @@ declare class ContractWatcher {
     private reconnectAttempts;
     private reconnectTimeoutId?;
     private failsafePollIntervalId?;
+    /** See {@link withCoalescedSubscription}. */
+    private subscriptionBatchDepth;
+    private subscriptionUpdateDeferred;
     /**
      * Create a contract watcher with the given providers and polling settings.
      *
@@ -3025,6 +3069,24 @@ declare class ContractWatcher {
      * Poll specific contracts and emit events for changes.
      */
     private pollContracts;
+    /**
+     * Run `fn` with subscription updates coalesced into a single
+     * `subscribeForScripts` on the way out.
+     *
+     * {@link addContract} re-subscribes eagerly (the watcher may already be
+     * running), and every subscribe posts the *whole* accumulated script list —
+     * so a restore scan that discovers N contracts sends N growing POSTs,
+     * quadratic in script-slots. Inside this scope those updates are only
+     * marked dirty, flushed once on the way out (success and error path alike).
+     *
+     * A contract added inside the scope is therefore not streaming until the
+     * flush. Nothing in the watcher closes that window — the failsafe poll
+     * replays repository state and cannot see VTXOs no one has fetched yet. The
+     * one caller, `scanContracts`, is covered because `Wallet.restore` follows
+     * it with a bulk `refreshVtxos`. A new caller must provide its own
+     * equivalent catch-up, or keep the scope short enough not to need one.
+     */
+    withCoalescedSubscription<T>(fn: () => Promise<T>): Promise<T>;
     private tryUpdateSubscription;
     /**
      * Update the subscription with scripts that should be watched.
@@ -4965,4 +5027,4 @@ declare namespace ProtoTypes {
     export {  };
 }
 
-export { type ReadonlyIdentity as $, type ArkTransaction as A, type VirtualTxRepository as B, type ContractRepository as C, type VirtualTx as D, type ExtendedCoin as E, type VtxoBranch as F, type GetVtxosFilter as G, ChainedTxType as H, type IWallet as I, type BatchStartedEvent as J, type TreeSigningStartedEvent as K, TxTree as L, type TreeNoncesEvent as M, type NormalizedExtendedVirtualCoin as N, type Outpoint as O, type BatchFinalizationEvent as P, type BatchFinalizedEvent as Q, type Recipient as R, type SendBitcoinParams as S, type TxNotification as T, type BatchFailedEvent as U, VtxoScript as V, type WalletRepository as W, type TreeTxEvent as X, type TreeSignatureEvent as Y, type DescriptorProvider as Z, type IReadonlyWallet as _, type Identity as a, ChainTxType as a$, type Network as a0, type OnchainProvider as a1, type DelegateProvider as a2, type ReadonlyWalletConfig as a3, type ExitCaptureMode as a4, type ExitDataSource as a5, type IReadonlyAssetManager as a6, type ContractSyncState as a7, type NetworkName as a8, type ArkInfo as a9, type BurnParams as aA, type RenewVtxosOptions as aB, type ContractWithVtxos as aC, type PathSelection as aD, type ContractEvent as aE, type AssetDetails as aF, type IssuanceResult as aG, type DelegateInfo as aH, type MigrationGlobalSkipReason as aI, type MigrationLegSkipReason as aJ, type SignerStatus as aK, type StorageConfig as aL, type IVtxoManager as aM, type ExplorerTransaction as aN, type EncodedVtxoScript as aO, type Status as aP, type ChainTx as aQ, type PathContext as aR, type ActivityIntent as aS, type ActivityResolver as aT, type ArkIntentState as aU, type ArkTapscript as aV, type AssetMetadata as aW, type BaseWalletConfig as aX, type BatchInfo as aY, type BatchSignableIdentity as aZ, CLTVMultisigTapscript as a_, ArkAddress as aa, type Coin as ab, ContractManager as ac, CSVMultisigTapscript as ad, type SettlementConfig as ae, VtxoManager as af, type SignerSession as ag, type SignedIntent as ah, Intent as ai, type TimeHeight as aj, type DescriptorSigningRequest as ak, Transaction as al, type IntentFeeConfig as am, type OffchainInput as an, FeeAmount as ao, type OnchainInput as ap, type FeeOutput as aq, type ContractWatcherConfig as ar, type Asset as as, type FeeInfo as at, type CreateContractParams as au, type GetContractsFilter as av, type GetSpendablePathsOptions as aw, type GetAllSpendingPathsOptions as ax, type IssuanceParams as ay, type ReissuanceParams as az, type WalletConfig as b, type VtxoChain as b$, type CommitmentTx as b0, ConditionCSVMultisigTapscript as b1, ConditionMultisigTapscript as b2, type ContractBalance as b3, type ContractEventCallback as b4, type ContractHandler as b5, type ContractManagerConfig as b6, type ContractState as b7, type ContractVtxo as b8, ContractWatcher as b9, type PageResponse as bA, type PaginationOptions as bB, PartialSig as bC, type ProviderClass as bD, RestDelegateProvider as bE, RestDelegatorProvider as bF, type ScanContractsOptions as bG, type ScanResult as bH, type ScheduledSession as bI, SettlementEventType as bJ, type SignRequest as bK, type SignerClassification as bL, type SignerSet as bM, type SubscriptionEvent as bN, type SubscriptionHeartbeat as bO, type TapLeaves as bP, TapTreeCoder as bQ, TapscriptType as bR, type TreeNonces as bS, type TreePartialSigs as bT, type Tx as bU, type TxHistoryRecord as bV, type TxKey as bW, type TxTreeNode as bX, TxType as bY, type VirtualStatus as bZ, type Vtxo as b_, DelegateManagerImpl as ba, type DelegateOptions as bb, DelegatorManagerImpl as bc, type DelegatorProvider as bd, type DeprecatedSignerMigrationReport as be, type DeprecatedSignerReport as bf, DigestMismatchError as bg, type Discoverable as bh, type DiscoveredContract as bi, type DiscoveryDeps as bj, ESPLORA_URL as bk, EsploraProvider as bl, type ExitChainResolver as bm, type ExtendedContractVtxo as bn, type GroupMembership as bo, type HandlerError as bp, type IDelegatorManager as bq, INTENT_TERMINAL_STATES as br, IndexerTxType as bs, type KnownMetadata as bt, type MigrateDeprecatedSignerOptions as bu, type MigrationLegReport as bv, type MigrationVtxoRef as bw, MultisigTapscript as bx, type Nonces as by, type Output as bz, type WalletBalance as c, type VtxoType as c0, type WalletMode as c1, boardingResolver as c2, canRecoverOnchain as c3, canSpendOffchain as c4, classifyAgainstSignerSet as c5, classifyContractSigner as c6, createDefaultActivityRegistry as c7, createExitChainResolver as c8, decodeTapscript as c9, getNetwork as ca, getSequence as cb, hasTerminalSpend as cc, isBatchSignable as cd, isCooperativelyMigratable as ce, isDiscoverable as cf, isExpired as cg, isPastExpiry as ch, isRecoverable as ci, isSpendable as cj, isSubdust as ck, isTerminalIntentState as cl, isVirtualCoin as cm, isVtxoExpiringSoon as cn, networks as co, signerSetFromInfo as cp, toXOnlySignerHex as cq, type TapscriptDeriving as cr, ActivityRegistry as d, type Activity as e, type IContractManager as f, type IDelegateManager as g, type SettleParams as h, type SettlementEvent as i, type IAssetManager as j, RestArkProvider as k, RestIndexerProvider as l, type SubscriptionResponse as m, type ArkProvider as n, type IndexerProvider as o, type RelativeTimelock as p, type TapLeafScript as q, type VirtualCoin as r, type Contract as s, type ExtendedVirtualCoin as t, type VtxoRepositoryKey as u, type WalletState as v, type ContractFilter as w, type IntentRepository as x, type ArkIntent as y, type IntentFilter as z };
+export { type NetworkName as $, type ArkTransaction as A, type BatchStartedEvent as B, type ContractRepository as C, type TreeTxEvent as D, type ExtendedCoin as E, type TreeSignatureEvent as F, type GetVtxosFilter as G, type DescriptorProvider as H, type IWallet as I, type IReadonlyWallet as J, type ReadonlyIdentity as K, type Network as L, type DelegateProvider as M, type NormalizedExtendedVirtualCoin as N, type OnchainProvider as O, type ReadonlyWalletConfig as P, type IntentRepository as Q, type Recipient as R, type SendBitcoinParams as S, type TxNotification as T, type VirtualTxRepository as U, VtxoScript as V, type WalletRepository as W, type ExitCaptureMode as X, type ExitDataSource as Y, type IReadonlyAssetManager as Z, type ContractSyncState as _, type Identity as a, ChainTxType as a$, type ArkInfo as a0, ArkAddress as a1, type Coin as a2, ContractManager as a3, CSVMultisigTapscript as a4, type SettlementConfig as a5, VtxoManager as a6, type SignerSession as a7, type SignedIntent as a8, Intent as a9, type BurnParams as aA, type RenewVtxosOptions as aB, type ContractWithVtxos as aC, type PathSelection as aD, type ContractEvent as aE, type AssetDetails as aF, type IssuanceResult as aG, type DelegateInfo as aH, type MigrationGlobalSkipReason as aI, type MigrationLegSkipReason as aJ, type SignerStatus as aK, type StorageConfig as aL, type IVtxoManager as aM, type ExplorerTransaction as aN, type EncodedVtxoScript as aO, type Status as aP, type ChainTx as aQ, type PathContext as aR, type ActivityIntent as aS, type ActivityResolver as aT, type ArkIntentState as aU, type ArkTapscript as aV, type AssetMetadata as aW, type BaseWalletConfig as aX, type BatchInfo as aY, type BatchSignableIdentity as aZ, CLTVMultisigTapscript as a_, type TimeHeight as aa, type VtxoRepositoryKey as ab, type WalletState as ac, type ContractFilter as ad, type ArkIntent as ae, type IntentFilter as af, type Outpoint as ag, type VirtualTx as ah, type VtxoBranch as ai, ChainedTxType as aj, type DescriptorSigningRequest as ak, Transaction as al, type IntentFeeConfig as am, type OffchainInput as an, FeeAmount as ao, type OnchainInput as ap, type FeeOutput as aq, type ContractWatcherConfig as ar, type Asset as as, type FeeInfo as at, type CreateContractParams as au, type GetContractsFilter as av, type GetSpendablePathsOptions as aw, type GetAllSpendingPathsOptions as ax, type IssuanceParams as ay, type ReissuanceParams as az, type WalletConfig as b, type VtxoChain as b$, type CommitmentTx as b0, ConditionCSVMultisigTapscript as b1, ConditionMultisigTapscript as b2, type ContractBalance as b3, type ContractEventCallback as b4, type ContractHandler as b5, type ContractManagerConfig as b6, type ContractState as b7, type ContractVtxo as b8, ContractWatcher as b9, type PageResponse as bA, type PaginationOptions as bB, PartialSig as bC, type ProviderClass as bD, RestDelegateProvider as bE, RestDelegatorProvider as bF, type ScanContractsOptions as bG, type ScanResult as bH, type ScheduledSession as bI, SettlementEventType as bJ, type SignRequest as bK, type SignerClassification as bL, type SignerSet as bM, type SubscriptionEvent as bN, type SubscriptionHeartbeat as bO, type TapLeaves as bP, TapTreeCoder as bQ, TapscriptType as bR, type TreeNonces as bS, type TreePartialSigs as bT, type Tx as bU, type TxHistoryRecord as bV, type TxKey as bW, type TxTreeNode as bX, TxType as bY, type VirtualStatus as bZ, type Vtxo as b_, DelegateManagerImpl as ba, type DelegateOptions as bb, DelegatorManagerImpl as bc, type DelegatorProvider as bd, type DeprecatedSignerMigrationReport as be, type DeprecatedSignerReport as bf, DigestMismatchError as bg, type Discoverable as bh, type DiscoveredContract as bi, type DiscoveryDeps as bj, ESPLORA_URL as bk, EsploraProvider as bl, type ExitChainResolver as bm, type ExtendedContractVtxo as bn, type GroupMembership as bo, type HandlerError as bp, type IDelegatorManager as bq, INTENT_TERMINAL_STATES as br, IndexerTxType as bs, type KnownMetadata as bt, type MigrateDeprecatedSignerOptions as bu, type MigrationLegReport as bv, type MigrationVtxoRef as bw, MultisigTapscript as bx, type Nonces as by, type Output as bz, type WalletBalance as c, type VtxoType as c0, type WalletMode as c1, boardingResolver as c2, canRecoverOnchain as c3, canSpendOffchain as c4, classifyAgainstSignerSet as c5, classifyContractSigner as c6, createDefaultActivityRegistry as c7, createExitChainResolver as c8, decodeTapscript as c9, getNetwork as ca, getSequence as cb, hasTerminalSpend as cc, isBatchSignable as cd, isCooperativelyMigratable as ce, isDiscoverable as cf, isExpired as cg, isPastExpiry as ch, isRecoverable as ci, isSpendable as cj, isSubdust as ck, isTerminalIntentState as cl, isVirtualCoin as cm, isVtxoExpiringSoon as cn, networks as co, signerSetFromInfo as cp, toXOnlySignerHex as cq, type TapscriptDeriving as cr, ActivityRegistry as d, type Activity as e, type IContractManager as f, type IDelegateManager as g, type SettleParams as h, type SettlementEvent as i, type IAssetManager as j, RestArkProvider as k, RestIndexerProvider as l, type SubscriptionResponse as m, type ArkProvider as n, type IndexerProvider as o, type RelativeTimelock as p, type TapLeafScript as q, type VirtualCoin as r, type Contract as s, type ExtendedVirtualCoin as t, type TreeSigningStartedEvent as u, TxTree as v, type TreeNoncesEvent as w, type BatchFinalizationEvent as x, type BatchFinalizedEvent as y, type BatchFailedEvent as z };

package/dist/{asyncStorageTaskQueue-D9SOPMPC.d.ts → asyncStorageTaskQueue-DCaEE83p.d.ts}

@@ -1,4 +1,4 @@
-import { a as TaskQueue, c as TaskItem, d as TaskResult } from './taskRunner-B-2MHCYG.js';
+import { a as TaskQueue, c as TaskItem, d as TaskResult } from './taskRunner-Dw7xs60Q.js';
 
 /**
  * Minimal async key-value storage interface.

package/dist/{asyncStorageTaskQueue-CeLZhZFU.d.cts → asyncStorageTaskQueue-DdxhsEz6.d.cts}

@@ -1,4 +1,4 @@
-import { a as TaskQueue, c as TaskItem, d as TaskResult } from './taskRunner-Brnak0Rc.cjs';
+import { a as TaskQueue, c as TaskItem, d as TaskResult } from './taskRunner-BjB5QINR.cjs';
 
 /**
  * Minimal async key-value storage interface.