micro-web3 0.1.0__py3-none-any.whl

micro_web3/addresses.py

@@ -0,0 +1,62 @@
+"""Address helpers.
+
+Decoding follows eth_abi and returns lower-case ``0x`` hex; checksumming is
+opt-in through :func:`to_checksum_address` (EIP-55).
+"""
+
+from functools import lru_cache
+
+from ._keccak import keccak256
+
+
+def to_bytes20(value: str | bytes | bytearray) -> bytes:
+    """Validate and return the 20 raw bytes of an address."""
+    if isinstance(value, bytearray):
+        value = bytes(value)
+    if isinstance(value, bytes):
+        if len(value) != 20:
+            raise ValueError(f"address must be 20 bytes, got {len(value)}")
+        return value
+    if not isinstance(value, str):
+        raise TypeError(f"address must be str or bytes, got {type(value).__name__}")
+    digits = value[2:] if value[:2].lower() == "0x" else value
+    if len(digits) != 40:
+        raise ValueError(f"address must be 20 bytes, got {len(digits) // 2} bytes")
+    try:
+        return bytes.fromhex(digits)
+    except ValueError as exc:
+        raise ValueError(f"invalid address: {value!r}") from exc
+
+
+def to_checksum_address(value: str | bytes | bytearray) -> str:
+    """Return the EIP-55 mixed-case form of ``value``."""
+    if type(value) is str:
+        return _checksum_str(value)
+    return _checksum(to_bytes20(value))
+
+
+@lru_cache(maxsize=4096)
+def _checksum_str(value: str) -> str:
+    return _checksum(to_bytes20(value))
+
+
+def _checksum(raw: bytes) -> str:
+    lower = raw.hex()
+    digest = keccak256(lower.encode("ascii")).hex()
+    return "0x" + "".join(
+        [
+            char.upper() if nibble >= "8" else char
+            for char, nibble in zip(lower, digest, strict=False)
+        ]
+    )
+
+
+def is_address(value: object) -> bool:
+    """True if ``value`` is a well-formed 20-byte address."""
+    if not isinstance(value, (str, bytes, bytearray)):
+        return False
+    try:
+        to_bytes20(value)
+    except ValueError:
+        return False
+    return True

micro_web3/contract.py

