create-mantle-facilitator 0.1.0

package/dist/index.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import path from "path";
+import fs from "fs";
+import { fileURLToPath } from "url";
+import fse from "fs-extra";
+function log(msg) {
+  console.log(msg);
+}
+function fail(msg) {
+  console.error(msg);
+  process.exit(1);
+}
+function cleanName(name) {
+  return name.replace(/[^a-zA-Z0-9-_]/g, "");
+}
+async function main() {
+  const args = process.argv.slice(2);
+  const rawProjectName = args[0];
+  if (!rawProjectName) {
+    fail("Usage: create-mantle-facilitator <project-name>");
+  }
+  const projectName = cleanName(rawProjectName);
+  if (!projectName) {
+    fail("Invalid project name.");
+  }
+  const cwd = process.cwd();
+  const targetDir = path.join(cwd, projectName);
+  if (fs.existsSync(targetDir)) {
+    fail(`Target directory already exists: ${targetDir}`);
+  }
+  const templateDir = path.join(
+    path.dirname(fileURLToPath(import.meta.url)),
+    "..",
+    "template"
+  );
+  if (!fs.existsSync(templateDir)) {
+    fail("Template folder not found in CLI package.");
+  }
+  await fse.copy(templateDir, targetDir);
+  const pkgPath = path.join(targetDir, "package.json");
+  if (fs.existsSync(pkgPath)) {
+    const pkg = JSON.parse(await fse.readFile(pkgPath, "utf8"));
+    pkg.name = projectName;
+    if (pkg.private === true) delete pkg.private;
+    await fse.writeFile(pkgPath, JSON.stringify(pkg, null, 2), "utf8");
+  }
+  log("");
+  log("\u2705 Mantle facilitator scaffolded!");
+  log("");
+  log("Next steps:");
+  log(`  cd ${projectName}`);
+  log("  cp .env.example .env");
+  log("  npm install");
+  log("  npm run dev");
+  log("");
+}
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/dist/index.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import path from "path";
+import fs from "fs";
+import { fileURLToPath } from "url";
+import fse from "fs-extra";
+function log(msg) {
+  console.log(msg);
+}
+function fail(msg) {
+  console.error(msg);
+  process.exit(1);
+}
+function cleanName(name) {
+  return name.replace(/[^a-zA-Z0-9-_]/g, "");
+}
+async function main() {
+  const args = process.argv.slice(2);
+  const rawProjectName = args[0];
+  if (!rawProjectName) {
+    fail("Usage: create-mantle-facilitator <project-name>");
+  }
+  const projectName = cleanName(rawProjectName);
+  if (!projectName) {
+    fail("Invalid project name.");
+  }
+  const cwd = process.cwd();
+  const targetDir = path.join(cwd, projectName);
+  if (fs.existsSync(targetDir)) {
+    fail(`Target directory already exists: ${targetDir}`);
+  }
+  const templateDir = path.join(
+    path.dirname(fileURLToPath(import.meta.url)),
+    "..",
+    "template"
+  );
+  if (!fs.existsSync(templateDir)) {
+    fail("Template folder not found in CLI package.");
+  }
+  await fse.copy(templateDir, targetDir);
+  const pkgPath = path.join(targetDir, "package.json");
+  if (fs.existsSync(pkgPath)) {
+    const pkg = JSON.parse(await fse.readFile(pkgPath, "utf8"));
+    pkg.name = projectName;
+    if (pkg.private === true) delete pkg.private;
+    await fse.writeFile(pkgPath, JSON.stringify(pkg, null, 2), "utf8");
+  }
+  log("");
+  log("\u2705 Mantle facilitator scaffolded!");
+  log("");
+  log("Next steps:");
+  log(`  cd ${projectName}`);
+  log("  cp .env.example .env");
+  log("  npm install");
+  log("  npm run dev");
+  log("");
+}
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,28 @@
+
+{
+  "name": "create-mantle-facilitator",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "bin": {
+    "create-mantle-facilitator": "./dist/index.mjs"
+  },
+  "files": [
+    "dist",
+    "template"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "node dist/index.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "fs-extra": "^11.2.0"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.4",
+    "@types/node": "^22.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.6.0"
+  }
+}

