create-mantle-facilitator 0.3.3 → 0.3.5

package/README.md

@@ -0,0 +1,373 @@
+# create-mantle-facilitator
+
+[![npm version](https://img.shields.io/npm/v/create-mantle-facilitator.svg)](https://www.npmjs.com/package/create-mantle-facilitator)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+CLI tool to scaffold a self-hosted x402 payment facilitator for Mantle blockchain.
+
+## Quick Start
+
+```bash
+npx create-mantle-facilitator my-facilitator
+cd my-facilitator
+npm install
+npm run dev
+```
+
+The CLI will guide you through the setup:
+
+```
+Welcome to Mantle Facilitator Setup!
+
+? Where should we create the facilitator? my-facilitator
+? 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)
+
+✓ Done! Your facilitator is ready.
+```
+
+## Configuration
+
+After creation, edit the `.env` file:
+
+```env
+# Required
+FACILITATOR_PRIVATE_KEY=0x...   # Wallet that pays gas fees
+RPC_URL=https://rpc.mantle.xyz  # Mantle RPC endpoint
+
+# Optional
+USDC_ADDRESS=0x09Bc4E0D864854c6aFB6eB9A9cdF58aC190D0dF9
+PORT=8080
+NETWORK_ID=mantle-mainnet
+CHAIN_ID=5000
+
+# Telemetry (optional)
+TELEMETRY_PROJECT_KEY=pk_xxx    # Get from dashboard
+```
+
+### Important Notes
+
+- **FACILITATOR_PRIVATE_KEY**: This wallet will pay gas fees for all settlements. Make sure it has MNT for gas.
+- **Security**: Never commit `.env` to version control. The generated `.gitignore` already excludes it.
+
+## Running Locally
+
+```bash
+# Development mode (hot reload)
+npm run dev
+
+# Build for production
+npm run build
+
+# Run production build
+npm start
+```
+
+Facilitator runs on `http://localhost:8080` by default.
+
+---
+
+## Deployment
+
+### Railway (Recommended)
+
+```bash
+# Install Railway CLI
+npm install -g @railway/cli
+
+# Login and deploy
+railway login
+railway init
+railway up
+```
+
+Then add environment variables in Railway dashboard.
+
+### Render
+
+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
+
+### Fly.io
+
+```bash
+# Install Fly CLI and login
+flyctl auth login
+
+# Launch (creates fly.toml)
+flyctl launch
+
+# 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
+```
+
+### Docker
+
+```dockerfile
+FROM node:20-alpine
+WORKDIR /app
+COPY package*.json ./
+RUN npm install
+COPY . .
+RUN npm run build
+EXPOSE 8080
+CMD ["npm", "start"]
+```
+
+```bash
+docker build -t my-facilitator .
+docker run -p 8080:8080 --env-file .env my-facilitator
+```
+
+### VPS (DigitalOcean, Hetzner, etc.)
+
+```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
+```
+
+Optional: Add Nginx reverse proxy for HTTPS.
+
+---
+
+## API Endpoints
+
+### GET /health
+
+Returns facilitator status and wallet info.
+
+```bash
+curl http://localhost:8080/health
+```
+
+```json
+{
+  "status": "ok",
+  "network": "mantle-mainnet",
+  "chainId": 5000,
+  "facilitatorAddress": "0x...",
+  "blockNumber": 12345678,
+  "mntBalance": "1.5"
+}
+```
+
+### GET /supported
+
+Returns supported networks and assets.
+
+```bash
+curl http://localhost:8080/supported
+```
+
+```json
+{
+  "x402Version": 1,
+  "schemes": ["exact"],
+  "networks": ["mantle-mainnet"],
+  "assets": {
+    "mantle-mainnet": [{
+      "address": "0x09Bc4E0D864854c6aFB6eB9A9cdF58aC190D0dF9",
+      "symbol": "USDC",
+      "decimals": 6
+    }]
+  }
+}
+```
+
+### POST /verify
+
+Verifies a payment header without executing.
+
+```bash
+curl -X POST http://localhost:8080/verify \
+  -H "Content-Type: application/json" \
+  -d '{
+    "x402Version": 1,
+    "paymentHeader": "base64...",
+    "paymentRequirements": {...}
+  }'
+```
+
+```json
+{
+  "isValid": true
+}
+```
+
+### POST /settle
+
+Executes the USDC transfer on-chain.
+
+```bash
+curl -X POST http://localhost:8080/settle \
+  -H "Content-Type: application/json" \
+  -d '{
+    "x402Version": 1,
+    "paymentHeader": "base64...",
+    "paymentRequirements": {...}
+  }'
+```
+
+```json
+{
+  "success": true,
+  "txHash": "0x..."
+}
+```
+
+---
+
+## How It Works
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                     Settlement Flow                             │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  1. Client signs EIP-712 authorization (gasless for user)       │
+│                           │                                     │
+│                           ▼                                     │
+│  2. Client sends to facilitator POST /settle                    │
+│                           │                                     │
+│                           ▼                                     │
+│  3. Facilitator verifies signature                              │
+│                           │                                     │
+│                           ▼                                     │
+│  4. Facilitator calls USDC.transferWithAuthorization()          │
+│     - Pays gas in MNT                                           │
+│     - USDC transfers from user → merchant                       │
+│                           │                                     │
+│                           ▼                                     │
+│  5. Returns txHash to client                                    │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+The facilitator uses EIP-3009 `transferWithAuthorization` which allows:
+- **Gasless for users**: Users only sign, never pay gas
+- **Atomic transfers**: Signature + transfer in one transaction
+- **Replay protection**: Nonces prevent double-spending
+
+---
+
+## Telemetry
+
+When `TELEMETRY_PROJECT_KEY` is set, the facilitator sends anonymous analytics:
+
+**What is sent:**
+- Payment metadata (buyer address, amount, asset, network)
+- Transaction hash
+- Timestamp
+- Facilitator address
+
+**What is NOT sent:**
+- Private keys
+- Personal information
+- Request/response payloads
+
+Get your project key from [Dashboard](https://x402mantlesdk.xyz/dashboard).
+
+Telemetry errors never affect payment processing — if analytics backend is down, payments continue normally.
+
+---
+
+## Security Considerations
+
+1. **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
+
+2. **Gas Management**
+   - Monitor MNT balance regularly
+   - Set up alerts for low balance
+   - Facilitator needs ~0.001 MNT per settlement
+
+3. **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
+```
+
+---
+
+## Links
+
+- [SDK Documentation](../x402-mantle-sdk)
+- [Full Documentation](https://x402mantlesdk.xyz/docs)
+- [Dashboard](https://x402mantlesdk.xyz/dashboard)
+- [GitHub](https://github.com/puga-labs/x402-mantle-sdk)
+
+## License
+
+MIT

package/package.json

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

package/template/README.md

@@ -1,50 +1,98 @@
-# Mantle x402 Facilitator (Self-hosted Template)
+# Mantle x402 Facilitator
 
-A minimal, self-hosted x402 facilitator for **Mantle mainnet** using **USDC (EIP-3009)**.
+A self-hosted x402 payment 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
+- Verifies x402 payment headers
+- Settles payments on-chain via `transferWithAuthorization`
+- Pays gas from the facilitator wallet
+
+## Quick Start
+
+```bash
+npm install
+npm run dev
+```
+
+Facilitator runs on `http://localhost:8080`.
+
+## Configuration
+
+Edit `.env` file:
+
+```env
+# Required
+FACILITATOR_PRIVATE_KEY=0x...   # Wallet that pays gas
+RPC_URL=https://rpc.mantle.xyz
+
+# Optional
+PORT=8080
+USDC_ADDRESS=0x09Bc4E0D864854c6aFB6eB9A9cdF58aC190D0dF9
+
+# Telemetry (optional)
+TELEMETRY_PROJECT_KEY=pk_xxx    # Get from https://x402mantlesdk.xyz/dashboard
+```
+
+**Important:** The facilitator wallet needs MNT for gas fees. Check balance at `/health`.
 
 ## Endpoints
 
-- `GET /health`
-- `GET /supported`
-- `POST /verify`
-- `POST /settle`
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/health` | GET | Facilitator status and wallet balance |
+| `/supported` | GET | Supported networks and assets |
+| `/verify` | POST | Verify payment header |
+| `/settle` | POST | Execute USDC transfer on-chain |
 
-## Quickstart
+## Scripts
 
 ```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
+npm run dev    # Development with hot reload
+npm run build  # Build for production
+npm start      # Run production build
+```
+
+## Deployment
+
+### Railway
+
+```bash
+railway login
+railway init
+railway up
+```
+
+Add environment variables in Railway dashboard.
+
+### Docker
+
+```bash
+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
 ```
 
-## Optional: Analytics & Telemetry
+## Telemetry
 
-To enable opt-in telemetry for payment tracking and analytics:
+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
 
-1. Get your project key from https://nosubs.ai/dashboard (or your analytics platform)
-2. Add to `.env`:
-   ```bash
-   TELEMETRY_PROJECT_KEY=proj_abc123xyz
-   ```
+**What is sent:** buyer address, amount, asset, txHash, timestamp
 
-**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 is NOT sent:** private keys, personal info, request payloads
 
-**What data is sent:**
-- Payment metadata (buyer address, amount, asset, network)
-- Transaction hash (after settlement)
-- Timestamp
+Telemetry errors never break payment processing.
 
-**What is NOT sent:**
-- Private keys
-- User personal information
-- Request/response payloads from your protected endpoints
+## Links
 
-Telemetry errors never break payment processing - if the analytics backend is down, payments continue to work normally.
+- [SDK Documentation](https://www.npmjs.com/package/@puga-labs/x402-mantle-sdk)
+- [Full Documentation](https://x402mantlesdk.xyz/docs)
+- [Dashboard](https://x402mantlesdk.xyz/dashboard)

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