@wopr-network/platform-core 1.48.0 → 1.49.0

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

@@ -66,7 +66,12 @@ describe("EvmWatcher", () => {
 
   it("skips blocks not yet confirmed", async () => {
     const events: unknown[] = [];
-    const mockRpc = vi.fn().mockResolvedValueOnce(`0x${(50).toString(16)}`);
+    // latest = 50, cursor = 50 → latest < cursor is false, but range is empty (50..50)
+    // With intermediate confirmations, we still scan the range but find no logs
+    const mockRpc = vi
+      .fn()
+      .mockResolvedValueOnce(`0x${(50).toString(16)}`) // eth_blockNumber
+      .mockResolvedValueOnce([]); // eth_getLogs (empty)
 
     const watcher = new EvmWatcher({
       chain: "base",
@@ -81,7 +86,6 @@ describe("EvmWatcher", () => {
 
     await watcher.poll();
     expect(events).toHaveLength(0);
-    expect(mockRpc).toHaveBeenCalledTimes(1);
   });
 
   it("processes multiple logs in one poll", async () => {

package/src/billing/crypto/evm/eth-watcher.ts

@@ -6,7 +6,7 @@ import type { EvmChain } from "./types.js";
 
 type RpcCall = (method: string, params: unknown[]) => Promise<unknown>;
 
-/** Event emitted when a native ETH deposit is detected and confirmed. */
+/** Event emitted on each confirmation increment for a native ETH deposit. */
 export interface EthPaymentEvent {
   readonly chain: EvmChain;
   readonly from: string;
@@ -17,6 +17,10 @@ export interface EthPaymentEvent {
   readonly amountUsdCents: number;
   readonly txHash: string;
   readonly blockNumber: number;
+  /** Current confirmation count (latest block - tx block). */
+  readonly confirmations: number;
+  /** Required confirmations for this chain. */
+  readonly confirmationsRequired: number;
 }
 
 export interface EthWatcherOpts {
@@ -44,9 +48,9 @@ interface RpcTransaction {
  * this scans blocks for transactions where `to` matches a watched deposit
  * address and `value > 0`.
  *
- * Processes one block at a time and persists cursor after each block.
- * On restart, resumes from the last committed cursor — no replay, no
- * unbounded in-memory state.
+ * Scans up to latest block (not just confirmed) to detect pending txs.
+ * Emits events on each confirmation increment. Only advances cursor
+ * past fully-confirmed blocks.
  */
 export class EthWatcher {
   private _cursor: number;
@@ -87,11 +91,10 @@ export class EthWatcher {
   }
 
   /**
-   * Poll for new native ETH transfers to watched addresses.
+   * Poll for native ETH transfers to watched addresses, including unconfirmed blocks.
    *
-   * Processes one block at a time. After each block is fully processed,
-   * the cursor is persisted to the DB. If onPayment fails mid-block,
-   * the cursor hasn't advanced — the entire block is retried on next poll.
+   * Scans from cursor to latest block. Emits events with current confirmation count.
+   * Re-emits on each confirmation increment. Only advances cursor past fully-confirmed blocks.
    */
   async poll(): Promise<void> {
     if (this._watchedAddresses.size === 0) return;
@@ -100,17 +103,20 @@ export class EthWatcher {
     const latest = Number.parseInt(latestHex, 16);
     const confirmed = latest - this.confirmations;
 
-    if (confirmed < this._cursor) return;
+    if (latest < this._cursor) return;
 
     const { priceCents } = await this.oracle.getPrice("ETH");
 
-    for (let blockNum = this._cursor; blockNum <= confirmed; blockNum++) {
+    // Scan up to latest (not just confirmed) to detect pending txs
+    for (let blockNum = this._cursor; blockNum <= latest; blockNum++) {
       const block = (await this.rpc("eth_getBlockByNumber", [`0x${blockNum.toString(16)}`, true])) as {
         transactions: RpcTransaction[];
       } | null;
 
       if (!block) continue;
 
+      const confs = latest - blockNum;
+
       for (const tx of block.transactions) {
         if (!tx.to) continue;
         const to = tx.to.toLowerCase();
@@ -119,6 +125,12 @@ export class EthWatcher {
         const valueWei = BigInt(tx.value);
         if (valueWei === 0n) continue;
 
+        // Skip if we already emitted at this confirmation count
+        if (this.cursorStore) {
+          const lastConf = await this.cursorStore.getConfirmationCount(this.watcherId, tx.hash);
+          if (lastConf !== null && confs <= lastConf) continue;
+        }
+
         const amountUsdCents = nativeToCents(valueWei, priceCents, 18);
 
         const event: EthPaymentEvent = {
@@ -129,15 +141,23 @@ export class EthWatcher {
           amountUsdCents,
           txHash: tx.hash,
           blockNumber: blockNum,
+          confirmations: confs,
+          confirmationsRequired: this.confirmations,
         };
 
         await this.onPayment(event);
+
+        if (this.cursorStore) {
+          await this.cursorStore.saveConfirmationCount(this.watcherId, tx.hash, confs);
+        }
       }
 
-      // Block fully processed — persist cursor so we never re-scan it.
-      this._cursor = blockNum + 1;
-      if (this.cursorStore) {
-        await this.cursorStore.save(this.watcherId, this._cursor);
+      // Only advance cursor past fully-confirmed blocks
+      if (blockNum <= confirmed) {
+        this._cursor = blockNum + 1;
+        if (this.cursorStore) {
+          await this.cursorStore.save(this.watcherId, this._cursor);
+        }
       }
     }
   }

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

@@ -21,7 +21,7 @@ export interface TokenConfig {
   readonly decimals: number;
 }
 
-/** Event emitted when a Transfer is detected and confirmed. */
+/** Event emitted on each confirmation increment for a Transfer. */
 export interface EvmPaymentEvent {
   readonly chain: EvmChain;
   readonly token: StablecoinToken;
@@ -34,6 +34,10 @@ export interface EvmPaymentEvent {
   readonly txHash: string;
   readonly blockNumber: number;
   readonly logIndex: number;
+  /** Current confirmation count (latest block - tx block). */
+  readonly confirmations: number;
+  /** Required confirmations for this chain. */
+  readonly confirmationsRequired: number;
 }
 
 /** Options for creating a stablecoin checkout. */

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

@@ -72,7 +72,15 @@ export class EvmWatcher {
     return this._cursor;
   }
 
-  /** Poll for new Transfer events. Call on an interval. */
+  /**
+   * Poll for Transfer events, including pending (unconfirmed) blocks.
+   *
+   * Two-phase scan:
+   *   1. Scan cursor..latest for new/updated txs, emit with current confirmation count
+   *   2. Re-check pending txs automatically since cursor doesn't advance past unconfirmed blocks
+   *
+   * Cursor only advances past fully-confirmed blocks.
+   */
   async poll(): Promise<void> {
     if (this._watchedAddresses.length === 0) return; // nothing to watch
 
@@ -80,27 +88,25 @@ export class EvmWatcher {
     const latest = Number.parseInt(latestHex, 16);
     const confirmed = latest - this.confirmations;
 
-    if (confirmed < this._cursor) return;
+    if (latest < this._cursor) return;
 
     // Filter by topic[2] (to address) when watched addresses are set.
-    // This avoids fetching ALL USDC transfers on the chain (millions/day on Base).
-    // topic[2] values are 32-byte zero-padded: 0x000000000000000000000000<address>
     const toFilter =
       this._watchedAddresses.length > 0
         ? this._watchedAddresses.map((a) => `0x000000000000000000000000${a.slice(2)}`)
         : null;
 
+    // Scan from cursor to latest (not just confirmed) to detect pending txs
     const logs = (await this.rpc("eth_getLogs", [
       {
         address: this.contractAddress,
         topics: [TRANSFER_TOPIC, null, toFilter],
         fromBlock: `0x${this._cursor.toString(16)}`,
-        toBlock: `0x${confirmed.toString(16)}`,
+        toBlock: `0x${latest.toString(16)}`,
       },
     ])) as RpcLog[];
 
-    // Group logs by block for incremental cursor checkpointing.
-    // If onPayment fails mid-batch, only the current block is replayed on next poll.
+    // Group logs by block
     const logsByBlock = new Map<number, RpcLog[]>();
     for (const log of logs) {
       const bn = Number.parseInt(log.blockNumber, 16);
@@ -109,10 +115,20 @@ export class EvmWatcher {
       else logsByBlock.set(bn, [log]);
     }
 
-    // Process blocks in order, checkpoint after each.
+    // Process all blocks (including unconfirmed), emit with confirmation count
     const blockNums = [...logsByBlock.keys()].sort((a, b) => a - b);
     for (const blockNum of blockNums) {
+      const confs = latest - blockNum;
+
       for (const log of logsByBlock.get(blockNum) ?? []) {
+        const txKey = `${log.transactionHash}:${log.logIndex}`;
+
+        // Skip if we already emitted at this confirmation count
+        if (this.cursorStore) {
+          const lastConf = await this.cursorStore.getConfirmationCount(this.watcherId, txKey);
+          if (lastConf !== null && confs <= lastConf) continue;
+        }
+
         const to = `0x${log.topics[2].slice(26)}`.toLowerCase();
         const from = `0x${log.topics[1].slice(26)}`.toLowerCase();
         const rawAmount = BigInt(log.data);
@@ -128,19 +144,29 @@ export class EvmWatcher {
           txHash: log.transactionHash,
           blockNumber: blockNum,
           logIndex: Number.parseInt(log.logIndex, 16),
+          confirmations: confs,
+          confirmationsRequired: this.confirmations,
         };
 
         await this.onPayment(event);
+
+        // Track confirmation count
+        if (this.cursorStore) {
+          await this.cursorStore.saveConfirmationCount(this.watcherId, txKey, confs);
+        }
       }
 
-      this._cursor = blockNum + 1;
-      if (this.cursorStore) {
-        await this.cursorStore.save(this.watcherId, this._cursor);
+      // Only advance cursor past fully-confirmed blocks
+      if (blockNum <= confirmed) {
+        this._cursor = blockNum + 1;
+        if (this.cursorStore) {
+          await this.cursorStore.save(this.watcherId, this._cursor);
+        }
       }
     }
 
-    // Advance cursor even if no logs were found in the range.
-    if (blockNums.length === 0) {
+    // Advance cursor if no logs found but confirmed blocks exist
+    if (blockNums.length === 0 && confirmed >= this._cursor) {
       this._cursor = confirmed + 1;
       if (this.cursorStore) {
         await this.cursorStore.save(this.watcherId, this._cursor);

package/src/billing/crypto/index.ts

@@ -1,5 +1,10 @@
 export * from "./btc/index.js";
-export type { CryptoChargeRecord, CryptoDepositChargeInput, ICryptoChargeRepository } from "./charge-store.js";
+export type {
+  CryptoChargeProgressUpdate,
+  CryptoChargeRecord,
+  CryptoDepositChargeInput,
+  ICryptoChargeRepository,
+} from "./charge-store.js";
 export { CryptoChargeRepository, DrizzleCryptoChargeRepository } from "./charge-store.js";
 export type {
   ChainInfo,
@@ -20,10 +25,14 @@ export type {
   KeyServerWebhookPayload as CryptoWebhookPayload,
   KeyServerWebhookResult as CryptoWebhookResult,
 } from "./key-server-webhook.js";
-export { handleKeyServerWebhook, handleKeyServerWebhook as handleCryptoWebhook } from "./key-server-webhook.js";
+export {
+  handleKeyServerWebhook,
+  handleKeyServerWebhook as handleCryptoWebhook,
+  normalizeStatus,
+} from "./key-server-webhook.js";
 export * from "./oracle/index.js";
 export type { IPaymentMethodStore, PaymentMethodRecord } from "./payment-method-store.js";
 export { DrizzlePaymentMethodStore } from "./payment-method-store.js";
-export type { CryptoPaymentState } from "./types.js";
+export type { CryptoCharge, CryptoChargeStatus, CryptoPaymentState } from "./types.js";
 export type { UnifiedCheckoutDeps, UnifiedCheckoutResult } from "./unified-checkout.js";
 export { createUnifiedCheckout, MIN_CHECKOUT_USD as MIN_PAYMENT_USD, MIN_CHECKOUT_USD } from "./unified-checkout.js";

package/src/billing/crypto/key-server-webhook.ts

@@ -1,17 +1,23 @@
 /**
- * Key Server webhook handler — processes payment confirmations from the
+ * Key Server webhook handler — processes payment events from the
  * centralized crypto key server.
  *
+ * Called on EVERY status update (not just terminal):
+ *   - "partial" / "Processing" → update progress, no credit
+ *   - "confirmed" / "Settled" → update progress + credit ledger
+ *   - "expired" / "failed" → update progress, no credit
+ *
  * Payload shape (from watcher-service.ts):
  * {
  *   chargeId: "btc:bc1q...",
  *   chain: "bitcoin",
  *   address: "bc1q...",
- *   amountUsdCents: 5000,
+ *   amountReceivedCents: 5000,
  *   status: "confirmed",
  *   txHash: "abc123...",
  *   amountReceived: "50000 sats",
- *   confirmations: 6
+ *   confirmations: 6,
+ *   confirmationsRequired: 6
  * }
  *
  * Replaces handleCryptoWebhook() for products using the key server.
@@ -20,16 +26,20 @@ import { Credit } from "../../credits/credit.js";
 import type { ILedger } from "../../credits/ledger.js";
 import type { IWebhookSeenRepository } from "../webhook-seen-repository.js";
 import type { ICryptoChargeRepository } from "./charge-store.js";
+import type { CryptoChargeStatus } from "./types.js";
 
 export interface KeyServerWebhookPayload {
   chargeId: string;
   chain: string;
   address: string;
-  amountUsdCents: number;
+  /** @deprecated Use amountReceivedCents instead. Kept for one release cycle. */
+  amountUsdCents?: number;
+  amountReceivedCents?: number;
   status: string;
   txHash?: string;
   amountReceived?: string;
   confirmations?: number;
+  confirmationsRequired?: number;
 }
 
 export interface KeyServerWebhookDeps {
@@ -45,13 +55,49 @@ export interface KeyServerWebhookResult {
   tenant?: string;
   creditedCents?: number;
   reactivatedBots?: string[];
+  status?: CryptoChargeStatus;
+  confirmations?: number;
+  confirmationsRequired?: number;
+}
+
+/**
+ * Map legacy/watcher status strings to canonical CryptoChargeStatus.
+ * Accepts both old BTCPay-style ("Settled", "Processing") and new canonical ("confirmed", "partial").
+ */
+export function normalizeStatus(raw: string): CryptoChargeStatus {
+  switch (raw) {
+    case "confirmed":
+    case "Settled":
+    case "InvoiceSettled":
+      return "confirmed";
+    case "partial":
+    case "Processing":
+    case "InvoiceProcessing":
+    case "InvoiceReceivedPayment":
+      return "partial";
+    case "expired":
+    case "Expired":
+    case "InvoiceExpired":
+      return "expired";
+    case "failed":
+    case "Invalid":
+    case "InvoiceInvalid":
+      return "failed";
+    case "pending":
+    case "New":
+    case "InvoiceCreated":
+      return "pending";
+    default:
+      return "pending";
+  }
 }
 
 /**
- * Process a payment confirmation from the crypto key server.
+ * Process a payment webhook from the crypto key server.
  *
- * Credits the ledger when status is "confirmed".
- * Idempotency: ledger referenceId + replay guard (same pattern as Stripe handler).
+ * Idempotency: deduplicate by chargeId + status + confirmations so that
+ * multiple progress updates (0→1→2→...→6 confirmations) each get through,
+ * but exact duplicates are rejected.
  */
 export async function handleKeyServerWebhook(
   deps: KeyServerWebhookDeps,
@@ -59,8 +105,15 @@ export async function handleKeyServerWebhook(
 ): Promise<KeyServerWebhookResult> {
   const { chargeStore, creditLedger } = deps;
 
-  // Replay guard: deduplicate by chargeId
-  const dedupeKey = `ks:${payload.chargeId}`;
+  const status = normalizeStatus(payload.status);
+  const confirmations = payload.confirmations ?? 0;
+  const confirmationsRequired = payload.confirmationsRequired ?? 1;
+  // Support deprecated amountUsdCents field as fallback
+  const amountReceivedCents = payload.amountReceivedCents ?? payload.amountUsdCents ?? 0;
+
+  // Replay guard: deduplicate by chargeId + status + confirmations
+  // This allows multiple progress updates for the same charge
+  const dedupeKey = `ks:${payload.chargeId}:${status}:${confirmations}`;
   if (await deps.replayGuard.isDuplicate(dedupeKey, "crypto")) {
     return { handled: true, duplicate: true };
   }
@@ -71,15 +124,36 @@ export async function handleKeyServerWebhook(
     return { handled: false };
   }
 
-  if (payload.status === "confirmed") {
-    // Only settle when payment is confirmed
-    await chargeStore.updateStatus(payload.chargeId, "Settled", charge.token ?? undefined, payload.amountReceived);
+  // Always update progress on every webhook
+  await chargeStore.updateProgress(payload.chargeId, {
+    status,
+    amountReceivedCents,
+    confirmations,
+    confirmationsRequired,
+    txHash: payload.txHash,
+  });
 
+  // Also call deprecated updateStatus for backward compat with downstream consumers
+  const legacyStatusMap: Record<CryptoChargeStatus, string> = {
+    pending: "New",
+    partial: "Processing",
+    confirmed: "Settled",
+    expired: "Expired",
+    failed: "Invalid",
+  };
+  await chargeStore.updateStatus(
+    payload.chargeId,
+    legacyStatusMap[status] as "Settled",
+    charge.token ?? undefined,
+    payload.amountReceived,
+  );
+
+  if (status === "confirmed") {
     // Idempotency: check ledger referenceId (atomic, same as BTCPay handler)
     const creditRef = `crypto:${payload.chargeId}`;
     if (await creditLedger.hasReferenceId(creditRef)) {
       await deps.replayGuard.markSeen(dedupeKey, "crypto");
-      return { handled: true, duplicate: true, tenant: charge.tenantId };
+      return { handled: true, duplicate: true, tenant: charge.tenantId, status, confirmations, confirmationsRequired };
     }
 
     // Credit the original USD amount requested.
@@ -104,16 +178,13 @@ export async function handleKeyServerWebhook(
       tenant: charge.tenantId,
       creditedCents: charge.amountUsdCents,
       reactivatedBots,
+      status,
+      confirmations,
+      confirmationsRequired,
     };
   }
 
-  // Non-confirmed status — update status but don't settle or credit
-  await chargeStore.updateStatus(
-    payload.chargeId,
-    payload.status as "Processing",
-    charge.token ?? undefined,
-    payload.amountReceived,
-  );
+  // Non-confirmed status — progress already updated above, no credit
   await deps.replayGuard.markSeen(dedupeKey, "crypto");
-  return { handled: true, tenant: charge.tenantId };
+  return { handled: true, tenant: charge.tenantId, status, confirmations, confirmationsRequired };
 }

package/src/billing/crypto/types.ts

@@ -1,6 +1,24 @@
 /** BTCPay Server invoice states (Greenfield API v1). */
 export type CryptoPaymentState = "New" | "Processing" | "Expired" | "Invalid" | "Settled";
 
+/** Charge status for the UI-facing payment lifecycle. */
+export type CryptoChargeStatus = "pending" | "partial" | "confirmed" | "expired" | "failed";
+
+/** Full charge record for UI display — includes partial payment progress and confirmations. */
+export interface CryptoCharge {
+  id: string;
+  tenantId: string;
+  chain: string;
+  status: CryptoChargeStatus;
+  amountExpectedCents: number;
+  amountReceivedCents: number;
+  confirmations: number;
+  confirmationsRequired: number;
+  txHash?: string;
+  credited: boolean;
+  createdAt: Date;
+}
+
 /** Options for creating a crypto payment session. */
 export interface CryptoCheckoutOpts {
   /** Internal tenant ID. */