package/template/.env.example

@@ -0,0 +1,17 @@
+# Server
+PORT=8080
+
+# Network
+NETWORK_ID=mantle-mainnet
+CHAIN_ID=5000
+RPC_URL=https://rpc.mantle.xyz
+
+# Asset (USDC on Mantle)
+USDC_ADDRESS=0x09Bc4E0D864854c6aFB6eB9A9cdF58aC190D0dF9
+USDC_DECIMALS=6
+
+# Facilitator signer (pays gas for transferWithAuthorization)
+FACILITATOR_PRIVATE_KEY=0xYOUR_PRIVATE_KEY
+
+# Optional: enable verbose logs
+LOG_LEVEL=debug

package/template/README.md

@@ -0,0 +1,25 @@
+# Mantle x402 Facilitator (Self-hosted Template)
+
+A minimal, self-hosted x402 facilitator for **Mantle mainnet** using **USDC (EIP-3009)**.
+
+This facilitator:
+- verifies x402 payment headers
+- settles payments on-chain via `transferWithAuthorization`
+- pays gas from the facilitator wallet
+
+## Endpoints
+
+- `GET /health`
+- `GET /supported`
+- `POST /verify`
+- `POST /settle`
+
+## Quickstart
+
+```bash
+git clone <this-repo>
+cd mantle-x402-facilitator-template
+npm install
+cp .env.example .env
+# Fill RPC_URL and FACILITATOR_PRIVATE_KEY
+npm start

package/template/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "create-mantle-facilitator-template",
+  "version": "0.1.0",
+  "type": "module",
+  "private": true,
+  "description": "Self-hosted x402 facilitator template for Mantle + USDC (TypeScript)",
+  "license": "MIT",
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "build": "tsup src/index.ts --format esm --dts false",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "dotenv": "^16.4.5",
+    "ethers": "^6.16.0",
+    "express": "^5.2.1"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/node": "^22.0.0",
+    "tsup": "^8.0.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.6.0"
+  }
+}

package/template/src/blockchain.ts

@@ -0,0 +1,29 @@
+// src/blockchain.ts
+import { ethers } from "ethers";
+import { CONFIG } from "./config";
+
+// Minimal ABI for USDC EIP-3009
+const USDC_EIP3009_ABI = [
+  "function transferWithAuthorization(address from,address to,uint256 value,uint256 validAfter,uint256 validBefore,bytes32 nonce,uint8 v,bytes32 r,bytes32 s) external",
+  "function balanceOf(address account) view returns (uint256)",
+];
+
+export function getProvider(): ethers.JsonRpcProvider {
+  return new ethers.JsonRpcProvider(CONFIG.rpcUrl, CONFIG.chainId);
+}
+
+export function getFacilitatorSigner(): ethers.Wallet {
+  const provider = getProvider();
+  return new ethers.Wallet(CONFIG.facilitatorPrivateKey, provider);
+}
+
+export function getUsdcContract(
+  signerOrProvider: ethers.ContractRunner
+): ethers.Contract {
+  return new ethers.Contract(CONFIG.usdcAddress, USDC_EIP3009_ABI, signerOrProvider);
+}
+
+export async function getMntBalance(address: string): Promise<bigint> {
+  const provider = getProvider();
+  return provider.getBalance(address);
+}

package/template/src/config.ts

@@ -0,0 +1,23 @@
+// src/config.ts
+import "dotenv/config";
+
+function required(name: string): string {
+  const v = process.env[name];
+  if (!v) throw new Error(`Missing env var: ${name}`);
+  return v;
+}
+
+export const CONFIG = {
+  port: Number(process.env.PORT ?? 8080),
+
+  networkId: process.env.NETWORK_ID ?? "mantle-mainnet",
+  chainId: Number(process.env.CHAIN_ID ?? 5000),
+  rpcUrl: required("RPC_URL"),
+
+  usdcAddress: required("USDC_ADDRESS"),
+  usdcDecimals: Number(process.env.USDC_DECIMALS ?? 6),
+
+  facilitatorPrivateKey: required("FACILITATOR_PRIVATE_KEY"),
+
+  logLevel: process.env.LOG_LEVEL ?? "info",
+} as const;

package/template/src/index.ts

@@ -0,0 +1,21 @@
+// src/index.ts
+import express from "express";
+import { CONFIG } from "./config";
+
+import { healthRoute } from "./routes/health";
+import { supportedRoute } from "./routes/supported";
+import { verifyRoute } from "./routes/verify";
+import { settleRoute } from "./routes/settle";
+
+const app = express();
+app.use(express.json({ limit: "1mb" }));
+
+app.get("/health", healthRoute);
+app.get("/supported", supportedRoute);
+app.post("/verify", verifyRoute);
+app.post("/settle", settleRoute);
+
+app.listen(CONFIG.port, () => {
+  console.log(`Facilitator server listening on http://localhost:${CONFIG.port}`);
+  console.log(`Network: ${CONFIG.networkId} (chainId=${CONFIG.chainId})`);
+});

