chipi-stack 2.0.0__py3-none-any.whl

chipi_sdk/x402_client.py

@@ -0,0 +1,207 @@
+"""x402 Payment Client for Starknet.
+
+Wraps HTTP requests with automatic 402 payment handling.
+When a server returns HTTP 402, the client parses the payment requirement,
+validates against configured limits, signs the payment, and retries.
+"""
+
+import asyncio
+import json
+import time
+import uuid
+from decimal import Decimal
+from typing import Any, Optional
+
+import httpx
+
+from .constants import CONTRACT_ADDRESSES, TOKEN_DECIMALS
+from .models.x402 import (
+    PaymentPayload,
+    PaymentPayloadData,
+    PaymentRequirement,
+    PaymentSignature,
+    X402ClientConfig,
+)
+
+
+class X402Client:
+    """x402 payment client for automatic HTTP 402 handling.
+
+    Args:
+        sdk: ChipiSDK instance for executing payments
+        config: Optional client configuration (max amount, allowed recipients, etc.)
+    """
+
+    def __init__(self, sdk: Any, config: Optional[X402ClientConfig] = None):
+        self.sdk = sdk
+        self.config = config or X402ClientConfig()
+
+    async def afetch(
+        self,
+        url: str,
+        bearer_token: Optional[str] = None,
+        wallet: Any = None,
+        encrypt_key: Optional[str] = None,
+        method: str = "GET",
+        **kwargs: Any,
+    ) -> httpx.Response:
+        """Async fetch with automatic x402 payment handling.
+
+        Args:
+            url: URL to fetch
+            bearer_token: Bearer token for Chipi API calls
+            wallet: Wallet data for SDK operations
+            encrypt_key: Encryption key for SDK operations
+            method: HTTP method (default: "GET"). Preserved on retry after payment.
+            **kwargs: Additional arguments passed to httpx (headers, params, etc.)
+
+        Returns:
+            httpx.Response from the server (after payment if needed)
+        """
+        async with httpx.AsyncClient() as client:
+            response = await client.request(method, url, **kwargs)
+
+            if response.status_code != 402:
+                return response
+
+            requirement = self._parse_requirement(response)
+            self._validate_requirement(requirement)
+            payment = self._build_payment(requirement)
+
+            # NOTE: Chipi SDK executes the transfer directly (client-side settlement)
+            # rather than producing a SNIP-12 signature for server-side settlement.
+            # Use verify-only mode on the server when using this client.
+            # TODO: Add local SNIP-12 signing when SDK exposes sign_typed_data().
+            amount_human = str(Decimal(requirement.max_amount_required) / Decimal(10 ** TOKEN_DECIMALS["USDC"]))
+            tx_hash = await self.sdk.atransfer(
+                params={
+                    "wallet": wallet,
+                    "encrypt_key": encrypt_key,
+                    "token": "USDC",
+                    "recipient": requirement.pay_to,
+                    "amount": amount_human,
+                },
+                bearer_token=bearer_token,
+            )
+
+            # Populate fromAddress from wallet
+            if wallet and isinstance(wallet, dict) and "publicKey" in wallet:
+                payment.payload.from_address = wallet["publicKey"]
+            elif wallet and hasattr(wallet, "publicKey"):
+                payment.payload.from_address = wallet.publicKey
+
+            if payment.payload.from_address == "0x0":
+                raise ValueError("Unable to resolve payer address (fromAddress) from wallet")
+
+            payment.payload.signature = PaymentSignature(r=tx_hash, s="direct")
+
+            # Retry with payment header
+            headers = dict(kwargs.get("headers", {}))
+            headers[self.config.header_name] = payment.model_dump_json(by_alias=True)
+
+            return await client.request(method, url, headers=headers, **{k: v for k, v in kwargs.items() if k != "headers"})
+
+    def fetch(
+        self,
+        url: str,
+        bearer_token: Optional[str] = None,
+        wallet: Any = None,
+        encrypt_key: Optional[str] = None,
+        method: str = "GET",
+        **kwargs: Any,
+    ) -> httpx.Response:
+        """Sync fetch with automatic x402 payment handling.
+
+        Note: Uses asyncio.run() internally. Cannot be called from within an
+        existing event loop (e.g. FastAPI background tasks). Use afetch() directly
+        in async contexts.
+
+        Args:
+            url: URL to fetch
+            bearer_token: Bearer token for Chipi API calls
+            wallet: Wallet data for SDK operations
+            encrypt_key: Encryption key for SDK operations
+            method: HTTP method (default: "GET"). Preserved on retry after payment.
+            **kwargs: Additional arguments passed to httpx
+
+        Returns:
+            httpx.Response from the server (after payment if needed)
+        """
+        return asyncio.run(self.afetch(url, bearer_token=bearer_token, wallet=wallet, encrypt_key=encrypt_key, method=method, **kwargs))
+
+    def _parse_requirement(self, response: httpx.Response) -> PaymentRequirement:
+        """Parse PAYMENT-REQUIRED header from 402 response."""
+        header_value = response.headers.get("payment-required")
+
+        if not header_value:
+            raise ValueError(
+                "Server returned 402 but no PAYMENT-REQUIRED header. "
+                "The server may not support x402 or is misconfigured."
+            )
+
+        try:
+            data = json.loads(header_value)
+        except json.JSONDecodeError:
+            raise ValueError("Malformed PAYMENT-REQUIRED header: invalid JSON")
+
+        return PaymentRequirement(**data)
+
+    def _validate_requirement(self, requirement: PaymentRequirement) -> None:
+        """Validate payment requirement against client configuration."""
+        # Validate protocol constraints
+        if requirement.scheme != "exact":
+            raise ValueError(f"Unsupported payment scheme: {requirement.scheme}")
+        if requirement.network != "starknet-mainnet":
+            raise ValueError(f"Unsupported network: {requirement.network}")
+
+        # Validate amount
+        if self.config.max_payment_amount:
+            max_base_units = int(Decimal(self.config.max_payment_amount) * Decimal(10 ** TOKEN_DECIMALS["USDC"]))
+            required_amount = int(requirement.max_amount_required)
+
+            if required_amount > max_base_units:
+                required_human = Decimal(required_amount) / Decimal(10 ** TOKEN_DECIMALS["USDC"])
+                raise ValueError(
+                    f"Payment amount {required_human} USDC exceeds maximum allowed "
+                    f"{self.config.max_payment_amount} USDC"
+                )
+
+        # Validate recipient whitelist (normalize addresses for Starknet leading-zero equivalence)
+        if self.config.allowed_recipients:
+            def normalize(a: str) -> str:
+                return a.lower().lstrip("0x").lstrip("0")
+
+            normalized = normalize(requirement.pay_to)
+            if not any(normalize(addr) == normalized for addr in self.config.allowed_recipients):
+                raise ValueError(
+                    f"Recipient {requirement.pay_to} is not in the allowed recipients list"
+                )
+
+        # Validate asset is USDC
+        normalized_asset = requirement.asset.lower().lstrip("0x").lstrip("0")
+        normalized_usdc = CONTRACT_ADDRESSES["USDC_MAINNET"].lower().lstrip("0x").lstrip("0")
+        if normalized_asset != normalized_usdc:
+            raise ValueError(
+                f"Unsupported asset: {requirement.asset}. "
+                f"Only USDC ({CONTRACT_ADDRESSES['USDC_MAINNET']}) is supported."
+            )
+
+    def _build_payment(self, requirement: PaymentRequirement) -> PaymentPayload:
+        """Build a PaymentPayload structure (signature filled in after execution)."""
+        nonce = str(uuid.uuid4())
+        valid_until = int(time.time()) + requirement.max_timeout_seconds
+
+        return PaymentPayload(
+            x402Version=1,
+            scheme="exact",
+            network="starknet-mainnet",
+            payload=PaymentPayloadData(
+                signature=PaymentSignature(r="0x0", s="0x0"),  # Placeholder
+                fromAddress="0x0",  # Filled in by SDK
+                toAddress=requirement.pay_to,
+                amount=requirement.max_amount_required,
+                asset=requirement.asset,
+                validUntil=valid_until,
+                nonce=nonce,
+            ),
+        )