@@ -0,0 +1,135 @@
+"""A tiny contract helper on top of the ABI codec."""
+
+from collections.abc import Mapping, Sequence
+from functools import cached_property
+from typing import Any
+
+from .abi import (
+    AbiType,
+    canonical,
+    decode_outputs,
+    encode,
+    inputs_types,
+    outputs_types,
+    selector,
+)
+from .addresses import to_checksum_address
+from .errors import AbiError
+from .methods import eth_call
+from .rpc import RpcNode
+
+__all__ = ["Contract"]
+
+
+def _unwrap(decoded: tuple[Any, ...]) -> Any:
+    return decoded[0] if len(decoded) == 1 else decoded
+
+
+class _Function:
+    """One ABI entry with its types and selector, derived on first use."""
+
+    def __init__(self, entry: Mapping[str, Any]) -> None:
+        self.entry = entry
+
+    @cached_property
+    def inputs(self) -> tuple[AbiType, ...]:
+        return inputs_types(self.entry)
+
+    @cached_property
+    def outputs(self) -> tuple[AbiType, ...]:
+        return outputs_types(self.entry)
+
+    @cached_property
+    def selector(self) -> bytes:
+        return selector(self.entry)
+
+
+class Contract:
+    """An ABI plus (optionally) an address.
+
+    ``Contract.encode`` returns ``0x`` hex like web3's ``encode_abi``, so the
+    Etherscan fallback path keeps working unchanged.
+    """
+
+    __slots__ = ("_abi", "_functions", "address")
+
+    def __init__(
+        self,
+        address: str | bytes | None,
+        abi: Sequence[Mapping[str, Any]],
+    ) -> None:
+        self.address = None if address is None else to_checksum_address(address)
+        self.abi = abi
+
+    @property
+    def abi(self) -> tuple[Mapping[str, Any], ...]:
+        return self._abi
+
+    @abi.setter
+    def abi(self, abi: Sequence[Mapping[str, Any]]) -> None:
+        self._abi = tuple(abi)
+        self._functions: dict[str, tuple[_Function, ...]] = {}
+
+    def function(self, name: str, args: Sequence[Any] = ()) -> Mapping[str, Any]:
+        """Return the matching ABI entry.
+
+        Raises :class:`AttributeError` if no function has that name and
+        :class:`~micro_web3.errors.AbiError` if the arguments do not fit any
+        overload.
+        """
+        return self._resolve(name, args)[0].entry
+
+    def encode(self, name: str, args: Sequence[Any] = ()) -> str:
+        """Encode a call, ``0x`` hex including the 4-byte selector."""
+        function, body = self._resolve(name, args)
+        return "0x" + (function.selector + body).hex()
+
+    def output_types(self, name: str, args: Sequence[Any] = ()) -> tuple[str, ...]:
+        return tuple(canonical(item) for item in self._outputs(name, args))
+
+    def decode(self, name: str, args: Sequence[Any], data: str | bytes) -> Any:
+        """Decode a return payload, unwrapping single-output results."""
+        return _unwrap(decode_outputs(self._outputs(name, args), data))
+
+    def call(
+        self,
+        node: RpcNode,
+        name: str,
+        args: Sequence[Any] = (),
+        block: int | str = "latest",
+    ) -> Any:
+        """``eth_call`` the function and decode the result."""
+        if self.address is None:
+            raise ValueError("contract has no address; cannot perform a call")
+        function, body = self._resolve(name, args)
+        raw = eth_call(node, self.address, "0x" + (function.selector + body).hex(), block)
+        return _unwrap(decode_outputs(function.outputs, raw))
+
+    def _outputs(self, name: str, args: Sequence[Any]) -> tuple[AbiType, ...]:
+        return self._resolve(name, args)[0].outputs
+
+    def _resolve(self, name: str, args: Sequence[Any]) -> tuple[_Function, bytes]:
+        """First overload accepting ``args``, with the encoded arguments."""
+        functions = self._functions.get(name)
+        if functions is None:
+            functions = tuple(
+                _Function(entry)
+                for entry in self.abi
+                if entry.get("type", "function") == "function" and entry.get("name") == name
+            )
+            if not functions:
+                raise AttributeError(f"ABI has no function named {name!r}")
+            self._functions[name] = functions
+        failures: list[str] = []
+        for function in functions:
+            try:
+                return function, encode(function.inputs, args)
+            except AbiError as exc:
+                failures.append(str(exc))
+        raise AbiError(
+            f"no overload of {name!r} accepts {len(args)} argument(s): " + "; ".join(failures),
+        )
+
+    def __repr__(self) -> str:
+        functions = sum(1 for entry in self.abi if entry.get("type", "function") == "function")
+        return f"Contract(address={self.address!r}, functions={functions})"

micro_web3/errors.py

