Node configuration reference

Top-level fields

log_config_name

Path to the loggers YAML configuration file. Relative paths are resolved from the directory containing config.json.

Type	Required	Default
string | null	no	null; falls back to console output at info level.

In the Helm chart, set this field to "/main/logs.config.yml".

ton_global_config_name

Path to the global network config. Determines which network the node joins.

Type	Required	Default
string | null	yes	null

In the Helm chart, always set to "/main/global.config.json".

internal_db_path

Path to the node’s internal database directory. Stores blocks, states, indexes, and other persistent data. Requires substantial disk space; on mainnet, storage requirements are typically hundreds of gigabytes.

Type	Required	Default
string | null	no	"node_db"

In the Helm chart, always set to "/db", where the database PVC is mounted.

restore_db

Enable database integrity check and repair on startup.

Type	Required	Default
bool	no	false

boot_from_zerostate

If true, the node starts synchronization from the zero state, which is the genesis block, instead of the init_block specified in the global config. This increases sync time but verifies the entire blockchain history from genesis.

Type	Required	Default
bool | null	no	false

sync_by_archives

If true, the node syncs by downloading block archives. Faster than block-by-block sync but requires peers that serve archives.

Type	Required	Default
bool	no	true

skip_saving_persistent_states

If true, the node skips saving periodic shard state snapshots. Saves disk space but makes recovery after failures harder.

Type	Required	Default
bool	no	false

states_cache_mode

Shards state caching strategy.

Type	Required	Default
string (enum)	no	"Moderate"

Value	Description
"Off"	States are saved synchronously and not cached.
"Moderate"	States are saved asynchronously; recommended.

accelerated_consensus_disabled

If true, uses the standard consensus procedure instead of the accelerated one.

Type	Required	Default
bool	no	false

validation_countdown_mode

Controls the countdown behavior for block validation.

Type	Required	Default
string | null	no	null; equivalent to "always".

Value	Description
"always"	Countdown applies to all blocks.
"except-zerostate"	Countdown does not apply to the zero state.

default_rldp_roundtrip_ms

Initial round-trip time or RTT estimates for the Reliable Large Datagram Protocol (RLDP) in milliseconds. RLDP is a transport layer on top of ADNL that provides ordered, retransmitted delivery for large data transfers.

Type	Required	Default
u32 | null	no	null; uses the RLDP implementation default.

unsafe_catchain_patches_path

Path to a directory with catchain JSON patch files. Used for emergency intervention in the catchain protocol for resync and rotation. Only for emergency situations.

Type	Required	Default
string | null	no	null

adnl_node

ADNL (Abstract Datagram Network Layer) is the core networking protocol of TON. This section defines how the node participates in the ADNL network.

adnl_node.ip_address

The node’s external IP address and UDP port. Must be reachable from the internet. Other nodes connect to this address.

Type	Required	Format
string	yes	"IP:PORT"

adnl_node.keys

Cryptographic keys for different node functions. Each key has a tag that determines its purpose.

Field	Type	Description
tag	integer	Key purpose; defined in the “Key tags”.
data.type_id	integer	Key type. 1209251014 = Ed25519
data.pvt_key	string (base64)	256-bit Ed25519 private key

Key tags:

Tag	Purpose
1	DHT key – used for peer discovery.
2	Overlay key – used for block and data exchange.

Additional adnl_node fields

These optional fields are not commonly needed:

Field	Type	Default	Description
recv_pipeline_pool	u8 | null	null	Percentage of CPU cores for packet receive workers.
recv_priority_pool	u8 | null	null	Percentage of workers for priority receive.
throughput	u32 | null	null	Max send throughput in bytes/sec.
timeout_expire_queued_packet_sec	u32 | null	null	Timeout for queued packets in seconds.

gc

Garbage collector settings for cleaning up stale data.

gc.enable_for_archives

Enables automatic cleanup of old block archives. If false, archives accumulate indefinitely.

Type	Default
bool	false

gc.archives_life_time_hours

Archive retention period in hours. Archives older than the specified number of hours are pruned by gc.

Type	Default
u32 | null	null; delete as soon as possible.

Example: 48 keeps archives for the last 2 days.

gc.enable_for_shard_state_persistent

Enable cleanup of old persistent shard state snapshots.

Type	Default
bool	false

gc.cells_gc_config

gc settings for cells – the basic data storage units in TON.

Field	Type	Default	Description
gc_interval_sec	u32	900 (15 min)	Interval between cell gc runs.
cells_lifetime_sec	u64	86400 (24 hours)	Cells unused for longer than this duration become eligible for deletion.

