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.

Start zkLink Nova Self-hosted RPC Node

To start a mainnet instance, run:

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
docker compose -f docker-compose.yml up

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.

Note

The node will recover from a snapshot on it's first run, this may take up to 10 hours. Before the recovery is finished, the API server won't serve any requests.

Using Snapshot to Run zkLink Nova self-hosted RPC Node locally

Currently, zkLink Nova provides periodic database snapshot of the External Node to shorten the synchronization time for running a self-hosted node. The latest database snapshot can be found here. Note that the database snapshot size for zkLink Nova's External Node is approximately 1 TB, so please prepare sufficient disk space in advance.

The process to import the database snapshot into PostgreSQL is as follows:

Shell

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

After the import is completed, start the service normally as described in the previous section.

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.