@arkade-os/sdk 0.4.15 → 0.4.17

package/dist/types/wallet/vtxo-manager.d.ts

@@ -1,22 +1,32 @@
 import { ExtendedCoin, ExtendedVirtualCoin, IWallet } from ".";
 import { SettlementEvent } from "../providers/ark";
-export declare const DEFAULT_THRESHOLD_MS: number;
+/** Default renewal threshold in seconds (3 days). */
 export declare const DEFAULT_THRESHOLD_SECONDS: number;
 /**
- * Configuration options for automatic VTXO renewal
- * @deprecated Use SettlementConfig instead
+ * Default renewal threshold in milliseconds (3 days).
+ */
+export declare const DEFAULT_THRESHOLD_MS: number;
+/**
+ * Configuration options for automatic virtual output renewal
+ *
+ * @see DEFAULT_RENEWAL_CONFIG
+ * @deprecated Leave `renewalConfig` undefined and use `settlementConfig` instead.
+ * @see SettlementConfig
  */
 export interface RenewalConfig {
     /**
      * Enable automatic renewal monitoring
-     * @default false
+     *
+     * @defaultValue `false`
+     * @deprecated Explicitly set `settlementConfig` to `false` to disable VTXO renewal.
      */
     enabled?: boolean;
     /**
      * Threshold in milliseconds to use as threshold for renewal
-     * E.g., 86400000 means renew when 24 hours until expiry remains
-     * @default 86400000 (24 hours)
-     * @deprecated Use SettlementConfig.vtxoThreshold (in seconds) instead
+     * E.g., 86_400_000 means renew when 24 hours until expiry remains
+     *
+     * @defaultValue `259_200_000` (3 days).
+     * @deprecated Use `SettlementConfig.vtxoThreshold` (in seconds) instead.
      */
     thresholdMs?: number;
 }
