hyperledger / iroha-2-docs Goto Github PK

View Code? Open in Web Editor NEW

5.0 28.0 25.0 6.16 MB

Home Page: https://hyperledger.github.io/iroha-2-docs/

License: Apache License 2.0

JavaScript 1.89% TypeScript 70.21% Vue 23.71% SCSS 0.45% TeX 3.61% Rust 0.12%

iroha iroha2 docs

iroha-2-docs's Introduction

Hyperledger Iroha 2 Tutorial

This repository contains the source files for Hyperledger Iroha 2 Tutorial.

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:

If you are already familiar with Hyperledger Iroha, we invite you to read about how Iroha 2 is different from its previous version.

Check the Hyperledger Iroha 2 repository for more detailed information about API and available features.

Contribution

If you want to contribute to Iroha 2 tutorial, please clone the repository and follow the steps below.

Prepare the environment

Install Node.js v16.9+. To install it without a headache, use NVM (Node Version Manager). You can run something like this:

# Install NVM itself
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash

# Run it to use NVM in the current shell session or restart your shell
export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm

Then you can install Node 18:

nvm install 18

Enable Corepack:
```
corepack enable
```
Install project dependencies. From the root of the cloned repository, run:
```
pnpm install
```

Run dev mode

pnpm dev

It will start a local dev-server. You will be able to open a browser, observe rendered documentation, edit source files and see your edits on-demand.

Formatting

We use Prettier to format project sources. Its configuration is located at ./.prettierrc.js. Check options reference for all available options.

Format sources: apply formatting to all project source files:
```
pnpm format:fix
```
Check the formatting in sources: ensure that all project source files match Prettier code style
```
pnpm format:check
```

We use prettier-eslint tool to override Prettier formatting for Vue components.

Linting

To check whether ESLint rules pass, run:

pnpm lint

To fix auto-fixable issues, run:

pnpm lint --fix

Testing

We use Vitest test framework to assure quality of non-trivial internal parts of the project.

To check whether tests pass, run:

pnpm vitest run

To run vitest in a watch-mode, run:

pnpm vitest

Enabling feedback form

In order to enable the "Share feedback" button, the following environment variable should be provided:

VITE_FEEDBACK_URL=https://example.com/get-feedback

When a user submits the form, a simple POST request with a JSON body is sent to this URL.

This variable will be picked up by the application during dev/build mode. Read more about it in the Vite documentation.

Compatibility matrix

Note: configuring this is required.

The SDK Compatibility Matrix provides an insightful look into the interoperability of various stories across multiple SDKs within Hyperledger Iroha 2.

