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

t402/schemes/evm/upto/server.py

@@ -0,0 +1,243 @@
+"""EVM Up-To Scheme - Server Implementation.
+
+This module provides the server-side implementation of the upto payment scheme
+for EVM networks using EIP-2612 Permit.
+
+The server parses user-friendly prices into atomic token amounts and enhances
+payment requirements with EIP-712 domain information needed by clients to
+sign Permit authorizations.
+"""
+
+from __future__ import annotations
+
+from decimal import Decimal
+from typing import Any, Dict, List, Optional, 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_UPTO = "upto"
+
+
+class UptoEvmServerScheme:
+    """Server scheme for EVM upto payments using EIP-2612 Permit.
+
+    Handles parsing user-friendly prices and enhancing payment requirements
+    with EIP-712 Permit domain information needed for clients to sign
+    gasless token approvals.
+
+    The upto scheme allows clients to authorize a maximum amount (maxAmount)
+    that the facilitator can settle up to, enabling usage-based billing.
+
+    Example:
+        ```python
+        scheme = UptoEvmServerScheme()
+
+        # Parse price to get asset amount info
+        asset_amount = await scheme.parse_price("$1.00", "eip155:8453")
+        # Returns: {"amount": "1000000", "asset": "0x833589...", "extra": {...}}
+
+        # Enhance requirements with EIP-712 domain info
+        enhanced = await scheme.enhance_requirements(
+            requirements,
+            supported_kind,
+            facilitator_extensions,
+        )
+        ```
+    """
+
+    scheme = SCHEME_UPTO
+    caip_family = "eip155:*"
+
+    def __init__(
+        self,
+        router_address: Optional[str] = None,
+    ):
+        """Initialize the server scheme.
+
+        Args:
+            router_address: Optional default router/spender contract address.
+                If provided, it will be included in enhanced requirements.
+        """
+        self._router_address = router_address
+
+    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.
+
+        For the upto scheme, this returns the maxAmount the client should
+        authorize. The actual settled amount may be less.
+
+        Supports:
+        - String with $ prefix: "$1.00" -> 1000000 (6 decimals)
+        - String without prefix: "1.00" -> 1000000
+        - Integer/float: 1.00 -> 1000000
+        - Dict (TokenAmount): {"amount": "1000000", "asset": "0x..."}
+
+        Args:
+            price: User-friendly price (represents the max amount)
+            network: Network identifier (CAIP-2 format, e.g., "eip155:8453")
+
+        Returns:
+            AssetAmount dict with amount, asset, and extra metadata
+            containing EIP-712 domain info.
+
+        Raises:
+            ValueError: If price format is invalid or network is unsupported
+        """
+        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 chain ID as string for token lookups
+        chain_id_str = str(chain_id)
+
+        # Get default token for the network
+        # Try USDT0 first, fall back to USDT, then USDC
+        try:
+            asset_address = get_default_token_address(chain_id_str, "usdt0")
+        except (ValueError, KeyError):
+            try:
+                asset_address = get_default_token_address(chain_id_str, "usdt")
+            except (ValueError, KeyError):
+                try:
+                    asset_address = get_default_token_address(chain_id_str, "usdc")
+                except (ValueError, KeyError):
+                    raise ValueError(
+                        f"Unknown network: no known token for chain {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 for Permit signing
+        extra: Dict[str, Any] = {
+            "name": get_token_name(chain_id_str, asset_address),
+            "version": get_token_version(chain_id_str, asset_address),
+            "decimals": decimals,
+        }
+
+        # Include router address if configured
+        if self._router_address:
+            extra["routerAddress"] = self._router_address
+
+        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 Permit-specific metadata.
+
+        Adds EIP-712 domain information (token name, version) and optionally
+        the router/spender address to the extra field so clients can properly
+        sign the EIP-2612 Permit authorization.
+
+        Args:
+            requirements: Base payment requirements (with maxAmount/amount set)
+            supported_kind: Matched SupportedKind from facilitator's /supported
+            facilitator_extensions: Extensions supported by facilitator
+
+        Returns:
+            Enhanced requirements with EIP-712 Permit domain info 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"]:
+            try:
+                req["extra"]["name"] = get_token_name(chain_id, asset)
+            except (ValueError, KeyError):
+                # If token not found in known tokens, use a sensible default
+                req["extra"]["name"] = "TetherToken"
+
+        if "version" not in req["extra"]:
+            try:
+                req["extra"]["version"] = get_token_version(chain_id, asset)
+            except (ValueError, KeyError):
+                req["extra"]["version"] = "1"
+
+        # Add router address if configured and not already present
+        if self._router_address and "routerAddress" not in req["extra"]:
+            req["extra"]["routerAddress"] = self._router_address
+
+        # 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
+
+        Raises:
+            ValueError: If the network format is unrecognized
+        """
+        # 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/types.py

