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

t402/schemes/cosmos/constants.py

@@ -0,0 +1,211 @@
+"""Cosmos/Noble blockchain constants for the T402 protocol.
+
+This module contains network configurations, token denominations,
+and other constants used by the Cosmos exact-direct payment scheme.
+"""
+
+from __future__ import annotations
+
+from typing import Dict, Optional
+
+
+# Scheme identifier
+SCHEME_EXACT_DIRECT = "exact-direct"
+
+# CAIP-2 network identifiers
+# Noble is a Cosmos app-chain specifically built for native USDC issuance
+COSMOS_NOBLE_MAINNET = "cosmos:noble-1"
+COSMOS_NOBLE_TESTNET = "cosmos:grand-1"
+
+# RPC endpoints
+NOBLE_MAINNET_RPC = "https://noble-rpc.polkachu.com"
+NOBLE_TESTNET_RPC = "https://rpc.testnet.noble.strange.love"
+
+# REST API endpoints
+NOBLE_MAINNET_REST = "https://noble-api.polkachu.com"
+NOBLE_TESTNET_REST = "https://api.testnet.noble.strange.love"
+
+# Address prefix (bech32)
+NOBLE_BECH32_PREFIX = "noble"
+
+# USDC denom on Noble (micro USDC: 1 USDC = 1,000,000 uusdc)
+USDC_DENOM = "uusdc"
+
+# Gas settings
+DEFAULT_GAS_LIMIT = 200000
+DEFAULT_GAS_PRICE = "0.025uusdc"
+DEFAULT_FEE_AMOUNT = "5000"  # 0.005 USDC
+DEFAULT_FEE_DENOM = USDC_DENOM
+
+# Message types
+MSG_TYPE_SEND = "/cosmos.bank.v1beta1.MsgSend"
+MSG_TYPE_MULTI_SEND = "/cosmos.bank.v1beta1.MsgMultiSend"
+
+# CAIP family pattern
+CAIP_FAMILY = "cosmos:*"
+
+
+class TokenInfo:
+    """Contains information about a Cosmos token.
+
+    Attributes:
+        denom: The token denomination (e.g., "uusdc").
+        symbol: The token symbol (e.g., "USDC").
+        decimals: The number of decimal places for the token.
+    """
+
+    def __init__(self, denom: str, symbol: str, decimals: int) -> None:
+        self.denom = denom
+        self.symbol = symbol
+        self.decimals = decimals
+
+    def __repr__(self) -> str:
+        return f"TokenInfo(denom={self.denom!r}, symbol={self.symbol!r}, decimals={self.decimals})"
+
+
+class NetworkConfig:
+    """Network-specific configuration for Cosmos.
+
+    Attributes:
+        chain_id: The Cosmos chain ID (e.g., "noble-1").
+        rpc_url: The RPC endpoint URL.
+        rest_url: The REST API endpoint URL.
+        bech32_prefix: The bech32 address prefix (e.g., "noble").
+        default_token: The default token for this network.
+    """
+
+    def __init__(
+        self,
+        chain_id: str,
+        rpc_url: str,
+        rest_url: str,
+        bech32_prefix: str,
+        default_token: TokenInfo,
+    ) -> None:
+        self.chain_id = chain_id
+        self.rpc_url = rpc_url
+        self.rest_url = rest_url
+        self.bech32_prefix = bech32_prefix
+        self.default_token = default_token
+
+
+# Token definitions
+USDC_TOKEN = TokenInfo(
+    denom=USDC_DENOM,
+    symbol="USDC",
+    decimals=6,
+)
+
+# Network configurations
+NETWORK_CONFIGS: Dict[str, NetworkConfig] = {
+    COSMOS_NOBLE_MAINNET: NetworkConfig(
+        chain_id="noble-1",
+        rpc_url=NOBLE_MAINNET_RPC,
+        rest_url=NOBLE_MAINNET_REST,
+        bech32_prefix=NOBLE_BECH32_PREFIX,
+        default_token=USDC_TOKEN,
+    ),
+    COSMOS_NOBLE_TESTNET: NetworkConfig(
+        chain_id="grand-1",
+        rpc_url=NOBLE_TESTNET_RPC,
+        rest_url=NOBLE_TESTNET_REST,
+        bech32_prefix=NOBLE_BECH32_PREFIX,
+        default_token=USDC_TOKEN,
+    ),
+}
+
+# Token registry: network -> symbol -> TokenInfo
+TOKEN_REGISTRY: Dict[str, Dict[str, TokenInfo]] = {
+    COSMOS_NOBLE_MAINNET: {
+        "USDC": USDC_TOKEN,
+    },
+    COSMOS_NOBLE_TESTNET: {
+        "USDC": USDC_TOKEN,
+    },
+}
+
+
+def get_network_config(network: str) -> Optional[NetworkConfig]:
+    """Get the configuration for a Cosmos network.
+
+    Args:
+        network: The CAIP-2 network identifier (e.g., "cosmos:noble-1").
+
+    Returns:
+        NetworkConfig if the network is supported, None otherwise.
+    """
+    return NETWORK_CONFIGS.get(network)
+
+
+def is_valid_network(network: str) -> bool:
+    """Check if a network identifier is a supported Cosmos network.
+
+    Args:
+        network: The CAIP-2 network identifier.
+
+    Returns:
+        True if the network is supported.
+    """
+    return network in NETWORK_CONFIGS
+
+
+def get_token_info(network: str, symbol: str) -> Optional[TokenInfo]:
+    """Get token info for a network and symbol.
+
+    Args:
+        network: The CAIP-2 network identifier.
+        symbol: The token symbol (e.g., "USDC").
+
+    Returns:
+        TokenInfo if found, None otherwise.
+    """
+    tokens = TOKEN_REGISTRY.get(network)
+    if tokens is None:
+        return None
+    return tokens.get(symbol)
+
+
+def get_token_by_denom(network: str, denom: str) -> Optional[TokenInfo]:
+    """Get token info by denomination.
+
+    Args:
+        network: The CAIP-2 network identifier.
+        denom: The token denomination (e.g., "uusdc").
+
+    Returns:
+        TokenInfo if found, None otherwise.
+    """
+    tokens = TOKEN_REGISTRY.get(network)
+    if tokens is None:
+        return None
+    for token in tokens.values():
+        if token.denom == denom:
+            return token
+    return None
+
+
+def is_valid_address(address: str, expected_prefix: str) -> bool:
+    """Check if an address has the correct bech32 prefix.
+
+    Validates that the address starts with the expected prefix followed by "1"
+    (the bech32 separator) and has sufficient length.
+
+    Args:
+        address: The bech32 address to validate.
+        expected_prefix: The expected prefix (e.g., "noble").
+
+    Returns:
+        True if the address has the correct prefix format.
+    """
+    if not address or len(address) < len(expected_prefix) + 1:
+        return False
+    return address[:len(expected_prefix)] == expected_prefix
+
+
+def get_supported_networks() -> list:
+    """Get a list of supported Cosmos network identifiers.
+
+    Returns:
+        List of CAIP-2 network identifier strings.
+    """
+    return [COSMOS_NOBLE_MAINNET, COSMOS_NOBLE_TESTNET]

