@arkade-os/sdk 0.3.4 → 0.3.6

package/README.md

@@ -120,8 +120,8 @@ import { VtxoManager } from '@arkade-os/sdk'
 
 // Create manager with optional renewal configuration
 const manager = new VtxoManager(wallet, {
-  enabled: true,           // Enable expiration monitoring
-  thresholdPercentage: 10  // Alert when 10% of lifetime remains (default)
+  enabled: true,                   // Enable expiration monitoring
+  thresholdMs: 24 * 60 * 60 * 1000 // Alert when 24h hours % of lifetime remains (default)
 })
 ```
 
@@ -137,8 +137,8 @@ console.log('Renewed:', txid)
 
 // Check which VTXOs are expiring soon
 const expiringVtxos = await manager.getExpiringVtxos()
-// Override threshold percentage (e.g., renew when 5% of time remains)
-const urgentlyExpiring = await manager.getExpiringVtxos(5)
+// Override thresholdMs (e.g., renew when 5 seconds of time remains)
+const urgentlyExpiring = await manager.getExpiringVtxos(5_000)
 ```
 
 
@@ -171,7 +171,13 @@ Collaborative exit or "offboarding" allows you to withdraw your virtual funds to
 ```typescript
 import { Ramps } from '@arkade-os/sdk'
 
-const exitTxid = await new Ramps(wallet).offboard(onchainAddress);
+// Get fee information from the server
+const info = await wallet.arkProvider.getInfo();
+
+const exitTxid = await new Ramps(wallet).offboard(
+  onchainAddress,
+  info.fees
+);
 ```
 
 ### Unilateral Exit

package/dist/cjs/index.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Unroll = exports.P2A = exports.TxTree = exports.Intent = exports.ContractRepositoryImpl = exports.WalletRepositoryImpl = exports.networks = exports.ArkNote = exports.combineTapscriptSigs = exports.hasBoardingTxExpired = exports.waitForIncomingFunds = exports.verifyTapscriptSignatures = exports.buildOffchainTx = exports.ConditionWitness = exports.VtxoTaprootTree = exports.VtxoTreeExpiry = exports.CosignerPublicKey = exports.getArkPsbtFields = exports.setArkPsbtField = exports.ArkPsbtFieldKeyType = exports.ArkPsbtFieldKey = exports.TapTreeCoder = exports.CLTVMultisigTapscript = exports.ConditionMultisigTapscript = exports.ConditionCSVMultisigTapscript = exports.CSVMultisigTapscript = exports.MultisigTapscript = exports.decodeTapscript = exports.Response = exports.Request = exports.ServiceWorkerWallet = exports.Worker = exports.setupServiceWorker = exports.SettlementEventType = exports.ChainTxType = exports.IndexerTxType = exports.TxType = exports.VHTLC = exports.VtxoScript = exports.DefaultVtxo = exports.ArkAddress = exports.RestIndexerProvider = exports.RestArkProvider = exports.EsploraProvider = exports.ESPLORA_URL = exports.VtxoManager = exports.Ramps = exports.OnchainWallet = exports.SingleKey = exports.Wallet = void 0;
-exports.maybeArkError = exports.ArkError = exports.Transaction = void 0;
+exports.P2A = exports.TxTree = exports.Intent = exports.ContractRepositoryImpl = exports.WalletRepositoryImpl = exports.networks = exports.ArkNote = exports.isVtxoExpiringSoon = exports.combineTapscriptSigs = exports.hasBoardingTxExpired = exports.waitForIncomingFunds = exports.verifyTapscriptSignatures = exports.buildOffchainTx = exports.ConditionWitness = exports.VtxoTaprootTree = exports.VtxoTreeExpiry = exports.CosignerPublicKey = exports.getArkPsbtFields = exports.setArkPsbtField = exports.ArkPsbtFieldKeyType = exports.ArkPsbtFieldKey = exports.TapTreeCoder = exports.CLTVMultisigTapscript = exports.ConditionMultisigTapscript = exports.ConditionCSVMultisigTapscript = exports.CSVMultisigTapscript = exports.MultisigTapscript = exports.decodeTapscript = exports.Response = exports.Request = exports.ServiceWorkerWallet = exports.Worker = exports.setupServiceWorker = exports.SettlementEventType = exports.ChainTxType = exports.IndexerTxType = exports.TxType = exports.VHTLC = exports.VtxoScript = exports.DefaultVtxo = exports.ArkAddress = exports.RestIndexerProvider = exports.RestArkProvider = exports.EsploraProvider = exports.ESPLORA_URL = exports.VtxoManager = exports.Ramps = exports.OnchainWallet = exports.SingleKey = exports.Wallet = void 0;
+exports.maybeArkError = exports.ArkError = exports.Transaction = exports.Unroll = void 0;
 const transaction_1 = require("./utils/transaction");
 Object.defineProperty(exports, "Transaction", { enumerable: true, get: function () { return transaction_1.Transaction; } });
 const singleKey_1 = require("./identity/singleKey");
