create-mantle-facilitator 0.3.1 → 0.3.4

package/ascii-art.txt

@@ -0,0 +1,11 @@
+   _____      ______      __               __           __
+  / ___/___  / / __/     / /_  ____  _____/ /____  ____/ /
+  \__ \/ _ \/ / /_______/ __ \/ __ \/ ___/ __/ _ \/ __  /
+ ___/ /  __/ / __/_____/ / / / /_/ (__  ) /_/  __/ /_/ /
+/____/\___/_/_/       /_/ /_/\____/____/\__/\___/\__,_/
+    __  ___            __  __        ____           _ ___ __        __
+   /  |/  /___ _____  / /_/ /__     / __/___ ______(_) (_) /_____ _/ /_____  _____
+  / /|_/ / __ `/ __ \/ __/ / _ \   / /_/ __ `/ ___/ / / / __/ __ `/ __/ __ \/ ___/
+ / /  / / /_/ / / / / /_/ /  __/  / __/ /_/ / /__/ / / / /_/ /_/ / /_/ /_/ / /
+/_/  /_/\__,_/_/ /_/\__/_/\___/  /_/  \__,_/\___/_/_/_/\__/\__,_/\__/\____/_/
+

package/dist/index.mjs

@@ -5,30 +5,181 @@ import path from "path";
 import fs from "fs";
 import { fileURLToPath } from "url";
 import fse from "fs-extra";
-function log(msg) {
-  console.log(msg);
+import prompts from "prompts";
+function getAsciiArt() {
+  const asciiArtPath = path.join(
+    path.dirname(fileURLToPath(import.meta.url)),
+    "..",
+    "ascii-art.txt"
+  );
+  try {
+    return fs.readFileSync(asciiArtPath, "utf-8");
+  } catch (error) {
+    return "Mantle Facilitator";
+  }
 }
-function fail(msg) {
-  console.error(msg);
-  process.exit(1);
+async function promptSetup() {
+  const questions = [
+    {
+      type: "text",
+      name: "projectName",
+      message: "Where should we create the facilitator?",
+      initial: "my-facilitator",
+      validate: (value) => {
+        if (!value) return "Project name is required";
+        if (value !== "." && !/^[a-zA-Z0-9-_]+$/.test(value)) {
+          return "Name can only contain letters, numbers, dashes, and underscores";
+        }
+        const targetDir = value === "." ? process.cwd() : path.join(process.cwd(), value);
+        if (fs.existsSync(targetDir) && fs.readdirSync(targetDir).length > 0) {
+          return `Directory ${value} already exists and is not empty`;
+        }
+        return true;
+      }
+    },
+    {
+      type: "text",
+      name: "rpcUrl",
+      message: "RPC URL for Mantle network:",
+      initial: "https://rpc.mantle.xyz",
+      validate: (value) => {
+        if (!value.startsWith("http://") && !value.startsWith("https://")) {
+          return "RPC URL must start with http:// or https://";
+        }
+        return true;
+      }
+    },
+    {
+      type: "password",
+      name: "privateKey",
+      message: "Facilitator wallet private key (optional):",
+      validate: (value) => {
+        if (!value) return true;
+        if (!value.startsWith("0x")) return "Private key must start with 0x";
+        if (value.length !== 66) return "Private key must be 66 characters (0x + 64 hex)";
+        if (!/^0x[0-9a-fA-F]{64}$/.test(value)) return "Invalid hex format";
+        return true;
+      }
+    },
+    {
+      type: "text",
+      name: "usdcAddress",
+      message: "USDC contract address:",
+      initial: "0x09Bc4E0D864854c6aFB6eB9A9cdF58aC190D0dF9",
+      validate: (value) => {
+        if (!value.startsWith("0x")) return "Address must start with 0x";
+        if (value.length !== 42) return "Address must be 42 characters";
+        if (!/^0x[0-9a-fA-F]{40}$/.test(value)) return "Invalid hex format";
+        return true;
+      }
+    },
+    {
+      type: "confirm",
+      name: "enableTelemetry",
+      message: "Enable telemetry? (Send anonymous usage stats to improve the SDK)",
+      initial: false
+    },
+    {
+      type: (prev) => prev ? "text" : null,
+      name: "telemetryKey",
+      message: "Enter PROJECT_KEY from https://x402mantlesdk.xyz/dashboard (optional):",
+      initial: ""
+    }
+  ];
+  return await prompts(questions, {
+    onCancel: () => {
+      console.log("\nSetup cancelled.");
+      process.exit(0);
+    }
+  });
 }
-function cleanName(name) {
-  return name.replace(/[^a-zA-Z0-9-_]/g, "");
+function generateEnvFile(answers) {
+  const env = [
+    `# Server Configuration`,
+    `PORT=8080`,
+    ``,
+    `# Blockchain Configuration`,
+    `NETWORK_ID=mantle-mainnet`,
+    `CHAIN_ID=5000`,
+    `RPC_URL=${answers.rpcUrl}`,
+    ``,
+    `# USDC Token Configuration`,
+    `USDC_ADDRESS=${answers.usdcAddress}`,
+    `USDC_DECIMALS=6`,
+    ``,
+    `# Facilitator Wallet (keeps private key safe)`,
+    answers.privateKey ? `FACILITATOR_PRIVATE_KEY=${answers.privateKey}` : `# FACILITATOR_PRIVATE_KEY=0xYOUR_PRIVATE_KEY_HERE`,
+    ``,
+    `# Logging`,
+    `LOG_LEVEL=info`,
+    ``
+  ];
+  if (answers.enableTelemetry && answers.telemetryKey) {
+    env.push(`# Telemetry (Optional - for analytics)`);
+    env.push(`TELEMETRY_PROJECT_KEY=${answers.telemetryKey}`);
+    env.push(``);
+  } else if (answers.enableTelemetry) {
+    env.push(`# Telemetry (Optional - for analytics)`);
+    env.push(`# TELEMETRY_PROJECT_KEY=your_project_key_here`);
+    env.push(`# Get your key from https://x402mantlesdk.xyz/dashboard`);
+    env.push(``);
+  }
+  return env.join("\n");
 }
