@breeztech/breez-sdk-spark 0.9.1 → 0.11.0-dev1

package/nodejs/postgres-storage/migrations.cjs

@@ -0,0 +1,241 @@
+/**
+ * Database Migration Manager for Breez SDK PostgreSQL Storage
+ *
+ * Uses a schema_migrations table + pg_advisory_xact_lock to safely run
+ * migrations from concurrent processes.
+ */
+
+const { StorageError } = require("./errors.cjs");
+
+/**
+ * Advisory lock ID for migrations.
+ * Derived from ASCII bytes of "MIGR" (0x4D49_4752).
+ */
+const MIGRATION_LOCK_ID = "1296388946"; // 0x4D494752 as decimal string
+
+class PostgresMigrationManager {
+  constructor(logger = null) {
+    this.logger = logger;
+  }
+
+  /**
+   * Run all pending migrations inside a single transaction with an advisory lock.
+   * @param {import('pg').Pool} pool
+   */
+  async migrate(pool) {
+    const client = await pool.connect();
+    try {
+      await client.query("BEGIN");
+
+      // Transaction-level advisory lock — automatically released on COMMIT/ROLLBACK
+      await client.query(`SELECT pg_advisory_xact_lock(${MIGRATION_LOCK_ID})`);
+
+      // Create the migrations tracking table if needed
+      await client.query(`
+        CREATE TABLE IF NOT EXISTS schema_migrations (
+          version INTEGER PRIMARY KEY,
+          applied_at TIMESTAMPTZ DEFAULT NOW()
+        )
+      `);
+
+      // Get current version
+      const versionResult = await client.query(
+        "SELECT COALESCE(MAX(version), 0) AS version FROM schema_migrations"
+      );
+      const currentVersion = versionResult.rows[0].version;
+
+      const migrations = this._getMigrations();
+
+      if (currentVersion >= migrations.length) {
+        this._log("info", `Database is up to date (version ${currentVersion})`);
+        await client.query("COMMIT");
+        return;
+      }
+
+      this._log(
+        "info",
+        `Migrating database from version ${currentVersion} to ${migrations.length}`
+      );
+
+      for (let i = currentVersion; i < migrations.length; i++) {
+        const migration = migrations[i];
+        const version = i + 1;
+        this._log("debug", `Running migration ${version}: ${migration.name}`);
+
+        for (const sql of migration.sql) {
+          await client.query(sql);
+        }
+
+        await client.query(
+          "INSERT INTO schema_migrations (version) VALUES ($1)",
+          [version]
+        );
+      }
+
+      await client.query("COMMIT");
+      this._log("info", "Database migration completed successfully");
+    } catch (error) {
+      await client.query("ROLLBACK").catch(() => {});
+      throw new StorageError(
+        `Migration failed: ${error.message}`,
+        error
+      );
+    } finally {
+      client.release();
+    }
+  }
+
+  _log(level, message) {
+    if (this.logger && typeof this.logger.log === "function") {
+      this.logger.log({ line: message, level });
+    } else if (level === "error") {
+      console.error(`[PostgresMigrationManager] ${message}`);
+    }
+  }
+
+  /**
+   * Single migration creating all tables at their final schema.
+   * This mirrors the Rust-native PostgresStorage schema but uses camelCase
+   * enum values (as produced by the WASM bridge).
+   */
+  _getMigrations() {
+    return [
+      {
+        name: "Create all tables at final schema",
+        sql: [
+          // -- Core tables --
+          `CREATE TABLE IF NOT EXISTS payments (
+            id TEXT PRIMARY KEY,
+            payment_type TEXT NOT NULL,
+            status TEXT NOT NULL,
+            amount TEXT NOT NULL,
+            fees TEXT NOT NULL,
+            timestamp BIGINT NOT NULL,
+            method TEXT,
+            withdraw_tx_id TEXT,
+            deposit_tx_id TEXT,
+            spark BOOLEAN
+          )`,
+
+          `CREATE TABLE IF NOT EXISTS settings (
+            key TEXT PRIMARY KEY,
+            value TEXT NOT NULL
+          )`,
+
+          `CREATE TABLE IF NOT EXISTS unclaimed_deposits (
+            txid TEXT NOT NULL,
+            vout INTEGER NOT NULL,
+            amount_sats BIGINT,
+            claim_error JSONB,
+            refund_tx TEXT,
+            refund_tx_id TEXT,
+            PRIMARY KEY (txid, vout)
+          )`,
+
+          `CREATE TABLE IF NOT EXISTS payment_metadata (
+            payment_id TEXT PRIMARY KEY,
+            parent_payment_id TEXT,
+            lnurl_pay_info JSONB,
+            lnurl_withdraw_info JSONB,
+            lnurl_description TEXT,
+            conversion_info JSONB
+          )`,
+
+          `CREATE TABLE IF NOT EXISTS payment_details_lightning (
+            payment_id TEXT PRIMARY KEY,
+            invoice TEXT NOT NULL,
+            payment_hash TEXT NOT NULL,
+            destination_pubkey TEXT NOT NULL,
+            description TEXT,
+            preimage TEXT,
+            htlc_status TEXT NOT NULL,
+            htlc_expiry_time BIGINT NOT NULL
+          )`,
+
+          `CREATE TABLE IF NOT EXISTS payment_details_token (
+            payment_id TEXT PRIMARY KEY,
+            metadata JSONB NOT NULL,
+            tx_hash TEXT NOT NULL,
+            tx_type TEXT NOT NULL,
+            invoice_details JSONB
+          )`,
+
+          `CREATE TABLE IF NOT EXISTS payment_details_spark (
+            payment_id TEXT PRIMARY KEY,
+            invoice_details JSONB,
+            htlc_details JSONB
+          )`,
+
+          `CREATE TABLE IF NOT EXISTS lnurl_receive_metadata (
+            payment_hash TEXT PRIMARY KEY,
+            nostr_zap_request TEXT,
+            nostr_zap_receipt TEXT,
+            sender_comment TEXT,
+            preimage TEXT
+          )`,
+
+          // -- Sync tables --
+          `CREATE TABLE IF NOT EXISTS sync_revision (
+            id INTEGER PRIMARY KEY DEFAULT 1,
+            revision BIGINT NOT NULL DEFAULT 0,
+            CHECK (id = 1)
+          )`,
+          `INSERT INTO sync_revision (id, revision) VALUES (1, 0) ON CONFLICT (id) DO NOTHING`,
+
+          `CREATE TABLE IF NOT EXISTS sync_outgoing (
+            record_type TEXT NOT NULL,
+            data_id TEXT NOT NULL,
+            schema_version TEXT NOT NULL,
+            commit_time BIGINT NOT NULL,
+            updated_fields_json JSONB NOT NULL,
+            revision BIGINT NOT NULL
+          )`,
+
+          `CREATE TABLE IF NOT EXISTS sync_state (
+            record_type TEXT NOT NULL,
+            data_id TEXT NOT NULL,
+            schema_version TEXT NOT NULL,
+            commit_time BIGINT NOT NULL,
+            data JSONB NOT NULL,
+            revision BIGINT NOT NULL,
+            PRIMARY KEY (record_type, data_id)
+          )`,
+
+          `CREATE TABLE IF NOT EXISTS sync_incoming (
+            record_type TEXT NOT NULL,
+            data_id TEXT NOT NULL,
+            schema_version TEXT NOT NULL,
+            commit_time BIGINT NOT NULL,
+            data JSONB NOT NULL,
+            revision BIGINT NOT NULL,
+            PRIMARY KEY (record_type, data_id, revision)
+          )`,
+
+          // -- Indexes --
+          `CREATE INDEX IF NOT EXISTS idx_payments_timestamp ON payments(timestamp)`,
+          `CREATE INDEX IF NOT EXISTS idx_payments_payment_type ON payments(payment_type)`,
+          `CREATE INDEX IF NOT EXISTS idx_payments_status ON payments(status)`,
+          `CREATE INDEX IF NOT EXISTS idx_payment_details_lightning_invoice ON payment_details_lightning(invoice)`,
+          `CREATE INDEX IF NOT EXISTS idx_payment_details_lightning_payment_hash ON payment_details_lightning(payment_hash)`,
+          `CREATE INDEX IF NOT EXISTS idx_payment_metadata_parent ON payment_metadata(parent_payment_id)`,
+          `CREATE INDEX IF NOT EXISTS idx_sync_outgoing_data_id_record_type ON sync_outgoing(record_type, data_id)`,
+          `CREATE INDEX IF NOT EXISTS idx_sync_incoming_revision ON sync_incoming(revision)`,
+        ],
+      },
+      {
+        name: "Create contacts table",
+        sql: [
+          `CREATE TABLE IF NOT EXISTS contacts (
+            id TEXT PRIMARY KEY,
+            name TEXT NOT NULL,
+            payment_identifier TEXT NOT NULL,
+            created_at BIGINT NOT NULL,
+            updated_at BIGINT NOT NULL
+          )`,
+        ],
+      },
+    ];
+  }
+}
+
+module.exports = { PostgresMigrationManager };

