@wopr-network/platform-core 1.48.0 → 1.49.1

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

@@ -0,0 +1,176 @@
+import { describe, expect, it, vi } from "vitest";
+import { EvmWatcher } from "../watcher.js";
+
+const TRANSFER_TOPIC = "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef";
+
+function mockTransferLog(to: string, amount: bigint, blockNumber: number) {
+  return {
+    address: "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
+    topics: [
+      TRANSFER_TOPIC,
+      `0x${"00".repeat(12)}${"ab".repeat(20)}`,
+      `0x${"00".repeat(12)}${to.slice(2).toLowerCase()}`,
+    ],
+    data: `0x${amount.toString(16).padStart(64, "0")}`,
+    blockNumber: `0x${blockNumber.toString(16)}`,
+    transactionHash: `0x${"ff".repeat(32)}`,
+    logIndex: "0x0",
+  };
+}
+
+function makeCursorStore() {
+  const cursors = new Map<string, number>();
+  return {
+    get: vi.fn().mockImplementation(async (id: string) => cursors.get(id) ?? null),
+    save: vi.fn().mockImplementation(async (id: string, val: number) => {
+      cursors.set(id, val);
+    }),
+    hasProcessedTx: vi.fn().mockResolvedValue(false),
+    markProcessedTx: vi.fn().mockResolvedValue(undefined),
+    getConfirmationCount: vi.fn().mockResolvedValue(null),
+    saveConfirmationCount: vi.fn().mockResolvedValue(undefined),
+  };
+}
+
+describe("EvmWatcher — intermediate confirmations", () => {
+  it("emits events with confirmation count", async () => {
+    const toAddr = `0x${"cc".repeat(20)}`;
+    const events: Array<{ confirmations: number; confirmationsRequired: number }> = [];
+
+    // Base has confirmations: 1. Latest block is 105. Log at block 103 -> 2 confirmations.
+    const mockRpc = vi
+      .fn()
+      .mockResolvedValueOnce(`0x${(105).toString(16)}`) // eth_blockNumber
+      .mockResolvedValueOnce([mockTransferLog(toAddr, 10_000_000n, 103)]); // eth_getLogs
+
+    const watcher = new EvmWatcher({
+      chain: "base",
+      token: "USDC",
+      rpcCall: mockRpc,
+      fromBlock: 100,
+      watchedAddresses: [toAddr],
+      cursorStore: makeCursorStore(),
+      onPayment: (evt) => {
+        events.push(evt);
+      },
+    });
+
+    await watcher.poll();
+
+    expect(events).toHaveLength(1);
+    expect(events[0].confirmations).toBe(2); // 105 - 103
+    expect(events[0].confirmationsRequired).toBe(1); // Base chain config
+  });
+
+  it("skips event when confirmation count unchanged", async () => {
+    const toAddr = `0x${"cc".repeat(20)}`;
+    const events: Array<{ confirmations: number }> = [];
+    const cursorStore = makeCursorStore();
+    cursorStore.getConfirmationCount.mockResolvedValue(2);
+
+    const mockRpc = vi
+      .fn()
+      .mockResolvedValueOnce(`0x${(105).toString(16)}`)
+      .mockResolvedValueOnce([mockTransferLog(toAddr, 10_000_000n, 103)]);
+
+    const watcher = new EvmWatcher({
+      chain: "base",
+      token: "USDC",
+      rpcCall: mockRpc,
+      fromBlock: 100,
+      watchedAddresses: [toAddr],
+      cursorStore,
+      onPayment: (evt) => {
+        events.push(evt);
+      },
+    });
+
+    await watcher.poll();
+
+    expect(events).toHaveLength(0);
+  });
+
+  it("re-emits when confirmations increase", async () => {
+    const toAddr = `0x${"cc".repeat(20)}`;
+    const events: Array<{ confirmations: number }> = [];
+    const cursorStore = makeCursorStore();
+    cursorStore.getConfirmationCount.mockResolvedValue(1);
+
+    const mockRpc = vi
+      .fn()
+      .mockResolvedValueOnce(`0x${(105).toString(16)}`)
+      .mockResolvedValueOnce([mockTransferLog(toAddr, 10_000_000n, 103)]);
+
+    const watcher = new EvmWatcher({
+      chain: "base",
+      token: "USDC",
+      rpcCall: mockRpc,
+      fromBlock: 100,
+      watchedAddresses: [toAddr],
+      cursorStore,
+      onPayment: (evt) => {
+        events.push(evt);
+      },
+    });
+
+    await watcher.poll();
+
+    expect(events).toHaveLength(1);
+    expect(events[0].confirmations).toBe(2);
+  });
+
+  it("includes confirmationsRequired from chain config", async () => {
+    const toAddr = `0x${"cc".repeat(20)}`;
+    const events: Array<{ confirmationsRequired: number }> = [];
+
+    const mockRpc = vi
+      .fn()
+      .mockResolvedValueOnce(`0x${(110).toString(16)}`)
+      .mockResolvedValueOnce([mockTransferLog(toAddr, 10_000_000n, 105)]);
+
+    const watcher = new EvmWatcher({
+      chain: "base",
+      token: "USDC",
+      rpcCall: mockRpc,
+      fromBlock: 100,
+      watchedAddresses: [toAddr],
+      cursorStore: makeCursorStore(),
+      onPayment: (evt) => {
+        events.push(evt);
+      },
+    });
+
+    await watcher.poll();
+
+    expect(events).toHaveLength(1);
+    expect(events[0].confirmationsRequired).toBe(1); // Base chain config
+  });
+
+  it("saves confirmation count after emitting", async () => {
+    const toAddr = `0x${"cc".repeat(20)}`;
+    const cursorStore = makeCursorStore();
+
+    const mockRpc = vi
+      .fn()
+      .mockResolvedValueOnce(`0x${(105).toString(16)}`)
+      .mockResolvedValueOnce([mockTransferLog(toAddr, 10_000_000n, 103)]);
+
+    const watcher = new EvmWatcher({
+      chain: "base",
+      token: "USDC",
+      rpcCall: mockRpc,
+      fromBlock: 100,
+      watchedAddresses: [toAddr],
+      cursorStore,
+      onPayment: () => {},
+    });
+
+    await watcher.poll();
+
+    expect(cursorStore.saveConfirmationCount).toHaveBeenCalledWith(
+      expect.any(String),
+      expect.stringContaining("0x"),
+      2,
+    );
+  });
+});

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-checkout.ts

