mm-web3 0.5.0__py3-none-any.whl

mm_web3/__init__.py

@@ -0,0 +1,21 @@
+from mm_web3.account import PrivateKeyMap as PrivateKeyMap
+from mm_web3.calcs import calc_decimal_expression as calc_decimal_expression
+from mm_web3.calcs import calc_expression_with_vars as calc_expression_with_vars
+from mm_web3.calcs import convert_value_with_units as convert_value_with_units
+from mm_web3.config import Web3CliConfig as Web3CliConfig
+from mm_web3.log import init_loguru as init_loguru
+from mm_web3.network import Network as Network
+from mm_web3.network import NetworkType as NetworkType
+from mm_web3.node import Nodes as Nodes
+from mm_web3.node import random_node as random_node
+from mm_web3.proxy import Proxies as Proxies
+from mm_web3.proxy import fetch_proxies as fetch_proxies
+from mm_web3.proxy import fetch_proxies_sync as fetch_proxies_sync
+from mm_web3.proxy import is_valid_proxy_url as is_valid_proxy_url
+from mm_web3.proxy import random_proxy as random_proxy
+from mm_web3.retry import retry_with_node_and_proxy as retry_with_node_and_proxy
+from mm_web3.retry import retry_with_proxy as retry_with_proxy
+from mm_web3.utils import read_items_from_file as read_items_from_file
+from mm_web3.utils import read_lines_from_file as read_lines_from_file
+from mm_web3.validators import ConfigValidators as ConfigValidators
+from mm_web3.validators import Transfer as Transfer

mm_web3/account.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+import contextlib
+from collections.abc import Callable
+from pathlib import Path
+
+from pydantic import GetCoreSchemaHandler, ValidationInfo
+from pydantic_core import core_schema
+
+
+class PrivateKeyMap(dict[str, str]):
+    """Map of addresses to private keys with fast lookup by address."""
+
+    def contains_all_addresses(self, addresses: list[str]) -> bool:
+        """Check if all addresses are in the map."""
+        return set(addresses) <= set(self.keys())
+
+    @classmethod
+    def __get_pydantic_core_schema__(cls, _source: object, handler: GetCoreSchemaHandler) -> core_schema.CoreSchema:
+        # Use the dict schema as the basis.
+        return core_schema.with_info_after_validator_function(
+            cls.validate,  # our function that converts a dict to PrivateKeyMap
+            handler(dict),  # get the schema for a plain dict
+        )
+
+    @classmethod
+    def validate(cls, value: object, _info: ValidationInfo) -> PrivateKeyMap:
+        """
+        Convert and validate an input value into a PrivateKeyMap.
+
+        - If the input is already a PrivateKeyMap, return it.
+        - If it is a dict, check that all keys and values are strings and
+          then return a PrivateKeyMap.
+        - Otherwise, raise a TypeError.
+        """
+        if isinstance(value, cls):
+            return value
+        if isinstance(value, dict):
+            # Optionally, ensure all keys and values are strings.
+            if not all(isinstance(k, str) for k in value):
+                raise TypeError("All keys in PrivateKeyMap must be strings")
+            if not all(isinstance(v, str) for v in value.values()):
+                raise TypeError("All values in PrivateKeyMap must be strings")
+            return cls(value)
+        raise TypeError("Invalid type for PrivateKeyMap. Expected dict or PrivateKeyMap.")
+
+    @staticmethod
+    def from_list(private_keys: list[str], address_from_private: Callable[[str], str]) -> PrivateKeyMap:
+        """Create a dictionary of private keys with addresses as keys.
+
+        Args:
+            private_keys: List of private keys. Must be fully valid:
+                - No empty strings
+                - No whitespace-only strings
+                - No duplicates
+            address_from_private: Function to derive address from private key
+
+        Raises:
+            ValueError: if any private key is invalid
+        """
+        # Check for duplicates
+        if len(private_keys) != len(set(private_keys)):
+            raise ValueError("duplicate private keys found")
+
+        result = PrivateKeyMap()
+        for private_key in private_keys:
+            address = None
+            with contextlib.suppress(Exception):
+                address = address_from_private(private_key)
+            if address is None:
+                raise ValueError("invalid private key")
+            result[address] = private_key
+        return result
+
+    @staticmethod
+    def from_file(private_keys_file: Path, address_from_private: Callable[[str], str]) -> PrivateKeyMap:
+        """Create a dictionary of private keys with addresses as keys from a file.
+        Raises:
+            ValueError: If the file cannot be read or any private key is invalid.
+        """
+        private_keys_file = private_keys_file.expanduser()
+        try:
+            content = private_keys_file.read_text().strip()
+        except OSError as e:
+            raise ValueError(f"can't read from the file: {private_keys_file}") from e
+
+        private_keys = content.split("\n") if content else []
+        return PrivateKeyMap.from_list(private_keys, address_from_private)

mm_web3/calcs.py

