<divclass="link title"><ahref="/v5/single-page/">Documentation</a></div><divclass="show show link depth-1"><ahref="#/v5/getting-started/">Getting Started</a></div><divclass="show show link depth-1"><ahref="#/v5/concepts/">Ethereum Basics</a></div><divclass="show show link depth-2"><ahref="#/v5/concepts/events/">Events</a></div><divclass="show show link depth-2"><ahref="#/v5/concepts/gas/">Gas</a></div><divclass="show show link depth-2"><ahref="#/v5/concepts/security/">Security</a></div><divclass="show show link depth-1"><ahref="#/v5/api/">Application Programming Interface</a></div><divclass="show show link depth-2"><ahref="#/v5/api/contract/">Contract Interaction</a></div><divclass="show show link depth-3"><ahref="#/v5/api/contract/contract/">Contract</a></div><divclass="show show link depth-3"><ahref="#/v5/api/contract/contract-factory/">ContractFactory</a></div><divclass="show show link depth-3"><ahref="#/v5/api/contract/example/">Example: ERC-20 Contract</a></div><divclass="show show link depth-2"><ahref="#/v5/api/signer/">Signers</a></div><divclass="show show link depth-2"><ahref="#/v5/api/providers/">Providers</a></div><divclass="show show link depth-3"><ahref="#/v5/api/providers/provider/">Provider</a></div><divclass="show show link depth-3"><ahref="#/v5/api/providers/jsonrpc-provider/">JsonRpcProvider</a></div><divclass="show show link depth-3"><ahref="#/v5/api/providers/api-providers/">API Providers</a></div><divclass="show show link depth-3"><ahref="#/v5/api/providers/other/">Other Providers</a></div><divclass="show show link depth-3"><ahref="#/v5/api/providers/types/">Types</a></div><divclass="show show link depth-2"><ahref="#/v5/api/utils/">Utilities</a></div><divclass="show show link depth-3"><ahref="#/v5/api/utils/abi/">Application Binary Interface</a></div><divclass="show show link depth-4"><ahref="#/v5/api/utils/abi/coder/">AbiCoder</a></div><divclass="show show link depth-4"><ahref="#/v5/api/utils/abi/formats/">ABI Formats</a></div><divclass="show show link depth-4"><ahref="#/v5/api/utils/abi/fragments/">Fragments</a></div><divclass="show show link depth-4"><ahref="#/v5/api/utils/abi/interface/">Interface</a></div><divclass="show show link depth-3"><ahref="#/v5/api/utils/address/">Addresses</a></div><divclass="show show link depth-3"><ahref="#/v5/api/utils/bignumber/">BigNumber</a></div><divclass="show show link depth-3"><ahref="#/v5/api/utils/bytes/">Byte Manipulation</a></div><divclass="show show link depth-3"><ahref="#/v5/api/utils/constants/">Constants</a></div><divclass="show show link depth-3"><ahref="#/v5/api/utils/display-logic/">Display Logic and Input</a></div><divclass="show show link depth-3"><ahref="#/v5/api/utils/encoding/">Encoding Utilities</a></div><divclass="show show link depth-3"><ahref="#/v5/api/utils/fixednumber/">FixedNumber</a></div><divclass="show show link depth-3"><ahref="#/v5/api/utils/hashing/">Hashing Algorithms</a></div><divclass="show show link depth-3"><ahref="#/v5/api/utils/hdnode/">HD Wallet</a></div><divclass="show show link depth-3"><ahref="#/v5/api/utils/logger/">Logging</a></div><divclass="show show link depth-3"><ahref="#/v5/api/utils/properties/">Property Utilities</a></div><divclass="show show link depth-3"><ahref="#/v5/api/utils/signing-key/">Signing Key</a></div><divclass="show show link depth-3"><ahref="#/v5/api/utils/strings/">Strings</a></div><divclass="show show link depth-3"><ahref="#/v5/api/utils/transactions/">Transactions</a></div><divclass="show show link depth-3"><ahref="#/v5/api/utils/web/">Web Utilities</a></div><divclass="show show link depth-3"><ahref="#/v5/api/utils/wordlists/">Wordlists</a></div><divclass="show show link depth-2"><ahref="#/v5/api/other/">Other Libraries</a></div><divclass="show show link depth-3"><ahref="#/v5/api/other/assembly/">Assembly</a></div><divclass="show show link depth-4"><ahref="#/v5/api/other/assembly/dialect/">Ethers ASM Dialect</a></div><divclass="show show link depth-4"><ahref="#/v5/api/other/assembly/api/">Utilities</a
<aname="/v5/-%23-preamble"></a><aname="/v5/-%23-documentation--preamble"></a><aname="/v5/"></a><h2class="show-anchors"><div>What is Ethers?<divclass="anchors"><aclass="self"href="#/v5/-%23-preamble"></a></div></div></h2><p>The ethers.js library aims to be a complete and compact library for interacting with the Ethereum Blockchain and its ecosystem. It was originally designed for use with <ahref="https://ethers.io/">ethers.io</a> and has since expanded into a much more general-purpose library.</p>
<aname="/v5/-%23-features"></a><aname="/v5/-%23-documentation--features"></a><aname="/v5/"></a><h2class="show-anchors"><div>Features<divclass="anchors"><aclass="self"href="#/v5/-%23-features"></a></div></div></h2><p><ul><li>Keep your private keys in your client, <b>safe</b> and sound </li><li>Import and export <b>JSON wallets</b> (Geth, Parity and crowdsale) </li><li>Import and export BIP 39 <b>mnemonic phrases</b> (12 word backup phrases) and HD Wallets (English, Italian, Japanese, Korean, Simplified Chinese, Traditional Chinese; more coming soon) </li><li>Meta-classes create JavaScript objects from any contract ABI, including <b>ABIv2</b> and <b>Human-Readable ABI</b></li><li>Connect to Ethereum nodes over <ahref="https://github.com/ethereum/wiki/wiki/JSON-RPC">JSON-RPC</a>, <ahref="https://infura.io">INFURA</a>, <ahref="https://etherscan.io">Etherscan</a>, <ahref="https://alchemyapi.io">Alchemy</a>, <ahref="https://developers.cloudflare.com/distributed-web/ethereum-gateway/">Cloudflare</a> or <ahref="https://metamask.io/">MetaMask</a>. </li><li><b>ENS names</b> are first-class citizens; they can be used anywhere an Ethereum addresses can be used </li><li><b>Tiny</b> (~88kb compressed; 284kb uncompressed) </li><li><b>Complete</b> functionality for all your Ethereum needs </li><li>Extensive <ahref="https://docs.ethers.io/">documentation</a></li><li>Large collection of <b>test cases</b> which are maintained and added to </li><li>Fully <b>TypeScript</b> ready, with definition files and full TypeScript source </li><li><b>MIT License</b> (including <i>ALL</i> dependencies); completely open source to do with as you please </li></ul></p>
<divclass="toc"><divstyle="padding-left: 0px"><spanclass="bullet">•</span><ahref="#/v5/getting-started/">Getting Started</a></div><divstyle="padding-left: 0px"><spanclass="bullet">•</span><ahref="#/v5/concepts/">Ethereum Basics</a></div><divstyle="padding-left: 0px"><spanclass="bullet">•</span><ahref="#/v5/api/">Application Programming Interface</a></div><divstyle="padding-left: 0px"><spanclass="bullet">•</span><ahref="#/v5/cli/">Command Line Interfaces</a></div><divstyle="padding-left: 0px"><spanclass="bullet">•</span><ahref="#/v5/cookbook/">Cookbook</a></div><divstyle="padding-left: 0px"><spanclass="bullet">•</span><ahref="#/v5/migration/">Migration Guide</a></div><divstyle="padding-left: 0px"><spanclass="bullet">•</span><ahref="#/v5/testing/">Testing</a></div><divstyle="padding-left: 0px"><spanclass="bullet">•</span><ahref="#/v5/contributing/">Contributing and Hacking</a></div><divstyle="padding-left: 0px"><spanclass="bullet">•</span><ahref="#/v5/documentation/">Flatworm Docs</a></div><divstyle="padding-left: 0px"><spanclass="bullet">•</span><ahref="#/v5/license/">License and Copyright</a></div></div><aname="/v5/-%23-documentation--legacy"></a><aname="/v5/-%23-documentation--documentation--legacy"></a><aname="/v5/"></a><h2class="show-anchors"><div>Legacy Documentation<divclass="anchors"><aclass="self"href="#/v5/-%23-documentation--legacy"></a></div></div></h2><p>This section will be kept up to date, linking to documentation of older versions of the library.</p>
<aname="/v5/getting-started/-%23-installing"></a><aname="/v5/getting-started/-%23-getting-started--installing"></a><aname="/v5/getting-started/"></a><h2class="show-anchors"><div>Installing<divclass="anchors"><aclass="self"href="#/v5/getting-started/-%23-installing"></a></div></div></h2><p>The various Classes and Functions are available to be imported manually from sub-packages under the <ahref="https://www.npmjs.com/search?q=%40ethersproject%2F">@ethersproject</a> organization but for most projects, the umbrella package is the easiest way to get started.</p>
</div><divclass="code-title"><div>ES6 or TypeScript</div></div><divclass="code">import { ethers } from "ethers";
</div><aname="/v5/getting-started/-%23-getting-started--importing--web-browser"></a><aname="/v5/getting-started/"></a><h3class="show-anchors"><div>Web Browser<divclass="anchors"><aclass="self"href="#/v5/getting-started/-%23-getting-started--importing--web-browser"></a></div></div></h3><p>It is generally better practice (for security reasons) to copy the <ahref="https://cdn.ethers.io/lib/ethers-5.0.esm.min.js">ethers library</a> to your own webserver and serve it yourself.</p>
<divclass="code-title"><div>ES6 in the Browser</div></div><divclass="code"><script type="module">
import { ethers } from "https://cdn.ethers.io/lib/ethers-5.0.esm.min.js";
// Your code here...
</script></div><divclass="code-title"><div>ES3 (UMD) in the Browser</div></div><divclass="code"><script src="https://cdn.ethers.io/lib/ethers-5.0.umd.min.js"
<tableclass="table minimal"><tr><tdalign="left"><b>Provider</b></td><tdalign="left">A Provider (in ethers) is a class which provides an abstraction for a connection to the Ethereum Network. It provides read-only access to the Blockchain and its status.</td><tdclass="fix"> </td></tr><tr><tdalign="left"><b>Signer</b></td><tdalign="left">A Signer is a class which (usually) in some way directly or indirectly has access to a private key, which can sign messages and transactions to authorize the network to charge your account ether to perform operations.</td><tdclass="fix"> </td></tr><tr><tdalign="left"><b>Contract</b></td><tdalign="left">A Contract is an abstraction which represents a connection to a specific contract on the Ethereum Network, so that it can be used like a normal JavaScipt object.</td><tdclass="fix"> </td></tr><tr><tdclass="table-title"colspan="2">Common Terms</td><tdclass="fix"> </td></tr></table><aname="/v5/getting-started/-%23-getting-started--connecting"></a><aname="/v5/getting-started/-%23-getting-started--getting-started--connecting"></a><aname="/v5/getting-started/"></a><h2class="show-anchors"><div>Connecting to Ethereum: Metamask<divclass="anchors"><aclass="self"href="#/v5/getting-started/-%23-getting-started--connecting"></a></div></div></h2><p>The quickest and easiest way to experiment and begin developing on Ethereum is to use <ahref="https://metamask.io/">Metamask</a>, which is a browser extension that provides:</p>
<p><ul><li>A connection to the Ethereum network (a <ahref="#/v5/api/providers/provider/">Provider</a>) </li><li>Holds your private key and can sign things (a <ahref="#/v5/api/signer/-%23-Signer">Signer</a>) </li></ul></p>
<divclass="code-title"><div>Connecting to Metamask</div></div><divclass="code"><spanclass="comment">// A Web3Provider wraps a standard Web3 provider, which is
</span><spanclass="comment">// what Metamask injects as window.ethereum into each page
</span>const provider = new ethers.providers.Web3Provider(window.ethereum)
<spanclass="comment">// The Metamask plugin also allows signing transactions to
</span><spanclass="comment">// send ether and pay to change state within the blockchain.
</span><spanclass="comment">// For this, we need the account signer...
</span>const signer = provider.getSigner()
</div><aname="/v5/getting-started/-%23-getting-started--querying"></a><aname="/v5/getting-started/-%23-getting-started--getting-started--connecting--getting-started--querying"></a><aname="/v5/getting-started/"></a><h3class="show-anchors"><div>Querying the Blockchain<divclass="anchors"><aclass="self"href="#/v5/getting-started/-%23-getting-started--querying"></a></div></div></h3><p>Once you have a <ahref="#/v5/api/providers/provider/">Provider</a>, you have a read-only connection to the blockchain, which can be used to query the current state, fetch historic logs, look up deployed code and so on.</p>
<divclass="code-title"><div>Basic Queries</div></div><divclass="code"><spanclass="comment">// Look up the current block number
</span></div><aname="/v5/getting-started/-%23-getting-started--sending"></a><aname="/v5/getting-started/-%23-getting-started--getting-started--connecting--getting-started--sending"></a><aname="/v5/getting-started/"></a><h3class="show-anchors"><div>Writing to the Blockchain<divclass="anchors"><aclass="self"href="#/v5/getting-started/-%23-getting-started--sending"></a></div></div></h3>
<divclass="code-title"><div>Sending Ether</div></div><divclass="code"><spanclass="comment">// Send 1 ether to an ens name.
</div><aname="/v5/getting-started/-%23-getting-started--contracts"></a><aname="/v5/getting-started/-%23-getting-started--getting-started--contracts"></a><aname="/v5/getting-started/"></a><h2class="show-anchors"><div>Contracts<divclass="anchors"><aclass="self"href="#/v5/getting-started/-%23-getting-started--contracts"></a></div></div></h2><p>A Contract is an abstraction of program code which lives on the Ethereum blockchain.</p>
<p>The <ahref="#/v5/api/contract/contract/">Contract</a> object makes it easier to use an on-chain Contract as a normal JavaScript object, with the method all mapped to encoding and decoding data for you.</p>
<p>If you are familiar with Databases, this is similar to ORM.</p>
<p>In order to communicate with the Contract on-chain, this class needs to know what methods are available and how to encode and decode the data, which is what the <i>Application Binary Interface</i> (API) provides.</p>
<p>This class is a meta-class, which means its methods are constructed at runtime, when you pass in the ABI to the constructor it uses that to determine which methods to add.</p>
<p>While a on-chain Contract may have many methods available, you can safely ignore any methods you don't need or use, providing a smaller subset of the ABI to the contract.</p>
<p>An ABI often comes from the Solidity or Vyper compiler, but may also be placed in the code easily using the Human-Readable ABI, which the following examples use.</p>
<divclass="code-title"><div>Connecting to the DAI Contract</div></div><divclass="code"><spanclass="comment">// We can use an ENS name for the contract address
</div><aname="/v5/getting-started/-%23-getting-started--events"></a><aname="/v5/getting-started/-%23-getting-started--getting-started--contracts--getting-started--events"></a><aname="/v5/getting-started/"></a><h3class="show-anchors"><div>Listening to Events<divclass="anchors"><aclass="self"href="#/v5/getting-started/-%23-getting-started--events"></a></div></div></h3>
<divclass="code-title"><div>Listening to Events</div></div><divclass="code"><spanclass="comment">// Receive an event when ANY transfer occurs
</span>daiContract.on("Transfer", (from, to, amount, event) => {
</span></div><divclass="page-separator"></div><aname="/v5/concepts/-%23-ethereum-basics"></a><aname="/v5/concepts/"></a><h1class="show-anchors"><div>Ethereum Basics<divclass="anchors"><aclass="self"href="#/v5/concepts/-%23-ethereum-basics"></a></div></div></h1><p>This is a very breif overview of some aspects of <i>Ethereum</i> and blockchains which developers can make use of or should be aware of.</p>
<p>This section is fairly sparse at the moment, but will be expanded as time goes on.</p>
<divclass="toc"><divstyle="padding-left: 0px"><spanclass="bullet">•</span><ahref="#/v5/concepts/events/">Events</a></div><divstyle="padding-left: 0px"><spanclass="bullet">•</span><ahref="#/v5/concepts/gas/">Gas</a></div><divstyle="padding-left: 0px"><spanclass="bullet">•</span><ahref="#/v5/concepts/security/">Security</a></div></div><divclass="page-separator"></div><aname="/v5/concepts/events/-%23-events"></a><aname="/v5/concepts/events/"></a><h1class="show-anchors"><div>Events<divclass="anchors"><aclass="self"href="#/v5/concepts/events/-%23-events"></a></div></div></h1><p>Explain how topics and such work</p>
<aname="/v5/concepts/events/-%23-events--solidity-topics"></a><aname="/v5/concepts/events/"></a><h2class="show-anchors"><div>Solidity Topics<divclass="anchors"><aclass="self"href="#/v5/concepts/events/-%23-events--solidity-topics"></a></div></div></h2><p>How to compute the topic...</p>
<aname="/v5/concepts/events/-%23-events--logs-and-filtering"></a><aname="/v5/concepts/events/"></a><h2class="show-anchors"><div>Logs and Filtering<divclass="anchors"><aclass="self"href="#/v5/concepts/events/-%23-events--logs-and-filtering"></a></div></div></h2><p>Example hog logs are used.</p>
<p>Link to provider.getLogs and contract.on</p>
<aname="/v5/concepts/events/-%23-events--logs-and-filtering--filters"></a><aname="/v5/concepts/events/"></a><h3class="show-anchors"><div>Filters<divclass="anchors"><aclass="self"href="#/v5/concepts/events/-%23-events--logs-and-filtering--filters"></a></div></div></h3><p>Filter are used as a way to query ... efficient, explain bloom filters lightly</p>
<p>A filter may have up to 4 topic-sets, where each topic-set refers to a condition that must match the log topic in that position (i.e. each condition is <codeclass="inline">AND</code>-ed together).</p>
<p>If a topic-set is <codeclass="inline">null</code>, a log topic in that position is not filtered at all and <b>any value</b> matches.</p>
<p>If a topic-set is a single topic, a log topic in that position must match <b>that topic</b>.</p>
<p>If a topic-set is an array of topics, a log topic in that position must match any <b>one</b> of the topics (i.e. the topic in this position are <codeclass="inline">OR</code>-ed).</p>
<tableclass="table full"><tr><tdalign="center"width="25%"><b>Topic-Sets</b></td><tdalign="center"colspan="3"width="75%"><b>Matching Logs</b></td><tdclass="fix"> </td></tr><tr><tdalign="center"width="25%">[ A ]</td><tdalign="left"colspan="3"rowspan="2"width="75%">topic[0] = A</td><tdclass="fix"> </td></tr><tr><tdalign="center"width="25%">[ A, null ]</td><tdclass="fix"> </td></tr><tr><tdalign="center"width="25%">[ null, B ]</td><tdalign="left"colspan="3"rowspan="3"width="75%">topic[1] = B</td><tdclass="fix"> </td></tr><tr><tdalign="center"width="25%">[ null, [ B ] ]</td><tdclass="fix"> </td></tr><tr><tdalign="center"width="25%">[ null, [ B ], null ]</td><tdclass="fix"> </td></tr><tr><tdalign="center"width="25%">[ A, B ]</td><tdalign="left"colspan="3"rowspan="3"width="75%">(topic[0] = A) <b>AND</b> (topic[1] = B)</td><tdclass="fix"> </td></tr><tr><tdalign="center"width="25%">[ A, [ B ] ]</td><tdclass="fix"> </td></tr><tr><tdalign="center"width="25%">[ A, [ B ], null ]</td><tdclass="fix"> </td></tr><tr><tdalign="center"width="25%">[ [ A, B ] ]</td><tdalign="left"colspan="3"rowspan="2"width="75%">(topic[0] = A) <b>OR</b> (topic[0] = B)</td><tdclass="fix"> </td></tr><tr><tdalign="center"width="25%">[ [ A, B ], null ]</td><tdclass="fix"> </td></tr><tr><tdalign="center"width="25%">[ [ A, B ], [ C, D ] ]</td><tdalign="left"colspan="3"width="75%"><b>[</b> (topic[0] = A) <b>OR</b> (topic[0] = B) <b>]</b><b>AND</b><b>[</b> (topic[1] = C) <b>OR</b> (topic[1] = D) <b>]</b></td><tdclass="fix"> </td></tr><tr><tdclass="table-title"colspan="4">Example Log Matching</td><tdclass="fix"> </td></tr></table><divclass="code-title"><div>ERC-20 Transfer Filter Examples</div></div><divclass="code"><spanclass="comment">// Short example of manually creating filters for an ERC-20
</span><spanclass="comment">// Transfer event.
</span>//
<spanclass="comment">// Most users should generally use the Contract API to
</span><spanclass="comment">// compute filters, as it is much simpler, but this is
</span><spanclass="comment">// provided as an illustration for those curious. See
</span><spanclass="comment">// below for examples of the equivalent Contract API.
</span></div><aname="/v5/concepts/events/-%23-events--logs-and-filtering--other-things-todo"></a><aname="/v5/concepts/events/"></a><h3class="show-anchors"><div>Other Things? TODO<divclass="anchors"><aclass="self"href="#/v5/concepts/events/-%23-events--logs-and-filtering--other-things-todo"></a></div></div></h3><p>Explain what happens to strings and bytes, how to filter and retain the value</p>
<aname="/v5/concepts/gas/-%23-gas-price"></a><aname="/v5/concepts/gas/-%23-gas--gas-price"></a><aname="/v5/concepts/gas/"></a><h2class="show-anchors"><div>Gas Price<divclass="anchors"><aclass="self"href="#/v5/concepts/gas/-%23-gas-price"></a></div></div></h2><p>The gas price is used somewhat like a bid, indicating an amount you are willing to pay (per unit of execution) to have your transaction processed.</p>
<aname="/v5/concepts/security/-%23-security--pbkdf"></a><aname="/v5/concepts/security/-%23-security--security--pbkdf"></a><aname="/v5/concepts/security/"></a><h2class="show-anchors"><div>Key Derivation Functions<divclass="anchors"><aclass="self"href="#/v5/concepts/security/-%23-security--pbkdf"></a></div></div></h2><p>This is not specific to Ethereum, but is a useful technique to understand and has some implications on User Experience.</p>
<p>Many people are concerned that encrypting and decrypting an Ethereum wallet is quite slow and can take quite some time. It is important to understand this is intentional and provides much stronger security.</p>
<p>The algorithm usually used for this process is <ahref="https://en.wikipedia.org/wiki/Scrypt">scrypt</a>, which is a memory and CPU intensive algorithm which computes a key (fixed-length pseudo-random series of bytes) for a given password.</p>
<aname="/v5/concepts/security/-%23-security--security--pbkdf--why-does-it-take-so-long"></a><aname="/v5/concepts/security/"></a><h3class="show-anchors"><div>Why does it take so long?<divclass="anchors"><aclass="self"href="#/v5/concepts/security/-%23-security--security--pbkdf--why-does-it-take-so-long"></a></div></div></h3><p>The goal is to use as much CPU and memory as possible during this algorithm, so that a single computer can only compute a very small number of results for some fixed amount of time. To scale up an attack, the attacker requires additional compuers, increasing the cost to <ahref="https://en.wikipedia.org/wiki/Brute-force_attack">brute-force attack</a> to guess the password.</p>
<p>For example, if a user knows their correct password, this process may take 10 seconds for them to unlock their own wallet and proceed.</p>
<p>But since an attacker does not know the password, they must guess; and each guess also requires 10 seconds. So, if they wish to try guessing 1 million passwords, their computer would be completely tied up for 10 million seconds, or around 115 days.</p>
<p>Without using an algorithm like this, a user would be able to log in instantly, however, 1 million passwords would only take a few seconds to attempt. Even secure passwords would likely be broken within a short period of time. There is no way the algorithm can be faster for a legitimate user without also being faster for an attacker.</p>
<aname="/v5/concepts/security/-%23-security--security--pbkdf--mitigating-the-user-experience"></a><aname="/v5/concepts/security/"></a><h3class="show-anchors"><div>Mitigating the User Experience<divclass="anchors"><aclass="self"href="#/v5/concepts/security/-%23-security--security--pbkdf--mitigating-the-user-experience"></a></div></div></h3><p>Rather than reducing the security (see below), a better practice is to make the user feel better about waiting. The Ethers encryption and decryption API allows the developer to incorporate a progress bar, by passing in a progress callback which will be periodically called with a number between 0 and 1 indication percent completion.</p>
<p>In general a progress bar makes the experience feel faster, as well as more comfortable since there is a clear indication how much (relative) time is remaining. Additionally, using language like <i>"decrypting..."</i> in a progress bar makes a user feel like there time is not being <i>needlessly</i> wasted.</p>
<aname="/v5/concepts/security/-%23-security--security--pbkdf--work-arounds-not-recommended"></a><aname="/v5/concepts/security/"></a><h3class="show-anchors"><div>Work-Arounds (not recommended)<divclass="anchors"><aclass="self"href="#/v5/concepts/security/-%23-security--security--pbkdf--work-arounds-not-recommended"></a></div></div></h3><p>There are ways to reduce the time required to decrypt an Ethereum JSON Wallet, but please keep in mind that doing so <b>discards nearly all security</b> on that wallet.</p>
<p>The scrypt algorithm is designed to be tuned. The main purpose of this is to increase the difficulty as time goes on and computers get faster, but it can also be tuned down in situations where the security is less important.</p>
</div><divclass="page-separator"></div><aname="/v5/api/-%23-api"></a><aname="/v5/api/-%23-api"></a><aname="/v5/api/"></a><h1class="show-anchors"><div>Application Programming Interface<divclass="anchors"><aclass="self"href="#/v5/api/-%23-api"></a></div></div></h1><p>An Application Programming Interface (API) is the formal specification of the library.</p>
<divclass="toc"><divstyle="padding-left: 0px"><spanclass="bullet">•</span><ahref="#/v5/api/contract/">Contract Interaction</a></div><divstyle="padding-left: 0px"><spanclass="bullet">•</span><ahref="#/v5/api/signer/">Signers</a></div><divstyle="padding-left: 0px"><spanclass="bullet">•</span><ahref="#/v5/api/providers/">Providers</a></div><divstyle="padding-left: 0px"><spanclass="bullet">•</span><ahref="#/v5/api/utils/">Utilities</a></div><divstyle="padding-left: 0px"><spanclass="bullet">•</span><ahref="#/v5/api/other/">Other Libraries</a></div><divstyle="padding-left: 0px"><spanclass="bullet">•</span><ahref="#/v5/api/experimental/">Experimental</a></div></div><divclass="page-separator"></div><aname="/v5/api/contract/-%23-contracts"></a><aname="/v5/api/contract/-%23-contracts"></a><aname="/v5/api/contract/"></a><h1class="show-anchors"><div>Contract Interaction<divclass="anchors"><aclass="self"href="#/v5/api/contract/-%23-contracts"></a></div></div></h1><p>A <b>Contract</b> object is an abstraction of a contract (EVM bytecode) deployed on the Ethereum network. It allows for a simple way to serialize calls and transactions to an on-chain contract and deserialize their results and emitted logs.</p>
</div></div><aname="/v5/api/contract/contract/-%23-Contract-attach"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">contract</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"><aclass="self"href="#/v5/api/contract/contract/-%23-Contract-attach"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/contracts/src.ts/index.ts#L821">source</a></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><aname="/v5/api/contract/contract/-%23-Contract-connect"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">contract</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"><aclass="self"href="#/v5/api/contract/contract/-%23-Contract-connect"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/contracts/src.ts/index.ts#L808">source</a></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>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">contract</span><spanclass="symbol">.</span><spanclass="method">address</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/address/-%23-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">contract</span><spanclass="symbol">.</span><spanclass="method">resolvedAddress</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/address/-%23-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/-%23-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">contract</span><spanclass="symbol">.</span><spanclass="method">deployTransaction</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/providers/types/-%23-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">contract</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">contract</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">contract</span><spanclass="symbol">.</span><spanclass="method">signer</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/signer/-%23-Signer">Signer</a></span><divclass="anchors"></div></div><divclass="body"><p>If a signer was provided to the constructor, this is that signer.</p>
<aname="/v5/api/contract/contract/-%23-Contract-queryFilter"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">contract</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/contract/-%23-Contract-queryFilter"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/contracts/src.ts/index.ts#L964">source</a></div></div><divclass="body"><p>Return Events that match the <i>event</i>.</p>
</div></div><aname="/v5/api/contract/contract/-%23-Contract-listenerCount"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">contract</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"><aclass="self"href="#/v5/api/contract/contract/-%23-Contract-listenerCount"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/contracts/src.ts/index.ts#L1005">source</a></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><aname="/v5/api/contract/contract/-%23-Contract-listeners"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">contract</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"><aclass="self"href="#/v5/api/contract/contract/-%23-Contract-listeners"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/contracts/src.ts/index.ts#L1010">source</a></div></div><divclass="body"><p>Return a list of listeners that are subscribed to <i>event</i>.</p>
</div></div><aname="/v5/api/contract/contract/-%23-Contract-off"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">contract</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"><aclass="self"href="#/v5/api/contract/contract/-%23-Contract-off"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/contracts/src.ts/index.ts#L1046">source</a></div></div><divclass="body"><p>Unsubscribe <i>listener</i> to <i>event</i>.</p>
</div></div><aname="/v5/api/contract/contract/-%23-Contract-on"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">contract</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"><aclass="self"href="#/v5/api/contract/contract/-%23-Contract-on"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/contracts/src.ts/index.ts#L983">source</a></div></div><divclass="body"><p>Subscribe to <i>event</i> calling <i>listener</i> when the event occurs.</p>
</div></div><aname="/v5/api/contract/contract/-%23-Contract-once"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">contract</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"><aclass="self"href="#/v5/api/contract/contract/-%23-Contract-once"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/contracts/src.ts/index.ts#L988">source</a></div></div><divclass="body"><p>Subscribe once to <i>event</i> calling <i>listener</i> when the event occurs.</p>
</div></div><aname="/v5/api/contract/contract/-%23-Contract-removeAllListeners"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">contract</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"><aclass="self"href="#/v5/api/contract/contract/-%23-Contract-removeAllListeners"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/contracts/src.ts/index.ts#L1026">source</a></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="/v5/api/contract/contract/-%23-Contract--metaclass"></a><aname="/v5/api/contract/contract/-%23-Contract--Contract--metaclass"></a><aname="/v5/api/contract/contract/"></a><h2class="show-anchors"><div>Meta-Class<divclass="anchors"><aclass="self"href="#/v5/api/contract/contract/-%23-Contract--metaclass"></a></div></div></h2><p>A Meta-Class is a Class which has any of its properties determined at run-time. The <b>Contract</b> object uses a Contract's ABI to determine what methods are available, so the following sections describe the generic ways to interact with the properties added at run-time during the <b>Contract</b> constructor.</p>
<aname="/v5/api/contract/contract/-%23-Contract--readonly"></a><aname="/v5/api/contract/contract/-%23-Contract--Contract--metaclass--Contract--readonly"></a><aname="/v5/api/contract/contract/"></a><h3class="show-anchors"><div>Read-Only Methods (constant)<divclass="anchors"><aclass="self"href="#/v5/api/contract/contract/-%23-Contract--readonly"></a></div></div></h3><p>A constant method is read-only and evaluates a small amount of EVM code against the current blockchain state and can be computed by asking a single node, which can return a result. It is therefore free and does not require any ether, but <b>cannot make changes</b> to the blockchain state..</p>
<aname="/v5/api/contract/contract/-%23-Contract-functionsCall"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">contract</span><spanclass="symbol">.</span><spanclass="method">METHOD_NAME</span><spanclass="symbol">(</span> ...<spanclass="param">args</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">overrides</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Promise< any ></span><divclass="anchors"><aclass="self"href="#/v5/api/contract/contract/-%23-Contract-functionsCall"></a></div></div><divclass="body"><p>The type of the result depends on the ABI.</p>
<p>For values that have a simple meaning in JavaScript, the types are fairly straight forward; strings and booleans are returned as JavaScript strings and booleans.</p>
<p>For numbers, if the <b>type</b> is in the JavaScript safe range (i.e. less than 53 bits, such as an <codeclass="inline">int24</code> or <codeclass="inline">uint48</code>) a normal JavaScript number is used. Otherwise a <ahref="#/v5/api/utils/bignumber/">BigNumber</a> is returned.</p>
<p>For bytes (both fixed length and dynamic), a <ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a> is returned.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">contract</span><spanclass="symbol">.</span><spanclass="path">functions</span><spanclass="symbol">.</span><spanclass="method">METHOD_NAME</span><spanclass="symbol">(</span> ...<spanclass="param">args</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/abi/interface/-%23-Result">Result</a>></span><divclass="anchors"></div></div><divclass="body"><p>The result will always be a <ahref="#/v5/api/utils/abi/interface/-%23-Result">Result</a>, even if there is only a single return value type.</p>
<p>This simplifies frameworks which wish to use the <ahref="#/v5/api/contract/contract/">Contract</a> object, since they do not need to inspect the return types to unwrap simplified functions.</p>
<p>Another use for this method is for error recovery. For example, if a function result is an invalid UTF-8 string, the normal call using the above meta-class function will throw an exception. This allows using the Result access error to access the low-level bytes and reason for the error allowing an alternate UTF-8 error strategy to be used.</p>
</div></div><aname="/v5/api/contract/contract/-%23-Contract--write"></a><aname="/v5/api/contract/contract/-%23-Contract--Contract--metaclass--Contract--write"></a><aname="/v5/api/contract/contract/"></a><h3class="show-anchors"><div>Write Methods (non-constant)<divclass="anchors"><aclass="self"href="#/v5/api/contract/contract/-%23-Contract--write"></a></div></div></h3><p>A non-constant method requires a transaction to be signed and requires payment in the form of a fee to be paid to a miner. This transaction will be verified by every node on the entire network as well by the miner who will compute the new state of the blockchain after executing it against the current state.</p>
<p>It cannot return a result. If a result is required, it should be logged using a Solidity event (or EVM log), which can then be queried from the transaction receipt.</p>
<aname="/v5/api/contract/contract/-%23-contract-functionsSend"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">contract</span><spanclass="symbol">.</span><spanclass="method">METHOD_NAME</span><spanclass="symbol">(</span> ...<spanclass="param">args</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/-%23-providers-TransactionResponse">TransactionResponse</a>></span><divclass="anchors"><aclass="self"href="#/v5/api/contract/contract/-%23-contract-functionsSend"></a></div></div><divclass="body"><p>Returns a <ahref="#/v5/api/providers/types/-%23-providers-TransactionResponse">TransactionResponse</a> for the transaction after it is sent to the network. This requires the <b>Contract</b> has a signer.</p>
</div></div><aname="/v5/api/contract/contract/-%23-Contract--check"></a><aname="/v5/api/contract/contract/-%23-Contract--Contract--metaclass--Contract--check"></a><aname="/v5/api/contract/contract/"></a><h3class="show-anchors"><div>Write Methods Analysis<divclass="anchors"><aclass="self"href="#/v5/api/contract/contract/-%23-Contract--check"></a></div></div></h3><p>There are several options to analyze properties and results of a write method without actually executing it.</p>
<aname="/v5/api/contract/contract/-%23-contract-estimateGas"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">contract</span><spanclass="symbol">.</span><spanclass="path">estimateGas</span><spanclass="symbol">.</span><spanclass="method">METHOD_NAME</span><spanclass="symbol">(</span> ...<spanclass="param">args</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"><aclass="self"href="#/v5/api/contract/contract/-%23-contract-estimateGas"></a></div></div><divclass="body"><p>Returns the estimate units of gas that would be required to execute the <i>METHOD_NAME</i> with <i>args</i> and <i>overrides</i>.</p>
</div></div><aname="/v5/api/contract/contract/-%23-contract-populateTransaction"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">contract</span><spanclass="symbol">.</span><spanclass="path">populateTransaction</span><spanclass="symbol">.</span><spanclass="method">METHOD_NAME</span><spanclass="symbol">(</span> ...<spanclass="param">args</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/-%23-UnsignedTransaction">UnsignedTx</a>></span><divclass="anchors"><aclass="self"href="#/v5/api/contract/contract/-%23-contract-populateTransaction"></a></div></div><divclass="body"><p>Returns an <ahref="#/v5/api/utils/transactions/-%23-UnsignedTransaction">UnsignedTransaction</a> which represents the transaction that would need to be signed and submitted to the network to execute <i>METHOD_NAME</i> with <i>args</i> and <i>overrides</i>.</p>
</div></div><aname="/v5/api/contract/contract/-%23-contract-callStatic"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">contract</span><spanclass="symbol">.</span><spanclass="path">callStatic</span><spanclass="symbol">.</span><spanclass="method">METHOD_NAME</span><spanclass="symbol">(</span> ...<spanclass="param">args</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">overrides</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Promise< any ></span><divclass="anchors"><aclass="self"href="#/v5/api/contract/contract/-%23-contract-callStatic"></a></div></div><divclass="body"><p>Rather than executing the state-change of a transaction, it is possible to ask a node to <i>pretend</i> that a call is not state-changing and return the result.</p>
</div></div><aname="/v5/api/contract/contract/-%23-Contract--filters"></a><aname="/v5/api/contract/contract/-%23-Contract--Contract--metaclass--Contract--filters"></a><aname="/v5/api/contract/contract/"></a><h3class="show-anchors"><div>Event Filters<divclass="anchors"><aclass="self"href="#/v5/api/contract/contract/-%23-Contract--filters"></a></div></div></h3><p>An event filter is made up of topics, which are values logged in a <ahref="https://en.wikipedia.org/wiki/Bloom_filter">Bloom Filter</a>, allowing efficient searching for entries which match a filter.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">contract</span><spanclass="symbol">.</span><spanclass="path">filters</span><spanclass="symbol">.</span><spanclass="method">EVENT_NAME</span><spanclass="symbol">(</span> ...<spanclass="param">args</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Filter</span><divclass="anchors"></div></div><divclass="body"><p>Return a filter for <i>EVENT_NAME</i>, optionally filtering by additional constraints.</p>
<p>Only <codeclass="inline">indexed</code> event parameters may be filtered. If a parameter is null (or not provided) then any value in that field matches.</p>
</div></div><divclass="page-separator"></div><aname="/v5/api/contract/contract-factory/-%23-ContractFactory"></a><aname="/v5/api/contract/contract-factory/-%23-ContractFactory"></a><aname="/v5/api/contract/contract-factory/"></a><h1class="show-anchors"><div>ContractFactory<divclass="anchors"><aclass="self"href="#/v5/api/contract/contract-factory/-%23-ContractFactory"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/contracts/src.ts/index.ts#L1060">source</a></div></div></h1><p>@TODO: Fill this in, including @SRC links</p>
<aname="/v5/api/contract/contract-factory/-%23-ContractFactory-attach"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">contractFactory</span><spanclass="symbol">.</span><spanclass="method">attach</span><spanclass="symbol">(</span><spanclass="param">address</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/contract/contract/">Contract</a></span><divclass="anchors"><aclass="self"href="#/v5/api/contract/contract-factory/-%23-ContractFactory-attach"></a></div></div><divclass="body"><p>Return an instance of a <ahref="#/v5/api/contract/contract/">Contract</a> attched to <i>address</i>. This is the same as using the <ahref="#/v5/api/contract/contract/-%23-Contract--creating">Contract constructor</a> with <i>address</i> and this the the <i>interface</i> and <i>signerOrProvider</i> passed in when creating the ContractFactory.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">contractFactory</span><spanclass="symbol">.</span><spanclass="method">getDeployTransaction</span><spanclass="symbol">(</span> ...<spanclass="param">args</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/transactions/-%23-UnsignedTransaction">UnsignedTransaction</a></span><divclass="anchors"></div></div><divclass="body"><p>Returns the unsigned transaction which would deploy this Contract with <i>args</i> passed to the Contract's constructor.</p>
</div></div><aname="/v5/api/contract/contract-factory/-%23-ContractFactory-deploy"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">contractFactory</span><spanclass="symbol">.</span><spanclass="method">deploy</span><spanclass="symbol">(</span> ...<spanclass="param">args</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Promise<<ahref="#/v5/api/contract/contract/">Contract</a>></span><divclass="anchors"><aclass="self"href="#/v5/api/contract/contract-factory/-%23-ContractFactory-deploy"></a></div></div><divclass="body"><p>Uses the signer to deploy the Contract with <i>args</i> passed into the constructor and retruns a Contract which is attached to the address where this contract <b>will</b> be deployed once the transaction is mined.</p>
<p>The transaction can be found at <codeclass="inline">contract.deployTransaction</code>, and no interactions should be made until the transaction is mined.</p>
<aname="/v5/api/contract/example/-%23-example-erc-20-contract--connecting-to-a-contract"></a><aname="/v5/api/contract/example/"></a><h2class="show-anchors"><div>Connecting to a Contract<divclass="anchors"><aclass="self"href="#/v5/api/contract/example/-%23-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="/v5/api/contract/example/-%23-example-erc-20-contract--properties"></a><aname="/v5/api/contract/example/"></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/-%23-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/-%23-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/-%23-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/-%23-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/-%23-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/-%23-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="/v5/api/contract/example/-%23-example-erc-20-contract--methods"></a><aname="/v5/api/contract/example/"></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/-%23-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="/v5/api/contract/example/-%23-erc20-events"></a><aname="/v5/api/contract/example/-%23-example-erc-20-contract--erc20-events"></a><aname="/v5/api/contract/example/"></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/-%23-erc20-events"></a></div></div></h2>
<aname="/v5/api/contract/example/-%23-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/-%23-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="/v5/api/contract/example/-%23-example-erc-20-contract--meta-class-methods"></a><aname="/v5/api/contract/example/"></a><h2class="show-anchors"><div>Meta-Class Methods<spanclass="inherits">(added at Runtime)</span><divclass="anchors"><aclass="self"href="#/v5/api/contract/example/-%23-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/-%23-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/-%23-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/-%23-UnsignedTransaction">UnsignedTx</a>></span><divclass="anchors"></div></div><divclass="body"><p>Returns an <ahref="#/v5/api/utils/transactions/-%23-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="/v5/api/contract/example/-%23-example-erc-20-contract--meta-class-filters"></a><aname="/v5/api/contract/example/"></a><h2class="show-anchors"><div>Meta-Class Filters<spanclass="inherits">(added at Runtime)</span><divclass="anchors"><aclass="self"href="#/v5/api/contract/example/-%23-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/-%23-erc20-queryfilter">query</a> or to <ahref="#/v5/api/contract/example/-%23-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>
</div></div><divclass="page-separator"></div><aname="/v5/api/signer/-%23-signers"></a><aname="/v5/api/signer/-%23-signers"></a><aname="/v5/api/signer/"></a><h1class="show-anchors"><div>Signers<divclass="anchors"><aclass="self"href="#/v5/api/signer/-%23-signers"></a></div></div></h1><p>A <b>Signer</b> in <i>ethers</i> is an abstraction of an Ethereum Account, which can be used to sign messages and transactions and send signed transactions to the Ethereum Network to execute state changing operations.</p>
<p>The available operations depends largely on the sub-class used.</p>
<p>For example, a Signer from MetaMask can send transactions and sign messages but cannot sign a transaction (without broadcasting it).</p>
<p>The most common Signers you will encounter are:</p>
<p><ul><li><ahref="#/v5/api/signer/-%23-Wallet">Wallet</a>, which is a class which knows its private key and can execute any operations with it </li><li><ahref="#/v5/api/providers/jsonrpc-provider/-%23-JsonRpcSigner">JsonRpcSigner</a>, which is connected to a <ahref="#/v5/api/providers/jsonrpc-provider/">JsonRpcProvider</a> (or sub-class) and is acquired using <ahref="#/v5/api/providers/jsonrpc-provider/-%23-JsonRpcProvider-getSigner">getSigner</a></li></ul></p>
<aname="/v5/api/signer/-%23-Signer"></a><aname="/v5/api/signer/-%23-signers--Signer"></a><aname="/v5/api/signer/"></a><h2class="show-anchors"><div>Signer<divclass="anchors"><aclass="self"href="#/v5/api/signer/-%23-Signer"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/abstract-signer/src.ts/index.ts#L30">source</a></div></div></h2><p>The <b>Signer</b> class is abstract and cannot be directly instaniated.</p>
<p>Instead use one of the concreate sub-classes, such as the <ahref="#/v5/api/signer/-%23-Wallet">Wallet</a>, <ahref="#/v5/api/signer/-%23-VoidSigner">VoidSigner</a> or <ahref="#/v5/api/providers/jsonrpc-provider/-%23-JsonRpcSigner">JsonRpcSigner</a>.</p>
<aname="/v5/api/signer/-%23-Signer-connect"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">signer</span><spanclass="symbol">.</span><spanclass="method">connect</span><spanclass="symbol">(</span><spanclass="param">provider</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/signer/-%23-Signer">Signer</a></span><divclass="anchors"><aclass="self"href="#/v5/api/signer/-%23-Signer-connect"></a></div></div><divclass="body"><p>Sub-classes <b>must</b> implement this, however they may simply throw an error if changing providers is not supported.</p>
</div></div><aname="/v5/api/signer/-%23-Signer-getaddress"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">signer</span><spanclass="symbol">.</span><spanclass="method">getAddress</span><spanclass="symbol">(</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Promise< string<<ahref="#/v5/api/utils/address/-%23-address">Address</a>>></span><divclass="anchors"><aclass="self"href="#/v5/api/signer/-%23-Signer-getaddress"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/abstract-signer/src.ts/index.ts#L53">source</a></div></div><divclass="body"><p>Returns a Promise that resolves to the account address.</p>
</div></div><aname="/v5/api/signer/-%23-Signer-isSigner"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">Signer</span><spanclass="symbol">.</span><spanclass="method">isSigner</span><spanclass="symbol">(</span><spanclass="param">object</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">boolean</span><divclass="anchors"><aclass="self"href="#/v5/api/signer/-%23-Signer-isSigner"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/abstract-signer/src.ts/index.ts#L206">source</a></div></div><divclass="body"><p>Returns true if an only if <i>object</i> is a <b>Signer</b>.</p>
<aname="/v5/api/signer/-%23-Signer-getBalance"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">signer</span><spanclass="symbol">.</span><spanclass="method">getBalance</span><spanclass="symbol">(</span><spanclass="symbol">[</span><spanclass="param">blockTag</span> = "<spanclass="param">latest</span>" <spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Promise<<ahref="#/v5/api/utils/bignumber/">BigNumber</a>></span><divclass="anchors"><aclass="self"href="#/v5/api/signer/-%23-Signer-getBalance"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/abstract-signer/src.ts/index.ts#L69">source</a></div></div><divclass="body"><p>Returns the balance of this wallet at <i>blockTag</i>.</p>
</div></div><aname="/v5/api/signer/-%23-Signer-getChainId"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">signer</span><spanclass="symbol">.</span><spanclass="method">getChainId</span><spanclass="symbol">(</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Promise< number ></span><divclass="anchors"><aclass="self"href="#/v5/api/signer/-%23-Signer-getChainId"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/abstract-signer/src.ts/index.ts#L103">source</a></div></div><divclass="body"><p>Returns the chain ID this wallet is connected to.</p>
</div></div><aname="/v5/api/signer/-%23-Signer-getGasPrice"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">signer</span><spanclass="symbol">.</span><spanclass="method">getGasPrice</span><spanclass="symbol">(</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Promise<<ahref="#/v5/api/utils/bignumber/">BigNumber</a>></span><divclass="anchors"><aclass="self"href="#/v5/api/signer/-%23-Signer-getGasPrice"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/abstract-signer/src.ts/index.ts#L109">source</a></div></div><divclass="body"><p>Returns the current gas price.</p>
</div></div><aname="/v5/api/signer/-%23-Signer-getTransactionCount"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">signer</span><spanclass="symbol">.</span><spanclass="method">getTransactionCount</span><spanclass="symbol">(</span><spanclass="symbol">[</span><spanclass="param">blockTag</span> = "<spanclass="param">latest</span>" <spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Promise< number ></span><divclass="anchors"><aclass="self"href="#/v5/api/signer/-%23-Signer-getTransactionCount"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/abstract-signer/src.ts/index.ts#L74">source</a></div></div><divclass="body"><p>Returns the number of transactions this account has ever sent. This is the value required to be included in transactions as the <codeclass="inline">nonce</code>.</p>
</div></div><aname="/v5/api/signer/-%23-Signer-call"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">signer</span><spanclass="symbol">.</span><spanclass="method">call</span><spanclass="symbol">(</span><spanclass="param">transactionRequest</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Promise< string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>>></span><divclass="anchors"><aclass="self"href="#/v5/api/signer/-%23-Signer-call"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/abstract-signer/src.ts/index.ts#L87">source</a></div></div><divclass="body"><p>Returns the result of calling using the <i>transactionRequest</i>, with this account address being used as the <codeclass="inline">from</code> field.</p>
</div></div><aname="/v5/api/signer/-%23-Signer-estimateGas"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">signer</span><spanclass="symbol">.</span><spanclass="method">estimateGas</span><spanclass="symbol">(</span><spanclass="param">transactionRequest</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Promise<<ahref="#/v5/api/utils/bignumber/">BigNumber</a>></span><divclass="anchors"><aclass="self"href="#/v5/api/signer/-%23-Signer-estimateGas"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/abstract-signer/src.ts/index.ts#L80">source</a></div></div><divclass="body"><p>Returns the result of estimating the cost to send the <i>transactionRequest</i>, with this account address being used as the <codeclass="inline">from</code> field.</p>
</div></div><aname="/v5/api/signer/-%23-Signer-resolveName"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">signer</span><spanclass="symbol">.</span><spanclass="method">resolveName</span><spanclass="symbol">(</span><spanclass="param">ensName</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Promise< string<<ahref="#/v5/api/utils/address/-%23-address">Address</a>>></span><divclass="anchors"><aclass="self"href="#/v5/api/signer/-%23-Signer-resolveName"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/abstract-signer/src.ts/index.ts#L114">source</a></div></div><divclass="body"><p>Returns the address associated with the <i>ensName</i>.</p>
<aname="/v5/api/signer/-%23-Signer-signMessage"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">signer</span><spanclass="symbol">.</span><spanclass="method">signMessage</span><spanclass="symbol">(</span><spanclass="param">message</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Promise< string<<ahref="#/v5/api/utils/bytes/-%23-signature-raw">RawSignature</a>>></span><divclass="anchors"><aclass="self"href="#/v5/api/signer/-%23-Signer-signMessage"></a></div></div><divclass="body"><p>This returns a Promise which resolves to the <ahref="#/v5/api/utils/bytes/-%23-signature-raw">Raw Signature</a> of <i>message</i>.</p>
<p>Sub-classes <b>must</b> implement this, however they may throw if signing a message is not supported, such as in a Contract-based Wallet or Meta-Transaction-based Wallet.</p>
</div></div><divclass="definition container-box note"><divclass="term">Note</div><divclass="body"><p>If <i>message</i> is a string, it is <b>treated as a string</b> and converted to its representation in UTF8 bytes.</p>
<p><b>If and only if</b> a message is a <ahref="#/v5/api/utils/bytes/-%23-Bytes">Bytes</a> will it be treated as binary data.</p>
<p>For example, the string <codeclass="inline">"0x1234"</code> is 6 characters long (and in this case 6 bytes long). This is <b>not</b> equivalent to the array <codeclass="inline">[ 0x12, 0x34 ]</code>, which is 2 bytes long.</p>
<p>A common case is to sign a hash. In this case, if the hash is a string, it <b>must</b> be converted to an array first, using the <ahref="#/v5/api/utils/bytes/-%23-utils-arrayify">arrayify</a> utility function.</p>
</div></div>
<aname="/v5/api/signer/-%23-Signer-signTransaction"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">signer</span><spanclass="symbol">.</span><spanclass="method">signTransaction</span><spanclass="symbol">(</span><spanclass="param">transactionRequest</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Promise< string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>>></span><divclass="anchors"><aclass="self"href="#/v5/api/signer/-%23-Signer-signTransaction"></a></div></div><divclass="body"><p>Returns a Promise which resolves to the signed transaction of the <i>transactionRequest</i>. This method does not populate any missing fields.</p>
<p>Sub-classes <b>must</b> implement this, however they may throw if signing a transaction is not supported, which is common for security reasons in many clients.</p>
</div></div><aname="/v5/api/signer/-%23-Signer-sendTransaction"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">signer</span><spanclass="symbol">.</span><spanclass="method">sendTransaction</span><spanclass="symbol">(</span><spanclass="param">transactionRequest</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Promise<<ahref="#/v5/api/providers/types/-%23-providers-TransactionResponse">TransactionResponse</a>></span><divclass="anchors"><aclass="self"href="#/v5/api/signer/-%23-Signer-sendTransaction"></a></div></div><divclass="body"><p>This method populates the transactionRequest with missing fields, using <ahref="#/v5/api/signer/-%23-Signer-populateTransaction">populateTransaction</a> and returns a Promise which resolves to the transaction.</p>
<p>Sub-classes <b>must</b> implement this, however they may throw if sending a transaction is not supported, such as the <ahref="#/v5/api/signer/-%23-VoidSigner">VoidSigner</a> or if the Wallet is offline and not connected to a <ahref="#/v5/api/providers/provider/">Provider</a>.</p>
</div></div><aname="/v5/api/signer/-%23-Signer--subclassing"></a><aname="/v5/api/signer/-%23-signers--Signer--Signer--subclassing"></a><aname="/v5/api/signer/"></a><h3class="show-anchors"><div>Sub-Classes<divclass="anchors"><aclass="self"href="#/v5/api/signer/-%23-Signer--subclassing"></a></div></div></h3><p>It is very important that all important properties of a <b>Signer</b> are <b>immutable</b>. Since Ethereum is very asynchronous and deals with critical data (such as ether and other potentially valuable crypto assets), keeping properties such as the <i>provider</i> and <i>address</i> static throughout the life-cycle of the Signer helps prevent serious issues and many other classes and libraries make this assumption.</p>
<aname="/v5/api/signer/-%23-Signer-checkTransaction"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">signer</span><spanclass="symbol">.</span><spanclass="method">checkTransaction</span><spanclass="symbol">(</span><spanclass="param">transactionRequest</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/providers/types/-%23-providers-TransactionRequest">TransactionRequest</a></span><divclass="anchors"><aclass="self"href="#/v5/api/signer/-%23-Signer-checkTransaction"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/abstract-signer/src.ts/index.ts#L131">source</a></div></div><divclass="body"><p>This is generally not required to be overridden, but may needed to provide custom behaviour in sub-classes.</p>
<p>This should return a <b>copy</b> of the <i>transactionRequest</i>, with any properties needed by <codeclass="inline">call</code>, <codeclass="inline">estimateGas</code> and <codeclass="inline">populateTransaction</code> (which is used by sendTransaction). It should also throw an error if any unknown key is specified.</p>
<p>The default implementation checks only valid <ahref="#/v5/api/providers/types/-%23-providers-TransactionRequest">TransactionRequest</a> properties exist and adds <codeclass="inline">from</code> to the transaction if it does not exist.</p>
<p>If there is a <codeclass="inline">from</code> field it <b>must</b> be verified to be equal to the Signer's address.</p>
</div></div><aname="/v5/api/signer/-%23-Signer-populateTransaction"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">signer</span><spanclass="symbol">.</span><spanclass="method">populateTransaction</span><spanclass="symbol">(</span><spanclass="param">transactionRequest</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Promise<<ahref="#/v5/api/providers/types/-%23-providers-TransactionRequest">TransactionRequest</a>></span><divclass="anchors"><aclass="self"href="#/v5/api/signer/-%23-Signer-populateTransaction"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/abstract-signer/src.ts/index.ts#L162">source</a></div></div><divclass="body"><p>This is generally not required to be overridden, but may needed to provide custom behaviour in sub-classes.</p>
<p>This should return a <b>copy</b> of <i>transactionRequest</i>, follow the same procedure as <codeclass="inline">checkTransaction</code> and fill in any properties required for sending a transaction. The result should have all promises resolved; if needed the <ahref="#/v5/api/utils/properties/-%23-utils-resolveproperties">resolveProperties</a> utility function can be used for this.</p>
<p>The default implementation calls <codeclass="inline">checkTransaction</code> and resolves to if it is an ENS name, adds <codeclass="inline">gasPrice</code>, <codeclass="inline">nonce</code>, <codeclass="inline">gasLimit</code> and <codeclass="inline">chainId</code> based on the related operations on Signer.</p>
</div></div><aname="/v5/api/signer/-%23-Wallet"></a><aname="/v5/api/signer/-%23-signers--Wallet"></a><aname="/v5/api/signer/"></a><h2class="show-anchors"><div>Wallet<spanclass="inherits"> inherits <ahref="#/v5/api/signer/-%23-ExternallyOwnedAccount">ExternallyOwnedAccount</a> and <ahref="#/v5/api/signer/-%23-Signer">Signer</a></span><divclass="anchors"><aclass="self"href="#/v5/api/signer/-%23-Wallet"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/wallet/src.ts/index.ts#L30">source</a></div></div></h2><p>The Wallet class inherits <ahref="#/v5/api/signer/-%23-Signer">Signer</a> and can sign transactions and messages using a private key as a standard Externally Owned Account (EOA).</p>
<aname="/v5/api/signer/-%23-Wallet-constructor"></a><divclass="property show-anchors"><divclass="signature"><spanclass="modifier">new </span><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="method">Wallet</span><spanclass="symbol">(</span><spanclass="param">privateKey</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">provider</span><spanclass="symbol">]</span><spanclass="symbol">)</span><divclass="anchors"><aclass="self"href="#/v5/api/signer/-%23-Wallet-constructor"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/wallet/src.ts/index.ts#L40">source</a></div></div><divclass="body"><p>Create a new Wallet instance for <i>privateKey</i> and optionally connected to the <i>provider</i>.</p>
</div></div><aname="/v5/api/signer/-%23-Wallet-createRandom"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">Wallet</span><spanclass="symbol">.</span><spanclass="method">createRandom</span><spanclass="symbol">(</span><spanclass="symbol">[</span><spanclass="param">options</span> = {} <spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/signer/-%23-Wallet">Wallet</a></span><divclass="anchors"><aclass="self"href="#/v5/api/signer/-%23-Wallet-createRandom"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/wallet/src.ts/index.ts#L143">source</a></div></div><divclass="body"><p>Returns a new Wallet with a random private key, generated from cryptographically secure entropy sources. If the current environment does not have a secure entropy source, an error is thrown.</p>
</div></div><aname="/v5/api/signer/-%23-Wallet-fromEncryptedJson"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">Wallet</span><spanclass="symbol">.</span><spanclass="method">fromEncryptedJson</span><spanclass="symbol">(</span><spanclass="param">json</span><spanclass="symbol">,</span><spanclass="param">password</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">progress</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Promise<<ahref="#/v5/api/signer/-%23-Wallet">Wallet</a>></span><divclass="anchors"><aclass="self"href="#/v5/api/signer/-%23-Wallet-fromEncryptedJson"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/wallet/src.ts/index.ts#L156">source</a></div></div><divclass="body"><p>Create an instance from an encrypted JSON wallet.</p>
</div></div><aname="/v5/api/signer/-%23-Wallet-fromEncryptedJsonSync"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">Wallet</span><spanclass="symbol">.</span><spanclass="method">fromEncryptedJsonSync</span><spanclass="symbol">(</span><spanclass="param">json</span><spanclass="symbol">,</span><spanclass="param">password</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/signer/-%23-Wallet">Wallet</a></span><divclass="anchors"><aclass="self"href="#/v5/api/signer/-%23-Wallet-fromEncryptedJsonSync"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/wallet/src.ts/index.ts#L162">source</a></div></div><divclass="body"><p>Create an instance from an encrypted JSON wallet.</p>
<p>This operation will operate synchronously which will lock up the user interface, possibly for a non-trivial duration. Most applications should use the asynchronous <codeclass="inline">fromEncryptedJson</code> instead.</p>
</div></div><aname="/v5/api/signer/-%23-Wallet.fromMnemonic"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">Wallet</span><spanclass="symbol">.</span><spanclass="method">fromMnemonic</span><spanclass="symbol">(</span><spanclass="param">mnemonic</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">path</span><spanclass="symbol">,</span><spanclass="symbol">[</span><spanclass="param">wordlist</span><spanclass="symbol">]</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/signer/-%23-Wallet">Wallet</a></span><divclass="anchors"><aclass="self"href="#/v5/api/signer/-%23-Wallet.fromMnemonic"></a></div></div><divclass="body"><p>Create an instance from a mnemonic phrase.</p>
<p>If path is not specified, the Ethereum default path is used (i.e. <codeclass="inline">m/44'/60'/0'/0/0</code>).</p>
<p>If wordlist is not specified, the English Wordlist is used.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">wallet</span><spanclass="symbol">.</span><spanclass="method">address</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/address/-%23-address">Address</a>></span><divclass="anchors"></div></div><divclass="body"><p>The address for the account this Wallet represents.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">wallet</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>The provider this wallet is connected to, which will ge used for any <ahref="#/v5/api/signer/-%23-Signer--blockchain-methods">Blockchain Methods</a> methods. This can be null.</p>
</div></div><divclass="definition container-box note"><divclass="term">Note</div><divclass="body"><p>A <b>Wallet</b> instance is immutable, so if you wish to change the Provider, you may use the <ahref="#/v5/api/signer/-%23-Signer-connect">connect</a> method to create a new instance connected to the desired provider.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">wallet</span><spanclass="symbol">.</span><spanclass="method">publicKey</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 65 >></span><divclass="anchors"></div></div><divclass="body"><p>The uncompressed public key for this Wallet represents.</p>
<aname="/v5/api/signer/-%23-Wallet-encrypt"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">wallet</span><spanclass="symbol">.</span><spanclass="method">encrypt</span><spanclass="symbol">(</span><spanclass="param">password</span><spanclass="symbol">,</span><spanclass="symbol">[</span><spanclass="param">options</span> = {} <spanclass="symbol">,</span><spanclass="symbol">[</span><spanclass="param">progress</span><spanclass="symbol">]</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Promise< string ></span><divclass="anchors"><aclass="self"href="#/v5/api/signer/-%23-Wallet-encrypt"></a></div></div><divclass="body"><p>Encrypt the wallet using <i>password</i> returning a Promise which resolves to a JSON wallet.</p>
</div></div><divclass="code-title"><div>Wallet Examples</div></div><divclass="code"><spanclass="comment">// Create a wallet instance from a mnemonic...
</span>mnemonic = "announce room limb pattern dry unit scale effort smooth jazz weasel alcohol"
</div><aname="/v5/api/signer/-%23-VoidSigner"></a><aname="/v5/api/signer/-%23-signers--VoidSigner"></a><aname="/v5/api/signer/"></a><h2class="show-anchors"><div>VoidSigner<spanclass="inherits"> inherits <ahref="#/v5/api/signer/-%23-Signer">Signer</a></span><divclass="anchors"><aclass="self"href="#/v5/api/signer/-%23-VoidSigner"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/abstract-signer/src.ts/index.ts#L211">source</a></div></div></h2><p>A <b>VoidSigner</b> is a simple Signer which cannot sign.</p>
<p>It is useful as a read-only signer, when an API requires a Signer as a parameter, but it is known only read-only operations will be carried.</p>
<p>For example, the <codeclass="inline">call</code> operation will automatically have the provided address passed along during the execution.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="modifier">new </span><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="method">VoidSigner</span><spanclass="symbol">(</span><spanclass="param">address</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">provider</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/signer/-%23-VoidSigner">VoidSigner</a></span><divclass="anchors"></div></div><divclass="body"><p>Create a new instance of a <b>VoidSigner</b> for <i>address</i>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">voidSigner</span><spanclass="symbol">.</span><spanclass="method">address</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/address/-%23-address">Address</a>></span><divclass="anchors"></div></div><divclass="body"><p>The address of this <b>VoidSigner</b>.</p>
</span></div><aname="/v5/api/signer/-%23-ExternallyOwnedAccount"></a><aname="/v5/api/signer/-%23-signers--ExternallyOwnedAccount"></a><aname="/v5/api/signer/"></a><h2class="show-anchors"><div>ExternallyOwnedAccount<divclass="anchors"><aclass="self"href="#/v5/api/signer/-%23-ExternallyOwnedAccount"></a></div></div></h2><p>This is an interface which contains a minimal set of properties required for Externally Owned Accounts which can have certain operations performed, such as encoding as a JSON wallet.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">eoa</span><spanclass="symbol">.</span><spanclass="method">address</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/address/-%23-address">Address</a>></span><divclass="anchors"></div></div><divclass="body"><p>The <ahref="#/v5/api/utils/address/-%23-address">Address</a> of this EOA.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">eoa</span><spanclass="symbol">.</span><spanclass="method">privateKey</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 >></span><divclass="anchors"></div></div><divclass="body"><p>The privateKey of this EOA</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">eoa</span><spanclass="symbol">.</span><spanclass="method">mnemonic</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/hdnode/-%23-Mnemonic">Mnemonic</a></span><divclass="anchors"></div></div><divclass="body"><p><i>Optional</i>. The account HD mnemonic, if it has one and can be determined. Some sources do not encode the mnemonic, such as an HD extended keys.</p>
</div></div><divclass="page-separator"></div><aname="/v5/api/providers/-%23-providers"></a><aname="/v5/api/providers/-%23-providers"></a><aname="/v5/api/providers/"></a><h1class="show-anchors"><div>Providers<divclass="anchors"><aclass="self"href="#/v5/api/providers/-%23-providers"></a></div></div></h1><p>A <b>Provider</b> is an abstraction of a connection to the Ethereum network, providing a concise, consistent interface to standard Ethereum node functionality.</p>
<p>The ethers.js library provides several options which should cover the vast majority of use-cases, but also includes the necessary functions and classes for sub-classing if a more custom configuration is necessary.</p>
<p>Most users should be able to simply use the <ahref="#/v5/api/providers/-%23-providers-getDefaultProvider">Default Provider</a>.</p>
<aname="/v5/api/providers/-%23-providers-getDefaultProvider"></a><aname="/v5/api/providers/-%23-providers--providers-getDefaultProvider"></a><aname="/v5/api/providers/"></a><h2class="show-anchors"><div>Default Provider<divclass="anchors"><aclass="self"href="#/v5/api/providers/-%23-providers-getDefaultProvider"></a></div></div></h2><p>The default provider is the safest, easiest way to begin developing on <i>Ethereum</i>, and it is also robust enough for use in production.</p>
<p>It creates a <ahref="#/v5/api/providers/other/-%23-FallbackProvider">FallbackProvider</a> connected to as many backend services as possible. When a request is made, it is sent to multiple backends simulatenously. As responses from each backend are returned, they are checked that they agree. Once a quorum has been reached (i.e. enough of the backends agree), the response is provided to your application.</p>
<p>This ensures that if a backend has become out-of-sync, or if it has been compromised that its responses are dropped in favor of responses that match the majority.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="method">getDefaultProvider</span><spanclass="symbol">(</span><spanclass="symbol">[</span><spanclass="param">network</span><spanclass="symbol">,</span><spanclass="symbol">[</span><spanclass="param">options</span><spanclass="symbol">]</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/providers/provider/">Provider</a></span><divclass="anchors"></div></div><divclass="body"><p>Returns a new Provider, backed by multiple services, connected to <i>network</i>. Is no <i>network</i> is provided, <b>homestead</b> (i.e. mainnet) is used.</p>
<p>The <i>options</i> is an object, with the following properties:</p>
</div></div><tableclass="table minimal"><tr><tdalign="center"><b>Property</b></td><tdalign="center"><b>Description</b></td><tdclass="fix"> </td></tr><tr><tdalign="center"><i>alchemy</i></td><tdalign="left"><ahref="https://alchemyapi.io">Alchemy</a> API Token</td><tdclass="fix"> </td></tr><tr><tdalign="center"><i>etherscan</i></td><tdalign="left"><ahref="https://etherscan.io">Etherscan</a> API Token</td><tdclass="fix"> </td></tr><tr><tdalign="center"><i>infura</i></td><tdalign="left"><ahref="https://infura.io">INFURA</a> Project ID or ProjectID and Project Secret</td><tdclass="fix"> </td></tr><tr><tdalign="center"><i>quorum</i></td><tdalign="left">The number of backends that must agree <i>(default: 2 for mainnet, 1 for testnets)</i></td><tdclass="fix"> </td></tr><tr><tdclass="table-title"colspan="2">Option Properties</td><tdclass="fix"> </td></tr></table><divclass="definition container-box note"><divclass="term">Note: API Keys</div><divclass="body"><p>It is highly recommended for production services that to acquire and specify an API Key for each sercice.</p>
<p>The default API Keys used by ethers are shared across all users, so services may throttle all services that are using the default API Keys during periods of load without realizing it.</p>
<p>Many services also have monitoring and usage metrics, which are only available if an API Key is specified. This allows tracking how many requests are being sent and which methods are being used the most.</p>
<aname="/v5/api/providers/provider/-%23-Provider-getBalance"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">provider</span><spanclass="symbol">.</span><spanclass="method">getBalance</span><spanclass="symbol">(</span><spanclass="param">address</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">blockTag</span> = <spanclass="param">latest</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Promise<<ahref="#/v5/api/utils/bignumber/">BigNumber</a>></span><divclass="anchors"><aclass="self"href="#/v5/api/providers/provider/-%23-Provider-getBalance"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/base-provider.ts#L700">source</a></div></div><divclass="body"><p>Returns the balance of <i>address</i> as of the <i>blockTag</i> block height.</p>
</div></div><aname="/v5/api/providers/provider/-%23-Provider-getCode"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">provider</span><spanclass="symbol">.</span><spanclass="method">getCode</span><spanclass="symbol">(</span><spanclass="param">address</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">blockTag</span> = <spanclass="param">latest</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Promise< string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>>></span><divclass="anchors"><aclass="self"href="#/v5/api/providers/provider/-%23-Provider-getCode"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/base-provider.ts#L718">source</a></div></div><divclass="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 <codeclass="inline">0x</code>.</p>
</div></div><aname="/v5/api/providers/provider/-%23-Provider-getStorageAt"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">provider</span><spanclass="symbol">.</span><spanclass="method">getStorageAt</span><spanclass="symbol">(</span><spanclass="param">addr</span><spanclass="symbol">,</span><spanclass="param">pos</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">blockTag</span> = <spanclass="param">latest</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Promise< string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>>></span><divclass="anchors"><aclass="self"href="#/v5/api/providers/provider/-%23-Provider-getStorageAt"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/base-provider.ts#L727">source</a></div></div><divclass="body"><p>Returns the <codeclass="inline">Bytes32</code> value of the position <i>pos</i> at address <i>addr</i>, as of the <i>blockTag</i>.</p>
</div></div><aname="/v5/api/providers/provider/-%23-Provider-getTransactionCount"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">provider</span><spanclass="symbol">.</span><spanclass="method">getTransactionCount</span><spanclass="symbol">(</span><spanclass="param">address</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">blockTag</span> = <spanclass="param">latest</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Promise< number ></span><divclass="anchors"><aclass="self"href="#/v5/api/providers/provider/-%23-Provider-getTransactionCount"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/base-provider.ts#L709">source</a></div></div><divclass="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>
<aname="/v5/api/providers/provider/-%23-Provider-getBlock"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">provider</span><spanclass="symbol">.</span><spanclass="method">getBlock</span><spanclass="symbol">(</span><spanclass="param">block</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Promise<<ahref="#/v5/api/providers/types/-%23-providers-Block">Block</a>></span><divclass="anchors"><aclass="self"href="#/v5/api/providers/provider/-%23-Provider-getBlock"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/base-provider.ts#L936">source</a></div></div><divclass="body"><p>Get the <i>block</i> from the network, where the <codeclass="inline">result.transactions</code> is a list of transaction hashes.</p>
</div></div><aname="/v5/api/providers/provider/-%23-Provider-getBlockWithTransactions"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">provider</span><spanclass="symbol">.</span><spanclass="method">getBlockWithTransactions</span><spanclass="symbol">(</span><spanclass="param">block</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Promise<<ahref="#/v5/api/providers/types/-%23-providers-BlockWithTransactions">BlockWithTransactions</a>></span><divclass="anchors"><aclass="self"href="#/v5/api/providers/provider/-%23-Provider-getBlockWithTransactions"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/base-provider.ts#L940">source</a></div></div><divclass="body"><p>Get the <i>block</i> from the network, where the <codeclass="inline">result.transactions</code> is an Array of <ahref="#/v5/api/providers/types/-%23-providers-TransactionResponse">TransactionResponse</a> objects.</p>
</span></div><aname="/v5/api/providers/provider/-%23-Provider--ens-methods"></a><aname="/v5/api/providers/provider/-%23-Provider--Provider--ens-methods"></a><aname="/v5/api/providers/provider/"></a><h2class="show-anchors"><div>Ethereum Naming Service (ENS) Methods<divclass="anchors"><aclass="self"href="#/v5/api/providers/provider/-%23-Provider--ens-methods"></a></div></div></h2><p>The <ahref="https://ens.domains/">Ethereum Naming Service</a> (ENS) allows a short and easy-to-remember ENS Name to be attached 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 <ahref="#/v5/api/utils/address/-%23-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>
<aname="/v5/api/providers/provider/-%23-Provider-lookupAddress"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">provider</span><spanclass="symbol">.</span><spanclass="method">lookupAddress</span><spanclass="symbol">(</span><spanclass="param">address</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Promise< string ></span><divclass="anchors"><aclass="self"href="#/v5/api/providers/provider/-%23-Provider-lookupAddress"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/base-provider.ts#L1099">source</a></div></div><divclass="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, <codeclass="inline">null</code> is returned.</p>
</div></div><aname="/v5/api/providers/provider/-%23-Provider-ResolveName"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">provider</span><spanclass="symbol">.</span><spanclass="method">resolveName</span><spanclass="symbol">(</span><spanclass="param">name</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Promise< string<<ahref="#/v5/api/utils/address/-%23-address">Address</a>>></span><divclass="anchors"><aclass="self"href="#/v5/api/providers/provider/-%23-Provider-ResolveName"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/base-provider.ts#L1071">source</a></div></div><divclass="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, <codeclass="inline">null</code> is returned.</p>
<aname="/v5/api/providers/provider/-%23-Provider-getLogs"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">provider</span><spanclass="symbol">.</span><spanclass="method">getLogs</span><spanclass="symbol">(</span><spanclass="param">filter</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Promise< Array<<ahref="#/v5/api/providers/types/-%23-providers-Log">Log</a>>></span><divclass="anchors"><aclass="self"href="#/v5/api/providers/provider/-%23-Provider-getLogs"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/base-provider.ts#L1016">source</a></div></div><divclass="body"><p>Returns the Array of <ahref="#/v5/api/providers/types/-%23-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><aname="/v5/api/providers/provider/-%23-Provider--network-methods"></a><aname="/v5/api/providers/provider/-%23-Provider--Provider--network-methods"></a><aname="/v5/api/providers/provider/"></a><h2class="show-anchors"><div>Network Status Methods<divclass="anchors"><aclass="self"href="#/v5/api/providers/provider/-%23-Provider--network-methods"></a></div></div></h2>
<aname="/v5/api/providers/provider/-%23-Provider-getNetwork"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">provider</span><spanclass="symbol">.</span><spanclass="method">getNetwork</span><spanclass="symbol">(</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Promise<<ahref="#/v5/api/providers/types/-%23-providers-Network">Network</a>></span><divclass="anchors"><aclass="self"href="#/v5/api/providers/provider/-%23-Provider-getNetwork"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/base-provider.ts#L520">source</a></div></div><divclass="body"><p>Returns the <ahref="#/v5/api/providers/types/-%23-providers-Network">Network</a> this Provider is connected to.</p>
</div></div><aname="/v5/api/providers/provider/-%23-Provider-getBlockNumber"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">provider</span><spanclass="symbol">.</span><spanclass="method">getBlockNumber</span><spanclass="symbol">(</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Promise< number ></span><divclass="anchors"><aclass="self"href="#/v5/api/providers/provider/-%23-Provider-getBlockNumber"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/base-provider.ts#L691">source</a></div></div><divclass="body"><p>Returns the block number (or height) of the most recently mined block.</p>
</div></div><aname="/v5/api/providers/provider/-%23-Provider-getGasPrice"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">provider</span><spanclass="symbol">.</span><spanclass="method">getGasPrice</span><spanclass="symbol">(</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Promise<<ahref="#/v5/api/utils/bignumber/">BigNumber</a>></span><divclass="anchors"><aclass="self"href="#/v5/api/providers/provider/-%23-Provider-getGasPrice"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/base-provider.ts#L695">source</a></div></div><divclass="body"><p>Returns a <i>best guess</i> of the <ahref="#/v5/concepts/gas/-%23-gas-price">Gas Price</a> to use in a transaction.</p>
<aname="/v5/api/providers/provider/-%23-Provider-call"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">provider</span><spanclass="symbol">.</span><spanclass="method">call</span><spanclass="symbol">(</span><spanclass="param">transaction</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">blockTag</span> = <spanclass="param">latest</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Promise< string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>>></span><divclass="anchors"><aclass="self"href="#/v5/api/providers/provider/-%23-Provider-call"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/base-provider.ts#L836">source</a></div></div><divclass="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><aname="/v5/api/providers/provider/-%23-Provider-estimateGas"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">provider</span><spanclass="symbol">.</span><spanclass="method">estimateGas</span><spanclass="symbol">(</span><spanclass="param">transaction</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Promise<<ahref="#/v5/api/utils/bignumber/">BigNumber</a>></span><divclass="anchors"><aclass="self"href="#/v5/api/providers/provider/-%23-Provider-estimateGas"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/base-provider.ts#L845">source</a></div></div><divclass="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><aname="/v5/api/providers/provider/-%23-Provider-sendTransaction"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">provider</span><spanclass="symbol">.</span><spanclass="method">sendTransaction</span><spanclass="symbol">(</span><spanclass="param">transaction</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Promise<<ahref="#/v5/api/providers/types/-%23-providers-TransactionResponse">TransactionResponse</a>></span><divclass="anchors"><aclass="self"href="#/v5/api/providers/provider/-%23-Provider-sendTransaction"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/base-provider.ts#L777">source</a></div></div><divclass="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><aname="/v5/api/providers/provider/-%23-Provider-waitForTransaction"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">provider</span><spanclass="symbol">.</span><spanclass="method">waitForTransaction</span><spanclass="symbol">(</span><spanclass="param">hash</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">confirms</span> = <spanclass="param">1</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">timeout</span><spanclass="symbol">]</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Promise<<ahref="#/v5/api/providers/types/-%23-providers-TransactionReceipt">TxReceipt</a>></span><divclass="anchors"><aclass="self"href="#/v5/api/providers/provider/-%23-Provider-waitForTransaction"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/base-provider.ts#L652">source</a></div></div><divclass="body"><p>Returns a Promise which will not resolve until <i>transactionHash</i> is mined.</p>
<aname="/v5/api/providers/provider/-%23-Provider-on"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">provider</span><spanclass="symbol">.</span><spanclass="method">on</span><spanclass="symbol">(</span><spanclass="param">eventName</span><spanclass="symbol">,</span><spanclass="param">listener</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">this</span><divclass="anchors"><aclass="self"href="#/v5/api/providers/provider/-%23-Provider-on"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/base-provider.ts#L1157">source</a></div></div><divclass="body"><p>Add a <i>listener</i> to be triggered for each <i>eventName</i>.</p>
</div></div><aname="/v5/api/providers/provider/-%23-Provider-once"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">provider</span><spanclass="symbol">.</span><spanclass="method">once</span><spanclass="symbol">(</span><spanclass="param">eventName</span><spanclass="symbol">,</span><spanclass="param">listener</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">this</span><divclass="anchors"><aclass="self"href="#/v5/api/providers/provider/-%23-Provider-once"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/base-provider.ts#L1161">source</a></div></div><divclass="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><aname="/v5/api/providers/provider/-%23-Provider-emit"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">provider</span><spanclass="symbol">.</span><spanclass="method">emit</span><spanclass="symbol">(</span><spanclass="param">eventName</span><spanclass="symbol">,</span> ...<spanclass="param">args</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">boolean</span><divclass="anchors"><aclass="self"href="#/v5/api/providers/provider/-%23-Provider-emit"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/base-provider.ts#L1166">source</a></div></div><divclass="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><aname="/v5/api/providers/provider/-%23-Provider-off"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">provider</span><spanclass="symbol">.</span><spanclass="method">off</span><spanclass="symbol">(</span><spanclass="param">eventName</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">listener</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">this</span><divclass="anchors"><aclass="self"href="#/v5/api/providers/provider/-%23-Provider-off"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/base-provider.ts#L1214">source</a></div></div><divclass="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><aname="/v5/api/providers/provider/-%23-Provider-removeAllListeners"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">provider</span><spanclass="symbol">.</span><spanclass="method">removeAllListeners</span><spanclass="symbol">(</span><spanclass="symbol">[</span><spanclass="param">eventName</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">this</span><divclass="anchors"><aclass="self"href="#/v5/api/providers/provider/-%23-Provider-removeAllListeners"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/base-provider.ts#L1237">source</a></div></div><divclass="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><aname="/v5/api/providers/provider/-%23-Provider-listenerCount"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">provider</span><spanclass="symbol">.</span><spanclass="method">listenerCount</span><spanclass="symbol">(</span><spanclass="symbol">[</span><spanclass="param">eventName</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">number</span><divclass="anchors"><aclass="self"href="#/v5/api/providers/provider/-%23-Provider-listenerCount"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/base-provider.ts#L1194">source</a></div></div><divclass="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><aname="/v5/api/providers/provider/-%23-Provider-listeners"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">provider</span><spanclass="symbol">.</span><spanclass="method">listeners</span><spanclass="symbol">(</span><spanclass="param">eventName</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Array< Listener ></span><divclass="anchors"><aclass="self"href="#/v5/api/providers/provider/-%23-Provider-listeners"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/base-provider.ts#L1203">source</a></div></div><divclass="body"><p>Returns the list of Listeners for <i>eventName</i>.</p>
</div></div><aname="/v5/api/providers/provider/-%23-Provider--events"></a><aname="/v5/api/providers/provider/-%23-Provider--Provider--event-methods--Provider--events"></a><aname="/v5/api/providers/provider/"></a><h3class="show-anchors"><div>Events<divclass="anchors"><aclass="self"href="#/v5/api/providers/provider/-%23-Provider--events"></a></div></div></h3><p>Any of the following may be used as the <i>eventName</i> in the above methods.</p>
<divclass="definition"><divclass="term"><b>Log Filter</b></div><divclass="body"><p>A filter is an object, representing a contract log Filter, which has the optional properties <codeclass="inline">address</code> (the source contract) and <codeclass="inline">topics</code> (a topic-set to match).</p>
<p>If <codeclass="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><divclass="definition"><divclass="term"><b>Topic-Set Filter</b></div><divclass="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><divclass="definition"><divclass="term"><b>Transaction Filter</b></div><divclass="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 <ahref="#/v5/api/providers/provider/-%23-Provider-once">once</a> method is used than the <ahref="#/v5/api/providers/provider/-%23-Provider-on">on</a> method.</p>
</div></div><p>In addition to transaction and filter events, there are several named events.</p>
<tableclass="table full"><tr><tdalign="center"width="16%"><b>Event Name</b></td><tdalign="center"colspan="2"width="28%"><b>Arguments</b></td><tdalign="center"colspan="4"width="56%"><b>Description</b></td><tdclass="fix"> </td></tr><tr><tdalign="center"width="16%"><codeclass="inline">"block"</code></td><tdalign="center"colspan="2"width="28%"><i>blockNumber</i></td><tdalign="left"colspan="4"width="56%">emitted when a new block is mined</td><tdclass="fix"> </td></tr><tr><tdalign="center"width="16%"><codeclass="inline">"error"</code></td><tdalign="center"colspan="2"width="28%"><i>error</i></td><tdalign="left"colspan="4"width="56%">emitted on any error</td><tdclass="fix"> </td></tr><tr><tdalign="center"width="16%"><codeclass="inline">"pending"</code></td><tdalign="center"colspan="2"width="28%"><i>pendingTransaction</i></td><tdalign="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><tdclass="fix"> </td></tr><tr><tdalign="center"width="16%"><codeclass="inline">"willPoll"</code></td><tdalign="center"colspan="2"width="28%"><i>pollId</i></td><tdalign="left"colspan="4"width="56%">emitted prior to a polling loop is about to begin; <i>(very rarely used by most developers)</i></td><tdclass="fix"> </td></tr><tr><tdalign="center"width="16%"><codeclass="inline">"poll"</code></td><tdalign="center"colspan="2"width="28%"><i>pollId</i>, <i>blockNumber</i></td><tdalign="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><tdclass="fix"> </td></tr><tr><tdalign="center"width="16%"><codeclass="inline">"didPoll"</code></td><tdalign="center"colspan="2"width="28%"><i>pollId</i></td><tdalign="left"colspan="4"width="56%">emitted after all events from a polling loop are emitted; <i>(very rarely used by most developers)</i></td><tdclass="fix"> </td></tr><tr><tdalign="center"width="16%"><codeclass="inline">"debug"</code></td><tdalign="center"colspan="2"width="28%">provider dependent</td><tdalign="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><tdclass="fix"> </td></tr><tr><tdclass="table-title"colspan="7">Named Provider Events</td><tdclass="fix"> </td></tr></table><divclass="code-title"><div>Events Example</div></div><divclass="code">provider.on("block", (blockNumber) => {
<spanclass="comment"> // Emitted on every block change
<aname="/v5/api/providers/provider/-%23-Provider-isProvider"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">Provider</span><spanclass="symbol">.</span><spanclass="method">isProvider</span><spanclass="symbol">(</span><spanclass="param">object</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">boolean</span><divclass="anchors"><aclass="self"href="#/v5/api/providers/provider/-%23-Provider-isProvider"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/abstract-provider/src.ts/index.ts#L269">source</a></div></div><divclass="body"><p>Returns true if and only if <i>object</i> is a Provider.</p>
</div></div><divclass="page-separator"></div><aname="/v5/api/providers/jsonrpc-provider/-%23-JsonRpcProvider"></a><aname="/v5/api/providers/jsonrpc-provider/-%23-JsonRpcProvider"></a><aname="/v5/api/providers/jsonrpc-provider/"></a><h1class="show-anchors"><div>JsonRpcProvider<spanclass="inherits"> inherits <ahref="#/v5/api/providers/provider/">Provider</a></span><divclass="anchors"><aclass="self"href="#/v5/api/providers/jsonrpc-provider/-%23-JsonRpcProvider"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/json-rpc-provider.ts#L220">source</a></div></div></h1><p>The <ahref="https://github.com/ethereum/wiki/wiki/JSON-RPC">JSON-RPC API</a> is a very popular method for interacting with Ethereum and is available in all major Ethereum node implementations (e.g. <ahref="https://geth.ethereum.org">Geth</a> and <ahref="https://www.parity.io">Parity</a>) as well as many third-party web services (e.g. <ahref="https://infura.io">INFURA</a>)</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="modifier">new </span><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">providers</span><spanclass="symbol">.</span><spanclass="method">JsonRpcProvider</span><spanclass="symbol">(</span><spanclass="symbol">[</span><spanclass="param">url</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">aNetworkish</span><spanclass="symbol">]</span><spanclass="symbol">]</span><spanclass="symbol">)</span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/json-rpc-provider.ts#L226">source</a></div></div><divclass="body"><p>Connect to a JSON-RPC API located at <i>url</i> using the <i>aNetworkish</i> network. If <i>url</i> is not specified, the default (i.e. <codeclass="inline">http://localhost:8545</code>) is used and if no network is specified, it will be determined automatically by querying the node.</p>
</div></div><divclass="definition container-box note"><divclass="term">Note: Connecting to a Local Node</div><divclass="body"><p>Each node implementation is slightly different and may require specific command-line flags, configuration or settings in their UI to enable JSON-RPC, unlock accounts or expose specific APIs. Please consult their documentation.</p>
</div></div><aname="/v5/api/providers/jsonrpc-provider/-%23-JsonRpcProvider-getSigner"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">jsonRpcProvider</span><spanclass="symbol">.</span><spanclass="method">getSigner</span><spanclass="symbol">(</span><spanclass="symbol">[</span><spanclass="param">addressOrIndex</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/providers/jsonrpc-provider/-%23-JsonRpcSigner">JsonRpcSigner</a></span><divclass="anchors"><aclass="self"href="#/v5/api/providers/jsonrpc-provider/-%23-JsonRpcProvider-getSigner"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/json-rpc-provider.ts#L294">source</a></div></div><divclass="body"><p>Returns a <ahref="#/v5/api/providers/jsonrpc-provider/-%23-JsonRpcSigner">JsonRpcSigner</a> which is managed by this Ethereum node, at <i>addressOrIndex</i>. If no <i>addressOrIndex</i> is provided, the first account (account #0) is used.</p>
</div></div><aname="/v5/api/providers/jsonrpc-provider/-%23-JsonRpcProvider-listAccounts"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">jsonRpcProvider</span><spanclass="symbol">.</span><spanclass="method">listAccounts</span><spanclass="symbol">(</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Array< string ></span><divclass="anchors"><aclass="self"href="#/v5/api/providers/jsonrpc-provider/-%23-JsonRpcProvider-listAccounts"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/json-rpc-provider.ts#L302">source</a></div></div><divclass="body"><p>Returns a list of all account addresses managed by this provider.</p>
</div></div><aname="/v5/api/providers/jsonrpc-provider/-%23-JsonRpcProvider-send"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">jsonRpcProvider</span><spanclass="symbol">.</span><spanclass="method">send</span><spanclass="symbol">(</span><spanclass="param">method</span><spanclass="symbol">,</span><spanclass="param">params</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Promise< any ></span><divclass="anchors"><aclass="self"href="#/v5/api/providers/jsonrpc-provider/-%23-JsonRpcProvider-send"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/json-rpc-provider.ts#L308">source</a></div></div><divclass="body"><p>Allows sending raw messages to the provider.</p>
</div></div><aname="/v5/api/providers/jsonrpc-provider/-%23-JsonRpcSigner"></a><aname="/v5/api/providers/jsonrpc-provider/-%23-JsonRpcProvider--JsonRpcSigner"></a><aname="/v5/api/providers/jsonrpc-provider/"></a><h2class="show-anchors"><div>JsonRpcSigner<spanclass="inherits"> inherits <ahref="#/v5/api/signer/-%23-Signer">Signer</a></span><divclass="anchors"><aclass="self"href="#/v5/api/providers/jsonrpc-provider/-%23-JsonRpcSigner"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/json-rpc-provider.ts#L46">source</a></div></div></h2><p>A <b>JsonRpcSigner</b> is a simple Signer which is backed by a connected <ahref="#/v5/api/providers/jsonrpc-provider/">JsonRpcProvider</a>.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">signer</span><spanclass="symbol">.</span><spanclass="method">provider</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/providers/jsonrpc-provider/">JsonRpcProvider</a></span><divclass="anchors"></div></div><divclass="body"><p>The provider this signer was established from.</p>
</div></div><aname="/v5/api/providers/jsonrpc-provider/-%23-JsonRpcSigner-connectUnchecked"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">signer</span><spanclass="symbol">.</span><spanclass="method">connectUnchecked</span><spanclass="symbol">(</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/providers/jsonrpc-provider/-%23-UncheckedJsonRpcSigner">JsonRpcUncheckedSigner</a></span><divclass="anchors"><aclass="self"href="#/v5/api/providers/jsonrpc-provider/-%23-JsonRpcSigner-connectUnchecked"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/json-rpc-provider.ts#L83">source</a></div></div><divclass="body"><p>Returns a new Signer object which does not perform additional checks when sending a transaction. See <ahref="#/v5/api/providers/jsonrpc-provider/-%23-JsonRpcProvider-getUncheckedSigner">getUncheckedSigner</a> for more details.</p>
</div></div><aname="/v5/api/providers/jsonrpc-provider/-%23-JsonRpcSigner-sendUncheckedTransaction"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">signer</span><spanclass="symbol">.</span><spanclass="method">sendUncheckedTransaction</span><spanclass="symbol">(</span><spanclass="param">transaction</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Promise< string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 >>></span><divclass="anchors"><aclass="self"href="#/v5/api/providers/jsonrpc-provider/-%23-JsonRpcSigner-sendUncheckedTransaction"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/json-rpc-provider.ts#L102">source</a></div></div><divclass="body"><p>Sends the <i>transaction</i> and returns a Promise which resolves to the opaque transaction hash.</p>
</div></div><aname="/v5/api/providers/jsonrpc-provider/-%23-JsonRpcSigner-unlock"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">signer</span><spanclass="symbol">.</span><spanclass="method">unlock</span><spanclass="symbol">(</span><spanclass="param">password</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Promise< boolean ></span><divclass="anchors"><aclass="self"href="#/v5/api/providers/jsonrpc-provider/-%23-JsonRpcSigner-unlock"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/json-rpc-provider.ts#L188">source</a></div></div><divclass="body"><p>Request the node unlock the account (if locked) using <i>password</i>.</p>
</div></div><aname="/v5/api/providers/jsonrpc-provider/-%23-UncheckedJsonRpcSigner"></a><aname="/v5/api/providers/jsonrpc-provider/-%23-JsonRpcProvider--UncheckedJsonRpcSigner"></a><aname="/v5/api/providers/jsonrpc-provider/"></a><h2class="show-anchors"><div>JsonRpcUncheckedSigner<spanclass="inherits"> inherits <ahref="#/v5/api/signer/-%23-Signer">Signer</a></span><divclass="anchors"><aclass="self"href="#/v5/api/providers/jsonrpc-provider/-%23-UncheckedJsonRpcSigner"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/json-rpc-provider.ts#L197">source</a></div></div></h2><p>The JSON-RPC API only provides a transaction hash as the response when a transaction is sent, but the ethers Provider requires populating all details of a transaction before returning it. For example, the gas price and gas limit may be adjusted by the node or the nonce automatically included, in which case the opaque transaction hash has discarded this.</p>
<p>To remedy this, the <ahref="#/v5/api/providers/jsonrpc-provider/-%23-JsonRpcSigner">JsonRpcSigner</a> immediately queries the provider for the details using the returned transaction hash to populate the <ahref="#/v5/api/providers/types/-%23-providers-TransactionResponse">TransactionResponse</a> object.</p>
<p>Some backends do not respond immediately and instead defer releasing the details of a transaction it was responsible for signing until it is mined.</p>
<p>The <b>UncheckedSigner</b> does not populate any additional information and will immediately return the result as a mock <ahref="#/v5/api/providers/types/-%23-providers-TransactionResponse">TransactionResponse</a>-like object, with most of the properties set to null, but allows access to the transaction hash quickly, if that is all that is required.</p>
<aname="/v5/api/providers/jsonrpc-provider/-%23-JsonRpcProvider--other"></a><aname="/v5/api/providers/jsonrpc-provider/-%23-JsonRpcProvider--JsonRpcProvider--other"></a><aname="/v5/api/providers/jsonrpc-provider/"></a><h2class="show-anchors"><div>Node-Specific Methods<divclass="anchors"><aclass="self"href="#/v5/api/providers/jsonrpc-provider/-%23-JsonRpcProvider--other"></a></div></div></h2><p>Many methods are less common or specific to certain Ethereum Node implementations (e.g. <ahref="https://www.parity.io">Parity</a> vs <ahref="https://geth.ethereum.org">Geth</a>. These include account and admin management, debugging, deeper block and transaction exploration and other services (such as Swarm and Whisper).</p>
<p>The <ahref="#/v5/api/providers/jsonrpc-provider/-%23-JsonRpcProvider-send">jsonRpcProvider.send</a> method can be used to access these.</p>
<p><ul><li><ahref="https://github.com/ethereum/wiki/wiki/JSON-RPC">All JSON-RPC methods</a> (including the less common methods) which most Ethereum Nodes support. </li><li><ahref="https://openethereum.github.io/wiki/JSONRPC-trace-module">Parity's Trace Module</a> can be used to trace and debug EVM execution of a transaction (requires custom configuration) </li><li><ahref="https://github.com/ethereum/go-ethereum/wiki/Management-APIs#debug">Geth's Debug Module</a> can be used to debug transactions and internal cache state, etc. </li><li><ahref="https://github.com/ethereum/go-ethereum/wiki/Management-APIs">Additional Geth Methods</a></li><li><ahref="https://openethereum.github.io/wiki/JSONRPC">Additional Parity Methods</a></li></ul></p>
<divclass="page-separator"></div><aname="/v5/api/providers/api-providers/-%23-api-providers"></a><aname="/v5/api/providers/api-providers/-%23-api-providers"></a><aname="/v5/api/providers/api-providers/"></a><h1class="show-anchors"><div>API Providers<divclass="anchors"><aclass="self"href="#/v5/api/providers/api-providers/-%23-api-providers"></a></div></div></h1><p>There are many services which offer a web API for accessing the Ethereum Blockchain. These Providers allow connecting to them, which simplifies development, since you do not need to run your own instance or cluster of Ethereum nodes.</p>
<p>However, this reliance on third-party services can reduce resiliance, security and increase the amount of required trust. To mitigate these issues, it is recommended you use a <ahref="#/v5/api/providers/-%23-providers-getDefaultProvider">Default Provider</a>.</p>
<aname="/v5/api/providers/api-providers/-%23-EtherscanProvider"></a><aname="/v5/api/providers/api-providers/-%23-api-providers--EtherscanProvider"></a><aname="/v5/api/providers/api-providers/"></a><h2class="show-anchors"><div>EtherscanProvider<spanclass="inherits"> inherits <ahref="#/v5/api/providers/provider/">Provider</a></span><divclass="anchors"><aclass="self"href="#/v5/api/providers/api-providers/-%23-EtherscanProvider"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/etherscan-provider.ts#L76">source</a></div></div></h2><p>The <b>EtherscanProvider</b> is backed by a combination of the various <ahref="https://etherscan.io/apis">Etherscan APIs</a>.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="modifier">new </span><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">providers</span><spanclass="symbol">.</span><spanclass="method">EtherscanProvider</span><spanclass="symbol">(</span><spanclass="symbol">[</span><spanclass="param">network</span> = "<spanclass="param">homestead</span>" <spanclass="symbol">,</span><spanclass="symbol">[</span><spanclass="param">apiKey</span><spanclass="symbol">]</span><spanclass="symbol">]</span><spanclass="symbol">)</span><divclass="anchors"></div></div><divclass="body"><p>Create a new <b>EtherscanProvider</b> connected to <i>network</i> with the optional <i>apiKey</i>.</p>
<p>The <i>network</i> may be specified as <b>string</b> for a common network name, a <b>number</b> for a common chain ID or a [Network Object]provider-(network).</p>
<p>If no <i>apiKey</i> is provided, a shared API key will be used, which may result in reduced performance and throttled requests. It is highly recommended for production, you register with <ahref="https://etherscan.io">Etherscan</a> for your own API key.</p>
</div></div><divclass="definition container-box note"><divclass="term">Note: Default API keys</div><divclass="body"><p>If no <i>apiKey</i> is provided, a shared API key will be used, which may result in reduced performance and throttled requests.</p>
<p>It is highly recommended for production, you register with <ahref="https://etherscan.io">Etherscan</a> for your own API key.</p>
</div><divclass="property show-anchors"><divclass="signature"><spanclass="path">provider</span><spanclass="symbol">.</span><spanclass="method">getHistory</span><spanclass="symbol">(</span><spanclass="param">address</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Array< History ></span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/etherscan-provider.ts#L306">source</a></div></div><divclass="body"><p>@TODO... Explain</p>
</div></div><aname="/v5/api/providers/api-providers/-%23-InfuraProvider"></a><aname="/v5/api/providers/api-providers/-%23-api-providers--InfuraProvider"></a><aname="/v5/api/providers/api-providers/"></a><h2class="show-anchors"><div>InfuraProvider<spanclass="inherits"> inherits <ahref="#/v5/api/providers/other/-%23-UrlJsonRpcProvider">UrlJsonRpcProvider</a></span><divclass="anchors"><aclass="self"href="#/v5/api/providers/api-providers/-%23-InfuraProvider"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/infura-provider.ts#L17">source</a></div></div></h2><p>The <b>InfuraProvider</b> is backed by the popular <ahref="https://infura.io">INFURA</a> Ethereum service.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="modifier">new </span><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">providers</span><spanclass="symbol">.</span><spanclass="method">InfuraProvider</span><spanclass="symbol">(</span><spanclass="symbol">[</span><spanclass="param">network</span> = "<spanclass="param">homestead</span>" <spanclass="symbol">,</span><spanclass="symbol">[</span><spanclass="param">apiKey</span><spanclass="symbol">]</span><spanclass="symbol">]</span><spanclass="symbol">)</span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/infura-provider.ts#L17">source</a></div></div><divclass="body"><p>Create a new <b>InfuraProvider</b> connected to <i>network</i> with the optional <i>apiKey</i>.</p>
<p>The <i>network</i> may be specified as <b>string</b> for a common network name, a <b>number</b> for a common chain ID or a [Network Object]provider-(network).</p>
<p>The <i>apiKey</i> can be a <b>string</b> Project ID or an <b>object</b> with the properties <codeclass="inline">projectId</code> and <codeclass="inline">projectSecret</code> to specify a <ahref="https://infura.io/docs/gettingStarted/authentication">Project Secret</a> which can be used on non-public sources (like on a server) to further secure your API access and quotas.</p>
</div></div><aname="/v5/api/providers/api-providers/-%23-InfuraProvider-getWebSocketProvider"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">InfuraProvider</span><spanclass="symbol">.</span><spanclass="method">getWebSocketProvider</span><spanclass="symbol">(</span><spanclass="symbol">[</span><spanclass="param">network</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">apiKey</span><spanclass="symbol">]</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/providers/other/-%23-WebSocketProvider">WebSocketProvider</a></span><divclass="anchors"><aclass="self"href="#/v5/api/providers/api-providers/-%23-InfuraProvider-getWebSocketProvider"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/infura-provider.ts#L21">source</a></div></div><divclass="body"><p>Create a new <ahref="#/v5/api/providers/other/-%23-WebSocketProvider">WebSocketProvider</a> using the INFURA web-socket endpoint to connect to <i>network</i> with the optional <i>apiKey</i>.</p>
<p>The <i>network</i> and <i>apiKey</i> are specified the same as <ahref="#/v5/api/providers/api-providers/-%23-InfuraProvider">the constructor</a>.</p>
</div></div><divclass="definition container-box note"><divclass="term">Note: Default API keys</div><divclass="body"><p>If no <i>apiKey</i> is provided, a shared API key will be used, which may result in reduced performance and throttled requests.</p>
<p>It is highly recommended for production, you register with <ahref="https://infura.io">INFURA</a> for your own API key.</p>
</div><aname="/v5/api/providers/api-providers/-%23-AlchemyProvider"></a><aname="/v5/api/providers/api-providers/-%23-api-providers--AlchemyProvider"></a><aname="/v5/api/providers/api-providers/"></a><h2class="show-anchors"><div>AlchemyProvider<spanclass="inherits"> inherits <ahref="#/v5/api/providers/other/-%23-UrlJsonRpcProvider">UrlJsonRpcProvider</a></span><divclass="anchors"><aclass="self"href="#/v5/api/providers/api-providers/-%23-AlchemyProvider"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/alchemy-provider.ts#L20">source</a></div></div></h2><p>The <b>AlchemyProvider</b> is backed by <ahref="https://alchemyapi.io">Alchemy</a>.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="modifier">new </span><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">providers</span><spanclass="symbol">.</span><spanclass="method">AlchemyProvider</span><spanclass="symbol">(</span><spanclass="symbol">[</span><spanclass="param">network</span> = "<spanclass="param">homestead</span>" <spanclass="symbol">,</span><spanclass="symbol">[</span><spanclass="param">apiKey</span><spanclass="symbol">]</span><spanclass="symbol">]</span><spanclass="symbol">)</span><divclass="anchors"></div></div><divclass="body"><p>Create a new <b>AlchemyProvider</b> connected to <i>network</i> with the optional <i>apiKey</i>.</p>
<p>The <i>network</i> may be specified as <b>string</b> for a common network name, a <b>number</b> for a common chain ID or a <ahref="#/v5/api/providers/types/-%23-providers-Network">Network Object</a>.</p>
</div></div><divclass="definition container-box note"><divclass="term">Note: Default API keys</div><divclass="body"><p>If no <i>apiKey</i> is provided, a shared API key will be used, which may result in reduced performance and throttled requests.</p>
<p>It is highly recommended for production, you register with <ahref="https://alchemyapi.io">Alchemy</a> for your own API key.</p>
</div><aname="/v5/api/providers/api-providers/-%23-CloudflareProvider"></a><aname="/v5/api/providers/api-providers/-%23-api-providers--CloudflareProvider"></a><aname="/v5/api/providers/api-providers/"></a><h2class="show-anchors"><div>CloudflareProvider<spanclass="inherits"> inherits <ahref="#/v5/api/providers/other/-%23-UrlJsonRpcProvider">UrlJsonRpcProvider</a></span><divclass="anchors"><aclass="self"href="#/v5/api/providers/api-providers/-%23-CloudflareProvider"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/cloudflare-provider.ts#L10">source</a></div></div></h2><p>The CloudflareProvider is backed by the <ahref="https://developers.cloudflare.com/distributed-web/ethereum-gateway/">Cloudflare Ethereum Gateway</a>.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="modifier">new </span><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">providers</span><spanclass="symbol">.</span><spanclass="method">CloudflareProvider</span><spanclass="symbol">(</span><spanclass="symbol">)</span><divclass="anchors"></div></div><divclass="body"><p>Create a new <b>CloudflareProvider</b> connected to mainnet (i.e. "homestead").</p>
<aname="/v5/api/providers/other/-%23-FallbackProvider"></a><aname="/v5/api/providers/other/-%23-other-providers--FallbackProvider"></a><aname="/v5/api/providers/other/"></a><h2class="show-anchors"><div>FallbackProvider<spanclass="inherits"> inherits <ahref="#/v5/api/providers/provider/">Provider</a></span><divclass="anchors"><aclass="self"href="#/v5/api/providers/other/-%23-FallbackProvider"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/fallback-provider.ts#L384">source</a></div></div></h2><p>The <b>FallbackProvider</b> is the most advanced <ahref="#/v5/api/providers/provider/">Provider</a> available in ethers.</p>
<p>It uses a quorum and connects to multiple <ahref="#/v5/api/providers/provider/">Providers</a> as backends, each configured with a <i>priority</i> and a <i>weight</i> .</p>
<p>When a request is made, the request is dispatched to multiple backends, randomly choosen (higher prioirty backends are always selected first) and the results from each are compared against the others. Only once the quorum has been reached will that result be accepted and returned to the caller.</p>
<p>By default the quorum requires 50% (rounded up) of the backends to agree. The <i>weight</i> can be used to give a backend Provider more influence.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="modifier">new </span><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">providers</span><spanclass="symbol">.</span><spanclass="method">FallbackProvider</span><spanclass="symbol">(</span><spanclass="param">providers</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">quorum</span><spanclass="symbol">]</span><spanclass="symbol">)</span><divclass="anchors"></div></div><divclass="body"><p>Creates a new instance of a FallbackProvider connected to <i>providers</i>. If quorum is not specified, half of the total sum of the provider weights is used.</p>
<p>The <i>providers</i> can be either an array of <ahref="#/v5/api/providers/provider/">Provider</a> or <ahref="#/v5/api/providers/other/-%23-FallbackProviderConfig">FallbackProviderConfig</a>. If a <ahref="#/v5/api/providers/provider/">Provider</a> is provided, the defaults are a priority of 1 and a weight of 1.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">provider</span><spanclass="symbol">.</span><spanclass="method">providerConfigs</span><spanclass="arrow">⇒</span><spanclass="returns">Array<<ahref="#/v5/api/providers/other/-%23-FallbackProviderConfig">FallbackProviderConfig</a>></span><divclass="anchors"></div></div><divclass="body"><p>The list of Provider Configurations that describe the backends.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">provider</span><spanclass="symbol">.</span><spanclass="method">quorum</span><spanclass="arrow">⇒</span><spanclass="returns">number</span><divclass="anchors"></div></div><divclass="body"><p>The quorum the backend responses must agree upon before a result will be resolved. By default this is <i>half the sum of the weights</i>.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">fallbackProviderConfig</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>The provider for this configuration.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">fallbackProviderConfig</span><spanclass="symbol">.</span><spanclass="method">priority</span><spanclass="arrow">⇒</span><spanclass="returns">number</span><divclass="anchors"></div></div><divclass="body"><p>The priority used for the provider. Higher priorities are favoured over lower priorities. If multiple providers share the same prioirty, they are choosen at random.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">fallbackProviderConfig</span><spanclass="symbol">.</span><spanclass="method">stallTimeout</span><spanclass="arrow">⇒</span><spanclass="returns">number</span><divclass="anchors"></div></div><divclass="body"><p>The timeout (in ms) after which another <ahref="#/v5/api/providers/provider/">Provider</a> will be attempted. This does not affect the current Provider; if it returns a result it is counted as part of the quorum.</p>
<p>Lower values will result in more network traffic, but may reduce the response time of requests.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">fallbackProviderConfig</span><spanclass="symbol">.</span><spanclass="method">weight</span><spanclass="arrow">⇒</span><spanclass="returns">number</span><divclass="anchors"></div></div><divclass="body"><p>The weight a response from this provider provides. This can be used if a given <ahref="#/v5/api/providers/provider/">Provider</a> is more trusted, for example.</p>
</div></div><aname="/v5/api/providers/other/-%23-IpcProvider"></a><aname="/v5/api/providers/other/-%23-other-providers--IpcProvider"></a><aname="/v5/api/providers/other/"></a><h2class="show-anchors"><div>IpcProvider<spanclass="inherits"> inherits <ahref="#/v5/api/providers/jsonrpc-provider/">JsonRpcProvider</a></span><divclass="anchors"><aclass="self"href="#/v5/api/providers/other/-%23-IpcProvider"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/ipc-provider.ts#L15">source</a></div></div></h2><p>The <b>IpcProvider</b> allows the JSON-RPC API to be used over a local filename on the file system, exposed by Geth, Parity and other nodes.</p>
<p>This is only available in <i>node.js</i> (as it requires file system access, and may have additional complications due to file permissions. See any related notes on the documentation for the actual node implementation websites.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">ipcProvider</span><spanclass="symbol">.</span><spanclass="method">path</span><spanclass="arrow">⇒</span><spanclass="returns">string</span><divclass="anchors"></div></div><divclass="body"><p>The path this <ahref="#/v5/api/providers/provider/">Provider</a> is connected to.</p>
</div></div><aname="/v5/api/providers/other/-%23-UrlJsonRpcProvider"></a><aname="/v5/api/providers/other/-%23-other-providers--UrlJsonRpcProvider"></a><aname="/v5/api/providers/other/"></a><h2class="show-anchors"><div>UrlJsonRpcProvider<spanclass="inherits"> inherits <ahref="#/v5/api/providers/jsonrpc-provider/">JsonRpcProvider</a></span><divclass="anchors"><aclass="self"href="#/v5/api/providers/other/-%23-UrlJsonRpcProvider"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/url-json-rpc-provider.ts#L49">source</a></div></div></h2><p>This class is intended to be sub-classed and not used directly. It simplifies creating a <ahref="#/v5/api/providers/provider/">Provider</a> where a normal <ahref="#/v5/api/providers/jsonrpc-provider/">JsonRpcProvider</a> would suffice, with a little extra effort needed to generate the JSON-RPC URL.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="modifier">new </span><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">providers</span><spanclass="symbol">.</span><spanclass="method">UrlJsonRpcProvider</span><spanclass="symbol">(</span><spanclass="symbol">[</span><spanclass="param">network</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">apiKey</span><spanclass="symbol">]</span><spanclass="symbol">]</span><spanclass="symbol">)</span><divclass="anchors"></div></div><divclass="body"><p>Sub-classes do not need to override this. Instead they should override the static method <codeclass="inline">getUrl</code> and optionally <codeclass="inline">getApiKey</code>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">urlJsonRpcProvider</span><spanclass="symbol">.</span><spanclass="method">apiKey</span><spanclass="arrow">⇒</span><spanclass="returns">any</span><divclass="anchors"></div></div><divclass="body"><p>The value of the apiKey that was returned from <codeclass="inline">InheritedClass.getApiKey</code>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">InheritingClass</span><spanclass="symbol">.</span><spanclass="method">getApiKey</span><spanclass="symbol">(</span><spanclass="param">apiKey</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">any</span><divclass="anchors"></div></div><divclass="body"><p>This function should examine the <i>apiKey</i> to ensure it is valid and return a (possible modified) value to use in <codeclass="inline">getUrl</code>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">InheritingClass</span><spanclass="symbol">.</span><spanclass="method">getUrl</span><spanclass="symbol">(</span><spanclass="param">network</span><spanclass="symbol">,</span><spanclass="param">apiKey</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">string</span><divclass="anchors"></div></div><divclass="body"><p>The URL to use for the JsonRpcProvider instance.</p>
</div></div><aname="/v5/api/providers/other/-%23-Web3Provider"></a><aname="/v5/api/providers/other/-%23-other-providers--Web3Provider"></a><aname="/v5/api/providers/other/"></a><h2class="show-anchors"><div>Web3Provider<spanclass="inherits"> inherits <ahref="#/v5/api/providers/jsonrpc-provider/">JsonRpcProvider</a></span><divclass="anchors"><aclass="self"href="#/v5/api/providers/other/-%23-Web3Provider"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/web3-provider.ts#L77">source</a></div></div></h2><p>The Web3Provider is meant to ease moving from a <ahref="https://github.com/ethereum/web3.js">web3.js based</a> application to ethers by wraping an existing Web3-compatible (such as a <ahref="https://github.com/ethereum/web3.js/tree/1.x/packages/web3-providers-http">Web3HttpProvider</a>, <ahref="https://github.com/ethereum/web3.js/tree/1.x/packages/web3-providers-ipc">Web3IpcProvider</a> or <ahref="https://github.com/ethereum/web3.js/tree/1.x/packages/web3-providers-ws">Web3WsProvider</a>) and exposing it as an ethers.js <ahref="#/v5/api/providers/provider/">Provider</a> which can then be used with the rest of the library.</p>
<p>This may also be used to wrap a standard [EIP-1193 Provider](link-eip-1193].</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="modifier">new </span><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">providers</span><spanclass="symbol">.</span><spanclass="method">Web3Provider</span><spanclass="symbol">(</span><spanclass="param">externalProvider</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">network</span><spanclass="symbol">]</span><spanclass="symbol">)</span><divclass="anchors"></div></div><divclass="body"><p>Create a new <b>Web3Provider</b>, which wraps an <ahref="https://eips.ethereum.org/EIPS/eip-1193">EIP-1193 Provider</a> or Web3Provider-compatible Provider.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">web3Provider</span><spanclass="symbol">.</span><spanclass="method">provider</span><spanclass="arrow">⇒</span><spanclass="returns">Web3CompatibleProvider</span><divclass="anchors"></div></div><divclass="body"><p>The provider used to create this instance.</p>
</div></div><aname="/v5/api/providers/other/-%23-Web3Provider--ExternalProvider"></a><aname="/v5/api/providers/other/-%23-other-providers--Web3Provider--Web3Provider--ExternalProvider"></a><aname="/v5/api/providers/other/"></a><h3class="show-anchors"><div>ExternalProvider<divclass="anchors"><aclass="self"href="#/v5/api/providers/other/-%23-Web3Provider--ExternalProvider"></a></div></div></h3><p>An <b>ExternalProvider</b> can be either one for the above mentioned Web3 Providers (or otherwise compatible) or an <ahref="https://eips.ethereum.org/EIPS/eip-1193">EIP-1193</a> provider.</p>
<p>An ExternalProvider must offer one of the following signatures, and the first matching is used:</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">externalProvider</span><spanclass="symbol">.</span><spanclass="method">request</span><spanclass="symbol">(</span><spanclass="param">request</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Promise< any ></span><divclass="anchors"></div></div><divclass="body"><p>This follows the <ahref="https://eips.ethereum.org/EIPS/eip-1193">EIP-1193</a> API signature.</p>
<p>The <i>request</i> should be a standard JSON-RPC payload, which should at a minimum specify the <codeclass="inline">method</code> and <codeclass="inline">params</code>.</p>
<p>The result should be the actual result, which differs from the Web3.js response, which is a wrapped JSON-RPC response.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">externalProvider</span><spanclass="symbol">.</span><spanclass="method">sendAsync</span><spanclass="symbol">(</span><spanclass="param">request</span><spanclass="symbol">,</span><spanclass="param">callback</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">void</span><divclass="anchors"></div></div><divclass="body"><p>This follows the <ahref="https://github.com/ethereum/web3.js/blob/1.x/packages/web3-providers-http/types/index.d.ts#L57">Web3.js Provider Signature</a>.</p>
<p>The <i>request</i> should be a standard JSON-RPC payload, which should at a minimum specify the <codeclass="inline">method</code> and <codeclass="inline">params</code>.</p>
<p>The <i>callback</i> should use the error-first calling semantics, so <codeclass="inline">(error, result)</code> where the result is a JSON-RPC wrapped result.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">externalProvider</span><spanclass="symbol">.</span><spanclass="method">send</span><spanclass="symbol">(</span><spanclass="param">request</span><spanclass="symbol">,</span><spanclass="param">callback</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">void</span><divclass="anchors"></div></div><divclass="body"><p>This is identical to <codeclass="inline">sendAsync</code>. Historically, this used a synchronous web request, but no current browsers support this, so its use this way was deprecated quite a long time ago</p>
</div></div><aname="/v5/api/providers/other/-%23-WebSocketProvider"></a><aname="/v5/api/providers/other/-%23-other-providers--WebSocketProvider"></a><aname="/v5/api/providers/other/"></a><h2class="show-anchors"><div>WebSocketProvider<spanclass="inherits"> inherits <ahref="#/v5/api/providers/jsonrpc-provider/">JsonRpcProvider</a></span><divclass="anchors"><aclass="self"href="#/v5/api/providers/other/-%23-WebSocketProvider"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/websocket-provider.ts#L47">source</a></div></div></h2><p>The <b>WebSocketProvider</b> connects to a JSON-RPC WebSocket-compatible backend which allows for a persistent connection, multiplexing requests and pub-sub events for a more immediate event dispatching.</p>
<p>The WebSocket API is newer, and if running your own infrastructure, note that WebSockets are much more intensive on your server resourses, as they must manage and maintain the state for each client. For this reason, many services may also charge additional fees for using their WebSocket endpoints.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="modifier">new </span><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">provider</span><spanclass="symbol">.</span><spanclass="method">WebSockerProvider</span><spanclass="symbol">(</span><spanclass="symbol">[</span><spanclass="param">url</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">network</span><spanclass="symbol">]</span><spanclass="symbol">]</span><spanclass="symbol">)</span><divclass="anchors"></div></div><divclass="body"><p>Returns a new <ahref="#/v5/api/providers/other/-%23-WebSocketProvider">WebSocketProvider</a> connected to <i>url</i> as the <i>network</i>.</p>
<p>If <i>url</i> is unspecified, the default <codeclass="inline">"ws://localhost:8546"</code> will be used. If <i>network</i> is unspecified, it will be queried from the network.</p>
<aname="/v5/api/providers/types/-%23-providers-BlockTag"></a><aname="/v5/api/providers/types/-%23-types--providers-BlockTag"></a><aname="/v5/api/providers/types/"></a><h2class="show-anchors"><div>BlockTag<divclass="anchors"><aclass="self"href="#/v5/api/providers/types/-%23-providers-BlockTag"></a></div></div></h2><p>A <b>BlockTag</b> specifies a specific location in the Blockchain.</p>
<p><ul><li><b><codeclass="inline">"latest"</code></b> -- The most recently mined block </li><li><b><codeclass="inline">"earliest"</code></b> -- Block #0 </li><li><b><codeclass="inline">"pending"</code></b> -- The block currently being prepared for mining; not all operations and backends support this BlockTag </li><li><b><i>number</i></b> -- The block at this height </li><li><b><i>a negative number</i></b> -- The block this many blocks ago </li></ul></p>
<aname="/v5/api/providers/types/-%23-providers-EventType"></a><aname="/v5/api/providers/types/-%23-types--providers-BlockTag--providers-EventType"></a><aname="/v5/api/providers/types/"></a><h3class="show-anchors"><div>EventType<divclass="anchors"><aclass="self"href="#/v5/api/providers/types/-%23-providers-EventType"></a></div></div></h3><p>And <b>EventType</b> can be any of the following.</p>
<aname="/v5/api/providers/types/-%23-providers-Network"></a><aname="/v5/api/providers/types/-%23-types--providers-Network"></a><aname="/v5/api/providers/types/"></a><h2class="show-anchors"><div>Network<divclass="anchors"><aclass="self"href="#/v5/api/providers/types/-%23-providers-Network"></a></div></div></h2><p>A <b>Network</b> represents an Etherem network.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">network</span><spanclass="symbol">.</span><spanclass="method">name</span><spanclass="arrow">⇒</span><spanclass="returns">string</span><divclass="anchors"></div></div><divclass="body"><p>The human-readable name of the network, such as <codeclass="inline">homestead</code>. If the network name is unknown, this will be <codeclass="inline">"unknown"</code>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">network</span><spanclass="symbol">.</span><spanclass="method">chainId</span><spanclass="arrow">⇒</span><spanclass="returns">number</span><divclass="anchors"></div></div><divclass="body"><p>The Chain ID of the network.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">network</span><spanclass="symbol">.</span><spanclass="method">ensAddress</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/address/-%23-address">Address</a>></span><divclass="anchors"></div></div><divclass="body"><p>The address at which the ENS registry is deployed on this network.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">block</span><spanclass="symbol">.</span><spanclass="method">hash</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 >></span><divclass="anchors"></div></div><divclass="body"><p>The hash of this block.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">block</span><spanclass="symbol">.</span><spanclass="method">parentHash</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 >></span><divclass="anchors"></div></div><divclass="body"><p>The hash of the previous block.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">block</span><spanclass="symbol">.</span><spanclass="method">number</span><spanclass="arrow">⇒</span><spanclass="returns">number</span><divclass="anchors"></div></div><divclass="body"><p>The height (number) of this block.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">block</span><spanclass="symbol">.</span><spanclass="method">timestamp</span><spanclass="arrow">⇒</span><spanclass="returns">number</span><divclass="anchors"></div></div><divclass="body"><p>The timestamp of this block.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">block</span><spanclass="symbol">.</span><spanclass="method">nonce</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>></span><divclass="anchors"></div></div><divclass="body"><p>The nonce used as part of the proof-of-work to mine this block.</p>
<p>This property is generally of little interest developers.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">block</span><spanclass="symbol">.</span><spanclass="method">difficulty</span><spanclass="arrow">⇒</span><spanclass="returns">number</span><divclass="anchors"></div></div><divclass="body"><p>The difficulty target required to be met by the miner of the block.</p>
<p>This property is generally of little interest developers.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">block</span><spanclass="symbol">.</span><spanclass="method">gasLimit</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/bignumber/">BigNumber</a></span><divclass="anchors"></div></div><divclass="body"><p>The maximum amount of gas that this block was permitted to use. This is a value that can be voted up or voted down by miners and is used to automatically adjust the bandwidth requirements of the network.</p>
<p>This property is generally of little interest developers.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">block</span><spanclass="symbol">.</span><spanclass="method">gasUsed</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/bignumber/">BigNumber</a></span><divclass="anchors"></div></div><divclass="body"><p>The total amount of gas used by all transactions in this block.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">block</span><spanclass="symbol">.</span><spanclass="method">miner</span><spanclass="arrow">⇒</span><spanclass="returns">string</span><divclass="anchors"></div></div><divclass="body"><p>The coinbase address of this block, which indicates the address the miner that mined this block would like the subsidy reward to go to.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">block</span><spanclass="symbol">.</span><spanclass="method">extraData</span><spanclass="arrow">⇒</span><spanclass="returns">string</span><divclass="anchors"></div></div><divclass="body"><p>This is extra data a miner may choose to include when mining a block.</p>
<p>This property is generally of little interest developers.</p>
</div></div><aname="/v5/api/providers/types/-%23-types--providers-Block--block-with-transaction-hashes"></a><aname="/v5/api/providers/types/"></a><h3class="show-anchors"><div>Block (with transaction hashes)<divclass="anchors"><aclass="self"href="#/v5/api/providers/types/-%23-types--providers-Block--block-with-transaction-hashes"></a></div></div></h3><p>Often only the hashes of the transactions included in a block are needed, so by default a block only contains this information, as it is substantially less data.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">block</span><spanclass="symbol">.</span><spanclass="method">transactions</span><spanclass="arrow">⇒</span><spanclass="returns">Array< string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 >>></span><divclass="anchors"></div></div><divclass="body"><p>A list of the transactions hashes for each transaction this block includes.</p>
</div></div><aname="/v5/api/providers/types/-%23-providers-BlockWithTransactions"></a><aname="/v5/api/providers/types/-%23-types--providers-Block--providers-BlockWithTransactions"></a><aname="/v5/api/providers/types/"></a><h3class="show-anchors"><div>BlockWithTransactions<spanclass="inherits"> inherits <ahref="#/v5/api/providers/types/-%23-providers-Block">Block</a></span><divclass="anchors"><aclass="self"href="#/v5/api/providers/types/-%23-providers-BlockWithTransactions"></a></div></div></h3><p>If all transactions for a block are needed, this object instead includes the full details on each transaction.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">block</span><spanclass="symbol">.</span><spanclass="method">transactions</span><spanclass="arrow">⇒</span><spanclass="returns">Array<<ahref="#/v5/api/providers/types/-%23-providers-TransactionResponse">TransactionResponse</a>></span><divclass="anchors"></div></div><divclass="body"><p>A list of the transactions this block includes.</p>
</div></div><aname="/v5/api/providers/types/-%23-types--events-and-logs"></a><aname="/v5/api/providers/types/"></a><h2class="show-anchors"><div>Events and Logs<divclass="anchors"><aclass="self"href="#/v5/api/providers/types/-%23-types--events-and-logs"></a></div></div></h2>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">filter</span><spanclass="symbol">.</span><spanclass="method">address</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/address/-%23-address">Address</a>></span><divclass="anchors"></div></div><divclass="body"><p>The address to filter by, or <codeclass="inline">null</code> to match any address.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">filter</span><spanclass="symbol">.</span><spanclass="method">topics</span><spanclass="arrow">⇒</span><spanclass="returns">Array< string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 >> | Array< string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 >>>></span><divclass="anchors"></div></div><divclass="body"><p>The topics to filter by, or <codeclass="inline">null</code> to match any topics. Each entry represents an <b>AND</b> condition that must match, or may be <codeclass="inline">null</code> to match anything. If a given entry is an Array, then that entry is treated as an <b>OR</b> for any value in the entry.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">filter</span><spanclass="symbol">.</span><spanclass="method">fromBlock</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/providers/types/-%23-providers-BlockTag">BlockTag</a></span><divclass="anchors"></div></div><divclass="body"><p>The starting block (inclusive) to search for logs matching the filter criteria.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">filter</span><spanclass="symbol">.</span><spanclass="method">toBlock</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/providers/types/-%23-providers-BlockTag">BlockTag</a></span><divclass="anchors"></div></div><divclass="body"><p>The end block (inclusive) to search for logs matching the filter criteria.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">filter</span><spanclass="symbol">.</span><spanclass="method">blockHash</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 >></span><divclass="anchors"></div></div><divclass="body"><p>The specific block (by its block hash) to search for logs matching the filter criteria.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">log</span><spanclass="symbol">.</span><spanclass="method">blockNumber</span><spanclass="arrow">⇒</span><spanclass="returns">number</span><divclass="anchors"></div></div><divclass="body"><p>The block height (number) of the block including the transaction of this log.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">log</span><spanclass="symbol">.</span><spanclass="method">blockHash</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 >></span><divclass="anchors"></div></div><divclass="body"><p>The block hash of the block including the transaction of this log.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">log</span><spanclass="symbol">.</span><spanclass="method">removed</span><spanclass="arrow">⇒</span><spanclass="returns">boolean</span><divclass="anchors"></div></div><divclass="body"><p>During a re-org, if a transaction is orphaned, this will be set to true to indicate the Log entry has been removed; it will likely be emitted again in the near future when another block is mined with the transaction that triggered this log, but keep in mind the values may change.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">log</span><spanclass="symbol">.</span><spanclass="method">transactionLogIndex</span><spanclass="arrow">⇒</span><spanclass="returns">number</span><divclass="anchors"></div></div><divclass="body"><p>The index of this log in the transaction.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">log</span><spanclass="symbol">.</span><spanclass="method">address</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/address/-%23-address">Address</a>></span><divclass="anchors"></div></div><divclass="body"><p>The address of the contract that generated this log.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">log</span><spanclass="symbol">.</span><spanclass="method">data</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>></span><divclass="anchors"></div></div><divclass="body"><p>The data included in this log.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">log</span><spanclass="symbol">.</span><spanclass="method">topics</span><spanclass="arrow">⇒</span><spanclass="returns">Array< string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 >>></span><divclass="anchors"></div></div><divclass="body"><p>The list of topics (indexed properties) for this log.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">log</span><spanclass="symbol">.</span><spanclass="method">transactionHash</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 >></span><divclass="anchors"></div></div><divclass="body"><p>The transaction hash of the transaction of this log.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">log</span><spanclass="symbol">.</span><spanclass="method">transactionIndex</span><spanclass="arrow">⇒</span><spanclass="returns">number</span><divclass="anchors"></div></div><divclass="body"><p>The index of the transaction in the block of the transaction of this log.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">log</span><spanclass="symbol">.</span><spanclass="method">logIndex</span><spanclass="arrow">⇒</span><spanclass="returns">number</span><divclass="anchors"></div></div><divclass="body"><p>The index of this log across all logs in the entire <b>block</b>.</p>
<aname="/v5/api/providers/types/-%23-providers-TransactionRequest"></a><aname="/v5/api/providers/types/-%23-types--transactions--providers-TransactionRequest"></a><aname="/v5/api/providers/types/"></a><h3class="show-anchors"><div>TransactionRequest<divclass="anchors"><aclass="self"href="#/v5/api/providers/types/-%23-providers-TransactionRequest"></a></div></div></h3><p>A transaction request describes a transaction that is to be sent to the network or otherwise processed.</p>
<p>All fields are optional and may be a promise which resolves to the required type.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">transactionRequest</span><spanclass="symbol">.</span><spanclass="method">to</span><spanclass="arrow">⇒</span><spanclass="returns">string | Promise< string ></span><divclass="anchors"></div></div><divclass="body"><p>The address (or ENS name) this transaction it to.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">transactionRequest</span><spanclass="symbol">.</span><spanclass="method">from</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/address/-%23-address">Address</a>> | Promise< string<<ahref="#/v5/api/utils/address/-%23-address">Address</a>>></span><divclass="anchors"></div></div><divclass="body"><p>The address this transaction is from.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">transactionRequest</span><spanclass="symbol">.</span><spanclass="method">nonce</span><spanclass="arrow">⇒</span><spanclass="returns">number | Promise< number ></span><divclass="anchors"></div></div><divclass="body"><p>The nonce for this transaction. This should be set to the number of transactions ever sent <b>from</b> this address.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">transactionRequest</span><spanclass="symbol">.</span><spanclass="method">gasLimit</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/bignumber/">BigNumber</a> | Promise<<ahref="#/v5/api/utils/bignumber/">BigNumber</a>></span><divclass="anchors"></div></div><divclass="body"><p>The maximum amount of gas this transaction is permitted to use.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">transactionRequest</span><spanclass="symbol">.</span><spanclass="method">gasPrice</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/bignumber/">BigNumber</a> | Promise<<ahref="#/v5/api/utils/bignumber/">BigNumber</a>></span><divclass="anchors"></div></div><divclass="body"><p>The price (in wei) per unit of gas this transaction will pay.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">transactionRequest</span><spanclass="symbol">.</span><spanclass="method">value</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/bignumber/">BigNumber</a> | Promise<<ahref="#/v5/api/utils/bignumber/">BigNumber</a>></span><divclass="anchors"></div></div><divclass="body"><p>The amount (in wei) this transaction is sending.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">transactionRequest</span><spanclass="symbol">.</span><spanclass="method">chainId</span><spanclass="arrow">⇒</span><spanclass="returns">number | Promise< number ></span><divclass="anchors"></div></div><divclass="body"><p>The chain ID this transaction is authorized on, as specified by <ahref="https://eips.ethereum.org/EIPS/eip-155">EIP-155</a>.</p>
<p>If the chain ID is 0 will disable EIP-155 and the transaction will be valid on any network. This can be <b>dangerous</b> and care should be taken, since it allows transactions to be replayed on networks that were possibly not intended.</p>
</div></div><aname="/v5/api/providers/types/-%23-providers-TransactionResponse"></a><aname="/v5/api/providers/types/-%23-types--transactions--providers-TransactionResponse"></a><aname="/v5/api/providers/types/"></a><h3class="show-anchors"><div>TransactionResponse<spanclass="inherits"> inherits <ahref="#/v5/api/utils/transactions/-%23-Transaction">Transaction</a></span><divclass="anchors"><aclass="self"href="#/v5/api/providers/types/-%23-providers-TransactionResponse"></a></div></div></h3><p>A <b>TransactionResponse</b> includes all properties of a <ahref="#/v5/api/utils/transactions/-%23-Transaction">Transaction</a> as well as several properties that are useful once it has been mined.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">transaction</span><spanclass="symbol">.</span><spanclass="method">blockNumber</span><spanclass="arrow">⇒</span><spanclass="returns">number</span><divclass="anchors"></div></div><divclass="body"><p>The number ("height") of the block this transaction was mined in. If the block has not been mined, this is <codeclass="inline">null</code>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">transaction</span><spanclass="symbol">.</span><spanclass="method">blockHash</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 >></span><divclass="anchors"></div></div><divclass="body"><p>The hash of the block this transaction was mined in. If the block has not been mined, this is <codeclass="inline">null</code>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">transaction</span><spanclass="symbol">.</span><spanclass="method">timestamp</span><spanclass="arrow">⇒</span><spanclass="returns">number</span><divclass="anchors"></div></div><divclass="body"><p>The timestamp of the block this transaction was mined in. If the block has not been mined, this is <codeclass="inline">null</code>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">transaction</span><spanclass="symbol">.</span><spanclass="method">confirmations</span><spanclass="arrow">⇒</span><spanclass="returns">number</span><divclass="anchors"></div></div><divclass="body"><p>The number of blocks that have been mined (including the initial block) since this transaction was mined.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">transaction</span><spanclass="symbol">.</span><spanclass="method">wait</span><spanclass="symbol">(</span><spanclass="symbol">[</span><spanclass="param">confirmations</span> = <spanclass="param">1</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Promise<<ahref="#/v5/api/providers/types/-%23-providers-TransactionReceipt">TransactionReceipt</a>></span><divclass="anchors"></div></div><divclass="body"><p>Wait for <i>confirmations</i>. If 0, and the transaction has not been mined, <codeclass="inline">null</code> is returned.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">receipt</span><spanclass="symbol">.</span><spanclass="method">to</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/address/-%23-address">Address</a>></span><divclass="anchors"></div></div><divclass="body"><p>The address this transaction is to. This is <codeclass="inline">null</code> if the the transaction was an <b>init transaction</b>, used to deploy a contract.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">receipt</span><spanclass="symbol">.</span><spanclass="method">from</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/address/-%23-address">Address</a>></span><divclass="anchors"></div></div><divclass="body"><p>The address this transaction is from.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">receipt</span><spanclass="symbol">.</span><spanclass="method">contractAddress</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/address/-%23-address">Address</a>></span><divclass="anchors"></div></div><divclass="body"><p>If this transaction has a <codeclass="inline">null</code> to address, it is an <b>init transaction</b> used to deploy a contract, in which case this is the address created by that contract.</p>
<p>To compute a contract address, the <ahref="#/v5/api/utils/address/-%23-utils-getContractAddress">getContractAddress</a> utility function can also be used with a <ahref="#/v5/api/providers/types/-%23-providers-TransactionResponse">TransactionResponse</a> object, which requires the transaction nonce and the address of the sender.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">receipt</span><spanclass="symbol">.</span><spanclass="method">transactionIndex</span><spanclass="arrow">⇒</span><spanclass="returns">number</span><divclass="anchors"></div></div><divclass="body"><p>The index of this transaction in the list of transactions included in the block this transaction was mined in.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">receipt</span><spanclass="symbol">.</span><spanclass="method">root</span><spanclass="arrow">⇒</span><spanclass="returns">string</span><divclass="anchors"></div></div><divclass="body"><p>The intermediate state root of a receipt.</p>
<p>Only transactions included in blocks <b>before</b> the <ahref="https://eips.ethereum.org/EIPS/eip-609">Byzantium Hard Fork</a> have this property, as it was replaced by the <codeclass="inline">status</code> property.</p>
<p>The property is generally of little use to developers. At the time it could be used to verify a state transition with a fraud-proof only considering the single transaction; without it the full block must be considered.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">receipt</span><spanclass="symbol">.</span><spanclass="method">gasUsed</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/bignumber/">BigNumber</a></span><divclass="anchors"></div></div><divclass="body"><p>The amount of gas actually used by this transaction.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">receipt</span><spanclass="symbol">.</span><spanclass="method">logsBloom</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>></span><divclass="anchors"></div></div><divclass="body"><p>A <ahref="https://en.wikipedia.org/wiki/Bloom_filter">bloom-filter</a>, which incldues all the addresses and topics included in any log in this transaction.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">receipt</span><spanclass="symbol">.</span><spanclass="method">blockHash</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 >></span><divclass="anchors"></div></div><divclass="body"><p>The block hash of the block that this transaction was included in.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">receipt</span><spanclass="symbol">.</span><spanclass="method">transactionHash</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 >></span><divclass="anchors"></div></div><divclass="body"><p>The transaction hash of this transaction.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">receipt</span><spanclass="symbol">.</span><spanclass="method">logs</span><spanclass="arrow">⇒</span><spanclass="returns">Array<<ahref="#/v5/api/providers/types/-%23-providers-Log">Log</a>></span><divclass="anchors"></div></div><divclass="body"><p>All the logs emitted by this transaction.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">receipt</span><spanclass="symbol">.</span><spanclass="method">blockNumber</span><spanclass="arrow">⇒</span><spanclass="returns">number</span><divclass="anchors"></div></div><divclass="body"><p>The block height (number) of the block that this transaction was included in.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">receipt</span><spanclass="symbol">.</span><spanclass="method">confirmations</span><spanclass="arrow">⇒</span><spanclass="returns">number</span><divclass="anchors"></div></div><divclass="body"><p>The number of blocks that have been mined since this transaction, including the actual block it was mined in.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">receipt</span><spanclass="symbol">.</span><spanclass="method">cumulativeGasUsed</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/bignumber/">BigNumber</a></span><divclass="anchors"></div></div><divclass="body"><p>For the block this transaction was included in, this is the sum of the gas used used by each transaction in the ordered list of transactions up to (and including) this transaction.</p>
<p>This is generally of little interest to developers.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">receipt</span><spanclass="symbol">.</span><spanclass="method">byzantium</span><spanclass="arrow">⇒</span><spanclass="returns">boolean</span><divclass="anchors"></div></div><divclass="body"><p>This is true if the block is in a <ahref="https://eips.ethereum.org/EIPS/eip-609">post-Byzantium Hard Fork</a> block.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">receipt</span><spanclass="symbol">.</span><spanclass="method">status</span><spanclass="arrow">⇒</span><spanclass="returns">boolean</span><divclass="anchors"></div></div><divclass="body"><p>The status of a transaction is 1 is successful or 0 if it was reverted. Only transactions included in blocks <ahref="https://eips.ethereum.org/EIPS/eip-609">post-Byzantium Hard Fork</a> have this property.</p>
</div></div><divclass="page-separator"></div><aname="/v5/api/utils/-%23-utilities"></a><aname="/v5/api/utils/"></a><h1class="show-anchors"><div>Utilities<divclass="anchors"><aclass="self"href="#/v5/api/utils/-%23-utilities"></a></div></div></h1><p>These utilities are used extensively within the library, but are also quite useful for application developers.</p>
<divclass="toc"><divstyle="padding-left: 0px"><spanclass="bullet">•</span><ahref="#/v5/api/utils/abi/">Application Binary Interface</a></div><divstyle="padding-left: 0px"><spanclass="bullet">•</span><ahref="#/v5/api/utils/address/">Addresses</a></div><divstyle="padding-left: 0px"><spanclass="bullet">•</span><ahref="#/v5/api/utils/bignumber/">BigNumber</a></div><divstyle="padding-left: 0px"><spanclass="bullet">•</span><ahref="#/v5/api/utils/bytes/">Byte Manipulation</a></div><divstyle="padding-left: 0px"><spanclass="bullet">•</span><ahref="#/v5/api/utils/constants/">Constants</a></div><divstyle="padding-left: 0px"><spanclass="bullet">•</span><ahref="#/v5/api/utils/display-logic/">Display Logic and Input</a></div><divstyle="padding-left: 0px"><spanclass="bullet">•</span><ahref="#/v5/api/utils/encoding/">Encoding Utilities</a></div><divstyle="padding-left: 0px"><spanclass="bullet">•</span><ahref="#/v5/api/utils/fixednumber/">FixedNumber</a></div><divstyle="padding-left: 0px"><spanclass="bullet">•</span><ahref="#/v5/api/utils/hashing/">Hashing Algorithms</a></div><divstyle="padding-left: 0px"><spanclass="bullet">•</span><ahref="#/v5/api/utils/hdnode/">HD Wallet</a></div><divstyle="padding-left: 0px"><spanclass="bullet">•</span><ahref="#/v5/api/utils/logger/">Logging</a></div><divstyle="padding-left: 0px"><spanclass="bullet">•</span><ahref="#/v5/api/utils/properties/">Property Utilities</a></div><divstyle="padding-left: 0px"><spanclass="bullet">•</span><ahref="#/v5/api/utils/signing-key/">Signing Key</a></div><divstyle="padding-left: 0px"><spanclass="bullet">•</span><ahref="#/v5/api/utils/strings/">Strings</a></div><divstyle="padding-left: 0px"><spanclass="bullet">•</span><ahref="#/v5/api/utils/transactions/">Transactions</a></div><divstyle="padding-left: 0px"><spanclass="bullet">•</span><ahref="#/v5/api/utils/web/">Web Utilities</a></div><divstyle="padding-left: 0px"><spanclass="bullet">•</span><ahref="#/v5/api/utils/wordlists/">Wordlists</a></div></div><divclass="page-separator"></div><aname="/v5/api/utils/abi/-%23-application-binary-interface"></a><aname="/v5/api/utils/abi/"></a><h1class="show-anchors"><div>Application Binary Interface<divclass="anchors"><aclass="self"href="#/v5/api/utils/abi/-%23-application-binary-interface"></a></div></div></h1><p>An <b>Application Binary Interface</b> (ABI) is a collection of <ahref="#/v5/api/utils/abi/fragments/-%23-Fragment">Fragments</a> which specify how to interact with various components of a Contract.</p>
<p>An <ahref="#/v5/api/utils/abi/interface/">Interface</a> helps organize Fragments by type as well as provides the functionality required to encode, decode and work with each component.</p>
<p>Most developers will not require this low-level access to encoding and decoding the binary data on the network and will most likely use a <ahref="#/v5/api/contract/contract/">Contract</a> which provides a more convenient interface. Some framework, tool developers or developers using advanced techniques may find these classes and utilities useful.</p>
<divclass="toc"><divstyle="padding-left: 0px"><spanclass="bullet">•</span><ahref="#/v5/api/utils/abi/coder/">AbiCoder</a></div><divstyle="padding-left: 0px"><spanclass="bullet">•</span><ahref="#/v5/api/utils/abi/formats/">ABI Formats</a></div><divstyle="padding-left: 0px"><spanclass="bullet">•</span><ahref="#/v5/api/utils/abi/fragments/">Fragments</a></div><divstyle="padding-left: 0px"><spanclass="bullet">•</span><ahref="#/v5/api/utils/abi/interface/">Interface</a></div></div><divclass="page-separator"></div><aname="/v5/api/utils/abi/coder/-%23-AbiCoder"></a><aname="/v5/api/utils/abi/coder/-%23-AbiCoder"></a><aname="/v5/api/utils/abi/coder/"></a><h1class="show-anchors"><div>AbiCoder<divclass="anchors"><aclass="self"href="#/v5/api/utils/abi/coder/-%23-AbiCoder"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/abi-coder.ts#L32">source</a></div></div></h1><p>The <b>AbiCoder</b> is a collection of Coders which can be used to encode and decode the binary data formats used to interoperate between the EVM and higher level libraries.</p>
<p>Most developers will never need to use this class directly, since the <ahref="#/v5/api/utils/abi/interface/">Interface</a> class greatly simplifies these operations.</p>
<aname="/v5/api/utils/abi/coder/-%23-AbiCoder--creating"></a><aname="/v5/api/utils/abi/coder/-%23-AbiCoder--AbiCoder--creating"></a><aname="/v5/api/utils/abi/coder/"></a><h2class="show-anchors"><div>Creating Instance<divclass="anchors"><aclass="self"href="#/v5/api/utils/abi/coder/-%23-AbiCoder--creating"></a></div></div></h2><p>For the most part, there should never be a need to manually create an instance of an <ahref="#/v5/api/utils/abi/coder/">AbiCoder</a>, since one is created with the default coersion function when the library is loaded which can be used universally.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="modifier">new </span><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="method">AbiCoder</span><spanclass="symbol">(</span><spanclass="symbol">[</span><spanclass="param">coerceFunc</span><spanclass="symbol">]</span><spanclass="symbol">)</span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/abi-coder.ts#L35">source</a></div></div><divclass="body"><p>Create a new AbiCoder instance, which will call the <i>coerceFunc</i> on every decode, where the result of the call will be used in the Result.</p>
<p>The function signature is `(type, value)`, where the <i>type</i> is the string describing the type and the <i>value</i> is the processed value from the underlying Coder.</p>
<p>If the callback throws, the Result will contain a property that when accessed will throw, allowing for higher level libraries to recover from data errors.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="method">defaultAbiCoder</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/abi/coder/">AbiCoder</a></span><divclass="anchors"></div></div><divclass="body"><p>An <ahref="#/v5/api/utils/abi/coder/">AbiCoder</a> created when the library is imported which is used by the <ahref="#/v5/api/utils/abi/interface/">Interface</a>.</p>
<aname="/v5/api/utils/abi/coder/-%23-AbiCoder-encode"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">abiCoder</span><spanclass="symbol">.</span><spanclass="method">encode</span><spanclass="symbol">(</span><spanclass="param">types</span><spanclass="symbol">,</span><spanclass="param">values</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>></span><divclass="anchors"><aclass="self"href="#/v5/api/utils/abi/coder/-%23-AbiCoder-encode"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/abi-coder.ts#L94">source</a></div></div><divclass="body"><p>Encode the array <i>values</i> according the array of <i>types</i>, each of which may be a string or a <ahref="#/v5/api/utils/abi/fragments/-%23-ParamType">ParamType</a>.</p>
</div></div><aname="/v5/api/utils/abi/coder/-%23-AbiCoder-decode"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">abiCoder</span><spanclass="symbol">.</span><spanclass="method">decode</span><spanclass="symbol">(</span><spanclass="param">types</span><spanclass="symbol">,</span><spanclass="param">data</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/abi/interface/-%23-Result">Result</a></span><divclass="anchors"><aclass="self"href="#/v5/api/utils/abi/coder/-%23-AbiCoder-decode"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/abi-coder.ts#L110">source</a></div></div><divclass="body"><p>Decode the <i>data</i> according to the array of <i>types</i>, each of which may be a string or <ahref="#/v5/api/utils/abi/fragments/-%23-ParamType">ParamType</a>.</p>
</div></div><divclass="page-separator"></div><aname="/v5/api/utils/abi/formats/-%23-abi-formats"></a><aname="/v5/api/utils/abi/formats/-%23-abi-formats"></a><aname="/v5/api/utils/abi/formats/"></a><h1class="show-anchors"><div>ABI Formats<divclass="anchors"><aclass="self"href="#/v5/api/utils/abi/formats/-%23-abi-formats"></a></div></div></h1><p>@TODO: Expand this section</p>
<divclass="page-separator"></div><aname="/v5/api/utils/abi/fragments/-%23-fragments"></a><aname="/v5/api/utils/abi/fragments/-%23-fragments"></a><aname="/v5/api/utils/abi/fragments/"></a><h1class="show-anchors"><div>Fragments<divclass="anchors"><aclass="self"href="#/v5/api/utils/abi/fragments/-%23-fragments"></a></div></div></h1><p>Explain an ABI.</p>
<aname="/v5/api/utils/abi/fragments/-%23-fragments--formats--json-string-abi-solidity-output-json"></a><aname="/v5/api/utils/abi/fragments/"></a><h3class="show-anchors"><div>JSON String ABI (Solidity Output JSON)<divclass="anchors"><aclass="self"href="#/v5/api/utils/abi/fragments/-%23-fragments--formats--json-string-abi-solidity-output-json"></a></div></div></h3><p>The <b>JSON ABI Format</b> is the format that is <ahref="https://solidity.readthedocs.io/en/v0.6.0/using-the-compiler.html#output-description">output from the Solidity compiler</a>.</p>
<p>A JSON serialized object is always a string, which represents an Array of Objects, where each Object has various properties describing the <ahref="#/v5/api/utils/abi/fragments/-%23-Fragment">Fragment</a> of the ABI.</p>
<aname="/v5/api/utils/abi/fragments/-%23-fragments--formats--humanb-readable-abi"></a><aname="/v5/api/utils/abi/fragments/"></a><h3class="show-anchors"><div>Humanb-Readable ABI<divclass="anchors"><aclass="self"href="#/v5/api/utils/abi/fragments/-%23-fragments--formats--humanb-readable-abi"></a></div></div></h3><p>The Human-Readable ABI was @TODO</p>
<aname="/v5/api/utils/abi/fragments/-%23-fragments--output-formats"></a><aname="/v5/api/utils/abi/fragments/-%23-fragments--formats--fragments--output-formats"></a><aname="/v5/api/utils/abi/fragments/"></a><h3class="show-anchors"><div>Output Formats<divclass="anchors"><aclass="self"href="#/v5/api/utils/abi/fragments/-%23-fragments--output-formats"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/fragments.ts#L235">source</a></div></div></h3><p>Each <ahref="#/v5/api/utils/abi/fragments/-%23-Fragment">Fragment</a> and <ahref="#/v5/api/utils/abi/fragments/-%23-ParamType">ParamType</a> may be output using its <codeclass="inline">format</code> method.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="path">FragmentTypes</span><spanclass="symbol">.</span><spanclass="method">full</span><spanclass="arrow">⇒</span><spanclass="returns">string</span><divclass="anchors"></div></div><divclass="body"><p>This is a full human-readable string, including all parameter names, any optional modifiers (e.g. <codeclass="inline">indexed</code>, <codeclass="inline">public</code>, etc) and white-space to aid in human readabiliy.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="path">FragmentTypes</span><spanclass="symbol">.</span><spanclass="method">minimal</span><spanclass="arrow">⇒</span><spanclass="returns">string</span><divclass="anchors"></div></div><divclass="body"><p>This is similar to <codeclass="inline">full</code>, except with no unnecessary whitespace or parameter names. This is useful for storing a minimal string which can still fully reconstruct the original Fragment using <ahref="#/v5/api/utils/abi/fragments/-%23-Fragment-from">Fragment&thinsp;.&thinsp;from</a>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="path">FragmentTypes</span><spanclass="symbol">.</span><spanclass="method">json</span><spanclass="arrow">⇒</span><spanclass="returns">string</span><divclass="anchors"></div></div><divclass="body"><p>This returns a JavaScript Object which is safe to call <codeclass="inline">JSON.stringify</code> on to create a JSON string.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="path">FragmentTypes</span><spanclass="symbol">.</span><spanclass="method">sighash</span><spanclass="arrow">⇒</span><spanclass="returns">string</span><divclass="anchors"></div></div><divclass="body"><p>This is a minimal output format, which is used by Solidity when computing a signature hash or an event topic hash.</p>
</div></div><divclass="definition container-box warning"><divclass="term">Note</div><divclass="body"><p>The <codeclass="inline">sighash</code> format is <b>insufficient</b> to re-create the original <ahref="#/v5/api/utils/abi/fragments/-%23-Fragment">Fragment</a>, since it discards modifiers such as indexed, anonymous, stateMutability, etc.</p>
</div></div><aname="/v5/api/utils/abi/fragments/-%23-Fragment"></a><aname="/v5/api/utils/abi/fragments/-%23-fragments--Fragment"></a><aname="/v5/api/utils/abi/fragments/"></a><h2class="show-anchors"><div>Fragment<divclass="anchors"><aclass="self"href="#/v5/api/utils/abi/fragments/-%23-Fragment"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/fragments.ts#L405">source</a></div></div></h2><p>An ABI is a collection of <b>Fragments</b>, where each fragment specifies:</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">fragment</span><spanclass="symbol">.</span><spanclass="method">name</span><spanclass="arrow">⇒</span><spanclass="returns">string</span><divclass="anchors"></div></div><divclass="body"><p>This is the name of the Event or Function. This will be null for a <ahref="#/v5/api/utils/abi/fragments/-%23-ConstructorFragment">ConstructorFragment</a>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">fragment</span><spanclass="symbol">.</span><spanclass="method">type</span><spanclass="arrow">⇒</span><spanclass="returns">string</span><divclass="anchors"></div></div><divclass="body"><p>This is a string which indicates the type of the <ahref="#/v5/api/utils/abi/fragments/-%23-Fragment">Fragment</a>. This will be one of:</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">fragment</span><spanclass="symbol">.</span><spanclass="method">inputs</span><spanclass="arrow">⇒</span><spanclass="returns">Array<<ahref="#/v5/api/utils/abi/fragments/-%23-ParamType">ParamType</a>></span><divclass="anchors"></div></div><divclass="body"><p>This is an array of of each <ahref="#/v5/api/utils/abi/fragments/-%23-ParamType">ParamType</a> for the input parameters to the Constructor, Event of Function.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">fragment</span><spanclass="symbol">.</span><spanclass="method">gas</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/bignumber/">BigNumber</a></span><divclass="anchors"></div></div><divclass="body"><p>This is the gas limit that should be used during deployment. It may be null.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">fragment</span><spanclass="symbol">.</span><spanclass="method">payable</span><spanclass="arrow">⇒</span><spanclass="returns">boolean</span><divclass="anchors"></div></div><divclass="body"><p>This is whether the constructor may receive ether during deployment as an endowment (i.e. msg.value != 0).</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">fragment</span><spanclass="symbol">.</span><spanclass="method">stateMutability</span><spanclass="arrow">⇒</span><spanclass="returns">string</span><divclass="anchors"></div></div><divclass="body"><p>This is the state mutability of the constructor. It can be any of:</p>
<aname="/v5/api/utils/abi/fragments/-%23-ConstructorFragment-from"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="path">ConstructorFragment</span><spanclass="symbol">.</span><spanclass="method">from</span><spanclass="symbol">(</span><spanclass="param">objectOrString</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/abi/fragments/-%23-ConstructorFragment">ConstructorFragment</a></span><divclass="anchors"><aclass="self"href="#/v5/api/utils/abi/fragments/-%23-ConstructorFragment-from"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/fragments.ts#L746">source</a></div></div><divclass="body"><p>Tra la la...</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">fragment</span><spanclass="symbol">.</span><spanclass="method">anonymous</span><spanclass="arrow">⇒</span><spanclass="returns">boolean</span><divclass="anchors"></div></div><divclass="body"><p>This is whether the event is anonymous. An anonymous Event does not inject its topic hash as topic0 when creating a log.</p>
<aname="/v5/api/utils/abi/fragments/-%23-EventFragment-from"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="path">EventFragment</span><spanclass="symbol">.</span><spanclass="method">from</span><spanclass="symbol">(</span><spanclass="param">objectOrString</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/abi/fragments/-%23-EventFragment">EventFragment</a></span><divclass="anchors"><aclass="self"href="#/v5/api/utils/abi/fragments/-%23-EventFragment-from"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/fragments.ts#L520">source</a></div></div><divclass="body"><p>Tra la la...</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">fragment</span><spanclass="symbol">.</span><spanclass="method">constant</span><spanclass="arrow">⇒</span><spanclass="returns">boolean</span><divclass="anchors"></div></div><divclass="body"><p>This is whether the function is constant (i.e. does not change state). This is true if the state mutability is <codeclass="inline">pure</code> or <codeclass="inline">view</code>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">fragment</span><spanclass="symbol">.</span><spanclass="method">stateMutability</span><spanclass="arrow">⇒</span><spanclass="returns">string</span><divclass="anchors"></div></div><divclass="body"><p>This is the state mutability of the constructor. It can be any of:</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">fragment</span><spanclass="symbol">.</span><spanclass="method">outputs</span><spanclass="arrow">⇒</span><spanclass="returns">Array<<ahref="#/v5/api/utils/abi/fragments/-%23-ParamType">ParamType</a>></span><divclass="anchors"></div></div><divclass="body"><p>A list of the Function output parameters.</p>
<aname="/v5/api/utils/abi/fragments/-%23-FunctionFragment-from"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="path">FunctionFragment</span><spanclass="symbol">.</span><spanclass="method">from</span><spanclass="symbol">(</span><spanclass="param">objectOrString</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/abi/fragments/-%23-FunctionFragment">FunctionFragment</a></span><divclass="anchors"><aclass="self"href="#/v5/api/utils/abi/fragments/-%23-FunctionFragment-from"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/fragments.ts#L746">source</a></div></div><divclass="body"><p>Tra la la...</p>
</div></div><aname="/v5/api/utils/abi/fragments/-%23-ParamType"></a><aname="/v5/api/utils/abi/fragments/-%23-fragments--ParamType"></a><aname="/v5/api/utils/abi/fragments/"></a><h2class="show-anchors"><div>ParamType<divclass="anchors"><aclass="self"href="#/v5/api/utils/abi/fragments/-%23-ParamType"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/fragments.ts#L251">source</a></div></div></h2><p>The following examples will represent the Solidity parameter:</p>
<aname="/v5/api/utils/abi/fragments/-%23-ParamType-name"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">paramType</span><spanclass="symbol">.</span><spanclass="method">name</span><spanclass="arrow">⇒</span><spanclass="returns">string</span><divclass="anchors"><aclass="self"href="#/v5/api/utils/abi/fragments/-%23-ParamType-name"></a></div></div><divclass="body"><p>The local parameter name. This may be null for unnamed parameters. For example, the parameter definition <codeclass="inline">string foobar</code> would be <codeclass="inline">foobar</code>.</p>
</div></div><aname="/v5/api/utils/abi/fragments/-%23-ParamType-type"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">paramType</span><spanclass="symbol">.</span><spanclass="method">type</span><spanclass="arrow">⇒</span><spanclass="returns">string</span><divclass="anchors"><aclass="self"href="#/v5/api/utils/abi/fragments/-%23-ParamType-type"></a></div></div><divclass="body"><p>The full type of the parameter, including tuple and array symbols. This may be null for unnamed parameters. For the above example, this would be <codeclass="inline">foobar</code>.</p>
</div></div><aname="/v5/api/utils/abi/fragments/-%23-ParamType-baseType"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">paramType</span><spanclass="symbol">.</span><spanclass="method">baseType</span><spanclass="arrow">⇒</span><spanclass="returns">string</span><divclass="anchors"><aclass="self"href="#/v5/api/utils/abi/fragments/-%23-ParamType-baseType"></a></div></div><divclass="body"><p>The base type of the parameter. For primitive types (e.g. <codeclass="inline">address</code>, <codeclass="inline">uint256</code>, etc) this is equal to <ahref="#/v5/api/utils/abi/fragments/-%23-ParamType-type">type</a>. For arrays, it will be the string <codeclass="inline">array</code> and for a tuple, it will be the string <codeclass="inline">tuple</code>.</p>
</div></div><aname="/v5/api/utils/abi/fragments/-%23-ParamType-indexed"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">paramType</span><spanclass="symbol">.</span><spanclass="method">indexed</span><spanclass="arrow">⇒</span><spanclass="returns">boolean</span><divclass="anchors"><aclass="self"href="#/v5/api/utils/abi/fragments/-%23-ParamType-indexed"></a></div></div><divclass="body"><p>Whether the parameter has been marked as indexed. This <b>only</b> applies to parameters which are part of an <ahref="#/v5/api/utils/abi/fragments/-%23-EventFragment">EventFragment</a>.</p>
</div></div><aname="/v5/api/utils/abi/fragments/-%23-ParamType-arrayChildren"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">paramType</span><spanclass="symbol">.</span><spanclass="method">arrayChildren</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/abi/fragments/-%23-ParamType">ParamType</a></span><divclass="anchors"><aclass="self"href="#/v5/api/utils/abi/fragments/-%23-ParamType-arrayChildren"></a></div></div><divclass="body"><p>The type of children of the array. This is null for for any parameter wjhich is not an array.</p>
</div></div><aname="/v5/api/utils/abi/fragments/-%23-ParamType-arrayLength"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">paramType</span><spanclass="symbol">.</span><spanclass="method">arrayLength</span><spanclass="arrow">⇒</span><spanclass="returns">number</span><divclass="anchors"><aclass="self"href="#/v5/api/utils/abi/fragments/-%23-ParamType-arrayLength"></a></div></div><divclass="body"><p>The length of the array, or <codeclass="inline">-1</code> for dynamic-length arrays. This is null for parameters which is not arrays.</p>
</div></div><aname="/v5/api/utils/abi/fragments/-%23-ParamType-components"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">paramType</span><spanclass="symbol">.</span><spanclass="method">components</span><spanclass="arrow">⇒</span><spanclass="returns">Array<<ahref="#/v5/api/utils/abi/fragments/-%23-ParamType">ParamType</a>></span><divclass="anchors"><aclass="self"href="#/v5/api/utils/abi/fragments/-%23-ParamType-components"></a></div></div><divclass="body"><p>The components of a tuple. This is null for non-tuple parameters.</p>
</div></div><aname="/v5/api/utils/abi/fragments/-%23-fragments--ParamType--methods"></a><aname="/v5/api/utils/abi/fragments/"></a><h3class="show-anchors"><div>Methods<divclass="anchors"><aclass="self"href="#/v5/api/utils/abi/fragments/-%23-fragments--ParamType--methods"></a></div></div></h3><p>Tra la la...</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">paramType</span><spanclass="symbol">.</span><spanclass="method">format</span><spanclass="symbol">(</span><spanclass="symbol">[</span><spanclass="param">outputType</span> = <spanclass="param">sighash</span><spanclass="symbol">]</span><spanclass="symbol">)</span><divclass="anchors"></div></div><divclass="body"><p>Tra la la...</p>
</div></div><aname="/v5/api/utils/abi/fragments/-%23-ParamType-from"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="path">ParamType</span><spanclass="symbol">.</span><spanclass="method">from</span><spanclass="symbol">(</span><spanclass="param">objectOrString</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/abi/fragments/-%23-ParamType">ParamType</a></span><divclass="anchors"><aclass="self"href="#/v5/api/utils/abi/fragments/-%23-ParamType-from"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/fragments.ts#L357">source</a></div></div><divclass="body"><p>Tra la la...</p>
</div></div><aname="/v5/api/utils/abi/fragments/-%23-ParamType-isParamType"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="path">ParamType</span><spanclass="symbol">.</span><spanclass="method">isParamType</span><spanclass="symbol">(</span><spanclass="param">object</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">boolean</span><divclass="anchors"><aclass="self"href="#/v5/api/utils/abi/fragments/-%23-ParamType-isParamType"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/fragments.ts#L388">source</a></div></div><divclass="body"><p>Tra la la...</p>
</div></div><divclass="page-separator"></div><aname="/v5/api/utils/abi/interface/-%23-Interface"></a><aname="/v5/api/utils/abi/interface/-%23-Interface"></a><aname="/v5/api/utils/abi/interface/"></a><h1class="show-anchors"><div>Interface<divclass="anchors"><aclass="self"href="#/v5/api/utils/abi/interface/-%23-Interface"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/interface.ts#L65">source</a></div></div></h1><p>The <b>Interface</b> Class abstracts the encoding and decoding required to interact with contracts on the Ethereum network.</p>
<p>Many of the standards organically evolved along side the <ahref="https://solidity.readthedocs.io/en/v0.6.2/">Solidity</a> language, which other languages have adopted to remain compatibile with existing deployed contracts.</p>
<p>The EVM itself does not understand what the ABI is. It is simply an agreed upon set of formats to encode various types of data which each contract can expect so they can interoperate with each other.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="modifier">new </span><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="method">Interface</span><spanclass="symbol">(</span><spanclass="param">abi</span><spanclass="symbol">)</span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/interface.ts#L79">source</a></div></div><divclass="body"><p>Create a new <b>Interface</b> from a JSON string or object representing <i>abi</i>.</p>
<p>The <i>abi</i> may be a JSON string or the parsed Object (using JSON.parse) which is emitted by the <ahref="https://solidity.readthedocs.io/en/v0.6.0/using-the-compiler.html#output-description">Solidity compiler</a> (or compatible languages).</p>
<p>The <i>abi</i> may also be a <ahref="https://blog.ricmoo.com/human-readable-contract-abis-in-ethers-js-141902f4d917">Human-Readable Abi</a>, which is a format the Ethers created to simplify manually typing the ABI into the source and so that a Contract ABI can also be referenced easily within the same source file.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">interface</span><spanclass="symbol">.</span><spanclass="method">fragments</span><spanclass="arrow">⇒</span><spanclass="returns">Array<<ahref="#/v5/api/utils/abi/fragments/-%23-Fragment">Fragment</a>></span><divclass="anchors"></div></div><divclass="body"><p>All the <ahref="#/v5/api/utils/abi/fragments/-%23-Fragment">Fragments</a> in the interface.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">interface</span><spanclass="symbol">.</span><spanclass="method">events</span><spanclass="arrow">⇒</span><spanclass="returns">Array<<ahref="#/v5/api/utils/abi/fragments/-%23-EventFragment">EventFragment</a>></span><divclass="anchors"></div></div><divclass="body"><p>All the <ahref="#/v5/api/utils/abi/fragments/-%23-EventFragment">Event Fragments</a> in the interface.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">interface</span><spanclass="symbol">.</span><spanclass="method">functions</span><spanclass="arrow">⇒</span><spanclass="returns">Array<<ahref="#/v5/api/utils/abi/fragments/-%23-FunctionFragment">FunctionFragment</a>></span><divclass="anchors"></div></div><divclass="body"><p>All the <ahref="#/v5/api/utils/abi/fragments/-%23-FunctionFragment">Function Fragments</a> in the interface.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">interface</span><spanclass="symbol">.</span><spanclass="method">deploy</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/abi/fragments/-%23-ConstructorFragment">ConstructorFragment</a></span><divclass="anchors"></div></div><divclass="body"><p>The <ahref="#/v5/api/utils/abi/fragments/-%23-ConstructorFragment">Constructor Fragments</a> for the interface.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">interface</span><spanclass="symbol">.</span><spanclass="method">format</span><spanclass="symbol">(</span><spanclass="symbol">[</span><spanclass="param">format</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">string | Array< string ></span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/interface.ts#L145">source</a></div></div><divclass="body"><p>Return the formatted <b>Interface</b>. If the format type is <codeclass="inline">json</code> a single string is returned, otherwise an Array of the human-readable strings is returned.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">interface</span><spanclass="symbol">.</span><spanclass="method">getFunction</span><spanclass="symbol">(</span><spanclass="param">fragment</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/abi/fragments/-%23-FunctionFragment">FunctionFragment</a></span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/interface.ts#L179">source</a></div></div><divclass="body"><p>Returns the <ahref="#/v5/api/utils/abi/fragments/-%23-FunctionFragment">FunctionFragment</a> for <i>fragment</i> (see <ahref="#/v5/api/utils/abi/interface/-%23-Interface--specifying-fragments">Specifying Fragments</a>).</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">interface</span><spanclass="symbol">.</span><spanclass="method">getEvent</span><spanclass="symbol">(</span><spanclass="param">fragment</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/abi/fragments/-%23-EventFragment">EventFragment</a></span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/interface.ts#L211">source</a></div></div><divclass="body"><p>Returns the <ahref="#/v5/api/utils/abi/fragments/-%23-EventFragment">EventFragment</a> for <i>fragment</i> (see <ahref="#/v5/api/utils/abi/interface/-%23-Interface--specifying-fragments">Specifying Fragments</a>).</p>
</div></div><aname="/v5/api/utils/abi/interface/-%23-Interface--selectors"></a><aname="/v5/api/utils/abi/interface/-%23-Interface--Interface--selectors"></a><aname="/v5/api/utils/abi/interface/"></a><h2class="show-anchors"><div>Signature and Topic Hashes<divclass="anchors"><aclass="self"href="#/v5/api/utils/abi/interface/-%23-Interface--selectors"></a></div></div></h2>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">interface</span><spanclass="symbol">.</span><spanclass="method">getSighash</span><spanclass="symbol">(</span><spanclass="param">fragment</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 4 >></span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/interface.ts#L244">source</a></div></div><divclass="body"><p>Return the sighash (or Function Selector) for <i>fragment</i> (see <ahref="#/v5/api/utils/abi/interface/-%23-Interface--specifying-fragments">Specifying Fragments</a>).</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">interface</span><spanclass="symbol">.</span><spanclass="method">getEventTopic</span><spanclass="symbol">(</span><spanclass="param">fragment</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 >></span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/interface.ts#L253">source</a></div></div><divclass="body"><p>Return the topic hash for <i>fragment</i> (see <ahref="#/v5/api/utils/abi/interface/-%23-Interface--specifying-fragments">Specifying Fragments</a>).</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">interface</span><spanclass="symbol">.</span><spanclass="method">encodeDeploy</span><spanclass="symbol">(</span><spanclass="symbol">[</span><spanclass="param">values</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>></span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/interface.ts#L270">source</a></div></div><divclass="body"><p>Return the encoded deployment data, which can be concatenated to the deployment bytecode of a contract to pass <i>values</i> into the contract constructor.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">interface</span><spanclass="symbol">.</span><spanclass="method">encodeFilterTopics</span><spanclass="symbol">(</span><spanclass="param">fragment</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">values</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Array< topic | Array< topic >></span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/interface.ts#L344">source</a></div></div><divclass="body"><p>Returns the encoded topic filter, which can be passed to getLogs for <i>fragment</i> (see <ahref="#/v5/api/utils/abi/interface/-%23-Interface--specifying-fragments">Specifying Fragments</a>) for the given <i>values</i>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">interface</span><spanclass="symbol">.</span><spanclass="method">encodeFunctionData</span><spanclass="symbol">(</span><spanclass="param">fragment</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">values</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>></span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/interface.ts#L290">source</a></div></div><divclass="body"><p>Returns the encoded data, which can be used as the data for a transaction for <i>fragment</i> (see <ahref="#/v5/api/utils/abi/interface/-%23-Interface--specifying-fragments">Specifying Fragments</a>) for the given <i>values</i>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">interface</span><spanclass="symbol">.</span><spanclass="method">encodeFunctionResult</span><spanclass="symbol">(</span><spanclass="param">fragment</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">values</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>></span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/interface.ts#L335">source</a></div></div><divclass="body"><p>Returns the encoded result, which would normally be the response from a call for <i>fragment</i> (see <ahref="#/v5/api/utils/abi/interface/-%23-Interface--specifying-fragments">Specifying Fragments</a>) for the given <i>values</i>.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">interface</span><spanclass="symbol">.</span><spanclass="method">decodeEventLog</span><spanclass="symbol">(</span><spanclass="param">fragment</span><spanclass="symbol">,</span><spanclass="param">data</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">topics</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/abi/interface/-%23-Result">Result</a></span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/interface.ts#L445">source</a></div></div><divclass="body"><p>Returns the decoded event values from an event log for <i>fragment</i> (see <ahref="#/v5/api/utils/abi/interface/-%23-Interface--specifying-fragments">Specifying Fragments</a>) for the given <i>data</i> with the optional <i>topics</i>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">interface</span><spanclass="symbol">.</span><spanclass="method">decodeFunctionData</span><spanclass="symbol">(</span><spanclass="param">fragment</span><spanclass="symbol">,</span><spanclass="param">data</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/abi/interface/-%23-Result">Result</a></span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/interface.ts#L275">source</a></div></div><divclass="body"><p>Returns the decoded values from transaction data for <i>fragment</i> (see <ahref="#/v5/api/utils/abi/interface/-%23-Interface--specifying-fragments">Specifying Fragments</a>) for the given <i>data</i>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">interface</span><spanclass="symbol">.</span><spanclass="method">decodeFunctionResult</span><spanclass="symbol">(</span><spanclass="param">fragment</span><spanclass="symbol">,</span><spanclass="param">data</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/abi/interface/-%23-Result">Result</a></span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/interface.ts#L302">source</a></div></div><divclass="body"><p>Returns the decoded values from the result of a call for <i>fragment</i> (see <ahref="#/v5/api/utils/abi/interface/-%23-Interface--specifying-fragments">Specifying Fragments</a>) for the given <i>data</i>.</p>
</div></div><aname="/v5/api/utils/abi/interface/-%23-Interface--parsing"></a><aname="/v5/api/utils/abi/interface/-%23-Interface--Interface--parsing"></a><aname="/v5/api/utils/abi/interface/"></a><h2class="show-anchors"><div>Parsing<divclass="anchors"><aclass="self"href="#/v5/api/utils/abi/interface/-%23-Interface--parsing"></a></div></div></h2><p>The functions are generally the most useful for most developers. They will automatically search the ABI for a matching Event or Function and decode the components as a fully specified description.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">interface</span><spanclass="symbol">.</span><spanclass="method">parseLog</span><spanclass="symbol">(</span><spanclass="param">log</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/abi/interface/-%23-LogDescription">LogDescription</a></span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/interface.ts#L552">source</a></div></div><divclass="body"><p>Search the event that matches the <i>log</i> topic hash and parse the values the log represents.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">interface</span><spanclass="symbol">.</span><spanclass="method">parseTransaction</span><spanclass="symbol">(</span><spanclass="param">transaction</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/abi/interface/-%23-TransactionDescription">TransactionDescription</a></span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/interface.ts#L535">source</a></div></div><divclass="body"><p>Search for the function that matches the <i>transaction</i> data sighash and parse the transaction properties.</p>
<aname="/v5/api/utils/abi/interface/-%23-Result"></a><aname="/v5/api/utils/abi/interface/-%23-Interface--Interface--types--Result"></a><aname="/v5/api/utils/abi/interface/"></a><h3class="show-anchors"><div>Result<spanclass="inherits"> inherits Array<any></span><divclass="anchors"><aclass="self"href="#/v5/api/utils/abi/interface/-%23-Result"></a></div></div></h3><p>A <b>Result</b> is an array, so each value can be accessed as a positional argument.</p>
<p>Additionally, if values are named, the identical object as its positional value can be accessed by its name.</p>
<p>The name <codeclass="inline">length</code> is however reserved as it is part of the Array, so any named value for this key is renamed to <codeclass="inline">_length</code>. If there is a name collision, only the first is available by its key.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">logDescription</span><spanclass="symbol">.</span><spanclass="method">args</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/abi/interface/-%23-Result">Result</a></span><divclass="anchors"></div></div><divclass="body"><p>The values of the input parameters of the event.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">logDescription</span><spanclass="symbol">.</span><spanclass="method">eventFragment</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/abi/fragments/-%23-EventFragment">EventFragment</a></span><divclass="anchors"></div></div><divclass="body"><p>The <ahref="#/v5/api/utils/abi/fragments/-%23-EventFragment">EventFragment</a> which matches the topic in the Log.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">transactionDescription</span><spanclass="symbol">.</span><spanclass="method">args</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/abi/interface/-%23-Result">Result</a></span><divclass="anchors"></div></div><divclass="body"><p>The decoded values from the transaction data which were passed as the input parameters.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">transactionDescription</span><spanclass="symbol">.</span><spanclass="method">functionFragment</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/abi/fragments/-%23-FunctionFragment">FunctionFragment</a></span><divclass="anchors"></div></div><divclass="body"><p>The <ahref="#/v5/api/utils/abi/fragments/-%23-FunctionFragment">FunctionFragment</a> which matches the sighash in the transaction data.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">transactionDescription</span><spanclass="symbol">.</span><spanclass="method">name</span><spanclass="arrow">⇒</span><spanclass="returns">string</span><divclass="anchors"></div></div><divclass="body"><p>The name of the function. (e.g. <codeclass="inline">transfer</code>)</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">transactionDescription</span><spanclass="symbol">.</span><spanclass="method">sighash</span><spanclass="arrow">⇒</span><spanclass="returns">string</span><divclass="anchors"></div></div><divclass="body"><p>The sighash (or function selector) that matched the transaction data.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">transactionDescription</span><spanclass="symbol">.</span><spanclass="method">signature</span><spanclass="arrow">⇒</span><spanclass="returns">string</span><divclass="anchors"></div></div><divclass="body"><p>The signature of the function. (e.g. <codeclass="inline">transfer(address,uint256)</code>)</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">transactionDescription</span><spanclass="symbol">.</span><spanclass="method">value</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/bignumber/">BigNumber</a></span><divclass="anchors"></div></div><divclass="body"><p>The value from the transaction.</p>
</div></div><aname="/v5/api/utils/abi/interface/-%23-Interface--specifying-fragments"></a><aname="/v5/api/utils/abi/interface/-%23-Interface--Interface--specifying-fragments"></a><aname="/v5/api/utils/abi/interface/"></a><h2class="show-anchors"><div>Specifying Fragments<divclass="anchors"><aclass="self"href="#/v5/api/utils/abi/interface/-%23-Interface--specifying-fragments"></a></div></div></h2><p>When specifying a fragment to any of the functions in an <b>Interface</b>, any of the following may be used:</p>
<p><ul><li>The <b>name</b> of the event or function, if it is unique and non-ambiguous within the ABI (e.g. <codeclass="inline">transfer</code>) </li><li>The <b>signature</b> of the event or function. The signature is normalized, so, for example, <codeclass="inline">uint</code> and <codeclass="inline">uint256</code> are equivalent (e.g. <codeclass="inline">transfer(address, uint)</code>) </li><li>The <b>sighash</b> or <b>topichash</b> of the function. The sighash is often referred to the function selector in Solidity (e.g. <codeclass="inline">0xa9059cbb</code>) </li><li>A <ahref="#/v5/api/utils/abi/fragments/-%23-Fragment">Fragment</a></li></ul></p>
<divclass="page-separator"></div><aname="/v5/api/utils/address/-%23-addresses"></a><aname="/v5/api/utils/address/-%23-addresses"></a><aname="/v5/api/utils/address/"></a><h1class="show-anchors"><div>Addresses<divclass="anchors"><aclass="self"href="#/v5/api/utils/address/-%23-addresses"></a></div></div></h1><p>Explain addresses,formats and checksumming here.</p>
<aname="/v5/api/utils/address/-%23-address"></a><aname="/v5/api/utils/address/-%23-addresses--address-formats--address"></a><aname="/v5/api/utils/address/"></a><h3class="show-anchors"><div>Address<divclass="anchors"><aclass="self"href="#/v5/api/utils/address/-%23-address"></a></div></div></h3><p>An <b>Address</b> is a <ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a> of 20 bytes (40 nibbles), with optional mixed case.</p>
<p>If the case is mixed, it is a <b>Checksum Address</b>, which uses a specific pattern of uppercase and lowercase letters within a given address to reduce the risk of errors introduced from typing an address or cut and paste issues.</p>
<p>All functions that return an Address will return a Checksum Address.</p>
<aname="/v5/api/utils/address/-%23-address-icap"></a><aname="/v5/api/utils/address/-%23-addresses--address-formats--address-icap"></a><aname="/v5/api/utils/address/"></a><h3class="show-anchors"><div>ICAP Address<divclass="anchors"><aclass="self"href="#/v5/api/utils/address/-%23-address-icap"></a></div></div></h3><p>The <b>ICAP Address Format</b> was an early attempt to introduce a checksum into Ethereum addresses using the popular banking industry's <ahref="https://en.wikipedia.org/wiki/International_Bank_Account_Number">IBAN</a> format with the country code specified as <b>XE</b>.</p>
<p>Due to the way IBAN encodes address, only addresses that fit into 30 base-36 characters are actually compatible, so the format was adapted to support 31 base-36 characters which is large enough for a full Ethereum address, however the preferred method was to select a private key whose address has a <codeclass="inline">0</code> as the first byte, which allows the address to be formatted as a fully compatibly standard IBAN address with 30 base-36 characters.</p>
<p>In general this format is no longer widely supported anymore, however any function that accepts an address can receive an ICAP address, and it will be converted internally.</p>
<p>To convert an address into the ICAP format, see <ahref="#/v5/api/utils/address/-%23-utils-getIcapAddress">getIcapAddress</a>.</p>
<aname="/v5/api/utils/address/-%23-utils--address"></a><aname="/v5/api/utils/address/-%23-addresses--utils--address"></a><aname="/v5/api/utils/address/"></a><h2class="show-anchors"><div>Converting and Verifying<divclass="anchors"><aclass="self"href="#/v5/api/utils/address/-%23-utils--address"></a></div></div></h2>
<aname="/v5/api/utils/address/-%23-utils-getAddress"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="method">getAddress</span><spanclass="symbol">(</span><spanclass="param">address</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/address/-%23-address">Address</a>></span><divclass="anchors"><aclass="self"href="#/v5/api/utils/address/-%23-utils-getAddress"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/address/src.ts/index.ts#L80">source</a></div></div><divclass="body"><p>Returns <i>address</i> as a Checksum Address.</p>
<p>If <i>address</i> is an invalid 40-nibble <ahref="#/v5/api/utils/bytes/-%23-HexString">HexString</a> or if it contains mixed case and the checksum is invalid, an InvalidArgument Error is thrown.</p>
</div></div><aname="/v5/api/utils/address/-%23-utils-getIcapAddress"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="method">getIcapAddress</span><spanclass="symbol">(</span><spanclass="param">address</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/address/-%23-address-icap">IcapAddress</a>></span><divclass="anchors"><aclass="self"href="#/v5/api/utils/address/-%23-utils-getIcapAddress"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/address/src.ts/index.ts#L126">source</a></div></div><divclass="body"><p>Returns <i>address</i> as an <ahref="https://github.com/ethereum/wiki/wiki/Inter-exchange-Client-Address-Protocol-%28ICAP%29">ICAP address</a>. Supports the same restrictions as <ahref="#/v5/api/utils/address/-%23-utils-getAddress">utils.getAddress</a>.</p>
</div></div><aname="/v5/api/utils/address/-%23-utils-isAddress"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="method">isAddress</span><spanclass="symbol">(</span><spanclass="param">address</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">boolean</span><divclass="anchors"><aclass="self"href="#/v5/api/utils/address/-%23-utils-isAddress"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/address/src.ts/index.ts#L118">source</a></div></div><divclass="body"><p>Returns true if <i>address</i> is valid (in any supported format).</p>
<aname="/v5/api/utils/address/-%23-utils-computeAddress"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="method">computeAddress</span><spanclass="symbol">(</span><spanclass="param">publicOrPrivateKey</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/address/-%23-address">Address</a>></span><divclass="anchors"><aclass="self"href="#/v5/api/utils/address/-%23-utils-computeAddress"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/transactions/src.ts/index.ts#L75">source</a></div></div><divclass="body"><p>Returns the address for <i>publicOrPrivateKey</i>. A public key may be compressed or uncompressed, and a private key will be converted automatically to a public key for the derivation.</p>
</div></div><aname="/v5/api/utils/address/-%23-utils-recoverAddress"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="method">recoverAddress</span><spanclass="symbol">(</span><spanclass="param">digest</span><spanclass="symbol">,</span><spanclass="param">signature</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/address/-%23-address">Address</a>></span><divclass="anchors"><aclass="self"href="#/v5/api/utils/address/-%23-utils-recoverAddress"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/transactions/src.ts/index.ts#L80">source</a></div></div><divclass="body"><p>Use <ahref="https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm#Public_key_recovery">ECDSA Public Key Recovery</a> to determine the address that signed <i>digest</i> to which generated <i>signature</i>.</p>
<aname="/v5/api/utils/address/-%23-utils-getContractAddress"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="method">getContractAddress</span><spanclass="symbol">(</span><spanclass="param">transaction</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/address/-%23-address">Address</a>></span><divclass="anchors"><aclass="self"href="#/v5/api/utils/address/-%23-utils-getContractAddress"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/address/src.ts/index.ts#L133">source</a></div></div><divclass="body"><p>Returns the contract address that would result if <i>transaction</i> was used to deploy a contract.</p>
</div></div><aname="/v5/api/utils/address/-%23-utils-getCreate2Address"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="method">getCreate2Address</span><spanclass="symbol">(</span><spanclass="param">from</span><spanclass="symbol">,</span><spanclass="param">salt</span><spanclass="symbol">,</span><spanclass="param">initCodeHash</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/address/-%23-address">Address</a>></span><divclass="anchors"><aclass="self"href="#/v5/api/utils/address/-%23-utils-getCreate2Address"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/address/src.ts/index.ts#L146">source</a></div></div><divclass="body"><p>Returns the contract address that would result from the given <ahref="https://eips.ethereum.org/EIPS/eip-1014">CREATE2</a> call.</p>
</div></div><divclass="page-separator"></div><aname="/v5/api/utils/bignumber/-%23-BigNumber"></a><aname="/v5/api/utils/bignumber/-%23-BigNumber"></a><aname="/v5/api/utils/bignumber/"></a><h1class="show-anchors"><div>BigNumber<divclass="anchors"><aclass="self"href="#/v5/api/utils/bignumber/-%23-BigNumber"></a></div></div></h1><p>Many operations in Ethereum operation on numbers which are <ahref="#/v5/api/utils/bignumber/-%23-BigNumber--notes-safenumbers">outside the range of safe values</a> to use in JavaScript.</p>
<p>A <b>BigNumber</b> is an object which safely allows mathematic operations on numbers of any magnitude.</p>
<p>Most operations which need to return a value will return a <b>BigNumber</b> and parameters which accept values will generally accept them.</p>
<aname="/v5/api/utils/bignumber/-%23-BigNumberish"></a><aname="/v5/api/utils/bignumber/-%23-BigNumber--BigNumber--types--BigNumberish"></a><aname="/v5/api/utils/bignumber/"></a><h3class="show-anchors"><div>BigNumberish<divclass="anchors"><aclass="self"href="#/v5/api/utils/bignumber/-%23-BigNumberish"></a></div></div></h3><p>Many functions and methods in this library take in values which can be non-ambiguously and safely converted to a BigNumber. These values can be sepcified as:</p>
<divclass="definition"><divclass="term"><b><i>string</i></b></div><divclass="body"><p>A <ahref="#/v5/api/utils/bytes/-%23-HexString">HexString</a> or a decimal string, either of which may be negative.</p>
</div></div><divclass="definition"><divclass="term"><b><i>BytesLike</i></b></div><divclass="body"><p>A <ahref="#/v5/api/utils/bytes/-%23-BytesLike">BytesLike</a> Object, such as an Array or Uint8Array.</p>
</div></div><divclass="definition"><divclass="term"><b><i>number</i></b></div><divclass="body"><p>A number that is within the <ahref="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER#Description">safe range</a> for JavaScript numbers.</p>
</div></div><divclass="definition"><divclass="term"><b><i>BigInt</i></b></div><divclass="body"><p>A JavaScript <ahref="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt">BigInt</a> object, on environments that support BigInt.</p>
</div></div><aname="/v5/api/utils/bignumber/-%23-BigNumber--creating"></a><aname="/v5/api/utils/bignumber/-%23-BigNumber--BigNumber--creating"></a><aname="/v5/api/utils/bignumber/"></a><h2class="show-anchors"><div>Creating Instances<divclass="anchors"><aclass="self"href="#/v5/api/utils/bignumber/-%23-BigNumber--creating"></a></div></div></h2><p>The constructor of BigNumber cannot be called directly. Instead, Use the static <codeclass="inline">BigNumber.from</code>.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">BigNumber</span><spanclass="symbol">.</span><spanclass="method">from</span><spanclass="symbol">(</span><spanclass="param">aBigNumberish</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/bignumber/">BigNumber</a></span><divclass="anchors"></div></div><divclass="body"><p>Returns an instance of a <b>BigNumber</b> for <i>aBigNumberish</i>.</p>
</span></div><aname="/v5/api/utils/bignumber/-%23-BigNumber--methods"></a><aname="/v5/api/utils/bignumber/-%23-BigNumber--BigNumber--methods"></a><aname="/v5/api/utils/bignumber/"></a><h2class="show-anchors"><div>Methods<divclass="anchors"><aclass="self"href="#/v5/api/utils/bignumber/-%23-BigNumber--methods"></a></div></div></h2><p>The BigNumber class is immutable, so no operations can change the value it represents.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">BigNumber</span><spanclass="symbol">.</span><spanclass="method">add</span><spanclass="symbol">(</span><spanclass="param">otherValue</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/bignumber/">BigNumber</a></span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/bignumber.ts#L71">source</a></div></div><divclass="body"><p>Returns a BigNumber with the value of <i>BigNumber</i><b>+</b><i>otherValue</i>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">BigNumber</span><spanclass="symbol">.</span><spanclass="method">sub</span><spanclass="symbol">(</span><spanclass="param">otherValue</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/bignumber/">BigNumber</a></span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/bignumber.ts#L75">source</a></div></div><divclass="body"><p>Returns a BigNumber with the value of <i>BigNumber</i><b>-</b><i>otherValue</i>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">BigNumber</span><spanclass="symbol">.</span><spanclass="method">mul</span><spanclass="symbol">(</span><spanclass="param">otherValue</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/bignumber/">BigNumber</a></span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/bignumber.ts#L87">source</a></div></div><divclass="body"><p>Returns a BigNumber with the value of <i>BigNumber</i><b>×</b><i>otherValue</i>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">BigNumber</span><spanclass="symbol">.</span><spanclass="method">div</span><spanclass="symbol">(</span><spanclass="param">divisor</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/bignumber/">BigNumber</a></span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/bignumber.ts#L79">source</a></div></div><divclass="body"><p>Returns a BigNumber with the value of <i>BigNumber</i><b>÷</b><i>divisor</i>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">BigNumber</span><spanclass="symbol">.</span><spanclass="method">mod</span><spanclass="symbol">(</span><spanclass="param">divisor</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/bignumber/">BigNumber</a></span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/bignumber.ts#L91">source</a></div></div><divclass="body"><p>Returns a BigNumber with the value of the <b>remainder</b> of <i>BigNumber</i>÷<i>divisor</i>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">BigNumber</span><spanclass="symbol">.</span><spanclass="method">pow</span><spanclass="symbol">(</span><spanclass="param">exponent</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/bignumber/">BigNumber</a></span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/bignumber.ts#L99">source</a></div></div><divclass="body"><p>Returns a BigNumber with the value of <i>BigNumber</i> to the power of <i>exponent</i>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">BigNumber</span><spanclass="symbol">.</span><spanclass="method">abs</span><spanclass="symbol">(</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/bignumber/">BigNumber</a></span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/bignumber.ts#L64">source</a></div></div><divclass="body"><p>Returns a BigNumber with the absolute value of <i>BigNumber</i>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">BigNumber</span><spanclass="symbol">.</span><spanclass="method">mask</span><spanclass="symbol">(</span><spanclass="param">bitcount</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/bignumber/">BigNumber</a></span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/bignumber.ts#L131">source</a></div></div><divclass="body"><p>Returns a BigNumber with the value of <i>BigNumber</i> with bits beyond the <i>bitcount</i> least significant bits set to zero.</p>
</div></div><aname="/v5/api/utils/bignumber/-%23-BigNumber--BigNumber--methods--two-s-compliment"></a><aname="/v5/api/utils/bignumber/"></a><h3class="show-anchors"><div>Two's Compliment<divclass="anchors"><aclass="self"href="#/v5/api/utils/bignumber/-%23-BigNumber--BigNumber--methods--two-s-compliment"></a></div></div></h3><p><ahref="https://en.wikipedia.org/wiki/Two%27s_complement">Two's Complicment</a> is an elegant method used to encode and decode fixed-width signed values while efficiently preserving mathematic operations. Most users will not need to interact with these.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">BigNumber</span><spanclass="symbol">.</span><spanclass="method">fromTwos</span><spanclass="symbol">(</span><spanclass="param">bitwidth</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/bignumber/">BigNumber</a></span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/bignumber.ts#L56">source</a></div></div><divclass="body"><p>Returns a BigNumber with the value of <i>BigNumber</i> converted from twos-compliment with <i>bitwidth</i>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">BigNumber</span><spanclass="symbol">.</span><spanclass="method">toTwos</span><spanclass="symbol">(</span><spanclass="param">bitwidth</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/bignumber/">BigNumber</a></span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/bignumber.ts#L60">source</a></div></div><divclass="body"><p>Returns a BigNumber with the value of <i>BigNumber</i> converted to twos-compliment with <i>bitwidth</i>.</p>
</div></div><aname="/v5/api/utils/bignumber/-%23-BigNumber--BigNumber--methods--comparison-and-equivalence"></a><aname="/v5/api/utils/bignumber/"></a><h3class="show-anchors"><div>Comparison and Equivalence<divclass="anchors"><aclass="self"href="#/v5/api/utils/bignumber/-%23-BigNumber--BigNumber--methods--comparison-and-equivalence"></a></div></div></h3>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">BigNumber</span><spanclass="symbol">.</span><spanclass="method">eq</span><spanclass="symbol">(</span><spanclass="param">otherValue</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">boolean</span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/bignumber.ts#L152">source</a></div></div><divclass="body"><p>Returns true if and only if the value of <i>BigNumber</i> is equal to <i>otherValue</i>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">BigNumber</span><spanclass="symbol">.</span><spanclass="method">lt</span><spanclass="symbol">(</span><spanclass="param">otherValue</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">boolean</span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/bignumber.ts#L156">source</a></div></div><divclass="body"><p>Returns true if and only if the value of <i>BigNumber</i><b><</b><i>otherValue</i>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">BigNumber</span><spanclass="symbol">.</span><spanclass="method">lte</span><spanclass="symbol">(</span><spanclass="param">otherValue</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">boolean</span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/bignumber.ts#L160">source</a></div></div><divclass="body"><p>Returns true if and only if the value of <i>BigNumber</i><b>≤</b><i>otherValue</i>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">BigNumber</span><spanclass="symbol">.</span><spanclass="method">gt</span><spanclass="symbol">(</span><spanclass="param">otherValue</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">boolean</span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/bignumber.ts#L164">source</a></div></div><divclass="body"><p>Returns true if and only if the value of <i>BigNumber</i><b>></b><i>otherValue</i>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">BigNumber</span><spanclass="symbol">.</span><spanclass="method">gte</span><spanclass="symbol">(</span><spanclass="param">otherValue</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">boolean</span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/bignumber.ts#L168">source</a></div></div><divclass="body"><p>Returns true if and only if the value of <i>BigNumber</i><b>≥</b><i>otherValue</i>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">BigNumber</span><spanclass="symbol">.</span><spanclass="method">isZero</span><spanclass="symbol">(</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">boolean</span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/bignumber.ts#L176">source</a></div></div><divclass="body"><p>Returns true if and only if the value of <i>BigNumber</i> is zero.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">BigNumber</span><spanclass="symbol">.</span><spanclass="method">toNumber</span><spanclass="symbol">(</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">number</span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/bignumber.ts#L180">source</a></div></div><divclass="body"><p>Returns the value of <i>BigNumber</i> as a JavaScript value.</p>
<p>This will <b>throw an error</b> if the value is greater than or equal to <i>Number.MAX_SAFE_INTEGER</i> or less than or equal to <i>Number.MIN_SAFE_INTEGER</i>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">BigNumber</span><spanclass="symbol">.</span><spanclass="method">toString</span><spanclass="symbol">(</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">string</span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/bignumber.ts#L189">source</a></div></div><divclass="body"><p>Returns the value of <i>BigNumber</i> as a base-10 string.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">BigNumber</span><spanclass="symbol">.</span><spanclass="method">toHexString</span><spanclass="symbol">(</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>></span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/bignumber.ts#L197">source</a></div></div><divclass="body"><p>Returns the value of <i>BigNumber</i> as a base-16, <codeclass="inline">0x</code>-prefixed <ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">BigNumnber</span><spanclass="symbol">.</span><spanclass="method">isBigNumber</span><spanclass="symbol">(</span><spanclass="param">object</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">boolean</span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/bignumber.ts#L250">source</a></div></div><divclass="body"><p>Returns true if and only if the <i>object</i> is a BigNumber object.</p>
</span></div><aname="/v5/api/utils/bignumber/-%23-BigNumber--notes"></a><aname="/v5/api/utils/bignumber/-%23-BigNumber--BigNumber--notes"></a><aname="/v5/api/utils/bignumber/"></a><h2class="show-anchors"><div>Notes<divclass="anchors"><aclass="self"href="#/v5/api/utils/bignumber/-%23-BigNumber--notes"></a></div></div></h2><p>This section is a for a couple of questions that come up frequently.</p>
<aname="/v5/api/utils/bignumber/-%23-BigNumber--notes-safenumbers"></a><aname="/v5/api/utils/bignumber/-%23-BigNumber--BigNumber--notes--BigNumber--notes-safenumbers"></a><aname="/v5/api/utils/bignumber/"></a><h3class="show-anchors"><div>Why can't I just use numbers?<divclass="anchors"><aclass="self"href="#/v5/api/utils/bignumber/-%23-BigNumber--notes-safenumbers"></a></div></div></h3><p>The first problem many encounter when dealing with Ethereum is the concept of numbers. Most common currencies are broken down with very little granularity. For example, there are only 100 cents in a single dollar. However, there are 10<sup>18</sup><b>wei</b> in a single <b>ether</b>.</p>
<p>JavaScript uses <ahref="https://en.wikipedia.org/wiki/Double-precision_floating-point_format">IEEE 754 double-precision binary floating point</a> numbers to represent numeric values. As a result, there are <i>holes</i> in the integer set after 9,007,199,254,740,991; which is problematic for <i>Ethereum</i> because that is only around 0.009 ether (in wei), which means any value over that will begin to experience rounding errors.</p>
<p>To demonstrate how this may be an issue in your code, consider:</p>
<p>The functions <ahref="#/v5/api/utils/display-logic/-%23-utils-parseEther">parseEther( etherString )</a> and <ahref="#/v5/api/utils/display-logic/-%23-utils-formatEther">formatEther( wei )</a> can be used to convert between string representations, which are displayed to or entered by the user and Big Number representations which can have mathematical operations handled safely.</p>
<aname="/v5/api/utils/bignumber/-%23-BigNumber--BigNumber--notes--why-not-bignumber-js-bn-js-bigdecimal-etc"></a><aname="/v5/api/utils/bignumber/"></a><h3class="show-anchors"><div>Why not BigNumber.js, BN.js, BigDecimal, etc?<divclass="anchors"><aclass="self"href="#/v5/api/utils/bignumber/-%23-BigNumber--BigNumber--notes--why-not-bignumber-js-bn-js-bigdecimal-etc"></a></div></div></h3><p>Everyone has their own favourite Big Number library, and once someone has choosen one, it becomes part of their identity, like their editor, vi vs emacs. There are over 100 Big Number libraries on <ahref="https://www.npmjs.com/search?q=bignumber">npm</a>.</p>
<p>One of the biggest differences between the Ethers <ahref="#/v5/api/utils/bignumber/">BigNumber</a> object and other libraries is that it is immutable, which is very important when dealing with the asynchronous nature of the blockchain.</p>
<p>Capturing the value is not safe in async functions, so immutability protects us from easy to make mistakes, which is not possible on the low-level library's objects which supports myriad in-place operations.</p>
<p>Second, the Ethers <ahref="#/v5/api/utils/bignumber/">BigNumber</a> provides all the functionality required internally and should generally be sufficient for most developers while not exposing some of the more advanced and rare functionality. So it will be eaiser to swap out the underlying library without impacting consumers.</p>
<p>For example, if <ahref="https://www.npmjs.com/package/bn.js">BN.js</a> was exposed, someone may use the greatest-common-denominator functions, which would then be functionality the replacing library should also provide to ensure anyone depending on that functionality is not broken.</p>
<aname="/v5/api/utils/bignumber/-%23-BigNumber--BigNumber--notes--why-bn-js"></a><aname="/v5/api/utils/bignumber/"></a><h3class="show-anchors"><div>Why BN.js??<divclass="anchors"><aclass="self"href="#/v5/api/utils/bignumber/-%23-BigNumber--BigNumber--notes--why-bn-js"></a></div></div></h3><p>The reason why <ahref="https://www.npmjs.com/package/bn.js">BN.js</a> is used internally as the big number is because that is the library used by <ahref="https://www.npmjs.com/package/elliptic">elliptic</a>.</p>
<p>Therefore it <b>must</b> be included regardless, so we leverage that library rather than adding another Big Number library, which would mean two different libraries offering the same functionality.</p>
<p>This has saved about 85kb (80% of this library size) of library size over other libraries which include separate Big Number libraries for various purposes.</p>
<aname="/v5/api/utils/bignumber/-%23-BigNumber--BigNumber--notes--allow-us-to-set-a-global-big-number-library"></a><aname="/v5/api/utils/bignumber/"></a><h3class="show-anchors"><div>Allow us to set a global Big Number library?<divclass="anchors"><aclass="self"href="#/v5/api/utils/bignumber/-%23-BigNumber--BigNumber--notes--allow-us-to-set-a-global-big-number-library"></a></div></div></h3><p>Another comment that comes up frequently is tha desire to specify a global user-defined Big Number library, which all functions would return.</p>
<p>This becomes problematic since your code may live along side other libraries or code that use Ethers. In fact, even Ethers uses a lot of the public functions internally.</p>
<p>If you, for example, used a library that used <codeclass="inline">a.plus(b)</code> instead of <codeclass="inline">a.add(b)</code>, this would break Ethers when it tries to compute fees internally, and other libraries likely have similar logic.</p>
<p>But, the <ahref="#/v5/api/utils/bignumber/">BigNumber</a> prototype is exposed, so you can always add a <codeclass="inline">toMyCustomBigNumber()</code> method to all <ahref="#/v5/api/utils/bignumber/">BigNumber</a>'s globally which is safe.</p>
<divclass="page-separator"></div><aname="/v5/api/utils/bytes/-%23-byte-manipulation"></a><aname="/v5/api/utils/bytes/"></a><h1class="show-anchors"><div>Byte Manipulation<divclass="anchors"><aclass="self"href="#/v5/api/utils/bytes/-%23-byte-manipulation"></a></div></div></h1><p>Tra la la...</p>
<aname="/v5/api/utils/bytes/-%23-Bytes"></a><aname="/v5/api/utils/bytes/-%23-byte-manipulation--types--Bytes"></a><aname="/v5/api/utils/bytes/"></a><h3class="show-anchors"><div>Bytes<divclass="anchors"><aclass="self"href="#/v5/api/utils/bytes/-%23-Bytes"></a></div></div></h3><p>A <b>Bytes</b> is any object which is an <ahref="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array">Array</a> or <ahref="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray">TypedArray</a> with each value in the valid byte range (i.e. between 0 and 255 inclusive), or is an Object with a <codeclass="inline">length</code> property where each indexed property is in the valid byte range.</p>
<aname="/v5/api/utils/bytes/-%23-BytesLike"></a><aname="/v5/api/utils/bytes/-%23-byte-manipulation--types--BytesLike"></a><aname="/v5/api/utils/bytes/"></a><h3class="show-anchors"><div>BytesLike<divclass="anchors"><aclass="self"href="#/v5/api/utils/bytes/-%23-BytesLike"></a></div></div></h3><p>A <b>BytesLike</b> can be either a <ahref="#/v5/api/utils/bytes/-%23-Bytes">Bytes</a> or a <ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>.</p>
<aname="/v5/api/utils/bytes/-%23-DataHexString"></a><aname="/v5/api/utils/bytes/-%23-byte-manipulation--types--DataHexString"></a><aname="/v5/api/utils/bytes/"></a><h3class="show-anchors"><div>DataHexString<divclass="anchors"><aclass="self"href="#/v5/api/utils/bytes/-%23-DataHexString"></a></div></div></h3><p>A <b>DataHexstring</b> is identical to a <ahref="#/v5/api/utils/bytes/-%23-HexString">HexString</a> except that it has an even number of nibbles, and therefore is a valid representation of binary data as a string.</p>
<aname="/v5/api/utils/bytes/-%23-HexString"></a><aname="/v5/api/utils/bytes/-%23-byte-manipulation--types--HexString"></a><aname="/v5/api/utils/bytes/"></a><h3class="show-anchors"><div>HexString<divclass="anchors"><aclass="self"href="#/v5/api/utils/bytes/-%23-HexString"></a></div></div></h3><p>A <b>Hexstring</b> is a string which has a <codeclass="inline">0x</code> prefix followed by any number of nibbles (i.e. case-insensitive hexidecumal characters, <codeclass="inline">0-9</code> and <codeclass="inline">a-f</code>).</p>
<aname="/v5/api/utils/bytes/-%23-Signature"></a><aname="/v5/api/utils/bytes/-%23-byte-manipulation--types--Signature"></a><aname="/v5/api/utils/bytes/"></a><h3class="show-anchors"><div>Signature<divclass="anchors"><aclass="self"href="#/v5/api/utils/bytes/-%23-Signature"></a></div></div></h3><p><ul><li><b>r</b> and <b>s</b> --- The x co-ordinate of <b>r</b> and the <b>s</b> value of the signature </li><li><b>v</b> --- The parity of the y co-ordinate of <b>r</b></li><li><b>_vs</b> --- The <ahref="https://eips.ethereum.org/EIPS/eip-2098">compact representation</a> of the <b>s</b> and <b>v</b></li><li><b>recoveryParam</b> --- The normalized (i.e. 0 or 1) value of <b>v</b></li></ul></p>
<aname="/v5/api/utils/bytes/-%23-signature-raw"></a><aname="/v5/api/utils/bytes/-%23-byte-manipulation--types--signature-raw"></a><aname="/v5/api/utils/bytes/"></a><h3class="show-anchors"><div>Raw Signature<spanclass="inherits"> inherits string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a><65>></span><divclass="anchors"><aclass="self"href="#/v5/api/utils/bytes/-%23-signature-raw"></a></div></div></h3><p>A <b>Raw Signature</b> is a common Signature format where the r, s and v are concanenated into a 65 byte (130 nibble) <ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>.</p>
<aname="/v5/api/utils/bytes/-%23-SignatureLike"></a><aname="/v5/api/utils/bytes/-%23-byte-manipulation--types--SignatureLike"></a><aname="/v5/api/utils/bytes/"></a><h3class="show-anchors"><div>SignatureLike<divclass="anchors"><aclass="self"href="#/v5/api/utils/bytes/-%23-SignatureLike"></a></div></div></h3><p>A <b>SignatureLike</b> is similar to a <ahref="#/v5/api/utils/bytes/-%23-Signature">Signature</a>, except redundant properties may be omitted or it may be a <ahref="#/v5/api/utils/bytes/-%23-signature-raw">Raw Signature</a>.</p>
<p>For example, if <b>_vs</b> is specified, <b>s</b> and <b>v</b> may be omitted. Likewise, if <b>recoveryParam</b> is provided, <b>v</b> may be omitted (as in these cases the missing values can be computed).</p>
<aname="/v5/api/utils/bytes/-%23-utils-isBytes"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="method">isBytes</span><spanclass="symbol">(</span><spanclass="param">object</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">boolean</span><divclass="anchors"><aclass="self"href="#/v5/api/utils/bytes/-%23-utils-isBytes"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/bytes/src.ts/index.ts#L73">source</a></div></div><divclass="body"><p>Returns true if and only if <i>object</i> is a valid <ahref="#/v5/api/utils/bytes/-%23-Bytes">Bytes</a>.</p>
</div></div><aname="/v5/api/utils/bytes/-%23-utils-isBytesLike"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="method">isBytesLike</span><spanclass="symbol">(</span><spanclass="param">object</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">boolean</span><divclass="anchors"><aclass="self"href="#/v5/api/utils/bytes/-%23-utils-isBytesLike"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/bytes/src.ts/index.ts#L69">source</a></div></div><divclass="body"><p>Returns true if and only if <i>object</i> is a <ahref="#/v5/api/utils/bytes/-%23-Bytes">Bytes</a> or <ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>.</p>
</div></div><aname="/v5/api/utils/bytes/-%23-utils-isHexString"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="method">isHexString</span><spanclass="symbol">(</span><spanclass="param">object</span><spanclass="symbol">,</span><spanclass="symbol">[</span><spanclass="param">length</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">boolean</span><divclass="anchors"><aclass="self"href="#/v5/api/utils/bytes/-%23-utils-isHexString"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/bytes/src.ts/index.ts#L184">source</a></div></div><divclass="body"><p>Returns true if and only if <i>object</i> is a valid hex string. If <i>length</i> is specified and <i>object</i> is not a valid <ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a> of <i>length</i> bytes, an InvalidArgument error is thrown.</p>
</div></div><aname="/v5/api/utils/bytes/-%23-byte-manipulation--converting-between-arrays-and-hexstrings"></a><aname="/v5/api/utils/bytes/"></a><h2class="show-anchors"><div>Converting between Arrays and Hexstrings<divclass="anchors"><aclass="self"href="#/v5/api/utils/bytes/-%23-byte-manipulation--converting-between-arrays-and-hexstrings"></a></div></div></h2>
<aname="/v5/api/utils/bytes/-%23-utils-arrayify"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="method">arrayify</span><spanclass="symbol">(</span><spanclass="param">DataHexStringOrArrayish</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">options</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Uint8Array</span><divclass="anchors"><aclass="self"href="#/v5/api/utils/bytes/-%23-utils-arrayify"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/bytes/src.ts/index.ts#L91">source</a></div></div><divclass="body"><p>Converts <i>DataHexStringOrArrayish</i> to a Uint8Array.</p>
</div></div><aname="/v5/api/utils/bytes/-%23-utils-hexlify"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="method">hexlify</span><spanclass="symbol">(</span><spanclass="param">hexstringOrArrayish</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>></span><divclass="anchors"><aclass="self"href="#/v5/api/utils/bytes/-%23-utils-hexlify"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/bytes/src.ts/index.ts#L194">source</a></div></div><divclass="body"><p>Converts <i>hexstringOrArrayish</i> to a <ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>.</p>
</div></div><aname="/v5/api/utils/bytes/-%23-utils-hexValue"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="method">hexValue</span><spanclass="symbol">(</span><spanclass="param">aBigNumberish</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/bytes/-%23-HexString">HexString</a>></span><divclass="anchors"><aclass="self"href="#/v5/api/utils/bytes/-%23-utils-hexValue"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/bytes/src.ts/index.ts#L287">source</a></div></div><divclass="body"><p>Converts <i>aBigNumberish</i> to a <ahref="#/v5/api/utils/bytes/-%23-HexString">HexString</a>, with no <u>unnecessary</u> leading zeros.</p>
<aname="/v5/api/utils/bytes/-%23-utils-concat"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="method">concat</span><spanclass="symbol">(</span><spanclass="param">arrayOfBytesLike</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Uint8Array</span><divclass="anchors"><aclass="self"href="#/v5/api/utils/bytes/-%23-utils-concat"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/bytes/src.ts/index.ts#L140">source</a></div></div><divclass="body"><p>Concatenates all the <ahref="#/v5/api/utils/bytes/-%23-BytesLike">BytesLike</a> in <i>arrayOfBytesLike</i> into a single Uint8Array.</p>
</div></div><aname="/v5/api/utils/bytes/-%23-utils-stripZeros"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="method">stripZeros</span><spanclass="symbol">(</span><spanclass="param">aBytesLike</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Uint8Array</span><divclass="anchors"><aclass="self"href="#/v5/api/utils/bytes/-%23-utils-stripZeros"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/bytes/src.ts/index.ts#L154">source</a></div></div><divclass="body"><p>Returns a Uint8Array with all leading <codeclass="inline">0</code> bytes of <i>aBtyesLike</i> removed.</p>
</div></div><aname="/v5/api/utils/bytes/-%23-utils-zeroPad"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="method">zeroPad</span><spanclass="symbol">(</span><spanclass="param">aBytesLike</span><spanclass="symbol">,</span><spanclass="param">length</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Uint8Array</span><divclass="anchors"><aclass="self"href="#/v5/api/utils/bytes/-%23-utils-zeroPad"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/bytes/src.ts/index.ts#L171">source</a></div></div><divclass="body"><p>Retutns a Uint8Array of the data in <i>aBytesLike</i> with <codeclass="inline">0</code> bytes prepended to <i>length</i> bytes long.</p>
<aname="/v5/api/utils/bytes/-%23-utils-hexConcat"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="method">hexConcat</span><spanclass="symbol">(</span><spanclass="param">arrayOfBytesLike</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>></span><divclass="anchors"><aclass="self"href="#/v5/api/utils/bytes/-%23-utils-hexConcat"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/bytes/src.ts/index.ts#L279">source</a></div></div><divclass="body"><p>Concatenates all the <ahref="#/v5/api/utils/bytes/-%23-BytesLike">BytesLike</a> in <i>arrayOfBytesLike</i> into a single <ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a></p>
</div></div><aname="/v5/api/utils/bytes/-%23-utils-hexDataLength"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="method">hexDataLength</span><spanclass="symbol">(</span><spanclass="param">aBytesLike</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>></span><divclass="anchors"><aclass="self"href="#/v5/api/utils/bytes/-%23-utils-hexDataLength"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/bytes/src.ts/index.ts#L253">source</a></div></div><divclass="body"><p>Returns the length (in bytes) of <i>aBytesLike</i>.</p>
</div></div><aname="/v5/api/utils/bytes/-%23-utils-hexDataSlice"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="method">hexDataSlice</span><spanclass="symbol">(</span><spanclass="param">aBytesLike</span><spanclass="symbol">,</span><spanclass="param">offset</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">endOffset</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>></span><divclass="anchors"><aclass="self"href="#/v5/api/utils/bytes/-%23-utils-hexDataSlice"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/bytes/src.ts/index.ts#L263">source</a></div></div><divclass="body"><p>Returns a <ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a> representation of a slice of <i>aBytesLike</i>, from <i>offset</i> (in bytes) to <i>endOffset</i> (in bytes). If <i>endOffset</i> is omitted, the length of <i>aBytesLike</i> is used.</p>
</div></div><aname="/v5/api/utils/bytes/-%23-utils-hexStripZeros"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="method">hexStripZeros</span><spanclass="symbol">(</span><spanclass="param">aBytesLike</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/bytes/-%23-HexString">HexString</a>></span><divclass="anchors"><aclass="self"href="#/v5/api/utils/bytes/-%23-utils-hexStripZeros"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/bytes/src.ts/index.ts#L293">source</a></div></div><divclass="body"><p>Returns a <ahref="#/v5/api/utils/bytes/-%23-HexString">HexString</a> representation of <i>aBytesLike</i> with all leading zeros removed.</p>
</div></div><aname="/v5/api/utils/bytes/-%23-utils-hexZeroPad"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="method">hexZeroPad</span><spanclass="symbol">(</span><spanclass="param">aBytesLike</span><spanclass="symbol">,</span><spanclass="param">length</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>></span><divclass="anchors"><aclass="self"href="#/v5/api/utils/bytes/-%23-utils-hexZeroPad"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/bytes/src.ts/index.ts#L305">source</a></div></div><divclass="body"><p>Returns a <ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a> representation of <i>aBytesLike</i> padded to <i>length</i> bytes.</p>
<aname="/v5/api/utils/bytes/-%23-utils-joinSignature"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="method">joinSignature</span><spanclass="symbol">(</span><spanclass="param">aSignatureLike</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/bytes/-%23-signature-raw">RawSignature</a>></span><divclass="anchors"><aclass="self"href="#/v5/api/utils/bytes/-%23-utils-joinSignature"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/bytes/src.ts/index.ts#L442">source</a></div></div><divclass="body"><p>Return the raw-format of <i>aSignaturelike</i>, which is 65 bytes (130 nibbles) long, concatenating the <b>r</b>, <b>s</b> and (normalized) <b>v</b> of a Signature.</p>
</div></div><aname="/v5/api/utils/bytes/-%23-utils-splitSignature"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="method">splitSignature</span><spanclass="symbol">(</span><spanclass="param">aSignatureLikeOrBytesLike</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/bytes/-%23-Signature">Signature</a></span><divclass="anchors"><aclass="self"href="#/v5/api/utils/bytes/-%23-utils-splitSignature"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/bytes/src.ts/index.ts#L323">source</a></div></div><divclass="body"><p>Return the full expanded-format of <i>aSignaturelike</i> or a raw-format <ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>. Any missing properties will be computed.</p>
<aname="/v5/api/utils/bytes/-%23-utils-randomBytes"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="method">randomBytes</span><spanclass="symbol">(</span><spanclass="param">length</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Uint8Array</span><divclass="anchors"><aclass="self"href="#/v5/api/utils/bytes/-%23-utils-randomBytes"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/random/src.ts/index.ts#L9">source</a></div></div><divclass="body"><p>Return a new Uint8Array of <i>length</i> random bytes.</p>
</div></div><aname="/v5/api/utils/bytes/-%23-utils-shuffled"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="method">shuffled</span><spanclass="symbol">(</span><spanclass="param">array</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Array< any ></span><divclass="anchors"><aclass="self"href="#/v5/api/utils/bytes/-%23-utils-shuffled"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/random/src.ts/shuffle.ts#L3">source</a></div></div><divclass="body"><p>Return a copy of <i>array</i> shuffled using <ahref="https://en.wikipedia.org/wiki/Fisher-Yates_shuffle">Fisher-Yates Shuffle</a>.</p>
<aname="/v5/api/utils/constants/-%23-constants-AddressZero"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">constants</span><spanclass="symbol">.</span><spanclass="method">AddressZero</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/address/-%23-address">Address</a>></span><divclass="anchors"><aclass="self"href="#/v5/api/utils/constants/-%23-constants-AddressZero"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/constants/src.ts/index.ts#L5">source</a></div></div><divclass="body"><p>The Address Zero, which is 20 bytes (40 nibbles) of zero.</p>
</div></div><aname="/v5/api/utils/constants/-%23-constants-HashZero"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">constants</span><spanclass="symbol">.</span><spanclass="method">HashZero</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 >></span><divclass="anchors"><aclass="self"href="#/v5/api/utils/constants/-%23-constants-HashZero"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/constants/src.ts/index.ts#L6">source</a></div></div><divclass="body"><p>The Hash Zero, which is 32 bytes (64 nibbles) of zero.</p>
</div></div><aname="/v5/api/utils/constants/-%23-constants-WeiPerEther"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">constants</span><spanclass="symbol">.</span><spanclass="method">WeiPerEther</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/bignumber/">BigNumber</a></span><divclass="anchors"><aclass="self"href="#/v5/api/utils/constants/-%23-constants-WeiPerEther"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/constants/src.ts/index.ts#L15">source</a></div></div><divclass="body"><p>The BigNumber value representing <codeclass="inline">"1000000000000000000"</code>, which is the number of Wei per Ether.</p>
</div></div><aname="/v5/api/utils/constants/-%23-constants-MaxUint256"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">constants</span><spanclass="symbol">.</span><spanclass="method">MaxUint256</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/bignumber/">BigNumber</a></span><divclass="anchors"><aclass="self"href="#/v5/api/utils/constants/-%23-constants-MaxUint256"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/constants/src.ts/index.ts#L16">source</a></div></div><divclass="body"><p>The BigNumber value representing the maximum <codeclass="inline">uint256</code> value.</p>
</div></div><divclass="page-separator"></div><aname="/v5/api/utils/display-logic/-%23-display-logic-and-input"></a><aname="/v5/api/utils/display-logic/"></a><h1class="show-anchors"><div>Display Logic and Input<divclass="anchors"><aclass="self"href="#/v5/api/utils/display-logic/-%23-display-logic-and-input"></a></div></div></h1><p>When creating an Application, it is useful to convert between user-friendly strings (usually displaying <b>ether</b>) and the machine-readable values that contracts and maths depend on (usually in <b>wei</b>).</p>
<p>For example, a Wallet may specify the balance in ether, and gas prices in gwei for the User Interface, but when sending a transaction, both must be specified in wei.</p>
<p>The <ahref="#/v5/api/utils/display-logic/-%23-unit-conversion">parseUnits</a> will parse a string representing ether, such as <codeclass="inline">1.1</code> into a <ahref="#/v5/api/utils/bignumber/">BigNumber</a> in wei, and is useful when a user types in a value, such as sending 1.1 ether.</p>
<p>The <ahref="#/v5/api/utils/display-logic/-%23-unit-conversion">formatUnits</a> will format a <ahref="#/v5/api/utils/bignumber/-%23-BigNumberish">BigNumberish</a> into a string, which is useful when displaying a balance.</p>
<aname="/v5/api/utils/display-logic/-%23-display-logic-and-input--units--decimal-count"></a><aname="/v5/api/utils/display-logic/"></a><h3class="show-anchors"><div>Decimal Count<divclass="anchors"><aclass="self"href="#/v5/api/utils/display-logic/-%23-display-logic-and-input--units--decimal-count"></a></div></div></h3><p>A <b>Unit</b> can be specified as an number, which indicates the number of decimal places that should be used.</p>
<p><b>Examples:</b></p>
<p><ul><li>1 ether in wei, has <b>18</b> decimal places (i.e. 1 ether represents 10<sup>18</sup> wei) </li><li>1 bitcoin in Satoshi, has <b>8</b> decimal places (i.e. 1 bitcoin represents 10<sup>8</sup> satoshi) </li></ul></p>
<aname="/v5/api/utils/display-logic/-%23-display-logic-and-input--units--named-units"></a><aname="/v5/api/utils/display-logic/"></a><h3class="show-anchors"><div>Named Units<divclass="anchors"><aclass="self"href="#/v5/api/utils/display-logic/-%23-display-logic-and-input--units--named-units"></a></div></div></h3><p>There are also several common <b>Named Units</b>, in which case their name (as a string) may be used.</p>
<aname="/v5/api/utils/display-logic/-%23-utils-commify"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="method">commify</span><spanclass="symbol">(</span><spanclass="param">value</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">string</span><divclass="anchors"><aclass="self"href="#/v5/api/utils/display-logic/-%23-utils-commify"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/units/src.ts/index.ts#L23">source</a></div></div><divclass="body"><p>Returns a string with value grouped by 3 digits, separated by <codeclass="inline">,</code>.</p>
<aname="/v5/api/utils/display-logic/-%23-utils-formatUnits"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="method">formatUnits</span><spanclass="symbol">(</span><spanclass="param">value</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">unit</span> = "<spanclass="param">ether</span>" <spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">string</span><divclass="anchors"><aclass="self"href="#/v5/api/utils/display-logic/-%23-utils-formatUnits"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/units/src.ts/index.ts#L61">source</a></div></div><divclass="body"><p>Returns a string representation of <i>value</i> formatted with <i>unit</i> digits (if it is a number) or to the unit specified (if a string).</p>
</div></div><aname="/v5/api/utils/display-logic/-%23-utils-parseUnits"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="method">parseUnits</span><spanclass="symbol">(</span><spanclass="param">value</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">unit</span> = "<spanclass="param">ether</span>" <spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/bignumber/">BigNumber</a></span><divclass="anchors"><aclass="self"href="#/v5/api/utils/display-logic/-%23-utils-parseUnits"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/units/src.ts/index.ts#L69">source</a></div></div><divclass="body"><p>Returns a <ahref="#/v5/api/utils/bignumber/">BigNumber</a> representation of <i>value</i>, parsed with <i>unit</i> digits (if it is a number) or from the unit specified (if a string).</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="path">base58</span><spanclass="symbol">.</span><spanclass="method">decode</span><spanclass="symbol">(</span><spanclass="param">textData</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Uin8Array</span><divclass="anchors"></div></div><divclass="body"><p>Return a typed Uint8Array representation of <i>textData</i> decoded using base-58 encoding.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="path">base58</span><spanclass="symbol">.</span><spanclass="method">encode</span><spanclass="symbol">(</span><spanclass="param">aBytesLike</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">string</span><divclass="anchors"></div></div><divclass="body"><p>Return <i>aBytesLike</i> encoded as a string using the base-58 encoding.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="path">base64</span><spanclass="symbol">.</span><spanclass="method">decode</span><spanclass="symbol">(</span><spanclass="param">textData</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Uin8Array</span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/base64/src.ts/index.ts#L6">source</a></div></div><divclass="body"><p>Return a typed Uint8Array representation of <i>textData</i> decoded using base-64 encoding.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="path">base64</span><spanclass="symbol">.</span><spanclass="method">encode</span><spanclass="symbol">(</span><spanclass="param">aBytesLike</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">string</span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/base64/src.ts/index.ts#L10">source</a></div></div><divclass="body"><p>Return <i>aBytesLike</i> encoded as a string using the base-64 encoding.</p>
</div></div><aname="/v5/api/utils/encoding/-%23-rlp--methods"></a><aname="/v5/api/utils/encoding/-%23-encoding--rlp--methods"></a><aname="/v5/api/utils/encoding/"></a><h2class="show-anchors"><div>Recursive-Length Prefix<divclass="anchors"><aclass="self"href="#/v5/api/utils/encoding/-%23-rlp--methods"></a></div></div></h2><p>The <ahref="https://github.com/ethereum/wiki/wiki/RLP">Recursive Length Prefix</a> encoding is used throughout Ethereum to serialize nested structures of Arrays and data.</p>
<aname="/v5/api/utils/encoding/-%23-utils-rlpEncode"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="path">RLP</span><spanclass="symbol">.</span><spanclass="method">encode</span><spanclass="symbol">(</span><spanclass="param">dataObject</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>></span><divclass="anchors"><aclass="self"href="#/v5/api/utils/encoding/-%23-utils-rlpEncode"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/rlp/src.ts/index.ts#L67">source</a></div></div><divclass="body"><p>Encode a structured Data Object into its RLP-encoded representation.</p>
</div></div><aname="/v5/api/utils/encoding/-%23-utils.rlpDecode"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="path">RLP</span><spanclass="symbol">.</span><spanclass="method">decode</span><spanclass="symbol">(</span><spanclass="param">aBytesLike</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/encoding/-%23-rlp--dataobject">DataObject</a></span><divclass="anchors"><aclass="self"href="#/v5/api/utils/encoding/-%23-utils.rlpDecode"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/rlp/src.ts/index.ts#L147">source</a></div></div><divclass="body"><p>Decode an RLP-encoded <i>aBytesLike</i> into its structured Data Object.</p>
<p>All Data components will be returned as a <ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>.</p>
</div></div><aname="/v5/api/utils/encoding/-%23-rlp--dataobject"></a><aname="/v5/api/utils/encoding/-%23-encoding--rlp--methods--rlp--dataobject"></a><aname="/v5/api/utils/encoding/"></a><h3class="show-anchors"><div>Data Object<divclass="anchors"><aclass="self"href="#/v5/api/utils/encoding/-%23-rlp--dataobject"></a></div></div></h3><p>A <b>Data Object</b> is a recursive structure which is used to serialize many internal structures in Ethereum. Each <b>Data Object</b> can either be:</p>
<p><ul><li>Binary Data </li><li>An Array of <b>Data Objects</b> (i.e. this recursively includes Nesting) </li></ul></p>
</div></div><divclass="page-separator"></div><aname="/v5/api/utils/fixednumber/-%23-FixedNumber"></a><aname="/v5/api/utils/fixednumber/-%23-FixedNumber"></a><aname="/v5/api/utils/fixednumber/"></a><h1class="show-anchors"><div>FixedNumber<divclass="anchors"><aclass="self"href="#/v5/api/utils/fixednumber/-%23-FixedNumber"></a></div></div></h1><p>A <b>FixedNumber</b> is a fixed-width (in bits) number with an internal base-10 divisor, which allows it to represent a decimal fractional component.</p>
<aname="/v5/api/utils/fixednumber/-%23-FixedNumber--creating-instances"></a><aname="/v5/api/utils/fixednumber/"></a><h2class="show-anchors"><div>Creating Instances<divclass="anchors"><aclass="self"href="#/v5/api/utils/fixednumber/-%23-FixedNumber--creating-instances"></a></div></div></h2><p>The FixedNumber constructor cannot be called directly. There are several static methods for creating a FixedNumber.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">FixedNumber</span><spanclass="symbol">.</span><spanclass="method">from</span><spanclass="symbol">(</span><spanclass="param">value</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">format</span> = "<spanclass="param">fixed</span>" <spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/fixednumber/">FixedNumber</a></span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/fixednumber.ts#L339">source</a></div></div><divclass="body"><p>Returns an instance of a <b>FixedNumber</b> for <i>value</i> as a <i>format</i>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">FixedNumber</span><spanclass="symbol">.</span><spanclass="method">fromBytes</span><spanclass="symbol">(</span><spanclass="param">aBytesLike</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">format</span> = "<spanclass="param">fixed</span>" <spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/fixednumber/">FixedNumber</a></span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/fixednumber.ts#L321">source</a></div></div><divclass="body"><p>Returns an instance of a <b>FixedNumber</b> for <i>value</i> as a <i>format</i>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">FixedNumber</span><spanclass="symbol">.</span><spanclass="method">fromString</span><spanclass="symbol">(</span><spanclass="param">value</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">format</span> = "<spanclass="param">fixed</span>" <spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/fixednumber/">FixedNumber</a></span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/fixednumber.ts#L297">source</a></div></div><divclass="body"><p>Returns an instance of a <b>FixedNumber</b> for <i>value</i> as a <i>format</i>. The <i>value</i> must not contain more decimals than the <i>format</i> permits.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">FixedNumber</span><spanclass="symbol">.</span><spanclass="method">fromValue</span><spanclass="symbol">(</span><spanclass="param">value</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">decimals</span> = <spanclass="param">0</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">format</span> = "<spanclass="param">fixed</span>" <spanclass="symbol">]</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/fixednumber/">FixedNumber</a></span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/fixednumber.ts#L283">source</a></div></div><divclass="body"><p>Returns an instance of a <b>FixedNumber</b> for <i>value</i> with <i>decimals</i> as a <i>format</i>.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">fixednumber</span><spanclass="symbol">.</span><spanclass="method">format</span><divclass="anchors"></div></div><divclass="body"><p>The <ahref="#/v5/api/utils/fixednumber/-%23-FixedFormat">FixedFormat</a> of <i>fixednumber</i>.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">fixednumber</span><spanclass="symbol">.</span><spanclass="method">addUnsafe</span><spanclass="symbol">(</span><spanclass="param">otherValue</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/fixednumber/">FixedNumber</a></span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/fixednumber.ts#L215">source</a></div></div><divclass="body"><p>Returns a new FixedNumber with the value of <i>fixedvalue</i><b>+</b><i>otherValue</i>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">fixednumber</span><spanclass="symbol">.</span><spanclass="method">subUnsafe</span><spanclass="symbol">(</span><spanclass="param">otherValue</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/fixednumber/">FixedNumber</a></span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/fixednumber.ts#L222">source</a></div></div><divclass="body"><p>Returns a new FixedNumber with the value of <i>fixedvalue</i><b>-</b><i>otherValue</i>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">fixednumber</span><spanclass="symbol">.</span><spanclass="method">mulUnsafe</span><spanclass="symbol">(</span><spanclass="param">otherValue</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/fixednumber/">FixedNumber</a></span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/fixednumber.ts#L229">source</a></div></div><divclass="body"><p>Returns a new FixedNumber with the value of <i>fixedvalue</i><b>×</b><i>otherValue</i>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">fixednumber</span><spanclass="symbol">.</span><spanclass="method">divUnsafe</span><spanclass="symbol">(</span><spanclass="param">otherValue</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/fixednumber/">FixedNumber</a></span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/fixednumber.ts#L236">source</a></div></div><divclass="body"><p>Returns a new FixedNumber with the value of <i>fixedvalue</i><b>÷</b><i>otherValue</i>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">fixednumber</span><spanclass="symbol">.</span><spanclass="method">round</span><spanclass="symbol">(</span><spanclass="symbol">[</span><spanclass="param">decimals</span> = <spanclass="param">0</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/fixednumber/">FixedNumber</a></span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/fixednumber.ts#L244">source</a></div></div><divclass="body"><p>Returns a new FixedNumber with the value of <i>fixedvalue</i> rounded to <i>decimals</i>.</p>
</div></div><aname="/v5/api/utils/fixednumber/-%23-FixedNumber--methods--comparison-and-equivalence"></a><aname="/v5/api/utils/fixednumber/"></a><h3class="show-anchors"><div>Comparison and Equivalence<divclass="anchors"><aclass="self"href="#/v5/api/utils/fixednumber/-%23-FixedNumber--methods--comparison-and-equivalence"></a></div></div></h3>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">FixedNumber</span><spanclass="symbol">.</span><spanclass="method">isZero</span><spanclass="symbol">(</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">boolean</span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/fixednumber.ts#L262">source</a></div></div><divclass="body"><p>Returns true if and only if the value of <i>FixedNumber</i> is zero.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">fixednumber</span><spanclass="symbol">.</span><spanclass="method">toFormat</span><spanclass="symbol">(</span><spanclass="param">format</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/fixednumber/">FixedNumber</a></span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/fixednumber.ts#L278">source</a></div></div><divclass="body"><p>Returns a new FixedNumber with the value of <i>fixedvalue</i> with <i>format</i>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">fixednumber</span><spanclass="symbol">.</span><spanclass="method">toHexString</span><spanclass="symbol">(</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">string</span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/fixednumber.ts#L269">source</a></div></div><divclass="body"><p>Returns a <ahref="#/v5/api/utils/bytes/-%23-HexString">HexString</a> representation of <i>fixednumber</i>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">fixednumber</span><spanclass="symbol">.</span><spanclass="method">toString</span><spanclass="symbol">(</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">string</span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/fixednumber.ts#L267">source</a></div></div><divclass="body"><p>Returns a string representation of <i>fixednumber</i>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">fixednumber</span><spanclass="symbol">.</span><spanclass="method">toUnsafeFloat</span><spanclass="symbol">(</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">float</span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/fixednumber.ts#L276">source</a></div></div><divclass="body"><p>Returns a floating-point JavaScript number value of <i>fixednumber</i>. Due to rounding in JavaScript numbers, the value is only approximate.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">FixedNumber</span><spanclass="symbol">.</span><spanclass="method">isFixedNumber</span><spanclass="symbol">(</span><spanclass="param">value</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">boolean</span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/fixednumber.ts#L360">source</a></div></div><divclass="body"><p>Returns true if and only if <i>value</i> is a <b>FixedNumber</b>.</p>
</div></div><aname="/v5/api/utils/fixednumber/-%23-FixedFormat"></a><aname="/v5/api/utils/fixednumber/-%23-FixedNumber--FixedFormat"></a><aname="/v5/api/utils/fixednumber/"></a><h2class="show-anchors"><div>FixedFormat<divclass="anchors"><aclass="self"href="#/v5/api/utils/fixednumber/-%23-FixedFormat"></a></div></div></h2><p>A <b>FixedFormat</b> is a simple object which represents a decimal (base-10) Fixed-Point data representation. Usually using this class directly is uneccessary, as passing in a <ahref="#/v5/api/utils/fixednumber/-%23-FixedFormat--strings">Format Strings</a> directly into the <ahref="#/v5/api/utils/fixednumber/">FixedNumber</a> will automatically create this.</p>
<aname="/v5/api/utils/fixednumber/-%23-FixedFormat--strings"></a><aname="/v5/api/utils/fixednumber/-%23-FixedNumber--FixedFormat--FixedFormat--strings"></a><aname="/v5/api/utils/fixednumber/"></a><h3class="show-anchors"><div>Format Strings<divclass="anchors"><aclass="self"href="#/v5/api/utils/fixednumber/-%23-FixedFormat--strings"></a></div></div></h3><p>A format string is composed of three components, including signed-ness, bit-width and number of decimals.</p>
<p>A signed format string begins with <codeclass="inline">fixed</code>, which an unsigned format string begins with <codeclass="inline">ufixed</code>, followed by the width (in bits) and the number of decimals.</p>
<p>The width must be conguent to 0 mod 8 (i.e. <codeclass="inline">(width % 8) == 0</code>) and no larger than 256 bits and the number of decimals must be no larger than 80.</p>
<p>For example:</p>
<p><ul><li><b>fixed128x18</b> is signed, 128 bits wide and has 18 decimals; this is useful for most purposes </li><li><b>fixed32x0</b> is signed, 32 bits wide and has 0 decimals; this would be the same as a <codeclass="inline">int32_t</code> in C </li><li><b>ufixed32x0</b> is unsigned, 32 bits wide and has 0 decimals; this would be the same as a <codeclass="inline">uint32_t</code> in C </li><li><b>fixed</b> is shorthand for <codeclass="inline">fixed128x18</code></li><li><b>ufixed</b> is shorthand for <codeclass="inline">ufixed128x18</code></li></ul></p>
<aname="/v5/api/utils/fixednumber/-%23-FixedNumber-from"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">FixedFormat</span><spanclass="symbol">.</span><spanclass="method">from</span><spanclass="symbol">(</span><spanclass="param">value</span> = "<spanclass="param">fixed128x18</span>" <spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/fixednumber/-%23-FixedFormat">FixedFormat</a></span><divclass="anchors"><aclass="self"href="#/v5/api/utils/fixednumber/-%23-FixedNumber-from"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/fixednumber.ts#L140">source</a></div></div><divclass="body"><p>Returns a new instance of a <b>FixedFormat</b> defined by <i>value</i>. Any valid <ahref="#/v5/api/utils/fixednumber/-%23-FixedFormat--strings">Format Strings</a> may be passed in as well as any object which has any of <codeclass="inline">signed</code>, <codeclass="inline">width</code> and <codeclass="inline">decimals</code> defined, including a <ahref="#/v5/api/utils/fixednumber/-%23-FixedFormat">FixedFormat</a> object.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">fixedFormat</span><spanclass="symbol">.</span><spanclass="method">signed</span><spanclass="arrow">⇒</span><spanclass="returns">boolean</span><divclass="anchors"></div></div><divclass="body"><p>The signed-ness of <i>fixedFormat</i>, true if negative values are supported.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">fixedFormat</span><spanclass="symbol">.</span><spanclass="method">width</span><spanclass="arrow">⇒</span><spanclass="returns">number</span><divclass="anchors"></div></div><divclass="body"><p>The width (in bits) of <i>fixedFormat</i>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">fixedFormat</span><spanclass="symbol">.</span><spanclass="method">decimals</span><spanclass="arrow">⇒</span><spanclass="returns">number</span><divclass="anchors"></div></div><divclass="body"><p>The number of decimal points of <i>fixedFormat</i>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">fixedFormat</span><spanclass="symbol">.</span><spanclass="method">name</span><spanclass="arrow">⇒</span><spanclass="returns">string</span><divclass="anchors"></div></div><divclass="body"><p>The name of the <i>fixedFormat</i>, which can be used to recreate the format and is the string that the Solidity language uses to represent this format.</p>
</div></div><divclass="definition"><divclass="term"><b><i>"fixed"</i></b></div><divclass="body"><p>A shorthand for <codeclass="inline">fixed128x80</code>.</p>
</div></div><divclass="page-separator"></div><aname="/v5/api/utils/hashing/-%23-hashing-algorithms"></a><aname="/v5/api/utils/hashing/-%23-hashing-algorithms"></a><aname="/v5/api/utils/hashing/"></a><h1class="show-anchors"><div>Hashing Algorithms<divclass="anchors"><aclass="self"href="#/v5/api/utils/hashing/-%23-hashing-algorithms"></a></div></div></h1><p>Explain what hash functions are?</p>
<aname="/v5/api/utils/hashing/-%23-cryptographic-hash-functions"></a><aname="/v5/api/utils/hashing/-%23-hashing-algorithms--cryptographic-hash-functions"></a><aname="/v5/api/utils/hashing/"></a><h2class="show-anchors"><div>Cryptographic Hash Functions<divclass="anchors"><aclass="self"href="#/v5/api/utils/hashing/-%23-cryptographic-hash-functions"></a></div></div></h2><p>The <ahref="https://en.wikipedia.org/wiki/Cryptographic_hash_function">Cryptographic Hash Functions</a> are a specific family of hash functions.</p>
<aname="/v5/api/utils/hashing/-%23-utils-id"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="method">id</span><spanclass="symbol">(</span><spanclass="param">text</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 >></span><divclass="anchors"><aclass="self"href="#/v5/api/utils/hashing/-%23-utils-id"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/hash/src.ts/index.ts#L47">source</a></div></div><divclass="body"><p>The Ethereum Identity function computs the <ahref="https://en.wikipedia.org/wiki/SHA-3">KECCAK256</a> hash of the <i>text</i> bytes.</p>
</div></div><aname="/v5/api/utils/hashing/-%23-utils-ripemd160"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="method">ripemd160</span><spanclass="symbol">(</span><spanclass="param">aBytesLike</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 20 >></span><divclass="anchors"><aclass="self"href="#/v5/api/utils/hashing/-%23-utils-ripemd160"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/sha2/src.ts/index.ts#L14">source</a></div></div><divclass="body"><p>Returns the <ahref="https://en.m.wikipedia.org/wiki/RIPEMD">RIPEMD-160</a> digest of <i>aBytesLike</i>.</p>
</div></div><aname="/v5/api/utils/hashing/-%23-utils-sha256"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="method">sha256</span><spanclass="symbol">(</span><spanclass="param">aBytesLike</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 >></span><divclass="anchors"><aclass="self"href="#/v5/api/utils/hashing/-%23-utils-sha256"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/sha2/src.ts/index.ts#L18">source</a></div></div><divclass="body"><p>Returns the <ahref="https://en.wikipedia.org/wiki/SHA-2">SHA2-256</a> digest of <i>aBytesLike</i>.</p>
</div></div><aname="/v5/api/utils/hashing/-%23-utils-sha512"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="method">sha512</span><spanclass="symbol">(</span><spanclass="param">aBytesLike</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 64 >></span><divclass="anchors"><aclass="self"href="#/v5/api/utils/hashing/-%23-utils-sha512"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/sha2/src.ts/index.ts#L22">source</a></div></div><divclass="body"><p>Returns the <ahref="https://en.wikipedia.org/wiki/SHA-2">SHA2-512</a> digest of <i>aBytesLike</i>.</p>
<aname="/v5/api/utils/hashing/-%23-utils-computeHmac"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="method">computeHmac</span><spanclass="symbol">(</span><spanclass="param">algorithm</span><spanclass="symbol">,</span><spanclass="param">key</span><spanclass="symbol">,</span><spanclass="param">data</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>></span><divclass="anchors"><aclass="self"href="#/v5/api/utils/hashing/-%23-utils-computeHmac"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/sha2/src.ts/index.ts#L27">source</a></div></div><divclass="body"><p>Returns the <ahref="https://en.wikipedia.org/wiki/HMAC">HMAC</a> of <i>data</i> with <i>key</i> using the <ahref="#/v5/api/utils/hashing/-%23-utils--hmac-supported-algorithm">Algorithm</a><i>algorithm</i>.</p>
<aname="/v5/api/utils/hashing/-%23-utils-hashMessage"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="method">hashMessage</span><spanclass="symbol">(</span><spanclass="param">message</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 >></span><divclass="anchors"><aclass="self"href="#/v5/api/utils/hashing/-%23-utils-hashMessage"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/hash/src.ts/index.ts#L53">source</a></div></div><divclass="body"><p>Computes the <ahref="https://eips.ethereum.org/EIPS/eip-191">EIP-191</a> personal message digest of <i>message</i>. Personal messages are converted to UTF-8 bytes and prefixed with <codeclass="inline">\x19Ethereum Signed Message:</code> and the length of <i>message</i>.</p>
</div></div><aname="/v5/api/utils/hashing/-%23-utils-namehash"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="method">namehash</span><spanclass="symbol">(</span><spanclass="param">name</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 >></span><divclass="anchors"><aclass="self"href="#/v5/api/utils/hashing/-%23-utils-namehash"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/hash/src.ts/index.ts#L29">source</a></div></div><divclass="body"><p>Returns the <ahref="https://docs.ens.domains/contract-api-reference/name-processing#hashing-names">ENS Namehash</a> of <i>name</i>.</p>
</div></div><divclass="code-title"><div>Hashing Messages</div></div><divclass="code"><spanclass="comment">// @TODO: include examples of hashMessage; it can be complex. :)
</span></div><aname="/v5/api/utils/hashing/-%23-utils--solidity-hashing"></a><aname="/v5/api/utils/hashing/-%23-hashing-algorithms--utils--solidity-hashing"></a><aname="/v5/api/utils/hashing/"></a><h2class="show-anchors"><div>Solidity Hashing Algorithms<divclass="anchors"><aclass="self"href="#/v5/api/utils/hashing/-%23-utils--solidity-hashing"></a></div></div></h2><p>When using the Solidity <codeclass="inline">abi.packEncoded(...)</code> function, a non-standard <i>tightly packed</i> version of encoding is used. These functions implement the tightly packing algorithm.</p>
<aname="/v5/api/utils/hashing/-%23-utils-solidityPack"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="method">solidityPack</span><spanclass="symbol">(</span><spanclass="param">types</span><spanclass="symbol">,</span><spanclass="param">values</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>></span><divclass="anchors"><aclass="self"href="#/v5/api/utils/hashing/-%23-utils-solidityPack"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/solidity/src.ts/index.ts#L73">source</a></div></div><divclass="body"><p>Returns the non-standard encoded <i>values</i> packed according to their respecive type in <i>types</i>.</p>
</div></div><aname="/v5/api/utils/hashing/-%23-utils-solidityKeccak256"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="method">solidityKeccak256</span><spanclass="symbol">(</span><spanclass="param">types</span><spanclass="symbol">,</span><spanclass="param">values</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 >></span><divclass="anchors"><aclass="self"href="#/v5/api/utils/hashing/-%23-utils-solidityKeccak256"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/solidity/src.ts/index.ts#L82">source</a></div></div><divclass="body"><p>Returns the <ahref="https://en.wikipedia.org/wiki/SHA-3">KECCAK256</a> of the non-standard encoded <i>values</i> packed according to their respective type in <i>types</i>.</p>
</div></div><aname="/v5/api/utils/hashing/-%23-utils-soliditySha256"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="method">soliditySha256</span><spanclass="symbol">(</span><spanclass="param">types</span><spanclass="symbol">,</span><spanclass="param">values</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 >></span><divclass="anchors"><aclass="self"href="#/v5/api/utils/hashing/-%23-utils-soliditySha256"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/solidity/src.ts/index.ts#L86">source</a></div></div><divclass="body"><p>Returns the <ahref="https://en.wikipedia.org/wiki/SHA-2">SHA2-256</a> of the non-standard encoded <i>values</i> packed according to their respective type in <i>types</i>.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="method">defaultPath</span><spanclass="arrow">⇒</span><spanclass="returns">"m/44'/60'/0'/0/0"</span><divclass="anchors"></div></div><divclass="body"><p>The default path for Ethereum in an HD Wallet</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">mnemonic</span><spanclass="symbol">.</span><spanclass="method">phrase</span><spanclass="arrow">⇒</span><spanclass="returns">string</span><divclass="anchors"></div></div><divclass="body"><p>The mnemonic phrase for this mnemonic. It is 12, 15, 18, 21 or 24 words long and separated by the whitespace specified by the <codeclass="inline">locale</code>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">mnemonic</span><spanclass="symbol">.</span><spanclass="method">path</span><spanclass="arrow">⇒</span><spanclass="returns">string</span><divclass="anchors"></div></div><divclass="body"><p>The HD path for this mnemonic.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">mnemonic</span><spanclass="symbol">.</span><spanclass="method">locale</span><spanclass="arrow">⇒</span><spanclass="returns">string</span><divclass="anchors"></div></div><divclass="body"><p>The language of the wordlist this mnemonic is using.</p>
<aname="/v5/api/utils/hdnode/-%23-HDNode-fromMnemonic"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">HDNode</span><spanclass="symbol">.</span><spanclass="method">fromMnemonic</span><spanclass="symbol">(</span><spanclass="param">phrase</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">password</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">wordlist</span><spanclass="symbol">]</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/hdnode/-%23-HDNode">HDNode</a></span><divclass="anchors"><aclass="self"href="#/v5/api/utils/hdnode/-%23-HDNode-fromMnemonic"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/hdnode/src.ts/index.ts#L262">source</a></div></div><divclass="body"><p>Return the <ahref="#/v5/api/utils/hdnode/-%23-HDNode">HDNode</a> for <i>phrase</i> with the optional <i>password</i> and <i>wordlist</i>.</p>
</div></div><aname="/v5/api/utils/hdnode/-%23-HDNode-fromSeed"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">HDNode</span><spanclass="symbol">.</span><spanclass="method">fromSeed</span><spanclass="symbol">(</span><spanclass="param">aBytesLike</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/hdnode/-%23-HDNode">HDNode</a></span><divclass="anchors"><aclass="self"href="#/v5/api/utils/hdnode/-%23-HDNode-fromSeed"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/hdnode/src.ts/index.ts#L277">source</a></div></div><divclass="body"><p>Return the <ahref="#/v5/api/utils/hdnode/-%23-HDNode">HDNode</a> for the seed <i>aBytesLike</i>.</p>
</div></div><aname="/v5/api/utils/hdnode/-%23-HDNode-fromExtendedKey"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">HDNode</span><spanclass="symbol">.</span><spanclass="method">fromExtendedKey</span><spanclass="symbol">(</span><spanclass="param">extendedKey</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/hdnode/-%23-HDNode">HDNode</a></span><divclass="anchors"><aclass="self"href="#/v5/api/utils/hdnode/-%23-HDNode-fromExtendedKey"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/hdnode/src.ts/index.ts#L281">source</a></div></div><divclass="body"><p>Return the <ahref="#/v5/api/utils/hdnode/-%23-HDNode">HDNode</a> for the <i>extendedKey</i>. If <i>extendedKey</i> was neutered, the <b>HDNode</b> will only be able to compute addresses and not private keys.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">hdNode</span><spanclass="symbol">.</span><spanclass="method">privateKey</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 >></span><divclass="anchors"></div></div><divclass="body"><p>The private key for this HDNode.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">hdNode</span><spanclass="symbol">.</span><spanclass="method">publicKey</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 33 >></span><divclass="anchors"></div></div><divclass="body"><p>The (compresses) public key for this HDNode.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">hdNode</span><spanclass="symbol">.</span><spanclass="method">fingerprint</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 4 >></span><divclass="anchors"></div></div><divclass="body"><p>The fingerprint is meant as an index to quickly match parent and children nodes together, however collisions may occur and software should verify matching nodes.</p>
<p>Most developers will not need to use this.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">hdNode</span><spanclass="symbol">.</span><spanclass="method">parentFingerprint</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 4 >></span><divclass="anchors"></div></div><divclass="body"><p>The fingerprint of the parent node. See <i>fingerprint</i> for more details.</p>
<p>Most developers will not need to use this.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">hdNode</span><spanclass="symbol">.</span><spanclass="method">address</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/address/-%23-address">Address</a>></span><divclass="anchors"></div></div><divclass="body"><p>The address of this HDNode.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">hdNode</span><spanclass="symbol">.</span><spanclass="method">mnemonic</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/hdnode/-%23-Mnemonic">Mnemonic</a></span><divclass="anchors"></div></div><divclass="body"><p>The mnemonic of this HDNode, if known.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">hdNode</span><spanclass="symbol">.</span><spanclass="method">path</span><spanclass="arrow">⇒</span><spanclass="returns">string</span><divclass="anchors"></div></div><divclass="body"><p>The path of this HDNode, if known. If the <i>mnemonic</i> is also known, this will match <codeclass="inline">mnemonic.path</code>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">hdNode</span><spanclass="symbol">.</span><spanclass="method">chainCode</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 >></span><divclass="anchors"></div></div><divclass="body"><p>The chain code is used as a non-secret private key which is then used with EC-multiply to provide the ability to derive addresses without the private key of child non-hardened nodes.</p>
<p>Most developers will not need to use this.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">hdNode</span><spanclass="symbol">.</span><spanclass="method">index</span><spanclass="arrow">⇒</span><spanclass="returns">number</span><divclass="anchors"></div></div><divclass="body"><p>The index of this HDNode. This will match the last component of the <i>path</i>.</p>
<p>Most developers will not need to use this.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">hdNode</span><spanclass="symbol">.</span><spanclass="method">depth</span><spanclass="arrow">⇒</span><spanclass="returns">number</span><divclass="anchors"></div></div><divclass="body"><p>The depth of this HDNode. This will match the number of components (less one, the <codeclass="inline">m/</code>) of the <i>path</i>.</p>
<p>Most developers will not need to use this.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">hdNode</span><spanclass="symbol">.</span><spanclass="method">extendedKey</span><spanclass="arrow">⇒</span><spanclass="returns">string</span><divclass="anchors"></div></div><divclass="body"><p>A serialized string representation of this HDNode. Not all properties are included in the serialization, such as the mnemonic and path, so serializing and deserializing (using the <codeclass="inline">fromExtendedKey</code> class method) will result in reduced information.</p>
<aname="/v5/api/utils/hdnode/-%23-HDNode-neuter"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">hdNode</span><spanclass="symbol">.</span><spanclass="method">neuter</span><spanclass="symbol">(</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/hdnode/-%23-HDNode">HDNode</a></span><divclass="anchors"><aclass="self"href="#/v5/api/utils/hdnode/-%23-HDNode-neuter"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/hdnode/src.ts/index.ts#L161">source</a></div></div><divclass="body"><p>Return a new instance of <i>hdNode</i> with its private key removed but all otehr properties preserved. This ensures that the key can not leak the private key of itself or any derived children, but may still be used to compute the addresses of itself and any non-hardened children.</p>
</div></div><aname="/v5/api/utils/hdnode/-%23-HDNode-derivePath"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">hdNode</span><spanclass="symbol">.</span><spanclass="method">derivePath</span><spanclass="symbol">(</span><spanclass="param">path</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/hdnode/-%23-HDNode">HDNode</a></span><divclass="anchors"><aclass="self"href="#/v5/api/utils/hdnode/-%23-HDNode-derivePath"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/hdnode/src.ts/index.ts#L224">source</a></div></div><divclass="body"><p>Return a new <ahref="#/v5/api/utils/hdnode/-%23-HDNode">HDNode</a> which is the child of <i>hdNode</i> found by deriving <i>path</i>.</p>
<aname="/v5/api/utils/hdnode/-%23-utils-mnemonicToSeed"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="method">mnemonicToSeed</span><spanclass="symbol">(</span><spanclass="param">phrase</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">password</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 64 >></span><divclass="anchors"><aclass="self"href="#/v5/api/utils/hdnode/-%23-utils-mnemonicToSeed"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/hdnode/src.ts/index.ts#L309">source</a></div></div><divclass="body"><p>Convert a mnemonic phrase to a seed, according to <ahref="https://en.bitcoin.it/wiki/BIP_0039">BIP-39</a>.</p>
</div></div><aname="/v5/api/utils/hdnode/-%23-utils-mnemonicToEntropy"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="method">mnemonicToEntropy</span><spanclass="symbol">(</span><spanclass="param">phrase</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">wordlist</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>></span><divclass="anchors"><aclass="self"href="#/v5/api/utils/hdnode/-%23-utils-mnemonicToEntropy"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/hdnode/src.ts/index.ts#L317">source</a></div></div><divclass="body"><p>Convert a mnemonic phrase to its entropy, according to <ahref="https://en.bitcoin.it/wiki/BIP_0039">BIP-39</a>.</p>
</div></div><aname="/v5/api/utils/hdnode/-%23-utils-isValidMnemonic"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="method">isValidMnemonic</span><spanclass="symbol">(</span><spanclass="param">phrase</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">wordlist</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">boolean</span><divclass="anchors"><aclass="self"href="#/v5/api/utils/hdnode/-%23-utils-isValidMnemonic"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/hdnode/src.ts/index.ts#L398">source</a></div></div><divclass="body"><p>Returns true if <i>phrase</i> is a valid mnemonic phrase, by testing the checksum.</p>
</div></div><divclass="page-separator"></div><aname="/v5/api/utils/logger/-%23-logging"></a><aname="/v5/api/utils/logger/-%23-logging"></a><aname="/v5/api/utils/logger/"></a><h1class="show-anchors"><div>Logging<divclass="anchors"><aclass="self"href="#/v5/api/utils/logger/-%23-logging"></a></div></div></h1><p>These are just a few simple logging utilities provided to simplify and standardize the error facilities across the Ethers library.</p>
<p>The <ahref="#/v5/api/utils/logger/-%23-Logger">Logger</a> library has zero dependencies and is intentionally very light so it can be easily included in each library.</p>
<p>The <ahref="#/v5/api/utils/logger/-%23-Logger--censorship">Censorship</a> functionality relies on one instance of the Ethers library being included. In large bundled packages or when <codeclass="inline">npm link</code> is used, this may not be the case. If you require this functionality, ensure that your bundling is configured properly.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="modifier">new </span><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="method">Logger</span><spanclass="symbol">(</span><spanclass="param">version</span><spanclass="symbol">)</span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/logger/src.ts/index.ts#L150">source</a></div></div><divclass="body"><p>Create a new logger which will include <i>version</i> in all errors thrown.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">Logger</span><spanclass="symbol">.</span><spanclass="method">globalLogger</span><spanclass="symbol">(</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/logger/-%23-Logger">Logger</a></span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/logger/src.ts/index.ts#L298">source</a></div></div><divclass="body"><p>Returns the singleton global logger.</p>
</div></div><aname="/v5/api/utils/logger/-%23-logging--Logger--errors"></a><aname="/v5/api/utils/logger/"></a><h3class="show-anchors"><div>Errors<divclass="anchors"><aclass="self"href="#/v5/api/utils/logger/-%23-logging--Logger--errors"></a></div></div></h3><p>These functions honor the current <ahref="#/v5/api/utils/logger/-%23-Logger--censorship">Censorship</a> and help create a standard error model for detecting and processing errors within Ethers.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">logger</span><spanclass="symbol">.</span><spanclass="method">makeError</span><spanclass="symbol">(</span><spanclass="param">message</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">code</span> = <spanclass="param">UNKNOWN_ERROR</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">params</span><spanclass="symbol">]</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Error</span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/logger/src.ts/index.ts#L179">source</a></div></div><divclass="body"><p>Create an Error object with <i>message</i> and an optional <i>code</i> and additional <i>params</i> set. This is useful when an error is needed to be rejected instead of thrown.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">logger</span><spanclass="symbol">.</span><spanclass="method">throwError</span><spanclass="symbol">(</span><spanclass="param">message</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">code</span> = <spanclass="param">UNKNOWN_ERROR</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">params</span><spanclass="symbol">]</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">never</span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/logger/src.ts/index.ts#L216">source</a></div></div><divclass="body"><p>Throw an Error with <i>message</i> and an optional <i>code</i> and additional <i>params</i> set.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">logger</span><spanclass="symbol">.</span><spanclass="method">throwArgumentError</span><spanclass="symbol">(</span><spanclass="param">message</span><spanclass="symbol">,</span><spanclass="param">name</span><spanclass="symbol">,</span><spanclass="param">value</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">never</span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/logger/src.ts/index.ts#L220">source</a></div></div><divclass="body"><p>Throw an <ahref="#/v5/api/utils/logger/-%23-errors-InvalidArgument">INVALID_ARGUMENT</a> Error with <i>name</i> and <i>value</i>.</p>
</div></div><aname="/v5/api/utils/logger/-%23-logging--Logger--usage-validation"></a><aname="/v5/api/utils/logger/"></a><h3class="show-anchors"><div>Usage Validation<divclass="anchors"><aclass="self"href="#/v5/api/utils/logger/-%23-logging--Logger--usage-validation"></a></div></div></h3><p>There can be used to ensure various properties and actions are safe.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">logger</span><spanclass="symbol">.</span><spanclass="method">checkAbstract</span><spanclass="symbol">(</span><spanclass="param">target</span><spanclass="symbol">,</span><spanclass="param">kind</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">void</span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/logger/src.ts/index.ts#L286">source</a></div></div><divclass="body"><p>Checks that <i>target</i> is not <i>kind</i> and performs the same operatons as <codeclass="inline">checkNew</code>. This is useful for ensuring abstract classes are not being instantiated.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">logger</span><spanclass="symbol">.</span><spanclass="method">checkArgumentCount</span><spanclass="symbol">(</span><spanclass="param">count</span><spanclass="symbol">,</span><spanclass="param">expectedCound</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">message</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">void</span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/logger/src.ts/index.ts#L258">source</a></div></div><divclass="body"><p>If <i>count</i> is not equal to <i>expectedCount</i>, throws a <ahref="#/v5/api/utils/logger/-%23-errors-MissingArgument">MISSING_ARGUMENT</a> or <ahref="#/v5/api/utils/logger/-%23-errors-UnexpectedArgument">UNEXPECTED_ARGUMENT</a> error.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">logger</span><spanclass="symbol">.</span><spanclass="method">checkNew</span><spanclass="symbol">(</span><spanclass="param">target</span><spanclass="symbol">,</span><spanclass="param">kind</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">void</span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/logger/src.ts/index.ts#L280">source</a></div></div><divclass="body"><p>If <i>target</i> is not a valid <codeclass="inline">this</code> or <codeclass="inline">target</code> value, throw a <ahref="#/v5/api/utils/logger/-%23-errors-MissingNew">MISSING_NEW</a> error. This is useful to ensure callers of a Class are using <codeclass="inline">new</code>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">logger</span><spanclass="symbol">.</span><spanclass="method">checkNormalize</span><spanclass="symbol">(</span><spanclass="param">message</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">void</span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/logger/src.ts/index.ts#L227">source</a></div></div><divclass="body"><p>Check that the environment has a correctly functioning <ahref="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/normalize">String.normalize</a>. If not, a <ahref="#/v5/api/utils/logger/-%23-errors-UnsupportedOperation">UNSUPPORTED_OPERATION</a> error is thrown.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">logger</span><spanclass="symbol">.</span><spanclass="method">checkSafeUint53</span><spanclass="symbol">(</span><spanclass="param">value</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">message</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">void</span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/logger/src.ts/index.ts#L236">source</a></div></div><divclass="body"><p>If <i>value</i> is not safe as a <ahref="https://en.wikipedia.org/wiki/Double-precision_floating-point_format">JavaScript number</a>, throws a <ahref="#/v5/api/utils/logger/-%23-errors-NumericFault">NUMERIC_FAULT</a> error.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">Logger</span><spanclass="symbol">.</span><spanclass="method">setLogLevel</span><spanclass="symbol">(</span><spanclass="param">logLevel</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">void</span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/logger/src.ts/index.ts#L321">source</a></div></div><divclass="body"><p>Set the log level, to suppress logging output below a <ahref="#/v5/api/utils/logger/-%23-Logger-levels">particular log level</a>.</p>
</div></div><aname="/v5/api/utils/logger/-%23-errors"></a><aname="/v5/api/utils/logger/-%23-logging--errors"></a><aname="/v5/api/utils/logger/"></a><h2class="show-anchors"><div>Errors<divclass="anchors"><aclass="self"href="#/v5/api/utils/logger/-%23-errors"></a></div></div></h2><p>Every error in Ethers has a <codeclass="inline">code</code> value, which is a string that will match one of the following error codes.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">Logger</span><spanclass="symbol">.</span><spanclass="path">errors</span><spanclass="symbol">.</span><spanclass="method">NOT_IMPLEMENTED</span><divclass="anchors"></div></div><divclass="body"><p>The operation is not implemented.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">Logger</span><spanclass="symbol">.</span><spanclass="path">errors</span><spanclass="symbol">.</span><spanclass="method">SERVER_ERROR</span><divclass="anchors"></div></div><divclass="body"><p>There was an error communicating with a server.</p>
</div></div><aname="/v5/api/utils/logger/-%23-errors-UnsupportedOperation"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">Logger</span><spanclass="symbol">.</span><spanclass="path">errors</span><spanclass="symbol">.</span><spanclass="method">UNSUPPORTED_OPERATION</span><divclass="anchors"><aclass="self"href="#/v5/api/utils/logger/-%23-errors-UnsupportedOperation"></a></div></div><divclass="body"><p>The operation is not supported.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">Logger</span><spanclass="symbol">.</span><spanclass="path">errors</span><spanclass="symbol">.</span><spanclass="method">BUFFER_OVERRUN</span><divclass="anchors"></div></div><divclass="body"><p>The amount of data needed is more than the amount of data required, which would cause the data buffer to read past its end.</p>
</div></div><aname="/v5/api/utils/logger/-%23-errors-NumericFault"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">Logger</span><spanclass="symbol">.</span><spanclass="path">errors</span><spanclass="symbol">.</span><spanclass="method">NUMERIC_FAULT</span><divclass="anchors"><aclass="self"href="#/v5/api/utils/logger/-%23-errors-NumericFault"></a></div></div><divclass="body"><p>There was an invalid operation done on numeric values.</p>
<p>Common cases of this occur when there is <ahref="https://en.wikipedia.org/wiki/Integer_overflow">overflow</a>, <ahref="https://en.wikipedia.org/wiki/Arithmetic_underflow">arithmetic underflow</a> in fixed numeric types or division by zero.</p>
<aname="/v5/api/utils/logger/-%23-errors-InvalidArgument"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">Logger</span><spanclass="symbol">.</span><spanclass="path">errors</span><spanclass="symbol">.</span><spanclass="method">INVALID_ARGUMENT</span><divclass="anchors"><aclass="self"href="#/v5/api/utils/logger/-%23-errors-InvalidArgument"></a></div></div><divclass="body"><p>The type or value of an argument is invalid. This will generally also include the <codeclass="inline">name</code> and <codeclass="inline">value</code> of the argument. Any function which accepts sensitive data (such as a private key) will include the string <codeclass="inline">[[REDACTED]]</code> instead of the value passed in.</p>
</div></div><aname="/v5/api/utils/logger/-%23-errors-MissingArgument"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">Logger</span><spanclass="symbol">.</span><spanclass="path">errors</span><spanclass="symbol">.</span><spanclass="method">MISSING_ARGUMENT</span><divclass="anchors"><aclass="self"href="#/v5/api/utils/logger/-%23-errors-MissingArgument"></a></div></div><divclass="body"><p>An expected parameter was not specified.</p>
</div></div><aname="/v5/api/utils/logger/-%23-errors-MissingNew"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">Logger</span><spanclass="symbol">.</span><spanclass="path">errors</span><spanclass="symbol">.</span><spanclass="method">MISSING_NEW</span><divclass="anchors"><aclass="self"href="#/v5/api/utils/logger/-%23-errors-MissingNew"></a></div></div><divclass="body"><p>An object is a Class, but is now being called with <codeclass="inline">new</code>.</p>
</div></div><aname="/v5/api/utils/logger/-%23-errors-UnexpectedArgument"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">Logger</span><spanclass="symbol">.</span><spanclass="path">errors</span><spanclass="symbol">.</span><spanclass="method">UNEXPECTED_ARGUMENT</span><divclass="anchors"><aclass="self"href="#/v5/api/utils/logger/-%23-errors-UnexpectedArgument"></a></div></div><divclass="body"><p>Too many parameters we passed into a function.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">Logger</span><spanclass="symbol">.</span><spanclass="path">errors</span><spanclass="symbol">.</span><spanclass="method">CALL_EXCEPTION</span><divclass="anchors"></div></div><divclass="body"><p>An attempt to call a blockchain contract (getter) resulted in a revert or other error.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">Logger</span><spanclass="symbol">.</span><spanclass="path">errors</span><spanclass="symbol">.</span><spanclass="method">INSUFFICIENT_FUNDS</span><divclass="anchors"></div></div><divclass="body"><p>The account is attempting to make a transaction which costs more than is available.</p>
<p>A sending account must have enough ether to pay for the value, the gas limit (at the gas price) as well as the intrinsic cost of data. The intrinsic cost of data is 4 gas for each zero byte and 68 gas for each non-zero byte.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">Logger</span><spanclass="symbol">.</span><spanclass="path">errors</span><spanclass="symbol">.</span><spanclass="method">NETWORK_ERROR</span><divclass="anchors"></div></div><divclass="body"><p>An Ethereum network validation error, such as an invalid chain ID.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">Logger</span><spanclass="symbol">.</span><spanclass="path">errors</span><spanclass="symbol">.</span><spanclass="method">NONCE_EXPIRED</span><divclass="anchors"></div></div><divclass="body"><p>The nonce being specified has already been used in a mined transaction.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">Logger</span><spanclass="symbol">.</span><spanclass="path">errors</span><spanclass="symbol">.</span><spanclass="method">REPLACEMENT_UNDERPRICED</span><divclass="anchors"></div></div><divclass="body"><p>When replacing a transaction, by using a nonce which has already been sent to the network, but which has not been mined yet the new transaction must specify a higher gas price.</p>
<p>This error occurs when the gas price is insufficient to <i>bribe</i> the transaction pool to prefer the new transaction over the old one. Generally, the new gas price should be about 50% + 1 wei more, so if a gas price of 10 gwei was used, the replacement should be 15.000000001 gwei.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">Logger</span><spanclass="symbol">.</span><spanclass="path">errors</span><spanclass="symbol">.</span><spanclass="method">UNPREDICTABLE_GAS_LIMIT</span><divclass="anchors"></div></div><divclass="body"><p>When estimating the required amount of gas for a transaction, a node is queried for its best guess.</p>
<p>If a node is unable (or unwilling) to predict the cost, this error occurs.</p>
<p>The best remedy for this situation is to specify a gas limit in the transaction manually.</p>
<p>This error can also indicate that the transaction is expected to fail regardless, if for example an account with no tokens is attempting to send a token.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">Logger</span><spanclass="symbol">.</span><spanclass="path">levels</span><spanclass="symbol">.</span><spanclass="method">DEBUG</span><divclass="anchors"></div></div><divclass="body"><p>Log all output, including debugging information.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">Logger</span><spanclass="symbol">.</span><spanclass="path">levels</span><spanclass="symbol">.</span><spanclass="method">INFO</span><divclass="anchors"></div></div><divclass="body"><p>Only log output for infomational, warnings and errors.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">Logger</span><spanclass="symbol">.</span><spanclass="path">levels</span><spanclass="symbol">.</span><spanclass="method">WARNING</span><divclass="anchors"></div></div><divclass="body"><p>Only log output for warnings and errors.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">Logger</span><spanclass="symbol">.</span><spanclass="path">levels</span><spanclass="symbol">.</span><spanclass="method">ERROR</span><divclass="anchors"></div></div><divclass="body"><p>Only log output for errors.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">Logger</span><spanclass="symbol">.</span><spanclass="path">levels</span><spanclass="symbol">.</span><spanclass="method">OFF</span><divclass="anchors"></div></div><divclass="body"><p>Do not output any logs.</p>
</div></div><aname="/v5/api/utils/properties/-%23-utils-resolveproperties"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="method">resolveProperties</span><spanclass="symbol">(</span><spanclass="param">anObject</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Promise< any ></span><divclass="anchors"><aclass="self"href="#/v5/api/utils/properties/-%23-utils-resolveproperties"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/properties/src.ts/index.ts#L32">source</a></div></div><divclass="body">
<aname="/v5/api/utils/signing-key/-%23-SigningKey-constructor"></a><divclass="property show-anchors"><divclass="signature"><spanclass="modifier">new </span><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="method">SigningKey</span><spanclass="symbol">(</span><spanclass="param">privateKey</span><spanclass="symbol">)</span><divclass="anchors"><aclass="self"href="#/v5/api/utils/signing-key/-%23-SigningKey-constructor"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/signing-key/src.ts/index.ts#L32">source</a></div></div><divclass="body"><p>Create a new SigningKey for <i>privateKey</i>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">signingKey</span><spanclass="symbol">.</span><spanclass="method">privateKey</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 >></span><divclass="anchors"></div></div><divclass="body"><p>The private key for this Signing Key.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">signingKey</span><spanclass="symbol">.</span><spanclass="method">publicKey</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 65 >></span><divclass="anchors"></div></div><divclass="body"><p>The uncompressed public key for this Signing Key. It will always be 65 bytes (130 nibbles) and begine with <codeclass="inline">0x04</code>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">signingKey</span><spanclass="symbol">.</span><spanclass="method">compressedPublicKey</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 33 >></span><divclass="anchors"></div></div><divclass="body"><p>The compressed public key for this Signing Key. It will always be 33 bytes (66 nibbles) and begine with either <codeclass="inline">0x02</code> or <codeclass="inline">0x03</code>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">signingKey</span><spanclass="symbol">.</span><spanclass="method">signDigest</span><spanclass="symbol">(</span><spanclass="param">digest</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/bytes/-%23-Signature">Signature</a></span><divclass="anchors"></div></div><divclass="body"><p>Sign the <i>digest</i> and return the signature.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">signingKey</span><spanclass="symbol">.</span><spanclass="method">computeSharedSecret</span><spanclass="symbol">(</span><spanclass="param">otherKey</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 >></span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/signing-key/src.ts/index.ts#L61">source</a></div></div><divclass="body"><p>Compute the ECDH shared secret with <i>otherKey</i>. The <i>otherKey</i> may be either a public key or a private key, but generally will be a public key from another party.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">SigningKey</span><spanclass="symbol">.</span><spanclass="method">isSigningKey</span><spanclass="symbol">(</span><spanclass="param">anObject</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">boolean</span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/signing-key/src.ts/index.ts#L67">source</a></div></div><divclass="body"><p>Returns true if <i>anObject</i> is a SigningKey.</p>
<aname="/v5/api/utils/signing-key/-%23-utils-verifyMessage"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="method">verifyMessage</span><spanclass="symbol">(</span><spanclass="param">message</span><spanclass="symbol">,</span><spanclass="param">signature</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/address/-%23-address">Address</a>></span><divclass="anchors"><aclass="self"href="#/v5/api/utils/signing-key/-%23-utils-verifyMessage"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/wallet/src.ts/index.ts#L172">source</a></div></div><divclass="body"><p>Returns the address that signed <i>message</i> producing <i>signature</i>. The signature may have a non-canonical v (i.e. does not need to be 27 or 28), in which case it will be normalized to compute the `recoveryParam` which will then be used to compute the address; this allows systems which use the v to encode additional data (such as <ahref="https://eips.ethereum.org/EIPS/eip-155">EIP-155</a>) to be used since the v parameter is still completely non-ambiguous.</p>
</div></div><aname="/v5/api/utils/signing-key/-%23-utils-computePublicKey"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="method">computePublicKey</span><spanclass="symbol">(</span><spanclass="param">key</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">compressed</span> = <spanclass="param">false</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>></span><divclass="anchors"><aclass="self"href="#/v5/api/utils/signing-key/-%23-utils-computePublicKey"></a></div></div><divclass="body"><p>Computes the public key of <i>key</i>, optionally compressing it. The <i>key</i> can be any form of public key (compressed or uncompressed) or a private key.</p>
</div></div><divclass="page-separator"></div><aname="/v5/api/utils/strings/-%23-strings"></a><aname="/v5/api/utils/strings/-%23-strings"></a><aname="/v5/api/utils/strings/"></a><h1class="show-anchors"><div>Strings<divclass="anchors"><aclass="self"href="#/v5/api/utils/strings/-%23-strings"></a></div></div></h1><p>Tra la la</p>
<aname="/v5/api/utils/strings/-%23-Bytes32String"></a><aname="/v5/api/utils/strings/-%23-strings--Bytes32String"></a><aname="/v5/api/utils/strings/"></a><h2class="show-anchors"><div>Bytes32String<divclass="anchors"><aclass="self"href="#/v5/api/utils/strings/-%23-Bytes32String"></a></div></div></h2><p>A string in Solidity is length prefixed with its 256-bit (32 byte) length, which means that even short strings require 2 words (64 bytes) of storage.</p>
<p>In many cases, we deal with short strings, so instead of prefixing the string with its length, we can null-terminate it and fit it in a single word (32 bytes). Since we need only a single byte for the null termination, we can store strings up to 31 bytes long in a word.</p>
<divclass="definition container-box note"><divclass="term">Note</div><divclass="body"><p>Strings that are 31 <u><i>bytes</i></u> long may contain fewer than 31 <u><i>characters</i></u>, since UTF-8 requires multiple bytes to encode international characters.</p>
</div></div><aname="/v5/api/utils/strings/-%23-utils-parseBytes32"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="method">parseBytes32String</span><spanclass="symbol">(</span><spanclass="param">aBytesLike</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">string</span><divclass="anchors"><aclass="self"href="#/v5/api/utils/strings/-%23-utils-parseBytes32"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/strings/src.ts/bytes32.ts#L21">source</a></div></div><divclass="body"><p>Returns the decoded string represented by the <codeclass="inline">Bytes32</code> encoded data.</p>
</div></div><aname="/v5/api/utils/strings/-%23-utils-formatBytes32"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="method">formatBytes32String</span><spanclass="symbol">(</span><spanclass="param">text</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 >></span><divclass="anchors"><aclass="self"href="#/v5/api/utils/strings/-%23-utils-formatBytes32"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/strings/src.ts/bytes32.ts#L9">source</a></div></div><divclass="body"><p>Returns a <codeclass="inline">bytes32</code> string representation of <i>text</i>. If the length of <i>text</i> exceeds 31 bytes, it will throw an error.</p>
<aname="/v5/api/utils/strings/-%23-utils-toUtf8Bytes"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="method">toUtf8Bytes</span><spanclass="symbol">(</span><spanclass="param">text</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">form</span> = <spanclass="param">current</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Uint8Array</span><divclass="anchors"><aclass="self"href="#/v5/api/utils/strings/-%23-utils-toUtf8Bytes"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/strings/src.ts/utf8.ts#L202">source</a></div></div><divclass="body"><p>Returns the UTF-8 bytes of <i>text</i>, optionally normalizing it using the <ahref="#/v5/api/utils/strings/-%23-strings--unicode-normalization-form">UnicodeNormalizationForm</a><i>form</i>.</p>
</div></div><aname="/v5/api/utils/strings/-%23-utils-toUtf8CodePoints"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="method">toUtf8CodePoints</span><spanclass="symbol">(</span><spanclass="param">text</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">form</span> = <spanclass="param">current</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Array< number ></span><divclass="anchors"><aclass="self"href="#/v5/api/utils/strings/-%23-utils-toUtf8CodePoints"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/strings/src.ts/utf8.ts#L293">source</a></div></div><divclass="body"><p>Returns the Array of codepoints of <i>text</i>, optionally normalized using the <ahref="#/v5/api/utils/strings/-%23-strings--unicode-normalization-form">UnicodeNormalizationForm</a><i>form</i>.</p>
</div></div><divclass="definition container-box note"><divclass="term">Note</div><divclass="body"><p>This function correctly splits each <b>user-perceived character</b> into its codepoint, accounting for surrogate pairs. This should not be confused with <codeclass="inline">string.split("")</code>, which destroys surrogate pairs, spliting between each UTF-16 codeunit instead.</p>
</div></div><aname="/v5/api/utils/strings/-%23-utils-toUtf8String"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="method">toUtf8String</span><spanclass="symbol">(</span><spanclass="param">aBytesLike</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">onError</span> = <spanclass="param">error</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">string</span><divclass="anchors"><aclass="self"href="#/v5/api/utils/strings/-%23-utils-toUtf8String"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/strings/src.ts/utf8.ts#L289">source</a></div></div><divclass="body"><p>Returns the string represented by the UTF-8 bytes of <i>aBytesLike</i>.</p>
<p>The <i>onError</i> is a <ahref="#/v5/api/utils/strings/-%23-strings--error-handling">Custom UTF-8 Error function</a> and if not specified it defaults to the <ahref="#/v5/api/utils/strings/-%23-strings--Utf8Error">error</a> function, which throws an error on <b>any</b> UTF-8 error.</p>
</div></div><aname="/v5/api/utils/strings/-%23-strings--unicode-normalization-form"></a><aname="/v5/api/utils/strings/-%23-strings--strings--unicode-normalization-form"></a><aname="/v5/api/utils/strings/"></a><h2class="show-anchors"><div>UnicodeNormalizationForm<divclass="anchors"><aclass="self"href="#/v5/api/utils/strings/-%23-strings--unicode-normalization-form"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/strings/src.ts/utf8.ts#L11">source</a></div></div></h2><p>There are several <ahref="https://en.wikipedia.org/wiki/Unicode_equivalence">commonly used forms</a> when normalizing UTF-8 data, which allow strings to be compared or hashed in a stable way.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="path">UnicodeNormalizationForm</span><spanclass="symbol">.</span><spanclass="method">current</span><divclass="anchors"></div></div><divclass="body"><p>Maintain the current normalization form.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="path">UnicodeNormalizationForm</span><spanclass="symbol">.</span><spanclass="method">NFC</span><divclass="anchors"></div></div><divclass="body"><p>The Composed Normalization Form. This form uses single codepoints which represent the fully composed character.</p>
<p>For example, the <b>é</b> is a single codepoint, <codeclass="inline">0x00e9</code>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="path">UnicodeNormalizationForm</span><spanclass="symbol">.</span><spanclass="method">NFD</span><divclass="anchors"></div></div><divclass="body"><p>The Decomposed Normalization Form. This form uses multiple codepoints (when necessary) to compose a character.</p>
<p>For example, the <b>é</b> is made up of two codepoints, <codeclass="inline">"0x0065"</code> (which is the letter <codeclass="inline">"e"</code>) and <codeclass="inline">"0x0301"</code> which is a special diacritic UTF-8 codepoint which indicates the previous character should have an acute accent.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="path">UnicodeNormalizationForm</span><spanclass="symbol">.</span><spanclass="method">NFKC</span><divclass="anchors"></div></div><divclass="body"><p>The Composed Normalization Form with Canonical Equivalence. The Canonical representation folds characters which have the same syntactic representation but different semantic meaning.</p>
<p>For example, the Roman Numeral <b>I</b>, which has a UTF-8 codepoint <codeclass="inline">"0x2160"</code>, is folded into the capital letter I, <codeclass="inline">"0x0049"</code>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="path">UnicodeNormalizationForm</span><spanclass="symbol">.</span><spanclass="method">NFKD</span><divclass="anchors"></div></div><divclass="body"><p>The Decomposed Normalization Form with Canonical Equivalence. See NFKC for more an example.</p>
</div></div><divclass="definition container-box note"><divclass="term">Note</div><divclass="body"><p>Only certain specified characters are folded in Canonical Equivalence, and thus it should <b>not</b> be considered a method to acheive <i>any</i> level of security from <ahref="https://en.wikipedia.org/wiki/IDN_homograph_attack">homoglyph attacks</a>.</p>
</div></div><aname="/v5/api/utils/strings/-%23-strings--error-handling"></a><aname="/v5/api/utils/strings/-%23-strings--strings--error-handling"></a><aname="/v5/api/utils/strings/"></a><h2class="show-anchors"><div>Custom UTF-8 Error Handling<divclass="anchors"><aclass="self"href="#/v5/api/utils/strings/-%23-strings--error-handling"></a></div></div></h2><p>When converting a string to its codepoints, there is the possibility of invalid byte sequences. Since certain situations may need specific ways to handle UTF-8 errors, a custom error handling function can be used, which has the signature:</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="method">errorFunction</span><spanclass="symbol">(</span><spanclass="param">reason</span><spanclass="symbol">,</span><spanclass="param">offset</span><spanclass="symbol">,</span><spanclass="param">bytes</span><spanclass="symbol">,</span><spanclass="param">output</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">badCodepoint</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">number</span><divclass="anchors"></div></div><divclass="body"><p>The <i>reason</i> is one of the <ahref="#/v5/api/utils/strings/-%23-strings--error-reasons">UTF-8 Error Reasons</a>, <i>offset</i> is the index into <i>bytes</i> where the error was first encountered, output is the list of codepoints already processed (and may be modified) and in certain Error Reasons, the <i>badCodepoint</i> indicates the currently computed codepoint, but which would be rejected because its value is invalid.</p>
<p>This function should return the number of bytes to skip past keeping in mind the value at <i>offset</i> will already be consumed.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="path">Utf8ErrorReason</span><spanclass="symbol">.</span><spanclass="method">BAD_PREFIX</span><divclass="anchors"></div></div><divclass="body"><p>A byte was encountered which is invalid to begin a UTF-8 byte sequence with.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="path">Utf8ErrorReason</span><spanclass="symbol">.</span><spanclass="method">MISSING_CONTINUE</span><divclass="anchors"></div></div><divclass="body"><p>A UTF-8 sequence was begun, but did not have enough continuation bytes for the sequence. For this error the <i>ofset</i> is the index at which a continuation byte was expected.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="path">Utf8ErrorReason</span><spanclass="symbol">.</span><spanclass="method">OUT_OF_RANGE</span><divclass="anchors"></div></div><divclass="body"><p>The computed codepoint is outside the range for valid UTF-8 codepoints (i.e. the codepoint is greater than 0x10ffff). This reason will pass the computed <i>badCountpoint</i> into the custom error function.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="path">Utf8ErrorReason</span><spanclass="symbol">.</span><spanclass="method">OVERLONG</span><divclass="anchors"></div></div><divclass="body"><p>Due to the way UTF-8 allows variable length byte sequences to be used, it is possible to have multiple representations of the same character, which means <ahref="https://en.wikipedia.org/wiki/UTF-8#Overlong_encodings">overlong sequences</a> allow for a non-distinguished string to be formed, which can impact security as multiple strings that are otherwise equal can have different hashes.</p>
<p>Generally, overlong sequences are an attempt to circumvent some part of security, but in rare cases may be produced by lazy libraries or used to encode the null terminating character in a way that is safe to include in a <codeclass="inline">char*</code>.</p>
<p>This reason will pass the computed <i>badCountpoint</i> into the custom error function, which is actually a valid codepoint, just one that was arrived at through unsafe methods.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="path">Utf8ErrorReason</span><spanclass="symbol">.</span><spanclass="method">OVERRUN</span><divclass="anchors"></div></div><divclass="body"><p>The string does not have enough characters remaining for the length of this sequence.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="path">Utf8ErrorReason</span><spanclass="symbol">.</span><spanclass="method">UNEXPECTED_CONTINUE</span><divclass="anchors"></div></div><divclass="body"><p>This error is similar to BAD_PREFIX, since a continuation byte cannot begin a valid sequence, but many may wish to process this differently. However, most developers would want to trap this and perform the same operation as a BAD_PREFIX.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="path">Utf8ErrorReason</span><spanclass="symbol">.</span><spanclass="method">UTF16_SURROGATE</span><divclass="anchors"></div></div><divclass="body"><p>The computed codepoint represents a value reserved for UTF-16 surrogate pairs. This reason will pass the computed surrogate half <i>badCountpoint</i> into the custom error function.</p>
</div></div><aname="/v5/api/utils/strings/-%23-strings--strings--error-handling--provided-utf-8-error-handling-functions"></a><aname="/v5/api/utils/strings/"></a><h3class="show-anchors"><div>Provided UTF-8 Error Handling Functions<divclass="anchors"><aclass="self"href="#/v5/api/utils/strings/-%23-strings--strings--error-handling--provided-utf-8-error-handling-functions"></a></div></div></h3><p>There are already several functions available for the most common situations.</p>
<aname="/v5/api/utils/strings/-%23-strings--Utf8Error"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="path">Utf8ErrorFuncs</span><spanclass="symbol">.</span><spanclass="method">error</span><divclass="anchors"><aclass="self"href="#/v5/api/utils/strings/-%23-strings--Utf8Error"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/strings/src.ts/utf8.ts#L55">source</a></div></div><divclass="body"><p>The will throw an error on <b>any</b> error with a UTF-8 sequence, including invalid prefix bytes, overlong sequences, UTF-16 surrogate pairs.</p>
</div></div><aname="/v5/api/utils/strings/-%23-strings--Utf8Ignore"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="path">Utf8ErrorFuncs</span><spanclass="symbol">.</span><spanclass="method">ignore</span><divclass="anchors"><aclass="self"href="#/v5/api/utils/strings/-%23-strings--Utf8Ignore"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/strings/src.ts/utf8.ts#L59">source</a></div></div><divclass="body"><p>This will drop all invalid sequences (by consuming invalid prefix bytes and any following continuation bytes) from the final string as well as permit overlong sequences to be converted to their equivalent string.</p>
</div></div><aname="/v5/api/utils/strings/-%23-strings--Utf8Replace"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="path">Utf8ErrorFuncs</span><spanclass="symbol">.</span><spanclass="method">replace</span><divclass="anchors"><aclass="self"href="#/v5/api/utils/strings/-%23-strings--Utf8Replace"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/strings/src.ts/utf8.ts#L81">source</a></div></div><divclass="body"><p>This will replace all invalid sequences (by consuming invalid prefix bytes and any following continuation bytes) with the <ahref="https://en.wikipedia.org/wiki/Specials_%28Unicode_block%29#Replacement_character">UTF-8 Replacement Character</a>, (i.e. U+FFFD).</p>
<aname="/v5/api/utils/transactions/-%23-UnsignedTransaction"></a><aname="/v5/api/utils/transactions/-%23-transactions--transactions--types--UnsignedTransaction"></a><aname="/v5/api/utils/transactions/"></a><h3class="show-anchors"><div>UnsignedTransaction<divclass="anchors"><aclass="self"href="#/v5/api/utils/transactions/-%23-UnsignedTransaction"></a></div></div></h3><p>An unsigned transaction represents a transaction that has not been signed and its values are flexible as long as they are not ambiguous.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">unsignedTransaction</span><spanclass="symbol">.</span><spanclass="method">to</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/address/-%23-address">Address</a>></span><divclass="anchors"></div></div><divclass="body"><p>The addres this transaction is to.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">unsignedTransaction</span><spanclass="symbol">.</span><spanclass="method">nonce</span><spanclass="arrow">⇒</span><spanclass="returns">number</span><divclass="anchors"></div></div><divclass="body"><p>The nonce of this transaction.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">unsignedTransaction</span><spanclass="symbol">.</span><spanclass="method">gasLimit</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/bignumber/-%23-BigNumberish">BigNumberish</a></span><divclass="anchors"></div></div><divclass="body"><p>The gas limit for this transaction.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">unsignedTransaction</span><spanclass="symbol">.</span><spanclass="method">gasPrice</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/bignumber/-%23-BigNumberish">BigNumberish</a></span><divclass="anchors"></div></div><divclass="body"><p>The gas price for this transaction.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">unsignedTransaction</span><spanclass="symbol">.</span><spanclass="method">data</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/bytes/-%23-BytesLike">BytesLike</a></span><divclass="anchors"></div></div><divclass="body"><p>The data for this transaction.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">unsignedTransaction</span><spanclass="symbol">.</span><spanclass="method">value</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/bignumber/-%23-BigNumberish">BigNumberish</a></span><divclass="anchors"></div></div><divclass="body"><p>The value (in wei) for this transaction.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">unsignedTransaction</span><spanclass="symbol">.</span><spanclass="method">chainId</span><spanclass="arrow">⇒</span><spanclass="returns">number</span><divclass="anchors"></div></div><divclass="body"><p>The chain ID for this transaction. If the chain ID is 0 or null, then <ahref="https://eips.ethereum.org/EIPS/eip-155">EIP-155</a> is disabled and legacy signing is used, unless overridden in a signature.</p>
</div></div><aname="/v5/api/utils/transactions/-%23-Transaction"></a><aname="/v5/api/utils/transactions/-%23-transactions--transactions--types--Transaction"></a><aname="/v5/api/utils/transactions/"></a><h3class="show-anchors"><div>Transaction<divclass="anchors"><aclass="self"href="#/v5/api/utils/transactions/-%23-Transaction"></a></div></div></h3><p>A generic object to represent a transaction.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">transaction</span><spanclass="symbol">.</span><spanclass="method">hash</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 >></span><divclass="anchors"></div></div><divclass="body"><p>The transaction hash, which can be used as an identifier for <i>transaction</i>. This is the keccak256 of the serialized RLP encoded representation of <i>transaction</i>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">unsignedTransaction</span><spanclass="symbol">.</span><spanclass="method">to</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/address/-%23-address">Address</a>></span><divclass="anchors"></div></div><divclass="body"><p>The address <i>transaction</i> is to.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">transaction</span><spanclass="symbol">.</span><spanclass="method">from</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/address/-%23-address">Address</a>></span><divclass="anchors"></div></div><divclass="body"><p>The address <i>transaction</i> is from.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">transaction</span><spanclass="symbol">.</span><spanclass="method">nonce</span><spanclass="arrow">⇒</span><spanclass="returns">number</span><divclass="anchors"></div></div><divclass="body"><p>The nonce for <i>transaction</i>. Each transaction sent to the network from an account includes this, which ensures the order and non-replayability of a transaction. This must be equal to the current number of transactions ever sent to the network by the <b>from</b> address.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">transaction</span><spanclass="symbol">.</span><spanclass="method">gasLimit</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/bignumber/">BigNumber</a></span><divclass="anchors"></div></div><divclass="body"><p>The gas limit for <i>transaction</i>. An account must have enough ether to cover the gas (at the specified <b>gasPrice</b>). Any unused gas is refunded at the end of the transaction, and if there is insufficient gas to complete execution, the effects of the trasaction are reverted, but the gas is <b>fully consumed</b> and an out-of-gas error occurs.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">transaction</span><spanclass="symbol">.</span><spanclass="method">gasPrice</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/bignumber/">BigNumber</a></span><divclass="anchors"></div></div><divclass="body"><p>The price (in wei) per unit of gas for <i>transaction</i>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">transaction</span><spanclass="symbol">.</span><spanclass="method">data</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/bytes/-%23-BytesLike">BytesLike</a></span><divclass="anchors"></div></div><divclass="body"><p>The data for <i>transaction</i>. In a contract this is the call data.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">transaction</span><spanclass="symbol">.</span><spanclass="method">value</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/bignumber/">BigNumber</a></span><divclass="anchors"></div></div><divclass="body"><p>The value (in wei) for <i>transaction</i>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">transaction</span><spanclass="symbol">.</span><spanclass="method">chainId</span><spanclass="arrow">⇒</span><spanclass="returns">number</span><divclass="anchors"></div></div><divclass="body"><p>The chain ID for <i>transaction</i>. This is used as part of <ahref="https://eips.ethereum.org/EIPS/eip-155">EIP-155</a> to prevent replay attacks on different networks.</p>
<p>For example, if a transaction was made on ropsten with an account also used on homestead, it would be possible for a transaction signed on ropsten to be executed on homestead, which is likely unintended.</p>
<p>There are situations where replay may be desired, however these are very rare and it is almost always recommended to specify the chain ID.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">transaction</span><spanclass="symbol">.</span><spanclass="method">r</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 >></span><divclass="anchors"></div></div><divclass="body"><p>The r portion of the elliptic curve signatures for <i>transaction</i>. This is more accurately, the x coordinate of the point r (from which the y can be computed, along with v).</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">transaction</span><spanclass="symbol">.</span><spanclass="method">s</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 >></span><divclass="anchors"></div></div><divclass="body"><p>The s portion of the elliptic curve signatures for <i>transaction</i>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">transaction</span><spanclass="symbol">.</span><spanclass="method">v</span><spanclass="arrow">⇒</span><spanclass="returns">number</span><divclass="anchors"></div></div><divclass="body"><p>The v portion of the elliptic curve signatures for <i>transaction</i>. This is used to refine which of the two possible points a given x-coordinate can have, and in <ahref="https://eips.ethereum.org/EIPS/eip-155">EIP-155</a> is additionally used to encode the chain ID into the serialized transaction.</p>
<aname="/v5/api/utils/transactions/-%23-utils-parseTransaction"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="method">parseTransaction</span><spanclass="symbol">(</span><spanclass="param">aBytesLike</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/transactions/-%23-Transaction">Transaction</a></span><divclass="anchors"><aclass="self"href="#/v5/api/utils/transactions/-%23-utils-parseTransaction"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/transactions/src.ts/index.ts#L165">source</a></div></div><divclass="body"><p>Parses the transaction properties from a serialized transactions.</p>
</div></div><aname="/v5/api/utils/transactions/-%23-utils-serializeTransaction"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="method">serializeTransaction</span><spanclass="symbol">(</span><spanclass="param">tx</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">signature</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>></span><divclass="anchors"><aclass="self"href="#/v5/api/utils/transactions/-%23-utils-serializeTransaction"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/transactions/src.ts/index.ts#L85">source</a></div></div><divclass="body"><p>Computes the serialized <i>transaction</i>, optionally serialized with the a <i>signature</i>. If <i>signature</i> is not present, the unsigned serialized transaction is returned, which can be used to compute the hash necessary to sign.</p>
<p>This function uses <ahref="https://eips.ethereum.org/EIPS/eip-155">EIP-155</a> if a chainId is provided, otherwise legacy serialization is used. It is <b>highly</b> recommended to always specify a <i>chainId</i>.</p>
<p>If <i>signature</i> includes a chain ID (explicitly or implicitly by using an <ahref="https://eips.ethereum.org/EIPS/eip-155">EIP-155</a><codeclass="inline">v</code> or <codeclass="inline">_vs</code>) it will be used to compute the chain ID.</p>
<p>If there is a mismatch between the chain ID of <i>transaction</i> and <i>signature</i> an error is thrown.</p>
<aname="/v5/api/utils/web/-%23-utils-fetchJson"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="method">fetchJson</span><spanclass="symbol">(</span><spanclass="param">urlOrConnectionInfo</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">json</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">processFunc</span><spanclass="symbol">]</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Promise< any ></span><divclass="anchors"><aclass="self"href="#/v5/api/utils/web/-%23-utils-fetchJson"></a></div></div><divclass="body"><p>Fetch and parse the JSON content from <i>urlOrConnectionInfo</i>, with the optiona body <i>json</i> and optionally processing the result with <i>processFun</i> before returning it.</p>
</div></div><aname="/v5/api/utils/web/-%23-utils-poll"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">utils</span><spanclass="symbol">.</span><spanclass="method">poll</span><spanclass="symbol">(</span><spanclass="param">pollFunc</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">options</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Promise< any ></span><divclass="anchors"><aclass="self"href="#/v5/api/utils/web/-%23-utils-poll"></a></div></div><divclass="body"><p>Repeatedly call pollFunc using the <ahref="#/v5/api/utils/web/-%23-PollOptions">PollOptions</a> until it returns a value other than undefined.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">connection</span><spanclass="symbol">.</span><spanclass="method">url</span><spanclass="arrow">⇒</span><spanclass="returns">string</span><divclass="anchors"></div></div><divclass="body"><p>The URL to connect to.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">connection</span><spanclass="symbol">.</span><spanclass="method">user</span><spanclass="arrow">⇒</span><spanclass="returns">string</span><divclass="anchors"></div></div><divclass="body"><p>The username to use for <ahref="https://en.wikipedia.org/wiki/Basic_access_authentication">Basic Authentication</a>. The default is null (i.e. do not use basic authentication)</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">connection</span><spanclass="symbol">.</span><spanclass="method">password</span><spanclass="arrow">⇒</span><spanclass="returns">string</span><divclass="anchors"></div></div><divclass="body"><p>The password to use for <ahref="https://en.wikipedia.org/wiki/Basic_access_authentication">Basic Authentication</a>. The default is null (i.e. do not use basic authentication)</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">connection</span><spanclass="symbol">.</span><spanclass="method">allowInsecureAuthentication</span><spanclass="arrow">⇒</span><spanclass="returns">boolean</span><divclass="anchors"></div></div><divclass="body"><p>Allow <ahref="https://en.wikipedia.org/wiki/Basic_access_authentication">Basic Authentication</a> over non-secure HTTP. The default is false.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">connection</span><spanclass="symbol">.</span><spanclass="method">timeout</span><spanclass="arrow">⇒</span><spanclass="returns">number</span><divclass="anchors"></div></div><divclass="body"><p>How long to wait before rejecting with a <i>timeout</i> error.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">connection</span><spanclass="symbol">.</span><spanclass="method">headers</span><spanclass="arrow">⇒</span><spanclass="returns">{[key:string]:string}</span><divclass="anchors"></div></div><divclass="body"><p>Additional headers to include in the connection.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">options</span><spanclass="symbol">.</span><spanclass="method">timeout</span><spanclass="arrow">⇒</span><spanclass="returns">number</span><divclass="anchors"></div></div><divclass="body"><p>The amount of time allowed to ellapse before triggering a timeout error.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">options</span><spanclass="symbol">.</span><spanclass="method">floor</span><spanclass="arrow">⇒</span><spanclass="returns">number</span><divclass="anchors"></div></div><divclass="body"><p>The minimum time limit to allow for <ahref="https://en.wikipedia.org/wiki/Exponential_backoff">Exponential Backoff</a>.</p>
<p>The default is 0s.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">options</span><spanclass="symbol">.</span><spanclass="method">ceiling</span><spanclass="arrow">⇒</span><spanclass="returns">number</span><divclass="anchors"></div></div><divclass="body"><p>The maximum time limit to allow for <ahref="https://en.wikipedia.org/wiki/Exponential_backoff">Exponential Backoff</a>.</p>
<p>The default is 10s.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">options</span><spanclass="symbol">.</span><spanclass="method">interval</span><spanclass="arrow">⇒</span><spanclass="returns">number</span><divclass="anchors"></div></div><divclass="body"><p>The interval used during <ahref="https://en.wikipedia.org/wiki/Exponential_backoff">Exponential Backoff</a> calculation.</p>
<p>The default is 250ms.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">options</span><spanclass="symbol">.</span><spanclass="method">retryLimit</span><spanclass="arrow">⇒</span><spanclass="returns">number</span><divclass="anchors"></div></div><divclass="body"><p>The number of times to retry in the event of an error or <i>undefined</i> is returned.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">options</span><spanclass="symbol">.</span><spanclass="method">onceBlock</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/providers/provider/">Provider</a></span><divclass="anchors"></div></div><divclass="body"><p>If this is specified, the polling will wait on new blocks from <i>provider</i> before attempting the <i>pollFunc</i> again.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">options</span><spanclass="symbol">.</span><spanclass="method">oncePoll</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/providers/provider/">Provider</a></span><divclass="anchors"></div></div><divclass="body"><p>If this is specified, the polling will occur on each poll cycle of <i>provider</i> before attempting the <i>pollFunc</i> again.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">wordlist</span><spanclass="symbol">.</span><spanclass="method">locale</span><spanclass="arrow">⇒</span><spanclass="returns">string</span><divclass="anchors"></div></div><divclass="body"><p>The locale for this wordlist.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">wordlist</span><spanclass="symbol">.</span><spanclass="method">getWord</span><spanclass="symbol">(</span><spanclass="param">index</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">string</span><divclass="anchors"></div></div><divclass="body"><p>Returns the word at <i>index</i>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">wordlist</span><spanclass="symbol">.</span><spanclass="method">getWordIndex</span><spanclass="symbol">(</span><spanclass="param">word</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">number</span><divclass="anchors"></div></div><divclass="body"><p>Returns the index of <i>word</i> within the wordlist.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">wordlist</span><spanclass="symbol">.</span><spanclass="method">split</span><spanclass="symbol">(</span><spanclass="param">mnemonic</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Array< string ></span><divclass="anchors"></div></div><divclass="body"><p>Returns the mnemonic split into each individual word, according to a locale's valid whitespace character set.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">wordlist</span><spanclass="symbol">.</span><spanclass="method">join</span><spanclass="symbol">(</span><spanclass="param">words</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">string</span><divclass="anchors"></div></div><divclass="body"><p>Returns the mnemonic by joining <i>words</i> together using the whitespace that is standard for the locale.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">Wordlist</span><spanclass="symbol">.</span><spanclass="method">check</span><spanclass="symbol">(</span><spanclass="param">wordlists</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 >></span><divclass="anchors"></div></div><divclass="body"><p>Checks that all words map both directions correctly and return the hash of the lists. Sub-classes should use this to validate the wordlist is correct against the official wordlist hash.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">Wordlist</span><spanclass="symbol">.</span><spanclass="method">register</span><spanclass="symbol">(</span><spanclass="param">wordlist</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">name</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">void</span><divclass="anchors"></div></div><divclass="body"><p>Register a wordlist with the list of wordlists, optionally overriding the registered <i>name</i>.</p>
</div></div><aname="/v5/api/utils/wordlists/-%23-wordlists--languages"></a><aname="/v5/api/utils/wordlists/-%23-wordlists--wordlists--languages"></a><aname="/v5/api/utils/wordlists/"></a><h2class="show-anchors"><div>Languages<divclass="anchors"><aclass="self"href="#/v5/api/utils/wordlists/-%23-wordlists--languages"></a></div></div></h2><p>The <ahref="https://github.com/bitcoin/bips/blob/master/bip-0039/bip-0039-wordlists.md">official wordlists</a> availalbe in at `ethers.wordlists`. In the browser, only the english langauge is available by default; to include the others (which increases the size of the library), see the dist files in the `ethers` package.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">wordlists</span><spanclass="symbol">.</span><spanclass="method">en</span><spanclass="arrow">⇒</span><spanclass="returns">Wordlist</span><divclass="anchors"></div></div><divclass="body"><p>The English <ahref="#/v5/api/utils/wordlists/-%23-Wordlist">Wordlist</a>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">wordlists</span><spanclass="symbol">.</span><spanclass="method">fr</span><spanclass="arrow">⇒</span><spanclass="returns">Wordlist</span><divclass="anchors"></div></div><divclass="body"><p>The French <ahref="#/v5/api/utils/wordlists/-%23-Wordlist">Wordlist</a>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">wordlists</span><spanclass="symbol">.</span><spanclass="method">it</span><spanclass="arrow">⇒</span><spanclass="returns">Wordlist</span><divclass="anchors"></div></div><divclass="body"><p>The Italian <ahref="#/v5/api/utils/wordlists/-%23-Wordlist">Wordlist</a>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">wordlists</span><spanclass="symbol">.</span><spanclass="method">ja</span><spanclass="arrow">⇒</span><spanclass="returns">Wordlist</span><divclass="anchors"></div></div><divclass="body"><p>The Japanese <ahref="#/v5/api/utils/wordlists/-%23-Wordlist">Wordlist</a>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">wordlists</span><spanclass="symbol">.</span><spanclass="method">ko</span><spanclass="arrow">⇒</span><spanclass="returns">Wordlist</span><divclass="anchors"></div></div><divclass="body"><p>The Korean <ahref="#/v5/api/utils/wordlists/-%23-Wordlist">Wordlist</a>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">wordlists</span><spanclass="symbol">.</span><spanclass="method">zh_cn</span><spanclass="arrow">⇒</span><spanclass="returns">Wordlist</span><divclass="anchors"></div></div><divclass="body"><p>The Simplified Chinese <ahref="#/v5/api/utils/wordlists/-%23-Wordlist">Wordlist</a>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">ethers</span><spanclass="symbol">.</span><spanclass="path">wordlists</span><spanclass="symbol">.</span><spanclass="method">zh_tw</span><spanclass="arrow">⇒</span><spanclass="returns">Wordlist</span><divclass="anchors"></div></div><divclass="body"><p>The Traditional Chinese <ahref="#/v5/api/utils/wordlists/-%23-Wordlist">Wordlist</a>.</p>
</div></div><divclass="page-separator"></div><aname="/v5/api/other/-%23-other-libraries"></a><aname="/v5/api/other/"></a><h1class="show-anchors"><div>Other Libraries<divclass="anchors"><aclass="self"href="#/v5/api/other/-%23-other-libraries"></a></div></div></h1><p>Now that ethers is more modular, it is possible to have additional ancillary packages, which are not part of the core but optionally add functionality only needed in certain situations.</p>
<divclass="toc"><divstyle="padding-left: 0px"><spanclass="bullet">•</span><ahref="#/v5/api/other/assembly/">Assembly</a></div><divstyle="padding-left: 0px"><spanclass="bullet">•</span><ahref="#/v5/api/other/hardware/">Hardware Wallets</a></div></div><divclass="page-separator"></div><aname="/v5/api/other/assembly/-%23-assembly"></a><aname="/v5/api/other/assembly/"></a><h1class="show-anchors"><div>Assembly<divclass="anchors"><aclass="self"href="#/v5/api/other/assembly/-%23-assembly"></a></div></div></h1><p>This module should still be considered fairly experimental.</p>
<divclass="toc"><divstyle="padding-left: 0px"><spanclass="bullet">•</span><ahref="#/v5/api/other/assembly/dialect/">Ethers ASM Dialect</a></div><divstyle="padding-left: 0px"><spanclass="bullet">•</span><ahref="#/v5/api/other/assembly/api/">Utilities</a></div><divstyle="padding-left: 0px"><spanclass="bullet">•</span><ahref="#/v5/api/other/assembly/ast/">Abstract Syntax Tree</a></div></div><divclass="page-separator"></div><aname="/v5/api/other/assembly/dialect/-%23-asm-dialect"></a><aname="/v5/api/other/assembly/dialect/-%23-asm-dialect"></a><aname="/v5/api/other/assembly/dialect/"></a><h1class="show-anchors"><div>Ethers ASM Dialect<divclass="anchors"><aclass="self"href="#/v5/api/other/assembly/dialect/-%23-asm-dialect"></a></div></div></h1><p>This provides a quick, high-level overcview of the <b>Ethers ASM Dialect</b> for EVM, which is defined by the <ahref="https://github.com/ethers-io/ethers.js/blob/master/packages/asm/grammar.jison">Ethers ASM Dialect Grammar</a></p>
<p>Once a program is compiled by a higher level langauge into ASM (assembly), or hand-coded directly in ASM, it needs to be assembled into bytecode.</p>
<p>The assembly process performs a very small set of operations and is intentionally simple and closely related to the underlying EVM bytecode.</p>
<p>Operations include embedding programs within programs (for example the deployment bootstrap has the runtime embedded in it) and computing the necessary offsets for jump operations.</p>
<p>The <ahref="#/v5/cli/asm/">Command-Line Assembler</a> can be used to assemble an <i>Ethers ASM Dialect</i> file or to disassemble bytecode into its human-readable (ish) opcodes and literals.</p>
<aname="/v5/api/other/assembly/dialect/-%23-asm-dialect-opcode"></a><aname="/v5/api/other/assembly/dialect/-%23-asm-dialect--asm-dialect-opcode"></a><aname="/v5/api/other/assembly/dialect/"></a><h2class="show-anchors"><div>Opcodes<divclass="anchors"><aclass="self"href="#/v5/api/other/assembly/dialect/-%23-asm-dialect-opcode"></a></div></div></h2><p>An <b>Opcode</b> may be provided in either a <i>functional</i> or <i>instructional</i> syntax. For Opcodes that require parameters, the <i>functional</i> syntax is recommended and the <i>instructional</i> syntax will raise a warning.</p>
<p>@TODO: Examples</p>
<aname="/v5/api/other/assembly/dialect/-%23-asm-dialect-label"></a><aname="/v5/api/other/assembly/dialect/-%23-asm-dialect--asm-dialect-label"></a><aname="/v5/api/other/assembly/dialect/"></a><h2class="show-anchors"><div>Labels<divclass="anchors"><aclass="self"href="#/v5/api/other/assembly/dialect/-%23-asm-dialect-label"></a></div></div></h2><p>A <b>Label</b> is a position in the program which can be jumped to. A <codeclass="inline">JUMPDEST</code> is automatically added to this point in the assembled output.</p>
<p>@TODO: Exmaples</p>
<aname="/v5/api/other/assembly/dialect/-%23-asm-dialect-literal"></a><aname="/v5/api/other/assembly/dialect/-%23-asm-dialect--asm-dialect-literal"></a><aname="/v5/api/other/assembly/dialect/"></a><h2class="show-anchors"><div>Literals<divclass="anchors"><aclass="self"href="#/v5/api/other/assembly/dialect/-%23-asm-dialect-literal"></a></div></div></h2><p>A <b>Literal</b> puts data on the stack when executed using a <codeclass="inline">PUSH</code> operation.</p>
<p>A <b>Literal</b> can be provided using a <ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a> or a decimal byte value.</p>
<p>@TODO: exmples</p>
<aname="/v5/api/other/assembly/dialect/-%23-asm-dialect-comment"></a><aname="/v5/api/other/assembly/dialect/-%23-asm-dialect--asm-dialect-comment"></a><aname="/v5/api/other/assembly/dialect/"></a><h2class="show-anchors"><div>Comments<divclass="anchors"><aclass="self"href="#/v5/api/other/assembly/dialect/-%23-asm-dialect-comment"></a></div></div></h2><p>To enter a comment in the <b>Ethers ASM Dialect</b>, any text following a semi-colon (i.e. <codeclass="inline">;</code>) is ignored by the assembler.</p>
<aname="/v5/api/other/assembly/dialect/-%23-asm-dialect-scope"></a><aname="/v5/api/other/assembly/dialect/-%23-asm-dialect--asm-dialect-scope"></a><aname="/v5/api/other/assembly/dialect/"></a><h2class="show-anchors"><div>Scopes<divclass="anchors"><aclass="self"href="#/v5/api/other/assembly/dialect/-%23-asm-dialect-scope"></a></div></div></h2><p>A common case in Ethereum is to have one program embedded in another.</p>
<p>The most common use of this is embedding a Contract <b>runtime bytecode</b> within a <b>deployment bytecode</b>, which can be used as <b>init code</b>.</p>
<p>When deploying a program to Ethereum, an <b>init transaction</b> is used. An <i>init transaction</i> has a null <codeclass="inline">to</code> address and contains bytecode in the <codeclass="inline">data</code>. This <codeclass="inline">data</code> bytecode is a program, that when executed returns some other bytecode as a result, this restul is the bytecode to be installed.</p>
<p>Therefore it is important that embedded code uses jumps relative to itself, not the entire program it is embedded in, which also means that a jump can <b>only</b> target its own scope, no parent or child scopes. This is enforced by the assembler.</p>
<p>A scope may access the offset of any child <ahref="#/v5/api/other/assembly/dialect/-%23-asm-dialect-datasegment">Data Segment</a> or child <ahref="#/v5/api/other/assembly/dialect/-%23-asm-dialect-scope">Scopes</a> (with respect to itself) and may access the length of any <ahref="#/v5/api/other/assembly/dialect/-%23-asm-dialect-datasegment">Data Segment</a> or <ahref="#/v5/api/other/assembly/dialect/-%23-asm-dialect-scope">Scopes</a> anywhere in the program.</p>
<p>Every program in the <b>Ethers ASM Dialect</b> has a top-leve scope named <codeclass="inline">_</code>.</p>
<aname="/v5/api/other/assembly/dialect/-%23-asm-dialect-datasegment"></a><aname="/v5/api/other/assembly/dialect/-%23-asm-dialect--asm-dialect-datasegment"></a><aname="/v5/api/other/assembly/dialect/"></a><h2class="show-anchors"><div>Data Segment<divclass="anchors"><aclass="self"href="#/v5/api/other/assembly/dialect/-%23-asm-dialect-datasegment"></a></div></div></h2><p>A <b>Data Segment</b> allows arbitrary data to be embedded into a program, which can be useful for lookup tables or deploy-time constants.</p>
<p>An emtpty <b>Data Segment</b> can also be used when a labelled location is required, but without the <codeclass="inline">JUMPDEST</code> which a <ahref="#/v5/api/other/assembly/dialect/-%23-asm-dialect-label">Labels</a> adds.</p>
<p>@TODO: Example</p>
<aname="/v5/api/other/assembly/dialect/-%23-asm-dialect-links"></a><aname="/v5/api/other/assembly/dialect/-%23-asm-dialect--asm-dialect-links"></a><aname="/v5/api/other/assembly/dialect/"></a><h2class="show-anchors"><div>Links<divclass="anchors"><aclass="self"href="#/v5/api/other/assembly/dialect/-%23-asm-dialect-links"></a></div></div></h2><p>A <b>Link</b> allows access to a <ahref="#/v5/api/other/assembly/dialect/-%23-asm-dialect-scope">Scopes</a>, <ahref="#/v5/api/other/assembly/dialect/-%23-asm-dialect-datasegment">Data Segment</a> or <ahref="#/v5/api/other/assembly/dialect/-%23-asm-dialect-label">Labels</a>.</p>
<p>To access the byte offset of a labelled item, use <codeclass="inline">$foobar</code>.</p>
<p>For a <ahref="#/v5/api/other/assembly/dialect/-%23-asm-dialect-label">Labels</a>, the target must be directly reachable within this scope. For a <ahref="#/v5/api/other/assembly/dialect/-%23-asm-dialect-datasegment">Data Segment</a> or a <ahref="#/v5/api/other/assembly/dialect/-%23-asm-dialect-scope">Scopes</a>, it can be inside the same scope or any child scope.</p>
<p>For a <ahref="#/v5/api/other/assembly/dialect/-%23-asm-dialect-datasegment">Data Segment</a> or a <ahref="#/v5/api/other/assembly/dialect/-%23-asm-dialect-label">Labels</a>, there is an additional type of <b>Link</b>, which provides the length of the data or bytecode respectively. A <b>Length Link</b> is accessed by <codeclass="inline">#foobar</code> and is pushed on the stack as a literal.</p>
<aname="/v5/api/other/assembly/dialect/-%23-asm-dialect-scripting"></a><aname="/v5/api/other/assembly/dialect/-%23-asm-dialect--asm-dialect-scripting"></a><aname="/v5/api/other/assembly/dialect/"></a><h2class="show-anchors"><div>Evaluation and Excution<divclass="anchors"><aclass="self"href="#/v5/api/other/assembly/dialect/-%23-asm-dialect-scripting"></a></div></div></h2>
<aname="/v5/api/other/assembly/api/-%23-asm-parse"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">asm</span><spanclass="symbol">.</span><spanclass="method">parse</span><spanclass="symbol">(</span><spanclass="param">code</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/other/assembly/ast/-%23-asm-node">Node</a></span><divclass="anchors"><aclass="self"href="#/v5/api/other/assembly/api/-%23-asm-parse"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/asm/src.ts/assembler.ts#L1245">source</a></div></div><divclass="body"><p>Parse an ethers-format assembly file and return the <ahref="#/v5/api/other/assembly/ast/">Abstract Syntax Tree</a>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">asm</span><spanclass="symbol">.</span><spanclass="method">assemble</span><spanclass="symbol">(</span><spanclass="param">node</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>></span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/asm/src.ts/assembler.ts#L1316">source</a></div></div><divclass="body"><p>Performs assembly of the <ahref="#/v5/api/other/assembly/ast/">Abstract Syntax Tree</a><i>node</i> and return the resulting bytecode representation.</p>
</div></div><aname="/v5/api/other/assembly/api/-%23-asm-utilities--disassembler"></a><aname="/v5/api/other/assembly/api/"></a><h2class="show-anchors"><div>Disassembler<divclass="anchors"><aclass="self"href="#/v5/api/other/assembly/api/-%23-asm-utilities--disassembler"></a></div></div></h2><p>The <b>Disassembler</b> utilities make it easy to convert bytecode into an object which can easily be examined for program structure.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">asm</span><spanclass="symbol">.</span><spanclass="method">disassemble</span><spanclass="symbol">(</span><spanclass="param">bytecode</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/other/assembly/api/-%23-asm-bytecode">Bytecode</a></span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/asm/src.ts/assembler.ts#L601">source</a></div></div><divclass="body"><p>Returns an array of Operations given <i>bytecode</i>.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">asm</span><spanclass="symbol">.</span><spanclass="method">formatBytecode</span><spanclass="symbol">(</span><spanclass="param">operations</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">string</span><divclass="anchors"><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/asm/src.ts/assembler.ts#L645">source</a></div></div><divclass="body"><p>Create a formatted output of an array of <ahref="#/v5/api/other/assembly/api/-%23-asm-operation">Operation</a>.</p>
</div></div><aname="/v5/api/other/assembly/api/-%23-asm-bytecode"></a><aname="/v5/api/other/assembly/api/-%23-asm-utilities--disassembler--asm-bytecode"></a><aname="/v5/api/other/assembly/api/"></a><h3class="show-anchors"><div>Bytecode<spanclass="inherits"> inherits Array<<ahref="#/v5/api/other/assembly/api/-%23-asm-operation">Operation</a>></span><divclass="anchors"><aclass="self"href="#/v5/api/other/assembly/api/-%23-asm-bytecode"></a></div></div></h3><p>Each arary index represents an operation, collapsing multi-byte operations (i.e. <codeclass="inline">PUSH</code>) into a single operation.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">bytecode</span><spanclass="symbol">.</span><spanclass="method">getOperation</span><spanclass="symbol">(</span><spanclass="param">offset</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/other/assembly/api/-%23-asm-operation">Operation</a></span><divclass="anchors"></div></div><divclass="body"><p>Get the operation at a given <i>offset</i> into the bytecode. This ensures that the byte at <i>offset</i> is an operation and not data contained within a <codeclass="inline">PUSH</code>, in which case null it returned.</p>
</div></div><aname="/v5/api/other/assembly/api/-%23-asm-operation"></a><aname="/v5/api/other/assembly/api/-%23-asm-utilities--disassembler--asm-operation"></a><aname="/v5/api/other/assembly/api/"></a><h3class="show-anchors"><div>Operation<divclass="anchors"><aclass="self"href="#/v5/api/other/assembly/api/-%23-asm-operation"></a></div></div></h3><p>An <b>Operation</b> is a single command from a disassembled bytecode stream.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">operation</span><spanclass="symbol">.</span><spanclass="method">opcode</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/other/assembly/api/-%23-asm-opcode">Opcode</a></span><divclass="anchors"></div></div><divclass="body"><p>The opcode for this Operation.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">operation</span><spanclass="symbol">.</span><spanclass="method">offset</span><spanclass="arrow">⇒</span><spanclass="returns">number</span><divclass="anchors"></div></div><divclass="body"><p>The offset into the bytecode for this Operation.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">operation</span><spanclass="symbol">.</span><spanclass="method">pushValue</span><spanclass="arrow">⇒</span><spanclass="returns">string<<ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>></span><divclass="anchors"></div></div><divclass="body"><p>If the opcode is a <codeclass="inline">PUSH</code>, this is the value of that push</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">asm</span><spanclass="symbol">.</span><spanclass="path">Opcode</span><spanclass="symbol">.</span><spanclass="method">from</span><spanclass="symbol">(</span><spanclass="param">valueOrMnemonic</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/other/assembly/api/-%23-asm-opcode">Opcode</a></span><divclass="anchors"></div></div><divclass="body"><p>Create a new instnace of an Opcode for a given numeric value (e.g. 0x60 is PUSH1) or mnemonic string (e.g. "PUSH1").</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">opcode</span><spanclass="symbol">.</span><spanclass="method">value</span><spanclass="arrow">⇒</span><spanclass="returns">number</span><divclass="anchors"></div></div><divclass="body"><p>The value (bytecode as a number) of this opcode.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">opcode</span><spanclass="symbol">.</span><spanclass="method">mnemonic</span><spanclass="arrow">⇒</span><spanclass="returns">string</span><divclass="anchors"></div></div><divclass="body"><p>The mnemonic string of this opcode.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">opcode</span><spanclass="symbol">.</span><spanclass="method">delta</span><spanclass="arrow">⇒</span><spanclass="returns">number</span><divclass="anchors"></div></div><divclass="body"><p>The number of items this opcode will consume from the stack.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">opcode</span><spanclass="symbol">.</span><spanclass="method">alpha</span><spanclass="arrow">⇒</span><spanclass="returns">number</span><divclass="anchors"></div></div><divclass="body"><p>The number of items this opcode will push onto the stack.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">opcode</span><spanclass="symbol">.</span><spanclass="method">doc</span><spanclass="arrow">⇒</span><spanclass="returns">string</span><divclass="anchors"></div></div><divclass="body"><p>A short description of what this opcode does.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">opcode</span><spanclass="symbol">.</span><spanclass="method">isMemory</span><spanclass="symbol">(</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">"read" | "write" | "full"</span><divclass="anchors"></div></div><divclass="body"><p>Returns true if the opcode accesses memory.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">opcode</span><spanclass="symbol">.</span><spanclass="method">isStatic</span><spanclass="symbol">(</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">boolean</span><divclass="anchors"></div></div><divclass="body"><p>Returns true if the opcode cannot change state.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">opcode</span><spanclass="symbol">.</span><spanclass="method">isJump</span><spanclass="symbol">(</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">boolean</span><divclass="anchors"></div></div><divclass="body"><p>Returns true if the opcode is a jumper operation.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">opcode</span><spanclass="symbol">.</span><spanclass="method">isPush</span><spanclass="symbol">(</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">number</span><divclass="anchors"></div></div><divclass="body"><p>Returns 0 if the opcode is not a <codeclass="inline">PUSH*</code>, or the number of bytes this opcode will push if it is.</p>
</div></div><divclass="page-separator"></div><aname="/v5/api/other/assembly/ast/-%23-asm-ast"></a><aname="/v5/api/other/assembly/ast/-%23-asm-ast"></a><aname="/v5/api/other/assembly/ast/"></a><h1class="show-anchors"><div>Abstract Syntax Tree<divclass="anchors"><aclass="self"href="#/v5/api/other/assembly/ast/-%23-asm-ast"></a></div></div></h1><p>Parsing a file using the <ahref="#/v5/api/other/assembly/dialect/">Ethers ASM Dialect</a> will generate an Abstract Syntax Tree. The root node will always be a <ahref="#/v5/api/other/assembly/ast/-%23-asm-scopenode">ScopeNode</a> whose name is <codeclass="inline">_</code>.</p>
<p>To parse a file into an Abstract Syntax tree, use the <ahref="#/v5/api/other/assembly/api/-%23-asm-parse">parse</a> function.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="method">offset</span><spanclass="arrow">⇒</span><spanclass="returns">number</span><divclass="anchors"></div></div><divclass="body"><p>The offset into the source code to the start of this node.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="method">length</span><spanclass="arrow">⇒</span><spanclass="returns">number</span><divclass="anchors"></div></div><divclass="body"><p>The length of characters in the source code to the end of this node.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="method">source</span><spanclass="arrow">⇒</span><spanclass="returns">string</span><divclass="anchors"></div></div><divclass="body"><p>The source code of this node.</p>
</div></div><aname="/v5/api/other/assembly/ast/-%23-asm-ast--nodes"></a><aname="/v5/api/other/assembly/ast/"></a><h2class="show-anchors"><div>Nodes<divclass="anchors"><aclass="self"href="#/v5/api/other/assembly/ast/-%23-asm-ast--nodes"></a></div></div></h2><p>@TODO: Place a diagram here showing the hierarchy</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">node</span><spanclass="symbol">.</span><spanclass="method">tag</span><spanclass="arrow">⇒</span><spanclass="returns">string</span><divclass="anchors"></div></div><divclass="body"><p>A unique tag for this node for the lifetime of the process.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">node</span><spanclass="symbol">.</span><spanclass="method">location</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/other/assembly/ast/-%23-asm-location">Location</a></span><divclass="anchors"></div></div><divclass="body"><p>The source code and location within the source code that this node represents.</p>
</div></div><aname="/v5/api/other/assembly/ast/-%23-asm-valuenode"></a><aname="/v5/api/other/assembly/ast/-%23-asm-ast--nodes--asm-valuenode"></a><aname="/v5/api/other/assembly/ast/"></a><h3class="show-anchors"><div>ValueNode<spanclass="inherits"> inherits <ahref="#/v5/api/other/assembly/ast/-%23-asm-node">Node</a></span><divclass="anchors"><aclass="self"href="#/v5/api/other/assembly/ast/-%23-asm-valuenode"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/asm/src.ts/assembler.ts#L213">source</a></div></div></h3><p>A <b>ValueNode</b> is a node which may manipulate the stack.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">literalNode</span><spanclass="symbol">.</span><spanclass="method">value</span><spanclass="arrow">⇒</span><spanclass="returns">string</span><divclass="anchors"></div></div><divclass="body"><p>The literal value of this node, which may be a <ahref="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a> or string of a decimal number.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">literalNode</span><spanclass="symbol">.</span><spanclass="method">verbatim</span><spanclass="arrow">⇒</span><spanclass="returns">boolean</span><divclass="anchors"></div></div><divclass="body"><p>This is true in a <ahref="#/v5/api/other/assembly/ast/-%23-asm-datanode">DataNode</a> context, since in that case the value should be taken verbatim and no <codeclass="inline">PUSH</code> operation shoud be added, otherwise false.</p>
</div></div><aname="/v5/api/other/assembly/ast/-%23-asm-popnode"></a><aname="/v5/api/other/assembly/ast/-%23-asm-ast--nodes--asm-popnode"></a><aname="/v5/api/other/assembly/ast/"></a><h3class="show-anchors"><div>PopNode<spanclass="inherits"> inherits <ahref="#/v5/api/other/assembly/ast/-%23-asm-valuenode">ValueNode</a></span><divclass="anchors"><aclass="self"href="#/v5/api/other/assembly/ast/-%23-asm-popnode"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/asm/src.ts/assembler.ts#L265">source</a></div></div></h3><p>A <b>PopNode</b> is used to store a place-holder for an implicit pop from the stack. It represents the code for an implicit place-holder (i.e. <codeclass="inline">$$</code>) or an explicit place-holder (e.g. <codeclass="inline">$1</code>), which indicates the expect stack position to consume.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">literalNode</span><spanclass="symbol">.</span><spanclass="method">index</span><spanclass="arrow">⇒</span><spanclass="returns">number</span><divclass="anchors"></div></div><divclass="body"><p>The index this <b>PopNode</b> is representing. For an implicit place-holder this is <codeclass="inline">0</code>.</p>
</div></div><aname="/v5/api/other/assembly/ast/-%23-asm-linknode"></a><aname="/v5/api/other/assembly/ast/-%23-asm-ast--nodes--asm-linknode"></a><aname="/v5/api/other/assembly/ast/"></a><h3class="show-anchors"><div>LinkNode<spanclass="inherits"> inherits <ahref="#/v5/api/other/assembly/ast/-%23-asm-valuenode">ValueNode</a></span><divclass="anchors"><aclass="self"href="#/v5/api/other/assembly/ast/-%23-asm-linknode"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/asm/src.ts/assembler.ts#L282">source</a></div></div></h3><p>A <b>LinkNode</b> represents a link to another <ahref="#/v5/api/other/assembly/ast/-%23-asm-node">Node</a>'s data, for example <codeclass="inline">$foo</code> or <codeclass="inline">#bar</code>.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">linkNode</span><spanclass="symbol">.</span><spanclass="method">label</span><spanclass="arrow">⇒</span><spanclass="returns">string</span><divclass="anchors"></div></div><divclass="body"><p>Te name of the target node.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">linkNode</span><spanclass="symbol">.</span><spanclass="method">type</span><spanclass="arrow">⇒</span><spanclass="returns">"offset" | "length"</span><divclass="anchors"></div></div><divclass="body"><p>Whether this node is for an offset or a length value of the target node.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">opcodeNode</span><spanclass="symbol">.</span><spanclass="method">opcode</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/other/assembly/api/-%23-asm-opcode">Opcode</a></span><divclass="anchors"></div></div><divclass="body"><p>The opcode for this Node.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">opcodeNode</span><spanclass="symbol">.</span><spanclass="method">operands</span><spanclass="arrow">⇒</span><spanclass="returns">Array<<ahref="#/v5/api/other/assembly/ast/-%23-asm-valuenode">ValueNode</a>></span><divclass="anchors"></div></div><divclass="body"><p>A list of all operands passed into this Node.</p>
</div></div><aname="/v5/api/other/assembly/ast/-%23-asm-evaluationnode"></a><aname="/v5/api/other/assembly/ast/-%23-asm-ast--nodes--asm-evaluationnode"></a><aname="/v5/api/other/assembly/ast/"></a><h3class="show-anchors"><div>EvaluationNode<spanclass="inherits"> inherits <ahref="#/v5/api/other/assembly/ast/-%23-asm-valuenode">ValueNode</a></span><divclass="anchors"><aclass="self"href="#/v5/api/other/assembly/ast/-%23-asm-evaluationnode"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/asm/src.ts/assembler.ts#L517">source</a></div></div></h3><p>An <b>EvaluationNode</b> is used to execute code and insert the results but does not generate any output assembly, using the <codeclass="inline">{{! code here }}</code> syntax.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">literalNode</span><spanclass="symbol">.</span><spanclass="method">verbatim</span><spanclass="arrow">⇒</span><spanclass="returns">boolean</span><divclass="anchors"></div></div><divclass="body"><p>This is true in a <ahref="#/v5/api/other/assembly/ast/-%23-asm-datanode">DataNode</a> context, since in that case the value should be taken verbatim and no <codeclass="inline">PUSH</code> operation shoud be added, otherwise false.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">evaluationNode</span><spanclass="symbol">.</span><spanclass="method">script</span><spanclass="arrow">⇒</span><spanclass="returns">string</span><divclass="anchors"></div></div><divclass="body"><p>The code to evaluate and produce the result to use as a literal.</p>
</div></div><aname="/v5/api/other/assembly/ast/-%23-asm-executionnode"></a><aname="/v5/api/other/assembly/ast/-%23-asm-ast--nodes--asm-executionnode"></a><aname="/v5/api/other/assembly/ast/"></a><h3class="show-anchors"><div>ExecutionNode<spanclass="inherits"> inherits <ahref="#/v5/api/other/assembly/ast/-%23-asm-node">Node</a></span><divclass="anchors"><aclass="self"href="#/v5/api/other/assembly/ast/-%23-asm-executionnode"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/asm/src.ts/assembler.ts#L546">source</a></div></div></h3><p>An <b>ExecutionNode</b> is used to execute code but does not generate any output assembly, using the <codeclass="inline">{{! code here }}</code> syntax.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">evaluationNode</span><spanclass="symbol">.</span><spanclass="method">script</span><spanclass="arrow">⇒</span><spanclass="returns">string</span><divclass="anchors"></div></div><divclass="body"><p>The code to execute. Any result is ignored.</p>
</div></div><aname="/v5/api/other/assembly/ast/-%23-asm-labellednode"></a><aname="/v5/api/other/assembly/ast/-%23-asm-ast--nodes--asm-labellednode"></a><aname="/v5/api/other/assembly/ast/"></a><h3class="show-anchors"><div>LabelledNode<spanclass="inherits"> inherits <ahref="#/v5/api/other/assembly/ast/-%23-asm-node">Node</a></span><divclass="anchors"><aclass="self"href="#/v5/api/other/assembly/ast/-%23-asm-labellednode"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/asm/src.ts/assembler.ts#L418">source</a></div></div></h3><p>A <b>LabelledNode</b> is used for any Node that has a name, and can therefore be targetted by a <ahref="#/v5/api/other/assembly/ast/-%23-asm-linknode">LinkNode</a>.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">labelledNode</span><spanclass="symbol">.</span><spanclass="method">name</span><spanclass="arrow">⇒</span><spanclass="returns">string</span><divclass="anchors"></div></div><divclass="body"><p>The name of this node.</p>
</div></div><aname="/v5/api/other/assembly/ast/-%23-asm-labelnode"></a><aname="/v5/api/other/assembly/ast/-%23-asm-ast--nodes--asm-labelnode"></a><aname="/v5/api/other/assembly/ast/"></a><h3class="show-anchors"><div>LabelNode<spanclass="inherits"> inherits <ahref="#/v5/api/other/assembly/ast/-%23-asm-labellednode">LabelledNode</a></span><divclass="anchors"><aclass="self"href="#/v5/api/other/assembly/ast/-%23-asm-labelnode"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/asm/src.ts/assembler.ts#L429">source</a></div></div></h3><p>A <b>LabelNode</b> is used as a place to <codeclass="inline">JUMP</code> to by referencing it name, using <codeclass="inline">@myLabel:</code>. A <codeclass="inline">JUMPDEST</code> is automatically inserted at the bytecode offset.</p>
<aname="/v5/api/other/assembly/ast/-%23-asm-datanode"></a><aname="/v5/api/other/assembly/ast/-%23-asm-ast--nodes--asm-datanode"></a><aname="/v5/api/other/assembly/ast/"></a><h3class="show-anchors"><div>DataNode<spanclass="inherits"> inherits <ahref="#/v5/api/other/assembly/ast/-%23-asm-labellednode">LabelledNode</a></span><divclass="anchors"><aclass="self"href="#/v5/api/other/assembly/ast/-%23-asm-datanode"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/asm/src.ts/assembler.ts#L465">source</a></div></div></h3><p>A <b>DataNode</b> allows for data to be inserted directly into the output assembly, using <codeclass="inline">@myData[ ... ]</code>. The data is padded if needed to ensure values that would otherwise be regarded as a <codeclass="inline">PUSH</code> value does not impact anything past the data.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">dataNode</span><spanclass="symbol">.</span><spanclass="method">data</span><spanclass="arrow">⇒</span><spanclass="returns">Array<<ahref="#/v5/api/other/assembly/ast/-%23-asm-valuenode">ValueNode</a>></span><divclass="anchors"></div></div><divclass="body"><p>The child nodes, which each represent a verbatim piece of data in insert.</p>
</div></div><aname="/v5/api/other/assembly/ast/-%23-asm-scopenode"></a><aname="/v5/api/other/assembly/ast/-%23-asm-ast--nodes--asm-scopenode"></a><aname="/v5/api/other/assembly/ast/"></a><h3class="show-anchors"><div>ScopeNode<spanclass="inherits"> inherits <ahref="#/v5/api/other/assembly/ast/-%23-asm-labellednode">LabelledNode</a></span><divclass="anchors"><aclass="self"href="#/v5/api/other/assembly/ast/-%23-asm-scopenode"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/asm/src.ts/assembler.ts#L565">source</a></div></div></h3><p>A <b>ScopeNode</b> allows a new frame of reference that all <ahref="#/v5/api/other/assembly/ast/-%23-asm-linknode">LinkNode</a>'s will use when resolving offset locations, using <codeclass="inline">@myScope{ ... }</code>.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">scopeNode</span><spanclass="symbol">.</span><spanclass="method">statements</span><spanclass="arrow">⇒</span><spanclass="returns">Array<<ahref="#/v5/api/other/assembly/ast/-%23-asm-node">Node</a>></span><divclass="anchors"></div></div><divclass="body"><p>The list of child nodes for this scope.</p>
<aname="/v5/api/other/hardware/-%23-hw-ledger"></a><aname="/v5/api/other/hardware/-%23-hardware-wallets--hw-ledger"></a><aname="/v5/api/other/hardware/"></a><h2class="show-anchors"><div>LedgerSigner<spanclass="inherits"> inherits <ahref="#/v5/api/signer/-%23-Signer">Signer</a></span><divclass="anchors"><aclass="self"href="#/v5/api/other/hardware/-%23-hw-ledger"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/hardware-wallets/src.ts/ledger.ts#L23">source</a></div></div></h2><p>The <ahref="https://www.ledger.com">Ledger Hardware Wallets</a> are a fairly popular brand.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="modifier">new </span><spanclass="method">LedgerSigner</span><spanclass="symbol">(</span><spanclass="symbol">[</span><spanclass="param">provider</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">type</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">path</span><spanclass="symbol">]</span><spanclass="symbol">]</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/other/hardware/-%23-hw-ledger">LedgerSigner</a></span><divclass="anchors"></div></div><divclass="body"><p>Connects to a Ledger Hardware Wallet. The <i>type</i> if left unspecified is determined by the environment; in node the default is "hid" and in the browser "u2f" is the default. The default Ethereum path is used if <i>path</i> is left unspecified.</p>
</div></div><divclass="page-separator"></div><aname="/v5/api/experimental/-%23-experimental"></a><aname="/v5/api/experimental/"></a><h1class="show-anchors"><div>Experimental<divclass="anchors"><aclass="self"href="#/v5/api/experimental/-%23-experimental"></a></div></div></h1><p>The <b>Experimental</b> package is used for features that are not ready to be included in the base library. The API should not be considered stable and does not follow <ahref="https://semver.org">semver</a> versioning, so applications requiring it should specify the <i>exact version</i> needed.</p>
<aname="/v5/api/experimental/-%23-experimental-brainwallet"></a><aname="/v5/api/experimental/-%23-experimental--experimental-brainwallet"></a><aname="/v5/api/experimental/"></a><h2class="show-anchors"><div>BrainWallet<spanclass="inherits"> inherits <ahref="#/v5/api/signer/-%23-Wallet">Wallet</a></span><divclass="anchors"><aclass="self"href="#/v5/api/experimental/-%23-experimental-brainwallet"></a></div></div></h2><p>Ethers removed support for BrainWallets in v4, since they are unsafe and many can be easily guessed, allowing attackers to steal the funds. This class is offered to ensure older systems which used brain wallets can still recover their funds and assets.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">BrainWallet</span><spanclass="symbol">.</span><spanclass="method">generate</span><spanclass="symbol">(</span><spanclass="param">username</span><spanclass="symbol">,</span><spanclass="param">password</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">progressCallback</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/experimental/-%23-experimental-brainwallet">BrainWallet</a></span><divclass="anchors"></div></div><divclass="body"><p>Generates a brain wallet, with a slightly improved experience, in which the generated wallet has a mnemonic.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">BrainWallet</span><spanclass="symbol">.</span><spanclass="method">generateLegacy</span><spanclass="symbol">(</span><spanclass="param">username</span><spanclass="symbol">,</span><spanclass="param">password</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">progressCallback</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/experimental/-%23-experimental-brainwallet">BrainWallet</a></span><divclass="anchors"></div></div><divclass="body"><p>Generate a brain wallet which is compatibile with the ethers v3 and earlier.</p>
</div></div><aname="/v5/api/experimental/-%23-experimental-eip1193bridge"></a><aname="/v5/api/experimental/-%23-experimental--experimental-eip1193bridge"></a><aname="/v5/api/experimental/"></a><h2class="show-anchors"><div>EIP1193Bridge<spanclass="inherits"> inherits <ahref="https://nodejs.org/dist/latest-v13.x/docs/api/events.html#events_class_eventemitter">EventEmitter</a></span><divclass="anchors"><aclass="self"href="#/v5/api/experimental/-%23-experimental-eip1193bridge"></a></div></div></h2><p>The <b>EIP1193Bridge</b> allows a normal Ethers <ahref="#/v5/api/signer/-%23-Signer">Signer</a> and <ahref="#/v5/api/providers/provider/">Provider</a> to be exposed in as a standard <ahref="https://eips.ethereum.org/EIPS/eip-1193">EIP-1193 Provider</a>, which may be useful when interacting with other libraries.</p>
<aname="/v5/api/experimental/-%23-experimental-noncemanager"></a><aname="/v5/api/experimental/-%23-experimental--experimental-noncemanager"></a><aname="/v5/api/experimental/"></a><h2class="show-anchors"><div>NonceManager<spanclass="inherits"> inherits <ahref="#/v5/api/signer/-%23-Signer">Signer</a></span><divclass="anchors"><aclass="self"href="#/v5/api/experimental/-%23-experimental-noncemanager"></a></div></div></h2><p>The <b>NonceManager</b> is designed to manage the nonce for a Signer, automatically increasing it as it sends transactions.</p>
<p>Currently the NonceManager does not handle re-broadcast. If you attempt to send a lot of transactions to the network on a node that does not control that account, the transaction pool may drop your transactions.</p>
<p>In the future, it'd be nice if the <b>NonceManager</b> remembered transactions and watched for them on the network, rebroadcasting transactions that appear to have been dropped.</p>
<p>Another future feature will be some sort of failure mode. For example, often a transaction is dependent on another transaction being mined first.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="modifier">new </span><spanclass="method">NonceManager</span><spanclass="symbol">(</span><spanclass="param">signer</span><spanclass="symbol">)</span><divclass="anchors"></div></div><divclass="body"><p>Create a new NonceManager.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">nonceManager</span><spanclass="symbol">.</span><spanclass="method">signer</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/signer/-%23-Signer">Signer</a></span><divclass="anchors"></div></div><divclass="body"><p>The signer whose nonce is being managed.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">nonceManager</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>The provider associated with the signer.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">nonceManager</span><spanclass="symbol">.</span><spanclass="method">setTransactionCount</span><spanclass="symbol">(</span><spanclass="param">count</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">void</span><divclass="anchors"></div></div><divclass="body"><p>Set the current transaction count (nonce) for the signer.</p>
<p>This may be useful it interacting with the signer outside of using this class.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">nonceManager</span><spanclass="symbol">.</span><spanclass="method">increaseTransactionCount</span><spanclass="symbol">(</span><spanclass="symbol">[</span><spanclass="param">count</span> = <spanclass="param">1</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">void</span><divclass="anchors"></div></div><divclass="body"><p>Bump the current transaction count (nonce) by <i>count</i>.</p>
<p>This may be useful it interacting with the signer outside of using this class.</p>
</div></div><divclass="page-separator"></div><aname="/v5/cli/-%23-command-line-interfaces"></a><aname="/v5/cli/"></a><h1class="show-anchors"><div>Command Line Interfaces<divclass="anchors"><aclass="self"href="#/v5/cli/-%23-command-line-interfaces"></a></div></div></h1>
<divclass="toc"><divstyle="padding-left: 0px"><spanclass="bullet">•</span><ahref="#/v5/cli/ethers/">Sandbox Utility</a></div><divstyle="padding-left: 0px"><spanclass="bullet">•</span><ahref="#/v5/cli/asm/">Assembler</a></div><divstyle="padding-left: 0px"><spanclass="bullet">•</span><ahref="#/v5/cli/ens/">Ethereum Naming Service</a></div><divstyle="padding-left: 0px"><spanclass="bullet">•</span><ahref="#/v5/cli/typescript/">TypeScript</a></div><divstyle="padding-left: 0px"><spanclass="bullet">•</span><ahref="#/v5/cli/plugin/">Making Your Own</a></div></div><divclass="page-separator"></div><aname="/v5/cli/ethers/-%23-sandbox-utility"></a><aname="/v5/cli/ethers/"></a><h1class="show-anchors"><div>Sandbox Utility<divclass="anchors"><aclass="self"href="#/v5/cli/ethers/-%23-sandbox-utility"></a></div></div></h1><p>The sandbox utility provides a simple way to use the most common ethers utilities required during learning, debuging and managing interactions with the Ethereum network.</p>
<p>If no command is given, it will enter a REPL interface with many of the ethers utilities already exposed.</p>
info [ TARGET ... ] Dump info for accounts, addresses and ENS names
send TARGET ETHER Send ETHER ether to TARGET form accounts[0]
[ --allow-zero ] Allow sending to the address zero
[ --data DATA ] Include data in the transaction
sweep TARGET Send all ether from accounts[0] to TARGET
sign-message MESSAGE Sign a MESSAGE with accounts[0]
[ --hex ] The message content is hex encoded
eval CODE Run CODE in a VM with ethers
run FILENAME Run FILENAME in a VM with ethers
wait HASH Wait for a transaction HASH to be mined
wrap-ether VALUE Deposit VALUE into Wrapped Ether (WETH)
unwrap-ether VALUE Withdraw VALUE from Wrapped Ether (WETH)
send-token TOKEN ADDRESS VALUE
Send VALUE tokens (at TOKEN) to ADDRESS
compile FILENAME Compiles a Solidity contract
[ --no-optimize ] Do not optimize the compiled output
[ --warnings ] Error on any warning
deploy FILENAME Compile and deploy a Solidity contract
[ --no-optimize ] Do not optimize the compiled output
[ --contract NAME ] Specify the contract to deploy
ACCOUNT OPTIONS
--account FILENAME Load from a file (JSON, RAW or mnemonic)
--account RAW_KEY Use a private key (insecure *)
--account 'MNEMONIC' Use a mnemonic (insecure *)
--account - Use secure entry for a raw key or mnemonic
--account-void ADDRESS Use an address as a void signer
--account-void ENS_NAME Add the resolved address as a void signer
--account-rpc ADDRESS Add the address from a JSON-RPC provider
--account-rpc INDEX Add the index from a JSON-RPC provider
--mnemonic-password Prompt for a password for mnemonics
--xxx-mnemonic-password Prompt for a (experimental) hard password
PROVIDER OPTIONS (default: all + homestead)
--alchemy Include Alchemy
--etherscan Include Etherscan
--infura Include INFURA
--nodesmith Include nodesmith
--rpc URL Include a custom JSON-RPC
--offline Dump signed transactions (no send)
--network NETWORK Network to connect to (default: homestead)
TRANSACTION OPTIONS (default: query network)
--gasPrice GWEI Default gas price for transactions(in wei)
--gasLimit GAS Default gas limit for transactions
--nonce NONCE Initial nonce for the first transaction
--yes Always accept Siging and Sending
OTHER OPTIONS
--wait Wait until transactions are mined
--debug Show stack traces for errors
--help Show this usage and exit
--version Show this version and exit
(*) By including mnemonics or private keys on the command line they are
possibly readable by other users on your system and may get stored in
your bash history file. This is NOT recommended.</div><aname="/v5/cli/ethers/-%23-sandbox-utility--examples"></a><aname="/v5/cli/ethers/"></a><h2class="show-anchors"><div>Examples<divclass="anchors"><aclass="self"href="#/v5/cli/ethers/-%23-sandbox-utility--examples"></a></div></div></h2>
<aname="/v5/cli/ethers/-%23-cliex-init"></a><divclass="code-title"><div>Creating New Wallets</div></div><divclass="code">/home/ethers> ethers init wallet.json
Creating a new JSON Wallet - wallet.json
Keep this password and file SAFE!! If lost or forgotten
it CANNOT be recovered, by ANYone, EVER.
Choose a password: ******
Confirm password: ******
Encrypting... 100%
New account address: 0x485bcC23ae2E5038ec7ec9b8DCB2A6A6291cC003
Saved: wallet.json
# If you are planning to try out the Ropsten testnet...
/home/ethers> ethers --network ropsten fund 0x485bcC23ae2E5038ec7ec9b8DCB2A6A6291cC003
Transaction Hash: 0x8dc55b8f8dc8076acded97f9e3ed7d6162460c0221e2769806006b6d7d1156e0</div><aname="/v5/cli/ethers/-%23-cliex-send"></a><divclass="code-title"><div>Sending Ether and Tokens</div></div><divclass="code"># Sending ether
recid: 0</div><aname="/v5/cli/ethers/-%23-cliex-scripting"></a><aname="/v5/cli/ethers/-%23-sandbox-utility--examples--cliex-scripting"></a><aname="/v5/cli/ethers/"></a><h3class="show-anchors"><div>Scripting<divclass="anchors"><aclass="self"href="#/v5/cli/ethers/-%23-cliex-scripting"></a></div></div></h3><p>The <codeclass="inline">eval</code> command can be used to execute simple one-line scripts from the command line to be passed into other commands or stored in script environment variables.</p>
<divclass="code-title"><div>Get the formatted balance of an account</div></div><divclass="code">/home/ethers> ethers --network ropsten \
3.141592653589793238</div><divclass="code-title"><div>Get the current block number</div></div><divclass="code">/home/ethers> ethers --network rinkeby \
eval "provider.getBlockNumber()"
5761009</div><divclass="code-title"><div>Convert a Solidity signature to JSON</div></div><divclass="code">/home/ethers> ethers eval 'utils.Fragment.from(
"function balanceOf(address) view returns (uint)"
).format("json")' | json_pp
{
"inputs" : [
{
"type" : "address",
"name" : "owner"
}
],
"type" : "function",
"payble" : false,
"stateMutability" : "view",
"ouputs" : [
{
"type" : "uint256"
}
],
"name" : "balanceOf",
"constant" : true
}</div><divclass="code-title"><div>Compute a topic hash</div></div><divclass="code">/home/ricmoo> ethers eval 'id("Transfer(address,address,uint256")'
0xd99659a21de82e379975ce8df556f939a4ccb95e92144f38bb0dd35730ffcdd5</div><divclass="code-title"><div>Create a random mnemonic</div></div><divclass="code">/home/ricmoo> ethers eval 'Wallet.createRandom().mnemonic'
useful pond inch knock ritual matrix giggle attend dilemma convince coach amazing</div><aname="/v5/cli/ethers/-%23-cliex-mnemonicpassword"></a><aname="/v5/cli/ethers/-%23-sandbox-utility--examples--cliex-mnemonicpassword"></a><aname="/v5/cli/ethers/"></a><h3class="show-anchors"><div>Using Mnemonics (with a password)<divclass="anchors"><aclass="self"href="#/v5/cli/ethers/-%23-cliex-mnemonicpassword"></a></div></div></h3><p>All mnemonic phrases have a password, but the default is to use the empty string (i.e. <codeclass="inline">""</code>) as the password. If you have a password on your mnemonic, the <codeclass="inline">--mnemonic-password</code> will prompt for the password to use to decrypt the account.</p>
homestead></div><aname="/v5/cli/ethers/-%23-cliex-mnemonicpassword-xxx"></a><aname="/v5/cli/ethers/-%23-sandbox-utility--examples--cliex-mnemonicpassword-xxx"></a><aname="/v5/cli/ethers/"></a><h3class="show-anchors"><div>Using Mnemonics (with experimental memory-hard passwords)<divclass="anchors"><aclass="self"href="#/v5/cli/ethers/-%23-cliex-mnemonicpassword-xxx"></a></div></div></h3><p>The <codeclass="inline">--xxx-mnemonic-password</code> is similar to the <codeclass="inline">--mnemonic-password</code> options, which uses a password to decrypt the account for a mnemonic, however it passes the password through the <ahref="https://en.wikipedia.org/wiki/Scrypt">scrypt</a><i>password-based key derivation function</i> first, which is intentionally slow and makes a brute-force attack far more difficult.</p>
homestead></div><divclass="definition container-box warning"><divclass="term">Note</div><divclass="body"><p>This is still an experimental feature (hence the <codeclass="inline">xxx</code>).</p>
</div></div><divclass="page-separator"></div><aname="/v5/cli/asm/-%23-cli-asm"></a><aname="/v5/cli/asm/-%23-cli-asm"></a><aname="/v5/cli/asm/"></a><h1class="show-anchors"><div>Assembler<divclass="anchors"><aclass="self"href="#/v5/cli/asm/-%23-cli-asm"></a></div></div></h1><p>The assembler Command-Line utility allows you to assemble the <ahref="#/v5/api/other/assembly/dialect/">Ethers ASM Dialect</a> into deployable EVM bytecode and disassemle EVM bytecode into human-readable mnemonics.</p>
--version Show this version and exit</div><aname="/v5/cli/asm/-%23-cli-asm--example-input-files"></a><aname="/v5/cli/asm/"></a><h2class="show-anchors"><div>Example Input Files<divclass="anchors"><aclass="self"href="#/v5/cli/asm/-%23-cli-asm--example-input-files"></a></div></div></h2>
0xf35b6024361415601e5760043560005560006000f3</div><divclass="definition container-box note"><divclass="term">Note: Bytecode File Syntax</div><divclass="body"><p>A bin file may be made up of multiple blocks of bytecode, each may optionally begin with a <codeclass="inline">0x</code> prefix, all of which <b>must</b> be of even length (since bytes are required, with 2 nibbles per byte)</p>
<p>All whitespace is ignored.</p>
</div></div><aname="/v5/cli/asm/-%23-cli-asm--assembler-examples"></a><aname="/v5/cli/asm/"></a><h2class="show-anchors"><div>Assembler Examples<divclass="anchors"><aclass="self"href="#/v5/cli/asm/-%23-cli-asm--assembler-examples"></a></div></div></h2><p>The assembler converts an <ahref="#/v5/api/other/assembly/dialect/">Ethers ASM Dialect</a> into bytecode by running multiple passes of an assemble stage, each pass more closely approximating the final result.</p>
<p>This allows small portions of the bytecode to be massaged and tweaked until the bytecode stablizes. This allows for more compact jump destinations and for code to be include more advanced meta-programming techniques.</p>
<divclass="definition"><divclass="term"><b>--define KEY=VALUE</b><i>or</i><b>--define FLAG</b></div><divclass="body"><p>This allows key/value pairs (where the value is a string) and flags (which the value is <codeclass="inline">true</code>) to be passed along to the assembler, which can be accessed in <ahref="#/v5/api/other/assembly/dialect/-%23-asm-dialect-scripting">Scripting Blocks</a>, such as <codeclass="inline">{{= defined.someKey }}</code>.</p>
</div></div><divclass="definition"><divclass="term"><b>--ignore-warnings</b></div><divclass="body"><p>By default any warning will be treated like an error. This enabled by-passing warnings.</p>
</div></div><divclass="definition"><divclass="term"><b>--pic</b></div><divclass="body"><p>When a program is assembled, the labels are usually given as an absolute byte position, which can be jumped to for loops and control flow. This means that a program must be installed at a specific location.</p>
<p>Byt specifying the <b>Position Independent Code</b> flag, code will be generated in a way such that all offsets are relative, allowing the program to be moved without any impact to its logic.</p>
<p>This does incur an additional gsas cost of 8 gas per offset access though.</p>
</div></div><divclass="definition"><divclass="term"><b>--target LABEL</b></div><divclass="body"><p>All programs have a root scope named <codeclass="inline">_</code> which is by default assembled. This option allows another labelled target (either a <ahref="#/v5/api/other/assembly/dialect/-%23-asm-dialect-scope">Scopes</a> or a <ahref="#/v5/api/other/assembly/dialect/-%23-asm-dialect-datasegment">Data Segment</a> to be assembled instead. The entire program is still assembled per usual, so this only impacts which part of the program is output.</p>
</div></div><aname="/v5/cli/asm/-%23-cli-asm--disassembler-examples"></a><aname="/v5/cli/asm/"></a><h2class="show-anchors"><div>Disassembler Examples<divclass="anchors"><aclass="self"href="#/v5/cli/asm/-%23-cli-asm--disassembler-examples"></a></div></div></h2><p>A disassembled program shows offsets and mnemonics for the given bytecode. This format may change in the future to be more human-readable.</p>
# Same as above</div><divclass="page-separator"></div><aname="/v5/cli/ens/-%23-ethereum-naming-service"></a><aname="/v5/cli/ens/"></a><h1class="show-anchors"><div>Ethereum Naming Service<divclass="anchors"><aclass="self"href="#/v5/cli/ens/-%23-ethereum-naming-service"></a></div></div></h1>
[ --duration DAYS ] Register duration (default: 365 days)
[ --salt SALT ] SALT to blind the commit with
[ --secret SECRET ] Use id(SECRET) as the salt
[ --owner OWNER ] The target owner (default: current account)
reveal NAME Reveal a previous pre-commitment
[ --duration DAYS ] Register duration (default: 365 days)
[ --salt SALT ] SALT to blind the commit with
[ --secret SECRET ] Use id(SECRET) as the salt
[ --owner OWNER ] The target owner (default: current account)
set-controller NAME Set the controller (default: current account)
[ --address ADDRESS ] Specify another address
set-subnode NAME Set a subnode owner (default: current account)
[ --address ADDRESS ] Specify another address
set-resolver NAME Set the resolver (default: resolver.eth)
[ --address ADDRESS ] Specify another address
set-addr NAME Set the addr record (default: current account)
[ --address ADDRESS ] Specify another address
set-text NAME KEY VALUE Set a text record
set-email NAME EMAIL Set the email text record
set-website NAME URL Set the website text record
set-content NAME HASH Set the IPFS Content Hash
migrate-registrar NAME Migrate from the Legacy to the Permanent Registrar
transfer NAME NEW_OWNER Transfer registrant ownership
reclaim NAME Reset the controller by the registrant
[ --address ADDRESS ] Specify another address
ACCOUNT OPTIONS
--account FILENAME Load from a file (JSON, RAW or mnemonic)
--account RAW_KEY Use a private key (insecure *)
--account 'MNEMONIC' Use a mnemonic (insecure *)
--account - Use secure entry for a raw key or mnemonic
--account-void ADDRESS Use an address as a void signer
--account-void ENS_NAME Add the resolved address as a void signer
--account-rpc ADDRESS Add the address from a JSON-RPC provider
--account-rpc INDEX Add the index from a JSON-RPC provider
--mnemonic-password Prompt for a password for mnemonics
--xxx-mnemonic-password Prompt for a (experimental) hard password
PROVIDER OPTIONS (default: all + homestead)
--alchemy Include Alchemy
--etherscan Include Etherscan
--infura Include INFURA
--nodesmith Include nodesmith
--rpc URL Include a custom JSON-RPC
--offline Dump signed transactions (no send)
--network NETWORK Network to connect to (default: homestead)
TRANSACTION OPTIONS (default: query network)
--gasPrice GWEI Default gas price for transactions(in wei)
--gasLimit GAS Default gas limit for transactions
--nonce NONCE Initial nonce for the first transaction
--yes Always accept Siging and Sending
OTHER OPTIONS
--wait Wait until transactions are mined
--debug Show stack traces for errors
--help Show this usage and exit
--version Show this version and exit
(*) By including mnemonics or private keys on the command line they are
possibly readable by other users on your system and may get stored in
your bash history file. This is NOT recommended.</div><aname="/v5/cli/ens/-%23-ethereum-naming-service--examples"></a><aname="/v5/cli/ens/"></a><h2class="show-anchors"><div>Examples<divclass="anchors"><aclass="self"href="#/v5/cli/ens/-%23-ethereum-naming-service--examples"></a></div></div></h2><p>TODO examples</p>
--output FILENAME Write the output to FILENAME (default: stdout)
--force Overwrite files if they already exist
--no-optimize Do not run the solc optimizer
--no-bytecode Do not include bytecode and Factory methods
OTHER OPTIONS
--debug Show stack traces for errors
--help Show this usage and exit
--version Show this version and exit
(*) By including mnemonics or private keys on the command line they are
possibly readable by other users on your system and may get stored in
your bash history file. This is NOT recommended.</div><aname="/v5/cli/typescript/-%23-typescript--examples"></a><aname="/v5/cli/typescript/"></a><h2class="show-anchors"><div>Examples<divclass="anchors"><aclass="self"href="#/v5/cli/typescript/-%23-typescript--examples"></a></div></div></h2><p>TODO</p>
<divclass="page-separator"></div><aname="/v5/cli/plugin/-%23-cli-diy"></a><aname="/v5/cli/plugin/-%23-cli-diy"></a><aname="/v5/cli/plugin/"></a><h1class="show-anchors"><div>Making Your Own<divclass="anchors"><aclass="self"href="#/v5/cli/plugin/-%23-cli-diy"></a></div></div></h1><p>The <i>cli</i> library is meant to make it easy to create command line utilities of your own.</p>
<aname="/v5/cli/plugin/-%23-cli-cli"></a><aname="/v5/cli/plugin/-%23-cli-diy--cli-cli"></a><aname="/v5/cli/plugin/"></a><h2class="show-anchors"><div>CLI<divclass="anchors"><aclass="self"href="#/v5/cli/plugin/-%23-cli-cli"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/cli/src.ts/cli.ts#L715">source</a></div></div></h2><p>A <b>CLI</b> handles parsing all the command-line flags, options and arguments and instantiates a <ahref="#/v5/cli/plugin/-%23-cli-plugin">Plugin</a> to process the command.</p>
<p>A <b>CLI</b> may support multiple <ahref="#/v5/cli/plugin/-%23-cli-plugin">Plugin</a>'s in which case the first argument is used to determine which to run (or if no arguments, the default plugin will be selected) or may be designed to be standalone, in which case exactly one <ahref="#/v5/cli/plugin/-%23-cli-plugin">Plugin</a> will be used and no command argument is allowed.</p>
<aname="/v5/cli/plugin/-%23-cli-addplugin"></a><divclass="property show-anchors"><divclass="signature"><spanclass="method">addPlugin</span><spanclass="symbol">(</span><spanclass="param">command</span><spanclass="symbol">,</span><spanclass="param">pluginClass</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">void</span><divclass="anchors"><aclass="self"href="#/v5/cli/plugin/-%23-cli-addplugin"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/cli/src.ts/cli.ts#L755">source</a></div></div><divclass="body"><p>Add a <i>plugin</i> class for the <i>command</i>. After all options and flags have been consumed, the first argument will be consumed and the associated plugin class will be instantiated and run.</p>
</div></div><aname="/v5/cli/plugin/-%23-cli-setplugin"></a><divclass="property show-anchors"><divclass="signature"><spanclass="method">setPlugin</span><spanclass="symbol">(</span><spanclass="param">pluginClass</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">void</span><divclass="anchors"><aclass="self"href="#/v5/cli/plugin/-%23-cli-setplugin"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/cli/src.ts/cli.ts#L769">source</a></div></div><divclass="body"><p>Set a dedicated <ahref="#/v5/cli/plugin/-%23-cli-plugin">Plugin</a> class which will handle all input. This may not be used in conjuction with addPlugin and will not automatically accept a command from the arguments.</p>
</div></div><aname="/v5/cli/plugin/-%23-cli-showusage"></a><divclass="property show-anchors"><divclass="signature"><spanclass="method">showUsage</span><spanclass="symbol">(</span><spanclass="symbol">[</span><spanclass="param">message</span> = "" <spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">status</span> = <spanclass="param">0</span><spanclass="symbol">]</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">never</span><divclass="anchors"><aclass="self"href="#/v5/cli/plugin/-%23-cli-showusage"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/cli/src.ts/cli.ts#L783">source</a></div></div><divclass="body"><p>Shows the usage help screen for the CLI and terminates.</p>
</div></div><aname="/v5/cli/plugin/-%23-cli-run"></a><divclass="property show-anchors"><divclass="signature"><spanclass="method">run</span><spanclass="symbol">(</span><spanclass="param">args</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Promise< void ></span><divclass="anchors"><aclass="self"href="#/v5/cli/plugin/-%23-cli-run"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/cli/src.ts/cli.ts#L910">source</a></div></div><divclass="body"><p>Usually the value of <i>args</i> passed in will be <codeclass="inline">process.argv.slice(2)</code>.</p>
</div></div><aname="/v5/cli/plugin/-%23-cli-plugin"></a><aname="/v5/cli/plugin/-%23-cli-diy--cli-plugin"></a><aname="/v5/cli/plugin/"></a><h2class="show-anchors"><div>Plugin<divclass="anchors"><aclass="self"href="#/v5/cli/plugin/-%23-cli-plugin"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/cli/src.ts/cli.ts#L490">source</a></div></div></h2><p>Each <b>Plugin</b> manages each command of a CLI and is executed in phases.</p>
<p>If the usage (i.e. help) of a CLI is requested, the static methods <codeclass="inline">getHelp</code> and <codeclass="inline">getOptionHelp</code> are used to geneate the help screen.</p>
<p>Otherwise, a plugin is instantiated and the <codeclass="inline">prepareOptions</code> is called. Each plugin <b>must</b> call <codeclass="inline">super.prepareOptions</code>, otherwise the basic options are not yet processed. During this time a Plugin should consume all the flags and options it understands, since any left over flags or options will cause the CLI to bail and issue an <i>unknown option</i> error. This should throw if a value for a given option is invalid or some combination of options and flags is not allowed.</p>
<p>Once the prepareOptions is complete (the returned promise is resolved), the <codeclass="inline">prepareArguments</code> is called. This should validate the number of arguments is expected and throw and error if there are too many or too few arguments or if any arguments do not make sense.</p>
<p>Once the prepareArguments is complete (the returned promise is resolved), the <codeclass="inline">run</code> is called.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">plugin</span><spanclass="symbol">.</span><spanclass="method">network</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/providers/types/-%23-providers-Network">Network</a></span><divclass="anchors"></div></div><divclass="body"><p>The network this plugin is running for.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">plugin</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>The provider for this plugin is running for.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">plugin</span><spanclass="symbol">.</span><spanclass="method">accounts</span><spanclass="arrow">⇒</span><spanclass="returns">Array<<ahref="#/v5/api/signer/-%23-Signer">Signer</a>></span><divclass="anchors"></div></div><divclass="body"><p>The accounts passed into the plugin using <codeclass="inline">--account</code>, <codeclass="inline">--account-rpc</code> and <codeclass="inline">--account-void</code> which this plugin can use.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">plugin</span><spanclass="symbol">.</span><spanclass="method">gasLimit</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/bignumber/">BigNumber</a></span><divclass="anchors"></div></div><divclass="body"><p>The gas limit this plugin should use. This is null if unspecified.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">plugin</span><spanclass="symbol">.</span><spanclass="method">gasPrice</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="#/v5/api/utils/bignumber/">BigNumber</a></span><divclass="anchors"></div></div><divclass="body"><p>The gas price this plugin should use. This is null if unspecified.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">plugin</span><spanclass="symbol">.</span><spanclass="method">nonce</span><spanclass="arrow">⇒</span><spanclass="returns">number</span><divclass="anchors"></div></div><divclass="body"><p>The initial nonce for the account this plugin should use.</p>
</div></div><aname="/v5/cli/plugin/-%23-plugin-getaddress"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">plugin</span><spanclass="symbol">.</span><spanclass="method">getAddress</span><spanclass="symbol">(</span><spanclass="param">addressOrName</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">message</span> = "" <spanclass="symbol">,</span><spanclass="symbol">[</span><spanclass="param">allowZero</span> = <spanclass="param">false</span><spanclass="symbol">]</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Promise< string ></span><divclass="anchors"><aclass="self"href="#/v5/cli/plugin/-%23-plugin-getaddress"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/cli/src.ts/cli.ts#L663">source</a></div></div><divclass="body"><p>A plugin should use this method to resolve an address. If the resovled address is the zero address and <i>allowZero</i> is not true, an error is raised.</p>
</div></div><aname="/v5/cli/plugin/-%23-plugin-dump"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">plugin</span><spanclass="symbol">.</span><spanclass="method">dump</span><spanclass="symbol">(</span><spanclass="param">header</span><spanclass="symbol">,</span><spanclass="param">info</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">void</span><divclass="anchors"><aclass="self"href="#/v5/cli/plugin/-%23-plugin-dump"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/cli/src.ts/cli.ts#L682">source</a></div></div><divclass="body"><p>Dumps the contents of <i>info</i> to the console with a <i>header</i> in a nicely formatted style. In the future, plugins may support a JSON output format which will automatically work with this method.</p>
</div></div><aname="/v5/cli/plugin/-%23-plugin-throwusageerror"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">plugin</span><spanclass="symbol">.</span><spanclass="method">throwUsageError</span><spanclass="symbol">(</span><spanclass="symbol">[</span><spanclass="param">message</span> = "" <spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">never</span><divclass="anchors"><aclass="self"href="#/v5/cli/plugin/-%23-plugin-throwusageerror"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/cli/src.ts/cli.ts#L688">source</a></div></div><divclass="body"><p>Stops exectuion of the plugin and shows the help screen of the plugin with the optional <i>message</i>.</p>
</div></div><aname="/v5/cli/plugin/-%23-plugin-throwerror"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">plugin</span><spanclass="symbol">.</span><spanclass="method">throwError</span><spanclass="symbol">(</span><spanclass="param">message</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">never</span><divclass="anchors"><aclass="self"href="#/v5/cli/plugin/-%23-plugin-throwerror"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/cli/src.ts/cli.ts#L693">source</a></div></div><divclass="body"><p>Stops execution of the plugin and shows <i>message</i>.</p>
<aname="/v5/cli/plugin/-%23-plugin-gethelp"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">Plugin</span><spanclass="symbol">.</span><spanclass="method">getHelp</span><spanclass="arrow">⇒</span><spanclass="returns">Help</span><divclass="anchors"><aclass="self"href="#/v5/cli/plugin/-%23-plugin-gethelp"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/cli/src.ts/cli.ts#L507">source</a></div></div><divclass="body"><p>Each subclass should implement this static method which is used to generate the help screen.</p>
</div></div><aname="/v5/cli/plugin/-%23-plugin-getoptionshelp"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">Plugin</span><spanclass="symbol">.</span><spanclass="method">getOptionHelp</span><spanclass="arrow">⇒</span><spanclass="returns">Array< Help ></span><divclass="anchors"><aclass="self"href="#/v5/cli/plugin/-%23-plugin-getoptionshelp"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/cli/src.ts/cli.ts#L511">source</a></div></div><divclass="body"><p>Each subclass should implement this static method if it supports additional options which is used to generate the help screen.</p>
</div></div><aname="/v5/cli/plugin/-%23-cli-argparser"></a><aname="/v5/cli/plugin/-%23-cli-diy--cli-argparser"></a><aname="/v5/cli/plugin/"></a><h2class="show-anchors"><div>ArgParser<divclass="anchors"><aclass="self"href="#/v5/cli/plugin/-%23-cli-argparser"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/cli/src.ts/cli.ts#L292">source</a></div></div></h2><p>The <b>ArgParser</b> is used to parse a command line into flags, options and arguments.</p>
# - [ "send", "ricmoo.eth", "1.0" ]</div><p>Flags are simple binary options (such as the <codeclass="inline">--yes</code>), which are true if present otherwise false.</p>
<p>Options require a single parameter follow them on the command line (such as <codeclass="inline">--account wallet.json</code>, which nhas the name <codeclass="inline">account</code> and the value <codeclass="inline">wallet.json</code>)</p>
<p>Arguments are all other values on the command line, and are not accessed through the <b>ArgParser</b> directly.</p>
<p>When a CLI is run, an <b>ArgParser</b> is used to validate the command line by using prepareOptions, which consumes all flags and options leaving only the arguments behind, which are then passed into prepareArgs.</p>
<aname="/v5/cli/plugin/-%23-argparser-consumeflag"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">argParser</span><spanclass="symbol">.</span><spanclass="method">consumeFlag</span><spanclass="symbol">(</span><spanclass="param">name</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">boolean</span><divclass="anchors"><aclass="self"href="#/v5/cli/plugin/-%23-argparser-consumeflag"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/cli/src.ts/cli.ts#L333">source</a></div></div><divclass="body"><p>Remove the flag <i>name</i> and return true if it is present.</p>
</div></div><aname="/v5/cli/plugin/-%23-argparser-consumemultioptions"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">argParser</span><spanclass="symbol">.</span><spanclass="method">consumeMultiOptions</span><spanclass="symbol">(</span><spanclass="param">names</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Array< {name:string,value:string} ></span><divclass="anchors"><aclass="self"href="#/v5/cli/plugin/-%23-argparser-consumemultioptions"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/cli/src.ts/cli.ts#L351">source</a></div></div><divclass="body"><p>Remove all options which match any name in the Array of <i>names</i> with their values returning the list (in order) of values.</p>
</div></div><aname="/v5/cli/plugin/-%23-argparser-consumeoption"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">argParser</span><spanclass="symbol">.</span><spanclass="method">consumeOption</span><spanclass="symbol">(</span><spanclass="param">name</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">string</span><divclass="anchors"><aclass="self"href="#/v5/cli/plugin/-%23-argparser-consumeoption"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/cli/src.ts/cli.ts#L380">source</a></div></div><divclass="body"><p>Remove the option with its value for <i>name</i> and return the value. This will throw a UsageError if the option is included multiple times.</p>
</div></div><aname="/v5/cli/plugin/-%23-argparser-consumeoptions"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">argParser</span><spanclass="symbol">.</span><spanclass="method">consumeOptions</span><spanclass="symbol">(</span><spanclass="param">name</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Array< string ></span><divclass="anchors"><aclass="self"href="#/v5/cli/plugin/-%23-argparser-consumeoptions"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/master/packages/cli/src.ts/cli.ts#L376">source</a></div></div><divclass="body"><p>Remove all options with their values for <i>name</i> and return the list (in order) of values.</p>
<divclass="page-separator"></div><aname="/v5/migration/-%23-migration"></a><aname="/v5/migration/-%23-migration"></a><aname="/v5/migration/"></a><h1class="show-anchors"><div>Migration Guide<divclass="anchors"><aclass="self"href="#/v5/migration/-%23-migration"></a></div></div></h1><p>Here are some migration guides when upgrading from older versions of Ethers or other libraries.</p>
<divclass="toc"><divstyle="padding-left: 0px"><spanclass="bullet">•</span><ahref="#/v5/migration/web3/">Migration: From Web3.js</a></div><divstyle="padding-left: 0px"><spanclass="bullet">•</span><ahref="#/v5/migration/ethers-v4/">Migration: From Ethers v4</a></div></div><divclass="page-separator"></div><aname="/v5/migration/web3/-%23-migration-from-web3-js"></a><aname="/v5/migration/web3/"></a><h1class="show-anchors"><div>Migration: From Web3.js<divclass="anchors"><aclass="self"href="#/v5/migration/web3/-%23-migration-from-web3-js"></a></div></div></h1><p>TODO</p>
<divclass="page-separator"></div><aname="/v5/migration/ethers-v4/-%23-migration-v4"></a><aname="/v5/migration/ethers-v4/-%23-migration-v4"></a><aname="/v5/migration/ethers-v4/"></a><h1class="show-anchors"><div>Migration: From Ethers v4<divclass="anchors"><aclass="self"href="#/v5/migration/ethers-v4/-%23-migration-v4"></a></div></div></h1>
<aname="/v5/migration/ethers-v4/-%23-migration-v4--bignumber--namespace"></a><aname="/v5/migration/ethers-v4/"></a><h3class="show-anchors"><div>Namespace<divclass="anchors"><aclass="self"href="#/v5/migration/ethers-v4/-%23-migration-v4--bignumber--namespace"></a></div></div></h3><p>Since <ahref="#/v5/api/utils/bignumber/">BigNumber</a> is used quite frequently, it has been moved to the top level of the umbrella package.</p>
</div><aname="/v5/migration/ethers-v4/-%23-migration-v4--bignumber--creating-instances"></a><aname="/v5/migration/ethers-v4/"></a><h3class="show-anchors"><div>Creating Instances<divclass="anchors"><aclass="self"href="#/v5/migration/ethers-v4/-%23-migration-v4--bignumber--creating-instances"></a></div></div></h3><p>The <codeclass="inline">bigNumberify</code> method was always preferred over the constructor since it could short-circuit an object instantiation for [[BigNumber] objects (since they are immutable). This has been moved to a static <codeclass="inline">from</code> class method.</p>
<aname="/v5/migration/ethers-v4/-%23-migration-v4--errors--namespace"></a><aname="/v5/migration/ethers-v4/"></a><h3class="show-anchors"><div>Namespace<divclass="anchors"><aclass="self"href="#/v5/migration/ethers-v4/-%23-migration-v4--errors--namespace"></a></div></div></h3><p>All errors now belong to the <ahref="#/v5/api/utils/logger/-%23-Logger">Logger</a> class and the related functions have been moved to <ahref="#/v5/api/utils/logger/-%23-Logger">Logger</a> instances, which can include a per-package version string.</p>
<p>Global error fucntions have been moved <ahref="#/v5/api/utils/logger/-%23-Logger">Logger</a> class methods.</p>
</div><aname="/v5/migration/ethers-v4/-%23-migration-v4--interface"></a><aname="/v5/migration/ethers-v4/"></a><h2class="show-anchors"><div>Interface<divclass="anchors"><aclass="self"href="#/v5/migration/ethers-v4/-%23-migration-v4--interface"></a></div></div></h2><p>The <ahref="#/v5/api/utils/abi/interface/">Interface</a> object has undergone the most dramatic changes.</p>
<p>It is no longer a meta-class and now has methods that simplify handling contract interface operations without the need for object inspection and special edge cases.</p>
</div><aname="/v5/migration/ethers-v4/-%23-migration-v4--interface--inspection"></a><aname="/v5/migration/ethers-v4/"></a><h3class="show-anchors"><div>Inspection<divclass="anchors"><aclass="self"href="#/v5/migration/ethers-v4/-%23-migration-v4--interface--inspection"></a></div></div></h3><p>Interrogating properties about a function or event can now (mostly) be done directly on the <ahref="#/v5/api/utils/abi/fragments/-%23-Fragment">Fragment</a> object.</p>
<aname="/v5/migration/ethers-v4/-%23-migration-v4--wallet--mnemonic-phrases"></a><aname="/v5/migration/ethers-v4/"></a><h3class="show-anchors"><div>Mnemonic Phrases<divclass="anchors"><aclass="self"href="#/v5/migration/ethers-v4/-%23-migration-v4--wallet--mnemonic-phrases"></a></div></div></h3><p>The <b>mnemonic</b> phrase and related properties have been merged into a single <codeclass="inline">mnemonic</code> object, which also now includes the <codeclass="inline">locale</code>.</p>
</span><spanclass="comment">// - Mnemonic phrase and path are a Mnemonic object
</span><spanclass="comment">// - Note: wallet.mnemonic is null if there is no mnemonic
</span>wallet.mnemonic.phrase
wallet.mnemonic.path
</div><divclass="page-separator"></div><aname="/v5/testing/-%23-testing"></a><aname="/v5/testing/"></a><h1class="show-anchors"><div>Testing<divclass="anchors"><aclass="self"href="#/v5/testing/-%23-testing"></a></div></div></h1><p>Here goes info about testing</p>
<divclass="page-separator"></div><aname="/v5/contributing/-%23-contributing"></a><aname="/v5/contributing/-%23-contributing"></a><aname="/v5/contributing/"></a><h1class="show-anchors"><div>Contributing and Hacking<divclass="anchors"><aclass="self"href="#/v5/contributing/-%23-contributing"></a></div></div></h1><p>The ethers.js library is something that I've written out of necessity, and has grown somewhat organically over time.</p>
<p>Many things are the way they are for good (at the time, at least) reasons, but I always welcome criticism, and am completely willing to have my mind changed on things.</p>
<p>So, pull requests are always welcome, but please keep a few points in mind:</p>
<p><ul><li>Backwards-compatibility-breaking changes will not be accepted; they may be considered for the next major version </li><li>Security is important; adding dependencies require fairly convincing arguments as to why </li><li>The library aims to be lean, so keep an eye on the dist/ethers.min.js file size before and after your changes </li><li>Add test cases for both expected and unexpected input </li><li>Any new features need to be supported by me (future issues, documentation, testing, migration), so anything that is overly complicated or specific may not be accepted </li></ul></p>
<p>In general, <b>please start an issue <i>before</i> beginning a pull request</b>, so we can have a public discussion and figure out the best way to address to problem/feature. <b>:)</b></p>
<aname="/v5/contributing/-%23-contributing--building"></a><aname="/v5/contributing/-%23-contributing--contributing--building"></a><aname="/v5/contributing/"></a><h2class="show-anchors"><div>Building<divclass="anchors"><aclass="self"href="#/v5/contributing/-%23-contributing--building"></a></div></div></h2><p>If you wish to modify the source code, there are a few steps involved in setting up your environment.</p>
<p>Since the library uses a monorepo, you must install an initial required set of libraries, which can then be used to install the remaining libraries used within each package, as well as link all the packages within the repo with each other.</p>
<divclass="code-title"><div>Preparing for builds</div></div><divclass="code"># Clone the repository
/home/ricmoo/ethers.js> npm run bootstrap</div><aname="/v5/contributing/-%23-contributing--updating"></a><aname="/v5/contributing/-%23-contributing--contributing--updating"></a><aname="/v5/contributing/"></a><h2class="show-anchors"><div>Making your changes<divclass="anchors"><aclass="self"href="#/v5/contributing/-%23-contributing--updating"></a></div></div></h2><p>TODO: Add more information here.</p>
<divclass="code-title"><div>Watching and Building</div></div><divclass="code"># Begin watching the files and re-building whenever they change
# Sometimes the issue only affects the ESM modules
/home/ricmoo/ethers.js> npm run auto-build-esm
# Or if you only need to run a single build
/home/ricmoo/ethers.js> npm run _build-cjs
/home/ricmoo/ethers.js> npm run _build-esm</div><divclass="code-title"><div>Testing</div></div><divclass="code"># Rebuilds all files and bundles testcases up for testing
/home/ricmoo/ethers.js> npm run _test-node</div><divclass="code-title"><div>Preparing the Distribution</div></div><divclass="code">/home/ricmoo/ethers.js> npm run update-version</div><aname="/v5/contributing/-%23-contributing--documentation"></a><aname="/v5/contributing/-%23-contributing--contributing--documentation"></a><aname="/v5/contributing/"></a><h2class="show-anchors"><div>Documentation<divclass="anchors"><aclass="self"href="#/v5/contributing/-%23-contributing--documentation"></a></div></div></h2><p>The documents are generated using <ahref="#/v5/documentation/">Flatworm</a> documentation generation tool, which was written for the purpose of writing the documentation for ethers.</p>
<p>Style Guide (this section will have much more coming):</p>
<p><ul><li>Try to keep lines no longer than <i>around</i> 80 characters </li><li>Avoid inline links in the source; use the <codeclass="inline">externalLinks</code> field in the config.js </li><li>Prefix external links with <codeclass="inline">link-</code></li><li>Changing an anchor name must be well justified, as it will break all existing links to that section; flatworm will support symblinks in the future </li><li>In general, I aim for xonsistency; look to similar situations throughout the documentation </li></ul></p>
<aname="/v5/contributing/-%23-contributing--contributing--documentation--building"></a><aname="/v5/contributing/"></a><h3class="show-anchors"><div>Building<divclass="anchors"><aclass="self"href="#/v5/contributing/-%23-contributing--contributing--documentation--building"></a></div></div></h3><p>To build the documentation, you should first follow the <ahref="#/v5/contributing/-%23-contributing--building">above steps</a> to build the ethers library.</p>
<p>Building the docs will generate several types of output:</p>
<p><ul><li>A full set of HTML pages, linking across each other </li><li>A single one-page HTML page with all pages linking to local anchors </li><li>A full set of README.md pages organized to be browsable and linkable in GitHub </li><li>A metadata dump for tool ingestion (still needs more work) </li><li>(@TODO; only half done) The documentation as a LaTeX and generated PDF </li></ul></p>
<divclass="code-title"><div>Building the Documentations</div></div><divclass="code">/home/ricmoo/ethers.js> npm run build-docs</div><aname="/v5/contributing/-%23-contributing--contributing--documentation--evaluation"></a><aname="/v5/contributing/"></a><h3class="show-anchors"><div>Evaluation<divclass="anchors"><aclass="self"href="#/v5/contributing/-%23-contributing--contributing--documentation--evaluation"></a></div></div></h3><p>When building the documentation, all code samples are run through a JavaScript VM to ensure there are no typos in the example code, as well the exact output of results are injected into the output, so there is no need to keep the results and code in-sync.</p>
<p>However, this can be a bit of a headache when making many small changes, so to build the documentation faster, you can skip the evaluation step, which will inject the code directly.</p>
<divclass="code-title"><div>Build docs skipping evaluation</div></div><divclass="code">/home/ricmoo/ethers.js> npm run build-docs -- --skip-eval</div><aname="/v5/contributing/-%23-contributing--contributing--documentation--previewing-changes"></a><aname="/v5/contributing/"></a><h3class="show-anchors"><div>Previewing Changes<divclass="anchors"><aclass="self"href="#/v5/contributing/-%23-contributing--contributing--documentation--previewing-changes"></a></div></div></h3><p>To preview the changes locally, you can use any standard web server and run from the <codeclass="inline">/docs/</code> folder, or use the built-in web server.</p>
<p>The same caveats as normal web development apply, such flushing browser caches after changing (and re-building) the docs.</p>
<divclass="code-title"><div>Running a webserver</div></div><divclass="code">/home/ricmoo/ethers.js> npm run serve-docs</div><divclass="page-separator"></div><aname="/v5/documentation/-%23-flatworm"></a><aname="/v5/documentation/-%23-flatworm"></a><aname="/v5/documentation/"></a><h1class="show-anchors"><div>Flatworm Docs<divclass="anchors"><aclass="self"href="#/v5/documentation/-%23-flatworm"></a></div></div></h1><p>The <i>Flatworm Docs</i> rendering engine is designed to be <b>very</b> simple, but provide enough formatting necessary for documenting JavaScript libraries.</p>
<p>A lot of its inspiration came from <ahref="https://github.com/readthedocs/sphinx_rtd_theme">Read the Docs</a> and the <ahref="https://www.sphinx-doc.org/">Sphinx</a> project.</p>
<aname="/v5/documentation/-%23-flatworm-fragments"></a><aname="/v5/documentation/-%23-flatworm--flatworm-fragments"></a><aname="/v5/documentation/"></a><h2class="show-anchors"><div>Fragments<divclass="anchors"><aclass="self"href="#/v5/documentation/-%23-flatworm-fragments"></a></div></div></h2><p>Each page is made up of fragments. A fragment is a <ahref="#/v5/documentation/-%23-flatworm-directive">directive</a>, with an value and optional <i>link</i>, <i>extensions</i> and a body.</p>
BODY: Optional; the directive body (certain directives only)</div><aname="/v5/documentation/-%23-flatworm-directive"></a><aname="/v5/documentation/-%23-flatworm--flatworm-fragments--flatworm-directive"></a><aname="/v5/documentation/"></a><h3class="show-anchors"><div>Flatworm Directives<divclass="anchors"><aclass="self"href="#/v5/documentation/-%23-flatworm-directive"></a></div></div></h3>
<divclass="definition"><divclass="term"><b>_section:</b><i>TITLE</i></div><divclass="body"><p>A <i>section</i> has its <b>TITLE</b> in an H1 font. Sections are linked to in <i>Table of Contents</i> and have a dividing line drawn above them.</p>
<p>The body supports markdown.</p>
<p>There should only be one <codeclass="inline">_section:</code> per page.</p>
</div></div><divclass="definition"><divclass="term"><b>_subsection:</b><i>TITLE</i></div><divclass="body"><p>A <i>subsection</i> has its <b>TITLE</b> in an H2 font. Subsections are linked to in <i>Table of Contents</i> and have a dividing line drawn above them.</p>
</div></div><divclass="definition"><divclass="term"><b>_heading:</b><i>TITLE</i></div><divclass="body"><p>A <i>heading</i> has its <b>TITLE</b> in an H3 font.</p>
</div></div><divclass="definition"><divclass="term"><b>_definition:</b><i>TERM</i></div><divclass="body"><p>A <i>definition</i> has its <b>TERM</b> in normal text and the body is indented.</p>
<p>The title and body support markdown.</p>
</div></div><divclass="definition"><divclass="term"><b>_property:</b><i>SIGNATURE</i></div><divclass="body"><p>A <i>property</i> has its JavaScript <b>SIGNATURE</b> formatted.</p>
<p>The body supports markdown and the return portion of the signature support markdown links.</p>
</div></div><divclass="definition"><divclass="term"><b>_note:</b><i>BANNER</i></div><divclass="body"><p>A <i>note</i> is placed in a blue bordered-box to draw attention to it.</p>
<p>The body supports markdown.</p>
</div></div><divclass="definition"><divclass="term"><b>_warning:</b><i>BANNER</i></div><divclass="body"><p>A <i>warning</i> is placed in an orange bordered-box to draw attention to it.</p>
<p>The body supports markdown.</p>
</div></div><divclass="definition"><divclass="term"><b>_code:</b><i>CAPTION</i></div><divclass="body"><p>Creates a <ahref="#/v5/documentation/-%23-flatworm--code">Code</a> block.</p>
<p>The body does <b>not</b> support markdown, and will be output exactly as is, with the exception of <ahref="#/v5/documentation/-%23-flatworm--code-eval">Code Evaluation</a>.</p>
<p>If a line begins with a <codeclass="inline">"_"</code>, it should be escaped with a <codeclass="inline">"\"</code>.</p>
</div></div><divclass="definition"><divclass="term"><b>_table:</b><i>FOOTER</i></div><divclass="body"><p>Creates a <ahref="#/v5/documentation/-%23-flatworm--table">Table</a> structured according to the body.</p>
</div></div><divclass="definition"><divclass="term"><b>_toc:</b></div><divclass="body"><p>A <i>toc</i> injects a Table of Contents, loading each line of the body as a filename and recursively loads the <i>toc</i> if present, otherwise all the <i>sections</i> and <i>subsections</i>.</p>
<p>The body does <b>not</b> support markdown, as it is interpreted as a list of files and directories to process.</p>
</div></div><divclass="definition"><divclass="term"><b>_null:</b></div><divclass="body"><p>A <i>null</i> is used to terminated a directive. For example, after a <i>definition</i>, the bodies are indented, so a <i>null</i> can be used to reset the indentation.</p>
<p>The body supports markdown.</p>
</div></div><divclass="code-title"><div>Example</div></div><divclass="code">_section: Hello World @<link-main>
Body for section...
_subsection: Some Example @<link-secondary>
Body for subsection...
_heading: Large Bold Text @<link-here>
Body for heading...
_definition: Flatworm
A phylum of relatively **simple** bilaterian, unsegmented,
soft-bodied invertebrates.
_property: String.fromCharCode(code) => string
Returns a string created from //code//, a sequence of
This breaks out of a directive. For example, to end
a ``_note:`` or ``_code:``.</div><aname="/v5/documentation/-%23-flatworm-markdown"></a><aname="/v5/documentation/-%23-flatworm--flatworm-markdown"></a><aname="/v5/documentation/"></a><h2class="show-anchors"><div>Markdown<divclass="anchors"><aclass="self"href="#/v5/documentation/-%23-flatworm-markdown"></a></div></div></h2><p>The markdown is simple and does not have the flexibility of other dialects, but allows for <b>bold</b>, <i>italic</i>, <u>underlined</u>, <codeclass="inline">monospaced</code>, super<sup>script</sup> and <strike>strike</strike> text, supporting <ahref="#/v5/documentation/-%23-flatworm-markdown">links</a> and lists.</p>
[[some-link]] will use the title from its directives value.</div><aname="/v5/documentation/-%23-flatworm--code"></a><aname="/v5/documentation/-%23-flatworm--flatworm--code"></a><aname="/v5/documentation/"></a><h2class="show-anchors"><div>Code<divclass="anchors"><aclass="self"href="#/v5/documentation/-%23-flatworm--code"></a></div></div></h2><p>The code directive creates a monospace, contained block useful for displaying code samples.</p>
<aname="/v5/documentation/-%23-flatworm--code-eval"></a><aname="/v5/documentation/-%23-flatworm--flatworm--code--flatworm--code-eval"></a><aname="/v5/documentation/"></a><h3class="show-anchors"><div>JavaScript Evaluation<divclass="anchors"><aclass="self"href="#/v5/documentation/-%23-flatworm--code-eval"></a></div></div></h3><p>For JavaScript files, the file is executed with some simple substitution.</p>
<p>A bare <codeclass="inline">//!</code> on a line is replaced with the result of the last statement. Building will fail if an error is thrown.</p>
<p>A bare <codeclass="inline">//!error</code> is replaced with the throw error. Building will fail if an error is not thrown.</p>
<p>Also any code included between the lines <b><codeclass="inline">// <hide></code></b> and <b><codeclass="inline">// </hide></code></b> will be omitted from the output, which can be used to setup variables.</p>
<divclass="code-title"><div>Code Evaluation Example</div></div><divclass="code">_code: Result of Code Example @lang<javascript>
// <hide>
const url = require("url");
// </hide>
url.parse("https://www.ricmoo.com/").protocol
//!
url.parse(45)
//! error
// You want to assign (doesn't emit eval) AND display the value
</span></div><aname="/v5/documentation/-%23-flatworm--flatworm--code--languages"></a><aname="/v5/documentation/"></a><h3class="show-anchors"><div>Languages<divclass="anchors"><aclass="self"href="#/v5/documentation/-%23-flatworm--flatworm--code--languages"></a></div></div></h3><p>The language can be specified using the <ahref="#/v5/documentation/-%23-flatworm--ext-lang">@lang extension</a>.</p>
<tableclass="table minimal"><tr><tdalign="center"><b>Language</b></td><tdalign="center"><b>Notes</b></td><tdclass="fix"> </td></tr><tr><tdalign="center">javascript</td><tdalign="left">Syntax highlights and <ahref="#/v5/documentation/-%23-flatworm--code-eval">evaluates</a> the JavaScipt</td><tdclass="fix"> </td></tr><tr><tdalign="center">script</td><tdalign="left">Same as <codeclass="inline">javascript</code>, but does not evaluate the results</td><tdclass="fix"> </td></tr><tr><tdalign="center">shell</td><tdalign="left">Shell scripts or command-line</td><tdclass="fix"> </td></tr><tr><tdalign="center">text</td><tdalign="left">Plain text with no syntax highlighting</td><tdclass="fix"> </td></tr></table><aname="/v5/documentation/-%23-flatworm--table"></a><aname="/v5/documentation/-%23-flatworm--flatworm--table"></a><aname="/v5/documentation/"></a><h2class="show-anchors"><div>Tables<divclass="anchors"><aclass="self"href="#/v5/documentation/-%23-flatworm--table"></a></div></div></h2><p>The table directive consumes the entire body up until the next directive. To terminate a table early to begin a text block, use a <b>_null:</b> directive.</p>
<p>Each line of the body should be <ahref="#/v5/documentation/-%23-flatworm--table-row">Row Data</a> or a <ahref="#/v5/documentation/-%23-flatworm--table-variable">Variable Declaration</a> (or continuation of a <i>Variable Declaration</i>). Blank lines are ignored.</p>
<aname="/v5/documentation/-%23-flatworm--table-row"></a><aname="/v5/documentation/-%23-flatworm--flatworm--table--flatworm--table-row"></a><aname="/v5/documentation/"></a><h3class="show-anchors"><div>Row Data<divclass="anchors"><aclass="self"href="#/v5/documentation/-%23-flatworm--table-row"></a></div></div></h3><p>Each <b>Row Data</b> line must begin and end with a <b><codeclass="inline">"|"</code></b>, with each gap representing the cell data, <ahref="#/v5/documentation/-%23-flatworm--table-alignment">alignment</a> with optional <ahref="#/v5/documentation/-%23-flatworm--table-spanning">column and row spanning</a>.</p>
<aname="/v5/documentation/-%23-flatworm--table-alignment"></a><aname="/v5/documentation/-%23-flatworm--flatworm--table--flatworm--table-alignment"></a><aname="/v5/documentation/"></a><h3class="show-anchors"><div>Alignment<divclass="anchors"><aclass="self"href="#/v5/documentation/-%23-flatworm--table-alignment"></a></div></div></h3><p>The alignment for a cell is determined by the whitespace surrounding the cell data.</p>
<tableclass="table minimal"><tr><tdalign="center"><b>Alignment</b></td><tdalign="center"><b>Whitespace</b></td><tdclass="fix"> </td></tr><tr><tdalign="center"><i>Left</i></td><tdalign="left">1 or fewer spaces before the content</td><tdclass="fix"> </td></tr><tr><tdalign="center"><i>Right</i></td><tdalign="left">1 or fewer spaces after the content</td><tdclass="fix"> </td></tr><tr><tdalign="center"><i>Center</i></td><tdalign="left">2 or more space <b>both</b> before and after the content</td><tdclass="fix"> </td></tr><tr><tdclass="table-title"colspan="2">Alignment Conditions (higher precedence listed first)</td><tdclass="fix"> </td></tr></table><divclass="code-title"><div>Alignment Example</div></div><divclass="code">_table: Result of Alignment Example @style<compact>
| right|</div><tableclass="table compact"><tr><tdalign="center"width="100%">center</td><tdclass="fix"> </td></tr><tr><tdalign="left"width="100%">left</td><tdclass="fix"> </td></tr><tr><tdalign="left"width="100%">left</td><tdclass="fix"> </td></tr><tr><tdalign="right"width="100%">right</td><tdclass="fix"> </td></tr><tr><tdalign="right"width="100%">right</td><tdclass="fix"> </td></tr><tr><tdclass="table-title"colspan="1">Result of Alignment Example</td><tdclass="fix"> </td></tr></table><aname="/v5/documentation/-%23-flatworm--table-spanning"></a><aname="/v5/documentation/-%23-flatworm--flatworm--table--flatworm--table-spanning"></a><aname="/v5/documentation/"></a><h3class="show-anchors"><div>Row and Column Spanning<divclass="anchors"><aclass="self"href="#/v5/documentation/-%23-flatworm--table-spanning"></a></div></div></h3><p>A column may end its content with any number of <b><codeclass="inline">"<"</code></b> which indicates how many <i>additional</i> columns to extend into.</p>
<p>If the cell content contains only a <b><codeclass="inline">"^"</code></b>, then the row above is extended into this cell (into the same number of columns).</p>
<divclass="code-title"><div>Cell Spanning Example</div></div><divclass="code">_table: Result of Cell Spanning Example @style<compact>
| ^ | ^ | (1x1) |</div><tableclass="table compact"><tr><tdalign="center"width="25%">(1x1)</td><tdalign="center"colspan="2"width="50%">(1x2)</td><tdalign="center"rowspan="2"width="25%">(2x1)</td><tdclass="fix"> </td></tr><tr><tdalign="center"colspan="2"rowspan="2"width="50%">(2x2)</td><tdalign="center"rowspan="2"width="25%">(2x1)</td><tdclass="fix"> </td></tr><tr><tdalign="center"width="25%">(1x1)</td><tdclass="fix"> </td></tr><tr><tdclass="table-title"colspan="4">Result of Cell Spanning Example</td><tdclass="fix"> </td></tr></table><aname="/v5/documentation/-%23-flatworm--table-style"></a><aname="/v5/documentation/-%23-flatworm--flatworm--table--flatworm--table-style"></a><aname="/v5/documentation/"></a><h3class="show-anchors"><div>Styles<divclass="anchors"><aclass="self"href="#/v5/documentation/-%23-flatworm--table-style"></a></div></div></h3><p>The <ahref="#/v5/documentation/-%23-flatworm--ext-style">@style extension</a> for a table can be used to control its appearance.</p>
<tableclass="table minimal"><tr><tdalign="center"><b>Name</b></td><tdalign="center"><b>Width</b></td><tdalign="center"><b>Columns</b></td><tdclass="fix"> </td></tr><tr><tdalign="center"><i>minimal</i></td><tdalign="center">minimum size</td><tdalign="center">best fit</td><tdclass="fix"> </td></tr><tr><tdalign="center"><i>compact</i></td><tdalign="center">40%</td><tdalign="center">evenly spaced</td><tdclass="fix"> </td></tr><tr><tdalign="center"><i>wide</i></td><tdalign="center">67%</td><tdalign="center">evenly spaced</td><tdclass="fix"> </td></tr><tr><tdalign="center"><i>full</i></td><tdalign="center">100%</td><tdalign="center">evenly spaced</td><tdclass="fix"> </td></tr></table><aname="/v5/documentation/-%23-flatworm--table-variable"></a><aname="/v5/documentation/-%23-flatworm--flatworm--table--flatworm--table-variable"></a><aname="/v5/documentation/"></a><h3class="show-anchors"><div>Variables<divclass="anchors"><aclass="self"href="#/v5/documentation/-%23-flatworm--table-variable"></a></div></div></h3><p>Often the layout of a table is easier to express and maintain without uneven or changing content within it. So the content can be defined separately within a table directive using <b>variables</b>. A varaible name must being with a letter and must only contain letters and numbers.</p>
<p>Variables are also useful when content is repeated throughout a table.</p>
<p>A variable is declared by starting a line with <codeclass="inline">"$NAME:"</code>, which consumes all lines until the next variable declaration or until the next table row line.</p>
<p>A variable name must start with a letter and may consist of letters and numbers. (i.e. <codeclass="inline">/[a-z][a-z0-9]*/i</code>)</p>
<divclass="code-title"><div>Variables Example</div></div><divclass="code">_table: Result of Variables Example
| $bottom <|</div><tableclass="table minimal"><tr><tdalign="center"><b>Feature</b></td><tdalign="center"><b>Supported</b></td><tdclass="fix"> </td></tr><tr><tdalign="center">Dancing Monkey</td><tdalign="center">This option is supported.</td><tdclass="fix"> </td></tr><tr><tdalign="center">Singing Turtle</td><tdalign="center">This option is <b>not</b> supported.</td><tdclass="fix"> </td></tr><tr><tdalign="center">Newt Hair</td><tdalign="center">This option is supported.</td><tdclass="fix"> </td></tr><tr><tdalign="center"colspan="2">This just represents an example of what is possible. Notice that variable content can span multiple lines.</td><tdclass="fix"> </td></tr><tr><tdclass="table-title"colspan="2">Result of Variables Example</td><tdclass="fix"> </td></tr></table><aname="/v5/documentation/-%23-flatworm-config"></a><aname="/v5/documentation/-%23-flatworm--flatworm-config"></a><aname="/v5/documentation/"></a><h2class="show-anchors"><div>Configuration<divclass="anchors"><aclass="self"href="#/v5/documentation/-%23-flatworm-config"></a></div></div></h2><p>Configuration is optional (but highly recommended) and may be either a simple JSON file (config.json) or a JS file (config.js) placed in the top of the source folder.</p>
<aname="/v5/documentation/-%23-flatworm--ext-inherit"></a><aname="/v5/documentation/-%23-flatworm--flatworm-extensions--flatworm--ext-inherit"></a><aname="/v5/documentation/"></a><h3class="show-anchors"><div>@inherit<<i>markdown</i>><divclass="anchors"><aclass="self"href="#/v5/documentation/-%23-flatworm--ext-inherit"></a></div></div></h3><p>Adds an inherits description to a directive. The <i>markdown</i> may contain links.</p>
<aname="/v5/documentation/-%23-flatworm--ext-lang"></a><aname="/v5/documentation/-%23-flatworm--flatworm-extensions--flatworm--ext-lang"></a><aname="/v5/documentation/"></a><h3class="show-anchors"><div>@lang<<i>text</i>><divclass="anchors"><aclass="self"href="#/v5/documentation/-%23-flatworm--ext-lang"></a></div></div></h3><p>Set the language a <ahref="#/v5/documentation/-%23-flatworm--code">code directive</a> should be syntax-highlighted for. If "javascript", the code will be evaluated.</p>
<aname="/v5/documentation/-%23-flatworm--ext-nav"></a><aname="/v5/documentation/-%23-flatworm--flatworm-extensions--flatworm--ext-nav"></a><aname="/v5/documentation/"></a><h3class="show-anchors"><div>@nav<<i>text</i>><divclass="anchors"><aclass="self"href="#/v5/documentation/-%23-flatworm--ext-nav"></a></div></div></h3><p>Sets the name in the breadcrumbs when not the current node.</p>
<aname="/v5/documentation/-%23-flatworm--ext-note"></a><aname="/v5/documentation/-%23-flatworm--flatworm-extensions--flatworm--ext-note"></a><aname="/v5/documentation/"></a><h3class="show-anchors"><div>@note<<i> markdown</i>><divclass="anchors"><aclass="self"href="#/v5/documentation/-%23-flatworm--ext-note"></a></div></div></h3><p>Adds a note to a directive. The <i>markdown</i> may contain links. If the directive already has an @INHERIT extension, that will be used instead and the @NOTE will be ignored.</p>
<aname="/v5/documentation/-%23-flatworm--ext-src"></a><aname="/v5/documentation/-%23-flatworm--flatworm-extensions--flatworm--ext-src"></a><aname="/v5/documentation/"></a><h3class="show-anchors"><div>@src<<i>key</i>><divclass="anchors"><aclass="self"href="#/v5/documentation/-%23-flatworm--ext-src"></a></div></div></h3><p>Calls the configuration <codeclass="inline">getSourceUrl(key, VALUE)</code> to get a URL which will be linked to by a link next to the <i>directive</i>.</p>
<p>This extended directive function requires an advanced <codeclass="inline">config.js</code><ahref="#/v5/documentation/-%23-flatworm-config">Configuration</a> file since it requires a JavaScript function.</p>
<aname="/v5/documentation/-%23-flatworm--ext-style"></a><aname="/v5/documentation/-%23-flatworm--flatworm-extensions--flatworm--ext-style"></a><aname="/v5/documentation/"></a><h3class="show-anchors"><div>@style<<i>text</i>><divclass="anchors"><aclass="self"href="#/v5/documentation/-%23-flatworm--ext-style"></a></div></div></h3><p>The <ahref="#/v5/documentation/-%23-flatworm--table-style">Table Style</a> to use for a table directive.</p>
<divclass="page-separator"></div><aname="/v5/license/-%23-license"></a><aname="/v5/license/-%23-license"></a><aname="/v5/license/"></a><h1class="show-anchors"><div>License and Copyright<divclass="anchors"><aclass="self"href="#/v5/license/-%23-license"></a></div></div></h1><p>The ethers library (including all dependencies) are available under the <ahref="https://en.m.wikipedia.org/wiki/MIT_License">MIT License</a>, which permits a wide variety of uses.</p>
<p>Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:</p>
<p>The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.</p>
<p>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.</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>
