@wopr-network/platform-core 1.47.0 → 1.49.0

package/src/billing/crypto/btc/__tests__/watcher.test.ts

@@ -0,0 +1,201 @@
+import { describe, expect, it, vi } from "vitest";
+import { BtcWatcher } from "../watcher.js";
+
+function makeCursorStore() {
+  const processed = new Set<string>();
+  const confirmationCounts = new Map<string, number>();
+  return {
+    get: vi.fn().mockResolvedValue(null),
+    save: vi.fn().mockResolvedValue(undefined),
+    hasProcessedTx: vi.fn().mockImplementation(async (_: string, txId: string) => processed.has(txId)),
+    markProcessedTx: vi.fn().mockImplementation(async (_: string, txId: string) => {
+      processed.add(txId);
+    }),
+    getConfirmationCount: vi
+      .fn()
+      .mockImplementation(async (_: string, txId: string) => confirmationCounts.get(txId) ?? null),
+    saveConfirmationCount: vi.fn().mockImplementation(async (_: string, txId: string, count: number) => {
+      confirmationCounts.set(txId, count);
+    }),
+    _processed: processed,
+    _confirmationCounts: confirmationCounts,
+  };
+}
+
+function makeOracle() {
+  return { getPrice: vi.fn().mockResolvedValue({ priceCents: 6_500_000 }) };
+}
+
+describe("BtcWatcher — intermediate confirmations", () => {
+  it("fires onPayment at 0 confirmations when tx first detected", async () => {
+    const events: Array<{ confirmations: number; confirmationsRequired: number }> = [];
+    const cursorStore = makeCursorStore();
+    const rpc = vi
+      .fn()
+      .mockResolvedValueOnce([{ address: "bc1qtest", amount: 0.0005, confirmations: 0, txids: ["tx1"] }])
+      .mockResolvedValueOnce({
+        details: [{ address: "bc1qtest", amount: 0.0005, category: "receive" }],
+        confirmations: 0,
+      });
+
+    const watcher = new BtcWatcher({
+      config: { rpcUrl: "http://localhost", rpcUser: "u", rpcPassword: "p", network: "regtest", confirmations: 3 },
+      rpcCall: rpc,
+      watchedAddresses: ["bc1qtest"],
+      oracle: makeOracle(),
+      cursorStore,
+      onPayment: (evt) => {
+        events.push(evt);
+      },
+    });
+
+    await watcher.poll();
+
+    expect(events).toHaveLength(1);
+    expect(events[0].confirmations).toBe(0);
+    expect(events[0].confirmationsRequired).toBe(3);
+  });
+
+  it("fires onPayment on each confirmation increment", async () => {
+    const events: Array<{ confirmations: number }> = [];
+    const cursorStore = makeCursorStore();
+    cursorStore._confirmationCounts.set("tx1", 1);
+
+    const rpc = vi
+      .fn()
+      .mockResolvedValueOnce([{ address: "bc1qtest", amount: 0.0005, confirmations: 2, txids: ["tx1"] }])
+      .mockResolvedValueOnce({
+        details: [{ address: "bc1qtest", amount: 0.0005, category: "receive" }],
+        confirmations: 2,
+      });
+
+    const watcher = new BtcWatcher({
+      config: { rpcUrl: "http://localhost", rpcUser: "u", rpcPassword: "p", network: "regtest", confirmations: 3 },
+      rpcCall: rpc,
+      watchedAddresses: ["bc1qtest"],
+      oracle: makeOracle(),
+      cursorStore,
+      onPayment: (evt) => {
+        events.push(evt);
+      },
+    });
+
+    await watcher.poll();
+
+    expect(events).toHaveLength(1);
+    expect(events[0].confirmations).toBe(2);
+  });
+
+  it("does not fire when confirmation count unchanged", async () => {
+    const events: Array<{ confirmations: number }> = [];
+    const cursorStore = makeCursorStore();
+    cursorStore._confirmationCounts.set("tx1", 2);
+
+    const rpc = vi
+      .fn()
+      .mockResolvedValueOnce([{ address: "bc1qtest", amount: 0.0005, confirmations: 2, txids: ["tx1"] }])
+      .mockResolvedValueOnce({
+        details: [{ address: "bc1qtest", amount: 0.0005, category: "receive" }],
+        confirmations: 2,
+      });
+
+    const watcher = new BtcWatcher({
+      config: { rpcUrl: "http://localhost", rpcUser: "u", rpcPassword: "p", network: "regtest", confirmations: 3 },
+      rpcCall: rpc,
+      watchedAddresses: ["bc1qtest"],
+      oracle: makeOracle(),
+      cursorStore,
+      onPayment: (evt) => {
+        events.push(evt);
+      },
+    });
+
+    await watcher.poll();
+
+    expect(events).toHaveLength(0);
+  });
+
+  it("marks tx as processed once confirmations reach threshold", async () => {
+    const events: Array<{ confirmations: number }> = [];
+    const cursorStore = makeCursorStore();
+    cursorStore._confirmationCounts.set("tx1", 2);
+
+    const rpc = vi
+      .fn()
+      .mockResolvedValueOnce([{ address: "bc1qtest", amount: 0.0005, confirmations: 3, txids: ["tx1"] }])
+      .mockResolvedValueOnce({
+        details: [{ address: "bc1qtest", amount: 0.0005, category: "receive" }],
+        confirmations: 3,
+      });
+
+    const watcher = new BtcWatcher({
+      config: { rpcUrl: "http://localhost", rpcUser: "u", rpcPassword: "p", network: "regtest", confirmations: 3 },
+      rpcCall: rpc,
+      watchedAddresses: ["bc1qtest"],
+      oracle: makeOracle(),
+      cursorStore,
+      onPayment: (evt) => {
+        events.push(evt);
+      },
+    });
+
+    await watcher.poll();
+
+    expect(events).toHaveLength(1);
+    expect(events[0].confirmations).toBe(3);
+    expect(cursorStore.markProcessedTx).toHaveBeenCalledWith(expect.any(String), "tx1");
+  });
+
+  it("skips fully-processed txids", async () => {
+    const events: unknown[] = [];
+    const cursorStore = makeCursorStore();
+    cursorStore._processed.add("tx1");
+
+    const rpc = vi
+      .fn()
+      .mockResolvedValueOnce([{ address: "bc1qtest", amount: 0.0005, confirmations: 6, txids: ["tx1"] }]);
+
+    const watcher = new BtcWatcher({
+      config: { rpcUrl: "http://localhost", rpcUser: "u", rpcPassword: "p", network: "regtest", confirmations: 3 },
+      rpcCall: rpc,
+      watchedAddresses: ["bc1qtest"],
+      oracle: makeOracle(),
+      cursorStore,
+      onPayment: (evt) => {
+        events.push(evt);
+      },
+    });
+
+    await watcher.poll();
+
+    expect(events).toHaveLength(0);
+  });
+
+  it("includes confirmationsRequired in event", async () => {
+    const events: Array<{ confirmationsRequired: number }> = [];
+    const cursorStore = makeCursorStore();
+
+    const rpc = vi
+      .fn()
+      .mockResolvedValueOnce([{ address: "bc1qtest", amount: 0.001, confirmations: 0, txids: ["txNew"] }])
+      .mockResolvedValueOnce({
+        details: [{ address: "bc1qtest", amount: 0.001, category: "receive" }],
+        confirmations: 0,
+      });
+
+    const watcher = new BtcWatcher({
+      config: { rpcUrl: "http://localhost", rpcUser: "u", rpcPassword: "p", network: "regtest", confirmations: 6 },
+      rpcCall: rpc,
+      watchedAddresses: ["bc1qtest"],
+      oracle: makeOracle(),
+      cursorStore,
+      onPayment: (evt) => {
+        events.push(evt);
+      },
+    });
+
+    await watcher.poll();
+
+    expect(events[0].confirmationsRequired).toBe(6);
+  });
+});

