@paynodelabs/sdk-js 1.0.1 → 1.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PayNode Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,68 +1,84 @@
-# PayNode Node.js/TypeScript SDK
+# PayNode JavaScript SDK
 
-PayNode SDK 为 Node.js 应用提供轻量级、无感集成的支付网关。基于 **x402 (Payment Required)** 协议，使您的 API 能够直接对 AI Agent 收取 USDC 微支付。
+[![Official Documentation](https://img.shields.io/badge/Docs-docs.paynode.dev-00ff88?style=for-the-badge&logo=readthedocs)](https://docs.paynode.dev)
+[![NPM Version](https://img.shields.io/npm/v/@paynodelabs/sdk-js.svg?style=for-the-badge)](https://www.npmjs.com/package/@paynodelabs/sdk-js)
 
-## 📦 安装
+The official TypeScript/JavaScript SDK for the **PayNode Protocol**. PayNode is a stateless, non-custodial M2M payment gateway that standardizes the HTTP 402 "Payment Required" flow for AI Agents, settling instantly in USDC on Base L2.
+
+## 📖 Read the Docs
+
+**For complete installation guides, advanced usage, API references, and architecture details, please visit our official documentation:**
+👉 **[docs.paynode.dev](https://docs.paynode.dev)**
+
+## ⚡ Quick Start
+
+### Installation
 
 ```bash
-npm install @paynode/sdk
+npm install @paynodelabs/sdk-js ethers
 ```
 
-## 🚀 Express 集成示例
-
-只需几行代码，即可为现有 API 路由开启支付门禁。
+### Agent Client (Payer)
 
 ```typescript
-import express from 'express';
-import { x402_gate } from '@paynode/sdk';
-
-const app = express();
-
-// 为指定路由挂载 PayNode 支付网关
-app.use('/api/premium-service', x402_gate({
-  rpcUrl: "https://mainnet.base.org",
-  contractAddress: "0x...",               // PayNodeRouter 部署地址
-  merchantAddress: "0x...",               // 商家收款地址
-  chainId: 8453,                          // Base Mainnet
-  currency: "USDC",
-  price: "0.01",                          // 单次调用价格 (USDC)
-  tokenAddress: "0x8335..."               // USDC 代币合约地址
-}));
-
-app.get('/api/premium-service', (req, res) => {
-  res.json({ data: "This content is paid and verified on-chain." });
-});
-
-app.listen(3000);
+import { PayNodeAgentClient } from "@paynodelabs/sdk-js";
+
+const client = new PayNodeAgentClient("YOUR_AGENT_PRIVATE_KEY", ["https://mainnet.base.org", "https://rpc.ankr.com/base"]);
+
+async function main() {
+  // Automatically handles 402 challenges, pays USDC, and retries the request
+  const response = await client.requestGate("https://api.merchant.com/premium-data");
+  console.log(await response.text());
+}
+main();
 ```
 
-## 🏗️ 核心验证逻辑
+## 🚀 Run the Demo
 
-PayNode SDK 核心职责是对 Agent 提供的 `x-paynode-receipt` (Transaction Hash) 进行链上状态校验：
+The SDK includes a full merchant/agent demonstration in the `examples/` directory.
 
-1. **402 握手阶段:** 
-   - 当请求头中缺失 `x-paynode-receipt` 时，SDK 自动返回 `402 Payment Required`。
-   - 响应头中包含支付所需的全部元数据 (价格、收款地址、合约、ChainId、OrderId)。
-2. **链上验证阶段:**
-   - 接收到交易哈希后，SDK 通过 RPC 实时查询交易状态。
-   - 解析 Event Log，比对 `orderId`、`merchant`、`token` 和 `amount` 是否完全一致。
-   - **防重放 (Anti-Replay):** 建议结合本地缓存或数据库记录已核销的 Receipt。
+### 1. Setup Environment
+
+```bash
+cp .env.example .env
+# Edit .env with your private key and RPC URLs
+```
 
-## 🧪 开发与测试
+### 2. Run the Merchant Server (Express)
 
 ```bash
-# 进入 SDK 目录
-cd packages/sdk-js
+npx ts-node examples/express-server.ts
+```
+
+### 3. Run the Agent Client
 
-# 安装依赖
-npm install
+In another terminal:
 
-# 运行单元测试
-npm test
+```bash
+npx ts-node examples/agent-client.ts
 ```
 
-## 🔗 资源
+The demo will perform a full loop: `402 Handshake -> On-chain Payment -> 200 Verification`.
+
+---
+
+## 📦 Publishing to NPM
+
+To publish a new version of the SDK:
+
+1. **Build the project**:
+   ```bash
+   npm run build
+   ```
+2. **Login to NPM** (if not already):
+   ```bash
+   npm login
+   ```
+3. **Publish**:
+   ```bash
+   npm publish --access public
+   ```
+
+---
 
-- **目录位置:** `packages/sdk-js`
-- **主页:** [paynode.dev](https://paynode.dev)
-- **协议文档:** `/agentpay-docs/`
+_Built for the Autonomous AI Economy by PayNodeLabs._

package/dist/client.d.ts

@@ -4,14 +4,19 @@ export interface RequestOptions extends RequestInit {
 export declare class PayNodeAgentClient {
     private wallet;
     private provider;
+    private rpcUrls;
     private ERC20_ABI;
     private ROUTER_ABI;
-    constructor(privateKey: string, rpcUrl: string);
-    /**
-     * Executes a fetch request and automatically handles the 402 Payment loop if encountered.
-     */
+    constructor(privateKey: string, rpcUrls: string | string[]);
     requestGate(url: string, options?: RequestOptions): Promise<Response>;
     private handlePaymentAndRetry;
-    private executeChainPayment;
+    private executeStandardPay;
+    private executePermitPay;
+    signPermit(tokenAddr: string, spenderAddr: string, amount: bigint, deadlineSeconds?: number): Promise<{
+        deadline: number;
+        v: 27 | 28;
+        r: string;
+        s: string;
+    }>;
 }
 //# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,cAAe,SAAQ,WAAW;IACjD,IAAI,CAAC,EAAE,GAAG,CAAC;CACZ;AAED,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,QAAQ,CAAyB;IAEzC,OAAO,CAAC,SAAS,CAIf;IAEF,OAAO,CAAC,UAAU,CAEhB;gBAEU,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;IAK9C;;OAEG;IACG,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,QAAQ,CAAC;YAqBjE,qBAAqB;YA6BrB,mBAAmB;CAmClC"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,cAAe,SAAQ,WAAW;IACjD,IAAI,CAAC,EAAE,GAAG,CAAC;CACZ;AAED,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,QAAQ,CAA0B;IAC1C,OAAO,CAAC,OAAO,CAAW;IAE1B,OAAO,CAAC,SAAS,CAMf;IAEF,OAAO,CAAC,UAAU,CAGhB;gBAEU,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE;IAcpD,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,QAAQ,CAAC;YA0BjE,qBAAqB;YAwDrB,kBAAkB;YAelB,gBAAgB;IAwBxB,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,GAAE,MAAa;;;;;;CAwCxG"}

package/dist/client.js

@@ -2,24 +2,33 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PayNodeAgentClient = void 0;
 const ethers_1 = require("ethers");
+const errors_1 = require("./errors");
 class PayNodeAgentClient {
     wallet;
     provider;
+    rpcUrls;
     ERC20_ABI = [
         "function approve(address spender, uint256 value) public returns (bool)",
         "function allowance(address owner, address spender) public view returns (uint256)",
-        "function balanceOf(address account) public view returns (uint256)"
+        "function balanceOf(address account) public view returns (uint256)",
+        "function name() view returns (string)",
+        "function nonces(address owner) view returns (uint256)"
     ];
     ROUTER_ABI = [
-        "function pay(address token, address merchant, uint256 amount, bytes32 orderId) public"
+        "function pay(address token, address merchant, uint256 amount, bytes32 orderId) public",
+        "function payWithPermit(address payer, address token, address merchant, uint256 amount, bytes32 orderId, uint256 deadline, uint8 v, bytes32 r, bytes32 s) public"
     ];
-    constructor(privateKey, rpcUrl) {
-        this.provider = new ethers_1.ethers.JsonRpcProvider(rpcUrl);
+    constructor(privateKey, rpcUrls) {
+        this.rpcUrls = Array.isArray(rpcUrls) ? rpcUrls : [rpcUrls];
+        const configs = this.rpcUrls.map((url, index) => ({
+            provider: new ethers_1.ethers.JsonRpcProvider(url),
+            priority: index,
+            weight: 1,
+            stallTimeout: 3000
+        }));
+        this.provider = new ethers_1.ethers.FallbackProvider(configs);
         this.wallet = new ethers_1.ethers.Wallet(privateKey, this.provider);
     }
-    /**
-     * Executes a fetch request and automatically handles the 402 Payment loop if encountered.
-     */
     async requestGate(url, options = {}) {
         const fetchOptions = { ...options };
         if (options.json && !fetchOptions.body) {
@@ -29,12 +38,19 @@ class PayNodeAgentClient {
                 ...fetchOptions.headers
             };
         }
-        let response = await fetch(url, fetchOptions);
-        if (response.status === 402) {
-            console.log(`💡 [PayNode-JS] 402 Payment Required detected. Handling autonomous payment...`);
-            return await this.handlePaymentAndRetry(url, fetchOptions, response.headers);
+        try {
+            let response = await fetch(url, fetchOptions);
+            if (response.status === 402) {
+                console.log(`💡 [PayNode-JS] 402 Payment Required detected. Handling autonomous payment...`);
+                return await this.handlePaymentAndRetry(url, fetchOptions, response.headers);
+            }
+            return response;
+        }
+        catch (error) {
+            if (error instanceof errors_1.PayNodeException)
+                throw error;
+            throw new errors_1.PayNodeException(`Failed to connect to any provided RPC nodes.`, errors_1.ErrorCode.RPC_ERROR, error);
         }
-        return response;
     }
     async handlePaymentAndRetry(url, options, headers) {
         const contractAddr = headers.get('x-paynode-contract');
@@ -43,11 +59,37 @@ class PayNodeAgentClient {
         const tokenAddr = headers.get('x-paynode-token-address');
         const orderIdStr = headers.get('x-paynode-order-id');
         if (!contractAddr || !merchantAddr || !amountStr || !tokenAddr || !orderIdStr) {
-            throw new Error("Malformed 402 headers: missing PayNode metadata");
+            throw new errors_1.PayNodeException("Malformed 402 headers: missing metadata", errors_1.ErrorCode.INTERNAL_ERROR);
         }
         const amount = BigInt(amountStr);
-        const orderIdBytes = ethers_1.ethers.id(orderIdStr);
-        const txHash = await this.executeChainPayment(contractAddr, merchantAddr, tokenAddr, amount, orderIdBytes);
+        // v1.3 Constraint: Min payment protection
+        if (amount < 1000n) {
+            throw new errors_1.PayNodeException("Payment amount is below the protocol minimum (1000).", errors_1.ErrorCode.AMOUNT_TOO_LOW);
+        }
+        let txHash;
+        try {
+            const tokenContract = new ethers_1.ethers.Contract(tokenAddr, this.ERC20_ABI, this.wallet);
+            const [balance, allowance] = await Promise.all([
+                tokenContract.balanceOf(this.wallet.address),
+                tokenContract.allowance(this.wallet.address, contractAddr)
+            ]);
+            if (balance < amount) {
+                throw new errors_1.PayNodeException("Wallet lacks USDC or ETH for gas.", errors_1.ErrorCode.INSUFFICIENT_FUNDS);
+            }
+            // Protocol v1.3: Permit-First Execution
+            if (allowance >= amount) {
+                txHash = await this.executeStandardPay(contractAddr, tokenAddr, merchantAddr, amount, orderIdStr);
+            }
+            else {
+                console.log(`⚡ [PayNode-JS] Insufficient allowance. Attempting Permit-First payment...`);
+                txHash = await this.executePermitPay(contractAddr, tokenAddr, merchantAddr, amount, orderIdStr);
+            }
+        }
+        catch (error) {
+            if (error instanceof errors_1.PayNodeException)
+                throw error;
+            throw new errors_1.PayNodeException(`On-chain transaction reverted or failed.`, errors_1.ErrorCode.TRANSACTION_FAILED, error);
+        }
         console.log(`✅ [PayNode-JS] Payment confirmed on-chain: ${txHash}`);
         const retryOptions = {
             ...options,
@@ -59,29 +101,61 @@ class PayNodeAgentClient {
         };
         return await fetch(url, retryOptions);
     }
-    async executeChainPayment(contractAddr, merchantAddr, tokenAddr, amount, orderId) {
-        const tokenContract = new ethers_1.ethers.Contract(tokenAddr, this.ERC20_ABI, this.wallet);
-        // 1. Check Balance
-        const balance = await tokenContract.balanceOf(this.wallet.address);
-        if (balance < amount) {
-            throw new Error(`Insufficient USDC balance. Have: ${ethers_1.ethers.formatUnits(balance, 6)}, Need: ${ethers_1.ethers.formatUnits(amount, 6)}`);
-        }
-        // 2. Check and Handle Allowance
-        const currentAllowance = await tokenContract.allowance(this.wallet.address, contractAddr);
-        if (currentAllowance < amount) {
-            console.log(`🔐 [PayNode-JS] Allowance too low (${currentAllowance}). Granting Infinite Approval to Router...`);
-            const approveTx = await tokenContract.approve(contractAddr, ethers_1.ethers.MaxUint256);
-            await approveTx.wait();
-            console.log(`🔓 [PayNode-JS] Infinite Approval confirmed.`);
-        }
-        // 3. Execute Payment
-        const routerContract = new ethers_1.ethers.Contract(contractAddr, this.ROUTER_ABI, this.wallet);
-        // Use manually specified gas limit to avoid estimateGas issues with some RPCs
-        const payTx = await routerContract.pay(tokenAddr, merchantAddr, amount, orderId, {
-            gasLimit: 200000 // Safe overhead for Base
+    async executeStandardPay(contractAddr, tokenAddr, merchantAddr, amount, orderId) {
+        const router = new ethers_1.ethers.Contract(contractAddr, this.ROUTER_ABI, this.wallet);
+        const orderIdBytes = ethers_1.ethers.id(orderId);
+        const feeData = await this.provider.getFeeData();
+        const gasPrice = (feeData.gasPrice * 120n) / 100n; // GasPrice * 1.2
+        const tx = await router.pay(tokenAddr, merchantAddr, amount, orderIdBytes, {
+            gasPrice,
+            gasLimit: 200000
         });
-        const receipt = await payTx.wait();
+        const receipt = await tx.wait();
+        return receipt.hash;
+    }
+    async executePermitPay(contractAddr, tokenAddr, merchantAddr, amount, orderId) {
+        const sig = await this.signPermit(tokenAddr, contractAddr, amount);
+        const router = new ethers_1.ethers.Contract(contractAddr, this.ROUTER_ABI, this.wallet);
+        const orderIdBytes = ethers_1.ethers.id(orderId);
+        const feeData = await this.provider.getFeeData();
+        const gasPrice = (feeData.gasPrice * 120n) / 100n;
+        const tx = await router.payWithPermit(this.wallet.address, tokenAddr, merchantAddr, amount, orderIdBytes, sig.deadline, sig.v, sig.r, sig.s, { gasPrice, gasLimit: 300000 });
+        const receipt = await tx.wait();
         return receipt.hash;
     }
+    async signPermit(tokenAddr, spenderAddr, amount, deadlineSeconds = 3600) {
+        const deadline = Math.floor(Date.now() / 1000) + deadlineSeconds;
+        const token = new ethers_1.ethers.Contract(tokenAddr, this.ERC20_ABI, this.wallet);
+        const [name, nonce, network] = await Promise.all([
+            token.name(),
+            token.nonces(this.wallet.address),
+            this.provider.getNetwork()
+        ]);
+        const domain = {
+            name,
+            version: '1', // USDC on Base uses version 1
+            chainId: Number(network.chainId),
+            verifyingContract: tokenAddr
+        };
+        const types = {
+            Permit: [
+                { name: 'owner', type: 'address' },
+                { name: 'spender', type: 'address' },
+                { name: 'value', type: 'uint256' },
+                { name: 'nonce', type: 'uint256' },
+                { name: 'deadline', type: 'uint256' },
+            ]
+        };
+        const value = {
+            owner: this.wallet.address,
+            spender: spenderAddr,
+            value: amount,
+            nonce,
+            deadline
+        };
+        const signature = await this.wallet.signTypedData(domain, types, value);
+        const { v, r, s } = ethers_1.ethers.Signature.from(signature);
+        return { deadline, v, r, s };
+    }
 }
 exports.PayNodeAgentClient = PayNodeAgentClient;

package/dist/constants.d.ts

@@ -0,0 +1,12 @@
+/** Generated by scripts/sync-config.py */
+export declare const PAYNODE_ROUTER_ADDRESS = "0x92e20164FC457a2aC35f53D06268168e6352b200";
+export declare const PAYNODE_ROUTER_ADDRESS_SANDBOX = "0xB587Bc36aaCf65962eCd6Ba59e2DA76f2f575408";
+export declare const BASE_USDC_ADDRESS = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+export declare const BASE_USDC_ADDRESS_SANDBOX = "0xeAC1f2C7099CdaFfB91Aa3b8Ffd653Ef16935798";
+export declare const PROTOCOL_TREASURY = "0x598bF63F5449876efafa7b36b77Deb2070621C0E";
+export declare const PROTOCOL_FEE_BPS = 100;
+export declare const MIN_PAYMENT_AMOUNT: bigint;
+export declare const BASE_RPC_URLS: string[];
+export declare const BASE_RPC_URLS_SANDBOX: string[];
+export declare const ACCEPTED_TOKENS: Record<number, string[]>;
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,0CAA0C;AAC1C,eAAO,MAAM,sBAAsB,+CAA+C,CAAC;AACnF,eAAO,MAAM,8BAA8B,+CAA+C,CAAC;AAC3F,eAAO,MAAM,iBAAiB,+CAA+C,CAAC;AAC9E,eAAO,MAAM,yBAAyB,+CAA+C,CAAC;AACtF,eAAO,MAAM,iBAAiB,+CAA+C,CAAC;AAC9E,eAAO,MAAM,gBAAgB,MAAM,CAAC;AACpC,eAAO,MAAM,kBAAkB,QAAe,CAAC;AAE/C,eAAO,MAAM,aAAa,UAAmF,CAAC;AAC9G,eAAO,MAAM,qBAAqB,UAA0E,CAAC;AAE7G,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAGpD,CAAC"}

package/dist/constants.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ACCEPTED_TOKENS = exports.BASE_RPC_URLS_SANDBOX = exports.BASE_RPC_URLS = exports.MIN_PAYMENT_AMOUNT = exports.PROTOCOL_FEE_BPS = exports.PROTOCOL_TREASURY = exports.BASE_USDC_ADDRESS_SANDBOX = exports.BASE_USDC_ADDRESS = exports.PAYNODE_ROUTER_ADDRESS_SANDBOX = exports.PAYNODE_ROUTER_ADDRESS = void 0;
+/** Generated by scripts/sync-config.py */
+exports.PAYNODE_ROUTER_ADDRESS = "0x92e20164FC457a2aC35f53D06268168e6352b200";
+exports.PAYNODE_ROUTER_ADDRESS_SANDBOX = "0xB587Bc36aaCf65962eCd6Ba59e2DA76f2f575408";
+exports.BASE_USDC_ADDRESS = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+exports.BASE_USDC_ADDRESS_SANDBOX = "0xeAC1f2C7099CdaFfB91Aa3b8Ffd653Ef16935798";
+exports.PROTOCOL_TREASURY = "0x598bF63F5449876efafa7b36b77Deb2070621C0E";
+exports.PROTOCOL_FEE_BPS = 100;
+exports.MIN_PAYMENT_AMOUNT = BigInt(1000);
+exports.BASE_RPC_URLS = ["https://mainnet.base.org", "https://base.meowrpc.com", "https://1rpc.io/base"];
+exports.BASE_RPC_URLS_SANDBOX = ["https://sepolia.base.org", "https://base-sepolia-rpc.publicnode.com"];
+exports.ACCEPTED_TOKENS = {
+    8453: ["0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"],
+    84532: ["0xeAC1f2C7099CdaFfB91Aa3b8Ffd653Ef16935798"]
+};

package/dist/errors/index.d.ts

@@ -1,11 +1,22 @@
 export declare enum ErrorCode {
-    TRANSACTION_NOT_FOUND = "TRANSACTION_NOT_FOUND",
+    RPC_ERROR = "RPC_ERROR",
+    INSUFFICIENT_FUNDS = "INSUFFICIENT_FUNDS",
+    AMOUNT_TOO_LOW = "AMOUNT_TOO_LOW",
+    TOKEN_NOT_ACCEPTED = "TOKEN_NOT_ACCEPTED",
     TRANSACTION_FAILED = "TRANSACTION_FAILED",
+    DUPLICATE_TRANSACTION = "DUPLICATE_TRANSACTION",
+    INVALID_RECEIPT = "INVALID_RECEIPT",
+    INTERNAL_ERROR = "INTERNAL_ERROR",
+    TRANSACTION_NOT_FOUND = "TRANSACTION_NOT_FOUND",
     WRONG_CONTRACT = "WRONG_CONTRACT",
     ORDER_MISMATCH = "ORDER_MISMATCH",
-    INSUFFICIENT_FUNDS = "INSUFFICIENT_FUNDS",
     RECEIPT_ALREADY_USED = "RECEIPT_ALREADY_USED",
-    INVALID_RECEIPT = "INVALID_RECEIPT",
     MISSING_RECEIPT = "MISSING_RECEIPT"
 }
+export declare class PayNodeException extends Error {
+    message: string;
+    code: ErrorCode;
+    details?: any | undefined;
+    constructor(message: string, code: ErrorCode, details?: any | undefined);
+}
 //# sourceMappingURL=index.d.ts.map

package/dist/errors/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AAAA,oBAAY,SAAS;IACnB,qBAAqB,0BAA0B;IAC/C,kBAAkB,uBAAuB;IACzC,cAAc,mBAAmB;IACjC,cAAc,mBAAmB;IACjC,kBAAkB,uBAAuB;IACzC,oBAAoB,yBAAyB;IAC7C,eAAe,oBAAoB;IACnC,eAAe,oBAAoB;CACpC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AAAA,oBAAY,SAAS;IACnB,SAAS,cAAc;IACvB,kBAAkB,uBAAuB;IACzC,cAAc,mBAAmB;IACjC,kBAAkB,uBAAuB;IACzC,kBAAkB,uBAAuB;IACzC,qBAAqB,0BAA0B;IAC/C,eAAe,oBAAoB;IACnC,cAAc,mBAAmB;IAEjC,qBAAqB,0BAA0B;IAC/C,cAAc,mBAAmB;IACjC,cAAc,mBAAmB;IACjC,oBAAoB,yBAAyB;IAC7C,eAAe,oBAAoB;CACpC;AAED,qBAAa,gBAAiB,SAAQ,KAAK;IACtB,OAAO,EAAE,MAAM;IAAS,IAAI,EAAE,SAAS;IAAS,OAAO,CAAC,EAAE,GAAG;gBAA7D,OAAO,EAAE,MAAM,EAAS,IAAI,EAAE,SAAS,EAAS,OAAO,CAAC,EAAE,GAAG,YAAA;CAIjF"}

package/dist/errors/index.js

@@ -1,14 +1,33 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ErrorCode = void 0;
+exports.PayNodeException = exports.ErrorCode = void 0;
 var ErrorCode;
 (function (ErrorCode) {
-    ErrorCode["TRANSACTION_NOT_FOUND"] = "TRANSACTION_NOT_FOUND";
+    ErrorCode["RPC_ERROR"] = "RPC_ERROR";
+    ErrorCode["INSUFFICIENT_FUNDS"] = "INSUFFICIENT_FUNDS";
+    ErrorCode["AMOUNT_TOO_LOW"] = "AMOUNT_TOO_LOW";
+    ErrorCode["TOKEN_NOT_ACCEPTED"] = "TOKEN_NOT_ACCEPTED";
     ErrorCode["TRANSACTION_FAILED"] = "TRANSACTION_FAILED";
+    ErrorCode["DUPLICATE_TRANSACTION"] = "DUPLICATE_TRANSACTION";
+    ErrorCode["INVALID_RECEIPT"] = "INVALID_RECEIPT";
+    ErrorCode["INTERNAL_ERROR"] = "INTERNAL_ERROR";
+    // Verification specific
+    ErrorCode["TRANSACTION_NOT_FOUND"] = "TRANSACTION_NOT_FOUND";
     ErrorCode["WRONG_CONTRACT"] = "WRONG_CONTRACT";
     ErrorCode["ORDER_MISMATCH"] = "ORDER_MISMATCH";
-    ErrorCode["INSUFFICIENT_FUNDS"] = "INSUFFICIENT_FUNDS";
     ErrorCode["RECEIPT_ALREADY_USED"] = "RECEIPT_ALREADY_USED";
-    ErrorCode["INVALID_RECEIPT"] = "INVALID_RECEIPT";
     ErrorCode["MISSING_RECEIPT"] = "MISSING_RECEIPT";
 })(ErrorCode || (exports.ErrorCode = ErrorCode = {}));
+class PayNodeException extends Error {
+    message;
+    code;
+    details;
+    constructor(message, code, details) {
+        super(message);
+        this.message = message;
+        this.code = code;
+        this.details = details;
+        this.name = "PayNodeException";
+    }
+}
+exports.PayNodeException = PayNodeException;

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export * from './middleware/x402';
 export * from './utils/verifier';
 export * from './utils/idempotency';
+export * from './utils/webhook';
 export * from './client';
+export * from './errors';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC"}

package/dist/index.js

@@ -17,4 +17,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./middleware/x402"), exports);
 __exportStar(require("./utils/verifier"), exports);
 __exportStar(require("./utils/idempotency"), exports);
+__exportStar(require("./utils/webhook"), exports);
 __exportStar(require("./client"), exports);
+__exportStar(require("./errors"), exports);

package/dist/middleware/x402.d.ts

@@ -1,6 +1,16 @@
-import { NextFunction } from 'express';
-export interface PayNodeOptions {
-    [key: string]: any;
+import { Request, NextFunction } from 'express';
+import { IdempotencyStore } from '../utils/idempotency';
+export interface PayNodeMiddlewareOptions {
+    rpcUrls: string | string[];
+    chainId: number;
+    contractAddress: string;
+    merchantAddress: string;
+    tokenAddress: string;
+    currency: string;
+    price: string;
+    decimals: number;
+    store?: IdempotencyStore;
+    generateOrderId?: (req: Request | any) => string;
 }
-export declare const x402_gate: (options: PayNodeOptions) => (req: any, res: any, next: NextFunction) => Promise<any>;
+export declare const x402_gate: (options: PayNodeMiddlewareOptions) => (req: any, res: any, next: NextFunction) => Promise<any>;
 //# sourceMappingURL=x402.d.ts.map

package/dist/middleware/x402.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"x402.d.ts","sourceRoot":"","sources":["../../src/middleware/x402.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,YAAY,EAAE,MAAM,SAAS,CAAC;AAG1D,MAAM,WAAW,cAAc;IAAG,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CAAE;AAEvD,eAAO,MAAM,SAAS,GAAI,SAAS,cAAc,MACjC,KAAK,GAAG,EAAE,KAAK,GAAG,EAAE,MAAM,YAAY,iBA2BrD,CAAC"}
+{"version":3,"file":"x402.d.ts","sourceRoot":"","sources":["../../src/middleware/x402.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAY,YAAY,EAAE,MAAM,SAAS,CAAC;AAG1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAGxD,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,gBAAgB,CAAC;IACzB,eAAe,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,KAAK,MAAM,CAAC;CAClD;AAED,eAAO,MAAM,SAAS,GAAI,SAAS,wBAAwB,MAgB3C,KAAK,GAAG,EAAE,KAAK,GAAG,EAAE,MAAM,YAAY,iBAwDrD,CAAC"}

package/dist/middleware/x402.js

@@ -2,9 +2,24 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.x402_gate = void 0;
 const errors_1 = require("../errors");
+const verifier_1 = require("../utils/verifier");
+const ethers_1 = require("ethers");
 const x402_gate = (options) => {
+    const verifier = new verifier_1.PayNodeVerifier({
+        rpcUrls: options.rpcUrls,
+        chainId: options.chainId,
+        store: options.store
+    });
+    let rawAmount;
+    try {
+        rawAmount = (0, ethers_1.parseUnits)(options.price, options.decimals);
+    }
+    catch (e) {
+        rawAmount = BigInt(Math.floor(parseFloat(options.price) * (10 ** options.decimals)));
+    }
+    const defaultOrderIdGen = (req) => `agent_js_${Date.now()}`;
     return async (req, res, next) => {
-        // 兼容多种 Mock 形式
+        // Compatibility with different mock/real environments
         const getHeader = (name) => {
             if (req.header && typeof req.header === 'function')
                 return req.header(name);
@@ -12,22 +27,50 @@ const x402_gate = (options) => {
                 return req.headers[name.toLowerCase()] || req.headers[name];
             return null;
         };
-        const txHash = getHeader('X-PayNode-TxHash');
-        if (!txHash) {
-            if (res.set)
+        const receiptHash = getHeader('x-paynode-receipt') || getHeader('X-PayNode-TxHash');
+        let orderId = getHeader('x-paynode-order-id');
+        if (!orderId) {
+            orderId = (options.generateOrderId || defaultOrderIdGen)(req);
+        }
+        if (!receiptHash) {
+            if (res.set) {
                 res.set({
-                    'x-paynode-contract': options.payNodeContractAddress,
-                    'x-paynode-amount': '1000000',
-                    'x-paynode-currency': 'USDC'
+                    'x-paynode-contract': options.contractAddress,
+                    'x-paynode-merchant': options.merchantAddress,
+                    'x-paynode-amount': rawAmount.toString(),
+                    'x-paynode-currency': options.currency,
+                    'x-paynode-token-address': options.tokenAddress,
+                    'x-paynode-chain-id': options.chainId.toString(),
+                    'x-paynode-order-id': orderId
                 });
-            return res.status(402).json({ code: errors_1.ErrorCode.MISSING_RECEIPT });
+            }
+            return res.status(402).json({
+                error: "Payment Required",
+                code: errors_1.ErrorCode.MISSING_RECEIPT,
+                message: "Please pay to PayNode contract and provide 'x-paynode-receipt' header.",
+                amount: options.price,
+                currency: options.currency
+            });
+        }
+        // Phase 2: On-chain Verification
+        const result = await verifier.verifyPayment(receiptHash, {
+            merchantAddress: options.merchantAddress,
+            tokenAddress: options.tokenAddress,
+            amount: rawAmount,
+            orderId: orderId
+        });
+        if (result.isValid) {
+            // Expose to downstream handlers
+            req.paynode = { receiptHash, orderId };
+            return next();
         }
-        // 测试用例 3: 无效支付
-        if (txHash === 'invalid_tx_hash') {
-            return res.status(403).json({ code: errors_1.ErrorCode.INSUFFICIENT_FUNDS });
+        else {
+            return res.status(403).json({
+                error: "Forbidden",
+                code: result.error?.code || errors_1.ErrorCode.INVALID_RECEIPT,
+                message: result.error?.message || "Invalid receipt"
+            });
         }
-        // 测试用例 2: 有效支付
-        next();
     };
 };
 exports.x402_gate = x402_gate;

package/dist/utils/idempotency.d.ts

@@ -1,3 +1,4 @@
+import type { Redis } from 'ioredis';
 export interface IdempotencyStore {
     /**
      * Attempts to mark a transaction hash as used.
@@ -8,6 +9,7 @@ export interface IdempotencyStore {
 /**
  * Default implementation for MVP.
  * Uses a Map with expiration logic.
+ * @deprecated Use RedisIdempotencyStore for production environments.
  */
 export declare class MemoryIdempotencyStore implements IdempotencyStore {
     private cache;
@@ -15,4 +17,14 @@ export declare class MemoryIdempotencyStore implements IdempotencyStore {
     checkAndSet(txHash: string, ttlSeconds: number): Promise<boolean>;
     private cleanup;
 }
+/**
+ * Production-ready implementation using Redis.
+ * Uses `SET txHash 1 NX EX ttlSeconds` for atomic check-and-set.
+ */
+export declare class RedisIdempotencyStore implements IdempotencyStore {
+    private redis;
+    private prefix;
+    constructor(redisClient: Redis, prefix?: string);
+    checkAndSet(txHash: string, ttlSeconds: number): Promise<boolean>;
+}
 //# sourceMappingURL=idempotency.d.ts.map

package/dist/utils/idempotency.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"idempotency.d.ts","sourceRoot":"","sources":["../../src/utils/idempotency.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACnE;AAED;;;GAGG;AACH,qBAAa,sBAAuB,YAAW,gBAAgB;IAC7D,OAAO,CAAC,KAAK,CAAkC;;IAOzC,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAYvE,OAAO,CAAC,OAAO;CAQhB"}
+{"version":3,"file":"idempotency.d.ts","sourceRoot":"","sources":["../../src/utils/idempotency.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAErC,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACnE;AAED;;;;GAIG;AACH,qBAAa,sBAAuB,YAAW,gBAAgB;IAC7D,OAAO,CAAC,KAAK,CAAkC;;IAOzC,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAYvE,OAAO,CAAC,OAAO;CAQhB;AAED;;;GAGG;AACH,qBAAa,qBAAsB,YAAW,gBAAgB;IAC5D,OAAO,CAAC,KAAK,CAAQ;IACrB,OAAO,CAAC,MAAM,CAAS;gBAEX,WAAW,EAAE,KAAK,EAAE,MAAM,GAAE,MAAsB;IAKxD,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAKxE"}

package/dist/utils/idempotency.js

@@ -1,9 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MemoryIdempotencyStore = void 0;
+exports.RedisIdempotencyStore = exports.MemoryIdempotencyStore = void 0;
 /**
  * Default implementation for MVP.
  * Uses a Map with expiration logic.
+ * @deprecated Use RedisIdempotencyStore for production environments.
  */
 class MemoryIdempotencyStore {
     cache = new Map();
@@ -30,3 +31,21 @@ class MemoryIdempotencyStore {
     }
 }
 exports.MemoryIdempotencyStore = MemoryIdempotencyStore;
+/**
+ * Production-ready implementation using Redis.
+ * Uses `SET txHash 1 NX EX ttlSeconds` for atomic check-and-set.
+ */
+class RedisIdempotencyStore {
+    redis;
+    prefix;
+    constructor(redisClient, prefix = 'paynode:tx:') {
+        this.redis = redisClient;
+        this.prefix = prefix;
+    }
+    async checkAndSet(txHash, ttlSeconds) {
+        const key = `${this.prefix}${txHash}`;
+        const result = await this.redis.set(key, '1', 'EX', ttlSeconds, 'NX');
+        return result === 'OK';
+    }
+}
+exports.RedisIdempotencyStore = RedisIdempotencyStore;

package/dist/utils/verifier.d.ts

@@ -1,16 +1,35 @@
-import { ErrorCode } from '../errors';
+import { PayNodeException } from '../errors';
+import { IdempotencyStore } from './idempotency';
+/**
+ * Default accepted token addresses across supported chains.
+ * SDK will reject any payment involving a token NOT in this whitelist,
+ * preventing fake-token attacks at the verification layer.
+ */
+export declare const ACCEPTED_TOKENS: Record<string, string[]>;
+/** Minimum allowed payment amount to prevent dust exploits (1000 = 0.001 USDC) */
+export declare const MIN_PAYMENT_AMOUNT = 1000n;
+export interface PayNodeVerifierConfig {
+    rpcUrls: string | string[];
+    chainId?: number;
+    store?: IdempotencyStore;
+    /** Override the default accepted token whitelist. If provided, only these addresses are allowed. */
+    acceptedTokens?: string[];
+}
+export interface ExpectedPayment {
+    merchantAddress: string;
+    tokenAddress: string;
+    amount: string | number | bigint;
+    orderId?: string;
+}
 export declare class PayNodeVerifier {
-    private usedHashes;
-    constructor(config: any);
-    verifyPayment(txHash: string, expected: any): Promise<{
+    private provider;
+    private chainId?;
+    private store?;
+    private acceptedTokens?;
+    constructor(config: PayNodeVerifierConfig);
+    verifyPayment(txHash: string, expected: ExpectedPayment): Promise<{
         isValid: boolean;
-        error?: {
-            code: ErrorCode;
-            message: string;
-        };
+        error?: PayNodeException;
     }>;
 }
-export interface ExpectedPayment {
-    [key: string]: any;
-}
 //# sourceMappingURL=verifier.d.ts.map

package/dist/utils/verifier.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"verifier.d.ts","sourceRoot":"","sources":["../../src/utils/verifier.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAKtC,qBAAa,eAAe;IAC1B,OAAO,CAAC,UAAU,CAAqB;gBAC3B,MAAM,EAAE,GAAG;IAEjB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE;YAAE,IAAI,EAAE,SAAS,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,CAAC;CAgBhI;AACD,MAAM,WAAW,eAAe;IAAG,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CAAE"}
+{"version":3,"file":"verifier.d.ts","sourceRoot":"","sources":["../../src/utils/verifier.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAExD,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEjD;;;;GAIG;AACH,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CASpD,CAAC;AAEF,kFAAkF;AAClF,eAAO,MAAM,kBAAkB,QAAQ,CAAC;AAExC,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,gBAAgB,CAAC;IACzB,oGAAoG;IACpG,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,eAAe;IAC9B,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAQD,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAqC;IACrD,OAAO,CAAC,OAAO,CAAC,CAAS;IACzB,OAAO,CAAC,KAAK,CAAC,CAAmB;IACjC,OAAO,CAAC,cAAc,CAAC,CAAc;gBAEzB,MAAM,EAAE,qBAAqB;IAiCnC,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,gBAAgB,CAAA;KAAE,CAAC;CA6ExH"}

package/dist/utils/verifier.js

@@ -1,30 +1,134 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PayNodeVerifier = void 0;
+exports.PayNodeVerifier = exports.MIN_PAYMENT_AMOUNT = exports.ACCEPTED_TOKENS = void 0;
 const errors_1 = require("../errors");
-// 使用全局计数器应对 Jest 重试/并发
-let globalCallCount = 0;
-globalCallCount = 0;
+const ethers_1 = require("ethers");
+/**
+ * Default accepted token addresses across supported chains.
+ * SDK will reject any payment involving a token NOT in this whitelist,
+ * preventing fake-token attacks at the verification layer.
+ */
+exports.ACCEPTED_TOKENS = {
+    // Base Mainnet (chainId: 8453)
+    '8453': [
+        '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', // USDC
+    ],
+    // Base Sepolia (chainId: 84532)
+    '84532': [
+        '0xeAC1f2C7099CdaFfB91Aa3b8Ffd653Ef16935798', // USDC (Sandbox)
+    ],
+};
+/** Minimum allowed payment amount to prevent dust exploits (1000 = 0.001 USDC) */
+exports.MIN_PAYMENT_AMOUNT = 1000n;
+const PAYNODE_ABI = [
+    "event PaymentReceived(bytes32 indexed orderId, address indexed merchant, address indexed payer, address token, uint256 amount, uint256 fee, uint256 chainId)"
+];
+const iface = new ethers_1.Interface(PAYNODE_ABI);
 class PayNodeVerifier {
-    usedHashes = new Set();
-    constructor(config) { }
+    provider;
+    chainId;
+    store;
+    acceptedTokens;
+    constructor(config) {
+        if (!config.rpcUrls || (Array.isArray(config.rpcUrls) && config.rpcUrls.length === 0)) {
+            throw new errors_1.PayNodeException("Failed to connect to any provided RPC nodes.", errors_1.ErrorCode.RPC_ERROR);
+        }
+        // Support RpcPool / FallbackProvider
+        if (Array.isArray(config.rpcUrls)) {
+            const providers = config.rpcUrls.map((url, i) => {
+                return {
+                    provider: new ethers_1.JsonRpcProvider(url, config.chainId),
+                    priority: i,
+                    stallTimeout: 1500,
+                    weight: 1
+                };
+            });
+            this.provider = new ethers_1.FallbackProvider(providers);
+        }
+        else {
+            this.provider = new ethers_1.JsonRpcProvider(config.rpcUrls, config.chainId);
+        }
+        this.chainId = config.chainId;
+        this.store = config.store;
+        let tokenList;
+        if (config.acceptedTokens !== undefined) {
+            tokenList = config.acceptedTokens;
+        }
+        else if (config.chainId) {
+            tokenList = exports.ACCEPTED_TOKENS[config.chainId.toString()];
+        }
+        if (tokenList && tokenList.length > 0) {
+            this.acceptedTokens = new Set(tokenList.map(t => t.toLowerCase()));
+        }
+    }
     async verifyPayment(txHash, expected) {
-        if (this.usedHashes.has(txHash))
-            return { isValid: false, error: { code: errors_1.ErrorCode.RECEIPT_ALREADY_USED, message: 'Used' } };
-        if (txHash === '0xFakeHash')
-            return { isValid: false, error: { code: errors_1.ErrorCode.TRANSACTION_NOT_FOUND, message: 'x' } };
-        if (txHash === '0xFailedHash')
-            return { isValid: false, error: { code: errors_1.ErrorCode.TRANSACTION_FAILED, message: 'x' } };
-        if (txHash === '0xHash') {
-            globalCallCount++;
-            if (globalCallCount === 1)
-                return { isValid: false, error: { code: errors_1.ErrorCode.WRONG_CONTRACT, message: 'x' } };
-            if (globalCallCount === 2)
-                return { isValid: false, error: { code: errors_1.ErrorCode.ORDER_MISMATCH, message: 'x' } };
-            return { isValid: false, error: { code: errors_1.ErrorCode.INSUFFICIENT_FUNDS, message: 'x' } };
-        }
-        this.usedHashes.add(txHash);
-        return { isValid: true };
+        try {
+            // 0. Dust Exploit Check (Minimum Payment)
+            const expectedAmount = BigInt(expected.amount);
+            if (expectedAmount < exports.MIN_PAYMENT_AMOUNT) {
+                return { isValid: false, error: new errors_1.PayNodeException("Payment amount is below the protocol minimum (1000).", errors_1.ErrorCode.AMOUNT_TOO_LOW) };
+            }
+            // 1. Token Whitelist Check (Anti-FakeToken)
+            if (this.acceptedTokens && !this.acceptedTokens.has(expected.tokenAddress.toLowerCase())) {
+                return { isValid: false, error: new errors_1.PayNodeException("The provided token address is not in the whitelist.", errors_1.ErrorCode.TOKEN_NOT_ACCEPTED) };
+            }
+            // 1. Idempotency Check
+            if (this.store) {
+                const isNew = await this.store.checkAndSet(txHash, 86400);
+                if (!isNew) {
+                    return { isValid: false, error: new errors_1.PayNodeException("This transaction hash has already been consumed.", errors_1.ErrorCode.DUPLICATE_TRANSACTION) };
+                }
+            }
+            // 2. Fetch Receipt
+            const receipt = await this.provider.getTransactionReceipt(txHash);
+            if (!receipt) {
+                return { isValid: false, error: new errors_1.PayNodeException("The provided receipt (TxHash) is malformed or invalid.", errors_1.ErrorCode.INVALID_RECEIPT) };
+            }
+            if (receipt.status !== 1) {
+                return { isValid: false, error: new errors_1.PayNodeException("On-chain transaction reverted or failed.", errors_1.ErrorCode.TRANSACTION_FAILED) };
+            }
+            // 3. Parse Logs
+            let paymentLog = null;
+            for (const log of receipt.logs) {
+                try {
+                    const parsed = iface.parseLog({ topics: log.topics, data: log.data });
+                    if (parsed && parsed.name === 'PaymentReceived') {
+                        paymentLog = { parsed, logAddress: log.address };
+                        break;
+                    }
+                }
+                catch (e) {
+                    continue;
+                }
+            }
+            if (!paymentLog) {
+                return { isValid: false, error: new errors_1.PayNodeException("No valid PaymentReceived event found in transaction.", errors_1.ErrorCode.INVALID_RECEIPT) };
+            }
+            const args = paymentLog.parsed.args;
+            // 4. Verify Merchant
+            if (args.merchant.toLowerCase() !== expected.merchantAddress.toLowerCase()) {
+                return { isValid: false, error: new errors_1.PayNodeException("Payment went to a different merchant.", errors_1.ErrorCode.INVALID_RECEIPT) };
+            }
+            // 5. Verify Token
+            if (args.token.toLowerCase() !== expected.tokenAddress.toLowerCase()) {
+                return { isValid: false, error: new errors_1.PayNodeException("Payment used unexpected token.", errors_1.ErrorCode.INVALID_RECEIPT) };
+            }
+            // 6. Verify Amount
+            if (BigInt(args.amount) < BigInt(expected.amount)) {
+                return { isValid: false, error: new errors_1.PayNodeException("Payment amount is below required price.", errors_1.ErrorCode.INVALID_RECEIPT) };
+            }
+            // 7. Verify ChainId (Cross-chain replay protection)
+            const expectedChainId = BigInt(this.chainId || (await this.provider.getNetwork()).chainId);
+            if (BigInt(args.chainId) !== expectedChainId) {
+                return { isValid: false, error: new errors_1.PayNodeException("ChainId mismatch. Invalid network.", errors_1.ErrorCode.INVALID_RECEIPT) };
+            }
+            return { isValid: true };
+        }
+        catch (e) {
+            if (e instanceof errors_1.PayNodeException)
+                return { isValid: false, error: e };
+            return { isValid: false, error: new errors_1.PayNodeException(`An unexpected error occurred: ${e.message}`, errors_1.ErrorCode.INTERNAL_ERROR) };
+        }
     }
 }
 exports.PayNodeVerifier = PayNodeVerifier;

package/dist/utils/webhook.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Configuration for the PayNode Webhook Notifier.
+ */
+export interface WebhookConfig {
+    /** RPC URL to connect to the chain */
+    rpcUrl: string;
+    /** PayNode Router contract address to monitor (Defaults to Mainnet) */
+    contractAddress?: string;
+    /** The merchant's webhook endpoint URL */
+    webhookUrl: string;
+    /** Secret key for HMAC-SHA256 signature (header: x-paynode-signature) */
+    webhookSecret: string;
+    /** Optional: chain ID for payload enrichment */
+    chainId?: number;
+    /** Polling interval in milliseconds (default: 5000ms) */
+    pollIntervalMs?: number;
+    /** Optional: custom headers to send with webhook POST */
+    customHeaders?: Record<string, string>;
+    /** Optional: callback when a webhook delivery fails */
+    onError?: (error: Error, event: PaymentEvent) => void;
+    /** Optional: callback when a webhook delivery succeeds */
+    onSuccess?: (event: PaymentEvent) => void;
+}
+/**
+ * Parsed PaymentReceived event data.
+ */
+export interface PaymentEvent {
+    txHash: string;
+    blockNumber: number;
+    orderId: string;
+    merchant: string;
+    payer: string;
+    token: string;
+    amount: string;
+    fee: string;
+    chainId: string;
+    timestamp: number;
+}
+/**
+ * PayNodeWebhookNotifier — listens to on-chain PaymentReceived events
+ * and delivers structured webhook POSTs to the merchant's endpoint.
+ *
+ * Features:
+ * - HMAC-SHA256 signature for authenticity verification
+ * - Configurable polling interval
+ * - Automatic retry with exponential backoff (3 attempts)
+ * - Error/Success callbacks
+ *
+ * @example
+ * ```ts
+ * const notifier = new PayNodeWebhookNotifier({
+ *   rpcUrl: 'https://mainnet.base.org',
+ *   contractAddress: '0x92e20164FC457a2aC35f53D06268168e6352b200',
+ *   webhookUrl: 'https://myshop.com/api/paynode-webhook',
+ *   webhookSecret: 'whsec_mysecretkey123',
+ * });
+ * notifier.start();
+ * ```
+ */
+export declare class PayNodeWebhookNotifier {
+    private provider;
+    private contract;
+    private iface;
+    private config;
+    private pollInterval;
+    private lastBlock;
+    private timer;
+    private isProcessing;
+    constructor(config: WebhookConfig);
+    /**
+     * Start polling for new PaymentReceived events.
+     * @param fromBlock Optional starting block number. Defaults to 'latest'.
+     */
+    start(fromBlock?: number): Promise<void>;
+    /**
+     * Stop polling.
+     */
+    stop(): void;
+    private poll;
+    private parseEvent;
+    /**
+     * Deliver a webhook POST with HMAC signature and retry logic.
+     */
+    private deliver;
+}
+//# sourceMappingURL=webhook.d.ts.map

package/dist/utils/webhook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook.d.ts","sourceRoot":"","sources":["../../src/utils/webhook.ts"],"names":[],"mappings":"AAIA;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAC;IACnB,yEAAyE;IACzE,aAAa,EAAE,MAAM,CAAC;IACtB,gDAAgD;IAChD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,yDAAyD;IACzD,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,uDAAuD;IACvD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;IACtD,0DAA0D;IAC1D,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;CAC3C;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAMD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,sBAAsB;IACjC,OAAO,CAAC,QAAQ,CAAkB;IAClC,OAAO,CAAC,QAAQ,CAAW;IAC3B,OAAO,CAAC,KAAK,CAAY;IACzB,OAAO,CAAC,MAAM,CAAoG;IAClH,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,SAAS,CAAa;IAC9B,OAAO,CAAC,KAAK,CAA+C;IAC5D,OAAO,CAAC,YAAY,CAAkB;gBAE1B,MAAM,EAAE,aAAa;IAgBjC;;;OAGG;IACG,KAAK,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAY9C;;OAEG;IACH,IAAI,IAAI,IAAI;YAQE,IAAI;IAgClB,OAAO,CAAC,UAAU;IAmBlB;;OAEG;YACW,OAAO;CA8CtB"}

package/dist/utils/webhook.js

@@ -0,0 +1,201 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PayNodeWebhookNotifier = void 0;
+const ethers_1 = require("ethers");
+const crypto = __importStar(require("crypto"));
+const constants_1 = require("../constants");
+const PAYNODE_ABI = [
+    "event PaymentReceived(bytes32 indexed orderId, address indexed merchant, address indexed payer, address token, uint256 amount, uint256 fee, uint256 chainId)"
+];
+/**
+ * PayNodeWebhookNotifier — listens to on-chain PaymentReceived events
+ * and delivers structured webhook POSTs to the merchant's endpoint.
+ *
+ * Features:
+ * - HMAC-SHA256 signature for authenticity verification
+ * - Configurable polling interval
+ * - Automatic retry with exponential backoff (3 attempts)
+ * - Error/Success callbacks
+ *
+ * @example
+ * ```ts
+ * const notifier = new PayNodeWebhookNotifier({
+ *   rpcUrl: 'https://mainnet.base.org',
+ *   contractAddress: '0x92e20164FC457a2aC35f53D06268168e6352b200',
+ *   webhookUrl: 'https://myshop.com/api/paynode-webhook',
+ *   webhookSecret: 'whsec_mysecretkey123',
+ * });
+ * notifier.start();
+ * ```
+ */
+class PayNodeWebhookNotifier {
+    provider;
+    contract;
+    iface;
+    config;
+    pollInterval;
+    lastBlock = 0;
+    timer = null;
+    isProcessing = false;
+    constructor(config) {
+        if (!config.rpcUrl)
+            throw new Error('rpcUrl is required');
+        if (!config.webhookUrl)
+            throw new Error('webhookUrl is required');
+        if (!config.webhookSecret)
+            throw new Error('webhookSecret is required');
+        this.config = {
+            ...config,
+            contractAddress: config.contractAddress || constants_1.PAYNODE_ROUTER_ADDRESS
+        };
+        this.pollInterval = config.pollIntervalMs || 5000;
+        this.provider = new ethers_1.JsonRpcProvider(config.rpcUrl, config.chainId);
+        this.iface = new ethers_1.Interface(PAYNODE_ABI);
+        this.contract = new ethers_1.Contract(this.config.contractAddress, PAYNODE_ABI, this.provider);
+    }
+    /**
+     * Start polling for new PaymentReceived events.
+     * @param fromBlock Optional starting block number. Defaults to 'latest'.
+     */
+    async start(fromBlock) {
+        if (this.timer) {
+            console.warn('[PayNode Webhook] Already running.');
+            return;
+        }
+        this.lastBlock = fromBlock ?? (await this.provider.getBlockNumber());
+        console.log(`🔔 [PayNode Webhook] Listening from block ${this.lastBlock} on ${this.config.contractAddress}`);
+        this.timer = setInterval(() => this.poll(), this.pollInterval);
+    }
+    /**
+     * Stop polling.
+     */
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+            console.log('🔕 [PayNode Webhook] Stopped.');
+        }
+    }
+    async poll() {
+        if (this.isProcessing)
+            return;
+        this.isProcessing = true;
+        try {
+            const currentBlock = await this.provider.getBlockNumber();
+            if (currentBlock <= this.lastBlock) {
+                this.isProcessing = false;
+                return;
+            }
+            const events = await this.contract.queryFilter('PaymentReceived', this.lastBlock + 1, currentBlock);
+            for (const event of events) {
+                const paymentEvent = this.parseEvent(event);
+                if (paymentEvent) {
+                    await this.deliver(paymentEvent);
+                }
+            }
+            this.lastBlock = currentBlock;
+        }
+        catch (error) {
+            console.error(`[PayNode Webhook] Poll error: ${error.message}`);
+        }
+        finally {
+            this.isProcessing = false;
+        }
+    }
+    parseEvent(event) {
+        try {
+            return {
+                txHash: event.transactionHash,
+                blockNumber: event.blockNumber,
+                orderId: event.args[0], // bytes32 indexed orderId
+                merchant: event.args[1], // address indexed merchant
+                payer: event.args[2], // address indexed payer
+                token: event.args[3], // address token
+                amount: event.args[4].toString(), // uint256 amount
+                fee: event.args[5].toString(), // uint256 fee
+                chainId: event.args[6].toString(), // uint256 chainId
+                timestamp: Date.now()
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Deliver a webhook POST with HMAC signature and retry logic.
+     */
+    async deliver(event, attempt = 1) {
+        const MAX_RETRIES = 3;
+        const payload = JSON.stringify({
+            event: 'payment.received',
+            data: event
+        });
+        const signature = crypto
+            .createHmac('sha256', this.config.webhookSecret)
+            .update(payload)
+            .digest('hex');
+        const headers = {
+            'Content-Type': 'application/json',
+            'x-paynode-signature': `sha256=${signature}`,
+            'x-paynode-event': 'payment.received',
+            'x-paynode-delivery-id': `${event.txHash}-${attempt}`,
+            ...(this.config.customHeaders || {})
+        };
+        try {
+            const response = await fetch(this.config.webhookUrl, {
+                method: 'POST',
+                headers,
+                body: payload
+            });
+            if (!response.ok) {
+                throw new Error(`Webhook returned ${response.status}: ${response.statusText}`);
+            }
+            console.log(`✅ [PayNode Webhook] Delivered tx ${event.txHash.slice(0, 10)}... → ${response.status}`);
+            this.config.onSuccess?.(event);
+        }
+        catch (error) {
+            console.error(`[PayNode Webhook] Delivery failed (attempt ${attempt}/${MAX_RETRIES}): ${error.message}`);
+            if (attempt < MAX_RETRIES) {
+                const backoffMs = Math.pow(2, attempt) * 1000; // 2s, 4s, 8s
+                await new Promise(resolve => setTimeout(resolve, backoffMs));
+                return this.deliver(event, attempt + 1);
+            }
+            console.error(`[PayNode Webhook] Gave up on tx ${event.txHash} after ${MAX_RETRIES} attempts.`);
+            this.config.onError?.(error, event);
+        }
+    }
+}
+exports.PayNodeWebhookNotifier = PayNodeWebhookNotifier;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paynodelabs/sdk-js",
-  "version": "1.0.1",
+  "version": "1.1.1",
   "description": "The official JavaScript/TypeScript SDK for PayNode x402 protocol on Base L2.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -11,7 +11,8 @@
   "scripts": {
     "build": "tsc",
     "prepublishOnly": "npm run build",
-    "test": "ts-node tests/mainnet_live.ts"
+    "test": "jest",
+    "example:server": "ts-node examples/express-server.ts"
   },
   "keywords": [
     "paynode",
@@ -24,12 +25,19 @@
   "author": "PayNodeLabs",
   "license": "MIT",
   "dependencies": {
-    "ethers": "^6.13.0"
+    "ethers": "^6.13.0",
+    "ioredis": "^5.10.1",
+    "express": "^4.19.2"
   },
   "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/ioredis": "^4.28.10",
+    "@types/jest": "^29.5.12",
+    "@types/node": "^20.12.12",
     "dotenv": "^16.4.5",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.4",
     "ts-node": "^10.9.2",
-    "typescript": "^5.4.5",
-    "@types/node": "^20.12.12"
+    "typescript": "^5.4.5"
   }
 }