@@ -0,0 +1,217 @@
+import random
+import re
+from decimal import Decimal
+
+from mm_std import random_decimal
+
+
+def calc_decimal_expression(expression: str) -> Decimal:
+    """Calculate decimal value from string expression.
+
+    Supports:
+    - Plain numbers: "123.45", "-0.5"
+    - Random function: "random(min, max)" returns random decimal between min and max
+
+    Args:
+        expression: String expression to calculate
+
+    Returns:
+        Calculated decimal value
+
+    Raises:
+        ValueError: If expression format is invalid or random range is invalid (min > max)
+    """
+    expression = expression.lower().strip()
+    if expression.startswith("random(") and expression.endswith(")"):
+        arr = expression.lstrip("random(").rstrip(")").split(",")
+        if len(arr) != 2:
+            raise ValueError(f"wrong expression, random part: {expression}")
+        try:
+            from_value = Decimal(arr[0])
+            to_value = Decimal(arr[1])
+        except Exception as e:
+            raise ValueError(f"wrong expression, random part: {expression}") from e
+        if from_value > to_value:
+            raise ValueError(f"wrong expression, random part: {expression}")
+        return random_decimal(from_value, to_value)
+
+    try:
+        return Decimal(expression)
+    except Exception as e:
+        raise ValueError(f"invalid decimal expression: {expression}") from e
+
+
+def convert_value_with_units(value: str, unit_decimals: dict[str, int]) -> int:
+    """Convert value with units to base integer units.
+
+    Converts values like "1.5eth" to base units (wei) using decimal places mapping.
+
+    Args:
+        value: String value to convert (e.g., "123.45eth", "100")
+        unit_decimals: Mapping of unit suffixes to decimal places (e.g., {"eth": 18})
+
+    Returns:
+        Value converted to base integer units
+
+    Raises:
+        ValueError: If value is negative or unit suffix is not recognized
+    """
+    value = value.lower().strip()
+    if value.startswith("-"):
+        raise ValueError(f"negative value is illegal: {value}")
+    if value.isdigit():
+        return int(value)
+    unit_decimals = {k.lower(): v for k, v in unit_decimals.items()}
+    for suffix in unit_decimals:
+        if value.endswith(suffix):
+            value = value.removesuffix(suffix)
+            return int(Decimal(value) * 10 ** unit_decimals[suffix])
+
+    raise ValueError(f"illegal value: {value}")
+
+
+def calc_expression_with_vars(
+    expression: str, variables: dict[str, int] | None = None, unit_decimals: dict[str, int] | None = None
+) -> int:
+    """Calculate complex integer expression with variables, units and random values.
+
+    Supports:
+    - Arithmetic operations: "+", "-"
+    - Variables with multipliers: "balance", "0.5balance"
+    - Unit conversions: "1.5eth", "100gwei"
+    - Random function: "random(1eth, 2eth)"
+    - Mixed expressions: "0.2balance + random(1gwei, 2gwei) - 100"
+
+    Args:
+        expression: String expression to calculate
+        variables: Mapping of variable names to their integer values
+        unit_decimals: Mapping of unit suffixes to decimal places
+
+    Returns:
+        Calculated integer value in base units
+
+    Raises:
+        ValueError: If expression format is invalid
+        TypeError: If expression is not a string
+    """
+    if not isinstance(expression, str):
+        raise TypeError(f"expression is not str: {expression}")
+    expression = expression.lower().strip()
+    if unit_decimals is None:
+        unit_decimals = {}
+    if variables is None:
+        variables = {}
+    unit_decimals = {k.lower(): v for k, v in unit_decimals.items()}
+    variables = {k.lower(): v for k, v in variables.items()}
+
+    # Check for conflicts between variable names and unit suffixes
+    for var_name in variables:
+        if var_name in unit_decimals:
+            raise ValueError(f"variable name conflicts with unit suffix: {var_name}")
+
+    try:
+        result = 0
+        for token in _split_on_plus_minus_tokens(expression.lower()):
+            operator = token[0]
+            term = token[1:]
+            suffix = _get_suffix(term, unit_decimals)
+
+            if term.isdigit():
+                term_value = int(term)
+            elif suffix is not None:
+                term_value = convert_value_with_units(term, unit_decimals)
+            elif variables:
+                # Check if term ends with any variable name
+                matched_var = None
+                for var_name in variables:
+                    if term.endswith(var_name):
+                        matched_var = var_name
+                        break
+
+                if matched_var:
+                    multiplier_part = term.removesuffix(matched_var)
+                    multiplier = Decimal(multiplier_part) if multiplier_part else Decimal(1)
+                    term_value = int(multiplier * variables[matched_var])
+                # Check for random function
+                elif term.startswith("random(") and term.endswith(")"):
+                    term_value = _parse_random_function(term, unit_decimals)
+                else:
+                    raise ValueError(f"unrecognized term: {term}")  # noqa: TRY301
+            elif term.startswith("random(") and term.endswith(")"):
+                term_value = _parse_random_function(term, unit_decimals)
+            else:
+                raise ValueError(f"unrecognized term: {term}")  # noqa: TRY301
+
+            if operator == "+":
+                result += term_value
+            if operator == "-":
+                result -= term_value
+
+        return result  # noqa: TRY300
+    except Exception as e:
+        raise ValueError(e) from e
+
+
+def _parse_random_function(term: str, unit_decimals: dict[str, int]) -> int:
+    """Extract random function parameters and generate random value within range.
+
+    Supports unit conversion in random bounds to ensure consistent base units.
+    """
+    content = term.lstrip("random(").rstrip(")")
+    parts = content.split(",")
+    if len(parts) != 2:
+        raise ValueError(f"random function must have exactly 2 arguments: {term}")
+
+    from_value = convert_value_with_units(parts[0].strip(), unit_decimals)
+    to_value = convert_value_with_units(parts[1].strip(), unit_decimals)
+
+    if from_value > to_value:
+        raise ValueError(f"random range invalid, min > max: {term}")
+
+    return random.randint(from_value, to_value)
+
+
+def _get_suffix(item: str, unit_decimals: dict[str, int]) -> str | None:
+    """Find unit suffix in term to enable unit conversion.
+
+    Returns first matching suffix to avoid ambiguity in complex expressions.
+    """
+    for suffix in unit_decimals:
+        if item.endswith(suffix):
+            return suffix
+    return None
+
+
+def _split_on_plus_minus_tokens(value: str) -> list[str]:
+    """Split expression into signed terms for sequential evaluation.
+
+    Normalizes input by removing spaces and adding leading '+' when needed.
+    Each token contains operator (+ or -) followed by the term value.
+    """
+    value = "".join(value.split())
+    if not value:
+        raise ValueError("value is empty")
+    if "++" in value:
+        raise ValueError("++ in value")
+    if "--" in value:
+        raise ValueError("-- in value")
+    if value.endswith("-"):
+        raise ValueError("ends with -")
+    if value.endswith("+"):
+        raise ValueError("ends with +")
+
+    if not value.startswith("+") and not value.startswith("-"):
+        value = "+" + value
+
+    result: list[str] = []
+    rest_value = value
+    while True:
+        if not rest_value:
+            return result
+        items = re.split(r"[+\-]", rest_value)
+        if rest_value.startswith("+"):
+            result.append("+" + items[1])
+            rest_value = rest_value.removeprefix("+" + items[1])
+        elif rest_value.startswith("-"):
+            result.append("-" + items[1])
+            rest_value = rest_value.removeprefix("-" + items[1])

