Why does Iroha run in a network? How can one gain a better understanding of the objects, both inside and outside the system? How do peers in the network collaborate and decide on which data to put into the blockchain? We will look at the Core Concepts and terminology used by Iroha in this section.
Account : An Iroha entity that is able to perform a specified set of actions or permissions. Each account belongs to one of multiple existing domains. An account is associated with zero or more roles.
There are two categories of permissions in Iroha, Permissions and Grantable Permissions. Only Grantable Permissions can be assigned to an account directly. Grantable Permissions allow an account to perform some action on behalf of another account.
Ametsuchi
An Iroha storage component. An Ametsuchi stores both blocks and the state generated from blocks. This state is known as the World State View. There is no way for the client to directly interact with ("an" or "the"?) Ametsuchi.
Question: Is there one or more than one Ametsuchi?
Asset
Any countable commodity or value. Each asset is related to one or more existing domains. An asset represents a real-world entity of value. fTor example; currency or monetary unit, a commodity, such as gold or oil, real estate or property, ect.
Block
A block is a container data structure, made up of one or more transactions. Transaction data is immutable and is permanently recorded in a block. Blocks are organized into a linear sequence over time. Multiple blocks make up the blockchain.
Blocks are signed with the cryptographic signatures of Iroha peers. The voting of blocks, which are to be added to the blockchain, occurs during consensus. Signed content is refered to as the payload. The structure of a block is outlined below:
Outside the payload
- hash — SHA3-512 hash of block protobuf payload
- signature — signature of all peers which voted for the block during consensus
Inside the payload
- height — the number of blocks in the chain up to the block
- timestamp — Unix time (in milliseconds) of block formation by peers
- body — transactions which successfully passed validation and consensus
- transaction quantity - number of transations contained in the block
- hash of the previous block - the hash value contained in the outside payload from the previous block
Question: Can you confirm that a block in Iroha contains only valid transactions? This question came up in the Training and Education Working Group
Block Creator
The system component that creates a block from a set of transactions. These transactions have passed stateless and stateful validation for further propagation to consensus.
Client
Any application that uses Iroha is treated as a client. A distinctive feature of Iroha is that all clients use simple client-server abstractions when they interact with a peer network. No abstractions, which are specific for blockchain-related systems, are needed. As an example, in Bitcoin, clients have to validate blocks. Likewise, in Hyperledger Fabric, clients need to poll several peers to ensure that a transaction was written to a block. However, in Iroha, a client interacts with any peer in a way which is similar to a single server.
Command
A command is an intention to change the state. For example, in order to create a new role in Iroha you must issue the Create Role command.
Consensus
Consensus is a means to achieve agreement on a single data value among multiple distributed processes or systems.
Consensus, as an algorithm
A consensus algorithm in computer science is a set of steps used to achieve agreement on a single data value among distributed processes or systems. Consensus algorithms are designed to achieve reliability in a network involving multiple unreliable nodes. The issue of achieving agreement amoung multiple unreliable nodes is known as the "consensus problem", and is important in distributed computing and multi-agent systems. By having a consensus alogorithm as a fundamental part of a system, reliability is increased.
Consensus, as a component
Consensus as a component preserves a consistent state among the peers within a peer network. Iroha uses its own consensus algorithm, Yet Another Consensus or YAC. Distinctive features of this algorithm are scalability, performance, and Byzantine Fault Tolerance. If there are missing blocks, they will be downloaded from another peer by the Synchronizer. Committed blocks are stored in Ametsuchi block storage.
Domain
A named abstraction for the grouping of accounts and the grouping of assets.
Question: Are grouping by accounts only and assests only or are do domains include both accounts and assets
Ordering Gate
An internal Iroha component that passes transactions from the Peer Communication Service to the Ordering Service. The Ordering Gate eventually recieves proposals from the Ordering Service and sends them to the Simulator for stateful validation.
Ordering Gate
An internal Iroha component, which combines several transactions, that have passed stateless validation into a proposal. Proposal creation could be triggered by one of the following events:
- Time limit dedicated to transactions collection has expired.
- The Ordering Service has received the maximum amount of transactions allowed for a single proposal.
Both parameters: timeout and maximum size of proposal, are configurable. Refer to the environment-specific parameters page for additional information.
A common precondition for both triggers is that at least one transaction should reach the Ordering Service. Otherwise, no proposal will be formed.
Peer
A node that is a part of Iroha network. A peer participates in the consensus process.
Peer Communication Service
An internal component of Iroha, the Peer Communication Service acts as an intermediary which transmits transactions from Torii to the Ordering Gate. The main goal of The Peer Communication Service (PCS) is to hide the complexity, or abstract, the interaction with the consensus implementation.
Permission
A named rule that gives the privilege to perform a command. Typicaly, permissions cannot be granted to an account directly (see Grantable Permission below), instead, an account is associated with certain roles. These roles are a collection of permissions.
Link to List of Iroha permissions.
Grantable Permission
Only Grantable permissions are given to an account directly. An account that holds a grantable permission is allowed to perform some particular action on behalf of another account. For example, if the account a@domain1 gives the account b@domain2 a permission which give the account the ability to transfer assets — then b@domain2 can transfer the assets associated with a@domain1 to any other account.
Proposal
A set of transactions that have only passed stateless validation. Stateless validation is the first step in verifing a proposal to be committed to the blockchain.
Verified Proposal
A set of transactions that have passed both stateless and stateful validation, however, have not been committed yet. Stateful validation is the second t step in verifing a proposal to be committed to the blockchain.
Query
A request to Iroha that does not change the state. By performing a query, a client can retrieve data from the state, for example, a balance associated with an account, a history of transactions, etc.
Quorum
Within the context of transaction signing, a quorum is a number representing the minimum amount of signatures required to consider a transaction signed. The default quorum value is 1. Each account can link additional public keys and increase its own quorum value or number.
Role
A named abstraction that holds a set of permissions or rules which give an account the privilege to perform a set of commands.
Signatory
Represents an entity that can confirm multisignature transactions for specified accounts. A Signatory can be attached to an account via AddSignatory and removed via RemoveSignatory.
Simulator
Currently defined as - See Verified Proposal Creator.
Note: Typically, you would not want to define a terms with another term within the same set of terms.
Synchronizer
The Synchronizer a part of the consensus mechanism. The Synchronizer adds missing blocks to peer's chains by downloading the blocks from other peers.
Torii
⛩ A Torii is an entry point for clients. The Torii in Iroha uses gRPC (Remote Procedure Calls), an open source remote procedure call as transport. In order to interact with Iroha anyone can use gRPC endpoints. gRPC is described in the Commands and Queries sections, or use client libraries.
Question: The last phrase, "or use client libraries" wasn't clear. Does this mean that instead of using gPRC, other clients libraries can be used? If so the recommendeded change would be - gRPC is described in the Commands and Queries sections, alternatively client libraries can be used.
Transation
A transation is an ordered set of commands. This set of commands or transation, is applied to the ledger atomically. Any invalid command within a transaction leads to the rejection of the whole transaction during the validation process.
Transaction Structure
Within the structure of a transaction, the Payload stores all transaction fields except for signatures. The payload includes the following transaction fields:
- Time of creation (Unix time, in milliseconds)
- Account ID of transaction creator. For exampple, username@domain.com
- Quorum field which indicates the required number of signatures
- Repeated commands. These commands are described in more detail in Commands section.
- Batch meta information (optional). Batch meta information is described in more detail in Batch of Transactions.
Within the structure of a transaction, Signatures contain one or many signatures (ed25519 public key + signature)
Reduced Transaction Hash
The Reduced Transaction Hash is calculated over the transaction payload and excludes batch meta information. The Reduced Transaction Hash is used in the Batch of Transactions.
Transaction Statuses
Hyperledger Iroha supports both push and pull interaction modes with a client. With pull technology, the initial request for data originates from the client. With push technology, a request for a given transaction is initiated by the publisher. A client which uses pull interaction requests status updates regaurding transactions from Iroha peers by sending transaction hashes and waiting for a response. In contrast, push interaction is achieved by listening on an event stream for each transaction. In both of these modes of interaction, the set of transaction statuses is the same.
IMAGE HERE
Transaction Status Set
- NOT_RECEIVED: The requested peer does not have this transaction.
- MST_EXPIRED: This transactions is a part of MST pipeline and has expired.
- STATELESS_VALIDATION_FAILED: This transaction was formed with some fields which did not meet the stateless validation constraints. This status is returned to a client who formed a transaction immediately after the transaction was sent. The rule in violation is also included in the response.
- STATELESS_VALIDATION_SUCCESS: The transaction has successfully passed stateless validation. This status is returned to a client who formed transaction immediately after the transaction was sent.
- STATEFUL_VALIDATION_FAILED: The transaction includes commands which violate the validation rules while checking the state of the chain, for example, asset balance, account permissions, etc. The rule in violation is also included in the response.
- STATEFUL_VALIDATION_SUCCESS: The transaction has successfully passed stateful validation.
- COMMITTED: The transaction is the part of a block and had gained enough votes. The transaction is committed to the block store at this moment.
Pending Transactions
For any transaction that has less than the majority number of signatures at the moment that quorum is established, the Transaction Creator will consider the account as pending. Pending transactions will be submitted for stateful validation as soon as the Multisignature Mechanism collects the required amount of signatures for quorum.
Transactions that already have reached a quorum of signatures may also be considered as pending in cases where the transaction is part of a batch of transactions and there is a not a fully signed transaction.
Batch of Transactions
This feature is not yet released
Transaction batch is a feature which allows the sending of several transactions to Iroha while at the same time preserving their order.
Each transaction in a batch includes batch meta information. Batch meta information contains a batch type identifier, either atomic or ordered, and a list of reduced hashes of all the transactions within a batch. The order of the associated hashes prescribes the transaction's sequence.
Batches can contain transactions created by different accounts. Any transaction within a batch can require eith single or multiple signatures, depending on the quorum set for an account by the Transaction Creator. At least one transaction inside a batch should have at least one signature to allow the batch to pass stateful validation.
Atomic Batch
All transactions in an atomic batch should pass stateful validation for the batch to be applied to a ledger.
Ordered Batch
Ordered batches preserves only the sequence of transactions applyingto a ledger. All transactions that are able to pass stateful validation within a batch will be applied to a ledger. Validation failure of one transaction would NOT directly imply the failure of the entire batch.
Multisignature Transactions
A transaction, which has a quorum greater than 1, is considered a multisignature transaction or MST.. To achieve stateful validity, the confirmation is required by the signatories of the creator account. These participants need to send the same transaction along with their signature.
Validator
There are two kinds of validation - stateless and stateful.
Stateless Validation
Stateless Validation is performed in Torii. This checks if an object is well-formed and includes signatures.
Stateful Validation
Stateful Validation is performed in the Verified Proposal Creator. Stateful Validation is validatidated against the World State View.
Verified Proposal Creator
An internal Iroha component that performs stateful validation of transactions contained in received proposals. Based on transactions, which have passed stateful validation, verified proposal will be created and passed to the Block Creator. All transactions, which have not passed stateful validation, will be dropped and will not be included in a verified proposal.
World State View
The World State View or WSV, reflects the current state of the system and may be considered as a snapshot. For example, the World State View holds information regarding the number of assets that an account has at at a given moment but does not contain any infornmation regarding the history of the transaction flow.
test