Run a Node

Introduction

zkLink Nova self-hosted RPC node is based on zkSync external node. You can find detailed information about zkSync external node here. This section focus on how to build a zkLink Nova self-hosted RPC node.

Quick Start

Preferred hardware configuration

This configuration is approximate, expect updates to these specs.

• Architecture: AMD64

• CPU: 32 core

• RAM: 64 GB

• Storage:

  • Testnet - ~1 TB (at the time of writing) and will grow over time, so should be constantly monitored

  • Mainnet - ~2 TB (at the time of writing) and will grow over time, so should be constantly monitored

  • NVMe recommended

• Network: 100 Mbps network connection.

Software Prerequisites

You can follow Docker's official manuals to install docker compose and Docker.

Running zkLink Nova self-hosted RPC Node locally

We offer a docker-compose file to facilitate running a zkLink Nova self-hosted rpc node locally.

Create data folder

sudo mkdir -p /data/mainnet-postgres
sudo mkdir -p /data/mainnet-rocksdb
sudo mkdir -p /data/mainnet-prometheus-data
sudo mkdir -p /data/mainnet-grafana-data
sudo mkdir -p /data/prometheus
sudo touch /data/prometheus/prometheus.yml

start pg sevice

cd /data && wget https://github.com/zkLinkProtocol/zksync-era/raw/zklink/docs/guides/external-node/docker-compose-examples/docker-compose.yml
docker-compose -f docker-compose.yml up -d postgres

Import backup data from Snapshot

Shell

cd /data/mainnet-postgres && wget https://zklink-nova-en-snapshot.s3.ap-east-1.amazonaws.com/zklink_nova_en_snapshot.backup
docker exec -it <postgres container id> bash
psql -U postgres -p 5430 -c "create database zklink_ext_node"
pg_restore -U postgres -p 5430 -d zklink_ext_node -j $(nproc) /var/lib/postgresql/data/zklink_nova_en_snapshot.backup

Start zkLink Nova Self-hosted RPC Node

To start a mainnet instance, run:

docker compose -f docker-compose.yml up -d

To reset its state, run:

docker compose -f docker-compose.yml down --volumes

You can see the status of the node (after recovery) in the local Grafana dashboard. Those commands start external node locally inside docker. The HTTP JSON-RPC API can be accessed on port 3060 and WebSocket API can be accessed on port 3061.

Tips

After importing the data, the blocks will be scanned to restore the Merkle tree with ​2000 batches per hour speed. Block synchronization will continue only after the recovery is complete. The speed of importing snapshot data into Postgres is 100G/h, the speed of rebuilding the Merkle tree is 2000 batches/h, with the specific time depending on the database snapshot.

Get local latest block

curl http://localhost:3060 -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

When first start service, it will take 5 hours to struct Merkle tree.

Building External Node from Source Code

This document outlines how to build the External Node from the zkLink Nova source code, supporting three ways:

1. Building the binary file for the External Node directly from the source code.

2. Building the Docker image for the External Node directly from the source code.

3. Customizing the Docker image for the External Node built from the source code.

Install Dependencies

Run the following commands to install the necessary dependencies.

Note: If you only wish to build the Docker image for the zkLink Nova External Node from the source code, you only need to install the Docker-related dependencies.

Rust and Tools

# Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# SQL tools
cargo install sqlx-cli --version 0.7.3

NVM and Node/Yarn

# NVM
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash

# Node & Yarn
nvm install 18
npm install -g yarn
yarn set version 1.22.19

System Software

# All necessary packages
sudo apt-get update
sudo apt-get install build-essential pkg-config cmake clang lldb lld libssl-dev
postgresql ca-certificates curl

Docker

# Docker installation
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o
/etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc]
https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
sudo apt-get install docker-ce docker-compose docker-ce-cli containerd.io docker-
buildx-plugin docker-compose-plugin -y
sudo usermod -aG docker <YOUR_USER>

Pulling Source Code

Use the command below to pull the zkLink Nova source code and fetch the submodules. If you wish to build code related to the zkLink Nova Sepolia testnet, please use the zklink_testnet branch.

git clone -b zklink https://github.com/zkLinkProtocol/zksync-era.git
cd zksync-era
git submodule update --init --recursive
# Initialize build system
zk
# Build contract artifacts
zk compiler system-contracts
zk contract build

Run the command below to set up the working directory:

echo -e "export ZKSYNC_HOME=$(pwd)\nexport PATH=\$ZKSYNC_HOME/bin:\$PATH" >>
~/.bashrc && source ~/.bashrc

Build the External Node

If you only wish to build the binary file for the External Node

Execute the command below; the results will be located in the target/release directory.

cargo build --release

If you want to build the Docker image for the External Node from source

Run the command below:

docker build -f docker/external-node/Dockerfile . -t <image name>:<tag>

If you want to customize the Docker image for the External Node

Refer to all the BUILD and COPY commands in the docker/external-node/Dockerfile file to customize the Docker image for the zkLink Nova External Node.