* @jdevcs @AlexeyKrasnoperov

sidebar_label: '🔄 Migration to ethers.js'

title: 'Migration from Web3.js to Ethers.js'

position: 17

This guide will help you migrate from web3.js to ethers.js for interacting with the Ethereum blockchain. The guide covers ethers.js v6, providing code examples for both libraries.

To begin migrating from Web3.js to ethers.js, first install the ethers.js package:

When migrating from Web3.js to ethers.js, the first step is to update how you connect to the Ethereum network. Both libraries use providers, but their initialization differs.

import { Web3 } from 'web3';

const web3 = new Web3(providerURL);

const blockNumber = await web3.eth.getBlockNumber();

console.log(blockNumber);

To migrate this to ethers.js, you'll need to replace it with JsonRpcProvider. Note that ethers.js separates provider types more explicitly:

import { ethers } from 'ethers';

const provider = new ethers.JsonRpcProvider(providerURL);

const blockNumber = await provider.getBlockNumber();

console.log(blockNumber);

When migrating browser wallet connections, you'll need to update how you handle the injected provider (like MetaMask). Here's your existing Web3.js code:

const web3 = new Web3(window.ethereum);

In ethers.js v6, you'll need to use the BrowserProvider class instead. This provider is specifically designed for browser environments:

const provider = new ethers.BrowserProvider(window.ethereum);

If your code generates private keys with Web3.js, here's how to migrate that functionality. Your existing Web3.js code:

const privateKey = web3.eth.accounts.create().privateKey;

To achieve the same in ethers.js, use the `Wallet.createRandom()` method:

const privateKey = ethers.Wallet.createRandom().privateKey;

When migrating wallet creation code, you'll need to change how accounts are added to wallets. Your existing Web3.js code using `wallet.add()`:

const web3 = new Web3();

const wallet = web3.eth.accounts.wallet.add(

// you can generate a private key using web3.eth.accounts.create().privateKey

privateKey,

);

console.log(wallet[0].address);

In ethers.js, wallet creation uses the Wallet constructor:

const wallet = new ethers.Wallet(

// A private key that you might had generated with:

ethers.Wallet.createRandom().privateKey,

// or explicitly given privateKey

);

console.log(wallet.address);

When migrating code that gets the current account, you'll need to change from Web3.js's getAccounts():

const account = (await web3.eth.getAccounts())[0];

To ethers.js's getSigner() method, which returns a signer object instead of just an address:

const signer = await provider.getSigner();

When migrating message signing functionality, you'll need to update from Web3.js's sign methods:

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

const signature = await web3.eth.sign(

web3.utils.utf8ToHex('Some data'), // data to be signed (4.x only supports Hex Strings)

'0x6E599DA0bfF7A6598AC1224E4985430Bf16458a4', // the address

);

In ethers.js, signing is simplified using the signMessage method:

const signer = new ethers.Wallet(privateKey);

const signature = await signer.signMessage('Some data');

When migrating transaction sending code, you'll need to update how transactions are signed and sent. Your existing Web3.js code where transactions are signed using an unlocked or added account:

const web3 = new Web3(url);

const wallet = web3.eth.accounts.wallet.add(givenPrivateKey);

const account = wallet[0].address;

const tx = await web3.eth.sendTransaction({

from: account,

to: '0x92d3267215Ec56542b985473E73C8417403B15ac',

value: web3.utils.toWei('0.00000000001', 'ether'),

});

console.log(tx);

In ethers.js, transactions are sent using a signer instance, which combines the private key and provider:

const signer = new ethers.Wallet(privateKey, provider);

const tx = await signer.sendTransaction({

to: '0x92d3267215Ec56542b985473E73C8417403B15ac',

value: ethers.parseUnits('0.001', 'ether'),

});

console.log(tx);

When migrating code that separates transaction signing and broadcasting, you'll need to update from Web3.js's two-step process:

const transaction = {

from: senderPublicAddress,

to: receiverPublicAddress,

value: 1,

gas: 21000,

};

const signedTransaction = await web3.eth.accounts.signTransaction(transaction, privateKey);

const tx = await web3.eth.sendSignedTransaction(signedTransaction.rawTransaction);

console.log(tx);

In ethers.js, you can broadcast a pre-signed transaction using the provider's broadcastTransaction method:

await provider.broadcastTransaction(signedTx);

When migrating contract deployment code, you'll need to update from Web3.js's deploy and send pattern:

const contract = new web3.eth.Contract(abi);

const deployTx = await contract

.deploy({

data: bytecode,

arguments: ['constructor param'],

})

.send({

from: '0x12598d2Fd88B420ED571beFDA8dD112624B5E730',

gas: '1000000',

});

console.log('contract address', deployTx.options.address);

In ethers.js, contract deployment uses the ContractFactory class:

const signer = await provider.getSigner();

const factory = new ethers.ContractFactory(abi, bytecode, signer);

const contract = await factory.deploy('constructor param');

console.log('contract address', contract.address);

await contract.deployTransaction.wait();

When migrating contract method calls, you'll need to update from Web3.js's methods object pattern:

const contract = new web3.eth.Contract(ABI, CONTRACT_ADDRESS);

const result = await contract.methods.someFunction().call();

const tx = await contract.methods.someFunction().send();

In ethers.js, contract methods are called directly as functions:

const contract = new ethers.Contract(CONTRACT_ADDRESS, ABI, provider);

const result = await contract.someFunction();

When migrating event handling code, you'll need to update from Web3.js's events interface:

const event = contract.events.SomeEvent({

filter: { val: 100 },

fromBlock: 0,

});

event.on('data', resolve);

event.on('error', reject);

In ethers.js, event listening is :

contract.on('SomeEvent', (arg1, arg2, event) => {

// event handling

});

When migrating gas estimation code, you'll need to update from Web3.js's estimateGas method:

const gasAmount = await contract.methods.myMethod(123).estimateGas({

from: transactionSenderAddress,

});

In ethers.js, gas estimation is made through a direct method call:

const gasEstimate = await contract.myMethod.estimateGas(123);

When migrating code that computes Keccak-256 hashes, you'll need to update from Web3.js's utility methods:

const hash1 = web3.utils.sha3('hello world');

const hash2 = web3.utils.keccak256('hello world');

In ethers.js, hashing requires explicit conversion of strings to bytes:

import { keccak256, toUtf8Bytes } from 'ethers';

const message = 'Hello, World!';

const messageBytes = toUtf8Bytes(message);

const hash = keccak256(messageBytes);

When migrating code that converts between ether units, you'll need to update from Web3.js's fromWei and toWei methods:

const fromWeiToEther = web3.utils.fromWei('1000000000000000000', 'ether');

console.log(fromWeiToEther);

const fromEtherToWei = web3.utils.toWei('1.0', 'ether');

console.log(fromEtherToWei);

In ethers.js, use formatEther and parseEther for common ether conversions:

const fromWeiToEther = ethers.formatEther('1000000000000000000');

console.log(fromWeiToEther);

const fromEtherToWei = ethers.parseEther('1.0');

console.log(fromEtherToWei);