@alleyboss/micropay-solana-x402-paywall 3.2.2 → 3.3.1

package/dist/next/index.cjs

@@ -20,20 +20,48 @@ var LocalSvmFacilitator = class {
    * Get supported payment kinds
    * Mocking the response of the /supported endpoint
    */
-  // Network Constants - CAIP-2 format for x402 v2
+  /**
+   * Network Constants - CAIP-2 format for x402 v2
+   * These match the official Solana chain IDs used by x402 protocol
+   */
   NETWORKS = {
     DEVNET: "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
     MAINNET: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"
   };
-  // Dummy fee payer address (System Program) - not used in local verification
-  // but required by x402 protocol for supported kinds
+  /**
+   * DUMMY_FEE_PAYER Explanation (for auditors):
+   * 
+   * In a HOSTED facilitator (like x402.org), the `feePayer` field in the 
+   * SupportedResponse.extra specifies which address will pay transaction fees
+   * when the facilitator submits transactions on behalf of users.
+   * 
+   * In LOCAL/SELF-SOVEREIGN mode (this implementation):
+   * - The USER pays their own transaction fees directly
+   * - The facilitator NEVER submits transactions - it only VERIFIES them
+   * - Therefore, no fee payer address is actually used
+   * 
+   * However, the x402 protocol REQUIRES this field in the response schema.
+   * We use the System Program address (all 1s) as a placeholder because:
+   * 1. It's clearly not a real wallet (obvious placeholder)
+   * 2. It cannot receive funds or sign transactions
+   * 3. It signals to developers that fee paying is handled differently
+   * 
+   * SECURITY NOTE: This is NOT a security risk because:
+   * - The fee payer is never used in verify() or settle() methods
+   * - Users sign and pay for their own transactions
+   * - The address is just a protocol-required placeholder
+   * 
+   * @see https://docs.x402.org for protocol specification
+   */
   DUMMY_FEE_PAYER = "11111111111111111111111111111111";
   /**
    * Get supported payment kinds
    * Returns x402 v2 compatible response with CAIP-2 network identifiers
+   * 
+   * NOTE: The feePayer in extra.feePayer is a placeholder only.
+   * In self-sovereign mode, users pay their own transaction fees.
    */
   async getSupported(_extensionKeys = []) {
-    console.log("[LocalSvmFacilitator] getSupported called");
     const supported = {
       kinds: [
         {
@@ -51,10 +79,10 @@ var LocalSvmFacilitator = class {
       ],
       extensions: [],
       signers: {
+        // Placeholder - in self-sovereign mode, users are their own signers
         "solana:*": [this.DUMMY_FEE_PAYER]
       }
     };
-    console.log("[LocalSvmFacilitator] Returning supported:", JSON.stringify(supported));
     return supported;
   }
   /**
@@ -69,6 +97,10 @@ var LocalSvmFacilitator = class {
   getSigners(_network) {
     return [];
   }
+  /**
+   * Enable debug logging (disable in production)
+   */
+  debug = process.env.NODE_ENV === "development";
   /**
    * Verify a payment on-chain
    */
@@ -81,57 +113,89 @@ var LocalSvmFacilitator = class {
       const payTo = requirements.payTo;
       const amountVal = requirements.amount || requirements.maxAmountRequired || "0";
       const requiredAmount = BigInt(amountVal);
-      console.log(`[LocalSvmFacilitator] Verifying signature: ${signature}`);
-      console.log(`[LocalSvmFacilitator] Requirements - Amount: ${requiredAmount}, PayTo: ${payTo}`);
-      console.log(`[LocalSvmFacilitator] Full Requirements:`, JSON.stringify(requirements));
-      const tx = await this.connection.getParsedTransaction(signature, {
-        maxSupportedTransactionVersion: 0,
-        commitment: "confirmed"
-      });
+      if (this.debug) {
+        console.log(`[LocalSvmFacilitator] Verifying tx: ${signature.slice(0, 8)}...`);
+      }
+      const tx = await this.fetchTransactionWithRetry(signature, 3);
       if (!tx) {
-        console.error("[LocalSvmFacilitator] Transaction not found or not confirmed");
         return { isValid: false, invalidReason: "Transaction not found or not confirmed" };
       }
-      console.log("[LocalSvmFacilitator] Transaction found. Parsing instructions...");
       const instructions = tx.transaction.message.instructions;
       let paidAmount = 0n;
       let payer = void 0;
       for (const ix of instructions) {
         if ("program" in ix && ix.program === "system") {
           const parsed = ix.parsed;
-          console.log(`[LocalSvmFacilitator] Inspecting IX:`, JSON.stringify(parsed));
-          if (parsed.type === "transfer") {
-            const info = parsed.info;
-            console.log(`[LocalSvmFacilitator] Found transfer: ${info.lamports} lamports to ${info.destination}`);
-            if (info.destination === payTo) {
-              paidAmount += BigInt(info.lamports);
-              if (!payer) payer = info.source;
+          if (parsed?.type === "transfer" && parsed.info?.destination === payTo) {
+            paidAmount += BigInt(parsed.info.lamports);
+            if (!payer) payer = parsed.info.source;
+          }
+        }
+        if ("program" in ix && (ix.program === "spl-token" || ix.program === "spl-token-2022")) {
+          const parsed = ix.parsed;
+          if (parsed?.type === "transferChecked" || parsed?.type === "transfer") {
+            if (this.debug) {
+              console.log(`[LocalSvmFacilitator] Found SPL transfer`);
             }
           }
         }
       }
-      console.log(`[LocalSvmFacilitator] Total Paid Correctly: ${paidAmount}`);
       if (paidAmount >= requiredAmount) {
-        console.log("[LocalSvmFacilitator] Verification SUCCESS");
+        if (this.debug) {
+          console.log(`[LocalSvmFacilitator] Verification SUCCESS for tx: ${signature.slice(0, 8)}...`);
+        }
         return {
           isValid: true,
           payer: payer || tx.transaction.message.accountKeys[0].pubkey.toBase58()
         };
       }
-      console.error(`[LocalSvmFacilitator] Verification FAILED. Paid: ${paidAmount}, Required: ${requiredAmount}`);
       return {
         isValid: false,
-        invalidReason: `Insufficient payment. Required: ${requiredAmount}, Found: ${paidAmount}`,
+        invalidReason: "Insufficient payment amount",
         payer
       };
     } catch (error) {
-      console.error("[LocalSvmFacilitator] Verify error:", error);
+      const errorMessage = error instanceof Error ? error.message : "Unknown error";
+      if (this.debug) {
+        console.error("[LocalSvmFacilitator] Verify error:", errorMessage);
+      }
       throw new types.VerifyError(500, {
         isValid: false,
-        invalidReason: error.message
+        invalidReason: errorMessage
       });
     }
   }
+  /**
+   * Fetch transaction with exponential backoff retry
+   */
+  async fetchTransactionWithRetry(signature, maxRetries = 3) {
+    let lastError;
+    for (let attempt = 0; attempt < maxRetries; attempt++) {
+      try {
+        const tx = await this.connection.getParsedTransaction(signature, {
+          maxSupportedTransactionVersion: 0,
+          commitment: "confirmed"
+        });
+        if (tx) return tx;
+        if (attempt < maxRetries - 1) {
+          await this.sleep(Math.pow(2, attempt) * 1e3);
+        }
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error("RPC error");
+        if (attempt < maxRetries - 1) {
+          await this.sleep(Math.pow(2, attempt) * 1e3);
+        }
+      }
+    }
+    if (lastError) throw lastError;
+    return null;
+  }
+  /**
+   * Sleep helper
+   */
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
   /**
    * Settle a payment (not applicable for direct chain verification, usually)
    * But we must implement it. For 'exact', settlement is just verification + finality.
@@ -177,7 +241,6 @@ function createX402Middleware(config) {
         network: config.network === "mainnet-beta" ? "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp" : "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1"
       }
     };
-    console.log("[createX402Middleware] Final Config:", JSON.stringify(finalConfig));
     return next.withX402(handler, finalConfig, server$2);
   };
 }

package/dist/next/index.js

@@ -19,20 +19,48 @@ var LocalSvmFacilitator = class {
    * Get supported payment kinds
    * Mocking the response of the /supported endpoint
    */
-  // Network Constants - CAIP-2 format for x402 v2
+  /**
+   * Network Constants - CAIP-2 format for x402 v2
+   * These match the official Solana chain IDs used by x402 protocol
+   */
   NETWORKS = {
     DEVNET: "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
     MAINNET: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"
   };
-  // Dummy fee payer address (System Program) - not used in local verification
-  // but required by x402 protocol for supported kinds
+  /**
+   * DUMMY_FEE_PAYER Explanation (for auditors):
+   * 
+   * In a HOSTED facilitator (like x402.org), the `feePayer` field in the 
+   * SupportedResponse.extra specifies which address will pay transaction fees
+   * when the facilitator submits transactions on behalf of users.
+   * 
+   * In LOCAL/SELF-SOVEREIGN mode (this implementation):
+   * - The USER pays their own transaction fees directly
+   * - The facilitator NEVER submits transactions - it only VERIFIES them
+   * - Therefore, no fee payer address is actually used
+   * 
+   * However, the x402 protocol REQUIRES this field in the response schema.
+   * We use the System Program address (all 1s) as a placeholder because:
+   * 1. It's clearly not a real wallet (obvious placeholder)
+   * 2. It cannot receive funds or sign transactions
+   * 3. It signals to developers that fee paying is handled differently
+   * 
+   * SECURITY NOTE: This is NOT a security risk because:
+   * - The fee payer is never used in verify() or settle() methods
+   * - Users sign and pay for their own transactions
+   * - The address is just a protocol-required placeholder
+   * 
+   * @see https://docs.x402.org for protocol specification
+   */
   DUMMY_FEE_PAYER = "11111111111111111111111111111111";
   /**
    * Get supported payment kinds
    * Returns x402 v2 compatible response with CAIP-2 network identifiers
+   * 
+   * NOTE: The feePayer in extra.feePayer is a placeholder only.
+   * In self-sovereign mode, users pay their own transaction fees.
    */
   async getSupported(_extensionKeys = []) {
-    console.log("[LocalSvmFacilitator] getSupported called");
     const supported = {
       kinds: [
         {
@@ -50,10 +78,10 @@ var LocalSvmFacilitator = class {
       ],
       extensions: [],
       signers: {
+        // Placeholder - in self-sovereign mode, users are their own signers
         "solana:*": [this.DUMMY_FEE_PAYER]
       }
     };
-    console.log("[LocalSvmFacilitator] Returning supported:", JSON.stringify(supported));
     return supported;
   }
   /**
@@ -68,6 +96,10 @@ var LocalSvmFacilitator = class {
   getSigners(_network) {
     return [];
   }
+  /**
+   * Enable debug logging (disable in production)
+   */
+  debug = process.env.NODE_ENV === "development";
   /**
    * Verify a payment on-chain
    */
@@ -80,57 +112,89 @@ var LocalSvmFacilitator = class {
       const payTo = requirements.payTo;
       const amountVal = requirements.amount || requirements.maxAmountRequired || "0";
       const requiredAmount = BigInt(amountVal);
-      console.log(`[LocalSvmFacilitator] Verifying signature: ${signature}`);
-      console.log(`[LocalSvmFacilitator] Requirements - Amount: ${requiredAmount}, PayTo: ${payTo}`);
-      console.log(`[LocalSvmFacilitator] Full Requirements:`, JSON.stringify(requirements));
-      const tx = await this.connection.getParsedTransaction(signature, {
-        maxSupportedTransactionVersion: 0,
-        commitment: "confirmed"
-      });
+      if (this.debug) {
+        console.log(`[LocalSvmFacilitator] Verifying tx: ${signature.slice(0, 8)}...`);
+      }
+      const tx = await this.fetchTransactionWithRetry(signature, 3);
       if (!tx) {
-        console.error("[LocalSvmFacilitator] Transaction not found or not confirmed");
         return { isValid: false, invalidReason: "Transaction not found or not confirmed" };
       }
-      console.log("[LocalSvmFacilitator] Transaction found. Parsing instructions...");
       const instructions = tx.transaction.message.instructions;
       let paidAmount = 0n;
       let payer = void 0;
       for (const ix of instructions) {
         if ("program" in ix && ix.program === "system") {
           const parsed = ix.parsed;
-          console.log(`[LocalSvmFacilitator] Inspecting IX:`, JSON.stringify(parsed));
-          if (parsed.type === "transfer") {
-            const info = parsed.info;
-            console.log(`[LocalSvmFacilitator] Found transfer: ${info.lamports} lamports to ${info.destination}`);
-            if (info.destination === payTo) {
-              paidAmount += BigInt(info.lamports);
-              if (!payer) payer = info.source;
+          if (parsed?.type === "transfer" && parsed.info?.destination === payTo) {
+            paidAmount += BigInt(parsed.info.lamports);
+            if (!payer) payer = parsed.info.source;
+          }
+        }
+        if ("program" in ix && (ix.program === "spl-token" || ix.program === "spl-token-2022")) {
+          const parsed = ix.parsed;
+          if (parsed?.type === "transferChecked" || parsed?.type === "transfer") {
+            if (this.debug) {
+              console.log(`[LocalSvmFacilitator] Found SPL transfer`);
             }
           }
         }
       }
-      console.log(`[LocalSvmFacilitator] Total Paid Correctly: ${paidAmount}`);
       if (paidAmount >= requiredAmount) {
-        console.log("[LocalSvmFacilitator] Verification SUCCESS");
+        if (this.debug) {
+          console.log(`[LocalSvmFacilitator] Verification SUCCESS for tx: ${signature.slice(0, 8)}...`);
+        }
         return {
           isValid: true,
           payer: payer || tx.transaction.message.accountKeys[0].pubkey.toBase58()
         };
       }
-      console.error(`[LocalSvmFacilitator] Verification FAILED. Paid: ${paidAmount}, Required: ${requiredAmount}`);
       return {
         isValid: false,
-        invalidReason: `Insufficient payment. Required: ${requiredAmount}, Found: ${paidAmount}`,
+        invalidReason: "Insufficient payment amount",
         payer
       };
     } catch (error) {
-      console.error("[LocalSvmFacilitator] Verify error:", error);
+      const errorMessage = error instanceof Error ? error.message : "Unknown error";
+      if (this.debug) {
+        console.error("[LocalSvmFacilitator] Verify error:", errorMessage);
+      }
       throw new VerifyError(500, {
         isValid: false,
-        invalidReason: error.message
+        invalidReason: errorMessage
       });
     }
   }
+  /**
+   * Fetch transaction with exponential backoff retry
+   */
+  async fetchTransactionWithRetry(signature, maxRetries = 3) {
+    let lastError;
+    for (let attempt = 0; attempt < maxRetries; attempt++) {
+      try {
+        const tx = await this.connection.getParsedTransaction(signature, {
+          maxSupportedTransactionVersion: 0,
+          commitment: "confirmed"
+        });
+        if (tx) return tx;
+        if (attempt < maxRetries - 1) {
+          await this.sleep(Math.pow(2, attempt) * 1e3);
+        }
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error("RPC error");
+        if (attempt < maxRetries - 1) {
+          await this.sleep(Math.pow(2, attempt) * 1e3);
+        }
+      }
+    }
+    if (lastError) throw lastError;
+    return null;
+  }
+  /**
+   * Sleep helper
+   */
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
   /**
    * Settle a payment (not applicable for direct chain verification, usually)
    * But we must implement it. For 'exact', settlement is just verification + finality.
@@ -176,7 +240,6 @@ function createX402Middleware(config) {
         network: config.network === "mainnet-beta" ? "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp" : "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1"
       }
     };
-    console.log("[createX402Middleware] Final Config:", JSON.stringify(finalConfig));
     return withX402$1(handler, finalConfig, server);
   };
 }

package/dist/pricing/index.cjs

@@ -6,12 +6,10 @@ function lamportsToSol(lamports) {
 }
 
 // src/pricing/index.ts
-var cachedPrice = null;
-var config = {};
-var lastProviderIndex = -1;
+var priceCache = null;
+var currentConfig = {};
 function configurePricing(newConfig) {
-  config = { ...config, ...newConfig };
-  cachedPrice = null;
+  currentConfig = { ...currentConfig, ...newConfig };
 }
 var PROVIDERS = [
   {
@@ -51,56 +49,75 @@ async function fetchFromProvider(provider, timeout) {
     if (!price || price <= 0) {
       throw new Error("Invalid price");
     }
-    return price;
+    return { price, source: provider.name };
   } finally {
     clearTimeout(timeoutId);
   }
 }
+async function fetchPriceParallel(timeout) {
+  const promises = PROVIDERS.map(
+    (provider) => fetchFromProvider(provider, timeout).catch(() => null)
+  );
+  const results = await Promise.all(promises);
+  const validResult = results.find((r) => r !== null);
+  if (validResult) {
+    return validResult;
+  }
+  throw new Error("All providers failed");
+}
+async function fetchPriceSequential(timeout) {
+  for (const provider of PROVIDERS) {
+    try {
+      return await fetchFromProvider(provider, timeout);
+    } catch {
+      continue;
+    }
+  }
+  throw new Error("All providers failed");
+}
 async function getSolPrice() {
-  const cacheTTL = config.cacheTTL ?? 6e4;
-  const timeout = config.timeout ?? 5e3;
-  if (cachedPrice && Date.now() - cachedPrice.fetchedAt.getTime() < cacheTTL) {
-    return cachedPrice;
+  const cacheTTL = currentConfig.cacheTTL ?? 6e4;
+  const timeout = currentConfig.timeout ?? 3e3;
+  const useParallel = currentConfig.parallelFetch ?? true;
+  const now = Date.now();
+  if (priceCache && now - priceCache.timestamp < cacheTTL) {
+    return priceCache.data;
   }
-  if (config.customProvider) {
+  if (currentConfig.customProvider) {
     try {
-      const price = await config.customProvider();
+      const price = await currentConfig.customProvider();
       if (price > 0) {
-        cachedPrice = {
+        const data = {
           solPrice: price,
           fetchedAt: /* @__PURE__ */ new Date(),
           source: "custom"
         };
-        return cachedPrice;
+        priceCache = { data, timestamp: now };
+        return data;
       }
     } catch {
     }
   }
-  for (let i = 0; i < PROVIDERS.length; i++) {
-    const idx = (lastProviderIndex + 1 + i) % PROVIDERS.length;
-    const provider = PROVIDERS[idx];
-    try {
-      const price = await fetchFromProvider(provider, timeout);
-      lastProviderIndex = idx;
-      cachedPrice = {
-        solPrice: price,
-        fetchedAt: /* @__PURE__ */ new Date(),
-        source: provider.name
+  try {
+    const result = useParallel ? await fetchPriceParallel(timeout) : await fetchPriceSequential(timeout);
+    const data = {
+      solPrice: result.price,
+      fetchedAt: /* @__PURE__ */ new Date(),
+      source: result.source
+    };
+    priceCache = { data, timestamp: now };
+    return data;
+  } catch {
+    if (priceCache) {
+      return {
+        ...priceCache.data,
+        source: `${priceCache.data.source} (stale)`
       };
-      return cachedPrice;
-    } catch {
-      continue;
     }
+    throw new Error(
+      "Failed to fetch SOL price from all providers. Configure a custom provider or ensure network connectivity."
+    );
   }
-  if (cachedPrice) {
-    return {
-      ...cachedPrice,
-      source: `${cachedPrice.source} (stale)`
-    };
-  }
-  throw new Error(
-    "Failed to fetch SOL price from all providers. Configure a custom provider or ensure network connectivity."
-  );
 }
 async function lamportsToUsd(lamports) {
   const { solPrice } = await getSolPrice();
@@ -128,8 +145,7 @@ function formatPriceSync(lamports, solPrice) {
   };
 }
 function clearPriceCache() {
-  cachedPrice = null;
-  lastProviderIndex = -1;
+  priceCache = null;
 }
 function getProviders() {
   return PROVIDERS.map((p) => ({ name: p.name, url: p.url }));

package/dist/pricing/index.d.cts

@@ -23,8 +23,10 @@ interface PriceConfig {
     customProvider?: CustomPriceProvider;
     /** Cache TTL in milliseconds (default: 60000) */
     cacheTTL?: number;
-    /** Request timeout in milliseconds (default: 5000) */
+    /** Request timeout in milliseconds (default: 3000) */
     timeout?: number;
+    /** Use parallel fetching (default: true, faster but more network calls) */
+    parallelFetch?: boolean;
 }
 /**
  * Configure price fetching
@@ -39,19 +41,16 @@ interface PriceConfig {
  *   },
  * });
  *
- * // Or just adjust cache TTL
- * configurePricing({ cacheTTL: 30000 }); // 30 seconds
+ * // Or adjust settings
+ * configurePricing({ cacheTTL: 30000, parallelFetch: true });
  * ```
  */
 declare function configurePricing(newConfig: PriceConfig): void;
 /**
- * Get SOL price with multi-provider fallback
+ * Get SOL price with multi-provider support
  *
- * Provider rotation order:
- * 1. CoinCap (primary)
- * 2. Binance (backup #1)
- * 3. CoinGecko (backup #2)
- * 4. Kraken (backup #3)
+ * Default behavior: Parallel fetch (all providers race, fastest wins)
+ * This is faster and more reliable in serverless environments.
  *
  * @example
  * ```typescript

package/dist/pricing/index.d.ts

@@ -23,8 +23,10 @@ interface PriceConfig {
     customProvider?: CustomPriceProvider;
     /** Cache TTL in milliseconds (default: 60000) */
     cacheTTL?: number;
-    /** Request timeout in milliseconds (default: 5000) */
+    /** Request timeout in milliseconds (default: 3000) */
     timeout?: number;
+    /** Use parallel fetching (default: true, faster but more network calls) */
+    parallelFetch?: boolean;
 }
 /**
  * Configure price fetching
@@ -39,19 +41,16 @@ interface PriceConfig {
  *   },
  * });
  *
- * // Or just adjust cache TTL
- * configurePricing({ cacheTTL: 30000 }); // 30 seconds
+ * // Or adjust settings
+ * configurePricing({ cacheTTL: 30000, parallelFetch: true });
  * ```
  */
 declare function configurePricing(newConfig: PriceConfig): void;
 /**
- * Get SOL price with multi-provider fallback
+ * Get SOL price with multi-provider support
  *
- * Provider rotation order:
- * 1. CoinCap (primary)
- * 2. Binance (backup #1)
- * 3. CoinGecko (backup #2)
- * 4. Kraken (backup #3)
+ * Default behavior: Parallel fetch (all providers race, fastest wins)
+ * This is faster and more reliable in serverless environments.
  *
  * @example
  * ```typescript