@alleyboss/micropay-solana-x402-paywall 2.0.2 → 2.1.0

package/README.md

@@ -21,10 +21,13 @@ npm install @alleyboss/micropay-solana-x402-paywall @solana/web3.js
 | 💰 **SOL & USDC Payments** | Native SOL and SPL tokens (USDC, USDT) |
 | 🔐 **x402 Protocol** | HTTP 402 Payment Required standard |
 | 🔑 **JWT Sessions** | Secure unlock tracking with anti-replay |
-| �️ **Signature Store** | Prevent double-spend at app layer |
+| 🛡️ **Signature Store** | Prevent double-spend at app layer |
 | 🔌 **Express & Next.js** | Zero-boilerplate middleware |
-| � **Price Conversion** | USD↔SOL with multi-provider fallback |
+| 💵 **Price Conversion** | USD↔SOL with multi-provider fallback |
 | 🌳 **Tree-Shakeable** | Import only what you need |
+| 🔄 **RPC Fallback** | Automatic failover on RPC errors |
+| ⚡ **Priority Fees** | Land transactions faster |
+| 📦 **Versioned Tx** | Full v0 transaction support |
 
 ## 📦 Quick Example
 
@@ -79,20 +82,44 @@ import { getSolPrice, formatPriceDisplay, configurePricing } from '@alleyboss/mi
 import { withRetry } from '@alleyboss/micropay-solana-x402-paywall/utils';
 ```
 
-## 🔥 New in v2.0
+## 🔥 New in v2.1.0
 
-- **SPL Token Support** — USDC, USDT, custom tokens
-- **Multi-Provider Pricing** — CoinCap → Binance → CoinGecko → Kraken fallback
-- **Custom Price API** — `configurePricing({ customProvider: yourFn })`
-- **Express Middleware** — Works with Express, Fastify, Polka
-- **Signature Store** — Memory & Redis adapters for anti-replay
-- **Client Helpers** — Solana Pay URLs for QR codes
+- **RPC Fallback Support** — Automatic failover on primary RPC failure (configurable, default: off)
+- **Priority Fees** — Compute budget instructions for landing transactions faster (configurable, default: off)
+- **Versioned Transactions** — Full v0 transaction support with lookup tables
+- **TDD Test Suite** — Comprehensive tests with vitest (must pass before npm publish)
 
-## 📚 Documentation
+```typescript
+// RPC Fallback configuration
+const config = {
+  network: 'mainnet-beta',
+  rpcUrl: 'https://primary-rpc.com',
+  enableFallback: true, // default: false
+  fallbackRpcUrls: [
+    'https://fallback1.com',
+    'https://fallback2.com',
+  ],
+};
 
-**Full documentation, API reference, and examples:**
+// Priority fees
+import { createPriorityFeeInstructions, estimatePriorityFee } from '@alleyboss/micropay-solana-x402-paywall/solana';
 
