Iroha 3

Appearance

Configuration Parameters ​

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
toml
chain = "00000000-0000-0000-0000-000000000000"
shell
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
toml
public_key = "ea01309060D021340617E9554CCBC2CF3CC3DB922A9BA323ABDF7C271FCC6EF69BE7A8DEBCA7D9E96C0F0089ABA22CDAADE4A2"
shell
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
toml
private_key = "8926201CA347641228C3B79AA43839DEDC85FA51C0E8B9B6A00F6B0D6B0423E902973F"
shell
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
toml
trusted_peers = [
    "ea01309060D021340617E9554CCBC2CF3CC3DB922A9BA323ABDF7C271FCC6EF69BE7A8DEBCA7D9E96C0F0089ABA22CDAADE4A2@127.0.0.1:1337",
    "ea0130A7E9D016D723F72942FCF4B988FB599EA0E092F73C8B68E69F4E8B3FE542A3F7E48AD6CD15F3EB484E45F79399071F77@127.0.0.1:1338",
]
shell
# 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
toml
trusted_peers_pop = [
  { public_key = "ea01309060D021340617E9554CCBC2CF3CC3DB922A9BA323ABDF7C271FCC6EF69BE7A8DEBCA7D9E96C0F0089ABA22CDAADE4A2", pop_hex = "8515da750f81182aaba5c22fc9f03a01e81ed85e4495a2ca6b29a71c0c8549537e31e79cddf6ff285b9e22d0d9dc17ce0f46e7d0cf78b2ef9feab50c849a1ea8e1e4f07e966f6113faa8a999317545d9f111b8e08a7273913710b43a20b19c08" },
  { public_key = "ea0130A7E9D016D723F72942FCF4B988FB599EA0E092F73C8B68E69F4E8B3FE542A3F7E48AD6CD15F3EB484E45F79399071F77", pop_hex = "a14eb180f0d78c55d2c034e91ccf691378e9c3ceed8e0b81d3e4b7c215c0dbb633bb9f1c5063911c31af4610016c164015f0f93db3c7df6a2ad0c39338fe7695b976a59fd13797615f229fbd77276a8bb2842e4e44fadcafdb7b37f4a143b913" },
]
shell
# 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
toml
[genesis]
file = "./genesis.signed.nrt"
shell
GENESIS="./genesis.signed.nrt"

genesis.public_key required ​

Public key of the genesis key pair.

Type: String, public key multihash
Env:GENESIS_PUBLIC_KEY
toml
[genesis]
public_key = "ed01208BA62848CF767D72E7F7F4B9D2D7BA07FEE33760F79ABE5597A51520E292A0CB"
shell
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
toml
[network]
address = "0.0.0.0:1337"
shell
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
toml
[network]
public_address = "0.0.0.0:5000"
shell
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
toml
[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)
toml
[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
toml
[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)
toml
[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)
toml
[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
toml
[torii]
address = "0.0.0.0:8080"
shell
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)

toml
[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)
toml
[torii]
query_idle_time_ms = 10_000

torii.query_store_capacity ​

The upper limit of the number of live queries.

Type: Number
Default:128
toml
[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
toml
[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
toml
[logger]
level = "INFO"
shell
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
toml
[logger]
filter = "iroha_core=debug,iroha_p2p=debug"
shell
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
toml
[logger]
format = "json"
shell
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
toml
[kura]
blocks_in_memory = 1024
shell
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
toml
[kura]
init_mode = "fast"
shell
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
toml
[kura]
store_dir = "/path/to/storage"
shell
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
toml
[kura.debug]
output_new_blocks = true
shell
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
toml
[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
toml
[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)
toml
[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
toml
[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
toml
[snapshot]
mode = "readonly"
shell
SNAPSHOT_MODE=readonly

snapshot.create_every_ms ​

Frequency of snapshots.

Type: Number, duration in milliseconds
Default:600_000 (10 minutes)
toml
[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
toml
[snapshot]
store_dir = "/path/to/storage"
shell
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
toml
[telemetry]
name = "iroha"

telemetry.url ​

The WebSocket URL of the telemetry collector.

Type: String
toml
[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)
toml
[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
toml
[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)
toml
[dev_telemetry]
out_file = "/path/to/file.json"