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

t402/schemes/near/upto/types.py

@@ -0,0 +1,272 @@
+"""NEAR Up-To Scheme Types.
+
+NEAR-specific types for the up-to payment scheme using an escrow pattern.
+Since NEAR NEP-141 tokens don't have native approve/transferFrom, the client
+ft_transfers maxAmount to the facilitator, who then forwards settleAmount
+to the payTo address 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 UptoNearAuthorization(BaseModel):
+    """Authorization metadata for NEAR upto payments.
+
+    Contains the transfer details needed for verification.
+
+    Attributes:
+        from_account: Sender's NEAR account ID.
+        facilitator: Facilitator's NEAR account ID that receives the transfer.
+        token_contract: NEP-141 token contract ID.
+        max_amount: Maximum authorized amount in smallest units (as string).
+    """
+
+    from_account: str = Field(alias="from", description="Sender's NEAR account ID")
+    facilitator: str = Field(description="Facilitator's NEAR account ID")
+    token_contract: str = Field(
+        alias="tokenContract",
+        description="NEP-141 token contract ID",
+    )
+    max_amount: str = Field(
+        alias="maxAmount",
+        description="Maximum authorized amount in smallest units",
+    )
+
+    model_config = ConfigDict(
+        alias_generator=to_camel,
+        populate_by_name=True,
+        from_attributes=True,
+    )
+
+
+class UptoNearPayload(BaseModel):
+    """NEAR upto payment payload.
+
+    Contains the transaction hash of the client's transfer to the facilitator,
+    along with authorization metadata for verification.
+
+    Attributes:
+        tx_hash: NEAR transaction hash of the transfer to facilitator.
+        authorization: Authorization metadata for verification.
+        payment_nonce: Unique nonce for replay protection (hex string).
+    """
+
+    tx_hash: str = Field(
+        alias="txHash",
+        description="NEAR transaction hash of the transfer to facilitator",
+    )
+    authorization: UptoNearAuthorization = Field(
+        description="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:
+            Dict with camelCase keys matching the Go/TypeScript field names.
+        """
+        return {
+            "txHash": self.tx_hash,
+            "authorization": {
+                "from": self.authorization.from_account,
+                "facilitator": self.authorization.facilitator,
+                "tokenContract": self.authorization.token_contract,
+                "maxAmount": self.authorization.max_amount,
+            },
+            "paymentNonce": self.payment_nonce,
+        }
+
+
+class UptoNearExtra(BaseModel):
+    """NEAR-specific extra fields for the upto scheme.
+
+    Included in the PaymentRequirements.extra field to provide
+    additional parameters needed for the upto payment flow.
+
+    Attributes:
+        facilitator: Facilitator account ID that will receive the initial transfer.
+        max_amount: Maximum payment amount authorized.
+        min_amount: Minimum acceptable settlement amount.
+        unit: Billing unit (e.g., "token", "request", "second").
+        unit_price: Price per unit in smallest denomination.
+    """
+
+    facilitator: Optional[str] = Field(
+        default=None,
+        description="Facilitator account ID 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,
+    )
+
+
+class UptoNearUsageDetails(BaseModel):
+    """Usage details for NEAR upto settlement.
+
+    Attributes:
+        units_consumed: Number of units consumed.
+        unit_price: Price per unit used.
+        unit_type: Type of unit.
+        start_time: Start timestamp.
+        end_time: End timestamp.
+    """
+
+    units_consumed: Optional[int] = Field(
+        default=None,
+        alias="unitsConsumed",
+        description="Number of units consumed",
+    )
+    unit_price: Optional[str] = Field(
+        default=None,
+        alias="unitPrice",
+        description="Price per unit used",
+    )
+    unit_type: Optional[str] = Field(
+        default=None,
+        alias="unitType",
+        description="Type of unit",
+    )
+    start_time: Optional[int] = Field(
+        default=None,
+        alias="startTime",
+        description="Start timestamp",
+    )
+    end_time: Optional[int] = Field(
+        default=None,
+        alias="endTime",
+        description="End timestamp",
+    )
+
+    model_config = ConfigDict(
+        alias_generator=to_camel,
+        populate_by_name=True,
+        from_attributes=True,
+    )
+
+
+class UptoNearSettlement(BaseModel):
+    """NEAR-specific settlement request for the upto scheme.
+
+    Attributes:
+        settle_amount: Actual amount to settle (must be <= maxAmount).
+        usage_details: Optional usage information for auditing.
+    """
+
+    settle_amount: str = Field(
+        alias="settleAmount",
+        description="Actual amount to settle",
+    )
+    usage_details: Optional[UptoNearUsageDetails] = Field(
+        default=None,
+        alias="usageDetails",
+        description="Optional usage information",
+    )
+
+    model_config = ConfigDict(
+        alias_generator=to_camel,
+        populate_by_name=True,
+        from_attributes=True,
+    )
+
+
+def is_upto_near_payload(data: Dict[str, Any]) -> bool:
+    """Check if the given data represents a NEAR upto payload.
+
+    Distinguishes upto payloads from exact-direct payloads by checking
+    for the authorization structure with facilitator field.
+
+    Args:
+        data: Dictionary to check.
+
+    Returns:
+        True if data has the correct NEAR upto payload structure.
+    """
+    if not isinstance(data, dict):
+        return False
+
+    tx_hash = data.get("txHash")
+    payment_nonce = data.get("paymentNonce")
+    auth = data.get("authorization")
+
+    if not tx_hash or not isinstance(tx_hash, 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 authorization structure
+    required_auth_fields = ["from", "facilitator", "tokenContract", "maxAmount"]
+    if not all(k in auth for k in required_auth_fields):
+        return False
+
+    # Ensure from and facilitator are non-empty strings
+    if not auth.get("from") or not isinstance(auth["from"], str):
+        return False
+    if not auth.get("facilitator") or not isinstance(auth["facilitator"], str):
+        return False
+
+    return True
+
+
+def upto_payload_from_dict(data: Dict[str, Any]) -> UptoNearPayload:
+    """Create an UptoNearPayload from a dictionary.
+
+    Args:
+        data: Dictionary containing payload data with camelCase keys.
+
+    Returns:
+        UptoNearPayload instance.
+
+    Raises:
+        ValueError: If required fields are missing or invalid.
+    """
+    auth_data = data.get("authorization", {})
+
+    return UptoNearPayload(
+        tx_hash=data.get("txHash", ""),
+        authorization=UptoNearAuthorization(
+            from_account=auth_data.get("from", ""),
+            facilitator=auth_data.get("facilitator", ""),
+            token_contract=auth_data.get("tokenContract", ""),
+            max_amount=auth_data.get("maxAmount", ""),
+        ),
+        payment_nonce=data.get("paymentNonce", ""),
+    )

t402/schemes/svm/__init__.py

@@ -4,6 +4,7 @@ This package provides payment scheme implementations for Solana blockchain.
 
 Supported schemes:
 - exact: SPL Token TransferChecked with facilitator fee payer
+- upto: SPL Token ApproveChecked with delegated transferFrom
 """
 
 from t402.schemes.svm.exact import (
@@ -15,6 +16,14 @@ from t402.schemes.svm.exact import (
     SCHEME_EXACT,
 )
 
+from t402.schemes.svm.upto import (
+    UptoSvmAuthorization,
+    UptoSvmPayload,
+    UptoSvmExtra,
+    is_upto_svm_payload,
+    upto_payload_from_dict,
+)
+
 __all__ = [
     # Client
     "ExactSvmClientScheme",
@@ -26,4 +35,10 @@ __all__ = [
     "FacilitatorSvmSigner",
     # Constants
     "SCHEME_EXACT",
+    # Upto types
+    "UptoSvmAuthorization",
+    "UptoSvmPayload",
+    "UptoSvmExtra",
+    "is_upto_svm_payload",
+    "upto_payload_from_dict",
 ]

t402/schemes/svm/upto/__init__.py

@@ -0,0 +1,23 @@
+"""Solana SVM Up-To Payment Scheme Types.
+
+This package provides types for the upto payment scheme on Solana
+using SPL ApproveChecked. The client approves the facilitator (delegate)
+to transfer up to maxAmount of tokens from the client's associated
+token account.
+"""
+
+from t402.schemes.svm.upto.types import (
+    UptoSvmAuthorization,
+    UptoSvmPayload,
+    UptoSvmExtra,
+    upto_payload_from_dict,
+    is_upto_svm_payload,
+)
+
+__all__ = [
+    "UptoSvmAuthorization",
+    "UptoSvmPayload",
+    "UptoSvmExtra",
+    "upto_payload_from_dict",
+    "is_upto_svm_payload",
+]

t402/schemes/svm/upto/types.py

@@ -0,0 +1,193 @@
+"""Solana SVM Up-To Scheme Types.
+
+SVM-specific types for the up-to payment scheme using SPL ApproveChecked.
+The client signs an approve transaction that authorizes the facilitator
+to transfer up to maxAmount tokens from the client's ATA.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+from pydantic.alias_generators import to_camel
+
+
+class UptoSvmAuthorization(BaseModel):
+    """SPL ApproveChecked authorization metadata.
+
+    Contains the details of the delegate approval including the owner,
+    delegate (facilitator), token mint, maximum amount, and source ATA.
+    """
+
+    owner: str = Field(description="Token owner address (base58)")
+    delegate: str = Field(description="Approved delegate address - facilitator (base58)")
+    mint: str = Field(description="SPL token mint address (base58)")
+    max_amount: str = Field(
+        alias="maxAmount",
+        description="Maximum approved amount in smallest units (as string)",
+    )
+    source_ata: str = Field(
+        alias="sourceATA",
+        description="Owner's associated token account (base58)",
+    )
+
+    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."""
+        return {
+            "owner": self.owner,
+            "delegate": self.delegate,
+            "mint": self.mint,
+            "maxAmount": self.max_amount,
+            "sourceATA": self.source_ata,
+        }
+
+
+class UptoSvmPayload(BaseModel):
+    """Up-to SVM payment payload containing a signed approve transaction.
+
+    The facilitator uses the delegated authority to transfer tokens
+    up to the approved maxAmount.
+    """
+
+    transaction: str = Field(description="Base64 encoded signed approve transaction")
+    authorization: UptoSvmAuthorization = Field(
+        description="Approval 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."""
+        return {
+            "transaction": self.transaction,
+            "authorization": self.authorization.to_dict(),
+            "paymentNonce": self.payment_nonce,
+        }
+
+
+class UptoSvmExtra(BaseModel):
+    """SVM-specific extra fields for the upto scheme.
+
+    Included in the PaymentRequirements.extra field to provide
+    billing configuration for upto payments.
+    """
+
+    fee_payer: Optional[str] = Field(
+        default=None,
+        alias="feePayer",
+        description="Facilitator address that will pay transaction fees (base58)",
+    )
+    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 upto_payload_from_dict(data: Dict[str, Any]) -> UptoSvmPayload:
+    """Create an UptoSvmPayload from a dictionary.
+
+    Args:
+        data: Dictionary containing payload data with keys:
+            - transaction: base64 encoded transaction
+            - authorization: dict with owner, delegate, mint, maxAmount, sourceATA
+            - paymentNonce: hex string nonce
+
+    Returns:
+        UptoSvmPayload instance
+
+    Raises:
+        ValueError: If required fields are missing
+    """
+    auth_data = data.get("authorization", {})
+    if not isinstance(auth_data, dict):
+        raise ValueError("authorization must be a dictionary")
+
+    transaction = data.get("transaction")
+    if not isinstance(transaction, str) or not transaction:
+        raise ValueError("missing or invalid transaction field")
+
+    payment_nonce = data.get("paymentNonce")
+    if not isinstance(payment_nonce, str) or not payment_nonce:
+        raise ValueError("missing or invalid paymentNonce field")
+
+    owner = auth_data.get("owner")
+    if not isinstance(owner, str) or not owner:
+        raise ValueError("missing or invalid authorization.owner field")
+
+    delegate = auth_data.get("delegate")
+    if not isinstance(delegate, str) or not delegate:
+        raise ValueError("missing or invalid authorization.delegate field")
+
+    return UptoSvmPayload(
+        transaction=transaction,
+        authorization=UptoSvmAuthorization(
+            owner=owner,
+            delegate=delegate,
+            mint=auth_data.get("mint", ""),
+            max_amount=auth_data.get("maxAmount", ""),
+            source_ata=auth_data.get("sourceATA", ""),
+        ),
+        payment_nonce=payment_nonce,
+    )
+
+
+def is_upto_svm_payload(data: Any) -> bool:
+    """Check if the given data represents an SVM upto payload.
+
+    Args:
+        data: Data to check
+
+    Returns:
+        True if data has the correct SVM upto payload structure
+    """
+    if not isinstance(data, dict):
+        return False
+
+    if not isinstance(data.get("transaction"), str):
+        return False
+
+    if not isinstance(data.get("paymentNonce"), str):
+        return False
+
+    auth = data.get("authorization")
+    if not isinstance(auth, dict):
+        return False
+
+    required_fields = ["owner", "delegate", "mint", "maxAmount", "sourceATA"]
+    return all(isinstance(auth.get(f), str) for f in required_fields)

t402/schemes/ton/__init__.py

@@ -4,6 +4,7 @@ This package provides payment scheme implementations for TON blockchain.
 
 Supported schemes:
 - exact: Jetton TransferWithAuthorization
+- upto: Escrow-based usage billing (maxAmount to facilitator, settle + refund)
 """
 
 from t402.schemes.ton.exact import (
@@ -15,6 +16,14 @@ from t402.schemes.ton.exact import (
     SCHEME_EXACT,
 )
 
+from t402.schemes.ton.upto import (
+    UptoTonAuthorization,
+    UptoTonPayload,
+    UptoTonExtra,
+    is_upto_ton_payload,
+    upto_payload_from_dict,
+)
+
 __all__ = [
     # Client
     "ExactTonClientScheme",
@@ -26,4 +35,10 @@ __all__ = [
     "FacilitatorTonSigner",
     # Constants
     "SCHEME_EXACT",
+    # Upto types
+    "UptoTonAuthorization",
+    "UptoTonPayload",
+    "UptoTonExtra",
+    "is_upto_ton_payload",
+    "upto_payload_from_dict",
 ]

t402/schemes/ton/upto/__init__.py

@@ -0,0 +1,31 @@
+"""TON Up-To Payment Scheme.
+
+This package provides types for the upto payment scheme on TON blockchain.
+
+The upto scheme uses an escrow pattern:
+1. Client signs a transfer of maxAmount to the facilitator's holding address
+2. Facilitator broadcasts the transfer, then sends settleAmount to payTo
+   and refunds (maxAmount - settleAmount) back to the client.
+"""
+
+from t402.schemes.ton.upto.types import (
+    # Models
+    UptoTonAuthorization,
+    UptoTonPayload,
+    UptoTonExtra,
+    # Type guards
+    is_upto_ton_payload,
+    # Helper functions
+    upto_payload_from_dict,
+)
+
+__all__ = [
+    # Types
+    "UptoTonAuthorization",
+    "UptoTonPayload",
+    "UptoTonExtra",
+    # Type guards
+    "is_upto_ton_payload",
+    # Helper functions
+    "upto_payload_from_dict",
+]