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

t402/schemes/evm/exact_legacy/server.py

@@ -0,0 +1,231 @@
+"""EVM Exact-Legacy Scheme - Server Implementation.
+
+This module provides the server-side implementation of the exact-legacy payment scheme
+for EVM networks using the approve + transferFrom pattern.
+
+.. deprecated:: 2.3.0
+    The exact-legacy scheme is deprecated in favor of using USDT0 with the "exact" scheme.
+    USDT0 supports EIP-3009 for gasless transfers and is available on 19+ chains via LayerZero.
+
+    **Migration Guide:**
+    - Replace: `SCHEME_EXACT_LEGACY` with `SCHEME_EXACT`
+    - Replace: legacy USDT tokens with USDT0 tokens
+    - See https://docs.t402.io/migration/exact-legacy for full migration guide
+
+    **Why Migrate:**
+    1. Gasless transfers: USDT0 supports EIP-3009, eliminating gas costs for users
+    2. Cross-chain: USDT0 is available on 19+ chains with LayerZero bridging
+    3. Better UX: No separate approve transaction required
+    4. Future support: exact-legacy will be removed in v3.0.0
+
+    **Supported Chains for Migration:**
+    - Ethereum (1) - USDT0: 0x6C96dE32CEa08842dcc4058c14d3aaAD7Fa41dee
+    - Arbitrum (42161) - USDT0: 0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9
+    - Base (8453) - Use USDC: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
+    - And 16+ more chains
+"""
+
+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,
+    KNOWN_TOKENS,
+)
+
+
+# Constants
+SCHEME_EXACT_LEGACY = "exact-legacy"
+
+# Legacy USDT token addresses by chain ID
+LEGACY_USDT_TOKENS = {
+    "56": "0x55d398326f99059fF775485246999027B3197955",  # BNB Chain
+    "43114": "0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7",  # Avalanche
+    "250": "0x049d68029688eabf473097a2fc38ef61633a3c7a",  # Fantom
+    "42220": "0x48065fbBE25f71C9282ddf5e1cD6D6A887483D5e",  # Celo
+    "8217": "0xcee8faf64bb97a73bb51e115aa89c17ffa8dd167",  # Kaia
+}
+
+
+def get_default_legacy_token(chain_id: str) -> str:
+    """Get the default legacy USDT token address for a chain.
+
+    Args:
+        chain_id: Chain ID as string
+
+    Returns:
+        Token address
+
+    Raises:
+        ValueError: If chain doesn't have legacy USDT
+    """
+    if chain_id in LEGACY_USDT_TOKENS:
+        return LEGACY_USDT_TOKENS[chain_id]
+
+    # Check KNOWN_TOKENS for usdt entry
+    if chain_id in KNOWN_TOKENS:
+        for token in KNOWN_TOKENS[chain_id]:
+            if token.get("human_name") == "usdt":
+                return token["address"]
+
+    raise ValueError(f"No legacy USDT token found for chain {chain_id}")
+
+
+class ExactLegacyEvmServerScheme:
+    """Server scheme for EVM exact-legacy payments.
+
+    Handles parsing user-friendly prices and enhancing payment requirements
+    with EIP-712 domain information needed for clients.
+
+    Example:
+        ```python
+        scheme = ExactLegacyEvmServerScheme()
+
+        # Parse price
+        asset_amount = await scheme.parse_price("$0.10", "eip155:56")
+        # Returns: {"amount": "100000000000000000", "asset": "0x55d398...", "extra": {...}}
+
+        # Enhance requirements
+        enhanced = await scheme.enhance_requirements(
+            requirements,
+            supported_kind,
+            facilitator_extensions,
+        )
+        ```
+    """
+
+    scheme = SCHEME_EXACT_LEGACY
+    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" -> 100000000000000000 (18 decimals for BSC)
+        - String without prefix: "0.10" -> 100000000000000000
+        - Integer/float: 0.10 -> 100000000000000000
+        - 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 legacy USDT token for the network
+        chain_id_str = str(chain_id)
+        asset_address = get_default_legacy_token(chain_id_str)
+        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": "T402LegacyTransfer",
+            "version": "1",
+            "decimals": decimals,
+            "tokenType": "legacy",
+        }
+
+        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 and spender address 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)
+
+        # 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"] = "T402LegacyTransfer"
+        if "version" not in req["extra"]:
+            req["extra"]["version"] = "1"
+
+        # Mark as legacy token type
+        req["extra"]["tokenType"] = "legacy"
+
+        # Add facilitator extra data if available (includes spender address)
+        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 int(get_chain_id(network))
+        except (KeyError, ValueError):
+            raise ValueError(f"Unknown network: {network}")

