Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merge block tags support 5199 #5410

Merged
merged 22 commits into from
Sep 7, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -600,3 +600,4 @@ Released with 1.0.0-beta.37 code base.

### Added
- Add missing function type "receive" in `AbiType` (#5165)
- Support of `safe` and `finalized` block tags added (#5410)
12 changes: 7 additions & 5 deletions docs/web3-eth-contract.rst
Original file line number Diff line number Diff line change
Expand Up @@ -144,6 +144,8 @@ The default block parameters can be one of the following:
- ``"earliest"`` - ``String``: The genesis block
- ``"latest"`` - ``String``: The latest block (current head of the blockchain)
- ``"pending"`` - ``String``: The currently mined block (including pending transactions)
- ``"finalized"`` - ``String``: (For POS networks) The finalized block is one which has been accepted as canonical by >2/3 of validators.
- ``"safe"`` - ``String``: (For POS networks) The safe head block is one which under normal network conditions, is expected to be included in the canonical chain. Under normal network conditions the safe head and the actual tip of the chain will be equivalent (with safe head trailing only by a few seconds). Safe heads will be less likely to be reorged than the proof of work networks latest blocks.

Default is ``"latest"``.

Expand Down Expand Up @@ -792,7 +794,7 @@ Parameters
* ``from`` - ``String`` (optional): The address the call "transaction" should be made from. For calls the ``from`` property is optional however it is highly recommended to explicitly set it or it may default to `address(0)` depending on your node or provider.
* ``gasPrice`` - ``String`` (optional): The gas price in wei to use for this call "transaction".
* ``gas`` - ``Number`` (optional): The maximum gas provided for this call "transaction" (gas limit).
2. ``defaultBlock`` - ``Number|String|BN|BigNumber`` (optional): If you pass this parameter it will not use the default block set with :ref:`contract.defaultBlock <defaultblock>`. Pre-defined block numbers as ``"earliest"``, ``"latest"``, and ``"pending"`` can also be used. Useful for requesting data from or replaying transactions in past blocks.
2. ``defaultBlock`` - ``Number|String|BN|BigNumber`` (optional): If you pass this parameter it will not use the default block set with :ref:`contract.defaultBlock <defaultblock>`. Pre-defined block numbers as ``"earliest"``, ``"latest"``, ``"pending"``, ``"safe"`` or ``"finalized"`` can also be used. Useful for requesting data from or replaying transactions in past blocks.
3. ``callback`` - ``Function`` (optional): This callback will be fired with the result of the smart contract method execution as the second argument, or with an error object as the first argument.

-------
Expand Down Expand Up @@ -1083,7 +1085,7 @@ Parameters
1. ``options`` - ``Object``: The options used for calling.
* ``from`` - ``String``: The address the call "transaction" should be made from.
* ``gas`` - ``Number`` (optional): The maximum gas provided for this call "transaction" (gas limit). Setting a specific value helps to detect out of gas errors. Access list response will return amount of gas used.
2. ``block`` - ``String|Number|BN|BigNumber`` (optional): The block number or hash. Or the string ``"earliest"``, ``"latest"`` or ``"pending"`` as in the :ref:`default block parameter <eth-defaultblock>`.
2. ``block`` - ``String|Number|BN|BigNumber`` (optional): The block number or hash. Or the string ``"earliest"``, ``"latest"`` , ``"pending"`` , ``"safe"`` or ``"finalized"`` as in the :ref:`default block parameter <eth-defaultblock>`.
3. ``callback`` - ``Function`` (optional): This callback will be fired with the result of the access list generation as the second argument, or with an error object as the first argument.

-------
Expand Down Expand Up @@ -1215,7 +1217,7 @@ Parameters

1. ``options`` - ``Object`` (optional): The options used for deployment.
* ``filter`` - ``Object`` (optional): Let you filter events by indexed parameters, e.g. ``{filter: {myNumber: [12,13]}}`` means all events where "myNumber" is 12 or 13.
* ``fromBlock`` - ``Number|String|BN|BigNumber`` (optional): The block number (greater than or equal to) from which to get events on. Pre-defined block numbers as ``"earliest"``, ``"latest"`` and ``"pending"`` can also be used. For specific range use :ref:`getPastEvents <getPastEvents>`.
* ``fromBlock`` - ``Number|String|BN|BigNumber`` (optional): The block number (greater than or equal to) from which to get events on. Pre-defined block numbers as ``"earliest"``, ``"latest"`` , ``"pending"`` , ``"safe"`` or ``"finalized"`` can also be used. For specific range use :ref:`getPastEvents <getPastEvents>`.
* ``topics`` - ``Array`` (optional): This allows to manually set the topics for the event filter. If given the filter property and event signature, (topic[0]) will not be set automatically. Each topic can also be a nested array of topics that behaves as “or” operation between the given nested topics.
2. ``callback`` - ``Function`` (optional): This callback will be fired for each *event* as the second argument, or an error as the first argument.

Expand Down Expand Up @@ -1324,8 +1326,8 @@ Parameters
1. ``event`` - ``String``: The name of the event in the contract, or ``"allEvents"`` to get all events.
2. ``options`` - ``Object`` (optional): The options used for deployment.
* ``filter`` - ``Object`` (optional): Lets you filter events by indexed parameters, e.g. ``{filter: {myNumber: [12,13]}}`` means all events where "myNumber" is 12 or 13.
* ``fromBlock`` - ``Number|String|BN|BigNumber`` (optional): The block number (greater than or equal to) from which to get events on. Pre-defined block numbers as ``"earliest"``, ``"latest"`` and ``"pending"`` can also be used.
* ``toBlock`` - ``Number|String|BN|BigNumber`` (optional): The block number (less than or equal to) to get events up to (Defaults to ``"latest"``). Pre-defined block numbers as ``"earliest"``, ``"latest"`` and ``"pending"`` can also be used.
* ``fromBlock`` - ``Number|String|BN|BigNumber`` (optional): The block number (greater than or equal to) from which to get events on. Pre-defined block numbers as ``"earliest"``, ``"latest"`` , ``"pending"`` , ``"safe"`` or ``"finalized"`` can also be used.
* ``toBlock`` - ``Number|String|BN|BigNumber`` (optional): The block number (less than or equal to) to get events up to (Defaults to ``"latest"``). Pre-defined block numbers as ``"earliest"``, ``"latest"`` , ``"pending"`` , ``"safe"`` or ``"finalized"`` can also be used.
* ``topics`` - ``Array`` (optional): This allows manually setting the topics for the event filter. If given the filter property and event signature, (topic[0]) will not be set automatically. Each topic can also be a nested array of topics that behaves as “or” operation between the given nested topics.
3. ``callback`` - ``Function`` (optional): This callback will be fired with an array of event logs as the second argument, or an error as the first argument.

Expand Down
30 changes: 16 additions & 14 deletions docs/web3-eth.rst
Original file line number Diff line number Diff line change
Expand Up @@ -191,6 +191,8 @@ Default block parameters can be one of the following:
- ``"earliest"`` - ``String``: The genesis block
- ``"latest"`` - ``String``: The latest block (current head of the blockchain)
- ``"pending"`` - ``String``: The currently mined block (including pending transactions)
- ``"finalized"`` - ``String``: (For POS networks) The finalized block is one which has been accepted as canonical by >2/3 of validators.
- ``"safe"`` - ``String``: (For POS networks) The safe head block is one which under normal network conditions, is expected to be included in the canonical chain. Under normal network conditions the safe head and the actual tip of the chain will be equivalent (with safe head trailing only by a few seconds). Safe heads will be less likely to be reorged than the proof of work networks latest blocks.

Default is ``"latest"``

Expand Down Expand Up @@ -884,7 +886,7 @@ Parameters
----------

1. ``String`` - The address to get the balance of.
2. ``Number|String|BN|BigNumber`` - (optional) If you pass this parameter it will not use the default block set with :ref:`web3.eth.defaultBlock <eth-defaultblock>`. Pre-defined block numbers as ``"earliest"``, ``"latest"`` and ``"pending"`` can also be used.
2. ``Number|String|BN|BigNumber`` - (optional) If you pass this parameter it will not use the default block set with :ref:`web3.eth.defaultBlock <eth-defaultblock>`. Pre-defined block numbers as ``"earliest"``, ``"latest"`` , ``"pending"``, ``"safe"`` or ``"finalized"`` can also be used.
3. ``Function`` - (optional) Optional callback, returns an error object as first parameter and the result as second.

-------
Expand Down Expand Up @@ -925,7 +927,7 @@ Parameters

1. ``String`` - The address to get the storage from.
2. ``Number|String|BN|BigNumber`` - The index position of the storage.
3. ``Number|String|BN|BigNumber`` - (optional) If you pass this parameter it will not use the default block set with :ref:`web3.eth.defaultBlock <eth-defaultblock>`. Pre-defined block numbers as ``"earliest"``, ``"latest"`` and ``"pending"`` can also be used.
3. ``Number|String|BN|BigNumber`` - (optional) If you pass this parameter it will not use the default block set with :ref:`web3.eth.defaultBlock <eth-defaultblock>`. Pre-defined block numbers as ``"earliest"``, ``"latest"`` , ``"pending"``, ``"safe"`` or ``"finalized"`` can also be used.
4. ``Function`` - (optional) Optional callback, returns an error object as first parameter and the result as second.


Expand Down Expand Up @@ -963,7 +965,7 @@ Parameters
----------

1. ``String`` - The address to get the code from.
2. ``Number|String|BN|BigNumber`` - (optional) If you pass this parameter it will not use the default block set with :ref:`web3.eth.defaultBlock <eth-defaultblock>`. Pre-defined block numbers as ``"earliest"``, ``"latest"`` and ``"pending"`` can also be used.
2. ``Number|String|BN|BigNumber`` - (optional) If you pass this parameter it will not use the default block set with :ref:`web3.eth.defaultBlock <eth-defaultblock>`. Pre-defined block numbers as ``"earliest"``, ``"latest"`` , ``"pending"``, ``"safe"`` or ``"finalized"`` can also be used.
3. ``Function`` - (optional) Optional callback, returns an error object as first parameter and the result as second.

-------
Expand Down Expand Up @@ -1002,7 +1004,7 @@ Returns a block matching the block number or block hash.
Parameters
----------

1. ``String|Number|BN|BigNumber`` - The block number or block hash. Or the string ``"earliest"``, ``"latest"`` or ``"pending"`` as in the :ref:`default block parameter <eth-defaultblock>`.
1. ``String|Number|BN|BigNumber`` - The block number or block hash. Or the string ``"earliest"``, ``"latest"`` , ``"pending"``, ``"safe"`` or ``"finalized"`` as in the :ref:`default block parameter <eth-defaultblock>`.
2. ``Boolean`` - (optional, default ``false``) If specified ``true``, the returned block will contain all transactions as objects. If ``false`` it will only contains the transaction hashes.
3. ``Function`` - (optional) Optional callback, returns an error object as first parameter and the result as second.

Expand Down Expand Up @@ -1085,7 +1087,7 @@ Parameters
----------


1. ``String|Number|BN|BigNumber`` - The block number or hash. Or the string ``"earliest"``, ``"latest"`` or ``"pending"`` as in the :ref:`default block parameter <eth-defaultblock>`.
1. ``String|Number|BN|BigNumber`` - The block number or hash. Or the string ``"earliest"``, ``"latest"`` , ``"pending"``, ``"safe"`` or ``"finalized"`` as in the :ref:`default block parameter <eth-defaultblock>`.
2. ``Function`` - (optional) Optional callback, returns an error object as first parameter and the result as second.

-------
Expand Down Expand Up @@ -1125,7 +1127,7 @@ Parameters
----------


1. ``String|Number|BN|BigNumber`` - The block number or hash. Or the string ``"earliest"``, ``"latest"`` or ``"pending"`` as in the :ref:`default block parameter <eth-defaultblock>`.
1. ``String|Number|BN|BigNumber`` - The block number or hash. Or the string ``"earliest"``, ``"latest"`` , ``"pending"``, ``"safe"`` or ``"finalized"`` as in the :ref:`default block parameter <eth-defaultblock>`.
2. ``Function`` - (optional) Optional callback, returns an error object as first parameter and the result as second.

-------
Expand Down Expand Up @@ -1162,7 +1164,7 @@ Returns a blocks uncle by a given uncle index position.
Parameters
----------

1. ``String|Number|BN|BigNumber`` - The block number or hash. Or the string ``"earliest"``, ``"latest"`` or ``"pending"`` as in the :ref:`default block parameter <eth-defaultblock>`.
1. ``String|Number|BN|BigNumber`` - The block number or hash. Or the string ``"earliest"``, ``"latest"`` , ``"pending"``, ``"safe"`` or ``"finalized"`` as in the :ref:`default block parameter <eth-defaultblock>`.
2. ``Number`` - The index position of the uncle.
3. ``Boolean`` - (optional, default ``false``) If specified ``true``, the returned block will contain all transactions as objects. By default it is ``false`` so, there is no need to explictly specify false. And, if ``false`` it will only contains the transaction hashes.
4. ``Function`` - (optional) Optional callback, returns an error object as first parameter and the result as second.
Expand Down Expand Up @@ -1356,7 +1358,7 @@ Parameters
----------


1. ``String|Number|BN|BigNumber`` - A block number or hash. Or the string ``"earliest"``, ``"latest"`` or ``"pending"`` as in the :ref:`default block parameter <eth-defaultblock>`.
1. ``String|Number|BN|BigNumber`` - A block number or hash. Or the string ``"earliest"``, ``"latest"`` , ``"pending"``, ``"safe"`` or ``"finalized"`` as in the :ref:`default block parameter <eth-defaultblock>`.
2. ``Number`` - The transaction's index position.
3. ``Function`` - (optional) Optional callback, returns an error object as first parameter and the result as second.

Expand Down Expand Up @@ -1486,7 +1488,7 @@ Parameters
----------

1. ``String`` - The address to get the numbers of transactions from.
2. ``Number|String|BN|BigNumber`` - (optional) If you pass this parameter it will not use the default block set with :ref:`web3.eth.defaultBlock <eth-defaultblock>`. Pre-defined block numbers as ``"earliest"``, ``"latest"`` and ``"pending"`` can also be used.
2. ``Number|String|BN|BigNumber`` - (optional) If you pass this parameter it will not use the default block set with :ref:`web3.eth.defaultBlock <eth-defaultblock>`. Pre-defined block numbers as ``"earliest"``, ``"latest"`` , ``"pending"``, ``"safe"`` or ``"finalized"`` can also be used.
3. ``Function`` - (optional) Optional callback, returns an error object as first parameter and the result as second.

-------
Expand Down Expand Up @@ -1804,7 +1806,7 @@ Parameters
----------

1. ``Object`` - A transaction object, see :ref:`web3.eth.sendTransaction <eth-sendtransaction-return>`. For calls the ``from`` property is optional however it is highly recommended to explicitly set it or it may default to `address(0)` depending on your node or provider.
2. ``Number|String|BN|BigNumber`` - (optional) If you pass this parameter it will not use the default block set with :ref:`web3.eth.defaultBlock <eth-defaultblock>`. Pre-defined block numbers as ``"earliest"``, ``"latest"`` and ``"pending"`` can also be used.
2. ``Number|String|BN|BigNumber`` - (optional) If you pass this parameter it will not use the default block set with :ref:`web3.eth.defaultBlock <eth-defaultblock>`. Pre-defined block numbers as ``"earliest"``, ``"latest"`` , ``"pending"``, ``"safe"`` or ``"finalized"`` can also be used.
3. ``Function`` - (optional) Optional callback, returns an error object as first parameter and the result as second.

-------
Expand Down Expand Up @@ -1888,8 +1890,8 @@ Parameters
----------

1. ``Object`` - The filter options as follows:
- ``fromBlock`` - ``Number|String``: The number of the earliest block (``"latest"`` may be given to mean the most recent and ``"pending"`` currently mining, block). By default ``"latest"``.
- ``toBlock`` - ``Number|String``: The number of the latest block (``"latest"`` may be given to mean the most recent and ``"pending"`` currently mining, block). By default ``"latest"``.
- ``fromBlock`` - ``Number|String``: The number of the earliest block (or any of block tag ``"earliest"``, ``"latest"`` , ``"pending"``, ``"safe"`` or ``"finalized"`` can also be used). By default ``"latest"``.
- ``toBlock`` - ``Number|String``: The number of the latest block (or any of block tag ``"earliest"``, ``"latest"`` , ``"pending"``, ``"safe"`` or ``"finalized"`` can also be used). By default ``"latest"``.
- ``address`` - ``String|Array``: An address or a list of addresses to only get logs from particular account(s).
- ``topics`` - ``Array``: An array of values which must each appear in the log entries. The order is important, if you want to leave topics out use ``null``, e.g. ``[null, '0x12...']``. You can also pass an array for each topic with options for that topic e.g. ``[null, ['option1', 'option2']]``

Expand Down Expand Up @@ -2133,7 +2135,7 @@ Parameters

1. ``String`` 20 Bytes: The Address of the account or contract.
2. ``Number[] | BigNumber[] | BN[] | String[]`` 32 Bytes: Array of storage-keys which should be proofed and included. See :ref:`web3.eth.getStorageAt <eth-getStorageAt>`.
3. ``Number | String | BN | BigNumber``: Integer block number. Pre-defined block numbers as ``"earliest"``, ``"latest"`` and ``"pending"`` can also be used.
3. ``Number | String | BN | BigNumber``: Integer block number. Pre-defined block numbers as ``"earliest"``, ``"latest"`` , ``"pending"``, ``"safe"`` or ``"finalized"`` can also be used.
4. ``Function`` - (optional) Optional callback, returns an error object as first parameter and the result as second.

-------
Expand Down Expand Up @@ -2208,7 +2210,7 @@ Parameters
----------

1. A transaction object, see :ref:`web3.eth.sendTransaction <eth-sendtransaction-return>` with the difference that this method is specifically for contract method executions.
2. ``block`` - ``String|Number|BN|BigNumber`` (optional): The block number or hash. Or the string ``"earliest"``, ``"latest"`` or ``"pending"`` as in the :ref:`default block parameter <eth-defaultblock>`.
2. ``block`` - ``String|Number|BN|BigNumber`` (optional): The block number or hash. Or the string ``"earliest"``, ``"latest"`` , ``"pending"``, ``"safe"`` or ``"finalized"`` as in the :ref:`default block parameter <eth-defaultblock>`.
3. ``callback`` - ``Function`` (optional): This callback will be fired with the result of the access list generation as the second argument, or with an error object as the first argument.


Expand Down
6 changes: 3 additions & 3 deletions packages/web3-core-helpers/src/formatters.js
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ var outputBigNumberFormatter = function (number) {
};

/**
* Returns true if the given blockNumber is 'latest', 'pending', or 'earliest.
* Returns true if the given blockNumber is 'latest', 'pending', 'earliest, 'finalized' or 'safe'
*
* @method isPredefinedBlockNumber
*
Expand All @@ -80,7 +80,7 @@ var outputBigNumberFormatter = function (number) {
* @returns {Boolean}
*/
var isPredefinedBlockNumber = function (blockNumber) {
return blockNumber === 'latest' || blockNumber === 'pending' || blockNumber === 'earliest';
return ['latest','pending','earliest','finalized','safe'].includes(blockNumber);
};

/**
Expand All @@ -101,7 +101,7 @@ var inputDefaultBlockNumberFormatter = function (blockNumber) {
};

/**
* Returns the given block number as hex string or the predefined block number 'latest', 'pending', 'earliest', 'genesis'
* Returns the given block number as hex string or the predefined block number 'latest', 'pending', 'earliest', 'finalized', 'safe', 'genesis'
*
* @param {String|Number|BN|BigNumber} blockNumber
*
Expand Down
2 changes: 1 addition & 1 deletion packages/web3-core/types/index.d.ts
Original file line number Diff line number Diff line change
Expand Up @@ -433,7 +433,7 @@ export interface LogsOptions {
topics?: Array<string | string[] | null>;
}

export type BlockNumber = string | number | BN | BigNumber | 'latest' | 'pending' | 'earliest' | 'genesis';
export type BlockNumber = string | number | BN | BigNumber | 'latest' | 'pending' | 'earliest' | 'genesis' | 'finalized' | 'safe';

export interface RequestArguments {
method: string;
Expand Down
Loading