Running

If you want to just run node with recommended default setting, please see quick start page

This section assumes that you have prepared a configuration file as described on the previous page.

System Requirements for nodes started from DB dumps

This configuration is approximate and should be considered as minimal requirements.

• 6-core CPU

• 10GB RAM

• SSD storage (NVME recommended):

  • Testnet - 10GB VIA node + 10GB PostgreSQL (at the time of writing, will grow over time, so should be constantly monitored)

• 100 Mbps connection (1 Gbps+ recommended)

A note about PostgreSQL storage

By far, the heaviest table to maintain is the call_traces table. This table is only required for the debug namespace. If you want to clear some space and aren't using the debug namespace, you can

• clear it with a simple query DELETE FROM call_traces;

• leave the debug namespace disabled via the EN_API_NAMESPACES env var as described in the example config.

Infrastructure

PostgreSQL

You need to set up a PostgreSQL server, however it is out of the scope of these docs, but the popular choice is to run it in Docker. There are many of guides on that, here's one example.

Note however that if you run PostgresSQL as a stand-alone Docker image (e.g. not in Docker-compose with a network shared between VIA Node and Postgres), VIA Node won't be able to access Postgres via localhost or 127.0.0.1 URLs. To make it work, you'll have to either run it with a --network host (on Linux) or use host.docker.internal instead of localhost in the VIA Node configuration (official docs).

Besides running Postgres, you are expected to have a DB dump from a corresponding env. The DB dumps can be found at:

https://testnet.external-node-db-dumps.onvia.org/<yyyy-mm-dd>/sequencer_testnet.dmp

The DB dumps are available for last 7 days.

For example, in order to get the DB dump for 2025-12-28, the URL would be the following: https://testnet.external-node-db-dumps.onvia.org/2025-12-28/sequencer_testnet.dmp

You can restore it using pg_restore --dbname=<DB_URL> <DUMP_PATH>.

Here is an example of how to restore a DB dump inside a Postgres container.

# change the date of the DB dump
wget https://testnet.external-node-db-dumps.onvia.org/2025-12-28/sequencer_testnet.dmp
docker run -dit --rm --name postgres -e POSTGRES_PASSWORD=notsecurepassword -e POSTGRES_DB=external-node postgres:16.11
docker cp sequencer_testnet.dmp postgres:/
docker exec -it postgres bash
# inside the container
export PGPASSWORD=notsecurepassword
pg_restore -U postgres -d external-node sequencer_testnet.dmp
# or execute the command direclty on container
docker exec postgres -- pg_restore -U postgres -d external-node sequencer_testnet.dmp

Bitcoin node

The Bitcoin node must be fully synchronized with the network (testnet4 or mainnet) for the VIA external node to function correctly. Initial synchronization may take a significant amount of time (2 hours).

Running

Assuming you have the VIA Node Docker image, an env file with the prepared configuration, and you have restored your DB with the pg dump, that is all you need.

Sample running command:

docker run --env-file <path_to_env_file> --mount type=bind,source=<local_rocksdb_data_path>,target=<configured_rocksdb_data_path> <image>

Helm charts for the VIA Node is available here.

First start

When you start the node for the first time, the state in PostgreSQL corresponds to the dump you have used, but the state in RocksDB (mainly the Merkle tree) is absent. Before the node can make any progress, it has to rebuild the state in RocksDB and verify consistency. The exact time required for that depends on the hardware configuration.

Genesis synchronization

While it's technically possible to synchronize a VIA Node from genesis, this process is not recommended for any users. The synchronization algorithm used for VIA Nodes is designed for keeping the live node up-to-date but doesn't implement optimizations to re-execute large amounts of historical blocks. As a result, genesis synchronization on VIA Network can take hours for a single node, and it is not being continuously tested for each release. The node is guaranteed to never be in an incorrect state, but issues unrelated to correctness may occur (such as synchronization getting stuck).

The recommended ways to run the VIA Node are:

• Snapshot synchronization for full nodes (if you don't need historical data).

• Restoration from a DB dump for archival nodes.

Redeploying the VIA node with a new PG dump

If you've been running the VIA node for some time and are going to redeploy it using a new PG dump, you should

• Stop the EN

• Remove SK cache (corresponding to EN_STATE_CACHE_PATH)

• Remove your current DB

• Restore with the new dump

• Start the EN

Monitoring the node behavior and analyzing the state it's in is covered in the observability section.