create-mantle-facilitator 0.4.0 → 0.4.1

package/README.md

@@ -62,16 +62,17 @@ Add `FACILITATOR_SECRET` to your backend and configure the SDK:
 ```typescript
 import { mantlePaywall } from '@puga-labs/x402-mantle-sdk/server/express';
 
+// Self-hosted facilitator (requires facilitatorUrl + facilitatorSecret)
 const pay = mantlePaywall({
   priceUsd: 0.01,
   payTo: '0xYourWallet',
-  facilitatorUrl: 'https://your-facilitator.com',
-  facilitatorSecret: process.env.FACILITATOR_SECRET, // Same secret as in facilitator
-  projectKey: process.env.PROJECT_KEY, // Optional: from dashboard for analytics
+  facilitatorUrl: 'https://your-facilitator.com', // Required for self-hosted
+  facilitatorSecret: process.env.FACILITATOR_SECRET!, // Required for self-hosted
+  // projectKey: process.env.PROJECT_KEY, // Optional: for analytics
 });
 ```
 
-**Note:** The `facilitatorUrl` is automatically passed to clients via 402 responses, so frontend code doesn't need to configure it.
+**Note:** When using `facilitatorSecret` (self-hosted mode), `facilitatorUrl` is required. The URL is automatically passed to clients via 402 responses, so frontend code doesn't need to configure it.
 
 ## Running Locally
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-mantle-facilitator",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "private": false,
   "type": "module",
   "bin": {

package/template/README.md

@@ -53,16 +53,17 @@ This prevents third parties from using your facilitator to settle their payments
 ```typescript
 import { mantlePaywall } from '@puga-labs/x402-mantle-sdk/server/express';
 
+// Self-hosted facilitator (requires facilitatorUrl + facilitatorSecret)
 const pay = mantlePaywall({
   priceUsd: 0.01,
   payTo: '0xYourWallet',
-  facilitatorUrl: 'https://your-facilitator.com',
-  facilitatorSecret: process.env.FACILITATOR_SECRET, // Same as in facilitator .env
-  projectKey: process.env.PROJECT_KEY, // Optional: for analytics
+  facilitatorUrl: 'https://your-facilitator.com', // Required for self-hosted
+  facilitatorSecret: process.env.FACILITATOR_SECRET!, // Required for self-hosted
+  // projectKey: process.env.PROJECT_KEY, // Optional: for analytics
 });
 ```
 
-**Note:** The `facilitatorUrl` is automatically passed to clients via 402 responses.
+**Note:** When using `facilitatorSecret`, `facilitatorUrl` is required. The URL is automatically passed to clients via 402 responses.
 
 ## Endpoints
 

package/template/src/config.ts

@@ -1,27 +1,136 @@
 // src/config.ts
 import "dotenv/config";
+import { ethers } from "ethers";
 import { DEFAULT_TELEMETRY_ENDPOINT } from "./constants";
 
-function required(name: string): string {
-  const v = process.env[name];
-  if (!v) throw new Error(`Missing env var: ${name}`);
-  return v;
+// ============================================
+// Validation types and helpers
+// ============================================
+
+interface ConfigError {
+  field: string;
+  message: string;
+  howToFix: string[];
+}
+
+function validateConfig(): ConfigError[] {
+  const errors: ConfigError[] = [];
+
+  // Required: FACILITATOR_PRIVATE_KEY
+  const privateKey = process.env.FACILITATOR_PRIVATE_KEY;
+  if (!privateKey) {
+    errors.push({
+      field: "FACILITATOR_PRIVATE_KEY",
+      message: "This is the wallet that will pay gas fees for settlements.",
+      howToFix: [
+        "Open .env file",
+        "Set FACILITATOR_PRIVATE_KEY=0xYourPrivateKey",
+        "Need a wallet? Create one at https://metamask.io",
+        "Make sure it has MNT for gas fees.",
+      ],
+    });
+  } else if (!privateKey.startsWith("0x") || privateKey.length !== 66) {
+    errors.push({
+      field: "FACILITATOR_PRIVATE_KEY",
+      message: "Invalid private key format.",
+      howToFix: [
+        "Private key must start with 0x",
+        "Private key must be 66 characters (0x + 64 hex digits)",
+        `Current length: ${privateKey.length} characters`,
+      ],
+    });
+  }
+
+  // Required: FACILITATOR_SECRET
+  const secret = process.env.FACILITATOR_SECRET;
+  if (!secret) {
+    errors.push({
+      field: "FACILITATOR_SECRET",
+      message: "This secret authenticates your backend with the facilitator.",
+      howToFix: [
+        "Open .env file",
+        "Set FACILITATOR_SECRET=fac_YOUR_SECRET_HERE",
+        "Then copy this value to your backend's facilitatorSecret config",
+      ],
+    });
+  }
+
+  // Required: RPC_URL
+  if (!process.env.RPC_URL) {
+    errors.push({
+      field: "RPC_URL",
+      message: "RPC URL for connecting to Mantle network.",
+      howToFix: [
+        "Open .env file",
+        "Set RPC_URL=https://rpc.mantle.xyz",
+      ],
+    });
+  }
+
+  // Required: USDC_ADDRESS
+  if (!process.env.USDC_ADDRESS) {
+    errors.push({
+      field: "USDC_ADDRESS",
+      message: "USDC contract address on Mantle.",
+      howToFix: [
+        "Open .env file",
+        "Set USDC_ADDRESS=0x09Bc4E0D864854c6aFB6eB9A9cdF58aC190D0dF9",
+      ],
+    });
+  }
+
+  return errors;
 }
 
+function printConfigErrors(errors: ConfigError[]): void {
+  console.error("");
+  console.error("CONFIGURATION ERROR");
+  console.error("=".repeat(50));
+
+  for (const error of errors) {
+    console.error("");
+    console.error(`Missing: ${error.field}`);
+    console.error(`${error.message}`);
+    console.error("");
+    console.error("To fix:");
+    error.howToFix.forEach((step, i) => {
+      console.error(`  ${i + 1}. ${step}`);
+    });
+  }
+
+  console.error("");
+  console.error("=".repeat(50));
+  console.error("");
+}
+
+// ============================================
+// Run validation at startup
+// ============================================
+
+const configErrors = validateConfig();
+if (configErrors.length > 0) {
+  printConfigErrors(configErrors);
+  process.exit(1);
+}
+
+// ============================================
+// Build config (all required fields are validated)
+// ============================================
+
 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"),
+  rpcUrl: process.env.RPC_URL!,
 
-  usdcAddress: required("USDC_ADDRESS"),
+  usdcAddress: process.env.USDC_ADDRESS!,
   usdcDecimals: Number(process.env.USDC_DECIMALS ?? 6),
 
-  facilitatorPrivateKey: required("FACILITATOR_PRIVATE_KEY"),
+  facilitatorPrivateKey: process.env.FACILITATOR_PRIVATE_KEY!,
 
   // Secret for settle token verification (required for security)
-  facilitatorSecret: required("FACILITATOR_SECRET"),
+  facilitatorSecret: process.env.FACILITATOR_SECRET!,
 
   logLevel: process.env.LOG_LEVEL ?? "info",
 
@@ -33,3 +142,12 @@ export const CONFIG = {
       }
     : undefined,
 } as const;
+
+// ============================================
+// Derive facilitator address from private key
+// ============================================
+
+export function getFacilitatorAddress(): string {
+  const wallet = new ethers.Wallet(CONFIG.facilitatorPrivateKey);
+  return wallet.address;
+}

package/template/src/index.ts

@@ -1,7 +1,7 @@
 // src/index.ts
 import express from "express";
 import cors from "cors";
-import { CONFIG } from "./config";
+import { CONFIG, getFacilitatorAddress } from "./config";
 
 import { healthRoute } from "./routes/health";
 import { supportedRoute } from "./routes/supported";
@@ -25,7 +25,36 @@ app.get("/supported", supportedRoute);
 app.post("/verify", verifyRoute);
 app.post("/settle", settleRoute);
 
+// ============================================
+// Startup banner
+// ============================================
+
+function printStartupBanner(): void {
+  const address = getFacilitatorAddress();
+  const shortAddress = `${address.slice(0, 6)}...${address.slice(-4)}`;
+  const telemetryStatus = CONFIG.telemetry ? "enabled" : "disabled";
+
+  console.log("");
+  console.log("+".padEnd(50, "-") + "+");
+  console.log("|  Mantle x402 Facilitator".padEnd(50) + "|");
+  console.log("+".padEnd(50, "-") + "+");
+  console.log(`|  Network:     ${CONFIG.networkId} (${CONFIG.chainId})`.padEnd(50) + "|");
+  console.log(`|  Address:     ${shortAddress}`.padEnd(50) + "|");
+  console.log(`|  Port:        ${CONFIG.port}`.padEnd(50) + "|");
+  console.log(`|  Telemetry:   ${telemetryStatus}`.padEnd(50) + "|");
+  console.log("+".padEnd(50, "-") + "+");
+  console.log("");
+
+  // Telemetry warning
+  if (!CONFIG.telemetry) {
+    console.log("Note: Telemetry is disabled.");
+    console.log("  To enable analytics, set TELEMETRY_PROJECT_KEY in .env");
+    console.log("  Get your key at https://x402mantlesdk.xyz/dashboard");
+    console.log("");
+  }
+}
+
 app.listen(CONFIG.port, () => {
-  console.log(`Facilitator server listening on http://localhost:${CONFIG.port}`);
-  console.log(`Network: ${CONFIG.networkId} (chainId=${CONFIG.chainId})`);
+  printStartupBanner();
+  console.log(`Server listening on http://localhost:${CONFIG.port}`);
 });