@arkade-os/sdk 0.4.33 → 0.4.35

package/dist/{ark-DEsDMYGv.d.cts → ark-D6sau_6-.d.cts}

@@ -454,6 +454,12 @@ declare class VtxoScript {
     /**
      * Create a virtual output script from its tapleaf scripts.
      *
+     * The Taproot script tree is assembled using btcd's algorithm
+     * (`txscript.AssembleTaprootScriptTree`) so the derived taproot output
+     * key agrees with arkd for any leaf count. `@scure/btc-signer`'s
+     * default `taprootListToTree` is a Huffman builder that only agrees
+     * with arkd for power-of-2 leaf counts.
+     *
      * @param scripts - Raw tapscript bytes for each leaf
      * @throws Error if the provided leaves cannot produce a valid Taproot tree
      */
@@ -518,6 +524,101 @@ type EncodedVtxoScript = {
  */
 declare function getSequence(tapLeafScript: TapLeafScript): number | undefined;
 
+/**
+ * Machine-readable classification of a contract's server signer relative to a
+ * fresh {@link ArkInfo} snapshot. Drives both the migration selection (Section
+ * 3) and the user-facing cutoff reporting (Section 6) without persisting any
+ * stale-key metadata: staleness is always derived at read time from the
+ * contract's `params.serverPubKey` plus the server's advertised signer set.
+ *
+ * - `CURRENT`: the contract was minted under the server's active signer; no
+ *   migration needed.
+ * - `MIGRATABLE`: the contract's signer is advertised as deprecated and its
+ *   cutoff has not passed — cooperative migration is still possible.
+ * - `DUE_NOW`: the contract's signer is advertised as deprecated with no cutoff
+ *   date (arkd advertises this as a `0n` cutoff), so migration should start
+ *   immediately.
+ * - `EXPIRED`: the contract's signer is deprecated and its cutoff has passed —
+ *   cooperative migration is closed. These funds are NOT stranded: the VTXO
+ *   keeps its own batch expiry, the server sweeps that batch at expiry, and the
+ *   swept VTXO then recovers into the active signer through the normal recovery
+ *   settle (no deprecated key, no forfeit, no on-chain exit). Unilateral exit
+ *   remains an opt-in escape hatch, not a requirement (Section 6 / post-cutoff).
+ * - `UNKNOWN_SIGNER`: the contract's signer is neither the active signer nor an
+ *   advertised deprecated signer. The SDK does not attempt to migrate these.
+ */
+type SignerStatus = "CURRENT" | "MIGRATABLE" | "DUE_NOW" | "EXPIRED" | "UNKNOWN_SIGNER";
+/**
+ * Result of classifying a single contract's server signer against the current
+ * {@link ArkInfo} signer set.
+ */
+interface SignerClassification {
+    status: SignerStatus;
+    /** The contract's server signer, normalized to x-only (32-byte) hex. */
+    signerPubKey: string;
+    /**
+     * Absolute cutoff as a Unix timestamp in seconds, present only when the
+     * server advertised one for this deprecated signer.
+     */
+    cutoffDate?: bigint;
+    /**
+     * Derived seconds until the advertised cutoff (`cutoffDate - now`), present
+     * only for `MIGRATABLE`/`EXPIRED` (i.e. an advertised cutoff exists).
+     * Negative once the cutoff has passed.
+     */
+    secondsUntilCutoff?: number;
+}
+/**
+ * The server's signer set, pre-normalized to x-only hex for cheap repeated
+ * lookups. Built once per migration/reporting pass from a fresh
+ * {@link ArkInfo} snapshot via {@link signerSetFromInfo}.
+ */
+interface SignerSet {
+    /** Active signer, x-only (32-byte) hex. */
+    active: string;
+    /**
+     * Deprecated signers keyed by x-only hex, mapped to their cutoff. The cutoff
+     * is always a bigint (arkd advertises it non-nullable); `0n` means "no cutoff
+     * advertised" (→ `DUE_NOW`).
+     */
+    deprecated: Map<string, bigint>;
+}
+/**
+ * Normalize a server signer pubkey hex to the x-only (32-byte) form contract
+ * scripts and `params.serverPubKey` use. A 33-byte compressed key drops its
+ * parity prefix; a 32-byte key is canonicalized to lowercase. Mirrors the
+ * wallet's `hex.decode(info.signerPubkey).slice(1)` setup path so the active
+ * signer and the deprecated signers (which arkd may advertise compressed)
+ * compare equal to the x-only `params.serverPubKey` persisted on contracts.
+ */
+declare function toXOnlySignerHex(pubkeyHex: string): string;
+/**
+ * Build the {@link SignerSet} from a server-info snapshot. Deprecated signers
+ * with an empty pubkey are skipped.
+ */
+declare function signerSetFromInfo(info: ArkInfo): SignerSet;
+/**
+ * Classify a contract's server signer against a pre-built {@link SignerSet}.
+ *
+ * @param contractServerPubKeyHex - the contract's `params.serverPubKey`
+ * @param signerSet - the server's signer set
+ * @param nowSeconds - current Unix time in seconds (compared against the
+ *   advertised cutoff). Defaults to `Math.floor(Date.now() / 1000)`.
+ */
+declare function classifyAgainstSignerSet(contractServerPubKeyHex: string, signerSet: SignerSet, nowSeconds?: number): SignerClassification;
+/**
+ * Convenience wrapper that builds the signer set from {@link ArkInfo} and
+ * classifies a single contract signer. Prefer {@link classifyAgainstSignerSet}
+ * with a shared signer set when classifying many contracts in one pass.
+ */
+declare function classifyContractSigner(contractServerPubKeyHex: string, info: ArkInfo, nowSeconds?: number): SignerClassification;
+/**
+ * Whether a signer status admits cooperative migration (i.e. a `settle()`
+ * intent should be built for VTXOs under this signer). True for `MIGRATABLE`
+ * and `DUE_NOW`; false for `CURRENT`, `EXPIRED`, and `UNKNOWN_SIGNER`.
+ */
+declare function isCooperativelyMigratable(status: SignerStatus): boolean;
+
 /**
  * Configuration options for automatic virtual output renewal
  *
@@ -612,6 +713,24 @@ interface SettlementConfig {
      * @defaultValue `60_000` (1 minute)
      */
     pollIntervalMs?: number;
+    /**
+     * Automatically migrate VTXOs minted under a now-deprecated server signer
+     * back to the wallet's active-signer address before their cutoff window
+     * closes (planned arkd key rotation).
+     *
+     * When enabled, each poll cycle cooperatively migrates stale-signer VTXOs
+     * via the normal `settle()` path, applying a mid-session server-signer
+     * rotation first when the wallet's own snapshot signer has been deprecated.
+     * The explicit {@link IVtxoManager.migrateDeprecatedSignerVtxos} method
+     * remains available for manual migration regardless of this flag.
+     *
+     * Setting `settlementConfig: false` disables all background settlement,
+     * including migration. Set this field to `false` to keep renewal/sweep but
+     * skip automatic deprecated-signer migration specifically.
+     *
+     * @defaultValue `true`
+     */
+    deprecatedSignerMigration?: boolean;
 }
 /**
  * Check if a virtual output is expiring soon based on threshold
@@ -634,6 +753,147 @@ interface RenewVtxosOptions {
      */
     thresholdSeconds?: number;
 }
