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

t402/schemes/tezos/exact_direct/server.py

@@ -0,0 +1,277 @@
+"""Tezos Exact-Direct Scheme - Server Implementation.
+
+This module provides the server-side implementation of the exact-direct payment
+scheme for Tezos. It handles price parsing (converting user-friendly prices to
+atomic units) and enhancement of payment requirements with Tezos-specific
+FA2 asset information (CAIP-19 identifiers, token metadata).
+"""
+
+from __future__ import annotations
+
+import logging
+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.schemes.tezos.constants import (
+    SCHEME_EXACT_DIRECT,
+    is_tezos_network,
+    get_network_config,
+    get_token_info,
+    create_asset_identifier,
+    parse_decimal_to_atomic,
+    TokenInfo,
+)
+
+
+logger = logging.getLogger(__name__)
+
+
+class ExactDirectTezosServer:
+    """Server scheme for Tezos exact-direct payments.
+
+    Handles parsing user-friendly prices (e.g., "$1.50") into atomic amounts
+    and enhancing payment requirements with Tezos-specific metadata including
+    CAIP-19 asset identifiers and token information.
+
+    Example:
+        ```python
+        from t402.schemes.tezos import ExactDirectTezosServer
+
+        server = ExactDirectTezosServer()
+
+        # Parse price to atomic units
+        asset_amount = await server.parse_price("$0.10", "tezos:NetXdQprcVkpaWU")
+        # Returns: {
+        #     "amount": "100000",
+        #     "asset": "tezos:NetXdQprcVkpaWU/fa2:KT1XnTn74.../0",
+        #     "extra": {"symbol": "USDt", "name": "Tether USD", "decimals": 6}
+        # }
+
+        # Enhance requirements with token metadata
+        enhanced = await server.enhance_requirements(
+            requirements, supported_kind, []
+        )
+        ```
+    """
+
+    scheme = SCHEME_EXACT_DIRECT
+    caip_family = "tezos:*"
+
+    def __init__(self, preferred_token: Optional[str] = None):
+        """Initialize the Tezos exact-direct server.
+
+        Args:
+            preferred_token: Preferred token symbol (e.g., "USDt").
+                If set, this token will be used for price conversions
+                when available on the network. Defaults to the network's
+                default token.
+        """
+        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:
+        - String with $ prefix: "$0.10" -> 100000 (6 decimals)
+        - String without prefix: "0.10" -> 100000
+        - Integer/float: 0.10 -> 100000
+        - Dict (AssetAmount): {"amount": "100000", "asset": "tezos:.../fa2:KT1.../0"}
+
+        Args:
+            price: User-friendly price
+            network: Network identifier (CAIP-2 format, e.g., "tezos:NetXdQprcVkpaWU")
+
+        Returns:
+            AssetAmount dict with amount (atomic), asset (CAIP-19), and extra metadata
+
+        Raises:
+            ValueError: If network is unsupported or price format is invalid
+        """
+        # Validate network
+        if not is_tezos_network(network):
+            raise ValueError(f"Invalid Tezos network: {network}")
+
+        # Handle dict (already in AssetAmount format)
+        if isinstance(price, dict):
+            amount_str = str(price.get("amount", "0"))
+            asset = price.get("asset", "")
+            if not asset:
+                raise ValueError(
+                    f"Asset must be specified for AssetAmount on network {network}"
+                )
+            return {
+                "amount": amount_str,
+                "asset": asset,
+                "extra": price.get("extra", {}),
+            }
+
+        # Get default token for the network
+        token = self._get_default_token(network)
+        if token is None:
+            raise ValueError(f"No token configured for network {network}")
+
+        # Parse price string/number to decimal
+        amount_decimal = self._parse_money_to_decimal(price)
+
+        # Convert to atomic units
+        atomic_amount = int(amount_decimal * Decimal(10**token.decimals))
+
+        # Build CAIP-19 asset identifier
+        asset_id = create_asset_identifier(network, token.contract_address, token.token_id)
+
+        # Build extra metadata
+        extra: Dict[str, Any] = {
+            "symbol": token.symbol,
+            "name": token.name,
+            "decimals": token.decimals,
+            "tokenId": token.token_id,
+        }
+
+        return {
+            "amount": str(atomic_amount),
+            "asset": asset_id,
+            "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 Tezos-specific metadata.
+
+        Adds FA2 token information to the extra field, resolves CAIP-19 asset
+        identifiers, and converts decimal amounts to atomic units if needed.
+
+        Args:
+            requirements: Base payment requirements with amount/asset set
+            supported_kind: Matched SupportedKind from the facilitator
+            facilitator_extensions: Extension keys supported by facilitator
+
+        Returns:
+            Enhanced requirements dict with Tezos metadata in extra field
+        """
+        # 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", "")
+
+        # Validate network
+        if not is_tezos_network(network):
+            raise ValueError(f"Invalid Tezos network: {network}")
+
+        # Get network config
+        network_config = get_network_config(network)
+        if network_config is None:
+            raise ValueError(f"Unsupported Tezos network: {network}")
+
+        # Resolve token info
+        token = self._get_default_token(network)
+
+        # Ensure asset is in CAIP-19 format
+        if not req.get("asset") and token is not None:
+            req["asset"] = create_asset_identifier(
+                network, token.contract_address, token.token_id
+            )
+
+        # Convert decimal amount to atomic units if needed
+        amount = req.get("amount", "")
+        if amount and "." in amount and token is not None:
+            req["amount"] = parse_decimal_to_atomic(amount, token.decimals)
+
+        # Ensure extra exists
+        if "extra" not in req or req["extra"] is None:
+            req["extra"] = {}
+
+        # Add token metadata to extra
+        if token is not None:
+            if "assetSymbol" not in req["extra"]:
+                req["extra"]["assetSymbol"] = token.symbol
+            if "assetDecimals" not in req["extra"]:
+                req["extra"]["assetDecimals"] = token.decimals
+            if "assetName" not in req["extra"]:
+                req["extra"]["assetName"] = token.name
+
+        # Add network name for convenience
+        if "networkName" not in req["extra"]:
+            req["extra"]["networkName"] = network_config.name
+
+        # Copy extensions from supportedKind if provided
+        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_default_token(self, network: str) -> Optional[TokenInfo]:
+        """Get the default token for a given network.
+
+        If a preferred token is configured, tries to use it first.
+        Falls back to the network's default token.
+
+        Args:
+            network: CAIP-2 network identifier
+
+        Returns:
+            TokenInfo if available, None otherwise
+        """
+        # If a preferred token is configured, try to use it
+        if self._preferred_token:
+            token = get_token_info(network, self._preferred_token)
+            if token is not None:
+                return token
+
+        # Use the network's default token
+        config = get_network_config(network)
+        if config is None:
+            return None
+        return config.default_token
+
+    def _parse_money_to_decimal(self, price: Union[str, int, float]) -> Decimal:
+        """Parse a money value to a Decimal amount.
+
+        Handles currency symbols, whitespace, and common suffixes.
+
+        Args:
+            price: Price as string, int, or float
+
+        Returns:
+            Decimal amount
+
+        Raises:
+            ValueError: If the price format cannot be parsed
+        """
+        if isinstance(price, (int, float)):
+            return Decimal(str(price))
+
+        if isinstance(price, str):
+            clean_price = price.strip()
+            # Remove currency prefix
+            if clean_price.startswith("$"):
+                clean_price = clean_price[1:]
+            # Remove common suffixes
+            for suffix in (" USD", " USDT", " USDt"):
+                if clean_price.endswith(suffix):
+                    clean_price = clean_price[: -len(suffix)]
+            clean_price = clean_price.strip()
+
+            try:
+                return Decimal(clean_price)
+            except Exception:
+                raise ValueError(f"Failed to parse price string: {price}")
+
+        raise ValueError(f"Unsupported price type: {type(price)}")

