@arkade-os/sdk 0.4.14 → 0.4.16

package/dist/cjs/utils/unknownFields.js

@@ -40,7 +40,7 @@ const bip68 = __importStar(require("bip68"));
 const btc_signer_1 = require("@scure/btc-signer");
 const base_1 = require("@scure/base");
 /**
- * ArkPsbtFieldKey is the key values for ark psbt fields.
+ * ArkPsbtFieldKey are the available key names for the Arkade PSBT custom fields.
  */
 var ArkPsbtFieldKey;
 (function (ArkPsbtFieldKey) {
@@ -50,8 +50,8 @@ var ArkPsbtFieldKey;
     ArkPsbtFieldKey["ConditionWitness"] = "condition";
 })(ArkPsbtFieldKey || (exports.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.
  */
 exports.ArkPsbtFieldKeyType = 222;
 /**

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

@@ -27,7 +27,7 @@ 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
@@ -112,7 +112,7 @@ 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
@@ -219,7 +219,7 @@ 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
@@ -237,7 +237,7 @@ 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 } = (0, asset_2.selectCoinsWithAsset)(virtualCoins, params.assetId, BigInt(params.amount));
         const selectedCoins = [...assetCoins];
         let totalBtcSelected = 0;

package/dist/cjs/wallet/batch.js

@@ -14,7 +14,7 @@ const base_1 = require("@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']
@@ -99,7 +99,7 @@ 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);
                     }
@@ -118,7 +118,7 @@ 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 = base_1.hex.decode(event.signature);
                     vtxoTree.update(event.txid, (tx) => {
                         tx.updateInput(0, {
@@ -134,7 +134,7 @@ var Batch;
                     if (step !== Step.BatchStarted) {
                         continue;
                     }
-                    // create vtxo tree from collected chunks
+                    // create virtual output tree from collected chunks
                     vtxoTree = txTree_1.TxTree.create(flatVtxoTree);
                     const { skip } = await handler.onTreeSigningStarted(event, vtxoTree);
                     if (!skip) {
@@ -156,7 +156,7 @@ 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_1.TxTree.create(flatVtxoTree);
                     }

package/dist/cjs/wallet/delegator.js

@@ -12,6 +12,7 @@ const networks_1 = require("../networks");
 const asset_1 = require("./asset");
 const extension_1 = require("../extension");
 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;
@@ -28,7 +29,7 @@ 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);
@@ -38,7 +39,7 @@ 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) {
@@ -55,7 +56,7 @@ 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);
@@ -68,7 +69,7 @@ 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) ?? []),
@@ -91,9 +92,9 @@ class DelegatorManagerImpl {
 }
 exports.DelegatorManagerImpl = 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.
@@ -110,7 +111,7 @@ async function delegate(identity, delegatorProvider, arkInfo, delegateInfo, vtxo
             .filter((coin) => !(0, __1.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/cjs/wallet/expo/background.js

@@ -65,7 +65,7 @@ function defineExpoBackgroundTask(taskName, options) {
             const indexerProvider = new expoIndexer_1.ExpoIndexerProvider(config.arkServerUrl);
             const arkProvider = new expoArk_1.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 default_1.DefaultVtxo.Script({
                 pubKey: base_1.hex.decode(config.pubkeyHex),
                 serverPubKey: base_1.hex.decode(config.serverPubKeyHex),
@@ -109,8 +109,8 @@ 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/cjs/wallet/expo/wallet.js

@@ -44,7 +44,7 @@ const default_1 = require("../../script/default");
 /**
  * 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.
  *
@@ -54,10 +54,10 @@ const default_1 = require("../../script/default");
  * 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),
@@ -86,8 +86,8 @@ 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/cjs/wallet/index.js

@@ -5,17 +5,51 @@ exports.isSpendable = isSpendable;
 exports.isRecoverable = isRecoverable;
 exports.isExpired = isExpired;
 exports.isSubdust = isSubdust;
+/** Wallet transaction direction. */
 var TxType;
 (function (TxType) {
     TxType["TxSent"] = "SENT";
     TxType["TxReceived"] = "RECEIVED";
 })(TxType || (exports.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
+ */
 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
+ */
 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
+ */
 function isExpired(vtxo) {
     if (vtxo.virtualStatus.state === "swept")
         return true; // swept by server = expired
@@ -30,6 +64,15 @@ 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
+ */
 function isSubdust(vtxo, dust) {
     return vtxo.value < dust;
 }

package/dist/cjs/wallet/onchain.js

@@ -13,7 +13,7 @@ const utils_1 = require("./utils");
  * 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
@@ -33,6 +33,16 @@ 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) {
@@ -46,9 +56,21 @@ 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
@@ -63,9 +85,9 @@ 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
@@ -74,7 +96,7 @@ 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
@@ -107,6 +129,14 @@ 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");
@@ -152,6 +182,14 @@ 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_1.Transaction({
@@ -173,7 +211,7 @@ 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/cjs/wallet/ramps.js

@@ -7,30 +7,50 @@ const base_1 = require("@scure/base");
 const networks_1 = require("../networks");
 const address_1 = require("../script/address");
 /**
- * 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
  * ```
  */
 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 arkfee_1.Estimator(feeInfo?.intentFee ?? {});
         const filteredBoardingUtxos = [];
         let totalAmount = 0n;
@@ -39,7 +59,7 @@ 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);
@@ -87,19 +107,29 @@ 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 arkfee_1.Estimator(feeInfo?.intentFee ?? {});
         const filteredVtxos = [];
         let totalAmount = 0n;
@@ -116,7 +146,7 @@ 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/cjs/wallet/serviceWorker/wallet-message-handler.js

@@ -55,7 +55,7 @@ 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();
@@ -490,7 +490,7 @@ 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) {
@@ -535,9 +535,9 @@ 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.
@@ -568,12 +568,12 @@ 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,
@@ -583,11 +583,11 @@ class WalletMessageHandler {
                 if (funds.type === "utxo") {
                     const utxos = funds.coins.map((utxo) => (0, utils_1.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,
@@ -596,8 +596,8 @@ 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();
@@ -608,7 +608,7 @@ 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.
      */
@@ -616,14 +616,14 @@ 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) => (0, utils_1.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)
@@ -765,7 +765,7 @@ 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() {
@@ -782,7 +782,7 @@ 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) {
@@ -796,15 +796,15 @@ 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) {
@@ -815,8 +815,8 @@ 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) {