@lemmaoracle/x402 0.1.1

package/src/transaction-watcher.test.ts

@@ -0,0 +1,153 @@
+/**
+ * Tests for x402 transaction watcher.
+ *
+ * Test files are exempt from FP rules.
+ */
+
+import { describe, it, expect, vi } from "vitest";
+import {
+  createTransactionWatcher,
+  isValidPayment,
+  extractPaymentDetails,
+} from "./transaction-watcher.js";
+import type { Config } from "./types.js";
+
+const mockConfig: Config = {
+  payToAddress: "0x2222222222222222222222222222222222222222" as `0x${string}`,
+  network: "eip155:84532",
+  price: "$0.001",
+  ethereumRpcUrl: "https://sepolia.base.org",
+  chainId: 84532,
+  lemmaApiBase: "https://workers.lemma.workers.dev",
+  circuitId: "x402-payment-v1",
+  minAmount: 1000n,
+  requiredConfirmations: 6,
+  maxProofAge: 3600,
+  ipfsGateway: "https://ipfs.io/ipfs/",
+};
+
+const mockTx = {
+  hash: "0xabc123",
+  from: "0x1111111111111111111111111111111111111111",
+  to: "0x2222222222222222222222222222222222222222",
+  value: 2000n,
+  blockNumber: 1000n,
+  blockTimestamp: 1712000000n,
+  gasUsed: 21000n,
+  effectiveGasPrice: 1000000000n,
+};
+
+const mockReceipt = {
+  status: "success" as const,
+  blockNumber: 1000n,
+  confirmations: 6,
+  gasUsed: 21000n,
+  effectiveGasPrice: 1000000000n,
+};
+
+describe("Transaction Watcher", () => {
+  it("should create a watcher", () => {
+    const watcher = createTransactionWatcher(mockConfig, {});
+
+    expect(watcher).toBeDefined();
+    expect(typeof watcher.start).toBe("function");
+    expect(typeof watcher.stop).toBe("function");
+    expect(typeof watcher.onPaymentDetected).toBe("function");
+    expect(typeof watcher.getState).toBe("function");
+  });
+
+  it("should register payment detected callbacks", async () => {
+    const watcher = createTransactionWatcher(mockConfig, {});
+    const callback = vi.fn();
+
+    // Callbacks return Promises
+    const promise = watcher.onPaymentDetected(callback);
+
+    expect(promise).toBeInstanceOf(Promise);
+    await promise;
+  });
+
+  it("should return watcher state", () => {
+    const watcher = createTransactionWatcher(mockConfig, {});
+    const state = watcher.getState();
+
+    expect(state.isRunning).toBe(false);
+    expect(Array.isArray(state.detectedPayments)).toBe(true);
+  });
+});
+
+describe("isValidPayment", () => {
+  it("should validate a correct payment", () => {
+    const currentBlockNumber = 1010n; // Sufficient confirmations (10 confirmations)
+    const result = isValidPayment(mockTx as any, mockReceipt as any, mockConfig, currentBlockNumber);
+
+    expect(result).toBe(true);
+  });
+
+  it("should reject payment to wrong recipient", () => {
+    const badTx = { ...mockTx, to: "0x3333333333333333333333333333333333333333" };
+    const currentBlockNumber = 1010n;
+
+    const result = isValidPayment(badTx as any, mockReceipt as any, mockConfig, currentBlockNumber);
+
+    expect(result).toBe(false);
+  });
+
+  it("should reject payment below minimum amount", () => {
+    const lowTx = { ...mockTx, value: 500n };
+    const currentBlockNumber = 1010n;
+
+    const result = isValidPayment(lowTx as any, mockReceipt as any, mockConfig, currentBlockNumber);
+
+    expect(result).toBe(false);
+  });
+
+  it("should reject failed transaction", () => {
+    const failedReceipt = { ...mockReceipt, status: "reverted" as const };
+    const currentBlockNumber = 1010n;
+
+    const result = isValidPayment(mockTx as any, failedReceipt as any, mockConfig, currentBlockNumber);
+
+    expect(result).toBe(false);
+  });
+
+  it("should reject payment with insufficient confirmations", () => {
+    const currentBlockNumber = 1002n; // Only 2 confirmations (1002 - 1000 = 2)
+    const result = isValidPayment(mockTx as any, mockReceipt as any, mockConfig, currentBlockNumber);
+
+    expect(result).toBe(false);
+  });
+});
+
+describe("extractPaymentDetails", () => {
+  it("should extract payment details from transaction and receipt", () => {
+    const currentBlockNumber = 1010n;
+
+    const details = extractPaymentDetails(
+      mockTx as any,
+      mockReceipt as any,
+      currentBlockNumber,
+    );
+
+    expect(details.txHash).toBe("0xabc123");
+    expect(details.from).toBe("0x1111111111111111111111111111111111111111");
+    expect(details.to).toBe("0x2222222222222222222222222222222222222222");
+    expect(details.amount).toBe(2000n);
+    expect(details.timestamp).toBe(1712000000); // Retrieved from blockTimestamp
+    expect(details.blockNumber).toBe(1000n);
+    expect(details.confirmations).toBe(10);
+  });
+
+  it("should handle missing blockTimestamp", () => {
+    const txNoTimestamp = { ...mockTx, blockTimestamp: undefined };
+    const currentBlockNumber = 1010n;
+
+    const details = extractPaymentDetails(
+      txNoTimestamp as any,
+      mockReceipt as any,
+      currentBlockNumber,
+    );
+
+    expect(details.timestamp).toBe(0);
+  });
+});

