traia-iatp 0.1.29__py3-none-any.whl

traia_iatp/d402/clients/base.py

@@ -0,0 +1,218 @@
+import time
+from typing import Optional, Callable, Dict, Any, List
+from eth_account import Account
+from ..payment_signing import sign_payment_header
+from ..types import (
+    PaymentRequirements,
+    UnsupportedSchemeException,
+)
+from ..common import d402_VERSION
+import secrets
+from ..encoding import safe_base64_decode
+import json
+
+# Define type for the payment requirements selector
+PaymentSelectorCallable = Callable[
+    [List[PaymentRequirements], Optional[str], Optional[str], Optional[int]],
+    PaymentRequirements,
+]
+
+
+def decode_x_payment_response(header: str) -> Dict[str, Any]:
+    """Decode the X-PAYMENT-RESPONSE header.
+
+    Args:
+        header: The X-PAYMENT-RESPONSE header to decode
+
+    Returns:
+        The decoded payment response containing:
+        - success: bool
+        - transaction: str (hex)
+        - network: str
+        - payer: str (address)
+    """
+    decoded = safe_base64_decode(header)
+    result = json.loads(decoded)
+    return result
+
+
+class PaymentError(Exception):
+    """Base class for payment-related errors."""
+
+    pass
+
+
+class PaymentAmountExceededError(PaymentError):
+    """Raised when payment amount exceeds maximum allowed value."""
+
+    pass
+
+
+class MissingRequestConfigError(PaymentError):
+    """Raised when request configuration is missing."""
+
+    pass
+
+
+class PaymentAlreadyAttemptedError(PaymentError):
+    """Raised when payment has already been attempted."""
+
+    pass
+
+
+class d402Client:
+    """Base client for handling d402 payments."""
+
+    def __init__(
+        self,
+        operator_account: Account,
+        wallet_address: str = None,
+        max_value: Optional[int] = None,
+        payment_requirements_selector: Optional[PaymentSelectorCallable] = None,
+    ):
+        """Initialize the d402 client.
+
+        Args:
+            operator_account: Operator account with private key for signing payments (EOA)
+            wallet_address: Consumer's IATPWallet contract address (if None, uses operator_account.address for testing)
+            max_value: Optional safety limit for maximum payment amount per request in base units.
+                      This is a global safety check that prevents paying more than intended.
+                      WARNING: This is a simple numeric comparison and does NOT account for:
+                      - Different tokens (USDC vs TRAIA vs others) - amounts are compared directly
+                      - Token decimals - ensure max_value uses the same decimals as expected tokens
+                      - Exchange rates - this is not a USD limit, it's a token amount limit
+                      Each endpoint can have different payment requirements (amount and token),
+                      but this limit applies to all requests. Set it based on your most expensive
+                      expected payment in the token's base units.
+                      If None, no limit is enforced (not recommended for production).
+            payment_requirements_selector: Optional custom selector for payment requirements
+        """
+        self.operator_account = operator_account  # Operator EOA for signing
+        self.wallet_address = wallet_address or operator_account.address  # IATPWallet contract or EOA for testing
+        self.max_value = max_value
+        self._payment_requirements_selector = (
+            payment_requirements_selector or self.default_payment_requirements_selector
+        )
+
+    @staticmethod
+    def default_payment_requirements_selector(
+        accepts: List[PaymentRequirements],
+        network_filter: Optional[str] = None,
+        scheme_filter: Optional[str] = None,
+        max_value: Optional[int] = None,
+    ) -> PaymentRequirements:
+        """Select payment requirements from the list of accepted requirements.
+
+        Args:
+            accepts: List of accepted payment requirements
+            network_filter: Optional network to filter by
+            scheme_filter: Optional scheme to filter by
+            max_value: Optional maximum allowed payment amount
+
+        Returns:
+            Selected payment requirements (PaymentRequirements instance from ..types)
+
+        Raises:
+            UnsupportedSchemeException: If no supported scheme is found
+            PaymentAmountExceededError: If payment amount exceeds max_value
+        """
+        for paymentRequirements in accepts:
+            scheme = paymentRequirements.scheme
+            network = paymentRequirements.network
+
+            # Check scheme filter
+            if scheme_filter and scheme != scheme_filter:
+                continue
+
+            # Check network filter
+            if network_filter and network != network_filter:
+                continue
+
+            if scheme == "exact":
+                # Check max value if set
+                # NOTE: This is a simple numeric comparison. It does NOT account for:
+                # - Different tokens (USDC vs TRAIA vs others)
+                # - Token decimals differences
+                # - Exchange rates between tokens
+                # This is a safety limit to prevent accidentally paying too much.
+                # The comparison is done on the raw amount values in base units.
+                if max_value is not None:
+                    max_amount = int(paymentRequirements.max_amount_required)
+                    if max_amount > max_value:
+                        raise PaymentAmountExceededError(
+                            f"Payment amount {max_amount} (token: {paymentRequirements.asset}) "
+                            f"exceeds maximum allowed value {max_value} base units. "
+                            f"Note: This comparison does not account for token differences or decimals."
+                        )
+
+                return paymentRequirements
+
+        raise UnsupportedSchemeException("No supported payment scheme found")
+
+    def select_payment_requirements(
+        self,
+        accepts: List[PaymentRequirements],
+        network_filter: Optional[str] = None,
+        scheme_filter: Optional[str] = None,
+    ) -> PaymentRequirements:
+        """Select payment requirements using the configured selector.
+
+        Args:
+            accepts: List of accepted payment requirements (PaymentRequirements models)
+            network_filter: Optional network to filter by
+            scheme_filter: Optional scheme to filter by
+
+        Returns:
+            Selected payment requirements (PaymentRequirements instance from ..types)
+
+        Raises:
+            UnsupportedSchemeException: If no supported scheme is found
+            PaymentAmountExceededError: If payment amount exceeds max_value
+        """
+        return self._payment_requirements_selector(
+            accepts, network_filter, scheme_filter, self.max_value
+        )
+
+   
+    def create_payment_header(
+        self,
+        payment_requirements: PaymentRequirements,
+        d402_version: int = d402_VERSION,
+        request_path: str = None,
+    ) -> str:
+        """Create a payment header for the given requirements.
+
+        Args:
+            payment_requirements: Selected payment requirements
+            d402_version: d402 protocol version
+            request_path: Optional API request path (if None, uses payment_requirements.resource)
+
+        Returns:
+            Signed payment header with PullFundsForSettlement signature
+        """
+        unsigned_header = {
+            "d402Version": d402_version,
+            "scheme": payment_requirements.scheme,
+            "network": payment_requirements.network,
+            "payload": {
+                "signature": None,
+                "authorization": {
+                    "from": self.wallet_address,  # IATPWallet contract address
+                    "to": payment_requirements.pay_to,  # Provider's IATPWallet
+                    "value": payment_requirements.max_amount_required,
+                    "validAfter": str(int(time.time()) - 60),  # 60 seconds before
+                    "validBefore": str(
+                        int(time.time()) + payment_requirements.max_timeout_seconds
+                    ),
+                },
+            },
+        }
+
+        signed_header = sign_payment_header(
+            self.operator_account,
+            payment_requirements,
+            unsigned_header,
+            wallet_address=self.wallet_address,
+            request_path=request_path or payment_requirements.resource
+        )
+        return signed_header

