@arkade-os/sdk 0.4.33 → 0.4.34

package/dist/wallet/expo/background.d.ts

@@ -1,6 +1,6 @@
-import { W as WalletRepository, C as ContractRepository } from '../../ark-DEsDMYGv.js';
-import { A as AsyncStorageTaskQueue } from '../../asyncStorageTaskQueue-CMrTYlKG.js';
-import { T as TaskProcessor } from '../../taskRunner-B7lBU45X.js';
+import { W as WalletRepository, C as ContractRepository } from '../../ark-Dsv5Jq4E.js';
+import { A as AsyncStorageTaskQueue } from '../../asyncStorageTaskQueue-BH-zuth5.js';
+import { T as TaskProcessor } from '../../taskRunner-B1NUWyWR.js';
 import '@scure/btc-signer/transaction.js';
 import '@scure/btc-signer/utils.js';
 import '@scure/btc-signer/psbt.js';

package/dist/wallet/expo/background.js

@@ -1,9 +1,9 @@
-import { contractPollProcessor, createTaskDependencies, runTasks, CONTRACT_POLL_TASK_TYPE } from '../../chunk-BU3BU6XK.js';
-import { ExpoIndexerProvider, ExpoArkProvider } from '../../chunk-L6ZETTX3.js';
-import { getRandomId } from '../../chunk-DSS2GQUG.js';
-import '../../chunk-E22HEKLN.js';
-import '../../chunk-AOJUURHM.js';
-import '../../chunk-TU3LVAPX.js';
+import { contractPollProcessor, createTaskDependencies, runTasks, CONTRACT_POLL_TASK_TYPE } from '../../chunk-VVGD3JIP.js';
+import { ExpoIndexerProvider, ExpoArkProvider } from '../../chunk-5WDBHWX3.js';
+import { getRandomId } from '../../chunk-HFXEUW55.js';
+import '../../chunk-FXFBPXV3.js';
+import '../../chunk-CUSABEUQ.js';
+import '../../chunk-OUVTG72A.js';
 import '../../chunk-NSBPE2FW.js';
 import * as TaskManager from 'expo-task-manager';
 import * as BackgroundTask from 'expo-background-task';

package/dist/wallet/expo/index.cjs

@@ -1,10 +1,10 @@
 'use strict';
 
-var chunkHAVA4XB7_cjs = require('../../chunk-HAVA4XB7.cjs');
-var chunk7K3ROJF6_cjs = require('../../chunk-7K3ROJF6.cjs');
-var chunkSPDNHPM4_cjs = require('../../chunk-SPDNHPM4.cjs');
-require('../../chunk-GYSK5R57.cjs');
-require('../../chunk-WMIPYZSB.cjs');
+var chunkZS3OZHC7_cjs = require('../../chunk-ZS3OZHC7.cjs');
+var chunkXCHBQVMK_cjs = require('../../chunk-XCHBQVMK.cjs');
+var chunkFSAXPBGP_cjs = require('../../chunk-FSAXPBGP.cjs');
+require('../../chunk-GUTKJMSF.cjs');
+require('../../chunk-CMPJR3HS.cjs');
 require('../../chunk-5BLDMQED.cjs');
 var base = require('@scure/base');
 
