traia-iatp 0.1.2__py3-none-any.whl → 0.1.67__py3-none-any.whl

traia_iatp/d402/payment_signing.py

@@ -0,0 +1,183 @@
+import time
+import secrets
+import logging
+from typing import Dict, Any
+from typing_extensions import (
+    TypedDict,
+)  # use `typing_extensions.TypedDict` instead of `typing.TypedDict` on Python < 3.12
+from eth_account import Account
+from .encoding import safe_base64_encode, safe_base64_decode
+from .types import (
+    PaymentRequirements,
+)
+from .chains import get_chain_id
+import json
+
+logger = logging.getLogger(__name__)
+
+
+def create_nonce() -> bytes:
+    """Create a random 32-byte nonce for authorization signatures."""
+    return secrets.token_bytes(32)
+
+
+def prepare_payment_header(
+    sender_address: str, d402_version: int, payment_requirements: PaymentRequirements
+) -> Dict[str, Any]:
+    """Prepare an unsigned payment header with sender address, d402 version, and payment requirements."""
+    nonce = create_nonce()
+    valid_after = str(int(time.time()) - 60)  # 60 seconds before
+    # Ensure at least 24 hours for settlement (facilitator batches payments)
+    min_deadline_seconds = max(payment_requirements.max_timeout_seconds, 86400)  # 24 hours
+    valid_before = str(int(time.time()) + min_deadline_seconds)
+
+    return {
+        "d402Version": d402_version,
+        "scheme": payment_requirements.scheme,
+        "network": payment_requirements.network,
+        "payload": {
+            "signature": None,
+            "authorization": {
+                "from": sender_address,
+                "to": payment_requirements.pay_to,
+                "value": payment_requirements.max_amount_required,
+                "validAfter": valid_after,
+                "validBefore": valid_before,
+                "nonce": nonce,
+            },
+        },
+    }
+
+
+class PaymentHeader(TypedDict):
+    d402Version: int
+    scheme: str
+    network: str
+    payload: dict[str, Any]
+
+
+def sign_payment_header(
+    operator_account: Account, 
+    payment_requirements: PaymentRequirements, 
+    header: PaymentHeader,
+    wallet_address: str = None,
+    request_path: str = None
+) -> str:
+    """
+    Sign a payment header using EIP-712 PullFundsForSettlement signature.
+    
+    This signature format matches IATPWallet.sol validateConsumerSignature.
+    
+    Contract Type Hash (IATPWallet.sol line 34-36):
+    PullFundsForSettlement(
+        address wallet,      // Consumer's IATPWallet contract address
+        address provider,    // Provider's IATPWallet contract address
+        address token,       // Token address (USDC, etc.)
+        uint256 amount,      // Payment amount
+        uint256 deadline,    // Signature expiration
+        string requestPath   // API path (e.g., "/mcp/tools/call")
+    )
+    
+    Note: chainId is in the EIP-712 domain, NOT in the message (per EIP-712 standard)
+    
+    Args:
+        operator_account: Operator account with private key for signing (EOA)
+        payment_requirements: Payment requirements from server
+        header: Payment header structure
+        wallet_address: Consumer's IATPWallet contract address (if None, uses operator_account.address)
+        request_path: API request path (if None, uses payment_requirements.resource)
+    """
+    try:
+        auth = header["payload"]["authorization"]
+        
+        # Get wallet address (IATPWallet contract, not EOA)
+        consumer_wallet = wallet_address or auth["from"]
+        
+        # Get request path from payment_requirements if not provided
+        if request_path is None:
+            request_path = payment_requirements.resource or "/mcp"
+            logger.info(f"🔍 payment_requirements.resource: {payment_requirements.resource}")
+            logger.info(f"🔍 Using request_path: {request_path}")
+        
+        # Ensure we have a valid request path (contract requires non-empty string)
+        if not request_path or request_path.strip() == "":
+            logger.warning(f"⚠️  request_path was empty, defaulting to /mcp")
+            request_path = "/mcp"
+        
+        # Get domain info from payment_requirements.extra (IATPWallet domain)
+        extra = payment_requirements.extra or {}
+        wallet_name = extra.get("name", "IATPWallet")
+        wallet_version = extra.get("version", "1")
+        
+        # Build EIP-712 typed data for PullFundsForSettlement
+        # Note: chainId is in the domain, not the message (EIP-712 standard)
+        typed_data = {
+            "types": {
+                "PullFundsForSettlement": [
+                    {"name": "wallet", "type": "address"},
+                    {"name": "provider", "type": "address"},
+                    {"name": "token", "type": "address"},
+                    {"name": "amount", "type": "uint256"},
+                    {"name": "deadline", "type": "uint256"},
+                    {"name": "requestPath", "type": "string"},
+                ]
+            },
+            "primaryType": "PullFundsForSettlement",
+            "domain": {
+                "name": wallet_name,
+                "version": wallet_version,
+                "chainId": int(get_chain_id(payment_requirements.network)),  # chainId in domain only
+                "verifyingContract": consumer_wallet,  # Consumer's IATPWallet contract
+            },
+            "message": {
+                "wallet": consumer_wallet,  # Consumer's IATPWallet contract address
+                "provider": auth["to"],  # Provider's IATPWallet contract address
+                "token": payment_requirements.asset,  # Token address (e.g., USDC)
+                "amount": int(auth["value"]),
+                "deadline": int(auth["validBefore"]),
+                "requestPath": request_path,  # Actual API path, not nonce
+            },
+        }
+
+        signed_message = operator_account.sign_typed_data(
+            domain_data=typed_data["domain"],
+            message_types=typed_data["types"],
+            message_data=typed_data["message"],
+        )
+        signature = signed_message.signature.hex()
+        if not signature.startswith("0x"):
+            signature = f"0x{signature}"
+
+        header["payload"]["signature"] = signature
+        
+        # Store wallet address and request path in header for verification
+        header["payload"]["authorization"]["from"] = consumer_wallet
+        header["payload"]["authorization"]["requestPath"] = request_path
+
+        encoded = encode_payment(header)
+        return encoded
+    except Exception:
+        raise
+
+
+def encode_payment(payment_payload: Dict[str, Any]) -> str:
+    """Encode a payment payload into a base64 string, handling HexBytes and other non-serializable types."""
+    from hexbytes import HexBytes
+
+    def default(obj):
+        if isinstance(obj, HexBytes):
+            return obj.hex()
+        if hasattr(obj, "to_dict"):
+            return obj.to_dict()
+        if hasattr(obj, "hex"):
+            return obj.hex()
+        raise TypeError(
+            f"Object of type {obj.__class__.__name__} is not JSON serializable"
+        )
+
+    return safe_base64_encode(json.dumps(payment_payload, default=default))
+
+
+def decode_payment(encoded_payment: str) -> Dict[str, Any]:
+    """Decode a base64 encoded payment string back into a PaymentPayload object."""
+    return json.loads(safe_base64_decode(encoded_payment))

