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

t402/schemes/ton/upto/types.py

@@ -0,0 +1,215 @@
+"""TON Up-To Scheme Types.
+
+TON-specific types for the up-to payment scheme using an escrow pattern.
+The client transfers maxAmount to the facilitator's holding address,
+and the facilitator forwards settleAmount to payTo and refunds the rest.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+from pydantic import BaseModel, ConfigDict, Field
+from pydantic.alias_generators import to_camel
+
+
+class UptoTonAuthorization(BaseModel):
+    """TON upto authorization metadata.
+
+    Contains all parameters for verifying the signed transfer message.
+    """
+
+    from_address: str = Field(
+        alias="from",
+        description="Sender wallet address (friendly format, bounceable)",
+    )
+    facilitator: str = Field(
+        description="Facilitator holding address that receives the initial transfer",
+    )
+    jetton_master: str = Field(
+        alias="jettonMaster",
+        description="Jetton master contract address",
+    )
+    max_amount: str = Field(
+        alias="maxAmount",
+        description="Maximum authorized amount in smallest units",
+    )
+    ton_amount: str = Field(
+        alias="tonAmount",
+        description="Gas amount in nanoTON",
+    )
+    valid_until: int = Field(
+        alias="validUntil",
+        description="Unix timestamp (seconds) until which the message is valid",
+    )
+    seqno: int = Field(
+        description="Wallet sequence number for replay protection",
+    )
+    query_id: str = Field(
+        alias="queryId",
+        description="Unique message ID (as string for large numbers)",
+    )
+
+    model_config = ConfigDict(
+        alias_generator=to_camel,
+        populate_by_name=True,
+        from_attributes=True,
+    )
+
+
+class UptoTonPayload(BaseModel):
+    """TON upto payment payload.
+
+    Contains a signed transfer message to the facilitator's holding address.
+    The facilitator broadcasts the transfer, then forwards settleAmount to payTo
+    and refunds (maxAmount - settleAmount) back to the client.
+    """
+
+    signed_boc: str = Field(
+        alias="signedBoc",
+        description="Base64 encoded signed external message (BOC format)",
+    )
+    authorization: UptoTonAuthorization = Field(
+        description="Transfer authorization metadata for verification",
+    )
+    payment_nonce: str = Field(
+        alias="paymentNonce",
+        description="Unique nonce for replay protection (hex string)",
+    )
+
+    model_config = ConfigDict(
+        alias_generator=to_camel,
+        populate_by_name=True,
+        from_attributes=True,
+    )
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for JSON serialization.
+
+        Returns:
+            Dictionary with camelCase keys matching the wire format.
+        """
+        return {
+            "signedBoc": self.signed_boc,
+            "authorization": {
+                "from": self.authorization.from_address,
+                "facilitator": self.authorization.facilitator,
+                "jettonMaster": self.authorization.jetton_master,
+                "maxAmount": self.authorization.max_amount,
+                "tonAmount": self.authorization.ton_amount,
+                "validUntil": self.authorization.valid_until,
+                "seqno": self.authorization.seqno,
+                "queryId": self.authorization.query_id,
+            },
+            "paymentNonce": self.payment_nonce,
+        }
+
+
+class UptoTonExtra(BaseModel):
+    """TON-specific extra fields for the upto scheme.
+
+    Included in PaymentRequirements.extra to provide upto-specific parameters.
+    """
+
+    facilitator: Optional[str] = Field(
+        default=None,
+        description="Facilitator address that will receive the initial transfer",
+    )
+    max_amount: Optional[str] = Field(
+        default=None,
+        alias="maxAmount",
+        description="Maximum payment amount authorized",
+    )
+    min_amount: Optional[str] = Field(
+        default=None,
+        alias="minAmount",
+        description="Minimum acceptable settlement amount",
+    )
+    unit: Optional[str] = Field(
+        default=None,
+        description="Billing unit (e.g., 'token', 'request', 'second')",
+    )
+    unit_price: Optional[str] = Field(
+        default=None,
+        alias="unitPrice",
+        description="Price per unit in smallest denomination",
+    )
+
+    model_config = ConfigDict(
+        alias_generator=to_camel,
+        populate_by_name=True,
+        from_attributes=True,
+    )
+
+
+def is_upto_ton_payload(data: Any) -> bool:
+    """Check if the given data represents a TON upto payload.
+
+    Validates the presence and types of required fields including signedBoc,
+    authorization (with from, facilitator, jettonMaster, maxAmount), and paymentNonce.
+
+    Args:
+        data: Dictionary or object to check.
+
+    Returns:
+        True if data has the correct TON upto payload structure.
+    """
+    if not isinstance(data, dict):
+        return False
+
+    signed_boc = data.get("signedBoc")
+    payment_nonce = data.get("paymentNonce")
+    auth = data.get("authorization")
+
+    if not signed_boc or not isinstance(signed_boc, str):
+        return False
+    if not payment_nonce or not isinstance(payment_nonce, str):
+        return False
+
+    if not auth or not isinstance(auth, dict):
+        return False
+
+    # Check required authorization fields
+    required_str_fields = ["from", "facilitator", "jettonMaster", "maxAmount", "tonAmount", "queryId"]
+    for field in required_str_fields:
+        val = auth.get(field)
+        if not isinstance(val, str):
+            return False
+
+    # from and facilitator must not be empty
+    if not auth.get("from") or not auth.get("facilitator"):
+        return False
+
+    # Check numeric fields
+    if not isinstance(auth.get("validUntil"), (int, float)):
+        return False
+    if not isinstance(auth.get("seqno"), (int, float)):
+        return False
+
+    return True
+
+
+def upto_payload_from_dict(data: Dict[str, Any]) -> UptoTonPayload:
+    """Create an UptoTonPayload from a dictionary.
+
+    Args:
+        data: Dictionary containing payload data with camelCase keys.
+
+    Returns:
+        UptoTonPayload instance.
+    """
+    auth_data = data.get("authorization", {})
+
+    return UptoTonPayload(
+        signed_boc=data.get("signedBoc", ""),
+        authorization=UptoTonAuthorization(
+            from_address=auth_data.get("from", ""),
+            facilitator=auth_data.get("facilitator", ""),
+            jetton_master=auth_data.get("jettonMaster", ""),
+            max_amount=auth_data.get("maxAmount", ""),
+            ton_amount=auth_data.get("tonAmount", ""),
+            valid_until=auth_data.get("validUntil", 0),
+            seqno=auth_data.get("seqno", 0),
+            query_id=auth_data.get("queryId", ""),
+        ),
+        payment_nonce=data.get("paymentNonce", ""),
+    )

