@arkade-os/sdk 0.4.32 → 0.4.34

package/dist/{chunk-XROGFOPX.js → chunk-HFXEUW55.js}

@@ -1,6 +1,6 @@
-import { craftToSpendTx, Transaction, OP_RETURN_EMPTY_PKSCRIPT, Intent, getArkPsbtFields, CosignerPublicKey, setArkPsbtField, VtxoTaprootTree, maybeArkError, AssetRef, AssetId, AssetOutput, AssetGroup, AssetInput, Packet, Metadata, isEventSourceError, RestArkProvider, RestIndexerProvider, ArkError, BufferReader } from './chunk-6NWNOLL3.js';
-import { isMainnetDescriptor, descriptorIsOurs, contractHandlers, DelegateVtxo, DefaultVtxo, WALLET_RECEIVE_SOURCE, deriveDescriptorLeafPubKey } from './chunk-YA4G7RFB.js';
-import { VtxoScript, timelockToSequence, DEFAULT_NETWORK, DEFAULT_NETWORK_NAME, decodeTapscript, scriptFromTapLeafScript, CLTVMultisigTapscript, ArkAddress, getSequence, CSVMultisigTapscript, getNetwork, MultisigTapscript, networks as networks$1, DEFAULT_ARKADE_SERVER_URL } from './chunk-TU3LVAPX.js';
+import { craftToSpendTx, Transaction, OP_RETURN_EMPTY_PKSCRIPT, Intent, getArkPsbtFields, CosignerPublicKey, setArkPsbtField, VtxoTaprootTree, maybeArkError, AssetRef, AssetId, AssetOutput, AssetGroup, AssetInput, Packet, Metadata, isEventSourceError, RestArkProvider, RestIndexerProvider, ArkError, BufferReader } from './chunk-FXFBPXV3.js';
+import { isMainnetDescriptor, descriptorIsOurs, contractHandlers, DEFAULT_PAGE_SIZE, DelegateVtxo, WALLET_RECEIVE_SOURCE, deriveDescriptorLeafPubKey, DefaultVtxo, BoardingContractHandler } from './chunk-CUSABEUQ.js';
+import { VtxoScript, timelockToSequence, DEFAULT_NETWORK, DEFAULT_NETWORK_NAME, decodeTapscript, scriptFromTapLeafScript, CLTVMultisigTapscript, ArkAddress, CSVMultisigTapscript, getSequence, getNetwork, MultisigTapscript, networks as networks$1, DEFAULT_ARKADE_SERVER_URL } from './chunk-OUVTG72A.js';
 import { sha256, hash160, sha256x2, concatBytes, randomPrivateKeyBytes, pubECDSA, pubSchnorr, equalBytes as equalBytes$1 } from '@scure/btc-signer/utils.js';
 import { SigHash, Script, p2tr, RawWitness, Address, OutScript, p2wpkh, TaprootControlBlock, DEFAULT_SEQUENCE, Transaction as Transaction$2 } from '@scure/btc-signer';
 import { hex, base58, base64 } from '@scure/base';
