t402 1.6.1__py3-none-any.whl → 1.7.1__py3-none-any.whl

t402/schemes/__init__.py

@@ -0,0 +1,125 @@
+"""T402 Payment Scheme Architecture.
+
+This package provides the interfaces and registry for managing payment schemes
+in the T402 protocol.
+
+Modules:
+    interfaces: Abstract interfaces for scheme implementations
+    registry: Scheme registration and lookup functionality
+
+Usage:
+    ```python
+    from t402.schemes import (
+        # Interfaces (for implementing new schemes)
+        SchemeNetworkClient,
+        SchemeNetworkServer,
+        SchemeNetworkFacilitator,
+
+        # Registry classes
+        SchemeRegistry,
+        ClientSchemeRegistry,
+        ServerSchemeRegistry,
+        FacilitatorSchemeRegistry,
+
+        # Global registry access
+        get_client_registry,
+        get_server_registry,
+        get_facilitator_registry,
+    )
+
+    # Register a scheme
+    registry = get_client_registry()
+    registry.register("eip155:8453", my_evm_client)
+
+    # Or create your own registry
+    my_registry = ClientSchemeRegistry()
+    my_registry.register("eip155:*", my_evm_client)  # Wildcard for all EVM
+    ```
+"""
+
+from t402.schemes.interfaces import (
+    # Type aliases
+    Price,
+    AssetAmount,
+    SupportedKindDict,
+    # Protocols (duck typing)
+    SchemeNetworkClient,
+    SchemeNetworkServer,
+    SchemeNetworkFacilitator,
+    # Abstract Base Classes (inheritance)
+    BaseSchemeNetworkClient,
+    BaseSchemeNetworkServer,
+    BaseSchemeNetworkFacilitator,
+)
+
+from t402.schemes.registry import (
+    # Core registry
+    SchemeRegistry,
+    # Typed registries
+    ClientSchemeRegistry,
+    ServerSchemeRegistry,
+    FacilitatorSchemeRegistry,
+    # Global registry accessors
+    get_client_registry,
+    get_server_registry,
+    get_facilitator_registry,
+    reset_global_registries,
+)
+
+# EVM Schemes
+from t402.schemes.evm import (
+    ExactEvmClientScheme,
+    ExactEvmServerScheme,
+    EvmSigner,
+)
+
+# TON Schemes
+from t402.schemes.ton import (
+    ExactTonClientScheme,
+    ExactTonServerScheme,
+    TonSigner,
+)
+
+# TRON Schemes
+from t402.schemes.tron import (
+    ExactTronClientScheme,
+    ExactTronServerScheme,
+    TronSigner,
+)
+
+__all__ = [
+    # Type aliases
+    "Price",
+    "AssetAmount",
+    "SupportedKindDict",
+    # Protocols
+    "SchemeNetworkClient",
+    "SchemeNetworkServer",
+    "SchemeNetworkFacilitator",
+    # ABCs
+    "BaseSchemeNetworkClient",
+    "BaseSchemeNetworkServer",
+    "BaseSchemeNetworkFacilitator",
+    # Registry classes
+    "SchemeRegistry",
+    "ClientSchemeRegistry",
+    "ServerSchemeRegistry",
+    "FacilitatorSchemeRegistry",
+    # Global registry functions
+    "get_client_registry",
+    "get_server_registry",
+    "get_facilitator_registry",
+    "reset_global_registries",
+    # EVM Schemes
+    "ExactEvmClientScheme",
+    "ExactEvmServerScheme",
+    "EvmSigner",
+    # TON Schemes
+    "ExactTonClientScheme",
+    "ExactTonServerScheme",
+    "TonSigner",
+    # TRON Schemes
+    "ExactTronClientScheme",
+    "ExactTronServerScheme",
+    "TronSigner",
+]

t402/schemes/evm/__init__.py

@@ -0,0 +1,25 @@
+"""EVM Blockchain Payment Schemes.
+
+This package provides payment scheme implementations for EVM-compatible
+blockchains (Ethereum, Base, Avalanche, etc.).
+
+Supported schemes:
+- exact: EIP-3009 TransferWithAuthorization
+"""
+
+from t402.schemes.evm.exact import (
+    ExactEvmClientScheme,
+    ExactEvmServerScheme,
+    EvmSigner,
+    create_nonce,
+    SCHEME_EXACT,
+)
+
+__all__ = [
+    # Exact scheme
+    "ExactEvmClientScheme",
+    "ExactEvmServerScheme",
+    "EvmSigner",
+    "create_nonce",
+    "SCHEME_EXACT",
+]

t402/schemes/evm/exact/__init__.py