mm_web3/config.py

@@ -0,0 +1,160 @@
+import sys
+import tomllib
+from pathlib import Path
+from typing import Any, NoReturn, Self, TypeVar
+from zipfile import ZipFile
+
+import mm_print
+from mm_result import Result
+from pydantic import BaseModel, ConfigDict, ValidationError
+
+T = TypeVar("T", bound="Web3CliConfig")
+
+
+class Web3CliConfig(BaseModel):
+    """Base configuration class for cryptocurrency CLI tools.
+
+    Provides TOML file loading with optional ZIP archive support,
+    validation error handling, and debug printing capabilities.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    def print_and_exit(self, exclude: set[str] | None = None, count: set[str] | None = None) -> NoReturn:
+        """Print config as JSON and exit the program.
+
+        Args:
+            exclude: Fields to exclude from output
+            count: Fields to show as length instead of full content
+        """
+        data = self.model_dump(exclude=exclude)
+        if count:
+            for k in count:
+                data[k] = len(data[k])
+        mm_print.json(data)
+        sys.exit(0)
+
+    @classmethod
+    def read_toml_config_or_exit(cls, config_path: Path, zip_password: str = "") -> Self:  # nosec
+        """Read TOML config file, exit on error.
+
+        Args:
+            config_path: Path to TOML file or ZIP archive
+            zip_password: Password for encrypted ZIP archives
+
+        Returns:
+            Validated config instance
+        """
+        res: Result[Self] = cls.read_toml_config(config_path, zip_password)
+        if res.is_ok():
+            return res.unwrap()
+        cls._print_error_and_exit(res)
+
+    @classmethod
+    async def read_toml_config_or_exit_async(cls, config_path: Path, zip_password: str = "") -> Self:  # nosec
+        """Read TOML config file with async validation, exit on error.
+
+        Args:
+            config_path: Path to TOML file or ZIP archive
+            zip_password: Password for encrypted ZIP archives
+
+        Returns:
+            Validated config instance
+        """
+        res: Result[Self] = await cls.read_toml_config_async(config_path, zip_password)
+        if res.is_ok():
+            return res.unwrap()
+        cls._print_error_and_exit(res)
+
+    @classmethod
+    def _load_toml_data(cls, config_path: Path, zip_password: str = "") -> dict[str, Any]:  # nosec
+        """Load TOML data from file or ZIP archive.
+
+        Args:
+            config_path: Path to TOML file or ZIP archive
+            zip_password: Password for encrypted ZIP archives
+
+        Returns:
+            Parsed TOML data as dictionary
+        """
+        config_path = config_path.expanduser()
+        if config_path.name.endswith(".zip"):
+            return tomllib.loads(read_text_from_zip_archive(config_path, password=zip_password))
+        with config_path.open("rb") as f:
+            return tomllib.load(f)
+
+    @classmethod
+    def read_toml_config(cls, config_path: Path, zip_password: str = "") -> Result[Self]:  # nosec
+        """Read and validate TOML config file.
+
+        Args:
+            config_path: Path to TOML file or ZIP archive
+            zip_password: Password for encrypted ZIP archives
+
+        Returns:
+            Result containing validated config or error details
+        """
+        try:
+            data = cls._load_toml_data(config_path, zip_password)
+            return Result.ok(cls(**data))
+        except ValidationError as e:
+            return Result.err(("validator_error", e), extra={"errors": e.errors()})
+        except Exception as e:
+            return Result.err(e)
+
+    @classmethod
+    async def read_toml_config_async(cls, config_path: Path, zip_password: str = "") -> Result[Self]:  # nosec
+        """Read and validate TOML config file with async validators.
+
+        Use this method when your config has async model validators that
+        need to perform network requests or database queries.
+
+        Args:
+            config_path: Path to TOML file or ZIP archive
+            zip_password: Password for encrypted ZIP archives
+
+        Returns:
+            Result containing validated config or error details
+        """
+        try:
+            data = cls._load_toml_data(config_path, zip_password)
+            model = await cls.model_validate(data)  # type: ignore[misc]
+            return Result.ok(model)
+        except ValidationError as e:
+            return Result.err(("validator_error", e), extra={"errors": e.errors()})
+        except Exception as e:
+            return Result.err(e)
+
+    @classmethod
+    def _print_error_and_exit(cls, res: Result[Any]) -> NoReturn:
+        """Print validation errors and exit with status code 1.
+
+        Args:
+            res: Failed Result containing error information
+        """
+        if res.error == "validator_error" and res.extra:
+            mm_print.plain("config validation errors")
+            for e in res.extra["errors"]:
+                loc = e["loc"]
+                field = ".".join(str(lo) for lo in loc) if len(loc) > 0 else ""
+                mm_print.plain(f"{field} {e['msg']}")
+        else:
+            mm_print.plain(f"can't parse config file: {res.error} {res.extra}")
+        sys.exit(1)
+
+
+def read_text_from_zip_archive(zip_archive_path: Path, filename: str | None = None, password: str | None = None) -> str:
+    """Read text content from ZIP archive.
+
+    Args:
+        zip_archive_path: Path to ZIP archive
+        filename: Specific file to read (first file if None)
+        password: Archive password if encrypted
+
+    Returns:
+        Decoded text content of the file
+    """
+    with ZipFile(zip_archive_path) as zipfile:
+        if filename is None:
+            filename = zipfile.filelist[0].filename
+        return zipfile.read(filename, pwd=password.encode() if password else None).decode()

mm_web3/log.py

@@ -0,0 +1,20 @@
+import sys
+from pathlib import Path
+
+from loguru import logger
+
+
+def init_loguru(debug: bool, debug_file: Path | None, info_file: Path | None) -> None:
+    if debug:
+        level = "DEBUG"
+        format_ = "<green>{time:YYYY-MM-DD HH:mm:ss}</green> <level>{level}</level> {message}"
+    else:
+        level = "INFO"
+        format_ = "{message}"
+
+    logger.remove()
+    logger.add(sys.stderr, format=format_, colorize=True, level=level)
+    if debug_file:
+        logger.add(debug_file.expanduser(), format="{time:YYYY-MM-DD HH:mm:ss} {level} {message}")
+    if info_file:
+        logger.add(info_file.expanduser(), format="{message}", level="INFO")

mm_web3/network.py

@@ -0,0 +1,191 @@
+"""Network types and utilities for different blockchain networks."""
+
+from __future__ import annotations
+
+from enum import StrEnum, unique
+
+
+@unique
+class NetworkType(StrEnum):
+    """Base network types (EVM, Solana, etc)."""
+
+    EVM = "evm"
+    SOLANA = "solana"
+    APTOS = "aptos"
+    STARKNET = "starknet"
+
+    def lowercase_address(self) -> bool:
+        """Whether addresses for this network type should be lowercase."""
+        match self:
+            case NetworkType.EVM:
+                return True
+            case NetworkType.SOLANA:
+                return False
+            case NetworkType.APTOS:
+                return True
+            case NetworkType.STARKNET:
+                return True
+        raise ValueError("no network found")
+
+
+@unique
+class Network(StrEnum):
+    """Blockchain networks"""
+
+    APTOS = "aptos"
+    ARBITRUM_ONE = "arbitrum-one"
+    AVAX_C = "avax-c"
+    BASE = "base"
+    BSC = "bsc"
+    CELO = "celo"
+    CORE = "core"
+    ETHEREUM = "ethereum"
+    FANTOM = "fantom"
+    LINEA = "linea"
+    OPBNB = "opbnb"
+    OP_MAINNET = "op-mainnet"
+    POLYGON = "polygon"
+    POLYGON_ZKEVM = "polygon-zkevm"
+    SCROLL = "scroll"
+    SOLANA = "solana"
+    STARKNET = "starknet"
+    ZKSYNC_ERA = "zksync-era"
+    ZORA = "zora"
+
+    @property
+    def network_type(self) -> NetworkType:
+        """Get the base network type (EVM, Solana, etc)."""
+        if self in self.evm_networks():
+            return NetworkType.EVM
+        if self in self.solana_networks():
+            return NetworkType.SOLANA
+        if self in self.aptos_networks():
+            return NetworkType.APTOS
+        if self in self.starknet_networks():
+            return NetworkType.STARKNET
+        raise ValueError("no network found")
+
+    def explorer_token(self, token: str) -> str:
+        """Get explorer URL for a token address."""
+        match self:
+            case Network.ARBITRUM_ONE:
+                return f"https://arbiscan.io/token/{token}"
+            case Network.AVAX_C:
+                return f"https://snowtrace.io/token/{token}"
+            case Network.APTOS:
+                return f"https://explorer.aptoslabs.com/coin/{token}"
+            case Network.BASE:
+                return f"https://basescan.org/token/{token}"
+            case Network.BSC:
+                return f"https://bscscan.com/token/{token}"
+            case Network.CELO:
+                return f"https://celoscan.io/token/{token}"
+            case Network.CORE:
+                return f"https://scan.coredao.org/token/{token}"
+            case Network.ETHEREUM:
+                return f"https://etherscan.io/token/{token}"
+            case Network.FANTOM:
+                return f"https://ftmscan.com/token/{token}"
+            case Network.LINEA:
+                return f"https://lineascan.build/token/{token}"
+            case Network.OPBNB:
+                return f"https://opbnbscan.com/token/{token}"
+            case Network.OP_MAINNET:
+                return f"https://optimistic.etherscan.io/token/{token}"
+            case Network.POLYGON:
+                return f"https://polygonscan.com/token/{token}"
+            case Network.POLYGON_ZKEVM:
+                return f"https://zkevm.polygonscan.com/token/{token}"
+            case Network.SCROLL:
+                return f"https://scrollscan.com/token/{token}"
+            case Network.SOLANA:
+                return f"https://solscan.io/token/{token}"
+            case Network.STARKNET:
+                return f"https://voyager.online/token/{token}"
+            case Network.ZKSYNC_ERA:
+                return f"https://explorer.zksync.io/token/{token}"
+            case Network.ZORA:
+                return f"https://explorer.zora.energy/tokens/{token}"
+
+        raise ValueError("no network found")
+
+    def explorer_account(self, account: str) -> str:
+        """Get explorer URL for an account address."""
+        match self:
+            case Network.ARBITRUM_ONE:
+                return f"https://arbiscan.io/address/{account}"
+            case Network.AVAX_C:
+                return f"https://snowtrace.io/address/{account}"
+            case Network.APTOS:
+                return f"https://explorer.aptoslabs.com/account/{account}"
+            case Network.BASE:
+                return f"https://basescan.org/address/{account}"
+            case Network.BSC:
+                return f"https://bscscan.com/address/{account}"
+            case Network.CELO:
+                return f"https://celoscan.io/address/{account}"
+            case Network.CORE:
+                return f"https://scan.coredao.org/address/{account}"
+            case Network.ETHEREUM:
+                return f"https://etherscan.io/address/{account}"
+            case Network.FANTOM:
+                return f"https://ftmscan.com/address/{account}"
+            case Network.LINEA:
+                return f"https://lineascan.build/address/{account}"
+            case Network.OPBNB:
+                return f"https://opbnbscan.com/address/{account}"
+            case Network.OP_MAINNET:
+                return f"https://optimistic.etherscan.io/address/{account}"
+            case Network.POLYGON:
+                return f"https://polygonscan.com/address/{account}"
+            case Network.POLYGON_ZKEVM:
+                return f"https://zkevm.polygonscan.com/address/{account}"
+            case Network.SCROLL:
+                return f"https://scrollscan.com/address/{account}"
+            case Network.SOLANA:
+                return f"https://solscan.io/account/{account}"
+            case Network.ZKSYNC_ERA:
+                return f"https://explorer.zksync.io/address/{account}"
+            case Network.STARKNET:
+                return f"https://voyager.online/contract/{account}"
+            case Network.ZORA:
+                return f"https://explorer.zora.energy/address/{account}"
+
+        raise ValueError("no network found")
+
+    @classmethod
+    def evm_networks(cls) -> list[Network]:
+        """Get list of all EVM-compatible networks."""
+        return [
+            Network.ARBITRUM_ONE,
+            Network.AVAX_C,
+            Network.BASE,
+            Network.BSC,
+            Network.CELO,
+            Network.CORE,
+            Network.ETHEREUM,
+            Network.FANTOM,
+            Network.LINEA,
+            Network.OPBNB,
+            Network.OP_MAINNET,
+            Network.POLYGON,
+            Network.POLYGON_ZKEVM,
+            Network.SCROLL,
+            Network.ZKSYNC_ERA,
+            Network.ZORA,
+        ]
+
+    @classmethod
+    def solana_networks(cls) -> list[Network]:
+        """Get list of all Solana networks."""
+        return [Network.SOLANA]
+
+    @classmethod
+    def aptos_networks(cls) -> list[Network]:
+        """Get list of all Aptos networks."""
+        return [Network.APTOS]
+
+    @classmethod
+    def starknet_networks(cls) -> list[Network]:
+        """Get list of all Starknet networks."""
+        return [Network.STARKNET]

mm_web3/node.py

@@ -0,0 +1,38 @@
+import random
+from collections.abc import Sequence
+
+type Nodes = str | Sequence[str]
+"""
+Type alias for JSON RPC node configuration.
+
+Can be either:
+- A single node URL as string
+- A sequence (list, tuple) of node URLs
+"""
+
+
+def random_node(nodes: Nodes, remove_slash: bool = True) -> str:
+    """
+    Select a random JSON RPC node from the provided nodes.
+
+    Args:
+        nodes: Single node URL or sequence of node URLs
+        remove_slash: Whether to remove trailing slash from the URL
+
+    Returns:
+        Selected node URL
+
+    Raises:
+        ValueError: When no valid node can be selected
+    """
+    if isinstance(nodes, str):
+        selected = nodes
+    else:
+        if not nodes:
+            raise ValueError("No nodes provided")
+        selected = random.choice(nodes)
+
+    if remove_slash and selected.endswith("/"):
+        selected = selected.removesuffix("/")
+
+    return selected

mm_web3/proxy.py

@@ -0,0 +1,106 @@
+"""Proxy utilities for HTTP requests."""
+
+import random
+from collections.abc import Sequence
+from urllib.parse import urlparse
+
+from mm_http import http_request, http_request_sync
+from mm_result import Result
+
+type Proxies = str | Sequence[str] | None
+"""Proxy configuration: single URL, sequence of URLs, or None for no proxy."""
+
+
+def random_proxy(proxies: Proxies) -> str | None:
+    """Select a random proxy from the given configuration."""
+    if proxies is None:
+        return None
+
+    if isinstance(proxies, str):
+        return proxies
+
+    # proxies is a Sequence[str] at this point
+    if proxies:
+        return random.choice(proxies)
+
+    return None
+
+
+async def fetch_proxies(proxies_url: str, timeout: float = 5) -> Result[list[str]]:
+    """Fetch proxies from the given url. Expects content-type: text/plain with one proxy per line. Each proxy must be valid."""
+    res = await http_request(proxies_url, timeout=timeout)
+    if res.is_err():
+        return res.to_result_err()
+
+    proxies = [p.strip() for p in (res.body or "").splitlines() if p.strip()]
+    proxies = list(dict.fromkeys(proxies))
+    for proxy in proxies:
+        if not is_valid_proxy_url(proxy):
+            return res.to_result_err(f"Invalid proxy URL: {proxy}")
+
+    if not proxies:
+        return res.to_result_err("No valid proxies found")
+    return res.to_result_ok(proxies)
+
+
+def fetch_proxies_sync(proxies_url: str, timeout: float = 5) -> Result[list[str]]:
+    """Synchronous version of fetch_proxies."""
+    res = http_request_sync(proxies_url, timeout=timeout)
+    if res.is_err():
+        return res.to_result_err()
+
+    proxies = [p.strip() for p in (res.body or "").splitlines() if p.strip()]
+    proxies = list(dict.fromkeys(proxies))
+    for proxy in proxies:
+        if not is_valid_proxy_url(proxy):
+            return res.to_result_err(f"Invalid proxy URL: {proxy}")
+
+    if not proxies:
+        return res.to_result_err("No valid proxies found")
+    return res.to_result_ok(proxies)
+
+
+def is_valid_proxy_url(proxy_url: str) -> bool:
+    """
+    Check if the given URL is a valid proxy URL.
+
+    A valid proxy URL must have:
+      - A scheme in {"http", "https", "socks4", "socks5", "zsocks5h"}.
+      - A non-empty hostname.
+      - A specified port.
+      - No extra path components (the path must be empty or "/").
+
+    For SOCKS4 URLs, authentication (username/password) is not supported.
+
+    Examples:
+      is_valid_proxy_url("socks5h://user:pass@proxy.example.com:1080") -> True
+      is_valid_proxy_url("http://proxy.example.com:8080") -> True
+      is_valid_proxy_url("socks4://proxy.example.com:1080") -> True
+      is_valid_proxy_url("socks4://user:pass@proxy.example.com:1080") -> False
+      is_valid_proxy_url("ftp://proxy.example.com:21") -> False
+      is_valid_proxy_url("socks4://proxy.example.com:1080/bla-bla-bla") -> False
+    """
+    try:
+        parsed = urlparse(proxy_url)
+    except Exception:
+        return False
+
+    allowed_schemes = {"http", "https", "socks4", "socks5", "socks5h"}
+    if parsed.scheme not in allowed_schemes:
+        return False
+
+    if not parsed.hostname:
+        return False
+
+    if not parsed.port:
+        return False
+
+    # For SOCKS4, authentication is not supported.
+    if parsed.scheme == "socks4" and (parsed.username or parsed.password):
+        return False
+
+    # Ensure that there is no extra path (only allow an empty path or a single "/")
+    if parsed.path and parsed.path not in ("", "/"):  # noqa: SIM103
+        return False
+
+    return True

mm_web3/retry.py

@@ -0,0 +1,68 @@
+from collections.abc import Awaitable, Callable
+from typing import TypeVar
+
+from mm_result import Result
+
+from mm_web3.node import Nodes, random_node
+from mm_web3.proxy import Proxies, random_proxy
+
+T = TypeVar("T")
+
+# Function that takes (node, proxy) and returns an Awaitable[Result[T]]
+FuncWithNodeAndProxy = Callable[[str, str | None], Awaitable[Result[T]]]
+
+# Function that takes only (proxy) and returns an Awaitable[Result[T]]
+FuncWithProxy = Callable[[str | None], Awaitable[Result[T]]]
+
+
+async def retry_with_node_and_proxy(retries: int, nodes: Nodes, proxies: Proxies, func: FuncWithNodeAndProxy[T]) -> Result[T]:
+    """
+    Retry the given function multiple times with random node and proxy on each attempt.
+
+    Args:
+        retries: Number of attempts to make.
+        nodes: Available nodes to randomly choose from.
+        proxies: Available proxies to randomly choose from.
+        func: Async function that accepts (node, proxy) and returns a Result.
+
+    Returns:
+        Result with success on first successful call, or last failure with logs of attempts.
+    """
+    res: Result[T] = Result.err("not_started")
+    logs = []
+
+    for _ in range(retries):
+        node = random_node(nodes)
+        proxy = random_proxy(proxies)
+        res = await func(node, proxy)
+        logs.append({"node": node, "proxy": proxy, "result": res.to_dict()})
+        if res.is_ok():
+            return Result.ok(res.unwrap(), {"retry_logs": logs})
+
+    return Result.err(res.unwrap_err(), {"retry_logs": logs})
+
+
+async def retry_with_proxy(retries: int, proxies: Proxies, func: FuncWithProxy[T]) -> Result[T]:
+    """
+    Retry the given function multiple times using a random proxy on each attempt.
+
+
+    Args:
+        retries: Number of attempts to make.
+        proxies: Available proxies to randomly choose from.
+        func: Async function that accepts (proxy) and returns a Result.
+
+    Returns:
+        Result with success on first successful call, or last failure with logs of attempts.
+    """
+    res: Result[T] = Result.err("not_started")
+    logs = []
+
+    for _ in range(retries):
+        proxy = random_proxy(proxies)
+        res = await func(proxy)
+        logs.append({"proxy": proxy, "result": res.to_dict()})
+        if res.is_ok():
+            return Result.ok(res.unwrap(), {"retry_logs": logs})
+
+    return Result.err(res.unwrap_err(), {"retry_logs": logs})

mm_web3/utils.py

@@ -0,0 +1,67 @@
+from collections.abc import Callable
+from pathlib import Path
+
+
+def read_items_from_file(path: Path, is_valid: Callable[[str], bool], lowercase: bool = False) -> list[str]:
+    """Read items from a file and validate them.
+
+    Raises:
+        ValueError: if the file cannot be read or any item is invalid.
+    """
+    path = path.expanduser()
+    if not path.is_file():
+        raise ValueError(f"{path} is not a file")
+
+    try:
+        with path.open() as file:
+            items = []
+            for line_num, raw_line in enumerate(file, 1):
+                item = raw_line.strip()
+                if not item:  # Skip empty lines
+                    continue
+
+                if lowercase:
+                    item = item.lower()
+
+                if not is_valid(item):
+                    raise ValueError(f"Invalid item in {path} at line {line_num}: {item}")
+                items.append(item)
+
+            return items
+    except OSError as e:
+        raise ValueError(f"Cannot read file {path}: {e}") from e
+
+
+def read_lines_from_file(source: Path | str, lowercase: bool = False) -> list[str]:
+    """Read non-empty lines from a file.
+
+    Args:
+        source: Path to the file to read from.
+        lowercase: If True, convert all lines to lowercase.
+
+    Returns:
+        List of non-empty lines from the file.
+
+    Raises:
+        ValueError: if the file cannot be read or is not a file.
+    """
+    path = Path(source).expanduser()
+    if not path.is_file():
+        raise ValueError(f"{path} is not a file")
+
+    try:
+        with path.open() as file:
+            lines = []
+            for raw_line in file:
+                stripped_line = raw_line.strip()
+                if not stripped_line:  # Skip empty lines
+                    continue
+
+                if lowercase:
+                    stripped_line = stripped_line.lower()
+
+                lines.append(stripped_line)
+
+            return lines
+    except OSError as e:
+        raise ValueError(f"Cannot read file {path}: {e}") from e

mm_web3/validators.py

@@ -0,0 +1,350 @@
+import os
+from collections.abc import Callable
+from pathlib import Path
+
+from mm_std import parse_lines
+from pydantic import BaseModel
+
+from mm_web3.account import PrivateKeyMap
+from mm_web3.calcs import calc_decimal_expression, calc_expression_with_vars
+from mm_web3.proxy import fetch_proxies_sync
+from mm_web3.utils import read_lines_from_file
+
+type IsAddress = Callable[[str], bool]
+
+
+class Transfer(BaseModel):
+    from_address: str
+    to_address: str
+    value: str  # can be empty string
+
+    @property
+    def log_prefix(self) -> str:
+        return f"{self.from_address}->{self.to_address}"
+
+
+class ConfigValidators:
+    """Pydantic field validators for cryptocurrency CLI application configuration.
+
+    Provides static methods that return validator functions for use with Pydantic models
+    in cryptocurrency CLI applications. Each validator handles complex input formats
+    including direct values, file references, and external data sources.
+
+    These validators are designed for CLI configuration files where users need flexible
+    ways to specify cryptocurrency addresses, private keys, network nodes, proxies,
+    and mathematical expressions for transaction amounts.
+    """
+
+    @staticmethod
+    def transfers(is_address: IsAddress, lowercase: bool = False) -> Callable[[str], list[Transfer]]:
+        """Validate and parse cryptocurrency transfers configuration.
+
+        Parses transfer configurations from string or file references. Each transfer
+        requires source and destination addresses, with optional value specification.
+
+        Args:
+            is_address: Function to validate cryptocurrency addresses
+            lowercase: If True, convert addresses to lowercase
+
+        Returns:
+            Validator function that parses string into list of Transfer objects
+
+        Format:
+            - Direct: "from_addr to_addr [value]"
+            - File reference: "file:/path/to/transfers.txt"
+
+        The value field can be:
+            - Empty string: value taken from default config
+            - Decimal expression: "123.45" or "random(1.0, 5.0)"
+            - Expression with variables: "0.5balance + 1eth"
+
+        Raises:
+            ValueError: If addresses are invalid, format is wrong, or no transfers found
+        """
+
+        def validator(v: str) -> list[Transfer]:
+            result = []
+            for line in parse_lines(v, remove_comments=True):  # don't use lowercase here because it can be a file: /To/Path.txt
+                if line.startswith("file:"):
+                    for file_line in read_lines_from_file(line.removeprefix("file:").strip()):
+                        arr = file_line.split()
+                        if len(arr) < 2 or len(arr) > 3:
+                            raise ValueError(f"illegal file_line: {file_line}")
+                        result.append(Transfer(from_address=arr[0], to_address=arr[1], value=arr[2] if len(arr) > 2 else ""))
+
+                else:
+                    arr = line.split()
+                    if len(arr) < 2 or len(arr) > 3:
+                        raise ValueError(f"illegal line: {line}")
+                    result.append(Transfer(from_address=arr[0], to_address=arr[1], value=arr[2] if len(arr) > 2 else ""))
+
+            if lowercase:
+                result = [
+                    Transfer(from_address=r.from_address.lower(), to_address=r.to_address.lower(), value=r.value) for r in result
+                ]
+
+            for route in result:
+                if not is_address(route.from_address):
+                    raise ValueError(f"illegal address: {route.from_address}")
+                if not is_address(route.to_address):
+                    raise ValueError(f"illegal address: {route.to_address}")
+
+            if not result:
+                raise ValueError("No valid transfers found")
+
+            return result
+
+        return validator
+
+    @staticmethod
+    def proxies() -> Callable[[str], list[str]]:
+        """Validate and parse proxy configuration from multiple sources.
+
+        Supports direct proxy specification, fetching from URLs, environment variables,
+        and local files. Automatically deduplicates results.
+
+        Returns:
+            Validator function that parses string into unique list of proxy addresses
+
+        Format:
+            - Direct: "proxy1:port\nproxy2:port"
+            - URL source: "url:http://example.com/proxies.txt"
+            - Environment URL: "env_url:PROXY_URL_VAR"
+            - File reference: "file:/path/to/proxies.txt"
+
+        Raises:
+            ValueError: If URL fetch fails or environment variable is missing
+        """
+
+        def validator(v: str) -> list[str]:
+            result = []
+            for line in parse_lines(v, deduplicate=True, remove_comments=True):
+                if line.startswith("url:"):
+                    url = line.removeprefix("url:").strip()
+                    res = fetch_proxies_sync(url)
+                    if res.is_err():
+                        raise ValueError(f"Can't get proxies: {res.unwrap_err()}")
+                    result += res.unwrap()
+                elif line.startswith("env_url:"):
+                    env_var = line.removeprefix("env_url:").strip()
+                    url = os.getenv(env_var) or ""
+                    if not url:
+                        raise ValueError(f"missing env var: {env_var}")
+                    res = fetch_proxies_sync(url)
+                    if res.is_err():
+                        raise ValueError(f"Can't get proxies: {res.unwrap_err()}")
+                    result += res.unwrap()
+                elif line.startswith("file:"):
+                    path = line.removeprefix("file:").strip()
+                    result += read_lines_from_file(path)
+                else:
+                    result.append(line)
+
+            return list(dict.fromkeys(result))
+
+        return validator
+
+    @staticmethod
+    def log_file() -> Callable[[Path], Path]:
+        """Validate and prepare log file path with automatic directory creation.
+
+        Creates parent directories and ensures file is writable. Expands user home directory (~).
+
+        Returns:
+            Validator function that validates Path and ensures write access
+
+        Raises:
+            ValueError: If path is not writable or cannot be created
+        """
+
+        def validator(v: Path) -> Path:
+            log_file = Path(v).expanduser()
+            log_file.parent.mkdir(parents=True, exist_ok=True)
+            log_file.touch(exist_ok=True)
+            if not log_file.is_file() or not os.access(log_file, os.W_OK):
+                raise ValueError(f"wrong log path: {v}")
+            return log_file
+
+        return validator
+
+    @staticmethod
+    def nodes(allow_empty: bool = False) -> Callable[[str], list[str]]:
+        """Validate blockchain node URLs configuration.
+
+        Parses and deduplicates node URLs from string input.
+
+        Args:
+            allow_empty: If True, allows empty node list
+
+        Returns:
+            Validator function that parses string into list of node URLs
+
+        Raises:
+            ValueError: If node list is empty when allow_empty=False
+        """
+
+        def validator(v: str) -> list[str]:
+            nodes = parse_lines(v, deduplicate=True, remove_comments=True)
+            if not allow_empty and not nodes:
+                raise ValueError("Node list cannot be empty")
+            return nodes
+
+        return validator
+
+    @staticmethod
+    def address(is_address: IsAddress, lowercase: bool = False) -> Callable[[str], str]:
+        """Validate single cryptocurrency address.
+
+        Args:
+            is_address: Function to validate cryptocurrency addresses
+            lowercase: If True, converts address to lowercase
+
+        Returns:
+            Validator function that validates and optionally lowercases address
+
+        Raises:
+            ValueError: If address is invalid
+        """
+
+        def validator(v: str) -> str:
+            if not is_address(v):
+                raise ValueError(f"illegal address: {v}")
+            if lowercase:
+                return v.lower()
+            return v
+
+        return validator
+
+    @staticmethod
+    def addresses(deduplicate: bool, lowercase: bool = False, is_address: IsAddress | None = None) -> Callable[[str], list[str]]:
+        """Validate list of cryptocurrency addresses from string or file references.
+
+        Supports direct address specification and file references. Optionally validates
+        each address and applies transformations.
+
+        Args:
+            deduplicate: If True, deduplicates addresses
+            lowercase: If True, converts addresses to lowercase
+            is_address: Optional function to validate each address
+
+        Returns:
+            Validator function that parses string into list of addresses
+
+        Format:
+            - Direct: "addr1\naddr2\naddr3"
+            - File reference: "file:/path/to/addresses.txt"
+
+        Raises:
+            ValueError: If any address is invalid (when is_address provided)
+        """
+
+        def validator(v: str) -> list[str]:
+            result = []
+            for line in parse_lines(v, deduplicate=deduplicate, remove_comments=True):
+                if line.startswith("file:"):  # don't use lowercase here because it can be a file: /To/Path.txt
+                    path = line.removeprefix("file:").strip()
+                    result += read_lines_from_file(path)
+                else:
+                    result.append(line)
+
+            if deduplicate:
+                result = list(dict.fromkeys(result))
+
+            if lowercase:
+                result = [r.lower() for r in result]
+
+            if is_address:
+                for address in result:
+                    if not is_address(address):
+                        raise ValueError(f"illegal address: {address}")
+            return result
+
+        return validator
+
+    @staticmethod
+    def private_keys(address_from_private: Callable[[str], str]) -> Callable[[str], PrivateKeyMap]:
+        """Validate and parse private keys configuration.
+
+        Parses private keys from string or file references and converts them to
+        address-to-private-key mapping using provided conversion function.
+
+        Args:
+            address_from_private: Function to derive address from private key
+
+        Returns:
+            Validator function that parses string into PrivateKeyMap
+
+        Format:
+            - Direct: "key1\nkey2\nkey3"
+            - File reference: "file:/path/to/keys.txt"
+
+        Raises:
+            ValueError: If any private key is invalid or duplicate
+        """
+
+        def validator(v: str) -> PrivateKeyMap:
+            private_keys = []
+            for line in parse_lines(v, deduplicate=True, remove_comments=True):
+                if line.startswith("file:"):
+                    path = line.removeprefix("file:").strip()
+                    private_keys += read_lines_from_file(path)
+                else:
+                    private_keys.append(line)
+
+            return PrivateKeyMap.from_list(private_keys, address_from_private)
+
+        return validator
+
+    @staticmethod
+    def expression_with_vars(var_name: str | None = None, unit_decimals: dict[str, int] | None = None) -> Callable[[str], str]:
+        """Validate mathematical expressions with variables and units.
+
+        Validates expressions using calc_expression_with_vars function. Supports variables,
+        unit suffixes, and arithmetic operations for dynamic value calculations.
+
+        Args:
+            var_name: Variable name to include in validation context
+            unit_decimals: Mapping of unit suffixes to decimal places
+
+        Returns:
+            Validator function that validates expression syntax
+
+        Examples:
+            - "0.5balance + 1eth"
+            - "random(1gwei, 10gwei) - 100"
+
+        Raises:
+            ValueError: If expression syntax is invalid
+        """
+
+        def validator(v: str) -> str:
+            # Use arbitrary test value to validate expression syntax without actual calculation
+            variables = {var_name: 123} if var_name else {}
+            calc_expression_with_vars(v, variables, unit_decimals=unit_decimals)
+            return v
+
+        return validator
+
+    @staticmethod
+    def decimal_expression() -> Callable[[str], str]:
+        """Validate decimal expressions and random functions.
+
+        Validates expressions using calc_decimal_expression function. Supports simple
+        decimal values and random function calls.
+
+        Returns:
+            Validator function that validates decimal expression syntax
+
+        Examples:
+            - "123.45"
+            - "random(1.0, 5.0)"
+
+        Raises:
+            ValueError: If expression syntax is invalid
+        """
+
+        def validator(v: str) -> str:
+            calc_decimal_expression(v)
+            return v
+
+        return validator

mm_web3-0.5.0.dist-info/METADATA

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: mm-web3
+Version: 0.5.0
+Requires-Python: >=3.13
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: mm-http~=0.1.0
+Requires-Dist: mm-print~=0.1.1
+Requires-Dist: mm-std~=0.5.3

mm_web3-0.5.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+mm_web3/__init__.py,sha256=uGPiC3UGbashWlRiIr27CjqGp1xUTHA6goDBO5cGBBU,1296
+mm_web3/account.py,sha256=CNV2I6BRxMNwh2lldOKo9Gpv30zXaL2UzurztUDR_bY,3623
+mm_web3/calcs.py,sha256=b5mWCDE8UdQjxkdVbWPMRNaMbG6XteSlqG0M2CYDQe4,7860
+mm_web3/config.py,sha256=A_xHvWQgJlAZPI7iJ0q-53gFA1WWOIKQl3uMTlQm6qM,5733
+mm_web3/log.py,sha256=rvrObh-Jo9nO0OEIsLD5-f98mxeuA1GQlkYUY7xLb0Q,653
+mm_web3/network.py,sha256=99Qv59rGAvf5akp8Sbow_PXkKQk6B3Yh8oy2kH6JhFw,6902
+mm_web3/node.py,sha256=vXO9PsKZ_yfKsLKc5R_HL62CAKTDJbOg4BHijqw4IbM,902
+mm_web3/proxy.py,sha256=dfFeb4cUWfPwxmK7EUZ5WBu_XPkytzDMIYvXYrz8gUk,3523
+mm_web3/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mm_web3/retry.py,sha256=GPwESXK-C9EI4r5TcWK46sP2fQa68gnp34D8Lhwc6Cc,2384
+mm_web3/utils.py,sha256=k-x8R8bLRZKBN3xqeepukD9Tzwt97qiTUETSrK7lIHM,2009
+mm_web3/validators.py,sha256=nt1AXiLfz1ek5PWsqVMtgvENSsCky0-B0NtrXuf0afI,12894
+mm_web3-0.5.0.dist-info/METADATA,sha256=TSwqQfLPOS4KgHyPehqVGwei0j7mPY1puF33WKTy1EI,194
+mm_web3-0.5.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+mm_web3-0.5.0.dist-info/RECORD,,

mm_web3-0.5.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any