NAV Navbar
protobuf json
  • Overview
  • Build
  • Run irohad locally
  • Block structure
  • Transactions
  • Commands
  • Queries
  • Command Line Interface
  • Overview

    Welcome to the Hyperledger Iroha API docs!

    This API allows users to send transactions to peer network, containing one or many commands to perform allowed actions in the system, and also make queries to know current state. Users are authenticated by their keypair and account id, passed as the parameter with their transactions or queries.

    The API is organized around protobuf format, as Iroha is using gRPC on transport level. Iroha CLI and blockstore works with JSON format to provide developer-friendly experience for community members.

    To try out a basic API request, do the following:

    1. Run the system (irohad daemon) on a single node
    2. Run iroha-cli in interactive mode
    3. Select a necessary action to perform
    4. Send formed protobuf via gRPC call
    5. Get a response from the system

    Build

    Docker

    Git repository

    Clone iroha repository on your directory.

    Cloning Iroha

    git clone -b develop --depth=1 \
    https://github.com/hyperledger/iroha /path/to/iroha
    

    How to run development environment

    /path/to/iroha/scripts/run-iroha-dev.sh
    

    You will be attached to interactive environment for development and testing with iroha folder mounted from host machine.

    Docker environment will be removed when you logout from the container.

    Build iroha and run tests

    Build: cmake -H. -Bbuild; cmake --build build -- -j$(nproc)

    irohad and iroha-cli binaries will be in ./build/bin directory.

    Add to irohad and iroha-cli to path (optional)

    export PATH=/path/to/iroha/build/bin:$PATH

    How to run tests method #1

    cmake --build build --target test
    

    How to run tests method #2

    ctest . # in build folder
    

    Execute iroha-cli with irohad running

    Execute run-iroha-dev.sh again to attach to existing container.

    Linux or macOS

    For Iroha, a provisioning of Postgres and Redis are required. You may launch them on your local machine, or use docker containers, as provided.

    Launching Docker and Postgres in Docker

    docker run --name some-redis -p 6379:6379 -d redis:3.2.8
    docker run --name some-postgres -e POSTGRES_PASSWORD=mysecretpassword -p 5432:5432 -d postgres:9.5
    

    Linux

    apt-get -y --no-install-recommends install \
            build-essential python-software-properties \
            automake libtool \
            libssl-dev zlib1g-dev libboost-all-dev \
            libc6-dbg golang \
            git ssh tar gzip ca-certificates \
            python3 python3-pip python3-setuptools \
            lcov \
            wget curl cmake file unzip gdb \
            iputils-ping vim ccache \
            gcovr vera++ cppcheck doxygen \
            graphviz graphviz-dev; \
        apt-get -y clean
    git clone https://github.com/hyperledger/iroha -b develop
    cd iroha
    cmake -H. -Bbuild
    cmake --build build -- -j4
    

    macOS

    xcode-select --install
    # if you dont't have brew installed
    ruby -e "$(curl -fsSL https://raw.githubusercontent.com/homebrew/install/master/install)"
    brew install cmake boost postgres grpc autoconf automake libtool golang
    git clone https://github.com/hyperledger/iroha -b develop
    cd iroha
    cmake -H. -Bbuild
    cmake --build build -- -j4
    

    macOS brew

    brew tap soramitsu/iroha
    brew install iroha
    

    Run irohad locally

    Generate genesis block

    1. Create peers.list file containing the peers' addresses. For the local node suffice to add only single peer: bash $ echo 'localhost:10001' > peers.list

    2. Generate genesis block using iroha-cli: bash $ iroha-cli --genesis_block --peers_address peers.list

    File genesis.block with keypair files for Administrator account (admin@test.priv and admin@test.pub) and node (node0.priv and node0.pub) should be generated in the same folder.

    Prepare config file

    Configuration file keeps information about storage credentials and irohad parameters:

    Parameter Type Meaning
    block_store_path string Path to store blocks of committed transactions
    torii_port integer Port to access iroha node
    internal_port integer Port used to communicate ordering service, YAC consensus and block loader for synchronization
    pg_opt string Postgres credentials
    redis_host string Redis host's IP address
    redis_port integer Port to access redis storage
    max_proposal_size integer Maximum size of created proposals
    proposal_delay integer The period of time (in ms) used to prepare proposal of transactions
    vote_delay integer The period of time (in ms) of spreading vote across the network
    load_delay integer The period of time (in ms) between synchronizations between peers

    Example:

    {
      "block_store_path" : "/tmp/block_store/",
      "torii_port" : 50051,
      "internal_port" : 10001,
      "pg_opt" : "host=localhost port=5432 user=postgres password=mysecretpassword",
      "redis_host" : "localhost",
      "redis_port" : 6379,
      "max_proposal_size" : 10,
      "proposal_delay" : 5000,
      "vote_delay" : 5000,
      "load_delay" : 5000
    }
    

    Launch irohad

    To launch irohad daemon, following parameters must be passed:

    Parameter Meaning
    config configuration file, containing postgres, and redis connection, and values to tune the system
    genesis_block initial block in the ledger
    keypair_name private and public key file names without .priv or .pub extension. Used by peer to sign the blocks

    Use this command to launch iroha from development branch:

    irohad --config example/config.sample --genesis_block example/genesis.block --keypair_name example/node
    

    Block structure

    Block

    In order to understand contents of the block better, this section tells about its parts:

    Outside payload

    Inside payload

    Transactions

    Transaction

    message Transaction {
      Payload payload = 1;
      repeated Signature signature = 2;
     }
    
    {
        /* Transaction */
        "signatures": array of objects,
        "created_ts": int(13),
        "creator_account_id": string(?),
        "tx_counter": int,
        "commands": array of objects
    }
    

    To provide connectivity with Iroha, currently Google RPC is used. To form a transaction with one or many commands, or send a query JSON format is used in CLI.

    Client application should follow descibed protocol and form transactions accordingly to description below.

    Transaction structure

    Each transaction consists of two parts:

    Payload

    message Payload {
      repeated Command commands = 1;
      string creator_account_id = 2;
      uint64 tx_counter  = 3;
      uint64 created_time = 4;
    }
    
    {
        "commands": [
            {
                "command_type": string(?),
                /* other command-specific fields */
            }
        ],
        "creator_account_id": string(?),
        "tx_counter": int,
        "created_ts": int(13)
    }
    

    Signature

    one or more signatures of payload

    message Signature {
       bytes pubkey    = 1;
       bytes signature = 2;
    }
    
    {
        "signatures": [
            {
                "pubkey": string(64),
                "signature": string(128),
            }
        ], 
    }
    

    Payload stores everything except signatures:

    Signatures contain one or many signatures (ed25519 pubkey + signature):

    Commands

    Add asset quantity

    Purpose

    Purpose of add asset quantity is to increase amount of assets on some account.

    Structure

    message AddAssetQuantity {
        string account_id = 1;
        string asset_id = 2;
        Amount amount = 3;
    }
    
    message uint256 {
       uint64 first = 1;
       uint64 second = 2;
       uint64 third = 3;
       uint64 fourth = 4;
    }
    
    message Amount {
       uint256 value = 1;
       uint32 precision = 2;
    }
    
    
    {
        "commands": [
            {
                "command_type": "AddAssetQuantity",
                "account_id": "test@test",
                "asset_id": "coin#test",
                "amount": {
                    "value": string,
                    "precision": int
                }
            }
        ], 
    }
    
    Field Description Constraint
    Account ID account id in which to add asset username@domain
    Asset ID id of the asset asset#account
    Amount positive amount of the asset to add > 0

    Validation

    1. Asset and account should exist
    2. Added quantity precision should be equal to asset precision
    3. User should have this asset in AccountHasAsset relation ("wallet")
    4. Creator of transaction should has role which has permissions for issuing assets
    5. Creator of transaction adds account quantity to his/her account only

    Add peer

    Purpose

    Purpose of add peer is to write into ledger the fact of peer addition into the peer network.

    Structure

    message AddPeer {
        string address = 1;
        bytes peer_key = 2;
    }
    
    {
        "commands": [
            {
                "command_type": "AddPeer",
                "address": "192.168.1.1:50001",
                "peer_key": string(64)
            },
        ], 
    }
    
    Field Description Constraint
    Address resolvable address in network (IPv4, IPv6, domain name, etc.) should be resolvable
    Peer key peer public key, which will be used in consensus algorithm to sign-off vote, commit, reject messages ed25519 public key

    Validation

    1. Creator of transaction has role which has CanAddPeer permission.

    Add signatory

    Purpose

    Purpose of add signatory is to add identity to the account. It can be the public key of another device or public key of another user.

    Structure

    message AddSignatory {
        string account_id = 1;
        bytes public_key = 2;
    }
    
    {
        "commands": [
            {
                "command_type": "AddSignatory",
                "account_id": "test@test",
                "public_key": string(64)
            }
        ], 
    }
    
    Field Description Constraint
    Account ID Account in which to add signatory (username@domain) username@domain
    Public key Signatory to add to account ed25519 public key

    Validation

    Two cases: Case 1. When transaction creator wants to add signatory to their account and he or she has permission CanAddSignatory Case 2. Transaction creator was granted with CanAddSignatory permission to add signatory to this account

    Create asset

    Purpose

    Purpose of сreate asset is to create new type of asset, specific for a domain.

    Structure

    message CreateAsset {
        string asset_name = 1;
        string domain_id = 2;
        uint32 precision = 3;
    }
    
    {
        "commands": [
            {
                "command_type": "CreateAsset",
                "asset_name": "usd",
                "domain_id": "test",
                "precision": "2"
            }
        ], 
    }
    
    Field Description Constraint
    Asset name domain-unique name for asset [a-z]{1,9}
    Domain ID target domain to make relation with should be created before the asset, [a-z]{1,9}
    Precision number of digits after comma/dot 0 <= precision <= uint32 max

    Validation

    1. Transaction creator has permission to create assets
    2. Asset name is valid and unique per domain

    Create account

    Purpose

    Purpose of create account is to make new entity similar to wallet, which stores assets and identities.

    Structure

    message CreateAccount {
        string account_name = 1;
        string domain_id = 2;
        bytes main_pubkey = 3;
    }
    
    {
        "commands": [
            {
                "command_type": "CreateAccount",
                "account_name": "takemiya",
                "domain_id": "test",
                "main_pubkey": string(64)
            }
        ], 
    }
    
    Field Description Constraint
    Account name domain-unique name for account [a-z]{1,7}
    Domain ID target domain to make relation with should be created before the account, [a-z]{1,9}
    Main pubkey first piblic key to add into the account ed25519 public key

    Validation

    1. Transaction creator has permission to create account

    Create domain

    Purpose

    Purpose of create domain is to make new domain in Iroha network.

    Structure

    message CreateDomain {
        string domain_name = 1;
        string default_role = 2;
    }
    
    {
        "commands": [
            {
                "command_type": "CreateDomain",
                "domain_name": "test2",
                "default_role": "User"
            }
        ], 
    }
    
    Field Description Constraint
    Domain ID ID for created domain unique, [a-z]{1,9}
    Default role role for any created user in the domain one of existing roles

    Validation

    1. domain id is unique and valid against regex
    2. Account, who sends this command in transaction, has role with permission to create domain

    Remove signatory

    Purpose

    Purpose of remove signatory is to remove public key, associated with an identity, from an account

    Structure

    message RemoveSignatory {
        string account_id = 1;
        bytes public_key = 2;
    }
    
    {
        "commands": [
            {
                "command_type": "RemoveSignatory",
                "account_id": "takemiya@test",
                "public_key": string(64)
            }
        ], 
    }
    
    Field Description Constraint
    Account ID ID of account to delete signatory from already existent, [a-z]{1,9}\@[a-z]{1,9}
    Public key Signatory to delete ed25519 public key

    Validation

    When signatory is deleted, we should check if invariant of size(signatories) >= quorum holds. Signatory should be added previously to the account.

    Two cases: Case 1. When transaction creator wants to remove signatory from their account and he or she has permission CanRemoveSignatory Case 2. Transaction creator was granted with CanRemoveSignatory permission to remove signatory from this account

    Set account quorum

    Purpose

    Purpose of set account quorum is to set the number of signatories needed to confirm the identity of person, sending the transaction or is to set amount of people to agree on transaction contents.

    Structure

    message SetAccountQuorum {
        string account_id = 1;
        uint32 quorum = 2;
    }
    
    {
        "commands": [
            {
                "command_type": "SetAccountQuorum",
                "account_id": "takemiya@test",
                "quorum": 5
            }
        ], 
    }
    
    Field Description Constraint
    Account ID ID of account to set quorum already existent, [a-z]{1,9}
    Quorum number of signatories needed to be included with a transaction from this account 0 < quorum < 10

    Validation

    When quorum is set, we should check if invariant of size(signatories) >= quorum holds.

    Two cases: Case 1. When transaction creator wants to set quorum for his/her account and he or she has permission CanRemoveSignatory Case 2. Transaction creator was granted with CanRemoveSignatory permission to remove signatory from this account

    Transfer asset

    Purpose

    Purpose of transfer asset is to share assets across the network, so that source account can transfer assets to target account.

    Structure

    message TransferAsset {
        string src_account_id = 1;
        string dest_account_id = 2;
        string asset_id = 3;
        string description = 4;
        Amount amount = 4;
    }
    
    {
        "commands": [
            {
                "command_type": "TransferAsset",
                "src_account_id": "takemiya@test",
                "dest_account_id": "nikolai@test",
                "asset_id": "coin#test",
                            "description": "Salary payment",
                "amount": {
                    "int_part": 20,
                    "precision": 0
                }
            }
        ], 
    }
    
    Field Description Constraint
    Source account ID ID of account to withdraw asset from already existent, [a-z]{1,9}\@[a-z]{1,9}
    Destination account ID ID of account to send asset at already existent, [a-z]{1,9}\@[a-z]{1,9}
    Asset ID ID of asset to use already existent, [a-z]{1,9}\#[a-z]{1,9}
    Amount amount of asset to transfer 0 < amount < max_uint256

    Validation

    1. Source and destination accounts have this asset in their AccountHasAsset relations.
    2. Precision is formed right.
    3. Source account has this amount of asset to transfer and is not zero.
    4. Source account can transfer money, and destination account can recieve money (their roles have these permissions).

    Append role

    Purpose

    Purpose of append role is to promote an account to some created role in the system, where role is a set or permissions account has to perform an action (command or query).

    Structure

    message AppendRole {
       string account_id = 1;
       string role_name = 2;
    }
    
    {
        "commands": [
            {
                "command_type": "AppendRole",
                "account_id": "takemiya@test",
                "role_name": "Administrator"
            }
        ], 
    }
    
    Field Description Constraint
    Account ID id or account to append role to already existent [a-z]{1,9}\@[a-z]{1,9}
    Role name name of already created role already existent
    Amount amount of asset to transfer 0 < amount < max_uint256

    Validation

    1. Role should exist in the system.
    2. Account triggering command should have permissions to append role.

    Create role

    Purpose

    Purpose of create role is to create new role in the system from the set of permissions. Combining different permissions into roles, maintainers of Iroha peer network can create customized security model.

    Structure

    message CreateRole {
       string role_name = 1;
       repeated string permissions = 2;
    }
    
    {
        "commands": [
            {
                "command_type": "CreateRole",
                "role_name": "MoneyCreator",
                "permissions": [
                    "CanAddAssetQuantity",
                    
                ]
            }
        ], 
    }
    
    Field Description Constraint
    Role name name of role to create [a-z]{1,9}
    Permissions array of already existent permissions set of passed permissions is fully included into set of existing permissions

    Validation

    1. TODO: check if role name is valid
    2. TODO: check if set of passed permissions is fully included into set of existing permissions

    Grant permission

    Purpose

    Purpose of grant permission is to give another account in the system rights to perform actions over account of transaction sender (give someone right to do something with my account).

    Structure

    message GrantPermission {
       string account_id = 1;
       string permission_name = 2;
    }
    
    {
        "commands": [
            {
                "command_type": "GrantPermission",
                "account_id": "takemiya@soramitsu",
                "permission_name": "CanAddAssetQuantity"
            }
        ], 
    }
    
    Field Description Constraint
    Account ID id of account whom rights are granted should be existent in the system
    Permission name name of granted permission permission is defined

    Validation

    1. Account exists
    2. Transaction creator is permitted to grant this permission

    Revoke permission

    Purpose

    Purpose of revoke permission is to revoke or dismiss given grant permission to another account in the network.

    Structure

    message RevokePermission {
       string account_id = 1;
       string permission_name = 2;
    }
    
    {
        "commands": [
            {
                "command_type": "RevokePermission",
                "account_id": "takemiya@soramitsu",
                "permission_name": "CanAddAssetQuantity"
            }
        ], 
    }
    
    Field Description Constraint
    Account ID id of account whom rights were granted should be existent in the system
    Permission name name of revoked permission permission is defined

    Validation

    1. Transaction creator should have previously granted this permission to target account

    Set account detail

    Purpose

    Purpose of set account detail is to set account's key-value information

    Structure

    message SetAccountDetail{
        string account_id = 1;
        string key = 2;
        string value = 3;
    }
    
    {
        "commands": [
            {
                "command_type": "SetAccountDetail",
                "account_id": "takemiya@soramitsu",
                "key": "position",
                "value": "Co-CEO"
            }
        ], 
    }
    
    Field Description Constraint
    Account ID id of account whom key-value information was set should be existent in the system
    Key key of information being set [A-Za-z0-9_]{1,}
    Value value for corresponding key -

    Validation

    1. Creators of transaction consisting that command only can add key-value information for theirs accounts

    Queries

    Query structure

     message Query {
      message Payload {
        uint64 created_time = 1;
        string creator_account_id = 2;
         oneof query {
           GetAccount get_account = 3;
           GetSignatories get_account_signatories = 4;
           GetAccountTransactions get_account_transactions = 5;
           GetAccountAssetTransactions get_account_asset_transactions = 6;
           GetAccountAssets get_account_assets = 7;
           GetRoles get_roles = 8;
           GetAssetInfo get_asset_info = 9;
           GetRolePermissions get_role_permissions = 10;
         }
         // used to prevent replay attacks.
         uint64 query_counter = 11;
      }
    
      Payload payload = 1;
      Signature signature = 2;
    }
    

    Each query consists of following things:

    1. Payload, which contains one created time, id of account creator, query counter and a query of one of possible types
    2. Signature, which signs payload

    Payload stores everything except signatures:

    Signatures contain one or many signatures (ed25519 pubkey + signature):

    Get account

    Purpose

    Purpose of get account query is to get state of an account.

    Given this Query, in successful case Iroha returns AccountResponse, which contains Account object with following fields:

    Structure

    Query

    Query

    message GetAccount {
        string account_id = 1;
    }
    
    {
        "signature":
            {
                "pubkey": "…",
                "signature": "…"
            },
        "created_ts": ,
        "creator_account_id": "admin@test",
        "query_counter": 1,
        "query_type" : "GetAccount",
        "account_id": "test@test"
    }
    
    Field Description Constraint
    Account ID account id to request its state username@domain

    Response

    Response

    message AccountResponse {
        Account account = 1;
    }
    message Account {
        string account_id = 1;
        string domain_name = 2;
        uint32 quorum = 3;
        string json_data = 4;
    }
    
    Field Description Constraint
    Account ID account id [a-z]{1,9}\@[a-z]{1,9}
    Domain name domain of account id [a-z]{1,9}
    Quorum number of signatories needed to sign the transaction to make it valid integer
    json_data key-value information properly formed json information

    Validation

    Stateless validation (check timestamp and signature)

    Get signatories

    Purpose

    Purpose of get signatories query is to get signatories, which act as an identity of the account.

    Given this Query, in successful case Iroha returns SignatoriesResponse, which is one or many public ed25519 keys.

    Structure

    Query

    Query

    message GetSignatories {
        string account_id = 1;
    }
    
    {
        "signature":
            {
                "pubkey": "…",
                "signature": "…"
            },
        "created_ts": ,
        "creator_account_id": "admin@test",
        "query_counter": 1,
        "query_type" : "GetSignatories",
        "account_id": "test@test"
    }
    
    Field Description Constraint
    Account ID account id to request signatories [a-z]{1,9}\@[a-z]{1,9}

    Response

    Response

    message SignatoriesResponse {
        repeated bytes keys = 1;
    }
    
    Field Description Constraint
    Keys an array of public keys ed25519

    Validation

    Stateless validation (check timestamp and signature)

    Get account transactions

    Purpose

    In case when a list of transactions per user is needed, GetAccountTransactions query can be formed.

    Given this Query, in successful case Iroha returns TransactionsResponse, which is a collection of transactions.

    Structure

    Query

    Query

    message GetAccountTransactions {
        string account_id = 1;
    }
    
    {
        "signature":
            {
                "pubkey": "…",
                "signature": "…"
            },
        "created_ts": ,
        "creator_account_id": "admin@test",
        "query_counter": 1,
        "query_type" : "GetAccountTransactions",
        "account_id": "test@test"
    }
    
    Field Description Constraint
    Account ID account id to request transactions from [a-z]{1,9}\@[a-z]{1,9}

    Response

    Response

    message TransactionsResponse {
        repeated Transaction transactions = 1;
    }
    
    Field Description Constraint
    Transactions an array of transactions for given account Committed transaction

    Get account asset transactions

    Purpose

    When an information about transaction per user using certain asset is needed, GetAccountAssetTransactions query is sent.

    Given this Query, in successful case Iroha returns TransactionsResponse, which is a collection of transactions.

    Structure

    Query

    Query

    message GetAccountAssetTransactions {
        string account_id = 1;
        string asset_id = 2;
    }
    
    {
        "signature":
            {
                "pubkey": "…",
                "signature": "…"
            },
        "created_ts": ,
        "creator_account_id": "admin@test",
        "query_counter": 1,
        "query_type" : "GetAccountAssetTransactions",
        "account_id": "test@test",
        "asset_id": "coin#test"
    }
    
    Field Description Constraint
    Account ID account id to request transactions from [a-z]{1,9}\@[a-z]{1,9}
    Asset ID asset id in order to filter transactions containing this asset [a-z]{1,9}\#[a-z]{1,9}

    Response

    Response

    message TransactionsResponse {
        repeated Transaction transactions = 1;
    }
    
    Field Description Constraint
    Transactions an array of transactions for given account and asset Committed transactions

    Get account assets

    Purpose

    To know the state of an asset per account (balance), GetAccountAssets query can be formed.

    Given this Query, in successful case Iroha returns AccountAssetResponse.

    Structure

    Query

    Query

    message GetAccountAssets {
     string account_id = 1;
     string asset_id = 2;
    }
    
    {
        "signature":
            {
                "pubkey": "…",
                "signature": "…"
            },
        "created_ts": ,
        "creator_account_id": "admin@test",
        "query_counter": 1,
        "query_type" : "GetAccountAssets",
        "account_id": "test@test",
        "asset_id": "coin#test",
    }
    
    Field Description Constraint
    Account ID account id to request balance from [a-z]{1,9}\@[a-z]{1,9}
    Asset ID asset id to know its balance [a-z]{1,9}\#[a-z]{1,9}

    Response

    Response

    message AccountAsset {
        string asset_id = 1;
        string account_id = 2;
        Amount balance = 3;
    }
    
    message AccountAssetResponse {
        AccountAsset account_asset = 1;
    }
    
    Field Description Constraint
    Asset ID asset id to knows its balance [a-z]{1,9}\#[a-z]{1,9}
    Account ID account which has this balance [a-z]{1,9}\@[a-z]{1,9}
    Balance balance of asset > 0

    Validation

    Stateless validation (check timestamp and signature)

    Get asset info

    Purpose

    In order to know precision for given asset, and other related info in future, such as description, etc. user can send GetAssetInfo query to Iroha network

    Given this Query, in successful case Iroha returns AssetResponse with an information about the asset.

    Structure

    Query

    Query

    message GetAssetInfo {
        string asset_id = 1;
    }
    
    {
        "signature":
            {
                "pubkey": "…",
                "signature": "…"
            },
        "created_ts": ,
        "creator_account_id": "admin@test",
        "query_counter": 1,
        "query_type" : "GetAssetInfo",
        "asset_id": "coin#test",
    }
    
    Field Description Constraint
    Asset ID asset id to know related information [a-z]{1,9}\#[a-z]{1,9}

    Response

    Response

    message AssetResponse {
    Asset asset = 1;
    }
    
    message Asset {
        string asset_id = 1;
        string domain_id = 2;
        uint32 precision = 3;
    }
    
    Field Description Constraint
    Asset ID asset id to get information about [a-z]{1,9}
    Domain ID domain related to this asset [a-z]{1,9}
    Precision number of digits after comma uint8_t

    Validation

    Stateless validation (check timestamp and signature)

    Get roles

    Purpose

    To get available roles in the system, user can send GetRoles query to Iroha network.

    Given this Query, in successful case Iroha returns RolesResponse containing array of existing roles.

    Structure

    Query

    Query

    message GetRoles {
    }
    
    {
        "signature":
            {
                "pubkey": "…",
                "signature": "…"
            },
        "created_ts": ,
        "creator_account_id": "admin@test",
        "query_counter": 1,
        "query_type" : "GetRoles",
    }
    

    Response

    Response

    message RolesResponse {
        repeated string roles = 1;
    }
    
    Field Description Constraint
    Roles array of created roles in the network vector of strings describing existing roles in the system

    Validation

    Stateless validation (check timestamp and signature)

    Get role permissions

    Purpose

    To get available permissions per role in the system, user can send GetRolePermissions query to Iroha network.

    Given this Query, in successful case Iroha returns RolePermissionsResponse containing array of permissions related to the role.

    Structure

    Query

    Query

    message GetRolePermissions {
        string role_id = 1;
    }
    
    {
        "signature":
            {
                "pubkey": "…",
                "signature": "…"
            },
        "created_ts": ,
        "creator_account_id": "admin@test",
        "query_counter": 1,
        "query_type" : "GetRolePermissions",
        "role_id" : "MoneyCreator",
    }
    
    Field Description Constraint
    Role ID role to get permissions for string describing role existing in the system

    Response

    Response

    message RolePermissionsResponse {
        repeated string permissions = 1;
    }
    
    Field Description Constraint
    Permissions array of permissions related to the role string of permissions related to the role

    Validation

    Stateless validation (check timestamp and signature)

    Command Line Interface

    Iroha Command Line Interface (CLI) is a tool for creation of transaction containing commands from the command line, or sending queries to Iroha. It is intended to simplify interaction between the client side and Iroha peer. CLI could be also used for keypair generation.

    Interactive mode of cli in a nutshell represents number of steps, where at each step user must interact with the system.  To choose one of the options can type short name of the command specified in parentheses, or number of the command in the menu.

    Keypair generation

    To generate files containing private and public keys --new_account flag should be used.

    Example: bash iroha-cli --new_account --name alice@ru --pass_phrase mysupersecretpassword

    After that alice@ru.priv and alice@ru.pub files will be generated in the folder where iroha-cli has been launched.

    Interactive mode 

    Run:  iroha-cli --interactive --name your_account_id 

    Your account_id will be used as the creator of the queries and transactions, signing up messages with accounts keys, fill up counters.  At the start of interactive cli will try to find locally keypairs associated with the account_id, hence this keypairs must be generated and stored locally. 

    Starting menu 

    At the start of cli user has two possible modes:

    image

    Transaction CLI

    Start up of transaction cli will trigger the creation of a new transaction. Each transaction consists of commands, being less or equal than 65000. User is offered to add commands to new formed transaction. All meta data of transaction will be filled automatically (signature, tx_counter, creator account, timestamp). Currently following Iroha commands are supported in Interactive CLI:

    image-2

    Back option will switch back to main menu.  To add command to transaction there two options:

       
    1. Type number of the command in the menu, or command name without parameters:  This will iterate through the parameters of the command and ask user to type the parameter value.  For example typing "1" will create set account quorum, and ask to type account id and quorum: image-3
    2.  

    3. Type command name with all needed parameters .  This option can be used to quickly add command to transaction. For example typing:  set_qrm test@test 2 - will create Set_Account_Quorum command for account: test@test and quorum: 2.
    4.  

    After addition of the command, result menu will be printed:   image-4

    1. User can add more commands to the same transaction
    2. User can send to Iroha peer 
    3. Go back and create new transaction (this will delete previous transaction)
    4. Save transaction as json file locally 

    Query CLI

    Interactive query cli is build similarly as Transaction CLI. Query meta data will be assigned automatically (query_counter, time_stamp,  creator_account, signature) Currently interactive cli supports the following queries:

    image-5

    For each query there two possible modes to run: 

    1. By typing appropriate number of query, either the corresponding abbreviation specified in parentheses.
    2. Typing the command abbreviation with appropriated parameters.
     

    After query is formed there are following options:

    image-6