@arkade-os/sdk 0.4.15 → 0.4.17

package/dist/cjs/wallet/wallet.js

@@ -39,6 +39,10 @@ const contractManager_1 = require("../contracts/contractManager");
 const handlers_1 = require("../contracts/handlers");
 const helpers_1 = require("../contracts/handlers/helpers");
 const syncCursors_1 = require("../utils/syncCursors");
+// 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.
  */
@@ -113,12 +117,12 @@ 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).`);
             }
         }
@@ -134,10 +138,16 @@ 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) {
@@ -190,6 +200,12 @@ 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) {
@@ -208,12 +224,17 @@ class ReadonlyWallet {
     get defaultContractScript() {
         return base_1.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(),
@@ -245,7 +266,7 @@ 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 (!(0, _1.isSpendable)(vtxo))
@@ -275,15 +296,16 @@ 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 ((0, _1.isSpendable)(vtxo)) {
                 if (!f.withRecoverable &&
                     ((0, _1.isRecoverable)(vtxo) || (0, _1.isExpired)(vtxo))) {
@@ -292,10 +314,13 @@ 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)
@@ -307,7 +332,7 @@ class ReadonlyWallet {
         return (0, transactionHistory_1.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.
      *
@@ -380,21 +405,21 @@ 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 = (0, syncCursors_1.cursorCutoff)(requestStartedAt);
         await this.walletRepository.saveVtxos(address, fetchedExtended);
         await (0, syncCursors_1.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
@@ -402,8 +427,8 @@ 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({
@@ -412,7 +437,7 @@ 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) {
@@ -429,7 +454,7 @@ 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,
@@ -462,12 +487,15 @@ 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 (0, syncCursors_1.clearSyncCursors)(this.walletRepository);
     }
+    /**
+     * Build a transaction history view for the wallet's boarding address.
+     */
     async getBoardingTxs() {
         const utxos = [];
         const commitmentsToIgnore = new Set();
@@ -538,16 +566,25 @@ 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 (0, utils_1.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();
@@ -558,11 +595,11 @@ 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);
@@ -587,8 +624,8 @@ 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 () => {
@@ -615,8 +652,9 @@ 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,
@@ -657,7 +695,7 @@ 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();
@@ -746,7 +784,6 @@ 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
@@ -770,7 +807,7 @@ 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 default_1.DefaultVtxo.Script({
                 pubKey: delegateScript.options.pubKey,
                 serverPubKey: delegateScript.options.serverPubKey,
@@ -808,6 +845,7 @@ class ReadonlyWallet {
         }
         return manager;
     }
+    /** Dispose wallet-owned managers and release background resources. */
     async dispose() {
         const manager = this._contractManager ??
             (this._contractManagerInitializing
@@ -817,30 +855,31 @@ class ReadonlyWallet {
         this._contractManager = undefined;
         this._contractManagerInitializing = undefined;
     }
+    /** Async-dispose hook that forwards to `dispose()`. */
     async [Symbol.asyncDispose]() {
         await this.dispose();
     }
 }
 exports.ReadonlyWallet = ReadonlyWallet;
 /**
- * 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'
  * });
  *
@@ -849,9 +888,9 @@ exports.ReadonlyWallet = 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,
  * });
  * ```
  */
@@ -880,7 +919,7 @@ 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.
@@ -960,6 +999,19 @@ 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) {
@@ -991,7 +1043,7 @@ 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
@@ -999,7 +1051,7 @@ 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() {
@@ -1009,19 +1061,22 @@ 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 (!(0, arkTransaction_1.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 () => {
@@ -1066,6 +1121,13 @@ 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));
     }
@@ -1083,7 +1145,7 @@ 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();
@@ -1104,7 +1166,7 @@ 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);
@@ -1125,7 +1187,7 @@ 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);
@@ -1216,7 +1278,7 @@ class Wallet extends ReadonlyWallet {
             const assetPacket = (0, asset_1.createAssetPacket)(assetInputs, recipients);
             outputs.push(extension_1.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) {
@@ -1267,7 +1329,7 @@ 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);
@@ -1345,11 +1407,12 @@ 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;
@@ -1363,7 +1426,7 @@ 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;
@@ -1396,10 +1459,10 @@ 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 = btc_signer_1.Transaction.fromPSBT(base_1.base64.decode(event.unsignedCommitmentTx));
                 (0, validation_1.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) {
                     (0, validation_2.validateBatchRecipients)(commitmentTx, vtxoTree.leaves(), expectedRecipients, this.network);
                 }
@@ -1500,7 +1563,7 @@ 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) {
@@ -1599,13 +1662,13 @@ 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
      * });
@@ -1753,8 +1816,8 @@ 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 = (0, arkTransaction_1.buildOffchainTx)(inputs.map((input) => {
@@ -1813,7 +1876,7 @@ 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 = [];
@@ -1861,7 +1924,7 @@ 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) {
@@ -1905,7 +1968,7 @@ 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();
@@ -1916,7 +1979,7 @@ 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 = (0, utils_1.extendVirtualCoin)(this, input);
                     if (vtxo.arkTxId) {
                         inputArkTxIds.add(vtxo.arkTxId);
@@ -1932,7 +1995,7 @@ class Wallet extends ReadonlyWallet {
                     });
                 }
                 else {
-                    // boarding utxo = remove it
+                    // boarding input = remove it
                     boardingUtxoToRemove.add(`${input.txid}:${input.vout}`);
                 }
             }
@@ -1957,13 +2020,13 @@ class Wallet extends ReadonlyWallet {
 exports.Wallet = Wallet;
 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
  */
 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/cjs/worker/expo/asyncStorageTaskQueue.js

@@ -52,7 +52,7 @@ 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/cjs/worker/expo/processors/contractPollProcessor.js

@@ -6,7 +6,7 @@ exports.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.
@@ -29,7 +29,7 @@ exports.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/cjs/worker/expo/taskRunner.js

@@ -8,7 +8,7 @@ const utils_1 = require("../../wallet/utils");
  *
  * 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.
@@ -57,8 +57,8 @@ 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