FallthroughProvider

Defined in: providers/FallthroughProvider.ts:31

A JSON RPC Provider which moves to the next URL when one fails.

Extends

BaseProvider

Constructors

Constructor

new FallthroughProvider(rpcUrls, options): FallthroughProvider

Defined in: providers/FallthroughProvider.ts:45

Parameters

rpcUrls

string[]

options

ConstructorOptions = {}

Returns

FallthroughProvider

Overrides

BaseProvider.constructor

Methods

call()

call(transaction, blockTag): Promise<string>

Defined in: providers/BaseProvider.ts:556

Returns the result of adding a transaction to the blockchain without actually adding that transaction to the blockchain. Does not require any ether as gas.

Identical to ethers.provider.call in ethers.js
Identical to web3.eth.call in web3.js

Parameters

transaction

TransactionRequest

the transaction object to, in theory, execute. Doesn’t actually get added to the blockchain.

blockTag

BlockTag = 'latest'

the block to execute this transaction on

Returns

Promise<string>

the result of executing the transaction on the specified block

Example

await provider.call({ to: "0x6b175474e89094c44da98b954eedeac495271d0f", data: "0x70a082310000000000000000000000006E0d01A76C3Cf4288372a29124A26D4353EE51BE" });
// '0x0000000000000000000000000000000000000000000000000858898f93629000'

Inherited from

BaseProvider.call

estimateGas()

estimateGas(transaction): Promise<bigint>

Defined in: providers/BaseProvider.ts:438

Returns an estimate of the amount of gas that would be required to submit transaction to the network. An estimate may not be accurate since there could be another transaction on the network that was not accounted for.

Identical to ethers.provider.estimateGas in ethers.js
Identical to web3.eth.estimateGas in web3.js

Parameters

transaction

TransactionRequest

the transaction to check the estimated gas cost for

Returns

Promise<bigint>

the estimated amount of gas charged for submitting the specified transaction to the blockchain

Example

await provider.estimateGas({
  // Wrapped ETH address
  to: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
  data: "0xd0e30db0",
  value: etherToWei('1.0').toHexString(),
});
// 27938n

Inherited from

BaseProvider.estimateGas

getBalance()

getBalance(address, blockTag): Promise<bigint>

Defined in: providers/BaseProvider.ts:383

Returns the balance of the account in wei.

Identical to ethers.provider.getBalance in ethers.js
Identical to web3.eth.getBalance in web3.js, returns a number (bigint) instead of a string

Parameters

address

string

the address to check the balance of

blockTag

BlockTag = 'latest'

the block to check the specified address’ balance on

Returns

Promise<bigint>

the balance of the network’s native token for the specified address on the specified block

Example

 await provider.getBalance('0x7cB57B5A97eAbe94205C07890BE4c1aD31E486A8');
// 28798127851528138

Inherited from

BaseProvider.getBalance

getBlock()

getBlock(timeFrame, returnTransactionObjects): Promise<BlockResponse>

Defined in: providers/BaseProvider.ts:328

Gets information about a certain block, optionally with full transaction objects.

Similar to ethers.provider.getBlock in ethers.js, includes some additional information. Can also return block with full transaction objects, similar to [ethers.providers.getBlockWithTransactions]
Identical to web3.eth.getBlock in web3.js

Parameters

timeFrame

BlockTag = 'latest'

The number, hash, or text-based description (‘latest’, ‘earliest’, or ‘pending’) of the block to collect information on.

returnTransactionObjects

boolean = false

Whether to also return data about the transactions on the block.

Returns

Promise<BlockResponse>

A BlockResponse object with information about the specified block

Example