-👉 **[solana-x402-paywall.vercel.app/docs](https://solana-x402-paywall.vercel.app/docs)**
+const instructions = createPriorityFeeInstructions({
+  enabled: true,
+  microLamports: 5000,
+  computeUnits: 200_000,
+});
+
+// Versioned transactions
+import { buildVersionedTransaction } from '@alleyboss/micropay-solana-x402-paywall/solana';
+
+const { transaction } = await buildVersionedTransaction({
+  connection,
+  payer: wallet.publicKey,
+  instructions: [transferIx],
+  priorityFee: { enabled: true },
+});
+```
 
 ## 🛠️ RPC Providers
 
@@ -105,9 +132,19 @@ const config = {
   tatumApiKey: 'your-key',
   // Or custom (Helius, QuickNode, etc.)
   rpcUrl: 'https://your-rpc.com',
+  // Optional: enable fallback
+  enableFallback: true,
+  fallbackRpcUrls: ['https://backup.rpc.com'],
 };
 ```
 
+## 📚 Documentation
+
+**Full documentation, API reference, and examples:**
+
+👉 **[solana-x402-paywall.vercel.app/docs](https://solana-x402-paywall.vercel.app/docs)**
+
 ## 📄 License
 
 MIT © AlleyBoss
+

package/dist/client-Blkcv17a.d.cts

@@ -0,0 +1,63 @@
+import { Connection } from '@solana/web3.js';
+import { S as SolanaNetwork } from './payment-CTxdtqmc.cjs';
+
+/** Configuration for Solana client */
+interface SolanaClientConfig {
+    /** Network to connect to */
+    network: SolanaNetwork;
+    /** Custom RPC URL (optional) */
+    rpcUrl?: string;
+    /** Tatum.io API key for RPC (optional) */
+    tatumApiKey?: string;
+    /** Enable RPC fallback on errors (default: false) */
+    enableFallback?: boolean;
+    /** Fallback RPC URLs to try on primary failure (optional) */
+    fallbackRpcUrls?: string[];
+}
+/** RPC connection with fallback support */
+interface RpcConnectionWithFallback {
+    /** Primary connection */
+    connection: Connection;
+    /** Fallback connections (if configured) */
+    fallbacks: Connection[];
+    /** Whether fallback is enabled */
+    fallbackEnabled: boolean;
+}
+/**
+ * Get or create a Solana connection
+ * Uses singleton pattern with network-aware caching
+ */
+declare function getConnection(config: SolanaClientConfig): Connection;
+/**
+ * Get connection with fallback support
+ * Returns both primary and fallback connections for manual failover
+ */
+declare function getConnectionWithFallback(config: SolanaClientConfig): RpcConnectionWithFallback;
+/**
+ * Execute an RPC call with automatic fallback on failure
+ * Only used when fallback is enabled in config
+ *
+ * @example
+ * ```typescript
+ * const balance = await withFallback(
+ *   config,
+ *   (conn) => conn.getBalance(publicKey)
+ * );
+ * ```
+ */
+declare function withFallback<T>(config: SolanaClientConfig, operation: (connection: Connection) => Promise<T>): Promise<T>;
+/**
+ * Reset the cached connection
+ * Useful for testing or network switching
+ */
+declare function resetConnection(): void;
+/**
+ * Check if network is mainnet
+ */
+declare function isMainnet(network: SolanaNetwork): boolean;
+/**
+ * Convert Solana network to x402 network identifier
+ */
+declare function toX402Network(network: SolanaNetwork): 'solana-devnet' | 'solana-mainnet';
+
+export { type RpcConnectionWithFallback as R, type SolanaClientConfig as S, getConnectionWithFallback as a, getConnection as g, isMainnet as i, resetConnection as r, toX402Network as t, withFallback as w };

package/dist/client-xhJSoeOH.d.ts

@@ -0,0 +1,63 @@
+import { Connection } from '@solana/web3.js';
+import { S as SolanaNetwork } from './payment-CTxdtqmc.js';
+
+/** Configuration for Solana client */
+interface SolanaClientConfig {
+    /** Network to connect to */
+    network: SolanaNetwork;
+    /** Custom RPC URL (optional) */
+    rpcUrl?: string;
+    /** Tatum.io API key for RPC (optional) */
+    tatumApiKey?: string;
+    /** Enable RPC fallback on errors (default: false) */
+    enableFallback?: boolean;
+    /** Fallback RPC URLs to try on primary failure (optional) */
+    fallbackRpcUrls?: string[];
+}
+/** RPC connection with fallback support */
+interface RpcConnectionWithFallback {
+    /** Primary connection */
+    connection: Connection;
+    /** Fallback connections (if configured) */
+    fallbacks: Connection[];
+    /** Whether fallback is enabled */
+    fallbackEnabled: boolean;
+}
+/**
+ * Get or create a Solana connection
+ * Uses singleton pattern with network-aware caching
+ */
+declare function getConnection(config: SolanaClientConfig): Connection;
+/**
+ * Get connection with fallback support
+ * Returns both primary and fallback connections for manual failover
+ */
+declare function getConnectionWithFallback(config: SolanaClientConfig): RpcConnectionWithFallback;
+/**
+ * Execute an RPC call with automatic fallback on failure
+ * Only used when fallback is enabled in config
+ *
+ * @example
+ * ```typescript
+ * const balance = await withFallback(
+ *   config,
+ *   (conn) => conn.getBalance(publicKey)
+ * );
+ * ```
+ */
+declare function withFallback<T>(config: SolanaClientConfig, operation: (connection: Connection) => Promise<T>): Promise<T>;
+/**
+ * Reset the cached connection
+ * Useful for testing or network switching
+ */
+declare function resetConnection(): void;
+/**
+ * Check if network is mainnet
+ */
+declare function isMainnet(network: SolanaNetwork): boolean;
+/**
+ * Convert Solana network to x402 network identifier
+ */
+declare function toX402Network(network: SolanaNetwork): 'solana-devnet' | 'solana-mainnet';
+
+export { type RpcConnectionWithFallback as R, type SolanaClientConfig as S, getConnectionWithFallback as a, getConnection as g, isMainnet as i, resetConnection as r, toX402Network as t, withFallback as w };

package/dist/index.cjs

@@ -15,6 +15,8 @@ var TOKEN_MINTS = {
 };
 var cachedConnection = null;
 var cachedNetwork = null;
+var cachedFallbacks = [];
+var cachedFallbackEnabled = false;
 function buildRpcUrl(config2) {
   const { network, rpcUrl, tatumApiKey } = config2;
   if (rpcUrl) {
@@ -29,19 +31,65 @@ function buildRpcUrl(config2) {
   }
   return web3_js.clusterApiUrl(network);
 }
+function createConnection(rpcUrl) {
+  return new web3_js.Connection(rpcUrl, {
+    commitment: "confirmed",
+    confirmTransactionInitialTimeout: 6e4
+  });
+}
 function getConnection(config2) {
   const { network } = config2;
   if (cachedConnection && cachedNetwork === network) {
     return cachedConnection;
   }
   const rpcUrl = buildRpcUrl(config2);
-  cachedConnection = new web3_js.Connection(rpcUrl, {
-    commitment: "confirmed",
-    confirmTransactionInitialTimeout: 6e4
-  });
+  cachedConnection = createConnection(rpcUrl);
   cachedNetwork = network;
+  cachedFallbackEnabled = config2.enableFallback ?? false;
+  cachedFallbacks = [];
+  if (cachedFallbackEnabled && config2.fallbackRpcUrls?.length) {
+    cachedFallbacks = config2.fallbackRpcUrls.map(createConnection);
+  }
   return cachedConnection;
 }
+function getConnectionWithFallback(config2) {
+  const connection = getConnection(config2);
+  return {
+    connection,
+    fallbacks: cachedFallbacks,
+    fallbackEnabled: cachedFallbackEnabled
+  };
+}
+async function withFallback(config2, operation) {
+  const { connection, fallbacks, fallbackEnabled } = getConnectionWithFallback(config2);
+  try {
+    return await operation(connection);
+  } catch (error) {
+    if (!fallbackEnabled || fallbacks.length === 0) {
+      throw error;
+    }
+    if (!isRetryableError(error)) {
+      throw error;
+    }
+    for (let i = 0; i < fallbacks.length; i++) {
+      try {
+        return await operation(fallbacks[i]);
+      } catch (fallbackError) {
+        if (i === fallbacks.length - 1) {
+          throw fallbackError;
+        }
+      }
+    }
+    throw error;
+  }
+}
+function isRetryableError(error) {
+  if (error instanceof Error) {
+    const message = error.message.toLowerCase();
+    return message.includes("429") || message.includes("503") || message.includes("502") || message.includes("timeout") || message.includes("econnrefused") || message.includes("enotfound") || message.includes("rate limit");
+  }
+  return false;
+}
 function resetConnection() {
   cachedConnection = null;
   cachedNetwork = null;
@@ -398,6 +446,88 @@ async function verifySPLPayment(params) {
 function isNativeAsset(asset) {
   return asset === "native";
 }
+var DEFAULT_COMPUTE_UNITS = 2e5;
+var DEFAULT_MICRO_LAMPORTS = 1e3;
+function createPriorityFeeInstructions(config2 = {}) {
+  const { enabled = false, microLamports, computeUnits } = config2;
+  if (!enabled) {
+    return [];
+  }
+  const instructions = [];
+  const units = computeUnits ?? DEFAULT_COMPUTE_UNITS;
+  instructions.push(web3_js.ComputeBudgetProgram.setComputeUnitLimit({ units }));
+  const price = microLamports ?? DEFAULT_MICRO_LAMPORTS;
+  instructions.push(web3_js.ComputeBudgetProgram.setComputeUnitPrice({ microLamports: price }));
+  return instructions;
+}
+async function estimatePriorityFee(connection, accounts = []) {
+  try {
+    const fees = await connection.getRecentPrioritizationFees({
+      lockedWritableAccounts: accounts
+    });
+    if (fees.length === 0) {
+      return DEFAULT_MICRO_LAMPORTS;
+    }
+    const sortedFees = fees.map((f) => f.prioritizationFee).filter((f) => f > 0).sort((a, b) => a - b);
+    if (sortedFees.length === 0) {
+      return DEFAULT_MICRO_LAMPORTS;
+    }
+    const medianIndex = Math.floor(sortedFees.length / 2);
+    return sortedFees[medianIndex];
+  } catch {
+    return DEFAULT_MICRO_LAMPORTS;
+  }
+}
+function calculatePriorityFeeCost(microLamportsPerCU, computeUnits) {
+  return Math.ceil(microLamportsPerCU * computeUnits / 1e6);
+}
+async function buildVersionedTransaction(config2) {
+  const {
+    connection,
+    payer,
+    instructions,
+    lookupTables = [],
+    priorityFee,
+    recentBlockhash
+  } = config2;
+  const priorityIxs = createPriorityFeeInstructions(priorityFee);
+  const allInstructions = [...priorityIxs, ...instructions];
+  let blockhash;
+  let lastValidBlockHeight;
+  if (recentBlockhash) {
+    blockhash = recentBlockhash;
+    const slot = await connection.getSlot();
+    lastValidBlockHeight = slot + 150;
+  } else {
+    const latestBlockhash = await connection.getLatestBlockhash("confirmed");
+    blockhash = latestBlockhash.blockhash;
+    lastValidBlockHeight = latestBlockhash.lastValidBlockHeight;
+  }
+  const message = new web3_js.TransactionMessage({
+    payerKey: payer,
+    recentBlockhash: blockhash,
+    instructions: allInstructions
+  }).compileToV0Message(lookupTables);
+  const transaction = new web3_js.VersionedTransaction(message);
+  return {
+    transaction,
+    blockhash,
+    lastValidBlockHeight
+  };
+}
+async function fetchLookupTables(connection, addresses) {
+  const tables = [];
+  for (const address of addresses) {
+    const result = await connection.getAddressLookupTable(address);
+    if (result.value) {
+      tables.push(result.value);
+    }
+  }
+  return tables;
+}
+function isVersionedTransaction(tx) {
+  return tx instanceof web3_js.VersionedTransaction;
+}
 var MAX_ARTICLES_PER_SESSION = 100;
 var MIN_SECRET_LENGTH = 32;
 function getSecretKey(secret) {
@@ -1177,6 +1307,8 @@ exports.X402_HEADERS = X402_HEADERS;
 exports.addArticleToSession = addArticleToSession;
 exports.buildPaymentRequirement = buildPaymentRequirement;
 exports.buildSolanaPayUrl = buildSolanaPayUrl;
+exports.buildVersionedTransaction = buildVersionedTransaction;
+exports.calculatePriorityFeeCost = calculatePriorityFeeCost;
 exports.checkPaywallAccess = checkPaywallAccess;
 exports.clearPriceCache = clearPriceCache;
 exports.configurePricing = configurePricing;
@@ -1186,14 +1318,18 @@ exports.createMemoryStore = createMemoryStore;
 exports.createPaymentFlow = createPaymentFlow;
 exports.createPaymentReference = createPaymentReference;
 exports.createPaywallMiddleware = createPaywallMiddleware;
+exports.createPriorityFeeInstructions = createPriorityFeeInstructions;
 exports.createRedisStore = createRedisStore;
 exports.createSession = createSession;
 exports.decodePaymentRequired = decodePaymentRequired;
 exports.encodePaymentRequired = encodePaymentRequired;
 exports.encodePaymentResponse = encodePaymentResponse;
+exports.estimatePriorityFee = estimatePriorityFee;
+exports.fetchLookupTables = fetchLookupTables;
 exports.formatPriceDisplay = formatPriceDisplay;
 exports.formatPriceSync = formatPriceSync;
 exports.getConnection = getConnection;
+exports.getConnectionWithFallback = getConnectionWithFallback;
 exports.getProviders = getProviders;
 exports.getSolPrice = getSolPrice;
 exports.getTokenDecimals = getTokenDecimals;
@@ -1202,6 +1338,7 @@ exports.isArticleUnlocked = isArticleUnlocked;
 exports.isMainnet = isMainnet;
 exports.isNativeAsset = isNativeAsset;
 exports.isRetryableRPCError = isRetryableRPCError;
+exports.isVersionedTransaction = isVersionedTransaction;
 exports.lamportsToSol = lamportsToSol;
 exports.lamportsToUsd = lamportsToUsd;
 exports.parsePaymentHeader = parsePaymentHeader;
@@ -1215,6 +1352,7 @@ exports.verifyPayment = verifyPayment;
 exports.verifySPLPayment = verifySPLPayment;
 exports.verifyX402Payment = verifyX402Payment;
 exports.waitForConfirmation = waitForConfirmation;
+exports.withFallback = withFallback;
 exports.withPaywall = withPaywall;
 exports.withRetry = withRetry;
 //# sourceMappingURL=index.cjs.map