@breeztech/breez-sdk-spark 0.15.1 → 0.17.0

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`;
 
@@ -99,6 +105,21 @@ function toBool(value) {
   return value === 1 || value === "1" || value === true;
 }
 
+/**
+ * Maps a brz_cross_chain_swaps row to the camelCase StoredCrossChainSwap shape
+ * the SDK expects, coercing TINYINT(1) to a boolean.
+ */
+function crossChainSwapFromRow(row) {
+  return {
+    provider: row.provider,
+    id: row.id,
+    isTerminal: toBool(row.is_terminal),
+    updatedAt: Number(row.updated_at),
+    data: row.data,
+    secrets: row.secrets,
+  };
+}
+
 class MysqlStorage {
   /**
    * @param {import('mysql2/promise').Pool} pool - Connection pool (may be shared with other tenants).
@@ -254,6 +275,17 @@ class MysqlStorage {
         for (const paymentDetailsFilter of request.paymentDetailsFilter) {
           const paymentDetailsClauses = [];
 
+          // Base type check: ensure payment type matches the filter type.
+          // Token payments are identified by spark = NULL AND a token row
+          // joined in via t.tx_hash.
+          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");
+          }
+
           const htlcAlias =
             paymentDetailsFilter.type === "spark"
               ? "s"
@@ -278,23 +310,40 @@ class MysqlStorage {
             params.push(...paymentDetailsFilter.htlcStatus);
           }
 
+          // Conversion filter — same enum shape as the Rust storage backend:
+          //   "ammRefundNeeded"   → AMM conversion that needs a clawback
+          //   "orchestraPending"  → Orchestra order not yet terminal
+          //   "boltzPending"      → Boltz reverse swap not yet terminal
+          //                         (lives on the Lightning hold-invoice leg)
           if (
             (paymentDetailsFilter.type === "spark" ||
-              paymentDetailsFilter.type === "token") &&
-            paymentDetailsFilter.conversionRefundNeeded !== undefined
+              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_UNQUOTE(JSON_EXTRACT(pm.conversion_info, '$.status')) ${refundNeeded}`
-            );
+            let statusClause;
+            if (paymentDetailsFilter.conversionFilter === "ammRefundNeeded") {
+              statusClause =
+                "JSON_UNQUOTE(JSON_EXTRACT(pm.conversion_info, '$.type')) = 'amm' AND \
+                 JSON_UNQUOTE(JSON_EXTRACT(pm.conversion_info, '$.status')) = 'refundNeeded'";
+            } else if (
+              paymentDetailsFilter.conversionFilter === "orchestraPending"
+            ) {
+              statusClause =
+                "JSON_UNQUOTE(JSON_EXTRACT(pm.conversion_info, '$.type')) = 'orchestra' AND \
+                 JSON_UNQUOTE(JSON_EXTRACT(pm.conversion_info, '$.status')) NOT IN ('completed', 'failed', 'refunded')";
+            } else if (
+              paymentDetailsFilter.conversionFilter === "boltzPending"
+            ) {
+              statusClause =
+                "JSON_UNQUOTE(JSON_EXTRACT(pm.conversion_info, '$.type')) = 'boltz' AND \
+                 JSON_UNQUOTE(JSON_EXTRACT(pm.conversion_info, '$.status')) NOT IN ('completed', 'failed', 'refunded')";
+            }
+            if (statusClause) {
+              paymentDetailsClauses.push(
+                `pm.conversion_info IS NOT NULL AND ${statusClause}`
+              );
+            }
           }
 
           if (
@@ -360,130 +409,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) {
@@ -764,6 +920,10 @@ class MysqlStorage {
           senderComment: row.lnurl_sender_comment || null,
         };
       }
+
+      if (row.conversion_info) {
+        details.conversionInfo = parseJson(row.conversion_info);
+      }
     } else if (row.withdraw_tx_id) {
       details = {
         type: "withdraw",
@@ -773,6 +933,7 @@ class MysqlStorage {
       details = {
         type: "deposit",
         txId: row.deposit_tx_id,
+        vout: Number(row.deposit_vout),
       };
     } else if (toBool(row.spark)) {
       details = {
@@ -916,6 +1077,74 @@ class MysqlStorage {
     }
   }
 
+  // ===== 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 (?, ?, ?, ?, ?, ?, ?)
+         ON DUPLICATE KEY UPDATE
+           is_terminal = VALUES(is_terminal),
+           updated_at = VALUES(updated_at),
+           data = VALUES(data),
+           secrets = VALUES(secrets)`,
+        [
+          this.identity,
+          swap.provider,
+          swap.id,
+          swap.isTerminal ? 1 : 0,
+          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 [rows] = await this.pool.query(
+        `SELECT provider, id, is_terminal, updated_at, data, secrets
+         FROM brz_cross_chain_swaps
+         WHERE user_id = ? AND provider = ? AND id = ?`,
+        [this.identity, provider, id]
+      );
+      if (rows.length === 0) {
+        return null;
+      }
+      return crossChainSwapFromRow(rows[0]);
+    } catch (error) {
+      throw new StorageError(
+        `Failed to get cross-chain swap: ${error.message}`,
+        error
+      );
+    }
+  }
+
+  async listActiveCrossChainSwaps(provider) {
+    try {
+      const [rows] = await this.pool.query(
+        `SELECT provider, id, is_terminal, updated_at, data, secrets
+         FROM brz_cross_chain_swaps
+         WHERE user_id = ? AND provider = ? AND is_terminal = FALSE`,
+        [this.identity, provider]
+      );
+      return rows.map(crossChainSwapFromRow);
+    } catch (error) {
+      throw new StorageError(
+        `Failed to list active cross-chain swaps: ${error.message}`,
+        error
+      );
+    }
+  }
+
   // ===== Sync Operations =====
 
   async syncAddOutgoingChange(record) {
@@ -1332,6 +1561,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,71 @@ 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, 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 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`,
+        ],
+      },
+      {
+        // Backfill the conversion_info `type` discriminator for the
+        // ConversionInfo enum refactor. All existing rows are AMM.
+        // Mirrors the Rust mysql migration of the same name.
+        name: "Backfill conversion_info type discriminator",
+        sql: [
+          `UPDATE brz_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`. 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 VARBINARY(33) NOT NULL,
+              provider VARCHAR(64) NOT NULL,
+              id VARCHAR(255) NOT NULL,
+              is_terminal TINYINT(1) NOT NULL,
+              updated_at BIGINT NOT NULL,
+              data LONGTEXT NOT NULL,
+              secrets LONGTEXT NOT NULL,
+              PRIMARY KEY (user_id, provider, id),
+              INDEX brz_idx_cross_chain_swaps_user_provider_is_terminal
+                  (user_id, provider, is_terminal)
+          )`,
+        ],
+      },
     ];
   }
 }