mm-web3 0.5.0__tar.gz

mm_web3-0.5.0/.gitignore

@@ -0,0 +1,16 @@
+.idea
+.vscode
+.venv
+.env
+.coverage
+/htmlcov
+__pycache__
+*.egg-info
+pip-wheel-metadata
+.pytest_cache
+.mypy_cache
+.ruff_cache
+/dist
+/build
+/tmp
+.DS_Store

mm_web3-0.5.0/.pre-commit-config.yaml

@@ -0,0 +1,10 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-json
+      - id: check-added-large-files

mm_web3-0.5.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,234 @@
+# mm-web3
+
+A Python library providing utilities for working with multiple blockchain networks, proxy management, and reliable network operations for cryptocurrency applications.
+
+## Features
+
+### 🔗 Multi-Blockchain Support
+- **19 blockchain networks** including Ethereum, Arbitrum, Polygon, Solana, Aptos, StarkNet and more
+- **4 network types**: EVM, Solana, Aptos, StarkNet
+- Network-specific explorer URL generation for tokens and accounts
+- Address formatting utilities (lowercase for certain networks)
+
+### 🌐 Proxy Management
+- Fetch proxy lists from remote URLs
+- Validate proxy URLs (HTTP, HTTPS, SOCKS4, SOCKS5)
+- Random proxy selection from pools
+- Support for authenticated proxies
+
+### 🔄 Retry Logic
+- Automatic retry with random node/proxy combinations
+- Configurable retry attempts
+- Detailed logging of retry attempts
+- Support for both node+proxy and proxy-only scenarios
+
+### ⚙️ Configuration System
+- TOML-based configuration with validation
+- ZIP archive support with optional encryption
+- Async and sync configuration loading
+- Pydantic-based validation with detailed error reporting
+
+### 🎯 Node Management
+- Random blockchain node selection
+- Support for single nodes or node pools
+- URL normalization (trailing slash removal)
+
+
+## Quick Start
+
+### Basic Usage
+
+```python
+import asyncio
+from mm_web3 import Network, fetch_proxies, random_node, random_proxy
+
+async def main():
+    # Get explorer URL for a token
+    network = Network.ETHEREUM
+    token_url = network.explorer_token("0xa0b86991c31cc0e37faeded5b4648648e8dd4a0425")
+    print(f"USDC on Ethereum: {token_url}")
+
+    # Fetch proxies from a URL
+    proxies_result = await fetch_proxies("https://example.com/proxy-list.txt")
+    if proxies_result.is_ok():
+        proxies = proxies_result.unwrap()
+        proxy = random_proxy(proxies)
+        print(f"Using proxy: {proxy}")
+
+    # Select random node from a pool
+    nodes = [
+        "https://eth-mainnet.g.alchemy.com/v2/your-key",
+        "https://mainnet.infura.io/v3/your-key",
+        "https://rpc.ankr.com/eth"
+    ]
+    node = random_node(nodes)
+    print(f"Using node: {node}")
+
+asyncio.run(main())
+```
+
+### Configuration with TOML
+
+```python
+from pathlib import Path
+from pydantic import BaseModel
+from mm_web3.config import Web3CliConfig
+
+class MyConfig(Web3CliConfig):
+    api_key: str
+    networks: list[str]
+    retry_count: int = 3
+
+# config.toml
+"""
+api_key = "your-api-key"
+networks = ["ethereum", "polygon", "arbitrum-one"]
+retry_count = 5
+"""
+
+config = MyConfig.read_toml_config_or_exit(Path("config.toml"))
+print(f"Loaded config: {config.api_key}")
+```
+
+### Retry Logic with Nodes and Proxies
+
+```python
+import asyncio
+from mm_web3.retry import retry_with_node_and_proxy
+from mm_result import Result
+
+async def make_request(node: str, proxy: str | None) -> Result[dict]:
+    # Your HTTP request logic here
+    # Return Result.ok(data) on success or Result.err(error) on failure
+    pass
+
+async def main():
+    nodes = ["https://rpc1.example.com", "https://rpc2.example.com"]
+    proxies = ["http://proxy1:8080", "http://proxy2:8080"]
+
+    result = await retry_with_node_and_proxy(
+        retries=3,
+        nodes=nodes,
+        proxies=proxies,
+        func=make_request
+    )
+
+    if result.is_ok():
+        data = result.unwrap()
+        print(f"Success: {data}")
+    else:
+        print(f"Failed after retries: {result.error}")
+
+asyncio.run(main())
+```
+
+## Supported Networks
+
+### EVM Networks
+- Ethereum, Arbitrum One, Avalanche C-Chain
+- Base, BSC, Celo, Core
+- Fantom, Linea, OpBNB, OP Mainnet
+- Polygon, Polygon zkEVM, Scroll
+- zkSync Era, Zora
+
+### Other Networks
+- **Solana**: Solana mainnet
+- **Aptos**: Aptos mainnet
+- **StarkNet**: StarkNet mainnet
+
+Each network provides:
+- Explorer URL generation for tokens and accounts
+- Network type classification
+- Address formatting preferences
+
+## Configuration
+
+The library supports TOML configuration files with:
+- **Validation**: Pydantic-based schema validation
+- **ZIP Support**: Load configs from encrypted ZIP archives
+- **Async Loading**: For configs with async validators
+- **Error Handling**: Detailed validation error messages
+
+### Configuration Example
+
+```toml
+# config.toml
+[network]
+default = "ethereum"
+nodes = [
+    "https://eth-mainnet.g.alchemy.com/v2/key1",
+    "https://mainnet.infura.io/v3/key2"
+]
+
+[proxy]
+enabled = true
+sources = ["https://proxy-list.example.com/free.txt"]
+timeout = 5.0
+
+[retry]
+max_attempts = 3
+backoff_seconds = 1.0
+```
+
+## Development
+
+### Setup
+
+```bash
+# Clone and setup
+git clone <repository-url>
+cd mm-cryptocurrency
+uv sync
+
+# Run tests
+just test
+
+# Format code
+just format
+
+# Run linting
+just lint
+
+# Run security audit
+just audit
+```
+
+### Requirements
+
+- **Python 3.13+**
+- **uv** for package management
+- Dependencies: `mm-http`, `mm-print`, `mm-result`
+
+### Testing
+
+The library includes comprehensive tests covering:
+- Network definitions and utilities
+- Proxy fetching and validation
+- Configuration loading and validation
+- Retry logic and error handling
+- Utility functions
+
+Run tests with: `just test` or `uv run pytest`
+
+## API Reference
+
+### Core Classes
+
+- **`Network`**: Enum of supported blockchain networks
+- **`NetworkType`**: Base network types (EVM, Solana, etc.)
+- **`Web3CliConfig`**: Base class for TOML configuration
+
+### Functions
+
+- **`fetch_proxies(url)`**: Fetch proxy list from URL
+- **`fetch_proxies_sync(url)`**: Synchronous proxy fetching
+- **`random_proxy(proxies)`**: Select random proxy from pool
+- **`random_node(nodes)`**: Select random node from pool
+- **`is_valid_proxy_url(url)`**: Validate proxy URL format
+- **`retry_with_node_and_proxy()`**: Retry with node/proxy rotation
+- **`retry_with_proxy()`**: Retry with proxy-only rotation
+
+### Type Aliases
+
+- **`Proxies`**: `str | Sequence[str] | None` - Proxy configuration
+- **`Nodes`**: `str | Sequence[str]` - Node configuration