t402/schemes/evm/upto/__init__.py

@@ -0,0 +1,70 @@
+"""EVM Up-To Payment Scheme.
+
+This package provides the upto payment scheme implementation for EVM networks
+using EIP-2612 Permit for gasless token approvals.
+
+The upto scheme allows clients to authorize a maximum amount that can be
+settled later based on actual usage.
+"""
+
+from t402.schemes.evm.upto.types import (
+    # Type definitions
+    PERMIT_TYPES,
+    PERMIT_DOMAIN_TYPES,
+    # Models
+    PermitSignature,
+    PermitAuthorization,
+    UptoEIP2612Payload,
+    UptoCompactPayload,
+    UptoEvmExtra,
+    UptoEvmSettlement,
+    UptoEvmUsageDetails,
+    # Type guards
+    is_eip2612_payload,
+    # Helper functions
+    create_permit_domain,
+    create_permit_message,
+    payload_from_dict,
+)
+
+from t402.schemes.evm.upto.client import (
+    UptoEvmClientScheme,
+    create_payment_nonce,
+    SCHEME_UPTO,
+)
+
+from t402.schemes.evm.upto.server import (
+    UptoEvmServerScheme,
+)
+
+from t402.schemes.evm.upto.facilitator import (
+    UptoEvmFacilitatorScheme,
+)
+
+__all__ = [
+    # Constants
+    "SCHEME_UPTO",
+    "PERMIT_TYPES",
+    "PERMIT_DOMAIN_TYPES",
+    # Client
+    "UptoEvmClientScheme",
+    "create_payment_nonce",
+    # Server
+    "UptoEvmServerScheme",
+    # Facilitator
+    "UptoEvmFacilitatorScheme",
+    # Types
+    "PermitSignature",
+    "PermitAuthorization",
+    "UptoEIP2612Payload",
+    "UptoCompactPayload",
+    "UptoEvmExtra",
+    "UptoEvmSettlement",
+    "UptoEvmUsageDetails",
+    # Type guards
+    "is_eip2612_payload",
+    # Helper functions
+    "create_permit_domain",
+    "create_permit_message",
+    "payload_from_dict",
+]

t402/schemes/evm/upto/client.py