package/nodejs/postgres-storage/package.json

@@ -0,0 +1,9 @@
+{
+  "dependencies": {
+    "pg": "^8.18.0"
+  },
+  "description": "Node.js PostgreSQL storage implementation for Breez SDK WASM (CommonJS)",
+  "main": "index.cjs",
+  "name": "@breez-sdk/postgres-storage",
+  "version": "1.0.0"
+}

package/nodejs/storage/index.cjs

@@ -62,6 +62,7 @@ const SELECT_PAYMENT_SQL = `
            lrm.nostr_zap_request AS lnurl_nostr_zap_request,
            lrm.nostr_zap_receipt AS lnurl_nostr_zap_receipt,
            lrm.sender_comment AS lnurl_sender_comment,
+           lrm.payment_hash AS lnurl_payment_hash,
            pm.parent_payment_id
       FROM payments p
       LEFT JOIN payment_details_lightning l ON p.id = l.payment_id
@@ -259,6 +260,19 @@ class SqliteStorage {
             paymentDetailsClauses.push("t.tx_type = ?");
             params.push(paymentDetailsFilter.txType);
           }
+          // Filter by LNURL preimage status
+          if (
+            paymentDetailsFilter.type === "lightning" &&
+            paymentDetailsFilter.hasLnurlPreimage !== undefined
+          ) {
+            if (paymentDetailsFilter.hasLnurlPreimage) {
+              paymentDetailsClauses.push("lrm.preimage IS NOT NULL");
+            } else {
+              paymentDetailsClauses.push(
+                "lrm.payment_hash IS NOT NULL AND l.preimage IS NOT NULL AND lrm.preimage IS NULL"
+              );
+            }
+          }
 
 
           if (paymentDetailsClauses.length > 0) {
@@ -406,8 +420,8 @@ class SqliteStorage {
             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,
+            htlcStatus: payment.details.htlcDetails?.status ?? null,
+            htlcExpiryTime: payment.details.htlcDetails?.expiryTime ?? 0,
           });
         }
 
@@ -681,7 +695,7 @@ class SqliteStorage {
   setLnurlMetadata(metadata) {
     try {
       const stmt = this.db.prepare(
-        "INSERT OR REPLACE INTO lnurl_receive_metadata (payment_hash, nostr_zap_request, nostr_zap_receipt, sender_comment) VALUES (?, ?, ?, ?)"
+        "INSERT OR REPLACE INTO lnurl_receive_metadata (payment_hash, nostr_zap_request, nostr_zap_receipt, sender_comment, preimage) VALUES (?, ?, ?, ?, ?)"
       );
 
       const transaction = this.db.transaction(() => {
@@ -690,7 +704,8 @@ class SqliteStorage {
             item.paymentHash,
             item.nostrZapRequest || null,
             item.nostrZapReceipt || null,
-            item.senderComment || null
+            item.senderComment || null,
+            item.preimage || null
           );
         }
       });
@@ -721,7 +736,7 @@ class SqliteStorage {
           ? {
               paymentHash: row.lightning_payment_hash,
               preimage: row.lightning_preimage || null,
-              expiryTime: row.lightning_htlc_expiry_time || 0,
+              expiryTime: row.lightning_htlc_expiry_time ?? 0,
               status: row.lightning_htlc_status,
             }
           : (() => { throw new StorageError(`htlc_status is required for Lightning payment ${row.id}`); })(),
@@ -749,7 +764,7 @@ class SqliteStorage {
         }
       }
 
-      if (row.lnurl_nostr_zap_request || row.lnurl_sender_comment) {
+      if (row.lnurl_payment_hash) {
         details.lnurlReceiveMetadata = {
           nostrZapRequest: row.lnurl_nostr_zap_request || null,
           nostrZapReceipt: row.lnurl_nostr_zap_receipt || null,
@@ -815,6 +830,7 @@ class SqliteStorage {
       timestamp: row.timestamp,
       method,
       details,
+      conversionDetails: null,
     };
   }
 
@@ -1239,6 +1255,84 @@ class SqliteStorage {
       );
     }
   }
+
+  // ===== Contact Operations =====
+
+  listContacts(request) {
+    try {
+      const offset = request.offset !== null && request.offset !== undefined ? request.offset : 0;
+      const limit = request.limit !== null && request.limit !== undefined ? request.limit : 4294967295;
+
+      const stmt = this.db.prepare(`
+        SELECT id, name, payment_identifier AS paymentIdentifier, created_at AS createdAt, updated_at AS updatedAt
+        FROM contacts
+        ORDER BY name ASC
+        LIMIT ? OFFSET ?
+      `);
+      const rows = stmt.all(limit, offset);
+
+      return Promise.resolve(rows);
+    } catch (error) {
+      return Promise.reject(
+        new StorageError(`Failed to list contacts: ${error.message}`, error)
+      );
+    }
+  }
+
+  getContact(id) {
+    try {
+      const stmt = this.db.prepare(`
+        SELECT id, name, payment_identifier AS paymentIdentifier, created_at AS createdAt, updated_at AS updatedAt
+        FROM contacts
+        WHERE id = ?
+      `);
+      const row = stmt.get(id);
+      return Promise.resolve(row || null);
+    } catch (error) {
+      return Promise.reject(
+        new StorageError(`Failed to get contact: ${error.message}`, error)
+      );
+    }
+  }
+
+  insertContact(contact) {
+    try {
+      const stmt = this.db.prepare(`
+        INSERT INTO contacts (id, name, payment_identifier, created_at, updated_at)
+        VALUES (?, ?, ?, ?, ?)
+        ON CONFLICT(id) DO UPDATE SET
+          name = excluded.name,
+          payment_identifier = excluded.payment_identifier,
+          updated_at = excluded.updated_at
+      `);
+
+      stmt.run(
+        contact.id,
+        contact.name,
+        contact.paymentIdentifier,
+        contact.createdAt,
+        contact.updatedAt
+      );
+
+      return Promise.resolve();
+    } catch (error) {
+      return Promise.reject(
+        new StorageError(`Failed to insert contact: ${error.message}`, error)
+      );
+    }
+  }
+
+  deleteContact(id) {
+    try {
+      const stmt = this.db.prepare("DELETE FROM contacts WHERE id = ?");
+      stmt.run(id);
+      return Promise.resolve();
+    } catch (error) {
+      return Promise.reject(
+        new StorageError(`Failed to delete contact: ${error.message}`, error)
+      );
+    }
+  }
 }
 
 async function createDefaultStorage(dataDir, logger = null) {

package/nodejs/storage/migrations.cjs

@@ -344,6 +344,13 @@ class MigrationManager {
           `DELETE FROM sync_state`,
           `UPDATE sync_revision SET revision = 0`,
           `DELETE FROM settings WHERE key = 'sync_initial_complete'`
+        ],
+      },
+      {
+        name: "Add preimage column to lnurl_receive_metadata for LUD-21 and NIP-57",
+        sql: [
+          `ALTER TABLE lnurl_receive_metadata ADD COLUMN preimage TEXT`,
+          `DELETE FROM settings WHERE key = 'lnurl_metadata_updated_after'`
         ]
       },
       {
@@ -367,6 +374,24 @@ class MigrationManager {
            WHERE key = 'sync_offset' AND json_valid(value)`,
         ]
       },
