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

package/README.md

@@ -1,165 +1,150 @@
 # @alleyboss/micropay-solana-x402-paywall
 
-> Production-ready Solana micropayments library implementing the x402 protocol with SPL token support.
+> Production-ready Solana micropayments library implementing the x402 protocol.
 
-[![npm version](https://img.shields.io/npm/v/@alleyboss/micropay-solana-x402-paywall)](https://www.npmjs.com/package/@alleyboss/micropay-solana-x402-paywall)
+[![npm](https://img.shields.io/npm/v/@alleyboss/micropay-solana-x402-paywall)](https://www.npmjs.com/package/@alleyboss/micropay-solana-x402-paywall)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Bundle Size](https://img.shields.io/badge/bundle-38KB-green)](https://bundlephobia.com/package/@alleyboss/micropay-solana-x402-paywall)
 
-## Features
+## 🚀 What It Does
 
-- 🔐 **x402 Protocol** — HTTP 402 Payment Required standard
-- ⚡ **Solana Native** — Fast, low-cost SOL & USDC micropayments
-- 🔑 **JWT Sessions** — Secure unlock tracking with anti-replay
-- 📦 **Framework Agnostic** — Express, Next.js, Fastify ready
-- 🌳 **Tree-shakeable** — Import only what you need (35KB full, 1-13KB per module)
-- 💰 **SPL Tokens** — USDC, USDT, and custom token support
-- 🔄 **Retry Logic** — Built-in resilience for RPC failures
-
-## Installation
+Turn any content into paid content with **one-time micropayments** on Solana. No subscriptions, no recurring charges—just pay to unlock.
 
 ```bash
 npm install @alleyboss/micropay-solana-x402-paywall @solana/web3.js
 ```
 
-## Quick Start
+## ✨ Features
+
+| Feature | Description |
+|---------|-------------|
+| 💰 **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 |
+| 🔌 **Express & Next.js** | Zero-boilerplate middleware |
+| 💵 **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 |
 
-### Verify a Payment (SOL or USDC)
+## 📦 Quick Example
 
 ```typescript
-import { verifyPayment, verifySPLPayment } from '@alleyboss/micropay-solana-x402-paywall';
+import { verifyPayment, createSession } from '@alleyboss/micropay-solana-x402-paywall';
 
-// SOL payment
+// Verify on-chain payment
 const result = await verifyPayment({
   signature: 'tx...',
   expectedRecipient: 'CreatorWallet',
   expectedAmount: 10_000_000n, // 0.01 SOL
-  clientConfig: { network: 'devnet' },
-});
-
-// USDC payment
-const usdcResult = await verifySPLPayment({
-  signature: 'tx...',
-  expectedRecipient: 'CreatorWallet',
-  expectedAmount: 1_000_000n, // 1 USDC
-  asset: 'usdc',
   clientConfig: { network: 'mainnet-beta' },
 });
-```
-
-### Express Middleware (Zero Boilerplate)
-
-```typescript
-import express from 'express';
-import { createExpressMiddleware } from '@alleyboss/micropay-solana-x402-paywall/middleware';
-
-const app = express();
-
-app.use('/api/premium', createExpressMiddleware({
-  sessionSecret: process.env.SESSION_SECRET!,
-  protectedPaths: ['/**'],
-}));
 
-app.get('/api/premium/content', (req, res) => {
-  res.json({ content: 'Premium!', wallet: req.session?.walletAddress });
-});
+// Create session for unlocked content
+if (result.valid) {
+  const { token } = await createSession(
+    result.from!,
+    'article-123',
+    { secret: process.env.SESSION_SECRET!, durationHours: 24 }
+  );
+}
 ```
 
-### Next.js Middleware
+## 🔧 Modules
+
+9 tree-shakeable entry points for minimal bundle size:
 
 ```typescript
-// middleware.ts
-import { createPaywallMiddleware } from '@alleyboss/micropay-solana-x402-paywall/middleware';
+// Core verification
+import { verifyPayment, verifySPLPayment } from '@alleyboss/micropay-solana-x402-paywall/solana';
 
-export const middleware = createPaywallMiddleware({
-  sessionSecret: process.env.SESSION_SECRET!,
-  protectedPaths: ['/api/premium/*', '/api/content/*'],
-});
+// Session management  
+import { createSession, validateSession } from '@alleyboss/micropay-solana-x402-paywall/session';
 
-export const config = { matcher: ['/api/premium/:path*'] };
-```
+// x402 protocol
+import { buildPaymentRequirement } from '@alleyboss/micropay-solana-x402-paywall/x402';
 
-### Prevent Signature Replay (Anti-Double-Spend)
+// Express/Next.js middleware
+import { createExpressMiddleware, createPaywallMiddleware } from '@alleyboss/micropay-solana-x402-paywall/middleware';
 
-```typescript
+// Anti-replay signature store
 import { createMemoryStore, createRedisStore } from '@alleyboss/micropay-solana-x402-paywall/store';
 
-// Development
-const store = createMemoryStore();
+// Client-side helpers
+import { createPaymentFlow, buildSolanaPayUrl } from '@alleyboss/micropay-solana-x402-paywall/client';
 
-// Production (with ioredis or node-redis)
-const store = createRedisStore({ client: redisClient });
+// Price conversion (4-provider rotation)
+import { getSolPrice, formatPriceDisplay, configurePricing } from '@alleyboss/micropay-solana-x402-paywall/pricing';
 
-// Check before verification
-if (await store.hasBeenUsed(signature)) {
-  throw new Error('Payment already used');
-}
-
-// Mark after successful verification
-await store.markAsUsed(signature, articleId, new Date(Date.now() + 86400000));
+// Retry utilities
+import { withRetry } from '@alleyboss/micropay-solana-x402-paywall/utils';
 ```
 
-### Client-Side Payment Flow
+## 🔥 New in v2.1.0
 
-```typescript
-import { createPaymentFlow, formatPriceDisplay } from '@alleyboss/micropay-solana-x402-paywall';
+- **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)
 
-const flow = createPaymentFlow({
+```typescript
+// RPC Fallback configuration
+const config = {
   network: 'mainnet-beta',
-  recipientWallet: 'CreatorWallet',
-  amount: 10_000_000n,
-});
-
-// Generate QR code for mobile wallets
-const qrUrl = flow.getSolanaPayUrl({ label: 'Unlock Article' });
-
-// Display price with USD equivalent
-const price = await formatPriceDisplay(10_000_000n);
-// "0.0100 SOL (~$1.50)"
-```
-
-## Module Exports
-
-Import only what you need for minimal bundle size:
+  rpcUrl: 'https://primary-rpc.com',
+  enableFallback: true, // default: false
+  fallbackRpcUrls: [
+    'https://fallback1.com',
+    'https://fallback2.com',
+  ],
+};
 
-| Import Path | Size | Functions |
-|-------------|------|-----------|
-| `@.../solana` | 13KB | `verifyPayment`, `verifySPLPayment`, `getConnection` |
-| `@.../session` | 4.5KB | `createSession`, `validateSession`, `isArticleUnlocked` |
-| `@.../x402` | 10KB | `buildPaymentRequirement`, `verifyX402Payment` |
-| `@.../middleware` | 8KB | `createExpressMiddleware`, `createPaywallMiddleware` |
-| `@.../store` | 2.6KB | `createMemoryStore`, `createRedisStore` |
-| `@.../client` | 3.3KB | `createPaymentFlow`, `buildSolanaPayUrl` |
-| `@.../pricing` | 2KB | `getSolPrice`, `formatPriceDisplay` |
-| `@.../utils` | 1.7KB | `withRetry`, `isRetryableRPCError` |
+// Priority fees
+import { createPriorityFeeInstructions, estimatePriorityFee } from '@alleyboss/micropay-solana-x402-paywall/solana';
 
-## TypeScript Support
+const instructions = createPriorityFeeInstructions({
+  enabled: true,
+  microLamports: 5000,
+  computeUnits: 200_000,
+});
 
-Full TypeScript with exported types:
+// Versioned transactions
+import { buildVersionedTransaction } from '@alleyboss/micropay-solana-x402-paywall/solana';
 
-```typescript
-import type {
-  PaymentRequirement,
-  PaymentAsset,
-  SessionData,
-  SignatureStore,
-  PaywallMiddlewareConfig,
-} from '@alleyboss/micropay-solana-x402-paywall';
+const { transaction } = await buildVersionedTransaction({
+  connection,
+  payer: wallet.publicKey,
+  instructions: [transferIx],
+  priorityFee: { enabled: true },
+});
 ```
 
-## RPC Configuration
+## 🛠️ RPC Providers
 
-Supports multiple RPC providers:
+Works with any Solana RPC provider:
 
 ```typescript
-const clientConfig = {
+const config = {
   network: 'mainnet-beta',
-  // Option 1: Tatum.io
-  tatumApiKey: 'your-api-key',
-  // Option 2: Custom RPC (Helius, QuickNode, etc.)
-  rpcUrl: 'https://your-rpc-endpoint.com',
+  // Tatum.io
+  tatumApiKey: 'your-key',
+  // Or custom (Helius, QuickNode, etc.)
+  rpcUrl: 'https://your-rpc.com',
+  // Optional: enable fallback
+  enableFallback: true,
+  fallbackRpcUrls: ['https://backup.rpc.com'],
 };
 ```
 
-## License
+## 📚 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