Migration from `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);