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

t402/multisig/transaction.py

@@ -0,0 +1,238 @@
+"""
+Transaction builder for T402 Multi-sig (Safe) support.
+"""
+
+from typing import List, Optional
+
+from web3 import Web3
+
+from .constants import SAFE_MULTISEND, ERC20_TRANSFER_SELECTOR, MULTISEND_SELECTOR
+from .types import SafeTransaction, OperationType
+
+
+class TransactionBuilder:
+    """Builder for Safe transactions."""
+
+    def __init__(self):
+        """Initialize TransactionBuilder."""
+        self._to: str = "0x0000000000000000000000000000000000000000"
+        self._value: int = 0
+        self._data: bytes = b""
+        self._operation: OperationType = OperationType.CALL
+        self._safe_tx_gas: int = 0
+        self._base_gas: int = 0
+        self._gas_price: int = 0
+        self._gas_token: str = "0x0000000000000000000000000000000000000000"
+        self._refund_receiver: str = "0x0000000000000000000000000000000000000000"
+        self._nonce: Optional[int] = None
+
+    def to(self, address: str) -> "TransactionBuilder":
+        """Set the target address."""
+        self._to = Web3.to_checksum_address(address)
+        return self
+
+    def value(self, amount: int) -> "TransactionBuilder":
+        """Set the ETH value to send."""
+        self._value = amount
+        return self
+
+    def data(self, data: bytes) -> "TransactionBuilder":
+        """Set the calldata."""
+        self._data = data
+        return self
+
+    def operation(self, op: OperationType) -> "TransactionBuilder":
+        """Set the operation type."""
+        self._operation = op
+        return self
+
+    def delegate_call(self) -> "TransactionBuilder":
+        """Set operation to delegate call."""
+        self._operation = OperationType.DELEGATE_CALL
+        return self
+
+    def safe_tx_gas(self, gas: int) -> "TransactionBuilder":
+        """Set the Safe transaction gas."""
+        self._safe_tx_gas = gas
+        return self
+
+    def base_gas(self, gas: int) -> "TransactionBuilder":
+        """Set the base gas."""
+        self._base_gas = gas
+        return self
+
+    def gas_price(self, price: int) -> "TransactionBuilder":
+        """Set the gas price for refund."""
+        self._gas_price = price
+        return self
+
+    def gas_token(self, token: str) -> "TransactionBuilder":
+        """Set the token for gas refund (zero address for ETH)."""
+        self._gas_token = Web3.to_checksum_address(token)
+        return self
+
+    def refund_receiver(self, receiver: str) -> "TransactionBuilder":
+        """Set the address to receive gas refund."""
+        self._refund_receiver = Web3.to_checksum_address(receiver)
+        return self
+
+    def nonce(self, nonce: int) -> "TransactionBuilder":
+        """Set the Safe nonce."""
+        self._nonce = nonce
+        return self
+
+    def build(self) -> SafeTransaction:
+        """Build the SafeTransaction."""
+        return SafeTransaction(
+            to=self._to,
+            value=self._value,
+            data=self._data,
+            operation=self._operation,
+            safe_tx_gas=self._safe_tx_gas,
+            base_gas=self._base_gas,
+            gas_price=self._gas_price,
+            gas_token=self._gas_token,
+            refund_receiver=self._refund_receiver,
+            nonce=self._nonce,
+        )
+
+
+def erc20_transfer(token: str, to: str, amount: int) -> SafeTransaction:
+    """
+    Create a transaction for ERC20 token transfer.
+
+    Args:
+        token: Token contract address.
+        to: Recipient address.
+        amount: Amount in smallest units.
+
+    Returns:
+        SafeTransaction for the transfer.
+    """
+    # Build calldata: transfer(address,uint256)
+    to_addr = Web3.to_checksum_address(to)
+    data = (
+        ERC20_TRANSFER_SELECTOR
+        + bytes(12)  # Padding for address
+        + bytes.fromhex(to_addr[2:])
+        + amount.to_bytes(32, "big")
+    )
+
+    return (
+        TransactionBuilder()
+        .to(token)
+        .data(data)
+        .build()
+    )
+
+
+def eth_transfer(to: str, amount: int) -> SafeTransaction:
+    """
+    Create a transaction for sending ETH.
+
+    Args:
+        to: Recipient address.
+        amount: Amount in wei.
+
+    Returns:
+        SafeTransaction for the transfer.
+    """
+    return (
+        TransactionBuilder()
+        .to(to)
+        .value(amount)
+        .build()
+    )
+
+
+def contract_call(target: str, data: bytes) -> SafeTransaction:
+    """
+    Create a transaction for calling a contract.
+
+    Args:
+        target: Target contract address.
+        data: Calldata.
+
+    Returns:
+        SafeTransaction for the call.
+    """
+    return (
+        TransactionBuilder()
+        .to(target)
+        .data(data)
+        .build()
+    )
+
+
+class BatchTransactionBuilder:
+    """Builder for batch transactions via MultiSend."""
+
+    def __init__(self):
+        """Initialize BatchTransactionBuilder."""
+        self._transactions: List[SafeTransaction] = []
+
+    def add(self, tx: SafeTransaction) -> "BatchTransactionBuilder":
+        """Add a transaction to the batch."""
+        self._transactions.append(tx)
+        return self
+
+    def add_transfer(
+        self, token: str, to: str, amount: int
+    ) -> "BatchTransactionBuilder":
+        """Add an ERC20 transfer to the batch."""
+        return self.add(erc20_transfer(token, to, amount))
+
+    def add_eth_transfer(self, to: str, amount: int) -> "BatchTransactionBuilder":
+        """Add an ETH transfer to the batch."""
+        return self.add(eth_transfer(to, amount))
+
+    def build(self) -> List[SafeTransaction]:
+        """Return all transactions in the batch."""
+        return self._transactions.copy()
+
+    def build_multisend(self) -> SafeTransaction:
+        """
+        Create a single transaction that executes all batch transactions via MultiSend.
+
+        Returns:
+            SafeTransaction for MultiSend execution.
+        """
+        # Encode each transaction for MultiSend
+        # Format: operation (1 byte) + to (20 bytes) + value (32 bytes) +
+        #         dataLength (32 bytes) + data (variable)
+        packed_txs = b""
+        for tx in self._transactions:
+            # Operation (1 byte)
+            packed_txs += bytes([tx.operation])
+
+            # To (20 bytes)
+            packed_txs += bytes.fromhex(tx.to[2:])
+
+            # Value (32 bytes)
+            packed_txs += tx.value.to_bytes(32, "big")
+
+            # Data length (32 bytes)
+            packed_txs += len(tx.data).to_bytes(32, "big")
+
+            # Data
+            packed_txs += tx.data
+
+        # Build MultiSend calldata
+        # multiSend(bytes transactions)
+        # Offset (32 bytes) + Length (32 bytes) + Data (padded to 32 bytes)
+        offset = (32).to_bytes(32, "big")  # Offset to data
+        length = len(packed_txs).to_bytes(32, "big")
+
+        # Pad to 32-byte boundary
+        padded_len = ((len(packed_txs) + 31) // 32) * 32
+        padded_data = packed_txs + b"\x00" * (padded_len - len(packed_txs))
+
+        calldata = MULTISEND_SELECTOR + offset + length + padded_data
+
+        return (
+            TransactionBuilder()
+            .to(SAFE_MULTISEND)
+            .data(calldata)
+            .delegate_call()
+            .build()
+        )

t402/multisig/types.py

@@ -0,0 +1,108 @@
+"""
+Type definitions for T402 Multi-sig (Safe) support.
+"""
+
+from dataclasses import dataclass, field
+from enum import IntEnum
+from typing import Dict, List, Optional
+
+
+class SignatureType(IntEnum):
+    """Type of signature for Safe transactions."""
+
+    EOA = 0  # Standard EOA signature
+    CONTRACT = 1  # EIP-1271 contract signature
+    APPROVED_HASH = 4  # Pre-approved hash
+
+
+class OperationType(IntEnum):
+    """Operation type for Safe transactions."""
+
+    CALL = 0
+    DELEGATE_CALL = 1
+
+
+@dataclass
+class SafeConfig:
+    """Configuration for a Safe multi-sig account."""
+
+    address: str
+    rpc_url: str
+    chain_id: Optional[int] = None
+
+
+@dataclass
+class SafeOwner:
+    """Represents an owner of a Safe account."""
+
+    address: str
+    index: int
+
+
+@dataclass
+class SafeTransaction:
+    """Represents a pending Safe transaction."""
+
+    to: str
+    value: int = 0
+    data: bytes = field(default_factory=bytes)
+    operation: OperationType = OperationType.CALL
+    safe_tx_gas: int = 0
+    base_gas: int = 0
+    gas_price: int = 0
+    gas_token: str = "0x0000000000000000000000000000000000000000"
+    refund_receiver: str = "0x0000000000000000000000000000000000000000"
+    nonce: Optional[int] = None
+
+
+@dataclass
+class SafeSignature:
+    """Holds a signature from a Safe owner."""
+
+    signer: str
+    signature: bytes
+    signature_type: SignatureType = SignatureType.EOA
+
+
+@dataclass
+class TransactionRequest:
+    """Represents a multi-sig transaction awaiting signatures."""
+
+    id: str
+    safe_address: str
+    transaction: SafeTransaction
+    transaction_hash: str
+    signatures: Dict[str, SafeSignature] = field(default_factory=dict)
+    threshold: int = 0
+    created_at: int = 0
+    expires_at: int = 0
+
+    def is_ready(self) -> bool:
+        """Check if enough signatures have been collected."""
+        return len(self.signatures) >= self.threshold
+
+    def collected_count(self) -> int:
+        """Return the number of signatures collected."""
+        return len(self.signatures)
+
+
+@dataclass
+class SafeInfo:
+    """Information about a Safe account."""
+
+    address: str
+    owners: List[str]
+    threshold: int
+    nonce: int
+    version: Optional[str] = None
+    chain_id: Optional[int] = None
+
+
+@dataclass
+class ExecutionResult:
+    """Result of executing a Safe transaction."""
+
+    tx_hash: str
+    success: bool
+    gas_used: int = 0
+    block_number: int = 0

t402/multisig/utils.py

@@ -0,0 +1,77 @@
+"""
+Utility functions for T402 Multi-sig support.
+"""
+
+import secrets
+import time
+from typing import List
+
+
+def generate_request_id() -> str:
+    """Generate a unique request ID."""
+    timestamp = int(time.time() * 1000)
+    random_bytes = secrets.token_hex(4)
+    return f"msig_{timestamp:x}_{random_bytes}"
+
+
+def current_timestamp() -> int:
+    """Get current Unix timestamp in seconds."""
+    return int(time.time())
+
+
+def sort_addresses(addresses: List[str]) -> List[str]:
+    """Sort addresses in ascending order (case-insensitive)."""
+    return sorted(addresses, key=lambda a: a.lower())
+
+
+def is_valid_threshold(threshold: int, owner_count: int) -> bool:
+    """Check if a threshold is valid for the given owner count."""
+    from .constants import MIN_THRESHOLD
+
+    return MIN_THRESHOLD <= threshold <= owner_count
+
+
+def are_addresses_unique(addresses: List[str]) -> bool:
+    """Check if all addresses are unique (case-insensitive)."""
+    lower_addresses = [a.lower() for a in addresses]
+    return len(set(lower_addresses)) == len(addresses)
+
+
+def get_owner_index(owner: str, owners: List[str]) -> int:
+    """
+    Get the index of an owner in the list.
+
+    Returns -1 if not found.
+    """
+    owner_lower = owner.lower()
+    for i, o in enumerate(owners):
+        if o.lower() == owner_lower:
+            return i
+    return -1
+
+
+def combine_signatures(signatures: dict) -> bytes:
+    """
+    Combine multiple signatures sorted by signer address.
+
+    Args:
+        signatures: Dict mapping signer address to SafeSignature.
+
+    Returns:
+        Combined signature bytes.
+    """
+    sorted_signers = sort_addresses(list(signatures.keys()))
+
+    packed = b""
+    for signer in sorted_signers:
+        sig = signatures[signer.lower()]
+        packed += sig.signature
+
+    return packed
+
+
+def pad_to_32_bytes(data: bytes) -> bytes:
+    """Pad data to 32 bytes."""
+    if len(data) >= 32:
+        return data[-32:]
+    return b"\x00" * (32 - len(data)) + data

t402/schemes/__init__.py

@@ -179,6 +179,17 @@ from t402.schemes.stacks import (
     SCHEME_EXACT_DIRECT as STACKS_SCHEME_EXACT_DIRECT,
 )
 
+# Cosmos Schemes
+from t402.schemes.cosmos import (
+    ExactDirectCosmosClientScheme,
+    ExactDirectCosmosServerScheme,
+    ExactDirectCosmosFacilitatorScheme,
+    ExactDirectCosmosFacilitatorConfig,
+    ClientCosmosSigner,
+    FacilitatorCosmosSigner,
+    SCHEME_EXACT_DIRECT as COSMOS_SCHEME_EXACT_DIRECT,
+)
+
 __all__ = [
     # Type aliases
     "Price",
@@ -285,4 +296,12 @@ __all__ = [
     "ClientStacksSigner",
     "FacilitatorStacksSigner",
     "STACKS_SCHEME_EXACT_DIRECT",
+    # Cosmos Schemes
+    "ExactDirectCosmosClientScheme",
+    "ExactDirectCosmosServerScheme",
+    "ExactDirectCosmosFacilitatorScheme",
+    "ExactDirectCosmosFacilitatorConfig",
+    "ClientCosmosSigner",
+    "FacilitatorCosmosSigner",
+    "COSMOS_SCHEME_EXACT_DIRECT",
 ]

t402/schemes/cosmos/__init__.py

@@ -0,0 +1,114 @@
+"""Cosmos/Noble Blockchain Payment Schemes.
+
+This package provides payment scheme implementations for the Cosmos/Noble blockchain.
+
+Supported schemes:
+- exact-direct: Client executes bank MsgSend, tx hash used as proof.
+
+Usage:
+    ```python
+    from t402.schemes.cosmos import (
+        # Client
+        ExactDirectCosmosClientScheme,
+        ExactDirectCosmosClientConfig,
+        # Server
+        ExactDirectCosmosServerScheme,
+        ExactDirectCosmosServerConfig,
+        # Facilitator
+        ExactDirectCosmosFacilitatorScheme,
+        ExactDirectCosmosFacilitatorConfig,
+        # Signer protocols
+        ClientCosmosSigner,
+        FacilitatorCosmosSigner,
+        # Constants
+        SCHEME_EXACT_DIRECT,
+        COSMOS_NOBLE_MAINNET,
+        COSMOS_NOBLE_TESTNET,
+    )
+    ```
+"""
+
+from t402.schemes.cosmos.exact_direct import (
+    ExactDirectCosmosClientScheme,
+    ExactDirectCosmosServerScheme,
+    ExactDirectCosmosFacilitatorScheme,
+)
+from t402.schemes.cosmos.exact_direct.client import ExactDirectCosmosClientConfig
+from t402.schemes.cosmos.exact_direct.server import ExactDirectCosmosServerConfig
+from t402.schemes.cosmos.exact_direct.facilitator import ExactDirectCosmosFacilitatorConfig
+from t402.schemes.cosmos.types import (
+    ClientCosmosSigner,
+    FacilitatorCosmosSigner,
+    ExactDirectPayload,
+    TransactionResult,
+    MsgSend,
+    Coin,
+)
+from t402.schemes.cosmos.constants import (
+    SCHEME_EXACT_DIRECT,
+    COSMOS_NOBLE_MAINNET,
+    COSMOS_NOBLE_TESTNET,
+    NOBLE_MAINNET_RPC,
+    NOBLE_TESTNET_RPC,
+    NOBLE_MAINNET_REST,
+    NOBLE_TESTNET_REST,
+    NOBLE_BECH32_PREFIX,
+    USDC_DENOM,
+    DEFAULT_GAS_LIMIT,
+    MSG_TYPE_SEND,
+    CAIP_FAMILY,
+    USDC_TOKEN,
+    TokenInfo,
+    NetworkConfig,
+    get_network_config,
+    get_token_info,
+    get_token_by_denom,
+    is_valid_network,
+    is_valid_address,
+    get_supported_networks,
+)
+
+__all__ = [
+    # Scheme implementations
+    "ExactDirectCosmosClientScheme",
+    "ExactDirectCosmosServerScheme",
+    "ExactDirectCosmosFacilitatorScheme",
+    # Configurations
+    "ExactDirectCosmosClientConfig",
+    "ExactDirectCosmosServerConfig",
+    "ExactDirectCosmosFacilitatorConfig",
+    # Signer protocols
+    "ClientCosmosSigner",
+    "FacilitatorCosmosSigner",
+    # Payload types
+    "ExactDirectPayload",
+    "TransactionResult",
+    "MsgSend",
+    "Coin",
+    # Validation
+    "is_valid_network",
+    "is_valid_address",
+    # Constants
+    "SCHEME_EXACT_DIRECT",
+    "COSMOS_NOBLE_MAINNET",
+    "COSMOS_NOBLE_TESTNET",
+    "NOBLE_MAINNET_RPC",
+    "NOBLE_TESTNET_RPC",
+    "NOBLE_MAINNET_REST",
+    "NOBLE_TESTNET_REST",
+    "NOBLE_BECH32_PREFIX",
+    "USDC_DENOM",
+    "DEFAULT_GAS_LIMIT",
+    "MSG_TYPE_SEND",
+    "CAIP_FAMILY",
+    # Token definitions
+    "USDC_TOKEN",
+    # Data classes
+    "TokenInfo",
+    "NetworkConfig",
+    # Lookup functions
+    "get_network_config",
+    "get_token_info",
+    "get_token_by_denom",
+    "get_supported_networks",
+]