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

t402/schemes/tezos/constants.py

@@ -0,0 +1,372 @@
+"""Tezos Blockchain Constants for T402 Protocol.
+
+This module defines constants, token information, and network configurations
+for the Tezos blockchain mechanism in the T402 protocol.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+
+# Scheme identifier
+SCHEME_EXACT_DIRECT = "exact-direct"
+
+# CAIP-2 network identifiers (derived from genesis block hash prefix)
+TEZOS_MAINNET = "tezos:NetXdQprcVkpaWU"
+TEZOS_GHOSTNET = "tezos:NetXnHfVqm9iesp"
+
+# RPC endpoints
+TEZOS_MAINNET_RPC = "https://mainnet.api.tez.ie"
+TEZOS_GHOSTNET_RPC = "https://ghostnet.tezos.marigold.dev"
+
+# Indexer API endpoints (TzKT)
+TEZOS_MAINNET_INDEXER = "https://api.tzkt.io"
+TEZOS_GHOSTNET_INDEXER = "https://api.ghostnet.tzkt.io"
+
+# FA2 token standard (TZIP-12)
+FA2_TRANSFER_ENTRYPOINT = "transfer"
+
+# USDt on Tezos Mainnet
+USDT_MAINNET_CONTRACT = "KT1XnTn74bUtxHfDtBmm2bGZAQfhPbvKWR8o"
+USDT_MAINNET_TOKEN_ID = 0
+USDT_DECIMALS = 6
+
+# Address length for Tezos addresses (tz1/tz2/tz3/KT1)
+TEZOS_ADDRESS_LENGTH = 36
+
+# Operation hash length (starts with 'o')
+TEZOS_OP_HASH_LENGTH = 51
+
+# Valid address prefixes
+VALID_ADDRESS_PREFIXES = ("tz1", "tz2", "tz3", "KT1")
+
+# Base58 character set (no 0, O, I, l)
+BASE58_CHARS = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"
+
+
+class TokenInfo:
+    """Information about a Tezos FA2 token.
+
+    Attributes:
+        contract_address: The FA2 contract address (KT1...)
+        token_id: The token ID within the FA2 contract
+        symbol: Token symbol (e.g., "USDt")
+        name: Full token name (e.g., "Tether USD")
+        decimals: Number of decimal places
+    """
+
+    def __init__(
+        self,
+        contract_address: str,
+        token_id: int,
+        symbol: str,
+        name: str,
+        decimals: int,
+    ):
+        self.contract_address = contract_address
+        self.token_id = token_id
+        self.symbol = symbol
+        self.name = name
+        self.decimals = decimals
+
+
+class NetworkConfig:
+    """Configuration for a Tezos network.
+
+    Attributes:
+        name: Human-readable network name
+        rpc_url: Tezos RPC endpoint URL
+        indexer_url: TzKT indexer API URL
+        default_token: Default token for price conversion (may be None)
+        is_testnet: Whether this is a testnet
+    """
+
+    def __init__(
+        self,
+        name: str,
+        rpc_url: str,
+        indexer_url: str,
+        default_token: Optional[TokenInfo] = None,
+        is_testnet: bool = False,
+    ):
+        self.name = name
+        self.rpc_url = rpc_url
+        self.indexer_url = indexer_url
+        self.default_token = default_token
+        self.is_testnet = is_testnet
+
+
+# Token definitions
+USDT_MAINNET = TokenInfo(
+    contract_address=USDT_MAINNET_CONTRACT,
+    token_id=USDT_MAINNET_TOKEN_ID,
+    symbol="USDt",
+    name="Tether USD",
+    decimals=USDT_DECIMALS,
+)
+
+# Network configurations
+NETWORK_CONFIGS: Dict[str, NetworkConfig] = {
+    TEZOS_MAINNET: NetworkConfig(
+        name="Tezos Mainnet",
+        rpc_url=TEZOS_MAINNET_RPC,
+        indexer_url=TEZOS_MAINNET_INDEXER,
+        default_token=USDT_MAINNET,
+        is_testnet=False,
+    ),
+    TEZOS_GHOSTNET: NetworkConfig(
+        name="Tezos Ghostnet",
+        rpc_url=TEZOS_GHOSTNET_RPC,
+        indexer_url=TEZOS_GHOSTNET_INDEXER,
+        default_token=None,  # No USDT on testnet
+        is_testnet=True,
+    ),
+}
+
+# Token registry indexed by network and symbol
+TOKEN_REGISTRY: Dict[str, Dict[str, TokenInfo]] = {
+    TEZOS_MAINNET: {
+        "USDt": USDT_MAINNET,
+    },
+    TEZOS_GHOSTNET: {},
+}
+
+
+def get_network_config(network: str) -> Optional[NetworkConfig]:
+    """Get the configuration for a Tezos network.
+
+    Args:
+        network: CAIP-2 network identifier (e.g., "tezos:NetXdQprcVkpaWU")
+
+    Returns:
+        NetworkConfig if found, None otherwise
+    """
+    return NETWORK_CONFIGS.get(network)
+
+
+def get_token_info(network: str, symbol: str) -> Optional[TokenInfo]:
+    """Get token information by network and symbol.
+
+    Args:
+        network: CAIP-2 network identifier
+        symbol: Token symbol (e.g., "USDt")
+
+    Returns:
+        TokenInfo if found, None otherwise
+    """
+    tokens = TOKEN_REGISTRY.get(network, {})
+    return tokens.get(symbol)
+
+
+def get_token_by_contract(
+    network: str, contract_address: str, token_id: int
+) -> Optional[TokenInfo]:
+    """Get token information by contract address and token ID.
+
+    Args:
+        network: CAIP-2 network identifier
+        contract_address: FA2 contract address
+        token_id: Token ID within the contract
+
+    Returns:
+        TokenInfo if found, None otherwise
+    """
+    tokens = TOKEN_REGISTRY.get(network, {})
+    for token in tokens.values():
+        if token.contract_address == contract_address and token.token_id == token_id:
+            return token
+    return None
+
+
+def is_tezos_network(network: str) -> bool:
+    """Check if a network identifier belongs to the Tezos namespace.
+
+    Args:
+        network: Network identifier string
+
+    Returns:
+        True if the network starts with "tezos:"
+    """
+    return network.startswith("tezos:")
+
+
+def is_valid_address(address: str) -> bool:
+    """Validate a Tezos address format.
+
+    Valid addresses:
+    - Implicit accounts: tz1, tz2, tz3 (36 characters)
+    - Contract accounts: KT1 (36 characters)
+
+    All characters must be valid Base58 characters.
+
+    Args:
+        address: The address to validate
+
+    Returns:
+        True if the address format is valid
+    """
+    if not address:
+        return False
+    if not address.startswith(VALID_ADDRESS_PREFIXES):
+        return False
+    if len(address) != TEZOS_ADDRESS_LENGTH:
+        return False
+    # Check all characters are valid base58
+    for char in address:
+        if char not in BASE58_CHARS:
+            return False
+    return True
+
+
+def is_valid_operation_hash(op_hash: str) -> bool:
+    """Validate a Tezos operation hash format.
+
+    Operation hashes start with 'o' and are 51 characters of Base58.
+
+    Args:
+        op_hash: The operation hash to validate
+
+    Returns:
+        True if the operation hash format is valid
+    """
+    if not op_hash:
+        return False
+    if not op_hash.startswith("o"):
+        return False
+    if len(op_hash) != TEZOS_OP_HASH_LENGTH:
+        return False
+    # Check all characters are valid base58
+    for char in op_hash:
+        if char not in BASE58_CHARS:
+            return False
+    return True
+
+
+def create_asset_identifier(network: str, contract_address: str, token_id: int) -> str:
+    """Create a CAIP-19 asset identifier for a Tezos FA2 token.
+
+    Format: tezos:{chainRef}/fa2:{contractAddress}/{tokenId}
+
+    Args:
+        network: CAIP-2 network identifier (e.g., "tezos:NetXdQprcVkpaWU")
+        contract_address: FA2 contract address (e.g., "KT1XnTn74bUtxHfDtBmm2bGZAQfhPbvKWR8o")
+        token_id: Token ID within the FA2 contract
+
+    Returns:
+        CAIP-19 asset identifier string
+    """
+    return f"{network}/fa2:{contract_address}/{token_id}"
+
+
+def parse_asset_identifier(asset: str) -> Dict[str, Any]:
+    """Parse a CAIP-19 asset identifier for Tezos FA2 tokens.
+
+    Supports two formats:
+    - CAIP-19: tezos:{chainRef}/fa2:{contractAddress}/{tokenId}
+    - Simple: {contractAddress}/{tokenId} or {contractAddress} (tokenId defaults to 0)
+
+    Args:
+        asset: The asset identifier string
+
+    Returns:
+        Dict with "contract_address" (str) and "token_id" (int)
+
+    Raises:
+        ValueError: If the asset format is unrecognized
+    """
+    if not asset:
+        raise ValueError("Asset identifier is empty")
+
+    # Try CAIP-19 format: tezos:{chainRef}/fa2:{contract}/{tokenId}
+    if asset.startswith("tezos:"):
+        parts = asset.split("/")
+        if len(parts) == 3 and parts[1].startswith("fa2:"):
+            contract_address = parts[1][4:]  # Remove "fa2:" prefix
+            try:
+                token_id = int(parts[2])
+            except ValueError:
+                raise ValueError(f"Invalid token ID in asset: {asset}")
+            if not contract_address.startswith("KT1") or len(contract_address) != 36:
+                raise ValueError(f"Invalid contract address in asset: {asset}")
+            return {"contract_address": contract_address, "token_id": token_id}
+
+    # Try simple format: KT1.../tokenId or KT1...
+    if asset.startswith("KT1"):
+        parts = asset.split("/")
+        contract_address = parts[0]
+        if len(contract_address) != 36:
+            raise ValueError(f"Invalid contract address in asset: {asset}")
+        token_id = 0
+        if len(parts) == 2:
+            try:
+                token_id = int(parts[1])
+            except ValueError:
+                raise ValueError(f"Invalid token ID in asset: {asset}")
+        elif len(parts) > 2:
+            raise ValueError(f"Unrecognized asset format: {asset}")
+        return {"contract_address": contract_address, "token_id": token_id}
+
+    raise ValueError(
+        f"Unrecognized asset format: {asset} "
+        f"(expected tezos:{{chainRef}}/fa2:{{contract}}/{{tokenId}} or KT1...)"
+    )
+
+
+def decimal_to_atomic(amount: float, decimals: int) -> str:
+    """Convert a decimal amount to atomic units string.
+
+    Args:
+        amount: Decimal amount (e.g., 1.50)
+        decimals: Number of decimal places for the token
+
+    Returns:
+        Atomic amount as string (e.g., "1500000" for 6 decimals)
+    """
+
+    multiplier = 10**decimals
+    atomic = int(round(amount * multiplier))
+    return str(atomic)
+
+
+def parse_decimal_to_atomic(amount: str, decimals: int) -> str:
+    """Convert a decimal string amount to atomic units.
+
+    Args:
+        amount: Decimal string (e.g., "1.50")
+        decimals: Number of decimal places for the token
+
+    Returns:
+        Atomic amount string (e.g., "1500000" for 6 decimals)
+
+    Raises:
+        ValueError: If the amount format is invalid
+    """
+    parts = amount.split(".")
+
+    integer_part = parts[0]
+    fractional_part = ""
+
+    if len(parts) == 2:
+        fractional_part = parts[1]
+    elif len(parts) > 2:
+        raise ValueError(f"Invalid amount format: {amount}")
+
+    # Pad or truncate fractional part to match decimals
+    if len(fractional_part) > decimals:
+        fractional_part = fractional_part[:decimals]
+    else:
+        fractional_part = fractional_part + "0" * (decimals - len(fractional_part))
+
+    # Combine and parse as integer
+    combined = integer_part + fractional_part
+
+    # Remove leading zeros but keep at least one digit
+    combined = combined.lstrip("0") or "0"
+
+    try:
+        result = int(combined)
+    except ValueError:
+        raise ValueError(f"Failed to parse amount: {amount}")
+
+    return str(result)

t402/schemes/tezos/exact_direct/__init__.py

@@ -0,0 +1,22 @@
+"""Tezos Exact-Direct Payment Scheme.
+
+This package provides the exact-direct payment scheme implementation for Tezos.
+In this scheme, the client executes the FA2 transfer directly on-chain and
+provides the operation hash as proof of payment. The facilitator then verifies
+the operation on-chain.
+
+Components:
+- Client: Executes FA2 transfer and returns opHash
+- Server: Parses prices and enhances requirements with CAIP-19 asset info
+- Facilitator: Verifies operation status and transfer details on-chain
+"""
+
+from t402.schemes.tezos.exact_direct.client import ExactDirectTezosClient
+from t402.schemes.tezos.exact_direct.server import ExactDirectTezosServer
+from t402.schemes.tezos.exact_direct.facilitator import ExactDirectTezosFacilitator
+
+__all__ = [
+    "ExactDirectTezosClient",
+    "ExactDirectTezosServer",
+    "ExactDirectTezosFacilitator",
+]

t402/schemes/tezos/exact_direct/client.py

@@ -0,0 +1,226 @@
+"""Tezos Exact-Direct Scheme - Client Implementation.
+
+This module provides the client-side implementation of the exact-direct payment
+scheme for Tezos using FA2 token transfers.
+
+In the exact-direct scheme, the client directly executes the FA2 transfer on-chain
+and provides the operation hash as proof of payment. This differs from off-chain
+authorization schemes where the facilitator executes the transfer.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, Union
+
+from t402.types import (
+    PaymentRequirementsV2,
+    T402_VERSION_V1,
+    T402_VERSION_V2,
+)
+from t402.schemes.tezos.constants import (
+    SCHEME_EXACT_DIRECT,
+    is_tezos_network,
+    is_valid_address,
+    parse_asset_identifier,
+)
+from t402.schemes.tezos.types import (
+    ClientTezosSigner,
+    ExactDirectPayload,
+)
+
+
+logger = logging.getLogger(__name__)
+
+
+class ExactDirectTezosClient:
+    """Client scheme for Tezos exact-direct payments using FA2 transfers.
+
+    This scheme executes FA2 token transfers directly on-chain and provides
+    the operation hash as proof of payment. The facilitator verifies the
+    operation status and transfer details.
+
+    Example:
+        ```python
+        from t402.schemes.tezos import ExactDirectTezosClient
+
+        class MyTezosSigner:
+            def address(self) -> str:
+                return "tz1..."
+
+            async def transfer_fa2(
+                self, contract, token_id, to, amount, network
+            ) -> str:
+                # Execute FA2 transfer
+                return "oo7bHf..."  # operation hash
+
+        signer = MyTezosSigner()
+        client = ExactDirectTezosClient(signer=signer)
+
+        payload = await client.create_payment_payload(
+            t402_version=2,
+            requirements={
+                "scheme": "exact-direct",
+                "network": "tezos:NetXdQprcVkpaWU",
+                "asset": "tezos:NetXdQprcVkpaWU/fa2:KT1XnTn74bUtxHfDtBmm2bGZAQfhPbvKWR8o/0",
+                "amount": "1000000",
+                "payTo": "tz1...",
+                "maxTimeoutSeconds": 300,
+            },
+        )
+        ```
+    """
+
+    scheme = SCHEME_EXACT_DIRECT
+    caip_family = "tezos:*"
+
+    def __init__(self, signer: ClientTezosSigner):
+        """Initialize the Tezos exact-direct client.
+
+        Args:
+            signer: A Tezos signer implementing the ClientTezosSigner protocol.
+                    Must provide address() and transfer_fa2() methods.
+        """
+        self._signer = signer
+
+    @property
+    def address(self) -> str:
+        """Get the signer's Tezos address."""
+        return self._signer.address()
+
+    async def create_payment_payload(
+        self,
+        t402_version: int,
+        requirements: Union[PaymentRequirementsV2, Dict[str, Any]],
+    ) -> Dict[str, Any]:
+        """Execute FA2 transfer and create payment payload with operation hash.
+
+        This method:
+        1. Validates the payment requirements
+        2. Parses the CAIP-19 asset identifier
+        3. Executes the FA2 transfer on-chain via the signer
+        4. Returns a payload containing the operation hash as proof
+
+        Args:
+            t402_version: Protocol version (1 or 2)
+            requirements: Payment requirements specifying amount, network, asset, payTo
+
+        Returns:
+            Payment payload dict containing the operation hash and transfer metadata
+
+        Raises:
+            ValueError: If requirements are invalid (wrong scheme, network, address, etc.)
+            Exception: If the FA2 transfer fails
+        """
+        # Convert to dict for easier access
+        if hasattr(requirements, "model_dump"):
+            req = requirements.model_dump(by_alias=True)
+        else:
+            req = dict(requirements)
+
+        # Validate requirements
+        self._validate_requirements(req)
+
+        # Extract fields
+        network = req.get("network", "")
+        asset = req.get("asset", "")
+        amount = req.get("amount", "0")
+        pay_to = req.get("payTo") or req.get("pay_to", "")
+
+        # Parse asset to get contract address and token ID
+        asset_info = parse_asset_identifier(asset)
+        contract_address = asset_info["contract_address"]
+        token_id = asset_info["token_id"]
+
+        # Parse amount as integer
+        amount_int = int(amount)
+
+        # Execute FA2 transfer on-chain
+        logger.debug(
+            "Executing FA2 transfer: contract=%s, token_id=%d, to=%s, amount=%d",
+            contract_address,
+            token_id,
+            pay_to,
+            amount_int,
+        )
+        op_hash = await self._signer.transfer_fa2(
+            contract=contract_address,
+            token_id=token_id,
+            to=pay_to,
+            amount=amount_int,
+            network=network,
+        )
+
+        # Build the payload
+        payload_data = ExactDirectPayload(
+            op_hash=op_hash,
+            from_=self._signer.address(),
+            to=pay_to,
+            amount=amount,
+            contract_address=contract_address,
+            token_id=token_id,
+        )
+
+        if t402_version == T402_VERSION_V1:
+            return {
+                "t402Version": T402_VERSION_V1,
+                "scheme": self.scheme,
+                "network": network,
+                "payload": payload_data.to_map(),
+            }
+
+        # V2 format
+        return {
+            "t402Version": T402_VERSION_V2,
+            "payload": payload_data.to_map(),
+        }
+
+    def _validate_requirements(self, req: Dict[str, Any]) -> None:
+        """Validate payment requirements for the exact-direct scheme.
+
+        Args:
+            req: Requirements dict
+
+        Raises:
+            ValueError: If any validation check fails
+        """
+        # Check scheme
+        scheme = req.get("scheme", "")
+        if scheme and scheme != SCHEME_EXACT_DIRECT:
+            raise ValueError(
+                f"Invalid scheme: expected {SCHEME_EXACT_DIRECT}, got {scheme}"
+            )
+
+        # Check network is Tezos
+        network = req.get("network", "")
+        if not is_tezos_network(network):
+            raise ValueError(f"Invalid network: {network} (expected tezos:*)")
+
+        # Check payTo address
+        pay_to = req.get("payTo") or req.get("pay_to", "")
+        if not pay_to:
+            raise ValueError("PayTo address is required")
+        if not is_valid_address(pay_to):
+            raise ValueError(f"Invalid payTo address: {pay_to}")
+
+        # Check amount
+        amount = req.get("amount", "")
+        if not amount:
+            raise ValueError("Amount is required")
+        try:
+            amount_int = int(amount)
+            if amount_int <= 0:
+                raise ValueError(
+                    f"Invalid amount: {amount} (must be a positive integer)"
+                )
+        except ValueError:
+            raise ValueError(
+                f"Invalid amount: {amount} (must be a positive integer string)"
+            )
+
+        # Check asset
+        asset = req.get("asset", "")
+        if not asset:
+            raise ValueError("Asset is required")
+        # This will raise ValueError if invalid
+        parse_asset_identifier(asset)