@arkade-os/sdk 0.4.50 → 0.4.52

package/dist/{chunk-SNTSB6M2.js → chunk-AXCKRS2D.js}

@@ -1,5 +1,5 @@
-import { Transaction, setArkPsbtField, PrevArkTxField, ConditionWitness, AssetId, AssetGroup, AssetInput, AssetOutput, Metadata, Packet, craftToSpendTx, getArkPsbtFields, CosignerPublicKey, BufferReader, BufferWriter, OP_RETURN_EMPTY_PKSCRIPT, VtxoTaprootTree, baseFetch, Intent, rateGate, maybeArkError, isArkError, ArkErrorName, ProviderUnavailableError, FetchError, isFetchTimeoutError, AssetRef, isEventSourceError, RestArkProvider, RestIndexerProvider, ArkError } from './chunk-AA4Q2J57.js';
-import { witnessRefToBytes, validateProgram, toASM, stringifyArtifact, serializeArkadeContractParams, resolveAsm, parseArtifact, getOpcodeValue, getOpcodeName, fromASM, deserializeArkadeContractParams, computeArkadeScriptPublicKey, bytesToASM, asmToBytes, arkadeWitnessHash, arkadeScriptHash, SUPPORTED_PROGRAM_VERSION, OPCODE_VALUES, OPCODE_NAMES, bignum_exports, ArkadeScript, ArkadeProgramScript, ARKADE_OPS, ARKADE_OPCODE_VALUES, ARKADE_OPCODE_NAMES, ARKADE_OPCODES, ARKADE_OP, inputName, contractHandlers, isMainnetDescriptor, descriptorIsOurs, DefaultVtxo, DelegateVtxo, WALLET_RECEIVE_SOURCE, deriveDescriptorLeafPubKey, BoardingContractHandler } from './chunk-MBSYQ3WX.js';
+import { Transaction, setArkPsbtField, PrevArkTxField, ConditionWitness, AssetId, AssetGroup, AssetInput, AssetOutput, Metadata, Packet, craftToSpendTx, getArkPsbtFields, CosignerPublicKey, BufferReader, BufferWriter, OP_RETURN_EMPTY_PKSCRIPT, VtxoTaprootTree, baseFetch, Intent, rateGate, maybeArkError, isArkError, ArkErrorName, ProviderUnavailableError, FetchError, isFetchTimeoutError, AssetRef, isEventSourceError, RestArkProvider, RestIndexerProvider, ArkError } from './chunk-ZK3JITHP.js';
+import { witnessRefToBytes, validateProgram, toASM, stringifyArtifact, serializeArkadeContractParams, resolveAsm, parseArtifact, getOpcodeValue, getOpcodeName, fromASM, deserializeArkadeContractParams, computeArkadeScriptPublicKey, bytesToASM, asmToBytes, arkadeWitnessHash, arkadeScriptHash, SUPPORTED_PROGRAM_VERSION, OPCODE_VALUES, OPCODE_NAMES, bignum_exports, ArkadeScript, ArkadeProgramScript, ARKADE_OPS, ARKADE_OPCODE_VALUES, ARKADE_OPCODE_NAMES, ARKADE_OPCODES, ARKADE_OP, inputName, contractHandlers, isMainnetDescriptor, descriptorIsOurs, DefaultVtxo, speculativeReceiveMetadata, DelegateVtxo, deriveDescriptorLeafPubKey, WALLET_RECEIVE_SOURCE, BoardingContractHandler } from './chunk-UZLQUWYP.js';
 import { VtxoScript, isRecoverable, CSVMultisigTapscript, DEFAULT_NETWORK, hasTerminalSpend, getNormalizedVtxos, isVirtualCoin, ArkAddress, sequenceToTimelock, decodeTapscript, scriptFromTapLeafScript, CLTVMultisigTapscript, timelockToSequence, DEFAULT_NETWORK_NAME, normalizeVtxo, getSequence, toBatchExpiry, toOffchainInputFeeParams, canRecoverOnchain, getNetwork, MultisigTapscript, getAllNormalizedVtxos, DEFAULT_PAGE_SIZE, canSpendOffchain, toVirtualStatus, resolveTimeHeight, parseLegacyExpiry, networks as networks$1, isExpired, DEFAULT_ARKADE_SERVER_URL, isPastExpiry } from './chunk-EFNLTS6Q.js';
 import { __export } from './chunk-NSBPE2FW.js';
 import { sha256, equalBytes, hash160, sha256x2, concatBytes, randomPrivateKeyBytes, pubECDSA, pubSchnorr } from '@scure/btc-signer/utils.js';
@@ -2589,6 +2589,9 @@ function parseProgram(text, env) {
 }
 
 // src/contracts/types.ts
