@lemmaoracle/x402 0.1.1

package/scripts/test-with-circuit.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+/**
+ * Combined test script that runs both TypeScript tests and circuit tests
+ * Usage: node scripts/test-with-circuit.mjs
+ */
+
+import { spawn } from 'child_process';
+import { existsSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, resolve } from 'path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT_DIR = resolve(__dirname, '..');
+
+// Check if build files exist
+function checkBuildFiles() {
+  const requiredFiles = [
+    'build/payment_js/payment.wasm',
+    'build/payment_final.zkey',
+    'build/verification_key.json'
+  ];
+  
+  const missingFiles = requiredFiles.filter(file => !existsSync(resolve(ROOT_DIR, file)));
+  return missingFiles;
+}
+
+// Helper function to run commands
+function runCommand(command, args = [], cwd = ROOT_DIR) {
+  return new Promise((resolve, reject) => {
+    console.log(`\n>>> Running: ${command} ${args.join(' ')}`);
+    
+    const child = spawn(command, args, {
+      cwd,
+      stdio: 'inherit',
+      shell: true
+    });
+    
+    child.on('close', (code) => {
+      if (code === 0) {
+        resolve();
+      } else {
+        reject(new Error(`Command failed with exit code ${code}`));
+      }
+    });
+    
+    child.on('error', (error) => {
+      reject(error);
+    });
+  });
+}
+
+async function main() {
+  console.log('=== Running X402 Package Tests ===\n');
+  
+  try {
+    // 1. Run TypeScript tests (direct vitest execution)
+    console.log('1. Running TypeScript tests with Vitest...');
+    await runCommand('npx', ['vitest', 'run']);
+    
+    // 2. Check circuit build files
+    console.log('\n2. Checking circuit build files...');
+    const missingFiles = checkBuildFiles();
+    
+    if (missingFiles.length > 0) {
+      console.log('⚠️  Circuit build files missing. Building circuit...');
+      await runCommand('npm', ['run', 'build:circuit']);
+    } else {
+      console.log('✅ Circuit build files are present.');
+    }
+    
+    // 3. Run circuit tests
+    console.log('\n3. Running circuit tests...');
+    await runCommand('node', ['circuits/payment.test.mjs']);
+    
+    console.log('\n✅ All tests passed!');
+    process.exit(0);
+    
+  } catch (error) {
+    console.error('\n❌ Test failed:', error.message);
+    process.exit(1);
+  }
+}
+
+// Execute main function
+main().catch(error => {
+  console.error('Unhandled error:', error);
+  process.exit(1);
+});

package/src/index.ts

@@ -0,0 +1,115 @@
+import { create, type LemmaClient } from "@lemmaoracle/sdk";
+import * as R from "ramda";
+import type { Config, Disclosure, Proof, Transaction, ProofResult } from "./types.js";
+import { createProofGenerator } from "./proof-generator.js";
+
+/**
+ * Create a Lemma API client from config.
+ */
+const createLemmaClient = (config: Config): LemmaClient =>
+  create({
+    apiBase: config.lemmaApiBase,
+    apiKey: config.lemmaApiKey,
+  });
+
+/**
+ * Build a disclosure object from a proof.
+ */
+const disclosure = (proof: Proof): Disclosure =>
+  ({
+    condition: { circuitId: proof.circuitId },
+    proof: proof.proof,
+    inputs: proof.inputs,
+  });
+
+/**
+ * Build disclosure with empty proof for initial query (will be filled by facilitator).
+ */
+const emptyDisclosure = (circuitId: string): Disclosure =>
+  ({
+    condition: { circuitId },
+    proof: "",
+    inputs: [],
+  });
+
+/**
+ * Create a configured facilitator client with proof generation capabilities.
+ *
+ * Usage:
+ *   const facilitator = facilitator(config);
+ *   
+ *   // Generate disclosure with payment proof
+ *   const disclosure = await facilitator.generateDisclosure(txHash);
+ *   
+ *   // Query Lemma API
+ *   const results = await lemmaApi.query({ disclosure });
+ */
+const facilitator = (config: Config) => {
+  const lemmaClient = createLemmaClient(config);
+  const proofGenerator = createProofGenerator(config, lemmaClient);
+
+  return {
+    /**
+     * Generate a disclosure with payment proof for a transaction.
+     */
+    generateDisclosure: async (txHash: `0x${string}`): Promise<Disclosure> => {
+      const { proof } = await proofGenerator.generateProof(txHash);
+
+      return disclosure(proof);
+    },
+
+    /**
+     * Get an empty disclosure template with condition for the configured circuit.
+     */
+    getEmptyDisclosure: (_?: undefined): Disclosure =>
+      emptyDisclosure(config.circuitId),
+
+    /**
+     * Get the configuration.
+     */
+    getConfig: (_?: undefined): Config => config,
+
+    /**
+     * Get the Lemma client.
+     */
+    getLemmaClient: (_?: undefined): LemmaClient => lemmaClient,
+  };
+};
+
+/**
+ * Default x402 facilitator configuration for Base Sepolia.
+ */
+const defaultConfig = (overrides: Partial<Config> = {}): Config =>
+  R.mergeRight(
+    {
+      payToAddress: "0x" 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, // $0.001 USDC in smallest units (6 decimals)
+      requiredConfirmations: 6,
+      maxProofAge: 3600, // 1 hour
+      ipfsGateway: "https://ipfs.io/ipfs/",
+    },
+    overrides,
+  );
+
+export {
+  facilitator,
+  createProofGenerator,
+  disclosure,
+  emptyDisclosure,
+  defaultConfig,
+  // createLemmaClient is not exported
+};
+
+export type {
+  Config,
+  Disclosure,
+  Proof,
+  Transaction,
+  ProofResult,
+};