mm_web3-0.5.0/justfile

@@ -0,0 +1,40 @@
+version := `uv run python -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])'`
+
+
+clean:
+    rm -rf .pytest_cache .mypy_cache .ruff_cache .coverage dist build src/*.egg-info
+
+build: clean
+    uv build
+
+format:
+    uv run ruff check --select I --fix src tests
+    uv run ruff format src tests
+
+test:
+    uv run pytest -n auto tests
+
+lint: format pre-commit
+    uv run ruff check src tests
+    uv run mypy src
+
+audit:
+    uv export --no-dev --all-extras --format requirements-txt --no-emit-project > requirements.txt
+    uv run pip-audit -r requirements.txt --disable-pip
+    rm requirements.txt
+    uv run bandit -q -r -c "pyproject.toml" src
+
+publish: build lint audit test
+    git diff-index --quiet HEAD
+    printf "Enter PyPI token: " && IFS= read -rs TOKEN && echo && uv publish --token "$TOKEN"
+    git tag -a 'v{{version}}' -m 'v{{version}}'
+    git push origin v{{version}}
+
+sync:
+    uv sync --all-extras
+
+pre-commit:
+    uv run pre-commit run --all-files
+
+pre-commit-autoupdate:
+    uv run pre-commit autoupdate

mm_web3-0.5.0/pyproject.toml

@@ -0,0 +1,83 @@
+[project]
+name = "mm-web3"
+version = "0.5.0"
+description = ""
+requires-python = ">=3.13"
+dependencies = [
+    "mm-std~=0.5.3",
+    "mm-http~=0.1.0",
+    "mm-print~=0.1.1",
+    "loguru>=0.7.3",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.uv]
+dev-dependencies = [
+    "pytest~=8.4.0",
+    "pytest-asyncio~=1.0.0",
+    "pytest-xdist~=3.7.0",
+    "pytest-httpserver~=1.1.3",
+    "ruff~=0.11.13",
+    "mypy~=1.16.0",
+    "pip-audit~=2.9.0",
+    "bandit~=1.8.3",
+    "pre-commit~=4.2.0",
+    "python-dotenv~=1.1.0",
+    "eth-account>=0.13.7",
+]
+
+[tool.mypy]
+python_version = "3.13"
+warn_no_return = false
+strict = true
+exclude = ["^tests/", "^tmp/"]
+
+[tool.ruff]
+line-length = 130
+target-version = "py313"
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "TC",       # flake8-type-checking, TYPE_CHECKING is dangerous, for example it doesn't work with pydantic
+    "A005",     # flake8-builtins: stdlib-module-shadowing
+    "ERA001",   # eradicate: commented-out-code
+    "PT",       # flake8-pytest-style
+    "D",        # pydocstyle
+    "FIX",      # flake8-fixme
+    "PLR0911",  # pylint: too-many-return-statements
+    "PLR0912",  # pylint: too-many-branches
+    "PLR0913",  # pylint: too-many-arguments
+    "PLR2004",  # pylint: magic-value-comparison
+    "PLC0414",  # pylint: useless-import-alias
+    "FBT",      # flake8-boolean-trap
+    "EM",       # flake8-errmsg
+    "TRY003",   # tryceratops: raise-vanilla-args
+    "C901",     # mccabe: complex-structure,
+    "BLE001",   # flake8-blind-except
+    "S311",     # bandit: suspicious-non-cryptographic-random-usage
+    "TD002",    # flake8-todos: missing-todo-author
+    "TD003",    # flake8-todos: missing-todo-link
+    "RET503",   # flake8-return: implicit-return
+    "COM812",   # it's used in ruff formatter
+    "ASYNC109",
+    "G004",
+]
+[tool.ruff.lint.pep8-naming]
+classmethod-decorators = ["field_validator"]
+[tool.ruff.lint.per-file-ignores]
+"tests/*.py" = ["ANN", "S"]
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+[tool.bandit]
+exclude_dirs = ["tests"]
+skips = ["B311"]
+
+[tool.pytest.ini_options]
+markers = ["proxy: requires access proxies"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"

mm_web3-0.5.0/src/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-0.5.0/src/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)