@arkade-os/sdk 0.4.15 → 0.4.17

package/dist/esm/wallet/wallet.js

@@ -34,6 +34,10 @@ import { ContractManager } from '../contracts/contractManager.js';
 import { contractHandlers } from '../contracts/handlers/index.js';
 import { timelockToSequence } from '../contracts/handlers/helpers.js';
 import { advanceSyncCursors, clearSyncCursors, computeSyncWindow, cursorCutoff, getAllSyncCursors, updateWalletState, } from '../utils/syncCursors.js';
+// Hardcoded unilateral exit delay for mainnet (~7 days in seconds).
+// Pinned here so that address derivation stays stable for existing mainnet
+// wallets even after the server lowers the delay it advertises.
+const MAINNET_UNILATERAL_EXIT_DELAY = 605184n;
 /**
  * Type guard function to check if an identity has a toReadonly method.
  */
@@ -108,12 +112,12 @@ export class ReadonlyWallet {
             const serverIsMainnet = info.network === "bitcoin";
             if (identityIsMainnet && !serverIsMainnet) {
                 throw new Error(`Network mismatch: identity uses mainnet derivation (coin type 0) ` +
-                    `but Ark server is on ${info.network}. ` +
+                    `but the Arkade server is on ${info.network}. ` +
                     `Create identity with { isMainnet: false } to use testnet derivation.`);
             }
             if (!identityIsMainnet && serverIsMainnet) {
                 throw new Error(`Network mismatch: identity uses testnet derivation (coin type 1) ` +
-                    `but Ark server is on mainnet. ` +
+                    `but the Arkade server is on mainnet. ` +
                     `Create identity with { isMainnet: true } or omit isMainnet (defaults to mainnet).`);
             }
         }
@@ -129,10 +133,16 @@ export class ReadonlyWallet {
                 throw new Error("invalid exitTimelock");
             }
         }
+        // On mainnet, pin the unilateral exit delay to the historical value so
+        // that addresses derived by existing wallets remain stable even if the
+        // server starts advertising a shorter delay.
+        const unilateralExitDelay = info.network === "bitcoin"
+            ? MAINNET_UNILATERAL_EXIT_DELAY
+            : info.unilateralExitDelay;
         // create unilateral exit timelock
         const exitTimelock = config.exitTimelock ?? {
-            value: info.unilateralExitDelay,
-            type: info.unilateralExitDelay < 512n ? "blocks" : "seconds",
+            value: unilateralExitDelay,
+            type: unilateralExitDelay < 512n ? "blocks" : "seconds",
         };
         // validate boarding timelock passed in config if any
         if (config.boardingTimelock) {
@@ -185,6 +195,12 @@ export class ReadonlyWallet {
             delegatorProvider: config.delegatorProvider,
         };
     }
