diff --git a/.vitepress/config.mts b/.vitepress/config.mts index 0c0aa5842..bf3df96df 100644 --- a/.vitepress/config.mts +++ b/.vitepress/config.mts @@ -89,6 +89,10 @@ function sidebarGuide(): DefaultTheme.SidebarItem[] { text: 'JavaScript', link: '/guide/tutorials/javascript', }, + { + text: 'Compatibility Matrix', + link: '/reference/compatibility-matrix', + }, ], }, { @@ -303,10 +307,10 @@ function sidebarChain(): DefaultTheme.SidebarItem[] { ] } -function sidebarAPI(): DefaultTheme.SidebarItem[] { +function sidebarReference(): DefaultTheme.SidebarItem[] { return [ { - text: 'About', + text: 'Reference', items: [ { text: 'Glossary', @@ -316,23 +320,6 @@ function sidebarAPI(): DefaultTheme.SidebarItem[] { text: 'Naming Conventions', link: '/reference/naming.md', }, - { - text: 'Compatibility Matrix', - link: '/reference/compatibility-matrix', - }, - { - text: 'Foreign Function Interfaces', - link: '/reference/ffi', - }, - ], - }, - { - text: 'Reference', - items: [ - { - text: 'Torii Endpoints', - link: '/reference/torii-endpoints.md', - }, { text: 'Data Model Schema', link: '/reference/data-model-schema', @@ -349,6 +336,34 @@ function sidebarAPI(): DefaultTheme.SidebarItem[] { text: 'Permissions', link: '/reference/permissions.md', }, + { + text: 'CLI', + }, + { + text: 'Torii HTTP API', + link: '/reference/torii-endpoints.md', + }, + { + text: 'Foreign Function Interfaces', + link: '/reference/ffi', + }, + ], + }, + { + text: 'Configuration', + items: [ + { text: 'Overview' }, + { + text: 'Peer Configuration', + link: '/reference/config/index.md', + items: [ + { text: 'Parameters', link: '/reference/config/params.md' }, + // Consider removal + { text: 'Migration from pre-rc.20', link: '/reference/config/migration.md' }, + ], + }, + { text: 'Genesis Block' }, + { text: 'On-Chain Configuration' }, ], }, ] diff --git a/.vitepress/theme/index.ts b/.vitepress/theme/index.ts index e923fafdb..0cea5ed4f 100644 --- a/.vitepress/theme/index.ts +++ b/.vitepress/theme/index.ts @@ -10,7 +10,7 @@ import './style/index.scss' import { defineAsyncComponent } from 'vue' export default { - ...ThemeDefault, + extends: ThemeDefault, Layout: LayoutCustom, enhanceApp({ app }: EnhanceAppContext) { app.component('MermaidRenderWrap', MermaidRenderWrap) diff --git a/src/reference/config/base-params.md b/src/reference/config/base-params.md deleted file mode 100644 index e3a633d54..000000000 --- a/src/reference/config/base-params.md +++ /dev/null @@ -1,52 +0,0 @@ -# Base Parameters - -## `chain_id` {#param-chain-id} - -::: code-group - -```toml [Config File] -chain_id = "00000000-0000-0000-0000-000000000000" -``` - -```shell [ENV] -CHAIN_ID=00000000-0000-0000-0000-000000000000 -``` - -::: - -## `private_key` {#param-private-key} - -- **Type:** Private Key -- **ENV:** `PRIVATE_KEY_ALGORITHM` + `PRIVATE_KEY_PAYLOAD` -- **Required** - -Private key of the peer - -::: code-group - -```toml [Config File] -private_key = { algorithm = "ed25519", payload = "8f4c15e5d664da3f13778801d23d4e89b76e94c1b94b389544168b6cb894f84f8ba62848cf767d72e7f7f4b9d2d7ba07fee33760f79abe5597a51520e292a0cb" } -``` - -```shell [ENV] -PRIVATE_KEY_ALGORITHM=ed25519 -PRIVATE_KEY_PAYLOAD=8f4c15e5d664da3f13778801d23d4e89b76e94c1b94b389544168b6cb894f84f8ba62848cf767d72e7f7f4b9d2d7ba07fee33760f79abe5597a51520e292a0cb -``` - -::: - -## `public_key` {#param-public-key} - -Public key of the peer - -::: code-group - -```toml [Config File] -public_key = "ed0120FAFCB2B27444221717F6FCBF900D5BE95273B1B0904B08C736B32A19F16AC1F9" -``` - -```shell [ENV] -PUBLIC_KEY=ed0120FAFCB2B27444221717F6FCBF900D5BE95273B1B0904B08C736B32A19F16AC1F9 -``` - -::: diff --git a/src/reference/config/chain-wide-params.md b/src/reference/config/chain-wide-params.md deleted file mode 100644 index 8f60f8fba..000000000 --- a/src/reference/config/chain-wide-params.md +++ /dev/null @@ -1,5 +0,0 @@ -# On-Chain Parameters - -- These parameters are chain-wide, and each peer should have the same -- It should not be specified in the config file: https://github.com/hyperledger/iroha/issues/4028 -- We don't document it for now diff --git a/src/reference/config/genesis-params.md b/src/reference/config/genesis-params.md deleted file mode 100644 index 5566bf2c6..000000000 --- a/src/reference/config/genesis-params.md +++ /dev/null @@ -1,48 +0,0 @@ -# Genesis Parameters - -This module configures the [genesis](/reference/genesis) block. - -## `genesis.file` {#param-file} - - - -The file path to the [Genesis JSON](/reference/genesis). - -::: code-group - -```toml [Config File] -[genesis] -file = "genesis.json" -``` - -```sh [Environment] -GENESIS_FILE="genesis.json" -``` - -::: - -::: tip Path Resolution - -[Paths resolution rules](glossary#paths-resolution) apply to this -parameter. - -::: - -## `genesis.private_key` {#param-private-key} - -## `genesis.public_key` {#param-public-key} - -The public key of the genesis account. - -::: code-group - -```toml [Config File] -[genesis] -public_key = "ed0120FAFCB2B27444221717F6FCBF900D5BE95273B1B0904B08C736B32A19F16AC1F9" -``` - -```shell [Environment] -GENESIS_PUBLIC_KEY=ed0120FAFCB2B27444221717F6FCBF900D5BE95273B1B0904B08C736B32A19F16AC1F9 -``` - -::: diff --git a/src/reference/config/index.md b/src/reference/config/index.md index 3844cf0e9..e38405166 100644 --- a/src/reference/config/index.md +++ b/src/reference/config/index.md @@ -1,80 +1,8 @@ # Configuring Iroha -Iroha is configured via a [TOML](https://toml.io/) file and/or Environment -Variables. - -The path to the configuration file should be passed through the -[`--config` CLI argument](/reference/cli#arg-config): - -```shell -iroha --config iroha_config.toml -``` - -If the peer submits the genesis: - -```shell -# `iroha_config.toml` should contain `genesis.file` and `genesis.private_key` -iroha --config iroha_config.toml --submit-genesis -``` - -## Structure - -- List links to all modules, giving high-level overview of them -- List required parameters - -| Module Name | Description | Required fields | -| ------------------------------- | ---------------------------- | ------------------------------------------------------------------------- | -| [Base](base-params) | Basic, root-level parameters | `chain_id`, `public_key`, `private_key` | -| [Genesis](genesis-params) | Genesis block configuration | `genesis.public_key`, and possibly `genesis.file` & `genesis.private_key` | -| [Network](network-params) | ? | `network.address` | -| [Torii](torii-params) | ? | `torii.address` | -| [Sumeragi](sumeragi-params) | ? | `sumeragi.trusted_peers` if doesn't submit the genesis | -| [Kura](kura-params) | ? | | -| [Queue](queue-params) | ? | | -| [Snapshot](snapshot-params) | ? | | -| [Logger](logger-params) | ? | | -| [Telemetry](telemetry-params) | ? | | -| [Chain Wide](chain-wide-params) | ? | | - -## Example Configuration - -- Show minimal TOML -- Show same minimal ENVs -- Refer to `peer.template.toml` in the repo, or show it here under the - spoiler. - -## Extends feature - -- You can compose configuration files together using the `extends` - root-level field - ---- - -## Required Parameters - -- [`public_key`](base-params#param-public-key): _explain the option_ -- [`private_key`](base-params#param-private-key): _explain the option_ -- [`network.address`](network-params#param-address): _explain the option_ -- [`genesis.public_key`](genesis-params#param-public-key): _explain the - option_ -- [`genesis.private_key`](genesis-params#param-private-key) if the peer - is the one who submits the genesis. _explain the option_ -- [`sumeragi.trusted_peers`](sumeragi-params#param-trusted-peers): - _explain the option_. It is not _strictly_ required, but you might need - to set it in most cases. -- [`torii.address`](torii-params#param-address): _explain the option_ - -## Modules Overview - -TODO: list each section (sumeragi, torii, kura etc) with links and short -explanations of their responsibility. - -- **[Base Options](base-params):** _explain_ -- **[Genesis](genesis-params):** _explain_ -- **[Sumeragi](sumeragi-params):** _explain_ -- **[Torii](torii-params):** _explain_ -- **[Queue](queue-params):** _explain_ -- **[Kura](kura-params):** _explain_ -- **[Logger](logger-params):** _explain_ -- **[Telemetry](telemetry-params):** _explain_ -- **[Snapshot](./snapshot-params)** +- Use `--config` CLI or relevant ENV parameter (?) +- Use `--trace-config` to debug +- Config consists of parameters set via TOML file (some via ENV too) +- There is also chain-wide config, which is different +- Here is the template file +- Here is how to use `extends` diff --git a/src/reference/config/kura-params.md b/src/reference/config/kura-params.md deleted file mode 100644 index 0d6399086..000000000 --- a/src/reference/config/kura-params.md +++ /dev/null @@ -1,40 +0,0 @@ -# Kura Parameters - -TODO: Explain Kura module - -## `kura.store_dir` {#param-store-dir} - -- **Type:** String -- **Default:** `./storage` -- **ENV:** `KURA_STORE_DIR` - -Path to the existing block store folder or path to create new folder. - -**Example:** - -```toml -[kura] -store_dir = "./storage" -``` - -TODO: will the path be resolved relative to the config file location, or to -CWD? the former is more intuitive - -## `kura.debug.output_new_blocks` {#param-debug-output-new-blocks} - -## `kura.init_mode` {#param-init-mode} - -- **Type:** String -- **Possible Values:** - - **`strict`:** strict validation of all blocks - - **`fast`:** fast initialization with basic checks -- **Default:** `strict` - -**Example:** - -```toml -[kura] -init_mode = "strict" -``` - -TODO: can we change this parameter and restart peer? diff --git a/src/reference/config/logger-params.md b/src/reference/config/logger-params.md deleted file mode 100644 index 917c537d6..000000000 --- a/src/reference/config/logger-params.md +++ /dev/null @@ -1,39 +0,0 @@ -# Logger Parameters - -This page explains the parameters related to logging operations of Iroha 2, as managed by the Logger module. - -## `logger.format` {#param-format} - -## `logger.level` {#param-level} - -Sets the logging sensitivity. - -- **ENV:** `LOG`, `LOG_LEVEL`, `IROHA_LOG_LEVEL` -- **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. - - **`FATAL`:** Critical errors that lead to immediate termination. (todo: maybe unsupported) -- **Default:** `INFO` - -Choose the level that best suits your use case. Refer to -[Stack Overflow](https://stackoverflow.com/questions/2031163/when-to-use-the-different-log-levels) for additional -details on how to use different log levels. - -**Example:** - -::: code-group - -```toml [Configuration file] -[logger] -level = "INFO" -``` - -```shell [ENV] -LOG_LEVEL=INFO -``` - -::: diff --git a/src/reference/config/migration.md b/src/reference/config/migration.md index fbc5570d7..ebe7c72ad 100644 --- a/src/reference/config/migration.md +++ b/src/reference/config/migration.md @@ -28,7 +28,6 @@ were removed. | ----------------------------------: | ---------------------------------------------------------------------------------------------------------------- | | `IROHA2_CONFIG_PATH` | removed, use [`--config`](../cli#arg-config) instead | | `IROHA2_GENESIS_PATH` | [`GENESIS_FILE`](genesis-params#param-file) | -| `IROHA2_GENESIS_PATH` | [`GENESIS_FILE`](genesis-params#param-file) | | `IROHA_PUBLIC_KEY` | [`PUBLIC_KEY`](base-params#param-public-key) | | `IROHA_PRIVATE_KEY` | split into [`PRIVATE_KEY_ALGORITHM` and `PRIVATE_KEY_PAYLOAD`](base-params#param-private-key) | | `TORII_P2P_ADDR` | [`P2P_ADDRESS`](network-params#param-address) | diff --git a/src/reference/config/network-params.md b/src/reference/config/network-params.md deleted file mode 100644 index e200d666b..000000000 --- a/src/reference/config/network-params.md +++ /dev/null @@ -1,86 +0,0 @@ -# Network Parameters - -## `network.address` {#param-address} - -- **Type:** String, [Socket-Address](glossary#type-socket-address) -- **Required** - -Address for p2p communication for consensus (sumeragi) and block synchronization (block_sync) purposes. - -```toml -[network] -address = "localhost:1337" -``` - -TODO: wait for renamings - -## `network.block_gossip_period` {#param-block-gossip-period} - -- **Type:** String or Number, [Duration](glossary#type-duration) -- **Default:** 10 seconds - -The time interval between requests to peers for the most recent block. - -**Example:** - -```toml -[sumeragi] -block_gossip_period = "5s" -``` - -::: warning - -More frequent gossiping shortens the time to sync, but can overload the -network. - -::: - -## `network.max_blocks_per_gossip` {#param-max-blocks-per-gossip} - -- **Type:** Number -- **Default:** $4$ - -The amount of blocks that can be sent in a single synchronization message. - -**Example:** - -```toml -[sumeragi] -max_blocks_per_gossip = 4 -``` - -## `network.max_transactions_per_gossip` {#param-max-transactions-per-gossip} - -- **Type:** Number -- **Default:** $500$ - -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. - -**Example:** - -```toml -[sumeragi] -max_transactions_per_gossip = 500 -``` - -## `network.transaction_gossip_period` {#param-transaction-gossip-period} - -- **Type:** String or Number, [Duration](glossary#type-duration) -- **Default:** 1 second - -Period for pending transaction gossiping between peers. - -**Example:** - -```toml -[sumeragi] -transaction_gossip_period = "1s" -``` - -::: warning - -More frequent gossiping shortens the time to sync, but can overload the -network. - -::: \ No newline at end of file diff --git a/src/reference/config/params.md b/src/reference/config/params.md new file mode 100644 index 000000000..58ef0a036 --- /dev/null +++ b/src/reference/config/params.md @@ -0,0 +1,727 @@ +--- +outline: [ 2, 3 ] +--- + +# Configuration Parameters + +This page describes available configuration parameters. + +[[toc]] + +## Root-Level + +### `chain_id` {#param-chain-id} + +Chain ID that must be included in each transaction. Used to prevent replay attacks. + +[//]: # (TODO: explain what replay attacks are) + +- **ENV:** `CHAIN_ID` +- **Type:** String +- **Required** + +::: code-group + +```toml [Config File] +chain_id = "00000000-0000-0000-0000-000000000000" +``` + +```shell [ENV] +CHAIN_ID=00000000-0000-0000-0000-000000000000 +``` + +::: + +### `private_key` {#param-private-key} + +Private key of the peer. + +- **ENV:** `PRIVATE_KEY` +- **Type:** String, private key multihash + +::: code-group + +```toml [Config File] +private_key = "8026208F4C15E5D664DA3F13778801D23D4E89B76E94C1B94B389544168B6CB894F84F" +``` + +```shell [ENV] +PRIVATE_KEY=8026208F4C15E5D664DA3F13778801D23D4E89B76E94C1B94B389544168B6CB894F84F +``` + +::: + +### `public_key` {#param-public-key} + +Public key of the peer. + +- **ENV:** `PRIVATE_KEY` +- **Type:** String, private key multihash + +::: code-group + +```toml [Config File] +public_key = "ed0120FAFCB2B27444221717F6FCBF900D5BE95273B1B0904B08C736B32A19F16AC1F9" +``` + +```shell [ENV] +PUBLIC_KEY=ed0120FAFCB2B27444221717F6FCBF900D5BE95273B1B0904B08C736B32A19F16AC1F9 +``` + +::: + +## Genesis + +### `genesis.file` {#param-genesis-file} + +File path[^paths] to the SCALE-encoded genesis block. + +Must be paired with `--submit-genesis` CLI parameter. + +- **ENV:** `GENESIS` +- **Type:** String, file path[^paths] + +::: code-group + +```toml [Config File] +[genesis] +file = "./genesis.scale" +``` + +```shell [ENV] +GENESIS="./genesis.scale" +``` + +::: + +### `genesis.public_key` {#param-genesis-public-key} + +Public key of the genesis key pair. + +- **ENV:** `GENESIS_PUBLIC_KEY` +- **Type:** String, public key multihash + +::: code-group + +```toml [Config File] +[genesis] +public_key = "ed01208BA62848CF767D72E7F7F4B9D2D7BA07FEE33760F79ABE5597A51520E292A0CB" +``` + +```shell [ENV] +GENESIS_PUBLIC_KEY="ed01208BA62848CF767D72E7F7F4B9D2D7BA07FEE33760F79ABE5597A51520E292A0CB" +``` + +::: + +## Network + +### `network.address` {#param-network-address} + +Address for p2p communication for consensus (sumeragi) and block synchronization (block_sync) purposes + +- **ENV:** `P2P_ADDRESS` +- **Type:** String, socket address (host/IPv4/IPv6 + port) + +::: code-group + +```toml [Config File] +[network] +address = "0.0.0.0:1337" +``` + +```shell [ENV] +P2P_ADDRESS="0.0.0.0:1337" +``` + +::: + +### `network.public_address` {#param-network-public-address} + +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. + +- **ENV:** `P2P_PUBLIC_ADDRESS` +- **Type:** String, socket address (host/IPv4/IPv6 + port) + +::: code-group + +```toml [Config File] +[network] +public_address = "0.0.0.0:5000" +``` + +```shell [ENV] +P2P_PUBLIC_ADDRESS="0.0.0.0:5000" +``` + +::: + +### `network.block_gossip_size` {#param-network-block-gossip-size} + +The amount of blocks that can be sent in a single synchronization message. + +- **Type:** Number +- **Default:** `500` + +::: code-group + +```toml [Config File] +[network] +block_gossip_size = 256 +``` + +::: + +### `network.block_gossip_period_ms` {#param-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 (of milliseconds) +- **Default:** `10_000` (10 seconds) + +::: code-group + +```toml [Config File] +[network] +block_gossip_period_ms = 1_000 +``` + +::: + +### `network.transaction_gossip_size` {#param-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` + +::: code-group + +```toml [Config File] +[network] +transaction_gossip_size = 256 +``` + +::: + +### `network.transaction_gossip_period_ms` {#param-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 (of milliseconds) +- **Default:** `1_000` (1 second) + +::: code-group + +```toml [Config File] +[network] +transaction_gossip_period_ms = 5_000 +``` + +::: + +### `network.idle_timeout_ms` {#param-network-idle-timeout-ms} + +Duration of time after which connection with peer is terminated if peer is idle. + +- **Type:** Number (of milliseconds) +- **Default:** `60_000` (60 seconds) + +::: code-group + +```toml [Config File] +[network] +idle_timeout_ms = 60_000 +``` + +::: + +## Torii + +This module contains configuration of [Torii](/reference/glossary#torii-gate) - the API gateway of Iroha. Refer to the +[Torii Endpoints reference](/reference/torii-endpoints) for information about exact endpoints. + +### `torii.address` {#param-torii-address} + +Address on which Torii Endpoints will be accessible. + +- **ENV:** `API_ADDRESS` +- **Type:** String, socket address (host/IPv4/IPv6 + port) + +::: code-group + +```toml [Config File] +[torii] +address = "0.0.0.0:8080" +``` + +```shell [ENV] +API_ADDRESS=0.0.0.0:8080 +``` + +::: + +### `torii.max_content_len` {#param-torii-max-content-len} + +The maximum number of bytes in a raw request body accepted by the +[Transaction Endpoint](/reference/torii-endpoints#transaction). This limit is used to prevent DOS attacks. + +- **Type:** Number (of bytes) +- **Default:** `16_777_216` (16 MiB, $2^{20} \cdot 16$) + +```toml +[torii] +max_content_len = 16_777_216 +``` + +### `torii.query_idle_time_ms` {#param-torii-query-idle-time} + +- **Type:** Number +- **Default:** `10_000` (10 seconds) + +The time a query can remain in the store if unaccessed. + +TODO: Configures behaviour of lazily-evaluated pagination of the [Query Endpoint](/reference/torii-endpoints#query). + +```toml +[torii] +query_idle_time = 10_000 +``` + +### `torii.query_store_capacity` {#param-torii-query-store-capacity} + +The upper limit of the number of live queries. + +- **Type:** Number +- **Default:** `128` + +### `torii.query_store_capacity_per_user` {#param-torii-query-store-capacity-per-user} + +The upper limit of the number of live queries for a single user. + +- **Type:** Number +- **Default:** `128` + +## Sumeragi + +### `sumeragi.trusted_peers` {#param-sumeragi-trusted-peers} + +List of predefined trusted peers. + +- **ENV:** `TRUSTED_PEERS` +- **Type:** Array of records with `address` and `public_key` fields. + +::: code-group + +```toml [Config File] +[[sumeragi.trusted_peers]] +address = "localhost:1338" +public_key = "ed012067C02E340AADD553BCF7DB28DD1F3BE8BE3D7581A2BAD81580AEE5CC75FEBD45" + +[[sumeragi.trusted_peers]] +address = "localhost:1339" +public_key = "ed0120236808A6D4C12C91CA19E54686C2B8F5F3A786278E3824B4571EF234DEC8683B" + +[[sumeragi.trusted_peers]] +address = "localhost:1340" +public_key = "ed0120FAFCB2B27444221717F6FCBF900D5BE95273B1B0904B08C736B32A19F16AC1F9" + +# Alternative syntax + +[sumeragi] +trusted_peers = [ + { address = "localhost:1338", public_key = "ed012067C02E340AADD553BCF7DB28DD1F3BE8BE3D7581A2BAD81580AEE5CC75FEBD45" }, + { address = "localhost:1339", public_key = "ed0120236808A6D4C12C91CA19E54686C2B8F5F3A786278E3824B4571EF234DEC8683B" }, + { address = "localhost:1340", public_key = "ed0120FAFCB2B27444221717F6FCBF900D5BE95273B1B0904B08C736B32A19F16AC1F9" }, +] +``` + +```shell [ENV] +# as JSON +TRUSTED_PEERS='[{"address":"irohad2:1339","public_key":"ed01204EE2FCD53E1730AF142D1E23951198678295047F9314B4006B0CB61850B1DB10"},{"address":"irohad1:1338","public_key":"ed01209897952D14BDFAEA780087C38FF3EB800CB20B882748FC95A575ADB9CD2CB21D"},{"address":"irohad3:1340","public_key":"ed0120CACF3A84B8DC8710CE9D6B968EE95EC7EE4C93C85858F026F3B4417F569592CE"}]' +``` + +::: + + + +### `sumeragi.debug.force_soft_fork` {#param-sumeragi-debug-force-soft-fork} + +TODO + +- **Type:** Boolean +- **Default:** `false` + +::: code-group + +```toml [Config File] +[sumeragi.debug] +force_soft_fork = true +``` + +::: + + + + +## Logger + +### `logger.format` {#param-logger-format} + +Logging format. + +- **ENV:** `LOG_FORMAT` +- **Type:** String, possible values: + - `full`: + - `compact`: + - `pretty`: + - `json`: +- **Default:** `full` + +::: code-group + +```toml [Config File] +[logger] +format = "full" +``` + +```shell [ENV] +LOG_FORMAT=full +``` + +::: + +### `logger.level` {#param-level} + +Logging verbosity. + +Choose the level that best suits your use case. Refer to +[Stack Overflow](https://stackoverflow.com/questions/2031163/when-to-use-the-different-log-levels) for additional +details on how to use different log levels. + +- **ENV:** `LOG_LEVEL` +- **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. +- **Default:** `INFO` + +::: code-group + +```toml [Config File] +[logger] +level = "INFO" +``` + +```shell [ENV] +LOG_LEVEL=INFO +``` + +::: + +## Kura + +### `kura.blocks_in_memory` {#param-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. + +- **ENV:** `KURA_BLOCKS_IN_MEMORY` +- **Type:** Number +- **Default:** `128` + +::: code-group + +```toml [Config File] +[kura] +blocks_in_memory = 256 +``` + +```shell [ENV] +KURA_BLOCKS_IN_MEMORY=256 +``` + +::: + +### `kura.init_mode` {#param-kura-init-mode} + +Kura initialisation mode + +- **ENV:** `KURA_INIT_MODE` +- **Type:** String, possible values: + - `strict`: strict validation of all blocks + - `fast`: Fast initialisation with only basic checks + +- **Default:** `strict` + +::: code-group + +```toml [Config File] +[kura] +init_mode = "fast" +``` + +```shell [ENV] +KURA_INIT_MODE="fast" +``` + +::: + +### `kura.store_dir` {#param-kura-store-dir} + +Path[^paths] to the existing block store folder or path to create new folder. + +- **ENV:** `KURA_STORE_DIR` +- **Type:** String, file path[^paths] +- **Default:** `./storage` + +::: code-group + +```toml [Config File] +[kura] +store_dir = "/path/to/storage" +``` + +```shell [ENV] +KURA_STORE_DIR="/path/to/storage" +``` + +::: + +### `kura.debug.output_new_blocks` {#param-kura-debug-output-new-blocks} + +Flag to enable printing new blocks to console. + +- **ENV:** `KURA_DEBUG_OUTPUT_NEW_BLOCKS` +- **Type:** Boolean +- **Default:** `false` + +::: code-group + +```toml [Config File] +[kura.debug] +output_new_blocks = true +``` + +```shell [ENV] +KURA_DEBUG_OUTPUT_NEW_BLOCKS=true +``` + +::: + +## Queue + +### `queue.capacity` {#param-queue-capacity} + +The upper limit of the number of transactions waiting in the queue. + +- **Type:** Number +- **Default:** `65_536` + +::: code-group + +```toml [Config File] +[queue] +capacity = 1_048_576 +``` + +::: + +### `queue.capacity_per_user` {#param-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 + +::: code-group + +```toml [Config File] +[queue] +capacity_per_user = 1_048_576 +``` + +::: + +### `queue.transaction_time_to_live_ms` {#param-queue-transaction-time-to-live-ms} + +The transaction will be dropped after this time if it is still in the queue. + +- **Type:** Number (of milliseconds) +- **Default:** `86_400_000` (24 hours) + +::: code-group + +```toml [Config File] +[queue] +transaction_time_to_live_ms = 43_200_000 +``` + +::: + +## Snapshot + +### `snapshot.mode` {#param-snapshot-mode} + +The mode the Snapshot system functions in. + +- **ENV:** `SNAPSHOT_MODE` +- **Type:** String, possible values: + +- `read_write`: Iroha creates snapshots with a period specified by [`snapshot.create_every_ms`](#param-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` + +::: code-group + +```toml [Config File] +[snapshot] +mode = "readonly" +``` +```shell [ENV] +SNAPSHOT_MODE=readonly +``` +::: + +### `snapshot.create_every_ms` {#param-snapshot-create-every-ms} + +Frequency of snapshots. + +- **Type:** Number (of milliseconds) +- **Default:** `600_000` (10 minutes) + +::: code-group + +```toml [Config File] +[snapshot] +create_every_ms = 60_000 +``` + +::: + +### `snapshot.store_dir` {#param-snapshot-store-dir} + +Directory where to store snapshots. + +- **ENV:** `SNAPSHOT_STORE_DIR` +- **Type:** String, file path[^paths] +- **Default:** `./storage/snapshot` (see also: [`kura.store_dir`](#param-kura-store-dir)) + +::: code-group + +```toml [Config File] +[snapshot] +store_dir = "/path/to/storage" +``` +```shell [ENV] +SNAPSHOT_STORE_DIR="/path/to/storage" +``` +::: + +## Telemetry + +TODO + +`name` and `url` must be paired. + +All `telemetry` section is optional. + + +### `telemetry.name` {#param-telemetry-name} + +The node's name to be displayed on the telemetry. + +- **Type:** String + +::: code-group + +```toml [Config File] +[telemetry] +name = "iroha" +``` + +::: + +### `telemetry.url` {#param-telemetry-url} + +The url of the telemetry. TODO update example value + +- **Type:** String + +::: code-group + +```toml [Config File] +[telemetry] +url = "ws://substrate.telemetry.iroha" +``` + +::: + +### `telemetry.min_retry_period_ms` {#param-telemetry-min-retry-period-ms} + +The minimum period of time to wait before reconnecting. + +- **Type:** Number (of milliseconds) +- **Default:** `1_000` (1 second) + +::: code-group + +```toml [Config File] +[telemetry] +min_retry_period_ms = 5_000 +``` + +::: + +### `telemetry.max_retry_delay_exponent` {#param-telemetry-max-retry-delay-exponent} + +The maximum exponent of 2 that is used for increasing delay between reconnections. + +- **Type:** Number +- **Default:** `4` + +::: code-group + +```toml [Config File] +[telemetry] +max_retry_delay_exponent = 4 +``` + +::: + +### `dev_telemetry.out_file` {#param-dev-telemetry-out-file} + +The filepath to write dev-telemetry to + +- **Type:** String, file path[^paths] + +::: code-group + +```toml [Config File] +[dev_telemetry] +out_file = "/path/to/file.json" +``` + +::: + + + + +[^paths]: Relative file paths in the configuration file are resolved relative to the configuration file location. If +provided via Environment Variables, they are resolved relative to the Current Working Directory. \ No newline at end of file diff --git a/src/reference/config/queue-params.md b/src/reference/config/queue-params.md deleted file mode 100644 index 2747a3323..000000000 --- a/src/reference/config/queue-params.md +++ /dev/null @@ -1,70 +0,0 @@ -# Queue Parameters - -TODO Explain Queue module. The queue holds incoming transactions. From time -to time, Sumeragi fetches them in order to create a block. - -## `queue.capacity` {#param-capacity} - -- **Type:** u32 -- **Default:** $2^{16} = 65\ 536$ - -The upper limit of the number of transactions waiting in the queue. - -**Example:** - -```toml -[queue] -max_transactions_in_queue = 65_536 -``` - -## `queue.capacity_per_user` {#param-capacity-per-user} - -- **Type:** u32 -- **Default:** $2^{16} = 65\ 536$ - -The upper limit of the number of transactions waiting in the queue for a -single user. Use this option to apply throttling. - -**Example:** - -```toml -[queue] -max_transactions_in_queue_per_user = 65_536 -``` - -## `queue.future_threshold` {#param-future-threshold} - -- **Type:** String or Number, [Duration](glossary#type-duration) -- **Default:** 1 second - -The threshold to determine if a transaction has been tampered with to have -a future timestamp. - -TODO: explain that _timestamp_ is the value specified in -[`TransactionPayload`'s `creation_time_ms` field](/reference/data-model-schema#transactionpayload). - -**Example:** - -```toml -[queue] -future_threshold = "1s" -``` - -## `queue.transaction_time_to_live` {#param-transaction-time-to-live} - -- **Type:** String or Number, [Duration](glossary#type-duration) -- **Default:** 24 hours - -The transaction will be dropped after this time if it is still in the -queue. - -TODO: there is also `TransactionPayload`'s `time_to_live` parameter. We -should probably say here that configuration parameter has higher priority. -Name it `queue.max_transaction_time_to_live`? - -**Example:** - -```toml -[queue] -transaction_time_to_live = "24h" -``` diff --git a/src/reference/config/snapshot-params.md b/src/reference/config/snapshot-params.md deleted file mode 100644 index edfe4a99b..000000000 --- a/src/reference/config/snapshot-params.md +++ /dev/null @@ -1,60 +0,0 @@ -# Snapshot Parameters - -This module is responsible for reading and writing snapshots of the -[World State View](/guide/blockchain/world#world-state-view-wsv). - -TODO: explain the purpose of snapshots, file formats, etc - -::: tip 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`](#param-store-dir). - -::: - -## `snapshot.create_every` {#param-create-every} - -- **Type:** String or Number, [Duration](glossary#type-duration) -- **Default:** 1 minute - -Frequency of making snapshots - -**Example:** - -```toml -[snapshot] -create_every = "1 minute" -``` - -## `snapshot.mode` {#param-mode} - -Specifies the mode the Snapshot system functions in. - -- **Type:** String -- **Possible Values:** - - **`read_write`:** Iroha creates snapshots with a period specified by `snapshot.create_every`. On startup, Iroha reads an - existing snapshot (if any) and verifies that it is up-to-date with the blocks storage. - - **`readonly`:** Similar to `normal` but Iroha doesn't create any snapshots. - - **`disabled`:** Iroha neither creates new snapshots nor reads an existing one on startup. -- **Default:** `normal` - -**Example:** - -```toml -[snapshot] -mode = "read_write" -``` - -## `snapshot.store_dir` {#param-store-dir} - -- **Type:** String -- **Default:** `./storage/snapshot` - -Directory where to store snapshots - -**Example:** - -```toml -[snapshot] -store_dir = "./storage/snapshot" -``` diff --git a/src/reference/config/sumeragi-params.md b/src/reference/config/sumeragi-params.md deleted file mode 100644 index 8baebb1eb..000000000 --- a/src/reference/config/sumeragi-params.md +++ /dev/null @@ -1,74 +0,0 @@ -# Sumeragi Parameters - -TODO Explain sumeragi module. Clarify that it consists of transactions and -blocks gossiping, which are two separate processes. Explain how periods & -gossip sizes might affect network load & speed of sync. Explain the -pipeline of transactions and blocks, refer to consensus section and maybe -some others. - -## `sumeragi.trusted_peers` {#param-trusted-peers} - - - -- **Type:** Array of Peer Ids -- **Optional** - -Optional list of predefined trusted peers. - -Each Peer Id consists of: - -- **`address`:** Address of the peer. - - **Type:** String, [Socket-Address](glossary#type-socket-address) - - **Required** -- **`public_key`:** Public key of the peer. - - **Type:** String, [Multi-hash](glossary#type-multi-hash) - - **Required** - -```toml -peer_id = { address = "localhost:1338", public_key = "ed0120FAFCB2B27444221717F6FCBF900D5BE95273B1B0904B08C736B32A19F16AC1F9" } -``` - -An array can be defined in two ways. Like this: - -```toml -[[sumeragi.trusted_peers]] -address = "localhost:1338" -public_key = "ed012067C02E340AADD553BCF7DB28DD1F3BE8BE3D7581A2BAD81580AEE5CC75FEBD45" - -[[sumeragi.trusted_peers]] -address = "localhost:1339" -public_key = "ed0120236808A6D4C12C91CA19E54686C2B8F5F3A786278E3824B4571EF234DEC8683B" - -[[sumeragi.trusted_peers]] -address = "localhost:1340" -public_key = "ed0120FAFCB2B27444221717F6FCBF900D5BE95273B1B0904B08C736B32A19F16AC1F9" -``` - -Or like this: - -```toml -[sumeragi] -trusted_peers = [ - { address = "localhost:1338", public_key = "ed012067C02E340AADD553BCF7DB28DD1F3BE8BE3D7581A2BAD81580AEE5CC75FEBD45" }, - { address = "localhost:1339", public_key = "ed0120236808A6D4C12C91CA19E54686C2B8F5F3A786278E3824B4571EF234DEC8683B" }, - { address = "localhost:1340", public_key = "ed0120FAFCB2B27444221717F6FCBF900D5BE95273B1B0904B08C736B32A19F16AC1F9" }, -] -``` - -## `sumeragi.debug.force_soft_fork` {#param-debug-force-soft-fork} diff --git a/src/reference/config/telemetry-params.md b/src/reference/config/telemetry-params.md deleted file mode 100644 index 7dae80b94..000000000 --- a/src/reference/config/telemetry-params.md +++ /dev/null @@ -1,57 +0,0 @@ -# Telemetry Parameters - -Two Telemetries are supported: Substrate-based and File-based. - -**Example:** - -```toml -[telemetry.substrate] -name = "iroha" -url = "ws://127.0.0.1:8001/submit" -``` - - -## `telemetry.name` {#param-name} - -- **Type:** String -- Must be paired with `telemetry.url` - -The node's name to be displayed on the telemetry - -## `telemetry.min_retry_period` {#param-min-retry-period} - -- **Type:** String or Number, [Duration](glossary#type-duration) -- **Default:** 1 second - - -The minimum period of time in seconds to wait before reconnecting - -## `telemetry.max_retry_delay_exponent` {#param-max-retry-delay-exponent} - -- **Type:** Number, u8 -- **Default:** 4 - - -The maximum exponent of 2 that is used for increasing delay between reconnections - -## `telemetry.dev.out_file` {#param-dev-out-file} - -Enables file-based active outbound telemetry. - -**Fields:** - -- **`file`:** The filepath to write dev-telemetry to - - **Type:** String, file path - - **Required** - -```toml -[telemetry.file_output] -file = "/path/to/file" -``` - -## `telemetry.url` {#param-url} - -- **Type:** String, URL -- Must be paired with `telemetry.name` - -The url of the telemetry diff --git a/src/reference/config/torii-params.md b/src/reference/config/torii-params.md deleted file mode 100644 index 25e57a9c8..000000000 --- a/src/reference/config/torii-params.md +++ /dev/null @@ -1,52 +0,0 @@ -# Torii Parameters - -TODO: Explain Torii module - -This module contains configuration of [Torii](/reference/glossary#torii-gate) - the API gateway of Iroha. Refer to the -[Torii Endpoints reference](/reference/torii-endpoints) for information about exact endpoints. - -## `torii.address` {#param-address} - -- **ENV:** `API_ENDPOINT` -- **Type:** String, [Socket-Address](glossary#type-socket-address) -- **Required** - -Address on which Torii Endpoints will be accessible. - -```toml -[torii] -api_address = "localhost:8080" -``` - -## `torii.max_content_length` {#param-max-content-length} - -- **Type:** String or Number, [Byte Size](glossary#type-bytes-amount) -- **Default:** $16\ 000\text{ KiB}$ ($2^{10} \cdot 16\ 000 = 16\ 384\ 000\text{ bytes}$) - -TODO: consider changing the default value to 16 MiB precisely (which is $2^{20} * 16 = 16\ 777\ 216$) - -The maximum number of bytes in a raw request body accepted by the -[Transaction Endpoint](/reference/torii-endpoints#transaction). This limit is used to prevent DOS attacks. - -**Example:** - -```toml -[torii] -max_content_length = "16MiB" -``` - -## `torii.query_idle_time` {#param-query-idle-time} - -- **Type:** String or Number, [Duration](glossary#type-duration) -- **Default:** 30 seconds - -The time a query can remain in the store if unaccessed. - -TODO: Configures behaviour of lazily-evaluated pagination of the [Query Endpoint](/reference/torii-endpoints#query). - -**Example:** - -```toml -[torii] -query_idle_time = "30s" -```