6.1. Команды

A command changes the state, called World State View, by performing an action over an entity (asset, account) in the system. Any command should be included in a transaction to perform an action.

6.1.1. Добавить определенное количество ассетов

6.1.1.1. Purpose

The purpose of add asset quantity command is to increase the quantity of an asset on account of transaction creator. Use case scenario is to increase the number of a mutable asset in the system, which can act as a claim on a commodity (e.g. money, gold, etc.)

6.1.1.2. Schema

message AddAssetQuantity {
    string asset_id = 1;
    string amount = 2;
}

Примечание

Please note that due to a known issue you would not get any exception if you pass invalid precision value. Valid range is: 0 <= precision <= 255

6.1.1.3. Structure

Field Description Constraint Example
Asset ID id of the asset <asset_name>#<domain_id> usd#morgan
Amount positive amount of the asset to add > 0 200.02

6.1.1.4. Валидация

  1. Asset and account should exist
  2. Added quantity precision should be equal to asset precision
  3. Creator of a transaction should have a role which has permissions for issuing assets

6.1.1.5. Possible Stateful Validation Errors

Code Error Name Description How to solve
1 Could not add asset quantity Internal error happened Try again or contact developers
2 No such permissions Command’s creator does not have permission to add asset quantity Grant the necessary permission
3 No such asset Cannot find asset with such name or such precision Make sure asset id and precision are correct
4 Summation overflow Resulting amount of asset is greater than the system can support Make sure that resulting amount is less than 2^256

6.1.2. Добавить пира

6.1.2.1. Purpose

The purpose of add peer command is to write into ledger the fact of peer addition into the peer network. After a transaction with AddPeer has been committed, consensus and synchronization components will start using it.

6.1.2.2. Schema

message AddPeer {
    Peer peer = 1;
}

message Peer {
    string address = 1;
    bytes peer_key = 2;
}

6.1.2.3. Structure

Field Description Constraint Example
Address resolvable address in network (IPv4, IPv6, domain name, etc.) should be resolvable 192.168.1.1:50541
Peer key peer public key, which is used in consensus algorithm to sign-off vote, commit, reject messages ed25519 public key 292a8714694095edce6be799398ed5d6244cd7be37eb813106b217d850d261f2

6.1.2.4. Валидация

  1. Peer key is unique (there is no other peer with such public key)
  2. Creator of the transaction has a role which has CanAddPeer permission
  3. Such network address has not been already added

6.1.2.5. Possible Stateful Validation Errors

Code Error Name Description How to solve
1 Could not add peer Internal error happened Try again or contact developers
2 No such permissions Command’s creator does not have permission to add peer Grant the necessary permission

6.1.3. Add signatory

6.1.3.1. Purpose

The purpose of add signatory command is to add an identifier to the account. Such identifier is a public key of another device or a public key of another user.

6.1.3.2. Schema

message AddSignatory {
    string account_id = 1;
    bytes public_key = 2;
}

6.1.3.3. Structure

Field Description Constraint Example
Account ID Account to which to add signatory <account_name>@<domain_id> makoto@soramitsu
Public key Signatory to add to account ed25519 public key 359f925e4eeecfdd6aa1abc0b79a6a121a5dd63bb612b603247ea4f8ad160156

6.1.3.4. Валидация

Two cases:

Case 1. Transaction creator wants to add a signatory to his or her account, having permission CanAddSignatory

Case 2. CanAddSignatory was granted to transaction creator

6.1.3.5. Possible Stateful Validation Errors

Code Error Name Description How to solve
1 Could not add signatory Internal error happened Try again or contact developers
2 No such permissions Command’s creator does not have permission to add signatory Grant the necessary permission
3 No such account Cannot find account to add signatory to Make sure account id is correct
4 Signatory already exists Account already has such signatory attached Choose another signatory

6.1.4. Дополнить роль

6.1.4.1. Purpose

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

6.1.4.2. Schema

message AppendRole {
   string account_id = 1;
   string role_name = 2;
}

6.1.4.3. Structure

Field Description Constraint Example
Account ID id or account to append role to already existent makoto@soramitsu
Role name name of already created role already existent MoneyCreator

6.1.4.4. Валидация

  1. The role should exist in the system
  2. Transaction creator should have permissions to append role (CanAppendRole)
  3. Account, which appends role, has set of permissions in his roles that is a superset of appended role (in other words no-one can append role that is more powerful than what transaction creator is)

6.1.4.5. Possible Stateful Validation Errors

Code Error Name Description How to solve
1 Could not append role Internal error happened Try again or contact developers
2 No such permissions Command’s creator does not have permission to append role Grant the necessary permission
3 No such account Cannot find account to append role to Make sure account id is correct
4 No such role Cannot find role with such name Make sure role id is correct

