Provider
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, getTransactionCount, code and state trie storage.
Simulating execution can be used to call, estimateGas and get transaction result.
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.
Extends
Properties
| Property | Type | Description | Overrides | Inherited from |
|---|---|---|---|---|
provider | Provider | The provider iteself. 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. | ContractRunner.provider | ContractRunner.provider |
sendTransaction? | (tx: TransactionRequest) => Promise<TransactionResponse> | Required for state mutating calls | ContractRunner.sendTransaction | ContractRunner.sendTransaction |
Methods
addListener()
addListener(
event,
listener,
zone?): Promise<Provider>
Alias for on.
Parameters
| Parameter | Type |
|---|---|
event | ProviderEvent |
listener | Listener |
zone? | Zone |
Returns
Promise<Provider>
Inherited from
Source
broadcastTransaction()
broadcastTransaction(
zone,
signedTx,
from?): 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.
Parameters
| Parameter | Type | Description |
|---|---|---|
zone | Zone | The zone to broadcast the transaction to. |
signedTx | string | The signed transaction to broadcast. |
from? | AddressLike | The address that signed the transaction. |
Returns
Promise<TransactionResponse>
A promise resolving to the transaction response.
Throws
If the transaction is invalid or the transaction is replaced.
Source
call()
call(tx): Promise<string>
Simulate the execution of tx. If the call reverts, it will throw a
CallExceptionError which includes the revert data.
Parameters
| Parameter | Type | Description |
|---|---|---|
tx | TransactionRequest | The transaction to simulate. |
Returns
Promise<string>
A promise resolving to the result of the execution.
Overrides
ContractRunner.call
Throws
If the transaction execution reverts.
Source
destroy()
destroy(): void
Shutdown any resources this provider is using. No additional calls should be made to this provider after calling this.
Returns
void
Source
emit()
emit(
event,
zone?, ...
args?): Promise<boolean>
Triggers each listener for event with the args.
Parameters
| Parameter | Type |
|---|---|
event | ProviderEvent |
zone? | Zone |
…args? | any[] |
Returns
Promise<boolean>
Inherited from
Source
estimateGas()
estimateGas(tx): Promise<bigint>
Estimates the amount of gas required to executre tx.
Parameters
| Parameter | Type | Description |
|---|---|---|
tx | TransactionRequest | The transaction to estimate the gas for. |
Returns
Promise<bigint>
A promise resolving to the estimated gas.
Overrides
ContractRunner.estimateGas
Throws
If the transaction execution reverts.
Source
getBalance()
getBalance(address, 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.
Parameters
| Parameter | Type | Description |
|---|---|---|
address | AddressLike | The address to fetch the balance for. |
blockTag? | BlockTag | The block tag to fetch the balance from. |
Returns
Promise<bigint>
A promise resolving to the balance.
Note
On nodes without archive access enabled, the blockTag may be
silently ignored by the node, which may cause issues if relied on.
Source
getBlock()
getBlock(
shard,
blockHashOrBlockTag,
prefetchTxs?): 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.
Parameters
| Parameter | Type | Description |
|---|---|---|
shard | Shard | The shard to fetch the block from. |
blockHashOrBlockTag | BlockTag | The block hash or block tag to fetch. |
prefetchTxs? | boolean | If true, prefetch the transactions. |
Returns
Promise<null | Block>
A promise resolving to the block or null if not found.
Throws
If the block is not found.
Source
getBlockNumber()
getBlockNumber(shard): Promise<number>
Get the current block number.
Parameters
| Parameter | Type | Description |
|---|---|---|
shard | Shard | The shard to fetch the block number from. |
Returns
Promise<number>
A promise resolving to the block number.
Source
getCode()
getCode(address, blockTag?): Promise<string>
Get the bytecode for address.
Parameters
| Parameter | Type | Description |
|---|---|---|
address | AddressLike | The address to fetch the code for. |
blockTag? | BlockTag | The block tag to fetch the code from. |
Returns
Promise<string>
A promise resolving to the code stored at the address.
Note
On nodes without archive access enabled, the blockTag may be
silently ignored by the node, which may cause issues if relied on.
Source
getFeeData()
getFeeData(zone): Promise<FeeData>
Get the best guess at the recommended FeeData.
Parameters
| Parameter | Type | Description |
|---|---|---|
zone | Zone | The shard to fetch the fee data from. |
Returns
Promise<FeeData>
A promise resolving to the fee data.
Source
getLogs()
getLogs(filter): Promise<Log[]>
Resolves to the list of Logs that match filter
Parameters
| Parameter | Type | Description |
|---|---|---|
filter | Filter | FilterByBlockHash | The filter to apply. |
Returns
Promise<Log[]>
A promise resolving to the logs.
Source
getNetwork()
getNetwork(): Promise<Network>
Get the connected Network.
Returns
Promise<Network>
A promise resolving to the network.
Source
getOutpointsByAddress()
getOutpointsByAddress(address): Promise<Outpoint[]>
Get the UTXO entries for address.
Parameters
| Parameter | Type | Description |
|---|---|---|
address | AddressLike | The address to fetch the UTXO entries for. |
Returns
Promise<Outpoint[]>
A promise resolving to the UTXO entries.
Note
On nodes without archive access enabled, the blockTag may be
silently ignored by the node, which may cause issues if relied on.
Source
getPendingHeader()
getPendingHeader(): Promise<WorkObjectLike>
Get a work object to package a transaction in.
Returns
Promise<WorkObjectLike>
A promise resolving to the work object.
Source
getProtocolExpansionNumber()
getProtocolExpansionNumber(): Promise<number>
Resolves to the number indicating the size of the network
Returns
Promise<number>
A promise resolving to the current network size.
Source
getStorage()
getStorage(
address,
position,
blockTag?): Promise<string>
Get the storage slot value for address at slot position.
Parameters
| Parameter | Type | Description |
|---|---|---|
address | AddressLike | The address to fetch the storage from. |
position | BigNumberish | The position to fetch the storage from. |
blockTag? | BlockTag | The block tag to fetch the storage from. |
Returns
Promise<string>
A promise resolving to the storage value.
Note
On nodes without archive access enabled, the blockTag may be
silently ignored by the node, which may cause issues if relied on.
Source
getTransaction()
getTransaction(hash): 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.
Parameters
| Parameter | Type | Description |
|---|---|---|
hash | string | The transaction hash to fetch. |
Returns
Promise<null | TransactionResponse>
A promise resolving to the transaction or null if not found.
Source
getTransactionCount()
getTransactionCount(address, 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.
Parameters
| Parameter | Type | Description |
|---|---|---|
address | AddressLike | The address to fetch the transaction count for. |
blockTag? | BlockTag | The block tag to fetch the transaction count from. |
Returns
Promise<number>
A promise resolving to the transaction count.
Note
On nodes without archive access enabled, the blockTag may be
silently ignored by the node, which may cause issues if relied on.
Source
getTransactionReceipt()
getTransactionReceipt(hash): 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.
Parameters
| Parameter | Type | Description |
|---|---|---|
hash | string | The transaction hash to fetch the receipt for. |
Returns
Promise<null | TransactionReceipt>
A promise resolving to the transaction receipt or null if not found.
Source
getTransactionResult()
getTransactionResult(hash): 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.
Parameters
| Parameter | Type | Description |
|---|---|---|
hash | string | The transaction hash to fetch the result for. |
Returns
Promise<null | string>
A promise resolving to the result or null if not found.
Source
getTxPoolContent()
getTxPoolContent(zone): Promise<txpoolContentResponse>
Resolves to the current content of the transaction pool.
Parameters
| Parameter | Type |
|---|---|
zone | Zone |
Returns
Promise<txpoolContentResponse>
A promise resolving to the transaction pool content.
Source
listenerCount()
listenerCount(event?): Promise<number>
Resolves to the number of listeners for event.
Parameters
| Parameter | Type |
|---|---|
event? | ProviderEvent |
Returns
Promise<number>
Inherited from
EventEmitterable.listenerCount
Source
listeners()
listeners(event?): Promise<Listener[]>
Resolves to the listeners for event.
Parameters
| Parameter | Type |
|---|---|
event? | ProviderEvent |
Returns
Promise<Listener[]>
Inherited from
Source
off()
off(
event,
listener?,
zone?): Promise<Provider>
Unregister the listener for event. If listener is unspecified, all listeners are unregistered.
Parameters
| Parameter | Type |
|---|---|
event | ProviderEvent |
listener? | Listener |
zone? | Zone |
Returns
Promise<Provider>
Inherited from
Source
on()
on(
event,
listener,
zone?): Promise<Provider>
Registers a listener that is called whenever the event occurs until unregistered.
Parameters
| Parameter | Type |
|---|---|
event | ProviderEvent |
listener | Listener |
zone? | Zone |
Returns
Promise<Provider>
Inherited from
Source
once()
once(
event,
listener,
zone?): Promise<Provider>
Registers a listener that is called the next time event occurs.
Parameters
| Parameter | Type |
|---|---|
event | ProviderEvent |
listener | Listener |
zone? | Zone |
Returns
Promise<Provider>
Inherited from
Source
removeAllListeners()
removeAllListeners(event?): Promise<Provider>
Unregister all listeners for event.
Parameters
| Parameter | Type |
|---|---|
event? | ProviderEvent |
Returns
Promise<Provider>
Inherited from
EventEmitterable.removeAllListeners
Source
removeListener()
removeListener(
event,
listener,
zone?): Promise<Provider>
Alias for off.
Parameters
| Parameter | Type |
|---|---|
event | ProviderEvent |
listener | Listener |
zone? | Zone |
Returns
Promise<Provider>
Inherited from
EventEmitterable.removeListener
Source
txPoolInspect()
txPoolInspect(zone): Promise<txpoolInspectResponse>
Resolves to the current content of the transaction pool.
Parameters
| Parameter | Type |
|---|---|
zone | Zone |
Returns
Promise<txpoolInspectResponse>
A promise resolving to the transaction pool inspect.
Source
waitForBlock()
waitForBlock(shard, 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.
Parameters
| Parameter | Type | Description |
|---|---|---|
shard | Shard | The shard to fetch the block from. |
blockTag? | BlockTag | The block tag to fetch. |
Returns
Promise<Block>
A promise resolving to the block.
Source
waitForTransaction()
waitForTransaction(
hash,
confirms?,
timeout?): Promise<null | TransactionReceipt>
Waits until the transaction hash is mined and has confirms confirmations.
Parameters
| Parameter | Type | Description |
|---|---|---|
hash | string | The transaction hash to wait for. |
confirms? | number | The number of confirmations to wait for. |
timeout? | number | The number of milliseconds to wait before timing out. |
Returns
Promise<null | TransactionReceipt>
A promise resolving to the transaction receipt or null if not found.
Source
Was this page helpful?