micro-web3 0.1.0__tar.gz

micro_web3-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yabir Benchakhtir
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

micro_web3-0.1.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: micro-web3
+Version: 0.1.0
+Summary: Minimal Ethereum JSON-RPC and ABI client
+Keywords: ethereum,web3,json-rpc,abi,keccak,multicall
+Author: Yabir Benchakhtir
+Author-email: Yabir Benchakhtir <git@yabirgb.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Dist: pycryptodome>=3.20,<4
+Requires-Dist: urllib3>=2,<3
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# micro-web3
+
+A small Ethereum client: JSON-RPC over urllib3, a hand-rolled
+Solidity ABI codec, EIP-55 checksums, and Multicall3 batching.
+
+Built to replace the slice of web3.py that a backend actually uses, without
+pulling in web3, eth-abi, eth-utils, eth-typing, or their transitive
+dependencies. Two runtime dependencies: `pycryptodome` for Keccak-256 and
+`urllib3` for HTTP.
+
+- Python 3.13+
+- HTTP via `urllib3` with one connection pool per node; no retries, no redirects,
+  and proxy environment variables are not read
+- No ABI/type/hex-byte libraries
+- `py.typed`
+
+## Install
+
+```console
+uv add micro-web3
+```
+
+## Quickstart
+
+```python
+from micro_web3 import Contract, RpcNode
+
+node = RpcNode("https://ethereum-rpc.publicnode.com", timeout=4)
+node.endpoint_uri  # 'https://ethereum-rpc.publicnode.com'
+node.is_connected()  # web3_clientVersion probe; False instead of raising
+node.close()  # optional: release pooled connections (pool size: RpcNode(uri, pool_maxsize=10))
+
+erc20 = Contract("0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", abi)
+erc20.call(node, "decimals")  # 6
+erc20.call(node, "balanceOf", [holder])  # int
+erc20.encode("balanceOf", [holder])  # '0x70a08231...' (hex, selector included)
+```
+
+`Contract.call` performs one `eth_call` and decodes the result: a single
+output is unwrapped, multiple outputs come back as a tuple.
+
+### Logs
+
+```python
+from micro_web3 import get_logs
+
+logs = get_logs(node, address=token, topics=[transfer_topic], from_block=0, to_block="latest")
+logs[0]["blockNumber"]  # '0x...' — raw JSON-RPC, never normalised
+logs[0]["data"]  # '0x...'
+```
+
+Raw hex is deliberate: it matches the Etherscan/Blockscout shapes, so one
+consumer can handle every indexer identically. Block filters accept `int`,
+decimal strings, hex strings or tags; they are emitted as JSON-RPC quantities.
+
+### Multicall
+
+```python
+from micro_web3 import try_aggregate
+
+results = try_aggregate(
+    node,
+    [
+        (token_a, erc20.encode("balanceOf", [holder])),
+        (token_b, erc20.encode("balanceOf", [holder])),
+    ],
+)
+# [b'...', None] — one entry per call, None where that call reverted
+```
+
+`try_aggregate` uses Multicall3's `tryAggregate(false, calls)`.
+
+### ABI
+
+```python
+from micro_web3 import decode_outputs, encode_call, to_checksum_address
+
+data = encode_call(abi, "transfer", [to, amount])
+values = decode_outputs(["uint256"], "0x" + "00" * 31 + "2a")
+```
+
+Supported types: `address`, `bool`, `uintN`, `intN`, `bytesN`, `bytes`,
+`string`, `function`, fixed and dynamic arrays, tuples, and nested
+combinations (`(bool,bytes)[]`, `uint256[2][]`, ...).
+
+Decoding matches eth_abi 6: addresses are lower-case hex strings, arrays and
+tuples are tuples, `bytesN` is `bytes`. Use `to_checksum_address` when you need
+EIP-55 form.
+
+## Errors
+
+Every failure derives from `RpcError`:
+
+| Class | Raised for |
+|---|---|
+| `RpcConnectionError` | unreachable node, timeout, non-JSON HTTP response |
+| `RpcResponseError` | JSON-RPC `error` object; `.code`, `.message`, `.data` |
+| `AbiError` | unknown type, bad value, undecodable payload |
+
+Reverts arrive as `RpcResponseError` with `execution reverted` in the message
+and the revert payload in `.data`. Looking up a function that the ABI does not
+contain raises `AttributeError`, which callers can use to fall back to another
+indexer.
+
+## What replaces what
+
+| web3.py | micro-web3 |
+|---|---|
+| `Web3(Web3.HTTPProvider(uri, request_kwargs={'timeout': 4}))` | `RpcNode(uri, timeout=4)` |
+| `node.is_connected()` | `node.is_connected()` |
+| `web3.manager.request_blocking(method, params)` | `node.request(method, params)` |
+| `contract.encode_abi(name, args=)` | `contract.encode(name, args)` |
+| `contract._find_matching_fn_abi(name, *args)` | `contract.function(name, args)` |
+| `contract.caller().fn(*args)` | `contract.call(node, name, args)` |
+| `web3.codec.decode(types, data)` | `decode_outputs(types, data)` |
+| `node.eth.get_logs(options)` | `get_logs(node, ...)` |
+| `node.eth.get_block('latest')['number']` | `get_block_number(node)` |
+| `Web3.to_checksum_address` | `to_checksum_address` |
+| `web3.exceptions.Web3Exception` | `RpcError` |
+
+## Development
+
+```console
+uv sync --all-groups
+uv run pytest
+MICRON_RPC_URL=https://ethereum-rpc.publicnode.com uv run pytest tests/test_live.py
+uv run ruff check .
+uv run ruff format --check .
+uv run pyrefly check
+```
+
+The ABI tests run against vectors generated with eth_abi 6 (`tests/vectors.json`),
+so the hand-rolled codec is checked against the reference implementation
+without depending on it.

