traia-iatp 0.1.29__py3-none-any.whl

traia_iatp/d402/middleware.py

@@ -0,0 +1,193 @@
+"""D402 middleware for IATP FastAPI servers (utility agents)."""
+
+import logging
+from typing import Callable, Optional
+from fastapi import Request
+from fastapi.responses import JSONResponse, HTMLResponse
+
+from .fastapi_middleware.middleware import require_payment as d402_require_payment
+from .types import Price, PaywallConfig, HTTPInputSchema
+from typing import Callable, Dict
+from typing_extensions import TypedDict
+
+from .models import D402Config, PaymentScheme
+
+# FacilitatorConfig (copied from d402)
+class FacilitatorConfig(TypedDict, total=False):
+    url: str
+    create_headers: Callable[[], dict[str, dict[str, str]]]
+
+logger = logging.getLogger(__name__)
+
+
+class D402IATPMiddleware:
+    """Middleware that integrates d402 payments into IATP servers.
+    
+    This middleware wraps the Coinbase d402 middleware and adapts it for
+    IATP utility agents, connecting to the custom IATP Settlement Layer.
+    """
+    
+    def __init__(self, config: D402Config):
+        """Initialize the d402 IATP middleware.
+        
+        Args:
+            config: D402 configuration including pricing and facilitator settings
+        """
+        self.config = config
+        self.facilitator_config: FacilitatorConfig = {
+            "url": config.facilitator_url,
+        }
+        
+        # Add authentication headers if API key is provided
+        if config.facilitator_api_key:
+            async def create_headers():
+                return {
+                    "verify": {"Authorization": f"Bearer {config.facilitator_api_key}"},
+                    "settle": {"Authorization": f"Bearer {config.facilitator_api_key}"}
+                }
+            self.facilitator_config["create_headers"] = create_headers
+    
+    def create_middleware(
+        self,
+        skill_id: Optional[str] = None,
+        custom_price: Optional[Price] = None,
+        custom_description: Optional[str] = None,
+    ) -> Callable:
+        """Create a FastAPI middleware function for a specific skill or endpoint.
+        
+        Args:
+            skill_id: Optional skill ID to use custom pricing
+            custom_price: Optional override price
+            custom_description: Optional override description
+            
+        Returns:
+            FastAPI middleware function
+        """
+        if not self.config.enabled:
+            # Return passthrough middleware if payments not enabled
+            async def passthrough(request: Request, call_next: Callable):
+                return await call_next(request)
+            return passthrough
+        
+        # Determine the price to use
+        if custom_price:
+            price = custom_price
+        elif skill_id and skill_id in self.config.skill_prices:
+            price_config = self.config.skill_prices[skill_id]
+            price = price_config.usd_amount
+        else:
+            price = self.config.default_price.usd_amount
+        
+        # Determine the description
+        description = custom_description or self.config.service_description
+        
+        # Get the pricing configuration
+        price_config = (
+            self.config.skill_prices.get(skill_id) 
+            if skill_id and skill_id in self.config.skill_prices
+            else self.config.default_price
+        )
+        
+        # Create the d402 middleware using Coinbase's implementation
+        return d402_require_payment(
+            price=price,
+            pay_to_address=self.config.pay_to_address,
+            path=self.config.protected_paths,
+            description=description,
+            mime_type="application/json",
+            max_deadline_seconds=price_config.max_timeout_seconds,
+            input_schema=HTTPInputSchema(
+                query_params=None,
+                body_type="json",
+                body_fields=None,
+                header_fields=None
+            ),
+            output_schema=None,
+            discoverable=True,
+            facilitator_config=self.facilitator_config,
+            network=price_config.network,
+            resource=None,  # Will be determined from request URL
+            paywall_config=None,  # Could add custom paywall UI here
+            custom_paywall_html=None
+        )
+
+
+def require_iatp_payment(
+    config: D402Config,
+    skill_id: Optional[str] = None,
+    custom_price: Optional[Price] = None,
+    custom_description: Optional[str] = None,
+) -> Callable:
+    """Convenience function to create d402 middleware for IATP.
+    
+    Usage:
+        @app.middleware("http")
+        async def payment_middleware(request: Request, call_next):
+            middleware = require_iatp_payment(d402_config)
+            return await middleware(request, call_next)
+    
+    Or for specific routes:
+        @app.post("/process")
+        async def process_request(request: Request):
+            # Will require payment
+            pass
+        
+        app.middleware("http")(
+            require_iatp_payment(d402_config, skill_id="process_request")
+        )
+    
+    Args:
+        config: D402 configuration
+        skill_id: Optional skill ID for custom pricing
+        custom_price: Optional price override
+        custom_description: Optional description override
+        
+    Returns:
+        FastAPI middleware function
+    """
+    middleware = D402IATPMiddleware(config)
+    return middleware.create_middleware(skill_id, custom_price, custom_description)
+
+
+async def add_d402_info_to_agent_card(agent_card: dict, config: D402Config) -> dict:
+    """Add d402 payment information to an agent card.
+    
+    This adds payment capabilities to the agent card for client discovery.
+    
+    Args:
+        agent_card: The agent card dictionary
+        config: D402 configuration
+        
+    Returns:
+        Updated agent card with payment information
+    """
+    if not config.enabled:
+        return agent_card
+    
+    # Add d402 payment information to metadata
+    agent_card.setdefault("metadata", {})
+    agent_card["metadata"]["d402"] = {
+        "enabled": True,
+        "paymentSchemes": [PaymentScheme.EXACT.value],
+        "networks": [config.default_price.network],
+        "defaultPrice": {
+            "usdAmount": config.default_price.usd_amount,
+            "network": config.default_price.network,
+            "asset": config.default_price.asset_address,
+            "maxTimeoutSeconds": config.default_price.max_timeout_seconds
+        },
+        "payToAddress": config.pay_to_address,
+        "facilitatorUrl": config.facilitator_url,
+        "skillPrices": {
+            skill_id: {
+                "usdAmount": price.usd_amount,
+                "network": price.network,
+                "asset": price.asset_address,
+                "maxTimeoutSeconds": price.max_timeout_seconds
+            }
+            for skill_id, price in config.skill_prices.items()
+        }
+    }
+    
+    return agent_card
+