traia_iatp/d402/clients/httpx.py

@@ -0,0 +1,219 @@
+"""HTTPX client integration for d402 payments."""
+
+import logging
+from typing import Optional, Dict, List
+from httpx import Request, Response, AsyncClient
+from eth_account import Account
+from functools import wraps
+
+from .base import (
+    d402Client,
+    MissingRequestConfigError,
+    PaymentError,
+    PaymentSelectorCallable,
+    decode_x_payment_response,
+)
+from ..types import d402PaymentRequiredResponse
+
+logger = logging.getLogger(__name__)
+
+
+class HttpxHooks:
+    """Event hooks for httpx client to handle d402 payments."""
+
+    def __init__(self, client: d402Client):
+        self.client = client
+        self._is_retry = False
+
+    async def on_request(self, request: Request):
+        """Handle request before it is sent."""
+        #TODO: (TBD) if mongodb had endpoints data for each mcp server then the client herre could apriori get the payment details and construct the payment payload.
+        pass
+
+    async def on_response(self, response: Response) -> Response:
+        """Handle response after it is received.
+
+        When a 402 Payment Required response is received:
+        1. Parse payment requirements from the response
+        2. Select appropriate payment option (token/network)
+        3. Create EIP-3009 signed payment authorization
+        4. Retry the original request with X-Payment header
+        """
+
+        # Log every response for debugging
+        logger.debug(f"d402 hook: on_response called - status={response.status_code}, url={response.url}")
+
+        # If this is not a 402, just return the response
+        if response.status_code != 402:
+            return response
+
+        # If this is a retry response, just return it (avoid infinite loop)
+        if self._is_retry:
+            logger.debug(f"d402 hook: This is a retry response, returning as-is")
+            return response
+        
+        logger.info(f"🔔 d402 hook: Intercepted HTTP 402 - creating payment...")
+
+        try:
+            if not response.request:
+                raise MissingRequestConfigError("Missing request configuration")
+
+            # Read the response content before parsing
+            await response.aread()
+
+            # Parse payment requirements from 402 response
+            data = response.json()
+            payment_response = d402PaymentRequiredResponse(**data)
+
+            # Select payment requirements (matches token/network, checks max_value)
+            selected_requirements = self.client.select_payment_requirements(
+                payment_response.accepts
+            )
+
+            # The server sets the resource field in payment_requirements
+            # This is the authoritative requestPath for the signature
+            # The server knows what endpoint is being called and sets it correctly
+            print(f"📍 DEBUG: Request path from server resource field: '{selected_requirements.resource}'")
+
+            # Create signed payment header using CLIENT's account
+            # Use payment_requirements.resource (don't override)
+            payment_header = self.client.create_payment_header(
+                selected_requirements, 
+                payment_response.d402_version
+                # No request_path parameter - uses payment_requirements.resource
+            )
+
+            # Mark as retry to avoid infinite loop
+            self._is_retry = True
+            
+            # Get the original request and add payment header
+            request = response.request
+            request.headers["X-Payment"] = payment_header
+            request.headers["Access-Control-Expose-Headers"] = "X-Payment-Response"
+
+            # Retry the request using the same httpx client that made the original request
+            # This ensures the retry uses the same client configuration (base_url, timeout, etc.)
+            # and that any hooks are still applied (via monkey-patch)
+            original_client = response.request.extensions.get("client")
+            if original_client and isinstance(original_client, AsyncClient):
+                # Use the original client for retry
+                retry_response = await original_client.send(request)
+            else:
+                # Fallback: create new client (will have hooks if monkey-patch is active)
+                async with AsyncClient() as new_client:
+                    retry_response = await new_client.send(request)
+
+            # Copy the retry response data to the original response object
+            response.status_code = retry_response.status_code
+            response.headers = retry_response.headers
+            response._content = retry_response._content
+            return response
+
+        except PaymentError as e:
+            self._is_retry = False
+            raise e
+        except Exception as e:
+            self._is_retry = False
+            raise PaymentError(f"Failed to handle payment: {str(e)}") from e
+
+
+def d402_payment_hooks(
+    operator_account: Account,
+    wallet_address: str = None,
+    max_value: Optional[int] = None,
+    payment_requirements_selector: Optional[PaymentSelectorCallable] = None,
+) -> Dict[str, List]:
+    """Create httpx event hooks dictionary for handling 402 Payment Required responses.
+
+    Args:
+        operator_account: Operator account with private key for signing payments (EOA)
+        wallet_address: Consumer's IATPWallet contract address (if None, uses operator_account.address for testing)
+        max_value: Optional maximum allowed payment amount in base units
+        payment_requirements_selector: Optional custom selector for payment requirements.
+            Should be a callable that takes (accepts, network_filter, scheme_filter, max_value)
+            and returns a PaymentRequirements object.
+
+    Returns:
+        Dictionary of event hooks that can be directly assigned to client.event_hooks
+
+    Example:
+        ```python
+        from eth_account import Account
+        from traia_iatp.d402.clients.httpx import d402_payment_hooks
+        import httpx
+
+        # For testing (uses EOA as wallet)
+        operator_account = Account.from_key("0x...")
+        client.event_hooks = d402_payment_hooks(operator_account)
+        
+        # For production (with IATPWallet contract)
+        operator_account = Account.from_key("0x...")  # Operator key
+        wallet = "0x..."  # IATPWallet contract address
+        client.event_hooks = d402_payment_hooks(operator_account, wallet_address=wallet)
+        ```
+    """
+    # Create d402Client
+    client = d402Client(
+        operator_account,
+        wallet_address=wallet_address,
+        max_value=max_value,
+        payment_requirements_selector=payment_requirements_selector,
+    )
+
+    # Create hooks
+    hooks = HttpxHooks(client)
+
+    # Return event hooks dictionary
+    return {
+        "request": [hooks.on_request],
+        "response": [hooks.on_response],
+    }
+
+
+class d402HttpxClient(AsyncClient):
+    """AsyncClient with built-in d402 payment handling."""
+
+    def __init__(
+        self,
+        operator_account: Account,
+        wallet_address: str = None,
+        max_value: Optional[int] = None,
+        payment_requirements_selector: Optional[PaymentSelectorCallable] = None,
+        **kwargs,
+    ):
+        """Initialize an AsyncClient with d402 payment handling.
+
+        Args:
+            operator_account: Operator account with private key for signing payments (EOA)
+            wallet_address: Consumer's IATPWallet contract address (if None, uses operator_account.address for testing)
+            max_value: Optional maximum allowed payment amount in base units
+            payment_requirements_selector: Optional custom selector for payment requirements.
+                Should be a callable that takes (accepts, network_filter, scheme_filter, max_value)
+                and returns a PaymentRequirements object.
+            **kwargs: Additional arguments to pass to AsyncClient
+
+        Example:
+            ```python
+            from eth_account import Account
+            from traia_iatp.d402.clients.httpx import d402HttpxClient
+
+            # For testing (uses EOA as wallet)
+            operator_account = Account.from_key("0x...")
+            async with d402HttpxClient(operator_account, base_url="https://api.example.com") as client:
+                response = await client.get("/protected-endpoint")
+                
+            # For production (with IATPWallet contract)
+            operator_account = Account.from_key("0x...")  # Operator key
+            wallet = "0x..."  # IATPWallet contract
+            async with d402HttpxClient(operator_account, wallet_address=wallet, base_url="https://api.example.com") as client:
+                response = await client.get("/protected-endpoint")
+            ```
+        """
+        super().__init__(**kwargs)
+        self.event_hooks = d402_payment_hooks(
+            operator_account, wallet_address, max_value, payment_requirements_selector
+        )
+
+
+__all__ = ["d402_payment_hooks", "d402HttpxClient", "HttpxHooks"]
+