package/src/proof-generator.test.ts

@@ -0,0 +1,139 @@
+/**
+ * Tests for x402 payment proof generator.
+ *
+ * Test files are exempt from FP rules.
+ */
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { createProofGenerator } from "./proof-generator.js";
+import type { Config } from "./types.js";
+
+// Mock viem
+vi.mock("viem", async () => {
+  const actual = await vi.importActual("viem");
+  return {
+    ...actual,
+    createPublicClient: vi.fn(() => ({
+      getTransaction: vi.fn().mockResolvedValue({
+        hash: "0xabc123",
+        from: "0xsender",
+        to: "0x2222222222222222222222222222222222222222",
+        value: 1000n,
+      }),
+      getTransactionReceipt: vi.fn().mockResolvedValue({
+        status: "success",
+        blockNumber: 1000n,
+        gasUsed: 21000n,
+        effectiveGasPrice: 1000000000n,
+        confirmations: 6,
+      }),
+      getBlock: vi.fn().mockResolvedValue({
+        number: 1006n,
+        timestamp: 1712000000n,
+      }),
+    })),
+  };
+});
+
+// Mock Lemma SDK
+vi.mock("@lemmaoracle/sdk", async () => {
+  const actual = await vi.importActual("@lemmaoracle/sdk");
+  return {
+    ...actual,
+    prover: {
+      prove: vi.fn().mockResolvedValue({
+        proof: "mock-proof-base64",
+        publicInputs: ["input1", "input2"],
+      }),
+    },
+    createClient: vi.fn().mockReturnValue({
+      apiBase: "https://workers.lemma.workers.dev",
+    }),
+  };
+});
+
+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 mockLemmaClient = {
+  apiBase: "https://workers.lemma.workers.dev",
+};
+
+describe("X402 Proof Generator", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("should create a proof generator", () => {
+    const generator = createProofGenerator(mockConfig, mockLemmaClient as any);
+
+    expect(generator).toBeDefined();
+    expect(typeof generator.generateProof).toBe("function");
+    expect(typeof generator.toFieldElements).toBe("function");
+  });
+
+  it("should convert payment details to field elements", async () => {
+    const generator = createProofGenerator(mockConfig, mockLemmaClient as any);
+
+    const mockPayment = {
+      txHash: "0xabc123" as `0x${string}`,
+      from: "0x1111111111111111111111111111111111111111" as `0x${string}`,
+      to: "0x2222222222222222222222222222222222222222" as `0x${string}`,
+      amount: 1000n,
+      timestamp: 1712000000,
+      blockNumber: 1000n,
+      confirmations: 6,
+    };
+
+    const result = await generator.toFieldElements(mockPayment, mockConfig);
+
+    expect(result).toBeDefined();
+    expect(result.witness).toBeDefined();
+    expect(result.publicInputs).toBeDefined();
+    expect(result.witness.amount).toBeDefined();
+    expect(result.witness.minAmount).toBeDefined();
+  });
+
+  it("should handle empty txHash gracefully", async () => {
+    const generator = createProofGenerator(mockConfig, mockLemmaClient as any);
+
+    expect(generator.generateProof).toBeDefined();
+  });
+});
+
+describe("Field Element Conversion", () => {
+  it("should convert addresses to field elements", async () => {
+    const generator = createProofGenerator(mockConfig, mockLemmaClient as any);
+
+    const mockPayment = {
+      txHash: "0xabc123" as `0x${string}`,
+      from: "0x1111111111111111111111111111111111111111" as `0x${string}`,
+      to: "0x2222222222222222222222222222222222222222" as `0x${string}`,
+      amount: 1000n,
+      timestamp: 1712000000,
+      blockNumber: 1000n,
+      confirmations: 6,
+    };
+
+    const { witness } = await generator.toFieldElements(mockPayment, mockConfig);
+
+    // Verify field elements are present and not null
+    expect(witness.txHashPacked_0).toBeDefined();
+    expect(witness.txHashPacked_1).toBeDefined();
+    expect(witness.recipientLow).toBeDefined();
+    expect(witness.amount).toBeDefined();
+    expect(witness.timestamp).toBeDefined();
+    expect(witness.minAmount).toBeDefined();
+  });
+});