@@ -0,0 +1,29 @@
+"""EVM Exact Payment Scheme.
+
+This package provides the exact payment scheme implementation for EVM networks
+using EIP-3009 TransferWithAuthorization.
+
+The exact scheme allows users to authorize token transfers that can be executed
+by a facilitator, enabling gasless payments.
+"""
+
+from t402.schemes.evm.exact.client import (
+    ExactEvmClientScheme,
+    EvmSigner,
+    create_nonce,
+    SCHEME_EXACT,
+)
+from t402.schemes.evm.exact.server import (
+    ExactEvmServerScheme,
+)
+
+__all__ = [
+    # Client
+    "ExactEvmClientScheme",
+    "EvmSigner",
+    "create_nonce",
+    # Server
+    "ExactEvmServerScheme",
+    # Constants
+    "SCHEME_EXACT",
+]

t402/schemes/evm/exact/client.py

@@ -0,0 +1,265 @@
+"""EVM Exact Scheme - Client Implementation.
+
+This module provides the client-side implementation of the exact payment scheme
+for EVM networks using EIP-3009 TransferWithAuthorization.
+"""
+
+from __future__ import annotations
+
+import secrets
+import time
+from typing import Any, Dict, Protocol, Union, runtime_checkable
+
+from t402.types import (
+    PaymentRequirementsV2,
+    T402_VERSION_V1,
+)
+from t402.chains import get_chain_id
+
+
+# Constants
+SCHEME_EXACT = "exact"
+
+
+@runtime_checkable
+class EvmSigner(Protocol):
+    """Protocol for EVM signing operations."""
+
+    @property
+    def address(self) -> str:
+        """Get the signer's address."""
+        ...
+
+    def sign_typed_data(
+        self,
+        domain_data: Dict[str, Any],
+        message_types: Dict[str, Any],
+        message_data: Dict[str, Any],
+    ) -> Any:
+        """Sign EIP-712 typed data."""
+        ...
+
+
+def create_nonce() -> bytes:
+    """Create a random 32-byte nonce for authorization signatures."""
+    return secrets.token_bytes(32)
+
+
+class ExactEvmClientScheme:
+    """Client scheme for EVM exact payments using EIP-3009.
+
+    This scheme creates payment payloads using EIP-3009 TransferWithAuthorization,
+    which allows gasless token transfers with signature authorization.
+
+    Example:
+        ```python
+        from eth_account import Account
+
+        # Create signer from private key
+        account = Account.from_key("0x...")
+
+        # Create scheme
+        scheme = ExactEvmClientScheme(account)
+
+        # Create payment payload
+        payload = await scheme.create_payment_payload(
+            t402_version=2,
+            requirements=requirements,
+        )
+        ```
+    """
+
+    scheme = SCHEME_EXACT
+    caip_family = "eip155:*"
+
+    def __init__(self, signer: EvmSigner):
+        """Initialize with an EVM signer.
+
+        Args:
+            signer: Any object implementing the EvmSigner protocol
+                   (e.g., eth_account.Account)
+        """
+        self._signer = signer
+
+    @property
+    def address(self) -> str:
+        """Get the signer's address."""
+        return self._signer.address
+
+    async def create_payment_payload(
+        self,
+        t402_version: int,
+        requirements: Union[PaymentRequirementsV2, Dict[str, Any]],
+    ) -> Dict[str, Any]:
+        """Create a payment payload for EVM exact scheme.
+
+        Creates an EIP-3009 TransferWithAuthorization and signs it.
+
+        Args:
+            t402_version: Protocol version (1 or 2)
+            requirements: Payment requirements with amount, asset, payTo, etc.
+
+        Returns:
+            Dict with t402Version, scheme, network, and payload containing
+            signature and authorization data.
+        """
+        # Extract requirements (handle both model and dict)
+        if hasattr(requirements, "model_dump"):
+            req = requirements.model_dump(by_alias=True)
+        else:
+            req = dict(requirements)
+
+        # Get network and chain ID
+        network = req.get("network", "")
+        chain_id = self._get_chain_id(network)
+
+        # Get amount - V2 uses 'amount', V1 uses 'maxAmountRequired'
+        amount = req.get("amount") or req.get("maxAmountRequired", "0")
+
+        # Get pay_to address
+        pay_to = req.get("payTo") or req.get("pay_to", "")
+
+        # Get asset address
+        asset = req.get("asset", "")
+
+        # Get timeout
+        max_timeout = req.get("maxTimeoutSeconds") or req.get("max_timeout_seconds", 300)
+
+        # Get EIP-712 domain info from extra
+        extra = req.get("extra", {})
+        token_name = extra.get("name", "USD Coin")
+        token_version = extra.get("version", "2")
+
+        # Create authorization
+        nonce = create_nonce()
+        now = int(time.time())
+        valid_after = str(now - 60)  # 60 seconds buffer
+        valid_before = str(now + max_timeout)
+
+        authorization = {
+            "from": self._signer.address,
+            "to": pay_to,
+            "value": str(amount),
+            "validAfter": valid_after,
+            "validBefore": valid_before,
+            "nonce": nonce,
+        }
+
+        # Sign the authorization
+        signature = self._sign_authorization(
+            authorization=authorization,
+            chain_id=chain_id,
+            asset_address=asset,
+            token_name=token_name,
+            token_version=token_version,
+        )
+
+        # Convert nonce to hex string
+        authorization["nonce"] = f"0x{nonce.hex()}"
+
+        # Build payload based on version
+        if t402_version == T402_VERSION_V1:
+            return {
+                "t402Version": t402_version,
+                "scheme": self.scheme,
+                "network": network,
+                "payload": {
+                    "signature": signature,
+                    "authorization": authorization,
+                },
+            }
+        else:
+            # V2 - return just the partial payload
+            return {
+                "t402Version": t402_version,
+                "payload": {
+                    "signature": signature,
+                    "authorization": authorization,
+                },
+            }
+
+    def _get_chain_id(self, network: str) -> int:
+        """Get chain ID from network identifier.
+
+        Args:
+            network: Network identifier (CAIP-2 or legacy format)
+
+        Returns:
+            Chain ID as integer
+        """
+        # Handle CAIP-2 format (eip155:8453)
+        if network.startswith("eip155:"):
+            return int(network.split(":")[1])
+
+        # Handle legacy format
+        try:
+            return get_chain_id(network)
+        except (KeyError, ValueError):
+            raise ValueError(f"Unknown network: {network}")
+
+    def _sign_authorization(
+        self,
+        authorization: Dict[str, Any],
+        chain_id: int,
+        asset_address: str,
+        token_name: str,
+        token_version: str,
+    ) -> str:
+        """Sign an EIP-3009 authorization.
+
+        Args:
+            authorization: Authorization data
+            chain_id: EVM chain ID
+            asset_address: Token contract address
+            token_name: Token name for EIP-712 domain
+            token_version: Token version for EIP-712 domain
+
+        Returns:
+            Signature as hex string
+        """
+        # Get nonce as bytes
+        nonce = authorization["nonce"]
+        if isinstance(nonce, str):
+            nonce = bytes.fromhex(nonce.replace("0x", ""))
+
+        # Build EIP-712 typed data
+        domain = {
+            "name": token_name,
+            "version": token_version,
+            "chainId": chain_id,
+            "verifyingContract": asset_address,
+        }
+
+        types = {
+            "TransferWithAuthorization": [
+                {"name": "from", "type": "address"},
+                {"name": "to", "type": "address"},
+                {"name": "value", "type": "uint256"},
+                {"name": "validAfter", "type": "uint256"},
+                {"name": "validBefore", "type": "uint256"},
+                {"name": "nonce", "type": "bytes32"},
+            ]
+        }
+
+        message = {
+            "from": authorization["from"],
+            "to": authorization["to"],
+            "value": int(authorization["value"]),
+            "validAfter": int(authorization["validAfter"]),
+            "validBefore": int(authorization["validBefore"]),
+            "nonce": nonce,
+        }
+
+        # Sign
+        signed = self._signer.sign_typed_data(
+            domain_data=domain,
+            message_types=types,
+            message_data=message,
+        )
+
+        # Extract signature
+        signature = signed.signature.hex()
+        if not signature.startswith("0x"):
+            signature = f"0x{signature}"
+
+        return signature