chipi_sdk/x402_facilitator.py

@@ -0,0 +1,200 @@
+"""x402 Payment Facilitator for Starknet.
+
+Implements the "facilitator" role in the x402 protocol:
+- verify(): Validate payment signature, amount, asset, nonce replay
+- settle(): Execute the USDC transfer via Chipi's paymaster
+"""
+
+import asyncio
+import time
+from abc import ABC, abstractmethod
+from typing import Any, Optional
+
+from .constants import CONTRACT_ADDRESSES, TOKEN_DECIMALS
+from .models.x402 import PaymentPayload, SettleResponse, VerifyResponse
+
+
+class NonceStore(ABC):
+    """Pluggable nonce store for replay protection.
+
+    Developers can provide Redis, DB, or any persistent backend.
+    """
+
+    @abstractmethod
+    async def ahas(self, nonce: str) -> bool:
+        """Check if nonce has been used (non-consuming read)."""
+        ...
+
+    @abstractmethod
+    async def aconsume(self, nonce: str) -> bool:
+        """Atomically consume a nonce. Returns True if consumed (was new), False if already used.
+
+        Must be atomic to prevent concurrent replay attacks.
+        Maps to Redis SETNX, PostgreSQL INSERT ON CONFLICT DO NOTHING, etc.
+        """
+        ...
+
+    def has(self, nonce: str) -> bool:
+        """Sync check if nonce has been used."""
+        return asyncio.run(self.ahas(nonce))
+
+    def consume(self, nonce: str) -> bool:
+        """Sync atomically consume a nonce."""
+        return asyncio.run(self.aconsume(nonce))
+
+
+class InMemoryNonceStore(NonceStore):
+    """Default in-memory store. Resets on process restart."""
+
+    def __init__(self) -> None:
+        self._used: set[str] = set()
+        self._lock = asyncio.Lock()
+
+    async def ahas(self, nonce: str) -> bool:
+        async with self._lock:
+            return nonce in self._used
+
+    async def aconsume(self, nonce: str) -> bool:
+        async with self._lock:
+            if nonce in self._used:
+                return False
+            self._used.add(nonce)
+            return True
+
+
+class X402Facilitator:
+    """x402 Payment Facilitator for Starknet.
+
+    Implements verify + settle for the x402 protocol using Chipi's paymaster.
+
+    Args:
+        sdk: ChipiSDK instance
+        bearer_token: Bearer token for Chipi API calls
+        nonce_store: Optional custom nonce store (defaults to in-memory)
+    """
+
+    def __init__(
+        self,
+        sdk: Any,
+        bearer_token: Optional[str] = None,
+        nonce_store: Optional[NonceStore] = None,
+    ):
+        self.sdk = sdk
+        self.bearer_token = bearer_token
+        self.nonce_store = nonce_store or InMemoryNonceStore()
+
+    async def averify(self, payment: PaymentPayload) -> VerifyResponse:
+        """Async verify a payment signature (doesn't execute transfer).
+
+        Checks: version, network, nonce replay, expiry, asset, amount, addresses, signature.
+        """
+        payload = payment.payload
+
+        # Check x402 version
+        if payment.x402_version != 1:
+            return VerifyResponse(isValid=False, invalidReason=f"Unsupported x402 version: {payment.x402_version}")
+
+        # Check scheme
+        if payment.scheme != "exact":
+            return VerifyResponse(isValid=False, invalidReason=f"Unsupported payment scheme: {payment.scheme}")
+
+        # Check network
+        if payment.network != "starknet-mainnet":
+            return VerifyResponse(isValid=False, invalidReason=f"Unsupported network: {payment.network}")
+
+        # Check nonce replay
+        if await self.nonce_store.ahas(payload.nonce):
+            return VerifyResponse(isValid=False, invalidReason="Nonce already used (replay)")
+
+        # Check expiry
+        now = int(time.time())
+        if payload.valid_until <= now:
+            return VerifyResponse(isValid=False, invalidReason="Payment has expired (validUntil in the past)")
+
+        # Validate asset is USDC
+        normalized_asset = payload.asset.lower().lstrip("0x").lstrip("0")
+        normalized_usdc = CONTRACT_ADDRESSES["USDC_MAINNET"].lower().lstrip("0x").lstrip("0")
+        if normalized_asset != normalized_usdc:
+            return VerifyResponse(isValid=False, invalidReason=f"Unsupported asset: {payload.asset}. Only USDC is accepted.")
+
+        # Validate amount is positive
+        try:
+            amount = int(payload.amount)
+        except (ValueError, TypeError):
+            return VerifyResponse(isValid=False, invalidReason="Invalid payment amount format")
+        if amount <= 0:
+            return VerifyResponse(isValid=False, invalidReason="Payment amount must be positive")
+
+        # Validate addresses
+        if not payload.from_address or not payload.to_address:
+            return VerifyResponse(isValid=False, invalidReason="Missing fromAddress or toAddress")
+
+        # Validate signature presence
+        # NOTE: Full SNIP-12 cryptographic verification requires reconstructing
+        # the typed data hash and verifying against from_address on-chain.
+        # Currently checks presence only; the paymaster rejects invalid signatures
+        # at settlement time. TODO: Add on-chain signature verification.
+        if not payload.signature.r or not payload.signature.s:
+            return VerifyResponse(isValid=False, invalidReason="Missing signature")
+
+        return VerifyResponse(isValid=True)
+
+    def verify(self, payment: PaymentPayload) -> VerifyResponse:
+        """Sync verify. Uses asyncio.run(); use averify() in async contexts."""
+        return asyncio.run(self.averify(payment))
+
+    async def asettle(self, payment: PaymentPayload) -> SettleResponse:
+        """Async settle a verified payment via paymaster.
+
+        Marks nonce as consumed BEFORE executing to prevent concurrent replays.
+        """
+        payload = payment.payload
+
+        # Verify first
+        verification = await self.averify(payment)
+        if not verification.is_valid:
+            return SettleResponse(success=False, errorReason=verification.invalid_reason)
+
+        # Atomically consume nonce (prevents concurrent replays)
+        consumed = await self.nonce_store.aconsume(payload.nonce)
+        if not consumed:
+            return SettleResponse(success=False, errorReason="Nonce already consumed (concurrent replay)")
+
+        try:
+            # Execute transfer via SDK
+            from .models.transaction import Call
+
+            tx_hash = await self.sdk.aexecute_transaction(
+                params={
+                    "wallet": {"publicKey": payload.from_address},
+                    "calls": [
+                        Call(
+                            contractAddress=payload.asset,
+                            entrypoint="transfer",
+                            calldata=[payload.to_address, payload.amount, "0x0"],
+                        )
+                    ],
+                },
+                bearer_token=self.bearer_token,
+            )
+
+            if not isinstance(tx_hash, str) or not tx_hash.strip():
+                return SettleResponse(
+                    success=False,
+                    errorReason="Settlement failed: invalid transaction hash returned by SDK",
+                )
+
+            return SettleResponse(
+                success=True,
+                transactionHash=tx_hash,
+                networkId="starknet-mainnet",
+            )
+        except Exception as e:
+            return SettleResponse(
+                success=False,
+                errorReason=f"Settlement failed: {str(e)}",
+            )
+
+    def settle(self, payment: PaymentPayload) -> SettleResponse:
+        """Sync settle. Uses asyncio.run(); use asettle() in async contexts."""
+        return asyncio.run(self.asettle(payment))