@@ -24,111 +34,142 @@ export interface RenewalConfig {
  * Configuration for automatic settlement and renewal.
  *
  * Controls two behaviors:
- * 1. **VTXO renewal**: Automatically renew VTXOs that are close to expiry
- * 2. **Boarding UTXO sweep**: Sweep expired boarding UTXOs back to a fresh boarding address
- *    via the unilateral exit path (on-chain self-spend to restart the timelock)
+ * 1. **VTXO renewal**: Automatically renew virtual outputs that are close to expiry
+ * 2. **Boarding UTXO sweep**: Sweep expired boarding inputs back to a fresh boarding address
+ *    via the unilateral exit path (onchain self-spend to restart the timelock)
  *
  * Enabled by default when no config is provided.
  * Pass `false` to explicitly disable all settlement behavior.
  *
+ * @remarks
+ * VTXO renewal and boarding UTXO sweep are both coordinated by `VtxoManager`, which periodically
+ * inspects wallet virtual outputs and boarding inputs and decides whether action is needed.
+ *
+ * @see DEFAULT_SETTLEMENT_CONFIG
+ *
  * @example
  * ```typescript
- * // Default behavior: VTXO renewal at 3 days + boarding sweep enabled
+ * // Default behavior: virtual output renewal at 3 days, boarding sweep enabled, polling every minute
  * const wallet = await Wallet.create({
- *   identity: SingleKey.fromHex('...'),
- *   arkServerUrl: 'https://ark.example.com',
+ *   identity: MnemonicIdentity.fromMnemonic('abandon abandon...'),
+ *   arkServerUrl: 'https://arkade.computer',
  * });
  *
- * // Custom threshold
+ * // Custom expiry threshold of 24 hours
  * const wallet = await Wallet.create({
- *   identity: SingleKey.fromHex('...'),
- *   arkServerUrl: 'https://ark.example.com',
+ *   identity: MnemonicIdentity.fromMnemonic('abandon abandon...'),
+ *   arkServerUrl: 'https://arkade.computer',
  *   settlementConfig: {
- *     vtxoThreshold: 86400, // 24 hours in seconds
+ *     vtxoThreshold: 60 * 60 * 24, // 24 hours in seconds
  *   },
  * });
  *
  * // Explicitly disable
  * const wallet = await Wallet.create({
- *   identity: SingleKey.fromHex('...'),
- *   arkServerUrl: 'https://ark.example.com',
+ *   identity: MnemonicIdentity.fromMnemonic('abandon abandon...'),
+ *   arkServerUrl: 'https://arkade.computer',
  *   settlementConfig: false,
  * });
  * ```
  */
 export interface SettlementConfig {
     /**
-     * Seconds before VTXO expiry to trigger renewal.
-     * @default 259200 (3 days)
+     * Seconds before virtual output expiry to trigger renewal.
+     *
+     * @defaultValue `259_200` (3 days)
      */
     vtxoThreshold?: number;
     /**
-     * Sweep expired boarding UTXOs back to a fresh boarding address
-     * via the unilateral exit path (on-chain self-spend to restart the timelock).
+     * Sweep expired boarding inputs back to a fresh boarding address
+     * via the unilateral exit path (onchain self-spend to restart the timelock).
+     *
+     * When enabled, expired boarding inputs are batched into a single onchain
+     * transaction with multiple inputs and one output.
      *
-     * When enabled, expired boarding UTXOs are batched into a single on-chain transaction
-     * with multiple inputs and one output. A dust check ensures the sweep is only
-     * performed when the output after fees is above dust.
+     * A dust check ensures the sweep is only performed when the output
+     * after fees is above dust.
      *
-     * @default true
+     * @defaultValue `true`
      */
     boardingUtxoSweep?: boolean;
     /**
-     * Polling interval in milliseconds for checking boarding UTXOs.
-     * The poll loop auto-settles new boarding UTXOs into Ark and
+     * Polling interval in milliseconds for checking boarding inputs.
+     * The poll loop auto-settles new boarding inputs into Arkade and
      * sweeps expired ones (when boardingUtxoSweep is enabled).
      *
-     * @default 60000 (1 minute)
+     * @defaultValue `60_000` (1 minute)
      */
     pollIntervalMs?: number;
 }
 /**
- * Default renewal configuration values
- * @deprecated Use DEFAULT_SETTLEMENT_CONFIG instead
+ * Default renewal configuration values.
+ *
+ * @see RenewalConfig
+ * @deprecated Leave `renewalConfig` undefined and use `settlementConfig` instead.
+ * @see SettlementConfig
  */
 export declare const DEFAULT_RENEWAL_CONFIG: Required<Omit<RenewalConfig, "enabled">>;
 /**
- * Default settlement configuration values
+ * Default settlement configuration values.
+ *
+ * @see SettlementConfig
+ *
+ * @example
+ * ```typescript
+ * const wallet = await Wallet.create({
+ *   identity,
+ *   arkServerUrl: 'https://arkade.computer',
+ *   settlementConfig: DEFAULT_SETTLEMENT_CONFIG,
+ * })
+ * ```
  */
 export declare const DEFAULT_SETTLEMENT_CONFIG: Required<SettlementConfig>;
 /**
- * Check if a VTXO is expiring soon based on threshold
+ * Check if a virtual output is expiring soon based on threshold
  *
- * @param vtxo - The virtual coin to check
+ * @param vtxo - The virtual output to check
  * @param thresholdMs - Threshold in milliseconds from now
- * @returns true if VTXO expires within threshold, false otherwise
+ * @returns true if virtual output expires within threshold, false otherwise
  */
 export declare function isVtxoExpiringSoon(vtxo: ExtendedVirtualCoin, thresholdMs: number): boolean;
 /**
- * Filter VTXOs that are expiring soon or are recoverable/subdust
+ * Filter virtual outputs that are expiring soon or are recoverable/subdust
  *
- * @param vtxos - Array of virtual coins to check
+ * @param vtxos - Array of virtual outputs to check
  * @param thresholdMs - Threshold in milliseconds from now
  * @param dustAmount - Dust threshold amount in satoshis
- * @returns Array of VTXOs expiring within threshold
+ * @returns Array of virtual outputs expiring within threshold
  */
 export declare function getExpiringAndRecoverableVtxos(vtxos: ExtendedVirtualCoin[], thresholdMs: number, dustAmount: bigint): ExtendedVirtualCoin[];
 /**
- * VtxoManager is a unified class for managing VTXO lifecycle operations including
- * recovery of swept/expired VTXOs and renewal to prevent expiration.
+ * VtxoManager is a unified class for managing virtual output lifecycle operations including
+ * recovery of swept/expired virtual outputs and renewal to prevent expiration.
  *
  * Key Features:
- * - **Recovery**: Reclaim swept or expired VTXOs back to the wallet
- * - **Renewal**: Refresh VTXO expiration time before they expire
- * - **Smart subdust handling**: Automatically includes subdust VTXOs when economically viable
- * - **Expiry monitoring**: Check for VTXOs that are expiring soon
+ * - **Recovery**: Reclaim swept or expired virtual outputs back to the wallet
+ * - **Renewal**: Refresh virtual output expiration time before they expire
+ * - **Smart subdust handling**: Automatically includes subdust virtual outputs when economically viable
+ * - **Expiry monitoring**: Check for virtual outputs that are expiring soon
  *
- * VTXOs become recoverable when:
- * - The Ark server sweeps them (virtualStatus.state === "swept") and they remain spendable
- * - They are preconfirmed subdust (to consolidate small amounts without locking liquidity on settled VTXOs)
+ * Virtual outputs become recoverable when:
+ * - The Arkade server sweeps them (virtualStatus.state === "swept") and they remain spendable
+ * - They are preconfirmed subdust (to consolidate small amounts without locking liquidity on settled virtual outputs)
  *
  * @example
  * ```typescript
- * // Initialize with renewal config
- * const manager = new VtxoManager(wallet, {
- *   enabled: true,
- *   thresholdMs: 86400000
+ * const wallet = await Wallet.create({
+ *   identity,
+ *   arkServerUrl: 'https://arkade.computer',
+ *   settlementConfig: {
+ *      // Seconds before virtual output expiry to trigger renewal
+ *      vtxoThreshold: 259_200, // 3 days
+ *      // Whether to sweep expired boarding inputs back to a fresh boarding address
+ *      boardingUtxoSweep: true,
+ *      // Polling interval in milliseconds for checking boarding inputs
+ *      pollIntervalMs: 60_000 // 1 minute
+ *  },
  * });
+ * const manager = await wallet.getVtxoManager();
  *
  * // Check recoverable balance
  * const balance = await manager.getRecoverableBalance();
@@ -137,10 +178,10 @@ export declare function getExpiringAndRecoverableVtxos(vtxos: ExtendedVirtualCoi
  *   const txid = await manager.recoverVtxos();
  * }
  *
- * // Check for expiring VTXOs
+ * // Check for expiring virtual outputs
  * const expiring = await manager.getExpiringVtxos();
  * if (expiring.length > 0) {
- *   console.log(`${expiring.length} VTXOs expiring soon`);
+ *   console.log(`${expiring.length} virtual outputs expiring soon`);
  *   const txid = await manager.renewVtxos();
  * }
  * ```
@@ -183,24 +224,24 @@ export declare class VtxoManager implements AsyncDisposable, IVtxoManager {
     /** @deprecated Use settlementConfig instead */
     renewalConfig?: RenewalConfig | undefined, settlementConfig?: SettlementConfig | false);
     /**
-     * Recover swept/expired VTXOs by settling them back to the wallet's Ark address.
+     * Recover swept/expired virtual outputs by settling them back to the wallet's Arkade address.
      *
      * This method:
-     * 1. Fetches all VTXOs (including recoverable ones)
-     * 2. Filters for swept but still spendable VTXOs and preconfirmed subdust
-     * 3. Includes subdust VTXOs if the total value >= dust threshold
-     * 4. Settles everything back to the wallet's Ark address
+     * 1. Fetches all virtual outputs (including recoverable ones)
+     * 2. Filters for swept but still spendable virtual outputs and preconfirmed subdust
+     * 3. Includes subdust virtual outputs if the total value >= dust threshold
+     * 4. Settles everything back to the wallet's Arkade address
      *
-     * Note: Settled VTXOs with long expiry are NOT recovered to avoid locking liquidity unnecessarily.
+     * Note: Settled virtual outputs with long expiry are NOT recovered to avoid locking liquidity unnecessarily.
      * Only preconfirmed subdust is recovered to consolidate small amounts.
      *
      * @param eventCallback - Optional callback to receive settlement events
      * @returns Settlement transaction ID
-     * @throws Error if no recoverable VTXOs found
+     * @throws Error if no recoverable virtual outputs found
      *
      * @example
      * ```typescript
-     * const manager = new VtxoManager(wallet);
+     * const manager = await wallet.getVtxoManager();
      *
      * // Simple recovery
      * const txid = await manager.recoverVtxos();
@@ -221,13 +262,13 @@ export declare class VtxoManager implements AsyncDisposable, IVtxoManager {
      *
      * @example
      * ```typescript
-     * const manager = new VtxoManager(wallet);
+     * const manager = await wallet.getVtxoManager();
      * const balance = await manager.getRecoverableBalance();
      *
      * if (balance.recoverable > 0n) {
      *   console.log(`You can recover ${balance.recoverable} sats`);
      *   if (balance.includesSubdust) {
-     *     console.log(`This includes ${balance.subdust} sats from subdust VTXOs`);
+     *     console.log(`This includes ${balance.subdust} sats from subdust virtual outputs`);
      *   }
      * }
      * ```
@@ -239,36 +280,43 @@ export declare class VtxoManager implements AsyncDisposable, IVtxoManager {
         vtxoCount: number;
     }>;
     /**
-     * Get VTXOs that are expiring soon based on renewal configuration
+     * Get virtual outputs that are expiring soon based on renewal configuration
      *
      * @param thresholdMs - Optional override for threshold in milliseconds
-     * @returns Array of expiring VTXOs, empty array if renewal is disabled or no VTXOs expiring
+     * @returns Array of expiring virtual outputs, empty array if renewal is disabled or no virtual outputs expiring
      *
      * @example
      * ```typescript
-     * const manager = new VtxoManager(wallet, { enabled: true, thresholdMs: 86400000 });
+     * const wallet = await Wallet.create({
+     *  identity,
+     *  arkServerUrl: 'https://arkade.computer',
+     *  settlementConfig: {
+     *      vtxoThreshold: 86_400 // 24 hours
+     *  },
+     * });
+     * const manager = await wallet.getVtxoManager();
      * const expiringVtxos = await manager.getExpiringVtxos();
      * if (expiringVtxos.length > 0) {
-     *   console.log(`${expiringVtxos.length} VTXOs expiring soon`);
+     *   console.log(`${expiringVtxos.length} virtual outputs expiring soon`);
      * }
      * ```
      */
     getExpiringVtxos(thresholdMs?: number): Promise<ExtendedVirtualCoin[]>;
     /**
-     * Renew expiring VTXOs by settling them back to the wallet's address
+     * Renew expiring virtual outputs by settling them back to the wallet's address
      *
-     * This method collects all expiring spendable VTXOs (including recoverable ones) and settles
+     * This method collects all expiring spendable virtual outputs (including recoverable ones) and settles
      * them back to the wallet, effectively refreshing their expiration time. This is the
-     * primary way to prevent VTXOs from expiring.
+     * primary way to prevent virtual outputs from expiring.
      *
      * @param eventCallback - Optional callback for settlement events
      * @returns Settlement transaction ID
-     * @throws Error if no VTXOs available to renew
+     * @throws Error if no virtual outputs available to renew
      * @throws Error if total amount is below dust threshold
      *
      * @example
      * ```typescript
-     * const manager = new VtxoManager(wallet);
+     * const manager = await wallet.getVtxoManager();
      *
      * // Simple renewal
      * const txid = await manager.renewVtxos();
@@ -281,49 +329,54 @@ export declare class VtxoManager implements AsyncDisposable, IVtxoManager {
      */
     renewVtxos(eventCallback?: (event: SettlementEvent) => void): Promise<string>;
     /**
-     * Get boarding UTXOs whose timelock has expired.
+     * Get boarding inputs whose timelock has expired.
      *
-     * These UTXOs can no longer be onboarded cooperatively via `settle()` and
+     * These inputs can no longer be onboarded cooperatively via `settle()` and
      * must be swept back to a fresh boarding address using the unilateral exit path.
      *
-     * @returns Array of expired boarding UTXOs
+     * @returns Array of expired boarding inputs
      *
      * @example
      * ```typescript
-     * const manager = new VtxoManager(wallet);
+     * const manager = await wallet.getVtxoManager();
      * const expired = await manager.getExpiredBoardingUtxos();
      * if (expired.length > 0) {
-     *   console.log(`${expired.length} expired boarding UTXOs to sweep`);
+     *   console.log(`${expired.length} expired boarding inputs to sweep`);
      * }
      * ```
      */
     getExpiredBoardingUtxos(prefetchedUtxos?: ExtendedCoin[]): Promise<ExtendedCoin[]>;
     /**
-     * Sweep expired boarding UTXOs back to a fresh boarding address via
-     * the unilateral exit path (on-chain self-spend).
+     * Sweep expired boarding inputs back to a fresh boarding address via
+     * the unilateral exit path (onchain self-spend).
      *
-     * This builds a raw on-chain transaction that:
-     * - Uses all expired boarding UTXOs as inputs (spent via the CSV exit script path)
+     * This builds a raw onchain transaction that:
+     * - Uses all expired boarding inputs as inputs (spent via the CSV exit script path)
      * - Has a single output to the wallet's boarding address (restarts the timelock)
-     * - Batches multiple expired UTXOs into one transaction
+     * - Batches multiple expired boarding inputs into one transaction
      * - Skips the sweep if the output after fees would be below dust
      *
-     * No Ark server involvement is needed — this is a pure on-chain transaction.
+     * No Arkade server involvement is needed — this is a pure onchain transaction.
      *
      * @returns The broadcast transaction ID
-     * @throws Error if no expired boarding UTXOs found
+     * @throws Error if no expired boarding inputs are found
      * @throws Error if output after fees is below dust (not economical to sweep)
-     * @throws Error if boarding UTXO sweep is not enabled in settlementConfig
+     * @throws Error if boarding input sweep is not enabled in settlementConfig
      *
      * @example
      * ```typescript
-     * const manager = new VtxoManager(wallet, undefined, {
-     *   boardingUtxoSweep: true,
+     * const wallet = await Wallet.create({
+     *   identity,
+     *   arkServerUrl: 'https://arkade.computer',
+     *   settlementConfig: {
+     *     boardingUtxoSweep: true,
+     *   },
      * });
+     * const manager = await wallet.getVtxoManager();
      *
      * try {
      *   const txid = await manager.sweepExpiredBoardingUtxos();
-     *   console.log('Swept expired boarding UTXOs:', txid);
+     *   console.log('Swept expired boarding inputs:', txid);
      * } catch (e) {
      *   console.log('No sweep needed or not economical');
      * }
@@ -338,7 +391,7 @@ export declare class VtxoManager implements AsyncDisposable, IVtxoManager {
     private getBoardingExitLeaf;
     /** Returns the pkScript (output script) of the boarding tapscript. */
     private getBoardingOutputScript;