t402/schemes/evm/exact/server.py

@@ -0,0 +1,181 @@
+"""EVM Exact Scheme - Server Implementation.
+
+This module provides the server-side implementation of the exact payment scheme
+for EVM networks.
+"""
+
+from __future__ import annotations
+
+from decimal import Decimal
+from typing import Any, Dict, List, Union
+
+from t402.types import (
+    PaymentRequirementsV2,
+    Network,
+)
+from t402.schemes.interfaces import AssetAmount, SupportedKindDict
+from t402.chains import (
+    get_chain_id,
+    get_token_decimals,
+    get_token_name,
+    get_token_version,
+    get_default_token_address,
+)
+
+
+# Constants
+SCHEME_EXACT = "exact"
+
+
+class ExactEvmServerScheme:
+    """Server scheme for EVM exact payments.
+
+    Handles parsing user-friendly prices and enhancing payment requirements
+    with EIP-712 domain information needed for clients.
+
+    Example:
+        ```python
+        scheme = ExactEvmServerScheme()
+
+        # Parse price
+        asset_amount = await scheme.parse_price("$0.10", "eip155:8453")
+        # Returns: {"amount": "100000", "asset": "0x833589...", "extra": {...}}
+
+        # Enhance requirements
+        enhanced = await scheme.enhance_requirements(
+            requirements,
+            supported_kind,
+            facilitator_extensions,
+        )
+        ```
+    """
+
+    scheme = SCHEME_EXACT
+    caip_family = "eip155:*"
+
+    async def parse_price(
+        self,
+        price: Union[str, int, float, Dict[str, Any]],
+        network: Network,
+    ) -> AssetAmount:
+        """Parse a user-friendly price to atomic amount and asset.
+
+        Supports:
+        - String with $ prefix: "$0.10" -> 100000 (6 decimals)
+        - String without prefix: "0.10" -> 100000
+        - Integer/float: 0.10 -> 100000
+        - Dict (TokenAmount): {"amount": "100000", "asset": "0x..."}
+
+        Args:
+            price: User-friendly price
+            network: Network identifier (CAIP-2 format)
+
+        Returns:
+            AssetAmount dict with amount, asset, and extra metadata
+        """
+        chain_id = self._get_chain_id(network)
+
+        # Handle dict (already in TokenAmount format)
+        if isinstance(price, dict):
+            return {
+                "amount": str(price.get("amount", "0")),
+                "asset": price.get("asset", ""),
+                "extra": price.get("extra", {}),
+            }
+
+        # Get default token (USDC) for the network
+        chain_id_str = str(chain_id)
+        asset_address = get_default_token_address(chain_id_str, "usdc")
+        decimals = get_token_decimals(chain_id_str, asset_address)
+
+        # Parse price string/number
+        if isinstance(price, str):
+            if price.startswith("$"):
+                price = price[1:]
+            amount_decimal = Decimal(price)
+        else:
+            amount_decimal = Decimal(str(price))
+
+        # Convert to atomic units
+        atomic_amount = int(amount_decimal * Decimal(10 ** decimals))
+
+        # Get EIP-712 domain info
+        extra = {
+            "name": get_token_name(chain_id_str, asset_address),
+            "version": get_token_version(chain_id_str, asset_address),
+            "decimals": decimals,
+        }
+
+        return {
+            "amount": str(atomic_amount),
+            "asset": asset_address,
+            "extra": extra,
+        }
+
+    async def enhance_requirements(
+        self,
+        requirements: Union[PaymentRequirementsV2, Dict[str, Any]],
+        supported_kind: SupportedKindDict,
+        facilitator_extensions: List[str],
+    ) -> Union[PaymentRequirementsV2, Dict[str, Any]]:
+        """Enhance payment requirements with EVM-specific metadata.
+
+        Adds EIP-712 domain information to the extra field so clients
+        can properly sign the authorization.
+
+        Args:
+            requirements: Base payment requirements
+            supported_kind: Matched SupportedKind from facilitator
+            facilitator_extensions: Extensions supported by facilitator
+
+        Returns:
+            Enhanced requirements with EIP-712 domain in extra
+        """
+        # Convert to dict for modification
+        if hasattr(requirements, "model_dump"):
+            req = requirements.model_dump(by_alias=True)
+        else:
+            req = dict(requirements)
+
+        network = req.get("network", "")
+        asset = req.get("asset", "")
+
+        # Get chain ID as string
+        chain_id = str(self._get_chain_id(network))
+
+        # Ensure extra exists
+        if "extra" not in req or req["extra"] is None:
+            req["extra"] = {}
+
+        # Add EIP-712 domain info if not present
+        if "name" not in req["extra"]:
+            req["extra"]["name"] = get_token_name(chain_id, asset)
+        if "version" not in req["extra"]:
+            req["extra"]["version"] = get_token_version(chain_id, asset)
+
+        # Add facilitator extra data if available
+        if supported_kind.get("extra"):
+            for key, value in supported_kind["extra"].items():
+                if key not in req["extra"]:
+                    req["extra"][key] = value
+
+        return req
+
+    def _get_chain_id(self, network: str) -> int:
+        """Get chain ID from network identifier.
+
+        Args:
+            network: Network identifier (CAIP-2 or legacy format)
+
+        Returns:
+            Chain ID as integer
+        """
+        # Handle CAIP-2 format (eip155:8453)
+        if network.startswith("eip155:"):
+            return int(network.split(":")[1])
+
+        # Handle legacy format
+        try:
+            return get_chain_id(network)
+        except (KeyError, ValueError):
+            raise ValueError(f"Unknown network: {network}")