@@ -1009,7 +1009,7 @@ var ESPLORA_URL = {
   testnet: "https://mempool.space/testnet/api",
   signet: "https://mempool.signet.arkade.sh/api",
   mutinynet: "https://mempool.mutinynet.arkade.sh/api",
-  regtest: "http://localhost:3000"
+  regtest: "http://localhost:3000/api"
 };
 var EsploraProvider = class {
   constructor(baseUrl = ESPLORA_URL[DEFAULT_NETWORK_NAME], opts) {
@@ -1028,6 +1028,9 @@ var EsploraProvider = class {
   }
   async getFeeRate() {
     const response = await fetch(`${this.baseUrl}/fee-estimates`);
+    if (response.status === 404) {
+      return void 0;
+    }
     if (!response.ok) {
       throw new Error(`Failed to fetch fee rate: ${response.statusText}`);
     }
@@ -1153,7 +1156,7 @@ var EsploraProvider = class {
     return stopFunc;
   }
   async getChainTip() {
-    const tipBlocks = await fetch(`${this.baseUrl}/blocks/tip`);
+    const tipBlocks = await fetch(`${this.baseUrl}/blocks`);
     if (!tipBlocks.ok) {
       throw new Error(`Failed to get chain tip: ${tipBlocks.statusText}`);
     }
@@ -1966,12 +1969,22 @@ function verifyTapscriptSignatures(tx, inputIndex, requiredSigners, excludePubke
   }
 }
 function combineTapscriptSigs(signedTx, originalTx) {
+  if (signedTx.inputsLength !== originalTx.inputsLength) {
+    throw new Error(
+      `combineTapscriptSigs: input count mismatch (signedTx ${signedTx.inputsLength}, originalTx ${originalTx.inputsLength})`
+    );
+  }
   for (let i = 0; i < signedTx.inputsLength; i++) {
     const input = originalTx.getInput(i);
     const signedInput = signedTx.getInput(i);
-    if (!input.tapScriptSig) throw new Error("No tapScriptSig");
+    if (!input.tapScriptSig) {
+      throw new Error(`combineTapscriptSigs: originalTx input ${i} has no tapScriptSig`);
+    }
+    if (!signedInput.tapScriptSig) {
+      throw new Error(`combineTapscriptSigs: signedTx input ${i} has no tapScriptSig`);
+    }
     originalTx.updateInput(i, {
-      tapScriptSig: input.tapScriptSig?.concat(signedInput.tapScriptSig)
+      tapScriptSig: input.tapScriptSig.concat(signedInput.tapScriptSig)
     });
   }
   return originalTx;
@@ -2248,12 +2261,12 @@ var FALLBACK_WALLET_DUST_AMOUNT = 330n;
 function getDustAmount(wallet) {
   return "dustAmount" in wallet ? wallet.dustAmount : FALLBACK_WALLET_DUST_AMOUNT;
 }
-function extendCoin(wallet, utxo) {
+function extendCoinWithTapscript(boardingTapscript, utxo) {
   return {
     ...utxo,
-    forfeitTapLeafScript: wallet.boardingTapscript.forfeit(),
-    intentTapLeafScript: wallet.boardingTapscript.forfeit(),
-    tapTree: wallet.boardingTapscript.encode()
+    forfeitTapLeafScript: boardingTapscript.forfeit(),
+    intentTapLeafScript: boardingTapscript.forfeit(),
+    tapTree: boardingTapscript.encode()
   };
 }
 function deriveContractTapscripts(contract) {
@@ -2347,12 +2360,12 @@ function validateRecipients(recipients, dustAmount) {
 
 // src/wallet/vtxo-manager.ts
 function isSweepCapable(wallet) {
-  return "boardingTapscript" in wallet && "onchainProvider" in wallet && "arkProvider" in wallet && "network" in wallet;
+  return "boardingTapscript" in wallet && "onchainProvider" in wallet && "arkProvider" in wallet && "network" in wallet && "signOnchainBoardingTx" in wallet;
 }
 function assertSweepCapable(wallet) {
   if (!isSweepCapable(wallet)) {
     throw new Error(
-      "Boarding UTXO sweep requires a Wallet instance with boardingTapscript, onchainProvider, arkProvider, and network"
+      "Boarding UTXO sweep requires a Wallet instance with boardingTapscript, onchainProvider, arkProvider, network, and signOnchainBoardingTx"
     );
   }
 }
@@ -2368,6 +2381,21 @@ async function runWithCrossInstanceLock(name, fn) {
     await fn();
   });
 }
+var MAX_VTXOS_PER_SETTLEMENT = 50;
+function byValueDescending(vtxos) {
+  return [...vtxos].sort((a, b) => b.value - a.value);
+}
+function byExpiryAscending(vtxos) {
+  const expiryKey = (vtxo) => {
+    if (isRecoverable(vtxo)) return -Infinity;
+    const batchExpiry = vtxo.virtualStatus.batchExpiry;
+    if (isExpired(vtxo)) return batchExpiry ?? -Infinity;
+    if (!batchExpiry) return Infinity;
+    if (new Date(batchExpiry).getFullYear() < 2025) return Infinity;
+    return batchExpiry;
+  };
+  return [...vtxos].sort((a, b) => expiryKey(a) - expiryKey(b));
+}
 var DEFAULT_THRESHOLD_SECONDS = 259200;
 var DEFAULT_THRESHOLD_MS = DEFAULT_THRESHOLD_SECONDS * 1e3;
 var DEFAULT_RENEWAL_CONFIG = {
@@ -2527,10 +2555,20 @@ var VtxoManager = class _VtxoManager {
       withUnrolled: false
     });
     const dustAmount = getDustAmount(this.wallet);
-    const { vtxosToRecover, totalAmount } = getRecoverableWithSubdust(allVtxos, dustAmount);
+    let { vtxosToRecover, totalAmount } = getRecoverableWithSubdust(allVtxos, dustAmount);
     if (vtxosToRecover.length === 0) {
       throw new Error("No recoverable VTXOs found");
     }
+    if (vtxosToRecover.length > MAX_VTXOS_PER_SETTLEMENT) {
+      const recoverableCount = vtxosToRecover.length;
+      const capped = byValueDescending(vtxosToRecover).slice(0, MAX_VTXOS_PER_SETTLEMENT);
+      ({ vtxosToRecover, totalAmount } = getRecoverableWithSubdust(capped, dustAmount));
+      if (vtxosToRecover.length === 0) {
+        throw new Error(
+          `Capped recovery batch (highest-value ${MAX_VTXOS_PER_SETTLEMENT} of ${recoverableCount} recoverable VTXOs) is below the dust threshold ${dustAmount}`
+        );
+      }
+    }
     const arkAddress = await this.wallet.getAddress();
     return this.wallet.settle(
       {
@@ -2680,6 +2718,9 @@ var VtxoManager = class _VtxoManager {
       if (vtxos.length === 0) {
         throw new Error("No VTXOs available to renew");
       }
+      if (vtxos.length > MAX_VTXOS_PER_SETTLEMENT) {
+        vtxos = byExpiryAscending(vtxos).slice(0, MAX_VTXOS_PER_SETTLEMENT);
+      }
       const totalAmount = vtxos.reduce((sum, vtxo) => sum + vtxo.value, 0);
       const dustAmount = getDustAmount(this.wallet);
       if (BigInt(totalAmount) < dustAmount) {
@@ -2787,7 +2828,6 @@ var VtxoManager = class _VtxoManager {
     const boardingAddress = await this.wallet.getBoardingAddress();
     const feeRate = await this.getOnchainProvider().getFeeRate() ?? 1;
     const exitTapLeafScript = this.getBoardingExitLeaf();
-    const sequence = getSequence(exitTapLeafScript);
     const leafScript = exitTapLeafScript[1];
     const leafScriptSize = leafScript.length - 1;
     const controlBlockSize = exitTapLeafScript[0].merklePath.length * 32;
@@ -2808,19 +2848,28 @@ var VtxoManager = class _VtxoManager {
     }
     const tx = new Transaction();
     for (const utxo of expiredUtxos) {
+      const utxoScript = VtxoScript.decode(utxo.tapTree);
+      const utxoExitLeaf = utxoScript.leaves.find(
+        (leaf) => CSVMultisigTapscript.isScriptValid(scriptFromTapLeafScript(leaf)) === true
+      );
+      if (!utxoExitLeaf) {
+        throw new Error(
+          `Boarding sweep: no CSV exit leaf for UTXO ${utxo.txid}:${utxo.vout}`
+        );
+      }
       tx.addInput({
         txid: utxo.txid,
         index: utxo.vout,
         witnessUtxo: {
-          script: this.getBoardingOutputScript(),
+          script: utxoScript.pkScript,
           amount: BigInt(utxo.value)
         },
-        tapLeafScript: [exitTapLeafScript],
-        sequence
+        tapLeafScript: [utxoExitLeaf],
+        sequence: getSequence(utxoExitLeaf)
       });
     }
     tx.addOutputAddress(boardingAddress, outputAmount, this.getNetwork());
-    const signedTx = await this.getIdentity().sign(tx);
+    const signedTx = await this.getSweepWallet().signOnchainBoardingTx(tx);
     signedTx.finalize();
     const txid = await this.getOnchainProvider().broadcastTransaction(signedTx.hex);
     for (const u of expiredUtxos) {
@@ -2847,10 +2896,6 @@ var VtxoManager = class _VtxoManager {
   getBoardingExitLeaf() {
     return this.getSweepWallet().boardingTapscript.exit();
   }
-  /** Returns the pkScript (output script) of the boarding tapscript. */
-  getBoardingOutputScript() {
-    return this.getSweepWallet().boardingTapscript.pkScript;
-  }
   /** Returns the onchain provider for fee estimation and broadcasting. */
   getOnchainProvider() {
     return this.getSweepWallet().onchainProvider;
@@ -2863,10 +2908,6 @@ var VtxoManager = class _VtxoManager {
   getNetwork() {
     return this.getSweepWallet().network;
   }
-  /** Returns the wallet's identity for transaction signing. */
-  getIdentity() {
-    return this.wallet.identity;
-  }
   async initializeSubscription() {
     if (this.settlementConfig === false) {
       return void 0;
@@ -3147,7 +3188,10 @@ var VtxoManager = class _VtxoManager {
       totalAmount += BigInt(u.value) - BigInt(inputFee.satoshis);
     }
     const filteredVtxos = [];
-    for (const v of expiringVtxos) {
+    for (const v of byExpiryAscending(expiringVtxos)) {
+      if (filteredVtxos.length >= MAX_VTXOS_PER_SETTLEMENT) {
+        break;
+      }
       const inputFee = estimator.evalOffchainInput({
         amount: BigInt(v.value),
         type: v.virtualStatus.state === "swept" ? "recoverable" : "vtxo",
@@ -6505,8 +6549,11 @@ function cursorCutoff(requestStartedAt) {
 }
 
 // src/contracts/contractManager.ts
-var DEFAULT_PAGE_SIZE = 500;
+function areCoalescibleContractTypes(a, b) {
+  return a === "default" && b === "boarding" || a === "boarding" && b === "default";
+}
 var SCAN_MAX_INDEX = 1e4;
+var DEFAULT_SCAN_BATCH = 10;
 var ContractManager = class _ContractManager {
   config;
   watcher;
@@ -6630,8 +6677,11 @@ var ContractManager = class _ContractManager {
     const [existing] = await this.getContracts({ script: params.script });
     if (existing) {
       if (existing.type === params.type) return { contract: existing, persisted: false };
+      if (areCoalescibleContractTypes(existing.type, params.type)) {
+        return { contract: existing, persisted: false };
+      }
       throw new Error(
-        `Contract with script ${params.script} already exists with with type ${existing.type}.`
+        `Contract with script ${params.script} already exists with type ${existing.type}.`
       );
     }
     const contract = {
@@ -6660,6 +6710,19 @@ var ContractManager = class _ContractManager {
    *   other handler hit it).
    * - `persistAndWatchContract` rejecting is operational/fatal and
    *   propagates (only `discoverAt` is guarded).
+   * - Within an index the handler probes run concurrently (independent
+   *   network reads); their hits are persisted sequentially in
+   *   `discoverables` order to preserve the first-wins collision tie-break.
+   * - Indices are probed `batchSize` at a time (a second concurrency layer
+   *   over the per-index probes), but each window is CAPPED to
+   *   `gapLimit - unused` indices — the most a serial scan could still reach
+   *   before the gap window is guaranteed to close. So every index probed in
+   *   a window is one a one-index-at-a-time scan would also reach: nothing is
+   *   over-scanned, nothing is discarded, and `materialize`/`discoverAt` are
+   *   invoked on exactly the same index set. The window's hits are still
+   *   processed strictly in ascending index order, so the discovered set,
+   *   persisted rows, `lastIndexUsed`, and `handlerErrors` are byte-for-byte
+   *   identical to the serial path — only the wall-clock differs.
    */
   async scanContracts(opts) {
     const gapLimit = opts.gapLimit ?? 20;
@@ -6668,35 +6731,69 @@ var ContractManager = class _ContractManager {
         `scanContracts: gapLimit must be a positive integer (got ${String(opts.gapLimit)})`
       );
     }
-    const discoverables = contractHandlers.getRegisteredTypes().map((t) => contractHandlers.get(t)).filter(isDiscoverable);
+    const batchSize = opts.batchSize ?? DEFAULT_SCAN_BATCH;
+    if (!Number.isInteger(batchSize) || batchSize <= 0) {
+      throw new Error(
+        `scanContracts: batchSize must be a positive integer (got ${String(opts.batchSize)})`
+      );
+    }
+    const registered = contractHandlers.getRegisteredTypes().map((t) => contractHandlers.get(t)).filter(isDiscoverable);
+    const discoverables = [
+      ...registered.filter((h) => h.type === "boarding"),
+      ...registered.filter((h) => h.type !== "boarding")
+    ];
     const maxIdx = opts.hd ? SCAN_MAX_INDEX : 0;
     const handlerErrors = [];
     let lastIndexUsed = -1;
     let unused = 0;
     let i = 0;
+    const probeIndex = async (index) => {
+      const descriptor = opts.materialize(index);
+      return Promise.all(
+        discoverables.map(async (h) => {
+          try {
+            return {
+              ok: true,
+              found: await h.discoverAt(index, descriptor, opts.deps)
+            };
+          } catch (error) {
+            return { ok: false, error };
+          }
+        })
+      );
+    };
     while (i <= maxIdx && unused < gapLimit) {
-      const descriptor = opts.materialize(i);
-      let hitAtThisIndex = false;
-      for (const h of discoverables) {
-        let found;
-        try {
-          found = await h.discoverAt(i, descriptor, opts.deps);
-        } catch (error) {
-          handlerErrors.push({ handler: h.type, index: i, error });
-          continue;
+      const windowEnd = Math.min(maxIdx, i + Math.min(batchSize, gapLimit - unused) - 1);
+      const windowIndices = [];
+      for (let idx = i; idx <= windowEnd; idx++) windowIndices.push(idx);
+      const windowProbes = await Promise.all(windowIndices.map(probeIndex));
+      for (let w = 0; w < windowIndices.length; w++) {
+        const index = windowIndices[w];
+        const probes = windowProbes[w];
+        let hitAtThisIndex = false;
+        for (let h = 0; h < discoverables.length; h++) {
+          const probe = probes[h];
+          if (!probe.ok) {
+            handlerErrors.push({
+              handler: discoverables[h].type,
+              index,
+              error: probe.error
+            });
+            continue;
+          }
+          for (const c of probe.found) {
+            await this.persistAndWatchContract(c);
+            hitAtThisIndex = true;
+          }
         }
-        for (const c of found) {
-          await this.persistAndWatchContract(c);
-          hitAtThisIndex = true;
+        if (hitAtThisIndex) {
+          lastIndexUsed = index;
+          unused = 0;
+        } else {
+          unused += 1;
         }
       }
-      if (hitAtThisIndex) {
-        lastIndexUsed = i;
-        unused = 0;
-      } else {
-        unused += 1;
-      }
-      i += 1;
+      i = windowEnd + 1;
     }
     if (opts.hd && i > maxIdx && unused < gapLimit) {
       throw new Error(
@@ -7402,7 +7499,8 @@ var WalletReceiveRotator = class _WalletReceiveRotator {
       walletRepository: setup.walletRepository,
       contractRepository: setup.contractRepository,
       serverPubKey: setup.serverPubKey,
-      expectedContractType
+      expectedContractType,
+      baselineReceivePubKey: setup.offchainTapscript.options.pubKey
     };
     let boot;
     try {
@@ -7447,14 +7545,17 @@ var WalletReceiveRotator = class _WalletReceiveRotator {
         receivePubkey: existing.pubKey
       };
     }
-    let descriptor;
-    if (hasPeekableDescriptor(provider)) {
-      descriptor = await provider.getCurrentSigningDescriptor();
+    const current = hasPeekableDescriptor(provider) ? await provider.getCurrentSigningDescriptor() : void 0;
+    if (current === void 0) {
+      const descriptor = await provider.getNextSigningDescriptor();
+      return {
+        rotator: new _WalletReceiveRotator(provider, void 0, opts.logger),
+        receivePubkey: deriveLeafPubkey(descriptor)
+      };
     }
-    descriptor ??= await provider.getNextSigningDescriptor();
     return {
       rotator: new _WalletReceiveRotator(provider, void 0, opts.logger),
-      receivePubkey: deriveLeafPubkey(descriptor)
+      receivePubkey: opts.baselineReceivePubKey ?? deriveLeafPubkey(current)
     };
   }
   /**
@@ -7559,7 +7660,7 @@ var WalletReceiveRotator = class _WalletReceiveRotator {
     const newScript = hex.encode(newTapscript.pkScript);
     const newAddress = newTapscript.address(wallet.network.hrp, wallet.arkServerPublicKey).encode();
     const manager = await wallet.getContractManager();
-    const csvTimelock = newTapscript.options.csvTimelock ?? DefaultVtxo.Script.DEFAULT_TIMELOCK;
+    const csvTimelock = newTapscript.options.csvTimelock;
     const csvTimelockStr = timelockToSequence(csvTimelock).toString();
     const serverPubKeyHex = hex.encode(newTapscript.options.serverPubKey);
     const baseParams = {
@@ -7687,13 +7788,29 @@ var DescriptorSigningProviderMissingError = class extends Error {
 };
 
 // src/wallet/inputSignerRouter.ts
-var DESCRIPTOR_CAPABLE_CONTRACT_TYPES = /* @__PURE__ */ new Set(["default", "delegate"]);
+var DESCRIPTOR_CAPABLE_CONTRACT_TYPES = /* @__PURE__ */ new Set(["default", "delegate", "boarding"]);
 var InputSignerRouter = class {
   constructor(deps) {
     this.deps = deps;
   }
-  async sign(tx, jobs) {
-    if (jobs.length === 0) return tx;
+  /**
+   * Resolve each job to its target signer without invoking signing. The
+   * returned plan is the single source of truth for both {@link sign} and
+   * the batch-eligibility predicate {@link canBatch} — callers that want
+   * to pre-flight a batch path call {@link canBatch} (which delegates
+   * here) so the routing rules never live in two places.
+   *
+   * Throws {@link MissingSigningDescriptorError} for a non-baseline
+   * default/delegate contract whose `metadata.signingDescriptor` is
+   * missing — the same condition that would later abort signing. Failing
+   * here moves the failure earlier, before any PSBT is mutated.
+   */
+  async classify(jobs) {
+    const identityIndexes = [];
+    const descriptorGroups = /* @__PURE__ */ new Map();
+    if (jobs.length === 0) {
+      return { identityIndexes, descriptorGroups };
+    }
     const distinctScripts = Array.from(new Set(jobs.map((j) => hex.encode(j.lookupScript))));
     const contracts = await this.deps.contractRepository.getContracts({
       script: distinctScripts
@@ -7706,8 +7823,6 @@ var InputSignerRouter = class {
     }
     const baselinePubKeyHex = hex.encode(await this.deps.identity.xOnlyPublicKey());
     const boardingScriptHex = hex.encode(this.deps.boardingPkScript);
-    const identityIndexes = [];
-    const descriptorGroups = /* @__PURE__ */ new Map();
     for (const job of jobs) {
       const scriptHex = hex.encode(job.lookupScript);
       const contract = scriptToContract.get(scriptHex);
@@ -7740,6 +7855,31 @@ var InputSignerRouter = class {
         descriptorGroups.set(descriptor, [job.index]);
       }
     }
+    return { identityIndexes, descriptorGroups };
+  }
+  /**
+   * Returns `true` when every signable input across all `jobSets` resolves
+   * to the baseline {@link Identity} key — i.e. the descriptor provider
+   * would not be invoked. Used by the wallet's send/recovery paths to
+   * pre-flight the {@link BatchSignableIdentity.signMultiple} fast path,
+   * which can only fold work a single identity key can sign.
+   *
+   * Accepts several job sets (e.g. an arkTx's jobs plus one set per
+   * checkpoint) and classifies their union in a single pass. Eligibility
+   * is monotonic — the union routes entirely to the baseline key iff every
+   * set does — so this returns the same answer as ANDing the per-set
+   * results, but with one {@link classify} (one repo round-trip + one
+   * `xOnlyPublicKey` call) instead of one per set. Only the routing buckets
+   * matter here, so the input-index collisions produced by flattening jobs
+   * from different transactions are irrelevant.
+   */
+  async canBatch(...jobSets) {
+    const plan = await this.classify(jobSets.flat());
+    return plan.descriptorGroups.size === 0;
+  }
+  async sign(tx, jobs) {
+    if (jobs.length === 0) return tx;
+    const { identityIndexes, descriptorGroups } = await this.classify(jobs);
     let signed = tx;
     if (identityIndexes.length > 0) {
       signed = await this.deps.identity.sign(signed, identityIndexes);
@@ -7780,6 +7920,11 @@ function extractArkProviderUrl(provider) {
   return typeof serverUrl === "string" && serverUrl.length > 0 ? serverUrl : void 0;
 }
 var MAINNET_UNILATERAL_EXIT_DELAY = 605184n;
+function toXOnlyPubKey(pubkey) {
+  if (pubkey.length === 33) return pubkey.slice(1);
+  if (pubkey.length === 32) return pubkey;
+  throw new Error(`invalid signer pubkey length: expected 32 or 33, got ${pubkey.length}`);
+}
 function delayToTimelock(delay) {
   return {
     value: delay,
@@ -7797,6 +7942,30 @@ function dedupeTimelocks(timelocks) {
   }
   return deduped;
 }
+async function ensureWalletContract(manager, params) {
+  await manager.createContract(params);
+}
+async function resolveBoardingBootTapscript(contractRepository, serverPubKey, baseline) {
+  const serverPubKeyHex = hex.encode(serverPubKey);
+  const candidates = await contractRepository.getContracts({
+    type: ["boarding"],
+    state: "active"
+  });
+  const newest = candidates.filter(
+    (c) => c.params.serverPubKey === serverPubKeyHex && c.metadata?.source === WALLET_RECEIVE_SOURCE
+  ).sort((a, b) => {
+    if (b.createdAt !== a.createdAt) return b.createdAt - a.createdAt;
+    return signingDescriptorIndex(b.metadata?.signingDescriptor) - signingDescriptorIndex(a.metadata?.signingDescriptor);
+  })[0];
+  if (!newest?.params.pubKey) return baseline;
+  try {
+    const pubKey = hex.decode(newest.params.pubKey);
+    return new DefaultVtxo.Script({ ...baseline.options, pubKey });
+  } catch (e) {
+    console.warn("Skipping malformed boarding contract at boot", newest.script, e);
+    return baseline;
+  }
+}
 function hasToReadonly(identity) {
   return typeof identity === "object" && identity !== null && "toReadonly" in identity && typeof identity.toReadonly === "function";
 }
@@ -7807,7 +7976,6 @@ var ReadonlyWallet = class _ReadonlyWallet {
     this.onchainProvider = onchainProvider;
     this.indexerProvider = indexerProvider;
     this.arkServerPublicKey = arkServerPublicKey;
-    this.boardingTapscript = boardingTapscript;
     this.dustAmount = dustAmount;
     this.walletRepository = walletRepository;
     this.contractRepository = contractRepository;
@@ -7823,11 +7991,10 @@ var ReadonlyWallet = class _ReadonlyWallet {
       }
     }
     this._offchainTapscript = offchainTapscript;
+    this._boardingTapscript = boardingTapscript;
     this.watcherConfig = watcherConfig;
     this._assetManager = new ReadonlyAssetManager(this.indexerProvider);
-    this.walletContractTimelocks = walletContractTimelocks && walletContractTimelocks.length > 0 ? dedupeTimelocks(walletContractTimelocks) : [
-      this.offchainTapscript.options.csvTimelock ?? DefaultVtxo.Script.DEFAULT_TIMELOCK
-    ];
+    this.walletContractTimelocks = walletContractTimelocks && walletContractTimelocks.length > 0 ? dedupeTimelocks(walletContractTimelocks) : [this.offchainTapscript.options.csvTimelock];
   }
   _contractManager;
   _contractManagerInitializing;
@@ -7851,6 +8018,17 @@ var ReadonlyWallet = class _ReadonlyWallet {
    * {@link WalletReceiveRotator.rotate} is the sole intended caller of.
    */
   _offchainTapscript;
+  /**
+   * Backing field for the current boarding tapscript (the QR / onboarding
+   * target). Read via the public `boardingTapscript` getter; written only
+   * by {@link Wallet.setBoardingTapscriptForRotation}, the sanctioned
+   * boarding-rotation write path (analogue of `_offchainTapscript`). It is
+   * a *current value*, not a fixed setup constant, because per-derivation
+   * boarding rotation (plan §6-II) swaps it when a fresh boarding address
+   * is explicitly allocated. Static / `auto` wallets never rotate it, so
+   * it stays the index-0 baseline for their lifetime.
+   */
+  _boardingTapscript;
   /**
    * Currently-active receive tapscript. Read-only from the outside;
    * mutated only via {@link Wallet.setOffchainTapscriptForRotation}
@@ -7859,6 +8037,52 @@ var ReadonlyWallet = class _ReadonlyWallet {
   get offchainTapscript() {
     return this._offchainTapscript;
   }
+  /**
+   * The wallet's current boarding tapscript (the on-chain onboarding
+   * target). Read-only from the outside; mutated only via
+   * {@link Wallet.setBoardingTapscriptForRotation} when a fresh boarding
+   * address is explicitly allocated. Single-valued for static / `auto`
+   * wallets.
+   */
+  get boardingTapscript() {
+    return this._boardingTapscript;
+  }
+  /**
+   * Listeners fired after the boarding tapscript rotates to a fresh index
+   * (see {@link Wallet.setBoardingTapscriptForRotation}). A live
+   * {@link notifyIncomingFunds} onchain watcher registers one so it can
+   * re-subscribe to include the newly allocated boarding address within the
+   * same session — without it, a deposit to the fresh address wouldn't fire
+   * a notification until the watcher's next re-init. Always empty for
+   * readonly / static / `auto` wallets, which never rotate boarding.
+   */
+  _boardingRotationListeners = /* @__PURE__ */ new Set();
+  /**
+   * Register a listener invoked synchronously after each boarding rotation.
+   * Returns an unsubscribe function. Protected: only internal subscribers
+   * (the incoming-funds watcher) participate.
+   */
+  onBoardingRotation(listener) {
+    this._boardingRotationListeners.add(listener);
+    return () => {
+      this._boardingRotationListeners.delete(listener);
+    };
+  }
+  /**
+   * Notify boarding-rotation listeners. Called by the boarding-rotation
+   * write path ({@link Wallet.setBoardingTapscriptForRotation}) once the new
+   * tapscript is in place. A throwing listener is isolated so it can neither
+   * break the rotation nor starve sibling listeners.
+   */
+  notifyBoardingRotation() {
+    for (const listener of this._boardingRotationListeners) {
+      try {
+        listener();
+      } catch (e) {
+        console.warn("Boarding-rotation listener failed", e);
+      }
+    }
+  }
   /**
    * Protected helper to set up shared wallet configuration.
    * Extracts common logic used by both ReadonlyWallet.create() and Wallet.create().
@@ -7933,9 +8157,10 @@ var ReadonlyWallet = class _ReadonlyWallet {
       csvTimelock: exitTimelock
     };
     const offchainTapscript = !delegatePubKey ? new DefaultVtxo.Script(offchainOptions) : new DelegateVtxo.Script({ ...offchainOptions, delegatePubKey });
-    const boardingTapscript = new DefaultVtxo.Script({
-      ...offchainOptions,
-      csvTimelock: boardingTimelock
+    const boardingTapscript = BoardingContractHandler.createScript({
+      pubKey: hex.encode(pubKey),
+      serverPubKey: hex.encode(serverPubKey),
+      csvTimelock: timelockToSequence(boardingTimelock).toString()
     });
     const walletRepository = config.storage?.walletRepository ?? new IndexedDBWalletRepository();
     const contractRepository = config.storage?.contractRepository ?? new IndexedDBContractRepository();
@@ -8098,43 +8323,59 @@ var ReadonlyWallet = class _ReadonlyWallet {
     await clearSyncCursor(this.walletRepository);
   }
   /**
-   * Build a transaction history view for the wallet's boarding address.
+   * The on-chain (P2TR) addresses of every boarding tapscript this wallet
+   * uses — the current address plus any historical rotated boarding
+   * addresses. The aggregating boarding readers (history, notifications) fan
+   * out over this set so deposits at previous boarding addresses are still
+   * surfaced (plan §6-IV); {@link getBoardingAddress} stays single-valued.
+   */
+  async getBoardingAddresses() {
+    const tapscripts = await this.getBoardingTapscripts();
+    return tapscripts.map((t) => t.onchainAddress(this.network));
+  }
+  /**
+   * Build a transaction history view across the wallet's boarding addresses
+   * (current + historical rotated; plan §6-IV.1).
    */
   async getBoardingTxs() {
     const utxos = [];
     const commitmentsToIgnore = /* @__PURE__ */ new Set();
-    const boardingAddress = await this.getBoardingAddress();
-    const txs = await this.onchainProvider.getTransactions(boardingAddress);
+    const tapscripts = await this.getBoardingTapscripts();
     const outspendCache = /* @__PURE__ */ new Map();
-    for (const tx of txs) {
-      for (let i = 0; i < tx.vout.length; i++) {
-        const vout = tx.vout[i];
-        if (vout.scriptpubkey_address === boardingAddress) {
-          let spentStatuses = outspendCache.get(tx.txid);
-          if (!spentStatuses) {
-            spentStatuses = await this.onchainProvider.getTxOutspends(tx.txid);
-            outspendCache.set(tx.txid, spentStatuses);
-          }
-          const spentStatus = spentStatuses[i];
-          if (spentStatus?.spent) {
-            commitmentsToIgnore.add(spentStatus.txid);
+    for (const tapscript of tapscripts) {
+      const boardingAddress = tapscript.onchainAddress(this.network);
+      const scriptHex = hex.encode(tapscript.pkScript);
+      const txs = await this.onchainProvider.getTransactions(boardingAddress);
+      for (const tx of txs) {
+        for (let i = 0; i < tx.vout.length; i++) {
+          const vout = tx.vout[i];
+          if (vout.scriptpubkey_address === boardingAddress) {
+            let spentStatuses = outspendCache.get(tx.txid);
+            if (!spentStatuses) {
+              spentStatuses = await this.onchainProvider.getTxOutspends(tx.txid);
+              outspendCache.set(tx.txid, spentStatuses);
+            }
+            const spentStatus = spentStatuses[i];
+            if (spentStatus?.spent) {
+              commitmentsToIgnore.add(spentStatus.txid);
+            }
+            utxos.push({
+              txid: tx.txid,
+              vout: i,
+              value: Number(vout.value),
+              status: {
+                confirmed: tx.status.confirmed,
+                block_time: tx.status.block_time
+              },
+              isUnrolled: true,
+              virtualStatus: {
+                state: spentStatus?.spent ? "spent" : "settled",
+                commitmentTxIds: spentStatus?.spent ? [spentStatus.txid] : void 0
+              },
+              createdAt: tx.status.confirmed ? new Date(tx.status.block_time * 1e3) : /* @__PURE__ */ new Date(0),
+              script: scriptHex
+            });
           }
-          utxos.push({
-            txid: tx.txid,
-            vout: i,
-            value: Number(vout.value),
-            status: {
-              confirmed: tx.status.confirmed,
-              block_time: tx.status.block_time
-            },
-            isUnrolled: true,
-            virtualStatus: {
-              state: spentStatus?.spent ? "spent" : "settled",
-              commitmentTxIds: spentStatus?.spent ? [spentStatus.txid] : void 0
-            },
-            createdAt: tx.status.confirmed ? new Date(tx.status.block_time * 1e3) : /* @__PURE__ */ new Date(0),
-            script: hex.encode(this.boardingTapscript.pkScript)
-          });
         }
       }
     }
@@ -8164,48 +8405,130 @@ var ReadonlyWallet = class _ReadonlyWallet {
     };
   }
   /**
-   * Fetch and cache onchain inputs (UTXOs) received at the boarding address.
+   * The set of boarding tapscripts whose on-chain UTXOs belong to this
+   * wallet — the current display tapscript plus every historical boarding
+   * address it has used. Under per-derivation rotation (plan §6-II) a wallet
+   * can hold unspent boarding UTXOs at several addresses at once, so fund
+   * discovery / spending must enumerate them all, not just the current one
+   * (plan §6-III.1). Deduplicated by scriptPubKey.
+   *
+   * Always includes the index-0 baseline (identity x-only key), which covers
+   * the degenerate equal-delay case where the index-0 boarding row is
+   * coalesced onto a `default` row and so isn't a `boarding`-typed contract.
    */
-  async getBoardingUtxos() {
-    const boardingAddress = await this.getBoardingAddress();
-    const boardingUtxos = await this.onchainProvider.getCoins(boardingAddress);
-    const utxos = boardingUtxos.map((utxo) => {
-      return extendCoin(this, utxo);
+  async getBoardingTapscripts() {
+    const byScript = /* @__PURE__ */ new Map();
+    const add = (s) => byScript.set(hex.encode(s.pkScript), s);
+    const boardingCsv = this.boardingTapscript.options.csvTimelock ?? DefaultVtxo.Script.DEFAULT_TIMELOCK;
+    add(
+      new DefaultVtxo.Script({
+        pubKey: await this.identity.xOnlyPublicKey(),
+        serverPubKey: this.boardingTapscript.options.serverPubKey,
+        csvTimelock: boardingCsv
+      })
+    );
+    add(this.boardingTapscript);
+    const serverPubKeyHex = hex.encode(this.boardingTapscript.options.serverPubKey);
+    const boardingContracts = await this.contractRepository.getContracts({
+      type: ["boarding"]
     });
-    await this.walletRepository.saveUtxos(boardingAddress, utxos);
-    return utxos;
+    for (const c of boardingContracts) {
+      if (c.params.serverPubKey !== serverPubKeyHex) continue;
+      try {
+        add(BoardingContractHandler.createScript(c.params));
+      } catch (e) {
+        console.warn("Skipping malformed boarding contract", c.script, e);
+      }
+    }
+    return [...byScript.values()];
+  }
+  /**
+   * Fetch and cache onchain inputs (UTXOs) received at the wallet's boarding
+   * addresses — the current address plus any historical rotated boarding
+   * addresses that still hold unspent UTXOs (plan §6-III.1). Each UTXO is
+   * annotated with the tapscript of the address it actually sits on, so the
+   * spending path forfeits / exits it with the correct per-index leaves.
+   */
+  async getBoardingUtxos() {
+    const tapscripts = await this.getBoardingTapscripts();
+    const all = [];
+    for (const tapscript of tapscripts) {
+      const address = tapscript.onchainAddress(this.network);
+      const coins = await this.onchainProvider.getCoins(address);
+      const utxos = coins.map((utxo) => extendCoinWithTapscript(tapscript, utxo));
+      await this.walletRepository.saveUtxos(address, utxos);
+      all.push(...utxos);
+    }
+    return all;
   }
   /**
    * Subscribe to onchain and offchain notifications for newly received funds.
    *
+   * The onchain watcher tracks the full boarding-address set (current +
+   * historical rotated). When boarding rotates *after* subscribing — e.g.
+   * rotate-on-board allocates a fresh address via
+   * {@link getNewBoardingAddress} — the watcher automatically re-subscribes
+   * to widen its set, so a deposit to the new address fires a notification
+   * within the same session (no watcher re-init required). The re-subscribe
+   * is driven by {@link onBoardingRotation}; static / `auto` / readonly
+   * wallets never rotate boarding, so it never fires for them.
+   *
    * @param eventCallback - Callback invoked when matching funds are detected
    * @returns A function that stops the subscriptions
    */
   async notifyIncomingFunds(eventCallback) {
     const arkAddress = await this.getAddress();
-    const boardingAddress = await this.getBoardingAddress();
     let onchainStopFunc;
     let indexerStopFunc;
-    if (this.onchainProvider && boardingAddress) {
-      const findVoutOnTx = (tx) => {
-        return tx.vout.findIndex((v) => v.scriptpubkey_address === boardingAddress);
-      };
-      onchainStopFunc = await this.onchainProvider.watchAddresses(
-        [boardingAddress],
-        (txs) => {
-          const coins = txs.filter((tx) => findVoutOnTx(tx) !== -1).map((tx) => {
-            const { txid, status } = tx;
-            const vout = findVoutOnTx(tx);
-            const value = Number(tx.vout[vout].value);
-            return { txid, vout, value, status };
-          });
-          eventCallback({
-            type: "utxo",
-            coins
-          });
+    let boardingRotationStopFunc;
+    let stopped = false;
+    let onchainChain = Promise.resolve();
+    const subscribeOnchain = () => {
+      onchainChain = onchainChain.then(async () => {
+        if (stopped || !this.onchainProvider) return;
+        const boardingAddresses = await this.getBoardingAddresses();
+        if (boardingAddresses.length === 0) return;
+        const boardingAddressSet = new Set(boardingAddresses);
+        const previousStop = onchainStopFunc;
+        const stop = await this.onchainProvider.watchAddresses(
+          boardingAddresses,
+          (txs) => {
+            const coins = txs.flatMap((tx) => {
+              const { txid, status } = tx;
+              const matched = [];
+              tx.vout.forEach((v, vout) => {
+                if (boardingAddressSet.has(v.scriptpubkey_address)) {
+                  matched.push({
+                    txid,
+                    vout,
+                    value: Number(v.value),
+                    status
+                  });
+                }
+              });
+              return matched;
+            });
+            eventCallback({
+              type: "utxo",
+              coins
+            });
+          }
+        );
+        if (stopped) {
+          stop();
+          return;
         }
-      );
-    }
+        onchainStopFunc = stop;
+        previousStop?.();
+      }).catch((e) => {
+        console.warn("Failed to (re)subscribe boarding-funds watcher", e);
+      });
+      return onchainChain;
+    };
+    boardingRotationStopFunc = this.onBoardingRotation(() => {
+      void subscribeOnchain();
+    });
+    await subscribeOnchain();
     if (this.indexerProvider && arkAddress) {
       const cm = await this.getContractManager();
       let annotationQueue = Promise.resolve();
@@ -8234,7 +8557,10 @@ var ReadonlyWallet = class _ReadonlyWallet {
       });
     }
     const stopFunc = () => {
+      stopped = true;
+      boardingRotationStopFunc?.();
       onchainStopFunc?.();
+      onchainStopFunc = void 0;
       indexerStopFunc?.();
     };
     return stopFunc;
@@ -8348,7 +8674,7 @@ var ReadonlyWallet = class _ReadonlyWallet {
         csvTimelock
       });
       const defaultScriptHex = hex.encode(defaultScript.pkScript);
-      await manager.createContract({
+      await ensureWalletContract(manager, {
         type: "default",
         params: {
           pubKey: hex.encode(defaultScript.options.pubKey),
@@ -8381,6 +8707,23 @@ var ReadonlyWallet = class _ReadonlyWallet {
         });
       }
     }
+    const boardingCsvTimelock = this.boardingTapscript.options.csvTimelock ?? DefaultVtxo.Script.DEFAULT_TIMELOCK;
+    const baselineBoarding = new DefaultVtxo.Script({
+      pubKey: baselinePubkey,
+      serverPubKey: this.boardingTapscript.options.serverPubKey,
+      csvTimelock: boardingCsvTimelock
+    });
+    await ensureWalletContract(manager, {
+      type: "boarding",
+      params: {
+        pubKey: hex.encode(baselineBoarding.options.pubKey),
+        serverPubKey: hex.encode(baselineBoarding.options.serverPubKey),
+        csvTimelock: timelockToSequence(boardingCsvTimelock).toString()
+      },
+      script: hex.encode(baselineBoarding.pkScript),
+      address: baselineBoarding.address(this.network.hrp, this.arkServerPublicKey).encode(),
+      state: "active"
+    });
     return manager;
   }
   /** Dispose wallet-owned managers and release background resources. */
@@ -8478,6 +8821,72 @@ var Wallet2 = class _Wallet extends ReadonlyWallet {
   setOffchainTapscriptForRotation(tapscript) {
     this._offchainTapscript = tapscript;
   }
+  /**
+   * @internal Sole write path for `boardingTapscript` after construction.
+   * Called by {@link Wallet.getNewBoardingAddress} once the rotated
+   * boarding contract has been persisted. External code must treat
+   * `boardingTapscript` as read-only.
+   */
+  setBoardingTapscriptForRotation(tapscript) {
+    this._boardingTapscript = tapscript;
+    this.notifyBoardingRotation();
+  }
+  /**
+   * Allocate and return a *fresh* on-chain boarding address, rotating the
+   * wallet's current boarding tapscript to a new HD index.
+   *
+   * This is the explicit boarding allocator — the analogue of dotnet's
+   * `GetNextContract(NextContractPurpose.Boarding)`. Unlike
+   * {@link getBoardingAddress} (a stable read of the current display
+   * address that never burns an index), each call here:
+   *
+   * - allocates the next index from the shared HD stream (so boarding and
+   *   L2 receive interleave on one monotonic index);
+   * - builds the boarding tapscript at that index with the boarding-exit
+   *   CSV;
+   * - persists an `active` `boarding` contract tagged
+   *   {@link WALLET_RECEIVE_SOURCE} (with its `signingDescriptor`) so the
+   *   ContractWatcher monitors it, boot can restore it as the current
+   *   boarding address, and descriptor-aware signing can recover the
+   *   per-index key;
+   * - swaps the wallet's current `boardingTapscript`.
+   *
+   * Gated by `walletMode`: a static / `auto` wallet has no descriptor
+   * provider and keeps a single index-0 boarding address for its lifetime,
+   * so this returns the existing {@link getBoardingAddress} unchanged
+   * (no rotation, no index burned).
+   */
+  async getNewBoardingAddress() {
+    const provider = this._descriptorProvider;
+    if (!provider) {
+      return this.getBoardingAddress();
+    }
+    const descriptor = await provider.getNextSigningDescriptor();
+    const pubKey = deriveDescriptorLeafPubKey(descriptor);
+    const newBoarding = new DefaultVtxo.Script({
+      ...this._boardingTapscript.options,
+      pubKey
+    });
+    const csvTimelock = newBoarding.options.csvTimelock ?? DefaultVtxo.Script.DEFAULT_TIMELOCK;
+    const manager = await this.getContractManager();
+    await manager.createContract({
+      type: "boarding",
+      params: {
+        pubKey: hex.encode(pubKey),
+        serverPubKey: hex.encode(newBoarding.options.serverPubKey),
+        csvTimelock: timelockToSequence(csvTimelock).toString()
+      },
+      script: hex.encode(newBoarding.pkScript),
+      address: newBoarding.address(this.network.hrp, this.arkServerPublicKey).encode(),
+      state: "active",
+      metadata: {
+        source: WALLET_RECEIVE_SOURCE,
+        signingDescriptor: descriptor
+      }
+    });
+    this.setBoardingTapscriptForRotation(newBoarding);
+    return newBoarding.onchainAddress(this.network);
+  }
   /**
    * Async mutex that serializes all operations submitting VTXOs to the Arkade
    * server (`settle`, `send`, `sendBitcoin`). This prevents VtxoManager's
@@ -8562,12 +8971,25 @@ var Wallet2 = class _Wallet extends ReadonlyWallet {
     const staticDescriptor = hd ? void 0 : `tr(${hex.encode(await this.identity.xOnlyPublicKey())})`;
     const materialize = (index) => hd ? provider.materializeDescriptorAt(index) : staticDescriptor;
     const delegatePubKey = this.offchainTapscript instanceof DelegateVtxo.Script ? this.offchainTapscript.options.delegatePubKey : void 0;
+    const arkInfo = await this.arkProvider.getInfo();
+    const currentSignerPubKey = toXOnlyPubKey(hex.decode(arkInfo.signerPubkey));
+    const deprecatedSignerPubKeys = arkInfo.deprecatedSigners.map(
+      (s) => toXOnlyPubKey(hex.decode(s.pubkey))
+    );
     const deps = {
       indexerProvider: this.indexerProvider,
       onchainProvider: this.onchainProvider,
       network: { hrp: this.network.hrp },
-      serverPubKey: this.offchainTapscript.options.serverPubKey,
+      // Full network for the boarding on-chain (P2TR) probe — the
+      // `{ hrp }` shape above lacks the `bech32` data
+      // `VtxoScript.onchainAddress` needs (plan §6-I.1).
+      onchainNetwork: this.network,
+      serverPubKey: currentSignerPubKey,
+      deprecatedSignerPubKeys,
       csvTimelocks: this.walletContractTimelocks,
+      // Boarding-exit CSV so the boarding handler can build its
+      // candidate script (distinct from the unilateral-exit matrix).
+      boardingTimelock: this.boardingTapscript.options.csvTimelock ?? DefaultVtxo.Script.DEFAULT_TIMELOCK,
       delegatePubKey
     };
     const result = await manager.scanContracts({
@@ -8699,6 +9121,16 @@ var Wallet2 = class _Wallet extends ReadonlyWallet {
       boot?.rotator,
       boot?.provider
     );
+    if (boot?.provider) {
+      const resolvedBoarding = await resolveBoardingBootTapscript(
+        setup.contractRepository,
+        setup.serverPubKey,
+        setup.boardingTapscript
+      );
+      if (resolvedBoarding !== setup.boardingTapscript) {
+        wallet.setBoardingTapscriptForRotation(resolvedBoarding);
+      }
+    }
     await wallet.getVtxoManager();
     return wallet;
   }
@@ -8866,7 +9298,10 @@ var Wallet2 = class _Wallet extends ReadonlyWallet {
       }
       const vtxos = await this.getVtxos({ withRecoverable: true });
       const filteredVtxos = [];
-      for (const vtxo of vtxos) {
+      for (const vtxo of byValueDescending(vtxos)) {
+        if (filteredVtxos.length >= MAX_VTXOS_PER_SETTLEMENT) {
+          break;
+        }
         const inputFee = estimator.evalOffchainInput({
           amount: BigInt(vtxo.value),
           type: vtxo.virtualStatus.state === "swept" ? "recoverable" : "vtxo",
@@ -8999,6 +9434,7 @@ var Wallet2 = class _Wallet extends ReadonlyWallet {
         eventCallback: eventCallback ? (event) => Promise.resolve(eventCallback(event)) : void 0
       });
       await this.updateDbAfterSettle(params.inputs, commitmentTxid);
+      await this.maybeRotateBoardingAfterBoard(params.inputs);
       return commitmentTxid;
     } catch (error) {
       const inputIds = params.inputs.map((i) => `${i.txid}:${i.vout}`).join(",");
@@ -9016,6 +9452,41 @@ var Wallet2 = class _Wallet extends ReadonlyWallet {
       });
     }
   }
+  /**
+   * Rotate the boarding address after a board (rotate-on-board trigger).
+   *
+   * Mirrors {@link WalletReceiveRotator}'s L2 rotation, but driven by a
+   * board instead of a `vtxo_received` event: when a settle consumes at
+   * least one boarding (on-chain) UTXO, the current boarding address has
+   * served its purpose, so we allocate a fresh one via
+   * {@link getNewBoardingAddress}. A settle that consumed only VTXOs (a
+   * renewal / offboard) is not a board and leaves the boarding address
+   * untouched.
+   *
+   * Boarding inputs are the non-VTXO coins (no `virtualStatus`), the same
+   * discriminator {@link handleSettlementFinalizationEvent} uses; the
+   * `typeof` guard skips arknote string inputs before the `in` test.
+   *
+   * No-ops for static / `auto` wallets (no descriptor provider — boarding
+   * stays on its fixed index-0 address). Best-effort and non-fatal: the
+   * settle has already committed and its txid must be returned, so a
+   * rotation failure is logged and swallowed rather than thrown. Funds at
+   * the retired boarding address remain discoverable — the old `boarding`
+   * contract stays active and {@link getBoardingUtxos} fans out over the
+   * full historical boarding set.
+   */
+  async maybeRotateBoardingAfterBoard(inputs) {
+    if (!this._descriptorProvider) return;
+    const consumedBoarding = inputs.some(
+      (input) => typeof input !== "string" && !("virtualStatus" in input)
+    );
+    if (!consumedBoarding) return;
+    try {
+      await this.getNewBoardingAddress();
+    } catch (e) {
+      console.warn("Failed to rotate boarding address after board", e);
+    }
+  }
   async handleSettlementFinalizationEvent(event, inputs, forfeitOutputScript, connectorsGraph) {
     const signedForfeits = [];
     const isVtxo = (input) => "virtualStatus" in input;
@@ -9226,6 +9697,19 @@ var Wallet2 = class _Wallet extends ReadonlyWallet {
     }
     return jobs;
   }
+  /**
+   * @internal Sign an on-chain boarding exit / sweep transaction, routing
+   * each input to the correct key by its `witnessUtxo.script`: the identity
+   * for index-0 / static boarding, the per-index descriptor for a rotated
+   * boarding UTXO (plan §6-III.3). Used by
+   * {@link VtxoManager.sweepExpiredBoardingUtxos}; without it, the
+   * unilateral exit of a rotated boarding UTXO would be signed with the
+   * wrong (index-0) key and rejected.
+   */
+  async signOnchainBoardingTx(tx) {
+    const signed = await this._signerRouter.sign(tx, this.inputSigningJobsFromWitnessUtxos(tx));
+    return signed;
+  }
   async safeRegisterIntent(intent, inputs) {
     try {
       return await this.arkProvider.registerIntent(intent);
@@ -9330,16 +9814,38 @@ var Wallet2 = class _Wallet extends ReadonlyWallet {
           seen.add(pendingTx.arkTxid);
           batchPending.push(pendingTx.arkTxid);
           try {
-            const finalCheckpoints = await Promise.all(
-              pendingTx.signedCheckpointTxs.map(async (c) => {
-                const tx = Transaction$2.fromPSBT(base64.decode(c));
-                const signedCheckpoint = await this._signerRouter.sign(
-                  tx,
-                  this.inputSigningJobsFromWitnessUtxos(tx)
-                );
-                return base64.encode(signedCheckpoint.toPSBT());
-              })
+            const checkpointTxs = pendingTx.signedCheckpointTxs.map(
+              (c) => Transaction$2.fromPSBT(base64.decode(c))
+            );
+            const checkpointJobs = checkpointTxs.map(
+              (tx) => this.inputSigningJobsFromWitnessUtxos(tx)
             );
+            const identity = this.identity;
+            const batchEligible = isBatchSignable(identity) && await this._signerRouter.canBatch(...checkpointJobs);
+            let finalCheckpoints;
+            if (batchEligible) {
+              const requests = checkpointTxs.map((tx, i) => ({
+                tx,
+                inputIndexes: checkpointJobs[i].map((j) => j.index)
+              }));
+              const signed = await identity.signMultiple(requests);
+              if (signed.length !== requests.length) {
+                throw new Error(
+                  `signMultiple returned ${signed.length} transactions, expected ${requests.length}`
+                );
+              }
+              finalCheckpoints = signed.map((tx) => base64.encode(tx.toPSBT()));
+            } else {
+              finalCheckpoints = await Promise.all(
+                checkpointTxs.map(async (tx, i) => {
+                  const signedCheckpoint = await this._signerRouter.sign(
+                    tx,
+                    checkpointJobs[i]
+                  );
+                  return base64.encode(signedCheckpoint.toPSBT());
+                })
+              );
+            }
             await this.arkProvider.finalizeTx(pendingTx.arkTxid, finalCheckpoints);
             batchFinalized.push(pendingTx.arkTxid);
           } catch (error) {
@@ -9567,22 +10073,65 @@ var Wallet2 = class _Wallet extends ReadonlyWallet {
       index,
       lookupScript: VtxoScript.decode(input.tapTree).pkScript
     }));
-    const signedVirtualTx = await this._signerRouter.sign(offchainTx.arkTx, arkTxJobs);
+    const checkpointJobs = offchainTx.checkpoints.map(
+      (c) => this.inputSigningJobsFromWitnessUtxos(c)
+    );
+    let signedVirtualTx;
+    let userSignedCheckpoints;
+    const identity = this.identity;
+    const batchEligible = isBatchSignable(identity) && await this._signerRouter.canBatch(arkTxJobs, ...checkpointJobs);
+    if (batchEligible) {
+      const requests = [
+        {
+          tx: offchainTx.arkTx.clone(),
+          inputIndexes: arkTxJobs.map((j) => j.index)
+        },
+        ...offchainTx.checkpoints.map((c, i) => ({
+          tx: c.clone(),
+          inputIndexes: checkpointJobs[i].map((j) => j.index)
+        }))
+      ];
+      const signed = await identity.signMultiple(requests);
+      if (signed.length !== requests.length) {
+        throw new Error(
+          `signMultiple returned ${signed.length} transactions, expected ${requests.length}`
+        );
+      }
+      const [firstSignedTx, ...signedCheckpoints] = signed;
+      signedVirtualTx = firstSignedTx;
+      userSignedCheckpoints = signedCheckpoints;
+    } else {
+      signedVirtualTx = await this._signerRouter.sign(offchainTx.arkTx, arkTxJobs);
+    }
     await this.setPendingTxFlag(true);
     const { arkTxid, signedCheckpointTxs } = await this.arkProvider.submitTx(
       base64.encode(signedVirtualTx.toPSBT()),
       offchainTx.checkpoints.map((c) => base64.encode(c.toPSBT()))
     );
-    const finalCheckpoints = await Promise.all(
-      signedCheckpointTxs.map(async (c) => {
-        const tx = Transaction$2.fromPSBT(base64.decode(c));
-        const signedCheckpoint = await this._signerRouter.sign(
-          tx,
-          this.inputSigningJobsFromWitnessUtxos(tx)
+    let finalCheckpoints;
+    if (userSignedCheckpoints) {
+      if (signedCheckpointTxs.length !== userSignedCheckpoints.length) {
+        throw new Error(
+          `submitTx returned ${signedCheckpointTxs.length} checkpoints, expected ${userSignedCheckpoints.length}`
         );
-        return base64.encode(signedCheckpoint.toPSBT());
-      })
-    );
+      }
+      finalCheckpoints = signedCheckpointTxs.map((c, i) => {
+        const serverSigned = Transaction$2.fromPSBT(base64.decode(c));
+        combineTapscriptSigs(userSignedCheckpoints[i], serverSigned);
+        return base64.encode(serverSigned.toPSBT());
+      });
+    } else {
+      finalCheckpoints = await Promise.all(
+        signedCheckpointTxs.map(async (c) => {
+          const tx = Transaction$2.fromPSBT(base64.decode(c));
+          const signedCheckpoint = await this._signerRouter.sign(
+            tx,
+            this.inputSigningJobsFromWitnessUtxos(tx)
+          );
+          return base64.encode(signedCheckpoint.toPSBT());
+        })
+      );
+    }
     await this.arkProvider.finalizeTx(arkTxid, finalCheckpoints);
     try {
       await this.setPendingTxFlag(false);
@@ -9727,10 +10276,9 @@ var Wallet2 = class _Wallet extends ReadonlyWallet {
   // mark virtual outputs as spent/settled, remove boarding inputs
   async updateDbAfterSettle(inputs, commitmentTxid) {
     try {
-      const boardingAddress = await this.getBoardingAddress();
       const spentVtxos = [];
       const inputArkTxIds = /* @__PURE__ */ new Set();
-      const boardingUtxoToRemove = /* @__PURE__ */ new Set();
+      const boardingRemovalsByAddress = /* @__PURE__ */ new Map();
       const isVtxo = (input) => "virtualStatus" in input;
       const vtxoInputs = inputs.filter(isVtxo);
       const cm = await this.getContractManager();
@@ -9752,7 +10300,20 @@ var Wallet2 = class _Wallet extends ReadonlyWallet {
             isSpent: true
           });
         } else {
-          boardingUtxoToRemove.add(`${input.txid}:${input.vout}`);
+          let sourceAddress;
+          try {
+            sourceAddress = VtxoScript.decode(input.tapTree).onchainAddress(
+              this.network
+            );
+          } catch {
+            sourceAddress = this.boardingTapscript.onchainAddress(this.network);
+          }
+          let set = boardingRemovalsByAddress.get(sourceAddress);
+          if (!set) {
+            set = /* @__PURE__ */ new Set();
+            boardingRemovalsByAddress.set(sourceAddress, set);
+          }
+          set.add(`${input.txid}:${input.vout}`);
         }
       }
       if (spentVtxos.length > 0) {
@@ -9784,14 +10345,12 @@ var Wallet2 = class _Wallet extends ReadonlyWallet {
           );
         }
       }
-      if (boardingUtxoToRemove.size > 0) {
-        const currentUtxos = await this.walletRepository.getUtxos(boardingAddress);
-        const filtered = currentUtxos.filter(
-          (u) => !boardingUtxoToRemove.has(`${u.txid}:${u.vout}`)
-        );
-        await this.walletRepository.deleteUtxos(boardingAddress);
+      for (const [address, toRemove] of boardingRemovalsByAddress) {
+        const currentUtxos = await this.walletRepository.getUtxos(address);
+        const filtered = currentUtxos.filter((u) => !toRemove.has(`${u.txid}:${u.vout}`));
+        await this.walletRepository.deleteUtxos(address);
         if (filtered.length > 0) {
-          await this.walletRepository.saveUtxos(boardingAddress, filtered);
+          await this.walletRepository.saveUtxos(address, filtered);
         }
       }
     } catch (e) {
@@ -9832,12 +10391,17 @@ function selectVirtualCoins(coins, targetAmount) {
 }
 async function waitForIncomingFunds(wallet) {
   let stopFunc;
+  let settled = false;
   return new Promise((resolve) => {
-    wallet.notifyIncomingFunds((coins) => {
-      resolve(coins);
-      if (stopFunc) stopFunc();
+    wallet.notifyIncomingFunds((funds) => {
+      const hasFunds = funds.type === "utxo" ? funds.coins.length > 0 : funds.newVtxos.length > 0;
+      if (settled || !hasFunds) return;
+      settled = true;
+      resolve(funds);
+      stopFunc?.();
     }).then((stop) => {
       stopFunc = stop;
+      if (settled) stop();
     });
   });
 }
@@ -11186,9 +11750,7 @@ var WalletMessageHandler = class {
           );
         }
         if (funds.type === "utxo") {
-          const utxos = funds.coins.map((utxo) => extendCoin(this.readonlyWallet, utxo));
-          const boardingAddress = await this.readonlyWallet.getBoardingAddress();
-          await this.walletRepository?.saveUtxos(boardingAddress, utxos);
+          const utxos = await this.readonlyWallet.getBoardingUtxos();
           this.scheduleForNextTick(
             () => this.tagged({
               type: "UTXO_UPDATE",
@@ -11217,13 +11779,16 @@ var WalletMessageHandler = class {
       return;
     }
     const vtxos = await this.getVtxosFromRepo();
-    const boardingAddress = await this.readonlyWallet.getBoardingAddress();
-    const coins = await this.readonlyWallet.onchainProvider.getCoins(boardingAddress);
-    await this.walletRepository.deleteUtxos(boardingAddress);
-    await this.walletRepository.saveUtxos(
-      boardingAddress,
-      coins.map((utxo) => extendCoin(this.readonlyWallet, utxo))
-    );
+    const boardingAddresses = await this.readonlyWallet.getBoardingAddresses();
+    const fresh = await this.readonlyWallet.getBoardingUtxos();
+    const freshKeys = new Set(fresh.map((u) => `${u.txid}:${u.vout}`));
+    for (const addr of boardingAddresses) {
+      const cached = await this.walletRepository.getUtxos(addr);
+      const kept = cached.filter((u) => freshKeys.has(`${u.txid}:${u.vout}`));
+      if (kept.length === cached.length) continue;
+      await this.walletRepository.deleteUtxos(addr);
+      if (kept.length > 0) await this.walletRepository.saveUtxos(addr, kept);
+    }
     const address = await this.readonlyWallet.getAddress();
     const txs = await this.buildTransactionHistoryFromCache(vtxos);
     if (txs) await this.walletRepository.saveTransactions(address, txs);
@@ -14014,5 +14579,5 @@ function isArkContract(str) {
 }
 
 export { ArkNote, AssetManager, BIP322, Batch, ContractManager, ContractRepositoryImpl, ContractWatcher, DB_VERSION, DEFAULT_MESSAGE_TIMEOUTS, DelegateManagerImpl, DelegateNotConfiguredError, DelegatorManagerImpl, DelegatorNotConfiguredError, DescriptorSigningProviderMissingError, DustChangeError, ELECTRUM_TCP_HOST, ELECTRUM_WS_URL, ESPLORA_URL, ElectrumOnchainProvider, EsploraProvider, Estimator, HDDescriptorProvider, InMemoryContractRepository, InMemoryWalletRepository, IndexedDBContractRepository, IndexedDBWalletRepository, MESSAGE_BUS_NOT_INITIALIZED, MIGRATION_KEY, MessageBus, MessageBusNotInitializedError, MissingSigningDescriptorError, MnemonicIdentity, OnchainWallet, P2A, Ramps, ReadonlyAssetManager, ReadonlyDescriptorIdentity, ReadonlySingleKey, ReadonlyWallet, ReadonlyWalletError, RestDelegateProvider, RestDelegatorProvider, SeedIdentity, ServiceWorkerReadonlyWallet, ServiceWorkerTimeoutError, ServiceWorkerWallet, SingleKey, TxTree, TxType, TxWeightEstimator, Unroll, VtxoManager, Wallet2 as Wallet, WalletMessageHandler, WalletNotInitializedError, WalletRepositoryImpl, WsElectrumChainSource, buildForfeitTx, buildOffchainTx, closeDatabase, combineTapscriptSigs, contractFromArkContract, contractFromArkContractWithAddress, decodeArkContract, deserializeAssets, deserializeUtxo, deserializeVtxo, encodeArkContract, extendVirtualCoinForContract, getMigrationStatus, getRandomId, hasBoardingTxExpired, isArkContract, isBatchSignable, isDiscoverable, isExpired, isRecoverable, isSpendable, isSubdust, isValidArkAddress, isVtxoExpiringSoon, isVtxoForScript, migrateWalletRepository, openDatabase, requiresMigration, rollbackMigration, saveVtxosForContract, scriptFromArkAddress, serializeAssets, serializeUtxo, serializeVtxo, setupServiceWorker, validateConnectorsTxGraph, validateVtxoTxGraph, verifyTapscriptSignatures, waitForIncomingFunds, warnAndFilterVtxosForScript };
-//# sourceMappingURL=chunk-XROGFOPX.js.map
-//# sourceMappingURL=chunk-XROGFOPX.js.map
+//# sourceMappingURL=chunk-HFXEUW55.js.map
+//# sourceMappingURL=chunk-HFXEUW55.js.map