web3 7.0.0b2__py3-none-any.whl → 7.7.0__py3-none-any.whl

web3/contract/utils.py

@@ -9,21 +9,33 @@ from typing import (
     Tuple,
     Type,
     Union,
+    cast,
 )
 
 from eth_abi.exceptions import (
     DecodingError,
 )
 from eth_typing import (
+    ABI,
+    ABICallable,
+    ABIFunction,
     ChecksumAddress,
+    TypeStr,
+)
+from eth_utils.abi import (
+    abi_to_signature,
+    filter_abi_by_type,
+    get_abi_output_types,
+)
+from eth_utils.toolz import (
+    compose,
+    curry,
 )
 from hexbytes import (
     HexBytes,
 )
 
 from web3._utils.abi import (
-    filter_by_type,
-    get_abi_output_types,
     map_abi_data,
     named_tree,
     recursive_dict_to_namedtuple,
@@ -31,8 +43,10 @@ from web3._utils.abi import (
 from web3._utils.async_transactions import (
     async_fill_transaction_defaults,
 )
+from web3._utils.compat import (
+    TypeAlias,
+)
 from web3._utils.contracts import (
-    find_matching_fn_abi,
     prepare_transaction,
 )
 from web3._utils.normalizers import (
@@ -43,35 +57,79 @@ from web3._utils.transactions import (
 )
 from web3.exceptions import (
     BadFunctionCallOutput,
+    Web3ValueError,
 )
 from web3.types import (
-    ABI,
-    ABIFunction,
+    ABIElementIdentifier,
     BlockIdentifier,
-    FunctionIdentifier,
+    RPCEndpoint,
     StateOverride,
+    TContractEvent,
     TContractFn,
     TxParams,
 )
+from web3.utils.abi import (
+    get_abi_element,
+)
 
 if TYPE_CHECKING:
     from web3 import (  # noqa: F401
         AsyncWeb3,
         Web3,
     )
+    from web3.providers.persistent import (  # noqa: F401
+        PersistentConnectionProvider,
+    )
 
 ACCEPTABLE_EMPTY_STRINGS = ["0x", b"0x", "", b""]
 
 
+@curry
+def format_contract_call_return_data_curried(
+    async_w3: Union["AsyncWeb3", "Web3"],
+    decode_tuples: bool,
+    fn_abi: ABICallable,
+    abi_element_identifier: ABIElementIdentifier,
+    normalizers: Tuple[Callable[..., Any], ...],
+    output_types: Sequence[TypeStr],
+    return_data: Any,
+) -> Any:
+    """
+    Helper function for formatting contract call return data for batch requests. Curry
+    with all arguments except `return_data` and process `return_data` once it is
+    available.
+    """
+    try:
+        output_data = async_w3.codec.decode(output_types, return_data)
+    except DecodingError as e:
+        msg = (
+            f"Could not decode contract function call to {abi_element_identifier} "
+            f"with return data: {str(return_data)}, output_types: {output_types}"
+        )
+        raise BadFunctionCallOutput(msg) from e
+
+    _normalizers = itertools.chain(
+        BASE_RETURN_NORMALIZERS,
+        normalizers,
+    )
+    normalized_data = map_abi_data(_normalizers, output_types, output_data)
+
+    if decode_tuples and fn_abi["type"] == "function":
+        decoded = named_tree(fn_abi["outputs"], normalized_data)
+        normalized_data = recursive_dict_to_namedtuple(decoded)
+
+    return normalized_data[0] if len(normalized_data) == 1 else normalized_data
+
+
 def call_contract_function(
     w3: "Web3",
     address: ChecksumAddress,
     normalizers: Tuple[Callable[..., Any], ...],
-    function_identifier: FunctionIdentifier,
+    abi_element_identifier: ABIElementIdentifier,
     transaction: TxParams,
     block_id: Optional[BlockIdentifier] = None,
     contract_abi: Optional[ABI] = None,
-    fn_abi: Optional[ABIFunction] = None,
+    abi_callable: Optional[ABICallable] = None,
     state_override: Optional[StateOverride] = None,
     ccip_read_enabled: Optional[bool] = None,
     decode_tuples: Optional[bool] = False,
@@ -85,9 +143,9 @@ def call_contract_function(
     call_transaction = prepare_transaction(
         address,
         w3,
-        fn_identifier=function_identifier,
+        abi_element_identifier=abi_element_identifier,
         contract_abi=contract_abi,
-        fn_abi=fn_abi,
+        abi_callable=abi_callable,
         transaction=transaction,
         fn_args=args,
         fn_kwargs=kwargs,
@@ -100,12 +158,50 @@ def call_contract_function(
         ccip_read_enabled=ccip_read_enabled,
     )
 
-    if fn_abi is None:
-        fn_abi = find_matching_fn_abi(
-            contract_abi, w3.codec, function_identifier, args, kwargs
+    if abi_callable is None:
+        abi_callable = cast(
+            ABIFunction,
+            get_abi_element(
+                contract_abi,
+                abi_element_identifier,
+                *args,
+                abi_codec=w3.codec,
+                **kwargs,
+            ),
         )
 
-    output_types = get_abi_output_types(fn_abi)
+    # get the output types, which only exist for function types
+    output_types = []
+    if abi_callable["type"] == "function":
+        output_types = get_abi_output_types(abi_callable)
+
+    provider = w3.provider
+    if hasattr(provider, "_is_batching") and provider._is_batching:
+        BatchingReturnData: TypeAlias = Tuple[Tuple[RPCEndpoint, Any], Tuple[Any, ...]]
+        request_information = tuple(cast(BatchingReturnData, return_data))
+        method_and_params = request_information[0]
+
+        # append return data formatting to result formatters
+        current_response_formatters = request_information[1]
+        current_result_formatters = current_response_formatters[0]
+        updated_result_formatters = compose(
+            # contract call return data formatter
+            format_contract_call_return_data_curried(
+                w3,
+                decode_tuples,
+                abi_callable,
+                abi_element_identifier,
+                normalizers,
+                output_types,
+            ),
+            current_result_formatters,
+        )
+        response_formatters = (
+            updated_result_formatters,  # result formatters
+            current_response_formatters[1],  # error formatters
+            current_response_formatters[2],  # null result formatters
+        )
+        return (method_and_params, response_formatters)
 
     try:
         output_data = w3.codec.decode(output_types, return_data)
@@ -123,7 +219,7 @@ def call_contract_function(
             )
         else:
             msg = (
-                f"Could not decode contract function call to {function_identifier} "
+                f"Could not decode contract function call to {abi_element_identifier} "
                 f"with return data: {str(return_data)}, output_types: {output_types}"
             )
         raise BadFunctionCallOutput(msg) from e
@@ -134,8 +230,8 @@ def call_contract_function(
     )
     normalized_data = map_abi_data(_normalizers, output_types, output_data)
 
-    if decode_tuples:
-        decoded = named_tree(fn_abi["outputs"], normalized_data)
+    if decode_tuples and abi_callable["type"] == "function":
+        decoded = named_tree(abi_callable["outputs"], normalized_data)
         normalized_data = recursive_dict_to_namedtuple(decoded)
 
     if len(normalized_data) == 1:
@@ -147,7 +243,7 @@ def call_contract_function(
 def transact_with_contract_function(
     address: ChecksumAddress,
     w3: "Web3",
-    function_name: Optional[FunctionIdentifier] = None,
+    abi_element_identifier: Optional[ABIElementIdentifier] = None,
     transaction: Optional[TxParams] = None,
     contract_abi: Optional[ABI] = None,
     fn_abi: Optional[ABIFunction] = None,
@@ -161,10 +257,10 @@ def transact_with_contract_function(
     transact_transaction = prepare_transaction(
         address,
         w3,
-        fn_identifier=function_name,
+        abi_element_identifier=abi_element_identifier,
         contract_abi=contract_abi,
         transaction=transaction,
-        fn_abi=fn_abi,
+        abi_callable=fn_abi,
         fn_args=args,
         fn_kwargs=kwargs,
     )
@@ -176,7 +272,7 @@ def transact_with_contract_function(
 def estimate_gas_for_function(
     address: ChecksumAddress,
     w3: "Web3",
-    fn_identifier: Optional[FunctionIdentifier] = None,
+    abi_element_identifier: Optional[ABIElementIdentifier] = None,
     transaction: Optional[TxParams] = None,
     contract_abi: Optional[ABI] = None,
     fn_abi: Optional[ABIFunction] = None,
@@ -185,7 +281,8 @@ def estimate_gas_for_function(
     *args: Any,
     **kwargs: Any,
 ) -> int:
-    """Estimates gas cost a function call would take.
+    """
+    Estimates gas cost a function call would take.
 
     Don't call this directly, instead use :meth:`Contract.estimate_gas`
     on your contract instance.
@@ -193,9 +290,9 @@ def estimate_gas_for_function(
     estimate_transaction = prepare_transaction(
         address,
         w3,
-        fn_identifier=fn_identifier,
+        abi_element_identifier=abi_element_identifier,
         contract_abi=contract_abi,
-        fn_abi=fn_abi,
+        abi_callable=fn_abi,
         transaction=transaction,
         fn_args=args,
         fn_kwargs=kwargs,
@@ -207,14 +304,15 @@ def estimate_gas_for_function(
 def build_transaction_for_function(
     address: ChecksumAddress,
     w3: "Web3",
-    function_name: Optional[FunctionIdentifier] = None,
+    abi_element_identifier: Optional[ABIElementIdentifier] = None,
     transaction: Optional[TxParams] = None,
     contract_abi: Optional[ABI] = None,
     fn_abi: Optional[ABIFunction] = None,
     *args: Any,
     **kwargs: Any,
 ) -> TxParams:
-    """Builds a dictionary with the fields required to make the given transaction
+    """
+    Builds a dictionary with the fields required to make the given transaction
 
     Don't call this directly, instead use :meth:`Contract.build_transaction`
     on your contract instance.
@@ -222,9 +320,9 @@ def build_transaction_for_function(
     prepared_transaction = prepare_transaction(
         address,
         w3,
-        fn_identifier=function_name,
+        abi_element_identifier=abi_element_identifier,
         contract_abi=contract_abi,
-        fn_abi=fn_abi,
+        abi_callable=fn_abi,
         transaction=transaction,
         fn_args=args,
         fn_kwargs=kwargs,
@@ -242,14 +340,20 @@ def find_functions_by_identifier(
     callable_check: Callable[..., Any],
     function_type: Type[TContractFn],
 ) -> List[TContractFn]:
-    fns_abi = filter_by_type("function", contract_abi)
+    """
+    Given a contract ABI, return a list of TContractFunction instances.
+    """
+    fns_abi = sorted(
+        filter_abi_by_type("function", contract_abi),
+        key=lambda fn: (fn["name"], len(fn.get("inputs", []))),
+    )
     return [
         function_type.factory(
-            fn_abi["name"],
+            abi_to_signature(fn_abi),
             w3=w3,
             contract_abi=contract_abi,
             address=address,
-            function_identifier=fn_abi["name"],
+            abi_element_identifier=abi_to_signature(fn_abi),
             abi=fn_abi,
         )
         for fn_abi in fns_abi
@@ -260,15 +364,59 @@ def find_functions_by_identifier(
 def get_function_by_identifier(
     fns: Sequence[TContractFn], identifier: str
 ) -> TContractFn:
+    """
+    Check that the provided list of TContractFunction instances contains one element and
+    return it.
+    """
     if len(fns) > 1:
-        raise ValueError(
+        raise Web3ValueError(
             f"Found multiple functions with matching {identifier}. " f"Found: {fns!r}"
         )
     elif len(fns) == 0:
-        raise ValueError(f"Could not find any function with matching {identifier}")
+        raise Web3ValueError(f"Could not find any function with matching {identifier}")
     return fns[0]
 
 
+def find_events_by_identifier(
+    contract_abi: ABI,
+    w3: Union["Web3", "AsyncWeb3"],
+    address: ChecksumAddress,
+    callable_check: Callable[..., Any],
+    event_type: Type[TContractEvent],
+) -> List[TContractEvent]:
+    """
+    Given a contract ABI, return a list of TContractEvent instances.
+    """
+    event_abis = filter_abi_by_type("event", contract_abi)
+    return [
+        event_type.factory(
+            event_abi["name"],
+            w3=w3,
+            contract_abi=contract_abi,
+            address=address,
+            abi=event_abi,
+        )
+        for event_abi in event_abis
+        if callable_check(event_abi)
+    ]
+
+
+def get_event_by_identifier(
+    events: Sequence[TContractEvent], identifier: str
+) -> TContractEvent:
+    """
+    Check that the provided list of TContractEvent instances contains one element and
+    return it.
+    """
+    if len(events) > 1:
+        raise Web3ValueError(
+            f"Found multiple events with matching {identifier}. " f"Found: {events!r}"
+        )
+    elif len(events) == 0:
+        raise Web3ValueError(f"Could not find any event with matching {identifier}")
+    return events[0]
+
+
 # --- async --- #
 
 
@@ -276,7 +424,7 @@ async def async_call_contract_function(
     async_w3: "AsyncWeb3",
     address: ChecksumAddress,
     normalizers: Tuple[Callable[..., Any], ...],
-    function_identifier: FunctionIdentifier,
+    abi_element_identifier: ABIElementIdentifier,
     transaction: TxParams,
     block_id: Optional[BlockIdentifier] = None,
     contract_abi: Optional[ABI] = None,
@@ -294,9 +442,9 @@ async def async_call_contract_function(
     call_transaction = prepare_transaction(
         address,
         async_w3,
-        fn_identifier=function_identifier,
+        abi_element_identifier=abi_element_identifier,
         contract_abi=contract_abi,
-        fn_abi=fn_abi,
+        abi_callable=fn_abi,
         transaction=transaction,
         fn_args=args,
         fn_kwargs=kwargs,
@@ -310,11 +458,60 @@ async def async_call_contract_function(
     )
 
     if fn_abi is None:
-        fn_abi = find_matching_fn_abi(
-            contract_abi, async_w3.codec, function_identifier, args, kwargs
+        fn_abi = cast(
+            ABIFunction,
+            get_abi_element(
+                contract_abi,
+                abi_element_identifier,
+                *args,
+                abi_codec=async_w3.codec,
+                **kwargs,
+            ),
         )
 
-    output_types = get_abi_output_types(fn_abi)
+    # get the output types, which only exist for function types
+    output_types = []
+    if fn_abi["type"] == "function":
+        output_types = get_abi_output_types(fn_abi)
+
+    if async_w3.provider._is_batching:
+        contract_call_return_data_formatter = format_contract_call_return_data_curried(
+            async_w3,
+            decode_tuples,
+            fn_abi,
+            abi_element_identifier,
+            normalizers,
+            output_types,
+        )
+        if async_w3.provider.has_persistent_connection:
+            # get the current request id
+            provider = cast("PersistentConnectionProvider", async_w3.provider)
+            current_request_id = provider._batch_request_counter - 1
+            provider._request_processor.append_result_formatter_for_request(
+                current_request_id, contract_call_return_data_formatter
+            )
+        else:
+            BatchingReturnData: TypeAlias = Tuple[
+                Tuple[RPCEndpoint, Any], Tuple[Any, ...]
+            ]
+            request_information = tuple(cast(BatchingReturnData, return_data))
+            method_and_params = request_information[0]
+
+            # append return data formatter to result formatters
+            current_response_formatters = request_information[1]
+            current_result_formatters = current_response_formatters[0]
+            updated_result_formatters = compose(
+                contract_call_return_data_formatter,
+                current_result_formatters,
+            )
+            response_formatters = (
+                updated_result_formatters,  # result formatters
+                current_response_formatters[1],  # error formatters
+                current_response_formatters[2],  # null result formatters
+            )
+            return (method_and_params, response_formatters)
+
+        return return_data
 
     try:
         output_data = async_w3.codec.decode(output_types, return_data)
@@ -332,7 +529,7 @@ async def async_call_contract_function(
             )
         else:
             msg = (
-                f"Could not decode contract function call to {function_identifier} "
+                f"Could not decode contract function call to {abi_element_identifier} "
                 f"with return data: {str(return_data)}, output_types: {output_types}"
             )
         raise BadFunctionCallOutput(msg) from e
@@ -347,16 +544,13 @@ async def async_call_contract_function(
         decoded = named_tree(fn_abi["outputs"], normalized_data)
         normalized_data = recursive_dict_to_namedtuple(decoded)
 
-    if len(normalized_data) == 1:
-        return normalized_data[0]
-    else:
-        return normalized_data
+    return normalized_data[0] if len(normalized_data) == 1 else normalized_data
 
 
 async def async_transact_with_contract_function(
     address: ChecksumAddress,
     async_w3: "AsyncWeb3",
-    function_name: Optional[FunctionIdentifier] = None,
+    abi_element_identifier: Optional[ABIElementIdentifier] = None,
     transaction: Optional[TxParams] = None,
     contract_abi: Optional[ABI] = None,
     fn_abi: Optional[ABIFunction] = None,
@@ -370,10 +564,10 @@ async def async_transact_with_contract_function(
     transact_transaction = prepare_transaction(
         address,
         async_w3,
-        fn_identifier=function_name,
+        abi_element_identifier=abi_element_identifier,
         contract_abi=contract_abi,
         transaction=transaction,
-        fn_abi=fn_abi,
+        abi_callable=fn_abi,
         fn_args=args,
         fn_kwargs=kwargs,
     )
@@ -385,7 +579,7 @@ async def async_transact_with_contract_function(
 async def async_estimate_gas_for_function(
     address: ChecksumAddress,
     async_w3: "AsyncWeb3",
-    fn_identifier: Optional[FunctionIdentifier] = None,
+    abi_element_identifier: Optional[ABIElementIdentifier] = None,
     transaction: Optional[TxParams] = None,
     contract_abi: Optional[ABI] = None,
     fn_abi: Optional[ABIFunction] = None,
@@ -394,7 +588,8 @@ async def async_estimate_gas_for_function(
     *args: Any,
     **kwargs: Any,
 ) -> int:
-    """Estimates gas cost a function call would take.
+    """
+    Estimates gas cost a function call would take.
 
     Don't call this directly, instead use :meth:`Contract.estimate_gas`
     on your contract instance.
@@ -402,9 +597,9 @@ async def async_estimate_gas_for_function(
     estimate_transaction = prepare_transaction(
         address,
         async_w3,
-        fn_identifier=fn_identifier,
+        abi_element_identifier=abi_element_identifier,
         contract_abi=contract_abi,
-        fn_abi=fn_abi,
+        abi_callable=fn_abi,
         transaction=transaction,
         fn_args=args,
         fn_kwargs=kwargs,
@@ -418,14 +613,15 @@ async def async_estimate_gas_for_function(
 async def async_build_transaction_for_function(
     address: ChecksumAddress,
     async_w3: "AsyncWeb3",
-    function_name: Optional[FunctionIdentifier] = None,
+    abi_element_identifier: Optional[ABIElementIdentifier] = None,
     transaction: Optional[TxParams] = None,
     contract_abi: Optional[ABI] = None,
     fn_abi: Optional[ABIFunction] = None,
     *args: Any,
     **kwargs: Any,
 ) -> TxParams:
-    """Builds a dictionary with the fields required to make the given transaction
+    """
+    Builds a dictionary with the fields required to make the given transaction
 
     Don't call this directly, instead use :meth:`Contract.build_transaction`
     on your contract instance.
@@ -433,9 +629,9 @@ async def async_build_transaction_for_function(
     prepared_transaction = prepare_transaction(
         address,
         async_w3,
-        fn_identifier=function_name,
+        abi_element_identifier=abi_element_identifier,
         contract_abi=contract_abi,
-        fn_abi=fn_abi,
+        abi_callable=fn_abi,
         transaction=transaction,
         fn_args=args,
         fn_kwargs=kwargs,