t402/schemes/tron/__init__.py

@@ -4,6 +4,7 @@ This package provides payment scheme implementations for TRON blockchain.
 
 Supported schemes:
 - exact: TRC-20 token transfers with signed transactions
+- upto: TRC-20 approve + transferFrom for authorized maximum-amount payments
 """
 
 from t402.schemes.tron.exact import (
@@ -16,16 +17,32 @@ from t402.schemes.tron.exact import (
     SCHEME_EXACT,
 )
 
+from t402.schemes.tron.upto import (
+    UptoTronAuthorization,
+    UptoTronPayload,
+    UptoTronExtra,
+    is_upto_tron_payload,
+    upto_payload_from_dict,
+)
+
 __all__ = [
-    # Client
+    # Exact - Client
     "ExactTronClientScheme",
     "TronSigner",
-    # Server
+    # Exact - Server
     "ExactTronServerScheme",
-    # Facilitator
+    # Exact - Facilitator
     "ExactTronFacilitatorScheme",
     "ExactTronFacilitatorConfig",
     "FacilitatorTronSigner",
-    # Constants
+    # Exact - Constants
     "SCHEME_EXACT",
+    # Upto - Types
+    "UptoTronAuthorization",
+    "UptoTronPayload",
+    "UptoTronExtra",
+    # Upto - Type guards
+    "is_upto_tron_payload",
+    # Upto - Helpers
+    "upto_payload_from_dict",
 ]

t402/schemes/tron/upto/__init__.py

@@ -0,0 +1,30 @@
+"""TRON Up-To Payment Scheme.
+
+This package provides the upto payment scheme types for TRON networks
+using TRC-20 approve + transferFrom for authorized maximum-amount payments.
+
+The upto scheme allows clients to authorize a maximum amount that can be
+settled later based on actual usage.
+"""
+
+from t402.schemes.tron.upto.types import (
+    # Models
+    UptoTronAuthorization,
+    UptoTronPayload,
+    UptoTronExtra,
+    # Type guards
+    is_upto_tron_payload,
+    # Helper functions
+    upto_payload_from_dict,
+)
+
+__all__ = [
+    # Types
+    "UptoTronAuthorization",
+    "UptoTronPayload",
+    "UptoTronExtra",
+    # Type guards
+    "is_upto_tron_payload",
+    # Helper functions
+    "upto_payload_from_dict",
+]

t402/schemes/tron/upto/types.py

@@ -0,0 +1,213 @@
+"""TRON Up-To Scheme Types.
+
+TRON-specific types for the up-to payment scheme using TRC-20 approve + transferFrom.
+The approve pattern allows the facilitator to execute a transferFrom up to the
+authorized maximum amount on behalf of the payer.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+from pydantic import BaseModel, ConfigDict, Field
+from pydantic.alias_generators import to_camel
+
+
+class UptoTronAuthorization(BaseModel):
+    """TRC-20 approve authorization metadata.
+
+    Contains all information needed to verify the approve transaction
+    without parsing the signed transaction.
+    """
+
+    owner: str = Field(description="Token owner address (T-prefix base58check)")
+    spender: str = Field(description="Approved spender address - facilitator (T-prefix base58check)")
+    contract_address: str = Field(
+        alias="contractAddress",
+        description="TRC-20 contract address (T-prefix base58check)",
+    )
+    max_amount: str = Field(
+        alias="maxAmount",
+        description="Maximum approved amount in smallest units (as string)",
+    )
+    expiration: int = Field(
+        description="Transaction expiration timestamp (milliseconds since epoch)",
+    )
+    ref_block_bytes: str = Field(
+        alias="refBlockBytes",
+        description="Reference block bytes (hex string)",
+    )
+    ref_block_hash: str = Field(
+        alias="refBlockHash",
+        description="Reference block hash (hex string)",
+    )
+    timestamp: int = Field(
+        description="Transaction timestamp (milliseconds since epoch)",
+    )
+
+    model_config = ConfigDict(
+        alias_generator=to_camel,
+        populate_by_name=True,
+        from_attributes=True,
+    )
+
+
+class UptoTronPayload(BaseModel):
+    """TRON upto payment payload.
+
+    Contains a signed TRC-20 approve transaction that authorizes the
+    facilitator to transfer up to maxAmount of tokens on behalf of the payer.
+    """
+
+    signed_transaction: str = Field(
+        alias="signedTransaction",
+        description="Hex-encoded signed approve transaction",
+    )
+    authorization: UptoTronAuthorization = Field(
+        description="Approve transaction authorization metadata",
+    )
+    payment_nonce: str = Field(
+        alias="paymentNonce",
+        description="Unique nonce for replay protection (hex string)",
+    )
+
+    model_config = ConfigDict(
+        alias_generator=to_camel,
+        populate_by_name=True,
+        from_attributes=True,
+    )
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for JSON serialization.
+
+        Returns:
+            Dictionary with camelCase keys matching the Go/TypeScript wire format.
+        """
+        return {
+            "signedTransaction": self.signed_transaction,
+            "authorization": {
+                "owner": self.authorization.owner,
+                "spender": self.authorization.spender,
+                "contractAddress": self.authorization.contract_address,
+                "maxAmount": self.authorization.max_amount,
+                "expiration": self.authorization.expiration,
+                "refBlockBytes": self.authorization.ref_block_bytes,
+                "refBlockHash": self.authorization.ref_block_hash,
+                "timestamp": self.authorization.timestamp,
+            },
+            "paymentNonce": self.payment_nonce,
+        }
+
+
+class UptoTronExtra(BaseModel):
+    """TRON-specific extra fields for upto payment requirements.
+
+    Included in the PaymentRequirements.extra field to communicate
+    upto-specific parameters to the client.
+    """
+
+    max_amount: Optional[str] = Field(
+        default=None,
+        alias="maxAmount",
+        description="Maximum payment amount authorized",
+    )
+    min_amount: Optional[str] = Field(
+        default=None,
+        alias="minAmount",
+        description="Minimum acceptable settlement amount",
+    )
+    unit: Optional[str] = Field(
+        default=None,
+        description="Billing unit (e.g., 'token', 'request', 'second')",
+    )
+    unit_price: Optional[str] = Field(
+        default=None,
+        alias="unitPrice",
+        description="Price per unit in smallest denomination",
+    )
+    spender_address: Optional[str] = Field(
+        default=None,
+        alias="spenderAddress",
+        description="Facilitator address that will be approved as spender",
+    )
+
+    model_config = ConfigDict(
+        alias_generator=to_camel,
+        populate_by_name=True,
+        from_attributes=True,
+    )
+
+
+def is_upto_tron_payload(data: Dict[str, Any]) -> bool:
+    """Check if the given data represents an upto TRON payload.
+
+    Validates that the data has the correct structure for a TRON upto
+    approve payload, including nested authorization fields.
+
+    Args:
+        data: Dictionary to check
+
+    Returns:
+        True if data has the correct upto TRON payload structure
+    """
+    if not isinstance(data, dict):
+        return False
+
+    # Check top-level fields
+    if not isinstance(data.get("signedTransaction"), str) or not data["signedTransaction"]:
+        return False
+
+    if not isinstance(data.get("paymentNonce"), str) or not data["paymentNonce"]:
+        return False
+
+    auth = data.get("authorization")
+    if not isinstance(auth, dict):
+        return False
+
+    # Check required authorization fields
+    required_string_fields = ["owner", "spender", "contractAddress", "maxAmount"]
+    for field in required_string_fields:
+        if not isinstance(auth.get(field), str) or not auth[field]:
+            return False
+
+    # Check numeric authorization fields
+    if not isinstance(auth.get("expiration"), (int, float)):
+        return False
+
+    if not isinstance(auth.get("timestamp"), (int, float)):
+        return False
+
+    # refBlockBytes and refBlockHash should be strings
+    if not isinstance(auth.get("refBlockBytes"), str):
+        return False
+
+    if not isinstance(auth.get("refBlockHash"), str):
+        return False
+
+    return True
+
+
+def upto_payload_from_dict(data: Dict[str, Any]) -> UptoTronPayload:
+    """Create an UptoTronPayload from a dictionary.
+
+    Args:
+        data: Dictionary containing payload data with camelCase keys
+
+    Returns:
+        UptoTronPayload instance
+    """
+    auth_data = data.get("authorization", {})
+
+    return UptoTronPayload(
+        signed_transaction=data.get("signedTransaction", ""),
+        authorization=UptoTronAuthorization(
+            owner=auth_data.get("owner", ""),
+            spender=auth_data.get("spender", ""),
+            contract_address=auth_data.get("contractAddress", ""),
+            max_amount=auth_data.get("maxAmount", ""),
+            expiration=auth_data.get("expiration", 0),
+            ref_block_bytes=auth_data.get("refBlockBytes", ""),
+            ref_block_hash=auth_data.get("refBlockHash", ""),
+            timestamp=auth_data.get("timestamp", 0),
+        ),
+        payment_nonce=data.get("paymentNonce", ""),
+    )

t402/starlette/__init__.py

@@ -0,0 +1,38 @@
+"""Starlette Integration for T402 Payment Protocol.
+
+This package provides Starlette ASGI middleware for integrating T402 payments
+into Starlette applications.
+
+Features:
+- PaymentMiddleware: Class-based middleware for protecting routes
+- V1 and V2 protocol support
+- Automatic settlement on successful responses
+- Browser paywall support
+
+Usage:
+    ```python
+    from starlette.applications import Starlette
+    from t402.starlette import PaymentMiddleware
+
+    app = Starlette()
+    payment = PaymentMiddleware(app)
+    payment.add(
+        path="/api/*",
+        price="$0.10",
+        pay_to_address="0x1234...",
+        network="eip155:8453",
+    )
+    ```
+"""
+
+from t402.starlette.middleware import (
+    PaymentMiddleware,
+    PaymentConfig,
+    PaymentDetails,
+)
+
+__all__ = [
+    "PaymentMiddleware",
+    "PaymentConfig",
+    "PaymentDetails",
+]