@arkade-os/sdk 0.4.15 → 0.4.16

package/dist/esm/script/vhtlc.js

@@ -2,36 +2,38 @@ import { Script } from "@scure/btc-signer";
 import { CLTVMultisigTapscript, ConditionCSVMultisigTapscript, ConditionMultisigTapscript, CSVMultisigTapscript, MultisigTapscript, } from './tapscript.js';
 import { hex } from "@scure/base";
 import { VtxoScript } from './base.js';
-/**
- * Virtual Hash Time Lock Contract (VHTLC) implementation.
- *
- * VHTLC is a contract that enables atomic swaps and conditional payments
- * in the Ark protocol. It provides multiple spending paths:
- *
- * - **claim**: Receiver can claim funds by revealing the preimage
- * - **refund**: Sender and receiver can collaboratively refund
- * - **refundWithoutReceiver**: Sender can refund after locktime expires
- * - **unilateralClaim**: Receiver can claim unilaterally after delay
- * - **unilateralRefund**: Sender and receiver can refund unilaterally after delay
- * - **unilateralRefundWithoutReceiver**: Sender can refund unilaterally after delay
- *
- * @example
- * ```typescript
- * const vhtlc = new VHTLC.Script({
- *   sender: alicePubKey,
- *   receiver: bobPubKey,
- *   server: serverPubKey,
- *   preimageHash: hash160(secret),
- *   refundLocktime: BigInt(chainTip + 10),
- *   unilateralClaimDelay: { type: 'blocks', value: 100n },
- *   unilateralRefundDelay: { type: 'blocks', value: 102n },
- *   unilateralRefundWithoutReceiverDelay: { type: 'blocks', value: 103n }
- * });
- * ```
- */
+/** Virtual Hash Time Lock Contract (VHTLC) namespace. */
 export var VHTLC;
 (function (VHTLC) {
+    /**
+     * Virtual Hash Time Lock Contract (VHTLC) script implementation.
+     *
+     * VHTLC enables atomic swaps and conditional payments in the Arkade protocol.
+     * It provides multiple spending paths:
+     *
+     * - **claim**: Receiver can claim funds by revealing the preimage
+     * - **refund**: Sender and receiver can collaboratively refund
+     * - **refundWithoutReceiver**: Sender can refund after locktime expires
+     * - **unilateralClaim**: Receiver can claim unilaterally after delay
+     * - **unilateralRefund**: Sender and receiver can refund unilaterally after delay
+     * - **unilateralRefundWithoutReceiver**: Sender can refund unilaterally after delay
+     *
+     * @example
+     * ```typescript
+     * const vhtlc = new VHTLC.Script({
+     *   sender: alicePubKey,
+     *   receiver: bobPubKey,
+     *   server: serverPubKey,
+     *   preimageHash: hash160(secret),
+     *   refundLocktime: BigInt(chainTip + 10),
+     *   unilateralClaimDelay: { type: 'blocks', value: 100n },
+     *   unilateralRefundDelay: { type: 'blocks', value: 102n },
+     *   unilateralRefundWithoutReceiverDelay: { type: 'blocks', value: 103n }
+     * });
+     * ```
+     */
     class Script extends VtxoScript {
+        /** Create a VHTLC script from the supplied participant keys, hash, and timelocks. */
         constructor(options) {
             validateOptions(options);
             const { sender, receiver, server, preimageHash, refundLocktime, unilateralClaimDelay, unilateralRefundDelay, unilateralRefundWithoutReceiverDelay, } = options;
@@ -76,21 +78,27 @@ export var VHTLC;
             this.unilateralRefundScript = hex.encode(unilateralRefundScript);
             this.unilateralRefundWithoutReceiverScript = hex.encode(unilateralRefundWithoutReceiverScript);
         }
+        /** Return the collaborative claim tapleaf script. */
         claim() {
             return this.findLeaf(this.claimScript);
         }
+        /** Return the collaborative refund tapleaf script. */
         refund() {
             return this.findLeaf(this.refundScript);
         }
+        /** Return the refund-without-receiver tapleaf script. */
         refundWithoutReceiver() {
             return this.findLeaf(this.refundWithoutReceiverScript);
         }
+        /** Return the unilateral claim tapleaf script. */
         unilateralClaim() {
             return this.findLeaf(this.unilateralClaimScript);
         }
+        /** Return the unilateral refund tapleaf script. */
         unilateralRefund() {
             return this.findLeaf(this.unilateralRefundScript);
         }
+        /** Return the unilateral refund-without-receiver tapleaf script. */
         unilateralRefundWithoutReceiver() {
             return this.findLeaf(this.unilateralRefundWithoutReceiverScript);
         }

package/dist/esm/storage/fileSystem.js

@@ -1,7 +1,7 @@
 import * as fs from "fs/promises";
 import * as path from "path";
 /**
- * @deprecated Use repositories instead
+ * @deprecated Use repository implementations via `StorageConfig` instead.
  */
 export class FileSystemStorageAdapter {
     constructor(dirPath) {

package/dist/esm/storage/inMemory.js

@@ -1,5 +1,5 @@
 /**
- * @deprecated Use repositories instead
+ * @deprecated Use repository implementations via `StorageConfig` instead.
  */
 export class InMemoryStorageAdapter {
     constructor() {

package/dist/esm/storage/indexedDB.js

@@ -1,6 +1,6 @@
 import { DB_VERSION } from '../repositories/indexedDB/db.js';
 /**
- * @deprecated Use repositories instead
+ * @deprecated Use repository implementations via `StorageConfig` instead.
  */
 export class IndexedDBStorageAdapter {
     constructor(dbName, version = DB_VERSION) {

package/dist/esm/storage/localStorage.js

@@ -1,5 +1,5 @@
 /**
- * @deprecated Use repositories instead
+ * @deprecated Use repository implementations via `StorageConfig` instead.
  */
 export class LocalStorageAdapter {
     getSafeLocalStorage() {

package/dist/esm/tree/validation.js

@@ -32,7 +32,7 @@ export function validateConnectorsTxGraph(settlementTxB64, connectorsGraph) {
     if (rootInput.index !== BATCH_OUTPUT_CONNECTORS_INDEX)
         throw ErrWrongSettlementTxid;
 }
-// ValidateVtxoTxGraph checks if the given vtxo graph is valid.
+// ValidateVtxoTxGraph checks if the given virtual output tx graph is valid.
 // The function validates:
 // - the number of nodes
 // - the number of leaves

package/dist/esm/utils/arkTransaction.js

@@ -14,7 +14,7 @@ import { Extension } from '../extension/index.js';
  *
  * Creates one checkpoint transaction per input and a virtual transaction that
  * combines all the checkpoints, sending to the specified outputs. This is the
- * core function for creating Ark transactions.
+ * core function for creating Arkade transactions.
  *
  * @param inputs - Array of virtual transaction inputs
  * @param outputs - Array of transaction outputs
@@ -92,9 +92,9 @@ function buildVirtualTx(inputs, outputs) {
     return tx;
 }
 function buildCheckpointTx(vtxo, serverUnrollScript) {
-    // create the checkpoint vtxo script from collaborative closure
+    // create the checkpoint virtual output script from collaborative closure
     const collaborativeClosure = decodeTapscript(scriptFromTapLeafScript(vtxo.tapLeafScript));
-    // create the checkpoint vtxo script combining collaborative closure and server unroll script
+    // create the checkpoint virtual output script combining collaborative closure and server unroll script
     const checkpointVtxoScript = new VtxoScript([
         serverUnrollScript.script,
         collaborativeClosure.script,
@@ -249,8 +249,8 @@ export function combineTapscriptSigs(signedTx, originalTx) {
     return originalTx;
 }
 /**
- * Validates if a given string is a valid Ark address by attempting to decode it.
- * @param address The Ark address to validate.
+ * Validates if a given string is a valid Arkade address by attempting to decode it.
+ * @param address The Arkade address to validate.
  * @returns True if the address is valid, false otherwise.
  */
 export function isValidArkAddress(address) {

package/dist/esm/utils/bip21.js

@@ -4,6 +4,12 @@ export var BIP21Error;
     BIP21Error["INVALID_ADDRESS"] = "Invalid address";
 })(BIP21Error || (BIP21Error = {}));
 export class BIP21 {
+    /**
+     * Create a BIP21 URI from the provided parameters.
+     *
+     * @param params - BIP21 parameters to encode
+     * @returns Encoded BIP21 URI
+     */
     static create(params) {
         const { address, ...options } = params;
         // Build query string
@@ -22,7 +28,7 @@ export class BIP21 {
                 queryParams[key] = value;
             }
             else if (key === "ark") {
-                // Validate ARK address format
+                // Validate Arkade address format
                 if (typeof value === "string" &&
                     (value.startsWith("ark") || value.startsWith("tark"))) {
                     queryParams[key] = value;
@@ -53,11 +59,18 @@ export class BIP21 {
             : "";
         return `bitcoin:${address ? address.toLowerCase() : ""}${query}`;
     }
+    /**
+     * Parse a BIP21 URI and return its decoded parameters.
+     *
+     * @param uri - BIP21 URI to parse
+     * @returns Parsed BIP21 URI data
+     * @throws Error if the URI does not start with the `bitcoin:` scheme
+     */
     static parse(uri) {
         if (!uri.toLowerCase().startsWith("bitcoin:")) {
             throw new Error(BIP21Error.INVALID_URI);
         }
-        // Remove bitcoin: prefix, preserving case of the rest
+        // Remove the `bitcoin:` prefix while preserving the case of the rest.
         const withoutPrefix = uri.slice(uri.toLowerCase().indexOf("bitcoin:") + 8);
         const [address, query] = withoutPrefix.split("?");
         const params = {};
@@ -80,7 +93,7 @@ export class BIP21 {
                     params[key] = amount;
                 }
                 else if (key === "ark") {
-                    // Validate ARK address format
+                    // Validate Arkade address format
                     if (value.startsWith("ark") || value.startsWith("tark")) {
                         params[key] = value;
                     }

package/dist/esm/utils/syncCursors.js

@@ -1,6 +1,6 @@
 /** Lag behind real-time to avoid racing with indexer writes. */
 export const SAFETY_LAG_MS = 30000;
-/** Overlap window so boundary VTXOs are never missed. */
+/** Overlap window so boundary virtual outputs are never missed. */
 export const OVERLAP_MS = 60000;
 /**
  * Per-repository mutex that serializes wallet-state mutations so that
@@ -101,8 +101,8 @@ export async function clearSyncCursors(repo, scripts) {
  * Returns `undefined` when the script has no cursor (bootstrap needed).
  *
  * No upper bound (`before`) is applied to the query so that freshly
- * created VTXOs are never excluded. The safety lag is applied only
- * when advancing the cursor (see {@link cursorCutoff}).
+ * created virtual outputs are never excluded. The safety lag is applied only
+ * when advancing the cursor (see @see cursorCutoff).
  */
 export function computeSyncWindow(cursor) {
     if (cursor === undefined)
@@ -112,7 +112,7 @@ export function computeSyncWindow(cursor) {
 }
 /**
  * The safe high-water mark for cursor advancement.
- * Lags behind real-time by {@link SAFETY_LAG_MS} so that VTXOs still
+ * Lags behind real-time by @see SAFETY_LAG_MS so that virtual outputs still
  * being indexed are re-queried on the next sync.
  *
  * When `requestStartedAt` is provided the cutoff is frozen to the

package/dist/esm/utils/transaction.js

@@ -1,7 +1,7 @@
 import { Transaction as BtcSignerTransaction } from "@scure/btc-signer";
 /**
  * Transaction is a wrapper around the @scure/btc-signer Transaction class.
- * It adds the Ark protocol specific options to the transaction.
+ * It adds the Arkade protocol specific options to the transaction.
  */
 export class Transaction extends BtcSignerTransaction {
     constructor(opts) {

package/dist/esm/utils/transactionHistory.js

@@ -45,13 +45,13 @@ function subtractAssets(spent, change) {
     return Array.from(map, ([assetId, amount]) => ({ assetId, amount }));
 }
 /**
- * Builds the transaction history by analyzing virtual coins (VTXOs), boarding transactions, and ignored commitments.
+ * Builds the transaction history by analyzing virtual outputs, boarding transactions, and ignored commitments.
  * History is sorted from newest to oldest and is composed only of SENT and RECEIVED transactions.
  *
- * @param {VirtualCoin[]} vtxos - An array of virtual coins representing the user's transactions and balances.
+ * @param {VirtualCoin[]} vtxos - An array of virtual outputs representing the user's transactions and balances.
  * @param {ArkTransaction[]} allBoardingTxs - An array of boarding transactions to include in the history.
  * @param {Set<string>} commitmentsToIgnore - A set of commitment IDs that should be excluded from processing.
- * @return {ExtendedArkTransaction[]} A sorted array of extended Ark transactions, representing the transaction history.
+ * @return {ExtendedArkTransaction[]} A sorted array of extended Arkade transactions, representing the transaction history.
  */
 export async function buildTransactionHistory(vtxos, allBoardingTxs, commitmentsToIgnore, getTxCreatedAt) {
     const fromOldestVtxo = [...vtxos].sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime());
@@ -59,7 +59,7 @@ export async function buildTransactionHistory(vtxos, allBoardingTxs, commitments
     let received = [];
     for (const vtxo of fromOldestVtxo) {
         if (vtxo.status.isLeaf) {
-            // If this vtxo is a leaf and it's not the settlement of a boarding or there's no vtxo refreshed by it,
+            // If this virtual output is a leaf and it's not the settlement of a boarding or there's no virtual output refreshed by it,
             // it's translated into a received batch transaction
             if (!commitmentsToIgnore.has(vtxo.virtualStatus.commitmentTxIds[0]) &&
                 fromOldestVtxo.filter((v) => v.settledBy === vtxo.virtualStatus.commitmentTxIds[0]).length === 0) {
@@ -79,7 +79,7 @@ export async function buildTransactionHistory(vtxos, allBoardingTxs, commitments
             }
         }
         else if (fromOldestVtxo.filter((v) => v.arkTxId === vtxo.txid).length === 0) {
-            // If this vtxo is preconfirmed and does not spend any other vtxos,
+            // If this virtual output is preconfirmed and does not spend any other virtual outputs,
             // it's translated into a received offchain transaction
             const assets = collectAssets([vtxo]);
             received.push({
@@ -92,15 +92,15 @@ export async function buildTransactionHistory(vtxos, allBoardingTxs, commitments
                 ...(assets && { assets }),
             });
         }
-        // If the vtxo is spent, it's translated into a sent transaction unless:
+        // If the virtual output is spent, it's translated into a sent transaction unless:
         // - it's been refreshed (we don't want to add any record in this case)
-        // - a sent transaction has been already added to avoid duplicates (can happen if many vtxos have been spent in the same tx or forfeited in the same batch)
+        // - a sent transaction has been already added to avoid duplicates (can happen if many virtual outputs have been spent in the same tx or forfeited in the same batch)
         if (vtxo.isSpent) {
-            // If the vtxo is spent offchain, it's translated into offchain sent tx
+            // If the virtual output is spent offchain, it's translated into an offchain sent tx
             if (vtxo.arkTxId &&
                 !sent.some((s) => s.key.arkTxid === vtxo.arkTxId)) {
                 const changes = fromOldestVtxo.filter((_) => _.txid === vtxo.arkTxId);
-                // We want to find all the other VTXOs spent by the same transaction to
+                // We want to find all the other virtual outputs spent by the same transaction to
                 // calculate the full amount of the change.
                 const allSpent = fromOldestVtxo.filter((v) => v.arkTxId === vtxo.arkTxId);
                 const spentAmount = allSpent.reduce((acc, v) => acc + v.value, 0);
@@ -113,7 +113,7 @@ export async function buildTransactionHistory(vtxos, allBoardingTxs, commitments
                 }
                 else {
                     txAmount = spentAmount;
-                    // TODO: fetch the vtxo with /v1/indexer/vtxos?outpoints=<vtxo.arkTxid:0> to know when the tx was made
+                    // TODO: fetch the virtual output with /v1/indexer/vtxos?outpoints=<vtxo.arkTxid:0> to know when the tx was made
                     txTime = getTxCreatedAt
                         ? ((await getTxCreatedAt(vtxo.arkTxId)) ??
                             vtxo.createdAt.getTime() + 1)
@@ -130,7 +130,7 @@ export async function buildTransactionHistory(vtxos, allBoardingTxs, commitments
                     ...(assets && { assets }),
                 });
             }
-            // If the vtxo is forfeited in a batch and the total sum of forfeited vtxos is bigger than the sum of new vtxos,
+            // If the virtual output is forfeited in a batch and the total sum of forfeited virtual outputs is bigger than the sum of new virtual outputs,
             // it's translated into an exit sent tx
             if (vtxo.settledBy &&
                 !commitmentsToIgnore.has(vtxo.settledBy) &&

package/dist/esm/utils/unknownFields.js

@@ -2,7 +2,7 @@ import * as bip68 from "bip68";
 import { RawWitness, ScriptNum } from "@scure/btc-signer";
 import { hex } from "@scure/base";
 /**
- * ArkPsbtFieldKey is the key values for ark psbt fields.
+ * ArkPsbtFieldKey are the available key names for the Arkade PSBT custom fields.
  */
 export var ArkPsbtFieldKey;
 (function (ArkPsbtFieldKey) {
@@ -12,8 +12,8 @@ export var ArkPsbtFieldKey;
     ArkPsbtFieldKey["ConditionWitness"] = "condition";
 })(ArkPsbtFieldKey || (ArkPsbtFieldKey = {}));
 /**
- * ArkPsbtFieldKeyType is the type of the ark psbt field key.
- * Every ark psbt field has key type 222.
+ * ArkPsbtFieldKeyType is the key type of the Arkade PSBT custom field.
+ * Every Arkade PSBT field has key type 222.
  */
 export const ArkPsbtFieldKeyType = 222;
 /**

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

@@ -23,7 +23,7 @@ export class AssetManager extends ReadonlyAssetManager {
      * @param params.amount - Amount of asset units to issue
      * @param params.controlAssetId - Optional control asset ID (for reissuable assets)
      * @param params.metadata - Optional metadata to attach to the asset
-     * @returns Promise resolving to the ark transaction ID and asset ID
+     * @returns Promise resolving to the Arkade transaction ID and asset ID
      *
      * @example
      * ```typescript
@@ -108,7 +108,7 @@ export class AssetManager extends ReadonlyAssetManager {
      * @param params - Parameters for asset reissuance
      * @param params.assetId - The asset ID to reissue (control asset ID is resolved via getAssetDetails)
      * @param params.amount - Amount of additional units to issue
-     * @returns Promise resolving to the ark transaction ID
+     * @returns Promise resolving to the Arkade transaction ID
      *
      * @example
      * ```typescript
@@ -215,7 +215,7 @@ export class AssetManager extends ReadonlyAssetManager {
      * @param params - Parameters for burning
      * @param params.assetId - The asset ID to burn
      * @param params.amount - Amount of units to burn
-     * @returns Promise resolving to the ark transaction ID
+     * @returns Promise resolving to the Arkade transaction ID
      *
      * @example
      * ```typescript
@@ -233,7 +233,7 @@ export class AssetManager extends ReadonlyAssetManager {
             withRecoverable: false,
         });
         const assetChanges = new Map();
-        // select vtxos with the asset to burn
+        // select virtual outputs with the asset to burn
         const { selected: assetCoins } = selectCoinsWithAsset(virtualCoins, params.assetId, BigInt(params.amount));
         const selectedCoins = [...assetCoins];
         let totalBtcSelected = 0;

package/dist/esm/wallet/batch.js

@@ -11,7 +11,7 @@ import { hex } from "@scure/base";
  * const handler = wallet.createBatchHandler(intentId, inputs, expectedRecipients, musig2session);
  *
  * const abortController = new AbortController();
- * // Get event stream from Ark provider
+ * // Get event stream from the Arkade provider
  * const eventStream = arkProvider.getEventStream(
  *   abortController.signal,
  *   ['your-topic-1', 'your-topic-2']
@@ -96,7 +96,7 @@ export var Batch;
                         step !== Step.TreeNoncesAggregated) {
                         continue;
                     }
-                    // batchIndex 0 = vtxo tree, batchIndex 1 = connector tree
+                    // batchIndex 0 = virtual output tree, batchIndex 1 = connector tree
                     if (event.batchIndex === 0) {
                         flatVtxoTree.push(event.chunk);
                     }
@@ -115,7 +115,7 @@ export var Batch;
                     if (!vtxoTree) {
                         throw new Error("vtxo tree not initialized");
                     }
-                    // push signature to the vtxo tree
+                    // push signature to the virtual output tree
                     const tapKeySig = hex.decode(event.signature);
                     vtxoTree.update(event.txid, (tx) => {
                         tx.updateInput(0, {
@@ -131,7 +131,7 @@ export var Batch;
                     if (step !== Step.BatchStarted) {
                         continue;
                     }
-                    // create vtxo tree from collected chunks
+                    // create virtual output tree from collected chunks
                     vtxoTree = TxTree.create(flatVtxoTree);
                     const { skip } = await handler.onTreeSigningStarted(event, vtxoTree);
                     if (!skip) {
@@ -153,7 +153,7 @@ export var Batch;
                     if (step !== Step.TreeNoncesAggregated) {
                         continue;
                     }
-                    // Build vtxo tree if it hasn't been built yet
+                    // Build virtual output tree if it hasn't been built yet
                     if (!vtxoTree && flatVtxoTree.length > 0) {
                         vtxoTree = TxTree.create(flatVtxoTree);
                     }

package/dist/esm/wallet/delegator.js

@@ -8,6 +8,7 @@ import { getNetwork } from '../networks.js';
 import { createAssetPacket } from './asset.js';
 import { Extension } from '../extension/index.js';
 export class DelegatorManagerImpl {
+    /** Create a delegator manager from the configured provider, Arkade info source, and wallet identity. */
     constructor(delegatorProvider, arkInfoProvider, identity) {
         this.delegatorProvider = delegatorProvider;
         this.arkInfoProvider = arkInfoProvider;
@@ -24,7 +25,7 @@ export class DelegatorManagerImpl {
         // fetch server and delegator info once, shared across all groups
         const arkInfo = await this.arkInfoProvider.getInfo();
         const delegateInfo = await this.delegatorProvider.getDelegateInfo();
-        // if explicit delegateAt is provided, delegate all vtxos at once without sorting
+        // if explicit delegateAt is provided, delegate all virtual outputs at once without sorting
         if (delegateAt) {
             try {
                 await delegate(this.identity, this.delegatorProvider, arkInfo, delegateInfo, vtxos, destinationScript, delegateAt);
@@ -34,7 +35,7 @@ export class DelegatorManagerImpl {
             }
             return { delegated: vtxos, failed: [] };
         }
-        // if no explicit delegateAt is provided, sort vtxos by expiry and delegate in groups of the same expiry day
+        // if no explicit delegateAt is provided, sort virtual outputs by expiry and delegate in groups of the same expiry day
         const groupByExpiry = new Map();
         let recoverableVtxos = [];
         for (const vtxo of vtxos) {
@@ -51,7 +52,7 @@ export class DelegatorManagerImpl {
                 vtxo,
             ]);
         }
-        // if no groups, it means we only need to delegate the recoverable vtxos
+        // if no groups, it means we only need to delegate the recoverable virtual outputs
         if (groupByExpiry.size === 0) {
             try {
                 await delegate(this.identity, this.delegatorProvider, arkInfo, delegateInfo, recoverableVtxos, destinationScript, delegateAt);
@@ -64,7 +65,7 @@ export class DelegatorManagerImpl {
             }
             return { delegated: recoverableVtxos, failed: [] };
         }
-        // search for the earliest group, include recoverable vtxos into it
+        // search for the earliest group, include recoverable virtual outputs into it
         const earliestGroup = Math.min(...groupByExpiry.keys());
         groupByExpiry.set(earliestGroup, [
             ...(groupByExpiry.get(earliestGroup) ?? []),
@@ -86,9 +87,9 @@ export class DelegatorManagerImpl {
     }
 }
 /**
- * Delegates virtual coins to a delegator provider, allowing them to manage the coins renewal
- * on behalf of the wallet.
- * @param vtxos - Array of extended virtual coins to delegate. Must not be empty.
+ * Delegates virtual outputs to a delegation service, allowing them to manage their renewal
+ * on behalf of the wallet owner.
+ * @param vtxos - Array of extended virtual outputs to delegate. Must not be empty.
  * @param delegateAt - Optional Date specifying when the delegation
  *                     should occur. If not provided, defaults to 12 hours before the earliest
  *                     expiry time of the provided vtxos.
@@ -105,7 +106,7 @@ async function delegate(identity, delegatorProvider, arkInfo, delegateInfo, vtxo
             .filter((coin) => !isRecoverable(coin) && coin.virtualStatus.batchExpiry)
             .reduce((min, coin) => Math.min(min, coin.virtualStatus.batchExpiry), Number.MAX_SAFE_INTEGER);
         if (!expiryTimestamp || expiryTimestamp === Number.MAX_SAFE_INTEGER) {
-            // if no expiry (recoverable vtxos), delegate 1 minute from now
+            // if no expiry (recoverable virtual outputs), delegate 1 minute from now
             delegateAt = new Date(Date.now() + 1 * 60 * 1000);
         }
         else {

package/dist/esm/wallet/expo/background.js

@@ -60,7 +60,7 @@ export function defineExpoBackgroundTask(taskName, options) {
             const indexerProvider = new ExpoIndexerProvider(config.arkServerUrl);
             const arkProvider = new ExpoArkProvider(config.arkServerUrl);
             // Reconstruct default offchainTapscript as fallback
-            // for VTXOs not associated with a contract.
+            // for virtual outputs not associated with a contract.
             const offchainTapscript = new DefaultVtxo.Script({
                 pubKey: hex.decode(config.pubkeyHex),
                 serverPubKey: hex.decode(config.serverPubKeyHex),
@@ -104,8 +104,8 @@ export function defineExpoBackgroundTask(taskName, options) {
 /**
  * Activate the OS-level background task scheduler.
  *
- * Call this after {@link defineExpoBackgroundTask} (typically inside
- * {@link ExpoWallet.setup} or in a React component after wallet init).
+ * Call this after @see defineExpoBackgroundTask (typically inside
+ * @see ExpoWallet.setup or in a React component after wallet init).
  *
  * @param minimumInterval - Minimum interval in minutes (default 15).
  */

package/dist/esm/wallet/expo/wallet.js

@@ -8,7 +8,7 @@ import { DefaultVtxo } from '../../script/default.js';
 /**
  * Expo/React Native wallet with built-in background task processing.
  *
- * Wraps a standard {@link Wallet} and adds a lightweight task queue
+ * Wraps a standard @see Wallet and adds a lightweight task queue
  * for keeping contract/VTXO state fresh while the app is active and
  * across Expo BackgroundTask wakes.
  *
@@ -18,10 +18,10 @@ import { DefaultVtxo } from '../../script/default.js';
  * import { AsyncStorageTaskQueue } from "@arkade-os/sdk/worker/expo";
  *
  * const wallet = await ExpoWallet.setup({
- *     identity: SingleKey.fromHex(privateKey),
- *     arkServerUrl,
- *     esploraUrl,
- *     storage: { walletRepository, contractRepository },
+ *     identity: MnemonicIdentity.fromMnemonic('abandon abandon...'),
+ *     arkServerUrl: 'https://arkade.computer',
+ *     esploraUrl: 'https://mempool.space/api',
+ *     storage: { ... },
  *     background: {
  *         taskName: "ark-background-poll",
  *         taskQueue: new AsyncStorageTaskQueue(AsyncStorage),
@@ -50,8 +50,8 @@ export class ExpoWallet {
     /**
      * Create an ExpoWallet with background task support.
      *
-     * 1. Creates the inner {@link Wallet} via `Wallet.create()`.
-     * 2. Wires up processors (defaults to {@link contractPollProcessor}).
+     * 1. Creates the inner @see Wallet via `Wallet.create()`.
+     * 2. Wires up processors (defaults to @see contractPollProcessor).
      * 3. Persists background config for the background handler (if the queue supports it).
      * 4. Seeds the task queue with a `contract-poll` task.
      * 5. Registers the background task with the OS scheduler (if `minimumBackgroundInterval` is set).

package/dist/esm/wallet/index.js

@@ -1,14 +1,48 @@
+/** Wallet transaction direction. */
 export var TxType;
 (function (TxType) {
     TxType["TxSent"] = "SENT";
     TxType["TxReceived"] = "RECEIVED";
 })(TxType || (TxType = {}));
+/**
+ * Return whether a virtual output is still spendable.
+ *
+ * @param vtxo - virtual output to inspect
+ * @returns `true` when the virtual output is not marked as spent
+ *
+ * @see isRecoverable
+ * @see isExpired
+ */
 export function isSpendable(vtxo) {
     return !vtxo.isSpent;
 }
+/**
+ * Return whether a virtual output is recoverable.
+ *
+ * @param vtxo - virtual output to inspect
+ * @returns `true` when the virtual output is swept but still spendable
+ *
+ * @remarks
+ * Recoverable virtual outputs are typically re-settled into fresh virtual outputs by the virtual output manager.
+ *
+ * @see isSpendable
+ * @see isExpired
+ */
 export function isRecoverable(vtxo) {
     return vtxo.virtualStatus.state === "swept" && isSpendable(vtxo);
 }
+/**
+ * Return whether a virtual output should be treated as expired.
+ *
+ * @param vtxo - virtual output to inspect
+ * @returns `true` when the virtual output is swept or its batch expiry has passed
+ * @remarks
+ * On regtest-like environments the upstream expiry value may be expressed as a block
+ * height instead of a timestamp. This helper intentionally ignores obviously non-time
+ * values to avoid false positives.
+ *
+ * @see VirtualStatus.batchExpiry
+ */
 export function isExpired(vtxo) {
     if (vtxo.virtualStatus.state === "swept")
         return true; // swept by server = expired
@@ -23,6 +57,15 @@ export function isExpired(vtxo) {
         return false;
     return expiry <= Date.now();
 }
+/**
+ * Return whether a virtual output is below the dust threshold.
+ *
+ * @param vtxo - virtual output to inspect
+ * @param dust - dust threshold in satoshis
+ * @returns `true` when the virtual output value is below `dust`
+ *
+ * @see isRecoverable
+ */
 export function isSubdust(vtxo, dust) {
     return vtxo.value < dust;
 }