Function ABI Utilities (#3408)

* Parse and validate contract data using new ``ABI`` utilities.

* Filter elements in a contract's ``ABI``.
* Extract function and event ``ABI`` attributes from a contract.
* Validate arguments passed to a function match the types in the ``ABI``
* Refactor logic and variable naming
  - Replace arguments named ``fn_name`` with ``abi_element_name``
  - Rename `FunctionIdentifier` to `ABIElementIdentifier`
  - Remove redundant logic and `Optional` types
  - Integrate new ABI types in ``eth-typing``.

* Newsfragments for #3408

Author: Stuart Reed

docs/migration.rst

@@ -195,6 +195,10 @@ web3.py. This allows a user to distinguish between when a method is not availabl
 the current provider, ``MethodUnavailable``, and when a method is not supported by
 web3.py under certain conditions, ``MethodNotSupported``.
 
+A ``MismatchedABI`` exception is now raised instead of a ``Web3ValidationError`` in
+cases where an ABI is not compatible with the data being passed to it. This change
+allows for more specific error handling when using certain ABI types.
+
 
 JSON-RPC Error Handling
 ```````````````````````
@@ -252,6 +256,26 @@ The ``personal`` namespace was used for managing accounts and keys and was depre
 in geth in ``v1.11.0``. Geth has moved to using ``clef`` for account and key management.
 
 
+ABI Types Removed
+`````````````````
+
+The type definitions for ABIs, deprecated in ``v6``, have been removed in ``v7``. New
+types have been introduced in the ``eth_typing`` ``v5`` package for ABIs. Improvements have
+been made to make required types more explicit and to offer better semantics.
+
+The following types from ``web3.types`` have been removed:
+- ``ABIEventParams`` is no longer avaiable. Use ``ABIComponentIndexed`` from
+``eth_typing`` to represent event input components.
+- ``ABIEvent`` now resides in ``eth_typing``. ``ABIEvent.type`` and ``ABIEvent.name``
+are now required fields.
+- ``ABIFunctionComponents`` and ``ABIFunctionParams`` are no longer available. Use
+``ABIComponent`` from ``eth_typing`` to represent function input components.
+- ``ABIFunction`` now resides in ``eth_typing``. ``ABIFunction.type`` and
+``ABIFunction.name`` are now required fields.
+- ``ABIElement`` now resides in ``eth_typing`` and represents a ``Union`` of all valid
+ABI element types, ``ABICallable``, ``ABIEvent`` and ``ABIError``.
+
+
 Miscellaneous Changes
 ~~~~~~~~~~~~~~~~~~~~~
 
@@ -262,13 +286,18 @@ Miscellaneous Changes
 - ``User-Agent`` header was changed to a more readable format.
 - ``BaseContractFunctions`` iterator now returns instances of ``ContractFunction`` rather
   than the function names.
+- ``BaseContractFunction`` class attribute ``function_identifier`` has been removed in
+  favor of the ``abi_element_identifier`` attribute.
+- ``web3.contract.utils.call_contract_function()`` no longers uses ``fn_abi`` as a
+  parameter. Instead, the ``abi_callable`` parameter of type ``ABICallable`` is used.
 - Beacon API filename change: ``beacon/main.py`` -> ``beacon/beacon.py``.
 - The asynchronous version of ``w3.eth.wait_for_transaction_receipt()`` changes its
   signature to use ``Optional[float]`` instead of ``float`` since it may be ``None``.
 - ``get_default_ipc_path()`` and ``get_dev_ipc_path()`` now return the path value
   without checking if the ``geth.ipc`` file exists.
 - ``Web3.is_address()`` returns ``True`` for non-checksummed addresses.
-- ``Contract.encodeABI()`` has been renamed to ``Contract.encode_abi()``.
+- ``Contract.encodeABI()`` has been renamed to ``Contract.encode_abi()``. The ``fn_name``
+  argument has been changed to ``abi_element_name``.
 - JSON-RPC responses are now more strictly validated against the JSON-RPC 2.0
   specification while providing more informative error messages for invalid responses.
 

docs/web3.contract.rst

@@ -625,7 +625,7 @@ Taking the following contract code as an example:
     >>> arrays_contract.functions.setBytes2Value([b'b']).transact()
     Traceback (most recent call last):
        ...
-    web3.exceptions.Web3ValidationError:
+    web3.exceptions.MismatchedABI:
     Could not identify the intended function with name
     >>> # check value is still b'aa'
     >>> arrays_contract.functions.getBytes2Value().call()
@@ -650,7 +650,7 @@ Taking the following contract code as an example:
     >>> arrays_contract.functions.setBytes2Value([b'a']).transact()
     Traceback (most recent call last):
        ...
-    web3.exceptions.Web3ValidationError:
+    web3.exceptions.MismatchedABI:
     Could not identify the intended function with name
 
 .. _contract-functions:

docs/web3.utils.rst

@@ -8,14 +8,10 @@ The ``utils`` module houses public utility functions and classes.
 ABI
 ---
 
-.. py:method:: utils.get_abi_input_names(abi)
-
-    Return the ``input`` names for an ABI function or event.
-
-
-.. py:method:: utils.get_abi_output_names(abi)
-
-    Return the ``output`` names an ABI function or event.
+.. automodule:: web3.utils.abi
+   :members:
+   :undoc-members:
+   :show-inheritance:
 
 Address
 -------

ens/base_ens.py

@@ -11,13 +11,15 @@
 from eth_typing import (
     ChecksumAddress,
 )
+from eth_utils.abi import (
+    get_abi_output_types,
+)
 from hexbytes import (
     HexBytes,
 )
 
 from .utils import (
     address_to_reverse_domain,
-    get_abi_output_types,
     is_valid_name,
     label_to_hash,
     normalize_name,

ens/utils.py

@@ -6,8 +6,6 @@
     TYPE_CHECKING,
     Any,
     Collection,
-    Dict,
-    List,
     Optional,
     Sequence,
     Tuple,
@@ -28,9 +26,6 @@
     to_bytes,
     to_normalized_address,
 )
-from eth_utils.abi import (
-    collapse_if_tuple,
-)
 from hexbytes import (
     HexBytes,
 )
@@ -68,9 +63,6 @@
         AsyncBaseProvider,
         BaseProvider,
     )