package/src/billing/crypto/btc/types.ts

@@ -1,4 +1,4 @@
-/** BTC payment event emitted when a deposit is confirmed. */
+/** BTC payment event emitted on each confirmation increment. */
 export interface BtcPaymentEvent {
   readonly address: string;
   readonly txid: string;
@@ -7,6 +7,8 @@ export interface BtcPaymentEvent {
   /** USD cents equivalent (integer). */
   readonly amountUsdCents: number;
   readonly confirmations: number;
+  /** Required confirmations for this chain (from config). */
+  readonly confirmationsRequired: number;
 }
 
 /** Options for creating a BTC checkout. */

package/src/billing/crypto/btc/watcher.ts

@@ -74,12 +74,18 @@ export class BtcWatcher {
     this.addresses.add(address);
   }
 
-  /** Poll for confirmed payments to watched addresses. */
+  /**
+   * Poll for payments to watched addresses, including unconfirmed txs.
+   *
+   * Fires onPayment on every confirmation increment (0, 1, 2, ... threshold).
+   * Only marks a tx as fully processed once it reaches the confirmation threshold.
+   */
   async poll(): Promise<void> {
     if (this.addresses.size === 0) return;
 
+    // Poll with minconf=0 to see unconfirmed txs
     const received = (await this.rpc("listreceivedbyaddress", [
-      this.minConfirmations,
+      0, // minconf=0: see ALL txs including unconfirmed
       false, // include_empty
       true, // include_watchonly
     ])) as ReceivedByAddress[];
@@ -90,7 +96,7 @@ export class BtcWatcher {
       if (!this.addresses.has(entry.address)) continue;
 
       for (const txid of entry.txids) {
-        // Skip already-processed txids (persisted to DB, survives restart)
+        // Skip fully-processed txids (already reached threshold, persisted to DB)
         if (await this.cursorStore.hasProcessedTx(this.watcherId, txid)) continue;
 
         // Get transaction details for the exact amount sent to this address
@@ -102,8 +108,11 @@ export class BtcWatcher {
         const detail = tx.details.find((d) => d.address === entry.address && d.category === "receive");
         if (!detail) continue;
 
+        // Check if confirmations have increased since last seen
+        const lastSeen = await this.cursorStore.getConfirmationCount(this.watcherId, txid);
+        if (lastSeen !== null && tx.confirmations <= lastSeen) continue; // No change
+
         const amountSats = Math.round(detail.amount * 100_000_000);
-        // priceCents is cents per 1 BTC. detail.amount is in BTC.
         const amountUsdCents = Math.round((amountSats * priceCents) / 100_000_000);
 
         const event: BtcPaymentEvent = {
@@ -112,11 +121,18 @@ export class BtcWatcher {
           amountSats,
           amountUsdCents,
           confirmations: tx.confirmations,
+          confirmationsRequired: this.minConfirmations,
         };
 
         await this.onPayment(event);
-        // Persist AFTER successful onPayment — survives restart, no unbounded memory
-        await this.cursorStore.markProcessedTx(this.watcherId, txid);
+
+        // Persist confirmation count
+        await this.cursorStore.saveConfirmationCount(this.watcherId, txid, tx.confirmations);
+
+        // Mark as fully processed once we reach the threshold
+        if (tx.confirmations >= this.minConfirmations) {
+          await this.cursorStore.markProcessedTx(this.watcherId, txid);
+        }
       }
     }
   }

package/src/billing/crypto/charge-store.test.ts

@@ -34,6 +34,10 @@ describe("CryptoChargeRepository", () => {
     expect(charge?.amountUsdCents).toBe(2500);
     expect(charge?.status).toBe("New");
     expect(charge?.creditedAt).toBeNull();
+    expect(charge?.confirmations).toBe(0);
+    expect(charge?.confirmationsRequired).toBe(1);
+    expect(charge?.txHash).toBeNull();
+    expect(charge?.amountReceivedCents).toBe(0);
   });
 
   it("getByReferenceId() returns null when not found", async () => {
@@ -41,7 +45,7 @@ describe("CryptoChargeRepository", () => {
     expect(charge).toBeNull();
   });
 
-  it("updateStatus() updates status, currency and filled_amount", async () => {
+  it("updateStatus() updates status, currency and filled_amount (deprecated compat)", async () => {
     await store.create("inv-002", "tenant-2", 5000);
     await store.updateStatus("inv-002", "Settled", "BTC", "0.00025");
 
@@ -79,6 +83,205 @@ describe("CryptoChargeRepository", () => {
     expect(await store.isCredited("inv-006")).toBe(true);
   });
 
+  describe("updateProgress", () => {
+    it("updates partial payment progress", async () => {
+      await store.createStablecoinCharge({
+        referenceId: "prog-001",
+        tenantId: "t-1",
+        amountUsdCents: 5000,
+        chain: "base",
+        token: "USDC",
+        depositAddress: "0xprog001",
+        derivationIndex: 0,
+      });
+
+      await store.updateProgress("prog-001", {
+        status: "partial",
+        amountReceivedCents: 2500,
+        confirmations: 2,
+        confirmationsRequired: 6,
+        txHash: "0xabc123",
+      });
+
+      const record = await store.getByReferenceId("prog-001");
+      expect(record?.status).toBe("Processing");
+      expect(record?.amountReceivedCents).toBe(2500);
+      expect(record?.confirmations).toBe(2);
+      expect(record?.confirmationsRequired).toBe(6);
+      expect(record?.txHash).toBe("0xabc123");
+    });
+
+    it("increments confirmations over multiple updates", async () => {
+      await store.createStablecoinCharge({
+        referenceId: "prog-002",
+        tenantId: "t-2",
+        amountUsdCents: 1000,
+        chain: "base",
+        token: "USDC",
+        depositAddress: "0xprog002",
+        derivationIndex: 1,
+      });
+
+      await store.updateProgress("prog-002", {
+        status: "partial",
+        amountReceivedCents: 1000,
+        confirmations: 1,
+        confirmationsRequired: 6,
+        txHash: "0xdef456",
+      });
+
+      await store.updateProgress("prog-002", {
+        status: "partial",
+        amountReceivedCents: 1000,
+        confirmations: 3,
+        confirmationsRequired: 6,
+        txHash: "0xdef456",
+      });
+
+      const record = await store.getByReferenceId("prog-002");
+      expect(record?.confirmations).toBe(3);
+    });
+
+    it("maps confirmed status to Settled in DB", async () => {
+      await store.createStablecoinCharge({
+        referenceId: "prog-003",
+        tenantId: "t-3",
+        amountUsdCents: 2000,
+        chain: "base",
+        token: "USDC",
+        depositAddress: "0xprog003",
+        derivationIndex: 2,
+      });
+
+      await store.updateProgress("prog-003", {
+        status: "confirmed",
+        amountReceivedCents: 2000,
+        confirmations: 6,
+        confirmationsRequired: 6,
+        txHash: "0xfinal",
+      });
+
+      const record = await store.getByReferenceId("prog-003");
+      expect(record?.status).toBe("Settled");
+    });
+  });
+
+  describe("get (UI-facing CryptoCharge)", () => {
+    it("returns null when not found", async () => {
+      const charge = await store.get("nonexistent");
+      expect(charge).toBeNull();
+    });
+
+    it("returns full CryptoCharge with all fields for a new charge", async () => {
+      await store.createStablecoinCharge({
+        referenceId: "get-001",
+        tenantId: "t-get",
+        amountUsdCents: 5000,
+        chain: "base",
+        token: "USDC",
+        depositAddress: "0xget001",
+        derivationIndex: 10,
+      });
+
+      const charge = await store.get("get-001");
+      expect(charge).not.toBeNull();
+      expect(charge?.id).toBe("get-001");
+      expect(charge?.tenantId).toBe("t-get");
+      expect(charge?.chain).toBe("base");
+      expect(charge?.status).toBe("pending");
+      expect(charge?.amountExpectedCents).toBe(5000);
+      expect(charge?.amountReceivedCents).toBe(0);
+      expect(charge?.confirmations).toBe(0);
+      expect(charge?.confirmationsRequired).toBe(1);
+      expect(charge?.txHash).toBeUndefined();
+      expect(charge?.credited).toBe(false);
+      expect(charge?.createdAt).toBeInstanceOf(Date);
+    });
+
+    it("reflects partial payment progress", async () => {
+      await store.createStablecoinCharge({
+        referenceId: "get-002",
+        tenantId: "t-get2",
+        amountUsdCents: 5000,
+        chain: "base",
+        token: "USDC",
+        depositAddress: "0xget002",
+        derivationIndex: 11,
+      });
+
+      await store.updateProgress("get-002", {
+        status: "partial",
+        amountReceivedCents: 2500,
+        confirmations: 3,
+        confirmationsRequired: 6,
+        txHash: "0xpartial",
+      });
+
+      const charge = await store.get("get-002");
+      expect(charge?.status).toBe("partial");
+      expect(charge?.amountReceivedCents).toBe(2500);
+      expect(charge?.confirmations).toBe(3);
+      expect(charge?.confirmationsRequired).toBe(6);
+      expect(charge?.txHash).toBe("0xpartial");
+      expect(charge?.credited).toBe(false);
+    });
+
+    it("shows confirmed+credited status after markCredited", async () => {
+      await store.createStablecoinCharge({
+        referenceId: "get-003",
+        tenantId: "t-get3",
+        amountUsdCents: 1000,
+        chain: "base",
+        token: "USDC",
+        depositAddress: "0xget003",
+        derivationIndex: 12,
+      });
+
+      await store.updateProgress("get-003", {
+        status: "confirmed",
+        amountReceivedCents: 1000,
+        confirmations: 6,
+        confirmationsRequired: 6,
+        txHash: "0xfull",
+      });
+      await store.markCredited("get-003");
+
+      const charge = await store.get("get-003");
+      expect(charge?.status).toBe("confirmed");
+      expect(charge?.credited).toBe(true);
+      expect(charge?.amountReceivedCents).toBe(1000);
+    });
+
+    it("maps expired status correctly", async () => {
+      await store.createStablecoinCharge({
+        referenceId: "get-004",
+        tenantId: "t-get4",
+        amountUsdCents: 3000,
+        chain: "base",
+        token: "USDC",
+        depositAddress: "0xget004",
+        derivationIndex: 13,
+      });
+
+      await store.updateProgress("get-004", {
+        status: "expired",
+        amountReceivedCents: 0,
+        confirmations: 0,
+        confirmationsRequired: 6,
+      });
+
+      const charge = await store.get("get-004");
+      expect(charge?.status).toBe("expired");
+    });
+
+    it("returns chain as 'unknown' for legacy charges without chain", async () => {
+      await store.create("get-005", "t-get5", 500);
+
+      const charge = await store.get("get-005");
+      expect(charge?.chain).toBe("unknown");
+    });
+  });
+
   describe("stablecoin charges", () => {
     it("creates a stablecoin charge with chain/token/address", async () => {
       await store.createStablecoinCharge({

package/src/billing/crypto/charge-store.ts

@@ -1,7 +1,7 @@
 import { and, eq, isNotNull, isNull, sql } from "drizzle-orm";
 import type { PlatformDb } from "../../db/index.js";
 import { cryptoCharges } from "../../db/schema/crypto.js";
-import type { CryptoPaymentState } from "./types.js";
+import type { CryptoCharge, CryptoChargeStatus, CryptoPaymentState } from "./types.js";
 
 export interface CryptoChargeRecord {
   referenceId: string;
@@ -20,6 +20,10 @@ export interface CryptoChargeRecord {
   callbackUrl: string | null;
   expectedAmount: string | null;
   receivedAmount: string | null;
+  confirmations: number;
+  confirmationsRequired: number;
+  txHash: string | null;
+  amountReceivedCents: number;
 }
 
 export interface CryptoDepositChargeInput {
@@ -35,15 +39,28 @@ export interface CryptoDepositChargeInput {
   expectedAmount?: string;
 }
 
+export interface CryptoChargeProgressUpdate {
+  status: CryptoChargeStatus;
+  amountReceivedCents: number;
+  confirmations: number;
+  confirmationsRequired: number;
+  txHash?: string;
+}
+
 export interface ICryptoChargeRepository {
   create(referenceId: string, tenantId: string, amountUsdCents: number): Promise<void>;
   getByReferenceId(referenceId: string): Promise<CryptoChargeRecord | null>;
+  /** @deprecated Use updateProgress() instead. Kept for one release cycle. */
   updateStatus(
     referenceId: string,
     status: CryptoPaymentState,
     currency?: string,
     filledAmount?: string,
   ): Promise<void>;
+  /** Update partial payment progress, confirmations, and tx hash. */
+  updateProgress(referenceId: string, update: CryptoChargeProgressUpdate): Promise<void>;
+  /** Get a charge as a UI-facing CryptoCharge with all progress fields. */
+  get(referenceId: string): Promise<CryptoCharge | null>;
   markCredited(referenceId: string): Promise<void>;
   isCredited(referenceId: string): Promise<boolean>;
   createStablecoinCharge(input: CryptoDepositChargeInput): Promise<void>;
@@ -101,10 +118,77 @@ export class DrizzleCryptoChargeRepository implements ICryptoChargeRepository {
       callbackUrl: row.callbackUrl ?? null,
       expectedAmount: row.expectedAmount ?? null,
       receivedAmount: row.receivedAmount ?? null,
+      confirmations: row.confirmations,
+      confirmationsRequired: row.confirmationsRequired,
+      txHash: row.txHash ?? null,
+      amountReceivedCents: row.amountReceivedCents,
+    };
+  }
+
+  /** Map DB status strings to CryptoChargeStatus for UI consumption. */
+  private mapStatus(dbStatus: string, credited: boolean): CryptoChargeStatus {
+    if (credited) return "confirmed";
+    switch (dbStatus) {
+      case "New":
+        return "pending";
+      case "Processing":
+        return "partial";
+      case "Settled":
+        return "confirmed";
+      case "Expired":
+        return "expired";
+      case "Invalid":
+        return "failed";
+      default:
+        return "pending";
+    }
+  }
+
+  /** Get a charge as a UI-facing CryptoCharge with all progress fields. */
+  async get(referenceId: string): Promise<CryptoCharge | null> {
+    const row = (await this.db.select().from(cryptoCharges).where(eq(cryptoCharges.referenceId, referenceId)))[0];
+    if (!row) return null;
+    return {
+      id: row.referenceId,
+      tenantId: row.tenantId,
+      chain: row.chain ?? "unknown",
+      status: this.mapStatus(row.status, row.creditedAt != null),
+      amountExpectedCents: row.amountUsdCents,
+      amountReceivedCents: row.amountReceivedCents,
+      confirmations: row.confirmations,
+      confirmationsRequired: row.confirmationsRequired,
+      txHash: row.txHash ?? undefined,
+      credited: row.creditedAt != null,
+      createdAt: new Date(row.createdAt),
     };
   }
 
-  /** Update charge status and payment details from webhook. */
+  /** Update partial payment progress, confirmations, and tx hash. */
+  async updateProgress(referenceId: string, update: CryptoChargeProgressUpdate): Promise<void> {
+    const statusMap: Record<CryptoChargeStatus, string> = {
+      pending: "New",
+      partial: "Processing",
+      confirmed: "Settled",
+      expired: "Expired",
+      failed: "Invalid",
+    };
+    await this.db
+      .update(cryptoCharges)
+      .set({
+        status: statusMap[update.status],
+        amountReceivedCents: update.amountReceivedCents,
+        confirmations: update.confirmations,
+        confirmationsRequired: update.confirmationsRequired,
+        txHash: update.txHash,
+        updatedAt: sql`now()`,
+      })
+      .where(eq(cryptoCharges.referenceId, referenceId));
+  }
+
+  /**
+   * @deprecated Use updateProgress() instead. Kept for one release cycle.
+   * Update charge status and payment details from webhook.
+   */
   async updateStatus(
     referenceId: string,
     status: CryptoPaymentState,

package/src/billing/crypto/client.ts

@@ -29,6 +29,8 @@ export interface CreateChargeResult {
   amountUsd: number;
   derivationIndex: number;
   expiresAt: string;
+  displayAmount?: string;
+  priceCents?: number;
 }
 
 export interface ChargeStatus {

package/src/billing/crypto/cursor-store.ts

@@ -7,18 +7,23 @@ export interface IWatcherCursorStore {
   get(watcherId: string): Promise<number | null>;
   /** Save block cursor after processing a range. */
   save(watcherId: string, cursorBlock: number): Promise<void>;
-  /** Check if a specific tx has been processed (for watchers without block cursors). */
+  /** Check if a specific tx has been fully processed (reached confirmation threshold). */
   hasProcessedTx(watcherId: string, txId: string): Promise<boolean>;
-  /** Mark a tx as processed (for watchers without block cursors). */
+  /** Mark a tx as fully processed (reached confirmation threshold). */
   markProcessedTx(watcherId: string, txId: string): Promise<void>;
+  /** Get the last-seen confirmation count for a tx (for intermediate confirmation tracking). */
+  getConfirmationCount(watcherId: string, txId: string): Promise<number | null>;
+  /** Save the current confirmation count for a tx (for intermediate confirmation tracking). */
+  saveConfirmationCount(watcherId: string, txId: string, count: number): Promise<void>;
 }
 
 /**
  * Persists watcher state to PostgreSQL.
  *
- * Two patterns:
+ * Three patterns:
  *   - Block cursor (EVM watchers): save/get cursor block number
  *   - Processed txids (BTC watcher): hasProcessedTx/markProcessedTx
+ *   - Confirmation counts (all watchers): getConfirmationCount/saveConfirmationCount
  *
  * Eliminates all in-memory watcher state. Clean restart recovery.
  */
@@ -58,4 +63,27 @@ export class DrizzleWatcherCursorStore implements IWatcherCursorStore {
   async markProcessedTx(watcherId: string, txId: string): Promise<void> {
     await this.db.insert(watcherProcessed).values({ watcherId, txId }).onConflictDoNothing();
   }
+
+  async getConfirmationCount(watcherId: string, txId: string): Promise<number | null> {
+    // Store confirmation counts as synthetic cursor entries: "watcherId:conf:txId" -> count
+    const key = `${watcherId}:conf:${txId}`;
+    const row = (
+      await this.db
+        .select({ cursorBlock: watcherCursors.cursorBlock })
+        .from(watcherCursors)
+        .where(eq(watcherCursors.watcherId, key))
+    )[0];
+    return row?.cursorBlock ?? null;
+  }
+
+  async saveConfirmationCount(watcherId: string, txId: string, count: number): Promise<void> {
+    const key = `${watcherId}:conf:${txId}`;
+    await this.db
+      .insert(watcherCursors)
+      .values({ watcherId: key, cursorBlock: count })
+      .onConflictDoUpdate({
+        target: watcherCursors.watcherId,
+        set: { cursorBlock: count, updatedAt: sql`(now())` },
+      });
+  }
 }