2.1.1. Account¶
An Iroha entity that is able to perform specified set of actions. Each account belongs to one of existing domains.
An account has some number of roles (can be null) — which is a collection of permissions. Only grantable permissions are assigned to an account directly.
2.1.2. Asset¶
Any countable commodity or value. Each asset is related to one of existing domains. For example, an asset can represent any kind of such units - currency unit, a bar of gold, real estate unit, etc.
2.1.3. Block¶
Transaction data is permanently recorded in files called blocks. Blocks are organized into a linear sequence over time (also known as the block chain) [1].
Blocks are signed with the cryptographic signatures of Iroha peers, voting for this block during consensus. Signable content is called payload, so the structure of a block looks like this:
Outside payload
- signatures — signatures of peers, which voted for the block during consensus round
Inside payload
- height — a number of blocks in the chain up to the block
- timestamp — Unix time (in milliseconds) of block forming by a peer
- array of transactions, which successfully passed validation and consensus step
- hash of a previous block in the chain
- rejected transactions hashes — array of transaction hashes, which did not pass stateful validation step; this field is optional
2.1.4. Client¶
Any application that uses Iroha is treated as a client.
A distinctive feature of Iroha is that all clients are using simple client-server abstractions when they interact with a peer network: they don’t use any abstractions which are specific for blockchain-related systems. For example, in Bitcoin clients have to validate blocks, or in HL Fabric they need to poll several peers to make sure that a transaction was written in a block, whereas in HL Iroha a client interacts with any peer similarly to a single server.
2.1.5. Command¶
A command is an intention to change the state of the network. For example, in order to create a new role in Iroha you have to issue Create role command.
2.1.6. Consensus¶
A consensus algorithm is a process in computer science 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. Solving that issue – known as the consensus problem – is important in distributed computing and multi-agent systems.
Consensus, as an algorithm
An algorithm to achieve agreement on a block among peers in the network. By having it in the system, reliability is increased.
For consensus as Iroha’s component, please check this link.
2.1.7. Domain¶
A named abstraction for grouping accounts and assets. For example, it can represent an organisation in the group of organisations working with Iroha.
2.1.9. Permission¶
A named rule that gives the privilege to perform a command. Permission cannot be granted to an account directly, instead, account has roles, which are collections of permissions. Although, there is an exception, see Grantable Permission.
2.1.9.1. Grantable Permission¶
Only grantable permission is given to an account directly. An account that holds grantable permission is allowed to perform some particular action on behalf of another account. For example, if account a@domain1 gives the account b@domain2 a permission that it can transfer assets — then b@domain2 can transfer assets of a@domain1 to anyone.
2.1.10. Proposal¶
A set of transactions that have passed only stateless validation.
2.1.11. Query¶
A request to Iroha that does not change the state of the network. By performing a query, a client can request data from the state, for example a balance of his account, a history of transactions, etc.
2.1.12. Quorum¶
In the context of transactions signing, quorum number is a minimum amount of signatures required to consider a transaction signed. The default value is 1. For MST transactions you will need to increase that number.
Each account can link additional public keys and increase own quorum number.
2.1.13. Role¶
A named abstraction that holds a set of permissions.
2.1.14. Signatory¶
Represents an entity that can confirm multisignature transactions for an account. It can be attached to account via AddSignatory and detached via RemoveSignatory.
2.1.15. Transaction¶
An ordered set of commands, which is applied to the ledger atomically. Any non-valid command within a transaction leads to rejection of the whole transaction during the validation process.
2.1.15.1. Transaction Structure¶
Payload stores all transaction fields, except signatures:
- Time of creation (unix time, in milliseconds)
- Account ID of transaction creator (username@domain)
- Quorum field (indicates required number of signatures)
- Repeated commands which are described in details in commands section
- Batch meta information (optional part). See Batch of Transactions for details
Signatures contain one or many signatures (ed25519 public key + signature)
2.1.15.1.1. Reduced Transaction Hash¶
Reduced hash is calculated over transaction payload excluding batch meta information. Used in Batch of Transactions.
2.1.15.2. Transaction Statuses¶
Hyperledger Iroha supports both push and pull interaction mode with a client. A client that uses pull mode requests status updates about transactions from Iroha peer by sending transaction hashes and awaiting a response. On the contrary, push interaction is performed by listening of an event stream for each transaction. In any of these modes, the set of transaction statuses is the same:
Note
We’ve written a great Medium article about Status streaming feature in Iroha. Check it out and let us know what you think in the comments!
2.1.15.2.1. Transaction Status Set¶
- NOT_RECEIVED: requested peer does not have this transaction.
- ENOUGH_SIGNATURES_COLLECTED: this is a multisignature transaction which has enough signatures and is going to be validated by the peer.
- MST_PENDING: this transaction is a multisignature transaction which has to be signed by more keys (as requested in quorum field).
- MST_EXPIRED: this transaction is a multisignature transaction which is no longer valid and is going to be deleted by this peer.
- STATELESS_VALIDATION_FAILED: the transaction was formed with some fields, not meeting stateless validation constraints. This status is returned to a client, who formed transaction, right after the transaction was sent. It would also return the reason — what rule was violated.
- STATELESS_VALIDATION_SUCCESS: the transaction has successfully passed stateless validation. This status is returned to a client, who formed transaction, right after the transaction was sent.
- STATEFUL_VALIDATION_FAILED: the transaction has commands, which violate validation rules, checking state of the chain (e.g. asset balance, account permissions, etc.). It would also return the reason — what rule was violated.
- STATEFUL_VALIDATION_SUCCESS: the transaction has successfully passed stateful validation.
- COMMITTED: the transaction is the part of a block, which gained enough votes and is in the block store at the moment.
- REJECTED: this exact transaction was rejected by the peer during stateful validation step in previous consensus rounds. Rejected transactions’ hashes are stored in block store. This is required in order to prevent replay attacks.
2.1.15.2.2. Pending Transactions¶
Any transaction that has lesser signatures at the moment than quorum of transaction creator account is considered as pending. Pending transaction will be submitted for stateful validation as soon as multisignature mechanism will collect required amount of signatures for quorum.
Transaction that already has quorum of signatures can also be considered as pending in cases when the transaction is a part of batch of transactions and there is a not fully signed transaction.
2.1.16. Batch of Transactions¶
Transactions batch is a feature that allows sending several transactions to Iroha at once preserving their order.
Each transaction within a batch includes batch meta information. Batch meta contains batch type identifier (atomic or ordered) and a list of reduced hashes of all transactions within a batch. The order of hashes defines transactions sequence.
Batch can contain transactions created by different accounts. Any transaction within a batch can require single or multiple signatures (depends on quorum set for an account of transaction creator). At least one transaction inside a batch should have at least one signature to let the batch pass stateless validation.
You can read an article about batches on our Contributors’ Page on Medium.
2.1.16.1. Atomic Batch¶
All the transactions within an atomic batch should pass stateful validation for the batch to be applied to a ledger.
2.1.16.2. Ordered Batch¶
Ordered batch preserves only the sequence of transactions applying to a ledger. All the transactions that 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 whole batch.
2.1.17. Multisignature Transactions¶
A transaction which has the quorum greater than one is considered as multisignature (also called mst). To achieve stateful validity the confirmation is required by the signatories of the creator account. These participants need to send the same transaction with their signature.
2.1.18. Validation¶
There are two kinds of validation - stateless and stateful.
2.1.18.1. Stateless Validation¶
Performed in Torii. Checks if an object is well-formed, including the signatures.
2.1.18.2. Stateful Validation¶
Performed in Verified Proposal Creator. Validates against World State View.
| [1] | https://en.bitcoin.it/wiki/Block |