@arkade-os/sdk 0.3.0-alpha.8 → 0.3.0

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

@@ -0,0 +1,179 @@
+import { ExtendedVirtualCoin, IWallet } from ".";
+import { SettlementEvent } from "../providers/ark";
+/**
+ * Configuration options for automatic VTXO renewal
+ */
+export interface RenewalConfig {
+    /**
+     * Enable automatic renewal monitoring
+     * @default false
+     */
+    enabled?: boolean;
+    /**
+     * Percentage of expiry time to use as threshold (0-100)
+     * E.g., 10 means renew when 10% of time until expiry remains
+     * @default 10
+     */
+    thresholdPercentage?: number;
+}
+/**
+ * Default renewal configuration values
+ */
+export declare const DEFAULT_RENEWAL_CONFIG: Required<Omit<RenewalConfig, "enabled">>;
+/**
+ * Check if a VTXO is expiring soon based on threshold
+ *
+ * @param vtxo - The virtual coin to check
+ * @param thresholdMs - Threshold in milliseconds from now
+ * @returns true if VTXO expires within threshold, false otherwise
+ */
+export declare function isVtxoExpiringSoon(vtxo: ExtendedVirtualCoin, percentage: number): boolean;
+/**
+ * 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 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.
+ *
+ * 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
+ *
+ * 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)
+ *
+ * @example
+ * ```typescript
+ * // Initialize with renewal config
+ * const manager = new VtxoManager(wallet, {
+ *   enabled: true,
+ *   thresholdPercentage: 10
+ * });
+ *
+ * // Check recoverable balance
+ * const balance = await manager.getRecoverableBalance();
+ * if (balance.recoverable > 0n) {
+ *   console.log(`Can recover ${balance.recoverable} sats`);
+ *   const txid = await manager.recoverVtxos();
+ * }
+ *
+ * // Check for expiring VTXOs
+ * const expiring = await manager.getExpiringVtxos();
+ * if (expiring.length > 0) {
+ *   console.log(`${expiring.length} VTXOs expiring soon`);
+ *   const txid = await manager.renewVtxos();
+ * }
+ * ```
+ */
+export declare class VtxoManager {
+    readonly wallet: IWallet;
+    readonly renewalConfig?: RenewalConfig | undefined;
+    constructor(wallet: IWallet, renewalConfig?: RenewalConfig | undefined);
+    /**
+     * Recover swept/expired VTXOs by settling them back to the wallet's Ark 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
+     *
+     * Note: Settled VTXOs 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
+     *
+     * @example
+     * ```typescript
+     * const manager = new VtxoManager(wallet);
+     *
+     * // Simple recovery
+     * const txid = await manager.recoverVtxos();
+     *
+     * // With event callback
+     * const txid = await manager.recoverVtxos((event) => {
+     *   console.log('Settlement event:', event.type);
+     * });
+     * ```
+     */
+    recoverVtxos(eventCallback?: (event: SettlementEvent) => void): Promise<string>;
+    /**
+     * Get information about recoverable balance without executing recovery.
+     *
+     * Useful for displaying to users before they decide to recover funds.
+     *
+     * @returns Object containing recoverable amounts and subdust information
+     *
+     * @example
+     * ```typescript
+     * const manager = new VtxoManager(wallet);
+     * 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`);
+     *   }
+     * }
+     * ```
+     */
+    getRecoverableBalance(): Promise<{
+        recoverable: bigint;
+        subdust: bigint;
+        includesSubdust: boolean;
+        vtxoCount: number;
+    }>;
+    /**
+     * Get VTXOs that are expiring soon based on renewal configuration
+     *
+     * @param thresholdPercentage - Optional override for threshold percentage (0-100)
+     * @returns Array of expiring VTXOs, empty array if renewal is disabled or no VTXOs expiring
+     *
+     * @example
+     * ```typescript
+     * const manager = new VtxoManager(wallet, { enabled: true, thresholdPercentage: 10 });
+     * const expiringVtxos = await manager.getExpiringVtxos();
+     * if (expiringVtxos.length > 0) {
+     *   console.log(`${expiringVtxos.length} VTXOs expiring soon`);
+     * }
+     * ```
+     */
+    getExpiringVtxos(thresholdPercentage?: number): Promise<ExtendedVirtualCoin[]>;
+    /**
+     * Renew expiring VTXOs by settling them back to the wallet's address
+     *
+     * 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.
+     *
+     * @param eventCallback - Optional callback for settlement events
+     * @returns Settlement transaction ID
+     * @throws Error if no VTXOs available to renew
+     * @throws Error if total amount is below dust threshold
+     *
+     * @example
+     * ```typescript
+     * const manager = new VtxoManager(wallet);
+     *
+     * // Simple renewal
+     * const txid = await manager.renewVtxos();
+     *
+     * // With event callback
+     * const txid = await manager.renewVtxos((event) => {
+     *   console.log('Settlement event:', event.type);
+     * });
+     * ```
+     */
+    renewVtxos(eventCallback?: (event: SettlementEvent) => void): Promise<string>;
+}