@@ -52,18 +52,18 @@ var ExpoWallet = class _ExpoWallet {
    */
   static async setup(config) {
     warnOnRemovedBackgroundFields(config.background);
-    const wallet = await chunk7K3ROJF6_cjs.Wallet.create(config);
-    const processors = config.background.processors ?? [chunkHAVA4XB7_cjs.contractPollProcessor];
+    const wallet = await chunkXCHBQVMK_cjs.Wallet.create(config);
+    const processors = config.background.processors ?? [chunkZS3OZHC7_cjs.contractPollProcessor];
     const deps = {
       walletRepository: wallet.walletRepository,
       contractRepository: wallet.contractRepository,
       indexerProvider: wallet.indexerProvider,
       arkProvider: wallet.arkProvider,
-      extendVtxo: (vtxo, contract) => chunk7K3ROJF6_cjs.extendVirtualCoinForContract(vtxo, contract)
+      extendVtxo: (vtxo, contract) => chunkXCHBQVMK_cjs.extendVirtualCoinForContract(vtxo, contract)
     };
     const { taskQueue } = config.background;
     if ("persistConfig" in taskQueue) {
-      const arkServerUrl = config.arkServerUrl || (wallet.arkProvider instanceof chunkSPDNHPM4_cjs.RestArkProvider ? wallet.arkProvider.serverUrl : void 0);
+      const arkServerUrl = config.arkServerUrl || (wallet.arkProvider instanceof chunkFSAXPBGP_cjs.RestArkProvider ? wallet.arkProvider.serverUrl : void 0);
       if (arkServerUrl) {
         const timelock = wallet.offchainTapscript.options.csvTimelock;
         const bgConfig = {
@@ -93,7 +93,7 @@ var ExpoWallet = class _ExpoWallet {
     }, intervalMs);
   }
   async runForegroundPoll() {
-    await chunkHAVA4XB7_cjs.runTasks(this.taskQueue, this.processors, this.deps);
+    await chunkZS3OZHC7_cjs.runTasks(this.taskQueue, this.processors, this.deps);
     const results = await this.taskQueue.getResults();
     if (results.length > 0) {
       await this.taskQueue.acknowledgeResults(results.map((r) => r.id));
@@ -101,11 +101,11 @@ var ExpoWallet = class _ExpoWallet {
     await this.seedContractPollTask();
   }
   async seedContractPollTask() {
-    const existing = await this.taskQueue.getTasks(chunkHAVA4XB7_cjs.CONTRACT_POLL_TASK_TYPE);
+    const existing = await this.taskQueue.getTasks(chunkZS3OZHC7_cjs.CONTRACT_POLL_TASK_TYPE);
     if (existing.length > 0) return;
     const task = {
-      id: chunk7K3ROJF6_cjs.getRandomId(),
-      type: chunkHAVA4XB7_cjs.CONTRACT_POLL_TASK_TYPE,
+      id: chunkXCHBQVMK_cjs.getRandomId(),
+      type: chunkZS3OZHC7_cjs.CONTRACT_POLL_TASK_TYPE,
       data: {},
       createdAt: Date.now()
     };

package/dist/wallet/expo/index.d.cts

@@ -1,11 +1,11 @@
-import { W as Wallet } from '../../wallet-D4Dll5Gu.cjs';
-import { I as IWallet, a as Identity, b as WalletConfig, c as WalletBalance, G as GetVtxosFilter, E as ExtendedVirtualCoin, d as ExtendedCoin, A as ArkTransaction, e as IContractManager, f as IDelegateManager, S as SendBitcoinParams, g as SettleParams, h as SettlementEvent, R as Recipient, i as IAssetManager } from '../../ark-DEsDMYGv.cjs';
-import { a as TaskQueue, T as TaskProcessor } from '../../taskRunner-pIGyarFG.cjs';
+import { W as Wallet } from '../../wallet-By9HIo0Q.cjs';
+import { I as IWallet, a as Identity, b as WalletConfig, c as WalletBalance, G as GetVtxosFilter, E as ExtendedVirtualCoin, d as ExtendedCoin, A as ArkTransaction, e as IContractManager, f as IDelegateManager, S as SendBitcoinParams, g as SettleParams, h as SettlementEvent, R as Recipient, i as IAssetManager } from '../../ark-Dsv5Jq4E.cjs';
+import { a as TaskQueue, T as TaskProcessor } from '../../taskRunner-vFRA3F9b.cjs';
+import '@scure/btc-signer';
 import '@scure/btc-signer/utils.js';
 import '@scure/btc-signer/psbt.js';
-import '../../delegate-BJeBNP5a.cjs';
+import '../../delegate-BaS5SCIW.cjs';
 import '@scure/btc-signer/transaction.js';
-import '@scure/btc-signer';
 
 /**
  * Background processing configuration for @see ExpoWallet.

package/dist/wallet/expo/index.d.ts

@@ -1,11 +1,11 @@
-import { W as Wallet } from '../../wallet-C4L_X0i6.js';
-import { I as IWallet, a as Identity, b as WalletConfig, c as WalletBalance, G as GetVtxosFilter, E as ExtendedVirtualCoin, d as ExtendedCoin, A as ArkTransaction, e as IContractManager, f as IDelegateManager, S as SendBitcoinParams, g as SettleParams, h as SettlementEvent, R as Recipient, i as IAssetManager } from '../../ark-DEsDMYGv.js';
-import { a as TaskQueue, T as TaskProcessor } from '../../taskRunner-B7lBU45X.js';
+import { W as Wallet } from '../../wallet-D6uoBLmS.js';
+import { I as IWallet, a as Identity, b as WalletConfig, c as WalletBalance, G as GetVtxosFilter, E as ExtendedVirtualCoin, d as ExtendedCoin, A as ArkTransaction, e as IContractManager, f as IDelegateManager, S as SendBitcoinParams, g as SettleParams, h as SettlementEvent, R as Recipient, i as IAssetManager } from '../../ark-Dsv5Jq4E.js';
+import { a as TaskQueue, T as TaskProcessor } from '../../taskRunner-B1NUWyWR.js';
+import '@scure/btc-signer';
 import '@scure/btc-signer/utils.js';
 import '@scure/btc-signer/psbt.js';
-import '../../delegate-EXN2mfkb.js';
+import '../../delegate-Baz_hb83.js';
 import '@scure/btc-signer/transaction.js';
-import '@scure/btc-signer';
 
 /**
  * Background processing configuration for @see ExpoWallet.

package/dist/wallet/expo/index.js

@@ -1,8 +1,8 @@
-import { contractPollProcessor, runTasks, CONTRACT_POLL_TASK_TYPE } from '../../chunk-BU3BU6XK.js';
-import { Wallet, getRandomId, extendVirtualCoinForContract } from '../../chunk-DSS2GQUG.js';
-import { RestArkProvider } from '../../chunk-E22HEKLN.js';
-import '../../chunk-AOJUURHM.js';
-import '../../chunk-TU3LVAPX.js';
+import { contractPollProcessor, runTasks, CONTRACT_POLL_TASK_TYPE } from '../../chunk-VVGD3JIP.js';
+import { Wallet, getRandomId, extendVirtualCoinForContract } from '../../chunk-HFXEUW55.js';
+import { RestArkProvider } from '../../chunk-FXFBPXV3.js';
+import '../../chunk-CUSABEUQ.js';
+import '../../chunk-OUVTG72A.js';
 import '../../chunk-NSBPE2FW.js';
 import { hex } from '@scure/base';
 

package/dist/{wallet-C4L_X0i6.d.ts → wallet-By9HIo0Q.d.cts}

@@ -1,7 +1,8 @@
+import { Transaction } from '@scure/btc-signer';
 import { Bytes } from '@scure/btc-signer/utils.js';
-import { B as BatchStartedEvent, v as TreeSigningStartedEvent, w as TxTree, x as TreeNoncesEvent, y as BatchFinalizationEvent, z as BatchFinalizedEvent, D as BatchFailedEvent, F as TreeTxEvent, H as TreeSignatureEvent, h as SettlementEvent, b as WalletConfig, W as WalletRepository, C as ContractRepository, J as DescriptorProvider, e as IContractManager, K as IReadonlyWallet, L as ReadonlyIdentity, N as Network, O as OnchainProvider, n as IndexerProvider, M as DelegateProvider, P as ReadonlyWalletConfig, o as RelativeTimelock, Q as IReadonlyAssetManager, m as ArkProvider, U as NetworkName, X as ArkInfo, Y as ArkAddress, c as WalletBalance, G as GetVtxosFilter, E as ExtendedVirtualCoin, A as ArkTransaction, d as ExtendedCoin, Z as Coin, _ as ContractManager, I as IWallet, $ as CSVMultisigTapscript, a as Identity, a0 as SettlementConfig, i as IAssetManager, a1 as VtxoManager, f as IDelegateManager, S as SendBitcoinParams, g as SettleParams, R as Recipient, a2 as SignerSession, a3 as SignedIntent, a4 as Intent } from './ark-DEsDMYGv.js';
+import { B as BatchStartedEvent, s as TreeSigningStartedEvent, t as TxTree, u as TreeNoncesEvent, v as BatchFinalizationEvent, w as BatchFinalizedEvent, x as BatchFailedEvent, y as TreeTxEvent, z as TreeSignatureEvent, h as SettlementEvent, b as WalletConfig, W as WalletRepository, C as ContractRepository, D as DescriptorProvider, e as IContractManager, F as IReadonlyWallet, H as ReadonlyIdentity, N as Network, O as OnchainProvider, n as IndexerProvider, J as DelegateProvider, K as ReadonlyWalletConfig, o as RelativeTimelock, L as IReadonlyAssetManager, m as ArkProvider, M as NetworkName, P as ArkInfo, Q as ArkAddress, c as WalletBalance, G as GetVtxosFilter, E as ExtendedVirtualCoin, A as ArkTransaction, d as ExtendedCoin, U as Coin, X as ContractManager, I as IWallet, Y as CSVMultisigTapscript, a as Identity, Z as SettlementConfig, i as IAssetManager, _ as VtxoManager, f as IDelegateManager, S as SendBitcoinParams, g as SettleParams, R as Recipient, $ as SignerSession, a0 as SignedIntent, a1 as Intent } from './ark-Dsv5Jq4E.cjs';
 import { TransactionOutput } from '@scure/btc-signer/psbt.js';
-import { D as DefaultVtxo, a as DelegateVtxo } from './delegate-EXN2mfkb.js';
+import { D as DefaultVtxo, a as DelegateVtxo } from './delegate-BaS5SCIW.cjs';
 
 /**
  * Batch namespace provides utilities for joining and processing batch session.
@@ -129,6 +130,17 @@ interface ReceiveRotatorBootOpts {
      * accidentally picking up a delegate contract or vice versa.
      */
     expectedContractType?: "default" | "delegate";
+    /**
+     * The wallet's baseline (index-0) receive pubkey — the x-only key the
+     * initial offchain tapscript is built from. Used by {@link
+     * WalletReceiveRotator.defaultBoot} as the no-tagged-row fallback:
+     * because boarding shares the single HD index stream, the raw watermark
+     * may have been advanced by a boarding-only allocation, so the boot must
+     * NOT derive the receive pubkey from it. A wallet with no tagged receive
+     * row has never rotated L2, so its correct current receive *is* the
+     * baseline index-0 key (plan §6-II.5).
+     */
+    baselineReceivePubKey?: Uint8Array;
     /**
      * Logger to receive rotation-failure + backoff diagnostics. Defaults
      * to `console` when omitted. Any object implementing
@@ -379,7 +391,6 @@ declare class ReadonlyWallet implements IReadonlyWallet {
     readonly onchainProvider: OnchainProvider;
     readonly indexerProvider: IndexerProvider;
     readonly arkServerPublicKey: Bytes;
-    readonly boardingTapscript: DefaultVtxo.Script;
     readonly dustAmount: bigint;
     readonly walletRepository: WalletRepository;
     readonly contractRepository: ContractRepository;
@@ -399,6 +410,17 @@ declare class ReadonlyWallet implements IReadonlyWallet {
      * {@link WalletReceiveRotator.rotate} is the sole intended caller of.
      */
     protected _offchainTapscript: DefaultVtxo.Script | DelegateVtxo.Script;
+    /**
+     * 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.
+     */
+    protected _boardingTapscript: DefaultVtxo.Script;
     protected constructor(identity: ReadonlyIdentity, network: Network, onchainProvider: OnchainProvider, indexerProvider: IndexerProvider, arkServerPublicKey: Bytes, offchainTapscript: DefaultVtxo.Script | DelegateVtxo.Script, boardingTapscript: DefaultVtxo.Script, dustAmount: bigint, walletRepository: WalletRepository, contractRepository: ContractRepository, delegateProvider?: DelegateProvider | undefined, watcherConfig?: ReadonlyWalletConfig["watcherConfig"], walletContractTimelocks?: RelativeTimelock[]);
     /**
      * Currently-active receive tapscript. Read-only from the outside;
@@ -406,6 +428,37 @@ declare class ReadonlyWallet implements IReadonlyWallet {
      * by {@link WalletReceiveRotator.rotate}.
      */
     get offchainTapscript(): DefaultVtxo.Script | DelegateVtxo.Script;
+    /**
+     * 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(): DefaultVtxo.Script;
+    /**
+     * 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.
+     */
+    private readonly _boardingRotationListeners;
+    /**
+     * Register a listener invoked synchronously after each boarding rotation.
+     * Returns an unsubscribe function. Protected: only internal subscribers
+     * (the incoming-funds watcher) participate.
+     */
+    protected onBoardingRotation(listener: () => void): () => void;
+    /**
+     * 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.
+     */
+    protected notifyBoardingRotation(): void;
     /**
      * Protected helper to set up shared wallet configuration.
      * Extracts common logic used by both ReadonlyWallet.create() and Wallet.create().
@@ -465,19 +518,54 @@ declare class ReadonlyWallet implements IReadonlyWallet {
      */
     clearSyncCursor(): Promise<void>;
     /**
-     * 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.
+     */
+    getBoardingAddresses(): Promise<string[]>;
+    /**
+     * Build a transaction history view across the wallet's boarding addresses
+     * (current + historical rotated; plan §6-IV.1).
      */
     getBoardingTxs(): Promise<{
         boardingTxs: ArkTransaction[];
         commitmentsToIgnore: Set<string>;
     }>;
     /**
-     * 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.
+     */
+    protected getBoardingTapscripts(): Promise<DefaultVtxo.Script[]>;
+    /**
+     * 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.
      */
     getBoardingUtxos(): Promise<ExtendedCoin[]>;
     /**
      * 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
      */
@@ -598,6 +686,39 @@ declare class Wallet extends ReadonlyWallet implements IWallet {
      * `offchainTapscript` as read-only.
      */
     setOffchainTapscriptForRotation(tapscript: DefaultVtxo.Script | DelegateVtxo.Script): void;
+    /**
+     * @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: DefaultVtxo.Script): void;
+    /**
+     * 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).
+     */
+    getNewBoardingAddress(): Promise<string>;
     /**
      * Async mutex that serializes all operations submitting VTXOs to the Arkade
      * server (`settle`, `send`, `sendBitcoin`). This prevents VtxoManager's
@@ -706,6 +827,30 @@ declare class Wallet extends ReadonlyWallet implements IWallet {
      */
     settle(params?: SettleParams, eventCallback?: (event: SettlementEvent) => void): Promise<string>;
     private _settleImpl;
+    /**
+     * 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.
+     */
+    private maybeRotateBoardingAfterBoard;
     private handleSettlementFinalizationEvent;
     /**
      * Create a batch event handler for settlement flows.
@@ -723,6 +868,16 @@ declare class Wallet extends ReadonlyWallet implements IWallet {
      * historical silent-skip behaviour for cosigner/connector inputs.
      */
     private inputSigningJobsFromWitnessUtxos;
+    /**
+     * @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.
+     */
+    signOnchainBoardingTx(tx: Transaction): Promise<Transaction>;
     safeRegisterIntent(intent: SignedIntent<Intent.RegisterMessage>, inputs: ExtendedCoin[]): Promise<string>;
     makeRegisterIntentSignature(coins: ExtendedCoin[], outputs: TransactionOutput[], onchainOutputsIndexes: number[], cosignerPubKeys: string[], validAt?: number): Promise<SignedIntent<Intent.RegisterMessage>>;
     makeDeleteIntentSignature(coins: ExtendedCoin[]): Promise<SignedIntent<Intent.DeleteMessage>>;

package/dist/{wallet-D4Dll5Gu.d.cts → wallet-D6uoBLmS.d.ts}

@@ -1,7 +1,8 @@
+import { Transaction } from '@scure/btc-signer';
 import { Bytes } from '@scure/btc-signer/utils.js';
-import { B as BatchStartedEvent, v as TreeSigningStartedEvent, w as TxTree, x as TreeNoncesEvent, y as BatchFinalizationEvent, z as BatchFinalizedEvent, D as BatchFailedEvent, F as TreeTxEvent, H as TreeSignatureEvent, h as SettlementEvent, b as WalletConfig, W as WalletRepository, C as ContractRepository, J as DescriptorProvider, e as IContractManager, K as IReadonlyWallet, L as ReadonlyIdentity, N as Network, O as OnchainProvider, n as IndexerProvider, M as DelegateProvider, P as ReadonlyWalletConfig, o as RelativeTimelock, Q as IReadonlyAssetManager, m as ArkProvider, U as NetworkName, X as ArkInfo, Y as ArkAddress, c as WalletBalance, G as GetVtxosFilter, E as ExtendedVirtualCoin, A as ArkTransaction, d as ExtendedCoin, Z as Coin, _ as ContractManager, I as IWallet, $ as CSVMultisigTapscript, a as Identity, a0 as SettlementConfig, i as IAssetManager, a1 as VtxoManager, f as IDelegateManager, S as SendBitcoinParams, g as SettleParams, R as Recipient, a2 as SignerSession, a3 as SignedIntent, a4 as Intent } from './ark-DEsDMYGv.cjs';
+import { B as BatchStartedEvent, s as TreeSigningStartedEvent, t as TxTree, u as TreeNoncesEvent, v as BatchFinalizationEvent, w as BatchFinalizedEvent, x as BatchFailedEvent, y as TreeTxEvent, z as TreeSignatureEvent, h as SettlementEvent, b as WalletConfig, W as WalletRepository, C as ContractRepository, D as DescriptorProvider, e as IContractManager, F as IReadonlyWallet, H as ReadonlyIdentity, N as Network, O as OnchainProvider, n as IndexerProvider, J as DelegateProvider, K as ReadonlyWalletConfig, o as RelativeTimelock, L as IReadonlyAssetManager, m as ArkProvider, M as NetworkName, P as ArkInfo, Q as ArkAddress, c as WalletBalance, G as GetVtxosFilter, E as ExtendedVirtualCoin, A as ArkTransaction, d as ExtendedCoin, U as Coin, X as ContractManager, I as IWallet, Y as CSVMultisigTapscript, a as Identity, Z as SettlementConfig, i as IAssetManager, _ as VtxoManager, f as IDelegateManager, S as SendBitcoinParams, g as SettleParams, R as Recipient, $ as SignerSession, a0 as SignedIntent, a1 as Intent } from './ark-Dsv5Jq4E.js';
 import { TransactionOutput } from '@scure/btc-signer/psbt.js';
-import { D as DefaultVtxo, a as DelegateVtxo } from './delegate-BJeBNP5a.cjs';
+import { D as DefaultVtxo, a as DelegateVtxo } from './delegate-Baz_hb83.js';
 
 /**
  * Batch namespace provides utilities for joining and processing batch session.
@@ -129,6 +130,17 @@ interface ReceiveRotatorBootOpts {
      * accidentally picking up a delegate contract or vice versa.
      */
     expectedContractType?: "default" | "delegate";
+    /**
+     * The wallet's baseline (index-0) receive pubkey — the x-only key the
+     * initial offchain tapscript is built from. Used by {@link
+     * WalletReceiveRotator.defaultBoot} as the no-tagged-row fallback:
+     * because boarding shares the single HD index stream, the raw watermark
+     * may have been advanced by a boarding-only allocation, so the boot must
+     * NOT derive the receive pubkey from it. A wallet with no tagged receive
+     * row has never rotated L2, so its correct current receive *is* the
+     * baseline index-0 key (plan §6-II.5).
+     */
+    baselineReceivePubKey?: Uint8Array;
     /**
      * Logger to receive rotation-failure + backoff diagnostics. Defaults
      * to `console` when omitted. Any object implementing
@@ -379,7 +391,6 @@ declare class ReadonlyWallet implements IReadonlyWallet {
     readonly onchainProvider: OnchainProvider;
     readonly indexerProvider: IndexerProvider;
     readonly arkServerPublicKey: Bytes;
-    readonly boardingTapscript: DefaultVtxo.Script;
     readonly dustAmount: bigint;
     readonly walletRepository: WalletRepository;
     readonly contractRepository: ContractRepository;
@@ -399,6 +410,17 @@ declare class ReadonlyWallet implements IReadonlyWallet {
      * {@link WalletReceiveRotator.rotate} is the sole intended caller of.
      */
     protected _offchainTapscript: DefaultVtxo.Script | DelegateVtxo.Script;
+    /**
+     * 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.
+     */
+    protected _boardingTapscript: DefaultVtxo.Script;
     protected constructor(identity: ReadonlyIdentity, network: Network, onchainProvider: OnchainProvider, indexerProvider: IndexerProvider, arkServerPublicKey: Bytes, offchainTapscript: DefaultVtxo.Script | DelegateVtxo.Script, boardingTapscript: DefaultVtxo.Script, dustAmount: bigint, walletRepository: WalletRepository, contractRepository: ContractRepository, delegateProvider?: DelegateProvider | undefined, watcherConfig?: ReadonlyWalletConfig["watcherConfig"], walletContractTimelocks?: RelativeTimelock[]);
     /**
      * Currently-active receive tapscript. Read-only from the outside;
@@ -406,6 +428,37 @@ declare class ReadonlyWallet implements IReadonlyWallet {
      * by {@link WalletReceiveRotator.rotate}.
      */
     get offchainTapscript(): DefaultVtxo.Script | DelegateVtxo.Script;
+    /**
+     * 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(): DefaultVtxo.Script;
+    /**
+     * 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.
+     */
+    private readonly _boardingRotationListeners;
+    /**
+     * Register a listener invoked synchronously after each boarding rotation.
+     * Returns an unsubscribe function. Protected: only internal subscribers
+     * (the incoming-funds watcher) participate.
+     */
+    protected onBoardingRotation(listener: () => void): () => void;
+    /**
+     * 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.
+     */
+    protected notifyBoardingRotation(): void;
     /**
      * Protected helper to set up shared wallet configuration.
      * Extracts common logic used by both ReadonlyWallet.create() and Wallet.create().
@@ -465,19 +518,54 @@ declare class ReadonlyWallet implements IReadonlyWallet {
      */
     clearSyncCursor(): Promise<void>;
     /**
-     * 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.
+     */
+    getBoardingAddresses(): Promise<string[]>;
+    /**
+     * Build a transaction history view across the wallet's boarding addresses
+     * (current + historical rotated; plan §6-IV.1).
      */
     getBoardingTxs(): Promise<{
         boardingTxs: ArkTransaction[];
         commitmentsToIgnore: Set<string>;
     }>;
     /**
-     * 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.
+     */
+    protected getBoardingTapscripts(): Promise<DefaultVtxo.Script[]>;
+    /**
+     * 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.
      */
     getBoardingUtxos(): Promise<ExtendedCoin[]>;
     /**
      * 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
      */
@@ -598,6 +686,39 @@ declare class Wallet extends ReadonlyWallet implements IWallet {
      * `offchainTapscript` as read-only.
      */
     setOffchainTapscriptForRotation(tapscript: DefaultVtxo.Script | DelegateVtxo.Script): void;
+    /**
+     * @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: DefaultVtxo.Script): void;
+    /**
+     * 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).
+     */
+    getNewBoardingAddress(): Promise<string>;
     /**
      * Async mutex that serializes all operations submitting VTXOs to the Arkade
      * server (`settle`, `send`, `sendBitcoin`). This prevents VtxoManager's
@@ -706,6 +827,30 @@ declare class Wallet extends ReadonlyWallet implements IWallet {
      */
     settle(params?: SettleParams, eventCallback?: (event: SettlementEvent) => void): Promise<string>;
     private _settleImpl;
+    /**
+     * 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.
+     */
+    private maybeRotateBoardingAfterBoard;
     private handleSettlementFinalizationEvent;
     /**
      * Create a batch event handler for settlement flows.
@@ -723,6 +868,16 @@ declare class Wallet extends ReadonlyWallet implements IWallet {
      * historical silent-skip behaviour for cosigner/connector inputs.
      */
     private inputSigningJobsFromWitnessUtxos;
+    /**
+     * @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.
+     */
+    signOnchainBoardingTx(tx: Transaction): Promise<Transaction>;
     safeRegisterIntent(intent: SignedIntent<Intent.RegisterMessage>, inputs: ExtendedCoin[]): Promise<string>;
     makeRegisterIntentSignature(coins: ExtendedCoin[], outputs: TransactionOutput[], onchainOutputsIndexes: number[], cosignerPubKeys: string[], validAt?: number): Promise<SignedIntent<Intent.RegisterMessage>>;
     makeDeleteIntentSignature(coins: ExtendedCoin[]): Promise<SignedIntent<Intent.DeleteMessage>>;