state_override docs and test improvements

Update test to pass None for block identifier so geth ignores it, per note in web3.contract.rst

Update description for `state_override`` param in docs

Add async test for `state_override` in estimate gas

Combine logic for eth_call and eth_estimateGas mungers

Mark not implemented in eth tester

Author: reedsa

docs/web3.eth.rst

@@ -1064,9 +1064,9 @@ The following methods are available on the ``web3.eth`` namespace.
     The ``transaction`` and ``block_identifier`` parameters are handled in the
     same manner as the :meth:`~web3.eth.Eth.send_transaction()` method.
 
-    The ``state_override`` parameter allows gas estimation for cases when there
-    are multiple calls that require a specific state as a side effect of the
-    earlier transaction, such as an `approve` followed by a `transfer` call.
+    The ``state_override`` is useful when there is a chain of transaction calls.
+    It overrides state so that the gas estimate of a transaction is accurate in
+    cases where prior calls produce side effects.
 
     .. code-block:: python
 

tests/integration/test_ethereum_tester.py

@@ -304,6 +304,10 @@ class TestEthereumTesterEthModule(EthModuleTest):
         EthModuleTest.test_eth_call_with_override_param_type_check,
         TypeError,
     )
+    test_eth_estimate_gas_with_override_param_type_check = not_implemented(
+        EthModuleTest.test_eth_estimate_gas_with_override_param_type_check,
+        TypeError,
+    )
     test_eth_create_access_list = not_implemented(
         EthModuleTest.test_eth_create_access_list,
         MethodUnavailable,

web3/_utils/method_formatters.py

@@ -455,14 +455,33 @@ def apply_list_to_array_formatter(formatter: Any) -> Callable[..., Any]:
 estimate_gas_without_block_id: Callable[[Dict[str, Any]], Dict[str, Any]]
 estimate_gas_without_block_id = apply_formatter_at_index(transaction_param_formatter, 0)
 estimate_gas_with_block_id: Callable[
-    [Tuple[Dict[str, Any], Union[str, int]]], Tuple[Dict[str, Any], int]
+    [Tuple[Dict[str, Any], BlockIdentifier]], Tuple[Dict[str, Any], int]
 ]
 estimate_gas_with_block_id = apply_formatters_to_sequence(
     [
         transaction_param_formatter,
         to_hex_if_integer,
     ]
 )
+ESTIMATE_GAS_OVERRIDE_FORMATTERS = {
+    "balance": to_hex_if_integer,
+    "nonce": to_hex_if_integer,
+    "code": to_hex_if_bytes,
+}
+estimate_gas_with_override: Callable[
+    [Tuple[Dict[str, Any], BlockIdentifier, CallOverrideParams]],
+    Tuple[Dict[str, Any], int, Dict[str, Any]],
+] = apply_formatters_to_sequence(
+    [
+        transaction_param_formatter,
+        to_hex_if_integer,
+        lambda val: type_aware_apply_formatters_to_dict_keys_and_values(
+            to_checksum_address,
+            type_aware_apply_formatters_to_dict(ESTIMATE_GAS_OVERRIDE_FORMATTERS),
+            val,
+        ),
+    ]
+)
 
 SIGNED_TX_FORMATTER = {
     "raw": HexBytes,
@@ -531,6 +550,7 @@ def apply_list_to_array_formatter(formatter: Any) -> Callable[..., Any]:
         (
             (is_length(1), estimate_gas_without_block_id),
             (is_length(2), estimate_gas_with_block_id),
+            (is_length(3), estimate_gas_with_override),
         )
     ),
     RPC.eth_sendTransaction: apply_formatter_at_index(transaction_param_formatter, 0),

web3/_utils/module_testing/eth_module.py

@@ -813,6 +813,39 @@ async def test_eth_estimate_gas(
         assert is_integer(gas_estimate)
         assert gas_estimate > 0
 
+    @pytest.mark.asyncio
+    @pytest.mark.parametrize(
+        "params",
+        (
+            {
+                "nonce": 1,  # int
+                "balance": 1,  # int
+                "code": HexStr("0x"),  # HexStr
+                # with state
+                "state": {HexStr(f"0x{'00' * 32}"): HexStr(f"0x{'00' * 32}")},
+            },
+            {
+                "nonce": HexStr("0x1"),  # HexStr
+                "balance": HexStr("0x1"),  # HexStr
+                "code": b"\x00",  # bytes
+                # with stateDiff
+                "stateDiff": {HexStr(f"0x{'00' * 32}"): HexStr(f"0x{'00' * 32}")},
+            },
+        ),
+    )
+    async def test_eth_estimate_gas_with_override_param_type_check(
+        self,
+        async_w3: "AsyncWeb3",
+        async_math_contract: "Contract",
+        params: CallOverrideParams,
+    ) -> None:
+        txn_params: TxParams = {"from": await async_w3.eth.coinbase}
+
+        # assert does not raise
+        await async_w3.eth.estimate_gas(
+            txn_params, None, {async_math_contract.address: params}
+        )
+
     @pytest.mark.asyncio
     async def test_eth_fee_history(self, async_w3: "AsyncWeb3") -> None:
         fee_history = await async_w3.eth.fee_history(1, "latest", [50])
@@ -4189,7 +4222,7 @@ def test_eth_estimate_gas_with_override_param_type_check(
         txn_params: TxParams = {"from": w3.eth.coinbase}
 
         # assert does not raise
-        w3.eth.estimate_gas(txn_params, "latest", {math_contract.address: params})
+        w3.eth.estimate_gas(txn_params, None, {math_contract.address: params})
 
     def test_eth_getBlockByHash(self, w3: "Web3", empty_block: BlockData) -> None:
         block = w3.eth.get_block(empty_block["hash"])

web3/eth/base_eth.py

@@ -3,7 +3,6 @@
     List,
     NoReturn,
     Optional,
-    Sequence,
     Tuple,
     Union,
 )
@@ -94,29 +93,38 @@ def set_gas_price_strategy(
     ) -> None:
         self._gas_price_strategy = gas_price_strategy
 
-    def estimate_gas_munger(
+    def _eth_call_and_estimate_gas_munger(
         self,
         transaction: TxParams,
         block_identifier: Optional[BlockIdentifier] = None,
         state_override: Optional[CallOverride] = None,
-    ) -> Sequence[Union[TxParams, BlockIdentifier, CallOverride]]:
+    ) -> Union[
+        Tuple[TxParams, BlockIdentifier], Tuple[TxParams, BlockIdentifier, CallOverride]
+    ]:
+        # TODO: move to middleware
         if "from" not in transaction and is_checksum_address(self.default_account):
             transaction = assoc(transaction, "from", self.default_account)
 
+        # TODO: move to middleware
         if block_identifier is None:
-            return [transaction]
+            block_identifier = self.default_block
 
         if state_override is None:
-            return [
-                transaction,
-                block_identifier,
-            ]
+            return (transaction, block_identifier)
         else:
-            return [
-                transaction,
-                block_identifier,
-                state_override,
-            ]
+            return (transaction, block_identifier, state_override)
+
+    def estimate_gas_munger(
+        self,
+        transaction: TxParams,
+        block_identifier: Optional[BlockIdentifier] = None,
+        state_override: Optional[CallOverride] = None,
+    ) -> Union[
+        Tuple[TxParams, BlockIdentifier], Tuple[TxParams, BlockIdentifier, CallOverride]
+    ]:
+        return self._eth_call_and_estimate_gas_munger(
+            transaction, block_identifier, state_override
+        )
 
     def get_block_munger(
         self, block_identifier: BlockIdentifier, full_transactions: bool = False
@@ -150,18 +158,9 @@ def call_munger(
     ) -> Union[
         Tuple[TxParams, BlockIdentifier], Tuple[TxParams, BlockIdentifier, CallOverride]
     ]:
-        # TODO: move to middleware
-        if "from" not in transaction and is_checksum_address(self.default_account):
-            transaction = assoc(transaction, "from", self.default_account)
-
-        # TODO: move to middleware
-        if block_identifier is None:
-            block_identifier = self.default_block
-
-        if state_override is None:
-            return (transaction, block_identifier)
-        else:
-            return (transaction, block_identifier, state_override)
+        return self._eth_call_and_estimate_gas_munger(
+            transaction, block_identifier, state_override
+        )
 
     def create_access_list_munger(
         self, transaction: TxParams, block_identifier: Optional[BlockIdentifier] = None