traia_iatp/d402/models.py

@@ -0,0 +1,116 @@
+"""D402 payment models for IATP protocol."""
+
+from enum import Enum
+from typing import Optional, Dict, Any
+from pydantic import BaseModel, Field
+
+
+class PaymentScheme(str, Enum):
+    """Payment schemes supported by d402."""
+    EXACT = "exact"  # EIP-3009 exact payment
+
+
+class D402ServicePrice(BaseModel):
+    """Pricing configuration for an IATP service.
+    
+    Supports any ERC20 token payment with full token details.
+    """
+    
+    # Token details
+    token_address: str = Field(..., description="Token contract address (e.g., USDC, TRAIA, DAI)")
+    token_symbol: str = Field(..., description="Token symbol for display")
+    token_decimals: int = Field(..., description="Token decimals (6 for USDC, 18 for most)")
+    
+    # Price (stored in multiple formats for convenience)
+    price_wei: str = Field(..., description="Price in wei/atomic units")
+    price_float: float = Field(..., description="Price in token units (human-readable)")
+    
+    # Network configuration
+    network: str = Field(..., description="Network (sepolia, base-sepolia, etc.)")
+    chain_id: int = Field(..., description="Chain ID")
+    
+    # Optional USD equivalent (for display only)
+    usd_amount: Optional[float] = Field(None, description="Approximate USD value")
+    
+    # Maximum timeout for payment completion
+    max_timeout_seconds: int = Field(default=300, description="Max time to complete payment")
+
+
+class D402Config(BaseModel):
+    """Configuration for d402 payment integration in IATP.
+    
+    Supports per-path pricing with different tokens.
+    """
+    
+    # Enable/disable d402 payments
+    enabled: bool = Field(default=False, description="Enable d402 payments")
+    
+    # Payment address (utility agent contract address)
+    pay_to_address: str = Field(..., description="Ethereum address to receive payments")
+    
+    # Pricing configuration
+    # Can be per-path (e.g., {"/analyze": D402ServicePrice(...), "/extract": D402ServicePrice(...)})
+    # or default for all paths
+    path_prices: Dict[str, D402ServicePrice] = Field(
+        default_factory=dict,
+        description="Price configuration per path"
+    )
+    
+    # Default price (used if path not in path_prices)
+    default_price: Optional[D402ServicePrice] = Field(None, description="Default price for all paths")
+    
+    # Legacy: Pricing per service/skill (deprecated, use path_prices)
+    skill_prices: Dict[str, D402ServicePrice] = Field(
+        default_factory=dict, 
+        description="Custom prices per skill ID (deprecated)"
+    )
+    
+    # Facilitator configuration
+    facilitator_url: str = Field(
+        default="https://api.traia.io/d402/facilitator",
+        description="URL of the d402 facilitator service"
+    )
+    
+    # Custom facilitator authentication (if needed)
+    facilitator_api_key: Optional[str] = Field(None, description="API key for facilitator")
+    
+    # Paths to gate with payments (* for all)
+    protected_paths: list[str] = Field(
+        default_factory=lambda: ["*"],
+        description="Paths that require payment"
+    )
+    
+    # Service description for payment prompt
+    service_description: str = Field(..., description="Description shown in payment UI")
+    
+    # Metadata
+    metadata: Dict[str, Any] = Field(default_factory=dict, description="Additional metadata")
+
+
+class D402PaymentInfo(BaseModel):
+    """Payment information for agent card discovery."""
+    
+    enabled: bool = Field(..., description="Whether d402 is enabled")
+    payment_schemes: list[PaymentScheme] = Field(
+        default_factory=lambda: [PaymentScheme.EXACT],
+        description="Supported payment schemes"
+    )
+    networks: list[str] = Field(..., description="Supported blockchain networks")
+    default_price: D402ServicePrice = Field(..., description="Default pricing")
+    facilitator_url: str = Field(..., description="Facilitator service URL")
+    
+    class Config:
+        use_enum_values = True
+
+
+class IATPSettlementRequest(BaseModel):
+    """Request to settle a payment through IATP settlement layer."""
+    
+    consumer: str = Field(..., description="Consumer address (client agent)")
+    provider: str = Field(..., description="Provider address (utility agent)")
+    amount: str = Field(..., description="Amount in atomic units")
+    timestamp: int = Field(..., description="Request timestamp")
+    service_description: str = Field(..., description="Description of service")
+    consumer_signature: str = Field(..., description="Consumer's EIP-712 signature")
+    provider_signature: str = Field(..., description="Provider's attestation signature")
+

