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

t402/schemes/tron/exact/client.py

@@ -0,0 +1,260 @@
+"""TRON Exact Scheme - Client Implementation.
+
+This module provides the client-side implementation of the exact payment scheme
+for TRON network using TRC-20 token transfers.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Dict, Optional, Protocol, Union
+
+from t402.types import (
+    PaymentRequirementsV2,
+    T402_VERSION_V1,
+    T402_VERSION_V2,
+)
+from t402.tron import (
+    TronAuthorization,
+    TronPaymentPayload,
+    DEFAULT_FEE_LIMIT,
+    validate_tron_address,
+)
+
+
+# Constants
+SCHEME_EXACT = "exact"
+
+
+class BlockInfo(Protocol):
+    """Protocol for TRON block reference info."""
+
+    @property
+    def ref_block_bytes(self) -> str:
+        """Reference block bytes (4 bytes hex)."""
+        ...
+
+    @property
+    def ref_block_hash(self) -> str:
+        """Reference block hash (8 bytes hex)."""
+        ...
+
+    @property
+    def expiration(self) -> int:
+        """Transaction expiration timestamp in milliseconds."""
+        ...
+
+
+class TronSigner(Protocol):
+    """Protocol for TRON wallet signing operations.
+
+    Implementations should provide wallet address, block info retrieval,
+    and transaction signing capabilities.
+
+    Example implementation with tronpy:
+        ```python
+        class MyTronSigner:
+            def __init__(self, private_key, client):
+                self._private_key = private_key
+                self._client = client
+                self._address = private_key_to_address(private_key)
+
+            @property
+            def address(self) -> str:
+                return self._address
+
+            async def get_block_info(self) -> BlockInfo:
+                block = await self._client.get_latest_block()
+                return {
+                    "ref_block_bytes": block.ref_block_bytes,
+                    "ref_block_hash": block.ref_block_hash,
+                    "expiration": int(time.time() * 1000) + 3600000,
+                }
+
+            async def sign_transaction(
+                self,
+                contract_address: str,
+                to: str,
+                amount: str,
+                fee_limit: int,
+                expiration: int,
+            ) -> str:
+                # Build and sign TRC-20 transfer transaction
+                return signed_transaction_hex
+        ```
+    """
+
+    @property
+    def address(self) -> str:
+        """Return the wallet address (T-prefix base58check)."""
+        ...
+
+    async def get_block_info(self) -> Dict[str, Any]:
+        """Get the current reference block info for transaction building.
+
+        Returns:
+            Dict with ref_block_bytes, ref_block_hash, and expiration
+        """
+        ...
+
+    async def sign_transaction(
+        self,
+        contract_address: str,
+        to: str,
+        amount: str,
+        fee_limit: int,
+        expiration: int,
+    ) -> str:
+        """Sign a TRC-20 transfer transaction.
+
+        Args:
+            contract_address: TRC-20 contract address
+            to: Recipient address
+            amount: Amount in smallest units
+            fee_limit: Fee limit in SUN
+            expiration: Transaction expiration in milliseconds
+
+        Returns:
+            Hex-encoded signed transaction
+        """
+        ...
+
+
+class ExactTronClientScheme:
+    """Client scheme for TRON exact payments using TRC-20 transfers.
+
+    Creates signed TRC-20 transfer transactions that can be verified and
+    broadcast by a facilitator to complete the payment.
+
+    Example:
+        ```python
+        scheme = ExactTronClientScheme(signer=my_tron_signer)
+
+        payload = await scheme.create_payment_payload(
+            t402_version=2,
+            requirements={
+                "scheme": "exact",
+                "network": "tron:mainnet",
+                "asset": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
+                "amount": "1000000",
+                "payTo": "TPayToAddress...",
+                "maxTimeoutSeconds": 300,
+            },
+        )
+        ```
+    """
+
+    scheme = SCHEME_EXACT
+    caip_family = "tron:*"
+
+    def __init__(
+        self,
+        signer: TronSigner,
+        fee_limit: Optional[int] = None,
+    ):
+        """Initialize the TRON client scheme.
+
+        Args:
+            signer: TRON signer for signing transactions
+            fee_limit: Override fee limit in SUN (default: 100 TRX)
+        """
+        self._signer = signer
+        self._fee_limit = fee_limit or DEFAULT_FEE_LIMIT
+
+    @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 TRC-20 transfer.
+
+        Args:
+            t402_version: Protocol version (1 or 2)
+            requirements: Payment requirements
+
+        Returns:
+            Payment payload with signed transaction 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 (TRC-20 contract address) is required")
+        if not pay_to:
+            raise ValueError("PayTo address is required")
+        if not amount:
+            raise ValueError("Amount is required")
+
+        # Validate addresses
+        if not validate_tron_address(asset):
+            raise ValueError(f"Invalid TRC-20 contract address: {asset}")
+        if not validate_tron_address(pay_to):
+            raise ValueError(f"Invalid payTo address: {pay_to}")
+        if not validate_tron_address(self._signer.address):
+            raise ValueError(f"Invalid signer address: {self._signer.address}")
+
+        # Get block info for transaction
+        block_info = await self._signer.get_block_info()
+        ref_block_bytes = block_info.get("ref_block_bytes", "")
+        ref_block_hash = block_info.get("ref_block_hash", "")
+
+        # Calculate expiration
+        now_ms = int(time.time() * 1000)
+        expiration = block_info.get("expiration") or (now_ms + max_timeout * 1000)
+
+        # Sign the transaction
+        signed_transaction = await self._signer.sign_transaction(
+            contract_address=asset,
+            to=pay_to,
+            amount=amount,
+            fee_limit=self._fee_limit,
+            expiration=expiration,
+        )
+
+        # Build authorization metadata
+        authorization = TronAuthorization(
+            from_=self._signer.address,
+            to=pay_to,
+            contract_address=asset,
+            amount=amount,
+            expiration=expiration,
+            ref_block_bytes=ref_block_bytes,
+            ref_block_hash=ref_block_hash,
+            timestamp=now_ms,
+        )
+
+        # Build payload
+        payload_data = TronPaymentPayload(
+            signed_transaction=signed_transaction,
+            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),
+        }

t402/schemes/tron/exact/server.py

@@ -0,0 +1,192 @@
+"""TRON Exact Scheme - Server Implementation.
+
+This module provides the server-side implementation of the exact payment scheme
+for TRON 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.tron import (
+    SCHEME_EXACT,
+    DEFAULT_DECIMALS,
+    get_network_config,
+    get_default_asset,
+    get_asset_info,
+    normalize_network as tron_normalize_network,
+)
+
+
+class ExactTronServerScheme:
+    """Server scheme for TRON exact payments.
+
+    Handles parsing user-friendly prices and enhancing payment requirements
+    with TRON-specific metadata for clients.
+
+    Example:
+        ```python
+        scheme = ExactTronServerScheme()
+
+        # Parse price
+        asset_amount = await scheme.parse_price("$0.10", "tron:mainnet")
+        # Returns: {"amount": "100000", "asset": "TR7N...", "extra": {...}}
+
+        # Enhance requirements
+        enhanced = await scheme.enhance_requirements(
+            requirements,
+            supported_kind,
+            facilitator_extensions,
+        )
+        ```
+    """
+
+    scheme = SCHEME_EXACT
+    caip_family = "tron:*"
+
+    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": "TR7N..."}
+
+        Args:
+            price: User-friendly price
+            network: Network identifier (CAIP-2 format, e.g., "tron:mainnet")
+
+        Returns:
+            AssetAmount dict with amount, asset, and extra metadata
+        """
+        # Normalize 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 TRON network: {network}")
+
+        asset_address = default_asset["contract_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 TRON-specific metadata.
+
+        Adds TRC-20 token metadata to the extra field so clients can
+        properly build the transfer transaction.
+
+        Args:
+            requirements: Base payment requirements
+            supported_kind: Matched SupportedKind from facilitator
+            facilitator_extensions: Extensions supported by facilitator
+
+        Returns:
+            Enhanced requirements with TRON 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 TRC-20 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 TRC20")
+            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
+        """
+        # Use the tron module's normalize function
+        try:
+            return tron_normalize_network(network)
+        except ValueError:
+            # Re-raise with consistent error message
+            raise ValueError(f"Unknown TRON network: {network}")

