@arkade-os/sdk 0.4.50 → 0.4.51

package/README.md

@@ -1247,9 +1247,33 @@ This is required for MuSig2 settlements and cryptographic operations.
 
 ### Contract Management
 
-Both `Wallet` and `ServiceWorkerWallet` use a `ContractManager` internally to watch for virtual outputs. This provides resilient connection handling with automatic reconnection and failsafe polling - for your wallet's default address and any external contracts you register (Boltz swaps, HTLCs, etc.).
+Both `Wallet` and `ServiceWorkerWallet` use a `ContractManager` internally to watch for virtual outputs and persist them into repositories. This provides resilient connection handling with automatic reconnection and failsafe polling - for your wallet's default address and any external contracts you register (Boltz swaps, HTLCs, etc.).
 
-When you call `wallet.notifyIncomingFunds()` or use `waitForIncomingFunds()`, it uses the ContractManager under the hood, giving you automatic reconnection and failsafe polling for free - no code changes needed.
+When you call `wallet.notifyIncomingFunds()` or use `waitForIncomingFunds()`, it uses the ContractManager under the hood, giving you automatic reconnection and repository-backed event replay for free - no code changes needed.
+
+`watcherConfig.failsafePollIntervalMs` (default `20_000`) controls how often the watcher replays repository changes into contract events; it does not fetch fresh VTXOs from the indexer.
+
+#### HD look-ahead window
+
+HD wallets (`walletMode: 'hd'`, or an explicit HD `DescriptorProvider`) also watch a band of *unused* offchain receive scripts around their allocation watermark, so a payment to an address that some other party issued from the same seed — a merchant backend such as BTCPay Server — arrives without the user calling `restore()`. `lookAheadWindow` (default `20`) is the per-side width of that band: the wallet watches `[watermark - N, watermark + N]`. Speculative entries are subscription-only; they become contract rows, and enter balances, only once funded.
+
+```typescript
+const wallet = await Wallet.create({
+  identity,
+  walletMode: 'hd',
+  lookAheadWindow: 50,  // issuer hands out long runs of unpaid invoices
+})
+
+// Same option on the service-worker wallet; it is forwarded to the worker's inner wallet.
+const swWallet = await ServiceWorkerWallet.setup({
+  serviceWorkerPath: '/service-worker.js',
+  identity,
+  walletMode: 'hd',
+  lookAheadWindow: 50,
+})
+```
+
+Raise it when the external issuer is expected to burn more than `N` consecutive addresses without any of them being paid — every index in such a run is a miss, and the funded one sits past the band. When that happens the funds are invisible until a `restore()` whose `gapLimit` is large enough to cross the run (`wallet.restore({ gapLimit: 200 })`); a default restore closes its gap window before reaching the funded index. Keep the value modest: the band adds up to `2N + 1` script filters to the wallet's subscription.
 
 For advanced use cases, you can access the ContractManager directly to register external contracts:
 