micro_web3-0.1.0/README.md

@@ -0,0 +1,134 @@
+# micro-web3
+
+A small Ethereum client: JSON-RPC over urllib3, a hand-rolled
+Solidity ABI codec, EIP-55 checksums, and Multicall3 batching.
+
+Built to replace the slice of web3.py that a backend actually uses, without
+pulling in web3, eth-abi, eth-utils, eth-typing, or their transitive
+dependencies. Two runtime dependencies: `pycryptodome` for Keccak-256 and
+`urllib3` for HTTP.
+
+- Python 3.13+
+- HTTP via `urllib3` with one connection pool per node; no retries, no redirects,
+  and proxy environment variables are not read
+- No ABI/type/hex-byte libraries
+- `py.typed`
+
+## Install
+
+```console
+uv add micro-web3
+```
+
+## Quickstart
+
+```python
+from micro_web3 import Contract, RpcNode
+
+node = RpcNode("https://ethereum-rpc.publicnode.com", timeout=4)
+node.endpoint_uri  # 'https://ethereum-rpc.publicnode.com'
+node.is_connected()  # web3_clientVersion probe; False instead of raising
+node.close()  # optional: release pooled connections (pool size: RpcNode(uri, pool_maxsize=10))
+
+erc20 = Contract("0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", abi)
+erc20.call(node, "decimals")  # 6
+erc20.call(node, "balanceOf", [holder])  # int
+erc20.encode("balanceOf", [holder])  # '0x70a08231...' (hex, selector included)
+```
+
+`Contract.call` performs one `eth_call` and decodes the result: a single
+output is unwrapped, multiple outputs come back as a tuple.
+
+### Logs
+
+```python
+from micro_web3 import get_logs
+
+logs = get_logs(node, address=token, topics=[transfer_topic], from_block=0, to_block="latest")
+logs[0]["blockNumber"]  # '0x...' — raw JSON-RPC, never normalised
+logs[0]["data"]  # '0x...'
+```
+
+Raw hex is deliberate: it matches the Etherscan/Blockscout shapes, so one
+consumer can handle every indexer identically. Block filters accept `int`,
+decimal strings, hex strings or tags; they are emitted as JSON-RPC quantities.
+
+### Multicall
+
+```python
+from micro_web3 import try_aggregate
+
+results = try_aggregate(
+    node,
+    [
+        (token_a, erc20.encode("balanceOf", [holder])),
+        (token_b, erc20.encode("balanceOf", [holder])),
+    ],
+)
+# [b'...', None] — one entry per call, None where that call reverted
+```
+
+`try_aggregate` uses Multicall3's `tryAggregate(false, calls)`.
+
+### ABI
+
+```python
+from micro_web3 import decode_outputs, encode_call, to_checksum_address
+
+data = encode_call(abi, "transfer", [to, amount])
+values = decode_outputs(["uint256"], "0x" + "00" * 31 + "2a")
+```
+
+Supported types: `address`, `bool`, `uintN`, `intN`, `bytesN`, `bytes`,
+`string`, `function`, fixed and dynamic arrays, tuples, and nested
+combinations (`(bool,bytes)[]`, `uint256[2][]`, ...).
+
+Decoding matches eth_abi 6: addresses are lower-case hex strings, arrays and
+tuples are tuples, `bytesN` is `bytes`. Use `to_checksum_address` when you need
+EIP-55 form.
+
+## Errors
+
+Every failure derives from `RpcError`:
+
+| Class | Raised for |
+|---|---|
+| `RpcConnectionError` | unreachable node, timeout, non-JSON HTTP response |
+| `RpcResponseError` | JSON-RPC `error` object; `.code`, `.message`, `.data` |
+| `AbiError` | unknown type, bad value, undecodable payload |
+
+Reverts arrive as `RpcResponseError` with `execution reverted` in the message
+and the revert payload in `.data`. Looking up a function that the ABI does not
+contain raises `AttributeError`, which callers can use to fall back to another
+indexer.
+
+## What replaces what
+
+| web3.py | micro-web3 |
+|---|---|
+| `Web3(Web3.HTTPProvider(uri, request_kwargs={'timeout': 4}))` | `RpcNode(uri, timeout=4)` |
+| `node.is_connected()` | `node.is_connected()` |
+| `web3.manager.request_blocking(method, params)` | `node.request(method, params)` |
+| `contract.encode_abi(name, args=)` | `contract.encode(name, args)` |
+| `contract._find_matching_fn_abi(name, *args)` | `contract.function(name, args)` |
+| `contract.caller().fn(*args)` | `contract.call(node, name, args)` |
+| `web3.codec.decode(types, data)` | `decode_outputs(types, data)` |
+| `node.eth.get_logs(options)` | `get_logs(node, ...)` |
+| `node.eth.get_block('latest')['number']` | `get_block_number(node)` |
+| `Web3.to_checksum_address` | `to_checksum_address` |
+| `web3.exceptions.Web3Exception` | `RpcError` |
+
+## Development
+
+```console
+uv sync --all-groups
+uv run pytest
+MICRON_RPC_URL=https://ethereum-rpc.publicnode.com uv run pytest tests/test_live.py
+uv run ruff check .
+uv run ruff format --check .
+uv run pyrefly check
+```
+
+The ABI tests run against vectors generated with eth_abi 6 (`tests/vectors.json`),
+so the hand-rolled codec is checked against the reference implementation
+without depending on it.