@@ -24,8 +24,8 @@ export interface EthCheckoutResult {
   amountUsd: number;
   /** Expected ETH amount in wei (BigInt as string). */
   expectedWei: string;
-  /** ETH price in USD cents at checkout time. */
-  priceCents: number;
+  /** ETH price in microdollars at checkout time (10^-6 USD). */
+  priceMicros: number;
   chain: EvmChain;
   referenceId: string;
 }
@@ -45,8 +45,8 @@ export async function createEthCheckout(deps: EthCheckoutDeps, opts: EthCheckout
   }
 
   const amountUsdCents = Credit.fromDollars(opts.amountUsd).toCentsRounded();
-  const { priceCents } = await deps.oracle.getPrice("ETH");
-  const expectedWei = centsToNative(amountUsdCents, priceCents, 18);
+  const { priceMicros } = await deps.oracle.getPrice("ETH");
+  const expectedWei = centsToNative(amountUsdCents, priceMicros, 18);
   const maxRetries = 3;
 
   for (let attempt = 0; attempt <= maxRetries; attempt++) {
@@ -69,7 +69,7 @@ export async function createEthCheckout(deps: EthCheckoutDeps, opts: EthCheckout
         depositAddress,
         amountUsd: opts.amountUsd,
         expectedWei: expectedWei.toString(),
-        priceCents,
+        priceMicros,
         chain: opts.chain,
         referenceId,
       };

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");
+    const { priceMicros } = 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,7 +125,13 @@ export class EthWatcher {
         const valueWei = BigInt(tx.value);
         if (valueWei === 0n) continue;
 
-        const amountUsdCents = nativeToCents(valueWei, priceCents, 18);
+        // 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, priceMicros, 18);
 
         const event: EthPaymentEvent = {
           chain: this.chain,
@@ -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-entry.ts

@@ -17,6 +17,8 @@ import { DrizzleWatcherCursorStore } from "./cursor-store.js";
 import { createRpcCaller } from "./evm/watcher.js";
 import { createKeyServerApp } from "./key-server.js";
 import { ChainlinkOracle } from "./oracle/chainlink.js";
+import { CoinGeckoOracle } from "./oracle/coingecko.js";
+import { CompositeOracle } from "./oracle/composite.js";
 import { FixedPriceOracle } from "./oracle/fixed.js";
 import { DrizzlePaymentMethodStore } from "./payment-method-store.js";
 import { startWatchers } from "./watcher-service.js";
@@ -48,10 +50,13 @@ async function main(): Promise<void> {
   const chargeStore = new DrizzleCryptoChargeRepository(db);
   const methodStore = new DrizzlePaymentMethodStore(db);
 
-  // Chainlink on-chain oracle for volatile assets (BTC, ETH).
-  const oracle = BASE_RPC_URL
+  // Composite oracle: Chainlink on-chain (BTC, ETH on Base) + CoinGecko fallback (DOGE, LTC, etc.)
+  // Every volatile asset needs reliable USD pricing — the ledger credits nanodollars.
+  const chainlink = BASE_RPC_URL
     ? new ChainlinkOracle({ rpcCall: createRpcCaller(BASE_RPC_URL) })
     : new FixedPriceOracle();
+  const coingecko = new CoinGeckoOracle();
+  const oracle = new CompositeOracle(chainlink, coingecko);
 
   const app = createKeyServerApp({
     db,