@@ -1312,21 +1336,22 @@ const allPaths = await manager.getAllSpendingPaths({
 // Fetch contracts together with their current virtual outputs
 const contractsWithVtxos = await manager.getContractsWithVtxos()
 
-// Force a full refresh from the indexer when needed
+// Force an indexer refresh of the watched contracts when needed
 await manager.refreshVtxos()
 
 // Stop watching
 unsubscribe()
 ```
 
-The watcher features:
-- **Automatic reconnection** with exponential backoff (1s → 30s max)
-- **Failsafe polling** every 60 seconds to catch missed events
-- **Immediate sync** on connection and after failures
+Contract freshness behavior:
+- **Automatic reconnection** with exponential backoff (1s → 5s max)
+- **Immediate sync** on manager initialization, subscription reconnect, and contract events
+- **Failsafe polling** every 20 seconds by default to catch missed events, configurable via `watcherConfig.failsafePollIntervalMs`
+- **Manual refresh** through `manager.refreshVtxos()`; pass `{ includeInactive: true }` to sweep every repository contract
 
 ### Repository Pattern
 
-Most users don't need to touch repositories directly — `Wallet` and `ContractManager` already read and write through them. They are documented here for advanced integrations (custom storage backends, offline-first apps, repository inspection).
+Most users don't need to touch repositories directly — `Wallet` reads through them and `ContractManager` owns VTXO/contract synchronization into them. They are documented here for advanced integrations (custom storage backends, offline-first apps, repository inspection).
 
 ```typescript
 // Wallet repository — VTXOs, UTXOs, transaction history, settings

package/dist/adapters/expo.cjs

@@ -1,7 +1,7 @@
 'use strict';
 
-var chunkTO3SR7TY_cjs = require('../chunk-TO3SR7TY.cjs');
-require('../chunk-SIAVTHMZ.cjs');
+var chunk5AT2NV5G_cjs = require('../chunk-5AT2NV5G.cjs');
+require('../chunk-FHDUEBBC.cjs');
 require('../chunk-E7HB3GKK.cjs');
 require('../chunk-5BLDMQED.cjs');
 
@@ -9,11 +9,11 @@ require('../chunk-5BLDMQED.cjs');
 
 Object.defineProperty(exports, "ExpoArkProvider", {
   enumerable: true,
-  get: function () { return chunkTO3SR7TY_cjs.ExpoArkProvider; }
+  get: function () { return chunk5AT2NV5G_cjs.ExpoArkProvider; }
 });
 Object.defineProperty(exports, "ExpoIndexerProvider", {
   enumerable: true,
-  get: function () { return chunkTO3SR7TY_cjs.ExpoIndexerProvider; }
+  get: function () { return chunk5AT2NV5G_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-ApoclKQZ.cjs';
-export { n as ArkProvider, o as IndexerProvider } from '../ark-ApoclKQZ.cjs';
+import { k as RestArkProvider, i as SettlementEvent, T as TxNotification, l as RestIndexerProvider, m as SubscriptionResponse } from '../ark-9V45Anrs.cjs';
+export { n as ArkProvider, o as IndexerProvider } from '../ark-9V45Anrs.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-ApoclKQZ.js';
-export { n as ArkProvider, o as IndexerProvider } from '../ark-ApoclKQZ.js';
+import { k as RestArkProvider, i as SettlementEvent, T as TxNotification, l as RestIndexerProvider, m as SubscriptionResponse } from '../ark-9V45Anrs.js';
+export { n as ArkProvider, o as IndexerProvider } from '../ark-9V45Anrs.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,5 +1,5 @@
-export { ExpoArkProvider, ExpoIndexerProvider } from '../chunk-ZXRSSBCF.js';
-import '../chunk-AA4Q2J57.js';
+export { ExpoArkProvider, ExpoIndexerProvider } from '../chunk-6T5BBPKO.js';
+import '../chunk-3AOTJZQ4.js';
 import '../chunk-EFNLTS6Q.js';
 import '../chunk-NSBPE2FW.js';
 //# sourceMappingURL=expo.js.map

package/dist/adapters/indexedDB.cjs

@@ -1,7 +1,7 @@
 'use strict';
 
-var chunk6BQTROB4_cjs = require('../chunk-6BQTROB4.cjs');
-require('../chunk-SIAVTHMZ.cjs');
+var chunk6XF6ZATZ_cjs = require('../chunk-6XF6ZATZ.cjs');
+require('../chunk-FHDUEBBC.cjs');
 require('../chunk-LJQ2VQBE.cjs');
 require('../chunk-E7HB3GKK.cjs');
 require('../chunk-5BLDMQED.cjs');
@@ -11,7 +11,7 @@ var IndexedDBStorageAdapter = class {
   dbName;
   version;
   db = null;
-  constructor(dbName, version = chunk6BQTROB4_cjs.DB_VERSION) {
+  constructor(dbName, version = chunk6XF6ZATZ_cjs.DB_VERSION) {
     this.dbName = dbName;
     this.version = version;
   }

package/dist/adapters/indexedDB.js

@@ -1,5 +1,5 @@
-import { DB_VERSION } from '../chunk-SNTSB6M2.js';
-import '../chunk-AA4Q2J57.js';
+import { DB_VERSION } from '../chunk-TS2MTRP4.js';
+import '../chunk-3AOTJZQ4.js';
 import '../chunk-MBSYQ3WX.js';
 import '../chunk-EFNLTS6Q.js';
 import '../chunk-NSBPE2FW.js';

package/dist/{ark-ApoclKQZ.d.cts → ark-9V45Anrs.d.cts}

@@ -2102,6 +2102,15 @@ interface IContractManager extends Disposable {
      * Outpoints not owned by any tracked contract are silently dropped.
      */
     refreshOutpoints(outpoints: Outpoint[]): Promise<void>;
+    /**
+     * Rebuild the HD look-ahead watch window around the current allocation
+     * watermark. No-op when the manager was configured without `lookAhead`.
+     *
+     * Call after anything that moves the watermark (restore, boarding
+     * allocation, receive rotation, server-signer rotation). Concurrent calls
+     * coalesce into a single drain.
+     */
+    refillLookAhead(): Promise<void>;
     /**
      * Explicit, gap-limit contract discovery used by `wallet.restore()`.
      *
@@ -2192,6 +2201,27 @@ interface ContractManagerConfig {
     onVtxosSpent?: (vtxos: Outpoint[]) => Promise<void>;
     /** Watcher configuration */
     watcherConfig?: Partial<ContractWatcherConfig>;
+    /**
+     * Enables the HD look-ahead watch window. Absent ⇒ feature off (static /
+     * non-HD wallets, third-party embedders). See
+     * {@link ContractManager.refillLookAhead}.
+     */
+    lookAhead?: LookAheadConfig;
+}
+/**
+ * Wallet-injected surface backing the HD look-ahead window. Kept as a
+ * callback bundle so the contracts layer never learns what an HD descriptor
+ * is (mirrors {@link ScanContractsOptions.materialize}).
+ */
+interface LookAheadConfig {
+    /** Per-side band bound: the window spans `[max(0, w - size), w + size]`. */
+    size: number;
+    /** Current allocation watermark (`lastIndexUsed ?? -1`). */
+    currentWatermark(): Promise<number>;
+    /** Offchain receive contract params at an HD index. Pure derivation. */
+    materialize(index: number): CreateContractParams;
+    /** Fired after a speculative entry at `index` is promoted to a real row. */
+    onPromoted?(index: number): Promise<void>;
 }
 /**
  * Parameters for creating a new contract.
@@ -2257,6 +2287,12 @@ declare class ContractManager implements IContractManager {
     private syncDegradedReason?;
     /** Epoch-ms of the last successful provider sync, if any. */
     private lastSyncedAt?;
+    /** Speculative look-ahead scripts, keyed by script. @see LookAheadEntry */
+    private lookAheadEntries;
+    /** In-flight look-ahead drain, if any. @see scheduleLookAheadDrain */
+    private lookAheadDrain?;
+    /** A refill was requested while a drain was running. */
+    private lookAheadDirty;
     private constructor();
     /**
      * Static factory method for creating a new ContractManager.
@@ -2298,6 +2334,59 @@ declare class ContractManager implements IContractManager {
      * a failure is logged and sync continues. No-op without an intent store.
      */
     private reconcileStaleIntents;
+    /** @see IContractManager.refillLookAhead */
+    refillLookAhead(): Promise<void>;
+    /**
+     * Serialized drain of the look-ahead band: concurrent callers join the
+     * active drain and mark it dirty, an idle call starts a new one. Promotion
+     * can uncover more funded indices, and boot / SSE / rotate / reconnect can
+     * all request a refill at once, so the loop coalesces them instead of
+     * recursing.
+     */
+    private scheduleLookAheadDrain;
+    /**
+     * Request a drain without awaiting it. Used from inside a sync (promotion),
+     * where awaiting the drain that the sync itself is part of would deadlock.
+     */
+    private requestLookAheadDrain;
+    /**
+     * Rebuild the speculative watch band around the allocation watermark.
+     *
+     * NArk needs no analogue because it *is* the address issuer: it persists a
+     * contract row at derivation time, so its watched set is a superset of
+     * every address it ever advertised. This SDK, when a third party issues
+     * addresses from the shared seed, cannot observe those allocations at all —
+     * the window is how a non-issuer compensates.
+     *
+     * Entries are registered with the watcher but NOT persisted: they become
+     * repository rows only once funded (see {@link promoteLookAheadHits}).
+     */
+    private ensureLookAhead;
+    /**
+     * One-time full-history sync for speculative entries the manager has not
+     * successfully caught up on yet.
+     *
+     * Every normal sync uses the cursor-derived delta window and SSE only
+     * delivers events after a script is subscribed, so a script first
+     * registered after its funding time would otherwise be skipped forever
+     * (upgrade migration, or a band that slid over an already-funded index).
+     * The entries are passed as in-memory contracts because `refreshVtxos`
+     * resolves scripts through the repository, where they deliberately do not
+     * exist. Targeted + explicitly windowed, so the global cursor stays put.
+     */
+    private runLookAheadCatchUp;
+    /**
+     * Promote every look-ahead entry funded by `vtxos` into a real repository
+     * row, returning the persisted rows keyed by script.
+     *
+     * MUST run on each raw indexer fetch before `annotateVtxos`:
+     * `extendVirtualCoinForContract` throws when a VTXO's script has no
+     * contract row, so a funded window entry has to be persisted before its
+     * VTXOs are annotated and saved. Callers also swap the returned rows into
+     * the local contract maps they built pre-promotion, so `saveVtxosForContract`
+     * and `onVtxosPersisted` never see the synthetic watcher object.
+     */
+    private promoteLookAheadHits;
     /**
      * Create and register a new contract.
      *
@@ -2324,6 +2413,7 @@ declare class ContractManager implements IContractManager {
      * `persisted` is `true`.
      */
     private upsertContract;
+    private upsertContractRow;
     /**
      * Explicit, gap-limit contract discovery (see {@link IContractManager.scanContracts}).
      *
@@ -3624,6 +3714,20 @@ interface WalletConfig extends ReadonlyWalletConfig {
      * @defaultValue `'auto'`
      */
     walletMode?: WalletMode;
+    /**
+     * Per-side width of the HD look-ahead watch window: the wallet watches
+     * missing offchain receive scripts across `[watermark - N, watermark + N]`
+     * so funds paid to an address issued by an external party (a merchant
+     * backend sharing the seed) arrive without an explicit `restore()`.
+     *
+     * Only meaningful for HD wallets (`walletMode: 'hd'` or an HD
+     * {@link DescriptorProvider}); ignored otherwise. Raise it when the issuer
+     * is expected to hand out more than `N` consecutive addresses without any
+     * of them being paid. Must be a positive integer.
+     *
+     * @defaultValue `20`
+     */
+    lookAheadWindow?: number;
 }
 /**
  * Repository implementations used to store wallet and contract state.
@@ -5034,4 +5138,4 @@ declare namespace ProtoTypes {
     export {  };
 }
 
-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 };
+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, CLTVMultisigTapscript 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 ReissuanceParams as aA, type BurnParams as aB, type RenewVtxosOptions as aC, type ContractWithVtxos as aD, type PathSelection as aE, type ContractEvent as aF, type AssetDetails as aG, type IssuanceResult as aH, type DelegateInfo as aI, type MigrationGlobalSkipReason as aJ, type MigrationLegSkipReason as aK, type SignerStatus as aL, type StorageConfig as aM, type IVtxoManager as aN, type ExplorerTransaction as aO, type EncodedVtxoScript as aP, type Status as aQ, type ChainTx as aR, type PathContext as aS, type ActivityIntent as aT, type ActivityResolver as aU, type ArkIntentState as aV, type ArkTapscript as aW, type AssetMetadata as aX, type BaseWalletConfig as aY, type BatchInfo as aZ, type BatchSignableIdentity as a_, ArkAddress as aa, type Coin as ab, ContractManager as ac, type ContractManagerConfig as ad, CSVMultisigTapscript as ae, type SettlementConfig as af, VtxoManager as ag, type SignerSession as ah, type SignedIntent as ai, Intent as aj, type TimeHeight as ak, type DescriptorSigningRequest as al, Transaction as am, type IntentFeeConfig as an, type OffchainInput as ao, FeeAmount as ap, type OnchainInput as aq, type FeeOutput as ar, type ContractWatcherConfig as as, type Asset as at, type FeeInfo as au, type CreateContractParams as av, type GetContractsFilter as aw, type GetSpendablePathsOptions as ax, type GetAllSpendingPathsOptions as ay, type IssuanceParams as az, type WalletConfig as b, type VtxoChain as b$, ChainTxType as b0, type CommitmentTx as b1, ConditionCSVMultisigTapscript as b2, ConditionMultisigTapscript as b3, type ContractBalance as b4, type ContractEventCallback as b5, type ContractHandler 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 };

package/dist/{ark-ApoclKQZ.d.ts → ark-9V45Anrs.d.ts}

@@ -2102,6 +2102,15 @@ interface IContractManager extends Disposable {
      * Outpoints not owned by any tracked contract are silently dropped.
      */
     refreshOutpoints(outpoints: Outpoint[]): Promise<void>;
+    /**
+     * Rebuild the HD look-ahead watch window around the current allocation
+     * watermark. No-op when the manager was configured without `lookAhead`.
+     *
+     * Call after anything that moves the watermark (restore, boarding
+     * allocation, receive rotation, server-signer rotation). Concurrent calls
+     * coalesce into a single drain.
+     */
+    refillLookAhead(): Promise<void>;
     /**
      * Explicit, gap-limit contract discovery used by `wallet.restore()`.
      *
@@ -2192,6 +2201,27 @@ interface ContractManagerConfig {
     onVtxosSpent?: (vtxos: Outpoint[]) => Promise<void>;
     /** Watcher configuration */
     watcherConfig?: Partial<ContractWatcherConfig>;
+    /**
+     * Enables the HD look-ahead watch window. Absent ⇒ feature off (static /
+     * non-HD wallets, third-party embedders). See
+     * {@link ContractManager.refillLookAhead}.
+     */
+    lookAhead?: LookAheadConfig;
+}
+/**
+ * Wallet-injected surface backing the HD look-ahead window. Kept as a
+ * callback bundle so the contracts layer never learns what an HD descriptor
+ * is (mirrors {@link ScanContractsOptions.materialize}).
+ */
+interface LookAheadConfig {
+    /** Per-side band bound: the window spans `[max(0, w - size), w + size]`. */
+    size: number;
+    /** Current allocation watermark (`lastIndexUsed ?? -1`). */
+    currentWatermark(): Promise<number>;
+    /** Offchain receive contract params at an HD index. Pure derivation. */
+    materialize(index: number): CreateContractParams;
+    /** Fired after a speculative entry at `index` is promoted to a real row. */
+    onPromoted?(index: number): Promise<void>;
 }
 /**
  * Parameters for creating a new contract.
@@ -2257,6 +2287,12 @@ declare class ContractManager implements IContractManager {
     private syncDegradedReason?;
     /** Epoch-ms of the last successful provider sync, if any. */
     private lastSyncedAt?;
+    /** Speculative look-ahead scripts, keyed by script. @see LookAheadEntry */
+    private lookAheadEntries;
+    /** In-flight look-ahead drain, if any. @see scheduleLookAheadDrain */
+    private lookAheadDrain?;
+    /** A refill was requested while a drain was running. */
+    private lookAheadDirty;
     private constructor();
     /**
      * Static factory method for creating a new ContractManager.
@@ -2298,6 +2334,59 @@ declare class ContractManager implements IContractManager {
      * a failure is logged and sync continues. No-op without an intent store.
      */
     private reconcileStaleIntents;
+    /** @see IContractManager.refillLookAhead */
+    refillLookAhead(): Promise<void>;
+    /**
+     * Serialized drain of the look-ahead band: concurrent callers join the
+     * active drain and mark it dirty, an idle call starts a new one. Promotion
+     * can uncover more funded indices, and boot / SSE / rotate / reconnect can
+     * all request a refill at once, so the loop coalesces them instead of
+     * recursing.
+     */
+    private scheduleLookAheadDrain;
+    /**
+     * Request a drain without awaiting it. Used from inside a sync (promotion),
+     * where awaiting the drain that the sync itself is part of would deadlock.
+     */
+    private requestLookAheadDrain;
+    /**
+     * Rebuild the speculative watch band around the allocation watermark.
+     *
+     * NArk needs no analogue because it *is* the address issuer: it persists a
+     * contract row at derivation time, so its watched set is a superset of
+     * every address it ever advertised. This SDK, when a third party issues
+     * addresses from the shared seed, cannot observe those allocations at all —
+     * the window is how a non-issuer compensates.
+     *
+     * Entries are registered with the watcher but NOT persisted: they become
+     * repository rows only once funded (see {@link promoteLookAheadHits}).
+     */
+    private ensureLookAhead;
+    /**
+     * One-time full-history sync for speculative entries the manager has not
+     * successfully caught up on yet.
+     *
+     * Every normal sync uses the cursor-derived delta window and SSE only
+     * delivers events after a script is subscribed, so a script first
+     * registered after its funding time would otherwise be skipped forever
+     * (upgrade migration, or a band that slid over an already-funded index).
+     * The entries are passed as in-memory contracts because `refreshVtxos`
+     * resolves scripts through the repository, where they deliberately do not
+     * exist. Targeted + explicitly windowed, so the global cursor stays put.
+     */
+    private runLookAheadCatchUp;
+    /**
+     * Promote every look-ahead entry funded by `vtxos` into a real repository
+     * row, returning the persisted rows keyed by script.
+     *
+     * MUST run on each raw indexer fetch before `annotateVtxos`:
+     * `extendVirtualCoinForContract` throws when a VTXO's script has no
+     * contract row, so a funded window entry has to be persisted before its
+     * VTXOs are annotated and saved. Callers also swap the returned rows into
+     * the local contract maps they built pre-promotion, so `saveVtxosForContract`
+     * and `onVtxosPersisted` never see the synthetic watcher object.
+     */
+    private promoteLookAheadHits;
     /**
      * Create and register a new contract.
      *
@@ -2324,6 +2413,7 @@ declare class ContractManager implements IContractManager {
      * `persisted` is `true`.
      */
     private upsertContract;
+    private upsertContractRow;
     /**
      * Explicit, gap-limit contract discovery (see {@link IContractManager.scanContracts}).
      *
@@ -3624,6 +3714,20 @@ interface WalletConfig extends ReadonlyWalletConfig {
      * @defaultValue `'auto'`
      */
     walletMode?: WalletMode;
+    /**
+     * Per-side width of the HD look-ahead watch window: the wallet watches
+     * missing offchain receive scripts across `[watermark - N, watermark + N]`
+     * so funds paid to an address issued by an external party (a merchant
+     * backend sharing the seed) arrive without an explicit `restore()`.
+     *
+     * Only meaningful for HD wallets (`walletMode: 'hd'` or an HD
+     * {@link DescriptorProvider}); ignored otherwise. Raise it when the issuer
+     * is expected to hand out more than `N` consecutive addresses without any
+     * of them being paid. Must be a positive integer.
+     *
+     * @defaultValue `20`
+     */
+    lookAheadWindow?: number;
 }
 /**
  * Repository implementations used to store wallet and contract state.
@@ -5034,4 +5138,4 @@ declare namespace ProtoTypes {
     export {  };
 }
 
-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 };
+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, CLTVMultisigTapscript 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 ReissuanceParams as aA, type BurnParams as aB, type RenewVtxosOptions as aC, type ContractWithVtxos as aD, type PathSelection as aE, type ContractEvent as aF, type AssetDetails as aG, type IssuanceResult as aH, type DelegateInfo as aI, type MigrationGlobalSkipReason as aJ, type MigrationLegSkipReason as aK, type SignerStatus as aL, type StorageConfig as aM, type IVtxoManager as aN, type ExplorerTransaction as aO, type EncodedVtxoScript as aP, type Status as aQ, type ChainTx as aR, type PathContext as aS, type ActivityIntent as aT, type ActivityResolver as aU, type ArkIntentState as aV, type ArkTapscript as aW, type AssetMetadata as aX, type BaseWalletConfig as aY, type BatchInfo as aZ, type BatchSignableIdentity as a_, ArkAddress as aa, type Coin as ab, ContractManager as ac, type ContractManagerConfig as ad, CSVMultisigTapscript as ae, type SettlementConfig as af, VtxoManager as ag, type SignerSession as ah, type SignedIntent as ai, Intent as aj, type TimeHeight as ak, type DescriptorSigningRequest as al, Transaction as am, type IntentFeeConfig as an, type OffchainInput as ao, FeeAmount as ap, type OnchainInput as aq, type FeeOutput as ar, type ContractWatcherConfig as as, type Asset as at, type FeeInfo as au, type CreateContractParams as av, type GetContractsFilter as aw, type GetSpendablePathsOptions as ax, type GetAllSpendingPathsOptions as ay, type IssuanceParams as az, type WalletConfig as b, type VtxoChain as b$, ChainTxType as b0, type CommitmentTx as b1, ConditionCSVMultisigTapscript as b2, ConditionMultisigTapscript as b3, type ContractBalance as b4, type ContractEventCallback as b5, type ContractHandler 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 };

package/dist/{asyncStorageTaskQueue-CIjgv1co.d.cts → asyncStorageTaskQueue-B6nXJv7m.d.cts}

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

package/dist/{asyncStorageTaskQueue-BCWmdVg8.d.ts → asyncStorageTaskQueue-BZjR843B.d.ts}

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

package/dist/{chunk-AA4Q2J57.js → chunk-3AOTJZQ4.js}

@@ -159,7 +159,7 @@ function checkKeyMatch(key, arkPsbtFieldKey, prefixOnly = false) {
 }
 
 // package.json
-var version = "0.4.50";
+var version = "0.4.51";
 
 // src/utils/fetch.ts
 var buildVersion = "0.9.9";
@@ -3102,5 +3102,5 @@ var Response;
 })(Response || (Response = {}));
 
 export { ArkError, ArkErrorName, ArkPsbtFieldKey, ArkPsbtFieldKeyType, AssetGroup, AssetId, AssetInput, AssetOutput, AssetRef, BufferReader, BufferWriter, ChainTxType, ConditionWitness, CosignerPublicKey, DigestMismatchError, FetchError, IndexerTxType, Intent, Metadata, OP_RETURN_EMPTY_PKSCRIPT, Packet, PrevArkTxField, PrevoutTxField, ProviderUnavailableError, RestArkProvider, RestIndexerProvider, SettlementEventType, Transaction, VtxoTaprootTree, VtxoTreeExpiry, asset_exports, baseFetch, buildVersion, craftToSpendTx, fetch, getArkPsbtFields, isArkError, isEventSourceError, isFetchTimeoutError, maybeArkError, rateGate, sdkVersion, setArkPsbtField };
-//# sourceMappingURL=chunk-AA4Q2J57.js.map
-//# sourceMappingURL=chunk-AA4Q2J57.js.map
+//# sourceMappingURL=chunk-3AOTJZQ4.js.map
+//# sourceMappingURL=chunk-3AOTJZQ4.js.map