traia_iatp/d402/common.py

@@ -0,0 +1,114 @@
+from decimal import Decimal
+from typing import List, Optional
+
+from .chains import (
+    get_chain_id,
+    get_token_decimals,
+    get_token_name,
+    get_token_version,
+    get_default_token_address,
+)
+from .types import Price, TokenAmount, PaymentRequirements, PaymentPayload
+
+
+def parse_money(amount: str | int, address: str, network: str) -> int:
+    """Parse money string or int into int
+
+    Params:
+        amount: str | int - if int, should be the full amount including token specific decimals
+    """
+    if isinstance(amount, str):
+        if amount.startswith("$"):
+            amount = amount[1:]
+        decimal_amount = Decimal(amount)
+
+        chain_id = get_chain_id(network)
+        decimals = get_token_decimals(chain_id, address)
+        decimal_amount = decimal_amount * Decimal(10**decimals)
+        return int(decimal_amount)
+    return amount
+
+
+def process_price_to_atomic_amount(
+    price: Price, network: str
+) -> tuple[str, str, dict[str, str]]:
+    """Process a Price into atomic amount, asset address, and EIP-712 domain info
+
+    Args:
+        price: Either Money (USD string/int) or TokenAmount
+        network: Network identifier
+
+    Returns:
+        Tuple of (max_amount_required, asset_address, eip712_domain)
+
+    Raises:
+        ValueError: If price format is invalid
+    """
+    if isinstance(price, (str, int)):
+        # Money type - convert USD to USDC atomic units
+        try:
+            if isinstance(price, str) and price.startswith("$"):
+                price = price[1:]
+            amount = Decimal(str(price))
+
+            # Get USDC address for the network
+            chain_id = get_chain_id(network)
+            asset_address = get_usdc_address(chain_id)
+            decimals = get_token_decimals(chain_id, asset_address)
+
+            # Convert to atomic units
+            atomic_amount = int(amount * Decimal(10**decimals))
+
+            # Get EIP-712 domain info
+            eip712_domain = {
+                "name": get_token_name(chain_id, asset_address),
+                "version": get_token_version(chain_id, asset_address),
+            }
+
+            return str(atomic_amount), asset_address, eip712_domain
+
+        except (ValueError, KeyError) as e:
+            raise ValueError(f"Invalid price format: {price}. Error: {e}")
+
+    elif isinstance(price, TokenAmount):
+        # TokenAmount type - already in atomic units with asset info
+        return (
+            price.amount,
+            price.asset.address,
+            {
+                "name": price.asset.eip712.name,
+                "version": price.asset.eip712.version,
+            },
+        )
+
+    else:
+        raise ValueError(f"Invalid price type: {type(price)}")
+
+
+def get_usdc_address(chain_id: int | str) -> str:
+    """Get the USDC contract address for a given chain ID"""
+    chain_id_str = str(chain_id)  # Convert to string for consistency
+    return get_default_token_address(chain_id_str, "usdc")
+
+
+def find_matching_payment_requirements(
+    payment_requirements: List[PaymentRequirements],
+    payment: PaymentPayload,
+) -> Optional[PaymentRequirements]:
+    """
+    Finds the matching payment requirements for the given payment.
+
+    Args:
+        payment_requirements: The payment requirements to search through
+        payment: The payment to match against
+
+    Returns:
+        The matching payment requirements or None if no match is found
+    """
+    for req in payment_requirements:
+        if req.scheme == payment.scheme and req.network == payment.network:
+            return req
+    return None
+
+
+d402_VERSION = 1

traia_iatp/d402/encoding.py

@@ -0,0 +1,28 @@
+import base64
+from typing import Union
+
+
+def safe_base64_encode(data: Union[str, bytes]) -> str:
+    """Safely encode string or bytes to base64 string.
+
+    Args:
+        data: String or bytes to encode
+
+    Returns:
+        Base64 encoded string
+    """
+    if isinstance(data, str):
+        data = data.encode("utf-8")
+    return base64.b64encode(data).decode("utf-8")
+
+
+def safe_base64_decode(data: str) -> str:
+    """Safely decode base64 string to bytes and then to utf-8 string.
+
+    Args:
+        data: Base64 encoded string
+
+    Returns:
+        Decoded utf-8 string
+    """
+    return base64.b64decode(data).decode("utf-8")