Update docs before 0.19.0 release (#1275)

* Update migration guide

* Update docs

* Add info about added versioned classes

* Apply suggestions from code review

Co-authored-by: Wojciech Szymczyk <wojciech.szymczyk@swmansion.com>

* Improve clarity of Fees section in Using Existing Contract chapter

* Fix hyperlinks to API documentation

* Add transaction fee section

* Apply suggestions from code review

Co-authored-by: Wojciech Szymczyk <wojciech.szymczyk@swmansion.com>

* Improve auto estimation warning

* Update auto estimation warning message

* Fix failing test

* Apply suggestions from code review

Co-authored-by: Maksim Zdobnikau <43750648+DelevoXDG@users.noreply.github.com>

* Address review feedback

* Update warning under `Fees` section

Co-authored-by: Maksim Zdobnikau <43750648+DelevoXDG@users.noreply.github.com>

* Add info about auto fee estimation under Fees

---------

Co-authored-by: Wojciech Szymczyk <wojciech.szymczyk@swmansion.com>
Co-authored-by: Maksim Zdobnikau <43750648+DelevoXDG@users.noreply.github.com>

Author: 3 people

docs/account_creation.rst

@@ -32,6 +32,6 @@ Here is step by step example:
 
     If you are experiencing transaction failures with ``FEE_TRANSFER_FAILURE``
     make sure that the address you are trying to deploy is prefunded with enough
-    tokens, and verify that ``max_fee`` argument
-    in :meth:`~starknet_py.net.account.account.Account.sign_deploy_account_transaction` is set
+    tokens, and verify that ``max_fee`` argument in :meth:`~starknet_py.net.account.account.Account.sign_deploy_account_v1`
+    or ``l1_resource_bounds`` argument in :meth:`~starknet_py.net.account.account.Account.sign_deploy_account_v3` is set
     to a high enough value.

docs/development.rst

@@ -25,11 +25,11 @@ Below is the command you can use to do this, designed for compatibility with the
 
 .. code-block:: bash
 
-    STARKNET_VERSION="0.12.3" RPC_SPEC_VERSION="0.5.1" \
+    STARKNET_VERSION="0.13.0" RPC_SPEC_VERSION="0.6.0" \
     cargo install \
     --locked \
     --git https://github.com/0xSpaceShard/starknet-devnet-rs.git \
-    --rev 78527de
+    --rev 1bd447d
 
 If you choose to install `starknet-devnet-rs <https://github.com/0xSpaceShard/starknet-devnet-rs>`_ using a different method, please make sure to add the executable ``starknet-devnet`` to your ``PATH`` environment variable.
 

docs/guide/account_and_client.rst

@@ -4,16 +4,41 @@ Account and Client
 Executing transactions
 ----------------------
 
-To execute transactions on Starknet, use :meth:`~starknet_py.net.account.account.Account.execute` method from :ref:`Account` interface.
+To execute transactions on Starknet, use :meth:`~starknet_py.net.account.account.Account.execute_v1` or :meth:`~starknet_py.net.account.account.Account.execute_v3` methods from :ref:`Account` interface.
+These methods will send :class:`~starknet_py.net.models.InvokeV1` and :class:`~starknet_py.net.models.InvokeV3` transactions respectively. To read about differences between transaction versions please visit `transaction types <https://docs.starknet.io/documentation/architecture_and_concepts/Network_Architecture/transactions>`_ from the Starknet docs.
 
 .. codesnippet:: ../../starknet_py/tests/e2e/docs/guide/test_executing_transactions.py
     :language: python
     :dedent: 4
 
+Transaction Fee
+---------------
+
+All methods within the :ref:`Account` that involve on-chain modifications require either specifying a maximum transaction fee or using auto estimation.
+In the case of V1 and V2 transactions, the transaction fee, denoted in Wei, is configured by the ``max_fee`` parameter.
+For V3 transactions, however, the fee is expressed in Fri and is determined by the ``l1_resource_bounds`` parameter.
+To enable auto estimation, set the ``auto_estimate`` parameter to ``True``.
+
+.. code-block:: python
+
+    resp = await account.execute_v1(calls=call, auto_estimate=True)
+
+.. warning::
+
+    It is strongly discouraged to use automatic fee estimation in production code as it may lead to an unexpectedly high fee.
+
+The returned estimated fee is multiplied by ``1.5`` for V1 and V2 transactions to mitigate fluctuations in price.
+For V3 transactions, ``max_amount`` and ``max_price_per_unit`` are scaled by ``1.1`` and ``1.5`` respectively.
+
+
+.. note::
+    It is possible to configure the value by which the estimated fee is multiplied,
+    by changing ``ESTIMATED_FEE_MULTIPLIER`` for V1 and V2 transactions in :class:`~starknet_py.net.account.account.Account`.
+    The same applies to ``ESTIMATED_AMOUNT_MULTIPLIER`` and ``ESTIMATED_UNIT_PRICE_MULTIPLIER`` for V3 transactions.
+
 Creating transactions without executing them
 --------------------------------------------
 
-Alongside the simpler :meth:`~starknet_py.net.account.account.Account.execute`,
 Account also provides a way of creating signed transaction without sending them.
 
 .. codesnippet:: ../../starknet_py/tests/e2e/docs/guide/test_account_sign_without_execute.py
@@ -24,7 +49,7 @@ Multicall
 ---------
 
 There is a possibility to execute an Invoke transaction containing multiple calls.
-Simply pass a list of calls to :meth:`~starknet_py.net.account.account.Account.execute` method.
+Simply pass a list of calls to :meth:`~starknet_py.net.account.account.Account.execute_v1` or :meth:`~starknet_py.net.account.account.Account.execute_v3` methods.
 Note that the nonce will be bumped only by 1.
 
 .. codesnippet:: ../../starknet_py/tests/e2e/docs/guide/test_multicall.py
@@ -38,8 +63,6 @@ Note that the nonce will be bumped only by 1.
 
     Do not pass arbitrarily large number of calls in one batch. Starknet rejects the transaction when it happens.
 
-
-
 FullNodeClient usage
 --------------------
 

docs/guide/deploying_contracts.rst

@@ -4,27 +4,21 @@ Deploying contracts
 Declaring contracts
 -------------------
 
-Since Cairo 0.10.0 Declare transactions can be signed and in the future, declaring without signing the transaction
-(and without paying the fee) will be impossible. That is why :ref:`Account` has
-:meth:`sign_declare_transaction()` method.
+A declare transaction can be issued in version 1, 2 or 3. Contracts written in Cairo 0 should be declared using version 1, while those written in Cairo 1 or higher should be declared with versions 2 or 3.
+To sign a declare transaction, you should utilize the :meth:`~starknet_py.net.account.account.Account.sign_declare_v1`, :meth:`~starknet_py.net.account.account.Account.sign_declare_v2` or :meth:`~starknet_py.net.account.account.Account.sign_declare_v3` method, respectively.
 
 Here's an example how to use it.
 
 .. codesnippet:: ../../starknet_py/tests/e2e/docs/guide/test_declaring_contracts.py
     :language: python
     :dedent: 4
 
-.. note::
-
-    Signing Declare transactions is possible only with Accounts having `__validate__` entrypoint (with `supported_tx_version = 1`).
-
-
 
 Simple declare and deploy
 -------------------------
 
 The simplest way of declaring and deploying contracts on the Starknet is to use the :ref:`Contract` class.
-Under the hood, this flow sends :meth:`Declare` transaction and then sends :meth:`InvokeFunction`
+Under the hood, this flow first sends ``Declare`` transaction and then sends ``Invoke``
 through Universal Deployment Contract (UDC) to deploy a contract.
 
 .. codesnippet:: ../../starknet_py/tests/e2e/docs/guide/test_simple_declare_and_deploy.py
@@ -34,7 +28,7 @@ through Universal Deployment Contract (UDC) to deploy a contract.
 Simple deploy
 -------------
 
-If you already know the class hash of an already declared contract you want to deploy just use the :meth:`Contract.deploy_contract`.
+If you know the class hash of an already declared contract you want to deploy just use the :meth:`~starknet_py.contract.Contract.deploy_contract_v1` or :meth:`~starknet_py.contract.Contract.deploy_contract_v3`.
 It will deploy the contract using funds from your account. Deployment is handled by UDC.
 
 .. codesnippet:: ../../starknet_py/tests/e2e/docs/guide/test_simple_deploy.py
@@ -62,7 +56,6 @@ Deploying and using deployed contract in the same transaction
 
 :ref:`Deployer` is designed to work with multicalls too. It allows to deploy a contract
 and call its methods in the same multicall, ensuring atomicity of all operations combined.
-Isn't it brilliant? Check out the code!
 
 .. codesnippet:: ../../starknet_py/tests/e2e/docs/guide/test_deploying_in_multicall.py
     :language: python
@@ -75,9 +68,7 @@ Cairo1 contracts
 Declaring Cairo1 contracts
 ##########################
 
-| Starknet 0.11 introduced the ability to declare contracts written in Cairo1!
-
-To declare a new contract, Declare v2 or Declare v3 transaction has to be sent.
+To declare a contract in Cairo version 1 or higher, Declare V2 or Declare V3 transaction has to be sent.
 You can see the structure of these transactions `here <https://docs.starknet.io/documentation/architecture_and_concepts/Network_Architecture/transactions/#declare-transaction>`_.
 
 The main differences in the structure of the transaction from its previous version are:

docs/guide/using_existing_contracts.rst

@@ -37,77 +37,81 @@ If you do not have ABI statically, but you know the interface of the contract on
 Fees
 ----
 
-starknet.py requires you to specify amount of Wei you
-are willing to pay either when making ``.invoke()`` transactions or when preparing
-function calls with ``.prepare()``.
+.. currentmodule:: starknet_py.contract
+
+Starknet.py requires you to specify amount of Wei (for V1 transaction) or Fri (for V3 transaction) you
+are willing to pay when executing either :meth:`~ContractFunction.invoke_v1` or :meth:`~ContractFunction.invoke_v3` transactions.
+Alternatively, you can estimate fee automatically, as described in the :ref:`automatic-fee-estimation` section below.
 
 .. code-block:: python
 
-    await contract.functions["put"].invoke(k, v, max_fee=5000)
+    await contract.functions["put"].invoke_v1(k, v, max_fee=5000)
 
-When max_fee is specified when preparing a call, you can invoke it without
-``max_fee``.
+The ``max_fee`` argument can be also defined in :meth:`~ContractFunction.prepare_invoke_v1`. Subsequently, the :meth:`~PreparedFunctionInvokeV1.invoke` method on a prepared call can be used either with ``max_fee`` omitted or with its value overridden.
+The same behavior applies to :meth:`~ContractFunction.prepare_invoke_v3` and ``l1_resource_bounds``.
 
 .. code-block:: python
 
-    prepared_call = contract.function["put"].prepare(k, v, max_fee=5000)
+    prepared_call = contract.function["put"].prepare_invoke_v1(k, v, max_fee=5000)
     await prepared_call.invoke()
+    # or max_fee can be overridden
+    await prepared_call.invoke(max_fee=10000)
 
 .. warning::
 
-    If ``max_fee`` is not specified at any step it will default to ``None``,
-    and will raise an exception when invoking a transaction.
+    For V1 transactions if ``max_fee`` is not specified at any step it will default to ``None``,
+    and will raise an exception when invoking a transaction, unless `auto_estimate` is specified and is set to `True`. The same applies to ``l1_resource_bounds`` and V3 transactions.
 
-Please note you will need to have enough Wei in your Starknet account otherwise
+Please note you will need to have enough Wei (for V1 transaction) or Fri (for V3 transaction) in your Starknet account otherwise
 transaction will be rejected.
 
 Fee estimation
 --------------
 
 You can estimate required amount of fee that will need to be paid for transaction
-using :meth:`PreparedFunctionCall.estimate_fee() <starknet_py.contract.PreparedFunctionCall.estimate_fee>`
+using :meth:`PreparedFunctionInvoke.estimate_fee() <starknet_py.contract.PreparedFunctionInvoke.estimate_fee>`
 
 .. code-block:: python
 
-    await contract.functions["put"].prepare(k, v, max_fee=5000).estimate_fee()
+    await contract.functions["put"].prepare_invoke_v1(k, v).estimate_fee()
 
+.. _automatic-fee-estimation:
 
 Automatic fee estimation
 ------------------------
 
-For testing purposes it is possible to enable automatic fee estimation when making
-a transaction. starknet.py will then use ``estimate_fee()`` internally and use value
-returned by it multiplied by ``1.5`` as a ``max_fee``.
-
-.. warning::
-
-    Do not use automatic fee estimation in production code! It may lead to
-    very high fees paid as the amount returned by ``estimate_fee()`` may be arbitrarily large.
+For testing purposes it is possible to enable automatic fee estimation when making a transaction. Starknet.py will then call :meth:`~starknet_py.net.full_node_client.FullNodeClient.estimate_fee`
+internally and use the returned value, multiplied by ``1.5`` to mitigate fluctuations in price, as a ``max_fee`` for V1 transactions. For V3 transactions,
+``max_amount`` will be multiplied by ``1.1``, and ``max_price_per_unit`` by ``1.5``.
 
 .. code-block:: python
 
-    await contract.functions["put"].invoke(k, v, auto_estimate=True)
+    await contract.functions["put"].invoke_v1(k, v, auto_estimate=True)
+
+.. warning::
 
+    It is strongly discouraged to use automatic fee estimation in production code as it may lead to unexpectedly high fee.
 
 .. note::
-    It is possible to configure the value by which the estimated fee is multiplied,
-    by changing ``ESTIMATED_FEE_MULTIPLIER`` in :class:`~starknet_py.net.account.account.Account`.
+    For V1 transactions it is possible to configure the value by which the estimated fee is multiplied,
+    by changing ``ESTIMATED_FEE_MULTIPLIER`` in :class:`~starknet_py.net.account.account.Account`. The same applies to
+    ``ESTIMATED_AMOUNT_MULTIPLIER`` and ``ESTIMATED_UNIT_PRICE_MULTIPLIER`` for V3 transactions.
 
 Account and Client interoperability
 -----------------------------------
 
 .. currentmodule:: starknet_py.contract
 
-:ref:`Contract` methods have been designed to be
-compatible with :ref:`Account` and :ref:`Client`.
+:ref:`Contract` methods have been designed to be compatible with :ref:`Account` and :ref:`Client`.
 
-:ref:`PreparedFunctionCall` returned by :meth:`ContractFunction.prepare` can be used in Account methods to create Invoke transactions.
+:ref:`PreparedFunctionInvokeV1` and :ref:`PreparedFunctionInvokeV3` returned by :meth:`ContractFunction.prepare_invoke_v1` and :meth:`ContractFunction.prepare_invoke_v3` respectively can be used in Account methods to create Invoke transactions.
 
 .. codesnippet:: ../../starknet_py/tests/e2e/docs/guide/test_contract_account_compatibility.py
     :language: python
     :dedent: 4
 
-It can also be used in :meth:`Client.call_contract() <starknet_py.net.client.Client.call_contract>`
+
+Similarly, :ref:`PreparedFunctionCall` returned by :meth:`ContractFunction.prepare_call` can be used in :meth:`Client.call_contract() <starknet_py.net.client.Client.call_contract>`
 
 .. codesnippet:: ../../starknet_py/tests/e2e/docs/guide/test_contract_client_compatibility.py
     :language: python

docs/migration_guide.rst

@@ -16,25 +16,37 @@ Changes in the :class:`~starknet_py.net.account.account.Account`:
 
 .. currentmodule:: starknet_py.net.account.account
 
-- :meth:`~Account.execute_v3` has been added.
-- :meth:`~Account.sign_declare_v3`, :meth:`~Account.sign_deploy_account_v3` and :meth:`~Account.sign_invoke_v3` have been added.
-- :meth:`sign_declare_transaction`, :meth:`sign_declare_v2_transaction`, :meth:`sign_deploy_account_transaction` and :meth:`sign_invoke_transaction` have been renamed to :meth:`~Account.sign_declare_v1`, :meth:`~Account.sign_declare_v2`, :meth:`~Account.sign_deploy_account_v1` and :meth:`~Account.sign_invoke_v1` respectively.
+- :meth:`~Account.execute` has been renamed to :meth:`~Account.execute_v1`
+- :meth:`~Account.execute_v3` has been added
+- :meth:`~Account.deploy_account` has been renamed to :meth:`~Account.deploy_account_v1`
+- :meth:`~Account.deploy_account_v3` has been added
+- :meth:`~Account.sign_declare_v3`, :meth:`~Account.sign_deploy_account_v3` and :meth:`~Account.sign_invoke_v3` have been added
+- :meth:`sign_declare_transaction`, :meth:`sign_declare_v2_transaction`, :meth:`sign_deploy_account_transaction` and :meth:`sign_invoke_transaction` have been renamed to :meth:`~Account.sign_declare_v1`, :meth:`~Account.sign_declare_v2`, :meth:`~Account.sign_deploy_account_v1` and :meth:`~Account.sign_invoke_v1` respectively
 
 All new functions with ``v3`` in their name operate similarly to their ``v1`` and ``v2`` counterparts.
-Unlike their ``v1`` counterparts, ``v3`` transaction fees are paid in Fri (10^-18 STRK). Therefore,  ``max_fee`` parameter, which is typically set in Wei, is not applicable for ``v3`` functions. Instead, ``l1_resource_bounds`` parameter is utilized to limit the Fri amount used.
+Unlike their ``v1`` counterparts however, ``v3`` transaction fees are paid in Fri (10^-18 STRK). Therefore,  ``max_fee`` parameter, which is typically set in Wei, is not applicable for ``v3`` functions. Instead, ``l1_resource_bounds`` parameter is utilized to limit the Fri amount used.
+The same applies to the new ``v3`` methods in the :class:`~starknet_py.contract.Contract` class.
 
 Changes in the :class:`~starknet_py.net.full_node_client.FullNodeClient`:
 
 .. currentmodule:: starknet_py.net.full_node_client
 
-- :meth:`~FullNodeClient.estimate_fee` has a new parameter ``skip_validate``.
+- :meth:`~FullNodeClient.estimate_fee` has a new parameter ``skip_validate``
 - :meth:`~FullNodeClient.declare` accepts ``transaction`` argument of the type :class:`~starknet_py.net.models.transaction.DeclareV3`
 - :meth:`~FullNodeClient.send_transaction` accepts ``transaction`` argument of the type :class:`~starknet_py.net.models.transaction.InvokeV3`
 - :meth:`~FullNodeClient.deploy_account` accepts ``transaction`` argument of the type :class:`~starknet_py.net.models.transaction.DeployAccountV3`
 
-.. warning::
-    :class:`~starknet_py.contract.Contract` class does not support V3 transactions in the pre-release.
+Changes in the :class:`~starknet_py.contract.Contract`:
 
+.. currentmodule:: starknet_py.contract
+
+- :meth:`Contract.declare` has been replaced by :meth:`Contract.declare_v1`, :meth:`Contract.declare_v2` and :meth:`Contract.declare_v3`
+- :meth:`Contract.deploy_contract` has been replaced by :meth:`Contract.deploy_contract_v1` and :meth:`Contract.deploy_contract_v3`. Optional parameters ``unique`` and ``salt`` have been added to both methods
+- :meth:`ContractFunction.prepare` has been replaced by :meth:`ContractFunction.prepare_invoke_v1`, :meth:`ContractFunction.prepare_invoke_v3` and :meth:`ContractFunction.prepare_call`
+- :meth:`ContractFunction.invoke` has been replaced by :meth:`ContractFunction.invoke_v1` and :meth:`ContractFunction.invoke_v3`
+- :meth:`PreparedFunctionCall` has now only methods :meth:`PreparedFunctionCall.call` and :meth:`PreparedFunctionCall.call_raw`
+- :meth:`PreparedFunctionInvokeV1` and :meth:`PreparedFunctionInvokeV3` with methods ``invoke`` and ``estimate_fee`` have been added
+- :meth:`DeclareResult.deploy` has been replaced by :meth:`DeclareResult.deploy_v1` and :meth:`DeclareResult.deploy_v3`
 
 0.19.0 Targeted versions
 ------------------------
@@ -44,6 +56,7 @@ Changes in the :class:`~starknet_py.net.full_node_client.FullNodeClient`:
 
 0.19.0 Breaking changes
 -----------------------
+Other breaking changes not mentioned above.
 
 .. currentmodule:: starknet_py.net.client_models
 
@@ -60,6 +73,9 @@ Changes in the :class:`~starknet_py.net.full_node_client.FullNodeClient`:
 11. :class:`ResourceLimits` class has been renamed to :class:`ResourceBounds`.
 12. :class:`~starknet_py.net.account.base_account.BaseAccount` and :class:`~starknet_py.net.account.account.Account` property ``supported_transaction_version`` has been removed.
 13. ``wait_for_accept`` parameter in :meth:`Client.wait_for_tx` and :meth:`SentTransaction.wait_for_acceptance` has been removed.
+14. :class:`InvokeTransaction` has been replaced by :class:`InvokeTransactionV0` and :class:`InvokeTransactionV1`.
+15. :class:`DeclareTransaction` has been replaced by :class:`DeclareTransactionV0`, :class:`DeclareTransactionV1` and :class:`DeclareTransactionV3`.
+16. :class:`DeployAccountTransaction` has been replaced by :class:`DeployAccountTransactionV1`.
 
 0.19.0 Minor changes
 --------------------

docs/quickstart.rst

@@ -30,8 +30,8 @@ It supports an account contract which proxies the calls to other contracts on St
 
 Account can be created in two ways:
 
-* By constructor (address, key_pair and net must be known).
-* By static method ``Account.deploy_account``
+* By constructor (It is required to provide an ``address`` and either ``key_pair`` or ``signer``).
+* By static methods ``Account.deploy_account_v1`` or ``Account.deploy_account_v3``
 
 There are some examples how to do it:
 
@@ -58,7 +58,7 @@ Using Contract
 
 .. note::
 
-    To check if invoke succeeds use wait_for_acceptance on InvokeResult and get its status.
+    To check if invoke succeeded use ``wait_for_acceptance`` on InvokeResult and get its status.
 
 Although asynchronous API is recommended, you can also use Contract's synchronous API:
 

starknet_py/tests/e2e/docs/account_creation/test_deploy_prefunded_account.py

@@ -58,7 +58,7 @@ async def test_deploy_prefunded_account(
     chain = chain_from_network(net=network, chain=StarknetChainId.GOERLI)
     # docs: start
 
-    # Use `Account.deploy_account_v1` static method to deploy an account
+    # Use `Account.deploy_account_v1` or `Account.deploy_account_v3` static methods to deploy an account
     account_deployment_result = await Account.deploy_account_v1(
         address=address,
         class_hash=class_hash,