@@ -0,0 +1,307 @@
+"""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", ""),
+    )

t402/schemes/interfaces.py

@@ -25,9 +25,13 @@ from t402.types import (
 
 
 # Type aliases for clarity
-Price = Union[str, int, float, Dict[str, Any]]  # e.g., "$0.10", 0.10, {"amount": "100000", "asset": "..."}
+Price = Union[
+    str, int, float, Dict[str, Any]
+]  # e.g., "$0.10", 0.10, {"amount": "100000", "asset": "..."}
 AssetAmount = Dict[str, Any]  # {"amount": str, "asset": str, "extra"?: dict}
-SupportedKindDict = Dict[str, Any]  # {"t402Version": int, "scheme": str, "network": str, "extra"?: dict}
+SupportedKindDict = Dict[
+    str, Any
+]  # {"t402Version": int, "scheme": str, "network": str, "extra"?: dict}
 
 
 @runtime_checkable

t402/schemes/near/__init__.py

@@ -0,0 +1,112 @@
+"""NEAR Blockchain Payment Schemes.
+
+This package provides payment scheme implementations for the NEAR blockchain.
+
+Supported schemes:
+- exact-direct: Client executes NEP-141 ft_transfer, tx hash used as proof.
+
+Usage:
+    ```python
+    from t402.schemes.near import (
+        # Client
+        ExactDirectNearClientScheme,
+        ExactDirectNearClientConfig,
+        # Server
+        ExactDirectNearServerScheme,
+        ExactDirectNearServerConfig,
+        # Facilitator
+        ExactDirectNearFacilitatorScheme,
+        ExactDirectNearFacilitatorConfig,
+        # Signer protocols
+        ClientNearSigner,
+        FacilitatorNearSigner,
+        # Constants
+        SCHEME_EXACT_DIRECT,
+        NEAR_MAINNET,
+        NEAR_TESTNET,
+    )
+    ```
+"""
+
+from t402.schemes.near.exact_direct import (
+    ExactDirectNearClientScheme,
+    ExactDirectNearServerScheme,
+    ExactDirectNearFacilitatorScheme,
+)
+from t402.schemes.near.exact_direct.client import ExactDirectNearClientConfig
+from t402.schemes.near.exact_direct.server import ExactDirectNearServerConfig
+from t402.schemes.near.exact_direct.facilitator import ExactDirectNearFacilitatorConfig
+from t402.schemes.near.types import (
+    ClientNearSigner,
+    FacilitatorNearSigner,
+    ExactDirectPayload,
+    FtTransferArgs,
+    is_valid_account_id,
+)
+from t402.schemes.near.constants import (
+    SCHEME_EXACT_DIRECT,
+    NEAR_MAINNET,
+    NEAR_TESTNET,
+    NEAR_MAINNET_RPC,
+    NEAR_TESTNET_RPC,
+    CAIP_FAMILY,
+    DEFAULT_GAS,
+    DEFAULT_GAS_INT,
+    STORAGE_DEPOSIT,
+    FUNCTION_FT_TRANSFER,
+    USDT_MAINNET,
+    USDT_TESTNET,
+    USDC_MAINNET,
+    USDC_TESTNET,
+    TokenInfo,
+    NetworkConfig,
+    get_network_config,
+    get_token_info,
+    get_token_by_contract,
+    is_valid_network,
+    get_supported_networks,
+)
+
+__all__ = [
+    # Scheme implementations
+    "ExactDirectNearClientScheme",
+    "ExactDirectNearServerScheme",
+    "ExactDirectNearFacilitatorScheme",
+    # Configurations
+    "ExactDirectNearClientConfig",
+    "ExactDirectNearServerConfig",
+    "ExactDirectNearFacilitatorConfig",
+    # Signer protocols
+    "ClientNearSigner",
+    "FacilitatorNearSigner",
+    # Payload types
+    "ExactDirectPayload",
+    "FtTransferArgs",
+    # Validation
+    "is_valid_account_id",
+    "is_valid_network",
+    # Constants
+    "SCHEME_EXACT_DIRECT",
+    "NEAR_MAINNET",
+    "NEAR_TESTNET",
+    "NEAR_MAINNET_RPC",
+    "NEAR_TESTNET_RPC",
+    "CAIP_FAMILY",
+    "DEFAULT_GAS",
+    "DEFAULT_GAS_INT",
+    "STORAGE_DEPOSIT",
+    "FUNCTION_FT_TRANSFER",
+    # Token definitions
+    "USDT_MAINNET",
+    "USDT_TESTNET",
+    "USDC_MAINNET",
+    "USDC_TESTNET",
+    # Data classes
+    "TokenInfo",
+    "NetworkConfig",
+    # Lookup functions
+    "get_network_config",
+    "get_token_info",
+    "get_token_by_contract",
+    "get_supported_networks",
+]