traia_iatp/d402/price_builder.py

@@ -0,0 +1,164 @@
+"""
+D402 Price Builder - Helper for creating payment amounts.
+
+Simplifies creating TokenAmount objects for payment configuration with any token.
+"""
+
+from .types import TokenAmount, TokenAsset, EIP712Domain
+
+
+class D402PriceBuilder:
+    """
+    Helper class for building D402 payment amounts with any token.
+    
+    Initialize once with your token configuration, then create prices easily.
+    
+    Usage:
+        # Initialize with ANY token configuration
+        builder = D402PriceBuilder(
+            token_address="0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238",  # Your token
+            token_decimals=6,                                              # Your decimals
+            network="sepolia",                                             # Your network
+            token_symbol="USDC"                                            # Your symbol
+        )
+        
+        # Create prices easily
+        price_cheap = builder.create_price(0.001)   # $0.001 
+        price_standard = builder.create_price(0.01) # $0.01
+        price_premium = builder.create_price(0.05)  # $0.05
+        
+        # Use in decorators
+        @require_payment(price=price_premium, description="Premium API call")
+        async def premium_endpoint():
+            pass
+    
+    Examples:
+        # USDC on Sepolia (6 decimals)
+        usdc_builder = D402PriceBuilder(
+            token_address="0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238",
+            token_decimals=6,
+            network="sepolia",
+            token_symbol="USDC"
+        )
+        
+        # TRAIA token (18 decimals)
+        traia_builder = D402PriceBuilder(
+            token_address="0x...",
+            token_decimals=18,
+            network="base-mainnet",
+            token_symbol="TRAIA"
+        )
+        
+        # Any custom token
+        custom_builder = D402PriceBuilder(
+            token_address="0xYourToken...",
+            token_decimals=8,  # Your token's decimals
+            network="arbitrum-mainnet",
+            token_symbol="CUSTOM"
+        )
+    """
+    
+    def __init__(
+        self,
+        token_address: str,
+        token_decimals: int,
+        network: str,
+        token_symbol: str = "TOKEN",
+        eip712_name: str = "IATPWallet",
+        eip712_version: str = "1"
+    ):
+        """
+        Initialize the price builder with token configuration.
+        
+        Args:
+            token_address: ERC20 token contract address
+            token_decimals: Token decimals (6 for USDC, 18 for most ERC20)
+            network: Blockchain network (sepolia, base-sepolia, base-mainnet, etc.)
+            token_symbol: Token symbol for display (USDC, TRAIA, DAI, etc.)
+            eip712_name: EIP-712 domain name (default: "IATPWallet")
+            eip712_version: EIP-712 domain version (default: "1")
+        """
+        self.token_address = token_address
+        self.token_decimals = token_decimals
+        self.network = network
+        self.token_symbol = token_symbol
+        self.eip712_domain = EIP712Domain(
+            name=eip712_name,
+            version=eip712_version
+        )
+    
+    def create_price(self, amount_usd: float) -> TokenAmount:
+        """
+        Create a TokenAmount from USD amount.
+        
+        Automatically converts USD to token's atomic units based on decimals.
+        
+        Args:
+            amount_usd: Amount in USD (e.g., 0.01 for 1 cent, 0.05 for 5 cents)
+        
+        Returns:
+            TokenAmount object ready to use in payment configs
+        
+        Examples:
+            # USDC (6 decimals)
+            price = builder.create_price(0.01)   # → "10000" wei (0.01 * 10^6)
+            price = builder.create_price(0.001)  # → "1000" wei
+            price = builder.create_price(1.00)   # → "1000000" wei
+            
+            # TRAIA (18 decimals)
+            price = builder.create_price(0.01)   # → "10000000000000000" wei (0.01 * 10^18)
+            
+            # Use in decorator
+            @require_payment(price=price, description="API call")
+            async def my_endpoint():
+                pass
+        """
+        # Convert USD to wei/atomic units based on token decimals
+        # Formula: amount_wei = amount_usd * (10 ** decimals)
+        amount_wei = str(int(amount_usd * (10 ** self.token_decimals)))
+        
+        return TokenAmount(
+            amount=amount_wei,
+            asset=TokenAsset(
+                address=self.token_address,
+                decimals=self.token_decimals,
+                network=self.network,
+                symbol=self.token_symbol,
+                eip712=self.eip712_domain
+            )
+        )
+    
+    def create_price_wei(self, amount_wei: str) -> TokenAmount:
+        """
+        Create a TokenAmount from wei/atomic units directly.
+        
+        Useful when you already know the exact atomic amount.
+        
+        Args:
+            amount_wei: Amount in atomic units as string (e.g., "10000" for 0.01 USDC)
+        
+        Returns:
+            TokenAmount object ready to use in payment configs
+        
+        Example:
+            # Exact atomic amount (useful for non-USD pricing)
+            price = builder.create_price_wei("10000")  # Exactly 10000 atomic units
+        """
+        return TokenAmount(
+            amount=amount_wei,
+            asset=TokenAsset(
+                address=self.token_address,
+                decimals=self.token_decimals,
+                network=self.network,
+                symbol=self.token_symbol,
+                eip712=self.eip712_domain
+            )
+        )
+    
+    def __repr__(self) -> str:
+        return f"D402PriceBuilder(token={self.token_symbol}, network={self.network}, decimals={self.token_decimals})"
+
+
+__all__ = ["D402PriceBuilder"]
+
+