await provider.getBlock(14879862);
// {
//   baseFeePerGas: 39095728776n,
//   difficulty: 14321294455359973n,
//   extraData: "0x486976656f6e2073672d6865617679",
//   gasLimit: 29970620n,
//   gasUsed: 20951384n,
//   hash: "0x563b458ec3c4f87393b53f70bdddc0058497109b784d8cacd9247ddf267049ab",
//   logsBloom:
//     "0x9f38794fe80b521794df6efad8b0d2e9582f9ec3959a3f9384bda0fa371cfa5fac5af9d515c6bdf1ec325f5b5f7ebdd6a3a9fae17b38a86d4dc4b0971afc68d8086640550f4c156e6f923f4a1bb94fb0bed6cdcc474c5c64bfeff7a4a906f72b9a7b94004ee58efc53d63ac66961acd3a431b2d896cc9fd75f6072960bced45f770587caf130f57504decfcb63c6ca8fbc5bdbd749edd5a99a7375d2b81872289adb775fb3c928259f4be39c6d3f4d5b6217822979bb88c1f1fb62429b1b6d41cf4e3f77f9e1db3f5723108f1e5b1255dd734ad8cdb11e7ea22487c788e67c83777b6f395e504ca59c64f52245ee6de3804cf809e5caa4f0ea6a9aa9eb6ed801",
//   miner: "0x1aD91ee08f21bE3dE0BA2ba6918E714dA6B45836",
//   mixHash: "0x73cc9419bfb89c9d41c3a8c34ce56b5ebe468bdcf870258d2e77262275d580ec",
//   nonce: "0x976f3f5d596ffb08",
//   number: 14879862,
//   parentHash: "0x95986ae14a71face8d9a6a379edd875b2e8bc73e4de0d9d460e7752bddb0f579",
//   receiptsRoot: "0x8e6ba2fd9bee602b653dae6e3132f16538c2c5df24f1df8c000392053f73defa",
//   sha3Uncles: "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
//   size: 134483n,
//   stateRoot: "0xbf2bb67bd1c741f3d00904b8451d7c2cf4e3a2726f5a5884792ede2074747b85",
//   timestamp: 1654016186n,
//   totalDifficulty: 50478104614257705213748n,
//   transactions: [
//     "0xb3326a9149809603a2c28545e50e4f7d16e194bf5ee9764e0544603854c4a8d2",
//     "0x8b42095f8d335404a4896b2817b8e5e3d86a5a87cb434a8eec295d5280a7f48e",
//     "0x882f78fcb73f0f7ad0700bb0424a8b4beb366aaa93b88a3562c49a8d0ce4dcff",
//     ...
//   ],
//   transactionsRoot: "0x5934902f3dcc263ec34f24318179bf6301f53f4834685792066026f3a4849d72",
//   uncles: [],
// }

Inherited from

BaseProvider.getBlock

getBlockNumber()

getBlockNumber(): Promise<number>

Defined in: providers/BaseProvider.ts:120

Gets the number of the most recently mined block on the network the provider is connected to.

Identical to ethers.provider.getBlockNumber in ethers.js
Identical to web3.eth.getBlockNumber in web3.js

Returns

Promise<number>

the number of the most recently mined block

Example

await provider.getBlockNumber();
// 1053312

Inherited from

BaseProvider.getBlockNumber

getCode()

getCode(address, blockTag): Promise<string>

Defined in: providers/BaseProvider.ts:408

Gets the code of a contract on a specified block.

Identical to ethers.provider.getCode in ethers.js
Identical to web3.eth.getCode in web3.js

Parameters

address

string

the contract address to get the contract code from

blockTag

BlockTag = 'latest'

the block height to search for the contract code from. Contract code can change, so this allows for checking a specific block

Returns

Promise<string>

the contract creation code for the specified address at the specified block height

Example

await jsonRpcProvider().getCode('0xaC6095720221C79C6E7C638d260A2eFBC5D8d880', 'latest');
// '0x608060405234801561001057600080fd5b506004361061...'

Inherited from

BaseProvider.getCode

getFeeData()

getFeeData(): Promise<FeeData>

Defined in: providers/BaseProvider.ts:464

Returns the current recommended FeeData to use in a transaction. For an EIP-1559 transaction, the maxFeePerGas and maxPriorityFeePerGas should be used. For legacy transactions and networks which do not support EIP-1559, the gasPrice should be used.Returns an estimate of the amount of gas that would be required to submit transaction to the network.

Identical to ethers.provider.getFeeData in ethers.js

Returns

Promise<FeeData>

an object with gas estimates for the network currently

Example

await provider.getFeeData();
// {
//   gasPrice: 14184772639n,
//   lastBaseFeePerGas: 14038523098n,
//   maxFeePerGas: 29577046196n,
//   maxPriorityFeePerGas: 1500000000n
// }

Inherited from

BaseProvider.getFeeData

getGasPrice()

getGasPrice(): Promise<bigint>

Defined in: providers/BaseProvider.ts:362

Gives an estimate of the current gas price in wei.

Similar to ethers.provider.getGasPrice in ethers.js, does not have a parameter specifying what unit you’d like to return. See also weiToEther and etherToGwei
Identical to web3.eth.getGasPrice in web3.js, returns a number (bigint) instead of a string

Returns

Promise<bigint>

an estimate of the current gas price in wei

Example

await provider.getGasPrice();
// 52493941856

Inherited from

BaseProvider.getGasPrice

getLogs()

getLogs(filter): Promise<Log[]>

Defined in: providers/BaseProvider.ts:525

Returns transaction receipt event logs that match a specified filter. May return [] if parameters are too broad, even if logs exist.

Identical to ethers.provider.getLogs in ethers.js
Identical to web3.eth.getPastLogs in web3.js

Parameters

filter

parameters to filter the logs by

Filter | FilterByBlockHash

Returns

Promise<Log[]>

an array of logs matching the specified filter

Example

