@arkade-os/sdk 0.4.14 → 0.4.16

package/dist/cjs/wallet/wallet.js

@@ -15,6 +15,7 @@ const ark_1 = require("../providers/ark");
 const forfeit_1 = require("../forfeit");
 const validation_1 = require("../tree/validation");
 const validation_2 = require("./validation");
+const identity_1 = require("../identity");
 const _1 = require(".");
 const asset_1 = require("./asset");
 const base_2 = require("../script/base");
@@ -112,12 +113,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).`);
             }
         }
@@ -189,6 +190,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) {
@@ -207,12 +214,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(),
@@ -244,7 +256,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))
@@ -274,11 +286,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.
+        // Virtual outputs that weren't in the delta are still returned.
         const vtxos = isDelta
             ? await this.walletRepository.getVtxos(address)
             : fetchedExtended;
@@ -293,8 +310,11 @@ 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)
@@ -306,7 +326,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.
      *
@@ -345,6 +365,19 @@ class ReadonlyWallet {
         }
         const requestStartedAt = Date.now();
         const allVtxos = [];
+        const extendWithScript = (vtxo) => {
+            const vtxoScript = vtxo.script
+                ? scriptMap.get(vtxo.script)
+                : undefined;
+            if (!vtxoScript)
+                return undefined;
+            return {
+                ...vtxo,
+                forfeitTapLeafScript: vtxoScript.forfeit(),
+                intentTapLeafScript: vtxoScript.forfeit(),
+                tapTree: vtxoScript.encode(),
+            };
+        };
         // Full fetch for scripts with no cursor.
         if (bootstrapScripts.length > 0) {
             const response = await this.indexerProvider.getVtxos({
@@ -366,49 +399,79 @@ 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 vtxoScript = vtxo.script
-                ? scriptMap.get(vtxo.script)
-                : undefined;
-            if (!vtxoScript)
-                continue;
-            fetchedExtended.push({
-                ...vtxo,
-                forfeitTapLeafScript: vtxoScript.forfeit(),
-                intentTapLeafScript: vtxoScript.forfeit(),
-                tapTree: vtxoScript.encode(),
-            });
+            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])));
-        // For delta syncs, reconcile pending (preconfirmed/spent) VTXOs
-        // whose state may have changed since the cursor so that
-        // getVtxos()/getTransactionHistory() don't serve stale state.
+        // Delta-sync reconciliation: full re-fetch for delta scripts.
+        //
+        // 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
+        // delta scripts.  This is slightly more data over the wire but
+        // gives us complete, authoritative state in one call and keeps
+        // the reconciliation logic simple.
+        //
+        // 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: pendingVtxos } = await this.indexerProvider.getVtxos({
+            const { vtxos: fullVtxos, page: fullPage } = await this.indexerProvider.getVtxos({
                 scripts: deltaScripts,
-                pendingOnly: true,
             });
-            const pendingExtended = [];
-            for (const vtxo of pendingVtxos) {
-                const vtxoScript = vtxo.script
-                    ? scriptMap.get(vtxo.script)
-                    : undefined;
-                if (!vtxoScript)
-                    continue;
-                pendingExtended.push({
-                    ...vtxo,
-                    forfeitTapLeafScript: vtxoScript.forfeit(),
-                    intentTapLeafScript: vtxoScript.forfeit(),
-                    tapTree: vtxoScript.encode(),
-                });
+            // 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
+            // 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) {
+                const fullOutpoints = new Map(fullVtxos.map((v) => [`${v.txid}:${v.vout}`, v]));
+                const deltaScriptSet = new Set(deltaScripts);
+                const cachedVtxos = await this.walletRepository.getVtxos(address);
+                const reconciledExtended = [];
+                for (const cached of cachedVtxos) {
+                    if (!cached.script ||
+                        !deltaScriptSet.has(cached.script) ||
+                        cached.isSpent) {
+                        continue;
+                    }
+                    const outpoint = `${cached.txid}:${cached.vout}`;
+                    const fresh = fullOutpoints.get(outpoint);
+                    if (!fresh) {
+                        // Server no longer knows about this virtual output —
+                        // it was spent between syncs.
+                        reconciledExtended.push({
+                            ...cached,
+                            isSpent: true,
+                        });
+                        continue;
+                    }
+                    const extended = extendWithScript(fresh);
+                    if (extended &&
+                        extended.virtualStatus.state !==
+                            cached.virtualStatus.state) {
+                        // State transitioned (e.g. preconfirmed →
+                        // settled) — update the cached entry.
+                        reconciledExtended.push(extended);
+                    }
+                }
+                if (reconciledExtended.length > 0) {
+                    console.warn(`[ark-sdk] delta sync: reconciled ${reconciledExtended.length} stale VTXO(s) via full re-fetch`);
+                    await this.walletRepository.saveVtxos(address, reconciledExtended);
+                }
             }
-            if (pendingExtended.length > 0) {
-                await this.walletRepository.saveVtxos(address, pendingExtended);
+            else {
+                console.warn("[ark-sdk] delta sync: skipping reconciliation — full re-fetch was paginated");
             }
         }
         return {
@@ -418,12 +481,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();
@@ -494,16 +560,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();
@@ -514,11 +589,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);
@@ -543,8 +618,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 () => {
@@ -571,8 +646,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,
@@ -613,7 +689,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();
@@ -726,7 +802,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,
@@ -764,6 +840,7 @@ class ReadonlyWallet {
         }
         return manager;
     }
+    /** Dispose wallet-owned managers and release background resources. */
     async dispose() {
         const manager = this._contractManager ??
             (this._contractManagerInitializing
@@ -773,30 +850,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'
  * });
  *
@@ -805,9 +883,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,
  * });
  * ```
  */
