Configuration Parameters

• Root-Level
  • chain required
  • public_key required
  • private_key required
  • trusted_peers
  • trusted_peers_pop
• Genesis
  • genesis.file
  • genesis.public_key required
• Network
  • network.address required
  • network.public_address required
  • network.block_gossip_size
  • network.block_gossip_period_ms
  • network.transaction_gossip_size
  • network.transaction_gossip_period_ms
  • network.idle_timeout_ms
• Torii
  • torii.address required
  • torii.max_content_len
  • torii.query_idle_time_ms
  • torii.query_store_capacity
  • torii.query_store_capacity_per_user
• Logger
  • logger.level
  • logger.filter
  • logger.format
• Kura
  • kura.blocks_in_memory
  • kura.init_mode
  • kura.store_dir
  • kura.debug.output_new_blocks debug
• Queue
  • queue.capacity
  • queue.capacity_per_user
  • queue.transaction_time_to_live_ms
• Sumeragi
  • sumeragi.debug.force_soft_fork debug
• Snapshot
  • snapshot.mode
  • snapshot.create_every_ms
  • snapshot.store_dir
• Telemetry
  • telemetry.name
  • telemetry.url
  • telemetry.min_retry_period_ms
  • telemetry.max_retry_delay_exponent
  • dev_telemetry.out_file

Root-Level

chain required

Chain ID that must be included in each transaction. Used to prevent replay attacks.

A replay attack is an attempt to submit a valid transaction to a different network than the one it was intended for. Because the chain is part of the signed transaction payload, a transaction signed for one chain is rejected by peers that use another chain ID.

Type:	String
Env:	CHAIN

Config File

chain = "00000000-0000-0000-0000-000000000000"

Environment

CHAIN="00000000-0000-0000-0000-000000000000"

public_key required

Public key of the peer. Consensus validator peers must use BLS-Normal keys.

Type:	String, public key multihash
Env:	PUBLIC_KEY

Config File

public_key = "ea01309060D021340617E9554CCBC2CF3CC3DB922A9BA323ABDF7C271FCC6EF69BE7A8DEBCA7D9E96C0F0089ABA22CDAADE4A2"

Environment

PUBLIC_KEY="ea01309060D021340617E9554CCBC2CF3CC3DB922A9BA323ABDF7C271FCC6EF69BE7A8DEBCA7D9E96C0F0089ABA22CDAADE4A2"

private_key required

Private key of the peer. It must match public_key; consensus validator peers must use BLS-Normal keys.

Type:	todo private-key
Env:	PRIVATE_KEY

Config File

private_key = "8926201CA347641228C3B79AA43839DEDC85FA51C0E8B9B6A00F6B0D6B0423E902973F"

Environment

PRIVATE_KEY="8926201CA347641228C3B79AA43839DEDC85FA51C0E8B9B6A00F6B0D6B0423E902973F"

trusted_peers

List of predefined trusted peers.

Consensus validators must use BLS-Normal peer keys. For each validator, also provide a matching trusted_peers_pop entry.

Type:	Array of peer strings. Use PUBLIC_KEY@ADDRESS when the P2P address is known; bare PUBLIC_KEY is also accepted and lets the peer address be discovered from gossip.
Env:	TRUSTED_PEERS

Config File

trusted_peers = [
    "ea01309060D021340617E9554CCBC2CF3CC3DB922A9BA323ABDF7C271FCC6EF69BE7A8DEBCA7D9E96C0F0089ABA22CDAADE4A2@127.0.0.1:1337",
    "ea0130A7E9D016D723F72942FCF4B988FB599EA0E092F73C8B68E69F4E8B3FE542A3F7E48AD6CD15F3EB484E45F79399071F77@127.0.0.1:1338",
]

Environment

# as JSON
TRUSTED_PEERS='[
  "ea01309060D021340617E9554CCBC2CF3CC3DB922A9BA323ABDF7C271FCC6EF69BE7A8DEBCA7D9E96C0F0089ABA22CDAADE4A2@127.0.0.1:1337",
  "ea0130A7E9D016D723F72942FCF4B988FB599EA0E092F73C8B68E69F4E8B3FE542A3F7E48AD6CD15F3EB484E45F79399071F77@127.0.0.1:1338"
]'

trusted_peers_pop

BLS proof-of-possession entries for validator trusted peers.

Type:	Array of objects with public_key and pop_hex fields
Env:	TRUSTED_PEERS_POP

Config File

