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

t402/schemes/ton/exact/client.py

@@ -0,0 +1,343 @@
+"""TON Exact Scheme - Client Implementation.
+
+This module provides the client-side implementation of the exact payment scheme
+for TON network using Jetton transfers.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Callable, Dict, Optional, Protocol, Union, Awaitable
+
+from t402.types import (
+    PaymentRequirementsV2,
+    T402_VERSION_V1,
+    T402_VERSION_V2,
+)
+from t402.ton import (
+    TonAuthorization,
+    TonPaymentPayload,
+    DEFAULT_JETTON_TRANSFER_TON,
+    DEFAULT_FORWARD_TON,
+    validate_ton_address,
+)
+
+
+# Constants
+SCHEME_EXACT = "exact"
+
+
+class SignedMessage(Protocol):
+    """Protocol for a signed TON message."""
+
+    def to_boc_base64(self) -> str:
+        """Convert message to base64-encoded BOC."""
+        ...
+
+
+class TonSigner(Protocol):
+    """Protocol for TON wallet signing operations.
+
+    Implementations should provide wallet address, seqno retrieval,
+    and message signing capabilities.
+
+    Example implementation with tonsdk:
+        ```python
+        class MyTonSigner:
+            def __init__(self, wallet, client):
+                self._wallet = wallet
+                self._client = client
+
+            @property
+            def address(self) -> str:
+                return self._wallet.address.to_string(True, True, True)
+
+            async def get_seqno(self) -> int:
+                return await self._client.get_seqno(self._wallet.address)
+
+            async def sign_message(
+                self,
+                to: str,
+                value: int,
+                body: bytes,
+                timeout: int,
+            ) -> SignedMessage:
+                # Build and sign the message
+                return signed_message
+        ```
+    """
+
+    @property
+    def address(self) -> str:
+        """Return the wallet address as a friendly string."""
+        ...
+
+    async def get_seqno(self) -> int:
+        """Get the current sequence number for replay protection."""
+        ...
+
+    async def sign_message(
+        self,
+        to: str,
+        value: int,
+        body: bytes,
+        timeout: int,
+    ) -> SignedMessage:
+        """Sign a message to be sent to the TON network.
+
+        Args:
+            to: Destination address
+            value: Amount of TON in nanoTON
+            body: Message body as bytes (BOC)
+            timeout: Message validity timeout in seconds
+
+        Returns:
+            SignedMessage that can be converted to BOC
+        """
+        ...
+
+
+# Type for Jetton wallet address resolver
+JettonWalletResolver = Callable[[str, str], Awaitable[str]]
+
+
+def generate_query_id() -> int:
+    """Generate a unique query ID for Jetton transfers.
+
+    Returns:
+        Unique query ID based on timestamp
+    """
+    return int(time.time() * 1000000)
+
+
+class ExactTonClientScheme:
+    """Client scheme for TON exact payments using Jetton transfers.
+
+    Creates signed BOC messages that can be broadcast by a facilitator
+    to complete the payment.
+
+    Example:
+        ```python
+        scheme = ExactTonClientScheme(
+            signer=my_ton_signer,
+            get_jetton_wallet_address=my_resolver,
+        )
+
+        payload = await scheme.create_payment_payload(
+            t402_version=2,
+            requirements={
+                "scheme": "exact",
+                "network": "ton:mainnet",
+                "asset": "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs",
+                "amount": "1000000",
+                "payTo": "EQ...",
+                "maxTimeoutSeconds": 300,
+            },
+        )
+        ```
+    """
+
+    scheme = SCHEME_EXACT
+    caip_family = "ton:*"
+
+    def __init__(
+        self,
+        signer: TonSigner,
+        get_jetton_wallet_address: JettonWalletResolver,
+        gas_amount: Optional[int] = None,
+        forward_amount: Optional[int] = None,
+    ):
+        """Initialize the TON client scheme.
+
+        Args:
+            signer: TON signer for signing messages
+            get_jetton_wallet_address: Function to resolve Jetton wallet address
+            gas_amount: Override TON amount for gas (in nanoTON)
+            forward_amount: Override forward TON amount (in nanoTON)
+        """
+        self._signer = signer
+        self._get_jetton_wallet_address = get_jetton_wallet_address
+        self._gas_amount = gas_amount or DEFAULT_JETTON_TRANSFER_TON
+        self._forward_amount = forward_amount or DEFAULT_FORWARD_TON
+
+    @property
+    def address(self) -> str:
+        """Return the wallet address."""
+        return self._signer.address
+
+    async def create_payment_payload(
+        self,
+        t402_version: int,
+        requirements: Union[PaymentRequirementsV2, Dict[str, Any]],
+    ) -> Dict[str, Any]:
+        """Create a payment payload for TON Jetton transfer.
+
+        Args:
+            t402_version: Protocol version (1 or 2)
+            requirements: Payment requirements
+
+        Returns:
+            Payment payload with signed BOC and authorization metadata
+        """
+        # Convert to dict for easier access
+        if hasattr(requirements, "model_dump"):
+            req = requirements.model_dump(by_alias=True)
+        else:
+            req = dict(requirements)
+
+        # Extract fields
+        network = req.get("network", "")
+        asset = req.get("asset", "")
+        amount = req.get("amount", "0")
+        pay_to = req.get("payTo", "")
+        max_timeout = req.get("maxTimeoutSeconds", 300)
+
+        # Validate required fields
+        if not asset:
+            raise ValueError("Asset (Jetton master address) is required")
+        if not pay_to:
+            raise ValueError("PayTo address is required")
+        if not amount:
+            raise ValueError("Amount is required")
+        if not validate_ton_address(pay_to):
+            raise ValueError(f"Invalid payTo address: {pay_to}")
+
+        # Get sender's Jetton wallet address
+        sender_jetton_wallet = await self._get_jetton_wallet_address(
+            self._signer.address,
+            asset,
+        )
+
+        # Get current seqno for replay protection
+        seqno = await self._signer.get_seqno()
+
+        # Calculate validity period
+        now = int(time.time())
+        valid_until = now + max_timeout
+
+        # Generate unique query ID
+        query_id = generate_query_id()
+
+        # Parse amount
+        jetton_amount = int(amount)
+
+        # Build Jetton transfer body
+        jetton_body = self._build_jetton_transfer_body(
+            query_id=query_id,
+            amount=jetton_amount,
+            destination=pay_to,
+            response_destination=self._signer.address,
+            forward_amount=self._forward_amount,
+        )
+
+        # Sign the message
+        signed_message = await self._signer.sign_message(
+            to=sender_jetton_wallet,
+            value=self._gas_amount,
+            body=jetton_body,
+            timeout=max_timeout,
+        )
+
+        # Encode to base64
+        signed_boc = signed_message.to_boc_base64()
+
+        # Build authorization metadata
+        authorization = TonAuthorization(
+            from_=self._signer.address,
+            to=pay_to,
+            jetton_master=asset,
+            jetton_amount=str(jetton_amount),
+            ton_amount=str(self._gas_amount),
+            valid_until=valid_until,
+            seqno=seqno,
+            query_id=str(query_id),
+        )
+
+        # Build payload
+        payload_data = TonPaymentPayload(
+            signed_boc=signed_boc,
+            authorization=authorization,
+        )
+
+        if t402_version == T402_VERSION_V1:
+            return {
+                "t402Version": T402_VERSION_V1,
+                "scheme": self.scheme,
+                "network": network,
+                "payload": payload_data.model_dump(by_alias=True),
+            }
+
+        # V2 format
+        return {
+            "t402Version": T402_VERSION_V2,
+            "payload": payload_data.model_dump(by_alias=True),
+        }
+
+    def _build_jetton_transfer_body(
+        self,
+        query_id: int,
+        amount: int,
+        destination: str,
+        response_destination: str,
+        forward_amount: int,
+    ) -> bytes:
+        """Build Jetton transfer body as bytes.
+
+        This builds the TEP-74 Jetton transfer internal message body.
+
+        Args:
+            query_id: Unique query ID
+            amount: Jetton amount in smallest units
+            destination: Destination address
+            response_destination: Address for excess response
+            forward_amount: Forward TON amount
+
+        Returns:
+            Serialized message body as bytes
+
+        Note:
+            This returns a minimal placeholder. Real implementations should
+            use tonsdk or pytoniq to build proper BOC cells.
+        """
+        # Import here to avoid hard dependency
+        try:
+            from t402.ton import JETTON_TRANSFER_OP
+
+            # Build cell using available library
+            # This is a placeholder - real implementation needs tonsdk/pytoniq
+            #
+            # The actual cell structure should be:
+            # transfer#0f8a7ea5 query_id:uint64 amount:(VarUInteger 16)
+            #                   destination:MsgAddress response_destination:MsgAddress
+            #                   custom_payload:(Maybe ^Cell) forward_ton_amount:(VarUInteger 16)
+            #                   forward_payload:(Either Cell ^Cell) = InternalMsgBody;
+
+            # For now, return a placeholder that indicates the transfer params
+            # Real signers should handle cell building internally
+            import json
+
+            # Encode as JSON for testing/mocking purposes
+            # Real implementation would use proper BOC encoding
+            transfer_params = {
+                "op": JETTON_TRANSFER_OP,
+                "query_id": query_id,
+                "amount": amount,
+                "destination": destination,
+                "response_destination": response_destination,
+                "forward_amount": forward_amount,
+            }
+            return json.dumps(transfer_params).encode("utf-8")
+
+        except ImportError:
+            # Fallback if ton module not fully available
+            import json
+
+            transfer_params = {
+                "op": 0x0F8A7EA5,
+                "query_id": query_id,
+                "amount": amount,
+                "destination": destination,
+                "response_destination": response_destination,
+                "forward_amount": forward_amount,
+            }
+            return json.dumps(transfer_params).encode("utf-8")

t402/schemes/ton/exact/server.py

@@ -0,0 +1,201 @@
+"""TON Exact Scheme - Server Implementation.
+
+This module provides the server-side implementation of the exact payment scheme
+for TON network.
+"""
+
+from __future__ import annotations
+
+from decimal import Decimal
+from typing import Any, Dict, List, Union
+
+from t402.types import (
+    PaymentRequirementsV2,
+    Network,
+)
+from t402.schemes.interfaces import AssetAmount, SupportedKindDict
+from t402.ton import (
+    SCHEME_EXACT,
+    TON_MAINNET,
+    TON_TESTNET,
+    DEFAULT_DECIMALS,
+    get_network_config,
+    get_default_asset,
+    get_asset_info,
+)
+
+
+class ExactTonServerScheme:
+    """Server scheme for TON exact payments.
+
+    Handles parsing user-friendly prices and enhancing payment requirements
+    with TON-specific metadata for clients.
+
+    Example:
+        ```python
+        scheme = ExactTonServerScheme()
+
+        # Parse price
+        asset_amount = await scheme.parse_price("$0.10", "ton:mainnet")
+        # Returns: {"amount": "100000", "asset": "EQ...", "extra": {...}}
+
+        # Enhance requirements
+        enhanced = await scheme.enhance_requirements(
+            requirements,
+            supported_kind,
+            facilitator_extensions,
+        )
+        ```
+    """
+
+    scheme = SCHEME_EXACT
+    caip_family = "ton:*"
+
+    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 (TokenAmount): {"amount": "100000", "asset": "EQ..."}
+
+        Args:
+            price: User-friendly price
+            network: Network identifier (CAIP-2 format, e.g., "ton:mainnet")
+
+        Returns:
+            AssetAmount dict with amount, asset, and extra metadata
+        """
+        # Validate network
+        network_str = self._normalize_network(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 default asset (USDT) for the network
+        default_asset = get_default_asset(network_str)
+        if not default_asset:
+            raise ValueError(f"Unsupported TON network: {network}")
+
+        asset_address = default_asset["master_address"]
+        decimals = default_asset.get("decimals", DEFAULT_DECIMALS)
+
+        # 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))
+
+        # Build extra metadata
+        extra = {
+            "symbol": default_asset.get("symbol", "USDT"),
+            "name": default_asset.get("name", "Tether USD"),
+            "decimals": decimals,
+        }
+
+        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 TON-specific metadata.
+
+        Adds Jetton metadata to the extra field so clients can
+        properly build the transfer message.
+
+        Args:
+            requirements: Base payment requirements
+            supported_kind: Matched SupportedKind from facilitator
+            facilitator_extensions: Extensions supported by facilitator
+
+        Returns:
+            Enhanced requirements with TON metadata 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", "")
+
+        # Normalize network
+        network_str = self._normalize_network(network)
+
+        # Ensure extra exists
+        if "extra" not in req or req["extra"] is None:
+            req["extra"] = {}
+
+        # Add Jetton metadata if not present
+        asset_info = get_asset_info(network_str, asset)
+        if asset_info:
+            if "symbol" not in req["extra"]:
+                req["extra"]["symbol"] = asset_info.get("symbol", "UNKNOWN")
+            if "name" not in req["extra"]:
+                req["extra"]["name"] = asset_info.get("name", "Unknown Jetton")
+            if "decimals" not in req["extra"]:
+                req["extra"]["decimals"] = asset_info.get("decimals", DEFAULT_DECIMALS)
+
+        # Add network config info
+        network_config = get_network_config(network_str)
+        if network_config:
+            if "endpoint" not in req["extra"]:
+                req["extra"]["endpoint"] = network_config.get("endpoint", "")
+
+        # 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 _normalize_network(self, network: str) -> str:
+        """Normalize network identifier to CAIP-2 format.
+
+        Args:
+            network: Network identifier
+
+        Returns:
+            Normalized CAIP-2 network string
+
+        Raises:
+            ValueError: If network is not supported
+        """
+        # Already in CAIP-2 format
+        if network.startswith("ton:"):
+            if network in (TON_MAINNET, TON_TESTNET):
+                return network
+            raise ValueError(f"Unknown TON network: {network}")
+
+        # Handle legacy format
+        lower = network.lower()
+        if lower in ("mainnet", "ton-mainnet"):
+            return TON_MAINNET
+        elif lower in ("testnet", "ton-testnet"):
+            return TON_TESTNET
+
+        raise ValueError(f"Unknown network: {network}")

t402/schemes/tron/__init__.py

@@ -0,0 +1,22 @@
+"""TRON Blockchain Payment Schemes.
+
+This package provides payment scheme implementations for TRON blockchain.
+
+Supported schemes:
+- exact: TRC-20 token transfers with signed transactions
+"""
+
+from t402.schemes.tron.exact import (
+    ExactTronClientScheme,
+    ExactTronServerScheme,
+    TronSigner,
+    SCHEME_EXACT,
+)
+
+__all__ = [
+    # Exact scheme
+    "ExactTronClientScheme",
+    "ExactTronServerScheme",
+    "TronSigner",
+    "SCHEME_EXACT",
+]

t402/schemes/tron/exact/__init__.py

@@ -0,0 +1,27 @@
+"""TRON Exact Payment Scheme.
+
+This package provides the exact payment scheme implementation for TRON
+using TRC-20 token transfers.
+
+The exact scheme allows users to sign TRC-20 transfer transactions that
+can be verified and broadcast by a facilitator, enabling gasless payments.
+"""
+
+from t402.schemes.tron.exact.client import (
+    ExactTronClientScheme,
+    TronSigner,
+    SCHEME_EXACT,
+)
+from t402.schemes.tron.exact.server import (
+    ExactTronServerScheme,
+)
+
+__all__ = [
+    # Client
+    "ExactTronClientScheme",
+    "TronSigner",
+    # Server
+    "ExactTronServerScheme",
+    # Constants
+    "SCHEME_EXACT",
+]