package/src/transaction-watcher.ts

@@ -0,0 +1,154 @@
+/**
+ * X402 Transaction Watcher
+ *
+ * Monitors the blockchain for x402 payment transactions to the configured
+ * recipient address and triggers proof generation when payments are detected.
+ */
+
+import type {
+  Transaction as ViemTransaction,
+  TransactionReceipt,
+} from "viem";
+import * as R from "ramda";
+import type { Config, Transaction } from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Callback invoked when a valid payment is detected */
+type PaymentDetectedCallback = (
+  payment: Transaction,
+) => Promise<void>;
+
+/** State of the transaction watcher */
+type WatcherState = Readonly<{
+  isRunning: boolean;
+  lastCheckedBlock: bigint;
+  detectedPayments: ReadonlyArray<PaymentDetectedCallback>;
+}>;
+
+// ---------------------------------------------------------------------------
+// Watcher Implementation
+// ---------------------------------------------------------------------------
+
+const initialState: WatcherState = {
+  isRunning: false,
+  lastCheckedBlock: 0n,
+  detectedPayments: [],
+};
+
+/**
+ * Creates a transaction watcher that monitors for payments to the configured address.
+ *
+ * Uses an immutable state cell (single-element tuple) as a controlled mutable reference.
+ */
+const createTransactionWatcher = (
+  _config: Config,
+  _publicClient: unknown,
+): Readonly<{
+  start: (_?: undefined) => Promise<void>;
+  stop: (_?: undefined) => void;
+  onPaymentDetected: (callback: PaymentDetectedCallback) => Promise<void>;
+  getState: (_?: undefined) => WatcherState;
+}> => {
+  const stateCell = { current: initialState };
+
+  const start = (_?: undefined): Promise<void> => {
+    // eslint-disable-next-line functional/no-expression-statements, functional/immutable-data
+    stateCell.current = {
+      ...stateCell.current,
+      isRunning: true,
+      lastCheckedBlock: 0n,
+    };
+
+    return Promise.resolve();
+  };
+
+  const stop = (_?: undefined): void => {
+    // eslint-disable-next-line functional/no-expression-statements, functional/immutable-data
+    stateCell.current = R.assoc("isRunning", false, stateCell.current);
+  };
+
+  const onPaymentDetected = (
+    callback: PaymentDetectedCallback,
+  ): Promise<void> => {
+    // eslint-disable-next-line functional/no-expression-statements, functional/immutable-data
+    stateCell.current = {
+      ...stateCell.current,
+      detectedPayments: R.append(callback, stateCell.current.detectedPayments),
+    };
+    return Promise.resolve();
+  };
+
+  const getState = (_?: undefined): WatcherState => stateCell.current;
+
+  return {
+    start,
+    stop,
+    onPaymentDetected,
+    getState,
+  };
+};
+
+// ---------------------------------------------------------------------------
+// Utility Functions
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate that a transaction is a valid x402 payment:
+ * - Transaction was successful
+ * - Sent to the correct recipient
+ * - Amount meets the minimum requirement
+ * - Has sufficient confirmations
+ */
+const isValidPayment = (
+  tx: ViemTransaction,
+  receipt: TransactionReceipt,
+  config: Config,
+  currentBlockNumber: bigint = 0n,
+): boolean =>
+  R.allPass([
+    R.always(tx.to === config.payToAddress),
+    R.always(tx.value >= config.minAmount),
+    R.always(receipt.status === "success"),
+    R.always(
+      currentBlockNumber > 0n
+        ? Number(currentBlockNumber - receipt.blockNumber) >= config.requiredConfirmations
+        : true,
+    ),
+  ])();
+
+/**
+ * Extract payment details from transaction and receipt.
+ */
+const extractPaymentDetails = (
+  tx: ViemTransaction,
+  receipt: TransactionReceipt,
+  currentBlockNumber: bigint,
+): Transaction => {
+  const txRecord = tx as unknown as Readonly<Record<string, unknown>>;
+  const rawTimestamp = txRecord["blockTimestamp"];
+  const timestamp = typeof rawTimestamp === "bigint" ? Number(rawTimestamp) : 0;
+
+  return R.always({
+    txHash: tx.hash,
+    from: tx.from,
+    to: tx.to ?? ("0x" as `0x${string}`),
+    amount: tx.value,
+    timestamp,
+    blockNumber: receipt.blockNumber,
+    confirmations: Number(currentBlockNumber - receipt.blockNumber),
+  })();
+};
+
+export type {
+  PaymentDetectedCallback,
+  WatcherState,
+};
+
+export {
+  createTransactionWatcher,
+  isValidPayment,
+  extractPaymentDetails,
+};

