Configuration

This document outlines various configuration options for the VIA Node.

The VIA Node requires the definition of numerous environment variables. To streamline this process, we provide prepared configs which can be used as a starting point and modify only the necessary sections.

Testnet coinfiguration:

# ------------------------------------------------------------------------
# -------------- YOU MUST CHANGE THE FOLLOWING VARIABLES -----------------
# ------------------------------------------------------------------------

# URL of the Postgres DB.
DATABASE_URL=postgres://postgres:notsecurepassword@localhost/via_local_ext_node
# PostgreSQL connection pool size
DATABASE_POOL_SIZE=50

# Folder where the state_keeper cache will be stored (RocksDB).
# If containerized, this path should be mounted to a volume.
EN_STATE_CACHE_PATH=./db/ext-node/state_keeper
# Folder where the Merkle Tree will be stored (RocksDB).
# If containerized, this path should be mounted to a volume.
EN_MERKLE_TREE_PATH=./db/ext-node/lightweight

# ------------------------------------------------------------------------
# -------------- YOU MAY CONFIGURE THE FOLLOWING VARIABLES ---------------
# ------------------------------------------------------------------------

# Port on which to serve the HTTP JSONRPC API.
EN_HTTP_PORT=3060
# Port on which to serve the WebSocket JSONRPC API.
EN_WS_PORT=3061

# Port on which to serve metrics to be collected by Prometheus.
# If not set, metrics won't be collected.
# EN_PROMETHEUS_PORT=3322

# Port on which to serve the healthcheck endpoint (to check if the service is live).
EN_HEALTHCHECK_PORT=3081

# Max possible limit of entities to be requested at once.
EN_REQ_ENTITIES_LIMIT=10000
# Max possible limit of filters to be active at once.
EN_FILTERS_LIMIT=10000
# Max possible limit of subscriptions to be active at once.
EN_SUBSCRIPTIONS_LIMIT=10000
# Interval for polling the DB for pubsub (in ms).
EN_PUBSUB_POLLING_INTERVAL=200
# Tx nonce: how far ahead from the committed nonce can it be.
# This shouldn't be larger than the value on the main node (50).
EN_MAX_NONCE_AHEAD=50
# The multiplier to use when suggesting gas price. Should be higher than one,
# otherwise if the L1 prices soar, the suggested gas price won't be sufficient to be included in block.
EN_GAS_PRICE_SCALE_FACTOR=1.2
# The factor by which to scale the gasLimit
EN_ESTIMATE_GAS_SCALE_FACTOR=1.2
# The max possible number of gas that `eth_estimateGas` is allowed to overestimate.
EN_ESTIMATE_GAS_ACCEPTABLE_OVERESTIMATION=1000
# Max possible size of an ABI encoded tx (in bytes).
# This shouldn't be larger than the value on the main node.
EN_MAX_TX_SIZE=1000000
# Enabled JSON-RPC API namespaces. Also available: en, debug.
EN_API_NAMESPACES=via,eth,web3,net,pubsub,zks

# Bitcoin network
VIA_BTC_CLIENT_NETWORK=testnet4
# URL of the Bitcoin node
VIA_BTC_CLIENT_RPC_URL=http://bitcoind:48332
# RPC user of the Bitcoin node
VIA_BTC_CLIENT_RPC_USER=rpcuser
# RPC password of the Bitcoin node
VIA_BTC_CLIENT_RPC_PASSWORD=rpcpassword
# URL to API which provides Bitcoin fee rate.
VIA_BTC_CLIENT_EXTERNAL_APIS=https://mempool.space/testnet4/api/v1/fees/recommended
# Fee estimation strategy
VIA_BTC_CLIENT_FEE_STRATEGIES=fastestFee
# Set to true to prioritize the Bitcoin RPC for fee estimation over external APIs.
VIA_BTC_CLIENT_USE_RPC_FOR_FEE_RATE=true
# Bridge address on Bitcoin network.
VIA_BRIDGE_BRIDGE_ADDRESS=tb1ppsy8j80jtns42rkpdsfcv25qfschqejxmk6datkvu236eekr4fms06wnz0
# Verifiers public keys which signed the bridge transaction.
VIA_BRIDGE_VERIFIERS_PUB_KEYS=0302ede5e1f0a6ceedf0c4263bb47b803973a3ffa4968b147c1d0f38c62f8c45df,023e01e4e2ff564b0fd159d94e1549fddf605f077a8c143e7a4f555adbeb324fe1
# Bootstrap transactions which contain genesis and system setup.
VIA_GENESIS_BOOTSTRAP_TXIDS=c89e5db75e74700582d106f1c0aa85f7b0df1436cecd3a6536f11bed9db0f407

# Settings related to sentry and opentelemetry.
MISC_LOG_FORMAT=plain
MISC_SENTRY_URL=unset
MISC_SENTRY_PANIC_INTERVAL=1800
MISC_SENTRY_ERROR_INTERVAL=10800
MISC_OTLP_URL=unset

