5077 lines
816 KiB
HTML
5077 lines
816 KiB
HTML
<!DOCTYPE html>
|
|
<html class="single-page">
|
|
<head>
|
|
<title>ethers</title>
|
|
<link rel="stylesheet" type="text/css" href="/v5/static/style.css">
|
|
<meta property="og:title" content="ethers"/>
|
|
<meta property="og:description" content="Documentation for ethers, a complete, tiny and simple Ethereum library."/>
|
|
|
|
<meta property="og:image" content="/v5/static/social.jpg"/>
|
|
|
|
</head>
|
|
<body>
|
|
<div class="sidebar">
|
|
<div class="header">
|
|
<div class="logo"><a href="/v5/"><div class="image"></div><div class="name">ethers</div><div class="version">v5.0</div></a></div>
|
|
<div class="search"><form action="/v5/search/" method="GET"><input name="search" id="search" /></form><span class="search-icon">⚲</span></div>
|
|
</div>
|
|
<div class="toc"><div>
|
|
<div class="link title"><a href="/v5/single-page/">Documentation</a></div><div class="show show link depth-1"><a href="#/v5/getting-started/">Getting Started</a></div><div class="show show link depth-1"><a href="#/v5/concepts/">Ethereum Basics</a></div><div class="show show link depth-2"><a href="#/v5/concepts/events/">Events</a></div><div class="show show link depth-2"><a href="#/v5/concepts/gas/">Gas</a></div><div class="show show link depth-2"><a href="#/v5/concepts/security/">Security</a></div><div class="show show link depth-2"><a href="#/v5/concepts/best-practices/">Best Practices</a></div><div class="show show link depth-1"><a href="#/v5/api-keys/">Provider API Keys</a></div><div class="show show link depth-1"><a href="#/v5/api/">Application Programming Interface</a></div><div class="show show link depth-2"><a href="#/v5/api/providers/">Providers</a></div><div class="show show link depth-3"><a href="#/v5/api/providers/provider/">Provider</a></div><div class="show show link depth-3"><a href="#/v5/api/providers/jsonrpc-provider/">JsonRpcProvider</a></div><div class="show show link depth-3"><a href="#/v5/api/providers/api-providers/">API Providers</a></div><div class="show show link depth-3"><a href="#/v5/api/providers/other/">Other Providers</a></div><div class="show show link depth-3"><a href="#/v5/api/providers/types/">Types</a></div><div class="show show link depth-2"><a href="#/v5/api/signer/">Signers</a></div><div class="show show link depth-2"><a href="#/v5/api/contract/">Contract Interaction</a></div><div class="show show link depth-3"><a href="#/v5/api/contract/contract/">Contract</a></div><div class="show show link depth-3"><a href="#/v5/api/contract/contract-factory/">ContractFactory</a></div><div class="show show link depth-3"><a href="#/v5/api/contract/example/">Example: ERC-20 Contract</a></div><div class="show show link depth-2"><a href="#/v5/api/utils/">Utilities</a></div><div class="show show link depth-3"><a href="#/v5/api/utils/abi/">Application Binary Interface</a></div><div class="show show link depth-4"><a href="#/v5/api/utils/abi/coder/">AbiCoder</a></div><div class="show show link depth-4"><a href="#/v5/api/utils/abi/formats/">ABI Formats</a></div><div class="show show link depth-4"><a href="#/v5/api/utils/abi/fragments/">Fragments</a></div><div class="show show link depth-4"><a href="#/v5/api/utils/abi/interface/">Interface</a></div><div class="show show link depth-3"><a href="#/v5/api/utils/address/">Addresses</a></div><div class="show show link depth-3"><a href="#/v5/api/utils/bignumber/">BigNumber</a></div><div class="show show link depth-3"><a href="#/v5/api/utils/bytes/">Byte Manipulation</a></div><div class="show show link depth-3"><a href="#/v5/api/utils/constants/">Constants</a></div><div class="show show link depth-3"><a href="#/v5/api/utils/display-logic/">Display Logic and Input</a></div><div class="show show link depth-3"><a href="#/v5/api/utils/encoding/">Encoding Utilities</a></div><div class="show show link depth-3"><a href="#/v5/api/utils/fixednumber/">FixedNumber</a></div><div class="show show link depth-3"><a href="#/v5/api/utils/hashing/">Hashing Algorithms</a></div><div class="show show link depth-3"><a href="#/v5/api/utils/hdnode/">HD Wallet</a></div><div class="show show link depth-3"><a href="#/v5/api/utils/logger/">Logging</a></div><div class="show show link depth-3"><a href="#/v5/api/utils/properties/">Property Utilities</a></div><div class="show show link depth-3"><a href="#/v5/api/utils/signing-key/">Signing Key</a></div><div class="show show link depth-3"><a href="#/v5/api/utils/strings/">Strings</a></div><div class="show show link depth-3"><a href="#/v5/api/utils/transactions/">Transactions</a></div><div class="show show link depth-3"><a href="#/v5/api/utils/web/">Web Utilities</a></div><div class="show show link depth-3"><a href="#/v5/api/utils/wordlists/">Wordlists</a></div><div class="show show link depth-2"><a href="#/v5/api/other/">Other Libraries</a></div><div class="show show link depth-3"><a href="#/v5/api/other/assembly/">Assembly</a></div><div class="show show link depth-4"><a href="#/v5/api/other/assembly/dialect/">Ethers ASM Dialect</a></div><div class="show show link depth-4"><a href="#/v5/api/other/assembly/api/">Utilities</a></div><div class="show show link depth-4"><a href="#/v5/api/other/assembly/ast/">Abstract Syntax Tree</a></div><div class="show show link depth-3"><a href="#/v5/api/other/hardware/">Hardware Wallets</a></div><div class="show show link depth-2"><a href="#/v5/api/experimental/">Experimental</a></div><div class="show show link depth-1"><a href="#/v5/cli/">Command Line Interfaces</a></div><div class="show show link depth-2"><a href="#/v5/cli/ethers/">Sandbox Utility</a></div><div class="show show link depth-2"><a href="#/v5/cli/asm/">Assembler</a></div><div class="show show link depth-2"><a href="#/v5/cli/ens/">Ethereum Naming Service</a></div><div class="show show link depth-2"><a href="#/v5/cli/typescript/">TypeScript</a></div><div class="show show link depth-2"><a href="#/v5/cli/plugin/">Making Your Own</a></div><div class="show show link depth-1"><a href="#/v5/cookbook/">Cookbook</a></div><div class="show show link depth-2"><a href="#/v5/cookbook/react-native/">React Native (and ilk)</a></div><div class="show show link depth-1"><a href="#/v5/migration/">Migration Guide</a></div><div class="show show link depth-2"><a href="#/v5/migration/web3/">Migration: From Web3.js</a></div><div class="show show link depth-2"><a href="#/v5/migration/ethers-v4/">Migration: From Ethers v4</a></div><div class="show show link depth-1"><a href="#/v5/testing/">Testing</a></div><div class="show show link depth-1"><a href="#/v5/contributing/">Contributing and Hacking</a></div><div class="show show link depth-1"><a href="#/v5/other-resources/">Other Resources</a></div><div class="show show link depth-1"><a href="#/v5/documentation/">Flatworm Docs</a></div><div class="show show link depth-1"><a href="#/v5/license/">License and Copyright</a></div>
|
|
</div></div>
|
|
<div class="footer">
|
|
<a href="/v5/">Split Pages</a>
|
|
</div>
|
|
</div>
|
|
<div class="content">
|
|
<div class="breadcrumbs"><!--BREADCRUMBS--></div>
|
|
<a name="/v5/-%23-documentation"></a><a name="/v5/-%23-documentation"></a><a name="/v5/"></a><h1 class="show-anchors"><div>Documentation<div class="anchors"><a class="self" href="#/v5/-%23-documentation"></a></div></div></h1>
|
|
<a name="/v5/-%23-preamble"></a><a name="/v5/-%23-documentation--preamble"></a><a name="/v5/"></a><h2 class="show-anchors"><div>What is Ethers?<div class="anchors"><a class="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 <a href="https://ethers.io/">ethers.io</a> and has since expanded into a more general-purpose library.</p>
|
|
|
|
<a name="/v5/-%23-features"></a><a name="/v5/-%23-documentation--features"></a><a name="/v5/"></a><h2 class="show-anchors"><div>Features<div class="anchors"><a class="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 <a href="https://github.com/ethereum/wiki/wiki/JSON-RPC">JSON-RPC</a>, <a href="https://infura.io">INFURA</a>, <a href="https://etherscan.io">Etherscan</a>, <a href="https://alchemyapi.io">Alchemy</a>, <a href="https://developers.cloudflare.com/distributed-web/ethereum-gateway/">Cloudflare</a> or <a href="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 <a href="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>
|
|
|
|
<a name="/v5/-%23-documentation--developer-documentation"></a><a name="/v5/"></a><h2 class="show-anchors"><div>Developer Documentation<div class="anchors"><a class="self" href="#/v5/-%23-documentation--developer-documentation"></a></div></div></h2>
|
|
<div class="toc"><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/getting-started/">Getting Started</a></div><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/concepts/">Ethereum Basics</a></div><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/api-keys/">Provider API Keys</a></div><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/api/">Application Programming Interface</a></div><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/cli/">Command Line Interfaces</a></div><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/cookbook/">Cookbook</a></div><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/migration/">Migration Guide</a></div><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/testing/">Testing</a></div><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/contributing/">Contributing and Hacking</a></div><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/other-resources/">Other Resources</a></div><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/documentation/">Flatworm Docs</a></div><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/license/">License and Copyright</a></div></div><a name="/v5/-%23-documentation--legacy"></a><a name="/v5/-%23-documentation--documentation--legacy"></a><a name="/v5/"></a><h2 class="show-anchors"><div>Legacy Documentation<div class="anchors"><a class="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>
|
|
|
|
<p><ul><li><a href="https://docs.ethers.io/v4/">version 4.0</a> </li><li><a href="https://docs.ethers.io/v3/">version 3.0</a> </li></ul></p>
|
|
|
|
<div class="page-separator"></div><a name="/v5/getting-started/-%23-getting-started"></a><a name="/v5/getting-started/-%23-getting-started"></a><a name="/v5/getting-started/"></a><h1 class="show-anchors"><div>Getting Started<div class="anchors"><a class="self" href="#/v5/getting-started/-%23-getting-started"></a></div></div></h1>
|
|
<a name="/v5/getting-started/-%23-installing"></a><a name="/v5/getting-started/-%23-getting-started--installing"></a><a name="/v5/getting-started/"></a><h2 class="show-anchors"><div>Installing<div class="anchors"><a class="self" href="#/v5/getting-started/-%23-installing"></a></div></div></h2><p>Ethers' various Classes and Functions are available to import manually from sub-packages under the <a href="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 class="code">/home/ricmoo> npm install --save ethers</div><a name="/v5/getting-started/-%23-importing"></a><a name="/v5/getting-started/-%23-getting-started--importing"></a><a name="/v5/getting-started/"></a><h2 class="show-anchors"><div>Importing<div class="anchors"><a class="self" href="#/v5/getting-started/-%23-importing"></a></div></div></h2>
|
|
<a name="/v5/getting-started/-%23-getting-started--importing--node-js"></a><a name="/v5/getting-started/"></a><h3 class="show-anchors"><div>Node.js<div class="anchors"><a class="self" href="#/v5/getting-started/-%23-getting-started--importing--node-js"></a></div></div></h3>
|
|
<div class="code-title"><div>node.js require</div></div><div class="code">const { ethers } = require("ethers");
|
|
</div><div class="code-title"><div>ES6 or TypeScript</div></div><div class="code">import { ethers } from "ethers";
|
|
</div><a name="/v5/getting-started/-%23-getting-started--importing--web-browser"></a><a name="/v5/getting-started/"></a><h3 class="show-anchors"><div>Web Browser<div class="anchors"><a class="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 <a href="https://cdn.ethers.io/lib/ethers-5.0.esm.min.js">ethers library</a> to your own webserver and serve it yourself.</p>
|
|
|
|
<p>For quick demos or prototyping though, you can load it in your Web Applications from our CDN.</p>
|
|
|
|
<div class="code-title"><div>ES6 in the Browser</div></div><div class="code"><script type="module">
|
|
import { ethers } from "https://cdn.ethers.io/lib/ethers-5.0.esm.min.js";
|
|
// Your code here...
|
|
</script></div><div class="code-title"><div>ES3 (UMD) in the Browser</div></div><div class="code"><script src="https://cdn.ethers.io/lib/ethers-5.0.umd.min.js"
|
|
type="application/javascript"></script></div><a name="/v5/getting-started/-%23-getting-started--glossary"></a><a name="/v5/getting-started/-%23-getting-started--getting-started--glossary"></a><a name="/v5/getting-started/"></a><h2 class="show-anchors"><div>Common Terminology<div class="anchors"><a class="self" href="#/v5/getting-started/-%23-getting-started--glossary"></a></div></div></h2><p>This section needs work...</p>
|
|
|
|
<table class="table minimal"><tr><td align="left"><b>Provider</b></td><td align="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><td class="fix"> </td></tr><tr><td align="left"><b>Signer</b></td><td align="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><td class="fix"> </td></tr><tr><td align="left"><b>Contract</b></td><td align="left">A Contract is an abstraction which represents a connection to a specific contract on the Ethereum Network, so that applications can use it like a normal JavaScript object.</td><td class="fix"> </td></tr><tr><td class="table-title" colspan="2">Common Terms</td><td class="fix"> </td></tr></table><a name="/v5/getting-started/-%23-getting-started--connecting"></a><a name="/v5/getting-started/-%23-getting-started--getting-started--connecting"></a><a name="/v5/getting-started/"></a><h2 class="show-anchors"><div>Connecting to Ethereum: Metamask<div class="anchors"><a class="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 <a href="https://metamask.io/">Metamask</a>, which is a browser extension that provides:</p>
|
|
|
|
<p><ul><li>A connection to the Ethereum network (a <a href="#/v5/api/providers/provider/">Provider</a>) </li><li>Holds your private key and can sign things (a <a href="#/v5/api/signer/-%23-Signer">Signer</a>) </li></ul></p>
|
|
|
|
<div class="code-title"><div>Connecting to Metamask</div></div><div class="code"><span class="comment">// A Web3Provider wraps a standard Web3 provider, which is
|
|
</span><span class="comment">// what Metamask injects as window.ethereum into each page
|
|
</span>const provider = new ethers.providers.Web3Provider(window.ethereum)
|
|
|
|
<span class="comment">// The Metamask plugin also allows signing transactions to
|
|
</span><span class="comment">// send ether and pay to change state within the blockchain.
|
|
</span><span class="comment">// For this, you need the account signer...
|
|
</span>const signer = provider.getSigner()
|
|
</div><a name="/v5/getting-started/-%23-getting-started--connecting-rpc"></a><a name="/v5/getting-started/-%23-getting-started--getting-started--connecting-rpc"></a><a name="/v5/getting-started/"></a><h2 class="show-anchors"><div>Connecting to Ethereum: RPC<div class="anchors"><a class="self" href="#/v5/getting-started/-%23-getting-started--connecting-rpc"></a></div></div></h2><p>The <a href="https://github.com/ethereum/wiki/wiki/JSON-RPC">JSON-RPC API</a> is another popular method for interacting with Ethereum and is available in all major Ethereum node implementations (e.g. <a href="https://geth.ethereum.org">Geth</a> and <a href="https://www.parity.io">Parity</a>) as well as many third-party web services (e.g. <a href="https://infura.io">INFURA</a>). It typically provides:</p>
|
|
|
|
<p><ul><li>A connection to the Ethereum network (a <a href="#/v5/api/providers/provider/">Provider</a>) </li><li>Holds your private key and can sign thing (a <a href="#/v5/api/signer/-%23-Signer">Signer</a>) </li></ul></p>
|
|
|
|
<div class="code-title"><div>Connecting to an RPC client</div></div><div class="code"><span class="comment">// If you don't specify a //url//, Ethers connects to the default
|
|
</span><span class="comment">// (i.e. ``http:/\/localhost:8545``)
|
|
</span>const provider = new ethers.providers.JsonRpcProvider();
|
|
|
|
<span class="comment">// The provider also allows signing transactions to
|
|
</span><span class="comment">// send ether and pay to change state within the blockchain.
|
|
</span><span class="comment">// For this, we need the account signer...
|
|
</span>const signer = provider.getSigner()
|
|
</div><a name="/v5/getting-started/-%23-getting-started--querying"></a><a name="/v5/getting-started/-%23-getting-started--getting-started--connecting-rpc--getting-started--querying"></a><a name="/v5/getting-started/"></a><h3 class="show-anchors"><div>Querying the Blockchain<div class="anchors"><a class="self" href="#/v5/getting-started/-%23-getting-started--querying"></a></div></div></h3><p>Once you have a <a href="#/v5/api/providers/provider/">Provider</a>, you have a read-only connection to the blockchain, which you can use to query the current state, fetch historic logs, look up deployed code and so on.</p>
|
|
|
|
<div class="code-title"><div>Basic Queries</div></div><div class="code"><span class="comment">// Look up the current block number
|
|
</span>provider.getBlockNumber()
|
|
<span class="result ok">// { Promise: 11817915 }
|
|
</span>
|
|
<span class="comment">// Get the balance of an account (by address or ENS name, if supported by network)
|
|
</span>balance = await provider.getBalance("ethers.eth")
|
|
<span class="result ok">// { BigNumber: "2337132817842795605" }
|
|
</span>
|
|
<span class="comment">// Often you need to format the output to something more user-friendly,
|
|
</span><span class="comment">// such as in ether (instead of wei)
|
|
</span>ethers.utils.formatEther(balance)
|
|
<span class="result ok">// '2.337132817842795605'
|
|
</span>
|
|
<span class="comment">// If a user enters a string in an input field, you may need
|
|
</span><span class="comment">// to convert it from ether (as a string) to wei (as a BigNumber)
|
|
</span>ethers.utils.parseEther("1.0")
|
|
<span class="result ok">// { BigNumber: "1000000000000000000" }
|
|
</span></div><a name="/v5/getting-started/-%23-getting-started--sending"></a><a name="/v5/getting-started/-%23-getting-started--getting-started--connecting-rpc--getting-started--sending"></a><a name="/v5/getting-started/"></a><h3 class="show-anchors"><div>Writing to the Blockchain<div class="anchors"><a class="self" href="#/v5/getting-started/-%23-getting-started--sending"></a></div></div></h3>
|
|
<div class="code-title"><div>Sending Ether</div></div><div class="code"><span class="comment">// Send 1 ether to an ens name.
|
|
</span>const tx = signer.sendTransaction({
|
|
to: "ricmoo.firefly.eth",
|
|
value: ethers.utils.parseEther("1.0")
|
|
});
|
|
</div><a name="/v5/getting-started/-%23-getting-started--contracts"></a><a name="/v5/getting-started/-%23-getting-started--getting-started--contracts"></a><a name="/v5/getting-started/"></a><h2 class="show-anchors"><div>Contracts<div class="anchors"><a class="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 <a href="#/v5/api/contract/contract/">Contract</a> object makes it easier to use an on-chain Contract as a normal JavaScript object, with the methods mapped to encoding and decoding data for you.</p>
|
|
|
|
<p>If you are familiar with Databases, this is similar to an <i>Object Relational Mapper</i> (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> (ABI) provides.</p>
|
|
|
|
<p>This class is a <i>meta-class</i>, which means its methods are constructed at runtime, and when you pass in the ABI to the constructor it uses it to determine which methods to add.</p>
|
|
|
|
<p>While an 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 you can use the Human-Readable ABI in code, which the following examples use.</p>
|
|
|
|
<div class="code-title"><div>Connecting to the DAI Contract</div></div><div class="code"><span class="comment">// You can also use an ENS name for the contract address
|
|
</span>const daiAddress = "dai.tokens.ethers.eth";
|
|
|
|
<span class="comment">// The ERC-20 Contract ABI, which is a common contract interface
|
|
</span><span class="comment">// for tokens (this is the Human-Readable ABI format)
|
|
</span>const daiAbi = [
|
|
<span class="comment"> // Some details about the token
|
|
</span> "function name() view returns (string)",
|
|
"function symbol() view returns (string)",
|
|
|
|
<span class="comment"> // Get the account balance
|
|
</span> "function balanceOf(address) view returns (uint)",
|
|
|
|
<span class="comment"> // Send some of your tokens to someone else
|
|
</span> "function transfer(address to, uint amount)",
|
|
|
|
<span class="comment"> // An event triggered whenever anyone transfers to someone else
|
|
</span> "event Transfer(address indexed from, address indexed to, uint amount)"
|
|
];
|
|
|
|
<span class="comment">// The Contract object
|
|
</span>const daiContract = new ethers.Contract(daiAddress, daiAbi, provider);
|
|
</div><a name="/v5/getting-started/-%23-getting-started--reading"></a><a name="/v5/getting-started/-%23-getting-started--getting-started--contracts--getting-started--reading"></a><a name="/v5/getting-started/"></a><h3 class="show-anchors"><div>Read-Only Methods<div class="anchors"><a class="self" href="#/v5/getting-started/-%23-getting-started--reading"></a></div></div></h3>
|
|
<div class="code-title"><div>Querying the DAI Contract</div></div><div class="code"><span class="comment">// Get the ERC-20 token name
|
|
</span>daiContract.name()
|
|
<span class="result ok">// { Promise: 'Dai Stablecoin' }
|
|
</span>
|
|
<span class="comment">// Get the ERC-20 token symbol (for tickers and UIs)
|
|
</span>daiContract.symbol()
|
|
<span class="result ok">// { Promise: 'DAI' }
|
|
</span>
|
|
<span class="comment">// Get the balance of an address
|
|
</span>balance = await daiContract.balanceOf("ricmoo.firefly.eth")
|
|
<span class="result ok">// { BigNumber: "198172622063578627973" }
|
|
</span>
|
|
<span class="comment">// Format the DAI for displaying to the user
|
|
</span>ethers.utils.formatUnits(balance, 18)
|
|
<span class="result ok">// '198.172622063578627973'
|
|
</span></div><a name="/v5/getting-started/-%23-getting-started--writing"></a><a name="/v5/getting-started/-%23-getting-started--getting-started--contracts--getting-started--writing"></a><a name="/v5/getting-started/"></a><h3 class="show-anchors"><div>State Changing Methods<div class="anchors"><a class="self" href="#/v5/getting-started/-%23-getting-started--writing"></a></div></div></h3>
|
|
<div class="code-title"><div>Sending DAI</div></div><div class="code"><span class="comment">// The DAI Contract is currently connected to the Provider,
|
|
</span><span class="comment">// which is read-only. You need to connect to a Signer, so
|
|
</span><span class="comment">// that you can pay to send state-changing transactions.
|
|
</span>const daiWithSigner = contract.connect(signer);
|
|
|
|
<span class="comment">// Each DAI has 18 decimal places
|
|
</span>const dai = ethers.utils.parseUnits("1.0", 18);
|
|
|
|
<span class="comment">// Send 1 DAI to "ricmoo.firefly.eth"
|
|
</span>tx = daiWithSigner.transfer("ricmoo.firefly.eth", dai);
|
|
</div><a name="/v5/getting-started/-%23-getting-started--events"></a><a name="/v5/getting-started/-%23-getting-started--getting-started--contracts--getting-started--events"></a><a name="/v5/getting-started/"></a><h3 class="show-anchors"><div>Listening to Events<div class="anchors"><a class="self" href="#/v5/getting-started/-%23-getting-started--events"></a></div></div></h3>
|
|
<div class="code-title"><div>Listening to Events</div></div><div class="code"><span class="comment">// Receive an event when ANY transfer occurs
|
|
</span>daiContract.on("Transfer", (from, to, amount, event) => {
|
|
console.log(`${ from } sent ${ formatEther(amount) } to ${ to}`);
|
|
<span class="comment"> // The event object contains the verbatim log data, the
|
|
</span><span class="comment"> // EventFragment and functions to fetch the block,
|
|
</span><span class="comment"> // transaction and receipt and event functions
|
|
</span>});
|
|
|
|
<span class="comment">// A filter for when a specific address receives tokens
|
|
</span>myAddress = "0x8ba1f109551bD432803012645Ac136ddd64DBA72";
|
|
filter = daiContract.filters.Transfer(null, myAddress)
|
|
<span class="result ok">// {
|
|
</span><span class="result ok">// address: 'dai.tokens.ethers.eth',
|
|
</span><span class="result ok">// topics: [
|
|
</span><span class="result ok">// '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef',
|
|
</span><span class="result ok">// null,
|
|
</span><span class="result ok">// '0x0000000000000000000000008ba1f109551bd432803012645ac136ddd64dba72'
|
|
</span><span class="result ok">// ]
|
|
</span><span class="result ok">// }
|
|
</span>
|
|
<span class="comment">// Receive an event when that filter occurs
|
|
</span>daiContract.on(filter, (from, to, amount, event) => {
|
|
<span class="comment"> // The to will always be "address"
|
|
</span> console.log(`I got ${ formatEther(amount) } from ${ from }.`);
|
|
});
|
|
</div><a name="/v5/getting-started/-%23-getting-started--history"></a><a name="/v5/getting-started/-%23-getting-started--getting-started--contracts--getting-started--history"></a><a name="/v5/getting-started/"></a><h3 class="show-anchors"><div>Query Historic Events<div class="anchors"><a class="self" href="#/v5/getting-started/-%23-getting-started--history"></a></div></div></h3>
|
|
<div class="code-title"><div>Filtering Historic Events</div></div><div class="code"><span class="comment">// Get the address of the Signer
|
|
</span>myAddress = await signer.getAddress()
|
|
<span class="result ok">// '0x8ba1f109551bD432803012645Ac136ddd64DBA72'
|
|
</span>
|
|
<span class="comment">// Filter for all token transfers from me
|
|
</span>filterFrom = daiContract.filters.Transfer(myAddress, null);
|
|
<span class="result ok">// {
|
|
</span><span class="result ok">// address: 'dai.tokens.ethers.eth',
|
|
</span><span class="result ok">// topics: [
|
|
</span><span class="result ok">// '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef',
|
|
</span><span class="result ok">// '0x0000000000000000000000008ba1f109551bd432803012645ac136ddd64dba72'
|
|
</span><span class="result ok">// ]
|
|
</span><span class="result ok">// }
|
|
</span>
|
|
<span class="comment">// Filter for all token transfers to me
|
|
</span>filterTo = daiContract.filters.Transfer(null, myAddress);
|
|
<span class="result ok">// {
|
|
</span><span class="result ok">// address: 'dai.tokens.ethers.eth',
|
|
</span><span class="result ok">// topics: [
|
|
</span><span class="result ok">// '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef',
|
|
</span><span class="result ok">// null,
|
|
</span><span class="result ok">// '0x0000000000000000000000008ba1f109551bd432803012645ac136ddd64dba72'
|
|
</span><span class="result ok">// ]
|
|
</span><span class="result ok">// }
|
|
</span>
|
|
<span class="comment">// List all transfers sent from me a specific block range
|
|
</span>daiContract.queryFilter(filterFrom, 9843470, 9843480)
|
|
<span class="result ok">// { Promise: [
|
|
</span><span class="result ok">// {
|
|
</span><span class="result ok">// address: '0x6B175474E89094C44Da98b954EedeAC495271d0F',
|
|
</span><span class="result ok">// args: [
|
|
</span><span class="result ok">// '0x8ba1f109551bD432803012645Ac136ddd64DBA72',
|
|
</span><span class="result ok">// '0x8B3765eDA5207fB21690874B722ae276B96260E0',
|
|
</span><span class="result ok">// { BigNumber: "4750000000000000000" }
|
|
</span><span class="result ok">// ],
|
|
</span><span class="result ok">// blockHash: '0x8462eb2fbcef5aa4861266f59ad5f47b9aa6525d767d713920fdbdfb6b0c0b78',
|
|
</span><span class="result ok">// blockNumber: 9843476,
|
|
</span><span class="result ok">// data: '0x00000000000000000000000000000000000000000000000041eb63d55b1b0000',
|
|
</span><span class="result ok">// decode: [Function],
|
|
</span><span class="result ok">// event: 'Transfer',
|
|
</span><span class="result ok">// eventSignature: 'Transfer(address,address,uint256)',
|
|
</span><span class="result ok">// getBlock: [Function],
|
|
</span><span class="result ok">// getTransaction: [Function],
|
|
</span><span class="result ok">// getTransactionReceipt: [Function],
|
|
</span><span class="result ok">// logIndex: 69,
|
|
</span><span class="result ok">// removeListener: [Function],
|
|
</span><span class="result ok">// removed: false,
|
|
</span><span class="result ok">// topics: [
|
|
</span><span class="result ok">// '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef',
|
|
</span><span class="result ok">// '0x0000000000000000000000008ba1f109551bd432803012645ac136ddd64dba72',
|
|
</span><span class="result ok">// '0x0000000000000000000000008b3765eda5207fb21690874b722ae276b96260e0'
|
|
</span><span class="result ok">// ],
|
|
</span><span class="result ok">// transactionHash: '0x1be23554545030e1ce47391a41098a46ff426382ed740db62d63d7676ff6fcf1',
|
|
</span><span class="result ok">// transactionIndex: 81
|
|
</span><span class="result ok">// },
|
|
</span><span class="result ok">// {
|
|
</span><span class="result ok">// address: '0x6B175474E89094C44Da98b954EedeAC495271d0F',
|
|
</span><span class="result ok">// args: [
|
|
</span><span class="result ok">// '0x8ba1f109551bD432803012645Ac136ddd64DBA72',
|
|
</span><span class="result ok">// '0x00De4B13153673BCAE2616b67bf822500d325Fc3',
|
|
</span><span class="result ok">// { BigNumber: "250000000000000000" }
|
|
</span><span class="result ok">// ],
|
|
</span><span class="result ok">// blockHash: '0x8462eb2fbcef5aa4861266f59ad5f47b9aa6525d767d713920fdbdfb6b0c0b78',
|
|
</span><span class="result ok">// blockNumber: 9843476,
|
|
</span><span class="result ok">// data: '0x00000000000000000000000000000000000000000000000003782dace9d90000',
|
|
</span><span class="result ok">// decode: [Function],
|
|
</span><span class="result ok">// event: 'Transfer',
|
|
</span><span class="result ok">// eventSignature: 'Transfer(address,address,uint256)',
|
|
</span><span class="result ok">// getBlock: [Function],
|
|
</span><span class="result ok">// getTransaction: [Function],
|
|
</span><span class="result ok">// getTransactionReceipt: [Function],
|
|
</span><span class="result ok">// logIndex: 70,
|
|
</span><span class="result ok">// removeListener: [Function],
|
|
</span><span class="result ok">// removed: false,
|
|
</span><span class="result ok">// topics: [
|
|
</span><span class="result ok">// '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef',
|
|
</span><span class="result ok">// '0x0000000000000000000000008ba1f109551bd432803012645ac136ddd64dba72',
|
|
</span><span class="result ok">// '0x00000000000000000000000000de4b13153673bcae2616b67bf822500d325fc3'
|
|
</span><span class="result ok">// ],
|
|
</span><span class="result ok">// transactionHash: '0x1be23554545030e1ce47391a41098a46ff426382ed740db62d63d7676ff6fcf1',
|
|
</span><span class="result ok">// transactionIndex: 81
|
|
</span><span class="result ok">// }
|
|
</span><span class="result ok">// ] }
|
|
</span>
|
|
//
|
|
<span class="comment">// The following have had the results omitted due to the
|
|
</span><span class="comment">// number of entries; but they provide some useful examples
|
|
</span>//
|
|
|
|
<span class="comment">// List all transfers sent in the last 10,000 blocks
|
|
</span>daiContract.queryFilter(filterFrom, -10000)
|
|
|
|
<span class="comment">// List all transfers ever sent to me
|
|
</span>daiContract.queryFilter(filterTo)
|
|
</div><a name="/v5/getting-started/-%23-getting-started--signing"></a><a name="/v5/getting-started/-%23-getting-started--getting-started--signing"></a><a name="/v5/getting-started/"></a><h2 class="show-anchors"><div>Signing Messages<div class="anchors"><a class="self" href="#/v5/getting-started/-%23-getting-started--signing"></a></div></div></h2>
|
|
<div class="code-title"><div>Signing Messages</div></div><div class="code"><span class="comment">// To sign a simple string, which are used for
|
|
</span><span class="comment">// logging into a service, such as CryptoKitties,
|
|
</span><span class="comment">// pass the string in.
|
|
</span>signature = await signer.signMessage("Hello World");
|
|
<span class="result ok">// '0x800d1d157d472b0cb567ec0d9e2825203aaa7e84db5a9b19169c0c85575f6e0761e99bd670ed82f71a346020cdec8326644132cdeffd8e327d888f94f21825e01b'
|
|
</span>
|
|
//
|
|
<span class="comment">// A common case is also signing a hash, which is 32
|
|
</span><span class="comment">// bytes. It is important to note, that to sign binary
|
|
</span><span class="comment">// data it MUST be an Array (or TypedArray)
|
|
</span>//
|
|
|
|
<span class="comment">// This string is 66 characters long
|
|
</span>message = "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
|
|
|
|
<span class="comment">// This array representation is 32 bytes long
|
|
</span>messageBytes = ethers.utils.arrayify(message);
|
|
<span class="result ok">// Uint8Array [ 221, 242, 82, 173, 27, 226, 200, 155, 105, 194, 176, 104, 252, 55, 141, 170, 149, 43, 167, 241, 99, 196, 161, 22, 40, 245, 90, 77, 245, 35, 179, 239 ]
|
|
</span>
|
|
<span class="comment">// To sign a hash, you most often want to sign the bytes
|
|
</span>signature = await signer.signMessage(messageBytes)
|
|
<span class="result ok">// '0x3ec3dca35ae2712e7f9bb1e2819f9b40c818c567b1a01586d3b0d0a73bad1c303b7f39d4471ac0c9eb900438bc6b6a4bf5b2c120a5cb31edc2cfab11ede409381b'
|
|
</span></div><div class="page-separator"></div><a name="/v5/concepts/-%23-ethereum-basics"></a><a name="/v5/concepts/"></a><h1 class="show-anchors"><div>Ethereum Basics<div class="anchors"><a class="self" href="#/v5/concepts/-%23-ethereum-basics"></a></div></div></h1><p>This is a brief 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 sparse at the moment, but will be expanded as time goes on.</p>
|
|
|
|
<div class="toc"><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/concepts/events/">Events</a></div><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/concepts/gas/">Gas</a></div><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/concepts/security/">Security</a></div><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/concepts/best-practices/">Best Practices</a></div></div><div class="page-separator"></div><a name="/v5/concepts/events/-%23-events"></a><a name="/v5/concepts/events/-%23-events"></a><a name="/v5/concepts/events/"></a><h1 class="show-anchors"><div>Events<div class="anchors"><a class="self" href="#/v5/concepts/events/-%23-events"></a></div></div></h1>
|
|
<a name="/v5/concepts/events/-%23-events--logs-and-filtering"></a><a name="/v5/concepts/events/"></a><h2 class="show-anchors"><div>Logs and Filtering<div class="anchors"><a class="self" href="#/v5/concepts/events/-%23-events--logs-and-filtering"></a></div></div></h2><p>Logs and filtering are used quite often in blockchain applications, since they allow for efficient queries of indexed data and provide lower-cost data storage when the data is not required to be accessed on-chain.</p>
|
|
|
|
<p>These can be used in conjunction with the <a href="#/v5/api/providers/provider/-%23-Provider--event-methods">Provider Events API</a> and with the <a href="#/v5/api/contract/contract/-%23-Contract--events">Contract Events API</a>.</p>
|
|
|
|
<p>The Contract Events API also provides <a href="#/v5/api/contract/contract/-%23-Contract--filters">higher-level methods</a> to compute and query this data, which should be preferred over the lower-level filter.</p>
|
|
|
|
<a name="/v5/concepts/events/-%23-events--filters"></a><a name="/v5/concepts/events/-%23-events--logs-and-filtering--events--filters"></a><a name="/v5/concepts/events/"></a><h3 class="show-anchors"><div>Filters<div class="anchors"><a class="self" href="#/v5/concepts/events/-%23-events--filters"></a></div></div></h3><p>When a Contract creates a log, it can include up to 4 pieces of data to be indexed by. The indexed data is hashed and included in a <a href="https://en.wikipedia.org/wiki/Bloom_filter">Bloom Filter</a>, which is a data structure that allows for efficient filtering.</p>
|
|
|
|
<p>So, a filter may correspondingly have up to 4 topic-sets, where each topic-set refers to a condition that must match the indexed log topic in that position (i.e. each condition is <code class="inline">AND</code>-ed together).</p>
|
|
|
|
<p>If a topic-set is <code class="inline">null</code>, a log topic in that position is <b>not filtered</b> at all and <b>any value</b> matches.</p>
|
|
|
|
<p>If a topic-set is a single topic, a log topic in that position <b>must</b> match <b>that topic</b>.</p>
|
|
|
|
<p>If a topic-set is an array of topics, a log topic in that position must match <b>any one</b> of the topics (i.e. the topic in this position are <code class="inline">OR</code>-ed).</p>
|
|
|
|
<p>This may sound complicated at first, but is more easily understood with some examples.</p>
|
|
|
|
<table class="table full"><tr><td align="center" width="25%"><b>Topic-Sets</b></td><td align="center" colspan="3" width="75%"><b>Matching Logs</b></td><td class="fix"> </td></tr><tr><td align="center" width="25%">[ A ]</td><td align="left" colspan="3" rowspan="2" width="75%">topic[0] = A</td><td class="fix"> </td></tr><tr><td align="center" width="25%">[ A, null ]</td><td class="fix"> </td></tr><tr><td align="center" width="25%">[ null, B ]</td><td align="left" colspan="3" rowspan="3" width="75%">topic[1] = B</td><td class="fix"> </td></tr><tr><td align="center" width="25%">[ null, [ B ] ]</td><td class="fix"> </td></tr><tr><td align="center" width="25%">[ null, [ B ], null ]</td><td class="fix"> </td></tr><tr><td align="center" width="25%">[ A, B ]</td><td align="left" colspan="3" rowspan="3" width="75%">(topic[0] = A) <b>AND</b> (topic[1] = B)</td><td class="fix"> </td></tr><tr><td align="center" width="25%">[ A, [ B ] ]</td><td class="fix"> </td></tr><tr><td align="center" width="25%">[ A, [ B ], null ]</td><td class="fix"> </td></tr><tr><td align="center" width="25%">[ [ A, B ] ]</td><td align="left" colspan="3" rowspan="2" width="75%">(topic[0] = A) <b>OR</b> (topic[0] = B)</td><td class="fix"> </td></tr><tr><td align="center" width="25%">[ [ A, B ], null ]</td><td class="fix"> </td></tr><tr><td align="center" width="25%">[ [ A, B ], [ C, D ] ]</td><td align="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><td class="fix"> </td></tr><tr><td class="table-title" colspan="4">Example Log Matching</td><td class="fix"> </td></tr></table><div class="code-title"><div>ERC-20 Transfer Filter Examples</div></div><div class="code"><span class="comment">// Short example of manually creating filters for an ERC-20
|
|
</span><span class="comment">// Transfer event.
|
|
</span>//
|
|
<span class="comment">// Most users should generally use the Contract API to
|
|
</span><span class="comment">// compute filters, as it is much simpler, but this is
|
|
</span><span class="comment">// provided as an illustration for those curious. See
|
|
</span><span class="comment">// below for examples of the equivalent Contract API.
|
|
</span>
|
|
<span class="comment">// ERC-20:
|
|
</span><span class="comment">// Transfer(address indexed src, address indexed dst, uint val)
|
|
</span>//
|
|
<span class="comment">// -------------------^
|
|
</span><span class="comment">// ----------------------------------------^
|
|
</span>//
|
|
<span class="comment">// Notice that only *src* and *dst* are *indexed*, so ONLY they
|
|
</span><span class="comment">// qualify for filtering.
|
|
</span>//
|
|
<span class="comment">// Also, note that in Solidity an Event uses the first topic to
|
|
</span><span class="comment">// identify the Event name; for Transfer this will be:
|
|
</span><span class="comment">// id("Transfer(address,address,uint256)")
|
|
</span>//
|
|
<span class="comment">// Other Notes:
|
|
</span><span class="comment">// - A topic must be 32 bytes; so shorter types must be padded
|
|
</span>
|
|
<span class="comment">// List all token transfers *from* myAddress
|
|
</span>filter = {
|
|
address: tokenAddress,
|
|
topics: [
|
|
id("Transfer(address,address,uint256)"),
|
|
hexZeroPad(myAddress, 32)
|
|
]
|
|
}
|
|
|
|
<span class="comment">// List all token transfers *to* myAddress:
|
|
</span>filter = {
|
|
address: tokenAddress,
|
|
topics: [
|
|
id("Transfer(address,address,uint256)"),
|
|
null,
|
|
hexZeroPad(myAddress, 32)
|
|
]
|
|
}
|
|
|
|
<span class="comment">// List all token transfers *to* myAddress or myOtherAddress:
|
|
</span>filter = {
|
|
address: tokenAddress,
|
|
topics: [
|
|
id("Transfer(address,address,uint256)"),
|
|
null,
|
|
[
|
|
hexZeroPad(myAddress, 32),
|
|
hexZeroPad(myOtherAddress, 32),
|
|
]
|
|
]
|
|
}
|
|
</div><p>To simplify life, ..., explain here, the contract API</p>
|
|
|
|
<div class="code-title"><div>ERC-20 Contract Filter Examples</div></div><div class="code">const abi = [
|
|
"event Transfer(address indexed src, address indexed dst, uint val)"
|
|
];
|
|
|
|
const contract = new Contract(tokenAddress, abi, provider);
|
|
|
|
<span class="comment">// List all token transfers *from* myAddress
|
|
</span>contract.filters.Transfer(myAddress)
|
|
<span class="result ok">// {
|
|
</span><span class="result ok">// address: '0x6B175474E89094C44Da98b954EedeAC495271d0F',
|
|
</span><span class="result ok">// topics: [
|
|
</span><span class="result ok">// '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef',
|
|
</span><span class="result ok">// '0x0000000000000000000000008ba1f109551bd432803012645ac136ddd64dba72'
|
|
</span><span class="result ok">// ]
|
|
</span><span class="result ok">// }
|
|
</span>
|
|
<span class="comment">// List all token transfers *to* myAddress:
|
|
</span>contract.filters.Transfer(null, myAddress)
|
|
<span class="result ok">// {
|
|
</span><span class="result ok">// address: '0x6B175474E89094C44Da98b954EedeAC495271d0F',
|
|
</span><span class="result ok">// topics: [
|
|
</span><span class="result ok">// '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef',
|
|
</span><span class="result ok">// null,
|
|
</span><span class="result ok">// '0x0000000000000000000000008ba1f109551bd432803012645ac136ddd64dba72'
|
|
</span><span class="result ok">// ]
|
|
</span><span class="result ok">// }
|
|
</span>
|
|
<span class="comment">// List all token transfers *from* myAddress *to* otherAddress:
|
|
</span>contract.filters.Transfer(myAddress, otherAddress)
|
|
<span class="result ok">// {
|
|
</span><span class="result ok">// address: '0x6B175474E89094C44Da98b954EedeAC495271d0F',
|
|
</span><span class="result ok">// topics: [
|
|
</span><span class="result ok">// '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef',
|
|
</span><span class="result ok">// '0x0000000000000000000000008ba1f109551bd432803012645ac136ddd64dba72',
|
|
</span><span class="result ok">// '0x000000000000000000000000ea517d5a070e6705cc5467858681ed953d285eb9'
|
|
</span><span class="result ok">// ]
|
|
</span><span class="result ok">// }
|
|
</span>
|
|
<span class="comment">// List all token transfers *to* myAddress OR otherAddress:
|
|
</span>contract.filters.Transfer(null, [ myAddress, otherAddress ])
|
|
<span class="result ok">// {
|
|
</span><span class="result ok">// address: '0x6B175474E89094C44Da98b954EedeAC495271d0F',
|
|
</span><span class="result ok">// topics: [
|
|
</span><span class="result ok">// '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef',
|
|
</span><span class="result ok">// null,
|
|
</span><span class="result ok">// [
|
|
</span><span class="result ok">// '0x0000000000000000000000008ba1f109551bd432803012645ac136ddd64dba72',
|
|
</span><span class="result ok">// '0x000000000000000000000000ea517d5a070e6705cc5467858681ed953d285eb9'
|
|
</span><span class="result ok">// ]
|
|
</span><span class="result ok">// ]
|
|
</span><span class="result ok">// }
|
|
</span></div><a name="/v5/concepts/events/-%23-events-solidity"></a><a name="/v5/concepts/events/-%23-events--events-solidity"></a><a name="/v5/concepts/events/"></a><h2 class="show-anchors"><div>Solidity Topics<div class="anchors"><a class="self" href="#/v5/concepts/events/-%23-events-solidity"></a></div></div></h2><p>This is a quick (and non-comprehensive) overview of how events are computed in Solidity.</p>
|
|
|
|
<p>This is likely out of the scope for most developers, but may be intersting to those who want to learn a bit more about the underlying technology.</p>
|
|
|
|
<p>Solidity provides two types of events, anonymous and non-anonymous. The default is non-anonymous, and most developers will not need to worry about anonymous events.</p>
|
|
|
|
<p>For non-anonymous events, up to 3 topics may be indexed (instead of 4), since the first topic is reserved to specify the event signature. This allows non-anonymous events to always be filtered by their event signature.</p>
|
|
|
|
<p>This topic hash is always in the first slot of the indexed data, and is computed by normalizing the Event signature and taking the keccak256 hash of it.</p>
|
|
|
|
<p>For anonymous events, up to 4 topics may be indexed, and there is no signature topic hash, so the events cannot be filtered by the event signature.</p>
|
|
|
|
<p>Each additional indexed property is processed depending on whether its length is fixed or dynamic.</p>
|
|
|
|
<p>For fixed length types (e.g. <code class="inline">uint</code>, <code class="inline">bytes5</code>), all of which are internally exactly 32 bytes (shorter types are padded with zeros; numeric values are padded on the left, data values padded on the right), these are included directly by their actual value, 32 bytes of data.</p>
|
|
|
|
<p>For dynamic types (e.g. <code class="inline">string</code>, <code class="inline">uint256[]</code>) , the value is hashed using keccak256 and this hash is used.</p>
|
|
|
|
<p>Because dynamic types are hashed, there are important consequences in parsing events that should be kept in mind. Mainly that the original value is lost in the event. So, it is possible to tell is a topic is equal to a given string, but if they do not match, there is no way to determine what the value was.</p>
|
|
|
|
<p>If a developer requires that a string value is required to be both able to be filtered and also able to be read, the value must be included in the signature twice, once indexed and once non-indexed (e.g. <code class="inline">someEvent(string indexed searchBy, string clearText)</code>).</p>
|
|
|
|
<p>For a more detailed description, please refer to the <a href="https://docs.soliditylang.org/en/v0.8.1/abi-spec.html#events">Solidity Event Documentation</a>.</p>
|
|
|
|
<a name="/v5/concepts/events/-%23-events--events-solidity--other-things-todo"></a><a name="/v5/concepts/events/"></a><h3 class="show-anchors"><div>Other Things? TODO<div class="anchors"><a class="self" href="#/v5/concepts/events/-%23-events--events-solidity--other-things-todo"></a></div></div></h3><p>Explain what happens to strings and bytes, how to filter and retain the value</p>
|
|
|
|
<div class="page-separator"></div><a name="/v5/concepts/gas/-%23-gas"></a><a name="/v5/concepts/gas/-%23-gas"></a><a name="/v5/concepts/gas/"></a><h1 class="show-anchors"><div>Gas<div class="anchors"><a class="self" href="#/v5/concepts/gas/-%23-gas"></a></div></div></h1><p>Explain attack vectors</p>
|
|
|
|
<a name="/v5/concepts/gas/-%23-gas-price"></a><a name="/v5/concepts/gas/-%23-gas--gas-price"></a><a name="/v5/concepts/gas/"></a><h2 class="show-anchors"><div>Gas Price<div class="anchors"><a class="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>
|
|
|
|
<a name="/v5/concepts/gas/-%23-gas-limit"></a><a name="/v5/concepts/gas/-%23-gas--gas-limit"></a><a name="/v5/concepts/gas/"></a><h2 class="show-anchors"><div>Gas Limit<div class="anchors"><a class="self" href="#/v5/concepts/gas/-%23-gas-limit"></a></div></div></h2>
|
|
<div class="page-separator"></div><a name="/v5/concepts/security/-%23-security"></a><a name="/v5/concepts/security/-%23-security"></a><a name="/v5/concepts/security/"></a><h1 class="show-anchors"><div>Security<div class="anchors"><a class="self" href="#/v5/concepts/security/-%23-security"></a></div></div></h1>
|
|
<a name="/v5/concepts/security/-%23-security--pbkdf"></a><a name="/v5/concepts/security/-%23-security--security--pbkdf"></a><a name="/v5/concepts/security/"></a><h2 class="show-anchors"><div>Key Derivation Functions<div class="anchors"><a class="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 <a href="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>
|
|
|
|
<a name="/v5/concepts/security/-%23-security--security--pbkdf--why-does-it-take-so-long"></a><a name="/v5/concepts/security/"></a><h3 class="show-anchors"><div>Why does it take so long?<div class="anchors"><a class="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 computers, increasing the cost to <a href="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>
|
|
|
|
<a name="/v5/concepts/security/-%23-security--security--pbkdf--mitigating-the-user-experience"></a><a name="/v5/concepts/security/"></a><h3 class="show-anchors"><div>Mitigating the User Experience<div class="anchors"><a class="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>
|
|
|
|
<a name="/v5/concepts/security/-%23-security--security--pbkdf--work-arounds-not-recommended"></a><a name="/v5/concepts/security/"></a><h3 class="show-anchors"><div>Work-Arounds (not recommended)<div class="anchors"><a class="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 class="code"><span class="comment">// Our wallet object
|
|
</span>const wallet = Wallet.createRandom();
|
|
|
|
<span class="comment">// The password to encrypt with
|
|
</span>const password = "password123";
|
|
|
|
<span class="comment">// WARNING: Doing this substantially reduces the security
|
|
</span><span class="comment">// of the wallet. This is highly NOT recommended.
|
|
</span>
|
|
<span class="comment">// We override the default scrypt.N value, which is used
|
|
</span><span class="comment">// to indicate the difficulty to crack this wallet.
|
|
</span>const json = wallet.encrypt(password, {
|
|
scrypt: {
|
|
<span class="comment"> // The number must be a power of 2 (default: 131072)
|
|
</span> N: 64
|
|
}
|
|
});
|
|
</div><div class="page-separator"></div><a name="/v5/concepts/best-practices/-%23-best-practices"></a><a name="/v5/concepts/best-practices/-%23-best-practices"></a><a name="/v5/concepts/best-practices/"></a><h1 class="show-anchors"><div>Best Practices<div class="anchors"><a class="self" href="#/v5/concepts/best-practices/-%23-best-practices"></a></div></div></h1>
|
|
<a name="/v5/concepts/best-practices/-%23-best-practices--network-changes"></a><a name="/v5/concepts/best-practices/"></a><h2 class="show-anchors"><div>Network Changes<div class="anchors"><a class="self" href="#/v5/concepts/best-practices/-%23-best-practices--network-changes"></a></div></div></h2><p>Handling a change in the network (e.g. Ropsten vs Mainnet) is incredibly complex and a slight failure can at best make your application seem confusing and at worst cause the loss of funds, leak private data or misrepresent what an action performed.</p>
|
|
|
|
<p>Luckily, standard users should likely never change their networks unless tricked to do so or they make a mistake.</p>
|
|
|
|
<p>This is a problem you mainly need to worry about for developers, and most developers should understand the vast array of issues surrounding a network change during application operation and will understand the page reloading (which is already the default behaviour in many clients).</p>
|
|
|
|
<p>So, the best practice when a network change occurs is to simply refresh the page. This should cause all your UI components to reset to a known-safe state, including any banners and warnings to your users if they are on an unsupported network.</p>
|
|
|
|
<p>This can be accomplished by using the following function:</p>
|
|
|
|
<div class="code-title"><div>Automatically Refresh on Network Change</div></div><div class="code"><span class="comment">// Force page refreshes on network changes
|
|
</span>{
|
|
<span class="comment"> // The "any" network will allow spontaneous network changes
|
|
</span> const provider = new ethers.providers.Web3Provider(window.ethereum, "any");
|
|
provider.on("network", (newNetwork, oldNetwork) => {
|
|
<span class="comment"> // When a Provider makes its initial connection, it emits a "network"
|
|
</span><span class="comment"> // event with a null oldNetwork along with the newNetwork. So, if the
|
|
</span><span class="comment"> // oldNetwork exists, it represents a changing network
|
|
</span> if (oldNetwork) {
|
|
window.location.reload();
|
|
}
|
|
});
|
|
}
|
|
</div><div class="page-separator"></div><a name="/v5/api-keys/-%23-api-keys"></a><a name="/v5/api-keys/-%23-api-keys"></a><a name="/v5/api-keys/"></a><h1 class="show-anchors"><div>Provider API Keys<div class="anchors"><a class="self" href="#/v5/api-keys/-%23-api-keys"></a></div></div></h1><p><i>( <b>TL; DR</b> – sign up for your own API keys with the links below to improve your application performance )</i></p>
|
|
|
|
<p>When using a <a href="#/v5/api/providers/provider/">Provider</a> backed by an API service (such as <a href="https://alchemyapi.io">Alchemy</a>, <a href="https://etherscan.io">Etherscan</a> or <a href="https://infura.io">INFURA</a>), the service requires an API key, which allows each service to track individual projects and their usage and permissions.</p>
|
|
|
|
<p>The ethers library offers default API keys for each service, so that each <a href="#/v5/api/providers/provider/">Provider</a> works out-of-the-box.</p>
|
|
|
|
<p>These API keys are provided as a community resource by the backend services for low-traffic projects and for early prototyping.</p>
|
|
|
|
<p>Since these API keys are shared by all users (that have not acquired their own API key), they are aggressively throttled which means retries occur more frequently and the responses are slower.</p>
|
|
|
|
<p>It is <b>highly recommended</b> that you sign up for a free API key from each service for their free tier, which (depending on the service) includes many advantages:</p>
|
|
|
|
<p><ul><li>a much <b>higher request rate</b> and concurrent request limit </li><li><b>faster</b> responses with fewer retries and timeouts </li><li>useful <b>metric tracking</b> for performance tuning and to analyze your customer behaviour </li><li>more <b>advanced APIs</b>, such as archive data or advanced log queries </li></ul></p>
|
|
|
|
<a name="/v5/api-keys/-%23-api-keys--etherscan"></a><a name="/v5/api-keys/-%23-api-keys--api-keys--etherscan"></a><a name="/v5/api-keys/"></a><h2 class="show-anchors"><div>Etherscan<div class="anchors"><a class="self" href="#/v5/api-keys/-%23-api-keys--etherscan"></a></div></div></h2><p>Etherscan is an Ethereum block explorer, which is possibly the most useful developer tool for building and debugging Ethereum applications.</p>
|
|
|
|
<p>They offer an extensive collection of API endpoints which provide all the operations required to interact with the Ethereum Blockchain.</p>
|
|
|
|
<p><a href="https://etherscan.io/apis">Sign up for a free API key on Etherscan</a></p>
|
|
|
|
<p><b>Benefits:</b></p>
|
|
|
|
<p><ul><li>higher rate limit (since you are not using the <a href="https://info.etherscan.com/api-return-errors/">shared rate limit</a>) </li><li>customer usage metrics </li></ul></p>
|
|
|
|
<a name="/v5/api-keys/-%23-api-keys--infura"></a><a name="/v5/api-keys/-%23-api-keys--api-keys--infura"></a><a name="/v5/api-keys/"></a><h2 class="show-anchors"><div>INFURA<div class="anchors"><a class="self" href="#/v5/api-keys/-%23-api-keys--infura"></a></div></div></h2><p>The INFURA service has been around for quite some time and is very robust and reliable and highly recommended.</p>
|
|
|
|
<p>They offer a standard JSON-RPC interface and a WebSocket interface, which makes interaction with standard tools versatile, simple and straight forward.</p>
|
|
|
|
<p><a href="https://infura.io/register">Sign up for a free Project ID on INFURA</a></p>
|
|
|
|
<p><b>Benefits:</b></p>
|
|
|
|
<p><ul><li>higher rate limit </li><li>customer usage metrics </li><li>access to archive data (requires paid upgrade) </li></ul></p>
|
|
|
|
<a name="/v5/api-keys/-%23-api-keys--alchemy"></a><a name="/v5/api-keys/-%23-api-keys--api-keys--alchemy"></a><a name="/v5/api-keys/"></a><h2 class="show-anchors"><div>Alchemy<div class="anchors"><a class="self" href="#/v5/api-keys/-%23-api-keys--alchemy"></a></div></div></h2><p>The Alchemy service has been around a few years and is also very robust and reliable.</p>
|
|
|
|
<p>They offer a standard JSON-RPC interface and a WebSocket interface, as well as a collection of advanced APIs for interacting with tokens and to assist with debugging.</p>
|
|
|
|
<p><a href="https://dashboard.alchemyapi.io/signup?referral=55a35117-028e-4b7c-9e47-e275ad0acc6d">Sign up for a free API key on Alchemy</a></p>
|
|
|
|
<p><b>Benefits:</b></p>
|
|
|
|
<p><ul><li>higher rate limit </li><li>customer usage metrics </li><li>access to advanced token balance and metadata APIs </li><li>access to advanced debugging trace and revert reason APIs </li></ul></p>
|
|
|
|
<a name="/v5/api-keys/-%23-api-keys--pocket-gateway"></a><a name="/v5/api-keys/-%23-api-keys--api-keys--pocket-gateway"></a><a name="/v5/api-keys/"></a><h2 class="show-anchors"><div>Pocket Gateway<div class="anchors"><a class="self" href="#/v5/api-keys/-%23-api-keys--pocket-gateway"></a></div></div></h2><p><a href="https://pokt.network/pocket-gateway-ethereum-mainnet/">Sign up for a free API key on Pocket</a></p>
|
|
|
|
<p><b>Benefits:</b></p>
|
|
|
|
<p><ul><li>customer usage metrics </li><li>decentralized Access to Blockchain Infrastructure </li><li>Stake as opposed to paying a monthly fee </li><li>Highly redundant global set of nodes incentivized by cryptoeconomic incentives </li></ul></p>
|
|
|
|
<a name="/v5/api-keys/-%23-api-keys--getDefaultProvider"></a><a name="/v5/api-keys/-%23-api-keys--api-keys--getDefaultProvider"></a><a name="/v5/api-keys/"></a><h2 class="show-anchors"><div>Creating a Default Provider<div class="anchors"><a class="self" href="#/v5/api-keys/-%23-api-keys--getDefaultProvider"></a></div></div></h2><p>The <a href="#/v5/api/providers/-%23-providers-getDefaultProvider">default provider</a> connects to multiple backends and verifies their results internally, making it simple to have a high level of trust in third-party services.</p>
|
|
|
|
<p>A second optional parameter allows API keys to be specified to each Provider created internally and any API key omitted will fallback onto using the default API key for that service.</p>
|
|
|
|
<p>It is <b>highly recommended</b> that you provide an API for each service, to maximize your applications performance.</p>
|
|
|
|
<div class="code-title"><div>Passing API Keys into getDefaultProvider</div></div><div class="code"><span class="comment">// Use the mainnet
|
|
</span>const network = "homestead";
|
|
|
|
<span class="comment">// Specify your own API keys
|
|
</span><span class="comment">// Each is optional, and if you omit it the default
|
|
</span><span class="comment">// API key for that service will be used.
|
|
</span>const provider = ethers.getDefaultProvider(network, {
|
|
etherscan: YOUR_ETHERSCAN_API_KEY,
|
|
infura: YOUR_INFURA_PROJECT_ID,
|
|
<span class="comment"> // Or if using a project secret:
|
|
</span><span class="comment"> // infura: {
|
|
</span><span class="comment"> // projectId: YOUR_INFURA_PROJECT_ID,
|
|
</span><span class="comment"> // projectSecret: YOUR_INFURA_PROJECT_SECRET,
|
|
</span><span class="comment"> // },
|
|
</span> alchemy: YOUR_ALCHEMY_API_KEY,
|
|
pocket: YOUR_POCKET_APPLICATION_KEY
|
|
<span class="comment"> // Or if using an application secret key:
|
|
</span><span class="comment"> // pocket: {
|
|
</span><span class="comment"> // applicationId: ,
|
|
</span><span class="comment"> // applicationSecretKey:
|
|
</span><span class="comment"> // }
|
|
</span>});
|
|
</div><div class="page-separator"></div><a name="/v5/api/-%23-api"></a><a name="/v5/api/-%23-api"></a><a name="/v5/api/"></a><h1 class="show-anchors"><div>Application Programming Interface<div class="anchors"><a class="self" href="#/v5/api/-%23-api"></a></div></div></h1><p>An Application Programming Interface (API) is the formal specification of the library.</p>
|
|
|
|
<div class="toc"><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/api/providers/">Providers</a></div><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/api/signer/">Signers</a></div><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/api/contract/">Contract Interaction</a></div><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/api/utils/">Utilities</a></div><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/api/other/">Other Libraries</a></div><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/api/experimental/">Experimental</a></div></div><div class="page-separator"></div><a name="/v5/api/providers/-%23-providers"></a><a name="/v5/api/providers/-%23-providers"></a><a name="/v5/api/providers/"></a><h1 class="show-anchors"><div>Providers<div class="anchors"><a class="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 use the <a href="#/v5/api/providers/-%23-providers-getDefaultProvider">Default Provider</a>.</p>
|
|
|
|
<a name="/v5/api/providers/-%23-providers-getDefaultProvider"></a><a name="/v5/api/providers/-%23-providers--providers-getDefaultProvider"></a><a name="/v5/api/providers/"></a><h2 class="show-anchors"><div>Default Provider<div class="anchors"><a class="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 <a href="#/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 simultaneously. 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>
|
|
|
|
<div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="method">getDefaultProvider</span><span class="symbol">(</span> <span class="symbol">[</span> <span class="param">network</span> <span class="symbol">,</span> <span class="symbol">[</span> <span class="param">options</span> <span class="symbol">]</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/providers/provider/">Provider</a></span><div class="anchors"></div></div><div class="body"><p>Returns a new Provider, backed by multiple services, connected to <i>network</i>. If no <i>network</i> is provided, <b>homestead</b> (i.e. mainnet) is used.</p>
|
|
|
|
<p>The <i>network</i> may also be a URL to connect to, such as <code class="inline">http://localhost:8545</code> or <code class="inline">wss://example.com</code>.</p>
|
|
|
|
<p>The <i>options</i> is an object, with the following properties:</p>
|
|
|
|
</div></div><table class="table minimal"><tr><td align="center"><b>Property</b></td><td align="center"><b>Description</b></td><td class="fix"> </td></tr><tr><td align="center"><i>alchemy</i></td><td align="left"><a href="https://alchemyapi.io">Alchemy</a> API Token</td><td class="fix"> </td></tr><tr><td align="center"><i>etherscan</i></td><td align="left"><a href="https://etherscan.io">Etherscan</a> API Token</td><td class="fix"> </td></tr><tr><td align="center"><i>infura</i></td><td align="left"><a href="https://infura.io">INFURA</a> Project ID or <code class="inline">{ projectId, projectSecret }</code></td><td class="fix"> </td></tr><tr><td align="center"><i>pocket</i></td><td align="left"><a href="https://pokt.network">Pocket Network</a> Application ID or <code class="inline">{ applicationId, applicationSecretKey }</code></td><td class="fix"> </td></tr><tr><td align="center"><i>quorum</i></td><td align="left">The number of backends that must agree <i>(default: 2 for mainnet, 1 for testnets)</i></td><td class="fix"> </td></tr><tr><td class="table-title" colspan="2">Option Properties</td><td class="fix"> </td></tr></table><div class="definition container-box note"><div class="term">Note: API Keys</div><div class="body"><p>It is highly recommended for production services to acquire and specify an API Key for each service.</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>
|
|
|
|
<p>Some services also provide additional paid features, which are only available when specifying an API Key.</p>
|
|
|
|
</div></div><a name="/v5/api/providers/-%23-providers--networks"></a><a name="/v5/api/providers/"></a><h2 class="show-anchors"><div>Networks<div class="anchors"><a class="self" href="#/v5/api/providers/-%23-providers--networks"></a></div></div></h2><p>There are several official common Ethereum networks as well as custom networks and other compatible projects.</p>
|
|
|
|
<p>Any API that accept a <a href="#/v5/api/providers/types/-%23-providers-Networkish">Networkish</a> can be passed a common name (such as <code class="inline">"mainnet"</code> or <code class="inline">"ropsten"</code>) to use that network definition or may specify custom parameters.</p>
|
|
|
|
<a name="/v5/api/providers/-%23-providers--networks--custom-ens-contract"></a><a name="/v5/api/providers/"></a><h3 class="show-anchors"><div>Custom ENS Contract<div class="anchors"><a class="self" href="#/v5/api/providers/-%23-providers--networks--custom-ens-contract"></a></div></div></h3><p>One common reason to specify custom properties for a <a href="#/v5/api/providers/types/-%23-providers-Network">Network</a> is to override the address of the root ENS registry, either on a common network to intercept the <a href="#/v5/api/providers/provider/-%23-Provider--ens-methods">ENS Methods</a> or to specify the ENS registry on a dev network (on most dev networks you must deploy the ENS contracts manually).</p>
|
|
|
|
<div class="code-title"><div>Example: Override the ENS registry</div></div><div class="code">const network = {
|
|
name: "dev",
|
|
chianId: 1337,
|
|
ensAddress: customEnsAddress
|
|
};
|
|
</div><a name="/v5/api/providers/-%23-providers--provider-documentation"></a><a name="/v5/api/providers/"></a><h2 class="show-anchors"><div>Provider Documentation<div class="anchors"><a class="self" href="#/v5/api/providers/-%23-providers--provider-documentation"></a></div></div></h2>
|
|
<div class="toc"><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/api/providers/provider/">Provider</a></div><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/api/providers/jsonrpc-provider/">JsonRpcProvider</a></div><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/api/providers/api-providers/">API Providers</a></div><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/api/providers/other/">Other Providers</a></div><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/api/providers/types/">Types</a></div></div><div class="page-separator"></div><a name="/v5/api/providers/provider/-%23-Provider"></a><a name="/v5/api/providers/provider/-%23-Provider"></a><a name="/v5/api/providers/provider/"></a><h1 class="show-anchors"><div>Provider<div class="anchors"><a class="self" href="#/v5/api/providers/provider/-%23-Provider"></a></div></div></h1><p>A <b>Provider</b> in ethers is a read-only abstraction to access the blockchain data.</p>
|
|
|
|
<div class="definition container-box note"><div class="term">Coming from Web3.js?</div><div class="body"><p>If you are coming from Web3.js, this is one of the biggest differences you will encounter using ethers.</p>
|
|
|
|
<p>The ethers library creates a strong division between the operation a <b>Provider</b> can perform and those of a <a href="#/v5/api/signer/-%23-Signer">Signer</a>, which Web3.js lumps together.</p>
|
|
|
|
<p>This separation of concerns and a stricted subset of Provider operations allows for a larger variety of backends, a more consistent API and ensures other libraries to operate without being able to rely on any underlying assumption.</p>
|
|
|
|
</div></div><a name="/v5/api/providers/provider/-%23-Provider--account-methods"></a><a name="/v5/api/providers/provider/-%23-Provider--Provider--account-methods"></a><a name="/v5/api/providers/provider/"></a><h2 class="show-anchors"><div>Accounts Methods<div class="anchors"><a class="self" href="#/v5/api/providers/provider/-%23-Provider--account-methods"></a></div></div></h2>
|
|
<a name="/v5/api/providers/provider/-%23-Provider-getBalance"></a><div class="property show-anchors"><div class="signature"><span class="path">provider</span><span class="symbol">.</span><span class="method">getBalance</span><span class="symbol">(</span> <span class="param">address</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">blockTag</span> = <span class="param">latest</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< <a href="#/v5/api/utils/bignumber/">BigNumber</a> ></span><div class="anchors"><a class="self" href="#/v5/api/providers/provider/-%23-Provider-getBalance"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/base-provider.ts#L976">source</a></div></div><div class="body"><p>Returns the balance of <i>address</i> as of the <i>blockTag</i> block height.</p>
|
|
|
|
</div></div><a name="/v5/api/providers/provider/-%23-Provider-getCode"></a><div class="property show-anchors"><div class="signature"><span class="path">provider</span><span class="symbol">.</span><span class="method">getCode</span><span class="symbol">(</span> <span class="param">address</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">blockTag</span> = <span class="param">latest</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a> > ></span><div class="anchors"><a class="self" href="#/v5/api/providers/provider/-%23-Provider-getCode"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/base-provider.ts#L994">source</a></div></div><div class="body"><p>Returns the contract code of <i>address</i> as of the <i>blockTag</i> block height. If there is no contract currently deployed, the result is <code class="inline">0x</code>.</p>
|
|
|
|
</div></div><a name="/v5/api/providers/provider/-%23-Provider-getStorageAt"></a><div class="property show-anchors"><div class="signature"><span class="path">provider</span><span class="symbol">.</span><span class="method">getStorageAt</span><span class="symbol">(</span> <span class="param">addr</span> <span class="symbol">,</span> <span class="param">pos</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">blockTag</span> = <span class="param">latest</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a> > ></span><div class="anchors"><a class="self" href="#/v5/api/providers/provider/-%23-Provider-getStorageAt"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/base-provider.ts#L1003">source</a></div></div><div class="body"><p>Returns the <code class="inline">Bytes32</code> value of the position <i>pos</i> at address <i>addr</i>, as of the <i>blockTag</i>.</p>
|
|
|
|
</div></div><a name="/v5/api/providers/provider/-%23-Provider-getTransactionCount"></a><div class="property show-anchors"><div class="signature"><span class="path">provider</span><span class="symbol">.</span><span class="method">getTransactionCount</span><span class="symbol">(</span> <span class="param">address</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">blockTag</span> = <span class="param">latest</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< number ></span><div class="anchors"><a class="self" href="#/v5/api/providers/provider/-%23-Provider-getTransactionCount"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/base-provider.ts#L985">source</a></div></div><div class="body"><p>Returns the number of transactions <i>address</i> has ever <b>sent</b>, as of <i>blockTag</i>. This value is required to be the nonce for the next transaction from <i>address</i> sent to the network.</p>
|
|
|
|
</div></div><div class="code-title"><div>Account Examples</div></div><div class="code"><span class="comment">// Get the balance for an account...
|
|
</span>provider.getBalance("ricmoo.firefly.eth");
|
|
<span class="result ok">// { Promise: { BigNumber: "25334210474552466902" } }
|
|
</span>
|
|
<span class="comment">// Get the code for a contract...
|
|
</span>provider.getCode("registrar.firefly.eth");
|
|
<span class="result ok">// { Promise: '0x606060405236156100885763ffffffff60e060020a60003504166369fe0e2d81146100fa578063704b6c021461010f57806379502c551461012d578063bed866f614610179578063c37067fa1461019e578063c66485b2146101ab578063d80528ae146101c9578063ddca3f43146101f7578063f2c298be14610219578063f3fef3a314610269575b6100f85b6000808052600760209081527f6d5257204ebe7d88fd91ae87941cb2dd9d8062b64ae5a2bd2d28ec40b9fbf6df80543490810190915560408051918252517fdb7750418f9fa390aaf85d881770065aa4adbe46343bcff4ae573754c829d9af929181900390910190a25b565b005b341561010257fe5b6100f860043561028a565b005b341561011757fe5b6100f8600160a060020a03600435166102ec565b005b341561013557fe5b61013d610558565b60408051600160a060020a0396871681526020810195909552928516848401526060840191909152909216608082015290519081900360a00190f35b341561018157fe5b61018c600435610580565b60408051918252519081900360200190f35b6100f8600435610595565b005b34156101b357fe5b6100f8600160a060020a03600435166105e6565b005b34156101d157fe5b6101d9610676565b60408051938452602084019290925282820152519081900360600190f35b34156101ff57fe5b61018c61068d565b60408051918252519081900360200190f35b6100f8600480803590602001908201803590602001908080601f0160208091040260200160405190810160405280939291908181526020018383808284375094965061069495505050505050565b005b341561027157fe5b6100f8600160a060020a0360043516602435610ab2565b005b60025433600160a060020a039081169116146102a65760006000fd5b600454604080519182526020820183905280517f854231545a00e13c316c82155f2b8610d638e9ff6ebc4930676f84a5af08a49a9281900390910190a160048190555b50565b60025433600160a060020a039081169116146103085760006000fd5b60025460408051600160a060020a039283168152918316602083015280517fbadc9a52979e89f78b7c58309537410c5e51d0f63a0a455efe8d61d2b474e6989281900390910190a16002805473ffffffffffffffffffffffffffffffffffffffff1916600160a060020a038381169190911790915560008054604080516020908101849052815160e060020a6302571be30281527f91d1777781884d03a6757a803996e38de2a42967fb37eeaca72729271025a9e26004820152915192909416936302571be39360248084019492938390030190829087803b15156103e957fe5b60325a03f115156103f657fe5b50505060405180519050600160a060020a0316631e83409a826000604051602001526040518263ffffffff1660e060020a0281526004018082600160a060020a0316600160a060020a03168152602001915050602060405180830381600087803b151561045f57fe5b60325a03f1151561046c57fe5b50506040805160008054600354602093840183905284517f0178b8bf00000000000000000000000000000000000000000000000000000000815260048101919091529351600160a060020a039091169450630178b8bf9360248082019493918390030190829087803b15156104dd57fe5b60325a03f115156104ea57fe5b505060408051805160035460025460e860020a62d5fa2b0284526004840191909152600160a060020a03908116602484015292519216925063d5fa2b0091604480830192600092919082900301818387803b151561054457fe5b60325a03f1151561055157fe5b5050505b50565b600054600354600254600454600154600160a060020a039485169492831692165b9091929394565b6000818152600760205260409020545b919050565b6000818152600760209081526040918290208054349081019091558251908152915183927fdb7750418f9fa390aaf85d881770065aa4adbe46343bcff4ae573754c829d9af92908290030190a25b50565b60025433600160a060020a039081169116146106025760006000fd5b60015460408051600160a060020a039283168152918316602083015280517f279875333405c968e401e3bc4e71d5f8e48728c90f4e8180ce28f74efb5669209281900390910190a16001805473ffffffffffffffffffffffffffffffffffffffff1916600160a060020a0383161790555b50565b600654600554600160a060020a033016315b909192565b6004545b90565b80516001820190600080808060048510806106af5750601485115b156106ba5760006000fd5b600093505b8484101561072a57855160ff16925060618310806106e05750607a8360ff16115b80156106fc575060308360ff1610806106fc575060398360ff16115b5b801561070d57508260ff16602d14155b156107185760006000fd5b6001909501945b6001909301926106bf565b60045434101561073a5760006000fd5b866040518082805190602001908083835b6020831061076a5780518252601f19909201916020918201910161074b565b51815160209384036101000a60001901801990921691161790526040805192909401829003822060035483528282018190528451928390038501832060008054948401819052865160e060020a6302571be3028152600481018390529651929a509098509650600160a060020a0390921694506302571be393602480820194509192919082900301818787803b15156107ff57fe5b60325a03f1151561080c57fe5b505060405151600160a060020a031691909114905061082b5760006000fd5b60008054600354604080517f06ab5923000000000000000000000000000000000000000000000000000000008152600481019290925260248201869052600160a060020a03308116604484015290519216926306ab59239260648084019382900301818387803b151561089a57fe5b60325a03f115156108a757fe5b505060008054600154604080517f1896f70a00000000000000000000000000000000000000000000000000000000815260048101879052600160a060020a0392831660248201529051919092169350631896f70a9260448084019391929182900301818387803b151561091657fe5b60325a03f1151561092357fe5b50506001546040805160e860020a62d5fa2b02815260048101859052600160a060020a033381166024830152915191909216925063d5fa2b009160448082019260009290919082900301818387803b151561097a57fe5b60325a03f1151561098757fe5b505060008054604080517f5b0fc9c300000000000000000000000000000000000000000000000000000000815260048101869052600160a060020a0333811660248301529151919092169350635b0fc9c39260448084019391929182900301818387803b15156109f357fe5b60325a03f11515610a0057fe5b505060058054349081019091556006805460010190556000838152600760209081526040918290208054840190558151600160a060020a03331681529081019290925280518493507f179ef3319e6587f6efd3157b34c8b357141528074bcb03f9903589876168fa149281900390910190a260408051348152905182917fdb7750418f9fa390aaf85d881770065aa4adbe46343bcff4ae573754c829d9af919081900360200190a25b50505050505050565b60025433600160a060020a03908116911614610ace5760006000fd5b604051600160a060020a0383169082156108fc029083906000818181858888f193505050501515610aff5760006000fd5b60408051600160a060020a03841681526020810183905281517fac375770417e1cb46c89436efcf586a74d0298fee9838f66a38d40c65959ffda929181900390910190a15b50505600a165627a7a723058205c3628c01dc80233f51979d91a76cec2a25d84e86c9838d34672734ca2232b640029' }
|
|
</span>
|
|
<span class="comment">// Get the storage value at position 0...
|
|
</span>provider.getStorageAt("registrar.firefly.eth", 0)
|
|
<span class="result ok">// { Promise: '0x000000000000000000000000314159265dd8dbb310642f98f50c066173c1259b' }
|
|
</span>
|
|
<span class="comment">// Get transaction count of an account...
|
|
</span>provider.getTransactionCount("ricmoo.firefly.eth");
|
|
<span class="result ok">// { Promise: 712 }
|
|
</span></div><a name="/v5/api/providers/provider/-%23-Provider--block-methods"></a><a name="/v5/api/providers/provider/-%23-Provider--Provider--block-methods"></a><a name="/v5/api/providers/provider/"></a><h2 class="show-anchors"><div>Blocks Methods<div class="anchors"><a class="self" href="#/v5/api/providers/provider/-%23-Provider--block-methods"></a></div></div></h2>
|
|
<a name="/v5/api/providers/provider/-%23-Provider-getBlock"></a><div class="property show-anchors"><div class="signature"><span class="path">provider</span><span class="symbol">.</span><span class="method">getBlock</span><span class="symbol">(</span> <span class="param">block</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< <a href="#/v5/api/providers/types/-%23-providers-Block">Block</a> ></span><div class="anchors"><a class="self" href="#/v5/api/providers/provider/-%23-Provider-getBlock"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/base-provider.ts#L1212">source</a></div></div><div class="body"><p>Get the <i>block</i> from the network, where the <code class="inline">result.transactions</code> is a list of transaction hashes.</p>
|
|
|
|
</div></div><a name="/v5/api/providers/provider/-%23-Provider-getBlockWithTransactions"></a><div class="property show-anchors"><div class="signature"><span class="path">provider</span><span class="symbol">.</span><span class="method">getBlockWithTransactions</span><span class="symbol">(</span> <span class="param">block</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< <a href="#/v5/api/providers/types/-%23-providers-BlockWithTransactions">BlockWithTransactions</a> ></span><div class="anchors"><a class="self" href="#/v5/api/providers/provider/-%23-Provider-getBlockWithTransactions"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/base-provider.ts#L1216">source</a></div></div><div class="body"><p>Get the <i>block</i> from the network, where the <code class="inline">result.transactions</code> is an Array of <a href="#/v5/api/providers/types/-%23-providers-TransactionResponse">TransactionResponse</a> objects.</p>
|
|
|
|
</div></div><div class="code-title"><div>Block Examples</div></div><div class="code">provider.getBlock(100004)
|
|
<span class="result ok">// { Promise: {
|
|
</span><span class="result ok">// difficulty: 3849295379889,
|
|
</span><span class="result ok">// extraData: '0x476574682f76312e302e312d39383130306634372f6c696e75782f676f312e34',
|
|
</span><span class="result ok">// gasLimit: { BigNumber: "3141592" },
|
|
</span><span class="result ok">// gasUsed: { BigNumber: "21000" },
|
|
</span><span class="result ok">// hash: '0xf93283571ae16dcecbe1816adc126954a739350cd1523a1559eabeae155fbb63',
|
|
</span><span class="result ok">// miner: '0x909755D480A27911cB7EeeB5edB918fae50883c0',
|
|
</span><span class="result ok">// nonce: '0x1a455280001cc3f8',
|
|
</span><span class="result ok">// number: 100004,
|
|
</span><span class="result ok">// parentHash: '0x73d88d376f6b4d232d70dc950d9515fad3b5aa241937e362fdbfd74d1c901781',
|
|
</span><span class="result ok">// timestamp: 1439799168,
|
|
</span><span class="result ok">// transactions: [
|
|
</span><span class="result ok">// '0x6f12399cc2cb42bed5b267899b08a847552e8c42a64f5eb128c1bcbd1974fb0c'
|
|
</span><span class="result ok">// ]
|
|
</span><span class="result ok">// } }
|
|
</span>
|
|
provider.getBlockWithTransactions(100004)
|
|
<span class="result ok">// { Promise: {
|
|
</span><span class="result ok">// difficulty: 3849295379889,
|
|
</span><span class="result ok">// extraData: '0x476574682f76312e302e312d39383130306634372f6c696e75782f676f312e34',
|
|
</span><span class="result ok">// gasLimit: { BigNumber: "3141592" },
|
|
</span><span class="result ok">// gasUsed: { BigNumber: "21000" },
|
|
</span><span class="result ok">// hash: '0xf93283571ae16dcecbe1816adc126954a739350cd1523a1559eabeae155fbb63',
|
|
</span><span class="result ok">// miner: '0x909755D480A27911cB7EeeB5edB918fae50883c0',
|
|
</span><span class="result ok">// nonce: '0x1a455280001cc3f8',
|
|
</span><span class="result ok">// number: 100004,
|
|
</span><span class="result ok">// parentHash: '0x73d88d376f6b4d232d70dc950d9515fad3b5aa241937e362fdbfd74d1c901781',
|
|
</span><span class="result ok">// timestamp: 1439799168,
|
|
</span><span class="result ok">// transactions: [
|
|
</span><span class="result ok">// {
|
|
</span><span class="result ok">// blockHash: '0xf93283571ae16dcecbe1816adc126954a739350cd1523a1559eabeae155fbb63',
|
|
</span><span class="result ok">// blockNumber: 100004,
|
|
</span><span class="result ok">// chainId: 0,
|
|
</span><span class="result ok">// confirmations: 11717911,
|
|
</span><span class="result ok">// creates: null,
|
|
</span><span class="result ok">// data: '0x',
|
|
</span><span class="result ok">// from: '0xcf00A85f3826941e7A25BFcF9Aac575d40410852',
|
|
</span><span class="result ok">// gasLimit: { BigNumber: "90000" },
|
|
</span><span class="result ok">// gasPrice: { BigNumber: "54588778004" },
|
|
</span><span class="result ok">// hash: '0x6f12399cc2cb42bed5b267899b08a847552e8c42a64f5eb128c1bcbd1974fb0c',
|
|
</span><span class="result ok">// nonce: 25,
|
|
</span><span class="result ok">// r: '0xb23adc880d3735e4389698dddc953fb02f1fa9b57e84d3510a2a4b3597ac2486',
|
|
</span><span class="result ok">// s: '0x4e856f95c4e2828933246fb4765a5bfd2ca5959840643bef0e80b4e3a243d064',
|
|
</span><span class="result ok">// to: '0xD9666150A9dA92d9108198a4072970805a8B3428',
|
|
</span><span class="result ok">// transactionIndex: 0,
|
|
</span><span class="result ok">// v: 27,
|
|
</span><span class="result ok">// value: { BigNumber: "5000000000000000000" }
|
|
</span><span class="result ok">// }
|
|
</span><span class="result ok">// ]
|
|
</span><span class="result ok">// } }
|
|
</span></div><a name="/v5/api/providers/provider/-%23-Provider--ens-methods"></a><a name="/v5/api/providers/provider/-%23-Provider--Provider--ens-methods"></a><a name="/v5/api/providers/provider/"></a><h2 class="show-anchors"><div>Ethereum Naming Service (ENS) Methods<div class="anchors"><a class="self" href="#/v5/api/providers/provider/-%23-Provider--ens-methods"></a></div></div></h2><p>The <a href="https://ens.domains/">Ethereum Naming Service</a> (ENS) allows a short and easy-to-remember ENS Name to be 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 <a href="#/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>
|
|
|
|
<div class="property show-anchors"><div class="signature"><span class="path">provider</span><span class="symbol">.</span><span class="method">getResolver</span><span class="symbol">(</span> <span class="param">name</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< <a href="#/v5/api/providers/provider/-%23-EnsResolver">EnsResolver</a> ></span><div class="anchors"></div></div><div class="body"><p>Returns an EnsResolver instance which can be used to further inquire about specific entries for an ENS name.</p>
|
|
|
|
</div></div><a name="/v5/api/providers/provider/-%23-Provider-lookupAddress"></a><div class="property show-anchors"><div class="signature"><span class="path">provider</span><span class="symbol">.</span><span class="method">lookupAddress</span><span class="symbol">(</span> <span class="param">address</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< string ></span><div class="anchors"><a class="self" href="#/v5/api/providers/provider/-%23-Provider-lookupAddress"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/base-provider.ts#L1375">source</a></div></div><div class="body"><p>Performs a reverse lookup of the <i>address</i> in ENS using the <i>Reverse Registrar</i>. If the name does not exist, or the forward lookup does not match, <code class="inline">null</code> is returned.</p>
|
|
|
|
</div></div><a name="/v5/api/providers/provider/-%23-Provider-ResolveName"></a><div class="property show-anchors"><div class="signature"><span class="path">provider</span><span class="symbol">.</span><span class="method">resolveName</span><span class="symbol">(</span> <span class="param">name</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< string< <a href="#/v5/api/utils/address/-%23-address">Address</a> > ></span><div class="anchors"><a class="self" href="#/v5/api/providers/provider/-%23-Provider-ResolveName"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/base-provider.ts#L1353">source</a></div></div><div class="body"><p>Looks up the address of <i>name</i>. If the name is not owned, or does not have a <i>Resolver</i> configured, or the <i>Resolver</i> does not have an address configured, <code class="inline">null</code> is returned.</p>
|
|
|
|
</div></div><div class="code-title"><div>ENS Examples</div></div><div class="code"><span class="comment">// Reverse lookup of an ENS by address...
|
|
</span>provider.lookupAddress("0x6fC21092DA55B392b045eD78F4732bff3C580e2c");
|
|
<span class="result ok">// { Promise: 'registrar.firefly.eth' }
|
|
</span>
|
|
<span class="comment">// Lookup an address of an ENS name...
|
|
</span>provider.resolveName("ricmoo.firefly.eth");
|
|
<span class="result ok">// { Promise: '0x8ba1f109551bD432803012645Ac136ddd64DBA72' }
|
|
</span></div><a name="/v5/api/providers/provider/-%23-EnsResolver"></a><a name="/v5/api/providers/provider/-%23-Provider--EnsResolver"></a><a name="/v5/api/providers/provider/"></a><h2 class="show-anchors"><div>EnsResolver<div class="anchors"><a class="self" href="#/v5/api/providers/provider/-%23-EnsResolver"></a></div></div></h2>
|
|
<div class="property show-anchors"><div class="signature"><span class="path">resolver</span><span class="symbol">.</span><span class="method">name</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"></div></div><div class="body"><p>The name of this resolver.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">resolver</span><span class="symbol">.</span><span class="method">address</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/address/-%23-address">Address</a> ></span><div class="anchors"></div></div><div class="body"><p>The address of the Resolver.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">resolver</span><span class="symbol">.</span><span class="method">getAddress</span><span class="symbol">(</span> <span class="symbol">[</span> <span class="param">cointType</span> = <span class="param">60</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< string ></span><div class="anchors"></div></div><div class="body"><p>Returns a Promise which resolves to the <a href="https://eips.ethereum.org/EIPS/eip-2304">EIP-2304</a> multicoin address stored for the <i>coinType</i>. By default an Ethereum <a href="#/v5/api/utils/address/-%23-address">Address</a> (<code class="inline">coinType = 60</code>) will be returned.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">resolver</span><span class="symbol">.</span><span class="method">getContentHash</span><span class="symbol">(</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< string ></span><div class="anchors"></div></div><div class="body"><p>Returns a Promise which resolves to any stored <a href="https://eips.ethereum.org/EIPS/eip-1577">EIP-1577</a> content hash.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">resolver</span><span class="symbol">.</span><span class="method">getText</span><span class="symbol">(</span> <span class="param">key</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< string ></span><div class="anchors"></div></div><div class="body"><p>Returns a Promise which resolves to any stored <a href="https://eips.ethereum.org/EIPS/eip-634">EIP-634</a> text entry for <i>key</i>.</p>
|
|
|
|
</div></div><a name="/v5/api/providers/provider/-%23-Provider--log-methods"></a><a name="/v5/api/providers/provider/-%23-Provider--Provider--log-methods"></a><a name="/v5/api/providers/provider/"></a><h2 class="show-anchors"><div>Logs Methods<div class="anchors"><a class="self" href="#/v5/api/providers/provider/-%23-Provider--log-methods"></a></div></div></h2>
|
|
<a name="/v5/api/providers/provider/-%23-Provider-getLogs"></a><div class="property show-anchors"><div class="signature"><span class="path">provider</span><span class="symbol">.</span><span class="method">getLogs</span><span class="symbol">(</span> <span class="param">filter</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< Array< <a href="#/v5/api/providers/types/-%23-providers-Log">Log</a> > ></span><div class="anchors"><a class="self" href="#/v5/api/providers/provider/-%23-Provider-getLogs"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/base-provider.ts#L1292">source</a></div></div><div class="body"><p>Returns the Array of <a href="#/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><a name="/v5/api/providers/provider/-%23-Provider--network-methods"></a><a name="/v5/api/providers/provider/-%23-Provider--Provider--network-methods"></a><a name="/v5/api/providers/provider/"></a><h2 class="show-anchors"><div>Network Status Methods<div class="anchors"><a class="self" href="#/v5/api/providers/provider/-%23-Provider--network-methods"></a></div></div></h2>
|
|
<a name="/v5/api/providers/provider/-%23-Provider-getNetwork"></a><div class="property show-anchors"><div class="signature"><span class="path">provider</span><span class="symbol">.</span><span class="method">getNetwork</span><span class="symbol">(</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< <a href="#/v5/api/providers/types/-%23-providers-Network">Network</a> ></span><div class="anchors"><a class="self" href="#/v5/api/providers/provider/-%23-Provider-getNetwork"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/base-provider.ts#L796">source</a></div></div><div class="body"><p>Returns the <a href="#/v5/api/providers/types/-%23-providers-Network">Network</a> this Provider is connected to.</p>
|
|
|
|
</div></div><a name="/v5/api/providers/provider/-%23-Provider-getBlockNumber"></a><div class="property show-anchors"><div class="signature"><span class="path">provider</span><span class="symbol">.</span><span class="method">getBlockNumber</span><span class="symbol">(</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< number ></span><div class="anchors"><a class="self" href="#/v5/api/providers/provider/-%23-Provider-getBlockNumber"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/base-provider.ts#L967">source</a></div></div><div class="body"><p>Returns the block number (or height) of the most recently mined block.</p>
|
|
|
|
</div></div><a name="/v5/api/providers/provider/-%23-Provider-getGasPrice"></a><div class="property show-anchors"><div class="signature"><span class="path">provider</span><span class="symbol">.</span><span class="method">getGasPrice</span><span class="symbol">(</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< <a href="#/v5/api/utils/bignumber/">BigNumber</a> ></span><div class="anchors"><a class="self" href="#/v5/api/providers/provider/-%23-Provider-getGasPrice"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/base-provider.ts#L971">source</a></div></div><div class="body"><p>Returns a <i>best guess</i> of the <a href="#/v5/concepts/gas/-%23-gas-price">Gas Price</a> to use in a transaction.</p>
|
|
|
|
</div></div><a name="/v5/api/providers/provider/-%23-Provider-ready"></a><div class="property show-anchors"><div class="signature"><span class="path">provider</span><span class="symbol">.</span><span class="method">ready</span> <span class="arrow">⇒</span> <span class="returns">Promise< <a href="#/v5/api/providers/types/-%23-providers-Network">Network</a> ></span><div class="anchors"><a class="self" href="#/v5/api/providers/provider/-%23-Provider-ready"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/base-provider.ts#L556">source</a></div></div><div class="body"><p>Returns a Promise which will stall until the network has heen established, ignoring errors due to the target node not being active yet.</p>
|
|
|
|
<p>This can be used for testing or attaching scripts to wait until the node is up and running smoothly.</p>
|
|
|
|
</div></div><div class="code-title"><div>Network Status Examples</div></div><div class="code"><span class="comment">// The network information
|
|
</span>provider.getNetwork()
|
|
<span class="result ok">// {
|
|
</span><span class="result ok">// chainId: 1,
|
|
</span><span class="result ok">// ensAddress: '0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e',
|
|
</span><span class="result ok">// name: 'homestead'
|
|
</span><span class="result ok">// }
|
|
</span>
|
|
<span class="comment">// The current block number
|
|
</span>provider.getBlockNumber()
|
|
<span class="result ok">// { Promise: 11817914 }
|
|
</span>
|
|
<span class="comment">// Get the current suggested gas price (in wei)...
|
|
</span>gasPrice = await provider.getGasPrice()
|
|
<span class="result ok">// { BigNumber: "207000000000" }
|
|
</span>
|
|
<span class="comment">// ...often this gas price is easier to understand or
|
|
</span><span class="comment">// display to the user in gwei (giga-wei, or 1e9 wei)
|
|
</span>utils.formatUnits(gasPrice, "gwei")
|
|
<span class="result ok">// '207.0'
|
|
</span></div><a name="/v5/api/providers/provider/-%23-Provider--transaction-methods"></a><a name="/v5/api/providers/provider/-%23-Provider--Provider--transaction-methods"></a><a name="/v5/api/providers/provider/"></a><h2 class="show-anchors"><div>Transactions Methods<div class="anchors"><a class="self" href="#/v5/api/providers/provider/-%23-Provider--transaction-methods"></a></div></div></h2>
|
|
<a name="/v5/api/providers/provider/-%23-Provider-call"></a><div class="property show-anchors"><div class="signature"><span class="path">provider</span><span class="symbol">.</span><span class="method">call</span><span class="symbol">(</span> <span class="param">transaction</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">blockTag</span> = <span class="param">latest</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a> > ></span><div class="anchors"><a class="self" href="#/v5/api/providers/provider/-%23-Provider-call"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/base-provider.ts#L1112">source</a></div></div><div class="body"><p>Returns the result of executing the <i>transaction</i>, using <i>call</i>. A call does not require any ether, but cannot change any state. This is useful for calling getters on Contracts.</p>
|
|
|
|
</div></div><a name="/v5/api/providers/provider/-%23-Provider-estimateGas"></a><div class="property show-anchors"><div class="signature"><span class="path">provider</span><span class="symbol">.</span><span class="method">estimateGas</span><span class="symbol">(</span> <span class="param">transaction</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< <a href="#/v5/api/utils/bignumber/">BigNumber</a> ></span><div class="anchors"><a class="self" href="#/v5/api/providers/provider/-%23-Provider-estimateGas"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/base-provider.ts#L1121">source</a></div></div><div class="body"><p>Returns an estimate of the amount of gas that would be required to submit <i>transaction</i> to the network.</p>
|
|
|
|
<p>An estimate may not be accurate since there could be another transaction on the network that was not accounted for, but after being mined affected relevant state.</p>
|
|
|
|
</div></div><a name="/v5/api/providers/provider/-%23-Provider-getTransaction"></a><div class="property show-anchors"><div class="signature"><span class="path">provider</span><span class="symbol">.</span><span class="method">getTransaction</span><span class="symbol">(</span> <span class="param">hash</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< <a href="#/v5/api/providers/types/-%23-providers-TransactionResponse">TransactionResponse</a> ></span><div class="anchors"><a class="self" href="#/v5/api/providers/provider/-%23-Provider-getTransaction"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/base-provider.ts#L1220">source</a></div></div><div class="body"><p>Returns the transaction with <i>hash</i> or null if the transaction is unknown.</p>
|
|
|
|
<p>If a transaction has not been mined, this method will search the transaction pool. Various backends may have more restrictive transaction pool access (e.g. if the gas price is too low or the transaction was only recently sent and not yet indexed) in which case this method may also return null.</p>
|
|
|
|
</div></div><a name="/v5/api/providers/provider/-%23-Provider-getTransactionReceipt"></a><div class="property show-anchors"><div class="signature"><span class="path">provider</span><span class="symbol">.</span><span class="method">getTransactionReceipt</span><span class="symbol">(</span> <span class="param">hash</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< <a href="#/v5/api/providers/types/-%23-providers-TransactionReceipt">TransactionReceipt</a> ></span><div class="anchors"><a class="self" href="#/v5/api/providers/provider/-%23-Provider-getTransactionReceipt"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/base-provider.ts#L1254">source</a></div></div><div class="body"><p>Returns the transaction receipt for <i>hash</i> or null if the transaction has not been mined.</p>
|
|
|
|
<p>To stall until the transaction has been mined, consider the <code class="inline">waitForTransaction</code> method below.</p>
|
|
|
|
</div></div><a name="/v5/api/providers/provider/-%23-Provider-sendTransaction"></a><div class="property show-anchors"><div class="signature"><span class="path">provider</span><span class="symbol">.</span><span class="method">sendTransaction</span><span class="symbol">(</span> <span class="param">transaction</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< <a href="#/v5/api/providers/types/-%23-providers-TransactionResponse">TransactionResponse</a> ></span><div class="anchors"><a class="self" href="#/v5/api/providers/provider/-%23-Provider-sendTransaction"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/base-provider.ts#L1053">source</a></div></div><div class="body"><p>Submits <i>transaction</i> to the network to be mined. The <i>transaction</i> <b>must</b> be signed, and be valid (i.e. the nonce is correct and the account has sufficient balance to pay for the transaction).</p>
|
|
|
|
</div></div><a name="/v5/api/providers/provider/-%23-Provider-waitForTransaction"></a><div class="property show-anchors"><div class="signature"><span class="path">provider</span><span class="symbol">.</span><span class="method">waitForTransaction</span><span class="symbol">(</span> <span class="param">hash</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">confirms</span> = <span class="param">1</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">timeout</span> <span class="symbol">]</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< <a href="#/v5/api/providers/types/-%23-providers-TransactionReceipt">TxReceipt</a> ></span><div class="anchors"><a class="self" href="#/v5/api/providers/provider/-%23-Provider-waitForTransaction"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/base-provider.ts#L928">source</a></div></div><div class="body"><p>Returns a Promise which will not resolve until <i>transactionHash</i> is mined.</p>
|
|
|
|
<p>If <i>confirms</i> is 0, this method is non-blocking and if the transaction has not been mined returns null. Otherwise, this method will block until the transaction has <i>confirms</i> blocks mined on top of the block in which is was mined.</p>
|
|
|
|
</div></div><a name="/v5/api/providers/provider/-%23-Provider--event-methods"></a><a name="/v5/api/providers/provider/-%23-Provider--Provider--event-methods"></a><a name="/v5/api/providers/provider/"></a><h2 class="show-anchors"><div>Event Emitter Methods<div class="anchors"><a class="self" href="#/v5/api/providers/provider/-%23-Provider--event-methods"></a></div></div></h2><p>The EventEmitter API allows applications to use an <a href="https://en.wikipedia.org/wiki/Observer_pattern">Obeserver Pattern</a> to register callbacks for when various events occur.</p>
|
|
|
|
<p>This closely follows the Event Emitter provided by other JavaScript libraries with the exception that event names support some more <a href="#/v5/api/providers/provider/-%23-Provider--events">complex objects</a>, not only strings. The objects are normalized internally.</p>
|
|
|
|
<a name="/v5/api/providers/provider/-%23-Provider-on"></a><div class="property show-anchors"><div class="signature"><span class="path">provider</span><span class="symbol">.</span><span class="method">on</span><span class="symbol">(</span> <span class="param">eventName</span> <span class="symbol">,</span> <span class="param">listener</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">this</span><div class="anchors"><a class="self" href="#/v5/api/providers/provider/-%23-Provider-on"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/base-provider.ts#L1433">source</a></div></div><div class="body"><p>Add a <i>listener</i> to be triggered for each <i>eventName</i> <a href="#/v5/api/providers/provider/-%23-Provider--events">event</a>.</p>
|
|
|
|
</div></div><a name="/v5/api/providers/provider/-%23-Provider-once"></a><div class="property show-anchors"><div class="signature"><span class="path">provider</span><span class="symbol">.</span><span class="method">once</span><span class="symbol">(</span> <span class="param">eventName</span> <span class="symbol">,</span> <span class="param">listener</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">this</span><div class="anchors"><a class="self" href="#/v5/api/providers/provider/-%23-Provider-once"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/base-provider.ts#L1437">source</a></div></div><div class="body"><p>Add a <i>listener</i> to be triggered for only the next <i>eventName</i> <a href="#/v5/api/providers/provider/-%23-Provider--events">event</a>, at which time it will be removed.</p>
|
|
|
|
</div></div><a name="/v5/api/providers/provider/-%23-Provider-emit"></a><div class="property show-anchors"><div class="signature"><span class="path">provider</span><span class="symbol">.</span><span class="method">emit</span><span class="symbol">(</span> <span class="param">eventName</span> <span class="symbol">,</span> ...<span class="param">args</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">boolean</span><div class="anchors"><a class="self" href="#/v5/api/providers/provider/-%23-Provider-emit"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/base-provider.ts#L1442">source</a></div></div><div class="body"><p>Notify all listeners of the <i>eventName</i> <a href="#/v5/api/providers/provider/-%23-Provider--events">event</a>, passing <i>args</i> to each listener. This is generally only used internally.</p>
|
|
|
|
</div></div><a name="/v5/api/providers/provider/-%23-Provider-off"></a><div class="property show-anchors"><div class="signature"><span class="path">provider</span><span class="symbol">.</span><span class="method">off</span><span class="symbol">(</span> <span class="param">eventName</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">listener</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">this</span><div class="anchors"><a class="self" href="#/v5/api/providers/provider/-%23-Provider-off"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/base-provider.ts#L1490">source</a></div></div><div class="body"><p>Remove a <i>listener</i> for the <i>eventName</i> <a href="#/v5/api/providers/provider/-%23-Provider--events">event</a>. If no <i>listener</i> is provided, all listeners for <i>eventName</i> are removed.</p>
|
|
|
|
</div></div><a name="/v5/api/providers/provider/-%23-Provider-removeAllListeners"></a><div class="property show-anchors"><div class="signature"><span class="path">provider</span><span class="symbol">.</span><span class="method">removeAllListeners</span><span class="symbol">(</span> <span class="symbol">[</span> <span class="param">eventName</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">this</span><div class="anchors"><a class="self" href="#/v5/api/providers/provider/-%23-Provider-removeAllListeners"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/base-provider.ts#L1513">source</a></div></div><div class="body"><p>Remove all the listeners for the <i>eventName</i> <a href="#/v5/api/providers/provider/-%23-Provider--events">events</a>. If no <i>eventName</i> is provided, <b>all</b> events are removed.</p>
|
|
|
|
</div></div><a name="/v5/api/providers/provider/-%23-Provider-listenerCount"></a><div class="property show-anchors"><div class="signature"><span class="path">provider</span><span class="symbol">.</span><span class="method">listenerCount</span><span class="symbol">(</span> <span class="symbol">[</span> <span class="param">eventName</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">number</span><div class="anchors"><a class="self" href="#/v5/api/providers/provider/-%23-Provider-listenerCount"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/base-provider.ts#L1470">source</a></div></div><div class="body"><p>Returns the number of listeners for the <i>eventName</i> <a href="#/v5/api/providers/provider/-%23-Provider--events">events</a>. If no <i>eventName</i> is provided, the total number of listeners is returned.</p>
|
|
|
|
</div></div><a name="/v5/api/providers/provider/-%23-Provider-listeners"></a><div class="property show-anchors"><div class="signature"><span class="path">provider</span><span class="symbol">.</span><span class="method">listeners</span><span class="symbol">(</span> <span class="param">eventName</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Array< Listener ></span><div class="anchors"><a class="self" href="#/v5/api/providers/provider/-%23-Provider-listeners"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/base-provider.ts#L1479">source</a></div></div><div class="body"><p>Returns the list of Listeners for the <i>eventName</i> <a href="#/v5/api/providers/provider/-%23-Provider--events">events</a>.</p>
|
|
|
|
</div></div><a name="/v5/api/providers/provider/-%23-Provider--events"></a><a name="/v5/api/providers/provider/-%23-Provider--Provider--event-methods--Provider--events"></a><a name="/v5/api/providers/provider/"></a><h3 class="show-anchors"><div>Events<div class="anchors"><a class="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>
|
|
|
|
<div class="definition"><div class="term"><b>Log Filter</b></div><div class="body"><p>A filter is an object, representing a contract log Filter, which has the optional properties <code class="inline">address</code> (the source contract) and <code class="inline">topics</code> (a topic-set to match).</p>
|
|
|
|
<p>If <code class="inline">address</code> is unspecified, the filter matches any contract address.</p>
|
|
|
|
<p>See <a href="#/v5/api/providers/types/-%23-providers-EventFilter">EventFilters</a> for more information on filtering events.</p>
|
|
|
|
</div></div><div class="definition"><div class="term"><b>Topic-Set Filter</b></div><div class="body"><p>The value of a <b>Topic-Set Filter</b> is a array of Topic-Sets.</p>
|
|
|
|
<p>This event is identical to a <i>Log Filter</i> with the address omitted (i.e. from any contract).</p>
|
|
|
|
<p>See <a href="#/v5/api/providers/types/-%23-providers-EventFilter">EventFilters</a> for more information on filtering events.</p>
|
|
|
|
</div></div><div class="definition"><div class="term"><b>Transaction Filter</b></div><div class="body"><p>The value of a <b>Transaction Filter</b> is any transaction hash.</p>
|
|
|
|
<p>This event is emitted on every block that is part of a chain that includes the given mined transaction. It is much more common that the <a href="#/v5/api/providers/provider/-%23-Provider-once">once</a> method is used than the <a href="#/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>
|
|
|
|
<table class="table full"><tr><td align="center" width="16%"><b>Event Name</b></td><td align="center" colspan="2" width="28%"><b>Arguments</b></td><td align="center" colspan="4" width="56%"><b>Description</b></td><td class="fix"> </td></tr><tr><td align="center" width="16%"><code class="inline">"block"</code></td><td align="center" colspan="2" width="28%"><i>blockNumber</i></td><td align="left" colspan="4" width="56%">emitted when a new block is mined</td><td class="fix"> </td></tr><tr><td align="center" width="16%"><code class="inline">"error"</code></td><td align="center" colspan="2" width="28%"><i>error</i></td><td align="left" colspan="4" width="56%">emitted on any error</td><td class="fix"> </td></tr><tr><td align="center" width="16%"><code class="inline">"pending"</code></td><td align="center" colspan="2" width="28%"><i>pendingTransaction</i></td><td align="left" colspan="4" width="56%">emitted when a new transaction enters the memory pool; only certain providers offer this event and may require running your own node for reliable results</td><td class="fix"> </td></tr><tr><td align="center" width="16%"><code class="inline">"willPoll"</code></td><td align="center" colspan="2" width="28%"><i>pollId</i></td><td align="left" colspan="4" width="56%">emitted prior to a polling loop is about to begin; <i>(very rarely used by most developers)</i></td><td class="fix"> </td></tr><tr><td align="center" width="16%"><code class="inline">"poll"</code></td><td align="center" colspan="2" width="28%"><i>pollId</i>, <i>blockNumber</i></td><td align="left" colspan="4" width="56%">emitted during each poll cycle after `blockNumber` is updated (if changed) and before any other events (if any) are emitted during the poll loop; <i>(very rarely used by most developers)</i></td><td class="fix"> </td></tr><tr><td align="center" width="16%"><code class="inline">"didPoll"</code></td><td align="center" colspan="2" width="28%"><i>pollId</i></td><td align="left" colspan="4" width="56%">emitted after all events from a polling loop are emitted; <i>(very rarely used by most developers)</i></td><td class="fix"> </td></tr><tr><td align="center" width="16%"><code class="inline">"debug"</code></td><td align="center" colspan="2" width="28%">provider dependent</td><td align="left" colspan="4" width="56%">each Provider may use this to emit useful debugging information and the format is up to the developer; <i>(very rarely used by most developers)</i></td><td class="fix"> </td></tr><tr><td class="table-title" colspan="7">Named Provider Events</td><td class="fix"> </td></tr></table><div class="code-title"><div>Events Example</div></div><div class="code">provider.on("block", (blockNumber) => {
|
|
<span class="comment"> // Emitted on every block change
|
|
</span>})
|
|
|
|
|
|
provider.once(txHash, (transaction) => {
|
|
<span class="comment"> // Emitted when the transaction has been mined
|
|
</span>})
|
|
|
|
|
|
<span class="comment">// This filter could also be generated with the Contract or
|
|
</span><span class="comment">// Interface API. If address is not specified, any address
|
|
</span><span class="comment">// matches and if topics is not specified, any log matches
|
|
</span>filter = {
|
|
address: "dai.tokens.ethers.eth",
|
|
topics: [
|
|
utils.id("Transfer(address,address,uint256)")
|
|
]
|
|
}
|
|
provider.on(filter, (log, event) => {
|
|
<span class="comment"> // Emitted whenever a DAI token transfer occurs
|
|
</span>})
|
|
|
|
|
|
<span class="comment">// Notice this is an array of topic-sets and is identical to
|
|
</span><span class="comment">// using a filter with no address (i.e. match any address)
|
|
</span>topicSets = [
|
|
utils.id("Transfer(address,address,uint256)"),
|
|
null,
|
|
[
|
|
myAddress,
|
|
myOtherAddress
|
|
]
|
|
]
|
|
provider.on(topicSets, (log, event) => {
|
|
<span class="comment"> // Emitted any token is sent TO either address
|
|
</span>})
|
|
|
|
|
|
provider.on("pending", (tx) => {
|
|
<span class="comment"> // Emitted when any new pending transaction is noticed
|
|
</span>});
|
|
|
|
|
|
provider.on("error", (tx) => {
|
|
<span class="comment"> // Emitted when any error occurs
|
|
</span>});
|
|
</div><a name="/v5/api/providers/provider/-%23-Provider--inspection-methods"></a><a name="/v5/api/providers/provider/-%23-Provider--Provider--inspection-methods"></a><a name="/v5/api/providers/provider/"></a><h2 class="show-anchors"><div>Inspection Methods<div class="anchors"><a class="self" href="#/v5/api/providers/provider/-%23-Provider--inspection-methods"></a></div></div></h2>
|
|
<a name="/v5/api/providers/provider/-%23-Provider-isProvider"></a><div class="property show-anchors"><div class="signature"><span class="path">Provider</span><span class="symbol">.</span><span class="method">isProvider</span><span class="symbol">(</span> <span class="param">object</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">boolean</span><div class="anchors"><a class="self" href="#/v5/api/providers/provider/-%23-Provider-isProvider"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/abstract-provider/src.ts/index.ts#L269">source</a></div></div><div class="body"><p>Returns true if and only if <i>object</i> is a Provider.</p>
|
|
|
|
</div></div><div class="page-separator"></div><a name="/v5/api/providers/jsonrpc-provider/-%23-JsonRpcProvider"></a><a name="/v5/api/providers/jsonrpc-provider/-%23-JsonRpcProvider"></a><a name="/v5/api/providers/jsonrpc-provider/"></a><h1 class="show-anchors"><div>JsonRpcProvider<span class="inherits"> inherits <a href="#/v5/api/providers/provider/">Provider</a></span><div class="anchors"><a class="self" href="#/v5/api/providers/jsonrpc-provider/-%23-JsonRpcProvider"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/json-rpc-provider.ts#L270">source</a></div></div></h1><p>The <a href="https://github.com/ethereum/wiki/wiki/JSON-RPC">JSON-RPC API</a> is a popular method for interacting with Ethereum and is available in all major Ethereum node implementations (e.g. <a href="https://geth.ethereum.org">Geth</a> and <a href="https://www.parity.io">Parity</a>) as well as many third-party web services (e.g. <a href="https://infura.io">INFURA</a>)</p>
|
|
|
|
<div class="property show-anchors"><div class="signature"><span class="modifier">new </span><span class="path">ethers</span><span class="symbol">.</span><span class="path">providers</span><span class="symbol">.</span><span class="method">JsonRpcProvider</span><span class="symbol">(</span> <span class="symbol">[</span> <span class="param">urlOrConnectionInfo</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">networkish</span> <span class="symbol">]</span> <span class="symbol">]</span> <span class="symbol">)</span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/json-rpc-provider.ts#L276">source</a></div></div><div class="body"><p>Connect to a JSON-RPC HTTP API using the URL or <a href="#/v5/api/utils/web/-%23-ConnectionInfo">ConnectionInfo</a> <i>urlOrConnectionInfo</i> connected to the <i>networkish</i> network.</p>
|
|
|
|
<p>If <i>urlOrConnectionInfo</i> is not specified, the default (i.e. <code class="inline">http://localhost:8545</code>) is used and if no network is specified, it will be determined automatically by querying the node using <code class="inline">eth_chaindId</code> and falling back on <code class="inline">eth_networkId</code>.</p>
|
|
|
|
</div></div><div class="definition container-box note"><div class="term">Note: Connecting to a Local Node</div><div class="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><a name="/v5/api/providers/jsonrpc-provider/-%23-JsonRpcProvider-getSigner"></a><div class="property show-anchors"><div class="signature"><span class="path">jsonRpcProvider</span><span class="symbol">.</span><span class="method">getSigner</span><span class="symbol">(</span> <span class="symbol">[</span> <span class="param">addressOrIndex</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/providers/jsonrpc-provider/-%23-JsonRpcSigner">JsonRpcSigner</a></span><div class="anchors"><a class="self" href="#/v5/api/providers/jsonrpc-provider/-%23-JsonRpcProvider-getSigner"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/json-rpc-provider.ts#L344">source</a></div></div><div class="body"><p>Returns a <a href="#/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><a name="/v5/api/providers/jsonrpc-provider/-%23-JsonRpcProvider-getUncheckedSigner"></a><div class="property show-anchors"><div class="signature"><span class="path">jsonRpcProvider</span><span class="symbol">.</span><span class="method">getUncheckedSigner</span><span class="symbol">(</span> <span class="symbol">[</span> <span class="param">addressOrIndex</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/providers/jsonrpc-provider/-%23-UncheckedJsonRpcSigner">JsonRpcUncheckedSigner</a></span><div class="anchors"><a class="self" href="#/v5/api/providers/jsonrpc-provider/-%23-JsonRpcProvider-getUncheckedSigner"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/json-rpc-provider.ts#L348">source</a></div></div><div class="body">
|
|
</div></div><a name="/v5/api/providers/jsonrpc-provider/-%23-JsonRpcProvider-listAccounts"></a><div class="property show-anchors"><div class="signature"><span class="path">jsonRpcProvider</span><span class="symbol">.</span><span class="method">listAccounts</span><span class="symbol">(</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Array< string ></span><div class="anchors"><a class="self" href="#/v5/api/providers/jsonrpc-provider/-%23-JsonRpcProvider-listAccounts"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/json-rpc-provider.ts#L352">source</a></div></div><div class="body"><p>Returns a list of all account addresses managed by this provider.</p>
|
|
|
|
</div></div><a name="/v5/api/providers/jsonrpc-provider/-%23-JsonRpcProvider-send"></a><div class="property show-anchors"><div class="signature"><span class="path">jsonRpcProvider</span><span class="symbol">.</span><span class="method">send</span><span class="symbol">(</span> <span class="param">method</span> <span class="symbol">,</span> <span class="param">params</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< any ></span><div class="anchors"><a class="self" href="#/v5/api/providers/jsonrpc-provider/-%23-JsonRpcProvider-send"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/json-rpc-provider.ts#L358">source</a></div></div><div class="body"><p>Allows sending raw messages to the provider.</p>
|
|
|
|
<p>This can be used for backend-specific calls, such as for debugging or specific account management.</p>
|
|
|
|
</div></div><a name="/v5/api/providers/jsonrpc-provider/-%23-JsonRpcSigner"></a><a name="/v5/api/providers/jsonrpc-provider/-%23-JsonRpcProvider--JsonRpcSigner"></a><a name="/v5/api/providers/jsonrpc-provider/"></a><h2 class="show-anchors"><div>JsonRpcSigner<span class="inherits"> inherits <a href="#/v5/api/signer/-%23-Signer">Signer</a></span><div class="anchors"><a class="self" href="#/v5/api/providers/jsonrpc-provider/-%23-JsonRpcSigner"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/json-rpc-provider.ts#L101">source</a></div></div></h2><p>A <b>JsonRpcSigner</b> is a simple Signer which is backed by a connected <a href="#/v5/api/providers/jsonrpc-provider/">JsonRpcProvider</a>.</p>
|
|
|
|
<div class="property show-anchors"><div class="signature"><span class="path">signer</span><span class="symbol">.</span><span class="method">provider</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/providers/jsonrpc-provider/">JsonRpcProvider</a></span><div class="anchors"></div></div><div class="body"><p>The provider this signer was established from.</p>
|
|
|
|
</div></div><a name="/v5/api/providers/jsonrpc-provider/-%23-JsonRpcSigner-connectUnchecked"></a><div class="property show-anchors"><div class="signature"><span class="path">signer</span><span class="symbol">.</span><span class="method">connectUnchecked</span><span class="symbol">(</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/providers/jsonrpc-provider/-%23-UncheckedJsonRpcSigner">JsonRpcUncheckedSigner</a></span><div class="anchors"><a class="self" href="#/v5/api/providers/jsonrpc-provider/-%23-JsonRpcSigner-connectUnchecked"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/json-rpc-provider.ts#L138">source</a></div></div><div class="body"><p>Returns a new Signer object which does not perform additional checks when sending a transaction. See <a href="#/v5/api/providers/jsonrpc-provider/-%23-JsonRpcProvider-getUncheckedSigner">getUncheckedSigner</a> for more details.</p>
|
|
|
|
</div></div><a name="/v5/api/providers/jsonrpc-provider/-%23-JsonRpcSigner-sendUncheckedTransaction"></a><div class="property show-anchors"><div class="signature"><span class="path">signer</span><span class="symbol">.</span><span class="method">sendUncheckedTransaction</span><span class="symbol">(</span> <span class="param">transaction</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 > > ></span><div class="anchors"><a class="self" href="#/v5/api/providers/jsonrpc-provider/-%23-JsonRpcSigner-sendUncheckedTransaction"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/json-rpc-provider.ts#L157">source</a></div></div><div class="body"><p>Sends the <i>transaction</i> and returns a Promise which resolves to the opaque transaction hash.</p>
|
|
|
|
</div></div><a name="/v5/api/providers/jsonrpc-provider/-%23-JsonRpcSigner-unlock"></a><div class="property show-anchors"><div class="signature"><span class="path">signer</span><span class="symbol">.</span><span class="method">unlock</span><span class="symbol">(</span> <span class="param">password</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< boolean ></span><div class="anchors"><a class="self" href="#/v5/api/providers/jsonrpc-provider/-%23-JsonRpcSigner-unlock"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/json-rpc-provider.ts#L238">source</a></div></div><div class="body"><p>Request the node unlock the account (if locked) using <i>password</i>.</p>
|
|
|
|
</div></div><a name="/v5/api/providers/jsonrpc-provider/-%23-UncheckedJsonRpcSigner"></a><a name="/v5/api/providers/jsonrpc-provider/-%23-JsonRpcProvider--UncheckedJsonRpcSigner"></a><a name="/v5/api/providers/jsonrpc-provider/"></a><h2 class="show-anchors"><div>JsonRpcUncheckedSigner<span class="inherits"> inherits <a href="#/v5/api/signer/-%23-Signer">Signer</a></span><div class="anchors"><a class="self" href="#/v5/api/providers/jsonrpc-provider/-%23-UncheckedJsonRpcSigner"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/json-rpc-provider.ts#L247">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 <a href="#/v5/api/providers/jsonrpc-provider/-%23-JsonRpcSigner">JsonRpcSigner</a> immediately queries the provider for the details using the returned transaction hash to populate the <a href="#/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 <a href="#/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>
|
|
|
|
<a name="/v5/api/providers/jsonrpc-provider/-%23-JsonRpcProvider--other"></a><a name="/v5/api/providers/jsonrpc-provider/-%23-JsonRpcProvider--JsonRpcProvider--other"></a><a name="/v5/api/providers/jsonrpc-provider/"></a><h2 class="show-anchors"><div>Node-Specific Methods<div class="anchors"><a class="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. <a href="https://www.parity.io">Parity</a> vs <a href="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 <a href="#/v5/api/providers/jsonrpc-provider/-%23-JsonRpcProvider-send">jsonRpcProvider.send</a> method can be used to access these.</p>
|
|
|
|
<p><ul><li><a href="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><a href="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><a href="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><a href="https://github.com/ethereum/go-ethereum/wiki/Management-APIs">Additional Geth Methods</a> </li><li><a href="https://openethereum.github.io/wiki/JSONRPC">Additional Parity Methods</a> </li></ul></p>
|
|
|
|
<div class="page-separator"></div><a name="/v5/api/providers/api-providers/-%23-api-providers"></a><a name="/v5/api/providers/api-providers/-%23-api-providers"></a><a name="/v5/api/providers/api-providers/"></a><h1 class="show-anchors"><div>API Providers<div class="anchors"><a class="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 resilience, security and increase the amount of required trust. To mitigate these issues, it is recommended you use a <a href="#/v5/api/providers/-%23-providers-getDefaultProvider">Default Provider</a>.</p>
|
|
|
|
<a name="/v5/api/providers/api-providers/-%23-EtherscanProvider"></a><a name="/v5/api/providers/api-providers/-%23-api-providers--EtherscanProvider"></a><a name="/v5/api/providers/api-providers/"></a><h2 class="show-anchors"><div>EtherscanProvider<span class="inherits"> inherits <a href="#/v5/api/providers/provider/">Provider</a></span><div class="anchors"><a class="self" href="#/v5/api/providers/api-providers/-%23-EtherscanProvider"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/etherscan-provider.ts#L142">source</a></div></div></h2><p>The <b>EtherscanProvider</b> is backed by a combination of the various <a href="https://etherscan.io/apis">Etherscan APIs</a>.</p>
|
|
|
|
<div class="property show-anchors"><div class="signature"><span class="modifier">new </span><span class="path">ethers</span><span class="symbol">.</span><span class="path">providers</span><span class="symbol">.</span><span class="method">EtherscanProvider</span><span class="symbol">(</span> <span class="symbol">[</span> <span class="param">network</span> = "<span class="param">homestead</span>" <span class="symbol">,</span> <span class="symbol">[</span> <span class="param">apiKey</span> <span class="symbol">]</span> <span class="symbol">]</span> <span class="symbol">)</span><div class="anchors"></div></div><div class="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 a <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 <a href="https://etherscan.io">Etherscan</a> for your own API key.</p>
|
|
|
|
</div></div><div class="definition container-box note"><div class="term">Note: Default API keys</div><div class="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 <a href="https://etherscan.io">Etherscan</a> for your own API key.</p>
|
|
|
|
</div></div><div class="definition"><div class="term"><b>Supported Networks</b></div><div class="body"><p><ul><li>Homestead (Mainnet) </li><li>Ropsten (proof-of-work testnet) </li><li>Rinkeby (proof-of-authority testnet) </li><li>Görli (clique testnet) </li><li>Kovan (proof-of-authority testnet) </li></ul></p>
|
|
|
|
</div></div><div class="code-title"><div>Etherscan Examples</div></div><div class="code"><span class="comment">// Connect to mainnet (homestead)
|
|
</span>provider = new EtherscanProvider();
|
|
|
|
<span class="comment">// Connect to rinkeby testnet (these are equivalent)
|
|
</span>provider = new EtherscanProvider("rinkeby");
|
|
provider = new EtherscanProvider(4);
|
|
|
|
const network = ethers.providers.getNetwork("rinkeby");
|
|
<span class="result ok">// {
|
|
</span><span class="result ok">// chainId: 4,
|
|
</span><span class="result ok">// ensAddress: '0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e',
|
|
</span><span class="result ok">// name: 'rinkeby'
|
|
</span><span class="result ok">// }
|
|
</span>
|
|
provider = new EtherscanProvider(network);
|
|
|
|
<span class="comment">// Connect to mainnet (homestead) with an API key
|
|
</span>provider = new EtherscanProvider(null, apiKey);
|
|
provider = new EtherscanProvider("homestead", apiKey);
|
|
</div><div class="property show-anchors"><div class="signature"><span class="path">provider</span><span class="symbol">.</span><span class="method">getHistory</span><span class="symbol">(</span> <span class="param">address</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Array< History ></span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/etherscan-provider.ts#L392">source</a></div></div><div class="body"><p>@TODO... Explain</p>
|
|
|
|
</div></div><a name="/v5/api/providers/api-providers/-%23-InfuraProvider"></a><a name="/v5/api/providers/api-providers/-%23-api-providers--InfuraProvider"></a><a name="/v5/api/providers/api-providers/"></a><h2 class="show-anchors"><div>InfuraProvider<span class="inherits"> inherits <a href="#/v5/api/providers/other/-%23-UrlJsonRpcProvider">UrlJsonRpcProvider</a></span><div class="anchors"><a class="self" href="#/v5/api/providers/api-providers/-%23-InfuraProvider"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/infura-provider.ts#L46">source</a></div></div></h2><p>The <b>InfuraProvider</b> is backed by the popular <a href="https://infura.io">INFURA</a> Ethereum service.</p>
|
|
|
|
<div class="property show-anchors"><div class="signature"><span class="modifier">new </span><span class="path">ethers</span><span class="symbol">.</span><span class="path">providers</span><span class="symbol">.</span><span class="method">InfuraProvider</span><span class="symbol">(</span> <span class="symbol">[</span> <span class="param">network</span> = "<span class="param">homestead</span>" <span class="symbol">,</span> <span class="symbol">[</span> <span class="param">apiKey</span> <span class="symbol">]</span> <span class="symbol">]</span> <span class="symbol">)</span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/infura-provider.ts#L46">source</a></div></div><div class="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 a <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 <code class="inline">projectId</code> and <code class="inline">projectSecret</code> to specify a <a href="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><a name="/v5/api/providers/api-providers/-%23-InfuraProvider-getWebSocketProvider"></a><div class="property show-anchors"><div class="signature"><span class="path">InfuraProvider</span><span class="symbol">.</span><span class="method">getWebSocketProvider</span><span class="symbol">(</span> <span class="symbol">[</span> <span class="param">network</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">apiKey</span> <span class="symbol">]</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/providers/other/-%23-WebSocketProvider">WebSocketProvider</a></span><div class="anchors"><a class="self" href="#/v5/api/providers/api-providers/-%23-InfuraProvider-getWebSocketProvider"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/infura-provider.ts#L50">source</a></div></div><div class="body"><p>Create a new <a href="#/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 <a href="#/v5/api/providers/api-providers/-%23-InfuraProvider">the constructor</a>.</p>
|
|
|
|
</div></div><div class="definition container-box note"><div class="term">Note: Default API keys</div><div class="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 <a href="https://infura.io">INFURA</a> for your own API key.</p>
|
|
|
|
</div></div><div class="definition"><div class="term"><b>Supported Networks</b></div><div class="body"><p><ul><li>Homestead (Mainnet) </li><li>Ropsten (proof-of-work testnet) </li><li>Rinkeby (proof-of-authority testnet) </li><li>Görli (clique testnet) </li><li>Kovan (proof-of-authority testnet) </li></ul></p>
|
|
|
|
</div></div><div class="code-title"><div>INFURA Examples</div></div><div class="code"><span class="comment">// Connect to mainnet (homestead)
|
|
</span>provider = new InfuraProvider();
|
|
|
|
<span class="comment">// Connect to the ropsten testnet
|
|
</span><span class="comment">// (see EtherscanProvider above for other network examples)
|
|
</span>provider = new InfuraProvider("ropsten");
|
|
|
|
<span class="comment">// Connect to mainnet with a Project ID (these are equivalent)
|
|
</span>provider = new InfuraProvider(null, projectId);
|
|
provider = new InfuraProvider("homestead", projectId);
|
|
|
|
<span class="comment">// Connect to mainnet with a Project ID and Project Secret
|
|
</span>provider = new InfuraProvider("homestead", {
|
|
projectId: projectId,
|
|
projectSecret: projectSecret
|
|
});
|
|
|
|
<span class="comment">// Connect to the INFURA WebSocket endpoints with a WebSocketProvider
|
|
</span>provider = InfuraProvider.getWebSocketProvider()
|
|
</div><a name="/v5/api/providers/api-providers/-%23-AlchemyProvider"></a><a name="/v5/api/providers/api-providers/-%23-api-providers--AlchemyProvider"></a><a name="/v5/api/providers/api-providers/"></a><h2 class="show-anchors"><div>AlchemyProvider<span class="inherits"> inherits <a href="#/v5/api/providers/other/-%23-UrlJsonRpcProvider">UrlJsonRpcProvider</a></span><div class="anchors"><a class="self" href="#/v5/api/providers/api-providers/-%23-AlchemyProvider"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/alchemy-provider.ts#L41">source</a></div></div></h2><p>The <b>AlchemyProvider</b> is backed by <a href="https://alchemyapi.io">Alchemy</a>.</p>
|
|
|
|
<div class="property show-anchors"><div class="signature"><span class="modifier">new </span><span class="path">ethers</span><span class="symbol">.</span><span class="path">providers</span><span class="symbol">.</span><span class="method">AlchemyProvider</span><span class="symbol">(</span> <span class="symbol">[</span> <span class="param">network</span> = "<span class="param">homestead</span>" <span class="symbol">,</span> <span class="symbol">[</span> <span class="param">apiKey</span> <span class="symbol">]</span> <span class="symbol">]</span> <span class="symbol">)</span><div class="anchors"></div></div><div class="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 a <b>string</b> for a common network name, a <b>number</b> for a common chain ID or a <a href="#/v5/api/providers/types/-%23-providers-Network">Network Object</a>.</p>
|
|
|
|
</div></div><div class="definition container-box note"><div class="term">Note: Default API keys</div><div class="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 <a href="https://alchemyapi.io">Alchemy</a> for your own API key.</p>
|
|
|
|
</div></div><div class="definition"><div class="term"><b>Supported Networks</b></div><div class="body"><p><ul><li>Homestead (Mainnet) </li><li>Ropsten (proof-of-work testnet) </li><li>Rinkeby (proof-of-authority testnet) </li><li>Görli (clique testnet) </li><li>Kovan (proof-of-authority testnet) </li></ul></p>
|
|
|
|
</div></div><div class="code-title"><div>Alchemy Examples</div></div><div class="code"><span class="comment">// Connect to mainnet (homestead)
|
|
</span>provider = new AlchemyProvider();
|
|
|
|
<span class="comment">// Connect to the ropsten testnet
|
|
</span><span class="comment">// (see EtherscanProvider above for other network examples)
|
|
</span>provider = new AlchemyProvider("ropsten");
|
|
|
|
<span class="comment">// Connect to mainnet with an API key (these are equivalent)
|
|
</span>provider = new AlchemyProvider(null, apiKey);
|
|
provider = new AlchemyProvider("homestead", apiKey);
|
|
|
|
<span class="comment">// Connect to the Alchemy WebSocket endpoints with a WebSocketProvider
|
|
</span>provider = AlchemyProvider.getWebSocketProvider()
|
|
</div><a name="/v5/api/providers/api-providers/-%23-CloudflareProvider"></a><a name="/v5/api/providers/api-providers/-%23-api-providers--CloudflareProvider"></a><a name="/v5/api/providers/api-providers/"></a><h2 class="show-anchors"><div>CloudflareProvider<span class="inherits"> inherits <a href="#/v5/api/providers/other/-%23-UrlJsonRpcProvider">UrlJsonRpcProvider</a></span><div class="anchors"><a class="self" href="#/v5/api/providers/api-providers/-%23-CloudflareProvider"></a><a class="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 <a href="https://developers.cloudflare.com/distributed-web/ethereum-gateway/">Cloudflare Ethereum Gateway</a>.</p>
|
|
|
|
<div class="property show-anchors"><div class="signature"><span class="modifier">new </span><span class="path">ethers</span><span class="symbol">.</span><span class="path">providers</span><span class="symbol">.</span><span class="method">CloudflareProvider</span><span class="symbol">(</span> <span class="symbol">)</span><div class="anchors"></div></div><div class="body"><p>Create a new <b>CloudflareProvider</b> connected to mainnet (i.e. "homestead").</p>
|
|
|
|
</div></div><div class="definition"><div class="term"><b>Supported Networks</b></div><div class="body"><p><ul><li>Homestead (Mainnet) </li></ul></p>
|
|
|
|
</div></div><div class="code-title"><div>Cloudflare Examples</div></div><div class="code"><span class="comment">// Connect to mainnet (homestead)
|
|
</span>provider = new CloudflareProvider();
|
|
</div><div class="page-separator"></div><a name="/v5/api/providers/other/-%23-other-providers"></a><a name="/v5/api/providers/other/"></a><h1 class="show-anchors"><div>Other Providers<div class="anchors"><a class="self" href="#/v5/api/providers/other/-%23-other-providers"></a></div></div></h1>
|
|
<a name="/v5/api/providers/other/-%23-FallbackProvider"></a><a name="/v5/api/providers/other/-%23-other-providers--FallbackProvider"></a><a name="/v5/api/providers/other/"></a><h2 class="show-anchors"><div>FallbackProvider<span class="inherits"> inherits <a href="#/v5/api/providers/provider/">Provider</a></span><div class="anchors"><a class="self" href="#/v5/api/providers/other/-%23-FallbackProvider"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/fallback-provider.ts#L403">source</a></div></div></h2><p>The <b>FallbackProvider</b> is the most advanced <a href="#/v5/api/providers/provider/">Provider</a> available in ethers.</p>
|
|
|
|
<p>It uses a quorum and connects to multiple <a href="#/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 chosen (lower-value priority 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>
|
|
|
|
<div class="property show-anchors"><div class="signature"><span class="modifier">new </span><span class="path">ethers</span><span class="symbol">.</span><span class="path">providers</span><span class="symbol">.</span><span class="method">FallbackProvider</span><span class="symbol">(</span> <span class="param">providers</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">quorum</span> <span class="symbol">]</span> <span class="symbol">)</span><div class="anchors"></div></div><div class="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 <a href="#/v5/api/providers/provider/">Provider</a> or <a href="#/v5/api/providers/other/-%23-FallbackProviderConfig">FallbackProviderConfig</a>. If a <a href="#/v5/api/providers/provider/">Provider</a> is provided, the defaults are a priority of 1 and a weight of 1.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">provider</span><span class="symbol">.</span><span class="method">providerConfigs</span> <span class="arrow">⇒</span> <span class="returns">Array< <a href="#/v5/api/providers/other/-%23-FallbackProviderConfig">FallbackProviderConfig</a> ></span><div class="anchors"></div></div><div class="body"><p>The list of Provider Configurations that describe the backends.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">provider</span><span class="symbol">.</span><span class="method">quorum</span> <span class="arrow">⇒</span> <span class="returns">number</span><div class="anchors"></div></div><div class="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>
|
|
|
|
</div></div><a name="/v5/api/providers/other/-%23-FallbackProviderConfig"></a><a name="/v5/api/providers/other/-%23-other-providers--FallbackProvider--FallbackProviderConfig"></a><a name="/v5/api/providers/other/"></a><h3 class="show-anchors"><div>FallbackProviderConfig<div class="anchors"><a class="self" href="#/v5/api/providers/other/-%23-FallbackProviderConfig"></a></div></div></h3>
|
|
<div class="property show-anchors"><div class="signature"><span class="path">fallbackProviderConfig</span><span class="symbol">.</span><span class="method">provider</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/providers/provider/">Provider</a></span><div class="anchors"></div></div><div class="body"><p>The provider for this configuration.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">fallbackProviderConfig</span><span class="symbol">.</span><span class="method">priority</span> <span class="arrow">⇒</span> <span class="returns">number</span><div class="anchors"></div></div><div class="body"><p>The priority used for the provider. Lower-value priorities are favoured over higher-value priorities. If multiple providers share the same priority, they are chosen at random.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">fallbackProviderConfig</span><span class="symbol">.</span><span class="method">stallTimeout</span> <span class="arrow">⇒</span> <span class="returns">number</span><div class="anchors"></div></div><div class="body"><p>The timeout (in ms) after which another <a href="#/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><div class="property show-anchors"><div class="signature"><span class="path">fallbackProviderConfig</span><span class="symbol">.</span><span class="method">weight</span> <span class="arrow">⇒</span> <span class="returns">number</span><div class="anchors"></div></div><div class="body"><p>The weight a response from this provider provides. This can be used if a given <a href="#/v5/api/providers/provider/">Provider</a> is more trusted, for example.</p>
|
|
|
|
</div></div><a name="/v5/api/providers/other/-%23-IpcProvider"></a><a name="/v5/api/providers/other/-%23-other-providers--IpcProvider"></a><a name="/v5/api/providers/other/"></a><h2 class="show-anchors"><div>IpcProvider<span class="inherits"> inherits <a href="#/v5/api/providers/jsonrpc-provider/">JsonRpcProvider</a></span><div class="anchors"><a class="self" href="#/v5/api/providers/other/-%23-IpcProvider"></a><a class="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>
|
|
|
|
<div class="property show-anchors"><div class="signature"><span class="path">ipcProvider</span><span class="symbol">.</span><span class="method">path</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"></div></div><div class="body"><p>The path this <a href="#/v5/api/providers/provider/">Provider</a> is connected to.</p>
|
|
|
|
</div></div><a name="/v5/api/providers/other/-%23-UrlJsonRpcProvider"></a><a name="/v5/api/providers/other/-%23-other-providers--UrlJsonRpcProvider"></a><a name="/v5/api/providers/other/"></a><h2 class="show-anchors"><div>UrlJsonRpcProvider<span class="inherits"> inherits <a href="#/v5/api/providers/jsonrpc-provider/">JsonRpcProvider</a></span><div class="anchors"><a class="self" href="#/v5/api/providers/other/-%23-UrlJsonRpcProvider"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/url-json-rpc-provider.ts#L50">source</a></div></div></h2><p>This class is intended to be sub-classed and not used directly. It simplifies creating a <a href="#/v5/api/providers/provider/">Provider</a> where a normal <a href="#/v5/api/providers/jsonrpc-provider/">JsonRpcProvider</a> would suffice, with a little extra effort needed to generate the JSON-RPC URL.</p>
|
|
|
|
<div class="property show-anchors"><div class="signature"><span class="modifier">new </span><span class="path">ethers</span><span class="symbol">.</span><span class="path">providers</span><span class="symbol">.</span><span class="method">UrlJsonRpcProvider</span><span class="symbol">(</span> <span class="symbol">[</span> <span class="param">network</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">apiKey</span> <span class="symbol">]</span> <span class="symbol">]</span> <span class="symbol">)</span><div class="anchors"></div></div><div class="body"><p>Sub-classes do not need to override this. Instead they should override the static method <code class="inline">getUrl</code> and optionally <code class="inline">getApiKey</code>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">urlJsonRpcProvider</span><span class="symbol">.</span><span class="method">apiKey</span> <span class="arrow">⇒</span> <span class="returns">any</span><div class="anchors"></div></div><div class="body"><p>The value of the apiKey that was returned from <code class="inline">InheritedClass.getApiKey</code>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">InheritingClass</span><span class="symbol">.</span><span class="method">getApiKey</span><span class="symbol">(</span> <span class="param">apiKey</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">any</span><div class="anchors"></div></div><div class="body"><p>This function should examine the <i>apiKey</i> to ensure it is valid and return a (possible modified) value to use in <code class="inline">getUrl</code>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">InheritingClass</span><span class="symbol">.</span><span class="method">getUrl</span><span class="symbol">(</span> <span class="param">network</span> <span class="symbol">,</span> <span class="param">apiKey</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"></div></div><div class="body"><p>The URL to use for the JsonRpcProvider instance.</p>
|
|
|
|
</div></div><a name="/v5/api/providers/other/-%23-Web3Provider"></a><a name="/v5/api/providers/other/-%23-other-providers--Web3Provider"></a><a name="/v5/api/providers/other/"></a><h2 class="show-anchors"><div>Web3Provider<span class="inherits"> inherits <a href="#/v5/api/providers/jsonrpc-provider/">JsonRpcProvider</a></span><div class="anchors"><a class="self" href="#/v5/api/providers/other/-%23-Web3Provider"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/web3-provider.ts#L78">source</a></div></div></h2><p>The Web3Provider is meant to ease moving from a <a href="https://github.com/ethereum/web3.js">web3.js based</a> application to ethers by wrapping an existing Web3-compatible (such as a <a href="https://github.com/ethereum/web3.js/tree/1.x/packages/web3-providers-http">Web3HttpProvider</a>, <a href="https://github.com/ethereum/web3.js/tree/1.x/packages/web3-providers-ipc">Web3IpcProvider</a> or <a href="https://github.com/ethereum/web3.js/tree/1.x/packages/web3-providers-ws">Web3WsProvider</a>) and exposing it as an ethers.js <a href="#/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>
|
|
|
|
<div class="property show-anchors"><div class="signature"><span class="modifier">new </span><span class="path">ethers</span><span class="symbol">.</span><span class="path">providers</span><span class="symbol">.</span><span class="method">Web3Provider</span><span class="symbol">(</span> <span class="param">externalProvider</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">network</span> <span class="symbol">]</span> <span class="symbol">)</span><div class="anchors"></div></div><div class="body"><p>Create a new <b>Web3Provider</b>, which wraps an <a href="https://eips.ethereum.org/EIPS/eip-1193">EIP-1193 Provider</a> or Web3Provider-compatible Provider.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">web3Provider</span><span class="symbol">.</span><span class="method">provider</span> <span class="arrow">⇒</span> <span class="returns">Web3CompatibleProvider</span><div class="anchors"></div></div><div class="body"><p>The provider used to create this instance.</p>
|
|
|
|
</div></div><a name="/v5/api/providers/other/-%23-Web3Provider--ExternalProvider"></a><a name="/v5/api/providers/other/-%23-other-providers--Web3Provider--Web3Provider--ExternalProvider"></a><a name="/v5/api/providers/other/"></a><h3 class="show-anchors"><div>ExternalProvider<div class="anchors"><a class="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 <a href="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>
|
|
|
|
<div class="property show-anchors"><div class="signature"><span class="path">externalProvider</span><span class="symbol">.</span><span class="method">request</span><span class="symbol">(</span> <span class="param">request</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< any ></span><div class="anchors"></div></div><div class="body"><p>This follows the <a href="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 <code class="inline">method</code> and <code class="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><div class="property show-anchors"><div class="signature"><span class="path">externalProvider</span><span class="symbol">.</span><span class="method">sendAsync</span><span class="symbol">(</span> <span class="param">request</span> <span class="symbol">,</span> <span class="param">callback</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">void</span><div class="anchors"></div></div><div class="body"><p>This follows the <a href="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 <code class="inline">method</code> and <code class="inline">params</code>.</p>
|
|
|
|
<p>The <i>callback</i> should use the error-first calling semantics, so <code class="inline">(error, result)</code> where the result is a JSON-RPC wrapped result.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">externalProvider</span><span class="symbol">.</span><span class="method">send</span><span class="symbol">(</span> <span class="param">request</span> <span class="symbol">,</span> <span class="param">callback</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">void</span><div class="anchors"></div></div><div class="body"><p>This is identical to <code class="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><a name="/v5/api/providers/other/-%23-WebSocketProvider"></a><a name="/v5/api/providers/other/-%23-other-providers--WebSocketProvider"></a><a name="/v5/api/providers/other/"></a><h2 class="show-anchors"><div>WebSocketProvider<span class="inherits"> inherits <a href="#/v5/api/providers/jsonrpc-provider/">JsonRpcProvider</a></span><div class="anchors"><a class="self" href="#/v5/api/providers/other/-%23-WebSocketProvider"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/providers/src.ts/websocket-provider.ts#L46">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 resources, 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>
|
|
|
|
<div class="property show-anchors"><div class="signature"><span class="modifier">new </span><span class="path">ethers</span><span class="symbol">.</span><span class="path">providers</span><span class="symbol">.</span><span class="method">WebSocketProvider</span><span class="symbol">(</span> <span class="symbol">[</span> <span class="param">url</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">network</span> <span class="symbol">]</span> <span class="symbol">]</span> <span class="symbol">)</span><div class="anchors"></div></div><div class="body"><p>Returns a new <a href="#/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 <code class="inline">"ws://localhost:8546"</code> will be used. If <i>network</i> is unspecified, it will be queried from the network.</p>
|
|
|
|
</div></div><div class="page-separator"></div><a name="/v5/api/providers/types/-%23-types"></a><a name="/v5/api/providers/types/"></a><h1 class="show-anchors"><div>Types<div class="anchors"><a class="self" href="#/v5/api/providers/types/-%23-types"></a></div></div></h1>
|
|
<a name="/v5/api/providers/types/-%23-providers-BlockTag"></a><a name="/v5/api/providers/types/-%23-types--providers-BlockTag"></a><a name="/v5/api/providers/types/"></a><h2 class="show-anchors"><div>BlockTag<div class="anchors"><a class="self" href="#/v5/api/providers/types/-%23-providers-BlockTag"></a></div></div></h2><p>A <b>BlockTag</b> specifies a specific block location in the Blockchain.</p>
|
|
|
|
<p><ul><li><b><code class="inline">"latest"</code></b> - The most recently mined block </li><li><b><code class="inline">"earliest"</code></b> - Block #0 </li><li><b><code class="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><li><b><i>hex string</i></b> - The block at this height (as a hexidecimal value) </li></ul></p>
|
|
|
|
<a name="/v5/api/providers/types/-%23-providers-Networkish"></a><a name="/v5/api/providers/types/-%23-types--providers-Networkish"></a><a name="/v5/api/providers/types/"></a><h2 class="show-anchors"><div>Networkish<div class="anchors"><a class="self" href="#/v5/api/providers/types/-%23-providers-Networkish"></a></div></div></h2><p>A <b>Networkish</b> may be any of the following:</p>
|
|
|
|
<p><ul><li>a <a href="#/v5/api/providers/types/-%23-providers-Network">Network</a> object </li><li>the name of a common network as a string (e.g. <code class="inline">"homestead"</code>) </li><li>the chain ID a network as a number; if the chain ID is that of a common network, the <code class="inline">name</code> and <code class="inline">ensAddress</code> will be populated, otherwise, the default name <code class="inline">"unknown"</code> and no <code class="inline">ensAddress</code> is used </li></ul></p>
|
|
|
|
<a name="/v5/api/providers/types/-%23-providers-Network"></a><a name="/v5/api/providers/types/-%23-types--providers-Network"></a><a name="/v5/api/providers/types/"></a><h2 class="show-anchors"><div>Network<div class="anchors"><a class="self" href="#/v5/api/providers/types/-%23-providers-Network"></a></div></div></h2><p>A <b>Network</b> represents an Ethereum network.</p>
|
|
|
|
<div class="property show-anchors"><div class="signature"><span class="path">network</span><span class="symbol">.</span><span class="method">name</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"></div></div><div class="body"><p>The human-readable name of the network, such as <code class="inline">homestead</code>. If the network name is unknown, this will be <code class="inline">"unknown"</code>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">network</span><span class="symbol">.</span><span class="method">chainId</span> <span class="arrow">⇒</span> <span class="returns">number</span><div class="anchors"></div></div><div class="body"><p>The Chain ID of the network.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">network</span><span class="symbol">.</span><span class="method">ensAddress</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/address/-%23-address">Address</a> ></span><div class="anchors"></div></div><div class="body"><p>The address at which the ENS registry is deployed on this network.</p>
|
|
|
|
</div></div><a name="/v5/api/providers/types/-%23-providers-Block"></a><a name="/v5/api/providers/types/-%23-types--providers-Block"></a><a name="/v5/api/providers/types/"></a><h2 class="show-anchors"><div>Block<div class="anchors"><a class="self" href="#/v5/api/providers/types/-%23-providers-Block"></a></div></div></h2>
|
|
<div class="property show-anchors"><div class="signature"><span class="path">block</span><span class="symbol">.</span><span class="method">hash</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 > ></span><div class="anchors"></div></div><div class="body"><p>The hash of this block.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">block</span><span class="symbol">.</span><span class="method">parentHash</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 > ></span><div class="anchors"></div></div><div class="body"><p>The hash of the previous block.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">block</span><span class="symbol">.</span><span class="method">number</span> <span class="arrow">⇒</span> <span class="returns">number</span><div class="anchors"></div></div><div class="body"><p>The height (number) of this block.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">block</span><span class="symbol">.</span><span class="method">timestamp</span> <span class="arrow">⇒</span> <span class="returns">number</span><div class="anchors"></div></div><div class="body"><p>The timestamp of this block.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">block</span><span class="symbol">.</span><span class="method">nonce</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a> ></span><div class="anchors"></div></div><div class="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 to developers.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">block</span><span class="symbol">.</span><span class="method">difficulty</span> <span class="arrow">⇒</span> <span class="returns">number</span><div class="anchors"></div></div><div class="body"><p>The difficulty target required to be met by the miner of the block.</p>
|
|
|
|
<p>This property is generally of little interest to developers.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">block</span><span class="symbol">.</span><span class="method">gasLimit</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/bignumber/">BigNumber</a></span><div class="anchors"></div></div><div class="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 to developers.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">block</span><span class="symbol">.</span><span class="method">gasUsed</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/bignumber/">BigNumber</a></span><div class="anchors"></div></div><div class="body"><p>The total amount of gas used by all transactions in this block.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">block</span><span class="symbol">.</span><span class="method">miner</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"></div></div><div class="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><div class="property show-anchors"><div class="signature"><span class="path">block</span><span class="symbol">.</span><span class="method">extraData</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"></div></div><div class="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 to developers.</p>
|
|
|
|
</div></div><a name="/v5/api/providers/types/-%23-types--providers-Block--block-with-transaction-hashes"></a><a name="/v5/api/providers/types/"></a><h3 class="show-anchors"><div>Block (with transaction hashes)<div class="anchors"><a class="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>
|
|
|
|
<div class="property show-anchors"><div class="signature"><span class="path">block</span><span class="symbol">.</span><span class="method">transactions</span> <span class="arrow">⇒</span> <span class="returns">Array< string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 > > ></span><div class="anchors"></div></div><div class="body"><p>A list of the transactions hashes for each transaction this block includes.</p>
|
|
|
|
</div></div><a name="/v5/api/providers/types/-%23-providers-BlockWithTransactions"></a><a name="/v5/api/providers/types/-%23-types--providers-Block--providers-BlockWithTransactions"></a><a name="/v5/api/providers/types/"></a><h3 class="show-anchors"><div>BlockWithTransactions<span class="inherits"> inherits <a href="#/v5/api/providers/types/-%23-providers-Block">Block</a></span><div class="anchors"><a class="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>
|
|
|
|
<div class="property show-anchors"><div class="signature"><span class="path">block</span><span class="symbol">.</span><span class="method">transactions</span> <span class="arrow">⇒</span> <span class="returns">Array< <a href="#/v5/api/providers/types/-%23-providers-TransactionResponse">TransactionResponse</a> ></span><div class="anchors"></div></div><div class="body"><p>A list of the transactions this block includes.</p>
|
|
|
|
</div></div><a name="/v5/api/providers/types/-%23-types--events-and-logs"></a><a name="/v5/api/providers/types/"></a><h2 class="show-anchors"><div>Events and Logs<div class="anchors"><a class="self" href="#/v5/api/providers/types/-%23-types--events-and-logs"></a></div></div></h2>
|
|
<a name="/v5/api/providers/types/-%23-providers-EventFilter"></a><a name="/v5/api/providers/types/-%23-types--events-and-logs--providers-EventFilter"></a><a name="/v5/api/providers/types/"></a><h3 class="show-anchors"><div>EventFilter<div class="anchors"><a class="self" href="#/v5/api/providers/types/-%23-providers-EventFilter"></a></div></div></h3>
|
|
<div class="property show-anchors"><div class="signature"><span class="path">filter</span><span class="symbol">.</span><span class="method">address</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/address/-%23-address">Address</a> ></span><div class="anchors"></div></div><div class="body"><p>The address to filter by, or <code class="inline">null</code> to match any address.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">filter</span><span class="symbol">.</span><span class="method">topics</span> <span class="arrow">⇒</span> <span class="returns">Array< string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">Data</a>< 32 > > | Array< string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">Data</a>< 32 > > > ></span><div class="anchors"></div></div><div class="body"><p>The topics to filter by or <code class="inline">null</code> to match any topics.</p>
|
|
|
|
<p>Each entry represents an <b>AND</b> condition that must match, or may be <code class="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>
|
|
|
|
<p>See <a href="#/v5/concepts/events/-%23-events--filters">Filters</a> for more details and examples on specifying complex filters.</p>
|
|
|
|
</div></div><a name="/v5/api/providers/types/-%23-providers-Filter"></a><a name="/v5/api/providers/types/-%23-types--events-and-logs--providers-Filter"></a><a name="/v5/api/providers/types/"></a><h3 class="show-anchors"><div>Filter<span class="inherits"> inherits <a href="#/v5/api/providers/types/-%23-providers-EventFilter">EventFilter</a></span><div class="anchors"><a class="self" href="#/v5/api/providers/types/-%23-providers-Filter"></a></div></div></h3>
|
|
<div class="property show-anchors"><div class="signature"><span class="path">filter</span><span class="symbol">.</span><span class="method">fromBlock</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/providers/types/-%23-providers-BlockTag">BlockTag</a></span><div class="anchors"></div></div><div class="body"><p>The starting block (inclusive) to search for logs matching the filter criteria.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">filter</span><span class="symbol">.</span><span class="method">toBlock</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/providers/types/-%23-providers-BlockTag">BlockTag</a></span><div class="anchors"></div></div><div class="body"><p>The end block (inclusive) to search for logs matching the filter criteria.</p>
|
|
|
|
</div></div><a name="/v5/api/providers/types/-%23-providers-FilterByBlockHash"></a><a name="/v5/api/providers/types/-%23-types--events-and-logs--providers-FilterByBlockHash"></a><a name="/v5/api/providers/types/"></a><h3 class="show-anchors"><div>FilterByBlockHash<span class="inherits"> inherits <a href="#/v5/api/providers/types/-%23-providers-EventFilter">EventFilter</a></span><div class="anchors"><a class="self" href="#/v5/api/providers/types/-%23-providers-FilterByBlockHash"></a></div></div></h3>
|
|
<div class="property show-anchors"><div class="signature"><span class="path">filter</span><span class="symbol">.</span><span class="method">blockHash</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 > ></span><div class="anchors"></div></div><div class="body"><p>The specific block (by its block hash) to search for logs matching the filter criteria.</p>
|
|
|
|
</div></div><a name="/v5/api/providers/types/-%23-providers-Log"></a><a name="/v5/api/providers/types/-%23-types--events-and-logs--providers-Log"></a><a name="/v5/api/providers/types/"></a><h3 class="show-anchors"><div>Log<div class="anchors"><a class="self" href="#/v5/api/providers/types/-%23-providers-Log"></a></div></div></h3>
|
|
<div class="property show-anchors"><div class="signature"><span class="path">log</span><span class="symbol">.</span><span class="method">blockNumber</span> <span class="arrow">⇒</span> <span class="returns">number</span><div class="anchors"></div></div><div class="body"><p>The block height (number) of the block including the transaction of this log.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">log</span><span class="symbol">.</span><span class="method">blockHash</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 > ></span><div class="anchors"></div></div><div class="body"><p>The block hash of the block including the transaction of this log.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">log</span><span class="symbol">.</span><span class="method">removed</span> <span class="arrow">⇒</span> <span class="returns">boolean</span><div class="anchors"></div></div><div class="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><div class="property show-anchors"><div class="signature"><span class="path">log</span><span class="symbol">.</span><span class="method">transactionLogIndex</span> <span class="arrow">⇒</span> <span class="returns">number</span><div class="anchors"></div></div><div class="body"><p>The index of this log in the transaction.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">log</span><span class="symbol">.</span><span class="method">address</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/address/-%23-address">Address</a> ></span><div class="anchors"></div></div><div class="body"><p>The address of the contract that generated this log.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">log</span><span class="symbol">.</span><span class="method">data</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a> ></span><div class="anchors"></div></div><div class="body"><p>The data included in this log.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">log</span><span class="symbol">.</span><span class="method">topics</span> <span class="arrow">⇒</span> <span class="returns">Array< string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 > > ></span><div class="anchors"></div></div><div class="body"><p>The list of topics (indexed properties) for this log.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">log</span><span class="symbol">.</span><span class="method">transactionHash</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 > ></span><div class="anchors"></div></div><div class="body"><p>The transaction hash of the transaction of this log.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">log</span><span class="symbol">.</span><span class="method">transactionIndex</span> <span class="arrow">⇒</span> <span class="returns">number</span><div class="anchors"></div></div><div class="body"><p>The index of the transaction in the block of the transaction of this log.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">log</span><span class="symbol">.</span><span class="method">logIndex</span> <span class="arrow">⇒</span> <span class="returns">number</span><div class="anchors"></div></div><div class="body"><p>The index of this log across all logs in the entire <b>block</b>.</p>
|
|
|
|
</div></div><a name="/v5/api/providers/types/-%23-types--transactions"></a><a name="/v5/api/providers/types/"></a><h2 class="show-anchors"><div>Transactions<div class="anchors"><a class="self" href="#/v5/api/providers/types/-%23-types--transactions"></a></div></div></h2>
|
|
<a name="/v5/api/providers/types/-%23-providers-TransactionRequest"></a><a name="/v5/api/providers/types/-%23-types--transactions--providers-TransactionRequest"></a><a name="/v5/api/providers/types/"></a><h3 class="show-anchors"><div>TransactionRequest<div class="anchors"><a class="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>
|
|
|
|
<div class="property show-anchors"><div class="signature"><span class="path">transactionRequest</span><span class="symbol">.</span><span class="method">to</span> <span class="arrow">⇒</span> <span class="returns">string | Promise< string ></span><div class="anchors"></div></div><div class="body"><p>The address (or ENS name) this transaction it to.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">transactionRequest</span><span class="symbol">.</span><span class="method">from</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/address/-%23-address">Address</a> > | Promise< string< <a href="#/v5/api/utils/address/-%23-address">Address</a> > ></span><div class="anchors"></div></div><div class="body"><p>The address this transaction is from.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">transactionRequest</span><span class="symbol">.</span><span class="method">nonce</span> <span class="arrow">⇒</span> <span class="returns">number | Promise< number ></span><div class="anchors"></div></div><div class="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><div class="property show-anchors"><div class="signature"><span class="path">transactionRequest</span><span class="symbol">.</span><span class="method">gasLimit</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/bignumber/">BigNumber</a> | Promise< <a href="#/v5/api/utils/bignumber/">BigNumber</a> ></span><div class="anchors"></div></div><div class="body"><p>The maximum amount of gas this transaction is permitted to use.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">transactionRequest</span><span class="symbol">.</span><span class="method">gasPrice</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/bignumber/">BigNumber</a> | Promise< <a href="#/v5/api/utils/bignumber/">BigNumber</a> ></span><div class="anchors"></div></div><div class="body"><p>The price (in wei) per unit of gas this transaction will pay.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">transactionRequest</span><span class="symbol">.</span><span class="method">data</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a> | Promise< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a> ></span><div class="anchors"></div></div><div class="body"><p>The transaction data.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">transactionRequest</span><span class="symbol">.</span><span class="method">value</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/bignumber/">BigNumber</a> | Promise< <a href="#/v5/api/utils/bignumber/">BigNumber</a> ></span><div class="anchors"></div></div><div class="body"><p>The amount (in wei) this transaction is sending.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">transactionRequest</span><span class="symbol">.</span><span class="method">chainId</span> <span class="arrow">⇒</span> <span class="returns">number | Promise< number ></span><div class="anchors"></div></div><div class="body"><p>The chain ID this transaction is authorized on, as specified by <a href="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><a name="/v5/api/providers/types/-%23-providers-TransactionResponse"></a><a name="/v5/api/providers/types/-%23-types--transactions--providers-TransactionResponse"></a><a name="/v5/api/providers/types/"></a><h3 class="show-anchors"><div>TransactionResponse<span class="inherits"> inherits <a href="#/v5/api/utils/transactions/-%23-Transaction">Transaction</a></span><div class="anchors"><a class="self" href="#/v5/api/providers/types/-%23-providers-TransactionResponse"></a></div></div></h3><p>A <b>TransactionResponse</b> includes all properties of a <a href="#/v5/api/utils/transactions/-%23-Transaction">Transaction</a> as well as several properties that are useful once it has been mined.</p>
|
|
|
|
<div class="property show-anchors"><div class="signature"><span class="path">transaction</span><span class="symbol">.</span><span class="method">blockNumber</span> <span class="arrow">⇒</span> <span class="returns">number</span><div class="anchors"></div></div><div class="body"><p>The number ("height") of the block this transaction was mined in. If the block has not been mined, this is <code class="inline">null</code>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">transaction</span><span class="symbol">.</span><span class="method">blockHash</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 > ></span><div class="anchors"></div></div><div class="body"><p>The hash of the block this transaction was mined in. If the block has not been mined, this is <code class="inline">null</code>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">transaction</span><span class="symbol">.</span><span class="method">timestamp</span> <span class="arrow">⇒</span> <span class="returns">number</span><div class="anchors"></div></div><div class="body"><p>The timestamp of the block this transaction was mined in. If the block has not been mined, this is <code class="inline">null</code>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">transaction</span><span class="symbol">.</span><span class="method">confirmations</span> <span class="arrow">⇒</span> <span class="returns">number</span><div class="anchors"></div></div><div class="body"><p>The number of blocks that have been mined (including the initial block) since this transaction was mined.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">transaction</span><span class="symbol">.</span><span class="method">raw</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a> ></span><div class="anchors"></div></div><div class="body"><p>The serialized transaction.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">transaction</span><span class="symbol">.</span><span class="method">wait</span><span class="symbol">(</span> <span class="symbol">[</span> <span class="param">confirms</span> = <span class="param">1</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< <a href="#/v5/api/providers/types/-%23-providers-TransactionReceipt">TransactionReceipt</a> ></span><div class="anchors"></div></div><div class="body"><p>Resolves to the <a href="#/v5/api/providers/types/-%23-providers-TransactionReceipt">TransactionReceipt</a> once the transaction has been included in the chain for <i>confirms</i> blocks. If <i>confirms</i> is 0, and the transaction has not been mined, <code class="inline">null</code> is returned.</p>
|
|
|
|
<p>If the transaction execution failed (i.e. the receipt status is <code class="inline">0</code>), a <a href="#/v5/api/utils/logger/-%23-errors--call-exception">CALL_EXCEPTION</a> Error will be rejected with the following properties:</p>
|
|
|
|
<p><ul><li><code class="inline">error.transaction</code> - the original transaction </li><li><code class="inline">error.transactionHash</code> - the hash of the transaction </li><li><code class="inline">error.receipt</code> - the actual receipt, with the status of <code class="inline">0</code> </li></ul></p>
|
|
|
|
</div></div><a name="/v5/api/providers/types/-%23-providers-TransactionReceipt"></a><a name="/v5/api/providers/types/-%23-types--transactions--providers-TransactionReceipt"></a><a name="/v5/api/providers/types/"></a><h3 class="show-anchors"><div>TransactionReceipt<div class="anchors"><a class="self" href="#/v5/api/providers/types/-%23-providers-TransactionReceipt"></a></div></div></h3>
|
|
<div class="property show-anchors"><div class="signature"><span class="path">receipt</span><span class="symbol">.</span><span class="method">to</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/address/-%23-address">Address</a> ></span><div class="anchors"></div></div><div class="body"><p>The address this transaction is to. This is <code class="inline">null</code> if the transaction was an <b>init transaction</b>, used to deploy a contract.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">receipt</span><span class="symbol">.</span><span class="method">from</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/address/-%23-address">Address</a> ></span><div class="anchors"></div></div><div class="body"><p>The address this transaction is from.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">receipt</span><span class="symbol">.</span><span class="method">contractAddress</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/address/-%23-address">Address</a> ></span><div class="anchors"></div></div><div class="body"><p>If this transaction has a <code class="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 <a href="#/v5/api/utils/address/-%23-utils-getContractAddress">getContractAddress</a> utility function can also be used with a <a href="#/v5/api/providers/types/-%23-providers-TransactionResponse">TransactionResponse</a> object, which requires the transaction nonce and the address of the sender.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">receipt</span><span class="symbol">.</span><span class="method">transactionIndex</span> <span class="arrow">⇒</span> <span class="returns">number</span><div class="anchors"></div></div><div class="body"><p>The index of this transaction in the list of transactions included in the block this transaction was mined in.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">receipt</span><span class="symbol">.</span><span class="method">root</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"></div></div><div class="body"><p>The intermediate state root of a receipt.</p>
|
|
|
|
<p>Only transactions included in blocks <b>before</b> the <a href="https://eips.ethereum.org/EIPS/eip-609">Byzantium Hard Fork</a> have this property, as it was replaced by the <code class="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><div class="property show-anchors"><div class="signature"><span class="path">receipt</span><span class="symbol">.</span><span class="method">gasUsed</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/bignumber/">BigNumber</a></span><div class="anchors"></div></div><div class="body"><p>The amount of gas actually used by this transaction.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">receipt</span><span class="symbol">.</span><span class="method">logsBloom</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a> ></span><div class="anchors"></div></div><div class="body"><p>A <a href="https://en.wikipedia.org/wiki/Bloom_filter">bloom-filter</a>, which includes all the addresses and topics included in any log in this transaction.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">receipt</span><span class="symbol">.</span><span class="method">blockHash</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 > ></span><div class="anchors"></div></div><div class="body"><p>The block hash of the block that this transaction was included in.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">receipt</span><span class="symbol">.</span><span class="method">transactionHash</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 > ></span><div class="anchors"></div></div><div class="body"><p>The transaction hash of this transaction.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">receipt</span><span class="symbol">.</span><span class="method">logs</span> <span class="arrow">⇒</span> <span class="returns">Array< <a href="#/v5/api/providers/types/-%23-providers-Log">Log</a> ></span><div class="anchors"></div></div><div class="body"><p>All the logs emitted by this transaction.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">receipt</span><span class="symbol">.</span><span class="method">blockNumber</span> <span class="arrow">⇒</span> <span class="returns">number</span><div class="anchors"></div></div><div class="body"><p>The block height (number) of the block that this transaction was included in.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">receipt</span><span class="symbol">.</span><span class="method">confirmations</span> <span class="arrow">⇒</span> <span class="returns">number</span><div class="anchors"></div></div><div class="body"><p>The number of blocks that have been mined since this transaction, including the actual block it was mined in.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">receipt</span><span class="symbol">.</span><span class="method">cumulativeGasUsed</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/bignumber/">BigNumber</a></span><div class="anchors"></div></div><div class="body"><p>For the block this transaction was included in, this is the sum of the gas 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><div class="property show-anchors"><div class="signature"><span class="path">receipt</span><span class="symbol">.</span><span class="method">byzantium</span> <span class="arrow">⇒</span> <span class="returns">boolean</span><div class="anchors"></div></div><div class="body"><p>This is true if the block is in a <a href="https://eips.ethereum.org/EIPS/eip-609">post-Byzantium Hard Fork</a> block.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">receipt</span><span class="symbol">.</span><span class="method">status</span> <span class="arrow">⇒</span> <span class="returns">boolean</span><div class="anchors"></div></div><div class="body"><p>The status of a transaction is 1 is successful or 0 if it was reverted. Only transactions included in blocks <a href="https://eips.ethereum.org/EIPS/eip-609">post-Byzantium Hard Fork</a> have this property.</p>
|
|
|
|
</div></div><div class="page-separator"></div><a name="/v5/api/signer/-%23-signers"></a><a name="/v5/api/signer/-%23-signers"></a><a name="/v5/api/signer/"></a><h1 class="show-anchors"><div>Signers<div class="anchors"><a class="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 depend 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><a href="#/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><a href="#/v5/api/providers/jsonrpc-provider/-%23-JsonRpcSigner">JsonRpcSigner</a>, which is connected to a <a href="#/v5/api/providers/jsonrpc-provider/">JsonRpcProvider</a> (or sub-class) and is acquired using <a href="#/v5/api/providers/jsonrpc-provider/-%23-JsonRpcProvider-getSigner">getSigner</a> </li></ul></p>
|
|
|
|
<a name="/v5/api/signer/-%23-Signer"></a><a name="/v5/api/signer/-%23-signers--Signer"></a><a name="/v5/api/signer/"></a><h2 class="show-anchors"><div>Signer<div class="anchors"><a class="self" href="#/v5/api/signer/-%23-Signer"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/abstract-signer/src.ts/index.ts#L58">source</a></div></div></h2><p>The <b>Signer</b> class is abstract and cannot be directly instantiated.</p>
|
|
|
|
<p>Instead use one of the concrete sub-classes, such as the <a href="#/v5/api/signer/-%23-Wallet">Wallet</a>, <a href="#/v5/api/signer/-%23-VoidSigner">VoidSigner</a> or <a href="#/v5/api/providers/jsonrpc-provider/-%23-JsonRpcSigner">JsonRpcSigner</a>.</p>
|
|
|
|
<a name="/v5/api/signer/-%23-Signer-connect"></a><div class="property show-anchors"><div class="signature"><span class="path">signer</span><span class="symbol">.</span><span class="method">connect</span><span class="symbol">(</span> <span class="param">provider</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/signer/-%23-Signer">Signer</a></span><div class="anchors"><a class="self" href="#/v5/api/signer/-%23-Signer-connect"></a></div></div><div class="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><a name="/v5/api/signer/-%23-Signer-getaddress"></a><div class="property show-anchors"><div class="signature"><span class="path">signer</span><span class="symbol">.</span><span class="method">getAddress</span><span class="symbol">(</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< string< <a href="#/v5/api/utils/address/-%23-address">Address</a> > ></span><div class="anchors"><a class="self" href="#/v5/api/signer/-%23-Signer-getaddress"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/abstract-signer/src.ts/index.ts#L81">source</a></div></div><div class="body"><p>Returns a Promise that resolves to the account address.</p>
|
|
|
|
<p>This is a Promise so that a <b>Signer</b> can be designed around an asynchronous source, such as hardware wallets.</p>
|
|
|
|
<p>Sub-classes <b>must</b> implement this.</p>
|
|
|
|
</div></div><a name="/v5/api/signer/-%23-Signer-isSigner"></a><div class="property show-anchors"><div class="signature"><span class="path">Signer</span><span class="symbol">.</span><span class="method">isSigner</span><span class="symbol">(</span> <span class="param">object</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">boolean</span><div class="anchors"><a class="self" href="#/v5/api/signer/-%23-Signer-isSigner"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/abstract-signer/src.ts/index.ts#L238">source</a></div></div><div class="body"><p>Returns true if an only if <i>object</i> is a <b>Signer</b>.</p>
|
|
|
|
</div></div><a name="/v5/api/signer/-%23-Signer--blockchain-methods"></a><a name="/v5/api/signer/-%23-signers--Signer--Signer--blockchain-methods"></a><a name="/v5/api/signer/"></a><h3 class="show-anchors"><div>Blockchain Methods<div class="anchors"><a class="self" href="#/v5/api/signer/-%23-Signer--blockchain-methods"></a></div></div></h3>
|
|
<a name="/v5/api/signer/-%23-Signer-getBalance"></a><div class="property show-anchors"><div class="signature"><span class="path">signer</span><span class="symbol">.</span><span class="method">getBalance</span><span class="symbol">(</span> <span class="symbol">[</span> <span class="param">blockTag</span> = "<span class="param">latest</span>" <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< <a href="#/v5/api/utils/bignumber/">BigNumber</a> ></span><div class="anchors"><a class="self" href="#/v5/api/signer/-%23-Signer-getBalance"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/abstract-signer/src.ts/index.ts#L97">source</a></div></div><div class="body"><p>Returns the balance of this wallet at <i>blockTag</i>.</p>
|
|
|
|
</div></div><a name="/v5/api/signer/-%23-Signer-getChainId"></a><div class="property show-anchors"><div class="signature"><span class="path">signer</span><span class="symbol">.</span><span class="method">getChainId</span><span class="symbol">(</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< number ></span><div class="anchors"><a class="self" href="#/v5/api/signer/-%23-Signer-getChainId"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/abstract-signer/src.ts/index.ts#L131">source</a></div></div><div class="body"><p>Returns the chain ID this wallet is connected to.</p>
|
|
|
|
</div></div><a name="/v5/api/signer/-%23-Signer-getGasPrice"></a><div class="property show-anchors"><div class="signature"><span class="path">signer</span><span class="symbol">.</span><span class="method">getGasPrice</span><span class="symbol">(</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< <a href="#/v5/api/utils/bignumber/">BigNumber</a> ></span><div class="anchors"><a class="self" href="#/v5/api/signer/-%23-Signer-getGasPrice"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/abstract-signer/src.ts/index.ts#L137">source</a></div></div><div class="body"><p>Returns the current gas price.</p>
|
|
|
|
</div></div><a name="/v5/api/signer/-%23-Signer-getTransactionCount"></a><div class="property show-anchors"><div class="signature"><span class="path">signer</span><span class="symbol">.</span><span class="method">getTransactionCount</span><span class="symbol">(</span> <span class="symbol">[</span> <span class="param">blockTag</span> = "<span class="param">latest</span>" <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< number ></span><div class="anchors"><a class="self" href="#/v5/api/signer/-%23-Signer-getTransactionCount"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/abstract-signer/src.ts/index.ts#L102">source</a></div></div><div class="body"><p>Returns the number of transactions this account has ever sent. This is the value required to be included in transactions as the <code class="inline">nonce</code>.</p>
|
|
|
|
</div></div><a name="/v5/api/signer/-%23-Signer-call"></a><div class="property show-anchors"><div class="signature"><span class="path">signer</span><span class="symbol">.</span><span class="method">call</span><span class="symbol">(</span> <span class="param">transactionRequest</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a> > ></span><div class="anchors"><a class="self" href="#/v5/api/signer/-%23-Signer-call"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/abstract-signer/src.ts/index.ts#L115">source</a></div></div><div class="body"><p>Returns the result of calling using the <i>transactionRequest</i>, with this account address being used as the <code class="inline">from</code> field.</p>
|
|
|
|
</div></div><a name="/v5/api/signer/-%23-Signer-estimateGas"></a><div class="property show-anchors"><div class="signature"><span class="path">signer</span><span class="symbol">.</span><span class="method">estimateGas</span><span class="symbol">(</span> <span class="param">transactionRequest</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< <a href="#/v5/api/utils/bignumber/">BigNumber</a> ></span><div class="anchors"><a class="self" href="#/v5/api/signer/-%23-Signer-estimateGas"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/abstract-signer/src.ts/index.ts#L108">source</a></div></div><div class="body"><p>Returns the result of estimating the cost to send the <i>transactionRequest</i>, with this account address being used as the <code class="inline">from</code> field.</p>
|
|
|
|
</div></div><a name="/v5/api/signer/-%23-Signer-resolveName"></a><div class="property show-anchors"><div class="signature"><span class="path">signer</span><span class="symbol">.</span><span class="method">resolveName</span><span class="symbol">(</span> <span class="param">ensName</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< string< <a href="#/v5/api/utils/address/-%23-address">Address</a> > ></span><div class="anchors"><a class="self" href="#/v5/api/signer/-%23-Signer-resolveName"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/abstract-signer/src.ts/index.ts#L142">source</a></div></div><div class="body"><p>Returns the address associated with the <i>ensName</i>.</p>
|
|
|
|
</div></div><a name="/v5/api/signer/-%23-Signer--signing-methods"></a><a name="/v5/api/signer/-%23-signers--Signer--Signer--signing-methods"></a><a name="/v5/api/signer/"></a><h3 class="show-anchors"><div>Signing<div class="anchors"><a class="self" href="#/v5/api/signer/-%23-Signer--signing-methods"></a></div></div></h3>
|
|
<a name="/v5/api/signer/-%23-Signer-signMessage"></a><div class="property show-anchors"><div class="signature"><span class="path">signer</span><span class="symbol">.</span><span class="method">signMessage</span><span class="symbol">(</span> <span class="param">message</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< string< <a href="#/v5/api/utils/bytes/-%23-signature-raw">RawSignature</a> > ></span><div class="anchors"><a class="self" href="#/v5/api/signer/-%23-Signer-signMessage"></a></div></div><div class="body"><p>This returns a Promise which resolves to the <a href="#/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><div class="definition container-box note"><div class="term">Note</div><div class="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 <a href="#/v5/api/utils/bytes/-%23-Bytes">Bytes</a> will it be treated as binary data.</p>
|
|
|
|
<p>For example, the string <code class="inline">"0x1234"</code> is 6 characters long (and in this case 6 bytes long). This is <b>not</b> equivalent to the array <code class="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 <a href="#/v5/api/utils/bytes/-%23-utils-arrayify">arrayify</a> utility function.</p>
|
|
|
|
</div></div>
|
|
<a name="/v5/api/signer/-%23-Signer-signTransaction"></a><div class="property show-anchors"><div class="signature"><span class="path">signer</span><span class="symbol">.</span><span class="method">signTransaction</span><span class="symbol">(</span> <span class="param">transactionRequest</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a> > ></span><div class="anchors"><a class="self" href="#/v5/api/signer/-%23-Signer-signTransaction"></a></div></div><div class="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><a name="/v5/api/signer/-%23-Signer-sendTransaction"></a><div class="property show-anchors"><div class="signature"><span class="path">signer</span><span class="symbol">.</span><span class="method">sendTransaction</span><span class="symbol">(</span> <span class="param">transactionRequest</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< <a href="#/v5/api/providers/types/-%23-providers-TransactionResponse">TransactionResponse</a> ></span><div class="anchors"><a class="self" href="#/v5/api/signer/-%23-Signer-sendTransaction"></a></div></div><div class="body"><p>This method populates the transactionRequest with missing fields, using <a href="#/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 <a href="#/v5/api/signer/-%23-VoidSigner">VoidSigner</a> or if the Wallet is offline and not connected to a <a href="#/v5/api/providers/provider/">Provider</a>.</p>
|
|
|
|
</div></div><a name="/v5/api/signer/-%23-Signer-signTypedData"></a><div class="property show-anchors"><div class="signature"><span class="path">signer</span><span class="symbol">.</span><span class="method">_signTypedData</span><span class="symbol">(</span> <span class="param">domain</span> <span class="symbol">,</span> <span class="param">types</span> <span class="symbol">,</span> <span class="param">value</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< string< <a href="#/v5/api/utils/bytes/-%23-signature-raw">RawSignature</a> > ></span><div class="anchors"><a class="self" href="#/v5/api/signer/-%23-Signer-signTypedData"></a></div></div><div class="body"><p>Signs the typed data <i>value</i> with <i>types</i> data structure for <i>domain</i> using the <a href="https://eips.ethereum.org/EIPS/eip-712">EIP-712</a> specification.</p>
|
|
|
|
</div></div><div class="definition container-box warning"><div class="term">Experimental feature (this method name will change)</div><div class="body"><p>This is still an experimental feature. If using it, please specify the <b>exact</b> version of ethers you are using (e.g. spcify <code class="inline">"5.0.18"</code>, <b>not</b> <code class="inline">"^5.0.18"</code>) as the method name will be renamed from <code class="inline">_signTypedData</code> to <code class="inline">signTypedData</code> once it has been used in the field a bit.</p>
|
|
|
|
</div></div><div class="code-title"><div>Typed Data Example</div></div><div class="code"><span class="comment">// All properties on a domain are optional
|
|
</span>const domain = {
|
|
name: 'Ether Mail',
|
|
version: '1',
|
|
chainId: 1,
|
|
verifyingContract: '0xCcCCccccCCCCcCCCCCCcCcCccCcCCCcCcccccccC'
|
|
};
|
|
|
|
<span class="comment">// The named list of all type definitions
|
|
</span>const types = {
|
|
Person: [
|
|
{ name: 'name', type: 'string' },
|
|
{ name: 'wallet', type: 'address' }
|
|
],
|
|
Mail: [
|
|
{ name: 'from', type: 'Person' },
|
|
{ name: 'to', type: 'Person' },
|
|
{ name: 'contents', type: 'string' }
|
|
]
|
|
};
|
|
|
|
<span class="comment">// The data to sign
|
|
</span>const value = {
|
|
from: {
|
|
name: 'Cow',
|
|
wallet: '0xCD2a3d9F938E13CD947Ec05AbC7FE734Df8DD826'
|
|
},
|
|
to: {
|
|
name: 'Bob',
|
|
wallet: '0xbBbBBBBbbBBBbbbBbbBbbbbBBbBbbbbBbBbbBBbB'
|
|
},
|
|
contents: 'Hello, Bob!'
|
|
};
|
|
|
|
|
|
const signature = await signer._signTypedData(domain, types, value);
|
|
<span class="result ok">// '0x463b9c9971d1a144507d2e905f4e98becd159139421a4bb8d3c9c2ed04eb401057dd0698d504fd6ca48829a3c8a7a98c1c961eae617096cb54264bbdd082e13d1c'
|
|
</span></div><a name="/v5/api/signer/-%23-Signer--subclassing"></a><a name="/v5/api/signer/-%23-signers--Signer--Signer--subclassing"></a><a name="/v5/api/signer/"></a><h3 class="show-anchors"><div>Sub-Classes<div class="anchors"><a class="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>
|
|
|
|
<p>A sub-class <b>must</b> extend Signer and <b>must</b> call <code class="inline">super()</code>.</p>
|
|
|
|
<a name="/v5/api/signer/-%23-Signer-checkTransaction"></a><div class="property show-anchors"><div class="signature"><span class="path">signer</span><span class="symbol">.</span><span class="method">checkTransaction</span><span class="symbol">(</span> <span class="param">transactionRequest</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/providers/types/-%23-providers-TransactionRequest">TransactionRequest</a></span><div class="anchors"><a class="self" href="#/v5/api/signer/-%23-Signer-checkTransaction"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/abstract-signer/src.ts/index.ts#L159">source</a></div></div><div class="body"><p>This is generally not required to be overridden, but may be 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 <code class="inline">call</code>, <code class="inline">estimateGas</code> and <code class="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 if valid <a href="#/v5/api/providers/types/-%23-providers-TransactionRequest">TransactionRequest</a> properties exist and adds <code class="inline">from</code> to the transaction if it does not exist.</p>
|
|
|
|
<p>If there is a <code class="inline">from</code> field it <b>must</b> be verified to be equal to the Signer's address.</p>
|
|
|
|
</div></div><a name="/v5/api/signer/-%23-Signer-populateTransaction"></a><div class="property show-anchors"><div class="signature"><span class="path">signer</span><span class="symbol">.</span><span class="method">populateTransaction</span><span class="symbol">(</span> <span class="param">transactionRequest</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< <a href="#/v5/api/providers/types/-%23-providers-TransactionRequest">TransactionRequest</a> ></span><div class="anchors"><a class="self" href="#/v5/api/signer/-%23-Signer-populateTransaction"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/abstract-signer/src.ts/index.ts#L190">source</a></div></div><div class="body"><p>This is generally not required to be overridden, but may be 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 <code class="inline">checkTransaction</code> and fill in any properties required for sending a transaction. The result should have all promises resolved; if needed the <a href="#/v5/api/utils/properties/-%23-utils-resolveproperties">resolveProperties</a> utility function can be used for this.</p>
|
|
|
|
<p>The default implementation calls <code class="inline">checkTransaction</code> and resolves to if it is an ENS name, adds <code class="inline">gasPrice</code>, <code class="inline">nonce</code>, <code class="inline">gasLimit</code> and <code class="inline">chainId</code> based on the related operations on Signer.</p>
|
|
|
|
</div></div><a name="/v5/api/signer/-%23-Wallet"></a><a name="/v5/api/signer/-%23-signers--Wallet"></a><a name="/v5/api/signer/"></a><h2 class="show-anchors"><div>Wallet<span class="inherits"> inherits <a href="#/v5/api/signer/-%23-ExternallyOwnedAccount">ExternallyOwnedAccount</a> and <a href="#/v5/api/signer/-%23-Signer">Signer</a></span><div class="anchors"><a class="self" href="#/v5/api/signer/-%23-Wallet"></a><a class="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 <a href="#/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>
|
|
|
|
<a name="/v5/api/signer/-%23-Wallet-constructor"></a><div class="property show-anchors"><div class="signature"><span class="modifier">new </span><span class="path">ethers</span><span class="symbol">.</span><span class="method">Wallet</span><span class="symbol">(</span> <span class="param">privateKey</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">provider</span> <span class="symbol">]</span> <span class="symbol">)</span><div class="anchors"><a class="self" href="#/v5/api/signer/-%23-Wallet-constructor"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/wallet/src.ts/index.ts#L40">source</a></div></div><div class="body"><p>Create a new Wallet instance for <i>privateKey</i> and optionally connected to the <i>provider</i>.</p>
|
|
|
|
</div></div><a name="/v5/api/signer/-%23-Wallet-createRandom"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">Wallet</span><span class="symbol">.</span><span class="method">createRandom</span><span class="symbol">(</span> <span class="symbol">[</span> <span class="param">options</span> = {} <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/signer/-%23-Wallet">Wallet</a></span><div class="anchors"><a class="self" href="#/v5/api/signer/-%23-Wallet-createRandom"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/wallet/src.ts/index.ts#L169">source</a></div></div><div class="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>
|
|
|
|
<p>Wallets created using this method will have a mnemonic.</p>
|
|
|
|
</div></div><a name="/v5/api/signer/-%23-Wallet-fromEncryptedJson"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">Wallet</span><span class="symbol">.</span><span class="method">fromEncryptedJson</span><span class="symbol">(</span> <span class="param">json</span> <span class="symbol">,</span> <span class="param">password</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">progress</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< <a href="#/v5/api/signer/-%23-Wallet">Wallet</a> ></span><div class="anchors"><a class="self" href="#/v5/api/signer/-%23-Wallet-fromEncryptedJson"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/wallet/src.ts/index.ts#L182">source</a></div></div><div class="body"><p>Create an instance from an encrypted JSON wallet.</p>
|
|
|
|
<p>If <i>progress</i> is provided it will be called during decryption with a value between 0 and 1 indicating the progress towards completion.</p>
|
|
|
|
</div></div><a name="/v5/api/signer/-%23-Wallet-fromEncryptedJsonSync"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">Wallet</span><span class="symbol">.</span><span class="method">fromEncryptedJsonSync</span><span class="symbol">(</span> <span class="param">json</span> <span class="symbol">,</span> <span class="param">password</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/signer/-%23-Wallet">Wallet</a></span><div class="anchors"><a class="self" href="#/v5/api/signer/-%23-Wallet-fromEncryptedJsonSync"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/wallet/src.ts/index.ts#L188">source</a></div></div><div class="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 <code class="inline">fromEncryptedJson</code> instead.</p>
|
|
|
|
</div></div><a name="/v5/api/signer/-%23-Wallet.fromMnemonic"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">Wallet</span><span class="symbol">.</span><span class="method">fromMnemonic</span><span class="symbol">(</span> <span class="param">mnemonic</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">path</span> <span class="symbol">,</span> <span class="symbol">[</span> <span class="param">wordlist</span> <span class="symbol">]</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/signer/-%23-Wallet">Wallet</a></span><div class="anchors"><a class="self" href="#/v5/api/signer/-%23-Wallet.fromMnemonic"></a></div></div><div class="body"><p>Create an instance from a mnemonic phrase.</p>
|
|
|
|
<p>If path is not specified, the Ethereum default path is used (i.e. <code class="inline">m/44'/60'/0'/0/0</code>).</p>
|
|
|
|
<p>If wordlist is not specified, the English Wordlist is used.</p>
|
|
|
|
</div></div><a name="/v5/api/signer/-%23-Wallet--properties"></a><a name="/v5/api/signer/-%23-signers--Wallet--Wallet--properties"></a><a name="/v5/api/signer/"></a><h3 class="show-anchors"><div>Properties<div class="anchors"><a class="self" href="#/v5/api/signer/-%23-Wallet--properties"></a></div></div></h3>
|
|
<div class="property show-anchors"><div class="signature"><span class="path">wallet</span><span class="symbol">.</span><span class="method">address</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/address/-%23-address">Address</a> ></span><div class="anchors"></div></div><div class="body"><p>The address for the account this Wallet represents.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">wallet</span><span class="symbol">.</span><span class="method">provider</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/providers/provider/">Provider</a></span><div class="anchors"></div></div><div class="body"><p>The provider this wallet is connected to, which will be used for any <a href="#/v5/api/signer/-%23-Signer--blockchain-methods">Blockchain Methods</a> methods. This can be null.</p>
|
|
|
|
</div></div><div class="definition container-box note"><div class="term">Note</div><div class="body"><p>A <b>Wallet</b> instance is immutable, so if you wish to change the Provider, you may use the <a href="#/v5/api/signer/-%23-Signer-connect">connect</a> method to create a new instance connected to the desired provider.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">wallet</span><span class="symbol">.</span><span class="method">publicKey</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 65 > ></span><div class="anchors"></div></div><div class="body"><p>The uncompressed public key for this Wallet represents.</p>
|
|
|
|
</div></div><a name="/v5/api/signer/-%23-Wallet--methods"></a><a name="/v5/api/signer/-%23-signers--Wallet--Wallet--methods"></a><a name="/v5/api/signer/"></a><h3 class="show-anchors"><div>Methods<div class="anchors"><a class="self" href="#/v5/api/signer/-%23-Wallet--methods"></a></div></div></h3>
|
|
<a name="/v5/api/signer/-%23-Wallet-encrypt"></a><div class="property show-anchors"><div class="signature"><span class="path">wallet</span><span class="symbol">.</span><span class="method">encrypt</span><span class="symbol">(</span> <span class="param">password</span> <span class="symbol">,</span> <span class="symbol">[</span> <span class="param">options</span> = {} <span class="symbol">,</span> <span class="symbol">[</span> <span class="param">progress</span> <span class="symbol">]</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< string ></span><div class="anchors"><a class="self" href="#/v5/api/signer/-%23-Wallet-encrypt"></a></div></div><div class="body"><p>Encrypt the wallet using <i>password</i> returning a Promise which resolves to a JSON wallet.</p>
|
|
|
|
<p>If <i>progress</i> is provided it will be called during decryption with a value between 0 and 1 indicating the progress towards completion.</p>
|
|
|
|
</div></div><div class="code-title"><div>Wallet Examples</div></div><div class="code"><span class="comment">// Create a wallet instance from a mnemonic...
|
|
</span>mnemonic = "announce room limb pattern dry unit scale effort smooth jazz weasel alcohol"
|
|
walletMnemonic = Wallet.fromMnemonic(mnemonic)
|
|
|
|
<span class="comment">// ...or from a private key
|
|
</span>walletPrivateKey = new Wallet(walletMnemonic.privateKey)
|
|
|
|
walletMnemonic.address === walletPrivateKey.address
|
|
<span class="result ok">// true
|
|
</span>
|
|
<span class="comment">// The address as a Promise per the Signer API
|
|
</span>walletMnemonic.getAddress()
|
|
<span class="result ok">// { Promise: '0x71CB05EE1b1F506fF321Da3dac38f25c0c9ce6E1' }
|
|
</span>
|
|
<span class="comment">// A Wallet address is also available synchronously
|
|
</span>walletMnemonic.address
|
|
<span class="result ok">// '0x71CB05EE1b1F506fF321Da3dac38f25c0c9ce6E1'
|
|
</span>
|
|
<span class="comment">// The internal cryptographic components
|
|
</span>walletMnemonic.privateKey
|
|
<span class="result ok">// '0x1da6847600b0ee25e9ad9a52abbd786dd2502fa4005dd5af9310b7cc7a3b25db'
|
|
</span>walletMnemonic.publicKey
|
|
<span class="result ok">// '0x04b9e72dfd423bcf95b3801ac93f4392be5ff22143f9980eb78b3a860c4843bfd04829ae61cdba4b3b1978ac5fc64f5cc2f4350e35a108a9c9a92a81200a60cd64'
|
|
</span>
|
|
<span class="comment">// The wallet mnemonic
|
|
</span>walletMnemonic.mnemonic
|
|
<span class="result ok">// {
|
|
</span><span class="result ok">// locale: 'en',
|
|
</span><span class="result ok">// path: "m/44'/60'/0'/0/0",
|
|
</span><span class="result ok">// phrase: 'announce room limb pattern dry unit scale effort smooth jazz weasel alcohol'
|
|
</span><span class="result ok">// }
|
|
</span>
|
|
<span class="comment">// Note: A wallet created with a private key does not
|
|
</span><span class="comment">// have a mnemonic (the derivation prevents it)
|
|
</span>walletPrivateKey.mnemonic
|
|
<span class="result ok">// null
|
|
</span>
|
|
<span class="comment">// Signing a message
|
|
</span>walletMnemonic.signMessage("Hello World")
|
|
<span class="result ok">// { Promise: '0x14280e5885a19f60e536de50097e96e3738c7acae4e9e62d67272d794b8127d31c03d9cd59781d4ee31fb4e1b893bd9b020ec67dfa65cfb51e2bdadbb1de26d91c' }
|
|
</span>
|
|
tx = {
|
|
to: "0x8ba1f109551bD432803012645Ac136ddd64DBA72",
|
|
value: utils.parseEther("1.0")
|
|
}
|
|
|
|
<span class="comment">// Signing a transaction
|
|
</span>walletMnemonic.signTransaction(tx)
|
|
<span class="result ok">// { Promise: '0xf865808080948ba1f109551bd432803012645ac136ddd64dba72880de0b6b3a7640000801ca0918e294306d177ab7bd664f5e141436563854ebe0a3e523b9690b4922bbb52b8a01181612cec9c431c4257a79b8c9f0c980a2c49bb5a0e6ac52949163eeb565dfc' }
|
|
</span>
|
|
<span class="comment">// The connect method returns a new instance of the
|
|
</span><span class="comment">// Wallet connected to a provider
|
|
</span>wallet = walletMnemonic.connect(provider)
|
|
|
|
<span class="comment">// Querying the network
|
|
</span>wallet.getBalance();
|
|
<span class="result ok">// { Promise: { BigNumber: "42" } }
|
|
</span>wallet.getTransactionCount();
|
|
<span class="result ok">// { Promise: 0 }
|
|
</span>
|
|
<span class="comment">// Sending ether
|
|
</span>wallet.sendTransaction(tx)
|
|
</div><a name="/v5/api/signer/-%23-VoidSigner"></a><a name="/v5/api/signer/-%23-signers--VoidSigner"></a><a name="/v5/api/signer/"></a><h2 class="show-anchors"><div>VoidSigner<span class="inherits"> inherits <a href="#/v5/api/signer/-%23-Signer">Signer</a></span><div class="anchors"><a class="self" href="#/v5/api/signer/-%23-VoidSigner"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/abstract-signer/src.ts/index.ts#L243">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 <code class="inline">call</code> operation will automatically have the provided address passed along during the execution.</p>
|
|
|
|
<div class="property show-anchors"><div class="signature"><span class="modifier">new </span><span class="path">ethers</span><span class="symbol">.</span><span class="method">VoidSigner</span><span class="symbol">(</span> <span class="param">address</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">provider</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/signer/-%23-VoidSigner">VoidSigner</a></span><div class="anchors"></div></div><div class="body"><p>Create a new instance of a <b>VoidSigner</b> for <i>address</i>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">voidSigner</span><span class="symbol">.</span><span class="method">address</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/address/-%23-address">Address</a> ></span><div class="anchors"></div></div><div class="body"><p>The address of this <b>VoidSigner</b>.</p>
|
|
|
|
</div></div><div class="code-title"><div>VoidSigner Pre-flight Example</div></div><div class="code">address = "0x8ba1f109551bD432803012645Ac136ddd64DBA72"
|
|
signer = new ethers.VoidSigner(address, provider)
|
|
|
|
<span class="comment">// The DAI token contract
|
|
</span>abi = [
|
|
"function balanceOf(address) view returns (uint)",
|
|
"function transfer(address, uint) returns (bool)"
|
|
]
|
|
contract = new ethers.Contract("dai.tokens.ethers.eth", abi, signer)
|
|
|
|
<span class="comment">// Get the number of tokens for this account
|
|
</span>tokens = await contract.balanceOf(signer.getAddress())
|
|
<span class="result ok">// { BigNumber: "198172622063578627973" }
|
|
</span>
|
|
//
|
|
<span class="comment">// Pre-flight (check for revert) on DAI from the signer
|
|
</span>//
|
|
<span class="comment">// Note: We do not have the private key at this point, this
|
|
</span><span class="comment">// simply allows us to check what would happen if we
|
|
</span><span class="comment">// did. This can be useful to check before prompting
|
|
</span><span class="comment">// a request in the UI
|
|
</span>//
|
|
|
|
<span class="comment">// This will pass since the token balance is available
|
|
</span>contract.callStatic.transfer("donations.ethers.eth", tokens)
|
|
<span class="result ok">// { Promise: true }
|
|
</span>
|
|
<span class="comment">// This will fail since it is greater than the token balance
|
|
</span>contract.callStatic.transfer("donations.ethers.eth", tokens.add(1))
|
|
<span class="result error">// Error: call revert exception (method="transfer(address,uint256)", errorSignature="Error(string)", errorArgs=["Dai/insufficient-balance"], reason="Dai/insufficient-balance", code=CALL_EXCEPTION, version=abi/5.0.12)
|
|
</span></div><a name="/v5/api/signer/-%23-ExternallyOwnedAccount"></a><a name="/v5/api/signer/-%23-signers--ExternallyOwnedAccount"></a><a name="/v5/api/signer/"></a><h2 class="show-anchors"><div>ExternallyOwnedAccount<div class="anchors"><a class="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>
|
|
|
|
<div class="property show-anchors"><div class="signature"><span class="path">eoa</span><span class="symbol">.</span><span class="method">address</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/address/-%23-address">Address</a> ></span><div class="anchors"></div></div><div class="body"><p>The <a href="#/v5/api/utils/address/-%23-address">Address</a> of this EOA.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">eoa</span><span class="symbol">.</span><span class="method">privateKey</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 > ></span><div class="anchors"></div></div><div class="body"><p>The privateKey of this EOA</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">eoa</span><span class="symbol">.</span><span class="method">mnemonic</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/hdnode/-%23-Mnemonic">Mnemonic</a></span><div class="anchors"></div></div><div class="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 HD extended keys.</p>
|
|
|
|
</div></div><div class="page-separator"></div><a name="/v5/api/contract/-%23-contracts"></a><a name="/v5/api/contract/-%23-contracts"></a><a name="/v5/api/contract/"></a><h1 class="show-anchors"><div>Contract Interaction<div class="anchors"><a class="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>
|
|
|
|
<p>A <b>ContractFactory</b> is an abstraction of a contract's <i>bytecode</i> and facilitates deploying a contract.</p>
|
|
|
|
<div class="toc"><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/api/contract/contract/">Contract</a></div><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/api/contract/contract-factory/">ContractFactory</a></div><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/api/contract/example/">Example: ERC-20 Contract</a></div></div><div class="page-separator"></div><a name="/v5/api/contract/contract/-%23-Contract"></a><a name="/v5/api/contract/contract/-%23-Contract"></a><a name="/v5/api/contract/contract/"></a><h1 class="show-anchors"><div>Contract<div class="anchors"><a class="self" href="#/v5/api/contract/contract/-%23-Contract"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/contracts/src.ts/index.ts#L574">source</a></div></div></h1><p>A <b>Contract</b> is an abstraction of code that has been deployed to the blockchain.</p>
|
|
|
|
<p>A Contract may be sent transactions, which will trigger its code to be run with the input of the transaction data.</p>
|
|
|
|
<a name="/v5/api/contract/contract/-%23-Contract--creating"></a><a name="/v5/api/contract/contract/-%23-Contract--Contract--creating"></a><a name="/v5/api/contract/contract/"></a><h2 class="show-anchors"><div>Creating Instances<div class="anchors"><a class="self" href="#/v5/api/contract/contract/-%23-Contract--creating"></a></div></div></h2>
|
|
<div class="property show-anchors"><div class="signature"><span class="modifier">new </span><span class="path">ethers</span><span class="symbol">.</span><span class="method">Contract</span><span class="symbol">(</span> <span class="param">address</span> <span class="symbol">,</span> <span class="param">abi</span> <span class="symbol">,</span> <span class="param">signerOrProvider</span> <span class="symbol">)</span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/contracts/src.ts/index.ts#L607">source</a></div></div><div class="body">
|
|
</div></div><a name="/v5/api/contract/contract/-%23-Contract-attach"></a><div class="property show-anchors"><div class="signature"><span class="path">contract</span><span class="symbol">.</span><span class="method">attach</span><span class="symbol">(</span> <span class="param">addressOrName</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/contract/contract/">Contract</a></span><div class="anchors"><a class="self" href="#/v5/api/contract/contract/-%23-Contract-attach"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/contracts/src.ts/index.ts#L833">source</a></div></div><div class="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><a name="/v5/api/contract/contract/-%23-Contract-connect"></a><div class="property show-anchors"><div class="signature"><span class="path">contract</span><span class="symbol">.</span><span class="method">connect</span><span class="symbol">(</span> <span class="param">providerOrSigner</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/contract/contract/">Contract</a></span><div class="anchors"><a class="self" href="#/v5/api/contract/contract/-%23-Contract-connect"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/contracts/src.ts/index.ts#L820">source</a></div></div><div class="body"><p>Returns a new instance of the Contract, but connected to <i>providerOrSigner</i>.</p>
|
|
|
|
<p>By passing in a <a href="#/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>
|
|
|
|
<p>By passing in a <a href="#/v5/api/signer/-%23-Signer">Signer</a>. this will return a <b>Contract</b> which will act on behalf of that signer.</p>
|
|
|
|
</div></div><a name="/v5/api/contract/contract/-%23-Contract--properties"></a><a name="/v5/api/contract/contract/-%23-Contract--Contract--properties"></a><a name="/v5/api/contract/contract/"></a><h2 class="show-anchors"><div>Properties<div class="anchors"><a class="self" href="#/v5/api/contract/contract/-%23-Contract--properties"></a></div></div></h2>
|
|
<div class="property show-anchors"><div class="signature"><span class="path">contract</span><span class="symbol">.</span><span class="method">address</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/address/-%23-address">Address</a> ></span><div class="anchors"></div></div><div class="body"><p>This is the address (or ENS name) the contract was constructed with.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">contract</span><span class="symbol">.</span><span class="method">resolvedAddress</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/address/-%23-address">Address</a> ></span><div class="anchors"></div></div><div class="body"><p>This is a promise that will resolve to the address the <b>Contract</b> object is attached to. If an <a href="#/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><div class="property show-anchors"><div class="signature"><span class="path">contract</span><span class="symbol">.</span><span class="method">deployTransaction</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/providers/types/-%23-providers-TransactionResponse">TransactionResponse</a></span><div class="anchors"></div></div><div class="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><div class="property show-anchors"><div class="signature"><span class="path">contract</span><span class="symbol">.</span><span class="method">interface</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/abi/interface/">Interface</a></span><div class="anchors"></div></div><div class="body"><p>This is the ABI as an <a href="#/v5/api/utils/abi/interface/">Interface</a>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">contract</span><span class="symbol">.</span><span class="method">provider</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/providers/provider/">Provider</a></span><div class="anchors"></div></div><div class="body"><p>If a provider was provided to the constructor, this is that provider. If a signer was provided that had a <a href="#/v5/api/providers/provider/">Provider</a>, this is that provider.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">contract</span><span class="symbol">.</span><span class="method">signer</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/signer/-%23-Signer">Signer</a></span><div class="anchors"></div></div><div class="body"><p>If a signer was provided to the constructor, this is that signer.</p>
|
|
|
|
</div></div><a name="/v5/api/contract/contract/-%23-Contract--methods"></a><a name="/v5/api/contract/contract/-%23-Contract--Contract--methods"></a><a name="/v5/api/contract/contract/"></a><h2 class="show-anchors"><div>Methods<div class="anchors"><a class="self" href="#/v5/api/contract/contract/-%23-Contract--methods"></a></div></div></h2>
|
|
<a name="/v5/api/contract/contract/-%23-Contract-deployed"></a><div class="property show-anchors"><div class="signature"><span class="path">contract</span><span class="symbol">.</span><span class="method">deployed</span><span class="symbol">(</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< <a href="#/v5/api/contract/contract/">Contract</a> ></span><div class="anchors"><a class="self" href="#/v5/api/contract/contract/-%23-Contract-deployed"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/contracts/src.ts/index.ts#L762">source</a></div></div><div class="body">
|
|
</div></div><a name="/v5/api/contract/contract/-%23-Contract-isIndexed"></a><div class="property show-anchors"><div class="signature"><span class="path">Contract</span><span class="symbol">.</span><span class="method">isIndexed</span><span class="symbol">(</span> <span class="param">value</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">boolean</span><div class="anchors"><a class="self" href="#/v5/api/contract/contract/-%23-Contract-isIndexed"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/contracts/src.ts/index.ts#L837">source</a></div></div><div class="body">
|
|
</div></div><a name="/v5/api/contract/contract/-%23-Contract--events"></a><a name="/v5/api/contract/contract/-%23-Contract--Contract--events"></a><a name="/v5/api/contract/contract/"></a><h2 class="show-anchors"><div>Events<div class="anchors"><a class="self" href="#/v5/api/contract/contract/-%23-Contract--events"></a></div></div></h2>
|
|
<a name="/v5/api/contract/contract/-%23-Contract-queryFilter"></a><div class="property show-anchors"><div class="signature"><span class="path">contract</span><span class="symbol">.</span><span class="method">queryFilter</span><span class="symbol">(</span> <span class="param">event</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">fromBlockOrBlockHash</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">toBlock</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< Array< Event > ></span><div class="anchors"><a class="self" href="#/v5/api/contract/contract/-%23-Contract-queryFilter"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/contracts/src.ts/index.ts#L976">source</a></div></div><div class="body"><p>Return Events that match the <i>event</i>.</p>
|
|
|
|
</div></div><a name="/v5/api/contract/contract/-%23-Contract-listenerCount"></a><div class="property show-anchors"><div class="signature"><span class="path">contract</span><span class="symbol">.</span><span class="method">listenerCount</span><span class="symbol">(</span> <span class="symbol">[</span> <span class="param">event</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">number</span><div class="anchors"><a class="self" href="#/v5/api/contract/contract/-%23-Contract-listenerCount"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/contracts/src.ts/index.ts#L1017">source</a></div></div><div class="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><a name="/v5/api/contract/contract/-%23-Contract-listeners"></a><div class="property show-anchors"><div class="signature"><span class="path">contract</span><span class="symbol">.</span><span class="method">listeners</span><span class="symbol">(</span> <span class="param">event</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Array< Listener ></span><div class="anchors"><a class="self" href="#/v5/api/contract/contract/-%23-Contract-listeners"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/contracts/src.ts/index.ts#L1027">source</a></div></div><div class="body"><p>Return a list of listeners that are subscribed to <i>event</i>.</p>
|
|
|
|
</div></div><a name="/v5/api/contract/contract/-%23-Contract-off"></a><div class="property show-anchors"><div class="signature"><span class="path">contract</span><span class="symbol">.</span><span class="method">off</span><span class="symbol">(</span> <span class="param">event</span> <span class="symbol">,</span> <span class="param">listener</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">this</span><div class="anchors"><a class="self" href="#/v5/api/contract/contract/-%23-Contract-off"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/contracts/src.ts/index.ts#L1063">source</a></div></div><div class="body"><p>Unsubscribe <i>listener</i> to <i>event</i>.</p>
|
|
|
|
</div></div><a name="/v5/api/contract/contract/-%23-Contract-on"></a><div class="property show-anchors"><div class="signature"><span class="path">contract</span><span class="symbol">.</span><span class="method">on</span><span class="symbol">(</span> <span class="param">event</span> <span class="symbol">,</span> <span class="param">listener</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">this</span><div class="anchors"><a class="self" href="#/v5/api/contract/contract/-%23-Contract-on"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/contracts/src.ts/index.ts#L995">source</a></div></div><div class="body"><p>Subscribe to <i>event</i> calling <i>listener</i> when the event occurs.</p>
|
|
|
|
</div></div><a name="/v5/api/contract/contract/-%23-Contract-once"></a><div class="property show-anchors"><div class="signature"><span class="path">contract</span><span class="symbol">.</span><span class="method">once</span><span class="symbol">(</span> <span class="param">event</span> <span class="symbol">,</span> <span class="param">listener</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">this</span><div class="anchors"><a class="self" href="#/v5/api/contract/contract/-%23-Contract-once"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/contracts/src.ts/index.ts#L1000">source</a></div></div><div class="body"><p>Subscribe once to <i>event</i> calling <i>listener</i> when the event occurs.</p>
|
|
|
|
</div></div><a name="/v5/api/contract/contract/-%23-Contract-removeAllListeners"></a><div class="property show-anchors"><div class="signature"><span class="path">contract</span><span class="symbol">.</span><span class="method">removeAllListeners</span><span class="symbol">(</span> <span class="symbol">[</span> <span class="param">event</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">this</span><div class="anchors"><a class="self" href="#/v5/api/contract/contract/-%23-Contract-removeAllListeners"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/contracts/src.ts/index.ts#L1043">source</a></div></div><div class="body"><p>Unsubscribe all listeners for <i>event</i>. If no event is provided, all events are unsubscribed.</p>
|
|
|
|
</div></div><a name="/v5/api/contract/contract/-%23-Contract--metaclass"></a><a name="/v5/api/contract/contract/-%23-Contract--Contract--metaclass"></a><a name="/v5/api/contract/contract/"></a><h2 class="show-anchors"><div>Meta-Class<div class="anchors"><a class="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>
|
|
|
|
<a name="/v5/api/contract/contract/-%23-Contract--readonly"></a><a name="/v5/api/contract/contract/-%23-Contract--Contract--metaclass--Contract--readonly"></a><a name="/v5/api/contract/contract/"></a><h3 class="show-anchors"><div>Read-Only Methods (constant)<div class="anchors"><a class="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>
|
|
|
|
<a name="/v5/api/contract/contract/-%23-Contract-functionsCall"></a><div class="property show-anchors"><div class="signature"><span class="path">contract</span><span class="symbol">.</span><span class="method">METHOD_NAME</span><span class="symbol">(</span> ...<span class="param">args</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">overrides</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< any ></span><div class="anchors"><a class="self" href="#/v5/api/contract/contract/-%23-Contract-functionsCall"></a></div></div><div class="body"><p>The type of the result depends on the ABI. If the method returns a single value, it will be returned directly, otherwise a <a href="#/v5/api/utils/abi/interface/-%23-Result">Result</a> object will be returned with each parameter available positionally and if the parameter is named, it will also be available by its name.</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 <code class="inline">int24</code> or <code class="inline">uint48</code>) a normal JavaScript number is used. Otherwise a <a href="#/v5/api/utils/bignumber/">BigNumber</a> is returned.</p>
|
|
|
|
<p>For bytes (both fixed length and dynamic), a <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a> is returned.</p>
|
|
|
|
<p>The <i>overrides</i> object for a read-only method may include any of:</p>
|
|
|
|
<p><ul><li><code class="inline">overrides.from</code> - the <code class="inline">msg.sender</code> (or <code class="inline">CALLER</code>) to use during the execution of the code </li><li><code class="inline">overrides.value</code> - the <code class="inline">msg.value</code> (or <code class="inline">CALLVALUE</code>) to use during the exectuiont of the code </li><li><code class="inline">overrides.gasPrice</code> - the price to pay per gas (theoretically); since there is no transaction, there is not going to be any fee charged, but the EVM still requires a value to report to <code class="inline">tx.gasprice</code> (or <code class="inline">GASPRICE</code>); <i>most developers will not require this</i> </li><li><code class="inline">overrides.gasLimit</code> - the amount of gas (theoretically) to allow a node to use during the execution of the code; since there is no transaction, there is not going to be any fee charged, but the EVM still processes gas metering so calls like <code class="inline">gasleft</code> (or <code class="inline">GAS</code>) report meaningful values </li><li><code class="inline">overrides.blockTag</code> - a block tag to simulate the execution at, which can be used for hypothetical historic analysis; note that many backends do not support this, or may require paid plans to access as the node database storage and processing requirements are much higher </li></ul></p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">contract</span><span class="symbol">.</span><span class="path">functions</span><span class="symbol">.</span><span class="method">METHOD_NAME</span><span class="symbol">(</span> ...<span class="param">args</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">overrides</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< <a href="#/v5/api/utils/abi/interface/-%23-Result">Result</a> ></span><div class="anchors"></div></div><div class="body"><p>The result will always be a <a href="#/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 <a href="#/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>
|
|
|
|
<p>Most developers should not require this.</p>
|
|
|
|
<p>The <i>overrides</i> are identical to the read-only operations above.</p>
|
|
|
|
</div></div><a name="/v5/api/contract/contract/-%23-Contract--write"></a><a name="/v5/api/contract/contract/-%23-Contract--Contract--metaclass--Contract--write"></a><a name="/v5/api/contract/contract/"></a><h3 class="show-anchors"><div>Write Methods (non-constant)<div class="anchors"><a class="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>
|
|
|
|
<a name="/v5/api/contract/contract/-%23-contract-functionsSend"></a><div class="property show-anchors"><div class="signature"><span class="path">contract</span><span class="symbol">.</span><span class="method">METHOD_NAME</span><span class="symbol">(</span> ...<span class="param">args</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">overrides</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< <a href="#/v5/api/providers/types/-%23-providers-TransactionResponse">TransactionResponse</a> ></span><div class="anchors"><a class="self" href="#/v5/api/contract/contract/-%23-contract-functionsSend"></a></div></div><div class="body"><p>Returns a <a href="#/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>
|
|
|
|
<p>The <i>overrides</i> object for write methods may include any of:</p>
|
|
|
|
<p><ul><li><code class="inline">overrides.gasPrice</code> - the price to pay per gas </li><li><code class="inline">overrides.gasLimit</code> - the limit on the amount of gas to allow the transaction to consume; any unused gas is returned at the gasPrice </li><li><code class="inline">overrides.value</code> - the amount of ether (in wei) to forward with the call </li><li><code class="inline">overrides.nonce</code> - the nonce to use for the <a href="#/v5/api/signer/-%23-Signer">Signer</a> </li></ul></p>
|
|
|
|
<p>If the <code class="inline">wait()</code> method on the returned <a href="#/v5/api/providers/types/-%23-providers-TransactionResponse">TransactionResponse</a> is called, there will be additional properties on the receipt:</p>
|
|
|
|
<p><ul><li><code class="inline">receipt.events</code> - an array of the logs, with additional properties (if the ABI included a description for the events) </li><li><code class="inline">receipt.events[n].args</code> - the parsed arguments </li><li><code class="inline">receipt.events[n].decode</code> - a method that can be used to parse the log topics and data (this was used to compute <code class="inline">args</code>) </li><li><code class="inline">receipt.events[n].event</code> - the name of the event </li><li><code class="inline">receipt.events[n].eventSignature</code> - the full signature of the event </li><li><code class="inline">receipt.removeListener()</code> - a method to remove the listener that trigger this event </li><li><code class="inline">receipt.getBlock()</code> - a method to return the <a href="#/v5/api/providers/types/-%23-providers-Block">Block</a> this event occurred in </li><li><code class="inline">receipt.getTransaction()</code> - a method to return the <a href="#/v5/api/providers/types/-%23-providers-TransactionResponse">Transaction</a> this event occurred in </li><li><code class="inline">receipt.getTransactionReceipt()</code> - a method to return the <a href="#/v5/api/providers/types/-%23-providers-TransactionReceipt">Transaction Receipt</a> this event occurred in </li></ul></p>
|
|
|
|
</div></div><a name="/v5/api/contract/contract/-%23-Contract--check"></a><a name="/v5/api/contract/contract/-%23-Contract--Contract--metaclass--Contract--check"></a><a name="/v5/api/contract/contract/"></a><h3 class="show-anchors"><div>Write Methods Analysis<div class="anchors"><a class="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>
|
|
|
|
<a name="/v5/api/contract/contract/-%23-contract-estimateGas"></a><div class="property show-anchors"><div class="signature"><span class="path">contract</span><span class="symbol">.</span><span class="path">estimateGas</span><span class="symbol">.</span><span class="method">METHOD_NAME</span><span class="symbol">(</span> ...<span class="param">args</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">overrides</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< <a href="#/v5/api/utils/bignumber/">BigNumber</a> ></span><div class="anchors"><a class="self" href="#/v5/api/contract/contract/-%23-contract-estimateGas"></a></div></div><div class="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>
|
|
|
|
<p>The <i>overrides</i> are identical to the overrides above for read-only or write methods, depending on the type of call of <i>METHOD_NAME</i>.</p>
|
|
|
|
</div></div><a name="/v5/api/contract/contract/-%23-contract-populateTransaction"></a><div class="property show-anchors"><div class="signature"><span class="path">contract</span><span class="symbol">.</span><span class="path">populateTransaction</span><span class="symbol">.</span><span class="method">METHOD_NAME</span><span class="symbol">(</span> ...<span class="param">args</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">overrides</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< <a href="#/v5/api/utils/transactions/-%23-UnsignedTransaction">UnsignedTx</a> ></span><div class="anchors"><a class="self" href="#/v5/api/contract/contract/-%23-contract-populateTransaction"></a></div></div><div class="body"><p>Returns an <a href="#/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>
|
|
|
|
<p>The <i>overrides</i> are identical to the overrides above for read-only or write methods, depending on the type of call of <i>METHOD_NAME</i>.</p>
|
|
|
|
</div></div><a name="/v5/api/contract/contract/-%23-contract-callStatic"></a><div class="property show-anchors"><div class="signature"><span class="path">contract</span><span class="symbol">.</span><span class="path">callStatic</span><span class="symbol">.</span><span class="method">METHOD_NAME</span><span class="symbol">(</span> ...<span class="param">args</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">overrides</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< any ></span><div class="anchors"><a class="self" href="#/v5/api/contract/contract/-%23-contract-callStatic"></a></div></div><div class="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>
|
|
|
|
<p>This does not actually change any state, but is free. This in some cases can be used to determine if a transaction will fail or succeed.</p>
|
|
|
|
<p>This otherwise functions the same as a <a href="#/v5/api/contract/contract/-%23-Contract--readonly">Read-Only Method</a>.</p>
|
|
|
|
<p>The <i>overrides</i> are identical to the read-only operations above.</p>
|
|
|
|
</div></div><a name="/v5/api/contract/contract/-%23-Contract--filters"></a><a name="/v5/api/contract/contract/-%23-Contract--Contract--metaclass--Contract--filters"></a><a name="/v5/api/contract/contract/"></a><h3 class="show-anchors"><div>Event Filters<div class="anchors"><a class="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 <a href="https://en.wikipedia.org/wiki/Bloom_filter">Bloom Filter</a>, allowing efficient searching for entries which match a filter.</p>
|
|
|
|
<div class="property show-anchors"><div class="signature"><span class="path">contract</span><span class="symbol">.</span><span class="path">filters</span><span class="symbol">.</span><span class="method">EVENT_NAME</span><span class="symbol">(</span> ...<span class="param">args</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Filter</span><div class="anchors"></div></div><div class="body"><p>Return a filter for <i>EVENT_NAME</i>, optionally filtering by additional constraints.</p>
|
|
|
|
<p>Only <code class="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><div class="page-separator"></div><a name="/v5/api/contract/contract-factory/-%23-ContractFactory"></a><a name="/v5/api/contract/contract-factory/-%23-ContractFactory"></a><a name="/v5/api/contract/contract-factory/"></a><h1 class="show-anchors"><div>ContractFactory<div class="anchors"><a class="self" href="#/v5/api/contract/contract-factory/-%23-ContractFactory"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/contracts/src.ts/index.ts#L1077">source</a></div></div></h1><p>To deploy a <a href="#/v5/api/contract/contract/">Contract</a>, additional information is needed that is not available on a Contract object itself.</p>
|
|
|
|
<p>Mainly, the bytecode (more specifically the initcode) of a contract is required.</p>
|
|
|
|
<p>The <b>Contract Factory</b> sends a special type of transaction, an initcode transaction (i.e. the <code class="inline">to</code> field is null, and the <code class="inline">data</code> field is the initcode) where the initcode will be evaluated and the result becomes the new code to be deployed as a new contract.</p>
|
|
|
|
<a name="/v5/api/contract/contract-factory/-%23-ContractFactory--creating"></a><a name="/v5/api/contract/contract-factory/-%23-ContractFactory--ContractFactory--creating"></a><a name="/v5/api/contract/contract-factory/"></a><h2 class="show-anchors"><div>Creating Instances<div class="anchors"><a class="self" href="#/v5/api/contract/contract-factory/-%23-ContractFactory--creating"></a></div></div></h2>
|
|
<div class="property show-anchors"><div class="signature"><span class="modifier">new </span><span class="path">ethers</span><span class="symbol">.</span><span class="method">ContractFactory</span><span class="symbol">(</span> <span class="param">interface</span> <span class="symbol">,</span> <span class="param">bytecode</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">signer</span> <span class="symbol">]</span> <span class="symbol">)</span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/contracts/src.ts/index.ts#L1083">source</a></div></div><div class="body"><p>Creates a new instance of a <b>ContractFactory</b> for the contract described by the <i>interface</i> and <i>bytecode</i> initcode.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">ContractFactory</span><span class="symbol">.</span><span class="method">fromSolidity</span><span class="symbol">(</span> <span class="param">compilerOutput</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">signer</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/contract/contract-factory/">ContractFactory</a></span><div class="anchors"></div></div><div class="body"><p>Consumes the output of the Solidity compiler, extracting the ABI and bytecode from it, allowing for the various formats the solc compiler has emitted over its life.</p>
|
|
|
|
</div></div><a name="/v5/api/contract/contract-factory/-%23-ContractFactory-connect"></a><div class="property show-anchors"><div class="signature"><span class="path">contractFactory</span><span class="symbol">.</span><span class="method">connect</span><span class="symbol">(</span> <span class="param">signer</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/contract/contract/">Contract</a></span><div class="anchors"><a class="self" href="#/v5/api/contract/contract-factory/-%23-ContractFactory-connect"></a></div></div><div class="body"><p>Returns a <b>new instance</b> of the ContractFactory with the same <i>interface</i> and <i>bytecode</i>, but with a different <i>signer</i>.</p>
|
|
|
|
</div></div><a name="/v5/api/contract/contract-factory/-%23-ContractFactory--properties"></a><a name="/v5/api/contract/contract-factory/-%23-ContractFactory--ContractFactory--properties"></a><a name="/v5/api/contract/contract-factory/"></a><h2 class="show-anchors"><div>Properties<div class="anchors"><a class="self" href="#/v5/api/contract/contract-factory/-%23-ContractFactory--properties"></a></div></div></h2>
|
|
<div class="property show-anchors"><div class="signature"><span class="path">contractFactory</span><span class="symbol">.</span><span class="method">interface</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/abi/interface/">Interface</a></span><div class="anchors"></div></div><div class="body"><p>The <a href="#/v5/api/contract/contract/">Contract</a> interface.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">contractFactory</span><span class="symbol">.</span><span class="method">bytecode</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a> ></span><div class="anchors"></div></div><div class="body"><p>The bytecode (i.e. initcode) that this <b>ContractFactory</b> will use to deploy the Contract.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">contractFactory</span><span class="symbol">.</span><span class="method">signer</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/signer/-%23-Signer">Signer</a></span><div class="anchors"></div></div><div class="body"><p>The <a href="#/v5/api/signer/-%23-Signer">Signer</a> (if any) this ContractFactory will use to deploy instances of the Contract to the Blockchain.</p>
|
|
|
|
</div></div><a name="/v5/api/contract/contract-factory/-%23-ContractFactory--methods"></a><a name="/v5/api/contract/contract-factory/-%23-ContractFactory--ContractFactory--methods"></a><a name="/v5/api/contract/contract-factory/"></a><h2 class="show-anchors"><div>Methods<div class="anchors"><a class="self" href="#/v5/api/contract/contract-factory/-%23-ContractFactory--methods"></a></div></div></h2>
|
|
<a name="/v5/api/contract/contract-factory/-%23-ContractFactory-attach"></a><div class="property show-anchors"><div class="signature"><span class="path">contractFactory</span><span class="symbol">.</span><span class="method">attach</span><span class="symbol">(</span> <span class="param">address</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/contract/contract/">Contract</a></span><div class="anchors"><a class="self" href="#/v5/api/contract/contract-factory/-%23-ContractFactory-attach"></a></div></div><div class="body"><p>Return an instance of a <a href="#/v5/api/contract/contract/">Contract</a> attached to <i>address</i>. This is the same as using the <a href="#/v5/api/contract/contract/-%23-Contract--creating">Contract constructor</a> with <i>address</i> and this the <i>interface</i> and <i>signerOrProvider</i> passed in when creating the ContractFactory.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">contractFactory</span><span class="symbol">.</span><span class="method">getDeployTransaction</span><span class="symbol">(</span> ...<span class="param">args</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">overrides</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/transactions/-%23-UnsignedTransaction">UnsignedTransaction</a></span><div class="anchors"></div></div><div class="body"><p>Returns the unsigned transaction which would deploy this Contract with <i>args</i> passed to the Contract's constructor.</p>
|
|
|
|
<p>If the optional <i>overrides</i> is specified, they can be used to override the endowment <code class="inline">value</code>, transaction <code class="inline">nonce</code>, <code class="inline">gasLimit</code> or <code class="inline">gasPrice</code>.</p>
|
|
|
|
</div></div><a name="/v5/api/contract/contract-factory/-%23-ContractFactory-deploy"></a><div class="property show-anchors"><div class="signature"><span class="path">contractFactory</span><span class="symbol">.</span><span class="method">deploy</span><span class="symbol">(</span> ...<span class="param">args</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">overrides</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< <a href="#/v5/api/contract/contract/">Contract</a> ></span><div class="anchors"><a class="self" href="#/v5/api/contract/contract-factory/-%23-ContractFactory-deploy"></a></div></div><div class="body"><p>Uses the signer to deploy the Contract with <i>args</i> passed into the constructor and returns 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 <code class="inline">contract.deployTransaction</code>, and no interactions should be made until the transaction is mined.</p>
|
|
|
|
<p>If the optional <i>overrides</i> is specified, they can be used to override the endowment <code class="inline">value</code>, transaction <code class="inline">nonce</code>, <code class="inline">gasLimit</code> or <code class="inline">gasPrice</code>.</p>
|
|
|
|
</div></div><div class="code-title"><div>Deploying a Contract</div></div><div class="code"><span class="comment">// If your contract constructor requires parameters, the ABI
|
|
</span><span class="comment">// must include the constructor
|
|
</span>const abi = [
|
|
"constructor(address owner, uint256 initialValue)",
|
|
"function value() view returns (uint)"
|
|
];
|
|
|
|
<span class="comment">// The factory we use for deploying contracts
|
|
</span>factory = new ContractFactory(abi, bytecode, signer)
|
|
|
|
<span class="comment">// Deploy an instance of the contract
|
|
</span>contract = await factory.deploy("ricmoo.eth", 42);
|
|
|
|
<span class="comment">// The address is available immediately, but the contract
|
|
</span><span class="comment">// is NOT deployed yet
|
|
</span>contract.address
|
|
<span class="result ok">// '0x26E9685C018Bf3A401DFA632827e7e6C7D96b1C0'
|
|
</span>
|
|
<span class="comment">// The transaction that the signer sent to deploy
|
|
</span>contract.deployTransaction
|
|
<span class="result ok">// {
|
|
</span><span class="result ok">// blockHash: null,
|
|
</span><span class="result ok">// blockNumber: null,
|
|
</span><span class="result ok">// chainId: 1337,
|
|
</span><span class="result ok">// confirmations: 0,
|
|
</span><span class="result ok">// creates: '0x26E9685C018Bf3A401DFA632827e7e6C7D96b1C0',
|
|
</span><span class="result ok">// data: '0x608060405234801561001057600080fd5b5060405161012e38038061012e8339818101604052604081101561003357600080fd5b81019080805190602001909291908051906020019092919050505081600160006101000a81548173ffffffffffffffffffffffffffffffffffffffff021916908373ffffffffffffffffffffffffffffffffffffffff1602179055508060008190555050506088806100a66000396000f3fe6080604052348015600f57600080fd5b506004361060285760003560e01c80633fa4f24514602d575b600080fd5b60336049565b6040518082815260200191505060405180910390f35b6000805490509056fea2646970667358221220926465385af0e8706644e1ff3db7161af699dc063beaadd55405f2ccd6478d7564736f6c63430007040033000000000000000000000000ab7c8803962c0f2f5bbbe3fa8bf41cd82aa1923c000000000000000000000000000000000000000000000000000000000000002a',
|
|
</span><span class="result ok">// from: '0xf3e6942b256A60B596B24F633caE8aDB4983fCA6',
|
|
</span><span class="result ok">// gasLimit: { BigNumber: "126462" },
|
|
</span><span class="result ok">// gasPrice: { BigNumber: "1" },
|
|
</span><span class="result ok">// hash: '0x4037630fdadbbe0aac0bf90eba61118e35ee5fc28329e2134bb2bad0bfc12684',
|
|
</span><span class="result ok">// nonce: 1,
|
|
</span><span class="result ok">// r: '0xc3bb79ea4600864cd110fe74d31d38bb3702c327fd5aef9feddf66903cc87a4f',
|
|
</span><span class="result ok">// s: '0x35cc2ffe352c02b5fcfbbcd2e348001af670f64438d7a9b2c34756ec293a0784',
|
|
</span><span class="result ok">// to: null,
|
|
</span><span class="result ok">// transactionIndex: null,
|
|
</span><span class="result ok">// v: 2709,
|
|
</span><span class="result ok">// value: { BigNumber: "0" },
|
|
</span><span class="result ok">// wait: [Function]
|
|
</span><span class="result ok">// }
|
|
</span>
|
|
<span class="comment">// Wait until the transaction is mined (i.e. contract is deployed)
|
|
</span><span class="comment">// - returns the receipt
|
|
</span><span class="comment">// - throws on failure (the reciept is on the error)
|
|
</span>contract.deployTransaction.wait()
|
|
<span class="result ok">// { Promise: {
|
|
</span><span class="result ok">// blockHash: '0x1715de2bdfec15a7f64fb79a8254699274be6776df244d24a04945a3218543e6',
|
|
</span><span class="result ok">// blockNumber: 2,
|
|
</span><span class="result ok">// byzantium: true,
|
|
</span><span class="result ok">// confirmations: 1,
|
|
</span><span class="result ok">// contractAddress: '0x26E9685C018Bf3A401DFA632827e7e6C7D96b1C0',
|
|
</span><span class="result ok">// cumulativeGasUsed: { BigNumber: "126462" },
|
|
</span><span class="result ok">// from: '0xf3e6942b256A60B596B24F633caE8aDB4983fCA6',
|
|
</span><span class="result ok">// gasUsed: { BigNumber: "126462" },
|
|
</span><span class="result ok">// logs: [],
|
|
</span><span class="result ok">// logsBloom: '0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000',
|
|
</span><span class="result ok">// status: 1,
|
|
</span><span class="result ok">// to: null,
|
|
</span><span class="result ok">// transactionHash: '0x4037630fdadbbe0aac0bf90eba61118e35ee5fc28329e2134bb2bad0bfc12684',
|
|
</span><span class="result ok">// transactionIndex: 0
|
|
</span><span class="result ok">// } }
|
|
</span>
|
|
<span class="comment">// Now the contract is safe to interact with
|
|
</span>contract.value()
|
|
<span class="result ok">// { Promise: { BigNumber: "42" } }
|
|
</span></div><div class="page-separator"></div><a name="/v5/api/contract/example/-%23-example-erc-20-contract"></a><a name="/v5/api/contract/example/"></a><h1 class="show-anchors"><div>Example: ERC-20 Contract<div class="anchors"><a class="self" href="#/v5/api/contract/example/-%23-example-erc-20-contract"></a></div></div></h1>
|
|
<a name="/v5/api/contract/example/-%23-example-erc-20-contract--connecting-to-a-contract"></a><a name="/v5/api/contract/example/"></a><h2 class="show-anchors"><div>Connecting to a Contract<div class="anchors"><a class="self" href="#/v5/api/contract/example/-%23-example-erc-20-contract--connecting-to-a-contract"></a></div></div></h2>
|
|
<div class="code-title"><div>A simple ERC-20 contract</div></div><div class="code"><span class="comment">// A Human-Readable ABI; any supported ABI format could be used
|
|
</span>const abi = [
|
|
<span class="comment"> // Read-Only Functions
|
|
</span> "function balanceOf(address owner) view returns (uint256)",
|
|
"function decimals() view returns (uint8)",
|
|
"function symbol() view returns (string)",
|
|
|
|
<span class="comment"> // Authenticated Functions
|
|
</span> "function transfer(address to, uint amount) returns (boolean)",
|
|
|
|
<span class="comment"> // Events
|
|
</span> "event Transfer(address indexed from, address indexed to, uint amount)"
|
|
];
|
|
|
|
<span class="comment">// This can be an address or an ENS name
|
|
</span>const address = "dai.tokens.ethers.eth";
|
|
|
|
<span class="comment">// An example Provider
|
|
</span>const provider = ethers.getDefaultProvider();
|
|
|
|
<span class="comment">// An example Signer
|
|
</span>const signer = ethers.Wallet.createRandom().connect(provider);
|
|
|
|
<span class="comment">// Read-Only; By connecting to a Provider, allows:
|
|
</span><span class="comment">// - Any constant function
|
|
</span><span class="comment">// - Querying Filters
|
|
</span><span class="comment">// - Populating Unsigned Transactions for non-constant methods
|
|
</span><span class="comment">// - Estimating Gas for non-constant (as an anonymous sender)
|
|
</span><span class="comment">// - Static Calling non-constant methods (as anonymous sender)
|
|
</span>const erc20 = new ethers.Contract(address, abi, provider);
|
|
|
|
<span class="comment">// Read-Write; By connecting to a Signer, allows:
|
|
</span><span class="comment">// - Everything from Read-Only (except as Signer, not anonymous)
|
|
</span><span class="comment">// - Sending transactions for non-constant functions
|
|
</span>const erc20_rw = new ethers.Contract(address, abi, signer)
|
|
</div><a name="/v5/api/contract/example/-%23-example-erc-20-contract--connecting-to-a-contract--erc20contract"></a><a name="/v5/api/contract/example/"></a><h3 class="show-anchors"><div>ERC20Contract<span class="inherits"> inherits <a href="#/v5/api/contract/contract/">Contract</a></span><div class="anchors"><a class="self" href="#/v5/api/contract/example/-%23-example-erc-20-contract--connecting-to-a-contract--erc20contract"></a></div></div></h3>
|
|
<div class="property show-anchors"><div class="signature"><span class="modifier">new </span><span class="path">ethers</span><span class="symbol">.</span><span class="method">Contract</span><span class="symbol">(</span> <span class="param">address</span> <span class="symbol">,</span> <span class="param">abi</span> <span class="symbol">,</span> <span class="param">providerOrSigner</span> <span class="symbol">)</span><div class="anchors"></div></div><div class="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><a name="/v5/api/contract/example/-%23-example-erc-20-contract--properties"></a><a name="/v5/api/contract/example/"></a><h2 class="show-anchors"><div>Properties<span class="inherits">(inheritted from <a href="#/v5/api/contract/contract/">Contract</a>)</span><div class="anchors"><a class="self" href="#/v5/api/contract/example/-%23-example-erc-20-contract--properties"></a></div></div></h2>
|
|
<div class="property show-anchors"><div class="signature"><span class="path">erc20</span><span class="symbol">.</span><span class="method">address</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/address/-%23-address">Address</a> ></span><div class="anchors"></div></div><div class="body"><p>This is the address (or ENS name) the contract was constructed with.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">erc20</span><span class="symbol">.</span><span class="method">resolvedAddress</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/address/-%23-address">Address</a> ></span><div class="anchors"></div></div><div class="body"><p>This is a promise that will resolve to the address the <b>Contract</b> object is attached to. If an <a href="#/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><div class="property show-anchors"><div class="signature"><span class="path">erc20</span><span class="symbol">.</span><span class="method">deployTransaction</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/providers/types/-%23-providers-TransactionResponse">TransactionResponse</a></span><div class="anchors"></div></div><div class="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><div class="property show-anchors"><div class="signature"><span class="path">erc20</span><span class="symbol">.</span><span class="method">interface</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/abi/interface/">Interface</a></span><div class="anchors"></div></div><div class="body"><p>This is the ABI as an <a href="#/v5/api/utils/abi/interface/">Interface</a>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">erc20</span><span class="symbol">.</span><span class="method">provider</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/providers/provider/">Provider</a></span><div class="anchors"></div></div><div class="body"><p>If a provider was provided to the constructor, this is that provider. If a signer was provided that had a <a href="#/v5/api/providers/provider/">Provider</a>, this is that provider.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">erc20</span><span class="symbol">.</span><span class="method">signer</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/signer/-%23-Signer">Signer</a></span><div class="anchors"></div></div><div class="body"><p>If a signer was provided to the constructor, this is that signer.</p>
|
|
|
|
</div></div><a name="/v5/api/contract/example/-%23-example-erc-20-contract--methods"></a><a name="/v5/api/contract/example/"></a><h2 class="show-anchors"><div>Methods<span class="inherits">(inheritted from <a href="#/v5/api/contract/contract/">Contract</a>)</span><div class="anchors"><a class="self" href="#/v5/api/contract/example/-%23-example-erc-20-contract--methods"></a></div></div></h2>
|
|
<div class="property show-anchors"><div class="signature"><span class="path">erc20</span><span class="symbol">.</span><span class="method">attach</span><span class="symbol">(</span> <span class="param">addressOrName</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/contract/contract/">Contract</a></span><div class="anchors"></div></div><div class="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><div class="property show-anchors"><div class="signature"><span class="path">erc20</span><span class="symbol">.</span><span class="method">connect</span><span class="symbol">(</span> <span class="param">providerOrSigner</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/contract/contract/">Contract</a></span><div class="anchors"></div></div><div class="body"><p>Returns a new instance of the Contract, but connected to <i>providerOrSigner</i>.</p>
|
|
|
|
<p>By passing in a <a href="#/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>
|
|
|
|
<p>By passing in a <a href="#/v5/api/signer/-%23-Signer">Signer</a>. this will return a <b>Contract</b> which will act on behalf of that signer.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">erc20</span><span class="symbol">.</span><span class="method">deployed</span><span class="symbol">(</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< Contract ></span><div class="anchors"></div></div><div class="body">
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">Contract</span><span class="symbol">.</span><span class="method">isIndexed</span><span class="symbol">(</span> <span class="param">value</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">boolean</span><div class="anchors"></div></div><div class="body">
|
|
</div></div><a name="/v5/api/contract/example/-%23-erc20-events"></a><a name="/v5/api/contract/example/-%23-example-erc-20-contract--erc20-events"></a><a name="/v5/api/contract/example/"></a><h2 class="show-anchors"><div>Events<span class="inherits">(inheritted from <a href="#/v5/api/contract/contract/">Contract</a>)</span><div class="anchors"><a class="self" href="#/v5/api/contract/example/-%23-erc20-events"></a></div></div></h2>
|
|
<a name="/v5/api/contract/example/-%23-erc20-queryfilter"></a><div class="property show-anchors"><div class="signature"><span class="path">erc20</span><span class="symbol">.</span><span class="method">queryFilter</span><span class="symbol">(</span> <span class="param">event</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">fromBlockOrBlockHash</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">toBlock</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< Array< Event > ></span><div class="anchors"><a class="self" href="#/v5/api/contract/example/-%23-erc20-queryfilter"></a></div></div><div class="body"><p>Return Events that match the <i>event</i>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">erc20</span><span class="symbol">.</span><span class="method">listenerCount</span><span class="symbol">(</span> <span class="symbol">[</span> <span class="param">event</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">number</span><div class="anchors"></div></div><div class="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><div class="property show-anchors"><div class="signature"><span class="path">erc20</span><span class="symbol">.</span><span class="method">listeners</span><span class="symbol">(</span> <span class="param">event</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Array< Listener ></span><div class="anchors"></div></div><div class="body"><p>Return a list of listeners that are subscribed to <i>event</i>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">erc20</span><span class="symbol">.</span><span class="method">off</span><span class="symbol">(</span> <span class="param">event</span> <span class="symbol">,</span> <span class="param">listener</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">this</span><div class="anchors"></div></div><div class="body"><p>Unsubscribe <i>listener</i> to <i>event</i>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">erc20</span><span class="symbol">.</span><span class="method">on</span><span class="symbol">(</span> <span class="param">event</span> <span class="symbol">,</span> <span class="param">listener</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">this</span><div class="anchors"></div></div><div class="body"><p>Subscribe to <i>event</i> calling <i>listener</i> when the event occurs.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">erc20</span><span class="symbol">.</span><span class="method">once</span><span class="symbol">(</span> <span class="param">event</span> <span class="symbol">,</span> <span class="param">listener</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">this</span><div class="anchors"></div></div><div class="body"><p>Subscribe once to <i>event</i> calling <i>listener</i> when the event occurs.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">erc20</span><span class="symbol">.</span><span class="method">removeAllListeners</span><span class="symbol">(</span> <span class="symbol">[</span> <span class="param">event</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">this</span><div class="anchors"></div></div><div class="body"><p>Unsubscribe all listeners for <i>event</i>. If no event is provided, all events are unsubscribed.</p>
|
|
|
|
</div></div><a name="/v5/api/contract/example/-%23-example-erc-20-contract--meta-class-methods"></a><a name="/v5/api/contract/example/"></a><h2 class="show-anchors"><div>Meta-Class Methods<span class="inherits">(added at Runtime)</span><div class="anchors"><a class="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>
|
|
|
|
<div class="property show-anchors"><div class="signature"><span class="path">erc20</span><span class="symbol">.</span><span class="method">decimals</span><span class="symbol">(</span> <span class="symbol">[</span> <span class="param">overrides</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< number ></span><div class="anchors"></div></div><div class="body"><p>Returns the number of decimal places used by this ERC-20 token. This can be used with <a href="#/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><div class="property show-anchors"><div class="signature"><span class="path">erc20</span><span class="symbol">.</span><span class="method">getBalance</span><span class="symbol">(</span> <span class="param">owner</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">overrides</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< <a href="#/v5/api/utils/bignumber/">BigNumber</a> ></span><div class="anchors"></div></div><div class="body"><p>Returns the balance of <i>owner</i> for this ERC-20 token.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">erc20</span><span class="symbol">.</span><span class="method">symbol</span><span class="symbol">(</span> <span class="symbol">[</span> <span class="param">overrides</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< string ></span><div class="anchors"></div></div><div class="body"><p>Returns the symbol of the token.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">erc20_rw</span><span class="symbol">.</span><span class="method">transfer</span><span class="symbol">(</span> <span class="param">target</span> <span class="symbol">,</span> <span class="param">amount</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">overrides</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< <a href="#/v5/api/providers/types/-%23-providers-TransactionResponse">TransactionResponse</a> ></span><div class="anchors"></div></div><div class="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 <code class="inline">transfer</code> function have access to this result, which is why it is possible.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">erc20</span><span class="symbol">.</span><span class="path">callStatic</span><span class="symbol">.</span><span class="method">transfer</span><span class="symbol">(</span> <span class="param">target</span> <span class="symbol">,</span> <span class="param">amount</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">overrides</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< boolean ></span><div class="anchors"></div></div><div class="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><div class="property show-anchors"><div class="signature"><span class="path">erc20</span><span class="symbol">.</span><span class="path">estimateGas</span><span class="symbol">.</span><span class="method">transfer</span><span class="symbol">(</span> <span class="param">target</span> <span class="symbol">,</span> <span class="param">amount</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">overrides</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< <a href="#/v5/api/utils/bignumber/">BigNumber</a> ></span><div class="anchors"></div></div><div class="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><div class="property show-anchors"><div class="signature"><span class="path">erc20</span><span class="symbol">.</span><span class="path">populateTransaction</span><span class="symbol">.</span><span class="method">transfer</span><span class="symbol">(</span> <span class="param">target</span> <span class="symbol">,</span> <span class="param">amount</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">overrides</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< <a href="#/v5/api/utils/transactions/-%23-UnsignedTransaction">UnsignedTx</a> ></span><div class="anchors"></div></div><div class="body"><p>Returns an <a href="#/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><div class="definition container-box note"><div class="term">Note on Estimating and Static Calling</div><div class="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><a name="/v5/api/contract/example/-%23-example-erc-20-contract--meta-class-filters"></a><a name="/v5/api/contract/example/"></a><h2 class="show-anchors"><div>Meta-Class Filters<span class="inherits">(added at Runtime)</span><div class="anchors"><a class="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>
|
|
|
|
<div class="property show-anchors"><div class="signature"><span class="path">erc20</span><span class="symbol">.</span><span class="path">filters</span><span class="symbol">.</span><span class="method">Transfer</span><span class="symbol">(</span> <span class="symbol">[</span> <span class="param">fromAddress</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">toAddress</span> <span class="symbol">]</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Filter</span><div class="anchors"></div></div><div class="body"><p>Returns a new Filter which can be used to <a href="#/v5/api/contract/example/-%23-erc20-queryfilter">query</a> or to <a href="#/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><div class="page-separator"></div><a name="/v5/api/utils/-%23-utilities"></a><a name="/v5/api/utils/"></a><h1 class="show-anchors"><div>Utilities<div class="anchors"><a class="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>
|
|
|
|
<div class="toc"><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/api/utils/abi/">Application Binary Interface</a></div><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/api/utils/address/">Addresses</a></div><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/api/utils/bignumber/">BigNumber</a></div><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/api/utils/bytes/">Byte Manipulation</a></div><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/api/utils/constants/">Constants</a></div><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/api/utils/display-logic/">Display Logic and Input</a></div><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/api/utils/encoding/">Encoding Utilities</a></div><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/api/utils/fixednumber/">FixedNumber</a></div><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/api/utils/hashing/">Hashing Algorithms</a></div><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/api/utils/hdnode/">HD Wallet</a></div><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/api/utils/logger/">Logging</a></div><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/api/utils/properties/">Property Utilities</a></div><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/api/utils/signing-key/">Signing Key</a></div><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/api/utils/strings/">Strings</a></div><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/api/utils/transactions/">Transactions</a></div><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/api/utils/web/">Web Utilities</a></div><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/api/utils/wordlists/">Wordlists</a></div></div><div class="page-separator"></div><a name="/v5/api/utils/abi/-%23-application-binary-interface"></a><a name="/v5/api/utils/abi/"></a><h1 class="show-anchors"><div>Application Binary Interface<div class="anchors"><a class="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 <a href="#/v5/api/utils/abi/fragments/-%23-Fragment">Fragments</a> which specify how to interact with various components of a Contract.</p>
|
|
|
|
<p>An <a href="#/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 <a href="#/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>
|
|
|
|
<div class="toc"><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/api/utils/abi/coder/">AbiCoder</a></div><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/api/utils/abi/formats/">ABI Formats</a></div><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/api/utils/abi/fragments/">Fragments</a></div><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/api/utils/abi/interface/">Interface</a></div></div><div class="page-separator"></div><a name="/v5/api/utils/abi/coder/-%23-AbiCoder"></a><a name="/v5/api/utils/abi/coder/-%23-AbiCoder"></a><a name="/v5/api/utils/abi/coder/"></a><h1 class="show-anchors"><div>AbiCoder<div class="anchors"><a class="self" href="#/v5/api/utils/abi/coder/-%23-AbiCoder"></a><a class="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 <a href="#/v5/api/utils/abi/interface/">Interface</a> class greatly simplifies these operations.</p>
|
|
|
|
<a name="/v5/api/utils/abi/coder/-%23-AbiCoder--creating"></a><a name="/v5/api/utils/abi/coder/-%23-AbiCoder--AbiCoder--creating"></a><a name="/v5/api/utils/abi/coder/"></a><h2 class="show-anchors"><div>Creating Instance<div class="anchors"><a class="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 <a href="#/v5/api/utils/abi/coder/">AbiCoder</a>, since one is created with the default coercion function when the library is loaded which can be used universally.</p>
|
|
|
|
<p>This is likely only needed by those with specific needs to override how values are coerced after they are decoded from their binary format.</p>
|
|
|
|
<div class="property show-anchors"><div class="signature"><span class="modifier">new </span><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">AbiCoder</span><span class="symbol">(</span> <span class="symbol">[</span> <span class="param">coerceFunc</span> <span class="symbol">]</span> <span class="symbol">)</span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/abi-coder.ts#L35">source</a></div></div><div class="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><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">defaultAbiCoder</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/abi/coder/">AbiCoder</a></span><div class="anchors"></div></div><div class="body"><p>An <a href="#/v5/api/utils/abi/coder/">AbiCoder</a> created when the library is imported which is used by the <a href="#/v5/api/utils/abi/interface/">Interface</a>.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/abi/coder/-%23-AbiCoder--methods"></a><a name="/v5/api/utils/abi/coder/-%23-AbiCoder--AbiCoder--methods"></a><a name="/v5/api/utils/abi/coder/"></a><h2 class="show-anchors"><div>Coding Methods<div class="anchors"><a class="self" href="#/v5/api/utils/abi/coder/-%23-AbiCoder--methods"></a></div></div></h2>
|
|
<a name="/v5/api/utils/abi/coder/-%23-AbiCoder-encode"></a><div class="property show-anchors"><div class="signature"><span class="path">abiCoder</span><span class="symbol">.</span><span class="method">encode</span><span class="symbol">(</span> <span class="param">types</span> <span class="symbol">,</span> <span class="param">values</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a> ></span><div class="anchors"><a class="self" href="#/v5/api/utils/abi/coder/-%23-AbiCoder-encode"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/abi-coder.ts#L100">source</a></div></div><div class="body"><p>Encode the array <i>values</i> according to the array of <i>types</i>, each of which may be a string or a <a href="#/v5/api/utils/abi/fragments/-%23-ParamType">ParamType</a>.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/abi/coder/-%23-AbiCoder-decode"></a><div class="property show-anchors"><div class="signature"><span class="path">abiCoder</span><span class="symbol">.</span><span class="method">decode</span><span class="symbol">(</span> <span class="param">types</span> <span class="symbol">,</span> <span class="param">data</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/abi/interface/-%23-Result">Result</a></span><div class="anchors"><a class="self" href="#/v5/api/utils/abi/coder/-%23-AbiCoder-decode"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/abi-coder.ts#L116">source</a></div></div><div class="body"><p>Decode the <i>data</i> according to the array of <i>types</i>, each of which may be a string or <a href="#/v5/api/utils/abi/fragments/-%23-ParamType">ParamType</a>.</p>
|
|
|
|
</div></div><div class="page-separator"></div><a name="/v5/api/utils/abi/formats/-%23-abi-formats"></a><a name="/v5/api/utils/abi/formats/-%23-abi-formats"></a><a name="/v5/api/utils/abi/formats/"></a><h1 class="show-anchors"><div>ABI Formats<div class="anchors"><a class="self" href="#/v5/api/utils/abi/formats/-%23-abi-formats"></a></div></div></h1><p>@TODO: Expand this section</p>
|
|
|
|
<a name="/v5/api/utils/abi/formats/-%23-abi-formats--human-readable-abi"></a><a name="/v5/api/utils/abi/formats/-%23-abi-formats--abi-formats--human-readable-abi"></a><a name="/v5/api/utils/abi/formats/"></a><h2 class="show-anchors"><div>Human-Readable ABI<div class="anchors"><a class="self" href="#/v5/api/utils/abi/formats/-%23-abi-formats--human-readable-abi"></a></div></div></h2><p>See <a href="https://blog.ricmoo.com/human-readable-contract-abis-in-ethers-js-141902f4d917">Human-Readable Abi</a>.</p>
|
|
|
|
<a name="/v5/api/utils/abi/formats/-%23-abi-formats--solidity"></a><a name="/v5/api/utils/abi/formats/-%23-abi-formats--abi-formats--solidity"></a><a name="/v5/api/utils/abi/formats/"></a><h2 class="show-anchors"><div>Solidity JSON ABI<div class="anchors"><a class="self" href="#/v5/api/utils/abi/formats/-%23-abi-formats--solidity"></a></div></div></h2><p>See <a href="https://solidity.readthedocs.io/en/v0.6.0/using-the-compiler.html#output-description">Solidity compiler</a>.</p>
|
|
|
|
<div class="page-separator"></div><a name="/v5/api/utils/abi/fragments/-%23-fragments"></a><a name="/v5/api/utils/abi/fragments/-%23-fragments"></a><a name="/v5/api/utils/abi/fragments/"></a><h1 class="show-anchors"><div>Fragments<div class="anchors"><a class="self" href="#/v5/api/utils/abi/fragments/-%23-fragments"></a></div></div></h1><p>Explain an ABI.</p>
|
|
|
|
<a name="/v5/api/utils/abi/fragments/-%23-fragments--formats"></a><a name="/v5/api/utils/abi/fragments/"></a><h2 class="show-anchors"><div>Formats<div class="anchors"><a class="self" href="#/v5/api/utils/abi/fragments/-%23-fragments--formats"></a></div></div></h2>
|
|
<a name="/v5/api/utils/abi/fragments/-%23-fragments--formats--json-string-abi-solidity-output-json"></a><a name="/v5/api/utils/abi/fragments/"></a><h3 class="show-anchors"><div>JSON String ABI (Solidity Output JSON)<div class="anchors"><a class="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 <a href="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 <a href="#/v5/api/utils/abi/fragments/-%23-Fragment">Fragment</a> of the ABI.</p>
|
|
|
|
<p>The deserialized JSON string (which is a normal JavaScript Object) may also be passed into any function which accepts a JSON String ABI.</p>
|
|
|
|
<a name="/v5/api/utils/abi/fragments/-%23-fragments--formats--humanb-readable-abi"></a><a name="/v5/api/utils/abi/fragments/"></a><h3 class="show-anchors"><div>Humanb-Readable ABI<div class="anchors"><a class="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>
|
|
|
|
<p><a href="https://blog.ricmoo.com/human-readable-contract-abis-in-ethers-js-141902f4d917">article</a></p>
|
|
|
|
<a name="/v5/api/utils/abi/fragments/-%23-fragments--output-formats"></a><a name="/v5/api/utils/abi/fragments/-%23-fragments--formats--fragments--output-formats"></a><a name="/v5/api/utils/abi/fragments/"></a><h3 class="show-anchors"><div>Output Formats<div class="anchors"><a class="self" href="#/v5/api/utils/abi/fragments/-%23-fragments--output-formats"></a><a class="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 <a href="#/v5/api/utils/abi/fragments/-%23-Fragment">Fragment</a> and <a href="#/v5/api/utils/abi/fragments/-%23-ParamType">ParamType</a> may be output using its <code class="inline">format</code> method.</p>
|
|
|
|
<div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="path">FragmentTypes</span><span class="symbol">.</span><span class="method">full</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"></div></div><div class="body"><p>This is a full human-readable string, including all parameter names, any optional modifiers (e.g. <code class="inline">indexed</code>, <code class="inline">public</code>, etc) and white-space to aid in human readability.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="path">FragmentTypes</span><span class="symbol">.</span><span class="method">minimal</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"></div></div><div class="body"><p>This is similar to <code class="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 <a href="#/v5/api/utils/abi/fragments/-%23-Fragment-from">Fragment&thinsp;.&thinsp;from</a>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="path">FragmentTypes</span><span class="symbol">.</span><span class="method">json</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"></div></div><div class="body"><p>This returns a JavaScript Object which is safe to call <code class="inline">JSON.stringify</code> on to create a JSON string.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="path">FragmentTypes</span><span class="symbol">.</span><span class="method">sighash</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"></div></div><div class="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><div class="definition container-box warning"><div class="term">Note</div><div class="body"><p>The <code class="inline">sighash</code> format is <b>insufficient</b> to re-create the original <a href="#/v5/api/utils/abi/fragments/-%23-Fragment">Fragment</a>, since it discards modifiers such as indexed, anonymous, stateMutability, etc.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/abi/fragments/-%23-Fragment"></a><a name="/v5/api/utils/abi/fragments/-%23-fragments--Fragment"></a><a name="/v5/api/utils/abi/fragments/"></a><h2 class="show-anchors"><div>Fragment<div class="anchors"><a class="self" href="#/v5/api/utils/abi/fragments/-%23-Fragment"></a><a class="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>
|
|
|
|
<p><ul><li>An <a href="#/v5/api/utils/abi/fragments/-%23-EventFragment">Event</a> </li><li>A <a href="#/v5/api/utils/abi/fragments/-%23-FunctionFragment">Function</a> </li><li>A <a href="#/v5/api/utils/abi/fragments/-%23-ConstructorFragment">Constructor</a> </li></ul></p>
|
|
|
|
<a name="/v5/api/utils/abi/fragments/-%23-fragments--Fragment--properties"></a><a name="/v5/api/utils/abi/fragments/"></a><h3 class="show-anchors"><div>Properties<div class="anchors"><a class="self" href="#/v5/api/utils/abi/fragments/-%23-fragments--Fragment--properties"></a></div></div></h3>
|
|
<div class="property show-anchors"><div class="signature"><span class="path">fragment</span><span class="symbol">.</span><span class="method">name</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"></div></div><div class="body"><p>This is the name of the Event or Function. This will be null for a <a href="#/v5/api/utils/abi/fragments/-%23-ConstructorFragment">ConstructorFragment</a>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">fragment</span><span class="symbol">.</span><span class="method">type</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"></div></div><div class="body"><p>This is a string which indicates the type of the <a href="#/v5/api/utils/abi/fragments/-%23-Fragment">Fragment</a>. This will be one of:</p>
|
|
|
|
<p><ul><li><code class="inline">constructor</code> </li><li><code class="inline">event</code> </li><li><code class="inline">function</code> </li></ul></p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">fragment</span><span class="symbol">.</span><span class="method">inputs</span> <span class="arrow">⇒</span> <span class="returns">Array< <a href="#/v5/api/utils/abi/fragments/-%23-ParamType">ParamType</a> ></span><div class="anchors"></div></div><div class="body"><p>This is an array of each <a href="#/v5/api/utils/abi/fragments/-%23-ParamType">ParamType</a> for the input parameters to the Constructor, Event of Function.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/abi/fragments/-%23-fragments--Fragment--methods"></a><a name="/v5/api/utils/abi/fragments/"></a><h3 class="show-anchors"><div>Methods<div class="anchors"><a class="self" href="#/v5/api/utils/abi/fragments/-%23-fragments--Fragment--methods"></a></div></div></h3>
|
|
<a name="/v5/api/utils/abi/fragments/-%23-Fragment-from"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="path">Fragment</span><span class="symbol">.</span><span class="method">from</span><span class="symbol">(</span> <span class="param">objectOrString</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/abi/fragments/-%23-Fragment">Fragment</a></span><div class="anchors"><a class="self" href="#/v5/api/utils/abi/fragments/-%23-Fragment-from"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/fragments.ts#L428">source</a></div></div><div class="body"><p>Returns a</p>
|
|
|
|
</div></div><a name="/v5/api/utils/abi/fragments/-%23-Fragment-isFragment"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="path">Fragment</span><span class="symbol">.</span><span class="method">isFragment</span><span class="symbol">(</span> <span class="param">object</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">boolean</span><div class="anchors"><a class="self" href="#/v5/api/utils/abi/fragments/-%23-Fragment-isFragment"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/fragments.ts#L474">source</a></div></div><div class="body"><p>Tra lal al</p>
|
|
|
|
</div></div><a name="/v5/api/utils/abi/fragments/-%23-ConstructorFragment"></a><a name="/v5/api/utils/abi/fragments/-%23-fragments--ConstructorFragment"></a><a name="/v5/api/utils/abi/fragments/"></a><h2 class="show-anchors"><div>ConstructorFragment<span class="inherits"> inherits <a href="#/v5/api/utils/abi/fragments/-%23-Fragment">Fragment</a></span><div class="anchors"><a class="self" href="#/v5/api/utils/abi/fragments/-%23-ConstructorFragment"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/fragments.ts#L708">source</a></div></div></h2>
|
|
<a name="/v5/api/utils/abi/fragments/-%23-fragments--ConstructorFragment--properties"></a><a name="/v5/api/utils/abi/fragments/"></a><h3 class="show-anchors"><div>Properties<div class="anchors"><a class="self" href="#/v5/api/utils/abi/fragments/-%23-fragments--ConstructorFragment--properties"></a></div></div></h3>
|
|
<div class="property show-anchors"><div class="signature"><span class="path">fragment</span><span class="symbol">.</span><span class="method">gas</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/bignumber/">BigNumber</a></span><div class="anchors"></div></div><div class="body"><p>This is the gas limit that should be used during deployment. It may be null.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">fragment</span><span class="symbol">.</span><span class="method">payable</span> <span class="arrow">⇒</span> <span class="returns">boolean</span><div class="anchors"></div></div><div class="body"><p>This is whether the constructor may receive ether during deployment as an endowment (i.e. msg.value != 0).</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">fragment</span><span class="symbol">.</span><span class="method">stateMutability</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"></div></div><div class="body"><p>This is the state mutability of the constructor. It can be any of:</p>
|
|
|
|
<p><ul><li><code class="inline">nonpayable</code> </li><li><code class="inline">payable</code> </li></ul></p>
|
|
|
|
</div></div><a name="/v5/api/utils/abi/fragments/-%23-fragments--ConstructorFragment--methods"></a><a name="/v5/api/utils/abi/fragments/"></a><h3 class="show-anchors"><div>Methods<div class="anchors"><a class="self" href="#/v5/api/utils/abi/fragments/-%23-fragments--ConstructorFragment--methods"></a></div></div></h3>
|
|
<a name="/v5/api/utils/abi/fragments/-%23-ConstructorFragment-from"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="path">ConstructorFragment</span><span class="symbol">.</span><span class="method">from</span><span class="symbol">(</span> <span class="param">objectOrString</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/abi/fragments/-%23-ConstructorFragment">ConstructorFragment</a></span><div class="anchors"><a class="self" href="#/v5/api/utils/abi/fragments/-%23-ConstructorFragment-from"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/fragments.ts#L746">source</a></div></div><div class="body"><p>Tra la la...</p>
|
|
|
|
</div></div><a name="/v5/api/utils/abi/fragments/-%23-ConstructorFragment-isConstructorFragment"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="path">ConstructorFragment</span><span class="symbol">.</span><span class="method">isConstructorFragment</span><span class="symbol">(</span> <span class="param">object</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">boolean</span><div class="anchors"><a class="self" href="#/v5/api/utils/abi/fragments/-%23-ConstructorFragment-isConstructorFragment"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/fragments.ts#L794">source</a></div></div><div class="body"><p>Tra lal al</p>
|
|
|
|
</div></div><a name="/v5/api/utils/abi/fragments/-%23-EventFragment"></a><a name="/v5/api/utils/abi/fragments/-%23-fragments--EventFragment"></a><a name="/v5/api/utils/abi/fragments/"></a><h2 class="show-anchors"><div>EventFragment<span class="inherits"> inherits <a href="#/v5/api/utils/abi/fragments/-%23-Fragment">Fragment</a></span><div class="anchors"><a class="self" href="#/v5/api/utils/abi/fragments/-%23-EventFragment"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/fragments.ts#L483">source</a></div></div></h2>
|
|
<a name="/v5/api/utils/abi/fragments/-%23-fragments--EventFragment--properties"></a><a name="/v5/api/utils/abi/fragments/"></a><h3 class="show-anchors"><div>Properties<div class="anchors"><a class="self" href="#/v5/api/utils/abi/fragments/-%23-fragments--EventFragment--properties"></a></div></div></h3>
|
|
<div class="property show-anchors"><div class="signature"><span class="path">fragment</span><span class="symbol">.</span><span class="method">anonymous</span> <span class="arrow">⇒</span> <span class="returns">boolean</span><div class="anchors"></div></div><div class="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>
|
|
|
|
</div></div><a name="/v5/api/utils/abi/fragments/-%23-fragments--EventFragment--methods"></a><a name="/v5/api/utils/abi/fragments/"></a><h3 class="show-anchors"><div>Methods<div class="anchors"><a class="self" href="#/v5/api/utils/abi/fragments/-%23-fragments--EventFragment--methods"></a></div></div></h3>
|
|
<a name="/v5/api/utils/abi/fragments/-%23-EventFragment-from"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="path">EventFragment</span><span class="symbol">.</span><span class="method">from</span><span class="symbol">(</span> <span class="param">objectOrString</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/abi/fragments/-%23-EventFragment">EventFragment</a></span><div class="anchors"><a class="self" href="#/v5/api/utils/abi/fragments/-%23-EventFragment-from"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/fragments.ts#L520">source</a></div></div><div class="body"><p>Tra la la...</p>
|
|
|
|
</div></div><a name="/v5/api/utils/abi/fragments/-%23-EventFragment-isEventFragment"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="path">EventFragment</span><span class="symbol">.</span><span class="method">isEventFragment</span><span class="symbol">(</span> <span class="param">object</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">boolean</span><div class="anchors"><a class="self" href="#/v5/api/utils/abi/fragments/-%23-EventFragment-isEventFragment"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/fragments.ts#L572">source</a></div></div><div class="body"><p>Tra lal al</p>
|
|
|
|
</div></div><a name="/v5/api/utils/abi/fragments/-%23-FunctionFragment"></a><a name="/v5/api/utils/abi/fragments/-%23-fragments--FunctionFragment"></a><a name="/v5/api/utils/abi/fragments/"></a><h2 class="show-anchors"><div>FunctionFragment<span class="inherits"> inherits <a href="#/v5/api/utils/abi/fragments/-%23-ConstructorFragment">ConstructorFragment</a></span><div class="anchors"><a class="self" href="#/v5/api/utils/abi/fragments/-%23-FunctionFragment"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/fragments.ts#L804">source</a></div></div></h2>
|
|
<a name="/v5/api/utils/abi/fragments/-%23-fragments--FunctionFragment--properties"></a><a name="/v5/api/utils/abi/fragments/"></a><h3 class="show-anchors"><div>Properties<div class="anchors"><a class="self" href="#/v5/api/utils/abi/fragments/-%23-fragments--FunctionFragment--properties"></a></div></div></h3>
|
|
<div class="property show-anchors"><div class="signature"><span class="path">fragment</span><span class="symbol">.</span><span class="method">constant</span> <span class="arrow">⇒</span> <span class="returns">boolean</span><div class="anchors"></div></div><div class="body"><p>This is whether the function is constant (i.e. does not change state). This is true if the state mutability is <code class="inline">pure</code> or <code class="inline">view</code>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">fragment</span><span class="symbol">.</span><span class="method">stateMutability</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"></div></div><div class="body"><p>This is the state mutability of the constructor. It can be any of:</p>
|
|
|
|
<p><ul><li><code class="inline">nonpayable</code> </li><li><code class="inline">payable</code> </li><li><code class="inline">pure</code> </li><li><code class="inline">view</code> </li></ul></p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">fragment</span><span class="symbol">.</span><span class="method">outputs</span> <span class="arrow">⇒</span> <span class="returns">Array< <a href="#/v5/api/utils/abi/fragments/-%23-ParamType">ParamType</a> ></span><div class="anchors"></div></div><div class="body"><p>A list of the Function output parameters.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/abi/fragments/-%23-fragments--FunctionFragment--method"></a><a name="/v5/api/utils/abi/fragments/"></a><h3 class="show-anchors"><div>Method<div class="anchors"><a class="self" href="#/v5/api/utils/abi/fragments/-%23-fragments--FunctionFragment--method"></a></div></div></h3>
|
|
<a name="/v5/api/utils/abi/fragments/-%23-FunctionFragment-from"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="path">FunctionFragment</span><span class="symbol">.</span><span class="method">from</span><span class="symbol">(</span> <span class="param">objectOrString</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/abi/fragments/-%23-FunctionFragment">FunctionFragment</a></span><div class="anchors"><a class="self" href="#/v5/api/utils/abi/fragments/-%23-FunctionFragment-from"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/fragments.ts#L746">source</a></div></div><div class="body"><p>Tra la la...</p>
|
|
|
|
</div></div><a name="/v5/api/utils/abi/fragments/-%23-FunctionFragment-isFunctionFragment"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="path">FunctionFragment</span><span class="symbol">.</span><span class="method">isFunctionFragment</span><span class="symbol">(</span> <span class="param">object</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">boolean</span><div class="anchors"><a class="self" href="#/v5/api/utils/abi/fragments/-%23-FunctionFragment-isFunctionFragment"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/fragments.ts#L925">source</a></div></div><div class="body"><p>Tra lal al</p>
|
|
|
|
</div></div><a name="/v5/api/utils/abi/fragments/-%23-ParamType"></a><a name="/v5/api/utils/abi/fragments/-%23-fragments--ParamType"></a><a name="/v5/api/utils/abi/fragments/"></a><h2 class="show-anchors"><div>ParamType<div class="anchors"><a class="self" href="#/v5/api/utils/abi/fragments/-%23-ParamType"></a><a class="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>
|
|
|
|
<p><code class="inline">string foobar</code></p>
|
|
|
|
<a name="/v5/api/utils/abi/fragments/-%23-fragments--ParamType--properties"></a><a name="/v5/api/utils/abi/fragments/"></a><h3 class="show-anchors"><div>Properties<div class="anchors"><a class="self" href="#/v5/api/utils/abi/fragments/-%23-fragments--ParamType--properties"></a></div></div></h3>
|
|
<a name="/v5/api/utils/abi/fragments/-%23-ParamType-name"></a><div class="property show-anchors"><div class="signature"><span class="path">paramType</span><span class="symbol">.</span><span class="method">name</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"><a class="self" href="#/v5/api/utils/abi/fragments/-%23-ParamType-name"></a></div></div><div class="body"><p>The local parameter name. This may be null for unnamed parameters. For example, the parameter definition <code class="inline">string foobar</code> would be <code class="inline">foobar</code>.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/abi/fragments/-%23-ParamType-type"></a><div class="property show-anchors"><div class="signature"><span class="path">paramType</span><span class="symbol">.</span><span class="method">type</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"><a class="self" href="#/v5/api/utils/abi/fragments/-%23-ParamType-type"></a></div></div><div class="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 <code class="inline">foobar</code>.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/abi/fragments/-%23-ParamType-baseType"></a><div class="property show-anchors"><div class="signature"><span class="path">paramType</span><span class="symbol">.</span><span class="method">baseType</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"><a class="self" href="#/v5/api/utils/abi/fragments/-%23-ParamType-baseType"></a></div></div><div class="body"><p>The base type of the parameter. For primitive types (e.g. <code class="inline">address</code>, <code class="inline">uint256</code>, etc) this is equal to <a href="#/v5/api/utils/abi/fragments/-%23-ParamType-type">type</a>. For arrays, it will be the string <code class="inline">array</code> and for a tuple, it will be the string <code class="inline">tuple</code>.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/abi/fragments/-%23-ParamType-indexed"></a><div class="property show-anchors"><div class="signature"><span class="path">paramType</span><span class="symbol">.</span><span class="method">indexed</span> <span class="arrow">⇒</span> <span class="returns">boolean</span><div class="anchors"><a class="self" href="#/v5/api/utils/abi/fragments/-%23-ParamType-indexed"></a></div></div><div class="body"><p>Whether the parameter has been marked as indexed. This <b>only</b> applies to parameters which are part of an <a href="#/v5/api/utils/abi/fragments/-%23-EventFragment">EventFragment</a>.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/abi/fragments/-%23-ParamType-arrayChildren"></a><div class="property show-anchors"><div class="signature"><span class="path">paramType</span><span class="symbol">.</span><span class="method">arrayChildren</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/abi/fragments/-%23-ParamType">ParamType</a></span><div class="anchors"><a class="self" href="#/v5/api/utils/abi/fragments/-%23-ParamType-arrayChildren"></a></div></div><div class="body"><p>The type of children of the array. This is null for any parameter which is not an array.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/abi/fragments/-%23-ParamType-arrayLength"></a><div class="property show-anchors"><div class="signature"><span class="path">paramType</span><span class="symbol">.</span><span class="method">arrayLength</span> <span class="arrow">⇒</span> <span class="returns">number</span><div class="anchors"><a class="self" href="#/v5/api/utils/abi/fragments/-%23-ParamType-arrayLength"></a></div></div><div class="body"><p>The length of the array, or <code class="inline">-1</code> for dynamic-length arrays. This is null for parameters which are not arrays.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/abi/fragments/-%23-ParamType-components"></a><div class="property show-anchors"><div class="signature"><span class="path">paramType</span><span class="symbol">.</span><span class="method">components</span> <span class="arrow">⇒</span> <span class="returns">Array< <a href="#/v5/api/utils/abi/fragments/-%23-ParamType">ParamType</a> ></span><div class="anchors"><a class="self" href="#/v5/api/utils/abi/fragments/-%23-ParamType-components"></a></div></div><div class="body"><p>The components of a tuple. This is null for non-tuple parameters.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/abi/fragments/-%23-fragments--ParamType--methods"></a><a name="/v5/api/utils/abi/fragments/"></a><h3 class="show-anchors"><div>Methods<div class="anchors"><a class="self" href="#/v5/api/utils/abi/fragments/-%23-fragments--ParamType--methods"></a></div></div></h3><p>Tra la la...</p>
|
|
|
|
<div class="property show-anchors"><div class="signature"><span class="path">paramType</span><span class="symbol">.</span><span class="method">format</span><span class="symbol">(</span> <span class="symbol">[</span> <span class="param">outputType</span> = <span class="param">sighash</span> <span class="symbol">]</span> <span class="symbol">)</span><div class="anchors"></div></div><div class="body"><p>Tra la la...</p>
|
|
|
|
</div></div><a name="/v5/api/utils/abi/fragments/-%23-ParamType-from"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="path">ParamType</span><span class="symbol">.</span><span class="method">from</span><span class="symbol">(</span> <span class="param">objectOrString</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/abi/fragments/-%23-ParamType">ParamType</a></span><div class="anchors"><a class="self" href="#/v5/api/utils/abi/fragments/-%23-ParamType-from"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/fragments.ts#L357">source</a></div></div><div class="body"><p>Tra la la...</p>
|
|
|
|
</div></div><a name="/v5/api/utils/abi/fragments/-%23-ParamType-isParamType"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="path">ParamType</span><span class="symbol">.</span><span class="method">isParamType</span><span class="symbol">(</span> <span class="param">object</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">boolean</span><div class="anchors"><a class="self" href="#/v5/api/utils/abi/fragments/-%23-ParamType-isParamType"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/fragments.ts#L388">source</a></div></div><div class="body"><p>Tra la la...</p>
|
|
|
|
</div></div><div class="page-separator"></div><a name="/v5/api/utils/abi/interface/-%23-Interface"></a><a name="/v5/api/utils/abi/interface/-%23-Interface"></a><a name="/v5/api/utils/abi/interface/"></a><h1 class="show-anchors"><div>Interface<div class="anchors"><a class="self" href="#/v5/api/utils/abi/interface/-%23-Interface"></a><a class="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 <a href="https://solidity.readthedocs.io/">Solidity</a> language, which other languages have adopted to remain compatible 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>
|
|
|
|
<a name="/v5/api/utils/abi/interface/-%23-Interface--creating"></a><a name="/v5/api/utils/abi/interface/-%23-Interface--Interface--creating"></a><a name="/v5/api/utils/abi/interface/"></a><h2 class="show-anchors"><div>Creating Instances<div class="anchors"><a class="self" href="#/v5/api/utils/abi/interface/-%23-Interface--creating"></a></div></div></h2>
|
|
<div class="property show-anchors"><div class="signature"><span class="modifier">new </span><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">Interface</span><span class="symbol">(</span> <span class="param">abi</span> <span class="symbol">)</span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/interface.ts#L79">source</a></div></div><div class="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 <a href="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 <a href="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>
|
|
|
|
</div></div><a name="/v5/api/utils/abi/interface/-%23-Interface--properties"></a><a name="/v5/api/utils/abi/interface/-%23-Interface--Interface--properties"></a><a name="/v5/api/utils/abi/interface/"></a><h2 class="show-anchors"><div>Properties<div class="anchors"><a class="self" href="#/v5/api/utils/abi/interface/-%23-Interface--properties"></a></div></div></h2>
|
|
<div class="property show-anchors"><div class="signature"><span class="path">interface</span><span class="symbol">.</span><span class="method">fragments</span> <span class="arrow">⇒</span> <span class="returns">Array< <a href="#/v5/api/utils/abi/fragments/-%23-Fragment">Fragment</a> ></span><div class="anchors"></div></div><div class="body"><p>All the <a href="#/v5/api/utils/abi/fragments/-%23-Fragment">Fragments</a> in the interface.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">interface</span><span class="symbol">.</span><span class="method">events</span> <span class="arrow">⇒</span> <span class="returns">Array< <a href="#/v5/api/utils/abi/fragments/-%23-EventFragment">EventFragment</a> ></span><div class="anchors"></div></div><div class="body"><p>All the <a href="#/v5/api/utils/abi/fragments/-%23-EventFragment">Event Fragments</a> in the interface.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">interface</span><span class="symbol">.</span><span class="method">functions</span> <span class="arrow">⇒</span> <span class="returns">Array< <a href="#/v5/api/utils/abi/fragments/-%23-FunctionFragment">FunctionFragment</a> ></span><div class="anchors"></div></div><div class="body"><p>All the <a href="#/v5/api/utils/abi/fragments/-%23-FunctionFragment">Function Fragments</a> in the interface.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">interface</span><span class="symbol">.</span><span class="method">deploy</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/abi/fragments/-%23-ConstructorFragment">ConstructorFragment</a></span><div class="anchors"></div></div><div class="body"><p>The <a href="#/v5/api/utils/abi/fragments/-%23-ConstructorFragment">Constructor Fragments</a> for the interface.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/abi/interface/-%23-Interface--formatting"></a><a name="/v5/api/utils/abi/interface/-%23-Interface--Interface--formatting"></a><a name="/v5/api/utils/abi/interface/"></a><h2 class="show-anchors"><div>Formatting<div class="anchors"><a class="self" href="#/v5/api/utils/abi/interface/-%23-Interface--formatting"></a></div></div></h2>
|
|
<div class="property show-anchors"><div class="signature"><span class="path">interface</span><span class="symbol">.</span><span class="method">format</span><span class="symbol">(</span> <span class="symbol">[</span> <span class="param">format</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string | Array< string ></span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/interface.ts#L145">source</a></div></div><div class="body"><p>Return the formatted <b>Interface</b>. If the format type is <code class="inline">json</code> a single string is returned, otherwise an Array of the human-readable strings is returned.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/abi/interface/-%23-Interface--fragments"></a><a name="/v5/api/utils/abi/interface/-%23-Interface--Interface--fragments"></a><a name="/v5/api/utils/abi/interface/"></a><h2 class="show-anchors"><div>Fragment Access<div class="anchors"><a class="self" href="#/v5/api/utils/abi/interface/-%23-Interface--fragments"></a></div></div></h2>
|
|
<div class="property show-anchors"><div class="signature"><span class="path">interface</span><span class="symbol">.</span><span class="method">getFunction</span><span class="symbol">(</span> <span class="param">fragment</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/abi/fragments/-%23-FunctionFragment">FunctionFragment</a></span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/interface.ts#L179">source</a></div></div><div class="body"><p>Returns the <a href="#/v5/api/utils/abi/fragments/-%23-FunctionFragment">FunctionFragment</a> for <i>fragment</i> (see <a href="#/v5/api/utils/abi/interface/-%23-Interface--specifying-fragments">Specifying Fragments</a>).</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">interface</span><span class="symbol">.</span><span class="method">getEvent</span><span class="symbol">(</span> <span class="param">fragment</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/abi/fragments/-%23-EventFragment">EventFragment</a></span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/interface.ts#L211">source</a></div></div><div class="body"><p>Returns the <a href="#/v5/api/utils/abi/fragments/-%23-EventFragment">EventFragment</a> for <i>fragment</i> (see <a href="#/v5/api/utils/abi/interface/-%23-Interface--specifying-fragments">Specifying Fragments</a>).</p>
|
|
|
|
</div></div><a name="/v5/api/utils/abi/interface/-%23-Interface--selectors"></a><a name="/v5/api/utils/abi/interface/-%23-Interface--Interface--selectors"></a><a name="/v5/api/utils/abi/interface/"></a><h2 class="show-anchors"><div>Signature and Topic Hashes<div class="anchors"><a class="self" href="#/v5/api/utils/abi/interface/-%23-Interface--selectors"></a></div></div></h2>
|
|
<div class="property show-anchors"><div class="signature"><span class="path">interface</span><span class="symbol">.</span><span class="method">getSighash</span><span class="symbol">(</span> <span class="param">fragment</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 4 > ></span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/interface.ts#L244">source</a></div></div><div class="body"><p>Return the sighash (or Function Selector) for <i>fragment</i> (see <a href="#/v5/api/utils/abi/interface/-%23-Interface--specifying-fragments">Specifying Fragments</a>).</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">interface</span><span class="symbol">.</span><span class="method">getEventTopic</span><span class="symbol">(</span> <span class="param">fragment</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 > ></span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/interface.ts#L253">source</a></div></div><div class="body"><p>Return the topic hash for <i>fragment</i> (see <a href="#/v5/api/utils/abi/interface/-%23-Interface--specifying-fragments">Specifying Fragments</a>).</p>
|
|
|
|
</div></div><a name="/v5/api/utils/abi/interface/-%23-Interface--encoding"></a><a name="/v5/api/utils/abi/interface/-%23-Interface--Interface--encoding"></a><a name="/v5/api/utils/abi/interface/"></a><h2 class="show-anchors"><div>Encoding Data<div class="anchors"><a class="self" href="#/v5/api/utils/abi/interface/-%23-Interface--encoding"></a></div></div></h2>
|
|
<div class="property show-anchors"><div class="signature"><span class="path">interface</span><span class="symbol">.</span><span class="method">encodeDeploy</span><span class="symbol">(</span> <span class="symbol">[</span> <span class="param">values</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a> ></span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/interface.ts#L270">source</a></div></div><div class="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><div class="property show-anchors"><div class="signature"><span class="path">interface</span><span class="symbol">.</span><span class="method">encodeFilterTopics</span><span class="symbol">(</span> <span class="param">fragment</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">values</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Array< topic | Array< topic > ></span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/interface.ts#L344">source</a></div></div><div class="body"><p>Returns the encoded topic filter, which can be passed to getLogs for <i>fragment</i> (see <a href="#/v5/api/utils/abi/interface/-%23-Interface--specifying-fragments">Specifying Fragments</a>) for the given <i>values</i>.</p>
|
|
|
|
<p>Each <i>topic</i> is a 32 byte (64 nibble) <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">interface</span><span class="symbol">.</span><span class="method">encodeFunctionData</span><span class="symbol">(</span> <span class="param">fragment</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">values</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a> ></span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/interface.ts#L290">source</a></div></div><div class="body"><p>Returns the encoded data, which can be used as the data for a transaction for <i>fragment</i> (see <a href="#/v5/api/utils/abi/interface/-%23-Interface--specifying-fragments">Specifying Fragments</a>) for the given <i>values</i>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">interface</span><span class="symbol">.</span><span class="method">encodeFunctionResult</span><span class="symbol">(</span> <span class="param">fragment</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">values</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a> ></span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/interface.ts#L335">source</a></div></div><div class="body"><p>Returns the encoded result, which would normally be the response from a call for <i>fragment</i> (see <a href="#/v5/api/utils/abi/interface/-%23-Interface--specifying-fragments">Specifying Fragments</a>) for the given <i>values</i>.</p>
|
|
|
|
<p>Most developers will not need this method, but may be useful for authors of a mock blockchain.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/abi/interface/-%23-Interface--decoding"></a><a name="/v5/api/utils/abi/interface/-%23-Interface--Interface--decoding"></a><a name="/v5/api/utils/abi/interface/"></a><h2 class="show-anchors"><div>Decoding Data<div class="anchors"><a class="self" href="#/v5/api/utils/abi/interface/-%23-Interface--decoding"></a></div></div></h2>
|
|
<div class="property show-anchors"><div class="signature"><span class="path">interface</span><span class="symbol">.</span><span class="method">decodeEventLog</span><span class="symbol">(</span> <span class="param">fragment</span> <span class="symbol">,</span> <span class="param">data</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">topics</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/abi/interface/-%23-Result">Result</a></span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/interface.ts#L445">source</a></div></div><div class="body"><p>Returns the decoded event values from an event log for <i>fragment</i> (see <a href="#/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>
|
|
|
|
<p>If <i>topics</i> is not specified, placeholders will be inserted into the result.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">interface</span><span class="symbol">.</span><span class="method">decodeFunctionData</span><span class="symbol">(</span> <span class="param">fragment</span> <span class="symbol">,</span> <span class="param">data</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/abi/interface/-%23-Result">Result</a></span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/interface.ts#L275">source</a></div></div><div class="body"><p>Returns the decoded values from transaction data for <i>fragment</i> (see <a href="#/v5/api/utils/abi/interface/-%23-Interface--specifying-fragments">Specifying Fragments</a>) for the given <i>data</i>.</p>
|
|
|
|
<p>Most developers will not need this method, but may be useful for debugging or inspecting transactions.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">interface</span><span class="symbol">.</span><span class="method">decodeFunctionResult</span><span class="symbol">(</span> <span class="param">fragment</span> <span class="symbol">,</span> <span class="param">data</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/abi/interface/-%23-Result">Result</a></span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/interface.ts#L302">source</a></div></div><div class="body"><p>Returns the decoded values from the result of a call for <i>fragment</i> (see <a href="#/v5/api/utils/abi/interface/-%23-Interface--specifying-fragments">Specifying Fragments</a>) for the given <i>data</i>.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/abi/interface/-%23-Interface--parsing"></a><a name="/v5/api/utils/abi/interface/-%23-Interface--Interface--parsing"></a><a name="/v5/api/utils/abi/interface/"></a><h2 class="show-anchors"><div>Parsing<div class="anchors"><a class="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>
|
|
|
|
<div class="property show-anchors"><div class="signature"><span class="path">interface</span><span class="symbol">.</span><span class="method">parseLog</span><span class="symbol">(</span> <span class="param">log</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/abi/interface/-%23-LogDescription">LogDescription</a></span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/interface.ts#L552">source</a></div></div><div class="body"><p>Search the event that matches the <i>log</i> topic hash and parse the values the log represents.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">interface</span><span class="symbol">.</span><span class="method">parseTransaction</span><span class="symbol">(</span> <span class="param">transaction</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/abi/interface/-%23-TransactionDescription">TransactionDescription</a></span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/interface.ts#L535">source</a></div></div><div class="body"><p>Search for the function that matches the <i>transaction</i> data sighash and parse the transaction properties.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/abi/interface/-%23-Interface--types"></a><a name="/v5/api/utils/abi/interface/-%23-Interface--Interface--types"></a><a name="/v5/api/utils/abi/interface/"></a><h2 class="show-anchors"><div>Types<div class="anchors"><a class="self" href="#/v5/api/utils/abi/interface/-%23-Interface--types"></a></div></div></h2>
|
|
<a name="/v5/api/utils/abi/interface/-%23-Result"></a><a name="/v5/api/utils/abi/interface/-%23-Interface--Interface--types--Result"></a><a name="/v5/api/utils/abi/interface/"></a><h3 class="show-anchors"><div>Result<span class="inherits"> inherits Array<any></span><div class="anchors"><a class="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 <code class="inline">length</code> is however reserved as it is part of the Array, so any named value for this key is renamed to <code class="inline">_length</code>. If there is a name collision, only the first is available by its key.</p>
|
|
|
|
<a name="/v5/api/utils/abi/interface/-%23-LogDescription"></a><a name="/v5/api/utils/abi/interface/-%23-Interface--Interface--types--LogDescription"></a><a name="/v5/api/utils/abi/interface/"></a><h3 class="show-anchors"><div>LogDescription<div class="anchors"><a class="self" href="#/v5/api/utils/abi/interface/-%23-LogDescription"></a></div></div></h3>
|
|
<div class="property show-anchors"><div class="signature"><span class="path">logDescription</span><span class="symbol">.</span><span class="method">args</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/abi/interface/-%23-Result">Result</a></span><div class="anchors"></div></div><div class="body"><p>The values of the input parameters of the event.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">logDescription</span><span class="symbol">.</span><span class="method">eventFragment</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/abi/fragments/-%23-EventFragment">EventFragment</a></span><div class="anchors"></div></div><div class="body"><p>The <a href="#/v5/api/utils/abi/fragments/-%23-EventFragment">EventFragment</a> which matches the topic in the Log.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">logDescription</span><span class="symbol">.</span><span class="method">name</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"></div></div><div class="body"><p>The event name. (e.g. <code class="inline">Transfer</code>)</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">logDescription</span><span class="symbol">.</span><span class="method">signature</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"></div></div><div class="body"><p>The event signature. (e.g. <code class="inline">Transfer(address,address,uint256)</code>)</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">logDescription</span><span class="symbol">.</span><span class="method">topic</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"></div></div><div class="body"><p>The topic hash.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/abi/interface/-%23-TransactionDescription"></a><a name="/v5/api/utils/abi/interface/-%23-Interface--Interface--types--TransactionDescription"></a><a name="/v5/api/utils/abi/interface/"></a><h3 class="show-anchors"><div>TransactionDescription<div class="anchors"><a class="self" href="#/v5/api/utils/abi/interface/-%23-TransactionDescription"></a></div></div></h3>
|
|
<div class="property show-anchors"><div class="signature"><span class="path">transactionDescription</span><span class="symbol">.</span><span class="method">args</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/abi/interface/-%23-Result">Result</a></span><div class="anchors"></div></div><div class="body"><p>The decoded values from the transaction data which were passed as the input parameters.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">transactionDescription</span><span class="symbol">.</span><span class="method">functionFragment</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/abi/fragments/-%23-FunctionFragment">FunctionFragment</a></span><div class="anchors"></div></div><div class="body"><p>The <a href="#/v5/api/utils/abi/fragments/-%23-FunctionFragment">FunctionFragment</a> which matches the sighash in the transaction data.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">transactionDescription</span><span class="symbol">.</span><span class="method">name</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"></div></div><div class="body"><p>The name of the function. (e.g. <code class="inline">transfer</code>)</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">transactionDescription</span><span class="symbol">.</span><span class="method">sighash</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"></div></div><div class="body"><p>The sighash (or function selector) that matched the transaction data.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">transactionDescription</span><span class="symbol">.</span><span class="method">signature</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"></div></div><div class="body"><p>The signature of the function. (e.g. <code class="inline">transfer(address,uint256)</code>)</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">transactionDescription</span><span class="symbol">.</span><span class="method">value</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/bignumber/">BigNumber</a></span><div class="anchors"></div></div><div class="body"><p>The value from the transaction.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/abi/interface/-%23-Interface--specifying-fragments"></a><a name="/v5/api/utils/abi/interface/-%23-Interface--Interface--specifying-fragments"></a><a name="/v5/api/utils/abi/interface/"></a><h2 class="show-anchors"><div>Specifying Fragments<div class="anchors"><a class="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. <code class="inline">transfer</code>) </li><li>The <b>signature</b> of the event or function. The signature is normalized, so, for example, <code class="inline">uint</code> and <code class="inline">uint256</code> are equivalent (e.g. <code class="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. <code class="inline">0xa9059cbb</code>) </li><li>A <a href="#/v5/api/utils/abi/fragments/-%23-Fragment">Fragment</a> </li></ul></p>
|
|
|
|
<div class="page-separator"></div><a name="/v5/api/utils/address/-%23-addresses"></a><a name="/v5/api/utils/address/-%23-addresses"></a><a name="/v5/api/utils/address/"></a><h1 class="show-anchors"><div>Addresses<div class="anchors"><a class="self" href="#/v5/api/utils/address/-%23-addresses"></a></div></div></h1><p>Explain addresses,formats and checksumming here.</p>
|
|
|
|
<p>Also see: <a href="#/v5/api/utils/constants/">constants.AddressZero</a></p>
|
|
|
|
<a name="/v5/api/utils/address/-%23-address-formats"></a><a name="/v5/api/utils/address/-%23-addresses--address-formats"></a><a name="/v5/api/utils/address/"></a><h2 class="show-anchors"><div>Address Formats<div class="anchors"><a class="self" href="#/v5/api/utils/address/-%23-address-formats"></a></div></div></h2>
|
|
<a name="/v5/api/utils/address/-%23-address"></a><a name="/v5/api/utils/address/-%23-addresses--address-formats--address"></a><a name="/v5/api/utils/address/"></a><h3 class="show-anchors"><div>Address<div class="anchors"><a class="self" href="#/v5/api/utils/address/-%23-address"></a></div></div></h3><p>An <b>Address</b> is a <a href="#/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>
|
|
|
|
<a name="/v5/api/utils/address/-%23-address-icap"></a><a name="/v5/api/utils/address/-%23-addresses--address-formats--address-icap"></a><a name="/v5/api/utils/address/"></a><h3 class="show-anchors"><div>ICAP Address<div class="anchors"><a class="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 <a href="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 <code class="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 <a href="#/v5/api/utils/address/-%23-utils-getIcapAddress">getIcapAddress</a>.</p>
|
|
|
|
<a name="/v5/api/utils/address/-%23-utils--address"></a><a name="/v5/api/utils/address/-%23-addresses--utils--address"></a><a name="/v5/api/utils/address/"></a><h2 class="show-anchors"><div>Converting and Verifying<div class="anchors"><a class="self" href="#/v5/api/utils/address/-%23-utils--address"></a></div></div></h2>
|
|
<a name="/v5/api/utils/address/-%23-utils-getAddress"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">getAddress</span><span class="symbol">(</span> <span class="param">address</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/address/-%23-address">Address</a> ></span><div class="anchors"><a class="self" href="#/v5/api/utils/address/-%23-utils-getAddress"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/address/src.ts/index.ts#L77">source</a></div></div><div class="body"><p>Returns <i>address</i> as a Checksum Address.</p>
|
|
|
|
<p>If <i>address</i> is an invalid 40-nibble <a href="#/v5/api/utils/bytes/-%23-HexString">HexString</a> or if it contains mixed case and the checksum is invalid, an <a href="#/v5/api/utils/logger/-%23-errors--invalid-argument">INVALID_ARGUMENT</a> Error is thrown.</p>
|
|
|
|
<p>The value of <i>address</i> may be any supported address format.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/address/-%23-utils-getIcapAddress"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">getIcapAddress</span><span class="symbol">(</span> <span class="param">address</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/address/-%23-address-icap">IcapAddress</a> ></span><div class="anchors"><a class="self" href="#/v5/api/utils/address/-%23-utils-getIcapAddress"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/address/src.ts/index.ts#L123">source</a></div></div><div class="body"><p>Returns <i>address</i> as an <a href="https://github.com/ethereum/wiki/wiki/Inter-exchange-Client-Address-Protocol-%28ICAP%29">ICAP address</a>. Supports the same restrictions as <a href="#/v5/api/utils/address/-%23-utils-getAddress">getAddress</a>.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/address/-%23-utils-isAddress"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">isAddress</span><span class="symbol">(</span> <span class="param">address</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">boolean</span><div class="anchors"><a class="self" href="#/v5/api/utils/address/-%23-utils-isAddress"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/address/src.ts/index.ts#L115">source</a></div></div><div class="body"><p>Returns true if <i>address</i> is valid (in any supported format).</p>
|
|
|
|
</div></div><a name="/v5/api/utils/address/-%23-utils--address-derivation"></a><a name="/v5/api/utils/address/-%23-addresses--utils--address-derivation"></a><a name="/v5/api/utils/address/"></a><h2 class="show-anchors"><div>Derivation<div class="anchors"><a class="self" href="#/v5/api/utils/address/-%23-utils--address-derivation"></a></div></div></h2>
|
|
<a name="/v5/api/utils/address/-%23-utils-computeAddress"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">computeAddress</span><span class="symbol">(</span> <span class="param">publicOrPrivateKey</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/address/-%23-address">Address</a> ></span><div class="anchors"><a class="self" href="#/v5/api/utils/address/-%23-utils-computeAddress"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/transactions/src.ts/index.ts#L75">source</a></div></div><div class="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><a name="/v5/api/utils/address/-%23-utils-recoverAddress"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">recoverAddress</span><span class="symbol">(</span> <span class="param">digest</span> <span class="symbol">,</span> <span class="param">signature</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/address/-%23-address">Address</a> ></span><div class="anchors"><a class="self" href="#/v5/api/utils/address/-%23-utils-recoverAddress"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/transactions/src.ts/index.ts#L80">source</a></div></div><div class="body"><p>Use <a href="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>
|
|
|
|
</div></div><a name="/v5/api/utils/address/-%23-utils--contract-addresses"></a><a name="/v5/api/utils/address/-%23-addresses--utils--contract-addresses"></a><a name="/v5/api/utils/address/"></a><h2 class="show-anchors"><div>Contracts Addresses<div class="anchors"><a class="self" href="#/v5/api/utils/address/-%23-utils--contract-addresses"></a></div></div></h2>
|
|
<a name="/v5/api/utils/address/-%23-utils-getContractAddress"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">getContractAddress</span><span class="symbol">(</span> <span class="param">transaction</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/address/-%23-address">Address</a> ></span><div class="anchors"><a class="self" href="#/v5/api/utils/address/-%23-utils-getContractAddress"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/address/src.ts/index.ts#L130">source</a></div></div><div class="body"><p>Returns the contract address that would result if <i>transaction</i> was used to deploy a contract.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/address/-%23-utils-getCreate2Address"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">getCreate2Address</span><span class="symbol">(</span> <span class="param">from</span> <span class="symbol">,</span> <span class="param">salt</span> <span class="symbol">,</span> <span class="param">initCodeHash</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/address/-%23-address">Address</a> ></span><div class="anchors"><a class="self" href="#/v5/api/utils/address/-%23-utils-getCreate2Address"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/address/src.ts/index.ts#L143">source</a></div></div><div class="body"><p>Returns the contract address that would result from the given <a href="https://eips.ethereum.org/EIPS/eip-1014">CREATE2</a> call.</p>
|
|
|
|
</div></div><div class="page-separator"></div><a name="/v5/api/utils/bignumber/-%23-BigNumber"></a><a name="/v5/api/utils/bignumber/-%23-BigNumber"></a><a name="/v5/api/utils/bignumber/"></a><h1 class="show-anchors"><div>BigNumber<div class="anchors"><a class="self" href="#/v5/api/utils/bignumber/-%23-BigNumber"></a></div></div></h1><p>Many operations in Ethereum operation on numbers which are <a href="#/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 mathematical 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>
|
|
|
|
<a name="/v5/api/utils/bignumber/-%23-BigNumber--types"></a><a name="/v5/api/utils/bignumber/-%23-BigNumber--BigNumber--types"></a><a name="/v5/api/utils/bignumber/"></a><h2 class="show-anchors"><div>Types<div class="anchors"><a class="self" href="#/v5/api/utils/bignumber/-%23-BigNumber--types"></a></div></div></h2>
|
|
<a name="/v5/api/utils/bignumber/-%23-BigNumberish"></a><a name="/v5/api/utils/bignumber/-%23-BigNumber--BigNumber--types--BigNumberish"></a><a name="/v5/api/utils/bignumber/"></a><h3 class="show-anchors"><div>BigNumberish<div class="anchors"><a class="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 specified as:</p>
|
|
|
|
<div class="definition"><div class="term"><b><i>string</i></b></div><div class="body"><p>A <a href="#/v5/api/utils/bytes/-%23-HexString">HexString</a> or a decimal string, either of which may be negative.</p>
|
|
|
|
</div></div><div class="definition"><div class="term"><b><i>BytesLike</i></b></div><div class="body"><p>A <a href="#/v5/api/utils/bytes/-%23-BytesLike">BytesLike</a> Object, such as an Array or Uint8Array.</p>
|
|
|
|
</div></div><div class="definition"><div class="term"><b><i>BigNumber</i></b></div><div class="body"><p>An existing <a href="#/v5/api/utils/bignumber/">BigNumber</a> instance.</p>
|
|
|
|
</div></div><div class="definition"><div class="term"><b><i>number</i></b></div><div class="body"><p>A number that is within the <a href="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><div class="definition"><div class="term"><b><i>BigInt</i></b></div><div class="body"><p>A JavaScript <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt">BigInt</a> object, on environments that support BigInt.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/bignumber/-%23-BigNumber--creating"></a><a name="/v5/api/utils/bignumber/-%23-BigNumber--BigNumber--creating"></a><a name="/v5/api/utils/bignumber/"></a><h2 class="show-anchors"><div>Creating Instances<div class="anchors"><a class="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 <code class="inline">BigNumber.from</code>.</p>
|
|
|
|
<div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">BigNumber</span><span class="symbol">.</span><span class="method">from</span><span class="symbol">(</span> <span class="param">aBigNumberish</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/bignumber/">BigNumber</a></span><div class="anchors"></div></div><div class="body"><p>Returns an instance of a <b>BigNumber</b> for <i>aBigNumberish</i>.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/bignumber/-%23-BigNumber--BigNumber--creating--examples"></a><a name="/v5/api/utils/bignumber/"></a><h3 class="show-anchors"><div>Examples:<div class="anchors"></div></div></h3>
|
|
<div class="code"><span class="comment">// From a decimal string...
|
|
</span>BigNumber.from("42")
|
|
<span class="result ok">// { BigNumber: "42" }
|
|
</span>
|
|
<span class="comment">// From a HexString...
|
|
</span>BigNumber.from("0x2a")
|
|
<span class="result ok">// { BigNumber: "42" }
|
|
</span>
|
|
<span class="comment">// From a negative HexString...
|
|
</span>BigNumber.from("-0x2a")
|
|
<span class="result ok">// { BigNumber: "-42" }
|
|
</span>
|
|
<span class="comment">// From an Array (or Uint8Array)...
|
|
</span>BigNumber.from([ 42 ])
|
|
<span class="result ok">// { BigNumber: "42" }
|
|
</span>
|
|
<span class="comment">// From an existing BigNumber...
|
|
</span>let one1 = constants.One;
|
|
let one2 = BigNumber.from(one1)
|
|
|
|
one2
|
|
<span class="result ok">// { BigNumber: "1" }
|
|
</span>
|
|
<span class="comment">// ...which returns the same instance
|
|
</span>one1 === one2
|
|
<span class="result ok">// true
|
|
</span>
|
|
<span class="comment">// From a (safe) number...
|
|
</span>BigNumber.from(42)
|
|
<span class="result ok">// { BigNumber: "42" }
|
|
</span>
|
|
<span class="comment">// From a ES2015 BigInt... (only on platforms with BigInt support)
|
|
</span>BigNumber.from(42n)
|
|
<span class="result ok">// { BigNumber: "42" }
|
|
</span>
|
|
<span class="comment">// Numbers outside the safe range fail:
|
|
</span>BigNumber.from(Number.MAX_SAFE_INTEGER);
|
|
<span class="result error">// Error: overflow (fault="overflow", operation="BigNumber.from", value=9007199254740991, code=NUMERIC_FAULT, version=bignumber/5.0.14)
|
|
</span></div><a name="/v5/api/utils/bignumber/-%23-BigNumber--methods"></a><a name="/v5/api/utils/bignumber/-%23-BigNumber--BigNumber--methods"></a><a name="/v5/api/utils/bignumber/"></a><h2 class="show-anchors"><div>Methods<div class="anchors"><a class="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>
|
|
|
|
<a name="/v5/api/utils/bignumber/-%23-BigNumber--BigNumber--methods--math-operations"></a><a name="/v5/api/utils/bignumber/"></a><h3 class="show-anchors"><div>Math Operations<div class="anchors"><a class="self" href="#/v5/api/utils/bignumber/-%23-BigNumber--BigNumber--methods--math-operations"></a></div></div></h3>
|
|
<div class="property show-anchors"><div class="signature"><span class="path">BigNumber</span><span class="symbol">.</span><span class="method">add</span><span class="symbol">(</span> <span class="param">otherValue</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/bignumber/">BigNumber</a></span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/bignumber.ts#L75">source</a></div></div><div class="body"><p>Returns a BigNumber with the value of <i>BigNumber</i> <b>+</b> <i>otherValue</i>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">BigNumber</span><span class="symbol">.</span><span class="method">sub</span><span class="symbol">(</span> <span class="param">otherValue</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/bignumber/">BigNumber</a></span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/bignumber.ts#L79">source</a></div></div><div class="body"><p>Returns a BigNumber with the value of <i>BigNumber</i> <b>-</b> <i>otherValue</i>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">BigNumber</span><span class="symbol">.</span><span class="method">mul</span><span class="symbol">(</span> <span class="param">otherValue</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/bignumber/">BigNumber</a></span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/bignumber.ts#L91">source</a></div></div><div class="body"><p>Returns a BigNumber with the value of <i>BigNumber</i> <b>×</b> <i>otherValue</i>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">BigNumber</span><span class="symbol">.</span><span class="method">div</span><span class="symbol">(</span> <span class="param">divisor</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/bignumber/">BigNumber</a></span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/bignumber.ts#L83">source</a></div></div><div class="body"><p>Returns a BigNumber with the value of <i>BigNumber</i> <b>÷</b> <i>divisor</i>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">BigNumber</span><span class="symbol">.</span><span class="method">mod</span><span class="symbol">(</span> <span class="param">divisor</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/bignumber/">BigNumber</a></span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/bignumber.ts#L95">source</a></div></div><div class="body"><p>Returns a BigNumber with the value of the <b>remainder</b> of <i>BigNumber</i> ÷ <i>divisor</i>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">BigNumber</span><span class="symbol">.</span><span class="method">pow</span><span class="symbol">(</span> <span class="param">exponent</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/bignumber/">BigNumber</a></span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/bignumber.ts#L103">source</a></div></div><div class="body"><p>Returns a BigNumber with the value of <i>BigNumber</i> to the power of <i>exponent</i>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">BigNumber</span><span class="symbol">.</span><span class="method">abs</span><span class="symbol">(</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/bignumber/">BigNumber</a></span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/bignumber.ts#L68">source</a></div></div><div class="body"><p>Returns a BigNumber with the absolute value of <i>BigNumber</i>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">BigNumber</span><span class="symbol">.</span><span class="method">mask</span><span class="symbol">(</span> <span class="param">bitcount</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/bignumber/">BigNumber</a></span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/bignumber.ts#L135">source</a></div></div><div class="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><a name="/v5/api/utils/bignumber/-%23-BigNumber--BigNumber--methods--two-s-complement"></a><a name="/v5/api/utils/bignumber/"></a><h3 class="show-anchors"><div>Two's Complement<div class="anchors"><a class="self" href="#/v5/api/utils/bignumber/-%23-BigNumber--BigNumber--methods--two-s-complement"></a></div></div></h3><p><a href="https://en.wikipedia.org/wiki/Two%27s_complement">Two's Complement</a> is an elegant method used to encode and decode fixed-width signed values while efficiently preserving mathematical operations. Most users will not need to interact with these.</p>
|
|
|
|
<div class="property show-anchors"><div class="signature"><span class="path">BigNumber</span><span class="symbol">.</span><span class="method">fromTwos</span><span class="symbol">(</span> <span class="param">bitwidth</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/bignumber/">BigNumber</a></span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/bignumber.ts#L60">source</a></div></div><div class="body"><p>Returns a BigNumber with the value of <i>BigNumber</i> converted from twos-complement with <i>bitwidth</i>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">BigNumber</span><span class="symbol">.</span><span class="method">toTwos</span><span class="symbol">(</span> <span class="param">bitwidth</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/bignumber/">BigNumber</a></span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/bignumber.ts#L64">source</a></div></div><div class="body"><p>Returns a BigNumber with the value of <i>BigNumber</i> converted to twos-complement with <i>bitwidth</i>.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/bignumber/-%23-BigNumber--BigNumber--methods--comparison-and-equivalence"></a><a name="/v5/api/utils/bignumber/"></a><h3 class="show-anchors"><div>Comparison and Equivalence<div class="anchors"><a class="self" href="#/v5/api/utils/bignumber/-%23-BigNumber--BigNumber--methods--comparison-and-equivalence"></a></div></div></h3>
|
|
<div class="property show-anchors"><div class="signature"><span class="path">BigNumber</span><span class="symbol">.</span><span class="method">eq</span><span class="symbol">(</span> <span class="param">otherValue</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">boolean</span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/bignumber.ts#L156">source</a></div></div><div class="body"><p>Returns true if and only if the value of <i>BigNumber</i> is equal to <i>otherValue</i>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">BigNumber</span><span class="symbol">.</span><span class="method">lt</span><span class="symbol">(</span> <span class="param">otherValue</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">boolean</span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/bignumber.ts#L160">source</a></div></div><div class="body"><p>Returns true if and only if the value of <i>BigNumber</i> <b><</b> <i>otherValue</i>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">BigNumber</span><span class="symbol">.</span><span class="method">lte</span><span class="symbol">(</span> <span class="param">otherValue</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">boolean</span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/bignumber.ts#L164">source</a></div></div><div class="body"><p>Returns true if and only if the value of <i>BigNumber</i> <b>≤</b> <i>otherValue</i>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">BigNumber</span><span class="symbol">.</span><span class="method">gt</span><span class="symbol">(</span> <span class="param">otherValue</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">boolean</span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/bignumber.ts#L168">source</a></div></div><div class="body"><p>Returns true if and only if the value of <i>BigNumber</i> <b>></b> <i>otherValue</i>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">BigNumber</span><span class="symbol">.</span><span class="method">gte</span><span class="symbol">(</span> <span class="param">otherValue</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">boolean</span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/bignumber.ts#L172">source</a></div></div><div class="body"><p>Returns true if and only if the value of <i>BigNumber</i> <b>≥</b> <i>otherValue</i>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">BigNumber</span><span class="symbol">.</span><span class="method">isZero</span><span class="symbol">(</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">boolean</span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/bignumber.ts#L180">source</a></div></div><div class="body"><p>Returns true if and only if the value of <i>BigNumber</i> is zero.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/bignumber/-%23-BigNumber--BigNumber--methods--conversion"></a><a name="/v5/api/utils/bignumber/"></a><h3 class="show-anchors"><div>Conversion<div class="anchors"><a class="self" href="#/v5/api/utils/bignumber/-%23-BigNumber--BigNumber--methods--conversion"></a></div></div></h3>
|
|
<div class="property show-anchors"><div class="signature"><span class="path">BigNumber</span><span class="symbol">.</span><span class="method">toNumber</span><span class="symbol">(</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">number</span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/bignumber.ts#L184">source</a></div></div><div class="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><div class="property show-anchors"><div class="signature"><span class="path">BigNumber</span><span class="symbol">.</span><span class="method">toString</span><span class="symbol">(</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/bignumber.ts#L193">source</a></div></div><div class="body"><p>Returns the value of <i>BigNumber</i> as a base-10 string.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">BigNumber</span><span class="symbol">.</span><span class="method">toHexString</span><span class="symbol">(</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a> ></span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/bignumber.ts#L210">source</a></div></div><div class="body"><p>Returns the value of <i>BigNumber</i> as a base-16, <code class="inline">0x</code>-prefixed <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/bignumber/-%23-BigNumber--BigNumber--methods--inspection"></a><a name="/v5/api/utils/bignumber/"></a><h3 class="show-anchors"><div>Inspection<div class="anchors"><a class="self" href="#/v5/api/utils/bignumber/-%23-BigNumber--BigNumber--methods--inspection"></a></div></div></h3>
|
|
<div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">BigNumber</span><span class="symbol">.</span><span class="method">isBigNumber</span><span class="symbol">(</span> <span class="param">object</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">boolean</span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/bignumber.ts#L284">source</a></div></div><div class="body"><p>Returns true if and only if the <i>object</i> is a BigNumber object.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/bignumber/-%23-BigNumber--BigNumber--methods--examples"></a><a name="/v5/api/utils/bignumber/"></a><h3 class="show-anchors"><div>Examples<div class="anchors"><a class="self" href="#/v5/api/utils/bignumber/-%23-BigNumber--BigNumber--methods--examples"></a></div></div></h3>
|
|
<div class="code">let a = BigNumber.from(42);
|
|
let b = BigNumber.from("91");
|
|
|
|
a.mul(b);
|
|
<span class="result ok">// { BigNumber: "3822" }
|
|
</span></div><a name="/v5/api/utils/bignumber/-%23-BigNumber--notes"></a><a name="/v5/api/utils/bignumber/-%23-BigNumber--BigNumber--notes"></a><a name="/v5/api/utils/bignumber/"></a><h2 class="show-anchors"><div>Notes<div class="anchors"><a class="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>
|
|
|
|
<a name="/v5/api/utils/bignumber/-%23-BigNumber--notes-safenumbers"></a><a name="/v5/api/utils/bignumber/-%23-BigNumber--BigNumber--notes--BigNumber--notes-safenumbers"></a><a name="/v5/api/utils/bignumber/"></a><h3 class="show-anchors"><div>Why can't I just use numbers?<div class="anchors"><a class="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 <a href="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>
|
|
|
|
<div class="code">(Number.MAX_SAFE_INTEGER + 2 - 2) == (Number.MAX_SAFE_INTEGER)
|
|
<span class="result ok">// false
|
|
</span></div><p>To remedy this, all numbers (which can be large) are stored and manipulated as <a href="#/v5/api/utils/bignumber/">Big Numbers</a>.</p>
|
|
|
|
<p>The functions <a href="#/v5/api/utils/display-logic/-%23-utils-parseEther">parseEther( etherString )</a> and <a href="#/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>
|
|
|
|
<a name="/v5/api/utils/bignumber/-%23-BigNumber--BigNumber--notes--why-not-bignumber-js-bn-js-bigdecimal-etc"></a><a name="/v5/api/utils/bignumber/"></a><h3 class="show-anchors"><div>Why not BigNumber.js, BN.js, BigDecimal, etc?<div class="anchors"><a class="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 chosen one, it becomes part of their identity, like their editor, vi vs emacs. There are over 100 Big Number libraries on <a href="https://www.npmjs.com/search?q=bignumber">npm</a>.</p>
|
|
|
|
<p>One of the biggest differences between the Ethers <a href="#/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 <a href="#/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 easier to swap out the underlying library without impacting consumers.</p>
|
|
|
|
<p>For example, if <a href="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>
|
|
|
|
<a name="/v5/api/utils/bignumber/-%23-BigNumber--BigNumber--notes--why-bn-js"></a><a name="/v5/api/utils/bignumber/"></a><h3 class="show-anchors"><div>Why BN.js??<div class="anchors"><a class="self" href="#/v5/api/utils/bignumber/-%23-BigNumber--BigNumber--notes--why-bn-js"></a></div></div></h3><p>The reason why <a href="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 <a href="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>
|
|
|
|
<a name="/v5/api/utils/bignumber/-%23-BigNumber--BigNumber--notes--allow-us-to-set-a-global-big-number-library"></a><a name="/v5/api/utils/bignumber/"></a><h3 class="show-anchors"><div>Allow us to set a global Big Number library?<div class="anchors"><a class="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 the 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 <code class="inline">a.plus(b)</code> instead of <code class="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 <a href="#/v5/api/utils/bignumber/">BigNumber</a> prototype is exposed, so you can always add a <code class="inline">toMyCustomBigNumber()</code> method to all <a href="#/v5/api/utils/bignumber/">BigNumber</a>'s globally which is safe.</p>
|
|
|
|
<div class="page-separator"></div><a name="/v5/api/utils/bytes/-%23-byte-manipulation"></a><a name="/v5/api/utils/bytes/"></a><h1 class="show-anchors"><div>Byte Manipulation<div class="anchors"><a class="self" href="#/v5/api/utils/bytes/-%23-byte-manipulation"></a></div></div></h1><p>While there are many high-level APIs for interacting with Ethereum, such as <a href="#/v5/api/contract/contract/">Contracts</a> and <a href="#/v5/api/providers/provider/">Providers</a>, a lot of the low level access requires byte manipulation operations.</p>
|
|
|
|
<p>Many of these operations are used internally, but can also be used to help normalize binary data representations from the output of various functions and methods.</p>
|
|
|
|
<a name="/v5/api/utils/bytes/-%23-byte-manipulation--types"></a><a name="/v5/api/utils/bytes/"></a><h2 class="show-anchors"><div>Types<div class="anchors"><a class="self" href="#/v5/api/utils/bytes/-%23-byte-manipulation--types"></a></div></div></h2>
|
|
<a name="/v5/api/utils/bytes/-%23-Bytes"></a><a name="/v5/api/utils/bytes/-%23-byte-manipulation--types--Bytes"></a><a name="/v5/api/utils/bytes/"></a><h3 class="show-anchors"><div>Bytes<div class="anchors"><a class="self" href="#/v5/api/utils/bytes/-%23-Bytes"></a></div></div></h3><p>A <b>Bytes</b> is any object which is an <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array">Array</a> or <a href="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 <code class="inline">length</code> property where each indexed property is in the valid byte range.</p>
|
|
|
|
<a name="/v5/api/utils/bytes/-%23-BytesLike"></a><a name="/v5/api/utils/bytes/-%23-byte-manipulation--types--BytesLike"></a><a name="/v5/api/utils/bytes/"></a><h3 class="show-anchors"><div>BytesLike<div class="anchors"><a class="self" href="#/v5/api/utils/bytes/-%23-BytesLike"></a></div></div></h3><p>A <b>BytesLike</b> can be either a <a href="#/v5/api/utils/bytes/-%23-Bytes">Bytes</a> or a <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>.</p>
|
|
|
|
<a name="/v5/api/utils/bytes/-%23-DataHexString"></a><a name="/v5/api/utils/bytes/-%23-byte-manipulation--types--DataHexString"></a><a name="/v5/api/utils/bytes/"></a><h3 class="show-anchors"><div>DataHexString<div class="anchors"><a class="self" href="#/v5/api/utils/bytes/-%23-DataHexString"></a></div></div></h3><p>A <b>DataHexstring</b> is identical to a <a href="#/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>
|
|
|
|
<a name="/v5/api/utils/bytes/-%23-HexString"></a><a name="/v5/api/utils/bytes/-%23-byte-manipulation--types--HexString"></a><a name="/v5/api/utils/bytes/"></a><h3 class="show-anchors"><div>HexString<div class="anchors"><a class="self" href="#/v5/api/utils/bytes/-%23-HexString"></a></div></div></h3><p>A <b>Hexstring</b> is a string which has a <code class="inline">0x</code> prefix followed by any number of nibbles (i.e. case-insensitive hexadecimal characters, <code class="inline">0-9</code> and <code class="inline">a-f</code>).</p>
|
|
|
|
<a name="/v5/api/utils/bytes/-%23-Signature"></a><a name="/v5/api/utils/bytes/-%23-byte-manipulation--types--Signature"></a><a name="/v5/api/utils/bytes/"></a><h3 class="show-anchors"><div>Signature<div class="anchors"><a class="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 <a href="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>
|
|
|
|
<a name="/v5/api/utils/bytes/-%23-signature-raw"></a><a name="/v5/api/utils/bytes/-%23-byte-manipulation--types--signature-raw"></a><a name="/v5/api/utils/bytes/"></a><h3 class="show-anchors"><div>Raw Signature<span class="inherits"> inherits string<<a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a><65>></span><div class="anchors"><a class="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 concatenated into a 65 byte (130 nibble) <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>.</p>
|
|
|
|
<a name="/v5/api/utils/bytes/-%23-SignatureLike"></a><a name="/v5/api/utils/bytes/-%23-byte-manipulation--types--SignatureLike"></a><a name="/v5/api/utils/bytes/"></a><h3 class="show-anchors"><div>SignatureLike<div class="anchors"><a class="self" href="#/v5/api/utils/bytes/-%23-SignatureLike"></a></div></div></h3><p>A <b>SignatureLike</b> is similar to a <a href="#/v5/api/utils/bytes/-%23-Signature">Signature</a>, except redundant properties may be omitted or it may be a <a href="#/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>
|
|
|
|
<a name="/v5/api/utils/bytes/-%23-byte-manipulation--inspection"></a><a name="/v5/api/utils/bytes/"></a><h2 class="show-anchors"><div>Inspection<div class="anchors"><a class="self" href="#/v5/api/utils/bytes/-%23-byte-manipulation--inspection"></a></div></div></h2>
|
|
<a name="/v5/api/utils/bytes/-%23-utils-isBytes"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">isBytes</span><span class="symbol">(</span> <span class="param">object</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">boolean</span><div class="anchors"><a class="self" href="#/v5/api/utils/bytes/-%23-utils-isBytes"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bytes/src.ts/index.ts#L73">source</a></div></div><div class="body"><p>Returns true if and only if <i>object</i> is a valid <a href="#/v5/api/utils/bytes/-%23-Bytes">Bytes</a>.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/bytes/-%23-utils-isBytesLike"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">isBytesLike</span><span class="symbol">(</span> <span class="param">object</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">boolean</span><div class="anchors"><a class="self" href="#/v5/api/utils/bytes/-%23-utils-isBytesLike"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bytes/src.ts/index.ts#L69">source</a></div></div><div class="body"><p>Returns true if and only if <i>object</i> is a <a href="#/v5/api/utils/bytes/-%23-Bytes">Bytes</a> or <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/bytes/-%23-utils-isHexString"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">isHexString</span><span class="symbol">(</span> <span class="param">object</span> <span class="symbol">,</span> <span class="symbol">[</span> <span class="param">length</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">boolean</span><div class="anchors"><a class="self" href="#/v5/api/utils/bytes/-%23-utils-isHexString"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bytes/src.ts/index.ts#L183">source</a></div></div><div class="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 <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a> of <i>length</i> bytes, an InvalidArgument error is thrown.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/bytes/-%23-byte-manipulation--converting-between-arrays-and-hexstrings"></a><a name="/v5/api/utils/bytes/"></a><h2 class="show-anchors"><div>Converting between Arrays and Hexstrings<div class="anchors"><a class="self" href="#/v5/api/utils/bytes/-%23-byte-manipulation--converting-between-arrays-and-hexstrings"></a></div></div></h2>
|
|
<a name="/v5/api/utils/bytes/-%23-utils-arrayify"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">arrayify</span><span class="symbol">(</span> <span class="param">DataHexStringOrArrayish</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">options</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Uint8Array</span><div class="anchors"><a class="self" href="#/v5/api/utils/bytes/-%23-utils-arrayify"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bytes/src.ts/index.ts#L90">source</a></div></div><div class="body"><p>Converts <i>DataHexStringOrArrayish</i> to a Uint8Array.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/bytes/-%23-utils-hexlify"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">hexlify</span><span class="symbol">(</span> <span class="param">hexstringOrArrayish</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a> ></span><div class="anchors"><a class="self" href="#/v5/api/utils/bytes/-%23-utils-hexlify"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bytes/src.ts/index.ts#L193">source</a></div></div><div class="body"><p>Converts <i>hexstringOrArrayish</i> to a <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/bytes/-%23-utils-hexValue"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">hexValue</span><span class="symbol">(</span> <span class="param">aBigNumberish</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-HexString">HexString</a> ></span><div class="anchors"><a class="self" href="#/v5/api/utils/bytes/-%23-utils-hexValue"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bytes/src.ts/index.ts#L286">source</a></div></div><div class="body"><p>Converts <i>aBigNumberish</i> to a <a href="#/v5/api/utils/bytes/-%23-HexString">HexString</a>, with no <u>unnecessary</u> leading zeros.</p>
|
|
|
|
</div></div><div class="code-title"><div>Examples</div></div><div class="code"><span class="comment">// Convert a hexstring to a Uint8Array
|
|
</span>arrayify("0x1234")
|
|
<span class="result ok">// Uint8Array [ 18, 52 ]
|
|
</span>
|
|
<span class="comment">// Convert an Array to a hexstring
|
|
</span>hexlify([1, 2, 3, 4])
|
|
<span class="result ok">// '0x01020304'
|
|
</span>
|
|
<span class="comment">// Convert an Object to a hexstring
|
|
</span>hexlify({ length: 2, "0": 1, "1": 2 })
|
|
<span class="result ok">// '0x0102'
|
|
</span>
|
|
<span class="comment">// Convert an Array to a hexstring
|
|
</span>hexlify([ 1 ])
|
|
<span class="result ok">// '0x01'
|
|
</span>
|
|
<span class="comment">// Convert a number to a stripped hex value
|
|
</span>hexValue(1)
|
|
<span class="result ok">// '0x1'
|
|
</span>
|
|
<span class="comment">// Convert an Array to a stripped hex value
|
|
</span>hexValue([ 1, 2 ])
|
|
<span class="result ok">// '0x102'
|
|
</span></div><a name="/v5/api/utils/bytes/-%23-byte-manipulation--array-manipulation"></a><a name="/v5/api/utils/bytes/"></a><h2 class="show-anchors"><div>Array Manipulation<div class="anchors"><a class="self" href="#/v5/api/utils/bytes/-%23-byte-manipulation--array-manipulation"></a></div></div></h2>
|
|
<a name="/v5/api/utils/bytes/-%23-utils-concat"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">concat</span><span class="symbol">(</span> <span class="param">arrayOfBytesLike</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Uint8Array</span><div class="anchors"><a class="self" href="#/v5/api/utils/bytes/-%23-utils-concat"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bytes/src.ts/index.ts#L139">source</a></div></div><div class="body"><p>Concatenates all the <a href="#/v5/api/utils/bytes/-%23-BytesLike">BytesLike</a> in <i>arrayOfBytesLike</i> into a single Uint8Array.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/bytes/-%23-utils-stripZeros"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">stripZeros</span><span class="symbol">(</span> <span class="param">aBytesLike</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Uint8Array</span><div class="anchors"><a class="self" href="#/v5/api/utils/bytes/-%23-utils-stripZeros"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bytes/src.ts/index.ts#L153">source</a></div></div><div class="body"><p>Returns a Uint8Array with all leading <code class="inline">0</code> bytes of <i>aBtyesLike</i> removed.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/bytes/-%23-utils-zeroPad"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">zeroPad</span><span class="symbol">(</span> <span class="param">aBytesLike</span> <span class="symbol">,</span> <span class="param">length</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Uint8Array</span><div class="anchors"><a class="self" href="#/v5/api/utils/bytes/-%23-utils-zeroPad"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bytes/src.ts/index.ts#L170">source</a></div></div><div class="body"><p>Returns a Uint8Array of the data in <i>aBytesLike</i> with <code class="inline">0</code> bytes prepended to <i>length</i> bytes long.</p>
|
|
|
|
<p>If <i>aBytesLike</i> is already longer than <i>length</i> bytes long, an InvalidArgument error will be thrown.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/bytes/-%23-byte-manipulation--hexstring-manipulation"></a><a name="/v5/api/utils/bytes/"></a><h2 class="show-anchors"><div>Hexstring Manipulation<div class="anchors"><a class="self" href="#/v5/api/utils/bytes/-%23-byte-manipulation--hexstring-manipulation"></a></div></div></h2>
|
|
<a name="/v5/api/utils/bytes/-%23-utils-hexConcat"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">hexConcat</span><span class="symbol">(</span> <span class="param">arrayOfBytesLike</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a> ></span><div class="anchors"><a class="self" href="#/v5/api/utils/bytes/-%23-utils-hexConcat"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bytes/src.ts/index.ts#L278">source</a></div></div><div class="body"><p>Concatenates all the <a href="#/v5/api/utils/bytes/-%23-BytesLike">BytesLike</a> in <i>arrayOfBytesLike</i> into a single <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a></p>
|
|
|
|
</div></div><a name="/v5/api/utils/bytes/-%23-utils-hexDataLength"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">hexDataLength</span><span class="symbol">(</span> <span class="param">aBytesLike</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a> ></span><div class="anchors"><a class="self" href="#/v5/api/utils/bytes/-%23-utils-hexDataLength"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bytes/src.ts/index.ts#L252">source</a></div></div><div class="body"><p>Returns the length (in bytes) of <i>aBytesLike</i>.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/bytes/-%23-utils-hexDataSlice"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">hexDataSlice</span><span class="symbol">(</span> <span class="param">aBytesLike</span> <span class="symbol">,</span> <span class="param">offset</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">endOffset</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a> ></span><div class="anchors"><a class="self" href="#/v5/api/utils/bytes/-%23-utils-hexDataSlice"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bytes/src.ts/index.ts#L262">source</a></div></div><div class="body"><p>Returns a <a href="#/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><a name="/v5/api/utils/bytes/-%23-utils-hexStripZeros"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">hexStripZeros</span><span class="symbol">(</span> <span class="param">aBytesLike</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-HexString">HexString</a> ></span><div class="anchors"><a class="self" href="#/v5/api/utils/bytes/-%23-utils-hexStripZeros"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bytes/src.ts/index.ts#L292">source</a></div></div><div class="body"><p>Returns a <a href="#/v5/api/utils/bytes/-%23-HexString">HexString</a> representation of <i>aBytesLike</i> with all leading zeros removed.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/bytes/-%23-utils-hexZeroPad"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">hexZeroPad</span><span class="symbol">(</span> <span class="param">aBytesLike</span> <span class="symbol">,</span> <span class="param">length</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a> ></span><div class="anchors"><a class="self" href="#/v5/api/utils/bytes/-%23-utils-hexZeroPad"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bytes/src.ts/index.ts#L304">source</a></div></div><div class="body"><p>Returns a <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a> representation of <i>aBytesLike</i> padded to <i>length</i> bytes.</p>
|
|
|
|
<p>If <i>aBytesLike</i> is already longer than <i>length</i> bytes long, an InvalidArgument error will be thrown.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/bytes/-%23-byte-manipulation--signature-conversion"></a><a name="/v5/api/utils/bytes/"></a><h2 class="show-anchors"><div>Signature Conversion<div class="anchors"><a class="self" href="#/v5/api/utils/bytes/-%23-byte-manipulation--signature-conversion"></a></div></div></h2>
|
|
<a name="/v5/api/utils/bytes/-%23-utils-joinSignature"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">joinSignature</span><span class="symbol">(</span> <span class="param">aSignatureLike</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-signature-raw">RawSignature</a> ></span><div class="anchors"><a class="self" href="#/v5/api/utils/bytes/-%23-utils-joinSignature"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bytes/src.ts/index.ts#L441">source</a></div></div><div class="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><a name="/v5/api/utils/bytes/-%23-utils-splitSignature"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">splitSignature</span><span class="symbol">(</span> <span class="param">aSignatureLikeOrBytesLike</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/bytes/-%23-Signature">Signature</a></span><div class="anchors"><a class="self" href="#/v5/api/utils/bytes/-%23-utils-splitSignature"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bytes/src.ts/index.ts#L322">source</a></div></div><div class="body"><p>Return the full expanded-format of <i>aSignaturelike</i> or a raw-format <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>. Any missing properties will be computed.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/bytes/-%23-byte-manipulation--random-bytes"></a><a name="/v5/api/utils/bytes/"></a><h2 class="show-anchors"><div>Random Bytes<div class="anchors"><a class="self" href="#/v5/api/utils/bytes/-%23-byte-manipulation--random-bytes"></a></div></div></h2>
|
|
<a name="/v5/api/utils/bytes/-%23-utils-randomBytes"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">randomBytes</span><span class="symbol">(</span> <span class="param">length</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Uint8Array</span><div class="anchors"><a class="self" href="#/v5/api/utils/bytes/-%23-utils-randomBytes"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/random/src.ts/random.ts#L5">source</a></div></div><div class="body"><p>Return a new Uint8Array of <i>length</i> random bytes.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/bytes/-%23-utils-shuffled"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">shuffled</span><span class="symbol">(</span> <span class="param">array</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Array< any ></span><div class="anchors"><a class="self" href="#/v5/api/utils/bytes/-%23-utils-shuffled"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/random/src.ts/shuffle.ts#L3">source</a></div></div><div class="body"><p>Return a copy of <i>array</i> shuffled using <a href="https://en.wikipedia.org/wiki/Fisher-Yates_shuffle">Fisher-Yates Shuffle</a>.</p>
|
|
|
|
</div></div><div class="code-title"><div>Examples</div></div><div class="code">utils.randomBytes(8)
|
|
<span class="result ok">// Uint8Array [ 97, 223, 223, 186, 224, 0, 90, 28 ]
|
|
</span>
|
|
const data = [ 1, 2, 3, 4, 5, 6, 7 ];
|
|
|
|
<span class="comment">// Returns a new Array
|
|
</span>utils.shuffled(data);
|
|
<span class="result ok">// [
|
|
</span><span class="result ok">// 5,
|
|
</span><span class="result ok">// 3,
|
|
</span><span class="result ok">// 1,
|
|
</span><span class="result ok">// 4,
|
|
</span><span class="result ok">// 6,
|
|
</span><span class="result ok">// 7,
|
|
</span><span class="result ok">// 2
|
|
</span><span class="result ok">// ]
|
|
</span>
|
|
<span class="comment">// The Original is unscathed...
|
|
</span>data
|
|
<span class="result ok">// [
|
|
</span><span class="result ok">// 1,
|
|
</span><span class="result ok">// 2,
|
|
</span><span class="result ok">// 3,
|
|
</span><span class="result ok">// 4,
|
|
</span><span class="result ok">// 5,
|
|
</span><span class="result ok">// 6,
|
|
</span><span class="result ok">// 7
|
|
</span><span class="result ok">// ]
|
|
</span></div><div class="page-separator"></div><a name="/v5/api/utils/constants/-%23-constants"></a><a name="/v5/api/utils/constants/-%23-constants"></a><a name="/v5/api/utils/constants/"></a><h1 class="show-anchors"><div>Constants<div class="anchors"><a class="self" href="#/v5/api/utils/constants/-%23-constants"></a></div></div></h1><p>The <b>ethers.contants</b> Object contains commonly used values.</p>
|
|
|
|
<a name="/v5/api/utils/constants/-%23-constants--bytes"></a><a name="/v5/api/utils/constants/"></a><h2 class="show-anchors"><div>Bytes<div class="anchors"><a class="self" href="#/v5/api/utils/constants/-%23-constants--bytes"></a></div></div></h2>
|
|
<a name="/v5/api/utils/constants/-%23-constants-AddressZero"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">constants</span><span class="symbol">.</span><span class="method">AddressZero</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/address/-%23-address">Address</a> ></span><div class="anchors"><a class="self" href="#/v5/api/utils/constants/-%23-constants-AddressZero"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/constants/src.ts/addresses.ts#L1">source</a></div></div><div class="body"><p>The Address Zero, which is 20 bytes (40 nibbles) of zero.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/constants/-%23-constants-HashZero"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">constants</span><span class="symbol">.</span><span class="method">HashZero</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 > ></span><div class="anchors"><a class="self" href="#/v5/api/utils/constants/-%23-constants-HashZero"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/constants/src.ts/hashes.ts#L1">source</a></div></div><div class="body"><p>The Hash Zero, which is 32 bytes (64 nibbles) of zero.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/constants/-%23-constants--strings"></a><a name="/v5/api/utils/constants/"></a><h2 class="show-anchors"><div>Strings<div class="anchors"><a class="self" href="#/v5/api/utils/constants/-%23-constants--strings"></a></div></div></h2>
|
|
<a name="/v5/api/utils/constants/-%23-constants-EtherSymbol"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">constants</span><span class="symbol">.</span><span class="method">EtherSymbol</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"><a class="self" href="#/v5/api/utils/constants/-%23-constants-EtherSymbol"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/constants/src.ts/strings.ts#L2">source</a></div></div><div class="body"><p>The Ether symbol, <b>Ξ</b>.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/constants/-%23-constants--bignumber"></a><a name="/v5/api/utils/constants/"></a><h2 class="show-anchors"><div>BigNumber<div class="anchors"><a class="self" href="#/v5/api/utils/constants/-%23-constants--bignumber"></a></div></div></h2>
|
|
<a name="/v5/api/utils/constants/-%23-constants-NegativeOne"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">constants</span><span class="symbol">.</span><span class="method">NegativeOne</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/bignumber/">BigNumber</a></span><div class="anchors"><a class="self" href="#/v5/api/utils/constants/-%23-constants-NegativeOne"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/constants/src.ts/bignumbers.ts#L3">source</a></div></div><div class="body"><p>The BigNumber value representing <code class="inline">"-1"</code>.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/constants/-%23-constants-Zero"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">constants</span><span class="symbol">.</span><span class="method">Zero</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/bignumber/">BigNumber</a></span><div class="anchors"><a class="self" href="#/v5/api/utils/constants/-%23-constants-Zero"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/constants/src.ts/bignumbers.ts#L4">source</a></div></div><div class="body"><p>The BigNumber value representing <code class="inline">"0"</code>.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/constants/-%23-constants-One"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">constants</span><span class="symbol">.</span><span class="method">One</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/bignumber/">BigNumber</a></span><div class="anchors"><a class="self" href="#/v5/api/utils/constants/-%23-constants-One"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/constants/src.ts/bignumbers.ts#L5">source</a></div></div><div class="body"><p>The BigNumber value representing <code class="inline">"1"</code>.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/constants/-%23-constants-Two"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">constants</span><span class="symbol">.</span><span class="method">Two</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/bignumber/">BigNumber</a></span><div class="anchors"><a class="self" href="#/v5/api/utils/constants/-%23-constants-Two"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/constants/src.ts/bignumbers.ts#L6">source</a></div></div><div class="body"><p>The BigNumber value representing <code class="inline">"2"</code>.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/constants/-%23-constants-WeiPerEther"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">constants</span><span class="symbol">.</span><span class="method">WeiPerEther</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/bignumber/">BigNumber</a></span><div class="anchors"><a class="self" href="#/v5/api/utils/constants/-%23-constants-WeiPerEther"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/constants/src.ts/bignumbers.ts#L7">source</a></div></div><div class="body"><p>The BigNumber value representing <code class="inline">"1000000000000000000"</code>, which is the number of Wei per Ether.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/constants/-%23-constants-MaxUint256"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">constants</span><span class="symbol">.</span><span class="method">MaxUint256</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/bignumber/">BigNumber</a></span><div class="anchors"><a class="self" href="#/v5/api/utils/constants/-%23-constants-MaxUint256"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/constants/src.ts/bignumbers.ts#L8">source</a></div></div><div class="body"><p>The BigNumber value representing the maximum <code class="inline">uint256</code> value.</p>
|
|
|
|
</div></div><div class="page-separator"></div><a name="/v5/api/utils/display-logic/-%23-display-logic"></a><a name="/v5/api/utils/display-logic/-%23-display-logic"></a><a name="/v5/api/utils/display-logic/"></a><h1 class="show-anchors"><div>Display Logic and Input<div class="anchors"><a class="self" href="#/v5/api/utils/display-logic/-%23-display-logic"></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 <a href="#/v5/api/utils/display-logic/-%23-unit-conversion">parseUnits</a> will parse a string representing ether, such as <code class="inline">1.1</code> into a <a href="#/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 <a href="#/v5/api/utils/display-logic/-%23-unit-conversion">formatUnits</a> will format a <a href="#/v5/api/utils/bignumber/-%23-BigNumberish">BigNumberish</a> into a string, which is useful when displaying a balance.</p>
|
|
|
|
<a name="/v5/api/utils/display-logic/-%23-display-logic--units"></a><a name="/v5/api/utils/display-logic/-%23-display-logic--display-logic--units"></a><a name="/v5/api/utils/display-logic/"></a><h2 class="show-anchors"><div>Units<div class="anchors"><a class="self" href="#/v5/api/utils/display-logic/-%23-display-logic--units"></a></div></div></h2>
|
|
<a name="/v5/api/utils/display-logic/-%23-display-logic--display-logic--units--decimal-count"></a><a name="/v5/api/utils/display-logic/"></a><h3 class="show-anchors"><div>Decimal Count<div class="anchors"><a class="self" href="#/v5/api/utils/display-logic/-%23-display-logic--display-logic--units--decimal-count"></a></div></div></h3><p>A <b>Unit</b> can be specified as a 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>
|
|
|
|
<a name="/v5/api/utils/display-logic/-%23-display-logic--named-units"></a><a name="/v5/api/utils/display-logic/-%23-display-logic--display-logic--units--display-logic--named-units"></a><a name="/v5/api/utils/display-logic/"></a><h3 class="show-anchors"><div>Named Units<div class="anchors"><a class="self" href="#/v5/api/utils/display-logic/-%23-display-logic--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>
|
|
|
|
<table class="table compact"><tr><td align="center" width="50%"><b>Name</b></td><td align="center" width="50%"><b>Decimals</b></td><td class="fix"> </td></tr><tr><td align="center" width="50%"><i>wei</i></td><td align="center" width="50%">0</td><td class="fix"> </td></tr><tr><td align="center" width="50%"><i>kwei</i></td><td align="center" width="50%">3</td><td class="fix"> </td></tr><tr><td align="center" width="50%"><i>mwei</i></td><td align="center" width="50%">6</td><td class="fix"> </td></tr><tr><td align="center" width="50%"><i>gwei</i></td><td align="center" width="50%">9</td><td class="fix"> </td></tr><tr><td align="center" width="50%"><i>szabo</i></td><td align="center" width="50%">12</td><td class="fix"> </td></tr><tr><td align="center" width="50%"><i>finney</i></td><td align="center" width="50%">15</td><td class="fix"> </td></tr><tr><td align="center" width="50%"><i>ether</i></td><td align="center" width="50%">18</td><td class="fix"> </td></tr></table><a name="/v5/api/utils/display-logic/-%23-display-logic--functions"></a><a name="/v5/api/utils/display-logic/-%23-display-logic--display-logic--functions"></a><a name="/v5/api/utils/display-logic/"></a><h2 class="show-anchors"><div>Functions<div class="anchors"><a class="self" href="#/v5/api/utils/display-logic/-%23-display-logic--functions"></a></div></div></h2>
|
|
<a name="/v5/api/utils/display-logic/-%23-display-logic--formatting"></a><a name="/v5/api/utils/display-logic/-%23-display-logic--display-logic--functions--display-logic--formatting"></a><a name="/v5/api/utils/display-logic/"></a><h3 class="show-anchors"><div>Formatting<div class="anchors"><a class="self" href="#/v5/api/utils/display-logic/-%23-display-logic--formatting"></a></div></div></h3>
|
|
<a name="/v5/api/utils/display-logic/-%23-utils-commify"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">commify</span><span class="symbol">(</span> <span class="param">value</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"><a class="self" href="#/v5/api/utils/display-logic/-%23-utils-commify"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/units/src.ts/index.ts#L23">source</a></div></div><div class="body"><p>Returns a string with value grouped by 3 digits, separated by <code class="inline">,</code>.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/display-logic/-%23-unit-conversion"></a><a name="/v5/api/utils/display-logic/-%23-display-logic--display-logic--functions--unit-conversion"></a><a name="/v5/api/utils/display-logic/"></a><h3 class="show-anchors"><div>Conversion<div class="anchors"><a class="self" href="#/v5/api/utils/display-logic/-%23-unit-conversion"></a></div></div></h3>
|
|
<a name="/v5/api/utils/display-logic/-%23-utils-formatUnits"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">formatUnits</span><span class="symbol">(</span> <span class="param">value</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">unit</span> = "<span class="param">ether</span>" <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"><a class="self" href="#/v5/api/utils/display-logic/-%23-utils-formatUnits"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/units/src.ts/index.ts#L64">source</a></div></div><div class="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><a name="/v5/api/utils/display-logic/-%23-utils-formatEther"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">formatEther</span><span class="symbol">(</span> <span class="param">value</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"><a class="self" href="#/v5/api/utils/display-logic/-%23-utils-formatEther"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/units/src.ts/index.ts#L83">source</a></div></div><div class="body"><p>The equivalent to calling <code class="inline">formatUnits(value, "ether")</code>.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/display-logic/-%23-utils-parseUnits"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">parseUnits</span><span class="symbol">(</span> <span class="param">value</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">unit</span> = "<span class="param">ether</span>" <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/bignumber/">BigNumber</a></span><div class="anchors"><a class="self" href="#/v5/api/utils/display-logic/-%23-utils-parseUnits"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/units/src.ts/index.ts#L72">source</a></div></div><div class="body"><p>Returns a <a href="#/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>
|
|
|
|
</div></div><a name="/v5/api/utils/display-logic/-%23-utils-parseEther"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">parseEther</span><span class="symbol">(</span> <span class="param">value</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/bignumber/">BigNumber</a></span><div class="anchors"><a class="self" href="#/v5/api/utils/display-logic/-%23-utils-parseEther"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/units/src.ts/index.ts#L87">source</a></div></div><div class="body"><p>The equivalent to calling <code class="inline">parseUnits(value, "ether")</code>.</p>
|
|
|
|
</div></div><div class="page-separator"></div><a name="/v5/api/utils/encoding/-%23-encoding"></a><a name="/v5/api/utils/encoding/-%23-encoding"></a><a name="/v5/api/utils/encoding/"></a><h1 class="show-anchors"><div>Encoding Utilities<div class="anchors"><a class="self" href="#/v5/api/utils/encoding/-%23-encoding"></a></div></div></h1>
|
|
<a name="/v5/api/utils/encoding/-%23-Bse58"></a><a name="/v5/api/utils/encoding/-%23-encoding--Bse58"></a><a name="/v5/api/utils/encoding/"></a><h2 class="show-anchors"><div>Base58<div class="anchors"><a class="self" href="#/v5/api/utils/encoding/-%23-Bse58"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/basex/src.ts/index.ts#L138">source</a></div></div></h2>
|
|
<div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="path">base58</span><span class="symbol">.</span><span class="method">decode</span><span class="symbol">(</span> <span class="param">textData</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Uin8Array</span><div class="anchors"></div></div><div class="body"><p>Return a typed Uint8Array representation of <i>textData</i> decoded using base-58 encoding.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="path">base58</span><span class="symbol">.</span><span class="method">encode</span><span class="symbol">(</span> <span class="param">aBytesLike</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"></div></div><div class="body"><p>Return <i>aBytesLike</i> encoded as a string using the base-58 encoding.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/encoding/-%23-Base64"></a><a name="/v5/api/utils/encoding/-%23-encoding--Base64"></a><a name="/v5/api/utils/encoding/"></a><h2 class="show-anchors"><div>Base64<div class="anchors"><a class="self" href="#/v5/api/utils/encoding/-%23-Base64"></a></div></div></h2>
|
|
<div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="path">base64</span><span class="symbol">.</span><span class="method">decode</span><span class="symbol">(</span> <span class="param">textData</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Uin8Array</span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/base64/src.ts/base64.ts#L6">source</a></div></div><div class="body"><p>Return a typed Uint8Array representation of <i>textData</i> decoded using base-64 encoding.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="path">base64</span><span class="symbol">.</span><span class="method">encode</span><span class="symbol">(</span> <span class="param">aBytesLike</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/base64/src.ts/base64.ts#L10">source</a></div></div><div class="body"><p>Return <i>aBytesLike</i> encoded as a string using the base-64 encoding.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/encoding/-%23-rlp--methods"></a><a name="/v5/api/utils/encoding/-%23-encoding--rlp--methods"></a><a name="/v5/api/utils/encoding/"></a><h2 class="show-anchors"><div>Recursive-Length Prefix<div class="anchors"><a class="self" href="#/v5/api/utils/encoding/-%23-rlp--methods"></a></div></div></h2><p>The <a href="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>
|
|
|
|
<a name="/v5/api/utils/encoding/-%23-utils-rlpEncode"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="path">RLP</span><span class="symbol">.</span><span class="method">encode</span><span class="symbol">(</span> <span class="param">dataObject</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a> ></span><div class="anchors"><a class="self" href="#/v5/api/utils/encoding/-%23-utils-rlpEncode"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/rlp/src.ts/index.ts#L67">source</a></div></div><div class="body"><p>Encode a structured Data Object into its RLP-encoded representation.</p>
|
|
|
|
<p>Each Data component may be a valid <a href="#/v5/api/utils/bytes/-%23-BytesLike">BytesLike</a>.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/encoding/-%23-utils.rlpDecode"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="path">RLP</span><span class="symbol">.</span><span class="method">decode</span><span class="symbol">(</span> <span class="param">aBytesLike</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/encoding/-%23-rlp--dataobject">DataObject</a></span><div class="anchors"><a class="self" href="#/v5/api/utils/encoding/-%23-utils.rlpDecode"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/rlp/src.ts/index.ts#L147">source</a></div></div><div class="body"><p>Decode an RLP-encoded <i>aBytesLike</i> into its structured Data Object.</p>
|
|
|
|
<p>All Data components will be returned as a <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/encoding/-%23-rlp--dataobject"></a><a name="/v5/api/utils/encoding/-%23-encoding--rlp--methods--rlp--dataobject"></a><a name="/v5/api/utils/encoding/"></a><h3 class="show-anchors"><div>Data Object<div class="anchors"><a class="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 class="definition"><div class="term"><b>Examples</b></div><div class="body"><p><ul><li><code class="inline">"0x1234"</code> </li><li><code class="inline">[ "0x1234", [ "0xdead", "0xbeef" ], [ ] ]</code> </li></ul></p>
|
|
|
|
</div></div><div class="page-separator"></div><a name="/v5/api/utils/fixednumber/-%23-FixedNumber"></a><a name="/v5/api/utils/fixednumber/-%23-FixedNumber"></a><a name="/v5/api/utils/fixednumber/"></a><h1 class="show-anchors"><div>FixedNumber<div class="anchors"><a class="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>
|
|
|
|
<a name="/v5/api/utils/fixednumber/-%23-FixedNumber--creating-instances"></a><a name="/v5/api/utils/fixednumber/"></a><h2 class="show-anchors"><div>Creating Instances<div class="anchors"><a class="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>
|
|
|
|
<div class="property show-anchors"><div class="signature"><span class="path">FixedNumber</span><span class="symbol">.</span><span class="method">from</span><span class="symbol">(</span> <span class="param">value</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">format</span> = "<span class="param">fixed</span>" <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/fixednumber/">FixedNumber</a></span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/fixednumber.ts#L366">source</a></div></div><div class="body"><p>Returns an instance of a <b>FixedNumber</b> for <i>value</i> as a <i>format</i>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">FixedNumber</span><span class="symbol">.</span><span class="method">fromBytes</span><span class="symbol">(</span> <span class="param">aBytesLike</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">format</span> = "<span class="param">fixed</span>" <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/fixednumber/">FixedNumber</a></span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/fixednumber.ts#L348">source</a></div></div><div class="body"><p>Returns an instance of a <b>FixedNumber</b> for <i>value</i> as a <i>format</i>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">FixedNumber</span><span class="symbol">.</span><span class="method">fromString</span><span class="symbol">(</span> <span class="param">value</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">format</span> = "<span class="param">fixed</span>" <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/fixednumber/">FixedNumber</a></span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/fixednumber.ts#L324">source</a></div></div><div class="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><div class="property show-anchors"><div class="signature"><span class="path">FixedNumber</span><span class="symbol">.</span><span class="method">fromValue</span><span class="symbol">(</span> <span class="param">value</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">decimals</span> = <span class="param">0</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">format</span> = "<span class="param">fixed</span>" <span class="symbol">]</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/fixednumber/">FixedNumber</a></span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/fixednumber.ts#L310">source</a></div></div><div class="body"><p>Returns an instance of a <b>FixedNumber</b> for <i>value</i> with <i>decimals</i> as a <i>format</i>.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/fixednumber/-%23-FixedNumber--properties"></a><a name="/v5/api/utils/fixednumber/"></a><h2 class="show-anchors"><div>Properties<div class="anchors"><a class="self" href="#/v5/api/utils/fixednumber/-%23-FixedNumber--properties"></a></div></div></h2>
|
|
<div class="property show-anchors"><div class="signature"><span class="path">fixednumber</span><span class="symbol">.</span><span class="method">format</span><div class="anchors"></div></div><div class="body"><p>The <a href="#/v5/api/utils/fixednumber/-%23-FixedFormat">FixedFormat</a> of <i>fixednumber</i>.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/fixednumber/-%23-FixedNumber--methods"></a><a name="/v5/api/utils/fixednumber/"></a><h2 class="show-anchors"><div>Methods<div class="anchors"><a class="self" href="#/v5/api/utils/fixednumber/-%23-FixedNumber--methods"></a></div></div></h2>
|
|
<a name="/v5/api/utils/fixednumber/-%23-FixedNumber--methods--math-operations"></a><a name="/v5/api/utils/fixednumber/"></a><h3 class="show-anchors"><div>Math Operations<div class="anchors"><a class="self" href="#/v5/api/utils/fixednumber/-%23-FixedNumber--methods--math-operations"></a></div></div></h3>
|
|
<div class="property show-anchors"><div class="signature"><span class="path">fixednumber</span><span class="symbol">.</span><span class="method">addUnsafe</span><span class="symbol">(</span> <span class="param">otherValue</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/fixednumber/">FixedNumber</a></span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/fixednumber.ts#L215">source</a></div></div><div class="body"><p>Returns a new FixedNumber with the value of <i>fixedvalue</i> <b>+</b> <i>otherValue</i>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">fixednumber</span><span class="symbol">.</span><span class="method">subUnsafe</span><span class="symbol">(</span> <span class="param">otherValue</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/fixednumber/">FixedNumber</a></span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/fixednumber.ts#L222">source</a></div></div><div class="body"><p>Returns a new FixedNumber with the value of <i>fixedvalue</i> <b>-</b> <i>otherValue</i>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">fixednumber</span><span class="symbol">.</span><span class="method">mulUnsafe</span><span class="symbol">(</span> <span class="param">otherValue</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/fixednumber/">FixedNumber</a></span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/fixednumber.ts#L229">source</a></div></div><div class="body"><p>Returns a new FixedNumber with the value of <i>fixedvalue</i> <b>×</b> <i>otherValue</i>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">fixednumber</span><span class="symbol">.</span><span class="method">divUnsafe</span><span class="symbol">(</span> <span class="param">otherValue</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/fixednumber/">FixedNumber</a></span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/fixednumber.ts#L236">source</a></div></div><div class="body"><p>Returns a new FixedNumber with the value of <i>fixedvalue</i> <b>÷</b> <i>otherValue</i>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">fixednumber</span><span class="symbol">.</span><span class="method">round</span><span class="symbol">(</span> <span class="symbol">[</span> <span class="param">decimals</span> = <span class="param">0</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/fixednumber/">FixedNumber</a></span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/fixednumber.ts#L270">source</a></div></div><div class="body"><p>Returns a new FixedNumber with the value of <i>fixedvalue</i> rounded to <i>decimals</i>.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/fixednumber/-%23-FixedNumber--methods--comparison-and-equivalence"></a><a name="/v5/api/utils/fixednumber/"></a><h3 class="show-anchors"><div>Comparison and Equivalence<div class="anchors"><a class="self" href="#/v5/api/utils/fixednumber/-%23-FixedNumber--methods--comparison-and-equivalence"></a></div></div></h3>
|
|
<div class="property show-anchors"><div class="signature"><span class="path">FixedNumber</span><span class="symbol">.</span><span class="method">isZero</span><span class="symbol">(</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">boolean</span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/fixednumber.ts#L286">source</a></div></div><div class="body"><p>Returns true if and only if the value of <i>FixedNumber</i> is zero.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/fixednumber/-%23-FixedNumber--methods--conversion"></a><a name="/v5/api/utils/fixednumber/"></a><h3 class="show-anchors"><div>Conversion<div class="anchors"><a class="self" href="#/v5/api/utils/fixednumber/-%23-FixedNumber--methods--conversion"></a></div></div></h3>
|
|
<div class="property show-anchors"><div class="signature"><span class="path">fixednumber</span><span class="symbol">.</span><span class="method">toFormat</span><span class="symbol">(</span> <span class="param">format</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/fixednumber/">FixedNumber</a></span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/fixednumber.ts#L305">source</a></div></div><div class="body"><p>Returns a new FixedNumber with the value of <i>fixedvalue</i> with <i>format</i>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">fixednumber</span><span class="symbol">.</span><span class="method">toHexString</span><span class="symbol">(</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/fixednumber.ts#L296">source</a></div></div><div class="body"><p>Returns a <a href="#/v5/api/utils/bytes/-%23-HexString">HexString</a> representation of <i>fixednumber</i>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">fixednumber</span><span class="symbol">.</span><span class="method">toString</span><span class="symbol">(</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/fixednumber.ts#L294">source</a></div></div><div class="body"><p>Returns a string representation of <i>fixednumber</i>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">fixednumber</span><span class="symbol">.</span><span class="method">toUnsafeFloat</span><span class="symbol">(</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">float</span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/fixednumber.ts#L303">source</a></div></div><div class="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>
|
|
|
|
</div></div><a name="/v5/api/utils/fixednumber/-%23-FixedNumber--methods--inspection"></a><a name="/v5/api/utils/fixednumber/"></a><h3 class="show-anchors"><div>Inspection<div class="anchors"><a class="self" href="#/v5/api/utils/fixednumber/-%23-FixedNumber--methods--inspection"></a></div></div></h3>
|
|
<div class="property show-anchors"><div class="signature"><span class="path">FixedNumber</span><span class="symbol">.</span><span class="method">isFixedNumber</span><span class="symbol">(</span> <span class="param">value</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">boolean</span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/fixednumber.ts#L387">source</a></div></div><div class="body"><p>Returns true if and only if <i>value</i> is a <b>FixedNumber</b>.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/fixednumber/-%23-FixedFormat"></a><a name="/v5/api/utils/fixednumber/-%23-FixedNumber--FixedFormat"></a><a name="/v5/api/utils/fixednumber/"></a><h2 class="show-anchors"><div>FixedFormat<div class="anchors"><a class="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 unnecessary, as passing in a <a href="#/v5/api/utils/fixednumber/-%23-FixedFormat--strings">Format Strings</a> directly into the <a href="#/v5/api/utils/fixednumber/">FixedNumber</a> will automatically create this.</p>
|
|
|
|
<a name="/v5/api/utils/fixednumber/-%23-FixedFormat--strings"></a><a name="/v5/api/utils/fixednumber/-%23-FixedNumber--FixedFormat--FixedFormat--strings"></a><a name="/v5/api/utils/fixednumber/"></a><h3 class="show-anchors"><div>Format Strings<div class="anchors"><a class="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 <code class="inline">fixed</code>, which an unsigned format string begins with <code class="inline">ufixed</code>, followed by the width (in bits) and the number of decimals.</p>
|
|
|
|
<p>The width must be congruent to 0 mod 8 (i.e. <code class="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 <code class="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 <code class="inline">uint32_t</code> in C </li><li><b>fixed</b> is shorthand for <code class="inline">fixed128x18</code> </li><li><b>ufixed</b> is shorthand for <code class="inline">ufixed128x18</code> </li></ul></p>
|
|
|
|
<a name="/v5/api/utils/fixednumber/-%23-FixedNumber--FixedFormat--creating-instances"></a><a name="/v5/api/utils/fixednumber/"></a><h3 class="show-anchors"><div>Creating Instances<div class="anchors"><a class="self" href="#/v5/api/utils/fixednumber/-%23-FixedNumber--FixedFormat--creating-instances"></a></div></div></h3>
|
|
<a name="/v5/api/utils/fixednumber/-%23-FixedNumber-from"></a><div class="property show-anchors"><div class="signature"><span class="path">FixedFormat</span><span class="symbol">.</span><span class="method">from</span><span class="symbol">(</span> <span class="param">value</span> = "<span class="param">fixed128x18</span>" <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/fixednumber/-%23-FixedFormat">FixedFormat</a></span><div class="anchors"><a class="self" href="#/v5/api/utils/fixednumber/-%23-FixedNumber-from"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/bignumber/src.ts/fixednumber.ts#L140">source</a></div></div><div class="body"><p>Returns a new instance of a <b>FixedFormat</b> defined by <i>value</i>. Any valid <a href="#/v5/api/utils/fixednumber/-%23-FixedFormat--strings">Format Strings</a> may be passed in as well as any object which has any of <code class="inline">signed</code>, <code class="inline">width</code> and <code class="inline">decimals</code> defined, including a <a href="#/v5/api/utils/fixednumber/-%23-FixedFormat">FixedFormat</a> object.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/fixednumber/-%23-FixedNumber--FixedFormat--properties"></a><a name="/v5/api/utils/fixednumber/"></a><h3 class="show-anchors"><div>Properties<div class="anchors"><a class="self" href="#/v5/api/utils/fixednumber/-%23-FixedNumber--FixedFormat--properties"></a></div></div></h3>
|
|
<div class="property show-anchors"><div class="signature"><span class="path">fixedFormat</span><span class="symbol">.</span><span class="method">signed</span> <span class="arrow">⇒</span> <span class="returns">boolean</span><div class="anchors"></div></div><div class="body"><p>The signed-ness of <i>fixedFormat</i>, true if negative values are supported.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">fixedFormat</span><span class="symbol">.</span><span class="method">width</span> <span class="arrow">⇒</span> <span class="returns">number</span><div class="anchors"></div></div><div class="body"><p>The width (in bits) of <i>fixedFormat</i>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">fixedFormat</span><span class="symbol">.</span><span class="method">decimals</span> <span class="arrow">⇒</span> <span class="returns">number</span><div class="anchors"></div></div><div class="body"><p>The number of decimal points of <i>fixedFormat</i>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">fixedFormat</span><span class="symbol">.</span><span class="method">name</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"></div></div><div class="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><div class="definition"><div class="term"><b><i>"fixed"</i></b></div><div class="body"><p>A shorthand for <code class="inline">fixed128x80</code>.</p>
|
|
|
|
</div></div><div class="page-separator"></div><a name="/v5/api/utils/hashing/-%23-hashing-algorithms"></a><a name="/v5/api/utils/hashing/-%23-hashing-algorithms"></a><a name="/v5/api/utils/hashing/"></a><h1 class="show-anchors"><div>Hashing Algorithms<div class="anchors"><a class="self" href="#/v5/api/utils/hashing/-%23-hashing-algorithms"></a></div></div></h1><p>There are many hashing algorithms used throughout the blockchain space as well as some more complex usages which require utilities to facilitate these common operations.</p>
|
|
|
|
<a name="/v5/api/utils/hashing/-%23-cryptographic-hash-functions"></a><a name="/v5/api/utils/hashing/-%23-hashing-algorithms--cryptographic-hash-functions"></a><a name="/v5/api/utils/hashing/"></a><h2 class="show-anchors"><div>Cryptographic Hash Functions<div class="anchors"><a class="self" href="#/v5/api/utils/hashing/-%23-cryptographic-hash-functions"></a></div></div></h2><p>The <a href="https://en.wikipedia.org/wiki/Cryptographic_hash_function">Cryptographic Hash Functions</a> are a specific family of hash functions.</p>
|
|
|
|
<a name="/v5/api/utils/hashing/-%23-utils-id"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">id</span><span class="symbol">(</span> <span class="param">text</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 > ></span><div class="anchors"><a class="self" href="#/v5/api/utils/hashing/-%23-utils-id"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/hash/src.ts/id.ts#L4">source</a></div></div><div class="body"><p>The Ethereum Identity function computes the <a href="https://en.wikipedia.org/wiki/SHA-3">KECCAK256</a> hash of the <i>text</i> bytes.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/hashing/-%23-utils-keccak256"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">keccak256</span><span class="symbol">(</span> <span class="param">aBytesLike</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 > ></span><div class="anchors"><a class="self" href="#/v5/api/utils/hashing/-%23-utils-keccak256"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/keccak256/src.ts/index.ts#L7">source</a></div></div><div class="body"><p>Returns the <a href="https://en.wikipedia.org/wiki/SHA-3">KECCAK256</a> digest <i>aBytesLike</i>.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/hashing/-%23-utils-ripemd160"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">ripemd160</span><span class="symbol">(</span> <span class="param">aBytesLike</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 20 > ></span><div class="anchors"><a class="self" href="#/v5/api/utils/hashing/-%23-utils-ripemd160"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/sha2/src.ts/sha2.ts#L13">source</a></div></div><div class="body"><p>Returns the <a href="https://en.m.wikipedia.org/wiki/RIPEMD">RIPEMD-160</a> digest of <i>aBytesLike</i>.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/hashing/-%23-utils-sha256"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">sha256</span><span class="symbol">(</span> <span class="param">aBytesLike</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 > ></span><div class="anchors"><a class="self" href="#/v5/api/utils/hashing/-%23-utils-sha256"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/sha2/src.ts/sha2.ts#L17">source</a></div></div><div class="body"><p>Returns the <a href="https://en.wikipedia.org/wiki/SHA-2">SHA2-256</a> digest of <i>aBytesLike</i>.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/hashing/-%23-utils-sha512"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">sha512</span><span class="symbol">(</span> <span class="param">aBytesLike</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 64 > ></span><div class="anchors"><a class="self" href="#/v5/api/utils/hashing/-%23-utils-sha512"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/sha2/src.ts/sha2.ts#L21">source</a></div></div><div class="body"><p>Returns the <a href="https://en.wikipedia.org/wiki/SHA-2">SHA2-512</a> digest of <i>aBytesLike</i>.</p>
|
|
|
|
</div></div><div class="code-title"><div>KECCAK256</div></div><div class="code">utils.keccak256([ 0x12, 0x34 ])
|
|
<span class="result ok">// '0x56570de287d73cd1cb6092bb8fdee6173974955fdef345ae579ee9f475ea7432'
|
|
</span>
|
|
utils.keccak256("0x")
|
|
<span class="result ok">// '0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470'
|
|
</span>
|
|
utils.keccak256("0x1234")
|
|
<span class="result ok">// '0x56570de287d73cd1cb6092bb8fdee6173974955fdef345ae579ee9f475ea7432'
|
|
</span>
|
|
<span class="comment">// The value MUST be data, such as:
|
|
</span><span class="comment">// - an Array of numbers
|
|
</span><span class="comment">// - a data hex string (e.g. "0x1234")
|
|
</span><span class="comment">// - a Uint8Array
|
|
</span>
|
|
<span class="comment">// Do NOT use UTF-8 strings that are not a DataHexstring
|
|
</span>utils.keccak256("hello world")
|
|
<span class="result error">// Error: invalid arrayify value (argument="value", value="hello world", code=INVALID_ARGUMENT, version=bytes/5.0.10)
|
|
</span>
|
|
<span class="comment">// If needed, convert strings to bytes first:
|
|
</span>utils.keccak256(utils.toUtf8Bytes("hello world"))
|
|
<span class="result ok">// '0x47173285a8d7341e5e972fc677286384f802f8ef42a5ec5f03bbfa254cb01fad'
|
|
</span>
|
|
<span class="comment">// Or equivalently use the identity function:
|
|
</span>utils.id("hello world")
|
|
<span class="result ok">// '0x47173285a8d7341e5e972fc677286384f802f8ef42a5ec5f03bbfa254cb01fad'
|
|
</span>
|
|
<span class="comment">// Keep in mind that the string "0x1234" represents TWO
|
|
</span><span class="comment">// bytes (i.e. [ 0x12, 0x34 ]. If you wish to compute the
|
|
</span><span class="comment">// hash of the 6 characters "0x1234", convert it to UTF-8
|
|
</span><span class="comment">// bytes first using utils.toUtf8Bytes.
|
|
</span>
|
|
<span class="comment">// Consider the following examples:
|
|
</span>
|
|
<span class="comment">// Hash of TWO (2) bytes:
|
|
</span>utils.keccak256("0x1234")
|
|
<span class="result ok">// '0x56570de287d73cd1cb6092bb8fdee6173974955fdef345ae579ee9f475ea7432'
|
|
</span>
|
|
<span class="comment">// Hash of TWO (2) bytes: (same result)
|
|
</span>utils.keccak256([ 0x12, 0x34 ])
|
|
<span class="result ok">// '0x56570de287d73cd1cb6092bb8fdee6173974955fdef345ae579ee9f475ea7432'
|
|
</span>
|
|
const bytes = utils.toUtf8Bytes("0x1234")
|
|
<span class="result ok">// Uint8Array [ 48, 120, 49, 50, 51, 52 ]
|
|
</span>
|
|
<span class="comment">// Hash of SIX (6) characters (different than above)
|
|
</span>utils.keccak256(bytes)
|
|
<span class="result ok">// '0x1ac7d1b81b7ba1025b36ccb86723da6ee5a87259f1c2fd5abe69d3200b512ec8'
|
|
</span>
|
|
<span class="comment">// Hash of SIX (6) characters (same result)
|
|
</span>utils.id("0x1234")
|
|
<span class="result ok">// '0x1ac7d1b81b7ba1025b36ccb86723da6ee5a87259f1c2fd5abe69d3200b512ec8'
|
|
</span></div><div class="code-title"><div>RIPEMD160</div></div><div class="code">utils.ripemd160("0x")
|
|
<span class="result ok">// '0x9c1185a5c5e9fc54612808977ee8f548b2258d31'
|
|
</span>
|
|
utils.ripemd160("0x1234")
|
|
<span class="result ok">// '0xc39867e393cb061b837240862d9ad318c176a96d'
|
|
</span></div><div class="code-title"><div>SHA-2</div></div><div class="code">utils.sha256("0x")
|
|
<span class="result ok">// '0xe3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855'
|
|
</span>
|
|
utils.sha256("0x1234")
|
|
<span class="result ok">// '0x3a103a4e5729ad68c02a678ae39accfbc0ae208096437401b7ceab63cca0622f'
|
|
</span>
|
|
utils.sha512("0x")
|
|
<span class="result ok">// '0xcf83e1357eefb8bdf1542850d66d8007d620e4050b5715dc83f4a921d36ce9ce47d0d13c5d85f2b0ff8318d2877eec2f63b931bd47417a81a538327af927da3e'
|
|
</span>
|
|
utils.sha512("0x1234")
|
|
<span class="result ok">// '0x4c54886c9821195522d88ff4705c3e0c686b921054421e6ea598739c29c26e1ee75419aaceec94dd2e3c0dbb82ecf895c9f61215f375de6d800d9b99d3d4b816'
|
|
</span></div><a name="/v5/api/utils/hashing/-%23-utils--hmac"></a><a name="/v5/api/utils/hashing/-%23-hashing-algorithms--utils--hmac"></a><a name="/v5/api/utils/hashing/"></a><h2 class="show-anchors"><div>HMAC<div class="anchors"><a class="self" href="#/v5/api/utils/hashing/-%23-utils--hmac"></a></div></div></h2>
|
|
<a name="/v5/api/utils/hashing/-%23-utils-computeHmac"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">computeHmac</span><span class="symbol">(</span> <span class="param">algorithm</span> <span class="symbol">,</span> <span class="param">key</span> <span class="symbol">,</span> <span class="param">data</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a> ></span><div class="anchors"><a class="self" href="#/v5/api/utils/hashing/-%23-utils-computeHmac"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/sha2/src.ts/sha2.ts#L25">source</a></div></div><div class="body"><p>Returns the <a href="https://en.wikipedia.org/wiki/HMAC">HMAC</a> of <i>data</i> with <i>key</i> using the <a href="#/v5/api/utils/hashing/-%23-utils--hmac-supported-algorithm">Algorithm</a> <i>algorithm</i>.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/hashing/-%23-utils--hmac-supported-algorithm"></a><a name="/v5/api/utils/hashing/-%23-hashing-algorithms--utils--hmac--utils--hmac-supported-algorithm"></a><a name="/v5/api/utils/hashing/"></a><h3 class="show-anchors"><div><b>HMAC Supported Algorithms</b><div class="anchors"><a class="self" href="#/v5/api/utils/hashing/-%23-utils--hmac-supported-algorithm"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/sha2/src.ts/types.ts#L1">source</a></div></div></h3>
|
|
<div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="path">SupportedAlgorithm</span><span class="symbol">.</span><span class="method">sha256</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"></div></div><div class="body"><p>Use the <a href="https://en.wikipedia.org/wiki/SHA-2">SHA2-256</a> hash algorithm.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="path">SupportedAlgorithm</span><span class="symbol">.</span><span class="method">sha512</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"></div></div><div class="body"><p>Use the <a href="https://en.wikipedia.org/wiki/SHA-2">SHA2-512</a> hash algorithm.</p>
|
|
|
|
</div></div><div class="code-title"><div>HMAC</div></div><div class="code">const key = "0x0102"
|
|
const data = "0x1234"
|
|
utils.computeHmac("sha256", key, data)
|
|
<span class="result ok">// '0x7553df81c628815cf569696cad13a37c606c5058df13d9dff4fee2cf5e9b5779'
|
|
</span></div><a name="/v5/api/utils/hashing/-%23-utils--hashing-helpers"></a><a name="/v5/api/utils/hashing/-%23-hashing-algorithms--utils--hashing-helpers"></a><a name="/v5/api/utils/hashing/"></a><h2 class="show-anchors"><div>Hashing Helpers<div class="anchors"><a class="self" href="#/v5/api/utils/hashing/-%23-utils--hashing-helpers"></a></div></div></h2>
|
|
<a name="/v5/api/utils/hashing/-%23-utils-hashMessage"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">hashMessage</span><span class="symbol">(</span> <span class="param">message</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 > ></span><div class="anchors"><a class="self" href="#/v5/api/utils/hashing/-%23-utils-hashMessage"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/hash/src.ts/message.ts#L7">source</a></div></div><div class="body"><p>Computes the <a href="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 <code class="inline">\x19Ethereum Signed Message:</code> and the length of <i>message</i>.</p>
|
|
|
|
</div></div><div class="code-title"><div>Hashing Messages</div></div><div class="code"><span class="comment">// Hashing a string message
|
|
</span>utils.hashMessage("Hello World")
|
|
<span class="result ok">// '0xa1de988600a42c4b4ab089b619297c17d53cffae5d5120d82d8a92d0bb3b78f2'
|
|
</span>
|
|
<span class="comment">// Hashing binary data (also "Hello World", but as bytes)
|
|
</span>utils.hashMessage( [ 72, 101, 108, 108, 111, 32, 87, 111, 114, 108, 100 ])
|
|
<span class="result ok">// '0xa1de988600a42c4b4ab089b619297c17d53cffae5d5120d82d8a92d0bb3b78f2'
|
|
</span>
|
|
<span class="comment">// NOTE: It is important to understand how strings and binary
|
|
</span><span class="comment">// data is handled differently. A string is ALWAYS processed
|
|
</span><span class="comment">// as the bytes of the string, so a hexstring MUST be
|
|
</span><span class="comment">// converted to an ArrayLike object first.
|
|
</span>
|
|
<span class="comment">// Hashing a hex string is the same as hashing a STRING
|
|
</span><span class="comment">// Note: this is the hash of the 4 characters [ '0', 'x', '4', '2' ]
|
|
</span>utils.hashMessage("0x42")
|
|
<span class="result ok">// '0xf0d544d6e4a96e1c08adc3efabe2fcb9ec5e28db1ad6c33ace880ba354ab0fce'
|
|
</span>
|
|
<span class="comment">// Hashing the binary data
|
|
</span><span class="comment">// Note: this is the hash of the 1 byte [ 0x42 ]
|
|
</span>utils.hashMessage([ 0x42 ])
|
|
<span class="result ok">// '0xd18c12b87124f9ceb7e1d3a5d06a5ac92ecab15931417e8d1558d9a263f99d63'
|
|
</span>
|
|
<span class="comment">// Hashing the binary data
|
|
</span><span class="comment">// Note: similarly, this is the hash of the 1 byte [ 0x42 ]
|
|
</span>utils.hashMessage(utils.arrayify("0x42"))
|
|
<span class="result ok">// '0xd18c12b87124f9ceb7e1d3a5d06a5ac92ecab15931417e8d1558d9a263f99d63'
|
|
</span></div><a name="/v5/api/utils/hashing/-%23-utils-namehash"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">namehash</span><span class="symbol">(</span> <span class="param">name</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 > ></span><div class="anchors"><a class="self" href="#/v5/api/utils/hashing/-%23-utils-namehash"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/hash/src.ts/namehash.ts#L27">source</a></div></div><div class="body"><p>Returns the <a href="https://docs.ens.domains/contract-api-reference/name-processing#hashing-names">ENS Namehash</a> of <i>name</i>.</p>
|
|
|
|
</div></div><div class="code-title"><div>Namehash</div></div><div class="code">utils.namehash("")
|
|
<span class="result ok">// '0x0000000000000000000000000000000000000000000000000000000000000000'
|
|
</span>
|
|
utils.namehash("eth")
|
|
<span class="result ok">// '0x93cdeb708b7545dc668eb9280176169d1c33cfd8ed6f04690a0bcc88a93fc4ae'
|
|
</span>
|
|
utils.namehash("ricmoo.firefly.eth")
|
|
<span class="result ok">// '0x0bcad17ecf260d6506c6b97768bdc2acfb6694445d27ffd3f9c1cfbee4a9bd6d'
|
|
</span>
|
|
utils.namehash("ricmoo.xyz")
|
|
<span class="result ok">// '0x7d56aa46358ba2f8b77d8e05bcabdd2358370dcf34e87810f8cea77ecb3fc57d'
|
|
</span></div><a name="/v5/api/utils/hashing/-%23-TypedDataEncoder"></a><a name="/v5/api/utils/hashing/-%23-hashing-algorithms--utils--hashing-helpers--TypedDataEncoder"></a><a name="/v5/api/utils/hashing/"></a><h3 class="show-anchors"><div>Typed Data Encoder<div class="anchors"><a class="self" href="#/v5/api/utils/hashing/-%23-TypedDataEncoder"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/hash/src.ts/typed-data.ts#L148">source</a></div></div></h3><p>The <b>TypedDataEncoder</b> is used to compute the various encoded data required for <a href="https://eips.ethereum.org/EIPS/eip-712">EIP-712</a> signed data.</p>
|
|
|
|
<p>Signed data requires a domain, list of structures and their members and the data itself.</p>
|
|
|
|
<p>The <b>domain</b> is an object with values for any of the standard domain properties.</p>
|
|
|
|
<p>The <b>types</b> is an object with each property being the name of a structure, mapping to an array of field descriptions. It should <b>not</b> include the <code class="inline">EIP712Domain</code> property unless it is required as a child structure of another.</p>
|
|
|
|
<div class="definition container-box note"><div class="term">Experimental Feature (this exported class name will change)</div><div class="body"><p>This is still an experimental feature. If using it, please specify the <b>exact</b> version of ethers you are using (e.g. spcify <code class="inline">"5.0.18"</code>, <b>not</b> <code class="inline">"^5.0.18"</code>) as the exported class name will be renamed from <code class="inline">_TypedDataEncoder</code> to <code class="inline">TypedDataEncoder</code> once it has been used in the field a bit.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/hashing/-%23-TypedDataEncoder-from"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="path">_TypedDataEncoder</span><span class="symbol">.</span><span class="method">from</span><span class="symbol">(</span> <span class="param">types</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">[TypedDataEncoder]</span><div class="anchors"><a class="self" href="#/v5/api/utils/hashing/-%23-TypedDataEncoder-from"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/hash/src.ts/typed-data.ts#L363">source</a></div></div><div class="body"><p>Creates a new <b>TypedDataEncoder</b> for <i>types</i>. This object is a fairly low-level object that most developers should not require using instances directly.</p>
|
|
|
|
<p>Most developers will find the static class methods below the most useful.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/hashing/-%23-TypedDataEncoder-encode"></a><div class="property show-anchors"><div class="signature"><span class="path">TypedDataEncoder</span><span class="symbol">.</span><span class="method">encode</span><span class="symbol">(</span> <span class="param">domain</span> <span class="symbol">,</span> <span class="param">types</span> <span class="symbol">,</span> <span class="param">values</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"><a class="self" href="#/v5/api/utils/hashing/-%23-TypedDataEncoder-encode"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/hash/src.ts/typed-data.ts#L392">source</a></div></div><div class="body"><p>Encodes the Returns the hashed <a href="https://eips.ethereum.org/EIPS/eip-712">EIP-712</a> domain.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/hashing/-%23-TypedDataEncoder-getPayload"></a><div class="property show-anchors"><div class="signature"><span class="path">TypedDataEncoder</span><span class="symbol">.</span><span class="method">getPayload</span><span class="symbol">(</span> <span class="param">domain</span> <span class="symbol">,</span> <span class="param">types</span> <span class="symbol">,</span> <span class="param">value</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">any</span><div class="anchors"><a class="self" href="#/v5/api/utils/hashing/-%23-TypedDataEncoder-getPayload"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/hash/src.ts/typed-data.ts#L447">source</a></div></div><div class="body"><p>Returns the standard payload used by various JSON-RPC <code class="inline">eth_signTypedData*</code> calls.</p>
|
|
|
|
<p>All domain values and entries in value are normalized and the types are verified.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/hashing/-%23-TypedDataEncoder-getPrimaryType"></a><div class="property show-anchors"><div class="signature"><span class="path">TypedDataEncoder</span><span class="symbol">.</span><span class="method">getPrimaryType</span><span class="symbol">(</span> <span class="param">types</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"><a class="self" href="#/v5/api/utils/hashing/-%23-TypedDataEncoder-getPrimaryType"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/hash/src.ts/typed-data.ts#L367">source</a></div></div><div class="body"><p>Constructs a directed acyclic graph of the types and returns the root type, which can be used as the <b>primaryType</b> for <a href="https://eips.ethereum.org/EIPS/eip-712">EIP-712</a> payloads.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/hashing/-%23-TypedDataEncoder-hash"></a><div class="property show-anchors"><div class="signature"><span class="path">TypedDataEncoder</span><span class="symbol">.</span><span class="method">hash</span><span class="symbol">(</span> <span class="param">domain</span> <span class="symbol">,</span> <span class="param">types</span> <span class="symbol">,</span> <span class="param">values</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 > ></span><div class="anchors"><a class="self" href="#/v5/api/utils/hashing/-%23-TypedDataEncoder-hash"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/hash/src.ts/typed-data.ts#L400">source</a></div></div><div class="body"><p>Returns the computed <a href="https://eips.ethereum.org/EIPS/eip-712">EIP-712</a> hash.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/hashing/-%23-TypedDataEncoder-hashDomain"></a><div class="property show-anchors"><div class="signature"><span class="path">TypedDataEncoder</span><span class="symbol">.</span><span class="method">hashDomain</span><span class="symbol">(</span> <span class="param">domain</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 > ></span><div class="anchors"><a class="self" href="#/v5/api/utils/hashing/-%23-TypedDataEncoder-hashDomain"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/hash/src.ts/typed-data.ts#L375">source</a></div></div><div class="body"><p>Returns the hashed <a href="https://eips.ethereum.org/EIPS/eip-712">EIP-712</a> domain.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/hashing/-%23-TypedDataEncoder-resolveNames"></a><div class="property show-anchors"><div class="signature"><span class="path">TypedDataEncoder</span><span class="symbol">.</span><span class="method">resolveNames</span><span class="symbol">(</span> <span class="param">domain</span> <span class="symbol">,</span> <span class="param">types</span> <span class="symbol">,</span> <span class="param">value</span> <span class="symbol">,</span> <span class="param">resolveName</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< any ></span><div class="anchors"><a class="self" href="#/v5/api/utils/hashing/-%23-TypedDataEncoder-resolveNames"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/hash/src.ts/typed-data.ts#L405">source</a></div></div><div class="body"><p>Returns a copy of value, where any leaf value with a type of <code class="inline">address</code> will have been recursively replacedwith the value of calling <i>resolveName</i> with that value.</p>
|
|
|
|
</div></div><div class="code-title"><div>Typed Data Example</div></div><div class="code">const domain = {
|
|
name: 'Ether Mail',
|
|
version: '1',
|
|
chainId: 1,
|
|
verifyingContract: '0xCcCCccccCCCCcCCCCCCcCcCccCcCCCcCcccccccC'
|
|
}
|
|
|
|
<span class="comment">// The named list of all type definitions
|
|
</span>const types = {
|
|
Person: [
|
|
{ name: 'name', type: 'string' },
|
|
{ name: 'wallet', type: 'address' }
|
|
],
|
|
Mail: [
|
|
{ name: 'from', type: 'Person' },
|
|
{ name: 'to', type: 'Person' },
|
|
{ name: 'contents', type: 'string' }
|
|
]
|
|
}
|
|
|
|
<span class="comment">// The data to sign
|
|
</span>const value = {
|
|
from: {
|
|
name: 'Cow',
|
|
wallet: '0xCD2a3d9F938E13CD947Ec05AbC7FE734Df8DD826'
|
|
},
|
|
to: {
|
|
name: 'Bob',
|
|
wallet: '0xbBbBBBBbbBBBbbbBbbBbbbbBBbBbbbbBbBbbBBbB'
|
|
},
|
|
contents: 'Hello, Bob!'
|
|
}
|
|
|
|
|
|
TypedDataEncoder.encode(domain, types, value)
|
|
<span class="result ok">// '0x1901f2cee375fa42b42143804025fc449deafd50cc031ca257e0b194a650a912090fc52c0ee5d84264471806290a3f2c4cecfc5490626bf912d01f240d7a274b371e'
|
|
</span>
|
|
TypedDataEncoder.getPayload(domain, types, value)
|
|
<span class="result ok">// {
|
|
</span><span class="result ok">// domain: {
|
|
</span><span class="result ok">// chainId: '1',
|
|
</span><span class="result ok">// name: 'Ether Mail',
|
|
</span><span class="result ok">// verifyingContract: '0xcccccccccccccccccccccccccccccccccccccccc',
|
|
</span><span class="result ok">// version: '1'
|
|
</span><span class="result ok">// },
|
|
</span><span class="result ok">// message: {
|
|
</span><span class="result ok">// contents: 'Hello, Bob!',
|
|
</span><span class="result ok">// from: {
|
|
</span><span class="result ok">// name: 'Cow',
|
|
</span><span class="result ok">// wallet: '0xcd2a3d9f938e13cd947ec05abc7fe734df8dd826'
|
|
</span><span class="result ok">// },
|
|
</span><span class="result ok">// to: {
|
|
</span><span class="result ok">// name: 'Bob',
|
|
</span><span class="result ok">// wallet: '0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb'
|
|
</span><span class="result ok">// }
|
|
</span><span class="result ok">// },
|
|
</span><span class="result ok">// primaryType: 'Mail',
|
|
</span><span class="result ok">// types: {
|
|
</span><span class="result ok">// EIP712Domain: [
|
|
</span><span class="result ok">// {
|
|
</span><span class="result ok">// name: 'name',
|
|
</span><span class="result ok">// type: 'string'
|
|
</span><span class="result ok">// },
|
|
</span><span class="result ok">// {
|
|
</span><span class="result ok">// name: 'version',
|
|
</span><span class="result ok">// type: 'string'
|
|
</span><span class="result ok">// },
|
|
</span><span class="result ok">// {
|
|
</span><span class="result ok">// name: 'chainId',
|
|
</span><span class="result ok">// type: 'uint256'
|
|
</span><span class="result ok">// },
|
|
</span><span class="result ok">// {
|
|
</span><span class="result ok">// name: 'verifyingContract',
|
|
</span><span class="result ok">// type: 'address'
|
|
</span><span class="result ok">// }
|
|
</span><span class="result ok">// ],
|
|
</span><span class="result ok">// Mail: [
|
|
</span><span class="result ok">// {
|
|
</span><span class="result ok">// name: 'from',
|
|
</span><span class="result ok">// type: 'Person'
|
|
</span><span class="result ok">// },
|
|
</span><span class="result ok">// {
|
|
</span><span class="result ok">// name: 'to',
|
|
</span><span class="result ok">// type: 'Person'
|
|
</span><span class="result ok">// },
|
|
</span><span class="result ok">// {
|
|
</span><span class="result ok">// name: 'contents',
|
|
</span><span class="result ok">// type: 'string'
|
|
</span><span class="result ok">// }
|
|
</span><span class="result ok">// ],
|
|
</span><span class="result ok">// Person: [
|
|
</span><span class="result ok">// {
|
|
</span><span class="result ok">// name: 'name',
|
|
</span><span class="result ok">// type: 'string'
|
|
</span><span class="result ok">// },
|
|
</span><span class="result ok">// {
|
|
</span><span class="result ok">// name: 'wallet',
|
|
</span><span class="result ok">// type: 'address'
|
|
</span><span class="result ok">// }
|
|
</span><span class="result ok">// ]
|
|
</span><span class="result ok">// }
|
|
</span><span class="result ok">// }
|
|
</span>
|
|
TypedDataEncoder.getPrimaryType(types)
|
|
<span class="result ok">// 'Mail'
|
|
</span>
|
|
TypedDataEncoder.hash(domain, types, value)
|
|
<span class="result ok">// '0xbe609aee343fb3c4b28e1df9e632fca64fcfaede20f02e86244efddf30957bd2'
|
|
</span>
|
|
TypedDataEncoder.hashDomain(domain)
|
|
<span class="result ok">// '0xf2cee375fa42b42143804025fc449deafd50cc031ca257e0b194a650a912090f'
|
|
</span></div><a name="/v5/api/utils/hashing/-%23-utils--solidity-hashing"></a><a name="/v5/api/utils/hashing/-%23-hashing-algorithms--utils--solidity-hashing"></a><a name="/v5/api/utils/hashing/"></a><h2 class="show-anchors"><div>Solidity Hashing Algorithms<div class="anchors"><a class="self" href="#/v5/api/utils/hashing/-%23-utils--solidity-hashing"></a></div></div></h2><p>When using the Solidity <code class="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>
|
|
|
|
<a name="/v5/api/utils/hashing/-%23-utils-solidityPack"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">solidityPack</span><span class="symbol">(</span> <span class="param">types</span> <span class="symbol">,</span> <span class="param">values</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a> ></span><div class="anchors"><a class="self" href="#/v5/api/utils/hashing/-%23-utils-solidityPack"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/solidity/src.ts/index.ts#L75">source</a></div></div><div class="body"><p>Returns the non-standard encoded <i>values</i> packed according to their respective type in <i>types</i>.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/hashing/-%23-utils-solidityKeccak256"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">solidityKeccak256</span><span class="symbol">(</span> <span class="param">types</span> <span class="symbol">,</span> <span class="param">values</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 > ></span><div class="anchors"><a class="self" href="#/v5/api/utils/hashing/-%23-utils-solidityKeccak256"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/solidity/src.ts/index.ts#L84">source</a></div></div><div class="body"><p>Returns the <a href="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><a name="/v5/api/utils/hashing/-%23-utils-soliditySha256"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">soliditySha256</span><span class="symbol">(</span> <span class="param">types</span> <span class="symbol">,</span> <span class="param">values</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 > ></span><div class="anchors"><a class="self" href="#/v5/api/utils/hashing/-%23-utils-soliditySha256"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/solidity/src.ts/index.ts#L88">source</a></div></div><div class="body"><p>Returns the <a href="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>
|
|
|
|
</div></div><div class="code-title"><div>Solidity Hashing</div></div><div class="code">utils.solidityPack([ "int16", "uint48" ], [ -1, 12 ])
|
|
<span class="result ok">// '0xffff00000000000c'
|
|
</span>
|
|
utils.solidityPack([ "string", "uint8" ], [ "Hello", 3 ])
|
|
<span class="result ok">// '0x48656c6c6f03'
|
|
</span>
|
|
utils.solidityKeccak256([ "int16", "uint48" ], [ -1, 12 ])
|
|
<span class="result ok">// '0x81da7abb5c9c7515f57dab2fc946f01217ab52f3bd8958bc36bd55894451a93c'
|
|
</span>
|
|
utils.soliditySha256([ "int16", "uint48" ], [ -1, 12 ])
|
|
<span class="result ok">// '0xa5580fb602f6e2ba9c588011dc4e6c2335e0f5d970dc45869db8f217efc6911a'
|
|
</span>
|
|
<span class="comment">// As a short example of the non-distinguished nature of
|
|
</span><span class="comment">// Solidity tight-packing (which is why it is inappropriate
|
|
</span><span class="comment">// for many things from a security point of view), consider
|
|
</span><span class="comment">// the following examples are all equal, despite representing
|
|
</span><span class="comment">// very different values and layouts.
|
|
</span>
|
|
utils.solidityPack([ "string", "string" ], [ "hello", "world01" ])
|
|
<span class="result ok">// '0x68656c6c6f776f726c643031'
|
|
</span>
|
|
utils.solidityPack([ "string", "string" ], [ "helloworld", "01" ])
|
|
<span class="result ok">// '0x68656c6c6f776f726c643031'
|
|
</span>
|
|
utils.solidityPack([ "string", "string", "uint16" ], [ "hell", "oworld", 0x3031 ])
|
|
<span class="result ok">// '0x68656c6c6f776f726c643031'
|
|
</span>
|
|
utils.solidityPack([ "uint96" ], [ "32309054545061485574011236401" ])
|
|
<span class="result ok">// '0x68656c6c6f776f726c643031'
|
|
</span></div><div class="page-separator"></div><a name="/v5/api/utils/hdnode/-%23-hdnodes"></a><a name="/v5/api/utils/hdnode/-%23-hdnodes"></a><a name="/v5/api/utils/hdnode/"></a><h1 class="show-anchors"><div>HD Wallet<div class="anchors"><a class="self" href="#/v5/api/utils/hdnode/-%23-hdnodes"></a></div></div></h1><p>The Hierarchal Desterministic (HD) Wallet was a standard created for Bitcoin, but lends itself well to a wide variety of Blockchains which rely on secp256k1 private keys.</p>
|
|
|
|
<p>For a more detailed technical understanding:</p>
|
|
|
|
<p><ul><li><a href="https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki">BIP-32</a> - the hierarchal deterministic description </li><li><a href="https://en.bitcoin.it/wiki/BIP_0039">BIP-39</a> - the method used to derive the BIP-32 seed from human-readable sequences of words (i.e. a mnemonic) </li><li><a href="https://en.bitcoin.it/wiki/BIP_0044">BIP-44</a> - a standard defined to make BIP-32 easy to adapt to any future compatible blockchain </li></ul></p>
|
|
|
|
<a name="/v5/api/utils/hdnode/-%23-hdnodes--types"></a><a name="/v5/api/utils/hdnode/"></a><h2 class="show-anchors"><div>Types<div class="anchors"><a class="self" href="#/v5/api/utils/hdnode/-%23-hdnodes--types"></a></div></div></h2>
|
|
<a name="/v5/api/utils/hdnode/-%23-hdnodes--defaultpath"></a><a name="/v5/api/utils/hdnode/-%23-hdnodes--types--hdnodes--defaultpath"></a><a name="/v5/api/utils/hdnode/"></a><h3 class="show-anchors"><div>Constants<div class="anchors"><a class="self" href="#/v5/api/utils/hdnode/-%23-hdnodes--defaultpath"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/hdnode/src.ts/index.ts#L67">source</a></div></div></h3>
|
|
<div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">defaultPath</span> <span class="arrow">⇒</span> <span class="returns">"m/44'/60'/0'/0/0"</span><div class="anchors"></div></div><div class="body"><p>The default path for Ethereum in an HD Wallet</p>
|
|
|
|
</div></div><a name="/v5/api/utils/hdnode/-%23-Mnemonic"></a><a name="/v5/api/utils/hdnode/-%23-hdnodes--types--Mnemonic"></a><a name="/v5/api/utils/hdnode/"></a><h3 class="show-anchors"><div>Mnemonic<div class="anchors"><a class="self" href="#/v5/api/utils/hdnode/-%23-Mnemonic"></a></div></div></h3>
|
|
<div class="property show-anchors"><div class="signature"><span class="path">mnemonic</span><span class="symbol">.</span><span class="method">phrase</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"></div></div><div class="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 <code class="inline">locale</code>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">mnemonic</span><span class="symbol">.</span><span class="method">path</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"></div></div><div class="body"><p>The HD path for this mnemonic.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">mnemonic</span><span class="symbol">.</span><span class="method">locale</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"></div></div><div class="body"><p>The language of the wordlist this mnemonic is using.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/hdnode/-%23-HDNode"></a><a name="/v5/api/utils/hdnode/-%23-hdnodes--HDNode"></a><a name="/v5/api/utils/hdnode/"></a><h2 class="show-anchors"><div>HDNode<div class="anchors"><a class="self" href="#/v5/api/utils/hdnode/-%23-HDNode"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/hdnode/src.ts/index.ts#L75">source</a></div></div></h2>
|
|
<a name="/v5/api/utils/hdnode/-%23-HDNode--creating"></a><a name="/v5/api/utils/hdnode/-%23-hdnodes--HDNode--HDNode--creating"></a><a name="/v5/api/utils/hdnode/"></a><h3 class="show-anchors"><div>Creating Instances<div class="anchors"><a class="self" href="#/v5/api/utils/hdnode/-%23-HDNode--creating"></a></div></div></h3>
|
|
<a name="/v5/api/utils/hdnode/-%23-HDNode-fromMnemonic"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">HDNode</span><span class="symbol">.</span><span class="method">fromMnemonic</span><span class="symbol">(</span> <span class="param">phrase</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">password</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">wordlist</span> <span class="symbol">]</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/hdnode/-%23-HDNode">HDNode</a></span><div class="anchors"><a class="self" href="#/v5/api/utils/hdnode/-%23-HDNode-fromMnemonic"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/hdnode/src.ts/index.ts#L263">source</a></div></div><div class="body"><p>Return the <a href="#/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><a name="/v5/api/utils/hdnode/-%23-HDNode-fromSeed"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">HDNode</span><span class="symbol">.</span><span class="method">fromSeed</span><span class="symbol">(</span> <span class="param">aBytesLike</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/hdnode/-%23-HDNode">HDNode</a></span><div class="anchors"><a class="self" href="#/v5/api/utils/hdnode/-%23-HDNode-fromSeed"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/hdnode/src.ts/index.ts#L278">source</a></div></div><div class="body"><p>Return the <a href="#/v5/api/utils/hdnode/-%23-HDNode">HDNode</a> for the seed <i>aBytesLike</i>.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/hdnode/-%23-HDNode-fromExtendedKey"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">HDNode</span><span class="symbol">.</span><span class="method">fromExtendedKey</span><span class="symbol">(</span> <span class="param">extendedKey</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/hdnode/-%23-HDNode">HDNode</a></span><div class="anchors"><a class="self" href="#/v5/api/utils/hdnode/-%23-HDNode-fromExtendedKey"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/hdnode/src.ts/index.ts#L282">source</a></div></div><div class="body"><p>Return the <a href="#/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>
|
|
|
|
</div></div><a name="/v5/api/utils/hdnode/-%23-HDNode--properties"></a><a name="/v5/api/utils/hdnode/-%23-hdnodes--HDNode--HDNode--properties"></a><a name="/v5/api/utils/hdnode/"></a><h3 class="show-anchors"><div>Properties<div class="anchors"><a class="self" href="#/v5/api/utils/hdnode/-%23-HDNode--properties"></a></div></div></h3>
|
|
<div class="property show-anchors"><div class="signature"><span class="path">hdNode</span><span class="symbol">.</span><span class="method">privateKey</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 > ></span><div class="anchors"></div></div><div class="body"><p>The private key for this HDNode.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">hdNode</span><span class="symbol">.</span><span class="method">publicKey</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 33 > ></span><div class="anchors"></div></div><div class="body"><p>The (compresses) public key for this HDNode.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">hdNode</span><span class="symbol">.</span><span class="method">fingerprint</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 4 > ></span><div class="anchors"></div></div><div class="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><div class="property show-anchors"><div class="signature"><span class="path">hdNode</span><span class="symbol">.</span><span class="method">parentFingerprint</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 4 > ></span><div class="anchors"></div></div><div class="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><div class="property show-anchors"><div class="signature"><span class="path">hdNode</span><span class="symbol">.</span><span class="method">address</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/address/-%23-address">Address</a> ></span><div class="anchors"></div></div><div class="body"><p>The address of this HDNode.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">hdNode</span><span class="symbol">.</span><span class="method">mnemonic</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/hdnode/-%23-Mnemonic">Mnemonic</a></span><div class="anchors"></div></div><div class="body"><p>The mnemonic of this HDNode, if known.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">hdNode</span><span class="symbol">.</span><span class="method">path</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"></div></div><div class="body"><p>The path of this HDNode, if known. If the <i>mnemonic</i> is also known, this will match <code class="inline">mnemonic.path</code>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">hdNode</span><span class="symbol">.</span><span class="method">chainCode</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 > ></span><div class="anchors"></div></div><div class="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><div class="property show-anchors"><div class="signature"><span class="path">hdNode</span><span class="symbol">.</span><span class="method">index</span> <span class="arrow">⇒</span> <span class="returns">number</span><div class="anchors"></div></div><div class="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><div class="property show-anchors"><div class="signature"><span class="path">hdNode</span><span class="symbol">.</span><span class="method">depth</span> <span class="arrow">⇒</span> <span class="returns">number</span><div class="anchors"></div></div><div class="body"><p>The depth of this HDNode. This will match the number of components (less one, the <code class="inline">m/</code>) of the <i>path</i>.</p>
|
|
|
|
<p>Most developers will not need to use this.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">hdNode</span><span class="symbol">.</span><span class="method">extendedKey</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"></div></div><div class="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 <code class="inline">fromExtendedKey</code> class method) will result in reduced information.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/hdnode/-%23-HDNode--methods"></a><a name="/v5/api/utils/hdnode/-%23-hdnodes--HDNode--HDNode--methods"></a><a name="/v5/api/utils/hdnode/"></a><h3 class="show-anchors"><div>Methods<div class="anchors"><a class="self" href="#/v5/api/utils/hdnode/-%23-HDNode--methods"></a></div></div></h3>
|
|
<a name="/v5/api/utils/hdnode/-%23-HDNode-neuter"></a><div class="property show-anchors"><div class="signature"><span class="path">hdNode</span><span class="symbol">.</span><span class="method">neuter</span><span class="symbol">(</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/hdnode/-%23-HDNode">HDNode</a></span><div class="anchors"><a class="self" href="#/v5/api/utils/hdnode/-%23-HDNode-neuter"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/hdnode/src.ts/index.ts#L162">source</a></div></div><div class="body"><p>Return a new instance of <i>hdNode</i> with its private key removed but all other 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><a name="/v5/api/utils/hdnode/-%23-HDNode-derivePath"></a><div class="property show-anchors"><div class="signature"><span class="path">hdNode</span><span class="symbol">.</span><span class="method">derivePath</span><span class="symbol">(</span> <span class="param">path</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/hdnode/-%23-HDNode">HDNode</a></span><div class="anchors"><a class="self" href="#/v5/api/utils/hdnode/-%23-HDNode-derivePath"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/hdnode/src.ts/index.ts#L225">source</a></div></div><div class="body"><p>Return a new <a href="#/v5/api/utils/hdnode/-%23-HDNode">HDNode</a> which is the child of <i>hdNode</i> found by deriving <i>path</i>.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/hdnode/-%23-HDNode--utilities"></a><a name="/v5/api/utils/hdnode/-%23-hdnodes--HDNode--utilities"></a><a name="/v5/api/utils/hdnode/"></a><h2 class="show-anchors"><div>Other Functions<div class="anchors"><a class="self" href="#/v5/api/utils/hdnode/-%23-HDNode--utilities"></a></div></div></h2>
|
|
<a name="/v5/api/utils/hdnode/-%23-utils-mnemonicToSeed"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">mnemonicToSeed</span><span class="symbol">(</span> <span class="param">phrase</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">password</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 64 > ></span><div class="anchors"><a class="self" href="#/v5/api/utils/hdnode/-%23-utils-mnemonicToSeed"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/hdnode/src.ts/index.ts#L310">source</a></div></div><div class="body"><p>Convert a mnemonic phrase to a seed, according to <a href="https://en.bitcoin.it/wiki/BIP_0039">BIP-39</a>.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/hdnode/-%23-utils-mnemonicToEntropy"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">mnemonicToEntropy</span><span class="symbol">(</span> <span class="param">phrase</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">wordlist</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a> ></span><div class="anchors"><a class="self" href="#/v5/api/utils/hdnode/-%23-utils-mnemonicToEntropy"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/hdnode/src.ts/index.ts#L318">source</a></div></div><div class="body"><p>Convert a mnemonic phrase to its entropy, according to <a href="https://en.bitcoin.it/wiki/BIP_0039">BIP-39</a>.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/hdnode/-%23-utils-isValidMnemonic"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">isValidMnemonic</span><span class="symbol">(</span> <span class="param">phrase</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">wordlist</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">boolean</span><div class="anchors"><a class="self" href="#/v5/api/utils/hdnode/-%23-utils-isValidMnemonic"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/hdnode/src.ts/index.ts#L399">source</a></div></div><div class="body"><p>Returns true if <i>phrase</i> is a valid mnemonic phrase, by testing the checksum.</p>
|
|
|
|
</div></div><div class="page-separator"></div><a name="/v5/api/utils/logger/-%23-logging"></a><a name="/v5/api/utils/logger/-%23-logging"></a><a name="/v5/api/utils/logger/"></a><h1 class="show-anchors"><div>Logging<div class="anchors"><a class="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 <a href="#/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 <a href="#/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 <code class="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>
|
|
|
|
<a name="/v5/api/utils/logger/-%23-Logger"></a><a name="/v5/api/utils/logger/-%23-logging--Logger"></a><a name="/v5/api/utils/logger/"></a><h2 class="show-anchors"><div>Logger<div class="anchors"><a class="self" href="#/v5/api/utils/logger/-%23-Logger"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/logger/src.ts/index.ts#L143">source</a></div></div></h2>
|
|
<div class="property show-anchors"><div class="signature"><span class="modifier">new </span><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">Logger</span><span class="symbol">(</span> <span class="param">version</span> <span class="symbol">)</span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/logger/src.ts/index.ts#L150">source</a></div></div><div class="body"><p>Create a new logger which will include <i>version</i> in all errors thrown.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">Logger</span><span class="symbol">.</span><span class="method">globalLogger</span><span class="symbol">(</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/logger/-%23-Logger">Logger</a></span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/logger/src.ts/index.ts#L308">source</a></div></div><div class="body"><p>Returns the singleton global logger.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/logger/-%23-logging--Logger--logging-output"></a><a name="/v5/api/utils/logger/"></a><h3 class="show-anchors"><div>Logging Output<div class="anchors"><a class="self" href="#/v5/api/utils/logger/-%23-logging--Logger--logging-output"></a></div></div></h3>
|
|
<div class="property show-anchors"><div class="signature"><span class="path">logger</span><span class="symbol">.</span><span class="method">debug</span><span class="symbol">(</span> ...<span class="param">args</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">void</span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/logger/src.ts/index.ts#L167">source</a></div></div><div class="body"><p>Log debugging information.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">logger</span><span class="symbol">.</span><span class="method">info</span><span class="symbol">(</span> ...<span class="param">args</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">void</span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/logger/src.ts/index.ts#L171">source</a></div></div><div class="body"><p>Log generic information.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">logger</span><span class="symbol">.</span><span class="method">warn</span><span class="symbol">(</span> ...<span class="param">args</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">void</span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/logger/src.ts/index.ts#L175">source</a></div></div><div class="body"><p>Log warnings.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/logger/-%23-logging--Logger--errors"></a><a name="/v5/api/utils/logger/"></a><h3 class="show-anchors"><div>Errors<div class="anchors"><a class="self" href="#/v5/api/utils/logger/-%23-logging--Logger--errors"></a></div></div></h3><p>These functions honor the current <a href="#/v5/api/utils/logger/-%23-Logger--censorship">Censorship</a> and help create a standard error model for detecting and processing errors within Ethers.</p>
|
|
|
|
<div class="property show-anchors"><div class="signature"><span class="path">logger</span><span class="symbol">.</span><span class="method">makeError</span><span class="symbol">(</span> <span class="param">message</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">code</span> = <span class="param">UNKNOWN_ERROR</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">params</span> <span class="symbol">]</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Error</span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/logger/src.ts/index.ts#L179">source</a></div></div><div class="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><div class="property show-anchors"><div class="signature"><span class="path">logger</span><span class="symbol">.</span><span class="method">throwError</span><span class="symbol">(</span> <span class="param">message</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">code</span> = <span class="param">UNKNOWN_ERROR</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">params</span> <span class="symbol">]</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">never</span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/logger/src.ts/index.ts#L216">source</a></div></div><div class="body"><p>Throw an Error with <i>message</i> and an optional <i>code</i> and additional <i>params</i> set.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">logger</span><span class="symbol">.</span><span class="method">throwArgumentError</span><span class="symbol">(</span> <span class="param">message</span> <span class="symbol">,</span> <span class="param">name</span> <span class="symbol">,</span> <span class="param">value</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">never</span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/logger/src.ts/index.ts#L220">source</a></div></div><div class="body"><p>Throw an <a href="#/v5/api/utils/logger/-%23-errors--invalid-argument">INVALID_ARGUMENT</a> Error with <i>name</i> and <i>value</i>.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/logger/-%23-logging--Logger--usage-validation"></a><a name="/v5/api/utils/logger/"></a><h3 class="show-anchors"><div>Usage Validation<div class="anchors"><a class="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>
|
|
|
|
<a name="/v5/api/utils/logger/-%23-Logger-checkAbstract"></a><div class="property show-anchors"><div class="signature"><span class="path">logger</span><span class="symbol">.</span><span class="method">checkAbstract</span><span class="symbol">(</span> <span class="param">target</span> <span class="symbol">,</span> <span class="param">kind</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">void</span><div class="anchors"><a class="self" href="#/v5/api/utils/logger/-%23-Logger-checkAbstract"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/logger/src.ts/index.ts#L296">source</a></div></div><div class="body"><p>If <i>target</i> is <i>kind</i>, throws a <a href="#/v5/api/utils/logger/-%23-errors--unsupported-operation">UNSUPPORTED_OPERATION</a> error otherwise performs the same operations as <a href="#/v5/api/utils/logger/-%23-Logger-checkNew">checkNew</a>.</p>
|
|
|
|
<p>This is useful for ensuring abstract classes are not being instantiated.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/logger/-%23-Logger-checkArgumentCount"></a><div class="property show-anchors"><div class="signature"><span class="path">logger</span><span class="symbol">.</span><span class="method">checkArgumentCount</span><span class="symbol">(</span> <span class="param">count</span> <span class="symbol">,</span> <span class="param">expectedCount</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">message</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">void</span><div class="anchors"><a class="self" href="#/v5/api/utils/logger/-%23-Logger-checkArgumentCount"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/logger/src.ts/index.ts#L268">source</a></div></div><div class="body"><p>If <i>count</i> is not equal to <i>expectedCount</i>, throws a <a href="#/v5/api/utils/logger/-%23-errors--missing-argument">MISSING_ARGUMENT</a> or <a href="#/v5/api/utils/logger/-%23-errors--unexpected-argument">UNEXPECTED_ARGUMENT</a> error.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/logger/-%23-Logger-checkNew"></a><div class="property show-anchors"><div class="signature"><span class="path">logger</span><span class="symbol">.</span><span class="method">checkNew</span><span class="symbol">(</span> <span class="param">target</span> <span class="symbol">,</span> <span class="param">kind</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">void</span><div class="anchors"><a class="self" href="#/v5/api/utils/logger/-%23-Logger-checkNew"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/logger/src.ts/index.ts#L290">source</a></div></div><div class="body"><p>If <i>target</i> is not a valid <code class="inline">this</code> or <code class="inline">target</code> value, throw a <a href="#/v5/api/utils/logger/-%23-errors--missing-new">MISSING_NEW</a> error. This is useful to ensure callers of a Class are using <code class="inline">new</code>.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/logger/-%23-Logger-checkNoralize"></a><div class="property show-anchors"><div class="signature"><span class="path">logger</span><span class="symbol">.</span><span class="method">checkNormalize</span><span class="symbol">(</span> <span class="param">message</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">void</span><div class="anchors"><a class="self" href="#/v5/api/utils/logger/-%23-Logger-checkNoralize"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/logger/src.ts/index.ts#L237">source</a></div></div><div class="body"><p>Check that the environment has a correctly functioning <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/normalize">String.normalize</a>. If not, a <a href="#/v5/api/utils/logger/-%23-errors--unsupported-operation">UNSUPPORTED_OPERATION</a> error is thrown.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/logger/-%23-Logger-checkSafeUint53"></a><div class="property show-anchors"><div class="signature"><span class="path">logger</span><span class="symbol">.</span><span class="method">checkSafeUint53</span><span class="symbol">(</span> <span class="param">value</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">message</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">void</span><div class="anchors"><a class="self" href="#/v5/api/utils/logger/-%23-Logger-checkSafeUint53"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/logger/src.ts/index.ts#L246">source</a></div></div><div class="body"><p>If <i>value</i> is not safe as a <a href="https://en.wikipedia.org/wiki/Double-precision_floating-point_format">JavaScript number</a>, throws a <a href="#/v5/api/utils/logger/-%23-errors--numeric-fault">NUMERIC_FAULT</a> error.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/logger/-%23-Logger--censorship"></a><a name="/v5/api/utils/logger/-%23-logging--Logger--Logger--censorship"></a><a name="/v5/api/utils/logger/"></a><h3 class="show-anchors"><div>Censorship<div class="anchors"><a class="self" href="#/v5/api/utils/logger/-%23-Logger--censorship"></a></div></div></h3>
|
|
<a name="/v5/api/utils/logger/-%23-Logger-setCensorship"></a><div class="property show-anchors"><div class="signature"><span class="path">Logger</span><span class="symbol">.</span><span class="method">setCensorship</span><span class="symbol">(</span> <span class="param">censor</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">permanent</span> = <span class="param">false</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">void</span><div class="anchors"><a class="self" href="#/v5/api/utils/logger/-%23-Logger-setCensorship"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/logger/src.ts/index.ts#L313">source</a></div></div><div class="body"><p>Set error censorship, optionally preventing errors from being uncensored.</p>
|
|
|
|
<p>In production applications, this prevents any error from leaking information by masking the message and values of errors.</p>
|
|
|
|
<p>This can impact debugging, making it substantially more difficult.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/logger/-%23-Logger-setLogLevel"></a><div class="property show-anchors"><div class="signature"><span class="path">Logger</span><span class="symbol">.</span><span class="method">setLogLevel</span><span class="symbol">(</span> <span class="param">logLevel</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">void</span><div class="anchors"><a class="self" href="#/v5/api/utils/logger/-%23-Logger-setLogLevel"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/logger/src.ts/index.ts#L331">source</a></div></div><div class="body"><p>Set the log level, to suppress logging output below a <a href="#/v5/api/utils/logger/-%23-Logger-levels">particular log level</a>.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/logger/-%23-errors"></a><a name="/v5/api/utils/logger/-%23-logging--errors"></a><a name="/v5/api/utils/logger/"></a><h2 class="show-anchors"><div>Errors<div class="anchors"><a class="self" href="#/v5/api/utils/logger/-%23-errors"></a></div></div></h2><p>Every error in Ethers has a <code class="inline">code</code> value, which is a string that will match one of the following error codes.</p>
|
|
|
|
<a name="/v5/api/utils/logger/-%23-errors-generic"></a><a name="/v5/api/utils/logger/-%23-logging--errors--errors-generic"></a><a name="/v5/api/utils/logger/"></a><h3 class="show-anchors"><div>Generic Error Codes<div class="anchors"><a class="self" href="#/v5/api/utils/logger/-%23-errors-generic"></a></div></div></h3>
|
|
<a name="/v5/api/utils/logger/-%23-errors--not-implemented"></a><div class="property show-anchors"><div class="signature"><span class="path">Logger</span><span class="symbol">.</span><span class="path">errors</span><span class="symbol">.</span><span class="method">NOT_IMPLEMENTED</span><div class="anchors"><a class="self" href="#/v5/api/utils/logger/-%23-errors--not-implemented"></a></div></div><div class="body"><p>The operation is not implemented. This may occur when calling a method on a sub-class that has not fully implemented its abstract superclass.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/logger/-%23-errors--server-error"></a><div class="property show-anchors"><div class="signature"><span class="path">Logger</span><span class="symbol">.</span><span class="path">errors</span><span class="symbol">.</span><span class="method">SERVER_ERROR</span><div class="anchors"><a class="self" href="#/v5/api/utils/logger/-%23-errors--server-error"></a></div></div><div class="body"><p>There was an error communicating with a server.</p>
|
|
|
|
<p>This may occur for a number of reasons, for example:</p>
|
|
|
|
<p><ul><li>a <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS">CORS</a> issue; this is quite often the problem and also the hardest to diagnose and fix, so it is very beneficial to familiarize yourself with CORS; some backends allow you configure your CORS, such as the geth command-line or conifguration files or the INFURA and Alchemy dashboards by specifing allowed Origins, methods, etc. </li><li>an SSL issue; for example, if you are trying to connect to a local node via HTTP but are serving the content from a secure HTTPS website </li><li>a link issue; a firewall is preventing the traffic from reaching the server </li><li>a server issue; the server is down, or is returning 500 error codes </li><li>a backend DDoS mitigation proxy; for example, Etherscan operates behind a Cloudflare proxy, which will block traffic if the request is sent via specific User Agents or the client fingerprint is detected as a bot in some cases </li></ul></p>
|
|
|
|
</div></div><a name="/v5/api/utils/logger/-%23-errors--timeout"></a><div class="property show-anchors"><div class="signature"><span class="path">Logger</span><span class="symbol">.</span><span class="path">errors</span><span class="symbol">.</span><span class="method">TIMEOUT</span><div class="anchors"><a class="self" href="#/v5/api/utils/logger/-%23-errors--timeout"></a></div></div><div class="body"><p>A timeout occurred.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/logger/-%23-errors--unknown-error"></a><div class="property show-anchors"><div class="signature"><span class="path">Logger</span><span class="symbol">.</span><span class="path">errors</span><span class="symbol">.</span><span class="method">UNKNOWN_ERROR</span><div class="anchors"><a class="self" href="#/v5/api/utils/logger/-%23-errors--unknown-error"></a></div></div><div class="body"><p>A generic unknown error.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/logger/-%23-errors--unsupported-operation"></a><div class="property show-anchors"><div class="signature"><span class="path">Logger</span><span class="symbol">.</span><span class="path">errors</span><span class="symbol">.</span><span class="method">UNSUPPORTED_OPERATION</span><div class="anchors"><a class="self" href="#/v5/api/utils/logger/-%23-errors--unsupported-operation"></a></div></div><div class="body"><p>The operation is not supported.</p>
|
|
|
|
<p>This can happen for a variety reasons, for example:</p>
|
|
|
|
<p><ul><li>Some backends do not support certain operations; such as passing a blockTag to an <a href="#/v5/api/providers/api-providers/-%23-EtherscanProvider">EtherscanProvider</a> for <a href="#/v5/api/providers/provider/-%23-Provider-call">call</a> </li><li>A <a href="#/v5/api/contract/contract/">Contract</a> object connected to <a href="#/v5/api/providers/provider/">Provider</a> (instead of a <a href="#/v5/api/signer/-%23-Signer">Signer</a>) cannot <a href="#/v5/api/signer/-%23-Signer-signTransaction">sign</a> or <a href="#/v5/api/signer/-%23-Signer-sendTransaction">send</a> transactions </li><li>a <a href="#/v5/api/contract/contract/">Contract</a> connected to a <a href="#/v5/api/signer/-%23-Signer">Signer</a> without a <a href="#/v5/api/providers/provider/">Provider</a> is write-only and cannot estimate gas or execute static calls </li></ul></p>
|
|
|
|
</div></div><a name="/v5/api/utils/logger/-%23-errors-safety"></a><a name="/v5/api/utils/logger/-%23-logging--errors--errors-safety"></a><a name="/v5/api/utils/logger/"></a><h3 class="show-anchors"><div>Safety Error Codes<div class="anchors"><a class="self" href="#/v5/api/utils/logger/-%23-errors-safety"></a></div></div></h3>
|
|
<a name="/v5/api/utils/logger/-%23-errors--buffer-overrun"></a><div class="property show-anchors"><div class="signature"><span class="path">Logger</span><span class="symbol">.</span><span class="path">errors</span><span class="symbol">.</span><span class="method">BUFFER_OVERRUN</span><div class="anchors"><a class="self" href="#/v5/api/utils/logger/-%23-errors--buffer-overrun"></a></div></div><div class="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>
|
|
|
|
<p>This can occur if a contract erroneously returns invalid ABI-encoded data or RLP data is malformed.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/logger/-%23-errors--numeric-fault"></a><div class="property show-anchors"><div class="signature"><span class="path">Logger</span><span class="symbol">.</span><span class="path">errors</span><span class="symbol">.</span><span class="method">NUMERIC_FAULT</span><div class="anchors"><a class="self" href="#/v5/api/utils/logger/-%23-errors--numeric-fault"></a></div></div><div class="body"><p>There was an invalid operation done on numeric values.</p>
|
|
|
|
<p>Common cases of this occur when there is <a href="https://en.wikipedia.org/wiki/Integer_overflow">overflow</a>, <a href="https://en.wikipedia.org/wiki/Arithmetic_underflow">arithmetic underflow</a> in fixed numeric types or division by zero.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/logger/-%23-errors-usage"></a><a name="/v5/api/utils/logger/-%23-logging--errors--errors-usage"></a><a name="/v5/api/utils/logger/"></a><h3 class="show-anchors"><div>Usage Error Codes<div class="anchors"><a class="self" href="#/v5/api/utils/logger/-%23-errors-usage"></a></div></div></h3>
|
|
<a name="/v5/api/utils/logger/-%23-errors--invalid-argument"></a><div class="property show-anchors"><div class="signature"><span class="path">Logger</span><span class="symbol">.</span><span class="path">errors</span><span class="symbol">.</span><span class="method">INVALID_ARGUMENT</span><div class="anchors"><a class="self" href="#/v5/api/utils/logger/-%23-errors--invalid-argument"></a></div></div><div class="body"><p>The type or value of an argument is invalid. This will generally also include the <code class="inline">name</code> and <code class="inline">value</code> of the argument. Any function which accepts sensitive data (such as a private key) will include the string <code class="inline">"[[REDACTED]]"</code> instead of the value passed in.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/logger/-%23-errors--missing-argument"></a><div class="property show-anchors"><div class="signature"><span class="path">Logger</span><span class="symbol">.</span><span class="path">errors</span><span class="symbol">.</span><span class="method">MISSING_ARGUMENT</span><div class="anchors"><a class="self" href="#/v5/api/utils/logger/-%23-errors--missing-argument"></a></div></div><div class="body"><p>An expected parameter was not specified.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/logger/-%23-errors--missing-new"></a><div class="property show-anchors"><div class="signature"><span class="path">Logger</span><span class="symbol">.</span><span class="path">errors</span><span class="symbol">.</span><span class="method">MISSING_NEW</span><div class="anchors"><a class="self" href="#/v5/api/utils/logger/-%23-errors--missing-new"></a></div></div><div class="body"><p>An object is a Class, but is not being called with <code class="inline">new</code>.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/logger/-%23-errors--unexpected-argument"></a><div class="property show-anchors"><div class="signature"><span class="path">Logger</span><span class="symbol">.</span><span class="path">errors</span><span class="symbol">.</span><span class="method">UNEXPECTED_ARGUMENT</span><div class="anchors"><a class="self" href="#/v5/api/utils/logger/-%23-errors--unexpected-argument"></a></div></div><div class="body"><p>Too many parameters we passed into a function.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/logger/-%23-errors-ethereum"></a><a name="/v5/api/utils/logger/-%23-logging--errors--errors-ethereum"></a><a name="/v5/api/utils/logger/"></a><h3 class="show-anchors"><div>Ethereum Error Codes<div class="anchors"><a class="self" href="#/v5/api/utils/logger/-%23-errors-ethereum"></a></div></div></h3>
|
|
<a name="/v5/api/utils/logger/-%23-errors--call-exception"></a><div class="property show-anchors"><div class="signature"><span class="path">Logger</span><span class="symbol">.</span><span class="path">errors</span><span class="symbol">.</span><span class="method">CALL_EXCEPTION</span><div class="anchors"><a class="self" href="#/v5/api/utils/logger/-%23-errors--call-exception"></a></div></div><div class="body"><p>An attempt to call a blockchain contract (getter) resulted in a revert or other error, such as insufficient gas (out-of-gas) or an invalid opcode. This can also occur during gas estimation or if waiting for a <a href="#/v5/api/providers/types/-%23-providers-TransactionReceipt">TransactionReceipt</a> which failed during execution.</p>
|
|
|
|
<p>Consult the contract to determine the cause, such as a failed condition in a <code class="inline">require</code> statement. The <code class="inline">reason</code> property may provide more context for the cause of this error.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/logger/-%23-errors--insufficient-funds"></a><div class="property show-anchors"><div class="signature"><span class="path">Logger</span><span class="symbol">.</span><span class="path">errors</span><span class="symbol">.</span><span class="method">INSUFFICIENT_FUNDS</span><div class="anchors"><a class="self" href="#/v5/api/utils/logger/-%23-errors--insufficient-funds"></a></div></div><div class="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, as well as 35000 gas if a transaction contains no <code class="inline">to</code> property and is therefore expected to create a new account.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/logger/-%23-errors--network"></a><div class="property show-anchors"><div class="signature"><span class="path">Logger</span><span class="symbol">.</span><span class="path">errors</span><span class="symbol">.</span><span class="method">NETWORK_ERROR</span><div class="anchors"><a class="self" href="#/v5/api/utils/logger/-%23-errors--network"></a></div></div><div class="body"><p>An Ethereum network validation error, such as an invalid chain ID.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/logger/-%23-errors--nonce-expired"></a><div class="property show-anchors"><div class="signature"><span class="path">Logger</span><span class="symbol">.</span><span class="path">errors</span><span class="symbol">.</span><span class="method">NONCE_EXPIRED</span><div class="anchors"><a class="self" href="#/v5/api/utils/logger/-%23-errors--nonce-expired"></a></div></div><div class="body"><p>The nonce being specified has already been used in a mined transaction.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/logger/-%23-errors--replacement-underpriced"></a><div class="property show-anchors"><div class="signature"><span class="path">Logger</span><span class="symbol">.</span><span class="path">errors</span><span class="symbol">.</span><span class="method">REPLACEMENT_UNDERPRICED</span><div class="anchors"><a class="self" href="#/v5/api/utils/logger/-%23-errors--replacement-underpriced"></a></div></div><div class="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. This is not enforced by the protocol, as it deals with unmined transactions, and can be configured by each node, however to ensure a transaction is propagated to a miner it is best practice to follow the defaults most nodes have enabled.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/logger/-%23-errors--unpredicatable-gas-limit"></a><div class="property show-anchors"><div class="signature"><span class="path">Logger</span><span class="symbol">.</span><span class="path">errors</span><span class="symbol">.</span><span class="method">UNPREDICTABLE_GAS_LIMIT</span><div class="anchors"><a class="self" href="#/v5/api/utils/logger/-%23-errors--unpredicatable-gas-limit"></a></div></div><div class="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>
|
|
|
|
</div></div><a name="/v5/api/utils/logger/-%23-Logger-levels"></a><a name="/v5/api/utils/logger/-%23-logging--Logger-levels"></a><a name="/v5/api/utils/logger/"></a><h2 class="show-anchors"><div>Log Levels<div class="anchors"><a class="self" href="#/v5/api/utils/logger/-%23-Logger-levels"></a></div></div></h2>
|
|
<div class="property show-anchors"><div class="signature"><span class="path">Logger</span><span class="symbol">.</span><span class="path">levels</span><span class="symbol">.</span><span class="method">DEBUG</span><div class="anchors"></div></div><div class="body"><p>Log all output, including debugging information.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">Logger</span><span class="symbol">.</span><span class="path">levels</span><span class="symbol">.</span><span class="method">INFO</span><div class="anchors"></div></div><div class="body"><p>Only log output for informational, warnings and errors.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">Logger</span><span class="symbol">.</span><span class="path">levels</span><span class="symbol">.</span><span class="method">WARNING</span><div class="anchors"></div></div><div class="body"><p>Only log output for warnings and errors.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">Logger</span><span class="symbol">.</span><span class="path">levels</span><span class="symbol">.</span><span class="method">ERROR</span><div class="anchors"></div></div><div class="body"><p>Only log output for errors.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">Logger</span><span class="symbol">.</span><span class="path">levels</span><span class="symbol">.</span><span class="method">OFF</span><div class="anchors"></div></div><div class="body"><p>Do not output any logs.</p>
|
|
|
|
</div></div><div class="page-separator"></div><a name="/v5/api/utils/properties/-%23-property-utilities"></a><a name="/v5/api/utils/properties/"></a><h1 class="show-anchors"><div>Property Utilities<div class="anchors"><a class="self" href="#/v5/api/utils/properties/-%23-property-utilities"></a></div></div></h1><p>This is a collection of utility functions used for handling properties in a platform-safe way.</p>
|
|
|
|
<p>The next major version of ethers will no longer be compatible with ES3, so many of these will be removed in favor of the built-in options available in ES2015 and above.</p>
|
|
|
|
<div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">checkProperties</span><span class="symbol">(</span> <span class="param">object</span> <span class="symbol">,</span> <span class="param">check</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">void</span><div class="anchors"></div></div><div class="body"><p>Checks that <i>object</i> only contains properties included in <i>check</i>, and throws <a href="#/v5/api/utils/logger/-%23-errors--invalid-argument">INVALID_ARGUMENT</a> if not.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">deepCopy</span><span class="symbol">(</span> <span class="param">anObject</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">any</span><div class="anchors"></div></div><div class="body"><p>Creates a recursive copy of <i>anObject</i>. Frozen (i.e. and other known immutable) objects are copied by reference.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">defineReadOnly</span><span class="symbol">(</span> <span class="param">anObject</span> <span class="symbol">,</span> <span class="param">name</span> <span class="symbol">,</span> <span class="param">value</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">void</span><div class="anchors"></div></div><div class="body"><p>Uses the <code class="inline">Object.defineProperty</code> method to set a read-only property on an object.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">getStatic</span><span class="symbol">(</span> <span class="param">aConstructor</span> <span class="symbol">,</span> <span class="param">key</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">any</span><div class="anchors"></div></div><div class="body"><p>Recursively check for a static method <i>key</i> on an inheritance chain from <i>aConstructor</i> to all ancestors.</p>
|
|
|
|
<p>This is used to mimic behaviour in other languages where <code class="inline">this</code> in a static method will also search ancestors.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/properties/-%23-utils-resolveproperties"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">resolveProperties</span><span class="symbol">(</span> <span class="param">anObject</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< any ></span><div class="anchors"><a class="self" href="#/v5/api/utils/properties/-%23-utils-resolveproperties"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/properties/src.ts/index.ts#L32">source</a></div></div><div class="body"><p>Retruns a Promise which resolves all child values on <i>anObject</i>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">shallowCopy</span><span class="symbol">(</span> <span class="param">anObject</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">any</span><div class="anchors"></div></div><div class="body"><p>Returns a shallow copy of <i>anObject</i>. This is the same as using <code class="inline">Object.assign({ }, anObject)</code>.</p>
|
|
|
|
</div></div><div class="page-separator"></div><a name="/v5/api/utils/signing-key/-%23-SigningKey"></a><a name="/v5/api/utils/signing-key/-%23-SigningKey"></a><a name="/v5/api/utils/signing-key/"></a><h1 class="show-anchors"><div>Signing Key<div class="anchors"><a class="self" href="#/v5/api/utils/signing-key/-%23-SigningKey"></a></div></div></h1>
|
|
<a name="/v5/api/utils/signing-key/-%23-SigningKey-constructor"></a><div class="property show-anchors"><div class="signature"><span class="modifier">new </span><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">SigningKey</span><span class="symbol">(</span> <span class="param">privateKey</span> <span class="symbol">)</span><div class="anchors"><a class="self" href="#/v5/api/utils/signing-key/-%23-SigningKey-constructor"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/signing-key/src.ts/index.ts#L32">source</a></div></div><div class="body"><p>Create a new SigningKey for <i>privateKey</i>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">signingKey</span><span class="symbol">.</span><span class="method">privateKey</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 > ></span><div class="anchors"></div></div><div class="body"><p>The private key for this Signing Key.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">signingKey</span><span class="symbol">.</span><span class="method">publicKey</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 65 > ></span><div class="anchors"></div></div><div class="body"><p>The uncompressed public key for this Signing Key. It will always be 65 bytes (130 nibbles) and begins with <code class="inline">0x04</code>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">signingKey</span><span class="symbol">.</span><span class="method">compressedPublicKey</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 33 > ></span><div class="anchors"></div></div><div class="body"><p>The compressed public key for this Signing Key. It will always be 33 bytes (66 nibbles) and begins with either <code class="inline">0x02</code> or <code class="inline">0x03</code>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">signingKey</span><span class="symbol">.</span><span class="method">signDigest</span><span class="symbol">(</span> <span class="param">digest</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/bytes/-%23-Signature">Signature</a></span><div class="anchors"></div></div><div class="body"><p>Sign the <i>digest</i> and return the signature.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">signingKey</span><span class="symbol">.</span><span class="method">computeSharedSecret</span><span class="symbol">(</span> <span class="param">otherKey</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 > ></span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/signing-key/src.ts/index.ts#L65">source</a></div></div><div class="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>
|
|
|
|
<p>It is best practice that each party computes the hash of this before using it as a symmetric key.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">SigningKey</span><span class="symbol">.</span><span class="method">isSigningKey</span><span class="symbol">(</span> <span class="param">anObject</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">boolean</span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/signing-key/src.ts/index.ts#L71">source</a></div></div><div class="body"><p>Returns true if <i>anObject</i> is a SigningKey.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/signing-key/-%23-SigningKey--other-functions"></a><a name="/v5/api/utils/signing-key/"></a><h2 class="show-anchors"><div>Other Functions<div class="anchors"><a class="self" href="#/v5/api/utils/signing-key/-%23-SigningKey--other-functions"></a></div></div></h2>
|
|
<a name="/v5/api/utils/signing-key/-%23-utils-verifyMessage"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">verifyMessage</span><span class="symbol">(</span> <span class="param">message</span> <span class="symbol">,</span> <span class="param">signature</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/address/-%23-address">Address</a> ></span><div class="anchors"><a class="self" href="#/v5/api/utils/signing-key/-%23-utils-verifyMessage"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/wallet/src.ts/index.ts#L198">source</a></div></div><div class="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 <a href="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><a name="/v5/api/utils/signing-key/-%23-utils-verifyTypedData"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">verifyTypedData</span><span class="symbol">(</span> <span class="param">domain</span> <span class="symbol">,</span> <span class="param">types</span> <span class="symbol">,</span> <span class="param">value</span> <span class="symbol">,</span> <span class="param">signature</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/address/-%23-address">Address</a> ></span><div class="anchors"><a class="self" href="#/v5/api/utils/signing-key/-%23-utils-verifyTypedData"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/wallet/src.ts/index.ts#L202">source</a></div></div><div class="body"><p>Returns the address that signed the <a href="https://eips.ethereum.org/EIPS/eip-712">EIP-712</a> <i>value</i> for the <i>domain</i> and <i>types</i> to produce the signature.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/signing-key/-%23-utils-recoverPublicKey"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">recoverPublicKey</span><span class="symbol">(</span> <span class="param">digest</span> <span class="symbol">,</span> <span class="param">signature</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 65 > ></span><div class="anchors"><a class="self" href="#/v5/api/utils/signing-key/-%23-utils-recoverPublicKey"></a></div></div><div class="body"><p>Returns the uncompressed public key (i.e. the first byte will be <code class="inline">0x04</code>) of the private key that was used to sign <i>digest</i> which gave the <i>signature</i>.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/signing-key/-%23-utils-computePublicKey"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">computePublicKey</span><span class="symbol">(</span> <span class="param">key</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">compressed</span> = <span class="param">false</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a> ></span><div class="anchors"><a class="self" href="#/v5/api/utils/signing-key/-%23-utils-computePublicKey"></a></div></div><div class="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><div class="page-separator"></div><a name="/v5/api/utils/strings/-%23-strings"></a><a name="/v5/api/utils/strings/-%23-strings"></a><a name="/v5/api/utils/strings/"></a><h1 class="show-anchors"><div>Strings<div class="anchors"><a class="self" href="#/v5/api/utils/strings/-%23-strings"></a></div></div></h1><p>A <b>String</b> is a representation of a human-readable input of output, which are often taken for granted.</p>
|
|
|
|
<p>When dealing with blockchains, properly handling human-readable and human-provided data is important to prevent loss of funds, assets, incorrect permissions, etc.</p>
|
|
|
|
<a name="/v5/api/utils/strings/-%23-Bytes32String"></a><a name="/v5/api/utils/strings/-%23-strings--Bytes32String"></a><a name="/v5/api/utils/strings/"></a><h2 class="show-anchors"><div>Bytes32String<div class="anchors"><a class="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>
|
|
|
|
<div class="definition container-box note"><div class="term">Note</div><div class="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><a name="/v5/api/utils/strings/-%23-utils-parseBytes32"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">parseBytes32String</span><span class="symbol">(</span> <span class="param">aBytesLike</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"><a class="self" href="#/v5/api/utils/strings/-%23-utils-parseBytes32"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/strings/src.ts/bytes32.ts#L21">source</a></div></div><div class="body"><p>Returns the decoded string represented by the <code class="inline">Bytes32</code> encoded data.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/strings/-%23-utils-formatBytes32"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">formatBytes32String</span><span class="symbol">(</span> <span class="param">text</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 > ></span><div class="anchors"><a class="self" href="#/v5/api/utils/strings/-%23-utils-formatBytes32"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/strings/src.ts/bytes32.ts#L9">source</a></div></div><div class="body"><p>Returns a <code class="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>
|
|
|
|
</div></div><a name="/v5/api/utils/strings/-%23-strings-utf8"></a><a name="/v5/api/utils/strings/-%23-strings--strings-utf8"></a><a name="/v5/api/utils/strings/"></a><h2 class="show-anchors"><div>UTF-8 Strings<div class="anchors"><a class="self" href="#/v5/api/utils/strings/-%23-strings-utf8"></a></div></div></h2>
|
|
<a name="/v5/api/utils/strings/-%23-utils-toUtf8Bytes"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">toUtf8Bytes</span><span class="symbol">(</span> <span class="param">text</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">form</span> = <span class="param">current</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Uint8Array</span><div class="anchors"><a class="self" href="#/v5/api/utils/strings/-%23-utils-toUtf8Bytes"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/strings/src.ts/utf8.ts#L202">source</a></div></div><div class="body"><p>Returns the UTF-8 bytes of <i>text</i>, optionally normalizing it using the <a href="#/v5/api/utils/strings/-%23-strings--unicode-normalization-form">UnicodeNormalizationForm</a> <i>form</i>.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/strings/-%23-utils-toUtf8CodePoints"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">toUtf8CodePoints</span><span class="symbol">(</span> <span class="param">text</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">form</span> = <span class="param">current</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Array< number ></span><div class="anchors"><a class="self" href="#/v5/api/utils/strings/-%23-utils-toUtf8CodePoints"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/strings/src.ts/utf8.ts#L293">source</a></div></div><div class="body"><p>Returns the Array of codepoints of <i>text</i>, optionally normalized using the <a href="#/v5/api/utils/strings/-%23-strings--unicode-normalization-form">UnicodeNormalizationForm</a> <i>form</i>.</p>
|
|
|
|
</div></div><div class="definition container-box note"><div class="term">Note</div><div class="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 <code class="inline">string.split("")</code>, which destroys surrogate pairs, splitting between each UTF-16 codeunit instead.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/strings/-%23-utils-toUtf8String"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">toUtf8String</span><span class="symbol">(</span> <span class="param">aBytesLike</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">onError</span> = <span class="param">error</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"><a class="self" href="#/v5/api/utils/strings/-%23-utils-toUtf8String"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/strings/src.ts/utf8.ts#L289">source</a></div></div><div class="body"><p>Returns the string represented by the UTF-8 bytes of <i>aBytesLike</i>.</p>
|
|
|
|
<p>The <i>onError</i> is a <a href="#/v5/api/utils/strings/-%23-strings--error-handling">Custom UTF-8 Error function</a> and if not specified it defaults to the <a href="#/v5/api/utils/strings/-%23-strings--Utf8Error">error</a> function, which throws an error on <b>any</b> UTF-8 error.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/strings/-%23-strings--unicode-normalization-form"></a><a name="/v5/api/utils/strings/-%23-strings--strings--unicode-normalization-form"></a><a name="/v5/api/utils/strings/"></a><h2 class="show-anchors"><div>UnicodeNormalizationForm<div class="anchors"><a class="self" href="#/v5/api/utils/strings/-%23-strings--unicode-normalization-form"></a><a class="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 <a href="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>
|
|
|
|
<div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="path">UnicodeNormalizationForm</span><span class="symbol">.</span><span class="method">current</span><div class="anchors"></div></div><div class="body"><p>Maintain the current normalization form.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="path">UnicodeNormalizationForm</span><span class="symbol">.</span><span class="method">NFC</span><div class="anchors"></div></div><div class="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, <code class="inline">0x00e9</code>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="path">UnicodeNormalizationForm</span><span class="symbol">.</span><span class="method">NFD</span><div class="anchors"></div></div><div class="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, <code class="inline">"0x0065"</code> (which is the letter <code class="inline">"e"</code>) and <code class="inline">"0x0301"</code> which is a special diacritic UTF-8 codepoint which indicates the previous character should have an acute accent.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="path">UnicodeNormalizationForm</span><span class="symbol">.</span><span class="method">NFKC</span><div class="anchors"></div></div><div class="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 <code class="inline">"0x2160"</code>, is folded into the capital letter I, <code class="inline">"0x0049"</code>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="path">UnicodeNormalizationForm</span><span class="symbol">.</span><span class="method">NFKD</span><div class="anchors"></div></div><div class="body"><p>The Decomposed Normalization Form with Canonical Equivalence. See NFKC for more an example.</p>
|
|
|
|
</div></div><div class="definition container-box note"><div class="term">Note</div><div class="body"><p>Only certain specified characters are folded in Canonical Equivalence, and thus it should <b>not</b> be considered a method to achieve <i>any</i> level of security from <a href="https://en.wikipedia.org/wiki/IDN_homograph_attack">homoglyph attacks</a>.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/strings/-%23-strings--error-handling"></a><a name="/v5/api/utils/strings/-%23-strings--strings--error-handling"></a><a name="/v5/api/utils/strings/"></a><h2 class="show-anchors"><div>Custom UTF-8 Error Handling<div class="anchors"><a class="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>
|
|
|
|
<div class="property show-anchors"><div class="signature"><span class="method">errorFunction</span><span class="symbol">(</span> <span class="param">reason</span> <span class="symbol">,</span> <span class="param">offset</span> <span class="symbol">,</span> <span class="param">bytes</span> <span class="symbol">,</span> <span class="param">output</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">badCodepoint</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">number</span><div class="anchors"></div></div><div class="body"><p>The <i>reason</i> is one of the <a href="#/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>
|
|
|
|
</div></div><a name="/v5/api/utils/strings/-%23-strings--error-reasons"></a><a name="/v5/api/utils/strings/-%23-strings--strings--error-handling--strings--error-reasons"></a><a name="/v5/api/utils/strings/"></a><h3 class="show-anchors"><div>UTF-8 Error Reasons<div class="anchors"><a class="self" href="#/v5/api/utils/strings/-%23-strings--error-reasons"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/strings/src.ts/utf8.ts#L19">source</a></div></div></h3>
|
|
<div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="path">Utf8ErrorReason</span><span class="symbol">.</span><span class="method">BAD_PREFIX</span><div class="anchors"></div></div><div class="body"><p>A byte was encountered which is invalid to begin a UTF-8 byte sequence with.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="path">Utf8ErrorReason</span><span class="symbol">.</span><span class="method">MISSING_CONTINUE</span><div class="anchors"></div></div><div class="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><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="path">Utf8ErrorReason</span><span class="symbol">.</span><span class="method">OUT_OF_RANGE</span><div class="anchors"></div></div><div class="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><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="path">Utf8ErrorReason</span><span class="symbol">.</span><span class="method">OVERLONG</span><div class="anchors"></div></div><div class="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 <a href="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 <code class="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><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="path">Utf8ErrorReason</span><span class="symbol">.</span><span class="method">OVERRUN</span><div class="anchors"></div></div><div class="body"><p>The string does not have enough characters remaining for the length of this sequence.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="path">Utf8ErrorReason</span><span class="symbol">.</span><span class="method">UNEXPECTED_CONTINUE</span><div class="anchors"></div></div><div class="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><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="path">Utf8ErrorReason</span><span class="symbol">.</span><span class="method">UTF16_SURROGATE</span><div class="anchors"></div></div><div class="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><a name="/v5/api/utils/strings/-%23-strings--strings--error-handling--provided-utf-8-error-handling-functions"></a><a name="/v5/api/utils/strings/"></a><h3 class="show-anchors"><div>Provided UTF-8 Error Handling Functions<div class="anchors"><a class="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>
|
|
|
|
<a name="/v5/api/utils/strings/-%23-strings--Utf8Error"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="path">Utf8ErrorFuncs</span><span class="symbol">.</span><span class="method">error</span><div class="anchors"><a class="self" href="#/v5/api/utils/strings/-%23-strings--Utf8Error"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/strings/src.ts/utf8.ts#L55">source</a></div></div><div class="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><a name="/v5/api/utils/strings/-%23-strings--Utf8Ignore"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="path">Utf8ErrorFuncs</span><span class="symbol">.</span><span class="method">ignore</span><div class="anchors"><a class="self" href="#/v5/api/utils/strings/-%23-strings--Utf8Ignore"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/strings/src.ts/utf8.ts#L59">source</a></div></div><div class="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><a name="/v5/api/utils/strings/-%23-strings--Utf8Replace"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="path">Utf8ErrorFuncs</span><span class="symbol">.</span><span class="method">replace</span><div class="anchors"><a class="self" href="#/v5/api/utils/strings/-%23-strings--Utf8Replace"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/strings/src.ts/utf8.ts#L81">source</a></div></div><div class="body"><p>This will replace all invalid sequences (by consuming invalid prefix bytes and any following continuation bytes) with the <a href="https://en.wikipedia.org/wiki/Specials_%28Unicode_block%29#Replacement_character">UTF-8 Replacement Character</a>, (i.e. U+FFFD).</p>
|
|
|
|
</div></div><div class="page-separator"></div><a name="/v5/api/utils/transactions/-%23-transactions"></a><a name="/v5/api/utils/transactions/-%23-transactions"></a><a name="/v5/api/utils/transactions/"></a><h1 class="show-anchors"><div>Transactions<div class="anchors"><a class="self" href="#/v5/api/utils/transactions/-%23-transactions"></a></div></div></h1>
|
|
<a name="/v5/api/utils/transactions/-%23-transactions--types"></a><a name="/v5/api/utils/transactions/-%23-transactions--transactions--types"></a><a name="/v5/api/utils/transactions/"></a><h2 class="show-anchors"><div>Types<div class="anchors"><a class="self" href="#/v5/api/utils/transactions/-%23-transactions--types"></a></div></div></h2>
|
|
<a name="/v5/api/utils/transactions/-%23-UnsignedTransaction"></a><a name="/v5/api/utils/transactions/-%23-transactions--transactions--types--UnsignedTransaction"></a><a name="/v5/api/utils/transactions/"></a><h3 class="show-anchors"><div>UnsignedTransaction<div class="anchors"><a class="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>
|
|
|
|
<div class="property show-anchors"><div class="signature"><span class="path">unsignedTransaction</span><span class="symbol">.</span><span class="method">to</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/address/-%23-address">Address</a> ></span><div class="anchors"></div></div><div class="body"><p>The address this transaction is to.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">unsignedTransaction</span><span class="symbol">.</span><span class="method">nonce</span> <span class="arrow">⇒</span> <span class="returns">number</span><div class="anchors"></div></div><div class="body"><p>The nonce of this transaction.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">unsignedTransaction</span><span class="symbol">.</span><span class="method">gasLimit</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/bignumber/-%23-BigNumberish">BigNumberish</a></span><div class="anchors"></div></div><div class="body"><p>The gas limit for this transaction.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">unsignedTransaction</span><span class="symbol">.</span><span class="method">gasPrice</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/bignumber/-%23-BigNumberish">BigNumberish</a></span><div class="anchors"></div></div><div class="body"><p>The gas price for this transaction.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">unsignedTransaction</span><span class="symbol">.</span><span class="method">data</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/bytes/-%23-BytesLike">BytesLike</a></span><div class="anchors"></div></div><div class="body"><p>The data for this transaction.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">unsignedTransaction</span><span class="symbol">.</span><span class="method">value</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/bignumber/-%23-BigNumberish">BigNumberish</a></span><div class="anchors"></div></div><div class="body"><p>The value (in wei) for this transaction.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">unsignedTransaction</span><span class="symbol">.</span><span class="method">chainId</span> <span class="arrow">⇒</span> <span class="returns">number</span><div class="anchors"></div></div><div class="body"><p>The chain ID for this transaction. If the chain ID is 0 or null, then <a href="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><a name="/v5/api/utils/transactions/-%23-Transaction"></a><a name="/v5/api/utils/transactions/-%23-transactions--transactions--types--Transaction"></a><a name="/v5/api/utils/transactions/"></a><h3 class="show-anchors"><div>Transaction<div class="anchors"><a class="self" href="#/v5/api/utils/transactions/-%23-Transaction"></a></div></div></h3><p>A generic object to represent a transaction.</p>
|
|
|
|
<div class="property show-anchors"><div class="signature"><span class="path">transaction</span><span class="symbol">.</span><span class="method">hash</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 > ></span><div class="anchors"></div></div><div class="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><div class="property show-anchors"><div class="signature"><span class="path">unsignedTransaction</span><span class="symbol">.</span><span class="method">to</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/address/-%23-address">Address</a> ></span><div class="anchors"></div></div><div class="body"><p>The address <i>transaction</i> is to.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">transaction</span><span class="symbol">.</span><span class="method">from</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/address/-%23-address">Address</a> ></span><div class="anchors"></div></div><div class="body"><p>The address <i>transaction</i> is from.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">transaction</span><span class="symbol">.</span><span class="method">nonce</span> <span class="arrow">⇒</span> <span class="returns">number</span><div class="anchors"></div></div><div class="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><div class="property show-anchors"><div class="signature"><span class="path">transaction</span><span class="symbol">.</span><span class="method">gasLimit</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/bignumber/">BigNumber</a></span><div class="anchors"></div></div><div class="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 transaction are reverted, but the gas is <b>fully consumed</b> and an out-of-gas error occurs.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">transaction</span><span class="symbol">.</span><span class="method">gasPrice</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/bignumber/">BigNumber</a></span><div class="anchors"></div></div><div class="body"><p>The price (in wei) per unit of gas for <i>transaction</i>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">transaction</span><span class="symbol">.</span><span class="method">data</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/bytes/-%23-BytesLike">BytesLike</a></span><div class="anchors"></div></div><div class="body"><p>The data for <i>transaction</i>. In a contract this is the call data.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">transaction</span><span class="symbol">.</span><span class="method">value</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/bignumber/">BigNumber</a></span><div class="anchors"></div></div><div class="body"><p>The value (in wei) for <i>transaction</i>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">transaction</span><span class="symbol">.</span><span class="method">chainId</span> <span class="arrow">⇒</span> <span class="returns">number</span><div class="anchors"></div></div><div class="body"><p>The chain ID for <i>transaction</i>. This is used as part of <a href="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><div class="property show-anchors"><div class="signature"><span class="path">transaction</span><span class="symbol">.</span><span class="method">r</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 > ></span><div class="anchors"></div></div><div class="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><div class="property show-anchors"><div class="signature"><span class="path">transaction</span><span class="symbol">.</span><span class="method">s</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 > ></span><div class="anchors"></div></div><div class="body"><p>The s portion of the elliptic curve signatures for <i>transaction</i>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">transaction</span><span class="symbol">.</span><span class="method">v</span> <span class="arrow">⇒</span> <span class="returns">number</span><div class="anchors"></div></div><div class="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 <a href="https://eips.ethereum.org/EIPS/eip-155">EIP-155</a> is additionally used to encode the chain ID into the serialized transaction.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/transactions/-%23-transactions--functions"></a><a name="/v5/api/utils/transactions/-%23-transactions--transactions--functions"></a><a name="/v5/api/utils/transactions/"></a><h2 class="show-anchors"><div>Functions<div class="anchors"><a class="self" href="#/v5/api/utils/transactions/-%23-transactions--functions"></a></div></div></h2>
|
|
<a name="/v5/api/utils/transactions/-%23-utils-parseTransaction"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">parseTransaction</span><span class="symbol">(</span> <span class="param">aBytesLike</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/transactions/-%23-Transaction">Transaction</a></span><div class="anchors"><a class="self" href="#/v5/api/utils/transactions/-%23-utils-parseTransaction"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/transactions/src.ts/index.ts#L165">source</a></div></div><div class="body"><p>Parses the transaction properties from a serialized transaction.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/transactions/-%23-utils-serializeTransaction"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">serializeTransaction</span><span class="symbol">(</span> <span class="param">tx</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">signature</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a> ></span><div class="anchors"><a class="self" href="#/v5/api/utils/transactions/-%23-utils-serializeTransaction"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/transactions/src.ts/index.ts#L85">source</a></div></div><div class="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 <a href="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 <a href="https://eips.ethereum.org/EIPS/eip-155">EIP-155</a> <code class="inline">v</code> or <code class="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>
|
|
|
|
</div></div><div class="page-separator"></div><a name="/v5/api/utils/web/-%23-web"></a><a name="/v5/api/utils/web/-%23-web"></a><a name="/v5/api/utils/web/"></a><h1 class="show-anchors"><div>Web Utilities<div class="anchors"><a class="self" href="#/v5/api/utils/web/-%23-web"></a></div></div></h1>
|
|
<a name="/v5/api/utils/web/-%23-utils-fetchJson"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">fetchJson</span><span class="symbol">(</span> <span class="param">urlOrConnectionInfo</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">json</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">processFunc</span> <span class="symbol">]</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< any ></span><div class="anchors"><a class="self" href="#/v5/api/utils/web/-%23-utils-fetchJson"></a></div></div><div class="body"><p>Fetch and parse the JSON content from <i>urlOrConnectionInfo</i>, with the optional body <i>json</i> and optionally processing the result with <i>processFun</i> before returning it.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/web/-%23-utils-poll"></a><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">utils</span><span class="symbol">.</span><span class="method">poll</span><span class="symbol">(</span> <span class="param">pollFunc</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">options</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< any ></span><div class="anchors"><a class="self" href="#/v5/api/utils/web/-%23-utils-poll"></a></div></div><div class="body"><p>Repeatedly call pollFunc using the <a href="#/v5/api/utils/web/-%23-PollOptions">PollOptions</a> until it returns a value other than undefined.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/web/-%23-ConnectionInfo"></a><a name="/v5/api/utils/web/-%23-web--ConnectionInfo"></a><a name="/v5/api/utils/web/"></a><h3 class="show-anchors"><div>ConnectionInfo<div class="anchors"><a class="self" href="#/v5/api/utils/web/-%23-ConnectionInfo"></a></div></div></h3>
|
|
<div class="property show-anchors"><div class="signature"><span class="path">connection</span><span class="symbol">.</span><span class="method">url</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"></div></div><div class="body"><p>The URL to connect to.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">connection</span><span class="symbol">.</span><span class="method">user</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"></div></div><div class="body"><p>The username to use for <a href="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><div class="property show-anchors"><div class="signature"><span class="path">connection</span><span class="symbol">.</span><span class="method">password</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"></div></div><div class="body"><p>The password to use for <a href="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><div class="property show-anchors"><div class="signature"><span class="path">connection</span><span class="symbol">.</span><span class="method">allowInsecureAuthentication</span> <span class="arrow">⇒</span> <span class="returns">boolean</span><div class="anchors"></div></div><div class="body"><p>Allow <a href="https://en.wikipedia.org/wiki/Basic_access_authentication">Basic Authentication</a> over non-secure HTTP. The default is false.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">connection</span><span class="symbol">.</span><span class="method">timeout</span> <span class="arrow">⇒</span> <span class="returns">number</span><div class="anchors"></div></div><div class="body"><p>How long to wait before rejecting with a <i>timeout</i> error.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">connection</span><span class="symbol">.</span><span class="method">headers</span> <span class="arrow">⇒</span> <span class="returns">{[key:string]:string}</span><div class="anchors"></div></div><div class="body"><p>Additional headers to include in the connection.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/web/-%23-PollOptions"></a><a name="/v5/api/utils/web/-%23-web--PollOptions"></a><a name="/v5/api/utils/web/"></a><h3 class="show-anchors"><div>PollOptions<div class="anchors"><a class="self" href="#/v5/api/utils/web/-%23-PollOptions"></a></div></div></h3>
|
|
<div class="property show-anchors"><div class="signature"><span class="path">options</span><span class="symbol">.</span><span class="method">timeout</span> <span class="arrow">⇒</span> <span class="returns">number</span><div class="anchors"></div></div><div class="body"><p>The amount of time allowed to elapse before triggering a timeout error.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">options</span><span class="symbol">.</span><span class="method">floor</span> <span class="arrow">⇒</span> <span class="returns">number</span><div class="anchors"></div></div><div class="body"><p>The minimum time limit to allow for <a href="https://en.wikipedia.org/wiki/Exponential_backoff">Exponential Backoff</a>.</p>
|
|
|
|
<p>The default is 0s.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">options</span><span class="symbol">.</span><span class="method">ceiling</span> <span class="arrow">⇒</span> <span class="returns">number</span><div class="anchors"></div></div><div class="body"><p>The maximum time limit to allow for <a href="https://en.wikipedia.org/wiki/Exponential_backoff">Exponential Backoff</a>.</p>
|
|
|
|
<p>The default is 10s.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">options</span><span class="symbol">.</span><span class="method">interval</span> <span class="arrow">⇒</span> <span class="returns">number</span><div class="anchors"></div></div><div class="body"><p>The interval used during <a href="https://en.wikipedia.org/wiki/Exponential_backoff">Exponential Backoff</a> calculation.</p>
|
|
|
|
<p>The default is 250ms.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">options</span><span class="symbol">.</span><span class="method">retryLimit</span> <span class="arrow">⇒</span> <span class="returns">number</span><div class="anchors"></div></div><div class="body"><p>The number of times to retry in the event of an error or <i>undefined</i> is returned.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">options</span><span class="symbol">.</span><span class="method">onceBlock</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/providers/provider/">Provider</a></span><div class="anchors"></div></div><div class="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><div class="property show-anchors"><div class="signature"><span class="path">options</span><span class="symbol">.</span><span class="method">oncePoll</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/providers/provider/">Provider</a></span><div class="anchors"></div></div><div class="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>
|
|
|
|
</div></div><div class="page-separator"></div><a name="/v5/api/utils/wordlists/-%23-wordlists"></a><a name="/v5/api/utils/wordlists/-%23-wordlists"></a><a name="/v5/api/utils/wordlists/"></a><h1 class="show-anchors"><div>Wordlists<div class="anchors"><a class="self" href="#/v5/api/utils/wordlists/-%23-wordlists"></a></div></div></h1>
|
|
<a name="/v5/api/utils/wordlists/-%23-Wordlist"></a><a name="/v5/api/utils/wordlists/-%23-wordlists--Wordlist"></a><a name="/v5/api/utils/wordlists/"></a><h2 class="show-anchors"><div>Wordlist<div class="anchors"><a class="self" href="#/v5/api/utils/wordlists/-%23-Wordlist"></a></div></div></h2>
|
|
<div class="property show-anchors"><div class="signature"><span class="path">wordlist</span><span class="symbol">.</span><span class="method">locale</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"></div></div><div class="body"><p>The locale for this wordlist.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">wordlist</span><span class="symbol">.</span><span class="method">getWord</span><span class="symbol">(</span> <span class="param">index</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"></div></div><div class="body"><p>Returns the word at <i>index</i>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">wordlist</span><span class="symbol">.</span><span class="method">getWordIndex</span><span class="symbol">(</span> <span class="param">word</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">number</span><div class="anchors"></div></div><div class="body"><p>Returns the index of <i>word</i> within the wordlist.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">wordlist</span><span class="symbol">.</span><span class="method">split</span><span class="symbol">(</span> <span class="param">mnemonic</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Array< string ></span><div class="anchors"></div></div><div class="body"><p>Returns the mnemonic split into each individual word, according to a locale's valid whitespace character set.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">wordlist</span><span class="symbol">.</span><span class="method">join</span><span class="symbol">(</span> <span class="param">words</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"></div></div><div class="body"><p>Returns the mnemonic by joining <i>words</i> together using the whitespace that is standard for the locale.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">Wordlist</span><span class="symbol">.</span><span class="method">check</span><span class="symbol">(</span> <span class="param">wordlists</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a>< 32 > ></span><div class="anchors"></div></div><div class="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><div class="property show-anchors"><div class="signature"><span class="path">Wordlist</span><span class="symbol">.</span><span class="method">register</span><span class="symbol">(</span> <span class="param">wordlist</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">name</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">void</span><div class="anchors"></div></div><div class="body"><p>Register a wordlist with the list of wordlists, optionally overriding the registered <i>name</i>.</p>
|
|
|
|
</div></div><a name="/v5/api/utils/wordlists/-%23-wordlists--languages"></a><a name="/v5/api/utils/wordlists/-%23-wordlists--wordlists--languages"></a><a name="/v5/api/utils/wordlists/"></a><h2 class="show-anchors"><div>Languages<div class="anchors"><a class="self" href="#/v5/api/utils/wordlists/-%23-wordlists--languages"></a></div></div></h2><p>The <a href="https://github.com/bitcoin/bips/blob/master/bip-0039/bip-0039-wordlists.md">official wordlists</a> available at `ethers.wordlists`. In the browser, only the english language 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 class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">wordlists</span><span class="symbol">.</span><span class="method">cz</span> <span class="arrow">⇒</span> <span class="returns">Wordlist</span><div class="anchors"></div></div><div class="body"><p>The Czech <a href="#/v5/api/utils/wordlists/-%23-Wordlist">Wordlist</a>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">wordlists</span><span class="symbol">.</span><span class="method">en</span> <span class="arrow">⇒</span> <span class="returns">Wordlist</span><div class="anchors"></div></div><div class="body"><p>The English <a href="#/v5/api/utils/wordlists/-%23-Wordlist">Wordlist</a>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">wordlists</span><span class="symbol">.</span><span class="method">es</span> <span class="arrow">⇒</span> <span class="returns">Wordlist</span><div class="anchors"></div></div><div class="body"><p>The Spanish <a href="#/v5/api/utils/wordlists/-%23-Wordlist">Wordlist</a>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">wordlists</span><span class="symbol">.</span><span class="method">fr</span> <span class="arrow">⇒</span> <span class="returns">Wordlist</span><div class="anchors"></div></div><div class="body"><p>The French <a href="#/v5/api/utils/wordlists/-%23-Wordlist">Wordlist</a>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">wordlists</span><span class="symbol">.</span><span class="method">it</span> <span class="arrow">⇒</span> <span class="returns">Wordlist</span><div class="anchors"></div></div><div class="body"><p>The Italian <a href="#/v5/api/utils/wordlists/-%23-Wordlist">Wordlist</a>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">wordlists</span><span class="symbol">.</span><span class="method">ja</span> <span class="arrow">⇒</span> <span class="returns">Wordlist</span><div class="anchors"></div></div><div class="body"><p>The Japanese <a href="#/v5/api/utils/wordlists/-%23-Wordlist">Wordlist</a>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">wordlists</span><span class="symbol">.</span><span class="method">ko</span> <span class="arrow">⇒</span> <span class="returns">Wordlist</span><div class="anchors"></div></div><div class="body"><p>The Korean <a href="#/v5/api/utils/wordlists/-%23-Wordlist">Wordlist</a>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">wordlists</span><span class="symbol">.</span><span class="method">zh_cn</span> <span class="arrow">⇒</span> <span class="returns">Wordlist</span><div class="anchors"></div></div><div class="body"><p>The Simplified Chinese <a href="#/v5/api/utils/wordlists/-%23-Wordlist">Wordlist</a>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">ethers</span><span class="symbol">.</span><span class="path">wordlists</span><span class="symbol">.</span><span class="method">zh_tw</span> <span class="arrow">⇒</span> <span class="returns">Wordlist</span><div class="anchors"></div></div><div class="body"><p>The Traditional Chinese <a href="#/v5/api/utils/wordlists/-%23-Wordlist">Wordlist</a>.</p>
|
|
|
|
</div></div><div class="page-separator"></div><a name="/v5/api/other/-%23-other-libraries"></a><a name="/v5/api/other/"></a><h1 class="show-anchors"><div>Other Libraries<div class="anchors"><a class="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>
|
|
|
|
<div class="toc"><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/api/other/assembly/">Assembly</a></div><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/api/other/hardware/">Hardware Wallets</a></div></div><div class="page-separator"></div><a name="/v5/api/other/assembly/-%23-assembly"></a><a name="/v5/api/other/assembly/"></a><h1 class="show-anchors"><div>Assembly<div class="anchors"><a class="self" href="#/v5/api/other/assembly/-%23-assembly"></a></div></div></h1><p>This module should still be considered fairly experimental.</p>
|
|
|
|
<div class="toc"><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/api/other/assembly/dialect/">Ethers ASM Dialect</a></div><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/api/other/assembly/api/">Utilities</a></div><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/api/other/assembly/ast/">Abstract Syntax Tree</a></div></div><div class="page-separator"></div><a name="/v5/api/other/assembly/dialect/-%23-asm-dialect"></a><a name="/v5/api/other/assembly/dialect/-%23-asm-dialect"></a><a name="/v5/api/other/assembly/dialect/"></a><h1 class="show-anchors"><div>Ethers ASM Dialect<div class="anchors"><a class="self" href="#/v5/api/other/assembly/dialect/-%23-asm-dialect"></a></div></div></h1><p>This provides a quick, high-level overview of the <b>Ethers ASM Dialect</b> for EVM, which is defined by the <a href="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 language 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 <a href="#/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>
|
|
|
|
<a name="/v5/api/other/assembly/dialect/-%23-asm-dialect-opcode"></a><a name="/v5/api/other/assembly/dialect/-%23-asm-dialect--asm-dialect-opcode"></a><a name="/v5/api/other/assembly/dialect/"></a><h2 class="show-anchors"><div>Opcodes<div class="anchors"><a class="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>
|
|
|
|
<a name="/v5/api/other/assembly/dialect/-%23-asm-dialect-label"></a><a name="/v5/api/other/assembly/dialect/-%23-asm-dialect--asm-dialect-label"></a><a name="/v5/api/other/assembly/dialect/"></a><h2 class="show-anchors"><div>Labels<div class="anchors"><a class="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 <code class="inline">JUMPDEST</code> is automatically added to this point in the assembled output.</p>
|
|
|
|
<p>@TODO: Examples</p>
|
|
|
|
<a name="/v5/api/other/assembly/dialect/-%23-asm-dialect-literal"></a><a name="/v5/api/other/assembly/dialect/-%23-asm-dialect--asm-dialect-literal"></a><a name="/v5/api/other/assembly/dialect/"></a><h2 class="show-anchors"><div>Literals<div class="anchors"><a class="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 <code class="inline">PUSH</code> operation.</p>
|
|
|
|
<p>A <b>Literal</b> can be provided using a <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a> or a decimal byte value.</p>
|
|
|
|
<p>@TODO: examples</p>
|
|
|
|
<a name="/v5/api/other/assembly/dialect/-%23-asm-dialect-comment"></a><a name="/v5/api/other/assembly/dialect/-%23-asm-dialect--asm-dialect-comment"></a><a name="/v5/api/other/assembly/dialect/"></a><h2 class="show-anchors"><div>Comments<div class="anchors"><a class="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. <code class="inline">;</code>) is ignored by the assembler.</p>
|
|
|
|
<a name="/v5/api/other/assembly/dialect/-%23-asm-dialect-scope"></a><a name="/v5/api/other/assembly/dialect/-%23-asm-dialect--asm-dialect-scope"></a><a name="/v5/api/other/assembly/dialect/"></a><h2 class="show-anchors"><div>Scopes<div class="anchors"><a class="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 <code class="inline">to</code> address and contains bytecode in the <code class="inline">data</code>. This <code class="inline">data</code> bytecode is a program, that when executed returns some other bytecode as a result, this result 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 <a href="#/v5/api/other/assembly/dialect/-%23-asm-dialect-datasegment">Data Segment</a> or child <a href="#/v5/api/other/assembly/dialect/-%23-asm-dialect-scope">Scopes</a> (with respect to itself) and may access the length of any <a href="#/v5/api/other/assembly/dialect/-%23-asm-dialect-datasegment">Data Segment</a> or <a href="#/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-level scope named <code class="inline">_</code>.</p>
|
|
|
|
<a name="/v5/api/other/assembly/dialect/-%23-asm-dialect-datasegment"></a><a name="/v5/api/other/assembly/dialect/-%23-asm-dialect--asm-dialect-datasegment"></a><a name="/v5/api/other/assembly/dialect/"></a><h2 class="show-anchors"><div>Data Segment<div class="anchors"><a class="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 empty <b>Data Segment</b> can also be used when a labelled location is required, but without the <code class="inline">JUMPDEST</code> which a <a href="#/v5/api/other/assembly/dialect/-%23-asm-dialect-label">Labels</a> adds.</p>
|
|
|
|
<p>@TODO: Example</p>
|
|
|
|
<a name="/v5/api/other/assembly/dialect/-%23-asm-dialect-links"></a><a name="/v5/api/other/assembly/dialect/-%23-asm-dialect--asm-dialect-links"></a><a name="/v5/api/other/assembly/dialect/"></a><h2 class="show-anchors"><div>Links<div class="anchors"><a class="self" href="#/v5/api/other/assembly/dialect/-%23-asm-dialect-links"></a></div></div></h2><p>A <b>Link</b> allows access to a <a href="#/v5/api/other/assembly/dialect/-%23-asm-dialect-scope">Scopes</a>, <a href="#/v5/api/other/assembly/dialect/-%23-asm-dialect-datasegment">Data Segment</a> or <a href="#/v5/api/other/assembly/dialect/-%23-asm-dialect-label">Labels</a>.</p>
|
|
|
|
<p>To access the byte offset of a labelled item, use <code class="inline">$foobar</code>.</p>
|
|
|
|
<p>For a <a href="#/v5/api/other/assembly/dialect/-%23-asm-dialect-label">Labels</a>, the target must be directly reachable within this scope. For a <a href="#/v5/api/other/assembly/dialect/-%23-asm-dialect-datasegment">Data Segment</a> or a <a href="#/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 <a href="#/v5/api/other/assembly/dialect/-%23-asm-dialect-datasegment">Data Segment</a> or a <a href="#/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 <code class="inline">#foobar</code> and is pushed on the stack as a literal.</p>
|
|
|
|
<a name="/v5/api/other/assembly/dialect/-%23-asm-dialect-placeholder"></a><a name="/v5/api/other/assembly/dialect/-%23-asm-dialect--asm-dialect-placeholder"></a><a name="/v5/api/other/assembly/dialect/"></a><h2 class="show-anchors"><div>Stack Placeholders<div class="anchors"><a class="self" href="#/v5/api/other/assembly/dialect/-%23-asm-dialect-placeholder"></a></div></div></h2><p>@TODO: exampl</p>
|
|
|
|
<a name="/v5/api/other/assembly/dialect/-%23-asm-dialect-scripting"></a><a name="/v5/api/other/assembly/dialect/-%23-asm-dialect--asm-dialect-scripting"></a><a name="/v5/api/other/assembly/dialect/"></a><h2 class="show-anchors"><div>Evaluation and Execution<div class="anchors"><a class="self" href="#/v5/api/other/assembly/dialect/-%23-asm-dialect-scripting"></a></div></div></h2>
|
|
<div class="page-separator"></div><a name="/v5/api/other/assembly/api/-%23-asm-utilities"></a><a name="/v5/api/other/assembly/api/-%23-asm-utilities"></a><a name="/v5/api/other/assembly/api/"></a><h1 class="show-anchors"><div>Utilities<div class="anchors"><a class="self" href="#/v5/api/other/assembly/api/-%23-asm-utilities"></a></div></div></h1>
|
|
<a name="/v5/api/other/assembly/api/-%23-asm-utilities--assembler"></a><a name="/v5/api/other/assembly/api/"></a><h2 class="show-anchors"><div>Assembler<div class="anchors"><a class="self" href="#/v5/api/other/assembly/api/-%23-asm-utilities--assembler"></a></div></div></h2><p>The assembler utilities allow parsing and assembling an <a href="#/v5/api/other/assembly/dialect/">Ethers ASM Dialect</a> source file.</p>
|
|
|
|
<a name="/v5/api/other/assembly/api/-%23-asm-parse"></a><div class="property show-anchors"><div class="signature"><span class="path">asm</span><span class="symbol">.</span><span class="method">parse</span><span class="symbol">(</span> <span class="param">code</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/other/assembly/ast/-%23-asm-node">Node</a></span><div class="anchors"><a class="self" href="#/v5/api/other/assembly/api/-%23-asm-parse"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/asm/src.ts/assembler.ts#L1277">source</a></div></div><div class="body"><p>Parse an ethers-format assembly file and return the <a href="#/v5/api/other/assembly/ast/">Abstract Syntax Tree</a>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">asm</span><span class="symbol">.</span><span class="method">assemble</span><span class="symbol">(</span> <span class="param">node</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a> ></span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/asm/src.ts/assembler.ts#L1348">source</a></div></div><div class="body"><p>Performs assembly of the <a href="#/v5/api/other/assembly/ast/">Abstract Syntax Tree</a> <i>node</i> and return the resulting bytecode representation.</p>
|
|
|
|
</div></div><a name="/v5/api/other/assembly/api/-%23-asm-utilities--disassembler"></a><a name="/v5/api/other/assembly/api/"></a><h2 class="show-anchors"><div>Disassembler<div class="anchors"><a class="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>
|
|
|
|
<div class="property show-anchors"><div class="signature"><span class="path">asm</span><span class="symbol">.</span><span class="method">disassemble</span><span class="symbol">(</span> <span class="param">bytecode</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/other/assembly/api/-%23-asm-bytecode">Bytecode</a></span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/asm/src.ts/assembler.ts#L606">source</a></div></div><div class="body"><p>Returns an array of Operations given <i>bytecode</i>.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">asm</span><span class="symbol">.</span><span class="method">formatBytecode</span><span class="symbol">(</span> <span class="param">operations</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/asm/src.ts/assembler.ts#L677">source</a></div></div><div class="body"><p>Create a formatted output of an array of <a href="#/v5/api/other/assembly/api/-%23-asm-operation">Operation</a>.</p>
|
|
|
|
</div></div><a name="/v5/api/other/assembly/api/-%23-asm-bytecode"></a><a name="/v5/api/other/assembly/api/-%23-asm-utilities--disassembler--asm-bytecode"></a><a name="/v5/api/other/assembly/api/"></a><h3 class="show-anchors"><div>Bytecode<span class="inherits"> inherits Array<<a href="#/v5/api/other/assembly/api/-%23-asm-operation">Operation</a>></span><div class="anchors"><a class="self" href="#/v5/api/other/assembly/api/-%23-asm-bytecode"></a></div></div></h3><p>Each array index represents an operation, collapsing multi-byte operations (i.e. <code class="inline">PUSH</code>) into a single operation.</p>
|
|
|
|
<div class="property show-anchors"><div class="signature"><span class="path">bytecode</span><span class="symbol">.</span><span class="method">getOperation</span><span class="symbol">(</span> <span class="param">offset</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/other/assembly/api/-%23-asm-operation">Operation</a></span><div class="anchors"></div></div><div class="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 <code class="inline">PUSH</code>, in which case null it returned.</p>
|
|
|
|
</div></div><a name="/v5/api/other/assembly/api/-%23-asm-operation"></a><a name="/v5/api/other/assembly/api/-%23-asm-utilities--disassembler--asm-operation"></a><a name="/v5/api/other/assembly/api/"></a><h3 class="show-anchors"><div>Operation<div class="anchors"><a class="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>
|
|
|
|
<div class="property show-anchors"><div class="signature"><span class="path">operation</span><span class="symbol">.</span><span class="method">opcode</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/other/assembly/api/-%23-asm-opcode">Opcode</a></span><div class="anchors"></div></div><div class="body"><p>The opcode for this Operation.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">operation</span><span class="symbol">.</span><span class="method">offset</span> <span class="arrow">⇒</span> <span class="returns">number</span><div class="anchors"></div></div><div class="body"><p>The offset into the bytecode for this Operation.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">operation</span><span class="symbol">.</span><span class="method">pushValue</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a> ></span><div class="anchors"></div></div><div class="body"><p>If the opcode is a <code class="inline">PUSH</code>, this is the value of that push</p>
|
|
|
|
</div></div><a name="/v5/api/other/assembly/api/-%23-asm-opcode"></a><a name="/v5/api/other/assembly/api/-%23-asm-utilities--asm-opcode"></a><a name="/v5/api/other/assembly/api/"></a><h2 class="show-anchors"><div>Opcode<div class="anchors"><a class="self" href="#/v5/api/other/assembly/api/-%23-asm-opcode"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/asm/src.ts/opcodes.ts#L21">source</a></div></div></h2>
|
|
<div class="property show-anchors"><div class="signature"><span class="path">asm</span><span class="symbol">.</span><span class="path">Opcode</span><span class="symbol">.</span><span class="method">from</span><span class="symbol">(</span> <span class="param">valueOrMnemonic</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/other/assembly/api/-%23-asm-opcode">Opcode</a></span><div class="anchors"></div></div><div class="body"><p>Create a new instance of an Opcode for a given numeric value (e.g. 0x60 is PUSH1) or mnemonic string (e.g. "PUSH1").</p>
|
|
|
|
</div></div><a name="/v5/api/other/assembly/api/-%23-asm-utilities--asm-opcode--properties"></a><a name="/v5/api/other/assembly/api/"></a><h3 class="show-anchors"><div>Properties<div class="anchors"><a class="self" href="#/v5/api/other/assembly/api/-%23-asm-utilities--asm-opcode--properties"></a></div></div></h3>
|
|
<div class="property show-anchors"><div class="signature"><span class="path">opcode</span><span class="symbol">.</span><span class="method">value</span> <span class="arrow">⇒</span> <span class="returns">number</span><div class="anchors"></div></div><div class="body"><p>The value (bytecode as a number) of this opcode.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">opcode</span><span class="symbol">.</span><span class="method">mnemonic</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"></div></div><div class="body"><p>The mnemonic string of this opcode.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">opcode</span><span class="symbol">.</span><span class="method">delta</span> <span class="arrow">⇒</span> <span class="returns">number</span><div class="anchors"></div></div><div class="body"><p>The number of items this opcode will consume from the stack.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">opcode</span><span class="symbol">.</span><span class="method">alpha</span> <span class="arrow">⇒</span> <span class="returns">number</span><div class="anchors"></div></div><div class="body"><p>The number of items this opcode will push onto the stack.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">opcode</span><span class="symbol">.</span><span class="method">doc</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"></div></div><div class="body"><p>A short description of what this opcode does.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">opcode</span><span class="symbol">.</span><span class="method">isMemory</span><span class="symbol">(</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">"read" | "write" | "full"</span><div class="anchors"></div></div><div class="body"><p>Returns true if the opcode accesses memory.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">opcode</span><span class="symbol">.</span><span class="method">isStatic</span><span class="symbol">(</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">boolean</span><div class="anchors"></div></div><div class="body"><p>Returns true if the opcode cannot change state.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">opcode</span><span class="symbol">.</span><span class="method">isJump</span><span class="symbol">(</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">boolean</span><div class="anchors"></div></div><div class="body"><p>Returns true if the opcode is a jumper operation.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">opcode</span><span class="symbol">.</span><span class="method">isPush</span><span class="symbol">(</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">number</span><div class="anchors"></div></div><div class="body"><p>Returns 0 if the opcode is not a <code class="inline">PUSH*</code>, or the number of bytes this opcode will push if it is.</p>
|
|
|
|
</div></div><div class="page-separator"></div><a name="/v5/api/other/assembly/ast/-%23-asm-ast"></a><a name="/v5/api/other/assembly/ast/-%23-asm-ast"></a><a name="/v5/api/other/assembly/ast/"></a><h1 class="show-anchors"><div>Abstract Syntax Tree<div class="anchors"><a class="self" href="#/v5/api/other/assembly/ast/-%23-asm-ast"></a></div></div></h1><p>Parsing a file using the <a href="#/v5/api/other/assembly/dialect/">Ethers ASM Dialect</a> will generate an Abstract Syntax Tree. The root node will always be a <a href="#/v5/api/other/assembly/ast/-%23-asm-scopenode">ScopeNode</a> whose name is <code class="inline">_</code>.</p>
|
|
|
|
<p>To parse a file into an Abstract Syntax tree, use the <a href="#/v5/api/other/assembly/api/-%23-asm-parse">parse</a> function.</p>
|
|
|
|
<a name="/v5/api/other/assembly/ast/-%23-asm-ast--types"></a><a name="/v5/api/other/assembly/ast/"></a><h2 class="show-anchors"><div>Types<div class="anchors"><a class="self" href="#/v5/api/other/assembly/ast/-%23-asm-ast--types"></a></div></div></h2>
|
|
<a name="/v5/api/other/assembly/ast/-%23-asm-location"></a><a name="/v5/api/other/assembly/ast/-%23-asm-ast--types--asm-location"></a><a name="/v5/api/other/assembly/ast/"></a><h3 class="show-anchors"><div>Location<div class="anchors"><a class="self" href="#/v5/api/other/assembly/ast/-%23-asm-location"></a></div></div></h3>
|
|
<div class="property show-anchors"><div class="signature"><span class="method">offset</span> <span class="arrow">⇒</span> <span class="returns">number</span><div class="anchors"></div></div><div class="body"><p>The offset into the source code to the start of this node.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="method">length</span> <span class="arrow">⇒</span> <span class="returns">number</span><div class="anchors"></div></div><div class="body"><p>The length of characters in the source code to the end of this node.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="method">source</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"></div></div><div class="body"><p>The source code of this node.</p>
|
|
|
|
</div></div><a name="/v5/api/other/assembly/ast/-%23-asm-ast--nodes"></a><a name="/v5/api/other/assembly/ast/"></a><h2 class="show-anchors"><div>Nodes<div class="anchors"><a class="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>
|
|
|
|
<a name="/v5/api/other/assembly/ast/-%23-asm-node"></a><a name="/v5/api/other/assembly/ast/-%23-asm-ast--nodes--asm-node"></a><a name="/v5/api/other/assembly/ast/"></a><h3 class="show-anchors"><div>Node<div class="anchors"><a class="self" href="#/v5/api/other/assembly/ast/-%23-asm-node"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/asm/src.ts/assembler.ts#L156">source</a></div></div></h3>
|
|
<div class="property show-anchors"><div class="signature"><span class="path">node</span><span class="symbol">.</span><span class="method">tag</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"></div></div><div class="body"><p>A unique tag for this node for the lifetime of the process.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">node</span><span class="symbol">.</span><span class="method">location</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/other/assembly/ast/-%23-asm-location">Location</a></span><div class="anchors"></div></div><div class="body"><p>The source code and location within the source code that this node represents.</p>
|
|
|
|
</div></div><a name="/v5/api/other/assembly/ast/-%23-asm-valuenode"></a><a name="/v5/api/other/assembly/ast/-%23-asm-ast--nodes--asm-valuenode"></a><a name="/v5/api/other/assembly/ast/"></a><h3 class="show-anchors"><div>ValueNode<span class="inherits"> inherits <a href="#/v5/api/other/assembly/ast/-%23-asm-node">Node</a></span><div class="anchors"><a class="self" href="#/v5/api/other/assembly/ast/-%23-asm-valuenode"></a><a class="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>
|
|
|
|
<a name="/v5/api/other/assembly/ast/-%23-asm-literalnode"></a><a name="/v5/api/other/assembly/ast/-%23-asm-ast--nodes--asm-literalnode"></a><a name="/v5/api/other/assembly/ast/"></a><h3 class="show-anchors"><div>LiteralNode<span class="inherits"> inherits <a href="#/v5/api/other/assembly/ast/-%23-asm-valuenode">ValueNode</a></span><div class="anchors"><a class="self" href="#/v5/api/other/assembly/ast/-%23-asm-literalnode"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/asm/src.ts/assembler.ts#L237">source</a></div></div></h3>
|
|
<div class="property show-anchors"><div class="signature"><span class="path">literalNode</span><span class="symbol">.</span><span class="method">value</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"></div></div><div class="body"><p>The literal value of this node, which may be a <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a> or string of a decimal number.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">literalNode</span><span class="symbol">.</span><span class="method">verbatim</span> <span class="arrow">⇒</span> <span class="returns">boolean</span><div class="anchors"></div></div><div class="body"><p>This is true in a <a href="#/v5/api/other/assembly/ast/-%23-asm-datanode">DataNode</a> context, since in that case the value should be taken verbatim and no <code class="inline">PUSH</code> operation should be added, otherwise false.</p>
|
|
|
|
</div></div><a name="/v5/api/other/assembly/ast/-%23-asm-popnode"></a><a name="/v5/api/other/assembly/ast/-%23-asm-ast--nodes--asm-popnode"></a><a name="/v5/api/other/assembly/ast/"></a><h3 class="show-anchors"><div>PopNode<span class="inherits"> inherits <a href="#/v5/api/other/assembly/ast/-%23-asm-valuenode">ValueNode</a></span><div class="anchors"><a class="self" href="#/v5/api/other/assembly/ast/-%23-asm-popnode"></a><a class="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. <code class="inline">$$</code>) or an explicit place-holder (e.g. <code class="inline">$1</code>), which indicates the expected stack position to consume.</p>
|
|
|
|
<div class="property show-anchors"><div class="signature"><span class="path">literalNode</span><span class="symbol">.</span><span class="method">index</span> <span class="arrow">⇒</span> <span class="returns">number</span><div class="anchors"></div></div><div class="body"><p>The index this <b>PopNode</b> is representing. For an implicit place-holder this is <code class="inline">0</code>.</p>
|
|
|
|
</div></div><a name="/v5/api/other/assembly/ast/-%23-asm-linknode"></a><a name="/v5/api/other/assembly/ast/-%23-asm-ast--nodes--asm-linknode"></a><a name="/v5/api/other/assembly/ast/"></a><h3 class="show-anchors"><div>LinkNode<span class="inherits"> inherits <a href="#/v5/api/other/assembly/ast/-%23-asm-valuenode">ValueNode</a></span><div class="anchors"><a class="self" href="#/v5/api/other/assembly/ast/-%23-asm-linknode"></a><a class="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 <a href="#/v5/api/other/assembly/ast/-%23-asm-node">Node</a>'s data, for example <code class="inline">$foo</code> or <code class="inline">#bar</code>.</p>
|
|
|
|
<div class="property show-anchors"><div class="signature"><span class="path">linkNode</span><span class="symbol">.</span><span class="method">label</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"></div></div><div class="body"><p>The name of the target node.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">linkNode</span><span class="symbol">.</span><span class="method">type</span> <span class="arrow">⇒</span> <span class="returns">"offset" | "length"</span><div class="anchors"></div></div><div class="body"><p>Whether this node is for an offset or a length value of the target node.</p>
|
|
|
|
</div></div><a name="/v5/api/other/assembly/ast/-%23-asm-opcodenode"></a><a name="/v5/api/other/assembly/ast/-%23-asm-ast--nodes--asm-opcodenode"></a><a name="/v5/api/other/assembly/ast/"></a><h3 class="show-anchors"><div>OpcodeNode<span class="inherits"> inherits <a href="#/v5/api/other/assembly/ast/-%23-asm-valuenode">ValueNode</a></span><div class="anchors"><a class="self" href="#/v5/api/other/assembly/ast/-%23-asm-opcodenode"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/asm/src.ts/assembler.ts#L367">source</a></div></div></h3>
|
|
<div class="property show-anchors"><div class="signature"><span class="path">opcodeNode</span><span class="symbol">.</span><span class="method">opcode</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/other/assembly/api/-%23-asm-opcode">Opcode</a></span><div class="anchors"></div></div><div class="body"><p>The opcode for this Node.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">opcodeNode</span><span class="symbol">.</span><span class="method">operands</span> <span class="arrow">⇒</span> <span class="returns">Array< <a href="#/v5/api/other/assembly/ast/-%23-asm-valuenode">ValueNode</a> ></span><div class="anchors"></div></div><div class="body"><p>A list of all operands passed into this Node.</p>
|
|
|
|
</div></div><a name="/v5/api/other/assembly/ast/-%23-asm-evaluationnode"></a><a name="/v5/api/other/assembly/ast/-%23-asm-ast--nodes--asm-evaluationnode"></a><a name="/v5/api/other/assembly/ast/"></a><h3 class="show-anchors"><div>EvaluationNode<span class="inherits"> inherits <a href="#/v5/api/other/assembly/ast/-%23-asm-valuenode">ValueNode</a></span><div class="anchors"><a class="self" href="#/v5/api/other/assembly/ast/-%23-asm-evaluationnode"></a><a class="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 <code class="inline">{{! code here }}</code> syntax.</p>
|
|
|
|
<div class="property show-anchors"><div class="signature"><span class="path">literalNode</span><span class="symbol">.</span><span class="method">verbatim</span> <span class="arrow">⇒</span> <span class="returns">boolean</span><div class="anchors"></div></div><div class="body"><p>This is true in a <a href="#/v5/api/other/assembly/ast/-%23-asm-datanode">DataNode</a> context, since in that case the value should be taken verbatim and no <code class="inline">PUSH</code> operation should be added, otherwise false.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">evaluationNode</span><span class="symbol">.</span><span class="method">script</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"></div></div><div class="body"><p>The code to evaluate and produce the result to use as a literal.</p>
|
|
|
|
</div></div><a name="/v5/api/other/assembly/ast/-%23-asm-executionnode"></a><a name="/v5/api/other/assembly/ast/-%23-asm-ast--nodes--asm-executionnode"></a><a name="/v5/api/other/assembly/ast/"></a><h3 class="show-anchors"><div>ExecutionNode<span class="inherits"> inherits <a href="#/v5/api/other/assembly/ast/-%23-asm-node">Node</a></span><div class="anchors"><a class="self" href="#/v5/api/other/assembly/ast/-%23-asm-executionnode"></a><a class="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 <code class="inline">{{! code here }}</code> syntax.</p>
|
|
|
|
<div class="property show-anchors"><div class="signature"><span class="path">evaluationNode</span><span class="symbol">.</span><span class="method">script</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"></div></div><div class="body"><p>The code to execute. Any result is ignored.</p>
|
|
|
|
</div></div><a name="/v5/api/other/assembly/ast/-%23-asm-labellednode"></a><a name="/v5/api/other/assembly/ast/-%23-asm-ast--nodes--asm-labellednode"></a><a name="/v5/api/other/assembly/ast/"></a><h3 class="show-anchors"><div>LabelledNode<span class="inherits"> inherits <a href="#/v5/api/other/assembly/ast/-%23-asm-node">Node</a></span><div class="anchors"><a class="self" href="#/v5/api/other/assembly/ast/-%23-asm-labellednode"></a><a class="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 targeted by a <a href="#/v5/api/other/assembly/ast/-%23-asm-linknode">LinkNode</a>.</p>
|
|
|
|
<div class="property show-anchors"><div class="signature"><span class="path">labelledNode</span><span class="symbol">.</span><span class="method">name</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"></div></div><div class="body"><p>The name of this node.</p>
|
|
|
|
</div></div><a name="/v5/api/other/assembly/ast/-%23-asm-labelnode"></a><a name="/v5/api/other/assembly/ast/-%23-asm-ast--nodes--asm-labelnode"></a><a name="/v5/api/other/assembly/ast/"></a><h3 class="show-anchors"><div>LabelNode<span class="inherits"> inherits <a href="#/v5/api/other/assembly/ast/-%23-asm-labellednode">LabelledNode</a></span><div class="anchors"><a class="self" href="#/v5/api/other/assembly/ast/-%23-asm-labelnode"></a><a class="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 <code class="inline">JUMP</code> to by referencing it name, using <code class="inline">@myLabel:</code>. A <code class="inline">JUMPDEST</code> is automatically inserted at the bytecode offset.</p>
|
|
|
|
<a name="/v5/api/other/assembly/ast/-%23-asm-datanode"></a><a name="/v5/api/other/assembly/ast/-%23-asm-ast--nodes--asm-datanode"></a><a name="/v5/api/other/assembly/ast/"></a><h3 class="show-anchors"><div>DataNode<span class="inherits"> inherits <a href="#/v5/api/other/assembly/ast/-%23-asm-labellednode">LabelledNode</a></span><div class="anchors"><a class="self" href="#/v5/api/other/assembly/ast/-%23-asm-datanode"></a><a class="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 <code class="inline">@myData[ ... ]</code>. The data is padded if needed to ensure values that would otherwise be regarded as a <code class="inline">PUSH</code> value does not impact anything past the data.</p>
|
|
|
|
<div class="property show-anchors"><div class="signature"><span class="path">dataNode</span><span class="symbol">.</span><span class="method">data</span> <span class="arrow">⇒</span> <span class="returns">Array< <a href="#/v5/api/other/assembly/ast/-%23-asm-valuenode">ValueNode</a> ></span><div class="anchors"></div></div><div class="body"><p>The child nodes, which each represent a verbatim piece of data in insert.</p>
|
|
|
|
</div></div><a name="/v5/api/other/assembly/ast/-%23-asm-scopenode"></a><a name="/v5/api/other/assembly/ast/-%23-asm-ast--nodes--asm-scopenode"></a><a name="/v5/api/other/assembly/ast/"></a><h3 class="show-anchors"><div>ScopeNode<span class="inherits"> inherits <a href="#/v5/api/other/assembly/ast/-%23-asm-labellednode">LabelledNode</a></span><div class="anchors"><a class="self" href="#/v5/api/other/assembly/ast/-%23-asm-scopenode"></a><a class="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 <a href="#/v5/api/other/assembly/ast/-%23-asm-linknode">LinkNode</a>'s will use when resolving offset locations, using <code class="inline">@myScope{ ... }</code>.</p>
|
|
|
|
<div class="property show-anchors"><div class="signature"><span class="path">scopeNode</span><span class="symbol">.</span><span class="method">statements</span> <span class="arrow">⇒</span> <span class="returns">Array< <a href="#/v5/api/other/assembly/ast/-%23-asm-node">Node</a> ></span><div class="anchors"></div></div><div class="body"><p>The list of child nodes for this scope.</p>
|
|
|
|
</div></div><div class="page-separator"></div><a name="/v5/api/other/hardware/-%23-hardware-wallets"></a><a name="/v5/api/other/hardware/"></a><h1 class="show-anchors"><div>Hardware Wallets<div class="anchors"><a class="self" href="#/v5/api/other/hardware/-%23-hardware-wallets"></a></div></div></h1>
|
|
<a name="/v5/api/other/hardware/-%23-hw-ledger"></a><a name="/v5/api/other/hardware/-%23-hardware-wallets--hw-ledger"></a><a name="/v5/api/other/hardware/"></a><h2 class="show-anchors"><div>LedgerSigner<span class="inherits"> inherits <a href="#/v5/api/signer/-%23-Signer">Signer</a></span><div class="anchors"><a class="self" href="#/v5/api/other/hardware/-%23-hw-ledger"></a><a class="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 <a href="https://www.ledger.com">Ledger Hardware Wallets</a> are a fairly popular brand.</p>
|
|
|
|
<div class="code-title"><div>Importing in ES6 or TypeScript</div></div><div class="code">import { LedgerSigner } from "@ethersproject/hardware-wallets";
|
|
</div><a name="/v5/api/other/hardware/-%23-hardware-wallets--hw-ledger--api"></a><a name="/v5/api/other/hardware/"></a><h3 class="show-anchors"><div>API<div class="anchors"><a class="self" href="#/v5/api/other/hardware/-%23-hardware-wallets--hw-ledger--api"></a></div></div></h3>
|
|
<div class="property show-anchors"><div class="signature"><span class="modifier">new </span><span class="method">LedgerSigner</span><span class="symbol">(</span> <span class="symbol">[</span> <span class="param">provider</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">type</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">path</span> <span class="symbol">]</span> <span class="symbol">]</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/other/hardware/-%23-hw-ledger">LedgerSigner</a></span><div class="anchors"></div></div><div class="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><div class="page-separator"></div><a name="/v5/api/experimental/-%23-experimental"></a><a name="/v5/api/experimental/"></a><h1 class="show-anchors"><div>Experimental<div class="anchors"><a class="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 <a href="https://semver.org">semver</a> versioning, so applications requiring it should specify the <i>exact version</i> needed.</p>
|
|
|
|
<a name="/v5/api/experimental/-%23-experimental-brainwallet"></a><a name="/v5/api/experimental/-%23-experimental--experimental-brainwallet"></a><a name="/v5/api/experimental/"></a><h2 class="show-anchors"><div>BrainWallet<span class="inherits"> inherits <a href="#/v5/api/signer/-%23-Wallet">Wallet</a></span><div class="anchors"><a class="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>
|
|
|
|
<div class="property show-anchors"><div class="signature"><span class="path">BrainWallet</span><span class="symbol">.</span><span class="method">generate</span><span class="symbol">(</span> <span class="param">username</span> <span class="symbol">,</span> <span class="param">password</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">progressCallback</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/experimental/-%23-experimental-brainwallet">BrainWallet</a></span><div class="anchors"></div></div><div class="body"><p>Generates a brain wallet, with a slightly improved experience, in which the generated wallet has a mnemonic.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">BrainWallet</span><span class="symbol">.</span><span class="method">generateLegacy</span><span class="symbol">(</span> <span class="param">username</span> <span class="symbol">,</span> <span class="param">password</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">progressCallback</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/experimental/-%23-experimental-brainwallet">BrainWallet</a></span><div class="anchors"></div></div><div class="body"><p>Generate a brain wallet which is compatible with the ethers v3 and earlier.</p>
|
|
|
|
</div></div><a name="/v5/api/experimental/-%23-experimental-eip1193bridge"></a><a name="/v5/api/experimental/-%23-experimental--experimental-eip1193bridge"></a><a name="/v5/api/experimental/"></a><h2 class="show-anchors"><div>EIP1193Bridge<span class="inherits"> inherits <a href="https://nodejs.org/dist/latest-v13.x/docs/api/events.html#events_class_eventemitter">EventEmitter</a></span><div class="anchors"><a class="self" href="#/v5/api/experimental/-%23-experimental-eip1193bridge"></a></div></div></h2><p>The <b>EIP1193Bridge</b> allows a normal Ethers <a href="#/v5/api/signer/-%23-Signer">Signer</a> and <a href="#/v5/api/providers/provider/">Provider</a> to be exposed in as a standard <a href="https://eips.ethereum.org/EIPS/eip-1193">EIP-1193 Provider</a>, which may be useful when interacting with other libraries.</p>
|
|
|
|
<a name="/v5/api/experimental/-%23-experimental-noncemanager"></a><a name="/v5/api/experimental/-%23-experimental--experimental-noncemanager"></a><a name="/v5/api/experimental/"></a><h2 class="show-anchors"><div>NonceManager<span class="inherits"> inherits <a href="#/v5/api/signer/-%23-Signer">Signer</a></span><div class="anchors"><a class="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>
|
|
|
|
<div class="property show-anchors"><div class="signature"><span class="modifier">new </span><span class="method">NonceManager</span><span class="symbol">(</span> <span class="param">signer</span> <span class="symbol">)</span><div class="anchors"></div></div><div class="body"><p>Create a new NonceManager.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">nonceManager</span><span class="symbol">.</span><span class="method">signer</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/signer/-%23-Signer">Signer</a></span><div class="anchors"></div></div><div class="body"><p>The signer whose nonce is being managed.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">nonceManager</span><span class="symbol">.</span><span class="method">provider</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/providers/provider/">Provider</a></span><div class="anchors"></div></div><div class="body"><p>The provider associated with the signer.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">nonceManager</span><span class="symbol">.</span><span class="method">setTransactionCount</span><span class="symbol">(</span> <span class="param">count</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">void</span><div class="anchors"></div></div><div class="body"><p>Set the current transaction count (nonce) for the signer.</p>
|
|
|
|
<p>This may be useful in interacting with the signer outside of using this class.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">nonceManager</span><span class="symbol">.</span><span class="method">incrementTransactionCount</span><span class="symbol">(</span> <span class="symbol">[</span> <span class="param">count</span> = <span class="param">1</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">void</span><div class="anchors"></div></div><div class="body"><p>Bump the current transaction count (nonce) by <i>count</i>.</p>
|
|
|
|
<p>This may be useful in interacting with the signer outside of using this class.</p>
|
|
|
|
</div></div><div class="page-separator"></div><a name="/v5/cli/-%23-command-line-interfaces"></a><a name="/v5/cli/"></a><h1 class="show-anchors"><div>Command Line Interfaces<div class="anchors"><a class="self" href="#/v5/cli/-%23-command-line-interfaces"></a></div></div></h1>
|
|
<div class="toc"><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/cli/ethers/">Sandbox Utility</a></div><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/cli/asm/">Assembler</a></div><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/cli/ens/">Ethereum Naming Service</a></div><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/cli/typescript/">TypeScript</a></div><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/cli/plugin/">Making Your Own</a></div></div><div class="page-separator"></div><a name="/v5/cli/ethers/-%23-sandbox-utility"></a><a name="/v5/cli/ethers/"></a><h1 class="show-anchors"><div>Sandbox Utility<div class="anchors"><a class="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, debugging 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>
|
|
|
|
<a name="/v5/cli/ethers/-%23-sandbox-utility--help"></a><a name="/v5/cli/ethers/"></a><h2 class="show-anchors"><div>Help<div class="anchors"><a class="self" href="#/v5/cli/ethers/-%23-sandbox-utility--help"></a></div></div></h2>
|
|
<div class="code">Usage:
|
|
ethers [ COMMAND ] [ ARGS ] [ OPTIONS ]
|
|
|
|
COMMANDS (default: sandbox)
|
|
sandbox Run a REPL VM environment with ethers
|
|
init FILENAME Create a new JSON wallet
|
|
[ --force ] Overwrite any existing files
|
|
fund TARGET Fund TARGET with testnet ether
|
|
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 Signing 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><a name="/v5/cli/ethers/-%23-sandbox-utility--examples"></a><a name="/v5/cli/ethers/"></a><h2 class="show-anchors"><div>Examples<div class="anchors"><a class="self" href="#/v5/cli/ethers/-%23-sandbox-utility--examples"></a></div></div></h2>
|
|
<a name="/v5/cli/ethers/-%23-cliex-init"></a><div class="code-title"><div>Creating New Wallets</div></div><div class="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><a name="/v5/cli/ethers/-%23-cliex-send"></a><div class="code-title"><div>Sending Ether and Tokens</div></div><div class="code"># Sending ether
|
|
/home/ricmoo> ethers --account wallet.json send ricmoo.firefly.eth 0.123
|
|
Password (wallet.json): ******
|
|
Decrypting... 100%
|
|
Transaction:
|
|
To: 0x8ba1f109551bD432803012645Ac136ddd64DBA72
|
|
From: 0xaB7C8803962c0f2F5BBBe3FA8bf41cd82AA1923C
|
|
Value: 0.123 ether
|
|
Nonce: 96
|
|
Data: 0x
|
|
Gas Limit: 21000
|
|
Gas Price: 1.2 gwei
|
|
Chain ID: 1
|
|
Network: homestead
|
|
Send Transaction? (y/N/a) y
|
|
Response:
|
|
Hash: 0xc4adf8b379033d7ab679d199aa35e6ceee9a802ca5ab0656af067e911c4a589a
|
|
|
|
|
|
# Sending a token (SAI)
|
|
# NOTE: the contract address could be used instead but
|
|
# popular token contract addresses are also managed
|
|
# by ethers
|
|
/home/ricmoo> ethers --account wallet.json send-token sai.tokens.ethers.eth ricmoo.firefly.eth 1.0
|
|
Sending Tokens:
|
|
To: 0x8ba1f109551bD432803012645Ac136ddd64DBA72
|
|
Token Contract: 0x89d24A6b4CcB1B6fAA2625fE562bDD9a23260359
|
|
Value: 1.0
|
|
Password (wallet.json): ******
|
|
Decrypting... 100%
|
|
Transaction:
|
|
To: 0x89d24A6b4CcB1B6fAA2625fE562bDD9a23260359
|
|
From: 0xaB7C8803962c0f2F5BBBe3FA8bf41cd82AA1923C
|
|
Value: 0.0 ether
|
|
Nonce: 95
|
|
Data: 0xa9059cbb0000000000000000000000008ba1f109551bd432803012645ac136ddd64dba720000000000000000000000000000000000000000000000000de0b6b3a7640000
|
|
Gas Limit: 37538
|
|
Gas Price: 1.0 gwei
|
|
Chain ID: 1
|
|
Network: homestead
|
|
Send Transaction? (y/N/a) y
|
|
Response:
|
|
Hash: 0xd609ecb7e3b5e8d36fd781dffceede3975ece6774b6322ea56cf1e4d0a17e3a1</div><a name="/v5/cli/ethers/-%23-cliex-signing"></a><div class="code-title"><div>Signing Messages</div></div><div class="code">/home/ethers> ethers --account wallet.json sign-message 'Hello World'
|
|
Password (wallet.json): ******
|
|
Decrypting... 100%
|
|
Message:
|
|
Message: "Hello World"
|
|
Message (hex): 0x48656c6c6f20576f726c64
|
|
Sign Message? (y/N/a) y
|
|
Signature
|
|
Flat: 0xca3f0b32a22a5ab97ca8be7e4a36b1e81d565c6822465d769f4faa4aa24539fb122ee5649c8a37c9f5fc8446593674159e3a7b039997cd6ee697a24b787b1a161b
|
|
r: 0xca3f0b32a22a5ab97ca8be7e4a36b1e81d565c6822465d769f4faa4aa24539fb
|
|
s: 0x122ee5649c8a37c9f5fc8446593674159e3a7b039997cd6ee697a24b787b1a16
|
|
vs: 0x122ee5649c8a37c9f5fc8446593674159e3a7b039997cd6ee697a24b787b1a16
|
|
v: 27
|
|
recid: 0</div><a name="/v5/cli/ethers/-%23-cliex-scripting"></a><a name="/v5/cli/ethers/-%23-sandbox-utility--examples--cliex-scripting"></a><a name="/v5/cli/ethers/"></a><h3 class="show-anchors"><div>Scripting<div class="anchors"><a class="self" href="#/v5/cli/ethers/-%23-cliex-scripting"></a></div></div></h3><p>The <code class="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>
|
|
|
|
<div class="code-title"><div>Get the formatted balance of an account</div></div><div class="code">/home/ethers> ethers --network ropsten \
|
|
--account wallet.json \
|
|
eval \
|
|
'accounts[0].getBalance().then(b => formatEther(b))'
|
|
3.141592653589793238</div><div class="code-title"><div>Get the current block number</div></div><div class="code">/home/ethers> ethers --network rinkeby \
|
|
eval "provider.getBlockNumber()"
|
|
5761009</div><div class="code-title"><div>Convert a Solidity signature to JSON</div></div><div class="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><div class="code-title"><div>Compute a topic hash</div></div><div class="code">/home/ricmoo> ethers eval 'id("Transfer(address,address,uint256")'
|
|
0xd99659a21de82e379975ce8df556f939a4ccb95e92144f38bb0dd35730ffcdd5</div><div class="code-title"><div>Create a random mnemonic</div></div><div class="code">/home/ricmoo> ethers eval 'Wallet.createRandom().mnemonic'
|
|
useful pond inch knock ritual matrix giggle attend dilemma convince coach amazing</div><a name="/v5/cli/ethers/-%23-cliex-mnemonicpassword"></a><a name="/v5/cli/ethers/-%23-sandbox-utility--examples--cliex-mnemonicpassword"></a><a name="/v5/cli/ethers/"></a><h3 class="show-anchors"><div>Using Mnemonics (with a password)<div class="anchors"><a class="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. <code class="inline">""</code>) as the password. If you have a password on your mnemonic, the <code class="inline">--mnemonic-password</code> will prompt for the password to use to decrypt the account.</p>
|
|
|
|
<div class="code">/home/ricmoo> ethers --account mnemonic.txt --mnemonic-password
|
|
Password (mnemonic): ******
|
|
network: homestead (chainId: 1)
|
|
homestead> accounts[0].getAddress()
|
|
<Promise id=0 resolved>
|
|
'0x6d3F723EC1B73141AA4aC248c3ab34A5a1DAD776'
|
|
homestead></div><a name="/v5/cli/ethers/-%23-cliex-mnemonicpassword-xxx"></a><a name="/v5/cli/ethers/-%23-sandbox-utility--examples--cliex-mnemonicpassword-xxx"></a><a name="/v5/cli/ethers/"></a><h3 class="show-anchors"><div>Using Mnemonics (with experimental memory-hard passwords)<div class="anchors"><a class="self" href="#/v5/cli/ethers/-%23-cliex-mnemonicpassword-xxx"></a></div></div></h3><p>The <code class="inline">--xxx-mnemonic-password</code> is similar to the <code class="inline">--mnemonic-password</code> options, which uses a password to decrypt the account for a mnemonic, however it passes the password through the <a href="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>
|
|
|
|
<div class="code">/home/ricmoo> ethers --account mnemonic.txt --xxx-mnemonic-password
|
|
Password (mnemonic; experimental - hard): ******
|
|
Decrypting... 100%
|
|
network: homestead (chainId: 1)
|
|
homestead> accounts[0].getAddress()
|
|
<Promise id=0 resolved>
|
|
'0x56FC8792cC17971C19bEC4Ced978beEA44711EeD'
|
|
homestead></div><div class="definition container-box warning"><div class="term">Note</div><div class="body"><p>This is still an experimental feature (hence the <code class="inline">xxx</code>).</p>
|
|
|
|
</div></div><div class="page-separator"></div><a name="/v5/cli/asm/-%23-cli-asm"></a><a name="/v5/cli/asm/-%23-cli-asm"></a><a name="/v5/cli/asm/"></a><h1 class="show-anchors"><div>Assembler<div class="anchors"><a class="self" href="#/v5/cli/asm/-%23-cli-asm"></a></div></div></h1><p>The assembler Command-Line utility allows you to assemble the <a href="#/v5/api/other/assembly/dialect/">Ethers ASM Dialect</a> into deployable EVM bytecode and disassemble EVM bytecode into human-readable mnemonics.</p>
|
|
|
|
<a name="/v5/cli/asm/-%23-cli-asm--help"></a><a name="/v5/cli/asm/"></a><h2 class="show-anchors"><div>Help<div class="anchors"><a class="self" href="#/v5/cli/asm/-%23-cli-asm--help"></a></div></div></h2>
|
|
<div class="code">Usage:
|
|
ethers-asm [ FILENAME ] [ OPTIONS ]
|
|
|
|
OPTIONS
|
|
--define KEY=VALUE provide assembler defines
|
|
--disassemble Disassemble input bytecode
|
|
--ignore-warnings Ignore warnings
|
|
--pic generate position independent code
|
|
--target LABEL output LABEL bytecode (default: _)
|
|
|
|
OTHER OPTIONS
|
|
--debug Show stack traces for errors
|
|
--help Show this usage and exit
|
|
--version Show this version and exit</div><a name="/v5/cli/asm/-%23-cli-asm--example-input-files"></a><a name="/v5/cli/asm/"></a><h2 class="show-anchors"><div>Example Input Files<div class="anchors"><a class="self" href="#/v5/cli/asm/-%23-cli-asm--example-input-files"></a></div></div></h2>
|
|
<div class="code-title"><div>SimpleStore.asm</div></div><div class="code">; SimpleStore (uint)
|
|
|
|
; Set the initial value of 42
|
|
sstore(0, 42)
|
|
|
|
; Init code to deploy myContract
|
|
codecopy(0, $myContract, #myContract)
|
|
return(0, #myContract)
|
|
|
|
@myContract {
|
|
; Non-payable
|
|
jumpi($error, callvalue)
|
|
|
|
; Get the Sighash
|
|
shr({{= 256 - 32 }}, calldataload(0))
|
|
|
|
; getValue()
|
|
dup1
|
|
{{= sighash("getValue()") }}
|
|
jumpi($getValue, eq)
|
|
|
|
; setValue(uint)
|
|
dup1
|
|
{{= sighash("setValue(uint)") }}
|
|
jumpi($setValue, eq)
|
|
|
|
; No matching signature
|
|
@error:
|
|
revert(0, 0)
|
|
|
|
@getValue:
|
|
mstore(0, sload(0))
|
|
return (0, 32)
|
|
|
|
@setValue:
|
|
; Make sure we have exactly a uint
|
|
jumpi($error, iszero(eq(calldatasize, 36)))
|
|
|
|
; Store the value
|
|
sstore(0, calldataload(4))
|
|
return (0, 0)
|
|
|
|
; There is no *need* for the PUSH32, it just makes
|
|
; decompiled code look nicer
|
|
@checksum[
|
|
{{= (defines.checksum ? concat([
|
|
Opcode.from("PUSH32"),
|
|
id(myContract.source)
|
|
]): "0x")
|
|
}}
|
|
]
|
|
}</div><div class="code-title"><div>SimpleStore.bin</div></div><div class="code">0x602a6000556044601160003960446000f334601e5760003560e01c8063209652
|
|
0x5514602457806355241077146030575b60006000fd5b60005460005260206000
|
|
0xf35b6024361415601e5760043560005560006000f3</div><div class="definition container-box note"><div class="term">Note: Bytecode File Syntax</div><div class="body"><p>A bin file may be made up of multiple blocks of bytecode, each may optionally begin with a <code class="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><a name="/v5/cli/asm/-%23-cli-asm--assembler-examples"></a><a name="/v5/cli/asm/"></a><h2 class="show-anchors"><div>Assembler Examples<div class="anchors"><a class="self" href="#/v5/cli/asm/-%23-cli-asm--assembler-examples"></a></div></div></h2><p>The assembler converts an <a href="#/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 stabilizes. This allows for more compact jump destinations and for code to include more advanced meta-programming techniques.</p>
|
|
|
|
<div class="code">/home/ethers> ethers-asm SimpleStore.asm
|
|
0x602a6000556044601160003960446000f334601e5760003560e01c80632096525514602457806355241077146030575b60006000fd5b60005460005260206000f35b6024361415601e5760043560005560006000f3
|
|
|
|
# Piping in ASM source code
|
|
/home/ethers> cat SimpleStore.asm | ethers-asm
|
|
# Same as above
|
|
|
|
# Setting a define which the ASM file checks and adds a checksum
|
|
/home/ethers> ethers-asm --define checksum SimpleStore.asm
|
|
0x602a6000556065601160003960656000f334601e5760003560e01c80632096525514602457806355241077146030575b60006000fd5b60005460005260206000f35b6024361415601e5760043560005560006000f37f10358310d664c9aeb4bf4ce7a10a6a03176bd23194c8ccbd3160a6dac90774d6</div><a name="/v5/cli/asm/-%23-cli-asm--assembler-examples--options"></a><a name="/v5/cli/asm/"></a><h3 class="show-anchors"><div>Options<div class="anchors"><a class="self" href="#/v5/cli/asm/-%23-cli-asm--assembler-examples--options"></a></div></div></h3>
|
|
<div class="definition"><div class="term"><b>--define KEY=VALUE</b> <i>or</i> <b>--define FLAG</b></div><div class="body"><p>This allows key/value pairs (where the value is a string) and flags (which the value is <code class="inline">true</code>) to be passed along to the assembler, which can be accessed in <a href="#/v5/api/other/assembly/dialect/-%23-asm-dialect-scripting">Scripting Blocks</a>, such as <code class="inline">{{= defined.someKey }}</code>.</p>
|
|
|
|
</div></div><div class="definition"><div class="term"><b>--ignore-warnings</b></div><div class="body"><p>By default any warning will be treated like an error. This enabled by-passing warnings.</p>
|
|
|
|
</div></div><div class="definition"><div class="term"><b>--pic</b></div><div class="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 gas cost of 8 gas per offset access though.</p>
|
|
|
|
</div></div><div class="definition"><div class="term"><b>--target LABEL</b></div><div class="body"><p>All programs have a root scope named <code class="inline">_</code> which is by default assembled. This option allows another labelled target (either a <a href="#/v5/api/other/assembly/dialect/-%23-asm-dialect-scope">Scopes</a> or a <a href="#/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><a name="/v5/cli/asm/-%23-cli-asm--disassembler-examples"></a><a name="/v5/cli/asm/"></a><h2 class="show-anchors"><div>Disassembler Examples<div class="anchors"><a class="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>
|
|
|
|
<div class="code">/home/ethers> ethers-asm --disassemble SimpleStore.bin
|
|
0000 : 0x2a ; #1
|
|
0002 : 0x00 ; #1
|
|
0004 : SSTORE
|
|
0005 : 0x44 ; #1
|
|
0007 : 0x11 ; #1
|
|
0009 : 0x00 ; #1
|
|
000b : CODECOPY
|
|
000c : 0x44 ; #1
|
|
000e : 0x00 ; #1
|
|
0010 : RETURN
|
|
0011 : CALLVALUE
|
|
0012 : 0x1e ; #1
|
|
0014 : JUMPI
|
|
0015 : 0x00 ; #1
|
|
0017 : CALLDATALOAD
|
|
0018 : 0xe0 ; #1
|
|
001a : SHR
|
|
001b : DUP1
|
|
001c : 0x20965255 ; #4
|
|
0021 : EQ
|
|
0022 : 0x24 ; #1
|
|
0024 : JUMPI
|
|
0025 : DUP1
|
|
0026 : 0x55241077 ; #4
|
|
002b : EQ
|
|
002c : 0x30 ; #1
|
|
002e : JUMPI
|
|
002f*: JUMPDEST
|
|
0030 : 0x00 ; #1
|
|
0032 : 0x00 ; #1
|
|
0034 : REVERT
|
|
0035*: JUMPDEST
|
|
0036 : 0x00 ; #1
|
|
0038 : SLOAD
|
|
0039 : 0x00 ; #1
|
|
003b : MSTORE
|
|
003c : 0x20 ; #1
|
|
003e : 0x00 ; #1
|
|
0040 : RETURN
|
|
0041*: JUMPDEST
|
|
0042 : 0x24 ; #1
|
|
0044 : CALLDATASIZE
|
|
0045 : EQ
|
|
0046 : ISZERO
|
|
0047 : 0x1e ; #1
|
|
0049 : JUMPI
|
|
004a : 0x04 ; #1
|
|
004c : CALLDATALOAD
|
|
004d : 0x00 ; #1
|
|
004f : SSTORE
|
|
0050 : 0x00 ; #1
|
|
0052 : 0x00 ; #1
|
|
0054 : RETURN
|
|
|
|
/home/ethers> cat SimpleStore.bin | ethers-asm --disassemble
|
|
# Same as above</div><div class="page-separator"></div><a name="/v5/cli/ens/-%23-ethereum-naming-service"></a><a name="/v5/cli/ens/"></a><h1 class="show-anchors"><div>Ethereum Naming Service<div class="anchors"><a class="self" href="#/v5/cli/ens/-%23-ethereum-naming-service"></a></div></div></h1>
|
|
<a name="/v5/cli/ens/-%23-ethereum-naming-service--help"></a><a name="/v5/cli/ens/"></a><h2 class="show-anchors"><div>Help<div class="anchors"><a class="self" href="#/v5/cli/ens/-%23-ethereum-naming-service--help"></a></div></div></h2>
|
|
<div class="code">Usage:
|
|
ethers-ens COMMAND [ ARGS ] [ OPTIONS ]
|
|
|
|
COMMANDS
|
|
lookup [ NAME | ADDRESS [ ... ] ]
|
|
Lookup a name or address
|
|
commit NAME Submit a 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)
|
|
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 Signing 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><a name="/v5/cli/ens/-%23-ethereum-naming-service--examples"></a><a name="/v5/cli/ens/"></a><h2 class="show-anchors"><div>Examples<div class="anchors"><a class="self" href="#/v5/cli/ens/-%23-ethereum-naming-service--examples"></a></div></div></h2><p>TODO examples</p>
|
|
|
|
<div class="page-separator"></div><a name="/v5/cli/typescript/-%23-typescript"></a><a name="/v5/cli/typescript/"></a><h1 class="show-anchors"><div>TypeScript<div class="anchors"><a class="self" href="#/v5/cli/typescript/-%23-typescript"></a></div></div></h1>
|
|
<a name="/v5/cli/typescript/-%23-typescript--help"></a><a name="/v5/cli/typescript/"></a><h2 class="show-anchors"><div>Help<div class="anchors"><a class="self" href="#/v5/cli/typescript/-%23-typescript--help"></a></div></div></h2>
|
|
<div class="code">Usage:
|
|
ethers-ts FILENAME [ ... ] [ OPTIONS ]
|
|
|
|
OPTIONS
|
|
--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><a name="/v5/cli/typescript/-%23-typescript--examples"></a><a name="/v5/cli/typescript/"></a><h2 class="show-anchors"><div>Examples<div class="anchors"><a class="self" href="#/v5/cli/typescript/-%23-typescript--examples"></a></div></div></h2><p>TODO</p>
|
|
|
|
<div class="page-separator"></div><a name="/v5/cli/plugin/-%23-cli-diy"></a><a name="/v5/cli/plugin/-%23-cli-diy"></a><a name="/v5/cli/plugin/"></a><h1 class="show-anchors"><div>Making Your Own<div class="anchors"><a class="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>
|
|
|
|
<a name="/v5/cli/plugin/-%23-cli-cli"></a><a name="/v5/cli/plugin/-%23-cli-diy--cli-cli"></a><a name="/v5/cli/plugin/"></a><h2 class="show-anchors"><div>CLI<div class="anchors"><a class="self" href="#/v5/cli/plugin/-%23-cli-cli"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/cli/src.ts/cli.ts#L717">source</a></div></div></h2><p>A <b>CLI</b> handles parsing all the command-line flags, options and arguments and instantiates a <a href="#/v5/cli/plugin/-%23-cli-plugin">Plugin</a> to process the command.</p>
|
|
|
|
<p>A <b>CLI</b> may support multiple <a href="#/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 <a href="#/v5/cli/plugin/-%23-cli-plugin">Plugin</a> will be used and no command argument is allowed.</p>
|
|
|
|
<a name="/v5/cli/plugin/-%23-cli-addplugin"></a><div class="property show-anchors"><div class="signature"><span class="method">addPlugin</span><span class="symbol">(</span> <span class="param">command</span> <span class="symbol">,</span> <span class="param">pluginClass</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">void</span><div class="anchors"><a class="self" href="#/v5/cli/plugin/-%23-cli-addplugin"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/cli/src.ts/cli.ts#L757">source</a></div></div><div class="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><a name="/v5/cli/plugin/-%23-cli-setplugin"></a><div class="property show-anchors"><div class="signature"><span class="method">setPlugin</span><span class="symbol">(</span> <span class="param">pluginClass</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">void</span><div class="anchors"><a class="self" href="#/v5/cli/plugin/-%23-cli-setplugin"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/cli/src.ts/cli.ts#L771">source</a></div></div><div class="body"><p>Set a dedicated <a href="#/v5/cli/plugin/-%23-cli-plugin">Plugin</a> class which will handle all input. This may not be used in conjunction with addPlugin and will not automatically accept a command from the arguments.</p>
|
|
|
|
</div></div><a name="/v5/cli/plugin/-%23-cli-showusage"></a><div class="property show-anchors"><div class="signature"><span class="method">showUsage</span><span class="symbol">(</span> <span class="symbol">[</span> <span class="param">message</span> = "" <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">status</span> = <span class="param">0</span> <span class="symbol">]</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">never</span><div class="anchors"><a class="self" href="#/v5/cli/plugin/-%23-cli-showusage"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/cli/src.ts/cli.ts#L785">source</a></div></div><div class="body"><p>Shows the usage help screen for the CLI and terminates.</p>
|
|
|
|
</div></div><a name="/v5/cli/plugin/-%23-cli-run"></a><div class="property show-anchors"><div class="signature"><span class="method">run</span><span class="symbol">(</span> <span class="param">args</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< void ></span><div class="anchors"><a class="self" href="#/v5/cli/plugin/-%23-cli-run"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/cli/src.ts/cli.ts#L912">source</a></div></div><div class="body"><p>Usually the value of <i>args</i> passed in will be <code class="inline">process.argv.slice(2)</code>.</p>
|
|
|
|
</div></div><a name="/v5/cli/plugin/-%23-cli-plugin"></a><a name="/v5/cli/plugin/-%23-cli-diy--cli-plugin"></a><a name="/v5/cli/plugin/"></a><h2 class="show-anchors"><div>Plugin<div class="anchors"><a class="self" href="#/v5/cli/plugin/-%23-cli-plugin"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/cli/src.ts/cli.ts#L492">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 <code class="inline">getHelp</code> and <code class="inline">getOptionHelp</code> are used to generate the help screen.</p>
|
|
|
|
<p>Otherwise, a plugin is instantiated and the <code class="inline">prepareOptions</code> is called. Each plugin <b>must</b> call <code class="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 <code class="inline">prepareArguments</code> is called. This should validate the number of arguments expected and throw an 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 <code class="inline">run</code> is called.</p>
|
|
|
|
<div class="property show-anchors"><div class="signature"><span class="path">plugin</span><span class="symbol">.</span><span class="method">network</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/providers/types/-%23-providers-Network">Network</a></span><div class="anchors"></div></div><div class="body"><p>The network this plugin is running for.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">plugin</span><span class="symbol">.</span><span class="method">provider</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/providers/provider/">Provider</a></span><div class="anchors"></div></div><div class="body"><p>The provider for this plugin is running for.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">plugin</span><span class="symbol">.</span><span class="method">accounts</span> <span class="arrow">⇒</span> <span class="returns">Array< <a href="#/v5/api/signer/-%23-Signer">Signer</a> ></span><div class="anchors"></div></div><div class="body"><p>The accounts passed into the plugin using <code class="inline">--account</code>, <code class="inline">--account-rpc</code> and <code class="inline">--account-void</code> which this plugin can use.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">plugin</span><span class="symbol">.</span><span class="method">gasLimit</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/bignumber/">BigNumber</a></span><div class="anchors"></div></div><div class="body"><p>The gas limit this plugin should use. This is null if unspecified.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">plugin</span><span class="symbol">.</span><span class="method">gasPrice</span> <span class="arrow">⇒</span> <span class="returns"><a href="#/v5/api/utils/bignumber/">BigNumber</a></span><div class="anchors"></div></div><div class="body"><p>The gas price this plugin should use. This is null if unspecified.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">plugin</span><span class="symbol">.</span><span class="method">nonce</span> <span class="arrow">⇒</span> <span class="returns">number</span><div class="anchors"></div></div><div class="body"><p>The initial nonce for the account this plugin should use.</p>
|
|
|
|
</div></div><a name="/v5/cli/plugin/-%23-cli-diy--cli-plugin--methods"></a><a name="/v5/cli/plugin/"></a><h3 class="show-anchors"><div>Methods<div class="anchors"><a class="self" href="#/v5/cli/plugin/-%23-cli-diy--cli-plugin--methods"></a></div></div></h3>
|
|
<a name="/v5/cli/plugin/-%23-plugin-prepareoptions"></a><div class="property show-anchors"><div class="signature"><span class="path">plugin</span><span class="symbol">.</span><span class="method">prepareOptions</span><span class="symbol">(</span> <span class="param">argParser</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">verifyOnly</span> = <span class="param">false</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< void ></span><div class="anchors"><a class="self" href="#/v5/cli/plugin/-%23-plugin-prepareoptions"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/cli/src.ts/cli.ts#L517">source</a></div></div><div class="body">
|
|
</div></div><a name="/v5/cli/plugin/-%23-plugin-prepareargs"></a><div class="property show-anchors"><div class="signature"><span class="path">plugin</span><span class="symbol">.</span><span class="method">prepareArgs</span><span class="symbol">(</span> <span class="param">args</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< void ></span><div class="anchors"><a class="self" href="#/v5/cli/plugin/-%23-plugin-prepareargs"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/cli/src.ts/cli.ts#L657">source</a></div></div><div class="body">
|
|
</div></div><a name="/v5/cli/plugin/-%23-plugin-run"></a><div class="property show-anchors"><div class="signature"><span class="path">plugin</span><span class="symbol">.</span><span class="method">run</span><span class="symbol">(</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< void ></span><div class="anchors"><a class="self" href="#/v5/cli/plugin/-%23-plugin-run"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/cli/src.ts/cli.ts#L661">source</a></div></div><div class="body">
|
|
</div></div><a name="/v5/cli/plugin/-%23-plugin-getaddress"></a><div class="property show-anchors"><div class="signature"><span class="path">plugin</span><span class="symbol">.</span><span class="method">getAddress</span><span class="symbol">(</span> <span class="param">addressOrName</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">message</span> = "" <span class="symbol">,</span> <span class="symbol">[</span> <span class="param">allowZero</span> = <span class="param">false</span> <span class="symbol">]</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Promise< string ></span><div class="anchors"><a class="self" href="#/v5/cli/plugin/-%23-plugin-getaddress"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/cli/src.ts/cli.ts#L665">source</a></div></div><div class="body"><p>A plugin should use this method to resolve an address. If the resolved address is the zero address and <i>allowZero</i> is not true, an error is raised.</p>
|
|
|
|
</div></div><a name="/v5/cli/plugin/-%23-plugin-dump"></a><div class="property show-anchors"><div class="signature"><span class="path">plugin</span><span class="symbol">.</span><span class="method">dump</span><span class="symbol">(</span> <span class="param">header</span> <span class="symbol">,</span> <span class="param">info</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">void</span><div class="anchors"><a class="self" href="#/v5/cli/plugin/-%23-plugin-dump"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/cli/src.ts/cli.ts#L684">source</a></div></div><div class="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><a name="/v5/cli/plugin/-%23-plugin-throwusageerror"></a><div class="property show-anchors"><div class="signature"><span class="path">plugin</span><span class="symbol">.</span><span class="method">throwUsageError</span><span class="symbol">(</span> <span class="symbol">[</span> <span class="param">message</span> = "" <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">never</span><div class="anchors"><a class="self" href="#/v5/cli/plugin/-%23-plugin-throwusageerror"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/cli/src.ts/cli.ts#L690">source</a></div></div><div class="body"><p>Stops execution of the plugin and shows the help screen of the plugin with the optional <i>message</i>.</p>
|
|
|
|
</div></div><a name="/v5/cli/plugin/-%23-plugin-throwerror"></a><div class="property show-anchors"><div class="signature"><span class="path">plugin</span><span class="symbol">.</span><span class="method">throwError</span><span class="symbol">(</span> <span class="param">message</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">never</span><div class="anchors"><a class="self" href="#/v5/cli/plugin/-%23-plugin-throwerror"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/cli/src.ts/cli.ts#L695">source</a></div></div><div class="body"><p>Stops execution of the plugin and shows <i>message</i>.</p>
|
|
|
|
</div></div><a name="/v5/cli/plugin/-%23-cli-diy--cli-plugin--static-methods"></a><a name="/v5/cli/plugin/"></a><h3 class="show-anchors"><div>Static Methods<div class="anchors"><a class="self" href="#/v5/cli/plugin/-%23-cli-diy--cli-plugin--static-methods"></a></div></div></h3>
|
|
<a name="/v5/cli/plugin/-%23-plugin-gethelp"></a><div class="property show-anchors"><div class="signature"><span class="path">Plugin</span><span class="symbol">.</span><span class="method">getHelp</span> <span class="arrow">⇒</span> <span class="returns">Help</span><div class="anchors"><a class="self" href="#/v5/cli/plugin/-%23-plugin-gethelp"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/cli/src.ts/cli.ts#L509">source</a></div></div><div class="body"><p>Each subclass should implement this static method which is used to generate the help screen.</p>
|
|
|
|
</div></div><a name="/v5/cli/plugin/-%23-plugin-getoptionshelp"></a><div class="property show-anchors"><div class="signature"><span class="path">Plugin</span><span class="symbol">.</span><span class="method">getOptionHelp</span> <span class="arrow">⇒</span> <span class="returns">Array< Help ></span><div class="anchors"><a class="self" href="#/v5/cli/plugin/-%23-plugin-getoptionshelp"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/cli/src.ts/cli.ts#L513">source</a></div></div><div class="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><a name="/v5/cli/plugin/-%23-cli-argparser"></a><a name="/v5/cli/plugin/-%23-cli-diy--cli-argparser"></a><a name="/v5/cli/plugin/"></a><h2 class="show-anchors"><div>ArgParser<div class="anchors"><a class="self" href="#/v5/cli/plugin/-%23-cli-argparser"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/cli/src.ts/cli.ts#L294">source</a></div></div></h2><p>The <b>ArgParser</b> is used to parse a command line into flags, options and arguments.</p>
|
|
|
|
<div class="code">/home/ethers> ethers --account wallet.json --yes send ricmoo.eth 1.0
|
|
# An Option ----------^ ^ ^
|
|
# - name = "account" | |
|
|
# - value = "wallet.json" | |
|
|
# A Flag -----------------------------------+ |
|
|
# - name = "yes" |
|
|
# - value = true |
|
|
# Arguments ------------------------------------+
|
|
# - count = 3
|
|
# - [ "send", "ricmoo.eth", "1.0" ]</div><p>Flags are simple binary options (such as the <code class="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 <code class="inline">--account wallet.json</code>, which has the name <code class="inline">account</code> and the value <code class="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>
|
|
|
|
<a name="/v5/cli/plugin/-%23-argparser-consumeflag"></a><div class="property show-anchors"><div class="signature"><span class="path">argParser</span><span class="symbol">.</span><span class="method">consumeFlag</span><span class="symbol">(</span> <span class="param">name</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">boolean</span><div class="anchors"><a class="self" href="#/v5/cli/plugin/-%23-argparser-consumeflag"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/cli/src.ts/cli.ts#L335">source</a></div></div><div class="body"><p>Remove the flag <i>name</i> and return true if it is present.</p>
|
|
|
|
</div></div><a name="/v5/cli/plugin/-%23-argparser-consumemultioptions"></a><div class="property show-anchors"><div class="signature"><span class="path">argParser</span><span class="symbol">.</span><span class="method">consumeMultiOptions</span><span class="symbol">(</span> <span class="param">names</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Array< {name:string,value:string} ></span><div class="anchors"><a class="self" href="#/v5/cli/plugin/-%23-argparser-consumemultioptions"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/cli/src.ts/cli.ts#L353">source</a></div></div><div class="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><a name="/v5/cli/plugin/-%23-argparser-consumeoption"></a><div class="property show-anchors"><div class="signature"><span class="path">argParser</span><span class="symbol">.</span><span class="method">consumeOption</span><span class="symbol">(</span> <span class="param">name</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string</span><div class="anchors"><a class="self" href="#/v5/cli/plugin/-%23-argparser-consumeoption"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/cli/src.ts/cli.ts#L382">source</a></div></div><div class="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><a name="/v5/cli/plugin/-%23-argparser-consumeoptions"></a><div class="property show-anchors"><div class="signature"><span class="path">argParser</span><span class="symbol">.</span><span class="method">consumeOptions</span><span class="symbol">(</span> <span class="param">name</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Array< string ></span><div class="anchors"><a class="self" href="#/v5/cli/plugin/-%23-argparser-consumeoptions"></a><a class="source" href="https://github.com/ethers-io/ethers.js/blob/master/packages/cli/src.ts/cli.ts#L378">source</a></div></div><div class="body"><p>Remove all options with their values for <i>name</i> and return the list (in order) of values.</p>
|
|
|
|
</div></div><div class="page-separator"></div><a name="/v5/cookbook/-%23-cookbook"></a><a name="/v5/cookbook/"></a><h1 class="show-anchors"><div>Cookbook<div class="anchors"><a class="self" href="#/v5/cookbook/-%23-cookbook"></a></div></div></h1><p>A collection (that will grow over time) of common, simple snippets of code that are in general useful.</p>
|
|
|
|
<div class="toc"><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/cookbook/react-native/">React Native (and ilk)</a></div></div><div class="page-separator"></div><a name="/v5/cookbook/react-native/-%23-cookbook-reactnative"></a><a name="/v5/cookbook/react-native/-%23-cookbook-reactnative"></a><a name="/v5/cookbook/react-native/"></a><h1 class="show-anchors"><div>React Native (and ilk)<div class="anchors"><a class="self" href="#/v5/cookbook/react-native/-%23-cookbook-reactnative"></a></div></div></h1><p>The <a href="https://reactnative.dev">React Native</a> framework has become quite popular and has many popular forks, such as <a href="https://expo.io">Expo</a>.</p>
|
|
|
|
<p>React Native is based on <a href="https://developer.apple.com/documentation/javascriptcore?language=objc">JavaScriptCore</a> (part of WebKit) and does not use Node.js or the common Web and DOM APIs. As such, there are many operations missing that a normal web environment or Node.js instance would provide.</p>
|
|
|
|
<p>For this reason, there is a <a href="https://www.npmjs.com/package/@ethersproject/shims">Shims</a> module provided to fill in the holes.</p>
|
|
|
|
<a name="/v5/cookbook/react-native/-%23-cookbook-reactnative-shims"></a><a name="/v5/cookbook/react-native/-%23-cookbook-reactnative--cookbook-reactnative-shims"></a><a name="/v5/cookbook/react-native/"></a><h2 class="show-anchors"><div>Installing<div class="anchors"><a class="self" href="#/v5/cookbook/react-native/-%23-cookbook-reactnative-shims"></a></div></div></h2><p>To use ethers in React Native, you must either provide shims for the needed missing functionality, or use the ethers.js shim.</p>
|
|
|
|
<p>It is <b>HIGHLY RECOMMENDED</b> you check out the <a href="#/v5/cookbook/react-native/-%23-cookbook-reactnative-security">security section</a> below for instructions on installing packages which can affect the security of your application.</p>
|
|
|
|
<p>After installing packages, you may need to restart your packager and company.</p>
|
|
|
|
<div class="code-title"><div>Installing</div></div><div class="code">/home/ricmoo/my-react-project> npm install @ethersproject/shims --save</div><div class="code-title"><div>Importing</div></div><div class="code"><span class="comment">// Pull in the shims (BEFORE importing ethers)
|
|
</span>import "@ethersproject/shims"
|
|
|
|
<span class="comment">// Import the ethers library
|
|
</span>import { ethers } from "ethers";
|
|
</div><a name="/v5/cookbook/react-native/-%23-cookbook-reactnative-security"></a><a name="/v5/cookbook/react-native/-%23-cookbook-reactnative--cookbook-reactnative-security"></a><a name="/v5/cookbook/react-native/"></a><h2 class="show-anchors"><div>Security<div class="anchors"><a class="self" href="#/v5/cookbook/react-native/-%23-cookbook-reactnative-security"></a></div></div></h2><p>The React Native environment does not contain a secure random source, which is used when computing random private keys. This could result in private keys that others could possibly guess, allowing funds to be stolen and assets manipulated.</p>
|
|
|
|
<p>For this reason, it is <b>HIGHLY RECOMMENDED</b> to also install the <a href="https://www.npmjs.com/package/react-native-get-random-values">React Native get-random-values</a>, which <b>must</b> be included before the shims. If it worked correctly you should not receive any warning in the console regarding missing secure random sources.</p>
|
|
|
|
<div class="code-title"><div>Importing with Secure Random Sources</div></div><div class="code"><span class="comment">// Import the crypto getRandomValues shim (**BEFORE** the shims)
|
|
</span>import "react-native-get-random-values"
|
|
|
|
<span class="comment">// Import the the ethers shims (**BEFORE** ethers)
|
|
</span>import "@ethersproject/shims"
|
|
|
|
<span class="comment">// Import the ethers library
|
|
</span>import { ethers } from "ethers";
|
|
</div><div class="page-separator"></div><a name="/v5/migration/-%23-migration"></a><a name="/v5/migration/-%23-migration"></a><a name="/v5/migration/"></a><h1 class="show-anchors"><div>Migration Guide<div class="anchors"><a class="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>
|
|
|
|
<div class="toc"><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/migration/web3/">Migration: From Web3.js</a></div><div style="padding-left: 0px"><span class="bullet">•</span><a href="#/v5/migration/ethers-v4/">Migration: From Ethers v4</a></div></div><div class="page-separator"></div><a name="/v5/migration/web3/-%23-migration-from-web3-js"></a><a name="/v5/migration/web3/"></a><h1 class="show-anchors"><div>Migration: From Web3.js<div class="anchors"><a class="self" href="#/v5/migration/web3/-%23-migration-from-web3-js"></a></div></div></h1><p>This migration guide focuses on migrating web3.js version 1.2.9 to ethers.js v5.</p>
|
|
|
|
<a name="/v5/migration/web3/-%23-migration-from-web3-js--providers"></a><a name="/v5/migration/web3/"></a><h2 class="show-anchors"><div>Providers<div class="anchors"><a class="self" href="#/v5/migration/web3/-%23-migration-from-web3-js--providers"></a></div></div></h2><p>In ethers, a provider provides an abstraction for a connection to the Ethereum Network. It can be used to issue read only queries and send signed state changing transactions to the Ethereum Network.</p>
|
|
|
|
<a name="/v5/migration/web3/-%23-migration-from-web3-js--providers--connecting-to-ethereum"></a><a name="/v5/migration/web3/"></a><h3 class="show-anchors"><div>Connecting to Ethereum<div class="anchors"><a class="self" href="#/v5/migration/web3/-%23-migration-from-web3-js--providers--connecting-to-ethereum"></a></div></div></h3>
|
|
<div class="code"><span class="comment">// web3
|
|
</span>var Web3 = require('web3');
|
|
var web3 = new Web3('http://localhost:8545');
|
|
|
|
<span class="comment">// ethers
|
|
</span>var ethers = require('ethers');
|
|
const url = "http://127.0.0.1:8545";
|
|
const provider = new ethers.providers.JsonRpcProvider(url);
|
|
</div><a name="/v5/migration/web3/-%23-migration-from-web3-js--providers--connecting-to-ethereum-metamask"></a><a name="/v5/migration/web3/"></a><h3 class="show-anchors"><div>Connecting to Ethereum: Metamask<div class="anchors"><a class="self" href="#/v5/migration/web3/-%23-migration-from-web3-js--providers--connecting-to-ethereum-metamask"></a></div></div></h3>
|
|
<div class="code"><span class="comment">// web3
|
|
</span>const web3 = new Web3(Web3.givenProvider);
|
|
|
|
<span class="comment">// ethers
|
|
</span>const provider = new ethers.providers.Web3Provider(window.ethereum);
|
|
</div><a name="/v5/migration/web3/-%23-migration-from-web3-js--signers"></a><a name="/v5/migration/web3/"></a><h2 class="show-anchors"><div>Signers<div class="anchors"><a class="self" href="#/v5/migration/web3/-%23-migration-from-web3-js--signers"></a></div></div></h2><p>In ethers, a <b>signer</b> is an abstraction of an Ethereum Account. It can be used to sign messages and transactions and send signed transactions to the Ethereum Network.</p>
|
|
|
|
<p>In web3, an account can be used to sign messages and transactions.</p>
|
|
|
|
<a name="/v5/migration/web3/-%23-migration-from-web3-js--signers--creating-signer"></a><a name="/v5/migration/web3/"></a><h3 class="show-anchors"><div>Creating signer<div class="anchors"><a class="self" href="#/v5/migration/web3/-%23-migration-from-web3-js--signers--creating-signer"></a></div></div></h3>
|
|
<div class="code"><span class="comment">// web3
|
|
</span>const account = web3.eth.accounts.create();
|
|
|
|
<span class="comment">// ethers (create random new account)
|
|
</span>const signer = ethers.Wallet.createRandom();
|
|
|
|
<span class="comment">// ethers (connect to JSON-RPC accounts)
|
|
</span>const signer = provider.getSigner();
|
|
</div><a name="/v5/migration/web3/-%23-migration-from-web3-js--signers--signing-a-message"></a><a name="/v5/migration/web3/"></a><h3 class="show-anchors"><div>Signing a message<div class="anchors"><a class="self" href="#/v5/migration/web3/-%23-migration-from-web3-js--signers--signing-a-message"></a></div></div></h3>
|
|
<div class="code"><span class="comment">// web3 (using a private key)
|
|
</span>signature = web3.eth.accounts.sign('Some data', privateKey)
|
|
|
|
<span class="comment">// web3 (using a JSON-RPC account)
|
|
</span><span class="comment">// @TODO
|
|
</span>
|
|
<span class="comment">// ethers
|
|
</span>signature = await signer.signMessage('Some data')
|
|
</div><a name="/v5/migration/web3/-%23-migration-from-web3-js--contracts"></a><a name="/v5/migration/web3/"></a><h2 class="show-anchors"><div>Contracts<div class="anchors"><a class="self" href="#/v5/migration/web3/-%23-migration-from-web3-js--contracts"></a></div></div></h2><p>A contract object is an abstraction of a smart contract on the Ethereum Network. It allows for easy interaction with the smart contact.</p>
|
|
|
|
<a name="/v5/migration/web3/-%23-migration-from-web3-js--contracts--deploying-a-contract"></a><a name="/v5/migration/web3/"></a><h3 class="show-anchors"><div>Deploying a Contract<div class="anchors"><a class="self" href="#/v5/migration/web3/-%23-migration-from-web3-js--contracts--deploying-a-contract"></a></div></div></h3>
|
|
<div class="code"><span class="comment">// web3
|
|
</span>const contract = new web3.eth.Contract(abi);
|
|
contract.deploy({
|
|
data: bytecode,
|
|
arguments: ["my string"]
|
|
})
|
|
.send({
|
|
from: "0x12598d2Fd88B420ED571beFDA8dD112624B5E730",
|
|
gas: 150000,
|
|
gasPrice: "30000000000000"
|
|
}), function(error, transactionHash){ ... })
|
|
.then(function(newContract){
|
|
console.log('new contract', newContract.options.address)
|
|
});
|
|
|
|
<span class="comment">// ethers
|
|
</span>const signer = provider.getSigner();
|
|
const factory = new ethers.ContractFactory(abi, bytecode, signer);
|
|
const contract = await factory.deploy("hello world");
|
|
console.log('contract address', contract.address);
|
|
|
|
<span class="comment">// wait for contract creation transaction to be mined
|
|
</span>await contract.deployTransaction.wait();
|
|
</div><a name="/v5/migration/web3/-%23-migration-from-web3-js--contracts--interacting-with-a-contract"></a><a name="/v5/migration/web3/"></a><h3 class="show-anchors"><div>Interacting with a Contract<div class="anchors"><a class="self" href="#/v5/migration/web3/-%23-migration-from-web3-js--contracts--interacting-with-a-contract"></a></div></div></h3>
|
|
<div class="code"><span class="comment">// web3
|
|
</span>const contract = new web3.eth.Contract(abi, contractAddress);
|
|
<span class="comment">// read only query
|
|
</span>contract.methods.getValue().call();
|
|
<span class="comment">// state changing operation
|
|
</span>contract.methods.changeValue(42).send({from: ....})
|
|
.on('receipt', function(){
|
|
...
|
|
});
|
|
|
|
<span class="comment">// ethers
|
|
</span><span class="comment">// pass a provider when initiating a contract for read only queries
|
|
</span>const contract = new ethers.Contract(contractAddress, abi, provider);
|
|
const value = await contract.getValue();
|
|
|
|
|
|
<span class="comment">// pass a signer to create a contract instance for state changing operations
|
|
</span>const contract = new ethers.Contract(contractAddress, abi, signer);
|
|
const tx = await contract.changeValue(33);
|
|
|
|
<span class="comment">// wait for the transaction to be mined
|
|
</span>const receipt = await tx.wait();
|
|
</div><a name="/v5/migration/web3/-%23-migration-from-web3-js--contracts--overloaded-functions"></a><a name="/v5/migration/web3/"></a><h3 class="show-anchors"><div>Overloaded Functions<div class="anchors"><a class="self" href="#/v5/migration/web3/-%23-migration-from-web3-js--contracts--overloaded-functions"></a></div></div></h3><p>Overloaded functions are functions that have the same name but different parameter types.</p>
|
|
|
|
<p>In ethers, the syntax to call an overloaded contract function is different from the non-overloaded function. This section shows the differences between web3 and ethers when calling overloaded functions.</p>
|
|
|
|
<p>See <a href="https://github.com/ethers-io/ethers.js/issues/407">issue #407</a> for more details.</p>
|
|
|
|
<div class="code"><span class="comment">// web3
|
|
</span>message = await contract.methods.getMessage('nice').call();
|
|
|
|
|
|
<span class="comment">// ethers
|
|
</span>const abi = [
|
|
"function getMessage(string) public view returns (string)",
|
|
"function getMessage() public view returns (string)"
|
|
]
|
|
const contract = new ethers.Contract(address, abi, signer);
|
|
|
|
<span class="comment">// for ambiguous functions (two functions with the same
|
|
</span><span class="comment">// name), the signature must also be specified
|
|
</span>message = await contract['getMessage(string)']('nice');
|
|
</div><a name="/v5/migration/web3/-%23-migration-from-web3-js--numbers"></a><a name="/v5/migration/web3/"></a><h2 class="show-anchors"><div>Numbers<div class="anchors"><a class="self" href="#/v5/migration/web3/-%23-migration-from-web3-js--numbers"></a></div></div></h2>
|
|
<a name="/v5/migration/web3/-%23-migration-from-web3-js--numbers--bignumber"></a><a name="/v5/migration/web3/"></a><h3 class="show-anchors"><div>BigNumber<div class="anchors"><a class="self" href="#/v5/migration/web3/-%23-migration-from-web3-js--numbers--bignumber"></a></div></div></h3><p>Convert to BigNumber:</p>
|
|
|
|
<div class="code"><span class="comment">// web3
|
|
</span>web3.utils.toBN('123456');
|
|
|
|
<span class="comment">// ethers (from a number; must be within safe range)
|
|
</span>ethers.BigNumber.from(123456)
|
|
|
|
<span class="comment">// ethers (from base-10 string)
|
|
</span>ethers.BigNumber.from("123456")
|
|
|
|
<span class="comment">// ethers (from hex string)
|
|
</span>ethers.BigNumber.from("0x1e240")
|
|
</div><a name="/v5/migration/web3/-%23-migration-from-web3-js--utilities"></a><a name="/v5/migration/web3/"></a><h2 class="show-anchors"><div>Utilities<div class="anchors"><a class="self" href="#/v5/migration/web3/-%23-migration-from-web3-js--utilities"></a></div></div></h2>
|
|
<a name="/v5/migration/web3/-%23-migration-from-web3-js--utilities--hash"></a><a name="/v5/migration/web3/"></a><h3 class="show-anchors"><div>Hash<div class="anchors"><a class="self" href="#/v5/migration/web3/-%23-migration-from-web3-js--utilities--hash"></a></div></div></h3><p>Computing Keccak256 hash of a UTF-8 string in web3 and ethers:</p>
|
|
|
|
<div class="code"><span class="comment">// web3
|
|
</span>web3.utils.sha3('hello world');
|
|
web3.utils.keccak256('hello world');
|
|
|
|
<span class="comment">// ethers (hash of a string)
|
|
</span>ethers.utils.id('hello world')
|
|
|
|
<span class="comment">// ethers (hash of binary data)
|
|
</span>ethers.utils.keccak256('0x4242')
|
|
</div><div class="page-separator"></div><a name="/v5/migration/ethers-v4/-%23-migration-v4"></a><a name="/v5/migration/ethers-v4/-%23-migration-v4"></a><a name="/v5/migration/ethers-v4/"></a><h1 class="show-anchors"><div>Migration: From Ethers v4<div class="anchors"><a class="self" href="#/v5/migration/ethers-v4/-%23-migration-v4"></a></div></div></h1><p>This document only covers the features present in v4 which have changed in some important way in v5.</p>
|
|
|
|
<p>It does not cover all the new additional features that have been added and mainly aims to help those updating their older scripts and applications to retain functional parity.</p>
|
|
|
|
<p>If you encounter any missing changes, please let me know and I'll update this guide.</p>
|
|
|
|
<a name="/v5/migration/ethers-v4/-%23-migration-v4--bignumber"></a><a name="/v5/migration/ethers-v4/"></a><h2 class="show-anchors"><div>BigNumber<div class="anchors"><a class="self" href="#/v5/migration/ethers-v4/-%23-migration-v4--bignumber"></a></div></div></h2>
|
|
<a name="/v5/migration/ethers-v4/-%23-migration-v4--bignumber--namespace"></a><a name="/v5/migration/ethers-v4/"></a><h3 class="show-anchors"><div>Namespace<div class="anchors"><a class="self" href="#/v5/migration/ethers-v4/-%23-migration-v4--bignumber--namespace"></a></div></div></h3><p>Since <a href="#/v5/api/utils/bignumber/">BigNumber</a> is used quite frequently, it has been moved to the top level of the umbrella package.</p>
|
|
|
|
<div class="code"><span class="comment">// v4
|
|
</span>ethers.utils.BigNumber
|
|
ethers.utils.BigNumberish
|
|
|
|
<span class="comment">// v5
|
|
</span>ethers.BigNumber
|
|
ethers.BigNumberish
|
|
</div><a name="/v5/migration/ethers-v4/-%23-migration-v4--bignumber--creating-instances"></a><a name="/v5/migration/ethers-v4/"></a><h3 class="show-anchors"><div>Creating Instances<div class="anchors"><a class="self" href="#/v5/migration/ethers-v4/-%23-migration-v4--bignumber--creating-instances"></a></div></div></h3><p>The <code class="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 <code class="inline">from</code> class method.</p>
|
|
|
|
<div class="code"><span class="comment">// v4
|
|
</span>new ethers.utils.BigNumber(someValue)
|
|
ethers.utils.bigNumberify(someValue);
|
|
|
|
<span class="comment">// v5
|
|
</span><span class="comment">// - Constructor is private
|
|
</span><span class="comment">// - Removed `bigNumberify`
|
|
</span>ethers.BigNumber.from(someValue)
|
|
</div><a name="/v5/migration/ethers-v4/-%23-migration-v4--contracts"></a><a name="/v5/migration/ethers-v4/"></a><h2 class="show-anchors"><div>Contracts<div class="anchors"><a class="self" href="#/v5/migration/ethers-v4/-%23-migration-v4--contracts"></a></div></div></h2>
|
|
<a name="/v5/migration/ethers-v4/-%23-migration-v4--contracts--ens-name-resolution"></a><a name="/v5/migration/ethers-v4/"></a><h3 class="show-anchors"><div>ENS Name Resolution<div class="anchors"><a class="self" href="#/v5/migration/ethers-v4/-%23-migration-v4--contracts--ens-name-resolution"></a></div></div></h3><p>The name of the resolved address has changed. If the address passed into the constructor was an ENS name, the address will be resolved before any calls are made to the contract.</p>
|
|
|
|
<p>The name of the property where the resolved address has changed from <code class="inline">addressPromise</code> to <code class="inline">resolvedAddress</code>.</p>
|
|
|
|
<div class="code-title"><div>Resolved ENS Names</div></div><div class="code"><span class="comment">// v4
|
|
</span>contract.addressPromise
|
|
|
|
<span class="comment">// v5
|
|
</span>contract.resolvedAddress
|
|
</div><a name="/v5/migration/ethers-v4/-%23-migration-v4--contracts--gas-estimation"></a><a name="/v5/migration/ethers-v4/"></a><h3 class="show-anchors"><div>Gas Estimation<div class="anchors"><a class="self" href="#/v5/migration/ethers-v4/-%23-migration-v4--contracts--gas-estimation"></a></div></div></h3><p>The only difference in gas estimation is that the bucket has changed its name from <code class="inline">estimate</code> to <code class="inline">estimateGas</code>.</p>
|
|
|
|
<div class="code-title"><div>Gas Estimation</div></div><div class="code"><span class="comment">// v4
|
|
</span>contract.estimate.transfer(toAddress, amount)
|
|
|
|
<span class="comment">// v5
|
|
</span>contract.estimateGas.transfer(toAddress, amount)
|
|
</div><a name="/v5/migration/ethers-v4/-%23-migration-v4--contracts--functions"></a><a name="/v5/migration/ethers-v4/"></a><h3 class="show-anchors"><div>Functions<div class="anchors"><a class="self" href="#/v5/migration/ethers-v4/-%23-migration-v4--contracts--functions"></a></div></div></h3><p>In a contract in ethers, there is a <code class="inline">functions</code> bucket, which exposes all the methods of a contract.</p>
|
|
|
|
<p>All these functions are available on the root contract itself as well and historically there was no difference between <code class="inline">contact.foo</code> and <code class="inline">contract.functions.foo</code>. The original reason for the <code class="inline">functions</code> bucket was to help when there were method names that collided with other buckets, which is rare.</p>
|
|
|
|
<p>In v5, the <code class="inline">functions</code> bucket is now intended to help with frameworks and for the new error recovery API, so most users should use the methods on the root contract.</p>
|
|
|
|
<p>The main difference will occur when a contract method only returns a single item. The root method will dereference this automatically while the <code class="inline">functions</code> bucket will preserve it as an <a href="#/v5/api/utils/abi/interface/-%23-Result">Result</a>.</p>
|
|
|
|
<p>If a method returns multiple items, there is no difference.</p>
|
|
|
|
<p>This helps when creating a framework, since the result will always be known to have the same number of components as the <a href="#/v5/api/utils/abi/fragments/-%23-Fragment">Fragment</a> outputs, without having to handle the special case of a single return value.</p>
|
|
|
|
<div class="code-title"><div>Functions Bucket</div></div><div class="code">const abi = [
|
|
|
|
<span class="comment"> // Returns a single value
|
|
</span> "function single() view returns (uint8)",
|
|
|
|
<span class="comment"> // Returns two values
|
|
</span> "function double() view returns (uint8, uint8)",
|
|
];
|
|
|
|
<span class="comment">// v4
|
|
</span>await contract.single()
|
|
<span class="comment">// 123
|
|
</span>await contract.functions.single()
|
|
<span class="comment">// 123
|
|
</span>
|
|
|
|
<span class="comment">// v5 (notice the change in the .function variant)
|
|
</span>await contract.single()
|
|
<span class="comment">// 123
|
|
</span>await contract.functions.single()
|
|
<span class="comment">// [ 123 ]
|
|
</span>
|
|
|
|
<span class="comment">// v4
|
|
</span>await contract.double()
|
|
<span class="comment">// [ 123, 5 ]
|
|
</span>await contract.functions.double()
|
|
<span class="comment">// [ 123, 5 ]
|
|
</span>
|
|
|
|
<span class="comment">// v5 (no difference from v4)
|
|
</span>await contract.double()
|
|
<span class="comment">// [ 123, 5 ]
|
|
</span>await contract.functions.double()
|
|
<span class="comment">// [ 123, 5 ]
|
|
</span></div><a name="/v5/migration/ethers-v4/-%23-migration-v4--errors"></a><a name="/v5/migration/ethers-v4/"></a><h2 class="show-anchors"><div>Errors<div class="anchors"><a class="self" href="#/v5/migration/ethers-v4/-%23-migration-v4--errors"></a></div></div></h2>
|
|
<a name="/v5/migration/ethers-v4/-%23-migration-v4--errors--namespace"></a><a name="/v5/migration/ethers-v4/"></a><h3 class="show-anchors"><div>Namespace<div class="anchors"><a class="self" href="#/v5/migration/ethers-v4/-%23-migration-v4--errors--namespace"></a></div></div></h3><p>All errors now belong to the <a href="#/v5/api/utils/logger/-%23-Logger">Logger</a> class and the related functions have been moved to <a href="#/v5/api/utils/logger/-%23-Logger">Logger</a> instances, which can include a per-package version string.</p>
|
|
|
|
<p>Global error functions have been moved to <a href="#/v5/api/utils/logger/-%23-Logger">Logger</a> class methods.</p>
|
|
|
|
<div class="code"><span class="comment">// v4
|
|
</span>ethers.errors.UNKNOWN_ERROR
|
|
ethers.errors.*
|
|
|
|
errors.setCensorship(censorship, permanent)
|
|
errors.setLogLevel(logLevel)
|
|
|
|
errors.checkArgumentCount(count, expectedCount, suffix)
|
|
errors.checkNew(self, kind)
|
|
errors.checkNormalize()
|
|
errors.throwError(message, code, params)
|
|
errors.warn(...)
|
|
errors.info(...)
|
|
|
|
<span class="comment">// v5
|
|
</span>ethers.utils.Logger.errors.UNKNOWN_ERROR
|
|
ethers.utils.Logger.errors.*
|
|
|
|
Logger.setCensorship(censorship, permanent)
|
|
Logger.setLogLevel(logLevel)
|
|
|
|
const logger = new ethers.utils.Logger(version);
|
|
logger.checkArgumentCount(count, expectedCount, suffix)
|
|
logger.checkNew(self, kind)
|
|
logger.checkNormalize()
|
|
logger.throwError(message, code, params)
|
|
logger.warn(...)
|
|
logger.info(...)
|
|
</div><a name="/v5/migration/ethers-v4/-%23-migration-v4--interface"></a><a name="/v5/migration/ethers-v4/"></a><h2 class="show-anchors"><div>Interface<div class="anchors"><a class="self" href="#/v5/migration/ethers-v4/-%23-migration-v4--interface"></a></div></div></h2><p>The <a href="#/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>
|
|
|
|
<a name="/v5/migration/ethers-v4/-%23-migration-v4--interface--functions"></a><a name="/v5/migration/ethers-v4/"></a><h3 class="show-anchors"><div>Functions<div class="anchors"><a class="self" href="#/v5/migration/ethers-v4/-%23-migration-v4--interface--functions"></a></div></div></h3>
|
|
<div class="code"><span class="comment">// v4 (example: "transfer(address to, uint amount)")
|
|
</span>interface.functions.transfer.encode(to, amount)
|
|
interface.functions.transfer.decode(callData)
|
|
|
|
<span class="comment">// v5
|
|
</span>interface.encodeFunctionData("transfer", [ to, amount ])
|
|
interface.decodeFunctionResult("transfer", data)
|
|
|
|
<span class="comment">// Or you can use any compatible signature or Fragment objects.
|
|
</span><span class="comment">// Notice that signature normalization is performed for you,
|
|
</span><span class="comment">// e.g. "uint" and "uint256" will be automatically converted
|
|
</span>interface.encodeFunctionData("transfer(address,uint)", [ to, amount ])
|
|
interface.decodeFunctionResult("transfer(address to, uint256 amount)", data)
|
|
</div><a name="/v5/migration/ethers-v4/-%23-migration-v4--interface--events"></a><a name="/v5/migration/ethers-v4/"></a><h3 class="show-anchors"><div>Events<div class="anchors"><a class="self" href="#/v5/migration/ethers-v4/-%23-migration-v4--interface--events"></a></div></div></h3>
|
|
<div class="code"><span class="comment">// v4 (example: Transfer(address indexed, address indexed, uint256)
|
|
</span>interface.events.Transfer.encodeTopics(values)
|
|
interface.events.Transfer.decode(data, topics)
|
|
|
|
<span class="comment">// v5
|
|
</span>interface.encodeFilterTopics("Transfer", values)
|
|
interface.decodeEventLog("Transfer", data, topics)
|
|
</div><a name="/v5/migration/ethers-v4/-%23-migration-v4--interface--inspection"></a><a name="/v5/migration/ethers-v4/"></a><h3 class="show-anchors"><div>Inspection<div class="anchors"><a class="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 <a href="#/v5/api/utils/abi/fragments/-%23-Fragment">Fragment</a> object.</p>
|
|
|
|
<div class="code">// v4
|
|
interface.functions.transfer.name
|
|
interface.functions.transfer.inputs
|
|
interface.functions.transfer.outputs
|
|
interface.functions.transfer.payable
|
|
interface.functions.transfer.gas
|
|
|
|
// v5
|
|
const functionFragment = interface.getFunction("transfer")
|
|
functionFragment.name
|
|
functionFragment.inputs
|
|
functionFragment.outputs
|
|
functionFragment.payable
|
|
functionFragment.gas
|
|
|
|
|
|
// v4; type is "call" or "transaction"
|
|
interface.functions.transfer.type
|
|
|
|
// v5; constant is true (i.e. "call") or false (i.e. "transaction")
|
|
functionFragment.constant
|
|
|
|
|
|
// v4
|
|
interface.events.Transfer.anonymous
|
|
interface.events.Transfer.inputs
|
|
interface.events.Transfer.name
|
|
|
|
// v5
|
|
const eventFragment = interface.getEvent("Transfer");
|
|
eventFragment.anonymous
|
|
eventFragment.inputs
|
|
eventFragment.name
|
|
|
|
|
|
// v4
|
|
const functionSig = interface.functions.transfer.signature
|
|
const sighash = interface.functions.transfer.sighash
|
|
|
|
const eventSig = interface.events.Transfer.signature
|
|
const topic = interface.events.Transfer.topic
|
|
|
|
// v5
|
|
const functionSig = functionFragment.format()
|
|
const sighash = interface.getSighash(functionFragment)
|
|
|
|
const eventSig = eventFragment.format()
|
|
const topic = interface.getTopic(eventFragment)</div><a name="/v5/migration/ethers-v4/-%23-migration-v4--wallet"></a><a name="/v5/migration/ethers-v4/"></a><h2 class="show-anchors"><div>Wallet<div class="anchors"><a class="self" href="#/v5/migration/ethers-v4/-%23-migration-v4--wallet"></a></div></div></h2>
|
|
<a name="/v5/migration/ethers-v4/-%23-migration-v4--wallet--mnemonic-phrases"></a><a name="/v5/migration/ethers-v4/"></a><h3 class="show-anchors"><div>Mnemonic Phrases<div class="anchors"><a class="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 <code class="inline">mnemonic</code> object, which also now includes the <code class="inline">locale</code>.</p>
|
|
|
|
<div class="code"><span class="comment">// v4
|
|
</span>wallet.mnemonic
|
|
wallet.path
|
|
|
|
<span class="comment">// v5
|
|
</span><span class="comment">// - Mnemonic phrase and path are a Mnemonic object
|
|
</span><span class="comment">// - Note: wallet.mnemonic is null if there is no mnemonic
|
|
</span>wallet.mnemonic.phrase
|
|
wallet.mnemonic.path
|
|
</div><div class="page-separator"></div><a name="/v5/testing/-%23-testing"></a><a name="/v5/testing/"></a><h1 class="show-anchors"><div>Testing<div class="anchors"><a class="self" href="#/v5/testing/-%23-testing"></a></div></div></h1><p>Testing is a critical part of any library which wishes to remain secure, safe and reliable.</p>
|
|
|
|
<p>Ethers currently has <b>over 23k tests</b> among its test suites, which are all made available for other projects to use as simple exported GZIP-JSON files.</p>
|
|
|
|
<p>The tests are run on every check-in and the results can been seen on the <a href="https://github.com/ethers-io/ethers.js/actions/runs/158006903">GitHub CI Action</a>.</p>
|
|
|
|
<p>We also strive to constantly add new test cases, especially when issues arise to ensure the issue is present prior to the fix, corrected after the fix and included to prevent future changes from causing a regression.</p>
|
|
|
|
<p>A large number of the test cases were created procedurally by using known correct implementations from various sources (such as Geth) and written in different languages and verified with multiple libraries.</p>
|
|
|
|
<p>For example, the ABI test suites were generated by procedurally generating a list of types, for each type choosing a random (valid) value, which then was converted into a Solidity source file, compiled using <code class="inline">solc</code> and deployed to a running Parity node and executed, with its outputs being captured. Similar to the how many of the hashing, event and selector test cases were created.</p>
|
|
|
|
<a name="/v5/testing/-%23-testing-supported"></a><a name="/v5/testing/-%23-testing--testing-supported"></a><a name="/v5/testing/"></a><h2 class="show-anchors"><div>Supported Platforms<div class="anchors"><a class="self" href="#/v5/testing/-%23-testing-supported"></a></div></div></h2><p>While web technologies move quite fast, especially in the Web3 universe, we try to keep ethers as accessible as possible.</p>
|
|
|
|
<p>Currently ethers should work on almost any ES3 or better environment and tests are run against:</p>
|
|
|
|
<p><ul><li>node.js 8.x </li><li>node.js 10.x </li><li>node.js 12.x </li><li>node.js 13.x </li><li>Web Browsers (using UMD) </li><li>Web Browsers (using ES modules) </li></ul></p>
|
|
|
|
<p>If there is an environment you feel has been overlooked or have suggestions, please feel free to reach out by opening an <a href="https://github.com/ethers-io/ethers.js/issues">issue on Github</a>.</p>
|
|
|
|
<p>We would like to add a test build for Expo and React as those developers often seem to encounter pain points when using ethers, so if you have experience or ideas on this, <a href="https://github.com/ethers-io/ethers.js/issues">bug us</a>.</p>
|
|
|
|
<p>The next Major version (probably summer 2021) will likely drop support for node 8.x and will require ES2015 for <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy">Proxy</a>.</p>
|
|
|
|
<p>Certain features in JavaScript are also avoided, such as look-behind tokens in regular expressions, since these have caused conflicts (at import time) with certain JavaScript environments such as <a href="https://github.com/robertkrimen/otto">Otto</a>.</p>
|
|
|
|
<p>Basically, the moral of the story is "be inclusive and don't drop people needlessly".</p>
|
|
|
|
<a name="/v5/testing/-%23-testing-suites"></a><a name="/v5/testing/-%23-testing--testing-suites"></a><a name="/v5/testing/"></a><h2 class="show-anchors"><div>Test Suites<div class="anchors"><a class="self" href="#/v5/testing/-%23-testing-suites"></a></div></div></h2><p>The test suites are available as gzipped JSON files in the <code class="inline">@ethersproject/testcases</code>, which makes it easy to install and import (both GZIP and JSON are quite easy to consume from most languages). Each test suite also has its schema available in this package.</p>
|
|
|
|
<table class="table full"><tr><td align="center" width="34%"><b>Filename</b></td><td align="center" colspan="2" width="66%"><b>Test Cases</b></td><td class="fix"> </td></tr><tr><td align="left" width="34%">accounts.json.gz</td><td align="left" colspan="2" width="66%">Private Keys and addresses in checksum and ICAP formats</td><td class="fix"> </td></tr><tr><td align="left" width="34%">contract-events.json.gz</td><td align="left" colspan="2" width="66%">Compiled Solidity, ABI interfaces, input types/values with the output types/values for emitted events; all tests were executed against real Ethereum nodes</td><td class="fix"> </td></tr><tr><td align="left" width="34%">contract-interface.json.gz</td><td align="left" colspan="2" width="66%">Compiled Solidity, ABI interfaces, input types/values with the output types/values, encoded and decoded binary data and normalized values for function calls executed against real Ethereum nodes.</td><td class="fix"> </td></tr><tr><td align="left" width="34%">contract-interface-abi2.json.gz</td><td align="left" colspan="2" width="66%">Identical to <code class="inline">contract-interface</code>, except with emphasis on the ABIv2 coder which supports nested dynami types and structured data</td><td class="fix"> </td></tr><tr><td align="left" width="34%">contract-signatures.json.gz</td><td align="left" colspan="2" width="66%">Contract signatures and matching selectors</td><td class="fix"> </td></tr><tr><td align="left" width="34%">hashes.json.gz</td><td align="left" colspan="2" width="66%">Data and respective hashes against a variety of hash functions</td><td class="fix"> </td></tr><tr><td align="left" width="34%">hdnode.json.gz</td><td align="left" colspan="2" width="66%">HDNodes (BIP-32) with mnemonics, entropy, seed and computed nodes with pathes and addresses</td><td class="fix"> </td></tr><tr><td align="left" width="34%">namehash.json.gz</td><td align="left" colspan="2" width="66%">ENS names along with computed [namehashes](link-namehash</td><td class="fix"> </td></tr><tr><td align="left" width="34%">nameprep.json.gz</td><td align="left" colspan="2" width="66%">IDNA and Nameprep representations including official vectors</td><td class="fix"> </td></tr><tr><td align="left" width="34%">rlp-coder.json.gz</td><td align="left" colspan="2" width="66%">Recursive-Length Prefix (RLP) data and encodings</td><td class="fix"> </td></tr><tr><td align="left" width="34%">solidity-hashes.json.gz</td><td align="left" colspan="2" width="66%">Hashes based on the Solidity non-standard packed form</td><td class="fix"> </td></tr><tr><td align="left" width="34%">transactions.json.gz</td><td align="left" colspan="2" width="66%">Signed and unsigned transactions with their serialized formats including both with and without EIP-155 replay protection</td><td class="fix"> </td></tr><tr><td align="left" width="34%">units.json.gz</td><td align="left" colspan="2" width="66%">Values converted between various units</td><td class="fix"> </td></tr><tr><td align="left" width="34%">wallets.json.gz</td><td align="left" colspan="2" width="66%">Keystore JSON format wallets, passwords and decrypted values</td><td class="fix"> </td></tr><tr><td align="left" width="34%">wordlists.json.gz</td><td align="left" colspan="2" width="66%">Fully decompressed BIP-39 official wordlists</td><td class="fix"> </td></tr><tr><td class="table-title" colspan="3">Test Suites</td><td class="fix"> </td></tr></table><a name="/v5/testing/-%23-testing-api"></a><a name="/v5/testing/-%23-testing--testing-api"></a><a name="/v5/testing/"></a><h2 class="show-anchors"><div>Test Suite API<div class="anchors"><a class="self" href="#/v5/testing/-%23-testing-api"></a></div></div></h2><p>There are also convenience functions for those developing directly in TypeScript.</p>
|
|
|
|
<div class="property show-anchors"><div class="signature"><span class="path">testcases</span><span class="symbol">.</span><span class="method">loadTests</span><span class="symbol">(</span> <span class="param">tag</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Array< TestCase ></span><div class="anchors"></div></div><div class="body"><p>Load all the given testcases for the <i>tag</i>.</p>
|
|
|
|
<p>A tag is the string in the above list of test case names not including any extension (e.g. <code class="inline">"solidity-hashes"</code>)</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">testcases</span><span class="symbol">.</span><span class="path">TestCase</span><span class="symbol">.</span><span class="method">TEST_NAME</span><div class="anchors"></div></div><div class="body"><p>Most testcases have its schema available as a TypeScript type to make testing each property easier.</p>
|
|
|
|
</div></div><a name="/v5/testing/-%23-testing--testing-api--deterministic-random-numbers-drng"></a><a name="/v5/testing/"></a><h3 class="show-anchors"><div>Deterministic Random Numbers (DRNG)<div class="anchors"><a class="self" href="#/v5/testing/-%23-testing--testing-api--deterministic-random-numbers-drng"></a></div></div></h3><p>When creating test cases, often we want want random data from the perspective we do not case what values are used, however we want the values to be consistent across runs. Otherwise it becomes difficult to reproduce an issue.</p>
|
|
|
|
<p>In each of the following the seed is used to control the random value returned. Be sure to tweak the seed properly, for example on each iteration change the value and in recursive functions, concatenate to the seed.</p>
|
|
|
|
<div class="property show-anchors"><div class="signature"><span class="path">testcases</span><span class="symbol">.</span><span class="method">randomBytes</span><span class="symbol">(</span> <span class="param">seed</span> <span class="symbol">,</span> <span class="param">lower</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">upper</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">Uint8Array</span><div class="anchors"></div></div><div class="body"><p>Return at least <i>lower</i> random bytes, up to <i>upper</i> (exclusive) if specified, given <i>seed</i>. If <i>upper</i> is omitted, exactly <i>/lower</i> bytes are returned.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">testcases</span><span class="symbol">.</span><span class="method">randomHexString</span><span class="symbol">(</span> <span class="param">seed</span> <span class="symbol">,</span> <span class="param">lower</span> <span class="symbol">[</span> <span class="symbol">,</span> <span class="param">upper</span> <span class="symbol">]</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">string< <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a> ></span><div class="anchors"></div></div><div class="body"><p>Identical to randomBytes, except returns the value as a <a href="#/v5/api/utils/bytes/-%23-DataHexString">DataHexString</a> instead of a Uint8Array.</p>
|
|
|
|
</div></div><div class="property show-anchors"><div class="signature"><span class="path">testcases</span><span class="symbol">.</span><span class="method">randomNumber</span><span class="symbol">(</span> <span class="param">seed</span> <span class="symbol">,</span> <span class="param">lower</span> <span class="symbol">,</span> <span class="param">upper</span> <span class="symbol">)</span> <span class="arrow">⇒</span> <span class="returns">number</span><div class="anchors"></div></div><div class="body"><p>Returns a random number of at least <i>lower</i> and less than <i>upper</i> given <i>seed</i>.</p>
|
|
|
|
</div></div><a name="/v5/testing/-%23-testing-schemas"></a><a name="/v5/testing/-%23-testing--testing-schemas"></a><a name="/v5/testing/"></a><h2 class="show-anchors"><div>Schemas<div class="anchors"><a class="self" href="#/v5/testing/-%23-testing-schemas"></a></div></div></h2><p>This section is still a work in progress, but will outline some of the more nuanced aspects of the test cases and their values.</p>
|
|
|
|
<p>There will likely be an overhaul of the test cases in the next major version, to make code coverage testing more straight forward and to collapse some of the redundancy.</p>
|
|
|
|
<p>For example, there is no longer a need to separate the ABI and ABIv2 test case and the accounts and transactions suites can be merged into one large collection.</p>
|
|
|
|
<a name="/v5/testing/-%23-testing--testing-schemas--accounts"></a><a name="/v5/testing/"></a><h3 class="show-anchors"><div>Accounts<div class="anchors"><a class="self" href="#/v5/testing/-%23-testing--testing-schemas--accounts"></a></div></div></h3><p>Basic account information using a private key and computing various address forms.</p>
|
|
|
|
<p>Tests were verified against [EthereumJS](https://github.com/ethereumjs) and custom scripts created to directly interact with Geth and cpp implementations.</p>
|
|
|
|
<p><i>See: <code class="inline">accounts.json.gz</code></i></p>
|
|
|
|
<table class="table minimal"><tr><td align="center"><b>Property</b></td><td align="center"><b>Meaning</b></td><td class="fix"> </td></tr><tr><td align="center">name</td><td align="center">The testcase name</td><td class="fix"> </td></tr><tr><td align="center">privateKey</td><td align="center">The private key</td><td class="fix"> </td></tr><tr><td align="center">address</td><td align="center">The address (lowercase)</td><td class="fix"> </td></tr><tr><td align="center">checksumAddress</td><td align="center">The address with checksum-adjusted case</td><td class="fix"> </td></tr><tr><td align="center">icapAddress</td><td align="center">The ICAP address</td><td class="fix"> </td></tr><tr><td class="table-title" colspan="2">Properties</td><td class="fix"> </td></tr></table><div class="code-title"><div>Example</div></div><div class="code">{
|
|
"name": "random-1023",
|
|
"address": "0x53bff74b9af2e3853f758a8d2bd61cd115d27782",
|
|
"privateKey": "0x8ab0e165c2ea461b01cdd49aec882d179dccdbdb5c85c3f9c94c448aa65c5ace",
|
|
"checksumAddress": "0x53bFf74b9Af2E3853f758A8D2Bd61CD115d27782",
|
|
"icapAddress": "XE709S6NUSJR6SXQERCMYENAYYOZ2Y91M6A"
|
|
}
|
|
</div><a name="/v5/testing/-%23-testing--testing-schemas--contract-interface"></a><a name="/v5/testing/"></a><h3 class="show-anchors"><div>Contract Interface<div class="anchors"><a class="self" href="#/v5/testing/-%23-testing--testing-schemas--contract-interface"></a></div></div></h3><p>Procedurally generated test cases to test ABI coding.</p>
|
|
|
|
<div class="code-title"><div>Example</div></div><div class="code">{
|
|
"name": "random-1999",
|
|
"source": "contract Test {\n function test() constant returns (address, bool, bytes14[1]) {\n address a = address(0x061C7F399Ee738c97C7b7cD840892B281bf772B5);\n bool b = bool(true);\n bytes14[1] memory c;\n c[0] = bytes14(0x327621c4abe12d4f21804ed40455);\n return (a, b, c);\n }\n}\n",
|
|
"types": "[\"address\",\"bool\",\"bytes14[1]\"]",
|
|
"interface": "[{\"constant\":true,\"inputs\":[],\"name\":\"test\",\"outputs\":[{\"name\":\"\",\"type\":\"address\"},{\"name\":\"\",\"type\":\"bool\"},{\"name\":\"\",\"type\":\"bytes14[1]\"}],\"type\":\"function\"}]\n",
|
|
"bytecode": "0x6060604052610175806100126000396000f360606040526000357c010000000000000000000000000000000000000000000000000000000090048063f8a8fd6d1461003957610037565b005b610046600480505061009d565b604051808473ffffffffffffffffffffffffffffffffffffffff1681526020018315158152602001826001602002808383829060006004602084601f0104600f02600301f150905001935050505060405180910390f35b600060006020604051908101604052806001905b60008152602001906001900390816100b157905050600060006020604051908101604052806001905b60008152602001906001900390816100da5790505073061c7f399ee738c97c7b7cd840892b281bf772b59250600191506d327621c4abe12d4f21804ed404557201000000000000000000000000000000000000028160006001811015610002579090602002019071ffffffffffffffffffffffffffffffffffff191690818152602001505082828295509550955061016d565b50505090919256",
|
|
"result": "0x000000000000000000000000061c7f399ee738c97c7b7cd840892b281bf772b50000000000000000000000000000000000000000000000000000000000000001327621c4abe12d4f21804ed40455000000000000000000000000000000000000",
|
|
"values": "[{\"type\":\"string\",\"value\":\"0x061C7F399Ee738c97C7b7cD840892B281bf772B5\"},{\"type\":\"boolean\",\"value\":true},[{\"type\":\"buffer\",\"value\":\"0x327621c4abe12d4f21804ed40455\"}]]",
|
|
"normalizedValues": "[{\"type\":\"string\",\"value\":\"0x061C7F399Ee738c97C7b7cD840892B281bf772B5\"},{\"type\":\"boolean\",\"value\":true},[{\"type\":\"buffer\",\"value\":\"0x327621c4abe12d4f21804ed40455\"}]]",
|
|
"runtimeBytecode": "0x60606040526000357c010000000000000000000000000000000000000000000000000000000090048063f8a8fd6d1461003957610037565b005b610046600480505061009d565b604051808473ffffffffffffffffffffffffffffffffffffffff1681526020018315158152602001826001602002808383829060006004602084601f0104600f02600301f150905001935050505060405180910390f35b600060006020604051908101604052806001905b60008152602001906001900390816100b157905050600060006020604051908101604052806001905b60008152602001906001900390816100da5790505073061c7f399ee738c97c7b7cd840892b281bf772b59250600191506d327621c4abe12d4f21804ed404557201000000000000000000000000000000000000028160006001811015610002579090602002019071ffffffffffffffffffffffffffffffffffff191690818152602001505082828295509550955061016d565b50505090919256"
|
|
}
|
|
</div><a name="/v5/testing/-%23-testing--testing-schemas--contract-signatures"></a><a name="/v5/testing/"></a><h3 class="show-anchors"><div>Contract Signatures<div class="anchors"><a class="self" href="#/v5/testing/-%23-testing--testing-schemas--contract-signatures"></a></div></div></h3><p>Computed ABI signatures and the selector hash.</p>
|
|
|
|
<div class="code-title"><div>Example</div></div><div class="code">{
|
|
"name": "random-1999",
|
|
"sigHash": "0xf51e9244",
|
|
"abi": "[{\"constant\":false,\"inputs\":[{\"name\":\"r0\",\"type\":\"string[2]\"},{\"name\":\"r1\",\"type\":\"uint128\"},{\"components\":[{\"name\":\"a\",\"type\":\"bytes\"},{\"name\":\"b\",\"type\":\"bytes\"},{\"name\":\"c\",\"type\":\"bytes\"}],\"name\":\"r2\",\"type\":\"tuple\"},{\"name\":\"r3\",\"type\":\"bytes\"}],\"name\":\"testSig\",\"outputs\":[],\"payable\":false,\"stateMutability\":\"nonpayable\",\"type\":\"function\"},{\"constant\":true,\"inputs\":[],\"name\":\"test\",\"outputs\":[{\"name\":\"r0\",\"type\":\"string[2]\"},{\"name\":\"r1\",\"type\":\"uint128\"},{\"components\":[{\"name\":\"a\",\"type\":\"bytes\"},{\"name\":\"b\",\"type\":\"bytes\"},{\"name\":\"c\",\"type\":\"bytes\"}],\"name\":\"r2\",\"type\":\"tuple\"},{\"name\":\"r3\",\"type\":\"bytes\"}],\"payable\":false,\"stateMutability\":\"pure\",\"type\":\"function\"}]",
|
|
"signature": "testSig(string[2],uint128,(bytes,bytes,bytes),bytes)"
|
|
}
|
|
</div><a name="/v5/testing/-%23-testing--testing-schemas--hashes"></a><a name="/v5/testing/"></a><h3 class="show-anchors"><div>Hashes<div class="anchors"><a class="self" href="#/v5/testing/-%23-testing--testing-schemas--hashes"></a></div></div></h3>
|
|
<div class="code-title"><div>Examples</div></div><div class="code">{
|
|
"data": "0x3718a88ceb214c1480c32a9d",
|
|
"keccak256": "0x82d7d2dc3d384ddb289f41917b8280675bb1283f4fe2b601ac7c8f0a2c2824fa",
|
|
"sha512": "0xe93462bb1de62ba3e6a980c3cb0b61728d3f771cea9680b0fa947b6f8fb2198a2690a3a837495c753b57f936401258dfe333a819e85f958b7d786fb9ab2b066c",
|
|
"sha256": "0xe761d897e667aa72141dd729264c393c4ddda5c62312bbd21b0f4d954eba1a8d"
|
|
}
|
|
</div><a name="/v5/testing/-%23-testing--testing-schemas--hierarchal-deterministic-node-bip-32"></a><a name="/v5/testing/"></a><h3 class="show-anchors"><div>Hierarchal Deterministic Node (BIP-32)<div class="anchors"><a class="self" href="#/v5/testing/-%23-testing--testing-schemas--hierarchal-deterministic-node-bip-32"></a></div></div></h3><p>Tests for <a href="https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki">BIP-32</a> HD Wallets.</p>
|
|
|
|
<div class="code-title"><div>Example</div></div><div class="code">{
|
|
"name": "trezor-23",
|
|
"entropy": "0xf585c11aec520db57dd353c69554b21a89b20fb0650966fa0a9d6f74fd989d8f",
|
|
"mnemonic": "void come effort suffer camp survey warrior heavy shoot primary clutch crush open amazing screen patrol group space point ten exist slush involve unfold",
|
|
"locale": "en",
|
|
"password": "TREZOR",
|
|
"hdnodes": [
|
|
{
|
|
"path": "m",
|
|
"address": "0xfd8eb95169ce57eab52fb69bc6922e9b6454d9aa",
|
|
"privateKey": "0x679bf92c04cf16307053cbed33784f3c4266b362bf5f3d7ee13bed6f2719743c"
|
|
},
|
|
{
|
|
"address": "0xada964e9f10c4fc9787f9e17f00c63fe188722b0",
|
|
"privateKey": "0xdcbcb48a2b11eef0aab93a8f88d83f60a3aaabb34f9ffdbe939b8f059b30f2b7",
|
|
"path": "m/8'/8'/2/3/4"
|
|
},
|
|
{
|
|
"privateKey": "0x10fd3776145dbeccb3d6925e4fdc0d58b452fce40cb8760b12f8b4223fafdfa6",
|
|
"address": "0xf3f6b1ef343d5f5f231a2287e801a46add43eb06",
|
|
"path": "m/1'/3'"
|
|
},
|
|
{
|
|
"address": "0xb7b0fdb6e0f79f0529e95400903321e8a601b411",
|
|
"privateKey": "0x093a8ff506c95a2b79d397aed59703f6212ff3084731c2f03089b069ae76e69d",
|
|
"path": "m/8'/4'/7'"
|
|
},
|
|
{
|
|
"path": "m/7'/5'/11",
|
|
"privateKey": "0x6bd79da4dfa7dd0abf566a011bdb7cba0d28bba9ca249ba25880d5dabf861b42",
|
|
"address": "0x1b3ad5fa50ae32875748107f4b2160829cc10536"
|
|
},
|
|
{
|
|
"path": "m/9'/6'/2'/7'/3'",
|
|
"address": "0x42eb4bed59f3291d02387cf0fb23098c55d82611",
|
|
"privateKey": "0xfc173acba7bc8bb2c434965d9e99f5a221f81add421bae96a891d08d60be11dd"
|
|
}
|
|
],
|
|
"seed": "0x01f5bced59dec48e362f2c45b5de68b9fd6c92c6634f44d6d40aab69056506f0e35524a518034ddc1192e1dacd32c1ed3eaa3c3b131c88ed8e7e54c49a5d0998"
|
|
}
|
|
</div><a name="/v5/testing/-%23-testing--testing-schemas--ens-namehash"></a><a name="/v5/testing/"></a><h3 class="show-anchors"><div>ENS Namehash<div class="anchors"><a class="self" href="#/v5/testing/-%23-testing--testing-schemas--ens-namehash"></a></div></div></h3><p>Test cases for the <a href="https://docs.ens.domains/contract-api-reference/name-processing#hashing-names">ENS Namehash Algorithm</a>.</p>
|
|
|
|
<div class="code-title"><div>Examples</div></div><div class="code">{
|
|
"expected": "0x33868cc5c3fd3a9cd3adbc1e868ea133d2218f60dc2660c3bc48d8b1f4961384",
|
|
"name": "ViTalIk.WALlet.Eth",
|
|
"test": "mixed case"
|
|
}</div><a name="/v5/testing/-%23-testing--testing-schemas--rlp-coder"></a><a name="/v5/testing/"></a><h3 class="show-anchors"><div>RLP Coder<div class="anchors"><a class="self" href="#/v5/testing/-%23-testing--testing-schemas--rlp-coder"></a></div></div></h3>
|
|
<div class="code-title"><div>Examples</div></div><div class="code">{
|
|
"name": "arrayWithNullString3",
|
|
"encoded": "0xc3808080",
|
|
"decoded": [ "0x", "0x", "0x" ]
|
|
}
|
|
</div><a name="/v5/testing/-%23-testing--testing-schemas--solidity-hashes"></a><a name="/v5/testing/"></a><h3 class="show-anchors"><div>Solidity Hashes<div class="anchors"><a class="self" href="#/v5/testing/-%23-testing--testing-schemas--solidity-hashes"></a></div></div></h3><p>Tests for the non-standard packed form of the Solidity hash functions.</p>
|
|
|
|
<p>These tests were created by procedurally generating random signatures and values that match those signatures, constructing the equivalent Soldity, compiling it and deploying it to a Parity node then evaluating the response.</p>
|
|
|
|
<div class="code-title"><div>Example</div></div><div class="code">{
|
|
"name": "random-1999",
|
|
"keccak256": "0x7d98f1144a0cd689f720aa2f11f0a73bd52a2da1117175bc4bacd93c130966a1",
|
|
"ripemd160": "0x59384617f8a06efd57ab106c9e0c20c3e64137ac000000000000000000000000",
|
|
"sha256": "0xf9aeea729ff39f8d372d8552bca81eb2a3c5d433dc8f98140040a03b7d81ac92",
|
|
"values": [
|
|
"0xcdffcb5242e6",
|
|
"0xc1e101b60ebe4688",
|
|
"0x5819f0ef5537796e43bdcd48309f717d6f7ccffa",
|
|
"0xec3f3f9f",
|
|
false,
|
|
true
|
|
],
|
|
"types": [
|
|
"int184",
|
|
"int176",
|
|
"address",
|
|
"int64",
|
|
"bool",
|
|
"bool"
|
|
]
|
|
}
|
|
</div><a name="/v5/testing/-%23-testing--testing-schemas--transactions"></a><a name="/v5/testing/"></a><h3 class="show-anchors"><div>Transactions<div class="anchors"><a class="self" href="#/v5/testing/-%23-testing--testing-schemas--transactions"></a></div></div></h3><p>Serialized signed and unsigned transactions with both EIP-155 enabled and disabled.</p>
|
|
|
|
<div class="code-title"><div>Examples</div></div><div class="code">{
|
|
"name": "random-998",
|
|
"privateKey": "0xd16c8076a15f7fb583f05dc12686fe526bc59d298f1eb7b9a237b458133d1dec",
|
|
"signedTransactionChainId5": "0xf8708391d450848517cfba8736fcf36da03ee4949577303fd4e0acbe72c6c116acab5bf63f0b1e9c8365fdc7827dc82ea059891894eb180cb7c6c45a52f62d2103420d3ad0bc3ba518d0a25ed910842522a0155c0ea2aee2ea82e75843aab297420bad907d46809d046b13d692928f4d78aa",
|
|
"gasLimit": "0x36fcf36da03ee4",
|
|
"to": "0x9577303fd4e0acbe72c6c116acab5bf63f0b1e9c",
|
|
"data": "0x7dc8",
|
|
"accountAddress": "0x6d4a6aff30ca5ca4b8422eea0ebcb669c7d79859",
|
|
"unsignedTransaction": "0xed8391d450848517cfba8736fcf36da03ee4949577303fd4e0acbe72c6c116acab5bf63f0b1e9c8365fdc7827dc8",
|
|
"nonce": "0x91d450",
|
|
"gasPrice": "0x8517cfba",
|
|
"signedTransaction": "0xf8708391d450848517cfba8736fcf36da03ee4949577303fd4e0acbe72c6c116acab5bf63f0b1e9c8365fdc7827dc81ba05030832331e6be48c95e1569a1ca9505c495486f72d6009b3a30fadfa05d9686a05cd3116b416d2362da1e9b0ca7fb1856c4e591cc22e63b395bd881ce2d3735e6",
|
|
"unsignedTransactionChainId5": "0xf08391d450848517cfba8736fcf36da03ee4949577303fd4e0acbe72c6c116acab5bf63f0b1e9c8365fdc7827dc8058080",
|
|
"value": "0x65fdc7"
|
|
}
|
|
</div><a name="/v5/testing/-%23-testing--testing-schemas--units"></a><a name="/v5/testing/"></a><h3 class="show-anchors"><div>Units<div class="anchors"><a class="self" href="#/v5/testing/-%23-testing--testing-schemas--units"></a></div></div></h3><p>Unit conversion.</p>
|
|
|
|
<div class="code-title"><div>Example</div></div><div class="code">{
|
|
"name": "one-two-three-3",
|
|
"gwei_format": "-1234567890123456.789012345",
|
|
"ether_format": "-1234567.890123456789012345",
|
|
"gwei": "-1234567890123456.789012345",
|
|
"ether": "-1234567.890123456789012345",
|
|
"finney": "-1234567890.123456789012345",
|
|
"wei": "-1234567890123456789012345",
|
|
"finney_format": "-1234567890.123456789012345"
|
|
}
|
|
</div><a name="/v5/testing/-%23-testing--testing-schemas--wallets"></a><a name="/v5/testing/"></a><h3 class="show-anchors"><div>Wallets<div class="anchors"><a class="self" href="#/v5/testing/-%23-testing--testing-schemas--wallets"></a></div></div></h3><p>Tests for the JSON keystore format.</p>
|
|
|
|
<div class="code-title"><div>Example</div></div><div class="code">{
|
|
"mnemonic": null,
|
|
"name": "secretstorage_password",
|
|
"type": "secret-storage",
|
|
"password": "foo",
|
|
"privateKey": "0xf03e581353c794928373fb0893bc731aefc4c4e234e643f3a46998b03cd4d7c5",
|
|
"hasAddress": true,
|
|
"json": "{\"address\":\"88a5c2d9919e46f883eb62f7b8dd9d0cc45bc290\",\"Crypto\":{\"cipher\":\"aes-128-ctr\",\"ciphertext\":\"10adcc8bcaf49474c6710460e0dc974331f71ee4c7baa7314b4a23d25fd6c406\",\"cipherparams\":{\"iv\":\"1dcdf13e49cea706994ed38804f6d171\"},\"kdf\":\"scrypt\",\"kdfparams\":{\"dklen\":32,\"n\":262144,\"p\":1,\"r\":8,\"salt\":\"bbfa53547e3e3bfcc9786a2cbef8504a5031d82734ecef02153e29daeed658fd\"},\"mac\":\"1cf53b5ae8d75f8c037b453e7c3c61b010225d916768a6b145adf5cf9cb3a703\"},\"id\":\"fb1280c0-d646-4e40-9550-7026b1be504a\",\"version\":3}\n",
|
|
"address": "0x88a5c2d9919e46f883eb62f7b8dd9d0cc45bc290"
|
|
}
|
|
</div><div class="page-separator"></div><a name="/v5/contributing/-%23-contributing"></a><a name="/v5/contributing/-%23-contributing"></a><a name="/v5/contributing/"></a><h1 class="show-anchors"><div>Contributing and Hacking<div class="anchors"><a class="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>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>Keep the PR simple and readable; only modify files in the <code class="inline">docs.wrm/</code> and <code class="inline">packages/*/src.ts/</code> folders, as this allows the changes to be easily verified </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 the problem/feature. <b>:)</b></p>
|
|
|
|
<a name="/v5/contributing/-%23-contributing--building"></a><a name="/v5/contributing/-%23-contributing--contributing--building"></a><a name="/v5/contributing/"></a><h2 class="show-anchors"><div>Building<div class="anchors"><a class="self" href="#/v5/contributing/-%23-contributing--building"></a></div></div></h2><p>The build process for ethers is unfortunatly not super trivial, but I have attempted to make it as straight-forward as possible.</p>
|
|
|
|
<p>It is a mono-repo which attempts to be compatibile with a large number of environments, build tools and platforms, which is why there are a some weird things it must do.</p>
|
|
|
|
<p>There are several custom scripts in the <code class="inline">misc/admin</code> folder to help manage the monorepo. Developers working on contributing to ethers should not generally need to worry about those, since they are wrapped up behind <code class="inline">npm run SCRIPT</code> operations.</p>
|
|
|
|
<div class="code-title"><div>Installing</div></div><div class="code"># Clone the repository
|
|
/home/ricmoo> git clone https://github.com/ethers-io/ethers.js.git
|
|
|
|
/home/ricmoo> cd ethers.js
|
|
|
|
# Install all dependencies:
|
|
# - Hoists all sub-package dependencies in the package.json (preinstall)
|
|
# - Installs all the (hoisted) dependencies and devDependencies (install)
|
|
# - Build the rat-nests (in .package_node_modules) (postinstall)
|
|
# - Create a dependency graph for the TypeScript (postinstall)
|
|
# - Link the rat-nets into each project (postinstall)
|
|
/home/ricmoo/ethers.js> npm install</div><a name="/v5/contributing/-%23-contributing--updating"></a><a name="/v5/contributing/-%23-contributing--contributing--building--contributing--updating"></a><a name="/v5/contributing/"></a><h3 class="show-anchors"><div>Making Changes<div class="anchors"><a class="self" href="#/v5/contributing/-%23-contributing--updating"></a></div></div></h3><p>Once your environment is set up, you should be able to simply start the <code class="inline">auto-build</code> feature, and make changes to the TypeScript source.</p>
|
|
|
|
<div class="code-title"><div>Watching and Building</div></div><div class="code"># Begin watching the files and re-building whenever they change
|
|
/home/ricmoo/ethers.js> npm run auto-build
|
|
|
|
# Or if you do not want to watch and just build
|
|
/home/ricmoo/ethers.js> npm run build</div><a name="/v5/contributing/-%23-contributing--contributing--building--creating-browser-ready-files"></a><a name="/v5/contributing/"></a><h3 class="show-anchors"><div>Creating Browser-Ready Files<div class="anchors"><a class="self" href="#/v5/contributing/-%23-contributing--contributing--building--creating-browser-ready-files"></a></div></div></h3><p>To create files for use directly in a browser, the distribution files (located in <code class="inline">packages/ethers/dist</code>) need to be built which requires several intermediate builds, scripts and for various rollup scripts to execute.</p>
|
|
|
|
<div class="code-title"><div>Building Distribution Files</div></div><div class="code"># If you need to rebuild all the libs (esm + cjs) and dist files
|
|
# Note: this requires node 10 or newer
|
|
/home/ricmoo/ethers.js> npm run build-all</div><a name="/v5/contributing/-%23-contributing--contributing--building--testing"></a><a name="/v5/contributing/"></a><h3 class="show-anchors"><div>Testing<div class="anchors"><a class="self" href="#/v5/contributing/-%23-contributing--contributing--building--testing"></a></div></div></h3>
|
|
<div class="code-title"><div>Testing</div></div><div class="code"># Rebuilds all files (npm run build-all) and bundles testcases up for testing
|
|
/home/ricmoo/ethers.js> npm test
|
|
|
|
# Often you don't need the full CI experience
|
|
/home/ricmoo/ethers.js> npm run test-node</div><a name="/v5/contributing/-%23-contributing--contributing--building--distribution"></a><a name="/v5/contributing/"></a><h3 class="show-anchors"><div>Distribution<div class="anchors"><a class="self" href="#/v5/contributing/-%23-contributing--contributing--building--distribution"></a></div></div></h3><p>Most developers should not ever require this step, but for people forking ethers and creating alternates (for example if you have a non-EVM compatible chain but are trying to reuse this package).</p>
|
|
|
|
<p>This script will rebuild the entire ethers project, compare it against npm, re-write package versions, update internal hashes, re-write various TypeScript files (to get around some ES+TS limitations for Tree Shaking and linking), re-write map files, bundle stripped versions of dependencies and basically just a whole bunch of stuff.</p>
|
|
|
|
<p>If you use this and get stuck, <a href="mailto:me@ricmoo.com">message me</a>.</p>
|
|
|
|
<div class="code-title"><div>Preparing the Distribution</div></div><div class="code"># Prepare all the distribution files
|
|
# - Remove all generated files (i.e. npm run clean)
|
|
# - Re-install all dependencies, hoisting, etc. (npm install)
|
|
# - Spell check all strings in every TypeScript files
|
|
# - Build everything from scratch with this clean install
|
|
# - Compare local with npm, bumping the version if changed
|
|
# - Build everything again (with the updated versions)
|
|
# - Update the CHANGELOG.md with the git history since the last change
|
|
/home/ricmoo/ethers.js> npm run update-version</div><div class="definition container-box note"><div class="term">Do NOT check in dist files in a PR</div><div class="body"><p>For Pull Requests, please ONLY commit files in the <code class="inline">docs.wrm/</code> and <code class="inline">packages/*/src.ts/</code> folders. I will prepare the distribution builds myself and keeping the PR relevant makes it easier to verify the changes.</p>
|
|
|
|
</div></div><a name="/v5/contributing/-%23-contributing--contributing--building--publishing"></a><a name="/v5/contributing/"></a><h3 class="show-anchors"><div>Publishing<div class="anchors"><a class="self" href="#/v5/contributing/-%23-contributing--contributing--building--publishing"></a></div></div></h3><p>Again, this should not be necessary for most developers. This step requires using the <code class="inline">misc/admin/cmds/config-set</code> script for a number of values, including private keys, NPM session keys, AWS access keys, GitHub API tokens, etc.</p>
|
|
|
|
<p>The config file is encrypted with about 30 seconds of scrypt password-based key derivation function, so brute-forcing the file is quite expensive.</p>
|
|
|
|
<p>The config file also contains a plain-text mnemonic. This is a money-pot. Place a tempting amount of ether or Bitcoin on this account and set up an e-mail alert for this account.</p>
|
|
|
|
<p>If any attacker happens across your encrypted config, they will have instant access to the plain-text mnemonic, so they have the option to immediately steal the ether (i.e. the responsible-disclosure bond).</p>
|
|
|
|
<p>If you ever see this ether taken, your encrypted file is compromised! Rotate all your AWS keys, NPM session keys, etc. immedately.</p>
|
|
|
|
<p>@TODO: document all the keys that need to be set for each step</p>
|
|
|
|
<div class="code-title"><div>Preparing the Distribution</div></div><div class="code"># Publish
|
|
# - Update any changed packages to NPM
|
|
# - Create a release on GitHub with the latest CHANGELOG.md description
|
|
# - Upload the bundled files the the CDN
|
|
# - Flush the CDN edge caches
|
|
/home/ricmoo/ethers.js> npm run publish-all</div><a name="/v5/contributing/-%23-contributing--documentation"></a><a name="/v5/contributing/-%23-contributing--contributing--documentation"></a><a name="/v5/contributing/"></a><h2 class="show-anchors"><div>Documentation<div class="anchors"><a class="self" href="#/v5/contributing/-%23-contributing--documentation"></a></div></div></h2><p>The documents are generated using <a href="#/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 <code class="inline">externalLinks</code> field in the config.js </li><li>Prefix external links with <code class="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 symlinks in the future </li><li>In general, I aim for consistency; look to similar situations throughout the documentation </li></ul></p>
|
|
|
|
<a name="/v5/contributing/-%23-contributing--contributing--documentation--building"></a><a name="/v5/contributing/"></a><h3 class="show-anchors"><div>Building<div class="anchors"><a class="self" href="#/v5/contributing/-%23-contributing--contributing--documentation--building"></a></div></div></h3><p>To build the documentation, you should first follow the <a href="#/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>
|
|
|
|
<div class="code-title"><div>Building the Documentations</div></div><div class="code">/home/ricmoo/ethers.js> npm run build-docs</div><a name="/v5/contributing/-%23-contributing--contributing--documentation--evaluation"></a><a name="/v5/contributing/"></a><h3 class="show-anchors"><div>Evaluation<div class="anchors"><a class="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>
|
|
|
|
<div class="code-title"><div>Build docs skipping evaluation</div></div><div class="code">/home/ricmoo/ethers.js> npm run build-docs -- --skip-eval</div><a name="/v5/contributing/-%23-contributing--contributing--documentation--previewing-changes"></a><a name="/v5/contributing/"></a><h3 class="show-anchors"><div>Previewing Changes<div class="anchors"><a class="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 <code class="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>
|
|
|
|
<div class="code-title"><div>Running a webserver</div></div><div class="code">/home/ricmoo/ethers.js> npm run serve-docs</div><div class="page-separator"></div><a name="/v5/other-resources/-%23-other-resources"></a><a name="/v5/other-resources/"></a><h1 class="show-anchors"><div>Other Resources<div class="anchors"><a class="self" href="#/v5/other-resources/-%23-other-resources"></a></div></div></h1><p>There is a lot of documentation on the internet to help you get started, learn more or cover advanced topics. Here are a few resources to check out.</p>
|
|
|
|
<a name="/v5/other-resources/-%23-other-resources--ethereum-overview"></a><a name="/v5/other-resources/"></a><h2 class="show-anchors"><div>Ethereum Overview<div class="anchors"><a class="self" href="#/v5/other-resources/-%23-other-resources--ethereum-overview"></a></div></div></h2><p><ul><li>Official <a href="https://ethereum.org/en/developers/docs/">Ethereum Developer Documentations</a> </li><li>The <a href="https://solidity.readthedocs.io/">Solidity Documentation</a>, the defactor language for smart contracts as well as a resource for some of the core concepts of Ethereum </li></ul></p>
|
|
|
|
<a name="/v5/other-resources/-%23-other-resources--tutorials"></a><a name="/v5/other-resources/"></a><h2 class="show-anchors"><div>Tutorials<div class="anchors"><a class="self" href="#/v5/other-resources/-%23-other-resources--tutorials"></a></div></div></h2><p>I do not manage or maintain these tutorials, but have happened across them. If a link is dead or outdated, please <a href="mailto:me@ricmoo.com">let me know</a> and I'll update it.</p>
|
|
|
|
<p><ul><li>No links yet; send me some </li></ul></p>
|
|
|
|
<div class="page-separator"></div><a name="/v5/documentation/-%23-flatworm"></a><a name="/v5/documentation/-%23-flatworm"></a><a name="/v5/documentation/"></a><h1 class="show-anchors"><div>Flatworm Docs<div class="anchors"><a class="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 <a href="https://github.com/readthedocs/sphinx_rtd_theme">Read the Docs</a> and the <a href="https://www.sphinx-doc.org/">Sphinx</a> project.</p>
|
|
|
|
<a name="/v5/documentation/-%23-flatworm-fragments"></a><a name="/v5/documentation/-%23-flatworm--flatworm-fragments"></a><a name="/v5/documentation/"></a><h2 class="show-anchors"><div>Fragments<div class="anchors"><a class="self" href="#/v5/documentation/-%23-flatworm-fragments"></a></div></div></h2><p>Each page is made up of fragments. A fragment is a <a href="#/v5/documentation/-%23-flatworm-directive">directive</a>, with an value and optional <i>link</i>, <i>extensions</i> and a body.</p>
|
|
|
|
<p>Many directives support <a href="#/v5/documentation/-%23-flatworm-markdown">markdown</a> in their value and body.</p>
|
|
|
|
<p>A fragment's body continues until another fragment is encountered.</p>
|
|
|
|
<a name="/v5/documentation/-%23-flatworm--flatworm-fragments--directive-format"></a><a name="/v5/documentation/"></a><h3 class="show-anchors"><div>Directive Format<div class="anchors"><a class="self" href="#/v5/documentation/-%23-flatworm--flatworm-fragments--directive-format"></a></div></div></h3>
|
|
<div class="code">_DIRECTIVE: VALUE @<LINK> @EXTENSION<PARAMETER>
|
|
BODY
|
|
|
|
MORE BODY
|
|
|
|
DIRECTIVE: The directive name
|
|
VALUE: Optional; the value to pass to the directive
|
|
LINK: Optional; a name for internal linking
|
|
EXTENSION: Optional; extended directive functionality
|
|
PARAMETER: Optional; value to pass to extended directive functions
|
|
BODY: Optional; the directive body (certain directives only)</div><a name="/v5/documentation/-%23-flatworm-directive"></a><a name="/v5/documentation/-%23-flatworm--flatworm-fragments--flatworm-directive"></a><a name="/v5/documentation/"></a><h3 class="show-anchors"><div>Flatworm Directives<div class="anchors"><a class="self" href="#/v5/documentation/-%23-flatworm-directive"></a></div></div></h3>
|
|
<div class="definition"><div class="term"><b>_section:</b> <i>TITLE</i></div><div class="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 <code class="inline">_section:</code> per page.</p>
|
|
|
|
<p><b>Extensions:</b> <a href="#/v5/documentation/-%23-flatworm--ext-inherit">@inherit</a>, <a href="#/v5/documentation/-%23-flatworm--ext-src">@src</a>, <a href="#/v5/documentation/-%23-flatworm--ext-nav">@nav</a>, <a href="#/v5/documentation/-%23-flatworm--ext-note">@note</a></p>
|
|
|
|
</div></div><div class="definition"><div class="term"><b>_subsection:</b> <i>TITLE</i></div><div class="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>
|
|
|
|
<p>The title and body support markdown.</p>
|
|
|
|
<p><b>Extensions:</b> <a href="#/v5/documentation/-%23-flatworm--ext-inherit">@inherit</a>, <a href="#/v5/documentation/-%23-flatworm--ext-src">@src</a>, <a href="#/v5/documentation/-%23-flatworm--ext-note">@note</a></p>
|
|
|
|
</div></div><div class="definition"><div class="term"><b>_heading:</b> <i>TITLE</i></div><div class="body"><p>A <i>heading</i> has its <b>TITLE</b> in an H3 font.</p>
|
|
|
|
<p>The title and body support markdown.</p>
|
|
|
|
<p><b>Extensions:</b> <a href="#/v5/documentation/-%23-flatworm--ext-inherit">@inherit</a>, <a href="#/v5/documentation/-%23-flatworm--ext-src">@src</a>, <a href="#/v5/documentation/-%23-flatworm--ext-note">@note</a></p>
|
|
|
|
</div></div><div class="definition"><div class="term"><b>_definition:</b> <i>TERM</i></div><div class="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><div class="definition"><div class="term"><b>_property:</b> <i>SIGNATURE</i></div><div class="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>
|
|
|
|
<p><b>Extensions:</b> <a href="#/v5/documentation/-%23-flatworm--ext-src">@src</a></p>
|
|
|
|
</div></div><div class="definition"><div class="term"><b>_note:</b> <i>BANNER</i></div><div class="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><div class="definition"><div class="term"><b>_warning:</b> <i>BANNER</i></div><div class="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><div class="definition"><div class="term"><b>_code:</b> <i>CAPTION</i></div><div class="body"><p>Creates a <a href="#/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 <a href="#/v5/documentation/-%23-flatworm--code-eval">Code Evaluation</a>.</p>
|
|
|
|
<p>If a line begins with a <code class="inline">"_"</code>, it should be escaped with a <code class="inline">"\"</code>.</p>
|
|
|
|
<p><b>Extensions:</b> <a href="#/v5/documentation/-%23-flatworm--ext-lang">@lang</a></p>
|
|
|
|
</div></div><div class="definition"><div class="term"><b>_table:</b> <i>FOOTER</i></div><div class="body"><p>Creates a <a href="#/v5/documentation/-%23-flatworm--table">Table</a> structured according to the body.</p>
|
|
|
|
<p>Each cell contents supports markdown and variables supports markdown.</p>
|
|
|
|
<p><b>Extensions:</b> <a href="#/v5/documentation/-%23-flatworm--ext-style">@style</a></p>
|
|
|
|
</div></div><div class="definition"><div class="term"><b>_toc:</b></div><div class="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><div class="definition"><div class="term"><b>_null:</b></div><div class="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><div class="code-title"><div>Example</div></div><div class="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
|
|
UTF-16 code units.
|
|
|
|
|
|
_code: heading
|
|
|
|
// Some code goes here
|
|
while(1);
|
|
|
|
|
|
_table: Table Footer
|
|
|
|
| **Name** | **Color** |
|
|
| Apple | Red |
|
|
| Banana | Yellow |
|
|
| Grape | Purple |
|
|
|
|
|
|
_toc:
|
|
some-file
|
|
some-directory
|
|
|
|
|
|
_note: Title
|
|
This is placed in a blue box.
|
|
|
|
|
|
_warning: Title
|
|
This is placed in an orange box.
|
|
|
|
|
|
_null:
|
|
This breaks out of a directive. For example, to end
|
|
a ``_note:`` or ``_code:``.</div><a name="/v5/documentation/-%23-flatworm-markdown"></a><a name="/v5/documentation/-%23-flatworm--flatworm-markdown"></a><a name="/v5/documentation/"></a><h2 class="show-anchors"><div>Markdown<div class="anchors"><a class="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>, <code class="inline">monospaced</code>, super<sup>script</sup> and <strike>strike</strike> text, supporting <a href="#/v5/documentation/-%23-flatworm-markdown">links</a> and lists.</p>
|
|
|
|
<p>Lists are rendered as blocks of a body, so cannot be used within a title or within another list.</p>
|
|
|
|
<div class="code">**bold text**
|
|
|
|
//italic text//
|
|
|
|
__underlined text__
|
|
|
|
``monospace code``
|
|
|
|
^^superscript text^^
|
|
|
|
~~strikeout text~~
|
|
|
|
- This is a list
|
|
- With bullet points
|
|
- With a total of three items
|
|
|
|
This is a [Link to Ethereum](https://ethereum.org) and this
|
|
is an [Internal Link](some-link).
|
|
|
|
This is a self-titled link [[https://ethereumorg]] and this
|
|
[[some-link]] will use the title from its directives value.</div><a name="/v5/documentation/-%23-flatworm--code"></a><a name="/v5/documentation/-%23-flatworm--flatworm--code"></a><a name="/v5/documentation/"></a><h2 class="show-anchors"><div>Code<div class="anchors"><a class="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>
|
|
|
|
<a name="/v5/documentation/-%23-flatworm--code-eval"></a><a name="/v5/documentation/-%23-flatworm--flatworm--code--flatworm--code-eval"></a><a name="/v5/documentation/"></a><h3 class="show-anchors"><div>JavaScript Evaluation<div class="anchors"><a class="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 <code class="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 <code class="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><code class="inline">// <hide></code></b> and <b><code class="inline">// </hide></code></b> will be omitted from the output, which can be used to setup variables.</p>
|
|
|
|
<div class="code-title"><div>Code Evaluation Example</div></div><div class="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
|
|
const foo = 4 + 5;
|
|
// <hide>
|
|
foo
|
|
// </hide>
|
|
//!</div><div class="code-title"><div>Result of Code Example</div></div><div class="code">url.parse("https://www.ricmoo.com/").protocol
|
|
<span class="result ok">// 'https:'
|
|
</span>
|
|
url.parse(45)
|
|
<span class="result error">// Error: The "url" argument must be of type string. Received type number (45)
|
|
</span>
|
|
<span class="comment">// You want to assign (doesn't emit eval) AND display the value
|
|
</span>const foo = 4 + 5;
|
|
<span class="result ok">// 9
|
|
</span></div><a name="/v5/documentation/-%23-flatworm--flatworm--code--languages"></a><a name="/v5/documentation/"></a><h3 class="show-anchors"><div>Languages<div class="anchors"><a class="self" href="#/v5/documentation/-%23-flatworm--flatworm--code--languages"></a></div></div></h3><p>The language can be specified using the <a href="#/v5/documentation/-%23-flatworm--ext-lang">@lang extension</a>.</p>
|
|
|
|
<table class="table minimal"><tr><td align="center"><b>Language</b></td><td align="center"><b>Notes</b></td><td class="fix"> </td></tr><tr><td align="center">javascript</td><td align="left">Syntax highlights and <a href="#/v5/documentation/-%23-flatworm--code-eval">evaluates</a> the JavaScript</td><td class="fix"> </td></tr><tr><td align="center">script</td><td align="left">Same as <code class="inline">javascript</code>, but does not evaluate the results</td><td class="fix"> </td></tr><tr><td align="center">shell</td><td align="left">Shell scripts or command-line</td><td class="fix"> </td></tr><tr><td align="center">text</td><td align="left">Plain text with no syntax highlighting</td><td class="fix"> </td></tr></table><a name="/v5/documentation/-%23-flatworm--table"></a><a name="/v5/documentation/-%23-flatworm--flatworm--table"></a><a name="/v5/documentation/"></a><h2 class="show-anchors"><div>Tables<div class="anchors"><a class="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 <a href="#/v5/documentation/-%23-flatworm--table-row">Row Data</a> or a <a href="#/v5/documentation/-%23-flatworm--table-variable">Variable Declaration</a> (or continuation of a <i>Variable Declaration</i>). Blank lines are ignored.</p>
|
|
|
|
<a name="/v5/documentation/-%23-flatworm--table-row"></a><a name="/v5/documentation/-%23-flatworm--flatworm--table--flatworm--table-row"></a><a name="/v5/documentation/"></a><h3 class="show-anchors"><div>Row Data<div class="anchors"><a class="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><code class="inline">"|"</code></b>, with each gap representing the cell data, <a href="#/v5/documentation/-%23-flatworm--table-alignment">alignment</a> with optional <a href="#/v5/documentation/-%23-flatworm--table-spanning">column and row spanning</a>.</p>
|
|
|
|
<a name="/v5/documentation/-%23-flatworm--table-alignment"></a><a name="/v5/documentation/-%23-flatworm--flatworm--table--flatworm--table-alignment"></a><a name="/v5/documentation/"></a><h3 class="show-anchors"><div>Alignment<div class="anchors"><a class="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>
|
|
|
|
<table class="table minimal"><tr><td align="center"><b>Alignment</b></td><td align="center"><b>Whitespace</b></td><td class="fix"> </td></tr><tr><td align="center"><i>Left</i></td><td align="left">1 or fewer spaces before the content</td><td class="fix"> </td></tr><tr><td align="center"><i>Right</i></td><td align="left">1 or fewer spaces after the content</td><td class="fix"> </td></tr><tr><td align="center"><i>Center</i></td><td align="left">2 or more space <b>both</b> before and after the content</td><td class="fix"> </td></tr><tr><td class="table-title" colspan="2">Alignment Conditions (higher precedence listed first)</td><td class="fix"> </td></tr></table><div class="code-title"><div>Alignment Example</div></div><div class="code">_table: Result of Alignment Example @style<compact>
|
|
|
|
| center |
|
|
|
|
| left |
|
|
|left |
|
|
|
|
| right |
|
|
| right|</div><table class="table compact"><tr><td align="center" width="100%">center</td><td class="fix"> </td></tr><tr><td align="left" width="100%">left</td><td class="fix"> </td></tr><tr><td align="left" width="100%">left</td><td class="fix"> </td></tr><tr><td align="right" width="100%">right</td><td class="fix"> </td></tr><tr><td align="right" width="100%">right</td><td class="fix"> </td></tr><tr><td class="table-title" colspan="1">Result of Alignment Example</td><td class="fix"> </td></tr></table><a name="/v5/documentation/-%23-flatworm--table-spanning"></a><a name="/v5/documentation/-%23-flatworm--flatworm--table--flatworm--table-spanning"></a><a name="/v5/documentation/"></a><h3 class="show-anchors"><div>Row and Column Spanning<div class="anchors"><a class="self" href="#/v5/documentation/-%23-flatworm--table-spanning"></a></div></div></h3><p>A column may end its content with any number of <b><code class="inline">"<"</code></b> which indicates how many <i>additional</i> columns to extend into.</p>
|
|
|
|
<p>If the cell content contains only a <b><code class="inline">"^"</code></b>, then the row above is extended into this cell (into the same number of columns).</p>
|
|
|
|
<div class="code-title"><div>Cell Spanning Example</div></div><div class="code">_table: Result of Cell Spanning Example @style<compact>
|
|
|
|
| (1x1) | (1x2) <| (2x1) |
|
|
| (2x2) <| (2x1) | ^ |
|
|
| ^ | ^ | (1x1) |</div><table class="table compact"><tr><td align="center" width="25%">(1x1)</td><td align="center" colspan="2" width="50%">(1x2)</td><td align="center" rowspan="2" width="25%">(2x1)</td><td class="fix"> </td></tr><tr><td align="center" colspan="2" rowspan="2" width="50%">(2x2)</td><td align="center" rowspan="2" width="25%">(2x1)</td><td class="fix"> </td></tr><tr><td align="center" width="25%">(1x1)</td><td class="fix"> </td></tr><tr><td class="table-title" colspan="4">Result of Cell Spanning Example</td><td class="fix"> </td></tr></table><a name="/v5/documentation/-%23-flatworm--table-style"></a><a name="/v5/documentation/-%23-flatworm--flatworm--table--flatworm--table-style"></a><a name="/v5/documentation/"></a><h3 class="show-anchors"><div>Styles<div class="anchors"><a class="self" href="#/v5/documentation/-%23-flatworm--table-style"></a></div></div></h3><p>The <a href="#/v5/documentation/-%23-flatworm--ext-style">@style extension</a> for a table can be used to control its appearance.</p>
|
|
|
|
<table class="table minimal"><tr><td align="center"><b>Name</b></td><td align="center"><b>Width</b></td><td align="center"><b>Columns</b></td><td class="fix"> </td></tr><tr><td align="center"><i>minimal</i></td><td align="center">minimum size</td><td align="center">best fit</td><td class="fix"> </td></tr><tr><td align="center"><i>compact</i></td><td align="center">40%</td><td align="center">evenly spaced</td><td class="fix"> </td></tr><tr><td align="center"><i>wide</i></td><td align="center">67%</td><td align="center">evenly spaced</td><td class="fix"> </td></tr><tr><td align="center"><i>full</i></td><td align="center">100%</td><td align="center">evenly spaced</td><td class="fix"> </td></tr></table><a name="/v5/documentation/-%23-flatworm--table-variable"></a><a name="/v5/documentation/-%23-flatworm--flatworm--table--flatworm--table-variable"></a><a name="/v5/documentation/"></a><h3 class="show-anchors"><div>Variables<div class="anchors"><a class="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 variable name must begin 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 <code class="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. <code class="inline">/[a-z][a-z0-9]*/i</code>)</p>
|
|
|
|
<div class="code-title"><div>Variables Example</div></div><div class="code">_table: Result of Variables Example
|
|
|
|
$Yes: This option is supported.
|
|
$No: This option is **not** supported
|
|
$bottom: This just represents an example of
|
|
what is possible. Notice that variable
|
|
content can span multiple lines.
|
|
|
|
| **Feature** | **Supported** |
|
|
| Dancing Monkey | $Yes |
|
|
| Singing Turtle | $No |
|
|
| Newt Hair | $Yes |
|
|
| $bottom <|</div><table class="table minimal"><tr><td align="center"><b>Feature</b></td><td align="center"><b>Supported</b></td><td class="fix"> </td></tr><tr><td align="center">Dancing Monkey</td><td align="center">This option is supported.</td><td class="fix"> </td></tr><tr><td align="center">Singing Turtle</td><td align="center">This option is <b>not</b> supported.</td><td class="fix"> </td></tr><tr><td align="center">Newt Hair</td><td align="center">This option is supported.</td><td class="fix"> </td></tr><tr><td align="center" colspan="2">This just represents an example of what is possible. Notice that variable content can span multiple lines.</td><td class="fix"> </td></tr><tr><td class="table-title" colspan="2">Result of Variables Example</td><td class="fix"> </td></tr></table><a name="/v5/documentation/-%23-flatworm-config"></a><a name="/v5/documentation/-%23-flatworm--flatworm-config"></a><a name="/v5/documentation/"></a><h2 class="show-anchors"><div>Configuration<div class="anchors"><a class="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>
|
|
|
|
<p>TODO: example JSON and example JS</p>
|
|
|
|
<a name="/v5/documentation/-%23-flatworm-extensions"></a><a name="/v5/documentation/-%23-flatworm--flatworm-extensions"></a><a name="/v5/documentation/"></a><h2 class="show-anchors"><div>Extensions<div class="anchors"><a class="self" href="#/v5/documentation/-%23-flatworm-extensions"></a></div></div></h2>
|
|
<a name="/v5/documentation/-%23-flatworm--ext-inherit"></a><a name="/v5/documentation/-%23-flatworm--flatworm-extensions--flatworm--ext-inherit"></a><a name="/v5/documentation/"></a><h3 class="show-anchors"><div>@inherit< <i>markdown</i> ><div class="anchors"><a class="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>
|
|
|
|
<a name="/v5/documentation/-%23-flatworm--ext-lang"></a><a name="/v5/documentation/-%23-flatworm--flatworm-extensions--flatworm--ext-lang"></a><a name="/v5/documentation/"></a><h3 class="show-anchors"><div>@lang< <i>text</i> ><div class="anchors"><a class="self" href="#/v5/documentation/-%23-flatworm--ext-lang"></a></div></div></h3><p>Set the language a <a href="#/v5/documentation/-%23-flatworm--code">code directive</a> should be syntax-highlighted for. If "javascript", the code will be evaluated.</p>
|
|
|
|
<a name="/v5/documentation/-%23-flatworm--ext-nav"></a><a name="/v5/documentation/-%23-flatworm--flatworm-extensions--flatworm--ext-nav"></a><a name="/v5/documentation/"></a><h3 class="show-anchors"><div>@nav< <i>text</i> ><div class="anchors"><a class="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>
|
|
|
|
<a name="/v5/documentation/-%23-flatworm--ext-note"></a><a name="/v5/documentation/-%23-flatworm--flatworm-extensions--flatworm--ext-note"></a><a name="/v5/documentation/"></a><h3 class="show-anchors"><div>@note<<i> markdown</i> ><div class="anchors"><a class="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>
|
|
|
|
<a name="/v5/documentation/-%23-flatworm--ext-src"></a><a name="/v5/documentation/-%23-flatworm--flatworm-extensions--flatworm--ext-src"></a><a name="/v5/documentation/"></a><h3 class="show-anchors"><div>@src< <i>key</i> ><div class="anchors"><a class="self" href="#/v5/documentation/-%23-flatworm--ext-src"></a></div></div></h3><p>Calls the configuration <code class="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 <code class="inline">config.js</code> <a href="#/v5/documentation/-%23-flatworm-config">Configuration</a> file since it requires a JavaScript function.</p>
|
|
|
|
<a name="/v5/documentation/-%23-flatworm--ext-style"></a><a name="/v5/documentation/-%23-flatworm--flatworm-extensions--flatworm--ext-style"></a><a name="/v5/documentation/"></a><h3 class="show-anchors"><div>@style< <i>text</i> ><div class="anchors"><a class="self" href="#/v5/documentation/-%23-flatworm--ext-style"></a></div></div></h3><p>The <a href="#/v5/documentation/-%23-flatworm--table-style">Table Style</a> to use for a table directive.</p>
|
|
|
|
<div class="page-separator"></div><a name="/v5/license/-%23-license"></a><a name="/v5/license/-%23-license"></a><a name="/v5/license/"></a><h1 class="show-anchors"><div>License and Copyright<div class="anchors"><a class="self" href="#/v5/license/-%23-license"></a></div></div></h1><p>The ethers library (including all dependencies) are available under the <a href="https://en.m.wikipedia.org/wiki/MIT_License">MIT License</a>, which permits a wide variety of uses.</p>
|
|
|
|
<a name="/v5/license/-%23-license--mit-license"></a><a name="/v5/license/"></a><h3 class="show-anchors"><div>MIT License<div class="anchors"><a class="self" href="#/v5/license/-%23-license--mit-license"></a></div></div></h3><p><i>Copyright © 2019 <a href="mailto:me@ricmoo.com">Richard Moore</a>.</i></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>
|
|
|
|
|
|
<div class="footer">
|
|
<div class="nav previous"><!--PREV_LINK--></div>
|
|
<div class="nav next"><!--NEXT_LINK--></div>
|
|
</div>
|
|
<div class="copyright">The content of this site is licensed under the <a href="https://choosealicense.com/licenses/cc-by-4.0/">Creative Commons License</a>. Generated on February 8, 2021, 3:25pm.</div>
|
|
</div>
|
|
<script src="/v5/static/script.js" type="text/javascript"></script>
|
|
<!--EXTRASCRIPT-->
|
|
</body>
|
|
</html>
|