package/dist/types/wallet/wallet.d.ts

@@ -1,3 +1,4 @@
+import { Bytes } from "@scure/btc-signer/utils.js";
 import { ArkAddress } from "../script/address";
 import { DefaultVtxo } from "../script/default";
 import { Network, NetworkName } from "../networks";
@@ -5,7 +6,6 @@ import { OnchainProvider } from "../providers/onchain";
 import { SettlementEvent, ArkProvider } from "../providers/ark";
 import { Identity } from "../identity";
 import { ArkTransaction, Coin, ExtendedCoin, ExtendedVirtualCoin, GetVtxosFilter, IWallet, SendBitcoinParams, SettleParams, WalletBalance, WalletConfig } from ".";
-import { Bytes } from "@scure/btc-signer/utils.js";
 import { CSVMultisigTapscript } from "../script/tapscript";
 import { IndexerProvider } from "../providers/indexer";
 import { WalletRepository } from "../repositories/walletRepository";
@@ -63,10 +63,15 @@ export declare class Wallet implements IWallet {
     readonly boardingTapscript: DefaultVtxo.Script;
     readonly serverUnrollScript: CSVMultisigTapscript.Type;
     readonly forfeitOutputScript: Bytes;
+    readonly forfeitPubkey: Bytes;
     readonly dustAmount: bigint;
     static MIN_FEE_RATE: number;
     readonly walletRepository: WalletRepository;
     readonly contractRepository: ContractRepository;
+    readonly renewalConfig: Required<Omit<WalletConfig["renewalConfig"], "enabled">> & {
+        enabled: boolean;
+        thresholdPercentage: number;
+    };
     private constructor();
     static create(config: WalletConfig): Promise<Wallet>;
     get arkAddress(): ArkAddress;
@@ -86,12 +91,11 @@ export declare class Wallet implements IWallet {
     notifyIncomingFunds(eventCallback: (coins: IncomingFunds) => void): Promise<() => void>;
     private handleBatchStartedEvent;
     private handleSettlementSigningEvent;
-    private handleSettlementSigningNoncesGeneratedEvent;
+    private handleSettlementTreeNoncesEvent;
     private handleSettlementFinalizationEvent;
     private makeRegisterIntentSignature;
     private makeDeleteIntentSignature;
-    private prepareBIP322Inputs;
-    private makeBIP322Signature;
+    private prepareIntentProofInputs;
 }
 /**
  * Wait for incoming funds to the wallet

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkade-os/sdk",
-  "version": "0.3.0-alpha.8",
+  "version": "0.3.0",
   "description": "Bitcoin wallet SDK with Taproot and Ark integration",
   "type": "module",
   "main": "./dist/cjs/index.js",
@@ -54,7 +54,6 @@
   },
   "dependencies": {
     "@noble/curves": "2.0.0",
-    "@noble/hashes": "2.0.0",
     "@noble/secp256k1": "3.0.0",
     "@scure/base": "2.0.0",
     "@scure/btc-signer": "2.0.1",

package/dist/cjs/bip322/errors.js

@@ -1,13 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ErrMissingWitnessUtxo = exports.ErrMissingData = exports.ErrMissingInputs = exports.BIP322Error = void 0;
-class BIP322Error extends Error {
-    constructor(message) {
-        super(message);
-        this.name = "BIP322Error";
-    }
-}
-exports.BIP322Error = BIP322Error;
-exports.ErrMissingInputs = new BIP322Error("missing inputs");
-exports.ErrMissingData = new BIP322Error("missing data");
-exports.ErrMissingWitnessUtxo = new BIP322Error("missing witness utxo");

package/dist/esm/bip322/errors.js

@@ -1,9 +0,0 @@
-export class BIP322Error extends Error {
-    constructor(message) {
-        super(message);
-        this.name = "BIP322Error";
-    }
-}
-export const ErrMissingInputs = new BIP322Error("missing inputs");
-export const ErrMissingData = new BIP322Error("missing data");
-export const ErrMissingWitnessUtxo = new BIP322Error("missing witness utxo");

package/dist/types/bip322/errors.d.ts

@@ -1,6 +0,0 @@
-export declare class BIP322Error extends Error {
-    constructor(message: string);
-}
-export declare const ErrMissingInputs: BIP322Error;
-export declare const ErrMissingData: BIP322Error;
-export declare const ErrMissingWitnessUtxo: BIP322Error;

package/dist/types/bip322/index.d.ts

@@ -1,57 +0,0 @@
-import { Transaction } from "@scure/btc-signer/transaction.js";
-import { TransactionInput, TransactionOutput } from "@scure/btc-signer/psbt.js";
-/**
- * BIP-322 signature implementation for Bitcoin message signing.
- *
- * BIP-322 defines a standard for signing Bitcoin messages as well as proving
- * ownership of coins. This namespace provides utilities for creating and
- * validating BIP-322.
- *
- * @see https://github.com/bitcoin/bips/blob/master/bip-0322.mediawiki
- *
- * @example
- * ```typescript
- * // Create a BIP-322 proof
- * const proof = BIP322.create(
- *   "Hello Bitcoin!",
- *   [input],
- *   [output]
- * );
- *
- * // Sign the proof
- * const signedProof = await identity.sign(proof);
- *
- * // Extract the signature
- * const signature = BIP322.signature(signedProof);
- * ```
- */
-export declare namespace BIP322 {
-    type FullProof = Transaction;
-    type Signature = string;
-    /**
-     * Creates a new BIP-322 "full" proof of funds unsigned transaction.
-     *
-     * This function constructs a special transaction that can be signed to prove
-     * ownership of VTXOs and UTXOs. The proof includes the message to be
-     * signed and the inputs/outputs that demonstrate ownership.
-     *
-     * @param message - The BIP-322 message to be signed
-     * @param inputs - Array of transaction inputs to prove ownership of
-     * @param outputs - Optional array of transaction outputs
-     * @returns An unsigned BIP-322 proof transaction
-     */
-    function create(message: string, inputs: TransactionInput[], outputs?: TransactionOutput[]): FullProof;
-    /**
-     * Finalizes and extracts the FullProof transaction into a BIP-322 signature.
-     *
-     * This function takes a signed proof transaction and converts it into a
-     * base64-encoded signature string. If the proof's inputs have special
-     * spending conditions, a custom finalizer can be provided.
-     *
-     * @param signedProof - The signed BIP-322 proof transaction
-     * @param finalizer - Optional custom finalizer function
-     * @returns Base64-encoded BIP-322 signature
-     */
-    function signature(signedProof: FullProof, finalizer?: (tx: FullProof) => void): Signature;
-}
-export declare function craftToSpendTx(message: string, pkScript: Uint8Array): Transaction;