traia_iatp/d402/servers/__init__.py

@@ -0,0 +1,61 @@
+"""D402 payment middleware for various server frameworks.
+
+This module provides framework-specific middleware implementations for the d402
+payment protocol. Each framework has its own module with appropriate middleware.
+
+Supported frameworks:
+- Starlette: For Starlette-based applications (including FastMCP)
+- FastAPI: For FastAPI applications  
+- MCP: For Model Context Protocol (MCP) servers with tool decorators
+
+Usage examples:
+
+1. MCP Server (FastMCP):
+    from traia_iatp.d402.servers import D402PaymentMiddleware, require_payment_for_tool
+    
+    app = mcp.streamable_http_app()
+    app.add_middleware(D402PaymentMiddleware, ...)
+
+2. FastAPI Server:
+    from traia_iatp.d402.servers.fastapi import D402FastAPIMiddleware, require_payment
+    
+    app = FastAPI()
+    middleware = D402FastAPIMiddleware(...)
+    middleware.add_to_app(app)
+
+3. Starlette Server:
+    from traia_iatp.d402.servers import D402PaymentMiddleware
+    
+    app = Starlette()
+    app.add_middleware(D402PaymentMiddleware, ...)
+"""
+
+from .starlette import (
+    D402PaymentMiddleware,
+    require_payment,
+    extract_payment_configs,
+    build_payment_config,
+)
+from .mcp import (
+    EndpointPaymentInfo,
+    get_active_api_key,
+    require_payment_for_tool,
+    settle_payment,
+)
+
+__all__ = [
+    # Starlette middleware (works for any Starlette-based app)
+    "D402PaymentMiddleware",
+    
+    # Generic decorators and extractors (for any server type)
+    "require_payment",
+    "extract_payment_configs",
+    "build_payment_config",
+    
+    # MCP-specific helpers (wraps require_payment for MCP tools)
+    "EndpointPaymentInfo",
+    "get_active_api_key",
+    "require_payment_for_tool",
+    "settle_payment",
+]
+