+function hasCandidates(handler) {
+  return !!handler && typeof handler.candidatesAt === "function";
+}
 function isDiscoverable(handler) {
   return !!handler && typeof handler.discoverAt === "function";
 }
@@ -8713,6 +8716,9 @@ function dedupeOutpoints(outpoints) {
 function areCoalescibleContractTypes(a, b) {
   return a === "default" && b === "boarding" || a === "boarding" && b === "default";
 }
+function toWatchOnlyContract(params) {
+  return { ...params, state: params.state ?? "active", createdAt: Date.now() };
+}
 var SCAN_MAX_INDEX = 1e4;
 var DEFAULT_SCAN_BATCH = 10;
 var ContractManager = class _ContractManager {
@@ -8725,6 +8731,12 @@ var ContractManager = class _ContractManager {
   syncDegradedReason;
   /** Epoch-ms of the last successful provider sync, if any. */
   lastSyncedAt;
+  /** Speculative look-ahead scripts, keyed by script. @see LookAheadEntry */
+  lookAheadEntries = /* @__PURE__ */ new Map();
+  /** In-flight look-ahead drain, if any. @see scheduleLookAheadDrain */
+  lookAheadDrain;
+  /** A refill was requested while a drain was running. */
+  lookAheadDirty = false;
   constructor(config) {
     this.config = config;
     this.watcher = new ContractWatcher({
@@ -8775,6 +8787,7 @@ var ContractManager = class _ContractManager {
     for (const contract of contracts) {
       await this.watcher.addContract(contract);
     }
+    await this.scheduleLookAheadDrain();
     try {
       await this.reconcileWatched();
       this.markSyncOnline();
@@ -8826,6 +8839,173 @@ var ContractManager = class _ContractManager {
       console.error("ContractManager: intent reconciliation failed", e);
     }
   }
+  /** @see IContractManager.refillLookAhead */
+  refillLookAhead() {
+    return this.scheduleLookAheadDrain();
+  }
+  /**
+   * 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.
+   */
+  scheduleLookAheadDrain() {
+    if (!this.config.lookAhead) return Promise.resolve();
+    if (this.lookAheadDrain) {
+      this.lookAheadDirty = true;
+      return this.lookAheadDrain;
+    }
+    const drain = (async () => {
+      do {
+        this.lookAheadDirty = false;
+        await this.ensureLookAhead();
+      } while (this.lookAheadDirty);
+    })().finally(() => {
+      this.lookAheadDrain = void 0;
+    });
+    this.lookAheadDrain = drain;
+    return drain;
+  }
+  /**
+   * 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.
+   */
+  requestLookAheadDrain() {
+    if (!this.config.lookAhead) return;
+    if (this.lookAheadDrain) {
+      this.lookAheadDirty = true;
+      return;
+    }
+    void this.scheduleLookAheadDrain().catch((err) => {
+      console.error("ContractManager: look-ahead refill failed", err);
+    });
+  }
+  /**
+   * 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}).
+   *
+   * Each index contributes every {@link Discoverable.candidatesAt} candidate —
+   * the same set `restore()`'s gap scan probes, since the wallet cannot know
+   * which variant a third-party issuer handed out.
+   */
+  async ensureLookAhead() {
+    const lookAhead = this.config.lookAhead;
+    if (!lookAhead) return;
+    const watermark = await lookAhead.currentWatermark();
+    const from = Math.max(0, watermark - lookAhead.size);
+    const to = watermark + lookAhead.size;
+    const deps = lookAhead.candidateDeps();
+    const handlers = contractHandlers.getRegisteredTypes().map((t) => contractHandlers.get(t)).filter(hasCandidates);
+    const band = /* @__PURE__ */ new Map();
+    for (let index = from; index <= to; index++) {
+      const descriptor = lookAhead.materialize(index);
+      for (const handler of handlers) {
+        for (const candidate of handler.candidatesAt(index, descriptor, deps)) {
+          if (band.has(candidate.script)) continue;
+          band.set(candidate.script, {
+            index,
+            params: {
+              ...candidate,
+              ...speculativeReceiveMetadata(descriptor)
+            }
+          });
+        }
+      }
+    }
+    await this.watcher.withCoalescedSubscription(async () => {
+      const persisted = await this.config.contractRepository.getContracts({
+        script: [...band.keys()]
+      });
+      const persistedScripts = new Set(persisted.map((c) => c.script));
+      for (const [script, { index, params }] of band) {
+        if (persistedScripts.has(script)) {
+          this.lookAheadEntries.delete(script);
+          continue;
+        }
+        if (this.lookAheadEntries.has(script)) continue;
+        const contract = toWatchOnlyContract(params);
+        this.lookAheadEntries.set(script, {
+          index,
+          params,
+          contract,
+          catchUpPending: true
+        });
+        await this.watcher.addContract(contract);
+      }
+      const stale = [...this.lookAheadEntries.keys()].filter((s) => !band.has(s));
+      if (stale.length > 0) {
+        const rows = await this.config.contractRepository.getContracts({ script: stale });
+        const nowPersisted = new Set(rows.map((c) => c.script));
+        for (const script of stale) {
+          this.lookAheadEntries.delete(script);
+          if (!nowPersisted.has(script)) await this.watcher.removeContract(script);
+        }
+      }
+    });
+    await this.runLookAheadCatchUp();
+  }
+  /**
+   * 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.
+   */
+  async runLookAheadCatchUp() {
+    const pending = [...this.lookAheadEntries.values()].filter((e) => e.catchUpPending);
+    if (pending.length === 0) return;
+    try {
+      await this.syncContracts({
+        contracts: pending.map((e) => e.contract),
+        window: { after: 0 }
+      });
+      for (const entry of pending) entry.catchUpPending = false;
+    } catch (err) {
+      if (!isRetryableProviderError(err)) throw err;
+      this.markSyncDegraded(err);
+    }
+  }
+  /**
+   * 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.
+   */
+  async promoteLookAheadHits(vtxos) {
+    const promoted = /* @__PURE__ */ new Map();
+    if (this.lookAheadEntries.size === 0) return promoted;
+    const hits = /* @__PURE__ */ new Map();
+    for (const vtxo of vtxos) {
+      const entry = this.lookAheadEntries.get(vtxo.script);
+      if (entry) hits.set(vtxo.script, entry);
+    }
+    if (hits.size === 0) return promoted;
+    for (const [script, entry] of hits) {
+      promoted.set(script, await this.persistAndWatchContract(entry.params));
+      await this.config.lookAhead?.onPromoted?.(entry.index);
+    }
+    this.requestLookAheadDrain();
+    return promoted;
+  }
   /**
    * Create and register a new contract.
    *
@@ -8871,6 +9051,11 @@ var ContractManager = class _ContractManager {
    * `persisted` is `true`.
    */
   async upsertContract(params) {
+    const result = await this.upsertContractRow(params);
+    this.lookAheadEntries.delete(params.script);
+    return result;
+  }
+  async upsertContractRow(params) {
     const handler = contractHandlers.get(params.type);
     if (!handler) {
       throw new Error(`No handler registered for contract type '${params.type}'`);
@@ -9360,6 +9545,7 @@ var ContractManager = class _ContractManager {
           }
           break;
         case "connection_reset":
+          await this.scheduleLookAheadDrain();
           await this.reconcileWatched();
           this.markSyncOnline();
           break;
@@ -9419,11 +9605,16 @@ var ContractManager = class _ContractManager {
       contracts.map((c) => c.script),
       { pendingOnly: true }
     );
+    for (const [script, contract] of await this.promoteLookAheadHits(vtxos)) {
+      scriptToContract.set(script, contract);
+    }
     const owned = vtxos.filter((v) => scriptToContract.has(v.script));
     const annotated = await this.annotateVtxos(owned);
     const byContract = /* @__PURE__ */ new Map();
+    const contractByAddress = /* @__PURE__ */ new Map();
     for (const vtxo of annotated) {
       const contract = scriptToContract.get(vtxo.script);
+      contractByAddress.set(contract.address, contract);
       let arr = byContract.get(contract.address);
       if (!arr) {
         arr = [];
@@ -9435,7 +9626,7 @@ var ContractManager = class _ContractManager {
       });
     }
     for (const [addr, contractVtxos] of byContract) {
-      const contract = contracts.find((c) => c.address === addr);
+      const contract = contractByAddress.get(addr);
       const filtered = warnAndFilterVtxosForScript(
         contractVtxos,
         contract.script,
@@ -9456,11 +9647,15 @@ var ContractManager = class _ContractManager {
     }
   }
   async fetchContractVxosFromIndexer(contracts, pageSize, syncWindow) {
-    const fetched = await this.fetchContractVtxosBulk(contracts, pageSize, syncWindow);
+    const { vtxosByScript, promoted } = await this.fetchContractVtxosBulk(
+      contracts,
+      pageSize,
+      syncWindow
+    );
     const result = /* @__PURE__ */ new Map();
-    for (const [contractScript, vtxos] of fetched) {
+    for (const [contractScript, vtxos] of vtxosByScript) {
       result.set(contractScript, vtxos);
-      const contract = contracts.find((c) => c.script === contractScript);
+      const contract = promoted.get(contractScript) ?? contracts.find((c) => c.script === contractScript);
       if (contract) {
         const filtered = warnAndFilterVtxosForScript(
           vtxos,
@@ -9488,7 +9683,7 @@ var ContractManager = class _ContractManager {
   }
   async fetchContractVtxosBulk(contracts, pageSize = DEFAULT_PAGE_SIZE, syncWindow) {
     if (contracts.length === 0) {
-      return /* @__PURE__ */ new Map();
+      return { vtxosByScript: /* @__PURE__ */ new Map(), promoted: /* @__PURE__ */ new Map() };
     }
     const scriptToContract = new Map(contracts.map((c) => [c.script, c]));
     const result = new Map(
@@ -9507,6 +9702,10 @@ var ContractManager = class _ContractManager {
       contracts.map((c) => c.script),
       { ...windowOpts, pageSize }
     );
+    const promoted = await this.promoteLookAheadHits(vtxos);
+    for (const [script, contract] of promoted) {
+      scriptToContract.set(script, contract);
+    }
     const owned = vtxos.filter((v) => scriptToContract.has(v.script));
     const annotated = await this.annotateVtxos(owned);
     for (const vtxo of annotated) {
@@ -9515,7 +9714,7 @@ var ContractManager = class _ContractManager {
         contractScript: vtxo.script
       });
     }
-    return result;
+    return { vtxosByScript: result, promoted };
   }
   /**
    * Dispose of the ContractManager and release all resources.
@@ -9529,6 +9728,7 @@ var ContractManager = class _ContractManager {
     this.stopWatcherFn?.();
     this.stopWatcherFn = void 0;
     this.eventCallbacks.clear();
+    this.lookAheadEntries.clear();
     this.initialized = false;
   }
   /**
@@ -9594,6 +9794,15 @@ var HDDescriptorProvider = class _HDDescriptorProvider {
     if (settings.lastIndexUsed === void 0) return void 0;
     return this.materializeDescriptorAt(settings.lastIndexUsed);
   }
+  /**
+   * The most recently allocated index, or `undefined` when nothing has ever
+   * been allocated on this repo. Read-only peek at the watermark that
+   * {@link getNextSigningDescriptor} advances.
+   */
+  async getLastIndexUsed() {
+    const state = await this.walletRepository.getWalletState();
+    return this.parseSettings(state ?? {}).lastIndexUsed;
+  }
   /**
    * Monotonically advance the allocation watermark so the next
    * `getNextSigningDescriptor()` skips indices discovered by a restore
@@ -9976,58 +10185,24 @@ var WalletReceiveRotator = class _WalletReceiveRotator {
    */
   async rotate(wallet) {
     const descriptor = await this.provider.getNextSigningDescriptor();
-    const pubKey = deriveLeafPubkey(descriptor);
-    const newTapscript = rebuildTapscript(wallet.offchainTapscript, pubKey);
-    const newScript = hex.encode(newTapscript.pkScript);
-    const newAddress = newTapscript.address(wallet.network.hrp, wallet.arkServerPublicKey).encode();
+    const { tapscript: newTapscript, params } = buildReceiveContract(
+      wallet.offchainTapscript,
+      descriptor,
+      wallet.network.hrp);
+    const newScript = params.script;
     const manager = await wallet.getContractManager();
-    const csvTimelock = newTapscript.options.csvTimelock;
-    const csvTimelockStr = timelockToSequence(csvTimelock).toString();
-    const serverPubKeyHex = hex.encode(newTapscript.options.serverPubKey);
-    const baseParams = {
-      script: newScript,
-      address: newAddress,
-      state: "active",
-      // Persist the materialized signing descriptor alongside the
-      // source tag. The wallet's spending paths read this at sign
-      // time to route inputs locked by a rotated pubkey through
-      // `DescriptorProvider.signWithDescriptor` instead of the
-      // identity's index-0 key. Without it, post-rotation sends
-      // produce unsigned PSBTs that the server rejects with
-      // `INVALID_PSBT_INPUT (5): missing tapscript spend sig`.
-      metadata: {
-        source: WALLET_RECEIVE_SOURCE,
-        signingDescriptor: descriptor
-      }
-    };
-    if (newTapscript instanceof DelegateVtxo.Script) {
-      await manager.createContract({
-        ...baseParams,
-        type: "delegate",
-        params: {
-          pubKey: hex.encode(pubKey),
-          serverPubKey: serverPubKeyHex,
-          delegatePubKey: hex.encode(newTapscript.options.delegatePubKey),
-          csvTimelock: csvTimelockStr
-        }
-      });
-    } else {
-      await manager.createContract({
-        ...baseParams,
-        type: "default",
-        params: {
-          pubKey: hex.encode(pubKey),
-          serverPubKey: serverPubKeyHex,
-          csvTimelock: csvTimelockStr
-        }
-      });
-    }
+    await manager.createContract(params);
     wallet.setOffchainTapscriptForRotation(newTapscript);
     const previousTagged = this.currentTaggedScript;
     if (previousTagged !== void 0 && previousTagged !== newScript) {
       await manager.setContractState(previousTagged, "inactive");
     }
     this.currentTaggedScript = newScript;
+    try {
+      await manager.refillLookAhead();
+    } catch (err) {
+      this.logger.error("WalletReceiveRotator: look-ahead refill failed", err);
+    }
   }
 };
 function deriveLeafPubkey(descriptor) {
@@ -10040,6 +10215,45 @@ function deriveLeafPubkey(descriptor) {
     );
   }
 }
+function buildReceiveContract(current, descriptor, hrp, tagSource) {
+  const pubKey = deriveLeafPubkey(descriptor);
+  const tapscript = rebuildTapscript(current, pubKey);
+  const serverPubKey = tapscript.options.serverPubKey;
+  const csvTimelock = timelockToSequence(tapscript.options.csvTimelock).toString();
+  const base = {
+    script: hex.encode(tapscript.pkScript),
+    address: tapscript.address(hrp, serverPubKey).encode(),
+    state: "active",
+    // The materialized signing descriptor is read at sign time to route
+    // inputs locked by a rotated pubkey through
+    // `DescriptorProvider.signWithDescriptor` instead of the identity's
+    // index-0 key. Without it, spends produce unsigned PSBTs that the
+    // server rejects with `INVALID_PSBT_INPUT (5): missing tapscript spend sig`.
+    metadata: {
+      ...{ source: WALLET_RECEIVE_SOURCE },
+      signingDescriptor: descriptor
+    }
+  };
+  const params = tapscript instanceof DelegateVtxo.Script ? {
+    ...base,
+    type: "delegate",
+    params: {
+      pubKey: hex.encode(pubKey),
+      serverPubKey: hex.encode(serverPubKey),
+      delegatePubKey: hex.encode(tapscript.options.delegatePubKey),
+      csvTimelock
+    }
+  } : {
+    ...base,
+    type: "default",
+    params: {
+      pubKey: hex.encode(pubKey),
+      serverPubKey: hex.encode(serverPubKey),
+      csvTimelock
+    }
+  };
+  return { tapscript, params };
+}
 function rebuildTapscript(current, pubKey) {
   if (current instanceof DelegateVtxo.Script) {
     return new DelegateVtxo.Script({ ...current.options, pubKey });
@@ -10242,6 +10456,7 @@ function extractArkProviderUrl(provider) {
   const serverUrl = provider.serverUrl;
   return typeof serverUrl === "string" && serverUrl.length > 0 ? serverUrl : void 0;
 }
+var DEFAULT_LOOK_AHEAD_WINDOW = 20;
 var MAINNET_UNILATERAL_EXIT_DELAY = 605184n;
 function toXOnlyPubKey(pubkey) {
   if (pubkey.length === 33) return pubkey.slice(1);
@@ -11297,6 +11512,14 @@ var ReadonlyWallet = class _ReadonlyWallet {
       this._contractManagerInitializing = void 0;
     }
   }
+  /**
+   * HD look-ahead configuration for the contract manager. Readonly wallets
+   * have no descriptor provider, hence no watermark to look ahead of.
+   * @see Wallet.lookAheadConfig
+   */
+  lookAheadConfig() {
+    return void 0;
+  }
   async initializeContractManager() {
     const virtualTxRepository = this.virtualTxRepository;
     let onVtxosPersisted;
@@ -11331,7 +11554,8 @@ var ReadonlyWallet = class _ReadonlyWallet {
       intentRepository: this.intentRepository,
       onVtxosPersisted,
       onVtxosSpent,
-      watcherConfig: this.watcherConfig
+      watcherConfig: this.watcherConfig,
+      lookAhead: this.lookAheadConfig()
     });
     const baselinePubkey = await this.identity.xOnlyPublicKey();
     const delegatePubKey = this.offchainTapscript instanceof DelegateVtxo.Script ? this.offchainTapscript.options.delegatePubKey : void 0;
@@ -11425,7 +11649,7 @@ var ReadonlyWallet = class _ReadonlyWallet {
   }
 };
 var Wallet2 = class _Wallet extends ReadonlyWallet {
-  constructor(identity, network, onchainProvider, arkProvider, indexerProvider, arkServerPublicKey, offchainTapscript, boardingTapscript, serverUnrollScript, forfeitOutputScript, forfeitPubkey, dustAmount, walletRepository, contractRepository, renewalConfig, delegateProvider, watcherConfig, settlementConfig, walletContractTimelocks, receiveRotator, descriptorProvider) {
+  constructor(identity, network, onchainProvider, arkProvider, indexerProvider, arkServerPublicKey, offchainTapscript, boardingTapscript, serverUnrollScript, forfeitOutputScript, forfeitPubkey, dustAmount, walletRepository, contractRepository, renewalConfig, delegateProvider, watcherConfig, settlementConfig, walletContractTimelocks, receiveRotator, descriptorProvider, lookAheadWindow) {
     super(
       identity,
       network,
@@ -11465,6 +11689,7 @@ var Wallet2 = class _Wallet extends ReadonlyWallet {
     this._serverUnrollScript = serverUnrollScript;
     this._receiveRotator = receiveRotator;
     this._descriptorProvider = descriptorProvider;
+    this._lookAheadWindow = lookAheadWindow ?? DEFAULT_LOOK_AHEAD_WINDOW;
     this._signerRouter = new InputSignerRouter({
       identity,
       contractRepository,
@@ -11537,6 +11762,48 @@ var Wallet2 = class _Wallet extends ReadonlyWallet {
    * paths only ever take the identity-sign branch.
    */
   _descriptorProvider;
+  /** Per-side width of the HD look-ahead band. @see WalletConfig.lookAheadWindow */
+  _lookAheadWindow;
+  /**
+   * Watch a band of missing offchain receive scripts around the HD watermark
+   * so payments to an externally-issued address land without a `restore()`.
+   * Only HD wallets have a watermark to look ahead of; static / `auto`
+   * wallets keep a single index-0 receive address, so the feature stays off.
+   *
+   * `candidateDeps` is read at refill time, so a band rebuilt after
+   * {@link rotateServerSigner} fans the active signer set (persisted
+   * old-signer rows stay watched through the repository).
+   */
+  lookAheadConfig() {
+    const provider = this._descriptorProvider;
+    if (!(provider instanceof HDDescriptorProvider)) return void 0;
+    return {
+      size: this._lookAheadWindow,
+      currentWatermark: async () => await provider.getLastIndexUsed() ?? -1,
+      materialize: (index) => provider.materializeDescriptorAt(index),
+      candidateDeps: () => this.receiveCandidateDeps(),
+      onPromoted: (index) => provider.advanceLastIndexUsed(index)
+    };
+  }
+  /**
+   * Every axis an externally issued receive script could be anchored to, not
+   * just the wallet's own current shape: an issuer sharing the seed (NArk, a
+   * merchant backend) picks its own contract type, and a band derived from one
+   * variant silently misses the rest until a `restore()`.
+   *
+   * Read from cached state, not a fresh `getInfo`, to stay synchronous and
+   * offline-safe; {@link refreshDeprecatedSigners} and
+   * {@link rotateServerSigner} keep it current and re-trigger a refill.
+   */
+  receiveCandidateDeps() {
+    return {
+      network: { hrp: this.network.hrp },
+      serverPubKey: this.offchainTapscript.options.serverPubKey,
+      deprecatedSignerPubKeys: [...this._deprecatedSigners.keys()].map((h) => hex.decode(h)),
+      csvTimelocks: this.walletContractTimelocks,
+      delegatePubKey: this.offchainTapscript instanceof DelegateVtxo.Script ? this.offchainTapscript.options.delegatePubKey : void 0
+    };
+  }
   _signerRouter;
   /**
    * @internal Sole write path for `offchainTapscript` after construction.
@@ -11649,6 +11916,11 @@ var Wallet2 = class _Wallet extends ReadonlyWallet {
       }
     });
     this.setBoardingTapscriptForRotation(newBoarding);
+    try {
+      await manager.refillLookAhead();
+    } catch (e) {
+      console.warn("look-ahead refill after boarding allocation failed", e);
+    }
     return newBoarding.onchainAddress(this.network);
   }
   /**
@@ -11770,6 +12042,11 @@ var Wallet2 = class _Wallet extends ReadonlyWallet {
     this.setBoardingTapscriptForRotation(newBoarding);
     this.setArkServerPublicKeyForRotation(xonly);
     this.setServerUnrollScriptForRotation(newServerUnrollScript);
+    try {
+      await manager.refillLookAhead();
+    } catch (e) {
+      console.warn("look-ahead refill after server-signer rotation failed", e);
+    }
   }
   /**
    * Async mutex that serializes all operations submitting VTXOs to the Arkade
@@ -11885,6 +12162,7 @@ var Wallet2 = class _Wallet extends ReadonlyWallet {
     if (hd && result.highestConfirmedUsedIndex >= 0) {
       await provider.advanceLastIndexUsed(result.highestConfirmedUsedIndex);
     }
+    await manager.refillLookAhead();
     await manager.refreshVtxos({ includeInactive: true, after: 0 });
     const causes = result.handlerErrors.map(
       (e) => e.error instanceof Error ? e.error : new Error(String(e.error))
@@ -11976,6 +12254,11 @@ var Wallet2 = class _Wallet extends ReadonlyWallet {
    * ```
    */
   static async create(config) {
+    if (config.lookAheadWindow !== void 0 && (!Number.isInteger(config.lookAheadWindow) || config.lookAheadWindow <= 0)) {
+      throw new Error(
+        `lookAheadWindow must be a positive integer (got ${String(config.lookAheadWindow)})`
+      );
+    }
     const pubkey = await config.identity.xOnlyPublicKey();
     if (!pubkey) {
       throw new Error("Invalid configured public key");
@@ -12013,7 +12296,8 @@ var Wallet2 = class _Wallet extends ReadonlyWallet {
       config.settlementConfig,
       setup.walletContractTimelocks,
       boot?.rotator,
-      boot?.provider
+      boot?.provider,
+      config.lookAheadWindow
     );
     wallet._serverInfoSource = setup.serverInfoSource;
     if (setup.serverInfoSource === "live") {
@@ -14007,7 +14291,8 @@ var MessageBus = class {
         delegateProvider,
         settlementConfig: config.settlementConfig,
         walletMode: config.walletMode,
-        watcherConfig: config.watcherConfig
+        watcherConfig: config.watcherConfig,
+        lookAheadWindow: config.lookAheadWindow
       });
       return { wallet, arkProvider, readonlyWallet: wallet };
     }
@@ -16472,6 +16757,9 @@ var ServiceWorkerReadonlyWallet = class _ServiceWorkerReadonlyWallet {
           )
         );
       },
+      refillLookAhead() {
+        return Promise.resolve();
+      },
       async isWatching() {
         const message = {
           type: "IS_CONTRACT_MANAGER_WATCHING",
@@ -16521,6 +16809,11 @@ var ServiceWorkerWallet = class _ServiceWorkerWallet extends ServiceWorkerReadon
     return serializeSigningIdentity(this.identity);
   }
   static async create(options) {
+    if (options.lookAheadWindow !== void 0 && (!Number.isInteger(options.lookAheadWindow) || options.lookAheadWindow <= 0)) {
+      throw new Error(
+        `lookAheadWindow must be a positive integer (got ${String(options.lookAheadWindow)})`
+      );
+    }
     const walletRepository = options.storage?.walletRepository ?? new IndexedDBWalletRepository();
     const contractRepository = options.storage?.contractRepository ?? new IndexedDBContractRepository();
     if (!isSigningCapable(options.identity)) {
@@ -16570,6 +16863,7 @@ var ServiceWorkerWallet = class _ServiceWorkerWallet extends ServiceWorkerReadon
       settlementConfig: options.settlementConfig,
       walletMode: options.walletMode,
       watcherConfig: options.watcherConfig,
+      lookAheadWindow: options.lookAheadWindow,
       messageTimeouts
     };
     await initializeMessageBus(
@@ -19877,6 +20171,6 @@ function isArkContract(str) {
   return str.startsWith(ARKCONTRACT_PREFIX + "=");
 }
 
-export { ARKADE_MAGIC, ActivityRegistry, ArkNote, ArkadeCash, ArkadeCashCreateError, AssetManager, BIP322, Batch, ChainedTxType, ContractManager, ContractRepositoryImpl, ContractWatcher, DB_VERSION, DEFAULT_MESSAGE_TIMEOUTS, DelegateManagerImpl, DelegateNotConfiguredError, DelegatorManagerImpl, DelegatorNotConfiguredError, DescriptorSigningProviderMissingError, DustChangeError, ELECTRUM_TCP_HOST, ELECTRUM_WS_URL, ESPLORA_URL, ElectrumOnchainProvider, EmulatorPacket, EsploraProvider, Estimator, Extension, ExtensionNotFoundError, HDDescriptorProvider, INTENT_TERMINAL_STATES, InMemoryContractRepository, InMemoryIntentRepository, InMemoryVirtualTxRepository, InMemoryWalletRepository, IndexedDBContractRepository, IndexedDBIntentRepository, IndexedDBVirtualTxRepository, IndexedDBWalletRepository, MESSAGE_BUS_INITIALIZING, MESSAGE_BUS_NOT_INITIALIZED, MIGRATION_KEY, MessageBus, MessageBusInitializingError, MessageBusNotInitializedError, MissingSigningDescriptorError, MnemonicIdentity, OnchainWallet, P2A, Ramps, ReadonlyAssetManager, ReadonlyDescriptorIdentity, ReadonlySingleKey, ReadonlyWallet, ReadonlyWalletError, RestDelegateProvider, RestDelegatorProvider, RestEmulatorProvider, SeedIdentity, ServiceWorkerReadonlyWallet, ServiceWorkerTimeoutError, ServiceWorkerWallet, SingleKey, TxTree, TxType, TxWeightEstimator, UnilateralExit, UnknownPacket, Unroll, VtxoManager, Wallet2 as Wallet, WalletMessageHandler, WalletNotInitializedError, WalletRepositoryImpl, WsElectrumChainSource, arkade_exports, assertIntentIdUnique, boardingResolver, buildForfeitTx, buildOffchainTx, classifyAgainstSignerSet, classifyContractSigner, closeDatabase, combineTapscriptSigs, contractFromArkContract, contractFromArkContractWithAddress, createAssetPacket, createDefaultActivityRegistry, createExitChainResolver, decodeArkContract, deserializeAssets, deserializeExitPackage, deserializeUtxo, deserializeVtxo, encodeArkContract, extendVirtualCoinForContract, getMigrationStatus, getRandomId, hasBoardingTxExpired, intentMatchesFilter, intentPageBounds, isArkContract, isBatchSignable, isCooperativelyMigratable, isDiscoverable, isRetryableProviderError, isSubdust, isTerminalIntentState, isValidArkAddress, isVtxoExpiringSoon, isVtxoForScript, mergeChainedTxType, migrateWalletRepository, openDatabase, requiresMigration, rollbackMigration, saveVtxosForContract, scriptFromArkAddress, selectCoinsWithAsset, selectVirtualCoins, serializeAssets, serializeExitPackage, serializeUtxo, serializeVtxo, setupServiceWorker, signerSetFromInfo, toXOnlySignerHex, validateConnectorsTxGraph, validateVtxoTxGraph, verifyTapscriptSignatures, waitForIncomingFunds, warnAndFilterVtxosForScript };
-//# sourceMappingURL=chunk-SNTSB6M2.js.map
-//# sourceMappingURL=chunk-SNTSB6M2.js.map
+export { ARKADE_MAGIC, ActivityRegistry, ArkNote, ArkadeCash, ArkadeCashCreateError, AssetManager, BIP322, Batch, ChainedTxType, ContractManager, ContractRepositoryImpl, ContractWatcher, DB_VERSION, DEFAULT_MESSAGE_TIMEOUTS, DelegateManagerImpl, DelegateNotConfiguredError, DelegatorManagerImpl, DelegatorNotConfiguredError, DescriptorSigningProviderMissingError, DustChangeError, ELECTRUM_TCP_HOST, ELECTRUM_WS_URL, ESPLORA_URL, ElectrumOnchainProvider, EmulatorPacket, EsploraProvider, Estimator, Extension, ExtensionNotFoundError, HDDescriptorProvider, INTENT_TERMINAL_STATES, InMemoryContractRepository, InMemoryIntentRepository, InMemoryVirtualTxRepository, InMemoryWalletRepository, IndexedDBContractRepository, IndexedDBIntentRepository, IndexedDBVirtualTxRepository, IndexedDBWalletRepository, MESSAGE_BUS_INITIALIZING, MESSAGE_BUS_NOT_INITIALIZED, MIGRATION_KEY, MessageBus, MessageBusInitializingError, MessageBusNotInitializedError, MissingSigningDescriptorError, MnemonicIdentity, OnchainWallet, P2A, Ramps, ReadonlyAssetManager, ReadonlyDescriptorIdentity, ReadonlySingleKey, ReadonlyWallet, ReadonlyWalletError, RestDelegateProvider, RestDelegatorProvider, RestEmulatorProvider, SeedIdentity, ServiceWorkerReadonlyWallet, ServiceWorkerTimeoutError, ServiceWorkerWallet, SingleKey, TxTree, TxType, TxWeightEstimator, UnilateralExit, UnknownPacket, Unroll, VtxoManager, Wallet2 as Wallet, WalletMessageHandler, WalletNotInitializedError, WalletRepositoryImpl, WsElectrumChainSource, arkade_exports, assertIntentIdUnique, boardingResolver, buildForfeitTx, buildOffchainTx, classifyAgainstSignerSet, classifyContractSigner, closeDatabase, combineTapscriptSigs, contractFromArkContract, contractFromArkContractWithAddress, createAssetPacket, createDefaultActivityRegistry, createExitChainResolver, decodeArkContract, deserializeAssets, deserializeExitPackage, deserializeUtxo, deserializeVtxo, encodeArkContract, extendVirtualCoinForContract, getMigrationStatus, getRandomId, hasBoardingTxExpired, hasCandidates, intentMatchesFilter, intentPageBounds, isArkContract, isBatchSignable, isCooperativelyMigratable, isDiscoverable, isRetryableProviderError, isSubdust, isTerminalIntentState, isValidArkAddress, isVtxoExpiringSoon, isVtxoForScript, mergeChainedTxType, migrateWalletRepository, openDatabase, requiresMigration, rollbackMigration, saveVtxosForContract, scriptFromArkAddress, selectCoinsWithAsset, selectVirtualCoins, serializeAssets, serializeExitPackage, serializeUtxo, serializeVtxo, setupServiceWorker, signerSetFromInfo, toXOnlySignerHex, validateConnectorsTxGraph, validateVtxoTxGraph, verifyTapscriptSignatures, waitForIncomingFunds, warnAndFilterVtxosForScript };
+//# sourceMappingURL=chunk-AXCKRS2D.js.map
+//# sourceMappingURL=chunk-AXCKRS2D.js.map