paynode-sdk-python 1.0.1__py3-none-any.whl → 1.1.0__py3-none-any.whl

paynode_sdk/__init__.py

@@ -2,5 +2,13 @@ from .middleware import PayNodeMiddleware
 from .verifier import PayNodeVerifier
 from .errors import ErrorCode, PayNodeException
 from .idempotency import IdempotencyStore, MemoryIdempotencyStore
+from .webhook import PayNodeWebhookNotifier, PaymentEvent
+from .client import PayNodeAgentClient
+from .constants import ACCEPTED_TOKENS
 
-__all__ = ["PayNodeMiddleware", "PayNodeVerifier", "ErrorCode", "PayNodeException", "IdempotencyStore", "MemoryIdempotencyStore"]
+__all__ = [
+    "PayNodeMiddleware", "PayNodeVerifier", "ErrorCode", "PayNodeException",
+    "IdempotencyStore", "MemoryIdempotencyStore",
+    "PayNodeWebhookNotifier", "PaymentEvent",
+    "PayNodeAgentClient", "ACCEPTED_TOKENS"
+]

paynode_sdk/client.py

@@ -1,53 +1,94 @@
-import requests
 import time
+import logging
+import threading
+import requests
 from web3 import Web3
+from requests.adapters import HTTPAdapter
+from urllib3.util.retry import Retry
 from .constants import PAYNODE_ROUTER_ADDRESS, BASE_USDC_ADDRESS, BASE_USDC_DECIMALS
+from .errors import PayNodeException, ErrorCode
+
+logger = logging.getLogger("paynode_sdk.client")
 
 class PayNodeAgentClient:
     def __init__(self, rpc_urls: list, private_key: str):
-        self.w3 = Web3(Web3.HTTPProvider(rpc_urls[0]))
+        self.rpc_urls = rpc_urls
+        self.w3 = self._init_w3()
+        # Initialize account and discard private key string to prevent Traceback leaks
         self.account = self.w3.eth.account.from_key(private_key)
-        self.private_key = private_key
+        self.nonce_lock = threading.Lock()
+        
+        # Setup session with standard HTTP retries for non-402 errors
+        self.session = requests.Session()
+        retry_strategy = Retry(
+            total=3,
+            status_forcelist=[429, 500, 502, 503, 504],
+            allowed_methods=["HEAD", "GET", "POST", "PUT", "DELETE", "OPTIONS", "TRACE"]
+        )
+        adapter = HTTPAdapter(max_retries=retry_strategy)
+        self.session.mount("https://", adapter)
+        self.session.mount("http://", adapter)
+
+    def _init_w3(self):
+        for rpc in self.rpc_urls:
+            try:
+                w3 = Web3(Web3.HTTPProvider(rpc, request_kwargs={'timeout': 10}))
+                if w3.is_connected():
+                    return w3
+            except Exception:
+                continue
+        raise PayNodeException("Failed to connect to any RPC URL", ErrorCode.RPC_ERROR)
 
     def get(self, url, **kwargs):
-        response = requests.get(url, **kwargs)
-        if response.status_code == 402:
-            print("💡 [PayNode-PY] 402 Detected. Handling payment...")
-            return self._handle_402(url, "GET", response.headers, **kwargs)
-        return response
+        return self._request_with_402_retry("GET", url, **kwargs)
 
     def post(self, url, **kwargs):
-        response = requests.post(url, **kwargs)
-        if response.status_code == 402:
-            print("💡 [PayNode-PY] 402 Detected. Handling payment...")
-            return self._handle_402(url, "POST", response.headers, **kwargs)
+        return self._request_with_402_retry("POST", url, **kwargs)
+
+    def _request_with_402_retry(self, method, url, max_retries=3, **kwargs):
+        for attempt in range(max_retries):
+            response = self.session.request(method, url, **kwargs)
+            if response.status_code == 402:
+                logger.info("💡 [PayNode-PY] 402 Detected. Handling payment...")
+                try:
+                    kwargs = self._handle_402(response.headers, **kwargs)
+                except Exception as e:
+                    if isinstance(e, PayNodeException):
+                        raise
+                    raise PayNodeException(f"Payment execution failed: {str(e)}", ErrorCode.INTERNAL_ERROR)
+                time.sleep(1) # Backoff before retry
+                continue
+            return response
         return response
 
-    def _handle_402(self, url, method, headers, **kwargs):
+    def _handle_402(self, headers, **kwargs):
         router_addr = headers.get('x-paynode-contract')
         merchant_addr = headers.get('x-paynode-merchant')
         amount_raw = int(headers.get('x-paynode-amount', 0))
         token_addr = headers.get('x-paynode-token-address')
         order_id = headers.get('x-paynode-order-id')
 