# Settings related to Rust logging and backtraces.
# You can read about the format [here](https://docs.rs/env_logger/0.10.0/env_logger/#enabling-logging) to fine-tune logging.
RUST_LOG=zksync_core=debug,zksync_dal=info,zksync_eth_client=info,zksync_merkle_tree=info,zksync_storage=info,zksync_state=debug,zksync_types=info,vm=info,zksync_external_node=info,zksync_utils=debug,
RUST_BACKTRACE=full
RUST_LIB_BACKTRACE=1

# ------------------------------------------------------------------------
# -------------- THE FOLLOWING VARIABLES DEPEND ON THE ENV ---------------
# ------------------------------------------------------------------------

# URL of the main ZKsync node.
EN_MAIN_NODE_URL=https://testnet.via.onvia.org

EN_L2_CHAIN_ID=25223
EN_L1_CHAIN_ID=11155111

# Optional, required only if sentry is configured. 
EN_SENTRY_ENVIRONMENT=via_testnet

# ------------------------------------------------------------------------
# -------------- THE FOLLOWING VARIABLES ARE NOT USED --------------------
# -------------- BUT HAVE TO BE SET. JUST LEAVE THEM AS IS ---------------
# ------------------------------------------------------------------------

VIA_HOME=/
EN_ETH_CLIENT_URL=http://127.0.0.1:8545

You can also see docker-compose setup if you want to run external-node on your machine with recommended default settings (testnet).

Database

The VIA Node uses two databases: PostgreSQL and RocksDB.

PostgreSQL serves as the main source of truth in the EN, so all the API requests fetch the state from there. The PostgreSQL connection is configured by the DATABASE_URL. Additionally, the DATABASE_POOL_SIZE variable defines the size of the connection pool.

RocksDB is used in components where IO is a bottleneck, such as the State Keeper and the Merkle tree. If possible, it is recommended to use an NVME SSD for RocksDB. RocksDB requires two variables to be set: EN_STATE_CACHE_PATH and EN_MERKLE_TREE_PATH, which must point to different directories. When running a Node inside Docker Compose, Kubernetes etc., these paths should point to dirs in a persistent volume (or 2 separate volumes). Persistent volumes must be exclusive to a node; i.e., they must not be shared among nodes concurrently or transferred from one node to another. Failing to adhere to this rule may result in RocksDB corruption or the Node crashing on start.

L1 Web3 client

The VIA Node requires a connection to a Bitcoin node. The env variables are:

• VIA_BTC_CLIENT_NETWORK - The Bitcoin network (e.g. testnet4 or mainnet).

• VIA_BTC_CLIENT_RPC_URL - The URL of the Bitcoin node.

• VIA_BTC_CLIENT_RPC_USER - The RPC user of the Bitcoin node.

• VIA_BTC_CLIENT_RPC_PASSWORD - The RPC password of the Bitcoin node.

• VIA_BTC_CLIENT_EXTERNAL_APIS - URL to API which provides Bitcoin fee rate.

• VIA_BTC_CLIENT_FEE_STRATEGIES - The fee estimation strategy (e.g., fastestFee).

• VIA_BTC_CLIENT_USE_RPC_FOR_FEE_RATE - Set to true to prioritize the Bitcoin RPC for fee estimation over external APIs.

Currently, the VIA Node makes 2 requests to the L1 per L1 batch, so the Web3 client usage for a synced node should not be high. However, during the synchronization phase the new batches would be persisted on the VIA Node quickly, so make sure that the L1 client won't exceed any limits (e.g. in case you use Bitcoin RPC providers).

Exposed ports

The dockerized version of the server exposes the following ports:

• HTTP JSON-RPC: 3060

• WebSocket JSON-RPC: 3061

• Prometheus listener: 3322

• Healthcheck server: 3081

While the configuration variables for them exist, you are not expected to change them unless you want to use the EN outside of provided docker environment (not supported at the time of writing).

API limits

There are variables that allow you to fine-tune the limits of the RPC servers, such as limits on the number of returned entries or the limit for the accepted transaction size. Provided files contain sane defaults that are recommended for use, but these can be edited, e.g. to make the VIA Node more/less restrictive.

JSON-RPC API namespaces

There are 7 total supported API namespaces: eth, net, web3, debug - standard ones; zks, via- rollup-specific one; pubsub - a.k.a. eth_subscribe; en - used by VIA nodes while syncing. You can configure what namespaces you want to enable using EN_API_NAMESPACES and specifying namespace names in a comma-separated list. By default, all but the debug namespace are enabled.

Logging and observability

MISC_LOG_FORMAT defines the format in which logs are shown: plain corresponds to the human-readable format, while the other option is json (recommended for deployments).

RUST_LOG variable allows you to set up the logs granularity (e.g. make the VIA Node emit fewer logs). You can read about the format here.

MISC_SENTRY_URL and MISC_OTLP_URL variables can be configured to set up Sentry and OpenTelemetry exporters.

If Sentry is configured, you also have to set EN_SENTRY_ENVIRONMENT variable to configure the environment in events reported to sentry.