@arkade-os/sdk 0.4.15 → 0.4.16

package/dist/esm/wallet/vtxo-manager.js

@@ -5,29 +5,57 @@ import { hex } from "@scure/base";
 import { getSequence } from '../script/base.js';
 import { Transaction } from '../utils/transaction.js';
 import { TxWeightEstimator } from '../utils/txSizeEstimator.js';
-/** Type guard to check if a wallet has the properties needed for sweep operations. */
+/**
+ * Return whether a wallet exposes the properties required for boarding input sweep operations.
+ *
+ * @param wallet - Wallet to inspect
+ * @returns `true` when the wallet supports boarding input sweep operations.
+ */
 function isSweepCapable(wallet) {
     return ("boardingTapscript" in wallet &&
         "onchainProvider" in wallet &&
         "network" in wallet);
 }
-/** Asserts that the wallet supports sweep operations, throwing a clear error if not. */
+/**
+ * Assert that the wallet supports boarding input sweep operations.
+ *
+ * @param wallet - Wallet to inspect
+ * @throws Error if the wallet does not support boarding input sweep operations.
+ */
 function assertSweepCapable(wallet) {
     if (!isSweepCapable(wallet)) {
         throw new Error("Boarding UTXO sweep requires a Wallet instance with boardingTapscript, onchainProvider, and network");
     }
 }
