Skip to content

Commit

Permalink
docs: add info on max_fee and priority_fee
Browse files Browse the repository at this point in the history
  • Loading branch information
iamdefinitelyahuman committed Aug 16, 2021
1 parent 9881cec commit 11a30e0
Show file tree
Hide file tree
Showing 4 changed files with 110 additions and 47 deletions.
43 changes: 39 additions & 4 deletions docs/api-network.rst
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,7 @@ The ``main`` module contains methods for conncting to or disconnecting from the

* If no argument is given, the current default is displayed.
* If an integer value is given, this will be the default gas limit.
* If set to ``auto``, the gas limit is determined automatically via :meth:`web3.eth.estimate_gas <web3.eth.Eth.estimateGas>`.
* If set to ``"auto"``, the gas limit is determined automatically via :meth:`web3.eth.estimate_gas <web3.eth.Eth.estimate_gas>`.

Returns ``False`` if the gas limit is set automatically, or an ``int`` if it is set to a fixed value.

Expand Down Expand Up @@ -99,7 +99,7 @@ The ``main`` module contains methods for conncting to or disconnecting from the
Gets and optionally sets the default gas price.

* If an integer value is given, this will be the default gas price.
* If set to ``auto``, the gas price is determined automatically via :attr:`web3.eth.gas_price <web3.eth.Eth.gasPrice>`.
* If set to ``"auto"``, the gas price is determined automatically via :attr:`web3.eth.gas_price <web3.eth.Eth.gas_price>`.

Returns ``False`` if the gas price is set automatically, or an ``int`` if it is set to a fixed value.

Expand All @@ -115,6 +115,41 @@ The ``main`` module contains methods for conncting to or disconnecting from the
>>> network.gas_price("auto")
False
.. py:method:: main.max_fee(*args)
Gets and optionally sets the default max fee per gas.

* If an integer value is given, this will be the default max fee.
* If set to ``None`` or ``False``, transactions will instead default to using a legacy-style ``gas_price``.

.. code-block:: python
>>> from brownie import network
>>> network.max_fee()
None
>>> network.max_fee(10000000000)
10000000000
>>> network.max_fee("45 gwei")
45000000000
.. py:method:: main.priority_fee(*args)
Gets and optionally sets the default max priority fee per gas.

* If an integer value is given, this will be the default priority fee.
* If set to ``"auto"``, the fee is determined automatically via :attr:`web3.eth.max_priority_fee <web3.eth.Eth.max_priority_fee>`.
* If set to ``None`` or ``False``, transactions will instead default to using a legacy-style ``gas_price``.

.. code-block:: python
>>> from brownie import network
>>> network.priority_fee()
None
>>> network.priority_fee(4000000000)
4000000000
>>> network.priority_fee("2 gwei")
2000000000
``brownie.network.account``
===========================

Expand Down Expand Up @@ -1690,7 +1725,7 @@ Multicall
2. Auto-deployment on development networks (on first use).
3. Uses ``multicall2`` key in network-config as pre-defined multicall contract address
4. Can specify/modify block number to make calls at particular block heights
5. Calls which fail return ``None`` instad of causing all calls to fail
5. Calls which fail return ``None`` instad of causing all calls to fail

.. code-block:: python
Expand Down Expand Up @@ -1725,7 +1760,7 @@ Multicall Attributes
.. note::

``Multicall`` relies on an instance of ``Multicall2`` being available for aggregating results. If you set the block_height before the ``Multicall2`` instance you are using was deployed a ``ContractNotFound`` error will be raised.

.. code-block:: python
>>> with brownie.multicall(block_identifier=12733683):
Expand Down
14 changes: 14 additions & 0 deletions docs/config.rst
Original file line number Diff line number Diff line change
Expand Up @@ -113,6 +113,8 @@ Networks
gas_limit: max
gas_buffer: 1
gas_price: 0
max_fee: null
priority_fee: null
reverting_tx_gas_limit: max
default_contract_owner: true
cmd_settings:
Expand Down Expand Up @@ -157,6 +159,18 @@ Networks

live default: ``auto``

.. py:attribute:: max_fee
The default max fee per gas for all transactions. If set to ``null``, transactions will default to legacy-style (using ``gas_price``).

default: ``null``

.. py:attribute:: priority_fee
The default max priority fee per gas for all transactions. If set to ``null``, transactions will default to legacy-style (using ``gas_price``).

default: ``null``

.. py:attribute:: default_contract_owner
If ``false``, deployed contracts will not remember the account that they were created by. Every transaction will require a ``from`` kwarg.
Expand Down
98 changes: 56 additions & 42 deletions docs/core-gas.rst
Original file line number Diff line number Diff line change
@@ -1,27 +1,41 @@
.. _core-accounts:
.. _core-gas:

==============================
Setting Transaction Gas Prices
==============================

========================
Dynamic Fee Transactions
========================

If the network you are interacting with implements EIP-1559, you can use a better fee model when sending transactions. Instead of specifying ``gas_price``, you specify ``priority_fee`` and an optional ``max_fee``.

* ``priority_fee`` detrmines ``maxPriorityFeePerGas``, which is tipped to the miner. The recommended priority fee can be read from ``chain.priority_fee``.
* ``priority_fee`` determines ``maxPriorityFeePerGas``, which is tipped to the miner. The recommended priority fee can be read from ``chain.priority_fee``.

* ``max_fee`` determines ``maxFeePerGas``, which includes the base fee, which is the same for all transactions in the block and is burned, and your priority fee. The current base fee can be read from ``chain.base_fee``.

Brownie uses ``base_fee * 2 + priority_fee`` as ``max_fee`` if you only specify the priority fee.

.. code-block:: python
.. code-block:: python
>>> accounts[0].transfer(accounts[1], priority_fee='2 gwei')
Transaction sent: 0x090755e0b75648d12b1ada31fa5957a07aadcbe8a34b8f9af59098f1890d1063
Max fee: 4.0 gwei Priority fee: 2.0 gwei Gas limit: 30000000 Nonce: 0
Transaction confirmed Block: 1 Gas used: 21000 (0.07%) Gas price: 2.875 gwei
>>> accounts[0].transfer(accounts[1], priority_fee="2 gwei")
Transaction sent: 0x090755e0b75648d12b1ada31fa5957a07aadcbe8a34b8f9af59098f1890d1063
Max fee: 4.0 gwei Priority fee: 2.0 gwei Gas limit: 30000000 Nonce: 0
Transaction confirmed Block: 1 Gas used: 21000 (0.07%) Gas price: 2.875 gwei
Dynamic fee transactions do not support (and arguably don't need) gas strategies. The section below only applies to legacy transactions which use ``gas_price``.
Dynamic fee transactions do not support (and arguably don't need) gas strategies. The section below only applies to legacy transactions which use ``gas_price``.

Setting Default Dynamic Fees
----------------------------

You can use :func:`network.priority_fee <main.max_fee>` to set a default priority fee for all transactions:

.. code-block:: python
>>> from brownie.network import gas_price
>>> priority_fee("2 gwei")
Setting the default to ``"auto"`` will dynamically determine the priority fee using :attr:`web3.eth.max_priority_fee <web3.eth.Eth.max_priority_fee>`. Seting to ``None`` will return to legacy-style transactions.

==============
Gas Strategies
==============

Expand All @@ -34,37 +48,37 @@ Gas strategies come in three basic types:
* **Time** strategies provide an initial price, and optionally replace pending transactions based on the amount of time that has passed since the first transaction was broadcast.

Using a Gas Strategy
====================
--------------------

To use a gas strategy, first import it from ``brownie.network.gas.strategies``:

.. code-block:: python
.. code-block:: python
>>> from brownie.network.gas.strategies import GasNowStrategy
>>> gas_strategy = GasNowStrategy("fast")
>>> from brownie.network.gas.strategies import GasNowStrategy
>>> gas_strategy = GasNowStrategy("fast")
You can then provide the object in the ``gas_price`` field when making a transaction:

.. code-block:: python
.. code-block:: python
>>> accounts[0].transfer(accounts[1], "1 ether", gas_price=gas_strategy)
>>> accounts[0].transfer(accounts[1], "1 ether", gas_price=gas_strategy)
When the strategy replaces a pending transaction, the returned :func:`TransactionReceipt <brownie.network.transaction.TransactionReceipt>` object will be for the transaction that confirms.

During :ref:`non-blocking transactions <core-accounts-non-blocking>`, all pending transactions are available within the :func:`history <brownie.network.state.TxHistory>` object. As soon as one transaction confirms, the remaining dropped transactions are removed.

Setting a Default Gas Strategy
==============================
------------------------------

You can use :func:`network.gas_price <main.gas_price>` to set a gas strategy as the default for all transactions:

.. code-block:: python
.. code-block:: python
>>> from brownie.network import gas_price
>>> gas_price(gas_strategy)
>>> from brownie.network import gas_price
>>> gas_price(gas_strategy)
Available Gas Strategies
========================
------------------------

.. py:class:: brownie.network.gas.strategies.LinearScalingStrategy(initial_gas_price, max_gas_price, increment=1.125, time_duration=30)
Expand All @@ -75,12 +89,12 @@ Available Gas Strategies
* ``increment``: Multiplier applied to the previous gas price in order to determine the new gas price
* ``time_duration``: Number of seconds between transactions

.. code-block:: python
.. code-block:: python
>>> from brownie.network.gas.strategies import LinearScalingStrategy
>>> gas_strategy = LinearScalingStrategy("10 gwei", "50 gwei", 1.1)
>>> from brownie.network.gas.strategies import LinearScalingStrategy
>>> gas_strategy = LinearScalingStrategy("10 gwei", "50 gwei", 1.1)
>>> accounts[0].transfer(accounts[1], "1 ether", gas_price=gas_strategy)
>>> accounts[0].transfer(accounts[1], "1 ether", gas_price=gas_strategy)
.. py:class:: brownie.network.gas.strategies.ExponentialScalingStrategy(initial_gas_price, max_gas_price, time_duration=30)
Expand All @@ -92,25 +106,25 @@ Available Gas Strategies
* ``max_gas_price``: The maximum gas price to use
* ``time_duration``: Number of seconds between transactions

.. code-block:: python
.. code-block:: python
>>> from brownie.network.gas.strategies import ExponentialScalingStrategy
>>> gas_strategy = ExponentialScalingStrategy("10 gwei", "50 gwei")
>>> from brownie.network.gas.strategies import ExponentialScalingStrategy
>>> gas_strategy = ExponentialScalingStrategy("10 gwei", "50 gwei")
>>> accounts[0].transfer(accounts[1], "1 ether", gas_price=gas_strategy)
>>> accounts[0].transfer(accounts[1], "1 ether", gas_price=gas_strategy)
.. py:class:: brownie.network.gas.strategies.GasNowStrategy(speed="fast")
Simple gas strategy for determing a price using the `GasNow <https://www.gasnow.org/>`_ API.

* ``speed``: The gas price to use based on the API call. Options are rapid, fast, standard and slow.

.. code-block:: python
.. code-block:: python
>>> from brownie.network.gas.strategies import GasNowStrategy
>>> gas_strategy = GasNowStrategy("fast")
>>> from brownie.network.gas.strategies import GasNowStrategy
>>> gas_strategy = GasNowStrategy("fast")
>>> accounts[0].transfer(accounts[1], "1 ether", gas_price=gas_strategy)
>>> accounts[0].transfer(accounts[1], "1 ether", gas_price=gas_strategy)
.. py:class:: brownie.network.gas.strategies.GasNowScalingStrategy(initial_speed="standard", max_speed="rapid", increment=1.125, block_duration=2)
Expand All @@ -121,12 +135,12 @@ Available Gas Strategies
* ``increment``: A multiplier applied to the most recently used gas price in order to determine the new gas price. If the incremented value is less than or equal to the current ``max_speed`` rate, a new transaction is broadcasted. If the current rate for ``initial_speed`` is greater than the incremented rate, it is used instead.
* ``block_duration``: The number of blocks to wait between broadcasting new transactions.

.. code-block:: python
.. code-block:: python
>>> from brownie.network.gas.strategies import GasNowScalingStrategy
>>> gas_strategy = GasNowScalingStrategy("fast", increment=1.2)
>>> from brownie.network.gas.strategies import GasNowScalingStrategy
>>> gas_strategy = GasNowScalingStrategy("fast", increment=1.2)
>>> accounts[0].transfer(accounts[1], "1 ether", gas_price=gas_strategy)
>>> accounts[0].transfer(accounts[1], "1 ether", gas_price=gas_strategy)
.. py:class:: brownie.network.gas.strategies.GethMempoolStrategy(position=500, graphql_endpoint=None, block_duration=2)
Expand All @@ -139,14 +153,14 @@ Available Gas Strategies
* A position of 200 or less usually places a transaction within the mining block.
* A position of 500 usually places a transaction within the 2nd pending block.

.. code-block:: python
.. code-block:: python
>>> from brownie.network.gas.strategies import GethMempoolStrategy
>>> gas_strategy = GethMempoolStrategy(200)
>>> from brownie.network.gas.strategies import GethMempoolStrategy
>>> gas_strategy = GethMempoolStrategy(200)
>>> accounts[0].transfer(accounts[1], "1 ether", gas_price=gas_strategy)
>>> accounts[0].transfer(accounts[1], "1 ether", gas_price=gas_strategy)
Building your own Gas Strategy
==============================
------------------------------

To implement your own gas strategy you must subclass from one of the :ref:`gas strategy abstract base classes <api-network-gas-abc>`.
2 changes: 1 addition & 1 deletion docs/toctree.rst
Original file line number Diff line number Diff line change
Expand Up @@ -28,10 +28,10 @@ Brownie

core-accounts.rst
core-contracts.rst
core-gas.rst
core-chain.rst
core-transactions.rst
core-types.rst
core-gas.rst


.. toctree::
Expand Down

0 comments on commit 11a30e0

Please sign in to comment.