This setting only affects cells required for serving external queries (e.g., account state requests from a lite-client). Cells required for the node’s own operation are retained regardless of this configuration.

For validators or nodes without a liteserver, a lower value, such as 1800 = 30 min, can be used to reduce disk usage and improve performance.

cells_db_config

Cell database tuning. If omitted entirely, the node uses built-in defaults for all fields. If the section is present, all fields must be specified — partial configs fail to deserialize.

cells_db_config.states_db_queue_len

Maximum queue length for state write operations. Controls backpressure during async saves.

Type	Default
u32	1000

cells_db_config.prefill_cells_counters

If true, pre-fills the cell counter cache during startup. Improves performance after start but increases startup time.

Type	Default
bool	false

cells_db_config.cells_cache_size_bytes

Size of the cell cache in bytes. Larger values reduce disk I/O at the cost of increased memory usage.

Type	Default
u64	4000000000 (~4 GB)

cells_db_config.counters_cache_size_bytes

Size of the cell reference counter cache in bytes. Used for reference counting during gc.

Type	Default
u64	4000000000 (~4 GB)

collator_config

Configuration of the collator component responsible for assembling new blocks. Only relevant for validators.

collator_config.cutoff_timeout_ms

Soft collation timeout in milliseconds. After this interval, the collator stops accepting new transactions and begins block finalization.

Type	Default
u32	1000 (1 second)

collator_config.stop_timeout_ms

Hard collation timeout in milliseconds. Collation is forcibly terminated after this interval. Must be greater than or equal to cutoff_timeout_ms.

Type	Default
u32	1500 (1.5 seconds)

collator_config.clean_timeout_percentage_points

Cleanup timeout as a fraction of cutoff_timeout. Measured in per-mille; out of 1000. For example, 150 corresponds to 15% of cutoff_timeout and defines the time allocated for removing processed messages during collation.

Type	Default
u32	150

collator_config.optimistic_clean_percentage_points

Fraction of clean_timeout used for the first cleanup attempt. 1000 corresponds to 100%.

Type	Default
u32	1000

collator_config.max_secondary_clean_timeout_percentage_points

Maximum secondary cleanup timeout as a fraction of cutoff_timeout. 350 corresponds to 35%.

Type	Default
u32	350

collator_config.max_collate_threads

Maximum number of parallel collation threads.

Type	Default
u32	10

collator_config.retry_if_empty

If true, retries collation when the resulting block contains no transactions. For TON consensus, false is recommended. Setting true may be useful in experimental networks to reduce block frequency during periods of low activity.

Type	Default
bool	false

collator_config.finalize_empty_after_ms

Time in milliseconds to wait for transactions before finalizing an empty block. If no transactions are received within this interval, the block is finalized as empty.

Type	Default
u32	800

collator_config.empty_collation_sleep_ms

Pause in milliseconds between collation attempts when there are no transactions. Reduces CPU usage during low activity.

Type	Default
u32	100

collator_config.external_messages_timeout_percentage_points

Fraction of cutoff_timeout allocated for processing external messages. 100 corresponds to 10%.

Type	Default
u32	100

collator_config.external_messages_maximum_queue_length

Maximum external message queue length. Limits memory usage during external message spam.

Type	Default
u32 | null	25600

collator_config_mc

Separate collator config for the masterchain. Same format as collator_config. If not set, collator_config is used for all chains.

Type	Default
object | null	null

control_server

Administrative interface for managing the node — validator key rotation, monitoring, etc. Required for validators; optional for full nodes.

control_server.address

Address and port to listen on.

Type	Format
string	"IP:PORT"

Use "0.0.0.0:<port>" to listen on all interfaces. For security, consider "127.0.0.1:<port>" if management is local only. The port must match ports.control in Helm values.

control_server.server_key

Server private key for ADNL encryption.

Field	Type	Description
type_id	integer	1209251014 = Ed25519
pvt_key	string (base64)	256-bit private key

control_server.clients

Authorized clients allowed to connect.

Field	Type	Description
list	array	Array of client public keys
list[].type_id	integer	1209251014 = Ed25519
list[].pub_key	string (base64)	Client public key

If clients is omitted or empty, any client can connect.

lite_server

Allows lite clients, such as tonlib, etc., to connect to the node for queries. The corresponding public key is published in the global config’s liteservers section for clients to discover it.

lite_server.address

Address and port for liteclient connections. The port must match ports.liteserver in Helm values.

Type	Format
string	"IP:PORT"

lite_server.server_key

Server private key. Same format as control_server.server_key.

