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 a default provider for network.
If network is a WebSocketLike or string that begins with "ws:" or "wss:", a WebSocketProvider is returned backed by that WebSocket or URL.
If network is a string that begins with "HTTP:" or "HTTPS:", a JsonRpcProvider is returned connected to that URL.
Otherwise, a default provider is created backed by well-known public Web3 backends (such as INFURA) using community-provided API keys.
The options allows specifying custom API keys per backend (setting an API key to "-" will omit that provider) and options.exclusive can be set to either a backend name or and array of backend names, which will whitelist only those backends.
Current backend strings supported are:
- "alchemy"
- "ankr"
- "cloudflare"
- "chainstack"
- "etherscan"
- "infura"
- "publicPolygon"
- "quicknode"
The total amount of blob gas consumed by the transactions within the block. See EIP-4844.
The running total of blob gas consumed in excess of the target, prior to the block. See EIP-4844.
The hash tree root of the parent beacon block for the given execution block. See EIP-4788.
Returns the complete transactions, in the order they were executed within the block.
This is only available for blocks which prefetched transactions, 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.
Discover and connect to a Provider in the Browser using the EIP-6963 discovery mechanism. If no providers are present, null is resolved.
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.
Provider info provided by the EIP-6963 discovery mechanism.
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.
The EIP-7702 authorizations (if any).
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).
Signs an authorization to be used in EIP-7702 transactions.
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 an AuthorizationRequest for authorization by populating any missing properties:
- resolves address (if an Addressable or ENS name)
- populates nonce via signer.getNonce("pending")
- populates chainId via signer.provider.getNetwork()
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)
Signs 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 price paid per BLOB in gas. See EIP-4844.
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.
The EIP-7702 authorizations (if any).
Any blobs to include in the transaction (see EIP-4844).
The blob versioned hashes (see EIP-4844).
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.
An external library for computing the KZG commitments and proofs necessary for EIP-4844 transactions (see EIP-4844).
This is generally null, unless you are creating BLOb transactions.
The maximum fee per blob gas (see EIP-4844).
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 EIP-7702 authorizations (if any).
The EIP-4844 BLOb versioned hashes.
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 hte transaction is a Cancun (i.e. type == 3) transaction. See EIP-4844.
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