The various Classes and Functions are available to be imported manually from sub-packages under the @ethersproject organization but for most projects, the umbrella package is the easiest way to get started.
/home/ricmoo> npm install --save ethers@next
const { ethers } = require("ethers");
import { ethers } from "ethers";
It is generally better practice (for security reasons) to copy the ethers library to your own webserver and serve it yourself.
For quick demos or prototyping though, it can be loaded in your Web Applications from our CDN.
<script src="https://cdn.ethers.io/lib/ethers-5.0.esm.min.js"
type="application/javascipt"></script>
<script src="https://cdn.ethers.io/lib/ethers-5.0.umd.min.js"
type="application/javascipt"></script>
This section needs work...
| Provider | 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. | |
| Signer | 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. | |
| Contract | 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. | |
| Common Terms | |
Connecting to Ethereum: Metamask
The quickest and easiest way to experiment and begin developing on Ethereum is to use Metamask, which is a browser extension that provides:
- A connection to the Ethereum network (a Provider)
- Holds your private key and can sign thing (a Signer)
// 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()
Once you have a Provider, 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.
// 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")
//!
Writing to the Blockchain
// Send 1 ether to an ens name.
const tx = signer.sendTransaction({
to: "ricmoo.firefly.eth",
value: ethers.utils.parseEther("1.0")
});
A Contract is an abstraction of program code which lives on the Ethereum blockchain.
The Contract 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.
If you are familiar with Databases, this is similar to ORM.
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 Application Binary Interface (API) provides.
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.
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.
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.
Connecting to the DAI Contract
// 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);
Querying the DAI Contract
// <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)
//!
// 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);
// <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>
Filtering Historic Events
// <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)
// <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