Provider - Quai Network Docs

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

Getting Started

Fundamentals

Reference

​Extends

​Properties

​Methods

​addListener()

​Parameters

​Returns

​Inherited from

​Source

​broadcastTransaction()

​Parameters

​Returns

​Throws

​Source

​calculateConversionAmount()

​calculateConversionAmount(from, to, value)

Parameters

Returns

Source

​calculateConversionAmount(transactionArgs)

Parameters

Returns

Source

​call()

​Parameters

​Returns

​Overrides

​Throws

​Source

​createAccessList()

​Parameters

​Returns

​Overrides

​Source

​destroy()

​Returns

​Source

​emit()

​Parameters

​Returns

​Inherited from

​Source

​estimateFeeForQi()

​Parameters

​Returns

​Source

​estimateGas()

​Parameters

​Returns

​Overrides

​Throws

​Source

​getBalance()

​Parameters

​Returns

​Note

​Source

​getBlock()

​Parameters

​Returns

​Throws

​Source

​getBlockNumber()

​Parameters

​Returns

​Source

​getCode()

​Parameters

​Returns

​Note

​Source

​getFeeData()

​Parameters

​Returns

​Source

​getLatestQiToQuaiRate()

​Parameters

​Returns

Extends

Properties

Methods

addListener()

Parameters

Returns

Inherited from

Source

broadcastTransaction()

Parameters

Returns

Throws

Source

calculateConversionAmount()

calculateConversionAmount(from, to, value)

calculateConversionAmount(transactionArgs)

call()

Parameters

Returns

Overrides

Throws

Source

createAccessList()

Parameters

Returns

Overrides

Source

destroy()

Returns

Source

emit()

Parameters

Returns

Inherited from

Source

estimateFeeForQi()

Parameters

Returns

Source

estimateGas()

Parameters

Returns

Overrides

Throws

Source

getBalance()

Parameters

Returns

Note

Source

getBlock()

Parameters

Returns

Throws

Source

getBlockNumber()

Parameters

Returns

Source

getCode()

Parameters

Returns

Note

Source

getFeeData()

Parameters

Returns

Source

getLatestQiToQuaiRate()

Parameters

Returns

Source

getLatestQuaiToQiRate()

Parameters

Returns

Source

getLockedBalance()

Parameters

Returns

Source