From c6cdb5ff427fbf75967c317f13024309f5c9d72a Mon Sep 17 00:00:00 2001 From: a_zorina <64249490+a-zorina@users.noreply.github.com> Date: Wed, 17 Jul 2024 19:44:28 +0200 Subject: [PATCH 01/13] Getting started update and overhaul Signed-off-by: a_zorina <64249490+a-zorina@users.noreply.github.com> Signed-off-by: a-zorina <64249490+a-zorina@users.noreply.github.com> --- .vitepress/config.mts | 39 +- README.md | 4 +- .../advanced/running-iroha-on-bare-metal.md | 5 +- src/guide/blockchain/assets.md | 2 +- src/guide/blockchain/data-model.md | 2 +- src/guide/blockchain/how-iroha-works.md | 2 +- src/guide/blockchain/instructions.md | 8 +- src/guide/get-started/bash.md | 608 ------------------ src/guide/get-started/build.md | 70 -- src/guide/get-started/index.md | 74 ++- src/guide/get-started/install-iroha.md | 100 +++ src/guide/get-started/install.md | 88 --- .../launch-iroha.docker-compose-output.ansi | 39 ++ .../{quick-start.md => launch-iroha.md} | 23 +- .../get-started/operate-iroha-via-cli.md | 391 +++++++++++ .../quick-start.docker-compose-output.ansi | 32 - src/guide/get-started/rust.md | 2 +- src/guide/get-started/tutorials.md | 3 +- src/guide/introduction.md | 34 - .../security/generating-cryptographic-keys.md | 2 +- src/index.md | 8 +- 21 files changed, 624 insertions(+), 912 deletions(-) delete mode 100644 src/guide/get-started/bash.md delete mode 100644 src/guide/get-started/build.md create mode 100644 src/guide/get-started/install-iroha.md delete mode 100644 src/guide/get-started/install.md create mode 100644 src/guide/get-started/launch-iroha.docker-compose-output.ansi rename src/guide/get-started/{quick-start.md => launch-iroha.md} (54%) create mode 100644 src/guide/get-started/operate-iroha-via-cli.md delete mode 100644 src/guide/get-started/quick-start.docker-compose-output.ansi delete mode 100644 src/guide/introduction.md diff --git a/.vitepress/config.mts b/.vitepress/config.mts index 9a75ac08c..e2d1ba9b8 100644 --- a/.vitepress/config.mts +++ b/.vitepress/config.mts @@ -14,12 +14,12 @@ function nav(): DefaultTheme.NavItem[] { text: 'Guide', items: [ // { text: 'Get Started', link: '/guide/get-started/index' }, - // { text: 'Build and Install', link: '/guide/get-started/install' }, + // { text: 'Build and Install', link: '/guide/get-started/install-iroha' }, // { text: 'Tutorials', link: '/guide/get-started/tutorials'}, { text: 'Get Started', items: [ - { text: 'Build and Install', link: '/guide/get-started/install' }, + { text: 'Install and Build', link: '/guide/get-started/install-iroha' }, { text: 'SDK Tutorials', link: '/guide/get-started/tutorials' }, ], }, @@ -93,32 +93,23 @@ function sidebarGuide(): DefaultTheme.SidebarItem[] { return [ { text: 'Get Started', + link: '/guide/get-started/', items: [ { - text: 'About Iroha', - link: '/guide/introduction', + text: 'Install Iroha', + link: '/guide/get-started/install-iroha', }, { - text: 'Iroha 2 vs. Iroha 1', - link: '/guide/iroha-2', + text: 'Launch Iroha', + link: '/guide/get-started/launch-iroha', }, { - text: 'Build and Install', - collapsed: true, - items: [ - { - text: 'Install Iroha', - link: '/guide/get-started/install', - }, - { - text: 'Build Iroha Client', - link: '/guide/get-started/build', - }, - { - text: 'Quick Start with Docker', - link: '/guide/get-started/quick-start', - }, - ], + text: 'Operate Iroha via CLI', + link: '/guide/get-started/operate-iroha-via-cli', + }, + { + text: 'Iroha 2 vs. Iroha 1', + link: '/guide/iroha-2', }, { text: 'Receive support', @@ -174,10 +165,6 @@ function sidebarGuide(): DefaultTheme.SidebarItem[] { { text: 'Language-specific Guides', items: [ - { - text: 'Bash', - link: '/guide/get-started/bash', - }, { text: 'Python 3', link: '/guide/get-started/python', diff --git a/README.md b/README.md index 02e3b76e3..97fc00589 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,10 @@ # Hyperledger Iroha 2 Tutorial -This repository contains the source files for [Hyperledger Iroha 2 Tutorial](https://hyperledger.github.io/iroha-2-docs/). +This repository contains the source files for [Hyperledger Iroha 2 Documentation](https://hyperledger.github.io/iroha-2-docs/). The tutorial is suitable for both experienced and novice users. It explains Iroha 2 concepts and features, and also offers language-specific step-by-step guides for these programming languages: -- [Bash](https://hyperledger.github.io/iroha-2-docs/guide/bash.html) +- [CLI](https://hyperledger.github.io/iroha-2-docs/guide/operate-iroha-via-cli.html) - [Python](https://hyperledger.github.io/iroha-2-docs/guide/python.html) - [Rust](https://hyperledger.github.io/iroha-2-docs/guide/rust.html) - [Kotlin/Java](https://hyperledger.github.io/iroha-2-docs/guide/kotlin-java.html) diff --git a/src/guide/advanced/running-iroha-on-bare-metal.md b/src/guide/advanced/running-iroha-on-bare-metal.md index 442d270e9..2c127134e 100644 --- a/src/guide/advanced/running-iroha-on-bare-metal.md +++ b/src/guide/advanced/running-iroha-on-bare-metal.md @@ -353,9 +353,8 @@ ports need to be adjusted so there are no collisions. See the ## Deploy a minimal BFT network -Both of the following approaches could be messy and error-prone, which is why the [Quick Start](../get-started/quick-start.md) tutorial suggests using the `docker compose` command. -However, this brings you closer to the -experience of actually maintaining a functional Iroha peer. +Both of the following approaches could be messy and error-prone, which is why the [Launch Iroha](../get-started/launch-iroha.md) tutorial suggests using the `docker compose` command. +However, this brings you closer to the experience of actually maintaining a functional Iroha peer. ### Using Environment Variables diff --git a/src/guide/blockchain/assets.md b/src/guide/blockchain/assets.md index b607b1d72..73096db66 100644 --- a/src/guide/blockchain/assets.md +++ b/src/guide/blockchain/assets.md @@ -76,7 +76,7 @@ Assets can be [registered](./instructions.md#un-register), Refer to one of the language-specific guides to walk you through the process of registering and minting assets in a blockchain: -- [Bash](/guide/get-started/bash.md#_5-registering-and-minting-assets) +- [CLI](/guide/get-started/operate-iroha-via-cli.md#_6-registering-and-minting-assets) - [Rust](/guide/get-started/rust.md#_5-registering-and-minting-assets) - [Kotlin/Java](/guide/get-started/kotlin-java.md#_5-registering-and-minting-assets) - [Python](/guide/get-started/python.md#_5-registering-and-minting-assets) diff --git a/src/guide/blockchain/data-model.md b/src/guide/blockchain/data-model.md index f7b63b393..fb5498077 100644 --- a/src/guide/blockchain/data-model.md +++ b/src/guide/blockchain/data-model.md @@ -87,7 +87,7 @@ domain_looking_glass *-- account_rabbit : registered in | Language | Guide | | --------------------- |--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Bash | Register a [domain](/guide/get-started/bash.md#_3-registering-a-domain), an [account](/guide/get-started/bash.md#_4-registering-an-account), an [asset](/guide/get-started/bash.md#_5-registering-and-minting-assets) | +| CLI | Register a [domain](/guide/get-started/operate-iroha-via-cli.md#_3-registering-a-domain), an [account](/guide/get-started/operate-iroha-via-cli.md#_4-registering-an-account), an [asset](/guide/get-started/operate-iroha-via-cli.md#_6-registering-and-minting-assets) | | Rust | Register a [domain](/guide/get-started/rust.md#_3-registering-a-domain), an [account](/guide/get-started/rust.md#_4-registering-an-account), an [asset](/guide/get-started/rust.md#_5-registering-and-minting-assets) | | Kotlin/Java | Register a [domain](/guide/get-started/kotlin-java.md#_3-querying-and-registering-domains), an [account](/guide/get-started/kotlin-java.md#_4-registering-an-account), an [asset](/guide/get-started/kotlin-java.md#_5-registering-and-minting-assets) | | Python | Register a [domain](/guide/get-started/python.md#_3-registering-a-domain), an [account](/guide/get-started/python.md#_4-registering-an-account), an [asset](/guide/get-started/python.md#_5-registering-and-minting-assets) | diff --git a/src/guide/blockchain/how-iroha-works.md b/src/guide/blockchain/how-iroha-works.md index 785b431cd..2564b7313 100644 --- a/src/guide/blockchain/how-iroha-works.md +++ b/src/guide/blockchain/how-iroha-works.md @@ -2,7 +2,7 @@ To understand how Iroha operates, let's draw parallels between a blockchain and a computer. If the blockchain is the computer, then in this metaphor of -ours the client binary (for example: [`iroha_client_cli`](/guide/get-started/bash.md)) +ours the client binary (for example: [`iroha_client_cli`](/guide/get-started/operate-iroha-via-cli.md)) is the keyboard, the blockchain is the hard drive, and the Iroha peer software is the processor. Like a processor, Iroha accepts portable instructions that modify what's written to the blockchain, allow certain diff --git a/src/guide/blockchain/instructions.md b/src/guide/blockchain/instructions.md index 89ca032e7..c3f64e3c7 100644 --- a/src/guide/blockchain/instructions.md +++ b/src/guide/blockchain/instructions.md @@ -109,7 +109,7 @@ process of registering objects in a blockchain: | Language | Guide | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| Bash | Register a [domain](/guide/get-started/bash.md#_3-registering-a-domain), an [account](/guide/get-started/bash.md#_4-registering-an-account), an [asset](/guide/get-started/bash.md#_5-registering-and-minting-assets) | +| CLI | Register a [domain](/guide/get-started/operate-iroha-via-cli.md#_3-registering-a-domain), an [account](/guide/get-started/operate-iroha-via-cli.md#_4-registering-an-account), an [asset](/guide/get-started/operate-iroha-via-cli.md#_6-registering-and-minting-assets) | | Rust | Register a [domain](/guide/get-started/rust.md#_3-registering-a-domain), an [account](/guide/get-started/rust.md#_4-registering-an-account), an [asset](/guide/get-started/rust.md#_5-registering-and-minting-assets) | | Kotlin/Java | Register a [domain](/guide/get-started/kotlin-java.md#_3-querying-and-registering-domains), an [account](/guide/get-started/kotlin-java.md#_4-registering-an-account), an [asset](/guide/get-started/kotlin-java.md#_5-registering-and-minting-assets) | | Python | Register a [domain](/guide/get-started/python.md#_3-registering-a-domain), an [account](/guide/get-started/python.md#_4-registering-an-account), an [asset](/guide/get-started/python.md#_5-registering-and-minting-assets) | @@ -130,7 +130,7 @@ are assumed to be non-negative as well, so you can never have $-1.0$ of Refer to one of the language-specific guides to walk you through the process of minting assets in a blockchain: -- [Bash](/guide/get-started/bash.md#_5-registering-and-minting-assets) +- [CLI](/guide/get-started/operate-iroha-via-cli.md#_6-registering-and-minting-assets) - [Rust](/guide/get-started/rust.md#_5-registering-and-minting-assets) - [Kotlin/Java](/guide/get-started/kotlin-java.md#_5-registering-and-minting-assets) - [Python](/guide/get-started/python.md#_5-registering-and-minting-assets) @@ -138,7 +138,7 @@ process of minting assets in a blockchain: Here are examples of burning assets: -- [Bash](/guide/get-started/bash.md#_7-burning-assets) +- [CLI](/guide/get-started/operate-iroha-via-cli.md#_8-burning-assets) - [Rust](/guide/get-started/rust.md#_7-burning-assets) ## Transfer @@ -149,7 +149,7 @@ can transfer assets between different accounts. To do this, an account have to be granted the [permission to transfer assets](/reference/permissions.md). Refer to an example on how to -transfer assets in [Bash](/guide/get-started/bash.md#_6-transferring-assets) or [Rust](/guide/get-started/rust.md#_6-transferring-assets). +transfer assets with [CLI](/guide/get-started/operate-iroha-via-cli.md#_7-transferring-assets) or [Rust](/guide/get-started/rust.md#_7-transferring-assets). diff --git a/src/guide/get-started/bash.md b/src/guide/get-started/bash.md deleted file mode 100644 index d9aa603b5..000000000 --- a/src/guide/get-started/bash.md +++ /dev/null @@ -1,608 +0,0 @@ -# Bash Guide - -## 0. A brief primer on CLI applications - -This is as good a place as any to discuss what `iroha_client_cli` is and -what you should expect it to be able to do. - -Most users think that everything that's run inside the terminal is a CLI -program. This is not the case. A **Command-line Interface** is a glorified -scripting language that you interact with using the shell. - -CLI programs are run multiple times and given different _arguments_: -`--flag1` `file2` `--help`, etc., depending on what you want to do. A -single session doesn't begin with you opening the program and end with you -closing it. When you've stopped interacting, the `iroha_client_cli` session -is finished. - -You also don't _configure_ a CLI program in the usual sense of the word. -Most people expect that it's possible to change some settings of a program -from inside that same program, but most CLI programs are configured -differently. - -First of all, if you want to make a certain `--flag` part of the way you -invoke `iroha_client_cli`, you should create a -[shell alias](https://www.educba.com/bash-alias/). Some programs, but not -`iroha_client_cli`, also use something called -[Environment variables](https://medium.com/chingu/an-introduction-to-environment-variables-and-how-to-use-them-f602f66d15fa). - -Finally, most programs store persistent information that is too big for -either a shell alias or an environment variable in a separate file. -`iroha_client_cli` does not yet follow the -[XDG_CONFIG_HOME specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html). -It only looks for a configuration file in one of two places: - -1. If the `-c` or `--config` command line flag is specified, the next - argument interpreted as a path. - - For example: `-c ~/Git/iroha/configs/peer/config.json`. If that file - doesn't exist, you will see an error, and `iroha_client_cli` won't look - for a configuration file anywhere else. - -2. If neither `-c` nor `--config` were given, it will look in the current - working directory. - -These defaults are not very ergonomic. They are artifacts of the way in -which Iroha is being deployed, and the fact that a CLI interface is used -exclusively for testing purposes. - -::: info - - - -This might change in the future, but likely not by fixing -`iroha_client_cli` but rather by replacing it entirely with Iroha Python. -The only thing stopping us from that today is that Iroha Python has not -gotten the attention it deserves. - -::: - -It is possible that a user might be expecting `iroha_client_cli` to behave -like a graphical program using terminal graphics: a **Terminal User -Interface**. While we'd like to provide you with such a program, we don't -think that it offers enough convenience over the amount of effort that we'd -need to put in. - -::: info - - - -It is possible that in the future, once `iroha_client_cli` is phased out -and `iroha_python` is the official scripting interface, we might use the -excellent Python libraries for creating a useful TUI. For now, one must -make do with what one has. - -::: - -## 1. Iroha 2 Client Setup - -Note, first, that we have already created the `iroha_client_cli` binary -executable, when we [ran the `build` command](./build.md#build-iroha-client). - -Create a fresh directory for the client: - -```bash -$ mkdir -p test_docker -``` - -Copy the configuration file to the client directory: - -```bash -$ cp ./configs/client/config.json test_docker/ -``` - -::: tip - -You could also use a file manager (e.g. finder) to do that. We prefer -providing command-line instructions, because they are easier to follow -step-by-step. - -::: - -To test Iroha 2 metadata capabilities, let's also create a dummy -`metadata.json` file: - -```bash -$ echo '{"comment":{"String": "Hello Meta!"}}' > test_docker/metadata.json -``` - -To get the CLI started, copy the `iroha_client_cli` binary into the client -directory: - -```bash -$ cp ./target/debug/iroha_client_cli test_docker/ -``` - -Make sure you [bring up the test network](./quick-start.md) as well. - -## 2. Configuring Iroha 2 - -Now let's look at how to properly configure Iroha 2, and especially its -**C**ommand-**L**ine **I**nterface client. - -Make sure that you have another terminal tab or window open with a running -version, using the instructions above. You can use this screen to monitor -the pipeline events as they are output. - -On a new terminal tab run: - -```bash -$ cd ~/Git/iroha/test_docker -``` - -If you followed the steps correctly, this should contain the -`iroha_client_cli` and `config.json`. - -::: tip - -Use `ls` to make sure both files are there, and if not, -[return to Step 1](#_1-iroha-2-client-setup). - -::: - -Run - -```bash -$ ./iroha_client_cli -``` - -::: details Expand to see the expected output - -``` -iroha_client_cli 0.1.0 -Soramitsu Iroha2 team (https, //github.com/orgs/soramitsu/teams/iroha2) -Iroha CLI Client provides an ability to interact with Iroha Peers Web API without direct network usage - -USAGE: - iroha_client_cli [OPTIONS] - -FLAGS: - -h, --help Prints help information - -V, --version Prints version information - -OPTIONS: - -c, --config Sets a config file path [default: config.json] - -SUBCOMMANDS: - account The subcommand related to accounts - asset The subcommand related to assets - blocks The subcommand related to block streaming - domain The subcommand related to domains - events The subcommand related to event streaming - help Prints this message or the help of the given subcommand(s) - json The subcommand related to multi-instructions as Json - peer The subcommand related to p2p networking - wasm The subcommand related to Wasm -``` - -::: - -To configure the Iroha client, run: - -```bash -$ ./iroha_client_cli --config ./test_docker/config.json -``` - -It should be noted that this is not _persistent configuration_: each time -you run `iroha_client_cli`, you must add the -`--config ./test_docker/config.json` command-line argument. - -::: tip - -Because the client checks the working directory for a file called -`config.json`, it's always much easier to just copy (or link) the file into -the working directory. Alternatively, you could also create a shell alias. - -::: - -Feel free to edit the file and see what each option does. The only thing -that you shouldn't edit at this point is the account. You see, `alice` has -to be pre-registered in the genesis block. Only she can interact with the -blockchain, and if you change the value of the user account, you should -also make sure that that user exists in the blockchain. - -To make sure that your configuration options worked, try to run a query, -e.g.: - -```bash -$ ./iroha_client_cli domain list all -``` - -If the output looks like some form of JSON (but not quite), then the -configuration was successful! - -## 3. Registering a Domain - -To get started, you must register a domain: - -```bash -$ ./iroha_client_cli domain register --id="looking_glass" -``` - -You will receive a confirmation of the domain creation. However, this -information will not be clearly visible within the message. To confirm that -the new domain _looking_glass_ has been created successfully, run: - -```bash -$ ./iroha_client_cli domain list all -``` - -The printout should contain the recently-created _looking_glass_ domain - -```rust -Domain { - name: "looking_glass", - accounts: {}, - asset_definitions: {}, - metadata: Metadata { - map: {}, - }, -}, -``` - -With a domain available, it is time to register an account. - -## 4. Registering an Account - -To register a new account, you need a cryptographic key pair, a set of a _public_ and _private_ keys that establish a secure communication channel between a peer and the network (to learn more about cryptographic keys, see [Public Key Cryptography](/guide/security/public-key-cryptography.md)). - -There is a number of different ways to generate a cryptographic key pair. For the convenience of our users, Iroha 2 is delivered with `kagami`, an in-built tool for generating keys. However, any user is free to generate their keys any way they like. - -To generate a new key pair with `kagami`, run the following command from your project's `root` directory: - -```bash -$ cargo build --bin kagami --release -$ ./target/release/kagami crypto -``` - -::: tip - -To customize the generated keys, you can specify a number of parameters. For instance, `kagami` can use of one of four available algorithms to generate cryptographic keys. - -To learn more about generating cryptographic keys with `kagami`, available algorithms, and other parameters, see [Generating Cryptographic Keys with Kagami](/guide/security/generating-cryptographic-keys.md#kagami) - -::: - -For the purposes of this tutorial, we will use the following key pair for `mad_hatter@looking_glass`: - -```bash -Public key (multihash): ed01204595da8957c5598d4de20fe5f3eb4c14820678e1a1957a535db1fd4b3d1607c5 -Private key: 14d382c5bd8c0bfbaefdef1133196b78839ed3c136e296e0d969b7a3fca2fb424595da8957c5598d4de20fe5f3eb4c14820678e1a1957a535db1fd4b3d1607c5 -Digest function: ed25519 -``` - -To register a new account called _mad_hatter_ within the _looking_glass_ -domain, run: - -```bash -$ ./iroha_client_cli account register \ - --id="mad_hatter@looking_glass" \ - --key="ed01204595da8957c5598d4de20fe5f3eb4c14820678e1a1957a535db1fd4b3d1607c5" -``` - -The `--id` argument in the above code snippet specifies the _account id_, -the unique name assigned to that account in the blockchain. This name -includes the _domain_, which is a group of things like asset definitions, -account ids, and other objects that we'll talk about later. The `--key` -argument specifies the public key, which is the one we generated above -using `kagami`. - -If the account registration is successful, you will receive a confirmation -message. Like before, it is necessary to query the accounts to verify that -_mad_hatter_ has been registered. - - -Now, let's switch to the newly created account, _mad_hatter_, and continue -experimenting with it. For this, we need to modify the `PUBLIC_KEY`, -`PRIVATE_KEY`, and `ACCOUNT_ID` in the `config.json` file with the ones -we registered earlier, which is located in the same directory as -`iroha_client_cli`. - -::: tip -Your updated config.json should look like this - - -```json -{ - "PUBLIC_KEY": "ed01204595da8957c5598d4de20fe5f3eb4c14820678e1a1957a535db1fd4b3d1607c5", - "PRIVATE_KEY": { - "digest_function": "ed25519", - "payload": "14d382c5bd8c0bfbaefdef1133196b78839ed3c136e296e0d969b7a3fca2fb424595da8957c5598d4de20fe5f3eb4c14820678e1a1957a535db1fd4b3d1607c5" - }, - "ACCOUNT_ID": "mad_hatter@looking_glass", - "BASIC_AUTH": { - "web_login": "mad_hatter", - "password": "ilovetea" - }, - "TORII_API_URL": "http://127.0.0.1:8080", - "TORII_TELEMETRY_URL": "http://127.0.0.1:8180", - "TRANSACTION_TIME_TO_LIVE_MS": 100000, - "TRANSACTION_STATUS_TIMEOUT_MS": 15000, - "TRANSACTION_LIMITS": { - "max_instruction_number": 4096, - "max_wasm_size_bytes": 4194304 - }, - "ADD_TRANSACTION_NONCE": false -} -``` - -::: - - -To see all the accounts on the network as _mad_hatter_, run: - -```bash -$ ./iroha_client_cli account list all -``` - -This will list the active accounts on the network, along with their assets. -It will look like this: - -::: details Expand to see the expected output - -```rust -Account { - id: Id { - name: "mad_hatter", - domain_name: Id { - name: "looking_glass", - }, - }, - assets: {}, - signatories: { - { digest: "ed25519", payload: "A753146E75B910AE5E2994DC8ADEA9E7D87E5D53024CFA310CE992F17106F92C", - }, - }, - permission_tokens: {}, - signature_check_condition: SignatureCheckCondition( - EvaluatesTo { - expression: ContainsAny( - ContainsAny { - collection: EvaluatesTo { - expression: ContextValue( - ContextValue { - value_name: "transaction_signatories", - }, - ), - _value_type: PhantomData, - }, - elements: EvaluatesTo { - expression: ContextValue( - ContextValue { - value_name: "account_signatories", - }, - ), - _value_type: PhantomData, - }, - }, - ), - _value_type: PhantomData, - }, - ), - metadata: Metadata { - map: {}, - }, - roles: {}, -} -``` - -::: - -Another way to create a user (and the user's keys) is as follows: - -1. Open a new tab and navigate to the `/iroha` directory, then run: - - ```bash - $ ./target/debug/iroha_crypto_cli - ``` - -2. Copy the public key and repeat the instructions to register a new - account. Every time you run this command, you will generate a new - key-pair. - -In this case, we will create an account for _white_rabbit_ within the -_looking_glass_ domain, so we will run: - -```bash -$ ./iroha_client_cli account register \ - --id="white_rabbit@looking_glass" \ - --key="ed0120a4c4dadd9f18b0f63d6a420151fe0748d785475dec63034a15fcf999ceda1e65" -``` - -And like before, the new active user will be listed on the network: - -::: details Expand to see the expected output - -```rust -Account { - id: Id { - name: "white_rabbit", - domain_name: Id { - name: "looking_glass", - }, - }, - assets: {}, - signatories: { - { digest: "ed25519", payload: "A4C4DADD9F18B0F63D6A420151FE0748D785475DEC63034A15FCF999CEDA1E65", - }, - }, - permission_tokens: {}, - signature_check_condition: SignatureCheckCondition( - EvaluatesTo { - expression: ContainsAny( - ContainsAny { - collection: EvaluatesTo { - expression: ContextValue( - ContextValue { - value_name: "transaction_signatories", - }, - ), - _value_type: PhantomData, - }, - elements: EvaluatesTo { - expression: ContextValue( - ContextValue { - value_name: "account_signatories", - }, - ), - _value_type: PhantomData, - }, - }, - ), - _value_type: PhantomData, - }, - ), - metadata: Metadata { - map: {}, - }, - roles: {}, -} -``` - -::: - -Now that the network and users are registered, it is possible to mint -assets. - -## 5. Registering and minting assets - -In order to mint assets, you need to register the -[asset](/guide/blockchain/assets.md) first. We are going to register the _tea_ -token within the _looking_glass_ network. To do that, run: - -```bash -$ ./iroha_client_cli asset register \ - --id="tea#looking_glass" \ - --value-type=Quantity -``` - -The _tea_ asset is now registered within the _looking_glass_ network. The -output within the CLI is the same as with other commands, you will be able -to see that there are new events in the pipeline. - -With the asset created, you can now mint tokens. Run: - -```bash -$ ./iroha_client_cli asset mint \ - --account="mad_hatter@looking_glass" \ - --asset="tea#looking_glass" \ - --quantity="100" -``` - -After minting one hundred _tea_, you will see more pipeline events in the -logger, and you can also query the assets that you have just minted: - -```bash -$ ./iroha_client_cli asset list all -``` - -After running this command, you will be able to see the tokens currently -available on the network: - -```rust -[ - Asset { - id: Id { - definition_id: DefinitionId { - name: "tea", - domain_name: "looking_glass", - }, - account_id: Id { - name: "mad_hatter", - domain_name: "looking_glass", - }, - }, - value: Quantity( - 100, - ), - }, - Asset { - id: Id { - definition_id: DefinitionId { - name: "rose", - domain_name: "wonderland", - }, - account_id: Id { - name: "alice", - domain_name: "wonderland", - }, - }, - value: Quantity( - 13, - ), - }, -] -``` - -::: info - -Iroha 2 currently doesn't validate the account names, so you could (in -theory) add invalid characters to the name, e.g. spaces. **We recommend -sticking to English alphanumeric characters and underscores**. - -::: - -## 6. Transferring assets - -After minting the assets, you can transfer some of Mad Hatter's tea to White Rabbit: - -```bash -$ ./iroha_client_cli asset transfer --from mad_hatter@looking_glass --to white_rabbit@looking_glass --asset-id tea#looking_glass --quantity 5 -``` - -## 7. Burning assets - -Burning assets is quite similar to minting them: - -```bash -$ ./iroha_client_cli asset burn \ - --account="mad_hatter@looking_glass" \ - --asset="tea#looking_glass" \ - --quantity="10" -``` - -## 8. Visualizing outputs - -Although you will get a constant data feed of the network within the -terminal running docker compose, you can also configure an output to listen -to events on the network. - -From a terminal tab/window run: - -```bash -$ ./iroha_client_cli events pipeline -``` - -This view will output all the events related to Iroha 2, such as -transactions, block validations, or data events (e.g. when the in-memory -representation of the blockchain gets committed to the hard disk). - -The output would look like this: - -```rust -Iroha Client CLI: build v0.0.1 [release] -User: alice@wonderland -{"PUBLIC_KEY":"ed01207233bfc89dcbd68c19fde6ce6158225298ec1131b6a130d1aeb454c1ab5183c0","PRIVATE_KEY":{"digest_function":"ed25519","payload":"9ac47abf59b356e0bd7dcbbbb4dec080e302156a48ca907e47cb6aea1d32719e7233bfc89dcbd68c19fde6ce6158225298ec1131b6a130d1aeb454c1ab5183c0"},"ACCOUNT_ID":{"name":"alice","domain_name":"wonderland"},"TORII_API_URL":"http://127.0.0.1:8080","TORII_STATUS_URL":"127.0.0.1:8180","TRANSACTION_TIME_TO_LIVE_MS":100000,"TRANSACTION_STATUS_TIMEOUT_MS":10000,"MAX_INSTRUCTION_NUMBER":4096,"ADD_TRANSACTION_NONCE":false,"LOGGER_CONFIGURATION":{"MAX_LOG_LEVEL":"INFO","TELEMETRY_CAPACITY":1000,"COMPACT_MODE":false,"LOG_FILE_PATH":null}} -Listening to events with filter: Pipeline(EventFilter { entity: None, hash: None }) -Pipeline( - Event { - entity_type: Transaction, - status: Validating, - hash: 10fadf7b7fb8036d00bbd8cadc5358193b04ad6573537463acef2091ba4d0e77, - }, -) -Pipeline( - Event { - entity_type: Block, - status: Validating, - hash: 944269f27e1ed8882c6c8c74bd641bc3551ef5651320f4e1e1be11a470b4e3c3, - }, -) -Pipeline( - Event { - entity_type: Transaction, - status: Committed, - hash: 10fadf7b7fb8036d00bbd8cadc5358193b04ad6573537463acef2091ba4d0e77, - }, -) -``` diff --git a/src/guide/get-started/build.md b/src/guide/get-started/build.md deleted file mode 100644 index 4ff391926..000000000 --- a/src/guide/get-started/build.md +++ /dev/null @@ -1,70 +0,0 @@ -# Build Iroha 2 Client - -After you have [installed Iroha](./install.md) from GitHub, follow these -instructions to build the Iroha 2 client: - -1. [Install the Rust Toolchain](#install-the-rust-toolchain) -2. [Build Iroha 2 Client](#build-iroha-client) - -## Install the Rust Toolchain - -You need -[a working Rust toolchain](https://www.rust-lang.org/learn/guide/get-started): -`cargo`, `rustc` v1.60 and up. [^1] - -[^1]: - If you're having issues installing Rust compatible with our code - (2021 edition), please consult the - [troubleshooting](/guide/troubleshooting/installation-issues#troubleshooting-rust-toolchain) section. - -Installing the Rust Toolchain is normally a straightforward process, but -we've added -[troubleshooting](/guide/troubleshooting/installation-issues#troubleshooting-rust-toolchain) -details for each stage, in case you experience issues with the installation -process. - -The easiest way to get the official `rustup` script is to run: - -```bash -$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -``` - -Or, alternatively, you can install `rustup` via your operating system’s -package manager. - -::: tip - -If you know what you're doing, you can also install the Rust toolchain -directly, without `rustup`. - -::: - -If you chose to use the one-line `curl` script, you will be guided through -the setup process. Just go with the defaults. - -## Build Iroha Client - -1. Navigate to the directory containing the Iroha repository. If you - followed the installation instructions - [here](./install.md#install-iroha-from-github), run: - - ```bash - $ cd ~/Git/iroha - ``` - -2. Build the Iroha 2 client using: - - ```bash - $ cargo build -p iroha_client_cli --release - ``` - - Build artifacts are created in the `./target/debug/` directory. - - ::: info - - We take pride in the fact that Iroha is extremely quick to compile. For - reference, compiling hyperledger/substrate takes a good part of ten - minutes on a modern M1 machine. Iroha, in comparison, compiles in around - one minute. - - ::: diff --git a/src/guide/get-started/index.md b/src/guide/get-started/index.md index f7982fef5..a0c84e4f0 100644 --- a/src/guide/get-started/index.md +++ b/src/guide/get-started/index.md @@ -1,35 +1,61 @@ -# Get Started - -1. [Install Iroha 2](/guide/get-started/install.md). -2. [Build Iroha 2](/guide/get-started/build.md) -3. Follow one of the language-specific guides to learn how to set up and - configure Iroha 2, register a domain and an account, register and mind - assets, and visualize outputs: - - [Bash](/guide/get-started/bash.md) +# Iroha 2 + +Iroha is a fully-featured +[blockchain ledger](/reference/glossary.md#blockchain-ledgers). With Iroha you +can: + +- Create and manage custom + [fungible assets](/reference/glossary.md#fungible-assets), such as currencies, + gold, and others +- Create and manage [non-fungible](/reference/glossary.md#non-fungible-assets) + assets +- Manage user accounts with a domain hierarchy and multi-signature + transactions +- Use efficient portable smart contracts implemented either via + [WebAssembly](/guide/blockchain/wasm.md) or + [Iroha Special Instructions](/guide/blockchain/instructions.md) +- Use both permissioned and permission-less blockchain deployments + + + +## Get Started + +1. [Install Iroha 2](/guide/get-started/install-iroha.md). +2. [Launch Iroha 2](/guide/get-started/launch-iroha.md). +3. [Learn how to operate Iroha via CLI](/guide/get-started/operate-iroha-via-cli.md) client: set up and + configure Iroha 2, register a domain and an account, register and manage + assets, and visualize outputs. +4. Once familiar with how Iroha works, proceed to the language-specific tutorials to learn how to build software on Iroha: - [Python](/guide/get-started/python.md) - [Rust](/guide/get-started/rust.md) - [Kotlin/Java](/guide/get-started/kotlin-java.md) - [Javascript (TypeScript)](/guide/get-started/javascript.md) - +If you have previously worked with Iroha, start with our comparison of [Iroha 1 and Iroha 2](/guide/iroha-2.md). It will help you understand the differences between the two versions and upgrade to the newer one. -If you have previously worked with Iroha, start with our comparison of -[Iroha 1 and Iroha 2](/guide/iroha-2.md). That will help you understand the -differences between the two versions and upgrade to the newer one. +## Explore In-Depth -Before you dive into tutorials and deploy Iroha 2, we suggest you read through the [Security](/guide/security/index.md) section to learn about [core security principles](/guide/security/security-principles.md) and [operational security measures](/guide/security/operational-security.md) that are necessary to ensure the safety and validity of data and assets. This section also covers [cryptographic keys](/guide/security/public-key-cryptography.md), [how to generate them](/guide/security/generating-cryptographic-keys.md), and [how to store them securely](/guide/security/storing-cryptographic-keys.md). +Once you've learned the basics, we suggest you read through the following: + - [Security](/guide/security/index.md) section - learn about [core security principles](/guide/security/security-principles.md) and [operational security measures](/guide/security/operational-security.md) that are necessary to ensure the safety and validity of data and assets. This section also covers [cryptographic keys](/guide/security/public-key-cryptography.md), [how to generate them](/guide/security/generating-cryptographic-keys.md), and [how to store them securely](/guide/security/storing-cryptographic-keys.md). -Check the [tutorial](/guide/get-started/tutorials.md) where you -can follow one of the available language-specific guides in -[Bash](/guide/get-started/bash.md), [Rust](/guide/get-started/rust.md), -[Kotlin](/guide/get-started/kotlin-java.md), [Javascript](/guide/get-started/javascript.md), or -[Python](/guide/get-started/python.md). The guides introduce you to the basic concepts -and provide code snippets that you can run yourself. + - Blockchain chapter - find documentation for Iroha features, such as [Iroha Special Instructions](/guide/blockchain/instructions.md), [triggers](/guide/blockchain/triggers.md), [queries](/guide/blockchain/queries.md). -In the Blockchain chapter you can find documentation for Iroha features, -such as [Iroha Special Instructions](/guide/blockchain/instructions.md), -[triggers](/guide/blockchain/triggers.md), -[queries](/guide/blockchain/queries.md). + - Configuration and Management section - explore Iroha 2 configuration files in great detail, including topics such as [genesis blocks and accounts](/guide/configure/genesis.md), [client configuration](/guide/configure/client-configuration.md), and [public and private modes](/guide/configure/modes.md). -The Configuration and Management section explains Iroha 2 configuration files in great detail and covers topics such as [genesis blocks and accounts](/guide/configure/genesis.md), [client configuration](/guide/configure/client-configuration.md), and [public and private modes](/guide/configure/modes.md). +## Learn More + +For more information on Iroha 2, please take a look at the +[Iroha 2 Whitepaper](https://github.com/hyperledger/iroha/blob/iroha2/docs/source/iroha_2_whitepaper.md), +as well as the Hyperledger Iroha section within the +[Hyperledger Foundation Wiki](https://wiki.hyperledger.org/display/iroha). + +For more information on Iroha 1, take a look at the +[Iroha 1 documentation](https://iroha.readthedocs.io/en/develop/index.html). + +::: tip + +If you want to contribute to Hyperledger Iroha, please look at our +[Contributing Guide](https://github.com/hyperledger/iroha/blob/iroha2-dev/CONTRIBUTING.md). + +::: \ No newline at end of file diff --git a/src/guide/get-started/install-iroha.md b/src/guide/get-started/install-iroha.md new file mode 100644 index 000000000..04f0ab510 --- /dev/null +++ b/src/guide/get-started/install-iroha.md @@ -0,0 +1,100 @@ +# Install Iroha 2 + +## Install Prerequisites + +To install and build Iroha from GitHub, you need: + +- [git](https://githowto.com/) +- [OpenSSL](https://www.openssl.org/) +- [Rust Toolchain](https://www.rust-lang.org/tools/install) + +### Install OpenSSL + +Make sure you have OpenSSL installed. Note that in most Linux setups it is already available to you. + +- Install OpenSSL on Ubuntu: + + ```bash + $ sudo apt-get install libssl-dev + ``` + +- Install OpenSSL on macOS using [brew](https://brew.sh/): + + ```bash + $ brew install openssl + ``` + +Check the [OpenSSL installation guide](https://github.com/openssl/openssl/blob/master/INSTALL.md) for details. + + +### Install the Rust Toolchain + +You need [a working Rust toolchain]: `cargo`, `rustc` v1.60 and up. [^1] + +[^1]: + If you're having issues installing Rust compatible with our code + (2021 edition), please consult the + [troubleshooting](/guide/troubleshooting/installation-issues#troubleshooting-rust-toolchain) section. + + +The easiest way to get the official `rustup` script is to run: + +```bash +$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh +``` + +You will be guided through the setup process. Just go with the defaults. + +## Install Iroha from GitHub + + + + +1. If you haven’t already, you might want to create a clean folder for + Iroha 2, to keep things tidy. + + ```bash + $ mkdir -p ~/Git + ``` + + ::: tip + + On macOS, if you get + `fatal: could not create work tree dir 'iroha': Read-only file system`, + that’s because the home folder is not a real file system. The fix is to + create the `Git` folder. + + ::: + +2. Enter the directory you have just created using + + ```bash + $ cd ~/Git + ``` + +3. Then `clone` the Iroha git repository into the folder `~/Git/iroha` + + ```bash + $ git clone https://github.com/hyperledger/iroha.git + ``` + +### Build Iroha 2 Client + +1. Navigate to the directory containing the Iroha repository: + + ```bash + $ cd ~/Git/iroha + ``` + +2. Build the Iroha 2 client using: + + ```bash + $ cargo build --release + ``` + + Build artifacts are created in the `./target/release/` directory. + + +## What's Next + +- [Launch Iroha Network](./launch-iroha.md) diff --git a/src/guide/get-started/install.md b/src/guide/get-started/install.md deleted file mode 100644 index 4027eb6a7..000000000 --- a/src/guide/get-started/install.md +++ /dev/null @@ -1,88 +0,0 @@ -# Install Iroha 2 - -To install Iroha, follow these instructions: - -1. [Choose the Iroha 2 version to work with](#choose-version) -2. [Install prerequisites](#install-prerequisites) -3. [Install Iroha from GitHub](#install-iroha-from-github) - -## Choose Version - -You can choose to work with one of the following versions of Iroha: `dev`, -`lts`, or `stable`: - -| Version | Description | -| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `iroha2-dev` | This is the latest state of Iroha and it is **not meant to be used in production**. This is an intermediate, untested, potentially broken state, and therefore we cannot guarantee that it is usable or stable. | -| `iroha2-stable` | This is the latest released version of Iroha. Stable versions are tested and released once a month, in accordance with our release schedule. You can use the stable version in production, and we will offer you tech support. | -| `iroha2-lts` | This is the long-term supported version. We guarantee its compatibility with SDKs, toolsets, and block stores released when it came out. We **recommend using the LTS version in production** since it is the version that will not change much over time. Similarly to the stable version, we offer tech support for LTS. | - -## Install Prerequisites - -To install Iroha from GitHub, you need: - -- [git](https://githowto.com/) -- [OpenSSL](https://www.openssl.org/) - -### Install OpenSSL - -Make sure you have OpenSSL installed. Note that in most Linux setups it is -already available to you. - -- Install OpenSSL on Ubuntu: - - ```bash - $ sudo apt-get install libssl-dev - ``` - -- Install OpenSSL on macOS using [brew](https://brew.sh/): - - ```bash - $ brew install openssl - ``` - -Check the -[OpenSSL installation guide](https://github.com/openssl/openssl/blob/master/INSTALL.md) -for details. - -## Install Iroha from GitHub - -1. If you haven’t already, you might want to create a clean folder for - Iroha 2, to keep things tidy. - - ```bash - $ mkdir -p ~/Git - ``` - - ::: tip - - On macOS, if you get - `fatal: could not create work tree dir 'iroha': Read-only file system`, - that’s because the home folder is not a real file system. The fix is to - create the `Git` folder. - - ::: - -2. Enter the directory you have just created using - - ```bash - $ cd ~/Git - ``` - -3. Then `clone` the Iroha git repository into the folder `~/Git/iroha` and - `checkout` the branch you prefer to work on. You can use the - `iroha2-lts` branch, which is the long-term support release, or the - latest stable release branch (`iroha2-stable`). To clone the repository - and checkout the stable release, run: - - ```bash - $ git clone https://github.com/hyperledger/iroha.git --branch iroha2-stable - ``` - - This will fetch all of Iroha, including Iroha 1, and the `iroha2-dev` - branch, which we will touch upon later. - -## What's next - -- [Run Iroha in Docker](./quick-start.md) -- [Build Iroha 2 client](build.md) diff --git a/src/guide/get-started/launch-iroha.docker-compose-output.ansi b/src/guide/get-started/launch-iroha.docker-compose-output.ansi new file mode 100644 index 000000000..15694778d --- /dev/null +++ b/src/guide/get-started/launch-iroha.docker-compose-output.ansi @@ -0,0 +1,39 @@ +[+] Running 9/9 + ✔ irohad2 Pulled 6.3s + ✔ irohad0 Pulled 6.3s + ✔ irohad3 Pulled 6.3s + ✔ irohad1 Pulled 6.3s + ✔ ec99f8b99825 Already exists 0.0s + ✔ d3a0e7f5d646 Pull complete 1.4s + ✔ 1b1d5514cbbf Pull complete 2.1s + ✔ 86e58c28036c Pull complete 2.3s + ✔ 0d3b3367a826 Pull complete 2.5s +[+] Running 5/5 + ✔ Network swarm_default Created 0.1s + ✔ Container swarm-irohad3-1 Created 0.4s + ✔ Container swarm-irohad0-1 Created 0.5s + ✔ Container swarm-irohad1-1 Created 0.4s + ✔ Container swarm-irohad2-1 Created 0.5s +Attaching to irohad0-1, irohad1-1, irohad2-1, irohad3-1 +irohad0-1 | 2024-07-15T05:51:39.204411Z INFO irohad: Hyperledgerいろは2にようこそ！(translation) Welcome to Hyperledger Iroha! version="2.0.0-pre-rc.21" git_commit_sha="185ef76" peer=ed0120A98BAFB0663CE08D75EBD506FEC38A84E576A7C9B0897693ED4B04FD9EF2D18D@@0.0.0.0:1337 chain=00000000-0000-0000-0000-000000000000 listening_on=0.0.0.0:8080 +irohad0-1 | 2024-07-15T05:51:39.204729Z INFO init:start{listen_addr=WithOrigin { value: 0.0.0.0:1337, origin: Env { id: ParameterId(network.address), var: "P2P_ADDRESS" } } idle_timeout=60s}: iroha_p2p::network: Network bound to listener +irohad0-1 | 2024-07-15T05:51:39.209730Z INFO init:kura_init: iroha_core::kura: Kura init complete mode=Strict block_count=0 +irohad0-1 | 2024-07-15T05:51:39.210006Z INFO init: irohad: Didn't find a state snapshot; creating an empty state +irohad0-1 | 2024-07-15T05:51:39.214759Z INFO init: irohad: Telemetry not started due to absent configuration +irohad0-1 | 2024-07-15T05:51:39.215234Z INFO iroha_core::sumeragi: Sumeragi has finished loading blocks and setting up the state + +... + + irohad2-1  | 2024-07-15T05:51:39.332824Z  INFO consensus: iroha_core::sumeragi::main_loop: Listening for genesis... peer_id=ed01204EE2FCD53E1730AF142D1E23951198678295047F9314B4006B0CB61850B1DB10@@0.0.0.0:1339 role=Leader + irohad0-1  | 2024-07-15T05:51:40.478714Z  INFO consensus: iroha_core::sumeragi::main_loop: Block committed peer_id=ed0120A98BAFB0663CE08D75EBD506FEC38A84E576A7C9B0897693ED4B04FD9EF2D18D@@0.0.0.0:1337 prev_role=ProxyTail next_role=ValidatingPeer block_hash=a638001762e365280677a5407bac9adaa119c8cb82c8afe377b72f85e71ed4a9 new_height=1 + irohad0-1  | 2024-07-15T05:51:40.478761Z  INFO consensus: iroha_core::sumeragi::main_loop: Sumeragi initialized peer_id=ed0120A98BAFB0663CE08D75EBD506FEC38A84E576A7C9B0897693ED4B04FD9EF2D18D@@0.0.0.0:1337 role=ValidatingPeer + irohad2-1  | 2024-07-15T05:51:42.085522Z  INFO consensus: iroha_core::sumeragi::main_loop: Block committed peer_id=ed01204EE2FCD53E1730AF142D1E23951198678295047F9314B4006B0CB61850B1DB10@@0.0.0.0:1339 prev_role=Leader next_role=ProxyTail block_hash=a638001762e365280677a5407bac9adaa119c8cb82c8afe377b72f85e71ed4a9 new_height=1 + irohad2-1  | 2024-07-15T05:51:42.085585Z  INFO consensus: iroha_core::sumeragi::main_loop: Sumeragi initialized peer_id=ed01204EE2FCD53E1730AF142D1E23951198678295047F9314B4006B0CB61850B1DB10@@0.0.0.0:1339 role=ProxyTail + irohad1-1  | 2024-07-15T05:51:42.109788Z  INFO consensus: iroha_core::sumeragi::main_loop: Block committed peer_id=ed01209897952D14BDFAEA780087C38FF3EB800CB20B882748FC95A575ADB9CD2CB21D@@0.0.0.0:1338 prev_role=ValidatingPeer next_role=Leader block_hash=a638001762e365280677a5407bac9adaa119c8cb82c8afe377b72f85e71ed4a9 new_height=1 + irohad1-1  | 2024-07-15T05:51:42.109858Z  INFO consensus: iroha_core::sumeragi::main_loop: Sumeragi initialized peer_id=ed01209897952D14BDFAEA780087C38FF3EB800CB20B882748FC95A575ADB9CD2CB21D@@0.0.0.0:1338 role=Leader + irohad3-1  | 2024-07-15T05:51:42.117040Z  INFO consensus: iroha_core::sumeragi::main_loop: Block committed peer_id=ed0120CACF3A84B8DC8710CE9D6B968EE95EC7EE4C93C85858F026F3B4417F569592CE@@0.0.0.0:1340 prev_role=ObservingPeer next_role=ObservingPeer block_hash=a638001762e365280677a5407bac9adaa119c8cb82c8afe377b72f85e71ed4a9 new_height=1 + irohad3-1  | 2024-07-15T05:51:42.117083Z  INFO consensus: iroha_core::sumeragi::main_loop: Sumeragi initialized peer_id=ed0120CACF3A84B8DC8710CE9D6B968EE95EC7EE4C93C85858F026F3B4417F569592CE@@0.0.0.0:1340 role=ObservingPeer + irohad0-1  | 2024-07-15T05:52:39.238596Z  INFO iroha_core::snapshot: Successfully created a snapshot of state at_height=1 + irohad1-1  | 2024-07-15T05:52:39.266902Z  INFO iroha_core::snapshot: Successfully created a snapshot of state at_height=1 + irohad3-1  | 2024-07-15T05:52:39.276634Z  INFO iroha_core::snapshot: Successfully created a snapshot of state at_height=1 + irohad2-1  | 2024-07-15T05:52:39.349409Z  INFO iroha_core::snapshot: Successfully created a snapshot of state at_height=1 diff --git a/src/guide/get-started/quick-start.md b/src/guide/get-started/launch-iroha.md similarity index 54% rename from src/guide/get-started/quick-start.md rename to src/guide/get-started/launch-iroha.md index 5173b35c3..4d5aa5658 100644 --- a/src/guide/get-started/quick-start.md +++ b/src/guide/get-started/launch-iroha.md @@ -1,26 +1,25 @@ -# Quick Start with Docker +# Launch Iroha 1. Install the prerequisites: - [Docker](https://docs.docker.com/get-docker/) - [Docker compose](https://docs.docker.com/compose/) -2. [Install Iroha from GitHub](./install.md). +2. [Install Iroha](./install.md). -3. Run `docker compose` to bring up a network of 4 containerised peers: +3. Run `docker compose` and specify the network configuration file to bring up a network of 4 containerized peers: ```bash - $ docker compose up + $ docker compose -f configs/swarm/docker-compose.yml up ``` Depending on your set-up, this might either - [pull the image](https://hub.docker.com/r/hyperledger/iroha2/tags) off - of DockerHub, or build the container locally. After this process is - complete, you'll be greeted with, + [pull the image](https://hub.docker.com/r/hyperledger/iroha2/tags) from DockerHub, or build the container locally. After this process + completes, you'll receive the following output: - <<< @/guide/get-started/quick-start.docker-compose-output.ansi + <<< @/guide/get-started/launch-iroha.docker-compose-output.ansi -4. Follow the [Bash tutorial](./bash.md) to check out Iroha's capabilities. +4. Proceed to the [CLI tutorial](./operate-iroha-via-cli.md) to check out Iroha's capabilities. 5. When you're done with the test network, just hit `Control + C` to stop the containers (`⌃ + C` on Mac). @@ -29,7 +28,7 @@ You might also be interested in other options for local compilation: -- For testing Iroha code quickly, you can use `docker-compose-single.yml`, +- To test Iroha code quickly, you can use `docker-compose-single.yml`, which starts a container with a single peer. - For testing Iroha code in normal conditions, you can use `docker-compose-local.yml`, which starts 4 connected containers with @@ -43,3 +42,7 @@ Docker even more customizable with the help of Swarm. ::: + +## What's Next + +Now that you have Iroha up and running, proceed to the [CLI tutorial](/guide/get-started/operate-iroha-via-cli) to learn how to work with it. \ No newline at end of file diff --git a/src/guide/get-started/operate-iroha-via-cli.md b/src/guide/get-started/operate-iroha-via-cli.md new file mode 100644 index 000000000..3e42614a2 --- /dev/null +++ b/src/guide/get-started/operate-iroha-via-cli.md @@ -0,0 +1,391 @@ +# Operate Iroha via CLI + +In this tutorial, we will set up and configure the Iroha client CLI, and perform some basic actions on the Iroha blockchain with it. + +You can learn how to: + - register [domains](#_3-registering-a-domain) and [accounts](#_4-registering-an-account) + - [mint](#_6-registering-and-minting-assets), [transfer](#_7-transferring-assets) and [burn](#_8-burning-assets) assets + - [visualize outputs](#_9-visualizing-outputs) + +## 1. Iroha 2 Client Setup + +Note, first, that we have already created the necessary binary executables when we [ran the `build` command](./build.md#build-iroha-client). + +Create a fresh folder for the client and copy the configuration file there: + +```bash +$ cp path_to_repo/configs/swarm/client.toml path_to_created_folder/ +``` + +Then copy the necessary binaries into the client folder: + +```bash +$ cp path_to_repo/target/release/iroha path_to_repo/target/release/kagami path_to_created_folder/ +``` + +Make sure you [brought up the test network](./launch-iroha.md) as well. You can monitor blockchain events in the terminal tab or window where it runs. + +## 2. Configuring Iroha 2 + +Now let's look at how to properly configure Iroha 2, and especially its **C**ommand-**L**ine **I**nterface client. + +Navigate to the binaries folder in your terminal. Check that it contains `iroha`, `kagami` and `client.toml`. + +::: tip + +Use `ls` to make sure all files are there, and if not, [return to Step 1](#_1-iroha-2-client-setup). + +::: + +Run + +```bash +$ ./iroha +``` + +::: details Expand to see the expected output + +```bash +Iroha CLI Client lets you interact with Iroha Peers Web API without direct network usage + +Usage: iroha [OPTIONS] + +Commands: + domain The subcommand related to domains + account The subcommand related to accounts + asset The subcommand related to assets + peer The subcommand related to p2p networking + events The subcommand related to event streaming + wasm The subcommand related to Wasm + blocks The subcommand related to block streaming + json The subcommand related to multi-instructions as Json or Json5 + help Print this message or the help of the given subcommand(s) + +Options: + -c, --config Path to the configuration file [default: client.toml] + -v, --verbose More verbose output + -h, --help Print help + -V, --version Print version + +``` + +::: + +To configure the Iroha client, run: + +```bash +$ ./iroha --config path/to/client.toml +``` + +Note: this is not _persistent configuration_: each time you run `iroha`, you must add the `--config path/to/client.toml` command-line argument, unless you put the `client.toml` config file in the same folder as `iroha` binary. + +The account specified in the `[account]` section of `client.toml` is pre-registered in the genesis block. Only it can interact with the blockchain for now, and if you change the keys or the domain of the account in the config file, you should make sure they are preregistered in the blockchain too. + +To check that your configuration options worked, try to run a query, +e.g.: + +```bash +$ ./iroha domain list all +``` + +If the output looks like some form of JSON, then the configuration was successful! + +## 3. Registering a Domain + +To get started, you must first register a domain: + +```bash +$ ./iroha domain register --id="looking_glass" +``` + +A _domain_ is a group of entities like asset definitions, accounts, and other objects grouped logically. We'll talk about it in more detail in other documentation sections. + +You will receive confirmation of the domain creation. However, this information will not be clearly visible within the message. To confirm that the new domain _looking_glass_ has been created successfully, run: + +```bash +$ ./iroha domain list all +``` + +The printout should contain the recently-created _looking_glass_ domain + +```json + { + "id": "looking_glass", + "logo": null, + "metadata": {}, + "owned_by": "ed0120CE7FA46C9DCE7EA4B125E2E36BDB63EA33073E7590AC92816AE1E861B7048B03@wonderland" + }, +``` + +Note, that the owner of the new domain is the account specified in our config file - it was the one performing registration. + +With a domain available, it is time to register an account in it. + +## 4. Registering an Account + +To register a new account, you need a cryptographic key pair consisting of a _public_ and a _private_ key that is used to establish a secure communication channel between a user and the network (to learn more about cryptographic keys, see [Public Key Cryptography](/guide/security/public-key-cryptography.md)). + +There is a number of different ways to generate a cryptographic key pair. For the convenience of our users, Iroha 2 is delivered with `kagami`, an in-built tool for generating keys. However, any user is free to generate their keys any way they like. + +To generate a new key pair with `kagami`, run the following command: + +```bash +$ ./kagami crypto +``` + +::: tip + +To customize the generated keys, you can specify a number of parameters. For instance, `kagami` can use one of four available algorithms to generate cryptographic keys. + +To learn more about generating cryptographic keys with `kagami`, available algorithms, and other parameters, see [Generating Cryptographic Keys with Kagami](/guide/security/generating-cryptographic-keys.md#kagami) + +::: + +For the purposes of this tutorial, we will use the following key pair: + +```bash +Public key (multihash): "ed012083CD3AB00C244CF627354302B4B2238161A4AAA36CD65209612C04262F706AE9" +Private key (multihash): "80264084A1DBC90B95A7F00E717A57277AF349DEA9A95EAC031D86E49320819635757583CD3AB00C244CF627354302B4B2238161A4AAA36CD65209612C04262F706AE9" +``` + +To register a new account within the _looking_glass_ domain, run: + +```bash +$ ./iroha account register --id="ed012083CD3AB00C244CF627354302B4B2238161A4AAA36CD65209612C04262F706AE9@looking_glass" +``` + +The `--id` argument in the above code snippet specifies the _account id_, the unique identificator assigned to that account, consisting of the user public key (which we generated above using `kagami`) and the domain it is created in. + +If the account registration is successful, you will receive a confirmation message. Like before, you should query the accounts to verify that the account was successfully registered. + +```bash +$ ./iroha account list all +``` + +::: details Expand to see the expected output + +```json +[ + { + "id": "ed0120E9F632D3034BAB6BB26D92AC8FD93EF878D9C5E69E01B61B4C47101884EE2F99@garden_of_live_flowers", + "metadata": {} + }, + { + "id": "ed01204164BF554923ECE1FD412D241036D863A6AE430476C898248B8237D77534CFC4@genesis", + "metadata": {} + }, + { + "id": "ed012083CD3AB00C244CF627354302B4B2238161A4AAA36CD65209612C04262F706AE9@looking_glass", + "metadata": {} + }, + { + "id": "ed012004FF5B81046DDCCF19E2E451C45DFB6F53759D4EB30FA2EFA807284D1CC33016@wonderland", + "metadata": { + "key": "value" + } + }, + { + "id": "ed0120CE7FA46C9DCE7EA4B125E2E36BDB63EA33073E7590AC92816AE1E861B7048B03@wonderland", + "metadata": { + "key": "value" + } + } +] + +``` +::: + +## 5. Transfering a Domain + +We could change the keys and domain in `client.toml` at this point and continue working with the account we just created, but we wouldn't be able to do much in the _looking_glass_ domain, as our new account is not the owner of _looking_glass_, and cannot manage it. + +Let's transfer the _looking_glass_ domain to the account we created: + +1. Run the transfer command: + + ```bash + $ ./iroha domain transfer --id="looking_glass" --from "ed0120CE7FA46C9DCE7EA4B125E2E36BDB63EA33073E7590AC92816AE1E861B7048B03@wonderland" --to "ed012083CD3AB00C244CF627354302B4B2238161A4AAA36CD65209612C04262F706AE9@looking_glass" + ``` +2. Check that the ownership changed: + + ```bash + $ ./iroha domain list all + ... + { + "id": "looking_glass", + "logo": null, + "metadata": {}, + "owned_by": "ed012083CD3AB00C244CF627354302B4B2238161A4AAA36CD65209612C04262F706AE9@looking_glass" + }, + ... + ``` + +3. Switch to the newly created account. For this, we need to modify the `public_key`, `private_key`, and `domain` in the `client.toml` config file with the ones we registered earlier. + + Your updated `client.toml` should look like this: + + ```toml + chain = "00000000-0000-0000-0000-000000000000" + torii_url = "http://127.0.0.1:8080/" + + [basic_auth] + web_login = "mad_hatter" + password = "ilovetea" + + [account] + domain = "looking_glass" + public_key = "ed012083CD3AB00C244CF627354302B4B2238161A4AAA36CD65209612C04262F706AE9" + private_key = "80264084A1DBC90B95A7F00E717A57277AF349DEA9A95EAC031D86E49320819635757583CD3AB00C244CF627354302B4B2238161A4AAA36CD65209612C04262F706AE9" + ``` + +::: tip +[Permissions](/guide/blockchain/permissions) determine which accounts have what rights within Iroha. Domain owners have the most rights in a domain by default, but permission configuration in Iroha is very flexible and can be customized to your needs. +::: + +Now that the network and users are registered, and we have control of the domain, it is possible to mint assets. + + +## 6. Registering and Minting Assets + +In order to mint assets, you need to register the [asset](/guide/blockchain/assets.md) first. We are going to register the _tea_ token within the _looking_glass_ network. To do that, run: + +```bash +$ ./iroha asset definition register --id="tea#looking_glass" --type="Numeric" +``` + +The _tea_ asset is now registered within the _looking_glass_ network. The +output within the CLI is the same as with other commands, you will be able +to see that there are new events in the pipeline. + +With the asset created, you can now mint tokens. Run: + +```bash +$ ./iroha asset mint --id="tea##ed012083CD3AB00C244CF627354302B4B2238161A4AAA36CD65209612C04262F706AE9@looking_glass" --quantity="100" +``` + +After minting one hundred _tea_, you will see more pipeline events in the logger, and you can also query the assets that you have just minted: + +```bash +$ ./iroha asset list all +``` + +After running this command, you will be able to see the tokens currently available on the network: + +::: details Expand to see the expected output + +```json +[ + { + "id": "tea##ed012083CD3AB00C244CF627354302B4B2238161A4AAA36CD65209612C04262F706AE9@looking_glass", + "value": { + "Numeric": "100" + } + }, + { + "id": "cabbage#garden_of_live_flowers#ed0120CE7FA46C9DCE7EA4B125E2E36BDB63EA33073E7590AC92816AE1E861B7048B03@wonderland", + "value": { + "Numeric": "44" + } + }, + { + "id": "rose##ed0120CE7FA46C9DCE7EA4B125E2E36BDB63EA33073E7590AC92816AE1E861B7048B03@wonderland", + "value": { + "Numeric": "13" + } + } +] + +``` +::: + + +## 7. Transferring Assets + +After minting the assets, you can transfer some of your tea to another account: + +```bash +$ ./iroha asset transfer --to="ed0120CE7FA46C9DCE7EA4B125E2E36BDB63EA33073E7590AC92816AE1E861B7048B03@wonderland" --id="tea##ed012083CD3AB00C244CF627354302B4B2238161A4AAA36CD65209612C04262F706AE9@looking_glass" --quantity=33 +``` + +## 8. Burning Assets + +Burning assets is quite similar to minting them: + +```bash +$ ./iroha asset burn --id="tea##ed012083CD3AB00C244CF627354302B4B2238161A4AAA36CD65209612C04262F706AE9@looking_glass" --quantity="15" + +``` + +## 9. Visualizing Outputs + +Although you will get a constant data feed of the network within the terminal running `docker compose`, you can also configure an output to listen +to events of several types on the network: blocks generation, transactions, data events and triggers. + +We will set up an event listener for the block pipeline. + +From a new terminal tab/window run: + +```bash +$ ./iroha events block-pipeline +``` + +The output would look like this: + +```json +Listening to events with filter: Pipeline(Block(BlockEventFilter { height: None, status: None })) +{ + "Pipeline": { + "Block": { + "header": { + "height": 14, + "prev_block_hash": "AF1ABC889019971D4C4E8866C347367D63A024319E50AEF989DB255F761E9D1D", + "transactions_hash": "7F2091D887BF9DBF6100DFEA696B06AE269C288AE55F1D281D9FDDAD93D1B8F1", + "creation_time_ms": 1721132667162, + "view_change_index": 1, + "consensus_estimation_ms": 4000 + }, + "hash": "1CC6256356418D02F19B17487AD4F7F105AE6CD3FD129760C575066484F3EF97", + "status": "Approved" + } + } +} +{ + "Pipeline": { + "Block": { + "header": { + "height": 14, + "prev_block_hash": "AF1ABC889019971D4C4E8866C347367D63A024319E50AEF989DB255F761E9D1D", + "transactions_hash": "7F2091D887BF9DBF6100DFEA696B06AE269C288AE55F1D281D9FDDAD93D1B8F1", + "creation_time_ms": 1721132667162, + "view_change_index": 1, + "consensus_estimation_ms": 4000 + }, + "hash": "99D30F9DD159A397A76E4A37143433BD302264F7509B6E154CA9C18263543857", + "status": "Committed" + } + } +} +{ + "Pipeline": { + "Block": { + "header": { + "height": 14, + "prev_block_hash": "AF1ABC889019971D4C4E8866C347367D63A024319E50AEF989DB255F761E9D1D", + "transactions_hash": "7F2091D887BF9DBF6100DFEA696B06AE269C288AE55F1D281D9FDDAD93D1B8F1", + "creation_time_ms": 1721132667162, + "view_change_index": 1, + "consensus_estimation_ms": 4000 + }, + "hash": "99D30F9DD159A397A76E4A37143433BD302264F7509B6E154CA9C18263543857", + "status": "Applied" + } + } +} + +``` + +Run the help command `./iroha events help` to find out how to listen to other types of events. + +## What's Next + +Now that you know the basics, you can proceed to one of our language-specific [turorials](/guide/get-started/tutorials) to learn how to build on Iroha. \ No newline at end of file diff --git a/src/guide/get-started/quick-start.docker-compose-output.ansi b/src/guide/get-started/quick-start.docker-compose-output.ansi deleted file mode 100644 index ec7221bb1..000000000 --- a/src/guide/get-started/quick-start.docker-compose-output.ansi +++ /dev/null @@ -1,32 +0,0 @@ -[+] Running 4/0 - ⠿ Container iroha-iroha2-1 Created 0.0s - ⠿ Container iroha-iroha0-1 Created 0.0s - ⠿ Container iroha-iroha3-1 Created 0.0s - ⠿ Container iroha-iroha1-1 Created 0.0s -Attaching to iroha-iroha0-1, iroha-iroha1-1, iroha-iroha2-1, iroha-iroha3-1 -iroha-iroha1-1 | 2023-02-27T12:43:08.540651Z  INFO iroha: Hyperledgerいろは2にようこそ！ -iroha-iroha1-1 | 2023-02-27T12:43:08.542379Z  INFO iroha: (translation) Welcome to Hyperledger Iroha 2! -iroha-iroha1-1 | 2023-02-27T12:43:08.542906Z  INFO iroha: Starting peer listen_addr=iroha1:1338 -iroha-iroha1-1 | 2023-02-27T12:43:08.543188Z  INFO iroha_p2p::network: Binding listener listen_addr=iroha1:1338 -iroha-iroha1-1 | 2023-02-27T12:43:08.551356Z  INFO iroha_p2p::network: Starting network actor listen_addr=iroha1:1338 -iroha-iroha1-1 | 2023-02-27T12:43:08.569289Z  INFO iroha_core::kura: Loaded 0 blocks at init. -iroha-iroha1-1 | 2023-02-27T12:43:08.572457Z ERROR iroha: Telemetry did not start -iroha-iroha1-1 | 2023-02-27T12:43:08.594190Z  INFO iroha: Starting Iroha -iroha-iroha2-1 | 2023-02-27T12:43:08.698491Z  INFO iroha: Hyperledgerいろは2にようこそ！ -iroha-iroha2-1 | 2023-02-27T12:43:08.700998Z  INFO iroha: (translation) Welcome to Hyperledger Iroha 2! -iroha-iroha2-1 | 2023-02-27T12:43:08.701624Z  INFO iroha: Starting peer listen_addr=iroha2:1339 -iroha-iroha2-1 | 2023-02-27T12:43:08.701895Z  INFO iroha_p2p::network: Binding listener listen_addr=iroha2:1339 -iroha-iroha2-1 | 2023-02-27T12:43:08.707759Z  INFO iroha_p2p::network: Starting network actor listen_addr=iroha2:1339 -iroha-iroha0-1 | 2023-02-27T12:43:08.719683Z  INFO iroha: Hyperledgerいろは2にようこそ！ -iroha-iroha0-1 | 2023-02-27T12:43:08.722029Z  INFO iroha: (translation) Welcome to Hyperledger Iroha 2! -iroha-iroha2-1 | 2023-02-27T12:43:08.730201Z  INFO iroha_core::kura: Loaded 1 blocks at init. -iroha-iroha2-1 | 2023-02-27T12:43:08.746975Z ERROR iroha: Telemetry did not start -iroha-iroha0-1 | 2023-02-27T12:43:08.748879Z  INFO iroha: Starting peer listen_addr=iroha0:1337 -iroha-iroha0-1 | 2023-02-27T12:43:08.749155Z  INFO iroha_p2p::network: Binding listener listen_addr=iroha0:1337 -iroha-iroha0-1 | 2023-02-27T12:43:08.754613Z  INFO iroha_p2p::network: Starting network actor listen_addr=iroha0:1337 -iroha-iroha3-1 | 2023-02-27T12:43:08.753230Z  INFO iroha: Hyperledgerいろは2にようこそ！ -iroha-iroha3-1 | 2023-02-27T12:43:08.754934Z  INFO iroha: (translation) Welcome to Hyperledger Iroha 2! -iroha-iroha3-1 | 2023-02-27T12:43:08.755503Z  INFO iroha: Starting peer listen_addr=iroha3:1340 -iroha-iroha3-1 | 2023-02-27T12:43:08.755802Z  INFO iroha_p2p::network: Binding listener listen_addr=iroha3:1340 -iroha-iroha3-1 | 2023-02-27T12:43:08.760437Z  INFO iroha_p2p::network: Starting network actor listen_addr=iroha3:1340 -iroha-iroha2-1 | 2023-02-27T12:43:08.763216Z  INFO iroha: Starting Iroha \ No newline at end of file diff --git a/src/guide/get-started/rust.md b/src/guide/get-started/rust.md index c4299bd8c..42a87675f 100644 --- a/src/guide/get-started/rust.md +++ b/src/guide/get-started/rust.md @@ -38,7 +38,7 @@ number of dependencies to start your own client, similar to Once the initial `v2.0.0` release is complete, we plan to create a package on [crates.io](https://crates.io/) with all the documentation. In the meantime, you could use the local copy that you've just created in the -[previous step](/guide/get-started/build) as a local installation in your client's +[previous step](/guide/get-started/install-iroha) as a local installation in your client's `Cargo.toml`: ```toml diff --git a/src/guide/get-started/tutorials.md b/src/guide/get-started/tutorials.md index d7913a3e9..1025db9c0 100644 --- a/src/guide/get-started/tutorials.md +++ b/src/guide/get-started/tutorials.md @@ -26,11 +26,10 @@ We invite you to follow the tutorial in this order: 0. If you are already familiar with Hyperledger Iroha, read about [the differences](/guide/iroha-2.md) between the two versions of Iroha. -1. [Install Iroha 2](/guide/get-started/install.md). +1. [Install Iroha 2](/guide/get-started/install-iroha.md). 2. Follow one of the language-specific guides to learn how to set up and configure Iroha 2, register a domain and an account, register and mind assets, and visualize outputs: - - [Bash](/guide/get-started/bash.md) - [Python](/guide/get-started/python.md) - [Rust](/guide/get-started/rust.md) - [Kotlin/Java](/guide/get-started/kotlin-java.md) diff --git a/src/guide/introduction.md b/src/guide/introduction.md deleted file mode 100644 index 8cd0f8a5d..000000000 --- a/src/guide/introduction.md +++ /dev/null @@ -1,34 +0,0 @@ -# Iroha 2 - -Iroha is a fully-featured -[blockchain ledger](/reference/glossary.md#blockchain-ledgers). With Iroha you -can: - -- Create and manage custom - [fungible assets](/reference/glossary.md#fungible-assets), such as currencies, - gold, and others -- Create and manage [non-fungible](/reference/glossary.md#non-fungible-assets) - assets -- Manage user accounts with a domain hierarchy and multi-signature - transactions -- Use efficient portable smart contracts implemented either via - [WebAssembly](/guide/blockchain/wasm.md) or - [Iroha Special Instructions](/guide/blockchain/instructions.md) -- Use both permissioned and permission-less blockchain deployments - -## Learn More - -For more information on Iroha 2, please take a look at the -[Iroha 2 Whitepaper](https://github.com/hyperledger/iroha/blob/iroha2/docs/source/iroha_2_whitepaper.md), -as well as the Hyperledger Iroha section within the -[Hyperledger Foundation Wiki](https://wiki.hyperledger.org/display/iroha). - -For more information on Iroha 1, take a look at the -[Iroha 1 documentation](https://iroha.readthedocs.io/en/develop/index.html). - -::: tip - -If you want to contribute to Hyperledger Iroha, please look at our -[Contributing Guide](https://github.com/hyperledger/iroha/blob/iroha2-dev/CONTRIBUTING.md). - -::: \ No newline at end of file diff --git a/src/guide/security/generating-cryptographic-keys.md b/src/guide/security/generating-cryptographic-keys.md index e38b4fcd4..97ee25d1b 100644 --- a/src/guide/security/generating-cryptographic-keys.md +++ b/src/guide/security/generating-cryptographic-keys.md @@ -14,7 +14,7 @@ Since `kagami` does not come with a manual page, you can use the `--help` (`-h`) ::: -After [installing Iroha](/guide/get-started/install.md), run the following command from the project's `root` directory to generate a new key pair: +After [installing Iroha](/guide/get-started/install-iroha.md), run the following command from the project's `root` directory to generate a new key pair: ```bash $ cargo run --bin kagami --release -- crypto diff --git a/src/index.md b/src/index.md index c3b667e86..19768b61d 100644 --- a/src/index.md +++ b/src/index.md @@ -13,12 +13,12 @@ hero: features: - icon: 🚀 title: Get Started - details: Install and build Iroha, follow step-by-step SDK tutorials to start working with Iroha + details: Install and build Iroha, follow a step-by-step tutorial to start working with Iroha link: /guide/get-started/ - icon: 📖 - title: Guide - details: Learn about Iroha functionality in great details and understand the underlying principles - link: /guide/introduction + title: Iroha Overview + details: Learn about Iroha functionality in great detail and understand the underlying principles + link: /guide/blockchain/how-iroha-works - icon: 💻 title: Reference details: Consult reference documentation for extensive information about available functionality From 2db70ddb66ffaa6503690dfce4700c9a82537fe2 Mon Sep 17 00:00:00 2001 From: a_zorina <64249490+a-zorina@users.noreply.github.com> Date: Wed, 17 Jul 2024 20:02:10 +0200 Subject: [PATCH 02/13] fix broken links Signed-off-by: a_zorina <64249490+a-zorina@users.noreply.github.com> Signed-off-by: a-zorina <64249490+a-zorina@users.noreply.github.com> --- src/guide/get-started/launch-iroha.md | 2 +- src/guide/get-started/operate-iroha-via-cli.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/guide/get-started/launch-iroha.md b/src/guide/get-started/launch-iroha.md index 4d5aa5658..83ec12001 100644 --- a/src/guide/get-started/launch-iroha.md +++ b/src/guide/get-started/launch-iroha.md @@ -5,7 +5,7 @@ - [Docker](https://docs.docker.com/get-docker/) - [Docker compose](https://docs.docker.com/compose/) -2. [Install Iroha](./install.md). +2. [Install Iroha](./install-iroha.md). 3. Run `docker compose` and specify the network configuration file to bring up a network of 4 containerized peers: diff --git a/src/guide/get-started/operate-iroha-via-cli.md b/src/guide/get-started/operate-iroha-via-cli.md index 3e42614a2..f553e88d5 100644 --- a/src/guide/get-started/operate-iroha-via-cli.md +++ b/src/guide/get-started/operate-iroha-via-cli.md @@ -9,7 +9,7 @@ You can learn how to: ## 1. Iroha 2 Client Setup -Note, first, that we have already created the necessary binary executables when we [ran the `build` command](./build.md#build-iroha-client). +Note, first, that we have already created the necessary binary executables when we [ran the `build` command](./install-iroha.md#build-iroha-2-client). Create a fresh folder for the client and copy the configuration file there: From 3151b5a367af747affe6f33bbd7649e83156e702 Mon Sep 17 00:00:00 2001 From: a_zorina <64249490+a-zorina@users.noreply.github.com> Date: Wed, 17 Jul 2024 20:13:54 +0200 Subject: [PATCH 03/13] fix section links Signed-off-by: a_zorina <64249490+a-zorina@users.noreply.github.com> Signed-off-by: a-zorina <64249490+a-zorina@users.noreply.github.com> --- src/guide/blockchain/instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/guide/blockchain/instructions.md b/src/guide/blockchain/instructions.md index c3f64e3c7..d768b76b2 100644 --- a/src/guide/blockchain/instructions.md +++ b/src/guide/blockchain/instructions.md @@ -149,7 +149,7 @@ can transfer assets between different accounts. To do this, an account have to be granted the [permission to transfer assets](/reference/permissions.md). Refer to an example on how to -transfer assets with [CLI](/guide/get-started/operate-iroha-via-cli.md#_7-transferring-assets) or [Rust](/guide/get-started/rust.md#_7-transferring-assets). +transfer assets with [CLI](/guide/get-started/operate-iroha-via-cli.md#_7-transferring-assets) or [Rust](/guide/get-started/rust.md#_6-transferring-assets). From 4fa6fefa86fcc8d40d4c8d1687058d95ea57c321 Mon Sep 17 00:00:00 2001 From: a-zorina <64249490+a-zorina@users.noreply.github.com> Date: Wed, 24 Jul 2024 14:49:56 +0200 Subject: [PATCH 04/13] Language and structure improvements Signed-off-by: a-zorina <64249490+a-zorina@users.noreply.github.com> --- src/guide/blockchain/assets.md | 2 +- src/guide/blockchain/data-model.md | 2 +- src/guide/blockchain/instructions.md | 8 +- src/guide/get-started/install-iroha.md | 8 +- .../get-started/operate-iroha-via-cli.md | 138 ++++++++---------- 5 files changed, 67 insertions(+), 91 deletions(-) diff --git a/src/guide/blockchain/assets.md b/src/guide/blockchain/assets.md index 73096db66..b086cf3cd 100644 --- a/src/guide/blockchain/assets.md +++ b/src/guide/blockchain/assets.md @@ -76,7 +76,7 @@ Assets can be [registered](./instructions.md#un-register), Refer to one of the language-specific guides to walk you through the process of registering and minting assets in a blockchain: -- [CLI](/guide/get-started/operate-iroha-via-cli.md#_6-registering-and-minting-assets) +- [CLI](/guide/get-started/operate-iroha-via-cli.md#_6-register-and-mint-assets) - [Rust](/guide/get-started/rust.md#_5-registering-and-minting-assets) - [Kotlin/Java](/guide/get-started/kotlin-java.md#_5-registering-and-minting-assets) - [Python](/guide/get-started/python.md#_5-registering-and-minting-assets) diff --git a/src/guide/blockchain/data-model.md b/src/guide/blockchain/data-model.md index fb5498077..c93e05f36 100644 --- a/src/guide/blockchain/data-model.md +++ b/src/guide/blockchain/data-model.md @@ -87,7 +87,7 @@ domain_looking_glass *-- account_rabbit : registered in | Language | Guide | | --------------------- |--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| CLI | Register a [domain](/guide/get-started/operate-iroha-via-cli.md#_3-registering-a-domain), an [account](/guide/get-started/operate-iroha-via-cli.md#_4-registering-an-account), an [asset](/guide/get-started/operate-iroha-via-cli.md#_6-registering-and-minting-assets) | +| CLI | Register a [domain](/guide/get-started/operate-iroha-via-cli.md#_3-register-a-domain), an [account](/guide/get-started/operate-iroha-via-cli.md#_4-register-an-account), an [asset](/guide/get-started/operate-iroha-via-cli.md#_6-register-and-mint-assets) | | Rust | Register a [domain](/guide/get-started/rust.md#_3-registering-a-domain), an [account](/guide/get-started/rust.md#_4-registering-an-account), an [asset](/guide/get-started/rust.md#_5-registering-and-minting-assets) | | Kotlin/Java | Register a [domain](/guide/get-started/kotlin-java.md#_3-querying-and-registering-domains), an [account](/guide/get-started/kotlin-java.md#_4-registering-an-account), an [asset](/guide/get-started/kotlin-java.md#_5-registering-and-minting-assets) | | Python | Register a [domain](/guide/get-started/python.md#_3-registering-a-domain), an [account](/guide/get-started/python.md#_4-registering-an-account), an [asset](/guide/get-started/python.md#_5-registering-and-minting-assets) | diff --git a/src/guide/blockchain/instructions.md b/src/guide/blockchain/instructions.md index d768b76b2..2f5938c20 100644 --- a/src/guide/blockchain/instructions.md +++ b/src/guide/blockchain/instructions.md @@ -109,7 +109,7 @@ process of registering objects in a blockchain: | Language | Guide | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| CLI | Register a [domain](/guide/get-started/operate-iroha-via-cli.md#_3-registering-a-domain), an [account](/guide/get-started/operate-iroha-via-cli.md#_4-registering-an-account), an [asset](/guide/get-started/operate-iroha-via-cli.md#_6-registering-and-minting-assets) | +| CLI | Register a [domain](/guide/get-started/operate-iroha-via-cli.md#_3-register-a-domain), an [account](/guide/get-started/operate-iroha-via-cli.md#_4-register-an-account), an [asset](/guide/get-started/operate-iroha-via-cli.md#_6-register-and-mint-assets) | | Rust | Register a [domain](/guide/get-started/rust.md#_3-registering-a-domain), an [account](/guide/get-started/rust.md#_4-registering-an-account), an [asset](/guide/get-started/rust.md#_5-registering-and-minting-assets) | | Kotlin/Java | Register a [domain](/guide/get-started/kotlin-java.md#_3-querying-and-registering-domains), an [account](/guide/get-started/kotlin-java.md#_4-registering-an-account), an [asset](/guide/get-started/kotlin-java.md#_5-registering-and-minting-assets) | | Python | Register a [domain](/guide/get-started/python.md#_3-registering-a-domain), an [account](/guide/get-started/python.md#_4-registering-an-account), an [asset](/guide/get-started/python.md#_5-registering-and-minting-assets) | @@ -130,7 +130,7 @@ are assumed to be non-negative as well, so you can never have $-1.0$ of Refer to one of the language-specific guides to walk you through the process of minting assets in a blockchain: -- [CLI](/guide/get-started/operate-iroha-via-cli.md#_6-registering-and-minting-assets) +- [CLI](/guide/get-started/operate-iroha-via-cli.md#_6-register-and-mint-assets) - [Rust](/guide/get-started/rust.md#_5-registering-and-minting-assets) - [Kotlin/Java](/guide/get-started/kotlin-java.md#_5-registering-and-minting-assets) - [Python](/guide/get-started/python.md#_5-registering-and-minting-assets) @@ -138,7 +138,7 @@ process of minting assets in a blockchain: Here are examples of burning assets: -- [CLI](/guide/get-started/operate-iroha-via-cli.md#_8-burning-assets) +- [CLI](/guide/get-started/operate-iroha-via-cli.md#_8-burn-assets) - [Rust](/guide/get-started/rust.md#_7-burning-assets) ## Transfer @@ -149,7 +149,7 @@ can transfer assets between different accounts. To do this, an account have to be granted the [permission to transfer assets](/reference/permissions.md). Refer to an example on how to -transfer assets with [CLI](/guide/get-started/operate-iroha-via-cli.md#_7-transferring-assets) or [Rust](/guide/get-started/rust.md#_6-transferring-assets). +transfer assets with [CLI](/guide/get-started/operate-iroha-via-cli.md#_7-transfer-assets) or [Rust](/guide/get-started/rust.md#_6-transferring-assets). diff --git a/src/guide/get-started/install-iroha.md b/src/guide/get-started/install-iroha.md index 04f0ab510..b9e4e20f2 100644 --- a/src/guide/get-started/install-iroha.md +++ b/src/guide/get-started/install-iroha.md @@ -50,7 +50,7 @@ You will be guided through the setup process. Just go with the defaults. -1. If you haven’t already, you might want to create a clean folder for +1. If you haven’t already, you might want to create a clean directory for Iroha 2, to keep things tidy. ```bash @@ -61,8 +61,8 @@ You will be guided through the setup process. Just go with the defaults. On macOS, if you get `fatal: could not create work tree dir 'iroha': Read-only file system`, - that’s because the home folder is not a real file system. The fix is to - create the `Git` folder. + that’s because the home directory is not a real file system. The fix is to + create the `Git` directory. ::: @@ -72,7 +72,7 @@ You will be guided through the setup process. Just go with the defaults. $ cd ~/Git ``` -3. Then `clone` the Iroha git repository into the folder `~/Git/iroha` +3. Then `clone` the Iroha git repository into the directory `~/Git/iroha` ```bash $ git clone https://github.com/hyperledger/iroha.git diff --git a/src/guide/get-started/operate-iroha-via-cli.md b/src/guide/get-started/operate-iroha-via-cli.md index f553e88d5..b0d6ce55f 100644 --- a/src/guide/get-started/operate-iroha-via-cli.md +++ b/src/guide/get-started/operate-iroha-via-cli.md @@ -3,41 +3,33 @@ In this tutorial, we will set up and configure the Iroha client CLI, and perform some basic actions on the Iroha blockchain with it. You can learn how to: - - register [domains](#_3-registering-a-domain) and [accounts](#_4-registering-an-account) - - [mint](#_6-registering-and-minting-assets), [transfer](#_7-transferring-assets) and [burn](#_8-burning-assets) assets - - [visualize outputs](#_9-visualizing-outputs) + - register [domains](#_3-register-a-domain) and [accounts](#_4-register-an-account) + - [mint](#_6-register-and-mint-assets), [transfer](#_7-transfer-assets) and [burn](#_8-burn-assets) assets + - [visualize outputs](#_9-visualize-outputs) -## 1. Iroha 2 Client Setup +## 1. Setup Iroha 2 Client Note, first, that we have already created the necessary binary executables when we [ran the `build` command](./install-iroha.md#build-iroha-2-client). -Create a fresh folder for the client and copy the configuration file there: +Create a fresh directory for the client and copy the configuration file there: ```bash -$ cp path_to_repo/configs/swarm/client.toml path_to_created_folder/ +$ cp path_to_repo/configs/swarm/client.toml path_to_created_directory/ ``` -Then copy the necessary binaries into the client folder: +Then copy the necessary binaries into the client directory: ```bash -$ cp path_to_repo/target/release/iroha path_to_repo/target/release/kagami path_to_created_folder/ +$ cp path_to_repo/target/release/iroha path_to_repo/target/release/kagami path_to_created_directory/ ``` -Make sure you [brought up the test network](./launch-iroha.md) as well. You can monitor blockchain events in the terminal tab or window where it runs. +Ensure you [brought up the test network](./launch-iroha.md). You can monitor blockchain events in the terminal where it runs. -## 2. Configuring Iroha 2 +## 2. Configure Iroha 2 Client -Now let's look at how to properly configure Iroha 2, and especially its **C**ommand-**L**ine **I**nterface client. +Navigate to the binaries directory in your terminal. Check that it contains `iroha`, `kagami` and `client.toml`. -Navigate to the binaries folder in your terminal. Check that it contains `iroha`, `kagami` and `client.toml`. - -::: tip - -Use `ls` to make sure all files are there, and if not, [return to Step 1](#_1-iroha-2-client-setup). - -::: - -Run +Run the client CLI: ```bash $ ./iroha @@ -71,26 +63,31 @@ Options: ::: -To configure the Iroha client, run: +By default, the Iroha client searches for its configuration in the `client.toml` file located in the current working directory. We already copied it there, so we're all set. + +::: tip + +To run any of the Iroha client commands with some other configuration file, use the following syntax: ```bash -$ ./iroha --config path/to/client.toml +$ ./iroha --config path/to/client.toml ``` -Note: this is not _persistent configuration_: each time you run `iroha`, you must add the `--config path/to/client.toml` command-line argument, unless you put the `client.toml` config file in the same folder as `iroha` binary. +This is not _persistent configuration_: each time you run `iroha`, you must add the `--config path/to/client.toml` command-line argument, unless you put the `client.toml` config file in the same directory as `iroha` binary. -The account specified in the `[account]` section of `client.toml` is pre-registered in the genesis block. Only it can interact with the blockchain for now, and if you change the keys or the domain of the account in the config file, you should make sure they are preregistered in the blockchain too. +::: + +The account specified in the `[account]` section of `client.toml` is preregistered in the blockchain. Only it can interact with the blockchain for now. If you change the keys or the domain of the account in the config file, you should ensure they are preregistered in the blockchain too. -To check that your configuration options worked, try to run a query, -e.g.: +To check that configuration works, try to run a query, e.g.: ```bash $ ./iroha domain list all ``` -If the output looks like some form of JSON, then the configuration was successful! +The output should contain several preregistered domains. -## 3. Registering a Domain +## 3. Register a Domain To get started, you must first register a domain: @@ -100,13 +97,13 @@ $ ./iroha domain register --id="looking_glass" A _domain_ is a group of entities like asset definitions, accounts, and other objects grouped logically. We'll talk about it in more detail in other documentation sections. -You will receive confirmation of the domain creation. However, this information will not be clearly visible within the message. To confirm that the new domain _looking_glass_ has been created successfully, run: +You will receive a confirmation message. However, the new domain details will not be directly readable in that message. To confirm that you created the new _looking_glass_ domain successfully, run: ```bash $ ./iroha domain list all ``` -The printout should contain the recently-created _looking_glass_ domain +The output should contain the _looking_glass_ domain: ```json { @@ -117,17 +114,15 @@ The printout should contain the recently-created _looking_glass_ domain }, ``` -Note, that the owner of the new domain is the account specified in our config file - it was the one performing registration. +Note, the owner of the new domain is the account specified in our config file. They performed the registration. With a domain available, it is time to register an account in it. -## 4. Registering an Account - -To register a new account, you need a cryptographic key pair consisting of a _public_ and a _private_ key that is used to establish a secure communication channel between a user and the network (to learn more about cryptographic keys, see [Public Key Cryptography](/guide/security/public-key-cryptography.md)). +## 4. Register an Account -There is a number of different ways to generate a cryptographic key pair. For the convenience of our users, Iroha 2 is delivered with `kagami`, an in-built tool for generating keys. However, any user is free to generate their keys any way they like. +To register a new account, you need a cryptographic key pair consisting of a _public_ and a _private_ key. You will use it to establish a secure communication channel between yourself and the network. -To generate a new key pair with `kagami`, run the following command: +For users' convenience, Iroha 2 comes with `kagami`, an in-built key generator tool. To generate a new key pair with `kagami`, run the following command: ```bash $ ./kagami crypto @@ -144,19 +139,19 @@ To learn more about generating cryptographic keys with `kagami`, available algor For the purposes of this tutorial, we will use the following key pair: ```bash -Public key (multihash): "ed012083CD3AB00C244CF627354302B4B2238161A4AAA36CD65209612C04262F706AE9" -Private key (multihash): "80264084A1DBC90B95A7F00E717A57277AF349DEA9A95EAC031D86E49320819635757583CD3AB00C244CF627354302B4B2238161A4AAA36CD65209612C04262F706AE9" +Public key (multihash): "ed0120ABA0446CFBD4E12627FFA870FB37993ED83EB1AE0588184B90D832A64C24C379" +Private key (multihash): "802620CBD3D701B561FE98463767729176404DC757D690F78980B8FDD40C171CCB8EB5" ``` To register a new account within the _looking_glass_ domain, run: ```bash -$ ./iroha account register --id="ed012083CD3AB00C244CF627354302B4B2238161A4AAA36CD65209612C04262F706AE9@looking_glass" +$ ./iroha account register --id="ed0120ABA0446CFBD4E12627FFA870FB37993ED83EB1AE0588184B90D832A64C24C379@looking_glass" ``` -The `--id` argument in the above code snippet specifies the _account id_, the unique identificator assigned to that account, consisting of the user public key (which we generated above using `kagami`) and the domain it is created in. +The `--id` argument in the above code snippet specifies the _account id_, the unique identifier of the account. It consists of the user public key (generated using `kagami`) and the domain it is associated with. -If the account registration is successful, you will receive a confirmation message. Like before, you should query the accounts to verify that the account was successfully registered. +If the account registration succeeds, you will receive a confirmation message. Like before, you should query the accounts to verify the details. ```bash $ ./iroha account list all @@ -175,7 +170,7 @@ $ ./iroha account list all "metadata": {} }, { - "id": "ed012083CD3AB00C244CF627354302B4B2238161A4AAA36CD65209612C04262F706AE9@looking_glass", + "id": "ed0120ABA0446CFBD4E12627FFA870FB37993ED83EB1AE0588184B90D832A64C24C379@looking_glass", "metadata": {} }, { @@ -191,11 +186,10 @@ $ ./iroha account list all } } ] - ``` ::: -## 5. Transfering a Domain +## 5. Transfer a Domain We could change the keys and domain in `client.toml` at this point and continue working with the account we just created, but we wouldn't be able to do much in the _looking_glass_ domain, as our new account is not the owner of _looking_glass_, and cannot manage it. @@ -204,63 +198,48 @@ Let's transfer the _looking_glass_ domain to the account we created: 1. Run the transfer command: ```bash - $ ./iroha domain transfer --id="looking_glass" --from "ed0120CE7FA46C9DCE7EA4B125E2E36BDB63EA33073E7590AC92816AE1E861B7048B03@wonderland" --to "ed012083CD3AB00C244CF627354302B4B2238161A4AAA36CD65209612C04262F706AE9@looking_glass" + $ ./iroha domain transfer --id="looking_glass" --from "ed0120CE7FA46C9DCE7EA4B125E2E36BDB63EA33073E7590AC92816AE1E861B7048B03@wonderland" --to "ed0120ABA0446CFBD4E12627FFA870FB37993ED83EB1AE0588184B90D832A64C24C379@looking_glass" ``` 2. Check that the ownership changed: ```bash $ ./iroha domain list all - ... - { - "id": "looking_glass", - "logo": null, - "metadata": {}, - "owned_by": "ed012083CD3AB00C244CF627354302B4B2238161A4AAA36CD65209612C04262F706AE9@looking_glass" - }, - ... ``` 3. Switch to the newly created account. For this, we need to modify the `public_key`, `private_key`, and `domain` in the `client.toml` config file with the ones we registered earlier. - Your updated `client.toml` should look like this: + The `account` section of your updated `client.toml` should look like this: ```toml - chain = "00000000-0000-0000-0000-000000000000" - torii_url = "http://127.0.0.1:8080/" - - [basic_auth] - web_login = "mad_hatter" - password = "ilovetea" - [account] domain = "looking_glass" - public_key = "ed012083CD3AB00C244CF627354302B4B2238161A4AAA36CD65209612C04262F706AE9" - private_key = "80264084A1DBC90B95A7F00E717A57277AF349DEA9A95EAC031D86E49320819635757583CD3AB00C244CF627354302B4B2238161A4AAA36CD65209612C04262F706AE9" + public_key = "ed0120ABA0446CFBD4E12627FFA870FB37993ED83EB1AE0588184B90D832A64C24C379" + private_key = "802620CBD3D701B561FE98463767729176404DC757D690F78980B8FDD40C171CCB8EB5" ``` ::: tip -[Permissions](/guide/blockchain/permissions) determine which accounts have what rights within Iroha. Domain owners have the most rights in a domain by default, but permission configuration in Iroha is very flexible and can be customized to your needs. +[Permissions](/guide/blockchain/permissions) determine accounts rights within Iroha. Domain owners have the most rights in a domain by default, but permission configuration in Iroha is very flexible and can be customized to your needs. ::: -Now that the network and users are registered, and we have control of the domain, it is possible to mint assets. +Now that we control the domain, we can mint assets in it. -## 6. Registering and Minting Assets +## 6. Register and Mint Assets -In order to mint assets, you need to register the [asset](/guide/blockchain/assets.md) first. We are going to register the _tea_ token within the _looking_glass_ network. To do that, run: +In order to mint assets, you need to register the [asset definition](/guide/blockchain/assets) first. We are going to register the _tea_ token within the _looking_glass_ network. To do that, run: ```bash $ ./iroha asset definition register --id="tea#looking_glass" --type="Numeric" ``` -The _tea_ asset is now registered within the _looking_glass_ network. The -output within the CLI is the same as with other commands, you will be able -to see that there are new events in the pipeline. +The Numeric _tea_ asset is now registered within the _looking_glass_ domain. + +If you open the terminal where the Iroha network runs, you will see that all our activity caused numerous pipeline events there. -With the asset created, you can now mint tokens. Run: +To mint _tea_ tokens run: ```bash -$ ./iroha asset mint --id="tea##ed012083CD3AB00C244CF627354302B4B2238161A4AAA36CD65209612C04262F706AE9@looking_glass" --quantity="100" +$ ./iroha asset mint --id="tea##ed0120ABA0446CFBD4E12627FFA870FB37993ED83EB1AE0588184B90D832A64C24C379@looking_glass" --quantity="100" ``` After minting one hundred _tea_, you will see more pipeline events in the logger, and you can also query the assets that you have just minted: @@ -269,14 +248,12 @@ After minting one hundred _tea_, you will see more pipeline events in the logger $ ./iroha asset list all ``` -After running this command, you will be able to see the tokens currently available on the network: - ::: details Expand to see the expected output ```json [ { - "id": "tea##ed012083CD3AB00C244CF627354302B4B2238161A4AAA36CD65209612C04262F706AE9@looking_glass", + "id": "tea##ed0120ABA0446CFBD4E12627FFA870FB37993ED83EB1AE0588184B90D832A64C24C379@looking_glass", "value": { "Numeric": "100" } @@ -294,29 +271,28 @@ After running this command, you will be able to see the tokens currently availab } } ] - ``` ::: -## 7. Transferring Assets +## 7. Transfer Assets After minting the assets, you can transfer some of your tea to another account: ```bash -$ ./iroha asset transfer --to="ed0120CE7FA46C9DCE7EA4B125E2E36BDB63EA33073E7590AC92816AE1E861B7048B03@wonderland" --id="tea##ed012083CD3AB00C244CF627354302B4B2238161A4AAA36CD65209612C04262F706AE9@looking_glass" --quantity=33 +$ ./iroha asset transfer --to="ed0120CE7FA46C9DCE7EA4B125E2E36BDB63EA33073E7590AC92816AE1E861B7048B03@wonderland" --id="tea##ed0120ABA0446CFBD4E12627FFA870FB37993ED83EB1AE0588184B90D832A64C24C379@looking_glass" --quantity=33 ``` -## 8. Burning Assets +## 8. Burn Assets Burning assets is quite similar to minting them: ```bash -$ ./iroha asset burn --id="tea##ed012083CD3AB00C244CF627354302B4B2238161A4AAA36CD65209612C04262F706AE9@looking_glass" --quantity="15" +$ ./iroha asset burn --id="tea##ed0120ABA0446CFBD4E12627FFA870FB37993ED83EB1AE0588184B90D832A64C24C379@looking_glass" --quantity="15" ``` -## 9. Visualizing Outputs +## 9. Visualize Outputs Although you will get a constant data feed of the network within the terminal running `docker compose`, you can also configure an output to listen to events of several types on the network: blocks generation, transactions, data events and triggers. From 3dc475df896e843534321c1c7640e87b5613d9d3 Mon Sep 17 00:00:00 2001 From: a-zorina <64249490+a-zorina@users.noreply.github.com> Date: Tue, 30 Jul 2024 15:33:26 +0200 Subject: [PATCH 05/13] External links and crate names fixes Signed-off-by: a-zorina <64249490+a-zorina@users.noreply.github.com> --- README.md | 2 +- src/documenting/snippets.md | 7 +++---- src/guide/blockchain/consensus.md | 2 +- src/guide/blockchain/how-iroha-works.md | 2 +- src/guide/blockchain/triggers.md | 2 +- src/guide/blockchain/wasm.md | 2 +- src/guide/configure/client-configuration.md | 2 +- .../configure/keys-for-network-deployment.md | 11 +++++----- src/guide/configure/peer-configuration.md | 2 +- src/guide/configure/sample-configuration.md | 8 ++------ src/guide/get-started/index.md | 4 ++-- src/guide/get-started/javascript.md | 4 ++-- src/guide/get-started/launch-iroha.md | 2 +- .../get-started/operate-iroha-via-cli.md | 2 +- src/guide/get-started/python.md | 14 +------------ src/guide/get-started/rust.md | 6 +++--- src/guide/iroha-2.md | 2 +- src/guide/security/public-key-cryptography.md | 2 +- .../security/storing-cryptographic-keys.md | 8 ++++---- src/index.md | 2 +- src/reference/specification.md | 20 ------------------- 21 files changed, 34 insertions(+), 72 deletions(-) delete mode 100644 src/reference/specification.md diff --git a/README.md b/README.md index 97fc00589..d86bf276d 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ The tutorial is suitable for both experienced and novice users. It explains Iroh If you are already familiar with Hyperledger Iroha, we invite you to read about [how Iroha 2 is different](https://hyperledger.github.io/iroha-2-docs/guide/iroha-2.html) from its previous version. -Check the [Hyperledger Iroha 2](https://github.com/hyperledger/iroha/tree/iroha2-dev#hyperledger-iroha) repository for more detailed information about API and available features. +Check the [Hyperledger Iroha 2](https://github.com/hyperledger/iroha/) repository for more detailed information about API and available features. ## Contribution diff --git a/src/documenting/snippets.md b/src/documenting/snippets.md index 27034a196..540b9fa97 100644 --- a/src/documenting/snippets.md +++ b/src/documenting/snippets.md @@ -9,14 +9,13 @@ located in other repositories, where they are built, run, and tested. ### Snippet Sources Snippet sources are defined in -[`snippet_sources.ts`](https://github.com/hyperledger/iroha-2-docs/blob/main/etc/snippet_sources.ts). -The `snippet_sources.ts` file is located at the documentation repository -and has the following format: +[`snippet_sources.ts`](https://github.com/hyperledger/iroha-2-docs/blob/main/etc/snippet-sources.ts). +The `snippet_sources.ts` file is located in the documentation repository and has the following format: ```ts export default [ { - src: 'https://raw.githubusercontent.com/hyperledger/iroha/iroha2-stable/MAINTAINERS.md', + src: 'https://raw.githubusercontent.com/hyperledger/iroha/main/MAINTAINERS.md', filename: 'iroha-maintainers-at-stable.md', }, { diff --git a/src/guide/blockchain/consensus.md b/src/guide/blockchain/consensus.md index 818a51cac..fc5bb739f 100644 --- a/src/guide/blockchain/consensus.md +++ b/src/guide/blockchain/consensus.md @@ -32,5 +32,5 @@ fail. The same thing happens if the peers have different instructions. [^1]: For prospective wizards, the - [Iroha 2 Whitepaper](https://github.com/hyperledger/iroha/blob/iroha2-dev/docs/source/iroha_2_whitepaper.md) + [Iroha 2 Whitepaper](https://github.com/hyperledger/iroha/blob/main/docs/source/iroha_2_whitepaper.md) is a good start. diff --git a/src/guide/blockchain/how-iroha-works.md b/src/guide/blockchain/how-iroha-works.md index 2564b7313..35b543c94 100644 --- a/src/guide/blockchain/how-iroha-works.md +++ b/src/guide/blockchain/how-iroha-works.md @@ -2,7 +2,7 @@ To understand how Iroha operates, let's draw parallels between a blockchain and a computer. If the blockchain is the computer, then in this metaphor of -ours the client binary (for example: [`iroha_client_cli`](/guide/get-started/operate-iroha-via-cli.md)) +ours the client binary (for example: [`iroha`](/guide/get-started/operate-iroha-via-cli.md)) is the keyboard, the blockchain is the hard drive, and the Iroha peer software is the processor. Like a processor, Iroha accepts portable instructions that modify what's written to the blockchain, allow certain diff --git a/src/guide/blockchain/triggers.md b/src/guide/blockchain/triggers.md index 879f98d82..ad623de4c 100644 --- a/src/guide/blockchain/triggers.md +++ b/src/guide/blockchain/triggers.md @@ -19,7 +19,7 @@ contains the necessary information: The documentation on the `EventFilter` types is under construction, as we are likely to make major changes to that particular architecture. For now, suffice it to say that you can look at the - [source code](https://github.com/hyperledger/iroha/blob/iroha2-dev/data_model/src/events/data/filters.rs) + [source code](https://github.com/hyperledger/iroha/blob/main/data_model/src/events/data/filters.rs) in `iroha_data_model` and see a few particularly interesting applications. diff --git a/src/guide/blockchain/wasm.md b/src/guide/blockchain/wasm.md index e2f820b17..1c25bb59e 100644 --- a/src/guide/blockchain/wasm.md +++ b/src/guide/blockchain/wasm.md @@ -70,7 +70,7 @@ edition = "2021" crate-type = ['cdylib'] [dependencies] -iroha_wasm = { git = "https://github.com/hyperledger/iroha/", branch = "iroha2-dev" } +iroha_wasm = { git = "https://github.com/hyperledger/iroha/"} ``` Note that the crate type is `cdylib`. Most Rust code is linked in a diff --git a/src/guide/configure/client-configuration.md b/src/guide/configure/client-configuration.md index b034d6b43..06c674a79 100644 --- a/src/guide/configure/client-configuration.md +++ b/src/guide/configure/client-configuration.md @@ -18,7 +18,7 @@ $ kagami config client > client-config.json ## Public and Private Keys -The `configs/client_cli/config.json` client 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`. +The `defaults/client.toml` client 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). diff --git a/src/guide/configure/keys-for-network-deployment.md b/src/guide/configure/keys-for-network-deployment.md index 6a617f61b..2bb7be074 100644 --- a/src/guide/configure/keys-for-network-deployment.md +++ b/src/guide/configure/keys-for-network-deployment.md @@ -1,10 +1,9 @@ # Keys for Network Deployment -If you're deploying your own Iroha 2 network, your unique cryptographic keys must be specified in all three of the configuration files: +If you're deploying your own Iroha 2 network, your unique cryptographic keys must be specified in all configuration files: -1. Peer configuration file: [`configs/peer/config.json`](./peer-configuration.md) -2. Client configuration file: [`configs/client_cli/config.json`](./client-configuration.md) -3. Genesis block file: [`configs/peer/genesis.json`](./genesis.md) +1. Client configuration file: [`defaults/client.toml`](./client-configuration.md) +2. Genesis block file: [`defaults/genesis.json`](./genesis.md) To learn more about cryptographic keys and their role, see [Security > Public Key Cryptography](../security/public-key-cryptography.md). @@ -52,13 +51,13 @@ Finally, while the first client _could_ use the genesis account to register new ::: warning -`iroha_client_cli` currently processes all of its instructions in the JSON format, it also provides a dedicated instruction to unregister accounts. +`iroha` binary currently processes all of its instructions in the JSON format, it also provides a dedicated instruction to unregister accounts. If you plan on creating a private blockchain, you should consider writing your own client based on the `client` Rust crate, or any of the provided client libraries: - [iroha-python](https://github.com/hyperledger/iroha-python) - [iroha-iOS](https://github.com/hyperledger/iroha-ios) - [iroha-java](https://github.com/hyperledger/iroha-java) -- [iroha-javascript](https://github.com/hyperledger/iroha-javascript/tree/iroha2) +- [iroha-javascript](https://github.com/hyperledger/iroha-javascript) ::: diff --git a/src/guide/configure/peer-configuration.md b/src/guide/configure/peer-configuration.md index 1e4a1b503..6d16146d7 100644 --- a/src/guide/configure/peer-configuration.md +++ b/src/guide/configure/peer-configuration.md @@ -68,7 +68,7 @@ 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_client_cli` to +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 diff --git a/src/guide/configure/sample-configuration.md b/src/guide/configure/sample-configuration.md index 72f1d6410..94448c23a 100644 --- a/src/guide/configure/sample-configuration.md +++ b/src/guide/configure/sample-configuration.md @@ -2,17 +2,13 @@ Here you can find sample configuration files for Iroha 2: -- Peer Configuration [`configs/peer/config.json`](https://github.com/hyperledger/iroha/blob/iroha2-dev/configs/peer/config.json).\ - For details, see [Peer Configuration](peer-configuration.md). -- Genesis Block [`configs/peer/genesis.json`](https://github.com/hyperledger/iroha/blob/iroha2-dev/configs/peer/genesis.json).\ +- Genesis Block [`configs/peer/genesis.json`](https://github.com/hyperledger/iroha/blob/main/defaults/genesis.json).\ For details, see [Genesis Block](genesis.md). -- Client Configuration [`configs/client/config.json`](https://github.com/hyperledger/iroha/blob/iroha2-dev/configs/client/config.json).\ +- Client Configuration [`configs/client/config.json`](https://github.com/hyperledger/iroha/blob/main/defaults/client.toml).\ For details, see [Client Configuration](client-configuration.md). ::: code-group -<<< @/snippets/peer-config-template.toml - <<< @/snippets/genesis.json <<< @/snippets/client-cli-config-template.toml diff --git a/src/guide/get-started/index.md b/src/guide/get-started/index.md index a0c84e4f0..bc5d04824 100644 --- a/src/guide/get-started/index.md +++ b/src/guide/get-started/index.md @@ -46,7 +46,7 @@ Once you've learned the basics, we suggest you read through the following: ## Learn More For more information on Iroha 2, please take a look at the -[Iroha 2 Whitepaper](https://github.com/hyperledger/iroha/blob/iroha2/docs/source/iroha_2_whitepaper.md), +[Iroha 2 Whitepaper](https://github.com/hyperledger/iroha/tree/main/docs/source/iroha_2_whitepaper.md), as well as the Hyperledger Iroha section within the [Hyperledger Foundation Wiki](https://wiki.hyperledger.org/display/iroha). @@ -56,6 +56,6 @@ For more information on Iroha 1, take a look at the ::: tip If you want to contribute to Hyperledger Iroha, please look at our -[Contributing Guide](https://github.com/hyperledger/iroha/blob/iroha2-dev/CONTRIBUTING.md). +[Contributing Guide](https://github.com/hyperledger/iroha/blob/main/CONTRIBUTING.md). ::: \ No newline at end of file diff --git a/src/guide/get-started/javascript.md b/src/guide/get-started/javascript.md index 78ab03caf..bcb7fdfec 100644 --- a/src/guide/get-started/javascript.md +++ b/src/guide/get-started/javascript.md @@ -403,7 +403,7 @@ in this guide! In this guide, we are roughly recreating the project that is a part of `iroha-javascript` integration tests. If you want to see the full project, please refer to the -[`@iroha2/client-test-web` sources](https://github.com/hyperledger/iroha-javascript/tree/iroha2/packages/client/test/integration/test-web). +[`@iroha2/client-test-web` sources](https://github.com/hyperledger/iroha-javascript/tree/main/packages/client/test/integration/test-web). ::: @@ -479,7 +479,7 @@ Here is a small demo with the usage of this component: ## 9. Subscribing to Block Stream You can use -[`/block/stream` endpoint](https://github.com/hyperledger/iroha/blob/iroha2-lts/docs/source/references/api_spec.md#blocks-stream) +[`/block/stream` endpoint](/reference/torii-endpoints.md#blocks-stream) to send a subscription request for block streaming. Via this endpoint, the client first provides the starting block number diff --git a/src/guide/get-started/launch-iroha.md b/src/guide/get-started/launch-iroha.md index 83ec12001..fae6f3a8e 100644 --- a/src/guide/get-started/launch-iroha.md +++ b/src/guide/get-started/launch-iroha.md @@ -10,7 +10,7 @@ 3. Run `docker compose` and specify the network configuration file to bring up a network of 4 containerized peers: ```bash - $ docker compose -f configs/swarm/docker-compose.yml up + $ docker compose -f defaults/docker-compose.yml up ``` Depending on your set-up, this might either diff --git a/src/guide/get-started/operate-iroha-via-cli.md b/src/guide/get-started/operate-iroha-via-cli.md index b0d6ce55f..5a8eaba07 100644 --- a/src/guide/get-started/operate-iroha-via-cli.md +++ b/src/guide/get-started/operate-iroha-via-cli.md @@ -14,7 +14,7 @@ Note, first, that we have already created the necessary binary executables when Create a fresh directory for the client and copy the configuration file there: ```bash -$ cp path_to_repo/configs/swarm/client.toml path_to_created_directory/ +$ cp path_to_repo/defaults/client.toml path_to_created_directory/ ``` Then copy the necessary binaries into the client directory: diff --git a/src/guide/get-started/python.md b/src/guide/get-started/python.md index 39efdb6e4..4b6eb2a79 100644 --- a/src/guide/get-started/python.md +++ b/src/guide/get-started/python.md @@ -1,17 +1,5 @@ # Python 3 Guide -::: warning - -WIP: The `iroha-python` SDK only works with the [`iroha2-lts`](https://github.com/hyperledger/iroha/tree/iroha2-lts) for now. -It applies both to the -[`iroha2-edge`](https://github.com/hyperledger/iroha-python/tree/iroha2-edge) and -the [`iroha2`](https://github.com/hyperledger/iroha-python/tree/iroha2) branches. -Our team recommends using the `iroha2-edge` branch while we update the `iroha2` one. - - - -::: - ## 1. Iroha 2 Client Setup There are two versions of Iroha Python to choose from. In theory, the Iroha @@ -61,7 +49,7 @@ slightly different. ## 2. Configuring Iroha 2 -Unlike `iroha_client_cli`, finding the configuration file in a scripting +Unlike `iroha` binary, finding the configuration file in a scripting language is the responsibility of the person writing the script. The easiest method is to de-serialise a dictionary type from the provided `config.json`. diff --git a/src/guide/get-started/rust.md b/src/guide/get-started/rust.md index 42a87675f..a2c7e9c44 100644 --- a/src/guide/get-started/rust.md +++ b/src/guide/get-started/rust.md @@ -33,7 +33,7 @@ constants. If you add `iroha_client` to the other two crates, you get the minimum number of dependencies to start your own client, similar to -`iroha_client_cli`. +`iroha` binary. Once the initial `v2.0.0` release is complete, we plan to create a package on [crates.io](https://crates.io/) with all the documentation. In the @@ -58,7 +58,7 @@ first. ::: info You could also make use of our `test_network` crate, which is available via -[GitHub](https://github.com/hyperledger/iroha/tree/iroha2/core/test_network) +[GitHub](https://github.com/hyperledger/iroha/tree/main/core/test_network) but not via crates.io. ::: @@ -403,4 +403,4 @@ for event in iroha_client.listen_for_events(filter)? { Needless to say, an synchronous infinite blocking loop is bad UX for anything but a command-line program, but for illustration purposes, this -would create a nice printout, just like in `iroha_client_cli`. +would create a nice printout, just like in `iroha` binary. diff --git a/src/guide/iroha-2.md b/src/guide/iroha-2.md index 70cd4c5eb..82d5863d9 100644 --- a/src/guide/iroha-2.md +++ b/src/guide/iroha-2.md @@ -27,7 +27,7 @@ would be accessible from Iroha 2. Iroha 2 learned a great deal from the development of the original Iroha. Of particular importance is the new and improved Byzantine-fault-tolerant consensus algorithm: -[_Sumeragi_](https://github.com/hyperledger/iroha/blob/iroha2-dev/docs/source/iroha_2_whitepaper.md#28-consensus). +[_Sumeragi_](https://github.com/hyperledger/iroha/tree/main/docs/source/iroha_2_whitepaper.md#28-consensus). This new consensus allowed us to expand what could be done on a blockchain without any security risks. diff --git a/src/guide/security/public-key-cryptography.md b/src/guide/security/public-key-cryptography.md index 24a440bb4..051e5d35c 100644 --- a/src/guide/security/public-key-cryptography.md +++ b/src/guide/security/public-key-cryptography.md @@ -18,7 +18,7 @@ Since every transaction must be signed on behalf of a peer, every operation requ ::: warning -All clients are different, but `iroha_client_cli` is the least secure in this regard, as it stores a peer's private key in the `multihash` format saved to a plain text file that could be overridden with an environment variable. +All clients are different, but `iroha` binary is the least secure in this regard, as it stores a peer's private key in the `multihash` format saved to a plain text file that could be overridden with an environment variable. **This is currently a reference implementation that will _not_ be a part of the production release.** diff --git a/src/guide/security/storing-cryptographic-keys.md b/src/guide/security/storing-cryptographic-keys.md index 2590d4e64..7179040d3 100644 --- a/src/guide/security/storing-cryptographic-keys.md +++ b/src/guide/security/storing-cryptographic-keys.md @@ -47,7 +47,7 @@ KeePassXC offers enhanced security, flexibility, and control. It not only stores ::: tip -Theoretically, any of the KeePass ports [listed on the official website](https://keepass.info/download.html) can be utilized for the key storage purposes. +Theoretically, any of the KeePass ports [listed on the official website](https://keepass.info/download.html) can be utilized for key storage purposes. We recommend any of the following: [KeePassX](https://www.keepassx.org/) or [KeePassXC](https://keepassxc.org/). ::: @@ -114,11 +114,11 @@ For those who seek the highest level of offline security, the option of storing ### Using a Hardware Key -Our team considers hardware keys to be one of the best safety measures. A hardware key—a compact device that connects via a USB port and has a size of a typical flash drive—only processes security-related events when it is connected to a machine. This allows you to easily disconnect the device in case of a security breach, or simply reconnect it to a different machine whenever it is required. +Our team considers hardware keys to be one of the best safety measures. A hardware key—a compact device that connects via a USB port and has the size of a typical flash drive—only processes security-related events when it is connected to a machine. This allows you to easily disconnect the device in case of a security breach, or simply reconnect it to a different machine whenever it is required. However, since there are many brands of hardware keys—each with their unique APIs—it is important to research the market to find the key that best suits your needs. -So far, our team has enternally tested the [YubiKey 5C](https://www.yubico.com/il/product/yubikey-5c/) hardware key that proved to have many positive features, including versatile API functionality. +So far, our team has internally tested the [YubiKey 5C](https://www.yubico.com/il/product/yubikey-5c/) hardware key which proved to have many positive features, including versatile API functionality. However, there's a potential drawback to consider. Implementing the [HMAC challenge-response authentication](https://en.wikipedia.org/wiki/Challenge%E2%80%93response_authentication) and storing a corresponding _private_ key for this response could create a vulnerability. This setup might inadvertently enable attackers to make educated guesses about the information stored within the YubiKey 5C's memory, thereby compromising the overall security. @@ -134,4 +134,4 @@ To read more about _the method above_, see the answer by one of the KeePassXC de ### Using a Mnemonic Phrase -Alternatively, you can memorize a private key as a series of words, known as a _mnemonic phrase_. This method, used in many wallets, requires remembering around 25 specific words. You can generate these words using the [XKCD password generator](https://xkpasswd.net/s/). +Alternatively, you can memorize a private key as a series of words, known as a _mnemonic phrase_. This method, used in many wallets, requires remembering around 25 specific words. Most password managers, including the previously discussed KeePassXC, offer mnemonic passphrase generation. diff --git a/src/index.md b/src/index.md index 19768b61d..107f0fbbf 100644 --- a/src/index.md +++ b/src/index.md @@ -8,7 +8,7 @@ hero: #actions: #- theme: alt # text: View on GitHub - # link: https://github.com/hyperledger/iroha/tree/iroha2-dev + # link: https://github.com/hyperledger/iroha/ features: - icon: 🚀 diff --git a/src/reference/specification.md b/src/reference/specification.md deleted file mode 100644 index 8b398a82a..000000000 --- a/src/reference/specification.md +++ /dev/null @@ -1,20 +0,0 @@ - - -# API Specification - -::: info - -This page contains a copy of `api_spec.md` from -`hyperledger/iroha#iroha2-dev`. You can read the most up-to-date version of -it on -[GitHub](https://github.com/hyperledger/iroha/blob/iroha2-dev/docs/source/references/api_spec.md). - -Please note this page was last updated on {{ new Date(page.lastUpdated).toLocaleString() }}. - -::: - - From c457d31def757a24fe067b0fe20adc6a5739dd31 Mon Sep 17 00:00:00 2001 From: a-zorina <64249490+a-zorina@users.noreply.github.com> Date: Thu, 1 Aug 2024 13:10:20 +0200 Subject: [PATCH 06/13] Switch to using cargo install for iroha binaries in getting started Signed-off-by: a-zorina <64249490+a-zorina@users.noreply.github.com> --- src/guide/get-started/install-iroha.md | 16 +++--- src/guide/get-started/launch-iroha.md | 13 +++-- .../get-started/operate-iroha-via-cli.md | 52 ++++++++----------- 3 files changed, 39 insertions(+), 42 deletions(-) diff --git a/src/guide/get-started/install-iroha.md b/src/guide/get-started/install-iroha.md index b9e4e20f2..8acd12c91 100644 --- a/src/guide/get-started/install-iroha.md +++ b/src/guide/get-started/install-iroha.md @@ -45,7 +45,7 @@ $ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh You will be guided through the setup process. Just go with the defaults. -## Install Iroha from GitHub +## Clone Iroha from GitHub @@ -78,21 +78,19 @@ You will be guided through the setup process. Just go with the defaults. $ git clone https://github.com/hyperledger/iroha.git ``` -### Build Iroha 2 Client +### Install Iroha 2 Binaries -1. Navigate to the directory containing the Iroha repository: - ```bash - $ cd ~/Git/iroha - ``` +To install the necessary binaries system-wide, use the following commands: -2. Build the Iroha 2 client using: ```bash - $ cargo build --release + $ cargo install --git https://github.com/hyperledger/iroha.git iroha ``` - Build artifacts are created in the `./target/release/` directory. + ```bash + $ cargo install --git https://github.com/hyperledger/iroha.git kagami + ``` ## What's Next diff --git a/src/guide/get-started/launch-iroha.md b/src/guide/get-started/launch-iroha.md index fae6f3a8e..eb2817057 100644 --- a/src/guide/get-started/launch-iroha.md +++ b/src/guide/get-started/launch-iroha.md @@ -7,7 +7,9 @@ 2. [Install Iroha](./install-iroha.md). -3. Run `docker compose` and specify the network configuration file to bring up a network of 4 containerized peers: +3. Navigate to the repository root directory. + +4. Run `docker compose` and specify the network configuration file to bring up a network of 4 containerized peers: ```bash $ docker compose -f defaults/docker-compose.yml up @@ -19,11 +21,16 @@ <<< @/guide/get-started/launch-iroha.docker-compose-output.ansi -4. Proceed to the [CLI tutorial](./operate-iroha-via-cli.md) to check out Iroha's capabilities. +5. Proceed to the [CLI tutorial](./operate-iroha-via-cli.md) to check out Iroha's capabilities. -5. When you're done with the test network, just hit `Control + C` to stop the +6. When you're done with the test network, just hit `Control + C` to stop the containers (`⌃ + C` on Mac). +::: tip + + You can monitor blockchain events in the terminal where the test network runs. + +::: ## Docker Options You might also be interested in other options for local compilation: diff --git a/src/guide/get-started/operate-iroha-via-cli.md b/src/guide/get-started/operate-iroha-via-cli.md index 5a8eaba07..a0156e302 100644 --- a/src/guide/get-started/operate-iroha-via-cli.md +++ b/src/guide/get-started/operate-iroha-via-cli.md @@ -9,30 +9,22 @@ You can learn how to: ## 1. Setup Iroha 2 Client -Note, first, that we have already created the necessary binary executables when we [ran the `build` command](./install-iroha.md#build-iroha-2-client). +Ensure you [installed Iroha](./install-iroha.md) and [brought up the test network](./launch-iroha.md). -Create a fresh directory for the client and copy the configuration file there: +Create a fresh directory and copy the `client.toml` configuration file there: ```bash -$ cp path_to_repo/defaults/client.toml path_to_created_directory/ +$ cp path_to_iroha_repo/defaults/client.toml path_to_created_directory/ ``` -Then copy the necessary binaries into the client directory: - -```bash -$ cp path_to_repo/target/release/iroha path_to_repo/target/release/kagami path_to_created_directory/ -``` - -Ensure you [brought up the test network](./launch-iroha.md). You can monitor blockchain events in the terminal where it runs. - ## 2. Configure Iroha 2 Client -Navigate to the binaries directory in your terminal. Check that it contains `iroha`, `kagami` and `client.toml`. +Navigate to the directory with the configuration file in your terminal. Run the client CLI: ```bash -$ ./iroha +$ iroha ``` ::: details Expand to see the expected output @@ -70,10 +62,10 @@ By default, the Iroha client searches for its configuration in the `client.toml` To run any of the Iroha client commands with some other configuration file, use the following syntax: ```bash -$ ./iroha --config path/to/client.toml +$ iroha --config path/to/client.toml ``` -This is not _persistent configuration_: each time you run `iroha`, you must add the `--config path/to/client.toml` command-line argument, unless you put the `client.toml` config file in the same directory as `iroha` binary. +This is not _persistent configuration_: each time you run `iroha`, you must add the `--config path/to/client.toml` command-line argument, unless you put the `client.toml` config file in your working directory. ::: @@ -82,7 +74,7 @@ The account specified in the `[account]` section of `client.toml` is preregister To check that configuration works, try to run a query, e.g.: ```bash -$ ./iroha domain list all +$ iroha domain list all ``` The output should contain several preregistered domains. @@ -92,7 +84,7 @@ The output should contain several preregistered domains. To get started, you must first register a domain: ```bash -$ ./iroha domain register --id="looking_glass" +$ iroha domain register --id="looking_glass" ``` A _domain_ is a group of entities like asset definitions, accounts, and other objects grouped logically. We'll talk about it in more detail in other documentation sections. @@ -100,7 +92,7 @@ A _domain_ is a group of entities like asset definitions, accounts, and other ob You will receive a confirmation message. However, the new domain details will not be directly readable in that message. To confirm that you created the new _looking_glass_ domain successfully, run: ```bash -$ ./iroha domain list all +$ iroha domain list all ``` The output should contain the _looking_glass_ domain: @@ -125,7 +117,7 @@ To register a new account, you need a cryptographic key pair consisting of a _pu For users' convenience, Iroha 2 comes with `kagami`, an in-built key generator tool. To generate a new key pair with `kagami`, run the following command: ```bash -$ ./kagami crypto +$ kagami crypto ``` ::: tip @@ -146,7 +138,7 @@ Private key (multihash): "802620CBD3D701B561FE98463767729176404DC757D690F78980B8 To register a new account within the _looking_glass_ domain, run: ```bash -$ ./iroha account register --id="ed0120ABA0446CFBD4E12627FFA870FB37993ED83EB1AE0588184B90D832A64C24C379@looking_glass" +$ iroha account register --id="ed0120ABA0446CFBD4E12627FFA870FB37993ED83EB1AE0588184B90D832A64C24C379@looking_glass" ``` The `--id` argument in the above code snippet specifies the _account id_, the unique identifier of the account. It consists of the user public key (generated using `kagami`) and the domain it is associated with. @@ -154,7 +146,7 @@ The `--id` argument in the above code snippet specifies the _account id_, the un If the account registration succeeds, you will receive a confirmation message. Like before, you should query the accounts to verify the details. ```bash -$ ./iroha account list all +$ iroha account list all ``` ::: details Expand to see the expected output @@ -198,12 +190,12 @@ Let's transfer the _looking_glass_ domain to the account we created: 1. Run the transfer command: ```bash - $ ./iroha domain transfer --id="looking_glass" --from "ed0120CE7FA46C9DCE7EA4B125E2E36BDB63EA33073E7590AC92816AE1E861B7048B03@wonderland" --to "ed0120ABA0446CFBD4E12627FFA870FB37993ED83EB1AE0588184B90D832A64C24C379@looking_glass" + $ iroha domain transfer --id="looking_glass" --from "ed0120CE7FA46C9DCE7EA4B125E2E36BDB63EA33073E7590AC92816AE1E861B7048B03@wonderland" --to "ed0120ABA0446CFBD4E12627FFA870FB37993ED83EB1AE0588184B90D832A64C24C379@looking_glass" ``` 2. Check that the ownership changed: ```bash - $ ./iroha domain list all + $ iroha domain list all ``` 3. Switch to the newly created account. For this, we need to modify the `public_key`, `private_key`, and `domain` in the `client.toml` config file with the ones we registered earlier. @@ -229,7 +221,7 @@ Now that we control the domain, we can mint assets in it. In order to mint assets, you need to register the [asset definition](/guide/blockchain/assets) first. We are going to register the _tea_ token within the _looking_glass_ network. To do that, run: ```bash -$ ./iroha asset definition register --id="tea#looking_glass" --type="Numeric" +$ iroha asset definition register --id="tea#looking_glass" --type="Numeric" ``` The Numeric _tea_ asset is now registered within the _looking_glass_ domain. @@ -239,13 +231,13 @@ If you open the terminal where the Iroha network runs, you will see that all our To mint _tea_ tokens run: ```bash -$ ./iroha asset mint --id="tea##ed0120ABA0446CFBD4E12627FFA870FB37993ED83EB1AE0588184B90D832A64C24C379@looking_glass" --quantity="100" +$ iroha asset mint --id="tea##ed0120ABA0446CFBD4E12627FFA870FB37993ED83EB1AE0588184B90D832A64C24C379@looking_glass" --quantity="100" ``` After minting one hundred _tea_, you will see more pipeline events in the logger, and you can also query the assets that you have just minted: ```bash -$ ./iroha asset list all +$ iroha asset list all ``` ::: details Expand to see the expected output @@ -280,7 +272,7 @@ $ ./iroha asset list all After minting the assets, you can transfer some of your tea to another account: ```bash -$ ./iroha asset transfer --to="ed0120CE7FA46C9DCE7EA4B125E2E36BDB63EA33073E7590AC92816AE1E861B7048B03@wonderland" --id="tea##ed0120ABA0446CFBD4E12627FFA870FB37993ED83EB1AE0588184B90D832A64C24C379@looking_glass" --quantity=33 +$ iroha asset transfer --to="ed0120CE7FA46C9DCE7EA4B125E2E36BDB63EA33073E7590AC92816AE1E861B7048B03@wonderland" --id="tea##ed0120ABA0446CFBD4E12627FFA870FB37993ED83EB1AE0588184B90D832A64C24C379@looking_glass" --quantity=33 ``` ## 8. Burn Assets @@ -288,7 +280,7 @@ $ ./iroha asset transfer --to="ed0120CE7FA46C9DCE7EA4B125E2E36BDB63EA33073E7590A Burning assets is quite similar to minting them: ```bash -$ ./iroha asset burn --id="tea##ed0120ABA0446CFBD4E12627FFA870FB37993ED83EB1AE0588184B90D832A64C24C379@looking_glass" --quantity="15" +$ iroha asset burn --id="tea##ed0120ABA0446CFBD4E12627FFA870FB37993ED83EB1AE0588184B90D832A64C24C379@looking_glass" --quantity="15" ``` @@ -302,7 +294,7 @@ We will set up an event listener for the block pipeline. From a new terminal tab/window run: ```bash -$ ./iroha events block-pipeline +$ iroha events block-pipeline ``` The output would look like this: @@ -360,7 +352,7 @@ Listening to events with filter: Pipeline(Block(BlockEventFilter { height: None, ``` -Run the help command `./iroha events help` to find out how to listen to other types of events. +Run the help command `iroha events help` to find out how to listen to other types of events. ## What's Next From fec265d9a98b1d356133521d2320837db466d62f Mon Sep 17 00:00:00 2001 From: a-zorina <64249490+a-zorina@users.noreply.github.com> Date: Thu, 8 Aug 2024 13:17:01 +0200 Subject: [PATCH 07/13] Minor post-review fixes Signed-off-by: a-zorina <64249490+a-zorina@users.noreply.github.com> --- README.md | 2 +- src/guide/configure/client-configuration.md | 2 +- src/guide/get-started/index.md | 5 ++--- src/guide/get-started/operate-iroha-via-cli.md | 14 ++++++++------ 4 files changed, 12 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index d86bf276d..d28521fef 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ The tutorial is suitable for both experienced and novice users. It explains Iroh If you are already familiar with Hyperledger Iroha, we invite you to read about [how Iroha 2 is different](https://hyperledger.github.io/iroha-2-docs/guide/iroha-2.html) from its previous version. -Check the [Hyperledger Iroha 2](https://github.com/hyperledger/iroha/) repository for more detailed information about API and available features. +Check the [Hyperledger Iroha](https://github.com/hyperledger/iroha/) repository for more detailed information about API and available features. ## Contribution diff --git a/src/guide/configure/client-configuration.md b/src/guide/configure/client-configuration.md index 06c674a79..53190302b 100644 --- a/src/guide/configure/client-configuration.md +++ b/src/guide/configure/client-configuration.md @@ -18,7 +18,7 @@ $ kagami config client > client-config.json ## Public and Private Keys -The `defaults/client.toml` client 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`. +The `defaults/client.toml` client configuration file should contain the user's `domain` and a pair of their cryptographic keys: `public_key` and `private_key`. For details on cryptographic keys, see [Public Key Cryptography](../security/public-key-cryptography.md). diff --git a/src/guide/get-started/index.md b/src/guide/get-started/index.md index bc5d04824..11c6ec75a 100644 --- a/src/guide/get-started/index.md +++ b/src/guide/get-started/index.md @@ -11,9 +11,8 @@ can: assets - Manage user accounts with a domain hierarchy and multi-signature transactions -- Use efficient portable smart contracts implemented either via - [WebAssembly](/guide/blockchain/wasm.md) or - [Iroha Special Instructions](/guide/blockchain/instructions.md) +- Use efficient portable smart contracts implemented with + [WebAssembly](/guide/blockchain/wasm.md) and [Iroha Special Instructions](/guide/blockchain/instructions.md) - Use both permissioned and permission-less blockchain deployments diff --git a/src/guide/get-started/operate-iroha-via-cli.md b/src/guide/get-started/operate-iroha-via-cli.md index a0156e302..6ecc6eb25 100644 --- a/src/guide/get-started/operate-iroha-via-cli.md +++ b/src/guide/get-started/operate-iroha-via-cli.md @@ -4,7 +4,7 @@ In this tutorial, we will set up and configure the Iroha client CLI, and perform You can learn how to: - register [domains](#_3-register-a-domain) and [accounts](#_4-register-an-account) - - [mint](#_6-register-and-mint-assets), [transfer](#_7-transfer-assets) and [burn](#_8-burn-assets) assets + - [register and mint](#_6-register-and-mint-assets), [transfer](#_7-transfer-assets) and [burn](#_8-burn-assets) assets - [visualize outputs](#_9-visualize-outputs) ## 1. Setup Iroha 2 Client @@ -69,7 +69,7 @@ This is not _persistent configuration_: each time you run `iroha`, you must add ::: -The account specified in the `[account]` section of `client.toml` is preregistered in the blockchain. Only it can interact with the blockchain for now. If you change the keys or the domain of the account in the config file, you should ensure they are preregistered in the blockchain too. +The account specified in the `[account]` section of `client.toml` is preregistered in the default [genesis block](/guide/configure/genesis) of the blockchain. Only it can interact with the blockchain for now. If you change the keys or the domain of the account in the config file, you should ensure they are preregistered in the blockchain too. To check that configuration works, try to run a query, e.g.: @@ -198,9 +198,11 @@ Let's transfer the _looking_glass_ domain to the account we created: $ iroha domain list all ``` -3. Switch to the newly created account. For this, we need to modify the `public_key`, `private_key`, and `domain` in the `client.toml` config file with the ones we registered earlier. +1. Switch to the newly created account. For this, we need to modify the `public_key`, `private_key`, and `domain` in the `client.toml` config file with the credentials of the user we want to act as. + +Note, here the domain of the user we're switching to matches the one we just transferred, but this is not a requirement. A user may be registered in one domain and own multiple others. When setting the domain in the config file, always use the one your user is registered in. - The `account` section of your updated `client.toml` should look like this: +The `account` section of your updated `client.toml` should look like this: ```toml [account] @@ -213,12 +215,12 @@ Let's transfer the _looking_glass_ domain to the account we created: [Permissions](/guide/blockchain/permissions) determine accounts rights within Iroha. Domain owners have the most rights in a domain by default, but permission configuration in Iroha is very flexible and can be customized to your needs. ::: -Now that we control the domain, we can mint assets in it. +Now that we control the domain, we can define and manage assets in it. ## 6. Register and Mint Assets -In order to mint assets, you need to register the [asset definition](/guide/blockchain/assets) first. We are going to register the _tea_ token within the _looking_glass_ network. To do that, run: +To mint an asset, you need to register its [asset definition](/guide/blockchain/assets) first. We are going to register the _tea_ token within the _looking_glass_ network. To do that, run: ```bash $ iroha asset definition register --id="tea#looking_glass" --type="Numeric" From 58d2ff85e565202a0666c905e3723e9dd1a9c110 Mon Sep 17 00:00:00 2001 From: yamkovoy Date: Wed, 28 Aug 2024 08:27:50 +0300 Subject: [PATCH 08/13] Fixes and suggestions after review Signed-off-by: yamkovoy --- src/guide/get-started/index.md | 70 +++++------- src/guide/get-started/install-iroha.md | 92 +++++++-------- src/guide/get-started/launch-iroha.md | 47 ++++---- .../get-started/operate-iroha-via-cli.md | 6 +- src/guide/iroha-2.md | 106 +++++------------- src/guide/support.md | 16 +-- 6 files changed, 128 insertions(+), 209 deletions(-) diff --git a/src/guide/get-started/index.md b/src/guide/get-started/index.md index 11c6ec75a..3b5a02b95 100644 --- a/src/guide/get-started/index.md +++ b/src/guide/get-started/index.md @@ -1,60 +1,50 @@ # Iroha 2 -Iroha is a fully-featured -[blockchain ledger](/reference/glossary.md#blockchain-ledgers). With Iroha you -can: - -- Create and manage custom - [fungible assets](/reference/glossary.md#fungible-assets), such as currencies, - gold, and others -- Create and manage [non-fungible](/reference/glossary.md#non-fungible-assets) - assets -- Manage user accounts with a domain hierarchy and multi-signature - transactions -- Use efficient portable smart contracts implemented with - [WebAssembly](/guide/blockchain/wasm.md) and [Iroha Special Instructions](/guide/blockchain/instructions.md) -- Use both permissioned and permission-less blockchain deployments +Iroha is a fully-featured [blockchain ledger](/reference/glossary.md#blockchain-ledgers). With Iroha you can: +- Create and manage custom [fungible assets](/reference/glossary.md#fungible-assets), such as currencies, gold, etc. +- Create and manage [non-fungible](/reference/glossary.md#non-fungible-assets) assets, such as digital art, intellectual property, etc. +- Manage user accounts with a domain hierarchy and multi-signature transactions. +- Use efficient portable smart contracts implemented with [WebAssembly](/guide/blockchain/wasm.md) and [Iroha Special Instructions](/guide/blockchain/instructions.md). +- Use both permissioned and permissionless blockchain deployments. +## Get Started +If you are just starting with Iroha 2, begin with the following step-by-step tutorials: +1. [Install Iroha](/guide/get-started/install-iroha.md): install prerequisites and clone the GitHub repository. +2. [Launch Iroha](/guide/get-started/launch-iroha.md): install prerequisites and establish an instance of Iroha network. +3. [Operate Iroha via CLI](/guide/get-started/operate-iroha-via-cli.md): learn how to [setup](operate-iroha-via-cli.md#_1-setup-iroha-2-client) and [configure](operate-iroha-via-cli.md#_2-configure-iroha-2-client) Iroha 2 Client, and perform necessary basic operations on the network (e.g., [registering domains](operate-iroha-via-cli.md#_3-register-a-domain) and [accounts](operate-iroha-via-cli.md#_4-register-an-account), [registering and minting assets](operate-iroha-via-cli.md#_6-register-and-mint-assets), etc.). -## Get Started +If you would like to operate Iroha using a different programming language, Iroha 2 provides SDKs and language-specific tutorials for the following languages: +- [Python](/guide/get-started/python.md) +- [Rust](/guide/get-started/rust.md) +- [Kotlin/Java](/guide/get-started/kotlin-java.md) +- [JavaScript (TypeScript)](/guide/get-started/javascript.md) -1. [Install Iroha 2](/guide/get-started/install-iroha.md). -2. [Launch Iroha 2](/guide/get-started/launch-iroha.md). -3. [Learn how to operate Iroha via CLI](/guide/get-started/operate-iroha-via-cli.md) client: set up and - configure Iroha 2, register a domain and an account, register and manage - assets, and visualize outputs. -4. Once familiar with how Iroha works, proceed to the language-specific tutorials to learn how to build software on Iroha: - - [Python](/guide/get-started/python.md) - - [Rust](/guide/get-started/rust.md) - - [Kotlin/Java](/guide/get-started/kotlin-java.md) - - [Javascript (TypeScript)](/guide/get-started/javascript.md) +::: tip +If you have previously worked with Iroha 1, you may want to start with the [Iroha 2 vs. Iroha 1](/guide/iroha-2.md) comparison that will help you understand the improvements and new features in Iroha 2. -If you have previously worked with Iroha, start with our comparison of [Iroha 1 and Iroha 2](/guide/iroha-2.md). It will help you understand the differences between the two versions and upgrade to the newer one. +::: ## Explore In-Depth -Once you've learned the basics, we suggest you read through the following: - - [Security](/guide/security/index.md) section - learn about [core security principles](/guide/security/security-principles.md) and [operational security measures](/guide/security/operational-security.md) that are necessary to ensure the safety and validity of data and assets. This section also covers [cryptographic keys](/guide/security/public-key-cryptography.md), [how to generate them](/guide/security/generating-cryptographic-keys.md), and [how to store them securely](/guide/security/storing-cryptographic-keys.md). - - - Blockchain chapter - find documentation for Iroha features, such as [Iroha Special Instructions](/guide/blockchain/instructions.md), [triggers](/guide/blockchain/triggers.md), [queries](/guide/blockchain/queries.md). +Once you have learned the basics, we suggest exploring the following sections: +- [Security](/guide/security/index.md): find out about [core security principles](/guide/security/security-principles.md) and [operational security measures](/guide/security/operational-security.md) that are necessary to ensure the safety and validity of data and assets. This section also covers [cryptographic keys](/guide/security/public-key-cryptography.md), [how to generate them](/guide/security/generating-cryptographic-keys.md), and [how to store them securely](/guide/security/storing-cryptographic-keys.md). +- Blockchain: learn [how Iroha works](../blockchain/how-iroha-works.md) and find information on key Iroha 2 concepts, including entities, operations, and features, such as [Iroha Special Instructions](/guide/blockchain/instructions.md), [triggers](/guide/blockchain/triggers.md), [queries](/guide/blockchain/queries.md). +- Configuration and Management: discover ways to configure the Iroha 2 network , including [genesis blocks and accounts](/guide/configure/genesis.md), [client configuration](/guide/configure/client-configuration.md), and [public and private modes](/guide/configure/modes.md). - - Configuration and Management section - explore Iroha 2 configuration files in great detail, including topics such as [genesis blocks and accounts](/guide/configure/genesis.md), [client configuration](/guide/configure/client-configuration.md), and [public and private modes](/guide/configure/modes.md). + ## Learn More -For more information on Iroha 2, please take a look at the -[Iroha 2 Whitepaper](https://github.com/hyperledger/iroha/tree/main/docs/source/iroha_2_whitepaper.md), -as well as the Hyperledger Iroha section within the -[Hyperledger Foundation Wiki](https://wiki.hyperledger.org/display/iroha). +For more information on Iroha 2, see the following: +- [Iroha 2 Whitepaper](https://github.com/hyperledger/iroha/tree/main/docs/source/iroha_2_whitepaper.md) +- [Hyperledger Foundation Wiki: Hyperledger Iroha > Iroha 2](https://wiki.hyperledger.org/display/iroha/Iroha+2) -For more information on Iroha 1, take a look at the -[Iroha 1 documentation](https://iroha.readthedocs.io/en/develop/index.html). +For more information on Iroha 1, see the official [Hyperledger Iroha documentation](https://iroha.readthedocs.io/en/develop/index.html). ::: tip -If you want to contribute to Hyperledger Iroha, please look at our -[Contributing Guide](https://github.com/hyperledger/iroha/blob/main/CONTRIBUTING.md). +If you want to contribute to Hyperledger Iroha, see the [Contributing Guide](https://github.com/hyperledger/iroha/blob/main/CONTRIBUTING.md). -::: \ No newline at end of file +::: diff --git a/src/guide/get-started/install-iroha.md b/src/guide/get-started/install-iroha.md index 8acd12c91..7ecae41b4 100644 --- a/src/guide/get-started/install-iroha.md +++ b/src/guide/get-started/install-iroha.md @@ -1,98 +1,98 @@ # Install Iroha 2 -## Install Prerequisites + -To install and build Iroha from GitHub, you need: +## Install Prerequisites +To install and build Iroha from GitHub, the following must be installed: - [git](https://githowto.com/) - [OpenSSL](https://www.openssl.org/) -- [Rust Toolchain](https://www.rust-lang.org/tools/install) +- [Rust Toolchain](https://www.rust-lang.org/tools/install) (v1.60.0 or newer) ### Install OpenSSL -Make sure you have OpenSSL installed. Note that in most Linux setups it is already available to you. +Depending on your operating system, perform one of the following: -- Install OpenSSL on Ubuntu: +- On Ubuntu, run: ```bash $ sudo apt-get install libssl-dev ``` -- Install OpenSSL on macOS using [brew](https://brew.sh/): +- Using [brew](https://brew.sh/) on macOS, run: ```bash $ brew install openssl ``` -Check the [OpenSSL installation guide](https://github.com/openssl/openssl/blob/master/INSTALL.md) for details. +::: tip Note +In most UNIX-based distributions, the OpenSSL library comes preinstalled. -### Install the Rust Toolchain +::: -You need [a working Rust toolchain]: `cargo`, `rustc` v1.60 and up. [^1] +::: info -[^1]: - If you're having issues installing Rust compatible with our code - (2021 edition), please consult the - [troubleshooting](/guide/troubleshooting/installation-issues#troubleshooting-rust-toolchain) section. +For details on all installation methods, troubleshooting and other related information, see [OpenSSL: Build and Install](https://github.com/openssl/openssl/blob/master/INSTALL.md). +::: -The easiest way to get the official `rustup` script is to run: +### Install the Rust Toolchain + +The recommended way to install the Rust toolchain is through the Rust installer and version management tool—[Rustup](https://rust-lang.github.io/rustup/) (See also: [Install Rust](https://www.rust-lang.org/tools/install))—by executing the following command in your terminal: ```bash $ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh ``` -You will be guided through the setup process. Just go with the defaults. - -## Clone Iroha from GitHub - - +Once executed, follow the on-screen instructions to finish installation. +::: tip Note -1. If you haven’t already, you might want to create a clean directory for - Iroha 2, to keep things tidy. +If you are experiencing issues installing Rust compatible with our code (2021 edition), see [Troubleshooting Rust Toolchain](/guide/troubleshooting/installation-issues#troubleshooting-rust-toolchain). - ```bash - $ mkdir -p ~/Git - ``` +::: - ::: tip - - On macOS, if you get - `fatal: could not create work tree dir 'iroha': Read-only file system`, - that’s because the home directory is not a real file system. The fix is to - create the `Git` directory. - - ::: +## Clone Iroha from GitHub -2. Enter the directory you have just created using + - ```bash - $ cd ~/Git - ``` +1. Create a new directory for Iroha 2: -3. Then `clone` the Iroha git repository into the directory `~/Git/iroha` + ```bash + $ mkdir -p ~/Git + ``` - ```bash - $ git clone https://github.com/hyperledger/iroha.git - ``` + ::: tip -### Install Iroha 2 Binaries + On macOS, if you get the `fatal: could not create work tree dir 'iroha': Read-only file system` error, that is because the home directory is not a real file system. + The solution is to create a directory named `Git`. -To install the necessary binaries system-wide, use the following commands: + ::: +2. Enter the directory that you created: ```bash - $ cargo install --git https://github.com/hyperledger/iroha.git iroha + $ cd ~/Git ``` +3. Clone the [`iroha`](https://github.com/hyperledger/iroha) GitHub repository: + ```bash - $ cargo install --git https://github.com/hyperledger/iroha.git kagami + $ git clone https://github.com/hyperledger/iroha.git ``` +### Install Iroha 2 Binaries + + + +To install any of the standalone Iroha 2 binaries system-wide, use the following commands: -## What's Next +```bash +$ cargo install --git https://github.com/hyperledger/iroha.git iroha +``` -- [Launch Iroha Network](./launch-iroha.md) +```bash +$ cargo install --git https://github.com/hyperledger/iroha.git kagami +``` diff --git a/src/guide/get-started/launch-iroha.md b/src/guide/get-started/launch-iroha.md index eb2817057..269081d4c 100644 --- a/src/guide/get-started/launch-iroha.md +++ b/src/guide/get-started/launch-iroha.md @@ -1,55 +1,50 @@ -# Launch Iroha +# Launch Iroha 2 + +Once you have Iroha 2 installed on your machine, you are ready to set up an instance of the Iroha 2 network. + +To do so, perform the following steps: 1. Install the prerequisites: - [Docker](https://docs.docker.com/get-docker/) - - [Docker compose](https://docs.docker.com/compose/) + - [Docker Compose](https://docs.docker.com/compose/) 2. [Install Iroha](./install-iroha.md). -3. Navigate to the repository root directory. - -4. Run `docker compose` and specify the network configuration file to bring up a network of 4 containerized peers: +3. Navigate to the local repository root directory. + +4. Run the `docker compose` command with the `docker-compose.yml` network configuration file specified to deploy a network of four containerized peers: ```bash $ docker compose -f defaults/docker-compose.yml up ``` - Depending on your set-up, this might either - [pull the image](https://hub.docker.com/r/hyperledger/iroha2/tags) from DockerHub, or build the container locally. After this process - completes, you'll receive the following output: + Depending on your setup, this might either [pull the image](https://hub.docker.com/r/hyperledger/iroha2/tags) from Docker Hub or build the container locally.\ + Once the process is complete, an output similar to the following is generated: <<< @/guide/get-started/launch-iroha.docker-compose-output.ansi -5. Proceed to the [CLI tutorial](./operate-iroha-via-cli.md) to check out Iroha's capabilities. +Once the network is deployed, it is possible to interact with it using Iroha Client CLI. -6. When you're done with the test network, just hit `Control + C` to stop the - containers (`⌃ + C` on Mac). +To discover its capabilities and learn to perform some of the basic operations, see [Operate Iroha via CLI](./operate-iroha-via-cli.md). ::: tip - You can monitor blockchain events in the terminal where the test network runs. - +You can monitor blockchain events in the terminal where the test network runs. + ::: + ## Docker Options -You might also be interested in other options for local compilation: +The following options are also available for local compilation: -- To test Iroha code quickly, you can use `docker-compose-single.yml`, - which starts a container with a single peer. -- For testing Iroha code in normal conditions, you can use - `docker-compose-local.yml`, which starts 4 connected containers with - peers. +- To test Iroha code quickly, use `docker-compose-single.yml`, which starts a container with a single peer. +- To test Iroha code in normal conditions, you can use `docker-compose-local.yml`, which starts four connected containers with peers. -::: info +::: tip Note -Please note that there is ongoing work to make our configurations for -Docker even more customizable with the help of Swarm. +There is ongoing work to make our configurations for Docker even more customizable with the help of Swarm. ::: - -## What's Next - -Now that you have Iroha up and running, proceed to the [CLI tutorial](/guide/get-started/operate-iroha-via-cli) to learn how to work with it. \ No newline at end of file diff --git a/src/guide/get-started/operate-iroha-via-cli.md b/src/guide/get-started/operate-iroha-via-cli.md index 6ecc6eb25..106cdc5d2 100644 --- a/src/guide/get-started/operate-iroha-via-cli.md +++ b/src/guide/get-started/operate-iroha-via-cli.md @@ -9,7 +9,7 @@ You can learn how to: ## 1. Setup Iroha 2 Client -Ensure you [installed Iroha](./install-iroha.md) and [brought up the test network](./launch-iroha.md). +Ensure you [installed Iroha](./install-iroha.md) and [brought up the test network](./launch-iroha.md). Create a fresh directory and copy the `client.toml` configuration file there: @@ -199,7 +199,7 @@ Let's transfer the _looking_glass_ domain to the account we created: ``` 1. Switch to the newly created account. For this, we need to modify the `public_key`, `private_key`, and `domain` in the `client.toml` config file with the credentials of the user we want to act as. - + Note, here the domain of the user we're switching to matches the one we just transferred, but this is not a requirement. A user may be registered in one domain and own multiple others. When setting the domain in the config file, always use the one your user is registered in. The `account` section of your updated `client.toml` should look like this: @@ -358,4 +358,4 @@ Run the help command `iroha events help` to find out how to listen to other type ## What's Next -Now that you know the basics, you can proceed to one of our language-specific [turorials](/guide/get-started/tutorials) to learn how to build on Iroha. \ No newline at end of file +Now that you know the basics, you can proceed to one of our language-specific [turorials](/guide/get-started/tutorials) to learn how to build on Iroha. diff --git a/src/guide/iroha-2.md b/src/guide/iroha-2.md index 82d5863d9..af8fd3833 100644 --- a/src/guide/iroha-2.md +++ b/src/guide/iroha-2.md @@ -1,140 +1,84 @@ # Iroha 2 vs. Iroha 1 -Iroha 2 is a **complete** re-write of -[Hyperledger Iroha](https://iroha.readthedocs.io/en/develop/index.html) in -Rust. As of writing, the two projects are developed concurrently. + -In this introduction we outline the differences between the two versions of -Iroha and highlight the new features of Iroha 2. It should be of particular -interest to those who are already familiar with Iroha but wish to upgrade -and start using the newer version. +Iroha 2 is a **complete** rewrite of [Hyperledger Iroha](https://iroha.readthedocs.io/en/develop/index.html) in Rust. As of writing, the two projects are developed concurrently. -::: info +In this introduction we outline the differences between the two versions of Iroha and highlight the new features of Iroha 2. It should be of particular interest to those who are already familiar with Iroha but wish to upgrade and start using the newer version. + +::: tip Note -Note that Iroha 1 and Iroha 2 are not compatible. Both projects are very -different in their approaches and implementations as we present in the -comparison below. +Iroha 1 and Iroha 2 are not compatible. Both projects are very different in their approaches and implementations as evident from the comparisons below. -Among other changes, cryptography and account structures are implemented -differently, meaning that users would have to generate new keys and link to -their old account through a centralized service and no data from Iroha 1 -would be accessible from Iroha 2. +Among other changes, cryptography and account structures are implemented differently, meaning that users would have to generate new keys and link their new account with the old one through a centralized service, and no data from Iroha 1 would be accessible from Iroha 2. ::: ## Fault Tolerance -Iroha 2 learned a great deal from the development of the original Iroha. Of -particular importance is the new and improved Byzantine-fault-tolerant -consensus algorithm: -[_Sumeragi_](https://github.com/hyperledger/iroha/tree/main/docs/source/iroha_2_whitepaper.md#28-consensus). -This new consensus allowed us to expand what could be done on a blockchain -without any security risks. +Iroha 2 learned a great deal from the development of the original Iroha. Of particular importance is the new and improved Byzantine-fault-tolerant consensus algorithm—[_Sumeragi_](https://github.com/hyperledger/iroha/tree/main/docs/source/iroha_2_whitepaper.md#28-consensus)—that allowed us to expand what could be done on a blockchain without any security risks. ::: info -The first version of Iroha used a consensus algorithm called _Yac_. _Yac_ -is _crash-fault-tolerant_, which means that it can survive a set number of -nodes _crashing_: i.e. losing power, being cut off from the network, or -being destroyed with a sledgehammer. +Iroha 1 uses a consensus algorithm called _Yac_. _Yac_ is _crash-fault-tolerant_, which means that it can survive a set number of nodes crashing, i.e., losing power, being cut off from the network, or being destroyed with a sledgehammer. -_Sumeragi_, by contrast, was designed to be _Byzantine-fault-tolerant_. -This means that Iroha 2 can tolerate not only peers being inactive on the -network, but also running malicious software and actively trying to falsify -data in the blockchain. +_Sumeragi_, by contrast, was designed to be _Byzantine-fault-tolerant_. This means that Iroha 2 can tolerate not only peers being inactive on the network, but also running malicious software and actively trying to falsify data in the blockchain. -We can mathematically prove that Iroha 2 can work when **up to 33%** of its -nodes are actively trying to stop Iroha 2 from working properly or at all. -In other words, even if someone gained control of a _third_ of all of your -network nodes, an Iroha 2 deployment is _mathematically guaranteed_ to keep -working. +We can mathematically prove that Iroha 2 can work when **up to 33%** of its nodes are actively trying to stop Iroha 2 from working properly or at all. In other words, even if someone gained control of a _third_ of all of your network nodes, an Iroha 2 deployment is _mathematically guaranteed_ to keep working. ::: ## Minimalist Code Base -Iroha 2 is a minimalist code base. We take great care to vet our -dependencies and avoid large inter-dependent chunks of code. +Iroha 2 utilizes a minimalist code base. We take great care to vet our dependencies and avoid large interdependent chunks of code. -We provide a few telemetry APIs, including `prometheus` tooling, structured -logging in JSON, as well as compatibility with standard tools used in -Parity Substrate. +We provide a few telemetry APIs, including `prometheus` tooling, structured logging in JSON, as well as compatibility with standard tools used in Parity Substrate. -Our data is strongly-typed, our methods are statically dispatched. We make -use of the best that Rust has to offer: `serde` and `parity_scale_codec` -for serialisation, `tokio` for co-operative multi-threading, as well as -testing, bench-marking, static analysis and code auditing tools that come -packaged with the exemplary `cargo`. +Our data is strongly-typed, our methods are statically dispatched. We make use of the best that Rust has to offer: `serde` and `parity_scale_codec` for serialisation, `tokio` for co-operative multi-threading, as well as testing, bench-marking, static analysis and code auditing tools that come packaged with the exemplary `cargo`. -Our code is easy to reason about, and quick to compile, whilst also being -ergonomic to use and thoughtfully crafted. We have no `panics` and no -`unsafe` code. +Our code is easy to reason about, and quick to compile, whilst also being ergonomic to use and thoughtfully crafted. We have no `panics` and no `unsafe` code. ## Flexibility -Iroha 2 is also more flexible than the original Iroha due to its modular -design. +Iroha 2 is also more flexible than the original Iroha due to its modular design. -It is possible to add or remove features based on a particular use-case. If -you want the blockchain to be extremely fast and work on embedded hardware, -just compile Iroha 2 without the `expensive-metrics` feature. Don't use -telemetry at all? Remove it entirely and enjoy even more performance. -_Permission_ sets are plugins that can be upgraded during run-time. +It is possible to add or remove features based on a particular use-case. If you want the blockchain to be extremely fast and work on embedded hardware, just compile Iroha 2 without the expensive `metrics` feature. Don't use telemetry at all? Remove it entirely and enjoy even more performance. _Permission_ sets are plugins that can be upgraded during run-time. -We have an extensive module system as well as a robust WASM runtime -framework. +We have an extensive module system as well as a robust WASM runtime framework. ## Smart Contracts -Iroha 2 is an event-driven ledger. Each change in the state of the -blockchain is necessarily accompanied by its own event that can _trigger_ a -smart contract: complex logic designed for use in on-chain scripting. +Iroha 2 is an event-driven ledger. Each change in the state of the blockchain is necessarily accompanied by its own event that can _trigger_ a smart contract: complex logic designed for use in on-chain scripting. For smart contracts, Iroha 2 supports two approaches: - [Iroha Special Instructions (ISI)](./blockchain/instructions.md) - [Web ASseMbly (WASM)](./blockchain/wasm.md) -The first approach is useful when you want very simple transparent logic -and also want to minimise the footprint in the blockchain. All interactions -with the _World state_, that is, the state of the blockchain at this point -in time, has to be done using the aforementioned instructions. There is -also rudimentary support for domain-specific conditional logic. +The first approach is useful when you want very simple transparent logic and also want to minimize the footprint in the blockchain. All interactions with the _World state_, that is, the state of the blockchain at any given point in time, has to be done using the aforementioned instructions. There is also rudimentary support for domain-specific conditional logic. -If you want to learn more about smart contracts in Iroha 2, please consult -our -[Wiki](https://wiki.hyperledger.org/display/iroha/Scripting+Languages+and+Runtimes+for+Iroha2+Smart+Contracts). +If you want to learn more about smart contracts in Iroha 2, please consult our [Wiki](https://wiki.hyperledger.org/display/iroha/Scripting+Languages+and+Runtimes+for+Iroha2+Smart+Contracts). ## Static and Dynamic Linking -Iroha 2 smartly chooses when to use dynamic linking. This strikes a balance -between it being easy to patch a Critical security vulnerability in a -vendored library like OpenSSL, but also remaining reproducible and portable -across platforms, architectures, and deployments. +Iroha 2 smartly chooses when to use dynamic linking. This strikes a balance between it being easy to patch a critical security vulnerability in a vendored library like OpenSSL, but also remaining reproducible and portable across platforms, architectures, and deployments. ::: info -You get the best of both worlds. Patching a security vulnerability is as -easy as running `sudo apt upgrade`. On the other hand, only -security-critical dependencies are linked dynamically, so it is highly -unlikely that any of the smaller and less important libraries can break -Iroha after an upgrade. +You get the best of both worlds. Patching a security vulnerability is as easy as running `sudo apt upgrade`. On the other hand, only security-critical dependencies are linked dynamically, so it is highly unlikely that any of the smaller and less important libraries can break Iroha after an upgrade. ::: ## Testing -Iroha 2 is extensively tested. Despite being in active development, Iroha -has 80% line coverage. Keep in mind that line coverage includes -documentation comments, some of which are also tests. +Iroha 2 is extensively tested. Despite being in active development, Iroha has 80% line coverage. Keep in mind that line coverage includes documentation comments, some of which are also tests. ::: info -There are plans to include Fuzz testing, property-based testing, and -failure-point testing to ensure that Iroha is reliable. +There are plans to include Fuzz testing, property-based testing, and failure-point testing to ensure that Iroha is reliable. ::: diff --git a/src/guide/support.md b/src/guide/support.md index 529ebcf91..bcf14c512 100644 --- a/src/guide/support.md +++ b/src/guide/support.md @@ -1,17 +1,7 @@ # Receive support -From time to time, you may have questions about Iroha that you would like -to discuss in detail with others. There are three ways to quickly get in -touch with our community: Telegram, Discord, and GitHub. +From time to time, you may have questions about Iroha that you would like to discuss in detail with others. There are three ways to quickly get in touch with our community: Telegram, Discord, and GitHub. -A large part of the community currently uses -[Telegram](https://t.me/hyperledgeriroha) for communication. The -Hyperledger part of the team prefers -[Discord](https://discord.gg/hyperledger), with two dedicated channels: -`iroha` and `iroha-2-contributors`. The Discord and Telegram channels are -synchronized, so users of both media see your messages. +A large part of the community currently uses [Telegram](https://t.me/hyperledgeriroha) for communication. The Hyperledger part of the team prefers [Discord](https://discord.gg/hyperledger), with two dedicated channels: `iroha` and `iroha-2-contributors`. The Discord and Telegram channels are synchronized, so users of both media see your messages. -Finally, you can -[create a GitHub issue](https://github.com/hyperledger/iroha/issues/new/choose), -whether it's a request to update documentation, a suggestion for the core -team, or a bug you have found. +Finally, you can [create a GitHub issue](https://github.com/hyperledger/iroha/issues/new/choose), whether it's a request to update documentation, a suggestion for the core team, or a bug you have found. From b6275be0afd8fb696d1399f5f950cb42d68adef4 Mon Sep 17 00:00:00 2001 From: yamkovoy Date: Fri, 30 Aug 2024 12:42:25 +0300 Subject: [PATCH 09/13] Changes after discussion Signed-off-by: yamkovoy --- src/guide/get-started/install-iroha.md | 50 +---------- src/guide/get-started/launch-iroha.md | 29 ++++--- .../get-started/operate-iroha-via-cli.md | 83 ++++++++++--------- 3 files changed, 61 insertions(+), 101 deletions(-) diff --git a/src/guide/get-started/install-iroha.md b/src/guide/get-started/install-iroha.md index 7ecae41b4..434f66c5f 100644 --- a/src/guide/get-started/install-iroha.md +++ b/src/guide/get-started/install-iroha.md @@ -1,58 +1,14 @@ -# Install Iroha 2 +# Install Iroha -## Install Prerequisites +## Prerequisites -To install and build Iroha from GitHub, the following must be installed: +To install and build Iroha from GitHub, the following must be installed first: - [git](https://githowto.com/) - [OpenSSL](https://www.openssl.org/) - [Rust Toolchain](https://www.rust-lang.org/tools/install) (v1.60.0 or newer) -### Install OpenSSL - -Depending on your operating system, perform one of the following: - -- On Ubuntu, run: - - ```bash - $ sudo apt-get install libssl-dev - ``` - -- Using [brew](https://brew.sh/) on macOS, run: - - ```bash - $ brew install openssl - ``` - -::: tip Note - -In most UNIX-based distributions, the OpenSSL library comes preinstalled. - -::: - -::: info - -For details on all installation methods, troubleshooting and other related information, see [OpenSSL: Build and Install](https://github.com/openssl/openssl/blob/master/INSTALL.md). - -::: - -### Install the Rust Toolchain - -The recommended way to install the Rust toolchain is through the Rust installer and version management tool—[Rustup](https://rust-lang.github.io/rustup/) (See also: [Install Rust](https://www.rust-lang.org/tools/install))—by executing the following command in your terminal: - -```bash -$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -``` - -Once executed, follow the on-screen instructions to finish installation. - -::: tip Note - -If you are experiencing issues installing Rust compatible with our code (2021 edition), see [Troubleshooting Rust Toolchain](/guide/troubleshooting/installation-issues#troubleshooting-rust-toolchain). - -::: - ## Clone Iroha from GitHub diff --git a/src/guide/get-started/launch-iroha.md b/src/guide/get-started/launch-iroha.md index 269081d4c..c7325960c 100644 --- a/src/guide/get-started/launch-iroha.md +++ b/src/guide/get-started/launch-iroha.md @@ -1,25 +1,28 @@ # Launch Iroha 2 -Once you have Iroha 2 installed on your machine, you are ready to set up an instance of the Iroha 2 network. +Once you have Iroha 2 installed on your machine, you are ready to set up an instance of the Iroha network. -To do so, perform the following steps: +## Prerequisites -1. Install the prerequisites: +To launch an instance of the Iroha network, the following must be installed first: +- [Docker](https://docs.docker.com/get-docker/) +- [Docker Compose](https://docs.docker.com/compose/install/) - - [Docker](https://docs.docker.com/get-docker/) - - [Docker Compose](https://docs.docker.com/compose/) +## Launch Iroha Network -2. [Install Iroha](./install-iroha.md). +1. In your terminal, navigate to the root directory of your local [`iroha`](https://github.com/hyperledger/iroha) repository: -3. Navigate to the local repository root directory. + ```bash + $ cd ~/Git/iroha + ``` -4. Run the `docker compose` command with the `docker-compose.yml` network configuration file specified to deploy a network of four containerized peers: +2. Run the `docker compose` command with the `docker-compose.yml` network configuration file specified to deploy a network of four containerized peers: ```bash $ docker compose -f defaults/docker-compose.yml up ``` - Depending on your setup, this might either [pull the image](https://hub.docker.com/r/hyperledger/iroha2/tags) from Docker Hub or build the container locally.\ + Depending on your setup, this might either pull an image from [Docker Hub]((https://hub.docker.com/r/hyperledger/iroha2/tags)) or build the container locally.\ Once the process is complete, an output similar to the following is generated: <<< @/guide/get-started/launch-iroha.docker-compose-output.ansi @@ -30,16 +33,16 @@ To discover its capabilities and learn to perform some of the basic operations, ::: tip -You can monitor blockchain events in the terminal where the test network runs. +You can monitor blockchain events in the terminal where the network runs. ::: -## Docker Options +### Docker Options The following options are also available for local compilation: -- To test Iroha code quickly, use `docker-compose-single.yml`, which starts a container with a single peer. -- To test Iroha code in normal conditions, you can use `docker-compose-local.yml`, which starts four connected containers with peers. +- To test Iroha code quickly, use the `docker-compose-single.yml` network configuration file, which starts a container with a single peer. +- To test Iroha code in normal conditions, use the `docker-compose-local.yml` network configuration file, which starts four connected containers with peers. ::: tip Note diff --git a/src/guide/get-started/operate-iroha-via-cli.md b/src/guide/get-started/operate-iroha-via-cli.md index 106cdc5d2..a65b89d39 100644 --- a/src/guide/get-started/operate-iroha-via-cli.md +++ b/src/guide/get-started/operate-iroha-via-cli.md @@ -1,61 +1,62 @@ # Operate Iroha via CLI -In this tutorial, we will set up and configure the Iroha client CLI, and perform some basic actions on the Iroha blockchain with it. +Most of the operations with an Iroha network can be performed via the Iroha Client CLI. This tutorial aims to help you set it up and configure, and then perform some of the basic operations with the network. -You can learn how to: - - register [domains](#_3-register-a-domain) and [accounts](#_4-register-an-account) - - [register and mint](#_6-register-and-mint-assets), [transfer](#_7-transfer-assets) and [burn](#_8-burn-assets) assets - - [visualize outputs](#_9-visualize-outputs) +For quick access to an operation that interests you, use the **On this page** menu. -## 1. Setup Iroha 2 Client +## 1. Set Up Iroha Client CLI -Ensure you [installed Iroha](./install-iroha.md) and [brought up the test network](./launch-iroha.md). +::: info -Create a fresh directory and copy the `client.toml` configuration file there: +To set up the Iroha Client CLI, an instance of the Iroha network must be [launched and operational](./launch-iroha.md). + +::: + +Create a new directory and copy the `client.toml` configuration file there: ```bash -$ cp path_to_iroha_repo/defaults/client.toml path_to_created_directory/ +$ cp path_to_iroha_repo/defaults/client.toml path_to_new_directory/ ``` -## 2. Configure Iroha 2 Client +## 2. Configure Iroha Client CLI -Navigate to the directory with the configuration file in your terminal. +1. Navigate to the directory with the copied `client.toml` configuration file. -Run the client CLI: +2. Run the Iroha Client CLI: -```bash -$ iroha -``` + ```bash + $ iroha + ``` -::: details Expand to see the expected output + ::: details Expected output -```bash -Iroha CLI Client lets you interact with Iroha Peers Web API without direct network usage - -Usage: iroha [OPTIONS] - -Commands: - domain The subcommand related to domains - account The subcommand related to accounts - asset The subcommand related to assets - peer The subcommand related to p2p networking - events The subcommand related to event streaming - wasm The subcommand related to Wasm - blocks The subcommand related to block streaming - json The subcommand related to multi-instructions as Json or Json5 - help Print this message or the help of the given subcommand(s) - -Options: - -c, --config Path to the configuration file [default: client.toml] - -v, --verbose More verbose output - -h, --help Print help - -V, --version Print version + ```bash + Iroha CLI Client lets you interact with Iroha Peers Web API without direct network usage -``` + Usage: iroha [OPTIONS] -::: + Commands: + domain The subcommand related to domains + account The subcommand related to accounts + asset The subcommand related to assets + peer The subcommand related to p2p networking + events The subcommand related to event streaming + wasm The subcommand related to Wasm + blocks The subcommand related to block streaming + json The subcommand related to multi-instructions as Json or Json5 + help Print this message or the help of the given subcommand(s) + + Options: + -c, --config Path to the configuration file [default: client.toml] + -v, --verbose More verbose output + -h, --help Print help + -V, --version Print version + + ``` + + ::: -By default, the Iroha client searches for its configuration in the `client.toml` file located in the current working directory. We already copied it there, so we're all set. +By default, the Iroha Client searches for a configuration in the `client.toml` file located in its current working directory. We already copied it there, so we're all set. ::: tip @@ -114,7 +115,7 @@ With a domain available, it is time to register an account in it. To register a new account, you need a cryptographic key pair consisting of a _public_ and a _private_ key. You will use it to establish a secure communication channel between yourself and the network. -For users' convenience, Iroha 2 comes with `kagami`, an in-built key generator tool. To generate a new key pair with `kagami`, run the following command: +For users' convenience, Iroha comes with `kagami`, a built-in key generator tool. To generate a new key pair with `kagami`, run the following command: ```bash $ kagami crypto From 28e65b498ae4713c6287646e280860d3e89f8952 Mon Sep 17 00:00:00 2001 From: yamkovoy Date: Sun, 1 Sep 2024 21:21:34 +0300 Subject: [PATCH 10/13] Minor tweaks in instructions Signed-off-by: yamkovoy --- .../get-started/operate-iroha-via-cli.md | 101 +++++++++++------- 1 file changed, 61 insertions(+), 40 deletions(-) diff --git a/src/guide/get-started/operate-iroha-via-cli.md b/src/guide/get-started/operate-iroha-via-cli.md index a65b89d39..ccf9d7fe2 100644 --- a/src/guide/get-started/operate-iroha-via-cli.md +++ b/src/guide/get-started/operate-iroha-via-cli.md @@ -66,13 +66,13 @@ To run any of the Iroha client commands with some other configuration file, use $ iroha --config path/to/client.toml ``` -This is not _persistent configuration_: each time you run `iroha`, you must add the `--config path/to/client.toml` command-line argument, unless you put the `client.toml` config file in your working directory. +This is a _non-persistent configuration_: each time you run `iroha`, you must add the `--config path/to/client.toml` command-line argument, unless the `client.toml` config file is in the working directory. ::: -The account specified in the `[account]` section of `client.toml` is preregistered in the default [genesis block](/guide/configure/genesis) of the blockchain. Only it can interact with the blockchain for now. If you change the keys or the domain of the account in the config file, you should ensure they are preregistered in the blockchain too. +The account specified in the `[account]` section of `client.toml` is preregistered in the default [genesis block](/guide/configure/genesis) of the blockchain. Only it can interact with the blockchain for now. If you change the keys or the domain of the account in the configuration file, make sure that they are preregistered on the blockchain too. -To check that configuration works, try to run a query, e.g.: +To check that a configuration works, run the following query: ```bash $ iroha domain list all @@ -80,23 +80,29 @@ $ iroha domain list all The output should contain several preregistered domains. + + ## 3. Register a Domain -To get started, you must first register a domain: +::: info + +A _domain_ is a group of entities like asset definitions, accounts, and other objects grouped logically. These are described in greater detail in the [Blockchain](TODO) section of the documentation. + +::: + +To register a new domain, run: ```bash $ iroha domain register --id="looking_glass" ``` -A _domain_ is a group of entities like asset definitions, accounts, and other objects grouped logically. We'll talk about it in more detail in other documentation sections. - -You will receive a confirmation message. However, the new domain details will not be directly readable in that message. To confirm that you created the new _looking_glass_ domain successfully, run: +Once executed, a confirmation message appears. However, since the details of the new domain are not directly readable in that message, to confirm that you have successfully created the new `looking_glass` domain, run: ```bash $ iroha domain list all ``` -The output should contain the _looking_glass_ domain: +::: details Expected output ```json { @@ -107,7 +113,9 @@ The output should contain the _looking_glass_ domain: }, ``` -Note, the owner of the new domain is the account specified in our config file. They performed the registration. +Note that the owner of the new domain is the account specified in our config file. They performed the registration. + +::: With a domain available, it is time to register an account in it. @@ -129,14 +137,14 @@ To learn more about generating cryptographic keys with `kagami`, available algor ::: -For the purposes of this tutorial, we will use the following key pair: +For the purposes of this tutorial, we iuse the following key pair: ```bash Public key (multihash): "ed0120ABA0446CFBD4E12627FFA870FB37993ED83EB1AE0588184B90D832A64C24C379" Private key (multihash): "802620CBD3D701B561FE98463767729176404DC757D690F78980B8FDD40C171CCB8EB5" ``` -To register a new account within the _looking_glass_ domain, run: +To register a new account within the `looking_glass` domain, run: ```bash $ iroha account register --id="ed0120ABA0446CFBD4E12627FFA870FB37993ED83EB1AE0588184B90D832A64C24C379@looking_glass" @@ -144,13 +152,13 @@ $ iroha account register --id="ed0120ABA0446CFBD4E12627FFA870FB37993ED83EB1AE058 The `--id` argument in the above code snippet specifies the _account id_, the unique identifier of the account. It consists of the user public key (generated using `kagami`) and the domain it is associated with. -If the account registration succeeds, you will receive a confirmation message. Like before, you should query the accounts to verify the details. +If the account registration is successful, you receive a confirmation message. Similar to the domain registration, to confirm that you have successfully created a new account within the `looking_glass` domain, run: ```bash $ iroha account list all ``` -::: details Expand to see the expected output +::: details Expected result ```json [ @@ -184,33 +192,40 @@ $ iroha account list all ## 5. Transfer a Domain -We could change the keys and domain in `client.toml` at this point and continue working with the account we just created, but we wouldn't be able to do much in the _looking_glass_ domain, as our new account is not the owner of _looking_glass_, and cannot manage it. + + +We could change the keys and domain in `client.toml` at this point and continue working with the account we just created, but we wouldn't be able to do much in the `looking_glass` domain, as our new account is not the owner of thw `looking_glass` domain, and therefore cannot manage it. -Let's transfer the _looking_glass_ domain to the account we created: +To transfer an account from under the `wonderland` domain to the `looking_glass` domain, perform the following: 1. Run the transfer command: - ```bash - $ iroha domain transfer --id="looking_glass" --from "ed0120CE7FA46C9DCE7EA4B125E2E36BDB63EA33073E7590AC92816AE1E861B7048B03@wonderland" --to "ed0120ABA0446CFBD4E12627FFA870FB37993ED83EB1AE0588184B90D832A64C24C379@looking_glass" - ``` + ```bash + $ iroha domain transfer --id="looking_glass" --from "ed0120CE7FA46C9DCE7EA4B125E2E36BDB63EA33073E7590AC92816AE1E861B7048B03@wonderland" --to "ed0120ABA0446CFBD4E12627FFA870FB37993ED83EB1AE0588184B90D832A64C24C379@looking_glass" + ``` + 2. Check that the ownership changed: - ```bash - $ iroha domain list all - ``` + ```bash + $ iroha domain list all + ``` 1. Switch to the newly created account. For this, we need to modify the `public_key`, `private_key`, and `domain` in the `client.toml` config file with the credentials of the user we want to act as. -Note, here the domain of the user we're switching to matches the one we just transferred, but this is not a requirement. A user may be registered in one domain and own multiple others. When setting the domain in the config file, always use the one your user is registered in. +Note that here the domain of the user that we are switching to matches the one we just transferred. However, this is not a requirement. A user may be registered in one domain and own multiple others. When setting the domain in the configuration file, always use the one that your user is registered with. -The `account` section of your updated `client.toml` should look like this: +::: details Expected result - ```toml - [account] - domain = "looking_glass" - public_key = "ed0120ABA0446CFBD4E12627FFA870FB37993ED83EB1AE0588184B90D832A64C24C379" - private_key = "802620CBD3D701B561FE98463767729176404DC757D690F78980B8FDD40C171CCB8EB5" - ``` +The `account` section of your updated `client.toml` file: + +```toml +[account] +domain = "looking_glass" +public_key = "ed0120ABA0446CFBD4E12627FFA870FB37993ED83EB1AE0588184B90D832A64C24C379" +private_key = "802620CBD3D701B561FE98463767729176404DC757D690F78980B8FDD40C171CCB8EB5" +``` + +::: ::: tip [Permissions](/guide/blockchain/permissions) determine accounts rights within Iroha. Domain owners have the most rights in a domain by default, but permission configuration in Iroha is very flexible and can be customized to your needs. @@ -218,32 +233,33 @@ The `account` section of your updated `client.toml` should look like this: Now that we control the domain, we can define and manage assets in it. - ## 6. Register and Mint Assets -To mint an asset, you need to register its [asset definition](/guide/blockchain/assets) first. We are going to register the _tea_ token within the _looking_glass_ network. To do that, run: +To mint an asset, its [asset definition](/guide/blockchain/assets) must be registered first. + +To register a `tea` token within the `looking_glass` domain, run: ```bash $ iroha asset definition register --id="tea#looking_glass" --type="Numeric" ``` -The Numeric _tea_ asset is now registered within the _looking_glass_ domain. +The numeric `tea` asset is now registered within the `looking_glass` domain. If you open the terminal where the Iroha network runs, you will see that all our activity caused numerous pipeline events there. -To mint _tea_ tokens run: +To mint `tea` tokens run: ```bash $ iroha asset mint --id="tea##ed0120ABA0446CFBD4E12627FFA870FB37993ED83EB1AE0588184B90D832A64C24C379@looking_glass" --quantity="100" ``` -After minting one hundred _tea_, you will see more pipeline events in the logger, and you can also query the assets that you have just minted: +After minting one hundred `tea`, more pipeline events are expected, and you can also query the assets that you have just minted: ```bash $ iroha asset list all ``` -::: details Expand to see the expected output +::: details Expected result ```json [ @@ -272,7 +288,7 @@ $ iroha asset list all ## 7. Transfer Assets -After minting the assets, you can transfer some of your tea to another account: +After minting the assets, you can transfer some of your `tea` to another account: ```bash $ iroha asset transfer --to="ed0120CE7FA46C9DCE7EA4B125E2E36BDB63EA33073E7590AC92816AE1E861B7048B03@wonderland" --id="tea##ed0120ABA0446CFBD4E12627FFA870FB37993ED83EB1AE0588184B90D832A64C24C379@looking_glass" --quantity=33 @@ -289,8 +305,7 @@ $ iroha asset burn --id="tea##ed0120ABA0446CFBD4E12627FFA870FB37993ED83EB1AE0588 ## 9. Visualize Outputs -Although you will get a constant data feed of the network within the terminal running `docker compose`, you can also configure an output to listen -to events of several types on the network: blocks generation, transactions, data events and triggers. +Although you will get a constant data feed of the network within the terminal running `docker compose`, you can also configure an output to listen to events of several types on the network: blocks generation, transactions, data events and triggers. We will set up an event listener for the block pipeline. @@ -300,7 +315,7 @@ From a new terminal tab/window run: $ iroha events block-pipeline ``` -The output would look like this: +::: details Expected result ```json Listening to events with filter: Pipeline(Block(BlockEventFilter { height: None, status: None })) @@ -355,8 +370,14 @@ Listening to events with filter: Pipeline(Block(BlockEventFilter { height: None, ``` -Run the help command `iroha events help` to find out how to listen to other types of events. +::: tip + +To find out how to listen to other types of events, run the `iroha events help` command. + +::: ## What's Next + + Now that you know the basics, you can proceed to one of our language-specific [turorials](/guide/get-started/tutorials) to learn how to build on Iroha. From 7b6b591db804177a1b52fc34a8cc20cd61aa7f65 Mon Sep 17 00:00:00 2001 From: a-zorina <64249490+a-zorina@users.noreply.github.com> Date: Thu, 5 Sep 2024 13:10:48 +0200 Subject: [PATCH 11/13] Additional post-review updates Signed-off-by: a-zorina <64249490+a-zorina@users.noreply.github.com> --- .vitepress/config.mts | 14 ++-- README.md | 2 +- .../advanced/running-iroha-on-bare-metal.md | 2 +- src/guide/blockchain/assets.md | 2 +- src/guide/blockchain/data-model.md | 2 +- src/guide/blockchain/how-iroha-works.md | 2 +- src/guide/blockchain/instructions.md | 8 +- src/guide/get-started/index.md | 18 ++--- src/guide/get-started/install-iroha-2.md | 75 +++++++++++++++++++ src/guide/get-started/install-iroha.md | 54 ------------- .../{launch-iroha.md => launch-iroha-2.md} | 17 ++--- ...-via-cli.md => operate-iroha-2-via-cli.md} | 58 ++++++++++---- src/guide/get-started/rust.md | 2 +- src/guide/get-started/tutorials.md | 2 +- .../security/generating-cryptographic-keys.md | 2 +- 15 files changed, 153 insertions(+), 107 deletions(-) create mode 100644 src/guide/get-started/install-iroha-2.md delete mode 100644 src/guide/get-started/install-iroha.md rename src/guide/get-started/{launch-iroha.md => launch-iroha-2.md} (66%) rename src/guide/get-started/{operate-iroha-via-cli.md => operate-iroha-2-via-cli.md} (86%) diff --git a/.vitepress/config.mts b/.vitepress/config.mts index e2d1ba9b8..3b2e97c6e 100644 --- a/.vitepress/config.mts +++ b/.vitepress/config.mts @@ -19,7 +19,7 @@ function nav(): DefaultTheme.NavItem[] { { text: 'Get Started', items: [ - { text: 'Install and Build', link: '/guide/get-started/install-iroha' }, + { text: 'Install and Build', link: '/guide/get-started/install-iroha-2' }, { text: 'SDK Tutorials', link: '/guide/get-started/tutorials' }, ], }, @@ -96,16 +96,16 @@ function sidebarGuide(): DefaultTheme.SidebarItem[] { link: '/guide/get-started/', items: [ { - text: 'Install Iroha', - link: '/guide/get-started/install-iroha', + text: 'Install Iroha 2', + link: '/guide/get-started/install-iroha-2', }, { - text: 'Launch Iroha', - link: '/guide/get-started/launch-iroha', + text: 'Launch Iroha 2', + link: '/guide/get-started/launch-iroha-2', }, { - text: 'Operate Iroha via CLI', - link: '/guide/get-started/operate-iroha-via-cli', + text: 'Operate Iroha 2 via CLI', + link: '/guide/get-started/operate-iroha-2-via-cli', }, { text: 'Iroha 2 vs. Iroha 1', diff --git a/README.md b/README.md index d28521fef..023059c38 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ This repository contains the source files for [Hyperledger Iroha 2 Documentation The tutorial is suitable for both experienced and novice users. It explains Iroha 2 concepts and features, and also offers language-specific step-by-step guides for these programming languages: -- [CLI](https://hyperledger.github.io/iroha-2-docs/guide/operate-iroha-via-cli.html) +- [CLI](https://hyperledger.github.io/iroha-2-docs/guide/operate-iroha-2-via-cli.html) - [Python](https://hyperledger.github.io/iroha-2-docs/guide/python.html) - [Rust](https://hyperledger.github.io/iroha-2-docs/guide/rust.html) - [Kotlin/Java](https://hyperledger.github.io/iroha-2-docs/guide/kotlin-java.html) diff --git a/src/guide/advanced/running-iroha-on-bare-metal.md b/src/guide/advanced/running-iroha-on-bare-metal.md index 2c127134e..590a967f5 100644 --- a/src/guide/advanced/running-iroha-on-bare-metal.md +++ b/src/guide/advanced/running-iroha-on-bare-metal.md @@ -353,7 +353,7 @@ ports need to be adjusted so there are no collisions. See the ## Deploy a minimal BFT network -Both of the following approaches could be messy and error-prone, which is why the [Launch Iroha](../get-started/launch-iroha.md) tutorial suggests using the `docker compose` command. +Both of the following approaches could be messy and error-prone, which is why the [Launch Iroha 2](../get-started/launch-iroha-2.md) tutorial suggests using the `docker compose` command. However, this brings you closer to the experience of actually maintaining a functional Iroha peer. ### Using Environment Variables diff --git a/src/guide/blockchain/assets.md b/src/guide/blockchain/assets.md index b086cf3cd..cf2875e57 100644 --- a/src/guide/blockchain/assets.md +++ b/src/guide/blockchain/assets.md @@ -76,7 +76,7 @@ Assets can be [registered](./instructions.md#un-register), Refer to one of the language-specific guides to walk you through the process of registering and minting assets in a blockchain: -- [CLI](/guide/get-started/operate-iroha-via-cli.md#_6-register-and-mint-assets) +- [CLI](/guide/get-started/operate-iroha-2-via-cli.md#_6-register-and-mint-assets) - [Rust](/guide/get-started/rust.md#_5-registering-and-minting-assets) - [Kotlin/Java](/guide/get-started/kotlin-java.md#_5-registering-and-minting-assets) - [Python](/guide/get-started/python.md#_5-registering-and-minting-assets) diff --git a/src/guide/blockchain/data-model.md b/src/guide/blockchain/data-model.md index c93e05f36..af4d16bbc 100644 --- a/src/guide/blockchain/data-model.md +++ b/src/guide/blockchain/data-model.md @@ -87,7 +87,7 @@ domain_looking_glass *-- account_rabbit : registered in | Language | Guide | | --------------------- |--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| CLI | Register a [domain](/guide/get-started/operate-iroha-via-cli.md#_3-register-a-domain), an [account](/guide/get-started/operate-iroha-via-cli.md#_4-register-an-account), an [asset](/guide/get-started/operate-iroha-via-cli.md#_6-register-and-mint-assets) | +| CLI | Register a [domain](/guide/get-started/operate-iroha-2-via-cli.md#_3-register-a-domain), an [account](/guide/get-started/operate-iroha-2-via-cli.md#_4-register-an-account), an [asset](/guide/get-started/operate-iroha-2-via-cli.md#_6-register-and-mint-assets) | | Rust | Register a [domain](/guide/get-started/rust.md#_3-registering-a-domain), an [account](/guide/get-started/rust.md#_4-registering-an-account), an [asset](/guide/get-started/rust.md#_5-registering-and-minting-assets) | | Kotlin/Java | Register a [domain](/guide/get-started/kotlin-java.md#_3-querying-and-registering-domains), an [account](/guide/get-started/kotlin-java.md#_4-registering-an-account), an [asset](/guide/get-started/kotlin-java.md#_5-registering-and-minting-assets) | | Python | Register a [domain](/guide/get-started/python.md#_3-registering-a-domain), an [account](/guide/get-started/python.md#_4-registering-an-account), an [asset](/guide/get-started/python.md#_5-registering-and-minting-assets) | diff --git a/src/guide/blockchain/how-iroha-works.md b/src/guide/blockchain/how-iroha-works.md index 35b543c94..bf0142ca0 100644 --- a/src/guide/blockchain/how-iroha-works.md +++ b/src/guide/blockchain/how-iroha-works.md @@ -2,7 +2,7 @@ To understand how Iroha operates, let's draw parallels between a blockchain and a computer. If the blockchain is the computer, then in this metaphor of -ours the client binary (for example: [`iroha`](/guide/get-started/operate-iroha-via-cli.md)) +ours the client binary (for example: [`iroha`](/guide/get-started/operate-iroha-2-via-cli.md)) is the keyboard, the blockchain is the hard drive, and the Iroha peer software is the processor. Like a processor, Iroha accepts portable instructions that modify what's written to the blockchain, allow certain diff --git a/src/guide/blockchain/instructions.md b/src/guide/blockchain/instructions.md index 2f5938c20..a53df0067 100644 --- a/src/guide/blockchain/instructions.md +++ b/src/guide/blockchain/instructions.md @@ -109,7 +109,7 @@ process of registering objects in a blockchain: | Language | Guide | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| CLI | Register a [domain](/guide/get-started/operate-iroha-via-cli.md#_3-register-a-domain), an [account](/guide/get-started/operate-iroha-via-cli.md#_4-register-an-account), an [asset](/guide/get-started/operate-iroha-via-cli.md#_6-register-and-mint-assets) | +| CLI | Register a [domain](/guide/get-started/operate-iroha-2-via-cli.md#_3-register-a-domain), an [account](/guide/get-started/operate-iroha-2-via-cli.md#_4-register-an-account), an [asset](/guide/get-started/operate-iroha-2-via-cli.md#_6-register-and-mint-assets) | | Rust | Register a [domain](/guide/get-started/rust.md#_3-registering-a-domain), an [account](/guide/get-started/rust.md#_4-registering-an-account), an [asset](/guide/get-started/rust.md#_5-registering-and-minting-assets) | | Kotlin/Java | Register a [domain](/guide/get-started/kotlin-java.md#_3-querying-and-registering-domains), an [account](/guide/get-started/kotlin-java.md#_4-registering-an-account), an [asset](/guide/get-started/kotlin-java.md#_5-registering-and-minting-assets) | | Python | Register a [domain](/guide/get-started/python.md#_3-registering-a-domain), an [account](/guide/get-started/python.md#_4-registering-an-account), an [asset](/guide/get-started/python.md#_5-registering-and-minting-assets) | @@ -130,7 +130,7 @@ are assumed to be non-negative as well, so you can never have $-1.0$ of Refer to one of the language-specific guides to walk you through the process of minting assets in a blockchain: -- [CLI](/guide/get-started/operate-iroha-via-cli.md#_6-register-and-mint-assets) +- [CLI](/guide/get-started/operate-iroha-2-via-cli.md#_6-register-and-mint-assets) - [Rust](/guide/get-started/rust.md#_5-registering-and-minting-assets) - [Kotlin/Java](/guide/get-started/kotlin-java.md#_5-registering-and-minting-assets) - [Python](/guide/get-started/python.md#_5-registering-and-minting-assets) @@ -138,7 +138,7 @@ process of minting assets in a blockchain: Here are examples of burning assets: -- [CLI](/guide/get-started/operate-iroha-via-cli.md#_8-burn-assets) +- [CLI](/guide/get-started/operate-iroha-2-via-cli.md#_8-burn-assets) - [Rust](/guide/get-started/rust.md#_7-burning-assets) ## Transfer @@ -149,7 +149,7 @@ can transfer assets between different accounts. To do this, an account have to be granted the [permission to transfer assets](/reference/permissions.md). Refer to an example on how to -transfer assets with [CLI](/guide/get-started/operate-iroha-via-cli.md#_7-transfer-assets) or [Rust](/guide/get-started/rust.md#_6-transferring-assets). +transfer assets with [CLI](/guide/get-started/operate-iroha-2-via-cli.md#_7-transfer-assets) or [Rust](/guide/get-started/rust.md#_6-transferring-assets). diff --git a/src/guide/get-started/index.md b/src/guide/get-started/index.md index 3b5a02b95..8896739c4 100644 --- a/src/guide/get-started/index.md +++ b/src/guide/get-started/index.md @@ -1,6 +1,6 @@ # Iroha 2 -Iroha is a fully-featured [blockchain ledger](/reference/glossary.md#blockchain-ledgers). With Iroha you can: +Iroha 2 is a fully-featured [blockchain ledger](/reference/glossary.md#blockchain-ledgers). With Iroha 2 you can: - Create and manage custom [fungible assets](/reference/glossary.md#fungible-assets), such as currencies, gold, etc. - Create and manage [non-fungible](/reference/glossary.md#non-fungible-assets) assets, such as digital art, intellectual property, etc. - Manage user accounts with a domain hierarchy and multi-signature transactions. @@ -10,11 +10,11 @@ Iroha is a fully-featured [blockchain ledger](/reference/glossary.md#blockchain- ## Get Started If you are just starting with Iroha 2, begin with the following step-by-step tutorials: -1. [Install Iroha](/guide/get-started/install-iroha.md): install prerequisites and clone the GitHub repository. -2. [Launch Iroha](/guide/get-started/launch-iroha.md): install prerequisites and establish an instance of Iroha network. -3. [Operate Iroha via CLI](/guide/get-started/operate-iroha-via-cli.md): learn how to [setup](operate-iroha-via-cli.md#_1-setup-iroha-2-client) and [configure](operate-iroha-via-cli.md#_2-configure-iroha-2-client) Iroha 2 Client, and perform necessary basic operations on the network (e.g., [registering domains](operate-iroha-via-cli.md#_3-register-a-domain) and [accounts](operate-iroha-via-cli.md#_4-register-an-account), [registering and minting assets](operate-iroha-via-cli.md#_6-register-and-mint-assets), etc.). +1. [Install Iroha 2](/guide/get-started/install-iroha-2.md): install prerequisites and clone the GitHub repository. +2. [Launch Iroha 2](/guide/get-started/launch-iroha-2.md): install prerequisites and establish an instance of Iroha network. +3. [Operate Iroha 2 via CLI](/guide/get-started/operate-iroha-2-via-cli.md): learn how to [setup](operate-iroha-2-via-cli.md#_1-setup-iroha-2-client) and [configure](operate-iroha-2-via-cli.md#_2-configure-iroha-2-client) Iroha Client, and perform necessary basic operations on the network (e.g., [registering domains](operate-iroha-2-via-cli.md#_3-register-a-domain) and [accounts](operate-iroha-2-via-cli.md#_4-register-an-account), [registering and minting assets](operate-iroha-2-via-cli.md#_6-register-and-mint-assets), etc.). -If you would like to operate Iroha using a different programming language, Iroha 2 provides SDKs and language-specific tutorials for the following languages: +If you would like to operate Iroha 2 using a different programming language, Iroha provides SDKs and language-specific tutorials for the following languages: - [Python](/guide/get-started/python.md) - [Rust](/guide/get-started/rust.md) - [Kotlin/Java](/guide/get-started/kotlin-java.md) @@ -22,7 +22,7 @@ If you would like to operate Iroha using a different programming language, Iroha ::: tip -If you have previously worked with Iroha 1, you may want to start with the [Iroha 2 vs. Iroha 1](/guide/iroha-2.md) comparison that will help you understand the improvements and new features in Iroha 2. +The current version of Iroha covered in this documentation is Iroha 2. If you have previously worked with Iroha 1, you may want to start with the [Iroha 2 vs. Iroha 1](/guide/iroha-2.md) comparison that will help you understand the improvements and new features of Iroha 2. ::: @@ -30,14 +30,14 @@ If you have previously worked with Iroha 1, you may want to start with the [Iroh Once you have learned the basics, we suggest exploring the following sections: - [Security](/guide/security/index.md): find out about [core security principles](/guide/security/security-principles.md) and [operational security measures](/guide/security/operational-security.md) that are necessary to ensure the safety and validity of data and assets. This section also covers [cryptographic keys](/guide/security/public-key-cryptography.md), [how to generate them](/guide/security/generating-cryptographic-keys.md), and [how to store them securely](/guide/security/storing-cryptographic-keys.md). -- Blockchain: learn [how Iroha works](../blockchain/how-iroha-works.md) and find information on key Iroha 2 concepts, including entities, operations, and features, such as [Iroha Special Instructions](/guide/blockchain/instructions.md), [triggers](/guide/blockchain/triggers.md), [queries](/guide/blockchain/queries.md). -- Configuration and Management: discover ways to configure the Iroha 2 network , including [genesis blocks and accounts](/guide/configure/genesis.md), [client configuration](/guide/configure/client-configuration.md), and [public and private modes](/guide/configure/modes.md). +- Blockchain: learn [how Iroha works](../blockchain/how-iroha-works.md) and find information on key Iroha concepts, including entities, operations, and features, such as [Iroha Special Instructions](/guide/blockchain/instructions.md), [triggers](/guide/blockchain/triggers.md), [queries](/guide/blockchain/queries.md). +- Configuration and Management: discover ways to configure the Iroha network , including [genesis blocks and accounts](/guide/configure/genesis.md), [client configuration](/guide/configure/client-configuration.md), and [public and private modes](/guide/configure/modes.md). ## Learn More -For more information on Iroha 2, see the following: +For more information on Iroha, see the following: - [Iroha 2 Whitepaper](https://github.com/hyperledger/iroha/tree/main/docs/source/iroha_2_whitepaper.md) - [Hyperledger Foundation Wiki: Hyperledger Iroha > Iroha 2](https://wiki.hyperledger.org/display/iroha/Iroha+2) diff --git a/src/guide/get-started/install-iroha-2.md b/src/guide/get-started/install-iroha-2.md new file mode 100644 index 000000000..8df5a1cb7 --- /dev/null +++ b/src/guide/get-started/install-iroha-2.md @@ -0,0 +1,75 @@ +# Install Iroha 2 + +This tutorial guides you through the steps to install Iroha 2 and its necessary binaries on your machine. + +## 1. Prerequisites + +To install Iroha 2, you need to set up the following first: +- [git](https://githowto.com/) +- [OpenSSL](https://www.openssl.org/) +- [Rust Toolchain](https://www.rust-lang.org/tools/install) (v1.60.0 or newer) + +::: details TIP: How to Install OpenSSL + +Note that in most Linux setups OpenSSL is already available to you. + +- Install OpenSSL on Ubuntu: + + ```bash + $ sudo apt-get install libssl-dev + ``` + +- Install OpenSSL on macOS using [brew](https://brew.sh/): + + ```bash + $ brew install openssl + ``` + +Check the [OpenSSL installation guide](https://github.com/openssl/openssl/blob/master/INSTALL.md) for details. + +::: + + +## 2. Clone Iroha from GitHub + +1. Create a new directory for Iroha: + + ```bash + $ mkdir -p ~/Git + ``` + + ::: tip + + On macOS, if you get the `fatal: could not create work tree dir 'iroha': Read-only file system` error, that is because the home directory is not a real file system. + + To fix this, create a directory named `Git`. + + ::: + +2. Enter the directory that you created: + + ```bash + $ cd ~/Git + ``` + +3. Clone the [`iroha`](https://github.com/hyperledger/iroha) GitHub repository: + + ```bash + $ git clone https://github.com/hyperledger/iroha.git + ``` + +### 3. Install Iroha Binaries + +To get started you need two of the binaries shipped with Iroha: + +- `iroha`, the main command line tool for accessing the Iroha network as a user. It allows you to manage domains, accounts, and assets, and to query network status and events. To install `iroha` system-wide, use the following command: + +```bash +$ cargo install --git https://github.com/hyperledger/iroha.git iroha_client_cli +``` + +- `kagami`, the tool that generates cryotpgraphic keys, configuration files and other necessary data. To install `kagami` system-wide, use the following command: + +```bash +$ cargo install --git https://github.com/hyperledger/iroha.git kagami +``` diff --git a/src/guide/get-started/install-iroha.md b/src/guide/get-started/install-iroha.md deleted file mode 100644 index 434f66c5f..000000000 --- a/src/guide/get-started/install-iroha.md +++ /dev/null @@ -1,54 +0,0 @@ -# Install Iroha - - - -## Prerequisites - -To install and build Iroha from GitHub, the following must be installed first: -- [git](https://githowto.com/) -- [OpenSSL](https://www.openssl.org/) -- [Rust Toolchain](https://www.rust-lang.org/tools/install) (v1.60.0 or newer) - -## Clone Iroha from GitHub - - - -1. Create a new directory for Iroha 2: - - ```bash - $ mkdir -p ~/Git - ``` - - ::: tip - - On macOS, if you get the `fatal: could not create work tree dir 'iroha': Read-only file system` error, that is because the home directory is not a real file system. - - The solution is to create a directory named `Git`. - - ::: - -2. Enter the directory that you created: - - ```bash - $ cd ~/Git - ``` - -3. Clone the [`iroha`](https://github.com/hyperledger/iroha) GitHub repository: - - ```bash - $ git clone https://github.com/hyperledger/iroha.git - ``` - -### Install Iroha 2 Binaries - - - -To install any of the standalone Iroha 2 binaries system-wide, use the following commands: - -```bash -$ cargo install --git https://github.com/hyperledger/iroha.git iroha -``` - -```bash -$ cargo install --git https://github.com/hyperledger/iroha.git kagami -``` diff --git a/src/guide/get-started/launch-iroha.md b/src/guide/get-started/launch-iroha-2.md similarity index 66% rename from src/guide/get-started/launch-iroha.md rename to src/guide/get-started/launch-iroha-2.md index c7325960c..574b13448 100644 --- a/src/guide/get-started/launch-iroha.md +++ b/src/guide/get-started/launch-iroha-2.md @@ -1,14 +1,14 @@ # Launch Iroha 2 -Once you have Iroha 2 installed on your machine, you are ready to set up an instance of the Iroha network. +This tutorial explains how to launch an Iroha 2 network. -## Prerequisites +## 1. Prerequisites -To launch an instance of the Iroha network, the following must be installed first: +To launch an instance of the Iroha 2 network, install the following first: - [Docker](https://docs.docker.com/get-docker/) - [Docker Compose](https://docs.docker.com/compose/install/) -## Launch Iroha Network +## 2. Launch Iroha Network 1. In your terminal, navigate to the root directory of your local [`iroha`](https://github.com/hyperledger/iroha) repository: @@ -22,14 +22,13 @@ To launch an instance of the Iroha network, the following must be installed firs $ docker compose -f defaults/docker-compose.yml up ``` - Depending on your setup, this might either pull an image from [Docker Hub]((https://hub.docker.com/r/hyperledger/iroha2/tags)) or build the container locally.\ - Once the process is complete, an output similar to the following is generated: + Depending on your setup, this command will either pull an image from [Docker Hub](https://hub.docker.com/r/hyperledger/iroha2/tags) or build the container locally. + + Once the process completes, you will see an output similar to the following: <<< @/guide/get-started/launch-iroha.docker-compose-output.ansi -Once the network is deployed, it is possible to interact with it using Iroha Client CLI. - -To discover its capabilities and learn to perform some of the basic operations, see [Operate Iroha via CLI](./operate-iroha-via-cli.md). +After deploying the network, you can interact with it using the [Iroha Client CLI](./operate-iroha-2-via-cli.md). ::: tip diff --git a/src/guide/get-started/operate-iroha-via-cli.md b/src/guide/get-started/operate-iroha-2-via-cli.md similarity index 86% rename from src/guide/get-started/operate-iroha-via-cli.md rename to src/guide/get-started/operate-iroha-2-via-cli.md index ccf9d7fe2..e3906d4c3 100644 --- a/src/guide/get-started/operate-iroha-via-cli.md +++ b/src/guide/get-started/operate-iroha-2-via-cli.md @@ -1,14 +1,12 @@ -# Operate Iroha via CLI +# Operate Iroha 2 via CLI -Most of the operations with an Iroha network can be performed via the Iroha Client CLI. This tutorial aims to help you set it up and configure, and then perform some of the basic operations with the network. - -For quick access to an operation that interests you, use the **On this page** menu. +You can perform most operations in an Iroha 2 network using the Iroha Client CLI. This tutorial guides you through setting it up, configuring it, and executing basic operations on the network. ## 1. Set Up Iroha Client CLI ::: info -To set up the Iroha Client CLI, an instance of the Iroha network must be [launched and operational](./launch-iroha.md). +To set up the Iroha Client CLI, an instance of the Iroha network must be [launched and operational](./launch-iroha-2.md). ::: @@ -28,7 +26,7 @@ $ cp path_to_iroha_repo/defaults/client.toml path_to_new_directory/ $ iroha ``` - ::: details Expected output + ::: details Expected result ```bash Iroha CLI Client lets you interact with Iroha Peers Web API without direct network usage @@ -80,13 +78,40 @@ $ iroha domain list all The output should contain several preregistered domains. - +::: details Expected result + +```json + { + "id": "garden_of_live_flowers", + "logo": null, + "metadata": {}, + "owned_by": "ed01204164BF554923ECE1FD412D241036D863A6AE430476C898248B8237D77534CFC4@genesis" + }, + { + "id": "genesis", + "logo": null, + "metadata": {}, + "owned_by": "ed01204164BF554923ECE1FD412D241036D863A6AE430476C898248B8237D77534CFC4@genesis" + }, + { + "id": "wonderland", + "logo": null, + "metadata": { + "key": "value" + }, + "owned_by": "ed0120CE7FA46C9DCE7EA4B125E2E36BDB63EA33073E7590AC92816AE1E861B7048B03@wonderland" + } + +``` + +::: + ## 3. Register a Domain ::: info -A _domain_ is a group of entities like asset definitions, accounts, and other objects grouped logically. These are described in greater detail in the [Blockchain](TODO) section of the documentation. +A _domain_ is a group of entities like asset definitions, accounts, and other objects grouped logically. These are described in greater detail in the [Blockchain](/guide/blockchain/how-iroha-works) section of the documentation. ::: @@ -102,7 +127,7 @@ Once executed, a confirmation message appears. However, since the details of the $ iroha domain list all ``` -::: details Expected output +::: details Expected result ```json { @@ -192,11 +217,11 @@ $ iroha account list all ## 5. Transfer a Domain - +The account we just created is part of the `looking_glass` domain but doesn't own it, so it can't manage the domain. To enable this, we'll transfer `looking_glass` ownership to our new account. -We could change the keys and domain in `client.toml` at this point and continue working with the account we just created, but we wouldn't be able to do much in the `looking_glass` domain, as our new account is not the owner of thw `looking_glass` domain, and therefore cannot manage it. +We could change the keys and domain in `client.toml` at this point and continue working with the account we just created, but we wouldn't be able to do much in the `looking_glass` domain, as our new account is not the owner of the `looking_glass` domain, and therefore cannot manage it. -To transfer an account from under the `wonderland` domain to the `looking_glass` domain, perform the following: +To transfer a domain, perform the following: 1. Run the transfer command: @@ -210,7 +235,7 @@ To transfer an account from under the `wonderland` domain to the `looking_glass` $ iroha domain list all ``` -1. Switch to the newly created account. For this, we need to modify the `public_key`, `private_key`, and `domain` in the `client.toml` config file with the credentials of the user we want to act as. +3. Switch to the newly created account. For this, we need to modify the `public_key`, `private_key`, and `domain` in the `client.toml` config file with the credentials of the user we want to act as. Note that here the domain of the user that we are switching to matches the one we just transferred. However, this is not a requirement. A user may be registered in one domain and own multiple others. When setting the domain in the configuration file, always use the one that your user is registered with. @@ -378,6 +403,7 @@ To find out how to listen to other types of events, run the `iroha events help` ## What's Next - - -Now that you know the basics, you can proceed to one of our language-specific [turorials](/guide/get-started/tutorials) to learn how to build on Iroha. +Now that you understand the basics, you can explore these advanced documentation: +- Learn how to build on Iroha 2 with our [SDK turorials](/guide/get-started/tutorials). +- Understand the fundamental concepts behind Iroha 2 in the [Blockchain](/guide/blockchain/how-iroha-works) section. +- Build more complex networks using the [Configuration and Management](/guide/configure/overview) section. \ No newline at end of file diff --git a/src/guide/get-started/rust.md b/src/guide/get-started/rust.md index a2c7e9c44..0818a5e7c 100644 --- a/src/guide/get-started/rust.md +++ b/src/guide/get-started/rust.md @@ -38,7 +38,7 @@ number of dependencies to start your own client, similar to Once the initial `v2.0.0` release is complete, we plan to create a package on [crates.io](https://crates.io/) with all the documentation. In the meantime, you could use the local copy that you've just created in the -[previous step](/guide/get-started/install-iroha) as a local installation in your client's +[previous step](/guide/get-started/install-iroha-2) as a local installation in your client's `Cargo.toml`: ```toml diff --git a/src/guide/get-started/tutorials.md b/src/guide/get-started/tutorials.md index 1025db9c0..7b4941ff1 100644 --- a/src/guide/get-started/tutorials.md +++ b/src/guide/get-started/tutorials.md @@ -26,7 +26,7 @@ We invite you to follow the tutorial in this order: 0. If you are already familiar with Hyperledger Iroha, read about [the differences](/guide/iroha-2.md) between the two versions of Iroha. -1. [Install Iroha 2](/guide/get-started/install-iroha.md). +1. [Install Iroha 2](/guide/get-started/install-iroha-2.md). 2. Follow one of the language-specific guides to learn how to set up and configure Iroha 2, register a domain and an account, register and mind assets, and visualize outputs: diff --git a/src/guide/security/generating-cryptographic-keys.md b/src/guide/security/generating-cryptographic-keys.md index 97ee25d1b..8b18c4dee 100644 --- a/src/guide/security/generating-cryptographic-keys.md +++ b/src/guide/security/generating-cryptographic-keys.md @@ -14,7 +14,7 @@ Since `kagami` does not come with a manual page, you can use the `--help` (`-h`) ::: -After [installing Iroha](/guide/get-started/install-iroha.md), run the following command from the project's `root` directory to generate a new key pair: +After [installing Iroha](/guide/get-started/install-iroha-2.md), run the following command from the project's `root` directory to generate a new key pair: ```bash $ cargo run --bin kagami --release -- crypto From 486fffbd63dd42361fdd53599f7853607176c75f Mon Sep 17 00:00:00 2001 From: a-zorina <64249490+a-zorina@users.noreply.github.com> Date: Thu, 5 Sep 2024 13:20:21 +0200 Subject: [PATCH 12/13] link fixes Signed-off-by: a-zorina <64249490+a-zorina@users.noreply.github.com> --- src/guide/get-started/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/guide/get-started/index.md b/src/guide/get-started/index.md index 8896739c4..7c2950e95 100644 --- a/src/guide/get-started/index.md +++ b/src/guide/get-started/index.md @@ -12,7 +12,7 @@ Iroha 2 is a fully-featured [blockchain ledger](/reference/glossary.md#blockchai If you are just starting with Iroha 2, begin with the following step-by-step tutorials: 1. [Install Iroha 2](/guide/get-started/install-iroha-2.md): install prerequisites and clone the GitHub repository. 2. [Launch Iroha 2](/guide/get-started/launch-iroha-2.md): install prerequisites and establish an instance of Iroha network. -3. [Operate Iroha 2 via CLI](/guide/get-started/operate-iroha-2-via-cli.md): learn how to [setup](operate-iroha-2-via-cli.md#_1-setup-iroha-2-client) and [configure](operate-iroha-2-via-cli.md#_2-configure-iroha-2-client) Iroha Client, and perform necessary basic operations on the network (e.g., [registering domains](operate-iroha-2-via-cli.md#_3-register-a-domain) and [accounts](operate-iroha-2-via-cli.md#_4-register-an-account), [registering and minting assets](operate-iroha-2-via-cli.md#_6-register-and-mint-assets), etc.). +3. [Operate Iroha 2 via CLI](/guide/get-started/operate-iroha-2-via-cli.md): learn how to [setup](operate-iroha-2-via-cli.md#_1-set-up-iroha-client-cli) and [configure](operate-iroha-2-via-cli.md#_2-configure-iroha-client-cli) Iroha Client, and perform necessary basic operations on the network (e.g., [registering domains](operate-iroha-2-via-cli.md#_3-register-a-domain) and [accounts](operate-iroha-2-via-cli.md#_4-register-an-account), [registering and minting assets](operate-iroha-2-via-cli.md#_6-register-and-mint-assets), etc.). If you would like to operate Iroha 2 using a different programming language, Iroha provides SDKs and language-specific tutorials for the following languages: - [Python](/guide/get-started/python.md) From 68ae813491f1d7b0c5bdaa8350b44d17772179f8 Mon Sep 17 00:00:00 2001 From: a-zorina <64249490+a-zorina@users.noreply.github.com> Date: Wed, 11 Sep 2024 09:49:11 +0200 Subject: [PATCH 13/13] final post-review changes Signed-off-by: a-zorina <64249490+a-zorina@users.noreply.github.com> --- src/guide/get-started/install-iroha-2.md | 2 +- src/guide/get-started/launch-iroha-2.md | 2 +- src/guide/iroha-2.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/guide/get-started/install-iroha-2.md b/src/guide/get-started/install-iroha-2.md index 8df5a1cb7..b66fde241 100644 --- a/src/guide/get-started/install-iroha-2.md +++ b/src/guide/get-started/install-iroha-2.md @@ -32,7 +32,7 @@ Check the [OpenSSL installation guide](https://github.com/openssl/openssl/blob/m ## 2. Clone Iroha from GitHub -1. Create a new directory for Iroha: +1. Create a new directory for Iroha. In this tutorial we use `Git` as an example, but you can name it anything else: ```bash $ mkdir -p ~/Git diff --git a/src/guide/get-started/launch-iroha-2.md b/src/guide/get-started/launch-iroha-2.md index 574b13448..8bba56604 100644 --- a/src/guide/get-started/launch-iroha-2.md +++ b/src/guide/get-started/launch-iroha-2.md @@ -45,7 +45,7 @@ The following options are also available for local compilation: ::: tip Note -There is ongoing work to make our configurations for Docker even more customizable with the help of Swarm. +There is ongoing work to make our configurations for Docker even more customizable with the help of [Swarm](https://github.com/hyperledger/iroha/tree/main/tools/swarm). diff --git a/src/guide/iroha-2.md b/src/guide/iroha-2.md index af8fd3833..c016e4289 100644 --- a/src/guide/iroha-2.md +++ b/src/guide/iroha-2.md @@ -2,7 +2,7 @@ -Iroha 2 is a **complete** rewrite of [Hyperledger Iroha](https://iroha.readthedocs.io/en/develop/index.html) in Rust. As of writing, the two projects are developed concurrently. +Iroha 2 is a **complete** rewrite of [Hyperledger Iroha](https://iroha.readthedocs.io/en/develop/index.html) in Rust. In this introduction we outline the differences between the two versions of Iroha and highlight the new features of Iroha 2. It should be of particular interest to those who are already familiar with Iroha but wish to upgrade and start using the newer version.