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

t402/schemes/aptos/exact_direct/server.py

@@ -0,0 +1,272 @@
+"""Aptos Exact-Direct Scheme - Server Implementation.
+
+This module provides the server-side implementation of the exact-direct payment
+scheme for Aptos. It handles parsing user-friendly prices into atomic units
+and enhancing payment requirements with Aptos-specific metadata.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, List, Optional, Union
+
+from t402.types import (
+    PaymentRequirementsV2,
+    Network,
+)
+from t402.schemes.interfaces import AssetAmount, SupportedKindDict
+from t402.schemes.aptos.constants import (
+    SCHEME_EXACT_DIRECT,
+    CAIP_FAMILY,
+    DEFAULT_DECIMALS,
+    get_network_config,
+    get_token_by_address,
+    get_token_info,
+    parse_amount,
+    TokenInfo,
+)
+
+
+logger = logging.getLogger(__name__)
+
+
+class ExactDirectAptosServerScheme:
+    """Server scheme for Aptos exact-direct payments.
+
+    Handles parsing user-friendly prices (e.g., "$1.50") into atomic FA amounts
+    and enhancing payment requirements with Aptos-specific metadata such as
+    token symbol, name, and decimals.
+
+    Example:
+        ```python
+        scheme = ExactDirectAptosServerScheme()
+
+        # Parse a price
+        asset_amount = await scheme.parse_price("$0.10", "aptos:1")
+        # Returns: {"amount": "100000", "asset": "0xf73e...", "extra": {...}}
+
+        # Enhance requirements
+        enhanced = await scheme.enhance_requirements(
+            requirements,
+            supported_kind,
+            facilitator_extensions,
+        )
+        ```
+
+    Attributes:
+        scheme: The scheme identifier ("exact-direct").
+        caip_family: The CAIP-2 family pattern ("aptos:*").
+    """
+
+    scheme = SCHEME_EXACT_DIRECT
+    caip_family = CAIP_FAMILY
+
+    def __init__(self, preferred_token: Optional[str] = None) -> None:
+        """Initialize the Aptos exact-direct server scheme.
+
+        Args:
+            preferred_token: Preferred token symbol (e.g., "USDT").
+                Defaults to the network's default token if not specified.
+        """
+        self._preferred_token = preferred_token
+
+    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 multiple input formats:
+        - String with $ prefix: "$0.10" -> 100000 (6 decimals)
+        - String without prefix: "0.10" -> 100000
+        - Integer/float: 0.10 -> 100000
+        - Dict (pre-parsed TokenAmount): {"amount": "100000", "asset": "0x..."}
+
+        Args:
+            price: User-friendly price in any supported format.
+            network: CAIP-2 network identifier (e.g., "aptos:1").
+
+        Returns:
+            AssetAmount dict with:
+            - amount: Atomic amount as string
+            - asset: FA metadata address
+            - extra: Token metadata (symbol, name, decimals)
+
+        Raises:
+            ValueError: If price format is invalid or network is unsupported.
+        """
+        network_str = str(network)
+
+        # Validate network
+        config = get_network_config(network_str)
+        if not config:
+            raise ValueError(f"Unsupported Aptos network: {network}")
+
+        # Handle dict (already in TokenAmount format)
+        if isinstance(price, dict):
+            amount_val = price.get("amount", "0")
+            asset = price.get("asset", config.default_token.metadata_address)
+            extra = price.get("extra", {})
+
+            if not asset:
+                raise ValueError(
+                    f"Asset address must be specified for AssetAmount on network {network}"
+                )
+
+            return {
+                "amount": str(amount_val),
+                "asset": asset,
+                "extra": extra,
+            }
+
+        # Parse money to decimal number
+        decimal_amount = self._parse_money_to_decimal(price)
+
+        # Get the appropriate token
+        token = self._get_default_token(network_str, config)
+
+        # Convert decimal to atomic units
+        amount_str = f"{decimal_amount:.{token.decimals}f}"
+        atomic_amount = parse_amount(amount_str, token.decimals)
+
+        return {
+            "amount": str(atomic_amount),
+            "asset": token.metadata_address,
+            "extra": {
+                "symbol": token.symbol,
+                "name": token.name,
+                "decimals": token.decimals,
+            },
+        }
+
+    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 Aptos-specific metadata.
+
+        Adds FA token metadata (symbol, name, decimals) to the extra field
+        and converts decimal amounts to atomic units if needed.
+
+        Args:
+            requirements: Base payment requirements with amount/asset set.
+            supported_kind: The matched SupportedKind from the facilitator.
+            facilitator_extensions: Extensions supported by the facilitator.
+
+        Returns:
+            Enhanced requirements with Aptos metadata in the extra field.
+
+        Raises:
+            ValueError: If the network is unsupported or amount parsing fails.
+        """
+        # 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", "")
+
+        # Validate network
+        config = get_network_config(network)
+        if not config:
+            raise ValueError(f"Unsupported Aptos network: {network}")
+
+        # Determine token info
+        token_info: Optional[TokenInfo] = None
+        if asset:
+            # Try to find by address
+            token_info = get_token_by_address(network, asset)
+            if not token_info:
+                # Use generic token with default decimals
+                token_info = TokenInfo(
+                    metadata_address=asset,
+                    symbol="UNKNOWN",
+                    name="Unknown Token",
+                    decimals=DEFAULT_DECIMALS,
+                )
+        else:
+            # Use default token
+            token_info = self._get_default_token(network, config)
+            req["asset"] = token_info.metadata_address
+
+        # Convert decimal amount to atomic units if needed
+        amount = req.get("amount", "")
+        if amount and "." in amount:
+            atomic = parse_amount(amount, token_info.decimals)
+            req["amount"] = str(atomic)
+
+        # Initialize extra map if needed
+        if "extra" not in req or req["extra"] is None:
+            req["extra"] = {}
+
+        # Add asset metadata to extra
+        req["extra"]["symbol"] = token_info.symbol
+        req["extra"]["name"] = token_info.name
+        req["extra"]["decimals"] = token_info.decimals
+
+        # Copy facilitator-provided extra fields
+        kind_extra = supported_kind.get("extra") if isinstance(supported_kind, dict) else None
+        if kind_extra:
+            if "assetSymbol" in kind_extra:
+                req["extra"]["assetSymbol"] = kind_extra["assetSymbol"]
+            if "assetDecimals" in kind_extra:
+                req["extra"]["assetDecimals"] = kind_extra["assetDecimals"]
+
+            # Copy specific extension keys
+            for key in facilitator_extensions:
+                if key in kind_extra:
+                    req["extra"][key] = kind_extra[key]
+
+        return req
+
+    def _get_default_token(self, network: str, config: Any) -> TokenInfo:
+        """Get the default token for a network, considering preferred token config.
+
+        Args:
+            network: CAIP-2 network identifier.
+            config: NetworkConfig for the network.
+
+        Returns:
+            TokenInfo for the default or preferred token.
+        """
+        if self._preferred_token:
+            token = get_token_info(network, self._preferred_token)
+            if token:
+                return token
+        return config.default_token
+
+    def _parse_money_to_decimal(self, price: Union[str, int, float]) -> float:
+        """Convert a price value to a decimal amount.
+
+        Args:
+            price: Price as string (e.g., "$1.50"), int, or float.
+
+        Returns:
+            Decimal amount as float.
+
+        Raises:
+            ValueError: If the price format cannot be parsed.
+        """
+        if isinstance(price, str):
+            clean = price.strip()
+            # Remove $ prefix
+            if clean.startswith("$"):
+                clean = clean[1:].strip()
+            # Take the first token (handle "1.50 USDT" format)
+            parts = clean.split()
+            if parts:
+                try:
+                    return float(parts[0])
+                except ValueError:
+                    raise ValueError(f"Failed to parse price string: '{price}'")
+            raise ValueError(f"Empty price string: '{price}'")
+
+        if isinstance(price, (int, float)):
+            return float(price)
+
+        raise ValueError(f"Invalid price format: {price}")

t402/schemes/aptos/types.py

@@ -0,0 +1,237 @@
+"""Aptos Scheme Types.
+
+This module defines the data types used by the Aptos exact-direct payment scheme,
+including the payload structure, transaction result, and signer protocols.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class ClientAptosSigner(Protocol):
+    """Protocol for Aptos client-side signing operations.
+
+    Implementations must provide the signer's address and the ability
+    to sign and submit transactions to the Aptos network.
+
+    Example:
+        ```python
+        class MyAptosSigner:
+            def __init__(self, account, client):
+                self._account = account
+                self._client = client
+
+            def address(self) -> str:
+                return str(self._account.address())
+
+            async def sign_and_submit(self, payload: Dict, network: str) -> str:
+                txn = await self._client.submit_transaction(
+                    self._account, payload
+                )
+                return txn["hash"]
+        ```
+    """
+
+    def address(self) -> str:
+        """Return the signer's Aptos address (0x-prefixed hex).
+
+        Returns:
+            The account address as a hex string.
+        """
+        ...
+
+    async def sign_and_submit(self, payload: Dict[str, Any], network: str) -> str:
+        """Sign and submit a transaction to the Aptos network.
+
+        Args:
+            payload: Transaction payload dict with function, type_arguments, and arguments.
+            network: CAIP-2 network identifier (e.g., "aptos:1").
+
+        Returns:
+            Transaction hash as a 0x-prefixed hex string.
+
+        Raises:
+            Exception: If signing or submission fails.
+        """
+        ...
+
+
+@runtime_checkable
+class FacilitatorAptosSigner(Protocol):
+    """Protocol for Aptos facilitator-side operations.
+
+    Implementations must provide the ability to query transactions
+    from the Aptos network for verification.
+
+    Example:
+        ```python
+        import httpx
+
+        class MyAptosQuerier:
+            def __init__(self, rpc_url: str):
+                self._rpc_url = rpc_url
+                self._client = httpx.AsyncClient()
+
+            def get_addresses(self, network: str) -> List[str]:
+                return []  # No on-chain addresses needed for exact-direct
+
+            async def get_transaction(self, tx_hash: str, network: str) -> Dict:
+                resp = await self._client.get(
+                    f"{self._rpc_url}/transactions/by_hash/{tx_hash}"
+                )
+                return resp.json()
+        ```
+    """
+
+    def get_addresses(self, network: str) -> List[str]:
+        """Return the facilitator's Aptos addresses for a network.
+
+        For exact-direct, the facilitator typically does not hold funds
+        and may return an empty list.
+
+        Args:
+            network: CAIP-2 network identifier.
+
+        Returns:
+            List of facilitator addresses.
+        """
+        ...
+
+    async def get_transaction(self, tx_hash: str, network: str) -> Dict[str, Any]:
+        """Query a transaction by hash from the Aptos network.
+
+        Args:
+            tx_hash: The transaction hash to query (0x-prefixed).
+            network: CAIP-2 network identifier.
+
+        Returns:
+            Transaction result dict from the Aptos REST API containing fields:
+            - hash: Transaction hash
+            - version: Ledger version
+            - success: Whether the transaction succeeded
+            - vm_status: VM execution status
+            - sender: Transaction sender address
+            - timestamp: Block timestamp in microseconds
+            - payload: Transaction payload
+            - events: Transaction events
+
+        Raises:
+            Exception: If the transaction is not found or the query fails.
+        """
+        ...
+
+
+class ExactDirectPayload:
+    """Represents the payment payload for the exact-direct scheme on Aptos.
+
+    This payload contains proof that the client has already executed a
+    fungible asset transfer on-chain.
+
+    Attributes:
+        tx_hash: The transaction hash of the completed transfer.
+        from_address: The sender's Aptos address.
+        to_address: The recipient's Aptos address.
+        amount: The transfer amount in atomic units.
+        metadata_address: The FA metadata object address.
+    """
+
+    def __init__(
+        self,
+        tx_hash: str,
+        from_address: str,
+        to_address: str,
+        amount: str,
+        metadata_address: str,
+    ) -> None:
+        self.tx_hash = tx_hash
+        self.from_address = from_address
+        self.to_address = to_address
+        self.amount = amount
+        self.metadata_address = metadata_address
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for serialization.
+
+        Returns:
+            Dict with camelCase keys matching the protocol format.
+        """
+        return {
+            "txHash": self.tx_hash,
+            "from": self.from_address,
+            "to": self.to_address,
+            "amount": self.amount,
+            "metadataAddress": self.metadata_address,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "ExactDirectPayload":
+        """Create an ExactDirectPayload from a dictionary.
+
+        Args:
+            data: Dict with payload fields (supports both camelCase and snake_case).
+
+        Returns:
+            ExactDirectPayload instance.
+
+        Raises:
+            ValueError: If required fields are missing.
+        """
+        tx_hash = data.get("txHash") or data.get("tx_hash", "")
+        from_address = data.get("from") or data.get("from_address", "")
+        to_address = data.get("to") or data.get("to_address", "")
+        amount = data.get("amount", "")
+        metadata_address = (
+            data.get("metadataAddress") or data.get("metadata_address", "")
+        )
+
+        return cls(
+            tx_hash=tx_hash,
+            from_address=from_address,
+            to_address=to_address,
+            amount=amount,
+            metadata_address=metadata_address,
+        )
+
+
+def extract_transfer_details(tx: Dict[str, Any]) -> Optional[Dict[str, str]]:
+    """Extract fungible asset transfer details from a transaction result.
+
+    Parses the transaction payload to extract sender, recipient, amount,
+    and metadata address from a primary_fungible_store::transfer call.
+
+    Args:
+        tx: Transaction result dict from the Aptos REST API.
+
+    Returns:
+        Dict with 'from', 'to', 'amount', 'metadata_address' keys,
+        or None if the transaction is not a valid FA transfer.
+    """
+    if not tx or not tx.get("success"):
+        return None
+
+    payload = tx.get("payload")
+    if not payload or payload.get("type") != "entry_function_payload":
+        return None
+
+    function = payload.get("function", "")
+    if "primary_fungible_store::transfer" not in function:
+        return None
+
+    arguments = payload.get("arguments", [])
+    if len(arguments) < 3:
+        return None
+
+    metadata_address = str(arguments[0])
+    to_address = str(arguments[1])
+    amount = str(arguments[2])
+
+    sender = tx.get("sender", "")
+
+    return {
+        "from": sender,
+        "to": to_address,
+        "amount": amount,
+        "metadata_address": metadata_address,
+    }

t402/schemes/evm/__init__.py

@@ -4,20 +4,55 @@ This package provides payment scheme implementations for EVM-compatible
 blockchains (Ethereum, Base, Avalanche, etc.).
 
 Supported schemes:
-- exact: EIP-3009 TransferWithAuthorization
+- exact: EIP-3009 TransferWithAuthorization (recommended)
+- exact-legacy: approve + transferFrom (DEPRECATED - see deprecation notice below)
 - upto: EIP-2612 Permit (usage-based billing)
+
+.. deprecated:: 2.3.0
+    The **exact-legacy** scheme is deprecated and will be removed in v3.0.0.
+
+    The exact-legacy scheme uses the traditional approve + transferFrom pattern,
+    which has several drawbacks compared to the "exact" scheme with USDT0:
+
+    1. **Two transactions required**: Users must approve then transfer
+    2. **Gas costs**: Users pay gas for both transactions
+    3. **Limited availability**: Legacy USDT only on specific chains
+
+    **Migration Guide:**
+    1. Replace `ExactLegacyEvmClientScheme` with `ExactEvmClientScheme`
+    2. Replace `ExactLegacyEvmServerScheme` with `ExactEvmServerScheme`
+    3. Use USDT0 token addresses instead of legacy USDT
+    4. See https://docs.t402.io/migration/exact-legacy for details
+
+    **USDT0 Advantages:**
+    - Single signature (no approve transaction)
+    - Gasless via EIP-3009
+    - Available on 19+ chains via LayerZero
+    - Cross-chain bridging support
 """
 
 from t402.schemes.evm.exact import (
     ExactEvmClientScheme,
     ExactEvmServerScheme,
+    ExactEvmFacilitatorScheme,
+    FacilitatorEvmSigner,
+    EvmVerifyResult,
+    EvmTransactionConfirmation,
     EvmSigner,
     create_nonce,
     SCHEME_EXACT,
 )
 
