facinet 2.2.1 → 2.3.0

package/README.md

@@ -2,17 +2,16 @@
 
 > JavaScript SDK and CLI tool for the x402 Facilitator Network
 
-Make gasless USDC payments and manage facilitators on the x402 decentralized payment network powered by Avalanche.
+Make gasless USDC payments and manage facilitators on the x402 decentralized payment network. Now with **multichain support** across 4 testnets.
 
-## Features
+## Supported Chains
 
-- 💳 **Make Payments** - Gasless USDC transfers via ERC-3009
-- 🎲 **Random Facilitator Selection** - Fair distribution across network
-- 🌐 **Multi-Platform** - Works in browser (MetaMask) and Node.js
-- 🚀 **Easy Integration** - Simple SDK for developers
-- 📊 **CLI Tool** - Command-line interface for payments and management
-- 🔐 **Secure** - Wallet management with encryption
-- ⚡ **Fast** - Built on Avalanche for sub-second finality
+| Chain | Network ID | Gas Token | Explorer |
+|-------|-----------|-----------|----------|
+| Avalanche Fuji | `avalanche-fuji` | AVAX | testnet.snowtrace.io |
+| Ethereum Sepolia | `ethereum-sepolia` | ETH | sepolia.etherscan.io |
+| Base Sepolia | `base-sepolia` | ETH | sepolia.basescan.org |
+| Polygon Amoy | `polygon-amoy` | MATIC | amoy.polygonscan.com |
 
 ## Installation
 
@@ -35,19 +34,20 @@ npm install -g facinet
 ```typescript
 import { Facinet } from 'facinet';
 
-// Initialize SDK
+// Initialize SDK - choose your chain
 const facinet = new Facinet({
-  network: 'avalanche', // or 'ethereum', 'polygon'
+  network: 'base-sepolia', // or 'avalanche-fuji', 'ethereum-sepolia', 'polygon-amoy'
 });
 
 // Make a payment (MetaMask will prompt for signature)
 const result = await facinet.pay({
-  amount: '1',                              // Amount in USDC
-  recipient: '0xYourMerchantAddress',       // Where you want to receive payment
+  amount: '1',
+  recipient: '0xYourMerchantAddress',
 });
 
 console.log('Payment successful!', result.txHash);
 console.log('Processed by:', result.facilitator.name);
+console.log('Network:', result.payment.network);
 ```
 
 ### Node.js (with Private Key)
@@ -55,10 +55,10 @@ console.log('Processed by:', result.facilitator.name);
 ```typescript
 import { Facinet } from 'facinet';
 
-// Initialize with private key
+// Initialize with private key on Polygon Amoy
 const facinet = new Facinet({
   privateKey: process.env.PRIVATE_KEY,
-  network: 'avalanche',
+  network: 'polygon-amoy',
 });
 
 // Make a payment
@@ -75,11 +75,12 @@ console.log('Transaction:', result.txHash);
 ```typescript
 import { Facinet } from 'facinet';
 
-// Quick payment without creating instance
+// Quick payment on any chain
 await Facinet.quickPay({
   amount: '1',
   recipient: '0xMerchantAddress',
   privateKey: process.env.PRIVATE_KEY,
+  network: 'ethereum-sepolia',
 });
 ```
 
@@ -97,17 +98,40 @@ const randomFacilitator = await facinet.selectRandomFacilitator();
 console.log('Selected:', randomFacilitator.name);
 ```
 
+### Get Supported Chains
+
+```typescript
+import { Facinet } from 'facinet';
+
+// List all supported chains
+const chains = Facinet.getSupportedChains();
+chains.forEach(chain => {
+  console.log(`${chain.displayName} (${chain.name}) - Chain ID: ${chain.chainId}`);
+});
+
+// Get supported network names
+const networks = Facinet.getSupportedNetworks();
+console.log('Networks:', networks);
+// ['avalanche-fuji', 'ethereum-sepolia', 'base-sepolia', 'polygon-amoy']
+```
+
 ### SDK Configuration Options
 
 ```typescript
 interface FacinetConfig {
   apiUrl?: string;       // Default: 'https://x402-avalanche-chi.vercel.app'
   privateKey?: string;   // For Node.js (not needed in browser)
-  network?: 'avalanche' | 'ethereum' | 'polygon';  // Default: 'avalanche'
+  network?: 'avalanche-fuji' | 'ethereum-sepolia' | 'base-sepolia' | 'polygon-amoy';
   rpcUrl?: string;       // Custom RPC URL (optional)
 }
 ```
 
+**Legacy aliases** are supported for backwards compatibility:
+- `'avalanche'` -> `'avalanche-fuji'`
+- `'ethereum'` -> `'ethereum-sepolia'`
+- `'polygon'` -> `'polygon-amoy'`
+- `'base'` -> `'base-sepolia'`
+
 ### TypeScript Support
 
 Facinet is written in TypeScript and includes full type definitions:
