@breeztech/breez-sdk-spark 0.27.0-dev1 → 0.27.0

package/nodejs/storage/index.cjs

@@ -27,6 +27,14 @@ try {
 const { StorageError } = require("./errors.cjs");
 const { MigrationManager } = require("./migrations.cjs");
 
+// JSON has no BigInt, so u128 amounts are stored as decimal strings, which the
+// SDK reads back as BigInts.
+function toJson(value) {
+  return JSON.stringify(value, (_key, v) =>
+    typeof v === "bigint" ? v.toString() : v
+  );
+}
+
 /**
  * Base query for payment lookups.
  * All columns are accessed by name in _rowToPayment.
@@ -329,7 +337,7 @@ class SqliteStorage {
     } catch (error) {
       return Promise.reject(
         new StorageError(
-          `Failed to list payments (request: ${JSON.stringify(request)}: ${
+          `Failed to list payments (request: ${toJson(request)}: ${
             error.message
           }`,
           error
@@ -446,7 +454,7 @@ class SqliteStorage {
       amount: payment.amount.toString(),
       fees: payment.fees.toString(),
       timestamp: payment.timestamp,
-      method: payment.method ? JSON.stringify(payment.method) : null,
+      method: payment.method ? toJson(payment.method) : null,
       withdrawTxId:
         payment.details?.type === "withdraw" ? payment.details.txId : null,
       spark: payment.details?.type === "spark" ? 1 : null,
@@ -468,10 +476,10 @@ class SqliteStorage {
       sparkInsert.run({
         id: payment.id,
         invoiceDetails: payment.details.invoiceDetails
-          ? JSON.stringify(payment.details.invoiceDetails)
+          ? toJson(payment.details.invoiceDetails)
           : null,
         htlcDetails: payment.details.htlcDetails
-          ? JSON.stringify(payment.details.htlcDetails)
+          ? toJson(payment.details.htlcDetails)
           : null,
       });
     }
@@ -492,11 +500,11 @@ class SqliteStorage {
     if (payment.details?.type === "token") {
       tokenInsert.run({
         id: payment.id,
-        metadata: JSON.stringify(payment.details.metadata),
+        metadata: toJson(payment.details.metadata),
         txHash: payment.details.txHash,
         txType: payment.details.txType,
         invoiceDetails: payment.details.invoiceDetails
-          ? JSON.stringify(payment.details.invoiceDetails)
+          ? toJson(payment.details.invoiceDetails)
           : null,
       });
     }
@@ -560,7 +568,6 @@ class SqliteStorage {
       return Promise.resolve(this._rowToPayment(row));
     } catch (error) {
       if (error instanceof StorageError) return Promise.reject(error);
-      const paymentId = id || "unknown";
       return Promise.reject(
         new StorageError(
           `Failed to get payment by invoice '${invoice}': ${error.message}`,
@@ -636,13 +643,13 @@ class SqliteStorage {
       stmt.run(
         paymentId,
         metadata.parentPaymentId,
-        metadata.lnurlPayInfo ? JSON.stringify(metadata.lnurlPayInfo) : null,
+        metadata.lnurlPayInfo ? toJson(metadata.lnurlPayInfo) : null,
         metadata.lnurlWithdrawInfo
-          ? JSON.stringify(metadata.lnurlWithdrawInfo)
+          ? toJson(metadata.lnurlWithdrawInfo)
           : null,
         metadata.lnurlDescription,
         metadata.conversionInfo
-          ? JSON.stringify(metadata.conversionInfo)
+          ? toJson(metadata.conversionInfo)
           : null,
         metadata.conversionStatus ?? null
       );
@@ -739,7 +746,7 @@ class SqliteStorage {
           WHERE txid = ? AND vout = ?
         `);
 
-        stmt.run(JSON.stringify(payload.error), txid, vout);
+        stmt.run(toJson(payload.error), txid, vout);
       } else if (payload.type === "refund") {
         const stmt = this.db.prepare(`
           UPDATE unclaimed_deposits
@@ -750,7 +757,7 @@ class SqliteStorage {
         stmt.run(
           payload.refundTx,
           payload.refundTxid,
-          JSON.stringify(payload.state),
+          toJson(payload.state),
           txid,
           vout
         );
@@ -761,7 +768,7 @@ class SqliteStorage {
           WHERE txid = ? AND vout = ?
         `);
 
-        stmt.run(JSON.stringify(payload.status), txid, vout);
+        stmt.run(toJson(payload.status), txid, vout);
       } else if (payload.type === "refundBroadcastState") {
         const stmt = this.db.prepare(`
           UPDATE unclaimed_deposits
@@ -769,7 +776,7 @@ class SqliteStorage {
           WHERE txid = ? AND vout = ? AND refund_tx_id = ?
         `);
 
-        stmt.run(JSON.stringify(payload.state), txid, vout, payload.refundTxid);
+        stmt.run(toJson(payload.state), txid, vout, payload.refundTxid);
       } else if (payload.type === "maxClaimFee") {
         const stmt = this.db.prepare(`
           UPDATE unclaimed_deposits
@@ -778,7 +785,7 @@ class SqliteStorage {
         `);
 
         stmt.run(
-          payload.maxFee ? JSON.stringify(payload.maxFee) : null,
+          payload.maxFee ? toJson(payload.maxFee) : null,
           txid,
           vout
         );
@@ -864,6 +871,147 @@ class SqliteStorage {
     }
   }
 
+  listLeafRecoveries() {
+    try {
+      const rows = this.db
+        .prepare(
+          `SELECT l.leaf_id,
+                  l.chain_checked_at,
+                  o.txid AS output_txid,
+                  o.vout AS output_vout,
+                  o.amount_sats AS output_amount_sats,
+                  o.script_pubkey AS output_script_pubkey,
+                  ot.block_height AS output_block_height,
+                  s.txid AS spend_txid,
+                  st.block_height AS spend_block_height,
+                  w.txid AS sweep_txid,
+                  wt.block_height AS sweep_block_height,
+                  r.txid AS recovery_txid,
+                  r.transaction_hex AS recovery_transaction_hex,
+                  r.output_amount_sats AS recovery_output_amount_sats
+             FROM leaf_recoveries l
+             LEFT JOIN watchtower_exit_outputs o ON o.leaf_id = l.leaf_id
+             LEFT JOIN chain_transactions ot ON ot.txid = o.txid
+             LEFT JOIN watchtower_exit_spends s ON s.leaf_id = l.leaf_id
+             LEFT JOIN chain_transactions st ON st.txid = s.txid
+             LEFT JOIN unilateral_exit_sweeps w ON w.leaf_id = l.leaf_id
+             LEFT JOIN chain_transactions wt ON wt.txid = w.txid
+             LEFT JOIN watchtower_exit_recoveries r ON r.leaf_id = l.leaf_id
+             ORDER BY l.leaf_id, r.txid`
+        )
+        .all();
+      return Promise.resolve(leafRecoveriesFromRows(rows));
+    } catch (error) {
+      return Promise.reject(
+        new StorageError(`Failed to list leaf recoveries: ${error.message}`, error)
+      );
+    }
+  }
+
+  updateLeafRecovery(update) {
+    try {
+      const leafId = update.leafId;
+      const setChainTransaction = this.db.prepare(
+        `INSERT INTO chain_transactions (txid, block_height) VALUES (?, ?)
+           ON CONFLICT(txid) DO UPDATE SET block_height = excluded.block_height`
+      );
+      const transaction = this.db.transaction(() => {
+        this.db
+          .prepare(
+            "INSERT INTO leaf_recoveries (leaf_id) VALUES (?) ON CONFLICT(leaf_id) DO NOTHING"
+          )
+          .run(leafId);
+        if (update.chainCheckedAt != null) {
+          this.db
+            .prepare(
+              `UPDATE leaf_recoveries
+                 SET chain_checked_at = MAX(COALESCE(chain_checked_at, 0), ?)
+                 WHERE leaf_id = ?`
+            )
+            .run(update.chainCheckedAt, leafId);
+        }
+        if (update.watchtowerExitOutput != null) {
+          const output = update.watchtowerExitOutput;
+          for (const table of [
+            "watchtower_exit_recoveries",
+            "watchtower_exit_spends",
+          ]) {
+            this.db
+              .prepare(
+                `DELETE FROM ${table} WHERE leaf_id = @leafId AND EXISTS (
+                     SELECT 1 FROM watchtower_exit_outputs
+                     WHERE leaf_id = @leafId AND (txid <> @txid OR vout <> @vout))`
+              )
+              .run({ leafId, txid: output.txid, vout: output.vout });
+          }
+          setChainTransaction.run(output.txid, output.blockHeight);
+          this.db
+            .prepare(
+              `INSERT INTO watchtower_exit_outputs
+                   (leaf_id, txid, vout, amount_sats, script_pubkey)
+                 VALUES (?, ?, ?, ?, ?)
+                 ON CONFLICT(leaf_id) DO UPDATE SET
+                   txid = excluded.txid,
+                   vout = excluded.vout,
+                   amount_sats = excluded.amount_sats,
+                   script_pubkey = excluded.script_pubkey`
+            )
+            .run(
+              leafId,
+              output.txid,
+              output.vout,
+              output.amountSats,
+              output.scriptPubkey
+            );
+        }
+        if (update.watchtowerExitRecovery != null) {
+          const recovery = update.watchtowerExitRecovery;
+          this.db
+            .prepare(
+              `INSERT INTO watchtower_exit_recoveries
+                   (leaf_id, txid, transaction_hex, output_amount_sats)
+                 VALUES (?, ?, ?, ?)
+                 ON CONFLICT(leaf_id, txid) DO NOTHING`
+            )
+            .run(
+              leafId,
+              recovery.txid,
+              recovery.transactionHex,
+              recovery.outputAmountSats
+            );
+        }
+        for (const [table, chainTransaction] of [
+          ["watchtower_exit_spends", update.watchtowerExitSpend],
+          ["unilateral_exit_sweeps", update.unilateralExitSweep],
+        ]) {
+          if (chainTransaction == null) {
+            continue;
+          }
+          setChainTransaction.run(
+            chainTransaction.txid,
+            chainTransaction.blockHeight
+          );
+          this.db
+            .prepare(
+              `INSERT INTO ${table} (leaf_id, txid) VALUES (?, ?)
+                 ON CONFLICT(leaf_id) DO UPDATE SET txid = excluded.txid`
+            )
+            .run(leafId, chainTransaction.txid);
+        }
+      });
+
+      transaction.immediate();
+      return Promise.resolve();
+    } catch (error) {
+      return Promise.reject(
+        new StorageError(
+          `Failed to update leaf recovery '${update.leafId}': ${error.message}`,
+          error
+        )
+      );
+    }
+  }
+
   setLnurlMetadata(metadata) {
     try {
       const stmt = this.db.prepare(
@@ -1048,7 +1196,7 @@ class SqliteStorage {
           record.id.dataId,
           record.schemaVersion,
           Math.floor(Date.now() / 1000),
-          JSON.stringify(record.updatedFields),
+          toJson(record.updatedFields),
           revision.toString()
         );
 
@@ -1099,7 +1247,7 @@ class SqliteStorage {
           record.revision.toString(),
           record.schemaVersion,
           Math.floor(Date.now() / 1000),
-          JSON.stringify(record.data)
+          toJson(record.data)
         );
 
         // Update sync_revision to track the highest known revision
@@ -1225,7 +1373,7 @@ class SqliteStorage {
             record.id.dataId,
             record.schemaVersion,
             Math.floor(Date.now() / 1000),
-            JSON.stringify(record.data),
+            toJson(record.data),
             record.revision.toString()
           );
         }
@@ -1419,7 +1567,7 @@ class SqliteStorage {
           record.revision.toString(),
           record.schemaVersion,
           Math.floor(Date.now() / 1000),
-          JSON.stringify(record.data)
+          toJson(record.data)
         );
 
         // Update sync_revision to track the highest known revision
@@ -1592,6 +1740,49 @@ function crossChainSwapFromRow(row) {
   };
 }
 
+/// A row holds a leaf recovery and one of its watchtower exit recoveries, so
+/// a leaf recovery with several of them spans several rows.
+function leafRecoveriesFromRows(rows) {
+  const leafRecoveries = [];
+  for (const row of rows) {
+    let leafRecovery = leafRecoveries[leafRecoveries.length - 1];
+    if (leafRecovery?.leafId !== row.leaf_id) {
+      leafRecovery = {
+        leafId: row.leaf_id,
+        chainCheckedAt: row.chain_checked_at,
+        watchtowerExitOutput:
+          row.output_block_height != null
+            ? {
+                txid: row.output_txid,
+                vout: row.output_vout,
+                amountSats: row.output_amount_sats,
+                scriptPubkey: row.output_script_pubkey,
+                blockHeight: row.output_block_height,
+              }
+            : null,
+        watchtowerExitRecoveries: [],
+        watchtowerExitSpend:
+          row.spend_block_height != null
+            ? { txid: row.spend_txid, blockHeight: row.spend_block_height }
+            : null,
+        unilateralExitSweep:
+          row.sweep_block_height != null
+            ? { txid: row.sweep_txid, blockHeight: row.sweep_block_height }
+            : null,
+      };
+      leafRecoveries.push(leafRecovery);
+    }
+    if (row.recovery_txid != null) {
+      leafRecovery.watchtowerExitRecoveries.push({
+        txid: row.recovery_txid,
+        transactionHex: row.recovery_transaction_hex,
+        outputAmountSats: row.recovery_output_amount_sats,
+      });
+    }
+  }
+  return leafRecoveries;
+}
+
 async function createDefaultStorage(dataDir, logger = null) {
   const path = require("path");
   const fs = require("fs").promises;

package/nodejs/storage/migrations.cjs

@@ -521,6 +521,44 @@ class MigrationManager {
           `ALTER TABLE unclaimed_deposits ADD COLUMN max_claim_fee TEXT`,
         ],
       },
+      {
+        // Leaf recoveries. What the chain service reported about leaves with
+        // funds to recover on-chain, and the recoveries the operators co-signed.
+        // Every block height is in chain_transactions, keyed by txid.
+        name: "Add leaf recovery tables",
+        sql: [
+          `CREATE TABLE IF NOT EXISTS leaf_recoveries (
+              leaf_id TEXT NOT NULL PRIMARY KEY,
+              chain_checked_at INTEGER
+          )`,
+          `CREATE TABLE IF NOT EXISTS chain_transactions (
+              txid TEXT NOT NULL PRIMARY KEY,
+              block_height INTEGER NOT NULL
+          )`,
+          `CREATE TABLE IF NOT EXISTS watchtower_exit_outputs (
+              leaf_id TEXT NOT NULL PRIMARY KEY,
+              txid TEXT NOT NULL,
+              vout INTEGER NOT NULL,
+              amount_sats INTEGER NOT NULL,
+              script_pubkey TEXT NOT NULL
+          )`,
+          `CREATE TABLE IF NOT EXISTS watchtower_exit_recoveries (
+              leaf_id TEXT NOT NULL,
+              txid TEXT NOT NULL,
+              transaction_hex TEXT NOT NULL,
+              output_amount_sats INTEGER NOT NULL,
+              PRIMARY KEY (leaf_id, txid)
+          )`,
+          `CREATE TABLE IF NOT EXISTS watchtower_exit_spends (
+              leaf_id TEXT NOT NULL PRIMARY KEY,
+              txid TEXT NOT NULL
+          )`,
+          `CREATE TABLE IF NOT EXISTS unilateral_exit_sweeps (
+              leaf_id TEXT NOT NULL PRIMARY KEY,
+              txid TEXT NOT NULL
+          )`,
+        ],
+      },
     ];
   }
 }

package/nodejs/tree-store/index.cjs

@@ -94,6 +94,17 @@ const SLIM_LEAF_CANDIDATES_SQL = `
     )
 `;
 
+/**
+ * Takes one status, bound twice: given several through IN, SQLite reads every
+ * unreserved leaf instead of using the status index.
+ */
+const LEAVES_WITH_STATUS_SQL = `
+  SELECT data FROM brz_tree_leaves WHERE status = ? AND reservation_id IS NULL
+  UNION ALL
+  SELECT data FROM brz_tree_leaves
+  WHERE status = ? AND reservation_id IN (SELECT id FROM brz_tree_reservations)
+`;
+
 /**
  * Pair a leaf with its ancestors (nearest first) by walking `parent_node_id`
  * through `nodes`. Returns null if the leaf itself is absent; stops at a gap or
@@ -414,6 +425,30 @@ class NodeTreeStore {
     }
   }
 
+  /**
+   * Return the leaves, reserved or not, whose status is one of `statuses`.
+   * @param {Array<string>} statuses
+   * @returns {Promise<Array<object>>}
+   */
+  async getLeavesWithStatus(statuses) {
+    try {
+      const stmt = this.db.prepare(LEAVES_WITH_STATUS_SQL);
+      // One snapshot across the statements, so a leaf whose status changes
+      // between them is not read twice or missed.
+      return this.db.transaction(() =>
+        [...new Set(statuses)].flatMap((status) =>
+          stmt.all(status, status).map((row) => JSON.parse(row.data))
+        )
+      )();
+    } catch (error) {
+      if (error instanceof TreeStoreError) throw error;
+      throw new TreeStoreError(
+        `Failed to get leaves with status: ${error.message}`,
+        error
+      );
+    }
+  }
+
   /**
    * Replace the pool from a refresh. Skipped while a swap is in flight or one
    * completed during the refresh, so a swap's leaves are never clobbered.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@breeztech/breez-sdk-spark",
-    "version": "0.27.0-dev1",
+    "version": "0.27.0",
     "description": "Breez Spark SDK",
     "repository": "https://github.com/breez/spark-sdk",
     "author": "Breez <contact@breez.technology> (https://github.com/breez)",