@arkade-os/sdk 0.4.33 → 0.4.35

package/dist/{wallet-D4Dll5Gu.d.cts → wallet-BWHbd5b1.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.cjs';
+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, a as Identity, $ as CSVMultisigTapscript, 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-D6sau_6-.cjs';
 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-C-L6gSZx.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
@@ -336,6 +348,15 @@ declare class WalletReceiveRotator {
      * needs to call this directly.
      */
     drain(): Promise<void>;
+    /**
+     * Run `fn` on the rotator's serialization chain, so it cannot interleave
+     * with a receive `rotate()`. Used by {@link Wallet.rotateServerSigner} to
+     * serialize server-signer rotation against HD receive rotation: both
+     * rebuild and swap `offchainTapscript`, so running them concurrently could
+     * tear the wallet's visible receive state. The chain keeps advancing even
+     * if `fn` rejects (its own caller still sees the rejection).
+     */
+    runExclusive<T>(fn: () => Promise<T>): Promise<T>;
     /**
      * Tear down the subscription first so no late `vtxo_received` event
      * can queue work on a disposing wallet, then drain any in-flight
@@ -373,13 +394,29 @@ type IncomingFunds = {
     spentVtxos: ExtendedVirtualCoin[];
 };
 
+/**
+ * Boarding UTXOs grouped by the boarding address they sit on, carrying that
+ * address's signer association explicitly. Returned by
+ * {@link ReadonlyWallet.getBoardingUtxosForSigners} because a flat
+ * {@link ExtendedCoin} cannot carry the signer: it retains only the encoded
+ * leaves/tapTree the spend needs, not the owning `DefaultVtxo.Script` (and so
+ * not its `serverPubKey` or CSV delay). The deprecated-signer boarding
+ * classification reads both back from this group (Section 7).
+ */
+interface BoardingUtxoGroup {
+    /** Tapscript of the boarding address the coins sit on. */
+    tapscript: DefaultVtxo.Script;
+    /** Server key of that address, normalized x-only hex. */
+    serverPubKey: string;
+    /** CSV exit timelock decoded from THIS tapscript's exit leaf. */
+    csvTimelock: RelativeTimelock;
+    coins: ExtendedCoin[];
+}
 declare class ReadonlyWallet implements IReadonlyWallet {
     readonly identity: ReadonlyIdentity;
     readonly network: Network;
     readonly onchainProvider: OnchainProvider;
     readonly indexerProvider: IndexerProvider;
-    readonly arkServerPublicKey: Bytes;
-    readonly boardingTapscript: DefaultVtxo.Script;
     readonly dustAmount: bigint;
     readonly walletRepository: WalletRepository;
     readonly contractRepository: ContractRepository;
@@ -388,7 +425,6 @@ declare class ReadonlyWallet implements IReadonlyWallet {
     private _contractManagerInitializing?;
     protected readonly watcherConfig?: ReadonlyWalletConfig["watcherConfig"];
     private readonly _assetManager;
-    private _syncVtxosInflight?;
     readonly walletContractTimelocks: RelativeTimelock[];
     protected _pendingSpendOutpoints: Set<string>;
     get assetManager(): IReadonlyAssetManager;
@@ -399,13 +435,105 @@ 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;
+    /**
+     * Backing field for the active server signer (x-only, 32 bytes). Read via
+     * the public {@link arkServerPublicKey} getter; written only by
+     * {@link Wallet.setArkServerPublicKeyForRotation}, the sanctioned
+     * server-signer rotation write path (analogue of `_offchainTapscript`). It
+     * is a *current value*, not a fixed constructor constant, because
+     * mid-session server-signer rotation (plan §4) swaps it when arkd rotates
+     * its active signer. Wallets that never span a rotation keep their
+     * construction-time snapshot for their lifetime.
+     */
+    protected _arkServerPublicKey: Bytes;
     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[]);
+    /**
+     * x-only hex of the operator's deprecated signer keys (from
+     * `ArkInfo.deprecatedSigners`), cached for the OFFLINE read/watch paths.
+     * The boarding watch/history surfaces ({@link getBoardingAddresses},
+     * {@link getBoardingTxs}) fan out over {current} ∪ this set so a deposit at
+     * a boarding address minted under a now-rotated operator signer keeps being
+     * watched. Refreshed from the server-info snapshot at construction (via the
+     * create() factories) and on a detected signer change. Deliberately NOT
+     * consulted by the spend path — {@link getBoardingUtxos} stays
+     * current-signer-only (a deprecated-signer input in a plain settle() is
+     * rejected; old-signer recovery goes through the migration API).
+     */
+    protected _deprecatedSigners: Map<string, bigint>;
+    /**
+     * Refresh the cached deprecated-signer set from a fresh server-info
+     * snapshot. Called by the create() factories at construction and by the
+     * server-info-change handler mid-session. Lenient: a malformed deprecated
+     * entry is skipped, never fatal to wallet creation.
+     */
+    refreshDeprecatedSigners(info: {
+        deprecatedSigners?: readonly {
+            pubkey?: string;
+            cutoffDate?: bigint;
+        }[];
+    }): void;
+    /**
+     * The signer set the boarding WATCH/HISTORY paths fan out over: the wallet's
+     * current signer plus every cached deprecated signer. Distinct from the
+     * spend path, which is current-signer-only.
+     */
+    protected watchedBoardingSigners(): Set<string>;
     /**
      * Currently-active receive tapscript. Read-only from the outside;
      * mutated only via {@link Wallet.setOffchainTapscriptForRotation}
      * by {@link WalletReceiveRotator.rotate}.
      */
     get offchainTapscript(): DefaultVtxo.Script | DelegateVtxo.Script;
+    /**
+     * The wallet's current active server signer (x-only, 32 bytes). Read-only
+     * from the outside; mutated only via
+     * {@link Wallet.setArkServerPublicKeyForRotation} during mid-session
+     * server-signer rotation (plan §4). Single-valued for wallets that never
+     * span a rotation.
+     */
+    get arkServerPublicKey(): Bytes;
+    /**
+     * 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().
@@ -455,6 +583,15 @@ declare class ReadonlyWallet implements IReadonlyWallet {
      * @param filter - Optional flags controlling whether recoverable or unrolled VTXOs are included
      */
     getVtxos(filter?: GetVtxosFilter): Promise<ExtendedVirtualCoin[]>;
+    /**
+     * Outpoints of VTXOs whose deprecated signer is past its cutoff (EXPIRED) and
+     * which have not yet been swept — unspendable until they recover. Offline:
+     * classifies the repo's contracts against the cached signer set (active +
+     * {@link _deprecatedSigners}, cutoffs included). Empty fast-path when no
+     * signer is deprecated. Consumed by {@link getBalance} (the `pendingRecovery`
+     * bucket) and the send coin-selection path so neither counts nor spends them.
+     */
+    pendingRecoveryOutpoints(): Promise<Set<string>>;
     /**
      * Return wallet transaction history derived from Arkade state and boarding transactions.
      */
@@ -465,19 +602,83 @@ 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.
+     *
+     * @param allowedSigners - Optional set of x-only-hex server keys whose
+     *   persisted boarding rows are included. Defaults to `{current x-only
+     *   signer}`, preserving today's current-signer-only discovery (and the
+     *   foreign-ASP guard). The deprecated-signer migration path widens this to
+     *   reach old-signer boarding addresses. The index-0 baseline and the
+     *   current display tapscript are always included regardless of the set.
+     */
+    protected getBoardingTapscripts(allowedSigners?: Set<string>): Promise<DefaultVtxo.Script[]>;
+    /**
+     * Fetch and cache onchain inputs (UTXOs) received at the boarding addresses
+     * of the given signer set, grouped per boarding address so the caller keeps
+     * the address↔signer association that {@link ExtendedCoin} cannot carry
+     * (it retains only the encoded leaves/tapTree the spend needs, not the
+     * `DefaultVtxo.Script` and its `serverPubKey`/CSV delay).
+     *
+     * Per group it does exactly what {@link getBoardingUtxos} does per tapscript:
+     * `getCoins` → {@link extendCoinWithTapscript} → `saveUtxos`. Offline-first:
+     * it does not call `getInfo()`; the caller supplies the allowed signer set,
+     * so the only network calls are the per-address `getCoins`.
+     *
+     * @param allowedSigners - x-only-hex server keys whose boarding addresses to
+     *   fetch (passed through to {@link getBoardingTapscripts}).
+     */
+    getBoardingUtxosForSigners(allowedSigners: Set<string>): Promise<BoardingUtxoGroup[]>;
+    /**
+     * 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.
+     *
+     * Current-signer only: a flatten of {@link getBoardingUtxosForSigners} over
+     * the wallet's current signer, so the two paths cannot drift. Old-signer
+     * boarding recovery goes through the deprecated-signer migration API
+     * instead (it would otherwise pull EXPIRED-signer inputs into a plain
+     * `settle()` that the server must reject).
      */
     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
      */
@@ -563,7 +764,6 @@ declare class ReadonlyWallet implements IReadonlyWallet {
  */
 declare class Wallet extends ReadonlyWallet implements IWallet {
     readonly arkProvider: ArkProvider;
-    readonly serverUnrollScript: CSVMultisigTapscript.Type;
     readonly forfeitOutputScript: Bytes;
     readonly forfeitPubkey: Bytes;
     static MIN_FEE_RATE: number;
@@ -581,6 +781,29 @@ declare class Wallet extends ReadonlyWallet implements IWallet {
      * the contract manager is up first.
      */
     private _receiveRotator?;
+    /**
+     * Unsubscribe handle for the arkProvider's `onServerInfoChanged` stream
+     * (mid-session signer-rotation detection). Torn down in {@link dispose}.
+     */
+    private _serverInfoUnsub?;
+    /**
+     * Tail of the serialized {@link handleServerInfoChanged} chain. Each
+     * `onServerInfoChanged` event chains onto it so handlers run one at a time,
+     * and {@link dispose} awaits it so an in-flight re-derive/rotation settles
+     * before the contract manager is torn down underneath it.
+     */
+    private _serverInfoInFlight;
+    /**
+     * React to a mid-session server-info change (driven by the arkProvider's
+     * `DIGEST_MISMATCH` detection). First refresh the cached deprecated-signer
+     * set so the boarding WATCH path immediately widens to the just-deprecated
+     * signer, then — only if the active signer actually changed — rotate the
+     * wallet onto it via {@link rotateServerSigner} (re-deriving the offchain +
+     * boarding display tapscripts and registering the current-signer rows).
+     * Old-signer rows stay active, so existing funds remain watched. Failures
+     * are logged, never thrown back into the provider's emit loop.
+     */
+    private handleServerInfoChanged;
     private _receiveRotatorInstalled;
     /**
      * Descriptor-aware signer used by {@link _signerRouter} to sign
@@ -598,6 +821,101 @@ 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;
+    /**
+     * @internal Sole write path for `arkServerPublicKey` after construction.
+     * Called by {@link Wallet.rotateServerSigner} once the rotated offchain and
+     * boarding contract rows have been persisted. External code must treat
+     * `arkServerPublicKey` as read-only.
+     */
+    setArkServerPublicKeyForRotation(serverPubKey: Bytes): void;
+    /**
+     * Output script for checkpoint transactions, decoded from the server's
+     * `checkpointTapscript`. Server-controlled state: pinned at construction
+     * and re-sourced from a fresh `ArkInfo` on server-signer rotation. Read it
+     * through {@link serverUnrollScript}; write it only through
+     * {@link setServerUnrollScriptForRotation}.
+     */
+    protected _serverUnrollScript: CSVMultisigTapscript.Type;
+    get serverUnrollScript(): CSVMultisigTapscript.Type;
+    /**
+     * @internal Sole write path for `serverUnrollScript` after construction.
+     * Called by {@link Wallet._doRotateServerSigner} with the checkpoint script
+     * sourced from the fresh `ArkInfo` that triggered the rotation, so the send
+     * path builds checkpoints against the new server epoch. External code must
+     * treat `serverUnrollScript` as read-only.
+     */
+    setServerUnrollScriptForRotation(script: CSVMultisigTapscript.Type): void;
+    /**
+     * Serializes {@link rotateServerSigner} for static / non-HD wallets (which
+     * have no {@link WalletReceiveRotator} chain to ride). Coalesces concurrent
+     * migration passes so two callers cannot both rebuild and swap the
+     * tapscripts. HD wallets serialize on the rotator's chain instead, via
+     * {@link WalletReceiveRotator.runExclusive}.
+     */
+    private _serverRotationChain;
+    /**
+     * 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>;
+    /**
+     * Mid-session server-signer rotation (plan §4). When arkd rotates its
+     * active signer mid-session — the case the long-lived service worker and
+     * Expo background processes that own automatic migration must handle — a
+     * wallet constructed before the rotation keeps deriving old-signer receive
+     * addresses. Building a migration output to such an address would produce a
+     * VTXO the server must reject, so the wallet must first re-derive its own
+     * receive state under the new active signer.
+     *
+     * Follows the {@link WalletReceiveRotator.rotate} write-path pattern with
+     * the server key swapped instead of the user key: build the new offchain
+     * and boarding tapscripts locally (preserving every other option),
+     * register the matching `default`/`delegate` and `boarding` contract rows
+     * through {@link ContractManager.createContract}, and only then commit the
+     * new tapscripts and server key to the wallet's visible state. The signing
+     * metadata of the current receive/boarding rows is carried onto the new
+     * rows so a rotated (descriptor-backed) receive pubkey can still sign.
+     *
+     * The old-signer contract rows are intentionally left `active` and watched
+     * — they are exactly the deprecated-signer contracts the migration pass
+     * drains. Idempotent: a no-op when the wallet already tracks `xonly`.
+     *
+     * Serialized against HD receive rotation so the two paths (both of which
+     * rebuild and swap `offchainTapscript`) cannot interleave.
+     *
+     * @internal Invoked by the {@link VtxoManager} migration pass; not part of
+     * the stable public API.
+     */
+    rotateServerSigner(newServerPubKey: Bytes, checkpointTapscript: string): Promise<void>;
+    private _doRotateServerSigner;
     /**
      * Async mutex that serializes all operations submitting VTXOs to the Arkade
      * server (`settle`, `send`, `sendBitcoin`). This prevents VtxoManager's
@@ -706,6 +1024,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 +1065,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>>;
@@ -756,12 +1108,38 @@ declare class Wallet extends ReadonlyWallet implements IWallet {
      */
     send(...args: [Recipient, ...Recipient[]]): Promise<string>;
     private _sendImpl;
+    /**
+     * Shared tail of every Ark-transaction spend path (`send`, selected-VTXO
+     * `sendBitcoin`, and {@link sendSelectedVtxosToSelf}): hide the inputs from
+     * concurrent `getVtxos()`, build+submit the offchain tx, persist the spent
+     * inputs and any wallet-owned (change / self) output, then release the
+     * pending-spend hold. Callers own coin selection, output construction, and
+     * the synchronous epoch snapshot; this owns the submit/persist sequence.
+     */
+    private _submitOffchainSpend;
+    /**
+     * @internal Migration primitive (deprecated-signer plan, step 1). Spend an
+     * explicit set of the wallet's own deprecated-signer VTXOs into a single
+     * full-value output on the wallet's *active* signer, through the Ark send
+     * path (not `settle`) so arkd builds checkpoints against the active server
+     * epoch. Consumed in-process by {@link VtxoManager}'s migration pass; not
+     * part of the public `IWallet` API and never accepts boarding `ExtendedCoin`
+     * inputs.
+     *
+     * The caller (`migrateCore`) must have already moved the wallet onto the
+     * active signer (`ensureReceiveOnActiveSigner`) and sized the batch (caps +
+     * dust floor); this method validates the inputs, preserves all input assets
+     * on the self output, and persists the new active-signer VTXO even though
+     * there is no separate change output. It records no `TxSent` history — the
+     * funds never leave the wallet.
+     */
+    sendSelectedVtxosToSelf(inputs: ExtendedVirtualCoin[]): Promise<string>;
     /**
      * Build an offchain transaction from the given inputs and outputs,
      * sign it, submit to the Arkade provider, and finalize.
      * @returns The Arkade transaction id and server-signed checkpoint PSBTs (for bookkeeping)
      */
-    buildAndSubmitOffchainTx(inputs: ExtendedVirtualCoin[], outputs: TransactionOutput[]): Promise<{
+    buildAndSubmitOffchainTx(inputs: ExtendedVirtualCoin[], outputs: TransactionOutput[], serverUnrollScript?: CSVMultisigTapscript.Type): Promise<{
         arkTxid: string;
         signedCheckpointTxs: string[];
     }>;
@@ -775,4 +1153,4 @@ declare class Wallet extends ReadonlyWallet implements IWallet {
  */
 declare function waitForIncomingFunds(wallet: Wallet): Promise<IncomingFunds>;
 
-export { Batch as B, type IncomingFunds as I, ReadonlyWallet as R, Wallet as W, type ReceiveRotatorFactory as a, type ReceiveRotatorBootOpts as b, type ReceiveRotatorBoot as c, waitForIncomingFunds as w };
+export { Batch as B, type IncomingFunds as I, ReadonlyWallet as R, Wallet as W, type ReceiveRotatorFactory as a, type ReceiveRotatorBootOpts as b, type ReceiveRotatorBoot as c, type BoardingUtxoGroup as d, waitForIncomingFunds as w };