Documentation

Providers

About providers.

<src>BlockTag⇒ number | string

<src>DebugEventBrowserProvider⇒ { action: "sendEip1193Payload" , payload: { method: string , params: Array< any > } } | { action: "receiveEip1193Result" , result: any } | { action: "receiveEip1193Error" , error: Error }

<src>GasCostParameters⇒ { txAccessListAddress?: number , txAccessListStorageKey?: number , txBase?: number , txCreate?: number , txDataNonzero?: number , txDataZero?: number }

<src>OrphanFilter⇒ { hash: string , number: number , orphan: "drop-block" } | { orphan: "drop-transaction" , other?: { blockHash: string , blockNumber: number , hash: string } , tx: { blockHash: string , blockNumber: number , hash: string } } | { orphan: "reorder-transaction" , other?: { blockHash: string , blockNumber: number , hash: string } , tx: { blockHash: string , blockNumber: number , hash: string } } | { log: { address: string , blockHash: string , blockNumber: number , data: string , index: number , topics: ReadonlyArray< string > , transactionHash: string } , orphan: "drop-log" }

<src>ProviderEvent⇒ string | Array< string | Array< string > > | EventFilter | OrphanFilter

<src>TopicFilter⇒ Array< null | string | Array< string > >

<src>WebSocketCreator⇒ () => WebSocketLike

<src>copyRequest(req: TransactionRequest)⇒ PreparedTransactionRequest

<src>getDefaultProvider(network: string | Networkish | WebSocketLike, options?: any)⇒ AbstractProvider

<src>class Block

inherits fromBlockParams

A Block represents the data associated with a full block on Ethereum.

<src>block.date⇒ null | Dateread-only

The Date this block was included at.

<src>block.length⇒ numberread-only

The number of transactions in this block.

<src>block.provider⇒ Providerread-only

The provider connected to the block used to fetch additional details if necessary.

<src>block.transactionResponses⇒ Array< TransactionResponse >read-only

Returns the complete transactions for blocks which prefetched them, by passing true to prefetchTxs into provider_getBlock.

<src>new Block(block: BlockParams, provider: Provider)

Create a new Block object.

This should generally not be necessary as the unless implementing a low-level library.

<src>block.getTransaction(indexOrHash: number | string)⇒ Promise< TransactionResponse >

Get the transaction at indexe within this block.

<src>block.getTransactionResponse(indexOrHash: number | string)⇒ TransactionResponse

<src>block.isLondon()⇒ boolean

<src>block.isMined()⇒ boolean

Has this block been mined.

If true, the block has been typed-gaurded that all mined properties are non-null.

<src>block.orphanedEvent()⇒ OrphanFilter

<src>block.toJSON()⇒ any

Returns a JSON-friendly value.

<src>class BrowserProvider

inherits fromJsonRpcApiPollingProvider, JsonRpcApiProvider, AbstractProvider, Provider, ContractRunner, EventEmitterable, NameResolver

<src>new BrowserProvider(ethereum: Eip1193Provider, network?: Networkish)

<src>browserProvider.hasSigner(address: number | string)⇒ Promise< boolean >

<src>interface ContractRunner

<src>contractRunner.call⇒ (tx: TransactionRequest) => Promise< string >

<src>contractRunner.estimateGas⇒ (tx: TransactionRequest) => Promise< bigint >

<src>contractRunner.provider⇒ null | Provider

<src>contractRunner.resolveName⇒ (name: string) => Promise< null | string >

<src>contractRunner.sendTransaction⇒ (tx: TransactionRequest) => Promise< TransactionResponse >

<src>interface Eip1193Provider

<src>eip1193Provider.request(request: { method: string , params?: Array< any > | Record< string, any > })⇒ Promise< any >

<src>class EnsPlugin

inherits fromNetworkPlugin

<src>ensPlugin.address⇒ stringread-only

<src>ensPlugin.targetNetwork⇒ numberread-only

<src>new EnsPlugin(address?: null | string, targetNetwork?: null | number)

<src>interface EventFilter

<src>eventFilter.address⇒ AddressLike | Array< AddressLike >

<src>eventFilter.topics⇒ TopicFilter

<src>class FeeData

A FeeData wraps all the fee-related values associated with the network.

<src>feeData.gasPrice⇒ null | bigintread-only

The gas price for legacy networks.

