Docs structure overhaul updated

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.
 

src/blockchain/WarningFatQuery.vue

@@ -0,0 +1,8 @@
+<template>
+  <div class="warning custom-block">
+    <p class="custom-block-title">
+      WARNING
+    </p>
+    <p>This query returns a large volume of data.</p>
+  </div>
+</template>

src/blockchain/accounts.md

@@ -0,0 +1,6 @@
+# Accounts
+
+<!-- the file is not currently included in the TOC -->
+<!-- TODO: add info about account structure -->
+
+TBD

src/blockchain/assets.md

@@ -0,0 +1,83 @@
+# Assets
+
+Iroha has been built with few underlying assumptions about what the assets
+need to be.
+
+The assets can be **fungible** (every £1 is exactly the same as every other
+£1) or **non-fungible** (a £1 bill signed by the Queen of Hearts is not the
+same as a £1 bill signed by the King of Spades).
+
+The assets can also be **mintable** (you can make more of them) and
+**non-mintable** (you can only specify their initial quantity in the
+[genesis block](/guide/configure/genesis.md)).
+
+## Value Types
+
+Additionally, the assets have different underlying value types.
+Specifically, we have `AssetValueType.Quantity`, which is effectively an
+unsigned 32-bit integer, a `BigQuantity`, which is an unsigned 128-bit
+integer, and `Fixed`, which is a positive (though signed) 64-bit
+fixed-precision number with nine significant digits after the decimal
+point. All three types can be registered as either **mintable** or
+**non-mintable**.
+
+There is also the `Store` asset type, which is used for storing key-values
+in object's metadata. We talk in detail about `Store` asset in the chapter
+related to [metadata](metadata.md).
+
+## Asset Structure
+
+```mermaid
+classDiagram
+
+class Asset
+class AssetDefinition
+
+class Id {
+  definition_id
+  account_id
+}
+
+class Mintable {
+  <<enumeration>>
+  Infinitely
+  Once
+  Not
+}
+
+class AssetValue {
+  <<enumeration>>
+  Quantity
+  BigQuantity
+  Fixed
+  Store
+}
+
+Asset -- AssetDefinition
+Asset -- Id
+AssetDefinition -- Mintable
+AssetDefinition -- AssetValue 
+AssetDefinition -- Id
+
+Asset : id {Id}
+Asset : value
+
+AssetDefinition : id {Id}
+AssetDefinition : value_type {AssetValueType}
+AssetDefinition : mintable {Mintable}
+AssetDefinition : metadata
+```
+
+## Instructions
+
+Assets can be [registered](./instructions.md#un-register),
+[minted or burned](./instructions.md#mint-burn), and transferred.
+
+Refer to one of the language-specific guides to walk you through the
+process of registering and minting assets in a blockchain:
+
+- [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)

src/blockchain/consensus.md

@@ -0,0 +1,36 @@
+# Consensus
+
+Each time you send a transaction to Iroha, it gets put into a queue. When
+it's time to produce a new block, the queue is emptied, and the consensus
+process begins. This process is equal parts common sense and black
+magic[^1].
+
+The mundane aspect is that a special set of peers needs to take the
+transaction queue and reproduce the same world state. If the world state
+cannot be reproduced for some reason or another, none of the transactions
+get committed to a block.
+
+The consensus starts over from scratch by choosing a different special set
+of peers. This is where the black magic comes in. There is a number of
+things that are fine-tuned: the number of peers in the voting process, the
+way in which subsequent voting peers are chosen, and the way in which the
+peers communicate that consensus has failed. Because this changes the view
+of the world, the process is called a _view change_. The exact reason for
+why the view was changed is encoded in the _view change proof_, but
+decoding that information is an advanced topic that we won't cover here.
+
+The reasoning behind this algorithm is simple: if someone had some evil
+peers and connected them to the existing network, if they tried to fake
+data, some good™ peers would not get the same (evil™) world state. If
+that's the case, the evil™ peers would not be allowed to participate in
+consensus, and you would eventually produce a block using only good™ peers.
+
+As a natural consequence, if any changes to the world state are made
+without the use of ISI, the good™ peers cannot know of them. They won't be
+able to reproduce the hash of the world state, and thus consensus will
+fail. The same thing happens if the peers have different instructions.
+
+[^1]:
+    For prospective wizards, the
+    [Iroha 2 Whitepaper](https://github.com/hyperledger/iroha/blob/main/docs/source/iroha_2_whitepaper.md)
+    is a good start.

src/blockchain/data-model.md

@@ -0,0 +1,139 @@
+# Data Model
+
+In language-specific guides we already walked you through registering
+domains, accounts, and assets. Here we merely wish to illustrate the
+relationship between various objects in the blockchain.
+
+```
+
+   +-----------------------------------------------+
+   |                                               |
+   |     +-----------------+                       |
+   |     |Domain           |                       |
+   |     +--------------+  |                       |
+   |     ||Asset        |  |                       |
++--+--+  ||Definition(s)|  |                       |
+|World|  +--------------+  |                       |
++--+--+  |                 |                       |
+   |     +------------+    |                       |
+   |     ||Account(s)||    | has   +-----------+   |
+   |     |------------------------->Signatories|   |
+   |     +-----------------+       +-----------+   |
+   |                       |                       |
+   |                       |  has  +--------+      |
+   |                       +------->Asset(s)|      |
+   |                               +--------+      |
+   +-----------------------------------------------+
+
+```
+
+[//]: # 'TODO: rewrite above schema with mermaid'
+
+The following example shows the relationship between domains, accounts, and
+assets.
+
+<div class="domains-example-scope">
+
+```mermaid
+classDiagram
+
+class domain_wonderland {
+  id = "wonderland"
+}
+class account_alice:::aliceblue {
+  id = "alice@wonderland"
+}
+class account_mad_hatter:::aliceblue {
+  id = "mad_hatter@wonderland"
+}
+
+class asset_rose:::pink {
+  id = "rose#wonderland"
+}
+
+domain_wonderland *-- account_alice : registered in
+domain_wonderland *-- asset_rose : registered in
+account_alice *-- asset_rose : registered by
+domain_wonderland *-- account_mad_hatter : registered in
+
+class domain_looking_glass {
+  id = "looking_glass"
+}
+
+class account_rabbit:::aliceblue {
+  id = "white_rabbit@looking_glass"
+}
+
+domain_looking_glass *-- account_rabbit : registered in
+```
+
+</div>
+
+<style scoped lang="scss">
+.domains-example-scope {
+  :deep(.aliceblue) rect {
+      stroke: rgba(59, 130, 246, 0.8) !important;
+      stroke-width: 4 !important;
+  }
+
+  :deep(.pink) rect {
+    stroke: rgba(246, 50, 100, 0.8) !important;
+    stroke-width: 4 !important;
+  }
+}
+</style>
+
+::: details Language-specific guides to register these objects
+
+| Language              | Guide                                                                                                                                                                                                              |
+| --------------------- |--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| 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)                |
+
+:::
+
+The diagram below provides a more detailed illustration of the relationship
+between domains, accounts, and assets in the blockchain. You can learn more
+about [permissions and roles](./permissions.md) and [metadata](metadata.md)
+in the corresponding sections. The asset structure is illustrated in a
+[dedicated chapter](./assets.md).
+
+```mermaid
+classDiagram
+
+class Domain
+class Account
+class AssetDefinition
+class Asset
+
+Domain *-- "many" Account : contains
+Domain *-- "many" AssetDefinition : contains
+Account *-- "many" Asset : contains
+Asset -- AssetDefinition
+
+Domain : id
+Domain : accounts
+Domain : asset_definitions
+Domain : logo
+Domain : metadata
+
+Account : id
+Account : assets
+Account : signatories
+Account : signature_check_condition
+Account : metadata
+Account : roles
+
+
+AssetDefinition : id
+AssetDefinition : value_type
+AssetDefinition : mintable
+AssetDefinition : metadata
+
+Asset : id
+Asset : value
+```
+

src/blockchain/domains.md

@@ -0,0 +1,6 @@
+# Domains
+
+<!-- the file is not currently included in the TOC -->
+<!-- TODO: add -->
+
+TBD

src/blockchain/events.md

@@ -0,0 +1,38 @@
+# Events
+
+Events are emitted when certain things happen within the blockchain, e.g. a
+new account is created or a block is committed. There are different types
+of events:
+
+- pipeline events
+- data events
+- time events
+- trigger execution events
+
+## Pipeline Events
+
+Pipeline events are emitted when transactions are submitted, executed, or
+committed to a block. A pipeline event contains the following information:
+the kind of entity that caused an event (transaction or block), its hash
+and status. The status can be either `Validating` (validation in progress),
+`Rejected`, or `Committed`. If an entity was rejected, the reason for the
+rejection is provided.
+
+## Data Events
+
+Data events are emitted when there is a change related to one of the
+following entities: peers, domains, accounts, asset definitions, assets,
+triggers, roles, permission tokens, permission validators, or Iroha
+configuration. These types of events are used in
+[entity filters](./filters.md).
+
+## Time Events
+
+Time events are emitted when the world state view is ready to handle
+[time triggers](./triggers.md#time-triggers).
+
+## Trigger Execution Events
+
+Trigger execution events are emitted when the
+[`ExecuteTrigger`](./instructions.md#executetrigger) instruction is
+executed

src/blockchain/expressions.md

@@ -0,0 +1,17 @@
+# Expressions, Conditionals, Logic
+
+All [Iroha Special Instructions](./instructions.md) operate on expressions.
+Each expression has an `EvaluatesTo`, which is used in instruction
+execution. While you could specify the account name directly, you could
+also specify the account ID via some mathematical or string operation. You
+can check if an account is registered on the blockchain too.
+
+Using expressions that implement `EvaluatesTo<bool>`, you can set up
+conditional logic and execute more sophisticated operations on-chain. For
+example, you can submit a `Mint` instruction only if a specific account is
+registered.
+
+Recall that you can combine this with queries, and as such can program the
+blockchain to do some amazing stuff. This is what we refer to as _smart
+contracts_, the defining feature of the advanced usage of blockchain
+technology.