@alleyboss/micropay-solana-x402-paywall 3.0.6 → 3.1.1

package/README.md

@@ -106,10 +106,65 @@ import { createSession, validateSession } from '@alleyboss/micropay-solana-x402-
 import { createPaymentFlow } from '@alleyboss/micropay-solana-x402-paywall/client';
 ```
 
+## 🛡️ Self-Sovereign Verification (New in v3.1)
+
+By default, the library uses the `x402.org` hosted facilitator for convenience. However, you can opt for **Self-Sovereign Mode** to verify payments directly against your own Solana RPC node, removing reliance on any external API services.
+
+```typescript
+// app/api/articles/[id]/route.ts
+const withMicropay = createX402Middleware({
+    walletAddress: 'YOUR_WALLET',
+    network: 'devnet',
+    price: '1000000',
+    // ⚡️ Enable Self-Sovereign Mode
+    // The library will verify transactions locally using this RPC connection.
+    rpcUrl: process.env.NEXT_PUBLIC_RPC_URL 
+});
+### 🛡️ Verification Flow (Self-Sovereign Mode)
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant App
+    participant Lib as x402 Lib
+    participant RPC as Solana RPC
+    
+    User->>App: Request Premium Content
+    App->>Lib: Create Payment Options
+    Lib-->>User: Return 402 + Payment Link
+    User->>RPC: Submit Transaction
+    User->>App: Send Receipt/Signature
+    App->>Lib: Verify Transaction
+    Lib->>RPC: Get Transaction Status (Local)
+    RPC-->>Lib: Confirmed
+    Lib-->>App: Valid Session Token
+    App-->>User: Unlock Content
+```
+
+### 🆚 Hosted vs. Self-Sovereign Mode
+
+| Feature | Hosted Mode (Default) | Self-Sovereign Mode |
+|---------|----------------------|---------------------|
+| **Verification** | Verified by x402.org | Verified by **You** (Local RPC) |
+| **Trust** | Trust x402 Facilitator | Trustless / Trust Your Node |
+| **Privacy** | Metadata sent to facilitator | No external data sharing |
+| **Setup** | Zero-config | Requires RPC URL |
+| **Best For** | Quick startups, MVPs | Production, High-Volume, Agents |
+
 ## 🤖 AI Agent Payments
 
 Enable autonomous AI agents to pay for premium API access.
 
+```mermaid
+flowchart LR
+    A[AI Agent] -->|1. Detects Paywall| B(Check Wallet)
+    B -->|2. Sufficient Balance?| C{Pay?}
+    C -- Yes --> D[Sign & Send Tx]
+    D --> E[Wait for Confirmation]
+    E -->|3. Success| F[Retry Request + Proof]
+    F --> G((Unlock Data))
+```
+
 ```typescript
 import { executeAgentPayment } from '@alleyboss/micropay-solana-x402-paywall/agent';
 import { Keypair, Connection } from '@solana/web3.js';
