facinet 2.3.0 → 2.4.1

package/README.md

@@ -2,16 +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. Now with **multichain support** across 4 testnets.
+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**.
 
 ## Supported Chains
 
-| 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 |
+| 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
 
@@ -29,14 +29,18 @@ 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 - choose your chain
+// Initialize SDK for Base Sepolia network
 const facinet = new Facinet({
-  network: 'base-sepolia', // or 'avalanche-fuji', 'ethereum-sepolia', 'polygon-amoy'
+  network: 'base-sepolia', // SDK will use Base Sepolia API and facilitators
 });
 
 // Make a payment (MetaMask will prompt for signature)
@@ -46,8 +50,9 @@ const result = await facinet.pay({
 });
 
 console.log('Payment successful!', result.txHash);
-console.log('Processed by:', result.facilitator.name);
-console.log('Network:', result.payment.network);
+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)
@@ -58,7 +63,7 @@ import { Facinet } from 'facinet';
 // Initialize with private key on Polygon Amoy
 const facinet = new Facinet({
   privateKey: process.env.PRIVATE_KEY,
-  network: 'polygon-amoy',
+  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,27 +81,94 @@ console.log('Transaction:', result.txHash);
 ```typescript
 import { Facinet } from 'facinet';
 
-// Quick payment on any chain
+// Quick payment on Ethereum Sepolia
 await Facinet.quickPay({
   amount: '1',
   recipient: '0xMerchantAddress',
   privateKey: process.env.PRIVATE_KEY,
-  network: 'ethereum-sepolia',
+  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
@@ -106,7 +179,10 @@ 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}`);
+  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
@@ -119,18 +195,41 @@ console.log('Networks:', networks);
 
 ```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-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'`
+- `'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
 
@@ -153,6 +252,12 @@ 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
@@ -164,6 +269,7 @@ 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 () => {
@@ -177,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');
@@ -191,7 +298,13 @@ function PaymentButton() {
       <button onClick={handlePayment} disabled={loading}>
         {loading ? 'Processing...' : 'Pay 1 USDC'}
       </button>
-      {txHash && <p>Transaction: {txHash.slice(0, 10)}...</p>}
+      {txHash && (
+        <div>
+          <p>Transaction: {txHash.slice(0, 10)}...</p>
+          <p>Facilitator: {facilitatorName}</p>
+          <p>Network: {network}</p>
+        </div>
+      )}
     </div>
   );
 }
@@ -199,11 +312,31 @@ function PaymentButton() {
 
 ### How SDK Payments Work
 
-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
+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
+
+```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
 
@@ -218,23 +351,33 @@ facinet connect
 ### 2. Make a Payment
 
 ```bash
-# Pay on Avalanche (default)
+# Pay on Avalanche Fuji (default)
 facinet pay --amount 1 --to 0xRecipientAddress
 
-# Pay on Base Sepolia
+# Pay on Base Sepolia (uses Base Sepolia facilitators)
 facinet pay --amount 1 --to 0xRecipientAddress --chain base
 
-# Pay on Polygon Amoy
+# Pay on Polygon Amoy (uses Polygon Amoy facilitators)
 facinet pay --amount 1 --to 0xRecipientAddress --chain polygon
 
-# Pay on Ethereum Sepolia
+# Pay on Ethereum Sepolia (uses Ethereum Sepolia facilitators)
 facinet pay --amount 1 --to 0xRecipientAddress --chain ethereum
 ```
 
 ### 3. List Active Facilitators
 
 ```bash
+# List all active facilitators (for the configured network)
 facinet facilitator list
+
+# The output shows:
+# - Facilitator name
+# - Facilitator ID
+# - Wallet address
+# - Status (active/inactive/needs_funding)
+# - Network (if available)
+# - Chain ID (if available)
+# - Total payments processed
 ```
 
 ### 4. Check Facilitator Status
@@ -243,6 +386,12 @@ facinet facilitator list
 facinet facilitator status fac_xyz123
 ```
 
+### 5. Check Facilitator Balance
+
+```bash
+facinet facilitator balance fac_xyz123
+```
+
 ## Configuration
 
 Facinet stores configuration in `~/.facinet/config.json`:
@@ -256,9 +405,24 @@ Facinet stores configuration in `~/.facinet/config.json`:
 }
 ```
 
+**Note**: The `apiUrl` is automatically set based on the `network` parameter. You can override it if needed.
+
 ## How It Works
 
-1. **Random Selection** - SDK/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
@@ -289,7 +453,7 @@ facinet --help
 facinet-sdk/
 ├── src/
 │   ├── sdk/
-│   │   ├── Facinet.ts    # Main SDK class (multichain)
+│   │   ├── Facinet.ts    # Main SDK class (multichain with network-specific facilitators)
 │   │   └── types.ts      # TypeScript types
 │   ├── commands/
 │   │   ├── connect.ts    # Wallet connection
@@ -297,7 +461,7 @@ facinet-sdk/
 │   │   └── 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
@@ -307,7 +471,18 @@ facinet-sdk/
 └── README.md
 ```
 
-## What's New in v2.3.0
+## What's New in v2.4.0
+
+- **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
+
+## Previous Versions
+
+### v2.3.0
 
 - **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)

package/dist/browser.js

@@ -2715,13 +2715,26 @@ var FacinetSDK = (() => {
     "polygon": "polygon-amoy",
     "base": "base-sepolia"
   };
+  var NETWORK_API_URLS = {
+    "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"
+  };
   function resolveNetwork(network) {
     return NETWORK_ALIASES[network] || network;
   }
+  function getApiUrlForNetwork(network, customApiUrl) {
+    if (customApiUrl) {
+      return customApiUrl.replace(/\/$/, "");
+    }
+    const resolvedNetwork = resolveNetwork(network);
+    return NETWORK_API_URLS[resolvedNetwork] || NETWORK_API_URLS["avalanche-fuji"];
+  }
   var Facinet = class _Facinet {
     constructor(config = {}) {
-      const apiUrl = (config.apiUrl || "https://x402-avalanche-chi.vercel.app").replace(/\/$/, "");
       const resolvedNetwork = resolveNetwork(config.network || "avalanche-fuji");
+      const apiUrl = getApiUrlForNetwork(resolvedNetwork, config.apiUrl);
       this.config = {
         apiUrl,
         privateKey: config.privateKey || "",
@@ -2892,7 +2905,7 @@ var FacinetSDK = (() => {
           txHash: response.data.txHash,
           facilitator: {
             id: facilitator.id,
-            name: facilitator.name,
+            name: facilitator.name || `Facilitator ${facilitator.id.slice(0, 8)}`,
             wallet: facilitator.facilitatorWallet
           },
           payment: {
@@ -2911,29 +2924,56 @@ var FacinetSDK = (() => {
       }
     }
     /**
-     * Get all active facilitators
+     * Get all active facilitators for the current network
      */
     async getFacilitators() {
-      const response = await axios_default.get(
-        `${this.config.apiUrl}/api/facilitator/list`
-      );
-      if (response.data.success) {
-        return response.data.facilitators.filter(
-          (f) => f.status === "active"
+      try {
+        const response = await axios_default.get(
+          `${this.config.apiUrl}/api/facilitator/list`,
+          {
+            timeout: 1e4,
+            headers: {
+              "User-Agent": "Facinet-SDK/2.3.0"
+            }
+          }
+        );
+        if (response.data.success && Array.isArray(response.data.facilitators)) {
+          return response.data.facilitators.filter((f) => {
+            if (f.status !== "active") {
+              return false;
+            }
+            if (f.network) {
+              return f.network === this.config.network;
+            }
+            if (f.chainId !== void 0) {
+              return f.chainId === this.chain.chainId;
+            }
+            return true;
+          });
+        }
+        return [];
+      } catch (error) {
+        throw new Error(
+          `Failed to fetch facilitators for ${this.chain.displayName} (${this.config.network}): ${error.message || "Unknown error"}`
         );
       }
-      return [];
     }
     /**
-     * Select a random active facilitator
+     * Select a random active facilitator for the current network
      */
     async selectRandomFacilitator() {
       const facilitators = await this.getFacilitators();
       if (facilitators.length === 0) {
-        throw new Error("No active facilitators available");
+        throw new Error(
+          `No active facilitators available for ${this.chain.displayName} (${this.config.network}, Chain ID: ${this.chain.chainId}). Please check that facilitators are registered for this network. API URL: ${this.config.apiUrl}`
+        );
       }
       const randomIndex = Math.floor(Math.random() * facilitators.length);
-      return facilitators[randomIndex];
+      const selectedFacilitator = facilitators[randomIndex];
+      if (!selectedFacilitator.name) {
+        selectedFacilitator.name = `Facilitator ${selectedFacilitator.id.slice(0, 8)}`;
+      }
+      return selectedFacilitator;
     }
     /**
      * Quick payment helper (static method)