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

t402/schemes/polkadot/exact_direct/server.py

@@ -0,0 +1,292 @@
+"""Polkadot Exact-Direct Scheme - Server Implementation.
+
+This module provides the server-side implementation of the exact-direct
+payment scheme for Polkadot Asset Hub networks.
+
+The server:
+1. Parses user-friendly prices (e.g., "$0.10") into atomic amounts
+2. Enhances payment requirements with Polkadot-specific metadata
+   (asset ID, decimals, network name, CAIP-19 asset identifier)
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Union
+
+from t402.types import (
+    PaymentRequirementsV2,
+    Network,
+)
+from t402.schemes.interfaces import AssetAmount, SupportedKindDict
+from t402.schemes.polkadot.constants import (
+    SCHEME_EXACT_DIRECT,
+    NetworkConfig,
+    TokenInfo,
+    get_network_config,
+    is_polkadot_network,
+)
+from t402.schemes.polkadot.types import create_asset_identifier
+
+
+class ExactDirectPolkadotServerScheme:
+    """Server scheme for Polkadot exact-direct payments.
+
+    Handles parsing user-friendly prices into atomic amounts and
+    enhancing payment requirements with Polkadot-specific metadata.
+
+    Example:
+        ```python
+        scheme = ExactDirectPolkadotServerScheme()
+
+        # Parse price to atomic units
+        asset_amount = await scheme.parse_price("$0.10", "polkadot:68d56f15f85d3136970ec16946040bc1")
+        # Returns: {"amount": "100000", "asset": "polkadot:.../asset:1984", "extra": {...}}
+
+        # Enhance requirements with metadata
+        enhanced = await scheme.enhance_requirements(
+            requirements,
+            supported_kind,
+            facilitator_extensions,
+        )
+        ```
+    """
+
+    scheme = SCHEME_EXACT_DIRECT
+    caip_family = "polkadot:*"
+
+    def __init__(self, preferred_token: Optional[str] = None):
+        """Initialize the Polkadot server scheme.
+
+        Args:
+            preferred_token: Override the default token symbol (e.g., "USDT")
+        """
+        self._preferred_token = preferred_token
+
+    async def parse_price(
+        self,
+        price: Union[str, int, float, Dict[str, Any]],
+        network: Network,
+    ) -> AssetAmount:
+        """Parse a user-friendly price to atomic amount and asset.
+
+        Supports:
+        - String with $ prefix: "$0.10" -> 100000 (6 decimals)
+        - String without prefix: "0.10" -> 100000
+        - Integer/float: 0.10 -> 100000
+        - Dict (pre-parsed): {"amount": "100000", "asset": "..."}
+
+        Args:
+            price: User-friendly price value
+            network: CAIP-2 network identifier
+
+        Returns:
+            AssetAmount dict with amount, asset, and extra metadata
+
+        Raises:
+            ValueError: If the network is unsupported or price is invalid
+        """
+        # Validate network
+        if not is_polkadot_network(network):
+            raise ValueError(f"Invalid Polkadot network: {network}")
+
+        network_config = get_network_config(network)
+
+        # Handle dict (already in pre-parsed format)
+        if isinstance(price, dict):
+            amount_str = str(price.get("amount", "0"))
+            asset = price.get("asset", "")
+            if not asset:
+                asset = create_asset_identifier(
+                    network, network_config.default_token.asset_id
+                )
+            extra = price.get("extra", {})
+            return {
+                "amount": amount_str,
+                "asset": asset,
+                "extra": extra,
+            }
+
+        # Get default token for this network
+        token = self._get_token(network, network_config)
+
+        # Parse price string/number to decimal
+        decimal_amount = self._parse_money_to_decimal(price)
+
+        # Convert to atomic units
+        atomic_amount = self._to_atomic_units(decimal_amount, token.decimals)
+
+        # Build asset identifier
+        asset_identifier = create_asset_identifier(network, token.asset_id)
+
+        # Build extra metadata
+        extra = {
+            "symbol": token.symbol,
+            "name": token.name,
+            "decimals": token.decimals,
+            "assetId": token.asset_id,
+        }
+
+        return {
+            "amount": str(atomic_amount),
+            "asset": asset_identifier,
+            "extra": extra,
+        }
+
+    async def enhance_requirements(
+        self,
+        requirements: Union[PaymentRequirementsV2, Dict[str, Any]],
+        supported_kind: SupportedKindDict,
+        facilitator_extensions: List[str],
+    ) -> Union[PaymentRequirementsV2, Dict[str, Any]]:
+        """Enhance payment requirements with Polkadot-specific metadata.
+
+        Adds asset metadata (ID, symbol, decimals, network name) and
+        the CAIP-19 asset identifier to the requirements.
+
+        Args:
+            requirements: Base payment requirements
+            supported_kind: Matched SupportedKind from facilitator
+            facilitator_extensions: Extensions supported by facilitator
+
+        Returns:
+            Enhanced requirements with Polkadot metadata in extra
+
+        Raises:
+            ValueError: If the network is not recognized
+        """
+        # Convert to dict for modification
+        if hasattr(requirements, "model_dump"):
+            req = requirements.model_dump(by_alias=True)
+        else:
+            req = dict(requirements)
+
+        network = req.get("network", "")
+
+        # Get network config
+        network_config = get_network_config(network)
+
+        # Get token info
+        token = self._get_token(network, network_config)
+
+        # Set asset identifier if not already set
+        if not req.get("asset"):
+            req["asset"] = create_asset_identifier(network, token.asset_id)
+
+        # Ensure amount is in atomic units (no decimals)
+        amount = req.get("amount", "")
+        if amount and "." in amount:
+            atomic = self._parse_amount_string(amount, token.decimals)
+            req["amount"] = str(atomic)
+
+        # Ensure extra exists
+        if "extra" not in req or req["extra"] is None:
+            req["extra"] = {}
+
+        # Add asset metadata
+        req["extra"]["assetId"] = token.asset_id
+        req["extra"]["assetSymbol"] = token.symbol
+        req["extra"]["assetDecimals"] = token.decimals
+        req["extra"]["networkName"] = network_config.name
+
+        # Add facilitator-provided extra fields from supportedKind
+        if supported_kind.get("extra"):
+            for key in ("assetId", "assetSymbol", "assetDecimals", "networkName"):
+                if key in supported_kind["extra"]:
+                    req["extra"][key] = supported_kind["extra"][key]
+
+        # Copy extension keys from supportedKind
+        if supported_kind.get("extra"):
+            for key in facilitator_extensions:
+                if key in supported_kind["extra"]:
+                    req["extra"][key] = supported_kind["extra"][key]
+
+        return req
+
+    def _get_token(self, network: str, network_config: NetworkConfig) -> TokenInfo:
+        """Get the token to use for the given network.
+
+        Uses the preferred token if configured and available,
+        otherwise falls back to the network's default token.
+
+        Args:
+            network: CAIP-2 network identifier
+            network_config: Network configuration
+
+        Returns:
+            TokenInfo for the selected token
+        """
+        if self._preferred_token:
+            if network_config.default_token.symbol == self._preferred_token:
+                return network_config.default_token
+        return network_config.default_token
+
+    def _parse_money_to_decimal(self, price: Union[str, int, float]) -> float:
+        """Parse a money value to a decimal float.
+
+        Handles:
+        - "$0.10" -> 0.10
+        - "0.10" -> 0.10
+        - 0.10 -> 0.10
+        - "1.50 USDT" -> 1.50
+
+        Args:
+            price: Price value to parse
+
+        Returns:
+            Decimal amount as float
+
+        Raises:
+            ValueError: If the price format is invalid
+        """
+        if isinstance(price, (int, float)):
+            return float(price)
+
+        if isinstance(price, str):
+            clean = price.strip()
+            clean = clean.lstrip("$").strip()
+
+            # Take only the numeric part (first token)
+            parts = clean.split()
+            if parts:
+                try:
+                    return float(parts[0])
+                except ValueError:
+                    raise ValueError(f"Failed to parse price string: '{price}'")
+
+        raise ValueError(f"Invalid price format: {price}")
+
+    def _to_atomic_units(self, amount: float, decimals: int) -> int:
+        """Convert a decimal amount to atomic units.
+
+        Args:
+            amount: Decimal amount (e.g., 1.50)
+            decimals: Number of decimal places (e.g., 6)
+
+        Returns:
+            Atomic amount as integer (e.g., 1500000)
+        """
+        multiplier = 10 ** decimals
+        return int(round(amount * multiplier))
+
+    def _parse_amount_string(self, amount_str: str, decimals: int) -> int:
+        """Parse a decimal amount string to atomic units.
+
+        Args:
+            amount_str: Amount as string (e.g., "1.50")
+            decimals: Number of decimal places
+
+        Returns:
+            Atomic amount as integer
+
+        Raises:
+            ValueError: If the amount string is invalid
+        """
+        try:
+            amount = float(amount_str)
+        except ValueError:
+            raise ValueError(f"Invalid amount: {amount_str}")
+
+        if amount < 0:
+            raise ValueError(f"Amount must be non-negative: {amount_str}")
+
+        return self._to_atomic_units(amount, decimals)

t402/schemes/polkadot/types.py

@@ -0,0 +1,385 @@
+"""Polkadot Scheme Types.
+
+This module defines types, payload structures, and validation utilities
+for the Polkadot exact-direct payment scheme.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Any, Dict, Optional, Protocol, runtime_checkable
+
+
+# SS58 address regex: base58 characters, typical length 45-50
+SS58_REGEX = re.compile(r"^[1-9A-HJ-NP-Za-km-z]{45,50}$")
+
+# Extrinsic/block hash regex: 0x-prefixed 64 hex characters (32 bytes)
+HASH_REGEX = re.compile(r"^0x[a-fA-F0-9]{64}$")
+
+
+@dataclass
+class ExactDirectPayload:
+    """Payment payload for the exact-direct scheme on Polkadot.
+
+    Contains the on-chain proof of a completed asset transfer.
+
+    Attributes:
+        extrinsic_hash: The 0x-prefixed hex hash of the submitted extrinsic
+        block_hash: The 0x-prefixed hex hash of the block containing the extrinsic
+        extrinsic_index: The index of the extrinsic within the block
+        from_address: The SS58-encoded sender address
+        to_address: The SS58-encoded recipient address
+        amount: The atomic amount transferred (as string)
+        asset_id: The on-chain asset ID (e.g., 1984 for USDT)
+    """
+
+    extrinsic_hash: str
+    block_hash: str
+    extrinsic_index: int
+    from_address: str
+    to_address: str
+    amount: str
+    asset_id: int
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert the payload to a dictionary suitable for JSON serialization.
+
+        Returns:
+            Dictionary with camelCase keys matching the protocol format
+        """
+        return {
+            "extrinsicHash": self.extrinsic_hash,
+            "blockHash": self.block_hash,
+            "extrinsicIndex": self.extrinsic_index,
+            "from": self.from_address,
+            "to": self.to_address,
+            "amount": self.amount,
+            "assetId": self.asset_id,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "ExactDirectPayload":
+        """Create an ExactDirectPayload from a dictionary.
+
+        Args:
+            data: Dictionary with payload fields (camelCase or snake_case)
+
+        Returns:
+            ExactDirectPayload instance
+
+        Raises:
+            KeyError: If required fields are missing
+            TypeError: If field types are incorrect
+        """
+        extrinsic_index = data.get("extrinsicIndex", data.get("extrinsic_index", 0))
+        if isinstance(extrinsic_index, float):
+            extrinsic_index = int(extrinsic_index)
+
+        asset_id = data.get("assetId", data.get("asset_id", 0))
+        if isinstance(asset_id, float):
+            asset_id = int(asset_id)
+
+        return cls(
+            extrinsic_hash=data.get("extrinsicHash", data.get("extrinsic_hash", "")),
+            block_hash=data.get("blockHash", data.get("block_hash", "")),
+            extrinsic_index=extrinsic_index,
+            from_address=data.get("from", data.get("from_address", "")),
+            to_address=data.get("to", data.get("to_address", "")),
+            amount=str(data.get("amount", "")),
+            asset_id=asset_id,
+        )
+
+
+@dataclass
+class ExtrinsicResult:
+    """Result of querying an extrinsic from the chain.
+
+    Represents the on-chain data for a submitted extrinsic,
+    including its parameters and success status.
+
+    Attributes:
+        extrinsic_hash: The 0x-prefixed hash of the extrinsic
+        block_hash: The 0x-prefixed hash of the containing block
+        block_number: The block number
+        extrinsic_index: Index within the block
+        success: Whether the extrinsic executed successfully
+        signer: The SS58-encoded address of the extrinsic signer
+        module: The pallet/module name (e.g., "Assets")
+        call: The call function name (e.g., "transfer_keep_alive")
+        params: List of call parameters
+    """
+
+    extrinsic_hash: str
+    block_hash: str
+    block_number: int
+    extrinsic_index: int
+    success: bool
+    signer: str
+    module: str
+    call: str
+    params: list
+
+
+@dataclass
+class ParsedAssetTransfer:
+    """Parsed asset transfer details extracted from an extrinsic.
+
+    Attributes:
+        asset_id: The on-chain asset ID
+        from_address: Sender SS58 address
+        to_address: Recipient SS58 address
+        amount: Transfer amount in atomic units (as string)
+        success: Whether the transfer succeeded
+    """
+
+    asset_id: int
+    from_address: str
+    to_address: str
+    amount: str
+    success: bool
+
+
+@runtime_checkable
+class ClientPolkadotSigner(Protocol):
+    """Protocol for signing and submitting Polkadot extrinsics.
+
+    Implementations should provide the signer's address and the ability
+    to build, sign, and submit asset transfer extrinsics to the chain.
+
+    Example:
+        ```python
+        class MyPolkadotSigner:
+            def address(self) -> str:
+                return "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY"
+
+            async def sign_and_submit(self, call: Dict, network: str) -> Dict:
+                # Build assets.transfer_keep_alive extrinsic
+                # Sign with keypair
+                # Submit to chain
+                return {
+                    "extrinsicHash": "0x...",
+                    "blockHash": "0x...",
+                    "extrinsicIndex": 2,
+                }
+        ```
+    """
+
+    def address(self) -> str:
+        """Return the SS58-encoded address of the signer.
+
+        Returns:
+            SS58-encoded address string
+        """
+        ...
+
+    async def sign_and_submit(self, call: Dict[str, Any], network: str) -> Dict[str, Any]:
+        """Sign and submit an asset transfer extrinsic.
+
+        The call dictionary contains:
+        - assetId: int - The on-chain asset ID
+        - target: str - The SS58-encoded recipient address
+        - amount: str - The atomic amount to transfer
+
+        Args:
+            call: Dictionary describing the assets.transfer_keep_alive call
+            network: CAIP-2 network identifier
+
+        Returns:
+            Dictionary with:
+            - extrinsicHash: str - 0x-prefixed hash of the extrinsic
+            - blockHash: str - 0x-prefixed hash of the block
+            - extrinsicIndex: int - Index within the block
+
+        Raises:
+            Exception: If signing or submission fails
+        """
+        ...
+
+
+@runtime_checkable
+class FacilitatorPolkadotSigner(Protocol):
+    """Protocol for facilitator-side Polkadot operations.
+
+    Implementations should provide the ability to query extrinsics
+    from the chain (via indexer or RPC).
+
+    Example:
+        ```python
+        class MyPolkadotFacilitator:
+            async def get_extrinsic(self, extrinsic_hash: str, network: str) -> Dict:
+                # Query Subscan or RPC for extrinsic details
+                return {
+                    "extrinsic_hash": "0x...",
+                    "block_hash": "0x...",
+                    "block_num": 12345,
+                    "extrinsic_index": 2,
+                    "success": True,
+                    "account_id": "5Grw...",
+                    "call_module": "Assets",
+                    "call_module_function": "transfer_keep_alive",
+                    "params": [...],
+                }
+        ```
+    """
+
+    async def get_extrinsic(self, extrinsic_hash: str, network: str) -> Dict[str, Any]:
+        """Query an extrinsic by its hash.
+
+        Args:
+            extrinsic_hash: The 0x-prefixed hex hash of the extrinsic
+            network: CAIP-2 network identifier
+
+        Returns:
+            Dictionary with extrinsic details including:
+            - extrinsic_hash: str
+            - block_hash: str
+            - block_num: int
+            - extrinsic_index: int
+            - success: bool
+            - account_id: str (signer address)
+            - call_module: str (e.g., "Assets")
+            - call_module_function: str (e.g., "transfer_keep_alive")
+            - params: list of parameter dicts
+
+        Raises:
+            Exception: If the extrinsic cannot be found or query fails
+        """
+        ...
+
+
+def is_valid_ss58_address(address: str) -> bool:
+    """Check if a string is a valid SS58-encoded Polkadot address.
+
+    Performs a basic format check using regex. Does not verify the checksum.
+
+    Args:
+        address: String to validate
+
+    Returns:
+        True if the address matches the SS58 format
+    """
+    if not address:
+        return False
+    return bool(SS58_REGEX.match(address))
+
+
+def is_valid_hash(hash_str: str) -> bool:
+    """Check if a string is a valid 0x-prefixed 32-byte hex hash.
+
+    Args:
+        hash_str: String to validate
+
+    Returns:
+        True if the hash matches the expected format
+    """
+    if not hash_str:
+        return False
+    return bool(HASH_REGEX.match(hash_str))
+
+
+def parse_asset_identifier(asset: str) -> Optional[int]:
+    """Parse a CAIP-19 asset identifier to extract the asset ID.
+
+    Format: "{network}/asset:{id}"
+    Example: "polkadot:68d56f15f85d3136970ec16946040bc1/asset:1984" -> 1984
+
+    Args:
+        asset: CAIP-19 asset identifier string
+
+    Returns:
+        The asset ID as an integer, or None if parsing fails
+    """
+    prefix = "/asset:"
+    idx = asset.find(prefix)
+    if idx == -1:
+        return None
+    try:
+        return int(asset[idx + len(prefix):])
+    except (ValueError, IndexError):
+        return None
+
+
+def create_asset_identifier(network: str, asset_id: int) -> str:
+    """Create a CAIP-19 asset identifier for a Polkadot asset.
+
+    Format: "{network}/asset:{id}"
+
+    Args:
+        network: CAIP-2 network identifier
+        asset_id: On-chain asset ID
+
+    Returns:
+        CAIP-19 asset identifier string
+    """
+    return f"{network}/asset:{asset_id}"
+
+
+def extract_asset_transfer(result: ExtrinsicResult) -> Optional[ParsedAssetTransfer]:
+    """Extract asset transfer details from an extrinsic result.
+
+    Validates that the extrinsic is a successful assets.transfer or
+    assets.transfer_keep_alive call, and extracts the transfer parameters.
+
+    Args:
+        result: ExtrinsicResult from chain query
+
+    Returns:
+        ParsedAssetTransfer if the extrinsic is a valid asset transfer,
+        None otherwise
+    """
+    if not result.success:
+        return None
+
+    # Check for assets module (case-insensitive)
+    module_lower = result.module.lower()
+    if module_lower != "assets":
+        return None
+
+    # Check for transfer call
+    call_lower = result.call.lower()
+    if call_lower not in ("transfer", "transfer_keep_alive"):
+        return None
+
+    asset_id: Optional[int] = None
+    to_address: Optional[str] = None
+    amount: Optional[str] = None
+
+    # Extract parameters
+    for param in result.params:
+        if not isinstance(param, dict):
+            continue
+
+        param_name = param.get("name", "")
+        param_value = param.get("value")
+
+        if param_name in ("id", "asset_id"):
+            if isinstance(param_value, (int, float)):
+                asset_id = int(param_value)
+            elif isinstance(param_value, str):
+                try:
+                    asset_id = int(param_value)
+                except ValueError:
+                    pass
+        elif param_name in ("target", "dest"):
+            if isinstance(param_value, str):
+                to_address = param_value
+            elif isinstance(param_value, dict):
+                # Handle MultiAddress enum format {"Id": "address"}
+                to_address = param_value.get("Id", param_value.get("id", ""))
+        elif param_name == "amount":
+            if isinstance(param_value, str):
+                amount = param_value
+            elif isinstance(param_value, (int, float)):
+                amount = str(int(param_value))
+
+    if asset_id is None or not to_address or not amount:
+        return None
+
+    return ParsedAssetTransfer(
+        asset_id=asset_id,
+        from_address=result.signer,
+        to_address=to_address,
+        amount=amount,
+        success=True,
+    )

t402/schemes/registry.py

@@ -270,7 +270,9 @@ class SchemeRegistry(Generic[T]):
             for pattern in self._patterns.get(v, []):
                 if _matches_network_pattern(pattern, network):
                     # Don't override exact matches
-                    for scheme_name, scheme in self._schemes[v].get(pattern, {}).items():
+                    for scheme_name, scheme in (
+                        self._schemes[v].get(pattern, {}).items()
+                    ):
                         if scheme_name not in result:
                             result[scheme_name] = scheme
 
@@ -411,7 +413,9 @@ class FacilitatorSchemeRegistry(SchemeRegistry[SchemeNetworkFacilitator]):
         with self._lock:
             for network, schemes in self._schemes.get(version, {}).items():
                 for scheme_name, scheme in schemes.items():
-                    if not hasattr(scheme, "caip_family") or not hasattr(scheme, "get_signers"):
+                    if not hasattr(scheme, "caip_family") or not hasattr(
+                        scheme, "get_signers"
+                    ):
                         continue
 
                     family = scheme.caip_family