@arkade-os/sdk 0.3.1-alpha.5 → 0.3.1-alpha.7

package/README.md

@@ -127,7 +127,8 @@ const manager = new VtxoManager(wallet, {
 
 #### Renewal: Prevent Expiration
 
-Renew VTXOs before they expire to keep your liquidity accessible. This settles all VTXOs (including recoverable ones) back to your wallet with a fresh expiration time.
+Renew VTXOs before they expire to retain unilateral control of funds.
+This settles expiring and recoverable VTXOs back to your wallet, refreshing their expiration time.
 
 ```typescript
 // Renew all VTXOs to prevent expiration

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

@@ -2,10 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VtxoManager = exports.DEFAULT_RENEWAL_CONFIG = void 0;
 exports.isVtxoExpiringSoon = isVtxoExpiringSoon;
-exports.getExpiringVtxos = getExpiringVtxos;
-exports.calculateExpiryThreshold = calculateExpiryThreshold;
-exports.getMinimumExpiry = getMinimumExpiry;
-exports.calculateDynamicThreshold = calculateDynamicThreshold;
+exports.getExpiringAndRecoverableVtxos = getExpiringAndRecoverableVtxos;
 const _1 = require(".");
 /**
  * Default renewal configuration values
@@ -13,6 +10,9 @@ const _1 = require(".");
 exports.DEFAULT_RENEWAL_CONFIG = {
     thresholdPercentage: 10,
 };
+function getDustAmount(wallet) {
+    return "dustAmount" in wallet ? wallet.dustAmount : 330n;
+}
 /**
  * Filter VTXOs that are recoverable (swept and still spendable, or preconfirmed subdust)
  *
@@ -82,80 +82,35 @@ function getRecoverableWithSubdust(vtxos, dustAmount) {
  * @param thresholdMs - Threshold in milliseconds from now
  * @returns true if VTXO expires within threshold, false otherwise
  */
-function isVtxoExpiringSoon(vtxo, thresholdMs) {
+function isVtxoExpiringSoon(vtxo, percentage) {
     const { batchExpiry } = vtxo.virtualStatus;
-    // No expiry set means it doesn't expire
     if (!batchExpiry) {
-        return false;
+        return false; // it doesn't expire
     }
     const now = Date.now();
-    const timeUntilExpiry = batchExpiry - now;
-    return timeUntilExpiry > 0 && timeUntilExpiry <= thresholdMs;
+    if (batchExpiry <= now) {
+        return false; // already expired
+    }
+    // It shouldn't happen, but let's be safe
+    if (!vtxo.createdAt) {
+        return false;
+    }
+    const duration = batchExpiry - vtxo.createdAt.getTime();
+    const softExpiry = batchExpiry - (duration * percentage) / 100;
+    return softExpiry > 0 && softExpiry <= now;
 }
 /**
- * Filter VTXOs that are expiring soon
+ * Filter VTXOs that are expiring soon or are recoverable/subdust
  *
  * @param vtxos - Array of virtual coins to check
  * @param thresholdMs - Threshold in milliseconds from now
+ * @param dustAmount - Dust threshold amount in satoshis
  * @returns Array of VTXOs expiring within threshold
  */
-function getExpiringVtxos(vtxos, thresholdMs) {
-    return vtxos.filter((vtxo) => isVtxoExpiringSoon(vtxo, thresholdMs));
-}
-/**
- * Calculate expiry threshold in milliseconds based on batch expiry and percentage
- *
- * @param batchExpiry - Batch expiry timestamp in milliseconds
- * @param percentage - Percentage of total time (0-100)
- * @returns Threshold timestamp in milliseconds from now
- *
- * @example
- * // VTXO expires in 10 days, threshold is 10%
- * const expiry = Date.now() + 10 * 24 * 60 * 60 * 1000;
- * const threshold = calculateExpiryThreshold(expiry, 10);
- * // Returns 1 day in milliseconds (10% of 10 days)
- */
-function calculateExpiryThreshold(batchExpiry, percentage) {
-    if (percentage < 0 || percentage > 100) {
-        throw new Error("Percentage must be between 0 and 100");
-    }
-    const now = Date.now();
-    const totalTime = batchExpiry - now;
-    if (totalTime <= 0) {
-        // Already expired
-        return 0;
-    }
-    // Calculate threshold as percentage of total time
-    return Math.floor((totalTime * percentage) / 100);
-}
-/**
- * Get the minimum expiry time from a list of VTXOs
- *
- * @param vtxos - Array of virtual coins
- * @returns Minimum batch expiry timestamp, or undefined if no VTXOs have expiry
- */
-function getMinimumExpiry(vtxos) {
-    const expiries = vtxos
-        .map((v) => v.virtualStatus.batchExpiry)
-        .filter((e) => e !== undefined);
-    if (expiries.length === 0) {
-        return undefined;
-    }
-    return Math.min(...expiries);
-}
-/**
- * Calculate dynamic threshold based on the earliest expiring VTXO
- *
- * @param vtxos - Array of virtual coins
- * @param percentage - Percentage of time until expiry (0-100)
- * @returns Threshold in milliseconds, or undefined if no VTXOs have expiry
- */
-function calculateDynamicThreshold(vtxos, percentage) {
-    const minExpiry = getMinimumExpiry(vtxos);
-    if (!minExpiry) {
-        return undefined;
-    }
-    return calculateExpiryThreshold(minExpiry, percentage);
+function getExpiringAndRecoverableVtxos(vtxos, percentage, dustAmount) {
+    return vtxos.filter((vtxo) => isVtxoExpiringSoon(vtxo, percentage) ||
+        (0, _1.isRecoverable)(vtxo) ||
+        (0, _1.isSubdust)(vtxo, dustAmount));
 }
 /**
  * VtxoManager is a unified class for managing VTXO lifecycle operations including
@@ -236,9 +191,7 @@ class VtxoManager {
             withUnrolled: false,
         });
         // Get dust amount from wallet
-        const dustAmount = "dustAmount" in this.wallet
-            ? this.wallet.dustAmount
-            : 1000n;
+        const dustAmount = getDustAmount(this.wallet);
         // Filter recoverable VTXOs and handle subdust logic
         const { vtxosToRecover, includesSubdust, totalAmount } = getRecoverableWithSubdust(allVtxos, dustAmount);
         if (vtxosToRecover.length === 0) {
@@ -281,9 +234,7 @@ class VtxoManager {
             withRecoverable: true,
             withUnrolled: false,
         });
-        const dustAmount = "dustAmount" in this.wallet
-            ? this.wallet.dustAmount
-            : 1000n;
+        const dustAmount = getDustAmount(this.wallet);
         const { vtxosToRecover, includesSubdust, totalAmount } = getRecoverableWithSubdust(allVtxos, dustAmount);
         // Calculate subdust amount separately for reporting
         const subdustAmount = vtxosToRecover
@@ -313,23 +264,16 @@ class VtxoManager {
      * ```
      */
     async getExpiringVtxos(thresholdPercentage) {
-        if (!this.renewalConfig?.enabled) {
-            return [];
-        }
-        const vtxos = await this.wallet.getVtxos();
+        const vtxos = await this.wallet.getVtxos({ withRecoverable: true });
         const percentage = thresholdPercentage ??
-            this.renewalConfig.thresholdPercentage ??
+            this.renewalConfig?.thresholdPercentage ??
             exports.DEFAULT_RENEWAL_CONFIG.thresholdPercentage;
-        const threshold = calculateDynamicThreshold(vtxos, percentage);
-        if (!threshold) {
-            return [];
-        }
-        return getExpiringVtxos(vtxos, threshold);
+        return getExpiringAndRecoverableVtxos(vtxos, percentage, getDustAmount(this.wallet));
     }
     /**
-     * Renew VTXOs by settling them back to the wallet's address
+     * Renew expiring VTXOs by settling them back to the wallet's address
      *
-     * This method collects all spendable VTXOs (including recoverable ones) and settles
+     * This method collects all expiring spendable VTXOs (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.
      *
@@ -353,15 +297,13 @@ class VtxoManager {
      */
     async renewVtxos(eventCallback) {
         // Get all VTXOs (including recoverable ones)
-        const vtxos = await this.wallet.getVtxos({ withRecoverable: true });
+        const vtxos = await this.getExpiringVtxos();
         if (vtxos.length === 0) {
             throw new Error("No VTXOs available to renew");
         }
         const totalAmount = vtxos.reduce((sum, vtxo) => sum + vtxo.value, 0);
         // Get dust amount from wallet
-        const dustAmount = "dustAmount" in this.wallet
-            ? this.wallet.dustAmount
-            : 1000n;
+        const dustAmount = getDustAmount(this.wallet);
         // Check if total amount is above dust threshold
         if (BigInt(totalAmount) < dustAmount) {
             throw new Error(`Total amount ${totalAmount} is below dust threshold ${dustAmount}`);

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

@@ -5,6 +5,9 @@ import { isRecoverable, isSubdust } from './index.js';
 export const DEFAULT_RENEWAL_CONFIG = {
     thresholdPercentage: 10,
 };
+function getDustAmount(wallet) {
+    return "dustAmount" in wallet ? wallet.dustAmount : 330n;
+}
 /**
  * Filter VTXOs that are recoverable (swept and still spendable, or preconfirmed subdust)
  *
@@ -74,80 +77,35 @@ function getRecoverableWithSubdust(vtxos, dustAmount) {
  * @param thresholdMs - Threshold in milliseconds from now
  * @returns true if VTXO expires within threshold, false otherwise
  */
-export function isVtxoExpiringSoon(vtxo, thresholdMs) {
+export function isVtxoExpiringSoon(vtxo, percentage) {
     const { batchExpiry } = vtxo.virtualStatus;
-    // No expiry set means it doesn't expire
     if (!batchExpiry) {
-        return false;
+        return false; // it doesn't expire
     }
     const now = Date.now();
-    const timeUntilExpiry = batchExpiry - now;
-    return timeUntilExpiry > 0 && timeUntilExpiry <= thresholdMs;
+    if (batchExpiry <= now) {
+        return false; // already expired
+    }
+    // It shouldn't happen, but let's be safe
+    if (!vtxo.createdAt) {
+        return false;
+    }
+    const duration = batchExpiry - vtxo.createdAt.getTime();
+    const softExpiry = batchExpiry - (duration * percentage) / 100;
+    return softExpiry > 0 && softExpiry <= now;
 }
 /**
- * Filter VTXOs that are expiring soon
+ * Filter VTXOs that are expiring soon or are recoverable/subdust
  *
  * @param vtxos - Array of virtual coins to check
  * @param thresholdMs - Threshold in milliseconds from now
+ * @param dustAmount - Dust threshold amount in satoshis
  * @returns Array of VTXOs expiring within threshold
  */
-export function getExpiringVtxos(vtxos, thresholdMs) {
-    return vtxos.filter((vtxo) => isVtxoExpiringSoon(vtxo, thresholdMs));
-}
-/**
- * Calculate expiry threshold in milliseconds based on batch expiry and percentage
- *
- * @param batchExpiry - Batch expiry timestamp in milliseconds
- * @param percentage - Percentage of total time (0-100)
- * @returns Threshold timestamp in milliseconds from now
- *
- * @example
- * // VTXO expires in 10 days, threshold is 10%
- * const expiry = Date.now() + 10 * 24 * 60 * 60 * 1000;
- * const threshold = calculateExpiryThreshold(expiry, 10);
- * // Returns 1 day in milliseconds (10% of 10 days)
- */
-export function calculateExpiryThreshold(batchExpiry, percentage) {
-    if (percentage < 0 || percentage > 100) {
-        throw new Error("Percentage must be between 0 and 100");
-    }
-    const now = Date.now();
-    const totalTime = batchExpiry - now;
-    if (totalTime <= 0) {
-        // Already expired
-        return 0;
-    }
-    // Calculate threshold as percentage of total time
-    return Math.floor((totalTime * percentage) / 100);
-}
-/**
- * Get the minimum expiry time from a list of VTXOs
- *
- * @param vtxos - Array of virtual coins
- * @returns Minimum batch expiry timestamp, or undefined if no VTXOs have expiry
- */
-export function getMinimumExpiry(vtxos) {
-    const expiries = vtxos
-        .map((v) => v.virtualStatus.batchExpiry)
-        .filter((e) => e !== undefined);
-    if (expiries.length === 0) {
-        return undefined;
-    }
-    return Math.min(...expiries);
-}
-/**
- * Calculate dynamic threshold based on the earliest expiring VTXO
- *
- * @param vtxos - Array of virtual coins
- * @param percentage - Percentage of time until expiry (0-100)
- * @returns Threshold in milliseconds, or undefined if no VTXOs have expiry
- */
-export function calculateDynamicThreshold(vtxos, percentage) {
-    const minExpiry = getMinimumExpiry(vtxos);
-    if (!minExpiry) {
-        return undefined;
-    }
-    return calculateExpiryThreshold(minExpiry, percentage);
+export function getExpiringAndRecoverableVtxos(vtxos, percentage, dustAmount) {
+    return vtxos.filter((vtxo) => isVtxoExpiringSoon(vtxo, percentage) ||
+        isRecoverable(vtxo) ||
+        isSubdust(vtxo, dustAmount));
 }
 /**
  * VtxoManager is a unified class for managing VTXO lifecycle operations including
@@ -228,9 +186,7 @@ export class VtxoManager {
             withUnrolled: false,
         });
         // Get dust amount from wallet
-        const dustAmount = "dustAmount" in this.wallet
-            ? this.wallet.dustAmount
-            : 1000n;
+        const dustAmount = getDustAmount(this.wallet);
         // Filter recoverable VTXOs and handle subdust logic
         const { vtxosToRecover, includesSubdust, totalAmount } = getRecoverableWithSubdust(allVtxos, dustAmount);
         if (vtxosToRecover.length === 0) {
@@ -273,9 +229,7 @@ export class VtxoManager {
             withRecoverable: true,
             withUnrolled: false,
         });
-        const dustAmount = "dustAmount" in this.wallet
-            ? this.wallet.dustAmount
-            : 1000n;
+        const dustAmount = getDustAmount(this.wallet);
         const { vtxosToRecover, includesSubdust, totalAmount } = getRecoverableWithSubdust(allVtxos, dustAmount);
         // Calculate subdust amount separately for reporting
         const subdustAmount = vtxosToRecover
@@ -305,23 +259,16 @@ export class VtxoManager {
      * ```
      */
     async getExpiringVtxos(thresholdPercentage) {
-        if (!this.renewalConfig?.enabled) {
-            return [];
-        }
-        const vtxos = await this.wallet.getVtxos();
+        const vtxos = await this.wallet.getVtxos({ withRecoverable: true });
         const percentage = thresholdPercentage ??
-            this.renewalConfig.thresholdPercentage ??
+            this.renewalConfig?.thresholdPercentage ??
             DEFAULT_RENEWAL_CONFIG.thresholdPercentage;
-        const threshold = calculateDynamicThreshold(vtxos, percentage);
-        if (!threshold) {
-            return [];
-        }
-        return getExpiringVtxos(vtxos, threshold);
+        return getExpiringAndRecoverableVtxos(vtxos, percentage, getDustAmount(this.wallet));
     }
     /**
-     * Renew VTXOs by settling them back to the wallet's address
+     * Renew expiring VTXOs by settling them back to the wallet's address
      *
-     * This method collects all spendable VTXOs (including recoverable ones) and settles
+     * This method collects all expiring spendable VTXOs (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.
      *
@@ -345,15 +292,13 @@ export class VtxoManager {
      */
     async renewVtxos(eventCallback) {
         // Get all VTXOs (including recoverable ones)
-        const vtxos = await this.wallet.getVtxos({ withRecoverable: true });
+        const vtxos = await this.getExpiringVtxos();
         if (vtxos.length === 0) {
             throw new Error("No VTXOs available to renew");
         }
         const totalAmount = vtxos.reduce((sum, vtxo) => sum + vtxo.value, 0);
         // Get dust amount from wallet
-        const dustAmount = "dustAmount" in this.wallet
-            ? this.wallet.dustAmount
-            : 1000n;
+        const dustAmount = getDustAmount(this.wallet);
         // Check if total amount is above dust threshold
         if (BigInt(totalAmount) < dustAmount) {
             throw new Error(`Total amount ${totalAmount} is below dust threshold ${dustAmount}`);

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

@@ -8,7 +8,7 @@ export interface RenewalConfig {
      * Enable automatic renewal monitoring
      * @default false
      */
-    enabled: boolean;
+    enabled?: boolean;
     /**
      * Percentage of expiry time to use as threshold (0-100)
      * E.g., 10 means renew when 10% of time until expiry remains
@@ -27,44 +27,16 @@ export declare const DEFAULT_RENEWAL_CONFIG: Required<Omit<RenewalConfig, "enabl
  * @param thresholdMs - Threshold in milliseconds from now
  * @returns true if VTXO expires within threshold, false otherwise
  */
-export declare function isVtxoExpiringSoon(vtxo: ExtendedVirtualCoin, thresholdMs: number): boolean;
+export declare function isVtxoExpiringSoon(vtxo: ExtendedVirtualCoin, percentage: number): boolean;
 /**
- * Filter VTXOs that are expiring soon
+ * Filter VTXOs that are expiring soon or are recoverable/subdust
  *
  * @param vtxos - Array of virtual coins to check
  * @param thresholdMs - Threshold in milliseconds from now
+ * @param dustAmount - Dust threshold amount in satoshis
  * @returns Array of VTXOs expiring within threshold
  */
-export declare function getExpiringVtxos(vtxos: ExtendedVirtualCoin[], thresholdMs: number): ExtendedVirtualCoin[];
-/**
- * Calculate expiry threshold in milliseconds based on batch expiry and percentage
- *
- * @param batchExpiry - Batch expiry timestamp in milliseconds
- * @param percentage - Percentage of total time (0-100)
- * @returns Threshold timestamp in milliseconds from now
- *
- * @example
- * // VTXO expires in 10 days, threshold is 10%
- * const expiry = Date.now() + 10 * 24 * 60 * 60 * 1000;
- * const threshold = calculateExpiryThreshold(expiry, 10);
- * // Returns 1 day in milliseconds (10% of 10 days)
- */
-export declare function calculateExpiryThreshold(batchExpiry: number, percentage: number): number;
-/**
- * Get the minimum expiry time from a list of VTXOs
- *
- * @param vtxos - Array of virtual coins
- * @returns Minimum batch expiry timestamp, or undefined if no VTXOs have expiry
- */
-export declare function getMinimumExpiry(vtxos: ExtendedVirtualCoin[]): number | undefined;
-/**
- * Calculate dynamic threshold based on the earliest expiring VTXO
- *
- * @param vtxos - Array of virtual coins
- * @param percentage - Percentage of time until expiry (0-100)
- * @returns Threshold in milliseconds, or undefined if no VTXOs have expiry
- */
-export declare function calculateDynamicThreshold(vtxos: ExtendedVirtualCoin[], percentage: number): number | undefined;
+export declare function getExpiringAndRecoverableVtxos(vtxos: ExtendedVirtualCoin[], percentage: 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.
@@ -179,9 +151,9 @@ export declare class VtxoManager {
      */
     getExpiringVtxos(thresholdPercentage?: number): Promise<ExtendedVirtualCoin[]>;
     /**
-     * Renew VTXOs by settling them back to the wallet's address
+     * Renew expiring VTXOs by settling them back to the wallet's address
      *
-     * This method collects all spendable VTXOs (including recoverable ones) and settles
+     * This method collects all expiring spendable VTXOs (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.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkade-os/sdk",
-  "version": "0.3.1-alpha.5",
+  "version": "0.3.1-alpha.7",
   "description": "Bitcoin wallet SDK with Taproot and Ark integration",
   "type": "module",
   "main": "./dist/cjs/index.js",