6.1.5. Создать аккаунт

6.1.5.1. Purpose

The purpose of create account command is to make entity in the system, capable of sending transactions or queries, storing signatories, personal data and identifiers.

6.1.5.2. Schema

message CreateAccount {
    string account_name = 1;
    string domain_id = 2;
    bytes public_key = 3;
}

6.1.5.3. Structure

Field Description Constraint Example
Account name domain-unique name for account [a-z_0-9]{1,32} morgan_stanley
Domain ID target domain to make relation with should be created before the account america
Public key first public key to add to the account ed25519 public key 407e57f50ca48969b08ba948171bb2435e035d82cec417e18e4a38f5fb113f83

6.1.5.4. Валидация

  1. Transaction creator has permission to create an account
  2. Domain, passed as domain_id, has already been created in the system
  3. Such public key has not been added before as first public key of account or added to a multi-signature account

6.1.5.5. Possible Stateful Validation Errors

Code Error Name Description How to solve
1 Could not create account Internal error happened Try again or contact developers
2 No such permissions Command’s creator either does not have permission to create account or tries to create account in a more privileged domain, than the one creator is in Grant the necessary permission or choose another domain
3 No such domain Cannot find domain with such name Make sure domain id is correct
4 Account already exists Account with such name already exists in that domain Choose another name

6.1.6. Создать тип ассета

6.1.6.1. Purpose

The purpose of сreate asset command is to create a new type of asset, unique in a domain. An asset is a countable representation of a commodity.

6.1.6.2. Schema

message CreateAsset {
    string asset_name = 1;
    string domain_id = 2;
    uint32 precision = 3;
}

Примечание

Please note that due to a known issue you would not get any exception if you pass invalid precision value. Valid range is: 0 <= precision <= 255

6.1.6.3. Structure

Field Description Constraint Example
Asset name domain-unique name for asset [a-z_0-9]{1,32} soracoin
Domain ID target domain to make relation with RFC1035 [1], RFC1123 [2] japan
Precision number of digits after comma/dot 0 <= precision <= 255 2

6.1.6.4. Валидация

  1. Transaction creator has permission to create assets
  2. Asset name is unique in domain

6.1.6.5. Possible Stateful Validation Errors

Code Error Name Description How to solve
1 Could not create asset Internal error happened Try again or contact developers
2 No such permissions Command’s creator does not have permission to create asset Grant the necessary permission
3 No such domain Cannot find domain with such name Make sure domain id is correct
4 Asset already exists Asset with such name already exists Choose another name

6.1.7. Создать домен

6.1.7.1. Purpose

The purpose of create domain command is to make new domain in Iroha network, which is a group of accounts.

6.1.7.2. Schema

message CreateDomain {
    string domain_id = 1;
    string default_role = 2;
}

6.1.7.3. Structure

Field Description Constraint Example
Domain ID ID for created domain unique, RFC1035 [1], RFC1123 [2] japan05
Default role role for any created user in the domain one of the existing roles User

6.1.7.4. Валидация

  1. Domain ID is unique
  2. Account, who sends this command in transaction, has role with permission to create domain
  3. Role, which will be assigned to created user by default, exists in the system

6.1.7.5. Possible Stateful Validation Errors

Code Error Name Description How to solve
1 Could not create domain Internal error happened Try again or contact developers
2 No such permissions Command’s creator does not have permission to create domain Grant the necessary permission
3 Domain already exists Domain with such name already exists Choose another domain name
4 No default role found Role, which is provided as a default one for the domain, is not found Make sure the role you provided exists or create it

6.1.8. Создать роль

6.1.8.1. Purpose

The purpose of create role command is to create a 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.

6.1.8.2. Schema

message CreateRole {
    string role_name = 1;
    repeated RolePermission permissions = 2;
}

6.1.8.3. Structure

Field Description Constraint Example
Role name name of role to create [a-z_0-9]{1,32} User
RolePermission array of already existent permissions set of passed permissions is fully included into set of existing permissions {can_receive, can_transfer}

6.1.8.4. Валидация

  1. Set of passed permissions is fully included into set of existing permissions
  2. Set of the permissions is not empty

6.1.8.5. Possible Stateful Validation Errors

Code Error Name Description How to solve
1 Could not create role Internal error happened Try again or contact developers
2 No such permissions Command’s creator does not have permission to create role Grant the necessary permission
3 Role already exists Role with such name already exists Choose another role name

6.1.9. Отключить роль

6.1.9.1. Purpose

The purpose of detach role command is to detach a role from the set of roles of an account. By executing this command it is possible to decrease the number of possible actions in the system for the user.