The underlying data for the matrix is sourced from a backend service, ensuring low-latency response with preprocessed data. To configure access to the service (e.g. deployed at https://docs-compat.iroha2.tachi.soramitsu.co.jp), set the following environment variable:

VITE_COMPAT_MATRIX_URL=https://docs-compat.iroha2.tachi.soramitsu.co.jp/compat-matrix

License

Iroha documentation files are made available under the Creative Commons Attribution 4.0 International License (CC-BY-4.0), available at http://creativecommons.org/licenses/by/4.0/

iroha-2-docs's People

Contributors

Stargazers

Watchers

iroha-2-docs's Issues

Add a section on WASM validators

Add info about the chain of runtime validators.
Based on hyperledger/iroha#2641.

(stable version)

Add npm, yarn and pnpm installation mention for JavaScript client installation guide

Add npm, yarn and pnpm installation mention for JavaScript client installation guide before this step:

Check statements in triggers.md about current state/ongoing work

In triggers.md there are two statements that have to be verified. They are marked with the  comment:

### Event Triggers

As we have said previously, all triggers are, in a sense, event triggers.
However, this category includes the largest variety of triggers: an account
got registered, an asset got transferred, the Queen of Hearts decided to
burn all of her assets. These types of events account for the vast majority
of triggers in Ethereum, and were the first to be implemented. As of today
we only support un-scoped system-wide triggers with no permission
validation. <!-- Q: still true? --> Work is ongoing to make the triggers
safer and more reliable, but the process is time-consuming and
work-intensive.

::: info

Be mindful of the limitations. Currently triggers don't check for
permissions <!-- Q: still true? -->, so they can do things your account
wouldn't be allowed to. Since the triggers are not scoped, every trigger
processes _every_ event, and the amount of work grows quadratically.

:::

Found when RC3 mentions were removed from the text (#55).

Update the tutorial with new features

https://hyperledger.github.io/iroha-2-docs/#tutorial-updates:

In the future this tutorial will have sections dedicated to:

- [ ] permissions
- [ ] multi-signature accounts and transactions
- [ ] custom permission validators
- [ ] permission groups

We will also cover peer management in greater detail: adding and removing peers, maintaining a healthy network, and troubleshooting the issues that you might have in your real-world application.

Metadata for an Account definition

There's a question in Hyperledger Iroha Community Telegram:

Does Iroha2 have something similar to SetAccountDetail or GetAccountDetail?

According to @appetrosyan, we have API in Iroha 2 allowing to do this; accounts are the objects in the Blockchain, and each such object is allowed to contain metadata. Those objects work like key-value stores with values supporting each variant of the Value enum: numbers, strings, etc.

Assets may be transferred one-by-one, or in bulk using a WASM transaction.

Moreover, there's an asset called Store, specifically designed to be a package of data. It is designed for the situations when you don’t really need an asset, but instead a storage of key-value pairs.

UPD: according to @Arjentix, there are SetKeyValue and RemoveKeyValue Iroha Special Instructions.
One can also get the key value using FindAccountKeyValueByIdAndKey Iroha Query.
It doesn't close the issue completely, we'll need to provide the examples, but it explains some aspects.

We'll need to document the details for those API features in each supported SDK.

Update to LTS

Some code snippets rely on the unsupported pre-rc.4

Prepare documentation for community about the Test Network

The documentation should include:

CLI documentation (check that it is updated)
Tutorial description how to connect to the Test Network
Technical description of the network
Official notification for the community with links, details about the network and invitation to test

Metadata for an Asset definition

We'll have to update an asset definition example with metadata that is currently possible to add.

Current example:

import iroha2.data_model.asset as asset

time = asset.Definition(
    value_type=asset.ValueType.Quantity,
    id=asset.DefinitionId(name="time", domain_name="looking_glass"),
    # Here
    metadata={},
    mintable=False
)

According to @QuentinI, the proper keys for metadata have to be the Values and defined like that:

from iroha2.sys.iroha_data_model import Value

time = asset.Definition(
    value_type=asset.ValueType.Quantity,
    id=asset.DefinitionId(name="time", domain_name="looking_glass"),
    # Here
    metadata={"a": Value.U32(10)},
    mintable=False
)

This seems to work properly, judging by the Hyperledger Iroha Community Telegram.

I believe we'll need to discuss what Value types might be there, how those are used and add proper examples.

Create a MAINTAINERS.md file

Example: https://github.com/hyperledger-labs/solang/blob/main/MAINTAINERS.md Example of a pointer: https://github.com/hyperledger-labs/homebrew-solang/blob/main/MAINTAINERS.md

Create onboarding guide for software contributors

Onboarding guide for software devs to contribute to Iroha v2

Update to RC7

Need to add section on

domain-scoped triggers (#105)
TBD

Document the FFI bindgen behaviour

With the merge of hyperledger/iroha#2314 we've added a complex infrastructure of FFI bindgen, that needs to be followed closely. @mversic has created an excellent graphic that should be included in our tutorials if possible.

TikZ or SVG fine. Prefer TikZ.

Rename Branch iroha2 to iroha2-stable

The branch is iroha2 no longer exists. Now iroha2-stable is used instead. We need to rename wherever iroha2 branch is mentioned. For example here https://hyperledger.github.io/iroha-2-docs/guide/build-and-install.html#install-iroha-from-github .

Improve readability of the tutorial

Introduce more structure to individual topics (e.g. for the iroha 1 vs. iroha 2 comparison, install instructions, etc.)
Shorten the longer paragraphs.
Reduce the number of highlighted phrases/sentences, especially within the same paragraph and in cases when italic and bold are mixed together. Leave highlighting only when it is really needed and serves a purpose.

The intention is to make the tutorial easily scannable and just readable. This is better be done after #42

Add block queries to the tutorial

@appetrosyan I'd need to add these queries to the tutorial, right?

Originally posted by @outoftardis in hyperledger/iroha#2453 (comment)

Adjust granting role instructions

The fix in #2371 might require changes in the tutorial.

See comment: hyperledger/iroha#2371 (comment)

Replace git clone command in Python guide and remove checkout

git clone https://github.com/hyperledger/iroha-python/tree/iroha2 is incorrect url.

We need git clone https://github.com/hyperledger/iroha-python/ --branch iroha2

And we can remove git checkout, because previous command include checkout to iroha2 branch

Add markdownlint to CI

https://github.com/igorshubovych/markdownlint-cli

Improve the linking strategy within the tutorial

Establish clear navigation for different audiences (it's more than just the table of contents on the sidebar)
Add interlinking between chapters/topics. Not extensive but enough to guide the reader and point them to more info, advanced guide on the matter, point to what to read next, etc.

Question: with the current generation tool/setup, is that possible to create internal links without hardcoding them (e.g. similar to ref from restructuredtext?)

Should be addressed after #42 and #43

QA Testing of Iroha 2 Documentation

We need to perform QA testing on the Iroha 2 documentation to ensure the quality and accuracy of the content. https://hyperledger.github.io/iroha-2-docs/
Please go through each section and article, ensuring the content is accurate, clear, and easy to understand. Report any issues, inconsistencies, or errors that you find during the testing process. The following sections and article titles should be reviewed and tested:

Getting started

Tutorial

Blockchain

Configuration and Management

Troubleshooting

Advanced Mode

Iroha On Bare Metal
Hot Reload Iroha
Monitor Iroha Performance

API

Specification
Foreign Function Interfaces

Documenting Iroha

Code Snippets

Reports

CSD/RTGS linkages via on-chain scripting

Exchanging minted tokens

If we'll try the bash tutorial, it is missing what to do after we've minted the tokens.
I'd expect some part about exchanging those, for example, like this:

./iroha_client_cli asset transfer --from mad_hatter@looking_glass --to white_rabbit@looking_glass --asset-id tea#looking_glass --quantity 5

That part is missing. Moreover, even if I'll try, I'll have no permissions to do that:

Needs permission: can_transfer_user_assets

Pipeline(
    Event {
        entity_kind: Transaction,
        status: Rejected(
            Transaction(
                NotPermitted(
                    NotPermittedFail {
                        reason: "Failed to pass first check with Can't transfer assets of the other account. and second check with Account does not have the needed permission token: PermissionToken { name: \"can_transfer_user_assets\", params: {\"asset_id\": Id(AssetId(Id { definition_id: DefinitionId { name: \"tea\", domain_id: Id { name: \"looking_glass\" } }, account_id: Id { name: \"mad_hatter\", domain_id: Id { name: \"looking_glass\" } } }))} }..",
                    },
                ),
            ),
        ),
        hash: { Hash(d9a5e5099dfccba677edeb3b4b15cd30c9d6d206aac9b3de8a9a71dc9a731d70) },
    },
)

Sections to improve:

Include Alice in Wonderland Stylised graphics

In-keeping with the style of the text and the prevalence of execute @outoftardis suggested that we add some Alice in Wonderland-styled graphics.

We need something very schematic, preferably in the style of a book illustration that could be put as a watermark on the page, rather than a graphic.

Drawings that we need

Add versioning support

We need to support three versions of Iroha simultaneously:

Iroha2
Iroha2-dev
Iroha2-lts

We need to annotate features only present in dev and deprecated since lts.

Proposed solution

Have a custom vitepress environment e.g.

::: Dev-only

for features which are only available in Dev. Another environment for deprecated features (e.g. avaialable in LTS only) and one for difference in behaviour e.g.

::: Diff LTS Dev

In LTS this does X, 

But on `iroha2-dev` it does Y. 
:::

UML graph of object hierarchy

We should create and maintain a schematic representing object hierarchies in an Iroha blockchain. Specifically

Domain has a Account
TimeTrigger is a EventTrigger

etc.

Add a section about domain-scoped triggers

Domain-scoped triggers were introduced in hyperledger/iroha#2418.

Expand section on query behaviour

@Mingela Identified a potential misbehaviour in pagination, and also requested that we document the filtering and sorting behaviour in-detail.

We should create an advanced topic (or subsection in the existing queries), that explains how to create the required QueryBox object from the SDK, and how it's interpreted.

We should document the sorting behaviour (the fact that there isn't any), and give a couple of examples of

Query that returns a single object, and a filter that matches on that object so we get one value returned,
Query that returns a collection of objects, half of which are filtered and the remaining half is paginated.
Query that filters (Blocks) by timestamp.
Query that returns a collection of objects none of which are matched by the filter and nothing is returned.
Proof of idempotency (no WSV modifications => same query results).
Passthrough filter (all values are returned as is)
Query that filters by block height.

Add CI to automatically add labels to all issues in this repo

Whenever a new issue is created it should receive the iroha2 and documentation labels automatically.

FAQ update on compatibility of Iroha version 1 and 2

There was a question in Hyperledger Iroha Community Telegram.

I'll need to add a note on the compatibility between Iroha 1 and Iroha 2, so the users understand the general transition process.

Can someone upgrade to iroha2 from 1. Will the two be compatible?

Compatibility between the two is analogous to Bitcoin and ethereum, so generally, no
Cryptography and account structures are different between 1 and 2, so all users would have to generate new keys and link to their old account through a centralized service. None of the data from Iroha v1 would be accessible in v2 either

Expand the section on permissions (groups, validators)

custom permission validators
permission groups (#100 covered the basics about roles, might need more info)

FN; `with_precision` → `new_fixed_precision`

Review the language used in the tutorial

Remove the uncertainty: "you should probably", "it's probably a good idea"
Make changes to remove condescending language (you are trying to make it informal but I'd rethink some of the word choices; even calling things "easy" is not always appropriate)

Should be done after #42 and #43

Update syntax

https://github.com/hyperledger/iroha/pull/2211/files#diff-0a81716e7f7ce966f6aa320e74a038ce72098f8238527d429a2b3679f9f763b2R21

Correct set of registry for JavaScript client installation Guide

Should write echo "@iroha2:registry=https://nexus.iroha.tech/repository/npm-group/" > .npmrc instead
@iroha2:registry=https://nexus.iroha.tech/repository/npm-group/

Add a topic discussing metadata

The tutorial used to say that discussing metadata is outside of its scope but we might want to add something on this because there were questions from the community about this. #95 (comment)

from @6r1d:

we'll need to discuss what Value types might be there [in asset metadata], how those are used and add proper examples

New syntax for register Account/Asset/Domain

Now we support

RegisterBox::new(Account::new( … ))

Add FindAllPermissionTokenDefinitions query

See hyperledger/iroha#2517 (comment)

Add a mention of the installation @iroha2/crypto-target-node, hada, tsx for JS tutorial.

Three suggestions:

We need mention:
npm i @iroha2/crypto-target-node
npm i hada
npm i tsx -g
After that we need mention than .ts script should locate near node_modules
And after that we need mention than script run by command tsx example.ts

Add the openssl installation to the instruction.

Build guide doesn't work because we don't have openssl installation command.

Mark all statements about future releases

It'd be better to avoid statements about plans for future releases, new functionality, etc altogether, but for the ones that are essential, the ones that the users really should know about, we need to find a way to mark these in text so it'd be easy to regularly check their relevance and update the statements once the related features are implemented.

For example: add the same comment to each statement about ongoing work/future plans, so it'd be easy to find and check them each release. Plus would be good to have links to the open issues so we'd not spend time figuring out whether that feature was implemented or not.

Account registration: a tool to generate internal ed25519 keys

The "account registration" part of the manual contains a constant public key: ed0120a753146e75b910ae5e2994dc8adea9e7d87e5d53024cfa310ce992f17106f92c.
The source and the generation method of that key would need to be recorded in the documentation.

Add mention of iroha-javascript repository in JS guide.

We need to mention ours done repository of JS project which customers will do to clone and use from the box.
git clone https://github.com/hyperledger/iroha-javascript.git --branch iroha2

Add section on multi-signature accounts and transactions

The section should explain

Why multisig is important.
How to do simple multisig with both keys in one account
How to do multisig with separate accounts
Interaction with permission validation

This should be done after the main merges into the iroha2-stable branch are finished.

Documenting the permission types

Today, @baziorek asked a question in community about permission types that would be implemented for Iroha.
Current documentation explains we can add permission and that there's a FindPermissionTokensByAccountId query, but provides a limited information otherwise. Iroha 1 documentation, on the other hand, has a list of permissions that are typically available.

I think we should add more details: a list of permissions if we've got the same set or more details on how to define permissions.

UPD: according to @Arjentix, "the list of Iroha2 permissions is different and not specified anywhere outside code. In future users will be able to create there own permissions and validators using WASM".

Document FFI bindgen name mangling semantics

Aleksandr Petrosyan, [25.07.22 19:41]
That being said, we should document that convention too.

rust
module_name__method_name
StructName__inherent_fn
TraitName__assoc_fn_name

… 

Marin, [25.07.22 19:56]
[In reply to Aleksandr Petrosyan]
1. module__name::__method_name -> we do this for functions that have the same API but are implemented on different types. Namely this is for trait impls, i.e. poor man's generics like Clone 
2. yes
3. no, it's actually StructName__trait_method_name at the moment, but, in my opinion, should be reduced to 1. after 2488 (https://github.com/hyperledger/iroha/issues/2488)

Marin, [25.07.22 19:58]
1. for Clone in iroha_crypto gen_ffi_impl will create iroha_crypto::__clone in that library equivalent of Clone::clone

Aleksandr Petrosyan, [25.07.22 19:59]
This looks like we're mangling by hand.

Marin, [25.07.22 19:59]
which one?

Aleksandr Petrosyan, [25.07.22 20:00]
[In reply to Marin]
This one

Aleksandr Petrosyan, [25.07.22 20:00]
Under the circumstances I doubt we can do much better

Marin, [25.07.22 20:01]
I edited the comment

Aleksandr Petrosyan, [25.07.22 20:02]
[In reply to Marin]
Got it.

Add proper codeowners

We wan to have a separation of concerns in this repo so as not to ping someone unnecessarily I propose adding

@0x009922 as the code owner of the **/**.js
@outoftardis, @WRRicht3r as the code owner of **/**.md
and myself as the code owner of **.

Restructure the tutorial

Improve overall tutorial structure without altering the contents of the individual topics.

My notes regarding this:

Some sections should be renamed (e.g., "conclusions"), some information should be moved around and grouped differently presenting the contents of the tutorial in a logical way.
Most of the info in Appendix shouldn't be there at all, because it's not something additional to the tutorial, it's the essential part of the tutorial. This might be a question of renaming the chapter and splitting it in a one or two other chapters.
- My proposal is to have a "Learn the concepts" type of chapter: e.g. the concept of "genesis block" -- it's mentioned in lang-specific guides, but its only described in appendix and its definition is never referenced from the lang-specific guides. This might not be essential for people already familiar with blockchains but the tutorial is aiming at all kinds of audiences.
- Config files better be described in something like "Configurations" section.
- Why is this info https://hyperledger.github.io/iroha-2-docs/guide/appendix/running-iroha-on-bare-metal.html is in the appendix? It's just a more advanced topic than the lang-specific ones, people won't go looking in the appendix for this information.
Address this question: do we think there are a lot of people who are interested in iroha 1 vs. iroha 2 comparison before they learn what this tutorial can offer them? My proposal is to highlight this comparison but not put it at the very beginning.

We will also cover peer management in greater detail: adding and removing peers, maintaining a healthy network, and troubleshooting the issues that you might have in your real-world application.

adding and removing peers
maintaining a healthy network
troubleshooting for real-world applications