Run Zircuit

Overview

Run your own Public Zircuit Node or Partner Zircuit Node on Mainnet or Garfield-Testnet. This guide covers setup, configuration, and operations for both public and partner node operators.

Prerequisites

System Requirements

OS: Linux or macOS
Python: 3.11 or higher
Storage:
- Type: Solid State
- Garfield-Testnet: 200-300 GB initially (grows over time as network progresses)
- Mainnet: 750-1000 GB initially (grows over time as network progresses)
CPU: 4 cores recommended
RAM: 16 GB recommended
Software:
- Docker + Docker Compose (required),
- lz4 (for snapshot decompression, required),
- aria2c (for accelerating snapshot downloads, optional but strongly recommended)
- sha256 utils (for verifying snapshot integrity, required)

For testing on a desktop computer, both Docker Desktop (with Compose extension) and Podman Desktop (with Compose extension) should work.

Quick Start

Get the Script

Make a new directory and download the node controller script to it:

mkdir -p my-public-zircuit-node
cd my-public-zircuit-node
curl -sS https://bootstrap.mainnet.zircuit.com/zircuit -o zircuit
chmod +x zircuit

Initialize as a Public Node

Testnet (default)

./zircuit init

Mainnet

./zircuit init --network mainnet

The above commands will:

Synchronize the latest chaindata snapshot.
Generate node identity files (JWT secret, P2P key).
Create configuration files for use with Docker Compose.
Request a unique node name from our bootstrap service.
Load network-specific configuration from embedded defaults and remote bootstrap server.

After initialization, your directory will contain:

test-node/
├── docker-compose.yml          # Docker services configuration
├── env-l2geth                  # Environment variables for l2geth
├── env-op_node                 # Environment variables for op-node
├── env-partner                 # Environment variables for partner mode, only if partner mode is enabled
├── env-zircuit                 # Environment variables for zircuit
├── gethconfig.toml             # Geth configuration
├── jwt-secret.txt              # Authentication secret
├── l2-replica-data/            # l2geth data directory
├── op-replica-log/             # op-node data directory
├── p2p-node-key.txt            # P2P identity key
├── zircuit-garfield-...tar.lz4 # Downloaded snapshot (compressed)
├── zircuit-garfield-...tar.txt # Fingerprint (sha256) for downloaded snapshot
└── zircuit                     # Node controller script

Start Node

./zircuit up

This command will:

Check that the Docker daemon is running.
Start the Docker containers (l2geth and op-node).
Begin syncing with the Zircuit network.
Connect to P2P peers.
Start serving RPC endpoints.

Monitor Logs

./zircuit logs

This shows the last 1000 lines and then follows (live-tails) new logs. Press Ctrl+C to exit.

Available Commands

Command

Description

./zircuit init

Initialize the node from scratch

./zircuit sync

Sync a new chaindata snapshot

./zircuit up

Start the node

./zircuit down

Stop the node

./zircuit restart

Restart the node

./zircuit logs

View the node logs (last 1000 lines + live tail)

./zircuit update

Update the node version and node configuration

Configuration Options

General Options

./zircuit --help

Key options:

-d|--debug: Raises the log level from INFO to DEBUG.

Initialization Options

./zircuit init --help

Key options:

-env|-n KEY=VALUE: Sets extra environment variables for both l2geth and op-node.
--force: Forces complete (re-)initialization of Zircuit Node.
--network|-n garfield-testnet|mainnet: Selects the Zircuit network to operate in. (default: garfield-testnet)
--mode|-m public|partner : Select the mode to operate in. (default: public)
--skip-snapshot-sync: Skips downloading the latest snapshot.
--snapshot-name: Use an already downloaded snapshot.
--version <VERSION>: Overrides the version of Zircuit Node to run.
--version-stream release|pre-release: Sets the version stream to follow. (default: release)

Examples:

# Default initialization
./zircuit init

# Initialize without downloading snapshot
./zircuit init --skip-snapshot-sync

# Initialize with existing snapshot
./zircuit init --skip-snapshot-sync --snapshot-name snapshot-garfield.tar.lz4

# Initialize mainnet node
./zircuit init --network mainnet

Public vs. Partner Nodes

Public Nodes (Default)

Ready to use without additional configuration.
Uses public L1 RPC endpoints (rate-limited).
Defaults to Garfield-Testnet (use --network mainnet for Mainnet).
Configuration loaded from embedded defaults and bootstrap server

Partner Nodes (Advanced)

./zircuit init --mode partner

Requires configuration of:

Node name for ETH Stats (if integration is enabled)
ETH Stats shared secret (if integration is enabled)
Custom L1 RPC endpoint
Custom L1 Beacon URL
Zircuit L2 RPC endpoint

For the L1 endpoints, you may set the endpoints provided by PublicNode but the same performance caveat applies.

Important Notes

Performance Warnings

The script will display warnings when using public infrastructure:

"Your Zircuit Node is using a rate-limited L1 RPC endpoint"
"Your Zircuit Node is using a rate-limited L1 Beacon endpoint"

For optimal performance, consider configuring dedicated L1 endpoints.

Updates

The node automatically checks for updates every 30 minutes (configurable). When updates are available:

Check logs for update notifications
Run ./zircuit update
Run ./zircuit restart to apply changes

Snapshots

Snapshots are provided by Liquify and automatically managed:

Latest snapshots are automatically downloaded during initialization
SHA256 fingerprint verification ensures integrity
Snapshots use lz4 compression for faster downloads
Download methods:
- aria2c: Used if detected on system (faster, parallel downloads)
- Built-in Python: Fallback method if aria2c not available (fallback, more compatible)
Optionally skip download with --skip-snapshot-sync
Optionally use existing snapshot with --snapshot-name

Configuration Cascade

The node uses a configuration cascade system:

Embedded defaults: Network-specific public bootstrap configuration built into the script.
Remote configuration: Network-specific configuration fetched from the bootstrap server.
Local overrides: Custom settings via command-line options or environment variables.

This ensures nodes always have working defaults while allowing customization and remote updates.

Troubleshooting

Common Issues

Docker not running: Ensure Docker daemon is started.
Insufficient disk space: Ensure sufficient free space (see System Requirements above).
Missing lz4: Install lz4 for snapshot decompression.
Network connectivity: Check firewall settings for P2P ports.
Interrupted snapshot download: The built-in Python download method does NOT support resuming interrupted downloads. If your download fails, you must restart from the beginning. To avoid this:
- Install aria2c for more reliable downloads with support for parallel downloads and resume.
- Ensure stable network connection before starting large downloads (especially Mainnet's ~200 GB snapshot)
- Consider using --skip-snapshot-sync and downloading the snapshot manually (see below).
429 Too Many Requests: If you're seeing this message in the op-node logs, you need to get a PublicNode token. Sign up at https://www.allnodes.com/publicnode, generate links for Sepolia RPC and Sepolia Beacon APIs, and re-initialize your Zircuit Node with the following two additional enviromnent variables:
- OP_NODE_L1_BEACON, and
- OP_NODE_L1_ETH_RPC .
For example, if the links generated by AllNodes are:
- https://ethereum-sepolia-beacon-api.publicnode.com/d7d55ad98cbb19d147fa42a559ee7ebd02e2026115fb5b819dae81db3b25f544,and
- https://ethereum-sepolia-rpc.publicnode.com/d7d55ad98cbb19d147fa42a559ee7ebd02e2026115fb5b819dae81db3b25f544
then add the following to your init command: -e OP_NODE_L1_BEACON=https://ethereum-sepolia-beacon-api.publicnode.com/d7d55ad98cbb19d147fa42a559ee7ebd02e2026115fb5b819dae81db3b25f544 -e OP_NODE_L1_ETH_RPC=https://ethereum-sepolia-rpc.publicnode.com/d7d55ad98cbb19d147fa42a559ee7ebd02e2026115fb5b819dae81db3b25f544 . (Note that these aren't real tokens and will not work.)

Manual Snapshot Download

If you experience issues with automatic snapshot downloads, you can download snapshots manually:

Garfield-Testnet

# Get the latest snapshot filename
SNAPSHOT=$(curl -sS https://zircuit-snapshot.liquify.com/files/garfield-testnet/latest_compressed_zircuit.txt)

# Download the snapshot
wget https://zircuit-snapshot.liquify.com/files/garfield-testnet/$SNAPSHOT
# or use aria2c for resume support:
aria2c -x 16 -s 16 https://zircuit-snapshot.liquify.com/files/garfield-testnet/$SNAPSHOT

# Download the verification file
wget https://zircuit-snapshot.liquify.com/files/garfield-testnet/$SNAPSHOT.sha256

# Initialize with the downloaded snapshot
./zircuit init --skip-snapshot-sync --snapshot-name $SNAPSHOT

Mainnet

# Get the latest snapshot filename
SNAPSHOT=$(curl -sS https://zircuit-snapshot.liquify.com/files/mainnet/latest_compressed_zircuit.txt)

# Download the snapshot
wget https://zircuit-snapshot.liquify.com/files/mainnet/$SNAPSHOT
# or use aria2c for resume support (recommended for 200 GB download):
aria2c -x 16 -s 16 https://zircuit-snapshot.liquify.com/files/mainnet/$SNAPSHOT

# Download the verification file
wget https://zircuit-snapshot.liquify.com/files/mainnet/$SNAPSHOT.sha256

# Initialize with the downloaded snapshot
./zircuit init --network mainnet --skip-snapshot-sync --snapshot-name $SNAPSHOT

Note: The aria2c command uses 16 connections (-x 16) and splits the download into 16 segments (-s 16) for faster downloads and automatic resume on interruption.