From a3b05f21647b831e8b637546284e60997a4ecc07 Mon Sep 17 00:00:00 2001 From: Alexandra Zorina <64249490+a-zorina@users.noreply.github.com> Date: Thu, 26 Sep 2024 17:12:05 +0200 Subject: [PATCH] Docs structure overhaul (#508) * Update new structure with recent changes Signed-off-by: a-zorina <64249490+a-zorina@users.noreply.github.com> * tweaks to structure after discussions Signed-off-by: a-zorina <64249490+a-zorina@users.noreply.github.com> * tweaks to Iroha Explained section Signed-off-by: a-zorina <64249490+a-zorina@users.noreply.github.com> * format fix 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 | 363 +++++++++--------- README.md | 2 +- .../blockchain/WarningFatQuery.vue | 0 src/{guide => }/blockchain/accounts.md | 0 src/{guide => }/blockchain/assets.md | 10 +- src/{guide => }/blockchain/consensus.md | 0 src/{guide => }/blockchain/data-model.md | 10 +- src/{guide => }/blockchain/domains.md | 0 src/{guide => }/blockchain/events.md | 0 src/{guide => }/blockchain/expressions.md | 0 src/{guide => }/blockchain/filters.md | 0 src/{guide => }/blockchain/instructions.md | 34 +- .../iroha-explained.md} | 10 +- src/{guide => }/blockchain/metadata.md | 6 +- src/{guide => }/blockchain/permissions.md | 2 +- src/{guide => }/blockchain/queries.md | 4 +- src/{guide => }/blockchain/transactions.md | 0 src/blockchain/trigger-examples.md | 213 ++++++++++ src/{guide => }/blockchain/triggers.md | 216 +---------- src/{guide => }/blockchain/wasm.md | 2 +- src/{guide => }/blockchain/world.md | 12 +- src/{guide => }/get-started/index.md | 20 +- .../get-started/install-iroha-2.md | 0 src/{guide => get-started}/iroha-2.md | 4 +- src/{guide => }/get-started/launch-iroha-2.md | 2 +- .../launch-iroha.docker-compose-output.ansi | 0 .../get-started/operate-iroha-2-via-cli.md | 10 +- .../advanced/running-iroha-on-bare-metal.md | 2 +- src/guide/configure/client-configuration.md | 2 +- .../configure/keys-for-network-deployment.md | 2 +- src/guide/configure/modes.md | 6 +- src/guide/configure/peer-management.md | 2 +- .../security/generating-cryptographic-keys.md | 2 +- .../tutorials.md => tutorials/index.md} | 12 +- .../{get-started => tutorials}/javascript.md | 2 +- .../{get-started => tutorials}/kotlin-java.md | 2 +- .../{get-started => tutorials}/python.md | 2 +- src/guide/{get-started => tutorials}/rust.md | 6 +- .../configuration-issues.md | 0 .../deployment-issues.md | 0 src/{guide/support.md => help/index.md} | 0 .../installation-issues.md | 4 +- .../integration-issues.md | 0 .../troubleshooting => help}/overview.md | 2 +- src/index.md | 12 +- src/reference/ffi.md | 2 +- src/reference/glossary.md | 8 +- src/reference/instructions.md | 16 +- src/reference/permissions.md | 2 +- src/reference/queries.md | 16 +- src/reference/torii-endpoints.md | 2 +- 51 files changed, 516 insertions(+), 508 deletions(-) rename src/{guide => }/blockchain/WarningFatQuery.vue (100%) rename src/{guide => }/blockchain/accounts.md (100%) rename src/{guide => }/blockchain/assets.md (82%) rename src/{guide => }/blockchain/consensus.md (100%) rename src/{guide => }/blockchain/data-model.md (72%) rename src/{guide => }/blockchain/domains.md (100%) rename src/{guide => }/blockchain/events.md (100%) rename src/{guide => }/blockchain/expressions.md (100%) rename src/{guide => }/blockchain/filters.md (100%) rename src/{guide => }/blockchain/instructions.md (80%) rename src/{guide/blockchain/how-iroha-works.md => blockchain/iroha-explained.md} (78%) rename src/{guide => }/blockchain/metadata.md (96%) rename src/{guide => }/blockchain/permissions.md (98%) rename src/{guide => }/blockchain/queries.md (95%) rename src/{guide => }/blockchain/transactions.md (100%) create mode 100644 src/blockchain/trigger-examples.md rename src/{guide => }/blockchain/triggers.md (61%) rename src/{guide => }/blockchain/wasm.md (99%) rename src/{guide => }/blockchain/world.md (58%) rename src/{guide => }/get-started/index.md (62%) rename src/{guide => }/get-started/install-iroha-2.md (100%) rename src/{guide => get-started}/iroha-2.md (98%) rename src/{guide => }/get-started/launch-iroha-2.md (96%) rename src/{guide => }/get-started/launch-iroha.docker-compose-output.ansi (100%) rename src/{guide => }/get-started/operate-iroha-2-via-cli.md (95%) rename src/guide/{get-started/tutorials.md => tutorials/index.md} (81%) rename src/guide/{get-started => tutorials}/javascript.md (99%) rename src/guide/{get-started => tutorials}/kotlin-java.md (99%) rename src/guide/{get-started => tutorials}/python.md (99%) rename src/guide/{get-started => tutorials}/rust.md (97%) rename src/{guide/troubleshooting => help}/configuration-issues.md (100%) rename src/{guide/troubleshooting => help}/deployment-issues.md (100%) rename src/{guide/support.md => help/index.md} (100%) rename src/{guide/troubleshooting => help}/installation-issues.md (95%) rename src/{guide/troubleshooting => help}/integration-issues.md (100%) rename src/{guide/troubleshooting => help}/overview.md (92%) diff --git a/.vitepress/config.mts b/.vitepress/config.mts index 3b2e97c6e..56de63b80 100644 --- a/.vitepress/config.mts +++ b/.vitepress/config.mts @@ -11,120 +11,139 @@ import { katex } from '@mdit/plugin-katex' function nav(): DefaultTheme.NavItem[] { return [ { - text: 'Guide', - items: [ - // { text: 'Get Started', link: '/guide/get-started/index' }, - // { text: 'Build and Install', link: '/guide/get-started/install-iroha' }, - // { text: 'Tutorials', link: '/guide/get-started/tutorials'}, - { - text: 'Get Started', - items: [ - { text: 'Install and Build', link: '/guide/get-started/install-iroha-2' }, - { text: 'SDK Tutorials', link: '/guide/get-started/tutorials' }, - ], - }, - // every part of guides needs an intro - { text: 'How Iroha Works', link: '/guide/blockchain/how-iroha-works' }, - { text: 'Security', link: '/guide/security/index' }, - { text: 'Configuration and Management', link: '/guide/configure/overview' }, - { text: 'Troubleshooting', link: '/guide/troubleshooting/overview' }, - ], + text: 'Get Started', + link: '/get-started/', + activeMatch: '/get-started/', + }, + { + text: 'Build on Iroha', + link: '/guide/tutorials/', + activeMatch: '/guide/', + }, + { + text: 'Iroha Explained', + link: '/blockchain/iroha-explained', + activeMatch: '/blockchain/', }, { text: 'Reference', link: '/reference/torii-endpoints', activeMatch: '/reference/', }, + { + text: 'Help', + link: '/help/', + activeMatch: '/help/', + }, ] } -function sidebarAPI(): DefaultTheme.SidebarItem[] { +function sidebarStart(): DefaultTheme.SidebarItem[] { return [ { - text: 'About', + text: 'Get Started', + link: '/get-started/', items: [ { - text: 'Glossary', - link: '/reference/glossary.md', + text: 'Install Iroha', + link: '/get-started/install-iroha-2', }, { - text: 'Naming Conventions', - link: '/reference/naming.md', + text: 'Launch Iroha', + link: '/get-started/launch-iroha-2', }, { - text: 'Compatibility Matrix', - link: '/reference/compatibility-matrix', + text: 'Operate Iroha via CLI', + link: '/get-started/operate-iroha-2-via-cli', }, { - text: 'Foreign Function Interfaces', - link: '/reference/ffi', + text: 'Iroha 2 vs. Iroha 1', + link: '/get-started/iroha-2', }, ], }, + ] +} + +function sidebarGuide(): DefaultTheme.SidebarItem[] { + return [ { - text: 'Reference', + text: 'SDK Tutorials', + link: '/guide/tutorials/', + collapsed: false, items: [ + /* a common lang-agnostic section will go here */ { - text: 'Torii Endpoints', - link: '/reference/torii-endpoints.md', + text: 'Rust', + link: '/guide/tutorials/rust', }, { - text: 'Data Model Schema', - link: '/reference/data-model-schema', + text: 'Python 3', + link: '/guide/tutorials/python', }, { - text: 'Instructions', - link: '/reference/instructions', + text: 'Kotlin/Java', + link: '/guide/tutorials/kotlin-java', }, { - text: 'Queries', - link: '/reference/queries.md', - }, - { - text: 'Permissions', - link: '/reference/permissions.md', + text: 'JavaScript', + link: '/guide/tutorials/javascript', }, ], }, - ] -} - -function sidebarGuide(): DefaultTheme.SidebarItem[] { - return [ { - text: 'Get Started', - link: '/guide/get-started/', + text: 'Configuration and Management', + collapsed: false, items: [ { - text: 'Install Iroha 2', - link: '/guide/get-started/install-iroha-2', - }, - { - text: 'Launch Iroha 2', - link: '/guide/get-started/launch-iroha-2', + text: 'Configure Iroha', + collapsed: true, + items: [ + { + text: 'Configuration Types', + link: '/guide/configure/configuration-types', + }, + { + text: 'Samples', + link: '/guide/configure/sample-configuration', + }, + { + text: 'Peer Configuration', + link: '/guide/configure/peer-configuration', + }, + { + text: 'Client Configuration', + link: '/guide/configure/client-configuration', + }, + { + text: 'Genesis Block', + link: '/guide/configure/genesis', + }, + { + text: 'Metadata and Store assets', + link: '/guide/configure/metadata-and-store-assets', + }, + ], }, { - text: 'Operate Iroha 2 via CLI', - link: '/guide/get-started/operate-iroha-2-via-cli', + text: 'Keys for Network Deployment', + link: '/guide/configure/keys-for-network-deployment.md', }, { - text: 'Iroha 2 vs. Iroha 1', - link: '/guide/iroha-2', + text: 'Peer Management', + link: '/guide/configure/peer-management', }, { - text: 'Receive support', - link: '/guide/support.md', + text: 'Public and Private Blockchains', + link: '/guide/configure/modes', }, ], }, { text: 'Security', - collapsed: true, + link: '/guide/security/', + collapsed: false, items: [ - { - text: 'Overview', - link: '/guide/security/', - }, { text: 'Security Principles', link: '/guide/security/security-principles.md', @@ -139,6 +158,7 @@ function sidebarGuide(): DefaultTheme.SidebarItem[] { }, { text: 'Public Key Cryptography', + collapsed: true, link: '/guide/security/public-key-cryptography.md', items: [ { @@ -154,232 +174,214 @@ function sidebarGuide(): DefaultTheme.SidebarItem[] { ], }, { - text: 'SDK Tutorials', - collapsed: true, + text: 'Advanced Use Cases', + collapsed: false, items: [ { - text: 'Introduction', - link: '/guide/get-started/tutorials', + text: 'Iroha On Bare Metal', + link: '/guide/advanced/running-iroha-on-bare-metal', }, - /* a common lang-agnostic section will go here */ { - text: 'Language-specific Guides', - items: [ - { - text: 'Python 3', - link: '/guide/get-started/python', - }, - { - text: 'Rust', - link: '/guide/get-started/rust', - }, - { - text: 'Kotlin/Java', - link: '/guide/get-started/kotlin-java', - }, - { - text: 'JavaScript', - link: '/guide/get-started/javascript', - }, - ], + text: 'Hot Reload Iroha', + link: '/guide/advanced/hot-reload', + }, + { + text: 'Monitor Iroha Performance', + link: '/guide/advanced/metrics', }, ], }, - { - text: 'Blockchain', + /* { + text: 'Reports', + collapsed: true, items: [ { - text: 'How Iroha Works', - link: '/guide/blockchain/how-iroha-works', + text: 'CSD/RTGS linkages via on-chain scripting', + link: '/guide/reports/csd-rtgs', }, + ], + }, +*/ + ] +} + +function sidebarChain(): DefaultTheme.SidebarItem[] { + return [ + { + text: 'Iroha Explained', + link: '/blockchain/iroha-explained', + items: [ { text: 'Overview', - collapsed: true, items: [ { text: 'Transactions', - link: '/guide/blockchain/transactions', + link: '/blockchain/transactions', }, { text: 'Consensus', - link: '/guide/blockchain/consensus', + link: '/blockchain/consensus', }, { text: 'Data Model', - link: '/guide/blockchain/data-model', + link: '/blockchain/data-model', }, ], }, { text: 'Entities', - collapsed: true, items: [ { text: 'Assets', - link: '/guide/blockchain/assets', + link: '/blockchain/assets', }, /* { text: 'Accounts', - link: '/guide/blockchain/accounts', + link: '/blockchain/accounts', }, { text: 'Domains', - link: '/guide/blockchain/domains', + link: '/blockchain/domains', }, */ { text: 'Metadata', - link: '/guide/blockchain/metadata', + link: '/blockchain/metadata', }, { text: 'Events', - link: '/guide/blockchain/events', + link: '/blockchain/events', }, { text: 'Filters', - link: '/guide/blockchain/filters', + link: '/blockchain/filters', }, { text: 'Triggers', - link: '/guide/blockchain/triggers', + link: '/blockchain/triggers', + items: [ + { + text: 'Event Triggers by Example', + link: '/blockchain/trigger-examples', + }, + ], }, { text: 'Queries', - link: '/guide/blockchain/queries', + link: '/blockchain/queries', }, { text: 'Permissions', - link: '/guide/blockchain/permissions', + link: '/blockchain/permissions', }, { text: 'World', - link: '/guide/blockchain/world', + link: '/blockchain/world', }, ], }, { text: 'Operations', - collapsed: true, items: [ { text: 'Instructions', - link: '/guide/blockchain/instructions', + link: '/blockchain/instructions', }, { text: 'Expressions', - link: '/guide/blockchain/expressions', + link: '/blockchain/expressions', }, { text: 'Web Assembly', - link: '/guide/blockchain/wasm', + link: '/blockchain/wasm', }, ], }, ], }, + ] +} + +function sidebarAPI(): DefaultTheme.SidebarItem[] { + return [ { - text: 'Configuration and Management', + text: 'About', items: [ { - text: 'Overview', - link: '/guide/configure/overview', - }, - { - text: 'Configure Iroha', - collapsed: true, - items: [ - { - text: 'Configuration Types', - link: '/guide/configure/configuration-types', - }, - { - text: 'Samples', - link: '/guide/configure/sample-configuration', - }, - { - text: 'Peer Configuration', - link: '/guide/configure/peer-configuration', - }, - { - text: 'Client Configuration', - link: '/guide/configure/client-configuration', - }, - { - text: 'Genesis Block', - link: '/guide/configure/genesis', - }, - { - text: 'Metadata and Store assets', - link: '/guide/configure/metadata-and-store-assets', - }, - ], + text: 'Glossary', + link: '/reference/glossary.md', }, { - text: 'Keys for Network Deployment', - link: '/guide/configure/keys-for-network-deployment.md', + text: 'Naming Conventions', + link: '/reference/naming.md', }, { - text: 'Peer Management', - link: '/guide/configure/peer-management', + text: 'Compatibility Matrix', + link: '/reference/compatibility-matrix', }, { - text: 'Public and Private Blockchains', - link: '/guide/configure/modes', + text: 'Foreign Function Interfaces', + link: '/reference/ffi', }, ], }, { - text: 'Troubleshooting', - collapsed: true, + text: 'Reference', items: [ { - text: 'Overview', - link: '/guide/troubleshooting/overview', + text: 'Torii Endpoints', + link: '/reference/torii-endpoints.md', }, { - text: 'Installation', - link: '/guide/troubleshooting/installation-issues', + text: 'Data Model Schema', + link: '/reference/data-model-schema', }, { - text: 'Configuration', - link: '/guide/troubleshooting/configuration-issues', + text: 'Instructions', + link: '/reference/instructions', }, { - text: 'Deployment', - link: '/guide/troubleshooting/deployment-issues', + text: 'Queries', + link: '/reference/queries.md', }, { - text: 'Integration', - link: '/guide/troubleshooting/integration-issues', + text: 'Permissions', + link: '/reference/permissions.md', }, ], }, + ] +} + +function sidebarHelp(): DefaultTheme.SidebarItem[] { + return [ { - text: 'Advanced Mode', - collapsed: true, + text: 'Receive support', + link: '/help/', + }, + { + text: 'Troubleshooting', items: [ { - text: 'Iroha On Bare Metal', - link: '/guide/advanced/running-iroha-on-bare-metal', + text: 'Overview', + link: '/help/overview', }, { - text: 'Hot Reload Iroha', - link: '/guide/advanced/hot-reload', + text: 'Installation', + link: '/help/installation-issues', }, { - text: 'Monitor Iroha Performance', - link: '/guide/advanced/metrics', + text: 'Configuration', + link: '/help/configuration-issues', }, - ], - }, - { - text: 'Reports', - collapsed: true, - items: [ { - text: 'CSD/RTGS linkages via on-chain scripting', - link: '/guide/reports/csd-rtgs', + text: 'Deployment', + link: '/help/deployment-issues', + }, + { + text: 'Integration', + link: '/help/integration-issues', }, ], }, @@ -466,8 +468,11 @@ export default defineConfig({ outline: [2, 3], sidebar: { + '/get-started/': sidebarStart(), '/guide/': sidebarGuide(), + '/blockchain/': sidebarChain(), '/reference/': sidebarAPI(), + '/help/': sidebarHelp(), }, search: { diff --git a/README.md b/README.md index 023059c38..865fe41d1 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ The tutorial is suitable for both experienced and novice users. It explains Iroh - [Kotlin/Java](https://hyperledger.github.io/iroha-2-docs/guide/kotlin-java.html) - [Javascript (TypeScript)](https://hyperledger.github.io/iroha-2-docs/guide/javascript.html) -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. +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/get-started/iroha-2.html) from its previous version. Check the [Hyperledger Iroha](https://github.com/hyperledger/iroha/) repository for more detailed information about API and available features. diff --git a/src/guide/blockchain/WarningFatQuery.vue b/src/blockchain/WarningFatQuery.vue similarity index 100% rename from src/guide/blockchain/WarningFatQuery.vue rename to src/blockchain/WarningFatQuery.vue diff --git a/src/guide/blockchain/accounts.md b/src/blockchain/accounts.md similarity index 100% rename from src/guide/blockchain/accounts.md rename to src/blockchain/accounts.md diff --git a/src/guide/blockchain/assets.md b/src/blockchain/assets.md similarity index 82% rename from src/guide/blockchain/assets.md rename to src/blockchain/assets.md index cf2875e57..844f7c13a 100644 --- a/src/guide/blockchain/assets.md +++ b/src/blockchain/assets.md @@ -76,8 +76,8 @@ 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-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) -- [JavaScript/TypeScript](/guide/get-started/javascript.md#_5-registering-and-minting-assets) +- [CLI](/get-started/operate-iroha-2-via-cli.md#_6-register-and-mint-assets) +- [Rust](/guide/tutorials/rust.md#_5-registering-and-minting-assets) +- [Kotlin/Java](/guide/tutorials/kotlin-java.md#_5-registering-and-minting-assets) +- [Python](/guide/tutorials/python.md#_5-registering-and-minting-assets) +- [JavaScript/TypeScript](/guide/tutorials/javascript.md#_5-registering-and-minting-assets) diff --git a/src/guide/blockchain/consensus.md b/src/blockchain/consensus.md similarity index 100% rename from src/guide/blockchain/consensus.md rename to src/blockchain/consensus.md diff --git a/src/guide/blockchain/data-model.md b/src/blockchain/data-model.md similarity index 72% rename from src/guide/blockchain/data-model.md rename to src/blockchain/data-model.md index af4d16bbc..ce33535c3 100644 --- a/src/guide/blockchain/data-model.md +++ b/src/blockchain/data-model.md @@ -87,11 +87,11 @@ domain_looking_glass *-- account_rabbit : registered in | Language | Guide | | --------------------- |--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| 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) | -| JavaScript/TypeScript | Register a [domain](/guide/get-started/javascript.md#_3-registering-a-domain), an [account](/guide/get-started/javascript.md#_4-registering-an-account), an [asset](/guide/get-started/javascript.md#_5-registering-and-minting-assets) | +| CLI | Register a [domain](/get-started/operate-iroha-2-via-cli.md#_3-register-a-domain), an [account](/get-started/operate-iroha-2-via-cli.md#_4-register-an-account), an [asset](/get-started/operate-iroha-2-via-cli.md#_6-register-and-mint-assets) | +| Rust | Register a [domain](/guide/tutorials/rust.md#_3-registering-a-domain), an [account](/guide/tutorials/rust.md#_4-registering-an-account), an [asset](/guide/tutorials/rust.md#_5-registering-and-minting-assets) | +| Kotlin/Java | Register a [domain](/guide/tutorials/kotlin-java.md#_3-querying-and-registering-domains), an [account](/guide/tutorials/kotlin-java.md#_4-registering-an-account), an [asset](/guide/tutorials/kotlin-java.md#_5-registering-and-minting-assets) | +| Python | Register a [domain](/guide/tutorials/python.md#_3-registering-a-domain), an [account](/guide/tutorials/python.md#_4-registering-an-account), an [asset](/guide/tutorials/python.md#_5-registering-and-minting-assets) | +| JavaScript/TypeScript | Register a [domain](/guide/tutorials/javascript.md#_3-registering-a-domain), an [account](/guide/tutorials/javascript.md#_4-registering-an-account), an [asset](/guide/tutorials/javascript.md#_5-registering-and-minting-assets) | ::: diff --git a/src/guide/blockchain/domains.md b/src/blockchain/domains.md similarity index 100% rename from src/guide/blockchain/domains.md rename to src/blockchain/domains.md diff --git a/src/guide/blockchain/events.md b/src/blockchain/events.md similarity index 100% rename from src/guide/blockchain/events.md rename to src/blockchain/events.md diff --git a/src/guide/blockchain/expressions.md b/src/blockchain/expressions.md similarity index 100% rename from src/guide/blockchain/expressions.md rename to src/blockchain/expressions.md diff --git a/src/guide/blockchain/filters.md b/src/blockchain/filters.md similarity index 100% rename from src/guide/blockchain/filters.md rename to src/blockchain/filters.md diff --git a/src/guide/blockchain/instructions.md b/src/blockchain/instructions.md similarity index 80% rename from src/guide/blockchain/instructions.md rename to src/blockchain/instructions.md index a53df0067..45f9b34fc 100644 --- a/src/guide/blockchain/instructions.md +++ b/src/blockchain/instructions.md @@ -1,6 +1,6 @@ # Iroha Special Instructions -When we spoke about [how Iroha operates](/guide/blockchain/how-iroha-works), we +When we spoke about [how Iroha operates](/blockchain/iroha-explained), we said that Iroha Special Instructions are the only way to modify the world state. So, what kind of special instructions do we have? If you've read the language-specific guides in this tutorial, you've already seen a couple of @@ -40,7 +40,7 @@ all you need is the object that you want to register. | [Mint/Burn](#mint-burn) | assets, triggers (trigger repetitions), permission tokens | accounts | | [SetKeyValue/RemoveKeyValue](#setkeyvalue-removekeyvalue) | any objects that have [metadata](./metadata.md): accounts, domains, assets, asset definitions, triggers, transactions | | | [NewParameter/SetParameter](#newparameter-setparameter) | Iroha configuration parameters | | -| [Grant/Revoke](#grant-revoke) | [roles, permission tokens](/guide/blockchain/permissions.md) | accounts | +| [Grant/Revoke](#grant-revoke) | [roles, permission tokens](/blockchain/permissions.md) | accounts | | [Transfer](#transfer) | assets | accounts | | [ExecuteTrigger](#executetrigger) | triggers | | | [If, Pair, Sequence](#composite-instructions) | any instructions | | @@ -109,11 +109,11 @@ process of registering objects in a blockchain: | Language | Guide | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| 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) | -| JavaScript/TypeScript | Register a [domain](/guide/get-started/javascript.md#_3-registering-a-domain), an [account](/guide/get-started/javascript.md#_4-registering-an-account), an [asset](/guide/get-started/javascript.md#_5-registering-and-minting-assets) | +| CLI | Register a [domain](/get-started/operate-iroha-2-via-cli.md#_3-register-a-domain), an [account](/get-started/operate-iroha-2-via-cli.md#_4-register-an-account), an [asset](/get-started/operate-iroha-2-via-cli.md#_6-register-and-mint-assets) | +| Rust | Register a [domain](/guide/tutorials/rust.md#_3-registering-a-domain), an [account](/guide/tutorials/rust.md#_4-registering-an-account), an [asset](/guide/tutorials/rust.md#_5-registering-and-minting-assets) | +| Kotlin/Java | Register a [domain](/guide/tutorials/kotlin-java.md#_3-querying-and-registering-domains), an [account](/guide/tutorials/kotlin-java.md#_4-registering-an-account), an [asset](/guide/tutorials/kotlin-java.md#_5-registering-and-minting-assets) | +| Python | Register a [domain](/guide/tutorials/python.md#_3-registering-a-domain), an [account](/guide/tutorials/python.md#_4-registering-an-account), an [asset](/guide/tutorials/python.md#_5-registering-and-minting-assets) | +| JavaScript/TypeScript | Register a [domain](/guide/tutorials/javascript.md#_3-registering-a-domain), an [account](/guide/tutorials/javascript.md#_4-registering-an-account), an [asset](/guide/tutorials/javascript.md#_5-registering-and-minting-assets) | ## Mint/Burn @@ -130,16 +130,16 @@ 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-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) -- [JavaScript/TypeScript ](/guide/get-started/javascript.md#_5-registering-and-minting-assets) +- [CLI](/get-started/operate-iroha-2-via-cli.md#_6-register-and-mint-assets) +- [Rust](/guide/tutorials/rust.md#_5-registering-and-minting-assets) +- [Kotlin/Java](/guide/tutorials/kotlin-java.md#_5-registering-and-minting-assets) +- [Python](/guide/tutorials/python.md#_5-registering-and-minting-assets) +- [JavaScript/TypeScript ](/guide/tutorials/javascript.md#_5-registering-and-minting-assets) Here are examples of burning assets: -- [CLI](/guide/get-started/operate-iroha-2-via-cli.md#_8-burn-assets) -- [Rust](/guide/get-started/rust.md#_7-burning-assets) +- [CLI](/get-started/operate-iroha-2-via-cli.md#_8-burn-assets) +- [Rust](/guide/tutorials/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-2-via-cli.md#_7-transfer-assets) or [Rust](/guide/get-started/rust.md#_6-transferring-assets). +transfer assets with [CLI](/get-started/operate-iroha-2-via-cli.md#_7-transfer-assets) or [Rust](/guide/tutorials/rust.md#_6-transferring-assets). @@ -166,7 +166,7 @@ be used carefully. ## `SetKeyValue`/`RemoveKeyValue` These instructions are used with the key/value -[`Store` asset type](/guide/blockchain/metadata.md#store-asset). This use +[`Store` asset type](/blockchain/metadata.md#store-asset). This use case has not received much attention so far, because storing data in the blockchain is a rather advanced topic that we shall cover separately. @@ -174,7 +174,7 @@ blockchain is a rather advanced topic that we shall cover separately. With these instructions, you can create (`NewParameter`) and change (`SetParameter`) chain-wide -[configuration parameters](./../configure/client-configuration.md) for +[configuration parameters](/guide/configure/client-configuration.md) for Iroha. ## `ExecuteTrigger` diff --git a/src/guide/blockchain/how-iroha-works.md b/src/blockchain/iroha-explained.md similarity index 78% rename from src/guide/blockchain/how-iroha-works.md rename to src/blockchain/iroha-explained.md index bf0142ca0..cef179cb0 100644 --- a/src/guide/blockchain/how-iroha-works.md +++ b/src/blockchain/iroha-explained.md @@ -1,26 +1,26 @@ -# How Iroha works +# Iroha Explained 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-2-via-cli.md)) +ours the client binary (for example: [`iroha`](/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 users to use the network, and lock others out. Any operation that is run on-chain is written in terms of -[Iroha Special Instructions (ISI)](/guide/blockchain/instructions.md), and +[Iroha Special Instructions (ISI)](/blockchain/instructions.md), and there is no other way of modifying the world state. Each interaction with the blockchain is done via a _transaction_. A transaction is a collection of _instructions_, which are either glued together in sequence or compiled into what we affectionately call a -[WASM](/guide/blockchain/wasm.md) blob. You need these instructions to +[WASM](/blockchain/wasm.md) blob. You need these instructions to register an account, remove an account, add X amount of Y currency, and so on. To read the information encoded in the blocks of a blockchain (the current -world state), you use [queries](/guide/blockchain/queries.md). Queries are +world state), you use [queries](/blockchain/queries.md). Queries are submitted like instructions, but they're not tracked and recorded in blocks, so they're much more lightweight. If you use queries as part of complicated logic (e.g. inside WASM), they have a non-negligible impact on diff --git a/src/guide/blockchain/metadata.md b/src/blockchain/metadata.md similarity index 96% rename from src/guide/blockchain/metadata.md rename to src/blockchain/metadata.md index ba432d3ba..4b8514b1a 100644 --- a/src/guide/blockchain/metadata.md +++ b/src/blockchain/metadata.md @@ -24,7 +24,7 @@ The metadata can be of very different types, such as: - request results The object's metadata can be transferred one by one, or in bulk via a -[WASM](/guide/blockchain/wasm.md) transaction. The `Store` asset type is +[WASM](/blockchain/wasm.md) transaction. The `Store` asset type is used for working with metadata. Let's take a closer look at this asset type. @@ -91,7 +91,7 @@ let set_hat_color = SetKeyValueBox::new( ## Working with metadata The following example showcases how to register and grant a -[role](/guide/blockchain/permissions.md#permission-groups-roles) to access +[role](/blockchain/permissions.md#permission-groups-roles) to access another account's metadata. ::: details Example @@ -148,7 +148,7 @@ fn register_and_grant_role_for_metadata_access() -> Result<()> { ## Queries You can get the key value of an object metadata using -[queries](/guide/blockchain/queries.md): +[queries](/blockchain/queries.md): - [`FindAccountKeyValueByIdAndKey`](/reference/queries.md#findaccountkeyvaluebyidandkey) - [`FindAssetKeyValueByIdAndKey`](/reference/queries.md#findassetkeyvaluebyidandkey) diff --git a/src/guide/blockchain/permissions.md b/src/blockchain/permissions.md similarity index 98% rename from src/guide/blockchain/permissions.md rename to src/blockchain/permissions.md index f2195ccb8..c7dc0efbd 100644 --- a/src/guide/blockchain/permissions.md +++ b/src/blockchain/permissions.md @@ -76,7 +76,7 @@ Before granting a role to an account, the role should be registered first. ### Register a new role Let's register a new role that, when granted, will allow another account -access to the [metadata](/guide/blockchain/metadata.md) in Mouse's account: +access to the [metadata](/blockchain/metadata.md) in Mouse's account: ```rust let role_id = RoleId::from_str("ACCESS_TO_MOUSE_METADATA")?; diff --git a/src/guide/blockchain/queries.md b/src/blockchain/queries.md similarity index 95% rename from src/guide/blockchain/queries.md rename to src/blockchain/queries.md index b82ccb8c8..5fcb24ee8 100644 --- a/src/guide/blockchain/queries.md +++ b/src/blockchain/queries.md @@ -77,14 +77,14 @@ that match the specified filter. ## Sorting -Iroha 2 can sort items with [metadata](/guide/blockchain/metadata.md) +Iroha 2 can sort items with [metadata](/blockchain/metadata.md) lexicographically if you provide a key to sort by during the construction of the query. A typical use case is for accounts to have a `registered-on` metadata entry, which, when sorted, allows you to view the account registration history. Sorting only applies to entities that have -[metadata](/guide/blockchain/metadata.md), as the metadata key is used to +[metadata](/blockchain/metadata.md), as the metadata key is used to sort query results. You can combine sorting with pagination and filters. Note that sorting is diff --git a/src/guide/blockchain/transactions.md b/src/blockchain/transactions.md similarity index 100% rename from src/guide/blockchain/transactions.md rename to src/blockchain/transactions.md diff --git a/src/blockchain/trigger-examples.md b/src/blockchain/trigger-examples.md new file mode 100644 index 000000000..c0b867bd1 --- /dev/null +++ b/src/blockchain/trigger-examples.md @@ -0,0 +1,213 @@ +# Event Triggers by Example + +Now that we've gotten the theory out of the way, we want to sit down with +the Mad Hatter, the March Hare, and the Dormouse and see if we can spin. +Let's start with an event trigger that shows the basics. + +## 1. Register accounts + +We have `mad_hatter@wonderland`, `dormouse@wonderland`, +`march_hare@wonderland` all of which share the fixed-point asset of +`tea#wonderland`. The Mad Hatter has the tea pot, while the rest have a +single cup of tea. When `alice@wonderland` had arrived, she got a nice cup +of tea as well. + +The way we get them in Rust code looks like this: + +```rust +let tea = AssetDefinitionId::new("tea", "wonderland")?; +let mad_hatter = AccountId::new("mad_hatter", "wonderland")?; +let dormouse = AccountId::new("dormouse", "wonderland")?; +let march_hare = AccountId::new("march_hare", "wonderland")?; +vec![ + RegisterBox::new(IdentifiableBox::from(NewAccount::new(mad_hatter.clone()))), + RegisterBox::new(IdentifiableBox::from(NewAccount::new(march_hare.clone()))), + RegisterBox::new(IdentifiableBox::from(NewAccount::new(dormouse.clone()))), + RegisterBox::new(IdentifiableBox::from(AssetDefinition::new_fixed(tea.clone()))), + MintBox::new(Value::Fixed(100.0_f64.try_into()?), IdBox::AssetId(AssetId::new(tea.clone(), mad_hatter.clone()))) + MintBox::new(Value::Fixed(1.0_f64.try_into()?), IdBox::AssetId(AssetId::new(tea.clone(), march_hare.clone()))) + MintBox::new(Value::Fixed(1.0_f64.try_into()?), IdBox::AssetId(AssetId::new(tea.clone(), dormouse.clone()))) + MintBox::new(Value::Fixed(1.0_f64.try_into()?), IdBox::AssetId(AssetId::new(tea.clone(), alice.clone()))) +] +``` + +## 2. Register a trigger + +We want a smart contract that transfers some `tea` from +`mad_hatter@wonderland` to `alice@wonderland` when her tea reduces by a +single cup. + +For that we need to register a trigger. The boilerplate is straightforward: + +```rust +let id = TriggerId::new(Name::new("refresh_tea")); + +let metadata = Metadata::new(); + +let executable = vec![ + TransferBox::new( + IdBox::AssetId(AssetId::new(tea.clone(), mad_hatter.clone())), + Value::Fixed(1_f64.try_into()?), + IdBox::AssetId(AssetId::new(alice.clone(), mad_hatter.clone())), + ) +]; + +let repeats = Repeats::Indefinitely; + +let technical_account = mad_hatter.clone(); + +let filter = _ // ... +``` + +## 3. Define an event filter + +The event filter is where we need to spend some time and think. So far +we've seen the `Pipeline` variety of filters. This time around, the filter +is a `Data` kind. This type of filter is a tuple with a single variant, +which is a `FilterOpt` of an `EntityFilter`: + +- `FilterOpt` stands for Optional Filter. It can either `AcceptAll` or + accept `BySome` of another `Filter`. +- An `EntityFilter` is a filter that matches `ByAccount` in our case, but + can match by many other means. It wraps an `AccountFilter`, which matches + various events produced on accounts. + +What we want to do is create an event filter for when `alice@wonderland` +drinks some of her tea, or, in other words, reduces the `tea` asset by any +amount. To do this with the current API, we need to work bottom up. + +An `IdFilter` is a filter that `.matches(event) == true` if and only if the +identities are exactly the same. Everything that has an `Id` has a +corresponding `IdFilter`. + +::: info + +An `IdFilter` is a parametric structure, an `IdFilter` that works on +`Peer`s has the type `IdFilter` and is not the same type as an +`IdFilter` that works with `AccountId`; `IdFilter` and `ByRemoved`. + +```rust +use FilterOpt::{BySome, AcceptAll}; + +let asset_filter = AssetFilter::new(BySome(IdFilter(tea.clone())), BySome(AssetEventFilter::ByRemoved)); +``` + +So far so good? + +Next, we want a filter that looks for changes in an asset for an account. +Specifically: + +```rust +let account_filter = AccountFilter::new(BySome(IdFilter(alice.clone())), BySome(asset_filter)); +``` + +Now, because of the way that `parity_scale_codec` works, we need to wrap +this in various boxes. + +```rust +let filter = EventFilter::Data(BySome(EntityFilter::ByAccount(account_filter))); +``` + +## 4. Create a `Trigger` instance + +After this somewhat laborious filter combination, we can create an `Action` + +```rust +let action = Action { + executable, repeats, technical_account, filter, metadata +} +``` + +Which allows us to create an instance of a `Trigger`. + +```rust +let trigger = Trigger::new(id, action); +``` + +## 5. Create a transaction + +Finally, in order to get said trigger onto the blockchain, we create a +transaction with the following single instruction: + +```rust +Instruction::Register(RegisterBox::new(IdentifiableBox::Trigger(Box::new(trigger)))); +``` + +## How it works + +The technical details of the created transaction are summarised as follows: + +- The (normal) instructions that either got submitted from WASM or directly + from the client get executed. If there were any triggers that should have + been registered, they get registered. +- Using the total set of events that got generated during the execution of + instructions, the triggers (including some that got registered just this + round) get executed. +- The events produced in the previous step get scheduled for execution in + the next block. + +::: info + +The reason why the events caused by the execution of triggers get processed +in the next block is that we don't want two triggers to inadvertently cause +an infinite loop of instruction execution and break consensus. + +::: + +Now each time Alice drinks some tea, the Mad Hatter pours in a whole new +cup. The keen eyed among you will have noticed that the amount that Alice +drinks is irrelevant to how much tea will be transferred. Alice may take a +tiny sip and still be poured a whole new cup's worth. + +::: info + +We intend to address this issue in the future so that an emitted event also +has an attached `Value`. We also intend to provide more event filter types. +For example, we will have filters that match when the asset: + +- Decreases by any amount (current behaviour) +- Decreases by more than (or exactly) the specific amount in one + instruction +- Decreases to below a certain threshold + + + +Only the first type of event filter is implemented now, and the other two +can be emulated using a WASM smart contract as the `Executable`. + +::: + +::: details Why not WASM + +The above observation can be generalised. WASM can do any logic that a +Turing complete machine could, using the data available via queries. So in +theory for event-based triggers, you could create an `AcceptAll` event +filter and do all of the processing using the key-value store as persistent +storage, and then, determining if you want to execute using +easy-to-understand Rust code, and not our admittedly cumbersome, +`EventFilters`. + +We don't want that. WASM takes up significantly more space, and takes +longer to execute compared to plain ISI, which are slower than +`EventFilters`. We want you to want to use the `EventFilters` because they +would make the process much more efficient, and we are working tirelessly +to make the experience of using event filters much less gruelling. + +However, as was mentioned previously on several occasions, implementing a +feature properly takes time and effort. Ergonomics must be balanced against +safety and reliability, so we cannot just make things easier to use. We +want them to retain many of the advantages of strong typing. + + + +This is all a work in progress. Our code is in flux. We need time to play +around with a particular implementation to optimise it. + +::: diff --git a/src/guide/blockchain/triggers.md b/src/blockchain/triggers.md similarity index 61% rename from src/guide/blockchain/triggers.md rename to src/blockchain/triggers.md index ad623de4c..77b287867 100644 --- a/src/guide/blockchain/triggers.md +++ b/src/blockchain/triggers.md @@ -117,7 +117,7 @@ accounts, domains, assets, or transactions. This is the storage for trigger data. You can learn more about metadata in a -[dedicated section](/guide/blockchain/metadata.md). +[dedicated section](/blockchain/metadata.md). ## How Triggers Work @@ -324,220 +324,6 @@ last. ::: -## Event Triggers by Example - -Now that we've gotten the theory out of the way, we want to sit down with -the Mad Hatter, the March Hare, and the Dormouse and see if we can spin. -Let's start with an event trigger that shows the basics. - -### 1. Register accounts - -We have `mad_hatter@wonderland`, `dormouse@wonderland`, -`march_hare@wonderland` all of which share the fixed-point asset of -`tea#wonderland`. The Mad Hatter has the tea pot, while the rest have a -single cup of tea. When `alice@wonderland` had arrived, she got a nice cup -of tea as well. - -The way we get them in Rust code looks like this: - -```rust -let tea = AssetDefinitionId::new("tea", "wonderland")?; -let mad_hatter = AccountId::new("mad_hatter", "wonderland")?; -let dormouse = AccountId::new("dormouse", "wonderland")?; -let march_hare = AccountId::new("march_hare", "wonderland")?; -vec![ - RegisterBox::new(IdentifiableBox::from(NewAccount::new(mad_hatter.clone()))), - RegisterBox::new(IdentifiableBox::from(NewAccount::new(march_hare.clone()))), - RegisterBox::new(IdentifiableBox::from(NewAccount::new(dormouse.clone()))), - RegisterBox::new(IdentifiableBox::from(AssetDefinition::new_fixed(tea.clone()))), - MintBox::new(Value::Fixed(100.0_f64.try_into()?), IdBox::AssetId(AssetId::new(tea.clone(), mad_hatter.clone()))) - MintBox::new(Value::Fixed(1.0_f64.try_into()?), IdBox::AssetId(AssetId::new(tea.clone(), march_hare.clone()))) - MintBox::new(Value::Fixed(1.0_f64.try_into()?), IdBox::AssetId(AssetId::new(tea.clone(), dormouse.clone()))) - MintBox::new(Value::Fixed(1.0_f64.try_into()?), IdBox::AssetId(AssetId::new(tea.clone(), alice.clone()))) -] -``` - -### 2. Register a trigger - -We want a smart contract that transfers some `tea` from -`mad_hatter@wonderland` to `alice@wonderland` when her tea reduces by a -single cup. - -For that we need to register a trigger. The boilerplate is straightforward: - -```rust -let id = TriggerId::new(Name::new("refresh_tea")); - -let metadata = Metadata::new(); - -let executable = vec![ - TransferBox::new( - IdBox::AssetId(AssetId::new(tea.clone(), mad_hatter.clone())), - Value::Fixed(1_f64.try_into()?), - IdBox::AssetId(AssetId::new(alice.clone(), mad_hatter.clone())), - ) -]; - -let repeats = Repeats::Indefinitely; - -let technical_account = mad_hatter.clone(); - -let filter = _ // ... -``` - -### 3. Define an event filter - -The event filter is where we need to spend some time and think. So far -we've seen the `Pipeline` variety of filters. This time around, the filter -is a `Data` kind. This type of filter is a tuple with a single variant, -which is a `FilterOpt` of an `EntityFilter`: - -- `FilterOpt` stands for Optional Filter. It can either `AcceptAll` or - accept `BySome` of another `Filter`. -- An `EntityFilter` is a filter that matches `ByAccount` in our case, but - can match by many other means. It wraps an `AccountFilter`, which matches - various events produced on accounts. - -What we want to do is create an event filter for when `alice@wonderland` -drinks some of her tea, or, in other words, reduces the `tea` asset by any -amount. To do this with the current API, we need to work bottom up. - -An `IdFilter` is a filter that `.matches(event) == true` if and only if the -identities are exactly the same. Everything that has an `Id` has a -corresponding `IdFilter`. - -::: info - -An `IdFilter` is a parametric structure, an `IdFilter` that works on -`Peer`s has the type `IdFilter` and is not the same type as an -`IdFilter` that works with `AccountId`; `IdFilter` and `ByRemoved`. - -```rust -use FilterOpt::{BySome, AcceptAll}; - -let asset_filter = AssetFilter::new(BySome(IdFilter(tea.clone())), BySome(AssetEventFilter::ByRemoved)); -``` - -So far so good? - -Next, we want a filter that looks for changes in an asset for an account. -Specifically: - -```rust -let account_filter = AccountFilter::new(BySome(IdFilter(alice.clone())), BySome(asset_filter)); -``` - -Now, because of the way that `parity_scale_codec` works, we need to wrap -this in various boxes. - -```rust -let filter = EventFilter::Data(BySome(EntityFilter::ByAccount(account_filter))); -``` - -### 4. Create a `Trigger` instance - -After this somewhat laborious filter combination, we can create an `Action` - -```rust -let action = Action { - executable, repeats, technical_account, filter, metadata -} -``` - -Which allows us to create an instance of a `Trigger`. - -```rust -let trigger = Trigger::new(id, action); -``` - -### 5. Create a transaction - -Finally, in order to get said trigger onto the blockchain, we create a -transaction with the following single instruction: - -```rust -Instruction::Register(RegisterBox::new(IdentifiableBox::Trigger(Box::new(trigger)))); -``` - -### How it works - -The technical details of the created transaction are summarised as follows: - -- The (normal) instructions that either got submitted from WASM or directly - from the client get executed. If there were any triggers that should have - been registered, they get registered. -- Using the total set of events that got generated during the execution of - instructions, the triggers (including some that got registered just this - round) get executed. -- The events produced in the previous step get scheduled for execution in - the next block. - -::: info - -The reason why the events caused by the execution of triggers get processed -in the next block is that we don't want two triggers to inadvertently cause -an infinite loop of instruction execution and break consensus. - -::: - -Now each time Alice drinks some tea, the Mad Hatter pours in a whole new -cup. The keen eyed among you will have noticed that the amount that Alice -drinks is irrelevant to how much tea will be transferred. Alice may take a -tiny sip and still be poured a whole new cup's worth. - -::: info - -We intend to address this issue in the future so that an emitted event also -has an attached `Value`. We also intend to provide more event filter types. -For example, we will have filters that match when the asset: - -- Decreases by any amount (current behaviour) -- Decreases by more than (or exactly) the specific amount in one - instruction -- Decreases to below a certain threshold - - - -Only the first type of event filter is implemented now, and the other two -can be emulated using a WASM smart contract as the `Executable`. - -::: - -::: details Why not WASM - -The above observation can be generalised. WASM can do any logic that a -Turing complete machine could, using the data available via queries. So in -theory for event-based triggers, you could create an `AcceptAll` event -filter and do all of the processing using the key-value store as persistent -storage, and then, determining if you want to execute using -easy-to-understand Rust code, and not our admittedly cumbersome, -`EventFilters`. - -We don't want that. WASM takes up significantly more space, and takes -longer to execute compared to plain ISI, which are slower than -`EventFilters`. We want you to want to use the `EventFilters` because they -would make the process much more efficient, and we are working tirelessly -to make the experience of using event filters much less gruelling. - -However, as was mentioned previously on several occasions, implementing a -feature properly takes time and effort. Ergonomics must be balanced against -safety and reliability, so we cannot just make things easier to use. We -want them to retain many of the advantages of strong typing. - - - -This is all a work in progress. Our code is in flux. We need time to play -around with a particular implementation to optimise it. - -::: - ## Supported ISI All Iroha Special Instructions work with triggers, specifically: diff --git a/src/guide/blockchain/wasm.md b/src/blockchain/wasm.md similarity index 99% rename from src/guide/blockchain/wasm.md rename to src/blockchain/wasm.md index 1c25bb59e..1dfd05e99 100644 --- a/src/guide/blockchain/wasm.md +++ b/src/blockchain/wasm.md @@ -31,7 +31,7 @@ on-chain, as we explained earlier. In theory, you can do anything you want just using ISI as it is a Turing-complete language. However, it'll be less convenient and efficient -since you'd need to use [metadata](/guide/blockchain/metadata.md) as memory +since you'd need to use [metadata](/blockchain/metadata.md) as memory and write complex conditionals using just the tools that we've provided in the `Expression` and ISI infrastructure. We highly recommend choosing a well-known programming language, such as Rust, to build the necessary logic diff --git a/src/guide/blockchain/world.md b/src/blockchain/world.md similarity index 58% rename from src/guide/blockchain/world.md rename to src/blockchain/world.md index 2aaf5126a..d7d3395c0 100644 --- a/src/guide/blockchain/world.md +++ b/src/blockchain/world.md @@ -3,21 +3,21 @@ `World` is the global entity that contains other entities. The `World` consists of: -- Iroha [configuration parameters](./../configure/client-configuration.md) +- Iroha [configuration parameters](/guide/configure/client-configuration.md) - the list of [trusted peers](/guide/configure/peer-configuration#trusted-peers) - registered domains -- registered [triggers](/guide/blockchain/triggers.md) +- registered [triggers](/blockchain/triggers.md) - registered - [roles](/guide/blockchain/permissions.md#permission-groups-roles) + [roles](/blockchain/permissions.md#permission-groups-roles) - registered - [permission token definitions](/guide/blockchain/permissions.md#permission-tokens) + [permission token definitions](/blockchain/permissions.md#permission-tokens) - permission tokens for all accounts -- [the chain of runtime validators](/guide/blockchain/permissions.md#runtime-validators) +- [the chain of runtime validators](/blockchain/permissions.md#runtime-validators) When domains, peers, or roles are registered or unregistered, the `World` is the target of the (un)register -[instruction](/guide/blockchain/instructions.md). +[instruction](/blockchain/instructions.md). ## World State View (WSV) diff --git a/src/guide/get-started/index.md b/src/get-started/index.md similarity index 62% rename from src/guide/get-started/index.md rename to src/get-started/index.md index 7c2950e95..97d7a0237 100644 --- a/src/guide/get-started/index.md +++ b/src/get-started/index.md @@ -4,25 +4,25 @@ Iroha 2 is a fully-featured [blockchain ledger](/reference/glossary.md#blockchai - 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 efficient portable smart contracts implemented with [WebAssembly](/blockchain/wasm.md) and [Iroha Special Instructions](/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 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-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.). +1. [Install Iroha 2](/get-started/install-iroha-2.md): install prerequisites and clone the GitHub repository. +2. [Launch Iroha 2](/get-started/launch-iroha-2.md): install prerequisites and establish an instance of Iroha network. +3. [Operate Iroha 2 via CLI](/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) -- [Rust](/guide/get-started/rust.md) -- [Kotlin/Java](/guide/get-started/kotlin-java.md) -- [JavaScript (TypeScript)](/guide/get-started/javascript.md) +- [Python](/guide/tutorials/python.md) +- [Rust](/guide/tutorials/rust.md) +- [Kotlin/Java](/guide/tutorials/kotlin-java.md) +- [JavaScript (TypeScript)](/guide/tutorials/javascript.md) ::: tip -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. +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](/get-started/iroha-2.md) comparison that will help you understand the improvements and new features of Iroha 2. ::: @@ -30,7 +30,7 @@ The current version of Iroha covered in this documentation is Iroha 2. If you ha 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 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). +- Iroha Explained: learn [how Iroha works](../blockchain/iroha-explained.md) and find information on key Iroha concepts, including entities, operations, and features, such as [Iroha Special Instructions](/blockchain/instructions.md), [triggers](/blockchain/triggers.md), [queries](/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). diff --git a/src/guide/get-started/install-iroha-2.md b/src/get-started/install-iroha-2.md similarity index 100% rename from src/guide/get-started/install-iroha-2.md rename to src/get-started/install-iroha-2.md diff --git a/src/guide/iroha-2.md b/src/get-started/iroha-2.md similarity index 98% rename from src/guide/iroha-2.md rename to src/get-started/iroha-2.md index c016e4289..8a009177a 100644 --- a/src/guide/iroha-2.md +++ b/src/get-started/iroha-2.md @@ -52,8 +52,8 @@ Iroha 2 is an event-driven ledger. Each change in the state of the blockchain is For smart contracts, Iroha 2 supports two approaches: -- [Iroha Special Instructions (ISI)](./blockchain/instructions.md) -- [Web ASseMbly (WASM)](./blockchain/wasm.md) +- [Iroha Special Instructions (ISI)](/blockchain/instructions) +- [Web ASseMbly (WASM)](/blockchain/wasm) 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. diff --git a/src/guide/get-started/launch-iroha-2.md b/src/get-started/launch-iroha-2.md similarity index 96% rename from src/guide/get-started/launch-iroha-2.md rename to src/get-started/launch-iroha-2.md index 8bba56604..039350d44 100644 --- a/src/guide/get-started/launch-iroha-2.md +++ b/src/get-started/launch-iroha-2.md @@ -26,7 +26,7 @@ To launch an instance of the Iroha 2 network, install the following first: Once the process completes, you will see an output similar to the following: - <<< @/guide/get-started/launch-iroha.docker-compose-output.ansi + <<< @/get-started/launch-iroha.docker-compose-output.ansi After deploying the network, you can interact with it using the [Iroha Client CLI](./operate-iroha-2-via-cli.md). diff --git a/src/guide/get-started/launch-iroha.docker-compose-output.ansi b/src/get-started/launch-iroha.docker-compose-output.ansi similarity index 100% rename from src/guide/get-started/launch-iroha.docker-compose-output.ansi rename to src/get-started/launch-iroha.docker-compose-output.ansi diff --git a/src/guide/get-started/operate-iroha-2-via-cli.md b/src/get-started/operate-iroha-2-via-cli.md similarity index 95% rename from src/guide/get-started/operate-iroha-2-via-cli.md rename to src/get-started/operate-iroha-2-via-cli.md index e3906d4c3..d940cf9ff 100644 --- a/src/guide/get-started/operate-iroha-2-via-cli.md +++ b/src/get-started/operate-iroha-2-via-cli.md @@ -111,7 +111,7 @@ The output should contain several preregistered domains. ::: 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](/guide/blockchain/how-iroha-works) 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 [Iroha Explained](/blockchain/iroha-explained) section of the documentation. ::: @@ -253,14 +253,14 @@ private_key = "802620CBD3D701B561FE98463767729176404DC757D690F78980B8FDD40C171CC ::: ::: 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. +[Permissions](/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 define and manage assets in it. ## 6. Register and Mint Assets -To mint an asset, its [asset definition](/guide/blockchain/assets) must be registered first. +To mint an asset, its [asset definition](/blockchain/assets) must be registered first. To register a `tea` token within the `looking_glass` domain, run: @@ -404,6 +404,6 @@ To find out how to listen to other types of events, run the `iroha events help` ## What's Next 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. +- Learn how to build on Iroha 2 with our [SDK turorials](/guide/tutorials/). +- Understand the fundamental concepts behind Iroha 2 in the [Iroha Explained](/blockchain/iroha-explained) 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/advanced/running-iroha-on-bare-metal.md b/src/guide/advanced/running-iroha-on-bare-metal.md index 590a967f5..a97acb24a 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 2](../get-started/launch-iroha-2.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) 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/configure/client-configuration.md b/src/guide/configure/client-configuration.md index 53190302b..2d6df8638 100644 --- a/src/guide/configure/client-configuration.md +++ b/src/guide/configure/client-configuration.md @@ -27,7 +27,7 @@ For details on cryptographic keys, see [Public Key Cryptography](../security/pub The `ACCOUNT_ID` should be self-explanatory. The only thing you need to worry about is that the account must already exist in the blockchain. In other words, the account you provide here should already be -[registered](/guide/blockchain/instructions.md#un-register). +[registered](/blockchain/instructions.md#un-register). ::: info Note diff --git a/src/guide/configure/keys-for-network-deployment.md b/src/guide/configure/keys-for-network-deployment.md index 2bb7be074..4f76d2d76 100644 --- a/src/guide/configure/keys-for-network-deployment.md +++ b/src/guide/configure/keys-for-network-deployment.md @@ -23,7 +23,7 @@ $ cargo run --bin kagami --release -- crypto --json The output cryptographic keys generated by `kagami` are customizable by using preferences. Note that in the example above the `--json` parameter is specified to generate a key pair in the JSON format. -To learn more about generating cryptographic keys with `kagami`, available algorithms, and other parameters, see [Generating Cryptographic Keys with Kagami](../security/generating-cryptographic-keys.md#kagami). +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). ::: diff --git a/src/guide/configure/modes.md b/src/guide/configure/modes.md index 1ed18e4d1..899839e7b 100644 --- a/src/guide/configure/modes.md +++ b/src/guide/configure/modes.md @@ -20,7 +20,7 @@ said permission. ::: info Refer to the -[dedicated section on permissions](/guide/blockchain/permissions.md) for +[dedicated section on permissions](/blockchain/permissions.md) for more details. ::: @@ -46,7 +46,7 @@ permission first. By default, Iroha allows **all** instructions to go through, until a permission validator that can restrict instruction execution has been registered. You can add permission validators to your genesis block by -registering built-in [permission tokens](/guide/blockchain/permissions.md) +registering built-in [permission tokens](/blockchain/permissions.md) that we thought would be useful for `private` and `public` blockchain use-cases. However, in that case, the process of registering accounts is different. @@ -83,7 +83,7 @@ mode. ::: Refer to the section on -[instructions](/guide/blockchain/instructions.md#un-register) for more +[instructions](/blockchain/instructions.md#un-register) for more details about `Register` instructions. [^1]: diff --git a/src/guide/configure/peer-management.md b/src/guide/configure/peer-management.md index 872230db0..5caa96a0b 100644 --- a/src/guide/configure/peer-management.md +++ b/src/guide/configure/peer-management.md @@ -50,7 +50,7 @@ Permissions for registering a peer are under construction. ::: We discuss permissions and roles with more detail in a -[separate chapter](/guide/blockchain/permissions.md). +[separate chapter](/blockchain/permissions.md). #### 2. Set up a peer diff --git a/src/guide/security/generating-cryptographic-keys.md b/src/guide/security/generating-cryptographic-keys.md index 8b18c4dee..2856e65f5 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-2.md), run the following command from the project's `root` directory to generate a new key pair: +After [installing Iroha](/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 diff --git a/src/guide/get-started/tutorials.md b/src/guide/tutorials/index.md similarity index 81% rename from src/guide/get-started/tutorials.md rename to src/guide/tutorials/index.md index 7b4941ff1..25fafe41f 100644 --- a/src/guide/get-started/tutorials.md +++ b/src/guide/tutorials/index.md @@ -25,15 +25,15 @@ In this guide, we shall 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-2.md). + [the differences](/get-started/iroha-2.md) between the two versions of Iroha. +1. [Install Iroha 2](/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: - - [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) + - [Python](/guide/tutorials/python.md) + - [Rust](/guide/tutorials/rust.md) + - [Kotlin/Java](/guide/tutorials/kotlin-java.md) + - [Javascript (TypeScript)](/guide/tutorials/javascript.md) ## Tutorial Updates diff --git a/src/guide/get-started/javascript.md b/src/guide/tutorials/javascript.md similarity index 99% rename from src/guide/get-started/javascript.md rename to src/guide/tutorials/javascript.md index bcb7fdfec..54a88eda3 100644 --- a/src/guide/get-started/javascript.md +++ b/src/guide/tutorials/javascript.md @@ -335,7 +335,7 @@ way as in the previous section when we registered a domain. ## 5. Registering and minting assets Iroha has been built with few -[underlying assumptions](/guide/blockchain/assets.md) about what the assets need +[underlying assumptions](/blockchain/assets.md) about what the assets need to be in terms of their value type and characteristics (fungible or non-fungible, mintable or non-mintable). diff --git a/src/guide/get-started/kotlin-java.md b/src/guide/tutorials/kotlin-java.md similarity index 99% rename from src/guide/get-started/kotlin-java.md rename to src/guide/tutorials/kotlin-java.md index b35d07b6c..6001ad51a 100644 --- a/src/guide/get-started/kotlin-java.md +++ b/src/guide/tutorials/kotlin-java.md @@ -271,7 +271,7 @@ an account. ## 5. Registering and minting assets Iroha has been built with few -[underlying assumptions](/guide/blockchain/assets.md) about what the assets need +[underlying assumptions](/blockchain/assets.md) about what the assets need to be in terms of their value type and characteristics (fungible or non-fungible, mintable or non-mintable). diff --git a/src/guide/get-started/python.md b/src/guide/tutorials/python.md similarity index 99% rename from src/guide/get-started/python.md rename to src/guide/tutorials/python.md index 4b6eb2a79..cc3b9b127 100644 --- a/src/guide/get-started/python.md +++ b/src/guide/tutorials/python.md @@ -151,7 +151,7 @@ hash = cl.submit_isi(register) ## 5. Registering and minting assets Iroha has been built with few -[underlying assumptions](/guide/blockchain/assets.md) about what the assets need +[underlying assumptions](/blockchain/assets.md) about what the assets need to be in terms of their value type and characteristics (fungible or non-fungible, mintable or non-mintable). diff --git a/src/guide/get-started/rust.md b/src/guide/tutorials/rust.md similarity index 97% rename from src/guide/get-started/rust.md rename to src/guide/tutorials/rust.md index 0818a5e7c..1bb927b93 100644 --- a/src/guide/get-started/rust.md +++ b/src/guide/tutorials/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-2) as a local installation in your client's +[previous step](/get-started/install-iroha-2) as a local installation in your client's `Cargo.toml`: ```toml @@ -136,7 +136,7 @@ Note that the keys in [client configuration](/guide/configure/client-configuration.md) are given in [multi-hash format](https://github.com/multiformats/multihash). If you are experiencing issues parsing the keys in this format, -[check the troubleshooting section](/guide/troubleshooting/configuration-issues#multihash-format-of-private-and-public-keys). +[check the troubleshooting section](/help/configuration-issues#multihash-format-of-private-and-public-keys). ::: @@ -251,7 +251,7 @@ Which is then **wrapped in a transaction** and **submitted to the peer** as ## 5. Registering and minting assets Iroha has been built with few -[underlying assumptions](/guide/blockchain/assets.md) about what the assets need +[underlying assumptions](/blockchain/assets.md) about what the assets need to be in terms of their value type and characteristics (fungible or non-fungible, mintable or non-mintable). diff --git a/src/guide/troubleshooting/configuration-issues.md b/src/help/configuration-issues.md similarity index 100% rename from src/guide/troubleshooting/configuration-issues.md rename to src/help/configuration-issues.md diff --git a/src/guide/troubleshooting/deployment-issues.md b/src/help/deployment-issues.md similarity index 100% rename from src/guide/troubleshooting/deployment-issues.md rename to src/help/deployment-issues.md diff --git a/src/guide/support.md b/src/help/index.md similarity index 100% rename from src/guide/support.md rename to src/help/index.md diff --git a/src/guide/troubleshooting/installation-issues.md b/src/help/installation-issues.md similarity index 95% rename from src/guide/troubleshooting/installation-issues.md rename to src/help/installation-issues.md index 6a4c430e9..865de1d93 100644 --- a/src/guide/troubleshooting/installation-issues.md +++ b/src/help/installation-issues.md @@ -137,7 +137,7 @@ $ rustup toolchain install stable ## Troubleshooting Python toolchain -When you install the Python Wheel package using pip on the "[client setup](/guide/get-started/python#_1-iroha-2-client-setup)" step, you may encounter an error like: +When you install the Python Wheel package using pip on the "[client setup](/guide/tutorials/python#_1-iroha-2-client-setup)" step, you may encounter an error like: "iroha_python-*.whl is not a supported wheel on this platform". This error means that pip is outdated, so you need to update it. @@ -149,7 +149,7 @@ If this doesn't work, you can try updating `pip` for your user directory. Make sure that `pip` that is installed in your home directory. To do this, run `whereis pip` and check if `/home/username/.local/bin/pip` is among the paths. If not, update your shell's `PATH` variable. -If the issue persists, please [contact us](../support) and report the outputs. +If the issue persists, please [contact us](/help/) and report the outputs. ``` python --version diff --git a/src/guide/troubleshooting/integration-issues.md b/src/help/integration-issues.md similarity index 100% rename from src/guide/troubleshooting/integration-issues.md rename to src/help/integration-issues.md diff --git a/src/guide/troubleshooting/overview.md b/src/help/overview.md similarity index 92% rename from src/guide/troubleshooting/overview.md rename to src/help/overview.md index 31b24b554..b0084bf5a 100644 --- a/src/guide/troubleshooting/overview.md +++ b/src/help/overview.md @@ -26,4 +26,4 @@ because it would expose the peers' public key. As such, if you have Helm charts or K8s deployed with keys defined via the environment variables, you should check for Key definitions. -If in doubt, [generate a new pair of keys](../security/generating-cryptographic-keys.md). +If in doubt, [generate a new pair of keys](/guide/security/generating-cryptographic-keys.md). diff --git a/src/index.md b/src/index.md index 107f0fbbf..4ed845a9e 100644 --- a/src/index.md +++ b/src/index.md @@ -8,17 +8,21 @@ hero: #actions: #- theme: alt # text: View on GitHub - # link: https://github.com/hyperledger/iroha/ + # link: https://github.com/hyperledger/iroha/tree/iroha2-dev features: - icon: 🚀 title: Get Started details: Install and build Iroha, follow a step-by-step tutorial to start working with Iroha - link: /guide/get-started/ + link: /get-started/ + - icon: 🏗️ + title: Build on Iroha + details: Discover how to develop a product on Iroha using popular programming languages + link: /guide/tutorials/ - icon: 📖 - title: Iroha Overview + title: Iroha Explained details: Learn about Iroha functionality in great detail and understand the underlying principles - link: /guide/blockchain/how-iroha-works + link: /blockchain/iroha-explained - icon: 💻 title: Reference details: Consult reference documentation for extensive information about available functionality diff --git a/src/reference/ffi.md b/src/reference/ffi.md index edb1d3fa4..988b9c66f 100644 --- a/src/reference/ffi.md +++ b/src/reference/ffi.md @@ -12,7 +12,7 @@ what a function should do, the way in which said functions are represented is very different. Moreover, in some languages (like Rust), the consequences of calling a function, and the things that it is allowed to do are different. Because one can use any language to create a -[WASM smartcontract](/guide/blockchain/wasm.md), we need to level the +[WASM smartcontract](/blockchain/wasm.md), we need to level the playing field. This is where the concept of foreign function interface (FFI) comes in. diff --git a/src/reference/glossary.md b/src/reference/glossary.md index 3f985841e..4a37045af 100644 --- a/src/reference/glossary.md +++ b/src/reference/glossary.md @@ -57,7 +57,7 @@ In the context of blockchains, an asset is the representation of a valuable object on the blockchain. Additional information on assets is available -[here](/guide/blockchain/assets.md). +[here](/blockchain/assets.md). ### Fungible assets @@ -136,7 +136,7 @@ of conditions is met. In Iroha smart contracts are implemented using An event type that allows invoking an Iroha special instruction at specific block commit, time (with some caveats), etc. More on triggers -[here](/guide/blockchain/triggers.md). +[here](/blockchain/triggers.md). ### Versioning @@ -159,7 +159,7 @@ Third party extensions to Iroha that provide custom functionality. A library of smart contracts provided with Iroha. These can be invoked via either transactions or registered event listeners. More on ISI -[here](/guide/blockchain/instructions.md). +[here](/blockchain/instructions.md). #### Utility Iroha Special Instructions @@ -194,7 +194,7 @@ thus [peers](#peer) running a modified instance will have their access revoked. ## Iroha Query A request to read the World State View without modifying said view. More on -queries [here](/guide/blockchain/queries.md). +queries [here](/blockchain/queries.md). ## View change diff --git a/src/reference/instructions.md b/src/reference/instructions.md index de0595383..143b41886 100644 --- a/src/reference/instructions.md +++ b/src/reference/instructions.md @@ -7,14 +7,14 @@ The following instructions are supported in Iroha 2: | Instruction | Descriptions | | --------------------------------------------------------------------------------------- | ------------------------------------------------- | -| [Register/Unregister](/guide/blockchain/instructions#un-register) | Give an ID to a new entity on the blockchain. | -| [Mint/Burn](/guide/blockchain/instructions#mint-burn) | Mint/burn assets, triggers, or permission tokens. | -| [SetKeyValue/RemoveKeyValue](/guide/blockchain/instructions#setkeyvalue-removekeyvalue) | Update blockchain object metadata. | -| [NewParameter/SetParameter](/guide/blockchain/instructions#newparameter-setparameter) | Create/set a chain-wide config parameter. | -| [Grant/Revoke](/guide/blockchain/instructions#grant-revoke) | Give or remove certain permissions from accounts. | -| [Transfer](/guide/blockchain/instructions#transfer) | Transfer assets between accounts. | -| [ExecuteTrigger](/guide/blockchain/instructions#executetrigger) | Execute triggers. | -| [If, Pair, Sequence](/guide/blockchain/instructions#composite-instructions) | Use to create composite instructions. | +| [Register/Unregister](/blockchain/instructions#un-register) | Give an ID to a new entity on the blockchain. | +| [Mint/Burn](/blockchain/instructions#mint-burn) | Mint/burn assets, triggers, or permission tokens. | +| [SetKeyValue/RemoveKeyValue](/blockchain/instructions#setkeyvalue-removekeyvalue) | Update blockchain object metadata. | +| [NewParameter/SetParameter](/blockchain/instructions#newparameter-setparameter) | Create/set a chain-wide config parameter. | +| [Grant/Revoke](/blockchain/instructions#grant-revoke) | Give or remove certain permissions from accounts. | +| [Transfer](/blockchain/instructions#transfer) | Transfer assets between accounts. | +| [ExecuteTrigger](/blockchain/instructions#executetrigger) | Execute triggers. | +| [If, Pair, Sequence](/blockchain/instructions#composite-instructions) | Use to create composite instructions. | ::: details Diagram: Iroha Special Instructions diff --git a/src/reference/permissions.md b/src/reference/permissions.md index d58aff61b..3dab74011 100644 --- a/src/reference/permissions.md +++ b/src/reference/permissions.md @@ -1,6 +1,6 @@ # Permissions -This section provides details about pre-configured permission tokens in Iroha 2. For more general information on permission tokens and permission groups (roles), refer to the [Permissions](/guide/blockchain/permissions) chapter in Guide. +This section provides details about pre-configured permission tokens in Iroha 2. For more general information on permission tokens and permission groups (roles), refer to the [Permissions](/blockchain/permissions) chapter in Guide. ## Permission Tokens diff --git a/src/reference/queries.md b/src/reference/queries.md index 1a09bbe68..c7086986e 100644 --- a/src/reference/queries.md +++ b/src/reference/queries.md @@ -5,8 +5,8 @@ the queries and present to you what they do. You can learn ::: info -The results of queries can be [sorted](/guide/blockchain/queries#sorting), [paginated](/guide/blockchain/queries#pagination) -and [filtered](/guide/blockchain/queries#filters) peer-side all at once. +The results of queries can be [sorted](/blockchain/queries#sorting), [paginated](/blockchain/queries#pagination) +and [filtered](/blockchain/queries#filters) peer-side all at once. ::: @@ -38,7 +38,7 @@ An optional feature. By default, it is present on all Iroha 2 deployments when they're compiled in the private blockchain configuration. You can learn more about roles in a -[dedicated section](/guide/blockchain/permissions.md#permission-groups-roles). +[dedicated section](/blockchain/permissions.md#permission-groups-roles). ### `FindAllRoles` @@ -94,7 +94,7 @@ blockchains but the use cases are different: said permission. We talk about permissions in more detail in a -[dedicated chapter](/guide/blockchain/permissions.md). +[dedicated chapter](/blockchain/permissions.md). ### `FindAllPermissionTokenDefinitions` @@ -142,7 +142,7 @@ diverse set of queries. - **Details**: Returns the value keyed by the provided `Name` for the given account. - This is done by querying the [`metadata`](/guide/blockchain/metadata.md) + This is done by querying the [`metadata`](/blockchain/metadata.md) attached to the given account. ### `FindAccountsByName` @@ -296,7 +296,7 @@ that is used as a secure data storage for privileged information. - **Returns**: `Value` - **Details**: Gets the value keyed by the given name in the - [metadata](/guide/blockchain/metadata.md) of the asset corresponding to + [metadata](/blockchain/metadata.md) of the asset corresponding to the given identifier. ### `FindAssetDefinitionKeyValueByIdAndKey` @@ -306,7 +306,7 @@ that is used as a secure data storage for privileged information. - **Returns**: `Value` - **Details**: Gets the value keyed by the given name in the - [metadata](/guide/blockchain/metadata.md) of the asset definition + [metadata](/blockchain/metadata.md) of the asset definition corresponding to the given identifier. ### `FindTotalAssetQuantityByAssetDefinitionId` @@ -484,7 +484,7 @@ Note that Iroha shut downs all listeners on panic. - **Returns**: `Trigger` - **Details**: Finds the value corresponding to the key in the - [metadata](/guide/blockchain/metadata.md) of the trigger with the given + [metadata](/blockchain/metadata.md) of the trigger with the given ID. ### `FindTriggersByDomainId` diff --git a/src/reference/torii-endpoints.md b/src/reference/torii-endpoints.md index 0791065b3..71d7f09df 100644 --- a/src/reference/torii-endpoints.md +++ b/src/reference/torii-endpoints.md @@ -139,7 +139,7 @@ This endpoint expects a subset of configuration parameters serialized into JSON The list of all accepted values is currently unavailable and will be a part of the configuration reference that is still WIP. -Until then, to get assistance with the acceptable values and their definitions, consult [Receive Support](../guide/support.md) for ways to contact us. +Until then, to get assistance with the acceptable values and their definitions, consult [Receive Support](/help/) for ways to contact us. The progress on the configuration reference can be tracked in the following GitHub issue:\ [iroha-2-docs > Issue #392: Tracking issue for Configuration Reference as per RFC](https://github.com/hyperledger/iroha-2-docs/issues/392).