@wopr-network/platform-core 1.48.0 → 1.49.1

package/dist/billing/crypto/watcher-service.js

@@ -4,8 +4,8 @@
  * Payment flow:
  *   1. Watcher detects payment → handlePayment()
  *   2. Accumulate native amount (supports partial payments)
- *   3. When totalReceived >= expectedAmount → settle + credit
- *   4. Every payment (partial or full) enqueues a webhook delivery
+ *   3. When totalReceived >= expectedAmount AND confirmations >= required → confirmed + credit
+ *   4. Every payment/confirmation change enqueues a webhook delivery
  *   5. Outbox processor retries failed deliveries with exponential backoff
  *
  * Amount comparison is ALWAYS in native crypto units (sats, wei, token base units).
@@ -90,14 +90,19 @@ async function processDeliveries(db, allowedPrefixes, log) {
     }
     return delivered;
 }
-// --- Payment handling (partial + full) ---
 /**
  * Handle a payment event. Accumulates partial payments in native units.
- * Settles when totalReceived >= expectedAmount. Fires webhook on every payment.
+ * Fires webhook on every payment/confirmation change with canonical statuses.
  *
- * @param nativeAmount — received amount in native base units (sats for BTC/DOGE, raw token units for ERC20)
+ * 3-phase webhook lifecycle:
+ *   1. Tx first seen -> status: "partial", confirmations: 0
+ *   2. Each new block -> status: "partial", confirmations: current
+ *   3. Threshold reached + full payment -> status: "confirmed"
+ *
+ * @param nativeAmount — received amount in native base units (sats for BTC/DOGE, raw token units for ERC20).
+ *                        Pass "0" for confirmation-only updates (no new payment, just more confirmations).
  */