@@ -25,6 +25,7 @@ Object.defineProperty(exports, "TxTree", { enumerable: true, get: function () {
 const ramps_1 = require("./wallet/ramps");
 Object.defineProperty(exports, "Ramps", { enumerable: true, get: function () { return ramps_1.Ramps; } });
 const vtxo_manager_1 = require("./wallet/vtxo-manager");
+Object.defineProperty(exports, "isVtxoExpiringSoon", { enumerable: true, get: function () { return vtxo_manager_1.isVtxoExpiringSoon; } });
 Object.defineProperty(exports, "VtxoManager", { enumerable: true, get: function () { return vtxo_manager_1.VtxoManager; } });
 const wallet_3 = require("./wallet/serviceWorker/wallet");
 Object.defineProperty(exports, "ServiceWorkerWallet", { enumerable: true, get: function () { return wallet_3.ServiceWorkerWallet; } });

package/dist/cjs/providers/ark.js

@@ -46,7 +46,14 @@ class RestArkProvider {
             })) ?? [],
             digest: fromServer.digest ?? "",
             dust: BigInt(fromServer.dust ?? 0),
-            fees: fromServer.fees,
+            fees: {
+                intentFee: {
+                    ...fromServer.fees?.intentFee,
+                    onchainInput: BigInt(fromServer.fees?.intentFee?.onchainInput ?? 0),
+                    onchainOutput: BigInt(fromServer.fees?.intentFee?.onchainOutput ?? 0),
+                },
+                txFeeRate: fromServer?.fees?.txFeeRate ?? "",
+            },
             forfeitAddress: fromServer.forfeitAddress ?? "",
             forfeitPubkey: fromServer.forfeitPubkey ?? "",
             network: fromServer.network ?? "",

package/dist/cjs/utils/transactionHistory.js

@@ -14,6 +14,10 @@ function vtxosToTxs(spendable, spent, boardingBatchTxids) {
     // All vtxos are received unless:
     // - they resulted from a settlement (either boarding or refresh)
     // - they are the change of a spend tx
+    // - they were spent in a payment (have arkTxId set)
+    // - they resulted from a payment (their txid matches an arkTxId of a spent vtxo)
+    // First, collect all arkTxIds from spent vtxos to identify payment transactions
+    const paymentArkTxIds = new Set(spent.filter((v) => v.arkTxId).map((v) => v.arkTxId));
     let vtxosLeftToCheck = [...spent];
     for (const vtxo of [...spendable, ...spent]) {
         if (vtxo.virtualStatus.state !== "preconfirmed" &&
@@ -21,6 +25,16 @@ function vtxosToTxs(spendable, spent, boardingBatchTxids) {
             vtxo.virtualStatus.commitmentTxIds.some((txid) => boardingBatchTxids.has(txid))) {
             continue;
         }
+        // Skip vtxos that were spent in a payment transaction
+        // These will be handled in the sent transaction section below
+        if (vtxo.arkTxId) {
+            continue;
+        }
+        // Skip vtxos that resulted from a payment transaction
+        // (their txid matches an arkTxId from a spent vtxo)
+        if (paymentArkTxIds.has(vtxo.txid)) {
+            continue;
+        }
         const settleVtxos = findVtxosSpentInSettlement(vtxosLeftToCheck, vtxo);
         vtxosLeftToCheck = removeVtxosFromList(vtxosLeftToCheck, settleVtxos);
         const settleAmount = reduceVtxosAmount(settleVtxos);
@@ -56,21 +70,17 @@ function vtxosToTxs(spendable, spent, boardingBatchTxids) {
     // vtxos by settled by or ark txid
     const vtxosByTxid = new Map();
     for (const v of spent) {
-        if (v.settledBy) {
-            if (!vtxosByTxid.has(v.settledBy)) {
-                vtxosByTxid.set(v.settledBy, []);
-            }
-            const currentVtxos = vtxosByTxid.get(v.settledBy);
-            vtxosByTxid.set(v.settledBy, [...currentVtxos, v]);
-        }
-        if (!v.arkTxId) {
+        // Prefer arkTxId over settledBy to avoid duplicates
+        // A vtxo should only be grouped once
+        const groupKey = v.arkTxId || v.settledBy;
+        if (!groupKey) {
             continue;
         }
-        if (!vtxosByTxid.has(v.arkTxId)) {
-            vtxosByTxid.set(v.arkTxId, []);
+        if (!vtxosByTxid.has(groupKey)) {
+            vtxosByTxid.set(groupKey, []);
         }
-        const currentVtxos = vtxosByTxid.get(v.arkTxId);
-        vtxosByTxid.set(v.arkTxId, [...currentVtxos, v]);
+        const currentVtxos = vtxosByTxid.get(groupKey);
+        vtxosByTxid.set(groupKey, [...currentVtxos, v]);
     }
     for (const [sb, vtxos] of vtxosByTxid) {
         const resultedVtxos = findVtxosResultedFromTxid([...spendable, ...spent], sb);
@@ -85,7 +95,13 @@ function vtxosToTxs(spendable, spent, boardingBatchTxids) {
             boardingTxid: "",
             arkTxid: "",
         };
-        if (vtxo.virtualStatus.state === "preconfirmed") {
+        // Use the grouping key (sb) as arkTxid if it looks like an arkTxId
+        // (i.e., if the spent vtxos had arkTxId set, use that instead of result vtxo's txid)
+        const isArkTxId = vtxos.some((v) => v.arkTxId === sb);
+        if (isArkTxId) {
+            txKey.arkTxid = sb;
+        }
+        else if (vtxo.virtualStatus.state === "preconfirmed") {
             txKey.arkTxid = vtxo.txid;
         }
         txs.push({

package/dist/cjs/wallet/ramps.js

@@ -56,10 +56,11 @@ class Ramps {
      * Offboard vtxos, or "collaborative exit" vtxos to onchain address.
      *
      * @param destinationAddress - The destination address to offboard to.
+     * @param feeInfo - The fee info to deduct from the offboard amount.
      * @param amount - The amount to offboard. If not provided, the total amount of vtxos will be offboarded.
      * @param eventCallback - The callback to receive settlement events. optional.
      */
-    async offboard(destinationAddress, amount, eventCallback) {
+    async offboard(destinationAddress, feeInfo, amount, eventCallback) {
         const vtxos = await this.wallet.getVtxos({
             withRecoverable: true,
             withUnrolled: false,
@@ -73,6 +74,11 @@ class Ramps {
             change = totalAmount - amount;
         }
         amount = amount ?? totalAmount;
+        const fees = feeInfo.intentFee.onchainOutput;
+        if (fees > amount) {
+            throw new Error(`can't deduct fees from offboard amount (${fees} > ${amount})`);
+        }
+        amount -= fees;
         const outputs = [
             {
                 address: destinationAddress,

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

@@ -1,14 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.VtxoManager = exports.DEFAULT_RENEWAL_CONFIG = void 0;
+exports.VtxoManager = exports.DEFAULT_RENEWAL_CONFIG = exports.DEFAULT_THRESHOLD_MS = void 0;
 exports.isVtxoExpiringSoon = isVtxoExpiringSoon;
 exports.getExpiringAndRecoverableVtxos = getExpiringAndRecoverableVtxos;
 const _1 = require(".");
+exports.DEFAULT_THRESHOLD_MS = 3 * 24 * 60 * 60 * 1000; // 3 days
 /**
  * Default renewal configuration values
  */
 exports.DEFAULT_RENEWAL_CONFIG = {
-    thresholdPercentage: 10,
+    thresholdMs: exports.DEFAULT_THRESHOLD_MS, // 3 days
 };
 function getDustAmount(wallet) {
     return "dustAmount" in wallet ? wallet.dustAmount : 330n;
@@ -82,22 +83,16 @@ function getRecoverableWithSubdust(vtxos, dustAmount) {
  * @param thresholdMs - Threshold in milliseconds from now
  * @returns true if VTXO expires within threshold, false otherwise
  */
-function isVtxoExpiringSoon(vtxo, percentage) {
+function isVtxoExpiringSoon(vtxo, thresholdMs // in milliseconds
+) {
+    const realThresholdMs = thresholdMs <= 100 ? exports.DEFAULT_THRESHOLD_MS : thresholdMs;
     const { batchExpiry } = vtxo.virtualStatus;
-    if (!batchExpiry) {
+    if (!batchExpiry)
         return false; // it doesn't expire
-    }
     const now = Date.now();
-    if (batchExpiry <= now) {
+    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;
+    return batchExpiry - now <= realThresholdMs;
 }
 /**
  * Filter VTXOs that are expiring soon or are recoverable/subdust
@@ -107,8 +102,8 @@ function isVtxoExpiringSoon(vtxo, percentage) {
  * @param dustAmount - Dust threshold amount in satoshis
  * @returns Array of VTXOs expiring within threshold
  */
-function getExpiringAndRecoverableVtxos(vtxos, percentage, dustAmount) {
-    return vtxos.filter((vtxo) => isVtxoExpiringSoon(vtxo, percentage) ||
+function getExpiringAndRecoverableVtxos(vtxos, thresholdMs, dustAmount) {
+    return vtxos.filter((vtxo) => isVtxoExpiringSoon(vtxo, thresholdMs) ||
         (0, _1.isRecoverable)(vtxo) ||
         (0, _1.isSubdust)(vtxo, dustAmount));
 }
@@ -131,7 +126,7 @@ function getExpiringAndRecoverableVtxos(vtxos, percentage, dustAmount) {
  * // Initialize with renewal config
  * const manager = new VtxoManager(wallet, {
  *   enabled: true,
- *   thresholdPercentage: 10
+ *   thresholdMs: 86400000
  * });
  *
  * // Check recoverable balance
@@ -251,24 +246,24 @@ class VtxoManager {
     /**
      * Get VTXOs that are expiring soon based on renewal configuration
      *
-     * @param thresholdPercentage - Optional override for threshold percentage (0-100)
+     * @param thresholdMs - Optional override for threshold in milliseconds
      * @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 manager = new VtxoManager(wallet, { enabled: true, thresholdMs: 86400000 });
      * const expiringVtxos = await manager.getExpiringVtxos();
      * if (expiringVtxos.length > 0) {
      *   console.log(`${expiringVtxos.length} VTXOs expiring soon`);
      * }
      * ```
      */
-    async getExpiringVtxos(thresholdPercentage) {
+    async getExpiringVtxos(thresholdMs) {
         const vtxos = await this.wallet.getVtxos({ withRecoverable: true });
-        const percentage = thresholdPercentage ??
-            this.renewalConfig?.thresholdPercentage ??
-            exports.DEFAULT_RENEWAL_CONFIG.thresholdPercentage;
-        return getExpiringAndRecoverableVtxos(vtxos, percentage, getDustAmount(this.wallet));
+        const threshold = thresholdMs ??
+            this.renewalConfig?.thresholdMs ??
+            exports.DEFAULT_RENEWAL_CONFIG.thresholdMs;
+        return getExpiringAndRecoverableVtxos(vtxos, threshold, getDustAmount(this.wallet));
     }
     /**
      * Renew expiring VTXOs by settling them back to the wallet's address

package/dist/cjs/wallet/wallet.js

@@ -431,14 +431,13 @@ class Wallet {
             });
         }
         const tapTree = this.offchainTapscript.encode();
-        let offchainTx = (0, arkTransaction_1.buildOffchainTx)(selected.inputs.map((input) => ({
+        const offchainTx = (0, arkTransaction_1.buildOffchainTx)(selected.inputs.map((input) => ({
             ...input,
             tapLeafScript: selectedLeaf,
             tapTree,
         })), outputs, this.serverUnrollScript);
         const signedVirtualTx = await this.identity.sign(offchainTx.arkTx);
         const { arkTxid, signedCheckpointTxs } = await this.arkProvider.submitTx(base_1.base64.encode(signedVirtualTx.toPSBT()), offchainTx.checkpoints.map((c) => base_1.base64.encode(c.toPSBT())));
-        // TODO persist final virtual tx and checkpoints to repository
         // sign the checkpoints
         const finalCheckpoints = await Promise.all(signedCheckpointTxs.map(async (c) => {
             const tx = btc_signer_1.Transaction.fromPSBT(base_1.base64.decode(c));
@@ -446,7 +445,78 @@ class Wallet {
             return base_1.base64.encode(signedCheckpoint.toPSBT());
         }));
         await this.arkProvider.finalizeTx(arkTxid, finalCheckpoints);
-        return arkTxid;
+        try {
+            // mark VTXOs as spent and optionally add the change VTXO
+            const spentVtxos = [];
+            const commitmentTxIds = new Set();
+            let batchExpiry = Number.MAX_SAFE_INTEGER;
+            for (const [inputIndex, input] of selected.inputs.entries()) {
+                const vtxo = (0, utils_1.extendVirtualCoin)(this, input);
+                const checkpointB64 = signedCheckpointTxs[inputIndex];
+                const checkpoint = btc_signer_1.Transaction.fromPSBT(base_1.base64.decode(checkpointB64));
+                spentVtxos.push({
+                    ...vtxo,
+                    virtualStatus: { ...vtxo.virtualStatus, state: "spent" },
+                    spentBy: checkpoint.id,
+                    arkTxId: arkTxid,
+                    isSpent: true,
+                });
+                if (vtxo.virtualStatus.commitmentTxIds) {
+                    for (const commitmentTxId of vtxo.virtualStatus
+                        .commitmentTxIds) {
+                        commitmentTxIds.add(commitmentTxId);
+                    }
+                }
+                if (vtxo.virtualStatus.batchExpiry) {
+                    batchExpiry = Math.min(batchExpiry, vtxo.virtualStatus.batchExpiry);
+                }
+            }
+            const createdAt = Date.now();
+            const addr = this.arkAddress.encode();
+            if (selected.changeAmount > 0n &&
+                batchExpiry !== Number.MAX_SAFE_INTEGER) {
+                const changeVtxo = {
+                    txid: arkTxid,
+                    vout: outputs.length - 1,
+                    createdAt: new Date(createdAt),
+                    forfeitTapLeafScript: this.offchainTapscript.forfeit(),
+                    intentTapLeafScript: this.offchainTapscript.exit(),
+                    isUnrolled: false,
+                    isSpent: false,
+                    tapTree: this.offchainTapscript.encode(),
+                    value: Number(selected.changeAmount),
+                    virtualStatus: {
+                        state: "preconfirmed",
+                        commitmentTxIds: Array.from(commitmentTxIds),
+                        batchExpiry,
+                    },
+                    status: {
+                        confirmed: false,
+                    },
+                };
+                await this.walletRepository.saveVtxos(addr, [changeVtxo]);
+            }
+            await this.walletRepository.saveVtxos(addr, spentVtxos);
+            await this.walletRepository.saveTransactions(addr, [
+                {
+                    key: {
+                        boardingTxid: "",
+                        commitmentTxid: "",
+                        arkTxid: arkTxid,
+                    },
+                    amount: params.amount,
+                    type: _1.TxType.TxSent,
+                    settled: false,
+                    createdAt: Date.now(),
+                },
+            ]);
+        }
+        catch (e) {
+            console.warn("error saving offchain tx to repository", e);
+        }
+        finally {
+            return arkTxid;
+        }
     }
     async settle(params, eventCallback) {
         if (params?.inputs) {
@@ -719,7 +789,8 @@ class Wallet {
             (async () => {
                 try {
                     for await (const update of subscription) {
-                        if (update.newVtxos?.length > 0) {
+                        if (update.newVtxos?.length > 0 ||
+                            update.spentVtxos?.length > 0) {
                             eventCallback({
                                 type: "vtxo",
                                 newVtxos: update.newVtxos.map((vtxo) => (0, utils_1.extendVirtualCoin)(this, vtxo)),

package/dist/esm/index.js

@@ -8,7 +8,7 @@ import { TxType, } from './wallet/index.js';
 import { Wallet, waitForIncomingFunds } from './wallet/wallet.js';
 import { TxTree } from './tree/txTree.js';
 import { Ramps } from './wallet/ramps.js';
-import { VtxoManager } from './wallet/vtxo-manager.js';
+import { isVtxoExpiringSoon, VtxoManager } from './wallet/vtxo-manager.js';
 import { ServiceWorkerWallet } from './wallet/serviceWorker/wallet.js';
 import { OnchainWallet } from './wallet/onchain.js';
 import { setupServiceWorker } from './wallet/serviceWorker/utils.js';
@@ -45,7 +45,7 @@ decodeTapscript, MultisigTapscript, CSVMultisigTapscript, ConditionCSVMultisigTa
 // Ark PSBT fields
 ArkPsbtFieldKey, ArkPsbtFieldKeyType, setArkPsbtField, getArkPsbtFields, CosignerPublicKey, VtxoTreeExpiry, VtxoTaprootTree, ConditionWitness, 
 // Utils
-buildOffchainTx, verifyTapscriptSignatures, waitForIncomingFunds, hasBoardingTxExpired, combineTapscriptSigs, 
+buildOffchainTx, verifyTapscriptSignatures, waitForIncomingFunds, hasBoardingTxExpired, combineTapscriptSigs, isVtxoExpiringSoon, 
 // Arknote
 ArkNote, 
 // Network

package/dist/esm/providers/ark.js

@@ -42,7 +42,14 @@ export class RestArkProvider {
             })) ?? [],
             digest: fromServer.digest ?? "",
             dust: BigInt(fromServer.dust ?? 0),
-            fees: fromServer.fees,
+            fees: {
+                intentFee: {
+                    ...fromServer.fees?.intentFee,
+                    onchainInput: BigInt(fromServer.fees?.intentFee?.onchainInput ?? 0),
+                    onchainOutput: BigInt(fromServer.fees?.intentFee?.onchainOutput ?? 0),
+                },
+                txFeeRate: fromServer?.fees?.txFeeRate ?? "",
+            },
             forfeitAddress: fromServer.forfeitAddress ?? "",
             forfeitPubkey: fromServer.forfeitPubkey ?? "",
             network: fromServer.network ?? "",

package/dist/esm/utils/transactionHistory.js

@@ -11,6 +11,10 @@ export function vtxosToTxs(spendable, spent, boardingBatchTxids) {
     // All vtxos are received unless:
     // - they resulted from a settlement (either boarding or refresh)
     // - they are the change of a spend tx
+    // - they were spent in a payment (have arkTxId set)
+    // - they resulted from a payment (their txid matches an arkTxId of a spent vtxo)
+    // First, collect all arkTxIds from spent vtxos to identify payment transactions
+    const paymentArkTxIds = new Set(spent.filter((v) => v.arkTxId).map((v) => v.arkTxId));
     let vtxosLeftToCheck = [...spent];
     for (const vtxo of [...spendable, ...spent]) {
         if (vtxo.virtualStatus.state !== "preconfirmed" &&
@@ -18,6 +22,16 @@ export function vtxosToTxs(spendable, spent, boardingBatchTxids) {
             vtxo.virtualStatus.commitmentTxIds.some((txid) => boardingBatchTxids.has(txid))) {
             continue;
         }
+        // Skip vtxos that were spent in a payment transaction
+        // These will be handled in the sent transaction section below
+        if (vtxo.arkTxId) {
+            continue;
+        }
+        // Skip vtxos that resulted from a payment transaction
+        // (their txid matches an arkTxId from a spent vtxo)
+        if (paymentArkTxIds.has(vtxo.txid)) {
+            continue;
+        }
         const settleVtxos = findVtxosSpentInSettlement(vtxosLeftToCheck, vtxo);
         vtxosLeftToCheck = removeVtxosFromList(vtxosLeftToCheck, settleVtxos);
         const settleAmount = reduceVtxosAmount(settleVtxos);
@@ -53,21 +67,17 @@ export function vtxosToTxs(spendable, spent, boardingBatchTxids) {
     // vtxos by settled by or ark txid
     const vtxosByTxid = new Map();
     for (const v of spent) {
-        if (v.settledBy) {
-            if (!vtxosByTxid.has(v.settledBy)) {
-                vtxosByTxid.set(v.settledBy, []);
-            }
-            const currentVtxos = vtxosByTxid.get(v.settledBy);
-            vtxosByTxid.set(v.settledBy, [...currentVtxos, v]);
-        }
-        if (!v.arkTxId) {
+        // Prefer arkTxId over settledBy to avoid duplicates
+        // A vtxo should only be grouped once
+        const groupKey = v.arkTxId || v.settledBy;
+        if (!groupKey) {
             continue;
         }
-        if (!vtxosByTxid.has(v.arkTxId)) {
-            vtxosByTxid.set(v.arkTxId, []);
+        if (!vtxosByTxid.has(groupKey)) {
+            vtxosByTxid.set(groupKey, []);
         }
-        const currentVtxos = vtxosByTxid.get(v.arkTxId);
-        vtxosByTxid.set(v.arkTxId, [...currentVtxos, v]);
+        const currentVtxos = vtxosByTxid.get(groupKey);
+        vtxosByTxid.set(groupKey, [...currentVtxos, v]);
     }
     for (const [sb, vtxos] of vtxosByTxid) {
         const resultedVtxos = findVtxosResultedFromTxid([...spendable, ...spent], sb);
@@ -82,7 +92,13 @@ export function vtxosToTxs(spendable, spent, boardingBatchTxids) {
             boardingTxid: "",
             arkTxid: "",
         };
-        if (vtxo.virtualStatus.state === "preconfirmed") {
+        // Use the grouping key (sb) as arkTxid if it looks like an arkTxId
+        // (i.e., if the spent vtxos had arkTxId set, use that instead of result vtxo's txid)
+        const isArkTxId = vtxos.some((v) => v.arkTxId === sb);
+        if (isArkTxId) {
+            txKey.arkTxid = sb;
+        }
+        else if (vtxo.virtualStatus.state === "preconfirmed") {
             txKey.arkTxid = vtxo.txid;
         }
         txs.push({

package/dist/esm/wallet/ramps.js

@@ -53,10 +53,11 @@ export class Ramps {
      * Offboard vtxos, or "collaborative exit" vtxos to onchain address.
      *
      * @param destinationAddress - The destination address to offboard to.
+     * @param feeInfo - The fee info to deduct from the offboard amount.
      * @param amount - The amount to offboard. If not provided, the total amount of vtxos will be offboarded.
      * @param eventCallback - The callback to receive settlement events. optional.
      */
-    async offboard(destinationAddress, amount, eventCallback) {
+    async offboard(destinationAddress, feeInfo, amount, eventCallback) {
         const vtxos = await this.wallet.getVtxos({
             withRecoverable: true,
             withUnrolled: false,
@@ -70,6 +71,11 @@ export class Ramps {
             change = totalAmount - amount;
         }
         amount = amount ?? totalAmount;
+        const fees = feeInfo.intentFee.onchainOutput;
+        if (fees > amount) {
+            throw new Error(`can't deduct fees from offboard amount (${fees} > ${amount})`);
+        }
+        amount -= fees;
         const outputs = [
             {
                 address: destinationAddress,

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

@@ -1,9 +1,10 @@
 import { isRecoverable, isSubdust } from './index.js';
+export const DEFAULT_THRESHOLD_MS = 3 * 24 * 60 * 60 * 1000; // 3 days
 /**
  * Default renewal configuration values
  */
 export const DEFAULT_RENEWAL_CONFIG = {
-    thresholdPercentage: 10,
+    thresholdMs: DEFAULT_THRESHOLD_MS, // 3 days
 };
 function getDustAmount(wallet) {
     return "dustAmount" in wallet ? wallet.dustAmount : 330n;
@@ -77,22 +78,16 @@ function getRecoverableWithSubdust(vtxos, dustAmount) {
  * @param thresholdMs - Threshold in milliseconds from now
  * @returns true if VTXO expires within threshold, false otherwise
  */
-export function isVtxoExpiringSoon(vtxo, percentage) {
+export function isVtxoExpiringSoon(vtxo, thresholdMs // in milliseconds
+) {
+    const realThresholdMs = thresholdMs <= 100 ? DEFAULT_THRESHOLD_MS : thresholdMs;
     const { batchExpiry } = vtxo.virtualStatus;
-    if (!batchExpiry) {
+    if (!batchExpiry)
         return false; // it doesn't expire
-    }
     const now = Date.now();
-    if (batchExpiry <= now) {
+    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;
+    return batchExpiry - now <= realThresholdMs;
 }
 /**
  * Filter VTXOs that are expiring soon or are recoverable/subdust
@@ -102,8 +97,8 @@ export function isVtxoExpiringSoon(vtxo, percentage) {
  * @param dustAmount - Dust threshold amount in satoshis
  * @returns Array of VTXOs expiring within threshold
  */
-export function getExpiringAndRecoverableVtxos(vtxos, percentage, dustAmount) {
-    return vtxos.filter((vtxo) => isVtxoExpiringSoon(vtxo, percentage) ||
+export function getExpiringAndRecoverableVtxos(vtxos, thresholdMs, dustAmount) {
+    return vtxos.filter((vtxo) => isVtxoExpiringSoon(vtxo, thresholdMs) ||
         isRecoverable(vtxo) ||
         isSubdust(vtxo, dustAmount));
 }
@@ -126,7 +121,7 @@ export function getExpiringAndRecoverableVtxos(vtxos, percentage, dustAmount) {
  * // Initialize with renewal config
  * const manager = new VtxoManager(wallet, {
  *   enabled: true,
- *   thresholdPercentage: 10
+ *   thresholdMs: 86400000
  * });
  *
  * // Check recoverable balance
@@ -246,24 +241,24 @@ export class VtxoManager {
     /**
      * Get VTXOs that are expiring soon based on renewal configuration
      *
-     * @param thresholdPercentage - Optional override for threshold percentage (0-100)
+     * @param thresholdMs - Optional override for threshold in milliseconds
      * @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 manager = new VtxoManager(wallet, { enabled: true, thresholdMs: 86400000 });
      * const expiringVtxos = await manager.getExpiringVtxos();
      * if (expiringVtxos.length > 0) {
      *   console.log(`${expiringVtxos.length} VTXOs expiring soon`);
      * }
      * ```
      */
-    async getExpiringVtxos(thresholdPercentage) {
+    async getExpiringVtxos(thresholdMs) {
         const vtxos = await this.wallet.getVtxos({ withRecoverable: true });
-        const percentage = thresholdPercentage ??
-            this.renewalConfig?.thresholdPercentage ??
-            DEFAULT_RENEWAL_CONFIG.thresholdPercentage;
-        return getExpiringAndRecoverableVtxos(vtxos, percentage, getDustAmount(this.wallet));
+        const threshold = thresholdMs ??
+            this.renewalConfig?.thresholdMs ??
+            DEFAULT_RENEWAL_CONFIG.thresholdMs;
+        return getExpiringAndRecoverableVtxos(vtxos, threshold, getDustAmount(this.wallet));
     }
     /**
      * Renew expiring VTXOs by settling them back to the wallet's address

package/dist/esm/wallet/wallet.js

@@ -394,14 +394,13 @@ export class Wallet {
             });
         }
         const tapTree = this.offchainTapscript.encode();
-        let offchainTx = buildOffchainTx(selected.inputs.map((input) => ({
+        const offchainTx = buildOffchainTx(selected.inputs.map((input) => ({
             ...input,
             tapLeafScript: selectedLeaf,
             tapTree,
         })), outputs, this.serverUnrollScript);
         const signedVirtualTx = await this.identity.sign(offchainTx.arkTx);
         const { arkTxid, signedCheckpointTxs } = await this.arkProvider.submitTx(base64.encode(signedVirtualTx.toPSBT()), offchainTx.checkpoints.map((c) => base64.encode(c.toPSBT())));
-        // TODO persist final virtual tx and checkpoints to repository
         // sign the checkpoints
         const finalCheckpoints = await Promise.all(signedCheckpointTxs.map(async (c) => {
             const tx = Transaction.fromPSBT(base64.decode(c));
@@ -409,7 +408,78 @@ export class Wallet {
             return base64.encode(signedCheckpoint.toPSBT());
         }));
         await this.arkProvider.finalizeTx(arkTxid, finalCheckpoints);
-        return arkTxid;
+        try {
+            // mark VTXOs as spent and optionally add the change VTXO
+            const spentVtxos = [];
+            const commitmentTxIds = new Set();
+            let batchExpiry = Number.MAX_SAFE_INTEGER;
+            for (const [inputIndex, input] of selected.inputs.entries()) {
+                const vtxo = extendVirtualCoin(this, input);
+                const checkpointB64 = signedCheckpointTxs[inputIndex];
+                const checkpoint = Transaction.fromPSBT(base64.decode(checkpointB64));
+                spentVtxos.push({
+                    ...vtxo,
+                    virtualStatus: { ...vtxo.virtualStatus, state: "spent" },
+                    spentBy: checkpoint.id,
+                    arkTxId: arkTxid,
+                    isSpent: true,
+                });
+                if (vtxo.virtualStatus.commitmentTxIds) {
+                    for (const commitmentTxId of vtxo.virtualStatus
+                        .commitmentTxIds) {
+                        commitmentTxIds.add(commitmentTxId);
+                    }
+                }
+                if (vtxo.virtualStatus.batchExpiry) {
+                    batchExpiry = Math.min(batchExpiry, vtxo.virtualStatus.batchExpiry);
+                }
+            }
+            const createdAt = Date.now();
+            const addr = this.arkAddress.encode();
+            if (selected.changeAmount > 0n &&
+                batchExpiry !== Number.MAX_SAFE_INTEGER) {
+                const changeVtxo = {
+                    txid: arkTxid,
+                    vout: outputs.length - 1,
+                    createdAt: new Date(createdAt),
+                    forfeitTapLeafScript: this.offchainTapscript.forfeit(),
+                    intentTapLeafScript: this.offchainTapscript.exit(),
+                    isUnrolled: false,
+                    isSpent: false,
+                    tapTree: this.offchainTapscript.encode(),
+                    value: Number(selected.changeAmount),
+                    virtualStatus: {
+                        state: "preconfirmed",
+                        commitmentTxIds: Array.from(commitmentTxIds),
+                        batchExpiry,
+                    },
+                    status: {
+                        confirmed: false,
+                    },
+                };
+                await this.walletRepository.saveVtxos(addr, [changeVtxo]);
+            }
+            await this.walletRepository.saveVtxos(addr, spentVtxos);
+            await this.walletRepository.saveTransactions(addr, [
+                {
+                    key: {
+                        boardingTxid: "",
+                        commitmentTxid: "",
+                        arkTxid: arkTxid,
+                    },
+                    amount: params.amount,
+                    type: TxType.TxSent,
+                    settled: false,
+                    createdAt: Date.now(),
+                },
+            ]);
+        }
+        catch (e) {
+            console.warn("error saving offchain tx to repository", e);
+        }
+        finally {
+            return arkTxid;
+        }
     }
     async settle(params, eventCallback) {
         if (params?.inputs) {
@@ -682,7 +752,8 @@ export class Wallet {
             (async () => {
                 try {
                     for await (const update of subscription) {
-                        if (update.newVtxos?.length > 0) {
+                        if (update.newVtxos?.length > 0 ||
+                            update.spentVtxos?.length > 0) {
                             eventCallback({
                                 type: "vtxo",
                                 newVtxos: update.newVtxos.map((vtxo) => extendVirtualCoin(this, vtxo)),

package/dist/types/index.d.ts

@@ -10,7 +10,7 @@ import { Wallet, waitForIncomingFunds, IncomingFunds } from "./wallet/wallet";
 import { TxTree, TxTreeNode } from "./tree/txTree";
 import { SignerSession, TreeNonces, TreePartialSigs } from "./tree/signingSession";
 import { Ramps } from "./wallet/ramps";
-import { VtxoManager } from "./wallet/vtxo-manager";
+import { isVtxoExpiringSoon, VtxoManager } from "./wallet/vtxo-manager";
 import { ServiceWorkerWallet } from "./wallet/serviceWorker/wallet";
 import { OnchainWallet } from "./wallet/onchain";
 import { setupServiceWorker } from "./wallet/serviceWorker/utils";
@@ -18,7 +18,7 @@ import { Worker } from "./wallet/serviceWorker/worker";
 import { Request } from "./wallet/serviceWorker/request";
 import { Response } from "./wallet/serviceWorker/response";
 import { ESPLORA_URL, EsploraProvider, OnchainProvider, ExplorerTransaction } from "./providers/onchain";
-import { RestArkProvider, ArkProvider, SettlementEvent, SettlementEventType, ArkInfo, SignedIntent, Output, TxNotification, BatchFinalizationEvent, BatchFinalizedEvent, BatchFailedEvent, TreeSigningStartedEvent, TreeNoncesEvent, BatchStartedEvent, TreeTxEvent, TreeSignatureEvent, ScheduledSession } from "./providers/ark";
+import { RestArkProvider, ArkProvider, SettlementEvent, SettlementEventType, ArkInfo, SignedIntent, Output, TxNotification, BatchFinalizationEvent, BatchFinalizedEvent, BatchFailedEvent, TreeSigningStartedEvent, TreeNoncesEvent, BatchStartedEvent, TreeTxEvent, TreeSignatureEvent, ScheduledSession, FeeInfo } from "./providers/ark";
 import { CLTVMultisigTapscript, ConditionCSVMultisigTapscript, ConditionMultisigTapscript, CSVMultisigTapscript, decodeTapscript, MultisigTapscript, TapscriptType, ArkTapscript, RelativeTimelock } from "./script/tapscript";
 import { hasBoardingTxExpired, buildOffchainTx, verifyTapscriptSignatures, ArkTxInput, OffchainTx, combineTapscriptSigs } from "./utils/arkTransaction";
 import { VtxoTaprootTree, ConditionWitness, getArkPsbtFields, setArkPsbtField, ArkPsbtFieldCoder, ArkPsbtFieldKey, ArkPsbtFieldKeyType, CosignerPublicKey, VtxoTreeExpiry } from "./utils/unknownFields";
@@ -33,5 +33,5 @@ import { Unroll } from "./wallet/unroll";
 import { WalletRepositoryImpl } from "./repositories/walletRepository";
 import { ContractRepositoryImpl } from "./repositories/contractRepository";
 import { ArkError, maybeArkError } from "./providers/errors";
-export { Wallet, SingleKey, OnchainWallet, Ramps, VtxoManager, ESPLORA_URL, EsploraProvider, RestArkProvider, RestIndexerProvider, ArkAddress, DefaultVtxo, VtxoScript, VHTLC, TxType, IndexerTxType, ChainTxType, SettlementEventType, setupServiceWorker, Worker, ServiceWorkerWallet, Request, Response, decodeTapscript, MultisigTapscript, CSVMultisigTapscript, ConditionCSVMultisigTapscript, ConditionMultisigTapscript, CLTVMultisigTapscript, TapTreeCoder, ArkPsbtFieldKey, ArkPsbtFieldKeyType, setArkPsbtField, getArkPsbtFields, CosignerPublicKey, VtxoTreeExpiry, VtxoTaprootTree, ConditionWitness, buildOffchainTx, verifyTapscriptSignatures, waitForIncomingFunds, hasBoardingTxExpired, combineTapscriptSigs, ArkNote, networks, WalletRepositoryImpl, ContractRepositoryImpl, Intent, TxTree, P2A, Unroll, Transaction, ArkError, maybeArkError, };
-export type { Identity, IWallet, WalletConfig, ProviderClass, ArkTransaction, Coin, ExtendedCoin, ExtendedVirtualCoin, WalletBalance, SendBitcoinParams, Recipient, SettleParams, Status, VirtualStatus, Outpoint, VirtualCoin, TxKey, TapscriptType, ArkTxInput, OffchainTx, TapLeaves, IncomingFunds, IndexerProvider, PageResponse, Batch, ChainTx, CommitmentTx, TxHistoryRecord, Vtxo, VtxoChain, Tx, OnchainProvider, ArkProvider, SettlementEvent, ArkInfo, SignedIntent, Output, TxNotification, ExplorerTransaction, BatchFinalizationEvent, BatchFinalizedEvent, BatchFailedEvent, TreeSigningStartedEvent, TreeNoncesEvent, BatchStartedEvent, TreeTxEvent, TreeSignatureEvent, ScheduledSession, PaginationOptions, SubscriptionResponse, SubscriptionHeartbeat, SubscriptionEvent, Network, NetworkName, ArkTapscript, RelativeTimelock, EncodedVtxoScript, TapLeafScript, SignerSession, TreeNonces, TreePartialSigs, GetVtxosFilter, Nonces, PartialSig, ArkPsbtFieldCoder, TxTreeNode, AnchorBumper, };
+export { Wallet, SingleKey, OnchainWallet, Ramps, VtxoManager, ESPLORA_URL, EsploraProvider, RestArkProvider, RestIndexerProvider, ArkAddress, DefaultVtxo, VtxoScript, VHTLC, TxType, IndexerTxType, ChainTxType, SettlementEventType, setupServiceWorker, Worker, ServiceWorkerWallet, Request, Response, decodeTapscript, MultisigTapscript, CSVMultisigTapscript, ConditionCSVMultisigTapscript, ConditionMultisigTapscript, CLTVMultisigTapscript, TapTreeCoder, ArkPsbtFieldKey, ArkPsbtFieldKeyType, setArkPsbtField, getArkPsbtFields, CosignerPublicKey, VtxoTreeExpiry, VtxoTaprootTree, ConditionWitness, buildOffchainTx, verifyTapscriptSignatures, waitForIncomingFunds, hasBoardingTxExpired, combineTapscriptSigs, isVtxoExpiringSoon, ArkNote, networks, WalletRepositoryImpl, ContractRepositoryImpl, Intent, TxTree, P2A, Unroll, Transaction, ArkError, maybeArkError, };
+export type { Identity, IWallet, WalletConfig, ProviderClass, ArkTransaction, Coin, ExtendedCoin, ExtendedVirtualCoin, WalletBalance, SendBitcoinParams, Recipient, SettleParams, Status, VirtualStatus, Outpoint, VirtualCoin, TxKey, TapscriptType, ArkTxInput, OffchainTx, TapLeaves, IncomingFunds, IndexerProvider, PageResponse, Batch, ChainTx, CommitmentTx, TxHistoryRecord, Vtxo, VtxoChain, Tx, OnchainProvider, ArkProvider, SettlementEvent, FeeInfo, ArkInfo, SignedIntent, Output, TxNotification, ExplorerTransaction, BatchFinalizationEvent, BatchFinalizedEvent, BatchFailedEvent, TreeSigningStartedEvent, TreeNoncesEvent, BatchStartedEvent, TreeTxEvent, TreeSignatureEvent, ScheduledSession, PaginationOptions, SubscriptionResponse, SubscriptionHeartbeat, SubscriptionEvent, Network, NetworkName, ArkTapscript, RelativeTimelock, EncodedVtxoScript, TapLeafScript, SignerSession, TreeNonces, TreePartialSigs, GetVtxosFilter, Nonces, PartialSig, ArkPsbtFieldCoder, TxTreeNode, AnchorBumper, };

package/dist/types/providers/ark.d.ts

@@ -75,8 +75,8 @@ export interface ScheduledSession {
 export interface IntentFeeInfo {
     offchainInput: string;
     offchainOutput: string;
-    onchainInput: string;
-    onchainOutput: string;
+    onchainInput: bigint;
+    onchainOutput: bigint;
 }
 export interface FeeInfo {
     intentFee: IntentFeeInfo;

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

@@ -1,5 +1,5 @@
 import { ExtendedCoin, IWallet } from ".";
-import { SettlementEvent } from "../providers/ark";
+import { FeeInfo, SettlementEvent } from "../providers/ark";
 /**
  * Ramps is a class wrapping IWallet.settle method to provide a more convenient interface for onboarding and offboarding operations.
  *
@@ -25,8 +25,9 @@ export declare class Ramps {
      * Offboard vtxos, or "collaborative exit" vtxos to onchain address.
      *
      * @param destinationAddress - The destination address to offboard to.
+     * @param feeInfo - The fee info to deduct from the offboard amount.
      * @param amount - The amount to offboard. If not provided, the total amount of vtxos will be offboarded.
      * @param eventCallback - The callback to receive settlement events. optional.
      */
-    offboard(destinationAddress: string, amount?: bigint, eventCallback?: (event: SettlementEvent) => void): ReturnType<IWallet["settle"]>;
+    offboard(destinationAddress: string, feeInfo: FeeInfo, amount?: bigint, eventCallback?: (event: SettlementEvent) => void): ReturnType<IWallet["settle"]>;
 }

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

@@ -1,5 +1,6 @@
 import { ExtendedVirtualCoin, IWallet } from ".";
 import { SettlementEvent } from "../providers/ark";
+export declare const DEFAULT_THRESHOLD_MS: number;
 /**
  * Configuration options for automatic VTXO renewal
  */
@@ -10,11 +11,11 @@ export interface RenewalConfig {
      */
     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
+     * Threshold in milliseconds to use as threshold for renewal
+     * E.g., 86400000 means renew when 24 hours until expiry remains
+     * @default 86400000 (24 hours)
      */
-    thresholdPercentage?: number;
+    thresholdMs?: number;
 }
 /**
  * Default renewal configuration values
@@ -27,7 +28,7 @@ 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, percentage: number): boolean;
+export declare function isVtxoExpiringSoon(vtxo: ExtendedVirtualCoin, thresholdMs: number): boolean;
 /**
  * Filter VTXOs that are expiring soon or are recoverable/subdust
  *
@@ -36,7 +37,7 @@ export declare function isVtxoExpiringSoon(vtxo: ExtendedVirtualCoin, percentage
  * @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[];
+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.
@@ -56,7 +57,7 @@ export declare function getExpiringAndRecoverableVtxos(vtxos: ExtendedVirtualCoi
  * // Initialize with renewal config
  * const manager = new VtxoManager(wallet, {
  *   enabled: true,
- *   thresholdPercentage: 10
+ *   thresholdMs: 86400000
  * });
  *
  * // Check recoverable balance
@@ -137,19 +138,19 @@ export declare class VtxoManager {
     /**
      * Get VTXOs that are expiring soon based on renewal configuration
      *
-     * @param thresholdPercentage - Optional override for threshold percentage (0-100)
+     * @param thresholdMs - Optional override for threshold in milliseconds
      * @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 manager = new VtxoManager(wallet, { enabled: true, thresholdMs: 86400000 });
      * const expiringVtxos = await manager.getExpiringVtxos();
      * if (expiringVtxos.length > 0) {
      *   console.log(`${expiringVtxos.length} VTXOs expiring soon`);
      * }
      * ```
      */
-    getExpiringVtxos(thresholdPercentage?: number): Promise<ExtendedVirtualCoin[]>;
+    getExpiringVtxos(thresholdMs?: number): Promise<ExtendedVirtualCoin[]>;
     /**
      * Renew expiring VTXOs by settling them back to the wallet's address
      *

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

@@ -71,7 +71,7 @@ export declare class Wallet implements IWallet {
     readonly contractRepository: ContractRepository;
     readonly renewalConfig: Required<Omit<WalletConfig["renewalConfig"], "enabled">> & {
         enabled: boolean;
-        thresholdPercentage: number;
+        thresholdMs: number;
     };
     private constructor();
     static create(config: WalletConfig): Promise<Wallet>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkade-os/sdk",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "description": "Bitcoin wallet SDK with Taproot and Ark integration",
   "type": "module",
   "main": "./dist/cjs/index.js",
@@ -63,8 +63,8 @@
     "@types/node": "24.3.1",
     "@vitest/coverage-v8": "3.2.4",
     "esbuild": "^0.25.9",
-    "expo": "~52.0.47",
     "eventsource": "4.0.0",
+    "expo": "~52.0.47",
     "glob": "11.0.3",
     "husky": "9.1.7",
     "prettier": "3.6.2",