220 lines
37 KiB
HTML
220 lines
37 KiB
HTML
<!DOCTYPE html>
|
|
<html class="paged">
|
|
<head>
|
|
<title>Provider</title>
|
|
<link rel="stylesheet" type="text/css" href="/v5/static/style.css">
|
|
</head>
|
|
<body>
|
|
<div class="sidebar">
|
|
<div class="header">
|
|
<div class="logo"><a href="/v5/"><div class="image"></div><div class="name">ethers</div><div class="version">v5.0-beta</div></a></div>
|
|
</div>
|
|
<div class="toc"><div>
|
|
<div class="link title"><a href="/">Documentation</a></div><div class="base show link depth-1"><a href="/v5/getting-started/">Getting Started</a></div><div class="base show link depth-1"><a href="/v5/concepts/">Ethereum Basics</a></div><div class="hide link depth-2"><a href="/v5/concepts/events/">Events</a></div><div class="hide link depth-2"><a href="/v5/concepts/gas/">Gas</a></div><div class="hide link depth-2"><a href="/v5/concepts/security/">Security</a></div><div class="base ancestor show link depth-1"><a href="/v5/api/">Application Programming Interface</a></div><div class="show link depth-2"><a href="/v5/api/contract/">Contract Interaction</a></div><div class="hide link depth-3"><a href="/v5/api/contract/contract/">Contract</a></div><div class="hide link depth-3"><a href="/v5/api/contract/contract-factory/">ContractFactory</a></div><div class="hide link depth-3"><a href="/v5/api/contract/example/">Example: ERC-20 Contract</a></div><div class="show link depth-2"><a href="/v5/api/signer/">Signers</a></div><div class="ancestor show link depth-2"><a href="/v5/api/providers/">Providers</a></div><div class="myself ancestor ancestor show link depth-3"><a href="/v5/api/providers/provider/">Provider</a></div><div class="show link depth-3"><a href="/v5/api/providers/jsonrpc-provider/">JsonRpcProvider</a></div><div class="show link depth-3"><a href="/v5/api/providers/api-providers/">API Providers</a></div><div class="show link depth-3"><a href="/v5/api/providers/other/">Other Providers</a></div><div class="show link depth-3"><a href="/v5/api/providers/types/">Types</a></div><div class="show link depth-2"><a href="/v5/api/utils/">Utilities</a></div><div class="hide link depth-3"><a href="/v5/api/utils/abi/">Application Binary Interface</a></div><div class="hide link depth-4"><a href="/v5/api/utils/abi/interface/">Interface</a></div><div class="hide link depth-4"><a href="/v5/api/utils/abi/fragments/">Fragments</a></div><div class="hide link depth-3"><a href="/v5/api/utils/address/">Addresses</a></div><div class="hide link depth-3"><a href="/v5/api/utils/bignumber/">BigNumber</a></div><div class="hide link depth-3"><a href="/v5/api/utils/bytes/">Byte Manipulation</a></div><div class="hide link depth-3"><a href="/v5/api/utils/constants/">Constants</a></div><div class="hide link depth-3"><a href="/v5/api/utils/display-logic/">Display Logic and Input</a></div><div class="hide link depth-3"><a href="/v5/api/utils/encoding/">Encoding Utilities</a></div><div class="hide link depth-3"><a href="/v5/api/utils/fixednumber/">FixedNumber</a></div><div class="hide link depth-3"><a href="/v5/api/utils/hashing/">Hashing Algorithms</a></div><div class="hide link depth-3"><a href="/v5/api/utils/hdnode/">HD Wallet</a></div><div class="hide link depth-3"><a href="/v5/api/utils/logger/">Logging</a></div><div class="hide link depth-3"><a href="/v5/api/utils/properties/">Property Utilities</a></div><div class="hide link depth-3"><a href="/v5/api/utils/signing-key/">Signing Key</a></div><div class="hide link depth-3"><a href="/v5/api/utils/strings/">Strings</a></div><div class="hide link depth-3"><a href="/v5/api/utils/transactions/">Transactions</a></div><div class="hide link depth-3"><a href="/v5/api/utils/web/">Web Utilities</a></div><div class="hide link depth-3"><a href="/v5/api/utils/wordlists/">Wordlists</a></div><div class="show link depth-2"><a href="/v5/api/other/">Other Libraries</a></div><div class="hide link depth-3"><a href="/v5/api/other/assembly/">Assembly</a></div><div class="hide link depth-4"><a href="/v5/api/other/assembly/dialect/">Ethers ASM Dialect</a></div><div class="hide link depth-4"><a href="/v5/api/other/assembly/api/">Utilities</a></div><div class="hide link depth-4"><a href="/v5/api/other/assembly/ast/">Abstract Syntax Tree</a></div><div class="hide link depth-3"><a href="/v5/api/other/hardware/">Hardware Wallets</a></div><div class="show link depth-2"><a href="/v5/api/experimental/">Experimental</a></div><div class="base show link depth-1"><a href="/v5/cli/">Command Line Interfaces</a></div><div class="hide link depth-2"><a href="/v5/cli/ethers/">Sandbox Utility</a></div><div class="hide link depth-2"><a href="/v5/cli/asm/">Assembler</a></div><div class="hide link depth-2"><a href="/v5/cli/ens/">Ethereum Naming Service</a></div><div class="hide link depth-2"><a href="/v5/cli/typescript/">TypeScript</a></div><div class="hide link depth-2"><a href="/v5/cli/plugin/">Making Your Own</a></div><div class="base show link depth-1"><a href="/v5/cookbook/">Cookbook</a></div><div class="base show link depth-1"><a href="/v5/migration/">Migration Guide</a></div><div class="hide link depth-2"><a href="/v5/migration/web3/">Migration: From Web3.js</a></div><div class="hide link depth-2"><a href="/v5/migration/ethers-v4/">Migration: From Ethers v4</a></div><div class="base show link depth-1"><a href="/v5/testing/">Testing</a></div><div class="base show link depth-1"><a href="/v5/contributing/">Contributing and Hacking</a></div><div class="base show link depth-1"><a href="/v5/documentation/">Flatworm Docs</a></div><div class="base show link depth-1"><a href="/v5/license/">License and Copyright</a></div>
|
|
</div></div>
|
|
</div>
|
|
<div class="content">
|
|
<div class="breadcrumbs"><a href="/v5/">Documentation</a> » <a href="/v5/api/">API</a> » <a href="/v5/api/providers/">Providers</a> » <span class="current">Provider</span></div>
|
|
|
|
<a name="Provider"></a><a name="Provider"></a><h1 class="show-anchors"><div>Provider<div class="anchors"><a class="self" href="/v5/api/providers/provider/#Provider"></a></div></div></h1><p>Explain what a provider is...</p>
|
|
|
|
<a name="Provider--account-methods"></a><a name="Provider--Provider--account-methods"></a><h2 class="show-anchors"><div>Accounts Methods<div class="anchors"><a class="self" href="/v5/api/providers/provider/#Provider--account-methods"></a></div></div></h2>
|
|
<a name="Provider-getBalance"></a><div class="property show-anchors"><div class="signature"><span class="path">provider</span><span class="symbol">.</span><span class="method">getBalance</span><span class="symbol">(</span> <span class="param">address</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">blockTag</span> = <span class="param">latest</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< <a href="/v5/api/utils/bignumber/">BigNumber</a> ></span><div class="anchors"><a class="self" href="/v5/api/providers/provider/#Provider-getBalance"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/ethers-v5-beta/packages/providers/src.ts/base-provider.ts#L689">source</a></div></div><div class="body"><p>Returns the balance of <i>address</i> as of the <i>blockTag</i> block height.</p>
|
|
|
|
</div></div><a name="Provider-getCode"></a><div class="property show-anchors"><div class="signature"><span class="path">provider</span><span class="symbol">.</span><span class="method">getCode</span><span class="symbol">(</span> <span class="param">address</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">blockTag</span> = <span class="param">latest</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< string< <a href="/v5/api/utils/bytes/#DataHexString">DataHexString</a> > ></span><div class="anchors"><a class="self" href="/v5/api/providers/provider/#Provider-getCode"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/ethers-v5-beta/packages/providers/src.ts/base-provider.ts#L707">source</a></div></div><div class="body"><p>Returns the contract code of <i>address</i> as of the <i>blockTag</i> block height. If there is no contract currently deployed, the result is <code class="inline">0x</code>.</p>
|
|
|
|
</div></div><a name="Provider-getStorageAt"></a><div class="property show-anchors"><div class="signature"><span class="path">provider</span><span class="symbol">.</span><span class="method">getStorageAt</span><span class="symbol">(</span> <span class="param">addr</span> <span class="symbol">,</span> <span class="param">pos</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">blockTag</span> = <span class="param">latest</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< string< <a href="/v5/api/utils/bytes/#DataHexString">DataHexString</a> > ></span><div class="anchors"><a class="self" href="/v5/api/providers/provider/#Provider-getStorageAt"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/ethers-v5-beta/packages/providers/src.ts/base-provider.ts#L716">source</a></div></div><div class="body"><p>Returns the <code class="inline">Bytes32</code> value of the position <i>pos</i> at address <i>addr</i>, as of the <i>blockTag</i>.</p>
|
|
|
|
</div></div><a name="Provider-getTransactionCount"></a><div class="property show-anchors"><div class="signature"><span class="path">provider</span><span class="symbol">.</span><span class="method">getTransactionCount</span><span class="symbol">(</span> <span class="param">address</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">blockTag</span> = <span class="param">latest</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< number ></span><div class="anchors"><a class="self" href="/v5/api/providers/provider/#Provider-getTransactionCount"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/ethers-v5-beta/packages/providers/src.ts/base-provider.ts#L698">source</a></div></div><div class="body"><p>Returns the number of transactions <i>address</i> has ever <b>sent</b>, as of <i>blockTag</i>. This value is required to be the nonce for the next transaction from <i>address</i> sent to the network.</p>
|
|
|
|
</div></div><div class="code-title"><div>Account Examples</div></div><div class="code">// Get the balance for an account...
|
|
provider.getBalance("ricmoo.firefly.eth");
|
|
//!
|
|
|
|
// Get the code for a contract...
|
|
provider.getCode("registrar.firefly.eth");
|
|
//!
|
|
|
|
// Get the storage value at position 0...
|
|
provider.getStorageAt("registrar.firefly.eth", 0)
|
|
//!
|
|
|
|
// Get transaction count of an account...
|
|
provider.getTransactionCount("ricmoo.firefly.eth");
|
|
//!</div><a name="Provider--block-methods"></a><a name="Provider--Provider--block-methods"></a><h2 class="show-anchors"><div>Blocks Methods<div class="anchors"><a class="self" href="/v5/api/providers/provider/#Provider--block-methods"></a></div></div></h2>
|
|
<a name="Provider-getBlock"></a><div class="property show-anchors"><div class="signature"><span class="path">provider</span><span class="symbol">.</span><span class="method">getBlock</span><span class="symbol">(</span> <span class="param">block</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< <a href="/v5/api/providers/types/#providers-Block">Block</a> ></span><div class="anchors"><a class="self" href="/v5/api/providers/provider/#Provider-getBlock"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/ethers-v5-beta/packages/providers/src.ts/base-provider.ts#L925">source</a></div></div><div class="body"><p>Get the <i>block</i> from the network, where the <code class="inline">result.transactions</code> is a list of transaction hashes.</p>
|
|
|
|
</div></div><a name="Provider-getBlockWithTransactions"></a><div class="property show-anchors"><div class="signature"><span class="path">provider</span><span class="symbol">.</span><span class="method">getBlockWithTransactions</span><span class="symbol">(</span> <span class="param">block</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< <a href="/v5/api/providers/types/#providers-BlockWithTransactions">BlockWithTransactions</a> ></span><div class="anchors"><a class="self" href="/v5/api/providers/provider/#Provider-getBlockWithTransactions"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/ethers-v5-beta/packages/providers/src.ts/base-provider.ts#L929">source</a></div></div><div class="body"><p>Get the <i>block</i> from the network, where the <code class="inline">result.transactions</code> is an Array of <a href="/v5/api/providers/types/#providers-TransactionResponse">TransactionResponse</a> objects.</p>
|
|
|
|
</div></div><div class="code-title"><div>Block Examples</div></div><div class="code">provider.getBlock(100004)
|
|
//!
|
|
|
|
provider.getBlockWithTransactions(100004)
|
|
//!</div><a name="Provider--ethereum-naming-service-ens-methods"></a><h2 class="show-anchors"><div>Ethereum Naming Service (ENS) Methods<div class="anchors"><a class="self" href="/v5/api/providers/provider/#Provider--ethereum-naming-service-ens-methods"></a></div></div></h2><p>The <a href="https://ens.domains/">Ethereum Naming Service</a> (ENS) allows a short and easy-to-remember ENS Name to be atached to any set of keys and values.</p>
|
|
|
|
<p>One of the most common uses for this is to use a simple name to refer to an <a href="/v5/api/utils/address/#address">Ethereum Address</a>.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>The provider offers some basic operations to help resolve and work with ENS names.</p>
|
|
|
|
<a name="Provider-lookupAddress"></a><div class="property show-anchors"><div class="signature"><span class="path">provider</span><span class="symbol">.</span><span class="method">lookupAddress</span><span class="symbol">(</span> <span class="param">address</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< string ></span><div class="anchors"><a class="self" href="/v5/api/providers/provider/#Provider-lookupAddress"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/ethers-v5-beta/packages/providers/src.ts/base-provider.ts#L1088">source</a></div></div><div class="body"><p>Performs a reverse lookup of the <i>address</i> in ENS using the <i>Reverse Registrar</i>. If the name does not exist, or the forward lookup does not match, <code class="inline">null</code> is returned.</p>
|
|
|
|
</div></div><a name="Provider-ResolveName"></a><div class="property show-anchors"><div class="signature"><span class="path">provider</span><span class="symbol">.</span><span class="method">resolveName</span><span class="symbol">(</span> <span class="param">name</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< string< <a href="/v5/api/utils/address/#address">Address</a> > ></span><div class="anchors"><a class="self" href="/v5/api/providers/provider/#Provider-ResolveName"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/ethers-v5-beta/packages/providers/src.ts/base-provider.ts#L1060">source</a></div></div><div class="body"><p>Looks up the address of <i>name</i>. If the name is not owned, or does not have a <i>Resolver</i> configured, or the <i>Resolver</i> does not have an address configured, <code class="inline">null</code> is returned.</p>
|
|
|
|
</div></div><div class="code-title"><div>ENS Examples</div></div><div class="code">// Reverse lookup of an ENS by address...
|
|
provider.lookupAddress("0x6fC21092DA55B392b045eD78F4732bff3C580e2c");
|
|
//!
|
|
|
|
// Lookup an address of an ENS name...
|
|
provider.resolveName("ricmoo.firefly.eth");
|
|
//!</div><a name="Provider--log-methods"></a><a name="Provider--Provider--log-methods"></a><h2 class="show-anchors"><div>Logs Methods<div class="anchors"><a class="self" href="/v5/api/providers/provider/#Provider--log-methods"></a></div></div></h2>
|
|
<a name="Provider-getLogs"></a><div class="property show-anchors"><div class="signature"><span class="path">provider</span><span class="symbol">.</span><span class="method">getLogs</span><span class="symbol">(</span> <span class="param">filter</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< Array< <a href="/v5/api/providers/types/#providers-Log">Log</a> > ></span><div class="anchors"><a class="self" href="/v5/api/providers/provider/#Provider-getLogs"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/ethers-v5-beta/packages/providers/src.ts/base-provider.ts#L1005">source</a></div></div><div class="body"><p>Returns the Array of <a href="/v5/api/providers/types/#providers-Log">Log</a> matching the <i>filter</i>.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
</div></div><a name="Provider--network-methods"></a><a name="Provider--Provider--network-methods"></a><h2 class="show-anchors"><div>Network Status Methods<div class="anchors"><a class="self" href="/v5/api/providers/provider/#Provider--network-methods"></a></div></div></h2>
|
|
<a name="Provider-getNetwork"></a><div class="property show-anchors"><div class="signature"><span class="path">provider</span><span class="symbol">.</span><span class="method">getNetwork</span><span class="symbol">(</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< <a href="/v5/api/providers/types/#providers-Network">Network</a> ></span><div class="anchors"><a class="self" href="/v5/api/providers/provider/#Provider-getNetwork"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/ethers-v5-beta/packages/providers/src.ts/base-provider.ts#L509">source</a></div></div><div class="body"><p>Returns the <a href="/v5/api/providers/types/#providers-Network">Network</a> this Provider is connected to.</p>
|
|
|
|
</div></div><a name="Provider-getBlockNumber"></a><div class="property show-anchors"><div class="signature"><span class="path">provider</span><span class="symbol">.</span><span class="method">getBlockNumber</span><span class="symbol">(</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< number ></span><div class="anchors"><a class="self" href="/v5/api/providers/provider/#Provider-getBlockNumber"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/ethers-v5-beta/packages/providers/src.ts/base-provider.ts#L680">source</a></div></div><div class="body"><p>Returns the block number (or height) of the most recently mined block.</p>
|
|
|
|
</div></div><a name="Provider-getGasPrice"></a><div class="property show-anchors"><div class="signature"><span class="path">provider</span><span class="symbol">.</span><span class="method">getGasPrice</span><span class="symbol">(</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< <a href="/v5/api/utils/bignumber/">BigNumber</a> ></span><div class="anchors"><a class="self" href="/v5/api/providers/provider/#Provider-getGasPrice"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/ethers-v5-beta/packages/providers/src.ts/base-provider.ts#L684">source</a></div></div><div class="body"><p>Returns a <i>best guess</i> of the <a href="/v5/concepts/gas/#gas-price">Gas Price</a> to use in a transaction.</p>
|
|
|
|
</div></div><div class="code-title"><div>Network Status Examples</div></div><div class="code">// The network information
|
|
provider.getNetwork()
|
|
// <hide>
|
|
//!
|
|
network = utils.shallowCopy(_)
|
|
delete network._defaultProvider
|
|
network
|
|
// </hide>
|
|
//!
|
|
|
|
// The current block number
|
|
provider.getBlockNumber()
|
|
//!
|
|
|
|
// Get the current suggested gas price (in wei)...
|
|
gasPrice = await provider.getGasPrice()
|
|
//! async gasPrice
|
|
|
|
// ...often this gas price is easier to understand or
|
|
// display to the user in gwei (giga-wei, or 1e9 wei)
|
|
utils.formatUnits(gasPrice, "gwei")
|
|
//!</div><a name="Provider--transaction-methods"></a><a name="Provider--Provider--transaction-methods"></a><h2 class="show-anchors"><div>Transactions Methods<div class="anchors"><a class="self" href="/v5/api/providers/provider/#Provider--transaction-methods"></a></div></div></h2>
|
|
<a name="Provider-call"></a><div class="property show-anchors"><div class="signature"><span class="path">provider</span><span class="symbol">.</span><span class="method">call</span><span class="symbol">(</span> <span class="param">transaction</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">blockTag</span> = <span class="param">latest</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< string< <a href="/v5/api/utils/bytes/#DataHexString">DataHexString</a> > ></span><div class="anchors"><a class="self" href="/v5/api/providers/provider/#Provider-call"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/ethers-v5-beta/packages/providers/src.ts/base-provider.ts#L825">source</a></div></div><div class="body"><p>Returns the result of executing the <i>transaction</i>, using <i>call</i>. A call does not require any ether, but cannot change any state. This is useful for calling gettings on Contracts.</p>
|
|
|
|
</div></div><a name="Provider-estimateGas"></a><div class="property show-anchors"><div class="signature"><span class="path">provider</span><span class="symbol">.</span><span class="method">estimateGas</span><span class="symbol">(</span> <span class="param">transaction</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< <a href="/v5/api/utils/bignumber/">BigNumber</a> ></span><div class="anchors"><a class="self" href="/v5/api/providers/provider/#Provider-estimateGas"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/ethers-v5-beta/packages/providers/src.ts/base-provider.ts#L834">source</a></div></div><div class="body"><p>Returns an estimate of the amount of gas that would be required to submit <i>transaction</i> to the network.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
</div></div><a name="Provider-sendTransaction"></a><div class="property show-anchors"><div class="signature"><span class="path">provider</span><span class="symbol">.</span><span class="method">sendTransaction</span><span class="symbol">(</span> <span class="param">transaction</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< <a href="/v5/api/providers/types/#providers-TransactionResponse">TransactionResponse</a> ></span><div class="anchors"><a class="self" href="/v5/api/providers/provider/#Provider-sendTransaction"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/ethers-v5-beta/packages/providers/src.ts/base-provider.ts#L766">source</a></div></div><div class="body"><p>Submits <i>transaction</i> to the network to be mined. The <i>transaction</i> <b>must</b> be signed, and be valid (i.e. the nonce is correct and the account has sufficient balance to pay for the transaction).</p>
|
|
|
|
</div></div><a name="Provider-waitForTransaction"></a><div class="property show-anchors"><div class="signature"><span class="path">provider</span><span class="symbol">.</span><span class="method">waitForTransaction</span><span class="symbol">(</span> <span class="param">hash</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">confirms</span> = <span class="param">1</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">timeout</span> <span class="symbol">]</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< <a href="/v5/api/providers/types/#providers-TransactionReceipt">TxReceipt</a> ></span><div class="anchors"><a class="self" href="/v5/api/providers/provider/#Provider-waitForTransaction"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/ethers-v5-beta/packages/providers/src.ts/base-provider.ts#L641">source</a></div></div><div class="body"><p>Returns a Promise which will not resolve until <i>transactionHash</i> is mined.</p>
|
|
|
|
</div></div><a name="Provider--event-methods"></a><a name="Provider--Provider--event-methods"></a><h2 class="show-anchors"><div>Event Emitter Methods<div class="anchors"><a class="self" href="/v5/api/providers/provider/#Provider--event-methods"></a></div></div></h2><p>Explain events here...</p>
|
|
|
|
<a name="Provider-on"></a><div class="property show-anchors"><div class="signature"><span class="path">provider</span><span class="symbol">.</span><span class="method">on</span><span class="symbol">(</span> <span class="param">eventName</span> <span class="symbol">,</span> <span class="param">listener</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">this</span><div class="anchors"><a class="self" href="/v5/api/providers/provider/#Provider-on"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/ethers-v5-beta/packages/providers/src.ts/base-provider.ts#L1146">source</a></div></div><div class="body"><p>Add a <i>listener</i> to be triggered for each <i>eventName</i>.</p>
|
|
|
|
</div></div><a name="Provider-once"></a><div class="property show-anchors"><div class="signature"><span class="path">provider</span><span class="symbol">.</span><span class="method">once</span><span class="symbol">(</span> <span class="param">eventName</span> <span class="symbol">,</span> <span class="param">listener</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">this</span><div class="anchors"><a class="self" href="/v5/api/providers/provider/#Provider-once"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/ethers-v5-beta/packages/providers/src.ts/base-provider.ts#L1150">source</a></div></div><div class="body"><p>Add a <i>listener</i> to be triggered for only the next <i>eventName</i>, at which time it be removed.</p>
|
|
|
|
</div></div><a name="Provider-emit"></a><div class="property show-anchors"><div class="signature"><span class="path">provider</span><span class="symbol">.</span><span class="method">emit</span><span class="symbol">(</span> <span class="param">eventName</span> <span class="symbol">,</span> ...<span class="param">args</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">boolean</span><div class="anchors"><a class="self" href="/v5/api/providers/provider/#Provider-emit"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/ethers-v5-beta/packages/providers/src.ts/base-provider.ts#L1155">source</a></div></div><div class="body"><p>Notify all listeners of <i>eventName</i>, passing <i>args</i> to each listener. This is generally only used internally.</p>
|
|
|
|
</div></div><a name="Provider-off"></a><div class="property show-anchors"><div class="signature"><span class="path">provider</span><span class="symbol">.</span><span class="method">off</span><span class="symbol">(</span> <span class="param">eventName</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">listener</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">this</span><div class="anchors"><a class="self" href="/v5/api/providers/provider/#Provider-off"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/ethers-v5-beta/packages/providers/src.ts/base-provider.ts#L1203">source</a></div></div><div class="body"><p>Remove a <i>listener</i> for <i>eventName</i>. If no <i>listener</i> is provided, all listeners for <i>eventName</i> are removed.</p>
|
|
|
|
</div></div><a name="Provider-removeAllListeners"></a><div class="property show-anchors"><div class="signature"><span class="path">provider</span><span class="symbol">.</span><span class="method">removeAllListeners</span><span class="symbol">(</span> <span class="symbol">[</span> <span class="param">eventName</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">this</span><div class="anchors"><a class="self" href="/v5/api/providers/provider/#Provider-removeAllListeners"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/ethers-v5-beta/packages/providers/src.ts/base-provider.ts#L1226">source</a></div></div><div class="body"><p>Remove all the listeners for <i>eventName</i>. If no <i>eventName</i> is provided, <b>all</b> events are removed.</p>
|
|
|
|
</div></div><a name="Provider-listenerCount"></a><div class="property show-anchors"><div class="signature"><span class="path">provider</span><span class="symbol">.</span><span class="method">listenerCount</span><span class="symbol">(</span> <span class="symbol">[</span> <span class="param">eventName</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">number</span><div class="anchors"><a class="self" href="/v5/api/providers/provider/#Provider-listenerCount"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/ethers-v5-beta/packages/providers/src.ts/base-provider.ts#L1183">source</a></div></div><div class="body"><p>Returns the number of listeners for <i>eventName</i>. If no <i>eventName</i> is provided, the total number of listeners is returned.</p>
|
|
|
|
</div></div><a name="Provider-listeners"></a><div class="property show-anchors"><div class="signature"><span class="path">provider</span><span class="symbol">.</span><span class="method">listeners</span><span class="symbol">(</span> <span class="param">eventName</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Array< Listener ></span><div class="anchors"><a class="self" href="/v5/api/providers/provider/#Provider-listeners"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/ethers-v5-beta/packages/providers/src.ts/base-provider.ts#L1192">source</a></div></div><div class="body"><p>Returns the list of Listeners for <i>eventName</i>.</p>
|
|
|
|
</div></div><a name="Provider--events"></a><a name="Provider--Provider--event-methods--Provider--events"></a><h3 class="show-anchors"><div>Events<div class="anchors"><a class="self" href="/v5/api/providers/provider/#Provider--events"></a></div></div></h3><p>Any of the following may be used as the <i>eventName</i> in the above methods.</p>
|
|
|
|
<div class="definition"><div class="term"><b>Log Filter</b></div><div class="body"><p>A filter is an object, representing a contract log Filter, which has the optional properties <code class="inline">address</code> (the source contract) and <code class="inline">topics</code> (a topic-set to match).</p>
|
|
|
|
<p>If <code class="inline">address</code> is unspecified, the filter matches any contract address.</p>
|
|
|
|
<p>See events for more information on how to specify topic-sets.</p>
|
|
|
|
</div></div><div class="definition"><div class="term"><b>Topic-Set Filter</b></div><div class="body"><p>The value of a <b>Topic-Set Filter</b> is a array of Topic-Sets.</p>
|
|
|
|
<p>This event is identical to a <i>Log Filter</i> with the address omitted (i.e. from any contract).</p>
|
|
|
|
</div></div><div class="definition"><div class="term"><b>Transaction Filter</b></div><div class="body"><p>The value of a <b>Transaction Filter</b> is any transaction hash.</p>
|
|
|
|
<p>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 <a href="/v5/api/providers/provider/#Provider-once">once</a> method is used than the <a href="/v5/api/providers/provider/#Provider-on">on</a> method.</p>
|
|
|
|
</div></div><p>In addition to transaction and filter events, there are several named events.</p>
|
|
|
|
<table class="table full"><tr><td align="center" width="16%"><b>Event Name</b></td><td align="center" colspan="2" width="28%"><b>Arguments</b></td><td align="center" colspan="4" width="56%"><b>Description</b></td><td class="fix"> </td></tr><tr><td align="center" width="16%"><code class="inline">"block"</code></td><td align="center" colspan="2" width="28%"><i>blockNumber</i></td><td align="left" colspan="4" width="56%">emitted when a new block is mined</td><td class="fix"> </td></tr><tr><td align="center" width="16%"><code class="inline">"error"</code></td><td align="center" colspan="2" width="28%"><i>error</i></td><td align="left" colspan="4" width="56%">emitted on any error</td><td class="fix"> </td></tr><tr><td align="center" width="16%"><code class="inline">"pending"</code></td><td align="center" colspan="2" width="28%"><i>pendingTransaction</i></td><td align="left" colspan="4" width="56%">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</td><td class="fix"> </td></tr><tr><td align="center" width="16%"><code class="inline">"willPoll"</code></td><td align="center" colspan="2" width="28%"><i>pollId</i></td><td align="left" colspan="4" width="56%">emitted prior to a polling loop is about to begin; <i>(very rarely used by most developers)</i></td><td class="fix"> </td></tr><tr><td align="center" width="16%"><code class="inline">"poll"</code></td><td align="center" colspan="2" width="28%"><i>pollId</i>, <i>blockNumber</i></td><td align="left" colspan="4" width="56%">emitted during each poll cycle after `blockNumber` is updated (if changed) and before any other events (if any) are emitted during the poll loop; <i>(very rarely used by most developers)</i></td><td class="fix"> </td></tr><tr><td align="center" width="16%"><code class="inline">"didPoll"</code></td><td align="center" colspan="2" width="28%"><i>pollId</i></td><td align="left" colspan="4" width="56%">emitted after all events from a polling loop are emitted; <i>(very rarely used by most developers)</i></td><td class="fix"> </td></tr><tr><td align="center" width="16%"><code class="inline">"debug"</code></td><td align="center" colspan="2" width="28%">provider dependent</td><td align="left" colspan="4" width="56%">each Provider may use this to emit useful debugging information and the format is up to the developer; <i>(very rarely used by most developers)</i></td><td class="fix"> </td></tr><tr><td class="table-title" colspan="7">Named Provider Events</td><td class="fix"> </td></tr></table><div class="code-title"><div>Events Example</div></div><div class="code">// <hide>
|
|
const txHash = utils.id("dummy-data");
|
|
const myAddress = ethers.constants.HashZero;
|
|
const myOtherAddress = ethers.constants.HashZero;
|
|
// </hide>
|
|
|
|
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,
|
|
[
|
|
myAddress,
|
|
myOtherAddress
|
|
]
|
|
]
|
|
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>
|
|
// Make sure our documentation builds without waiting forever
|
|
provider.removeAllListeners()
|
|
// </hide></div><a name="Provider--inspection-methods"></a><a name="Provider--Provider--inspection-methods"></a><h2 class="show-anchors"><div>Inspection Methods<div class="anchors"><a class="self" href="/v5/api/providers/provider/#Provider--inspection-methods"></a></div></div></h2>
|
|
<a name="Provider-isProvider"></a><div class="property show-anchors"><div class="signature"><span class="path">Provider</span><span class="symbol">.</span><span class="method">isProvider</span><span class="symbol">(</span> <span class="param">object</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">boolean</span><div class="anchors"><a class="self" href="/v5/api/providers/provider/#Provider-isProvider"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/ethers-v5-beta/packages/abstract-provider/src.ts/index.ts#L269">source</a></div></div><div class="body"><p>Returns true if and only if <i>object</i> is a Provider.</p>
|
|
|
|
</div></div>
|
|
|
|
<div class="footer">
|
|
<div class="nav previous"><a href="/v5/api/providers/"><span class="arrow">←</span>Providers</a></div>
|
|
<div class="nav next"><a href="/v5/api/providers/jsonrpc-provider/">JsonRpcProvider<span class="arrow">→</span></a></div>
|
|
</div>
|
|
<div class="copyright">The content of this site is licensed under the <a href="https://choosealicense.com/licenses/cc-by-4.0/">Creative Commons License</a>. Generated on June 8, 2020, 10:6pm.</div>
|
|
</div>
|
|
<script src="/v5/static/script.js" type="text/javascript"></script>
|
|
</body>
|
|
</html>
|