EthersJS

Migration from `zksync-web3`

A guide for migrating from `zksync-web3` to `zksync-ethers v6`.
Note on v5 and v6
  • This migration guide applies to zksync-ethers v6.
  • If you're using v5, no changes are required in your code as zksync-ethers v5 uses ethers v5, similar to the deprecated zksync-web3.

This guide highlights the key differences between zksync-web3/zksync-ethers v5 and zksync-ethers v6 for those familiar with zksync-web3 and need a quick primer. zksync-ethers v6 incorporates several changes due to its integration with ethers.js v6. Before proceeding, it's recommended to read the migration guide from ethers.js v5 to ethers.js v6.

Key differences

  • Removal of deprecated functions and properties:
    • Token.Address has been removed.
    • Provider.getMessageProof has been removed.
    • Provider.getTokenPrice has been removed.
  • Changes in methods and parameters:
    • Provider.getBlockWithTransaction has been replaced with Provider.getBlock(<BlockTag>, true).
    • BlockWithTransaction has been removed.
  • Changes in transaction parameters:
    • TransactionRequest.calldata has been changed from BytesLike to string.
    • transaction.calldata parameter in the following methods has been changed from BytesLike to string:
      • Provider.estimateL1ToL2Execute
      • AdapterL1.getRequestExecuteTx
      • AdapterL1.estimateGasRequestExecute
      • AdapterL1.RequestExecute
  • Utilities:
    • utils.parseTransaction has been replaced by Transaction.from.

Migration steps

  1. Update imports: Ensure you're importing from zksync-ethers instead of zksync-web3.
    import { Provider, Wallet, parseEther, Transaction } from "zksync-ethers";
    
  2. Adapt to method changes: Replace deprecated methods with their new counterparts.
    // Old
    const blockWithTx = await provider.getBlockWithTransaction(blockNumber);
    
    // New
    const blockWithTx = await provider.getBlock(blockNumber, true);
    
  3. Update transaction parameters: Change calldata parameters from BytesLike to string.
    // Old
    const txRequest = {
      calldata: ethers.utils.hexlify(data),
    };
    
    // New
    const txRequest = {
      calldata: data,
    };
    
  4. Replace utility functions: Use the new utility functions provided by ethers.js v6.
    // Old
    const parsedTx = utils.parseTransaction(rawTransaction);
    
    // New
    const parsedTx = Transaction.from(rawTransaction);
    
  5. Remove deprecated properties and methods: Ensure you remove any usage of deprecated properties like Token.Address and methods such as Provider.getMessageProof and Provider.getTokenPrice.

Example migration

Before migration (Using zksync-web3)

import { Provider, Wallet, utils } from "zksync-web3";
import { ethers } from "ethers";

const provider = new Provider("https://mainnet.era.zksync.io");
const wallet = new Wallet("<PRIVATE_KEY>", provider);

const tx = {
  to: "0xReceiverAddress",
  value: ethers.utils.parseEther("1.0"),
  calldata: ethers.utils.hexlify("0x1234"),
};

const gasEstimate = await provider.estimateL1ToL2Execute(tx);
console.log(gasEstimate);

const parsedTx = utils.parseTransaction("0xRawTransaction");
console.log(parsedTx);

After migration (Using zksync-ethers v6)

import { Provider, Wallet, parseEther, Transaction } from "zksync-ethers";

const provider = new Provider("https://mainnet.era.zksync.io");
const wallet = new Wallet("<PRIVATE_KEY>", provider);

const tx = {
  to: "0xReceiverAddress",
  value: parseEther("1.0"),
  calldata: "0x1234",
};

const gasEstimate = await provider.estimateL1ToL2Execute(tx);
console.log(gasEstimate);

const parsedTx = Transaction.from("0xRawTransaction");
console.log(parsedTx);
For development and testing, it is recommended to use burner wallets. Avoid using real private keys to prevent security risks.

Made with ❤️ by the ZKsync Community