ZKsync Block Explorer

Online blockchain browser for viewing and analyzing ZKsync blockchain.

📌 Overview

This repository is a monorepo consisting of 4 packages:

• Worker - an indexer service for ZKsync blockchain data. The purpose of the service is to read blockchain data in real time, transform it and fill in it's database with the data in a way that makes it easy to be queried by the API service.
• Data Fetcher - a service that exposes and implements an HTTP endpoint to retrieve aggregated data for a certain block / range of blocks from the blockchain. This endpoint is called by the Worker service.
• API - a service providing Web API for retrieving structured ZKsync blockchain data collected by Worker. It connects to the Worker's database to be able to query the collected data.
• App - a front-end app providing an easy-to-use interface for users to view and inspect transactions, blocks, contracts and more. It makes requests to the API to get the data and presents it in a way that's easy to read and understand.

🏛 Architecture

The following diagram illustrates how are the block explorer components connected:

flowchart
  subgraph blockchain[Blockchain]
    Blockchain[ZKsync JSON-RPC API]
  end

  subgraph explorer[Block explorer]
    Database[("Block explorer DB<br/>(PostgreSQL)")]
    Worker(Worker service)
    Data-Fetcher(Data Fetcher service)
    API(API service)
    App(App)
    
    Worker-."Request aggregated data (HTTP)".->Data-Fetcher
    Data-Fetcher-."Request data (HTTP)".->Blockchain
    Worker-.Save processed data.->Database

    API-.Query data.->Database
    App-."Request data (HTTP)".->API
    App-."Request data (HTTP)".->Blockchain
  end

  Worker-."Request data (HTTP)".->Blockchain

Loading

Worker service retrieves aggregated data from the Data Fetcher via HTTP and also directly from the blockchain using ZKsync JSON-RPC API, processes it and saves into the database. API service is connected to the same database where it gets the data from to handle API requests. It performs only read requests to the database. The front-end App makes HTTP calls to the Block Explorer API to get blockchain data and to the ZKsync JSON-RPC API for reading contracts, performing transactions etc.

🚀 Features

• ✅ View transactions, blocks, transfers and logs.
• ✅ Inspect accounts, contracts, tokens and balances.
• ✅ Verify smart contracts.
• ✅ Interact with smart contracts.
• ✅ Standalone HTTP API.
• ✅ Local node support.

📋 Prerequisites

• Ensure you have node >= 18.0.0 and npm >= 9.0.0 installed.

🛠 Installation

npm install

⚙️ Setting up env variables

Manually set up env variables

Make sure you have set up all the necessary env variables. Follow setting up env variables instructions for Worker, Data Fetcher and API. For the App package you might want to edit environment config, see Environment configs.

Configure custom base token

For networks with a custom base token, make sure to configure the base token for both Worker and API services by following the corresponding instructions here and here.

👨‍💻 Running locally

Before running the solution, make sure you have a database server up and running, you have created a database and set up all the required environment variables. To create a database run the following command:

npm run db:create

To run all the packages (Worker, Data Fetcher, API and front-end App) in development mode run the following command from the root directory.

npm run dev

For production mode run:

npm run build
npm run start

Each component can also be started individually. Follow individual packages README for details.

🐳 Running in Docker

There is a docker compose configuration that allows you to run Block Explorer and all its dependencies in docker. Just run the following command to spin up the whole environment:

docker compose up

It will run local Ethereum node, ZkSync, Postgres DB and all Block Explorer services.

🔍 Verify Block Explorer is up and running

To verify front-end App is running open http://localhost:3010 in your browser. API should be available at http://localhost:3020, Worker at http://localhost:3001 and Data Fetcher at http://localhost:3040.

🎨 Customizing branding and color scheme

The front end supports customization of branding, links, and the color scheme via environment variables or config.js. See the Branding, links, and color scheme section in .env.example.

The color scheme configuration can be set either via the VITE_THEME_CONFIG environment variable (as a JSON string) or directly in the config.js file.

There are 3 ways to define colors:

1. Use standard Tailwind colors (e.g., blue, yellow, green). Shades are defined by Tailwind.
2. Use a single hex color, and all shades will be calculated automatically.
3. Define all shades manually for full control. Example config:

{
  "colors": {
    "primary": {
      "50": "#F3F5FF",
      "100": "#D9D9F9",
      "200": "#CBCBFF",
      "300": "#8C8DFC",
      "400": "#5D65B9",
      "500": "#53579f",
      "600": "#4E529A",
      "700": "#32325D",
      "800": "#27274E",
      "900": "#11142B"
    },
    "secondary": "#FEFCE8",
    "neutral": "gray",
    "success": "green",
    "error": "red",
    "warning": "yellow"
  }
}

Some branding configuration (e.g., icon and logo) is network-specific and can be set in the environment config. See the interface for reference.

🕵️‍♂️ Testing

Run unit tests for all packages:

npm run test

Run e2e tests for all packages:

npm run test:e2e

Run tests for a specific package:

npm run test -w {package}

For more details on testing please check individual packages README.

💻 Conventional Commits

We follow the Conventional Commits specification.

📘 License

ZKsync Block Explorer is distributed under the terms of either

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

🔗 Production links

• Testnet Sepolia API: https://block-explorer-api.sepolia.zksync.dev
• Mainnet API: https://block-explorer-api.mainnet.zksync.io
• Testnet Sepolia App: https://sepolia.explorer.zksync.io
• Mainnet App: https://explorer.zksync.io