@pioneer-platform/blockbook 8.12.0 → 8.12.2

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @pioneer-platform/blockbook
 
+## 8.12.2
+
+### Patch Changes
+
+- chore: 🔒 CRITICAL FIX: XRP destination tag validation
+
+## 8.12.1
+
+### Patch Changes
+
+- 🔒 CRITICAL FIX: XRP destination tag validation
+
 ## 8.12.0
 
 ### Minor Changes

package/UNCONFIRMED_BALANCE_FIX.md

@@ -0,0 +1,142 @@
+# ✅ Critical Fix: Unconfirmed Balance Support
+
+## Problem
+
+**CRITICAL UX BUG**: When a user had pending/unconfirmed Bitcoin transactions, the system would show **0 balance** instead of showing the unconfirmed balance. This made users think all their Bitcoin had disappeared!
+
+### Root Cause
+
+The `get_balance_by_xpub()` function in `utxo-network` only summed confirmed UTXOs from the `/api/v2/utxo/{xpub}` endpoint. When UTXOs were spent in an unconfirmed transaction:
+
+- ✅ Confirmed UTXOs: spent (returns empty array)
+- ❌ Unconfirmed balance: **NOT CHECKED** (showed as $0.00)
+
+Result: **User sees 0 balance even though they have pending transactions!**
+
+## Solution
+
+### 1. Backend Fix (`utxo-network/src/index.ts`)
+
+Added unconfirmed balance check to `get_balance_by_xpub`:
+
+```typescript
+// CRITICAL FIX: Also get unconfirmed balance from xpub info
+// When UTXOs are spent but not confirmed, balance would show 0 without this
+let unconfirmedBalance = 0;
+try {
+    const xpubInfo = await blockbook.getPubkeyInfo(coin, xpub);
+    unconfirmedBalance = parseInt(xpubInfo.unconfirmedBalance || '0');
+    
+    if (isBitcoin) log.info(tag, '🔍 [BITCOIN] Xpub info:', {
+        confirmedBalance: xpubInfo.balance,
+        unconfirmedBalance: xpubInfo.unconfirmedBalance,
+        totalReceived: xpubInfo.totalReceived,
+        totalSent: xpubInfo.totalSent,
+        txCount: xpubInfo.txs
+    });
+} catch (e) {
+    log.warn(tag, 'Failed to fetch xpub info for unconfirmed balance:', e);
+    // Continue with just confirmed balance
+}
+
+const totalBalance = balance + unconfirmedBalance;
+
+// Return balance, unconfirmed balance, and node URL
+return { 
+    balance: totalBalance, 
+    unconfirmedBalance, 
+    confirmedBalance: balance, 
+    nodeUrl 
+}
+```
+
+### 2. API Controller Fix (`pioneer-server/src/controllers/utxo.controller.ts`)
+
+Updated `GetBalanceByXpub` to return balance breakdown:
+
+```typescript
+public async GetBalanceByXpub(
+    @Path() network: string,
+    @Path() xpub: string
+): Promise<{ 
+    balance: string; 
+    unconfirmedBalance?: number; 
+    confirmedBalance?: number; 
+    nodeUrl?: string 
+} | BasicResponse> {
+    const balanceInfo = await utxoNetwork.getBalanceByXpub(network, xpub);
+    
+    return {
+        balance: balanceInfo.balance.toString(),
+        unconfirmedBalance: balanceInfo.unconfirmedBalance || 0,
+        confirmedBalance: balanceInfo.confirmedBalance || balanceInfo.balance,
+        nodeUrl: balanceInfo.nodeUrl
+    };
+}
+```
+
+## API Response Format
+
+### Before (Broken)
+```json
+{
+  "balance": "0"  ← Shows 0 even with unconfirmed transactions!
+}
+```
+
+### After (Fixed)
+```json
+{
+  "balance": "74953",           ← Total balance (confirmed + unconfirmed)
+  "confirmedBalance": 0,        ← Confirmed balance
+  "unconfirmedBalance": 74953,  ← Unconfirmed balance (pending TX)
+  "nodeUrl": "https://btcbook.nownodes.io/..."
+}
+```
+
+## Testing
+
+### Test Case: Pending Transaction
+
+```bash
+# Wallet with pending transaction
+curl "http://localhost:9001/api/v1/utxo/balance/BTC/{zpub}"
+
+# Expected: Shows unconfirmed balance
+{
+  "balance": "74953",
+  "confirmedBalance": 0,
+  "unconfirmedBalance": 74953
+}
+```
+
+### Test Case: Fully Confirmed Balance
+
+```bash
+# Wallet with confirmed balance
+curl "http://localhost:9001/api/v1/utxo/balance/BTC/{zpub}"
+
+# Expected: Shows confirmed balance only  
+{
+  "balance": "74953",
+  "confirmedBalance": 74953,
+  "unconfirmedBalance": 0
+}
+```
+
+## Files Changed
+
+1. `modules/coins/utxo/utxo-network/src/index.ts` - Added unconfirmed balance query
+2. `services/pioneer-server/src/controllers/utxo.controller.ts` - Updated response format
+
+## Impact
+
+✅ **Users will no longer panic when they see $0.00 balance during pending transactions**  
+✅ **UI can now show "Pending: X BTC" separately from confirmed balance**  
+✅ **Proper debugging with detailed balance breakdown in logs**
+
+## Related
+
+- Blockbook API: `/api/v2/xpub/{xpub}` returns `unconfirmedBalance` field
+- Blockbook API: `/api/v2/utxo/{xpub}?confirmed=false` returns unconfirmed UTXOs (but is empty when spent)
+

