diff --git a/.vitepress/config.mts b/.vitepress/config.mts index 465a1aa3c..38d2f7a95 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', @@ -89,6 +89,10 @@ function sidebarGuide(): DefaultTheme.SidebarItem[] { text: 'JavaScript', link: '/guide/tutorials/javascript', }, + { + text: 'Compatibility Matrix', + link: '/reference/compatibility-matrix', + }, ], }, { @@ -99,18 +103,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', @@ -303,10 +295,10 @@ function sidebarChain(): DefaultTheme.SidebarItem[] { ] } -function sidebarAPI(): DefaultTheme.SidebarItem[] { +function sidebarReference(): DefaultTheme.SidebarItem[] { return [ { - text: 'About', + text: 'Reference', items: [ { text: 'Glossary', @@ -316,23 +308,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 +324,30 @@ function sidebarAPI(): DefaultTheme.SidebarItem[] { text: 'Permissions', link: '/reference/permissions.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', + }, ], }, ] @@ -465,13 +464,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/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/etc/meta.ts b/etc/meta.ts index d34632004..78279e6b8 100644 --- a/etc/meta.ts +++ b/etc/meta.ts @@ -1,7 +1,7 @@ /** - * hyperledger-iroha/iroha#iroha2-dev + * `main` as of 2024/11/13 */ -export const IROHA_REV_DEV = 'e7a605c1a926c319d214ef3825524ee6c2e9f076' +export const IROHA_REV_DEV = '2a30fc97087d48f0aa95ef0382038c4a06288828' /** * hyperledger-iroha/iroha-javascript#iroha2 (rc13) diff --git a/etc/snippet-sources.ts b/etc/snippet-sources.ts index bb4b14592..381db419f 100644 --- a/etc/snippet-sources.ts +++ b/etc/snippet-sources.ts @@ -116,18 +116,18 @@ export default [ src: './src/example_code/lorem.rs', }, { - src: `https://raw.githubusercontent.com/hyperledger-iroha/iroha/${IROHA_REV_DEV}/configs/client.template.toml`, - filename: 'client-cli-config-template.toml', + src: `https://raw.githubusercontent.com/hyperledger-iroha/iroha/${IROHA_REV_DEV}/docs/source/references/client.template.toml`, + // filename: 'client-cli-config-template.toml', }, { - src: `https://raw.githubusercontent.com/hyperledger-iroha/iroha/${IROHA_REV_DEV}/configs/peer.template.toml`, - filename: 'peer-config-template.toml', + src: `https://raw.githubusercontent.com/hyperledger-iroha/iroha/${IROHA_REV_DEV}/docs/source/references/peer.template.toml`, + // filename: 'peer-config-template.toml', }, { - src: `https://raw.githubusercontent.com/hyperledger-iroha/iroha/${IROHA_REV_DEV}/configs/swarm/genesis.json`, + src: `https://raw.githubusercontent.com/hyperledger-iroha/iroha/${IROHA_REV_DEV}/defaults/genesis.json`, }, { - src: `https://raw.githubusercontent.com/hyperledger-iroha/iroha/${IROHA_REV_DEV}/client/examples/tutorial.rs`, + src: `https://raw.githubusercontent.com/hyperledger-iroha/iroha/${IROHA_REV_DEV}/crates/iroha/examples/tutorial.rs`, filename: 'tutorial-snippets.rs', }, 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/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..e77404e26 --- /dev/null +++ b/src/reference/irohad-cli.md @@ -0,0 +1,55 @@ +# `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 +``` + +::: tip + +Paths parameters in the config file are resolved relative to its own +location. See how +[paths resolution](/reference/peer-config/glossary#paths-resolution) works. + +::: + +## `--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/glossary.md b/src/reference/peer-config/glossary.md new file mode 100644 index 000000000..c14c35854 --- /dev/null +++ b/src/reference/peer-config/glossary.md @@ -0,0 +1,159 @@ +# Glossary + +This page contains the definitions and brief explanations of data types and topics shared across +multiple configuration parameters. + +## Numeric Types + +TODO Explain the limitations of different numeric types, like `u8` and `u64`. + +## Type: Duration + +Duration is specified as a human-readable string: + +```toml +value1 = "1sec" +value2 = "1hour 12min 5s" +value3 = "2years 2min 12us" +value4 = "550ms" +``` + +The duration string is a concatenation of time spans. Each time span is an +integer number and a suffix. Supported suffixes: + +- `nsec`, `ns` — nanoseconds +- `usec`, `us` — microseconds +- `msec`, `ms` — milliseconds +- `seconds`, `second`, `sec`, `s` +- `minutes`, `minute`, `min`, `m` +- `hours`, `hour`, `hr`, `h` +- `days`, `day`, `d` +- `weeks`, `week`, `w` +- `months`, `month`, `M` — defined as $30.44$ days +- `years`, `year`, `y` — defined as $365.25$ days + +TODO: put link to +[`humantime` crate](https://docs.rs/humantime/latest/humantime/fn.parse_duration.html)? +It is an implementation detail. + +## Type: Multi-hash + + +To configure Multihash types in Iroha 2, you specify the cryptographic hash function used for digital signatures or data integrity verification. Iroha 2 supports a limited set of hash functions, identified by unique byte codes as defined in the [official multicodec table](https://github.com/multiformats/multicodec/blob/master/table.csv). + +Supported Digest Functions: + +- `Ed25519Pub` (code: `0xed`) - Ed25519 public key +- `Secp256k1Pub` (code: `0xe7`) - Secp256k1 public key +- `Bls12381G1Pub` (code: `0xea`) - BLS12-381 G1 public key +- `Bls12381G2Pub` (code: `0xeb`) - BLS12-381 G2 public key + +Below is an example of how to specify these multihashes in your TOML configuration: + +```toml +# Ed25519 public key hash +ed25519_pub = "0xed..." + +# Secp256k1 public key hash +secp256k1_pub = "0xe7..." + +# BLS12-381 G1 public key hash +bls12381_g1_pub = "0xea..." + +# BLS12-381 G2 public key hash +bls12381_g2_pub = "0xeb..." +``` + +In these examples, replace `` with the actual hash output encoded in hexadecimal. The code before the hash value corresponds to the hash function used, as per the Iroha 2 supported options. + +For further details on Multihash and its implementation, please refer to the [Multihash specification](https://multiformats.io/multihash/) and the [Multicodec Table](https://github.com/multiformats/multicodec/blob/master/table.csv) for a comprehensive list of hash function codes. + + +## Type: Bytes Amount + +Bytes amount is specified as a human-readable string: + +```toml +# 42 bytes +value1 = "42B" + +# 1 kilobyte = 1000 bytes +value2 = "1KB" + +# 1 kilobyte (binary format) = 1024 bytes +value3 = "1KiB" + +# Sum of multiple +value4 = "1GB 5MB" +``` + +Iroha can parse sizes in bytes, kilobytes (`K`), megabytes (`M`), gigabytes (`G`), terabytes (`T`), +and petabytes (`P`). + +The format of suffixes: + +- **`{size}iB`:** Binary size +- **`{size}B`:** Decimal size + +TODO: haven't found a rust lib for that. There is a Python one +([`humanfriendly`](https://humanfriendly.readthedocs.io/en/latest/api.html?highlight=parse_size#humanfriendly.parse_size)) +I used for reference. + +TODO: [article explains kb, kB, KiB difference](https://web.archive.org/web/20150324153922/https://pacoup.com/2009/05/26/kb-kb-kib-whats-up-with-that/). +Consider it for the format. + +## Type: Private Key + +TODO explain private key + +```toml +private_key = { algorithm = "ed25519", payload = "" } +``` + +## Type: Socket Address + +To specify a socket address in the configuration, use the format `host:port`, where `host` is either a hostname or an IP address, and `port` is the numeric port number the application should connect to or listen on. + +- **Hostname example**: `localhost:8080` +- **IP address example**: `192.168.1.100:8080` + +**Hostname**: Can be a local hostname (`localhost` for the local machine) or a remote server's domain name (e.g., `example.com`). + +**IP address**: Use IPv4 (e.g., `192.168.1.100`) or IPv6 (enclosed in square brackets, e.g., `[2001:db8::1]`) formats. + +**Port**: A numeric value typically ranging from `1` to `65535`, where ports below `1024` are reserved for well-known services and require root privileges on Unix-like systems. + +**Example in TOML:** + +```toml +address = "localhost:8080" +``` + +For more information on socket addresses and networking, refer to the [IANA Service Name and Transport Protocol Port Number Registry](https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml) or the [RFC 3986](https://tools.ietf.org/html/rfc3986) specification. + +## Paths Resolution + +There are numerous parameters in the configuration that specify file paths. These paths might be relative. If they are specified in the config file, they are resolved relative to the config file location. If a path is specified via a Environment Variable, it is resolved relative to the CWD. + +For example, we run Iroha from `/home/alice` directory, using a config file at `/home/alice/projects/iroha.toml`: + +```shell +iroha --config ./projects/iroha.toml +``` + +In `iroha.toml`, we specify [`kura.store_dir`](params#param-kura-store-dir): + +```toml +[kura] +store_dir = "./storage" +``` + +This path will be resolved as `/home/alice/projects/storage`. + +On the other hand, if we pass it via env: + +```shell +KURA_STORE_DIR=./env-storage iroha --config ./projects/iroha.toml +``` + +Then it will be set to `/home/alice/env-storage`. 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..e605be298 --- /dev/null +++ b/src/reference/peer-config/params.md @@ -0,0 +1,740 @@ +--- +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) + +- **Environment:** `CHAIN_ID` +- **Type:** String + +::: 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. + +- **Environment:** `PUBLIC_KEY` +- **Type:** String + +::: code-group + +```toml [Config File] +public_key = "ed0120FAFCB2B27444221717F6FCBF900D5BE95273B1B0904B08C736B32A19F16AC1F9" +``` + +```shell [Environment] +PUBLIC_KEY="ed0120FAFCB2B27444221717F6FCBF900D5BE95273B1B0904B08C736B32A19F16AC1F9" +``` + +::: + +### `private_key` {#param-private-key} + +Private key of the peer. + +- **Environment:** `PRIVATE_KEY` +- **Type:** String + +::: code-group + +```toml [Config File] +private_key = "8026208F4C15E5D664DA3F13778801D23D4E89B76E94C1B94B389544168B6CB894F84F" +``` + +```shell [Environment] +PRIVATE_KEY="8026208F4C15E5D664DA3F13778801D23D4E89B76E94C1B94B389544168B6CB894F84F" +``` + +::: + +### `trusted_peers` {#param-trusted-peers} + +List of predefined trusted peers. + +- **Environment:** `TRUSTED_PEERS` +- **Type:** Array of strings in a format `PUBLIC_KEY@ADDRESS` + +::: 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[^paths] to the SCALE-encoded genesis block. + +Must be paired with `--submit-genesis` CLI parameter. + +- **Environment:** `GENESIS` +- **Type:** String, file path[^paths] + +::: 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. + +- **Environment:** `GENESIS_PUBLIC_KEY` +- **Type:** String, public key multihash + +::: 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. + +- **Environment:** `P2P_ADDRESS` +- **Type:** String, socket address (host/IPv4/IPv6 + port) + +::: 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. + +- **Environment:** `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 [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. + +- **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 {#torii} + +### `torii.address` {#param-torii-address} + +Address to which the Torii server must listen and to which the client(s) make their requests. + +- **Environment:** `API_ADDRESS` +- **Type:** String, socket address (host/IPv4/IPv6 + port) + +::: 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. + +- **Type:** Number (of bytes) +- **Default:** `16_777_216` (16 MiB, $2^{20} \cdot 16$) + +::: 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. + +- **Type:** Number (of milliseconds) +- **Default:** `10_000` (10 seconds) + +::: 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. + +- **Type:** Number +- **Default:** `128` + +::: 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. + +- **Type:** Number +- **Default:** `128` + +::: code-group + +```toml [Config File] +[torii] +query_store_capacity_per_user = 128 +``` + +::: + +## Logger {#logger} + +### `logger.level` {#param-logger-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. + +- **Environment:** `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 [Environment] +LOG_LEVEL="INFO" +``` + +::: + +### `logger.format` {#param-logger-format} + +Logs format. + +- **Environment:** `LOG_FORMAT` +- **Type:** String, possible values: (TODO: describe) + - `full` + - `compact` + - `pretty` + - `json` +- **Default:** `full` + +::: 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. + +- **Environment:** `KURA_BLOCKS_IN_MEMORY` +- **Type:** Number +- **Default:** `128` + +::: 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 + +- **Environment:** `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 [Environment] +KURA_INIT_MODE="fast" +``` + +::: + +### `kura.store_dir` {#param-kura-store-dir} + +Specifies the directory[^paths] where the blocks are stored. + +- **Environment:** `KURA_STORE_DIR` +- **Type:** String, file path[^paths] +- **Default:** `./storage` (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. + +- **Environment:** `KURA_DEBUG_OUTPUT_NEW_BLOCKS` +- **Type:** Boolean +- **Default:** `false` + +::: 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. + +- **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 +``` + +::: + +## Sumeragi {#sumeragi} + +### `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 +``` + +::: + +## 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. + +- **Environment:** `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 [Environment] +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. + +- **Environment:** `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 [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. + +- **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/torii-endpoints.md b/src/reference/torii-endpoints.md index 0796c380a..81ba88d9e 100644 --- a/src/reference/torii-endpoints.md +++ b/src/reference/torii-endpoints.md @@ -2,15 +2,26 @@ ::: tip About Parity SCALE Codec -Messages for certain `TORII` operations are encoded with the Parity SCALE Codec (`SCALE`) commonly used with the [Parity Substrate](https://www.parity.io/technologies/substrate/) blockchain framework, and other blockchains utilizing it. +Messages for certain `TORII` operations are encoded with the Parity +SCALE +Codec (`SCALE`) commonly used with the +[Parity Substrate](https://www.parity.io/technologies/substrate/) +blockchain framework, and other blockchains utilizing it. -For more information on `SCALE`, see the [Substrate Documentation: Type encoding (SCALE)](https://docs.substrate.io/reference/scale-codec/) article and its [official GitHub repository](https://github.com/paritytech/parity-scale-codec). +For more information on `SCALE`, see the +[Substrate Documentation: Type encoding (SCALE)](https://docs.substrate.io/reference/scale-codec/) +article and its +[official GitHub repository](https://github.com/paritytech/parity-scale-codec). ::: -Torii (Japanese: 鳥居 — Shinto shrine gateway) is the Iroha 2 module in charge of handling `HTTP` and `WebSocket` requests. It is the main API for interacting with Iroha 2. Such interactions include sending transactions, making queries, listening for blocks stream, etc. +Torii (Japanese: 鳥居 — Shinto shrine gateway) is the Iroha 2 module in +charge of handling `HTTP` and `WebSocket` requests. It is the main +API for interacting +with Iroha 2. Such interactions include sending transactions, making +queries, listening for blocks stream, etc. @@ -44,7 +50,8 @@ To establish two-way communication with the `TORII` endpoints, the following add ::: info -This operation requires the specific Iroha node being requested to be compiled with the `telemetry` feature enabled. +This operation requires the specific Iroha node being requested to be +compiled with the `telemetry` feature enabled. @@ -61,9 +68,10 @@ A `GET` request to the endpoint. #### 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**: @@ -73,7 +81,10 @@ A `GET` request to the endpoint. ::: info -The API version is retrieved from and is the same as the version of the [genesis block](../guide/configure/genesis.md), which means that at least a minimal subnet of four peers must be running, and the genesis block must already be submitted at the time of the request. +The API version is retrieved from and is the same as the version of the +[genesis block](genesis.md), which means that at least a minimal subnet of +four peers must be running, and the genesis block must already be submitted +at the time of the request. ::: @@ -85,11 +96,20 @@ The API version is retrieved from and is the same as the version of the [genesis #### Handshake -Since the `/block/stream` endpoint handles continuous two-way data exchange, a `WebSocket` handshake between the client and server must first be performed to initiate communication with this endpoint. +Since the `/block/stream` endpoint handles continuous two-way data +exchange, a `WebSocket` handshake between the client and server must first +be performed to initiate communication with this endpoint. #### Data Exchange -After establishing a `WebSocket` connection, the client must send a [`BlockSubscriptionRequest`](/reference/data-model-schema#blocksubscriptionrequest) request with the starting block number provided (i.e., the `height` value). Then, upon sending the confirmation and [`BlockMessage`](/reference/data-model-schema#blockmessage) messages, the server starts streaming all of the blocks, beginning with the block specified with `height` up to the most recent one, and then continues to stream new blocks as they are added to the blockchain. +After establishing a `WebSocket` connection, the client must send a +[`BlockSubscriptionRequest`](/reference/data-model-schema#blocksubscriptionrequest) +request with the starting block number provided (i.e., the `height` value). +Then, upon sending the confirmation and +[`BlockMessage`](/reference/data-model-schema#blockmessage) messages, the +server starts streaming all of the blocks, beginning with the block +specified with `height` up to the most recent one, and then continues to +stream new blocks as they are added to the blockchain. ## Configuration / Retrieve @@ -102,6 +122,12 @@ After establishing a `WebSocket` connection, the client must send a [`BlockSubsc A `GET` request to the endpoint. +Via this endpoint, the client first provides the starting block number +(i.e. height) in the subscription request. After sending the confirmation +message, the server starts streaming all the blocks from the given block +number up to the current block and continues to stream blocks as they are +added to the blockchain. + #### Responses | Code | Response | Description | @@ -120,7 +146,9 @@ A `GET` request to the endpoint. ::: info -The subset of configuration parameters returned by this operation is equal to the one accepted by the [Configuration / Update](#configuration-update) operation, i.e., it only contains the `logger.level` parameter as of now. +The subset of configuration parameters returned by this operation is equal +to the one accepted by the [Configuration / Update](#configuration-update) +operation, i.e., it only contains the [`logger.level`](./peer-config/params#param-logger-level) parameter as of now. ::: @@ -133,18 +161,9 @@ The subset of configuration parameters returned by this operation is equal to th #### Requests -This endpoint expects a subset of configuration parameters serialized into JSON format. Currently, it only supports dynamic updating of the `logger.level` parameter. - -::: info - -The list of all accepted values is currently unavailable and will be a part of the configuration reference that is still WIP. - -Until then, to get assistance with the acceptable values and their definitions, consult [Receive Support](/help/) for ways to contact us. - -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). - -::: +This endpoint expects a subset of configuration parameters serialized into +JSON format. Currently, it only supports dynamic updating of the +[`logger.level`](./peer-config/params#param-logger-level). **Example**: @@ -164,7 +183,10 @@ The progress on the configuration reference can be tracked in the following GitH ::: tip Guarantees -A successful configuration update does not guarantee that the configuration is indeed updated. While a follow-up [Configuration / Retrieve](#configuration-retrieve) request will return updated values, the actual update is performed asynchronously. +A successful configuration update does not guarantee that the configuration +is indeed updated. While a follow-up +[Configuration / Retrieve](#configuration-retrieve) request will return +updated values, the actual update is performed asynchronously. ::: @@ -178,21 +200,35 @@ A successful configuration update does not guarantee that the configuration is i The status of a transaction event can be one of the following: -- `Validating` — The transaction has been successfully submitted and is currently being validated by peers. -- `Committed` — The transaction has been successfully validated and is committed to the blockchain. -- `Rejected` — The transaction has been rejected by at least one peer and is __not__ committed to the blockchain. - -All transactions are designated with the `Validating` status upon creation, which later proceeds to either `Committed` or `Rejected`. However, due to the distributed nature of the network, some peers might receive events out of order (e.g., `Committed` before `Validating`). - -Some peers in the network may be offline for the validation round. If a client connects to them while they are offline, the peers might not respond with the `Validating` status. But when the offline peers come back online they will automatically synchronize the blocks. These peers are then guaranteed to respond with either `Committed` or `Rejected` status, depending on the information found in the block. - -#### Handshake - -Since the `/events` endpoint handles continuous two-way data exchange, a `WebSocket` handshake between the client and server must first be performed to initiate communication with this endpoint. +- `Validating` — The transaction has been successfully submitted and is + currently being validated by peers. +- `Committed` — The transaction has been successfully validated and is + committed to the blockchain. +- `Rejected`— The transaction has been rejected by at least one peer and is + **not** committed to the blockchain. + +All transactions are designated with the `Validating` status upon creation, +which later proceeds to either `Committed` or `Rejected`. However, due to +the distributed nature of the network, some peers might receive events out +of order (e.g., `Committed` before `Validating`). + +Some peers in the network may be offline for the validation round. If a +client connects to them while they are offline, the peers might not respond +with the `Validating` status. But when the offline peers come back online +they will automatically synchronize the blocks. These peers are then +guaranteed to respond with either `Committed` or `Rejected` status, +depending on the information found in the block.#### Handshake + +Since the `/events` endpoint handles continuous two-way data exchange, a +`WebSocket` handshake between the client and server must first be performed +to initiate communication with this endpoint. #### Data Exchange -After establishing a `WebSocket` connection, the client must send an [`EventSubscriptionRequest`](/reference/data-model-schema#eventsubscriptionrequest) request, after which the server sends an [`EventMessage`](/reference/data-model-schema#eventmessage) response. +After establishing a `WebSocket` connection, the client must send an +[`EventSubscriptionRequest`](/reference/data-model-schema#eventsubscriptionrequest) +request, after which the server sends an +[`EventMessage`](/reference/data-model-schema#eventmessage) response. ## Health @@ -221,7 +257,8 @@ A `GET` request to the endpoint. ::: info -This operation requires the Iroha 2 network to be established with the `telemetry` feature enabled. +This operation requires the Iroha 2 network to be established with the +`telemetry` feature enabled. @@ -323,41 +360,50 @@ This endpoint expects requests with two shapes: Start a query: -- **Body**: [`SignedQuery`](/reference/data-model-schema#signedquery) - +- **Body**: + [`SignedQuery`](/reference/data-model-schema#signedquery) OR - -Get the next batch of a previously started query: - -- **Parameters**: + Get the next batch of a previously started query: + + - **Parameters**: - `cursor` - specifies a cursor previously returned as part of query response - -Request + Request #### Responses -| Code | Response | Body | Description | -|:----:|---------------------------------|----------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------| -| 200 | Success | [`BatchedResponse`](/reference/data-model-schema#batchedresponse-queryoutputbox) | Successful query request | -| 400 | Conversion Error | [`QueryExecutionFail::Conversion(String)`](/reference/data-model-schema#queryexecutionfail) | Invalid asset query for the actual asset type | -| 400 | Cursor Error | [`QueryExecutionFail::UnknownCursor`](/reference/data-model-schema#queryexecutionfail) | An invalid cursor was provided in the batch request | -| 400 | FetchSizeTooBig Error | [`QueryExecutionFail::FetchSizeTooBig`](/reference/data-model-schema#queryexecutionfail) | Fetch size specified in the query request is too large | +| Code | Response | Body | Description | +|:----:|---------------------------------|--------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------| +| 200 | Success | [`QueryOutputBox`](/reference/data-model-schema#queryoutput) | Successful query request | +| 400 | Conversion Error | [`QueryExecutionFail::Conversion(String)`](/reference/data-model-schema#queryexecutionfail) | Invalid asset query for the actual asset type | +| 400 | Cursor Error | [`QueryExecutionFail::UnknownCursor`](/reference/data-model-schema#queryexecutionfail) | An invalid cursor was provided in the batch request | +| 400 | FetchSizeTooBig Error | [`QueryExecutionFail::FetchSizeTooBig`](/reference/data-model-schema#queryexecutionfail) | Fetch size specified in the query request is too large | | 400 | InvalidSingularParameters Error | [`QueryExecutionFail::InvalidSingularParameters`](/reference/data-model-schema#queryexecutionfail) | Specified query parameters are not applicable to the (singular) query type | -| 401 | Signature Error | [`QueryExecutionFail::Signature(String)`](/reference/data-model-schema#queryexecutionfail) | The signature on the query is incorrect | -| 403 | Permission Error | [`QueryExecutionFail::Permission(String)`](/reference/data-model-schema#queryexecutionfail) | The user does not have permission to execute this query | -| 404 | Find Error | [`QueryExecutionFail::Find(FindError)`](/reference/data-model-schema#queryexecutionfail) | The queried object was not found | +| 401 | Signature Error | [`QueryExecutionFail::Signature(String)`](/reference/data-model-schema#queryexecutionfail) | The signature on the query is incorrect | +| 403 | Permission Error | [`QueryExecutionFail::Permission(String)`](/reference/data-model-schema#queryexecutionfail) | The user does not have permission to execute this query | +| 404 | Find Error | [`QueryExecutionFail::Find(FindError)`](/reference/data-model-schema#queryexecutionfail) | The queried object was not found | ::: info -The `200 Success` response returns results that are ordered by `id`, which use -Rust's [PartialOrd](https://doc.rust-lang.org/std/cmp/trait.PartialOrd.html) -and [Ord](https://doc.rust-lang.org/std/cmp/trait.Ord.html) traits. +The `200 Success` response returns results that are ordered by `id`, which +use +Rust's +[PartialOrd](https://doc.rust-lang.org/std/cmp/trait.PartialOrd.html) +and +[Ord](https://doc.rust-lang.org/std/cmp/trait.Ord.html) traits. + +::: + +::: tip Lazily Evaluated Pagination + +TODO: explain how it works. Explain that this behaviour is configured with +[`torii.query_idle_time_ms`](/reference/peer-config/params#param-torii-query-idle-time-ms). ::: ### Account Not Found 404 -Whether each prerequisite object was found and [`FindError`](/reference/data-model-schema#finderror): +Whether each prerequisite object was found and +[`FindError`](/reference/data-model-schema#finderror): | Domain | Account | [`FindError`](/reference/data-model-schema#finderror) | | :----: | :-----: | ------------------------------------------------------------------------- | @@ -366,7 +412,8 @@ Whether each prerequisite object was found and [`FindError`](/reference/data-mod ### Asset Not Found 404 -Whether each prerequisite object was found and [`FindError`](/reference/data-model-schema#finderror): +Whether each prerequisite object was found and +[`FindError`](/reference/data-model-schema#finderror): | Domain | Account | Asset Definition | Asset | [`FindError`](/reference/data-model-schema#finderror) | | :----: | :-----: | :--------------: | :---: | ----------------------------------------------------------------------------------------- | @@ -379,7 +426,8 @@ Whether each prerequisite object was found and [`FindError`](/reference/data-mod ::: info -This operation requires the Iroha 2 network to be established with the `schema` feature enabled. +This operation requires the Iroha 2 network to be established with the +`schema` feature enabled. @@ -404,7 +452,8 @@ A `GET` request to the endpoint. ::: info -This operation requires the Iroha 2 network to be established with the `telemetry` feature enabled. +This operation requires the Iroha 2 network to be established with the +`telemetry` feature enabled. @@ -421,42 +470,58 @@ A `GET` request to the endpoint. This endpoint also accepts the following: - - **Header**: Specifies the encoding of the retrieved data.\ +- **Header**: Specifies the encoding of the retrieved data.\ Can be set to one of the following: - - `Accept: application/x-parity-scale` — the retrieved data is encoded with `SCALE`. - - `Accept: application/json` — the retrieved data is encoded with `JSON`. + - `Accept: application/x-parity-scale` — the retrieved data is encoded + with `SCALE`. + - `Accept: application/json` — the retrieved data is encoded with `JSON`. -If no header is specified in the request, the `Accept: application/json` header is used by default. +If no header is specified in the request, the `Accept: application/json` +header is used by default. #### Responses -| Code | Response | Description | -| :--: | --------------------- | ------------------------------------------------------------------------------------------ | -| 200 | Iroha Status | Returns the Iroha network status report encoded as specified in the header of the request. | +| Code | Response | Description | +| :--: | ------------ | ------------------------------------------------------------------------------------------ | +| 200 | Iroha Status | Returns the Iroha network status report encoded as specified in the header of the request. | 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: -struct Uptime { - secs: u64, - nanos: u32 +::: details Sample response + +```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, } ``` @@ -489,21 +554,29 @@ The following examples represent the same data: ::: warning JSON Precision Lost -Almost all fields in the `Status` structure are 64-bit integers, and they are encoded in JSON as-is. Since native JSON's number type according to the specification effectively is `f64`, the precision might be lost on deserialization, for example, in [JavaScript's `JSON.parse`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse). +Almost all fields in the `Status` structure are 64-bit integers, and they +are encoded in JSON as-is. Since native JSON's number type according to the +specification effectively is `f64`, the precision might be lost on +deserialization, for example, in +[JavaScript's `JSON.parse`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse). -For more details, see the related [GitHub issue](https://github.com/hyperledger-iroha/iroha/issues/3964). +For more details, see the related +[GitHub issue](https://github.com/hyperledger-iroha/iroha/issues/3964). ::: ::: tip Compact Form in SCALE -Fields with `u64` type are serialized in the [Compact form](https://docs.substrate.io/reference/scale-codec/#fn-1). +Fields with `u64` type are serialized in the +[Compact form](https://docs.substrate.io/reference/scale-codec/#fn-1). ::: ### Sub-routing -It is also possible to retrieve the data of a specific `struct` group or variable within it by adding their path to the endpoint address. The sub-routed values are only returned in the JSON format. +It is also possible to retrieve the data of a specific `struct` group or +variable within it by adding their path to the endpoint address. The +sub-routed values are only returned in the JSON format. **Examples**: @@ -552,7 +625,8 @@ It is also possible to retrieve the data of a specific `struct` group or variabl This endpoint expects the following data: - - **Body**: [`SignedTransaction`](/reference/data-model-schema#signedtransaction) +- **Body**: + [`SignedTransaction`](/reference/data-model-schema#signedtransaction) #### Responses