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

t402/schemes/cosmos/exact_direct/facilitator.py

@@ -0,0 +1,493 @@
+"""Cosmos/Noble Exact-Direct Scheme - Facilitator Implementation.
+
+This module provides the facilitator-side implementation of the exact-direct
+payment scheme for Cosmos/Noble networks.
+
+The facilitator:
+1. Verifies the on-chain transaction by querying the Cosmos REST API.
+2. Confirms the transaction was a successful MsgSend with correct parameters.
+3. Marks the transaction as settled (already executed in exact-direct).
+
+Replay protection is built-in via an in-memory cache of used transaction hashes.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+import time
+from typing import Any, Dict, List, Optional, Union
+
+from t402.types import (
+    PaymentRequirementsV2,
+    PaymentPayloadV2,
+    VerifyResponse,
+    SettleResponse,
+    Network,
+)
+from t402.schemes.cosmos.constants import (
+    SCHEME_EXACT_DIRECT,
+    CAIP_FAMILY,
+    USDC_DENOM,
+    get_network_config,
+    is_valid_address,
+    is_valid_network,
+)
+from t402.schemes.cosmos.types import (
+    FacilitatorCosmosSigner,
+    ExactDirectPayload,
+)
+
+
+logger = logging.getLogger(__name__)
+
+
+class ExactDirectCosmosFacilitatorConfig:
+    """Configuration for the ExactDirectCosmosFacilitatorScheme.
+
+    Attributes:
+        max_transaction_age_seconds: Maximum age (in seconds) of a transaction to accept.
+            Default: 300 (5 minutes).
+        used_tx_cache_duration_seconds: How long (in seconds) to cache used transaction
+            hashes for replay protection. Default: 86400 (24 hours).
+    """
+
+    def __init__(
+        self,
+        max_transaction_age_seconds: int = 300,
+        used_tx_cache_duration_seconds: int = 86400,
+    ) -> None:
+        self.max_transaction_age_seconds = max_transaction_age_seconds
+        self.used_tx_cache_duration_seconds = used_tx_cache_duration_seconds
+
+
+class ExactDirectCosmosFacilitatorScheme:
+    """Facilitator scheme for Cosmos/Noble exact-direct payments.
+
+    Verifies that an on-chain bank MsgSend transaction was executed correctly
+    and marks it as settled. Since the client already executed the transfer,
+    settlement simply confirms the transaction is valid.
+
+    Features:
+    - Replay protection via used transaction hash cache.
+    - Validates transaction status, recipient, sender, denom, and amount.
+
+    Example:
+        ```python
+        class MyCosmosRPC:
+            def get_addresses(self, network: str) -> List[str]:
+                return ["noble1facilitator..."]
+
+            async def query_transaction(
+                self, network, tx_hash
+            ) -> TransactionResult:
+                # Query Cosmos REST API
+                ...
+
+            async def get_balance(
+                self, network, address, denom
+            ) -> str:
+                return "1000000"
+
+        rpc = MyCosmosRPC()
+        facilitator = ExactDirectCosmosFacilitatorScheme(rpc)
+
+        result = await facilitator.verify(payload, requirements)
+        if result.is_valid:
+            settlement = await facilitator.settle(payload, requirements)
+        ```
+    """
+
+    def __init__(
+        self,
+        signer: FacilitatorCosmosSigner,
+        config: Optional[ExactDirectCosmosFacilitatorConfig] = None,
+    ) -> None:
+        """Initialize the facilitator scheme.
+
+        Args:
+            signer: Any object implementing the FacilitatorCosmosSigner protocol.
+            config: Optional configuration. If not provided, defaults are used.
+        """
+        self._signer = signer
+        self._config = config or ExactDirectCosmosFacilitatorConfig()
+
+        # Used transaction cache for replay protection
+        self._used_txs: Dict[str, float] = {}
+        self._used_txs_lock = threading.Lock()
+
+        # Start cleanup thread
+        self._cleanup_thread = threading.Thread(
+            target=self._cleanup_used_txs,
+            daemon=True,
+            name="cosmos-facilitator-cleanup",
+        )
+        self._cleanup_thread.start()
+
+    @property
+    def scheme(self) -> str:
+        """The scheme identifier."""
+        return SCHEME_EXACT_DIRECT
+
+    @property
+    def caip_family(self) -> str:
+        """CAIP-2 family pattern for network matching."""
+        return CAIP_FAMILY
+
+    def get_extra(self, network: Network) -> Optional[Dict[str, Any]]:
+        """Get mechanism-specific extra data for supported kinds.
+
+        Returns the default token symbol, decimals, and denom for the network.
+
+        Args:
+            network: The network identifier.
+
+        Returns:
+            Dict with assetSymbol, assetDecimals, and assetDenom, or None if network unknown.
+        """
+        config = get_network_config(network)
+        if not config:
+            return None
+
+        return {
+            "assetSymbol": config.default_token.symbol,
+            "assetDecimals": config.default_token.decimals,
+            "assetDenom": config.default_token.denom,
+        }
+
+    def get_signers(self, network: Network) -> List[str]:
+        """Get signer addresses for this facilitator.
+
+        Args:
+            network: The network identifier.
+
+        Returns:
+            List of bech32-encoded Cosmos addresses.
+        """
+        return self._signer.get_addresses(network)
+
+    async def verify(
+        self,
+        payload: Union[PaymentPayloadV2, Dict[str, Any]],
+        requirements: Union[PaymentRequirementsV2, Dict[str, Any]],
+    ) -> VerifyResponse:
+        """Verify a payment payload by checking the on-chain transaction.
+
+        Validates:
+        1. Payload has correct structure with txHash and from fields.
+        2. Network is supported and addresses have correct bech32 prefix.
+        3. Transaction has not been used before (replay protection).
+        4. Transaction was successful on-chain (code == 0).
+        5. Transaction contains a MsgSend with correct recipient and sender.
+        6. The transfer amount for the expected denom is >= the required amount.
+
+        Args:
+            payload: The payment payload containing txHash and from.
+            requirements: The payment requirements to verify against.
+
+        Returns:
+            VerifyResponse indicating validity and payer address.
+        """
+        try:
+            payload_data = self._extract_payload(payload)
+            req_data = self._extract_requirements(requirements)
+
+            network = req_data.get("network", "")
+
+            # Validate network
+            if not is_valid_network(network):
+                return VerifyResponse(
+                    is_valid=False,
+                    invalid_reason=f"Unsupported network: {network}",
+                    payer=None,
+                )
+
+            network_config = get_network_config(network)
+            if network_config is None:
+                return VerifyResponse(
+                    is_valid=False,
+                    invalid_reason=f"Unsupported network: {network}",
+                    payer=None,
+                )
+
+            # Parse the Cosmos payload
+            cosmos_payload = ExactDirectPayload.from_map(payload_data)
+
+            # Validate required fields
+            if not cosmos_payload.tx_hash:
+                return VerifyResponse(
+                    is_valid=False,
+                    invalid_reason="Missing transaction hash in payload",
+                    payer=None,
+                )
+
+            if not cosmos_payload.from_address:
+                return VerifyResponse(
+                    is_valid=False,
+                    invalid_reason="Missing sender (from) in payload",
+                    payer=None,
+                )
+
+            # Validate address format
+            if not is_valid_address(cosmos_payload.from_address, network_config.bech32_prefix):
+                return VerifyResponse(
+                    is_valid=False,
+                    invalid_reason=f"Invalid sender address format: {cosmos_payload.from_address}",
+                    payer=cosmos_payload.from_address,
+                )
+
+            # Check for replay attack
+            if self._is_tx_used(cosmos_payload.tx_hash):
+                return VerifyResponse(
+                    is_valid=False,
+                    invalid_reason="Transaction has already been used",
+                    payer=cosmos_payload.from_address,
+                )
+
+            # Query the transaction from the Cosmos REST API
+            try:
+                tx_result = await self._signer.query_transaction(
+                    network=network,
+                    tx_hash=cosmos_payload.tx_hash,
+                )
+            except Exception as e:
+                return VerifyResponse(
+                    is_valid=False,
+                    invalid_reason=f"Transaction not found: {e}",
+                    payer=cosmos_payload.from_address,
+                )
+
+            # Verify transaction succeeded
+            if not tx_result.is_success():
+                return VerifyResponse(
+                    is_valid=False,
+                    invalid_reason=(
+                        f"Transaction failed on-chain: code={tx_result.code}, "
+                        f"log={tx_result.raw_log}"
+                    ),
+                    payer=cosmos_payload.from_address,
+                )
+
+            # Find MsgSend in the transaction
+            msg_send = tx_result.find_msg_send()
+            if msg_send is None:
+                return VerifyResponse(
+                    is_valid=False,
+                    invalid_reason="No bank send message found in transaction",
+                    payer=cosmos_payload.from_address,
+                )
+
+            # Determine expected denom
+            expected_denom = USDC_DENOM
+            required_asset = req_data.get("asset", "")
+            if required_asset and required_asset != "USDC":
+                # If asset is specified and not USDC symbol, treat it as denom
+                expected_denom = required_asset
+
+            # Verify recipient
+            required_pay_to = req_data.get("payTo") or req_data.get("pay_to", "")
+            if msg_send.to_address != required_pay_to:
+                return VerifyResponse(
+                    is_valid=False,
+                    invalid_reason=(
+                        f"Wrong recipient: expected {required_pay_to}, "
+                        f"got {msg_send.to_address}"
+                    ),
+                    payer=cosmos_payload.from_address,
+                )
+
+            # Verify sender
+            if msg_send.from_address != cosmos_payload.from_address:
+                return VerifyResponse(
+                    is_valid=False,
+                    invalid_reason=(
+                        f"Sender mismatch: expected {cosmos_payload.from_address}, "
+                        f"got {msg_send.from_address}"
+                    ),
+                    payer=cosmos_payload.from_address,
+                )
+
+            # Verify amount by denom
+            tx_amount_str = msg_send.get_amount_by_denom(expected_denom)
+            if not tx_amount_str:
+                return VerifyResponse(
+                    is_valid=False,
+                    invalid_reason=(
+                        f"Wrong denom: expected {expected_denom} not found in transaction"
+                    ),
+                    payer=cosmos_payload.from_address,
+                )
+
+            try:
+                tx_amount = int(tx_amount_str)
+            except (ValueError, TypeError):
+                return VerifyResponse(
+                    is_valid=False,
+                    invalid_reason=f"Invalid transaction amount: {tx_amount_str}",
+                    payer=cosmos_payload.from_address,
+                )
+
+            required_amount_str = req_data.get("amount", "0")
+            try:
+                required_amount = int(required_amount_str)
+            except (ValueError, TypeError):
+                return VerifyResponse(
+                    is_valid=False,
+                    invalid_reason=f"Invalid required amount: {required_amount_str}",
+                    payer=cosmos_payload.from_address,
+                )
+
+            if tx_amount < required_amount:
+                return VerifyResponse(
+                    is_valid=False,
+                    invalid_reason=(
+                        f"Insufficient amount: expected {required_amount}, "
+                        f"got {tx_amount}"
+                    ),
+                    payer=cosmos_payload.from_address,
+                )
+
+            # Mark transaction as used
+            self._mark_tx_used(cosmos_payload.tx_hash)
+
+            return VerifyResponse(
+                is_valid=True,
+                invalid_reason=None,
+                payer=cosmos_payload.from_address,
+            )
+
+        except Exception as e:
+            logger.error(f"Cosmos verification failed: {e}")
+            return VerifyResponse(
+                is_valid=False,
+                invalid_reason=f"Verification error: {str(e)}",
+                payer=None,
+            )
+
+    async def settle(
+        self,
+        payload: Union[PaymentPayloadV2, Dict[str, Any]],
+        requirements: Union[PaymentRequirementsV2, Dict[str, Any]],
+    ) -> SettleResponse:
+        """Settle a verified payment.
+
+        For exact-direct, the transfer was already executed by the client,
+        so settlement simply verifies the transaction and returns the tx hash.
+
+        Args:
+            payload: The verified payment payload.
+            requirements: The payment requirements.
+
+        Returns:
+            SettleResponse with the transaction hash and status.
+        """
+        try:
+            payload_data = self._extract_payload(payload)
+            req_data = self._extract_requirements(requirements)
+
+            network = req_data.get("network", "")
+            cosmos_payload = ExactDirectPayload.from_map(payload_data)
+
+            # Verify the transaction first
+            verify_result = await self.verify(payload, requirements)
+
+            if not verify_result.is_valid:
+                return SettleResponse(
+                    success=False,
+                    error_reason=verify_result.invalid_reason,
+                    transaction=None,
+                    network=network,
+                    payer=verify_result.payer,
+                )
+
+            # For exact-direct, settlement is already complete
+            return SettleResponse(
+                success=True,
+                error_reason=None,
+                transaction=cosmos_payload.tx_hash,
+                network=network,
+                payer=verify_result.payer,
+            )
+
+        except Exception as e:
+            logger.error(f"Cosmos settlement failed: {e}")
+            return SettleResponse(
+                success=False,
+                error_reason=f"Settlement error: {str(e)}",
+                transaction=None,
+                network=None,
+                payer=None,
+            )
+
+    def _is_tx_used(self, tx_hash: str) -> bool:
+        """Check if a transaction has been used (replay protection).
+
+        Args:
+            tx_hash: The transaction hash to check.
+
+        Returns:
+            True if the transaction has already been used.
+        """
+        with self._used_txs_lock:
+            return tx_hash in self._used_txs
+
+    def _mark_tx_used(self, tx_hash: str) -> None:
+        """Mark a transaction as used.
+
+        Args:
+            tx_hash: The transaction hash to mark.
+        """
+        with self._used_txs_lock:
+            self._used_txs[tx_hash] = time.time()
+
+    def _cleanup_used_txs(self) -> None:
+        """Periodically clean up old used transaction entries.
+
+        Runs in a background daemon thread.
+        """
+        while True:
+            time.sleep(3600)  # Clean up every hour
+            cutoff = time.time() - self._config.used_tx_cache_duration_seconds
+            with self._used_txs_lock:
+                expired = [
+                    tx_hash
+                    for tx_hash, used_at in self._used_txs.items()
+                    if used_at < cutoff
+                ]
+                for tx_hash in expired:
+                    del self._used_txs[tx_hash]
+
+    def _extract_payload(
+        self, payload: Union[PaymentPayloadV2, Dict[str, Any]]
+    ) -> Dict[str, Any]:
+        """Extract payload data as a dict.
+
+        Handles both PaymentPayloadV2 models and plain dicts.
+
+        Args:
+            payload: Payment payload (model or dict).
+
+        Returns:
+            Dict containing the inner payload data.
+        """
+        if hasattr(payload, "model_dump"):
+            data = payload.model_dump(by_alias=True)
+            return data.get("payload", data)
+        elif isinstance(payload, dict):
+            return payload.get("payload", payload)
+        return dict(payload)
+
+    def _extract_requirements(
+        self, requirements: Union[PaymentRequirementsV2, Dict[str, Any]]
+    ) -> Dict[str, Any]:
+        """Extract requirements data as a dict.
+
+        Args:
+            requirements: Payment requirements (model or dict).
+
+        Returns:
+            Dict containing requirement fields.
+        """
+        if hasattr(requirements, "model_dump"):
+            return requirements.model_dump(by_alias=True)
+        return dict(requirements)