t402 1.6.0__py3-none-any.whl → 1.6.1__py3-none-any.whl

t402/__init__.py

@@ -64,11 +64,15 @@ from t402.tron import (
     is_testnet as is_tron_testnet,
 )
 from t402.svm import (
+    # Constants
     SOLANA_MAINNET,
     SOLANA_DEVNET,
     SOLANA_TESTNET,
     USDC_MAINNET_ADDRESS as SVM_USDC_MAINNET_ADDRESS,
     USDC_DEVNET_ADDRESS as SVM_USDC_DEVNET_ADDRESS,
+    TOKEN_PROGRAM_ADDRESS as SVM_TOKEN_PROGRAM_ADDRESS,
+    TOKEN_2022_PROGRAM_ADDRESS as SVM_TOKEN_2022_PROGRAM_ADDRESS,
+    # Address/Network utilities
     validate_svm_address,
     get_usdc_address as get_svm_usdc_address,
     get_network_config as get_svm_network_config,
@@ -80,6 +84,34 @@ from t402.svm import (
     validate_transaction as validate_svm_transaction,
     normalize_network as normalize_svm_network,
     get_rpc_url as get_svm_rpc_url,
+    # Transaction utilities
+    decode_transaction as decode_svm_transaction,
+    decode_versioned_transaction,
+    encode_transaction as encode_svm_transaction,
+    get_transaction_fee_payer as get_svm_fee_payer,
+    get_token_payer_from_transaction as get_svm_token_payer,
+    parse_transfer_checked_instruction,
+    TransferDetails as SvmTransferDetails,
+    # Signer interfaces and implementations
+    ClientSvmSigner,
+    FacilitatorSvmSigner,
+    KeypairSvmSigner,
+    RpcSvmSigner,
+    # Scheme implementations
+    ExactSvmClientScheme,
+    ExactSvmServerScheme,
+    ExactSvmFacilitatorScheme,
+    # Factory functions
+    create_client_scheme as create_svm_client_scheme,
+    create_server_scheme as create_svm_server_scheme,
+    create_facilitator_scheme as create_svm_facilitator_scheme,
+    check_solana_available,
+    # Types
+    SvmAuthorization,
+    SvmPaymentPayload,
+    SvmVerifyMessageResult,
+    SvmTransactionConfirmation,
+    ExactSvmPayloadV2,
 )
 from t402.paywall import (
     get_paywall_html,
@@ -235,12 +267,15 @@ __all__ = [
     "parse_tron_amount",
     "format_tron_amount",
     "is_tron_testnet",
-    # SVM (Solana) utilities
+    # SVM (Solana) utilities - Constants
     "SOLANA_MAINNET",
     "SOLANA_DEVNET",
     "SOLANA_TESTNET",
     "SVM_USDC_MAINNET_ADDRESS",
     "SVM_USDC_DEVNET_ADDRESS",
+    "SVM_TOKEN_PROGRAM_ADDRESS",
+    "SVM_TOKEN_2022_PROGRAM_ADDRESS",
+    # SVM - Address/Network utilities
     "validate_svm_address",
     "get_svm_usdc_address",
     "get_svm_network_config",
@@ -252,6 +287,34 @@ __all__ = [
     "validate_svm_transaction",
     "normalize_svm_network",
     "get_svm_rpc_url",
+    # SVM - Transaction utilities
+    "decode_svm_transaction",
+    "decode_versioned_transaction",
+    "encode_svm_transaction",
+    "get_svm_fee_payer",
+    "get_svm_token_payer",
+    "parse_transfer_checked_instruction",
+    "SvmTransferDetails",
+    # SVM - Signer interfaces
+    "ClientSvmSigner",
+    "FacilitatorSvmSigner",
+    "KeypairSvmSigner",
+    "RpcSvmSigner",
+    # SVM - Scheme implementations
+    "ExactSvmClientScheme",
+    "ExactSvmServerScheme",
+    "ExactSvmFacilitatorScheme",
+    # SVM - Factory functions
+    "create_svm_client_scheme",
+    "create_svm_server_scheme",
+    "create_svm_facilitator_scheme",
+    "check_solana_available",
+    # SVM - Types
+    "SvmAuthorization",
+    "SvmPaymentPayload",
+    "SvmVerifyMessageResult",
+    "SvmTransactionConfirmation",
+    "ExactSvmPayloadV2",
     # Paywall
     "get_paywall_html",
     "get_paywall_template",

t402/svm.py

@@ -3,6 +3,13 @@ Solana SVM blockchain support for t402 protocol.
 
 This module provides types and utilities for Solana payments
 using SPL token transfers.
+
+Features:
+- Client scheme for creating payment payloads
+- Server scheme for parsing prices and requirements
+- Facilitator scheme for verifying and settling payments
+- Signer interfaces for key management
+- Transaction utilities for validation and parsing
 """
 
 from __future__ import annotations
@@ -10,12 +17,35 @@ from __future__ import annotations
 import re
 import time
 import base64
-from typing import Any, Dict, Optional, List
+from typing import Any, Dict, Optional, List, Callable, Awaitable, Protocol, runtime_checkable
 from typing_extensions import TypedDict
 
 from pydantic import BaseModel, ConfigDict, Field, field_validator
 from pydantic.alias_generators import to_camel
 
+# Optional solana imports - only required for actual blockchain operations
+try:
+    from solders.keypair import Keypair
+    from solders.pubkey import Pubkey
+    from solders.transaction import VersionedTransaction
+    from solders.message import MessageV0
+    from solders.signature import Signature
+    from solders.instruction import CompiledInstruction
+    from solana.rpc.async_api import AsyncClient
+    from solana.rpc.commitment import Commitment, Confirmed
+    SOLANA_AVAILABLE = True
+except ImportError:
+    SOLANA_AVAILABLE = False
+    Keypair = None
+    Pubkey = None
+    VersionedTransaction = None
+    MessageV0 = None
+    Signature = None
+    CompiledInstruction = None
+    AsyncClient = None
+    Commitment = None
+    Confirmed = None
+
 
 # Constants
 SCHEME_EXACT = "exact"
@@ -564,3 +594,969 @@ def get_known_tokens(network: str) -> List[TokenConfig]:
     if not config:
         return []
     return list(config["supported_assets"].values())
+
+
+# =============================================================================
+# Transaction Utilities
+# =============================================================================
+
+
+def decode_transaction(tx_base64: str) -> bytes:
+    """
+    Decode a base64 encoded transaction.
+
+    Args:
+        tx_base64: Base64 encoded transaction string
+
+    Returns:
+        Transaction bytes
+
+    Raises:
+        ValueError: If transaction cannot be decoded
+    """
+    try:
+        return base64.b64decode(tx_base64)
+    except Exception as e:
+        raise ValueError(f"Failed to decode transaction: {e}")
+
+
+def decode_versioned_transaction(tx_base64: str) -> "VersionedTransaction":
+    """
+    Decode a base64 encoded Solana versioned transaction.
+
+    Requires solana/solders packages to be installed.
+
+    Args:
+        tx_base64: Base64 encoded transaction string
+
+    Returns:
+        VersionedTransaction object
+
+    Raises:
+        ImportError: If solana packages not installed
+        ValueError: If transaction cannot be decoded
+    """
+    if not SOLANA_AVAILABLE:
+        raise ImportError(
+            "solana and solders packages required for transaction decoding. "
+            "Install with: pip install t402[svm]"
+        )
+
+    try:
+        tx_bytes = decode_transaction(tx_base64)
+        return VersionedTransaction.from_bytes(tx_bytes)
+    except Exception as e:
+        raise ValueError(f"Failed to decode versioned transaction: {e}")
+
+
+def encode_transaction(tx: "VersionedTransaction") -> str:
+    """
+    Encode a versioned transaction to base64.
+
+    Args:
+        tx: VersionedTransaction object
+
+    Returns:
+        Base64 encoded transaction string
+    """
+    return base64.b64encode(bytes(tx)).decode("utf-8")
+
+
+def get_transaction_fee_payer(tx_base64: str) -> Optional[str]:
+    """
+    Extract the fee payer address from a transaction.
+
+    Args:
+        tx_base64: Base64 encoded transaction string
+
+    Returns:
+        Fee payer address or None if cannot be extracted
+    """
+    if not SOLANA_AVAILABLE:
+        return None
+
+    try:
+        tx = decode_versioned_transaction(tx_base64)
+        message = tx.message
+        if hasattr(message, "account_keys") and len(message.account_keys) > 0:
+            return str(message.account_keys[0])
+        return None
+    except Exception:
+        return None
+
+
+def get_token_payer_from_transaction(tx_base64: str) -> Optional[str]:
+    """
+    Extract the token transfer authority (payer) from a transaction.
+
+    This looks for the authority account in TransferChecked instructions.
+
+    Args:
+        tx_base64: Base64 encoded transaction string
+
+    Returns:
+        Token payer address or None if cannot be extracted
+    """
+    if not SOLANA_AVAILABLE:
+        return None
+
+    try:
+        tx = decode_versioned_transaction(tx_base64)
+        message = tx.message
+        account_keys = list(message.account_keys) if hasattr(message, "account_keys") else []
+
+        # Look for token program instructions
+        for ix in message.instructions:
+            program_idx = ix.program_id_index
+            if program_idx >= len(account_keys):
+                continue
+
+            program_id = str(account_keys[program_idx])
+
+            # Check if it's a token program
+            if program_id in (TOKEN_PROGRAM_ADDRESS, TOKEN_2022_PROGRAM_ADDRESS):
+                # TransferChecked has authority at index 2
+                accounts = list(ix.accounts)
+                if len(accounts) >= 3:
+                    authority_idx = accounts[2]
+                    if authority_idx < len(account_keys):
+                        return str(account_keys[authority_idx])
+
+        return None
+    except Exception:
+        return None
+
+
+class TransferDetails(TypedDict):
+    """Details of a token transfer instruction."""
+    source: str
+    mint: str
+    destination: str
+    authority: str
+    amount: int
+    decimals: int
+
+
+def parse_transfer_checked_instruction(
+    tx_base64: str,
+) -> Optional[TransferDetails]:
+    """
+    Parse a TransferChecked instruction from a transaction.
+
+    Args:
+        tx_base64: Base64 encoded transaction string
+
+    Returns:
+        TransferDetails or None if no transfer found
+    """
+    if not SOLANA_AVAILABLE:
+        return None
+
+    try:
+        tx = decode_versioned_transaction(tx_base64)
+        message = tx.message
+        account_keys = list(message.account_keys) if hasattr(message, "account_keys") else []
+
+        for ix in message.instructions:
+            program_idx = ix.program_id_index
+            if program_idx >= len(account_keys):
+                continue
+
+            program_id = str(account_keys[program_idx])
+
+            # Check if it's a token program
+            if program_id not in (TOKEN_PROGRAM_ADDRESS, TOKEN_2022_PROGRAM_ADDRESS):
+                continue
+
+            # Check instruction discriminator for TransferChecked (12)
+            if not ix.data or ix.data[0] != 12:
+                continue
+
+            accounts = list(ix.accounts)
+            if len(accounts) < 4:
+                continue
+
+            # Parse TransferChecked data: [discriminator(1), amount(8), decimals(1)]
+            if len(ix.data) < 10:
+                continue
+
+            amount = int.from_bytes(ix.data[1:9], "little")
+            decimals = ix.data[9]
+
+            source_idx = accounts[0]
+            mint_idx = accounts[1]
+            dest_idx = accounts[2]
+            authority_idx = accounts[3]
+
+            return {
+                "source": str(account_keys[source_idx]) if source_idx < len(account_keys) else "",
+                "mint": str(account_keys[mint_idx]) if mint_idx < len(account_keys) else "",
+                "destination": str(account_keys[dest_idx]) if dest_idx < len(account_keys) else "",
+                "authority": str(account_keys[authority_idx]) if authority_idx < len(account_keys) else "",
+                "amount": amount,
+                "decimals": decimals,
+            }
+
+        return None
+    except Exception:
+        return None
+
+
+# =============================================================================
+# Signer Interfaces
+# =============================================================================
+
+
+@runtime_checkable
+class ClientSvmSigner(Protocol):
+    """
+    Interface for client-side SVM signing operations.
+
+    Implementations should provide methods to:
+    - Get the signer's public address
+    - Sign transactions
+    - Optionally get token balances
+    """
+
+    def get_address(self) -> str:
+        """Get the signer's Solana address."""
+        ...
+
+    async def sign_transaction(
+        self,
+        tx_base64: str,
+        network: str,
+    ) -> str:
+        """
+        Sign a transaction.
+
+        Args:
+            tx_base64: Base64 encoded unsigned transaction
+            network: Network identifier
+
+        Returns:
+            Base64 encoded signed transaction
+        """
+        ...
+
+
+@runtime_checkable
+class FacilitatorSvmSigner(Protocol):
+    """
+    Interface for facilitator-side SVM operations.
+
+    Extends client signer with RPC capabilities for:
+    - Signing transactions (as fee payer)
+    - Simulating transactions
+    - Sending and confirming transactions
+    """
+
+    def get_addresses(self) -> List[str]:
+        """Get all available fee payer addresses."""
+        ...
+
+    async def sign_transaction(
+        self,
+        tx_base64: str,
+        fee_payer: str,
+        network: str,
+    ) -> str:
+        """
+        Sign a transaction as fee payer.
+
+        Args:
+            tx_base64: Base64 encoded transaction
+            fee_payer: Fee payer address to use
+            network: Network identifier
+
+        Returns:
+            Base64 encoded fully signed transaction
+        """
+        ...
+
+    async def simulate_transaction(
+        self,
+        tx_base64: str,
+        network: str,
+    ) -> bool:
+        """
+        Simulate a transaction to verify it will succeed.
+
+        Args:
+            tx_base64: Base64 encoded signed transaction
+            network: Network identifier
+
+        Returns:
+            True if simulation succeeds
+
+        Raises:
+            Exception: If simulation fails
+        """
+        ...
+
+    async def send_transaction(
+        self,
+        tx_base64: str,
+        network: str,
+    ) -> str:
+        """
+        Send a signed transaction to the network.
+
+        Args:
+            tx_base64: Base64 encoded signed transaction
+            network: Network identifier
+
+        Returns:
+            Transaction signature
+        """
+        ...
+
+    async def confirm_transaction(
+        self,
+        signature: str,
+        network: str,
+    ) -> bool:
+        """
+        Wait for transaction confirmation.
+
+        Args:
+            signature: Transaction signature
+            network: Network identifier
+
+        Returns:
+            True if confirmed
+        """
+        ...
+
+
+class KeypairSvmSigner:
+    """
+    Simple SVM signer using a Keypair.
+
+    Suitable for client-side signing operations.
+    """
+
+    def __init__(self, keypair: "Keypair"):
+        """
+        Initialize with a Keypair.
+
+        Args:
+            keypair: Solders Keypair object
+        """
+        if not SOLANA_AVAILABLE:
+            raise ImportError(
+                "solana and solders packages required. "
+                "Install with: pip install t402[svm]"
+            )
+        self._keypair = keypair
+
+    @classmethod
+    def from_secret_key(cls, secret_key: bytes) -> "KeypairSvmSigner":
+        """Create signer from a 64-byte secret key."""
+        if not SOLANA_AVAILABLE:
+            raise ImportError(
+                "solana and solders packages required. "
+                "Install with: pip install t402[svm]"
+            )
+        return cls(Keypair.from_bytes(secret_key))
+
+    @classmethod
+    def from_base58(cls, base58_key: str) -> "KeypairSvmSigner":
+        """Create signer from a base58 encoded secret key."""
+        if not SOLANA_AVAILABLE:
+            raise ImportError(
+                "solana and solders packages required. "
+                "Install with: pip install t402[svm]"
+            )
+        return cls(Keypair.from_base58_string(base58_key))
+
+    def get_address(self) -> str:
+        """Get the signer's public address."""
+        return str(self._keypair.pubkey())
+
+    async def sign_transaction(
+        self,
+        tx_base64: str,
+        network: str,
+    ) -> str:
+        """Sign a transaction."""
+        tx = decode_versioned_transaction(tx_base64)
+
+        # Sign the transaction
+        tx.sign([self._keypair])
+
+        return encode_transaction(tx)
+
+
+class RpcSvmSigner:
+    """
+    Facilitator SVM signer with RPC capabilities.
+
+    Manages multiple keypairs and provides RPC operations
+    for transaction simulation, sending, and confirmation.
+    """
+
+    def __init__(
+        self,
+        keypairs: List["Keypair"],
+        rpc_urls: Optional[Dict[str, str]] = None,
+    ):
+        """
+        Initialize with keypairs and optional custom RPC URLs.
+
+        Args:
+            keypairs: List of Keypair objects for signing
+            rpc_urls: Optional map of network -> RPC URL overrides
+        """
+        if not SOLANA_AVAILABLE:
+            raise ImportError(
+                "solana and solders packages required. "
+                "Install with: pip install t402[svm]"
+            )
+
+        self._keypairs = {str(kp.pubkey()): kp for kp in keypairs}
+        self._rpc_urls = rpc_urls or {}
+
+    def get_addresses(self) -> List[str]:
+        """Get all available fee payer addresses."""
+        return list(self._keypairs.keys())
+
+    def _get_rpc_url(self, network: str) -> str:
+        """Get RPC URL for a network."""
+        if network in self._rpc_urls:
+            return self._rpc_urls[network]
+        return get_rpc_url(network)
+
+    async def sign_transaction(
+        self,
+        tx_base64: str,
+        fee_payer: str,
+        network: str,
+    ) -> str:
+        """Sign a transaction as fee payer."""
+        if fee_payer not in self._keypairs:
+            raise ValueError(f"Fee payer {fee_payer} not found in managed keypairs")
+
+        tx = decode_versioned_transaction(tx_base64)
+        keypair = self._keypairs[fee_payer]
+
+        # Sign the transaction
+        tx.sign([keypair])
+
+        return encode_transaction(tx)
+
+    async def simulate_transaction(
+        self,
+        tx_base64: str,
+        network: str,
+    ) -> bool:
+        """Simulate a transaction."""
+        rpc_url = self._get_rpc_url(network)
+
+        async with AsyncClient(rpc_url) as client:
+            tx = decode_versioned_transaction(tx_base64)
+            result = await client.simulate_transaction(tx)
+
+            if result.value.err:
+                raise Exception(f"Simulation failed: {result.value.err}")
+
+            return True
+
+    async def send_transaction(
+        self,
+        tx_base64: str,
+        network: str,
+    ) -> str:
+        """Send a signed transaction."""
+        rpc_url = self._get_rpc_url(network)
+
+        async with AsyncClient(rpc_url) as client:
+            tx = decode_versioned_transaction(tx_base64)
+            result = await client.send_transaction(tx)
+            return str(result.value)
+
+    async def confirm_transaction(
+        self,
+        signature: str,
+        network: str,
+        timeout_seconds: int = 30,
+    ) -> bool:
+        """Wait for transaction confirmation."""
+        rpc_url = self._get_rpc_url(network)
+
+        async with AsyncClient(rpc_url) as client:
+            sig = Signature.from_string(signature)
+            # Wait for confirmation with timeout
+            result = await client.confirm_transaction(
+                sig,
+                commitment=Confirmed,
+            )
+            return result.value[0].confirmation_status is not None
+
+
+# =============================================================================
+# Scheme Implementations
+# =============================================================================
+
+
+class ExactSvmPayloadV2(TypedDict):
+    """Exact SVM payment payload (V2 format)."""
+    transaction: str
+    authorization: Optional[Dict[str, Any]]
+
+
+class SvmPaymentRequirementsExtra(TypedDict, total=False):
+    """Extra fields for SVM payment requirements."""
+    feePayer: str
+
+
+class ExactSvmClientScheme:
+    """
+    Client scheme for creating SVM payment payloads.
+
+    Handles creation of SPL token transfer transactions
+    for the exact payment scheme.
+    """
+
+    scheme = SCHEME_EXACT
+    caip_family = "solana:*"
+
+    def __init__(self, signer: ClientSvmSigner):
+        """
+        Initialize with a client signer.
+
+        Args:
+            signer: ClientSvmSigner implementation
+        """
+        self._signer = signer
+
+    async def create_payment_payload(
+        self,
+        requirements: Dict[str, Any],
+        build_transaction: Callable[[], Awaitable[str]],
+    ) -> Dict[str, Any]:
+        """
+        Create a payment payload for the given requirements.
+
+        Args:
+            requirements: Payment requirements dict
+            build_transaction: Async function that builds and returns
+                a base64 encoded unsigned transaction
+
+        Returns:
+            Payment payload dict ready for header encoding
+        """
+        # Build the transaction
+        unsigned_tx = await build_transaction()
+
+        # Sign the transaction
+        signed_tx = await self._signer.sign_transaction(
+            unsigned_tx,
+            requirements.get("network", SOLANA_MAINNET),
+        )
+
+        # Extract transfer details for authorization
+        transfer = parse_transfer_checked_instruction(signed_tx)
+
+        now = int(time.time())
+        valid_until = now + requirements.get("maxTimeoutSeconds", DEFAULT_VALIDITY_DURATION)
+
+        authorization = None
+        if transfer:
+            authorization = {
+                "from": self._signer.get_address(),
+                "to": requirements.get("payTo", ""),
+                "mint": transfer["mint"],
+                "amount": str(transfer["amount"]),
+                "validUntil": valid_until,
+                "feePayer": requirements.get("extra", {}).get("feePayer"),
+            }
+
+        return {
+            "t402Version": requirements.get("t402Version", 1),
+            "scheme": SCHEME_EXACT,
+            "network": requirements.get("network", SOLANA_MAINNET),
+            "payload": {
+                "transaction": signed_tx,
+                "authorization": authorization,
+            },
+        }
+
+
+class ExactSvmServerScheme:
+    """
+    Server scheme for SVM payment processing.
+
+    Handles parsing prices and enhancing payment requirements
+    with SVM-specific details.
+    """
+
+    scheme = SCHEME_EXACT
+    caip_family = "solana:*"
+
+    def parse_price(
+        self,
+        price: str,
+        network: str,
+    ) -> Dict[str, Any]:
+        """
+        Parse a price string into amount and asset info.
+
+        Args:
+            price: Price string (e.g., "1.50" or "1500000")
+            network: Network identifier
+
+        Returns:
+            Dict with amount (in atomic units) and asset info
+        """
+        default_asset = get_default_asset(network)
+        if not default_asset:
+            raise ValueError(f"Unsupported network: {network}")
+
+        decimals = default_asset["decimals"]
+
+        # Check if price is already in atomic units (no decimal)
+        if "." in price:
+            amount = parse_amount(price, decimals)
+        else:
+            amount = int(price)
+
+        return {
+            "amount": str(amount),
+            "asset": default_asset["mint_address"],
+            "decimals": decimals,
+            "symbol": default_asset["symbol"],
+        }
+
+    def enhance_payment_requirements(
+        self,
+        requirements: Dict[str, Any],
+        fee_payer: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        Enhance payment requirements with SVM-specific details.
+
+        Args:
+            requirements: Base payment requirements
+            fee_payer: Optional fee payer address from facilitator
+
+        Returns:
+            Enhanced requirements dict
+        """
+        enhanced = dict(requirements)
+
+        # Normalize network to CAIP-2 format
+        network = enhanced.get("network", SOLANA_MAINNET)
+        enhanced["network"] = normalize_network(network)
+
+        # Add fee payer if provided
+        if fee_payer:
+            extra = enhanced.get("extra", {})
+            extra["feePayer"] = fee_payer
+            enhanced["extra"] = extra
+
+        return enhanced
+
+
+class ExactSvmFacilitatorScheme:
+    """
+    Facilitator scheme for SVM payment verification and settlement.
+
+    Handles transaction validation, simulation, and settlement
+    for the exact payment scheme.
+    """
+
+    scheme = SCHEME_EXACT
+    caip_family = "solana:*"
+
+    def __init__(self, signer: FacilitatorSvmSigner):
+        """
+        Initialize with a facilitator signer.
+
+        Args:
+            signer: FacilitatorSvmSigner implementation
+        """
+        self._signer = signer
+
+    def get_extra(self, network: str) -> Optional[Dict[str, Any]]:
+        """
+        Get mechanism-specific extra data for supported kinds.
+
+        Returns a randomly selected fee payer address to distribute load.
+
+        Args:
+            network: Network identifier (unused for SVM)
+
+        Returns:
+            Dict with feePayer address
+        """
+        import random
+
+        addresses = self._signer.get_addresses()
+        if not addresses:
+            return None
+
+        return {
+            "feePayer": random.choice(addresses),
+        }
+
+    def get_signers(self, network: str) -> List[str]:
+        """
+        Get all signer addresses for this facilitator.
+
+        Args:
+            network: Network identifier (unused for SVM)
+
+        Returns:
+            List of fee payer addresses
+        """
+        return self._signer.get_addresses()
+
+    async def verify(
+        self,
+        payload: Dict[str, Any],
+        requirements: Dict[str, Any],
+    ) -> Dict[str, Any]:
+        """
+        Verify a payment payload.
+
+        Args:
+            payload: Payment payload dict
+            requirements: Payment requirements dict
+
+        Returns:
+            Verification result dict with isValid, invalidReason, payer
+        """
+        svm_payload = payload.get("payload", {})
+        tx_base64 = svm_payload.get("transaction")
+
+        # Validate payload structure
+        if not tx_base64:
+            return {
+                "isValid": False,
+                "invalidReason": "invalid_payload_structure",
+                "payer": "",
+            }
+
+        # Validate scheme
+        if payload.get("scheme") != SCHEME_EXACT or requirements.get("scheme") != SCHEME_EXACT:
+            return {
+                "isValid": False,
+                "invalidReason": "unsupported_scheme",
+                "payer": "",
+            }
+
+        # Validate network
+        accepted_network = payload.get("network", "")
+        required_network = requirements.get("network", "")
+        if normalize_network(accepted_network) != normalize_network(required_network):
+            return {
+                "isValid": False,
+                "invalidReason": "network_mismatch",
+                "payer": "",
+            }
+
+        # Validate fee payer
+        extra = requirements.get("extra", {})
+        fee_payer = extra.get("feePayer")
+        if not fee_payer:
+            return {
+                "isValid": False,
+                "invalidReason": "invalid_exact_svm_payload_missing_fee_payer",
+                "payer": "",
+            }
+
+        # Verify fee payer is managed by this facilitator
+        signer_addresses = self._signer.get_addresses()
+        if fee_payer not in signer_addresses:
+            return {
+                "isValid": False,
+                "invalidReason": "fee_payer_not_managed_by_facilitator",
+                "payer": "",
+            }
+
+        # Get token payer from transaction
+        payer = get_token_payer_from_transaction(tx_base64)
+        if not payer:
+            return {
+                "isValid": False,
+                "invalidReason": "invalid_exact_svm_payload_no_transfer_instruction",
+                "payer": "",
+            }
+
+        # Parse and validate transfer instruction
+        transfer = parse_transfer_checked_instruction(tx_base64)
+        if not transfer:
+            return {
+                "isValid": False,
+                "invalidReason": "invalid_exact_svm_payload_no_transfer_instruction",
+                "payer": payer,
+            }
+
+        # Security: Verify facilitator's signers are not transferring their own funds
+        if transfer["authority"] in signer_addresses:
+            return {
+                "isValid": False,
+                "invalidReason": "invalid_exact_svm_payload_transaction_fee_payer_transferring_funds",
+                "payer": payer,
+            }
+
+        # Verify mint matches requirements
+        if transfer["mint"] != requirements.get("asset"):
+            return {
+                "isValid": False,
+                "invalidReason": "invalid_exact_svm_payload_mint_mismatch",
+                "payer": payer,
+            }
+
+        # Verify amount meets requirements
+        required_amount = int(requirements.get("maxAmountRequired", "0"))
+        if transfer["amount"] < required_amount:
+            return {
+                "isValid": False,
+                "invalidReason": "invalid_exact_svm_payload_amount_insufficient",
+                "payer": payer,
+            }
+
+        # Sign and simulate transaction
+        try:
+            signed_tx = await self._signer.sign_transaction(
+                tx_base64,
+                fee_payer,
+                required_network,
+            )
+            await self._signer.simulate_transaction(signed_tx, required_network)
+        except Exception as e:
+            return {
+                "isValid": False,
+                "invalidReason": f"transaction_simulation_failed: {str(e)}",
+                "payer": payer,
+            }
+
+        return {
+            "isValid": True,
+            "invalidReason": None,
+            "payer": payer,
+        }
+
+    async def settle(
+        self,
+        payload: Dict[str, Any],
+        requirements: Dict[str, Any],
+    ) -> Dict[str, Any]:
+        """
+        Settle a payment by submitting the transaction.
+
+        Args:
+            payload: Payment payload dict
+            requirements: Payment requirements dict
+
+        Returns:
+            Settlement result dict
+        """
+        network = payload.get("network", "")
+        svm_payload = payload.get("payload", {})
+        tx_base64 = svm_payload.get("transaction")
+
+        if not tx_base64:
+            return {
+                "success": False,
+                "network": network,
+                "transaction": "",
+                "errorReason": "invalid_payload_structure",
+                "payer": "",
+            }
+
+        # Verify first
+        verify_result = await self.verify(payload, requirements)
+        if not verify_result.get("isValid"):
+            return {
+                "success": False,
+                "network": network,
+                "transaction": "",
+                "errorReason": verify_result.get("invalidReason", "verification_failed"),
+                "payer": verify_result.get("payer", ""),
+            }
+
+        try:
+            fee_payer = requirements.get("extra", {}).get("feePayer")
+            required_network = requirements.get("network", network)
+
+            # Sign transaction
+            signed_tx = await self._signer.sign_transaction(
+                tx_base64,
+                fee_payer,
+                required_network,
+            )
+
+            # Send transaction
+            signature = await self._signer.send_transaction(signed_tx, required_network)
+
+            # Wait for confirmation
+            await self._signer.confirm_transaction(signature, required_network)
+
+            return {
+                "success": True,
+                "transaction": signature,
+                "network": network,
+                "payer": verify_result.get("payer", ""),
+            }
+        except Exception as e:
+            return {
+                "success": False,
+                "errorReason": f"transaction_failed: {str(e)}",
+                "transaction": "",
+                "network": network,
+                "payer": verify_result.get("payer", ""),
+            }
+
+
+# =============================================================================
+# Helper Functions
+# =============================================================================
+
+
+def create_client_scheme(signer: ClientSvmSigner) -> ExactSvmClientScheme:
+    """
+    Create a client scheme for SVM payments.
+
+    Args:
+        signer: ClientSvmSigner implementation
+
+    Returns:
+        ExactSvmClientScheme instance
+    """
+    return ExactSvmClientScheme(signer)
+
+
+def create_server_scheme() -> ExactSvmServerScheme:
+    """
+    Create a server scheme for SVM payments.
+
+    Returns:
+        ExactSvmServerScheme instance
+    """
+    return ExactSvmServerScheme()
+
+
+def create_facilitator_scheme(signer: FacilitatorSvmSigner) -> ExactSvmFacilitatorScheme:
+    """
+    Create a facilitator scheme for SVM payments.
+
+    Args:
+        signer: FacilitatorSvmSigner implementation
+
+    Returns:
+        ExactSvmFacilitatorScheme instance
+    """
+    return ExactSvmFacilitatorScheme(signer)
+
+
+def check_solana_available() -> bool:
+    """
+    Check if Solana packages are available.
+
+    Returns:
+        True if solana/solders packages are installed
+    """
+    return SOLANA_AVAILABLE

{t402-1.6.0.dist-info → t402-1.6.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: t402
-Version: 1.6.0
+Version: 1.6.1
 Summary: t402: An internet native payments protocol
 Author-email: T402 Team <dev@t402.io>
 License: Apache-2.0

{t402-1.6.0.dist-info → t402-1.6.1.dist-info}/RECORD

@@ -1,4 +1,4 @@
-t402/__init__.py,sha256=yara_fUhws5F34SNkO8QCDr4yWH6xq01dDdcwDGeYPw,8153
+t402/__init__.py,sha256=ijh3QHwocnPewrlYYAmeW04XaJO4DuFfNYEEKJoJVSw,10225
 t402/chains.py,sha256=Hyn3bfubNpiWE1fqkyJulkonzMu3lncSt-_RCgagdro,2832
 t402/cli.py,sha256=UiGuXNHUp67P7S2nD2j67JJ1M2KWalXk5qjE3LfXK_4,9732
 t402/common.py,sha256=cRiu_MsMVldCOZH9XCzynSAtF4Xkcvhc63jbIlKhe3c,5851
@@ -10,7 +10,7 @@ t402/networks.py,sha256=WZzQ_azmlLwD4sp3RCcU0BMMZ26FGyQSiGeNjaxX340,3766
 t402/path.py,sha256=G3oxm12FS1OsxXK_BPopS4bVCFrei5MOMnQAvDbgZsY,1311
 t402/paywall.py,sha256=lSpGlDBC4slPU5rw7aDq5iBrBJXxLHRe3lgddFMKZ-Q,4119
 t402/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-t402/svm.py,sha256=IaiFy-xRpVrVe8AC2r2_Ht1R45A_6B9JrrkZhQLApiA,14672
+t402/svm.py,sha256=cN_AtbYF29yVbZFGb9Hb4N3luakFkmHNTJf2GsdBF3Q,43339
 t402/svm_paywall_template.py,sha256=pmueO0Qgcwl-uyci8lVI1eiery2vggHGl_b1tnxcB_E,827953
 t402/ton.py,sha256=ggh_6nvZ55c-iYe6bNVejPJIWoFRSf85-DQmsvu-auI,11919
 t402/ton_paywall_template.py,sha256=kRddMyZk51dDd1b4-r_MlSGCc-DLRHskIxA-LN9l9vw,7343
@@ -45,7 +45,7 @@ t402/wdk/chains.py,sha256=UlkOjBeV8HhUis61YceMevHgGoPLvDJ9VzL8IskO2V8,6885
 t402/wdk/errors.py,sha256=Sz_qNoO1K8Tx1sGs3KcG9rMoKJXkIvhSkoEZyPaAyd0,6066
 t402/wdk/signer.py,sha256=cEjBTdWNVqrDZCHsuy6IC7fV81o_dX2mpKqLEhxtLGI,20234
 t402/wdk/types.py,sha256=dkuLK7hNNUTrIs15obZTYiniwT0vF87qoEMyOJkOmms,2542
-t402-1.6.0.dist-info/METADATA,sha256=NbhisTU-SnGKoBgFAF2fDcpHP7PysM8IOEu4_-VVsuA,11317
-t402-1.6.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-t402-1.6.0.dist-info/entry_points.txt,sha256=Lx-ftLGax72kwtKHBUcyIbwOPT9tjMLc5_bxbRts-G4,39
-t402-1.6.0.dist-info/RECORD,,
+t402-1.6.1.dist-info/METADATA,sha256=X_OS1aDoRyl9WNrPqNv9rZbVdy_swHqUGgJnasJWOHU,11317
+t402-1.6.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+t402-1.6.1.dist-info/entry_points.txt,sha256=Lx-ftLGax72kwtKHBUcyIbwOPT9tjMLc5_bxbRts-G4,39
+t402-1.6.1.dist-info/RECORD,,