<src>feeData.maxFeePerGas⇒ null | bigintread-only

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)

<src>feeData.maxPriorityFeePerGas⇒ null | bigintread-only

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)

<src>new FeeData(gasPrice?: null | bigint, maxFeePerGas?: null | bigint, maxPriorityFeePerGas?: null | bigint)

Creates a new FeeData for gasPrice, maxFeePerGas and maxPriorityFeePerGas.

<src>feeData.toJSON()⇒ any

Returns a JSON-friendly value.

<src>class FeeDataNetworkPlugin

inherits fromNetworkPlugin

<src>feeDataNetworkPlugin.feeDataFunc⇒ (provider: Provider) => Promise< FeeData >read-only

<src>new FeeDataNetworkPlugin(feeDataFunc: (provider: Provider) => Promise< FeeData >)

<src>feeDataNetworkPlugin.getFeeData(provider: Provider)⇒ Promise< FeeData >

<src>interface Filter

inherits fromEventFilter

<src>filter.fromBlock⇒ BlockTag

<src>filter.toBlock⇒ BlockTag

<src>interface FilterByBlockHash

inherits fromEventFilter

<src>filterByBlockHash.blockHash⇒ string

<src>class GasCostPlugin

inherits fromNetworkPlugin

<src>gasCostPlugin.effectiveBlock⇒ numberread-only

<src>gasCostPlugin.txAccessListAddress⇒ numberread-only

<src>gasCostPlugin.txAccessListStorageKey⇒ numberread-only

<src>gasCostPlugin.txBase⇒ numberread-only

<src>gasCostPlugin.txCreate⇒ numberread-only

<src>gasCostPlugin.txDataNonzero⇒ numberread-only

<src>gasCostPlugin.txDataZero⇒ numberread-only

<src>new GasCostPlugin(effectiveBlock?: number, costs?: GasCostParameters)

<src>class IpcSocketProvider

inherits fromSocketProvider, JsonRpcApiProvider, AbstractProvider, Provider, ContractRunner, EventEmitterable, NameResolver

<src>ipcSocketProvider.socket⇒ Socketread-only

<src>new IpcSocketProvider(path: string, network?: Networkish)

<src>class Log

inherits fromLogParams

<src>log.provider⇒ Providerread-only

<src>new Log(log: LogParams, provider: Provider)

<src>log.getBlock()⇒ Promise< Block >

<src>log.getTransaction()⇒ Promise< TransactionResponse >

<src>log.getTransactionReceipt()⇒ Promise< TransactionReceipt >

<src>log.removedEvent()⇒ OrphanFilter

<src>log.toJSON()⇒ any

<src>interface MinedBlock

inherits fromBlock, BlockParams

<src>interface MinedTransactionResponse

inherits fromTransactionResponse, TransactionResponseParams

<src>minedTransactionResponse.date⇒ Date

<src>class NetworkPlugin

<src>networkPlugin.name⇒ stringread-only

<src>new NetworkPlugin(name: string)

<src>networkPlugin.clone()⇒ NetworkPlugin

Networks

About networks

<src>Networkish⇒ Network | number | bigint | string | { chainId?: number , ensAddress?: string , ensNetwork?: number , name?: string }

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

<src>class Network

<src>network.chainId⇒ bigint

<src>network.name⇒ string

<src>network.plugins⇒ Array< NetworkPlugin >read-only

<src>new Network(name: string, chainId: BigNumberish)

<src>Network.from(network?: Networkish)⇒ Network

Returns a new Network for the network name or chainId.

<src>network.attachPlugin(plugin: NetworkPlugin)⇒ this

<src>network.clone()⇒ Network

<src>network.computeIntrinsicGas(tx: TransactionLike)⇒ number

<src>network.getPlugin(name: string)⇒ null | T

<src>network.getPlugins(basename: string)⇒ Array< T >

<src>network.toJSON()⇒ any

<src>Network.register(nameOrChainId: string | number | bigint, networkFunc: () => Network)⇒ void

<src>class NonceManager

inherits fromAbstractSigner, Signer, Addressable, ContractRunner, NameResolver

<src>nonceManager.signer⇒ Signer

<src>new NonceManager(signer: Signer)

<src>nonceManager.increment()⇒ void

<src>nonceManager.reset()⇒ void

<src>interface PreparedTransactionRequest

<src>preparedTransactionRequest.accessList⇒ AccessList

