wdk-payment-verifier 1.0.0

package/README.md

@@ -0,0 +1,56 @@
+# wdk-payment-verifier
+
+Server-side, **read-only** on-chain confirmation for self-custodial **WDK Pay**
+payments. A payment is a plain ERC-20 transfer of the settlement token (USDt) to
+the merchant; this library confirms one landed — `Transfer(token, to = merchant,
+value ≥ due)` with N confirmations — over JSON-RPC. No keys, no custody: the
+merchant only *watches* the chain. It's the Node/headless counterpart to the
+WooCommerce plugin's PHP verifier.
+
+```bash
+npm install wdk-payment-verifier
+```
+
+## Verify a known transaction
+
+```ts
+import { PaymentVerifier } from 'wdk-payment-verifier'
+
+const verifier = new PaymentVerifier({ rpcUrl: process.env.RPC_URL! })
+
+const result = await verifier.verify(
+  { tokenAddress: USDt, receivingAddress: merchant, amountBase: '19990000' }, // 19.99 USDt
+  txHash,
+  /* requiredConfirmations */ 5,
+)
+// result.status: 'confirmed' | 'pending' | 'failed'
+if (result.status === 'confirmed') markOrderPaid(result)
+```
+
+## Watch for an incoming payment (no hash yet)
+
+```ts
+const result = await verifier.watch(
+  { tokenAddress: USDt, receivingAddress: merchant, amountBase: '19990000' },
+  { requiredConfirmations: 5, timeoutMs: 15 * 60_000, pollIntervalMs: 5000 },
+)
+```
+
+`watch` polls `eth_getLogs` for a matching Transfer to the recipient, then waits
+for confirmations; it resolves `confirmed`/`failed`, or `pending` (reason
+`timeout`) if the window elapses.
+
+## Pluggable provider
+
+Pass `rpcUrl` (an ethers `JsonRpcProvider` is created lazily), an existing
+`provider`, or — for tests — any object implementing the minimal `EvmReadProvider`
+interface (`getTransactionReceipt`, `getBlockNumber`, `getLogs`). Nothing is
+hard-coded.
+
+`PaymentConfirmation` carries `status`, `txHash`, `blockNumber`, `confirmations`,
+`valueBase`, and `fromAddress` so your order system has everything to reconcile.
+
+## License
+
+[MIT](https://github.com/plinkdev1/wdk-checkout-and-woocommerce-plugin/blob/main/LICENSE).
+Built with [Tether WDK](https://docs.wallet.tether.io); not an official Tether product.

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * wdk-payment-verifier — server-side on-chain confirmation of self-custodial
+ * WDK Pay payments (the Node/headless counterpart to the WooCommerce PHP verifier).
+ */
+export { PaymentVerifier, matchTransfer, TRANSFER_TOPIC } from './verifier.js';
+export type { VerifierIntent, PaymentStatus, PaymentConfirmation, EvmLog, EvmReceipt, EvmReadProvider, PaymentVerifierOptions, WatchOptions } from './verifier.js';

package/dist/index.js

@@ -0,0 +1,5 @@
+/**
+ * wdk-payment-verifier — server-side on-chain confirmation of self-custodial
+ * WDK Pay payments (the Node/headless counterpart to the WooCommerce PHP verifier).
+ */
+export { PaymentVerifier, matchTransfer, TRANSFER_TOPIC } from './verifier.js';

package/dist/verifier.d.ts

@@ -0,0 +1,102 @@
+/** keccak256("Transfer(address,address,uint256)") — the ERC-20 Transfer topic. */
+export declare const TRANSFER_TOPIC = "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef";
+/** The minimum a verifier needs to know about an order to confirm payment. */
+export interface VerifierIntent {
+    /** Settlement token contract (the Transfer emitter), e.g. USDt. */
+    readonly tokenAddress: string;
+    /** Merchant receiving address (the Transfer `to`). */
+    readonly receivingAddress: string;
+    /** Minimum amount required, in token base units (decimal string). */
+    readonly amountBase: string;
+}
+export type PaymentStatus = 'confirmed' | 'pending' | 'failed';
+/** The outcome of a verification. */
+export interface PaymentConfirmation {
+    readonly status: PaymentStatus;
+    readonly txHash?: string;
+    readonly blockNumber?: number;
+    readonly confirmations?: number;
+    /** The matched transfer's value, base units. */
+    readonly valueBase?: string;
+    /** The payer (the Transfer `from`). */
+    readonly fromAddress?: string;
+    /** Unix ms when confirmed. */
+    readonly receivedAt?: number;
+    /** Machine-readable reason for pending/failed. */
+    readonly reason?: string;
+}
+/** A single log entry (subset of an eth_getLogs / receipt log). */
+export interface EvmLog {
+    readonly address: string;
+    readonly topics: readonly string[];
+    readonly data: string;
+    readonly blockNumber?: number;
+    readonly transactionHash?: string;
+}
+/** A transaction receipt subset. */
+export interface EvmReceipt {
+    readonly status?: number | null;
+    readonly blockNumber: number;
+    readonly logs: readonly EvmLog[];
+    readonly transactionHash?: string;
+}
+/**
+ * Minimal read-only provider the verifier needs. An ethers `JsonRpcProvider`
+ * satisfies it; tests pass a fake. (ethers receipts expose `logs` and a numeric
+ * `status`; `getLogs` returns the same log shape.)
+ */
+export interface EvmReadProvider {
+    getTransactionReceipt(txHash: string): Promise<EvmReceipt | null>;
+    getBlockNumber(): Promise<number>;
+    getLogs(filter: {
+        address?: string;
+        topics?: (string | null)[];
+        fromBlock?: number | string;
+        toBlock?: number | string;
+    }): Promise<readonly EvmLog[]>;
+}
+export interface PaymentVerifierOptions {
+    /** A ready provider (e.g. ethers JsonRpcProvider) — preferred for reuse. */
+    readonly provider?: EvmReadProvider;
+    /** Or a JSON-RPC URL; an ethers JsonRpcProvider is created lazily. */
+    readonly rpcUrl?: string;
+}
+export interface WatchOptions {
+    /** Confirmations required before `confirmed`. Default 1. */
+    readonly requiredConfirmations?: number;
+    /** Give up after this many ms (resolves `pending`/`timeout`). Default 15 min. */
+    readonly timeoutMs?: number;
+    /** Poll cadence. Default 5s. */
+    readonly pollIntervalMs?: number;
+    /** Block to scan logs from. Default: latest − 5000 (or 0). */
+    readonly fromBlock?: number;
+    /** Injectable sleep for deterministic tests. */
+    readonly sleep?: (ms: number) => Promise<void>;
+    /** Injectable clock (ms) for deterministic tests. */
+    readonly now?: () => number;
+}
+/**
+ * Find a Transfer log in `logs` matching the intent (emitter = token,
+ * to = recipient, value ≥ amount). Returns the match or null.
+ */
+export declare function matchTransfer(logs: readonly EvmLog[], intent: VerifierIntent): {
+    value: bigint;
+    from: string;
+    log: EvmLog;
+} | null;
+export declare class PaymentVerifier {
+    #private;
+    constructor(opts: PaymentVerifierOptions);
+    /**
+     * Verify a specific transaction satisfies the intent. One-shot: checks the
+     * receipt for a matching Transfer and the current confirmation count.
+     */
+    verify(intent: VerifierIntent, txHash: string, requiredConfirmations?: number): Promise<PaymentConfirmation>;
+    /**
+     * Watch for an incoming payment matching the intent (no tx hash known yet):
+     * polls `getLogs` for a Transfer to the recipient ≥ amount, then waits for
+     * confirmations. Resolves `confirmed`, or `pending` (reason `timeout`) if the
+     * window elapses.
+     */
+    watch(intent: VerifierIntent, options?: WatchOptions): Promise<PaymentConfirmation>;
+}

package/dist/verifier.js

@@ -0,0 +1,154 @@
+/**
+ * wdk-payment-verifier — server-side on-chain confirmation of WDK Pay payments.
+ *
+ * A payment is a plain ERC-20 transfer of the settlement token to the merchant.
+ * Verification = observe the chain (read-only JSON-RPC) and confirm a
+ * `Transfer(token, to = merchant, value ≥ due)` landed with enough
+ * confirmations. No keys, no custody — the merchant only watches.
+ *
+ * This is the standalone library counterpart to the WooCommerce plugin's PHP
+ * verifier, for Node back-ends / headless commerce. The RPC provider is
+ * injectable (pass an `rpcUrl`, an ethers provider, or any minimal provider for
+ * tests); nothing is hard-coded.
+ */
+import { getAddress } from 'ethers';
+/** keccak256("Transfer(address,address,uint256)") — the ERC-20 Transfer topic. */
+export const TRANSFER_TOPIC = '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef';
+/** A 32-byte topic word → checksummed address (last 20 bytes). */
+function topicToAddress(topic) {
+    return getAddress('0x' + topic.slice(-40));
+}
+function eq(a, b) {
+    try {
+        return getAddress(a) === getAddress(b);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Find a Transfer log in `logs` matching the intent (emitter = token,
+ * to = recipient, value ≥ amount). Returns the match or null.
+ */
+export function matchTransfer(logs, intent) {
+    const need = BigInt(intent.amountBase);
+    for (const log of logs) {
+        if (!log.topics || log.topics.length < 3)
+            continue;
+        if (log.topics[0]?.toLowerCase() !== TRANSFER_TOPIC)
+            continue;
+        if (!eq(log.address, intent.tokenAddress))
+            continue;
+        if (!eq(topicToAddress(log.topics[2]), intent.receivingAddress))
+            continue;
+        let value;
+        try {
+            value = BigInt(log.data);
+        }
+        catch {
+            continue;
+        }
+        if (value < need)
+            continue;
+        return { value, from: topicToAddress(log.topics[1]), log };
+    }
+    return null;
+}
+export class PaymentVerifier {
+    #provider;
+    #rpcUrl;
+    constructor(opts) {
+        if (!opts.provider && !opts.rpcUrl)
+            throw new Error('PaymentVerifier: pass `provider` or `rpcUrl`.');
+        this.#provider = opts.provider;
+        this.#rpcUrl = opts.rpcUrl;
+    }
+    async #getProvider() {
+        if (this.#provider)
+            return this.#provider;
+        const { JsonRpcProvider } = await import('ethers');
+        this.#provider = new JsonRpcProvider(this.#rpcUrl);
+        return this.#provider;
+    }
+    /**
+     * Verify a specific transaction satisfies the intent. One-shot: checks the
+     * receipt for a matching Transfer and the current confirmation count.
+     */
+    async verify(intent, txHash, requiredConfirmations = 1) {
+        const provider = await this.#getProvider();
+        let receipt;
+        try {
+            receipt = await provider.getTransactionReceipt(txHash);
+        }
+        catch {
+            return { status: 'pending', txHash, reason: 'rpc_unreachable' };
+        }
+        if (!receipt)
+            return { status: 'pending', txHash, reason: 'not_mined' };
+        if (receipt.status === 0)
+            return { status: 'failed', txHash, reason: 'reverted' };
+        const match = matchTransfer(receipt.logs, intent);
+        if (!match)
+            return { status: 'failed', txHash, reason: 'no_matching_transfer' };
+        let head;
+        try {
+            head = await provider.getBlockNumber();
+        }
+        catch {
+            return { status: 'pending', txHash, valueBase: match.value.toString(), reason: 'rpc_unreachable' };
+        }
+        const confirmations = head - receipt.blockNumber + 1;
+        const base = {
+            txHash, blockNumber: receipt.blockNumber, confirmations: Math.max(0, confirmations),
+            valueBase: match.value.toString(), fromAddress: match.from
+        };
+        if (confirmations < requiredConfirmations)
+            return { status: 'pending', ...base, reason: 'awaiting_confirmations' };
+        return { status: 'confirmed', ...base, receivedAt: Date.now() };
+    }
+    /**
+     * Watch for an incoming payment matching the intent (no tx hash known yet):
+     * polls `getLogs` for a Transfer to the recipient ≥ amount, then waits for
+     * confirmations. Resolves `confirmed`, or `pending` (reason `timeout`) if the
+     * window elapses.
+     */
+    async watch(intent, options = {}) {
+        const provider = await this.#getProvider();
+        const requiredConfirmations = options.requiredConfirmations ?? 1;
+        const timeoutMs = options.timeoutMs ?? 15 * 60 * 1000;
+        const pollIntervalMs = options.pollIntervalMs ?? 5000;
+        const sleep = options.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+        const now = options.now ?? (() => Date.now());
+        const start = now();
+        let fromBlock = options.fromBlock;
+        if (fromBlock === undefined) {
+            try {
+                fromBlock = Math.max(0, (await provider.getBlockNumber()) - 5000);
+            }
+            catch {
+                fromBlock = 0;
+            }
+        }
+        for (;;) {
+            let logs = [];
+            try {
+                logs = await provider.getLogs({
+                    address: intent.tokenAddress,
+                    topics: [TRANSFER_TOPIC, null, '0x' + getAddress(intent.receivingAddress).slice(2).toLowerCase().padStart(64, '0')],
+                    fromBlock,
+                    toBlock: 'latest'
+                });
+            }
+            catch { /* transient — retry next tick */ }
+            const match = matchTransfer(logs, intent);
+            if (match && match.log.transactionHash) {
+                const confirmation = await this.verify(intent, match.log.transactionHash, requiredConfirmations);
+                if (confirmation.status === 'confirmed' || confirmation.status === 'failed')
+                    return confirmation;
+            }
+            if (now() - start >= timeoutMs)
+                return { status: 'pending', reason: 'timeout' };
+            await sleep(pollIntervalMs);
+        }
+    }
+}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "wdk-payment-verifier",
+  "version": "1.0.0",
+  "description": "Server-side on-chain confirmation for self-custodial WDK Pay payments — verify or watch for a USDt transfer to the merchant with N confirmations. Node/headless counterpart to the WooCommerce PHP verifier.",
+  "type": "module",
+  "license": "MIT",
+  "author": "WDK Pay contributors",
+  "keywords": [
+    "wdk",
+    "tether",
+    "usdt",
+    "payment",
+    "verifier",
+    "on-chain",
+    "ecommerce",
+    "self-custodial",
+    "erc20",
+    "ethers"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/plinkdev1/wdk-checkout-and-woocommerce-plugin.git",
+    "directory": "packages/wdk-payment-verifier"
+  },
+  "homepage": "https://github.com/plinkdev1/wdk-checkout-and-woocommerce-plugin/tree/main/packages/wdk-payment-verifier#readme",
+  "bugs": {
+    "url": "https://github.com/plinkdev1/wdk-checkout-and-woocommerce-plugin/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "ethers": "6.14.3"
+  },
+  "devDependencies": {
+    "typescript": "5.5.4",
+    "vitest": "^3.2.6"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "overrides": {
+    "vitest": "^3.2.6",
+    "vite": ">=6.4.3 <7",
+    "ws": ">=8.21.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+/**
+ * wdk-payment-verifier — server-side on-chain confirmation of self-custodial
+ * WDK Pay payments (the Node/headless counterpart to the WooCommerce PHP verifier).
+ */
+export { PaymentVerifier, matchTransfer, TRANSFER_TOPIC } from './verifier.js'
+export type {
+  VerifierIntent, PaymentStatus, PaymentConfirmation,
+  EvmLog, EvmReceipt, EvmReadProvider,
+  PaymentVerifierOptions, WatchOptions
+} from './verifier.js'

package/src/verifier.spec.ts

@@ -0,0 +1,111 @@
+/**
+ * Unit tests for the payment verifier: Transfer-log matching, one-shot verify
+ * (confirmed / pending / reverted / no-match), and watch (poll → confirm, timeout).
+ * A fake provider stands in for ethers so no network is touched.
+ */
+import { describe, it, expect, vi } from 'vitest'
+import { PaymentVerifier, matchTransfer, TRANSFER_TOPIC, type EvmLog, type EvmReadProvider, type VerifierIntent } from './verifier.js'
+
+const TOKEN = '0xdAC17F958D2ee523a2206206994597C13D831ec7' // USDt
+const MERCHANT = '0x70997970C51812dc3A010C7d01b50e0d17dc79C8'
+const PAYER = '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266'
+const HASH = '0x' + 'ab'.repeat(32)
+
+const intent: VerifierIntent = { tokenAddress: TOKEN, receivingAddress: MERCHANT, amountBase: '100000000' } // 100 USDt
+
+function topicAddr (addr: string): string {
+  return '0x' + addr.slice(2).toLowerCase().padStart(64, '0')
+}
+function valueData (v: bigint): string {
+  return '0x' + v.toString(16).padStart(64, '0')
+}
+function transferLog (over: Partial<EvmLog> & { value?: bigint } = {}): EvmLog {
+  const value = over.value ?? 100_000_000n
+  return {
+    address: over.address ?? TOKEN,
+    topics: over.topics ?? [TRANSFER_TOPIC, topicAddr(PAYER), topicAddr(MERCHANT)],
+    data: over.data ?? valueData(value),
+    blockNumber: over.blockNumber ?? 100,
+    transactionHash: over.transactionHash ?? HASH
+  }
+}
+
+function provider (over: Partial<EvmReadProvider> = {}): EvmReadProvider {
+  return {
+    getTransactionReceipt: vi.fn(async () => ({ status: 1, blockNumber: 100, logs: [transferLog()], transactionHash: HASH })),
+    getBlockNumber: vi.fn(async () => 105),
+    getLogs: vi.fn(async () => []),
+    ...over
+  }
+}
+
+describe('matchTransfer', () => {
+  it('matches a Transfer to the recipient with value ≥ amount', () => {
+    const m = matchTransfer([transferLog()], intent)
+    expect(m?.value).toBe(100_000_000n)
+    expect(m?.from.toLowerCase()).toBe(PAYER.toLowerCase())
+  })
+  it('rejects wrong token, wrong recipient, or short amount', () => {
+    expect(matchTransfer([transferLog({ address: '0x' + '11'.repeat(20) })], intent)).toBeNull()
+    expect(matchTransfer([transferLog({ topics: [TRANSFER_TOPIC, topicAddr(PAYER), topicAddr(PAYER)] })], intent)).toBeNull()
+    expect(matchTransfer([transferLog({ value: 99_999_999n })], intent)).toBeNull()
+  })
+})
+
+describe('verify', () => {
+  it('confirms with enough confirmations', async () => {
+    const v = new PaymentVerifier({ provider: provider() })
+    const r = await v.verify(intent, HASH, 3)
+    expect(r.status).toBe('confirmed')
+    expect(r.confirmations).toBe(6) // 105 - 100 + 1
+    expect(r.valueBase).toBe('100000000')
+    expect(r.fromAddress?.toLowerCase()).toBe(PAYER.toLowerCase())
+  })
+
+  it('is pending while confirmations are insufficient', async () => {
+    const v = new PaymentVerifier({ provider: provider({ getBlockNumber: vi.fn(async () => 100) }) })
+    const r = await v.verify(intent, HASH, 5)
+    expect(r.status).toBe('pending')
+    expect(r.reason).toBe('awaiting_confirmations')
+    expect(r.confirmations).toBe(1)
+  })
+
+  it('is pending when the tx is not mined yet', async () => {
+    const v = new PaymentVerifier({ provider: provider({ getTransactionReceipt: vi.fn(async () => null) }) })
+    expect((await v.verify(intent, HASH)).reason).toBe('not_mined')
+  })
+
+  it('fails on a reverted tx', async () => {
+    const v = new PaymentVerifier({ provider: provider({ getTransactionReceipt: vi.fn(async () => ({ status: 0, blockNumber: 100, logs: [] })) }) })
+    expect((await v.verify(intent, HASH)).status).toBe('failed')
+  })
+
+  it('fails when no matching transfer is present', async () => {
+    const v = new PaymentVerifier({ provider: provider({ getTransactionReceipt: vi.fn(async () => ({ status: 1, blockNumber: 100, logs: [transferLog({ value: 1n })] })) }) })
+    const r = await v.verify(intent, HASH)
+    expect(r.status).toBe('failed')
+    expect(r.reason).toBe('no_matching_transfer')
+  })
+})
+
+describe('watch', () => {
+  it('polls getLogs, finds the transfer, and confirms', async () => {
+    const p = provider({ getLogs: vi.fn(async () => [transferLog()]) })
+    const v = new PaymentVerifier({ provider: p })
+    const r = await v.watch(intent, { requiredConfirmations: 3, fromBlock: 0, sleep: async () => {}, now: () => 0 })
+    expect(r.status).toBe('confirmed')
+    expect(p.getLogs).toHaveBeenCalled()
+  })
+
+  it('resolves pending/timeout when nothing arrives', async () => {
+    let t = 0
+    const v = new PaymentVerifier({ provider: provider() }) // getLogs → []
+    const r = await v.watch(intent, { timeoutMs: 5, pollIntervalMs: 1, fromBlock: 0, sleep: async () => {}, now: () => (t += 10) })
+    expect(r.status).toBe('pending')
+    expect(r.reason).toBe('timeout')
+  })
+
+  it('requires a provider or rpcUrl', () => {
+    expect(() => new PaymentVerifier({})).toThrow()
+  })
+})

package/src/verifier.ts

@@ -0,0 +1,225 @@
+/**
+ * wdk-payment-verifier — server-side on-chain confirmation of WDK Pay payments.
+ *
+ * A payment is a plain ERC-20 transfer of the settlement token to the merchant.
+ * Verification = observe the chain (read-only JSON-RPC) and confirm a
+ * `Transfer(token, to = merchant, value ≥ due)` landed with enough
+ * confirmations. No keys, no custody — the merchant only watches.
+ *
+ * This is the standalone library counterpart to the WooCommerce plugin's PHP
+ * verifier, for Node back-ends / headless commerce. The RPC provider is
+ * injectable (pass an `rpcUrl`, an ethers provider, or any minimal provider for
+ * tests); nothing is hard-coded.
+ */
+import { getAddress } from 'ethers'
+
+/** keccak256("Transfer(address,address,uint256)") — the ERC-20 Transfer topic. */
+export const TRANSFER_TOPIC = '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef'
+
+/** The minimum a verifier needs to know about an order to confirm payment. */
+export interface VerifierIntent {
+  /** Settlement token contract (the Transfer emitter), e.g. USDt. */
+  readonly tokenAddress: string
+  /** Merchant receiving address (the Transfer `to`). */
+  readonly receivingAddress: string
+  /** Minimum amount required, in token base units (decimal string). */
+  readonly amountBase: string
+}
+
+export type PaymentStatus = 'confirmed' | 'pending' | 'failed'
+
+/** The outcome of a verification. */
+export interface PaymentConfirmation {
+  readonly status: PaymentStatus
+  readonly txHash?: string
+  readonly blockNumber?: number
+  readonly confirmations?: number
+  /** The matched transfer's value, base units. */
+  readonly valueBase?: string
+  /** The payer (the Transfer `from`). */
+  readonly fromAddress?: string
+  /** Unix ms when confirmed. */
+  readonly receivedAt?: number
+  /** Machine-readable reason for pending/failed. */
+  readonly reason?: string
+}
+
+/** A single log entry (subset of an eth_getLogs / receipt log). */
+export interface EvmLog {
+  readonly address: string
+  readonly topics: readonly string[]
+  readonly data: string
+  readonly blockNumber?: number
+  readonly transactionHash?: string
+}
+
+/** A transaction receipt subset. */
+export interface EvmReceipt {
+  readonly status?: number | null
+  readonly blockNumber: number
+  readonly logs: readonly EvmLog[]
+  readonly transactionHash?: string
+}
+
+/**
+ * Minimal read-only provider the verifier needs. An ethers `JsonRpcProvider`
+ * satisfies it; tests pass a fake. (ethers receipts expose `logs` and a numeric
+ * `status`; `getLogs` returns the same log shape.)
+ */
+export interface EvmReadProvider {
+  getTransactionReceipt (txHash: string): Promise<EvmReceipt | null>
+  getBlockNumber (): Promise<number>
+  getLogs (filter: {
+    address?: string
+    topics?: (string | null)[]
+    fromBlock?: number | string
+    toBlock?: number | string
+  }): Promise<readonly EvmLog[]>
+}
+
+export interface PaymentVerifierOptions {
+  /** A ready provider (e.g. ethers JsonRpcProvider) — preferred for reuse. */
+  readonly provider?: EvmReadProvider
+  /** Or a JSON-RPC URL; an ethers JsonRpcProvider is created lazily. */
+  readonly rpcUrl?: string
+}
+
+export interface WatchOptions {
+  /** Confirmations required before `confirmed`. Default 1. */
+  readonly requiredConfirmations?: number
+  /** Give up after this many ms (resolves `pending`/`timeout`). Default 15 min. */
+  readonly timeoutMs?: number
+  /** Poll cadence. Default 5s. */
+  readonly pollIntervalMs?: number
+  /** Block to scan logs from. Default: latest − 5000 (or 0). */
+  readonly fromBlock?: number
+  /** Injectable sleep for deterministic tests. */
+  readonly sleep?: (ms: number) => Promise<void>
+  /** Injectable clock (ms) for deterministic tests. */
+  readonly now?: () => number
+}
+
+/** A 32-byte topic word → checksummed address (last 20 bytes). */
+function topicToAddress (topic: string): string {
+  return getAddress('0x' + topic.slice(-40))
+}
+
+function eq (a: string, b: string): boolean {
+  try { return getAddress(a) === getAddress(b) } catch { return false }
+}
+
+/**
+ * Find a Transfer log in `logs` matching the intent (emitter = token,
+ * to = recipient, value ≥ amount). Returns the match or null.
+ */
+export function matchTransfer (
+  logs: readonly EvmLog[],
+  intent: VerifierIntent
+): { value: bigint, from: string, log: EvmLog } | null {
+  const need = BigInt(intent.amountBase)
+  for (const log of logs) {
+    if (!log.topics || log.topics.length < 3) continue
+    if (log.topics[0]?.toLowerCase() !== TRANSFER_TOPIC) continue
+    if (!eq(log.address, intent.tokenAddress)) continue
+    if (!eq(topicToAddress(log.topics[2]!), intent.receivingAddress)) continue
+    let value: bigint
+    try { value = BigInt(log.data) } catch { continue }
+    if (value < need) continue
+    return { value, from: topicToAddress(log.topics[1]!), log }
+  }
+  return null
+}
+
+export class PaymentVerifier {
+  #provider: EvmReadProvider | undefined
+  readonly #rpcUrl: string | undefined
+
+  constructor (opts: PaymentVerifierOptions) {
+    if (!opts.provider && !opts.rpcUrl) throw new Error('PaymentVerifier: pass `provider` or `rpcUrl`.')
+    this.#provider = opts.provider
+    this.#rpcUrl = opts.rpcUrl
+  }
+
+  async #getProvider (): Promise<EvmReadProvider> {
+    if (this.#provider) return this.#provider
+    const { JsonRpcProvider } = await import('ethers')
+    this.#provider = new JsonRpcProvider(this.#rpcUrl) as unknown as EvmReadProvider
+    return this.#provider
+  }
+
+  /**
+   * Verify a specific transaction satisfies the intent. One-shot: checks the
+   * receipt for a matching Transfer and the current confirmation count.
+   */
+  async verify (
+    intent: VerifierIntent,
+    txHash: string,
+    requiredConfirmations = 1
+  ): Promise<PaymentConfirmation> {
+    const provider = await this.#getProvider()
+    let receipt: EvmReceipt | null
+    try {
+      receipt = await provider.getTransactionReceipt(txHash)
+    } catch {
+      return { status: 'pending', txHash, reason: 'rpc_unreachable' }
+    }
+    if (!receipt) return { status: 'pending', txHash, reason: 'not_mined' }
+    if (receipt.status === 0) return { status: 'failed', txHash, reason: 'reverted' }
+
+    const match = matchTransfer(receipt.logs, intent)
+    if (!match) return { status: 'failed', txHash, reason: 'no_matching_transfer' }
+
+    let head: number
+    try { head = await provider.getBlockNumber() } catch {
+      return { status: 'pending', txHash, valueBase: match.value.toString(), reason: 'rpc_unreachable' }
+    }
+    const confirmations = head - receipt.blockNumber + 1
+    const base = {
+      txHash, blockNumber: receipt.blockNumber, confirmations: Math.max(0, confirmations),
+      valueBase: match.value.toString(), fromAddress: match.from
+    }
+    if (confirmations < requiredConfirmations) return { status: 'pending', ...base, reason: 'awaiting_confirmations' }
+    return { status: 'confirmed', ...base, receivedAt: Date.now() }
+  }
+
+  /**
+   * Watch for an incoming payment matching the intent (no tx hash known yet):
+   * polls `getLogs` for a Transfer to the recipient ≥ amount, then waits for
+   * confirmations. Resolves `confirmed`, or `pending` (reason `timeout`) if the
+   * window elapses.
+   */
+  async watch (intent: VerifierIntent, options: WatchOptions = {}): Promise<PaymentConfirmation> {
+    const provider = await this.#getProvider()
+    const requiredConfirmations = options.requiredConfirmations ?? 1
+    const timeoutMs = options.timeoutMs ?? 15 * 60 * 1000
+    const pollIntervalMs = options.pollIntervalMs ?? 5000
+    const sleep = options.sleep ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms)))
+    const now = options.now ?? (() => Date.now())
+
+    const start = now()
+    let fromBlock = options.fromBlock
+    if (fromBlock === undefined) {
+      try { fromBlock = Math.max(0, (await provider.getBlockNumber()) - 5000) } catch { fromBlock = 0 }
+    }
+
+    for (;;) {
+      let logs: readonly EvmLog[] = []
+      try {
+        logs = await provider.getLogs({
+          address: intent.tokenAddress,
+          topics: [TRANSFER_TOPIC, null, '0x' + getAddress(intent.receivingAddress).slice(2).toLowerCase().padStart(64, '0')],
+          fromBlock,
+          toBlock: 'latest'
+        })
+      } catch { /* transient — retry next tick */ }
+
+      const match = matchTransfer(logs, intent)
+      if (match && match.log.transactionHash) {
+        const confirmation = await this.verify(intent, match.log.transactionHash, requiredConfirmations)
+        if (confirmation.status === 'confirmed' || confirmation.status === 'failed') return confirmation
+      }
+      if (now() - start >= timeoutMs) return { status: 'pending', reason: 'timeout' }
+      await sleep(pollIntervalMs)
+    }
+  }
+}