@@ -0,0 +1,244 @@
+"""EVM Up-To Scheme - Client Implementation.
+
+This module provides the client-side implementation of the upto payment scheme
+for EVM networks using EIP-2612 Permit.
+"""
+
+from __future__ import annotations
+
+import secrets
+import time
+from typing import Any, Dict, Optional, Union
+
+from t402.types import PaymentRequirementsV2
+from t402.chains import get_chain_id
+from t402.schemes.evm.exact.client import EvmSigner
+from t402.schemes.upto.types import UptoPaymentRequirements
+
+
+# Constants
+SCHEME_UPTO = "upto"
+
+
+def create_payment_nonce() -> bytes:
+    """Create a random 32-byte payment nonce."""
+    return secrets.token_bytes(32)
+
+
+class UptoEvmClientScheme:
+    """Client scheme for EVM upto payments using EIP-2612.
+
+    This scheme creates payment payloads using EIP-2612 Permit,
+    which allows gasless token approvals for up-to payments.
+
+    Example:
+        ```python
+        from eth_account import Account
+
+        # Create signer from private key
+        account = Account.from_key("0x...")
+
+        # Create scheme
+        scheme = UptoEvmClientScheme(account)
+
+        # Create payment payload
+        payload = await scheme.create_payment_payload(
+            t402_version=2,
+            requirements=requirements,
+        )
+        ```
+    """
+
+    scheme = SCHEME_UPTO
+    caip_family = "eip155:*"
+
+    def __init__(
+        self,
+        signer: EvmSigner,
+        router_address: Optional[str] = None,
+    ):
+        """Initialize with an EVM signer.
+
+        Args:
+            signer: Any object implementing the EvmSigner protocol
+            router_address: Optional default router contract address
+        """
+        self._signer = signer
+        self._router_address = router_address
+
+    @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[
+            UptoPaymentRequirements, PaymentRequirementsV2, Dict[str, Any]
+        ],
+    ) -> Dict[str, Any]:
+        """Create a payment payload for EVM upto scheme.
+
+        Creates an EIP-2612 Permit authorization and signs it.
+
+        Args:
+            t402_version: Protocol version (1 or 2)
+            requirements: Payment requirements with maxAmount, asset, payTo, etc.
+
+        Returns:
+            Dict with t402Version and payload containing permit 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 maxAmount for upto scheme
+        max_amount = req.get("maxAmount") or req.get("max_amount", "0")
+
+        # Get router/spender address
+        extra = req.get("extra", {})
+        router_address = (
+            extra.get("routerAddress")
+            or extra.get("router_address")
+            or self._router_address
+            or req.get("payTo")  # Fallback to payTo
+        )
+
+        # 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
+        token_name = extra.get("name", "USD Coin")
+        token_version = extra.get("version", "2")
+
+        # Create payment nonce
+        payment_nonce = create_payment_nonce()
+
+        # Calculate deadline
+        deadline = int(time.time()) + max_timeout
+
+        # Get permit nonce from token contract (would need RPC call in production)
+        # For now, use 0 as placeholder - real implementation needs contract call
+        permit_nonce = 0
+
+        # Create authorization
+        authorization = {
+            "owner": self._signer.address,
+            "spender": router_address,
+            "value": str(max_amount),
+            "deadline": str(deadline),
+            "nonce": permit_nonce,
+        }
+
+        # Sign the permit
+        signature = self._sign_permit(
+            authorization=authorization,
+            chain_id=chain_id,
+            asset_address=asset,
+            token_name=token_name,
+            token_version=token_version,
+        )
+
+        # Build payload
+        payload = {
+            "signature": signature,
+            "authorization": authorization,
+            "paymentNonce": f"0x{payment_nonce.hex()}",
+        }
+
+        return {
+            "t402Version": t402_version,
+            "payload": payload,
+        }
+
+    def _get_chain_id(self, network: str) -> int:
+        """Get chain ID from network identifier."""
+        if network.startswith("eip155:"):
+            return int(network.split(":")[1])
+
+        try:
+            return get_chain_id(network)
+        except (KeyError, ValueError):
+            raise ValueError(f"Unknown network: {network}")
+
+    def _sign_permit(
+        self,
+        authorization: Dict[str, Any],
+        chain_id: int,
+        asset_address: str,
+        token_name: str,
+        token_version: str,
+    ) -> Dict[str, Any]:
+        """Sign an EIP-2612 Permit.
+
+        Args:
+            authorization: Permit 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 dict with v, r, s components
+        """
+        # Build EIP-712 typed data
+        domain = {
+            "name": token_name,
+            "version": token_version,
+            "chainId": chain_id,
+            "verifyingContract": asset_address,
+        }
+
+        types = {
+            "Permit": [
+                {"name": "owner", "type": "address"},
+                {"name": "spender", "type": "address"},
+                {"name": "value", "type": "uint256"},
+                {"name": "nonce", "type": "uint256"},
+                {"name": "deadline", "type": "uint256"},
+            ]
+        }
+
+        message = {
+            "owner": authorization["owner"],
+            "spender": authorization["spender"],
+            "value": int(authorization["value"]),
+            "nonce": authorization["nonce"],
+            "deadline": int(authorization["deadline"]),
+        }
+
+        # Sign
+        signed = self._signer.sign_typed_data(
+            domain_data=domain,
+            message_types=types,
+            message_data=message,
+        )
+
+        # Extract signature components
+        sig_hex = signed.signature.hex()
+        if sig_hex.startswith("0x"):
+            sig_hex = sig_hex[2:]
+
+        # Split into v, r, s
+        r = f"0x{sig_hex[:64]}"
+        s = f"0x{sig_hex[64:128]}"
+        v = int(sig_hex[128:], 16) if len(sig_hex) > 128 else 27
+
+        return {
+            "v": v,
+            "r": r,
+            "s": s,
+        }