create-mantle-facilitator 0.4.3 → 0.4.4

package/README.md

@@ -8,8 +8,8 @@ CLI tool to scaffold a self-hosted x402 payment facilitator for Mantle blockchai
 ## Quick Start
 
 ```bash
-npx create-mantle-facilitator my-facilitator
-cd my-facilitator
+npx create-mantle-facilitator
+cd my-facilitator  # or the name you chose
 npm install
 npm run dev
 ```
@@ -23,8 +23,7 @@ Welcome to Mantle Facilitator Setup!
 ? RPC URL for Mantle network: https://rpc.mantle.xyz
 ? Facilitator wallet private key: (optional, set later)
 ? USDC contract address: 0x09Bc4E0D864854c6aFB6eB9A9cdF58aC190D0dF9
-? Enable telemetry? Yes
-? Enter PROJECT_KEY from dashboard: (optional)
+? Enable telemetry? (Send anonymous usage stats) No
 
 ✓ Done! Your facilitator is ready.
 ```
@@ -45,10 +44,13 @@ PORT=8080
 NETWORK_ID=mantle-mainnet
 CHAIN_ID=5000
 
-# Telemetry (optional)
-TELEMETRY_PROJECT_KEY=pk_xxx    # Get from dashboard
+# Telemetry (Optional - always present in .env)
+# TELEMETRY_PROJECT_KEY=your_project_key_here
+# Get your key from https://x402mantlesdk.xyz/dashboard
 ```
 
+**Note:** The telemetry section is always added to `.env` (commented out if disabled during setup). To enable later, just uncomment and add your project key.
+
 ### Important Notes
 
 - **FACILITATOR_PRIVATE_KEY**: This wallet will pay gas fees for all settlements. Make sure it has MNT for gas.
@@ -89,50 +91,43 @@ npm start
 
 Facilitator runs on `http://localhost:8080` by default.
 
----
-
-## Deployment
-
-### Railway (Recommended)
+### Startup Banner
 
-```bash
-# Install Railway CLI
-npm install -g @railway/cli
+When the facilitator starts successfully, you'll see a banner:
 
-# Login and deploy
-railway login
-railway init
-railway up
+```
++--------------------------------------------------+
+|  Mantle x402 Facilitator                         |
++--------------------------------------------------+
+|  Network:     mantle-mainnet (5000)              |
+|  Address:     0xAbcd...ef01                      |
+|  Port:        8080                               |
+|  Telemetry:   disabled                           |
++--------------------------------------------------+
+
+Note: Telemetry is disabled.
+  To enable analytics, set TELEMETRY_PROJECT_KEY in .env
+  Get your key at https://x402mantlesdk.xyz/dashboard
+
+Server listening on http://localhost:8080
 ```
 
-Then add environment variables in Railway dashboard.
+### Configuration Validation
 
-### Render
+The facilitator validates all required environment variables at startup with helpful error messages:
 
-1. Push your facilitator to GitHub
-2. Create new Web Service in Render
-3. Connect your repository
-4. Set build command: `npm install && npm run build`
-5. Set start command: `npm start`
-6. Add environment variables
+- **FACILITATOR_PRIVATE_KEY**: Must be 66 chars (0x + 64 hex digits)
+- **FACILITATOR_SECRET**: Required for secure authentication
+- **RPC_URL**: Must be valid URL (http:// or https://)
+- **USDC_ADDRESS**: Must be valid Ethereum address
 
-### Fly.io
+If validation fails, you'll see step-by-step fix instructions in the console.
 
-```bash
-# Install Fly CLI and login
-flyctl auth login
+---
 
-# Launch (creates fly.toml)
-flyctl launch
+## Deployment
 
-# Set secrets
-flyctl secrets set FACILITATOR_PRIVATE_KEY=0x...
-flyctl secrets set RPC_URL=https://rpc.mantle.xyz
-flyctl secrets set USDC_ADDRESS=0x09Bc4E0D864854c6aFB6eB9A9cdF58aC190D0dF9
-
-# Deploy
-flyctl deploy
-```
+Deploy your facilitator to any Node.js hosting platform.
 
 ### Docker
 
@@ -152,27 +147,16 @@ docker build -t my-facilitator .
 docker run -p 8080:8080 --env-file .env my-facilitator
 ```
 
-### VPS (DigitalOcean, Hetzner, etc.)
+### Railway
 
 ```bash
-# On your server
-git clone <your-repo>
-cd my-facilitator
-npm install
-npm run build
-
-# Install PM2 for process management
-npm install -g pm2
-
-# Start with PM2
-pm2 start dist/index.js --name facilitator
-
-# Save process list and setup startup script
-pm2 save
-pm2 startup
+npm install -g @railway/cli
+railway login
+railway init
+railway up
 ```
 
-Optional: Add Nginx reverse proxy for HTTPS.
+Then add environment variables in Railway dashboard.
 
 ---
 
@@ -299,6 +283,25 @@ The facilitator uses EIP-3009 `transferWithAuthorization` which allows:
 
 ---
 
+## Supported Tokens
+
+Currently, the facilitator supports **USDC only** for gasless payments.
+
+### Why only USDC?
+
+Gasless payments require tokens that implement the **EIP-3009** standard (`transferWithAuthorization`). This standard allows users to sign a payment authorization off-chain, while the facilitator submits the transaction and pays gas fees.
+
+On Mantle mainnet, **USDC is currently the only token** that implements EIP-3009. As other stablecoins and tokens adopt this standard, we will add support for them.
+
+| Token | EIP-3009 Support | Status |
+|-------|------------------|--------|
+| USDC | Yes | Supported |
+| USDT | No | Not available |
+| DAI | No | Not available |
+| Other tokens | — | Pending EIP-3009 adoption |
+
+---
+
 ## Telemetry
 
 When `TELEMETRY_PROJECT_KEY` is set, the facilitator sends anonymous analytics:
@@ -331,63 +334,6 @@ Telemetry errors never affect payment processing — if analytics backend is dow
 2. **Private Key Security**
    - Never commit `.env` to git
    - Use secret management in production (Railway secrets, Fly secrets, etc.)
-   - Consider using hardware wallets for high-value facilitators
-
-3. **Gas Management**
-   - Monitor MNT balance regularly
-   - Set up alerts for low balance
-   - Facilitator needs ~0.001 MNT per settlement
-
-4. **Network Security**
-   - Use HTTPS in production
-   - Consider rate limiting
-   - Monitor for unusual patterns
-
----
-
-## Monitoring
-
-Check facilitator health:
-
-```bash
-# Check if running
-curl http://your-facilitator.com/health
-
-# Check wallet balance
-curl http://your-facilitator.com/health | jq '.mntBalance'
-```
-
-Set up monitoring alerts for:
-- Health endpoint availability
-- Low MNT balance (< 0.1 MNT)
-- High error rates
-
----
-
-## Troubleshooting
-
-### "Missing env var: FACILITATOR_PRIVATE_KEY"
-
-Set the private key in `.env`:
-```env
-FACILITATOR_PRIVATE_KEY=0x...
-```
-
-### "Insufficient funds for gas"
-
-The facilitator wallet needs MNT for gas fees. Send some MNT to the facilitator address shown in `/health`.
-
-### "Invalid signature"
-
-- Check that the client is signing for the correct network (Mantle mainnet, chainId 5000)
-- Verify USDC address matches: `0x09Bc4E0D864854c6aFB6eB9A9cdF58aC190D0dF9`
-
-### Port already in use
-
-Change the port in `.env`:
-```env
-PORT=8081
-```
 
 ---
 

package/package.json

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

package/template/README.md

@@ -16,6 +16,27 @@ npm run dev
 
 Facilitator runs on `http://localhost:8080`.
 
+## Startup Information
+
+When the facilitator starts, it displays a banner with:
+- Network and chain ID (Mantle mainnet, 5000)
+- Facilitator wallet address
+- Port
+- Telemetry status
+
+```
++--------------------------------------------------+
+|  Mantle x402 Facilitator                         |
++--------------------------------------------------+
+|  Network:     mantle-mainnet (5000)              |
+|  Address:     0xAbcd...ef01                      |
+|  Port:        8080                               |
+|  Telemetry:   disabled                           |
++--------------------------------------------------+
+```
+
+If telemetry is disabled, you'll see instructions to enable it.
+
 ## Configuration
 
 Edit `.env` file:
@@ -30,10 +51,22 @@ FACILITATOR_SECRET=fac_xxx...   # Auto-generated, share with your backend
 PORT=8080
 USDC_ADDRESS=0x09Bc4E0D864854c6aFB6eB9A9cdF58aC190D0dF9
 
-# Telemetry (optional)
-TELEMETRY_PROJECT_KEY=pk_xxx    # Get from https://x402mantlesdk.xyz/dashboard
+# Telemetry (Optional - always present in .env)
+# TELEMETRY_PROJECT_KEY=your_project_key_here
+# Get your key from https://x402mantlesdk.xyz/dashboard
 ```
 
+### Configuration Validation
+
+Required variables are validated at startup with helpful error messages:
+
+- **FACILITATOR_PRIVATE_KEY** - Must be 66 chars (0x + 64 hex)
+- **FACILITATOR_SECRET** - Required for secure authentication
+- **RPC_URL** - Must be valid URL
+- **USDC_ADDRESS** - Must be valid Ethereum address
+
+If validation fails, you'll see step-by-step fix instructions.
+
 **Important:**
 - The facilitator wallet needs MNT for gas fees. Check balance at `/health`.
 - Copy `FACILITATOR_SECRET` to your backend's environment variables.
@@ -84,36 +117,27 @@ npm start      # Run production build
 
 ## Deployment
 
-### Railway
-
-```bash
-railway login
-railway init
-railway up
-```
-
-Add environment variables in Railway dashboard.
-
-### Docker
+Deploy to any Node.js hosting platform. Examples:
 
 ```bash
+# Docker
 docker build -t facilitator .
 docker run -p 8080:8080 --env-file .env facilitator
-```
-
-### PM2 (VPS)
 
-```bash
-npm run build
-pm2 start dist/index.js --name facilitator
+# Railway
+railway login && railway init && railway up
 ```
 
 ## Telemetry
 
-When `TELEMETRY_PROJECT_KEY` is set:
-- Settlement events are sent to analytics
-- Track payments in [Dashboard](https://x402mantlesdk.xyz/dashboard)
-- No sensitive data is transmitted
+The `TELEMETRY_PROJECT_KEY` setting is always present in `.env`:
+- If enabled during setup: filled with your key
+- If disabled: commented out (easy to enable later)
+
+**To enable telemetry:**
+1. Get key from https://x402mantlesdk.xyz/dashboard
+2. Uncomment `TELEMETRY_PROJECT_KEY` in `.env`
+3. Restart facilitator
 
 **What is sent:** buyer address, amount, asset, txHash, timestamp