Ethers.js Cheat Sheet

2021-09-04

ethers.js is a library that interact with Ethereum Blockchain.
It is a very useful library but the official documentation was a little hard to read for me so I would like to summarize it for easy reference. (Focusing on what will be used often.)

*They are arranged in alphabetical order.





Accounts

Gets a list of accounts

1
const accounts = await provider.listAccounts();

Example:

1
2
3
4
5
// Connect web3
const provider = new ethers.providers.Web3Provider(window.ethereum);

const accounts = await provider.listAccounts();
console.log(accounts[0]);



Balance

Gets a blanace of address

1
const balance = await provider.getBalance(`address`);

Example:

1
2
3
4
5
6
7
8
// Connect web3
const provider = new ethers.providers.Web3Provider(window.ethereum);

const address = "0x28d3...";

const balance = await provider.getBalance(address);

console.log(`The ${address} balance: ${balance.toString()}`);



Connect (MetaMask)

Connects to Ethereum with MetaMask

1
const provider = new ethers.providers.Web3Provider(window.ethereum);



Connect (RPC)

Connects to Ethereum with RPC

1
const provider = new ethers.providers.JsonRpcProvider(`url`);

url for example:

Platform URL
Alchemy https://<network>.alchemyapi.io/v2/YOUR-API-KEY
Infura https://<network>.infura.io/v3/YOUR-PROJECT-ID



Contract

Create a contract instance by signer.
It does not work if the user does not have a wallet or is not connected.

1
const contract = new ethers.Contract(`address`, `abi`, `signer`);

Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
import Artifact from './Contract.json';

// Connect web3
const provider = new ethers.providers.Web3Provider(window.ethereum);
const signer = provider.getSigner();

const contractAddress = "0x9fE4...";

const contract = new ethers.Contract(
contractAddress,
Artifact.abi,
signer
);

// Call a state-change method
const userAddress = "0x28d3...";
const dai = ethers.utils.parseUnits("1.0", 18);
await contract.transfer(userAddress, dai);



Contract (Read-Only)

Create a contract instance by provider.
It can call Read-Only methods only. Instead, it also works if the user doesn’t have a wallet or isn’t connected.

1
const contract = new ethers.Contract(`address`, `abi`, `provider`);

Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
import Artifact from './Contract.json';

// For example here, interact with Alchemy JSON-RPC
const provider = new ethers.providers.JsonRpcProvider("https://eth-mainnet.alchemyapi.io/v2/<YOUR-API-KEY>");

const contractAddress = "0x9fE4...";

const contract = new ethers.Contract(
contractAddress,
Artifact.abi,
provider
);

// Call a getter method
const contractName = await contract.name();
console.log(`Contract name is ${contractName}`);



Contract Event Listener

Listens events emitted in contract.

1
contract.on(`event`, `listener`);

Example:

1
2
3
4
5
6
7
8
contract.on("TransferedFrom", (from, to) => {
console.log(`Token transfered from ${from} to ${to}`);
});

contract.on("Minted", (tokenId) => {
console.log(`Token #${tokenId} minted`);
});



Convert (Ether -> Wei)

Returns BigNumber.

1
const wei = ethers.utils.parseEther(`ETH`);

Example:

1
2
3
4
const weiBigNumber = ethers.utils.parseEther("0.2");
const wei = weiBigNumber.toString();

console.log("wei: ", wei);



Convert (Wei -> Ether)f

Returns string.

1
const ether = ethers.utils.formatEther(`wei`);
1
2
3
4
5
const address = "0x28d319067E209fa43Ef46bF54343Dae4CEDd3824";
const balanceBigNumber = await ethers.providers.getBalance(address);

const balance = ethers.utils.formatEther(balance.toString());
console.log(`user balance: ${balance} Ether`);



Install

1
npm install ethers



Import

for CommonJS

1
const { ethers } = require('ethers');

for ES Modules

1
import { ethers } from 'ethers';



Network & Chain ID

Gets a connecting network and chain ID.

1
2
const network = await provider.getNetwork();
const chainId = network.chainId;

Example:

1
2
3
4
5
// Connect web3
const provider = new ethers.providers.Web3Provider(window.ethereum);

const network = await provider.getNetwork();
const chainId = network.chainId;

Chain ID List for example:

1 — Mainnet
3 — Ropsten
4 — Rinkeby
5 — Goerli
10 — Optimism
42 — Kovan
56 — BSC
137 — Polygon
42161 — Arbitrum One
43114 — Avalanche