@arkade-os/sdk 0.4.34 → 0.4.36

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

@@ -1,8 +1,8 @@
 import { Transaction } from '@scure/btc-signer';
 import { Bytes } from '@scure/btc-signer/utils.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.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, 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-Baz_hb83.js';
+import { D as DefaultVtxo, a as DelegateVtxo } from './delegate-C-L6gSZx.cjs';
 
 /**
  * Batch namespace provides utilities for joining and processing batch session.
@@ -348,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
@@ -385,12 +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 dustAmount: bigint;
     readonly walletRepository: WalletRepository;
     readonly contractRepository: ContractRepository;
@@ -399,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;
@@ -421,13 +446,63 @@ declare class ReadonlyWallet implements IReadonlyWallet {
      * 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
@@ -508,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.
      */
@@ -544,14 +628,43 @@ declare class ReadonlyWallet implements IReadonlyWallet {
      * 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(): Promise<DefaultVtxo.Script[]>;
+    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[]>;
     /**
@@ -651,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;
@@ -669,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
@@ -693,6 +828,38 @@ declare class Wallet extends ReadonlyWallet implements IWallet {
      * `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.
@@ -719,6 +886,36 @@ declare class Wallet extends ReadonlyWallet implements IWallet {
      * (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
@@ -911,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[];
     }>;
@@ -930,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 };