@breeztech/breez-sdk-spark 0.15.1 → 0.16.1-dev1

package/nodejs/mysql-storage/index.cjs

@@ -16,6 +16,8 @@
  *   → `conn.beginTransaction()`/`conn.commit()`/`conn.rollback()`.
  */
 
+const crypto = require("crypto");
+
 let mysql;
 try {
   const mainModule = require.main;
@@ -38,6 +40,8 @@ try {
 const { StorageError } = require("./errors.cjs");
 const { MysqlMigrationManager } = require("./migrations.cjs");
 
+const PAYMENT_UPDATE_LOCK_TIMEOUT_SECS = 10;
+
 /**
  * Base query for payment lookups. All columns are accessed by name in _rowToPayment.
  * parent_payment_id is only used by getPaymentsByParentIds.
@@ -51,7 +55,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,
@@ -79,6 +84,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`;
 
@@ -360,130 +366,237 @@ class MysqlStorage {
     }
   }
 
-  async insertPayment(payment) {
+  async applyPaymentUpdate(payment) {
+    if (!payment) {
+      throw new StorageError("Payment cannot be null or undefined");
+    }
+
+    let conn = null;
+    const lockName = this._paymentUpdateLockName(payment.id);
+    let acquired = false;
+    let shouldEmit = false;
+    let operationError = null;
+    let releaseError = null;
+
     try {
-      if (!payment) {
-        throw new StorageError("Payment cannot be null or undefined");
+      conn = await this.pool.getConnection();
+      const [lockRows] = await conn.query("SELECT GET_LOCK(?, ?) AS acquired", [
+        lockName,
+        PAYMENT_UPDATE_LOCK_TIMEOUT_SECS,
+      ]);
+      acquired = Number(lockRows?.[0]?.acquired) === 1;
+      if (!acquired) {
+        throw new StorageError(`Timed out acquiring payment update lock '${lockName}'`);
       }
 
-      await this._withTransaction(async (conn) => {
-        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" ? 1 : null;
-
-        await conn.query(
-          `INSERT INTO brz_payments (user_id, id, payment_type, status, amount, fees, timestamp, method, withdraw_tx_id, deposit_tx_id, spark)
-           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-           ON DUPLICATE KEY UPDATE
-             payment_type=VALUES(payment_type),
-             status=VALUES(status),
-             amount=VALUES(amount),
-             fees=VALUES(fees),
-             timestamp=VALUES(timestamp),
-             method=VALUES(method),
-             withdraw_tx_id=VALUES(withdraw_tx_id),
-             deposit_tx_id=VALUES(deposit_tx_id),
-             spark=VALUES(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,
-          ]
+      await conn.query("SET TRANSACTION ISOLATION LEVEL READ COMMITTED");
+      await conn.beginTransaction();
+      try {
+        const [rows] = await conn.query(
+          "SELECT status FROM brz_payments WHERE user_id = ? AND id = ? FOR UPDATE",
+          [this.identity, payment.id]
         );
-
-        if (
-          payment.details?.type === "spark" &&
-          (payment.details.invoiceDetails != null ||
-            payment.details.htlcDetails != null)
-        ) {
-          await conn.query(
-            `INSERT INTO brz_payment_details_spark (user_id, payment_id, invoice_details, htlc_details)
-             VALUES (?, ?, ?, ?)
-             ON DUPLICATE KEY UPDATE
-               invoice_details=COALESCE(VALUES(invoice_details), invoice_details),
-               htlc_details=COALESCE(VALUES(htlc_details), htlc_details)`,
-            [
-              this.identity,
-              payment.id,
-              payment.details.invoiceDetails
-                ? JSON.stringify(payment.details.invoiceDetails)
-                : null,
-              payment.details.htlcDetails
-                ? JSON.stringify(payment.details.htlcDetails)
-                : null,
-            ]
+        const stored = rows.length > 0
+          ? this._normalizePaymentStatus(rows[0].status)
+          : null;
+        const next = this._normalizePaymentStatus(payment.status);
+
+        if (stored == null) {
+          await this._runPaymentUpsert(conn, payment);
+          shouldEmit = true;
+        } else if (stored === next) {
+          console.debug(
+            `Skipping redundant payment event: id=${payment.id} status=${next}`
           );
-        }
-
-        if (payment.details?.type === "lightning") {
-          await conn.query(
-            `INSERT INTO brz_payment_details_lightning
-              (user_id, payment_id, invoice, payment_hash, destination_pubkey, description, preimage, htlc_status, htlc_expiry_time)
-              VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
-              ON DUPLICATE KEY UPDATE
-                invoice=VALUES(invoice),
-                payment_hash=VALUES(payment_hash),
-                destination_pubkey=VALUES(destination_pubkey),
-                description=VALUES(description),
-                preimage=COALESCE(VALUES(preimage), preimage),
-                htlc_status=COALESCE(VALUES(htlc_status), htlc_status),
-                htlc_expiry_time=COALESCE(VALUES(htlc_expiry_time), 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,
-            ]
+          await this._runPaymentUpsert(conn, 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 {
+          await this._runPaymentUpsert(conn, payment);
+          shouldEmit = true;
         }
 
-        if (payment.details?.type === "token") {
-          await conn.query(
-            `INSERT INTO brz_payment_details_token
-              (user_id, payment_id, metadata, tx_hash, tx_type, invoice_details)
-              VALUES (?, ?, ?, ?, ?, ?)
-              ON DUPLICATE KEY UPDATE
-                metadata=VALUES(metadata),
-                tx_hash=VALUES(tx_hash),
-                tx_type=VALUES(tx_type),
-                invoice_details=COALESCE(VALUES(invoice_details), 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,
-            ]
-          );
-        }
-      });
+        await conn.commit();
+      } catch (error) {
+        await conn.rollback().catch(() => {});
+        throw error;
+      }
     } catch (error) {
-      if (error instanceof StorageError) throw error;
+      operationError = error;
+    } finally {
+      if (conn && acquired) {
+        try {
+          await conn.query("SELECT RELEASE_LOCK(?)", [lockName]);
+        } catch (error) {
+          releaseError = error;
+        }
+      }
+      if (conn) {
+        conn.release();
+      }
+    }
+
+    if (operationError) {
+      if (operationError instanceof StorageError) {
+        throw operationError;
+      }
       throw new StorageError(
-        `Failed to insert payment '${payment.id}': ${error.message}`,
-        error
+        `Failed to apply payment update '${payment.id}': ${operationError.message}`,
+        operationError
       );
     }
+
+    if (releaseError) {
+      throw new StorageError(
+        `Failed to release payment update lock '${lockName}': ${releaseError.message}`,
+        releaseError
+      );
+    }
+
+    return shouldEmit;
   }
 
+  async _runPaymentUpsert(conn, payment) {
+    const withdrawTxId =
+      payment.details?.type === "withdraw" ? payment.details.txId : null;
+    const spark = payment.details?.type === "spark" ? 1 : null;
+
+    await conn.query(
+      `INSERT INTO brz_payments (user_id, id, payment_type, status, amount, fees, timestamp, method, withdraw_tx_id, spark)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+       ON DUPLICATE KEY UPDATE
+         payment_type=VALUES(payment_type),
+         status=VALUES(status),
+         amount=VALUES(amount),
+         fees=VALUES(fees),
+         timestamp=VALUES(timestamp),
+         method=VALUES(method),
+         withdraw_tx_id=VALUES(withdraw_tx_id),
+         spark=VALUES(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 conn.query(
+        `INSERT INTO brz_payment_details_deposit (user_id, payment_id, tx_id, vout)
+         VALUES (?, ?, ?, ?)
+         ON DUPLICATE KEY UPDATE
+           tx_id=VALUES(tx_id),
+           vout=VALUES(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 conn.query(
+        `INSERT INTO brz_payment_details_spark (user_id, payment_id, invoice_details, htlc_details)
+         VALUES (?, ?, ?, ?)
+         ON DUPLICATE KEY UPDATE
+           invoice_details=COALESCE(VALUES(invoice_details), invoice_details),
+           htlc_details=COALESCE(VALUES(htlc_details), 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 conn.query(
+        `INSERT INTO brz_payment_details_lightning
+          (user_id, payment_id, invoice, payment_hash, destination_pubkey, description, preimage, htlc_status, htlc_expiry_time)
+          VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+          ON DUPLICATE KEY UPDATE
+            invoice=VALUES(invoice),
+            payment_hash=VALUES(payment_hash),
+            destination_pubkey=VALUES(destination_pubkey),
+            description=VALUES(description),
+            preimage=COALESCE(VALUES(preimage), preimage),
+            htlc_status=COALESCE(VALUES(htlc_status), htlc_status),
+            htlc_expiry_time=COALESCE(VALUES(htlc_expiry_time), 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 conn.query(
+        `INSERT INTO brz_payment_details_token
+          (user_id, payment_id, metadata, tx_hash, tx_type, invoice_details)
+          VALUES (?, ?, ?, ?, ?, ?)
+          ON DUPLICATE KEY UPDATE
+            metadata=VALUES(metadata),
+            tx_hash=VALUES(tx_hash),
+            tx_type=VALUES(tx_type),
+            invoice_details=COALESCE(VALUES(invoice_details), 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,
+        ]
+      );
+    }
+  }
+
+  _paymentUpdateLockName(paymentId) {
+    return crypto
+      .createHash("sha256")
+      .update("brz_payment_update")
+      .update(this.identity)
+      .update(Buffer.from(paymentId))
+      .digest("hex")
+      .slice(0, 32);
+  }
+
+  _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) {
@@ -773,6 +886,7 @@ class MysqlStorage {
       details = {
         type: "deposit",
         txId: row.deposit_tx_id,
+        vout: Number(row.deposit_vout),
       };
     } else if (toBool(row.spark)) {
       details = {
@@ -1332,6 +1446,10 @@ function createMysqlPool(config) {
     connectTimeout: (config.createTimeoutSecs || 0) * 1000 || 10000,
     idleTimeout: (config.recycleTimeoutSecs || 0) * 1000 || 10000,
     waitForConnections: true,
+    // Serialize JS `Date` parameters as UTC strings rather than host-local
+    // time. Paired with explicit `UTC_TIMESTAMP(6)` on the server side, this
+    // keeps timestamp comparisons consistent regardless of the host TZ.
+    timezone: "Z",
   });
 }
 

package/nodejs/mysql-storage/migrations.cjs

@@ -89,7 +89,7 @@ class MysqlMigrationManager {
         await conn.query(`
           CREATE TABLE IF NOT EXISTS brz_schema_migrations (
             version INT PRIMARY KEY,
-            applied_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6)
+            applied_at DATETIME(6) NOT NULL DEFAULT (UTC_TIMESTAMP(6))
           )
         `);
 
@@ -121,7 +121,7 @@ class MysqlMigrationManager {
           }
 
           await conn.query(
-            "INSERT INTO brz_schema_migrations (version) VALUES (?)",
+            "INSERT INTO brz_schema_migrations (version, applied_at) VALUES (?, UTC_TIMESTAMP(6))",
             [version]
           );
         }
@@ -497,6 +497,41 @@ class MysqlMigrationManager {
              ON brz_sync_incoming(user_id, revision)`,
         ],
       },
+      {
+        // Pin the migration-tracking table's `applied_at` default to UTC.
+        // The migration manager already passes `UTC_TIMESTAMP(6)` explicitly
+        // on INSERT, but aligning the default keeps `SHOW CREATE TABLE`
+        // output consistent with the token-store / tree-store migrations
+        // table and avoids future mistakes if a callsite omits the column.
+        name: "Pin schema-migrations applied_at default to UTC",
+        sql: [
+          `ALTER TABLE brz_schema_migrations MODIFY COLUMN applied_at DATETIME(6) NOT NULL DEFAULT (UTC_TIMESTAMP(6))`,
+        ],
+      },
+      {
+        // 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 — 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 VARBINARY(33) NOT NULL,
+              payment_id VARCHAR(255) NOT NULL,
+              tx_id VARCHAR(255) NOT NULL,
+              vout INT UNSIGNED NOT NULL,
+              PRIMARY KEY (user_id, payment_id)
+          )`,
+          `ALTER TABLE brz_payments DROP COLUMN deposit_tx_id`,
+          `UPDATE brz_settings
+           SET value = JSON_SET(value, '$.offset', 0)
+           WHERE \`key\` = 'sync_offset' AND value IS NOT NULL`,
+        ],
+      },
     ];
   }
 }