@wopr-network/platform-core 1.48.0 → 1.49.0

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

@@ -1,20 +1,9 @@
-import { Credit } from "../../credits/credit.js";
-import { deriveAddress, deriveP2pkhAddress } from "./btc/address-gen.js";
-import type { ICryptoChargeRepository } from "./charge-store.js";
-import { deriveDepositAddress } from "./evm/address-gen.js";
-import { centsToNative } from "./oracle/convert.js";
-import type { IPriceOracle } from "./oracle/types.js";
-import type { PaymentMethodRecord } from "./payment-method-store.js";
+import type { CryptoServiceClient } from "./client.js";
 
 export const MIN_CHECKOUT_USD = 10;
 
 export interface UnifiedCheckoutDeps {
-  chargeStore: Pick<ICryptoChargeRepository, "getNextDerivationIndex" | "createStablecoinCharge">;
-  oracle: IPriceOracle;
-  evmXpub: string;
-  btcXpub?: string;
-  /** UTXO network override (auto-detected from node in production). Default: "mainnet". */
-  utxoNetwork?: "mainnet" | "testnet" | "regtest";
+  cryptoService: CryptoServiceClient;
 }
 
 export interface UnifiedCheckoutResult {
@@ -30,182 +19,34 @@ export interface UnifiedCheckoutResult {
 }
 
 /**
- * Unified checkout — one entry point for all payment methods.
+ * Unified checkout — delegates to CryptoServiceClient.createCharge().
  *
- * Looks up the method record, routes by type:
- *   - erc20: derives EVM address, computes token amount (1:1 USD for stablecoins)
- *   - native (ETH): derives EVM address, oracle-priced
- *   - native (BTC): derives BTC address, oracle-priced
- *
- * CRITICAL: amountUsd → integer cents via Credit.fromDollars().toCentsRounded().
+ * The pay server handles xpub management, address derivation, and charge
+ * creation. This function is a thin wrapper that validates the amount
+ * and maps the response to `UnifiedCheckoutResult`.
  */
 export async function createUnifiedCheckout(
   deps: UnifiedCheckoutDeps,
-  method: PaymentMethodRecord,
-  opts: { tenant: string; amountUsd: number },
+  chain: string,
+  opts: { tenant: string; amountUsd: number; callbackUrl?: string },
 ): Promise<UnifiedCheckoutResult> {
   if (!Number.isFinite(opts.amountUsd) || opts.amountUsd < MIN_CHECKOUT_USD) {
     throw new Error(`Minimum payment amount is $${MIN_CHECKOUT_USD}`);
   }
 
-  const amountUsdCents = Credit.fromDollars(opts.amountUsd).toCentsRounded();
-
-  if (method.type === "erc20") {
-    return handleErc20(deps, method, opts.tenant, amountUsdCents, opts.amountUsd);
-  }
-  if (method.type === "native" && method.chain === "base") {
-    return handleNativeEvm(deps, method, opts.tenant, amountUsdCents, opts.amountUsd);
-  }
-  if (method.type === "native") {
-    return handleNativeUtxo(deps, method, opts.tenant, amountUsdCents, opts.amountUsd);
-  }
-
-  throw new Error(`Unsupported payment method type: ${method.type}/${method.token}`);
-}
-
-async function handleErc20(
-  deps: UnifiedCheckoutDeps,
-  method: PaymentMethodRecord,
-  tenant: string,
-  amountUsdCents: number,
-  amountUsd: number,
-): Promise<UnifiedCheckoutResult> {
-  const depositAddress = await deriveAndStore(deps, method, tenant, amountUsdCents);
+  const result = await deps.cryptoService.createCharge({
+    chain,
+    amountUsd: opts.amountUsd,
+    callbackUrl: opts.callbackUrl,
+  });
 
   return {
-    depositAddress,
-    displayAmount: `${amountUsd} ${method.token}`,
-    amountUsd,
-    token: method.token,
-    chain: method.chain,
-    referenceId: `erc20:${method.chain}:${depositAddress}`,
+    depositAddress: result.address,
+    displayAmount: result.displayAmount ?? `${opts.amountUsd} ${result.token}`,
+    amountUsd: opts.amountUsd,
+    token: result.token,
+    chain: result.chain,
+    referenceId: result.chargeId,
+    priceCents: result.priceCents,
   };
 }
-
-async function handleNativeEvm(
-  deps: UnifiedCheckoutDeps,
-  method: PaymentMethodRecord,
-  tenant: string,
-  amountUsdCents: number,
-  amountUsd: number,
-): Promise<UnifiedCheckoutResult> {
-  const { priceCents } = await deps.oracle.getPrice("ETH");
-  const expectedWei = centsToNative(amountUsdCents, priceCents, 18);
-  const depositAddress = await deriveAndStore(deps, method, tenant, amountUsdCents);
-
-  const divisor = BigInt("1000000000000000000");
-  const whole = expectedWei / divisor;
-  const frac = (expectedWei % divisor).toString().padStart(18, "0").slice(0, 6);
-
-  return {
-    depositAddress,
-    displayAmount: `${whole}.${frac} ETH`,
-    amountUsd,
-    token: "ETH",
-    chain: method.chain,
-    referenceId: `${method.type}:${method.chain}:${depositAddress}`,
-    priceCents,
-  };
-}
-
-/**
- * Handle native UTXO coins (BTC, LTC, DOGE, BCH, etc.).
- * Uses the xpub from the payment method record (DB-driven).
- * Derives bech32 addresses for BTC/LTC, Base58 P2PKH for DOGE.
- */
-async function handleNativeUtxo(
-  deps: UnifiedCheckoutDeps,
-  method: PaymentMethodRecord,
-  tenant: string,
-  amountUsdCents: number,
-  amountUsd: number,
-): Promise<UnifiedCheckoutResult> {
-  const xpub = method.xpub ?? deps.btcXpub;
-  if (!xpub) throw new Error(`${method.token} payments not configured (no xpub)`);
-
-  const { priceCents } = await deps.oracle.getPrice(method.token);
-  const rawAmount = centsToNative(amountUsdCents, priceCents, method.decimals);
-
-  const maxRetries = 3;
-  for (let attempt = 0; attempt <= maxRetries; attempt++) {
-    const derivationIndex = await deps.chargeStore.getNextDerivationIndex();
-
-    // Derive address by chain type
-    let depositAddress: string;
-    if (method.chain === "dogecoin") {
-      depositAddress = deriveP2pkhAddress(xpub, derivationIndex, "dogecoin");
-    } else {
-      depositAddress = deriveAddress(
-        xpub,
-        derivationIndex,
-        deps.utxoNetwork ?? "mainnet",
-        method.chain as "bitcoin" | "litecoin",
-      );
-    }
-
-    const referenceId = `${method.token.toLowerCase()}:${depositAddress}`;
-
-    try {
-      await deps.chargeStore.createStablecoinCharge({
-        referenceId,
-        tenantId: tenant,
-        amountUsdCents,
-        chain: method.chain,
-        token: method.token,
-        depositAddress,
-        derivationIndex,
-      });
-
-      const divisor = 10 ** method.decimals;
-      const displayAmt = (Number(rawAmount) / divisor).toFixed(method.decimals);
-      return {
-        depositAddress,
-        displayAmount: `${displayAmt} ${method.token}`,
-        amountUsd,
-        token: method.token,
-        chain: method.chain,
-        referenceId,
-        priceCents,
-      };
-    } catch (err: unknown) {
-      const code = (err as { code?: string }).code;
-      const isConflict = code === "23505" || (err instanceof Error && err.message.includes("unique_violation"));
-      if (!isConflict || attempt === maxRetries) throw err;
-    }
-  }
-
-  throw new Error("Failed to claim derivation index after retries");
-}
-
-/** Derive an EVM deposit address and store the charge. Retries on unique conflict. */
-async function deriveAndStore(
-  deps: UnifiedCheckoutDeps,
-  method: PaymentMethodRecord,
-  tenant: string,
-  amountUsdCents: number,
-): Promise<string> {
-  const maxRetries = 3;
-  for (let attempt = 0; attempt <= maxRetries; attempt++) {
-    const derivationIndex = await deps.chargeStore.getNextDerivationIndex();
-    const depositAddress = deriveDepositAddress(deps.evmXpub, derivationIndex);
-    const referenceId = `${method.type}:${method.chain}:${depositAddress}`;
-
-    try {
-      await deps.chargeStore.createStablecoinCharge({
-        referenceId,
-        tenantId: tenant,
-        amountUsdCents,
-        chain: method.chain,
-        token: method.token,
-        depositAddress,
-        derivationIndex,
-      });
-      return depositAddress;
-    } catch (err: unknown) {
-      const code = (err as { code?: string }).code;
-      const isConflict = code === "23505" || (err instanceof Error && err.message.includes("unique_violation"));
-      if (!isConflict || attempt === maxRetries) throw err;
-    }
-  }
-  throw new Error("Failed to claim derivation index after retries");
-}

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

@@ -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).
@@ -23,7 +23,7 @@ import type { EvmChain, EvmPaymentEvent, StablecoinToken } from "./evm/types.js"
 import { createRpcCaller, EvmWatcher } from "./evm/watcher.js";
 import type { IPriceOracle } from "./oracle/types.js";
 import type { IPaymentMethodStore } from "./payment-method-store.js";
