TON Node Command-Line Flags Documentation

This document describes the various flags and options available when running a TON node. Each flag has a short name, a long name, a default value (if applicable), and a description of its functionality.

General Options

• -v, --verbosity

• Description: Sets the verbosity level of the log output.

• Default: INFO (represented by 2 in the code).

• Usage: -v <level>

• Example: -v 2

• -V, --version

• Description: Shows validator-engine build information.

• Default: N/A

• Usage: -V

• -h, --help

• Description: Prints help information.

• Default: N/A

• Usage: -h

• -C, --global-config

• Description: Specifies the file to read global configuration (bootstrap nodes, public liteservers, init blocks etc). Example can be found here: https://github.com/ton-blockchain/ton-blockchain.github.io/blob/main/testnet-global.config.json

• Default: N/A

• Usage: -C <file>

• -c, --local-config

• Description: Specifies the file to write and read local node configuration: this node adnl addresses, public key for LS and validator console access, etc

• Default: N/A

• Usage: -c <file>

• -I, --ip

• Description: Specifies the IP address and port of the instance. Should be used during first run to create configuration, can be ommited later.

• Default: N/A

• Usage: -I <ip:port>

• -D, --db

• Description: Specifies the root directory for the databases. Usually /var/ton-work/db is used.

• Default: N/A

• Usage: -D <path>

• -f, --fift-dir

• Description: Specifies the directory with Fift scripts.

• Default: N/A

• Usage: -f <path>

• -d, --daemonize

• Description: Daemonizes the process by closing standard input and creating a new session.

• Default: Disabled

• Usage: -d

• -l, --logname

• Description: Specifies the log file to write logs.

• Default: N/A

• Usage: -l <file>

• -s, --state-ttl

• Description: Sets the TTL (time-to-live) for the state in seconds.

• Default: 86400 seconds (1 day)

• Usage: -s <seconds>

• -m, --mempool-num

• Description: Specifies the maximum number of external messages in the mempool.

• Default: Unlimited

• Usage: -m <number>

• -b, --block-ttl

• Description: Sets the TTL (time-to-live) for blocks in seconds.

• Default: 86400 seconds (1 day)

• Usage: -b <seconds>

• -A, --archive-ttl

• Description: Sets the TTL for archived blocks in seconds.

• Default: 604800 seconds (7 days)

• Usage: -A <seconds>

• -K, --key-proof-ttl

• Description: Sets the TTL for key blocks in seconds.

• Default: 315360000 seconds (10 years)

• Usage: -K <seconds>

• -S, --sync-before

• Description: During initial sync, download all blocks for the last given number of seconds.

• Default: 3600 seconds (1 hour)

• Usage: -S <seconds>

• -t, --threads

• Description: Specifies the number of threads to use.

• Default: 7

• Usage: -t <number>

• -u, --user

• Description: Changes the user running the process.

• Default: N/A

• Usage: -u <username>

Advanced Options

• --shutdown-at

• Description: Schedules the validator to shut down at the given Unix timestamp.

• Default: N/A

• Usage: --shutdown-at <timestamp>

• -T, --truncate-db

• Description: Truncates the database with the specified sequence number as the new top masterchain block sequence number.

• Default: N/A

• Usage: -T <seqno>

• -U, --unsafe-catchain-restore

• Description: Enables the slow and dangerous catchain recovery method.

• Default: Disabled

• Usage: -U <catchain-seqno>

• -F, --unsafe-catchain-rotate

• Description: Enables forceful and dangerous catchain rotation.

• Default: Disabled

• Usage: -F <block-seqno>:<catchain-seqno>:<height>

• --celldb-compress-depth

• Description: Optimizes CellDb by storing cells of depth X with whole subtrees.

• Default: 0 (disabled)

• Usage: --celldb-compress-depth <depth>

• --max-archive-fd

• Description: Sets a limit on the number of open file descriptors in the archive manager. 0 for unlimited.

• Default: 0 (unlimited)

• Usage: --max-archive-fd <number>

• --archive-preload-period

• Description: Preloads archive slices for the past X seconds on startup.

• Default: 0 seconds (disabled)

• Usage: --archive-preload-period <seconds>

• --enable-precompiled-smc

• Description: Enables execution of precompiled smart contracts (experimental).

• Default: Disabled

• Usage: --enable-precompiled-smc

• --disable-rocksdb-stats

• Description: Disables the gathering of RocksDb statistics.

• Default: Enabled

• Usage: --disable-rocksdb-stats

• --nonfinal-ls

• Description: Enables special local state (LS) queries to non-finalized blocks.

• Default: Disabled

• Usage: --nonfinal-ls

• --celldb-cache-size

• Description: Sets the block cache size for RocksDb in CellDb, in bytes.

• Default: 1G (1 Gigabyte)

• Usage: --celldb-cache-size <size>

• --celldb-direct-io

• Description: Enables direct I/O mode for RocksDb in CellDb (only applies when cache size is >= 30G).

• Default: Disabled

• Usage: --celldb-direct-io

• --celldb-preload-all

• Description: Preloads all cells from CellDb on startup.

• Default: Disabled

• Usage: --celldb-preload-all

• --catchain-max-block-delay

• Description: Sets the delay before creating a new catchain block, in seconds.

• Default: 0.4 seconds

• Usage: --catchain-max-block-delay <seconds>

• --catchain-max-block-delay-slow

• Description: Sets the maximum extended catchain block delay for too long rounds, in seconds.

• Default: 1.0 seconds

• Usage: --catchain-max-block-delay-slow <seconds>

• --fast-state-serializer

• Description: Enables a faster persistent state serializer, which requires more RAM (enabled automatically on machines with >= 90GB RAM).

• Default: Disabled

• Usage: --fast-state-serializer

Session Logs Options

• --session-logs
• Description: Specifies the file for validator session statistics.
• Default: {logname}.session-stats
• Usage: --session-logs <file>

This documentation provides an overview of the options

available for configuring and running a TON validator node. Each option allows customization to suit various deployment scenarios.