A BlockTag specifies a specific block location in the Blockchain.
"latest"- The most recently mined block"earliest"- Block #0"pending"- The block currently being prepared for mining; not all operations and backends support this BlockTag- number - The block at this height
- a negative number - The block this many blocks ago
- hex string - The block at this height (as a hexidecimal value)
A Networkish may be any of the following:
- a Network object
- the name of a common network as a string (e.g.
"homestead") - the chain ID a network as a number; if the chain ID is that of a common network, the
nameandensAddresswill be populated, otherwise, the default name"unknown"and noensAddressis used
A Network represents an Ethereum network.
The human-readable name of the network, such as homestead. If the network name is unknown, this will be "unknown".
The Chain ID of the network.
The address at which the ENS registry is deployed on this network.
A FeeData object encapsulates the necessary fee data required to send a transaction, based on the best available recommendations.
The gasPrice to use for legacy transactions or networks which do not support EIP-1559.
The maxFeePerGas to use for a transaction. This is based on the most recent block's baseFee.
The maxPriorityFeePerGas to use for a transaction. This accounts for the uncle risk and for the majority of current MEV risk.
The hash of this block.
The hash of the previous block.
The height (number) of this block.
The timestamp of this block.
The nonce used as part of the proof-of-work to mine this block.
This property is generally of little interest to developers.
The difficulty target required to be met by the miner of the block.
Recently the difficulty frequently exceeds the size that a JavaScript number can safely store (53-bits), so in that case this property may be null. It is recommended to use the `_difficulty` property below, which will always return a value, but as a BigNumber.
This property is generally of little interest to developers.
The difficulty target required to be met by the miner of the block, as a BigNumber.
Recently the difficulty frequently exceeds the size that a JavaScript number can safely store (53-bits), so this property was added to safely encode the value for applications that require it.
This property is generally of little interest to developers.
The maximum amount of gas that this block was permitted to use. This is a value that can be voted up or voted down by miners and is used to automatically adjust the bandwidth requirements of the network.
This property is generally of little interest to developers.
The total amount of gas used by all transactions in this block.
The coinbase address of this block, which indicates the address the miner that mined this block would like the subsidy reward to go to.
This is extra data a miner may choose to include when mining a block.
This property is generally of little interest to developers.
Often only the hashes of the transactions included in a block are needed, so by default a block only contains this information, as it is substantially less data.
A list of the transactions hashes for each transaction this block includes.
BlockWithTransactions inherits Block
If all transactions for a block are needed, this object instead includes the full details on each transaction.
A list of the transactions this block includes.
The address to filter by, or null to match any address.
The topics to filter by or null to match any topics.
Each entry represents an AND condition that must match, or may be null to match anything. If a given entry is an Array, then that entry is treated as an OR for any value in the entry.
See Filters for more details and examples on specifying complex filters.
Filter inherits EventFilter
The starting block (inclusive) to search for logs matching the filter criteria.
The end block (inclusive) to search for logs matching the filter criteria.
FilterByBlockHash inherits EventFilter
The specific block (by its block hash) to search for logs matching the filter criteria.
The block height (number) of the block including the transaction of this log.
The block hash of the block including the transaction of this log.
During a re-org, if a transaction is orphaned, this will be set to true to indicate the Log entry has been removed; it will likely be emitted again in the near future when another block is mined with the transaction that triggered this log, but keep in mind the values may change.
The address of the contract that generated this log.
The data included in this log.
The list of topics (indexed properties) for this log.
The transaction hash of the transaction of this log.
The index of the transaction in the block of the transaction of this log.
The index of this log across all logs in the entire block.
A transaction request describes a transaction that is to be sent to the network or otherwise processed.
All fields are optional and may be a promise which resolves to the required type.
The address (or ENS name) this transaction it to.
The address this transaction is from.
The nonce for this transaction. This should be set to the number of transactions ever sent from this address.
The transaction data.
The amount (in wei) this transaction is sending.
The maximum amount of gas this transaction is permitted to use.
If left unspecified, ethers will use estimateGas to determine the value to use. For transactions with unpredicatable gas estimates, this may be required to specify explicitly.
The price (in wei) per unit of gas this transaction will pay.
This may not be specified for transactions with type set to 1 or 2, or if maxFeePerGas or maxPriorityFeePerGas is given.
The maximum price (in wei) per unit of gas this transaction will pay for the combined EIP-1559 block's base fee and this transaction's priority fee.
Most developers should leave this unspecified and use the default value that ethers determines from the network.
This may not be specified for transactions with type set to 0 or if gasPrice is specified..
The price (in wei) per unit of gas this transaction will allow in addition to the EIP-1559 block's base fee to bribe miners into giving this transaction priority. This is included in the maxFeePerGas, so this will not affect the total maximum cost set with maxFeePerGas.
Most developers should leave this unspecified and use the default value that ethers determines from the network.
This may not be specified for transactions with type set to 0 or if gasPrice is specified.
The chain ID this transaction is authorized on, as specified by EIP-155.
If the chain ID is 0 will disable EIP-155 and the transaction will be valid on any network. This can be dangerous and care should be taken, since it allows transactions to be replayed on networks that were possibly not intended. Intentionally-replayable transactions are also disabled by default on recent versions of Geth and require configuration to enable.
The EIP-2718 type of this transaction envelope, or null for to use the network default. To force using a lagacy transaction without an envelope, use type 0.
The AccessList to include; only available for EIP-2930 and EIP-1559 transactions.
TransactionResponse inherits Transaction
A TransactionResponse includes all properties of a Transaction as well as several properties that are useful once it has been mined.
The number ("height") of the block this transaction was mined in. If the block has not been mined, this is null.
The hash of the block this transaction was mined in. If the block has not been mined, this is null.
The timestamp of the block this transaction was mined in. If the block has not been mined, this is null.
The number of blocks that have been mined (including the initial block) since this transaction was mined.
The serialized transaction. This may be null as some backends do not populate it. If this is required, it can be computed from a TransactionResponse object using this cookbook recipe.
Resolves to the TransactionReceipt once the transaction has been included in the chain for confirms blocks. If confirms is 0, and the transaction has not been mined, null is returned.
If the transaction execution failed (i.e. the receipt status is 0), a CALL_EXCEPTION error will be rejected with the following properties:
error.transaction- the original transactionerror.transactionHash- the hash of the transactionerror.receipt- the actual receipt, with the status of0
If the transaction is replaced by another transaction, a TRANSACTION_REPLACED error will be rejected with the following properties:
error.hash- the hash of the original transaction which was replacederror.reason- a string reason; one of"repriced","cancelled"or"replaced"error.cancelled- a boolean; a"repriced"transaction is not considered cancelled, but"cancelled"and"replaced"areerror.replacement- the replacement transaction (a TransactionResponse)error.receipt- the receipt of the replacement transaction (a TransactionReceipt)
Transactions are replaced when the user uses an option in their client to send a new transaction from the same account with the original nonce. This is usually to speed up a transaction or to cancel one, by bribing miners with additional fees to prefer the new transaction over the original one.
The EIP-2718 type of this transaction. If the transaction is a legacy transaction without an envelope, it will have the type 0.
The AccessList included, or null for transaction types which do not support access lists.
The address this transaction is to. This is null if the transaction was an init transaction, used to deploy a contract.
The address this transaction is from.
If this transaction has a null to address, it is an init transaction used to deploy a contract, in which case this is the address created by that contract.
To compute a contract address, the getContractAddress utility function can also be used with a TransactionResponse object, which requires the transaction nonce and the address of the sender.
The index of this transaction in the list of transactions included in the block this transaction was mined in.
The EIP-2718 type of this transaction. If the transaction is a legacy transaction without an envelope, it will have the type 0.
The intermediate state root of a receipt.
Only transactions included in blocks before the Byzantium Hard Fork have this property, as it was replaced by the status property.
The property is generally of little use to developers. At the time it could be used to verify a state transition with a fraud-proof only considering the single transaction; without it the full block must be considered.
The amount of gas actually used by this transaction.
The effective gas price the transaction was charged at.
Prior to EIP-1559 or on chains that do not support it, this value will simply be equal to the transaction gasPrice.
On EIP-1559 chains, this is equal to the block baseFee for the block that the transaction was included in, plus the transaction maxPriorityFeePerGas clamped to the transaction maxFeePerGas.
A bloom-filter, which includes all the addresses and topics included in any log in this transaction.
The block hash of the block that this transaction was included in.
The transaction hash of this transaction.
All the logs emitted by this transaction.
The block height (number) of the block that this transaction was included in.
The number of blocks that have been mined since this transaction, including the actual block it was mined in.
For the block this transaction was included in, this is the sum of the gas used by each transaction in the ordered list of transactions up to (and including) this transaction.
This is generally of little interest to developers.
This is true if the block is in a post-Byzantium Hard Fork block.
The status of a transaction is 1 is successful or 0 if it was reverted. Only transactions included in blocks post-Byzantium Hard Fork have this property.
An Access List is optional an includes a list of addresses and storage slots for that address which should be warmed or pre-fetched for use within the execution of this transaction. A warmed value has an additional upfront cost to access, but is discounted throughout the code execution for reading and writing.
A looser description of an AccessList, which will be converted internally using accessListify.
It may be any of:
- any AccessList
- an Array of 2-element Arrays, where the first element is the address and second array is an array of storage keys
- an object, whose keys represent the addresses and each value is an array of storage keys
When using the object form (the last option), the addresses and storage slots will be sorted. If an explicit order for the access list is required, one of the other forms must be used. Most developers do not require explicit order.
An EIP-2930 transaction allows an optional AccessList which causes a transaction to warm (i.e. pre-cache) another addresses state and the specified storage keys.
This incurs an increased intrinsic cost for the transaction, but provides discounts for storage and state access throughout the execution of the transaction.