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

t402/networks.py

@@ -2,7 +2,16 @@ from typing import Literal, Union, get_args
 
 
 # EVM Networks
-EVMNetworks = Literal["base", "base-sepolia", "avalanche-fuji", "avalanche"]
+EVMNetworks = Literal[
+    # Standard networks
+    "base", "base-sepolia", "avalanche-fuji", "avalanche",
+    # Core USDT0 Networks
+    "ethereum", "arbitrum", "optimism", "polygon", "ink", "berachain", "unichain",
+    # Phase 1: High Priority USDT0 Networks
+    "mantle", "plasma", "sei", "conflux", "monad",
+    # Phase 2: Medium Priority USDT0 Networks
+    "flare", "rootstock", "xlayer", "stable", "hyperevm", "megaeth", "corn",
+]
 
 # TON Networks (CAIP-2 format)
 TONNetworks = Literal["ton:mainnet", "ton:testnet"]
@@ -32,11 +41,35 @@ def get_all_supported_networks() -> tuple[str, ...]:
     svm = get_args(SVMNetworks)
     return evm + ton + tron + svm
 
+
 EVM_NETWORK_TO_CHAIN_ID = {
+    # Standard networks
     "base-sepolia": 84532,
     "base": 8453,
     "avalanche-fuji": 43113,
     "avalanche": 43114,
+    # Core USDT0 Networks
+    "ethereum": 1,
+    "arbitrum": 42161,
+    "optimism": 10,
+    "polygon": 137,
+    "ink": 57073,
+    "berachain": 80094,
+    "unichain": 130,
+    # Phase 1: High Priority USDT0 Networks
+    "mantle": 5000,
+    "plasma": 9745,
+    "sei": 1329,
+    "conflux": 1030,
+    "monad": 143,
+    # Phase 2: Medium Priority USDT0 Networks
+    "flare": 14,
+    "rootstock": 30,
+    "xlayer": 196,
+    "stable": 988,
+    "hyperevm": 999,
+    "megaeth": 4326,
+    "corn": 21000000,
 }
 
 # TON Network configurations

t402/paywall.py