<src>preparedTransactionRequest.blockTag⇒ BlockTag

<src>preparedTransactionRequest.chainId⇒ bigint

<src>preparedTransactionRequest.customData⇒ any

<src>preparedTransactionRequest.data⇒ string

<src>preparedTransactionRequest.enableCcipRead⇒ boolean

<src>preparedTransactionRequest.from⇒ AddressLike

<src>preparedTransactionRequest.gasLimit⇒ bigint

<src>preparedTransactionRequest.gasPrice⇒ bigint

<src>preparedTransactionRequest.maxFeePerGas⇒ bigint

<src>preparedTransactionRequest.maxPriorityFeePerGas⇒ bigint

<src>preparedTransactionRequest.nonce⇒ number

<src>preparedTransactionRequest.to⇒ AddressLike

<src>preparedTransactionRequest.type⇒ number

<src>preparedTransactionRequest.value⇒ bigint

<src>interface Provider

inherits fromContractRunner, EventEmitterable, NameResolver

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.

<src>provider.broadcastTransaction(signedTx: string)⇒ Promise< TransactionResponse >

Broadcasts the signedTx to the network, adding it to the memory pool of any node for which the transaction meets the rebroadcast requirements.

<src>provider.destroy()⇒ void

Shutdown any resources this provider is using. No additional calls should be made to this provider after calling this.

<src>provider.getBalance(address: AddressLike, blockTag?: BlockTag)⇒ Promise< bigint >

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.

<src>provider.getBlock(blockHashOrBlockTag: BlockTag | string, prefetchTxs?: boolean)⇒ Promise< null | Block >

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.

<src>provider.getBlockNumber()⇒ Promise< number >

Get the current block number.

<src>provider.getCode(address: AddressLike, blockTag?: BlockTag)⇒ Promise< string >

Get the bytecode for address.

<src>provider.getFeeData()⇒ Promise< FeeData >

Get the best guess at the recommended FeeData.

<src>provider.getLogs(filter: Filter | FilterByBlockHash)⇒ Promise< Array< Log > >

Resolves to the list of Logs that match filter

<src>provider.getNetwork()⇒ Promise< Network >

Get the connected Network.

<src>provider.getStorage(address: AddressLike, position: BigNumberish, blockTag?: BlockTag)⇒ Promise< string >

Get the storage slot value for address at slot position.

<src>provider.getTransaction(hash: string)⇒ Promise< null | TransactionResponse >

Resolves to the transaction for hash.

If the transaction is unknown or on pruning nodes which discard old transactions this resolves to null.

<src>provider.getTransactionCount(address: AddressLike, blockTag?: BlockTag)⇒ Promise< number >

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.

<src>provider.getTransactionReceipt(hash: string)⇒ Promise< null | TransactionReceipt >

Resolves to the transaction receipt for hash, if mined.

If the transaction has not been mined, is unknown or on pruning nodes which discard old transactions this resolves to null.

<src>provider.getTransactionResult(hash: string)⇒ Promise< null | string >

Resolves to the result returned by the executions of hash.

This is only supported on nodes with archive access and with the necessary debug APIs enabled.

<src>provider.lookupAddress(address: string)⇒ Promise< null | string >

Resolves to the ENS name associated for the address or null if the primary name is not configured.

Users must perform additional steps to configure a primary name, which is not currently common.

<src>provider.waitForBlock(blockTag?: BlockTag)⇒ Promise< Block >

Resolves to the block at blockTag once it has been mined.

This can be useful for waiting some number of blocks by using the currentBlockNumber + N.

<src>provider.waitForTransaction(hash: string, confirms?: number, timeout?: number)⇒ Promise< null | TransactionReceipt >

Waits until the transaction hash is mined and has confirms confirmations.

<src>interface Signer

inherits fromAddressable, ContractRunner, NameResolver

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).

<src>signer.connect(provider: null | Provider)⇒ Signer

Returns a new instance of this Signer connected to provider or detached from any Provider if null.

<src>signer.getNonce(blockTag?: BlockTag)⇒ Promise< number >

Gets the next nonce required for this Signer to send a transaction.

<src>signer.populateCall(tx: TransactionRequest)⇒ Promise< TransactionLike < string > >

Prepares a {@link TransactionRequest} for calling:

resolves to and from addresses
if from is specified , check that it matches this Signer

