uvd-x402-sdk 0.2.0__py3-none-any.whl

uvd_x402_sdk/config.py

@@ -0,0 +1,249 @@
+"""
+SDK configuration classes.
+
+This module provides configuration management for the x402 SDK,
+including facilitator settings, recipient addresses, and timeouts.
+
+Supports:
+- x402 v1 and v2 protocols
+- Multi-network payment options
+- Per-network recipient configuration
+"""
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Any, Literal
+import os
+
+
+@dataclass
+class NetworkRecipientConfig:
+    """
+    Configuration for a specific network's recipient address.
+
+    Use this to specify different recipient addresses for different networks.
+    """
+
+    recipient: str
+    enabled: bool = True
+
+
+# Alias for backward compatibility
+NetworkConfig = NetworkRecipientConfig
+
+
+@dataclass
+class MultiPaymentConfig:
+    """
+    Configuration for multi-payment support.
+
+    Allows users to offer multiple networks for payment acceptance.
+    """
+
+    networks: List[str] = field(default_factory=list)
+    default_network: Optional[str] = None
+
+    def __post_init__(self) -> None:
+        if self.networks and not self.default_network:
+            self.default_network = self.networks[0]
+
+
+@dataclass
+class X402Config:
+    """
+    Main SDK configuration.
+
+    Attributes:
+        facilitator_url: URL of the x402 facilitator service
+        recipient_evm: Default recipient address for EVM chains
+        recipient_solana: Recipient address for Solana/SVM chains (also used for Fogo)
+        recipient_near: Recipient account for NEAR
+        recipient_stellar: Recipient address for Stellar
+        facilitator_solana: Solana/SVM facilitator address (fee payer)
+        verify_timeout: Timeout for verify requests (seconds)
+        settle_timeout: Timeout for settle requests (seconds)
+        supported_networks: List of enabled network names
+        network_configs: Per-network recipient overrides
+        resource_url: Resource URL sent to facilitator
+        description: Description sent to facilitator
+        x402_version: Protocol version to use (1, 2, or "auto")
+        multi_payment: Multi-payment configuration for accepting multiple networks
+    """
+
+    facilitator_url: str = "https://facilitator.ultravioletadao.xyz"
+
+    # Recipient addresses per network type
+    recipient_evm: str = ""
+    recipient_solana: str = ""  # Also used for Fogo and other SVM chains
+    recipient_near: str = ""
+    recipient_stellar: str = ""
+
+    # Solana/SVM facilitator (fee payer) - same for all SVM chains
+    facilitator_solana: str = "F742C4VfFLQ9zRQyithoj5229ZgtX2WqKCSFKgH2EThq"
+
+    # Timeouts
+    verify_timeout: float = 30.0
+    settle_timeout: float = 55.0  # Must be < Lambda timeout (60s)
+
+    # Network configuration - All 15 networks (14 enabled by default)
+    supported_networks: List[str] = field(default_factory=lambda: [
+        # EVM chains (11 total, 10 enabled)
+        "base", "ethereum", "polygon", "arbitrum", "optimism",
+        "avalanche", "celo", "hyperevm", "unichain", "monad",
+        # bsc disabled: Binance-Peg USDC doesn't support ERC-3009
+        # SVM chains (2 total, 2 enabled)
+        "solana", "fogo",
+        # NEAR (1 total, 1 enabled)
+        "near",
+        # Stellar (1 total, 1 enabled)
+        "stellar",
+    ])
+
+    # Per-network recipient overrides
+    network_configs: Dict[str, NetworkRecipientConfig] = field(default_factory=dict)
+
+    # Facilitator request metadata
+    resource_url: str = ""
+    description: str = "x402 payment"
+
+    # x402 protocol version: 1, 2, or "auto" (detect from payload)
+    x402_version: Literal[1, 2, "auto"] = "auto"
+
+    # Multi-payment configuration
+    multi_payment: Optional[MultiPaymentConfig] = None
+
+    def __post_init__(self) -> None:
+        """Validate configuration after initialization."""
+        if not self.facilitator_url:
+            raise ValueError("facilitator_url is required")
+
+        # At least one recipient is required
+        if not any([
+            self.recipient_evm,
+            self.recipient_solana,
+            self.recipient_near,
+            self.recipient_stellar,
+        ]):
+            raise ValueError("At least one recipient address is required")
+
+    @classmethod
+    def from_env(cls) -> "X402Config":
+        """
+        Create configuration from environment variables.
+
+        Environment variables:
+            X402_FACILITATOR_URL: Facilitator URL
+            X402_RECIPIENT_EVM: EVM recipient address
+            X402_RECIPIENT_SOLANA: Solana recipient address
+            X402_RECIPIENT_NEAR: NEAR recipient account
+            X402_RECIPIENT_STELLAR: Stellar recipient address
+            X402_FACILITATOR_SOLANA: Solana fee payer address
+            X402_VERIFY_TIMEOUT: Verify request timeout
+            X402_SETTLE_TIMEOUT: Settle request timeout
+            X402_RESOURCE_URL: Resource URL for facilitator
+            X402_DESCRIPTION: Description for facilitator
+        """
+        return cls(
+            facilitator_url=os.environ.get(
+                "X402_FACILITATOR_URL",
+                "https://facilitator.ultravioletadao.xyz",
+            ),
+            recipient_evm=os.environ.get("X402_RECIPIENT_EVM", ""),
+            recipient_solana=os.environ.get("X402_RECIPIENT_SOLANA", ""),
+            recipient_near=os.environ.get("X402_RECIPIENT_NEAR", ""),
+            recipient_stellar=os.environ.get("X402_RECIPIENT_STELLAR", ""),
+            facilitator_solana=os.environ.get(
+                "X402_FACILITATOR_SOLANA",
+                "F742C4VfFLQ9zRQyithoj5229ZgtX2WqKCSFKgH2EThq",
+            ),
+            verify_timeout=float(os.environ.get("X402_VERIFY_TIMEOUT", "30")),
+            settle_timeout=float(os.environ.get("X402_SETTLE_TIMEOUT", "55")),
+            resource_url=os.environ.get("X402_RESOURCE_URL", ""),
+            description=os.environ.get("X402_DESCRIPTION", "x402 payment"),
+        )
+
+    def get_recipient(self, network: str) -> str:
+        """
+        Get recipient address for a specific network.
+
+        First checks network_configs for overrides, then falls back to
+        network-type default.
+
+        Args:
+            network: Network name (e.g., 'base', 'solana', 'fogo')
+
+        Returns:
+            Recipient address for the network
+        """
+        # Check for network-specific override
+        if network in self.network_configs:
+            return self.network_configs[network].recipient
+
+        # Fall back to network-type default
+        from uvd_x402_sdk.networks import get_network, NetworkType
+
+        network_config = get_network(network)
+        if not network_config:
+            return self.recipient_evm  # Default to EVM
+
+        # SVM chains (Solana, Fogo, etc.) use the same recipient
+        if NetworkType.is_svm(network_config.network_type):
+            return self.recipient_solana
+        elif network_config.network_type == NetworkType.NEAR:
+            return self.recipient_near
+        elif network_config.network_type == NetworkType.STELLAR:
+            return self.recipient_stellar
+        else:
+            return self.recipient_evm
+
+    def is_network_enabled(self, network: str) -> bool:
+        """
+        Check if a network is enabled.
+
+        Args:
+            network: Network name
+
+        Returns:
+            True if network is in supported_networks and not disabled
+        """
+        if network not in self.supported_networks:
+            return False
+
+        # Check network-specific config
+        if network in self.network_configs:
+            return self.network_configs[network].enabled
+
+        return True
+
+    def get_supported_chain_ids(self) -> List[int]:
+        """
+        Get list of supported EVM chain IDs.
+
+        Returns:
+            List of chain IDs for enabled EVM networks
+        """
+        from uvd_x402_sdk.networks import get_network, NetworkType
+
+        chain_ids = []
+        for network_name in self.supported_networks:
+            network = get_network(network_name)
+            if network and network.network_type == NetworkType.EVM and network.chain_id > 0:
+                if self.is_network_enabled(network_name):
+                    chain_ids.append(network.chain_id)
+
+        return chain_ids
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert configuration to dictionary."""
+        return {
+            "facilitator_url": self.facilitator_url,
+            "recipient_evm": self.recipient_evm,
+            "recipient_solana": self.recipient_solana,
+            "recipient_near": self.recipient_near,
+            "recipient_stellar": self.recipient_stellar,
+            "facilitator_solana": self.facilitator_solana,
+            "verify_timeout": self.verify_timeout,
+            "settle_timeout": self.settle_timeout,
+            "supported_networks": self.supported_networks,
+            "resource_url": self.resource_url,
+            "description": self.description,
+        }

uvd_x402_sdk/decorators.py

@@ -0,0 +1,325 @@
+"""
+Decorators for protecting endpoints with x402 payments.
+
+These decorators provide a clean, declarative way to require payment
+for specific endpoints across different web frameworks.
+"""
+
+from decimal import Decimal
+from functools import wraps
+from typing import Any, Callable, Optional, TypeVar, Union, Dict
+
+from uvd_x402_sdk.config import X402Config
+from uvd_x402_sdk.client import X402Client
+from uvd_x402_sdk.exceptions import (
+    X402Error,
+    PaymentRequiredError,
+    InvalidPayloadError,
+)
+from uvd_x402_sdk.response import create_402_response, create_402_headers
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+# Global client instance (set by configure_x402)
+_global_client: Optional[X402Client] = None
+_global_config: Optional[X402Config] = None
+
+
+def configure_x402(
+    config: Optional[X402Config] = None,
+    recipient_address: Optional[str] = None,
+    facilitator_url: str = "https://facilitator.ultravioletadao.xyz",
+    **kwargs: Any,
+) -> None:
+    """
+    Configure the global x402 client for decorator usage.
+
+    Call this once during application startup to set up the x402 client
+    that decorators will use.
+
+    Args:
+        config: Full X402Config object
+        recipient_address: Default recipient for EVM chains
+        facilitator_url: Facilitator service URL
+        **kwargs: Additional config parameters
+
+    Example:
+        >>> from uvd_x402_sdk import configure_x402
+        >>> configure_x402(
+        ...     recipient_address="0xYourWallet...",
+        ...     facilitator_url="https://facilitator.ultravioletadao.xyz"
+        ... )
+    """
+    global _global_client, _global_config
+
+    if config:
+        _global_config = config
+    else:
+        _global_config = X402Config(
+            facilitator_url=facilitator_url,
+            recipient_evm=recipient_address or "",
+            **kwargs,
+        )
+
+    _global_client = X402Client(config=_global_config)
+
+
+def get_x402_client() -> X402Client:
+    """Get the global x402 client instance."""
+    if _global_client is None:
+        raise RuntimeError(
+            "x402 not configured. Call configure_x402() during application startup."
+        )
+    return _global_client
+
+
+def get_x402_config() -> X402Config:
+    """Get the global x402 config instance."""
+    if _global_config is None:
+        raise RuntimeError(
+            "x402 not configured. Call configure_x402() during application startup."
+        )
+    return _global_config
+
+
+def require_payment(
+    amount_usd: Union[Decimal, float, str],
+    amount_callback: Optional[Callable[..., Decimal]] = None,
+    networks: Optional[list] = None,
+    message: Optional[str] = None,
+    inject_result: bool = True,
+    header_name: str = "X-PAYMENT",
+) -> Callable[[F], F]:
+    """
+    Decorator that requires x402 payment for an endpoint.
+
+    This is the main decorator for protecting endpoints with payments.
+    It handles the complete payment flow:
+    1. Check for X-PAYMENT header
+    2. If missing, return 402 Payment Required
+    3. If present, verify and settle payment
+    4. Optionally inject PaymentResult into function
+
+    Args:
+        amount_usd: Fixed payment amount in USD (or use amount_callback)
+        amount_callback: Callable that returns dynamic amount based on request
+        networks: Limit to specific networks (default: all enabled)
+        message: Custom message for 402 response
+        inject_result: Whether to inject PaymentResult as 'payment_result' kwarg
+        header_name: Header name for payment (default: X-PAYMENT)
+
+    Returns:
+        Decorated function
+
+    Example (Flask):
+        >>> @app.route("/api/premium")
+        >>> @require_payment(amount_usd=Decimal("1.00"))
+        >>> def premium_endpoint(payment_result=None):
+        ...     return {"message": f"Paid by {payment_result.payer_address}"}
+
+    Example (Dynamic pricing):
+        >>> def calculate_price(request):
+        ...     items = request.json.get("items", 1)
+        ...     return Decimal(str(items * 0.10))
+        >>>
+        >>> @require_payment(amount_callback=calculate_price)
+        >>> def dynamic_endpoint(payment_result=None):
+        ...     return {"message": "Success"}
+    """
+
+    def decorator(func: F) -> F:
+        @wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            # Get client and config
+            client = get_x402_client()
+            config = get_x402_config()
+
+            # Framework-agnostic request extraction
+            # This will be overridden by framework-specific integrations
+            request = _extract_request(*args, **kwargs)
+            payment_header = _get_header(request, header_name)
+
+            # Determine amount
+            if amount_callback:
+                required_amount = Decimal(str(amount_callback(request)))
+            else:
+                required_amount = Decimal(str(amount_usd))
+
+            # No payment header - return 402
+            if not payment_header:
+                response_body = create_402_response(
+                    amount_usd=required_amount,
+                    config=config,
+                    message=message,
+                )
+                return _create_402_response(response_body)
+
+            # Process payment
+            try:
+                result = client.process_payment(
+                    x_payment_header=payment_header,
+                    expected_amount_usd=required_amount,
+                )
+
+                # Inject result if requested
+                if inject_result:
+                    kwargs["payment_result"] = result
+
+                return func(*args, **kwargs)
+
+            except X402Error as e:
+                # Return appropriate error response
+                return _create_error_response(e, required_amount, config)
+
+        return wrapper  # type: ignore
+
+    return decorator
+
+
+# Alias for backward compatibility and preference
+x402_required = require_payment
+
+
+def _extract_request(*args: Any, **kwargs: Any) -> Any:
+    """
+    Extract request object from function arguments.
+
+    This is a framework-agnostic implementation that works with:
+    - Flask (request from flask.globals)
+    - FastAPI/Starlette (request in kwargs)
+    - Django (request as first arg)
+    - AWS Lambda (event dict as first arg)
+    """
+    # Check kwargs first
+    if "request" in kwargs:
+        return kwargs["request"]
+
+    # Check first positional arg
+    if args:
+        return args[0]
+
+    # Try Flask global
+    try:
+        from flask import request
+        return request
+    except ImportError:
+        pass
+
+    # No request found
+    return None
+
+
+def _get_header(request: Any, header_name: str) -> Optional[str]:
+    """
+    Get header value from request object.
+
+    Handles different frameworks' request objects.
+    """
+    if request is None:
+        return None
+
+    # Dict-like (AWS Lambda event)
+    if isinstance(request, dict):
+        headers = request.get("headers", {})
+        # Lambda headers can be case-sensitive or not
+        return headers.get(header_name) or headers.get(header_name.lower())
+
+    # Flask/Werkzeug
+    if hasattr(request, "headers"):
+        headers = request.headers
+        if hasattr(headers, "get"):
+            return headers.get(header_name)
+
+    # Django
+    if hasattr(request, "META"):
+        # Django uses HTTP_X_PAYMENT format
+        django_header = f"HTTP_{header_name.replace('-', '_').upper()}"
+        return request.META.get(django_header)
+
+    return None
+
+
+def _create_402_response(body: Dict[str, Any]) -> Any:
+    """
+    Create a 402 response appropriate for the current framework.
+
+    This is a fallback that returns a tuple. Framework-specific
+    integrations override this.
+    """
+    # Try Flask
+    try:
+        from flask import jsonify, make_response
+        response = make_response(jsonify(body), 402)
+        for key, value in create_402_headers().items():
+            response.headers[key] = value
+        return response
+    except ImportError:
+        pass
+
+    # Try FastAPI/Starlette
+    try:
+        from starlette.responses import JSONResponse
+        return JSONResponse(
+            status_code=402,
+            content=body,
+            headers=create_402_headers(),
+        )
+    except ImportError:
+        pass
+
+    # Try Django
+    try:
+        from django.http import JsonResponse
+        response = JsonResponse(body, status=402)
+        for key, value in create_402_headers().items():
+            response[key] = value
+        return response
+    except ImportError:
+        pass
+
+    # Fallback: return dict (for AWS Lambda or raw WSGI)
+    return {
+        "statusCode": 402,
+        "headers": {
+            "Content-Type": "application/json",
+            **create_402_headers(),
+        },
+        "body": body,
+    }
+
+
+def _create_error_response(
+    error: X402Error,
+    amount: Decimal,
+    config: X402Config,
+) -> Any:
+    """Create an error response for x402 errors."""
+    # Payment verification/settlement failed - return 402
+    if isinstance(error, (PaymentRequiredError, InvalidPayloadError)):
+        body = create_402_response(amount_usd=amount, config=config)
+        body["error"] = error.message
+        body["details"] = error.details
+        return _create_402_response(body)
+
+    # Other errors - return 400
+    body = error.to_dict()
+
+    try:
+        from flask import jsonify, make_response
+        return make_response(jsonify(body), 400)
+    except ImportError:
+        pass
+
+    try:
+        from starlette.responses import JSONResponse
+        return JSONResponse(status_code=400, content=body)
+    except ImportError:
+        pass
+
+    try:
+        from django.http import JsonResponse
+        return JsonResponse(body, status=400)
+    except ImportError:
+        pass
+
+    return {"statusCode": 400, "body": body}