2. Getting Started¶
In this guide, we will create a very basic Iroha network, launch it, create a couple of transactions, and check the data written in the ledger. To keep things simple, we will use Docker.
Ledger is the synonym for a blockchain, and Hyperledger Iroha is known also as Distributed Ledger Technology — which in essence is the same as “blockchain framework”. You can check the rest of terminology used in the Glossary section.
For this guide, you need a computer running Unix-like system with
installed. You can read how to install it on a
Please note that you can use Iroha without
docker as well. You
can read about it in other parts of documentation.
2.2. Starting Iroha Node¶
2.2.1. Creating a Docker Network¶
To operate, Iroha requires a
PostgreSQL database. Let’s start with creating
a Docker network, so containers for Postgres and Iroha can run on the same
virtual network and successfully communicate. In this guide we will call it
iroha-network, but you can use any name. In your terminal write following
docker network create iroha-network
2.2.2. Starting PostgreSQL Container¶
Now we need to run
PostgreSQL in a container, attach it to the network you
have created before, and expose ports for communication:
docker run --name some-postgres \ -e POSTGRES_USER=postgres \ -e POSTGRES_PASSWORD=mysecretpassword \ -p 5432:5432 \ --network=iroha-network \ -d postgres:9.5
If you already have Postgres running on a host system on default port
(5432), then you should pick another free port that will be occupied. For
-p 5433:5432 \
2.2.3. Creating Blockstore¶
Before we run Iroha container, we should create persistent volume to store files, storing blocks for the chain. It is done via the following command:
docker volume create blockstore
2.2.4. Configuring Iroha Network¶
To keep things simple, in this guide we will create a network containing only one node. To understand how to run several peers, follow this guide.
Now we need to configure our Iroha network. This includes creating a configuration file, generating keypairs for a users, writing a list of peers and creating a genesis block. However, we have prepared an example configuration for this guide, so you can start playing with Iroha faster. In order to get those files, you need to clone the Iroha repository from Github.
git clone -b master https://github.com/hyperledger/iroha --depth=1
--depth=1 option allows us to download only latest commit and
save some time and bandwidth. If you want to get a full commit history, you
can omit this option.
2.2.5. Starting Iroha Container¶
We are ready to launch our Iroha container. Let’s do it with the following command
docker run -it --name iroha \ -p 50051:50051 \ -v $(pwd)/iroha/example:/opt/iroha_data \ -v blockstore:/tmp/block_store \ --network=iroha-network \ --entrypoint=/bin/bash \ hyperledger/iroha:latest
Let’s look in detail what this command does:
docker run -it --name iroha \attaches you to docker container called
$(pwd)/iroha/example:/opt/iroha_data \we add a folder containing our prepared configuration to a docker container into
-v blockstore:/tmp/block_store \adds a persistent block storage which we created before to a container, so our blocks won’t be lost after we stop the container
--network=iroha-network \adds our container to previously created
iroha-network, so Iroha and Postgres could see each other.
hyperledger/irohahas the custom script which runs after starting the container, we want to override it so we can start Iroha Daemon manually.
hyperledger/iroha:latestis the image which has the
2.2.6. Launching Iroha Daemon¶
Now you are in the interactive shell of Iroha’s container. To actually run
Iroha, we need to launch Iroha daemon –
irohad --config config.docker --genesis_block genesis.block --keypair_name node0
In the usual situation, you need to provide a config file, generate genesis block and keypair. However, as a part of this guide, we provide an example configuration for you. Please do not use these settings in a production. You can read more about configuration here.
Congratulations! You have an Iroha node up and running! In the next section, we will test it by sending some transactions.
You can get more information about
irohad and its launch options
in this section
2.3. Interacting with Iroha Network¶
You can interact with Iroha using various ways. You can use our client libraries
Swift) which communicates with Iroha. Alternatively, you can use
our command-line tool for interacting with Iroha. As a part of this guide,
let’s get familiar with
iroha-cli is arguably the simplest way to start
working with Iroha,
iroha-cli was engineered very fast and lacks tests,
so user experience might not be the best. For example, the order of menu items
can differ from that you see in this guide. In the future, we will deliver a
better version and appreciate contributions.
Open a new terminal (note that Iroha container and
irohad should be up and
running) and attach to an
iroha docker container:
docker exec -it iroha /bin/bash
Now you are in the interactive shell of Iroha’s container again. We need to
iroha-cli and pass an account name of the desired user. In our example,
admin is already created in a
test domain. Let’s use this
account to work with Iroha.
iroha-cli -account_name admin@test
Full account name has a
@ symbol between name and domain. Note
that the keypair has the same name.
2.3.1. Creating the First Transaction¶
You can see the interface of
iroha-cli now. Let’s create a new asset, add
some asset to the admin account and transfer it to other account. To achieve
this, please choose option
1. New transaction (tx) by writing
1 to a console.
Now you can see a list of available commands. Let’s try creating a new asset.
14. Create Asset (crt_ast). Now enter a name for your asset, for
coolcoin. Next, enter a Domain ID. In our example we already have a
test, so let’s use it. Then we need to enter an asset precision
– the amount of numbers in a fractional part. Let’s set precision to
Congratulations, you have created your first command and added it to a
transaction! You can either send it to Iroha or add some more commands
1. Add one more command to the transaction (add). Let’s add more commands,
so we can do everything in one shot. Type
Now try adding some
coolcoins to our account. Select
16. Add Asset
Quantity (add_ast_qty), enter Account ID –
admin@test, asset ID –
coolcoin#test, integer part and precision. For example, to add 200.50
coolcoins, we need to enter integer part as
20050 and precision as
2, so it becomes
Full asset name has a
# symbol between name and domain.
Let’s transfer 100.50
by adding one more command and choosing
5. Transfer Assets (tran_ast).
Enter Source Account and Destination Account, in our case
test@test, Asset ID (
coolcoin#test), integer part and precision
Now we need to send our transaction to Iroha peer (
2. Send to Iroha peer
(send)). Enter peer address (in our case
localhost) and port (
Congratulations, your transaction is submitted and you can see your transaction
hash. You can use it to check transaction’s status.
Go back to a terminal where
irohad is running. You can see logs of your
Congratulations! You have submitted your first transaction to Iroha.
2.3.2. Creating the First Query¶
Now let’s check if
coolcoins were successfully transferred from
2. New query
7. Get Account's Assets (get_acc_ast) can help you to check if
test@test now has
coolcoin. Form a query in a similar way you did with
commands you did with commands and
1. Send to Iroha peer (send). Now you
can see information about how many
It will look similar to this:
[2018-03-21 12:33:23.179275525][th:36][info] QueryResponseHandler [Account Assets] [2018-03-21 12:33:23.179329199][th:36][info] QueryResponseHandler -Account Id:- test@test [2018-03-21 12:33:23.179338394][th:36][info] QueryResponseHandler -Asset Id- coolcoin#test [2018-03-21 12:33:23.179387969][th:36][info] QueryResponseHandler -Balance- 100.50``
Congratulations! You have submitted your first query to Iroha and got a response!
To get information about all available commands and queries please check our API section.
2.3.3. Being Badass¶
Let’s try being badass and cheat Iroha. For example, let’s transfer more
admin@test has. Try to transfer 100000.00
test@test. Again, proceed to
1. New transaction
5. Transfer Assets (tran_ast), enter Source Account and Destination
Account, in our case
test@test, Asset ID
coolcoin#test), integer part and precision (
accordingly). Send a transaction to Iroha peer as you did before. Well, it says
[2018-03-21 12:58:40.791297963][th:520][info] TransactionResponseHandler Transaction successfully sent Congratulation, your transaction was accepted for processing. Its hash is fc1c23f2de1b6fccbfe1166805e31697118b57d7bb5b1f583f2d96e78f60c241
Your transaction was accepted for processing. Does it mean that we
had successfully cheated Iroha? Let’s try to see transaction’s status. Choose
3. New transaction status request (st) and enter transaction’s hash which
you can get in the console after the previous command. Let’s send it to Iroha.
It replies with:
Transaction has not passed stateful validation.
Apparently no. Our transaction was not accepted because it did not pass
stateful validation and
coolcoins were not transferred. You can check
the status of
test@test with queries to be sure
(like we did earlier).