@breeztech/breez-sdk-spark 0.15.1 → 0.17.0

package/nodejs/postgres-storage/index.cjs

@@ -2,6 +2,8 @@
  * CommonJS implementation for Node.js PostgreSQL Storage
  */
 
+const crypto = require("crypto");
+
 let pg;
 try {
   const mainModule = require.main;
@@ -38,7 +40,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,
@@ -66,6 +69,7 @@ const SELECT_PAYMENT_SQL = `
       LEFT JOIN brz_payment_details_lightning l ON p.id = l.payment_id AND p.user_id = l.user_id
       LEFT JOIN brz_payment_details_token t ON p.id = t.payment_id AND p.user_id = t.user_id
       LEFT JOIN brz_payment_details_spark s ON p.id = s.payment_id AND p.user_id = s.user_id
+      LEFT JOIN brz_payment_details_deposit pd ON p.id = pd.payment_id AND p.user_id = pd.user_id
       LEFT JOIN brz_payment_metadata pm ON p.id = pm.payment_id AND p.user_id = pm.user_id
       LEFT JOIN brz_lnurl_receive_metadata lrm ON l.payment_hash = lrm.payment_hash AND l.user_id = lrm.user_id`;
 
@@ -235,6 +239,15 @@ class PostgresStorage {
         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 = true");
+          } 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"
@@ -262,24 +275,35 @@ class PostgresStorage {
             params.push(...paymentDetailsFilter.htlcStatus);
           }
 
-          // Filter by conversion refund needed
+          // Filter by conversion type + status
           if (
             (paymentDetailsFilter.type === "spark" ||
-              paymentDetailsFilter.type === "token") &&
-            paymentDetailsFilter.conversionRefundNeeded !== undefined
+              paymentDetailsFilter.type === "token" ||
+              paymentDetailsFilter.type === "lightning") &&
+            paymentDetailsFilter.conversionFilter !== undefined
           ) {
+            // 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 = true"
-                : "p.spark IS NULL";
-            const refundNeeded =
-              paymentDetailsFilter.conversionRefundNeeded === true
-                ? "= 'refundNeeded'"
-                : "!= 'refundNeeded'";
-            paymentDetailsClauses.push(
-              `${typeCheck} AND pm.conversion_info IS NOT NULL AND
-               pm.conversion_info::jsonb->>'status' ${refundNeeded}`
-            );
+                : paymentDetailsFilter.type === "token"
+                  ? "p.spark IS NULL"
+                  : null;
+            let statusClause;
+            if (paymentDetailsFilter.conversionFilter === "ammRefundNeeded") {
+              statusClause = "pm.conversion_info::jsonb->>'type' = 'amm' AND pm.conversion_info::jsonb->>'status' = 'refundNeeded'";
+            } else if (paymentDetailsFilter.conversionFilter === "orchestraPending") {
+              statusClause = "pm.conversion_info::jsonb->>'type' = 'orchestra' AND pm.conversion_info::jsonb->>'status' NOT IN ('completed', 'failed', 'refunded')";
+            } else if (paymentDetailsFilter.conversionFilter === "boltzPending") {
+              statusClause = "pm.conversion_info::jsonb->>'type' = 'boltz' AND pm.conversion_info::jsonb->>'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
@@ -353,130 +377,192 @@ class PostgresStorage {
     }
   }
 
-  async insertPayment(payment) {
-    try {
-      if (!payment) {
-        throw new StorageError("Payment cannot be null or undefined");
-      }
-
-      await this._withTransaction(async (client) => {
-        const withdrawTxId =
-          payment.details?.type === "withdraw" ? payment.details.txId : null;
-        const depositTxId =
-          payment.details?.type === "deposit" ? payment.details.txId : null;
-        const spark = payment.details?.type === "spark" ? true : null;
+  async applyPaymentUpdate(payment) {
+    if (!payment) {
+      throw new StorageError("Payment cannot be null or undefined");
+    }
 
+    try {
+      return await this._withTransaction(async (client) => {
+        const lockKey = this._paymentUpdateLockKey(payment.id);
         await client.query(
-          `INSERT INTO brz_payments (user_id, id, payment_type, status, amount, fees, timestamp, method, withdraw_tx_id, deposit_tx_id, spark)
-           VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11)
-           ON CONFLICT(user_id, 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`,
-          [
-            this.identity,
-            payment.id,
-            payment.paymentType,
-            payment.status,
-            payment.amount.toString(),
-            payment.fees.toString(),
-            payment.timestamp,
-            payment.method ? JSON.stringify(payment.method) : null,
-            withdrawTxId,
-            depositTxId,
-            spark,
-          ]
+          "SELECT pg_advisory_xact_lock($1::bigint)",
+          [lockKey]
         );
 
-        if (
-          payment.details?.type === "spark" &&
-          (payment.details.invoiceDetails != null ||
-            payment.details.htlcDetails != null)
-        ) {
-          await client.query(
-            `INSERT INTO brz_payment_details_spark (user_id, payment_id, invoice_details, htlc_details)
-             VALUES ($1, $2, $3, $4)
-             ON CONFLICT(user_id, payment_id) DO UPDATE SET
-               invoice_details=COALESCE(EXCLUDED.invoice_details, brz_payment_details_spark.invoice_details),
-               htlc_details=COALESCE(EXCLUDED.htlc_details, brz_payment_details_spark.htlc_details)`,
-            [
-              this.identity,
-              payment.id,
-              payment.details.invoiceDetails
-                ? JSON.stringify(payment.details.invoiceDetails)
-                : null,
-              payment.details.htlcDetails
-                ? JSON.stringify(payment.details.htlcDetails)
-                : null,
-            ]
-          );
-        }
-
-        if (payment.details?.type === "lightning") {
-          await client.query(
-            `INSERT INTO brz_payment_details_lightning
-              (user_id, payment_id, invoice, payment_hash, destination_pubkey, description, preimage, htlc_status, htlc_expiry_time)
-              VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)
-              ON CONFLICT(user_id, 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, brz_payment_details_lightning.preimage),
-                htlc_status=COALESCE(EXCLUDED.htlc_status, brz_payment_details_lightning.htlc_status),
-                htlc_expiry_time=COALESCE(EXCLUDED.htlc_expiry_time, brz_payment_details_lightning.htlc_expiry_time)`,
-            [
-              this.identity,
-              payment.id,
-              payment.details.invoice,
-              payment.details.htlcDetails.paymentHash,
-              payment.details.destinationPubkey,
-              payment.details.description,
-              payment.details.htlcDetails?.preimage,
-              payment.details.htlcDetails?.status ?? null,
-              payment.details.htlcDetails?.expiryTime ?? 0,
-            ]
+        const { rows } = await client.query(
+          "SELECT status FROM brz_payments WHERE user_id = $1 AND id = $2 FOR UPDATE",
+          [this.identity, payment.id]
+        );
+        const stored = rows.length > 0
+          ? this._normalizePaymentStatus(rows[0].status)
+          : null;
+        const next = this._normalizePaymentStatus(payment.status);
+
+        if (stored != null
+            && this._isFinalPaymentStatus(stored)
+            && stored !== next) {
+          console.warn(
+            `Skipping payment update (would replace terminal status): id=${payment.id} stored=${stored} new=${next}`
           );
+          return false;
         }
 
-        if (payment.details?.type === "token") {
-          await client.query(
-            `INSERT INTO brz_payment_details_token
-              (user_id, payment_id, metadata, tx_hash, tx_type, invoice_details)
-              VALUES ($1, $2, $3, $4, $5, $6)
-              ON CONFLICT(user_id, payment_id) DO UPDATE SET
-                metadata=EXCLUDED.metadata,
-                tx_hash=EXCLUDED.tx_hash,
-                tx_type=EXCLUDED.tx_type,
-                invoice_details=COALESCE(EXCLUDED.invoice_details, brz_payment_details_token.invoice_details)`,
-            [
-              this.identity,
-              payment.id,
-              JSON.stringify(payment.details.metadata),
-              payment.details.txHash,
-              payment.details.txType,
-              payment.details.invoiceDetails
-                ? JSON.stringify(payment.details.invoiceDetails)
-                : null,
-            ]
+        const sameStatus = stored === next;
+        if (sameStatus) {
+          console.debug(
+            `Skipping redundant payment event: id=${payment.id} status=${next}`
           );
         }
+        await this._runPaymentUpsert(client, payment);
+        return !sameStatus;
       });
     } catch (error) {
       if (error instanceof StorageError) throw error;
       throw new StorageError(
-        `Failed to insert payment '${payment.id}': ${error.message}`,
+        `Failed to apply payment update '${payment.id}': ${error.message}`,
         error
       );
     }
   }
 
+  _paymentUpdateLockKey(paymentId) {
+    return crypto
+      .createHash("sha256")
+      .update("brz_payment_update")
+      .update(this.identity)
+      .update(Buffer.from(paymentId))
+      .digest()
+      .readBigInt64BE(0)
+      .toString();
+  }
+
+  async _runPaymentUpsert(client, payment) {
+    const withdrawTxId =
+      payment.details?.type === "withdraw" ? payment.details.txId : null;
+    const spark = payment.details?.type === "spark" ? true : null;
+
+    await client.query(
+      `INSERT INTO brz_payments (user_id, id, payment_type, status, amount, fees, timestamp, method, withdraw_tx_id, spark)
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)
+       ON CONFLICT(user_id, 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`,
+      [
+        this.identity,
+        payment.id,
+        payment.paymentType,
+        payment.status,
+        payment.amount.toString(),
+        payment.fees.toString(),
+        payment.timestamp,
+        payment.method ? JSON.stringify(payment.method) : null,
+        withdrawTxId,
+        spark,
+      ]
+    );
+
+    if (payment.details?.type === "deposit") {
+      await client.query(
+        `INSERT INTO brz_payment_details_deposit (user_id, payment_id, tx_id, vout)
+         VALUES ($1, $2, $3, $4)
+         ON CONFLICT(user_id, payment_id) DO UPDATE SET
+           tx_id=EXCLUDED.tx_id,
+           vout=EXCLUDED.vout`,
+        [this.identity, payment.id, payment.details.txId, payment.details.vout]
+      );
+    }
+
+    if (
+      payment.details?.type === "spark" &&
+      (payment.details.invoiceDetails != null ||
+        payment.details.htlcDetails != null)
+    ) {
+      await client.query(
+        `INSERT INTO brz_payment_details_spark (user_id, payment_id, invoice_details, htlc_details)
+         VALUES ($1, $2, $3, $4)
+         ON CONFLICT(user_id, payment_id) DO UPDATE SET
+           invoice_details=COALESCE(EXCLUDED.invoice_details, brz_payment_details_spark.invoice_details),
+           htlc_details=COALESCE(EXCLUDED.htlc_details, brz_payment_details_spark.htlc_details)`,
+        [
+          this.identity,
+          payment.id,
+          payment.details.invoiceDetails
+            ? JSON.stringify(payment.details.invoiceDetails)
+            : null,
+          payment.details.htlcDetails
+            ? JSON.stringify(payment.details.htlcDetails)
+            : null,
+        ]
+      );
+    }
+
+    if (payment.details?.type === "lightning") {
+      await client.query(
+        `INSERT INTO brz_payment_details_lightning
+          (user_id, payment_id, invoice, payment_hash, destination_pubkey, description, preimage, htlc_status, htlc_expiry_time)
+          VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)
+          ON CONFLICT(user_id, 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, brz_payment_details_lightning.preimage),
+            htlc_status=COALESCE(EXCLUDED.htlc_status, brz_payment_details_lightning.htlc_status),
+            htlc_expiry_time=COALESCE(EXCLUDED.htlc_expiry_time, brz_payment_details_lightning.htlc_expiry_time)`,
+        [
+          this.identity,
+          payment.id,
+          payment.details.invoice,
+          payment.details.htlcDetails.paymentHash,
+          payment.details.destinationPubkey,
+          payment.details.description,
+          payment.details.htlcDetails?.preimage,
+          payment.details.htlcDetails?.status ?? null,
+          payment.details.htlcDetails?.expiryTime ?? 0,
+        ]
+      );
+    }
+
+    if (payment.details?.type === "token") {
+      await client.query(
+        `INSERT INTO brz_payment_details_token
+          (user_id, payment_id, metadata, tx_hash, tx_type, invoice_details)
+          VALUES ($1, $2, $3, $4, $5, $6)
+          ON CONFLICT(user_id, payment_id) DO UPDATE SET
+            metadata=EXCLUDED.metadata,
+            tx_hash=EXCLUDED.tx_hash,
+            tx_type=EXCLUDED.tx_type,
+            invoice_details=COALESCE(EXCLUDED.invoice_details, brz_payment_details_token.invoice_details)`,
+        [
+          this.identity,
+          payment.id,
+          JSON.stringify(payment.details.metadata),
+          payment.details.txHash,
+          payment.details.txType,
+          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";
+  }
+
   async getPaymentById(id) {
     try {
       if (!id) {
@@ -769,6 +855,13 @@ class PostgresStorage {
           senderComment: row.lnurl_sender_comment || null,
         };
       }
+
+      if (row.conversion_info) {
+        details.conversionInfo =
+          typeof row.conversion_info === "string"
+            ? JSON.parse(row.conversion_info)
+            : row.conversion_info;
+      }
     } else if (row.withdraw_tx_id) {
       details = {
         type: "withdraw",
@@ -778,6 +871,7 @@ class PostgresStorage {
       details = {
         type: "deposit",
         txId: row.deposit_tx_id,
+        vout: Number(row.deposit_vout),
       };
     } else if (row.spark) {
       details = {
@@ -950,6 +1044,74 @@ class PostgresStorage {
     }
   }
 
+  // ===== Cross-Chain Swap Operations =====
+
+  async setCrossChainSwap(swap) {
+    try {
+      await this.pool.query(
+        `INSERT INTO brz_cross_chain_swaps
+           (user_id, provider, id, is_terminal, updated_at, data, secrets)
+         VALUES ($1, $2, $3, $4, $5, $6, $7)
+         ON CONFLICT(user_id, provider, id) DO UPDATE SET
+           is_terminal = EXCLUDED.is_terminal,
+           updated_at = EXCLUDED.updated_at,
+           data = EXCLUDED.data,
+           secrets = EXCLUDED.secrets`,
+        [
+          this.identity,
+          swap.provider,
+          swap.id,
+          swap.isTerminal,
+          swap.updatedAt,
+          swap.data,
+          swap.secrets,
+        ]
+      );
+    } catch (error) {
+      throw new StorageError(
+        `Failed to set cross-chain swap: ${error.message}`,
+        error
+      );
+    }
+  }
+
+  async getCrossChainSwap(provider, id) {
+    try {
+      const result = await this.pool.query(
+        `SELECT provider, id, is_terminal, updated_at, data, secrets
+         FROM brz_cross_chain_swaps
+         WHERE user_id = $1 AND provider = $2 AND id = $3`,
+        [this.identity, provider, id]
+      );
+      if (result.rows.length === 0) {
+        return null;
+      }
+      return crossChainSwapFromRow(result.rows[0]);
+    } catch (error) {
+      throw new StorageError(
+        `Failed to get cross-chain swap: ${error.message}`,
+        error
+      );
+    }
+  }
+
+  async listActiveCrossChainSwaps(provider) {
+    try {
+      const result = await this.pool.query(
+        `SELECT provider, id, is_terminal, updated_at, data, secrets
+         FROM brz_cross_chain_swaps
+         WHERE user_id = $1 AND provider = $2 AND is_terminal = FALSE`,
+        [this.identity, provider]
+      );
+      return result.rows.map(crossChainSwapFromRow);
+    } catch (error) {
+      throw new StorageError(
+        `Failed to list active cross-chain swaps: ${error.message}`,
+        error
+      );
+    }
+  }
+
   // ===== Sync Operations =====
 
   async syncAddOutgoingChange(record) {
@@ -1376,6 +1538,21 @@ class PostgresStorage {
   }
 }
 
+/**
+ * Maps a brz_cross_chain_swaps row to the camelCase StoredCrossChainSwap shape
+ * the SDK expects.
+ */
+function crossChainSwapFromRow(row) {
+  return {
+    provider: row.provider,
+    id: row.id,
+    isTerminal: row.is_terminal,
+    updatedAt: Number(row.updated_at),
+    data: row.data,
+    secrets: row.secrets,
+  };
+}
+
 /**
  * Creates a PostgresStorageConfig with the given connection string and default pool settings.
  *

package/nodejs/postgres-storage/migrations.cjs

@@ -467,6 +467,57 @@ class PostgresMigrationManager {
              ON brz_sync_incoming(user_id, revision)`,
         ],
       },
+      {
+        // Move deposit details into their own table so vout can be NOT NULL and
+        // the schema matches brz_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 brz_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 brz_payment_details_deposit table",
+        sql: [
+          `CREATE TABLE IF NOT EXISTS brz_payment_details_deposit (
+              user_id BYTEA NOT NULL,
+              payment_id TEXT NOT NULL,
+              tx_id TEXT NOT NULL,
+              vout BIGINT NOT NULL,
+              PRIMARY KEY (user_id, payment_id)
+          )`,
+          `ALTER TABLE brz_payments DROP COLUMN IF EXISTS deposit_tx_id`,
+          `UPDATE brz_settings
+           SET value = jsonb_set(value::jsonb, '{offset}', '0')::text
+           WHERE key = 'sync_offset' AND value IS NOT NULL`,
+        ],
+      },
+      {
+        name: "Backfill conversion_info type discriminator",
+        sql: [
+          `UPDATE brz_payment_metadata SET conversion_info = conversion_info::jsonb || '{"type": "amm"}'::jsonb WHERE conversion_info IS NOT NULL AND conversion_info::jsonb->>'type' IS NULL`,
+        ],
+      },
+      {
+        // Cross-chain swap rows, synced for cross-instance recovery. Shared
+        // across providers, discriminated by `provider`. Born multi-tenant
+        // (user_id in the PK). `data` is provider-opaque JSON; `secrets` is
+        // provider-opaque ciphertext (empty when the provider has none).
+        name: "Create brz_cross_chain_swaps table",
+        sql: [
+          `CREATE TABLE IF NOT EXISTS brz_cross_chain_swaps (
+              user_id BYTEA NOT NULL,
+              provider TEXT NOT NULL,
+              id TEXT NOT NULL,
+              is_terminal BOOLEAN NOT NULL,
+              updated_at BIGINT NOT NULL,
+              data TEXT NOT NULL,
+              secrets TEXT NOT NULL,
+              PRIMARY KEY (user_id, provider, id)
+          )`,
+          `CREATE INDEX brz_idx_cross_chain_swaps_user_provider_is_terminal
+             ON brz_cross_chain_swaps(user_id, provider, is_terminal)`,
+        ],
+      },
     ];
   }
 }