306 lines
44 KiB
HTML
306 lines
44 KiB
HTML
<!DOCTYPE html>
|
|
<html class="paged">
|
|
<head>
|
|
<title>Signers</title>
|
|
<link rel="stylesheet" type="text/css" href="/v5/static/style.css">
|
|
<meta property="og:title" content="Signers"/>
|
|
<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/">Documentation</a></div><div class="base show link depth-1"><a href="/v5/getting-started/">Getting Started</a></div><div class="base show link depth-1"><a href="/v5/concepts/">Ethereum Basics</a></div><div class="hide link depth-2"><a href="/v5/concepts/events/">Events</a></div><div class="hide link depth-2"><a href="/v5/concepts/gas/">Gas</a></div><div class="hide link depth-2"><a href="/v5/concepts/security/">Security</a></div><div class="hide link depth-2"><a href="/v5/concepts/best-practices/">Best Practices</a></div><div class="base show link depth-1"><a href="/v5/api-keys/">Provider API Keys</a></div><div class="base ancestor show link depth-1"><a href="/v5/api/">Application Programming Interface</a></div><div class="show link depth-2"><a href="/v5/api/providers/">Providers</a></div><div class="hide link depth-3"><a href="/v5/api/providers/provider/">Provider</a></div><div class="hide link depth-3"><a href="/v5/api/providers/jsonrpc-provider/">JsonRpcProvider</a></div><div class="hide link depth-3"><a href="/v5/api/providers/api-providers/">API Providers</a></div><div class="hide link depth-3"><a href="/v5/api/providers/other/">Other Providers</a></div><div class="hide link depth-3"><a href="/v5/api/providers/types/">Types</a></div><div class="myself ancestor ancestor show link depth-2"><a href="/v5/api/signer/">Signers</a></div><div class="link show child depth-3"><a href="#Signer">Signer</a></div><div class="link show child depth-3"><a href="#Wallet">Wallet</a></div><div class="link show child depth-3"><a href="#VoidSigner">VoidSigner</a></div><div class="link show child depth-3"><a href="#ExternallyOwnedAccount">ExternallyOwnedAccount</a></div><div class="show link depth-2"><a href="/v5/api/contract/">Contract Interaction</a></div><div class="hide link depth-3"><a href="/v5/api/contract/contract/">Contract</a></div><div class="hide link depth-3"><a href="/v5/api/contract/contract-factory/">ContractFactory</a></div><div class="hide link depth-3"><a href="/v5/api/contract/example/">Example: ERC-20 Contract</a></div><div class="show link depth-2"><a href="/v5/api/utils/">Utilities</a></div><div class="hide link depth-3"><a href="/v5/api/utils/abi/">Application Binary Interface</a></div><div class="hide link depth-4"><a href="/v5/api/utils/abi/coder/">AbiCoder</a></div><div class="hide link depth-4"><a href="/v5/api/utils/abi/formats/">ABI Formats</a></div><div class="hide link depth-4"><a href="/v5/api/utils/abi/fragments/">Fragments</a></div><div class="hide link depth-4"><a href="/v5/api/utils/abi/interface/">Interface</a></div><div class="hide link depth-3"><a href="/v5/api/utils/address/">Addresses</a></div><div class="hide link depth-3"><a href="/v5/api/utils/bignumber/">BigNumber</a></div><div class="hide link depth-3"><a href="/v5/api/utils/bytes/">Byte Manipulation</a></div><div class="hide link depth-3"><a href="/v5/api/utils/constants/">Constants</a></div><div class="hide link depth-3"><a href="/v5/api/utils/display-logic/">Display Logic and Input</a></div><div class="hide link depth-3"><a href="/v5/api/utils/encoding/">Encoding Utilities</a></div><div class="hide link depth-3"><a href="/v5/api/utils/fixednumber/">FixedNumber</a></div><div class="hide link depth-3"><a href="/v5/api/utils/hashing/">Hashing Algorithms</a></div><div class="hide link depth-3"><a href="/v5/api/utils/hdnode/">HD Wallet</a></div><div class="hide link depth-3"><a href="/v5/api/utils/logger/">Logging</a></div><div class="hide link depth-3"><a href="/v5/api/utils/properties/">Property Utilities</a></div><div class="hide link depth-3"><a href="/v5/api/utils/signing-key/">Signing Key</a></div><div class="hide link depth-3"><a href="/v5/api/utils/strings/">Strings</a></div><div class="hide link depth-3"><a href="/v5/api/utils/transactions/">Transactions</a></div><div class="hide link depth-3"><a href="/v5/api/utils/web/">Web Utilities</a></div><div class="hide link depth-3"><a href="/v5/api/utils/wordlists/">Wordlists</a></div><div class="show link depth-2"><a href="/v5/api/other/">Other Libraries</a></div><div class="hide link depth-3"><a href="/v5/api/other/assembly/">Assembly</a></div><div class="hide link depth-4"><a href="/v5/api/other/assembly/dialect/">Ethers ASM Dialect</a></div><div class="hide link depth-4"><a href="/v5/api/other/assembly/api/">Utilities</a></div><div class="hide link depth-4"><a href="/v5/api/other/assembly/ast/">Abstract Syntax Tree</a></div><div class="hide link depth-3"><a href="/v5/api/other/hardware/">Hardware Wallets</a></div><div class="show link depth-2"><a href="/v5/api/experimental/">Experimental</a></div><div class="base show link depth-1"><a href="/v5/cli/">Command Line Interfaces</a></div><div class="hide link depth-2"><a href="/v5/cli/ethers/">Sandbox Utility</a></div><div class="hide link depth-2"><a href="/v5/cli/asm/">Assembler</a></div><div class="hide link depth-2"><a href="/v5/cli/ens/">Ethereum Naming Service</a></div><div class="hide link depth-2"><a href="/v5/cli/typescript/">TypeScript</a></div><div class="hide link depth-2"><a href="/v5/cli/plugin/">Making Your Own</a></div><div class="base show link depth-1"><a href="/v5/cookbook/">Cookbook</a></div><div class="hide link depth-2"><a href="/v5/cookbook/react-native/">React Native (and ilk)</a></div><div class="base show link depth-1"><a href="/v5/migration/">Migration Guide</a></div><div class="hide link depth-2"><a href="/v5/migration/web3/">Migration: From Web3.js</a></div><div class="hide link depth-2"><a href="/v5/migration/ethers-v4/">Migration: From Ethers v4</a></div><div class="base show link depth-1"><a href="/v5/testing/">Testing</a></div><div class="base show link depth-1"><a href="/v5/contributing/">Contributing and Hacking</a></div><div class="base show link depth-1"><a href="/v5/other-resources/">Other Resources</a></div><div class="base show link depth-1"><a href="/v5/documentation/">Flatworm Docs</a></div><div class="base show link depth-1"><a href="/v5/license/">License and Copyright</a></div>
|
|
</div></div>
|
|
<div class="footer">
|
|
<a href="/v5/single-page/">Single Page</a>
|
|
</div>
|
|
</div>
|
|
<div class="content">
|
|
<div class="breadcrumbs"><a href="/v5/">Documentation</a> » <a href="/v5/api/">API</a> » <span class="current">Signers</span></div>
|
|
|
|
<a name="signers"></a><a name="signers"></a><h1 class="show-anchors"><div>Signers<div class="anchors"><a class="self" href="/v5/api/signer/#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/#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/#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/#JsonRpcProvider-getSigner">getSigner</a> </li></ul></p>
|
|
|
|
<a name="Signer"></a><a name="signers--Signer"></a><h2 class="show-anchors"><div>Signer<div class="anchors"><a class="self" href="/v5/api/signer/#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/#Wallet">Wallet</a>, <a href="/v5/api/signer/#VoidSigner">VoidSigner</a> or <a href="/v5/api/providers/jsonrpc-provider/#JsonRpcSigner">JsonRpcSigner</a>.</p>
|
|
|
|
<a name="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/#Signer">Signer</a></span><div class="anchors"><a class="self" href="/v5/api/signer/#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="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/#address">Address</a> > ></span><div class="anchors"><a class="self" href="/v5/api/signer/#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="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/#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="Signer--blockchain-methods"></a><a name="signers--Signer--Signer--blockchain-methods"></a><h3 class="show-anchors"><div>Blockchain Methods<div class="anchors"><a class="self" href="/v5/api/signer/#Signer--blockchain-methods"></a></div></div></h3>
|
|
<a name="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/#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="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/#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="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/#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="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/#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="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/#DataHexString">DataHexString</a> > ></span><div class="anchors"><a class="self" href="/v5/api/signer/#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="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/#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="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/#address">Address</a> > ></span><div class="anchors"><a class="self" href="/v5/api/signer/#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="Signer--signing-methods"></a><a name="signers--Signer--Signer--signing-methods"></a><h3 class="show-anchors"><div>Signing<div class="anchors"><a class="self" href="/v5/api/signer/#Signer--signing-methods"></a></div></div></h3>
|
|
<a name="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/#signature-raw">RawSignature</a> > ></span><div class="anchors"><a class="self" href="/v5/api/signer/#Signer-signMessage"></a></div></div><div class="body"><p>This returns a Promise which resolves to the <a href="/v5/api/utils/bytes/#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/#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/#utils-arrayify">arrayify</a> utility function.</p>
|
|
|
|
</div></div>
|
|
<a name="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/#DataHexString">DataHexString</a> > ></span><div class="anchors"><a class="self" href="/v5/api/signer/#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="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/#providers-TransactionResponse">TransactionResponse</a> ></span><div class="anchors"><a class="self" href="/v5/api/signer/#Signer-sendTransaction"></a></div></div><div class="body"><p>This method populates the transactionRequest with missing fields, using <a href="/v5/api/signer/#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/#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="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/#signature-raw">RawSignature</a> > ></span><div class="anchors"><a class="self" href="/v5/api/signer/#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="Signer--subclassing"></a><a name="signers--Signer--Signer--subclassing"></a><h3 class="show-anchors"><div>Sub-Classes<div class="anchors"><a class="self" href="/v5/api/signer/#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="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/#providers-TransactionRequest">TransactionRequest</a></span><div class="anchors"><a class="self" href="/v5/api/signer/#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/#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="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/#providers-TransactionRequest">TransactionRequest</a> ></span><div class="anchors"><a class="self" href="/v5/api/signer/#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/#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="Wallet"></a><a name="signers--Wallet"></a><h2 class="show-anchors"><div>Wallet<span class="inherits"> inherits <a href="/v5/api/signer/#ExternallyOwnedAccount">ExternallyOwnedAccount</a> and <a href="/v5/api/signer/#Signer">Signer</a></span><div class="anchors"><a class="self" href="/v5/api/signer/#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/#Signer">Signer</a> and can sign transactions and messages using a private key as a standard Externally Owned Account (EOA).</p>
|
|
|
|
<a name="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/#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="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/#Wallet">Wallet</a></span><div class="anchors"><a class="self" href="/v5/api/signer/#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="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/#Wallet">Wallet</a> ></span><div class="anchors"><a class="self" href="/v5/api/signer/#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="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/#Wallet">Wallet</a></span><div class="anchors"><a class="self" href="/v5/api/signer/#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="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/#Wallet">Wallet</a></span><div class="anchors"><a class="self" href="/v5/api/signer/#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="Wallet--properties"></a><a name="signers--Wallet--Wallet--properties"></a><h3 class="show-anchors"><div>Properties<div class="anchors"><a class="self" href="/v5/api/signer/#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/#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/#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/#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/#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="Wallet--methods"></a><a name="signers--Wallet--Wallet--methods"></a><h3 class="show-anchors"><div>Methods<div class="anchors"><a class="self" href="/v5/api/signer/#Wallet--methods"></a></div></div></h3>
|
|
<a name="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/#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="VoidSigner"></a><a name="signers--VoidSigner"></a><h2 class="show-anchors"><div>VoidSigner<span class="inherits"> inherits <a href="/v5/api/signer/#Signer">Signer</a></span><div class="anchors"><a class="self" href="/v5/api/signer/#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/#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/#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="ExternallyOwnedAccount"></a><a name="signers--ExternallyOwnedAccount"></a><h2 class="show-anchors"><div>ExternallyOwnedAccount<div class="anchors"><a class="self" href="/v5/api/signer/#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/#address">Address</a> ></span><div class="anchors"></div></div><div class="body"><p>The <a href="/v5/api/utils/address/#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/#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/#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="footer">
|
|
<div class="nav previous"><a href="/v5/api/providers/types/"><span class="arrow">←</span>Types</a></div>
|
|
<div class="nav next"><a href="/v5/api/contract/">Contract Interaction<span class="arrow">→</span></a></div>
|
|
</div>
|
|
<div class="copyright">The content of this site is licensed under the <a href="https://choosealicense.com/licenses/cc-by-4.0/">Creative Commons License</a>. Generated on February 8, 2021, 3:25pm.</div>
|
|
</div>
|
|
<script src="/v5/static/script.js" type="text/javascript"></script>
|
|
<!--EXTRASCRIPT-->
|
|
</body>
|
|
</html>
|