@facilitator/server 0.0.1

package/README.md

@@ -0,0 +1,123 @@
+# @facilitator/server
+
+x402 payment facilitator server implementing gasless ERC-20 and native ETH transfers via [EIP-7702](https://eips.ethereum.org/EIPS/eip-7702) delegated transactions.
+
+A **relayer** pays the gas on behalf of users. Users sign an EIP-712 payment intent and an EIP-7702 authorization that delegates their EOA to the [`Delegate`](../contracts/src/Delegate.sol) contract. The facilitator verifies both signatures off-chain, then submits a single Type 4 transaction to settle the payment on-chain.
+
+## Prerequisites
+
+- [Bun](https://bun.sh/) v1.1+
+- Access to an EVM RPC endpoint (Anvil for local development)
+- A deployed `Delegate` contract (see `packages/contracts`)
+
+## Quick Start
+
+```sh
+# Install dependencies
+bun install
+
+# Set environment variables (or create a .env file — Bun loads it automatically)
+export RELAYER_PRIVATE_KEY="0x..."
+export DELEGATE_ADDRESS="0x..."
+export RPC_URL_31337="http://127.0.0.1:8545"
+
+# Start the server
+bun run start
+
+# Or with file-watching for development
+bun run dev
+```
+
+The server starts on port `3000` by default. Override with the `PORT` environment variable.
+
+## Environment Variables
+
+| Variable              | Required | Description                                               |
+| --------------------- | -------- | --------------------------------------------------------- |
+| `RELAYER_PRIVATE_KEY` | Yes      | Private key of the relayer account that pays gas          |
+| `DELEGATE_ADDRESS`    | Yes      | Deployed `Delegate` contract address                      |
+| `RPC_URL_<chainId>`   | Yes      | RPC endpoint per chain (e.g. `RPC_URL_1`, `RPC_URL_8453`) |
+| `PORT`                | No       | Server port (default: `3000`)                             |
+
+## API
+
+### `GET /healthcheck`
+
+Returns server uptime and status.
+
+### `GET /supported`
+
+Returns supported payment schemes, networks, and the relayer signer address.
+
+### `GET /discovery/resources?limit=100&offset=0`
+
+Lists resources that have been settled through this facilitator (the "bazaar").
+
+### `POST /verify`
+
+Off-chain verification of a payment intent. Checks:
+
+1. EIP-7702 authorization signature recovery
+2. Delegate contract address trust
+3. EIP-712 intent signature validity
+4. Deadline expiration
+5. Nonce uniqueness
+6. Payer balance (ERC-20 `balanceOf` or native ETH `getBalance`)
+
+**Request body:**
+
+```json
+{
+  "paymentPayload": { "..." },
+  "paymentRequirements": { "..." }
+}
+```
+
+### `POST /settle`
+
+Verifies and then submits the payment transaction on-chain. Sends a Type 4 (EIP-7702) transaction through the relayer. If the payer's EOA already has delegated code, the authorization list is omitted.
+
+**Request body:** Same as `/verify`.
+
+## Asset Types
+
+- **ERC-20 tokens:** Set `asset` to the token contract address. Uses `Delegate.transfer()`.
+- **Native ETH:** Set `asset` to `0x0000000000000000000000000000000000000000`. Uses `Delegate.transferEth()`.
+
+## Architecture
+
+```
+src/
+  index.ts      HTTP server (Bun.serve) and route handlers
+  config.ts     Environment config, relayer account, RPC client factory
+  mechanism.ts  EIP-7702 verification and settlement logic
+  storage.ts    In-memory nonce tracker and discovery catalog
+  types.ts      x402 protocol and EIP-7702 type definitions
+  abi.ts        Solidity ABI fragments for Delegate and ERC-20
+test/
+  integration.test.ts   End-to-end test against Anvil
+```
+
+## Testing
+
+Tests require [Foundry](https://getfoundry.sh/) (for Anvil) and compiled contract artifacts.
+
+```sh
+# Build contracts first (from the monorepo root)
+cd packages/contracts && forge build
+
+# Run integration tests
+cd packages/server && bun test
+```
+
+The integration test suite:
+
+1. Starts a local Anvil instance
+2. Deploys `Delegate` and `MockERC20` contracts
+3. Starts the facilitator server
+4. Executes full verify + settle flows for both ERC-20 and native ETH transfers
+5. Asserts on-chain balances after settlement
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@facilitator/server",
+  "version": "0.0.1",
+  "description": "x402 payment facilitator server using EIP-7702 delegated transactions",
+  "module": "src/index.ts",
+  "type": "module",
+  "scripts": {
+    "start": "bun run src/index.ts",
+    "dev": "bun --hot src/index.ts",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@x402/core": "^2.2.0",
+    "viem": "^2.45.1"
+  },
+  "license": "MIT"
+}

package/src/abi.ts

@@ -0,0 +1,58 @@
+export const ERC20_ABI = [
+  {
+    name: "balanceOf",
+    type: "function",
+    stateMutability: "view",
+    inputs: [{ name: "account", type: "address" }],
+    outputs: [{ name: "", type: "uint256" }],
+  },
+] as const;
+
+export const DELEGATE_ABI = [
+  {
+    name: "transfer",
+    type: "function",
+    stateMutability: "nonpayable",
+    inputs: [
+      {
+        name: "intent",
+        type: "tuple",
+        components: [
+          { name: "token", type: "address" },
+          { name: "amount", type: "uint256" },
+          { name: "to", type: "address" },
+          { name: "nonce", type: "uint256" },
+          { name: "deadline", type: "uint256" },
+        ],
+      },
+      { name: "signature", type: "bytes" },
+    ],
+    outputs: [],
+  },
+  {
+    name: "transferEth",
+    type: "function",
+    stateMutability: "nonpayable",
+    inputs: [
+      {
+        name: "intent",
+        type: "tuple",
+        components: [
+          { name: "amount", type: "uint256" },
+          { name: "to", type: "address" },
+          { name: "nonce", type: "uint256" },
+          { name: "deadline", type: "uint256" },
+        ],
+      },
+      { name: "signature", type: "bytes" },
+    ],
+    outputs: [],
+  },
+  {
+    name: "invalidateNonce",
+    type: "function",
+    stateMutability: "nonpayable",
+    inputs: [{ name: "nonce", type: "uint256" }],
+    outputs: [],
+  },
+] as const;

package/src/config.ts

@@ -0,0 +1,54 @@
+import { createPublicClient, createWalletClient, defineChain, http } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+
+const RELAYER_KEY = process.env.RELAYER_PRIVATE_KEY as `0x${string}`;
+if (!RELAYER_KEY) throw new Error("RELAYER_PRIVATE_KEY is required");
+
+export const relayerAccount = privateKeyToAccount(RELAYER_KEY);
+
+export const DELEGATE_CONTRACT_ADDRESS = (process.env.DELEGATE_ADDRESS ??
+  "") as `0x${string}`;
+if (!DELEGATE_CONTRACT_ADDRESS || DELEGATE_CONTRACT_ADDRESS.length !== 42) {
+  throw new Error(
+    "DELEGATE_ADDRESS must be a valid 42-character hex address (0x...)",
+  );
+}
+
+function buildClients(chainId: number) {
+  const rpcUrl = process.env[`RPC_URL_${chainId}`];
+  if (!rpcUrl) {
+    throw new Error(
+      `RPC URL for chain ${chainId} not configured (set RPC_URL_${chainId})`,
+    );
+  }
+
+  const chain = defineChain({
+    id: chainId,
+    name: `Chain ${chainId}`,
+    nativeCurrency: { decimals: 18, name: "Ether", symbol: "ETH" },
+    rpcUrls: { default: { http: [rpcUrl] } },
+  });
+
+  const transport = http(rpcUrl);
+
+  return {
+    publicClient: createPublicClient({ chain, transport }),
+    walletClient: createWalletClient({
+      account: relayerAccount,
+      chain,
+      transport,
+    }),
+  };
+}
+
+type Clients = ReturnType<typeof buildClients>;
+const clientCache = new Map<number, Clients>();
+
+export function getClients(chainId: number): Clients {
+  const cached = clientCache.get(chainId);
+  if (cached) return cached;
+
+  const clients = buildClients(chainId);
+  clientCache.set(chainId, clients);
+  return clients;
+}

package/src/index.ts

@@ -0,0 +1,147 @@
+import { DELEGATE_CONTRACT_ADDRESS, relayerAccount, getClients } from "./config";
+import { formatEther } from "viem";
+import { mechanism } from "./mechanism";
+import { bazaarManager } from "./storage";
+import type {
+  DiscoveryResponse,
+  SettleRequest,
+  SettleResponse,
+  SupportedResponse,
+  VerifyRequest,
+  VerifyResponse,
+} from "./types";
+
+const PORT = Number(process.env.PORT) || 3000;
+
+const CORS_HEADERS = {
+  "Access-Control-Allow-Origin": "*",
+  "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+  "Access-Control-Allow-Headers": "Content-Type, Payment-Signature",
+} as const;
+
+function json(data: unknown, status = 200) {
+  return Response.json(data, { status, headers: CORS_HEADERS });
+}
+
+// --- Route Handlers ---
+
+function handleHealthcheck() {
+  return json({
+    status: "ok",
+    uptime: process.uptime(),
+    timestamp: Date.now(),
+  });
+}
+
+function handleSupported() {
+  const response: SupportedResponse = {
+    kinds: [
+      {
+        x402Version: 2,
+        scheme: "eip7702",
+        network: "eip155:*",
+        extra: {},
+      },
+    ],
+    extensions: ["bazaar"],
+    signers: { "eip155:*": [relayerAccount.address] },
+  };
+  return json({ ...response, delegateContract: DELEGATE_CONTRACT_ADDRESS });
+}
+
+function handleDiscovery(url: URL) {
+  const limit = Number(url.searchParams.get("limit")) || 100;
+  const offset = Number(url.searchParams.get("offset")) || 0;
+  const { items, total } = bazaarManager.list(limit, offset);
+
+  const response: DiscoveryResponse = {
+    x402Version: 2,
+    items,
+    pagination: { limit, offset, total },
+  };
+  return json(response);
+}
+
+async function handleVerify(req: Request) {
+  const body = (await req.json()) as VerifyRequest;
+  const result: VerifyResponse = await mechanism.verify(
+    body.paymentPayload,
+    body.paymentRequirements,
+  );
+  return json(result);
+}
+
+async function handleSettle(req: Request) {
+  const body = (await req.json()) as SettleRequest;
+  const result: SettleResponse = await mechanism.settle(
+    body.paymentPayload,
+    body.paymentRequirements,
+  );
+
+  if (result.success && body.paymentPayload.resource?.url) {
+    bazaarManager.upsert({
+      resource: body.paymentPayload.resource.url,
+      type: "http",
+      x402Version: 2,
+      accepts: [body.paymentRequirements],
+      lastUpdated: new Date().toISOString(),
+      metadata: body.paymentPayload.extensions?.bazaar as
+        | Record<string, unknown>
+        | undefined,
+    });
+  }
+
+  return json(result);
+}
+
+async function handleBalance() {
+  try {
+    // Default to Anvil chain ID 31337 for this demo
+    const chainId = 31337; 
+    const { publicClient } = getClients(chainId);
+    const balance = await publicClient.getBalance({ address: relayerAccount.address });
+    
+    return json({
+      address: relayerAccount.address,
+      eth: formatEther(balance),
+      chainId
+    });
+  } catch (e) {
+    return json({ error: "Failed to fetch balance", details: (e as Error).message }, 500);
+  }
+}
+
+// --- Server ---
+
+Bun.serve({
+  port: PORT,
+  async fetch(req) {
+    if (req.method === "OPTIONS") {
+      return new Response(null, { headers: CORS_HEADERS });
+    }
+
+    const url = new URL(req.url);
+
+    try {
+      if (req.method === "GET") {
+        if (url.pathname === "/healthcheck") return handleHealthcheck();
+        if (url.pathname === "/supported") return handleSupported();
+        if (url.pathname === "/discovery/resources")
+          return handleDiscovery(url);
+        if (url.pathname === "/balance") return await handleBalance();
+      }
+
+      if (req.method === "POST") {
+        if (url.pathname === "/verify") return await handleVerify(req);
+        if (url.pathname === "/settle") return await handleSettle(req);
+      }
+
+      return new Response("Not Found", { status: 404, headers: CORS_HEADERS });
+    } catch (e) {
+      console.error(e);
+      return json({ error: (e as Error).message }, 500);
+    }
+  },
+});
+
+console.log(`x402 EIP-7702 Facilitator running on port ${PORT}`);

package/src/mechanism.ts

@@ -0,0 +1,306 @@
+import { type Address, encodeFunctionData, verifyTypedData } from "viem";
+import { recoverAuthorizationAddress } from "viem/utils";
+import { DELEGATE_ABI, ERC20_ABI } from "./abi";
+import {
+  DELEGATE_CONTRACT_ADDRESS,
+  getClients,
+  relayerAccount,
+} from "./config";
+import { nonceManager } from "./storage";
+import {
+  ADDRESS_ZERO,
+  type Eip7702Authorization,
+  type Eip7702EthPayloadData,
+  type Eip7702PayloadData,
+  type PaymentPayload,
+  type PaymentRequirements,
+  type SettleResponse,
+  type VerifyResponse,
+} from "./types";
+
+// --- EIP-712 Type Definitions ---
+
+const EIP712_DOMAIN = {
+  name: "Delegate",
+  version: "1.0",
+} as const;
+
+const ERC20_INTENT_TYPES = {
+  PaymentIntent: [
+    { name: "token", type: "address" },
+    { name: "amount", type: "uint256" },
+    { name: "to", type: "address" },
+    { name: "nonce", type: "uint256" },
+    { name: "deadline", type: "uint256" },
+  ],
+} as const;
+
+const ETH_INTENT_TYPES = {
+  EthPaymentIntent: [
+    { name: "amount", type: "uint256" },
+    { name: "to", type: "address" },
+    { name: "nonce", type: "uint256" },
+    { name: "deadline", type: "uint256" },
+  ],
+} as const;
+
+// --- Helpers ---
+
+function isEthPayment(reqs: PaymentRequirements): boolean {
+  return reqs.asset.toLowerCase() === ADDRESS_ZERO.toLowerCase();
+}
+
+function parseChainId(network: string): number {
+  const chainId = Number(network.split(":")[1]);
+  if (isNaN(chainId)) throw new Error(`Invalid network format: ${network}`);
+  return chainId;
+}
+
+function extractPayload<T extends Eip7702PayloadData | Eip7702EthPayloadData>(
+  payload: Record<string, unknown>,
+): T {
+  if (!payload.authorization || !payload.intent || !payload.signature) {
+    throw new Error("Missing required EIP-7702 payload fields");
+  }
+  return payload as unknown as T;
+}
+
+function buildDomain(chainId: number, verifyingContract: Address) {
+  return { ...EIP712_DOMAIN, chainId, verifyingContract };
+}
+
+// --- Mechanism ---
+
+export class Eip7702Mechanism {
+  private async recoverSigner(authorization: Eip7702Authorization) {
+    const signer = await recoverAuthorizationAddress({
+      authorization: {
+        contractAddress: authorization.contractAddress,
+        to: authorization.contractAddress,
+        chainId: authorization.chainId,
+        nonce: authorization.nonce,
+      },
+      signature: {
+        r: authorization.r,
+        s: authorization.s,
+        yParity: authorization.yParity,
+      },
+    });
+
+    if (
+      authorization.contractAddress.toLowerCase() !==
+      DELEGATE_CONTRACT_ADDRESS.toLowerCase()
+    ) {
+      throw new Error("Untrusted Delegate Contract");
+    }
+
+    return signer;
+  }
+
+  private async verifyIntentSignature(
+    payload: PaymentPayload,
+    ethPayment: boolean,
+    chainId: number,
+    signer: Address,
+    signature: `0x${string}`,
+  ): Promise<boolean> {
+    const domain = buildDomain(chainId, signer);
+
+    if (ethPayment) {
+      const { intent } = extractPayload<Eip7702EthPayloadData>(payload.payload);
+      return verifyTypedData({
+        address: signer,
+        domain,
+        types: ETH_INTENT_TYPES,
+        primaryType: "EthPaymentIntent",
+        message: {
+          amount: BigInt(intent.amount),
+          to: intent.to,
+          nonce: BigInt(intent.nonce),
+          deadline: BigInt(intent.deadline),
+        },
+        signature,
+      });
+    }
+
+    const { intent } = extractPayload<Eip7702PayloadData>(payload.payload);
+    return verifyTypedData({
+      address: signer,
+      domain,
+      types: ERC20_INTENT_TYPES,
+      primaryType: "PaymentIntent",
+      message: {
+        token: intent.token,
+        amount: BigInt(intent.amount),
+        to: intent.to,
+        nonce: BigInt(intent.nonce),
+        deadline: BigInt(intent.deadline),
+      },
+      signature,
+    });
+  }
+
+  async verify(
+    payload: PaymentPayload,
+    reqs: PaymentRequirements,
+  ): Promise<VerifyResponse> {
+    try {
+      const chainId = parseChainId(reqs.network);
+      const ethPayment = isEthPayment(reqs);
+      const { authorization, signature } = extractPayload<Eip7702PayloadData>(
+        payload.payload,
+      );
+      const { publicClient } = getClients(chainId);
+
+      // 1. Verify EIP-7702 authorization
+      const signer = await this.recoverSigner(authorization);
+
+      // 2. Verify EIP-712 intent signature
+      const valid = await this.verifyIntentSignature(
+        payload,
+        ethPayment,
+        chainId,
+        signer,
+        signature,
+      );
+      if (!valid) {
+        return { isValid: false, invalidReason: "Invalid Intent Signature" };
+      }
+
+      // 3. Check deadline
+      const intent = extractPayload<Eip7702PayloadData>(payload.payload).intent;
+      if (BigInt(intent.deadline) < BigInt(Math.floor(Date.now() / 1000))) {
+        return { isValid: false, invalidReason: "Deadline Expired" };
+      }
+
+      // 4. Check nonce
+      if (!nonceManager.checkAndMark(intent.nonce.toString())) {
+        return { isValid: false, invalidReason: "Nonce Used" };
+      }
+
+      // 5. Check balance
+      if (ethPayment) {
+        const balance = await publicClient.getBalance({ address: signer });
+        if (balance < BigInt(intent.amount)) {
+          return { isValid: false, invalidReason: "Insufficient Balance" };
+        }
+      } else {
+        const balance = await publicClient.readContract({
+          address: intent.token,
+          abi: ERC20_ABI,
+          functionName: "balanceOf",
+          args: [signer],
+        });
+        if (balance < BigInt(intent.amount)) {
+          return { isValid: false, invalidReason: "Insufficient Balance" };
+        }
+      }
+
+      return { isValid: true, payer: signer };
+    } catch (e) {
+      console.error(e);
+      return { isValid: false, invalidReason: (e as Error).message };
+    }
+  }
+
+  async settle(
+    payload: PaymentPayload,
+    reqs: PaymentRequirements,
+  ): Promise<SettleResponse> {
+    try {
+      const verification = await this.verify(payload, reqs);
+      if (!verification.isValid) throw new Error(verification.invalidReason);
+
+      const chainId = parseChainId(reqs.network);
+      const { walletClient, publicClient } = getClients(chainId);
+      const ethPayment = isEthPayment(reqs);
+      const { authorization, signature } = extractPayload<Eip7702PayloadData>(
+        payload.payload,
+      );
+      const payer = verification.payer! as Address;
+
+      // Encode call data
+      let data;
+      if (ethPayment) {
+        const { intent } = extractPayload<Eip7702EthPayloadData>(
+          payload.payload,
+        );
+        data = encodeFunctionData({
+          abi: DELEGATE_ABI,
+          functionName: "transferEth",
+          args: [
+            {
+              amount: BigInt(intent.amount),
+              to: intent.to,
+              nonce: BigInt(intent.nonce),
+              deadline: BigInt(intent.deadline),
+            },
+            signature,
+          ],
+        });
+      } else {
+        const { intent } = extractPayload<Eip7702PayloadData>(payload.payload);
+        data = encodeFunctionData({
+          abi: DELEGATE_ABI,
+          functionName: "transfer",
+          args: [
+            {
+              token: intent.token,
+              amount: BigInt(intent.amount),
+              to: intent.to,
+              nonce: BigInt(intent.nonce),
+              deadline: BigInt(intent.deadline),
+            },
+            signature,
+          ],
+        });
+      }
+
+      // Skip authorization list if payer already has delegated code
+      const code = await publicClient.getCode({ address: payer });
+      const hasCode = code && code !== "0x";
+
+      const txBase = {
+        account: relayerAccount,
+        chain: walletClient.chain,
+        to: payer,
+        data,
+      } as const;
+
+      const hash = hasCode
+        ? await walletClient.sendTransaction(txBase)
+        : await walletClient.sendTransaction({
+            ...txBase,
+            authorizationList: [
+              {
+                contractAddress: authorization.contractAddress,
+                address: authorization.contractAddress,
+                chainId: authorization.chainId,
+                nonce: authorization.nonce,
+                r: authorization.r,
+                s: authorization.s,
+                yParity: authorization.yParity,
+              },
+            ],
+          });
+
+      await publicClient.waitForTransactionReceipt({ hash });
+
+      return {
+        success: true,
+        transaction: hash,
+        network: reqs.network,
+        payer,
+      };
+    } catch (e) {
+      return {
+        success: false,
+        errorReason: (e as Error).message,
+        transaction: "",
+        network: reqs.network,
+      };
+    }
+  }
+}
+
+export const mechanism = new Eip7702Mechanism();