ethers.js/docs.wrm/migration/web3.wrm

_section: Migration: From Web3.js

This migration guide focuses on migrating web3.js version 1.2.9 to ethers.js v5.

_subsection: Providers

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.

_heading: Connecting to Ethereum

_code: @lang<script>

// web3
var Web3 = require('web3');
var web3 = new Web3('http://localhost:8545');

// ethers
var ethers = require('ethers');
const url = "http://127.0.0.1:8545";
const provider = new ethers.providers.JsonRpcProvider(url);


_heading: Connecting to Ethereum: Metamask


_code: @lang<script>

// web3
const web3 = new Web3(Web3.givenProvider);

// ethers
import { ethers } from "./dist/ethers.esm.js";
const provider = new ethers.providers.Web3Provider(window.ethereum);

_subsection: Signers

In ethers, a **signer** is an abstraction of an Ethereum Account. It can be used to sign messages and transactions and send signed transactions to the Ethereum Network.

In web3, an account can be used to sign messages and transactions.

_heading: Creating signer

_code: @lang<script>

// web3
const account = web3.eth.accounts.create();

// ethers
const signer = ethers.Wallet.createRandom();
// getting signer from JSON RPC providers
const signer = provider.getSigner();

_heading: Signing a message

_code: @lang<script>

// web3
let signature = web3.eth.accounts.sign('Some data', privateKey);

// ethers
let signature = await signer.signMessage('Some data');

_subsection: Contracts

A contract object is an abstraction of a smart contract on the Ethereum Network. It allows for easy interaction with the smart contact.

_heading: Deploying a Contract

_code: @lang<script>

// web3
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) 
});

// ethers
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);

// wait for contract creation transaction to be mined
await contract.deployTransaction.wait();


_heading: Interacting with a Contract

_code: @lang<script>

// web3
const contract = new web3.eth.Contract(abi, contractAddress);
// read only query
contract.methods.getValue().call();
// state changing operation
contract.methods.changeValue(42).send({from: ....})
.on('receipt', function(){
    ...
});

// ethers
// pass a provider when initiating a contract for read only queries
const contract = new ethers.Contract(contractAddress, abi, provider);
const value = await contract.getValue();


// pass a signer to create a contract instance for state changing operations
const contract = new ethers.Contract(contractAddress, abi, signer);
const tx = await contract.changeValue(33);

// wait for the transaction to be mined
const receipt = await tx.wait();


_heading: Overloaded Functions

Overloaded functions are functions that have the same name but different parameter types. 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. See [issue #407](https://github.com/ethers-io/ethers.js/issues/407) for more details.

_code: @lang<script>

// web3
const message = await contract.methods.getMessage('nice').call();
console.log('message', message);


// ethers
const abi = ['function getMessage(string memory prefix) public view returns (string memory)',
             'function getMessage() public view returns (string memory)'];
const contract = new ethers.Contract(address, abi, signer);

// this is how ethers identifies which function to call for overloaded functions
const message = await contract['getMessage(string)']('nice');
console.log('message', message);

_subsection: Numbers

_heading: BigNumber

Convert to BigNumber:

_code: @lang<script>

// web3
const bn = web3.utils.toBN('123456');

// ethers
const bn = ethers.BigNumber.from(123456);

_subsection: Utilities

_heading: Hash

Computing Keccak256 hash of a UTF-8 string in web3 and ethers:

_code: @lang<script>

// web3
web3.utils.sha3('hello world');
web3.utils.keccak256('hello world');

// ethers
ethers.utils.id('hello world')