paynode-sdk-python 1.4.0__py3-none-any.whl → 2.1.0__py3-none-any.whl

paynode_sdk/__init__.py

@@ -8,7 +8,7 @@ warnings.filterwarnings("ignore", category=DeprecationWarning, module="websocket
 from .middleware import PayNodeMiddleware, x402_gate
 from .verifier import PayNodeVerifier
 from .errors import ErrorCode, PayNodeException
-from .idempotency import IdempotencyStore, MemoryIdempotencyStore
+from .idempotency import IdempotencyStore, MemoryIdempotencyStore, RedisIdempotencyStore
 from .webhook import PayNodeWebhookNotifier, PaymentEvent
 from .client import PayNodeAgentClient
 from .constants import (
@@ -22,7 +22,7 @@ from .constants import (
 
 __all__ = [
     "PayNodeMiddleware", "x402_gate", "PayNodeVerifier", "ErrorCode", "PayNodeException",
-    "IdempotencyStore", "MemoryIdempotencyStore",
+    "IdempotencyStore", "MemoryIdempotencyStore", "RedisIdempotencyStore",
     "PayNodeWebhookNotifier", "PaymentEvent",
     "PayNodeAgentClient",
     "PAYNODE_ROUTER_ADDRESS", "PAYNODE_ROUTER_ADDRESS_SANDBOX",

paynode_sdk/client.py

@@ -1,25 +1,28 @@
 import time
 import logging
 import threading
+from concurrent.futures import ThreadPoolExecutor, as_completed
 import requests
+from urllib.parse import urlparse
 from eth_account.messages import encode_typed_data
 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, BASE_RPC_URLS, ACCEPTED_TOKENS
+from .constants import PAYNODE_ROUTER_ADDRESS, BASE_USDC_ADDRESS, BASE_USDC_DECIMALS, BASE_RPC_URLS, ACCEPTED_TOKENS, MIN_PAYMENT_AMOUNT, PAYNODE_ROUTER_ABI
 from .errors import PayNodeException, ErrorCode
 
 logger = logging.getLogger("paynode_sdk.client")
 
 class PayNodeAgentClient:
     """
-    The main PayNode Client for AI Agents (v1.1.1).
+    The main PayNode Client for AI Agents (v3.1).
     Automatically handles the x402 'Payment Required' handshake.
-    Supports RPC redundancy and EIP-2612 Permit-First payments.
+    Supports RPC redundancy, EIP-2612 Permit, and EIP-3009 Authorization.
     """
     def __init__(self, private_key: str, rpc_urls: list | str = BASE_RPC_URLS):
         self.rpc_urls = rpc_urls if isinstance(rpc_urls, list) else [rpc_urls]
         self.w3 = self._init_w3()
+        self.current_rpc_index = 0
         
         # Initialize account and discard private key string
         self.account = self.w3.eth.account.from_key(private_key)
@@ -37,16 +40,45 @@ class PayNodeAgentClient:
         self.session.mount("http://", adapter)
 
     def _init_w3(self):
-        """Finds a working RPC from the list."""
-        for rpc in self.rpc_urls:
+        """Finds a working RPC from the list concurrently (Faster initialization)."""
+        
+        def _check_rpc(rpc_url):
+            try:
+                temp_w3 = Web3(Web3.HTTPProvider(rpc_url, request_kwargs={'timeout': 3}))
+                if temp_w3.is_connected():
+                    return temp_w3
+                return None
+            except Exception:
+                return None
+
+        with ThreadPoolExecutor(max_workers=min(len(self.rpc_urls), 5)) as executor:
+            future_to_url = {executor.submit(_check_rpc, url): url for url in self.rpc_urls}
+            # Return the first one that succeeds
+            for future in as_completed(future_to_url):
+                w3_instance = future.result()
+                if w3_instance:
+                    logger.debug(f"⚡ [PayNode-PY] Connected to RPC: {future_to_url[future]}")
+                    return w3_instance
+                    
+        raise PayNodeException(ErrorCode.rpc_error, message="All provided RPC nodes are unreachable.")
+
+    def _rotate_rpc(self):
+        """Switches to the next available RPC node in the list."""
+        self.current_rpc_index = (self.current_rpc_index + 1) % len(self.rpc_urls)
+        new_url = self.rpc_urls[self.current_rpc_index]
+        logger.warning(f"⚠️ [PayNode-PY] RPC failure detected. Rotating to: {new_url}")
+        self.w3 = Web3(Web3.HTTPProvider(new_url, request_kwargs={'timeout': 10}))
+
+    def _call_with_failover(self, func, *args, **kwargs):
+        """Wrapper to retry a web3 call with RPC failover."""
+        for attempt in range(len(self.rpc_urls)):
             try:
-                w3 = Web3(Web3.HTTPProvider(rpc, request_kwargs={'timeout': 5}))
-                if w3.is_connected():
-                    return w3
+                return func(*args, **kwargs)
             except Exception as e:
-                logger.warning(f"⚠️ [PayNode-PY] RPC {rpc} failed: {str(e)}")
-                continue
-        raise PayNodeException(ErrorCode.rpc_error)
+                if attempt < len(self.rpc_urls) - 1:
+                    self._rotate_rpc()
+                else:
+                    raise e
 
     def request_gate(self, url: str, method: str = "GET", **kwargs):
         """The high-level autonomous method handling 402 loop."""
@@ -58,84 +90,215 @@ class PayNodeAgentClient:
     def post(self, url, **kwargs):
         return self.request_gate(url, "POST", **kwargs)
 
-    def _request_with_402_retry(self, method, url, max_retries=3, **kwargs):
-        for _ in range(max_retries):
+    def _request_with_402_retry(self, method: str, url: str, max_retries: int = 3, **kwargs) -> requests.Response:
+        response = None
+        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(ErrorCode.internal_error, message=f"An unexpected error occurred: {str(e)}")
-                continue
+                logger.info(f"💡 [PayNode-PY] 402 Detected (Attempt {attempt+1}/{max_retries}). Analyzing protocol version...")
+                
+                # Check for x402 v2 (JSON body or X-402-Required header)
+                content_type = response.headers.get('Content-Type', '')
+                b64_required = response.headers.get('X-402-Required')
+                order_id = response.headers.get('X-402-Order-Id')
+                
+                body = None
+                if 'application/json' in content_type:
+                    try:
+                        body = response.json()
+                    except Exception as e:
+                        logger.debug(f"⚠️ [PayNode-PY] Failed to parse 402 JSON body: {e}")
+                
+                if not body and b64_required:
+                    try:
+                        import base64
+                        import json
+                        body = json.loads(base64.b64decode(b64_required).decode())
+                    except Exception as e:
+                        logger.warning(f"❌ [PayNode-PY] Failed to decode X-402-Required header: {e}")
+
+                if body and body.get('x402Version') == 2:
+                    logger.info("🚀 [PayNode-PY] x402 v2 detected. Handling autonomous payment...")
+                    if order_id: body['orderId'] = order_id
+                    kwargs = self._handle_x402_v2(url, body, **kwargs)
+                    continue
+
+                raise PayNodeException(ErrorCode.internal_error, message="Unsupported or malformed 402 response")
+            
             return response
+
+        if response and response.status_code == 402:
+            raise PayNodeException(ErrorCode.internal_error, message="Still 402 after all payment attempts. The server may have rejected the payment or authorization.")
         return response
 
-    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')
-        currency = headers.get('x-paynode-currency', 'USDC')
-        chain_id_header = headers.get('x-paynode-chain-id')
-
-        if not all([router_addr, merchant_addr, amount_raw, token_addr, order_id]):
-            raise PayNodeException(ErrorCode.internal_error, message="Malformed 402 headers: missing metadata")
-
-        # Network safety check (v1.4)
-        if chain_id_header:
-            current_chain_id = self.w3.eth.chain_id
-            if int(chain_id_header) != current_chain_id:
-                raise PayNodeException(ErrorCode.invalid_receipt, message=f"Network mismatch: Current {current_chain_id}, Request {chain_id_header}.")
-
-        logger.info(f"💡 [PayNode-PY] Payment request: {amount_raw} {currency} to {merchant_addr}")
-
-        # v1.3 Constraint: Min payment protection
-        if amount_raw < 1000:
-            raise PayNodeException(ErrorCode.amount_too_low)
-
-        # v1.4 Constraint: Token whitelist pre-flight (Anti-FakeToken)
-        resolved_chain_id = int(chain_id_header) if chain_id_header else 8453
-        whitelist = ACCEPTED_TOKENS.get(resolved_chain_id, [])
-        if whitelist and token_addr and token_addr.lower() not in [t.lower() for t in whitelist]:
-            raise PayNodeException(ErrorCode.token_not_accepted)
-
-        # Protocol v1.3: Permit-First Execution
-        try:
-            # Check allowance first to decide if we need Permit
-            allowance = self._get_allowance(token_addr, router_addr)
-            if allowance >= amount_raw:
-                tx_hash = self._execute_pay(router_addr, token_addr, merchant_addr, amount_raw, order_id)
+    def _handle_x402_v2(self, url: str, requirements: dict, **kwargs) -> dict:
+        """
+        Internal handler for X402 V2/V3.1 protocol.
+        Analyzes requirements, executes payment, and returns updated kwargs for retrying the request.
+        """
+        chain_id = self.w3.eth.chain_id
+        caip2_chain_id = f"eip155:{chain_id}"
+
+        # Select suitable requirement
+        requirement = next((req for req in requirements.get('accepts', []) 
+                         if req.get('network') == caip2_chain_id), None)
+
+        if not requirement:
+            raise PayNodeException(ErrorCode.internal_error, message=f"No compatible payment requirement found for network {caip2_chain_id}")
+
+        # 🛡️ Token Whitelist Check
+        chain_tokens = ACCEPTED_TOKENS.get(chain_id, [])
+        if chain_tokens and requirement.get('asset').lower() not in [t.lower() for t in chain_tokens]:
+            raise PayNodeException(ErrorCode.token_not_accepted, message=f"Token {requirement['asset']} is not in the whitelist for chain {chain_id}")
+
+        logger.info(f"💡 [PayNode-PY] Payment request (v2): {requirement['amount']} atomic units of {requirement['asset']} to {requirement['payTo']}")
+        
+        # Dust limit check
+        if int(requirement['amount']) < MIN_PAYMENT_AMOUNT:
+            raise PayNodeException(ErrorCode.amount_too_low, message=f"Payment amount {requirement['amount']} is below the minimum dust limit of {MIN_PAYMENT_AMOUNT}")
+
+        order_id = requirement.get('orderId') or requirements.get('orderId') or urlparse(url).path
+        
+        payload_data = {}
+        ptype = requirement.get('type', 'onchain')
+
+        if ptype == 'eip3009':
+            valid_after = int(time.time()) - 60
+            valid_before = int(time.time()) + requirement.get('maxTimeoutSeconds', 3600)
+            import os
+            nonce = "0x" + os.urandom(32).hex()
+
+            try:
+                payload_data = self.sign_transfer_with_authorization(
+                    requirement['asset'],
+                    requirement['payTo'],
+                    int(requirement['amount']),
+                    valid_after,
+                    valid_before,
+                    nonce,
+                    requirement.get('extra', {})
+                )
+            except Exception as e:
+                raise PayNodeException(ErrorCode.transaction_failed, message="Failed to sign payment authorization", details=e)
+        else:
+            # type: 'onchain'
+            router_addr = requirement.get('router')
+            if not router_addr:
+                raise PayNodeException(ErrorCode.internal_error, message="On-chain payment required but no router address provided.")
+
+            logger.info(f"⚡ [PayNode-PY] Executing on-chain payment to {requirement['payTo']}...")
+            amount = int(requirement['amount'])
+            asset = requirement['asset']
+            allowance = self._get_allowance(asset, router_addr)
+
+            if allowance >= amount:
+                try:
+                    tx_hash = self.pay(router_addr, asset, requirement['payTo'], amount, order_id)
+                except Exception as e:
+                    logger.warning(f"⚠️ [PayNode-PY] Direct pay failed (possibly allowance race), falling back to permit: {e}")
+                    tx_hash = self.pay_with_permit(router_addr, asset, requirement['payTo'], amount, order_id, version=requirement.get('extra', {}).get('version', '2'))
             else:
-                logger.info("⚡ [PayNode-PY] Insufficient allowance. Attempting Permit-First payment...")
-                tx_hash = self.pay_with_permit(router_addr, token_addr, merchant_addr, amount_raw, order_id)
+                tx_hash = self.pay_with_permit(router_addr, asset, requirement['payTo'], amount, order_id, version=requirement.get('extra', {}).get('version', '2'))
             
-            logger.info(f"✅ [PayNode-PY] Payment successful: {tx_hash}")
-        except Exception as e:
-            if isinstance(e, PayNodeException): raise
-            raise PayNodeException(ErrorCode.transaction_failed, details=e)
+            payload_data = {"txHash": tx_hash}
+
+        # Unified Payload for v3.1
+        payment_payload = {
+            "version": "3.1",
+            "type": ptype,
+            "orderId": order_id,
+            "payload": payload_data
+        }
+
+        logger.info(f"✅ [PayNode-PY] {ptype} payment prepared. Retrying request...")
+        
+        import json
+        import base64
+        b64_payload = base64.b64encode(json.dumps(payment_payload).encode()).decode()
 
         retry_headers = kwargs.get('headers', {}).copy()
-        retry_headers.update({'x-paynode-receipt': tx_hash, 'x-paynode-order-id': order_id})
+        retry_headers.update({
+            'Content-Type': 'application/json',
+            'X-402-Payload': b64_payload,
+            'X-402-Order-Id': order_id
+        })
         kwargs['headers'] = retry_headers
         return kwargs
 
+    def sign_transfer_with_authorization(self, token_addr, to, amount, valid_after, valid_before, nonce, extra=None):
+        extra = extra or {}
+        token_addr = Web3.to_checksum_address(token_addr)
+        to = Web3.to_checksum_address(to)
+        
+        domain = {
+            "name": extra.get("name", "USD Coin"),
+            "version": extra.get("version", "2"),
+            "chainId": self.w3.eth.chain_id,
+            "verifyingContract": token_addr,
+        }
+        
+        types = {
+            "EIP712Domain": [
+                {"name": "name", "type": "string"},
+                {"name": "version", "type": "string"},
+                {"name": "chainId", "type": "uint256"},
+                {"name": "verifyingContract", "type": "address"},
+            ],
+            "TransferWithAuthorization": [
+                {"name": "from", "type": "address"},
+                {"name": "to", "type": "address"},
+                {"name": "value", "type": "uint256"},
+                {"name": "validAfter", "type": "uint256"},
+                {"name": "validBefore", "type": "uint256"},
+                {"name": "nonce", "type": "bytes32"},
+            ],
+        }
+        
+        message = {
+            "from": self.account.address,
+            "to": to,
+            "value": int(amount),
+            "validAfter": int(valid_after),
+            "validBefore": int(valid_before),
+            "nonce": Web3.to_bytes(hexstr=nonce),
+        }
+        
+        structured_data = {
+            "types": types,
+            "domain": domain,
+            "primaryType": "TransferWithAuthorization",
+            "message": message,
+        }
+        
+        signed = self.account.sign_typed_data(full_message=structured_data)
+        
+        return {
+            "signature": signed.signature.hex(),
+            "authorization": {
+                "from": self.account.address,
+                "to": to,
+                "value": str(amount),
+                "validAfter": str(valid_after),
+                "validBefore": str(valid_before),
+                "nonce": nonce
+            }
+        }
+
     def _get_allowance(self, token_addr, spender_addr):
+        return self._call_with_failover(self.__get_allowance_raw, token_addr, spender_addr)
+
+    def __get_allowance_raw(self, token_addr, spender_addr):
         abi = [{"constant": True, "inputs": [{"name": "o", "type": "address"}, {"name": "s", "type": "address"}], "name": "allowance", "outputs": [{"name": "", "type": "uint256"}], "type": "function"}]
         token = self.w3.eth.contract(address=Web3.to_checksum_address(token_addr), abi=abi)
         return token.functions.allowance(self.account.address, Web3.to_checksum_address(spender_addr)).call()
 
-    def sign_permit(self, token_addr, spender_addr, amount, deadline=None):
-        """Signs EIP-2612 Permit data."""
+    def sign_permit(self, token_addr: str, spender_addr: str, amount: int, deadline: int = None, version: str = "2"):
         if deadline is None:
             deadline = int(time.time()) + 3600
         
         token_addr = Web3.to_checksum_address(token_addr)
         spender_addr = Web3.to_checksum_address(spender_addr)
         
-        # Get nonce and domain separator
         abi = [
             {"inputs": [{"name": "o", "type": "address"}], "name": "nonces", "outputs": [{"name": "", "type": "uint256"}], "stateMutability": "view", "type": "function"},
             {"inputs": [], "name": "name", "outputs": [{"name": "", "type": "string"}], "stateMutability": "view", "type": "function"}
@@ -145,93 +308,55 @@ class PayNodeAgentClient:
         name = token.functions.name().call()
         chain_id = self.w3.eth.chain_id
 
-        domain = {
-            "name": name,
-            "version": "1",
-            "chainId": chain_id,
-            "verifyingContract": token_addr,
-        }
-        message = {
-            "owner": self.account.address,
-            "spender": spender_addr,
-            "value": amount,
-            "nonce": nonce,
-            "deadline": deadline,
-        }
+        domain = {"name": name, "version": version, "chainId": chain_id, "verifyingContract": token_addr}
+        message = {"owner": self.account.address, "spender": spender_addr, "value": amount, "nonce": nonce, "deadline": deadline}
         types = {
             "EIP712Domain": [
-                {"name": "name", "type": "string"},
-                {"name": "version", "type": "string"},
-                {"name": "chainId", "type": "uint256"},
-                {"name": "verifyingContract", "type": "address"},
+                {"name": "name", "type": "string"}, {"name": "version", "type": "string"},
+                {"name": "chainId", "type": "uint256"}, {"name": "verifyingContract", "type": "address"},
             ],
             "Permit": [
-                {"name": "owner", "type": "address"},
-                {"name": "spender", "type": "address"},
-                {"name": "value", "type": "uint256"},
-                {"name": "nonce", "type": "uint256"},
+                {"name": "owner", "type": "address"}, {"name": "spender", "type": "address"},
+                {"name": "value", "type": "uint256"}, {"name": "nonce", "type": "uint256"},
                 {"name": "deadline", "type": "uint256"},
             ],
         }
+        structured_data = {"types": types, "domain": domain, "primaryType": "Permit", "message": message}
+        signed = self.account.sign_typed_data(full_message=structured_data)
         
-        structured_data = {
-            "types": types,
-            "domain": domain,
-            "primaryType": "Permit",
-            "message": message,
-        }
+        # NOTE: r/s padding to 32 bytes ensures bytes32 compatibility
+        r_bytes = Web3.to_bytes(signed.r).rjust(32, b'\0')
+        s_bytes = Web3.to_bytes(signed.s).rjust(32, b'\0')
         
-        signed = self.account.sign_typed_data(full_message=structured_data)
-        return {
-            "v": signed.v,
-            "r": Web3.to_bytes(signed.r).rjust(32, b'\0'),
-            "s": Web3.to_bytes(signed.s).rjust(32, b'\0'),
-            "deadline": deadline
-        }
+        return {"v": signed.v, "r": r_bytes, "s": s_bytes, "deadline": deadline}
+
+    def pay_with_permit(self, router_addr, token_addr, merchant_addr, amount, order_id, version="2"):
+        return self._call_with_failover(self.__pay_with_permit_raw, router_addr, token_addr, merchant_addr, amount, order_id, version)
 
-    def pay_with_permit(self, router_addr, token_addr, merchant_addr, amount, order_id):
-        """Combines sign_permit and on-chain submission."""
-        sig = self.sign_permit(token_addr, router_addr, amount)
-        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)
+    def __pay_with_permit_raw(self, router_addr, token_addr, merchant_addr, amount, order_id, version="2"):
+        sig = self.sign_permit(token_addr, router_addr, amount, version=version)
+        router = self.w3.eth.contract(address=Web3.to_checksum_address(router_addr), abi=PAYNODE_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.payWithPermit(
-                self.account.address,
-                Web3.to_checksum_address(token_addr),
-                Web3.to_checksum_address(merchant_addr),
-                amount,
-                order_id_bytes,
-                sig["deadline"], sig["v"], sig["r"], sig["s"]
-            ).build_transaction({
-                'from': self.account.address,
-                'nonce': nonce,
-                'gas': 300000,
-                'gasPrice': current_gas_price
-            })
+            tx = router.functions.payWithPermit(self.account.address, Web3.to_checksum_address(token_addr), Web3.to_checksum_address(merchant_addr), amount, order_id_bytes, sig["deadline"], sig["v"], sig["r"], sig["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)
         return self.w3.to_hex(tx_h)
 
-    def _execute_pay(self, router_addr, token_addr, merchant_addr, amount, order_id):
-        """Standard pay method (fallback)."""
-        router_abi = [{"inputs": [{"name": "token", "type": "address"}, {"name": "merchant", "type": "address"}, {"name": "amount", "type": "uint256"}, {"name": "orderId", "type": "bytes32"}], "name": "pay", "outputs": [], "stateMutability": "nonpayable", "type": "function"}]
-        router = self.w3.eth.contract(address=Web3.to_checksum_address(router_addr), abi=router_abi)
+    def pay(self, router_addr, token_addr, merchant_addr, amount, order_id):
+        return self._call_with_failover(self.__pay_raw, router_addr, token_addr, merchant_addr, amount, order_id)
+
+    def __pay_raw(self, router_addr, token_addr, merchant_addr, amount, order_id):
+        router = self.w3.eth.contract(address=Web3.to_checksum_address(router_addr), abi=PAYNODE_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': nonce, 'gas': 200000, 'gasPrice': current_gas_price
-            })
+            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': nonce, 'gas': 200000, '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)
         return self.w3.to_hex(tx_h)

paynode_sdk/constants.py

@@ -2,7 +2,7 @@
 PAYNODE_ROUTER_ADDRESS = "0x4A73696ccF76E7381b044cB95127B3784369Ed63"
 PAYNODE_ROUTER_ADDRESS_SANDBOX = "0x24cD8b68aaC209217ff5a6ef1Bf55a59f2c8Ca6F"
 BASE_USDC_ADDRESS = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
-BASE_USDC_ADDRESS_SANDBOX = "0x109AEddD656Ed2761d1e210E179329105039c784"
+BASE_USDC_ADDRESS_SANDBOX = "0x65c088EfBDB0E03185Dbe8e258Ad0cf4Ab7946b0"
 BASE_USDC_DECIMALS = 6
 
 PROTOCOL_TREASURY = "0x598bF63F5449876efafa7b36b77Deb2070621C0E"
@@ -14,22 +14,7 @@ BASE_RPC_URLS_SANDBOX = ["https://sepolia.base.org", "https://base-sepolia-rpc.p
 
 ACCEPTED_TOKENS = {
     8453: ["0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"],
-    84532: ["0x109AEddD656Ed2761d1e210E179329105039c784"]
+    84532: ["0x65c088EfBDB0E03185Dbe8e258Ad0cf4Ab7946b0"]
 }
 
-PAYNODE_ROUTER_ABI = [
-    {
-        "anonymous": False,
-        "inputs": [
-            {"indexed": True, "name": "orderId", "type": "bytes32"},
-            {"indexed": True, "name": "merchant", "type": "address"},
-            {"indexed": True, "name": "payer", "type": "address"},
-            {"indexed": False, "name": "token", "type": "address"},
-            {"indexed": False, "name": "amount", "type": "uint256"},
-            {"indexed": False, "name": "fee", "type": "uint256"},
-            {"indexed": False, "name": "chainId", "type": "uint256"}
-        ],
-        "name": "PaymentReceived",
-        "type": "event"
-    }
-]
+PAYNODE_ROUTER_ABI = [{'type': 'constructor', 'inputs': [{'name': '_protocolTreasury', 'type': 'address', 'internalType': 'address'}], 'stateMutability': 'nonpayable'}, {'type': 'function', 'name': 'MAX_BPS', 'inputs': [], 'outputs': [{'name': '', 'type': 'uint256', 'internalType': 'uint256'}], 'stateMutability': 'view'}, {'type': 'function', 'name': 'MIN_PAYMENT_AMOUNT', 'inputs': [], 'outputs': [{'name': '', 'type': 'uint256', 'internalType': 'uint256'}], 'stateMutability': 'view'}, {'type': 'function', 'name': 'PROTOCOL_FEE_BPS', 'inputs': [], 'outputs': [{'name': '', 'type': 'uint256', 'internalType': 'uint256'}], 'stateMutability': 'view'}, {'type': 'function', 'name': 'acceptOwnership', 'inputs': [], 'outputs': [], 'stateMutability': 'nonpayable'}, {'type': 'function', 'name': 'owner', 'inputs': [], 'outputs': [{'name': '', 'type': 'address', 'internalType': 'address'}], 'stateMutability': 'view'}, {'type': 'function', 'name': 'pause', 'inputs': [], 'outputs': [], 'stateMutability': 'nonpayable'}, {'type': 'function', 'name': 'paused', 'inputs': [], 'outputs': [{'name': '', 'type': 'bool', 'internalType': 'bool'}], 'stateMutability': 'view'}, {'type': 'function', 'name': 'pay', 'inputs': [{'name': 'token', 'type': 'address', 'internalType': 'address'}, {'name': 'merchant', 'type': 'address', 'internalType': 'address'}, {'name': 'amount', 'type': 'uint256', 'internalType': 'uint256'}, {'name': 'orderId', 'type': 'bytes32', 'internalType': 'bytes32'}], 'outputs': [], 'stateMutability': 'nonpayable'}, {'type': 'function', 'name': 'payWithPermit', 'inputs': [{'name': 'payer', 'type': 'address', 'internalType': 'address'}, {'name': 'token', 'type': 'address', 'internalType': 'address'}, {'name': 'merchant', 'type': 'address', 'internalType': 'address'}, {'name': 'amount', 'type': 'uint256', 'internalType': 'uint256'}, {'name': 'orderId', 'type': 'bytes32', 'internalType': 'bytes32'}, {'name': 'deadline', 'type': 'uint256', 'internalType': 'uint256'}, {'name': 'v', 'type': 'uint8', 'internalType': 'uint8'}, {'name': 'r', 'type': 'bytes32', 'internalType': 'bytes32'}, {'name': 's', 'type': 'bytes32', 'internalType': 'bytes32'}], 'outputs': [], 'stateMutability': 'nonpayable'}, {'type': 'function', 'name': 'pendingOwner', 'inputs': [], 'outputs': [{'name': '', 'type': 'address', 'internalType': 'address'}], 'stateMutability': 'view'}, {'type': 'function', 'name': 'protocolTreasury', 'inputs': [], 'outputs': [{'name': '', 'type': 'address', 'internalType': 'address'}], 'stateMutability': 'view'}, {'type': 'function', 'name': 'renounceOwnership', 'inputs': [], 'outputs': [], 'stateMutability': 'nonpayable'}, {'type': 'function', 'name': 'transferOwnership', 'inputs': [{'name': 'newOwner', 'type': 'address', 'internalType': 'address'}], 'outputs': [], 'stateMutability': 'nonpayable'}, {'type': 'function', 'name': 'unpause', 'inputs': [], 'outputs': [], 'stateMutability': 'nonpayable'}, {'type': 'function', 'name': 'updateTreasury', 'inputs': [{'name': '_newTreasury', 'type': 'address', 'internalType': 'address'}], 'outputs': [], 'stateMutability': 'nonpayable'}, {'type': 'event', 'name': 'OwnershipTransferStarted', 'inputs': [{'name': 'previousOwner', 'type': 'address', 'indexed': True, 'internalType': 'address'}, {'name': 'newOwner', 'type': 'address', 'indexed': True, 'internalType': 'address'}], 'anonymous': False}, {'type': 'event', 'name': 'OwnershipTransferred', 'inputs': [{'name': 'previousOwner', 'type': 'address', 'indexed': True, 'internalType': 'address'}, {'name': 'newOwner', 'type': 'address', 'indexed': True, 'internalType': 'address'}], 'anonymous': False}, {'type': 'event', 'name': 'Paused', 'inputs': [{'name': 'account', 'type': 'address', 'indexed': False, 'internalType': 'address'}], 'anonymous': False}, {'type': 'event', 'name': 'PaymentReceived', 'inputs': [{'name': 'orderId', 'type': 'bytes32', 'indexed': True, 'internalType': 'bytes32'}, {'name': 'merchant', 'type': 'address', 'indexed': True, 'internalType': 'address'}, {'name': 'payer', 'type': 'address', 'indexed': True, 'internalType': 'address'}, {'name': 'token', 'type': 'address', 'indexed': False, 'internalType': 'address'}, {'name': 'amount', 'type': 'uint256', 'indexed': False, 'internalType': 'uint256'}, {'name': 'fee', 'type': 'uint256', 'indexed': False, 'internalType': 'uint256'}, {'name': 'chainId', 'type': 'uint256', 'indexed': False, 'internalType': 'uint256'}], 'anonymous': False}, {'type': 'event', 'name': 'TreasuryUpdated', 'inputs': [{'name': 'oldTreasury', 'type': 'address', 'indexed': True, 'internalType': 'address'}, {'name': 'newTreasury', 'type': 'address', 'indexed': True, 'internalType': 'address'}], 'anonymous': False}, {'type': 'event', 'name': 'Unpaused', 'inputs': [{'name': 'account', 'type': 'address', 'indexed': False, 'internalType': 'address'}], 'anonymous': False}, {'type': 'error', 'name': 'AmountTooLow', 'inputs': []}, {'type': 'error', 'name': 'EnforcedPause', 'inputs': []}, {'type': 'error', 'name': 'ExpectedPause', 'inputs': []}, {'type': 'error', 'name': 'InvalidAddress', 'inputs': []}, {'type': 'error', 'name': 'OwnableInvalidOwner', 'inputs': [{'name': 'owner', 'type': 'address', 'internalType': 'address'}]}, {'type': 'error', 'name': 'OwnableUnauthorizedAccount', 'inputs': [{'name': 'account', 'type': 'address', 'internalType': 'address'}]}, {'type': 'error', 'name': 'SafeERC20FailedOperation', 'inputs': [{'name': 'token', 'type': 'address', 'internalType': 'address'}]}, {'type': 'error', 'name': 'UnauthorizedCaller', 'inputs': []}]

paynode_sdk/errors.py

@@ -28,7 +28,7 @@ ERROR_MESSAGES = {
     ErrorCode.transaction_not_found: "Transaction not found on-chain.",
     ErrorCode.wrong_contract: "Payment event was not emitted by the official PayNode contract.",
     ErrorCode.order_mismatch: "OrderId in receipt does not match requested ID.",
-    ErrorCode.missing_receipt: "Please pay to PayNode contract and provide 'x-paynode-receipt' header.",
+    ErrorCode.missing_receipt: "Please pay to PayNode contract and provide 'X-402-Payload' header.",
 }
 
 class PayNodeException(Exception):

paynode_sdk/idempotency.py

@@ -10,24 +10,69 @@ class IdempotencyStore(ABC):
         """
         pass
 
+    @abstractmethod
+    async def delete(self, tx_hash: str) -> None:
+        """
+        Deletes a transaction hash from the store.
+        Used for rolling back a lock if subsequent verification fails.
+        """
+        pass
+
+import threading
+
 class MemoryIdempotencyStore(IdempotencyStore):
     def __init__(self):
         self.cache: Dict[str, float] = {}
+        self.last_cleanup = time.time()
+        self.lock = threading.Lock()
 
     async def check_and_set(self, tx_hash: str, ttl_seconds: int) -> bool:
-        now = time.time()
-        expiry = self.cache.get(tx_hash)
-        
-        if expiry and expiry > now:
-            return False
+        with self.lock:
+            now = time.time()
+            expiry = self.cache.get(tx_hash)
+
+            if expiry and expiry > now:
+                return False
+
+            self.cache[tx_hash] = now + ttl_seconds
             
-        self.cache[tx_hash] = now + ttl_seconds
-        self._cleanup()
-        return True
+            # BUG-5 FIX: Only cleanup periodically to avoid O(n) overhead on every call.
+            if now - self.last_cleanup > 60:
+                self._cleanup()
+                self.last_cleanup = now
+                
+            return True
+
+    async def delete(self, tx_hash: str) -> None:
+        with self.lock:
+            self.cache.pop(tx_hash, None)
 
     def _cleanup(self):
+        # Already inside lock when called from check_and_set
         now = time.time()
-        # Simple cleanup logic: remove expired entries
         expired_keys = [k for k, v in self.cache.items() if v <= now]
         for k in expired_keys:
             del self.cache[k]
+
+
+class RedisIdempotencyStore(IdempotencyStore):
+    """
+    Production-ready implementation using Redis.
+    Uses `SET txHash 1 NX EX ttlSeconds` for atomic check-and-set.
+
+    Requires: pip install redis
+    Usage:
+        import redis
+        store = RedisIdempotencyStore(redis.Redis(host='localhost', port=6379))
+    """
+    def __init__(self, redis_client, prefix: str = "paynode:tx:"):
+        self.redis = redis_client
+        self.prefix = prefix
+
+    async def check_and_set(self, tx_hash: str, ttl_seconds: int) -> bool:
+        key = f"{self.prefix}{tx_hash}"
+        return bool(self.redis.set(key, 1, ex=ttl_seconds, nx=True))
+
+    async def delete(self, tx_hash: str) -> None:
+        key = f"{self.prefix}{tx_hash}"
+        self.redis.delete(key)