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

uvd_x402_sdk/networks/stellar.py

@@ -0,0 +1,129 @@
+"""
+Stellar network configuration.
+
+Stellar uses Soroban smart contracts for USDC transfers:
+1. User signs a SorobanAuthorizationEntry (XDR format)
+2. Authorization contains transfer function invocation
+3. Facilitator wraps in fee-bump transaction
+4. Facilitator pays all XLM fees - user pays ZERO XLM
+
+Stellar USDC Details:
+- Uses SAC (Soroban Asset Contract) for the Circle-issued USDC
+- 7 decimals (stroops), different from other chains (6 decimals)
+- Freighter wallet required for signing (Bitget doesn't support Stellar)
+"""
+
+from uvd_x402_sdk.networks.base import (
+    NetworkConfig,
+    NetworkType,
+    register_network,
+)
+
+# Stellar Mainnet
+STELLAR = NetworkConfig(
+    name="stellar",
+    display_name="Stellar",
+    network_type=NetworkType.STELLAR,
+    chain_id=0,  # Non-EVM, no chain ID
+    # Soroban Asset Contract (SAC) for USDC
+    usdc_address="CCW67TSZV3SSS2HXMBQ5JFGCKJNXKZM7UQUWUZPUTHXSTZLEO7SJMI75",
+    usdc_decimals=7,  # Stellar uses 7 decimals (stroops)
+    usdc_domain_name="",  # Not applicable for Stellar
+    usdc_domain_version="",
+    rpc_url="https://horizon.stellar.org",
+    enabled=True,
+    extra_config={
+        # Network passphrase for signing
+        "network_passphrase": "Public Global Stellar Network ; September 2015",
+        # Soroban RPC endpoint (different from Horizon)
+        "soroban_rpc_url": "https://mainnet.sorobanrpc.com",
+        # Block explorer
+        "explorer_url": "https://stellar.expert/explorer/public",
+        # Circle USDC issuer (G... address)
+        "usdc_issuer": "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
+        # Default ledger validity (~5 minutes, ~60 ledgers)
+        "default_ledger_validity": 60,
+    },
+)
+
+# Register Stellar network
+register_network(STELLAR)
+
+
+# =============================================================================
+# Stellar-specific utilities
+# =============================================================================
+
+
+def stroops_to_usd(stroops: int) -> float:
+    """
+    Convert stroops (7 decimals) to USD amount.
+
+    Args:
+        stroops: Amount in stroops
+
+    Returns:
+        USD amount
+    """
+    return stroops / 10_000_000
+
+
+def usd_to_stroops(usd: float) -> int:
+    """
+    Convert USD amount to stroops (7 decimals).
+
+    Args:
+        usd: USD amount
+
+    Returns:
+        Amount in stroops
+    """
+    return int(usd * 10_000_000)
+
+
+def is_valid_stellar_address(address: str) -> bool:
+    """
+    Validate a Stellar public key format.
+
+    Args:
+        address: Stellar address to validate
+
+    Returns:
+        True if valid G... address (56 characters, starts with G)
+    """
+    return (
+        isinstance(address, str)
+        and len(address) == 56
+        and address.startswith("G")
+    )
+
+
+def is_valid_contract_address(address: str) -> bool:
+    """
+    Validate a Soroban contract address format.
+
+    Args:
+        address: Contract address to validate
+
+    Returns:
+        True if valid C... address (56 characters, starts with C)
+    """
+    return (
+        isinstance(address, str)
+        and len(address) == 56
+        and address.startswith("C")
+    )
+
+
+def calculate_expiration_ledger(current_ledger: int, validity_ledgers: int = 60) -> int:
+    """
+    Calculate expiration ledger for authorization.
+
+    Args:
+        current_ledger: Current ledger sequence from RPC
+        validity_ledgers: Number of ledgers the auth is valid (~5 minutes at 5s/ledger)
+
+    Returns:
+        Expiration ledger number
+    """
+    return current_ledger + validity_ledgers

uvd_x402_sdk/response.py