<src>signer.populateTransaction(tx: TransactionRequest)⇒ Promise< TransactionLike < string > >

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)

<src>signer.signMessage(message: string | Uint8Array)⇒ Promise< string >

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 ])).

<src>signer.signTransaction(tx: TransactionRequest)⇒ Promise< string >

Signs tx, returning the fully signed transaction. This does not populate any additional properties within the transaction.

<src>signer.signTypedData(domain: TypedDataDomain, types: Record< string, Array< TypedDataField > >, value: Record< string, any >)⇒ Promise< string >

Signs the EIP-712 typed data.

<src>class TransactionReceipt

inherits fromTransactionReceiptParams

<src>transactionReceipt.fee⇒ bigintread-only

<src>transactionReceipt.length⇒ numberread-only

<src>transactionReceipt.provider⇒ Providerread-only

<src>new TransactionReceipt(tx: TransactionReceiptParams, provider: Provider)

<src>transactionReceipt.confirmations()⇒ Promise< number >

<src>transactionReceipt.getBlock()⇒ Promise< Block >

<src>transactionReceipt.getResult()⇒ Promise< string >

<src>transactionReceipt.getTransaction()⇒ Promise< TransactionResponse >

<src>transactionReceipt.removedEvent()⇒ OrphanFilter

<src>transactionReceipt.reorderedEvent(other?: TransactionResponse)⇒ OrphanFilter

<src>transactionReceipt.toJSON()⇒ any

<src>interface TransactionRequest

<src>transactionRequest.accessList⇒ null | AccessListish

<src>transactionRequest.blockTag⇒ BlockTag

<src>transactionRequest.chainId⇒ null | BigNumberish

<src>transactionRequest.customData⇒ any

<src>transactionRequest.data⇒ null | string

<src>transactionRequest.enableCcipRead⇒ boolean

<src>transactionRequest.from⇒ null | AddressLike

<src>transactionRequest.gasLimit⇒ null | BigNumberish

<src>transactionRequest.gasPrice⇒ null | BigNumberish

<src>transactionRequest.maxFeePerGas⇒ null | BigNumberish

<src>transactionRequest.maxPriorityFeePerGas⇒ null | BigNumberish

<src>transactionRequest.nonce⇒ null | number

<src>transactionRequest.to⇒ null | AddressLike

<src>transactionRequest.type⇒ null | number

<src>transactionRequest.value⇒ null | BigNumberish

<src>class TransactionResponse

inherits fromTransactionResponseParams

<src>transactionResponse.provider⇒ Providerread-only

<src>new TransactionResponse(tx: TransactionResponseParams, provider: Provider)

<src>transactionResponse.getBlock()⇒ Promise< null | Block >

<src>transactionResponse.getTransaction()⇒ Promise< null | TransactionResponse >

<src>transactionResponse.isBerlin()⇒ boolean

<src>transactionResponse.isLegacy()⇒ boolean

<src>transactionResponse.isLondon()⇒ boolean

<src>transactionResponse.isMined()⇒ boolean

<src>transactionResponse.removedEvent()⇒ OrphanFilter

<src>transactionResponse.reorderedEvent(other?: TransactionResponse)⇒ OrphanFilter

<src>transactionResponse.replaceableTransaction(startBlock: number)⇒ TransactionResponse

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.

<src>transactionResponse.toJSON()⇒ any

<src>transactionResponse.wait(confirms?: number, timeout?: number)⇒ Promise< null | TransactionReceipt >

<src>interface WebSocketLike

<src>webSocketLike.onerror⇒ null | PAREN<(args: Array< any >) => any }>

<src>webSocketLike.onmessage⇒ null | PAREN<(args: Array< any >) => any }>

<src>webSocketLike.onopen⇒ null | PAREN<(args: Array< any >) => any }>

<src>webSocketLike.readyState⇒ number

<src>webSocketLike.close(code?: number, reason?: string)⇒ void

<src>webSocketLike.send(payload: any)⇒ void

<src>class WebSocketProvider

inherits fromSocketProvider, JsonRpcApiProvider, AbstractProvider, Provider, ContractRunner, EventEmitterable, NameResolver

<src>webSocketProvider.websocket⇒ WebSocketLikeread-only

<src>new WebSocketProvider(url: string | WebSocketLike | WebSocketCreator, network?: Networkish)