micro_web3-0.1.0/pyproject.toml

@@ -0,0 +1,78 @@
+[project]
+name = "micro-web3"
+version = "0.1.0"
+description = "Minimal Ethereum JSON-RPC and ABI client"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.13"
+keywords = [
+    "ethereum",
+    "web3",
+    "json-rpc",
+    "abi",
+    "keccak",
+    "multicall",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pycryptodome>=3.20,<4",
+    "urllib3>=2,<3",
+]
+
+[[project.authors]]
+name = "Yabir Benchakhtir"
+email = "git@yabirgb.com"
+
+[dependency-groups]
+dev = [
+    "pyrefly>=1.4.0",
+    "pytest>=8.3",
+    "ruff>=0.9",
+]
+
+[build-system]
+requires = ["uv_build>=0.13.7,<0.14.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "micro_web3"
+module-root = "src"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.ruff]
+line-length = 100
+target-version = "py313"
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "UP",
+    "B",
+    "SIM",
+    "RUF",
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["micro_web3"]
+
+[tool.pyrefly]
+python-version = "3.13"
+project-includes = [
+    "src/**/*.py",
+    "tests/**/*.py",
+]
+search-path = ["src"]

micro_web3-0.1.0/pyproject.toml.orig

@@ -0,0 +1,59 @@
+[project]
+name = "micro-web3"
+version = "0.1.0"
+description = "Minimal Ethereum JSON-RPC and ABI client"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Yabir Benchakhtir", email = "git@yabirgb.com" }
+]
+requires-python = ">=3.13"
+keywords = ["ethereum", "web3", "json-rpc", "abi", "keccak", "multicall"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pycryptodome>=3.20,<4",
+    "urllib3>=2,<3",
+]
+
+[dependency-groups]
+dev = [
+    "pyrefly>=1.4.0",
+    "pytest>=8.3",
+    "ruff>=0.9",
+]
+
+[build-system]
+requires = ["uv_build>=0.13.7,<0.14.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "micro_web3"
+module-root = "src"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.ruff]
+line-length = 100
+target-version = "py313"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["micro_web3"]
+
+[tool.pyrefly]
+python-version = "3.13"
+project-includes = ["src/**/*.py", "tests/**/*.py"]
+search-path = ["src"]