6.1.9.2. Schema

message DetachRole {
    string account_id = 1;
    string role_name = 2;
}

6.1.9.3. Structure

Field Description Constraint Example
Account ID ID of account where role will be deleted already existent makoto@soramitsu
Role name a detached role name existing role User

6.1.9.4. Валидация

  1. The role exists in the system
  2. The account has such role

6.1.9.5. Possible Stateful Validation Errors

Code Error Name Description How to solve
1 Could not detach role Internal error happened Try again or contact developers
2 No such permissions Command’s creator does not have permission to detach role Grant the necessary permission
3 No such account Cannot find account to detach role from Make sure account id is correct
4 No such role in account’s roles Account with such id does not have role with such name Make sure account-role pair is correct
5 No such role Role with such name does not exist Make sure role id is correct

6.1.10. Предоставить полномочия

6.1.10.1. Purpose

The purpose of grant permission command is to give another account rights to perform actions on the account of transaction sender (give someone right to do something with my account).

6.1.10.2. Schema

message GrantPermission {
    string account_id = 1;
    GrantablePermission permission = 2;
}

6.1.10.3. Structure

Field Description Constraint Example
Account ID id of the account to which the rights are granted already existent makoto@soramitsu
GrantablePermission name name of grantable permission permission is defined CanTransferAssets

6.1.10.4. Валидация

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

6.1.10.5. Possible Stateful Validation Errors

Code Error Name Description How to solve
1 Could not grant permission Internal error happened Try again or contact developers
2 No such permissions Command’s creator does not have permission to grant permission Grant the necessary permission
3 No such account Cannot find account to grant permission to Make sure account id is correct

6.1.11. Remove signatory

6.1.11.1. Purpose

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

6.1.11.2. Schema

message RemoveSignatory {
    string account_id = 1;
    bytes public_key = 2;
}

6.1.11.3. Structure

Field Description Constraint Example
Account ID id of the account to which the rights are granted already existent makoto@soramitsu
Public key Signatory to delete ed25519 public key 407e57f50ca48969b08ba948171bb2435e035d82cec417e18e4a38f5fb113f83

6.1.11.4. Валидация

  1. When signatory is deleted, we should check if invariant of size(signatories) >= quorum holds
  2. Signatory should have been previously added 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. CanRemoveSignatory was granted to transaction creator

6.1.11.5. Possible Stateful Validation Errors

Code Error Name Description How to solve
1 Could not remove signatory Internal error happened Try again or contact developers
2 No such permissions Command’s creator does not have permission to remove signatory from his account Grant the necessary permission
3 No such account Cannot find account to remove signatory from Make sure account id is correct
4 No such signatory Cannot find signatory with such public key Make sure public key is correct
5 Quorum does not allow to remove signatory After removing the signatory account will be left with less signatories, than its quorum allows Reduce the quorum

6.1.12. Отозвать полномочия

6.1.12.1. Purpose

The purpose of revoke permission command is to revoke or dismiss given granted permission from another account in the network.

6.1.12.2. Schema

message RevokePermission {
    string account_id = 1;
    GrantablePermission permission = 2;
}

6.1.12.3. Structure

Field Description Constraint Example
Account ID id of the account to which the rights are granted already existent makoto@soramitsu
GrantablePermission name name of grantable permission permission was granted CanTransferAssets

6.1.12.4. Валидация

Transaction creator should have previously granted this permission to a target account

6.1.12.5. Possible Stateful Validation Errors

Code Error Name Description How to solve
1 Could not revoke permission Internal error happened Try again or contact developers
2 No such permissions Command’s creator does not have permission to revoke permission Grant the necessary permission
3 No such account Cannot find account to revoke permission from Make sure account id is correct

6.1.13. Set account detail

6.1.13.1. Purpose

Purpose of set account detail command is to set key-value information for a given account

Предупреждение

If there was a value for a given key already in the storage then it will be replaced with the new value

6.1.13.2. Schema

message SetAccountDetail{
    string account_id = 1;
    string key = 2;
    string value = 3;
}

6.1.13.3. Structure

Field Description Constraint Example
Account ID id of the account to which the key-value information was set already existent makoto@soramitsu
Key key of information being set [A-Za-z0-9_]{1,64} Name
Value value of corresponding key ≤ 4096 Makoto

6.1.13.4. Валидация

Two cases:

Case 1. When transaction creator wants to set account detail to his/her account and he or she has permission CanSetAccountInfo

Case 2. CanSetAccountInfo was granted to transaction creator

6.1.13.5. Possible Stateful Validation Errors