lite_server.max_parallel_fast_queries

Maximum number of concurrent “fast” queries, which read from cache or perform simple lookups. Limits concurrency to prevent resource exhaustion under high load.

Type	Required	Default
u64 | null	no	256

lite_server.max_parallel_slow_queries

Maximum number of concurrent “slow” queries, which require disk reads, state traversal, or proof generation. These are more resource-intensive, so the default is lower.

Type	Required	Default
u64 | null	no	16

lite_server.account_state_cache_size_mb

Size of the in-memory cache for account states in megabytes. Caches recently queried account states to avoid repeated disk lookups.

Type	Required	Default
u64 | null	no	256 (MB)

json_rpc_server

HTTP JSON-RPC server for API requests.

json_rpc_server.address

Address and port for the HTTP API. The port must match ports.jsonRpc in Helm values.

Type	Format
string	"IP:PORT"

metrics

Prometheus metrics and Kubernetes health probe HTTP server. When present, the node starts an HTTP server with three endpoints:

Endpoint	Purpose
GET /metrics	Prometheus scrape endpoint
GET /healthz	Kubernetes liveness probe
GET /readyz	Kubernetes readiness probe

If the metrics section is absent from the config, the metrics server is not started, meaning no metrics and no probes.

metrics.address

Address and port for the metrics and probes HTTP server. The port must match ports.metrics in Helm values.

Type	Required	Format
string	yes	"IP:PORT"

Recommended: "0.0.0.0:9100".

metrics.histogram_buckets

Custom histogram bucket boundaries, keyed by metric name suffix. If a key matches the end of a histogram metric name, those buckets are used.

Type	Required	Default
map<string, float[]>	no	{}; default duration buckets applied to all *_seconds metrics.

When empty or absent, the following default buckets are applied to all histograms whose name ends with seconds:

[0.000001, 0.0001, 0.001, 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0, 60.0, 120.0, 300.0, 600.0, 3600.0]

Example of overriding buckets for all *_seconds histograms and adding custom ones for gas_used:

"histogram_buckets": {
  "seconds": [0.001, 0.01, 0.1, 0.5, 1.0, 5.0, 30.0, 60.0],
  "gas_used": [1000, 10000, 100000, 500000, 1000000]
}

metrics.global_labels

Key-value pairs added to every metric. Useful for distinguishing nodes when multiple instances report to the same Prometheus.

Type	Required	Default
map<string, string>	no	{}

Example:

"global_labels": {
  "network": "mainnet",
  "node_id": "validator-01"
}

Full example

"metrics": {
  "address": "0.0.0.0:9100",
  "histogram_buckets": {},
  "global_labels": {
    "network": "mainnet",
    "node_id": "validator-01"
  }
}

extensions

Optional network extensions.

Field	Type	Default	Description
disable_broadcast_retransmit	bool	false	Disable broadcast retransmission. Reduces traffic but hurts data propagation.
adnl_compression	bool	false	Enable ADNL packet compression. Not compatible with C++ TON nodes; only enable in networks where all peers run the Rust node.
broadcast_hops	u8 | null	null	Maximum number of broadcast hops.

secrets_vault_config

External secrets vault for storing private keys outside of config.json.

"secrets_vault_config": {
  "url": "file:///path/to/vault"
}

Type	Default
object | null	null

Auto-managed fields

The following fields are written by the node itself through the control server and must not be edited manually:

Field	Description
validator_keys	Validator key records with election IDs and expiration timestamps
validator_key_ring	Private key storage for validator keys

These fields are primarily relevant in testing environments. During validator elections, the node rotates keys and writes updated values to config.json. In a Kubernetes environment, this has no persistent effect because the configuration is stored in a Secret and is overwritten on pod restart or Helm upgrade.

These fields should be treated as initialization-only or system-managed. The node regenerates them as required through the control server.

Validator-specific sections

The collator_config section defines block collation parameters, including timeouts, threading, and message queue limits. Use the validator node config example for typical values.

Advanced fields

The following fields are present in the configuration but are not required for standard node operation. They should be left unchanged unless explicitly instructed otherwise.

Field	Type	Default	Description
accelerated_consensus_disabled	bool	false	Disables accelerated consensus, falling back to the standard procedure.
validation_countdown_mode	string | null	null ("always")	Defines when validation countdown is applied: "always" or "except-zerostate".
default_rldp_roundtrip_ms	u32 | null	null	Initial RTT estimate for the RLDP protocol, in milliseconds.
unsafe_catchain_patches_path	string | null	null	Path to catchain emergency patch files. Intended for emergency use only.