@paynodelabs/sdk-js 1.1.0 → 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

@@ -21,35 +21,64 @@ npm install @paynodelabs/sdk-js ethers
 ### Agent Client (Payer)
 
 ```typescript
-import { PayNodeClient } from '@paynodelabs/sdk-js';
+import { PayNodeAgentClient } from "@paynodelabs/sdk-js";
 
-const client = new PayNodeClient('YOUR_AGENT_PRIVATE_KEY');
+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.request('https://api.merchant.com/premium-data');
-    console.log(await response.text());
+  // 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();
 ```
 
-### Merchant Middleware (Receiver)
+## 🚀 Run the Demo
 
-```typescript
-import express from 'express';
-import { createPayNodeMiddleware } from '@paynodelabs/sdk-js';
+The SDK includes a full merchant/agent demonstration in the `examples/` directory.
 
-const app = express();
+### 1. Setup Environment
 
-const requirePayment = createPayNodeMiddleware({
-    price: "1.50", // 1.50 USDC
-    merchantWallet: "0xYourWalletAddress..."
-});
+```bash
+cp .env.example .env
+# Edit .env with your private key and RPC URLs
+```
 
-app.get('/premium-data', requirePayment, (req, res) => {
-    res.json({ secret: "This is paid M2M data." });
-});
+### 2. Run the Merchant Server (Express)
+
+```bash
+npx ts-node examples/express-server.ts
 ```
 
+### 3. Run the Agent Client
+
+In another terminal:
+
+```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
+   ```
+
 ---
-*Built for the Autonomous AI Economy by PayNodeLabs.*
+
+_Built for the Autonomous AI Economy by PayNodeLabs._

package/dist/client.d.ts

@@ -4,38 +4,17 @@ 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;
-    /**
-     * 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
-     */
+    private executeStandardPay;
+    private executePermitPay;
     signPermit(tokenAddr: string, spenderAddr: string, amount: bigint, deadlineSeconds?: number): Promise<{
         deadline: number;
-        v: number;
+        v: 27 | 28;
         r: string;
         s: string;
     }>;

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,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"}
+{"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,25 +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 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) {
@@ -30,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');
@@ -44,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,
@@ -60,72 +101,40 @@ 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;
     }
-    /**
-     * 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 });
+    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;
     }
-    /**
-     * 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 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: '2', // USDC uses version "2"
-            chainId: Number(chainId),
+            version: '1', // USDC on Base uses version 1
+            chainId: Number(network.chainId),
             verifyingContract: tokenAddr
         };
         const types = {
@@ -144,8 +153,8 @@ class PayNodeAgentClient {
             nonce,
             deadline
         };
-        const sig = await this.wallet.signTypedData(domain, types, value);
-        const { v, r, s } = ethers_1.ethers.Signature.from(sig);
+        const signature = await this.wallet.signTypedData(domain, types, value);
+        const { v, r, s } = ethers_1.ethers.Signature.from(signature);
         return { deadline, v, r, s };
     }
 }

package/dist/constants.d.ts

@@ -5,4 +5,8 @@ export declare const BASE_USDC_ADDRESS = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA0
 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

@@ -1 +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"}
+{"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

@@ -1,6 +1,6 @@
 "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;
+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";
@@ -8,3 +8,10 @@ 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,13 +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",
-    TOKEN_NOT_ACCEPTED = "TOKEN_NOT_ACCEPTED",
-    INTERNAL_ERROR = "INTERNAL_ERROR"
+    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;IACnC,kBAAkB,uBAAuB;IACzC,cAAc,mBAAmB;CAClC"}
+{"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,16 +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["TOKEN_NOT_ACCEPTED"] = "TOKEN_NOT_ACCEPTED";
-    ErrorCode["INTERNAL_ERROR"] = "INTERNAL_ERROR";
 })(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/utils/verifier.d.ts

@@ -1,4 +1,4 @@
-import { ErrorCode } from '../errors';
+import { PayNodeException } from '../errors';
 import { IdempotencyStore } from './idempotency';
 /**
  * Default accepted token addresses across supported chains.
@@ -6,6 +6,8 @@ import { IdempotencyStore } from './idempotency';
  * 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;
@@ -18,7 +20,6 @@ export interface ExpectedPayment {
     tokenAddress: string;
     amount: string | number | bigint;
     orderId?: string;
-    verifyDepegPrice?: boolean;
 }
 export declare class PayNodeVerifier {
     private provider;
@@ -28,10 +29,7 @@ export declare class PayNodeVerifier {
     constructor(config: PayNodeVerifierConfig);
     verifyPayment(txHash: string, expected: ExpectedPayment): Promise<{
         isValid: boolean;
-        error?: {
-            code: ErrorCode;
-            message: string;
-        };
+        error?: PayNodeException;
     }>;
 }
 //# 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;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"}
+{"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,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PayNodeVerifier = exports.ACCEPTED_TOKENS = void 0;
+exports.PayNodeVerifier = exports.MIN_PAYMENT_AMOUNT = exports.ACCEPTED_TOKENS = void 0;
 const errors_1 = require("../errors");
 const ethers_1 = require("ethers");
 /**
@@ -12,13 +12,14 @@ exports.ACCEPTED_TOKENS = {
     // Base Mainnet (chainId: 8453)
     '8453': [
         '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', // USDC
-        '0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2', // USDT
     ],
     // 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)"
 ];
@@ -30,7 +31,7 @@ class PayNodeVerifier {
     acceptedTokens;
     constructor(config) {
         if (!config.rpcUrls || (Array.isArray(config.rpcUrls) && config.rpcUrls.length === 0)) {
-            throw new Error("rpcUrls must be provided");
+            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)) {
@@ -49,8 +50,6 @@ class PayNodeVerifier {
         }
         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;
@@ -64,25 +63,29 @@ class PayNodeVerifier {
     }
     async verifyPayment(txHash, expected) {
         try {
-            // 0. Token Whitelist Check (Anti-FakeToken)
+            // 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: { code: errors_1.ErrorCode.TOKEN_NOT_ACCEPTED, message: `Token ${expected.tokenAddress} is not in the accepted whitelist.` } };
+                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) {
-                // 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.' } };
+                    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: { code: errors_1.ErrorCode.TRANSACTION_NOT_FOUND, message: "Transaction not found on-chain." } };
+                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: { code: errors_1.ErrorCode.TRANSACTION_FAILED, message: "Transaction reverted on-chain." } };
+                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;
@@ -99,39 +102,32 @@ class PayNodeVerifier {
                 }
             }
             if (!paymentLog) {
-                return { isValid: false, error: { code: errors_1.ErrorCode.ORDER_MISMATCH, message: "No PaymentReceived event found in transaction." } };
+                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: { code: errors_1.ErrorCode.ORDER_MISMATCH, message: `Merchant mismatch. Expected ${expected.merchantAddress}, got ${args.merchant}` } };
+                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: { code: errors_1.ErrorCode.ORDER_MISMATCH, message: `Token mismatch. Expected ${expected.tokenAddress}, got ${args.token}` } };
+                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: { code: errors_1.ErrorCode.INSUFFICIENT_FUNDS, message: `Expected amount ${expected.amount}, received ${args.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: { 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: false, error: new errors_1.PayNodeException("ChainId mismatch. Invalid network.", errors_1.ErrorCode.INVALID_RECEIPT) };
             }
             return { isValid: true };
         }
         catch (e) {
-            return { isValid: false, error: { code: errors_1.ErrorCode.INTERNAL_ERROR, message: e.message } };
+            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) };
         }
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paynodelabs/sdk-js",
-  "version": "1.1.0",
+  "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",
@@ -25,13 +26,17 @@
   "license": "MIT",
   "dependencies": {
     "ethers": "^6.13.0",
-    "ioredis": "^5.10.1"
+    "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"
   }