@arkade-os/sdk 0.4.47 → 0.4.48

package/dist/{ark-CoJgwTi_.d.cts → ark-CjE0KkGp.d.cts}

@@ -524,6 +524,285 @@ type EncodedVtxoScript = {
  */
 declare function getSequence(tapLeafScript: TapLeafScript): number | undefined;
 
+type NetworkName = "bitcoin" | "testnet" | "signet" | "mutinynet" | "regtest";
+interface Network {
+    hrp: string;
+    bech32: string;
+    pubKeyHash: number;
+    scriptHash: number;
+    wif: number;
+}
+declare const getNetwork: (network: NetworkName) => Network;
+declare const networks: {
+    bitcoin: Network;
+    testnet: Network;
+    signet: Network;
+    mutinynet: Network;
+    regtest: Network;
+};
+
+/**
+ * The default base URLs for esplora API providers.
+ *
+ * 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 arkade-regtest
+ * stack exposing mempool's esplora API on the standard port.
+ */
+declare const ESPLORA_URL: Record<NetworkName, string>;
+type ExplorerTransaction = {
+    txid: string;
+    /**
+     * Inputs as returned by Esplora's `/address/:addr/txs`, each carrying the
+     * outpoint it spends (`txid:vout`). Optional: not every provider populates
+     * it (the electrum provider omits inputs), so consumers that correlate
+     * spenders must tolerate its absence. Used to recover a boarding output's
+     * spending (commitment) tx when `/outspends` omits the spender txid.
+     */
+    vin?: {
+        txid: string;
+        vout: number;
+    }[];
+    vout: {
+        scriptpubkey_address: string;
+        value: string;
+    }[];
+    status: {
+        confirmed: boolean;
+        block_time: number;
+    };
+};
+interface OnchainProvider {
+    /**
+     * Fetch spendable onchain outputs for an address.
+     *
+     * @param address - Bitcoin address to query
+     * @returns Spendable onchain outputs for the address
+     * @see Coin
+     */
+    getCoins(address: string): Promise<Coin[]>;
+    /**
+     * Fetch the current fastest fee rate estimate.
+     *
+     * @returns Fee rate in sats/vB, if available
+     * @remarks
+     * Implementations may return `undefined` when the backing service does not expose
+     * a usable fee estimate.
+     */
+    getFeeRate(): Promise<number | undefined>;
+    /**
+     * Broadcast a single transaction or a 1P1C package.
+     *
+     * @param txs - One or more raw transaction hex strings
+     * @returns Broadcast transaction id
+     * @throws Error if the broadcast request fails or the package shape is invalid
+     */
+    broadcastTransaction(...txs: string[]): Promise<string>;
+    /**
+     * Fetch outspend information for every output in a transaction.
+     *
+     * @param txid - Transaction id to inspect
+     * @returns Per-output spend status information. `txid` (the spender) may be
+     *   absent even when `spent` is true: some Esplora deployments
+     *   (e.g. mempool.arkade.sh) omit it from `/outspends`.
+     * @see getTxStatus
+     */
+    getTxOutspends(txid: string): Promise<{
+        spent: boolean;
+        txid?: string;
+    }[]>;
+    /**
+     * Fetch transactions associated with an address.
+     *
+     * @param address - Bitcoin address to query
+     * @returns Transactions involving the address
+     * @see ExplorerTransaction
+     */
+    getTransactions(address: string): Promise<ExplorerTransaction[]>;
+    /**
+     * Fetch confirmation status for a transaction.
+     *
+     * @param txid - Transaction id to inspect
+     * @returns Confirmation status and block metadata when confirmed
+     * @see getTxOutspends
+     */
+    getTxStatus(txid: string): Promise<{
+        confirmed: false;
+    } | {
+        confirmed: true;
+        blockTime: number;
+        blockHeight: number;
+    }>;
+    /**
+     * Fetch the current chain tip.
+     *
+     * @returns Current chain height, block time, and block hash
+     */
+    getChainTip(): Promise<{
+        height: number;
+        time: number;
+        hash: string;
+    }>;
+    /**
+     * Watch a set of addresses and invoke the callback when transactions are observed.
+     *
+     * @param addresses - Addresses to monitor
+     * @param eventCallback - Callback invoked when matching transactions are seen
+     * @returns Stop function that cancels the watch
+     * @remarks
+     * Implementations may use websockets, server-sent events, polling, or a hybrid strategy.
+     * @see getTransactions
+     */
+    watchAddresses(addresses: string[], eventCallback: (txs: ExplorerTransaction[]) => void): Promise<() => void>;
+}
+/**
+ * Implementation of the onchain provider interface for esplora REST API.
+ *
+ * @see https://mempool.space/docs/api/rest
+ * @example
+ * ```typescript
+ * const provider = new EsploraProvider("https://mempool.space/api");
+ * const outputs = await provider.getCoins("bcrt1q679zsd45msawvr7782r0twvmukns3drlstjt77");
+ * ```
+ */
+declare class EsploraProvider implements OnchainProvider {
+    private baseUrl;
+    readonly pollingInterval: number;
+    readonly forcePolling: boolean;
+    constructor(baseUrl?: string, opts?: {
+        /** Polling interval in milliseconds. */
+        pollingInterval?: number;
+        /** Force polling even when websocket transport is available. */
+        forcePolling?: boolean;
+    });
+    getCoins(address: string): Promise<Coin[]>;
+    getFeeRate(): Promise<number | undefined>;
+    broadcastTransaction(...txs: string[]): Promise<string>;
+    getTxOutspends(txid: string): Promise<{
+        spent: boolean;
+        txid?: string;
+    }[]>;
+    getTransactions(address: string): Promise<ExplorerTransaction[]>;
+    getTxStatus(txid: string): Promise<{
+        confirmed: false;
+    } | {
+        confirmed: true;
+        blockTime: number;
+        blockHeight: number;
+    }>;
+    watchAddresses(addresses: string[], callback: (txs: ExplorerTransaction[]) => void): Promise<() => void>;
+    getChainTip(): Promise<{
+        height: number;
+        time: number;
+        hash: string;
+    }>;
+    private broadcastPackage;
+    private broadcastTx;
+}
+
+/**
+ * The current moment, as the expiry predicates need it.
+ *
+ * `height` is optional: offline-first paths have no chain tip at hand. When it is absent,
+ * height-based expiry cannot be evaluated and reads as not expired.
+ */
+type TimeHeight = {
+    timestamp: Date;
+    height?: number;
+};
+/**
+ * A {@link VirtualCoin} that has passed through {@link normalizeVtxo}: every fact the capability
+ * predicates read is present.
+ *
+ * Internal signatures take this rather than `VirtualCoin` so the compiler rejects un-normalized
+ * input — on the public shape these facts are optional, and `undefined` is falsy, so a legacy coin
+ * would silently read as "not swept", "not spent", and drop out of the wrong bucket.
+ *
+ * It is deliberately a *subtype* of `VirtualCoin`, so normalized coins are returned to consumers
+ * directly and no egress projection exists.
+ */
+type NormalizedVirtualCoin = Omit<VirtualCoin, "isSwept" | "isPreconfirmed" | "isSpent" | "spentBy" | "commitmentTxIds"> & {
+    isSwept: boolean;
+    isPreconfirmed: boolean;
+    isSpent: boolean;
+    spentBy: string;
+    commitmentTxIds: string[];
+};
+type NormalizedExtendedVirtualCoin = ExtendedVirtualCoin & NormalizedVirtualCoin;
+/**
+ * Whether a virtual output has been consumed and can never be spent again.
+ *
+ * @remarks
+ * Unions all three spend facts rather than trusting any one of them. The wire contract permits
+ * `isSpent: true` with an empty `spentBy` (settlement inputs needing no forfeit are written that
+ * way), so a `spentBy || settledBy` definition would classify a spent VTXO as spendable — inflating
+ * balance and selecting it for a send that must fail.
+ */
+declare function hasTerminalSpend(vtxo: VirtualCoin): boolean;
+/**
+ * Whether a virtual output's batch expiry has passed. Pure expiry — swept is a separate fact, ORed
+ * in explicitly by {@link canSpendOffchain} / {@link canRecoverOnchain}.
+ *
+ * @remarks
+ * Not named `isExpired`: the deprecated {@link isExpired} also returns `true` for a swept VTXO, and
+ * two same-named predicates with different truth conditions is how a call site gets silently
+ * rewired.
+ *
+ * Height-based expiry is only evaluated when `now.height` is supplied.
+ */
+declare function isPastExpiry(vtxo: VirtualCoin, now: TimeHeight): boolean;
+/** Whether a virtual output can be spent in an offchain transaction. The send/coin-selection test. */
+declare function canSpendOffchain(vtxo: VirtualCoin, now: TimeHeight): boolean;
+/**
+ * Whether a virtual output must be recovered into a fresh batch rather than spent offchain. The
+ * recovery/renewal test and the `recoverable` balance bucket.
+ */
+declare function canRecoverOnchain(vtxo: VirtualCoin, now: TimeHeight): boolean;
+/**
+ * Narrow a settle input to a virtual output.
+ *
+ * @remarks
+ * Keyed on `script`: it is required on `VirtualCoin` (so legacy and canonical shapes both have it)
+ * and absent from `ExtendedCoin`, which the optional canonical facts cannot claim.
+ *
+ * The `typeof` guard is load-bearing — `settle` accepts arknote strings, and `in` throws a
+ * `TypeError` on a primitive rather than returning false.
+ */
+declare function isVirtualCoin<T>(input: T): input is T & VirtualCoin;
+/**
+ * Return whether a virtual output is still spendable.
+ *
+ * @param vtxo - virtual output to inspect
+ * @returns `true` when the virtual output has not been consumed
+ *
+ * @deprecated Ambiguous: `true` for swept or expired virtual outputs, which cannot in fact be spent
+ * offchain. Use {@link canSpendOffchain}.
+ */
+declare function isSpendable(vtxo: VirtualCoin): boolean;
+/**
+ * Return whether a virtual output is recoverable.
+ *
+ * @param vtxo - virtual output to inspect
+ * @returns `true` when the virtual output is swept but not yet consumed
+ *
+ * @deprecated Swept-only: ignores virtual outputs that are past expiry but not yet swept, which are
+ * equally recoverable. Use {@link canRecoverOnchain}.
+ */
+declare function isRecoverable(vtxo: VirtualCoin): boolean;
+/**
+ * Return whether a virtual output should be treated as expired.
+ *
+ * @param vtxo - virtual output to inspect
+ * @returns `true` when the virtual output is swept or its wall-clock batch expiry has passed
+ *
+ * @deprecated Conflates swept with expired, and cannot evaluate height-based expiry — being
+ * synchronous, it has no source for the current chain tip, so it ignores `expiresAtHeight` exactly
+ * as it always has. For the recovery decision use {@link canRecoverOnchain}; to reproduce this
+ * truth condition use `v.isSwept || isPastExpiry(v, now)`.
+ */
+declare function isExpired(vtxo: VirtualCoin): boolean;
+
 /**
  * Machine-readable classification of a contract's server signer relative to a
  * fresh {@link ArkInfo} snapshot. Drives both the migration selection (Section
@@ -826,7 +1105,7 @@ interface DeprecatedSignerReport {
  * exceeds the server's per-output ceiling (`vtxoMaxAmount`) — see
  * {@link MigrationLegReport.oversized}.
  */
-type MigrationLegSkipReason = "below-dust" | "oversized-only";
+type MigrationLegSkipReason = "below-dust" | "oversized-only" | "not-spendable-only";
 /**
  * Why the whole pass submitted nothing, before either leg was built.
  * `no-deprecated-vtxos` means BOTH migratable sets (VTXO and boarding) were
@@ -863,6 +1142,16 @@ interface MigrationLegReport {
      * absent when the server advertises no ceiling (`vtxoMaxAmount < 0`).
      */
     oversized?: MigrationVtxoRef[];
+    /**
+     * Inputs the leg's submit path would have rejected — for the VTXO leg, no longer
+     * cooperatively spendable at this pass's chain tip (past batch expiry, since swept and spent
+     * inputs are already excluded upstream) or carrying no batch expiry at all.
+     *
+     * Partitioned out rather than submitted, because the send path validates the batch as a
+     * whole: one rejected input would abort the entire leg and strand every other migratable
+     * VTXO until the next pass. Present only when non-empty.
+     */
+    notSpendableOffchain?: MigrationVtxoRef[];
     /** Error message when this leg's submission failed; the other leg still runs. */
     error?: string;
 }