trusted_peers_pop = [
  { public_key = "ea01309060D021340617E9554CCBC2CF3CC3DB922A9BA323ABDF7C271FCC6EF69BE7A8DEBCA7D9E96C0F0089ABA22CDAADE4A2", pop_hex = "8515da750f81182aaba5c22fc9f03a01e81ed85e4495a2ca6b29a71c0c8549537e31e79cddf6ff285b9e22d0d9dc17ce0f46e7d0cf78b2ef9feab50c849a1ea8e1e4f07e966f6113faa8a999317545d9f111b8e08a7273913710b43a20b19c08" },
  { public_key = "ea0130A7E9D016D723F72942FCF4B988FB599EA0E092F73C8B68E69F4E8B3FE542A3F7E48AD6CD15F3EB484E45F79399071F77", pop_hex = "a14eb180f0d78c55d2c034e91ccf691378e9c3ceed8e0b81d3e4b7c215c0dbb633bb9f1c5063911c31af4610016c164015f0f93db3c7df6a2ad0c39338fe7695b976a59fd13797615f229fbd77276a8bb2842e4e44fadcafdb7b37f4a143b913" },
]

Environment

# as JSON
TRUSTED_PEERS_POP='[
  {"public_key":"ea01309060D021340617E9554CCBC2CF3CC3DB922A9BA323ABDF7C271FCC6EF69BE7A8DEBCA7D9E96C0F0089ABA22CDAADE4A2","pop_hex":"0x8515da750f81182aaba5c22fc9f03a01e81ed85e4495a2ca6b29a71c0c8549537e31e79cddf6ff285b9e22d0d9dc17ce0f46e7d0cf78b2ef9feab50c849a1ea8e1e4f07e966f6113faa8a999317545d9f111b8e08a7273913710b43a20b19c08"},
  {"public_key":"ea0130A7E9D016D723F72942FCF4B988FB599EA0E092F73C8B68E69F4E8B3FE542A3F7E48AD6CD15F3EB484E45F79399071F77","pop_hex":"0xa14eb180f0d78c55d2c034e91ccf691378e9c3ceed8e0b81d3e4b7c215c0dbb633bb9f1c5063911c31af4610016c164015f0f93db3c7df6a2ad0c39338fe7695b976a59fd13797615f229fbd77276a8bb2842e4e44fadcafdb7b37f4a143b913"}
]'

Genesis

genesis.file

File path to the signed genesis block payload generated by kagami genesis sign. Generated profiles commonly write this as a Norito .nrt file.

Type:	String, file path (relative to the config file or CWD)
Env:	GENESIS

Config File

[genesis]
file = "./genesis.signed.nrt"

Environment

GENESIS="./genesis.signed.nrt"

genesis.public_key required

Public key of the genesis key pair.

Type:	String, public key multihash
Env:	GENESIS_PUBLIC_KEY

Config File

[genesis]
public_key = "ed01208BA62848CF767D72E7F7F4B9D2D7BA07FEE33760F79ABE5597A51520E292A0CB"

Environment

GENESIS_PUBLIC_KEY="ed01208BA62848CF767D72E7F7F4B9D2D7BA07FEE33760F79ABE5597A51520E292A0CB"

Network

network.address required

Address for p2p communication for consensus (sumeragi) and block synchronization (block_sync) purposes.

Type:	String, socket address (host/IPv4/IPv6 + port)
Env:	P2P_ADDRESS

Config File

[network]
address = "0.0.0.0:1337"

Environment

P2P_ADDRESS=0.0.0.0:1337

network.public_address required

Peer-to-peer address (external, as seen by other peers).

Will be gossiped to connected peers so that they can gossip it to other peers.

Type:	String, socket address (host/IPv4/IPv6 + port)
Env:	P2P_PUBLIC_ADDRESS

Config File

[network]
public_address = "0.0.0.0:5000"

Environment

P2P_PUBLIC_ADDRESS=0.0.0.0:5000

network.block_gossip_size

The amount of blocks that can be sent in a single synchronization message.

Type:	Number
Default:	4

Config File

[network]
block_gossip_size = 256

network.block_gossip_period_ms

The time interval between requests to peers for the most recent block.

More frequent gossiping shortens the time to sync, but can overload the network.

Type:	Number, duration in milliseconds
Default:	10_000 (10 seconds)

Config File

[network]
block_gossip_period_ms = 1_000

network.transaction_gossip_size

Max number of transactions in a gossip batch message.

Smaller size leads to longer time to synchronise, but useful if you have high packet loss.

Type:	Number
Default:	500

Config File

[network]
transaction_gossip_size = 256

network.transaction_gossip_period_ms

Period of gossiping pending transaction between peers.

More frequent gossiping shortens the time to sync, but can overload the network.

Type:	Number, duration in milliseconds
Default:	1_000 (1 second)

