t402 1.9.0__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/polkadot/__init__.py

@@ -0,0 +1,72 @@
+"""Polkadot Blockchain Payment Schemes.
+
+This package provides payment scheme implementations for Polkadot Asset Hub networks.
+
+Supported schemes:
+- exact-direct: On-chain asset transfer with extrinsic proof
+
+Supported networks:
+- polkadot:68d56f15f85d3136970ec16946040bc1 (Polkadot Asset Hub)
+- polkadot:e143f23803ac50e8f6f8e62695d1ce9e (Westend Asset Hub / Testnet)
+"""
+
+from t402.schemes.polkadot.exact_direct import (
+    ExactDirectPolkadotClientScheme,
+    ExactDirectPolkadotServerScheme,
+    ExactDirectPolkadotFacilitatorScheme,
+    ClientPolkadotSigner,
+    FacilitatorPolkadotSigner,
+    SCHEME_EXACT_DIRECT,
+)
+from t402.schemes.polkadot.constants import (
+    POLKADOT_ASSET_HUB_CAIP2,
+    WESTEND_ASSET_HUB_CAIP2,
+    KUSAMA_ASSET_HUB_CAIP2,
+    USDT_ASSET_ID,
+    USDT_DECIMALS,
+    NETWORKS,
+    get_network_config,
+    get_supported_networks,
+    is_polkadot_network,
+)
+from t402.schemes.polkadot.types import (
+    ExactDirectPayload,
+    ExtrinsicResult,
+    ParsedAssetTransfer,
+    is_valid_ss58_address,
+    is_valid_hash,
+    parse_asset_identifier,
+    create_asset_identifier,
+    extract_asset_transfer,
+)
+
+__all__ = [
+    # Schemes
+    "ExactDirectPolkadotClientScheme",
+    "ExactDirectPolkadotServerScheme",
+    "ExactDirectPolkadotFacilitatorScheme",
+    # Signer protocols
+    "ClientPolkadotSigner",
+    "FacilitatorPolkadotSigner",
+    # Constants
+    "SCHEME_EXACT_DIRECT",
+    "POLKADOT_ASSET_HUB_CAIP2",
+    "WESTEND_ASSET_HUB_CAIP2",
+    "KUSAMA_ASSET_HUB_CAIP2",
+    "USDT_ASSET_ID",
+    "USDT_DECIMALS",
+    "NETWORKS",
+    # Functions
+    "get_network_config",
+    "get_supported_networks",
+    "is_polkadot_network",
+    # Types
+    "ExactDirectPayload",
+    "ExtrinsicResult",
+    "ParsedAssetTransfer",
+    "is_valid_ss58_address",
+    "is_valid_hash",
+    "parse_asset_identifier",
+    "create_asset_identifier",
+    "extract_asset_transfer",
+]

t402/schemes/polkadot/constants.py