provider.getLogs({
  address: "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
  topics: [
    "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
    "0x00000000000000000000000021b8065d10f73ee2e260e5b47d3344d3ced7596e",
  ],
  fromBlock: 14825027,
  toBlock: 14825039,
});

[
  {
    address: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2',
    blockHash: '0x8e0dfac2f704851960f866c8708b3bef2f66c0fee0329cf25ff0261b264ca6bc',
    blockNumber: 14825029,
    data: '0x000000000000000000000000000000000000000000000000005f862ee352a38a',
    logIndex: 384,
    removed: false,
    topics: [
      '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef',
      '0x00000000000000000000000021b8065d10f73ee2e260e5b47d3344d3ced7596e',
      '0x00000000000000000000000068b3465833fb72a70ecdf485e0e4c7bd8665fc45'
    ],
    transactionHash: '0xbd49031be16f8fd1775f4e0fe79b408ffd8ae9c65b2827ee47e3238e3f51f4c0',
    transactionIndex: 226
  }
]

Inherited from

BaseProvider.getLogs

getNetwork()

getNetwork(): Promise<Network>

Defined in: providers/BaseProvider.ts:94

Gets information (name, chainId, and ensAddress when applicable) about the network the provider is connected to.

Identical to ethers.provider.getNetwork in ethers.js
Similar to web3.eth.getChainId in web3.js, returns more than just the chainId

Returns

Promise<Network>

information about the network this provider is currently connected to

Examples

jsonRpcProvider('https://free-eth-node.com/api/eth').getNetwork();
// { chainId: 1, name: 'eth', ensAddress: '0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e' }

jsonRpcProvider('https://free-eth-node.com/api/MATIC').getNetwork();
// { chainId: 137, name: 'MATIC', ensAddress: null }

Inherited from

BaseProvider.getNetwork

getTransaction()

getTransaction(transactionHash): Promise<TransactionResponse>

Defined in: providers/BaseProvider.ts:161

Gets information about a specified transaction, even if it hasn’t been mined yet.

Similar to ethers.provider.getTransaction in ethers.js, does not have wait method that waits until the transaction has been mined
Similar to web3.eth.getTransaction in web3.js, some information returned using different types

Parameters

transactionHash

string

the hash of the transaction to get information about

Returns

Promise<TransactionResponse>

information about the specified transaction

Example

await provider.getTransaction('0x9014ae6ef92464338355a79e5150e542ff9a83e2323318b21f40d6a3e65b4789');
// {
//   accessList: [],
//   blockHash: "0x876810a013dbcd140f6fd6048c1dc33abbb901f1f96b394c2fa63aef3cb40b5d",
//   blockNumber: 14578286,
//   chainId: 1,
//   from: "0xdfD9dE5f6FA60BD70636c0900752E93a6144AEd4",
//   gas: 112163n,
//   gasPrice: 48592426858n,
//   hash: "0x9014ae6ef92464338355a79e5150e542ff9a83e2323318b21f40d6a3e65b4789",
//   input: "0x83259f17000000000000000000000000000000000000000000...",
//   maxFeePerGas: 67681261618n,
//   maxPriorityFeePerGas: 1500000000n,
//   nonce: 129n,
//   r: "0x59a7c15b12c18cd68d6c440963d959bff3e73831ffc938e75ecad07f7ee43fbc",
//   s: "0x1ebaf05f0d9273b16c2a7748b150a79d22533a8cd74552611cbe620fee3dcf1c",
//   to: "0x39B72d136ba3e4ceF35F48CD09587ffaB754DD8B",
//   transactionIndex: 29,
//   type: 2,
//   v: 0,
//   value: 0n,
//   confirmations: 298140,
// }

Inherited from

BaseProvider.getTransaction

getTransactionCount()

getTransactionCount(address, blockTag): Promise<number>

Defined in: providers/BaseProvider.ts:275

Returns the number of sent transactions by an address, from genesis (or as far back as a provider looks) up to specified block.

Identical to ethers.provider.getTransactionCount in ethers.js
Identical to web3.eth.getTransactionCount in web3.js

Parameters

address

string

the address to count number of sent transactions

blockTag

BlockTag = 'latest'

the block to count transactions up to, inclusive

Returns

Promise<number>

the number of transactions sent by the specified address

Examples

await provider.getTransactionCount('0x71660c4005ba85c37ccec55d0c4493e66fe775d3');
// 1060000

await provider.getTransactionCount('0x71660c4005ba85c37ccec55d0c4493e66fe775d3', 'latest');
// 1060000

await provider.getTransactionCount('0x71660c4005ba85c37ccec55d0c4493e66fe775d3', 14649390);
// 1053312

Inherited from

BaseProvider.getTransactionCount

getTransactionReceipt()

getTransactionReceipt(transactionHash): Promise<TransactionReceipt>

Defined in: providers/BaseProvider.ts:236