Config File

[network]
transaction_gossip_period_ms = 5_000

network.idle_timeout_ms

Duration of time after which connection with peer is terminated if peer is idle.

Type:	Number, duration in milliseconds
Default:	300_000 (5 minutes)

Config File

[network]
idle_timeout_ms = 300_000

Torii

torii.address required

Address to which the Torii server must listen and to which the client(s) make their requests.

Type:	String, socket address (host/IPv4/IPv6 + port)
Env:	API_ADDRESS

Config File

[torii]
address = "0.0.0.0:8080"

Environment

API_ADDRESS=0.0.0.0:8080

torii.max_content_len

The maximum number of bytes in a raw request body accepted by the Torii endpoints.

This limit is used to prevent DOS attacks.

Type:	Number (of bytes)
Default:	64_000_000 (64 million bytes)

Config File

[torii]
max_content_len = 64_000_000

torii.query_idle_time_ms

The time a query can remain in the store if unaccessed.

Type:	Number, duration in milliseconds
Default:	10_000 (10 seconds)

Config File

[torii]
query_idle_time_ms = 10_000

torii.query_store_capacity

The upper limit of the number of live queries.

Type:	Number
Default:	128

Config File

[torii]
query_store_capacity = 128

torii.query_store_capacity_per_user

The upper limit of the number of live queries for a single user.

Type:	Number
Default:	128

Config File

[torii]
query_store_capacity_per_user = 128

Logger

logger.level

General logging verbosity (see logger.filter for refined configuration).

Type:	String, possible values: TRACE: All events, including low-level operations. DEBUG: Debug-level messages, useful for diagnostics. INFO: General informational messages. WARN: Warnings that indicate potential issues. ERROR: Errors that disrupt normal function but allow continued operation. Choose the level that best suits your use case. Refer to Stack Overflow for additional details on how to use different log levels.
Default:	INFO
Env:	LOG_LEVEL

Config File

[logger]
level = "INFO"

Environment

LOG_LEVEL=INFO

Runtime update

This parameter is subject to runtime configuration update through Torii operator endpoints.

logger.filter

Refined log filters in addition to logger.level. Allows to customize logging verbosity per-target.

Type:

String, consists of one or more comma-separated directives. Each directive may have a corresponding maximum verbosity level which enables (e.g., selects for) spans and events that match. Iroha considers less exclusive levels (like trace or info) to be more verbose than more exclusive levels (like error or warn). At a high level, the syntax for directives consists of several parts: target[span{field=value}]=level For more details, see tracing-subscriber documentation.

Env:

LOG_FILTER

Config File

[logger]
filter = "iroha_core=debug,iroha_p2p=debug"

Environment

LOG_FILTER=iroha_core=debug,iroha_p2p=debug

Compatibility with logger.level

logger.filter works together with logger.level and neither one overwrites another one.

For example, if logger.level is set to INFO and logger.filter is set to iroha_core=debug, the resulting filter set will be info,iroha_core=debug (i.e. info for all modules, debug for iroha_core).

Runtime update

This parameter is subject to runtime configuration update through Torii operator endpoints.

logger.format

Logs format.

Type:	String, possible values: full: The default formatter. This emits human-readable, single-line logs for each event that occurs, with the current span context displayed before the formatted representation of the event. compact: A variant of the default formatter, optimized for short line lengths. Fields from the current span context are appended to the fields of the formatted event, and span names are not shown; the verbosity level is abbreviated to a single character. pretty: Emits excessively pretty, multi-line logs, optimized for human readability. This is primarily intended to be used in local development and debugging, or for command-line applications, where automated analysis and compact storage of logs is less of a priority than readability and visual appeal. json: Outputs newline-delimited JSON logs. This is intended for production use with systems where structured logs are consumed as JSON by analysis and viewing tools. The JSON output is not optimized for human readability. For more details and sample outputs, see tracing-subscriber documentation.
Default:	full
Env:	LOG_FORMAT

Config File

[logger]
format = "json"

Environment

LOG_FORMAT=json

Kura

Kura is the persistent storage engine of Iroha (Japanese for warehouse).

kura.blocks_in_memory

At most N last blocks will be stored in memory.

Older blocks will be dropped from memory and loaded from the disk if they are needed.

Type:	Number
Default:	1024
Env:	KURA_BLOCKS_IN_MEMORY

Config File

[kura]
blocks_in_memory = 1024

Environment

KURA_BLOCKS_IN_MEMORY=1024

kura.init_mode

Kura initialisation mode

Type:	String, possible values: strict: strict validation of all blocks fast: Fast initialisation with only basic checks
Default:	strict
Env:	KURA_INIT_MODE

