x402-fl 0.0.0

package/dist/lib/chain.js

@@ -0,0 +1,30 @@
+import { createPublicClient as viemCreatePublicClient, createWalletClient as viemCreateWalletClient, defineChain, http, publicActions, } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+export async function fetchChainId(rpcUrl) {
+    const client = viemCreatePublicClient({ transport: http(rpcUrl) });
+    return client.getChainId();
+}
+export function createLocalChain(rpcUrl, chainId) {
+    return defineChain({
+        id: chainId,
+        name: "Local Anvil Fork",
+        nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
+        rpcUrls: {
+            default: { http: [rpcUrl] },
+        },
+    });
+}
+export function createPublicClient(rpcUrl, chainId) {
+    return viemCreatePublicClient({
+        chain: createLocalChain(rpcUrl, chainId),
+        transport: http(rpcUrl),
+    });
+}
+export function createWalletClient(privateKey, rpcUrl, chainId) {
+    const account = privateKeyToAccount(privateKey);
+    return viemCreateWalletClient({
+        account,
+        chain: createLocalChain(rpcUrl, chainId),
+        transport: http(rpcUrl),
+    }).extend(publicActions);
+}

package/dist/lib/config.d.ts

@@ -0,0 +1,15 @@
+export declare const accounts: {
+    facilitator: {
+        address: `0x${string}`;
+        privateKey: `0x${string}`;
+    };
+};
+export declare const defaults: {
+    readonly anvilPort: 8545;
+    readonly facilitatorPort: 4022;
+};
+export declare function networkId(chainId: number): `eip155:${number}`;
+export declare const USDC_ADDRESS: `0x${string}`;
+export declare const DEFAULT_DECIMALS = 6;
+export declare function parseTokenAmount(amount: string, decimals?: number): bigint;
+export declare function formatTokenAmount(raw: bigint, decimals?: number): string;

package/dist/lib/config.js

@@ -0,0 +1,31 @@
+import { mnemonicToAccount } from "viem/accounts";
+// Anvil default mnemonic — first account (index 0) is the facilitator
+const ANVIL_MNEMONIC = "test test test test test test test test test test test junk";
+const facilitatorAccount = mnemonicToAccount(ANVIL_MNEMONIC, { addressIndex: 0 });
+export const accounts = {
+    facilitator: {
+        address: facilitatorAccount.address,
+        privateKey: `0x${Buffer.from(facilitatorAccount.getHdKey().privateKey).toString("hex")}`,
+    },
+};
+export const defaults = {
+    anvilPort: 8545,
+    facilitatorPort: 4022,
+};
+export function networkId(chainId) {
+    return `eip155:${chainId}`;
+}
+// Base mainnet USDC
+export const USDC_ADDRESS = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+export const DEFAULT_DECIMALS = 6;
+export function parseTokenAmount(amount, decimals = DEFAULT_DECIMALS) {
+    const [whole, frac = ""] = amount.split(".");
+    const padded = frac.padEnd(decimals, "0").slice(0, decimals);
+    return BigInt(whole + padded);
+}
+export function formatTokenAmount(raw, decimals = DEFAULT_DECIMALS) {
+    const str = raw.toString().padStart(decimals + 1, "0");
+    const whole = str.slice(0, -decimals);
+    const frac = str.slice(-decimals).replace(/0+$/, "") || "0";
+    return `${whole}.${frac}`;
+}

package/dist/lib/facilitator.d.ts

@@ -0,0 +1,7 @@
+import type { Server } from "http";
+export interface FacilitatorOptions {
+    port: number;
+    rpcUrl: string;
+    chainId: number;
+}
+export declare function startFacilitator(options: FacilitatorOptions): Promise<Server>;

package/dist/lib/facilitator.js