+    /**
+     * Create a readonly wallet for querying balances, addresses, and history.
+     *
+     * @param config - Readonly wallet configuration
+     * @returns A readonly wallet instance
+     */
     static async create(config) {
         const pubkey = await config.identity.xOnlyPublicKey();
         if (!pubkey) {
@@ -203,12 +219,17 @@ export class ReadonlyWallet {
     get defaultContractScript() {
         return hex.encode(this.offchainTapscript.pkScript);
     }
+    /** Returns the wallet's Arkade address. */
     async getAddress() {
         return this.arkAddress.encode();
     }
+    /** Returns the onchain boarding address used to move funds into Arkade. */
     async getBoardingAddress() {
         return this.boardingTapscript.onchainAddress(this.network);
     }
+    /**
+     * Return the wallet's combined onchain and offchain balances.
+     */
     async getBalance() {
         const [boardingUtxos, vtxos] = await Promise.all([
             this.getBoardingUtxos(),
@@ -240,7 +261,7 @@ export class ReadonlyWallet {
             .reduce((sum, coin) => sum + coin.value, 0);
         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 vtxos) {
             if (!isSpendable(vtxo))
@@ -270,15 +291,16 @@ export class ReadonlyWallet {
             assets,
         };
     }
+    /**
+     * Return virtual outputs tracked by the wallet.
+     *
+     * @param filter - Optional flags controlling whether recoverable or unrolled VTXOs are included
+     */
     async getVtxos(filter) {
-        const { isDelta, fetchedExtended, address } = await this.syncVtxos();
         const f = filter ?? { withRecoverable: true, withUnrolled: false };
-        // For delta syncs, read the full merged set from cache so old
-        // VTXOs that weren't in the delta are still returned.
-        const vtxos = isDelta
-            ? await this.walletRepository.getVtxos(address)
-            : fetchedExtended;
-        return vtxos.filter((vtxo) => {
+        const contractManager = await this.getContractManager();
+        const contractsWithVtxos = await contractManager.getContractsWithVtxos();
+        return contractsWithVtxos.flatMap(({ vtxos }) => vtxos.filter((vtxo) => {
             if (isSpendable(vtxo)) {
                 if (!f.withRecoverable &&
                     (isRecoverable(vtxo) || isExpired(vtxo))) {
@@ -287,10 +309,13 @@ export class ReadonlyWallet {
                 return true;
             }
             return !!(f.withUnrolled && vtxo.isUnrolled);
-        });
+        }));
     }
+    /**
+     * Return wallet transaction history derived from Arkade state and boarding transactions.
+     */
     async getTransactionHistory() {
-        // Delta-sync VTXOs into cache, then build history from the cache.
+        // Delta-sync virtual outputs into cache, then build history from the cache.
         const { isDelta, fetchedExtended, address } = await this.syncVtxos();
         const allVtxos = isDelta
             ? await this.walletRepository.getVtxos(address)
@@ -302,7 +327,7 @@ export class ReadonlyWallet {
         return buildTransactionHistory(allVtxos, boardingTxs, commitmentsToIgnore, getTxCreatedAt);
     }
     /**
-     * Delta-sync wallet VTXOs: fetch only changed VTXOs since the last
+     * Delta-sync wallet virtual outputs: fetch only changed virtual outputs since the last
      * cursor, or do a full bootstrap when no cursor exists. Upserts
      * the result into the cache and advances the sync cursors.
      *
@@ -375,21 +400,21 @@ export class ReadonlyWallet {
                 allVtxos.push(...response.vtxos);
             }
         }
-        // Extend every fetched VTXO and upsert into the cache.
+        // Extend every fetched virtual output and upsert into the cache.
         const fetchedExtended = [];
         for (const vtxo of allVtxos) {
             const extended = extendWithScript(vtxo);
             if (extended)
                 fetchedExtended.push(extended);
         }
-        // Save VTXOs first, then advance cursors only on success.
+        // Save virtual outputs first, then advance cursors only on success.
         const cutoff = cursorCutoff(requestStartedAt);
         await this.walletRepository.saveVtxos(address, fetchedExtended);
         await advanceSyncCursors(this.walletRepository, Object.fromEntries(allScripts.map((s) => [s, cutoff])));
         // Delta-sync reconciliation: full re-fetch for delta scripts.
         //
-        // The delta fetch (above) only returns VTXOs changed after the
-        // cursor, so it can miss preconfirmed VTXOs that were consumed
+        // The delta fetch (above) only returns virtual outputs changed after the
+        // cursor, so it can miss preconfirmed virtual outputs that were consumed
         // by a round between syncs.  Rather than layering targeted
         // queries (pendingOnly, spendableOnly) with pagination guards
         // and set algebra, we perform a single unfiltered re-fetch for
@@ -397,8 +422,8 @@ export class ReadonlyWallet {
         // gives us complete, authoritative state in one call and keeps
         // the reconciliation logic simple.
         //
-        // Any cached non-spent VTXO that is absent from the full
-        // result set is marked spent; any VTXO whose state changed
+        // Any cached non-spent virtual output that is absent from the full
+        // result set is marked spent; any virtual output whose state changed
         // (e.g. preconfirmed → settled) is updated in place.
         if (hasDelta) {
             const { vtxos: fullVtxos, page: fullPage } = await this.indexerProvider.getVtxos({
@@ -407,7 +432,7 @@ export class ReadonlyWallet {
             // Reconciliation is best-effort: if the response is
             // paginated we don't have a complete picture, so we skip
             // rather than act on partial data.  Wallets with enough
-            // VTXOs to exceed a single page rely solely on the
+            // virtual outputs to exceed a single page rely solely on the
             // cursor-based delta mechanism for state updates.
             const fullSetComplete = !fullPage || fullPage.total <= 1;
             if (fullSetComplete) {
@@ -424,7 +449,7 @@ export class ReadonlyWallet {
                     const outpoint = `${cached.txid}:${cached.vout}`;
                     const fresh = fullOutpoints.get(outpoint);
                     if (!fresh) {
-                        // Server no longer knows about this VTXO —
+                        // Server no longer knows about this virtual output —
                         // it was spent between syncs.
                         reconciledExtended.push({
                             ...cached,
@@ -457,12 +482,15 @@ export class ReadonlyWallet {
         };
     }
     /**
-     * Clear all VTXO sync cursors, forcing a full re-bootstrap on next sync.
+     * Clear all virtual output sync cursors, forcing a full re-bootstrap on next sync.
      * Useful for recovery after indexer reprocessing or debugging.
      */
     async clearSyncCursors() {
         await clearSyncCursors(this.walletRepository);
     }
+    /**
+     * Build a transaction history view for the wallet's boarding address.
+     */
     async getBoardingTxs() {
         const utxos = [];
         const commitmentsToIgnore = new Set();
@@ -533,16 +561,25 @@ export class ReadonlyWallet {
             commitmentsToIgnore,
         };
     }
+    /**
+     * Fetch and cache onchain inputs (UTXOs) received at the boarding address.
+     */
     async getBoardingUtxos() {
         const boardingAddress = await this.getBoardingAddress();
         const boardingUtxos = await this.onchainProvider.getCoins(boardingAddress);
         const utxos = boardingUtxos.map((utxo) => {
             return extendCoin(this, utxo);
         });
-        // Save boardingUtxos using unified repository
+        // Save boarding inputs using unified repository
         await this.walletRepository.saveUtxos(boardingAddress, utxos);
         return utxos;
     }
+    /**
+     * Subscribe to onchain and offchain notifications for newly received funds.
+     *
+     * @param eventCallback - Callback invoked when matching funds are detected
+     * @returns A function that stops the subscriptions
+     */
     async notifyIncomingFunds(eventCallback) {
         const arkAddress = await this.getAddress();
         const boardingAddress = await this.getBoardingAddress();
@@ -553,11 +590,11 @@ export class ReadonlyWallet {
                 return tx.vout.findIndex((v) => v.scriptpubkey_address === boardingAddress);
             };
             onchainStopFunc = await this.onchainProvider.watchAddresses([boardingAddress], (txs) => {
-                // find all utxos belonging to our boarding address
+                // find all onchain outputs belonging to our boarding address
                 const coins = txs
                     // filter txs where address is in output
                     .filter((tx) => findVoutOnTx(tx) !== -1)
-                    // return utxo as Coin
+                    // return boarding input as Coin
                     .map((tx) => {
                     const { txid, status } = tx;
                     const vout = findVoutOnTx(tx);
@@ -582,8 +619,8 @@ export class ReadonlyWallet {
             };
             // Handle subscription updates asynchronously without blocking.
             // Note: subscription covers all wallet scripts (default + delegate),
-            // but we can't determine which script each VTXO belongs to from the
-            // subscription event. VTXOs are extended with the current offchainTapscript;
+            // but we can't determine which script each virtual output belongs to from the
+            // subscription event. Virtual outputs are extended with the current offchainTapscript;
             // this is for notification/display only — not for spending.
             // For correct extension metadata, use getVtxos() which queries per-script.
             (async () => {
@@ -610,8 +647,9 @@ export class ReadonlyWallet {
         };
         return stopFunc;
     }
+    /** Fetch Arkade transaction ids that are still pending final settlement. */
     async fetchPendingTxs() {
-        // get non-swept VTXOs, rely on the indexer only in case DB doesn't have the right state
+        // get non-swept virtual outputs, rely on the indexer only in case DB doesn't have the right state
         const scripts = await this.getWalletScripts();
         let { vtxos } = await this.indexerProvider.getVtxos({
             scripts,
@@ -652,7 +690,7 @@ export class ReadonlyWallet {
     }
     /**
      * Build a map of scriptHex → VtxoScript for all wallet contracts,
-     * so VTXOs can be extended with the correct tapscript per contract.
+     * so virtual outputs can be extended with the correct tapscript per contract.
      */
     async getScriptMap() {
         const map = new Map();
@@ -741,7 +779,6 @@ export class ReadonlyWallet {
             indexerProvider: this.indexerProvider,
             contractRepository: this.contractRepository,
             walletRepository: this.walletRepository,
-            getDefaultAddress: () => this.getAddress(),
             watcherConfig: this.watcherConfig,
         });
         // Register the wallet's current address as a contract
@@ -765,7 +802,7 @@ export class ReadonlyWallet {
                 address: await this.getAddress(),
                 state: "active",
             });
-            // Also register the non-delegate version so old VTXOs remain visible
+            // Also register the non-delegate version so old virtual outputs remain visible
             const nonDelegateScript = new DefaultVtxo.Script({
                 pubKey: delegateScript.options.pubKey,
                 serverPubKey: delegateScript.options.serverPubKey,
@@ -803,6 +840,7 @@ export class ReadonlyWallet {
         }
         return manager;
     }
+    /** Dispose wallet-owned managers and release background resources. */
     async dispose() {
         const manager = this._contractManager ??
             (this._contractManagerInitializing
@@ -812,29 +850,30 @@ export class ReadonlyWallet {
         this._contractManager = undefined;
         this._contractManagerInitializing = undefined;
     }
+    /** Async-dispose hook that forwards to `dispose()`. */
     async [Symbol.asyncDispose]() {
         await this.dispose();
     }
 }
 /**
- * Main wallet implementation for Bitcoin transactions with Ark protocol support.
- * The wallet does not store any data locally and relies on Ark and onchain
- * providers to fetch UTXOs and VTXOs.
+ * Main wallet implementation for Bitcoin transactions with Arkade protocol support.
+ * The wallet does not store any data locally and relies on Arkade and onchain
+ * providers to fetch onchain and virtual outputs.
  *
  * @example
  * ```typescript
  * // Create a wallet with URL configuration
  * const wallet = await Wallet.create({
- *   identity: SingleKey.fromHex('your_private_key'),
- *   arkServerUrl: 'https://ark.example.com',
+ *   identity: MnemonicIdentity.fromMnemonic('abandon abandon...'),
+ *   arkServerUrl: 'https://arkade.computer',
  *   esploraUrl: 'https://mempool.space/api'
  * });
  *
  * // Or with custom provider instances (e.g., for Expo/React Native)
  * const wallet = await Wallet.create({
- *   identity: SingleKey.fromHex('your_private_key'),
- *   arkProvider: new ExpoArkProvider('https://ark.example.com'),
- *   indexerProvider: new ExpoIndexerProvider('https://ark.example.com'),
+ *   identity: MnemonicIdentity.fromMnemonic('abandon abandon...'),
+ *   arkProvider: new ExpoArkProvider('https://arkade.computer'),
+ *   indexerProvider: new ExpoIndexerProvider('https://arkade.computer'),
  *   esploraUrl: 'https://mempool.space/api'
  * });
  *
@@ -843,9 +882,9 @@ export class ReadonlyWallet {
  * const boardingAddress = await wallet.getBoardingAddress();
  *
  * // Send bitcoin
- * const txid = await wallet.sendBitcoin({
- *   address: 'tb1...',
- *   amount: 50000
+ * const txid = await wallet.send({
+ *   address: 'ark1q...',
+ *   amount: 50000,
  * });
  * ```
  */
@@ -874,7 +913,7 @@ export class Wallet extends ReadonlyWallet {
         this.forfeitOutputScript = forfeitOutputScript;
         this.forfeitPubkey = forfeitPubkey;
         /**
-         * Async mutex that serializes all operations submitting VTXOs to the Ark
+         * Async mutex that serializes all operations submitting VTXOs to the Arkade
          * server (`settle`, `send`, `sendBitcoin`). This prevents VtxoManager's
          * background renewal from racing with user-initiated transactions for the
          * same VTXO inputs.
@@ -954,6 +993,19 @@ export class Wallet extends ReadonlyWallet {
             await super.dispose();
         }
     }
+    /**
+     * Create a full wallet and initialize its background managers.
+     *
+     * @param config - Wallet configuration
+     * @returns A wallet ready to query balances and send transactions
+     * @example
+     * ```typescript
+     * const wallet = await Wallet.create({
+     *   identity,
+     *   arkServerUrl: 'https://arkade.computer',
+     * });
+     * ```
+     */
     static async create(config) {
         const pubkey = await config.identity.xOnlyPublicKey();
         if (!pubkey) {
@@ -985,7 +1037,7 @@ export class Wallet extends ReadonlyWallet {
      * @returns A readonly wallet with the same configuration but readonly identity
      * @example
      * ```typescript
-     * const wallet = await Wallet.create({ identity: SingleKey.fromHex('...'), ... });
+     * const wallet = await Wallet.create({ identity: MnemonicIdentity.fromMnemonic('abandon abandon...'), ... });
      * const readonlyWallet = await wallet.toReadonly();
      *
      * // Can query balance and addresses
@@ -993,7 +1045,7 @@ export class Wallet extends ReadonlyWallet {
      * const address = await readonlyWallet.getAddress();
      *
      * // But cannot send transactions (type error)
-     * // readonlyWallet.sendBitcoin(...); // TypeScript error
+     * // readonlyWallet.send(...); // TypeScript error
      * ```
      */
     async toReadonly() {
@@ -1003,19 +1055,22 @@ export class Wallet extends ReadonlyWallet {
             : this.identity; // Identity extends ReadonlyIdentity, so this is safe
         return new ReadonlyWallet(readonlyIdentity, this.network, this.onchainProvider, this.indexerProvider, this.arkServerPublicKey, this.offchainTapscript, this.boardingTapscript, this.dustAmount, this.walletRepository, this.contractRepository, this.delegatorProvider, this.watcherConfig);
     }
+    /** Returns the delegator manager when delegation support is configured. */
     async getDelegatorManager() {
         return this._delegatorManager;
     }
     /**
-     * @deprecated Use `send`
-     * @param params
+     * Send bitcoin to an Arkade address.
+     *
+     * @deprecated Use `send`.
+     * @param params - Send parameters
      */
     async sendBitcoin(params) {
         if (params.amount <= 0) {
             throw new Error("Amount must be positive");
         }
         if (!isValidArkAddress(params.address)) {
-            throw new Error("Invalid Ark address " + params.address);
+            throw new Error("Invalid Arkade address " + params.address);
         }
         if (params.selectedVtxos && params.selectedVtxos.length > 0) {
             return this._withTxLock(async () => {
@@ -1060,6 +1115,13 @@ export class Wallet extends ReadonlyWallet {
             amount: params.amount,
         });
     }
+    /**
+     * Settle boarding inputs and/or virtual outputs into a finalized mainnet transaction.
+     *
+     * @param params - Optional settlement inputs and outputs. When omitted, the wallet settles all eligible funds.
+     * @param eventCallback - Optional callback invoked for settlement stream events.
+     * @returns The finalized Arkade transaction id
+     */
     async settle(params, eventCallback) {
         return this._withTxLock(() => this._settleImpl(params, eventCallback));
     }
@@ -1077,7 +1139,7 @@ export class Wallet extends ReadonlyWallet {
                 }
             }
         }
-        // if no params are provided, use all non expired boarding utxos and offchain vtxos as inputs
+        // if no params are provided, use all non-expired boarding inputs and offchain virtual outputs as inputs
         // and send all to the offchain address
         if (!params) {
             const { fees } = await this.arkProvider.getInfo();
@@ -1098,7 +1160,7 @@ export class Wallet extends ReadonlyWallet {
                     amount: BigInt(utxo.value),
                 });
                 if (inputFee.value >= utxo.value) {
-                    // skip if fees are greater than the utxo value
+                    // skip if fees are greater than the boarding input value
                     continue;
                 }
                 filteredBoardingUtxos.push(utxo);
@@ -1119,7 +1181,7 @@ export class Wallet extends ReadonlyWallet {
                         : new Date(),
                 });
                 if (inputFee.value >= vtxo.value) {
-                    // skip if fees are greater than the vtxo value
+                    // skip if fees are greater than the virtual output value
                     continue;
                 }
                 filteredVtxos.push(vtxo);
@@ -1210,7 +1272,7 @@ export class Wallet extends ReadonlyWallet {
             const assetPacket = createAssetPacket(assetInputs, recipients);
             outputs.push(Extension.create([assetPacket]).txOut());
         }
-        // session holds the state of the musig2 signing process of the vtxo tree
+        // session holds the state of the musig2 signing process of the virtual output tree
         let session;
         const signingPublicKeys = [];
         if (hasOffchainOutputs) {
@@ -1261,7 +1323,7 @@ export class Wallet extends ReadonlyWallet {
         for (const input of inputs) {
             // check if the input is an offchain "virtual" coin
             const vtxo = vtxos.find((vtxo) => vtxo.txid === input.txid && vtxo.vout === input.vout);
-            // boarding utxo, we need to sign the settlement tx
+            // boarding input, we need to sign the settlement tx
             if (!vtxo) {
                 for (let i = 0; i < settlementPsbt.inputsLength; i++) {
                     const settlementInput = settlementPsbt.getInput(i);
@@ -1339,11 +1401,12 @@ export class Wallet extends ReadonlyWallet {
         }
     }
     /**
-     * @implements Batch.Handler interface.
+     * Create a batch event handler for settlement flows.
+     *
      * @param intentId - The intent ID.
-     * @param inputs - The inputs of the intent.
-     * @param session - The musig2 signing session, if not provided, the signing will be skipped.
-     * @param expectedRecipients - Expected recipients to validate in the vtxo tree.
+     * @param inputs - Inputs used by the intent.
+     * @param expectedRecipients - Expected recipients to validate in the virtual output tree.
+     * @param session - Optional musig2 signing session. When omitted, signing steps are skipped.
      */
     createBatchHandler(intentId, inputs, expectedRecipients, session) {
         let sweepTapTreeRoot;
@@ -1357,7 +1420,7 @@ export class Wallet extends ReadonlyWallet {
                 for (const idHash of event.intentIdHashes) {
                     if (idHash === intentIdHashStr) {
                         if (!this.arkProvider) {
-                            throw new Error("Ark provider not configured");
+                            throw new Error("Arkade provider not configured");
                         }
                         await this.arkProvider.confirmRegistration(intentId);
                         skip = false;
@@ -1390,10 +1453,10 @@ export class Wallet extends ReadonlyWallet {
                     // not a cosigner, skip the signing
                     return { skip: true };
                 }
-                // validate the unsigned vtxo tree
+                // validate the unsigned virtual output tree
                 const commitmentTx = Transaction.fromPSBT(base64.decode(event.unsignedCommitmentTx));
                 validateVtxoTxGraph(vtxoTree, commitmentTx, sweepTapTreeRoot);
-                // validate that all expected receivers are in the vtxo tree with correct amounts and assets
+                // validate that all expected receivers are in the virtual output tree with correct amounts and assets
                 if (expectedRecipients && expectedRecipients.length > 0) {
                     validateBatchRecipients(commitmentTx, vtxoTree.leaves(), expectedRecipients, this.network);
                 }
@@ -1494,7 +1557,7 @@ export class Wallet extends ReadonlyWallet {
     /**
      * Finalizes pending transactions by retrieving them from the server and finalizing each one.
      * Skips the server check entirely when no send was interrupted (no pending tx flag set).
-     * @param vtxos - Optional list of VTXOs to use instead of retrieving them from the server
+     * @param vtxos - Optional list of virtual outputs to use instead of retrieving them from the server
      * @returns Array of transaction IDs that were finalized
      */
     async finalizePendingTxs(vtxos) {
@@ -1593,13 +1656,13 @@ export class Wallet extends ReadonlyWallet {
     /**
      * Send BTC and/or assets to one or more recipients.
      *
-     * @param recipients - Array of recipients with their addresses, BTC amounts, and assets
-     * @returns Promise resolving to the ark transaction ID
+     * @param args - Recipients with their addresses, BTC amounts, and assets
+     * @returns Promise resolving to the Arkade transaction ID
      *
      * @example
      * ```typescript
      * const txid = await wallet.send({
-     *     address: 'ark1...',
+     *     address: 'ark1q...',
      *     amount: 1000, // (optional, default to dust) btc amount to send to the output
      *     assets: [{ assetId: 'abc123...', amount: 50 }] // (optional) list of assets to send
      * });
@@ -1747,8 +1810,8 @@ export class Wallet extends ReadonlyWallet {
     }
     /**
      * Build an offchain transaction from the given inputs and outputs,
-     * sign it, submit to the ark provider, and finalize.
-     * @returns The ark transaction id and server-signed checkpoint PSBTs (for bookkeeping)
+     * sign it, submit to the Arkade provider, and finalize.
+     * @returns The Arkade transaction id and server-signed checkpoint PSBTs (for bookkeeping)
      */
     async buildAndSubmitOffchainTx(inputs, outputs) {
         const offchainTx = buildOffchainTx(inputs.map((input) => {
@@ -1807,7 +1870,7 @@ export class Wallet extends ReadonlyWallet {
         }
         return { arkTxid, signedCheckpointTxs };
     }
-    // mark vtxo spent and save change vtxo if any
+    // mark virtual outputs as spent, save change outputs if any
     async updateDbAfterOffchainTx(inputs, arkTxid, signedCheckpointTxs, sentAmount, changeAmount, changeVout, changeAssets) {
         try {
             const spentVtxos = [];
@@ -1855,7 +1918,7 @@ export class Wallet extends ReadonlyWallet {
             }
             const createdAt = Date.now();
             const addr = this.arkAddress.encode();
-            // Only save a change VTXO for preconfirmed coins (those with a batchExpiry).
+            // Only save a change virtual output for preconfirmed coins (those with a batchExpiry).
             // Inputs without a batchExpiry are already settled/unrolled and don't need tracking.
             let changeVtxo;
             if (changeAmount > 0n && batchExpiry !== Number.MAX_SAFE_INTEGER) {
@@ -1899,7 +1962,7 @@ export class Wallet extends ReadonlyWallet {
             console.warn("error saving offchain tx to repository", e);
         }
     }
-    // mark vtxo spent & settled, remove boarding utxo
+    // mark virtual outputs as spent/settled, remove boarding inputs
     async updateDbAfterSettle(inputs, commitmentTxid) {
         try {
             const addr = this.arkAddress.encode();
@@ -1910,7 +1973,7 @@ export class Wallet extends ReadonlyWallet {
             const isVtxo = (input) => "virtualStatus" in input;
             for (const input of inputs) {
                 if (isVtxo(input)) {
-                    // vtxo = mark it settled
+                    // virtual output = mark it settled
                     const vtxo = extendVirtualCoin(this, input);
                     if (vtxo.arkTxId) {
                         inputArkTxIds.add(vtxo.arkTxId);
@@ -1926,7 +1989,7 @@ export class Wallet extends ReadonlyWallet {
                     });
                 }
                 else {
-                    // boarding utxo = remove it
+                    // boarding input = remove it
                     boardingUtxoToRemove.add(`${input.txid}:${input.vout}`);
                 }
             }
@@ -1950,13 +2013,13 @@ export class Wallet extends ReadonlyWallet {
 }
 Wallet.MIN_FEE_RATE = 1; // sats/vbyte
 /**
- * Select virtual coins to reach a target amount, prioritizing those closer to expiry
- * @param coins List of virtual coins to select from
+ * Select virtual outputs to reach a target amount, prioritizing those closer to expiry
+ * @param coins List of virtual outputs to select from
  * @param targetAmount Target amount to reach in satoshis
- * @returns Selected coins and change amount
+ * @returns Selected virtual outputs and change amount
  */
 export function selectVirtualCoins(coins, targetAmount) {
-    // Sort VTXOs by expiry (ascending) and amount (descending)
+    // Sort virtual outputs by expiry (ascending) and amount (descending)
     const sortedCoins = [...coins].sort((a, b) => {
         // First sort by expiry if available
         const expiryA = a.virtualStatus.batchExpiry || Number.MAX_SAFE_INTEGER;

package/dist/esm/worker/expo/asyncStorageTaskQueue.js

@@ -49,7 +49,7 @@ export class AsyncStorageTaskQueue {
     // ── Config persistence (for background handler rehydration) ──────
     /**
      * Persist a config blob alongside the queue data.
-     * Used by {@link ExpoWallet.setup} to store the wallet parameters
+     * Used by @see ExpoWallet.setup to store the wallet parameters
      * that the background handler needs to reconstruct providers.
      */
     async persistConfig(config) {

package/dist/esm/worker/expo/processors/contractPollProcessor.js

@@ -3,7 +3,7 @@ export const CONTRACT_POLL_TASK_TYPE = "contract-poll";
  * Polls the indexer for the latest VTXO state of every contract and
  * persists the results to the wallet repository.
  *
- * Replicates the polling subset of {@link ContractManager.initialize}:
+ * Replicates the polling subset of @see ContractManager.initialize:
  * 1. Load all contracts from the contract repository.
  * 2. Mark expired active contracts as inactive.
  * 3. Paginated fetch of spendable VTXOs from the indexer.
@@ -26,7 +26,7 @@ export const contractPollProcessor = {
                 contract.state = "inactive";
                 await contractRepository.saveContract(contract);
             }
-            // Paginated fetch of spendable VTXOs
+            // Paginated fetch of spendable virtual outputs
             const pageSize = 100;
             let pageIndex = 0;
             let hasMore = true;

package/dist/esm/worker/expo/taskRunner.js

@@ -4,7 +4,7 @@ import { getRandomId, extendVirtualCoin, extendVtxoFromContract, } from '../../w
  *
  * For each task in the inbox:
  * 1. Find the processor whose `taskType` matches `task.type`.
- * 2. Execute it, producing a {@link TaskResult}.
+ * 2. Execute it, producing a @see TaskResult.
  * 3. Push the result to the outbox and remove the task from the inbox.
  *
  * Tasks with no matching processor produce a `"noop"` result.
@@ -53,8 +53,8 @@ export async function runTasks(queue, processors, deps) {
     return results;
 }
 /**
- * Build the {@link TaskDependencies} needed by task processors
- * (e.g. {@link import("./processors").contractPollProcessor}).
+ * Build the @see TaskDependencies needed by task processors
+ * (e.g. `src/worker/expo/processors/contractPollProcessor.ts`)
  *
  * This is the same construction that `defineExpoBackgroundTask` does
  * internally, extracted so that consumers with custom schedulers