Code Error Name Description How to solve
1 Could not set account detail Internal error happened Try again or contact developers
2 No such permissions Command’s creator does not have permission to set account detail for another account Grant the necessary permission
3 No such account Cannot find account to set account detail to Make sure account id is correct

6.1.14. Установить кворум для аккаунта

6.1.14.1. Purpose

The purpose of set account quorum command is to set the number of signatories required to confirm the identity of a user, who creates the transaction. Use case scenario is to set the number of different users, utilizing single account, to sign off the transaction.

6.1.14.2. Schema

message SetAccountQuorum {
    string account_id = 1;
    uint32 quorum = 2;
}

6.1.14.3. Structure

Field Description Constraint Example
Account ID ID of account to set quorum already existent makoto@soramitsu
Quorum number of signatories needed to be included within a transaction from this account 0 < quorum ≤ public-key set up to account ≤ 128 5

6.1.14.4. Валидация

When quorum is set, it is checked 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. CanRemoveSignatory was granted to transaction creator

6.1.14.5. Possible Stateful Validation Errors

Code Error Name Description How to solve
1 Could not set quorum Internal error happened Try again or contact developers
2 No such permissions Command’s creator does not have permission to set quorum for his account Grant the necessary permission
3 No such account Cannot find account to set quorum to Make sure account id is correct
4 No signatories on account Cannot find any signatories attached to the account Add some signatories before setting quorum
5 New quorum is incorrect New quorum size is less than account’s signatories amount Choose another value or add more signatories

6.1.15. Subtract asset quantity

6.1.15.1. Purpose

The purpose of subtract asset quantity command is the opposite of AddAssetQuantity commands — to decrease the number of assets on account of transaction creator.

6.1.15.2. Schema

message SubtractAssetQuantity {
    string asset_id = 1;
    string amount = 2;
}

Примечание

Please note that due to a known issue you would not get any exception if you pass invalid precision value. Valid range is: 0 <= precision <= 255

6.1.15.3. Structure

Field Description Constraint Example
Asset ID id of the asset <asset_name>#<domain_id> usd#morgan
Amount positive amount of the asset to subtract > 0 200

6.1.15.4. Валидация

  1. Asset and account should exist
  2. Added quantity precision should be equal to asset precision
  3. Creator of the transaction should have a role which has permissions for subtraction of assets

6.1.15.5. Possible Stateful Validation Errors

Code Error Name Description How to solve
1 Could not subtract asset quantity Internal error happened Try again or contact developers
2 No such permissions Command’s creator does not have permission to subtract asset quantity Grant the necessary permission
3 No such asset found Cannot find asset with such name or precision in account’s assets Make sure asset name and precision are correct
4 Not enough balance Account’s balance is too low to perform the operation Add asset to account or choose lower value to subtract

6.1.16. Перевести ассеты

6.1.16.1. Purpose

The purpose of transfer asset command is to share assets within the account in peer network: in the way that source account transfers assets to the target account.

6.1.16.2. Schema

message TransferAsset {
    string src_account_id = 1;
    string dest_account_id = 2;
    string asset_id = 3;
    string description = 4;
    string amount = 5;
}

6.1.16.3. Structure

Field Description Constraint Example
Source account ID ID of the account to withdraw the asset from already existent makoto@soramitsu
Destination account ID ID of the account to send the asset to already existent alex@california
Asset ID ID of the asset to transfer already existent usd#usa
Description Message to attach to the transfer Max length is 64 here’s my money take it
Amount amount of the asset to transfer 0 <= precision <= 255 200.20

6.1.16.4. Валидация

  1. Source account has this asset in its AccountHasAsset relation [1]
  2. An amount is a positive number and asset precision is consistent with the asset definition
  3. Source account has enough amount of asset to transfer and is not zero
  4. Source account can transfer money, and destination account can receive money (their roles have these permissions)

6.1.16.5. Possible Stateful Validation Errors

Code Error Name Description How to solve
1 Could not transfer asset Internal error happened Try again or contact developers
2 No such permissions Command’s creator does not have permission to transfer asset from his account Grant the necessary permission
3 No such source account Cannot find account with such id to transfer money from Make sure source account id is correct
4 No such destination account Cannot find account with such id to transfer money to Make sure destination account id is correct
5 No such asset found Cannot find such asset Make sure asset name and precision are correct
6 Not enough balance Source account’s balance is too low to perform the operation Add asset to account or choose lower value to subtract
7 Too much asset to transfer Resulting value of asset amount overflows destination account’s amount Make sure final value is less than 2^256
[1](1, 2, 3) https://www.ietf.org/rfc/rfc1035.txt
[2](1, 2) https://www.ietf.org/rfc/rfc1123.txt