-async function main() {
-  const args = process.argv.slice(2);
-  const rawProjectName = args[0];
-  if (!rawProjectName) {
-    fail("Usage: create-mantle-facilitator <project-name>");
+async function createProjectInteractive() {
+  console.log(getAsciiArt());
+  console.log("\nWelcome to Mantle Facilitator Setup!\n");
+  const answers = await promptSetup();
+  const targetDir = answers.projectName === "." ? process.cwd() : path.join(process.cwd(), answers.projectName);
+  console.log(`
+Creating facilitator in ${targetDir}...`);
+  const templateDir = path.join(
+    path.dirname(fileURLToPath(import.meta.url)),
+    "..",
+    "template"
+  );
+  if (!fs.existsSync(templateDir)) {
+    console.error("ERROR: Template folder not found in CLI package.");
+    process.exit(1);
+  }
+  await fse.copy(templateDir, targetDir);
+  console.log("\u2713 Template files copied");
+  const packageJsonPath = path.join(targetDir, "package.json");
+  if (fs.existsSync(packageJsonPath)) {
+    const packageJson = JSON.parse(await fse.readFile(packageJsonPath, "utf-8"));
+    packageJson.name = answers.projectName === "." ? path.basename(process.cwd()) : answers.projectName;
+    if (packageJson.private === true) delete packageJson.private;
+    await fse.writeFile(packageJsonPath, JSON.stringify(packageJson, null, 2));
+    console.log("\u2713 Package configured");
+  }
+  const envContent = generateEnvFile(answers);
+  await fse.writeFile(path.join(targetDir, ".env"), envContent);
+  console.log("\u2713 Environment variables configured");
+  console.log("\n\u2713 Done! Your facilitator is ready.\n");
+  console.log("Next steps:");
+  if (answers.projectName !== ".") {
+    console.log(`  cd ${answers.projectName}`);
+  }
+  console.log("  npm install");
+  console.log("  npm run dev");
+  console.log("\nFacilitator will start on http://localhost:8080");
+  const reminders = [];
+  if (!answers.privateKey) {
+    reminders.push("IMPORTANT: Set FACILITATOR_PRIVATE_KEY in .env before starting");
+  }
+  if (answers.enableTelemetry && !answers.telemetryKey) {
+    reminders.push("Telemetry enabled: Get PROJECT_KEY from https://x402mantlesdk.xyz/dashboard");
   }
-  const projectName = cleanName(rawProjectName);
-  if (!projectName) {
-    fail("Invalid project name.");
+  if (reminders.length > 0) {
+    console.log("\n" + reminders.join("\n"));
   }
-  const cwd = process.cwd();
-  const targetDir = path.join(cwd, projectName);
+}
+async function createProjectNonInteractive(projectName) {
+  console.log(`Creating facilitator: ${projectName}`);
+  const targetDir = path.join(process.cwd(), projectName);
   if (fs.existsSync(targetDir)) {
-    fail(`Target directory already exists: ${targetDir}`);
+    console.error(`ERROR: Target directory already exists: ${targetDir}`);
+    process.exit(1);
   }
   const templateDir = path.join(
     path.dirname(fileURLToPath(import.meta.url)),
@@ -36,27 +187,45 @@ async function main() {
     "template"
   );
   if (!fs.existsSync(templateDir)) {
-    fail("Template folder not found in CLI package.");
+    console.error("ERROR: Template folder not found in CLI package.");
+    process.exit(1);
   }
   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("");
+  const packageJsonPath = path.join(targetDir, "package.json");
+  if (fs.existsSync(packageJsonPath)) {
+    const packageJson = JSON.parse(await fse.readFile(packageJsonPath, "utf-8"));
+    packageJson.name = projectName;
+    if (packageJson.private === true) delete packageJson.private;
+    await fse.writeFile(packageJsonPath, JSON.stringify(packageJson, null, 2));
+  }
+  const envDefaults = {
+    projectName,
+    rpcUrl: "https://rpc.mantle.xyz",
+    privateKey: "",
+    usdcAddress: "0x09Bc4E0D864854c6aFB6eB9A9cdF58aC190D0dF9",
+    enableTelemetry: false,
+    telemetryKey: ""
+  };
+  const envContent = generateEnvFile(envDefaults);
+  await fse.writeFile(path.join(targetDir, ".env"), envContent);
+  console.log("\n\u2713 Done!\n");
+  console.log("IMPORTANT: Edit .env file and set FACILITATOR_PRIVATE_KEY");
+  console.log(`Then run: cd ${projectName} && npm install && npm run dev`);
+}
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.length > 0) {
+    const projectName = args[0];
+    if (!/^[a-zA-Z0-9-_]+$/.test(projectName)) {
+      console.error("ERROR: Project name can only contain letters, numbers, dashes, and underscores");
+      process.exit(1);
+    }
+    await createProjectNonInteractive(projectName);
+    return;
+  }
+  await createProjectInteractive();
 }
 main().catch((err) => {
-  console.error(err);
+  console.error("Setup failed:", err);
   process.exit(1);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-mantle-facilitator",
-  "version": "0.3.1",
+  "version": "0.3.4",
   "private": false,
   "type": "module",
   "bin": {
@@ -8,7 +8,8 @@
   },
   "files": [
     "dist",
-    "template"
+    "template",
+    "ascii-art.txt"
   ],
   "scripts": {
     "build": "tsup",
@@ -16,11 +17,13 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "fs-extra": "^11.2.0"
+    "fs-extra": "^11.2.0",
+    "prompts": "^2.4.2"
   },
   "devDependencies": {
     "@types/fs-extra": "^11.0.4",
     "@types/node": "^22.0.0",
+    "@types/prompts": "^2.4.9",
     "tsup": "^8.0.0",
     "typescript": "^5.6.0"
   }

package/template/README.md

@@ -16,12 +16,15 @@ This facilitator:
 
 ## Quickstart
 
+This template is generated by `create-mantle-facilitator`. The CLI automatically creates a `.env` file with all configuration.
+
+If you need to modify configuration:
+1. Edit `.env` file
+2. Set `FACILITATOR_PRIVATE_KEY` if not already set
+3. Adjust `RPC_URL` if using a custom RPC endpoint
+
 ```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/src/x402.ts

@@ -183,7 +183,7 @@ export function verifyPayment(
         expected: authorization.from,
         message: 'This may indicate EIP-712 domain/types mismatch between SDK and facilitator'
       });
-      // ⚠️ DO NOT return error - let USDC contract validate on-chain
+      // WARNING: DO NOT return error - let USDC contract validate on-chain
     } else {
       console.log('[FACILITATOR] Signature verification passed (preflight check)');
     }
@@ -191,7 +191,7 @@ export function verifyPayment(
     console.warn('[FACILITATOR WARNING] Signature verification failed (will let USDC contract validate on-chain)', {
       error: err instanceof Error ? err.message : "Unknown error"
     });
-    // ⚠️ DO NOT return error - let USDC contract validate on-chain
+    // WARNING: DO NOT return error - let USDC contract validate on-chain
   }
 
   return { isValid: true, invalidReason: null };

package/template/.env.example

@@ -1,25 +0,0 @@
-# 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
-
-# =============================================================================
-# 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