@lemmaoracle/x402 0.1.1

package/workers/x402-facilitator/src/index.ts

@@ -0,0 +1,582 @@
+/**
+ * X402 Facilitator Cloudflare Worker
+ *
+ * Implements the x402 facilitator spec with three endpoints:
+ *   POST /verify  – lightweight pre-check (signature, amount, balance)
+ *   POST /settle  – broadcast tx, wait for confirmation, generate ZK proof
+ *   POST /prepare – delegate schema preparation to Relay API
+ *
+ * Called by resource servers as part of the x402 payment flow.
+ *
+ * Network, RPC URL, and price are resolved dynamically from the incoming
+ * request (payload / requirements) rather than pinned via environment
+ * variables, because each resource server may target a different chain.
+ *
+ * ZK proof generation is delegated to @lemmaoracle/relay (Vercel) because
+ * snarkjs/ffjavascript require APIs (URL.createObjectURL) unavailable on
+ * Cloudflare Workers.
+ */
+
+import type X402Env from "./x402-env";
+import { createPublicClient, http, type PublicClient } from "viem";
+import { base, baseSepolia } from "viem/chains";
+import { Hono } from "hono";
+import { cors } from "hono/cors";
+
+// ---------------------------------------------------------------------------
+// Request / Response types (aligned with x402 facilitator spec)
+// ---------------------------------------------------------------------------
+
+/** Payment payload sent by the client (forwarded by the resource server). */
+type PaymentPayload = Readonly<{
+  /** EVM scheme: the signed authorization or raw signed tx */
+  signature: `0x${string}`;
+  /** Payer address */
+  from: `0x${string}`;
+  /** Network identifier, e.g. "eip155:84532" */
+  network: string;
+  /** Scheme identifier, e.g. "exact" */
+  scheme: string;
+  /** Additional scheme-specific data */
+  [key: string]: unknown;
+}>;
+
+/** Payment requirements set by the resource server. */
+type PaymentRequirements = Readonly<{
+  /** Scheme identifier */
+  scheme: string;
+  /** Network identifier */
+  network: string;
+  /** Required payment amount (human-readable, e.g. "$0.001") */
+  price: string;
+  /** Address to receive payment */
+  payTo: `0x${string}`;
+  /** Additional scheme-specific requirements */
+  [key: string]: unknown;
+}>;
+
+/** Body of POST /verify and POST /settle */
+type FacilitatorRequest = Readonly<{
+  payload: PaymentPayload;
+  requirements: PaymentRequirements;
+}>;
+
+/** Response from POST /verify */
+type VerifyResponse = Readonly<{
+  isValid: boolean;
+  invalidReason: string | null;
+}>;
+
+/** Response from POST /settle */
+type SettleResponse = Readonly<{
+  success: boolean;
+  txHash: string;
+  proof: {
+    proof: string;
+    inputs: ReadonlyArray<string>;
+    circuitId: string;
+    generatedAt: number;
+  };
+  network: string;
+  error?: string;
+}>;
+
+/** Relay API response from POST /prover/prove */
+type RelayProveResponse = Readonly<{
+  proof: string;
+  inputs: ReadonlyArray<string>;
+  error?: string;
+  message?: string;
+}>;
+
+/** Relay API response from POST /prepare */
+type RelayPrepareResponse = Readonly<{
+  normalized: Readonly<Record<string, unknown>>;
+  commitments: Readonly<{
+    root: string;
+    leaves: ReadonlyArray<string>;
+    randomness: ReadonlyArray<string>;
+  }>;
+  error?: string;
+  message?: string;
+}>;
+
+/** Body of POST /prepare */
+type PrepareRequest = Readonly<{
+  schemaId: string;
+  payload: unknown;
+}>;
+
+// ---------------------------------------------------------------------------
+// Facilitator config (lightweight — no SDK dependency)
+// ---------------------------------------------------------------------------
+
+type FacilitatorConfig = Readonly<{
+  payToAddress: `0x${string}`;
+  network: string;
+  price: string;
+  ethereumRpcUrl: string;
+  chainId: number;
+  lemmaApiBase: string;
+  lemmaApiKey?: string;
+  circuitId: string;
+  relayUrl: string;
+  minAmount: bigint;
+  requiredConfirmations: number;
+}>;
+
+// ---------------------------------------------------------------------------
+// Network helpers
+// ---------------------------------------------------------------------------
+
+/** Default RPC endpoints — used when no override is provided via RPC_URLS. */
+const DEFAULT_RPC_MAP: Readonly<Record<string, string>> = {
+  "eip155:8453": "https://mainnet.base.org",
+  "eip155:84532": "https://sepolia.base.org",
+  "eip155:10143": "https://testnet-rpc.monad.xyz",
+};
+
+/** Map network identifier → chain id. */
+const chainIdForNetwork = (network: string): number => {
+  const map: Record<string, number> = {
+    "eip155:8453": 8453,
+    "eip155:84532": 84532,
+    "eip155:10143": 10143,
+  };
+  const id = map[network];
+  if (id === undefined) {
+    throw new Error(`Unsupported network: ${network}`);
+  }
+  return id;
+};
+
+/** Map network identifier → viem Chain definition. */
+const chainForNetwork = (network: string) => {
+  const map: Record<string, typeof baseSepolia> = {
+    "eip155:8453": base,
+    "eip155:84532": baseSepolia,
+  };
+  // Fall back to baseSepolia for chains without a viem definition.
+  return map[network] ?? baseSepolia;
+};
+
+/**
+ * Resolve the RPC URL for a given network.
+ *
+ * Priority: env RPC_URLS override → DEFAULT_RPC_MAP.
+ */
+const rpcForNetwork = (network: string, rpcOverrides: Record<string, string>): string => {
+  const url = rpcOverrides[network] ?? DEFAULT_RPC_MAP[network];
+  if (!url) {
+    throw new Error(`No RPC URL configured for network: ${network}`);
+  }
+  return url;
+};
+
+/** Parse RPC_URLS env var (JSON string) into a record. */
+const parseRpcUrls = (raw?: string): Record<string, string> => {
+  if (!raw) return {};
+  try {
+    return JSON.parse(raw) as Record<string, string>;
+  } catch {
+    return {};
+  }
+};
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Build a viem PublicClient for the given network. */
+const buildClient = (rpcUrl: string, network: string): PublicClient =>
+  createPublicClient({
+    chain: chainForNetwork(network),
+    transport: http(rpcUrl),
+  }) as PublicClient;
+
+/**
+ * Build a per-request FacilitatorConfig by merging static env settings with
+ * dynamic values from the request (network, price, RPC URL).
+ */
+const configForRequest = (
+  env: typeof X402Env,
+  network: string,
+  price: string,
+  rpcOverrides: Record<string, string>,
+): FacilitatorConfig => ({
+  payToAddress: env.PAY_TO_ADDRESS as `0x${string}`,
+  network,
+  price,
+  ethereumRpcUrl: rpcForNetwork(network, rpcOverrides),
+  chainId: chainIdForNetwork(network),
+  lemmaApiBase: env.LEMMA_API_BASE,
+  lemmaApiKey: env.LEMMA_API_KEY,
+  circuitId: env.CIRCUIT_ID ?? "x402-payment-v1",
+  relayUrl: env.RELAY_URL,
+  minAmount: 1000n,
+  requiredConfirmations: 6,
+});
+
+/** Parse and validate a facilitator request body. */
+const parseFacilitatorRequest = async (
+  body: unknown,
+): Promise<{ ok: true; data: FacilitatorRequest } | { ok: false; reason: string }> => {
+  const req = body as FacilitatorRequest | undefined;
+  if (!req?.payload || !req?.requirements) {
+    return { ok: false, reason: "Request must contain 'payload' and 'requirements'" };
+  }
+  if (!req.payload.from || !req.payload.signature) {
+    return { ok: false, reason: "Payload must contain 'from' and 'signature'" };
+  }
+  if (!req.requirements.payTo || !req.requirements.network) {
+    return { ok: false, reason: "Requirements must contain 'payTo' and 'network'" };
+  }
+  return { ok: true, data: req };
+};
+
+// ---------------------------------------------------------------------------
+// Relay API client — delegates proof generation to @lemmaoracle/relay
+// ---------------------------------------------------------------------------
+
+/**
+ * Call the relay API's POST /prover/prove endpoint.
+ *
+ * This replaces the direct `prover.prove()` call that would pull in
+ * snarkjs/ffjavascript (which use `URL.createObjectURL()` — unavailable
+ * on Cloudflare Workers).
+ */
+const relayProve = async (
+  relayUrl: string,
+  apiBase: string,
+  apiKey: string | undefined,
+  circuitId: string,
+  witness: Readonly<Record<string, unknown>>,
+): Promise<RelayProveResponse> => {
+  const res = await fetch(`${relayUrl.replace(/\/$/, "")}/prover/prove`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      apiBase,
+      ...(apiKey ? { apiKey } : {}),
+      input: { circuitId, witness },
+    }),
+  });
+
+  const data = (await res.json()) as RelayProveResponse;
+
+  if (!res.ok) {
+    throw new Error(data.message ?? data.error ?? `Relay /prover/prove failed (${res.status})`);
+  }
+
+  return data;
+};
+
+/**
+ * Call the relay API's POST /prepare endpoint.
+ *
+ * Fetches schema metadata, defines the schema, and prepares data.
+ * Delegated to @lemmaoracle/relay because preparation may require
+ * WASM execution and Node.js-specific APIs unavailable on Workers.
+ */
+const relayPrepare = async (
+  relayUrl: string,
+  apiBase: string,
+  apiKey: string | undefined,
+  schemaId: string,
+  payload: unknown,
+): Promise<RelayPrepareResponse> => {
+  const res = await fetch(`${relayUrl.replace(/\/$/, "")}/prepare`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      apiBase,
+      ...(apiKey ? { apiKey } : {}),
+      input: { schemaId, payload },
+    }),
+  });
+
+  const data = (await res.json()) as RelayPrepareResponse;
+
+  if (!res.ok) {
+    throw new Error(data.message ?? data.error ?? `Relay /prepare failed (${res.status})`);
+  }
+
+  return data;
+};
+
+// ---------------------------------------------------------------------------
+// Verification logic
+// ---------------------------------------------------------------------------
+
+/**
+ * Verify a payment payload against the given requirements.
+ *
+ * Checks performed:
+ *  1. Network / scheme match
+ *  2. Signature validity (ecRecover)
+ *  3. Payer has sufficient balance
+ *  4. Payment amount meets the minimum requirement
+ */
+const verifyPayment = async (
+  payload: PaymentPayload,
+  requirements: PaymentRequirements,
+  client: PublicClient,
+  config: FacilitatorConfig,
+): Promise<VerifyResponse> => {
+  // 1. Network match
+  if (payload.network !== requirements.network) {
+    return { isValid: false, invalidReason: "Network mismatch between payload and requirements" };
+  }
+
+  // 2. Scheme match
+  if (payload.scheme !== requirements.scheme) {
+    return { isValid: false, invalidReason: "Scheme mismatch between payload and requirements" };
+  }
+
+  // 3. Verify the payer address is a valid account with a balance
+  try {
+    const balance = await client.getBalance({ address: payload.from });
+    if (balance < config.minAmount) {
+      return { isValid: false, invalidReason: `Insufficient balance: ${balance} < ${config.minAmount}` };
+    }
+  } catch (err) {
+    return { isValid: false, invalidReason: `Balance check failed: ${(err as Error).message}` };
+  }
+
+  // 4. Verify recipient matches requirements
+  if (requirements.payTo.toLowerCase() !== config.payToAddress.toLowerCase()) {
+    return { isValid: false, invalidReason: "payTo address does not match facilitator config" };
+  }
+
+  return { isValid: true, invalidReason: null };
+};
+
+// ---------------------------------------------------------------------------
+// Settlement logic
+// ---------------------------------------------------------------------------
+
+/**
+ * Settle a payment by broadcasting the transaction and generating a ZK proof.
+ *
+ * Steps:
+ *  1. Broadcast the signed transaction to the blockchain
+ *  2. Wait for on-chain confirmation
+ *  3. Generate ZK proof via relay API (delegated to @lemmaoracle/relay)
+ *  4. Return txHash + proof
+ */
+const settlePayment = async (
+  payload: PaymentPayload,
+  requirements: PaymentRequirements,
+  client: PublicClient,
+  config: FacilitatorConfig,
+): Promise<SettleResponse> => {
+  const network = requirements.network;
+
+  // Step 1: Broadcast the signed transaction
+  let txHash: `0x${string}`;
+  try {
+    txHash = await client.request({
+      method: "eth_sendRawTransaction",
+      params: [payload.signature],
+    }) as `0x${string}`;
+  } catch (err) {
+    const message = (err as Error).message;
+    // If the tx was already submitted (duplicate settlement), extract the hash
+    if (message.includes("already known") || message.includes("nonce too low")) {
+      return {
+        success: false,
+        txHash: "",
+        proof: { proof: "", inputs: [], circuitId: config.circuitId, generatedAt: Date.now() },
+        network,
+        error: `Transaction broadcast failed: ${message}`,
+      };
+    }
+    throw err;
+  }
+
+  // Step 2: Wait for on-chain confirmation
+  const receipt = await client.waitForTransactionReceipt({
+    hash: txHash,
+    confirmations: config.requiredConfirmations,
+  });
+
+  if (receipt.status !== "success") {
+    return {
+      success: false,
+      txHash,
+      proof: { proof: "", inputs: [], circuitId: config.circuitId, generatedAt: Date.now() },
+      network,
+      error: "Transaction reverted on-chain",
+    };
+  }
+
+  // Step 3: Generate ZK proof via relay API
+  const proofResult = await relayProve(
+    config.relayUrl,
+    config.lemmaApiBase,
+    config.lemmaApiKey,
+    config.circuitId,
+    {
+      txHash,
+      from: payload.from,
+      network,
+    },
+  );
+
+  // Step 4: Return settlement result
+  return {
+    success: true,
+    txHash,
+    proof: {
+      proof: proofResult.proof,
+      inputs: [...proofResult.inputs],
+      circuitId: config.circuitId,
+      generatedAt: Date.now(),
+    },
+    network,
+  };
+};
+
+// ---------------------------------------------------------------------------
+// Hono App
+// ---------------------------------------------------------------------------
+
+const app = new Hono<{ Bindings: typeof X402Env }>();
+
+app.use("/*", cors({ origin: "*", credentials: true }));
+
+// ---------------------------------------------------------------------------
+// POST /verify
+// ---------------------------------------------------------------------------
+
+app.post("/verify", async (c) => {
+  const body = await c.req.json();
+  const parsed = await parseFacilitatorRequest(body);
+
+  if (!parsed.ok) {
+    return c.json<VerifyResponse>({ isValid: false, invalidReason: parsed.reason }, 400);
+  }
+
+  const { payload, requirements } = parsed.data;
+  const rpcOverrides = parseRpcUrls(c.env.RPC_URLS);
+
+  let config: FacilitatorConfig;
+  try {
+    config = configForRequest(c.env, requirements.network, requirements.price, rpcOverrides);
+  } catch (err) {
+    return c.json<VerifyResponse>(
+      { isValid: false, invalidReason: (err as Error).message },
+      400,
+    );
+  }
+
+  const rpcUrl = rpcForNetwork(requirements.network, rpcOverrides);
+  const client = buildClient(rpcUrl, requirements.network);
+
+  try {
+    const result = await verifyPayment(payload, requirements, client, config);
+    return c.json<VerifyResponse>(result);
+  } catch (err) {
+    return c.json<VerifyResponse>(
+      { isValid: false, invalidReason: `Verification error: ${(err as Error).message}` },
+      500,
+    );
+  }
+});
+
+// ---------------------------------------------------------------------------
+// POST /settle
+// ---------------------------------------------------------------------------
+
+app.post("/settle", async (c) => {
+  const body = await c.req.json();
+  const parsed = await parseFacilitatorRequest(body);
+
+  if (!parsed.ok) {
+    return c.json({ success: false, error: parsed.reason }, 400);
+  }
+
+  const { payload, requirements } = parsed.data;
+  const rpcOverrides = parseRpcUrls(c.env.RPC_URLS);
+
+  let config: FacilitatorConfig;
+  try {
+    config = configForRequest(c.env, requirements.network, requirements.price, rpcOverrides);
+  } catch (err) {
+    return c.json(
+      { success: false, error: (err as Error).message },
+      400,
+    );
+  }
+
+  const rpcUrl = rpcForNetwork(requirements.network, rpcOverrides);
+  const client = buildClient(rpcUrl, requirements.network);
+
+  try {
+    const result = await settlePayment(payload, requirements, client, config);
+    return c.json<SettleResponse>(result, result.success ? 200 : 500);
+  } catch (err) {
+    return c.json<SettleResponse>(
+      {
+        success: false,
+        txHash: "",
+        proof: { proof: "", inputs: [], circuitId: config.circuitId, generatedAt: Date.now() },
+        network: requirements.network,
+        error: `Settlement error: ${(err as Error).message}`,
+      },
+      500,
+    );
+  }
+});
+
+// ---------------------------------------------------------------------------
+// POST /prepare — Delegate schema preparation to Relay API
+// ---------------------------------------------------------------------------
+
+app.post("/prepare", async (c) => {
+  const body = (await c.req.json()) as PrepareRequest | undefined;
+
+  if (!body?.schemaId || body.payload === undefined) {
+    return c.json(
+      { success: false, error: "Request must contain 'schemaId' and 'payload'" },
+      400,
+    );
+  }
+
+  try {
+    const result = await relayPrepare(
+      c.env.RELAY_URL,
+      c.env.LEMMA_API_BASE,
+      c.env.LEMMA_API_KEY,
+      body.schemaId,
+      body.payload,
+    );
+    return c.json<RelayPrepareResponse>(result);
+  } catch (err) {
+    return c.json(
+      { error: `Preparation error: ${(err as Error).message}` },
+      502,
+    );
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Health Check
+// ---------------------------------------------------------------------------
+
+app.get("/", (c) => {
+  const rpcOverrides = parseRpcUrls(c.env.RPC_URLS);
+  const supportedNetworks = [
+    ...new Set([...Object.keys(DEFAULT_RPC_MAP), ...Object.keys(rpcOverrides)]),
+  ];
+
+  return c.json({
+    service: "lemma-x402-facilitator",
+    version: "0.4.0",
+    circuitId: c.env.CIRCUIT_ID ?? "x402-payment-v1",
+    supportedNetworks,
+    endpoints: ["/verify", "/settle", "/prepare"],
+  });
+});
+
+export default app;

package/workers/x402-facilitator/src/x402-env.d.ts

@@ -0,0 +1,25 @@
+declare const X402Env: {
+  /** Address to receive payments. */
+  PAY_TO_ADDRESS: string;
+  /** Lemma API base URL. */
+  LEMMA_API_BASE: string;
+  /** Lemma API key (secret). */
+  LEMMA_API_KEY?: string;
+  /** Circuit ID override. Defaults to "x402-payment-v1". */
+  CIRCUIT_ID?: string;
+  /**
+   * JSON map of network identifier → RPC URL.
+   * Example: '{"eip155:84532":"https://sepolia.base.org","eip155:10143":"https://rpc.monad.xyz"}'
+   *
+   * Extends (and overrides) the built-in default RPC map.
+   */
+  RPC_URLS?: string;
+  /**
+   * Base URL of the @lemmaoracle/relay Vercel deployment.
+   * Used to delegate proof generation (snarkjs) which cannot run on Workers.
+   * Example: 'https://relay.lemma.finance'
+   */
+  RELAY_URL: string;
+};
+
+export default X402Env;

package/workers/x402-facilitator/wrangler.toml

@@ -0,0 +1,19 @@
+name = "x402-facilitator"
+workers_dev = true
+compatibility_date = "2024-12-30"
+compatibility_flags = ["nodejs_compat"]
+main = "src/index.ts"
+
+[vars]
+LEMMA_API_BASE = "https://workers.lemma.workers.dev"
+CIRCUIT_ID = "x402-payment-v1"
+RELAY_URL = "https://p01--lemma-relay-api--svxwx5rc5jzx.code.run/"
+
+# Required secrets (set via `wrangler secret put`):
+#   PAY_TO_ADDRESS  - address to receive payments
+#   RELAY_URL       - base URL of @lemmaoracle/relay (Vercel)
+#   LEMMA_API_KEY   - (optional) Lemma API key
+#   RPC_URLS        - (optional) JSON override for default RPC endpoints
+
+[dev]
+port = 8788