@@ -0,0 +1,155 @@
+"""Polkadot Scheme Constants.
+
+This module defines constants for the Polkadot exact-direct payment scheme,
+including network identifiers, token configurations, and default endpoints.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Dict
+
+
+# Scheme identifier
+SCHEME_EXACT_DIRECT = "exact-direct"
+
+# CAIP-2 network identifiers for Polkadot parachains
+POLKADOT_ASSET_HUB_CAIP2 = "polkadot:68d56f15f85d3136970ec16946040bc1"
+KUSAMA_ASSET_HUB_CAIP2 = "polkadot:48239ef607d7928874027a43a67689209727dfb3d3dc5e5b03a39bdc2eda771a"
+WESTEND_ASSET_HUB_CAIP2 = "polkadot:e143f23803ac50e8f6f8e62695d1ce9e"
+
+# Default indexer endpoints (Subscan)
+POLKADOT_ASSET_HUB_INDEXER = "https://assethub-polkadot.api.subscan.io"
+KUSAMA_ASSET_HUB_INDEXER = "https://assethub-kusama.api.subscan.io"
+WESTEND_ASSET_HUB_INDEXER = "https://assethub-westend.api.subscan.io"
+
+# Default RPC endpoints
+POLKADOT_ASSET_HUB_RPC = "wss://polkadot-asset-hub-rpc.polkadot.io"
+KUSAMA_ASSET_HUB_RPC = "wss://kusama-asset-hub-rpc.polkadot.io"
+WESTEND_ASSET_HUB_RPC = "wss://westend-asset-hub-rpc.polkadot.io"
+
+# USDT Asset ID on Asset Hub parachains
+USDT_ASSET_ID = 1984
+
+# Default decimals for USDT
+USDT_DECIMALS = 6
+
+
+@dataclass(frozen=True)
+class TokenInfo:
+    """Token configuration for a Polkadot asset."""
+
+    asset_id: int
+    symbol: str
+    name: str
+    decimals: int
+
+
+@dataclass(frozen=True)
+class NetworkConfig:
+    """Configuration for a Polkadot network."""
+
+    name: str
+    caip2: str
+    indexer_url: str
+    rpc_url: str
+    genesis_hash: str
+    ss58_prefix: int
+    is_testnet: bool
+    default_token: TokenInfo
+
+
+# Default token configurations
+USDT_POLKADOT = TokenInfo(
+    asset_id=USDT_ASSET_ID,
+    symbol="USDT",
+    name="Tether USD",
+    decimals=USDT_DECIMALS,
+)
+
+USDT_KUSAMA = TokenInfo(
+    asset_id=USDT_ASSET_ID,
+    symbol="USDT",
+    name="Tether USD",
+    decimals=USDT_DECIMALS,
+)
+
+USDT_WESTEND = TokenInfo(
+    asset_id=USDT_ASSET_ID,
+    symbol="USDT",
+    name="Test Tether USD",
+    decimals=USDT_DECIMALS,
+)
+
+# Network configurations indexed by CAIP-2 identifier
+NETWORKS: Dict[str, NetworkConfig] = {
+    POLKADOT_ASSET_HUB_CAIP2: NetworkConfig(
+        name="Polkadot Asset Hub",
+        caip2=POLKADOT_ASSET_HUB_CAIP2,
+        indexer_url=POLKADOT_ASSET_HUB_INDEXER,
+        rpc_url=POLKADOT_ASSET_HUB_RPC,
+        genesis_hash="0x68d56f15f85d3136970ec16946040bc1752654e906147f7e43e9d539d7c3de2f",
+        ss58_prefix=0,
+        is_testnet=False,
+        default_token=USDT_POLKADOT,
+    ),
+    KUSAMA_ASSET_HUB_CAIP2: NetworkConfig(
+        name="Kusama Asset Hub",
+        caip2=KUSAMA_ASSET_HUB_CAIP2,
+        indexer_url=KUSAMA_ASSET_HUB_INDEXER,
+        rpc_url=KUSAMA_ASSET_HUB_RPC,
+        genesis_hash="0x48239ef607d7928874027a43a67689209727dfb3d3dc5e5b03a39bdc2eda771a",
+        ss58_prefix=2,
+        is_testnet=False,
+        default_token=USDT_KUSAMA,
+    ),
+    WESTEND_ASSET_HUB_CAIP2: NetworkConfig(
+        name="Westend Asset Hub",
+        caip2=WESTEND_ASSET_HUB_CAIP2,
+        indexer_url=WESTEND_ASSET_HUB_INDEXER,
+        rpc_url=WESTEND_ASSET_HUB_RPC,
+        genesis_hash="0xe143f23803ac50e8f6f8e62695d1ce9e4e1d68aa36c1cd2cfd15340213f3423e",
+        ss58_prefix=42,
+        is_testnet=True,
+        default_token=USDT_WESTEND,
+    ),
+}
+
+
+def get_network_config(network: str) -> NetworkConfig:
+    """Get the network configuration for a CAIP-2 identifier.
+
+    Args:
+        network: CAIP-2 network identifier (e.g., "polkadot:68d56f15f85d3136970ec16946040bc1")
+
+    Returns:
+        NetworkConfig for the given network
+
+    Raises:
+        ValueError: If the network is not supported
+    """
+    config = NETWORKS.get(network)
+    if config is None:
+        raise ValueError(f"Unsupported Polkadot network: {network}")
+    return config
+
+
+def is_polkadot_network(network: str) -> bool:
+    """Check if a network identifier is a Polkadot network.
+
+    Args:
+        network: Network identifier to check
+
+    Returns:
+        True if the network starts with "polkadot:"
+    """
+    return network.startswith("polkadot:")
+
+
+def get_supported_networks() -> list:
+    """Get all supported Polkadot network identifiers.
+
+    Returns:
+        List of CAIP-2 network identifiers
+    """
+    return list(NETWORKS.keys())

t402/schemes/polkadot/exact_direct/__init__.py

@@ -0,0 +1,43 @@
+"""Polkadot Exact-Direct Payment Scheme.
+
+This package provides the exact-direct payment scheme implementation for
+Polkadot Asset Hub networks using on-chain asset transfers.
+
+The exact-direct scheme works by:
+1. Client executes assets.transfer_keep_alive on-chain
+2. Client returns the extrinsic hash, block hash, and index as proof
+3. Facilitator verifies the transfer on-chain via indexer/RPC
+
+This is a "direct" scheme because the client pays on-chain before
+submitting the payment proof, rather than providing an off-chain signature
+for later settlement.
+"""
+
+from t402.schemes.polkadot.exact_direct.client import (
+    ExactDirectPolkadotClientScheme,
+)
+from t402.schemes.polkadot.exact_direct.server import (
+    ExactDirectPolkadotServerScheme,
+)
+from t402.schemes.polkadot.exact_direct.facilitator import (
+    ExactDirectPolkadotFacilitatorScheme,
+)
+from t402.schemes.polkadot.constants import SCHEME_EXACT_DIRECT
+from t402.schemes.polkadot.types import (
+    ClientPolkadotSigner,
+    FacilitatorPolkadotSigner,
+)
+
+__all__ = [
+    # Client
+    "ExactDirectPolkadotClientScheme",
+    # Server
+    "ExactDirectPolkadotServerScheme",
+    # Facilitator
+    "ExactDirectPolkadotFacilitatorScheme",
+    # Signer protocols
+    "ClientPolkadotSigner",
+    "FacilitatorPolkadotSigner",
+    # Constants
+    "SCHEME_EXACT_DIRECT",
+]