-    from web3.types import (  # noqa: F401
-        ABIFunction,
-    )
 
 
 def Web3() -> Type["_Web3"]:
@@ -293,15 +285,6 @@ def is_valid_ens_name(ens_name: str) -> bool:
     return True
 
 
-# borrowed from similar method at `web3._utils.abi` due to circular dependency
-def get_abi_output_types(abi: "ABIFunction") -> List[str]:
-    return (
-        []
-        if abi["type"] == "fallback"
-        else [collapse_if_tuple(cast(Dict[str, Any], arg)) for arg in abi["outputs"]]
-    )
-
-
 # -- async -- #
 
 

newsfragments/3408.breaking.rst

@@ -0,0 +1,6 @@
+Upgrades to use latest ``ABI`` utilities and typings from ``eth-utils`` and ``eth-typing``.
+* Typings for ``ABI`` components are now available in the ``eth-typing`` package. ``ABI`` types previously in ``web3.types`` have been removed.
+* New versions of existing ABI functions were added to ``eth-utils`` and are now exposed in `web3.py` via ``web3.utils.abi``.
+* ABI exceptions have been renamed in ``web3.exceptions``. The ``ABIEventFunctionNotFound`` and ``FallbackNotFound`` exceptions have been removed. Use ``ABIEventNotFound`` and ``ABIFallbackNotFound`` instead.
+* ``MismatchedABI`` exceptions are raised instead of a ``Web3ValidationError`` for ABI related errors.
+* ``encode_abi`` arguments have been updated to use ``abi_element_name`` instead of ``fn_name``.

newsfragments/3408.docs.rst

@@ -0,0 +1 @@
+Use autodoc and update ABI functions with docstrings and doctests.

newsfragments/3408.feature.rst

@@ -0,0 +1,7 @@
+Utilities to extract function and event ``ABI`` attributes from a contract. Utilities in the ``web3.utils.abi`` module parse ABI elements and check encodability of provided arguments. ABI functions in ``eth-utils`` are exposed by the ``web3.utils.abi`` module.
+* ``get_abi_element_info`` returns an ``ABIElementInfo`` TypedDict with the ``abi``, ``selector``, and ``arguments``.
+* ``get_abi_element`` returns the ``ABI`` of a function, event, or error given the name and arguments.
+* ``check_if_arguments_can_be_encoded`` returns true if the arguments can be encoded with the given ABI.
+* ``get_event_abi`` returns the ``ABI`` of an event given the name.
+* ``get_event_log_topics`` returns the log topics of an event given the name.
+* ``log_topics_to_bytes`` returns the log topics as bytes.

newsfragments/3408.misc.rst

@@ -0,0 +1 @@
+Move ``get_abi_input_names`` and ``get_abi_output_names`` to ``eth-utils`` and re-export in ``web3.utils.abi``.

setup.py

@@ -64,8 +64,8 @@
         "eth-abi>=5.0.1",
         "eth-account>=0.12.2",
         "eth-hash[pycryptodome]>=0.5.1",
-        "eth-typing>=4.0.0",
-        "eth-utils>=4.0.0",
+        "eth-typing>=5.0.0b1",
+        "eth-utils>=5.0.0b1",
         "hexbytes>=1.2.0",
         "pydantic>=2.4.0",
         "pywin32>=223;platform_system=='Windows'",