chipi_sdk/x402_middleware.py

@@ -0,0 +1,280 @@
+"""x402 Payment Middleware for Python web frameworks.
+
+Provides middleware/decorators for FastAPI and Flask to monetize API endpoints
+using the x402 payment protocol on Starknet.
+"""
+
+import json
+import re
+from functools import wraps
+from typing import Any, Callable, Optional
+
+from .constants import CONTRACT_ADDRESSES, TOKEN_DECIMALS
+from .models.x402 import PaymentPayload, PaymentRequirement, X402PaymentConfig
+from .x402_facilitator import X402Facilitator
+
+_AMOUNT_RE = re.compile(r"^\d+(?:\.\d+)?$")
+
+
+def _amount_to_base_units(amount: str, decimals: int) -> str:
+    """Convert human-readable amount to base units using string arithmetic (no float)."""
+    normalized = amount.strip()
+    if not _AMOUNT_RE.fullmatch(normalized):
+        raise ValueError(f"Invalid amount format: {amount!r}")
+    parts = normalized.split(".")
+    whole = parts[0]
+    frac = parts[1] if len(parts) > 1 else ""
+    if len(frac) > decimals:
+        raise ValueError(f"Too many decimal places in {amount!r}; max {decimals}")
+    frac_padded = (frac + "0" * decimals)[:decimals]
+    result = str(int(whole + frac_padded))
+    if result == "0":
+        raise ValueError(f"Amount resolves to zero base units: {amount!r}")
+    return result
+
+
+def _build_payment_requirement(config: X402PaymentConfig, resource: str) -> dict:
+    """Build a payment requirement dict from config + request URL."""
+    amount_base_units = _amount_to_base_units(config.amount, TOKEN_DECIMALS["USDC"])
+
+    return {
+        "scheme": "exact",
+        "network": "starknet-mainnet",
+        "maxAmountRequired": amount_base_units,
+        "resource": resource,
+        "description": config.description,
+        "payTo": config.pay_to,
+        "maxTimeoutSeconds": 300,
+        "asset": CONTRACT_ADDRESSES["USDC_MAINNET"],
+    }
+
+
+def _normalize_addr(addr: str) -> str:
+    """Normalize a Starknet address for comparison."""
+    return addr.lower().lstrip("0x").lstrip("0")
+
+
+def _enforce_payment_policy(payment: PaymentPayload, config: X402PaymentConfig) -> Optional[str]:
+    """Validate payment matches endpoint config. Returns error reason or None."""
+    requirement = _build_payment_requirement(config, "")
+
+    # Check recipient
+    if _normalize_addr(payment.payload.to_address) != _normalize_addr(config.pay_to):
+        return f"Payment recipient mismatch: expected {config.pay_to}, got {payment.payload.to_address}"
+
+    # Check amount
+    try:
+        paid = int(payment.payload.amount)
+        required = int(requirement["maxAmountRequired"])
+        if paid < required:
+            return f"Payment amount insufficient: required {required}, got {paid}"
+    except (ValueError, TypeError):
+        return f"Invalid payment amount: {payment.payload.amount}"
+
+    # Check asset
+    if _normalize_addr(payment.payload.asset) != _normalize_addr(requirement["asset"]):
+        return f"Payment asset mismatch: expected USDC, got {payment.payload.asset}"
+
+    return None
+
+
+def fastapi_x402_dependency(
+    facilitator: X402Facilitator,
+    config: X402PaymentConfig,
+    verify_only: bool = False,
+) -> Callable:
+    """FastAPI dependency for x402 payment verification.
+
+    Usage:
+        facilitator = X402Facilitator(sdk, bearer_token)
+        payment_config = X402PaymentConfig(amount="0.01", pay_to="0xADDRESS")
+
+        @app.get("/premium")
+        async def premium(request: Request, x402=Depends(fastapi_x402_dependency(facilitator, payment_config))):
+            return {"data": "premium content", "tx_hash": x402.get("tx_hash")}
+    """
+
+    async def verify_payment(request: Any) -> dict:
+        from fastapi import HTTPException
+
+        if request.method == "OPTIONS":
+            return {}
+
+        payment_header = request.headers.get("x-payment") or request.headers.get("X-PAYMENT")
+        resource = str(request.url)
+
+        if not payment_header:
+            requirement = _build_payment_requirement(config, resource)
+            raise HTTPException(
+                status_code=402,
+                detail={
+                    "error": "Payment Required",
+                    "paymentRequirement": requirement,
+                },
+                headers={"Payment-Required": json.dumps(requirement)},
+            )
+
+        try:
+            payment_data = json.loads(payment_header)
+            payment = PaymentPayload(**payment_data)
+        except (json.JSONDecodeError, Exception) as e:
+            raise HTTPException(
+                status_code=400,
+                detail={"error": f"Malformed X-PAYMENT header: {str(e)}"},
+            )
+
+        # Enforce payment policy before verify/settle
+        policy_error = _enforce_payment_policy(payment, config)
+        if policy_error:
+            raise HTTPException(
+                status_code=402,
+                detail={"error": "Payment policy violation", "reason": policy_error},
+            )
+
+        try:
+            verified = await facilitator.averify(payment)
+            if not verified.is_valid:
+                raise HTTPException(
+                    status_code=402,
+                    detail={
+                        "error": "Payment verification failed",
+                        "reason": verified.invalid_reason,
+                    },
+                )
+
+            result: dict[str, Any] = {"payment": payment}
+
+            if not verify_only:
+                settled = await facilitator.asettle(payment)
+                if not settled.success:
+                    raise HTTPException(
+                        status_code=402,
+                        detail={
+                            "error": "Payment settlement failed",
+                            "reason": settled.error_reason,
+                        },
+                    )
+                result["tx_hash"] = settled.transaction_hash
+                result["network_id"] = settled.network_id
+        except HTTPException:
+            raise
+        except Exception:
+            raise HTTPException(
+                status_code=500,
+                detail={"error": "Internal payment processing error"},
+            )
+
+        return result
+
+    return verify_payment
+
+
+def flask_x402_required(
+    facilitator: X402Facilitator,
+    config: X402PaymentConfig,
+    verify_only: bool = False,
+) -> Callable:
+    """Flask decorator for x402 payment verification.
+
+    Usage:
+        facilitator = X402Facilitator(sdk, bearer_token)
+        payment_config = X402PaymentConfig(amount="0.01", pay_to="0xADDRESS")
+
+        @app.route("/premium")
+        @flask_x402_required(facilitator, payment_config)
+        def premium():
+            return jsonify({"data": "premium content"})
+    """
+
+    def decorator(f: Callable) -> Callable:
+        @wraps(f)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            from flask import request, jsonify, make_response
+
+            if request.method == "OPTIONS":
+                return make_response("", 204)
+
+            payment_header = request.headers.get("X-PAYMENT") or request.headers.get("x-payment")
+            resource = request.url
+
+            if not payment_header:
+                requirement = _build_payment_requirement(config, resource)
+                response = make_response(
+                    jsonify({"error": "Payment Required", "paymentRequirement": requirement}),
+                    402,
+                )
+                response.headers["Payment-Required"] = json.dumps(requirement)
+                return response
+
+            try:
+                payment_data = json.loads(payment_header)
+                payment = PaymentPayload(**payment_data)
+            except (json.JSONDecodeError, Exception) as e:
+                return jsonify({"error": f"Malformed X-PAYMENT header: {str(e)}"}), 400
+
+            # Enforce payment policy before verify/settle
+            policy_error = _enforce_payment_policy(payment, config)
+            if policy_error:
+                return jsonify({
+                    "error": "Payment policy violation",
+                    "reason": policy_error,
+                }), 402
+
+            try:
+                verified = facilitator.verify(payment)
+                if not verified.is_valid:
+                    return jsonify({
+                        "error": "Payment verification failed",
+                        "reason": verified.invalid_reason,
+                    }), 402
+
+                if not verify_only:
+                    settled = facilitator.settle(payment)
+                    if not settled.success:
+                        return jsonify({
+                            "error": "Payment settlement failed",
+                            "reason": settled.error_reason,
+                        }), 402
+
+                    request.x402 = {
+                        "tx_hash": settled.transaction_hash,
+                        "payment": payment,
+                        "network_id": settled.network_id,
+                    }
+                else:
+                    request.x402 = {"payment": payment}
+            except Exception:
+                return jsonify({
+                    "error": "Internal payment processing error",
+                }), 500
+
+            return f(*args, **kwargs)
+
+        return wrapper
+
+    return decorator
+
+
+def x402_middleware(
+    amount: str,
+    recipient: str,
+    facilitator: X402Facilitator,
+    *,
+    description: Optional[str] = None,
+    verify_only: bool = False,
+) -> Callable:
+    """Convenience wrapper that creates a FastAPI x402 dependency with flat params.
+
+    Usage::
+
+        facilitator = X402Facilitator(sdk, bearer_token)
+
+        @app.get("/premium")
+        async def premium(
+            request: Request,
+            x402=Depends(x402_middleware("0.01", "0xADDRESS", facilitator)),
+        ):
+            return {"data": "premium", "tx_hash": x402.get("tx_hash")}
+    """
+    config = X402PaymentConfig(amount=amount, pay_to=recipient, description=description)
+    return fastapi_x402_dependency(facilitator, config, verify_only=verify_only)