t402/schemes/tezos/types.py

@@ -0,0 +1,220 @@
+"""Tezos Scheme Type Definitions.
+
+This module defines the Pydantic models and Protocol interfaces used by the
+Tezos exact-direct payment scheme.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Protocol, runtime_checkable
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+from pydantic.alias_generators import to_camel
+
+
+@runtime_checkable
+class ClientTezosSigner(Protocol):
+    """Protocol for Tezos client-side signing operations.
+
+    Implementations are responsible for managing private keys, constructing
+    FA2 transfer operations, signing, and injecting them into the Tezos network.
+
+    Example implementation:
+        ```python
+        class MyTezosSigner:
+            def __init__(self, private_key: str, rpc_url: str):
+                self._key = private_key
+                self._rpc_url = rpc_url
+
+            def address(self) -> str:
+                return "tz1..."
+
+            async def transfer_fa2(
+                self,
+                contract: str,
+                token_id: int,
+                to: str,
+                amount: int,
+                network: str,
+            ) -> str:
+                # Build FA2 transfer, sign and inject
+                return "o..."  # operation hash
+        ```
+    """
+
+    def address(self) -> str:
+        """Return the Tezos address (tz1/tz2/tz3) of the signer."""
+        ...
+
+    async def transfer_fa2(
+        self,
+        contract: str,
+        token_id: int,
+        to: str,
+        amount: int,
+        network: str,
+    ) -> str:
+        """Execute an FA2 transfer operation on-chain.
+
+        Constructs the FA2 transfer call parameter, signs the operation,
+        and injects it into the Tezos network.
+
+        Args:
+            contract: The FA2 contract address (KT1...)
+            token_id: The token ID within the FA2 contract
+            to: Recipient Tezos address
+            amount: Amount in atomic units (integer)
+            network: CAIP-2 network identifier
+
+        Returns:
+            The operation hash (starts with 'o', 51 characters)
+
+        Raises:
+            Exception: If the transfer fails
+        """
+        ...
+
+
+@runtime_checkable
+class FacilitatorTezosSigner(Protocol):
+    """Protocol for Tezos facilitator-side operations.
+
+    Implementations query the Tezos blockchain (via RPC or indexer)
+    to verify operation status and details.
+
+    Example implementation:
+        ```python
+        class MyTezosQuerier:
+            def __init__(self, indexer_url: str):
+                self._indexer_url = indexer_url
+
+            async def get_operation(
+                self, op_hash: str, network: str
+            ) -> Dict[str, Any]:
+                # Query TzKT indexer for operation details
+                response = await httpx.get(
+                    f"{self._indexer_url}/v1/operations/{op_hash}"
+                )
+                return response.json()
+        ```
+    """
+
+    async def get_operation(self, op_hash: str, network: str) -> Dict[str, Any]:
+        """Query an operation by its hash.
+
+        Returns the operation details from the Tezos blockchain,
+        typically via a TzKT indexer API.
+
+        Args:
+            op_hash: The operation hash to query
+            network: CAIP-2 network identifier
+
+        Returns:
+            Dict containing operation details with at minimum:
+            - "status": str ("applied", "failed", "backtracked", "skipped")
+            - "sender": Dict with "address" key
+            - "target": Dict with "address" key (the FA2 contract)
+            - "entrypoint": str (should be "transfer")
+            - "parameter": The FA2 transfer parameters
+
+        Raises:
+            Exception: If the query fails or operation not found
+        """
+        ...
+
+
+class TezosFA2TransferTx(BaseModel):
+    """A single transfer transaction within an FA2 transfer batch.
+
+    Attributes:
+        to: Recipient address
+        token_id: Token ID within the FA2 contract
+        amount: Amount in atomic units
+    """
+
+    to: str = Field(alias="to_")
+    token_id: int = Field(alias="token_id")
+    amount: str
+
+    model_config = ConfigDict(
+        populate_by_name=True,
+        from_attributes=True,
+    )
+
+
+class TezosFA2TransferParam(BaseModel):
+    """FA2 transfer parameter structure.
+
+    Represents a single sender's batch of transfers in the FA2 standard.
+
+    Attributes:
+        from_: Sender address
+        txs: List of transfer transactions
+    """
+
+    from_: str = Field(alias="from_")
+    txs: List[TezosFA2TransferTx]
+
+    model_config = ConfigDict(
+        populate_by_name=True,
+        from_attributes=True,
+    )
+
+
+class ExactDirectPayload(BaseModel):
+    """Payload for the Tezos exact-direct payment scheme.
+
+    Contains the operation hash proving on-chain execution and metadata
+    about the FA2 transfer for verification.
+
+    Attributes:
+        op_hash: The Tezos operation hash (starts with 'o', 51 chars)
+        from_: Sender's Tezos address
+        to: Recipient's Tezos address
+        amount: Amount transferred in atomic units
+        contract_address: FA2 contract address
+        token_id: Token ID within the FA2 contract
+    """
+
+    op_hash: str = Field(alias="opHash")
+    from_: str = Field(alias="from")
+    to: str
+    amount: str
+    contract_address: str = Field(alias="contractAddress")
+    token_id: int = Field(alias="tokenId")
+
+    model_config = ConfigDict(
+        alias_generator=to_camel,
+        populate_by_name=True,
+        from_attributes=True,
+    )
+
+    @field_validator("amount")
+    @classmethod
+    def validate_amount(cls, v: str) -> str:
+        """Validate that amount is a positive integer string."""
+        try:
+            val = int(v)
+            if val <= 0:
+                raise ValueError("amount must be a positive integer")
+        except ValueError:
+            raise ValueError("amount must be a positive integer encoded as a string")
+        return v
+
+    @field_validator("op_hash")
+    @classmethod
+    def validate_op_hash(cls, v: str) -> str:
+        """Validate operation hash format."""
+        if not v.startswith("o"):
+            raise ValueError("Operation hash must start with 'o'")
+        if len(v) != 51:
+            raise ValueError("Operation hash must be 51 characters")
+        return v
+
+    def to_map(self) -> Dict[str, Any]:
+        """Convert to a dict suitable for payment payload.
+
+        Returns:
+            Dict with camelCase keys matching the protocol format.
+        """
+        return self.model_dump(by_alias=True)

t402/schemes/ton/__init__.py

@@ -9,14 +9,21 @@ Supported schemes:
 from t402.schemes.ton.exact import (
     ExactTonClientScheme,
     ExactTonServerScheme,
+    ExactTonFacilitatorScheme,
     TonSigner,
+    FacilitatorTonSigner,
     SCHEME_EXACT,
 )
 
 __all__ = [
-    # Exact scheme
+    # Client
     "ExactTonClientScheme",
-    "ExactTonServerScheme",
     "TonSigner",
+    # Server
+    "ExactTonServerScheme",
+    # Facilitator
+    "ExactTonFacilitatorScheme",
+    "FacilitatorTonSigner",
+    # Constants
     "SCHEME_EXACT",
 ]

t402/schemes/ton/exact/__init__.py

@@ -15,6 +15,10 @@ from t402.schemes.ton.exact.client import (
 from t402.schemes.ton.exact.server import (
     ExactTonServerScheme,
 )
+from t402.schemes.ton.exact.facilitator import (
+    ExactTonFacilitatorScheme,
+    FacilitatorTonSigner,
+)
 
 __all__ = [
     # Client
@@ -22,6 +26,9 @@ __all__ = [
     "TonSigner",
     # Server
     "ExactTonServerScheme",
+    # Facilitator
+    "ExactTonFacilitatorScheme",
+    "FacilitatorTonSigner",
     # Constants
     "SCHEME_EXACT",
 ]