facinet 2.2.2 → 2.4.1

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 with **network-specific facilitator selection**.
 
-## 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 | Chain ID | Gas Token | Explorer | API URL |
+|-------|-----------|----------|-----------|----------|---------|
+| Avalanche Fuji | `avalanche-fuji` | 43113 | AVAX | testnet.snowtrace.io | x402-avalanche-chi.vercel.app |
+| Ethereum Sepolia | `ethereum-sepolia` | 11155111 | ETH | sepolia.etherscan.io | x402-ethereum-chi.vercel.app |
+| Base Sepolia | `base-sepolia` | 84532 | ETH | sepolia.basescan.org | x402-base-chi.vercel.app |
+| Polygon Amoy | `polygon-amoy` | 80002 | MATIC | amoy.polygonscan.com | x402-polygon-chi.vercel.app |
 
 ## Installation
 
@@ -30,24 +29,30 @@ npm install -g facinet
 
 ## SDK Usage
 
+### Network-Specific Facilitator Selection
+
+The SDK automatically selects **active facilitators** for the **specific network** you're using. Each network has its own facilitator pool, and the SDK ensures you only get facilitators registered for that network.
+
 ### Browser (with MetaMask)
 
 ```typescript
 import { Facinet } from 'facinet';
 
-// Initialize SDK
+// Initialize SDK for Base Sepolia network
 const facinet = new Facinet({
-  network: 'avalanche', // or 'ethereum', 'polygon'
+  network: 'base-sepolia', // SDK will use Base Sepolia API and facilitators
 });
 
 // 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('Processed by:', result.facilitator.name); // Facilitator name
+console.log('Facilitator ID:', result.facilitator.id);
+console.log('Network:', result.payment.network); // 'base-sepolia'
 ```
 
 ### Node.js (with Private Key)
@@ -55,10 +60,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', // SDK will use Polygon Amoy API and facilitators
 });
 
 // Make a payment
@@ -68,6 +73,7 @@ const result = await facinet.pay({
 });
 
 console.log('Transaction:', result.txHash);
+console.log('Facilitator:', result.facilitator.name);
 ```
 
 ### Quick One-Liner
@@ -75,39 +81,156 @@ console.log('Transaction:', result.txHash);
 ```typescript
 import { Facinet } from 'facinet';
 
-// Quick payment without creating instance
+// Quick payment on Ethereum Sepolia
 await Facinet.quickPay({
   amount: '1',
   recipient: '0xMerchantAddress',
   privateKey: process.env.PRIVATE_KEY,
+  network: 'ethereum-sepolia', // Uses Ethereum Sepolia facilitators
 });
 ```
 
-### Get Available Facilitators
+### Get Active Facilitators for a Network
 
 ```typescript
-const facinet = new Facinet();
+import { Facinet } from 'facinet';
 
-// Get all active facilitators
+// Initialize for a specific network
+const facinet = new Facinet({
+  network: 'base-sepolia', // Only gets facilitators for Base Sepolia
+});
+
+// Get all active facilitators for this network
 const facilitators = await facinet.getFacilitators();
-console.log(`${facilitators.length} active facilitators`);
+console.log(`${facilitators.length} active facilitators on Base Sepolia`);
+
+facilitators.forEach(fac => {
+  console.log(`- ${fac.name} (${fac.id})`);
+  console.log(`  Wallet: ${fac.facilitatorWallet}`);
+  console.log(`  Network: ${fac.network || 'N/A'}`);
+  console.log(`  Chain ID: ${fac.chainId || 'N/A'}`);
+  console.log(`  Status: ${fac.status}`);
+});
 
-// Get a random facilitator
+// Get a random active facilitator for this network
 const randomFacilitator = await facinet.selectRandomFacilitator();
 console.log('Selected:', randomFacilitator.name);
