create-mantle-facilitator 0.1.0 → 0.2.1

package/package.json

@@ -1,7 +1,6 @@
-
 {
   "name": "create-mantle-facilitator",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "private": false,
   "type": "module",
   "bin": {

package/template/.env.example

@@ -15,3 +15,11 @@ FACILITATOR_PRIVATE_KEY=0xYOUR_PRIVATE_KEY
 
 # Optional: enable verbose logs
 LOG_LEVEL=debug
+
+# =============================================================================
+# Optional: Analytics & Telemetry
+# =============================================================================
+# Uncomment to send usage metrics to analytics backend
+# This helps improve the x402 ecosystem and provides you with payment analytics
+
+# TELEMETRY_PROJECT_KEY=your_project_key_here

package/template/README.md

@@ -23,3 +23,28 @@ npm install
 cp .env.example .env
 # Fill RPC_URL and FACILITATOR_PRIVATE_KEY
 npm start
+```
+
+## Optional: Analytics & Telemetry
+
+To enable opt-in telemetry for payment tracking and analytics:
+
+1. Get your project key from https://nosubs.ai/dashboard (or your analytics platform)
+2. Add to `.env`:
+   ```bash
+   TELEMETRY_PROJECT_KEY=proj_abc123xyz
+   ```
+
+**Note:** Telemetry is sent automatically to the official analytics backend. If you don't want to send telemetry, simply don't set `TELEMETRY_PROJECT_KEY`.
+
+**What data is sent:**
+- Payment metadata (buyer address, amount, asset, network)
+- Transaction hash (after settlement)
+- Timestamp
+
+**What is NOT sent:**
+- Private keys
+- User personal information
+- Request/response payloads from your protected endpoints
+
+Telemetry errors never break payment processing - if the analytics backend is down, payments continue to work normally.

package/template/dist/index.mjs

@@ -0,0 +1,324 @@
+// src/index.ts
+import express from "express";
+
+// src/config.ts
+import "dotenv/config";
+
+// src/constants.ts
+var DEFAULT_TELEMETRY_ENDPOINT = void 0;
+
+// src/config.ts
+function required(name) {
+  const v = process.env[name];
+  if (!v) throw new Error(`Missing env var: ${name}`);
+  return v;
+}
+var CONFIG = {
+  port: Number(process.env.PORT ?? 8080),
+  networkId: process.env.NETWORK_ID ?? "mantle-mainnet",
+  chainId: Number(process.env.CHAIN_ID ?? 5e3),
+  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",
+  // Telemetry config (opt-in via projectKey)
+  telemetry: process.env.TELEMETRY_PROJECT_KEY ? {
+    projectKey: process.env.TELEMETRY_PROJECT_KEY,
+    endpoint: DEFAULT_TELEMETRY_ENDPOINT
+  } : void 0
+};
+
+// src/routes/health.ts
+import { ethers as ethers2 } from "ethers";
+
+// src/blockchain.ts
+import { ethers } from "ethers";
+var 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)"
+];
+function getProvider() {
+  return new ethers.JsonRpcProvider(CONFIG.rpcUrl, CONFIG.chainId);
+}
+function getFacilitatorSigner() {
+  const provider = getProvider();
+  return new ethers.Wallet(CONFIG.facilitatorPrivateKey, provider);
+}
+function getUsdcContract(signerOrProvider) {
+  return new ethers.Contract(CONFIG.usdcAddress, USDC_EIP3009_ABI, signerOrProvider);
+}
+async function getMntBalance(address) {
+  const provider = getProvider();
+  return provider.getBalance(address);
+}
+
+// src/routes/health.ts
+async function healthRoute(_req, res) {
+  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: ethers2.formatEther(mntBalanceWei)
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : "Unknown error";
+    res.status(500).json({ ok: false, error: msg });
+  }
+}
+
+// src/routes/supported.ts
+function supportedRoute(_req, res) {
+  res.status(200).json({
+    networkId: CONFIG.networkId,
+    chainId: CONFIG.chainId,
+    schemes: ["exact"],
+    assets: [
+      {
+        symbol: "USDC",
+        address: CONFIG.usdcAddress,
+        decimals: CONFIG.usdcDecimals
+      }
+    ]
+  });
+}
+
+// src/x402.ts
+import { ethers as ethers3 } from "ethers";
+function decodePaymentHeader(paymentHeader) {
+  try {
+    const json = Buffer.from(paymentHeader, "base64").toString("utf8");
+    return JSON.parse(json);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : "Unknown error";
+    throw new Error(`Failed to decode paymentHeader: ${msg}`);
+  }
+}
+function validateHeaderShape(headerObj) {
+  if (!headerObj || typeof headerObj !== "object") {
+    return { ok: false, reason: "Header is not an object" };
+  }
+  if (headerObj.x402Version !== 1) {
+    return { ok: false, reason: "Unsupported x402Version" };
+  }
+  if (headerObj.scheme !== "exact") {
+    return { ok: false, reason: "Unsupported scheme" };
+  }
+  if (!headerObj.network) {
+    return { ok: false, reason: "Missing network" };
+  }
+  if (!headerObj.payload?.authorization || !headerObj.payload?.signature) {
+    return { ok: false, reason: "Missing payload.authorization or payload.signature" };
+  }
+  return { ok: true };
+}
+function getUsdcTypedData(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 };
+}
+function verifyAuthorizationSignature(authorization, signature) {
+  const { domain, types, message } = getUsdcTypedData(authorization);
+  return ethers3.verifyTypedData(domain, types, message, signature);
+}
+function verifyPayment(headerObj, paymentRequirements) {
+  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);
+  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 };
+}
+
+// src/routes/verify.ts
+async function verifyRoute(req, res) {
+  try {
+    const { x402Version, paymentHeader, paymentRequirements } = req.body ?? {};
+    const projectKey = req.header("X-Project-Key");
+    if (projectKey) {
+      console.log(`[billing] Verify request from project: ${projectKey}`);
+    }
+    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);
+    const result = verifyPayment(headerObj, 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 });
+  }
+}
+
+// src/routes/settle.ts
+import { ethers as ethers4 } from "ethers";
+function signatureToVRS(signature) {
+  const sig = ethers4.Signature.from(signature);
+  return { v: sig.v, r: sig.r, s: sig.s };
+}
+async function settleRoute(req, res) {
+  const raw = req.body ?? {};
+  try {
+    const { x402Version, paymentHeader, paymentRequirements } = raw;
+    const projectKey = req.header("X-Project-Key");
+    if (projectKey) {
+      console.log(`[billing] Settle request from project: ${projectKey}`);
+    }
+    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();
+    if (CONFIG.telemetry && CONFIG.telemetry.endpoint) {
+      const telemetryEvent = {
+        event: "payment_settled",
+        ts: Date.now(),
+        projectKey: CONFIG.telemetry.projectKey,
+        network: paymentRequirements.network,
+        buyer: authorization.from,
+        payTo: authorization.to,
+        amountAtomic: authorization.value,
+        asset: CONFIG.usdcAddress,
+        decimals: CONFIG.usdcDecimals,
+        nonce: authorization.nonce,
+        route: "facilitator_settle",
+        // Facilitator doesn't know original route
+        // Facilitator metadata
+        facilitatorType: "self-hosted",
+        facilitatorUrl: void 0,
+        // Facilitator doesn't have URL to itself
+        facilitatorAddress: signer.address,
+        // Get from signer (line 66)
+        // Optional metadata
+        txHash: receipt?.hash ?? tx.hash,
+        priceUsd: paymentRequirements.price
+      };
+      fetch(CONFIG.telemetry.endpoint, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Authorization": `Bearer ${CONFIG.telemetry.projectKey}`
+        },
+        body: JSON.stringify(telemetryEvent)
+      }).catch((err) => console.error("[telemetry] Send failed:", err));
+    }
+    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?.paymentRequirements?.network
+    });
+  }
+}
+
+// src/index.ts
+var 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/config.ts

@@ -1,5 +1,6 @@
 // src/config.ts
 import "dotenv/config";
+import { DEFAULT_TELEMETRY_ENDPOINT } from "./constants";
 
 function required(name: string): string {
   const v = process.env[name];
@@ -20,4 +21,12 @@ export const CONFIG = {
   facilitatorPrivateKey: required("FACILITATOR_PRIVATE_KEY"),
 
   logLevel: process.env.LOG_LEVEL ?? "info",
+
+  // Telemetry config (opt-in via projectKey)
+  telemetry: process.env.TELEMETRY_PROJECT_KEY
+    ? {
+        projectKey: process.env.TELEMETRY_PROJECT_KEY,
+        endpoint: DEFAULT_TELEMETRY_ENDPOINT,
+      }
+    : undefined,
 } as const;

package/template/src/constants.ts

@@ -0,0 +1,9 @@
+// src/constants.ts
+
+/**
+ * Default telemetry endpoint URL.
+ *
+ * Set to a valid URL when the official analytics backend is ready.
+ * If undefined, telemetry will only be sent if TELEMETRY_ENDPOINT env var is set.
+ */
+export const DEFAULT_TELEMETRY_ENDPOINT: string | undefined = undefined;

package/template/src/routes/settle.ts

@@ -3,6 +3,7 @@ import type { Request, Response } from "express";
 import { ethers } from "ethers";
 import { decodePaymentHeader, verifyPayment, type PaymentRequirements } from "../x402";
 import { getFacilitatorSigner, getUsdcContract } from "../blockchain";
+import { CONFIG } from "../config";
 
 function signatureToVRS(signature: string) {
   const sig = ethers.Signature.from(signature);
@@ -19,6 +20,12 @@ export async function settleRoute(req: Request, res: Response) {
       paymentHeader?: string;
       paymentRequirements?: PaymentRequirements;
     };
+    const projectKey = req.header("X-Project-Key"); // Optional: for hosted facilitator billing
+
+    // Optional: Log for billing/attribution (useful for hosted facilitators)
+    if (projectKey) {
+      console.log(`[billing] Settle request from project: ${projectKey}`);
+    }
 
     if (x402Version !== 1) {
       res.status(400).json({
@@ -71,6 +78,44 @@ export async function settleRoute(req: Request, res: Response) {
 
     const receipt = await tx.wait();
 
+    // Send telemetry if configured and endpoint is available
+    if (CONFIG.telemetry && CONFIG.telemetry.endpoint) {
+      // NOTE: This event structure matches TelemetryEvent from x402-mantle-sdk
+      // See: packages/x402-mantle-sdk/src/server/types.ts
+      const telemetryEvent = {
+        event: "payment_settled" as const,
+        ts: Date.now(),
+        projectKey: CONFIG.telemetry.projectKey,
+        network: paymentRequirements.network,
+        buyer: authorization.from,
+        payTo: authorization.to,
+        amountAtomic: authorization.value,
+        asset: CONFIG.usdcAddress,
+        decimals: CONFIG.usdcDecimals,
+        nonce: authorization.nonce,
+        route: "facilitator_settle", // Facilitator doesn't know original route
+
+        // Facilitator metadata
+        facilitatorType: "self-hosted" as const,
+        facilitatorUrl: undefined,              // Facilitator doesn't have URL to itself
+        facilitatorAddress: signer.address,     // Get from signer (line 66)
+
+        // Optional metadata
+        txHash: receipt?.hash ?? tx.hash,
+        priceUsd: paymentRequirements.price,
+      };
+
+      // Fire-and-forget (don't await - don't delay response)
+      fetch(CONFIG.telemetry.endpoint, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Authorization": `Bearer ${CONFIG.telemetry.projectKey}`,
+        },
+        body: JSON.stringify(telemetryEvent),
+      }).catch(err => console.error("[telemetry] Send failed:", err));
+    }
+
     res.status(200).json({
       success: true,
       error: null,

package/template/src/routes/verify.ts

@@ -5,6 +5,12 @@ import { decodePaymentHeader, verifyPayment, type PaymentRequirements } from "..
 export async function verifyRoute(req: Request, res: Response) {
   try {
     const { x402Version, paymentHeader, paymentRequirements } = req.body ?? {};
+    const projectKey = req.header("X-Project-Key"); // Optional: for hosted facilitator billing
+
+    // Optional: Log for billing/attribution (useful for hosted facilitators)
+    if (projectKey) {
+      console.log(`[billing] Verify request from project: ${projectKey}`);
+    }
 
     if (x402Version !== 1) {
       res.status(400).json({ isValid: false, invalidReason: "Unsupported x402Version" });