package/src/types.ts

@@ -0,0 +1,110 @@
+/** Configuration for payment facilitator */
+type Config = Readonly<{
+  /** x402 facilitator URL (for HTTPFacilitatorClient compatibility) */
+  facilitatorUrl?: string;
+
+  /** Address to receive payments */
+  payToAddress: `0x${string}`;
+
+  /** Network identifier (e.g., "eip155:84532" for Base Sepolia) */
+  network: string;
+
+  /** Price for accessing verified attributes (e.g., "$0.001") */
+  price: string;
+
+  /** Ethereum RPC URL for transaction monitoring */
+  ethereumRpcUrl: string;
+
+  /** Chain ID for the network */
+  chainId: number;
+
+  /** Lemma API base URL */
+  lemmaApiBase: string;
+
+  /** Lemma API key (if required) */
+  lemmaApiKey?: string;
+
+  /** Circuit ID for the payment proof */
+  circuitId: string;
+
+  /** Minimum amount in USDC smallest unit (6 decimals) */
+  minAmount: bigint;
+
+  /** Number of block confirmations before considering payment valid */
+  requiredConfirmations: number;
+
+  /** Maximum age of payment proof in seconds */
+  maxProofAge: number;
+
+  /** IPFS gateway URL for fetching circuit artifacts */
+  ipfsGateway?: string;
+}>;
+
+/** Parsed transaction details */
+type Transaction = Readonly<{
+  /** Transaction hash */
+  txHash: `0x${string}`;
+
+  /** Sender address */
+  from: `0x${string}`;
+
+  /** Recipient address */
+  to: `0x${string}`;
+
+  /** Amount in smallest token unit */
+  amount: bigint;
+
+  /** Block timestamp */
+  timestamp: number;
+
+  /** Block number */
+  blockNumber: bigint;
+
+  /** Number of confirmations */
+  confirmations: number;
+}>;
+
+/** Generated proof with inputs for Lemma API */
+type Proof = Readonly<{
+  /** ZK proof data (base64 encoded) */
+  proof: string;
+
+  /** Public inputs for the circuit */
+  inputs: ReadonlyArray<string>;
+
+  /** Circuit ID used */
+  circuitId: string;
+
+  /** Timestamp when proof was generated */
+  generatedAt: number;
+}>;
+
+/** Result of proof generation */
+type ProofResult = Readonly<{
+  /** Transaction */
+  payment: Transaction;
+
+  /** Generated proof */
+  proof: Proof;
+}>;
+
+/** Disclosure condition for Lemma API query */
+type DisclosureCondition = Readonly<{
+  circuitId: string;
+}>;
+
+/** Disclosure object to send with query */
+type Disclosure = Readonly<{
+  condition?: DisclosureCondition;
+  proof: string;
+  inputs: ReadonlyArray<string>;
+}>;
+
+export type {
+  Config,
+  Transaction,
+  Proof,
+  ProofResult,
+  Disclosure,
+  DisclosureCondition,
+};

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "workers"],
+  "references": [
+    { "path": "../spec" },
+    { "path": "../sdk" }
+  ]
+}

package/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["./src/index.ts","./src/proof-generator.test.ts","./src/proof-generator.ts","./src/transaction-watcher.test.ts","./src/transaction-watcher.ts","./src/types.ts"],"version":"5.8.3"}

package/vitest.config.ts

@@ -0,0 +1,18 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    exclude: [
+      '**/node_modules/**',
+      '**/dist/**',
+      '**/build/**',
+      '**/*.test.mjs', // Exclude circuit test files
+      '**/*.spec.mjs',
+      '**/circuits/**/*.mjs', // Exclude all .mjs files in circuits directory
+    ],
+    include: [
+      '**/*.test.ts',
+      '**/*.spec.ts',
+    ],
+  },
+});