+console.log('Network:', randomFacilitator.network);
+```
+
+### Network-Specific Examples
+
+#### Avalanche Fuji
+
+```typescript
+const facinet = new Facinet({
+  network: 'avalanche-fuji', // Uses Avalanche Fuji facilitators
+});
+
+const result = await facinet.pay({
+  amount: '1',
+  recipient: '0xYourMerchantAddress',
+});
+
+console.log('Facilitator:', result.facilitator.name);
+console.log('Network:', result.payment.network); // 'avalanche-fuji'
+```
+
+#### Ethereum Sepolia
+
+```typescript
+const facinet = new Facinet({
+  network: 'ethereum-sepolia', // Uses Ethereum Sepolia facilitators
+});
+
+const facilitators = await facinet.getFacilitators();
+// Only returns facilitators registered for Ethereum Sepolia (Chain ID: 11155111)
+```
+
+#### Base Sepolia
+
+```typescript
+const facinet = new Facinet({
+  network: 'base-sepolia', // Uses Base Sepolia facilitators
+});
+
+const facilitator = await facinet.selectRandomFacilitator();
+// Only selects from facilitators registered for Base Sepolia (Chain ID: 84532)
+```
+
+#### Polygon Amoy
+
+```typescript
+const facinet = new Facinet({
+  network: 'polygon-amoy', // Uses Polygon Amoy facilitators
+});
+
+const result = await facinet.pay({
+  amount: '2',
+  recipient: '0xYourMerchantAddress',
+});
+```
+
+### 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})`);
+  console.log(`  Chain ID: ${chain.chainId}`);
+  console.log(`  Gas Token: ${chain.gasToken}`);
+  console.log(`  USDC Address: ${chain.usdcAddress}`);
+});
+
+// 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'
+  apiUrl?: string;       // Optional: Override API URL (auto-selected by network)
   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)
 }
 ```
 
+**Network-specific API URLs** (automatically selected):
+- `avalanche-fuji` → `https://x402-avalanche-chi.vercel.app`
+- `ethereum-sepolia` → `https://x402-ethereum-chi.vercel.app`
+- `base-sepolia` → `https://x402-base-chi.vercel.app`
+- `polygon-amoy` → `https://x402-polygon-chi.vercel.app`
+
+**Legacy aliases** are supported for backwards compatibility:
+- `'avalanche'` → `'avalanche-fuji'`
+- `'ethereum'` → `'ethereum-sepolia'`
+- `'polygon'` → `'polygon-amoy'`
+- `'base'` → `'base-sepolia'`
+
+### Facilitator Filtering
+
+The SDK automatically filters facilitators by:
+
+1. **Status**: Only `'active'` facilitators are selected
+2. **Network**: Only facilitators registered for the selected network
+3. **Chain ID**: Only facilitators matching the chain ID
+
+```typescript
+const facinet = new Facinet({ network: 'base-sepolia' });
+
+// This will only return facilitators that are:
+// - Status: 'active'
+// - Network: 'base-sepolia' OR Chain ID: 84532
+const facilitators = await facinet.getFacilitators();
+```
+
 ### TypeScript Support
 
 Facinet is written in TypeScript and includes full type definitions:
@@ -117,17 +240,24 @@ import type {
   FacinetConfig,
   PaymentParams,
   PaymentResult,
-  Facilitator
+  Facilitator,
+  ChainConfig
 } from 'facinet';
 
 const config: FacinetConfig = {
-  network: 'avalanche',
+  network: 'base-sepolia',
 };
 
 const params: PaymentParams = {
   amount: '1',
   recipient: '0x...',
 };
+
+// PaymentResult includes facilitator information
+const result: PaymentResult = await facinet.pay(params);
+console.log(result.facilitator.name); // Facilitator name
+console.log(result.facilitator.id);   // Facilitator ID
+console.log(result.facilitator.wallet); // Facilitator wallet address
 ```
 
 ### React Example
@@ -139,11 +269,13 @@ import { Facinet } from 'facinet';
 function PaymentButton() {
   const [loading, setLoading] = useState(false);
   const [txHash, setTxHash] = useState('');
+  const [facilitatorName, setFacilitatorName] = 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',
@@ -151,7 +283,8 @@ function PaymentButton() {
       });
 
       setTxHash(result.txHash);
-      alert('Payment successful!');
+      setFacilitatorName(result.facilitator.name);
+      alert(`Payment successful! Processed by ${result.facilitator.name}`);
     } catch (error) {
       console.error('Payment failed:', error);
       alert('Payment failed');
@@ -166,9 +299,11 @@ function PaymentButton() {
         {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>
+        <div>
+          <p>Transaction: {txHash.slice(0, 10)}...</p>
+          <p>Facilitator: {facilitatorName}</p>
+          <p>Network: {network}</p>
+        </div>
       )}
     </div>
   );
@@ -177,13 +312,31 @@ function PaymentButton() {
 
 ### How SDK Payments Work
 
-1. **Initialize SDK** - Create Facinet instance with your config
-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
+1. **Initialize SDK** - Create Facinet instance with your network choice
+2. **Network Detection** - SDK automatically uses the correct API URL for your network
+3. **Active Facilitator Selection** - SDK picks a random **active** facilitator **for your network**
+4. **Sign Authorization** - User signs ERC-3009 authorization (gasless!)
+5. **Facilitator Executes** - Selected facilitator submits transaction and pays gas
+6. **Payment Complete** - USDC transferred to YOUR merchant address
+
+### Error Handling
 
-**Key Point:** The `recipient` you specify in `pay()` is where YOU receive payment. The SDK automatically handles facilitator selection and gas payment.
+```typescript
+try {
+  const facinet = new Facinet({ network: 'base-sepolia' });
+  const result = await facinet.pay({
+    amount: '1',
+    recipient: '0xYourMerchantAddress',
+  });
+} catch (error) {
+  if (error.message.includes('No active facilitators available')) {
+    console.error('No active facilitators found for Base Sepolia');
+    console.error('Please check that facilitators are registered for this network');
+  } else {
+    console.error('Payment failed:', error.message);
+  }
+}
+```
 
 ## CLI Usage
 
@@ -195,145 +348,50 @@ 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 Fuji (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
-
-### 3. List Active Facilitators
-
-```bash
-facinet facilitator list
-```
-
-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...
+# Pay on Base Sepolia (uses Base Sepolia facilitators)
+facinet pay --amount 1 --to 0xRecipientAddress --chain base
 
-# 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).
+# Pay on Polygon Amoy (uses Polygon Amoy facilitators)
+facinet pay --amount 1 --to 0xRecipientAddress --chain polygon
 
-**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...
+# Pay on Ethereum Sepolia (uses Ethereum Sepolia facilitators)
+facinet pay --amount 1 --to 0xRecipientAddress --chain ethereum
 ```
 
