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

t402/schemes/stacks/exact_direct/server.py

@@ -0,0 +1,292 @@
+"""Stacks Exact-Direct Scheme - Server Implementation.
+
+This module provides the server-side implementation of the exact-direct
+payment scheme for Stacks (Bitcoin L2) networks.
+
+The server:
+1. Parses user-friendly prices (e.g., "$0.10") into atomic amounts
+2. Enhances payment requirements with Stacks-specific metadata
+   (contract address, 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.stacks.constants import (
+    SCHEME_EXACT_DIRECT,
+    NetworkConfig,
+    TokenInfo,
+    get_network_config,
+    is_stacks_network,
+)
+from t402.schemes.stacks.types import create_asset_identifier
+
+
+class ExactDirectStacksServerScheme:
+    """Server scheme for Stacks exact-direct payments.
+
+    Handles parsing user-friendly prices into atomic amounts and
+    enhancing payment requirements with Stacks-specific metadata.
+
+    Example:
+        ```python
+        scheme = ExactDirectStacksServerScheme()
+
+        # Parse price to atomic units
+        asset_amount = await scheme.parse_price("$0.10", "stacks:1")
+        # Returns: {"amount": "100000", "asset": "stacks:1/token:SP3Y2...", "extra": {...}}
+
+        # Enhance requirements with metadata
+        enhanced = await scheme.enhance_requirements(
+            requirements,
+            supported_kind,
+            facilitator_extensions,
+        )
+        ```
+    """
+
+    scheme = SCHEME_EXACT_DIRECT
+    caip_family = "stacks:*"
+
+    def __init__(self, preferred_token: Optional[str] = None):
+        """Initialize the Stacks server scheme.
+
+        Args:
+            preferred_token: Override the default token symbol (e.g., "sUSDC")
+        """
+        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_stacks_network(network):
+            raise ValueError(f"Invalid Stacks 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.contract_address
+                )
+            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.contract_address)
+
+        # Build extra metadata
+        extra = {
+            "symbol": token.symbol,
+            "name": token.name,
+            "decimals": token.decimals,
+            "contractAddress": token.contract_address,
+        }
+
+        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 Stacks-specific metadata.
+
+        Adds asset metadata (contract address, 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 Stacks 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.contract_address)
+
+        # 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"]["contractAddress"] = token.contract_address
+        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 ("contractAddress", "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 sUSDC" -> 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/stacks/types.py

@@ -0,0 +1,380 @@
+"""Stacks Scheme Types.
+
+This module defines types, payload structures, and validation utilities
+for the Stacks exact-direct payment scheme.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Any, Dict, Optional, Protocol, runtime_checkable
+
+
+# Stacks address regex: SP/ST prefix followed by base58 characters
+# SP for mainnet, ST for testnet, typical length 39-41 characters total
+STACKS_ADDRESS_REGEX = re.compile(r"^S[PT][A-Z0-9]{38,40}$")
+
+# Transaction ID regex: 0x-prefixed 64 hex characters (32 bytes)
+TX_ID_REGEX = re.compile(r"^0x[a-fA-F0-9]{64}$")
+
+# Contract identifier regex: address.contract-name
+CONTRACT_ID_REGEX = re.compile(
+    r"^S[PT][A-Z0-9]{38,40}\.[a-zA-Z][a-zA-Z0-9\-]{0,127}$"
+)
+
+
+@dataclass
+class ExactDirectPayload:
+    """Payment payload for the exact-direct scheme on Stacks.
+
+    Contains the on-chain proof of a completed SIP-010 token transfer.
+
+    Attributes:
+        tx_id: The 0x-prefixed hex transaction ID
+        from_address: The sender's Stacks address
+        to_address: The recipient's Stacks address
+        amount: The atomic amount transferred (as string)
+        contract_address: The SIP-010 token contract identifier
+    """
+
+    tx_id: str
+    from_address: str
+    to_address: str
+    amount: str
+    contract_address: str
+
+    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 {
+            "txId": self.tx_id,
+            "from": self.from_address,
+            "to": self.to_address,
+            "amount": self.amount,
+            "contractAddress": self.contract_address,
+        }
+
+    @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
+        """
+        return cls(
+            tx_id=data.get("txId", data.get("tx_id", "")),
+            from_address=data.get("from", data.get("from_address", "")),
+            to_address=data.get("to", data.get("to_address", "")),
+            amount=str(data.get("amount", "")),
+            contract_address=data.get(
+                "contractAddress", data.get("contract_address", "")
+            ),
+        )
+
+
+@dataclass
+class TransactionResult:
+    """Result of querying a transaction from the Stacks chain.
+
+    Represents the on-chain data for a submitted transaction,
+    including its parameters and success status.
+
+    Attributes:
+        tx_id: The 0x-prefixed transaction ID
+        tx_status: Transaction status (e.g., "success", "pending")
+        sender_address: The sender's Stacks address
+        contract_call: Details of the contract call (if applicable)
+        block_height: Block height where the transaction was included
+        block_hash: Hash of the block
+    """
+
+    tx_id: str
+    tx_status: str
+    sender_address: str
+    contract_call: Optional[Dict[str, Any]]
+    block_height: int
+    block_hash: str
+
+
+@dataclass
+class ParsedTokenTransfer:
+    """Parsed SIP-010 token transfer details extracted from a transaction.
+
+    Attributes:
+        contract_address: The SIP-010 contract identifier
+        from_address: Sender Stacks address
+        to_address: Recipient Stacks address
+        amount: Transfer amount in atomic units (as string)
+        success: Whether the transfer succeeded
+    """
+
+    contract_address: str
+    from_address: str
+    to_address: str
+    amount: str
+    success: bool
+
+
+@runtime_checkable
+class ClientStacksSigner(Protocol):
+    """Protocol for signing and submitting Stacks token transfers.
+
+    Implementations should provide the signer's address and the ability
+    to execute SIP-010 token transfers on the Stacks chain.
+
+    Example:
+        ```python
+        class MyStacksSigner:
+            @property
+            def address(self) -> str:
+                return "SP3Y2ZSH8P7D50B0VBTSX11S7XSG24M1VB9YFQA4K"
+
+            async def transfer_token(
+                self, contract_address: str, to: str, amount: int
+            ) -> str:
+                # Build and submit SIP-010 transfer contract call
+                # Returns the transaction ID
+                return "0x..."
+        ```
+    """
+
+    @property
+    def address(self) -> str:
+        """Return the Stacks address of the signer.
+
+        Returns:
+            Stacks address string (SP... or ST...)
+        """
+        ...
+
+    async def transfer_token(
+        self, contract_address: str, to: str, amount: int
+    ) -> str:
+        """Execute a SIP-010 token transfer on-chain.
+
+        Builds a contract-call transaction for the SIP-010 `transfer`
+        function and submits it to the Stacks chain.
+
+        Args:
+            contract_address: The SIP-010 token contract identifier
+                (e.g., "SP3Y2ZSH8P7D50B0VBTSX11S7XSG24M1VB9YFQA4K.token-susdc")
+            to: The recipient's Stacks address
+            amount: The amount to transfer in atomic units
+
+        Returns:
+            The 0x-prefixed transaction ID
+
+        Raises:
+            Exception: If signing or submission fails
+        """
+        ...
+
+
+@runtime_checkable
+class FacilitatorStacksSigner(Protocol):
+    """Protocol for facilitator-side Stacks operations.
+
+    Implementations should provide the ability to query transactions
+    from the Stacks chain (via Hiro API or similar).
+
+    Example:
+        ```python
+        class MyStacksFacilitator:
+            def get_addresses(self, network: str) -> list[str]:
+                return ["SP3Y2ZSH8P7D50B0VBTSX11S7XSG24M1VB9YFQA4K"]
+
+            async def query_transaction(self, tx_id: str) -> dict | None:
+                # Query Hiro API for transaction details
+                return {
+                    "tx_id": "0x...",
+                    "tx_status": "success",
+                    "sender_address": "SP...",
+                    "contract_call": {
+                        "contract_id": "SP3Y2ZSH8P7D50B0VBTSX11S7XSG24M1VB9YFQA4K.token-susdc",
+                        "function_name": "transfer",
+                        "function_args": [...],
+                    },
+                    "block_height": 12345,
+                    "block_hash": "0x...",
+                }
+        ```
+    """
+
+    def get_addresses(self, network: str) -> list:
+        """Get the facilitator addresses for a given network.
+
+        Args:
+            network: CAIP-2 network identifier
+
+        Returns:
+            List of Stacks addresses for the facilitator on this network
+        """
+        ...
+
+    async def query_transaction(self, tx_id: str) -> Optional[Dict[str, Any]]:
+        """Query a transaction by its ID from the Stacks chain.
+
+        Args:
+            tx_id: The 0x-prefixed transaction ID
+
+        Returns:
+            Dictionary with transaction details, or None if not found.
+            Expected fields:
+            - tx_id: str
+            - tx_status: str ("success", "pending", "abort_by_response", etc.)
+            - sender_address: str
+            - contract_call: dict with contract_id, function_name, function_args
+            - block_height: int
+            - block_hash: str
+
+        Raises:
+            Exception: If the query fails
+        """
+        ...
+
+
+def is_valid_stacks_address(address: str) -> bool:
+    """Check if a string is a valid Stacks address.
+
+    Validates that the address starts with SP (mainnet) or ST (testnet)
+    followed by the expected base58 characters.
+
+    Args:
+        address: String to validate
+
+    Returns:
+        True if the address matches the Stacks address format
+    """
+    if not address:
+        return False
+    return bool(STACKS_ADDRESS_REGEX.match(address))
+
+
+def is_valid_tx_id(tx_id: str) -> bool:
+    """Check if a string is a valid Stacks transaction ID.
+
+    Transaction IDs are 0x-prefixed 64 hex character strings (32 bytes).
+
+    Args:
+        tx_id: String to validate
+
+    Returns:
+        True if the transaction ID matches the expected format
+    """
+    if not tx_id:
+        return False
+    return bool(TX_ID_REGEX.match(tx_id))
+
+
+def parse_contract_identifier(asset: str) -> Optional[str]:
+    """Parse a CAIP-19 asset identifier to extract the contract identifier.
+
+    Format: "{network}/token:{contract_id}"
+    Example: "stacks:1/token:SP3Y2ZSH8P7D50B0VBTSX11S7XSG24M1VB9YFQA4K.token-susdc"
+
+    Args:
+        asset: CAIP-19 asset identifier string
+
+    Returns:
+        The contract identifier string, or None if parsing fails
+    """
+    prefix = "/token:"
+    idx = asset.find(prefix)
+    if idx == -1:
+        return None
+    contract_id = asset[idx + len(prefix):]
+    if not contract_id:
+        return None
+    return contract_id
+
+
+def create_asset_identifier(network: str, contract_address: str) -> str:
+    """Create a CAIP-19 asset identifier for a Stacks SIP-010 token.
+
+    Format: "{network}/token:{contract_id}"
+
+    Args:
+        network: CAIP-2 network identifier
+        contract_address: SIP-010 contract identifier
+
+    Returns:
+        CAIP-19 asset identifier string
+    """
+    return f"{network}/token:{contract_address}"
+
+
+def extract_token_transfer(result: TransactionResult) -> Optional[ParsedTokenTransfer]:
+    """Extract SIP-010 token transfer details from a transaction result.
+
+    Validates that the transaction is a successful SIP-010 transfer
+    contract call and extracts the transfer parameters.
+
+    Args:
+        result: TransactionResult from chain query
+
+    Returns:
+        ParsedTokenTransfer if the transaction is a valid token transfer,
+        None otherwise
+    """
+    if result.tx_status != "success":
+        return None
+
+    if not result.contract_call:
+        return None
+
+    # Check for transfer function
+    function_name = result.contract_call.get("function_name", "")
+    if function_name != "transfer":
+        return None
+
+    contract_id = result.contract_call.get("contract_id", "")
+    if not contract_id:
+        return None
+
+    # Extract function arguments
+    function_args = result.contract_call.get("function_args", [])
+
+    amount: Optional[str] = None
+    to_address: Optional[str] = None
+
+    for arg in function_args:
+        if not isinstance(arg, dict):
+            continue
+
+        arg_name = arg.get("name", "")
+        arg_repr = arg.get("repr", "")
+
+        if arg_name == "amount":
+            # repr is like "u1000000" for uint
+            if arg_repr.startswith("u"):
+                amount = arg_repr[1:]
+            else:
+                amount = arg_repr
+        elif arg_name == "recipient" or arg_name == "to":
+            # repr is the principal address, strip leading '
+            if arg_repr.startswith("'"):
+                to_address = arg_repr[1:]
+            else:
+                to_address = arg_repr
+
+    if not amount or not to_address:
+        return None
+
+    return ParsedTokenTransfer(
+        contract_address=contract_id,
+        from_address=result.sender_address,
+        to_address=to_address,
+        amount=amount,
+        success=True,
+    )