@@ -0,0 +1,48 @@
+"""Exception hierarchy.
+
+Everything raised by :mod:`micro_web3` derives from :class:`RpcError` so call
+sites can keep a single ``except RpcError`` (the replacement for
+``web3.exceptions.Web3Exception``).
+"""
+
+from typing import Any
+
+
+class RpcError(Exception):
+    """Base class for every error raised by micro_web3."""
+
+
+class RpcConnectionError(RpcError):
+    """The node could not be reached, timed out, or spoke non JSON-RPC."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        endpoint_uri: str | None = None,
+        status: int | None = None,
+    ) -> None:
+        self.endpoint_uri = endpoint_uri
+        self.status = status
+        super().__init__(message)
+
+
+class RpcResponseError(RpcError):
+    """The node answered with a JSON-RPC ``error`` object.
+
+    Reverts arrive here: the message contains ``execution reverted`` and the
+    revert payload (when the node provides it) is in :attr:`data`.
+    """
+
+    def __init__(self, code: int, message: str, data: Any = None) -> None:
+        self.code = code
+        self.message = message
+        self.data = data
+        text = f"{message} (code {code})"
+        if data not in (None, "", "0x"):
+            text = f"{text}: {data!r}"
+        super().__init__(text)
+
+
+class AbiError(RpcError):
+    """An ABI definition, value, or encoded payload was invalid."""

micro_web3/methods.py

@@ -0,0 +1,114 @@
+"""High-level RPC helpers: ``eth_call``, ``eth_getLogs``, block number."""
+
+from collections.abc import Sequence
+from typing import Any
+
+from .addresses import to_checksum_address
+from .errors import RpcError
+from .rpc import RpcNode
+
+_BLOCK_TAGS = frozenset({"latest", "earliest", "pending", "safe", "finalized"})
+
+
+def to_quantity(value: int | str) -> str:
+    """Normalise a block number or tag to a JSON-RPC quantity.
+
+    Accepts ``int``, decimal strings, hex strings and block tags. Decimal input
+    is accepted on purpose: it lets call sites keep Etherscan-shaped arguments
+    and still emit valid ``eth_getLogs`` params.
+    """
+    if isinstance(value, bool):
+        raise ValueError("block number must not be a bool")
+    if isinstance(value, int):
+        if value < 0:
+            raise ValueError(f"negative block number: {value}")
+        return hex(value)
+    if not isinstance(value, str):
+        raise ValueError(f"invalid block identifier: {value!r}")
+    stripped = value.strip()
+    if stripped in _BLOCK_TAGS:
+        return stripped
+    if stripped[:2].lower() == "0x":
+        try:
+            return hex(int(stripped, 16))
+        except ValueError as exc:
+            raise ValueError(f"invalid hex block number: {value!r}") from exc
+    if stripped.isdigit():
+        return hex(int(stripped))
+    raise ValueError(f"invalid block identifier: {value!r}")
+
+
+def eth_call(
+    node: RpcNode,
+    to: str | bytes,
+    data: str | bytes,
+    block: int | str = "latest",
+) -> str:
+    """Perform one ``eth_call`` and return the raw ``0x`` result."""
+    result = node.request(
+        "eth_call",
+        [
+            {"to": to_checksum_address(to), "data": _hex_data(data)},
+            to_quantity(block),
+        ],
+    )
+    if not isinstance(result, str):
+        raise RpcError(f"eth_call returned {type(result).__name__}, expected hex string")
+    return result
+
+
+def get_logs(
+    node: RpcNode,
+    address: str | bytes | Sequence[str | bytes] | None = None,
+    topics: Sequence[str | Sequence[str] | None] | None = None,
+    from_block: int | str | None = None,
+    to_block: int | str | None = None,
+) -> list[dict[str, Any]]:
+    """Perform ``eth_getLogs`` and return the node's raw JSON-RPC objects.
+
+    No normalisation: ``blockNumber``, ``topics`` and ``data`` stay hex strings,
+    identical to the Etherscan/Blockscout shapes.
+    """
+    params: dict[str, Any] = {}
+    if address is not None:
+        if isinstance(address, (str, bytes)):
+            params["address"] = to_checksum_address(address)
+        else:
+            params["address"] = [to_checksum_address(item) for item in address]
+    if topics is not None:
+        params["topics"] = list(topics)
+    if from_block is not None:
+        params["fromBlock"] = to_quantity(from_block)
+    if to_block is not None:
+        params["toBlock"] = to_quantity(to_block)
+
+    result = node.request("eth_getLogs", [params])
+    if not isinstance(result, list):
+        raise RpcError(f"eth_getLogs returned {type(result).__name__}, expected list")
+    return result
+
+
+def get_block_number(node: RpcNode) -> int:
+    """Return the head block number."""
+    block = node.request("eth_getBlockByNumber", ["latest", False])
+    if not isinstance(block, dict):
+        raise RpcError("eth_getBlockByNumber returned a non-object result")
+    number = block.get("number")
+    if isinstance(number, int):
+        return number
+    if isinstance(number, str):
+        try:
+            return int(number, 16)
+        except ValueError as exc:
+            raise RpcError(f"invalid block number from node: {number!r}") from exc
+    raise RpcError(f"eth_getBlockByNumber result without number: {block!r}")
+
+
+def _hex_data(value: str | bytes) -> str:
+    if isinstance(value, (bytes, bytearray)):
+        return "0x" + value.hex()
+    if isinstance(value, str):
+        if value[:2].lower() != "0x":
+            return "0x" + value
+        return value
+    raise ValueError(f"invalid calldata type: {type(value).__name__}")

micro_web3/multicall.py

@@ -0,0 +1,63 @@
+"""Multicall3 batching (``tryAggregate``)."""
+
+from collections.abc import Sequence
+from functools import lru_cache
+from typing import Any
+
+from .contract import Contract
+from .rpc import RpcNode
+
+__all__ = ["MULTICALL3_ADDRESS", "try_aggregate"]
+
+MULTICALL3_ADDRESS = "0xcA11bde05977b3631167028862bE2a173976CA11"
+
+_MULTICALL3_ABI: tuple[dict[str, Any], ...] = (
+    {
+        "type": "function",
+        "name": "tryAggregate",
+        "stateMutability": "view",
+        "inputs": [
+            {"name": "requireSuccess", "type": "bool"},
+            {
+                "name": "calls",
+                "type": "tuple[]",
+                "components": [
+                    {"name": "target", "type": "address"},
+                    {"name": "callData", "type": "bytes"},
+                ],
+            },
+        ],
+        "outputs": [
+            {
+                "name": "returnData",
+                "type": "tuple[]",
+                "components": [
+                    {"name": "success", "type": "bool"},
+                    {"name": "returnData", "type": "bytes"},
+                ],
+            },
+        ],
+    },
+)
+
+
+@lru_cache(maxsize=16)
+def _multicall(address: str) -> Contract:
+    return Contract(address, _MULTICALL3_ABI)
+
+
+def try_aggregate(
+    node: RpcNode,
+    calls: Sequence[tuple[str | bytes, str | bytes]],
+    block: int | str = "latest",
+    address: str = MULTICALL3_ADDRESS,
+) -> list[bytes | None]:
+    """Run ``calls`` through Multicall3 ``tryAggregate(false, calls)``.
+
+    Each call is ``(target, calldata)``. Returns one entry per call: the raw
+    return data as ``bytes``, or ``None`` when that individual call reverted.
+    """
+    contract = _multicall(address)
+    encoded = [(target, call_data) for target, call_data in calls]
+    results = contract.call(node, "tryAggregate", [False, encoded], block)
+    return [return_data if success else None for success, return_data in results]

micro_web3/rpc.py

@@ -0,0 +1,143 @@
+"""JSON-RPC over urllib3.
+
+Each node keeps its own connection pool. One HTTP POST per call and no retries:
+fallback across nodes is the caller's job (see rotkehlchen's ``EthereumManager``).
+"""
+
+import itertools
+import json
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from urllib3 import PoolManager
+from urllib3.exceptions import HTTPError
+
+from .errors import RpcConnectionError, RpcError, RpcResponseError
+
+__all__ = ["RpcNode"]
+
+_DEFAULT_USER_AGENT = "micro-web3"
+
+
+class RpcNode:
+    """A single JSON-RPC endpoint."""
+
+    __slots__ = ("_headers", "_ids", "_pool", "endpoint_uri", "timeout")
+
+    def __init__(
+        self,
+        endpoint_uri: str,
+        *,
+        timeout: float = 4.0,
+        headers: Mapping[str, str] | None = None,
+        pool_maxsize: int = 10,
+    ) -> None:
+        self._pool = PoolManager(num_pools=1, maxsize=pool_maxsize)
+        self.endpoint_uri = endpoint_uri
+        self.timeout = timeout
+        self._headers = {
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "User-Agent": _DEFAULT_USER_AGENT,
+        }
+        if headers:
+            self._headers.update(headers)
+        self._ids = itertools.count(1)
+
+    def request(self, method: str, params: Sequence[Any] | Mapping[str, Any] | None = None) -> Any:
+        """Perform one JSON-RPC call and return its ``result``.
+
+        Raises :class:`RpcConnectionError` if the endpoint cannot be reached and
+        :class:`RpcResponseError` if it answers with a JSON-RPC error object.
+        """
+        if params is None:
+            params_list: list[Any] = []
+        elif isinstance(params, Mapping):
+            params_list = [params]
+        else:
+            params_list = list(params)
+
+        request_id = next(self._ids)
+        try:
+            payload = json.dumps(
+                {"jsonrpc": "2.0", "id": request_id, "method": method, "params": params_list},
+                separators=(",", ":"),
+            ).encode()
+        except (TypeError, ValueError) as exc:
+            raise RpcError(f"cannot serialise JSON-RPC params for {method}: {exc}") from exc
+
+        try:
+            response = self._pool.request(
+                "POST",
+                self.endpoint_uri,
+                body=payload,
+                headers=self._headers,
+                timeout=self.timeout,
+                retries=False,
+            )
+            body = response.data
+        except (HTTPError, OSError) as exc:
+            raise RpcConnectionError(
+                f"cannot reach {self.endpoint_uri}: {exc}",
+                endpoint_uri=self.endpoint_uri,
+            ) from exc
+
+        parsed = _parse_json(body)
+        if not 200 <= response.status < 300:
+            if isinstance(parsed, dict) and isinstance(parsed.get("error"), dict):
+                raise _response_error(parsed["error"])
+            raise RpcConnectionError(
+                f"HTTP {response.status} from {self.endpoint_uri}: {_snippet(body)}",
+                endpoint_uri=self.endpoint_uri,
+                status=response.status,
+            )
+
+        if not isinstance(parsed, dict):
+            raise RpcError(
+                f"invalid JSON-RPC response from {self.endpoint_uri}: {_snippet(body)}",
+            )
+
+        error = parsed.get("error")
+        if error is not None:
+            if not isinstance(error, dict):
+                raise RpcError(f"malformed JSON-RPC error from {self.endpoint_uri}: {error!r}")
+            raise _response_error(error)
+        if "result" not in parsed:
+            raise RpcError(f"JSON-RPC response without result from {self.endpoint_uri}")
+        return parsed["result"]
+
+    def is_connected(self) -> bool:
+        """Probe the node with ``web3_clientVersion``; never raises."""
+        try:
+            version = self.request("web3_clientVersion")
+        except (RpcError, OSError, ValueError):
+            return False
+        return isinstance(version, str) and version != ""
+
+    def close(self) -> None:
+        """Close the pooled connections. The node reconnects if used again."""
+        self._pool.clear()
+
+    def __repr__(self) -> str:
+        return f"RpcNode({self.endpoint_uri!r}, timeout={self.timeout!r})"
+
+
+def _response_error(error: Mapping[str, Any]) -> RpcResponseError:
+    code = error.get("code")
+    message = error.get("message", "")
+    return RpcResponseError(
+        code if isinstance(code, int) else -1,
+        message if isinstance(message, str) else str(message),
+        error.get("data"),
+    )
+
+
+def _parse_json(body: bytes) -> Any:
+    try:
+        return json.loads(body)
+    except ValueError:
+        return None
+
+
+def _snippet(body: bytes, limit: int = 300) -> str:
+    return body[:limit].decode("utf-8", "replace")