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

t402/schemes/svm/__init__.py

@@ -0,0 +1,44 @@
+"""Solana SVM Blockchain Payment Schemes.
+
+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 (
+    ExactSvmClientScheme,
+    ExactSvmServerScheme,
+    ExactSvmFacilitatorScheme,
+    ClientSvmSigner,
+    FacilitatorSvmSigner,
+    SCHEME_EXACT,
+)
+
+from t402.schemes.svm.upto import (
+    UptoSvmAuthorization,
+    UptoSvmPayload,
+    UptoSvmExtra,
+    is_upto_svm_payload,
+    upto_payload_from_dict,
+)
+
+__all__ = [
+    # Client
+    "ExactSvmClientScheme",
+    "ClientSvmSigner",
+    # Server
+    "ExactSvmServerScheme",
+    # Facilitator
+    "ExactSvmFacilitatorScheme",
+    "FacilitatorSvmSigner",
+    # Constants
+    "SCHEME_EXACT",
+    # Upto types
+    "UptoSvmAuthorization",
+    "UptoSvmPayload",
+    "UptoSvmExtra",
+    "is_upto_svm_payload",
+    "upto_payload_from_dict",
+]

t402/schemes/svm/exact/__init__.py

@@ -0,0 +1,35 @@
+"""Solana SVM Exact Payment Scheme.
+
+This package provides the exact payment scheme implementation for Solana
+using SPL Token TransferChecked instructions with a facilitator fee payer.
+
+The exact scheme allows users to sign transactions that transfer SPL tokens
+to a recipient. The facilitator pays for gas (transaction fees) and broadcasts
+the transaction.
+"""
+
+from t402.schemes.svm.exact.client import (
+    ExactSvmClientScheme,
+    ClientSvmSigner,
+    SCHEME_EXACT,
+)
+from t402.schemes.svm.exact.server import (
+    ExactSvmServerScheme,
+)
+from t402.schemes.svm.exact.facilitator import (
+    ExactSvmFacilitatorScheme,
+    FacilitatorSvmSigner,
+)
+
+__all__ = [
+    # Client
+    "ExactSvmClientScheme",
+    "ClientSvmSigner",
+    # Server
+    "ExactSvmServerScheme",
+    # Facilitator
+    "ExactSvmFacilitatorScheme",
+    "FacilitatorSvmSigner",
+    # Constants
+    "SCHEME_EXACT",
+]

t402/schemes/svm/exact/client.py

@@ -0,0 +1,23 @@
+"""Solana SVM Exact Scheme - Client Implementation.
+
+This module provides the client-side implementation of the exact payment scheme
+for Solana network using SPL Token TransferChecked instructions.
+
+The client creates and signs a Solana transaction containing a TransferChecked
+instruction, which the facilitator then co-signs (as fee payer) and broadcasts.
+
+This module re-exports the client implementation from the monolithic svm module,
+providing the standard scheme package structure.
+"""
+
+from t402.svm import (
+    SCHEME_EXACT,
+    ExactSvmClientScheme,
+    ClientSvmSigner,
+)
+
+__all__ = [
+    "SCHEME_EXACT",
+    "ExactSvmClientScheme",
+    "ClientSvmSigner",
+]

t402/schemes/svm/exact/facilitator.py

@@ -0,0 +1,24 @@
+"""Solana SVM Exact Scheme - Facilitator Implementation.
+
+This module provides the facilitator-side implementation of the exact payment
+scheme for Solana network using SPL Token TransferChecked instructions.
+
+The facilitator:
+1. Verifies signed transactions by checking transfer instruction parameters,
+   ensuring the facilitator's funds are not being stolen, and simulating
+2. Settles payments by co-signing (as fee payer) and broadcasting the transaction
+3. Waits for transaction confirmation
+
+This module re-exports the facilitator implementation from the monolithic svm module,
+providing the standard scheme package structure.
+"""
+
+from t402.svm import (
+    ExactSvmFacilitatorScheme,
+    FacilitatorSvmSigner,
+)
+
+__all__ = [
+    "ExactSvmFacilitatorScheme",
+    "FacilitatorSvmSigner",
+]

t402/schemes/svm/exact/server.py

@@ -0,0 +1,20 @@
+"""Solana SVM Exact Scheme - Server Implementation.
+
+This module provides the server-side implementation of the exact payment scheme
+for Solana network.
+
+The server parses user-friendly prices into atomic token amounts and enhances
+payment requirements with the facilitator's fee payer address so clients can
+build transactions correctly.
+
+This module re-exports the server implementation from the monolithic svm module,
+providing the standard scheme package structure.
+"""
+
+from t402.svm import (
+    ExactSvmServerScheme,
+)
+
+__all__ = [
+    "ExactSvmServerScheme",
+]

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/tezos/__init__.py

@@ -0,0 +1,84 @@
+"""Tezos Blockchain Payment Schemes.
+
+This package provides payment scheme implementations for the Tezos blockchain.
+
+Supported schemes:
+- exact-direct: Client executes FA2 transfer directly, provides opHash as proof
+
+Usage:
+    ```python
+    from t402.schemes.tezos import (
+        ExactDirectTezosClient,
+        ExactDirectTezosServer,
+        ExactDirectTezosFacilitator,
+        ClientTezosSigner,
+        FacilitatorTezosSigner,
+        SCHEME_EXACT_DIRECT,
+    )
+    ```
+"""
+
+from t402.schemes.tezos.constants import (
+    SCHEME_EXACT_DIRECT,
+    TEZOS_MAINNET,
+    TEZOS_GHOSTNET,
+    USDT_MAINNET_CONTRACT,
+    USDT_MAINNET_TOKEN_ID,
+    USDT_DECIMALS,
+    USDT_MAINNET,
+    NETWORK_CONFIGS,
+    TOKEN_REGISTRY,
+    is_tezos_network,
+    is_valid_address,
+    is_valid_operation_hash,
+    create_asset_identifier,
+    parse_asset_identifier,
+    get_network_config,
+    get_token_info,
+    get_token_by_contract,
+    decimal_to_atomic,
+    parse_decimal_to_atomic,
+)
+from t402.schemes.tezos.types import (
+    ClientTezosSigner,
+    FacilitatorTezosSigner,
+    ExactDirectPayload,
+)
+from t402.schemes.tezos.exact_direct import (
+    ExactDirectTezosClient,
+    ExactDirectTezosServer,
+    ExactDirectTezosFacilitator,
+)
+
+__all__ = [
+    # Scheme classes
+    "ExactDirectTezosClient",
+    "ExactDirectTezosServer",
+    "ExactDirectTezosFacilitator",
+    # Signer protocols
+    "ClientTezosSigner",
+    "FacilitatorTezosSigner",
+    # Payload type
+    "ExactDirectPayload",
+    # Constants
+    "SCHEME_EXACT_DIRECT",
+    "TEZOS_MAINNET",
+    "TEZOS_GHOSTNET",
+    "USDT_MAINNET_CONTRACT",
+    "USDT_MAINNET_TOKEN_ID",
+    "USDT_DECIMALS",
+    "USDT_MAINNET",
+    "NETWORK_CONFIGS",
+    "TOKEN_REGISTRY",
+    # Utility functions
+    "is_tezos_network",
+    "is_valid_address",
+    "is_valid_operation_hash",
+    "create_asset_identifier",
+    "parse_asset_identifier",
+    "get_network_config",
+    "get_token_info",
+    "get_token_by_contract",
+    "decimal_to_atomic",
+    "parse_decimal_to_atomic",
+]