567 lines
20 KiB
Plaintext
567 lines
20 KiB
Plaintext
_section: Provider @<Provider>
|
|
|
|
A **Provider** in ethers is a read-only abstraction to
|
|
access the blockchain data.
|
|
|
|
_note: Coming from Web3.js?
|
|
If you are coming from Web3.js, this is one of the biggest
|
|
differences you will encounter using ethers.
|
|
|
|
The ethers library creates a strong division between the
|
|
operation a **Provider** can perform and those of a [[Signer]],
|
|
which Web3.js lumps together.
|
|
|
|
This separation of concerns and a stricted subset of Provider
|
|
operations allows for a larger variety of backends, a more
|
|
consistent API and ensures other libraries to operate without
|
|
being able to rely on any underlying assumption.
|
|
|
|
_subsection: Accounts Methods @<Provider--account-methods>
|
|
|
|
_property: provider.getBalance(address [ , blockTag = latest ]) => Promise<[[BigNumber]]> @<Provider-getBalance> @SRC<providers/base-provider>
|
|
Returns the balance of //address// as of the //blockTag// block height.
|
|
|
|
_code: @lang<javascript>
|
|
|
|
//_result:
|
|
await provider.getBalance("ricmoo.eth");
|
|
//_log:
|
|
|
|
_property: provider.getCode(address [ , blockTag = latest ]) => Promise<string<[[DataHexString]]>> @<Provider-getCode> @SRC<providers/base-provider>
|
|
Returns the contract code of //address// as of the //blockTag// block height. If there is
|
|
no contract currently deployed, the result is ``0x``.
|
|
|
|
_code: @lang<javascript>
|
|
|
|
//_result:
|
|
await provider.getCode("registrar.firefly.eth");
|
|
//_log:
|
|
|
|
_property: provider.getStorageAt(addr, pos [ , blockTag = latest ]) => Promise<string<[[DataHexString]]>> @<Provider-getStorageAt> @SRC<providers/base-provider>
|
|
Returns the ``Bytes32`` value of the position //pos// at address //addr//, as of the //blockTag//.
|
|
|
|
_code: @lang<javascript>
|
|
|
|
//_result:
|
|
await provider.getStorageAt("registrar.firefly.eth", 0)
|
|
//_log:
|
|
|
|
_property: provider.getTransactionCount(address [ , blockTag = latest ]) => Promise<number> @<Provider-getTransactionCount> @SRC<providers/base-provider>
|
|
Returns the number of transactions //address// has ever **sent**, as of //blockTag//.
|
|
This value is required to be the nonce for the next transaction from //address//
|
|
sent to the network.
|
|
|
|
_code: @lang<javascript>
|
|
|
|
//_result:
|
|
await provider.getTransactionCount("ricmoo.eth");
|
|
//_log:
|
|
|
|
|
|
_subsection: Blocks Methods @<Provider--block-methods>
|
|
|
|
_property: provider.getBlock(block) => Promise<[[providers-Block]]> @<Provider-getBlock> @SRC<providers/base-provider>
|
|
Get the //block// from the network, where the ``result.transactions`` is a list
|
|
of transaction hashes.
|
|
|
|
_code: @lang<javascript>
|
|
|
|
//_result:
|
|
await provider.getBlock(100004)
|
|
//_log:
|
|
|
|
_property: provider.getBlockWithTransactions(block) => Promise<[[providers-BlockWithTransactions]]> @<Provider-getBlockWithTransactions> @SRC<providers/base-provider>
|
|
Get the //block// from the network, where the ``result.transactions`` is
|
|
an Array of [[providers-TransactionResponse]] objects.
|
|
|
|
_code: @lang<javascript>
|
|
|
|
//_result:
|
|
await provider.getBlockWithTransactions(100004)
|
|
//_log:
|
|
|
|
_subsection: Ethereum Naming Service (ENS) Methods @<Provider--ens-methods>
|
|
|
|
The [Ethereum Naming Service](link-ens) (ENS) allows a short and
|
|
easy-to-remember ENS Name to be attached to any set of keys
|
|
and values.
|
|
|
|
One of the most common uses for this is to use a simple name to
|
|
refer to an [Ethereum Address](address).
|
|
|
|
In the ethers API, nearly anywhere that accepts an address, an
|
|
ENS name may be used instead, which can simplify code and make
|
|
reading and debugging much simpler.
|
|
|
|
The provider offers some basic operations to help resolve and
|
|
work with ENS names.
|
|
|
|
_property: provider.getAvatar(name) => Promise<string>
|
|
Returns the URL for the avatar associated to the ENS name, or null
|
|
if no avatar was configured.
|
|
|
|
_property: provider.getResolver(name) => Promise<[[EnsResolver]]>
|
|
Returns an EnsResolver instance which can be used to further inquire
|
|
about specific entries for an ENS name.
|
|
|
|
_code: @lang<javascript>
|
|
|
|
//_hide: provider = ethers.getDefaultProvider();
|
|
|
|
// See below (Resolver) for examples of using this object
|
|
const resolver = await provider.getResolver("ricmoo.eth");
|
|
|
|
//_hide: _page.resolver = resolver;
|
|
|
|
_property: provider.lookupAddress(address) => Promise<string> @<Provider-lookupAddress> @SRC<providers/base-provider>
|
|
Performs a reverse lookup of the //address// in ENS using the
|
|
//Reverse Registrar//. If the name does not exist, or the
|
|
forward lookup does not match, ``null`` is returned.
|
|
|
|
An ENS name requries additional configuration to setup a reverse
|
|
record, they are not automatically set up.
|
|
|
|
_code: @lang<javascript>
|
|
|
|
//_result:
|
|
await provider.lookupAddress("0x5555763613a12D8F3e73be831DFf8598089d3dCa");
|
|
//_log:
|
|
|
|
_property: provider.resolveName(name) => Promise<string<[Address](address)>> @<Provider-ResolveName> @SRC<providers/base-provider>
|
|
Looks up the address of //name//. If the name is not owned, or
|
|
does not have a //Resolver// configured, or the //Resolver// does
|
|
not have an address configured, ``null`` is returned.
|
|
|
|
_code: @lang<javascript>
|
|
|
|
//_result:
|
|
await provider.resolveName("ricmoo.eth");
|
|
//_log:
|
|
|
|
|
|
_subsection: EnsResolver @<EnsResolver>
|
|
|
|
_property: resolver.name => string
|
|
The name of this resolver.
|
|
|
|
_property: resolver.address => string<[[address]]>
|
|
The address of the Resolver.
|
|
|
|
_property: resolver.getAddress([ cointType = 60 ]) => Promise<string>
|
|
Returns a Promise which resolves to the [[link-eip-2304]] multicoin address
|
|
stored for the //coinType//. By default an Ethereum [[address]]
|
|
(``coinType = 60``) will be returned.
|
|
|
|
_code: @lang<javascript>
|
|
|
|
//_hide: const resolver = _page.resolver;
|
|
|
|
// By default, looks up the Ethereum address
|
|
// (this will match provider.resolveName)
|
|
//_result:
|
|
await resolver.getAddress();
|
|
//_log:
|
|
|
|
// Specify the coinType for other coin addresses (0 = Bitcoin)
|
|
//_result:
|
|
await resolver.getAddress(0);
|
|
//_log:
|
|
|
|
_property: resolver.getAvatar() => Promise<AvatarInfo>
|
|
Returns an object the provides the URL of the avatar and the
|
|
linkage representing each stage in the avatar resolution.
|
|
|
|
If there is no avatar found (or the owner of any NFT does not
|
|
match the name owner), null is returned.
|
|
|
|
The AvatarInfo has the properties:
|
|
|
|
- ``info.linkage`` - An array of info on each step resolving the avatar
|
|
- ``info.url`` - The URL of the avatar
|
|
|
|
_property: resolver.getContentHash() => Promise<string>
|
|
Returns a Promise which resolves to any stored [[link-eip-1577]] content hash.
|
|
|
|
_code: @lang<javascript>
|
|
|
|
//_hide: const resolver = _page.resolver;
|
|
|
|
//_result:
|
|
await resolver.getContentHash();
|
|
//_log:
|
|
|
|
_property: resolver.getText(key) => Promise<string>
|
|
Returns a Promise which resolves to any stored [[link-eip-634]] text entry for //key//.
|
|
|
|
_code: @lang<javascript>
|
|
|
|
//_hide: const resolver = _page.resolver;
|
|
|
|
//_result:
|
|
await resolver.getText("email");
|
|
//_log:
|
|
|
|
//_result:
|
|
await resolver.getText("url");
|
|
//_log:
|
|
|
|
//_result:
|
|
await resolver.getText("com.twitter");
|
|
//_log:
|
|
|
|
_subsection: Logs Methods @<Provider--log-methods>
|
|
|
|
_property: provider.getLogs(filter) => Promise<Array<[[providers-Log]]>> @<Provider-getLogs> @SRC<providers/base-provider>
|
|
Returns the Array of [[providers-Log]] matching the //filter//.
|
|
|
|
Keep in mind that many backends will discard old events, and that requests
|
|
which are too broad may get dropped as they require too many resources to
|
|
execute the query.
|
|
|
|
|
|
_subsection: Network Status Methods @<Provider--network-methods>
|
|
|
|
_property: provider.getNetwork() => Promise<[[providers-Network]]> @<Provider-getNetwork> @SRC<providers/base-provider:method.BaseProvider.getNetwork>
|
|
Returns the [[providers-Network]] this Provider is connected to.
|
|
|
|
_code: @lang<javascript>
|
|
|
|
//_result:
|
|
await provider.getNetwork()
|
|
//_hide: _ = utils.shallowCopy(_);
|
|
//_hide: delete _._defaultProvider;
|
|
//_log:
|
|
|
|
_property: provider.getBlockNumber() => Promise<number> @<Provider-getBlockNumber> @SRC<providers/base-provider>
|
|
Returns the block number (or height) of the most recently mined block.
|
|
|
|
_code: @lang<javascript>
|
|
|
|
//_result:
|
|
await provider.getBlockNumber()
|
|
//_log:
|
|
|
|
_property: provider.getGasPrice() => Promise<[[BigNumber]]> @<Provider-getGasPrice> @SRC<providers/base-provider>
|
|
Returns a //best guess// of the [[gas-price]] to use in a transaction.
|
|
|
|
_code: @lang<javascript>
|
|
|
|
// The gas price (in wei)...
|
|
gasPrice = await provider.getGasPrice()
|
|
//_log: gasPrice
|
|
|
|
// ...often this gas price is easier to understand or
|
|
// display to the user in gwei
|
|
//_result:
|
|
utils.formatUnits(gasPrice, "gwei")
|
|
//_log:
|
|
|
|
_property: provider.getFeeData() => Promise<[[providers-FeeData]]> @<Provider-getFeeData> @SRC<abstract-provider>
|
|
Returns the current recommended [[providers-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.
|
|
|
|
_code: @lang<javascript>
|
|
|
|
// The gas price (in wei)...
|
|
feeData = await provider.getFeeData()
|
|
//_log: feeData
|
|
|
|
// ...often these values are easier to understand or
|
|
// display to the user in gwei
|
|
//_result:
|
|
utils.formatUnits(feeData.maxFeePerGas, "gwei")
|
|
//_log:
|
|
|
|
_property: provider.ready => Promise<[[providers-Network]]> @<Provider-ready> @src<providers/base-provider>
|
|
Returns a Promise which will stall until the network has heen established,
|
|
ignoring errors due to the target node not being active yet.
|
|
|
|
This can be used for testing or attaching scripts to wait until the node is
|
|
up and running smoothly.
|
|
|
|
|
|
_subsection: Transactions Methods @<Provider--transaction-methods>
|
|
|
|
_property: provider.call(transaction [ , blockTag = latest ]) => Promise<string<[[DataHexString]]>> @<Provider-call> @SRC<providers/base-provider>
|
|
Returns the result of executing the //transaction//, using //call//. A call
|
|
does not require any ether, but cannot change any state. This is useful
|
|
for calling getters on Contracts.
|
|
|
|
_code: @lang<javascript>
|
|
|
|
//_result:
|
|
await provider.call({
|
|
// ENS public resovler address
|
|
to: "0x4976fb03C32e5B8cfe2b6cCB31c09Ba78EBaBa41",
|
|
|
|
// `function addr(namehash("ricmoo.eth")) view returns (address)`
|
|
data: "0x3b3b57debf074faa138b72c65adbdcfb329847e4f2c04bde7f7dd7fcad5a52d2f395a558"
|
|
});
|
|
//_log:
|
|
|
|
_property: provider.estimateGas(transaction) => Promise<[[BigNumber]]> @<Provider-estimateGas> @SRC<providers/base-provider>
|
|
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, but after being mined affected
|
|
relevant state.
|
|
|
|
_code: @lang<javascript>
|
|
|
|
//_hide: const parseEther = ethers.utils.parseEther;
|
|
|
|
//_result:
|
|
await provider.estimateGas({
|
|
// Wrapped ETH address
|
|
to: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
|
|
|
|
// `function deposit() payable`
|
|
data: "0xd0e30db0",
|
|
|
|
// 1 ether
|
|
value: parseEther("1.0")
|
|
});
|
|
//_log:
|
|
|
|
_property: provider.getTransaction(hash) => Promise<[[providers-TransactionResponse]]> @<Provider-getTransaction> @src<providers/base-provider>
|
|
Returns the transaction with //hash// or null if the transaction is unknown.
|
|
|
|
If a transaction has not been mined, this method will search the transaction
|
|
pool. Various backends may have more restrictive transaction pool access (e.g.
|
|
if the gas price is too low or the transaction was only recently sent and not
|
|
yet indexed) in which case this method may also return null.
|
|
|
|
_code: @lang<javascript>
|
|
|
|
//_result:
|
|
await provider.getTransaction("0x5b73e239c55d790e3c9c3bbb84092652db01bb8dbf49ccc9e4a318470419d9a0");
|
|
//_log:
|
|
|
|
_property: provider.getTransactionReceipt(hash) => Promise<[[providers-TransactionReceipt]]> @<Provider-getTransactionReceipt> @src<providers/base-provider>
|
|
Returns the transaction receipt for //hash// or null if the transaction
|
|
has not been mined.
|
|
|
|
To stall until the transaction has been mined, consider the ``waitForTransaction``
|
|
method below.
|
|
|
|
_code: @lang<javascript>
|
|
|
|
//_result:
|
|
await provider.getTransactionReceipt("0x5b73e239c55d790e3c9c3bbb84092652db01bb8dbf49ccc9e4a318470419d9a0");
|
|
//_log:
|
|
|
|
_property: provider.sendTransaction(transaction) => Promise<[[providers-TransactionResponse]]> @<Provider-sendTransaction> @SRC<providers/base-provider>
|
|
Submits //transaction// to the network to be mined. The //transaction// **must** be signed,
|
|
and be valid (i.e. the nonce is correct and the account has sufficient balance to pay
|
|
for the transaction).
|
|
|
|
_code: @lang<javascript>
|
|
|
|
//_hide: const provider = localProvider;
|
|
//_hide: const wallet = new ethers.Wallet(ethers.utils.id("HelloWorld"), provider);
|
|
//_hide: const fundTx = await localSigner.sendTransaction({
|
|
//_hide: to: wallet.address,
|
|
//_hide: value: ethers.utils.parseEther("2.0")
|
|
//_hide: });
|
|
//_hide: await fundTx.wait();
|
|
//_hide: const tx = await localSigner.populateTransaction({ to: "ricmoo.eth", value: ethers.utils.parseEther("3.14159") });
|
|
//_hide: const signedTx = await localSigner.signTransaction(tx);
|
|
|
|
//_verbatim: `const signedTx = ${ JSON.stringify(signedTx) };`
|
|
//_result:
|
|
await provider.sendTransaction(signedTx);
|
|
//_log:
|
|
|
|
_property: provider.waitForTransaction(hash [ , confirms = 1 [ , timeout ] ]) => Promise<[TxReceipt](providers-TransactionReceipt)> @<Provider-waitForTransaction> @SRC<providers/base-provider>
|
|
Returns a Promise which will not resolve until //transactionHash// is mined.
|
|
|
|
If //confirms// is 0, this method is non-blocking and if the
|
|
transaction has not been mined returns null. Otherwise,
|
|
this method will block until the transaction has //confirms//
|
|
blocks mined on top of the block in which is was mined.
|
|
|
|
_subsection: Event Emitter Methods @<Provider--event-methods>
|
|
|
|
The EventEmitter API allows applications to use an
|
|
[[link-wiki-observer-pattern]] to register callbacks for when
|
|
various events occur.
|
|
|
|
This closely follows the Event Emitter provided by other JavaScript
|
|
libraries with the exception that event names support some more
|
|
[complex objects](Provider--events), not only strings. The objects
|
|
are normalized internally.
|
|
|
|
_property: provider.on(eventName, listener) => this @<Provider-on> @SRC<providers/base-provider>
|
|
Add a //listener// to be triggered for each //eventName// [event](Provider--events).
|
|
|
|
_property: provider.once(eventName, listener) => this @<Provider-once> @SRC<providers/base-provider>
|
|
Add a //listener// to be triggered for only the next
|
|
//eventName// [event](Provider--events), at which time it will be removed.
|
|
|
|
_property: provider.emit(eventName, ...args) => boolean @<Provider-emit> @SRC<providers/base-provider>
|
|
Notify all listeners of the //eventName// [event](Provider--events),
|
|
passing //args// to each listener. This is generally only used internally.
|
|
|
|
_property: provider.off(eventName [ , listener ]) => this @<Provider-off> @SRC<providers/base-provider>
|
|
Remove a //listener// for the //eventName// [event](Provider--events).
|
|
If no //listener// is provided, all listeners for //eventName// are removed.
|
|
|
|
_property: provider.removeAllListeners([ eventName ]) => this @<Provider-removeAllListeners> @SRC<providers/base-provider>
|
|
Remove all the listeners for the //eventName// [events](Provider--events).
|
|
If no //eventName// is provided, **all** events are removed.
|
|
|
|
_property: provider.listenerCount([ eventName ]) => number @<Provider-listenerCount> @SRC<providers/base-provider>
|
|
Returns the number of listeners for the //eventName// [events](Provider--events).
|
|
If no //eventName// is provided, the total number of listeners is returned.
|
|
|
|
_property: provider.listeners(eventName) => Array<Listener> @<Provider-listeners> @SRC<providers/base-provider>
|
|
Returns the list of Listeners for the //eventName// [events](Provider--events).
|
|
|
|
|
|
_heading: Events @<Provider--events>
|
|
|
|
Any of the following may be used as the //eventName// in the above methods.
|
|
|
|
_definition: **Log Filter**
|
|
|
|
A filter is an object, representing a contract log Filter, which has the optional
|
|
properties ``address`` (the source contract) and ``topics`` (a topic-set to match).
|
|
|
|
If ``address`` is unspecified, the filter matches any contract address.
|
|
|
|
See [EventFilters](providers-EventFilter) for more information on filtering events.
|
|
|
|
_definition: **Topic-Set Filter**
|
|
|
|
The value of a **Topic-Set Filter** is a array of Topic-Sets.
|
|
|
|
This event is identical to a //Log Filter// with the address omitted (i.e. from
|
|
any contract).
|
|
|
|
See [EventFilters](providers-EventFilter) for more information on filtering events.
|
|
|
|
_definition: **Transaction Filter**
|
|
|
|
The value of a **Transaction Filter** is any transaction hash.
|
|
|
|
This event is emitted on every block that is part of a chain that
|
|
includes the given mined transaction. It is much more common that the
|
|
[once](Provider-once) method is used than the [on](Provider-on) method.
|
|
|
|
_null:
|
|
|
|
In addition to transaction and filter events, there are several named
|
|
events.
|
|
|
|
_table: Named Provider Events @style<full>
|
|
|
|
$Block: emitted when a new block is mined
|
|
$Error: emitted on any error
|
|
$Pending: emitted when a new transaction enters the memory pool; only
|
|
certain providers offer this event and may require
|
|
running your own node for reliable results
|
|
$WillPoll: emitted prior to a polling loop is about to begin;
|
|
//(very rarely used by most developers)//
|
|
$DidPoll: emitted after all events from a polling loop are emitted;
|
|
//(very rarely used by most developers)//
|
|
$Poll: emitted during each poll cycle after `blockNumber` is updated
|
|
(if changed) and before any other events (if any) are emitted
|
|
during the poll loop;
|
|
//(very rarely used by most developers)//
|
|
$Debug: each Provider may use this to emit useful debugging information
|
|
and the format is up to the developer;
|
|
//(very rarely used by most developers)//
|
|
|
|
| **Event Name** | **Arguments** <| **Description** <<<|
|
|
| ``"block"`` | //blockNumber// <| $Block <<<|
|
|
| ``"error"`` | //error// <| $Error <<<|
|
|
| ``"pending"`` | //pendingTransaction// <| $Pending <<<|
|
|
| ``"willPoll"`` | //pollId// <| $WillPoll <<<|
|
|
| ``"poll"`` | //pollId//, //blockNumber// <| $Poll <<<|
|
|
| ``"didPoll"`` | //pollId// <| $DidPoll <<<|
|
|
| ``"debug"`` | provider dependent <| $Debug <<<|
|
|
|
|
|
|
_code: Events Example @lang<javascript>
|
|
|
|
//_hide: const txHash = utils.id("dummy-data");
|
|
//_hide: const myAddress = ethers.constants.HashZero;
|
|
//_hide: const myOtherAddress = ethers.constants.HashZero;
|
|
//_hide: const hexZeroPad = ethers.utils.hexZeroPad;
|
|
|
|
provider.on("block", (blockNumber) => {
|
|
// Emitted on every block change
|
|
})
|
|
|
|
|
|
provider.once(txHash, (transaction) => {
|
|
// Emitted when the transaction has been mined
|
|
})
|
|
|
|
|
|
// This filter could also be generated with the Contract or
|
|
// Interface API. If address is not specified, any address
|
|
// matches and if topics is not specified, any log matches
|
|
filter = {
|
|
address: "dai.tokens.ethers.eth",
|
|
topics: [
|
|
utils.id("Transfer(address,address,uint256)")
|
|
]
|
|
}
|
|
provider.on(filter, (log, event) => {
|
|
// Emitted whenever a DAI token transfer occurs
|
|
})
|
|
|
|
|
|
// Notice this is an array of topic-sets and is identical to
|
|
// using a filter with no address (i.e. match any address)
|
|
topicSets = [
|
|
utils.id("Transfer(address,address,uint256)"),
|
|
null,
|
|
[
|
|
hexZeroPad(myAddress, 32),
|
|
hexZeroPad(myOtherAddress, 32)
|
|
]
|
|
]
|
|
provider.on(topicSets, (log, event) => {
|
|
// Emitted any token is sent TO either address
|
|
})
|
|
|
|
|
|
provider.on("pending", (tx) => {
|
|
// Emitted when any new pending transaction is noticed
|
|
});
|
|
|
|
|
|
provider.on("error", (tx) => {
|
|
// Emitted when any error occurs
|
|
});
|
|
|
|
//_hide: provider.removeAllListeners() /* Make sure the docs build without waiting forever */
|
|
|
|
_subsection: Inspection Methods @<Provider--inspection-methods>
|
|
|
|
_property: Provider.isProvider(object) => boolean @<Provider-isProvider> @SRC<abstract-provider>
|
|
Returns true if and only if //object// is a Provider.
|
|
|
|
|
|
_subsection: BaseProvider @<BaseProvider> @INHERIT<[[Provider]]> @SRC<providers:class.BaseProvider>
|
|
|
|
Most Providers available in ethers are sub-classes of BaseProvider, which
|
|
simplifies sub-classes, as it handles much of the event operations, such as
|
|
polling and formatting.
|
|
|
|
_property: provider.polling => boolean
|
|
Indicates if the Provider is currently polling. If there are no events to
|
|
poll for or polling has been explicitly disabled, this will be false.
|
|
|
|
_property: provider.pollingInterval => number
|
|
The frequency at which the provider polls.
|
|
|