@@ -0,0 +1,439 @@
+"""
+HTTP 402 response helpers.
+
+This module provides utilities for creating standard 402 Payment Required
+responses that are compatible with both x402 v1 and v2 protocols.
+
+v1 Response:
+- JSON body with payment requirements
+- X-Accept-Payment header
+
+v2 Response:
+- PAYMENT-REQUIRED header (base64-encoded JSON)
+- PAYMENT-SIGNATURE header
+- accepts array with multiple payment options
+"""
+
+from decimal import Decimal
+from typing import Dict, List, Optional, Any, Union, Literal
+
+from uvd_x402_sdk.config import X402Config
+from uvd_x402_sdk.models import Payment402Response, PaymentOption, PaymentRequirementsV2
+from uvd_x402_sdk.networks import (
+    get_network,
+    list_networks,
+    NetworkType,
+    get_supported_network_names,
+    to_caip2_network,
+)
+
+
+def create_402_response(
+    amount_usd: Union[Decimal, float, str],
+    config: X402Config,
+    message: Optional[str] = None,
+    resource_description: Optional[str] = None,
+) -> Dict[str, Any]:
+    """
+    Create a standard 402 Payment Required response body.
+
+    This response tells the client what payment is required and provides
+    all necessary information to create a payment authorization.
+
+    Args:
+        amount_usd: Required payment amount in USD
+        config: X402Config with recipient addresses
+        message: Optional custom message (default: generated)
+        resource_description: Optional description of what's being purchased
+
+    Returns:
+        Dictionary suitable for JSON response body
+
+    Example:
+        >>> config = X402Config(recipient_evm="0x...")
+        >>> response_body = create_402_response(
+        ...     amount_usd=Decimal("10.00"),
+        ...     config=config,
+        ...     message="Payment required for API access"
+        ... )
+        >>> return JSONResponse(status_code=402, content=response_body)
+    """
+    amount = Decimal(str(amount_usd))
+
+    # Build recipients map
+    recipients: Dict[str, str] = {}
+    if config.recipient_evm:
+        recipients["evm"] = config.recipient_evm
+    if config.recipient_solana:
+        recipients["solana"] = config.recipient_solana
+    if config.recipient_near:
+        recipients["near"] = config.recipient_near
+    if config.recipient_stellar:
+        recipients["stellar"] = config.recipient_stellar
+
+    # Get supported chain IDs and network names
+    supported_chains: List[Union[int, str]] = []
+
+    for network_name in config.supported_networks:
+        network = get_network(network_name)
+        if network and network.enabled and config.is_network_enabled(network_name):
+            if network.network_type == NetworkType.EVM and network.chain_id > 0:
+                supported_chains.append(network.chain_id)
+            else:
+                # Non-EVM networks: include name
+                supported_chains.append(network_name)
+
+    # Default message
+    if not message:
+        message = f"Payment of ${amount} USDC required"
+        if resource_description:
+            message += f" for {resource_description}"
+
+    response = Payment402Response(
+        error="Payment required",
+        recipient=config.recipient_evm,  # Default for backward compatibility
+        recipients=recipients if recipients else None,
+        facilitator=config.facilitator_solana,
+        amount=str(amount),
+        token="USDC",
+        supportedChains=supported_chains,
+        message=message,
+    )
+
+    return response.model_dump(exclude_none=True, by_alias=True)
+
+
+def create_402_headers(
+    accept_payment: str = "x402 USDC 1.0",
+) -> Dict[str, str]:
+    """
+    Create headers for a 402 response.
+
+    Args:
+        accept_payment: Value for X-Accept-Payment header
+
+    Returns:
+        Dictionary of headers
+    """
+    return {
+        "Content-Type": "application/json",
+        "X-Accept-Payment": accept_payment,
+    }
+
+
+def payment_required_response(
+    amount_usd: Union[Decimal, float, str],
+    config: X402Config,
+    message: Optional[str] = None,
+) -> tuple:
+    """
+    Create a complete 402 response (body, headers, status code).
+
+    Useful for frameworks that accept tuple responses.
+
+    Args:
+        amount_usd: Required payment amount
+        config: X402Config with recipient addresses
+        message: Optional custom message
+
+    Returns:
+        Tuple of (body_dict, headers_dict, status_code)
+
+    Example (Flask):
+        >>> @app.route("/api/resource")
+        >>> def resource():
+        ...     if not has_payment:
+        ...         body, headers, status = payment_required_response(
+        ...             amount_usd="1.00", config=config
+        ...         )
+        ...         return body, status, headers
+    """
+    body = create_402_response(amount_usd, config, message)
+    headers = create_402_headers()
+    return body, headers, 402
+
+
+class Payment402Builder:
+    """
+    Builder class for constructing 402 responses with fluent API.
+
+    Example:
+        >>> response = (
+        ...     Payment402Builder(config)
+        ...     .amount(Decimal("5.00"))
+        ...     .message("Premium feature access required")
+        ...     .networks(["base", "solana"])
+        ...     .build()
+        ... )
+    """
+
+    def __init__(self, config: X402Config) -> None:
+        self._config = config
+        self._amount: Decimal = Decimal("1.00")
+        self._message: Optional[str] = None
+        self._description: Optional[str] = None
+        self._networks: Optional[List[str]] = None
+        self._extra_data: Dict[str, Any] = {}
+
+    def amount(self, usd: Union[Decimal, float, str]) -> "Payment402Builder":
+        """Set the required payment amount in USD."""
+        self._amount = Decimal(str(usd))
+        return self
+
+    def message(self, msg: str) -> "Payment402Builder":
+        """Set the payment message."""
+        self._message = msg
+        return self
+
+    def description(self, desc: str) -> "Payment402Builder":
+        """Set the resource description."""
+        self._description = desc
+        return self
+
+    def networks(self, network_names: List[str]) -> "Payment402Builder":
+        """Limit to specific networks."""
+        self._networks = network_names
+        return self
+
+    def extra(self, key: str, value: Any) -> "Payment402Builder":
+        """Add extra data to the response."""
+        self._extra_data[key] = value
+        return self
+
+    def build(self) -> Dict[str, Any]:
+        """Build the response body."""
+        # Create modified config if networks are limited
+        if self._networks:
+            limited_config = X402Config(
+                facilitator_url=self._config.facilitator_url,
+                recipient_evm=self._config.recipient_evm,
+                recipient_solana=self._config.recipient_solana,
+                recipient_near=self._config.recipient_near,
+                recipient_stellar=self._config.recipient_stellar,
+                facilitator_solana=self._config.facilitator_solana,
+                supported_networks=self._networks,
+            )
+        else:
+            limited_config = self._config
+
+        response = create_402_response(
+            amount_usd=self._amount,
+            config=limited_config,
+            message=self._message,
+            resource_description=self._description,
+        )
+
+        # Add extra data
+        response.update(self._extra_data)
+
+        return response
+
+    def build_tuple(self) -> tuple:
+        """Build complete response tuple (body, headers, status)."""
+        return self.build(), create_402_headers(), 402
+
+
+# =============================================================================
+# x402 v2 Response Helpers
+# =============================================================================
+
+
+def create_402_response_v2(
+    amount_usd: Union[Decimal, float, str],
+    config: X402Config,
+    resource: str = "",
+    description: str = "",
+    networks: Optional[List[str]] = None,
+) -> Dict[str, Any]:
+    """
+    Create an x402 v2 format 402 response with accepts array.
+
+    x402 v2 uses CAIP-2 network identifiers and allows clients to
+    choose from multiple payment options.
+
+    Args:
+        amount_usd: Required payment amount in USD
+        config: X402Config with recipient addresses
+        resource: Resource URL being purchased
+        description: Human-readable description
+        networks: List of networks to offer (default: all enabled)
+
+    Returns:
+        Dictionary suitable for JSON response body
+
+    Example:
+        >>> response = create_402_response_v2(
+        ...     amount_usd=Decimal("5.00"),
+        ...     config=config,
+        ...     resource="/api/premium",
+        ...     description="Premium API access",
+        ... )
+    """
+    amount = Decimal(str(amount_usd))
+
+    # Determine which networks to include
+    if networks:
+        network_list = networks
+    else:
+        network_list = config.supported_networks
+
+    # Build accepts array
+    accepts: List[Dict[str, Any]] = []
+
+    for network_name in network_list:
+        network = get_network(network_name)
+        if not network or not network.enabled:
+            continue
+        if not config.is_network_enabled(network_name):
+            continue
+
+        # Get CAIP-2 format network ID
+        caip2_network = to_caip2_network(network_name)
+        if not caip2_network:
+            continue
+
+        # Get recipient for this network
+        recipient = config.get_recipient(network_name)
+        if not recipient:
+            continue
+
+        # Calculate amount in token base units
+        token_amount = network.get_token_amount(float(amount))
+
+        option: Dict[str, Any] = {
+            "network": caip2_network,
+            "asset": network.usdc_address,
+            "amount": str(token_amount),
+            "payTo": recipient,
+        }
+
+        # Add EIP-712 domain for EVM chains
+        if network.network_type == NetworkType.EVM:
+            option["extra"] = {
+                "name": network.usdc_domain_name,
+                "version": network.usdc_domain_version,
+            }
+
+        accepts.append(option)
+
+    return {
+        "x402Version": 2,
+        "scheme": "exact",
+        "resource": resource or config.resource_url or "/api/resource",
+        "description": description or config.description,
+        "mimeType": "application/json",
+        "maxTimeoutSeconds": 60,
+        "accepts": accepts,
+    }
+
+
+def create_402_headers_v2(
+    requirements: Dict[str, Any],
+) -> Dict[str, str]:
+    """
+    Create headers for an x402 v2 402 response.
+
+    The PAYMENT-REQUIRED header contains base64-encoded JSON of the
+    payment requirements.
+
+    Args:
+        requirements: Payment requirements dictionary
+
+    Returns:
+        Dictionary of headers
+    """
+    import base64
+    import json
+
+    requirements_json = json.dumps(requirements, separators=(',', ':'))
+    requirements_b64 = base64.b64encode(requirements_json.encode()).decode()
+
+    return {
+        "Content-Type": "application/json",
+        "PAYMENT-REQUIRED": requirements_b64,
+        "X-Accept-Payment": "x402 USDC 2.0",
+    }
+
+
+def payment_required_response_v2(
+    amount_usd: Union[Decimal, float, str],
+    config: X402Config,
+    resource: str = "",
+    description: str = "",
+    networks: Optional[List[str]] = None,
+) -> tuple:
+    """
+    Create a complete x402 v2 402 response (body, headers, status code).
+
+    Args:
+        amount_usd: Required payment amount
+        config: X402Config with recipient addresses
+        resource: Resource URL
+        description: Description
+        networks: Networks to offer
+
+    Returns:
+        Tuple of (body_dict, headers_dict, status_code)
+    """
+    body = create_402_response_v2(amount_usd, config, resource, description, networks)
+    headers = create_402_headers_v2(body)
+    return body, headers, 402
+
+
+class Payment402BuilderV2:
+    """
+    Builder class for constructing x402 v2 402 responses.
+
+    Example:
+        >>> response = (
+        ...     Payment402BuilderV2(config)
+        ...     .amount(Decimal("5.00"))
+        ...     .resource("/api/premium")
+        ...     .description("Premium feature access")
+        ...     .networks(["base", "solana", "near"])
+        ...     .build()
+        ... )
+    """
+
+    def __init__(self, config: X402Config) -> None:
+        self._config = config
+        self._amount: Decimal = Decimal("1.00")
+        self._resource: str = ""
+        self._description: str = ""
+        self._networks: Optional[List[str]] = None
+
+    def amount(self, usd: Union[Decimal, float, str]) -> "Payment402BuilderV2":
+        """Set the required payment amount in USD."""
+        self._amount = Decimal(str(usd))
+        return self
+
+    def resource(self, url: str) -> "Payment402BuilderV2":
+        """Set the resource URL."""
+        self._resource = url
+        return self
+
+    def description(self, desc: str) -> "Payment402BuilderV2":
+        """Set the resource description."""
+        self._description = desc
+        return self
+
+    def networks(self, network_names: List[str]) -> "Payment402BuilderV2":
+        """Limit to specific networks."""
+        self._networks = network_names
+        return self
+
+    def build(self) -> Dict[str, Any]:
+        """Build the v2 response body."""
+        return create_402_response_v2(
+            amount_usd=self._amount,
+            config=self._config,
+            resource=self._resource,
+            description=self._description,
+            networks=self._networks,
+        )
+
+    def build_with_headers(self) -> tuple:
+        """Build complete response with headers (body, headers, status)."""
+        body = self.build()
+        headers = create_402_headers_v2(body)
+        return body, headers, 402

uvd_x402_sdk-0.2.0.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ultravioleta DAO
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.