deprecated estimateGas and buildTransaction in v5 contract #2438 (#2459)

Author: dbfreem

docs/contracts.rst

@@ -247,6 +247,11 @@ Each Contract Factory exposes the following methods.
 .. py:classmethod:: Contract.constructor(*args, **kwargs).estimateGas(transaction=None, block_identifier=None)
     :noindex:
 
+    .. warning:: Deprecated: This method is deprecated in favor of :py:meth:`Contract.constructor(*args, **kwargs).estimate_gas`
+
+.. py:classmethod:: Contract.constructor(*args, **kwargs).estimate_gas(transaction=None, block_identifier=None)
+    :noindex:
+
     Estimate gas for constructing and deploying the contract.
 
     This method behaves the same as the
@@ -264,12 +269,18 @@ Each Contract Factory exposes the following methods.
 
     .. code-block:: python
 
-        >>> token_contract.constructor(web3.eth.coinbase, 12345).estimateGas()
+        >>> token_contract.constructor(web3.eth.coinbase, 12345).estimate_gas()
         12563
 
 .. py:classmethod:: Contract.constructor(*args, **kwargs).buildTransaction(transaction=None)
     :noindex:
 
+    .. warning:: Deprecated: This method is deprecated in favor of :py:meth:`Contract.constructor(*args, **kwargs).build_transaction`
+
+
+.. py:classmethod:: Contract.constructor(*args, **kwargs).build_transaction(transaction=None)
+    :noindex:
+
     Construct the contract deploy transaction bytecode data.
 
     If the contract takes constructor parameters they should be provided as
@@ -286,7 +297,7 @@ Each Contract Factory exposes the following methods.
         'gasPrice': w3.eth.gas_price,
         'chainId': None
         }
-        >>> contract_data = token_contract.constructor(web3.eth.coinbase, 12345).buildTransaction(transaction)
+        >>> contract_data = token_contract.constructor(web3.eth.coinbase, 12345).build_transaction(transaction)
         >>> web3.eth.send_transaction(contract_data)
 
 .. _contract_createFilter:
@@ -835,14 +846,18 @@ Methods
 
 .. py:method:: ContractFunction.estimateGas(transaction, block_identifier=None)
 
+    .. warning:: Deprecated: This method is deprecated in favor of :class:`~estimate_gas`
+
+.. py:method:: ContractFunction.estimate_gas(transaction, block_identifier=None)
+
     Call a contract function, executing the transaction locally using the
     ``eth_call`` API.  This will not create a new public transaction.
 
     Refer to the following invocation:
 
     .. code-block:: python
 
-        myContract.functions.myMethod(*args, **kwargs).estimateGas(transaction)
+        myContract.functions.myMethod(*args, **kwargs).estimate_gas(transaction)
 
     This method behaves the same as the :py:meth:`ContractFunction.transact` method,
     with transaction details being passed into the end portion of the
@@ -853,7 +868,7 @@ Methods
 
     .. code-block:: python
 
-        >>> my_contract.functions.multiply7(3).estimateGas()
+        >>> my_contract.functions.multiply7(3).estimate_gas()
         42650
 
     .. note::
@@ -862,14 +877,18 @@ Methods
         nodes would result in an error like:  ``ValueError: {'code': -32602, 'message': 'too many arguments, want at most 1'}``
 
 .. py:method:: ContractFunction.buildTransaction(transaction)
+  
+    .. warning:: Deprecated: This method is deprecated in favor of :class:`~build_transaction`
+
+.. py:method:: ContractFunction.build_transaction(transaction)
 
     Builds a transaction dictionary based on the contract function call specified.
 
     Refer to the following invocation:
 
     .. code-block:: python
 
-        myContract.functions.myMethod(*args, **kwargs).buildTransaction(transaction)
+        myContract.functions.myMethod(*args, **kwargs).build_transaction(transaction)
 
     This method behaves the same as the :py:meth:`Contract.transact` method,
     with transaction details being passed into the end portion of the
@@ -881,15 +900,15 @@ Methods
 
         .. code-block:: python
 
-            >>> math_contract.functions.increment(5).buildTransaction({'nonce': 10})
+            >>> math_contract.functions.increment(5).build_transaction({'nonce': 10})
 
         You may use :meth:`~web3.eth.Eth.getTransactionCount` to get the current nonce
         for an account. Therefore a shortcut for producing a transaction dictionary with
         nonce included looks like:
 
         .. code-block:: python
 
-            >>> math_contract.functions.increment(5).buildTransaction({'nonce': web3.eth.get_transaction_count('0xF5...')})
+            >>> math_contract.functions.increment(5).build_transaction({'nonce': web3.eth.get_transaction_count('0xF5...')})
 
     Returns a transaction dictionary. This transaction dictionary can then be sent using
     :meth:`~web3.eth.Eth.send_transaction`.
@@ -899,7 +918,7 @@ Methods
 
     .. code-block:: python
 
