@breeztech/breez-sdk-spark 0.15.1 → 0.17.0

package/nodejs/storage/index.cjs

@@ -41,7 +41,8 @@ const SELECT_PAYMENT_SQL = `
            p.timestamp,
            p.method,
            p.withdraw_tx_id,
-           p.deposit_tx_id,
+           pd.tx_id AS deposit_tx_id,
+           pd.vout AS deposit_vout,
            p.spark,
            l.invoice AS lightning_invoice,
            l.payment_hash AS lightning_payment_hash,
@@ -69,6 +70,7 @@ const SELECT_PAYMENT_SQL = `
       LEFT JOIN payment_details_lightning l ON p.id = l.payment_id
       LEFT JOIN payment_details_token t ON p.id = t.payment_id
       LEFT JOIN payment_details_spark s ON p.id = s.payment_id
+      LEFT JOIN payment_details_deposit pd ON p.id = pd.payment_id
       LEFT JOIN payment_metadata pm ON p.id = pm.payment_id
       LEFT JOIN lnurl_receive_metadata lrm ON l.payment_hash = lrm.payment_hash`;
 
@@ -204,6 +206,14 @@ class SqliteStorage {
         const allPaymentDetailsClauses = [];
         for (const paymentDetailsFilter of request.paymentDetailsFilter) {
           const paymentDetailsClauses = [];
+          // Base type check: ensure payment type matches the filter type
+          if (paymentDetailsFilter.type === "spark") {
+            paymentDetailsClauses.push("p.spark = 1");
+          } else if (paymentDetailsFilter.type === "token") {
+            paymentDetailsClauses.push("p.spark IS NULL AND t.tx_hash IS NOT NULL");
+          } else if (paymentDetailsFilter.type === "lightning") {
+            paymentDetailsClauses.push("l.htlc_status IS NOT NULL");
+          }
           // Filter by HTLC status (Spark or Lightning)
           const htlcAlias =
             paymentDetailsFilter.type === "spark" ? "s"
@@ -230,20 +240,35 @@ class SqliteStorage {
             }
             params.push(...paymentDetailsFilter.htlcStatus);
           }
-          // Filter by token conversion info presence
+          // Filter by conversion type + status
           if (
-            (paymentDetailsFilter.type === "spark" || paymentDetailsFilter.type === "token") &&
-              paymentDetailsFilter.conversionRefundNeeded !== undefined
+            (paymentDetailsFilter.type === "spark" ||
+              paymentDetailsFilter.type === "token" ||
+              paymentDetailsFilter.type === "lightning") &&
+              paymentDetailsFilter.conversionFilter !== undefined
           ) {
-            const typeCheck = paymentDetailsFilter.type === "spark" ? "p.spark = 1" : "p.spark IS NULL";
-            const refundNeeded =
-              paymentDetailsFilter.conversionRefundNeeded === true
-                ? "= 'refundNeeded'"
-                : "!= 'refundNeeded'";
-            paymentDetailsClauses.push(
-              `${typeCheck} AND pm.conversion_info IS NOT NULL AND
-              json_extract(pm.conversion_info, '$.status') ${refundNeeded}`
-            );
+            // Lightning carries the Boltz conversion; its `conversion_info.type`
+            // is the authoritative discriminator, so no payment-type column check.
+            const typeCheck =
+              paymentDetailsFilter.type === "spark"
+                ? "p.spark = 1"
+                : paymentDetailsFilter.type === "token"
+                  ? "p.spark IS NULL"
+                  : null;
+            let statusClause;
+            if (paymentDetailsFilter.conversionFilter === "ammRefundNeeded") {
+              statusClause = "json_extract(pm.conversion_info, '$.type') = 'amm' AND json_extract(pm.conversion_info, '$.status') = 'refundNeeded'";
+            } else if (paymentDetailsFilter.conversionFilter === "orchestraPending") {
+              statusClause = "json_extract(pm.conversion_info, '$.type') = 'orchestra' AND json_extract(pm.conversion_info, '$.status') NOT IN ('completed', 'failed', 'refunded')";
+            } else if (paymentDetailsFilter.conversionFilter === "boltzPending") {
+              statusClause = "json_extract(pm.conversion_info, '$.type') = 'boltz' AND json_extract(pm.conversion_info, '$.status') NOT IN ('completed', 'failed', 'refunded')";
+            }
+            if (statusClause) {
+              const prefix = typeCheck ? `${typeCheck} AND ` : "";
+              paymentDetailsClauses.push(
+                `${prefix}pm.conversion_info IS NOT NULL AND ${statusClause}`
+              );
+            }
           }
           // Filter by token transaction hash
           if (
@@ -313,129 +338,180 @@ class SqliteStorage {
     }
   }
 
-  insertPayment(payment) {
-    try {
-      if (!payment) {
-        return Promise.reject(
-          new StorageError("Payment cannot be null or undefined")
-        );
-      }
+  async applyPaymentUpdate(payment) {
+    if (!payment) {
+      throw new StorageError("Payment cannot be null or undefined");
+    }
 
-      const paymentInsert = this.db.prepare(
-        `INSERT INTO payments (id, payment_type, status, amount, fees, timestamp, method, withdraw_tx_id, deposit_tx_id, spark) 
-         VALUES (@id, @paymentType, @status, @amount, @fees, @timestamp, @method, @withdrawTxId, @depositTxId, @spark)
-         ON CONFLICT(id) DO UPDATE SET
-           payment_type=excluded.payment_type,
-           status=excluded.status,
-           amount=excluded.amount,
-           fees=excluded.fees,
-           timestamp=excluded.timestamp,
-           method=excluded.method,
-           withdraw_tx_id=excluded.withdraw_tx_id,
-           deposit_tx_id=excluded.deposit_tx_id,
-           spark=excluded.spark`
-      );
-      const lightningInsert = this.db.prepare(
-        `INSERT INTO payment_details_lightning
-          (payment_id, invoice, payment_hash, destination_pubkey, description, preimage, htlc_status, htlc_expiry_time)
-          VALUES (@id, @invoice, @paymentHash, @destinationPubkey, @description, @preimage, @htlcStatus, @htlcExpiryTime)
-          ON CONFLICT(payment_id) DO UPDATE SET
-            invoice=excluded.invoice,
-            payment_hash=excluded.payment_hash,
-            destination_pubkey=excluded.destination_pubkey,
-            description=excluded.description,
-            preimage=COALESCE(excluded.preimage, payment_details_lightning.preimage),
-            htlc_status=COALESCE(excluded.htlc_status, payment_details_lightning.htlc_status),
-            htlc_expiry_time=COALESCE(excluded.htlc_expiry_time, payment_details_lightning.htlc_expiry_time)`
-      );
-      const tokenInsert = this.db.prepare(
-        `INSERT INTO payment_details_token 
-          (payment_id, metadata, tx_hash, tx_type, invoice_details) 
-          VALUES (@id, @metadata, @txHash, @txType, @invoiceDetails)
-          ON CONFLICT(payment_id) DO UPDATE SET
-            metadata=excluded.metadata,
-            tx_hash=excluded.tx_hash,
-            tx_type=excluded.tx_type,
-            invoice_details=COALESCE(excluded.invoice_details, payment_details_token.invoice_details)`
-      );
-      const sparkInsert = this.db.prepare(
-        `INSERT INTO payment_details_spark 
-          (payment_id, invoice_details, htlc_details) 
-          VALUES (@id, @invoiceDetails, @htlcDetails)
-          ON CONFLICT(payment_id) DO UPDATE SET
-            invoice_details=COALESCE(excluded.invoice_details, payment_details_spark.invoice_details),
-            htlc_details=COALESCE(excluded.htlc_details, payment_details_spark.htlc_details)`
+    try {
+      const selectStatus = this.db.prepare(
+        "SELECT status FROM payments WHERE id = ?"
       );
+      let shouldEmit = false;
       const transaction = this.db.transaction(() => {
-        paymentInsert.run({
-          id: payment.id,
-          paymentType: payment.paymentType,
-          status: payment.status,
-          amount: payment.amount.toString(),
-          fees: payment.fees.toString(),
-          timestamp: payment.timestamp,
-          method: payment.method ? JSON.stringify(payment.method) : null,
-          withdrawTxId:
-            payment.details?.type === "withdraw" ? payment.details.txId : null,
-          depositTxId:
-            payment.details?.type === "deposit" ? payment.details.txId : null,
-          spark: payment.details?.type === "spark" ? 1 : null,
-        });
-
-        if (
-          payment.details?.type === "spark" &&
-          (payment.details.invoiceDetails != null ||
-            payment.details.htlcDetails != null)
-        ) {
-          sparkInsert.run({
-            id: payment.id,
-            invoiceDetails: payment.details.invoiceDetails
-              ? JSON.stringify(payment.details.invoiceDetails)
-              : null,
-            htlcDetails: payment.details.htlcDetails
-              ? JSON.stringify(payment.details.htlcDetails)
-              : null,
-          });
-        }
-
-        if (payment.details?.type === "lightning") {
-          lightningInsert.run({
-            id: payment.id,
-            invoice: payment.details.invoice,
-            paymentHash: payment.details.htlcDetails.paymentHash,
-            destinationPubkey: payment.details.destinationPubkey,
-            description: payment.details.description,
-            preimage: payment.details.htlcDetails?.preimage,
-            htlcStatus: payment.details.htlcDetails?.status ?? null,
-            htlcExpiryTime: payment.details.htlcDetails?.expiryTime ?? 0,
-          });
-        }
-
-        if (payment.details?.type === "token") {
-          tokenInsert.run({
-            id: payment.id,
-            metadata: JSON.stringify(payment.details.metadata),
-            txHash: payment.details.txHash,
-            txType: payment.details.txType,
-            invoiceDetails: payment.details.invoiceDetails
-              ? JSON.stringify(payment.details.invoiceDetails)
-              : null,
-          });
+        const row = selectStatus.get(payment.id);
+        const stored = row
+          ? this._normalizePaymentStatus(row.status)
+          : null;
+        const next = this._normalizePaymentStatus(payment.status);
+
+        if (stored == null) {
+          this._runPaymentUpsert(payment);
+          shouldEmit = true;
+        } else if (stored === next) {
+          console.debug(
+            `Skipping redundant payment event: id=${payment.id} status=${next}`
+          );
+          this._runPaymentUpsert(payment);
+          shouldEmit = false;
+        } else if (this._isFinalPaymentStatus(stored)) {
+          console.warn(
+            `Skipping payment update (would replace terminal status): id=${payment.id} stored=${stored} new=${next}`
+          );
+          shouldEmit = false;
+        } else {
+          this._runPaymentUpsert(payment);
+          shouldEmit = true;
         }
       });
 
-      transaction();
-      return Promise.resolve();
+      transaction.immediate();
+      return shouldEmit;
     } catch (error) {
-      return Promise.reject(
-        new StorageError(
-          `Failed to insert payment '${payment.id}': ${error.message}`,
-          error
-        )
+      throw new StorageError(
+        `Failed to apply payment update '${payment.id}': ${error.message}`,
+        error
       );
     }
   }
 
+  _runPaymentUpsert(payment) {
+    const paymentInsert = this.db.prepare(
+      `INSERT INTO payments (id, payment_type, status, amount, fees, timestamp, method, withdraw_tx_id, spark)
+       VALUES (@id, @paymentType, @status, @amount, @fees, @timestamp, @method, @withdrawTxId, @spark)
+       ON CONFLICT(id) DO UPDATE SET
+         payment_type=excluded.payment_type,
+         status=excluded.status,
+         amount=excluded.amount,
+         fees=excluded.fees,
+         timestamp=excluded.timestamp,
+         method=excluded.method,
+         withdraw_tx_id=excluded.withdraw_tx_id,
+         spark=excluded.spark`
+    );
+    const depositInsert = this.db.prepare(
+      `INSERT INTO payment_details_deposit
+        (payment_id, tx_id, vout)
+        VALUES (@id, @txId, @vout)
+        ON CONFLICT(payment_id) DO UPDATE SET
+          tx_id=excluded.tx_id,
+          vout=excluded.vout`
+    );
+    const lightningInsert = this.db.prepare(
+      `INSERT INTO payment_details_lightning
+        (payment_id, invoice, payment_hash, destination_pubkey, description, preimage, htlc_status, htlc_expiry_time)
+        VALUES (@id, @invoice, @paymentHash, @destinationPubkey, @description, @preimage, @htlcStatus, @htlcExpiryTime)
+        ON CONFLICT(payment_id) DO UPDATE SET
+          invoice=excluded.invoice,
+          payment_hash=excluded.payment_hash,
+          destination_pubkey=excluded.destination_pubkey,
+          description=excluded.description,
+          preimage=COALESCE(excluded.preimage, payment_details_lightning.preimage),
+          htlc_status=COALESCE(excluded.htlc_status, payment_details_lightning.htlc_status),
+          htlc_expiry_time=COALESCE(excluded.htlc_expiry_time, payment_details_lightning.htlc_expiry_time)`
+    );
+    const tokenInsert = this.db.prepare(
+      `INSERT INTO payment_details_token
+        (payment_id, metadata, tx_hash, tx_type, invoice_details)
+        VALUES (@id, @metadata, @txHash, @txType, @invoiceDetails)
+        ON CONFLICT(payment_id) DO UPDATE SET
+          metadata=excluded.metadata,
+          tx_hash=excluded.tx_hash,
+          tx_type=excluded.tx_type,
+          invoice_details=COALESCE(excluded.invoice_details, payment_details_token.invoice_details)`
+    );
+    const sparkInsert = this.db.prepare(
+      `INSERT INTO payment_details_spark
+        (payment_id, invoice_details, htlc_details)
+        VALUES (@id, @invoiceDetails, @htlcDetails)
+        ON CONFLICT(payment_id) DO UPDATE SET
+          invoice_details=COALESCE(excluded.invoice_details, payment_details_spark.invoice_details),
+          htlc_details=COALESCE(excluded.htlc_details, payment_details_spark.htlc_details)`
+    );
+
+    paymentInsert.run({
+      id: payment.id,
+      paymentType: payment.paymentType,
+      status: payment.status,
+      amount: payment.amount.toString(),
+      fees: payment.fees.toString(),
+      timestamp: payment.timestamp,
+      method: payment.method ? JSON.stringify(payment.method) : null,
+      withdrawTxId:
+        payment.details?.type === "withdraw" ? payment.details.txId : null,
+      spark: payment.details?.type === "spark" ? 1 : null,
+    });
+
+    if (payment.details?.type === "deposit") {
+      depositInsert.run({
+        id: payment.id,
+        txId: payment.details.txId,
+        vout: payment.details.vout,
+      });
+    }
+
+    if (
+      payment.details?.type === "spark" &&
+      (payment.details.invoiceDetails != null ||
+        payment.details.htlcDetails != null)
+    ) {
+      sparkInsert.run({
+        id: payment.id,
+        invoiceDetails: payment.details.invoiceDetails
+          ? JSON.stringify(payment.details.invoiceDetails)
+          : null,
+        htlcDetails: payment.details.htlcDetails
+          ? JSON.stringify(payment.details.htlcDetails)
+          : null,
+      });
+    }
+
+    if (payment.details?.type === "lightning") {
+      lightningInsert.run({
+        id: payment.id,
+        invoice: payment.details.invoice,
+        paymentHash: payment.details.htlcDetails.paymentHash,
+        destinationPubkey: payment.details.destinationPubkey,
+        description: payment.details.description,
+        preimage: payment.details.htlcDetails?.preimage,
+        htlcStatus: payment.details.htlcDetails?.status ?? null,
+        htlcExpiryTime: payment.details.htlcDetails?.expiryTime ?? 0,
+      });
+    }
+
+    if (payment.details?.type === "token") {
+      tokenInsert.run({
+        id: payment.id,
+        metadata: JSON.stringify(payment.details.metadata),
+        txHash: payment.details.txHash,
+        txType: payment.details.txType,
+        invoiceDetails: payment.details.invoiceDetails
+          ? JSON.stringify(payment.details.invoiceDetails)
+          : null,
+      });
+    }
+  }
+
+  _normalizePaymentStatus(status) {
+    return typeof status === "string" ? status.toLowerCase() : status;
+  }
+
+  _isFinalPaymentStatus(status) {
+    const normalized = this._normalizePaymentStatus(status);
+    return normalized === "completed" || normalized === "failed";
+  }
+
+
   getPaymentById(id) {
     try {
       if (!id) {
@@ -760,6 +836,17 @@ class SqliteStorage {
           senderComment: row.lnurl_sender_comment || null,
         };
       }
+
+      if (row.conversion_info) {
+        try {
+          details.conversionInfo = JSON.parse(row.conversion_info);
+        } catch (e) {
+          throw new StorageError(
+            `Failed to parse conversion_info JSON for payment ${row.id}: ${e.message}`,
+            e
+          );
+        }
+      }
     } else if (row.withdraw_tx_id) {
       details = {
         type: "withdraw",
@@ -769,6 +856,7 @@ class SqliteStorage {
       details = {
         type: "deposit",
         txId: row.deposit_tx_id,
+        vout: row.deposit_vout,
       };
     } else if (row.spark) {
       details = {
@@ -1324,6 +1412,78 @@ class SqliteStorage {
       );
     }
   }
+
+  // ===== Cross-Chain Swap Operations =====
+
+  setCrossChainSwap(swap) {
+    try {
+      const stmt = this.db.prepare(`
+        INSERT INTO cross_chain_swaps (provider, id, is_terminal, updated_at, data, secrets)
+        VALUES (?, ?, ?, ?, ?, ?)
+        ON CONFLICT(provider, id) DO UPDATE SET
+          is_terminal = excluded.is_terminal,
+          updated_at = excluded.updated_at,
+          data = excluded.data,
+          secrets = excluded.secrets
+      `);
+      stmt.run(
+        swap.provider,
+        swap.id,
+        swap.isTerminal ? 1 : 0,
+        swap.updatedAt,
+        swap.data,
+        swap.secrets
+      );
+      return Promise.resolve();
+    } catch (error) {
+      return Promise.reject(
+        new StorageError(`Failed to set cross-chain swap: ${error.message}`, error)
+      );
+    }
+  }
+
+  getCrossChainSwap(provider, id) {
+    try {
+      const stmt = this.db.prepare(
+        `SELECT provider, id, is_terminal, updated_at, data, secrets
+         FROM cross_chain_swaps WHERE provider = ? AND id = ?`
+      );
+      const row = stmt.get(provider, id);
+      return Promise.resolve(row ? crossChainSwapFromRow(row) : null);
+    } catch (error) {
+      return Promise.reject(
+        new StorageError(`Failed to get cross-chain swap: ${error.message}`, error)
+      );
+    }
+  }
+
+  listActiveCrossChainSwaps(provider) {
+    try {
+      const stmt = this.db.prepare(
+        `SELECT provider, id, is_terminal, updated_at, data, secrets
+         FROM cross_chain_swaps WHERE provider = ? AND is_terminal = 0`
+      );
+      const rows = stmt.all(provider);
+      return Promise.resolve(rows.map(crossChainSwapFromRow));
+    } catch (error) {
+      return Promise.reject(
+        new StorageError(`Failed to list active cross-chain swaps: ${error.message}`, error)
+      );
+    }
+  }
+}
+
+/// Maps a `cross_chain_swaps` row to a StoredCrossChainSwap, parsing `data` and
+/// the is_terminal flag back into the camelCase shape the SDK expects.
+function crossChainSwapFromRow(row) {
+  return {
+    provider: row.provider,
+    id: row.id,
+    isTerminal: row.is_terminal !== 0,
+    updatedAt: Number(row.updated_at),
+    data: row.data,
+    secrets: row.secrets,
+  };
 }
 
 async function createDefaultStorage(dataDir, logger = null) {

package/nodejs/storage/migrations.cjs

@@ -433,6 +433,53 @@ class MigrationManager {
           `CREATE INDEX idx_payment_metadata_payment_id ON payment_metadata(payment_id)`,
         ],
       },
+      {
+        // Move deposit details into their own table so vout can be NOT NULL and
+        // the schema matches payment_details_lightning / _token / _spark. We can't
+        // safely backfill the new table from the dropped deposit_tx_id column: we
+        // never stored the original SSP output_index, and vout=0 is a valid output
+        // index, so defaulting would silently mislabel. Drop the column and leave
+        // the payments row in place. The read path sees an unjoined deposit row
+        // as `details: None` until the resync re-fetches the SSP user_request and
+        // the upsert inserts the new details row.
+        name: "Move deposit details into payment_details_deposit table",
+        sql: [
+          `CREATE TABLE payment_details_deposit (
+              payment_id TEXT PRIMARY KEY,
+              tx_id TEXT NOT NULL,
+              vout INTEGER NOT NULL,
+              FOREIGN KEY (payment_id) REFERENCES payments(id) ON DELETE CASCADE
+          )`,
+          `ALTER TABLE payments DROP COLUMN deposit_tx_id`,
+          `UPDATE settings
+           SET value = json_set(value, '$.offset', 0)
+           WHERE key = 'sync_offset' AND json_valid(value)`,
+        ],
+      },
+      {
+        name: "Backfill conversion_info type discriminator",
+        sql: `UPDATE payment_metadata SET conversion_info = json_set(conversion_info, '$.type', 'amm') WHERE conversion_info IS NOT NULL AND json_extract(conversion_info, '$.type') IS NULL`,
+      },
+      {
+        // Cross-chain swap rows, synced for cross-instance recovery. Shared
+        // across providers, discriminated by `provider`. `data` is
+        // provider-opaque JSON; `secrets` is provider-opaque ciphertext (empty
+        // when the provider has none).
+        name: "Create cross_chain_swaps table",
+        sql: [
+          `CREATE TABLE cross_chain_swaps (
+              provider TEXT NOT NULL,
+              id TEXT NOT NULL,
+              is_terminal INTEGER NOT NULL,
+              updated_at INTEGER NOT NULL,
+              data TEXT NOT NULL,
+              secrets TEXT NOT NULL,
+              PRIMARY KEY (provider, id)
+          )`,
+          `CREATE INDEX idx_cross_chain_swaps_provider_is_terminal
+            ON cross_chain_swaps(provider, is_terminal)`,
+        ],
+      },
     ];
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@breeztech/breez-sdk-spark",
-    "version": "0.15.1",
+    "version": "0.17.0",
     "description": "Breez Spark SDK",
     "repository": "https://github.com/breez/spark-sdk",
     "author": "Breez <contact@breez.technology> (https://github.com/breez)",
@@ -23,6 +23,11 @@
         "./nodejs": "./nodejs/index.js",
         "./web": "./web/index.js",
         "./ssr": "./ssr/index.js",
+        "./passkey-prf-provider": {
+            "types": "./web/passkey-prf-provider/index.d.ts",
+            "import": "./web/passkey-prf-provider/index.js",
+            "default": "./web/passkey-prf-provider/index.js"
+        },
         ".": {
             "node": {
                 "import": "./nodejs/index.mjs",