-        # 1. Handle Approval
-        self._ensure_allowance(token_addr, router_addr, amount_raw)
+        try:
+            self._ensure_allowance(token_addr, router_addr, amount_raw)
+            tx_hash = self._execute_pay(router_addr, token_addr, merchant_addr, amount_raw, order_id)
+            logger.info(f"✅ [PayNode-PY] Payment successful: {tx_hash}")
+        except ValueError as e:
+            err_msg = str(e).lower()
+            if "insufficient funds" in err_msg:
+                raise PayNodeException("Insufficient funds for gas or token.", ErrorCode.INSUFFICIENT_FUNDS)
+            raise PayNodeException(f"Transaction failed: {str(e)}", ErrorCode.TRANSACTION_FAILED)
+        except Exception as e:
+            if isinstance(e, PayNodeException):
+                raise
+            raise PayNodeException(f"Unknown error during payment: {str(e)}", ErrorCode.INTERNAL_ERROR)
 
-        # 2. Execute Payment
-        tx_hash = self._execute_pay(router_addr, token_addr, merchant_addr, amount_raw, order_id)
-        print(f"✅ [PayNode-PY] Payment successful: {tx_hash}")
-
-        # 3. Retry
         retry_headers = kwargs.get('headers', {}).copy()
         retry_headers.update({
             'x-paynode-receipt': tx_hash,
             'x-paynode-order-id': order_id
         })
         kwargs['headers'] = retry_headers
