t402 1.9.0__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

@@ -98,7 +98,9 @@ class UptoEIP2612Payload(BaseModel):
 class UptoCompactPayload(BaseModel):
     """Alternative payload with combined signature."""
 
-    signature: str = Field(description="Combined EIP-2612 permit signature (65 bytes hex)")
+    signature: str = Field(
+        description="Combined EIP-2612 permit signature (65 bytes hex)"
+    )
     authorization: PermitAuthorization = Field(description="Permit parameters")
     payment_nonce: str = Field(
         alias="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",
+]

t402/schemes/near/constants.py

@@ -0,0 +1,189 @@
+"""NEAR blockchain constants for the T402 protocol.
+
+This module contains network configurations, token contract addresses,
+and other constants used by the NEAR exact-direct payment scheme.
+"""
+
+from __future__ import annotations
+
+from typing import Dict, Optional
+
+
+# Scheme identifier
+SCHEME_EXACT_DIRECT = "exact-direct"
+
+# CAIP-2 network identifiers
+NEAR_MAINNET = "near:mainnet"
+NEAR_TESTNET = "near:testnet"
+
+# RPC endpoints
+NEAR_MAINNET_RPC = "https://rpc.mainnet.near.org"
+NEAR_TESTNET_RPC = "https://rpc.testnet.near.org"
+
+# Default gas for ft_transfer (30 TGas)
+DEFAULT_GAS = "30000000000000"
+DEFAULT_GAS_INT = 30_000_000_000_000
+
+# Storage deposit required (1 yoctoNEAR) for ft_transfer
+STORAGE_DEPOSIT = "1"
+
+# NEP-141 function names
+FUNCTION_FT_TRANSFER = "ft_transfer"
+FUNCTION_FT_BALANCE_OF = "ft_balance_of"
+FUNCTION_STORAGE_BALANCE = "storage_balance_of"
+
+# CAIP family pattern
+CAIP_FAMILY = "near:*"
+
+
+class TokenInfo:
+    """Contains information about a NEAR fungible token.
+
+    Attributes:
+        contract_id: The NEAR account ID of the token contract.
+        symbol: The token symbol (e.g., "USDT").
+        decimals: The number of decimal places for the token.
+    """
+
+    def __init__(self, contract_id: str, symbol: str, decimals: int) -> None:
+        self.contract_id = contract_id
+        self.symbol = symbol
+        self.decimals = decimals
+
+    def __repr__(self) -> str:
+        return f"TokenInfo(contract_id={self.contract_id!r}, symbol={self.symbol!r}, decimals={self.decimals})"
+
+
+class NetworkConfig:
+    """Network-specific configuration for NEAR.
+
+    Attributes:
+        network_id: The short network identifier (e.g., "mainnet").
+        rpc_url: The RPC endpoint URL.
+        default_token: The default token for this network.
+    """
+
+    def __init__(self, network_id: str, rpc_url: str, default_token: TokenInfo) -> None:
+        self.network_id = network_id
+        self.rpc_url = rpc_url
+        self.default_token = default_token
+
+
+# Token definitions
+USDT_MAINNET = TokenInfo(
+    contract_id="usdt.tether-token.near",
+    symbol="USDT",
+    decimals=6,
+)
+
+USDT_TESTNET = TokenInfo(
+    contract_id="usdt.fakes.testnet",
+    symbol="USDT",
+    decimals=6,
+)
+
+USDC_MAINNET = TokenInfo(
+    contract_id="17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1",
+    symbol="USDC",
+    decimals=6,
+)
+
+USDC_TESTNET = TokenInfo(
+    contract_id="usdc.fakes.testnet",
+    symbol="USDC",
+    decimals=6,
+)
+
+# Network configurations
+NETWORK_CONFIGS: Dict[str, NetworkConfig] = {
+    NEAR_MAINNET: NetworkConfig(
+        network_id="mainnet",
+        rpc_url=NEAR_MAINNET_RPC,
+        default_token=USDT_MAINNET,
+    ),
+    NEAR_TESTNET: NetworkConfig(
+        network_id="testnet",
+        rpc_url=NEAR_TESTNET_RPC,
+        default_token=USDT_TESTNET,
+    ),
+}
+
+# Token registry: network -> symbol -> TokenInfo
+TOKEN_REGISTRY: Dict[str, Dict[str, TokenInfo]] = {
+    NEAR_MAINNET: {
+        "USDT": USDT_MAINNET,
+        "USDC": USDC_MAINNET,
+    },
+    NEAR_TESTNET: {
+        "USDT": USDT_TESTNET,
+        "USDC": USDC_TESTNET,
+    },
+}
+
+
+def get_network_config(network: str) -> Optional[NetworkConfig]:
+    """Get the configuration for a NEAR network.
+
+    Args:
+        network: The CAIP-2 network identifier (e.g., "near:mainnet").
+
+    Returns:
+        NetworkConfig if the network is supported, None otherwise.
+    """
+    return NETWORK_CONFIGS.get(network)
+
+
+def is_valid_network(network: str) -> bool:
+    """Check if a network identifier is a supported NEAR network.
+
+    Args:
+        network: The CAIP-2 network identifier.
+
+    Returns:
+        True if the network is supported.
+    """
+    return network in NETWORK_CONFIGS
+
+
+def get_token_info(network: str, symbol: str) -> Optional[TokenInfo]:
+    """Get token info for a network and symbol.
+
+    Args:
+        network: The CAIP-2 network identifier.
+        symbol: The token symbol (e.g., "USDT").
+
+    Returns:
+        TokenInfo if found, None otherwise.
+    """
+    tokens = TOKEN_REGISTRY.get(network)
+    if tokens is None:
+        return None
+    return tokens.get(symbol)
+
+
+def get_token_by_contract(network: str, contract_id: str) -> Optional[TokenInfo]:
+    """Get token info by contract address.
+
+    Args:
+        network: The CAIP-2 network identifier.
+        contract_id: The token contract account ID.
+
+    Returns:
+        TokenInfo if found, None otherwise.
+    """
+    tokens = TOKEN_REGISTRY.get(network)
+    if tokens is None:
+        return None
+    for token in tokens.values():
+        if token.contract_id == contract_id:
+            return token
+    return None
+
+
+def get_supported_networks() -> list:
+    """Get a list of supported NEAR network identifiers.
+
+    Returns:
+        List of CAIP-2 network identifier strings.
+    """
+    return [NEAR_MAINNET, NEAR_TESTNET]

t402/schemes/near/exact_direct/__init__.py

@@ -0,0 +1,21 @@
+"""NEAR Exact-Direct Payment Scheme.
+
+This package provides the exact-direct payment scheme implementation for NEAR.
+In this scheme, the client executes the NEP-141 ft_transfer on-chain directly,
+and the transaction hash is used as proof of payment.
+
+Components:
+    - ExactDirectNearClientScheme: Client-side (executes transfer, returns tx hash)
+    - ExactDirectNearServerScheme: Server-side (parses prices, enhances requirements)
+    - ExactDirectNearFacilitatorScheme: Facilitator-side (verifies tx, marks settled)
+"""
+
+from t402.schemes.near.exact_direct.client import ExactDirectNearClientScheme
+from t402.schemes.near.exact_direct.server import ExactDirectNearServerScheme
+from t402.schemes.near.exact_direct.facilitator import ExactDirectNearFacilitatorScheme
+
+__all__ = [
+    "ExactDirectNearClientScheme",
+    "ExactDirectNearServerScheme",
+    "ExactDirectNearFacilitatorScheme",
+]