fastweb3-objects 0.1.0__py3-none-any.whl

fw3_objects/abi.py

@@ -0,0 +1,511 @@
+"""Utilities for ABI encoding, decoding, and signature handling."""
+
+import re
+
+from Crypto.Hash import keccak
+from eth.codecs import abi as _abi
+from fw3_keypass.utils import checksum_address
+
+from .errors import ABITypeError, ABIValueError
+
+_ARRAY_RE = re.compile(r"\[(\d*)\]")
+_INT_RE = re.compile(r"^(u?int)(\d*)$")
+_BYTES_RE = re.compile(r"^bytes(\d*)$")
+_HEX_RE = re.compile(r"^[0-9a-fA-F]*$")
+_DECIMAL_INT_RE = re.compile(r"^-?[0-9]+$")
+_HEX_INT_RE = re.compile(r"^-?0[xX][0-9a-fA-F]+$")
+_ADDRESS_RE = re.compile(r"^0x[0-9a-fA-F]{40}$")
+_DYNAMIC_TYPES = {"bytes", "string"}
+
+
+def _abi_item_type(item: dict) -> str:
+    item_type = item["type"]
+
+    if not item_type.startswith("tuple"):
+        return item_type
+
+    suffix = item_type[5:]
+    components = item.get("components", [])
+    inner = ",".join(_abi_item_type(component) for component in components)
+    return f"({inner}){suffix}"
+
+
+def _abi_schema(items: list[dict]) -> str:
+    types = ",".join(_abi_item_type(item) for item in items)
+    return f"({types})"
+
+
+def _split_array_type(item_type: str) -> tuple[str, list[int | None]]:
+    if "[" not in item_type:
+        return item_type, []
+
+    base = item_type[: item_type.index("[")]
+    suffix = item_type[len(base) :]
+    dims = []
+
+    matches = list(_ARRAY_RE.finditer(suffix))
+    if not matches or "".join(i.group(0) for i in matches) != suffix:
+        raise ABIValueError(f"Invalid ABI array type: {item_type}")
+
+    for match in matches:
+        size = match.group(1)
+        dims.append(None if size == "" else int(size))
+
+    return base, dims
+
+
+def _coerce_args(items: list[dict], values: tuple) -> tuple:
+    if len(items) != len(values):
+        raise ABITypeError(f"Expected {len(items)} arguments, got {len(values)}")
+    return tuple(_coerce_value(item, value) for item, value in zip(items, values, strict=True))
+
+
+def _coerce_value(item: dict, value):
+    base_type, dims = _split_array_type(item["type"])
+
+    if dims:
+        return _coerce_array(item, value, base_type, dims)
+
+    if base_type == "address":
+        return _coerce_address(value)
+    if base_type == "bool":
+        return _coerce_bool(value)
+    if base_type == "string":
+        return _coerce_string(value)
+    if base_type == "bytes":
+        return _coerce_dynamic_bytes(value)
+    if base_type.startswith("bytes"):
+        return _coerce_fixed_bytes(base_type, value)
+    if base_type.startswith("uint") or base_type.startswith("int"):
+        return _coerce_int(base_type, value)
+    if base_type == "tuple":
+        return _coerce_tuple(item, value)
+
+    raise ABIValueError(f"Unsupported ABI type: {item['type']}")
+
+
+def _coerce_array(item: dict, value, base_type: str, dims: list[int | None]):
+    if not isinstance(value, (list, tuple)):
+        raise ABITypeError(f"Expected list or tuple for {item['type']}")
+
+    size = dims[-1]
+    if size is not None and len(value) != size:
+        raise ABIValueError(f"Expected array of length {size} for {item['type']}, got {len(value)}")
+
+    child = dict(item)
+    child["type"] = base_type + "".join("[]" if i is None else f"[{i}]" for i in dims[:-1])
+    return tuple(_coerce_value(child, i) for i in value)
+
+
+def _coerce_tuple(item: dict, value):
+    if not isinstance(value, (list, tuple)):
+        raise ABITypeError("Expected list or tuple for tuple ABI argument")
+    return _coerce_args(item.get("components", []), tuple(value))
+
+
+def _coerce_address(value) -> str:
+    from .account import Account
+    from .contract import Contract
+
+    if isinstance(value, Contract):
+        value = value.address.address
+
+    if isinstance(value, Account):
+        value = value.address
+
+    if not isinstance(value, str):
+        raise ABITypeError("Expected address string or Account")
+    if not _ADDRESS_RE.fullmatch(value):
+        raise ABIValueError(f"Invalid address: {value}")
+
+    return checksum_address(value)
+
+
+def _coerce_bool(value) -> bool:
+    if not isinstance(value, bool):
+        raise ABITypeError("Expected bool")
+    return value
+
+
+def _coerce_string(value) -> str:
+    if not isinstance(value, str):
+        raise ABITypeError("Expected string")
+    return value
+
+
+def _coerce_dynamic_bytes(value) -> bytes:
+    if isinstance(value, bytes):
+        return value
+    if isinstance(value, str):
+        return _coerce_hexbytes(value)
+    raise ABITypeError("Expected bytes or 0x-prefixed hex string")
+
+
+def _coerce_fixed_bytes(item_type: str, value) -> bytes:
+    match = _BYTES_RE.fullmatch(item_type)
+    if match is None or match.group(1) == "":
+        raise ABIValueError(f"Invalid ABI bytes type: {item_type}")
+
+    size = int(match.group(1))
+    if size < 1 or size > 32:
+        raise ABIValueError(f"Invalid ABI bytes size: {size}")
+
+    value = _coerce_dynamic_bytes(value)
+    if len(value) != size:
+        raise ABIValueError(f"Expected {item_type} value of length {size}, got {len(value)}")
+    return value
+
+
+def _coerce_hexbytes(value: str) -> bytes:
+    if not value.startswith("0x"):
+        raise ABITypeError("Expected 0x-prefixed hex string")
+
+    value = value[2:]
+    if len(value) % 2:
+        raise ABIValueError("Hex string must contain an even number of digits")
+    if not _HEX_RE.fullmatch(value):
+        raise ABIValueError("Invalid hex string")
+    return bytes.fromhex(value)
+
+
+def _coerce_int(item_type: str, value) -> int:
+    match = _INT_RE.fullmatch(item_type)
+    if match is None:
+        raise ABIValueError(f"Invalid ABI integer type: {item_type}")
+
+    signed = match.group(1) == "int"
+    bits = int(match.group(2) or 256)
+    if bits < 8 or bits > 256 or bits % 8:
+        raise ABIValueError(f"Invalid ABI integer size: {bits}")
+
+    if isinstance(value, bool):
+        raise ABITypeError(f"Expected {item_type}")
+    if isinstance(value, int):
+        coerced = value
+    elif isinstance(value, float):
+        coerced = _coerce_float_int(item_type, value)
+    elif isinstance(value, str):
+        coerced = _coerce_string_int(item_type, value)
+    else:
+        raise ABITypeError(f"Expected {item_type}")
+
+    if signed:
+        lower = -(2 ** (bits - 1))
+        upper = 2 ** (bits - 1) - 1
+    else:
+        lower = 0
+        upper = 2**bits - 1
+
+    if coerced < lower or coerced > upper:
+        raise ABIValueError(f"{item_type} value {coerced} is outside bounds [{lower}, {upper}]")
+    return coerced
+
+
+def _coerce_float_int(item_type: str, value: float) -> int:
+    try:
+        coerced = int(value)
+    except (OverflowError, ValueError) as exc:
+        raise ABIValueError(f"Invalid {item_type} value: {value}") from exc
+
+    if value != coerced:
+        raise ABIValueError(f"Expected integral float for {item_type}")
+    return coerced
+
+
+def _coerce_string_int(item_type: str, value: str) -> int:
+    try:
+        if _HEX_INT_RE.fullmatch(value):
+            return int(value, 16)
+        if _DECIMAL_INT_RE.fullmatch(value):
+            return int(value, 10)
+        raise ValueError
+    except ValueError as exc:
+        raise ABIValueError(f"Invalid {item_type} string: {value}") from exc
+
+
+def encode(schema: str, values: tuple) -> bytes:
+    """Encode values using an ABI schema string.
+
+    Args:
+        schema: Parenthesized ABI schema, such as ``"(address,uint256)"``.
+        values: Values to encode.
+
+    Returns:
+        ABI-encoded bytes.
+    """
+    return _abi.encode(schema, values)
+
+
+def decode(schema: str, data: bytes):
+    """Decode ABI-encoded bytes using an ABI schema string.
+
+    Args:
+        schema: Parenthesized ABI schema, such as ``"(address,uint256)"``.
+        data: ABI-encoded bytes.
+
+    Returns:
+        Decoded values.
+    """
+    return _abi.decode(schema, data)
+
+
+def _coerce_hex(value, name: str) -> str:
+    if isinstance(value, bytes):
+        return "0x" + value.hex()
+    if not isinstance(value, str):
+        raise ABITypeError(f"{name} must be bytes or a hex string")
+    if not value.startswith("0x"):
+        raise ABIValueError(f"{name} must be 0x-prefixed")
+    try:
+        bytes.fromhex(value[2:])
+    except ValueError as exc:
+        raise ABIValueError(f"{name} must be valid hex") from exc
+    return value.lower()
+
+
+def _hex_to_bytes(value, name: str) -> bytes:
+    value = _coerce_hex(value, name)
+    return bytes.fromhex(value[2:])
+
+
+def _is_dynamic_indexed_type(item: dict) -> bool:
+    item_type = item["type"]
+    base_type, dims = _split_array_type(item_type)
+    return bool(dims) or base_type in _DYNAMIC_TYPES or base_type == "tuple"
+
+
+def _normalize_decoded_value(item: dict, value):
+    item_type = item["type"]
+    base_type, dims = _split_array_type(item_type)
+
+    if dims:
+        child = dict(item)
+        child["type"] = base_type + "".join("[]" if i is None else f"[{i}]" for i in dims[:-1])
+        return tuple(_normalize_decoded_value(child, i) for i in value)
+
+    if base_type == "address":
+        return checksum_address(value)
+    if base_type == "tuple":
+        return tuple(
+            _normalize_decoded_value(component, item_value)
+            for component, item_value in zip(item.get("components", []), value, strict=True)
+        )
+    return value
+
+
+def event_signature(event_abi: dict) -> str:
+    """Return the canonical signature for an event ABI item.
+
+    Args:
+        event_abi: Event ABI item.
+
+    Returns:
+        Signature string such as ``"Transfer(address,address,uint256)"``.
+
+    Raises:
+        ABIValueError: If the ABI item is not an event.
+    """
+    if event_abi.get("type") != "event":
+        raise ABIValueError("ABI item is not an event")
+
+    name = event_abi["name"]
+    inputs = event_abi.get("inputs", [])
+    types = ",".join(_abi_item_type(i) for i in inputs)
+    return f"{name}({types})"
+
+
+def event_topic(event_abi: dict) -> str:
+    """Return the topic hash for an event ABI item.
+
+    Args:
+        event_abi: Event ABI item.
+
+    Returns:
+        Hex-encoded keccak256 hash of the event signature.
+    """
+    k = keccak.new(digest_bits=256)
+    k.update(event_signature(event_abi).encode())
+    return "0x" + k.hexdigest()
+
+
+def decode_event(event_abi: dict, raw_log: dict) -> dict[str, object]:
+    """Decode a raw log using an event ABI item.
+
+    Indexed dynamic values are returned as their topic hash, matching Ethereum log
+    semantics.
+
+    Args:
+        event_abi: Event ABI item.
+        raw_log: RPC log object containing ``topics`` and ``data``.
+
+    Returns:
+        Mapping of event argument names to decoded values.
+
+    Raises:
+        ABIValueError: If the ABI item, topic count, or event topic is invalid.
+    """
+    if event_abi.get("type") != "event":
+        raise ABIValueError("ABI item is not an event")
+    if event_abi.get("anonymous", False):
+        raise ABIValueError("Anonymous events are not supported")
+
+    topics = tuple(_coerce_hex(i, "topic") for i in raw_log.get("topics", []))
+    expected_topic = event_topic(event_abi)
+    inputs = event_abi.get("inputs", [])
+    indexed = [i for i in inputs if i.get("indexed", False)]
+    non_indexed = [i for i in inputs if not i.get("indexed", False)]
+
+    expected_topics = 1 + len(indexed)
+    if len(topics) != expected_topics:
+        raise ABIValueError(f"Expected {expected_topics} topics, got {len(topics)}")
+    if topics[0] != expected_topic:
+        raise ABIValueError(f"Topic {topics[0]} does not match event topic {expected_topic}")
+
+    values = {}
+    topic_index = 1
+    data_values = decode(_abi_schema(non_indexed), _hex_to_bytes(raw_log.get("data", "0x"), "data"))
+    data_iter = iter(data_values)
+
+    for item in inputs:
+        name = item.get("name", "")
+        if item.get("indexed", False):
+            topic = topics[topic_index]
+            topic_index += 1
+            if _is_dynamic_indexed_type(item):
+                value = topic
+            else:
+                decoded = decode(_abi_schema([item]), _hex_to_bytes(topic, "topic"))[0]
+                value = _normalize_decoded_value(item, decoded)
+        else:
+            value = _normalize_decoded_value(item, next(data_iter))
+        values[name] = value
+
+    return values
+
+
+def function_signature(method_abi: dict) -> str:
+    """Return the canonical signature for a function ABI item.
+
+    Args:
+        method_abi: Function ABI item.
+
+    Returns:
+        Signature string such as ``"balanceOf(address)"``.
+    """
+    name = method_abi["name"]
+    inputs = method_abi.get("inputs", [])
+    types = ",".join(i["type"] for i in inputs)
+    return f"{name}({types})"
+
+
+def function_selector(method_abi: dict) -> bytes:
+    """Return the four-byte selector for a function ABI item.
+
+    Args:
+        method_abi: Function ABI item.
+
+    Returns:
+        First four bytes of the keccak256 function signature hash.
+    """
+    k = keccak.new(digest_bits=256)
+    k.update(function_signature(method_abi).encode())
+    return k.digest()[:4]
+
+
+def overlay_abi(implementation_abi: list[dict], proxy_abi: list[dict]) -> list[dict]:
+    """Overlay proxy ABI items on top of implementation ABI items.
+
+    Function selectors from the proxy ABI take precedence over matching
+    implementation selectors. Non-function ABI items from both lists are preserved.
+
+    Args:
+        implementation_abi: ABI for the implementation contract.
+        proxy_abi: ABI for the proxy contract.
+
+    Returns:
+        Combined ABI list.
+    """
+    items = []
+    functions = {}
+
+    for item in [*implementation_abi, *proxy_abi]:
+        if item.get("type", "function") != "function":
+            items.append(item)
+            continue
+
+        selector = function_selector(item)
+        if selector in functions:
+            items[functions[selector]] = item
+        else:
+            functions[selector] = len(items)
+            items.append(item)
+
+    return items
+
+
+def decode_calldata(method_abi: dict, hexstr: str):
+    """Decode function calldata for a specific ABI item.
+
+    Args:
+        method_abi: Function ABI item.
+        hexstr: Hex-encoded calldata including the function selector.
+
+    Returns:
+        Decoded input values.
+
+    Raises:
+        ValueError: If calldata is too short or has the wrong selector.
+    """
+    data = bytes.fromhex(hexstr.removeprefix("0x"))
+
+    if len(data) < 4:
+        raise ValueError("Input data is shorter than a function selector")
+
+    selector = data[:4]
+    expected_selector = function_selector(method_abi)
+    if selector != expected_selector:
+        raise ValueError(
+            f"Input selector 0x{selector.hex()} does not match "
+            f"method selector 0x{expected_selector.hex()}"
+        )
+
+    schema = _abi_schema(method_abi.get("inputs", []))
+    return decode(schema, data[4:])
+
+
+def encode_calldata(method_abi: dict, args: tuple):
+    """Encode function calldata for a specific ABI item.
+
+    Args:
+        method_abi: Function ABI item.
+        args: Function arguments.
+
+    Returns:
+        Hex-encoded calldata including the function selector.
+    """
+    inputs = method_abi.get("inputs", [])
+    schema = _abi_schema(inputs)
+    coerced = _coerce_args(inputs, args)
+    data = function_selector(method_abi) + encode(schema, coerced)
+    return f"0x{data.hex()}"
+
+
+def decode_returndata(method_abi: dict, hexstr: str):
+    """Decode function return data for a specific ABI item.
+
+    Args:
+        method_abi: Function ABI item.
+        hexstr: Hex-encoded return data.
+
+    Returns:
+        ``None`` for no outputs, a single value for one output, or a tuple for
+        multiple outputs.
+    """
+    schema = _abi_schema(method_abi.get("outputs", []))
+    values = decode(schema, bytes.fromhex(hexstr.removeprefix("0x")))
+
+    if len(values) == 0:
+        return None
+    if len(values) == 1:
+        return values[0]
+    return values