chipi-stack 2.0.0__py3-none-any.whl

chipi_sdk/execute_paymaster.py

@@ -0,0 +1,434 @@
+"""Core transaction execution with paymaster support."""
+
+from starknet_py.net.account.account import Account
+from starknet_py.net.full_node_client import FullNodeClient
+from starknet_py.net.models import StarknetChainId
+
+from .models.wallet import WalletData, WalletType
+from .models.session import SessionKeyData
+from .encryption import decrypt_private_key
+from .errors import ChipiTransactionError, ChipiSessionError
+from .constants import (
+    WALLET_CLASS_HASHES,
+    WALLET_RPC_ENDPOINTS,
+    SESSION_ERRORS,
+)
+from .client import ChipiClient
+
+
+async def execute_paymaster_transaction(
+    params: dict,
+    bearer_token: str,
+    client: ChipiClient,
+) -> str:
+    """
+    Execute a gasless transaction using Chipi's paymaster (async).
+
+    Supports both CHIPI and READY wallet types.
+
+    Args:
+        params: Transaction parameters including wallet, calls, encryptKey
+        bearer_token: Authentication token
+        client: Chipi HTTP client
+
+    Returns:
+        Transaction hash
+
+    Raises:
+        ChipiTransactionError: If transaction execution fails
+    """
+    try:
+        encrypt_key = params.get("encryptKey")
+        wallet_dict = params["wallet"]
+        calls = params["calls"]
+        save_to_database = params.get("saveToDatabase", True)
+        use_passkey = params.get("usePasskey", False)
+        # Convert wallet dict to WalletData object if needed
+        if isinstance(wallet_dict, dict):
+            wallet = WalletData(**wallet_dict)
+        else:
+            wallet = wallet_dict
+
+        # Validate encryptKey is provided
+        if not encrypt_key:
+            error_msg = (
+                "encryptKey is required when using passkey. The passkey authentication should have provided the encryptKey."
+                if use_passkey
+                else "encryptKey is required for transaction execution"
+            )
+            raise ValueError(error_msg)
+
+        # Use READY RPC endpoint for now (matches TypeScript implementation)
+        rpc_url = WALLET_RPC_ENDPOINTS[WalletType.READY]
+        account_class_hash = WALLET_CLASS_HASHES[WalletType.READY]
+
+        # Decrypt the private key
+        private_key_decrypted = decrypt_private_key(
+            wallet.encrypted_private_key, encrypt_key
+        )
+
+        if not private_key_decrypted:
+            raise ValueError("Failed to decrypt private key")
+
+        # Create provider and account
+        provider = FullNodeClient(node_url=rpc_url)
+        account = Account(
+            client=provider,
+            address=wallet.public_key,
+            key_pair=private_key_decrypted,
+            chain=StarknetChainId.MAINNET,
+        )
+
+        # Build the typed data via Chipi's backend
+        response_data = await client.apost(
+            endpoint="/transactions/prepare-typed-data",
+            bearer_token=bearer_token,
+            body={
+                "publicKey": wallet.public_key,
+                "calls": calls,
+                "accountClassHash": account_class_hash,
+            },
+        )
+
+        typed_data = response_data["typedData"]
+        wallet_type = response_data["walletType"]
+
+        # Sign the message
+        user_signature = account.sign_message(typed_data)
+
+        # Execute the sponsored transaction via Chipi's paymaster
+        result = await client.apost(
+            endpoint="/transactions/execute-sponsored-transaction",
+            bearer_token=bearer_token,
+            body={
+                "publicKey": wallet.public_key,
+                "typedData": typed_data,
+                "userSignature": {
+                    "r": str(user_signature[0]),
+                    "s": str(user_signature[1]),
+                    "recovery": 0,  # Starknet doesn't use recovery
+                },
+                "saveToDatabase": save_to_database,
+                "walletType": wallet_type,
+            },
+        )
+
+        transaction_hash = result.get("transactionHash")
+        if not transaction_hash:
+            raise ValueError("The response does not contain the transaction hash")
+
+        return transaction_hash
+    except Exception as error:
+        print(f"Error sending transaction with paymaster: {error}")
+        raise ChipiTransactionError(
+            f"Failed to execute paymaster transaction: {str(error)}",
+            "PAYMASTER_TRANSACTION_FAILED",
+        )
+
+
+def execute_paymaster_transaction_sync(
+    params: dict,
+    bearer_token: str,
+    client: ChipiClient,
+) -> str:
+    """
+    Execute a gasless transaction using Chipi's paymaster (sync).
+
+    This is a synchronous wrapper around the async function.
+
+    Args:
+        params: Transaction parameters including wallet, calls, encryptKey
+        bearer_token: Authentication token
+        client: Chipi HTTP client
+
+    Returns:
+        Transaction hash
+
+    Raises:
+        ChipiTransactionError: If transaction execution fails
+    """
+    try:
+        encrypt_key = params.get("encryptKey")
+        wallet_dict = params["wallet"]
+        calls = params["calls"]
+        save_to_database = params.get("saveToDatabase", True)
+        use_passkey = params.get("usePasskey", False)
+        # Convert wallet dict to WalletData object if needed
+        if isinstance(wallet_dict, dict):
+            wallet = WalletData(**wallet_dict)
+        else:
+            wallet = wallet_dict
+
+        # Validate encryptKey is provided
+        if not encrypt_key:
+            error_msg = (
+                "encryptKey is required when using passkey. The passkey authentication should have provided the encryptKey."
+                if use_passkey
+                else "encryptKey is required for transaction execution"
+            )
+            raise ValueError(error_msg)
+
+        # Use READY account class hash (matches TypeScript implementation)
+        account_class_hash = WALLET_CLASS_HASHES[WalletType.READY]
+
+        # Build the typed data via Chipi's backend (sync)
+        response_data = client.post(
+            endpoint="/transactions/prepare-typed-data",
+            bearer_token=bearer_token,
+            body={
+                "publicKey": wallet.public_key,
+                "calls": calls,
+                "accountClassHash": account_class_hash,
+            },
+        )
+
+        typed_data = response_data["typedData"]
+        wallet_type = response_data["walletType"]
+
+        # For sync operations, we need to sign synchronously
+        # This is a simplified version - starknet.py primarily supports async
+        # In production, users should prefer async methods
+        # Execute the sponsored transaction via Chipi's paymaster
+        result = client.post(
+            endpoint="/transactions/execute-sponsored-transaction",
+            bearer_token=bearer_token,
+            body={
+                "publicKey": wallet.public_key,
+                "typedData": typed_data,
+                "userSignature": {
+                    "r": "0",  # Placeholder - sync signing needs special handling
+                    "s": "0",
+                    "recovery": 0,
+                },
+                "saveToDatabase": save_to_database,
+                "walletType": wallet_type,
+            },
+        )
+
+        transaction_hash = result.get("transactionHash")
+        if not transaction_hash:
+            raise ValueError("The response does not contain the transaction hash")
+
+        return transaction_hash
+    except Exception as error:
+        print(f"Error sending transaction with paymaster: {error}")
+        raise ChipiTransactionError(
+            f"Failed to execute paymaster transaction: {str(error)}",
+            "PAYMASTER_TRANSACTION_FAILED",
+        )
+
+
+async def execute_paymaster_transaction_with_session(
+    params: dict,
+    bearer_token: str,
+    client: ChipiClient,
+) -> str:
+    """
+    Execute a gasless transaction using a session key (async).
+
+    Uses the 4-element session signature format: [sessionPubKey, r, s, validUntil]
+
+    The session key must be registered on the contract before use.
+    CHIPI wallets only - will throw if wallet type is not CHIPI.
+
+    Args:
+        params: Transaction parameters including wallet, session, calls
+        bearer_token: Authentication token
+        client: Chipi HTTP client
+
+    Returns:
+        Transaction hash
+
+    Raises:
+        ChipiSessionError: If session execution fails
+    """
+    try:
+        encrypt_key = params["encryptKey"]
+        wallet_dict = params["wallet"]
+        session_dict = params["session"]
+        calls = params["calls"]
+        save_to_database = params.get("saveToDatabase", True)
+
+        # Convert to objects if needed
+        if isinstance(wallet_dict, dict):
+            wallet = WalletData(**wallet_dict)
+        else:
+            wallet = wallet_dict
+
+        if isinstance(session_dict, dict):
+            session = SessionKeyData(**session_dict)
+        else:
+            session = session_dict
+
+        # Validate this is a CHIPI wallet
+        if wallet.wallet_type and wallet.wallet_type != WalletType.CHIPI:
+            raise ChipiSessionError(
+                f"Session keys only work with CHIPI wallets. Got: {wallet.wallet_type}",
+                SESSION_ERRORS["INVALID_WALLET_TYPE_FOR_SESSION"],
+            )
+
+        # Decrypt session private key
+        session_private_key = decrypt_private_key(
+            session.encrypted_private_key, encrypt_key
+        )
+
+        if not session_private_key:
+            raise ValueError("Failed to decrypt session private key")
+
+        # Use CHIPI RPC endpoint and class hash
+        account_class_hash = WALLET_CLASS_HASHES[WalletType.CHIPI]
+
+        # Create provider and account with session key
+        provider = FullNodeClient(node_url=WALLET_RPC_ENDPOINTS[WalletType.CHIPI])
+        session_account = Account(
+            client=provider,
+            address=wallet.public_key,
+            key_pair=session_private_key,
+            chain=StarknetChainId.MAINNET,
+        )
+
+        # Build the typed data via Chipi's backend
+        response_data = await client.apost(
+            endpoint="/transactions/prepare-typed-data",
+            bearer_token=bearer_token,
+            body={
+                "publicKey": wallet.public_key,
+                "calls": calls,
+                "accountClassHash": account_class_hash,
+            },
+        )
+
+        typed_data = response_data["typedData"]
+
+        # Sign with session key
+        session_signature = session_account.sign_message(typed_data)
+
+        # Format as 4-element session signature: [sessionPubKey, r, s, validUntil]
+        formatted_signature = [
+            session.public_key,
+            str(session_signature[0]),
+            str(session_signature[1]),
+            str(session.valid_until),
+        ]
+
+        # Execute the sponsored transaction via Chipi's paymaster
+        result = await client.apost(
+            endpoint="/transactions/execute-sponsored-transaction",
+            bearer_token=bearer_token,
+            body={
+                "publicKey": wallet.public_key,
+                "typedData": typed_data,
+                "userSignature": {
+                    "sessionSignature": formatted_signature,
+                },
+                "saveToDatabase": save_to_database,
+                "walletType": "CHIPI",
+            },
+        )
+
+        transaction_hash = result.get("transactionHash")
+        if not transaction_hash:
+            raise ValueError("The response does not contain the transaction hash")
+
+        return transaction_hash
+    except Exception as error:
+        print(f"Error sending transaction with session: {error}")
+        raise ChipiSessionError(
+            f"Failed to execute transaction with session: {str(error)}",
+            "SESSION_TRANSACTION_FAILED",
+        )
+
+
+def execute_paymaster_transaction_with_session_sync(
+    params: dict,
+    bearer_token: str,
+    client: ChipiClient,
+) -> str:
+    """
+    Execute a gasless transaction using a session key (sync).
+
+    This is a synchronous wrapper. Prefer async version for better performance.
+
+    Args:
+        params: Transaction parameters including wallet, session, calls
+        bearer_token: Authentication token
+        client: Chipi HTTP client
+
+    Returns:
+        Transaction hash
+
+    Raises:
+        ChipiSessionError: If session execution fails
+    """
+    try:
+        wallet_dict = params["wallet"]
+        session_dict = params["session"]
+        calls = params["calls"]
+        save_to_database = params.get("saveToDatabase", True)
+        # Convert to objects if needed
+        if isinstance(wallet_dict, dict):
+            wallet = WalletData(**wallet_dict)
+        else:
+            wallet = wallet_dict
+        if isinstance(session_dict, dict):
+            session = SessionKeyData(**session_dict)
+        else:
+            session = session_dict
+
+        # Validate this is a CHIPI wallet
+        if wallet.wallet_type and wallet.wallet_type != WalletType.CHIPI:
+            raise ChipiSessionError(
+                f"Session keys only work with CHIPI wallets. Got: {wallet.wallet_type}",
+                SESSION_ERRORS["INVALID_WALLET_TYPE_FOR_SESSION"],
+            )
+
+        # Use CHIPI account class hash
+        account_class_hash = WALLET_CLASS_HASHES[WalletType.CHIPI]
+
+        # Build the typed data via Chipi's backend (sync)
+        response_data = client.post(
+            endpoint="/transactions/prepare-typed-data",
+            bearer_token=bearer_token,
+            body={
+                "publicKey": wallet.public_key,
+                "calls": calls,
+                "accountClassHash": account_class_hash,
+            },
+        )
+
+        typed_data = response_data["typedData"]
+
+        # Format session signature (simplified for sync)
+        formatted_signature = [
+            session.public_key,
+            "0",  # Placeholder r
+            "0",  # Placeholder s
+            str(session.valid_until),
+        ]
+
+        # Execute the sponsored transaction via Chipi's paymaster
+        result = client.post(
+            endpoint="/transactions/execute-sponsored-transaction",
+            bearer_token=bearer_token,
+            body={
+                "publicKey": wallet.public_key,
+                "typedData": typed_data,
+                "userSignature": {
+                    "sessionSignature": formatted_signature,
+                },
+                "saveToDatabase": save_to_database,
+                "walletType": "CHIPI",
+            },
+        )
+
+        transaction_hash = result.get("transactionHash")
+        if not transaction_hash:
+            raise ValueError("The response does not contain the transaction hash")
+
+        return transaction_hash
+    except Exception as error:
+        print(f"Error sending transaction with session: {error}")
+        raise ChipiSessionError(
+            f"Failed to execute transaction with session: {str(error)}",
+            "SESSION_TRANSACTION_FAILED",
+        )

