diff --git a/.vitepress/config.mts b/.vitepress/config.mts index 5938447eb..d6bd7146a 100644 --- a/.vitepress/config.mts +++ b/.vitepress/config.mts @@ -1,6 +1,6 @@ /// -import { defineConfig, DefaultTheme } from 'vitepress' +import { DefaultTheme, defineConfig } from 'vitepress' import footnote from 'markdown-it-footnote' import { resolve } from 'path' import ViteSvgLoader from 'vite-svg-loader' @@ -28,7 +28,7 @@ function nav(): DefaultTheme.NavItem[] { { text: 'Reference', link: '/reference/torii-endpoints', - activeMatch: '/reference/', + activeMatch: '^/reference/', }, { text: 'Help', @@ -93,6 +93,10 @@ function sidebarGuide(): DefaultTheme.SidebarItem[] { text: 'JavaScript', link: '/guide/tutorials/javascript', }, + { + text: 'Compatibility Matrix', + link: '/reference/compatibility-matrix', + }, ], }, { @@ -103,18 +107,6 @@ function sidebarGuide(): DefaultTheme.SidebarItem[] { text: 'Configure Iroha', collapsed: true, items: [ - { - text: 'Configuration Types', - link: '/guide/configure/configuration-types', - }, - { - text: 'Samples', - link: '/guide/configure/sample-configuration', - }, - { - text: 'Peer Configuration', - link: '/guide/configure/peer-configuration', - }, { text: 'Client Configuration', link: '/guide/configure/client-configuration', @@ -307,10 +299,10 @@ function sidebarChain(): DefaultTheme.SidebarItem[] { ] } -function sidebarAPI(): DefaultTheme.SidebarItem[] { +function sidebarReference(): DefaultTheme.SidebarItem[] { return [ { - text: 'About', + text: 'Reference', items: [ { text: 'Glossary', @@ -320,23 +312,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', @@ -357,6 +332,30 @@ function sidebarAPI(): DefaultTheme.SidebarItem[] { text: 'Binaries', link: '/reference/binaries.md', }, + { + text: 'irohad CLI', + link: '/reference/irohad-cli.md', + }, + { + text: 'Torii HTTP API', + link: '/reference/torii-endpoints.md', + }, + { + text: 'Foreign Function Interfaces', + link: '/reference/ffi', + }, + { + text: 'Peer Configuration', + link: '/reference/peer-config/index.md', + items: [ + { text: 'Parameters', link: '/reference/peer-config/params.md' }, + { text: 'Migration from pre-rc.20', link: '/reference/peer-config/migration.md' }, + ], + }, + { + text: 'Genesis Block', + link: '/reference/genesis.md', + }, ], }, ] @@ -473,13 +472,12 @@ export default defineConfig({ }, nav: nav(), - outline: [2, 3], sidebar: { '/get-started/': sidebarStart(), '/guide/': sidebarGuide(), '/blockchain/': sidebarChain(), - '/reference/': sidebarAPI(), + '/reference/': sidebarReference(), '/help/': sidebarHelp(), }, diff --git a/.vitepress/theme/style/index.scss b/.vitepress/theme/style/index.scss index 1d9c95fee..dc2b76060 100644 --- a/.vitepress/theme/style/index.scss +++ b/.vitepress/theme/style/index.scss @@ -1,9 +1,13 @@ -@import url('https://fonts.googleapis.com/css2?family=Sora:wght@100..800&display=swap'); +@import url("https://fonts.googleapis.com/css2?family=Sora:wght@100..800&display=swap"); :root { - --vp-font-family-mono: 'JetBrains Mono', 'Fira Code', Menlo, Monaco, Consolas, 'Courier New', monospace; - --vp-font-family-base: 'Sora', 'Inter', ui-sans-serif, system-ui, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol', 'Noto Color Emoji'; - + --vp-font-family-mono: + "JetBrains Mono", "Fira Code", Menlo, Monaco, Consolas, "Courier New", + monospace; + --vp-font-family-base: + "Sora", "Inter", ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", + "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; + --vp-c-brand-1: var(--vp-c-red-1); --vp-c-brand-2: var(--vp-c-red-2); --vp-c-brand-3: var(--vp-c-red-3); @@ -15,7 +19,11 @@ color: var(--vp-c-text-1); } -.VPSidebarItem.level-1 .text, .VPSidebarItem.level-2 .text, .VPSidebarItem.level-3 .text, .VPSidebarItem.level-4 .text, .VPSidebarItem.level-5 .text { +.VPSidebarItem.level-1 .text, +.VPSidebarItem.level-2 .text, +.VPSidebarItem.level-3 .text, +.VPSidebarItem.level-4 .text, +.VPSidebarItem.level-5 .text { font-weight: 400 !important; color: var(--vp-c-text-2); } @@ -25,7 +33,7 @@ } .vp-doc { - div[class*='language-'] { + div[class*="language-"] { pre { font-size: 14px; font-variant-ligatures: none; @@ -44,4 +52,21 @@ line-height: 1.75; font-weight: 300; } + + tr.transposed-table:nth-child(2n+1) { + background: var(--vp-c-bg-soft); + + pre { + border: 1px solid var(--vp-c-divider); + border-radius: 8px; + } + } + + tr.transposed-table:nth-child(2n) { + background: transparent; + } + + section.footnotes { + font-size: 0.8rem; + } } diff --git a/etc/snippet-sources.ts b/etc/snippet-sources.ts index b0573ce7f..fc2f615e2 100644 --- a/etc/snippet-sources.ts +++ b/etc/snippet-sources.ts @@ -117,11 +117,9 @@ export default [ }, { src: `https://raw.githubusercontent.com/hyperledger-iroha/iroha/${IROHA_RC_1}/docs/source/references/client.template.toml`, - filename: 'client-cli-config-template.toml', }, { src: `https://raw.githubusercontent.com/hyperledger-iroha/iroha/${IROHA_RC_1}/docs/source/references/peer.template.toml`, - filename: 'peer-config-template.toml', }, { src: `https://raw.githubusercontent.com/hyperledger-iroha/iroha/${IROHA_RC_1}/defaults/genesis.json`, diff --git a/src/blockchain/wasm.md b/src/blockchain/wasm.md index 2ba41ec1e..8686ad573 100644 --- a/src/blockchain/wasm.md +++ b/src/blockchain/wasm.md @@ -78,9 +78,9 @@ non-portable architecture and OS-specific static manner, but WASM is a portable format. Since C ABI is the _lingua franca_ of the programming world and there is no other stable Rust ABI (yet), Iroha relies on the C-linkage to generate WASM bindings. Thankfully, `iroha_wasm` takes care of -everything related to [foreign function interfaces](/reference/ffi.md) (FFI), so -you don't have to worry about things like `unsafe`, `repr(C)`, padding, -alignment, and others. +everything related to [foreign function interfaces](/reference/ffi.md) +(FFI), so you don't have to worry about things like `unsafe`, `repr(C)`, +padding, alignment, and others. The `iroha_wasm` crate contains all of the bindings, macros, and trait implementations that you'd need to write the program, most notably the diff --git a/src/blockchain/world.md b/src/blockchain/world.md index d7d3395c0..4c6ea713c 100644 --- a/src/blockchain/world.md +++ b/src/blockchain/world.md @@ -4,8 +4,7 @@ consists of: - Iroha [configuration parameters](/guide/configure/client-configuration.md) -- the list of - [trusted peers](/guide/configure/peer-configuration#trusted-peers) +- TODO: peers - registered domains - registered [triggers](/blockchain/triggers.md) - registered diff --git a/src/guide/advanced/metrics.md b/src/guide/advanced/metrics.md index e8f29cbf8..5a6469620 100644 --- a/src/guide/advanced/metrics.md +++ b/src/guide/advanced/metrics.md @@ -19,12 +19,6 @@ This topic will be updated as part of the new configuration reference. The progress on the configuration reference can be tracked in the following GitHub issue:\ [iroha-2-docs > Issue #392: Tracking issue for Configuration Reference as per RFC](https://github.com/hyperledger-iroha/iroha-2-docs/issues/392). -::: note - -For examples, see [Sample Configuration Files](../configure/sample-configuration.md). - -::: - After the above is configured, you can use the IP address set in the `"TORII_TELEMETRY_URL"` variable to access the metrics data from within a running Iroha instance. **Example**: diff --git a/src/guide/advanced/running-iroha-on-bare-metal.md b/src/guide/advanced/running-iroha-on-bare-metal.md index c4f4e5d58..63d9c5449 100644 --- a/src/guide/advanced/running-iroha-on-bare-metal.md +++ b/src/guide/advanced/running-iroha-on-bare-metal.md @@ -12,19 +12,12 @@ error-prone, particularly for exotic systems (Windows). ::: info For this chapter, we assume you have learned about -[configuration](/guide/configure/sample-configuration.md) and [management](/guide/configure/peer-management.md) in Iroha 2. Here we offer you instructions to run Iroha on bare metal without going into details about various configuration options available. -You can always check -[sample configuration files](/guide/configure/sample-configuration.md) for -`configs/peer/genesis.json` and `configs/peer/config.json`, or refer to -[peer configuration options](/guide/configure/peer-configuration.md) for -more details. +TODO extend with a relevant config guide - ::: @@ -448,13 +441,11 @@ Iroha in the real world. ``` 3. Register your peer to a network, and make sure to add at least four of - the peers on that network to the - [`TRUSTED_PEERS`](/guide/configure/peer-configuration.md#trusted-peers) + the peers on that network to the trusted peers array in your configuration file. -4. Determine the web socket that the other peers will use to connect to - you. Make sure that the port is open and use that address - ([`P2P_ADDR`](/guide/configure/peer-configuration.md#p2p-addr)) in your +4. Determine the socket address that the other peers will use to connect to + you. Make sure that the port is open and use that address in your `configs/peer/config.json` file. 5. After you have finished editing the configuration file, deploy Iroha by diff --git a/src/guide/configure/client-configuration.md b/src/guide/configure/client-configuration.md index 2d6df8638..8fdf0d22a 100644 --- a/src/guide/configure/client-configuration.md +++ b/src/guide/configure/client-configuration.md @@ -4,7 +4,7 @@ Let's look at the client configuration options. ::: details Client configuration template -<<< @/snippets/client-cli-config-template.toml +<<< @/snippets/client.template.toml ::: @@ -24,26 +24,26 @@ For details on cryptographic keys, see [Public Key Cryptography](../security/pub ## User account -The `ACCOUNT_ID` should be self-explanatory. The only thing you need to -worry about is that the account must already exist in the blockchain. In -other words, the account you provide here should already be +The `ACCOUNT_ID` should be self-explanatory. The only thing you need to worry about is that the account must already +exist in the blockchain. In other words, the account you provide here should already be [registered](/blockchain/instructions.md#un-register). ::: info Note -Iroha is **case-sensitive**, meaning that _Alice_@wonderland is different -from _alice_@wonderland. It should go without saying that -_alice@wonderland_ is not the same as _alice@looking_glass_ either, since -these accounts belong to different domains, `wonderland` and -`looking_glass`. +Iroha is **case-sensitive**, meaning that _Alice_@wonderland is different from _alice_@wonderland. It should go without +saying that _alice@wonderland_ is not the same as _alice@looking_glass_ either, since these accounts belong to different +domains, `wonderland` and `looking_glass`. ::: ## Basic Authentication Credentials -The idea of basic authentication credentials is to provide the access control using a web server with a reverse proxy like [Nginx](https://www.nginx.com/) while these credentials are ignored by the Iroha peers. +The idea of basic authentication credentials is to provide the access control using a web server with a reverse proxy +like [Nginx](https://www.nginx.com/) while these credentials are ignored by the Iroha peers. -The login and password will be filled by the client and used for the [`Authorization`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization) HTTP [header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers). +The login and password will be filled by the client and used for the +[`Authorization`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization) HTTP +[header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers). Use this style of configuration to provide the basic authentication credentials (login and password): @@ -56,49 +56,26 @@ Use this style of configuration to provide the basic authentication credentials ## Iroha Public Addresses -`TORII` is the module in charge of handling incoming and outgoing -connections. For client configuration, you can set up two addresses: -`TORII_API_URL` and `TORII_TELEMETRY_URL`. +`TORII` is the module in charge of handling incoming and outgoing connections. For client configuration, you can set up +two addresses: `TORII_API_URL` and `TORII_TELEMETRY_URL`. ### `TORII_API_URL` -First, the `TORII_API_URL` is the same as `TORII` `API_URL` in the -[peer configuration](peer-configuration.md#api-url). This is the module -responsible for handling incoming and outgoing connections. You should also -add the prefix `http://` or (_preferably_) `https://` to the address. For -example: +First, the `TORII_API_URL` is the same as +[`torii.address` in the peer configuration](/reference/peer-config/params#param-torii-address). This is the module +responsible for handling incoming and outgoing connections. You should also add the prefix `http://` or (_preferably_) +`https://` to the address. For example: ```json -"TORII_API_URL": "http://127.0.0.1:8080" -``` - -### `TORII_TELEMETRY_URL` - -The `TORII_TELEMETRY_URL` is used to specify the prometheus endpoint -address. You can set `TORII_TELEMETRY_URL` like this: - -```json -"TORII_TELEMETRY_URL": "http://127.0.0.1:8180" +{ + "TORII_API_URL": "http://127.0.0.1:8080" +} ``` -A `GET` request to the `127.0.0.1:8180/status` will give you a JSON-encoded -representation of the top-level metrics, while a `GET` request to -`127.0.0.1:8180/metrics` will give you a (somewhat verbose) list of all -available metrics gathered in Iroha. You might want to change this if -you're having trouble gathering metrics using `prometheus`. - -::: info - -Learn how to [monitor Iroha performance](/guide/advanced/metrics.md) using -prometheus. - -::: - ## Transaction Limits -You can specify the transaction limits that each transaction must adhere -to: the maximum number of instructions and the maximum size of a WASM blob -(in bytes). For example: +You can specify the transaction limits that each transaction must adhere to: the maximum number of instructions and the +maximum size of a WASM blob (in bytes). For example: ```json { @@ -109,9 +86,8 @@ to: the maximum number of instructions and the maximum size of a WASM blob ## Transaction TTL and Timeout -Configure the time-to-live (TTL) for transactions and the timeout to wait -for the status. Both values have to be provided in milliseconds. For -example: +Configure the time-to-live (TTL) for transactions and the timeout to wait for the status. Both values have to be +provided in milliseconds. For example: ```json "TRANSACTION_TIME_TO_LIVE_MS": 100000, @@ -120,5 +96,5 @@ example: ## Transaction Nonce -If you set `ADD_TRANSACTION_NONCE` to `true`, Iroha will create different -hashes for transactions that occur repeatedly and simultaneously. +If you set `ADD_TRANSACTION_NONCE` to `true`, Iroha will create different hashes for transactions that occur repeatedly +and simultaneously. diff --git a/src/guide/configure/configuration-types.md b/src/guide/configure/configuration-types.md deleted file mode 100644 index e8cfc49d7..000000000 --- a/src/guide/configure/configuration-types.md +++ /dev/null @@ -1,74 +0,0 @@ -# Configuration Types - -Configuration options have different underlying types and default values, -which are denoted in code as types wrapped in a single `Option<..>` or in a -double `Option>`. - -In this section we explain the difference between `Option<..>` and -`Option>` used for configuration types. You can find more about -available configuration options in the [Peer Configuration](peer-configuration.md) topic. - - - -## `Option<..>` - -A type wrapped in a single `Option<..>` signifies that in the corresponding -`json` block there is a fallback value for this type, and that it only -serves as a reference. - -::: warning If a default for such a type has a `null` value, it means that -there is no meaningful fallback available for this particular value. It -doesn't mean that you can omit the value. Quite the opposite, it **must** -be set manually, either in the configuration file, or via the environment -variables. - -::: - -All the default values can be freely obtained from a provided -[sample configuration file](./sample-configuration), -but it is only a starting point. \*\*If left unchanged, the sample -configuration file will not work. All `null` values in place of public and -private keys as well as -[endpoint URLs](./peer-configuration.md#iroha-public-addresses) should be -provided either by modifying the sample config file or as environment -variables. No other overloading of configuration values happens besides -reading them from a file and capturing the environment variables, and -environment variables take precedence. - -For both types of configuration options wrapped in a single `Option<..>` -(i.e. both those that have meaningful defaults and those that have `null`), -failure to provide them in any of the above two ways results in an error. - -## `Option>` - -`Option>` types should be distinguished from types wrapped in a -single `Option<..>`. Only the double option ones are allowed to stay -`null`, meaning that **not** providing them in an environment variable or a -file will **not** cause an error. - -Thus, only these types are truly optional in the common sense of the word. -An example of this distinction is genesis -[public and private keys](./peer-configuration.md#genesis). While the first -one is a single `Option<..>` wrapped type, the latter is wrapped in -`Option>`. This means that the genesis _public_ key should -always be provided by the user, be it via a file config or an environment -variable, whereas the _private_ key is only needed for the peer that -submits the genesis block, and can be omitted for all others. The same -logic goes for other double option fields such as logger file path. - -## Sumeragi: default `null` values - -A special note about Sumeragi fields with `null` as default: only the -[`trusted_peers`](./peer-configuration.md#trusted-peers) field out of the -three can be initialized via a provided file or an environment variable. - -The other two fields, namely `key_pair` and `peer_id`, go through a process -of finalization where their values are derived from the corresponding ones -in the uppermost Iroha config (using its `public_key` and `private_key` -fields) or the Torii config (via its `p2p_addr`). This ensures that these -linked fields stay in sync, and prevents the programmer error when -different values are provided to these field pairs. Providing either -`sumeragi.key_pair` or `sumeragi.peer_id` by hand will result in an error, -as it should never be done directly. In later versions these configuration -options shall be hidden completely. diff --git a/src/guide/configure/genesis.md b/src/guide/configure/genesis.md index ffa2e902e..04031c677 100644 --- a/src/guide/configure/genesis.md +++ b/src/guide/configure/genesis.md @@ -10,8 +10,8 @@ empty, even if `configs/peer/genesis.json` is. Here's an example: ::: The **genesis account** is specified in the -[peer configuration](./peer-configuration.md#genesis) file, -`configs/peer/config.json`. This is the account that will submit the +[`genesis` section of the peer configuration](/reference/peer-config/params#genesis) file. +This is the account that will submit the genesis block. The genesis account is like a super user account that has elevated privileges, but only during the genesis round. The genesis account should be signed by one of the peers, or, in other words, it should have @@ -80,10 +80,3 @@ You can use `kagami` to generate the default genesis block: ``` The genesis block should be located in `configs/peer/genesis.json`. - -## Configuration - -As we already explained, _genesis account_ is specified in the peer -configuration file, `configs/peer/config.json`. You can use the same -configuration file to fine-tune other -[genesis block configurations](./peer-configuration.md#genesis). diff --git a/src/guide/configure/peer-configuration.md b/src/guide/configure/peer-configuration.md deleted file mode 100644 index 554dc9311..000000000 --- a/src/guide/configure/peer-configuration.md +++ /dev/null @@ -1,204 +0,0 @@ -# Peer Configuration - -The peer configuration file (`configs/peer/config.json`) determines how -your blockchain operates. - -Here's an example of how peer configuration file looks like: - -::: details Peer configuration template - -<<< @/snippets/peer-config-template.toml - -::: - -::: info - -Note that for convenient container deployment, configuration options specified via environment variables always override the corresponding values in the configuration file. This way, you can have a basic configuration file and also configure some options in a `docker-compose.yml` or in your shell's environment file (`.bashrc`, `.zshrc`, etc.). - -::: - -Some of the configuration options are required, while others are used for -fine-tuning. When you create a new peer, you are required to provide the -following: - -- [The peer's Public and private keys](#public-and-private-keys) (`PUBLIC_KEY` and - `PRIVATE_KEY`) -- [Iroha public addresses](#iroha-public-addresses) (`P2P_ADDR`, `API_URL`, - `TELEMETRY_URL`) -- [Trusted peers](#trusted-peers) (`TRUSTED_PEERS`) -- [Public and private keys for the genesis account](#genesis) - (`ACCOUNT_PUBLIC_KEY` and `ACCOUNT_PRIVATE_KEY`) - - - -::: info - -Configuration options have different underlying types and default values, -which are denoted in code as types wrapped in a single `Option<..>` or in a -double `Option>`. Refer to -[configuration types](./configuration-types.md) for details. - -::: - -## Generation - -You can use `kagami` to generate the default peer configuration: - -```bash -$ kagami config peer > peer-config.json -``` - -## Public and private keys - -The `configs/peer/config.json` peer configuration file should contain a pair of the user's public `PUBLIC_KEY` and private `PRIVATE_KEY` cryptographic keys for their account's `ACCOUNT_ID`. - -For details on cryptographic keys, see [Public Key Cryptography](../security/public-key-cryptography.md). - -## Trusted Peers - -Iroha is a blockchain ledger. In order for it to work optimally and be -Byzantine-fault tolerant with the maximum number of faults allowed, it -needs to be started with a set number of peers: `4`, `7`, `10`, ... `3f+1`, -where `f` is the allowed number of faults. - -So usually, when you want to start an Iroha deployment, you should already -know a number of peers that you can trust and join their blockchain. The -way it works in the examples is that you just specify in four `config.json` -files four peers with their public keys and API addresses. - -Since Iroha has no automatic peer discovery, the only other way to make -peers known to each other is to use the `iroha` binary to -[register new peers](peer-management.md#registering-peers)). This is not -too difficult with the provided client libraries. With Python's -[Beautiful Soup](https://www.crummy.com/software/BeautifulSoup/), the -curated list of peers can be updated, registered, and un-registered on its -own. - -The list of trusted peers is a part of `SUMERAGI` configuration. Here's an -example of `SUMERAGI_TRUSTED_PEERS` environment variable to configure -trusted peers: - -``` -'[{"address":"iroha0:1337", "public_key": "ed01201c61faf8fe94e253b93114240394f79a607b7fa55f9e5a41ebec74b88055768b"}, {"address":"iroha1:1338", "public_key": "ed0120cc25624d62896d3a0bfd8940f928dc2abf27cc57cefeb442aa96d9081aae58a1"}, {"address": "iroha2:1339", "public_key": "ed0120faca9e8aa83225cb4d16d67f27dd4f93fc30ffa11adc1f5c88fd5495ecc91020"}, {"address": "iroha3:1340", "public_key": "ed01208e351a70b6a603ed285d666b8d689b680865913ba03ce29fb7d13a166c4e7f1f"}]' -``` - -## Iroha Public Addresses - -`TORII` is the module in charge of handling incoming and outgoing -connections. - - - -### `API_URL` - -The `API_URL` is the location to which the client(s) make their requests. -You can also use it to change some peer-specific configuration options. - -Most of the time, the only reason to change the `API_URL` is to change the -port, in case `8080` is either closed, or if you want to randomise ports to -avoid certain kinds of attacks. - -### `P2P_ADDR` - -The `P2P_ADDR` is the internal address used for communication between -peers. This address should be included in the `TRUSTED_PEERS` section of -the configuration file. - -### `TELEMETRY_URL` - -The `TELEMETRY_URL` is used to specify the prometheus endpoint address. -It's set by adding `"TELEMETRY_URL": "127.0.0.1:8180"` to the `TORII` -section of the configuration file. - -It's not meant to be human-readable. However, a `GET` request to the -`127.0.0.1:8180/status` will give you a JSON-encoded representation of the -top-level metrics, while a `GET` request to `127.0.0.1:8180/metrics` will -give you a (somewhat verbose) list of all available metrics gathered in -Iroha. You might want to change this if you're having trouble gathering -metrics using `prometheus`. - -::: info - -Learn how to [monitor Iroha performance](/guide/advanced/metrics.md) using -prometheus. - -::: - -## Genesis - -When you configure a peer, you have to provide private and public keys for -the genesis account. - -You can do this via the configuration file (`ACCOUNT_PUBLIC_KEY`, -`ACCOUNT_PRIVATE_KEY`) or environment variables -(`IROHA_GENESIS_ACCOUNT_PUBLIC_KEY`, `IROHA_GENESIS_ACCOUNT_PRIVATE_KEY`). - -To learn more about genesis block, genesis account, and cryptographic keys, see the following: - -- [Genesis Block](./genesis) -- [Public Key Cryptography](../security/public-key-cryptography) - -Aside from the public and private keys for the genesis account, which are -required configuration options, you can also fine-tune other genesis block -configurations, such as: - -- `WAIT_FOR_PEERS_RETRY_COUNT_LIMIT`: the number of attempts to connect to - peers before genesis block is submitted -- `WAIT_FOR_PEERS_RETRY_PERIOD_MS`: how long to wait before retrying a - connection to peers -- `GENESIS_SUBMISSION_DELAY_MS`: the delay before the genesis block - submission after the minimum number of peers were discovered. - - - -## Logger - -Let's cover the most useful `LOGGER` configurations, `MAX_LOG_LEVEL` and -`LOG_FILE_PATH`. - -### `MAX_LOG_LEVEL` - -The `MAX_LOG_LEVEL` is used to determine which messages are logged. - -With `"MAX_LOG_LEVEL": "WARN"` you won't get any messages unless they are -either a warning or an error. Beside `WARN`, other available options are: - -- `TRACE` (log every time you enter a function) -- `DEBUG` (use when you know something went wrong) -- `INFO` (the default) -- `WARN` (log everything that could be an error) -- `ERROR` (to silence any logging except for error messages) - -### `LOG_FILE_PATH` - -Another useful option is `"LOG_FILE_PATH": bunyan.json`. It creates (if it -didn't already exist) a file called `bunyan.json` that contains the message -log in a structured format. - -This is extremely useful for two reasons. Firstly, you can use the `bunyan` -log viewer to filter information more precisely than Iroha would allow you -to do. Do you only want messages from a specific module or package? You can -do that with `bunyan`. Secondly, while copying logs is not too big of a -problem if your instance is just a small setup, for bigger setups the log -will be larger. Having it saved to a file makes much more sense in that -case. - -::: info - -You can also set `LOG_FILE_PATH` to `/dev/stdout` if you want to use -bunyan's logging facilities directly without saving the output. - -::: - -## Kura - -_Kura_ is the persistent storage engine of Iroha (Japanese for -_warehouse_). The `BLOCK_STORE_PATH` specifies where the blocks are stored. -You can change it to a custom location if for some reason the default -location (`./storage`) is not available or desirable. - - diff --git a/src/guide/configure/sample-configuration.md b/src/guide/configure/sample-configuration.md deleted file mode 100644 index dcf441389..000000000 --- a/src/guide/configure/sample-configuration.md +++ /dev/null @@ -1,16 +0,0 @@ -# Sample Configuration Files - -Here you can find sample configuration files for Iroha 2: - -- Genesis Block [`configs/peer/genesis.json`](https://github.com/hyperledger-iroha/iroha/blob/main/defaults/genesis.json).\ - For details, see [Genesis Block](genesis.md). -- Client Configuration [`configs/client/config.json`](https://github.com/hyperledger-iroha/iroha/blob/main/defaults/client.toml).\ - For details, see [Client Configuration](client-configuration.md). - -::: code-group - -<<< @/snippets/genesis.json - -<<< @/snippets/client-cli-config-template.toml - -::: diff --git a/src/help/overview.md b/src/help/overview.md index b0084bf5a..38973e912 100644 --- a/src/help/overview.md +++ b/src/help/overview.md @@ -21,7 +21,7 @@ first**. Here's a quick explanation: It is not possible to differentiate the error messages that arise when peers' keys do not match the keys in the array of -[trusted peers](/guide/configure/peer-configuration.md#trusted-peers), +trusted peers (TODO link to config guide) because it would expose the peers' public key. As such, if you have Helm charts or K8s deployed with keys defined via the environment variables, you should check for Key definitions. diff --git a/src/reference/binaries.md b/src/reference/binaries.md index 8786e2348..f5d44f6d0 100644 --- a/src/reference/binaries.md +++ b/src/reference/binaries.md @@ -11,7 +11,6 @@ Iroha 2 provides the following binary executables: > See also: > - [Generating Cryptographic Keys](../guide/security/generating-cryptographic-keys.md) — instructions on how to generate cryptographic keys with `kagami`. > - [Configure Iroha > Genesis Block: Generation](../guide/configure/genesis.md#generation) — instructions on how to generate a default genesis block with `kagami`. - > - [Configure Iroha > Peer Configuration: Generation](../guide/configure/peer-configuration.md#generation) — instructions on how to generate a default peer configuration file with `kagami`. > - [Configure Iroha > Client Configuration: Generation](../guide/configure/client-configuration.md#generation) — instructions on how to generate a default client configuration file with `kagami`. There are two main ways to work with Iroha 2 binaries: diff --git a/src/reference/genesis.md b/src/reference/genesis.md new file mode 100644 index 000000000..317110ab3 --- /dev/null +++ b/src/reference/genesis.md @@ -0,0 +1,3 @@ +# Genesis Block + +TODO: describe its structure, purpose, mechanism, encoding with Kagami \ No newline at end of file diff --git a/src/reference/index.md b/src/reference/index.md new file mode 100644 index 000000000..2326cc225 --- /dev/null +++ b/src/reference/index.md @@ -0,0 +1,3 @@ +# Reference + +What is here? \ No newline at end of file diff --git a/src/reference/irohad-cli.md b/src/reference/irohad-cli.md new file mode 100644 index 000000000..92f22a667 --- /dev/null +++ b/src/reference/irohad-cli.md @@ -0,0 +1,47 @@ +# `irohad` CLI + +TODO + +## `--config` {#arg-config} + +- **Type:** File Path +- **Alias:** `-c` + +Path to the [configuration](/reference/peer-config/index.md) file. + +```shell +irohad --config path/to/iroha.toml +``` + +## `--trace-config` {#arg-trace-config} + +Enables trace logs of configuration reading and parsing. Might be useful for configuration troubleshooting. + +- **Type:** flag + +```shell +irohad --trace-config +``` + +## `--terminal-colors` {#arg-terminal-colors} + +- **Type:** Boolean, either `--terminal-colors=false` or + `--terminal-colors=true` +- **Default:** Auto-detect +- **ENV:** `TERMINAL_COLORS` + +Whether to enable ANSI-colored output or not. + +By default, Iroha determines whether the terminal supports colored output +or not. + +To explicitly disable colours: + +```shell +iroha --terminal-colors=false + +# or via env + +set TERMINAL_COLORS=false +iroha +``` diff --git a/src/reference/peer-config/MigrationSnapshotModeTable.vue b/src/reference/peer-config/MigrationSnapshotModeTable.vue new file mode 100644 index 000000000..8672b1316 --- /dev/null +++ b/src/reference/peer-config/MigrationSnapshotModeTable.vue @@ -0,0 +1,27 @@ + + + diff --git a/src/reference/peer-config/ParamTable.vue b/src/reference/peer-config/ParamTable.vue new file mode 100644 index 000000000..2794187a2 --- /dev/null +++ b/src/reference/peer-config/ParamTable.vue @@ -0,0 +1,88 @@ + + + + + diff --git a/src/reference/peer-config/index.md b/src/reference/peer-config/index.md new file mode 100644 index 000000000..870bbb3b2 --- /dev/null +++ b/src/reference/peer-config/index.md @@ -0,0 +1,64 @@ +# Configuring Iroha + +Local peer configuration is set via Environment and/or TOML files. Note that this is different from On-Chain +Configuration set via `SetParameter` instruction (TODO refer to ISI reference). + +Use [`--config`](../irohad-cli#arg-config) CLI argument to specify the path to the configuration file. + +## Template + +For a detailed description of each parameter, please refer to the [Parameters](./params.md) reference. + +::: details `peer.template.toml` + +<<< @/snippets/peer.template.toml + +::: + +## Composing configuration files + +TOML configuration files has an additional `extends` field, pointing to other TOML file(s). It could be a single path or +multiple paths:Example format: + +::: code-group + +```toml [Single] +extends = "single-path.toml" +``` + +```toml [Multiple] +extends = ["file1.toml", "file2.toml"] +``` + +::: + +Iroha will recursively read all files specified in `extends` and compose them into layers, where latter ones overwrite +previous ones on a parameter level. For example, if reading `config.toml`: + +::: code-group + +```toml [config.toml] +extends = ["a.toml", "b.toml"] + +[torii] +address = "0.0.0.0:8080" +``` + +```toml [a.toml] +chain_id = "whatever" +``` + +```toml [b.toml] +[torii] +address = "localhost:4000" +max_content_len = 2048 +``` + +::: + +The resulting configuration will be `chain_id` from `a.toml`, `max_content_len` from `b.toml`, and `torii.address` from +`config.toml` (overwrites `b.toml`). + +## Troubleshooting + +Pass [`--trace-config`](../irohad-cli#arg-trace-config) CLI flag to see a trace of how configuration is read and parsed. diff --git a/src/reference/peer-config/migration.md b/src/reference/peer-config/migration.md new file mode 100644 index 000000000..a22a00d09 --- /dev/null +++ b/src/reference/peer-config/migration.md @@ -0,0 +1,204 @@ + + +# Migrate Configuration + +...from `2.0.0-pre-rc.20` to the new format. + +::: danger + +This is an unstable document, Work in Progress. + +::: + +Do the following: + +- Update CLI and ENVs +- Use TOML for the config file +- Update parameters +- [Sign genesis with Kagami](../genesis.md) + +## CLI and Environment + +Here, the **After** column contains _all_ new supported environment +variables. Environment variables aren't mentioned in the **Before** column +were removed. + +| Before | After | +| ----------------------------------: |--------------------------------------------------------------------| +| `IROHA2_CONFIG_PATH` | removed, use [`--config`](../irohad-cli#arg-config) instead | +| `IROHA2_GENESIS_PATH` | [`GENESIS_FILE`](params#param-genesis-file) | +| `IROHA_PUBLIC_KEY` | [`PUBLIC_KEY`](params#param-public-key) | +| `IROHA_PRIVATE_KEY` | [`PRIVATE_KEY`](params#param-private-key) | +| `TORII_P2P_ADDR` | [`P2P_ADDRESS`](params#param-network-address) | +| `IROHA_GENESIS_ACCOUNT_PUBLIC_KEY` | [`GENESIS_PUBLIC_KEY`](params#param-genesis-public-key) | +| `IROHA_GENESIS_ACCOUNT_PRIVATE_KEY` | removed; genesis block is signed with it outside of Iroha | +| `TORII_API_URL` | [`API_ADDRESS`](params#param-torii-address) | +| `KURA_INIT_MODE` | [same](params#param-kura-init-mode) | +| `KURA_BLOCK_STORE_PATH` | [`KURA_STORE_DIR`](params#param-kura-store-dir) | +| `KURA_DEBUG_OUTPUT_NEW_BLOCKS` | [same](params#param-kura-debug-output-new-blocks) | +| `MAX_LOG_LEVEL` | [`LOG_LEVEL`](params#param-logger-level) | +| `COMPACT_MODE` | removed, see [`LOG_FORMAT`](params#param-logger-format) | +| `TERMINAL_COLORS` | same, see [`--terminal-colors`](../irohad-cli#arg-terminal-colors) | +| `SNAPSHOT_CREATION_ENABLED` | removed, see [`SNAPSHOT_MODE`](params#param-snapshot-mode) | +| `SNAPSHOT_DIR_PATH` | [`SNAPSHOT_STORE_DIR`](params#param-snapshot-store-dir) | +| `SUMERAGI_TRUSTED_PEERS` | [same](params#param-trusted-peers) | +| ...all other ones | removed | + +## Configuration Parameters + +New mandatory parameters: + +- [`chain_id`](params#param-chain-id) +- [`network.public_address`](params#param-network-public-address) + +List of all old parameters: + +- Root parameters: see [Root-Level Params](params#root) + - `PRIVATE_KEY`: became [`private_key`](params#param-private-key) + - `PUBLIC_KEY`: became [`public_key`](params#param-public-key) +- ~~`BLOCK_SYNC`~~: section removed + - ~~`ACTOR_CHANNEL_CAPACITY`~~: removed + - `BLOCK_BATCH_SIZE`: became + [`network.block_gossip_size`](params#param-network-block-gossip-size) + - `GOSSIP_PERIOD_MS`: became + [`network.block_gossip_period_ms`](params#param-network-block-gossip-period-ms) +- ~~`DISABLE_PANIC_TERMINAL_COLORS`~~: removed +- `GENESIS`: see [Genesis Params](params#genesis) + - `ACCOUNT_PRIVATE_KEY`: removed (must be used to sign the genesis block now) + - `ACCOUNT_PUBLIC_KEY`: became + [`genesis.public_key`](params#param-genesis-public-key) +- `KURA`: see [Kura Params](params#kura) + - ~~`ACTOR_CHANNEL_CAPACITY`~~: removed + - ~~`BLOCKS_PER_STORAGE_FILE`~~: removed + - `BLOCK_STORE_PATH`: became + [`kura.store_dir`](params#param-kura-store-dir) + - `DEBUG_OUTPUT_NEW_BLOCKS`: became + [`kura.debug.output_new_blocks`](params#param-kura-debug-output-new-blocks) + - `INIT_MODE`: same, lowercase +- `LOGGER`: see [Logger Params](params#logger) + - ~~`COMPACT_MODE`~~: removed; now might be enabled with + [`logger.format = "compact"`](params#param-logger-format) + - ~~`LOG_FILE_PATH`~~: removed; use STDOUT redirection instead and enable + JSON format with [`logger.format = "json"`](params#param-logger-format) + - `MAX_LOG_LEVEL`: became [`logger.log_level`](params#param-logger-level) + - ~~`TELEMETRY_CAPACITY`~~: removed + - ~~`TERMINAL_COLORS`~~: removed; use [`--terminal-colors`](../irohad-cli#arg-terminal-colors) + instead +- `NETWORK`: see [Network Params](params#network), some parameters migrated + here + - ~~`ACTOR_CHANNEL_CAPACITY`~~: removed +- `QUEUE`: see [Queue Params](params#queue) + - `FUTURE_THRESHOLD_MS`: removed + - `MAX_TRANSACTIONS_IN_QUEUE`: became + [`queue.capacity`](params#param-queue-capacity) + - `MAX_TRANSACTIONS_IN_QUEUE_PER_USER`: became + [`queue.capacity_per_user`](params#param-queue-capacity-per-user) + - `TRANSACTION_TIME_TO_LIVE_MS`: became + [`queue.transaction_time_to_live`](params#param-queue-transaction-time-to-live-ms) +- `SNAPSHOT`: see [Snapshot Params](params#snapshot) + - `CREATE_EVERY_MS`: became + [`snapshot.create_every_ms`](params#param-snapshot-create-every-ms) + - `CREATION_ENABLED`: removed in favour of + [`snapshot.mode`](params#param-snapshot-mode); see the mapping: + + - `DIR_PATH`: became + [`snapshot.store_dir`](params#param-snapshot-store-dir) +- `SUMERAGI`: see [Sumeragi Params](params#sumeragi) + - ~~`ACTOR_CHANNEL_CAPACITY`~~: removed + - ~~`BLOCK_TIME_MS`~~: removed[^1] + - ~~`COMMIT_TIME_LIMIT_MS`~~: removed[^1] + - `GOSSIP_BATCH_SIZE`: became + [`network.transaction_gossip_size`](params#param-network-transaction-gossip-size) + - `GOSSIP_PERIOD_MS`: became + [`network.transaction_gossip_period_ms`](params#param-network-transaction-gossip-period-ms) + - ~~`KEY_PAIR`~~: removed + - ~~`MAX_TRANSACTIONS_IN_BLOCK`~~: removed[^1] + - ~~`PEER_ID`~~: removed + - `TRUSTED_PEERS`: [same, lowercase](params#param-trusted-peers) +- `TELEMETRY`: see [Telemetry Params](params#telemetry) + - `FILE`: became [`dev_telemetry.out_file`](./params.md#param-dev-telemetry-out-file) + - `MAX_RETRY_DELAY_EXPONENT`: same, lowercase + - `MIN_RETRY_PERIOD`: same, lowercase + - `NAME`: same, lowercase + - `URL`: same, lowercase +- `TORII`: see [Torii Params](params#torii) + - `API_URL`: became [`torii.address`](params#param-torii-address) + - ~~`FETCH_SIZE`~~: removed + - `MAX_CONTENT_LEN`: same, lowercase + - ~~`MAX_TRANSACTION_SIZE`~~: removed + - `P2P_ADDR`: became [`network.address`](params#param-network-address) + - `QUERY_IDLE_TIME_MS`: became `torii.query_idle_time` +- ~~`WSV`~~: removed[^1] + +[^1]: on-chain configuration removed from configuration file. TODO link reference. + +## Example + +**Complete setup before:** + +::: code-group + +```shell [CLI] +export IROHA2_CONFIG=./config.json +export IROHA2_GENESIS=./genesis.json + +iroha --submit-genesis +``` + +```json [Configuration file] +{ + "PUBLIC_KEY": "ed01201C61FAF8FE94E253B93114240394F79A607B7FA55F9E5A41EBEC74B88055768B", + "PRIVATE_KEY": { + "digest_function": "ed25519", + "payload": "282ED9F3CF92811C3818DBC4AE594ED59DC1A2F78E4241E31924E101D6B1FB831C61FAF8FE94E253B93114240394F79A607B7FA55F9E5A41EBEC74B88055768B" + }, + "TORII": { + "API_URL": "127.0.0.1:8080", + "P2P_ADDR": "127.0.0.1:1337" + }, + "GENESIS": { + "ACCOUNT_PUBLIC_KEY": "ed01203F4E3E98571B55514EDC5CCF7E53CA7509D89B2868E62921180A6F57C2F4E255", + "ACCOUNT_PRIVATE_KEY": { + "digest_function": "ed25519", + "payload": "038AE16B219DA35AA036335ED0A43C28A2CC737150112C78A7B8034B9D99C9023F4E3E98571B55514EDC5CCF7E53CA7509D89B2868E62921180A6F57C2F4E255" + } + }, + "KURA": { + "BLOCK_STORE_PATH": "./storage" + } +} +``` + +::: + +**Complete setup after:** + +::: code-group + +```shell [CLI] +iroha --submit-genesis --config ./iroha.toml +``` + +```toml [Configuration file] +chain_id = "000" +public_key = "ed01201C61FAF8FE94E253B93114240394F79A607B7FA55F9E5A41EBEC74B88055768B" +private_key = { algorithm = "ed25519", payload = "282ED9F3CF92811C3818DBC4AE594ED59DC1A2F78E4241E31924E101D6B1FB831C61FAF8FE94E253B93114240394F79A607B7FA55F9E5A41EBEC74B88055768B" } + +[network] +address = "127.0.0.1:1337" + +[torii] +address = "127.0.0.1:8080" + +[kura] +store_dir = "./storage" + +[genesis] +public_key = "ed01203F4E3E98571B55514EDC5CCF7E53CA7509D89B2868E62921180A6F57C2F4E255" +private_key = { algorithm = "ed25519", payload = "038AE16B219DA35AA036335ED0A43C28A2CC737150112C78A7B8034B9D99C9023F4E3E98571B55514EDC5CCF7E53CA7509D89B2868E62921180A6F57C2F4E255" } +file = "./genesis.json" +``` + +::: diff --git a/src/reference/peer-config/params.md b/src/reference/peer-config/params.md new file mode 100644 index 000000000..179b49dd7 --- /dev/null +++ b/src/reference/peer-config/params.md @@ -0,0 +1,815 @@ +--- +outline: [ 2, 3 ] +--- + + + +# Configuration Parameters + +[[toc]] + +## Root-Level {#root} + +### `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) + + + +::: code-group + +```toml [Config File] +chain_id = "00000000-0000-0000-0000-000000000000" +``` + +```shell [Environment] +CHAIN_ID="00000000-0000-0000-0000-000000000000" +``` + +::: + +### `public_key` {#param-public-key} + +Public key of the peer. + + + +::: code-group + +```toml [Config File] +public_key = "ed0120FAFCB2B27444221717F6FCBF900D5BE95273B1B0904B08C736B32A19F16AC1F9" +``` + +```shell [Environment] +PUBLIC_KEY="ed0120FAFCB2B27444221717F6FCBF900D5BE95273B1B0904B08C736B32A19F16AC1F9" +``` + +::: + +### `private_key` {#param-private-key} + +Private key of the peer. + + + +::: code-group + +```toml [Config File] +private_key = "8026208F4C15E5D664DA3F13778801D23D4E89B76E94C1B94B389544168B6CB894F84F" +``` + +```shell [Environment] +PRIVATE_KEY="8026208F4C15E5D664DA3F13778801D23D4E89B76E94C1B94B389544168B6CB894F84F" +``` + +::: + +### `trusted_peers` {#param-trusted-peers} + +List of predefined trusted peers. + + + + + +::: code-group + +```toml [Config File] +trusted_peers = [ + "ed01201C61FAF8FE94E253B93114240394F79A607B7FA55F9E5A41EBEC74B88055768B@127.0.0.1:1337", + "ed0120CC25624D62896D3A0BFD8940F928DC2ABF27CC57CEFEB442AA96D9081AAE58A1@127.0.0.1:1338", + "ed0120FACA9E8AA83225CB4D16D67F27DD4F93FC30FFA11ADC1F5C88FD5495ECC91020@127.0.0.1:1339", + "ed01208E351A70B6A603ED285D666B8D689B680865913BA03CE29FB7D13A166C4E7F1F@127.0.0.1:1340", +] +``` + +```shell [Environment] +# as JSON +TRUSTED_PEERS='["ed01204EE2FCD53E1730AF142D1E23951198678295047F9314B4006B0CB61850B1DB10@irohad2:1339","ed01209897952D14BDFAEA780087C38FF3EB800CB20B882748FC95A575ADB9CD2CB21D@irohad1:1338","ed0120CACF3A84B8DC8710CE9D6B968EE95EC7EE4C93C85858F026F3B4417F569592CE@irohad3:1340"]' +``` + +::: + +## Genesis {#genesis} + +### `genesis.file` {#param-genesis-file} + +File path to the SCALE-encoded genesis block. + + + +::: code-group + +```toml [Config File] +[genesis] +file = "./genesis.scale" +``` + +```shell [Environment] +GENESIS="./genesis.scale" +``` + +::: + +### `genesis.public_key` {#param-genesis-public-key} + +Public key of the genesis key pair. + + + +::: code-group + +```toml [Config File] +[genesis] +public_key = "ed01208BA62848CF767D72E7F7F4B9D2D7BA07FEE33760F79ABE5597A51520E292A0CB" +``` + +```shell [Environment] +GENESIS_PUBLIC_KEY="ed01208BA62848CF767D72E7F7F4B9D2D7BA07FEE33760F79ABE5597A51520E292A0CB" +``` + +::: + +## Network {#network} + +### `network.address` {#param-network-address} + +Address for p2p communication for consensus (sumeragi) and block synchronization (block_sync) purposes. + + + +::: code-group + +```toml [Config File] +[network] +address = "0.0.0.0:1337" +``` + +```shell [Environment] +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. + + + +::: code-group + +```toml [Config File] +[network] +public_address = "0.0.0.0:5000" +``` + +```shell [Environment] +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. + + + +::: 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. + + + +::: 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. + + + +::: 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. + + + +::: 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. + + + +::: code-group + +```toml [Config File] +[network] +idle_timeout_ms = 60_000 +``` + +::: + +## Torii {#torii} + +### `torii.address` {#param-torii-address} + +Address to which the Torii server must listen and to which the client(s) make their requests. + + + +::: code-group + +```toml [Config File] +[torii] +address = "0.0.0.0:8080" +``` + +```shell [Environment] +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. + + + + + + +::: code-group + +```toml [Config File] +[torii] +max_content_len = 16_777_216 +``` + +::: + +### `torii.query_idle_time_ms` {#param-torii-query-idle-time-ms} + +The time a query can remain in the store if unaccessed. + + + +::: code-group + +```toml [Config File] +[torii] +query_idle_time_ms = 10_000 +``` + +::: + +### `torii.query_store_capacity` {#param-torii-query-store-capacity} + +The upper limit of the number of live queries. + + + +::: code-group + +```toml [Config File] +[torii] +query_store_capacity = 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. + + + +::: code-group + +```toml [Config File] +[torii] +query_store_capacity_per_user = 128 +``` + +::: + +## Logger {#logger} + +### `logger.level` {#param-logger-level} + +_General_ logging verbosity (see [`logger.filter`](#param-logger-filter) for refined configuration). + + + + + +::: code-group + +```toml [Config File] +[logger] +level = "INFO" +``` + +```shell [Environment] +LOG_LEVEL=INFO +``` + +::: + +::: tip Runtime update + +This parameter is subject for [runtime configuration update](/reference/torii-endpoints#configuration-update). + +::: + +### `logger.filter` {#param-logger-filter} + +Refined log filters in addition to [`logger.level`](#param-logger-level). Allows to customize logging verbosity +per-_target_. + + + + + + +::: code-group + +```toml [Config File] +[logger] +filter = "iroha_core=debug,iroha_p2p=debug" +``` + +```shell [Environment] +LOG_FILTER=iroha_core=debug,iroha_p2p=debug +``` + +::: + +::: info Compatibility with [`logger.level`](#param-logger-level) + +`logger.filter` works _together_ with [`logger.level`](#param-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`). + +::: + +::: tip Runtime update + +This parameter is subject for [runtime configuration update](/reference/torii-endpoints#configuration-update). + +::: + +### `logger.format` {#param-logger-format} + +Logs format. + + + + + +::: code-group + +```toml [Config File] +[logger] +format = "json" +``` + +```shell [Environment] +LOG_FORMAT=json +``` + +::: + +## Kura {#kura} + +_Kura_ is the persistent storage engine of Iroha (Japanese for _warehouse_). + +### `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. + + + +::: code-group + +```toml [Config File] +[kura] +blocks_in_memory = 256 +``` + +```shell [Environment] +KURA_BLOCKS_IN_MEMORY=256 +``` + +::: + +### `kura.init_mode` {#param-kura-init-mode} + +Kura initialisation mode + + + + + +::: code-group + +```toml [Config File] +[kura] +init_mode = "fast" +``` + +```shell [Environment] +KURA_INIT_MODE=fast +``` + +::: + +### `kura.store_dir` {#param-kura-store-dir} + +Specifies the directory[^paths] where the blocks are stored. + +See also: [`snapshot.store_dir`](#param-snapshot-store-dir). + + + +::: code-group + +```toml [Config File] +[kura] +store_dir = "/path/to/storage" +``` + +```shell [Environment] +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. + + + +::: code-group + +```toml [Config File] +[kura.debug] +output_new_blocks = true +``` + +```shell [Environment] +KURA_DEBUG_OUTPUT_NEW_BLOCKS=true +``` + +::: + +## Queue {#queue} + +### `queue.capacity` {#param-queue-capacity} + +The upper limit of the number of transactions waiting in the queue. + + + +::: 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. + + + +::: 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. + + + +::: code-group + +```toml [Config File] +[queue] +transaction_time_to_live_ms = 43_200_000 +``` + +::: + +## Sumeragi {#sumeragi} + +### `sumeragi.debug.force_soft_fork` {#param-sumeragi-debug-force-soft-fork} + +TODO + + + +::: code-group + +```toml [Config File] +[sumeragi.debug] +force_soft_fork = true +``` + +::: + +## Snapshot {#snapshot} + +This module is responsible for reading and writing snapshots of the +[World State View](/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-snapshot-store-dir). + +::: + +### `snapshot.mode` {#param-snapshot-mode} + +The mode the Snapshot system functions in. + + + + + +::: code-group + +```toml [Config File] +[snapshot] +mode = "readonly" +``` + +```shell [Environment] +SNAPSHOT_MODE=readonly +``` + +::: + +### `snapshot.create_every_ms` {#param-snapshot-create-every-ms} + +Frequency of snapshots. + + + +::: code-group + +```toml [Config File] +[snapshot] +create_every_ms = 60_000 +``` + +::: + +### `snapshot.store_dir` {#param-snapshot-store-dir} + +Directory where to store snapshots. + +See also: [`kura.store_dir`](#param-kura-store-dir) + + + +::: code-group + +```toml [Config File] +[snapshot] +store_dir = "/path/to/storage" +``` + +```shell [Environment] +SNAPSHOT_STORE_DIR="/path/to/storage" +``` + +::: + +## Telemetry {#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. + + + +::: code-group + +```toml [Config File] +[telemetry] +name = "iroha" +``` + +::: + +### `telemetry.url` {#param-telemetry-url} + +The url of the telemetry. TODO update example value + + + +::: 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. + + + +::: 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. + + + +::: 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 + + + +::: code-group + +```toml [Config File] +[dev_telemetry] +out_file = "/path/to/file.json" +``` + +::: diff --git a/src/reference/torii-endpoints.md b/src/reference/torii-endpoints.md index 20ec32ebd..22840397b 100644 --- a/src/reference/torii-endpoints.md +++ b/src/reference/torii-endpoints.md @@ -43,11 +43,6 @@ To establish two-way communication with the `TORII` endpoints, the following add This address is the same as the `TORII_API_URL` address in the `configs/client_cli/config.json` client configuration file. - `TELEMETRY_URL` — connects to the [Prometheus](https://prometheus.io/) endpoint address that is used as a [metrics](../guide/advanced/metrics.md) tool to monitor the network performance. - ::: info - - To learn more, see [Peer Configuration > Iroha Public Addresses](../guide/configure/peer-configuration.html#iroha-public-addresses). - - ::: --> @@ -71,9 +66,10 @@ with the `telemetry` feature enabled. #### Responses -| Code | Response | Description | -| :--: | -------- | ------------------------------------------------------------------------------------------- | -| 200 | OK | Returns the current version of the API used by the requested Iroha 2 node as a JSON string. | +| Code | Response | Description | +| :-----: | -------- | ----------------------------------------------------------------------------------- | +| 200 | OK | Returns the current version of the API used by the requested Iroha 2 node as a JSON | +| string. | **Example**: @@ -488,27 +484,41 @@ is used by default. The response body has the following structure: -```rust -struct Status { - /// Number of connected peers, except for the reporting peer itself - peers: u64, - /// Number of committed blocks - blocks: u64, - /// Number of accepted transactions - txs_accepted: u64, - /// Number of rejected transactions - txs_rejected: u64, - /// Uptime since genesis block creation - uptime: Uptime, - /// Number of view changes in the current round - view_changes: u64, - /// Number of the transactions in the queue - queue_size: u64, -} +`200 OK` reports status as JSON: + +::: details Sample response -struct Uptime { - secs: u64, - nanos: u32 +```json5 +// Note: while this snippet is JSON5 (for better readability), +// the actual response is JSON +{ + /** + * Number of connected peers, except for the reporting peer itself + */ + peers: 3, + /** + * Number of committed blocks (block height) + */ + blocks: 1, + /** + * Total number of accepted transactions + */ + txs_accepted: 3, + /** + * Total number of rejected transactions + */ + txs_rejected: 0, + /** + * Uptime with nanosecond precision since creation of the genesis block + */ + uptime: { + secs: 5, + nanos: 937000000, + }, + /** + * Number of view changes in the current round + */ + view_changes: 0, } ```