t402/schemes/upto/__init__.py

@@ -0,0 +1,80 @@
+"""Up-To Payment Scheme.
+
+The upto scheme authorizes transfer of up to a maximum amount,
+enabling usage-based billing where the final settlement amount
+is determined by actual usage.
+
+This is useful for:
+- AI inference billing (pay per token)
+- Metered API access (pay per request)
+- Streaming services (pay per second/minute)
+- Data transfer (pay per byte)
+
+Example:
+    ```python
+    from t402.schemes.upto import (
+        UptoPaymentRequirements,
+        UptoSettlement,
+        create_payment_requirements,
+        create_settlement,
+    )
+
+    # Server specifies requirements
+    requirements = create_payment_requirements(
+        network="eip155:8453",
+        max_amount="1000000",  # $1.00 max
+        asset="0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+        pay_to="0x...",
+    )
+
+    # After service delivery, settle for actual usage
+    settlement = create_settlement(
+        settle_amount="150000",  # $0.15 actual
+        units_consumed=1500,
+        unit_price="100",
+        unit_type="token",
+    )
+    ```
+"""
+
+from t402.schemes.upto.types import (
+    # Constants
+    SCHEME_UPTO,
+    DEFAULT_MIN_AMOUNT,
+    DEFAULT_MAX_TIMEOUT_SECONDS,
+    SUPPORTED_UNITS,
+    # Models
+    UptoExtra,
+    UptoPaymentRequirements,
+    UptoUsageDetails,
+    UptoSettlement,
+    UptoSettlementResponse,
+    UptoValidationResult,
+    # Type guards
+    is_upto_payment_requirements,
+    is_valid_unit,
+    # Factory functions
+    create_payment_requirements,
+    create_settlement,
+)
+
+__all__ = [
+    # Constants
+    "SCHEME_UPTO",
+    "DEFAULT_MIN_AMOUNT",
+    "DEFAULT_MAX_TIMEOUT_SECONDS",
+    "SUPPORTED_UNITS",
+    # Models
+    "UptoExtra",
+    "UptoPaymentRequirements",
+    "UptoUsageDetails",
+    "UptoSettlement",
+    "UptoSettlementResponse",
+    "UptoValidationResult",
+    # Type guards
+    "is_upto_payment_requirements",
+    "is_valid_unit",
+    # Factory functions
+    "create_payment_requirements",
+    "create_settlement",
+]