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

package/nodejs/postgres-session-store/index.cjs

@@ -22,10 +22,12 @@ try {
   try {
     pg = require("pg");
   } catch (fallbackError) {
-    throw new Error(
+    const loadError = new Error(
       `pg not found. Please install it in your project: npm install pg@^8.18.0\n` +
         `Original error: ${error.message}\nFallback error: ${fallbackError.message}`
     );
+    loadError.code = fallbackError.code;
+    throw loadError;
   }
 }
 

package/nodejs/postgres-storage/index.cjs

@@ -16,16 +16,26 @@ try {
   try {
     pg = require("pg");
   } catch (fallbackError) {
-    throw new Error(
+    const loadError = new Error(
       `pg not found. Please install it in your project: npm install pg@^8.18.0\n` +
         `Original error: ${error.message}\nFallback error: ${fallbackError.message}`
     );
+    loadError.code = fallbackError.code;
+    throw loadError;
   }
 }
 
 const { StorageError } = require("./errors.cjs");
 const { PostgresMigrationManager } = 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.
@@ -371,7 +381,7 @@ class PostgresStorage {
     } catch (error) {
       if (error instanceof StorageError) throw error;
       throw new StorageError(
-        `Failed to list payments (request: ${JSON.stringify(request)}): ${error.message}`,
+        `Failed to list payments (request: ${toJson(request)}): ${error.message}`,
         error
       );
     }
@@ -462,7 +472,7 @@ class PostgresStorage {
         payment.amount.toString(),
         payment.fees.toString(),
         payment.timestamp,
-        payment.method ? JSON.stringify(payment.method) : null,
+        payment.method ? toJson(payment.method) : null,
         withdrawTxId,
         spark,
       ]
@@ -494,10 +504,10 @@ class PostgresStorage {
           this.identity,
           payment.id,
           payment.details.invoiceDetails
-            ? JSON.stringify(payment.details.invoiceDetails)
+            ? toJson(payment.details.invoiceDetails)
             : null,
           payment.details.htlcDetails
-            ? JSON.stringify(payment.details.htlcDetails)
+            ? toJson(payment.details.htlcDetails)
             : null,
         ]
       );
@@ -543,11 +553,11 @@ class PostgresStorage {
         [
           this.identity,
           payment.id,
-          JSON.stringify(payment.details.metadata),
+          toJson(payment.details.metadata),
           payment.details.txHash,
           payment.details.txType,
           payment.details.invoiceDetails
-            ? JSON.stringify(payment.details.invoiceDetails)
+            ? toJson(payment.details.invoiceDetails)
             : null,
         ]
       );
@@ -675,14 +685,14 @@ class PostgresStorage {
           paymentId,
           metadata.parentPaymentId,
           metadata.lnurlPayInfo
-            ? JSON.stringify(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,
         ]
@@ -761,7 +771,7 @@ class PostgresStorage {
           `UPDATE brz_unclaimed_deposits
            SET claim_error = $1
            WHERE user_id = $2 AND txid = $3 AND vout = $4`,
-          [JSON.stringify(payload.error), this.identity, txid, vout]
+          [toJson(payload.error), this.identity, txid, vout]
         );
       } else if (payload.type === "refund") {
         await this.pool.query(
@@ -771,7 +781,7 @@ class PostgresStorage {
           [
             payload.refundTx,
             payload.refundTxid,
-            JSON.stringify(payload.state),
+            toJson(payload.state),
             this.identity,
             txid,
             vout,
@@ -782,7 +792,7 @@ class PostgresStorage {
           `UPDATE brz_unclaimed_deposits
            SET instant_claim_status = $1
            WHERE user_id = $2 AND txid = $3 AND vout = $4`,
-          [JSON.stringify(payload.status), this.identity, txid, vout]
+          [toJson(payload.status), this.identity, txid, vout]
         );
       } else if (payload.type === "refundBroadcastState") {
         await this.pool.query(
@@ -790,7 +800,7 @@ class PostgresStorage {
            SET refund_state = $1
            WHERE user_id = $2 AND txid = $3 AND vout = $4 AND refund_tx_id = $5`,
           [
-            JSON.stringify(payload.state),
+            toJson(payload.state),
             this.identity,
             txid,
             vout,
@@ -803,7 +813,7 @@ class PostgresStorage {
            SET max_claim_fee = $1
            WHERE user_id = $2 AND txid = $3 AND vout = $4`,
           [
-            payload.maxFee ? JSON.stringify(payload.maxFee) : null,
+            payload.maxFee ? toJson(payload.maxFee) : null,
             this.identity,
             txid,
             vout,
@@ -874,6 +884,153 @@ class PostgresStorage {
     }
   }
 
+  async listLeafRecoveries() {
+    try {
+      const result = await this.pool.query(
+        `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 brz_leaf_recoveries l
+           LEFT JOIN brz_watchtower_exit_outputs o
+             ON o.user_id = l.user_id AND o.leaf_id = l.leaf_id
+           LEFT JOIN brz_chain_transactions ot
+             ON ot.user_id = o.user_id AND ot.txid = o.txid
+           LEFT JOIN brz_watchtower_exit_spends s
+             ON s.user_id = l.user_id AND s.leaf_id = l.leaf_id
+           LEFT JOIN brz_chain_transactions st
+             ON st.user_id = s.user_id AND st.txid = s.txid
+           LEFT JOIN brz_unilateral_exit_sweeps w
+             ON w.user_id = l.user_id AND w.leaf_id = l.leaf_id
+           LEFT JOIN brz_chain_transactions wt
+             ON wt.user_id = w.user_id AND wt.txid = w.txid
+           LEFT JOIN brz_watchtower_exit_recoveries r
+             ON r.user_id = l.user_id AND r.leaf_id = l.leaf_id
+           WHERE l.user_id = $1
+           ORDER BY l.leaf_id, r.txid`,
+        [this.identity]
+      );
+      return leafRecoveriesFromRows(result.rows);
+    } catch (error) {
+      throw new StorageError(
+        `Failed to list leaf recoveries: ${error.message}`,
+        error
+      );
+    }
+  }
+
+  async updateLeafRecovery(update) {
+    try {
+      const leafId = update.leafId;
+      await this._withTransaction(async (client) => {
+        const setChainTransaction = (txid, blockHeight) =>
+          client.query(
+            `INSERT INTO brz_chain_transactions (user_id, txid, block_height)
+               VALUES ($1, $2, $3)
+               ON CONFLICT(user_id, txid) DO UPDATE SET block_height = EXCLUDED.block_height`,
+            [this.identity, txid, blockHeight]
+          );
+
+        // PostgreSQL locks the leaf's row, so writers of one leaf do not interleave.
+        await client.query(
+          `INSERT INTO brz_leaf_recoveries (user_id, leaf_id) VALUES ($1, $2)
+             ON CONFLICT(user_id, leaf_id) DO UPDATE SET leaf_id = EXCLUDED.leaf_id`,
+          [this.identity, leafId]
+        );
+        if (update.chainCheckedAt != null) {
+          await client.query(
+            `UPDATE brz_leaf_recoveries
+               SET chain_checked_at = GREATEST(COALESCE(chain_checked_at, 0), $3)
+               WHERE user_id = $1 AND leaf_id = $2`,
+            [this.identity, leafId, String(update.chainCheckedAt)]
+          );
+        }
+        if (update.watchtowerExitOutput != null) {
+          const output = update.watchtowerExitOutput;
+          for (const table of [
+            "brz_watchtower_exit_recoveries",
+            "brz_watchtower_exit_spends",
+          ]) {
+            await client.query(
+              `DELETE FROM ${table}
+                 WHERE user_id = $1 AND leaf_id = $2 AND EXISTS (
+                   SELECT 1 FROM brz_watchtower_exit_outputs
+                   WHERE user_id = $1 AND leaf_id = $2 AND (txid <> $3 OR vout <> $4))`,
+              [this.identity, leafId, output.txid, output.vout]
+            );
+          }
+          await setChainTransaction(output.txid, output.blockHeight);
+          await client.query(
+            `INSERT INTO brz_watchtower_exit_outputs
+                 (user_id, leaf_id, txid, vout, amount_sats, script_pubkey)
+               VALUES ($1, $2, $3, $4, $5, $6)
+               ON CONFLICT(user_id, leaf_id) DO UPDATE SET
+                 txid = EXCLUDED.txid,
+                 vout = EXCLUDED.vout,
+                 amount_sats = EXCLUDED.amount_sats,
+                 script_pubkey = EXCLUDED.script_pubkey`,
+            [
+              this.identity,
+              leafId,
+              output.txid,
+              output.vout,
+              String(output.amountSats),
+              output.scriptPubkey,
+            ]
+          );
+        }
+        if (update.watchtowerExitRecovery != null) {
+          const recovery = update.watchtowerExitRecovery;
+          await client.query(
+            `INSERT INTO brz_watchtower_exit_recoveries
+                 (user_id, leaf_id, txid, transaction_hex, output_amount_sats)
+               VALUES ($1, $2, $3, $4, $5)
+               ON CONFLICT(user_id, leaf_id, txid) DO NOTHING`,
+            [
+              this.identity,
+              leafId,
+              recovery.txid,
+              recovery.transactionHex,
+              String(recovery.outputAmountSats),
+            ]
+          );
+        }
+        for (const [table, chainTransaction] of [
+          ["brz_watchtower_exit_spends", update.watchtowerExitSpend],
+          ["brz_unilateral_exit_sweeps", update.unilateralExitSweep],
+        ]) {
+          if (chainTransaction == null) {
+            continue;
+          }
+          await setChainTransaction(
+            chainTransaction.txid,
+            chainTransaction.blockHeight
+          );
+          await client.query(
+            `INSERT INTO ${table} (user_id, leaf_id, txid) VALUES ($1, $2, $3)
+               ON CONFLICT(user_id, leaf_id) DO UPDATE SET txid = EXCLUDED.txid`,
+            [this.identity, leafId, chainTransaction.txid]
+          );
+        }
+      });
+    } catch (error) {
+      throw new StorageError(
+        `Failed to update leaf recovery '${update.leafId}': ${error.message}`,
+        error
+      );
+    }
+  }
+
   async setLnurlMetadata(metadata) {
     try {
       await this._withTransaction(async (client) => {
@@ -1235,7 +1392,7 @@ class PostgresStorage {
             record.id.dataId,
             record.schemaVersion,
             Math.floor(Date.now() / 1000),
-            JSON.stringify(record.updatedFields),
+            toJson(record.updatedFields),
             revision.toString(),
           ]
         );
@@ -1295,7 +1452,7 @@ class PostgresStorage {
             record.revision.toString(),
             record.schemaVersion,
             Math.floor(Date.now() / 1000),
-            JSON.stringify(record.data),
+            toJson(record.data),
           ]
         );
 
@@ -1426,7 +1583,7 @@ class PostgresStorage {
               record.id.dataId,
               record.schemaVersion,
               Math.floor(Date.now() / 1000),
-              JSON.stringify(record.data),
+              toJson(record.data),
               record.revision.toString(),
             ]
           );
@@ -1613,7 +1770,7 @@ class PostgresStorage {
             record.revision.toString(),
             record.schemaVersion,
             Math.floor(Date.now() / 1000),
-            JSON.stringify(record.data),
+            toJson(record.data),
           ]
         );
 
@@ -1648,6 +1805,58 @@ 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 != null ? BigInt(row.chain_checked_at) : null,
+        watchtowerExitOutput:
+          row.output_block_height != null
+            ? {
+                txid: row.output_txid,
+                vout: Number(row.output_vout),
+                amountSats: BigInt(row.output_amount_sats),
+                scriptPubkey: row.output_script_pubkey,
+                blockHeight: Number(row.output_block_height),
+              }
+            : null,
+        watchtowerExitRecoveries: [],
+        watchtowerExitSpend:
+          row.spend_block_height != null
+            ? {
+                txid: row.spend_txid,
+                blockHeight: Number(row.spend_block_height),
+              }
+            : null,
+        unilateralExitSweep:
+          row.sweep_block_height != null
+            ? {
+                txid: row.sweep_txid,
+                blockHeight: Number(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: BigInt(row.recovery_output_amount_sats),
+      });
+    }
+  }
+  return leafRecoveries;
+}
+
 /**
  * Creates a PostgresStorageConfig with the given connection string and default pool settings.
  *

package/nodejs/postgres-storage/migrations.cjs

@@ -563,6 +563,55 @@ class PostgresMigrationManager {
           `ALTER TABLE brz_unclaimed_deposits ADD COLUMN max_claim_fee JSONB`,
         ],
       },
+      {
+        // 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 brz_chain_transactions, keyed by txid.
+        name: "Add leaf recovery tables",
+        sql: [
+          `CREATE TABLE IF NOT EXISTS brz_leaf_recoveries (
+              user_id BYTEA NOT NULL,
+              leaf_id TEXT NOT NULL,
+              chain_checked_at BIGINT,
+              PRIMARY KEY (user_id, leaf_id)
+          )`,
+          `CREATE TABLE IF NOT EXISTS brz_chain_transactions (
+              user_id BYTEA NOT NULL,
+              txid TEXT NOT NULL,
+              block_height BIGINT NOT NULL,
+              PRIMARY KEY (user_id, txid)
+          )`,
+          `CREATE TABLE IF NOT EXISTS brz_watchtower_exit_outputs (
+              user_id BYTEA NOT NULL,
+              leaf_id TEXT NOT NULL,
+              txid TEXT NOT NULL,
+              vout BIGINT NOT NULL,
+              amount_sats BIGINT NOT NULL,
+              script_pubkey TEXT NOT NULL,
+              PRIMARY KEY (user_id, leaf_id)
+          )`,
+          `CREATE TABLE IF NOT EXISTS brz_watchtower_exit_recoveries (
+              user_id BYTEA NOT NULL,
+              leaf_id TEXT NOT NULL,
+              txid TEXT NOT NULL,
+              transaction_hex TEXT NOT NULL,
+              output_amount_sats BIGINT NOT NULL,
+              PRIMARY KEY (user_id, leaf_id, txid)
+          )`,
+          `CREATE TABLE IF NOT EXISTS brz_watchtower_exit_spends (
+              user_id BYTEA NOT NULL,
+              leaf_id TEXT NOT NULL,
+              txid TEXT NOT NULL,
+              PRIMARY KEY (user_id, leaf_id)
+          )`,
+          `CREATE TABLE IF NOT EXISTS brz_unilateral_exit_sweeps (
+              user_id BYTEA NOT NULL,
+              leaf_id TEXT NOT NULL,
+              txid TEXT NOT NULL,
+              PRIMARY KEY (user_id, leaf_id)
+          )`,
+        ],
+      },
     ];
   }
 }

package/nodejs/postgres-token-store/index.cjs

@@ -14,10 +14,12 @@ try {
   try {
     pg = require("pg");
   } catch (fallbackError) {
-    throw new Error(
+    const loadError = new Error(
       `pg not found. Please install it in your project: npm install pg@^8.18.0\n` +
         `Original error: ${error.message}\nFallback error: ${fallbackError.message}`
     );
+    loadError.code = fallbackError.code;
+    throw loadError;
   }
 }
 

package/nodejs/postgres-tree-store/index.cjs

@@ -14,10 +14,12 @@ try {
   try {
     pg = require("pg");
   } catch (fallbackError) {
-    throw new Error(
+    const loadError = new Error(
       `pg not found. Please install it in your project: npm install pg@^8.18.0\n` +
         `Original error: ${error.message}\nFallback error: ${fallbackError.message}`
     );
+    loadError.code = fallbackError.code;
+    throw loadError;
   }
 }
 
@@ -475,6 +477,28 @@ class PostgresTreeStore {
     }
   }
 
+  /**
+   * Return the leaves, reserved or not, whose status is one of `statuses`.
+   * @param {Array<string>} statuses
+   * @returns {Promise<Array<object>>}
+   */
+  async getLeavesWithStatus(statuses) {
+    try {
+      if (!statuses || statuses.length === 0) return [];
+      const result = await this.pool.query(
+        "SELECT data FROM brz_tree_leaves WHERE user_id = $1 AND status = ANY($2)",
+        [this.identity, statuses]
+      );
+      return result.rows.map((row) => row.data);
+    } catch (error) {
+      if (error instanceof TreeStoreError) throw error;
+      throw new TreeStoreError(
+        `Failed to get leaves with status: ${error.message}`,
+        error
+      );
+    }
+  }
+
   /**
    * Set leaves from a refresh operation.
    * @param {Array} leaves - Available leaves from operators

package/nodejs/postgres-tree-store/migrations.cjs

@@ -346,6 +346,16 @@ class TreeStoreMigrationManager {
              signing_public_key = data->'signing_keyshare'->>'public_key'`,
         ],
       },
+      {
+        // Mirrors Rust migration 6 in spark-postgres/src/tree_store.rs. Indexes
+        // the leaves outside the `Available` status, so reading them by status
+        // does not scan the spendable pool.
+        name: "Index leaves outside the Available status",
+        sql: [
+          `CREATE INDEX IF NOT EXISTS brz_idx_tree_leaves_user_unavailable
+             ON brz_tree_leaves(user_id, status) WHERE status <> 'Available'`,
+        ],
+      },
     ];
   }
 }