+      {
+        name: "Clear cached lightning address for LnurlInfo schema change",
+        sql: `DELETE FROM settings WHERE key = 'lightning_address'`
+      },
+      {
+        name: "Add index on payment_hash for JOIN with lnurl_receive_metadata",
+        sql: `CREATE INDEX IF NOT EXISTS idx_payment_details_lightning_payment_hash ON payment_details_lightning(payment_hash)`
+      },
+      {
+        name: "Create contacts table",
+        sql: `CREATE TABLE contacts (
+          id TEXT PRIMARY KEY,
+          name TEXT NOT NULL,
+          payment_identifier TEXT NOT NULL,
+          created_at INTEGER NOT NULL,
+          updated_at INTEGER NOT NULL
+        )`
+      },
     ];
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@breeztech/breez-sdk-spark",
-    "version": "0.9.1",
+    "version": "0.11.0-dev1",
     "description": "Breez Spark SDK",
     "repository": "https://github.com/breez/spark-sdk",
     "author": "Breez <contact@breez.technology> (https://github.com/breez)",
@@ -34,6 +34,7 @@
         "node": ">=22"
     },
     "optionalDependencies": {
-        "better-sqlite3": "^12.2.0"
+        "better-sqlite3": "^12.2.0",
+        "pg": "^8.18.0"
     }
 }