@@ -127,6 +127,4 @@ def get_paywall_html(
         raise ValueError("payment_requirements cannot be empty")
     network = payment_requirements[0].network
     template = get_paywall_template(network)
-    return inject_payment_data(
-        template, error, payment_requirements, paywall_config
-    )
+    return inject_payment_data(template, error, payment_requirements, paywall_config)

t402/schemes/__init__.py

@@ -70,9 +70,15 @@ from t402.schemes.registry import (
 from t402.schemes.evm import (
     ExactEvmClientScheme,
     ExactEvmServerScheme,
+    ExactEvmFacilitatorScheme,
+    FacilitatorEvmSigner,
+    EvmVerifyResult,
+    EvmTransactionConfirmation,
     EvmSigner,
     # Upto EVM
     UptoEvmClientScheme,
+    UptoEvmServerScheme,
+    UptoEvmFacilitatorScheme,
     PermitSignature,
     PermitAuthorization,
     UptoEIP2612Payload,
@@ -98,14 +104,90 @@ from t402.schemes.upto import (
 from t402.schemes.ton import (
     ExactTonClientScheme,
     ExactTonServerScheme,
+    ExactTonFacilitatorScheme,
     TonSigner,
+    FacilitatorTonSigner,
 )
 
 # TRON Schemes
 from t402.schemes.tron import (
     ExactTronClientScheme,
     ExactTronServerScheme,
+    ExactTronFacilitatorScheme,
+    ExactTronFacilitatorConfig,
     TronSigner,
+    FacilitatorTronSigner,
+)
+
+# SVM Schemes
+from t402.schemes.svm import (
+    ExactSvmClientScheme,
+    ExactSvmServerScheme,
+    ExactSvmFacilitatorScheme,
+    ClientSvmSigner as SvmClientSigner,
+    FacilitatorSvmSigner as SvmFacilitatorSigner,
+    SCHEME_EXACT as SVM_SCHEME_EXACT,
+)
+
+# NEAR Schemes
+from t402.schemes.near import (
+    ExactDirectNearClientScheme,
+    ExactDirectNearServerScheme,
+    ExactDirectNearFacilitatorScheme,
+    ClientNearSigner,
+    FacilitatorNearSigner,
+    SCHEME_EXACT_DIRECT as NEAR_SCHEME_EXACT_DIRECT,
+)
+
+# Aptos Schemes
+from t402.schemes.aptos import (
+    ExactDirectAptosClientScheme,
+    ExactDirectAptosServerScheme,
+    ExactDirectAptosFacilitatorScheme,
+    ClientAptosSigner,
+    FacilitatorAptosSigner,
+    SCHEME_EXACT_DIRECT,
+)
+
+# Polkadot Schemes
+from t402.schemes.polkadot import (
+    ExactDirectPolkadotClientScheme,
+    ExactDirectPolkadotServerScheme,
+    ExactDirectPolkadotFacilitatorScheme,
+    ClientPolkadotSigner,
+    FacilitatorPolkadotSigner,
+    SCHEME_EXACT_DIRECT as POLKADOT_SCHEME_EXACT_DIRECT,
+)
+
+# Tezos Schemes
+from t402.schemes.tezos import (
+    ExactDirectTezosClient,
+    ExactDirectTezosServer,
+    ExactDirectTezosFacilitator,
+    ClientTezosSigner,
+    FacilitatorTezosSigner,
+    SCHEME_EXACT_DIRECT as TEZOS_SCHEME_EXACT_DIRECT,
+)
+
+# Stacks Schemes
+from t402.schemes.stacks import (
+    ExactDirectStacksClientScheme,
+    ExactDirectStacksServerScheme,
+    ExactDirectStacksFacilitatorScheme,
+    ClientStacksSigner,
+    FacilitatorStacksSigner,
+    SCHEME_EXACT_DIRECT as STACKS_SCHEME_EXACT_DIRECT,
+)
+
+# Cosmos Schemes
+from t402.schemes.cosmos import (
+    ExactDirectCosmosClientScheme,
+    ExactDirectCosmosServerScheme,
+    ExactDirectCosmosFacilitatorScheme,
+    ExactDirectCosmosFacilitatorConfig,
+    ClientCosmosSigner,
+    FacilitatorCosmosSigner,
+    SCHEME_EXACT_DIRECT as COSMOS_SCHEME_EXACT_DIRECT,
 )
 
 __all__ = [
@@ -134,9 +216,15 @@ __all__ = [
     # EVM Exact Schemes
     "ExactEvmClientScheme",
     "ExactEvmServerScheme",
+    "ExactEvmFacilitatorScheme",
+    "FacilitatorEvmSigner",
+    "EvmVerifyResult",
+    "EvmTransactionConfirmation",
     "EvmSigner",
     # EVM Upto Schemes
     "UptoEvmClientScheme",
+    "UptoEvmServerScheme",
+    "UptoEvmFacilitatorScheme",
     "PermitSignature",
     "PermitAuthorization",
     "UptoEIP2612Payload",
@@ -156,9 +244,64 @@ __all__ = [
     # TON Schemes
     "ExactTonClientScheme",
     "ExactTonServerScheme",
+    "ExactTonFacilitatorScheme",
     "TonSigner",
+    "FacilitatorTonSigner",
     # TRON Schemes
     "ExactTronClientScheme",
     "ExactTronServerScheme",
+    "ExactTronFacilitatorScheme",
+    "ExactTronFacilitatorConfig",
     "TronSigner",
+    "FacilitatorTronSigner",
+    # SVM Schemes
+    "ExactSvmClientScheme",
+    "ExactSvmServerScheme",
+    "ExactSvmFacilitatorScheme",
+    "SvmClientSigner",
+    "SvmFacilitatorSigner",
+    "SVM_SCHEME_EXACT",
+    # NEAR Schemes
+    "ExactDirectNearClientScheme",
+    "ExactDirectNearServerScheme",
+    "ExactDirectNearFacilitatorScheme",
+    "ClientNearSigner",
+    "FacilitatorNearSigner",
+    "NEAR_SCHEME_EXACT_DIRECT",
+    # Aptos Schemes
+    "ExactDirectAptosClientScheme",
+    "ExactDirectAptosServerScheme",
+    "ExactDirectAptosFacilitatorScheme",
+    "ClientAptosSigner",
+    "FacilitatorAptosSigner",
+    "SCHEME_EXACT_DIRECT",
+    # Polkadot Schemes
+    "ExactDirectPolkadotClientScheme",
+    "ExactDirectPolkadotServerScheme",
+    "ExactDirectPolkadotFacilitatorScheme",
+    "ClientPolkadotSigner",
+    "FacilitatorPolkadotSigner",
+    "POLKADOT_SCHEME_EXACT_DIRECT",
+    # Tezos Schemes
+    "ExactDirectTezosClient",
+    "ExactDirectTezosServer",
+    "ExactDirectTezosFacilitator",
+    "ClientTezosSigner",
+    "FacilitatorTezosSigner",
+    "TEZOS_SCHEME_EXACT_DIRECT",
+    # Stacks Schemes
+    "ExactDirectStacksClientScheme",
+    "ExactDirectStacksServerScheme",
+    "ExactDirectStacksFacilitatorScheme",
+    "ClientStacksSigner",
+    "FacilitatorStacksSigner",
+    "STACKS_SCHEME_EXACT_DIRECT",
+    # Cosmos Schemes
+    "ExactDirectCosmosClientScheme",
+    "ExactDirectCosmosServerScheme",
+    "ExactDirectCosmosFacilitatorScheme",
+    "ExactDirectCosmosFacilitatorConfig",
+    "ClientCosmosSigner",
+    "FacilitatorCosmosSigner",
+    "COSMOS_SCHEME_EXACT_DIRECT",
 ]

t402/schemes/aptos/__init__.py

@@ -0,0 +1,70 @@
+"""Aptos Blockchain Payment Schemes.
+
+This package provides payment scheme implementations for the Aptos blockchain.
+
+Supported schemes:
+- exact-direct: Fungible Asset transfers via 0x1::primary_fungible_store::transfer
+"""
+
+from t402.schemes.aptos.exact_direct import (
+    ExactDirectAptosClientScheme,
+    ExactDirectAptosServerScheme,
+    ExactDirectAptosFacilitatorScheme,
+    ClientAptosSigner,
+    FacilitatorAptosSigner,
+    ExactDirectPayload,
+    SCHEME_EXACT_DIRECT,
+)
+from t402.schemes.aptos.constants import (
+    APTOS_MAINNET,
+    APTOS_TESTNET,
+    APTOS_DEVNET,
+    CAIP_FAMILY,
+    USDT_MAINNET_METADATA,
+    USDC_MAINNET_METADATA,
+    FA_TRANSFER_FUNCTION,
+    DEFAULT_DECIMALS,
+    is_valid_address,
+    is_valid_tx_hash,
+    is_valid_network,
+    compare_addresses,
+    normalize_address,
+    parse_amount,
+    format_amount,
+    get_network_config,
+    get_token_info,
+    get_token_by_address,
+)
+
+__all__ = [
+    # Exact-Direct scheme
+    "ExactDirectAptosClientScheme",
+    "ExactDirectAptosServerScheme",
+    "ExactDirectAptosFacilitatorScheme",
+    # Signer protocols
+    "ClientAptosSigner",
+    "FacilitatorAptosSigner",
+    # Types
+    "ExactDirectPayload",
+    # Constants
+    "SCHEME_EXACT_DIRECT",
+    "APTOS_MAINNET",
+    "APTOS_TESTNET",
+    "APTOS_DEVNET",
+    "CAIP_FAMILY",
+    "USDT_MAINNET_METADATA",
+    "USDC_MAINNET_METADATA",
+    "FA_TRANSFER_FUNCTION",
+    "DEFAULT_DECIMALS",
+    # Utility functions
+    "is_valid_address",
+    "is_valid_tx_hash",
+    "is_valid_network",
+    "compare_addresses",
+    "normalize_address",
+    "parse_amount",
+    "format_amount",
+    "get_network_config",
+    "get_token_info",
+    "get_token_by_address",
+]

t402/schemes/aptos/constants.py

@@ -0,0 +1,349 @@
+"""Aptos Network Constants and Token Registry.
+
+This module defines constants for Aptos blockchain networks, token metadata
+addresses, and network configurations used by the exact-direct payment scheme.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+# Scheme identifier
+SCHEME_EXACT_DIRECT = "exact-direct"
+
+# CAIP-2 family pattern
+CAIP_FAMILY = "aptos:*"
+
+# CAIP-2 network identifiers
+APTOS_MAINNET = "aptos:1"
+APTOS_TESTNET = "aptos:2"
+APTOS_DEVNET = "aptos:149"
+
+# RPC endpoints
+APTOS_MAINNET_RPC = "https://fullnode.mainnet.aptoslabs.com/v1"
+APTOS_TESTNET_RPC = "https://fullnode.testnet.aptoslabs.com/v1"
+APTOS_DEVNET_RPC = "https://fullnode.devnet.aptoslabs.com/v1"
+
+# Fungible Asset transfer function
+FA_TRANSFER_FUNCTION = "0x1::primary_fungible_store::transfer"
+
+# Default decimals for USDT on Aptos
+DEFAULT_DECIMALS = 6
+
+# USDT Fungible Asset metadata address on Aptos mainnet
+USDT_MAINNET_METADATA = (
+    "0xf73e887a8754f540ee6e1a93bdc6dde2af69fc7ca5de32013e89dd44244473cb"
+)
+
+# USDC metadata address on Aptos mainnet
+USDC_MAINNET_METADATA = (
+    "0xbae207659db88bea0cbead6da0ed00aac12edcdda169e591cd41c94180b46f3b"
+)
+
+
+# Token information structure
+class TokenInfo:
+    """Contains information about an Aptos fungible asset.
+
+    Attributes:
+        metadata_address: The on-chain FA metadata object address.
+        symbol: Token ticker symbol (e.g., "USDT").
+        name: Human-readable token name (e.g., "Tether USD").
+        decimals: Number of decimal places for the token.
+    """
+
+    def __init__(
+        self,
+        metadata_address: str,
+        symbol: str,
+        name: str,
+        decimals: int,
+    ) -> None:
+        self.metadata_address = metadata_address
+        self.symbol = symbol
+        self.name = name
+        self.decimals = decimals
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary representation."""
+        return {
+            "metadata_address": self.metadata_address,
+            "symbol": self.symbol,
+            "name": self.name,
+            "decimals": self.decimals,
+        }
+
+
+# Token definitions
+USDT_MAINNET = TokenInfo(
+    metadata_address=USDT_MAINNET_METADATA,
+    symbol="USDT",
+    name="Tether USD",
+    decimals=6,
+)
+
+USDC_MAINNET = TokenInfo(
+    metadata_address=USDC_MAINNET_METADATA,
+    symbol="USDC",
+    name="USD Coin",
+    decimals=6,
+)
+
+
+# Network configuration
+class NetworkConfig:
+    """Network-specific configuration for Aptos.
+
+    Attributes:
+        chain_id: Numeric chain ID.
+        rpc_url: Default RPC endpoint URL.
+        default_token: Default token for this network.
+    """
+
+    def __init__(
+        self,
+        chain_id: int,
+        rpc_url: str,
+        default_token: TokenInfo,
+    ) -> None:
+        self.chain_id = chain_id
+        self.rpc_url = rpc_url
+        self.default_token = default_token
+
+
+# Network configurations registry
+NETWORK_CONFIGS: Dict[str, NetworkConfig] = {
+    APTOS_MAINNET: NetworkConfig(
+        chain_id=1,
+        rpc_url=APTOS_MAINNET_RPC,
+        default_token=USDT_MAINNET,
+    ),
+    APTOS_TESTNET: NetworkConfig(
+        chain_id=2,
+        rpc_url=APTOS_TESTNET_RPC,
+        default_token=USDT_MAINNET,
+    ),
+    APTOS_DEVNET: NetworkConfig(
+        chain_id=149,
+        rpc_url=APTOS_DEVNET_RPC,
+        default_token=USDT_MAINNET,
+    ),
+}
+
+# Token registry by network
+TOKEN_REGISTRY: Dict[str, Dict[str, TokenInfo]] = {
+    APTOS_MAINNET: {
+        "USDT": USDT_MAINNET,
+        "USDC": USDC_MAINNET,
+    },
+    APTOS_TESTNET: {
+        "USDT": USDT_MAINNET,
+    },
+}
+
+
+def get_network_config(network: str) -> Optional[NetworkConfig]:
+    """Get the configuration for a given network.
+
+    Args:
+        network: CAIP-2 network identifier (e.g., "aptos:1").
+
+    Returns:
+        NetworkConfig if found, None otherwise.
+    """
+    return NETWORK_CONFIGS.get(network)
+
+
+def get_token_info(network: str, symbol: str) -> Optional[TokenInfo]:
+    """Get token info for a network and symbol.
+
+    Args:
+        network: CAIP-2 network identifier.
+        symbol: Token symbol (e.g., "USDT").
+
+    Returns:
+        TokenInfo if found, None otherwise.
+    """
+    tokens = TOKEN_REGISTRY.get(network)
+    if not tokens:
+        return None
+    return tokens.get(symbol)
+
+
+def get_token_by_address(network: str, metadata_address: str) -> Optional[TokenInfo]:
+    """Get token info by FA metadata address.
+
+    Args:
+        network: CAIP-2 network identifier.
+        metadata_address: The on-chain metadata object address.
+
+    Returns:
+        TokenInfo if found, None otherwise.
+    """
+    tokens = TOKEN_REGISTRY.get(network)
+    if not tokens:
+        return None
+    normalized = normalize_address(metadata_address)
+    for token in tokens.values():
+        if normalize_address(token.metadata_address) == normalized:
+            return token
+    return None
+
+
+def is_valid_network(network: str) -> bool:
+    """Check if a network identifier is supported.
+
+    Args:
+        network: CAIP-2 network identifier.
+
+    Returns:
+        True if the network is known and supported.
+    """
+    return network in NETWORK_CONFIGS
+
+
+def is_valid_address(address: str) -> bool:
+    """Validate an Aptos address format.
+
+    Aptos addresses are 0x-prefixed hex strings, up to 64 hex characters.
+
+    Args:
+        address: The address to validate.
+
+    Returns:
+        True if the address is valid.
+    """
+    if not address:
+        return False
+    if not address.startswith("0x"):
+        return False
+    hex_part = address[2:]
+    if len(hex_part) == 0 or len(hex_part) > 64:
+        return False
+    try:
+        int(hex_part, 16)
+        return True
+    except ValueError:
+        return False
+
+
+def is_valid_tx_hash(tx_hash: str) -> bool:
+    """Validate an Aptos transaction hash format.
+
+    Transaction hashes are 0x-prefixed hex strings of exactly 64 hex characters.
+
+    Args:
+        tx_hash: The transaction hash to validate.
+
+    Returns:
+        True if the hash is valid.
+    """
+    if not tx_hash:
+        return False
+    if not tx_hash.startswith("0x"):
+        return False
+    hex_part = tx_hash[2:]
+    if len(hex_part) != 64:
+        return False
+    try:
+        int(hex_part, 16)
+        return True
+    except ValueError:
+        return False
+
+
+def normalize_address(address: str) -> str:
+    """Normalize an Aptos address for comparison.
+
+    Converts to lowercase and ensures 0x prefix.
+
+    Args:
+        address: The address to normalize.
+
+    Returns:
+        Normalized address string.
+    """
+    if not address:
+        return ""
+    if address.startswith("0x"):
+        return "0x" + address[2:].lower()
+    return "0x" + address.lower()
+
+
+def compare_addresses(addr1: str, addr2: str) -> bool:
+    """Compare two Aptos addresses (case-insensitive).
+
+    Args:
+        addr1: First address.
+        addr2: Second address.
+
+    Returns:
+        True if addresses are equivalent.
+    """
+    if not addr1 or not addr2:
+        return False
+    return normalize_address(addr1) == normalize_address(addr2)
+
+
+def parse_amount(amount: str, decimals: int) -> int:
+    """Convert a decimal string amount to atomic units.
+
+    Args:
+        amount: Decimal amount string (e.g., "1.5").
+        decimals: Number of decimal places for the token.
+
+    Returns:
+        Amount in smallest atomic units.
+
+    Raises:
+        ValueError: If the amount format is invalid.
+    """
+    amount = amount.strip()
+    parts = amount.split(".")
+
+    if len(parts) > 2:
+        raise ValueError(f"Invalid amount format: {amount}")
+
+    try:
+        int_part = int(parts[0])
+    except ValueError:
+        raise ValueError(f"Invalid integer part: {parts[0]}")
+
+    dec_part = 0
+    if len(parts) == 2 and parts[1]:
+        dec_str = parts[1]
+        if len(dec_str) > decimals:
+            dec_str = dec_str[:decimals]
+        else:
+            dec_str += "0" * (decimals - len(dec_str))
+        try:
+            dec_part = int(dec_str)
+        except ValueError:
+            raise ValueError(f"Invalid decimal part: {parts[1]}")
+
+    multiplier = 10**decimals
+    return int_part * multiplier + dec_part
+
+
+def format_amount(atomic_amount: int, decimals: int) -> str:
+    """Convert atomic units to a human-readable decimal string.
+
+    Args:
+        atomic_amount: Amount in smallest atomic units.
+        decimals: Number of decimal places for the token.
+
+    Returns:
+        Formatted decimal string.
+    """
+    if atomic_amount == 0:
+        return "0"
+
+    multiplier = 10**decimals
+    int_part = atomic_amount // multiplier
+    dec_part = atomic_amount % multiplier
+
+    if dec_part == 0:
+        return str(int_part)
+
+    dec_str = str(dec_part).zfill(decimals).rstrip("0")
+    return f"{int_part}.{dec_str}"

t402/schemes/aptos/exact_direct/__init__.py

@@ -0,0 +1,44 @@
+"""Aptos Exact-Direct Payment Scheme.
+
+This package provides the exact-direct payment scheme implementation for Aptos
+using Fungible Asset (FA) transfers via ``0x1::primary_fungible_store::transfer``.
+
+The exact-direct scheme works as follows:
+1. Client executes the FA transfer on-chain directly.
+2. Client returns the transaction hash as proof of payment.
+3. Facilitator queries the Aptos REST API to verify the transaction details.
+
+This is a "push" payment model where the client performs the transfer first,
+unlike permit-based models where the facilitator executes settlement.
+"""
+
+from t402.schemes.aptos.exact_direct.client import (
+    ExactDirectAptosClientScheme,
+)
+from t402.schemes.aptos.exact_direct.server import (
+    ExactDirectAptosServerScheme,
+)
+from t402.schemes.aptos.exact_direct.facilitator import (
+    ExactDirectAptosFacilitatorScheme,
+)
+from t402.schemes.aptos.constants import SCHEME_EXACT_DIRECT
+from t402.schemes.aptos.types import (
+    ClientAptosSigner,
+    FacilitatorAptosSigner,
+    ExactDirectPayload,
+)
+
+__all__ = [
+    # Client
+    "ExactDirectAptosClientScheme",
+    "ClientAptosSigner",
+    # Server
+    "ExactDirectAptosServerScheme",
+    # Facilitator
+    "ExactDirectAptosFacilitatorScheme",
+    "FacilitatorAptosSigner",
+    # Types
+    "ExactDirectPayload",
+    # Constants
+    "SCHEME_EXACT_DIRECT",
+]