Migration: From Web3.js

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


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.

Connecting to Ethereum

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

Connecting to Ethereum: Metamask

// web3 const web3 = new Web3(Web3.givenProvider); // ethers const provider = new ethers.providers.Web3Provider(window.ethereum);


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.

Creating signer

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

Signing a message

// 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')


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

Deploying a Contract

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

Interacting with a Contract

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

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 for more details.

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



Convert to BigNumber:

// 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")



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

// 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')