traia_iatp/d402/networks.py

@@ -0,0 +1,98 @@
+"""Network configuration for d402 payments.
+
+This module defines supported networks and their token configurations.
+Customized for IATP - uses database-driven network configuration.
+"""
+
+from typing import Literal, Dict, Any
+from typing_extensions import TypedDict
+
+
+# Network type definition
+SupportedNetworks = Literal[
+    "sepolia",
+    "base-sepolia",
+    "arbitrum-sepolia",
+    "base-mainnet",
+    "arbitrum-mainnet",
+]
+
+
+class NetworkConfig(TypedDict):
+    """Network configuration."""
+    chain_id: int
+    name: str
+    rpc_url: str
+    explorer_url: str
+    usdc_address: str
+
+
+# Network configurations
+NETWORKS: Dict[str, NetworkConfig] = {
+    "sepolia": {
+        "chain_id": 11155111,
+        "name": "Ethereum Sepolia",
+        "rpc_url": "https://ethereum-sepolia-rpc.publicnode.com",
+        "explorer_url": "https://sepolia.etherscan.io",
+        "usdc_address": "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238"
+    },
+    "base-sepolia": {
+        "chain_id": 84532,
+        "name": "Base Sepolia",
+        "rpc_url": "https://sepolia.base.org",
+        "explorer_url": "https://sepolia.basescan.org",
+        "usdc_address": "0x036CbD53842c5426634e7929541eC2318f3dCF7e"
+    },
+    "arbitrum-sepolia": {
+        "chain_id": 421614,
+        "name": "Arbitrum Sepolia",
+        "rpc_url": "https://arbitrum-sepolia-rpc.publicnode.com",
+        "explorer_url": "https://sepolia.arbiscan.io",
+        "usdc_address": "0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d"
+    },
+    "base-mainnet": {
+        "chain_id": 8453,
+        "name": "Base",
+        "rpc_url": "https://mainnet.base.org",
+        "explorer_url": "https://basescan.org",
+        "usdc_address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
+    },
+    "arbitrum-mainnet": {
+        "chain_id": 42161,
+        "name": "Arbitrum One",
+        "rpc_url": "https://arbitrum-one-rpc.publicnode.com",
+        "explorer_url": "https://arbiscan.io",
+        "usdc_address": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831"
+    }
+}
+
+
+def get_network_config(network: str) -> NetworkConfig:
+    """Get configuration for a network."""
+    if network not in NETWORKS:
+        raise ValueError(f"Unsupported network: {network}")
+    return NETWORKS[network]
+
+
+def get_usdc_address(network: str) -> str:
+    """Get USDC address for a network."""
+    return get_network_config(network)["usdc_address"]
+
+
+def get_chain_id(network: str) -> int:
+    """Get chain ID for a network."""
+    return get_network_config(network)["chain_id"]
+
+
+# TODO: Load from database network table
+async def load_networks_from_db() -> Dict[str, NetworkConfig]:
+    """Load network configurations from database.
+    
+    This will query the Network table and build NETWORKS dict dynamically.
+    For now, returns static config.
+    """
+    # from db.dal.models import Network
+    # networks = await db.query(Network).filter(Network.active == True).all()
+    # return {net.shortname: {...} for net in networks}
+    return NETWORKS
+

traia_iatp/d402/path.py

