_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
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 (create random new account)
const signer = ethers.Wallet.createRandom();

// ethers (connect to JSON-RPC accounts)
const signer = provider.getSigner();


_heading: Signing a message

_code: @lang<script>

// web3 (using a private key)
signature = web3.eth.accounts.sign('Some data', privateKey)

// web3 (using a JSON-RPC account)
// @TODO

// ethers
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](link-issue-407) for more details.

_code: @lang<script>

// web3
message = await contract.methods.getMessage('nice').call();


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

// for ambiguous functions (two functions with the same
// name), the signature must also be specified
message = await contract['getMessage(string)']('nice');


_subsection: Numbers

_heading: BigNumber

Convert to BigNumber:

_code: @lang<script>

// web3
web3.utils.toBN('123456');

// ethers (from a number; must be within safe range)
ethers.BigNumber.from(123456)

// ethers (from base-10 string)
ethers.BigNumber.from("123456")

// ethers (from hex string)
ethers.BigNumber.from("0x1e240")


_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 (hash of a string)
ethers.utils.id('hello world')

// ethers (hash of binary data)
ethers.utils.keccak256('0x4242')