+from t402.schemes.evm.exact_legacy import (
+    ExactLegacyEvmClientScheme,
+    ExactLegacyEvmServerScheme,
+    SCHEME_EXACT_LEGACY,
+)
+
 from t402.schemes.evm.upto import (
     UptoEvmClientScheme,
+    UptoEvmServerScheme,
+    UptoEvmFacilitatorScheme,
     create_payment_nonce,
     SCHEME_UPTO,
     PermitSignature,
@@ -31,11 +66,21 @@ __all__ = [
     # Exact scheme
     "ExactEvmClientScheme",
     "ExactEvmServerScheme",
+    "ExactEvmFacilitatorScheme",
+    "FacilitatorEvmSigner",
+    "EvmVerifyResult",
+    "EvmTransactionConfirmation",
     "EvmSigner",
     "create_nonce",
     "SCHEME_EXACT",
+    # Exact-Legacy scheme
+    "ExactLegacyEvmClientScheme",
+    "ExactLegacyEvmServerScheme",
+    "SCHEME_EXACT_LEGACY",
     # Upto scheme
     "UptoEvmClientScheme",
+    "UptoEvmServerScheme",
+    "UptoEvmFacilitatorScheme",
     "create_payment_nonce",
     "SCHEME_UPTO",
     "PermitSignature",

t402/schemes/evm/exact/__init__.py

@@ -16,6 +16,12 @@ from t402.schemes.evm.exact.client import (
 from t402.schemes.evm.exact.server import (
     ExactEvmServerScheme,
 )
+from t402.schemes.evm.exact.facilitator import (
+    ExactEvmFacilitatorScheme,
+    FacilitatorEvmSigner,
+    EvmVerifyResult,
+    EvmTransactionConfirmation,
+)
 
 __all__ = [
     # Client
@@ -24,6 +30,11 @@ __all__ = [
     "create_nonce",
     # Server
     "ExactEvmServerScheme",
+    # Facilitator
+    "ExactEvmFacilitatorScheme",
+    "FacilitatorEvmSigner",
+    "EvmVerifyResult",
+    "EvmTransactionConfirmation",
     # Constants
     "SCHEME_EXACT",
 ]

t402/schemes/evm/exact/client.py

@@ -123,7 +123,9 @@ class ExactEvmClientScheme:
         asset = req.get("asset", "")
 
         # Get timeout
-        max_timeout = req.get("maxTimeoutSeconds") or req.get("max_timeout_seconds", 300)
+        max_timeout = req.get("maxTimeoutSeconds") or req.get(
+            "max_timeout_seconds", 300
+        )
 
         # Get EIP-712 domain info from extra
         extra = req.get("extra", {})