traia_iatp/d402/servers/base.py

@@ -0,0 +1,139 @@
+"""Base classes and utilities for d402 server middleware.
+
+This module provides shared functionality used across different server framework
+implementations.
+"""
+
+import logging
+from typing import Dict, Any, Optional
+from enum import Enum
+
+logger = logging.getLogger(__name__)
+
+
+class PaymentMode(Enum):
+    """Payment mode for a request."""
+    FREE_WITH_API_KEY = "free_with_api_key"  # Client has valid API key
+    PAID_WITH_SERVER_KEY = "paid_with_server_key"  # Client paid, server uses internal key
+    NO_PAYMENT = "no_payment"  # No payment required
+
+
+class BasePaymentConfig:
+    """Base configuration for payment-enabled servers.
+    
+    This class provides common configuration used across all server frameworks.
+    """
+    
+    def __init__(
+        self,
+        server_address: str,
+        requires_auth: bool = False,
+        internal_api_key: Optional[str] = None,
+        testing_mode: bool = False,
+        facilitator_url: Optional[str] = None,
+        facilitator_api_key: Optional[str] = None,
+        server_name: Optional[str] = None
+    ):
+        """Initialize payment configuration.
+        
+        Args:
+            server_address: Address where payments should be sent
+            requires_auth: Whether server accepts API keys for free access
+            internal_api_key: Server's internal API key (used when client pays)
+            testing_mode: If True, skip facilitator verification
+            facilitator_url: URL of the payment facilitator
+            facilitator_api_key: API key for facilitator authentication
+            server_name: Name/ID of this server for tracking
+        """
+        self.server_address = server_address
+        self.requires_auth = requires_auth
+        self.internal_api_key = internal_api_key
+        self.testing_mode = testing_mode
+        self.facilitator_url = facilitator_url
+        self.facilitator_api_key = facilitator_api_key
+        self.server_name = server_name
+        
+        self.validate()
+    
+    def validate(self):
+        """Validate configuration."""
+        if not self.server_address:
+            raise ValueError("server_address is required")
+        
+        if not self.testing_mode and not self.facilitator_url:
+            raise ValueError("facilitator_url required when testing_mode is False")
+
+
+def extract_api_key_from_headers(headers: Dict[str, str]) -> Optional[str]:
+    """Extract API key from request headers.
+    
+    Supports both Authorization: Bearer <token> and X-API-KEY: <token> formats.
+    
+    Args:
+        headers: Request headers (dict or Headers object)
+        
+    Returns:
+        API key string if found, None otherwise
+    """
+    # Authorization header
+    auth = headers.get("authorization") or headers.get("Authorization", "")
+    if auth.lower().startswith("bearer "):
+        return auth[7:].strip()
+    
+    # X-API-KEY header
+    api_key = headers.get("x-api-key") or headers.get("X-API-KEY", "")
+    if api_key:
+        return api_key.strip()
+    
+    return None
+
+
+def log_payment_verification_start(tool_name: str, has_auth: bool, payment_header_present: bool):
+    """Log start of payment verification process.
+    
+    Args:
+        tool_name: Name of the tool/endpoint being called
+        has_auth: Whether client has API key
+        payment_header_present: Whether payment header is present
+    """
+    if has_auth:
+        logger.info(f"✅ {tool_name}: Client authenticated with API key (Mode 1: Free)")
+    elif payment_header_present:
+        logger.info(f"💰 {tool_name}: Payment header RECEIVED - validating...")
+    else:
+        logger.info(f"💰 {tool_name}: Payment required (Mode 2) - HTTP 402")
+
+
+def log_payment_validation_success(
+    tool_name: str,
+    payment_amount: int,
+    required_amount: int,
+    from_address: str,
+    to_address: str,
+    request_path: str
+):
+    """Log successful payment validation.
+    
+    Args:
+        tool_name: Name of the tool/endpoint
+        payment_amount: Amount paid
+        required_amount: Amount required
+        from_address: Payer address
+        to_address: Payee address
+        request_path: Request path for signature binding
+    """
+    logger.info(f"✅ {tool_name}: Payment VERIFIED successfully (Mode 2: Paid)")
+    logger.info(f"   Payment amount: {payment_amount} wei (required: {required_amount} wei)")
+    logger.info(f"   From (wallet): {from_address}")
+    logger.info(f"   To (provider): {to_address}")
+    logger.info(f"   Request path: {request_path}")
+
+
+__all__ = [
+    "PaymentMode",
+    "BasePaymentConfig",
+    "extract_api_key_from_headers",
+    "log_payment_verification_start",
+    "log_payment_validation_success",
+]
+

