@arkade-os/sdk 0.3.0-alpha.7 → 0.3.1-alpha.0

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

@@ -0,0 +1,207 @@
+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, thresholdMs: number): boolean;
+/**
+ * Filter VTXOs that are expiring soon
+ *
+ * @param vtxos - Array of virtual coins to check
+ * @param thresholdMs - Threshold in milliseconds from now
+ * @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;
+/**
+ * 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 VTXOs by settling them back to the wallet's address
+     *
+     * This method collects all 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";
@@ -25,13 +25,21 @@ export type IncomingFunds = {
  *
  * @example
  * ```typescript
- * // Create a wallet
+ * // Create a wallet with URL configuration
  * const wallet = await Wallet.create({
  *   identity: SingleKey.fromHex('your_private_key'),
  *   arkServerUrl: 'https://ark.example.com',
  *   esploraUrl: 'https://mempool.space/api'
  * });
  *
+ * // Or with custom provider instances (e.g., for Expo/React Native)
+ * const wallet = await Wallet.create({
+ *   identity: SingleKey.fromHex('your_private_key'),
+ *   arkProvider: new ExpoArkProvider('https://ark.example.com'),
+ *   indexerProvider: new ExpoIndexerProvider('https://ark.example.com'),
+ *   esploraUrl: 'https://mempool.space/api'
+ * });
+ *
  * // Get addresses
  * const arkAddress = await wallet.getAddress();
  * const boardingAddress = await wallet.getBoardingAddress();
@@ -55,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;
@@ -82,8 +95,7 @@ export declare class Wallet implements IWallet {
     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.7",
+  "version": "0.3.1-alpha.0",
   "description": "Bitcoin wallet SDK with Taproot and Ark integration",
   "type": "module",
   "main": "./dist/cjs/index.js",
@@ -14,6 +14,12 @@
       "require": "./dist/cjs/index.js",
       "default": "./dist/esm/index.js"
     },
+    "./adapters/expo": {
+      "types": "./dist/types/adapters/expo.d.ts",
+      "import": "./dist/esm/adapters/expo.js",
+      "require": "./dist/cjs/adapters/expo.js",
+      "default": "./dist/esm/adapters/expo.js"
+    },
     "./adapters/localStorage": {
       "types": "./dist/types/adapters/localStorage.d.ts",
       "import": "./dist/esm/adapters/localStorage.js",
@@ -48,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",
@@ -58,6 +63,7 @@
     "@types/node": "24.3.1",
     "@vitest/coverage-v8": "3.2.4",
     "esbuild": "^0.25.9",
+    "expo": "~52.0.47",
     "eventsource": "4.0.0",
     "glob": "11.0.3",
     "husky": "9.1.7",
@@ -78,7 +84,7 @@
   "author": "Ark Labs",
   "license": "MIT",
   "engines": {
-    "node": "^14.17.0 || ^16.13.0 || >=18.0.0"
+    "node": ">=20.0.0"
   },
   "scripts": {
     "build": "rimraf dist && pnpm run build:esm && node scripts/add-extensions.js && pnpm run build:cjs && pnpm run build:types && node scripts/generate-package-files.js",
@@ -101,6 +107,8 @@
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "test:sw": "pnpm run build:browser && node test/serviceWorker/serve.js",
+    "expo:web:install": "cd examples/expo-demo && pnpm install",
+    "expo:web": "cd examples/expo-demo && pnpm start",
     "format": "prettier --write src test examples",
     "lint": "prettier --check src test examples",
     "audit": "pnpm audit",

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;