Config File

[kura]
init_mode = "fast"

Environment

KURA_INIT_MODE=fast

kura.store_dir

Specifies the directory[^paths] where the blocks are stored.

See also: snapshot.store_dir.

Type:	String, file path (relative to the config file or CWD)
Default:	./storage
Env:	KURA_STORE_DIR

Config File

[kura]
store_dir = "/path/to/storage"

Environment

KURA_STORE_DIR=/path/to/storage

kura.debug.output_new_blocks debug

Flag to enable printing new blocks to console.

Type:	todo bool
Default:	false
Env:	KURA_DEBUG_OUTPUT_NEW_BLOCKS

Config File

[kura.debug]
output_new_blocks = true

Environment

KURA_DEBUG_OUTPUT_NEW_BLOCKS=true

Queue

queue.capacity

The upper limit of the number of transactions waiting in the queue.

Type:	Number
Default:	65_536

Config File

[queue]
capacity = 1_048_576

queue.capacity_per_user

The upper limit of the number of transactions waiting in the queue for a single user.

Use this option to apply throttling.

Type:	Number
Default:	65_536

Config File

[queue]
capacity_per_user = 1_048_576

queue.transaction_time_to_live_ms

The transaction will be dropped after this time if it is still in the queue.

Type:	Number, duration in milliseconds
Default:	86_400_000 (24 hours)

Config File

[queue]
transaction_time_to_live_ms = 43_200_000

Sumeragi

sumeragi.debug.force_soft_fork debug

Debug-only switch for exercising Sumeragi soft-fork handling paths. Leave this disabled outside controlled tests; changing it on a running production network can make peers disagree about consensus behavior.

Type:	todo bool
Default:	false

Config File

[sumeragi.debug]
force_soft_fork = true

Snapshot

This module is responsible for reading and writing snapshots of the World State View.

Snapshots store a serialized checkpoint of the World State View so a peer can restart without replaying every block from Kura. Kura remains the durable block history and the source of truth for replay; snapshots are an acceleration path. On startup, Iroha checks snapshot metadata against the configured chain and the stored blocks before deciding whether to load a snapshot or fall back to replay.

Wipe Snapshots

In case if something is wrong with the snapshots system, and you want to start from a blank page (in terms of snapshots), you could remove the directory specified by snapshot.store_dir.

snapshot.mode

The mode the Snapshot system functions in.

Type:	String, possible values: read_write: Iroha creates snapshots with a period specified by snapshot.create_every_ms. On startup, Iroha reads an existing snapshot (if any) and verifies that it is up-to-date with the blocks storage. readonly: Similar to read_write but Iroha doesn't create any snapshots. disabled: Iroha neither creates new snapshots nor reads an existing one on startup.
Default:	read_write
Env:	SNAPSHOT_MODE

Config File

[snapshot]
mode = "readonly"

Environment

SNAPSHOT_MODE=readonly

snapshot.create_every_ms

Frequency of snapshots.

Type:	Number, duration in milliseconds
Default:	600_000 (10 minutes)

Config File

[snapshot]
create_every_ms = 60_000

snapshot.store_dir

Directory where to store snapshots.

See also: kura.store_dir

Type:	String, file path (relative to the config file or CWD)
Default:	./storage/snapshot
Env:	SNAPSHOT_STORE_DIR

Config File

[snapshot]
store_dir = "/path/to/storage"

Environment

SNAPSHOT_STORE_DIR="/path/to/storage"

Telemetry

Telemetry exports peer diagnostics to an external telemetry collector. Configure both telemetry.name and telemetry.url when a peer should report to a collector; omit the section when telemetry is not used.

name and url must be paired.

All telemetry section is optional.

telemetry.name

The node's name to be displayed on the telemetry.

Type:	String

Config File

[telemetry]
name = "iroha"

telemetry.url

The WebSocket URL of the telemetry collector.

Type:	String

Config File

[telemetry]
url = "ws://telemetry.example.com/submit"

telemetry.min_retry_period_ms

The minimum period of time to wait before reconnecting.

Type:	Number, duration in milliseconds
Default:	1_000 (1 second)

Config File

[telemetry]
min_retry_period_ms = 5_000

telemetry.max_retry_delay_exponent

The maximum exponent of 2 that is used for increasing delay between reconnections.

Type:	Number
Default:	4

Config File

[telemetry]
max_retry_delay_exponent = 4

dev_telemetry.out_file

The filepath to write dev-telemetry to

Type:	String, file path (relative to the config file or CWD)

Config File

[dev_telemetry]
out_file = "/path/to/file.json"