package/lib/index.d.ts

@@ -50,7 +50,13 @@ declare let broadcast_transaction: (coin: string, hex: string) => Promise<{
     txid?: undefined;
 }>;
 declare let get_transaction: (coin: string, txid: string) => Promise<any>;
-declare let get_utxos_by_xpub: (coin: string, xpub: string) => Promise<any>;
+declare let get_utxos_by_xpub: (coin: string, xpub: string) => Promise<{
+    data: any;
+    nodeUrl: string;
+} | undefined>;
 declare let update_node_performance: (coin: string, url: string, success: boolean, responseTime: number) => void;
-declare let get_balance_by_xpub: (coin: string, xpub: any) => Promise<number>;
+declare let get_balance_by_xpub: (coin: string, xpub: any) => Promise<{
+    balance: number;
+    nodeUrl: string;
+}>;
 declare let get_node_info: () => Promise<boolean>;

package/lib/index.js

@@ -757,7 +757,8 @@ var get_utxos_by_xpub = function (coin, xpub) {
                     if (isBitcoin) {
                         log.info(tag, '🔍 [BITCOIN BLOCKBOOK] Returning UTXOs:', resp.data);
                     }
-                    return [2 /*return*/, resp.data];
+                    // Return both data and the node URL that was used
+                    return [2 /*return*/, { data: resp.data, nodeUrl: node.url }];
                 case 5:
                     error_2 = _b.sent();
                     responseTime = Date.now() - startTime;
@@ -843,7 +844,7 @@ var update_node_performance = function (coin, url, success, responseTime) {
 };
 var get_balance_by_xpub = function (coin, xpub) {
     return __awaiter(this, void 0, void 0, function () {
-        var tag, output, balance, i, uxto, e_10;
+        var tag, result, output, nodeUrl, balance, i, uxto, e_10;
         return __generator(this, function (_a) {
             switch (_a.label) {
                 case 0:
@@ -855,7 +856,12 @@ var get_balance_by_xpub = function (coin, xpub) {
                     log.debug(tag, "xpub: ", xpub);
                     return [4 /*yield*/, get_utxos_by_xpub(coin, xpub)];
                 case 2:
-                    output = _a.sent();
+                    result = _a.sent();
+                    if (!result) {
+                        throw new Error('No result from get_utxos_by_xpub');
+                    }
+                    output = result.data;
+                    nodeUrl = result.nodeUrl;
                     log.debug(tag, "output: ", output);
                     balance = 0;
                     //tally
@@ -863,7 +869,8 @@ var get_balance_by_xpub = function (coin, xpub) {
                         uxto = output[i];
                         balance = balance + parseInt(uxto.value);
                     }
-                    return [2 /*return*/, balance / 100000000];
+                    // Return both balance and node URL
+                    return [2 /*return*/, { balance: balance / 100000000, nodeUrl: nodeUrl }];
                 case 3:
                     e_10 = _a.sent();
                     console.error(tag, e_10);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pioneer-platform/blockbook",
-  "version": "8.12.0",
+  "version": "8.12.2",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
   "scripts": {