Online blockchain browser for viewing and analyzing zkSync Era blockchain.
This repository is a monorepo consisting of 4 packages:
- Worker - an indexer service for zkSync Era 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 Era 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.
Also the repository contains integration-test package with a set of API and UI tests. Follow this Readme for more details.
The following diagram illustrates how are the block explorer components connected:
flowchart
subgraph blockchain[Blockchain]
Blockchain[zkSync Era 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
Worker service retrieves aggregated data from the Data Fetcher via HTTP and also directly from the blockchain using zkSync Era 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 Era JSON-RPC API for reading contracts, performing transactions etc.
- β 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.
- Ensure you have
node >= 18.0.0
andnpm >= 9.0.0
installed.
npm install
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.
Build env variables based on your zksync-era local repo setup
Make sure you have zksync-era repo set up locally. You must have your environment variables files present in the zksync-era repo at /etc/env/*.env
for the build envs script to work.
The following script sets .env
files for Worker, Data Fetcher and API packages as well as environment configuration file for App package based on your local zksync-era repo setup.
npm run hyperchain:configure
You can review and edit generated files if you need to change any settings.
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.
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 Era, Postgres DB and all Block Explorer services.
To get block-explorer connected to your ZK Stack Hyperchain you need to set up all the the necessary environment and configuration files with your Hyperchain settings. You can use a script to build them. See Setting up env variables.
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.
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
.
We follow the Conventional Commits specification.
zkSync Era 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.
- Testnet Goerli API: https://block-explorer-api.testnets.zksync.dev
- Testnet Sepolia API: https://block-explorer-api.sepolia.zksync.dev
- Mainnet API: https://block-explorer-api.mainnet.zksync.io
- Testnet Goerli App: https://goerli.explorer.zksync.io
- Testnet Sepolia App: https://sepolia.explorer.zksync.io
- Mainnet App: https://explorer.zksync.io