@arkade-os/sdk 0.4.15 → 0.4.17

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;
 }

package/dist/esm/wallet/onchain.js

@@ -9,7 +9,7 @@ import { DUST_AMOUNT } from './utils.js';
  * Onchain Bitcoin wallet implementation for traditional Bitcoin transactions.
  *
  * This wallet handles regular Bitcoin transactions on the blockchain without
- * using the Ark protocol. It supports P2TR (Pay-to-Taproot) addresses and
+ * using the Arkade protocol. It supports P2TR (Pay-to-Taproot) addresses and
  * provides basic Bitcoin wallet functionality.
  *
  * @example
@@ -29,6 +29,16 @@ export class OnchainWallet {
         this.onchainP2TR = onchainP2TR;
         this.provider = provider;
     }
+    /**
+     * Create an onchain wallet for the given identity and Bitcoin network.
+     *
+     * @param identity - Identity used to derive the Taproot key and sign transactions
+     * @param networkName - Bitcoin network name, @see NetworkName
+     * @param provider - Optional onchain provider override, @see OnchainProvider
+     * @returns Configured onchain wallet
+     * @defaultValue `provider = new EsploraProvider('https://mempool.space/api')`
+     * @throws Error if the configured identity cannot produce a valid x-only public key
+     */
     static async create(identity, networkName, provider) {
         const pubkey = await identity.xOnlyPublicKey();
         if (!pubkey) {
@@ -42,9 +52,21 @@ export class OnchainWallet {
     get address() {
         return this.onchainP2TR.address || "";
     }
+    /**
+     * Fetch spendable onchain outputs for the wallet address.
+     *
+     * @returns Spendable onchain outputs for the wallet address
+     * @see getBalance
+     */
     async getCoins() {
         return this.provider.getCoins(this.address);
     }
+    /**
+     * Return the wallet's total onchain balance in satoshis.
+     *
+     * @returns Confirmed plus unconfirmed onchain balance
+     * @see getCoins
+     */
     async getBalance() {
         const coins = await this.getCoins();
         const onchainConfirmed = coins
@@ -59,9 +81,9 @@ export class OnchainWallet {
     /**
      * Iteratively selects coins and estimates transaction fees until convergence.
      *
-     * This method handles the circular dependency between coin selection and fee
+     * This method handles the circular dependency between output selection and fee
      * estimation: the fee depends on transaction size, which depends on the number
-     * of inputs (selected coins) and whether a change output is needed.
+     * of inputs (selected outputs) and whether a change output is needed.
      *
      * The algorithm iterates up to 10 times, refining the fee estimate based on
      * the actual transaction structure. It resolves dust oscillation loops that
@@ -70,7 +92,7 @@ export class OnchainWallet {
      * When a lower fee is computed (indicating the change output was dropped),
      * the function accepts this state to guarantee termination.
      *
-     * @param coins - Available coins to select from
+     * @param coins - Available onchain outputs to select from
      * @param amount - Target send amount in satoshis
      * @param feeRate - Fee rate in sat/vbyte
      * @param recipientAddress - Destination address for size estimation
@@ -103,6 +125,14 @@ export class OnchainWallet {
         }
         throw new Error("Fee estimation failed: could not converge");
     }
+    /**
+     * Send bitcoin to a single onchain address.
+     *
+     * @param params - destination `address`, `amount` (in satoshis), and optional `feeRate` override (other fields ignored)
+     * @returns Broadcast transaction id
+     * @throws Error if the amount is non-positive, below dust, or cannot be funded
+     * @see SendBitcoinParams
+     */
     async send(params) {
         if (params.amount <= 0) {
             throw new Error("Amount must be positive");
@@ -148,6 +178,14 @@ export class OnchainWallet {
         const txid = await this.provider.broadcastTransaction(tx.hex);
         return txid;
     }
+    /**
+     * CPFP-bump a parent transaction that contains a pay-to-anchor output.
+     *
+     * @param parent - Parent transaction containing a pay-to-anchor output
+     * @returns Tuple of parent transaction id and child transaction id
+     * @throws Error if the parent transaction has no pay-to-anchor output or bumping cannot be funded
+     * @see send
+     */
     async bumpP2A(parent) {
         const parentVsize = parent.vsize;
         let child = new Transaction({
@@ -169,7 +207,7 @@ export class OnchainWallet {
         if (!fee) {
             throw new Error(`invalid fee, got ${fee} with vsize ${packageVSize}, feeRate ${feeRate}`);
         }
-        // Select coins
+        // Select onchain outputs
         const coins = await this.getCoins();
         const selected = selectCoins(coins, fee, true);
         for (const input of selected.inputs) {

package/dist/esm/wallet/ramps.js

@@ -4,30 +4,50 @@ import { hex } from "@scure/base";
 import { networks } from '../networks.js';
 import { ArkAddress } from '../script/address.js';
 /**
- * Ramps is a class wrapping IWallet.settle method to provide a more convenient interface for onboarding and offboarding operations.
+ * Ramps is a class wrapping `settle` method to provide a more convenient interface for onboarding and offboarding operations.
+ *
+ * @see IWallet.settle
+ * @see onboard
+ * @see offboard
  *
  * @example
  * ```typescript
  * const ramps = new Ramps(wallet);
- * await ramps.onboard(); // onboard all boarding utxos
- * await ramps.offboard(myOnchainAddress); // collaborative exit all vtxos to onchain address
+ * const feeInfo = { intentFee: {}, txFeeRate: '1' };
+ * await ramps.onboard(feeInfo); // onboard all boarding inputs
+ * await ramps.offboard('bc1q...', feeInfo); // collaboratively exit all virtual outputs to an onchain address
  * ```
  */
 export class Ramps {
+    /**
+     * Create convenience wrappers for onboarding and offboarding flows.
+     *
+     * @param wallet - Wallet used to query funds and execute settlement transactions
+     */
     constructor(wallet) {
         this.wallet = wallet;
     }
     /**
-     * Onboard boarding utxos.
+     * Onboard boarding inputs.
      *
      * @param feeInfo - The fee info to deduct from the onboard amount.
-     * @param boardingUtxos - The boarding utxos to onboard. If not provided, all boarding utxos will be used.
-     * @param amount - The amount to onboard. If not provided, the total amount of boarding utxos will be onboarded.
-     * @param eventCallback - The callback to receive settlement events. optional.
+     * @param boardingUtxos - Specific boarding inputs to onboard. If not provided, all boarding inputs will be used.
+     * @param amount - Amount to onboard. If not provided, the total amount of boarding inputs will be onboarded.
+     * @param eventCallback - Optional callback that receives settlement events
+     * @returns The Arkade transaction id created by settlement
+     * @throws Error if no boarding inputs remain after fee deduction or if `amount` exceeds available value
+     * @see IWallet.getBoardingUtxos
+     * @see IWallet.settle
+     * @example
+     * ```typescript
+     * const feeInfo = { intentFee: {}, txFeeRate: '1' };
+     * const ramps = new Ramps(wallet);
+     * await ramps.onboard(feeInfo);
+     * ```
      */
     async onboard(feeInfo, boardingUtxos, amount, eventCallback) {
         boardingUtxos = boardingUtxos ?? (await this.wallet.getBoardingUtxos());
-        // Calculate input fees and filter out utxos where fee >= value
+        // Calculate input fees and filter out boarding inputs where fee >= value.
         const estimator = new Estimator(feeInfo?.intentFee ?? {});
         const filteredBoardingUtxos = [];
         let totalAmount = 0n;
@@ -36,7 +56,7 @@ export class Ramps {
                 amount: BigInt(utxo.value),
             });
             if (inputFee.satoshis >= utxo.value) {
-                // skip if fees are greater than or equal to the utxo value
+                // Skip boarding inputs where spending fees are greater than or equal to the input value.
                 continue;
             }
             filteredBoardingUtxos.push(utxo);
@@ -84,19 +104,29 @@ export class Ramps {
         }, eventCallback);
     }
     /**
-     * Offboard vtxos, or "collaborative exit" vtxos to onchain address.
+     * Offboard virtual outputs, or collaboratively exit them to an 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.
+     * @param amount - The amount to offboard. If not provided, the total amount of virtual outputs will be offboarded.
+     * @param eventCallback - Optional callback that receives settlement events
+     * @returns The Arkade transaction id created by settlement
+     * @throws Error if no virtual outputs remain after fee deduction or the destination address cannot be decoded
+     * @see IWallet.getVtxos
+     * @see IWallet.settle
+     * @example
+     * ```typescript
+     * const feeInfo = { intentFee: {}, txFeeRate: '1' };
+     * const ramps = new Ramps(wallet);
+     * await ramps.offboard('bc1q...', feeInfo);
+     * ```
      */
     async offboard(destinationAddress, feeInfo, amount, eventCallback) {
         const vtxos = await this.wallet.getVtxos({
             withRecoverable: true,
             withUnrolled: false,
         });
-        // Calculate input fees and filter out vtxos where fee >= value
+        // Calculate input fees and filter out virtual outputs where fee >= value.
         const estimator = new Estimator(feeInfo?.intentFee ?? {});
         const filteredVtxos = [];
         let totalAmount = 0n;
@@ -113,7 +143,7 @@ export class Ramps {
                     : undefined,
             });
             if (inputFee.satoshis >= vtxo.value) {
-                // skip if fees are greater than or equal to the vtxo value
+                // Skip virtual outputs where spending fees are greater than or equal to the output value.
                 continue;
             }
             filteredVtxos.push(vtxo);

package/dist/esm/wallet/serviceWorker/wallet-message-handler.js

@@ -49,7 +49,7 @@ export class WalletMessageHandler {
             this.contractEventsSubscription = undefined;
         }
         // Dispose the wallet to stop VtxoManager background tasks
-        // (auto-renewal, boarding UTXO polling) and ContractWatcher.
+        // (auto-renewal, boarding input polling) and ContractWatcher.
         try {
             if (this.wallet) {
                 await this.wallet.dispose();
@@ -484,7 +484,7 @@ export class WalletMessageHandler {
         }
         const totalBoarding = confirmed + unconfirmed;
         const totalOffchain = settled + preconfirmed + recoverable;
-        // aggregate asset balances from spendable vtxos
+        // aggregate asset balances from spendable virtual outputs
         const assetBalances = new Map();
         for (const vtxo of spendableVtxos) {
             if (vtxo.assets) {
@@ -529,9 +529,9 @@ export class WalletMessageHandler {
             return;
         }
         // Initialize contract manager FIRST — this populates the repository
-        // with full VTXO history for all contracts (one indexer call per contract)
+        // with full virtual output history for all contracts (one indexer call per contract)
         await this.ensureContractEventBroadcasting();
-        // Refresh cached data (VTXOs, boarding UTXOs, tx history)
+        // Refresh cached data (virtual outputs, boarding inputs, tx history)
         await this.refreshCachedData();
         // Recover pending transactions (init-only, not on reload).
         // Pending txs only exist if a send was interrupted mid-finalization.
@@ -562,12 +562,12 @@ export class WalletMessageHandler {
                         : [];
                     if ([...newVtxos, ...spentVtxos].length === 0)
                         return;
-                    // save vtxos using unified repository
+                    // save virtual outputs using unified repository
                     await this.walletRepository?.saveVtxos(address, [
                         ...newVtxos,
                         ...spentVtxos,
                     ]);
-                    // notify all clients about the vtxo update
+                    // notify all clients about the virtual output state update
                     this.scheduleForNextTick(() => this.tagged({
                         type: "VTXO_UPDATE",
                         broadcast: true,
@@ -577,11 +577,11 @@ export class WalletMessageHandler {
                 if (funds.type === "utxo") {
                     const utxos = funds.coins.map((utxo) => extendCoin(this.readonlyWallet, utxo));
                     const boardingAddress = await this.readonlyWallet.getBoardingAddress();
-                    // save utxos using unified repository
-                    // TODO: remove UTXOS by address
+                    // save boarding inputs using unified repository
+                    // TODO: remove UTXOs by address
                     //  await this.walletRepository.clearUtxos(boardingAddress);
                     await this.walletRepository?.saveUtxos(boardingAddress, utxos);
-                    // notify all clients about the utxo update
+                    // notify all clients about the boarding input state update
                     this.scheduleForNextTick(() => this.tagged({
                         type: "UTXO_UPDATE",
                         broadcast: true,
@@ -590,8 +590,8 @@ export class WalletMessageHandler {
                 }
             });
         // Eagerly start the VtxoManager so its background tasks (auto-renewal,
-        // boarding UTXO polling/sweep) run inside the service worker without
-        // waiting for a client to send a vtxo-manager message first.
+        // boarding input polling/sweep) run inside the service worker without
+        // waiting for a client to send a VtxoManager message first.
         if (this.wallet) {
             try {
                 await this.wallet.getVtxoManager();
@@ -602,7 +602,7 @@ export class WalletMessageHandler {
         }
     }
     /**
-     * Refresh VTXOs, boarding UTXOs, and transaction history from cache.
+     * Refresh virtual outputs, boarding inputs, and transaction history from cache.
      * Shared by onWalletInitialized (full bootstrap) and reloadWallet
      * (post-refresh), avoiding duplicate subscriptions and VtxoManager restarts.
      */
@@ -610,14 +610,14 @@ export class WalletMessageHandler {
         if (!this.readonlyWallet || !this.walletRepository) {
             return;
         }
-        // Read VTXOs from repository (now populated by contract manager)
+        // Read virtual outputs from repository (now populated by contract manager)
         const vtxos = await this.getVtxosFromRepo();
-        // Fetch boarding utxos and save using unified repository
+        // Fetch boarding inputs and save using unified repository
         const boardingAddress = await this.readonlyWallet.getBoardingAddress();
         const coins = await this.readonlyWallet.onchainProvider.getCoins(boardingAddress);
         await this.walletRepository.deleteUtxos(boardingAddress);
         await this.walletRepository.saveUtxos(boardingAddress, coins.map((utxo) => extendCoin(this.readonlyWallet, utxo)));
-        // Build transaction history from cached VTXOs (no indexer call)
+        // Build transaction history from cached virtual outputs (no indexer call)
         const address = await this.readonlyWallet.getAddress();
         const txs = await this.buildTransactionHistoryFromCache(vtxos);
         if (txs)
@@ -759,7 +759,7 @@ export class WalletMessageHandler {
         this.indexerProvider = undefined;
     }
     /**
-     * Read all VTXOs from the repository, aggregated across all contract
+     * Read all virtual outputs from the repository, aggregated across all contract
      * addresses and the wallet's primary address, with deduplication.
      */
     async getVtxosFromRepo() {
@@ -776,7 +776,7 @@ export class WalletMessageHandler {
                 }
             }
         };
-        // Aggregate VTXOs from all contract addresses
+        // Aggregate virtual outputs from all contract addresses
         const manager = await this.readonlyWallet.getContractManager();
         const contracts = await manager.getContracts();
         for (const contract of contracts) {
@@ -790,15 +790,15 @@ export class WalletMessageHandler {
         return allVtxos;
     }
     /**
-     * Build transaction history from cached VTXOs without hitting the indexer.
+     * Build transaction history from cached virtual outputs without hitting the indexer.
      * Falls back to indexer only for uncached transaction timestamps.
      */
     async buildTransactionHistoryFromCache(vtxos) {
         if (!this.readonlyWallet)
             return null;
         const { boardingTxs, commitmentsToIgnore } = await this.readonlyWallet.getBoardingTxs();
-        // Build a lookup for cached VTXO timestamps, keyed by txid.
-        // Multiple VTXOs can share a txid (different vouts) — we keep the
+        // Build a lookup for cached virtual output timestamps, keyed by txid.
+        // Multiple virtual outputs can share a txid (different vouts) — we keep the
         // earliest createdAt so the history ordering is stable.
         const vtxoCreatedAt = new Map();
         for (const vtxo of vtxos) {
@@ -809,8 +809,8 @@ export class WalletMessageHandler {
             }
         }
         // Pre-fetch uncached timestamps in a single batched indexer call.
-        // buildTransactionHistory needs these for spent-offchain VTXOs with
-        // no change outputs (i.e. arkTxId is set but no VTXO has txid === arkTxId).
+        // buildTransactionHistory needs these for spent-offchain virtual outputs with
+        // no change outputs (i.e. arkTxId is set but no virtual output has txid === arkTxId).
         if (this.indexerProvider) {
             const uncachedTxids = new Set();
             for (const vtxo of vtxos) {

package/dist/esm/wallet/serviceWorker/wallet.js

@@ -179,6 +179,13 @@ export class ServiceWorkerReadonlyWallet {
     getTimeoutForRequest(request) {
         return this.messageTimeouts[request.type] ?? 30000;
     }
+    /**
+     * Create a readonly service-worker wallet bound to an already-registered worker.
+     *
+     * @param options - Service worker, identity, and backend configuration
+     * @returns Initialized readonly service-worker wallet
+     * @throws Error if service-worker initialization fails
+     */
     static async create(options) {
         const walletRepository = options.storage?.walletRepository ??
             new IndexedDBWalletRepository();
@@ -239,23 +246,17 @@ export class ServiceWorkerReadonlyWallet {
         return wallet;
     }
     /**
-     * Simplified setup method that handles service worker registration,
-     * identity creation, and wallet initialization automatically.
+     * Simplified setup method that handles service worker registration
+     * and wallet initialization automatically.
+     *
+     * @see ServiceWorkerReadonlyWallet.create
      *
      * @example
      * ```typescript
-     * // One-liner setup - handles everything automatically!
      * const wallet = await ServiceWorkerReadonlyWallet.setup({
      *   serviceWorkerPath: '/service-worker.js',
-     *   arkServerUrl: 'https://mutinynet.arkade.sh'
-     * });
-     *
-     * // With custom readonly identity
-     * const identity = ReadonlySingleKey.fromPublicKey('your_public_key_hex');
-     * const wallet = await ServiceWorkerReadonlyWallet.setup({
-     *   serviceWorkerPath: '/service-worker.js',
-     *   arkServerUrl: 'https://mutinynet.arkade.sh',
-     *   identity
+     *   arkServerUrl: 'https://arkade.computer',
+     *   identity: ReadonlySingleKey.fromPublicKey('your_public_key_hex')
      * });
      * ```
      */
@@ -457,6 +458,7 @@ export class ServiceWorkerReadonlyWallet {
         });
         return this.reinitPromise;
     }
+    /** Clear cached wallet state from both the page and service worker storage. */
     async clear() {
         const message = {
             id: getRandomId(),
@@ -529,6 +531,11 @@ export class ServiceWorkerReadonlyWallet {
             throw new Error(`Failed to get boarding UTXOs: ${error}`);
         }
     }
+    /**
+     * Return service-worker wallet status, including connectivity and sync state.
+     *
+     * @returns Current service-worker wallet status payload including `walletInitalized` and `xOnlyPublicKey`
+     */
     async getStatus() {
         const message = {
             id: getRandomId(),
@@ -573,6 +580,11 @@ export class ServiceWorkerReadonlyWallet {
             throw new Error(`Failed to get vtxos: ${error}`);
         }
     }
+    /**
+     * Trigger a wallet reload inside the service worker.
+     *
+     * @returns `true` when the wallet was reloaded
+     */
     async reload() {
         const message = {
             id: getRandomId(),
@@ -851,23 +863,15 @@ export class ServiceWorkerWallet extends ServiceWorkerReadonlyWallet {
         return wallet;
     }
     /**
-     * Simplified setup method that handles service worker registration,
-     * identity creation, and wallet initialization automatically.
+     * Simplified setup method that handles service worker registration
+     * and wallet initialization automatically.
      *
      * @example
      * ```typescript
-     * // One-liner setup - handles everything automatically!
-     * const wallet = await ServiceWorkerWallet.setup({
-     *   serviceWorkerPath: '/service-worker.js',
-     *   arkServerUrl: 'https://mutinynet.arkade.sh'
-     * });
-     *
-     * // With custom identity
-     * const identity = SingleKey.fromHex('your_private_key_hex');
      * const wallet = await ServiceWorkerWallet.setup({
      *   serviceWorkerPath: '/service-worker.js',
-     *   arkServerUrl: 'https://mutinynet.arkade.sh',
-     *   identity
+     *   arkServerUrl: 'https://arkade.computer',
+     *   identity: MnemonicIdentity.fromMnemonic('abandon abandon...')
      * });
      * ```
      */