<divclass="link title"><ahref="/v5/">Documentation</a></div><divclass="base show link depth-1"><ahref="/v5/getting-started/">Getting Started</a></div><divclass="base show link depth-1"><ahref="/v5/concepts/">Ethereum Basics</a></div><divclass="hide link depth-2"><ahref="/v5/concepts/events/">Events</a></div><divclass="hide link depth-2"><ahref="/v5/concepts/gas/">Gas</a></div><divclass="hide link depth-2"><ahref="/v5/concepts/security/">Security</a></div><divclass="base ancestor show link depth-1"><ahref="/v5/api/">Application Programming Interface</a></div><divclass="ancestor show link depth-2"><ahref="/v5/api/contract/">Contract Interaction</a></div><divclass="show link depth-3"><ahref="/v5/api/contract/contract/">Contract</a></div><divclass="show link depth-3"><ahref="/v5/api/contract/contract-factory/">ContractFactory</a></div><divclass="myself ancestor ancestor show link depth-3"><ahref="/v5/api/contract/example/">Example: ERC-20 Contract</a></div><divclass="show link depth-2"><ahref="/v5/api/signer/">Signers</a></div><divclass="show link depth-2"><ahref="/v5/api/providers/">Providers</a></div><divclass="hide link depth-3"><ahref="/v5/api/providers/provider/">Provider</a></div><divclass="hide link depth-3"><ahref="/v5/api/providers/jsonrpc-provider/">JsonRpcProvider</a></div><divclass="hide link depth-3"><ahref="/v5/api/providers/api-providers/">API Providers</a></div><divclass="hide link depth-3"><ahref="/v5/api/providers/other/">Other Providers</a></div><divclass="hide link depth-3"><ahref="/v5/api/providers/types/">Types</a></div><divclass="show link depth-2"><ahref="/v5/api/utils/">Utilities</a></div><divclass="hide link depth-3"><ahref="/v5/api/utils/abi/">Application Binary Interface</a></div><divclass="hide link depth-4"><ahref="/v5/api/utils/abi/coder/">AbiCoder</a></div><divclass="hide link depth-4"><ahref="/v5/api/utils/abi/formats/">ABI Formats</a></div><divclass="hide link depth-4"><ahref="/v5/api/utils/abi/fragments/">Fragments</a></div><divclass="hide link depth-4"><ahref="/v5/api/utils/abi/interface/">Interface</a></div><divclass="hide link depth-3"><ahref="/v5/api/utils/address/">Addresses</a></div><divclass="hide link depth-3"><ahref="/v5/api/utils/bignumber/">BigNumber</a></div><divclass="hide link depth-3"><ahref="/v5/api/utils/bytes/">Byte Manipulation</a></div><divclass="hide link depth-3"><ahref="/v5/api/utils/constants/">Constants</a></div><divclass="hide link depth-3"><ahref="/v5/api/utils/display-logic/">Display Logic and Input</a></div><divclass="hide link depth-3"><ahref="/v5/api/utils/encoding/">Encoding Utilities</a></div><divclass="hide link depth-3"><ahref="/v5/api/utils/fixednumber/">FixedNumber</a></div><divclass="hide link depth-3"><ahref="/v5/api/utils/hashing/">Hashing Algorithms</a></div><divclass="hide link depth-3"><ahref="/v5/api/utils/hdnode/">HD Wallet</a></div><divclass="hide link depth-3"><ahref="/v5/api/utils/logger/">Logging</a></div><divclass="hide link depth-3"><ahref="/v5/api/utils/properties/">Property Utilities</a></div><divclass="hide link depth-3"><ahref="/v5/api/utils/signing-key/">Signing Key</a></div><divclass="hide link depth-3"><ahref="/v5/api/utils/strings/">Strings</a></div><divclass="hide link depth-3"><ahref="/v5/api/utils/transactions/">Transactions</a></div><divclass="hide link depth-3"><ahref="/v5/api/utils/web/">Web Utilities</a></div><divclass="hide link depth-3"><ahref="/v5/api/utils/wordlists/">Wordlists</a></div><divclass="show link depth-2"><ahref="/v5/api/other/">Other Libraries</a></div><divclass="hide link depth-3"><ahref="/v5/api/other/assembly/">Assembly</a></div><divclass="hide link depth-4"><ahref="/v5/api/other/assembly/dialect/">Ethers ASM Dialect</a></div><divclass="hide link depth-4"><ahref="/v5/api/other/assembly/api/">Utilities</a></div><divclass="hide link depth-4"><ahref="/v5/api/other/assembly/ast/">Abstract Syntax Tree</a></div><divclass="hide link depth-3"><ahref="/v5/api/other/hardware/">Hardware Wallets</a></div><divclass="sho
<aname="example-erc-20-contract--connecting-to-a-contract"></a><h2class="show-anchors"><div>Connecting to a Contract<divclass="anchors"><aclass="self"href="/v5/api/contract/example/#example-erc-20-contract--connecting-to-a-contract"></a></div></div></h2>
<divclass="code-title"><div>A simple ERC-20 contract</div></div><divclass="code"><spanclass="comment">// A Human-Readable ABI; any supported ABI format could be used
<divclass="property show-anchors"><divclass="signature"><spanclass="modifier">new </span><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="method">Contract</span><spanclass="symbol">(</span><spanclass="param">address</span><spanclass="symbol">,</span><spanclass="param">abi</span><spanclass="symbol">,</span><spanclass="param">providerOrSigner</span><spanclass="symbol">)</span><divclass="anchors"></div></div><divclass="body"><p>See the above code example for creating an Instance which will (in addition to the Contact methods and properties) automatically add the additional properties defined in <i>abi</i> to a <b>Contract</b> connected to <i>address</i> using the <i>providerOrSigner</i>.</p>
</div></div><aname="example-erc-20-contract--properties"></a><h2class="show-anchors"><div>Properties<spanclass="inherits">(inheritted from <ahref="/v5/api/contract/contract/">Contract</a>)</span><divclass="anchors"><aclass="self"href="/v5/api/contract/example/#example-erc-20-contract--properties"></a></div></div></h2>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">erc20</span><spanclass="symbol">.</span><spanclass="method">address</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="/v5/api/utils/address/#address">Address</a>></span><divclass="anchors"></div></div><divclass="body"><p>This is the address (or ENS name) the contract was constructed with.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">erc20</span><spanclass="symbol">.</span><spanclass="method">resolvedAddress</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="/v5/api/utils/address/#address">Address</a>></span><divclass="anchors"></div></div><divclass="body"><p>This is a promise that will resolve to the address the <b>Contract</b> object is attached to. If an <ahref="/v5/api/utils/address/#address">Address</a> was provided to the constructor, it will be equal to this; if an ENS name was provided, this will be the resolved address.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">erc20</span><spanclass="symbol">.</span><spanclass="method">deployTransaction</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="/v5/api/providers/types/#providers-TransactionResponse">TransactionResponse</a></span><divclass="anchors"></div></div><divclass="body"><p>If the <b>Contract</b> object is the result of a ContractFactory deployment, this is the transaction which was used to deploy the contract.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">erc20</span><spanclass="symbol">.</span><spanclass="method">interface</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="/v5/api/utils/abi/interface/">Interface</a></span><divclass="anchors"></div></div><divclass="body"><p>This is the ABI as an <ahref="/v5/api/utils/abi/interface/">Interface</a>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">erc20</span><spanclass="symbol">.</span><spanclass="method">provider</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="/v5/api/providers/provider/">Provider</a></span><divclass="anchors"></div></div><divclass="body"><p>If a provider was provided to the constructor, this is that provider. If a signer was provided that had a <ahref="/v5/api/providers/provider/">Provider</a>, this is that provider.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">erc20</span><spanclass="symbol">.</span><spanclass="method">signer</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="/v5/api/signer/#Signer">Signer</a></span><divclass="anchors"></div></div><divclass="body"><p>If a signer was provided to the constructor, this is that signer.</p>
</div></div><aname="example-erc-20-contract--methods"></a><h2class="show-anchors"><div>Methods<spanclass="inherits">(inheritted from <ahref="/v5/api/contract/contract/">Contract</a>)</span><divclass="anchors"><aclass="self"href="/v5/api/contract/example/#example-erc-20-contract--methods"></a></div></div></h2>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">erc20</span><spanclass="symbol">.</span><spanclass="method">attach</span><spanclass="symbol">(</span><spanclass="param">addressOrName</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="/v5/api/contract/contract/">Contract</a></span><divclass="anchors"></div></div><divclass="body"><p>Returns a new instance of the <b>Contract</b> attached to a new address. This is useful if there are multiple similar or identical copies of a Contract on the network and you wish to interact with each of them.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">erc20</span><spanclass="symbol">.</span><spanclass="method">connect</span><spanclass="symbol">(</span><spanclass="param">providerOrSigner</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="/v5/api/contract/contract/">Contract</a></span><divclass="anchors"></div></div><divclass="body"><p>Returns a new instance of the Contract, but connected to <i>providerOrSigner</i>.</p>
<p>By passing in a <ahref="/v5/api/providers/provider/">Provider</a>, this will return a downgraded <b>Contract</b> which only has read-only access (i.e. constant calls).</p>
</div></div><aname="erc20-events"></a><aname="example-erc-20-contract--erc20-events"></a><h2class="show-anchors"><div>Events<spanclass="inherits">(inheritted from <ahref="/v5/api/contract/contract/">Contract</a>)</span><divclass="anchors"><aclass="self"href="/v5/api/contract/example/#erc20-events"></a></div></div></h2>
<aname="erc20-queryfilter"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">erc20</span><spanclass="symbol">.</span><spanclass="method">queryFilter</span><spanclass="symbol">(</span><spanclass="param">event</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">fromBlockOrBlockHash</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">toBlock</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Promise< Array< Event >></span><divclass="anchors"><aclass="self"href="/v5/api/contract/example/#erc20-queryfilter"></a></div></div><divclass="body"><p>Return Events that match the <i>event</i>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">erc20</span><spanclass="symbol">.</span><spanclass="method">listenerCount</span><spanclass="symbol">(</span><spanclass="symbol">[</span><spanclass="param">event</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">number</span><divclass="anchors"></div></div><divclass="body"><p>Return the number of listeners that are subscribed to <i>event</i>. If no event is provided, returns the total count of all events.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">erc20</span><spanclass="symbol">.</span><spanclass="method">listeners</span><spanclass="symbol">(</span><spanclass="param">event</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Array< Listener ></span><divclass="anchors"></div></div><divclass="body"><p>Return a list of listeners that are subscribed to <i>event</i>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">erc20</span><spanclass="symbol">.</span><spanclass="method">off</span><spanclass="symbol">(</span><spanclass="param">event</span><spanclass="symbol">,</span><spanclass="param">listener</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">this</span><divclass="anchors"></div></div><divclass="body"><p>Unsubscribe <i>listener</i> to <i>event</i>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">erc20</span><spanclass="symbol">.</span><spanclass="method">on</span><spanclass="symbol">(</span><spanclass="param">event</span><spanclass="symbol">,</span><spanclass="param">listener</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">this</span><divclass="anchors"></div></div><divclass="body"><p>Subscribe to <i>event</i> calling <i>listener</i> when the event occurs.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">erc20</span><spanclass="symbol">.</span><spanclass="method">once</span><spanclass="symbol">(</span><spanclass="param">event</span><spanclass="symbol">,</span><spanclass="param">listener</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">this</span><divclass="anchors"></div></div><divclass="body"><p>Subscribe once to <i>event</i> calling <i>listener</i> when the event occurs.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">erc20</span><spanclass="symbol">.</span><spanclass="method">removeAllListeners</span><spanclass="symbol">(</span><spanclass="symbol">[</span><spanclass="param">event</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">this</span><divclass="anchors"></div></div><divclass="body"><p>Unsubscribe all listeners for <i>event</i>. If no event is provided, all events are unsubscribed.</p>
</div></div><aname="example-erc-20-contract--meta-class-methods"></a><h2class="show-anchors"><div>Meta-Class Methods<spanclass="inherits">(added at Runtime)</span><divclass="anchors"><aclass="self"href="/v5/api/contract/example/#example-erc-20-contract--meta-class-methods"></a></div></div></h2><p>Since the Contract is a Meta-Class, the methods available here depend on the ABI which was passed into the <b>Contract</b>.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">erc20</span><spanclass="symbol">.</span><spanclass="method">decimals</span><spanclass="symbol">(</span><spanclass="symbol">[</span><spanclass="param">overrides</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Promise< number ></span><divclass="anchors"></div></div><divclass="body"><p>Returns the number of decimal places used by this ERC-20 token. This can be used with <ahref="/v5/api/utils/display-logic/#utils-parseUnits">parseUnits</a> when taking input from the user or [formatUnits](utils-formatunits] when displaying the token amounts in the UI.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">erc20</span><spanclass="symbol">.</span><spanclass="method">getBalance</span><spanclass="symbol">(</span><spanclass="param">owner</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">overrides</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Promise<<ahref="/v5/api/utils/bignumber/">BigNumber</a>></span><divclass="anchors"></div></div><divclass="body"><p>Returns the balance of <i>owner</i> for this ERC-20 token.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">erc20</span><spanclass="symbol">.</span><spanclass="method">symbol</span><spanclass="symbol">(</span><spanclass="symbol">[</span><spanclass="param">overrides</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Promise< string ></span><divclass="anchors"></div></div><divclass="body"><p>Returns the symbol of the token.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">erc20_rw</span><spanclass="symbol">.</span><spanclass="method">transfer</span><spanclass="symbol">(</span><spanclass="param">target</span><spanclass="symbol">,</span><spanclass="param">amount</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">overrides</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Promise<<ahref="/v5/api/providers/types/#providers-TransactionResponse">TransactionResponse</a>></span><divclass="anchors"></div></div><divclass="body"><p>Transfers <i>amount</i> tokens to <i>target</i> from the current signer. The return value (a boolean) is inaccessible during a write operation using a transaction. Other techniques (such as events) are required if this value is required. On-chain contracts calling the <codeclass="inline">transfer</code> function have access to this result, which is why it is possible.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">erc20</span><spanclass="symbol">.</span><spanclass="path">callStatic</span><spanclass="symbol">.</span><spanclass="method">transfer</span><spanclass="symbol">(</span><spanclass="param">target</span><spanclass="symbol">,</span><spanclass="param">amount</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">overrides</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Promise< boolean ></span><divclass="anchors"></div></div><divclass="body"><p>Performs a dry-run of transferring <i>amount</i> tokens to <i>target</i> from the current signer, without actually signing or sending a transaction.</p>
<p>This can be used to preflight check that a transaction will be successful.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">erc20</span><spanclass="symbol">.</span><spanclass="path">estimateGas</span><spanclass="symbol">.</span><spanclass="method">transfer</span><spanclass="symbol">(</span><spanclass="param">target</span><spanclass="symbol">,</span><spanclass="param">amount</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">overrides</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Promise<<ahref="/v5/api/utils/bignumber/">BigNumber</a>></span><divclass="anchors"></div></div><divclass="body"><p>Returns an estimate for how many units of gas would be required to transfer <i>amount</i> tokens to <i>target</i>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">erc20</span><spanclass="symbol">.</span><spanclass="path">populateTransaction</span><spanclass="symbol">.</span><spanclass="method">transfer</span><spanclass="symbol">(</span><spanclass="param">target</span><spanclass="symbol">,</span><spanclass="param">amount</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">overrides</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Promise<<ahref="/v5/api/utils/transactions/#UnsignedTransaction">UnsignedTx</a>></span><divclass="anchors"></div></div><divclass="body"><p>Returns an <ahref="/v5/api/utils/transactions/#UnsignedTransaction">UnsignedTransaction</a> which could be signed and submitted to the network to transaction <i>amount</i> tokens to <i>target</i>.</p>
</div></div><divclass="definition container-box note"><divclass="term">Note on Estimating and Static Calling</div><divclass="body"><p>When you perform a static call, the current state is taken into account as best as Ethereum can determine. There are many cases where this can provide false positives and false negatives. The eventually consistent model of the blockchain also means there are certain consistency modes that cannot be known until an actual transaction is attempted.</p>
</div></div><aname="example-erc-20-contract--meta-class-filters"></a><h2class="show-anchors"><div>Meta-Class Filters<spanclass="inherits">(added at Runtime)</span><divclass="anchors"><aclass="self"href="/v5/api/contract/example/#example-erc-20-contract--meta-class-filters"></a></div></div></h2><p>Since the Contract is a Meta-Class, the methods available here depend on the ABI which was passed into the <b>Contract</b>.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">erc20</span><spanclass="symbol">.</span><spanclass="path">filters</span><spanclass="symbol">.</span><spanclass="method">Transafer</span><spanclass="symbol">(</span><spanclass="symbol">[</span><spanclass="param">fromAddress</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">toAddress</span><spanclass="symbol">]</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Filter</span><divclass="anchors"></div></div><divclass="body"><p>Returns a new Filter which can be used to <ahref="/v5/api/contract/example/#erc20-queryfilter">query</a> or to <ahref="/v5/api/contract/example/#erc20-events">subscribe/unsubscribe to events</a>.</p>
<p>If <i>fromAddress</i> is null or not provided, then any from address matches. If <i>toAddress</i> is null or not provided, then any to address matches.</p>
<divclass="copyright">The content of this site is licensed under the <ahref="https://choosealicense.com/licenses/cc-by-4.0/">Creative Commons License</a>. Generated on July 5, 2020, 12:0am.</div>