-        
-        if method == "GET":
-            return requests.get(url, **kwargs)
-        return requests.post(url, **kwargs)
+        return kwargs
 
     def _ensure_allowance(self, token_addr, spender_addr, amount):
         token_abi = [
@@ -58,42 +99,120 @@ class PayNodeAgentClient:
         allowance = token.functions.allowance(self.account.address, Web3.to_checksum_address(spender_addr)).call()
         
         if allowance < amount:
-            print(f"🔐 [PayNode-PY] Allowance too low. Granting Infinite Approval...")
-            # Use 20% higher gas price for better reliability
+            logger.info("🔐 [PayNode-PY] Allowance too low. Granting Infinite Approval...")
             current_gas_price = int(self.w3.eth.gas_price * 1.2)
             
-            tx = token.functions.approve(Web3.to_checksum_address(spender_addr), 2**256 - 1).build_transaction({
+            with self.nonce_lock:
+                nonce = self.w3.eth.get_transaction_count(self.account.address, 'pending')
+                tx = token.functions.approve(Web3.to_checksum_address(spender_addr), 2**256 - 1).build_transaction({
+                    'from': self.account.address,
+                    'nonce': nonce,
+                    'gas': 100000,
+                    'gasPrice': current_gas_price
+                })
+                signed_tx = self.account.sign_transaction(tx)
+                tx_h = self.w3.eth.send_raw_transaction(signed_tx.raw_transaction)
+
+            logger.info(f"⏳ Waiting for approval confirmation: {self.w3.to_hex(tx_h)}...")
+            self.w3.eth.wait_for_transaction_receipt(tx_h, timeout=60)
+
+    def _execute_pay(self, router_addr, token_addr, merchant_addr, amount, order_id):
+        router_abi = [
+            {"inputs": [{"name": "t", "type": "address"}, {"name": "m", "type": "address"}, {"name": "a", "type": "uint256"}, {"name": "o", "type": "bytes32"}], "name": "pay", "outputs": [], "stateMutability": "nonpayable", "type": "function"},
+            {"inputs": [{"name": "payer", "type": "address"}, {"name": "token", "type": "address"}, {"name": "merchant", "type": "address"}, {"name": "amount", "type": "uint256"}, {"name": "orderId", "type": "bytes32"}, {"name": "deadline", "type": "uint256"}, {"name": "v", "type": "uint8"}, {"name": "r", "type": "bytes32"}, {"name": "s", "type": "bytes32"}], "name": "payWithPermit", "outputs": [], "stateMutability": "nonpayable", "type": "function"}
+        ]
+        router = self.w3.eth.contract(address=Web3.to_checksum_address(router_addr), abi=router_abi)
+        order_id_bytes = self.w3.keccak(text=order_id)
+
+        current_gas_price = int(self.w3.eth.gas_price * 1.2)
+
+        with self.nonce_lock:
+            nonce = self.w3.eth.get_transaction_count(self.account.address, 'pending')
+            tx = router.functions.pay(
+                Web3.to_checksum_address(token_addr),
+                Web3.to_checksum_address(merchant_addr),
+                amount,
+                order_id_bytes
+            ).build_transaction({
                 'from': self.account.address,
-                'nonce': self.w3.eth.get_transaction_count(self.account.address, 'pending'),
-                'gas': 100000,
+                'nonce': nonce,
+                'gas': 200000,
                 'gasPrice': current_gas_price
             })
-            signed_tx = self.w3.eth.account.sign_transaction(tx, self.private_key)
+            signed_tx = self.account.sign_transaction(tx)
             tx_h = self.w3.eth.send_raw_transaction(signed_tx.raw_transaction)
-            print(f"⏳ Waiting for approval confirmation: {self.w3.to_hex(tx_h)}...")
-            self.w3.eth.wait_for_transaction_receipt(tx_h)
-            time.sleep(1) # Extra buffer for indexers
+            
+        self.w3.eth.wait_for_transaction_receipt(tx_h, timeout=60)
+        return self.w3.to_hex(tx_h)
 
-    def _execute_pay(self, router_addr, token_addr, merchant_addr, amount, order_id):
-        router_abi = [{"inputs": [{"name": "t", "type": "address"}, {"name": "m", "type": "address"}, {"name": "a", "type": "uint256"}, {"name": "o", "type": "bytes32"}], "name": "pay", "outputs": [], "stateMutability": "nonpayable", "type": "function"}]
+    def pay_with_permit(
+        self,
+        router_addr: str,
+        payer_address: str,
+        token_addr: str,
+        merchant_addr: str,
+        amount: int,
+        order_id: str,
+        deadline: int,
+        v: int,
+        r: bytes,
+        s: bytes
+    ) -> str:
+        """
+        Execute payment using EIP-2612 Permit — single-tx approve + pay.
+        The payer signs the permit offline, and this Agent relays it on-chain.
+
+        Args:
+            router_addr: PayNode Router contract address
+            payer_address: The address that holds the tokens and signed the permit
+            token_addr: ERC20 token address (must support EIP-2612)
+            merchant_addr: Merchant receiving 99% of payment
+            amount: Token amount in smallest unit (e.g. 1000000 = 1 USDC)
+            order_id: Order identifier string
+            deadline: Unix timestamp after which the permit is invalid
+            v: ECDSA recovery id
+            r: ECDSA signature r component (bytes32)
+            s: ECDSA signature s component (bytes32)
+        """
+        router_abi = [
+            {"inputs": [{"name": "payer", "type": "address"}, {"name": "token", "type": "address"}, {"name": "merchant", "type": "address"}, {"name": "amount", "type": "uint256"}, {"name": "orderId", "type": "bytes32"}, {"name": "deadline", "type": "uint256"}, {"name": "v", "type": "uint8"}, {"name": "r", "type": "bytes32"}, {"name": "s", "type": "bytes32"}], "name": "payWithPermit", "outputs": [], "stateMutability": "nonpayable", "type": "function"}
+        ]
         router = self.w3.eth.contract(address=Web3.to_checksum_address(router_addr), abi=router_abi)
         order_id_bytes = self.w3.keccak(text=order_id)
 
-        # Use 20% higher gas price
         current_gas_price = int(self.w3.eth.gas_price * 1.2)
 
-        tx = router.functions.pay(
-            Web3.to_checksum_address(token_addr),
-            Web3.to_checksum_address(merchant_addr),
-            amount,
-            order_id_bytes
-        ).build_transaction({
-            'from': self.account.address,
-            'nonce': self.w3.eth.get_transaction_count(self.account.address, 'pending'),
-            'gas': 200000,
-            'gasPrice': current_gas_price
-        })
-        signed_tx = self.w3.eth.account.sign_transaction(tx, self.private_key)
-        tx_h = self.w3.eth.send_raw_transaction(signed_tx.raw_transaction)
-        self.w3.eth.wait_for_transaction_receipt(tx_h)
-        return self.w3.to_hex(tx_h)
+        try:
+            with self.nonce_lock:
+                nonce = self.w3.eth.get_transaction_count(self.account.address, 'pending')
+                tx = router.functions.payWithPermit(
+                    Web3.to_checksum_address(payer_address),
+                    Web3.to_checksum_address(token_addr),
+                    Web3.to_checksum_address(merchant_addr),
+                    amount,
+                    order_id_bytes,
+                    deadline,
+                    v,
+                    r,
+                    s
+                ).build_transaction({
+                    'from': self.account.address,
+                    'nonce': nonce,
+                    'gas': 300000,
+                    'gasPrice': current_gas_price
+                })
+                signed_tx = self.account.sign_transaction(tx)
+                tx_h = self.w3.eth.send_raw_transaction(signed_tx.raw_transaction)
+
+            self.w3.eth.wait_for_transaction_receipt(tx_h, timeout=60)
+            logger.info(f"✅ [PayNode-PY] Permit payment confirmed: {self.w3.to_hex(tx_h)}")
+            return self.w3.to_hex(tx_h)
+        except ValueError as e:
+            err_msg = str(e).lower()
+            if "insufficient funds" in err_msg:
+                raise PayNodeException("Insufficient funds for gas.", ErrorCode.INSUFFICIENT_FUNDS)
+            raise PayNodeException(f"Permit transaction failed: {str(e)}", ErrorCode.PERMIT_FAILED)
+        except Exception as e:
+            if isinstance(e, PayNodeException):
+                raise
+            raise PayNodeException(f"Permit payment error: {str(e)}", ErrorCode.INTERNAL_ERROR)

paynode_sdk/constants.py

@@ -1,5 +1,14 @@
-PAYNODE_ROUTER_ADDRESS = "0xA88B5eaD188De39c015AC51F45E1B41D3d95f2bb"
-PAYNODE_ROUTER_ADDRESS_SANDBOX = "0x1E12700393D3222BC451fb0aEe7351E4eB6779b1"
+# Generated by scripts/sync-config.py
+PAYNODE_ROUTER_ADDRESS = "0x92e20164FC457a2aC35f53D06268168e6352b200"
+PAYNODE_ROUTER_ADDRESS_SANDBOX = "0xB587Bc36aaCf65962eCd6Ba59e2DA76f2f575408"
 BASE_USDC_ADDRESS = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
 BASE_USDC_ADDRESS_SANDBOX = "0xeAC1f2C7099CdaFfB91Aa3b8Ffd653Ef16935798"
 BASE_USDC_DECIMALS = 6
+
+PROTOCOL_TREASURY = "0x598bF63F5449876efafa7b36b77Deb2070621C0E"
+PROTOCOL_FEE_BPS = 100
+
+ACCEPTED_TOKENS = {
+    8453: ["0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2"],
+    84532: ["0xeAC1f2C7099CdaFfB91Aa3b8Ffd653Ef16935798"]
+}

paynode_sdk/errors.py

@@ -13,8 +13,10 @@ class ErrorCode(str, Enum):
     WRONG_CONTRACT = 'PAYNODE_WRONG_CONTRACT'
     WRONG_MERCHANT = 'PAYNODE_WRONG_MERCHANT'
     WRONG_TOKEN = 'PAYNODE_WRONG_TOKEN'
+    TOKEN_NOT_ACCEPTED = 'PAYNODE_TOKEN_NOT_ACCEPTED'
     INSUFFICIENT_FUNDS = 'PAYNODE_INSUFFICIENT_FUNDS'
     ORDER_MISMATCH = 'PAYNODE_ORDER_MISMATCH'
+    PERMIT_FAILED = 'PAYNODE_PERMIT_FAILED'
     
     # System
     RPC_ERROR = 'PAYNODE_RPC_ERROR'

paynode_sdk/verifier.py

@@ -1,36 +1,100 @@
-from .errors import ErrorCode
-from unittest.mock import MagicMock
+from .errors import ErrorCode, PayNodeException
+from .constants import PAYNODE_ROUTER_ABI, ACCEPTED_TOKENS
+from .idempotency import MemoryIdempotencyStore
+from web3 import Web3
 
 class PayNodeVerifier:
-    def __init__(self, rpc_url=None, contract_address=None, chain_id=None, w3=None):
-        self.w3 = w3 or MagicMock()
+    def __init__(self, rpc_url=None, contract_address=None, chain_id=None, w3=None, store=None, accepted_tokens=None):
+        self.w3 = w3
+        if not self.w3 and rpc_url:
+            self.w3 = Web3(Web3.HTTPProvider(rpc_url))
         self.contract_address = contract_address
-        self.used_receipts = set()
+        self.chain_id = int(chain_id) if chain_id else None
+        self.store = store or MemoryIdempotencyStore()
+
+        # Build accepted token set: user-provided or chain-default
+        # accepted_tokens=None → use chain default; accepted_tokens=[] → explicitly disable whitelist
+        if accepted_tokens is not None:
+            token_list = accepted_tokens
+        elif self.chain_id:
+            token_list = ACCEPTED_TOKENS.get(self.chain_id)
+        else:
+            token_list = None
+        self.accepted_tokens = set(t.lower() for t in token_list) if token_list else None
 
     async def verify_payment(self, tx_hash, expected):
-        if tx_hash in self.used_receipts:
-            return {"isValid": False, "error": MagicError(ErrorCode.TRANSACTION_NOT_FOUND if "Used" not in str(tx_hash) else ErrorCode.RECEIPT_ALREADY_USED)}
-        
-        # 兼容性修复：根据枚举实际名称调整
+        if not self.w3:
+            return {"isValid": False, "error": PayNodeException("Verifier Provider Missing", ErrorCode.RPC_ERROR)}
+
+        # 0. Token Whitelist Check (Anti-FakeToken)
+        expected_token = expected.get("tokenAddress", "").lower()
+        if self.accepted_tokens and expected_token not in self.accepted_tokens:
+            return {"isValid": False, "error": PayNodeException(
+                f"Token {expected.get('tokenAddress')} is not in the accepted whitelist.",
+                ErrorCode.TOKEN_NOT_ACCEPTED
+            )}
+
         try:
-            err_code = ErrorCode.RECEIPT_ALREADY_USED
-        except AttributeError:
-            err_code = ErrorCode.PAYNODE_RECEIPT_ALREADY_USED
+            is_new = await self.store.check_and_set(tx_hash, 86400) # 24 hour TTL
+            if not is_new:
+                return {"isValid": False, "error": PayNodeException("Receipt already used", ErrorCode.RECEIPT_ALREADY_USED)}
+        except Exception as e:
+            return {"isValid": False, "error": PayNodeException("Store Error", ErrorCode.INTERNAL_ERROR, details=str(e))}
+
+        try:
+            receipt = self.w3.eth.get_transaction_receipt(tx_hash)
+        except Exception:
+            return {"isValid": False, "error": PayNodeException("Transaction not found", ErrorCode.TRANSACTION_NOT_FOUND)}
 
-        if tx_hash == "0xUsedHash":
-             return {"isValid": False, "error": MagicError(err_code)}
-        
-        receipt = self.w3.eth.get_transaction_receipt(tx_hash)
         if not receipt:
-            try: return {"isValid": False, "error": MagicError(ErrorCode.TRANSACTION_NOT_FOUND)}
-            except AttributeError: return {"isValid": False, "error": MagicError(ErrorCode.PAYNODE_TRANSACTION_NOT_FOUND)}
+            return {"isValid": False, "error": PayNodeException("Transaction not found", ErrorCode.TRANSACTION_NOT_FOUND)}
         
         if receipt.get("status") == 0:
-            try: return {"isValid": False, "error": MagicError(ErrorCode.TRANSACTION_FAILED)}
-            except AttributeError: return {"isValid": False, "error": MagicError(ErrorCode.PAYNODE_TRANSACTION_FAILED)}
+            return {"isValid": False, "error": PayNodeException("Transaction failed", ErrorCode.TRANSACTION_FAILED)}
 
-        return {"isValid": True}
+        if not receipt.get("to") or receipt.get("to", "").lower() != self.contract_address.lower():
+            return {"isValid": False, "error": PayNodeException("Wrong contract", ErrorCode.WRONG_CONTRACT)}
 
-class MagicError:
-    def __init__(self, code):
-        self.code = code
+        contract = self.w3.eth.contract(address=Web3.to_checksum_address(self.contract_address), abi=PAYNODE_ROUTER_ABI)
+        
+        try:
+            logs = contract.events.PaymentReceived().process_receipt(receipt)
+        except Exception:
+            return {"isValid": False, "error": PayNodeException("Invalid receipt format", ErrorCode.INVALID_RECEIPT)}
+
+        if not logs:
+            return {"isValid": False, "error": PayNodeException("No valid PaymentReceived event found", ErrorCode.INVALID_RECEIPT)}
+
+        # Find the valid log
+        merchant = expected.get("merchantAddress", "").lower()
+        token = expected.get("tokenAddress", "").lower()
+        amount = int(expected.get("amount", 0))
+        
+        order_id_bytes = self.w3.keccak(text=expected.get("orderId", ""))
+
+        valid = False
+        for log in logs:
+            args = log.args
+            
+            if args.get("orderId") != order_id_bytes:
+                continue
+                
+            if args.get("merchant", "").lower() != merchant:
+                continue
+                
+            if args.get("token", "").lower() != token:
+                continue
+                
+            if args.get("amount", 0) < amount:
+                continue
+
+            if self.chain_id and args.get("chainId") != self.chain_id:
+                continue
+
+            valid = True
+            break
+
+        if not valid:
+            return {"isValid": False, "error": PayNodeException("Payment criteria mismatch", ErrorCode.INVALID_RECEIPT)}
+
+        return {"isValid": True}

paynode_sdk/webhook.py

@@ -0,0 +1,233 @@
+"""
+PayNode Webhook Notifier — monitors on-chain PaymentReceived events
+and delivers structured webhook POSTs to a merchant's endpoint.
+
+Features:
+- HMAC-SHA256 signature for authenticity (header: x-paynode-signature)
+- Configurable polling interval
+- Automatic retry with exponential backoff (3 attempts)
+- Async-first design
+"""
+
+import json
+import time
+import hmac
+import hashlib
+import logging
+import asyncio
+from typing import Optional, Callable, Dict, Any, List
+from web3 import Web3
+
+from .constants import PAYNODE_ROUTER_ABI, PAYNODE_ROUTER_ADDRESS
+from .errors import PayNodeException, ErrorCode
+
+logger = logging.getLogger("paynode_sdk.webhook")
+
+
+class PaymentEvent:
+    """Parsed PaymentReceived event data."""
+
+    def __init__(
+        self,
+        tx_hash: str,
+        block_number: int,
+        order_id: str,
+        merchant: str,
+        payer: str,
+        token: str,
+        amount: int,
+        fee: int,
+        chain_id: int,
+        timestamp: float
+    ):
+        self.tx_hash = tx_hash
+        self.block_number = block_number
+        self.order_id = order_id
+        self.merchant = merchant
+        self.payer = payer
+        self.token = token
+        self.amount = amount
+        self.fee = fee
+        self.chain_id = chain_id
+        self.timestamp = timestamp
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "txHash": self.tx_hash,
+            "blockNumber": self.block_number,
+            "orderId": self.order_id,
+            "merchant": self.merchant,
+            "payer": self.payer,
+            "token": self.token,
+            "amount": str(self.amount),
+            "fee": str(self.fee),
+            "chainId": str(self.chain_id),
+            "timestamp": self.timestamp,
+        }
+
+
+class PayNodeWebhookNotifier:
+    """
+    Monitors on-chain PaymentReceived events and delivers webhook notifications.
+
+    Usage:
+        notifier = PayNodeWebhookNotifier(
+            rpc_url="https://mainnet.base.org",
+            contract_address="0x92e20164FC457a2aC35f53D06268168e6352b200",
+            webhook_url="https://myshop.com/api/paynode-webhook",
+            webhook_secret="whsec_mysecretkey123",
+        )
+        await notifier.start()
+    """
+
+    def __init__(
+        self,
+        rpc_url: str,
+        webhook_url: str,
+        webhook_secret: str,
+        contract_address: Optional[str] = None,
+        chain_id: Optional[int] = None,
+        poll_interval_seconds: float = 5.0,
+        custom_headers: Optional[Dict[str, str]] = None,
+        on_error: Optional[Callable[[Exception, PaymentEvent], None]] = None,
+        on_success: Optional[Callable[[PaymentEvent], None]] = None,
+    ):
+        if not rpc_url:
+            raise ValueError("rpc_url is required")
+        if not webhook_url:
+            raise ValueError("webhook_url is required")
+        if not webhook_secret:
+            raise ValueError("webhook_secret is required")
+
+        self.contract_address = contract_address or PAYNODE_ROUTER_ADDRESS
+        self.w3 = Web3(Web3.HTTPProvider(rpc_url, request_kwargs={"timeout": 10}))
+        self.contract = self.w3.eth.contract(
+            address=Web3.to_checksum_address(self.contract_address),
+            abi=PAYNODE_ROUTER_ABI
+        )
+        self.webhook_url = webhook_url
+        self.webhook_secret = webhook_secret
+        self.chain_id = chain_id
+        self.poll_interval = poll_interval_seconds
+        self.custom_headers = custom_headers or {}
+        self.on_error = on_error
+        self.on_success = on_success
+
+        self._last_block: int = 0
+        self._running: bool = False
+        self._task: Optional[asyncio.Task] = None
+
+    async def start(self, from_block: Optional[int] = None) -> None:
+        """Start polling for PaymentReceived events."""
+        if self._running:
+            logger.warning("[PayNode Webhook] Already running.")
+            return
+
+        self._last_block = from_block if from_block is not None else self.w3.eth.block_number
+        self._running = True
+        logger.info(f"🔔 [PayNode Webhook] Listening from block {self._last_block} on {self.contract_address}")
+
+        self._task = asyncio.create_task(self._poll_loop())
+
+    async def stop(self) -> None:
+        """Stop polling."""
+        self._running = False
+        if self._task:
+            self._task.cancel()
+            try:
+                await self._task
+            except asyncio.CancelledError:
+                pass
+            self._task = None
+        logger.info("🔕 [PayNode Webhook] Stopped.")
+
+    async def _poll_loop(self) -> None:
+        """Main polling loop."""
+        while self._running:
+            try:
+                current_block = self.w3.eth.block_number
+                if current_block > self._last_block:
+                    events = self.contract.events.PaymentReceived().get_logs(
+                        fromBlock=self._last_block + 1,
+                        toBlock=current_block
+                    )
+                    for event in events:
+                        payment = self._parse_event(event)
+                        if payment:
+                            await self._deliver(payment)
+
+                    self._last_block = current_block
+            except Exception as e:
+                logger.error(f"[PayNode Webhook] Poll error: {e}")
+
+            await asyncio.sleep(self.poll_interval)
+
+    def _parse_event(self, event) -> Optional[PaymentEvent]:
+        """Parse a web3 event log into a PaymentEvent."""
+        try:
+            args = event.args
+            return PaymentEvent(
+                tx_hash=event.transactionHash.hex() if hasattr(event.transactionHash, 'hex') else str(event.transactionHash),
+                block_number=event.blockNumber,
+                order_id=args.get("orderId", b"").hex() if isinstance(args.get("orderId"), bytes) else str(args.get("orderId", "")),
+                merchant=args.get("merchant", ""),
+                payer=args.get("payer", ""),
+                token=args.get("token", ""),
+                amount=args.get("amount", 0),
+                fee=args.get("fee", 0),
+                chain_id=args.get("chainId", 0),
+                timestamp=time.time(),
+            )
+        except Exception as e:
+            logger.error(f"[PayNode Webhook] Failed to parse event: {e}")
+            return None
+
+    async def _deliver(self, event: PaymentEvent, attempt: int = 1) -> None:
+        """Deliver webhook POST with HMAC signature and retry logic."""
+        import aiohttp  # lazy import to keep dependency optional
+
+        MAX_RETRIES = 3
+
+        payload = json.dumps({
+            "event": "payment.received",
+            "data": event.to_dict()
+        })
+
+        signature = hmac.new(
+            self.webhook_secret.encode("utf-8"),
+            payload.encode("utf-8"),
+            hashlib.sha256
+        ).hexdigest()
+
+        headers = {
+            "Content-Type": "application/json",
+            "x-paynode-signature": f"sha256={signature}",
+            "x-paynode-event": "payment.received",
+            "x-paynode-delivery-id": f"{event.tx_hash}-{attempt}",
+            **self.custom_headers,
+        }
+
+        try:
+            async with aiohttp.ClientSession() as session:
+                async with session.post(self.webhook_url, data=payload, headers=headers, timeout=aiohttp.ClientTimeout(total=10)) as resp:
+                    if resp.status >= 400:
+                        raise PayNodeException(
+                            f"Webhook returned {resp.status}",
+                            ErrorCode.INTERNAL_ERROR
+                        )
+
+                    logger.info(f"✅ [PayNode Webhook] Delivered tx {event.tx_hash[:10]}... → {resp.status}")
+                    if self.on_success:
+                        self.on_success(event)
+
+        except Exception as e:
+            logger.error(f"[PayNode Webhook] Delivery failed (attempt {attempt}/{MAX_RETRIES}): {e}")
+
+            if attempt < MAX_RETRIES:
+                backoff = (2 ** attempt)  # 2s, 4s, 8s
+                await asyncio.sleep(backoff)
+                return await self._deliver(event, attempt + 1)
+
+            logger.error(f"[PayNode Webhook] Gave up on tx {event.tx_hash} after {MAX_RETRIES} attempts.")
+            if self.on_error:
+                self.on_error(e, event)

paynode_sdk_python-1.1.0.dist-info/METADATA

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: paynode-sdk-python
+Version: 1.1.0
+Summary: PayNode Protocol Python SDK for AI Agents
+Author-email: PayNodeLabs <contact@paynode.dev>
+License: MIT
+Project-URL: Homepage, https://github.com/PayNodeLabs/paynode-sdk-python
+Keywords: paynode,x402,base,agentic-web3,payments
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.31.0
+Requires-Dist: web3>=6.15.0
+Requires-Dist: python-dotenv>=1.0.1
+
+# PayNode Python SDK
+
+[![Official Documentation](https://img.shields.io/badge/Docs-docs.paynode.dev-00ff88?style=for-the-badge&logo=readthedocs)](https://docs.paynode.dev)
+[![PyPI Version](https://img.shields.io/pypi/v/paynode-sdk-python.svg?style=for-the-badge)](https://pypi.org/project/paynode-sdk-python/)
+
+The official Python SDK for the **PayNode Protocol**. PayNode allows autonomous AI Agents to seamlessly pay for APIs and computational resources using USDC on Base L2, utilizing the standardized HTTP 402 protocol.
+
+## 📖 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
+pip install paynode-sdk-python web3
+```
+
+### Agent Client (Payer)
+
+```python
+from paynode_sdk import Client
+
+agent = Client(private_key="YOUR_AGENT_PRIVATE_KEY")
+
+# Automatically handles the 402 challenge, executes the Base L2 transaction, and gets the data.
+response = agent.get("https://api.merchant.com/premium-data")
+
+print(response.json())
+```
+
+### Merchant Middleware (FastAPI Receiver)
+
+```python
+from fastapi import FastAPI, Depends
+from paynode_sdk.middleware import PayNodeMiddleware
+
+app = FastAPI()
+
+# Protect routes with a 1.50 USDC fee requirement
+require_payment = PayNodeMiddleware(
+    price=1.50, 
+    merchant_wallet="0xYourWalletAddress..."
+)
+
+@app.get("/premium-data", dependencies=[Depends(require_payment)])
+def get_premium_data():
+    return {"secret": "This is paid M2M data."}
+```
+
+---
+*Built for the Autonomous AI Economy by PayNodeLabs.*

paynode_sdk_python-1.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+paynode_sdk/__init__.py,sha256=dK8m7FfOsWUJakKqHaY44x-xC-uUWVwDrXa0G_zUs8E,562
+paynode_sdk/client.py,sha256=NWzsb9OryI5EEld-L-svQHk6sVwbCulepB7xSIAVr6A,10777
+paynode_sdk/constants.py,sha256=kmE45nR7XKUwn-FEt8CvcvzH3VoQbT-MD2mt71LPVEk,621
+paynode_sdk/errors.py,sha256=LaTwDJxinKYd2UD58lyANRm-rLXF3KSb1XHvIKOcgt0,1075
+paynode_sdk/idempotency.py,sha256=od7HuSxFdejBP0oE4QCzbJdrDZWvziiu09d3BRErU2k,999
+paynode_sdk/middleware.py,sha256=dg3hSmHAjW8wTF3AH3id8LFxbN2kXKKUsBRp1gyc6qw,3292
+paynode_sdk/verifier.py,sha256=huMXbBF361Yj9HLehaY34ToGBrYSuy5Uy8Jau3Seg7k,4414
+paynode_sdk/webhook.py,sha256=KxlXGkXe3wpR8ueO8FMW2iypJgWaLwMfxAAZLNRvNDo,8302
+paynode_sdk_python-1.1.0.dist-info/METADATA,sha256=_18F4H7sRGtdYA9-lA7kdEiO_n2Xnrv6Y_8XN-nj1VQ,2087
+paynode_sdk_python-1.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+paynode_sdk_python-1.1.0.dist-info/top_level.txt,sha256=c6Skc1Xx-9O-JJ7sHghLW8Kyn4hyJoVPUawH1Mu8iTU,12
+paynode_sdk_python-1.1.0.dist-info/RECORD,,

paynode_sdk_python-1.0.1.dist-info/METADATA

@@ -1,85 +0,0 @@
-Metadata-Version: 2.4
-Name: paynode-sdk-python
-Version: 1.0.1
-Summary: PayNode Protocol Python SDK for AI Agents
-Author-email: PayNodeLabs <contact@paynode.dev>
-License: MIT
-Project-URL: Homepage, https://github.com/PayNodeLabs/paynode-sdk-python
-Keywords: paynode,x402,base,agentic-web3,payments
-Description-Content-Type: text/markdown
-Requires-Dist: requests>=2.31.0
-Requires-Dist: web3>=6.15.0
-Requires-Dist: python-dotenv>=1.0.1
-
-# PayNode Python SDK
-
-为 Python 开发者提供的 PayNode 支付网关 SDK，支持 FastAPI、Flask 等主流 Web 框架。实现 M2M 场景下的 x402 握手与链上支付验证。
-
-## 📦 安装
-
-```bash
-pip install paynode-sdk
-```
-
-## 🚀 FastAPI Middleware 初始化示例
-
-通过注入 `PayNodeMiddleware`，您可以轻松地将任何 API 端点转变为收费接口。
-
-```python
-from fastapi import FastAPI, Request
-from paynode_sdk import PayNodeMiddleware
-
-app = FastAPI()
-
-# 1. 初始化 PayNode 中间件
-paynode = PayNodeMiddleware(
-    rpc_url="https://mainnet.base.org",           # RPC 节点地址
-    contract_address="0x...",                     # PayNodeRouter 合约地址
-    merchant_address="0x...",                     # 商家收款钱包地址
-    chain_id=8453,                                # 链 ID (Base: 8453)
-    currency="USDC",                              # 计价单位
-    token_address="0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", # USDC 地址
-    price="0.01",                                 # 每次调用的价格
-    decimals=6                                    # 代币精度
-)
-
-# 2. 挂载中间件
-@app.middleware("http")
-async def paynode_gate(request: Request, call_next):
-    # 此中间件会自动处理 402 握手及 x-paynode-receipt 验证
-    return await paynode(request, call_next)
-
-# 3. 受保护的路由
-@app.get("/api/ai-vision")
-async def ai_feature():
-    return {"message": "Success! The agent has paid for this API call."}
-```
-
-## 🧪 测试与开发
-
-SDK 采用严谨的代码审计标准，所有核心逻辑均经过多层验证。
-
-### 运行测试
-
-使用 `pytest` 运行测试套件。确保已配置 `PYTHONPATH` 以正确加载本地包。
-
-```bash
-# 运行所有验证逻辑测试
-PYTHONPATH=. pytest tests/
-```
-
-### 开发模式
-
-如果需要修改 `paynode_sdk` 并即时测试：
-
-```bash
-pip install -e .
-```
-
-## ⚙️ 验证逻辑详解 (Verifier)
-
-`PayNodeVerifier` 直接通过 Web3.py 与以太坊节点交互。验证过程包括：
-- **交易状态确认:** 检查交易哈希是否已上链并成功 (Status 1)。
-- **合约交互验证:** 解析交易数据，确认其调用的是 `PayNodeRouter` 的 `pay` 函数。
-- **金额与代币校验:** 严格匹配转账金额与指定的代币地址，防止恶意 Agent 使用虚假代币支付。
-- **商户一致性:** 确认资金最终流向了预设的商户钱包。

paynode_sdk_python-1.0.1.dist-info/RECORD

@@ -1,11 +0,0 @@
-paynode_sdk/__init__.py,sha256=qIoMcnfe3dviK6E3E0yMYukuvbO3Nmv0Cpuaeptgx3s,325
-paynode_sdk/client.py,sha256=3_Rux6DZyR6dABLjYaAtBmBtPczlLVpyvuDXc6UzFuQ,4933
-paynode_sdk/constants.py,sha256=1WHbiwQSrSUI6jj4xo7ISak_X0eDZMgFnCbeLzUl3JM,309
-paynode_sdk/errors.py,sha256=ZiuYEvP8zMXpfmi3VEdGyBX3VXqj4TdrRS-WucrdSew,977
-paynode_sdk/idempotency.py,sha256=od7HuSxFdejBP0oE4QCzbJdrDZWvziiu09d3BRErU2k,999
-paynode_sdk/middleware.py,sha256=dg3hSmHAjW8wTF3AH3id8LFxbN2kXKKUsBRp1gyc6qw,3292
-paynode_sdk/verifier.py,sha256=YkYUBgt5RPXigZsHNvdcca290YQyoOVijIa6f5SlHLw,1572
-paynode_sdk_python-1.0.1.dist-info/METADATA,sha256=EcJUyKLTNco58bzxeuzOEd73Fvp3ScRS8SsVYwB9OHk,2852
-paynode_sdk_python-1.0.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-paynode_sdk_python-1.0.1.dist-info/top_level.txt,sha256=c6Skc1Xx-9O-JJ7sHghLW8Kyn4hyJoVPUawH1Mu8iTU,12
-paynode_sdk_python-1.0.1.dist-info/RECORD,,