-export const DEFAULT_THRESHOLD_MS = 3 * 24 * 60 * 60 * 1000; // 3 days
-export const DEFAULT_THRESHOLD_SECONDS = 3 * 24 * 60 * 60; // 3 days
+/** Default renewal threshold in seconds (3 days). */
+export const DEFAULT_THRESHOLD_SECONDS = 3 * 24 * 60 * 60;
 /**
- * Default renewal configuration values
- * @deprecated Use DEFAULT_SETTLEMENT_CONFIG instead
+ * Default renewal threshold in milliseconds (3 days).
+ */
+export const DEFAULT_THRESHOLD_MS = DEFAULT_THRESHOLD_SECONDS * 1000;
+/**
+ * Default renewal configuration values.
+ *
+ * @see RenewalConfig
+ * @deprecated Leave `renewalConfig` undefined and use `settlementConfig` instead.
+ * @see SettlementConfig
  */
 export const DEFAULT_RENEWAL_CONFIG = {
     thresholdMs: DEFAULT_THRESHOLD_MS, // 3 days
 };
 /**
- * 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 const DEFAULT_SETTLEMENT_CONFIG = {
     vtxoThreshold: DEFAULT_THRESHOLD_SECONDS,
@@ -39,23 +67,23 @@ function getDustAmount(wallet) {
     return "dustAmount" in wallet ? wallet.dustAmount : 330n;
 }
 /**
- * Filter VTXOs that are recoverable (swept and still spendable, or preconfirmed subdust)
+ * Filter virtual outputs that are recoverable (swept and still spendable, or preconfirmed subdust)
  *
  * Recovery strategy:
- * - Always recover swept VTXOs (they've been taken by the server)
- * - Only recover subdust preconfirmed VTXOs (to avoid locking liquidity on settled VTXOs with long expiry)
+ * - Always recover swept virtual outputs (they've been taken by the server)
+ * - Only recover subdust preconfirmed virtual outputs (to avoid locking liquidity on settled virtual outputs with long expiry)
  *
- * @param vtxos - Array of virtual coins to check
+ * @param vtxos - Array of virtual outputs to check
  * @param dustAmount - Dust threshold to identify subdust
- * @returns Array of recoverable VTXOs
+ * @returns Array of recoverable virtual outputs
  */
 function getRecoverableVtxos(vtxos, dustAmount) {
     return vtxos.filter((vtxo) => {
-        // Always recover swept VTXOs
+        // Always recover swept virtual outputs
         if (isRecoverable(vtxo)) {
             return true;
         }
-        // also include vtxos that are not swept but expired
+        // also include virtual outputs that are not swept but expired
         if (isSpendable(vtxo) && isExpired(vtxo)) {
             return true;
         }
@@ -68,14 +96,14 @@ function getRecoverableVtxos(vtxos, dustAmount) {
     });
 }
 /**
- * Get recoverable VTXOs including subdust coins if the total value exceeds dust threshold.
+ * Get recoverable virtual outputs including subdust outputs if the total value exceeds dust threshold.
  *
- * Decision is based on the combined total of ALL recoverable VTXOs (regular + subdust),
+ * Decision is based on the combined total of ALL recoverable virtual outputs (regular + subdust),
  * not just the subdust portion alone.
  *
- * @param vtxos - Array of virtual coins to check
+ * @param vtxos - Array of virtual outputs to check
  * @param dustAmount - Dust threshold amount in satoshis
- * @returns Object containing recoverable VTXOs and whether subdust should be included
+ * @returns Object containing recoverable virtual outputs and whether subdust should be included
  */
 function getRecoverableWithSubdust(vtxos, dustAmount) {
     const recoverableVtxos = getRecoverableVtxos(vtxos, dustAmount);
@@ -105,11 +133,11 @@ function getRecoverableWithSubdust(vtxos, dustAmount) {
     };
 }
 /**
- * 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 function isVtxoExpiringSoon(vtxo, thresholdMs // in milliseconds
 ) {
@@ -130,12 +158,12 @@ export function isVtxoExpiringSoon(vtxo, thresholdMs // in milliseconds
     return batchExpiry - now <= realThresholdMs;
 }
 /**
- * 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 function getExpiringAndRecoverableVtxos(vtxos, thresholdMs, dustAmount) {
     return vtxos.filter((vtxo) => isVtxoExpiringSoon(vtxo, thresholdMs) ||
@@ -185,24 +213,24 @@ export class VtxoManager {
     }
     // ========== Recovery Methods ==========
     /**
-     * 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();
@@ -214,20 +242,20 @@ export class VtxoManager {
      * ```
      */
     async recoverVtxos(eventCallback) {
-        // Get all VTXOs including recoverable ones
+        // Get all virtual outputs including recoverable ones
         const allVtxos = await this.wallet.getVtxos({
             withRecoverable: true,
             withUnrolled: false,
         });
         // Get dust amount from wallet
         const dustAmount = getDustAmount(this.wallet);
-        // Filter recoverable VTXOs and handle subdust logic
+        // Filter recoverable virtual outputs and handle subdust logic
         const { vtxosToRecover, totalAmount } = getRecoverableWithSubdust(allVtxos, dustAmount);
         if (vtxosToRecover.length === 0) {
             throw new Error("No recoverable VTXOs found");
         }
         const arkAddress = await this.wallet.getAddress();
-        // Settle all recoverable VTXOs back to the wallet
+        // Settle all recoverable virtual outputs back to the wallet
         return this.wallet.settle({
             inputs: vtxosToRecover,
             outputs: [
@@ -247,13 +275,13 @@ export class VtxoManager {
      *
      * @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`);
      *   }
      * }
      * ```
@@ -278,17 +306,24 @@ export class VtxoManager {
     }
     // ========== Renewal Methods ==========
     /**
-     * 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`);
      * }
      * ```
      */
@@ -316,20 +351,20 @@ export class VtxoManager {
         return getExpiringAndRecoverableVtxos(vtxos, threshold, getDustAmount(this.wallet));
     }
     /**
-     * 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();
@@ -346,7 +381,7 @@ export class VtxoManager {
         }
         this.renewalInProgress = true;
         try {
-            // Get all VTXOs (including recoverable ones)
+            // Get all virtual outputs (including recoverable ones)
             // Use default threshold to bypass settlementConfig gate (manual API should always work)
             const vtxos = await this.getExpiringVtxos(this.settlementConfig !== false &&
                 this.settlementConfig?.vtxoThreshold !== undefined
@@ -379,21 +414,21 @@ export class VtxoManager {
             this.renewalInProgress = false;
         }
     }
-    // ========== Boarding UTXO Sweep Methods ==========
+    // ========== Boarding Input Sweep Methods ==========
     /**
-     * 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`);
      * }
      * ```
      */
@@ -409,31 +444,36 @@ export class VtxoManager {
         return boardingUtxos.filter((utxo) => hasBoardingTxExpired(utxo, boardingTimelock, chainTipHeight));
     }
     /**
-     * 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');
      * }
@@ -447,7 +487,7 @@ export class VtxoManager {
             throw new Error("Boarding UTXO sweep is not enabled in settlementConfig");
         }
         const allExpired = await this.getExpiredBoardingUtxos(prefetchedUtxos);
-        // Filter out UTXOs already swept (tx broadcast but not yet confirmed)
+        // Filter out inputs already swept (tx broadcast but not yet confirmed).
         const expiredUtxos = allExpired.filter((u) => !this.sweptBoardingUtxos.has(`${u.txid}:${u.vout}`));
         if (expiredUtxos.length === 0) {
             throw new Error("No expired boarding UTXOs to sweep");
@@ -498,12 +538,12 @@ export class VtxoManager {
         signedTx.finalize();
         // Broadcast
         const txid = await this.getOnchainProvider().broadcastTransaction(signedTx.hex);
-        // Mark UTXOs as swept to prevent duplicate broadcasts on next poll
+        // Mark boarding inputs as swept to prevent duplicate broadcasts on next poll
         for (const u of expiredUtxos) {
             this.sweptBoardingUtxos.add(`${u.txid}:${u.vout}`);
         }
         // Mark the sweep output as "known" so the next poll doesn't try to
-        // auto-settle it back into Ark (it lands at the same boarding address).
+        // auto-settle it back into Arkade (it lands at the same boarding address).
         this.knownBoardingUtxos.add(`${txid}:0`);
         return txid;
     }
@@ -527,7 +567,7 @@ export class VtxoManager {
     getBoardingOutputScript() {
         return this.getSweepWallet().boardingTapscript.pkScript;
     }
-    /** Returns the on-chain provider for fee estimation and broadcasting. */
+    /** Returns the onchain provider for fee estimation and broadcasting. */
     getOnchainProvider() {
         return this.getSweepWallet().onchainProvider;
     }
@@ -543,7 +583,7 @@ export class VtxoManager {
         if (this.settlementConfig === false) {
             return undefined;
         }
-        // Start polling for boarding UTXOs independently of contract manager
+        // Start polling for boarding inputs independently of contract manager
         // SSE setup. Use a short delay to let the wallet finish construction.
         this.startupPollTimeoutId = setTimeout(() => {
             if (this.disposed)
@@ -567,18 +607,18 @@ export class VtxoManager {
                     this.renewVtxos().catch((e) => {
                         if (e instanceof Error) {
                             if (e.message.includes("No VTXOs available to renew")) {
-                                // Not an error, just no VTXO eligible for renewal.
+                                // Not an error, just no virtual outputs eligible for renewal.
                                 return;
                             }
                             if (e.message.includes("is below dust threshold")) {
                                 // Not an error, just below dust threshold.
-                                // As more VTXOs are received, the threshold will be raised.
+                                // As more virtual outputs are received, the threshold will be raised.
                                 return;
                             }
                             if (e.message.includes("VTXO_ALREADY_REGISTERED") ||
                                 e.message.includes("VTXO_ALREADY_SPENT") ||
                                 e.message.includes("duplicated input")) {
-                                // VTXO is already being used in a concurrent
+                                // Virtual output is already being used in a concurrent
                                 // user-initiated operation. Skip silently — the
                                 // wallet's tx lock serializes these, but the
                                 // renewal will retry on the next cycle.
@@ -614,8 +654,8 @@ export class VtxoManager {
     }
     /**
      * 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.
@@ -633,7 +673,7 @@ export class VtxoManager {
         this.pollTimeoutId = setTimeout(() => this.pollBoardingUtxos(), delay);
     }
     async pollBoardingUtxos() {
-        // Guard: wallet must support boarding UTXO + sweep operations
+        // Guard: wallet must support boarding input + sweep operations
         if (!isSweepCapable(this.wallet))
             return;
         // Skip if disposed or a previous poll is still running
@@ -648,11 +688,11 @@ export class VtxoManager {
         this.pollDone = { promise, resolve: resolve };
         let hadError = false;
         try {
-            // Fetch boarding UTXOs once for the entire poll cycle so that
+            // Fetch boarding inputs once for the entire poll cycle so that
             // settle and sweep don't each hit the network independently.
             const boardingUtxos = await this.wallet.getBoardingUtxos();
-            // Settle new (unexpired) UTXOs first, then sweep expired ones.
-            // Sequential to avoid racing for the same UTXOs.
+            // Settle new (unexpired) boarding inputs first, then sweep expired ones.
+            // Sequential to avoid racing for the same inputs.
             try {
                 await this.settleBoardingUtxos(boardingUtxos);
             }
@@ -694,16 +734,16 @@ export class VtxoManager {
         }
     }
     /**
-     * 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
      * attempts will be retried on the next poll.
      */
     async settleBoardingUtxos(boardingUtxos) {
-        // Exclude expired UTXOs — those should be swept, not settled.
+        // Exclude expired boarding inputs — those should be swept, not settled.
         // If we can't determine expired status, bail out entirely to avoid
-        // accidentally settling expired UTXOs (which would conflict with sweep).
+        // accidentally settling expired inputs (which would conflict with sweep).
         let expiredSet;
         try {
             const boardingTimelock = this.getBoardingTimelock();