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

PropertyTypeDescriptionOverridesInherited from
providerProviderThe 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.providerContractRunner.provider
sendTransaction?(tx: TransactionRequest) => Promise<TransactionResponse>Required for state mutating callsContractRunner.sendTransactionContractRunner.sendTransaction

Methods

addListener()

addListener(
   event, 
   listener, 
zone?): Promise<Provider>

Alias for on.

Parameters

ParameterType
eventProviderEvent
listenerListener
zone?Zone

Returns

Promise<Provider>

Inherited from

EventEmitterable.addListener

Source

utils/events.ts:61


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

ParameterTypeDescription
zoneZoneThe zone to broadcast the transaction to.
signedTxstringThe signed transaction to broadcast.
from?AddressLikeThe 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

providers/provider.ts:2850


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

ParameterTypeDescription
txTransactionRequestThe 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

providers/provider.ts:2838


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

providers/provider.ts:2721


emit()

emit(
   event, 
   zone?, ...
args?): Promise<boolean>

Triggers each listener for event with the args.

Parameters

ParameterType
eventProviderEvent
zone?Zone
…args?any[]

Returns

Promise<boolean>

Inherited from

EventEmitterable.emit

Source

utils/events.ts:36


estimateGas()

estimateGas(tx): Promise<bigint>

Estimates the amount of gas required to executre tx.

Parameters

ParameterTypeDescription
txTransactionRequestThe 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

providers/provider.ts:2828


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

ParameterTypeDescription
addressAddressLikeThe address to fetch the balance for.
blockTag?BlockTagThe 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

providers/provider.ts:2770


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

ParameterTypeDescription
shardShardThe shard to fetch the block from.
blockHashOrBlockTagBlockTagThe block hash or block tag to fetch.
prefetchTxs?booleanIf 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

providers/provider.ts:2867


getBlockNumber()

getBlockNumber(shard): Promise<number>

Get the current block number.

Parameters

ParameterTypeDescription
shardShardThe shard to fetch the block number from.

Returns

Promise<number>

A promise resolving to the block number.

Source

providers/provider.ts:2732


getCode()

getCode(address, blockTag?): Promise<string>

Get the bytecode for address.

Parameters

ParameterTypeDescription
addressAddressLikeThe address to fetch the code for.
blockTag?BlockTagThe 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

providers/provider.ts:2804


getFeeData()

getFeeData(zone): Promise<FeeData>

Get the best guess at the recommended FeeData.

Parameters

ParameterTypeDescription
zoneZoneThe shard to fetch the fee data from.

Returns

Promise<FeeData>

A promise resolving to the fee data.

Source

providers/provider.ts:2748


getLogs()

getLogs(filter): Promise<Log[]>

Resolves to the list of Logs that match filter

Parameters

ParameterTypeDescription
filterFilter | FilterByBlockHashThe filter to apply.

Returns

Promise<Log[]>

A promise resolving to the logs.

Source

providers/provider.ts:2910


getNetwork()

getNetwork(): Promise<Network>

Get the connected Network.

Returns

Promise<Network>

A promise resolving to the network.

Source

providers/provider.ts:2740


getOutpointsByAddress()

getOutpointsByAddress(address): Promise<Outpoint[]>

Get the UTXO entries for address.

Parameters

ParameterTypeDescription
addressAddressLikeThe 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

providers/provider.ts:2780


getPendingHeader()

getPendingHeader(): Promise<WorkObjectLike>

Get a work object to package a transaction in.

Returns

Promise<WorkObjectLike>

A promise resolving to the work object.

Source

providers/provider.ts:2755


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

providers/provider.ts:2939


getStorage()

getStorage(
   address, 
   position, 
blockTag?): Promise<string>

Get the storage slot value for address at slot position.

Parameters

ParameterTypeDescription
addressAddressLikeThe address to fetch the storage from.
positionBigNumberishThe position to fetch the storage from.
blockTag?BlockTagThe 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

providers/provider.ts:2816


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