-import type { CryptoPaymentState } from "./types.js";
+import type { CryptoChargeStatus } from "./types.js";
 
 const MAX_DELIVERY_ATTEMPTS = 10;
 const BACKOFF_BASE_MS = 5_000;
@@ -131,20 +131,34 @@ async function processDeliveries(
   return delivered;
 }
 
-// --- Payment handling (partial + full) ---
+// --- Payment handling (partial + full + confirmation tracking) ---
+
+export interface PaymentPayload {
+  txHash: string;
+  confirmations: number;
+  confirmationsRequired: number;
+  amountReceivedCents: number;
+  [key: string]: unknown;
+}
 
 /**
  * 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(
+export async function handlePayment(
   db: DrizzleDb,
   chargeStore: ICryptoChargeRepository,
   address: string,
   nativeAmount: string,
-  payload: Record<string, unknown>,
+  payload: PaymentPayload,
   log: (msg: string, meta?: Record<string, unknown>) => void,
 ): Promise<void> {
   const charge = await chargeStore.getByDepositAddress(address);
@@ -156,41 +170,64 @@ async function handlePayment(
     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;
+  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));
+  }
 
-  // Update received_amount in DB
-  await db
-    .update(cryptoCharges)
-    .set({ receivedAmount: totalReceived, filledAmount: totalReceived })
-    .where(eq(cryptoCharges.referenceId, charge.referenceId));
+  // Determine canonical status
+  const status: CryptoChargeStatus = isConfirmed ? "confirmed" : "partial";
 
-  if (isFull) {
-    const settled: CryptoPaymentState = "Settled";
-    await chargeStore.updateStatus(charge.referenceId, settled, charge.token ?? undefined, totalReceived);
+  // 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: CryptoPaymentState = "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,
     });
   }
 }
@@ -245,8 +282,14 @@ export async function startWatchers(opts: WatcherServiceOpts): Promise<() => voi
       oracle,
       cursorStore,
       onPayment: async (event: BtcPaymentEvent) => {
-        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,
@@ -255,6 +298,8 @@ export async function startWatchers(opts: WatcherServiceOpts): Promise<() => voi
           {
             txHash: event.txid,
             confirmations: event.confirmations,
+            confirmationsRequired: event.confirmationsRequired,
+            amountReceivedCents: event.amountUsdCents,
           },
           log,
         );
@@ -323,8 +368,14 @@ export async function startWatchers(opts: WatcherServiceOpts): Promise<() => voi
       watchedAddresses: chainAddresses,
       cursorStore,
       onPayment: async (event: EvmPaymentEvent) => {
-        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,
@@ -332,7 +383,9 @@ export async function startWatchers(opts: WatcherServiceOpts): Promise<() => voi
           event.rawAmount,
           {
             txHash: event.txHash,
-            confirmations: method.confirmations,
+            confirmations: event.confirmations,
+            confirmationsRequired: event.confirmationsRequired,
+            amountReceivedCents: event.amountUsdCents,
           },
           log,
         );

package/src/db/schema/crypto.ts

@@ -30,6 +30,14 @@ export const cryptoCharges = pgTable(
     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),

package/src/monetization/crypto/__tests__/webhook.test.ts

@@ -164,7 +164,8 @@ describe("handleCryptoWebhook (monetization layer)", () => {
       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 () => {