@@ -121,7 +176,7 @@ const result = await executeAgentPayment({
   agentKeypair,
   recipientAddress: 'CREATOR_WALLET',
   amountLamports: 2_000_000n, 
-  priorityFee: { enabled: true, microLamports: 10000 }, // Priority Fees Supported
+  priorityFee: { enabled: true, microLamports: 10000 },
 });
 
 if (result.success) {

package/dist/next/index.cjs

@@ -4,21 +4,161 @@ var next = require('@x402/next');
 var server = require('@x402/core/server');
 var http = require('@x402/core/http');
 var server$1 = require('@x402/svm/exact/server');
+var web3_js = require('@solana/web3.js');
+var types = require('@x402/core/types');
+
+// src/next/index.ts
+var LocalSvmFacilitator = class {
+  scheme = "exact";
+  caipFamily = "solana:*";
+  connection;
+  constructor(rpcUrl) {
+    this.connection = new web3_js.Connection(rpcUrl, "confirmed");
+  }
+  /**
+   * Get supported payment kinds
+   * Mocking the response of the /supported endpoint
+   */
+  async getSupported(extensionKeys = []) {
+    return {
+      kinds: [
+        {
+          x402Version: 1,
+          scheme: "exact",
+          network: "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
+          // Devnet
+          extra: {}
+        },
+        {
+          x402Version: 1,
+          scheme: "exact",
+          network: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
+          // Mainnet
+          extra: {}
+        }
+      ],
+      extensions: [],
+      signers: {
+        "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1": [],
+        "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp": []
+      }
+    };
+  }
+  /**
+   * Get mechanism-specific extra data
+   */
+  getExtra(network) {
+    return void 0;
+  }
+  /**
+   * Get default signers (not used for local verification usually, but required by interface)
+   */
+  getSigners(network) {
+    return [];
+  }
+  /**
+   * Verify a payment on-chain
+   */
+  async verify(payload, requirements) {
+    try {
+      const signature = payload.payload.signature;
+      if (!signature) {
+        return { isValid: false, invalidReason: "Missing signature in payment payload" };
+      }
+      const payTo = requirements.payTo;
+      const amountVal = requirements.amount || requirements.maxAmountRequired || "0";
+      const requiredAmount = BigInt(amountVal);
+      console.log(`[LocalSvmFacilitator] Verifying signature: ${signature}`);
+      console.log(`[LocalSvmFacilitator] Required Amount: ${requiredAmount}, PayTo: ${payTo}`);
+      const tx = await this.connection.getParsedTransaction(signature, {
+        maxSupportedTransactionVersion: 0,
+        commitment: "confirmed"
+      });
+      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;
+          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;
+            }
+          }
+        }
+      }
+      console.log(`[LocalSvmFacilitator] Total Paid Correctly: ${paidAmount}`);
+      if (paidAmount >= requiredAmount) {
+        console.log("[LocalSvmFacilitator] Verification SUCCESS");
+        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}`,
+        payer
+      };
+    } catch (error) {
+      console.error("[LocalSvmFacilitator] Verify error:", error);
+      throw new types.VerifyError(500, {
+        isValid: false,
+        invalidReason: error.message
+      });
+    }
+  }
+  /**
+   * Settle a payment (not applicable for direct chain verification, usually)
+   * But we must implement it. For 'exact', settlement is just verification + finality.
+   */
+  async settle(payload, requirements) {
+    const verifyResult = await this.verify(payload, requirements);
+    if (!verifyResult.isValid) {
+      throw new types.SettleError(400, {
+        success: false,
+        errorReason: verifyResult.invalidReason || "Verification failed",
+        transaction: payload.payload.signature,
+        network: requirements.network
+      });
+    }
+    return {
+      success: true,
+      payer: verifyResult.payer,
+      transaction: payload.payload.signature,
+      network: requirements.network
+    };
+  }
+};
 
 // src/next/index.ts
 function createX402Middleware(config) {
-  const facilitatorUrl = config.facilitatorUrl || "https://x402.org/facilitator";
-  const client = new http.HTTPFacilitatorClient({
-    url: facilitatorUrl
-  });
-  const server$2 = new server.x402ResourceServer(client);
-  server$1.registerExactSvmScheme(server$2, {});
+  let facilitatorClient;
+  if (config.rpcUrl) {
+    facilitatorClient = new LocalSvmFacilitator(config.rpcUrl);
+  } else {
+    const facilitatorUrl = config.facilitatorUrl || "https://x402.org/facilitator";
+    facilitatorClient = new http.HTTPFacilitatorClient({
+      url: facilitatorUrl
+    });
+  }
+  const server$2 = new server.x402ResourceServer(facilitatorClient);
+  server$1.registerExactSvmScheme(server$2);
   return function withMicropay(handler, routeConfig) {
     const finalConfig = routeConfig || {
       accepts: {
         scheme: "exact",
         payTo: config.walletAddress,
-        maxAmountRequired: config.price?.toString() || "0",
+        amount: config.price?.toString() || "0",
         network: config.network === "mainnet-beta" ? "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp" : "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
         asset: "native"
       }

package/dist/next/index.d.cts

@@ -14,6 +14,8 @@ interface X402Config {
     price?: string | number;
     /** Network (mainnet-beta or devnet) */
     network?: 'mainnet-beta' | 'devnet';
+    /** RPC URL for local verification (optional, enables self-contained validation) */
+    rpcUrl?: string;
 }
 /**
  * Create a specialized Next.js middleware with Solana support pre-configured

package/dist/next/index.d.ts

@@ -14,6 +14,8 @@ interface X402Config {
     price?: string | number;
     /** Network (mainnet-beta or devnet) */
     network?: 'mainnet-beta' | 'devnet';
+    /** RPC URL for local verification (optional, enables self-contained validation) */
+    rpcUrl?: string;
 }
 /**
  * Create a specialized Next.js middleware with Solana support pre-configured

package/dist/next/index.js

@@ -3,21 +3,161 @@ import { x402ResourceServer } from '@x402/core/server';
 export { x402ResourceServer } from '@x402/core/server';
 import { HTTPFacilitatorClient } from '@x402/core/http';
 import { registerExactSvmScheme } from '@x402/svm/exact/server';
+import { Connection } from '@solana/web3.js';
+import { VerifyError, SettleError } from '@x402/core/types';
+
+// src/next/index.ts
+var LocalSvmFacilitator = class {
+  scheme = "exact";
+  caipFamily = "solana:*";
+  connection;
+  constructor(rpcUrl) {
+    this.connection = new Connection(rpcUrl, "confirmed");
+  }
+  /**
+   * Get supported payment kinds
+   * Mocking the response of the /supported endpoint
+   */
+  async getSupported(extensionKeys = []) {
+    return {
+      kinds: [
+        {
+          x402Version: 1,
+          scheme: "exact",
+          network: "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
+          // Devnet
+          extra: {}
+        },
+        {
+          x402Version: 1,
+          scheme: "exact",
+          network: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
+          // Mainnet
+          extra: {}
+        }
+      ],
+      extensions: [],
+      signers: {
+        "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1": [],
+        "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp": []
+      }
+    };
+  }
+  /**
+   * Get mechanism-specific extra data
+   */
+  getExtra(network) {
+    return void 0;
+  }
+  /**
+   * Get default signers (not used for local verification usually, but required by interface)
+   */
+  getSigners(network) {
+    return [];
+  }
+  /**
+   * Verify a payment on-chain
+   */
+  async verify(payload, requirements) {
+    try {
+      const signature = payload.payload.signature;
+      if (!signature) {
+        return { isValid: false, invalidReason: "Missing signature in payment payload" };
+      }
+      const payTo = requirements.payTo;
+      const amountVal = requirements.amount || requirements.maxAmountRequired || "0";
+      const requiredAmount = BigInt(amountVal);
+      console.log(`[LocalSvmFacilitator] Verifying signature: ${signature}`);
+      console.log(`[LocalSvmFacilitator] Required Amount: ${requiredAmount}, PayTo: ${payTo}`);
+      const tx = await this.connection.getParsedTransaction(signature, {
+        maxSupportedTransactionVersion: 0,
+        commitment: "confirmed"
+      });
+      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;
+          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;
+            }
+          }
+        }
+      }
+      console.log(`[LocalSvmFacilitator] Total Paid Correctly: ${paidAmount}`);
+      if (paidAmount >= requiredAmount) {
+        console.log("[LocalSvmFacilitator] Verification SUCCESS");
+        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}`,
+        payer
+      };
+    } catch (error) {
+      console.error("[LocalSvmFacilitator] Verify error:", error);
+      throw new VerifyError(500, {
+        isValid: false,
+        invalidReason: error.message
+      });
+    }
+  }
+  /**
+   * Settle a payment (not applicable for direct chain verification, usually)
+   * But we must implement it. For 'exact', settlement is just verification + finality.
+   */
+  async settle(payload, requirements) {
+    const verifyResult = await this.verify(payload, requirements);
+    if (!verifyResult.isValid) {
+      throw new SettleError(400, {
+        success: false,
+        errorReason: verifyResult.invalidReason || "Verification failed",
+        transaction: payload.payload.signature,
+        network: requirements.network
+      });
+    }
+    return {
+      success: true,
+      payer: verifyResult.payer,
+      transaction: payload.payload.signature,
+      network: requirements.network
+    };
+  }
+};
 
 // src/next/index.ts
 function createX402Middleware(config) {
-  const facilitatorUrl = config.facilitatorUrl || "https://x402.org/facilitator";
-  const client = new HTTPFacilitatorClient({
-    url: facilitatorUrl
-  });
-  const server = new x402ResourceServer(client);
-  registerExactSvmScheme(server, {});
+  let facilitatorClient;
+  if (config.rpcUrl) {
+    facilitatorClient = new LocalSvmFacilitator(config.rpcUrl);
+  } else {
+    const facilitatorUrl = config.facilitatorUrl || "https://x402.org/facilitator";
+    facilitatorClient = new HTTPFacilitatorClient({
+      url: facilitatorUrl
+    });
+  }
+  const server = new x402ResourceServer(facilitatorClient);
+  registerExactSvmScheme(server);
   return function withMicropay(handler, routeConfig) {
     const finalConfig = routeConfig || {
       accepts: {
         scheme: "exact",
         payTo: config.walletAddress,
-        maxAmountRequired: config.price?.toString() || "0",
+        amount: config.price?.toString() || "0",
         network: config.network === "mainnet-beta" ? "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp" : "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
         asset: "native"
       }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@alleyboss/micropay-solana-x402-paywall",
-    "version": "3.0.6",
+    "version": "3.1.1",
     "description": "Production-ready Solana micropayments library wrapper for official x402 SDK",
     "author": "AlleyBoss",
     "license": "MIT",