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

t402/schemes/evm/upto/__init__.py

@@ -0,0 +1,58 @@
+"""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,
+)
+
+__all__ = [
+    # Constants
+    "SCHEME_UPTO",
+    "PERMIT_TYPES",
+    "PERMIT_DOMAIN_TYPES",
+    # Client
+    "UptoEvmClientScheme",
+    "create_payment_nonce",
+    # 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,240 @@
+"""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,
+        }

t402/schemes/evm/upto/types.py

@@ -0,0 +1,305 @@
+"""EVM Up-To Scheme Types.
+
+EVM-specific types for the up-to payment scheme using EIP-2612 Permit.
+The Permit standard allows gasless token approvals via signature.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+from pydantic import BaseModel, ConfigDict, Field
+from pydantic.alias_generators import to_camel
+
+
+# EIP-712 Permit type definitions
+PERMIT_TYPES: Dict[str, List[Dict[str, str]]] = {
+    "Permit": [
+        {"name": "owner", "type": "address"},
+        {"name": "spender", "type": "address"},
+        {"name": "value", "type": "uint256"},
+        {"name": "nonce", "type": "uint256"},
+        {"name": "deadline", "type": "uint256"},
+    ]
+}
+
+PERMIT_DOMAIN_TYPES: List[Dict[str, str]] = [
+    {"name": "name", "type": "string"},
+    {"name": "version", "type": "string"},
+    {"name": "chainId", "type": "uint256"},
+    {"name": "verifyingContract", "type": "address"},
+]
+
+
+class PermitSignature(BaseModel):
+    """EIP-2612 permit signature components."""
+
+    v: int = Field(description="Recovery id")
+    r: str = Field(description="First 32 bytes of signature")
+    s: str = Field(description="Second 32 bytes of signature")
+
+    model_config = ConfigDict(
+        alias_generator=to_camel,
+        populate_by_name=True,
+        from_attributes=True,
+    )
+
+
+class PermitAuthorization(BaseModel):
+    """EIP-2612 permit authorization parameters."""
+
+    owner: str = Field(description="Token owner address")
+    spender: str = Field(description="Address authorized to spend (router contract)")
+    value: str = Field(description="Maximum authorized value")
+    deadline: str = Field(description="Permit deadline (unix timestamp)")
+    nonce: int = Field(description="Permit nonce from token contract")
+
+    model_config = ConfigDict(
+        alias_generator=to_camel,
+        populate_by_name=True,
+        from_attributes=True,
+    )
+
+
+class UptoEIP2612Payload(BaseModel):
+    """Up-to payment payload using EIP-2612 Permit."""
+
+    signature: PermitSignature = Field(description="Permit signature components")
+    authorization: PermitAuthorization = Field(description="Permit parameters")
+    payment_nonce: str = Field(
+        alias="paymentNonce",
+        description="Unique nonce to prevent replay attacks",
+    )
+
+    model_config = ConfigDict(
+        alias_generator=to_camel,
+        populate_by_name=True,
+        from_attributes=True,
+    )
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        return {
+            "signature": {
+                "v": self.signature.v,
+                "r": self.signature.r,
+                "s": self.signature.s,
+            },
+            "authorization": {
+                "owner": self.authorization.owner,
+                "spender": self.authorization.spender,
+                "value": self.authorization.value,
+                "deadline": self.authorization.deadline,
+                "nonce": self.authorization.nonce,
+            },
+            "paymentNonce": self.payment_nonce,
+        }
+
+
+class UptoCompactPayload(BaseModel):
+    """Alternative payload with combined signature."""
+
+    signature: str = Field(description="Combined EIP-2612 permit signature (65 bytes hex)")
+    authorization: PermitAuthorization = Field(description="Permit parameters")
+    payment_nonce: str = Field(
+        alias="paymentNonce",
+        description="Unique nonce to prevent replay attacks",
+    )
+
+    model_config = ConfigDict(
+        alias_generator=to_camel,
+        populate_by_name=True,
+        from_attributes=True,
+    )
+
+
+class UptoEvmExtra(BaseModel):
+    """EVM-specific extra fields for the upto scheme."""
+
+    name: str = Field(description="EIP-712 domain name (token name)")
+    version: str = Field(description="EIP-712 domain version")
+    router_address: Optional[str] = Field(
+        default=None,
+        alias="routerAddress",
+        description="Upto router contract address",
+    )
+    unit: Optional[str] = Field(
+        default=None,
+        description="Billing unit (e.g., 'token', 'request')",
+    )
+    unit_price: Optional[str] = Field(
+        default=None,
+        alias="unitPrice",
+        description="Price per unit in smallest denomination",
+    )
+
+    model_config = ConfigDict(
+        alias_generator=to_camel,
+        populate_by_name=True,
+        from_attributes=True,
+    )
+
+
+class UptoEvmSettlement(BaseModel):
+    """EVM-specific settlement request."""
+
+    settle_amount: str = Field(
+        alias="settleAmount",
+        description="Actual amount to settle",
+    )
+    usage_details: Optional["UptoEvmUsageDetails"] = Field(
+        default=None,
+        alias="usageDetails",
+        description="Optional usage information",
+    )
+
+    model_config = ConfigDict(
+        alias_generator=to_camel,
+        populate_by_name=True,
+        from_attributes=True,
+    )
+
+
+class UptoEvmUsageDetails(BaseModel):
+    """Usage details for EVM settlement."""
+
+    units_consumed: Optional[int] = Field(
+        default=None,
+        alias="unitsConsumed",
+        description="Number of units consumed",
+    )
+    unit_price: Optional[str] = Field(
+        default=None,
+        alias="unitPrice",
+        description="Price per unit used",
+    )
+    unit_type: Optional[str] = Field(
+        default=None,
+        alias="unitType",
+        description="Type of unit",
+    )
+    start_time: Optional[int] = Field(
+        default=None,
+        alias="startTime",
+        description="Start timestamp",
+    )
+    end_time: Optional[int] = Field(
+        default=None,
+        alias="endTime",
+        description="End timestamp",
+    )
+
+    model_config = ConfigDict(
+        alias_generator=to_camel,
+        populate_by_name=True,
+        from_attributes=True,
+    )
+
+
+# Update forward reference
+UptoEvmSettlement.model_rebuild()
+
+
+def is_eip2612_payload(data: Dict[str, Any]) -> bool:
+    """Check if the given data represents an EIP-2612 permit payload.
+
+    Args:
+        data: Dictionary to check
+
+    Returns:
+        True if data has the correct EIP-2612 structure
+    """
+    if not isinstance(data, dict):
+        return False
+
+    sig = data.get("signature")
+    auth = data.get("authorization")
+
+    if not sig or not auth:
+        return False
+
+    # Check signature structure (should be object with v, r, s)
+    if not isinstance(sig, dict):
+        return False
+    if not all(k in sig for k in ["v", "r", "s"]):
+        return False
+
+    # Check authorization structure
+    if not isinstance(auth, dict):
+        return False
+    required_auth_fields = ["owner", "spender", "value", "deadline"]
+    if not all(k in auth for k in required_auth_fields):
+        return False
+
+    return True
+
+
+def create_permit_domain(
+    name: str,
+    version: str,
+    chain_id: int,
+    token_address: str,
+) -> Dict[str, Any]:
+    """Create an EIP-712 domain for permit signing.
+
+    Args:
+        name: Token name
+        version: Token version
+        chain_id: Chain ID
+        token_address: Token contract address
+
+    Returns:
+        EIP-712 domain dictionary
+    """
+    return {
+        "name": name,
+        "version": version,
+        "chainId": chain_id,
+        "verifyingContract": token_address,
+    }
+
+
+def create_permit_message(authorization: PermitAuthorization) -> Dict[str, Any]:
+    """Create an EIP-712 message for permit signing.
+
+    Args:
+        authorization: Permit authorization parameters
+
+    Returns:
+        EIP-712 message dictionary
+    """
+    return {
+        "owner": authorization.owner,
+        "spender": authorization.spender,
+        "value": int(authorization.value),
+        "nonce": authorization.nonce,
+        "deadline": int(authorization.deadline),
+    }
+
+
+def payload_from_dict(data: Dict[str, Any]) -> UptoEIP2612Payload:
+    """Create an UptoEIP2612Payload from a dictionary.
+
+    Args:
+        data: Dictionary containing payload data
+
+    Returns:
+        UptoEIP2612Payload instance
+    """
+    sig_data = data.get("signature", {})
+    auth_data = data.get("authorization", {})
+
+    return UptoEIP2612Payload(
+        signature=PermitSignature(
+            v=sig_data.get("v", 0),
+            r=sig_data.get("r", ""),
+            s=sig_data.get("s", ""),
+        ),
+        authorization=PermitAuthorization(
+            owner=auth_data.get("owner", ""),
+            spender=auth_data.get("spender", ""),
+            value=auth_data.get("value", ""),
+            deadline=auth_data.get("deadline", ""),
+            nonce=auth_data.get("nonce", 0),
+        ),
+        payment_nonce=data.get("paymentNonce", ""),
+    )