micro_web3-0.1.0/src/micro_web3/__init__.py

@@ -0,0 +1,58 @@
+"""micro-web3: a small Ethereum JSON-RPC + ABI client.
+
+Replaces the web3.py surface used by the rotki web backend: JSON-RPC transport,
+calldata encoding, output decoding, log queries and Multicall3 batching.
+
+    >>> from micro_web3 import Contract, RpcNode
+    >>> node = RpcNode('https://ethereum-rpc.publicnode.com', timeout=4)
+    >>> node.is_connected()
+    True
+    >>> contract = Contract('0xA0b8...eB48', erc20_abi)
+    >>> contract.call(node, 'decimals')
+    6
+"""
+
+from .abi import (
+    AbiType,
+    canonical,
+    decode,
+    decode_outputs,
+    encode,
+    encode_call,
+    find_function,
+    parse_type,
+)
+from .addresses import is_address, to_checksum_address
+from .contract import Contract
+from .errors import AbiError, RpcConnectionError, RpcError, RpcResponseError
+from .methods import eth_call, get_block_number, get_logs, to_quantity
+from .multicall import MULTICALL3_ADDRESS, try_aggregate
+from .rpc import RpcNode
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "MULTICALL3_ADDRESS",
+    "AbiError",
+    "AbiType",
+    "Contract",
+    "RpcConnectionError",
+    "RpcError",
+    "RpcNode",
+    "RpcResponseError",
+    "__version__",
+    "canonical",
+    "decode",
+    "decode_outputs",
+    "encode",
+    "encode_call",
+    "eth_call",
+    "find_function",
+    "get_block_number",
+    "get_logs",
+    "is_address",
+    "parse_type",
+    "to_checksum_address",
+    "to_quantity",
+    "try_aggregate",
+]

micro_web3-0.1.0/src/micro_web3/_keccak.py

@@ -0,0 +1,14 @@
+"""Keccak-256.
+
+Not SHA3-256: Ethereum uses the original Keccak padding, which the standard
+library's ``hashlib.sha3_256`` does not implement. pycryptodome provides the C
+implementation.
+"""
+
+from Crypto.Hash import keccak
+
+
+def keccak256(data: bytes) -> bytes:
+    digest = keccak.new(digest_bits=256)
+    digest.update(data)
+    return digest.digest()