qweb3 1.1.0__py3-none-any.whl

qweb3/__init__.py

@@ -0,0 +1,107 @@
+"""qweb3 — Quantova Post-Quantum Web3 Client SDK (Python).
+
+A synchronous client for the Quantova Layer-1 blockchain: post-quantum wallets
+and signing (Falcon, Dilithium, SPHINCS+), the full ``q_*`` JSON-RPC namespace,
+a QVM contract layer with ABI codec and event-log decoding, QNS ``.q`` name
+resolution, dynamic fee/gas estimation, batch requests, real-time event hooks,
+and REST-gateway access.
+
+Quick start::
+
+    from qweb3 import QWeb3
+    q = QWeb3("http://127.0.0.1:9944", rest_url="http://127.0.0.1:8080")
+    block = q.rpc.block_number()
+    fees = q.fees.estimate()
+
+Post-quantum signing requires Quantova's crypto backend; install it and call
+``qweb3.crypto_backend.set_backend(...)`` (see that module's docstring).
+"""
+
+from . import abi, crypto_backend
+from .abi import (
+    decode_function_result,
+    decode_parameters,
+    encode_function_call,
+    encode_parameters,
+    event_topic,
+    function_selector,
+)
+from .batch import BatchRequest, BatchResult
+from .contract import QContract
+from .errors import (
+    ConnectionErrorQ,
+    InvalidArgumentError,
+    QWeb3Error,
+    RpcError,
+    TransactionError,
+)
+from .fee import FeeOracle
+from .hooks import EventHooks, TxTracker
+from .qns import QNS
+from .rest import QRestClient
+from .rpc import QRpcClient
+from .signer import QuantumSigner
+from .utils import AddressUtils, FormatUtils, HexUtils, ValidationUtils
+from .wallet import Account, QuantumWallet
+
+__version__ = "1.1.0"
+
+
+class QWeb3:
+    """High-level facade wiring the RPC client, wallet, fees, hooks, and helpers."""
+
+    def __init__(self, url: str = "http://127.0.0.1:9944", *,
+                 rest_url: str = None, session=None) -> None:
+        self.url = url
+        self.rpc = QRpcClient(url, session=session)
+        self.rest = QRestClient(rest_url, session=session) if rest_url else None
+        self.wallet = QuantumWallet()
+        self.signer = QuantumSigner
+        self.abi = abi
+        self.fees = FeeOracle(rpc=self.rpc, rest_client=self.rest)
+        self.hooks = EventHooks(rpc=self.rpc, rest_client=self.rest)
+
+    def contract(self, abi_list, address: str) -> QContract:
+        return QContract(abi_list, address, rpc=self.rpc, wallet=self.wallet, rest_client=self.rest)
+
+    def qns(self, registry_address: str, **kwargs) -> QNS:
+        return QNS(registry_address, rpc=self.rpc, wallet=self.wallet,
+                   rest_client=self.rest, **kwargs)
+
+    def batch(self) -> BatchRequest:
+        return BatchRequest(self.url)
+
+
+__all__ = [
+    "QWeb3",
+    "QRpcClient",
+    "QRestClient",
+    "QuantumWallet",
+    "Account",
+    "QuantumSigner",
+    "QContract",
+    "QNS",
+    "BatchRequest",
+    "BatchResult",
+    "FeeOracle",
+    "EventHooks",
+    "TxTracker",
+    "AddressUtils",
+    "HexUtils",
+    "FormatUtils",
+    "ValidationUtils",
+    "QWeb3Error",
+    "ConnectionErrorQ",
+    "InvalidArgumentError",
+    "RpcError",
+    "TransactionError",
+    "abi",
+    "crypto_backend",
+    "function_selector",
+    "event_topic",
+    "encode_parameters",
+    "decode_parameters",
+    "encode_function_call",
+    "decode_function_result",
+    "__version__",
+]

qweb3/_keccak.py

@@ -0,0 +1,73 @@
+"""Pure-Python keccak-256 (Ethereum/Solidity padding, 0x01).
+
+This is the default selector/topic hash used by the QVM ABI codec, which speaks
+the standard Solidity ABI. It is dependency-free so the codec works out of the
+box; it can be overridden via ``qweb3.abi.set_keccak`` (for example to use a
+faster C implementation, or the hash provided by Quantova's crypto backend).
+
+Note: this is keccak-256, not SHA3-256. They differ only in the padding byte.
+Quantova hashes *transactions/state* with SHA3-256 (handled in the signing
+layer); contract-call *selectors* use keccak-256, which is what this provides.
+"""
+
+from typing import List
+
+_RC = [
+    0x0000000000000001, 0x0000000000008082, 0x800000000000808A, 0x8000000080008000,
+    0x000000000000808B, 0x0000000080000001, 0x8000000080008081, 0x8000000000008009,
+    0x000000000000008A, 0x0000000000000088, 0x0000000080008009, 0x000000008000000A,
+    0x000000008000808B, 0x800000000000008B, 0x8000000000008089, 0x8000000000008003,
+    0x8000000000008002, 0x8000000000000080, 0x000000000000800A, 0x800000008000000A,
+    0x8000000080008081, 0x8000000000008080, 0x0000000080000001, 0x8000000080008008,
+]
+_ROT = [
+    [0, 36, 3, 41, 18],
+    [1, 44, 10, 45, 2],
+    [62, 6, 43, 15, 61],
+    [28, 55, 25, 21, 56],
+    [27, 20, 39, 8, 14],
+]
+_MASK = (1 << 64) - 1
+
+
+def _rotl(x: int, n: int) -> int:
+    return ((x << n) | (x >> (64 - n))) & _MASK
+
+
+def _keccak_f(s: List[List[int]]) -> None:
+    for rnd in range(24):
+        c = [s[x][0] ^ s[x][1] ^ s[x][2] ^ s[x][3] ^ s[x][4] for x in range(5)]
+        d = [c[(x + 4) % 5] ^ _rotl(c[(x + 1) % 5], 1) for x in range(5)]
+        for x in range(5):
+            for y in range(5):
+                s[x][y] ^= d[x]
+        b = [[0] * 5 for _ in range(5)]
+        for x in range(5):
+            for y in range(5):
+                b[y][(2 * x + 3 * y) % 5] = _rotl(s[x][y], _ROT[x][y])
+        for x in range(5):
+            for y in range(5):
+                s[x][y] = (b[x][y] ^ ((~b[(x + 1) % 5][y]) & b[(x + 2) % 5][y])) & _MASK
+        s[0][0] ^= _RC[rnd]
+
+
+def keccak256(data: bytes) -> bytes:
+    """Return the 32-byte keccak-256 digest of ``data``."""
+    rate = 136  # bytes for keccak-256
+    msg = bytearray(data)
+    pad_len = rate - (len(msg) % rate)
+    msg += bytearray(pad_len)
+    msg[len(data)] ^= 0x01          # keccak padding (Ethereum/Solidity)
+    msg[-1] ^= 0x80
+
+    s = [[0] * 5 for _ in range(5)]
+    for off in range(0, len(msg), rate):
+        for i in range(rate // 8):
+            lane = int.from_bytes(msg[off + i * 8: off + i * 8 + 8], "little")
+            s[i % 5][i // 5] ^= lane
+        _keccak_f(s)
+
+    out = bytearray()
+    for i in range(4):  # 4 lanes * 8 bytes = 32 bytes
+        out += (s[i % 5][i // 5]).to_bytes(8, "little")
+    return bytes(out)

qweb3/abi.py

@@ -0,0 +1,341 @@
+"""ABI encoder & decoder for the Quantova Virtual Machine (QVM).
+
+The QVM runs Solidity compiled to PolkaVM via pallet-revive and speaks the
+standard Ethereum/Solidity ABI at the contract-call boundary: keccak-256 4-byte
+function selectors and 32-byte-word ("head/tail") argument encoding. This module
+turns method arguments into hex calldata and decodes return data and event
+topics/data back into Python values.
+
+The keccak implementation defaults to the bundled pure-Python one and can be
+swapped via :func:`set_keccak` (e.g. to use Quantova's crypto backend).
+
+Supported types: ``uint<M>`` / ``int<M>`` (default 256), ``address``, ``bool``,
+``bytes``, ``bytes<N>``, ``string``, and one level of dynamic (``T[]``) or fixed
+(``T[k]``) arrays of those.
+"""
+
+from typing import Any, Callable, Dict, List, Sequence
+
+from ._keccak import keccak256
+
+_keccak: Callable[[bytes], bytes] = keccak256
+
+
+def set_keccak(fn: Callable[[bytes], bytes]) -> None:
+    """Override the keccak-256 implementation (takes/returns ``bytes``)."""
+    global _keccak
+    _keccak = fn
+
+
+# --------------------------------------------------------------------------- #
+# type parsing
+# --------------------------------------------------------------------------- #
+
+def parse_type(type_str: str) -> Dict[str, Any]:
+    if type_str.endswith("]"):
+        idx = type_str.rfind("[")
+        base = parse_type(type_str[:idx])
+        inner = type_str[idx + 1:-1]
+        length = int(inner) if inner != "" else None
+        return {"kind": "array", "base": base, "length": length,
+                "dynamic": length is None or base["dynamic"]}
+    if type_str == "address":
+        return {"kind": "address", "dynamic": False}
+    if type_str == "bool":
+        return {"kind": "bool", "dynamic": False}
+    if type_str == "string":
+        return {"kind": "string", "dynamic": True}
+    if type_str == "bytes":
+        return {"kind": "bytes", "dynamic": True}
+    if type_str.startswith("bytes"):
+        n = int(type_str[5:])
+        if not (1 <= n <= 32):
+            raise ValueError(f"invalid fixed bytes size: {type_str}")
+        return {"kind": "fbytes", "size": n, "dynamic": False}
+    if type_str.startswith("uint"):
+        bits = int(type_str[4:]) if type_str[4:] else 256
+        return {"kind": "uint", "bits": bits, "dynamic": False}
+    if type_str.startswith("int"):
+        bits = int(type_str[3:]) if type_str[3:] else 256
+        return {"kind": "int", "bits": bits, "dynamic": False}
+    raise ValueError(f"unsupported ABI type: {type_str}")
+
+
+def canonical_type(type_str: str) -> str:
+    t = parse_type(type_str)
+    return _canonical(t)
+
+
+def _canonical(t: Dict[str, Any]) -> str:
+    k = t["kind"]
+    if k == "array":
+        return _canonical(t["base"]) + "[" + ("" if t["length"] is None else str(t["length"])) + "]"
+    if k == "uint":
+        return "uint" + str(t["bits"])
+    if k == "int":
+        return "int" + str(t["bits"])
+    if k == "fbytes":
+        return "bytes" + str(t["size"])
+    return {"address": "address", "bool": "bool", "string": "string", "bytes": "bytes"}[k]
+
+
+def _is_dynamic(t: Dict[str, Any]) -> bool:
+    if t["kind"] in ("string", "bytes"):
+        return True
+    if t["kind"] == "array":
+        return t["length"] is None or t["base"]["dynamic"]
+    return False
+
+
+def _head_size(t: Dict[str, Any]) -> int:
+    if _is_dynamic(t):
+        return 32
+    if t["kind"] == "array" and t["length"] is not None:
+        return t["length"] * _head_size(t["base"])
+    return 32
+
+
+# --------------------------------------------------------------------------- #
+# word helpers (two's complement)
+# --------------------------------------------------------------------------- #
+
+def _int_to_word(value: int, signed: bool) -> bytes:
+    v = int(value)
+    mod = 1 << 256
+    if v < 0:
+        if not signed:
+            raise ValueError("negative value for unsigned type")
+        v = (mod + (v % mod)) % mod
+    if v >= mod:
+        raise ValueError("value exceeds 256 bits")
+    return v.to_bytes(32, "big")
+
+
+def _word_to_int(word: bytes, signed: bool) -> int:
+    v = int.from_bytes(word, "big")
+    if signed and v >= (1 << 255):
+        v -= 1 << 256
+    return v
+
+
+# --------------------------------------------------------------------------- #
+# encoding
+# --------------------------------------------------------------------------- #
+
+def _encode_value(t: Dict[str, Any], value: Any) -> bytes:
+    k = t["kind"]
+    if k == "uint":
+        return _int_to_word(value, False)
+    if k == "int":
+        return _int_to_word(value, True)
+    if k == "bool":
+        return _int_to_word(1 if value else 0, False)
+    if k == "address":
+        # Accept a Q-branded account address ("Q1...") as well as a 0x contract address.
+        if isinstance(value, str) and value[:2].upper() == "Q1":
+            from .utils import AddressUtils
+            value = AddressUtils.to_node_address(value)
+        b = HexBytes(value)
+        if len(b) != 20:
+            raise ValueError("address must be 20 bytes")
+        return b"\x00" * 12 + b
+    if k == "fbytes":
+        b = HexBytes(value)
+        if len(b) != t["size"]:
+            raise ValueError(f"bytes{t['size']} must be {t['size']} bytes")
+        return b + b"\x00" * (32 - len(b))
+    if k in ("bytes", "string"):
+        data = value.encode("utf-8") if k == "string" else HexBytes(value)
+        length = _int_to_word(len(data), False)
+        padded = data + b"\x00" * ((32 - len(data) % 32) % 32)
+        return length + padded
+    if k == "array":
+        if not isinstance(value, (list, tuple)):
+            raise ValueError("expected array value")
+        if t["length"] is not None and len(value) != t["length"]:
+            raise ValueError(f"fixed array expected {t['length']} items, got {len(value)}")
+        parts = [_EncodedItem(t["base"], _encode_value(t["base"], v)) for v in value]
+        body = _pack(t["base"], parts)
+        if t["length"] is None:
+            return _int_to_word(len(value), False) + body
+        return body
+    raise ValueError(f"cannot encode kind {k}")
+
+
+class _EncodedItem:
+    __slots__ = ("t", "data")
+
+    def __init__(self, t, data):
+        self.t = t
+        self.data = data
+
+
+def _pack(t: Dict[str, Any], parts: List[_EncodedItem]) -> bytes:
+    if not _is_dynamic(t):
+        return b"".join(p.data for p in parts)
+    heads, tails = [], []
+    offset = len(parts) * 32
+    for p in parts:
+        heads.append(_int_to_word(offset, False))
+        tails.append(p.data)
+        offset += len(p.data)
+    return b"".join(heads) + b"".join(tails)
+
+
+def encode_parameters(types: Sequence[str], values: Sequence[Any]) -> bytes:
+    if len(types) != len(values):
+        raise ValueError(f"type/value count mismatch: {len(types)} vs {len(values)}")
+    descs = [parse_type(t) for t in types]
+    encoded = [_encode_value(d, v) for d, v in zip(descs, values)]
+
+    heads, tails = [], []
+    offset = sum(_head_size(d) for d in descs)
+    for d, e in zip(descs, encoded):
+        if _is_dynamic(d):
+            heads.append(_int_to_word(offset, False))
+            tails.append(e)
+            offset += len(e)
+        else:
+            heads.append(e)
+    return b"".join(heads) + b"".join(tails)
+
+
+def function_selector(signature: str) -> str:
+    """4-byte selector for a signature like ``transfer(address,uint256)``."""
+    return "0x" + _keccak(signature.encode("utf-8"))[:4].hex()
+
+
+def build_signature(name: str, inputs: Sequence[dict]) -> str:
+    types = [canonical_type(i["type"]) for i in (inputs or [])]
+    return f"{name}({','.join(types)})"
+
+
+def encode_function_call(fn_abi: dict, args: Sequence[Any]) -> str:
+    sig = build_signature(fn_abi["name"], fn_abi.get("inputs"))
+    selector = function_selector(sig)
+    types = [i["type"] for i in (fn_abi.get("inputs") or [])]
+    return selector + encode_parameters(types, args or []).hex()
+
+
+def event_topic(signature: str) -> str:
+    """keccak-256 topic hash of an event signature."""
+    return "0x" + _keccak(signature.encode("utf-8")).hex()
+
+
+# --------------------------------------------------------------------------- #
+# decoding
+# --------------------------------------------------------------------------- #
+
+def _decode_value(t: Dict[str, Any], view: bytes, base: int) -> Any:
+    k = t["kind"]
+    if k == "uint":
+        return _word_to_int(view[base:base + 32], False)
+    if k == "int":
+        return _word_to_int(view[base:base + 32], True)
+    if k == "bool":
+        return _word_to_int(view[base:base + 32], False) != 0
+    if k == "address":
+        return "0x" + view[base + 12:base + 32].hex()
+    if k == "fbytes":
+        return "0x" + view[base:base + t["size"]].hex()
+    if k in ("string", "bytes"):
+        offset = _word_to_int(view[base:base + 32], False)
+        length = _word_to_int(view[offset:offset + 32], False)
+        data = view[offset + 32:offset + 32 + length]
+        return data.decode("utf-8") if k == "string" else "0x" + data.hex()
+    if k == "array":
+        if _is_dynamic(t):
+            offset = _word_to_int(view[base:base + 32], False)
+            return _decode_array_at(t, view, offset)
+        out = []
+        cur = base
+        for _ in range(t["length"]):
+            out.append(_decode_value(t["base"], view, cur))
+            cur += _head_size(t["base"])
+        return out
+    raise ValueError(f"cannot decode kind {k}")
+
+
+def _decode_array_at(t: Dict[str, Any], view: bytes, offset: int) -> list:
+    if t["length"] is None:
+        count = _word_to_int(view[offset:offset + 32], False)
+        body = view[offset + 32:]
+        return _decode_items(t["base"], body, count)
+    body = view[offset:]
+    return _decode_items(t["base"], body, t["length"])
+
+
+# [QW3PY-001] Absolute upper bound on any decoded array/element count, mirroring
+# eth-abi's guard against attacker-controlled length fields causing huge allocations.
+_MAX_ARRAY_COUNT = 1_000_000
+
+
+def _check_array_count(count: int, body: bytes) -> None:
+    """[QW3PY-001] Validate an attacker-controlled element count against the
+    remaining buffer before iterating. Each element occupies at least one 32-byte
+    head word, so the buffer can hold at most len(body) // 32 elements; also impose
+    a hard absolute cap to bound work even when the buffer is large."""
+    if count < 0:
+        raise ValueError("array length exceeds buffer")
+    if count > _MAX_ARRAY_COUNT or count > len(body) // 32:
+        raise ValueError("array length exceeds buffer")
+
+
+def _decode_items(base_t: Dict[str, Any], body: bytes, count: int) -> list:
+    _check_array_count(count, body)
+    out = []
+    if _is_dynamic(base_t):
+        for i in range(count):
+            item_offset = _word_to_int(body[i * 32:i * 32 + 32], False)
+            out.append(_decode_value_absolute(base_t, body, item_offset))
+    else:
+        cur = 0
+        for _ in range(count):
+            out.append(_decode_value(base_t, body, cur))
+            cur += _head_size(base_t)
+    return out
+
+
+def _decode_value_absolute(t: Dict[str, Any], view: bytes, start: int) -> Any:
+    if t["kind"] in ("string", "bytes"):
+        length = _word_to_int(view[start:start + 32], False)
+        data = view[start + 32:start + 32 + length]
+        return data.decode("utf-8") if t["kind"] == "string" else "0x" + data.hex()
+    if t["kind"] == "array":
+        return _decode_array_at(t, view, start)
+    return _decode_value(t, view, start)
+
+
+def decode_parameters(types: Sequence[str], data) -> list:
+    view = HexBytes(data)
+    descs = [parse_type(t) for t in types]
+    out = []
+    head = 0
+    for d in descs:
+        out.append(_decode_value(d, view, head))
+        head += _head_size(d)
+    return out
+
+
+def decode_function_result(fn_abi: dict, data) -> Any:
+    types = [o["type"] for o in (fn_abi.get("outputs") or [])]
+    if not types:
+        return None
+    decoded = decode_parameters(types, data)
+    return decoded[0] if len(decoded) == 1 else decoded
+
+
+# --------------------------------------------------------------------------- #
+# small helper
+# --------------------------------------------------------------------------- #
+
+def HexBytes(value) -> bytes:
+    """Coerce a 0x-hex string or bytes-like into ``bytes``."""
+    if isinstance(value, (bytes, bytearray)):
+        return bytes(value)
+    if isinstance(value, str):
+        s = value[2:] if value.startswith(("0x", "0X")) else value
+        if len(s) % 2:
+            raise ValueError(f"invalid hex length: {value}")
+        return bytes.fromhex(s)
+    raise TypeError("expected hex string or bytes")

qweb3/batch.py

@@ -0,0 +1,97 @@
+"""Batch requests portal.
+
+Groups multiple ``q_*`` JSON-RPC calls into a single payload (a JSON-RPC 2.0
+batch array) to cut round-trips. Results come back in insertion order with
+per-call success/error, so one failing call doesn't sink the batch.
+
+    batch = BatchRequest("http://127.0.0.1:9944")
+    batch.add("q_blockNumber").add("q_getBalance", [addr, "latest"])
+    results = batch.execute()   # [BatchResult(...), ...]
+"""
+
+from dataclasses import dataclass
+from typing import Any, List, Optional
+
+try:
+    import requests as _requests
+except Exception:  # pragma: no cover
+    _requests = None
+
+
+@dataclass
+class BatchResult:
+    success: bool
+    result: Any = None
+    error: Optional[str] = None
+
+
+class BatchRequest:
+    def __init__(self, endpoint: str = "http://127.0.0.1:9944",
+                 session: Optional[Any] = None, timeout: int = 30) -> None:
+        self.endpoint = endpoint
+        self.timeout = timeout
+        self._calls: List[dict] = []
+        self._next_id = 1
+        if session is not None:
+            self.session = session
+        else:
+            if _requests is None:
+                raise RuntimeError("the 'requests' package is required (or inject a session)")
+            self.session = _requests.Session()
+
+    def add(self, method: str, params: Optional[list] = None) -> "BatchRequest":
+        self._calls.append({"id": self._next_id, "method": method, "params": params or []})
+        self._next_id += 1
+        return self
+
+    def __len__(self) -> int:
+        return len(self._calls)
+
+    def reset(self) -> "BatchRequest":
+        self._calls = []
+        self._next_id = 1
+        return self
+
+    def execute(self) -> List[BatchResult]:
+        if not self._calls:
+            return []
+        payload = [{"jsonrpc": "2.0", "id": c["id"], "method": c["method"], "params": c["params"]}
+                   for c in self._calls]
+        try:
+            resp = self.session.post(self.endpoint, json=payload,
+                                     headers={"content-type": "application/json"},
+                                     timeout=self.timeout)
+            data = resp.json()
+        except Exception as exc:
+            out = [BatchResult(False, error=f"batch request failed: {exc}") for _ in self._calls]
+            self.reset()
+            return out
+
+        by_id = {}
+        if isinstance(data, list):
+            for r in data:
+                by_id[r.get("id")] = r
+        elif isinstance(data, dict) and data.get("id") is not None:
+            by_id[data["id"]] = data
+
+        out: List[BatchResult] = []
+        for c in self._calls:
+            r = by_id.get(c["id"])
+            if r is None:
+                out.append(BatchResult(False, error=f"no response for {c['method']} (id {c['id']})"))
+            elif r.get("error"):
+                err = r["error"]
+                out.append(BatchResult(False, error=err.get("message") if isinstance(err, dict) else str(err)))
+            else:
+                out.append(BatchResult(True, result=r.get("result")))
+        self.reset()
+        return out
+
+    def execute_or_throw(self) -> list:
+        results = self.execute()
+        values = []
+        for r in results:
+            if not r.success:
+                raise RuntimeError(r.error)
+            values.append(r.result)
+        return values