@@ -117,11 +141,12 @@ import type {
   FacinetConfig,
   PaymentParams,
   PaymentResult,
-  Facilitator
+  Facilitator,
+  ChainConfig
 } from 'facinet';
 
 const config: FacinetConfig = {
-  network: 'avalanche',
+  network: 'base-sepolia',
 };
 
 const params: PaymentParams = {
@@ -139,11 +164,12 @@ import { Facinet } from 'facinet';
 function PaymentButton() {
   const [loading, setLoading] = useState(false);
   const [txHash, setTxHash] = useState('');
+  const [network] = useState('base-sepolia');
 
   const handlePayment = async () => {
     setLoading(true);
     try {
-      const facinet = new Facinet({ network: 'avalanche' });
+      const facinet = new Facinet({ network });
 
       const result = await facinet.pay({
         amount: '1',
@@ -165,11 +191,7 @@ function PaymentButton() {
       <button onClick={handlePayment} disabled={loading}>
         {loading ? 'Processing...' : 'Pay 1 USDC'}
       </button>
-      {txHash && (
-        <p>Transaction: <a href={`https://testnet.snowtrace.io/tx/${txHash}`} target="_blank">
-          {txHash.slice(0, 10)}...
-        </a></p>
-      )}
+      {txHash && <p>Transaction: {txHash.slice(0, 10)}...</p>}
     </div>
   );
 }
@@ -177,14 +199,12 @@ function PaymentButton() {
 
 ### How SDK Payments Work
 
-1. **Initialize SDK** - Create Facinet instance with your config
+1. **Initialize SDK** - Create Facinet instance with your config and chain
 2. **Random Facilitator** - SDK automatically picks random active facilitator
 3. **Sign Authorization** - User signs ERC-3009 authorization (gasless!)
 4. **Facilitator Executes** - Facilitator submits transaction and pays gas
 5. **Payment Complete** - USDC transferred to YOUR merchant address
 
-**Key Point:** The `recipient` you specify in `pay()` is where YOU receive payment. The SDK automatically handles facilitator selection and gas payment.
-
 ## CLI Usage
 
 ### Quick Start
@@ -195,145 +215,34 @@ function PaymentButton() {
 facinet connect
 ```
 
-Choose to either:
-- Enter your private key (for testing)
-- Generate a new wallet
-
 ### 2. Make a Payment
 
 ```bash
+# Pay on Avalanche (default)
 facinet pay --amount 1 --to 0xRecipientAddress
-```
 
-The CLI will automatically:
-- Select a random active facilitator
-- Sign the payment authorization
-- Submit to the facilitator network
-- Show transaction details
+# Pay on Base Sepolia
+facinet pay --amount 1 --to 0xRecipientAddress --chain base
 
-### 3. List Active Facilitators
+# Pay on Polygon Amoy
+facinet pay --amount 1 --to 0xRecipientAddress --chain polygon
 
-```bash
-facinet facilitator list
+# Pay on Ethereum Sepolia
+facinet pay --amount 1 --to 0xRecipientAddress --chain ethereum
 ```
 
-See all active facilitators in the network with their stats.
-
-### 4. Check Facilitator Status
-
-```bash
-facinet facilitator status fac_xyz123
-```
-
-View detailed information about a specific facilitator.
-
-## Commands
-
-### Connection
-
-#### `facinet connect`
-
-Connect your wallet to Facinet. Options:
-- Enter existing private key
-- Generate new wallet
-
-Config is saved to `~/.facinet/config.json`
-
----
-
-### Payment Commands
-
-#### `facinet pay`
-
-Make a payment via the x402 facilitator network.
-
-**Options:**
-- `-a, --amount <amount>` - Payment amount in USDC (default: 1)
-- `-t, --to <address>` - Recipient Ethereum address
-- `-c, --chain <chain>` - Blockchain network (default: avalanche)
-- `-n, --network <url>` - Custom API URL
-
-**Examples:**
-
-```bash
-# Pay 1 USDC to recipient
-facinet pay --to 0x123...
-
-# Pay custom amount
-facinet pay --amount 5 --to 0x456...
-
-# Use custom API endpoint
-facinet pay --to 0x789... --network https://my-api.com
-```
-
----
-
-### Facilitator Commands
-
-#### `facinet facilitator create`
-
-Create a new facilitator (requires 1 USDC registration fee).
-
-**Options:**
-- `-n, --name <name>` - Facilitator name
-- `-r, --recipient <address>` - Payment recipient address
-- `-u, --url <url>` - API URL (default: http://localhost:3000)
-
-**Example:**
-
-```bash
-facinet facilitator create --name "MyNode" --recipient 0xABC...
-```
-
-**Important:** Save the facilitator wallet private key shown after creation!
-
-#### `facinet facilitator list`
-
-List all active facilitators in the network.
-
-**Options:**
-- `-u, --url <url>` - API URL (default: http://localhost:3000)
-
-**Example:**
+### 3. List Active Facilitators
 
 ```bash
 facinet facilitator list
 ```
 
-#### `facinet facilitator status <id>`
-
-Check the status of a specific facilitator.
-
-**Arguments:**
-- `<id>` - Facilitator ID (e.g., fac_xyz123)
-
-**Options:**
-- `-u, --url <url>` - API URL
-
-**Example:**
-
-```bash
-facinet facilitator status fac_NdIk4EytdaIYHRK1
-```
-
-#### `facinet facilitator balance <id>`
-
-Check the AVAX gas balance of a facilitator.
-
-**Arguments:**
-- `<id>` - Facilitator ID
-
-**Options:**
-- `-u, --url <url>` - API URL
-
-**Example:**
+### 4. Check Facilitator Status
 
 ```bash
-facinet facilitator balance fac_NdIk4EytdaIYHRK1
+facinet facilitator status fac_xyz123
 ```
 
----
-
 ## Configuration
 
 Facinet stores configuration in `~/.facinet/config.json`:
@@ -343,31 +252,23 @@ Facinet stores configuration in `~/.facinet/config.json`:
   "privateKey": "0x...",
   "address": "0x...",
   "network": "avalanche-fuji",
-  "apiUrl": "http://localhost:3000"
+  "apiUrl": "https://x402-avalanche-chi.vercel.app"
 }
 ```
 
-## Supported Networks
-
-- **Avalanche** (Fuji Testnet) - Default
-- **Ethereum** (Sepolia Testnet)
-- More chains coming soon
-
 ## How It Works
 
-1. **Random Selection** - CLI picks a random active facilitator from the network
+1. **Random Selection** - SDK/CLI picks a random active facilitator from the network
 2. **Sign Authorization** - You sign an ERC-3009 payment authorization (gasless for you!)
 3. **Facilitator Executes** - The facilitator submits the transaction and pays gas
-4. **Payment Complete** - USDC transferred on-chain, access granted
+4. **Payment Complete** - USDC transferred on-chain
 
 ## Development
 
 ### Build from Source
 
 ```bash
-# Clone repository
-git clone https://github.com/your-repo/x402.git
-cd x402/packages/facinet
+cd facinet-sdk
 
 # Install dependencies
 npm install
@@ -385,10 +286,10 @@ facinet --help
 ### Project Structure
 
 ```
-facinet/
+facinet-sdk/
 ├── src/
 │   ├── sdk/
-│   │   ├── Facinet.ts    # Main SDK class
+│   │   ├── Facinet.ts    # Main SDK class (multichain)
 │   │   └── types.ts      # TypeScript types
 │   ├── commands/
 │   │   ├── connect.ts    # Wallet connection
@@ -400,92 +301,20 @@ facinet/
 │   ├── sdk.ts            # SDK exports
 │   └── index.ts          # CLI entry point
 ├── dist/                 # Compiled JavaScript
+├── build.js              # esbuild config
 ├── package.json
 ├── tsconfig.json
 └── README.md
 ```
 
-## Security
-
-- **Private keys** are stored encrypted in `~/.facinet/config.json`
-- **Never share** your private key or config file
-- **Use test wallets** for testnet development
-- **Backup** your private keys securely
-
-## Troubleshooting
-
-### "No wallet connected"
-
-Run `facinet connect` first to set up your wallet.
-
-### "No active facilitators available"
-
-The network has no active facilitators. Create one with:
-```bash
-facinet facilitator create
-```
+## What's New in v2.3.0
 
-### "Insufficient USDC"
-
-You need USDC in your wallet. On testnet:
-1. Get AVAX from faucet
-2. Swap AVAX → USDC
-
-### API connection errors
-
-Check that your API URL is correct:
-```bash
-facinet pay --network https://your-api-url.com
-```
-
-## Examples
-
-### Complete Payment Flow
-
-```bash
-# 1. Connect wallet
-facinet connect
-
-# 2. List available facilitators
-facinet facilitator list
-
-# 3. Make payment
-facinet pay --amount 1 --to 0x1234567890123456789012345678901234567890
-
-# Output:
-# ✅ Payment processed successfully!
-# Facilitator: Xavier
-# Amount: 1 USDC
-# Recipient: 0x123...
-```
-
-### Create and Monitor Facilitator
-
-```bash
-# 1. Create facilitator
-facinet facilitator create --name "MyNode"
-
-# 2. Fund with AVAX (send to facilitator wallet address)
-# ...
-
-# 3. Check status
-facinet facilitator status fac_abc123
-
-# 4. Monitor balance
-facinet facilitator balance fac_abc123
-```
-
-## Resources
-
-- [x402 Protocol](https://github.com/x402-rs/x402-rs)
-- [Documentation](https://docs.x402.network)
-- [Avalanche Docs](https://docs.avax.network/)
-- [Report Issues](https://github.com/your-repo/x402/issues)
+- **Multichain Support** - Now supports 4 chains: Avalanche Fuji, Ethereum Sepolia, Base Sepolia, Polygon Amoy
+- **Chain-specific ERC-3009 domains** - Correct EIP-712 domain names per chain (USD Coin vs USDC)
+- **Legacy aliases** - Old network names (`avalanche`, `ethereum`, `polygon`) still work
+- **Static helpers** - `Facinet.getSupportedChains()` and `Facinet.getSupportedNetworks()`
+- **`quickPay` with network** - Now accepts `network` parameter for chain selection
 
 ## License
 
 MIT © x402 Team
-
----
-
-**Built with x402 on Avalanche** ⚡