# Node configuration reference (https://docs-fpm2731fy-ton-core-docs.vercel.app/llms/ecosystem/nodes/rust/node-config-ref/content.md)



## Top-level fields [#top-level-fields]

### `log_config_name` [#log_config_name]

Path to the [loggers YAML configuration file](/llms/ecosystem/nodes/rust/logs-config/content.md). 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` [#ton_global_config_name]

Path to the [global network config](/llms/ecosystem/nodes/rust/global-config/content.md). 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` [#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` [#restore_db]

Enable database integrity check and repair on startup.

| Type | Required | Default |
| ---- | -------- | ------- |
| bool | no       | `false` |

### `boot_from_zerostate` [#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](/llms/ecosystem/nodes/rust/global-config/content.md). This increases sync time but verifies the entire blockchain history from genesis.

| Type         | Required | Default |
| ------------ | -------- | ------- |
| bool \| null | no       | `false` |

### `sync_by_archives` [#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` [#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` [#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` [#accelerated_consensus_disabled]

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

| Type | Required | Default |
| ---- | -------- | ------- |
| bool | no       | `false` |

### `validation_countdown_mode` [#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` [#default_rldp_roundtrip_ms]

Initial round-trip time or RTT estimates for the [Reliable Large Datagram Protocol (RLDP)](/llms/foundations/whitepapers/ton/content.md) 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` [#unsafe_catchain_patches_path]

Path to a directory with catchain JSON patch files. Used for emergency intervention in the [catchain protocol](/llms/foundations/whitepapers/catchain/content.md) for resync and rotation. Only for emergency situations.

| Type           | Required | Default |
| -------------- | -------- | ------- |
| string \| null | no       | `null`  |

## `adnl_node` [#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` [#adnl_nodeip_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"` |

<Callout type="note">
  The `adnl_node.ip_address` value must match the external IP assigned to this replica's `LoadBalancer` service. The port must match `ports.adnl` defined in Helm values.
</Callout>

### `adnl_node.keys` [#adnl_nodekeys]

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 [#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` [#gc]

Garbage collector settings for cleaning up stale data.

### `gc.enable_for_archives` [#gcenable_for_archives]

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

| Type | Default |
| ---- | ------- |
| bool | `false` |

### `gc.archives_life_time_hours` [#gcarchives_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` [#gcenable_for_shard_state_persistent]

Enable cleanup of old persistent shard state snapshots.

| Type | Default |
| ---- | ------- |
| bool | `false` |

### `gc.cells_gc_config` [#gccells_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` [#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` [#cells_db_configstates_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` [#cells_db_configprefill_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` [#cells_db_configcells_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` [#cells_db_configcounters_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` [#collator_config]

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

### `collator_config.cutoff_timeout_ms` [#collator_configcutoff_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` [#collator_configstop_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` [#collator_configclean_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` [#collator_configoptimistic_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` [#collator_configmax_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` [#collator_configmax_collate_threads]

Maximum number of parallel collation threads.

| Type | Default |
| ---- | ------- |
| u32  | `10`    |

### `collator_config.retry_if_empty` [#collator_configretry_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` [#collator_configfinalize_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` [#collator_configempty_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` [#collator_configexternal_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` [#collator_configexternal_messages_maximum_queue_length]

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

| Type        | Default |
| ----------- | ------- |
| u32 \| null | `25600` |

### `collator_config_mc` [#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` [#control_server]

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

### `control_server.address` [#control_serveraddress]

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` [#control_serverserver_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` [#control_serverclients]

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` [#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` [#lite_serveraddress]

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

| Type   | Format      |
| ------ | ----------- |
| string | `"IP:PORT"` |

### `lite_server.server_key` [#lite_serverserver_key]

Server private key. Same format as `control_server.server_key`.

### `lite_server.max_parallel_fast_queries` [#lite_servermax_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` [#lite_servermax_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` [#lite_serveraccount_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` [#json_rpc_server]

HTTP JSON-RPC server for API requests.

### `json_rpc_server.address` [#json_rpc_serveraddress]

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

| Type   | Format      |
| ------ | ----------- |
| string | `"IP:PORT"` |

## `metrics` [#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` [#metricsaddress]

Address and port for the [metrics](/llms/ecosystem/nodes/rust/metrics/content.md) and [probes](/llms/ecosystem/nodes/rust/probes/content.md) 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` [#metricshistogram_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`:

```json
"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` [#metricsglobal_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       | `{}`    |

<Callout type="note">
  The bundled [Grafana dashboard](https://github.com/RSquad/ton-rust-node/tree/master/grafana) relies on the `network` and `node_id` labels for filtering. If `global_labels` is not set or is empty, dashboard variables will be empty and panels will display no data.

  Both labels must be defined.
</Callout>

Example:

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

### Full example [#full-example]

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

## `extensions` [#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.                                                                                             |

<Callout type="danger" title="Mainnet compatibility">
  Do not enable `adnl_compression` on mainnet while any dependent peers run C++ TON nodes. This option is only safe when all interacting peers run the Rust node implementation.
</Callout>

## `secrets_vault_config` [#secrets_vault_config]

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

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

| Type           | Default |
| -------------- | ------- |
| object \| null | `null`  |

<Callout type="note" title="Helm integration">
  For Helm deployments, prefer chart-level `vault.url` or `vault.secretName` values. When `VAULT_URL` is set by Helm, do not also set `secrets_vault_config` in `config.json`.
</Callout>

## Auto-managed fields [#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 [#validator-specific-sections]

The [`collator_config` section](/llms/ecosystem/nodes/rust/node-config-ref/content.md) defines block collation parameters, including timeouts, threading, and message queue limits. Use the [validator node config example](/llms/ecosystem/nodes/rust/node-config/content.md) for typical values.

## Advanced fields [#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.          |