@@ -0,0 +1,43 @@
+import fnmatch
+import re
+from typing import Union
+
+
+def path_is_match(path: Union[str, list[str]], request_path: str) -> bool:
+    """
+    Check if request path matches the specified path pattern(s).
+
+    Supports:
+    - Exact matching: "/api/users"
+    - Glob patterns: "/api/users/*", "/api/*/profile"
+    - Regex patterns (prefix with 'regex:'): "regex:^/api/users/\\d+$"
+    - List of any of the above
+
+    Args:
+        path: Path pattern(s) to match against. Can be a string or list of strings.
+        request_path: The actual request path to check.
+
+    Returns:
+        bool: True if the request path matches any of the patterns, False otherwise.
+    """
+
+    def single_path_match(pattern: str) -> bool:
+        # Regex pattern
+        if pattern.startswith("regex:"):
+            regex_pattern = pattern[6:]  # Remove 'regex:' prefix
+            return bool(re.match(regex_pattern, request_path))
+
+        # Glob pattern (contains * or ?)
+        elif "*" in pattern or "?" in pattern:
+            return fnmatch.fnmatch(request_path, pattern)
+
+        # Exact match
+        else:
+            return pattern == request_path
+
+    if isinstance(path, str):
+        return single_path_match(path)
+    elif isinstance(path, list):
+        return any(single_path_match(p) for p in path)
+
+    return False

traia_iatp/d402/payment_introspection.py

@@ -0,0 +1,104 @@
+"""
+Helper to extract payment configurations from @require_payment_for_tool decorators.
+
+This allows us to have a single source of truth - payment config is declared
+in the decorator, and we introspect it to build TOOL_PAYMENT_CONFIGS.
+"""
+
+import logging
+from typing import Dict, Any, Optional
+
+from .types import TokenAmount
+
+logger = logging.getLogger(__name__)
+
+
+def extract_payment_configs_from_mcp(mcp_server, server_address: str) -> Dict[str, Dict[str, Any]]:
+    """
+    Extract payment configurations from tools decorated with @require_payment_for_tool.
+    
+    This introspects the decorator closures to extract TokenAmount objects,
+    eliminating the need to duplicate payment configuration.
+    
+    Args:
+        mcp_server: FastMCP server instance
+        server_address: Server's payment address
+    
+    Returns:
+        Dict mapping tool names to payment configurations
+        Format: {"tool_name": {"price_wei": "1000", "token_address": "0x...", ...}}
+    
+    Usage:
+        mcp = FastMCP("Server")
+        
+        # Add tools with @require_payment_for_tool decorators
+        @mcp.tool()
+        @require_payment_for_tool(price=TokenAmount(...))
+        async def my_tool(context): ...
+        
+        # Extract configs dynamically
+        TOOL_PAYMENT_CONFIGS = extract_payment_configs_from_mcp(mcp, SERVER_ADDRESS)
+        
+        # Add middleware with extracted configs
+        app.add_middleware(D402PaymentMiddleware, tool_payment_configs=TOOL_PAYMENT_CONFIGS, ...)
+    """
+    tool_payment_configs = {}
+    
+    try:
+        # Get registered tools from FastMCP
+        tools = mcp_server._tool_manager.list_tools()
+        
+        for tool in tools:
+            if not hasattr(tool, 'fn'):
+                continue
+            
+            fn = tool.fn
+            tool_name = tool.name
+            
+            # Check if function has a closure (from decorators)
+            if not hasattr(fn, '__closure__') or not fn.__closure__:
+                logger.debug(f"Tool {tool_name}: No closure (no payment decorator)")
+                continue
+            
+            # Look for TokenAmount in closure
+            token_amount = None
+            for cell in fn.__closure__:
+                try:
+                    val = cell.cell_contents
+                    if isinstance(val, TokenAmount):
+                        token_amount = val
+                        break
+                except:
+                    pass
+            
+            if token_amount:
+                # Extract payment config from TokenAmount (including EIP712 domain)
+                config = {
+                    "price_wei": token_amount.amount,
+                    "token_address": token_amount.asset.address,
+                    "network": token_amount.asset.network,
+                    "server_address": server_address,
+                    "description": tool.description or tool_name,
+                    "eip712_domain": {
+                        "name": token_amount.asset.eip712.name if token_amount.asset.eip712 else "USD Coin",
+                        "version": token_amount.asset.eip712.version if token_amount.asset.eip712 else "2"
+                    }
+                }
+                
+                tool_payment_configs[tool_name] = config
+                logger.info(f"✅ Extracted payment config for {tool_name}: {config['price_wei']} wei on {config['network']}")
+            else:
+                logger.debug(f"Tool {tool_name}: No TokenAmount found (free tool)")
+        
+        logger.info(f"📊 Extracted {len(tool_payment_configs)} payment configs from decorators")
+        
+    except Exception as e:
+        logger.error(f"Error extracting payment configs: {e}")
+        import traceback
+        logger.error(traceback.format_exc())
+    
+    return tool_payment_configs
+
+
+__all__ = ["extract_payment_configs_from_mcp"]
+