-async function handlePayment(db, chargeStore, address, nativeAmount, payload, log) {
+export async function handlePayment(db, chargeStore, address, nativeAmount, payload, log) {
     const charge = await chargeStore.getByDepositAddress(address);
     if (!charge) {
         log("Payment to unknown address", { address });
@@ -106,39 +111,59 @@ async function handlePayment(db, chargeStore, address, nativeAmount, payload, lo
     if (charge.creditedAt) {
         return; // Already fully paid and credited
     }
-    // Accumulate: add this payment to the running total
+    const { confirmations, confirmationsRequired, amountReceivedCents, txHash } = payload;
+    // Accumulate: add this payment to the running total (if nativeAmount > 0)
     const prevReceived = BigInt(charge.receivedAmount ?? "0");
     const thisPayment = BigInt(nativeAmount);
     const totalReceived = (prevReceived + thisPayment).toString();
     const expected = BigInt(charge.expectedAmount ?? "0");
     const isFull = expected > 0n && BigInt(totalReceived) >= expected;
-    // Update received_amount in DB
-    await db
-        .update(cryptoCharges)
-        .set({ receivedAmount: totalReceived, filledAmount: totalReceived })
-        .where(eq(cryptoCharges.referenceId, charge.referenceId));
-    if (isFull) {
-        const settled = "Settled";
-        await chargeStore.updateStatus(charge.referenceId, settled, charge.token ?? undefined, totalReceived);
+    const isConfirmed = isFull && confirmations >= confirmationsRequired;
+    // Update received_amount in DB (only when there's a new payment)
+    if (thisPayment > 0n) {
+        await db
+            .update(cryptoCharges)
+            .set({ receivedAmount: totalReceived, filledAmount: totalReceived })
+            .where(eq(cryptoCharges.referenceId, charge.referenceId));
+    }
+    // Determine canonical status
+    const status = isConfirmed ? "confirmed" : "partial";
+    // Update progress via new API
+    await chargeStore.updateProgress(charge.referenceId, {
+        status,
+        amountReceivedCents,
+        confirmations,
+        confirmationsRequired,
+        txHash,
+    });
+    if (isConfirmed) {
         await chargeStore.markCredited(charge.referenceId);
-        log("Charge settled", { chargeId: charge.referenceId, expected: expected.toString(), received: totalReceived });
+        log("Charge confirmed", {
+            chargeId: charge.referenceId,
+            confirmations,
+            confirmationsRequired,
+        });
     }
     else {
-        const processing = "Processing";
-        await chargeStore.updateStatus(charge.referenceId, processing, charge.token ?? undefined, totalReceived);
-        log("Partial payment", { chargeId: charge.referenceId, expected: expected.toString(), received: totalReceived });
+        log("Payment progress", {
+            chargeId: charge.referenceId,
+            confirmations,
+            confirmationsRequired,
+            received: totalReceived,
+        });
     }
-    // Webhook on every payment — product shows progress to user
+    // Webhook on every event — product shows confirmation progress to user
     if (charge.callbackUrl) {
         await enqueueWebhook(db, charge.referenceId, charge.callbackUrl, {
             chargeId: charge.referenceId,
             chain: charge.chain,
             address: charge.depositAddress,
-            expectedAmount: expected.toString(),
-            receivedAmount: totalReceived,
-            amountUsdCents: charge.amountUsdCents,
-            status: isFull ? "confirmed" : "partial",
-            ...payload,
+            amountExpectedCents: charge.amountUsdCents,
+            amountReceivedCents,
+            confirmations,
+            confirmationsRequired,
+            txHash,
+            status,
         });
     }
 }
@@ -181,11 +206,19 @@ export async function startWatchers(opts) {
             oracle,
             cursorStore,
             onPayment: async (event) => {
-                log("UTXO payment", { chain: method.chain, address: event.address, txid: event.txid, sats: event.amountSats });
-                // Pass native amount (sats) — NOT USD cents
+                log("UTXO payment", {
+                    chain: method.chain,
+                    address: event.address,
+                    txid: event.txid,
+                    sats: event.amountSats,
+                    confirmations: event.confirmations,
+                    confirmationsRequired: event.confirmationsRequired,
+                });
                 await handlePayment(db, chargeStore, event.address, String(event.amountSats), {
                     txHash: event.txid,
                     confirmations: event.confirmations,
+                    confirmationsRequired: event.confirmationsRequired,
+                    amountReceivedCents: event.amountUsdCents,
                 }, log);
             },
         });
@@ -247,11 +280,19 @@ export async function startWatchers(opts) {
             watchedAddresses: chainAddresses,
             cursorStore,
             onPayment: async (event) => {
-                log("EVM payment", { chain: event.chain, token: event.token, to: event.to, txHash: event.txHash });
-                // Pass native amount (raw token units) — NOT USD cents
+                log("EVM payment", {
+                    chain: event.chain,
+                    token: event.token,
+                    to: event.to,
+                    txHash: event.txHash,
+                    confirmations: event.confirmations,
+                    confirmationsRequired: event.confirmationsRequired,
+                });
                 await handlePayment(db, chargeStore, event.to, event.rawAmount, {
                     txHash: event.txHash,
-                    confirmations: method.confirmations,
+                    confirmations: event.confirmations,
+                    confirmationsRequired: event.confirmationsRequired,
+                    amountReceivedCents: event.amountUsdCents,
                 }, log);
             },
         });

package/dist/db/schema/crypto.d.ts

@@ -282,6 +282,74 @@ export declare const cryptoCharges: import("drizzle-orm/pg-core").PgTableWithCol
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        confirmations: import("drizzle-orm/pg-core").PgColumn<{
+            name: "confirmations";
+            tableName: "crypto_charges";
+            dataType: "number";
+            columnType: "PgInteger";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        confirmationsRequired: import("drizzle-orm/pg-core").PgColumn<{
+            name: "confirmations_required";
+            tableName: "crypto_charges";
+            dataType: "number";
+            columnType: "PgInteger";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        txHash: import("drizzle-orm/pg-core").PgColumn<{
+            name: "tx_hash";
+            tableName: "crypto_charges";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        amountReceivedCents: import("drizzle-orm/pg-core").PgColumn<{
+            name: "amount_received_cents";
+            tableName: "crypto_charges";
+            dataType: "number";
+            columnType: "PgInteger";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
     };
     dialect: "pg";
 }>;

package/dist/db/schema/crypto.js

@@ -27,6 +27,14 @@ export const cryptoCharges = pgTable("crypto_charges", {
     expectedAmount: text("expected_amount"),
     /** Running total of received crypto in native units. Accumulates across partial payments. */
     receivedAmount: text("received_amount"),
+    /** Number of blockchain confirmations observed so far. */
+    confirmations: integer("confirmations").notNull().default(0),
+    /** Required confirmations for settlement (copied from payment method at creation). */
+    confirmationsRequired: integer("confirmations_required").notNull().default(1),
+    /** Blockchain transaction hash for the payment. */
+    txHash: text("tx_hash"),
+    /** Amount received so far in USD cents (integer). Converted from crypto at time of receipt. */
+    amountReceivedCents: integer("amount_received_cents").notNull().default(0),
 }, (table) => [
     index("idx_crypto_charges_tenant").on(table.tenantId),
     index("idx_crypto_charges_status").on(table.status),

package/dist/monetization/crypto/__tests__/webhook.test.js

@@ -120,7 +120,8 @@ describe("handleCryptoWebhook (monetization layer)", () => {
         it("updates charge status on every webhook call", async () => {
             await handleCryptoWebhook(deps, makePayload({ status: "partial" }));
             const charge = await chargeStore.getByReferenceId("chg-test-001");
-            expect(charge?.status).toBe("partial");
+            // DB stores legacy status values; "partial" maps to "Processing" internally
+            expect(charge?.status).toBe("Processing");
         });
         it("settles charge when status is confirmed", async () => {
             await handleCryptoWebhook(deps, makePayload({ status: "confirmed" }));

package/drizzle/migrations/0016_charge_progress_columns.sql

@@ -0,0 +1,4 @@
+ALTER TABLE "crypto_charges" ADD COLUMN "confirmations" integer DEFAULT 0 NOT NULL;--> statement-breakpoint
+ALTER TABLE "crypto_charges" ADD COLUMN "confirmations_required" integer DEFAULT 1 NOT NULL;--> statement-breakpoint
+ALTER TABLE "crypto_charges" ADD COLUMN "tx_hash" text;--> statement-breakpoint
+ALTER TABLE "crypto_charges" ADD COLUMN "amount_received_cents" integer DEFAULT 0 NOT NULL;

package/drizzle/migrations/meta/_journal.json

@@ -113,6 +113,13 @@
       "when": 1742918400000,
       "tag": "0015_callback_url",
       "breakpoints": true
+    },
+    {
+      "idx": 16,
+      "version": "7",
+      "when": 1743004800000,
+      "tag": "0016_charge_progress_columns",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wopr-network/platform-core",
-  "version": "1.48.0",
+  "version": "1.49.1",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/billing/crypto/__tests__/key-server.test.ts

@@ -110,7 +110,7 @@ function mockDeps(): KeyServerDeps & {
     db: createMockDb() as never,
     chargeStore: chargeStore as never,
     methodStore: methodStore as never,
-    oracle: { getPrice: vi.fn().mockResolvedValue({ priceCents: 6_500_000, updatedAt: new Date() }) } as never,
+    oracle: { getPrice: vi.fn().mockResolvedValue({ priceMicros: 65_000_000_000, updatedAt: new Date() }) } as never,
   };
 }
 

package/src/billing/crypto/__tests__/unified-checkout.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it, vi } from "vitest";
+import type { CryptoServiceClient } from "../client.js";
+import { createUnifiedCheckout, MIN_CHECKOUT_USD } from "../unified-checkout.js";
+
+function mockCryptoService(): CryptoServiceClient {
+  return {
+    createCharge: vi.fn().mockResolvedValue({
+      chargeId: "btc:bc1qtest",
+      address: "bc1qtest",
+      chain: "bitcoin",
+      token: "BTC",
+      amountUsd: 50,
+      displayAmount: "0.00076923 BTC",
+      derivationIndex: 7,
+      expiresAt: "2026-03-21T23:00:00Z",
+    }),
+    listChains: vi.fn(),
+    deriveAddress: vi.fn(),
+    getCharge: vi.fn(),
+  } as unknown as CryptoServiceClient;
+}
+
+describe("createUnifiedCheckout", () => {
+  it("delegates to CryptoServiceClient.createCharge", async () => {
+    const service = mockCryptoService();
+    const result = await createUnifiedCheckout({ cryptoService: service }, "btc", { tenant: "t-1", amountUsd: 50 });
+
+    expect(result.depositAddress).toBe("bc1qtest");
+    expect(result.displayAmount).toBe("0.00076923 BTC");
+    expect(result.amountUsd).toBe(50);
+    expect(result.token).toBe("BTC");
+    expect(result.chain).toBe("bitcoin");
+    expect(result.referenceId).toBe("btc:bc1qtest");
+
+    expect(service.createCharge).toHaveBeenCalledWith({
+      chain: "btc",
+      amountUsd: 50,
+      callbackUrl: undefined,
+    });
+  });
+
+  it("passes callbackUrl to createCharge", async () => {
+    const service = mockCryptoService();
+    await createUnifiedCheckout({ cryptoService: service }, "base-usdc", {
+      tenant: "t-1",
+      amountUsd: 25,
+      callbackUrl: "https://example.com/hook",
+    });
+
+    expect(service.createCharge).toHaveBeenCalledWith({
+      chain: "base-usdc",
+      amountUsd: 25,
+      callbackUrl: "https://example.com/hook",
+    });
+  });
+
+  it("rejects amount below minimum", async () => {
+    const service = mockCryptoService();
+    await expect(
+      createUnifiedCheckout({ cryptoService: service }, "btc", { tenant: "t-1", amountUsd: 5 }),
+    ).rejects.toThrow(`Minimum payment amount is $${MIN_CHECKOUT_USD}`);
+
+    expect(service.createCharge).not.toHaveBeenCalled();
+  });
+
+  it("rejects non-finite amount", async () => {
+    const service = mockCryptoService();
+    await expect(
+      createUnifiedCheckout({ cryptoService: service }, "btc", { tenant: "t-1", amountUsd: NaN }),
+    ).rejects.toThrow(`Minimum payment amount is $${MIN_CHECKOUT_USD}`);
+  });
+
+  it("propagates createCharge errors", async () => {
+    const service = mockCryptoService();
+    (service.createCharge as ReturnType<typeof vi.fn>).mockRejectedValue(
+      new Error("CryptoService createCharge failed (500): Internal Server Error"),
+    );
+
+    await expect(
+      createUnifiedCheckout({ cryptoService: service }, "btc", { tenant: "t-1", amountUsd: 50 }),
+    ).rejects.toThrow("CryptoService createCharge failed (500)");
+  });
+});

package/src/billing/crypto/__tests__/watcher-service.test.ts

@@ -0,0 +1,242 @@
+import { describe, expect, it, vi } from "vitest";
+import { handlePayment } from "../watcher-service.js";
+
+function mockChargeStore(overrides: Record<string, unknown> = {}) {
+  return {
+    getByDepositAddress: vi.fn().mockResolvedValue({
+      referenceId: "btc:test",
+      tenantId: "t1",
+      amountUsdCents: 5000,
+      creditedAt: null,
+      chain: "bitcoin",
+      depositAddress: "bc1qtest",
+      token: "BTC",
+      callbackUrl: "https://example.com/hook",
+      expectedAmount: "50000",
+      receivedAmount: "0",
+      confirmations: 0,
+      confirmationsRequired: 6,
+      ...overrides,
+    }),
+    updateProgress: vi.fn().mockResolvedValue(undefined),
+    updateStatus: vi.fn().mockResolvedValue(undefined),
+    markCredited: vi.fn().mockResolvedValue(undefined),
+  };
+}
+
+function mockDb() {
+  return {
+    insert: vi.fn().mockReturnValue({ values: vi.fn().mockResolvedValue(undefined) }),
+    update: vi.fn().mockReturnValue({
+      set: vi.fn().mockReturnValue({ where: vi.fn().mockResolvedValue(undefined) }),
+    }),
+  };
+}
+
+const noop = () => {};
+
+describe("handlePayment", () => {
+  it("fires webhook with confirmations: 0 on first tx detection", async () => {
+    const chargeStore = mockChargeStore();
+    const db = mockDb();
+    const enqueuedPayloads: Record<string, unknown>[] = [];
+    db.insert = vi.fn().mockReturnValue({
+      values: vi.fn().mockImplementation((val: Record<string, unknown>) => {
+        if (val.payload) enqueuedPayloads.push(JSON.parse(val.payload as string));
+        return Promise.resolve(undefined);
+      }),
+    });
+
+    await handlePayment(
+      db as never,
+      chargeStore as never,
+      "bc1qtest",
+      "50000",
+      {
+        txHash: "abc123",
+        confirmations: 0,
+        confirmationsRequired: 6,
+        amountReceivedCents: 5000,
+      },
+      noop,
+    );
+
+    expect(enqueuedPayloads).toHaveLength(1);
+    expect(enqueuedPayloads[0]).toMatchObject({
+      chargeId: "btc:test",
+      status: "partial",
+      confirmations: 0,
+      confirmationsRequired: 6,
+    });
+  });
+
+  it("fires webhook on each confirmation increment", async () => {
+    const chargeStore = mockChargeStore({ confirmations: 2 });
+    const db = mockDb();
+    const enqueuedPayloads: Record<string, unknown>[] = [];
+    db.insert = vi.fn().mockReturnValue({
+      values: vi.fn().mockImplementation((val: Record<string, unknown>) => {
+        if (val.payload) enqueuedPayloads.push(JSON.parse(val.payload as string));
+        return Promise.resolve(undefined);
+      }),
+    });
+
+    await handlePayment(
+      db as never,
+      chargeStore as never,
+      "bc1qtest",
+      "0", // no additional payment, just confirmation update
+      {
+        txHash: "abc123",
+        confirmations: 3,
+        confirmationsRequired: 6,
+        amountReceivedCents: 5000,
+      },
+      noop,
+    );
+
+    expect(enqueuedPayloads).toHaveLength(1);
+    expect(enqueuedPayloads[0]).toMatchObject({
+      status: "partial",
+      confirmations: 3,
+      confirmationsRequired: 6,
+    });
+  });
+
+  it("fires final webhook with status confirmed at threshold", async () => {
+    const chargeStore = mockChargeStore({
+      receivedAmount: "50000",
+      confirmations: 5,
+    });
+    const db = mockDb();
+    const enqueuedPayloads: Record<string, unknown>[] = [];
+    db.insert = vi.fn().mockReturnValue({
+      values: vi.fn().mockImplementation((val: Record<string, unknown>) => {
+        if (val.payload) enqueuedPayloads.push(JSON.parse(val.payload as string));
+        return Promise.resolve(undefined);
+      }),
+    });
+
+    await handlePayment(
+      db as never,
+      chargeStore as never,
+      "bc1qtest",
+      "0",
+      {
+        txHash: "abc123",
+        confirmations: 6,
+        confirmationsRequired: 6,
+        amountReceivedCents: 5000,
+      },
+      noop,
+    );
+
+    expect(enqueuedPayloads).toHaveLength(1);
+    expect(enqueuedPayloads[0]).toMatchObject({
+      status: "confirmed",
+      confirmations: 6,
+      confirmationsRequired: 6,
+    });
+    expect(chargeStore.markCredited).toHaveBeenCalledOnce();
+  });
+
+  it("all webhooks use canonical status values only", async () => {
+    const chargeStore = mockChargeStore();
+    const db = mockDb();
+    const enqueuedPayloads: Record<string, unknown>[] = [];
+    db.insert = vi.fn().mockReturnValue({
+      values: vi.fn().mockImplementation((val: Record<string, unknown>) => {
+        if (val.payload) enqueuedPayloads.push(JSON.parse(val.payload as string));
+        return Promise.resolve(undefined);
+      }),
+    });
+
+    await handlePayment(
+      db as never,
+      chargeStore as never,
+      "bc1qtest",
+      "50000",
+      {
+        txHash: "abc123",
+        confirmations: 0,
+        confirmationsRequired: 6,
+        amountReceivedCents: 5000,
+      },
+      noop,
+    );
+
+    const validStatuses = ["pending", "partial", "confirmed", "expired", "failed"];
+    for (const payload of enqueuedPayloads) {
+      expect(validStatuses).toContain(payload.status);
+    }
+    // Must NEVER contain legacy statuses
+    for (const payload of enqueuedPayloads) {
+      expect(payload.status).not.toBe("Settled");
+      expect(payload.status).not.toBe("Processing");
+      expect(payload.status).not.toBe("New");
+    }
+  });
+
+  it("updates charge progress via updateProgress()", async () => {
+    const chargeStore = mockChargeStore();
+    const db = mockDb();
+    db.insert = vi.fn().mockReturnValue({
+      values: vi.fn().mockResolvedValue(undefined),
+    });
+
+    await handlePayment(
+      db as never,
+      chargeStore as never,
+      "bc1qtest",
+      "25000",
+      {
+        txHash: "abc123",
+        confirmations: 2,
+        confirmationsRequired: 6,
+        amountReceivedCents: 2500,
+      },
+      noop,
+    );
+
+    expect(chargeStore.updateProgress).toHaveBeenCalledWith("btc:test", {
+      status: "partial",
+      amountReceivedCents: 2500,
+      confirmations: 2,
+      confirmationsRequired: 6,
+      txHash: "abc123",
+    });
+  });
+
+  it("skips already-credited charges", async () => {
+    const chargeStore = mockChargeStore({ creditedAt: "2026-01-01" });
+    const db = mockDb();
+
+    await handlePayment(
+      db as never,
+      chargeStore as never,
+      "bc1qtest",
+      "50000",
+      { txHash: "abc123", confirmations: 6, confirmationsRequired: 6, amountReceivedCents: 5000 },
+      noop,
+    );
+
+    expect(chargeStore.updateProgress).not.toHaveBeenCalled();
+  });
+
+  it("skips unknown addresses", async () => {
+    const chargeStore = mockChargeStore();
+    chargeStore.getByDepositAddress.mockResolvedValue(null);
+    const db = mockDb();
+
+    await handlePayment(
+      db as never,
+      chargeStore as never,
+      "bc1qunknown",
+      "50000",
+      { txHash: "abc123", confirmations: 0, confirmationsRequired: 6, amountReceivedCents: 5000 },
+      noop,
+    );
+
+    expect(chargeStore.updateProgress).not.toHaveBeenCalled();
+  });
+});