-    /** Returns the on-chain provider for fee estimation and broadcasting. */
+    /** Returns the onchain provider for fee estimation and broadcasting. */
     private getOnchainProvider;
     /** Returns the Bitcoin network configuration from the wallet. */
     private getNetwork;
@@ -349,8 +402,8 @@ export declare class VtxoManager implements AsyncDisposable, IVtxoManager {
     private getNextPollDelay;
     /**
      * Starts a polling loop that:
-     * 1. Auto-settles new boarding UTXOs into Ark
-     * 2. Sweeps expired boarding UTXOs (when boardingUtxoSweep is enabled)
+     * 1. Auto-settles new boarding inputs into Arkade
+     * 2. Sweeps expired boarding inputs (when boardingUtxoSweep is enabled)
      *
      * Uses setTimeout chaining (not setInterval) so a slow/blocked poll
      * cannot stack up and the next delay can incorporate backoff.
@@ -359,7 +412,7 @@ export declare class VtxoManager implements AsyncDisposable, IVtxoManager {
     private schedulePoll;
     private pollBoardingUtxos;
     /**
-     * Auto-settle new (unexpired) boarding UTXOs into the Ark.
+     * Auto-settle new (unexpired) boarding inputs into Arkade.
      * Skips UTXOs that are already expired (those are handled by sweep).
      * Only settles UTXOs not already in-flight (tracked in knownBoardingUtxos).
      * UTXOs are marked as known only after a successful settle, so failed