diff --git a/.vitepress/config.mts b/.vitepress/config.mts index bf3df96df..38d2f7a95 100644 --- a/.vitepress/config.mts +++ b/.vitepress/config.mts @@ -103,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', @@ -337,7 +325,8 @@ function sidebarReference(): DefaultTheme.SidebarItem[] { link: '/reference/permissions.md', }, { - text: 'CLI', + text: 'irohad CLI', + link: '/reference/irohad-cli.md', }, { text: 'Torii HTTP API', @@ -347,23 +336,18 @@ function sidebarReference(): DefaultTheme.SidebarItem[] { text: 'Foreign Function Interfaces', link: '/reference/ffi', }, - ], - }, - { - text: 'Configuration', - items: [ - { text: 'Overview' }, { text: 'Peer Configuration', - link: '/reference/config/index.md', + link: '/reference/peer-config/index.md', items: [ - { text: 'Parameters', link: '/reference/config/params.md' }, - // Consider removal - { text: 'Migration from pre-rc.20', link: '/reference/config/migration.md' }, + { text: 'Parameters', link: '/reference/peer-config/params.md' }, + { text: 'Migration from pre-rc.20', link: '/reference/peer-config/migration.md' }, ], }, - { text: 'Genesis Block' }, - { text: 'On-Chain Configuration' }, + { + text: 'Genesis Block', + link: '/reference/genesis.md', + }, ], }, ] 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/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 240f236e9..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 ::: @@ -62,7 +62,7 @@ two addresses: `TORII_API_URL` and `TORII_TELEMETRY_URL`. ### `TORII_API_URL` First, the `TORII_API_URL` is the same as -[`torii.address` in the peer configuration](/reference/config/params#param-torii-address). This is the module +[`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: diff --git a/src/guide/configure/genesis.md b/src/guide/configure/genesis.md index 6fe710628..04031c677 100644 --- a/src/guide/configure/genesis.md +++ b/src/guide/configure/genesis.md @@ -10,7 +10,7 @@ empty, even if `configs/peer/genesis.json` is. Here's an example: ::: The **genesis account** is specified in the -[`genesis` section of the peer configuration](/reference/config/params#genesis) file. +[`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 diff --git a/src/guide/configure/peer-configuration.md b/src/guide/configure/peer-configuration.md deleted file mode 100644 index 6b4e59bb0..000000000 --- a/src/guide/configure/peer-configuration.md +++ /dev/null @@ -1,195 +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`) - - - -## 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/cli.md b/src/reference/cli.md deleted file mode 100644 index 07ea20119..000000000 --- a/src/reference/cli.md +++ /dev/null @@ -1,78 +0,0 @@ -# Command Line Interface (CLI) - -TODO - -## `--config` {#arg-config} - -- **Type:** File Path -- **Required** -- **Alias:** `-c` - -Path to the [configuration](/reference/config/) file. - -```shell -iroha --config path/to/iroha.toml -``` - -::: tip - -Paths parameters in the config file are resolved relative to its own -location. See how -[paths resolution](/reference/config/glossary#paths-resolution) works. - -::: - -## `--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 colors: - -```shell -iroha --terminal-colors=false - -# or via env - -set TERMINAL_COLORS=false -iroha -``` - -## `--submit-genesis` - -**TO BE REMOVED** - -- **Type:** Flag, either set or omitted - -Whether the current peer should submit the genesis block or not. - -Only one peer in the network should submit the genesis block. - -This argument must be set alongside with -[`genesis.file`](/reference/config/params#param-genesis-file) and -[`genesis.public_key`](/reference/config/params#param-genesis-public-key) -configuration parameters. If not, Iroha will exit with an error. - -In case when the network consists only of this one peer, i.e. the amount of -trusted peers in the configuration -([`sumeragi.trusted_peers`](/reference/config/params#param-sumeragi-trusted-peers)) -is less than 2, this peer must submit the genesis, since there are no other -peers who can provide it. In this case, Iroha will exit with an error if -`--submit-genesis` is not set. - -**Examples:** - -```shell -# the peer that doesn't submit the genesis block -iroha - -# the peer submits the genesis -iroha --submit-genesis -``` diff --git a/src/reference/config/index.md b/src/reference/config/index.md deleted file mode 100644 index e38405166..000000000 --- a/src/reference/config/index.md +++ /dev/null @@ -1,8 +0,0 @@ -# Configuring Iroha - -- Use `--config` CLI or relevant ENV parameter (?) -- Use `--trace-config` to debug -- Config consists of parameters set via TOML file (some via ENV too) -- There is also chain-wide config, which is different -- Here is the template file -- Here is how to use `extends` diff --git a/src/reference/genesis.md b/src/reference/genesis.md index d81dbd935..317110ab3 100644 --- a/src/reference/genesis.md +++ b/src/reference/genesis.md @@ -1,3 +1,3 @@ # Genesis Block -TODO: describe its structure, purpose, mechanism. \ No newline at end of file +TODO: describe its structure, purpose, mechanism, encoding with Kagami \ 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/isi-on-chain.md b/src/reference/isi-on-chain.md deleted file mode 100644 index c0ea6a74b..000000000 --- a/src/reference/isi-on-chain.md +++ /dev/null @@ -1,76 +0,0 @@ -# On-Chain Configuration - -Supplied using `Configure` ISI with all optional fields, known beforehand. All parameters have default values. Defaults -are explicitly submitted in the genesis block if not set by a user. - -This page contains description of each field configurable. - -## `block_time` - -- **Type:** Number, milliseconds -- **Default:** 2 seconds - -Time since the round start[^1] by which a new block should be created regardless if there were enough transactions or -not. Used to force block commits when there is a small influx of new transactions. - -A block might be created earlier if there is enough transactions in the [Queue](config/params#queue). The limit of transactions -is configured by [`transactions_in_block`](#transactions-in-block). - -**Example:** - -```json -{ - "block_time": 2000 -} -``` - -## `commit_time` - -- **Type:** Number, milliseconds -- **Default:** 4 seconds - -Time by which a newly created block should be committed. Prevents malicious nodes from stalling the network by not -participating in consensus. - -The block creation is configured with [`block_time`](#block-time) and [`transactions_in_block`](#transactions-in-block). - -**Example:** - -```toml -commit_time = "4s" -``` - -## `transactions_in_block` - -- **Type:** u32 -- **Default:** $2^9 = 512$ - -The upper limit of the number of transactions per block. If there is enough transactions in the [Queue](config/params#queue), -the block is created immediately. Otherwise, the block is created when [`block_time`](#block-time) is elapsed since the -round start[^1]. - -**Example:** - -```toml -transactions_in_block = 512 -``` - -## `wsv_transaction_limits` - -## `wsv_identifier_length_limits` - -## `wsv_domain_metadata_limits` - -## `wsv_account_metadata_limits` - -## `wsv_asset_definition_metadata_limits` - -## `wsv_asset_metadata_limits` - -## `wasm_fuel_limit` - -## `wasm_memory_limit` - -[^1]: - The round start happens on peers rotation, when the leader is elected. Generally it happens after the previous block - is committed. See [Consensus](/blockchain/consensus) (todo: that page doesn't mention "round start" term ). diff --git a/src/reference/config/MigrationSnapshotModeTable.vue b/src/reference/peer-config/MigrationSnapshotModeTable.vue similarity index 70% rename from src/reference/config/MigrationSnapshotModeTable.vue rename to src/reference/peer-config/MigrationSnapshotModeTable.vue index c45da22c2..29fca072f 100644 --- a/src/reference/config/MigrationSnapshotModeTable.vue +++ b/src/reference/peer-config/MigrationSnapshotModeTable.vue @@ -1,8 +1,10 @@