traia_iatp/d402/servers/example_general_server.py

@@ -0,0 +1,140 @@
+"""
+Example: General-purpose API server with D402 payment support.
+
+This example shows how to use the @require_payment decorator for a 
+custom FastAPI server with multiple endpoints at different prices.
+
+This is the same pattern as MCP servers, just generalized for any endpoint!
+"""
+
+import os
+from fastapi import FastAPI, Request
+import uvicorn
+
+from traia_iatp.d402.servers import (
+    D402PaymentMiddleware,
+    require_payment,
+    extract_payment_configs
+)
+from traia_iatp.d402 import D402PriceBuilder
+
+# Initialize FastAPI app
+app = FastAPI(title="Paid Analysis API")
+
+# Get configuration from environment
+SERVER_ADDRESS = os.getenv("SERVER_ADDRESS", "0x1234567890123456789012345678901234567890")
+NETWORK = os.getenv("NETWORK", "sepolia")
+TOKEN_ADDRESS = os.getenv("TOKEN_ADDRESS", "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238")
+TOKEN_DECIMALS = int(os.getenv("TOKEN_DECIMALS", "6"))
+TOKEN_SYMBOL = os.getenv("TOKEN_SYMBOL", "USDC")
+
+# Create price builder - works with ANY token!
+# Just pass your token configuration from environment
+price_builder = D402PriceBuilder(
+    token_address=TOKEN_ADDRESS,
+    token_decimals=TOKEN_DECIMALS,
+    network=NETWORK,
+    token_symbol=TOKEN_SYMBOL
+)
+
+# ============================================================================
+# API ENDPOINTS - Different prices for different operations
+# ============================================================================
+
+@app.post("/quick-check")
+@require_payment(
+    price=price_builder.create_price(0.001),  # $0.001 - uses builder!
+    endpoint_path="/quick-check",
+    description="Quick health check of data"
+)
+async def quick_check(request: Request, data: dict):
+    """Cheap, fast check - only $0.001"""
+    return {"status": "ok", "data_quality": "good"}
+
+
+@app.post("/analyze")
+@require_payment(
+    price=price_builder.create_price(0.01),  # $0.01 - uses builder!
+    endpoint_path="/analyze",
+    description="Standard analysis"
+)
+async def analyze(request: Request, data: dict):
+    """Standard analysis - $0.01"""
+    return {"analysis": "detailed results", "confidence": 0.95}
+
+
+@app.post("/deep-analysis")
+@require_payment(
+    price=price_builder.create_price(0.05),  # $0.05 - uses builder!
+    endpoint_path="/deep-analysis",
+    description="Comprehensive deep analysis with ML models"
+)
+async def deep_analysis(request: Request, data: dict):
+    """Expensive operation - $0.05"""
+    return {
+        "analysis": "very detailed results",
+        "confidence": 0.99,
+        "model": "advanced-ml-v2"
+    }
+
+
+@app.get("/health")
+async def health():
+    """Health check - FREE (no decorator, no payment required)"""
+    return {"status": "healthy"}
+
+
+# ============================================================================
+# D402 MIDDLEWARE SETUP
+# ============================================================================
+
+def create_app_with_middleware():
+    """Add D402 middleware to the app."""
+    
+    # Extract payment configs from @require_payment decorators
+    # This is the SAME approach as MCP servers, just generalized!
+    payment_configs = extract_payment_configs(app, SERVER_ADDRESS)
+    
+    print("=" * 80)
+    print("D402 Payment Configuration:")
+    print(f"  Server Address: {SERVER_ADDRESS}")
+    print(f"  Protected endpoints: {len(payment_configs)}")
+    for path, config in payment_configs.items():
+        price_usd = config['price_float']
+        print(f"    {path}: ${price_usd} USD")
+    print("=" * 80)
+    
+    # Add D402 middleware
+    facilitator_url = os.getenv("D402_FACILITATOR_URL", "http://localhost:7070")
+    testing_mode = os.getenv("D402_TESTING_MODE", "true").lower() == "true"
+    
+    app.add_middleware(
+        D402PaymentMiddleware,
+        server_address=SERVER_ADDRESS,
+        tool_payment_configs=payment_configs,  # Same interface as MCP!
+        requires_auth=False,  # Payment only (no API keys)
+        testing_mode=testing_mode,
+        facilitator_url=facilitator_url,
+        server_name="example-analysis-api"
+    )
+    
+    print("✅ D402 middleware added")
+    print(f"   Testing mode: {testing_mode}")
+    print(f"   Facilitator: {facilitator_url}")
+    print("=" * 80)
+    
+    return app
+
+
+if __name__ == "__main__":
+    # Create app with middleware
+    app_with_d402 = create_app_with_middleware()
+    
+    # Run server
+    port = int(os.getenv("PORT", "8000"))
+    uvicorn.run(
+        app_with_d402,
+        host="0.0.0.0",
+        port=port
+    )
+