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

• ContractRunner.EventEmitterable<ProviderEvent>

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

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

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

providers/provider.ts:2900

---

calculateConversionAmount()

calculateConversionAmount(from, to, value)

calculateConversionAmount(
   from, 
   to, 
value): Promise<bigint>

Calculate the conversion amount between two addresses from different ledgers.

Parameters

Parameter	Type	Description
from	string	The source address
to	string	The destination address
value	BigNumberish	The amount to convert

Returns

Promise<bigint>

A promise resolving to the converted amount

Source

providers/provider.ts:3047

calculateConversionAmount(transactionArgs)

calculateConversionAmount(transactionArgs): Promise<bigint>

Calculate the conversion amount between two addresses from different ledgers.

Parameters

Parameter	Type	Description
transactionArgs	ConversionTransactionRequest	The transaction arguments containing from, to, and value

Returns

Promise<bigint>

A promise resolving to the converted amount

Source

providers/provider.ts:3055

---

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

providers/provider.ts:2888

---

createAccessList()

createAccessList(tx): Promise<AccessList>

Required for populating access lists for state mutating calls

Parameters

Parameter	Type	Description
tx	QuaiTransactionRequest

Returns

Promise<AccessList>

Overrides

ContractRunner.createAccessList

Source

providers/provider.ts:2878

---

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:2746

---

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

EventEmitterable.emit

Source

utils/events.ts:36

---

estimateFeeForQi()

estimateFeeForQi(tx): Promise<bigint>

Estimate the fee for a Qi transaction.

Parameters

Parameter	Type	Description
tx	QiPerformActionTransaction	The transaction to estimate the fee for.

Returns

Promise<bigint>

A promise resolving to the estimated fee.

Source

providers/provider.ts:2870

---

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

providers/provider.ts:2862

---

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

providers/provider.ts:2796

---

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

providers/provider.ts:2917

---

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

providers/provider.ts:2757

---

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

providers/provider.ts:2838

---

getFeeData()

getFeeData(zone, txType): Promise<FeeData>

Get the best guess at the recommended FeeData.

Parameters

Parameter	Type	Description
zone	Zone	The shard to fetch the fee data from.
txType	boolean	The transaction type to fetch the fee data for (true for Quai, false for Qi)

Returns

Promise<FeeData>

A promise resolving to the fee data.

Source

providers/provider.ts:2774

---

getLatestQiToQuaiRate()

getLatestQiToQuaiRate(zone, amt): Promise<bigint>

Resolves to the current Quai rate for the given amount.

Parameters

Parameter	Type	Description
zone	Zone	-
amt	bigint	The amount in quais to get the rate for.

Returns

Promise<bigint>

A promise resolving to the latest Quai rate.

Source

providers/provider.ts:3019

---

getLatestQuaiToQiRate()

getLatestQuaiToQiRate(zone, amt): Promise<bigint>

Resolves to the current Quai rate for the given amount.

Parameters

Parameter	Type	Description
zone	Zone	-
amt	bigint	The amount in quai to get the rate for.

Returns

Promise<bigint>

A promise resolving to the latest Quai->Qi rate.

Source

providers/provider.ts:3035

---

getLockedBalance()

getLockedBalance(address): Promise<bigint>

Get the locked balance for address.

Parameters

Parameter	Type	Description
address	AddressLike	The address to fetch the locked balance for.

Returns

Promise<bigint>

A promise resolving to the locked balance.

Source

providers/provider.ts:2804

---

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

providers/provider.ts:2960

---

getNetwork()

getNetwork(): Promise<Network>

Get the connected Network.

Returns

Promise<Network>

A promise resolving to the network.

Source

providers/provider.ts:2765

---

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

providers/provider.ts:2814

---

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:2781

---

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:2989

---

getQiToQuaiRateAtBlock()

getQiToQuaiRateAtBlock(
   zone, 
   blockTag, 
amt): Promise<bigint>

Resolves to the current Quai rate for the given amount.

Parameters

Parameter	Type	Description
zone	Zone	-
blockTag	BlockTag	-
amt	bigint	The amount in quais to get the rate for.

Returns

Promise<bigint>

A promise resolving to the latest Quai rate.

Source

providers/provider.ts:3011

---

getQuaiToQiRateAtBlock()

getQuaiToQiRateAtBlock(
   zone, 
   blockTag, 
amt): Promise<bigint>

Resolves to the current Quai rate for the given amount.

Parameters

Parameter	Type	Description
zone	Zone	-
blockTag	BlockTag	-
amt	bigint	The amount in quais to get the rate for.

Returns

Promise<bigint>

A promise resolving to the latest Quai rate.

Source

providers/provider.ts:3027

---

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

providers/provider.ts:2850

---

getTransaction()

getTransaction(hash): Promise<null | TransactionResponse | ExternalTransactionResponse>

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 | ExternalTransactionResponse>

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

Source

providers/provider.ts:2927

---

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

providers/provider.ts:2827

---

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

providers/provider.ts:2939

---

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

providers/provider.ts:2949

---

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

providers/provider.ts:2996

---

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

utils/events.ts:41

---

listeners()

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

Resolves to the listeners for event.

Parameters

Parameter	Type
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

Parameter	Type
event	ProviderEvent
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

Parameter	Type
event	ProviderEvent
listener	Listener
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

Parameter	Type
event	ProviderEvent
listener	Listener
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

Parameter	Type
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

Parameter	Type
event	ProviderEvent
listener	Listener
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

Parameter	Type
zone	Zone

Returns

Promise<txpoolInspectResponse>

A promise resolving to the transaction pool inspect.

Source

providers/provider.ts:3003

---

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

providers/provider.ts:2982

---

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

providers/provider.ts:2971