@alleyboss/micropay-solana-x402-paywall 2.3.0 → 3.0.0

package/README.md

@@ -1,6 +1,6 @@
 # @alleyboss/micropay-solana-x402-paywall
 
-> Production-ready Solana micropayments library implementing the x402 protocol.
+> Production-ready Solana micropayments library wrapper for the official x402 SDK.
 
 [![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)
@@ -8,158 +8,114 @@
 
 ## 🚀 What It Does
 
-Turn any content into paid content with **one-time micropayments** on Solana. No subscriptions, no recurring charges—just pay to unlock.
+Turn any content into paid content with **one-time micropayments** on Solana. fully compatible with the official [x402.org](https://x402.org) protocol.
+
+This library enhances the official SDK with features like **AI Agent Payments**, **Hybrid Sessions**, and **Express.js Middleware**.
 
 ```bash
-npm install @alleyboss/micropay-solana-x402-paywall @solana/web3.js
+npm install @alleyboss/micropay-solana-x402-paywall @x402/core @x402/svm @solana/web3.js
 ```
 
 ## ✨ Features
 
-| Feature | Description |
-|---------|-------------|
-| 💰 **SOL & USDC Payments** | Native SOL and SPL tokens (USDC, USDT) |
-| 🔐 **x402 Protocol** | Full HTTP 402 compliance with `X-Payment-Required` headers |
-| 🔑 **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 |
-
-## 📦 Quick Example
+| Feature | Description | Status |
+|---------|-------------|--------|
+| 💰 **SOL & USDC** | Native SOL and SPL tokens (USDC, USDT) | ✅ Verified by `@x402/svm` |
+| 🔐 **x402 Protocol** | Full HTTP 402 compliance | ✅ Powered by `@x402/core` |
+| 🔑 **JWT Sessions** | "Pay once, unlock for 24h" logic | ✅ Built-in (Hybrid Support) |
+| 🛡️ **Replay Protection** | Prevent double-spend / replay attacks | ✅ Managed by x402 Facilitator |
+| 🔌 **Express Integration** | Middleware for Express/Node.js | ✅ Built-in |
+| 💵 **Price Conversion** | USD↔SOL with multi-provider fallback | ✅ Built-in |
+| 🤖 **AI Agents** | Autonomous payment execution for agents | ✅ Built-in |
+| ⚡ **Priority Fees** | Compute unit price optimization | ✅ Supported (Agent Module) |
+| 📦 **Versioned Tx** | v0 Transaction support | ✅ Native (x402 SDK) |
+| 🌳 **Tree-Shakeable** | Modular exports | ✅ Built-in |
+
+## 📦 Quick Example (Express.js)
 
 ```typescript
-import { verifyPayment, createSession } from '@alleyboss/micropay-solana-x402-paywall';
-
-// Verify on-chain payment
-const result = await verifyPayment({
-  signature: 'tx...',
-  expectedRecipient: 'CreatorWallet',
-  expectedAmount: 10_000_000n, // 0.01 SOL
-  clientConfig: { network: 'mainnet-beta' },
+import express from 'express';
+import { x402ResourceServer } from '@x402/core/server';
+import { x402Middleware } from '@alleyboss/micropay-solana-x402-paywall/express';
+
+const app = express();
+// The x402ResourceServer handles protocol logic and facilitator communication
+const server = new x402ResourceServer({
+    facilitatorUrl: process.env.X402_FACILITATOR_URL,
+    serviceId: process.env.X402_SERVICE_ID,
 });
 
-// Create session for unlocked content
-if (result.valid) {
-  const { token } = await createSession(
-    result.from!,
-    'article-123',
-    { secret: process.env.SESSION_SECRET!, durationHours: 24 }
-  );
-}
+app.get('/premium', x402Middleware(server, {
+    accepts: {
+        scheme: 'exact',
+        amount: '1000000', // 0.001 SOL
+        network: 'solana-mainnet'
+    },
+    description: 'Premium Article'
+}), (req, res) => {
+    // Session token or payment proof is available
+    res.send('Thank you for your payment!');
+});
 ```
 
 ## 🔧 Modules
 
-9 tree-shakeable entry points for minimal bundle size:
+Import only what you need:
 
 ```typescript
-// Core verification
-import { verifyPayment, verifySPLPayment } from '@alleyboss/micropay-solana-x402-paywall/solana';
-
-// Session management  
-import { createSession, validateSession } from '@alleyboss/micropay-solana-x402-paywall/session';
-
-// x402 protocol
-import { buildPaymentRequirement } from '@alleyboss/micropay-solana-x402-paywall/x402';
+// Express Middleware
+import { x402Middleware } from '@alleyboss/micropay-solana-x402-paywall/express';
 
-// Express/Next.js middleware
-import { createExpressMiddleware, createPaywallMiddleware } from '@alleyboss/micropay-solana-x402-paywall/middleware';
+// AI Agent Payments
+import { executeAgentPayment } from '@alleyboss/micropay-solana-x402-paywall/agent';
 
-// Anti-replay signature store
-import { createMemoryStore, createRedisStore } from '@alleyboss/micropay-solana-x402-paywall/store';
+// Pricing Utilities
+import { getSolPrice, lamportsToUsd } from '@alleyboss/micropay-solana-x402-paywall/pricing';
 
-// Client-side helpers
-import { createPaymentFlow, buildSolanaPayUrl } from '@alleyboss/micropay-solana-x402-paywall/client';
-
-// Price conversion (4-provider rotation)
-import { getSolPrice, formatPriceDisplay, configurePricing } from '@alleyboss/micropay-solana-x402-paywall/pricing';
+// Session Management (Hybrid)
+import { createSession, validateSession } from '@alleyboss/micropay-solana-x402-paywall/session';
 
-// Retry utilities
-import { withRetry } from '@alleyboss/micropay-solana-x402-paywall/utils';
+// Client Helpers
+import { createPaymentFlow } from '@alleyboss/micropay-solana-x402-paywall/client';
 ```
 
-## 🔥 New in v2.2.0
-
-### x402 Protocol Compliance
+## 🤖 AI Agent Payments
 
-Full compliance with the [x402.org](https://x402.org) specification:
+Enable autonomous AI agents to pay for premium API access.
 
 ```typescript
-import { create402Response, parsePaymentHeader, encodePaymentRequirement } from '@alleyboss/micropay-solana-x402-paywall/x402';
-
-// Create 402 response with X-Payment-Required header
-const response = create402Response({
-  scheme: 'exact',
-  network: 'solana-mainnet',
-  maxAmountRequired: '10000000',
-  payTo: 'CreatorWallet...',
-  resource: '/api/premium',
-  description: 'Premium content access',
-  maxTimeoutSeconds: 300,
-  asset: 'native',
-});
-// Response includes: X-Payment-Required: <base64-encoded-requirement>
-
-// Parse X-Payment header from client
-const payload = parsePaymentHeader(request.headers.get('x-payment'));
-```
+import { executeAgentPayment } from '@alleyboss/micropay-solana-x402-paywall/agent';
+import { Keypair, Connection } from '@solana/web3.js';
 
-### Previous Features (v2.1.x)
+const agentKeypair = Keypair.fromSecretKey(/* ... */);
 
-- **RPC Fallback Support** — Automatic failover on primary RPC failure
-- **Priority Fees** — Compute budget instructions for landing transactions faster
-- **Versioned Transactions** — Full v0 transaction support with lookup tables
-- **TDD Test Suite** — Comprehensive tests with vitest
-
-```typescript
-// Priority fees
-import { createPriorityFeeInstructions } from '@alleyboss/micropay-solana-x402-paywall/solana';
-
-const instructions = createPriorityFeeInstructions({
-  enabled: true,
-  microLamports: 5000,
-  computeUnits: 200_000,
+const result = await executeAgentPayment({
+  connection: new Connection('https://api.mainnet-beta.solana.com'),
+  agentKeypair,
+  recipientAddress: 'CREATOR_WALLET',
+  amountLamports: 2_000_000n, 
+  priorityFee: { enabled: true, microLamports: 10000 }, // Priority Fees Supported
 });
 
-// Versioned transactions
-import { buildVersionedTransaction } from '@alleyboss/micropay-solana-x402-paywall/solana';
-
-const { transaction } = await buildVersionedTransaction({
-  connection,
-  payer: wallet.publicKey,
-  instructions: [transferIx],
-  priorityFee: { enabled: true },
-});
+if (result.success) {
+  console.log('Payment confirmed:', result.signature);
+}
 ```
 
-## 🛠️ RPC Providers
+## 📚 Documentation
 
-Works with any Solana RPC provider:
+For full documentation:
+- **Library Docs**: [solana-x402-paywall.vercel.app/docs](https://solana-x402-paywall.vercel.app/docs)
+- **Protocol Docs**: [x402.org](https://docs.x402.org)
 
-```typescript
-const config = {
-  network: 'mainnet-beta',
-  // 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'],
-};
-```
+## ☕ Support
 
-## 📚 Documentation
+If you find this library useful, you can buy me a coffee by sending some SOL to:
 
-**Full documentation, API reference, and examples:**
+**`7fPjNJaEHtepp1ZRr6GsaW1k22U1FupQtwuHUkTb6Xg9`**
 
-👉 **[solana-x402-paywall.vercel.app/docs](https://solana-x402-paywall.vercel.app/docs)**
+Your support helps maintain this project!
 
 ## 📄 License
 
 MIT © AlleyBoss
-

package/dist/agent/index.cjs

@@ -0,0 +1,358 @@
+'use strict';
+
+var web3_js = require('@solana/web3.js');
+var jose = require('jose');
+var uuid = require('uuid');
+
+// src/agent/agentPayment.ts
+var DEFAULT_COMPUTE_UNITS = 2e5;
+var DEFAULT_MICRO_LAMPORTS = 1e3;
+function createPriorityFeeInstructions(config = {}) {
+  const { enabled = false, microLamports, computeUnits } = config;
+  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 buildVersionedTransaction(config) {
+  const {
+    connection,
+    payer,
+    instructions,
+    priorityFee,
+    recentBlockhash
+  } = config;
+  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([]);
+  const transaction = new web3_js.VersionedTransaction(message);
+  return {
+    transaction,
+    blockhash,
+    lastValidBlockHeight
+  };
+}
+
+// src/agent/agentPayment.ts
+var WALLET_REGEX = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
+function isValidWalletAddress(address) {
+  if (!address || typeof address !== "string") return false;
+  return WALLET_REGEX.test(address);
+}
+async function executeAgentPayment(params) {
+  const {
+    connection,
+    agentKeypair,
+    recipientAddress,
+    amountLamports,
+    priorityFee,
+    confirmationTimeout = 6e4
+  } = params;
+  if (!isValidWalletAddress(recipientAddress)) {
+    return {
+      success: false,
+      error: "Invalid recipient address format"
+    };
+  }
+  if (amountLamports <= 0n) {
+    return {
+      success: false,
+      error: "Amount must be greater than 0"
+    };
+  }
+  try {
+    const recipientPubkey = new web3_js.PublicKey(recipientAddress);
+    const transferInstruction = web3_js.SystemProgram.transfer({
+      fromPubkey: agentKeypair.publicKey,
+      toPubkey: recipientPubkey,
+      lamports: amountLamports
+    });
+    const { transaction, lastValidBlockHeight } = await buildVersionedTransaction({
+      connection,
+      payer: agentKeypair.publicKey,
+      instructions: [transferInstruction],
+      priorityFee
+    });
+    transaction.sign([agentKeypair]);
+    const signature = await connection.sendTransaction(transaction, {
+      maxRetries: 3,
+      skipPreflight: false
+    });
+    const confirmationPromise = connection.confirmTransaction(
+      {
+        signature,
+        lastValidBlockHeight,
+        blockhash: transaction.message.recentBlockhash
+      },
+      "confirmed"
+    );
+    const timeoutPromise = new Promise((_, reject) => {
+      setTimeout(() => reject(new Error("Confirmation timeout")), confirmationTimeout);
+    });
+    const confirmation = await Promise.race([confirmationPromise, timeoutPromise]);
+    if (confirmation.value.err) {
+      return {
+        success: false,
+        signature,
+        error: "Transaction failed on-chain"
+      };
+    }
+    const txDetails = await connection.getTransaction(signature, {
+      commitment: "confirmed",
+      maxSupportedTransactionVersion: 0
+    });
+    return {
+      success: true,
+      signature,
+      confirmedAt: txDetails?.blockTime ?? Math.floor(Date.now() / 1e3),
+      slot: txDetails?.slot ?? confirmation.context.slot,
+      amountLamports,
+      amountSol: Number(amountLamports) / web3_js.LAMPORTS_PER_SOL
+    };
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : "Unknown error";
+    return {
+      success: false,
+      error: errorMessage
+    };
+  }
+}
+async function getAgentBalance(connection, agentKeypair) {
+  const balance = await connection.getBalance(agentKeypair.publicKey);
+  return {
+    balance: BigInt(balance),
+    balanceSol: balance / web3_js.LAMPORTS_PER_SOL
+  };
+}
+async function hasAgentSufficientBalance(connection, agentKeypair, requiredLamports) {
+  const { balance } = await getAgentBalance(connection, agentKeypair);
+  const totalRequired = requiredLamports + 10000n;
+  return {
+    sufficient: balance >= totalRequired,
+    balance,
+    required: totalRequired
+  };
+}
+function keypairFromBase58(base58Secret) {
+  const bytes = Buffer.from(base58Secret, "base64");
+  if (bytes.length !== 64) {
+    const parts = base58Secret.split(",").map((n) => parseInt(n.trim(), 10));
+    if (parts.length === 64) {
+      return web3_js.Keypair.fromSecretKey(Uint8Array.from(parts));
+    }
+    throw new Error("Invalid secret key format. Expected base58 string or comma-separated bytes.");
+  }
+  return web3_js.Keypair.fromSecretKey(bytes);
+}
+function generateAgentKeypair() {
+  const keypair = web3_js.Keypair.generate();
+  const secretBytes = Array.from(keypair.secretKey);
+  return {
+    keypair,
+    secretBase58: secretBytes.join(","),
+    // Comma-separated for easy storage
+    publicKey: keypair.publicKey.toBase58()
+  };
+}
+var MAX_CREDITS = 1e3;
+var MIN_SECRET_LENGTH = 32;
+function getSecretKey(secret) {
+  if (!secret || typeof secret !== "string") {
+    throw new Error("Session secret is required");
+  }
+  if (secret.length < MIN_SECRET_LENGTH) {
+    throw new Error(`Session secret must be at least ${MIN_SECRET_LENGTH} characters`);
+  }
+  return new TextEncoder().encode(secret);
+}
+function validateWalletAddress(address) {
+  if (!address || typeof address !== "string") return false;
+  const base58Regex = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
+  return base58Regex.test(address);
+}
+async function createCreditSession(walletAddress, purchaseId, config) {
+  if (!validateWalletAddress(walletAddress)) {
+    throw new Error("Invalid wallet address format");
+  }
+  if (config.initialCredits <= 0 || config.initialCredits > MAX_CREDITS) {
+    throw new Error(`Credits must be between 1 and ${MAX_CREDITS}`);
+  }
+  if (!config.durationHours || config.durationHours <= 0 || config.durationHours > 8760) {
+    throw new Error("Session duration must be between 1 and 8760 hours (1 year)");
+  }
+  const sessionId = uuid.v4();
+  const now = Math.floor(Date.now() / 1e3);
+  const expiresAt = now + config.durationHours * 3600;
+  const bundleExpiry = config.bundleExpiryHours ? now + config.bundleExpiryHours * 3600 : expiresAt;
+  const session = {
+    id: sessionId,
+    walletAddress,
+    unlockedArticles: [purchaseId],
+    siteWideUnlock: false,
+    createdAt: now,
+    expiresAt,
+    credits: config.initialCredits,
+    bundleExpiry,
+    bundleType: config.bundleType
+  };
+  const payload = {
+    sub: walletAddress,
+    sid: sessionId,
+    articles: session.unlockedArticles,
+    siteWide: false,
+    credits: config.initialCredits,
+    bundleExpiry,
+    bundleType: config.bundleType,
+    iat: now,
+    exp: expiresAt
+  };
+  const token = await new jose.SignJWT(payload).setProtectedHeader({ alg: "HS256" }).setIssuedAt().setExpirationTime(`${config.durationHours}h`).sign(getSecretKey(config.secret));
+  return { token, session };
+}
+async function validateCreditSession(token, secret) {
+  if (!token || typeof token !== "string") {
+    return { valid: false, reason: "Invalid token format" };
+  }
+  try {
+    const { payload } = await jose.jwtVerify(token, getSecretKey(secret));
+    const creditPayload = payload;
+    if (!creditPayload.sub || !creditPayload.sid || !creditPayload.exp) {
+      return { valid: false, reason: "Malformed session payload" };
+    }
+    const now = Math.floor(Date.now() / 1e3);
+    if (creditPayload.exp < now) {
+      return { valid: false, reason: "Session expired" };
+    }
+    if (creditPayload.bundleExpiry && creditPayload.bundleExpiry < now) {
+      return { valid: false, reason: "Bundle expired" };
+    }
+    if (!validateWalletAddress(creditPayload.sub)) {
+      return { valid: false, reason: "Invalid session data" };
+    }
+    const session = {
+      id: creditPayload.sid,
+      walletAddress: creditPayload.sub,
+      unlockedArticles: Array.isArray(creditPayload.articles) ? creditPayload.articles : [],
+      siteWideUnlock: Boolean(creditPayload.siteWide),
+      createdAt: creditPayload.iat ?? 0,
+      expiresAt: creditPayload.exp,
+      credits: creditPayload.credits ?? 0,
+      bundleExpiry: creditPayload.bundleExpiry,
+      bundleType: creditPayload.bundleType
+    };
+    return { valid: true, session };
+  } catch {
+    return { valid: false, reason: "Invalid session" };
+  }
+}
+async function useCredit(token, secret, creditsToUse = 1) {
+  if (creditsToUse <= 0) {
+    return { success: false, remainingCredits: 0, error: "Invalid credit amount" };
+  }
+  const validation = await validateCreditSession(token, secret);
+  if (!validation.valid || !validation.session) {
+    return {
+      success: false,
+      remainingCredits: 0,
+      error: validation.reason || "Invalid session"
+    };
+  }
+  const session = validation.session;
+  if (session.credits < creditsToUse) {
+    return {
+      success: false,
+      remainingCredits: session.credits,
+      error: "Insufficient credits"
+    };
+  }
+  const newCredits = session.credits - creditsToUse;
+  const payload = {
+    sub: session.walletAddress,
+    sid: session.id,
+    articles: session.unlockedArticles,
+    siteWide: session.siteWideUnlock,
+    credits: newCredits,
+    bundleExpiry: session.bundleExpiry,
+    bundleType: session.bundleType,
+    iat: session.createdAt,
+    exp: session.expiresAt
+  };
+  const newToken = await new jose.SignJWT(payload).setProtectedHeader({ alg: "HS256" }).sign(getSecretKey(secret));
+  return {
+    success: true,
+    remainingCredits: newCredits,
+    newToken
+  };
+}
+async function addCredits(token, secret, creditsToAdd) {
+  if (creditsToAdd <= 0 || creditsToAdd > MAX_CREDITS) {
+    return { success: false, error: "Invalid credit amount" };
+  }
+  const validation = await validateCreditSession(token, secret);
+  if (!validation.valid || !validation.session) {
+    return { success: false, error: validation.reason || "Invalid session" };
+  }
+  const session = validation.session;
+  const newCredits = Math.min(session.credits + creditsToAdd, MAX_CREDITS);
+  const payload = {
+    sub: session.walletAddress,
+    sid: session.id,
+    articles: session.unlockedArticles,
+    siteWide: session.siteWideUnlock,
+    credits: newCredits,
+    bundleExpiry: session.bundleExpiry,
+    bundleType: session.bundleType,
+    iat: session.createdAt,
+    exp: session.expiresAt
+  };
+  const newToken = await new jose.SignJWT(payload).setProtectedHeader({ alg: "HS256" }).sign(getSecretKey(secret));
+  return {
+    success: true,
+    newToken,
+    totalCredits: newCredits
+  };
+}
+async function getRemainingCredits(token, secret) {
+  const validation = await validateCreditSession(token, secret);
+  if (!validation.valid || !validation.session) {
+    return { credits: 0, valid: false };
+  }
+  return {
+    credits: validation.session.credits,
+    valid: true,
+    bundleExpiry: validation.session.bundleExpiry
+  };
+}
+
+exports.addCredits = addCredits;
+exports.createCreditSession = createCreditSession;
+exports.executeAgentPayment = executeAgentPayment;
+exports.generateAgentKeypair = generateAgentKeypair;
+exports.getAgentBalance = getAgentBalance;
+exports.getRemainingCredits = getRemainingCredits;
+exports.hasAgentSufficientBalance = hasAgentSufficientBalance;
+exports.keypairFromBase58 = keypairFromBase58;
+exports.useCredit = useCredit;
+exports.validateCreditSession = validateCreditSession;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map