+/**
+ * Optional arguments for {@link IVtxoManager.migrateDeprecatedSignerVtxos}.
+ */
+interface MigrateDeprecatedSignerOptions {
+    /** Callback to receive settlement events during the migration intent. */
+    eventCallback?: (event: SettlementEvent) => void;
+}
+/**
+ * A single VTXO referenced in a {@link DeprecatedSignerMigrationReport}.
+ */
+interface MigrationVtxoRef {
+    txid: string;
+    vout: number;
+    value: number;
+    /** The deprecated signer the VTXO was minted under (x-only hex). */
+    signerPubKey: string;
+    /** Absolute cutoff (Unix seconds) when the server advertised one. */
+    cutoffDate?: bigint;
+}
+/**
+ * Machine-readable status for a single deprecated signer the wallet holds
+ * funds under (Section 6). Derived at read time from contract params plus a
+ * fresh {@link ArkInfo} snapshot — never persisted.
+ */
+interface DeprecatedSignerReport {
+    /** Deprecated signer key (x-only hex). */
+    signerPubKey: string;
+    /** One of `migratable` | `dueNow` | `expired` | `unknownSigner`. */
+    status: SignerStatus;
+    /** Absolute cutoff (Unix seconds), present only when advertised. */
+    cutoffDate?: bigint;
+    /** Derived seconds until cutoff; negative once passed. */
+    secondsUntilCutoff?: number;
+    /** Number of spendable VTXOs the wallet holds under this signer. */
+    vtxoCount: number;
+    /** Total value of those VTXOs in satoshis. */
+    totalValue: number;
+    /**
+     * Number of spendable boarding UTXOs the wallet holds under this signer
+     * (Section 7). Counts every confirmed boarding coin, including those whose
+     * own CSV exit window has elapsed (they leave via the unilateral sweep).
+     */
+    boardingCount: number;
+    /** Total value of those boarding UTXOs in satoshis (Section 7). */
+    boardingValue: number;
+    /**
+     * Expired-signer VTXOs already swept and queued for recovery to the active
+     * signer (the recover-on-sweep default — see {@link SignerStatus} `EXPIRED`).
+     * Non-zero only on `EXPIRED` rows; these drain on the next recovery pass
+     * (Section 6 / post-cutoff).
+     */
+    recoverableCount: number;
+    recoverableValue: number;
+    /**
+     * Expired-signer VTXOs not yet swept; awaiting the server batch sweep before
+     * they become recoverable. Non-zero only on `EXPIRED` rows — nothing for the
+     * user to do but wait (Section 6 / post-cutoff).
+     */
+    awaitingSweepCount: number;
+    awaitingSweepValue: number;
+    /**
+     * Soonest batch expiry (ms since epoch) among the awaiting-sweep VTXOs, as a
+     * recovery ETA hint. Present only when an `EXPIRED` row has awaiting-sweep
+     * VTXOs that carry a batch expiry (Section 6 / post-cutoff).
+     */
+    nextSweepEta?: number;
+}
+/**
+ * Why a single migration leg (VTXO send or boarding settle) submitted nothing.
+ * `oversized-only` means every migratable input in that leg individually
+ * exceeds the server's per-output ceiling (`vtxoMaxAmount`) — see
+ * {@link MigrationLegReport.oversized}.
+ */
+type MigrationLegSkipReason = "below-dust" | "oversized-only";
+/**
+ * Why the whole pass submitted nothing, before either leg was built.
+ * `no-deprecated-vtxos` means BOTH migratable sets (VTXO and boarding) were
+ * empty; `unknown-wallet-signer` means the wallet's own snapshot signer is
+ * neither active nor advertised deprecated, so the pass refuses to rotate.
+ */
+type MigrationGlobalSkipReason = "no-deprecated-vtxos" | "unknown-wallet-signer";
+/**
+ * Outcome of one migration leg. The VTXO leg migrates through the Ark send path
+ * ({@link Wallet.sendSelectedVtxosToSelf}); the boarding leg keeps its
+ * settle-backed migration (boarding coins are on-chain inputs with no send
+ * path). Each leg owns its full sizing pipeline (oversized filtering, count +
+ * amount caps, its own dust floor) and reports independently — a failure or skip
+ * in one leg never suppresses the other.
+ */
+interface MigrationLegReport {
+    /** VTXO leg: Ark transaction id from send. Boarding leg: settle commitment txid. */
+    txid?: string;
+    /** Inputs submitted and accepted in this leg's transaction; empty on error/skip. */
+    migrated: MigrationVtxoRef[];
+    /** Why this leg submitted nothing (every candidate below dust or oversized). */
+    skipped?: MigrationLegSkipReason;
+    /**
+     * Migratable inputs deferred to a later pass by this leg's own caps (the
+     * input count {@link MAX_VTXOS_PER_SETTLEMENT} or the per-output amount
+     * ceiling `vtxoMaxAmount`). Present and non-zero only when a cap bound and
+     * the leg actually submitted; makes the truncation visible.
+     */
+    deferred?: number;
+    /**
+     * Inputs whose value alone exceeds the per-output ceiling (`vtxoMaxAmount`):
+     * a single ≤-ceiling output can never hold them, so they never migrate
+     * cooperatively and require a unilateral exit. Present only when non-empty;
+     * absent when the server advertises no ceiling (`vtxoMaxAmount < 0`).
+     */
+    oversized?: MigrationVtxoRef[];
+    /** Error message when this leg's submission failed; the other leg still runs. */
+    error?: string;
+}
+/**
+ * Result of a {@link IVtxoManager.migrateDeprecatedSignerVtxos} pass, split into
+ * two symmetric legs: VTXOs migrate through the send path, boarding UTXOs keep a
+ * separate settle-backed migration. They are never combined into one intent.
+ */
+interface DeprecatedSignerMigrationReport {
+    /** Whether a mid-session server-signer rotation was applied first. */
+    rotated: boolean;
+    /** Global skip; when set, neither leg is present. */
+    skipped?: MigrationGlobalSkipReason;
+    /** Send leg. Present iff ≥1 cooperatively-migratable VTXO existed this pass. */
+    vtxos?: MigrationLegReport;
+    /** Settle leg. Present iff ≥1 cooperatively-migratable boarding UTXO existed this pass. */
+    boarding?: MigrationLegReport;
+    /**
+     * Cutoff-expired inputs of both kinds (a classification outcome, not a leg
+     * outcome). Skipped because their signer cutoff has passed: cooperative
+     * migration is closed for them. They are NOT pushed to a unilateral exit —
+     * each keeps its own batch expiry, the server sweeps it at expiry, and the
+     * recovery path then re-mints it under the active signer. The per-signer
+     * sweep/recovery lifecycle is surfaced on {@link signers}
+     * ({@link DeprecatedSignerReport.recoverableCount} /
+     * {@link DeprecatedSignerReport.awaitingSweepCount}).
+     */
+    expired: MigrationVtxoRef[];
+    /** Per-deprecated-signer status snapshot (Section 6). */
+    signers: DeprecatedSignerReport[];
+}
 /**
  * VtxoManager is a unified class for managing virtual output lifecycle operations including
  * recovery of swept/expired virtual outputs and renewal to prevent expiration.
@@ -691,6 +951,29 @@ interface IVtxoManager {
     renewVtxos(eventCallback?: (event: SettlementEvent) => void, options?: RenewVtxosOptions): Promise<string>;
     getExpiredBoardingUtxos(): Promise<ExtendedCoin[]>;
     sweepExpiredBoardingUtxos(): Promise<string>;
+    /**
+     * Cooperatively migrate VTXOs minted under a now-deprecated server signer
+     * to the wallet's active-signer address (planned arkd key rotation).
+     *
+     * Applies a mid-session server-signer rotation first when the wallet's own
+     * snapshot signer has been deprecated, so the migration output commits to
+     * the active signer. Selects spendable VTXOs under deprecated-signer
+     * contracts, prioritizing those closest to their cutoff, and settles them
+     * back to the (rotated) Ark address. VTXOs whose cutoff has already passed
+     * are reported as `expired` rather than migrated.
+     *
+     * Available regardless of the `deprecatedSignerMigration` config flag (that
+     * flag only gates the automatic poll-loop pass).
+     *
+     * @returns A report of what was migrated, skipped, expired, or failed.
+     */
+    migrateDeprecatedSignerVtxos(options?: MigrateDeprecatedSignerOptions): Promise<DeprecatedSignerMigrationReport>;
+    /**
+     * Machine-readable status of every deprecated server signer the wallet
+     * currently holds funds under, without performing any migration. Lets
+     * consumers surface cutoff warnings on their own schedule.
+     */
+    getDeprecatedSignerStatus(): Promise<DeprecatedSignerReport[]>;
     dispose(): Promise<void>;
 }
 declare class VtxoManager implements AsyncDisposable, IVtxoManager {
@@ -698,7 +981,6 @@ declare class VtxoManager implements AsyncDisposable, IVtxoManager {
     /** @deprecated Use settlementConfig instead */
     readonly renewalConfig?: RenewalConfig | undefined;
     readonly settlementConfig: SettlementConfig | false;
-    private contractEventsSubscription?;
     private readonly contractEventsSubscriptionReady;
     private disposePromise?;
     private pollTimeoutId?;
@@ -720,6 +1002,10 @@ declare class VtxoManager implements AsyncDisposable, IVtxoManager {
     private lastVtxoSpentRefreshTimestamp;
     private vtxoSpentRefreshPromise?;
     private static readonly VTXO_SPENT_REFRESH_COOLDOWN_MS;
+    private lastMigrationTimestamp;
+    private consecutiveMigrationFailures;
+    private static readonly MIGRATION_COOLDOWN_MS;
+    private static readonly MIGRATION_MAX_BACKOFF_MS;
     constructor(wallet: IWallet, 
     /** @deprecated Use settlementConfig instead */
     renewalConfig?: RenewalConfig | undefined, settlementConfig?: SettlementConfig | false);
@@ -887,22 +1173,140 @@ declare class VtxoManager implements AsyncDisposable, IVtxoManager {
      * ```
      */
     sweepExpiredBoardingUtxos(prefetchedUtxos?: ExtendedCoin[]): Promise<string>;
+    /**
+     * Cooperatively migrate VTXOs minted under a now-deprecated server signer
+     * to the wallet's active-signer address. See {@link IVtxoManager}.
+     */
+    migrateDeprecatedSignerVtxos(options?: MigrateDeprecatedSignerOptions): Promise<DeprecatedSignerMigrationReport>;
+    /**
+     * Machine-readable status of every deprecated server signer the wallet
+     * currently holds funds under (Section 6), without migrating. Covers both
+     * VTXO and boarding holdings (Section 7), merged per signer.
+     *
+     * @remarks This is no longer a pure repository/info read: surfacing boarding
+     * holdings fans out per boarding address (`getCoins` round trips) and
+     * refreshes the UTXO cache via `saveUtxos`.
+     */
+    getDeprecatedSignerStatus(): Promise<DeprecatedSignerReport[]>;
+    /**
+     * Core migration routine shared by the manual API and the automatic poll
+     * pass. Fetches a fresh {@link ArkInfo}, applies a mid-session signer
+     * rotation when the wallet's own snapshot signer has been deprecated,
+     * selects spendable VTXOs under deprecated-signer contracts (cutoff-first),
+     * and settles them to the active-signer Ark address.
+     */
+    private migrateCore;
+    /**
+     * Size and submit one migration leg. Filters inputs whose value alone
+     * exceeds the per-output ceiling (`vtxoMaxAmount`; `< 0` means no limit) —
+     * those can never form a ≤-ceiling output and must exit unilaterally — then
+     * caps the rest (highest-value first; bounded by {@link MAX_VTXOS_PER_SETTLEMENT}
+     * AND a gross total within `vtxoMaxAmount`), applies the protocol dust floor,
+     * and submits the capped batch through `submit`. A throw from `submit` lands
+     * in `error`; the caller's other leg still runs.
+     *
+     * Migration is mandatory and fee-exempt: every selected input moves at its
+     * full value, so the gross total IS the aggregated output amount (kept under
+     * the server ceiling by the cap). The dust floor guards the degenerate cases
+     * where every input was oversized or the whole holding sums below dust.
+     */
+    private runMigrationLeg;
+    /**
+     * Enumerate the wallet's `default`/`delegate` contracts, classify each
+     * against the fresh signer set, and split their spendable VTXOs into
+     * cooperatively-migratable and cutoff-expired sets while building the
+     * per-signer status report. Current-signer contracts are skipped; swept
+     * (recoverable) VTXOs are excluded from the settle sets — those follow the
+     * recovery path — but are still counted on EXPIRED report rows
+     * (`recoverableCount`) so post-cutoff funds in flight stay visible.
+     */
+    private classifyDeprecatedSignerContracts;
+    /**
+     * Boarding sibling of {@link classifyDeprecatedSignerContracts} (Section 7):
+     * fan out over the wallet's boarding addresses (current + historical), group
+     * the on-chain UTXOs per address, classify each address's signer against the
+     * fresh signer set, and split the confirmed boarding coins into cooperatively-
+     * migratable and cutoff-expired sets while building the per-signer report.
+     *
+     * Discovery sees the active signer plus EVERY deprecated key (EXPIRED
+     * included), so expired-signer boarding is still reported; migration
+     * eligibility is gated afterwards by {@link isCooperativelyMigratable} and a
+     * per-row boarding-output CSV check — never by the fetch. Current-signer
+     * coins are classified `CURRENT` and ignored; foreign-ASP rows are excluded
+     * because their keys are not in the signer set.
+     */
+    private classifyDeprecatedSignerBoarding;
+    /**
+     * Automatic migration pass invoked from the poll loop. Self-contained:
+     * respects an exponential cooldown and logs failures rather than throwing,
+     * so a persistently failing migration backs off instead of re-submitting
+     * an identical intent every cycle.
+     */
+    private runMigrationPass;
+    /** Asserts migration capability and returns the typed wallet. */
+    private requireMigrationCapableWallet;
+    /**
+     * If the wallet's own construction-time signer snapshot has been deprecated,
+     * re-derive its receive/boarding state under the active signer so any output
+     * built afterwards commits to the active key. No-op when the snapshot is
+     * already current. Returns whether a rotation was applied. Treats an
+     * unknown-signer snapshot as "do not rotate" (caller decides).
+     *
+     * Shared by the migration pass (where the wallet's own snapshot is the thing
+     * being migrated) and the recovery/renewal/periodic-settle paths (via
+     * {@link rotateForRecoverableInputs}), so a swept old-signer VTXO recovered
+     * after cutoff re-mints under the active signer rather than re-committing to
+     * the deprecated key (Section 6 / post-cutoff). `rotateServerSigner` is
+     * idempotent and serializes itself against HD receive rotation, so repeated
+     * calls across passes are safe.
+     */
+    private ensureReceiveOnActiveSigner;
+    /**
+     * Rotation guard for the recovery-bearing settle paths (recover / renew /
+     * periodic settle). Pins the wallet's receive snapshot to the active signer
+     * before they build their output, but ONLY when this pass actually carries
+     * an input minted under a deprecated signer — so a routine current-signer
+     * settle on a long-lived pre-rotation instance does not eagerly rotate.
+     *
+     * Cheap in the common case: a watch-only/proxy wallet (not migration-capable)
+     * and a current/unknown wallet snapshot both short-circuit before the
+     * contract round-trip, so the only instance that pays for the input scan is
+     * the long-lived deprecated-snapshot one that genuinely needs rotating.
+     *
+     * Runs OUTSIDE any `renewalInProgress` window the caller sets, and
+     * `rotateServerSigner` does not depend on that flag, so it cannot deadlock
+     * against the receive rotator. Returns whether a rotation was applied.
+     */
+    private rotateForRecoverableInputs;
+    /**
+     * Whether any of the given input outpoints belongs to a contract whose
+     * server signer classifies as non-`CURRENT` against the fresh signer set —
+     * i.e. a deprecated-signer (incl. EXPIRED) input. Maps outpoints to their
+     * owning contract via the ContractManager so it works on the typed
+     * {@link ExtendedVirtualCoin}/{@link ExtendedCoin} inputs the recovery paths
+     * carry (which don't expose `contractScript`).
+     */
+    private anyInputUnderDeprecatedSigner;
     /** Asserts sweep capability and returns the typed wallet. */
     private getSweepWallet;
     /** Decodes the boarding tapscript exit path to extract the CSV timelock. */
     private getBoardingTimelock;
     /** Returns the TapLeafScript for the boarding tapscript's exit (CSV) path. */
     private getBoardingExitLeaf;
-    /** Returns the pkScript (output script) of the boarding tapscript. */
-    private getBoardingOutputScript;
     /** Returns the onchain provider for fee estimation and broadcasting. */
     private getOnchainProvider;
     /** Returns the Ark provider for intent fee and server info lookups. */
     private getArkProvider;
+    /**
+     * Read-only access to the ark provider for fetching server limits. Unlike
+     * {@link getArkProvider}, this does not require full boarding-sweep
+     * capability — recovery and renewal only need it to read `vtxoMaxAmount`.
+     * Returns undefined when no provider is wired, which callers treat as
+     * "no limit".
+     */
+    private getInfoProvider;
     /** Returns the Bitcoin network configuration from the wallet. */
     private getNetwork;
-    /** Returns the wallet's identity for transaction signing. */
-    private getIdentity;
     private initializeSubscription;
     /**
      * VTXO_ALREADY_SPENT means the server's authoritative view of VTXO state
@@ -994,8 +1398,8 @@ declare const networks: {
  * Mainnet, mutinynet, and signet point at Ark Labs–operated
  * mempool deployments (mempool.space-compatible esplora API).
  * Testnet falls back to the public mempool.space deployment
- * because Ark doesn't host it. Regtest assumes a local nigiri
- * stack on the standard port.
+ * because Ark doesn't host it. Regtest assumes a local arkade-regtest
+ * stack exposing mempool's esplora API on the standard port.
  */
 declare const ESPLORA_URL: Record<NetworkName, string>;
 type ExplorerTransaction = {
@@ -1281,6 +1685,14 @@ interface ScanResult {
 interface ScanContractsOptions {
     /** Default 20. A non-positive / non-integer value throws. */
     gapLimit?: number;
+    /**
+     * Number of HD indices probed concurrently per window (default
+     * {@link DEFAULT_SCAN_BATCH}). Pure latency knob: the gap loop stays
+     * gap-limit bounded and the discovered set is identical regardless of
+     * batch size. A non-positive / non-integer value throws. Ignored when
+     * `hd` is false (the static pass probes only index 0).
+     */
+    batchSize?: number;
     /** HD mode → unbounded gap loop guided by the gap counter; false → probe only index 0 (single static pass). */
     hd: boolean;
     /**
@@ -1581,6 +1993,19 @@ declare class ContractManager implements IContractManager {
      *   other handler hit it).
      * - `persistAndWatchContract` rejecting is operational/fatal and
      *   propagates (only `discoverAt` is guarded).
+     * - Within an index the handler probes run concurrently (independent
+     *   network reads); their hits are persisted sequentially in
+     *   `discoverables` order to preserve the first-wins collision tie-break.
+     * - Indices are probed `batchSize` at a time (a second concurrency layer
+     *   over the per-index probes), but each window is CAPPED to
+     *   `gapLimit - unused` indices — the most a serial scan could still reach
+     *   before the gap window is guaranteed to close. So every index probed in
+     *   a window is one a one-index-at-a-time scan would also reach: nothing is
+     *   over-scanned, nothing is discarded, and `materialize`/`discoverAt` are
+     *   invoked on exactly the same index set. The window's hits are still
+     *   processed strictly in ascending index order, so the discovered set,
+     *   persisted rows, `lastIndexUsed`, and `handlerErrors` are byte-for-byte
+     *   identical to the serial path — only the wall-clock differs.
      */
     scanContracts(opts: ScanContractsOptions): Promise<ScanResult>;
     /**
@@ -1958,12 +2383,47 @@ interface DiscoveredContract {
 interface DiscoveryDeps {
     indexerProvider: IndexerProvider;
     onchainProvider: OnchainProvider;
+    /**
+     * Ark-address network data. The `{ hrp }` shape is all the L2
+     * (`default`/`delegate`) discovery path needs to render an Ark address.
+     */
     network: {
         hrp: string;
     };
+    /**
+     * Full Bitcoin network descriptor for on-chain (P2TR) address
+     * rendering. Required by the boarding discovery probe, which derives an
+     * on-chain Taproot address via {@link VtxoScript.onchainAddress} — the
+     * `{ hrp }`-only {@link DiscoveryDeps.network} lacks the `bech32` data
+     * that needs. Absent only when no boarding discovery is plumbed (e.g.
+     * the scanner unit harness), in which case boarding `discoverAt` no-ops.
+     */
+    onchainNetwork?: Network;
+    /**
+     * The server's **current** signer key (x-only, 32 bytes), taken from a
+     * fresh server-info snapshot at restore time. L2 (`default`/`delegate`)
+     * discovery probes this key first.
+     */
     serverPubKey: Uint8Array;
+    /**
+     * The server's **deprecated** signer keys (x-only, 32 bytes) from the same
+     * snapshot. A VTXO minted under a now-rotated signer is anchored to a
+     * different script; L2 discovery scans these keys alongside
+     * {@link DiscoveryDeps.serverPubKey} so signer rotation does not strand
+     * funds. Empty/absent when the server advertises no deprecated signers.
+     * Boarding discovery does not consult this set (current UTXO set only).
+     */
+    deprecatedSignerPubKeys?: Uint8Array[];
     /** Relative timelocks the wallet treats as its baseline matrix. */
     csvTimelocks: RelativeTimelock[];
+    /**
+     * Boarding-exit CSV timelock. Distinct from {@link DiscoveryDeps.csvTimelocks}
+     * (the unilateral-exit matrix): boarding scripts source their CSV from the
+     * server's boarding-exit delay. Present only when boarding discovery is
+     * plumbed; when absent, boarding `discoverAt` no-ops (so the scanner unit
+     * harness, which never sets it, is unaffected).
+     */
+    boardingTimelock?: RelativeTimelock;
     /** Present only for delegate wallets. */
     delegatePubKey?: Uint8Array;
 }
@@ -2679,7 +3139,14 @@ interface WalletBalance {
     available: number;
     /** Recoverable balance from subdust or expired (swept) virtual outputs. */
     recoverable: number;
-    /** Total balance across offchain, recoverable, and boarding funds. */
+    /**
+     * Funds under a now-deprecated signer past its cutoff (EXPIRED) that have not
+     * yet been swept by the server. NOT spendable until they recover, so excluded
+     * from `available`/`settled`/`preconfirmed` and from coin selection — but
+     * still the wallet's funds, so counted in `total`.
+     */
+    pendingRecovery: number;
+    /** Total balance across offchain, recoverable, pending-recovery, and boarding funds. */
     total: number;
     /** Asset balance entries (`assetId` & `amount`) */
     assets: Asset[];
@@ -3556,6 +4023,17 @@ interface FeeOutput {
     script: string;
 }
 
+/**
+ * Thrown by {@link RestArkProvider} when arkd rejects a request with
+ * `DIGEST_MISMATCH` — the client's cached server info was stale (e.g. an
+ * operator signer rotation). By the time this surfaces the provider has already
+ * refreshed its info and fired `onServerInfoChanged`; the caller should rebuild
+ * the request under the fresh server info and retry. Mirrors NArk's
+ * `DigestMismatchException` (dotnet-sdk #131): the SDK never silently retries.
+ */
+declare class DigestMismatchError extends Error {
+    constructor(message: string);
+}
 /** Output requested during settlement or transaction submission. */
 type Output = {
     /** Destination address, either onchain or Arkade (offchain). */
@@ -3646,6 +4124,15 @@ interface PendingTx {
     signedCheckpointTxs: string[];
 }
 interface DeprecatedSigner {
+    /**
+     * Unix timestamp (seconds) after which the server no longer accepts this
+     * signer's VTXOs as cooperative-migration inputs. arkd advertises this as a
+     * non-nullable field, so it is always present: `0n` is the sentinel for "no
+     * cutoff advertised" — the deprecated signer is due for migration
+     * immediately ({@link classifyContractSigner} maps `0n` to `DUE_NOW`). A
+     * positive value is a real deadline (`MIGRATABLE` until it passes, then
+     * `EXPIRED`).
+     */
     cutoffDate: bigint;
     pubkey: string;
 }
@@ -3752,6 +4239,32 @@ interface ArkProvider {
 declare class RestArkProvider implements ArkProvider {
     serverUrl: string;
     constructor(serverUrl?: string);
+    /**
+     * Last server-info digest seen (from {@link getInfo}). Sent as `X-Digest`
+     * on outgoing requests so arkd can reject a client whose cached info is
+     * stale. Empty until the first {@link getInfo}.
+     */
+    private _digest;
+    private _serverInfoListeners;
+    /**
+     * Subscribe to server-info changes. Fired when a request is rejected with
+     * `DIGEST_MISMATCH` and fresh info is re-fetched, so consumers (the wallet)
+     * can re-derive signer-dependent state mid-session without polling. Returns
+     * an unsubscribe function.
+     */
+    onServerInfoChanged(listener: (info: ArkInfo) => void): () => void;
+    private emitServerInfoChanged;
+    /**
+     * `fetch` wrapper for arkd requests that participates in server-info digest
+     * negotiation. Sends the cached `X-Digest`; when arkd rejects a request with
+     * `DIGEST_MISMATCH`, refreshes {@link getInfo} (updating the digest), fires
+     * {@link onServerInfoChanged}, and THROWS {@link DigestMismatchError} — it
+     * never silently retries, since the in-flight request was built against the
+     * now-stale config. Dormant until arkd returns the error — then it is the
+     * instant, event-driven signer-rotation trigger. {@link getInfo} itself never
+     * routes through here: it is the refresh path and must not be digest-gated.
+     */
+    private authedFetch;
     getInfo(): Promise<ArkInfo>;
     submitTx(signedArkTx: string, checkpointTxs: string[]): Promise<{
         arkTxid: string;
@@ -3919,4 +4432,4 @@ declare namespace ProtoTypes {
     export {  };
 }
 
-export { CSVMultisigTapscript as $, type ArkTransaction as A, type BatchStartedEvent as B, type ContractRepository as C, type BatchFailedEvent as D, type ExtendedVirtualCoin as E, type TreeTxEvent as F, type GetVtxosFilter as G, type TreeSignatureEvent as H, type IWallet as I, type DescriptorProvider as J, type IReadonlyWallet as K, type ReadonlyIdentity as L, type DelegateProvider as M, type Network as N, type OnchainProvider as O, type ReadonlyWalletConfig as P, type IReadonlyAssetManager as Q, type Recipient as R, type SendBitcoinParams as S, type TxNotification as T, type NetworkName as U, VtxoScript as V, type WalletRepository as W, type ArkInfo as X, ArkAddress as Y, type Coin as Z, ContractManager as _, type Identity as a, type ExtendedContractVtxo as a$, type SettlementConfig as a0, VtxoManager as a1, type SignerSession as a2, type SignedIntent as a3, Intent as a4, type DescriptorSigningRequest as a5, Transaction as a6, type IntentFeeConfig as a7, type OffchainInput as a8, FeeAmount as a9, type ArkTapscript as aA, type Asset as aB, type AssetMetadata as aC, type BaseWalletConfig as aD, type BatchInfo as aE, type BatchSignableIdentity as aF, CLTVMultisigTapscript as aG, ChainTxType as aH, type CommitmentTx as aI, ConditionCSVMultisigTapscript as aJ, ConditionMultisigTapscript as aK, type ContractBalance as aL, type ContractEventCallback as aM, type ContractHandler as aN, type ContractManagerConfig as aO, type ContractState as aP, type ContractVtxo as aQ, ContractWatcher as aR, DelegateManagerImpl as aS, type DelegateOptions as aT, DelegatorManagerImpl as aU, type DelegatorProvider as aV, type Discoverable as aW, type DiscoveredContract as aX, type DiscoveryDeps as aY, ESPLORA_URL as aZ, EsploraProvider as a_, type OnchainInput as aa, type FeeOutput as ab, type ContractWatcherConfig as ac, type FeeInfo as ad, type CreateContractParams as ae, type GetContractsFilter as af, type GetSpendablePathsOptions as ag, type GetAllSpendingPathsOptions as ah, type IssuanceParams as ai, type ReissuanceParams as aj, type BurnParams as ak, type RenewVtxosOptions as al, type ContractWithVtxos as am, type PathSelection as an, type ContractEvent as ao, type AssetDetails as ap, type IssuanceResult as aq, type DelegateInfo as ar, type StorageConfig as as, type IVtxoManager as at, type ExplorerTransaction as au, type EncodedVtxoScript as av, type Status as aw, type Outpoint as ax, type ChainTx as ay, type PathContext as az, type WalletConfig as b, type HandlerError as b0, type IDelegatorManager as b1, IndexerTxType as b2, type KnownMetadata as b3, MultisigTapscript as b4, type Nonces as b5, type Output as b6, type PageResponse as b7, type PaginationOptions as b8, PartialSig as b9, getSequence as bA, isBatchSignable as bB, isDiscoverable as bC, isExpired as bD, isRecoverable as bE, isSpendable as bF, isSubdust as bG, isVtxoExpiringSoon as bH, networks as bI, type ProviderClass as ba, RestDelegateProvider as bb, RestDelegatorProvider as bc, type ScanContractsOptions as bd, type ScanResult as be, type ScheduledSession as bf, SettlementEventType as bg, type SignRequest as bh, type SubscriptionEvent as bi, type SubscriptionHeartbeat as bj, type TapLeaves as bk, TapTreeCoder as bl, TapscriptType as bm, type TreeNonces as bn, type TreePartialSigs as bo, type Tx as bp, type TxHistoryRecord as bq, type TxKey as br, type TxTreeNode as bs, TxType as bt, type VirtualStatus as bu, type Vtxo as bv, type VtxoChain as bw, type VtxoType as bx, type WalletMode as by, decodeTapscript as bz, type WalletBalance as c, type ExtendedCoin as d, type IContractManager as e, type IDelegateManager as f, type SettleParams as g, type SettlementEvent as h, type IAssetManager as i, RestArkProvider as j, RestIndexerProvider as k, type SubscriptionResponse as l, type ArkProvider as m, type IndexerProvider as n, type RelativeTimelock as o, type TapLeafScript as p, type VirtualCoin as q, type Contract as r, type VtxoRepositoryKey as s, type WalletState as t, type ContractFilter as u, type TreeSigningStartedEvent as v, TxTree as w, type TreeNoncesEvent as x, type BatchFinalizationEvent as y, type BatchFinalizedEvent as z };
+export { CSVMultisigTapscript as $, type ArkTransaction as A, type BatchStartedEvent as B, type ContractRepository as C, type BatchFailedEvent as D, type ExtendedVirtualCoin as E, type TreeTxEvent as F, type GetVtxosFilter as G, type TreeSignatureEvent as H, type IWallet as I, type DescriptorProvider as J, type IReadonlyWallet as K, type ReadonlyIdentity as L, type DelegateProvider as M, type Network as N, type OnchainProvider as O, type ReadonlyWalletConfig as P, type IReadonlyAssetManager as Q, type Recipient as R, type SendBitcoinParams as S, type TxNotification as T, type NetworkName as U, VtxoScript as V, type WalletRepository as W, type ArkInfo as X, ArkAddress as Y, type Coin as Z, ContractManager as _, type Identity as a, DigestMismatchError as a$, type SettlementConfig as a0, VtxoManager as a1, type SignerSession as a2, type SignedIntent as a3, Intent as a4, type DescriptorSigningRequest as a5, Transaction as a6, type IntentFeeConfig as a7, type OffchainInput as a8, FeeAmount as a9, type Outpoint as aA, type ChainTx as aB, type PathContext as aC, type ArkTapscript as aD, type Asset as aE, type AssetMetadata as aF, type BaseWalletConfig as aG, type BatchInfo as aH, type BatchSignableIdentity as aI, CLTVMultisigTapscript as aJ, ChainTxType as aK, type CommitmentTx as aL, ConditionCSVMultisigTapscript as aM, ConditionMultisigTapscript as aN, type ContractBalance as aO, type ContractEventCallback as aP, type ContractHandler as aQ, type ContractManagerConfig as aR, type ContractState as aS, type ContractVtxo as aT, ContractWatcher as aU, DelegateManagerImpl as aV, type DelegateOptions as aW, DelegatorManagerImpl as aX, type DelegatorProvider as aY, type DeprecatedSignerMigrationReport as aZ, type DeprecatedSignerReport as a_, type OnchainInput as aa, type FeeOutput as ab, type ContractWatcherConfig as ac, type FeeInfo as ad, type CreateContractParams as ae, type GetContractsFilter as af, type GetSpendablePathsOptions as ag, type GetAllSpendingPathsOptions as ah, type IssuanceParams as ai, type ReissuanceParams as aj, type BurnParams as ak, type RenewVtxosOptions as al, type ContractWithVtxos as am, type PathSelection as an, type ContractEvent as ao, type AssetDetails as ap, type IssuanceResult as aq, type DelegateInfo as ar, type MigrationGlobalSkipReason as as, type MigrationLegSkipReason as at, type SignerStatus as au, type StorageConfig as av, type IVtxoManager as aw, type ExplorerTransaction as ax, type EncodedVtxoScript as ay, type Status as az, type WalletConfig as b, type Discoverable as b0, type DiscoveredContract as b1, type DiscoveryDeps as b2, ESPLORA_URL as b3, EsploraProvider as b4, type ExtendedContractVtxo as b5, type HandlerError as b6, type IDelegatorManager as b7, IndexerTxType as b8, type KnownMetadata as b9, type Tx as bA, type TxHistoryRecord as bB, type TxKey as bC, type TxTreeNode as bD, TxType as bE, type VirtualStatus as bF, type Vtxo as bG, type VtxoChain as bH, type VtxoType as bI, type WalletMode as bJ, classifyAgainstSignerSet as bK, classifyContractSigner as bL, decodeTapscript as bM, getSequence as bN, isBatchSignable as bO, isCooperativelyMigratable as bP, isDiscoverable as bQ, isExpired as bR, isRecoverable as bS, isSpendable as bT, isSubdust as bU, isVtxoExpiringSoon as bV, networks as bW, signerSetFromInfo as bX, toXOnlySignerHex as bY, type MigrateDeprecatedSignerOptions as ba, type MigrationLegReport as bb, type MigrationVtxoRef as bc, MultisigTapscript as bd, type Nonces as be, type Output as bf, type PageResponse as bg, type PaginationOptions as bh, PartialSig as bi, type ProviderClass as bj, RestDelegateProvider as bk, RestDelegatorProvider as bl, type ScanContractsOptions as bm, type ScanResult as bn, type ScheduledSession as bo, SettlementEventType as bp, type SignRequest as bq, type SignerClassification as br, type SignerSet as bs, type SubscriptionEvent as bt, type SubscriptionHeartbeat as bu, type TapLeaves as bv, TapTreeCoder as bw, TapscriptType as bx, type TreeNonces as by, type TreePartialSigs as bz, type WalletBalance as c, type ExtendedCoin as d, type IContractManager as e, type IDelegateManager as f, type SettleParams as g, type SettlementEvent as h, type IAssetManager as i, RestArkProvider as j, RestIndexerProvider as k, type SubscriptionResponse as l, type ArkProvider as m, type IndexerProvider as n, type RelativeTimelock as o, type TapLeafScript as p, type VirtualCoin as q, type Contract as r, type VtxoRepositoryKey as s, type WalletState as t, type ContractFilter as u, type TreeSigningStartedEvent as v, TxTree as w, type TreeNoncesEvent as x, type BatchFinalizationEvent as y, type BatchFinalizedEvent as z };