package/template/src/routes/health.ts

@@ -0,0 +1,33 @@
+// src/routes/health.ts
+import type { Request, Response } from "express";
+import { ethers } from "ethers";
+import { CONFIG } from "../config";
+import { getFacilitatorSigner, getMntBalance } from "../blockchain";
+
+export async function healthRoute(_req: Request, res: Response) {
+  try {
+    const signer = getFacilitatorSigner();
+    const provider = signer.provider;
+
+    if (!provider) {
+      res.status(500).json({ ok: false, error: "No provider available" });
+      return;
+    }
+
+    const currentBlock = await provider.getBlockNumber();
+    const mntBalanceWei = await getMntBalance(signer.address);
+
+    res.status(200).json({
+      ok: true,
+      network: CONFIG.networkId,
+      chainId: CONFIG.chainId,
+      facilitatorAddress: signer.address,
+      currentBlock,
+      mntBalanceWei: mntBalanceWei.toString(),
+      mntBalance: ethers.formatEther(mntBalanceWei),
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : "Unknown error";
+    res.status(500).json({ ok: false, error: msg });
+  }
+}

package/template/src/routes/settle.ts

@@ -0,0 +1,89 @@
+// src/routes/settle.ts
+import type { Request, Response } from "express";
+import { ethers } from "ethers";
+import { decodePaymentHeader, verifyPayment, type PaymentRequirements } from "../x402";
+import { getFacilitatorSigner, getUsdcContract } from "../blockchain";
+
+function signatureToVRS(signature: string) {
+  const sig = ethers.Signature.from(signature);
+  return { v: sig.v, r: sig.r, s: sig.s };
+}
+
+/** Send transferWithAuthorization on-chain using facilitator gas. */
+export async function settleRoute(req: Request, res: Response) {
+  const raw = req.body ?? {};
+
+  try {
+    const { x402Version, paymentHeader, paymentRequirements } = raw as {
+      x402Version?: number;
+      paymentHeader?: string;
+      paymentRequirements?: PaymentRequirements;
+    };
+
+    if (x402Version !== 1) {
+      res.status(400).json({
+        success: false,
+        error: "Unsupported x402Version",
+        txHash: null,
+        networkId: paymentRequirements?.network,
+      });
+      return;
+    }
+
+    if (!paymentHeader || !paymentRequirements) {
+      res.status(400).json({
+        success: false,
+        error: "Missing paymentHeader or paymentRequirements",
+        txHash: null,
+        networkId: paymentRequirements?.network,
+      });
+      return;
+    }
+
+    const headerObj = decodePaymentHeader(paymentHeader);
+    const verify = verifyPayment(headerObj, paymentRequirements);
+
+    if (!verify.isValid) {
+      res.status(400).json({
+        success: false,
+        error: verify.invalidReason ?? "Invalid payment",
+        txHash: null,
+        networkId: paymentRequirements.network,
+      });
+      return;
+    }
+
+    const { authorization, signature } = headerObj.payload;
+    const { v, r, s } = signatureToVRS(signature);
+
+    const signer = getFacilitatorSigner();
+    const usdc = getUsdcContract(signer);
+
+    const tx = await usdc.transferWithAuthorization(
+      authorization.from,
+      authorization.to,
+      authorization.value,
+      authorization.validAfter,
+      authorization.validBefore,
+      authorization.nonce,
+      v, r, s
+    );
+
+    const receipt = await tx.wait();
+
+    res.status(200).json({
+      success: true,
+      error: null,
+      txHash: receipt?.hash ?? tx.hash,
+      networkId: paymentRequirements.network,
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : "Unknown error";
+    res.status(500).json({
+      success: false,
+      error: msg,
+      txHash: null,
+      networkId: (raw as { paymentRequirements?: { network?: string } })?.paymentRequirements?.network,
+    });
+  }
+}

package/template/src/routes/supported.ts

@@ -0,0 +1,18 @@
+// src/routes/supported.ts
+import type { Request, Response } from "express";
+import { CONFIG } from "../config";
+
+export function supportedRoute(_req: Request, res: Response) {
+  res.status(200).json({
+    networkId: CONFIG.networkId,
+    chainId: CONFIG.chainId,
+    schemes: ["exact"],
+    assets: [
+      {
+        symbol: "USDC",
+        address: CONFIG.usdcAddress,
+        decimals: CONFIG.usdcDecimals,
+      },
+    ],
+  });
+}

package/template/src/routes/verify.ts

@@ -0,0 +1,27 @@
+// src/routes/verify.ts
+import type { Request, Response } from "express";
+import { decodePaymentHeader, verifyPayment, type PaymentRequirements } from "../x402";
+
+export async function verifyRoute(req: Request, res: Response) {
+  try {
+    const { x402Version, paymentHeader, paymentRequirements } = req.body ?? {};
+
+    if (x402Version !== 1) {
+      res.status(400).json({ isValid: false, invalidReason: "Unsupported x402Version" });
+      return;
+    }
+
+    if (!paymentHeader || !paymentRequirements) {
+      res.status(400).json({ isValid: false, invalidReason: "Missing paymentHeader or paymentRequirements" });
+      return;
+    }
+
+    const headerObj = decodePaymentHeader(paymentHeader as string);
+    const result = verifyPayment(headerObj, paymentRequirements as PaymentRequirements);
+
+    res.status(200).json(result);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : "Unknown error";
+    res.status(500).json({ isValid: false, invalidReason: msg });
+  }
+}

package/template/src/x402.ts

@@ -0,0 +1,147 @@
+// src/x402.ts
+import { ethers } from "ethers";
+import { CONFIG } from "./config";
+
+/** Payment requirements expected by facilitator endpoints. */
+export interface PaymentRequirements {
+  scheme: "exact";
+  network: string;
+  asset: string;
+  maxAmountRequired: string;
+  payTo: string;
+  price?: string;
+  currency?: string;
+}
+
+/** EIP-3009 authorization payload. */
+export interface Authorization {
+  from: string;
+  to: string;
+  value: string;
+  validAfter: string;
+  validBefore: string;
+  nonce: string;
+}
+
+/** x402 header object structure before base64 encoding. */
+export interface PaymentHeaderObject {
+  x402Version: number;
+  scheme: "exact";
+  network: string;
+  payload: {
+    signature: string;
+    authorization: Authorization;
+  };
+}
+
+/** Decode base64 payment header into JSON object. */
+export function decodePaymentHeader(paymentHeader: string): PaymentHeaderObject {
+  try {
+    const json = Buffer.from(paymentHeader, "base64").toString("utf8");
+    return JSON.parse(json) as PaymentHeaderObject;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : "Unknown error";
+    throw new Error(`Failed to decode paymentHeader: ${msg}`);
+  }
+}
+
+/** Basic structural validation of header. */
+export function validateHeaderShape(headerObj: PaymentHeaderObject) {
+  if (!headerObj || typeof headerObj !== "object") {
+    return { ok: false, reason: "Header is not an object" as const };
+  }
+  if (headerObj.x402Version !== 1) {
+    return { ok: false, reason: "Unsupported x402Version" as const };
+  }
+  if (headerObj.scheme !== "exact") {
+    return { ok: false, reason: "Unsupported scheme" as const };
+  }
+  if (!headerObj.network) {
+    return { ok: false, reason: "Missing network" as const };
+  }
+  if (!headerObj.payload?.authorization || !headerObj.payload?.signature) {
+    return { ok: false, reason: "Missing payload.authorization or payload.signature" as const };
+  }
+  return { ok: true as const };
+}
+
+/** Build EIP-712 domain/types for USDC TransferWithAuthorization. */
+export function getUsdcTypedData(authorization: Authorization) {
+  const domain = {
+    name: "USD Coin",
+    version: "2",
+    chainId: CONFIG.chainId,
+    verifyingContract: CONFIG.usdcAddress,
+  };
+
+  const types = {
+    TransferWithAuthorization: [
+      { name: "from", type: "address" },
+      { name: "to", type: "address" },
+      { name: "value", type: "uint256" },
+      { name: "validAfter", type: "uint256" },
+      { name: "validBefore", type: "uint256" },
+      { name: "nonce", type: "bytes32" },
+    ],
+  };
+
+  return { domain, types, primaryType: "TransferWithAuthorization", message: authorization };
+}
+
+/** Verify that header signature matches authorization.from. */
+export function verifyAuthorizationSignature(
+  authorization: Authorization,
+  signature: string
+): string {
+  const { domain, types, message } = getUsdcTypedData(authorization);
+  return ethers.verifyTypedData(domain, types, message, signature);
+}
+
+/**
+ * Verify payment header against paymentRequirements.
+ * This checks:
+ * - network/scheme
+ * - authorization.to/value equals requirements fields
+ * - EIP-712 signature is valid
+ */
+export function verifyPayment(
+  headerObj: PaymentHeaderObject,
+  paymentRequirements: PaymentRequirements
+): { isValid: boolean; invalidReason: string | null } {
+  const shape = validateHeaderShape(headerObj);
+  if (!shape.ok) return { isValid: false, invalidReason: shape.reason };
+
+  const { authorization, signature } = headerObj.payload;
+
+  if (headerObj.network !== paymentRequirements.network) {
+    return { isValid: false, invalidReason: "Network mismatch" };
+  }
+
+  if (paymentRequirements.scheme !== "exact") {
+    return { isValid: false, invalidReason: "Only exact scheme supported" };
+  }
+
+  if (authorization.to.toLowerCase() !== paymentRequirements.payTo.toLowerCase()) {
+    return { isValid: false, invalidReason: "Authorization.to does not match payTo" };
+  }
+
+  const authValue = BigInt(authorization.value);
+  const maxValue = BigInt(paymentRequirements.maxAmountRequired);
+
+  // In our current exact mode we keep strict equality (same as your working stack)
+  if (authValue !== maxValue) {
+    return { isValid: false, invalidReason: "Authorization.value does not match maxAmountRequired" };
+  }
+
+  try {
+    const recovered = verifyAuthorizationSignature(authorization, signature);
+    if (recovered.toLowerCase() !== authorization.from.toLowerCase()) {
+      return { isValid: false, invalidReason: "Signature does not match authorization.from" };
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : "Unknown error";
+    return { isValid: false, invalidReason: `Signature verification failed: ${msg}` };
+  }
+
+  return { isValid: true, invalidReason: null };
+}

package/template/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "Node",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src"]
+}