t402/schemes/cosmos/exact_direct/__init__.py

@@ -0,0 +1,21 @@
+"""Cosmos/Noble Exact-Direct Payment Scheme.
+
+This package provides the exact-direct payment scheme implementation for Cosmos/Noble.
+In this scheme, the client executes a bank MsgSend on-chain directly,
+and the transaction hash is used as proof of payment.
+
+Components:
+    - ExactDirectCosmosClientScheme: Client-side (executes transfer, returns tx hash)
+    - ExactDirectCosmosServerScheme: Server-side (parses prices, enhances requirements)
+    - ExactDirectCosmosFacilitatorScheme: Facilitator-side (verifies tx, marks settled)
+"""
+
+from t402.schemes.cosmos.exact_direct.client import ExactDirectCosmosClientScheme
+from t402.schemes.cosmos.exact_direct.server import ExactDirectCosmosServerScheme
+from t402.schemes.cosmos.exact_direct.facilitator import ExactDirectCosmosFacilitatorScheme
+
+__all__ = [
+    "ExactDirectCosmosClientScheme",
+    "ExactDirectCosmosServerScheme",
+    "ExactDirectCosmosFacilitatorScheme",
+]

t402/schemes/cosmos/exact_direct/client.py

@@ -0,0 +1,198 @@
+"""Cosmos/Noble Exact-Direct Scheme - Client Implementation.
+
+This module provides the client-side implementation of the exact-direct payment
+scheme for Cosmos/Noble networks using bank MsgSend.
+
+Unlike other schemes where the client creates a signed message for the facilitator
+to execute, the exact-direct scheme has the client execute the transfer directly.
+The transaction hash is then used as proof of payment.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, Optional, Union
+
+from t402.types import PaymentRequirementsV2
+from t402.schemes.cosmos.constants import (
+    SCHEME_EXACT_DIRECT,
+    CAIP_FAMILY,
+    USDC_DENOM,
+    is_valid_network,
+    is_valid_address,
+    get_network_config,
+    get_token_info,
+)
+from t402.schemes.cosmos.types import (
+    ClientCosmosSigner,
+    ExactDirectPayload,
+)
+
+
+logger = logging.getLogger(__name__)
+
+
+class ExactDirectCosmosClientConfig:
+    """Configuration for the ExactDirectCosmosClientScheme.
+
+    Attributes:
+        memo: Optional memo to include in the transaction.
+    """
+
+    def __init__(
+        self,
+        memo: Optional[str] = None,
+    ) -> None:
+        self.memo = memo
+
+
+class ExactDirectCosmosClientScheme:
+    """Client scheme for Cosmos/Noble exact-direct payments using bank MsgSend.
+
+    This scheme executes the token transfer on-chain directly and returns the
+    transaction hash as proof of payment. The facilitator then verifies the
+    transaction was successful.
+
+    Example:
+        ```python
+        class MyCosmosSigner:
+            def address(self) -> str:
+                return "noble1abc..."
+
+            async def send_tokens(
+                self, network, to, amount, denom
+            ) -> str:
+                # Execute the transaction
+                return "AABB1122..."
+
+        signer = MyCosmosSigner()
+        scheme = ExactDirectCosmosClientScheme(signer)
+
+        payload = await scheme.create_payment_payload(
+            t402_version=2,
+            requirements=requirements,
+        )
+        ```
+    """
+
+    def __init__(
+        self,
+        signer: ClientCosmosSigner,
+        config: Optional[ExactDirectCosmosClientConfig] = None,
+    ) -> None:
+        """Initialize with a Cosmos signer.
+
+        Args:
+            signer: Any object implementing the ClientCosmosSigner protocol.
+            config: Optional configuration for the client scheme.
+        """
+        self._signer = signer
+        self._config = config or ExactDirectCosmosClientConfig()
+
+    @property
+    def scheme(self) -> str:
+        """The scheme identifier."""
+        return SCHEME_EXACT_DIRECT
+
+    @property
+    def caip_family(self) -> str:
+        """The CAIP-2 family pattern for Cosmos networks."""
+        return CAIP_FAMILY
+
+    @property
+    def signer_address(self) -> str:
+        """Get the signer's Cosmos address."""
+        return self._signer.address()
+
+    async def create_payment_payload(
+        self,
+        t402_version: int,
+        requirements: Union[PaymentRequirementsV2, Dict[str, Any]],
+    ) -> Dict[str, Any]:
+        """Create a payment payload by executing a bank send on-chain.
+
+        Executes a Cosmos bank MsgSend to the specified recipient and returns
+        the transaction hash as proof of payment.
+
+        Args:
+            t402_version: The T402 protocol version.
+            requirements: Payment requirements with amount, asset, payTo, network.
+
+        Returns:
+            Dict with t402Version and payload containing txHash, from, to, amount.
+
+        Raises:
+            ValueError: If requirements are invalid (bad network, missing fields,
+                invalid addresses).
+            RuntimeError: If the transaction execution fails.
+        """
+        # Extract requirements as dict
+        if hasattr(requirements, "model_dump"):
+            req = requirements.model_dump(by_alias=True)
+        else:
+            req = dict(requirements)
+
+        network = req.get("network", "")
+        asset = req.get("asset", "")
+        pay_to = req.get("payTo") or req.get("pay_to", "")
+        amount = req.get("amount", "")
+
+        # Validate network
+        if not is_valid_network(network):
+            raise ValueError(f"Unsupported network: {network}")
+
+        # Get network config for address validation
+        config = get_network_config(network)
+        if config is None:
+            raise ValueError(f"Unsupported network: {network}")
+
+        # Validate required fields
+        if not pay_to:
+            raise ValueError("payTo address is required")
+        if not amount:
+            raise ValueError("Amount is required")
+
+        # Determine denom
+        denom = USDC_DENOM
+        if asset:
+            # Check if asset is a symbol or denom
+            token = get_token_info(network, asset)
+            if token:
+                denom = token.denom
+            else:
+                # Assume it's already a denom
+                denom = asset
+
+        # Validate recipient address
+        if not is_valid_address(pay_to, config.bech32_prefix):
+            raise ValueError(f"Invalid recipient address: {pay_to}")
+
+        # Validate sender address
+        sender = self._signer.address()
+        if not is_valid_address(sender, config.bech32_prefix):
+            raise ValueError(f"Invalid sender address: {sender}")
+
+        # Execute the transfer via the signer
+        try:
+            tx_hash = await self._signer.send_tokens(
+                network=network,
+                to=pay_to,
+                amount=amount,
+                denom=denom,
+            )
+        except Exception as e:
+            raise RuntimeError(f"Failed to send tokens: {e}") from e
+
+        # Build the payload
+        payload = ExactDirectPayload(
+            tx_hash=tx_hash,
+            from_address=sender,
+            to_address=pay_to,
+            amount=amount,
+            denom=denom,
+        )
+
+        return {
+            "t402Version": t402_version,
+            "payload": payload.to_map(),
+        }