@paynodelabs/sdk-js 1.0.1 → 1.1.0

package/README.md

@@ -1,68 +1,55 @@
-# 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.
 
-```bash
-npm install @paynode/sdk
-```
+## 📖 Read the Docs
 
-## 🚀 Express 集成示例
+**For complete installation guides, advanced usage, API references, and architecture details, please visit our official documentation:**
+👉 **[docs.paynode.dev](https://docs.paynode.dev)**
 
-只需几行代码，即可为现有 API 路由开启支付门禁。
+## ⚡ Quick Start
 
-```typescript
-import express from 'express';
-import { x402_gate } from '@paynode/sdk';
+### Installation
 
-const app = express();
+```bash
+npm install @paynodelabs/sdk-js ethers
+```
 
-// 为指定路由挂载 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." });
-});
+### Agent Client (Payer)
 
-app.listen(3000);
-```
+```typescript
+import { PayNodeClient } from '@paynodelabs/sdk-js';
 
-## 🏗️ 核心验证逻辑
+const client = new PayNodeClient('YOUR_AGENT_PRIVATE_KEY');
 
-PayNode SDK 核心职责是对 Agent 提供的 `x-paynode-receipt` (Transaction Hash) 进行链上状态校验：
+async function main() {
+    // Automatically handles 402 challenges, pays USDC, and retries the request
+    const response = await client.request('https://api.merchant.com/premium-data');
+    console.log(await response.text());
+}
+main();
+```
 
-1. **402 握手阶段:** 
-   - 当请求头中缺失 `x-paynode-receipt` 时，SDK 自动返回 `402 Payment Required`。
-   - 响应头中包含支付所需的全部元数据 (价格、收款地址、合约、ChainId、OrderId)。
-2. **链上验证阶段:**
-   - 接收到交易哈希后，SDK 通过 RPC 实时查询交易状态。
-   - 解析 Event Log，比对 `orderId`、`merchant`、`token` 和 `amount` 是否完全一致。
-   - **防重放 (Anti-Replay):** 建议结合本地缓存或数据库记录已核销的 Receipt。
+### Merchant Middleware (Receiver)
 
-## 🧪 开发与测试
+```typescript
+import express from 'express';
+import { createPayNodeMiddleware } from '@paynodelabs/sdk-js';
 
-```bash
-# 进入 SDK 目录
-cd packages/sdk-js
+const app = express();
 
-# 安装依赖
-npm install
+const requirePayment = createPayNodeMiddleware({
+    price: "1.50", // 1.50 USDC
+    merchantWallet: "0xYourWalletAddress..."
+});
 
-# 运行单元测试
-npm test
+app.get('/premium-data', requirePayment, (req, res) => {
+    res.json({ secret: "This is paid M2M data." });
+});
 ```
 
-## 🔗 资源
-
-- **目录位置:** `packages/sdk-js`
-- **主页:** [paynode.dev](https://paynode.dev)
-- **协议文档:** `/agentpay-docs/`
+---
+*Built for the Autonomous AI Economy by PayNodeLabs.*

package/dist/client.d.ts

@@ -13,5 +13,31 @@ export declare class PayNodeAgentClient {
     requestGate(url: string, options?: RequestOptions): Promise<Response>;
     private handlePaymentAndRetry;
     private executeChainPayment;
+    /**
+     * Executes a payment using EIP-2612 Permit — single-tx approve + pay.
+     * The payer signs the permit offline, and any relayer (e.g. AI Agent) can submit it on-chain.
+     * @param contractAddr PayNode Router address
+     * @param payerAddress The address that holds the tokens and signed the permit
+     * @param tokenAddr ERC20 token with EIP-2612 support (e.g. USDC)
+     * @param merchantAddr Merchant receiving 99% of payment
+     * @param amount Token amount in smallest unit (e.g. 1000000 = 1 USDC)
+     * @param orderId Order identifier as bytes32
+     * @param deadline Unix timestamp after which the permit is invalid
+     * @param v ECDSA recovery id
+     * @param r ECDSA signature component
+     * @param s ECDSA signature component
+     */
+    payWithPermit(contractAddr: string, payerAddress: string, tokenAddr: string, merchantAddr: string, amount: bigint, orderId: string, deadline: number, v: number, r: string, s: string): Promise<string>;
+    /**
+     * Helper: Generate an EIP-2612 Permit signature for USDC/ERC20.
+     * The wallet that calls this must be the token holder (payer).
+     * @returns { deadline, v, r, s } to pass to payWithPermit
+     */
+    signPermit(tokenAddr: string, spenderAddr: string, amount: bigint, deadlineSeconds?: number): Promise<{
+        deadline: number;
+        v: number;
+        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":"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,CAGhB;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;IAoCjC;;;;;;;;;;;;;OAaG;IACG,aAAa,CACjB,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,GACR,OAAO,CAAC,MAAM,CAAC;IAoBlB;;;;OAIG;IACG,UAAU,CACd,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,EACd,eAAe,GAAE,MAAa,GAC7B,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CA8ClE"}

package/dist/client.js

@@ -11,7 +11,8 @@ class PayNodeAgentClient {
         "function balanceOf(address account) public 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);
@@ -83,5 +84,69 @@ class PayNodeAgentClient {
         const receipt = await payTx.wait();
         return receipt.hash;
     }
+    /**
+     * Executes a payment using EIP-2612 Permit — single-tx approve + pay.
+     * The payer signs the permit offline, and any relayer (e.g. AI Agent) can submit it on-chain.
+     * @param contractAddr PayNode Router address
+     * @param payerAddress The address that holds the tokens and signed the permit
+     * @param tokenAddr ERC20 token with EIP-2612 support (e.g. USDC)
+     * @param merchantAddr Merchant receiving 99% of payment
+     * @param amount Token amount in smallest unit (e.g. 1000000 = 1 USDC)
+     * @param orderId Order identifier as bytes32
+     * @param deadline Unix timestamp after which the permit is invalid
+     * @param v ECDSA recovery id
+     * @param r ECDSA signature component
+     * @param s ECDSA signature component
+     */
+    async payWithPermit(contractAddr, payerAddress, tokenAddr, merchantAddr, amount, orderId, deadline, v, r, s) {
+        const routerContract = new ethers_1.ethers.Contract(contractAddr, this.ROUTER_ABI, this.wallet);
+        const tx = await routerContract.payWithPermit(payerAddress, tokenAddr, merchantAddr, amount, orderId, deadline, v, r, s, { gasLimit: 300000 });
+        const receipt = await tx.wait();
+        return receipt.hash;
+    }
+    /**
+     * Helper: Generate an EIP-2612 Permit signature for USDC/ERC20.
+     * The wallet that calls this must be the token holder (payer).
+     * @returns { deadline, v, r, s } to pass to payWithPermit
+     */
+    async signPermit(tokenAddr, spenderAddr, amount, deadlineSeconds = 3600) {
+        const deadline = Math.floor(Date.now() / 1000) + deadlineSeconds;
+        // EIP-2612 domain & types
+        const tokenContract = new ethers_1.ethers.Contract(tokenAddr, [
+            "function name() view returns (string)",
+            "function nonces(address owner) view returns (uint256)",
+            "function DOMAIN_SEPARATOR() view returns (bytes32)"
+        ], this.wallet);
+        const [name, nonce, chainId] = await Promise.all([
+            tokenContract.name(),
+            tokenContract.nonces(this.wallet.address),
+            this.provider.getNetwork().then(n => n.chainId)
+        ]);
+        const domain = {
+            name,
+            version: '2', // USDC uses version "2"
+            chainId: Number(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 sig = await this.wallet.signTypedData(domain, types, value);
+        const { v, r, s } = ethers_1.ethers.Signature.from(sig);
+        return { deadline, v, r, s };
+    }
 }
 exports.PayNodeAgentClient = PayNodeAgentClient;

package/dist/constants.d.ts

@@ -0,0 +1,8 @@
+/** 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;
+//# 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"}

package/dist/constants.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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;

package/dist/errors/index.d.ts

@@ -6,6 +6,8 @@ export declare enum ErrorCode {
     INSUFFICIENT_FUNDS = "INSUFFICIENT_FUNDS",
     RECEIPT_ALREADY_USED = "RECEIPT_ALREADY_USED",
     INVALID_RECEIPT = "INVALID_RECEIPT",
-    MISSING_RECEIPT = "MISSING_RECEIPT"
+    MISSING_RECEIPT = "MISSING_RECEIPT",
+    TOKEN_NOT_ACCEPTED = "TOKEN_NOT_ACCEPTED",
+    INTERNAL_ERROR = "INTERNAL_ERROR"
 }
 //# 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,qBAAqB,0BAA0B;IAC/C,kBAAkB,uBAAuB;IACzC,cAAc,mBAAmB;IACjC,cAAc,mBAAmB;IACjC,kBAAkB,uBAAuB;IACzC,oBAAoB,yBAAyB;IAC7C,eAAe,oBAAoB;IACnC,eAAe,oBAAoB;IACnC,kBAAkB,uBAAuB;IACzC,cAAc,mBAAmB;CAClC"}

package/dist/errors/index.js

@@ -11,4 +11,6 @@ var ErrorCode;
     ErrorCode["RECEIPT_ALREADY_USED"] = "RECEIPT_ALREADY_USED";
     ErrorCode["INVALID_RECEIPT"] = "INVALID_RECEIPT";
     ErrorCode["MISSING_RECEIPT"] = "MISSING_RECEIPT";
+    ErrorCode["TOKEN_NOT_ACCEPTED"] = "TOKEN_NOT_ACCEPTED";
+    ErrorCode["INTERNAL_ERROR"] = "INTERNAL_ERROR";
 })(ErrorCode || (exports.ErrorCode = ErrorCode = {}));

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,8 +1,32 @@
 import { ErrorCode } 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[]>;
+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;
+    verifyDepegPrice?: boolean;
+}
 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;
@@ -10,7 +34,4 @@ export declare class PayNodeVerifier {
         };
     }>;
 }
-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,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEjD;;;;GAIG;AACH,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAUpD,CAAC;AAEF,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;IACjB,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;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;IAmCnC,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,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;CAiF5I"}

package/dist/utils/verifier.js

@@ -1,30 +1,138 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PayNodeVerifier = void 0;
+exports.PayNodeVerifier = 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
+        '0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2', // USDT
+    ],
+    // Base Sepolia (chainId: 84532)
+    '84532': [
+        '0xeAC1f2C7099CdaFfB91Aa3b8Ffd653Ef16935798', // USDC (Sandbox)
+    ],
+};
+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 Error("rpcUrls must be provided");
+        }
+        // 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;
+        // Build accepted token set: user-provided or chain-default
+        // acceptedTokens=undefined → use chain default; acceptedTokens=[] → explicitly disable whitelist
+        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. Token Whitelist Check (Anti-FakeToken)
+            if (this.acceptedTokens && !this.acceptedTokens.has(expected.tokenAddress.toLowerCase())) {
+                return { isValid: false, error: { code: errors_1.ErrorCode.TOKEN_NOT_ACCEPTED, message: `Token ${expected.tokenAddress} is not in the accepted whitelist.` } };
+            }
+            // 1. Idempotency Check
+            if (this.store) {
+                // Assume TTL of 24 hours for replay protection
+                const isNew = await this.store.checkAndSet(txHash, 86400);
+                if (!isNew) {
+                    return { isValid: false, error: { code: errors_1.ErrorCode.RECEIPT_ALREADY_USED, message: 'Transaction hash has already been consumed.' } };
+                }
+            }
+            // 2. Fetch Receipt
+            const receipt = await this.provider.getTransactionReceipt(txHash);
+            if (!receipt) {
+                return { isValid: false, error: { code: errors_1.ErrorCode.TRANSACTION_NOT_FOUND, message: "Transaction not found on-chain." } };
+            }
+            if (receipt.status !== 1) {
+                return { isValid: false, error: { code: errors_1.ErrorCode.TRANSACTION_FAILED, message: "Transaction reverted on-chain." } };
+            }
+            // 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: { code: errors_1.ErrorCode.ORDER_MISMATCH, message: "No PaymentReceived event found in transaction." } };
+            }
+            const args = paymentLog.parsed.args;
+            // 4. Verify Merchant
+            if (args.merchant.toLowerCase() !== expected.merchantAddress.toLowerCase()) {
+                return { isValid: false, error: { code: errors_1.ErrorCode.ORDER_MISMATCH, message: `Merchant mismatch. Expected ${expected.merchantAddress}, got ${args.merchant}` } };
+            }
+            // 5. Verify Token
+            if (args.token.toLowerCase() !== expected.tokenAddress.toLowerCase()) {
+                return { isValid: false, error: { code: errors_1.ErrorCode.ORDER_MISMATCH, message: `Token mismatch. Expected ${expected.tokenAddress}, got ${args.token}` } };
+            }
+            // 6. Verify Amount
+            if (BigInt(args.amount) < BigInt(expected.amount)) {
+                return { isValid: false, error: { code: errors_1.ErrorCode.INSUFFICIENT_FUNDS, message: `Expected amount ${expected.amount}, received ${args.amount}` } };
+            }
+            // 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: { code: errors_1.ErrorCode.ORDER_MISMATCH, message: "ChainId mismatch. Invalid network." } };
+            }
+            // 8. Order Id Check (Optional)
+            if (expected.orderId) {
+                // Contract orderId is bytes32. Just comparing strings directly if it was passed cleanly, or checking startsWith etc.
+                // Ethers returns bytes32 as 0x-prefixed hex string. We should format expected to bytes32 if it's text.
+                // For simplicity, assume they match format or we enforce formatting in the caller.
+                if (args.orderId !== expected.orderId) {
+                    return { isValid: false, error: { code: errors_1.ErrorCode.ORDER_MISMATCH, message: "OrderId mismatch." } };
+                }
+            }
+            return { isValid: true };
+        }
+        catch (e) {
+            return { isValid: false, error: { code: errors_1.ErrorCode.INTERNAL_ERROR, message: e.message } };
+        }
     }
 }
 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.0",
   "description": "The official JavaScript/TypeScript SDK for PayNode x402 protocol on Base L2.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -24,12 +24,15 @@
   "author": "PayNodeLabs",
   "license": "MIT",
   "dependencies": {
-    "ethers": "^6.13.0"
+    "ethers": "^6.13.0",
+    "ioredis": "^5.10.1"
   },
   "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/ioredis": "^4.28.10",
+    "@types/node": "^20.12.12",
     "dotenv": "^16.4.5",
     "ts-node": "^10.9.2",
-    "typescript": "^5.4.5",
-    "@types/node": "^20.12.12"
+    "typescript": "^5.4.5"
   }
 }