251 lines
20 KiB
HTML
251 lines
20 KiB
HTML
<!DOCTYPE html>
|
|
<html class="paged">
|
|
<head>
|
|
<title>Getting Started</title>
|
|
<link rel="stylesheet" type="text/css" href="/v5/static/style.css">
|
|
</head>
|
|
<body>
|
|
<div class="sidebar">
|
|
<div class="header">
|
|
<div class="logo"><a href="/v5/"><div class="image"></div><div class="name">ethers</div><div class="version">v5.0-beta</div></a></div>
|
|
</div>
|
|
<div class="toc"><div>
|
|
<div class="link title"><a href="/v5/">Documentation</a></div><div class="base myself ancestor ancestor show link depth-1"><a href="/v5/getting-started/">Getting Started</a></div><div class="base show link depth-1"><a href="/v5/concepts/">Ethereum Basics</a></div><div class="hide link depth-2"><a href="/v5/concepts/events/">Events</a></div><div class="hide link depth-2"><a href="/v5/concepts/gas/">Gas</a></div><div class="hide link depth-2"><a href="/v5/concepts/security/">Security</a></div><div class="base show link depth-1"><a href="/v5/api/">Application Programming Interface</a></div><div class="hide 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="hide link depth-2"><a href="/v5/api/signer/">Signers</a></div><div class="hide 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="hide 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="hide 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="hide link depth-2"><a href="/v5/api/experimental/">Experimental</a></div><div class="base show link depth-1"><a href="/v5/cli/">Command Line Interfaces</a></div><div class="hide link depth-2"><a href="/v5/cli/ethers/">Sandbox Utility</a></div><div class="hide link depth-2"><a href="/v5/cli/asm/">Assembler</a></div><div class="hide link depth-2"><a href="/v5/cli/ens/">Ethereum Naming Service</a></div><div class="hide link depth-2"><a href="/v5/cli/typescript/">TypeScript</a></div><div class="hide link depth-2"><a href="/v5/cli/plugin/">Making Your Own</a></div><div class="base show link depth-1"><a href="/v5/cookbook/">Cookbook</a></div><div class="base show link depth-1"><a href="/v5/migration/">Migration Guide</a></div><div class="hide link depth-2"><a href="/v5/migration/web3/">Migration: From Web3.js</a></div><div class="hide link depth-2"><a href="/v5/migration/ethers-v4/">Migration: From Ethers v4</a></div><div class="base show link depth-1"><a href="/v5/testing/">Testing</a></div><div class="base show link depth-1"><a href="/v5/contributing/">Contributing and Hacking</a></div><div class="base show link depth-1"><a href="/v5/documentation/">Flatworm Docs</a></div><div class="base show link depth-1"><a href="/v5/license/">License and Copyright</a></div>
|
|
</div></div>
|
|
</div>
|
|
<div class="content">
|
|
<div class="breadcrumbs"><a href="/v5/">Documentation</a> » <span class="current">Getting Started</span></div>
|
|
|
|
<a name="getting-started"></a><a name="getting-started"></a><h1 class="show-anchors"><div>Getting Started<div class="anchors"><a class="self" href="/v5/getting-started/#getting-started"></a></div></div></h1>
|
|
<a name="installing"></a><a name="getting-started--installing"></a><h2 class="show-anchors"><div>Installing<div class="anchors"><a class="self" href="/v5/getting-started/#installing"></a></div></div></h2><p>The various Classes and Functions are available to be imported 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@next</div><a name="importing"></a><a name="getting-started--importing"></a><h2 class="show-anchors"><div>Importing<div class="anchors"><a class="self" href="/v5/getting-started/#importing"></a></div></div></h2>
|
|
<a name="getting-started--importing--node-js"></a><h3 class="show-anchors"><div>Node.js<div class="anchors"><a class="self" href="/v5/getting-started/#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="getting-started--importing--web-browser"></a><h3 class="show-anchors"><div>Web Browser<div class="anchors"><a class="self" href="/v5/getting-started/#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, it can be loaded in your Web Applications from our CDN.</p>
|
|
|
|
<div class="code-title"><div>ES6 in the Browser</div></div><div class="code"><script src="https://cdn.ethers.io/lib/ethers-5.0.esm.min.js"
|
|
type="application/javascipt"></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/javascipt"></script></div><a name="getting-started--glossary"></a><a name="getting-started--getting-started--glossary"></a><h2 class="show-anchors"><div>Common Terminology<div class="anchors"><a class="self" href="/v5/getting-started/#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 it can be used like a normal JavaScipt 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="getting-started--connecting"></a><a name="getting-started--getting-started--connecting"></a><h2 class="show-anchors"><div>Connecting to Ethereum: Metamask<div class="anchors"><a class="self" href="/v5/getting-started/#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 thing (a <a href="/v5/api/signer/#Signer">Signer</a>) </li></ul></p>
|
|
|
|
<div class="code-title"><div>Connecting to Metamask</div></div><div class="code">// A Web3Provider wraps a standard Web3 provider, which is
|
|
// what Metamask injects as window.ethereum into each page
|
|
const provider = new ethers.providers.Web3Provider(window.ethereum)
|
|
|
|
// The Metamask plugin also allows signing transactions to
|
|
// send ether and pay to change state within the blockchain.
|
|
// For this, we need the account signer...
|
|
const signer = provider.getSigner()</div><a name="getting-started--querying"></a><a name="getting-started--getting-started--connecting--getting-started--querying"></a><h3 class="show-anchors"><div>Querying the Blockchain<div class="anchors"><a class="self" href="/v5/getting-started/#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 can be used 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">// Look up the current block number
|
|
provider.getBlockNumber()
|
|
//!
|
|
|
|
// Get the balance of an account (by address or ENS name)
|
|
balance = await provider.getBalance("ethers.eth")
|
|
//! async balance
|
|
|
|
// Often you will need to format the output for the user
|
|
// which prefer to see values in ether (instead of wei)
|
|
ethers.utils.formatEther(balance)
|
|
//!
|
|
|
|
// Or if a user enters a string in an input field, you may need
|
|
// to convert it from ether (as a string) to wei (as a BigNumber)
|
|
ethers.utils.parseEther("1.0")
|
|
//!</div><a name="getting-started--sending"></a><a name="getting-started--getting-started--connecting--getting-started--sending"></a><h3 class="show-anchors"><div>Writing to the Blockchain<div class="anchors"><a class="self" href="/v5/getting-started/#getting-started--sending"></a></div></div></h3>
|
|
<div class="code-title"><div>Sending Ether</div></div><div class="code">// Send 1 ether to an ens name.
|
|
const tx = signer.sendTransaction({
|
|
to: "ricmoo.firefly.eth",
|
|
value: ethers.utils.parseEther("1.0")
|
|
});</div><a name="getting-started--contracts"></a><a name="getting-started--getting-started--contracts"></a><h2 class="show-anchors"><div>Contracts<div class="anchors"><a class="self" href="/v5/getting-started/#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 method all mapped to encoding and decoding data for you.</p>
|
|
|
|
<p>If you are familiar with Databases, this is similar to ORM.</p>
|
|
|
|
<p>In order to communicate with the Contract on-chain, this class needs to know what methods are available and how to encode and decode the data, which is what the <i>Application Binary Interface</i> (API) provides.</p>
|
|
|
|
<p>This class is a meta-class, which means its methods are constructed at runtime, when you pass in the ABI to the constructor it uses that to determine which methods to add.</p>
|
|
|
|
<p>While a on-chain Contract may have many methods available, you can safely ignore any methods you don't need or use, providing a smaller subset of the ABI to the contract.</p>
|
|
|
|
<p>An ABI often comes from the Solidity or Vyper compiler, but may also be placed in the code easily using the Human-Readable ABI, which the following examples use.</p>
|
|
|
|
<div class="code-title"><div>Connecting to the DAI Contract</div></div><div class="code">// We can use an ENS name for the contract address
|
|
const daiAddress = "dai.tokens.ethers.eth";
|
|
|
|
// The ERC-20 Contract ABI, which is a common contract interface
|
|
// for tokens (this is the Human-Readable ABI format)
|
|
const daiAbi = [
|
|
// Some simple details about the token
|
|
"function name() view returns (string)",
|
|
"function symbol() view returns (string)",
|
|
|
|
// Get the account balance
|
|
"function balanceOf(address) view returns (uint)",
|
|
|
|
// Send some of your tokens to someone else
|
|
"function transfer(address to, uint amount)",
|
|
|
|
// An event triggered whenever anyone transfers to someone else
|
|
"event Transfer(address indexed from, address indexed to, uint amount)"
|
|
];
|
|
|
|
// The Contract object
|
|
const daiContract = new ethers.Contract(daiAddress, daiAbi, provider);</div><a name="getting-started--reading"></a><a name="getting-started--getting-started--contracts--getting-started--reading"></a><h3 class="show-anchors"><div>Read-Only Methods<div class="anchors"><a class="self" href="/v5/getting-started/#getting-started--reading"></a></div></div></h3>
|
|
<div class="code-title"><div>Querying the DAI Contract</div></div><div class="code">// <hide>
|
|
const daiAbi = [
|
|
// Some simple details about the token
|
|
"function name() view returns (string)",
|
|
"function symbol() view returns (string)",
|
|
|
|
// Get the account balance
|
|
"function balanceOf(address) view returns (uint)",
|
|
];
|
|
const daiContract = new ethers.Contract("dai.tokens.ethers.eth", daiAbi, provider);
|
|
// </hide>
|
|
|
|
// Get the ERC-20 token name
|
|
daiContract.name()
|
|
//!
|
|
|
|
// Get the ERC-20 token synbol (for tickers and UIs)
|
|
daiContract.symbol()
|
|
//!
|
|
|
|
// Get the balance of an address
|
|
balance = await daiContract.balanceOf("ricmoo.firefly.eth")
|
|
//! async balance
|
|
|
|
// Format the DAI for displaying to the user
|
|
ethers.utils.formatUnits(balance, 18)
|
|
//!</div><a name="getting-started--writing"></a><a name="getting-started--getting-started--contracts--getting-started--writing"></a><h3 class="show-anchors"><div>State Changing Methods<div class="anchors"><a class="self" href="/v5/getting-started/#getting-started--writing"></a></div></div></h3>
|
|
<div class="code-title"><div>Sending DAI</div></div><div class="code">// The DAI Contract is currently connected to the Provider,
|
|
// which is read-only. We need to connect to a Signer, so
|
|
// that we can pay to send state-changing transactions.
|
|
const daiWithSigner = contract.connect(signer);
|
|
|
|
// Each DAI has 18 decimal places
|
|
const dai = ethers.utils.parseUnits("1.0", 18);
|
|
|
|
// Send 1 DAI to "ricmoo.firefly.eth"
|
|
tx = daiWithSigner.transfer("ricmoo.firefly.eth", dai);</div><a name="getting-started--events"></a><a name="getting-started--getting-started--contracts--getting-started--events"></a><h3 class="show-anchors"><div>Listening to Events<div class="anchors"><a class="self" href="/v5/getting-started/#getting-started--events"></a></div></div></h3>
|
|
<div class="code-title"><div>Listening to Events</div></div><div class="code">// <hide>
|
|
const daiAbi = [
|
|
"event Transfer(address indexed, address indexed, uint256)"
|
|
];
|
|
const daiContract = new ethers.Contract("dai.tokens.ethers.eth", daiAbi, provider);
|
|
const formatEther = ethers.utils.formatEther;
|
|
// </hide>
|
|
|
|
// Receive an event when ANY transfer occurs
|
|
daiContract.on("Transfer", (from, to, amount, event) => {
|
|
console.log(`${ from } sent ${ formatEther(amount) } to ${ to}`);
|
|
// The event object contains the verbatim log data, the
|
|
// EventFragment and functions to fetch the block,
|
|
// transaction and receipt and event functions
|
|
});
|
|
|
|
// A filter for when a specific address receives tokens
|
|
myAddress = "0x8ba1f109551bD432803012645Ac136ddd64DBA72";
|
|
filter = daiContract.filters.Transfer(null, myAddress)
|
|
// <hide>
|
|
filter
|
|
// </hide>
|
|
//!
|
|
|
|
// Receive an event when that filter occurs
|
|
daiContract.on(filter, (from, to, amount, event) => {
|
|
// The to will always be "address"
|
|
console.log(`I got ${ formatEther(amount) } from ${ from }.`);
|
|
});
|
|
|
|
// <hide>
|
|
// Don't want to block the docs from compiling...
|
|
daiContract.removeAllListeners();
|
|
// </hide></div><a name="getting-started--history"></a><a name="getting-started--getting-started--contracts--getting-started--history"></a><h3 class="show-anchors"><div>Query Historic Events<div class="anchors"><a class="self" href="/v5/getting-started/#getting-started--history"></a></div></div></h3>
|
|
<div class="code-title"><div>Filtering Historic Events</div></div><div class="code">// <hide>
|
|
const signer = new ethers.VoidSigner("0x8ba1f109551bD432803012645Ac136ddd64DBA72");
|
|
const daiAbi = [
|
|
"event Transfer(address indexed, address indexed, uint256)"
|
|
];
|
|
const daiContract = new ethers.Contract("dai.tokens.ethers.eth", daiAbi, provider);
|
|
//!
|
|
// </hide>
|
|
|
|
// Get the address of the Signer
|
|
myAddress = await signer.getAddress()
|
|
//! async myAddress
|
|
|
|
// Filter for all token transfers to me
|
|
filterFrom = daiContract.filters.Transfer(myAddress, null);
|
|
// <hide>
|
|
filterFrom
|
|
// </hide>
|
|
//!
|
|
|
|
// Filter for all token transfers from me
|
|
filterTo = daiContract.filters.Transfer(null, myAddress);
|
|
// <hide>
|
|
filterTo
|
|
// </hide>
|
|
//!
|
|
|
|
// List all transfers sent from me a specific block range
|
|
daiContract.queryFilter(filterFrom, 9843470, 9843480)
|
|
//!
|
|
|
|
//
|
|
// The following have had the results omitted due to the
|
|
// number of entries; but they provide some useful examples
|
|
//
|
|
|
|
// List all transfers I sent in the last 10,000 blocks
|
|
daiContract.queryFilter(filterFrom, -10000)
|
|
|
|
// List all transfers ever sent to me
|
|
daiContract.queryFilter(filterTo)</div><a name="getting-started--signing"></a><a name="getting-started--getting-started--signing"></a><h2 class="show-anchors"><div>Signing Messages<div class="anchors"><a class="self" href="/v5/getting-started/#getting-started--signing"></a></div></div></h2>
|
|
<div class="code-title"><div>Signing Messages</div></div><div class="code">// <hide>
|
|
const signer = ethers.Wallet.createRandom();
|
|
//!
|
|
// </hide>
|
|
|
|
// To sign a simple string, which can often be used for
|
|
// logging into a service, such as CryptoKitties simply
|
|
// pass the string in.
|
|
signature = await signer.signMessage("Hello World");
|
|
//! async signature
|
|
|
|
//
|
|
// A common case is also signing a hash, which is 32
|
|
// bytes. It is important to note, that to sign binary
|
|
// data it MUST be an Array (or TypedArray)
|
|
//
|
|
|
|
// This string is 66 chacacters long
|
|
message = "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
|
|
|
|
// This array representation is 32 bytes long
|
|
messageBytes = ethers.utils.arrayify(message);
|
|
//!
|
|
|
|
// To sign a hash, you most often want to sign the bytes
|
|
signature = await signer.signMessage(messageBytes)
|
|
//! async signature</div>
|
|
|
|
<div class="footer">
|
|
<div class="nav previous"><a href="/v5/"><span class="arrow">←</span>Documentation</a></div>
|
|
<div class="nav next"><a href="/v5/concepts/">Ethereum Basics<span class="arrow">→</span></a></div>
|
|
</div>
|
|
<div class="copyright">The content of this site is licensed under the <a href="https://choosealicense.com/licenses/cc-by-4.0/">Creative Commons License</a>. Generated on June 12, 2020, 3:31am.</div>
|
|
</div>
|
|
<script src="/v5/static/script.js" type="text/javascript"></script>
|
|
</body>
|
|
</html>
|