package/src/proof-generator.ts

@@ -0,0 +1,220 @@
+/**
+ * X402 Payment Proof Generator
+ *
+ * Generates ZK proofs for x402 payment transactions so that
+ * Lemma's disclosure.condition API can verify payments without
+ * exposing transaction details.
+ */
+
+import { createPublicClient, http, type PublicClient } from "viem";
+import { prover, type LemmaClient } from "@lemmaoracle/sdk";
+import * as R from "ramda";
+import type {
+  ProofResult,
+  Config,
+  Transaction,
+  Proof,
+} from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Default IPFS gateway if not specified in config */
+const _DEFAULT_IPFS_GATEWAY = "https://ipfs.io/ipfs/";
+
+/** Poseidon hash function for field element hashing */
+const toFieldElement = (value: string): string =>
+  BigInt(value) < 0n
+    ? String(BigInt(value) % 21888242871839275222246405745257275088548364400416034343698204186575808495617n)
+    : value;
+
+// ---------------------------------------------------------------------------
+// Proof Generator Class
+// ---------------------------------------------------------------------------
+
+/**
+ * Generates x402 payment proofs using Lemma's prover infrastructure.
+ *
+ * Usage:
+ *   const generator = new X402ProofGenerator(config, lemmaClient);
+ *   const result = await generator.generateProof(txHash);
+ */
+const createProofGenerator = (
+  config: Config,
+  lemmaClient: LemmaClient,
+): Readonly<{
+  generateProof: (txHash: `0x${string}`) => Promise<ProofResult>;
+  toFieldElements: (
+    payment: Transaction,
+    config: Config,
+  ) => Readonly<{ witness: Record<string, string>; publicInputs: string[] }>;
+}> => {
+  /** Create public client for transaction inspection */
+  const publicClient: PublicClient = createPublicClient({
+    transport: http(config.ethereumRpcUrl),
+  });
+
+  return {
+    /**
+     * Generate a payment proof for a given transaction hash.
+     * This fetches the transaction details, computes the witness,
+     * and generates the ZK proof.
+     */
+    generateProof: async (txHash: `0x${string}`): Promise<ProofResult> => {
+      // Step 1: Fetch transaction details from blockchain
+      const payment = await fetchPaymentTransaction(txHash, publicClient);
+
+      // Step 2: Generate proof
+      const proofResult = await generateZKProof(
+        lemmaClient,
+        payment,
+        config,
+      );
+
+      return R.always({
+        payment,
+        proof: proofResult,
+      })();
+    },
+
+    /**
+     * Convert payment transaction details to circuit field elements.
+     */
+    toFieldElements: (
+      payment: Transaction,
+      cfg: Config,
+    ) => {
+      // Split 256-bit txHash into two 128-bit elements
+      const txHashBigInt = BigInt(payment.txHash);
+      const upper128 = toFieldElement(String(txHashBigInt >> 128n));
+      const lower128 = toFieldElement(String(txHashBigInt & ((1n << 128n) - 1n)));
+
+      // Split 160-bit recipient address
+      const recipientBigInt = BigInt(payment.to);
+      const recipientLow = toFieldElement(String(recipientBigInt & ((1n << 128n) - 1n)));
+      const recipientHigh = toFieldElement(String(recipientBigInt >> 128n));
+
+      // Amount and timestamp
+      const amount = toFieldElement(String(payment.amount));
+      const timestamp = toFieldElement(String(payment.timestamp));
+      const minAmount = toFieldElement(String(cfg.minAmount));
+
+      return R.always({
+        witness: {
+          txHashPacked_0: lower128,
+          txHashPacked_1: upper128,
+          recipientLow,
+          recipientHigh,
+          amount,
+          timestamp,
+          minAmount,
+        },
+        publicInputs: [
+          // commitment will be computed during proof generation
+          toFieldElement(String(cfg.minAmount)), // minAmountPublic
+          toFieldElement(String(cfg.maxProofAge)), // timestampMax
+        ],
+      })();
+    },
+  };
+};
+
+// ---------------------------------------------------------------------------
+// Private Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Fetch payment transaction details from the blockchain.
+ */
+const fetchPaymentTransaction = async (
+  txHash: `0x${string}`,
+  client: PublicClient,
+): Promise<Transaction> => {
+  const txPromise = client.getTransaction({ hash: txHash });
+  const receiptPromise = client.getTransactionReceipt({ hash: txHash });
+  const blockPromise = client.getBlock({ blockTag: "latest" });
+
+  const [tx, receipt, block] = await Promise.all([
+    txPromise,
+    receiptPromise,
+    blockPromise,
+  ]);
+
+  return receipt.status !== "success"
+    ? Promise.reject(new Error(`Transaction ${txHash} failed`))
+    : client.getBlock({ blockNumber: receipt.blockNumber }).then(
+        (blockData) =>
+          R.always({
+            txHash,
+            from: tx.from,
+            to: tx.to ?? ("0x" as `0x${string}`),
+            amount: tx.value + receipt.effectiveGasPrice * receipt.gasUsed,
+            timestamp: Number(blockData.timestamp),
+            blockNumber: receipt.blockNumber,
+            confirmations: Number(block.number - receipt.blockNumber),
+          })(),
+      );
+};
+
+/**
+ * Generate ZK proof for the payment transaction.
+ */
+const generateZKProof = async (
+  lemmaClient: LemmaClient,
+  payment: Transaction,
+  config: Config,
+): Promise<Proof> => {
+  // Build witness from payment transaction
+  const builder = createProofGenerator(config, lemmaClient);
+  const { witness, publicInputs } = builder.toFieldElements(payment, config);
+
+  // Generate proof using Lemma SDK
+  const proofResult = await prover.prove(lemmaClient, {
+    circuitId: config.circuitId,
+    witness,
+  });
+
+  // Compute the commitment for public inputs
+  const commitment = computeCommitment(witness, publicInputs);
+
+  return R.always({
+    proof: proofResult.proof,
+    inputs: [commitment, ...publicInputs],
+    circuitId: config.circuitId,
+    generatedAt: Date.now(),
+  })();
+};
+
+/**
+ * Compute the commitment hash for the circuit public inputs.
+ */
+const computeCommitment = (
+  witness: Record<string, string>,
+  _publicInputs: string[],
+): string => {
+  // The commitment is computed from:
+  // poseidon(txHashPacked[0], txHashPacked[1], recipientLow, amount, timestamp, minAmount)
+  // This should match the public commitment used in the circuit
+  const values = [
+    witness.txHashPacked_0,
+    witness.txHashPacked_1,
+    witness.recipientLow,
+    witness.amount,
+    witness.timestamp,
+    witness.minAmount,
+  ];
+
+  // In a real implementation, use poseidon from circomlib
+  // For now, we use a simple hash placeholder
+  return values.join(",");
+};
+
+export type {
+  ProofResult,
+  Config,
+  Proof,
+  Transaction,
+};
+
+export { createProofGenerator };