@arkade-os/sdk 0.4.49 → 0.4.51

package/dist/{chunk-5QVBJUOG.js → chunk-TS2MTRP4.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-CPO2UB7L.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-3AOTJZQ4.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, deriveDescriptorLeafPubKey, WALLET_RECEIVE_SOURCE, BoardingContractHandler } from './chunk-MBSYQ3WX.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';
@@ -8114,10 +8114,10 @@ var ContractWatcher = class {
   /**
    * Add a contract to be watched.
    *
-   * Active contracts are immediately subscribed.
+   * Once watching, every contract is subscribed and polled whatever
+   * its state.
    *
-   * All contracts are polled to discover any existing virtual outputs
-   * (which may cause them to be watched even if inactive).
+   * @see getWatchedContracts
    */
   async addContract(contract) {
     const state = {
@@ -8185,18 +8185,18 @@ var ContractWatcher = class {
     return Array.from(this.contracts.values()).map((s) => s.contract);
   }
   /**
-   * Contracts the watcher is actually tracking:
-   * - all active contracts, plus
-   * - inactive contracts that still hold known virtual outputs
-   *   (the subscription keeps watching them so `vtxo_spent` events for
-   *   those unspent outputs are still observed).
+   * Every registered contract, retired (`inactive`) ones included.
    *
-   * This is the single source of truth for "contracts whose VTXO state
-   * we still care about" — callers and the subscription itself fan out
-   * over the same set so nothing is reconciled that isn't also watched.
+   * Feeds both the subscription and the indexer sweep scope, so
+   * narrowing it drops a contract from every background channel at
+   * once. Nothing may be narrowed out: an Ark receive address can be
+   * paid again after the wallet has rotated past it, and a payment
+   * that lands outside every background channel is invisible until
+   * some foreground read happens to sweep it. Retirement therefore
+   * governs receive-address selection, not coverage.
    */
   getWatchedContracts() {
-    return Array.from(this.contracts.values()).filter((s) => s.contract.state === "active" || s.lastKnownVtxos.size > 0).map((s) => s.contract);
+    return this.getAllContracts();
   }
   /**
    * Get virtual outputs for contracts, grouped by contract script.
@@ -8225,7 +8225,7 @@ var ContractWatcher = class {
     return new Map(results.flat(1));
   }
   /**
-   * Start watching for virtual output events across all active contracts.
+   * Start watching for virtual output events across all watched contracts.
    */
   async startWatching(callback) {
     if (this.isWatching) {
@@ -8276,7 +8276,7 @@ var ContractWatcher = class {
     return this.connectionState;
   }
   /**
-   * Force a poll of all active contracts.
+   * Force a poll of all watched contracts.
    * Useful for manual refresh or after app resume.
    */
   async forcePoll() {
@@ -8464,7 +8464,7 @@ var ContractWatcher = class {
   /**
    * Update the subscription with scripts that should be watched.
    *
-   * Watches both active contracts and contracts with virtual outputs.
+   * @see getWatchedContracts
    */
   async updateSubscription() {
     const scriptsToWatch = this.getWatchedContracts().map((c) => c.script);
@@ -8713,6 +8713,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 +8728,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({
@@ -8737,8 +8746,8 @@ var ContractManager = class _ContractManager {
    * Static factory method for creating a new ContractManager.
    * Initialize the manager by loading persisted contracts and starting to watch.
    *
-   * After initialization, the manager automatically watches all active contracts
-   * and contracts with virtual outputs. Use `onContractEvent()` to register event callbacks.
+   * After initialization, the manager automatically watches every persisted
+   * contract. Use `onContractEvent()` to register event callbacks.
    *
    * @param config ContractManagerConfig
    */
@@ -8775,6 +8784,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 +8836,156 @@ 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}).
+   */
+  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 band = /* @__PURE__ */ new Map();
+    for (let index = from; index <= to; index++) {
+      const params = lookAhead.materialize(index);
+      band.set(params.script, { index, params });
+    }
+    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 +9031,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}'`);
@@ -9185,13 +9350,17 @@ var ContractManager = class _ContractManager {
     return updated;
   }
   /**
-   * Set a contract's state.
+   * Set a contract's state. Retiring (`inactive`) keeps it watched;
+   * see {@link ContractState}. To stop watching, use
+   * {@link deleteContract}.
    */
   async setContractState(script, state) {
     await this.updateContract(script, { state });
   }
   /**
-   * Delete a contract.
+   * Delete a contract. Also removes it from the watcher — the only way
+   * to stop watching a contract (retiring it via
+   * {@link setContractState} does not).
    *
    * @param script - Contract script
    */
@@ -9266,22 +9435,10 @@ var ContractManager = class _ContractManager {
   /**
    * Force refresh virtual outputs from the indexer.
    *
-   * Without options, re-fetches every contract in the watcher's
-   * watched set and advances the global cursor.
-   *
-   * `scripts` narrows the refresh to a specific list (subset query —
-   * cursor is not advanced because contracts outside the list may
-   * have data we'd skip).
-   *
-   * `includeInactive: true` (and no `scripts`) widens the refresh to
-   * every contract in the repository, including ones marked
-   * `inactive` and ones that have dropped out of the watcher's
-   * active set. This is a *superset* of the watched set, so the
-   * cursor invariant still holds and the cursor advances normally.
-   *
-   * `after` / `before` apply a caller-supplied time window. The
-   * cursor never advances on a windowed query because the window
-   * may skip data outside its bounds.
+   * Without options, re-fetches the watcher's watched set and
+   * advances the global cursor. Each option narrows or widens that
+   * scope and may hold the cursor back — see
+   * {@link RefreshVtxosOptions}.
    */
   async refreshVtxos(opts) {
     const contracts = opts?.scripts ? await this.getContracts({ script: opts.scripts }) : void 0;
@@ -9368,6 +9525,7 @@ var ContractManager = class _ContractManager {
           }
           break;
         case "connection_reset":
+          await this.scheduleLookAheadDrain();
           await this.reconcileWatched();
           this.markSyncOnline();
           break;
@@ -9397,11 +9555,10 @@ var ContractManager = class _ContractManager {
    * Sync virtual outputs for the given contracts against the indexer.
    *
    * When `options.contracts` is omitted the sync covers the full
-   * watched set (active contracts plus any inactive contracts still
-   * holding cached VTXOs) and the global cursor is advanced on
-   * success. Passing an explicit subset leaves the cursor alone so a
-   * narrow poll can't hide data that other contracts still need to
-   * pick up.
+   * watched set ({@link ContractWatcher.getWatchedContracts}) and the
+   * global cursor is advanced on success. Passing an explicit subset
+   * leaves the cursor alone so a narrow poll can't hide data that
+   * other contracts still need to pick up.
    */
   async syncContracts(options) {
     const cursor = await getSyncCursor(this.config.walletRepository);
@@ -9428,11 +9585,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 = [];
@@ -9444,7 +9606,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,
@@ -9465,11 +9627,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,
@@ -9497,7 +9663,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(
@@ -9516,6 +9682,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) {
@@ -9524,7 +9694,7 @@ var ContractManager = class _ContractManager {
         contractScript: vtxo.script
       });
     }
-    return result;
+    return { vtxosByScript: result, promoted };
   }
   /**
    * Dispose of the ContractManager and release all resources.
@@ -9538,6 +9708,7 @@ var ContractManager = class _ContractManager {
     this.stopWatcherFn?.();
     this.stopWatcherFn = void 0;
     this.eventCallbacks.clear();
+    this.lookAheadEntries.clear();
     this.initialized = false;
   }
   /**
@@ -9603,6 +9774,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
@@ -9985,58 +10165,26 @@ 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,
+      true
+    );
+    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) {
@@ -10049,6 +10197,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: {
+      ...tagSource && { 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 });
@@ -10251,6 +10438,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);
@@ -11306,6 +11494,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;
@@ -11340,7 +11536,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;
@@ -11434,7 +11631,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,
@@ -11474,6 +11671,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,
@@ -11546,6 +11744,36 @@ 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.
+   *
+   * `materialize` reads `this.offchainTapscript` at call time, so a refill
+   * after {@link rotateServerSigner} rebuilds the band under the active
+   * signer (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) => buildReceiveContract(
+        this.offchainTapscript,
+        provider.materializeDescriptorAt(index),
+        this.network.hrp,
+        // Never tagged: a promoted entry was generated by someone
+        // else, and the tag would make the next boot advertise a
+        // third party's invoice address as our own.
+        false
+      ).params,
+      onPromoted: (index) => provider.advanceLastIndexUsed(index)
+    };
+  }
   _signerRouter;
   /**
    * @internal Sole write path for `offchainTapscript` after construction.
@@ -11658,6 +11886,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);
   }
   /**
@@ -11779,6 +12012,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
@@ -11894,6 +12132,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))
@@ -11985,6 +12224,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");
@@ -12022,7 +12266,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") {
@@ -14016,7 +14261,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 };
     }
@@ -16481,6 +16727,9 @@ var ServiceWorkerReadonlyWallet = class _ServiceWorkerReadonlyWallet {
           )
         );
       },
+      refillLookAhead() {
+        return Promise.resolve();
+      },
       async isWatching() {
         const message = {
           type: "IS_CONTRACT_MANAGER_WATCHING",
@@ -16530,6 +16779,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)) {
@@ -16579,6 +16833,7 @@ var ServiceWorkerWallet = class _ServiceWorkerWallet extends ServiceWorkerReadon
       settlementConfig: options.settlementConfig,
       walletMode: options.walletMode,
       watcherConfig: options.watcherConfig,
+      lookAheadWindow: options.lookAheadWindow,
       messageTimeouts
     };
     await initializeMessageBus(
@@ -19887,5 +20142,5 @@ function isArkContract(str) {
 }
 
 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-5QVBJUOG.js.map
-//# sourceMappingURL=chunk-5QVBJUOG.js.map
+//# sourceMappingURL=chunk-TS2MTRP4.js.map
+//# sourceMappingURL=chunk-TS2MTRP4.js.map