Gives information about a transaction that has already been mined. Includes additional information beyond what’s provided by getTransaction.

Identical to ethers.provider.getTransactionReceipt in ethers.js
Similar to web3.eth.getTransactionReceipt in web3.js, some information returned using different types

Parameters

transactionHash

string

the hash of the transaction to get information about

Returns

Promise<TransactionReceipt>

information about the specified transaction that has already been mined

Example

await provider.getTransactionReceipt('0x9014ae6ef92464338355a79e5150e542ff9a83e2323318b21f40d6a3e65b4789');
// {
//   blockHash: "0x876810a013dbcd140f6fd6048c1dc33abbb901f1f96b394c2fa63aef3cb40b5d",
//   blockNumber: 14578286,
//   contractAddress: null,
//   cumulativeGasUsed: 3067973n,
//   effectiveGasPrice: 48592426858n,
//   from: "0xdfD9dE5f6FA60BD70636c0900752E93a6144AEd4",
//   gasUsed: 112163n,
//   logs: [
//     {
//       address: "0x0eDF9bc41Bbc1354c70e2107F80C42caE7FBBcA8",
//       blockHash: "0x876810a013dbcd140f6fd6048c1dc33abbb901f1f96b394c2fa63aef3cb40b5d",
//       blockNumber: 14578286,
//       data: "0x0000000000000000000000000000000000000000000003a12ec797b5484968c1",
//       logIndex: 42,
//       topics: [
//         "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
//         "0x00000000000000000000000039b72d136ba3e4cef35f48cd09587ffab754dd8b",
//         "0x000000000000000000000000dfd9de5f6fa60bd70636c0900752e93a6144aed4",
//       ],
//       transactionHash: "0x9014ae6ef92464338355a79e5150e542ff9a83e2323318b21f40d6a3e65b4789",
//       transactionIndex: 29,
//     },
//     {
//       address: "0x39B72d136ba3e4ceF35F48CD09587ffaB754DD8B",
//       blockHash: "0x876810a013dbcd140f6fd6048c1dc33abbb901f1f96b394c2fa63aef3cb40b5d",
//       blockNumber: 14578286,
//       data: "0x0000000000000000000000000000000000000000000003a12ec797b5484968c1",
//       logIndex: 43,
//       topics: [
//         "0x34fcbac0073d7c3d388e51312faf357774904998eeb8fca628b9e6f65ee1cbf7",
//         "0x000000000000000000000000dfd9de5f6fa60bd70636c0900752e93a6144aed4",
//         "0x0000000000000000000000000000000000000000000000000000000000000003",
//       ],
//       transactionHash: "0x9014ae6ef92464338355a79e5150e542ff9a83e2323318b21f40d6a3e65b4789",
//       transactionIndex: 29,
//     },
//   ],
//   logsBloom: "0x00000000000000000000000000000...",
//   status: 1,
//   to: "0x39B72d136ba3e4ceF35F48CD09587ffaB754DD8B",
//   transactionHash: "0x9014ae6ef92464338355a79e5150e542ff9a83e2323318b21f40d6a3e65b4789",
//   transactionIndex: 29,
//   type: 2,
//   byzantium: true,
//   confirmations: 298171,
// }

Inherited from

BaseProvider.getTransactionReceipt

lookupAddress()

lookupAddress(address): Promise<string | null>

Defined in: providers/BaseProvider.ts:692

Performs reverse ENS resolution to get the ENS name associated with an address.

Performs the full ENS reverse resolution process:

Formats the address as a reverse lookup: {address}.addr.reverse
Computes the namehash of the reverse name
Queries the ENS Registry for the resolver contract
Queries the resolver for the name
Verifies the name resolves back to the original address (per ENSIP-3)

Identical to viem.getEnsName in viem

Parameters

address

string

the Ethereum address to look up (e.g. ‘0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045’)

Returns

Promise<string | null>

the ENS name the address resolves to, or null if not found or verification fails

Examples

await provider.lookupAddress('0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045');
// 'vitalik.eth'

await provider.lookupAddress('0x0000000000000000000000000000000000000000');
// null

Inherited from

BaseProvider.lookupAddress

resolveName()

resolveName(name): Promise<string | null>

Defined in: providers/BaseProvider.ts:612

Resolves an ENS name to an Ethereum address.

Performs the full ENS resolution process:

Computes the namehash of the ENS name
Queries the ENS Registry for the resolver contract
Queries the resolver for the address

Identical to ethers.provider.resolveName in ethers.js

Parameters

name

string

the ENS name to resolve (e.g. ‘vitalik.eth’)

Returns

Promise<string | null>

the Ethereum address the name resolves to, or null if not found

Examples

await provider.resolveName('vitalik.eth');
// '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'

await provider.resolveName('thisshouldnotexist12345.eth');
// null

Inherited from

BaseProvider.resolveName