@wopr-network/platform-core 1.47.0 → 1.49.0

package/dist/billing/crypto/btc/__tests__/watcher.test.js

@@ -0,0 +1,170 @@
+import { describe, expect, it, vi } from "vitest";
+import { BtcWatcher } from "../watcher.js";
+function makeCursorStore() {
+    const processed = new Set();
+    const confirmationCounts = new Map();
+    return {
+        get: vi.fn().mockResolvedValue(null),
+        save: vi.fn().mockResolvedValue(undefined),
+        hasProcessedTx: vi.fn().mockImplementation(async (_, txId) => processed.has(txId)),
+        markProcessedTx: vi.fn().mockImplementation(async (_, txId) => {
+            processed.add(txId);
+        }),
+        getConfirmationCount: vi
+            .fn()
+            .mockImplementation(async (_, txId) => confirmationCounts.get(txId) ?? null),
+        saveConfirmationCount: vi.fn().mockImplementation(async (_, txId, count) => {
+            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 = [];
+        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 = [];
+        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 = [];
+        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 = [];
+        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 = [];
+        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 = [];
+        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/dist/billing/crypto/btc/types.d.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. */
 export interface BtcCheckoutOpts {

package/dist/billing/crypto/btc/watcher.d.ts

@@ -31,7 +31,12 @@ export declare class BtcWatcher {
      * Uses `importdescriptors` (modern bitcoind v24+) with fallback to legacy `importaddress`.
      */
     importAddress(address: string): Promise<void>;
-    /** 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.
+     */
     poll(): Promise<void>;
 }
 /** Create a bitcoind JSON-RPC caller with basic auth. */

package/dist/billing/crypto/btc/watcher.js

@@ -40,12 +40,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() {
         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
         ]));
@@ -54,7 +60,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
@@ -62,8 +68,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 = {
                     address: entry.address,
@@ -71,10 +80,15 @@ 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/dist/billing/crypto/charge-store.d.ts

@@ -1,5 +1,5 @@
 import type { PlatformDb } from "../../db/index.js";
-import type { CryptoPaymentState } from "./types.js";
+import type { CryptoCharge, CryptoChargeStatus, CryptoPaymentState } from "./types.js";
 export interface CryptoChargeRecord {
     referenceId: string;
     tenantId: string;
@@ -17,6 +17,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 {
     referenceId: string;
@@ -30,10 +34,22 @@ export interface CryptoDepositChargeInput {
     /** Expected crypto amount in native base units (sats for BTC, base units for ERC20). */
     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>;
@@ -63,7 +79,16 @@ export declare class DrizzleCryptoChargeRepository implements ICryptoChargeRepos
     /** Get a charge by reference ID. Returns null if not found. */
     getByReferenceId(referenceId: string): Promise<CryptoChargeRecord | null>;
     private toRecord;
-    /** Update charge status and payment details from webhook. */
+    /** Map DB status strings to CryptoChargeStatus for UI consumption. */
+    private mapStatus;
+    /** Get a charge as a UI-facing CryptoCharge with all progress fields. */
+    get(referenceId: string): Promise<CryptoCharge | null>;
+    /** Update partial payment progress, confirmations, and tx hash. */
+    updateProgress(referenceId: string, update: CryptoChargeProgressUpdate): Promise<void>;
+    /**
+     * @deprecated Use updateProgress() instead. Kept for one release cycle.
+     * Update charge status and payment details from webhook.
+     */
     updateStatus(referenceId: string, status: CryptoPaymentState, currency?: string, filledAmount?: string): Promise<void>;
     /** Mark a charge as credited (idempotency flag). */
     markCredited(referenceId: string): Promise<void>;

package/dist/billing/crypto/charge-store.js

@@ -49,9 +49,75 @@ export class DrizzleCryptoChargeRepository {
             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,
         };
     }
-    /** Update charge status and payment details from webhook. */
+    /** Map DB status strings to CryptoChargeStatus for UI consumption. */
+    mapStatus(dbStatus, credited) {
+        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) {
+        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 partial payment progress, confirmations, and tx hash. */
+    async updateProgress(referenceId, update) {
+        const statusMap = {
+            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, status, currency, filledAmount) {
         await this.db
             .update(cryptoCharges)

package/dist/billing/crypto/charge-store.test.js

@@ -26,12 +26,16 @@ 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 () => {
         const charge = await store.getByReferenceId("inv-nonexistent");
         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");
         const charge = await store.getByReferenceId("inv-002");
@@ -61,6 +65,181 @@ describe("CryptoChargeRepository", () => {
         await store.markCredited("inv-006");
         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/dist/billing/crypto/client.d.ts

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

package/dist/billing/crypto/cursor-store.d.ts

@@ -4,17 +4,22 @@ 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.
  */
@@ -25,4 +30,6 @@ export declare class DrizzleWatcherCursorStore implements IWatcherCursorStore {
     save(watcherId: string, cursorBlock: number): Promise<void>;
     hasProcessedTx(watcherId: string, txId: string): Promise<boolean>;
     markProcessedTx(watcherId: string, txId: string): Promise<void>;
+    getConfirmationCount(watcherId: string, txId: string): Promise<number | null>;
+    saveConfirmationCount(watcherId: string, txId: string, count: number): Promise<void>;
 }

package/dist/billing/crypto/cursor-store.js

@@ -3,9 +3,10 @@ import { watcherCursors, watcherProcessed } from "../../db/schema/crypto.js";
 /**
  * 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.
  */
@@ -40,4 +41,23 @@ export class DrizzleWatcherCursorStore {
     async markProcessedTx(watcherId, txId) {
         await this.db.insert(watcherProcessed).values({ watcherId, txId }).onConflictDoNothing();
     }
+    async getConfirmationCount(watcherId, txId) {
+        // 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, txId, count) {
+        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())` },
+        });
+    }
 }