Hyperledger Iroha (Blockchain Framework) Tutorial with Multi Signature & Decentralized Exchange in Multi Peers Set-up (Part 1)

8 min readMay 15, 2021

Key Features of Iroha Blockchain System

In Hyperledger Iroha’s official documentation, they mentioned some key features.

Assets and identity management
Decentralized finance and decentralized exchange
Role-based access control, Multi signature transactions
Available SDK in Python, Java, Javascript, iOS
Built-in commands for asset management
No costly mining and low transactions latency
Clients need interaction with any one of the peers and that peer will proceed other operations
Private and permissioned network

Possible Use Cases

Banking, cross border asset management, decentralized finance and decentralized exchange, financial applications, identity management, supply chain, fund management, certificate management, payment systems, central bank digital currencies, inter bank settlement and many more, token management.

Details with examples are also available at documentation.

Hyperledger Iroha Network

Hyperledger Iroha network consists of distributed peers/nodes server where each peer/node has the same identical blockchain which is stored in the database of that peer/node for storing the information and every peer/node maintains the same identical protocol to keep the blockchain running into a secured, distributed and decentralized way.

To achieve reliability into the network involving multiple unreliable nodes, a consensus algorithm is used to achieve agreement on a single data value among distributed processes or systems. To preserve a consistent state among the peers within a distributed, decentralized, private and permissioned network, Iroha uses its own consensus algorithm called Yet Another Consensus (aka YAC). You can check out a video with a thorough explanation of the principles of consensus and YAC implemented in Iroha.

Unlike other Hyperledger frameworks, in Hyperledger Iroha clients need interaction with any one of the peers and that peer will proceed other operations with other peers. An Iroha peer has a Torii gateway for client to peer communication with the help of gRPC system and has a separate internal port for peer to peer communication.

Demo Code Repository Setup

We run this demo with Docker and Docker Compose on an Ubuntu machine. To run the python SDK, you also need python3, pip3 and iroha python library. Those are the prerequisite of this demo. Please install the iroha python library with following command:

pip3 install iroha==0.0.5.5

We assume that you have git install on your machine. Please clone the project by using the following command:

git clone https://github.com/Ta-SeenJunaid/Hyperledger-Iroha-Tutorial-with-Multi-Signature-and-Decentralized-Exchanged-in-Multi-Node-Set-up.git

Please go to project’s root directory:

cd Hyperledger-Iroha-Tutorial-with-Multi-Signature-and-Decentralized-Exchanged-in-Multi-Node-Set-up/

For this tutorial, we will use version v1.0.0 and so we have to checkout that version with the following command:

git checkout tags/v1.0.0 -b v1.0.0-branch

Short Review on Public Key Cryptography and Digital Signature

In the public key cryptographic (asymmetric key cryptographic) system, an entity owns a pair of keys known as a private key and its corresponding public key. The private key is kept private/secret which may never be known by any except the owner where the owner shares the corresponding public key publicly with other participants for encryption-decryption or digital signature verification purpose.

An entity can cryptographically sign a document with the private key which is known as digital signature. A signature verification function takes this digital signature and the corresponding document as input and with the help of public key, it can cryptographically prove that the document is came from that entity who owns this public key’s corresponding private key and the document is not tampered during transmission time.

In this demo, we use Iroha’s special Ed25519 with SHA-3 algorithm as our public key cryptography where Hyperledger Ursa provides Iroha with support of standard Ed25519 with SHA-2 algorithm which is also implementable.

To generate private-public key-pair, use following command from your projects root folder:

python3 python_sdk/key-pair.py

This will print our private-public key-pair where we have to save the private key in private and publish the public key with other entities.

By using the private key we can also regenerate private-public key-pair. An example command is given below where we have to give a private key as argument to regenerate private-public key-pair..

python3 python_sdk/key-pair.py --private_key 038783f1bfb934bea80a892d789a53d7d7126c9c60c375ff2259f6fc809b7828

Data Structure with Prebuilt Commands, Queries & Permission in Hyperledger Iroha

