Additional utility functions useful for get_event_data

Build filter params using `construct_event_filter_params`
Find ABIs for events and functions with `find_matching_event_abi`, `find_matching_fn_abi`
Fix imports

Author: Stuart Reed

docs/web3.contract.rst

@@ -1178,6 +1178,87 @@ Utils
           '_debatingPeriod': 604800,
           '_newCurator': True})
 
+.. py:method:: web3.contract.utils.get_function_info(fn_name, abi_codec, contract_abi, fn_abi, args, kwargs)
+
+    Get function signature and information from a contract ABI given a name, contract 
+    ABI, and arguments.
+
+    If the function exists and its signature matches the provided arguments, the 
+    function ABI, selector and arguments will be returned.
+
+    Inspect a contract function from an ABI as follows:
+
+    .. code-block:: python
+
+        # Contract ABI with a single "counter" function
+        contract_abi = [
+            {
+                "inputs": [],
+                "name": "counter",
+                "outputs": [{"internalType": "uint256", "name": "", "type": "uint256"}],
+                "stateMutability": "view",
+                "type": "function",
+            },
+        ]
+
+        >>> web3.contract.utils.get_function_info("counter", w3.codec, contract_abi)
+        ({'inputs': [], 'name': 'counter', 'outputs': [{'internalType': 'uint256', 'name': '', 'type': 'uint256'}], 'stateMutability': 'view', 'type': 'function'}, '0x61bc221a', ())
+
+.. py:method:: web3.contract.utils.get_event_data(abi_codec, event_abi, log_entry)
+
+    Get decoded event data from a log entry using an event ABI.
+
+    For example, to find all WETH "Transfer" events in the latest block:
+
+    .. code-block:: python
+
+        WETH_ADDRESS = '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2'
+        WETH_ABI = '[{"constant":true,"inputs":[],"name":"name","outputs":[{"name":"","type":"string"}],"payable":false,"stateMutability":"view","type":"function"},{"constant":false,"inputs":[{"name":"guy","type":"address"},{"name":"wad","type":"uint256"}],"name":"approve","outputs":[{"name":"","type":"bool"}],"payable":false,"stateMutability":"nonpayable","type":"function"},{"constant":true,"inputs":[],"name":"totalSupply","outputs":[{"name":"","type":"uint256"}],"payable":false,"stateMutability":"view","type":"function"},{"constant":false,"inputs":[{"name":"src","type":"address"},{"name":"dst","type":"address"},{"name":"wad","type":"uint256"}],"name":"transferFrom","outputs":[{"name":"","type":"bool"}],"payable":false,"stateMutability":"nonpayable","type":"function"},{"constant":false,"inputs":[{"name":"wad","type":"uint256"}],"name":"withdraw","outputs":[],"payable":false,"stateMutability":"nonpayable","type":"function"},{"constant":true,"inputs":[],"name":"decimals","outputs":[{"name":"","type":"uint8"}],"payable":false,"stateMutability":"view","type":"function"},{"constant":true,"inputs":[{"name":"","type":"address"}],"name":"balanceOf","outputs":[{"name":"","type":"uint256"}],"payable":false,"stateMutability":"view","type":"function"},{"constant":true,"inputs":[],"name":"symbol","outputs":[{"name":"","type":"string"}],"payable":false,"stateMutability":"view","type":"function"},{"constant":false,"inputs":[{"name":"dst","type":"address"},{"name":"wad","type":"uint256"}],"name":"transfer","outputs":[{"name":"","type":"bool"}],"payable":false,"stateMutability":"nonpayable","type":"function"},{"constant":false,"inputs":[],"name":"deposit","outputs":[],"payable":true,"stateMutability":"payable","type":"function"},{"constant":true,"inputs":[{"name":"","type":"address"},{"name":"","type":"address"}],"name":"allowance","outputs":[{"name":"","type":"uint256"}],"payable":false,"stateMutability":"view","type":"function"},{"payable":true,"stateMutability":"payable","type":"fallback"},{"anonymous":false,"inputs":[{"indexed":true,"name":"src","type":"address"},{"indexed":true,"name":"guy","type":"address"},{"indexed":false,"name":"wad","type":"uint256"}],"name":"Approval","type":"event"},{"anonymous":false,"inputs":[{"indexed":true,"name":"src","type":"address"},{"indexed":true,"name":"dst","type":"address"},{"indexed":false,"name":"wad","type":"uint256"}],"name":"Transfer","type":"event"},{"anonymous":false,"inputs":[{"indexed":true,"name":"dst","type":"address"},{"indexed":false,"name":"wad","type":"uint256"}],"name":"Deposit","type":"event"},{"anonymous":false,"inputs":[{"indexed":true,"name":"src","type":"address"},{"indexed":false,"name":"wad","type":"uint256"}],"name":"Withdrawal","type":"event"}]'
+
+        # Obtain an event ABI for the "Transfer" event
+        event_abi = find_matching_event_abi(WETH_ABI, "Transfer")
+
+        # Build keccak signatures for event filter_params
+        data_filter_params, filter_params = construct_event_filter_params(
+            event_abi,
+            w3.codec,
+            contract_address=WETH_ADDRESS,
+            fromBlock="latest",
+        )
+
+        # call JSON-RPC API to get logs
+        logs = w3.eth.get_logs(filter_params)
+
+        # convert raw binary data to Python proxy objects as described by ABI:
+        all_event_logs = tuple(get_event_data(w3.codec, event_abi, entry) for entry in logs)
+
+        print(all_event_logs)
+        >>> {'topics': ['0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef'], 'address': '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2', 'fromBlock': 'latest'}
+        logs: [AttributeDict({'address': '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2', 'blockHash': HexBytes('0xf72be5db2280ddc56ce01405f606a99593f95efbf7ebb4ab4df6ba860248410c'), 'blockNumber': 19414349, 'data':
+        HexBytes('0x00000000000000000000000000000000000000000000000000499d1f0dbe4c00'), 'logIndex': 26, 'removed': False, 'topics': [HexBytes('0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef')
+        , HexBytes('0x0000000000000000000000003fc91a3afd70395cd496c647d5a6cc9d4b2b7fad'), HexBytes('0x000000000000000000000000b9ed555632c308f0f44489500045a9afba73473c')], 'transactionHash': HexBytes('0xaaf772c057
+        20be70081aefefcbf88fbe5740a3090afdc1a651b5e4d0e3d8ab75'), 'transactionIndex': 25})]
+        events: (AttributeDict({'args': AttributeDict({'src': '0x3fC91A3afd70395Cd496C647d5a6CC9D4B2b7FAD', 'dst': '0xB9ed555632c308f0f44489500045A9AFba73473c', 'wad': 20720430000000000}), 'event': 'Transfer', 'l
+        ogIndex': 26, 'transactionIndex': 25, 'transactionHash': HexBytes('0xaaf772c05720be70081aefefcbf88fbe5740a3090afdc1a651b5e4d0e3d8ab75'), 'address': '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2', 'blockHash
+        ': HexBytes('0xf72be5db2280ddc56ce01405f606a99593f95efbf7ebb4ab4df6ba860248410c'), 'blockNumber': 19414349}),)
+
+
+    See also: :class:`web3.contract.ContractEvents` for obtaining event logs from a Contract instance.
+
+.. py:method:: web3.contract.utils.find_matching_event_abi(contract_abi, event_name, argument_names)
+
+    Find the ABI for the event with the provided name. Useful when filtering logs to find event data.
+    
+    Returns ValueError if the event does not exist.
+
+.. py:method:: web3.contract.utils.construct_event_filter_params(event_abi, abi_codec, contract_address, argument_filters, topics, fromBlock, toBlock, address)
+
+    Convert human readable filter inputs to their keccak signatures. Often used when 
+    filtering events using the JSON-RPC :meth:`web3.eth.get_logs() <web3.eth.Eth.get_logs>` API.
+
+    See :doc:`filters` for more examples using filter params.
+
+
 ContractCaller
 --------------
 

tests/core/contracts/test_contract_function_info.py

@@ -40,7 +40,6 @@ def test_get_function_info_for_math_contract(
     w3, math_contract_abi, fn_name, args, kwargs, fn_selector, fn_arguments
 ):
     fn_info_abi, fn_info_selector, fn_info_arguments = get_function_info(
-        # fn_info = get_function_info(
         fn_name,
         w3.codec,
         contract_abi=math_contract_abi,

tests/core/utilities/test_construct_event_filter_params.py

@@ -1,6 +1,6 @@
 import pytest
 
-from web3._utils.filters import (
+from web3.contract.utils import (
     construct_event_filter_params,
 )
 

web3/_utils/contracts.py

@@ -43,10 +43,8 @@
     abi_to_signature,
     check_if_arguments_can_be_encoded,
     filter_by_argument_count,
-    filter_by_argument_name,
     filter_by_encodability,
     filter_by_name,
-    filter_by_type,
     get_abi_input_types,
     get_aligned_abi_inputs,
     get_fallback_func_abi,
@@ -80,7 +78,6 @@
 )
 from web3.types import (
     ABI,
-    ABIEvent,
     ABIFunction,
     BlockIdentifier,
     BlockNumber,
@@ -116,31 +113,6 @@ def extract_argument_types(*args: Sequence[Any]) -> str:
     return ",".join(collapsed_args)
 
 
-def find_matching_event_abi(
-    abi: ABI,
-    event_name: Optional[str] = None,
-    argument_names: Optional[Sequence[str]] = None,
-) -> ABIEvent:
-    filters = [
-        functools.partial(filter_by_type, "event"),
-    ]
-
-    if event_name is not None:
-        filters.append(functools.partial(filter_by_name, event_name))
-
-    if argument_names is not None:
-        filters.append(functools.partial(filter_by_argument_name, argument_names))
-
-    event_abi_candidates = pipe(abi, *filters)
-
-    if len(event_abi_candidates) == 1:
-        return event_abi_candidates[0]
-    elif not event_abi_candidates:
-        raise ValueError("No matching events found")
-    else:
-        raise ValueError("Multiple events found")
-
-
 def find_matching_fn_abi(
     abi: ABI,
     abi_codec: ABICodec,

web3/_utils/filters.py

@@ -3,11 +3,9 @@
     Any,
     Callable,
     Collection,
-    Dict,
     Iterator,
     List,
     Optional,
-    Sequence,
     Tuple,
     Union,
 )
@@ -19,13 +17,11 @@
     parse as parse_type_string,
 )
 from eth_typing import (
-    ChecksumAddress,
     HexStr,
     TypeStr,
 )
 from eth_utils import (
     is_hex,
-    is_list_like,
     is_string,
     is_text,
 )
@@ -43,18 +39,11 @@
 from web3._utils.events import (
     AsyncEventFilterBuilder,
     EventFilterBuilder,
-    construct_event_data_set,
-    construct_event_topic_set,
-)
-from web3._utils.validation import (
-    validate_address,
 )
 from web3.exceptions import (
     Web3ValidationError,
 )
 from web3.types import (
-    ABIEvent,
-    BlockIdentifier,
     FilterParams,
     LogReceipt,
     RPCEndpoint,
@@ -65,72 +54,6 @@
     from web3.eth import Eth  # noqa: F401
 
 
-def construct_event_filter_params(
-    event_abi: ABIEvent,
-    abi_codec: ABICodec,
-    contract_address: Optional[ChecksumAddress] = None,
-    argument_filters: Optional[Dict[str, Any]] = None,
-    topics: Optional[Sequence[HexStr]] = None,
-    fromBlock: Optional[BlockIdentifier] = None,
-    toBlock: Optional[BlockIdentifier] = None,
-    address: Optional[ChecksumAddress] = None,
-) -> Tuple[List[List[Optional[HexStr]]], FilterParams]:
-    filter_params: FilterParams = {}
-    topic_set: Sequence[HexStr] = construct_event_topic_set(
-        event_abi, abi_codec, argument_filters
-    )
-
-    if topics is not None:
-        if len(topic_set) > 1:
-            raise TypeError(
-                "Merging the topics argument with topics generated "
-                "from argument_filters is not supported."
-            )
-        topic_set = topics
-
-    if len(topic_set) == 1 and is_list_like(topic_set[0]):
-        # type ignored b/c list-like check on line 88
-        filter_params["topics"] = topic_set[0]  # type: ignore
-    else:
-        filter_params["topics"] = topic_set
-
-    if address and contract_address:
-        if is_list_like(address):
-            filter_params["address"] = [address] + [contract_address]
-        elif is_string(address):
-            filter_params["address"] = (
-                [address, contract_address]
-                if address != contract_address
-                else [address]
-            )
-        else:
-            raise ValueError(
-                f"Unsupported type for `address` parameter: {type(address)}"
-            )
-    elif address:
-        filter_params["address"] = address
-    elif contract_address:
-        filter_params["address"] = contract_address
-
-    if "address" not in filter_params:
-        pass
-    elif is_list_like(filter_params["address"]):
-        for addr in filter_params["address"]:
-            validate_address(addr)
-    else:
-        validate_address(filter_params["address"])
-
-    if fromBlock is not None:
-        filter_params["fromBlock"] = fromBlock
-
-    if toBlock is not None:
-        filter_params["toBlock"] = toBlock
-
-    data_filters_set = construct_event_data_set(event_abi, abi_codec, argument_filters)
-
-    return data_filters_set, filter_params
-
-
 class BaseFilter:
     callbacks: List[Callable[..., Any]] = None
     stopped = False

web3/contract/base_contract.py

@@ -47,7 +47,6 @@
 from web3._utils.contracts import (
     decode_transaction_data,
     encode_abi,
-    find_matching_event_abi,
     find_matching_fn_abi,
     get_function_info,
     prepare_transaction,
@@ -67,9 +66,6 @@
     EventFilterBuilder,
     is_dynamic_sized_type,
 )
-from web3._utils.filters import (
-    construct_event_filter_params,
-)
 from web3._utils.function_identifiers import (
     FallbackFn,
     ReceiveFn,
@@ -78,6 +74,8 @@
     BASE_RETURN_NORMALIZERS,
 )
 from web3.contract.utils import (
+    construct_event_filter_params,
+    find_matching_event_abi,
     get_event_data,
 )
 from web3.datastructures import (