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

​

Methods

​

addListener()

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

Alias for on.

​

Parameters

​

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

​

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

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

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

​

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

​

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

​

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

​

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

​

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

​

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

​

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

​

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

​

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

​

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

​

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

​

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

​

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

​

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

​

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

​

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

​

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

​

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

​

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

​

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

​

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

​

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

​

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

​

Returns

Promise<number>

​

Inherited from

EventEmitterable.listenerCount

​

Source

utils/events.ts:41

​

listeners()

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

Resolves to the listeners for event.

​

Parameters

​

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

​

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

​

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

​

Returns

Promise<Provider>

​

Inherited from

EventEmitterable.once

​

Source

utils/events.ts:31

​

removeAllListeners()

removeAllListeners(event?): Promise<Provider>

Unregister all listeners for event.

​

Parameters

​

Returns

Promise<Provider>

​

Inherited from

EventEmitterable.removeAllListeners

​

Source

utils/events.ts:56

​

removeListener()

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

Alias for off.

​

Parameters

​

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

​

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

​

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

​

Returns

Promise<null | TransactionReceipt>

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

​

Source

providers/provider.ts:2971