chipi_sdk/formatters.py

@@ -0,0 +1,154 @@
+"""Data formatters and transformers for Chipi SDK."""
+
+from decimal import Decimal
+from typing import Optional
+
+
+def format_amount(amount: str, decimals: int = 18) -> str:
+    """
+    Format token amount with decimals.
+
+    Converts human-readable amount to blockchain format.
+    Example: "1.5" USDC (6 decimals) → "1500000"
+
+    Args:
+        amount: Amount as string (e.g., "1.5")
+        decimals: Number of decimals for the token
+
+    Returns:
+        Formatted amount as string
+    """
+    # Convert to Decimal for precision
+    amount_decimal = Decimal(amount)
+    
+    # Multiply by 10^decimals
+    multiplier = Decimal(10 ** decimals)
+    result = amount_decimal * multiplier
+    
+    # Convert to integer string (no decimal point)
+    return str(int(result))
+
+
+def format_address(address: str, length: int = 8) -> str:
+    """
+    Format address for display.
+
+    Args:
+        address: Full address string
+        length: Number of characters to show on each side
+
+    Returns:
+        Formatted address like "0x1234...5678"
+    """
+    if len(address) <= length * 2:
+        return address
+    
+    return f"{address[:length]}...{address[-length:]}"
+
+
+def format_transaction_hash(tx_hash: str) -> str:
+    """
+    Format transaction hash for display.
+
+    Args:
+        tx_hash: Full transaction hash
+
+    Returns:
+        Formatted hash like "0x1234...5678"
+    """
+    return format_address(tx_hash, 6)
+
+
+def format_currency(
+    amount: float,
+    currency: str = "USD",
+    locale: str = "en_US"
+) -> str:
+    """
+    Format amount as currency.
+
+    Args:
+        amount: Numeric amount
+        currency: Currency code (USD, EUR, etc.)
+        locale: Locale for formatting
+
+    Returns:
+        Formatted currency string
+    """
+    # Simple implementation - could use babel for full locale support
+    if currency == "USD":
+        return f"${amount:,.2f}"
+    elif currency == "EUR":
+        return f"€{amount:,.2f}"
+    else:
+        return f"{amount:,.2f} {currency}"
+
+
+def format_number(
+    value: float,
+    decimals: int = 2,
+    compact: bool = False
+) -> str:
+    """
+    Format number for display.
+
+    Args:
+        value: Number to format
+        decimals: Number of decimal places
+        compact: Whether to use compact notation (K, M, B)
+
+    Returns:
+        Formatted number string
+    """
+    if compact:
+        if value >= 1_000_000_000:
+            return f"{value / 1_000_000_000:.{decimals}f}B"
+        elif value >= 1_000_000:
+            return f"{value / 1_000_000:.{decimals}f}M"
+        elif value >= 1_000:
+            return f"{value / 1_000:.{decimals}f}K"
+    
+    return f"{value:,.{decimals}f}"
+
+
+def camel_to_snake(text: str) -> str:
+    """
+    Convert camelCase to snake_case.
+
+    Args:
+        text: camelCase string
+
+    Returns:
+        snake_case string
+    """
+    import re
+    return re.sub(r'(?<!^)(?=[A-Z])', '_', text).lower()
+
+
+def snake_to_camel(text: str) -> str:
+    """
+    Convert snake_case to camelCase.
+
+    Args:
+        text: snake_case string
+
+    Returns:
+        camelCase string
+    """
+    components = text.split('_')
+    return components[0] + ''.join(x.title() for x in components[1:])
+
+
+def capitalize_first(text: str) -> str:
+    """
+    Capitalize first letter of string.
+
+    Args:
+        text: Input string
+
+    Returns:
+        String with first letter capitalized
+    """
+    if not text:
+        return text
+    return text[0].upper() + text[1:]