@@ -836,7 +914,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.
@@ -916,6 +994,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) {
@@ -947,7 +1038,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
@@ -955,7 +1046,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() {
@@ -965,19 +1056,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 () => {
@@ -1022,6 +1116,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));
     }
@@ -1039,7 +1140,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();
@@ -1060,7 +1161,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);
@@ -1081,7 +1182,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);
@@ -1172,7 +1273,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) {
@@ -1223,7 +1324,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);
@@ -1301,11 +1402,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;
@@ -1319,7 +1421,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;
@@ -1352,10 +1454,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);
                 }
@@ -1456,7 +1558,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) {
@@ -1555,13 +1657,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
      * });
@@ -1709,8 +1811,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) => {
@@ -1719,16 +1821,47 @@ class Wallet extends ReadonlyWallet {
                 tapLeafScript: input.forfeitTapLeafScript,
             };
         }), outputs, this.serverUnrollScript);
-        const signedVirtualTx = await this.identity.sign(offchainTx.arkTx);
+        let signedVirtualTx;
+        let userSignedCheckpoints;
+        if ((0, identity_1.isBatchSignable)(this.identity)) {
+            // Batch-sign arkTx + all checkpoints in one wallet popup.
+            // Clone so the provider can't mutate originals before submitTx.
+            const requests = [
+                { tx: offchainTx.arkTx.clone() },
+                ...offchainTx.checkpoints.map((c) => ({ tx: c.clone() })),
+            ];
+            const signed = await this.identity.signMultiple(requests);
+            if (signed.length !== requests.length) {
+                throw new Error(`signMultiple returned ${signed.length} transactions, expected ${requests.length}`);
+            }
+            const [firstSignedTx, ...signedCheckpoints] = signed;
+            signedVirtualTx = firstSignedTx;
+            userSignedCheckpoints = signedCheckpoints;
+        }
+        else {
+            signedVirtualTx = await this.identity.sign(offchainTx.arkTx);
+        }
         // Mark pending before submitting — if we crash between submit and
         // finalize, the next init will recover via finalizePendingTxs.
         await this.setPendingTxFlag(true);
         const { arkTxid, signedCheckpointTxs } = await this.arkProvider.submitTx(base_1.base64.encode(signedVirtualTx.toPSBT()), offchainTx.checkpoints.map((c) => base_1.base64.encode(c.toPSBT())));
-        const finalCheckpoints = await Promise.all(signedCheckpointTxs.map(async (c) => {
-            const tx = btc_signer_1.Transaction.fromPSBT(base_1.base64.decode(c));
-            const signedCheckpoint = await this.identity.sign(tx);
-            return base_1.base64.encode(signedCheckpoint.toPSBT());
-        }));
+        let finalCheckpoints;
+        if (userSignedCheckpoints) {
+            // Merge pre-signed user signatures onto server-signed checkpoints
+            finalCheckpoints = signedCheckpointTxs.map((c, i) => {
+                const serverSigned = btc_signer_1.Transaction.fromPSBT(base_1.base64.decode(c));
+                (0, arkTransaction_1.combineTapscriptSigs)(userSignedCheckpoints[i], serverSigned);
+                return base_1.base64.encode(serverSigned.toPSBT());
+            });
+        }
+        else {
+            // Legacy: sign each checkpoint individually (N popups)
+            finalCheckpoints = await Promise.all(signedCheckpointTxs.map(async (c) => {
+                const tx = btc_signer_1.Transaction.fromPSBT(base_1.base64.decode(c));
+                const signedCheckpoint = await this.identity.sign(tx);
+                return base_1.base64.encode(signedCheckpoint.toPSBT());
+            }));
+        }
         await this.arkProvider.finalizeTx(arkTxid, finalCheckpoints);
         try {
             await this.setPendingTxFlag(false);
@@ -1738,7 +1871,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 = [];
@@ -1786,7 +1919,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) {
@@ -1830,7 +1963,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();
@@ -1841,7 +1974,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);
@@ -1857,7 +1990,7 @@ class Wallet extends ReadonlyWallet {
                     });
                 }
                 else {
-                    // boarding utxo = remove it
+                    // boarding input = remove it
                     boardingUtxoToRemove.add(`${input.txid}:${input.vout}`);
                 }
             }
@@ -1882,13 +2015,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;