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

t402/schemes/near/constants.py

@@ -0,0 +1,189 @@
+"""NEAR blockchain constants for the T402 protocol.
+
+This module contains network configurations, token contract addresses,
+and other constants used by the NEAR exact-direct payment scheme.
+"""
+
+from __future__ import annotations
+
+from typing import Dict, Optional
+
+
+# Scheme identifier
+SCHEME_EXACT_DIRECT = "exact-direct"
+
+# CAIP-2 network identifiers
+NEAR_MAINNET = "near:mainnet"
+NEAR_TESTNET = "near:testnet"
+
+# RPC endpoints
+NEAR_MAINNET_RPC = "https://rpc.mainnet.near.org"
+NEAR_TESTNET_RPC = "https://rpc.testnet.near.org"
+
+# Default gas for ft_transfer (30 TGas)
+DEFAULT_GAS = "30000000000000"
+DEFAULT_GAS_INT = 30_000_000_000_000
+
+# Storage deposit required (1 yoctoNEAR) for ft_transfer
+STORAGE_DEPOSIT = "1"
+
+# NEP-141 function names
+FUNCTION_FT_TRANSFER = "ft_transfer"
+FUNCTION_FT_BALANCE_OF = "ft_balance_of"
+FUNCTION_STORAGE_BALANCE = "storage_balance_of"
+
+# CAIP family pattern
+CAIP_FAMILY = "near:*"
+
+
+class TokenInfo:
+    """Contains information about a NEAR fungible token.
+
+    Attributes:
+        contract_id: The NEAR account ID of the token contract.
+        symbol: The token symbol (e.g., "USDT").
+        decimals: The number of decimal places for the token.
+    """
+
+    def __init__(self, contract_id: str, symbol: str, decimals: int) -> None:
+        self.contract_id = contract_id
+        self.symbol = symbol
+        self.decimals = decimals
+
+    def __repr__(self) -> str:
+        return f"TokenInfo(contract_id={self.contract_id!r}, symbol={self.symbol!r}, decimals={self.decimals})"
+
+
+class NetworkConfig:
+    """Network-specific configuration for NEAR.
+
+    Attributes:
+        network_id: The short network identifier (e.g., "mainnet").
+        rpc_url: The RPC endpoint URL.
+        default_token: The default token for this network.
+    """
+
+    def __init__(self, network_id: str, rpc_url: str, default_token: TokenInfo) -> None:
+        self.network_id = network_id
+        self.rpc_url = rpc_url
+        self.default_token = default_token
+
+
+# Token definitions
+USDT_MAINNET = TokenInfo(
+    contract_id="usdt.tether-token.near",
+    symbol="USDT",
+    decimals=6,
+)
+
+USDT_TESTNET = TokenInfo(
+    contract_id="usdt.fakes.testnet",
+    symbol="USDT",
+    decimals=6,
+)
+
+USDC_MAINNET = TokenInfo(
+    contract_id="17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1",
+    symbol="USDC",
+    decimals=6,
+)
+
+USDC_TESTNET = TokenInfo(
+    contract_id="usdc.fakes.testnet",
+    symbol="USDC",
+    decimals=6,
+)
+
+# Network configurations
+NETWORK_CONFIGS: Dict[str, NetworkConfig] = {
+    NEAR_MAINNET: NetworkConfig(
+        network_id="mainnet",
+        rpc_url=NEAR_MAINNET_RPC,
+        default_token=USDT_MAINNET,
+    ),
+    NEAR_TESTNET: NetworkConfig(
+        network_id="testnet",
+        rpc_url=NEAR_TESTNET_RPC,
+        default_token=USDT_TESTNET,
+    ),
+}
+
+# Token registry: network -> symbol -> TokenInfo
+TOKEN_REGISTRY: Dict[str, Dict[str, TokenInfo]] = {
+    NEAR_MAINNET: {
+        "USDT": USDT_MAINNET,
+        "USDC": USDC_MAINNET,
+    },
+    NEAR_TESTNET: {
+        "USDT": USDT_TESTNET,
+        "USDC": USDC_TESTNET,
+    },
+}
+
+
+def get_network_config(network: str) -> Optional[NetworkConfig]:
+    """Get the configuration for a NEAR network.
+
+    Args:
+        network: The CAIP-2 network identifier (e.g., "near:mainnet").
+
+    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 NEAR 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., "USDT").
+
+    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_contract(network: str, contract_id: str) -> Optional[TokenInfo]:
+    """Get token info by contract address.
+
+    Args:
+        network: The CAIP-2 network identifier.
+        contract_id: The token contract account ID.
+
+    Returns:
+        TokenInfo if found, None otherwise.
+    """
+    tokens = TOKEN_REGISTRY.get(network)
+    if tokens is None:
+        return None
+    for token in tokens.values():
+        if token.contract_id == contract_id:
+            return token
+    return None
+
+
+def get_supported_networks() -> list:
+    """Get a list of supported NEAR network identifiers.
+
+    Returns:
+        List of CAIP-2 network identifier strings.
+    """
+    return [NEAR_MAINNET, NEAR_TESTNET]

t402/schemes/near/exact_direct/__init__.py

@@ -0,0 +1,21 @@
+"""NEAR Exact-Direct Payment Scheme.
+
+This package provides the exact-direct payment scheme implementation for NEAR.
+In this scheme, the client executes the NEP-141 ft_transfer on-chain directly,
+and the transaction hash is used as proof of payment.
+
+Components:
+    - ExactDirectNearClientScheme: Client-side (executes transfer, returns tx hash)
+    - ExactDirectNearServerScheme: Server-side (parses prices, enhances requirements)
+    - ExactDirectNearFacilitatorScheme: Facilitator-side (verifies tx, marks settled)
+"""
+
+from t402.schemes.near.exact_direct.client import ExactDirectNearClientScheme
+from t402.schemes.near.exact_direct.server import ExactDirectNearServerScheme
+from t402.schemes.near.exact_direct.facilitator import ExactDirectNearFacilitatorScheme
+
+__all__ = [
+    "ExactDirectNearClientScheme",
+    "ExactDirectNearServerScheme",
+    "ExactDirectNearFacilitatorScheme",
+]

t402/schemes/near/exact_direct/client.py

@@ -0,0 +1,204 @@
+"""NEAR Exact-Direct Scheme - Client Implementation.
+
+This module provides the client-side implementation of the exact-direct payment
+scheme for NEAR networks using NEP-141 ft_transfer.
+
+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 json
+import logging
+from typing import Any, Dict, List, Optional, Union
+
+from t402.types import PaymentRequirementsV2
+from t402.schemes.near.constants import (
+    SCHEME_EXACT_DIRECT,
+    CAIP_FAMILY,
+    DEFAULT_GAS_INT,
+    STORAGE_DEPOSIT,
+    FUNCTION_FT_TRANSFER,
+    is_valid_network,
+)
+from t402.schemes.near.types import (
+    ClientNearSigner,
+    ExactDirectPayload,
+    is_valid_account_id,
+)
+
+
+logger = logging.getLogger(__name__)
+
+
+class ExactDirectNearClientConfig:
+    """Configuration for the ExactDirectNearClientScheme.
+
+    Attributes:
+        memo: Optional memo to include in the ft_transfer call.
+        gas_amount: Gas to attach to the ft_transfer call (default: 30 TGas).
+    """
+
+    def __init__(
+        self,
+        memo: Optional[str] = None,
+        gas_amount: Optional[int] = None,
+    ) -> None:
+        self.memo = memo
+        self.gas_amount = gas_amount or DEFAULT_GAS_INT
+
+
+class ExactDirectNearClientScheme:
+    """Client scheme for NEAR exact-direct payments using NEP-141 ft_transfer.
+
+    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 MyNearSigner:
+            def account_id(self) -> str:
+                return "alice.near"
+
+            async def sign_and_send_transaction(
+                self, receiver_id, actions, network
+            ) -> str:
+                # Execute the transaction
+                return "Abc123TxHash..."
+
+        signer = MyNearSigner()
+        scheme = ExactDirectNearClientScheme(signer)
+
+        payload = await scheme.create_payment_payload(
+            t402_version=2,
+            requirements=requirements,
+        )
+        ```
+    """
+
+    def __init__(
+        self,
+        signer: ClientNearSigner,
+        config: Optional[ExactDirectNearClientConfig] = None,
+    ) -> None:
+        """Initialize with a NEAR signer.
+
+        Args:
+            signer: Any object implementing the ClientNearSigner protocol.
+            config: Optional configuration for the client scheme.
+        """
+        self._signer = signer
+        self._config = config or ExactDirectNearClientConfig()
+
+    @property
+    def scheme(self) -> str:
+        """The scheme identifier."""
+        return SCHEME_EXACT_DIRECT
+
+    @property
+    def caip_family(self) -> str:
+        """The CAIP-2 family pattern for NEAR networks."""
+        return CAIP_FAMILY
+
+    @property
+    def account_id(self) -> str:
+        """Get the signer's NEAR account ID."""
+        return self._signer.account_id()
+
+    async def create_payment_payload(
+        self,
+        t402_version: int,
+        requirements: Union[PaymentRequirementsV2, Dict[str, Any]],
+    ) -> Dict[str, Any]:
+        """Create a payment payload by executing ft_transfer on-chain.
+
+        Executes a NEP-141 ft_transfer 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 account IDs).
+            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}")
+
+        # Validate required fields
+        if not asset:
+            raise ValueError("Asset (token contract address) is required")
+        if not pay_to:
+            raise ValueError("payTo address is required")
+        if not amount:
+            raise ValueError("Amount is required")
+
+        # Validate account IDs
+        if not is_valid_account_id(pay_to):
+            raise ValueError(f"Invalid recipient account ID: {pay_to}")
+        sender_id = self._signer.account_id()
+        if not is_valid_account_id(sender_id):
+            raise ValueError(f"Invalid sender account ID: {sender_id}")
+
+        # Build ft_transfer arguments
+        ft_transfer_args: Dict[str, Any] = {
+            "receiver_id": pay_to,
+            "amount": amount,
+        }
+        if self._config.memo:
+            ft_transfer_args["memo"] = self._config.memo
+
+        # Build the function call action
+        actions: List[Dict[str, Any]] = [
+            {
+                "FunctionCall": {
+                    "method_name": FUNCTION_FT_TRANSFER,
+                    "args": json.dumps(ft_transfer_args),
+                    "gas": self._config.gas_amount,
+                    "deposit": STORAGE_DEPOSIT,
+                }
+            }
+        ]
+
+        # Execute the transfer via the signer
+        try:
+            tx_hash = await self._signer.sign_and_send_transaction(
+                receiver_id=asset,
+                actions=actions,
+                network=network,
+            )
+        except Exception as e:
+            raise RuntimeError(f"Failed to execute ft_transfer: {e}") from e
+
+        # Build the payload
+        payload = ExactDirectPayload(
+            tx_hash=tx_hash,
+            from_account=sender_id,
+            to_account=pay_to,
+            amount=amount,
+        )
+
+        return {
+            "t402Version": t402_version,
+            "payload": payload.to_map(),
+        }