ParameterTypeDescription
hashstringThe transaction hash to fetch.

Returns

Promise<null | TransactionResponse>

A promise resolving to the transaction or null if not found.

Source

providers/provider.ts:2877


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

ParameterTypeDescription
addressAddressLikeThe address to fetch the transaction count for.
blockTag?BlockTagThe 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

providers/provider.ts:2793


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

ParameterTypeDescription
hashstringThe transaction hash to fetch the receipt for.

Returns

Promise<null | TransactionReceipt>

A promise resolving to the transaction receipt or null if not found.

Source

providers/provider.ts:2889


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

ParameterTypeDescription
hashstringThe transaction hash to fetch the result for.

Returns

Promise<null | string>

A promise resolving to the result or null if not found.

Source

providers/provider.ts:2899


getTxPoolContent()

getTxPoolContent(zone): Promise<txpoolContentResponse>

Resolves to the current content of the transaction pool.

Parameters

ParameterType
zoneZone

Returns

Promise<txpoolContentResponse>

A promise resolving to the transaction pool content.

Source

providers/provider.ts:2946


listenerCount()

listenerCount(event?): Promise<number>

Resolves to the number of listeners for event.

Parameters

ParameterType
event?ProviderEvent

Returns

Promise<number>

Inherited from

EventEmitterable.listenerCount

Source

utils/events.ts:41


listeners()

listeners(event?): Promise<Listener[]>

Resolves to the listeners for event.

Parameters

ParameterType
event?ProviderEvent

Returns

Promise<Listener[]>

Inherited from

EventEmitterable.listeners

Source

utils/events.ts:46


off()

off(
   event, 
   listener?, 
zone?): Promise<Provider>

Unregister the listener for event. If listener is unspecified, all listeners are unregistered.

Parameters

ParameterType
eventProviderEvent
listener?Listener
zone?Zone

Returns

Promise<Provider>

Inherited from

EventEmitterable.off

Source

utils/events.ts:51


on()

on(
   event, 
   listener, 
zone?): Promise<Provider>

Registers a listener that is called whenever the event occurs until unregistered.

Parameters

ParameterType
eventProviderEvent
listenerListener
zone?Zone

Returns

Promise<Provider>

Inherited from

EventEmitterable.on

Source

utils/events.ts:26


once()

once(
   event, 
   listener, 
zone?): Promise<Provider>

Registers a listener that is called the next time event occurs.

Parameters

ParameterType
eventProviderEvent
listenerListener
zone?Zone

Returns

Promise<Provider>

Inherited from

EventEmitterable.once

Source

utils/events.ts:31


removeAllListeners()

removeAllListeners(event?): Promise<Provider>

Unregister all listeners for event.

Parameters

ParameterType
event?ProviderEvent

Returns

Promise<Provider>

Inherited from

EventEmitterable.removeAllListeners

Source

utils/events.ts:56


removeListener()

removeListener(
   event, 
   listener, 
zone?): Promise<Provider>

Alias for off.

Parameters

ParameterType
eventProviderEvent
listenerListener
zone?Zone

Returns

Promise<Provider>

Inherited from

EventEmitterable.removeListener

Source

utils/events.ts:66


txPoolInspect()

txPoolInspect(zone): Promise<txpoolInspectResponse>

Resolves to the current content of the transaction pool.

Parameters

ParameterType
zoneZone

Returns

Promise<txpoolInspectResponse>

A promise resolving to the transaction pool inspect.

Source

providers/provider.ts:2953


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

ParameterTypeDescription
shardShardThe shard to fetch the block from.
blockTag?BlockTagThe block tag to fetch.

Returns

Promise<Block>

A promise resolving to the block.

Source

providers/provider.ts:2932


waitForTransaction()

waitForTransaction(
   hash, 
   confirms?, 
timeout?): Promise<null | TransactionReceipt>

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

Parameters

ParameterTypeDescription
hashstringThe transaction hash to wait for.
confirms?numberThe number of confirmations to wait for.
timeout?numberThe 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

providers/provider.ts:2921