A Provider provides a connection to the blockchain, whch can be used to query its current state, simulate execution and send transactions to update the state.
It is one of the most fundamental components of interacting with a blockchain application, and there are many ways to connect, such as over HTTP, WebSockets or injected providers such as MetaMask.
A BlockTag specifies a specific block.
numeric value - specifies the block height, where the genesis block is block 0; many operations accept a negative value which indicates the block number should be deducted from the most recent block. A numeric value may be a number, bigint, or a decimal of hex string.
blockhash - specifies a specific block by its blockhash; this allows potentially orphaned blocks to be specifed, without ambiguity, but many backends do not support this for some operations.
The possible additional events dispatched when using the "debug" event on a BrowserProvider.
The gas cost parameters for a GasCostPlugin.
A ProviderEvent provides the types of events that can be subscribed to on a Provider.
Each provider may include additional possible events it supports, but the most commonly supported are:
"block" - calls the listener with the current block number on each new block.
"error" - calls the listener on each async error that occurs during the event loop, with the error.
"debug" - calls the listener on debug events, which can be used to troubleshoot network errors, provider problems, etc.
transaction hash - calls the listener on each block after the transaction has been mined; generally .once is more appropriate for this event.
Array - calls the listener on each log that matches the filter.
EventFilter - calls the listener with each matching log
Returns the complete transactions for blocks which prefetched them, by passing true to prefetchTxs into provider.getBlock.
Returns true if this block been mined. This provides a type guard for all properties on a MinedBlock.
A BrowserProvider is intended to wrap an injected provider which adheres to the EIP-1193 standard, which most (if not all) currently do.
The provider used for necessary state querying operations.
This can also point to the ContractRunner itself, in the case of an AbstractProvider.
The interface to an EIP-1193 provider, which is a standard used by most injected providers, which the BrowserProvider accepts and exposes the API of.
See EIP-1193 for details on this method.
An EnsPlugin allows a Network to specify the ENS Registry Contract address and the target network to use when using that contract.
Various testnets have their own instance of the contract to use, but in general, the mainnet instance supports multi-chain addresses and should be used.
The maximum fee to pay per gas.
The base fee per gas is defined by the network and based on congestion, increasing the cost during times of heavy load and lowering when less busy.
The actual fee per gas will be the base fee for the block and the priority fee, up to the max fee per gas.
This will be null on legacy networks (i.e. pre-EIP-1559)
The additional amout to pay per gas to encourage a validator to include the transaction.
The purpose of this is to compensate the validator for the adjusted risk for including a given transaction.
This will be null on legacy networks (i.e. pre-EIP-1559)
A FeeDataNetworkPlugin allows a network to provide and alternate means to specify its fee data.
For example, a network which does not support EIP-1559 may choose to use a Gas Station site to approximate the gas price.
The fee per address in the EIP-2930 access list.
The fee per storage key in the EIP-2930 access list.
The block hash of the block this log occurred in. Use the log.getBlock to get the Block.
The block number of the block this log occurred in. It is preferred to use the block.hash when fetching the related Block, since in the case of an orphaned block, the block at that height may have changed.
The indexed topics included in this log when it was emitted.
All topics are included in the bloom filters, so they can be efficiently filtered using the provider.getLogs method.
The transaction hash of the transaction this log occurred in. Use the log.getTransaction to get the TransactionResponse.
An Interface to indicate a Block has been included in the blockchain. This asserts a Type Guard that necessary properties are non-null.
A NetworkPlugin provides additional functionality on a Network.
A NonceManager wraps another Signer and automatically manages the nonce, ensuring serialized and sequential nonces are used during transaction.
A PreparedTransactionRequest is identical to a TransactionRequest except all the property types are strictly enforced.
The EIP-2930 access list. Storage slots included in the access list are warmed by pre-loading them, so their initial cost to fetch is guaranteed, but then each additional access is cheaper.
When using call, this enables CCIP-read, which permits the provider to be redirected to web-based content during execution, which is then further validated by the contract.
There are potential security implications allowing CCIP-read, as it could be used to expose the IP address or user activity during the fetch to unexpected parties.
The EIP-1559 maximum total fee to pay per gas. The actual value used is protocol enforced to be the block's base fee.
The EIP-1559 maximum priority fee to pay per gas.
A Provider is the primary method to interact with the read-only content on Ethereum.
It allows access to details about accounts, blocks and transactions and the ability to query event logs and simulate contract execution.
Account data includes the balance, transaction count, code and state trie storage.
Simulating execution can be used to call, estimate gas and get transaction results.
The broadcastTransaction is the only method which allows updating the blockchain, but it is usually accessed by a Signer, since a private key must be used to sign the transaction before it can be broadcast.
This is part of the necessary API for executing a contract, as it provides a common property on any ContractRunner that can be used to access the read-only portion of the runner.
Simulate the execution of tx. If the call reverts, it will throw a CallExceptionError which includes the revert data.
Get the account balance (in wei) of address. If blockTag is specified and the node supports archive access for that blockTag, the balance is as of that BlockTag.
Resolves to the block for blockHashOrBlockTag.
If prefetchTxs, and the backend supports including transactions with block requests, all transactions will be included and the Block object will not need to make remote calls for getting transactions.
Get the number of transactions ever sent for address, which is used as the nonce when sending a transaction. If blockTag is specified and the node supports archive access for that blockTag, the transaction count is as of that BlockTag.
A Signer represents an account on the Ethereum Blockchain, and is most often backed by a private key represented by a mnemonic or residing on a Hardware Wallet.
The API remains abstract though, so that it can deal with more advanced exotic Signing entities, such as Smart Contract Wallets or Virtual Wallets (where the private key may not be known).
Evaluates the tx by running it against the current Blockchain state. This cannot change state and has no cost in ether, as it is effectively simulating execution.
This can be used to have the Blockchain perform computations based on its state (e.g. running a Contract's getters) or to simulate the effect of a transaction before actually performing an operation.
Estimates the required gas required to execute tx on the Blockchain. This will be the expected amount a transaction will require as its gasLimit to successfully run all the necessary computations and store the needed state that the transaction intends.
Keep in mind that this is best efforts, since the state of the Blockchain is in flux, which could affect transaction gas requirements.
Prepares a {@link TransactionRequest} for sending to the network by populating any missing properties:
- resolves to and from addresses
- if from is specified , check that it matches this Signer
- populates nonce via signer.getNonce("pending")
- populates gasLimit via signer.estimateGas(tx)
- populates chainId via signer.provider.getNetwork()
- populates type and relevant fee data for that type (gasPrice for legacy transactions, maxFeePerGas for EIP-1559, etc)
Signers an EIP-191 prefixed personal message.
If the message is a string, it is signed as UTF-8 encoded bytes. It is not interpretted as a BytesLike; so the string "0x1234" is signed as six characters, not two bytes.
To sign that example as two bytes, the Uint8Array should be used (i.e. new Uint8Array([ 0x12, 0x34 ])).
Signs the EIP-712 typed data.
The block hash of the Block this transaction was included in.
The block number of the Block this transaction was included in.
The actual gas price used during execution.
Due to the complexity of EIP-1559 this value can only be caluclated after the transaction has been mined, snce the base fee is protocol-enforced.
The EIP-2930 access list. Storage slots included in the access list are warmed by pre-loading them, so their initial cost to fetch is guaranteed, but then each additional access is cheaper.
When using call, this enables CCIP-read, which permits the provider to be redirected to web-based content during execution, which is then further validated by the contract.
There are potential security implications allowing CCIP-read, as it could be used to expose the IP address or user activity during the fetch to unexpected parties.
The EIP-1559 maximum total fee to pay per gas. The actual value used is protocol enforced to be the block's base fee.
The EIP-1559 maximum priority fee to pay per gas.
A TransactionResponse includes all properties about a transaction that was sent to the network, which may or may not be included in a block.
The transactionResponse.isMined can be used to check if the transaction has been mined as well as type guard that the otherwise possibly null properties are defined.
The EIP-2930 access list for transaction types that support it, otherwise null.
The sender of this transaction. It is implicitly computed from the transaction pre-image hash (as the digest) and the signature using ecrecover.
The gas price can have various values, depending on the network.
In modern networks, for transactions that are included this is the effective gas price (the fee per gas that was actually charged), while for transactions that have not been included yet is the maxFeePerGas.
For legacy transactions, or transactions on legacy networks, this is the fee that will be charged per unit of gas the transaction consumes.
The nonce, which is used to prevent replay attacks and offer a method to ensure transactions from a given sender are explicitly ordered.
When sending a transaction, this must be equal to the number of transactions ever sent by from.
The receiver of this transaction.
If null, then the transaction is an initcode transaction. This means the result of executing the data will be deployed as a new contract on chain (assuming it does not revert) and the address may be computed using getCreateAddress.
The EIP-2718 transaction envelope type. This is 0 for legacy transactions types.
The value, in wei. Use formatEther to format this value as ether.
Returns true if the transaction is a Berlin (i.e. type == 1) transaction. See EIP-2930.
This provides a Type Guard that this transaction will have the null-ness for hardfork-specific properties set correctly.
Returns true if the transaction is a London (i.e. type == 2) transaction. See EIP-1559.
This provides a Type Guard that this transaction will have the null-ness for hardfork-specific properties set correctly.
Returns true if this transaction has been included.
This is effective only as of the time the TransactionResponse was instantiated. To get up-to-date information, use getTransaction.
This provides a Type Guard that this transaction will have non-null property values for properties that are null for unmined transactions.
Returns a new TransactionResponse instance which has the ability to detect (and throw an error) if the transaction is replaced, which will begin scanning at startBlock.
This should generally not be used by developers and is intended primarily for internal use. Setting an incorrect startBlock can have devastating performance consequences if used incorrectly.
A JSON-RPC provider which is backed by a WebSocket.
WebSockets are often preferred because they retain a live connection to a server, which permits more instant access to events.
However, this incurs higher server infrasturture costs, so additional resources may be required to host your own WebSocket nodes and many third-party services charge additional fees for WebSocket endpoints.
A Networkish can be used to allude to a Network, by specifing:
- a Network object
- a well-known (or registered) network name
- a well-known (or registered) chain ID
- an object with sufficient details to describe a network