From b1256807b0fb3c5a0e364abf86412d295509fb5f Mon Sep 17 00:00:00 2001 From: Ekaterina Mekhnetsova Date: Tue, 5 Nov 2024 14:36:44 +0300 Subject: [PATCH] docs: Update readmes (#5219) Signed-off-by: Ekaterina Mekhnetsova --- crates/iroha_cli/README.md | 71 +++++++------------------------- docs/README.md | 18 +++----- docs/source/guides/hot-reload.md | 71 -------------------------------- 3 files changed, 20 insertions(+), 140 deletions(-) delete mode 100644 docs/source/guides/hot-reload.md diff --git a/crates/iroha_cli/README.md b/crates/iroha_cli/README.md index 30295aac38b..57a50db8136 100644 --- a/crates/iroha_cli/README.md +++ b/crates/iroha_cli/README.md @@ -1,12 +1,6 @@ # Iroha CLI Client -With the Iroha CLI Client, you can interact with Iroha Peers Web API. -It is a "thin" wrapper around functionality exposed in the `iroha` crate. Specifically, it should be used as a reference for using `iroha`'s features, and not as a production-ready client. As such, the CLI client is not guaranteed to support all features supported by the client library. - -## Features - -* Submit Transactions with your Iroha Special Instructions to Iroha Peers -* Send Requests with your Queries to Iroha Peers +Iroha Client CLI is a "thin" wrapper around functionality exposed in the `iroha` crate. Specifically, it should be used as a reference for using `iroha`'s features, and not as a production-ready client. As such, the CLI client is not guaranteed to support all features supported by the client library. Check [Iroha 2 documentation](https://docs.iroha.tech/get-started/operate-iroha-2-via-cli.html) for a detailed tutorial on working with Iroha Client CLI. ## Installation @@ -52,8 +46,6 @@ iroha [OPTIONS] Refer to [Iroha Special Instructions](https://docs.iroha.tech/blockchain/instructions.html) for more information about Iroha instructions such as register, mint, grant, and so on. -Check the [getting started guide](https://docs.iroha.tech/get-started/operate-iroha-2-via-cli.html) for detailed instructions on working with Iroha Client CLI. - ## Examples :grey_exclamation: All examples below are Unix-oriented. If you're working on Windows, we would highly encourage you to consider using WSL, as most documentation assumes a POSIX-like shell running on your system. Please be advised that the differences in the syntax may go beyond executing `iroha.exe` instead of `iroha`. @@ -68,35 +60,24 @@ Check the [getting started guide](https://docs.iroha.tech/get-started/operate-ir In this section we will show you how to use Iroha CLI Client to do the following: -- [Iroha CLI Client](#iroha-cli-client) - - [Features](#features) - - [Installation](#installation) - - [Usage](#usage) - - [Options](#options) - - [Subcommands](#subcommands) - - [Examples](#examples) - - [Create new Domain](#create-new-domain) - - [Create new Account](#create-new-account) - - [Mint Asset to Account](#mint-asset-to-account) - - [Query Account Assets Quantity](#query-account-assets-quantity) - - [Execute WASM transaction](#execute-wasm-transaction) - - [Execute Multi-instruction Transactions](#execute-multi-instruction-transactions) + - [Create new Domain](#create-new-domain) + - [Create new Account](#create-new-account) + - [Mint Asset to Account](#mint-asset-to-account) + - [Query Account Assets Quantity](#query-account-assets-quantity) + - [Execute WASM transaction](#execute-wasm-transaction) + - [Execute Multi-instruction Transactions](#execute-multi-instruction-transactions) ### Create new Domain -Let's start with domain creation. To create a domain, you need to specify the entity type first (`domain` in our case) and then the command (`register`) with a list of required parameters. - -For the `domain` entity, you only need to provide the `id` argument as a string that doesn't contain the `@` and `#` symbols. +To create a domain, you need to specify the entity type first (`domain` in our case) and then the command (`register`) with a list of required parameters. For the `domain` entity, you only need to provide the `id` argument as a string that doesn't contain the `@` and `#` symbols. ```bash ./iroha domain register --id="Soramitsu" ``` -Now you have a domain without any accounts. - ### Create new Account -Let's create a new account. Like in the previous example, specify the entity type (`account`) and the command (`register`). Then define the value of the `id` argument in "signatory@domain" format, where signatory is the account's public key in multihash representation. +To create an account, specify the entity type (`account`) and the command (`register`). Then define the value of the `id` argument in "signatory@domain" format, where signatory is the account's public key in multihash representation: ```bash ./iroha account register --id="ed01204A3C5A6B77BBE439969F95F0AA4E01AE31EC45A0D68C131B2C622751FCC5E3B6@Soramitsu" @@ -104,33 +85,18 @@ Let's create a new account. Like in the previous example, specify the entity typ ### Mint Asset to Account -It's time to give something to the Account you created. Let's add some Assets of the type `Quantity` to the account. - -To do so, you must first register an Asset Definition and only then add some Assets to the account. Specify the `asset` entity and then use the `register` and `mint` commands respectively. - -Every asset has its own value spec. In this example, it is defined as `Numeric`, a 96-bit unsigned decimal. We also support `Store` for key-value structured data. +To add assets to the account, you must first register an Asset Definition. Specify the `asset` entity and then use the `register` and `mint` commands respectively. Here is an example of adding Assets of the type `Quantity` to the account: ```bash ./iroha asset register --id="XOR#Soramitsu" --type=Numeric ./iroha asset mint --account="ed01204A3C5A6B77BBE439969F95F0AA4E01AE31EC45A0D68C131B2C622751FCC5E3B6@Soramitsu" --asset="XOR#Soramitsu" --quantity=1010 ``` -You created `XOR#Soramitsu`, an asset of type `Numeric`, and then gave `1010` units of this asset to the account `ed01204A3C5A6B77BBE439969F95F0AA4E01AE31EC45A0D68C131B2C622751FCC5E3B6@Soramitsu`. +With this, you created `XOR#Soramitsu`, an asset of type `Numeric`, and then gave `1010` units of this asset to the account `ed01204A3C5A6B77BBE439969F95F0AA4E01AE31EC45A0D68C131B2C622751FCC5E3B6@Soramitsu`. ### Query Account Assets Quantity -Because distributed systems heavily rely on the concept of _eventual_ consistency and Iroha works by awaiting consensus between peers, your request is not guaranteed to be processed (or be accepted) even if it is correctly formed. -While the Iroha Client will successfully send your transactions and the Iroha Peer will confirm receiving them, it is possible that your request will not appear in the next block. - -Different causes such as a transaction timeout, a faulty peer in the network, catastrophic failure of the peer that you've sent your data towards, and many other conditions naturally occurring inside of any blockchain may lead to a rejection of your transaction at many different stages of processing. - -It should be noted that Iroha is designed to reduce the incidence of such rejections, and only rejects properly formed transactions in situations when not rejecting it would lead to data corruption and a hard-fork of the network. - -As such it's important to check that your instructions were applied and the _world_ is now in the desired state. -For this you need to use Query API. - -Let's use Get Account Assets Query as an example. -To know how many units of a particular asset an account has, use `asset get` with the specified account and asset: +You can use Query API to check that your instructions were applied and the _world_ is in the desired state. For example, to know how many units of a particular asset an account has, use `asset get` with the specified account and asset: ```bash ./iroha asset get --account="ed01204A3C5A6B77BBE439969F95F0AA4E01AE31EC45A0D68C131B2C622751FCC5E3B6@Soramitsu" --asset="XOR#Soramitsu" @@ -138,24 +104,15 @@ To know how many units of a particular asset an account has, use `asset get` wit This query returns the quantity of `XOR#Soramitsu` asset for the `ed01204A3C5A6B77BBE439969F95F0AA4E01AE31EC45A0D68C131B2C622751FCC5E3B6@Soramitsu` account. -It's possible to filter based on either account, asset or domain id by using the filtering API provided by the Iroha client CLI. - -Generally it looks like this: - -```bash -./iroha ENTITY list filter PREDICATE -``` - -Where ENTITY is asset, account or domain and PREDICATE is condition used for filtering serialized using JSON5 (check `iroha::data_model::predicate::value::ValuePredicate` type). +You can also filter based on either account, asset or domain id by using the filtering API provided by the Iroha client CLI. Generally, filtering follows the `./iroha ENTITY list filter PREDICATE` pattern, where ENTITY is asset, account or domain and PREDICATE is condition used for filtering serialized using JSON5 (check `iroha::data_model::predicate::value::ValuePredicate` type). -Examples: +Here are some examples of filtering: ```bash # Filter domains by id ./iroha domain list filter '{"Identifiable": {"Is": "wonderland"}}' # Filter accounts by domain ./iroha account list filter '{"Identifiable": {"EndsWith": "@wonderland"}}' -# It is possible to combine filters using "Or" or "And" # Filter asset by domain ./iroha asset list filter '{"Or": [{"Identifiable": {"Contains": "#wonderland#"}}, {"And": [{"Identifiable": {"Contains": "##"}}, {"Identifiable": {"EndsWith": "@wonderland"}}]}]}' ``` diff --git a/docs/README.md b/docs/README.md index b907992e83b..457f3a3cf17 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,23 +1,17 @@ # Iroha 2 Documentation -This is the main Iroha 2 documentation that you will find useful: +In the [main Iroha 2 documentation](https://docs.iroha.tech/) you will find: -- [Tutorial](https://docs.iroha.tech/guide/tutorials/) +- [Get Started Guide](https://docs.iroha.tech/get-started/) +- [SDK Tutorials](https://docs.iroha.tech/guide/tutorials/) for Rust, Python, Javascript, and Java/Kotlin - [API Reference](https://docs.iroha.tech/reference/torii-endpoints.html) - -- [Iroha 2 Whitepaper](./source/iroha_2_whitepaper.md) + +You can also check out [Iroha 2 Whitepaper](./source/iroha_2_whitepaper.md) for Iroha 2 specification. ## Tools -Documentation for Iroha 2 tools: +In this repository you can find documentation for Iroha 2 tools: - [Kagami](../crates/iroha_kagami/README.md) - [Kura Inspector](../crates/kura_inspector/README.md) - [Parity Scale Decoder Tool](../crates/iroha_codec/README.md) - -## Development - -The following is useful for development: - -- [Hot reload Iroha in a Docker container](./source/guides/hot-reload.md) -- [Benchmark your code](../crates/iroha/benches/tps/README.md) diff --git a/docs/source/guides/hot-reload.md b/docs/source/guides/hot-reload.md deleted file mode 100644 index 421e5ccd64f..00000000000 --- a/docs/source/guides/hot-reload.md +++ /dev/null @@ -1,71 +0,0 @@ -# How to hot reload Iroha in a Docker container - -Here is the overall procedure for hot reloading Iroha in a Docker container: - -1. Build Iroha on your host OS. - - To avoid issues with dynamic linking, run: - - ```bash - cargo build --release --target x86_64-unknown-linux-musl - ``` - -
An explanation for using `cargo build` with these parameters. - - You may experience an issue with dynamic linking if your host OS has a newer version of `glibc` compared to the one in the Docker container. The options used in the command above resolve the issue: - - - `--target x86_64-unknown-linux-musl` forces static linking against `musl` libc implementation - -
- -2. Enter Docker container. For example: - - ```bash - docker exec -it iroha-iroha0-1 bash - ``` - -3. Copy Iroha to the current directory: - - ```bash - docker cp root/soramitsu/iroha/target/x86_64-unknown-linux-musl/release/irohad . - ``` - -4. (Optional) Make any modifications you need: - - - [Recommit genesis block](#wiping-previous-blockchain-state-recommit-genesis) - - [Use custom configuration files](#use-custom-configuration-files) - - [Use custom environment variables](#use-custom-environment-variables) - -5. Exit docker container and restart it using `docker restart`. - - **Note:** If you use the combination of `container down` and `container up`, any modifications you made on the previous step will be lost. Use `docker restart` to preserve changes. - -If you skip the optional step (step 4), the state of the blockchain after hot reload will be the same as it was before the Docker container was restarted. - -Note that if you get the `Kura initialisation failed` error message, it might mean one of two things: corruption or binary incompatibility of the stored block. To fix this, remove the `blocks/` directory. - -## Wiping previous blockchain state (recommit genesis) - -To recommit a custom genesis block, remove the previously stored blocks before restarting the container: - -```bash -rm blocks/* -``` - -The new genesis block will be automatically recommitted upon container restart. - -## Use custom configuration files - -To use custom configuration files, such as `config.json` or `genesis.json`, copy (or bind mount) them to the `config/` subvolume before restarting the Docker container. - -The changes will take effect upon container restart. - -## Use custom environment variables - -To use custom environment variables (e.g. `IROHA_PUBLIC_KEY`), simply modify them before restarting the Docker container. For example: - -```bash - IROHA_PUBLIC_KEY= docker restart -``` - -The changes will take effect upon container restart.