Skip to main content

Archive node

info

Before this article, read about Full Node.

Overview​

An archive node is a type of full node that stores extended historical data from a blockchain. If you are creating a blockchain explorer or a similar application that requires access to historical data, it is recommended that you use an archive node as an indexer.

OS requirements​

We highly recommend installing mytonctrl using the supported operating systems:

  • Ubuntu 20.04
  • Ubuntu 22.04
  • Debian 11

Minimal hardware requirements​

  • 16-core CPU
  • 128 GB ECC Memory
  • 12 TB SSD OR Provisioned 64+k IOPS storage
  • 1 Gbit/s network connectivity, both inbound and outbound
  • 16 TB/month traffic on peak load
  • Linux OS with open files limit above 400k
  • A public IP address (fixed IP address)
Data compression

Uncompressed data requires 12 TB of storage. A ZFS volume with compression reduces this to 11 TB. As of February 2025, the data volume is growing by approximately 0.1 to 1 TB per month, depending on the load.

Installation​

Install ZFS and prepare volume​

Dumps come in the form of ZFS snapshots compressed using plzip. You need to install ZFS on your host and restore the dump. See Oracle Documentation for more details.

Usually, it's a good idea to create a separate ZFS pool for your node on a dedicated SSD drive. This will allow you to manage storage space and back up your node easily.

  1. Install ZFS:
sudo apt install zfsutils-linux
  1. Create a pool on your dedicated 4 TB <disk> and name it data:
sudo zpool create data <disk>
  1. We recommend enabling compression on the parent ZFS filesystem before restoring. This will save you a significant amount of space. To enable compression for the data volume, use the root account to enter the following:
sudo zfs set compression=lz4 data

Install MyTonCtrl​

Please use the Running Full Node guide to install and run mytonctrl.

Run an archive node​

Prepare the node​

  1. Before performing a restore, you must stop the validator using the root account:
sudo -s
systemctl stop validator.service
  1. Make a backup of ton-work config files (we will need /var/ton-work/db/config.json, /var/ton-work/keys, and /var/ton-work/db/keyring):
mv /var/ton-work /var/ton-work.bak

Download the dump​

Here is an example command to download & restore the mainnet dump from the ton.org server:

curl -L -s https://archival-dump.ton.org/dumps/mainnet_full_44888096.zfs.zstd | pv | zstd -d -T16 | zfs recv mypool/ton-db

To install the testnet dump, use:

wget -c https://dump.ton.org/dumps/latest_testnet_archival.zfs.lz | pv | plzip -d -n <cores> | zfs recv data/ton-work

The mainnet dump size is approximately 9 TB, so it may take several days to download and restore. The dump size will increase as the network grows.

Prepare and run the command:

  1. Install the necessary tools (pv, plzip, zstd).
  2. Tell plzip to use as many cores as your machine allows to speed up extraction (-n).

Mount the dump​

  1. Mount ZFS:
zfs set mountpoint=/var/ton-work data/ton-work && zfs mount data/ton-work
  1. Restore db/config.json, keys, and db/keyring from the backup to /var/ton-work:
cp /var/ton-work.bak/db/config.json /var/ton-work/db/config.json
cp -r /var/ton-work.bak/keys /var/ton-work/keys
cp -r /var/ton-work.bak/db/keyring /var/ton-work/db/keyring
  1. Set the permissions for the /var/ton-work and /var/ton-work/keys directories correctly:
  • The owner of the /var/ton-work/db directory should be the validator user:
chown -R validator:validator /var/ton-work/db
  • The owner of the /var/ton-work/keys directory should be the ubuntu user:
chown -R ubuntu:ubuntu /var/ton-work/keys

Update configuration​

Update the node configuration for the archive node.

  1. Open the node config file /etc/systemd/system/validator.service:
nano /etc/systemd/system/validator.service
  1. Add storage settings for the node in the ExecStart line:
--state-ttl 3153600000 --archive-ttl 3153600000
info

Please remain patient after starting the node and monitor the logs closely. The dump files lack DHT caches, requiring your node to discover other nodes and synchronize with them. Depending on the snapshot's age and your network bandwidth, your node might need anywhere from several hours to multiple days to synchronize with the network. The synchronization process typically takes up to 5 days when using minimum hardware specifications. This is expected behavior.

caution

If the node sync process has already taken 5 days, but the node is still out of sync, you should check the troubleshooting section.

Start the node​

  1. Start the validator by running the command:
systemctl start validator.service
  1. Open mytonctrl from the local user and check the node status using the status command.

Node maintenance​

The node database requires cleansing from time to time (we advise doing this once a week). To do so, please perform the following steps as root:

  1. Stop the validator process (Never skip this!):
sudo -s
systemctl stop validator.service
  1. Remove old logs:
find /var/ton-work -name 'LOG.old*' -exec rm {} +
  1. Remove temporary files:
rm -r /var/ton-work/db/files/packages/temp.archive.*
  1. Start the validator process:
systemctl start validator.service

Troubleshooting and backups​

If, for some reason, something does not work or breaks, you can always roll back to the @archstate snapshot on your ZFS filesystem. This is the original state from the dump.

  1. Stop the validator process (Never skip this!):
sudo -s
systemctl stop validator.service
  1. Check the snapshot name:
zfs list -t snapshot
  1. Roll back to the snapshot:
zfs rollback data/ton-work@dumpstate

If your node operates properly, you may remove this snapshot to reclaim storage space. However, we recommend creating regular filesystem snapshots for rollback capability since the validator node may occasionally corrupt data and config.json. For automated snapshot management, zfsnap handles rotation effectively.

Need help?

Have a question or need help? Please ask in the TON dev chat to get help from the community. MyTonCtrl developers also hang out there.

Tips & tricks​

info

Basic info about archival dumps is present at https://archival-dump.ton.org/

Remove dump snapshot​

  1. Find the correct snapshot
zfs list -t snapshot
  1. Delete it
zfs destroy <snapshot>

Force the archive node not to store blocks​

To force the node not to store archive blocks, use the value 86400. Check the set_node_argument section for more details.

installer set_node_argument --archive-ttl 86400

Support​

Contact technical support at @mytonctrl_help.

See also​