@@ -0,0 +1,93 @@
+import express from "express";
+import { x402Facilitator } from "@x402/core/facilitator";
+import { toFacilitatorEvmSigner } from "@x402/evm";
+import { ExactEvmScheme } from "@x402/evm/exact/facilitator";
+import { createWalletClient } from "./chain.js";
+import { accounts, networkId } from "./config.js";
+export function startFacilitator(options) {
+    const viemClient = createWalletClient(accounts.facilitator.privateKey, options.rpcUrl, options.chainId);
+    const evmSigner = toFacilitatorEvmSigner({
+        address: accounts.facilitator.address,
+        readContract: (args) => viemClient.readContract(args),
+        verifyTypedData: (args) => viemClient.verifyTypedData(args),
+        writeContract: (args) => viemClient.writeContract(args),
+        sendTransaction: (args) => viemClient.sendTransaction(args),
+        waitForTransactionReceipt: (args) => viemClient.waitForTransactionReceipt(args),
+        getCode: (args) => viemClient.getCode(args),
+    });
+    const facilitator = new x402Facilitator();
+    const network = networkId(options.chainId);
+    facilitator.register(network, new ExactEvmScheme(evmSigner));
+    const app = express();
+    app.use(express.json());
+    app.use((req, res, next) => {
+        const start = Date.now();
+        res.on("finish", () => {
+            console.log(`[facilitator] ${req.method} ${req.path} ${res.statusCode} (${Date.now() - start}ms)`);
+        });
+        next();
+    });
+    app.post("/verify", async (req, res) => {
+        try {
+            const { paymentPayload, paymentRequirements } = req.body;
+            if (!paymentPayload || !paymentRequirements) {
+                res
+                    .status(400)
+                    .json({ error: "Missing paymentPayload or paymentRequirements" });
+                return;
+            }
+            const response = await facilitator.verify(paymentPayload, paymentRequirements);
+            res.json(response);
+        }
+        catch (error) {
+            console.error("Verify error:", error);
+            res.status(500).json({
+                error: error instanceof Error ? error.message : "Unknown error",
+            });
+        }
+    });
+    app.post("/settle", async (req, res) => {
+        try {
+            const { paymentPayload, paymentRequirements } = req.body;
+            if (!paymentPayload || !paymentRequirements) {
+                res
+                    .status(400)
+                    .json({ error: "Missing paymentPayload or paymentRequirements" });
+                return;
+            }
+            const response = await facilitator.settle(paymentPayload, paymentRequirements);
+            res.json(response);
+        }
+        catch (error) {
+            console.error("Settle error:", error);
+            res.status(500).json({
+                error: error instanceof Error ? error.message : "Unknown error",
+            });
+        }
+    });
+    app.get("/supported", (_req, res) => {
+        try {
+            const response = facilitator.getSupported();
+            res.json(response);
+        }
+        catch (error) {
+            console.error("Supported error:", error);
+            res.status(500).json({
+                error: error instanceof Error ? error.message : "Unknown error",
+            });
+        }
+    });
+    app.get("/health", (_req, res) => {
+        res.json({
+            status: "ok",
+            network,
+            facilitator: accounts.facilitator.address,
+        });
+    });
+    return new Promise((resolve, reject) => {
+        const server = app.listen(options.port, () => {
+            resolve(server);
+        });
+        server.on("error", reject);
+    });
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "x402-fl",
+  "version": "0.0.0",
+  "description": "Local x402 facilitator dev tool, spin up Anvil + facilitator for local x402 development",
+  "type": "module",
+  "bin": {
+    "x402-fl": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/cli.ts dev"
+  },
+  "keywords": [
+    "x402",
+    "facilitator",
+    "local",
+    "development",
+    "anvil"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@x402/core": "^2.5.0",
+    "@x402/evm": "^2.5.0",
+    "boxen": "^8.0.1",
+    "chalk": "^5.6.2",
+    "commander": "^12.1.0",
+    "dotenv": "^16.4.7",
+    "express": "^4.21.2",
+    "viem": "^2.39.3"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.0",
+    "@types/node": "^22.13.4",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.3"
+  },
+  "packageManager": "pnpm@10.28.2",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+
+import { readFileSync } from "fs";
+import { Command, InvalidArgumentError } from "commander";
+import dotenv from "dotenv";
+import { defaults } from "./lib/config.js";
+
+const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf-8"));
+
+dotenv.config();
+
+function parsePort(value: string): number {
+  const port = parseInt(value, 10);
+  if (isNaN(port) || port < 1 || port > 65535) {
+    throw new InvalidArgumentError("must be a number between 1 and 65535");
+  }
+  return port;
+}
+
+function parseAddress(value: string): `0x${string}` {
+  if (!/^0x[0-9a-fA-F]{40}$/.test(value)) {
+    throw new InvalidArgumentError(
+      "must be a valid 0x-prefixed Ethereum address (42 characters)",
+    );
+  }
+  return value as `0x${string}`;
+}
+
+function parseAmount(value: string): string {
+  if (!/^\d+(\.\d+)?$/.test(value) || Number(value) <= 0) {
+    throw new InvalidArgumentError(
+      "must be a positive number (e.g. '100' or '1.5')",
+    );
+  }
+  return value;
+}
+
+const program = new Command();
+
+program
+  .name("x402-fl")
+  .description(
+    "Local x402 facilitator dev tool\n\n" +
+      "  Spin up a local Anvil fork and x402 facilitator server for development.\n" +
+      "  Requires `anvil` (from Foundry) to be installed and available in PATH.\n\n" +
+      "  Quick start:\n" +
+      "    $ x402-fl dev --rpc-url https://mainnet.base.org\n" +
+      "    $ x402-fl fund 0xYourAddress 100",
+  )
+  .version(pkg.version)
+  .showHelpAfterError(true)
+  .configureHelp({ showGlobalOptions: true });
+
+program
+  .command("dev")
+  .description(
+    "Start Anvil fork + facilitator server for local x402 development",
+  )
+  .option(
+    "--port <number>",
+    `facilitator server port (default: ${defaults.facilitatorPort})`,
+    parsePort,
+    defaults.facilitatorPort,
+  )
+  .option(
+    "--anvil-port <number>",
+    `Anvil JSON-RPC port (default: ${defaults.anvilPort})`,
+    parsePort,
+    defaults.anvilPort,
+  )
+  .option(
+    "--rpc-url <url>",
+    "Base mainnet RPC URL to fork (or set BASE_RPC_URL in .env)",
+  )
+  .addHelpText(
+    "after",
+    `
+Examples:
+  $ x402-fl dev --rpc-url https://mainnet.base.org
+  $ x402-fl dev --rpc-url $BASE_RPC_URL --port 5000 --anvil-port 9545
+
+Environment variables:
+  BASE_RPC_URL    Fallback RPC URL when --rpc-url is not provided`,
+  )
+  .action(async (opts) => {
+    const rpcUrl = opts.rpcUrl || process.env.BASE_RPC_URL;
+    if (!rpcUrl) {
+      program.error(
+        "missing required RPC URL\n\n" +
+          "  Provide one of:\n" +
+          "    --rpc-url <url>          pass directly as a flag\n" +
+          "    BASE_RPC_URL=<url>       set in .env or environment\n\n" +
+          "  Example:\n" +
+          "    $ x402-fl dev --rpc-url https://mainnet.base.org",
+      );
+    }
+
+    const { devCommand } = await import("./commands/dev.js");
+    await devCommand({
+      port: opts.port,
+      anvilPort: opts.anvilPort,
+      rpcUrl,
+    });
+  });
+
+program
+  .command("fund")
+  .description("Fund an address with USDC on local Anvil")
+  .argument("<address>", "0x-prefixed Ethereum address to fund", parseAddress)
+  .argument(
+    "<amount>",
+    "USDC amount (e.g. '100' or '1.5')",
+    parseAmount,
+  )
+  .option(
+    "--anvil-port <number>",
+    `Anvil JSON-RPC port`,
+    parsePort,
+    defaults.anvilPort,
+  )
+  .addHelpText(
+    "after",
+    `
+Examples:
+  $ x402-fl fund 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 100
+  $ x402-fl fund 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 1.5 --anvil-port 9545`,
+  )
+  .action(async (address: `0x${string}`, amount: string, opts) => {
+    const { fundCommand } = await import("./commands/fund.js");
+    await fundCommand({
+      address,
+      amount,
+      anvilPort: opts.anvilPort,
+    });
+  });
+
+program
+  .command("balance")
+  .description("Get USDC balance for an address on local Anvil")
+  .argument("<address>", "0x-prefixed Ethereum address to check", parseAddress)
+  .option(
+    "--anvil-port <number>",
+    `Anvil JSON-RPC port`,
+    parsePort,
+    defaults.anvilPort,
+  )
+  .addHelpText(
+    "after",
+    `
+Examples:
+  $ x402-fl balance 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266
+  $ x402-fl balance 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 --anvil-port 9545`,
+  )
+  .action(async (address: `0x${string}`, opts) => {
+    const { balanceCommand } = await import("./commands/balance.js");
+    await balanceCommand({
+      address,
+      anvilPort: opts.anvilPort,
+    });
+  });
+
+program.parse();

package/src/commands/balance.ts

@@ -0,0 +1,66 @@
+import chalk from "chalk";
+import boxen from "boxen";
+import { createPublicClient, fetchChainId } from "../lib/chain.js";
+import {
+  DEFAULT_DECIMALS,
+  formatTokenAmount,
+  USDC_ADDRESS,
+} from "../lib/config.js";
+import { ERC20_ABI } from "../lib/abi.js";
+
+export interface BalanceOptions {
+  address: `0x${string}`;
+  anvilPort: number;
+}
+
+export async function balanceCommand(options: BalanceOptions): Promise<void> {
+  const { address, anvilPort } = options;
+  const rpcUrl = `http://localhost:${anvilPort}`;
+
+  let chainId: number;
+  try {
+    chainId = await fetchChainId(rpcUrl);
+  } catch {
+    console.error(
+      `Error: Could not connect to Anvil at ${rpcUrl}.\n` +
+        `Make sure Anvil is running (e.g. "x402-fl dev" or "anvil --fork-url ...").`,
+    );
+    process.exit(1);
+  }
+
+  const client = createPublicClient(rpcUrl, chainId);
+
+  let decimals = DEFAULT_DECIMALS;
+  try {
+    decimals = await client.readContract({
+      address: USDC_ADDRESS,
+      abi: ERC20_ABI,
+      functionName: "decimals",
+    });
+  } catch {
+    // Non-standard token without decimals(); fall back to default
+  }
+
+  const balance = await client.readContract({
+    address: USDC_ADDRESS,
+    abi: ERC20_ABI,
+    functionName: "balanceOf",
+    args: [address],
+  });
+
+  console.log(
+    boxen(
+      [
+        `${chalk.dim("Token")}    ${USDC_ADDRESS}`,
+        `${chalk.dim("Address")}  ${address}`,
+        `${chalk.dim("Balance")}  ${chalk.green.bold(formatTokenAmount(balance, decimals))} USDC`,
+      ].join("\n"),
+      {
+        title: "USDC Balance",
+        padding: 1,
+        borderStyle: "round",
+        borderColor: "cyan",
+      },
+    ),
+  );
+}

package/src/commands/dev.ts

@@ -0,0 +1,112 @@
+import chalk from "chalk";
+import boxen from "boxen";
+import type { ChildProcess } from "child_process";
+import type { Server } from "http";
+import { startAnvil, waitForAnvil } from "../lib/anvil.js";
+import { startFacilitator } from "../lib/facilitator.js";
+import { fetchChainId } from "../lib/chain.js";
+import { accounts, defaults, networkId, USDC_ADDRESS } from "../lib/config.js";
+
+export interface DevOptions {
+  port: number;
+  anvilPort: number;
+  rpcUrl: string;
+}
+
+export async function devCommand(options: DevOptions): Promise<void> {
+  const localRpcUrl = `http://localhost:${options.anvilPort}`;
+  let anvilProc: ChildProcess | null = null;
+  let server: Server | null = null;
+
+  function cleanup() {
+    console.log("\nShutting down...");
+    let pending = 0;
+    const done = () => { if (--pending <= 0) process.exit(0); };
+
+    if (server) {
+      pending++;
+      server.close(() => done());
+      server = null;
+    }
+    if (anvilProc) {
+      pending++;
+      anvilProc.on("exit", () => done());
+      anvilProc.kill("SIGTERM");
+      anvilProc = null;
+    }
+    if (pending === 0) process.exit(0);
+
+    // Force exit after 3s if graceful shutdown hangs
+    setTimeout(() => process.exit(0), 3000).unref();
+  }
+
+  process.on("SIGINT", cleanup);
+  process.on("SIGTERM", cleanup);
+
+  // 0. Detect chain ID from fork RPC
+  console.log(chalk.dim(`Detecting chain ID from ${options.rpcUrl}...`));
+  const chainId = await fetchChainId(options.rpcUrl);
+  console.log(chalk.dim(`Detected chain ID: ${chainId}`));
+
+  // 1. Start Anvil
+  console.log(
+    chalk.dim(
+      `Starting Anvil (forking chain ${chainId}, port ${options.anvilPort})...`,
+    ),
+  );
+  anvilProc = startAnvil({
+    forkUrl: options.rpcUrl,
+    port: options.anvilPort,
+    chainId,
+  });
+
+  anvilProc.on("exit", (code) => {
+    if (code !== null && code !== 0) {
+      console.error(chalk.red(`Anvil exited with code ${code}`));
+      process.exit(1);
+    }
+  });
+
+  // 2. Wait for Anvil to be ready
+  console.log(chalk.dim("Waiting for Anvil to be ready..."));
+  await waitForAnvil(localRpcUrl);
+  console.log(chalk.dim("Anvil is ready."));
+
+  // 3. Start facilitator
+  console.log(chalk.dim(`Starting facilitator on port ${options.port}...`));
+  server = await startFacilitator({
+    port: options.port,
+    rpcUrl: localRpcUrl,
+    chainId,
+  });
+
+  const network = networkId(chainId);
+
+  // 4. Print summary
+  console.log(
+    boxen(
+      [
+        `${chalk.dim("Anvil RPC")}     ${chalk.cyan(localRpcUrl)}`,
+        `${chalk.dim("Facilitator")}   ${chalk.cyan(`http://localhost:${options.port}`)}`,
+        `${chalk.dim("Network")}       ${network}`,
+        `${chalk.dim("Chain ID")}      ${chainId}`,
+        "",
+        chalk.dim("Accounts"),
+        `  ${chalk.dim("Facilitator")}  ${accounts.facilitator.address}`,
+        "",
+        `${chalk.dim("USDC")}          ${USDC_ADDRESS}`,
+        "",
+        `${chalk.dim("Fund account with:")}`,
+        `$ ${chalk.white("x402-fl fund <address> <amount>")}`,
+        "",
+        chalk.dim("Press Ctrl+C to stop."),
+      ].join("\n"),
+      {
+        title: "x402-fl dev",
+        padding: 1,
+        borderStyle: "round",
+        borderColor: "green",
+      },
+    ),
+  );
+}