@@ -905,7 +1194,7 @@ interface DeprecatedSignerMigrationReport {
  * - **Expiry monitoring**: Check for virtual outputs that are expiring soon
  *
  * Virtual outputs become recoverable when:
- * - The Arkade server sweeps them (virtualStatus.state === "swept") and they remain spendable
+ * - The Arkade server sweeps them (`isSwept`) and they remain spendable
  * - They are preconfirmed subdust (to consolidate small amounts without locking liquidity on settled virtual outputs)
  *
  * @example
@@ -1092,7 +1381,15 @@ declare class VtxoManager implements AsyncDisposable, IVtxoManager {
      * }
      * ```
      */
-    getExpiringVtxos(thresholdMs?: number): Promise<ExtendedVirtualCoin[]>;
+    getExpiringVtxos(thresholdMs?: number): Promise<NormalizedExtendedVirtualCoin[]>;
+    /**
+     * {@link getExpiringVtxos}, against a caller-supplied chain tip.
+     *
+     * The settle paths select, re-select after pre-flight, and sort by expiry within one pass;
+     * each of those judges expiry, so they share one tip rather than fetching (and possibly
+     * disagreeing on) one apiece. Fetches its own when `now` is omitted.
+     */
+    private selectExpiringVtxos;
     /**
      * Renew expiring virtual outputs by settling them back to the wallet's address
      *
@@ -1381,183 +1678,6 @@ declare class VtxoManager implements AsyncDisposable, IVtxoManager {
     [Symbol.asyncDispose](): Promise<void>;
 }
 
-type NetworkName = "bitcoin" | "testnet" | "signet" | "mutinynet" | "regtest";
-interface Network {
-    hrp: string;
-    bech32: string;
-    pubKeyHash: number;
-    scriptHash: number;
-    wif: number;
-}
-declare const getNetwork: (network: NetworkName) => Network;
-declare const networks: {
-    bitcoin: Network;
-    testnet: Network;
-    signet: Network;
-    mutinynet: Network;
-    regtest: Network;
-};
-
-/**
- * The default base URLs for esplora API providers.
- *
- * 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 arkade-regtest
- * stack exposing mempool's esplora API on the standard port.
- */
-declare const ESPLORA_URL: Record<NetworkName, string>;
-type ExplorerTransaction = {
-    txid: string;
-    /**
-     * Inputs as returned by Esplora's `/address/:addr/txs`, each carrying the
-     * outpoint it spends (`txid:vout`). Optional: not every provider populates
-     * it (the electrum provider omits inputs), so consumers that correlate
-     * spenders must tolerate its absence. Used to recover a boarding output's
-     * spending (commitment) tx when `/outspends` omits the spender txid.
-     */
-    vin?: {
-        txid: string;
-        vout: number;
-    }[];
-    vout: {
-        scriptpubkey_address: string;
-        value: string;
-    }[];
-    status: {
-        confirmed: boolean;
-        block_time: number;
-    };
-};
-interface OnchainProvider {
-    /**
-     * Fetch spendable onchain outputs for an address.
-     *
-     * @param address - Bitcoin address to query
-     * @returns Spendable onchain outputs for the address
-     * @see Coin
-     */
-    getCoins(address: string): Promise<Coin[]>;
-    /**
-     * Fetch the current fastest fee rate estimate.
-     *
-     * @returns Fee rate in sats/vB, if available
-     * @remarks
-     * Implementations may return `undefined` when the backing service does not expose
-     * a usable fee estimate.
-     */
-    getFeeRate(): Promise<number | undefined>;
-    /**
-     * Broadcast a single transaction or a 1P1C package.
-     *
-     * @param txs - One or more raw transaction hex strings
-     * @returns Broadcast transaction id
-     * @throws Error if the broadcast request fails or the package shape is invalid
-     */
-    broadcastTransaction(...txs: string[]): Promise<string>;
-    /**
-     * Fetch outspend information for every output in a transaction.
-     *
-     * @param txid - Transaction id to inspect
-     * @returns Per-output spend status information. `txid` (the spender) may be
-     *   absent even when `spent` is true: some Esplora deployments
-     *   (e.g. mempool.arkade.sh) omit it from `/outspends`.
-     * @see getTxStatus
-     */
-    getTxOutspends(txid: string): Promise<{
-        spent: boolean;
-        txid?: string;
-    }[]>;
-    /**
-     * Fetch transactions associated with an address.
-     *
-     * @param address - Bitcoin address to query
-     * @returns Transactions involving the address
-     * @see ExplorerTransaction
-     */
-    getTransactions(address: string): Promise<ExplorerTransaction[]>;
-    /**
-     * Fetch confirmation status for a transaction.
-     *
-     * @param txid - Transaction id to inspect
-     * @returns Confirmation status and block metadata when confirmed
-     * @see getTxOutspends
-     */
-    getTxStatus(txid: string): Promise<{
-        confirmed: false;
-    } | {
-        confirmed: true;
-        blockTime: number;
-        blockHeight: number;
-    }>;
-    /**
-     * Fetch the current chain tip.
-     *
-     * @returns Current chain height, block time, and block hash
-     */
-    getChainTip(): Promise<{
-        height: number;
-        time: number;
-        hash: string;
-    }>;
-    /**
-     * Watch a set of addresses and invoke the callback when transactions are observed.
-     *
-     * @param addresses - Addresses to monitor
-     * @param eventCallback - Callback invoked when matching transactions are seen
-     * @returns Stop function that cancels the watch
-     * @remarks
-     * Implementations may use websockets, server-sent events, polling, or a hybrid strategy.
-     * @see getTransactions
-     */
-    watchAddresses(addresses: string[], eventCallback: (txs: ExplorerTransaction[]) => void): Promise<() => void>;
-}
-/**
- * Implementation of the onchain provider interface for esplora REST API.
- *
- * @see https://mempool.space/docs/api/rest
- * @example
- * ```typescript
- * const provider = new EsploraProvider("https://mempool.space/api");
- * const outputs = await provider.getCoins("bcrt1q679zsd45msawvr7782r0twvmukns3drlstjt77");
- * ```
- */
-declare class EsploraProvider implements OnchainProvider {
-    private baseUrl;
-    readonly pollingInterval: number;
-    readonly forcePolling: boolean;
-    constructor(baseUrl?: string, opts?: {
-        /** Polling interval in milliseconds. */
-        pollingInterval?: number;
-        /** Force polling even when websocket transport is available. */
-        forcePolling?: boolean;
-    });
-    getCoins(address: string): Promise<Coin[]>;
-    getFeeRate(): Promise<number | undefined>;
-    broadcastTransaction(...txs: string[]): Promise<string>;
-    getTxOutspends(txid: string): Promise<{
-        spent: boolean;
-        txid?: string;
-    }[]>;
-    getTransactions(address: string): Promise<ExplorerTransaction[]>;
-    getTxStatus(txid: string): Promise<{
-        confirmed: false;
-    } | {
-        confirmed: true;
-        blockTime: number;
-        blockHeight: number;
-    }>;
-    watchAddresses(addresses: string[], callback: (txs: ExplorerTransaction[]) => void): Promise<() => void>;
-    getChainTip(): Promise<{
-        height: number;
-        time: number;
-        hash: string;
-    }>;
-    private broadcastPackage;
-    private broadcastTx;
-}
-
 interface WalletState {
     /** Arbitrary stored wallet settings. */
     settings?: Record<string, any>;
@@ -1802,14 +1922,26 @@ interface HandlerError {
 }
 /**
  * Outcome of a {@link IContractManager.scanContracts} run.
- *
- * `lastIndexUsed` is the highest HD index at which any handler discovered a
- * contract (`-1` if nothing was found). `handlerErrors` collects per-handler
- * `discoverAt` failures — non-empty means the gap window may have closed
- * early and the caller should surface this (the scan itself still resolved).
  */
 interface ScanResult {
+    /** @deprecated Alias of {@link ScanResult.highestConfirmedUsedIndex}. */
     lastIndexUsed: number;
+    /**
+     * Highest HD index at which any handler confirmed a contract (`-1` if none),
+     * including hits past {@link ScanResult.truncatedAt}. Safe to record
+     * unconditionally: the HD watermark it feeds is a monotonic max over a scan
+     * that always restarts at 0, so it cannot skip an index — while withholding
+     * it risks re-issuing a funded index as a fresh receive address.
+     */
+    highestConfirmedUsedIndex: number;
+    /**
+     * First index a handler failed at, making it *indeterminate* — neither a hit
+     * nor a confirmed miss. The scan stops there, so indices `>= truncatedAt` are
+     * unverified and the caller must retry (scanning is idempotent). `undefined`
+     * when the scan closed a genuine gap.
+     */
+    truncatedAt?: number;
+    /** Per-handler `discoverAt` failures. Non-empty implies `truncatedAt` is set. */
     handlerErrors: HandlerError[];
 }
 /**
@@ -1895,7 +2027,7 @@ interface IContractManager extends Disposable {
      * in wallet/handler code, and keeps the wallet from silently stamping the
      * default tapscript onto a non-default vtxo.
      */
-    annotateVtxos(vtxos: VirtualCoin[]): Promise<ExtendedVirtualCoin[]>;
+    annotateVtxos(vtxos: VirtualCoin[]): Promise<NormalizedExtendedVirtualCoin[]>;
     /**
      * Update mutable contract fields.
      *
@@ -1961,15 +2093,17 @@ interface IContractManager extends Disposable {
      *
      * Error contract (safety-critical — see spec §4):
      * - A handler's `discoverAt` rejecting is **collected** into
-     *   `handlerErrors` and the loop **continues**; it never aborts the
-     *   scan or throws.
+     *   `handlerErrors` and makes its index *indeterminate*: it never
+     *   advances the gap counter, and the scan **stops verifying** there
+     *   rather than closing a window it never observed close. It still
+     *   never throws.
      * - A fatal operational error — `materialize()` throwing, or
      *   `createContract` rejecting — **propagates** out of `scanContracts`
      *   (it invalidates the gap-window signal, so a silent truncation
      *   would risk hiding user funds).
      *
      * @param opts See {@link ScanContractsOptions}.
-     * @returns `{ lastIndexUsed, handlerErrors }` — the caller surfaces
+     * @returns See {@link ScanResult}. The caller surfaces `truncatedAt` /
      *   `handlerErrors` *after* the inline VTXO pull.
      */
     scanContracts(opts: ScanContractsOptions): Promise<ScanResult>;
@@ -2182,9 +2316,10 @@ declare class ContractManager implements IContractManager {
      * Safety-critical invariants (spec §2.C / §4):
      * - `opts.materialize(i)` throwing is structural/fatal: it is NOT
      *   wrapped — it propagates and aborts the scan.
-     * - A `discoverAt` rejection is collected into `handlerErrors` and the
-     *   loop continues (the gap counter still advances for that index if no
-     *   other handler hit it).
+     * - A `discoverAt` rejection is collected into `handlerErrors` and makes
+     *   its index *indeterminate*: it does NOT advance the gap counter, and
+     *   the scan stops verifying there, reporting `truncatedAt`. Only an index
+     *   every handler answered for can be a confirmed miss.
      * - `persistAndWatchContract` rejecting is operational/fatal and
      *   propagates (only `discoverAt` is guarded).
      * - Within an index the handler probes run concurrently (independent
@@ -2198,8 +2333,12 @@ declare class ContractManager implements IContractManager {
      *   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.
+     *   persisted rows, `highestConfirmedUsedIndex`, and `handlerErrors` are
+     *   byte-for-byte identical to the serial path — only the wall-clock
+     *   differs. Truncation is the one exception: a window's concurrent probes
+     *   can surface hits above the failed index that a serial scan would never
+     *   have reached, so a truncated batched scan discovers a superset — never
+     *   a subset — of the serial one.
      */
     scanContracts(opts: ScanContractsOptions): Promise<ScanResult>;
     /**
@@ -2219,7 +2358,7 @@ declare class ContractManager implements IContractManager {
      */
     getContracts(filter?: GetContractsFilter): Promise<Contract[]>;
     getContractsWithVtxos(filter?: GetContractsFilter, pageSize?: number): Promise<ContractWithVtxos[]>;
-    annotateVtxos(vtxos: VirtualCoin[]): Promise<ExtendedVirtualCoin[]>;
+    annotateVtxos(vtxos: VirtualCoin[]): Promise<NormalizedExtendedVirtualCoin[]>;
     private buildContractsDbFilter;
     /**
      * Update a contract.
@@ -2438,7 +2577,7 @@ type ContractVtxo = VirtualCoin & Partial<TapLeaves & EncodedVtxoScript> & {
  * should enforce that annotation has happened — e.g. `saveVtxos` and
  * forfeit transaction construction.
  */
-type ExtendedContractVtxo = ExtendedVirtualCoin & {
+type ExtendedContractVtxo = NormalizedExtendedVirtualCoin & {
     contractScript: string;
 };
 /**
@@ -2899,6 +3038,10 @@ declare class ContractWatcher {
     private listenLoop;
     /**
      * Handle a subscription update.
+     *
+     * Normalization boundary: `getSubscription` is part of the public `IndexerProvider` interface,
+     * so a consumer implementation may yield legacy-shaped VTXOs. Normalizing on ingest also fixes
+     * the shape of the payloads emitted to external event consumers.
      */
     private handleSubscriptionUpdate;
     /**
@@ -3676,7 +3819,13 @@ interface BurnParams {
  * @see Output
  */
 interface SettleParams {
-    /** Offchain virtual outputs and/or onchain boarding inputs to settle. */
+    /**
+     * Offchain virtual outputs and/or onchain boarding inputs to settle.
+     *
+     * @remarks
+     * Arknotes are settled by passing the `ArkNote` itself (it is an `ExtendedCoin`), not its
+     * string form — `ArkNote.fromString(note)`.
+     */
     inputs: ExtendedCoin[];
     /** Optional onchain outputs to create (i.e., exit to). */
     outputs: Output[];
@@ -3706,7 +3855,13 @@ interface Status {
     block_time?: number;
 }
 /**
- * Virtual output status
+ * Virtual output status.
+ *
+ * @deprecated Use the canonical facts on {@link VirtualCoin} — `isSwept`, `isPreconfirmed`,
+ * `isSpent`, `expiresAt`, `expiresAtHeight`, `commitmentTxIds`, `spentBy`, `settledBy` — and the
+ * capability predicates {@link canSpendOffchain}, {@link canRecoverOnchain},
+ * {@link hasTerminalSpend}, {@link isPastExpiry}. `state` collapses independent facts into one
+ * lossy label; this object is retained only as a backward-compatible projection.
  */
 interface VirtualStatus {
     /**
@@ -3717,25 +3872,24 @@ interface VirtualStatus {
      * - `swept`: expired/swept and recoverable in a new batch
      * - `spent`: destroyed by a later transaction
      *
-     * @remarks
-     * `state` is the high-level lifecycle summary used throughout wallet balance,
-     * recovery, and transaction history logic.
+     * @deprecated Lossy: the states are not orthogonal and collapse with precedence
+     * `spent` > `swept` > `preconfirmed` > `settled`, so a spent VTXO that was also swept reports
+     * only `spent`. Read `isSpent`/`isSwept`/`isPreconfirmed` instead, or a capability predicate.
      */
     state: "preconfirmed" | "settled" | "swept" | "spent";
     /**
      * Which batch commitment transaction(s) this virtual output depends on.
      *
-     * @remarks
-     * The history builder uses these ids to group received batch transactions and
-     * relate refreshed or forfeited virtual outputs back to the same batch.
+     * @deprecated Use {@link VirtualCoin.commitmentTxIds}.
      */
     commitmentTxIds?: string[];
     /**
-     * The earliest point at which this virtual output stops being safely preconfirmed.
+     * The earliest point at which this virtual output stops being safely preconfirmed,
+     * in milliseconds.
      *
-     * @remarks
-     * The value is stored in milliseconds in the wallet model and is used by expiry
-     * and recovery logic to decide when a virtual output can be swept or renewed.
+     * @deprecated Unit-ambiguous: the server returns a single scalar that is either unix seconds or
+     * a block height, and both land here multiplied by 1000. Use {@link VirtualCoin.expiresAt} and
+     * {@link VirtualCoin.expiresAtHeight}, which disambiguate the two.
      */
     batchExpiry?: number;
 }
@@ -3760,8 +3914,16 @@ interface Coin extends Outpoint {
 /**
  * Virtual output data.
  *
+ * @remarks
+ * The canonical facts (`isSwept`, `isPreconfirmed`, `isSpent`, `expiresAt`, `expiresAtHeight`,
+ * `commitmentTxIds`) are optional because `VirtualCoin` is also a *construction* type: custom
+ * {@link IndexerProvider} and {@link WalletRepository} implementations may hand back coins without
+ * them. The SDK normalizes every incoming coin, so coins it returns always carry the facts that are
+ * determinable; do not read these fields off a coin the SDK has not returned to you — use
+ * {@link canSpendOffchain} / {@link canRecoverOnchain} / {@link hasTerminalSpend} /
+ * {@link isPastExpiry}, which normalize defensively.
+ *
  * @see Coin
- * @see VirtualStatus
  */
 interface VirtualCoin extends Coin {
     /** Creation time of the virtual output. */
@@ -3775,13 +3937,40 @@ interface VirtualCoin extends Coin {
      * This is not set to true if the virtual output is unrolled or swept, only when it's spent offchain.
      */
     isSpent?: boolean;
+    /** Whether the server has swept the batch this virtual output belongs to. */
+    isSwept?: boolean;
+    /** Whether this virtual output is not yet finalized in a batch. */
+    isPreconfirmed?: boolean;
     /** ID of the onchain commitment transaction that settled this output, if applicable. */
     settledBy?: string;
-    /** ID of the offchain checkpoint transaction that spent this output, if applicable. */
+    /**
+     * ID of the offchain checkpoint transaction that spent this output.
+     *
+     * @remarks
+     * The empty string means "not spent by anything" — test truthiness, never presence.
+     */
     spentBy?: string;
     /** ID of the offchain Arkade transaction that spent the above checkpoint output, if applicable. */
     arkTxId?: string;
-    /** Virtual output status */
+    /** Batch commitment transaction(s) this virtual output depends on. */
+    commitmentTxIds?: string[];
+    /**
+     * Wall-clock batch expiry, when the server expressed expiry as a timestamp.
+     *
+     * @remarks
+     * Mutually exclusive with `expiresAtHeight`; both are absent when there is no expiry.
+     */
+    expiresAt?: Date;
+    /**
+     * Block-height batch expiry, when the server expressed expiry as a height (regtest-like
+     * deployments). Evaluating it needs a chain tip — see {@link isPastExpiry}.
+     */
+    expiresAtHeight?: number;
+    /**
+     * Virtual output status.
+     *
+     * @deprecated See {@link VirtualStatus}.
+     */
     virtualStatus: VirtualStatus;
     /** Assets carried by this virtual output, if any. */
     assets?: Asset[];
@@ -3854,42 +4043,7 @@ type ExtendedCoin = TapLeaves & EncodedVtxoScript & Coin & {
 type ExtendedVirtualCoin = TapLeaves & EncodedVtxoScript & VirtualCoin & {
     extraWitness?: Bytes[];
 };
-/**
- * Return whether a virtual output is still spendable.
- *
- * @param vtxo - virtual output to inspect
- * @returns `true` when the virtual output is not marked as spent
- *
- * @see isRecoverable
- * @see isExpired
- */
-declare function isSpendable(vtxo: VirtualCoin): boolean;
-/**
- * Return whether a virtual output is recoverable.
- *
- * @param vtxo - virtual output to inspect
- * @returns `true` when the virtual output is swept but still spendable
- *
- * @remarks
- * Recoverable virtual outputs are typically re-settled into fresh virtual outputs by the virtual output manager.
- *
- * @see isSpendable
- * @see isExpired
- */
-declare function isRecoverable(vtxo: VirtualCoin): boolean;
-/**
- * Return whether a virtual output should be treated as expired.
- *
- * @param vtxo - virtual output to inspect
- * @returns `true` when the virtual output is swept or its batch expiry has passed
- * @remarks
- * On regtest-like environments the upstream expiry value may be expressed as a block
- * height instead of a timestamp. This helper intentionally ignores obviously non-time
- * values to avoid false positives.
- *
- * @see VirtualStatus.batchExpiry
- */
-declare function isExpired(vtxo: VirtualCoin): boolean;
+
 /**
  * Return whether a virtual output is below the dust threshold.
  *
@@ -4031,10 +4185,11 @@ interface IReadonlyWallet {
      * Get virtual outputs tracked by the wallet.
      *
      * @param filter - Optional filtering flags
-     * @returns virtual outputs with tapscript and witness data
+     * @returns virtual outputs with tapscript and witness data, normalized: every canonical fact
+     * the capability predicates read is populated, whatever the underlying repository stored
      * @see GetVtxosFilter
      */
-    getVtxos(filter?: GetVtxosFilter): Promise<ExtendedVirtualCoin[]>;
+    getVtxos(filter?: GetVtxosFilter): Promise<NormalizedExtendedVirtualCoin[]>;
     /** @returns Onchain boarding inputs tracked by the wallet. */
     getBoardingUtxos(): Promise<ExtendedCoin[]>;
     /** @returns Wallet transaction history derived from boarding and Arkade activity. */
@@ -4810,4 +4965,4 @@ declare namespace ProtoTypes {
     export {  };
 }
 
-export { type Network as $, type ArkTransaction as A, type VirtualTxRepository as B, type ContractRepository as C, type VirtualTx as D, type ExtendedVirtualCoin as E, type VtxoBranch as F, type GetVtxosFilter as G, ChainedTxType as H, type IWallet as I, type BatchStartedEvent as J, type TreeSigningStartedEvent as K, TxTree as L, type TreeNoncesEvent as M, type BatchFinalizationEvent as N, type Outpoint as O, type BatchFinalizedEvent as P, type BatchFailedEvent as Q, type Recipient as R, type SendBitcoinParams as S, type TxNotification as T, type TreeTxEvent as U, VtxoScript as V, type WalletRepository as W, type TreeSignatureEvent as X, type DescriptorProvider as Y, type IReadonlyWallet as Z, type ReadonlyIdentity as _, type Identity as a, ConditionCSVMultisigTapscript as a$, type OnchainProvider as a0, type DelegateProvider as a1, type ReadonlyWalletConfig as a2, type ExitCaptureMode as a3, type ExitDataSource as a4, type IReadonlyAssetManager as a5, type ContractSyncState as a6, type NetworkName as a7, type ArkInfo as a8, ArkAddress as a9, type ContractWithVtxos as aA, type PathSelection as aB, type ContractEvent as aC, type AssetDetails as aD, type IssuanceResult as aE, type DelegateInfo as aF, type MigrationGlobalSkipReason as aG, type MigrationLegSkipReason as aH, type SignerStatus as aI, type StorageConfig as aJ, type IVtxoManager as aK, type ExplorerTransaction as aL, type EncodedVtxoScript as aM, type Status as aN, type ChainTx as aO, type PathContext as aP, type ActivityIntent as aQ, type ActivityResolver as aR, type ArkIntentState as aS, type ArkTapscript as aT, type AssetMetadata as aU, type BaseWalletConfig as aV, type BatchInfo as aW, type BatchSignableIdentity as aX, CLTVMultisigTapscript as aY, ChainTxType as aZ, type CommitmentTx as a_, type Coin as aa, ContractManager as ab, CSVMultisigTapscript as ac, type SettlementConfig as ad, VtxoManager as ae, type SignerSession as af, type SignedIntent as ag, Intent as ah, type DescriptorSigningRequest as ai, Transaction as aj, type IntentFeeConfig as ak, type OffchainInput as al, FeeAmount as am, type OnchainInput as an, type FeeOutput as ao, type ContractWatcherConfig as ap, type Asset as aq, type FeeInfo as ar, type CreateContractParams as as, type GetContractsFilter as at, type GetSpendablePathsOptions as au, type GetAllSpendingPathsOptions as av, type IssuanceParams as aw, type ReissuanceParams as ax, type BurnParams as ay, type RenewVtxosOptions as az, type WalletConfig as b, type WalletMode as b$, ConditionMultisigTapscript as b0, type ContractBalance as b1, type ContractEventCallback as b2, type ContractHandler as b3, type ContractManagerConfig as b4, type ContractState as b5, type ContractVtxo as b6, ContractWatcher as b7, DelegateManagerImpl as b8, type DelegateOptions as b9, PartialSig as bA, type ProviderClass as bB, RestDelegateProvider as bC, RestDelegatorProvider as bD, type ScanContractsOptions as bE, type ScanResult as bF, type ScheduledSession as bG, SettlementEventType as bH, type SignRequest as bI, type SignerClassification as bJ, type SignerSet as bK, type SubscriptionEvent as bL, type SubscriptionHeartbeat as bM, type TapLeaves as bN, TapTreeCoder as bO, TapscriptType as bP, type TreeNonces as bQ, type TreePartialSigs as bR, type Tx as bS, type TxHistoryRecord as bT, type TxKey as bU, type TxTreeNode as bV, TxType as bW, type VirtualStatus as bX, type Vtxo as bY, type VtxoChain as bZ, type VtxoType as b_, DelegatorManagerImpl as ba, type DelegatorProvider as bb, type DeprecatedSignerMigrationReport as bc, type DeprecatedSignerReport as bd, DigestMismatchError as be, type Discoverable as bf, type DiscoveredContract as bg, type DiscoveryDeps as bh, ESPLORA_URL as bi, EsploraProvider as bj, type ExitChainResolver as bk, type ExtendedContractVtxo as bl, type GroupMembership as bm, type HandlerError as bn, type IDelegatorManager as bo, INTENT_TERMINAL_STATES as bp, IndexerTxType as bq, type KnownMetadata as br, type MigrateDeprecatedSignerOptions as bs, type MigrationLegReport as bt, type MigrationVtxoRef as bu, MultisigTapscript as bv, type Nonces as bw, type Output as bx, type PageResponse as by, type PaginationOptions as bz, type WalletBalance as c, boardingResolver as c0, classifyAgainstSignerSet as c1, classifyContractSigner as c2, createDefaultActivityRegistry as c3, createExitChainResolver as c4, decodeTapscript as c5, getNetwork as c6, getSequence as c7, isBatchSignable as c8, isCooperativelyMigratable as c9, isDiscoverable as ca, isExpired as cb, isRecoverable as cc, isSpendable as cd, isSubdust as ce, isTerminalIntentState as cf, isVtxoExpiringSoon as cg, networks as ch, signerSetFromInfo as ci, toXOnlySignerHex as cj, type TapscriptDeriving as ck, type ExtendedCoin as d, ActivityRegistry as e, type Activity as f, type IContractManager as g, type IDelegateManager as h, type SettleParams as i, type SettlementEvent as j, type IAssetManager as k, RestArkProvider as l, RestIndexerProvider as m, type SubscriptionResponse as n, type ArkProvider as o, type IndexerProvider as p, type RelativeTimelock as q, type TapLeafScript as r, type VirtualCoin as s, type Contract as t, type VtxoRepositoryKey as u, type WalletState as v, type ContractFilter as w, type IntentRepository as x, type ArkIntent as y, type IntentFilter as z };
+export { type ReadonlyIdentity as $, type ArkTransaction as A, type VirtualTxRepository as B, type ContractRepository as C, type VirtualTx as D, type ExtendedCoin as E, type VtxoBranch as F, type GetVtxosFilter as G, ChainedTxType as H, type IWallet as I, type BatchStartedEvent as J, type TreeSigningStartedEvent as K, TxTree as L, type TreeNoncesEvent as M, type NormalizedExtendedVirtualCoin as N, type Outpoint as O, type BatchFinalizationEvent as P, type BatchFinalizedEvent as Q, type Recipient as R, type SendBitcoinParams as S, type TxNotification as T, type BatchFailedEvent as U, VtxoScript as V, type WalletRepository as W, type TreeTxEvent as X, type TreeSignatureEvent as Y, type DescriptorProvider as Z, type IReadonlyWallet as _, type Identity as a, ChainTxType as a$, type Network as a0, type OnchainProvider as a1, type DelegateProvider as a2, type ReadonlyWalletConfig as a3, type ExitCaptureMode as a4, type ExitDataSource as a5, type IReadonlyAssetManager as a6, type ContractSyncState as a7, type NetworkName as a8, type ArkInfo as a9, type BurnParams as aA, type RenewVtxosOptions as aB, type ContractWithVtxos as aC, type PathSelection as aD, type ContractEvent as aE, type AssetDetails as aF, type IssuanceResult as aG, type DelegateInfo as aH, type MigrationGlobalSkipReason as aI, type MigrationLegSkipReason as aJ, type SignerStatus as aK, type StorageConfig as aL, type IVtxoManager as aM, type ExplorerTransaction as aN, type EncodedVtxoScript as aO, type Status as aP, type ChainTx as aQ, type PathContext as aR, type ActivityIntent as aS, type ActivityResolver as aT, type ArkIntentState as aU, type ArkTapscript as aV, type AssetMetadata as aW, type BaseWalletConfig as aX, type BatchInfo as aY, type BatchSignableIdentity as aZ, CLTVMultisigTapscript as a_, ArkAddress as aa, type Coin as ab, ContractManager as ac, CSVMultisigTapscript as ad, type SettlementConfig as ae, VtxoManager as af, type SignerSession as ag, type SignedIntent as ah, Intent as ai, type TimeHeight as aj, type DescriptorSigningRequest as ak, Transaction as al, type IntentFeeConfig as am, type OffchainInput as an, FeeAmount as ao, type OnchainInput as ap, type FeeOutput as aq, type ContractWatcherConfig as ar, type Asset as as, type FeeInfo as at, type CreateContractParams as au, type GetContractsFilter as av, type GetSpendablePathsOptions as aw, type GetAllSpendingPathsOptions as ax, type IssuanceParams as ay, type ReissuanceParams as az, type WalletConfig as b, type VtxoChain as b$, type CommitmentTx as b0, ConditionCSVMultisigTapscript as b1, ConditionMultisigTapscript as b2, type ContractBalance as b3, type ContractEventCallback as b4, type ContractHandler as b5, type ContractManagerConfig as b6, type ContractState as b7, type ContractVtxo as b8, ContractWatcher as b9, type PageResponse as bA, type PaginationOptions as bB, PartialSig as bC, type ProviderClass as bD, RestDelegateProvider as bE, RestDelegatorProvider as bF, type ScanContractsOptions as bG, type ScanResult as bH, type ScheduledSession as bI, SettlementEventType as bJ, type SignRequest as bK, type SignerClassification as bL, type SignerSet as bM, type SubscriptionEvent as bN, type SubscriptionHeartbeat as bO, type TapLeaves as bP, TapTreeCoder as bQ, TapscriptType as bR, type TreeNonces as bS, type TreePartialSigs as bT, type Tx as bU, type TxHistoryRecord as bV, type TxKey as bW, type TxTreeNode as bX, TxType as bY, type VirtualStatus as bZ, type Vtxo as b_, DelegateManagerImpl as ba, type DelegateOptions as bb, DelegatorManagerImpl as bc, type DelegatorProvider as bd, type DeprecatedSignerMigrationReport as be, type DeprecatedSignerReport as bf, DigestMismatchError as bg, type Discoverable as bh, type DiscoveredContract as bi, type DiscoveryDeps as bj, ESPLORA_URL as bk, EsploraProvider as bl, type ExitChainResolver as bm, type ExtendedContractVtxo as bn, type GroupMembership as bo, type HandlerError as bp, type IDelegatorManager as bq, INTENT_TERMINAL_STATES as br, IndexerTxType as bs, type KnownMetadata as bt, type MigrateDeprecatedSignerOptions as bu, type MigrationLegReport as bv, type MigrationVtxoRef as bw, MultisigTapscript as bx, type Nonces as by, type Output as bz, type WalletBalance as c, type VtxoType as c0, type WalletMode as c1, boardingResolver as c2, canRecoverOnchain as c3, canSpendOffchain as c4, classifyAgainstSignerSet as c5, classifyContractSigner as c6, createDefaultActivityRegistry as c7, createExitChainResolver as c8, decodeTapscript as c9, getNetwork as ca, getSequence as cb, hasTerminalSpend as cc, isBatchSignable as cd, isCooperativelyMigratable as ce, isDiscoverable as cf, isExpired as cg, isPastExpiry as ch, isRecoverable as ci, isSpendable as cj, isSubdust as ck, isTerminalIntentState as cl, isVirtualCoin as cm, isVtxoExpiringSoon as cn, networks as co, signerSetFromInfo as cp, toXOnlySignerHex as cq, type TapscriptDeriving as cr, ActivityRegistry as d, type Activity as e, type IContractManager as f, type IDelegateManager as g, type SettleParams as h, type SettlementEvent as i, type IAssetManager as j, RestArkProvider as k, RestIndexerProvider as l, type SubscriptionResponse as m, type ArkProvider as n, type IndexerProvider as o, type RelativeTimelock as p, type TapLeafScript as q, type VirtualCoin as r, type Contract as s, type ExtendedVirtualCoin as t, type VtxoRepositoryKey as u, type WalletState as v, type ContractFilter as w, type IntentRepository as x, type ArkIntent as y, type IntentFilter as z };