t402 1.6.1__py3-none-any.whl → 1.7.1__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/types.py

@@ -12,6 +12,14 @@ from pydantic.alias_generators import to_camel
 
 from t402.networks import SupportedNetworks
 
+# Protocol version constants
+T402_VERSION_V1 = 1
+T402_VERSION_V2 = 2
+T402_VERSION = T402_VERSION_V2  # Current default version
+
+# Network type alias (CAIP-2 format: "namespace:reference")
+Network = str  # e.g., "eip155:1", "solana:mainnet", "ton:mainnet"
+
 
 # Add HTTP request structure types
 class HTTPVerbs(str, Enum):
@@ -93,7 +101,14 @@ Money = Union[str, int]  # e.g., "$0.01", 0.01, "0.001"
 Price = Union[Money, TokenAmount]
 
 
-class PaymentRequirements(BaseModel):
+# =============================================================================
+# V1 Types (Legacy - for backward compatibility)
+# =============================================================================
+
+
+class PaymentRequirementsV1(BaseModel):
+    """V1 Payment Requirements - Legacy format."""
+
     scheme: str
     network: SupportedNetworks
     max_amount_required: str
@@ -123,10 +138,15 @@ class PaymentRequirements(BaseModel):
         return v
 
 
-# Returned by a server as json alongside a 402 response code
-class t402PaymentRequiredResponse(BaseModel):
-    t402_version: int
-    accepts: list[PaymentRequirements]
+# Alias for backward compatibility
+PaymentRequirements = PaymentRequirementsV1
+
+
+class t402PaymentRequiredResponseV1(BaseModel):
+    """V1 Payment Required Response - Legacy format (returned in response body)."""
+
+    t402_version: int = Field(default=T402_VERSION_V1, alias="t402Version")
+    accepts: list[PaymentRequirementsV1]
     error: str
 
     model_config = ConfigDict(
@@ -136,6 +156,80 @@ class t402PaymentRequiredResponse(BaseModel):
     )
 
 
+# Alias for backward compatibility
+t402PaymentRequiredResponse = t402PaymentRequiredResponseV1
+
+
+# =============================================================================
+# V2 Types (Current Protocol Version)
+# =============================================================================
+
+
+class ResourceInfo(BaseModel):
+    """Resource information for V2 protocol.
+
+    Contains metadata about the protected resource.
+    """
+
+    url: str
+    description: str = ""
+    mime_type: str = Field(default="", alias="mimeType")
+
+    model_config = ConfigDict(
+        alias_generator=to_camel,
+        populate_by_name=True,
+        from_attributes=True,
+    )
+
+
+class PaymentRequirementsV2(BaseModel):
+    """V2 Payment Requirements - Current format.
+
+    Represents a single payment option that a client can use to pay for access.
+    """
+
+    scheme: str
+    network: Network
+    asset: str
+    amount: str
+    pay_to: str = Field(alias="payTo")
+    max_timeout_seconds: int = Field(alias="maxTimeoutSeconds")
+    extra: dict[str, Any] = Field(default_factory=dict)
+
+    model_config = ConfigDict(
+        alias_generator=to_camel,
+        populate_by_name=True,
+        from_attributes=True,
+    )
+
+    @field_validator("amount")
+    def validate_amount(cls, v):
+        try:
+            int(v)
+        except ValueError:
+            raise ValueError("amount must be an integer encoded as a string")
+        return v
+
+
+class PaymentRequiredV2(BaseModel):
+    """V2 Payment Required Response - Current format.
+
+    Returned in the PAYMENT-REQUIRED header as base64-encoded JSON.
+    """
+
+    t402_version: int = Field(default=T402_VERSION_V2, alias="t402Version")
+    resource: ResourceInfo
+    accepts: list[PaymentRequirementsV2]
+    error: Optional[str] = None
+    extensions: Optional[dict[str, Any]] = None
+
+    model_config = ConfigDict(
+        alias_generator=to_camel,
+        populate_by_name=True,
+        from_attributes=True,
+    )
+
+
 class ExactPaymentPayload(BaseModel):
     signature: str
     authorization: EIP3009Authorization
@@ -258,7 +352,7 @@ class VerifyResponse(BaseModel):
 
 class SettleResponse(BaseModel):
     success: bool
-    error_reason: Optional[str] = None
+    error_reason: Optional[str] = Field(None, alias="errorReason")
     transaction: Optional[str] = None
     network: Optional[str] = None
     payer: Optional[str] = None
@@ -270,12 +364,65 @@ class SettleResponse(BaseModel):
     )
 
 
+class PaymentResponseV2(BaseModel):
+    """V2 Payment Response - returned in PAYMENT-RESPONSE header after settlement."""
+
+    success: bool
+    error_reason: Optional[str] = Field(None, alias="errorReason")
+    payer: Optional[str] = None
+    transaction: str
+    network: Network
+    requirements: PaymentRequirementsV2
+
+    model_config = ConfigDict(
+        alias_generator=to_camel,
+        populate_by_name=True,
+        from_attributes=True,
+    )
+
+
+# =============================================================================
+# Facilitator Types
+# =============================================================================
+
+
+class SupportedKind(BaseModel):
+    """A single supported scheme/network combination from the facilitator."""
+
+    t402_version: int = Field(alias="t402Version")
+    scheme: str
+    network: Network
+    extra: Optional[dict[str, Any]] = None
+
+    model_config = ConfigDict(
+        alias_generator=to_camel,
+        populate_by_name=True,
+        from_attributes=True,
+    )
+
+
+class SupportedResponse(BaseModel):
+    """Response from facilitator's /supported endpoint."""
+
+    kinds: list[SupportedKind]
+    extensions: list[str] = Field(default_factory=list)
+    signers: dict[str, list[str]] = Field(default_factory=dict)  # CAIP family → addresses
+
+    model_config = ConfigDict(
+        alias_generator=to_camel,
+        populate_by_name=True,
+        from_attributes=True,
+    )
+
+
 # Union of payloads for each scheme
 SchemePayloads = Union[ExactPaymentPayload, TonPaymentPayload, TronPaymentPayload]
 
 
-class PaymentPayload(BaseModel):
-    t402_version: int
+class PaymentPayloadV1(BaseModel):
+    """V1 Payment Payload - Legacy format."""
+
+    t402_version: int = Field(default=T402_VERSION_V1, alias="t402Version")
     scheme: str
     network: str
     payload: SchemePayloads
@@ -287,6 +434,29 @@ class PaymentPayload(BaseModel):
     )
 
 
+# Alias for backward compatibility
+PaymentPayload = PaymentPayloadV1
+
+
+class PaymentPayloadV2(BaseModel):
+    """V2 Payment Payload - Current format.
+
+    Sent in the PAYMENT-SIGNATURE header as base64-encoded JSON.
+    """
+
+    t402_version: int = Field(default=T402_VERSION_V2, alias="t402Version")
+    resource: ResourceInfo
+    accepted: PaymentRequirementsV2
+    payload: dict[str, Any]
+    extensions: Optional[dict[str, Any]] = None
+
+    model_config = ConfigDict(
+        alias_generator=to_camel,
+        populate_by_name=True,
+        from_attributes=True,
+    )
+
+
 class T402Headers(BaseModel):
     x_payment: str
 

{t402-1.6.1.dist-info → t402-1.7.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: t402
-Version: 1.6.1
+Version: 1.7.1
 Summary: t402: An internet native payments protocol
 Author-email: T402 Team <dev@t402.io>
 License: Apache-2.0