-**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
+# List all active facilitators (for the configured network)
 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
+# The output shows:
+# - Facilitator name
+# - Facilitator ID
+# - Wallet address
+# - Status (active/inactive/needs_funding)
+# - Network (if available)
+# - Chain ID (if available)
+# - Total payments processed
+```
 
-**Example:**
+### 4. Check Facilitator Status
 
 ```bash
-facinet facilitator status fac_NdIk4EytdaIYHRK1
+facinet facilitator status fac_xyz123
 ```
 
-#### `facinet facilitator balance <id>`
-
-Check the AVAX gas balance of a facilitator.
-
-**Arguments:**
-- `<id>` - Facilitator ID
-
-**Options:**
-- `-u, --url <url>` - API URL
-
-**Example:**
+### 5. Check Facilitator Balance
 
 ```bash
-facinet facilitator balance fac_NdIk4EytdaIYHRK1
+facinet facilitator balance fac_xyz123
 ```
 
----
-
 ## Configuration
 
 Facinet stores configuration in `~/.facinet/config.json`:
@@ -343,31 +401,38 @@ 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
+**Note**: The `apiUrl` is automatically set based on the `network` parameter. You can override it if needed.
 
 ## How It Works
 
-1. **Random Selection** - CLI picks a random active facilitator from the network
+### Network-Specific Facilitator Selection
+
+1. **Network Selection** - You specify a network (e.g., `'base-sepolia'`)
+2. **API URL Selection** - SDK automatically uses the correct API endpoint for that network
+3. **Facilitator Filtering** - SDK fetches facilitators and filters by:
+   - Status: Must be `'active'`
+   - Network: Must match your selected network (if facilitator has `network` property)
+   - Chain ID: Must match your chain ID (if facilitator has `chainId` property)
+4. **Random Selection** - SDK picks a random facilitator from the filtered list
+5. **Payment Processing** - Selected facilitator processes your payment
+
+### Payment Flow
+
+1. **Random Selection** - SDK/CLI picks a random active facilitator from the **selected 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 +450,10 @@ facinet --help
 ### Project Structure
 
 ```
-facinet/
+facinet-sdk/
 ├── src/
 │   ├── sdk/
-│   │   ├── Facinet.ts    # Main SDK class
+│   │   ├── Facinet.ts    # Main SDK class (multichain with network-specific facilitators)
 │   │   └── types.ts      # TypeScript types
 │   ├── commands/
 │   │   ├── connect.ts    # Wallet connection
@@ -396,96 +461,35 @@ facinet/
 │   │   └── facilitator.ts # Facilitator management
 │   ├── utils/
 │   │   ├── config.ts     # Configuration management
-│   │   └── api.ts        # API client
+│   │   └── api.ts        # API client with network filtering
 │   ├── 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
-```
-
-### "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)
-# ...
+## What's New in v2.4.0
 
-# 3. Check status
-facinet facilitator status fac_abc123
+- **Network-Specific Facilitator Selection** - SDK automatically filters facilitators by network/chainId
+- **Network-Specific API URLs** - Each network uses its own API endpoint automatically
+- **Enhanced Facilitator Filtering** - Only active facilitators for the selected network are returned
+- **Better Error Messages** - Error messages now include network information
+- **Facilitator Name Display** - Facilitator names are properly displayed in all results
+- **Improved Documentation** - Comprehensive examples for each network
 
-# 4. Monitor balance
-facinet facilitator balance fac_abc123
-```
+## Previous Versions
 
-## Resources
+### v2.3.0
 
-- [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** ⚡