-        >>> math_contract.functions.increment(5).buildTransaction({'maxFeePerGas': 2000000000, 'maxPriorityFeePerGas': 1000000000})
+        >>> math_contract.functions.increment(5).build_transaction({'maxFeePerGas': 2000000000, 'maxPriorityFeePerGas': 1000000000})
         {
             'to': '0x6Bc272FCFcf89C14cebFC57B8f1543F5137F97dE',
             'data': '0x7cf5dab00000000000000000000000000000000000000000000000000000000000000005',

docs/examples.rst

@@ -361,7 +361,7 @@ The following example demonstrates a few things:
 
     store_var_contract = w3.eth.contract(address=address, abi=contract_interface["abi"])
 
-    gas_estimate = store_var_contract.functions.setVar(255).estimateGas()
+    gas_estimate = store_var_contract.functions.setVar(255).estimate_gas()
     print(f'Gas estimate to transact with setVar: {gas_estimate}')
 
     if gas_estimate < 100000:
@@ -674,7 +674,7 @@ Just remember that you have to sign all transactions locally, as infura does not
 
 .. code-block:: python
 
-    transaction = contract.functions.function_Name(params).buildTransaction()
+    transaction = contract.functions.function_Name(params).build_transaction()
     transaction.update({ 'gas' : appropriate_gas_amount })
     transaction.update({ 'nonce' : w3.eth.get_transaction_count('Your_Wallet_Address') })
     signed_tx = w3.eth.account.sign_transaction(transaction, private_key)

docs/web3.eth.account.rst

@@ -303,7 +303,7 @@ To sign a transaction locally that will invoke a smart contract:
     >>> unicorn_txn = unicorns.functions.transfer(
     ...     '0xfB6916095ca1df60bB79Ce92cE3Ea74c37c5d359',
     ...     1,
-    ... ).buildTransaction({
+    ... ).build_transaction({
     ...     'chainId': 1,
     ...     'gas': 70000,
     ...     'maxFeePerGas': w3.toWei('2', 'gwei'),

newsfragments/2459.feature.rst

@@ -0,0 +1,2 @@
+Deprecated ``buildTransaction`` and ``estimateGas`` in contract.py v5,
+in favor of ``estimate_gas`` and ``build_transaction``

tests/core/contracts/conftest.py

@@ -1008,7 +1008,7 @@ def invoke_contract(api_call_desig='call',
                     func_args=[],
                     func_kwargs={},
                     tx_params={}):
-    allowable_call_desig = ['call', 'transact', 'estimateGas', 'buildTransaction']
+    allowable_call_desig = ['call', 'transact', 'estimate_gas', 'build_transaction']
     if api_call_desig not in allowable_call_desig:
         raise ValueError("allowable_invoke_method must be one of: %s" % allowable_call_desig)
 
@@ -1029,10 +1029,10 @@ def call(request):
 
 
 @pytest.fixture
-def estimateGas(request):
-    return functools.partial(invoke_contract, api_call_desig='estimateGas')
+def estimate_gas(request):
+    return functools.partial(invoke_contract, api_call_desig='estimate_gas')
 
 
 @pytest.fixture
-def buildTransaction(request):
-    return functools.partial(invoke_contract, api_call_desig='buildTransaction')
+def build_transaction(request):
+    return functools.partial(invoke_contract, api_call_desig='build_transaction')

tests/core/contracts/test_contract_ambiguous_functions.py

@@ -181,8 +181,8 @@ def test_contract_function_methods(string_contract):
     get_value_func = string_contract.get_function_by_signature('getValue()')
     assert isinstance(set_value_func('Hello').transact(), HexBytes)
     assert get_value_func().call() == 'Hello'
-    assert isinstance(set_value_func('Hello World').estimateGas(), int)
-    assert isinstance(set_value_func('Hello World').buildTransaction(), dict)
+    assert isinstance(set_value_func('Hello World').estimate_gas(), int)
+    assert isinstance(set_value_func('Hello World').build_transaction(), dict)
 
 
 def test_diff_between_fn_and_fn_called(string_contract):

tests/core/contracts/test_contract_buildTransaction.py renamed to tests/core/contracts/test_contract_build_transaction.py

@@ -45,9 +45,9 @@ def payable_tester_contract(web3, PayableTesterContract, address_conversion_func
 def test_build_transaction_not_paying_to_nonpayable_function(
         web3,
         payable_tester_contract,
-        buildTransaction):
-    txn = buildTransaction(contract=payable_tester_contract,
-                           contract_function='doNoValueCall')
+        build_transaction):
+    txn = build_transaction(contract=payable_tester_contract,
+                            contract_function='doNoValueCall')
     assert dissoc(txn, 'gas') == {
         'to': payable_tester_contract.address,
         'data': '0xe4cb8f5c',
@@ -61,15 +61,15 @@ def test_build_transaction_not_paying_to_nonpayable_function(
 def test_build_transaction_paying_to_nonpayable_function(
         web3,
         payable_tester_contract,
-        buildTransaction):
+        build_transaction):
     with pytest.raises(ValidationError):
-        buildTransaction(contract=payable_tester_contract,
-                         contract_function='doNoValueCall',
-                         tx_params={'value': 1})
+        build_transaction(contract=payable_tester_contract,
+                          contract_function='doNoValueCall',
+                          tx_params={'value': 1})
 
 
-def test_build_transaction_with_contract_no_arguments(web3, math_contract, buildTransaction):
-    txn = buildTransaction(contract=math_contract, contract_function='increment')
+def test_build_transaction_with_contract_no_arguments(web3, math_contract, build_transaction):
+    txn = build_transaction(contract=math_contract, contract_function='increment')
     assert dissoc(txn, 'gas') == {
         'to': math_contract.address,
         'data': '0xd09de08a',
@@ -81,7 +81,7 @@ def test_build_transaction_with_contract_no_arguments(web3, math_contract, build
 
 
 def test_build_transaction_with_contract_fallback_function(web3, fallback_function_contract):
-    txn = fallback_function_contract.fallback.buildTransaction()
+    txn = fallback_function_contract.fallback.build_transaction()
     assert dissoc(txn, 'gas') == {
         'to': fallback_function_contract.address,
         'data': '0x',
@@ -96,8 +96,8 @@ def test_build_transaction_with_contract_class_method(
         web3,
         MathContract,
         math_contract,
-        buildTransaction):
-    txn = buildTransaction(
+        build_transaction):
+    txn = build_transaction(
         contract=MathContract,
         contract_function='increment',
         tx_params={'to': math_contract.address},
@@ -115,8 +115,8 @@ def test_build_transaction_with_contract_class_method(
 def test_build_transaction_with_contract_default_account_is_set(
         web3,
         math_contract,
-        buildTransaction):
-    txn = buildTransaction(contract=math_contract, contract_function='increment')
+        build_transaction):
+    txn = build_transaction(contract=math_contract, contract_function='increment')
     assert dissoc(txn, 'gas') == {
         'to': math_contract.address,
         'data': '0xd09de08a',
@@ -127,11 +127,11 @@ def test_build_transaction_with_contract_default_account_is_set(
     }
 
 
-def test_build_transaction_with_gas_price_strategy_set(web3, math_contract, buildTransaction):
+def test_build_transaction_with_gas_price_strategy_set(web3, math_contract, build_transaction):
     def my_gas_price_strategy(web3, transaction_params):
         return 5
     web3.eth.set_gas_price_strategy(my_gas_price_strategy)
-    txn = buildTransaction(contract=math_contract, contract_function='increment')
+    txn = build_transaction(contract=math_contract, contract_function='increment')
     assert dissoc(txn, 'gas') == {
         'to': math_contract.address,
         'data': '0xd09de08a',
@@ -143,20 +143,20 @@ def my_gas_price_strategy(web3, transaction_params):
 
 def test_build_transaction_with_contract_data_supplied_errors(web3,
                                                               math_contract,
-                                                              buildTransaction):
+                                                              build_transaction):
     with pytest.raises(ValueError):
-        buildTransaction(contract=math_contract,
-                         contract_function='increment',
-                         tx_params={'data': '0x000'})
+        build_transaction(contract=math_contract,
+                          contract_function='increment',
+                          tx_params={'data': '0x000'})
 
 
 def test_build_transaction_with_contract_to_address_supplied_errors(web3,
                                                                     math_contract,
-                                                                    buildTransaction):
+                                                                    build_transaction):
     with pytest.raises(ValueError):
-        buildTransaction(contract=math_contract,
-                         contract_function='increment',
-                         tx_params={'to': '0xb2930B35844a230f00E51431aCAe96Fe543a0347'})
+        build_transaction(contract=math_contract,
+                          contract_function='increment',
+                          tx_params={'to': '0xb2930B35844a230f00E51431aCAe96Fe543a0347'})
 
 
 @pytest.mark.parametrize(
@@ -219,19 +219,24 @@ def test_build_transaction_with_contract_with_arguments(web3, skip_if_testrpc, m
                                                         method_kwargs,
                                                         expected,
                                                         skip_testrpc,
-                                                        buildTransaction):
+                                                        build_transaction):
     if skip_testrpc:
         skip_if_testrpc(web3)
 
-    txn = buildTransaction(contract=math_contract,
-                           contract_function='increment',
-                           func_args=method_args,
-                           func_kwargs=method_kwargs,
-                           tx_params=transaction_args)
+    txn = build_transaction(contract=math_contract,
+                            contract_function='increment',
+                            func_args=method_args,
+                            func_kwargs=method_kwargs,
+                            tx_params=transaction_args)
     expected['to'] = math_contract.address
     assert txn is not None
     if 'gas' in transaction_args:
         assert txn['gas'] == transaction_args['gas']
     else:
         assert 'gas' in txn
     assert dissoc(txn, 'gas') == expected
+
+
+def test_buildTransaction_deprecated(math_contract):
+    with pytest.warns(DeprecationWarning, match="deprecated in favor of build_transaction"):
+        math_contract.functions.counter().buildTransaction()

tests/core/contracts/test_contract_class_construction.py

@@ -53,4 +53,4 @@ def test_error_to_call_non_existent_fallback(web3,
         bytecode_runtime=MATH_RUNTIME,
     )
     with pytest.raises(FallbackNotFound):
-        math_contract.fallback.estimateGas()
+        math_contract.fallback.estimate_gas()