Using Web3.js to interact with ZKsync

Web3.js is a robust and flexible collection of libraries for TypeScript and JavaScript developers. It serves as an essential tool for connecting and crafting applications within the Ethereum ecosystem and can be extended to support other networks through its plugin system.

You can use the ZKsync plugin for Web3.js to interact with the ZKsync JSON-RPC API smart contracts deployed on ZKsync. Whether you are setting up a project from scratch or integrating Web3.js into an existing project, this guide has you covered.

Installation with existing project

For existing projects, start by adding Web3.js and the ZKsync plugin for Web3.js. Open your terminal and execute the following command:

npm install web3 web3-plugin-zksync

This command installs the latest version of Web3.js and the ZKsync plugin for Web3.js and adds them to your project's dependencies.

Creating a project with ZKsync CLI

This section provides a quick start for developers who prefer using ZKsync CLI to bootstrap their Web3.js project from scratch. It’s ideal for those looking to create scripts that interact with ZKsync contracts in a new project.

Step 1: Install ZKsync CLI globally

npm install -g @matterlabs/zksync-cli

Step 2: Create a new ZKsync project by running

zksync-cli create --template node_web3js my-project

And then choose your preferred package manager in the list. This command will generate a new project with all necessary configurations for ZKsync and install all necessary dependencies.

Step 3: Navigate to the newly created project directory:

cd my-project

Step 4: Let's walk through the code to understand each part before running the script.

Initialization

Before using the ZKsync plugin for Web3.js, you need to initialize Web3 with a provider and register the plugin.

Example

import { Web3 } from "web3";
import { ZKsyncPlugin } from "web3-plugin-zksync";

const web3: Web3 = new Web3("https://rpc.sepolia.org");

const zksyncRpcUrl: string = "https://sepolia.era.zksync.dev";
console.log(`📞 Connecting to ZKsync Era [${zksyncRpcUrl}]`);
web3.registerPlugin(new ZKsyncPlugin(zksyncRpcUrl));

Ethereum JSON-RPC API

ZKsync Era implements the Ethereum JSON-RPC API, so you can use the Web3.js eth package to fetch data from the Layer 1 and Layer 2 networks.

Fetch the Latest Block Number

const l1BlockNumber = await web3.eth.getBlockNumber();
console.log(`Current L1 block number: ${l1BlockNumber}`);
const l2BlockNumber = await web3.ZKsync.L2.eth.getBlockNumber();
console.log(`Current L2 block number: ${l2BlockNumber}`);

ZKsync L2-Specific JSON-RPC API

The ZKsync plugin for Web3.js implements the ZKsync-specific methods from the zks_ namespace of the JSON-RPC API.

Fetch the Main Contract Address

const mainContract = await web3.ZKsync.rpc.getMainContract();
console.log(`Main contract: ${mainContract}`);

Step 5: Write your code in src/main.ts file, then run the script using npm run start.

import { Web3 } from "web3";
import { ZKsyncPlugin } from "web3-plugin-zksync";

const web3: Web3 = new Web3("https://rpc.sepolia.org");

const zksyncRpcUrl: string = "https://sepolia.era.zksync.dev";
console.log(`📞 Connecting to ZKsync Era [${zksyncRpcUrl}]`);
web3.registerPlugin(new ZKsyncPlugin(zksyncRpcUrl));

async function main() {
  const l1BlockNumber = await web3.eth.getBlockNumber();
  console.log(`Current L1 block number: ${l1BlockNumber}`);
  const l2BlockNumber = await web3.ZKsync.L2.eth.getBlockNumber();
  console.log(`Current L2 block number: ${l2BlockNumber}`);

  const mainContract = await web3.ZKsync.rpc.getMainContract();
  console.log(`Main contract: ${mainContract}`);
}

main().catch(console.error);

Recap

In this tutorial, you’ve learned how to set up a Web3.js project with ZKsync, both by integrating it into an existing project and by starting from scratch using ZKsync CLI. You’ve also explored how to interact with ZKsync specific JSON-RPC methods, such as retrieving the current block number and fetching the main contract address.

Learn More

• To further enhance your skills, explore the examples provided in the ZKsync CLI scripting template found under src/examples. These examples demonstrate additional scripts you can run with Web3.js to interact with ZKsync.
• Refer to the ZKsync Web3.js documentation for more details and code samples to continue building with the Web3.js Plugin.