client_cli

Iroha CLI Client

With the Iroha CLI Client, you can interact with Iroha Peers Web API. It is a "thin" wrapper around functionality exposed in the iroha crate. Specifically, it should be used as a reference for using iroha's features, and not as a production-ready client. As such, the CLI client is not guaranteed to support all features supported by the client library.

Features

• Submit Transactions with your Iroha Special Instructions to Iroha Peers
• Send Requests with your Queries to Iroha Peers

Installation

Requirements: a working Rust toolchain (version 1.62.1), installed and configured.

Build Iroha and its binaries:

cargo build

The above command will produce the iroha ELF executable file for Linux/BSD, the iroha executable for MacOS, and the iroha.exe executable for Windows, depending on your platform and configuration.

Check build and installation instructions for more details.

Usage

Run Iroha Client CLI:

iroha [OPTIONS] <SUBCOMMAND>

Options

Option	Description
-c, --config	Set a config file path (config.json by default).

Subcommands

Command	Description
account	Execute commands related to accounts: register a new one, list all accounts, grant a permission to an account, list all account permissions
asset	Execute commands related to assets: register a new one, mint or transfer assets, get info about an asset, list all assets
blocks	Get block stream from Iroha peer
domain	Execute commands related to domains: register a new one, list all domains
events	Get event stream from Iroha peer
json	Submit multi-instructions or request query as JSON
peer	Execute commands related to peer administration and networking
wasm	Execute commands related to WASM
help	Print the help message for iroha and/or the current subcommand other than help subcommand

Refer to Iroha Special Instructions for more information about Iroha instructions such as register, mint, grant, and so on.

Check the Bash guide in Iroha Tutorial for detailed instructions on working with Iroha Client CLI.

Examples

❕ All examples below are Unix-oriented. If you're working on Windows, we would highly encourage you to consider using WSL, as most documentation assumes a POSIX-like shell running on your system. Please be advised that the differences in the syntax may go beyond executing iroha.exe instead of iroha.

./iroha domain register --id="Soramitsu"
./iroha account register --id="ed01204A3C5A6B77BBE439969F95F0AA4E01AE31EC45A0D68C131B2C622751FCC5E3B6@Soramitsu"
./iroha asset register --id="XOR#Soramitsu" --value-type=Numeric
./iroha asset mint --account="ed01204A3C5A6B77BBE439969F95F0AA4E01AE31EC45A0D68C131B2C622751FCC5E3B6@Soramitsu" --asset="XOR#Soramitsu" --quantity=1010
./iroha asset get --account="ed01204A3C5A6B77BBE439969F95F0AA4E01AE31EC45A0D68C131B2C622751FCC5E3B6@Soramitsu" --asset="XOR#Soramitsu"

In this section we will show you how to use Iroha CLI Client to do the following:

• Iroha CLI Client
  • Features
  • Installation
  • Usage
    • Options
    • Subcommands
  • Examples
    • Create new Domain
    • Create new Account
    • Mint Asset to Account
    • Query Account Assets Quantity
    • Execute WASM transaction
    • Execute Multi-instruction Transactions

Create new Domain

Let's start with domain creation. To create a domain, you need to specify the entity type first (domain in our case) and then the command (register) with a list of required parameters.

For the domain entity, you only need to provide the id argument as a string that doesn't contain the @ and # symbols.

./iroha domain register --id="Soramitsu"

Now you have a domain without any accounts.

Create new Account

Let's create a new account. Like in the previous example, specify the entity type (account) and the command (register). Then define the value of the id argument in "signatory@domain" format, where signatory is the account's public key in multihash representation.

./iroha account register --id="ed01204A3C5A6B77BBE439969F95F0AA4E01AE31EC45A0D68C131B2C622751FCC5E3B6@Soramitsu"

Mint Asset to Account

It's time to give something to the Account you created. Let's add some Assets of the type Quantity to the account.

To do so, you must first register an Asset Definition and only then add some Assets to the account. Specify the asset entity and then use the register and mint commands respectively.

Every asset has its own value spec. In this example, it is defined as Numeric, a 96-bit unsigned decimal. We also support Store for key-value structured data.

./iroha asset register --id="XOR#Soramitsu" --value-type=Numeric
./iroha asset mint --account="ed01204A3C5A6B77BBE439969F95F0AA4E01AE31EC45A0D68C131B2C622751FCC5E3B6@Soramitsu" --asset="XOR#Soramitsu" --quantity=1010

You created XOR#Soramitsu, an asset of type Numeric, and then gave 1010 units of this asset to the account ed01204A3C5A6B77BBE439969F95F0AA4E01AE31EC45A0D68C131B2C622751FCC5E3B6@Soramitsu.

Query Account Assets Quantity

Because distributed systems heavily rely on the concept of eventual consistency and Iroha works by awaiting consensus between peers, your request is not guaranteed to be processed (or be accepted) even if it is correctly formed. While the Iroha Client will successfully send your transactions and the Iroha Peer will confirm receiving them, it is possible that your request will not appear in the next block.

Different causes such as a transaction timeout, a faulty peer in the network, catastrophic failure of the peer that you've sent your data towards, and many other conditions naturally occurring inside of any blockchain may lead to a rejection of your transaction at many different stages of processing.

It should be noted that Iroha is designed to reduce the incidence of such rejections, and only rejects properly formed transactions in situations when not rejecting it would lead to data corruption and a hard-fork of the network.

As such it's important to check that your instructions were applied and the world is now in the desired state. For this you need to use Query API.

Let's use Get Account Assets Query as an example. To know how many units of a particular asset an account has, use asset get with the specified account and asset:

./iroha asset get --account="ed01204A3C5A6B77BBE439969F95F0AA4E01AE31EC45A0D68C131B2C622751FCC5E3B6@Soramitsu" --asset="XOR#Soramitsu"

This query returns the quantity of XOR#Soramitsu asset for the ed01204A3C5A6B77BBE439969F95F0AA4E01AE31EC45A0D68C131B2C622751FCC5E3B6@Soramitsu account.

It's possible to filter based on either account, asset or domain id by using the filtering API provided by the Iroha client CLI.

Generally it looks like this:

./iroha ENTITY list filter PREDICATE

Where ENTITY is asset, account or domain and PREDICATE is condition used for filtering serialized using JSON5 (check iroha::data_model::predicate::value::ValuePredicate type).

Examples:

# Filter domains by id
./iroha domain list filter '{"Identifiable": {"Is": "wonderland"}}'
# Filter accounts by domain
./iroha account list filter '{"Identifiable": {"EndsWith": "@wonderland"}}'
# It is possible to combine filters using "Or" or "And"
# Filter asset by domain
./iroha asset list filter '{"Or": [{"Identifiable": {"Contains": "#wonderland#"}}, {"And": [{"Identifiable": {"Contains": "##"}}, {"Identifiable": {"EndsWith": "@wonderland"}}]}]}'

Execute WASM transaction

Use --file to specify a path to the WASM file:

./iroha wasm --file=/path/to/file.wasm

Or skip --file to read WASM from standard input:

cat /path/to/file.wasm | ./iroha wasm

These subcommands submit the provided wasm binary as an Executable to be executed outside a trigger context.

Execute Multi-instruction Transactions

The reference implementation of the Rust client, iroha, is often used for diagnosing problems in other implementations.

To test transactions in the JSON format (used in the genesis block and by other SDKs), pipe the transaction into the client and add the json subcommand to the arguments:

cat /path/to/file.json | ./iroha json transaction

Request arbitrary query

echo '{ "FindAllParameters": null }' | ./iroha --config client.toml json query