@wopr-network/platform-core 1.48.0 → 1.49.1

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())` },
+        });
+    }
 }

package/dist/billing/crypto/evm/__tests__/eth-checkout.test.js

@@ -1,6 +1,6 @@
 import { describe, expect, it, vi } from "vitest";
 import { createEthCheckout, MIN_ETH_USD } from "../eth-checkout.js";
-const mockOracle = { getPrice: vi.fn().mockResolvedValue({ priceCents: 350_000, updatedAt: new Date() }) };
+const mockOracle = { getPrice: vi.fn().mockResolvedValue({ priceMicros: 3_500_000_000, updatedAt: new Date() }) };
 function makeDeps(derivationIndex = 0) {
     return {
         chargeStore: {
@@ -16,9 +16,9 @@ describe("createEthCheckout", () => {
         const deps = makeDeps();
         const result = await createEthCheckout(deps, { tenant: "t1", amountUsd: 50, chain: "base" });
         expect(result.amountUsd).toBe(50);
-        expect(result.priceCents).toBe(350_000);
+        expect(result.priceMicros).toBe(3_500_000_000);
         expect(result.chain).toBe("base");
-        // $50 = 5000 cents. 5000 × 10^18 / 350000 = 14285714285714285n
+        // $50 = 5000 cents × 10000 micros/cent × 10^18 / 3_500_000_000 micros = 14285714285714285n
         expect(result.expectedWei).toBe("14285714285714285");
         expect(result.depositAddress).toMatch(/^0x/);
         expect(result.referenceId).toMatch(/^eth:base:0x/);

package/dist/billing/crypto/evm/__tests__/eth-settler.test.js

@@ -9,6 +9,8 @@ function makeEvent(overrides = {}) {
         amountUsdCents: 5000,
         txHash: "0xabc123",
         blockNumber: 100,
+        confirmations: 1,
+        confirmationsRequired: 1,
         ...overrides,
     };
 }

package/dist/billing/crypto/evm/__tests__/eth-watcher.test.js

@@ -3,12 +3,13 @@ import { EthWatcher } from "../eth-watcher.js";
 function makeRpc(responses) {
     return vi.fn(async (method) => responses[method]);
 }
-const mockOracle = { getPrice: vi.fn().mockResolvedValue({ priceCents: 350_000, updatedAt: new Date() }) };
+const mockOracle = { getPrice: vi.fn().mockResolvedValue({ priceMicros: 3_500_000_000, updatedAt: new Date() }) };
 describe("EthWatcher", () => {
     it("detects native ETH transfer to watched address", async () => {
         const onPayment = vi.fn();
+        // latest = 0xa (10), fromBlock = 10 → scans exactly block 10
         const rpc = makeRpc({
-            eth_blockNumber: "0xb",
+            eth_blockNumber: "0xa",
             eth_getBlockByNumber: {
                 transactions: [
                     {
@@ -34,8 +35,10 @@ describe("EthWatcher", () => {
         const event = onPayment.mock.calls[0][0];
         expect(event.to).toBe("0xdeposit");
         expect(event.valueWei).toBe("1000000000000000000");
-        expect(event.amountUsdCents).toBe(350_000); // 1 ETH × $3,500
+        expect(event.amountUsdCents).toBe(350_000); // 1 ETH × $3,500 = $3,500 = 350,000 cents
         expect(event.txHash).toBe("0xabc");
+        expect(event.confirmations).toBe(0);
+        expect(event.confirmationsRequired).toBe(1);
     });
     it("skips transactions not to watched addresses", async () => {
         const onPayment = vi.fn();
@@ -77,6 +80,19 @@ describe("EthWatcher", () => {
     });
     it("does not double-process same txid", async () => {
         const onPayment = vi.fn();
+        const confirmations = new Map();
+        const cursorStore = {
+            get: vi.fn().mockResolvedValue(null),
+            save: vi.fn().mockResolvedValue(undefined),
+            hasProcessedTx: vi.fn().mockResolvedValue(false),
+            markProcessedTx: vi.fn().mockResolvedValue(undefined),
+            getConfirmationCount: vi
+                .fn()
+                .mockImplementation(async (_, txId) => confirmations.get(txId) ?? null),
+            saveConfirmationCount: vi.fn().mockImplementation(async (_, txId, count) => {
+                confirmations.set(txId, count);
+            }),
+        };
         const rpc = makeRpc({
             eth_blockNumber: "0xb",
             eth_getBlockByNumber: {
@@ -90,9 +106,10 @@ describe("EthWatcher", () => {
             fromBlock: 10,
             onPayment,
             watchedAddresses: ["0xDeposit"],
+            cursorStore,
         });
         await watcher.poll();
-        // Reset cursor to re-scan same block
+        // Second poll — same block, same confirmations → no duplicate emission
         await watcher.poll();
         expect(onPayment).toHaveBeenCalledOnce();
     });
@@ -112,8 +129,17 @@ describe("EthWatcher", () => {
     });
     it("does not mark txid as processed if onPayment throws", async () => {
         const onPayment = vi.fn().mockRejectedValueOnce(new Error("db fail")).mockResolvedValueOnce(undefined);
+        const cursorStore = {
+            get: vi.fn().mockResolvedValue(null),
+            save: vi.fn().mockResolvedValue(undefined),
+            hasProcessedTx: vi.fn().mockResolvedValue(false),
+            markProcessedTx: vi.fn().mockResolvedValue(undefined),
+            getConfirmationCount: vi.fn().mockResolvedValue(null),
+            saveConfirmationCount: vi.fn().mockResolvedValue(undefined),
+        };
+        // latest = 0xa (10) = fromBlock → exactly one block to scan
         const rpc = makeRpc({
-            eth_blockNumber: "0xb",
+            eth_blockNumber: "0xa",
             eth_getBlockByNumber: {
                 transactions: [{ hash: "0xabc", from: "0xa", to: "0xdeposit", value: "0xDE0B6B3A7640000", blockNumber: "0xa" }],
             },
@@ -125,9 +151,10 @@ describe("EthWatcher", () => {
             fromBlock: 10,
             onPayment,
             watchedAddresses: ["0xDeposit"],
+            cursorStore,
         });
         await expect(watcher.poll()).rejects.toThrow("db fail");
-        // Retry — should process the same tx again since it wasn't marked
+        // Retry — should process the same tx again since confirmationCount wasn't saved (error before save)
         await watcher.poll();
         expect(onPayment).toHaveBeenCalledTimes(2);
     });

package/dist/billing/crypto/evm/__tests__/settler.test.js

@@ -10,6 +10,8 @@ const mockEvent = {
     txHash: "0xtx123",
     blockNumber: 100,
     logIndex: 0,
+    confirmations: 1,
+    confirmationsRequired: 1,
 };
 describe("settleEvmPayment", () => {
     it("credits ledger when charge found and not yet credited", async () => {

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

@@ -0,0 +1 @@
+export {};

package/dist/billing/crypto/evm/__tests__/watcher-confirmations.test.js

@@ -0,0 +1,144 @@
+import { describe, expect, it, vi } from "vitest";
+import { EvmWatcher } from "../watcher.js";
+const TRANSFER_TOPIC = "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef";
+function mockTransferLog(to, amount, blockNumber) {
+    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();
+    return {
+        get: vi.fn().mockImplementation(async (id) => cursors.get(id) ?? null),
+        save: vi.fn().mockImplementation(async (id, val) => {
+            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 = [];
+        // 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, 10000000n, 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 = [];
+        const cursorStore = makeCursorStore();
+        cursorStore.getConfirmationCount.mockResolvedValue(2);
+        const mockRpc = vi
+            .fn()
+            .mockResolvedValueOnce(`0x${(105).toString(16)}`)
+            .mockResolvedValueOnce([mockTransferLog(toAddr, 10000000n, 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 = [];
+        const cursorStore = makeCursorStore();
+        cursorStore.getConfirmationCount.mockResolvedValue(1);
+        const mockRpc = vi
+            .fn()
+            .mockResolvedValueOnce(`0x${(105).toString(16)}`)
+            .mockResolvedValueOnce([mockTransferLog(toAddr, 10000000n, 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 = [];
+        const mockRpc = vi
+            .fn()
+            .mockResolvedValueOnce(`0x${(110).toString(16)}`)
+            .mockResolvedValueOnce([mockTransferLog(toAddr, 10000000n, 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, 10000000n, 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/dist/billing/crypto/evm/__tests__/watcher.test.js

@@ -56,7 +56,12 @@ describe("EvmWatcher", () => {
     });
     it("skips blocks not yet confirmed", async () => {
         const events = [];
-        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",
             token: "USDC",
@@ -69,7 +74,6 @@ describe("EvmWatcher", () => {
         });
         await watcher.poll();
         expect(events).toHaveLength(0);
-        expect(mockRpc).toHaveBeenCalledTimes(1);
     });
     it("processes multiple logs in one poll", async () => {
         const addr1 = `0x${"aa".repeat(20)}`;

package/dist/billing/crypto/evm/eth-checkout.d.ts

@@ -17,8 +17,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;
 }

package/dist/billing/crypto/evm/eth-checkout.js

@@ -16,8 +16,8 @@ export async function createEthCheckout(deps, opts) {
         throw new Error(`Minimum payment amount is $${MIN_ETH_USD}`);
     }
     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++) {
         const derivationIndex = await deps.chargeStore.getNextDerivationIndex();
@@ -37,7 +37,7 @@ export async function createEthCheckout(deps, opts) {
                 depositAddress,
                 amountUsd: opts.amountUsd,
                 expectedWei: expectedWei.toString(),
-                priceCents,
+                priceMicros,
                 chain: opts.chain,
                 referenceId,
             };

package/dist/billing/crypto/evm/eth-watcher.d.ts

@@ -2,7 +2,7 @@ import type { IWatcherCursorStore } from "../cursor-store.js";
 import type { IPriceOracle } from "../oracle/types.js";
 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;
@@ -13,6 +13,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 {
     chain: EvmChain;
@@ -30,9 +34,9 @@ export interface EthWatcherOpts {
  * 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 declare class EthWatcher {
     private _cursor;
@@ -50,11 +54,10 @@ export declare class EthWatcher {
     setWatchedAddresses(addresses: string[]): void;
     get cursor(): number;
     /**
-     * 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.
      */
     poll(): Promise<void>;
 }

package/dist/billing/crypto/evm/eth-watcher.js

@@ -7,9 +7,9 @@ import { getChainConfig } from "./config.js";
  * 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 {
     _cursor;
@@ -47,11 +47,10 @@ export class EthWatcher {
         return this._cursor;
     }
     /**
-     * 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() {
         if (this._watchedAddresses.size === 0)
@@ -59,13 +58,15 @@ export class EthWatcher {
         const latestHex = (await this.rpc("eth_blockNumber", []));
         const latest = Number.parseInt(latestHex, 16);
         const confirmed = latest - this.confirmations;
-        if (confirmed < this._cursor)
+        if (latest < this._cursor)
             return;
-        const { priceCents } = await this.oracle.getPrice("ETH");
-        for (let blockNum = this._cursor; blockNum <= confirmed; blockNum++) {
+        const { priceMicros } = await this.oracle.getPrice("ETH");
+        // 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]));
             if (!block)
                 continue;
+            const confs = latest - blockNum;
             for (const tx of block.transactions) {
                 if (!tx.to)
                     continue;
@@ -75,7 +76,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 = {
                     chain: this.chain,
                     from: tx.from.toLowerCase(),
@@ -84,13 +91,20 @@ 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/dist/billing/crypto/evm/types.d.ts

@@ -17,7 +17,7 @@ export interface TokenConfig {
     readonly contractAddress: `0x${string}`;
     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;
@@ -30,6 +30,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. */
 export interface StablecoinCheckoutOpts {

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

@@ -29,7 +29,15 @@ export declare class EvmWatcher {
     /** Update the set of watched deposit addresses (e.g. after a new checkout). */
     setWatchedAddresses(addresses: string[]): void;
     get cursor(): number;
-    /** 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.
+     */
     poll(): Promise<void>;
 }
 /** Create an RPC caller for a given URL (plain JSON-RPC over fetch). */

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

@@ -42,31 +42,37 @@ export class EvmWatcher {
     get cursor() {
         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() {
         if (this._watchedAddresses.length === 0)
             return; // nothing to watch
         const latestHex = (await this.rpc("eth_blockNumber", []));
         const latest = Number.parseInt(latestHex, 16);
         const confirmed = latest - this.confirmations;
-        if (confirmed < this._cursor)
+        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)}`,
             },
         ]));
-        // 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();
         for (const log of logs) {
             const bn = Number.parseInt(log.blockNumber, 16);
@@ -76,10 +82,18 @@ 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);
@@ -94,16 +108,25 @@ 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);