@arkade-os/sdk 0.4.15 → 0.4.16

package/dist/esm/wallet/wallet.js

@@ -108,12 +108,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).`);
             }
         }
@@ -185,6 +185,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 +209,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 +251,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,11 +281,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.
+        // Virtual outputs that weren't in the delta are still returned.
         const vtxos = isDelta
             ? await this.walletRepository.getVtxos(address)
             : fetchedExtended;
@@ -289,8 +305,11 @@ export class ReadonlyWallet {
             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 +321,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 +394,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 +416,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 +426,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 +443,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 +476,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 +555,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 +584,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 +613,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 +641,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 +684,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();
@@ -765,7 +797,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 +835,7 @@ export class ReadonlyWallet {
         }
         return manager;
     }
+    /** Dispose wallet-owned managers and release background resources. */
     async dispose() {
         const manager = this._contractManager ??
             (this._contractManagerInitializing
@@ -812,29 +845,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 +877,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 +908,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 +988,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 +1032,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 +1040,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 +1050,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 +1110,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 +1134,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 +1155,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 +1176,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 +1267,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 +1318,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 +1396,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 +1415,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 +1448,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 +1552,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 +1651,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 +1805,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 +1865,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 +1913,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 +1957,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 +1968,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 +1984,7 @@ export class Wallet extends ReadonlyWallet {
                     });
                 }
                 else {
-                    // boarding utxo = remove it
+                    // boarding input = remove it
                     boardingUtxoToRemove.add(`${input.txid}:${input.vout}`);
                 }
             }
@@ -1950,13 +2008,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

package/dist/esm/worker/messageBus.js

@@ -7,6 +7,7 @@ import { ReadonlyWallet, Wallet } from '../wallet/wallet.js';
 import { hex } from "@scure/base";
 import { MessageBusNotInitializedError, ServiceWorkerTimeoutError, } from './errors.js';
 export class MessageBus {
+    /** Create the service-worker message bus with repositories and handler configuration. */
     constructor(walletRepository, contractRepository, { messageHandlers, tickIntervalMs = 10000, messageTimeoutMs = 30000, debug = false, buildServices, }) {
         this.walletRepository = walletRepository;
         this.contractRepository = contractRepository;
@@ -22,6 +23,7 @@ export class MessageBus {
         this.debug = debug;
         this.buildServicesFn = buildServices ?? this.buildServices.bind(this);
     }
+    /** Start the message bus and attach service-worker event listeners. */
     async start() {
         if (this.running)
             return;
@@ -42,6 +44,7 @@ export class MessageBus {
             }
         });
     }
+    /** Stop the message bus, cancel ticks, and stop all registered handlers. */
     async stop() {
         if (this.debug)
             console.log("MessageBus stopping");

package/dist/types/arkfee/estimator.d.ts

@@ -1,6 +1,6 @@
 import { IntentFeeConfig, OffchainInput, OnchainInput, FeeOutput, FeeAmount } from "./types.js";
 /**
- * Estimator evaluates CEL expressions to calculate fees for Ark intents
+ * Estimator evaluates CEL expressions to calculate fees for Arkade intents
  */
 export declare class Estimator {
     readonly config: IntentFeeConfig;