A domain is a named abstraction for grouping accounts and assets where every user (or entity) has its own account: {account_name}@{domain} like ‘satoshi@test’, ‘nakamoto@test’ and every account can have several types of assets on board: {asset_name}#{domain} like the account ‘satoshi@test’ may have several asset like ‘bitcoin#test’, ‘dogecoin#test’ with some owned quantity where the account ‘nakamoto@test’ may have no ownership on ‘bitcoin#test’. Every account may have a list of roles with corresponding permission. Like a role named as ‘admin’ may have permission to create a new asset where a role named as ‘user’ may not have any permission to create a new asset. So the account ‘nakamoto@test’ with role only ‘user’ may not be able to create a new asset where the account ‘satoshi@test’ with both ‘user’ and ‘admin’ roles may be able to create a new asset. Actually all of those are maintaining an entity-relationship model which can be found in official documentation.

As Hyperledger Iroha is a special purpose framework for asset, identity & supply chain management, it allows users to perform common functions with some prebuilt commands and queries which negates the need to write cumbersome and hard to test smart contracts, enabling developers to complete simple tasks faster and reliably with less risk.

Block and Genesis Block with Genesis Transactions

Transaction data is permanently recorded into the data store of every peer, known as blocks. Blocks are organized into a linear sequence over time like a chain of blocks as each block is attaching the hash of it’s previous block. A block has several fields and those are:

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
Signatures, signatures of peers, which voted for the block during consensus round
Hash of a previous block in the chain
Rejected transactions’ hashes

A genesis block is the name given to the first block a chain, which has ‘height = 1’, ‘previous block hash = 0000000000000000000000000000000000000000000000000000000000000000’ and some initialization transactions known as genesis transactions. You can create the genesis block with any of available SDK of you can easily write the genesis block as this is human readable file. To initialize genesis transactions into our example “genesis.block” file, we first add each initial peer/node with address (network address and internal port) and attach every peer’s public key with it so that our network can automatically verify digital signature for synchronization, consensus, and communication purposes. Then we create different roles like ‘admin’, ‘user’ with their allowed permission (prebuilt commands and queries) list. We also initialize some domains, assets and accounts where we also append different roles on those accounts. We also attach a public key on each account creation time so that we can automatically verify that a transaction is signed by that entity and the transaction is not tampered. Each and every peer must need an identical genesis block to start up it’s operation on same network.

genesis.block

Setting-up & Deploying Multi Peers Network

To deploy the Iroha network, we need to configure deployment specific parameters like block store path, torii port, internal port, database etc and environment specific parameters like maximum proposal size, proposal delay, vote delay etc. The Detailed configuration process for different setup is described in official documentation with examples.

In our multi peers/nodes setup, we have different data volume for different peers like for peer/node 1 we have volume ‘node1’, for peer/node 2 we have volume ‘node2’, for peer/node 3 we have volume ‘node3’ where we store genesis.block file, public and private key of that peer/node for singing purpose, config.docker file for configuration set up for that node/peer.

Now it’s time to deploy our network where we run this demo with Docker and Docker Compose into an Ubuntu machine and so we have to prepare a docker-compose.yaml file. To create multi peers/nodes into localhost, we have to provide all the peers/nodes IP addresses into the genesis file and to give each node a specific IP address into our localhost, we have to create a docker network with a specific subnet. Details explanation for a network with single peer/node set up will also be available at Iroha’s quick start guide.

From projects root directory, run the following command to clear the previous setup:

bash network.sh down

From projects root directory, run the following command to start the network:

bash network.sh up

You can also change the start up timing according to your machine by modifying the ‘network.sh’ file.

Testing Client Libraries AKA SDK

Hyperledger Iroha has client libraries aka SDK available in Python, Java, Javascript, iOS etc where in this demo we use python SDK. When we create the genesis block, we initialize the ‘admin@test’ and the ‘test@test’ account. Here we will use that ‘admin@test’ account’s credential(public-private key pair) for transactions and for querying the result from different peers/nodes.

From projects root directory, run the following command for transaction example with python SDK:

python3 python_sdk/tx-example.py

Summary of Part 1:

In this tutorial we deploy a multi peers/nodes Iroha network and we also discuss some core concepts of Hyperledger Iroha and try to provide some valuable links of different concepts related to Hyperledger Iroha.

In the next part of this tutorial we will describe some of Hyperledger Iroha’s awesome features like ‘Multi Signature’, ‘Decentralized Exchange’ etc where the code for that tutorial is already available at github.

This blog is written only for learning purposes and we hope that this blog will be helpful for you and also expect your valuable reviews so that we all can have a chance to learn from you.

The link of part 2 is given below: