Iroha Special Instructions
When we spoke about how Iroha operates, we said that Iroha Special Instructions are the only way to modify the world state. So, what kind of special instructions do we have? If you've read the language-specific guides in this tutorial, you've already seen a couple of instructions: Register<Account> and Mint<Quantity>.
Here is the full list of Iroha Special Instructions:
| Instruction | Descriptions |
|---|---|
| Register/Unregister | Give an ID to a new entity on the blockchain. |
| Mint/Burn | Mint/burn assets, triggers, or permission tokens. |
| SetKeyValue/RemoveKeyValue | Update blockchain object metadata. |
| NewParameter/SetParameter | Create/set a chain-wide config parameter. |
| Grant/Revoke | Give or remove certain permissions from accounts. |
| Transfer | Transfer assets between accounts. |
| ExecuteTrigger | Execute triggers. |
| If, Pair, Sequence | Use to create composite instructions. |
Let's start with a summary of Iroha Special Instructions; what objects each instruction can be called for and what instructions are available for each object.
Summary
Diagram: Iroha Special Instructions
For each instruction, there is a list of objects on which this instruction can be run on. For example, only assets can be transferred, while minting can refer to assets, triggers, and permission tokens.
Some instructions require a destination to be specified. For example, if you transfer assets, you always need to specify to which account you are transferring them. On the other hand, when you are registering something, all you need is the object that you want to register.
| Instruction | Objects | Destination |
|---|---|---|
| Register/Unregister | accounts, domains, asset definitions, triggers, roles, peers | |
| Mint/Burn | assets, triggers (trigger repetitions), permission tokens | accounts |
| SetKeyValue/RemoveKeyValue | any objects that have metadata: accounts, domains, assets, asset definitions, triggers, transactions | |
| NewParameter/SetParameter | Iroha configuration parameters | |
| Grant/Revoke | roles, permission tokens | accounts |
| Transfer | assets | accounts |
| ExecuteTrigger | triggers | |
| If, Pair, Sequence | any instructions |
There is also another way of looking at ISI, i.e. in terms of the target of each instruction. For example, when you register an account, you do so within a certain domain. This means that the target of the Register<Account> instruction would be the domain within which it is being registered.
| Target | Instructions |
|---|---|
| Account | (un)register assets, mint/burn account public key, mint/burn account signature condition check, update account metadata, grant/revoke a permission token, grant/revoke role |
| Domain | (un)register accounts, (un)register asset definitions, update asset metadata, update domain metadata |
| Asset | update metadata, mint/burn, transfer |
| Trigger | (un)register, mint/burn trigger repetitions, execute trigger |
| World | (un)register domains, peers, roles |
(Un)Register
Registering and unregistering are the instructions used to give an ID to a new entity on the blockchain.
Everything that can be registered is both Registrable and Identifiable, but not everything that's Identifiable is Registrable. Most things are registered directly, like Peers, but in some cases the representation in the blockchain has considerably more data. For security and performance reasons, we use builders for such data structures (e.g. NewAccount). As a rule, everything that can be registered, can also be un-registered, but that is not a hard and fast rule.
You can register domains, accounts, asset definitions, peers, roles, and triggers. Check our naming conventions to learn about the restrictions put on entity names.
INFO
Note that depending on how you decide to set up your genesis block in genesis.json (specifically, whether or not you include registration of permission tokens), the process for registering an account can be very different. In general, we can summarise it like this:
- In a public blockchain, anyone should be able to register an account.
- In a private blockchain, there can be a unique process for registering accounts. In a typical private blockchain, i.e. a blockchain without any unique processes for registering accounts, you need an account to register another account.
We discuss these differences in great detail when we compare private and public blockchains.
INFO
Registering a peer is currently the only way of adding peers that were not part of the original TRUSTED_PEERS array to the network.
Refer to one of the language-specific guides to walk you through the process of registering objects in a blockchain:
| Language | Guide |
|---|---|
| Bash | Register a domain, an account, an asset |
| Rust | Register a domain, an account, an asset |
| Kotlin/Java | Register a domain, an account, an asset |
| Python | Register a domain, an account, an asset |
| JavaScript/TypeScript | Register a domain, an account, an asset |
Mint/Burn
Minting and burning can refer to assets, triggers (if the trigger has a limited number of repetitions), and temporary permission tokens. Some assets can be declared as non-mintable, meaning that they can be minted only once after registration.
Assets and permission tokens need to be minted to a specific account, usually the one that registered the asset in the first place. All assets are assumed to be non-negative as well, so you can never have of time or Burn a negative amount and get a Mint.
Refer to one of the language-specific guides to walk you through the process of minting assets in a blockchain:
Here are examples of burning assets:
Transfer
Similar to mint and burn instructions, transferring refers to assets. You can transfer assets between different accounts.
To do this, an account have to be granted the permission to transfer assets. Refer to an example on how to transfer assets in Bash.
Grant/Revoke
Grant and revoke instructions are used for account permissions and roles.
Grant is used to permanently grant a user either a single permission, or a group of permissions (a "role"). Granted roles and permissions can only be removed via the Revoke instruction. As such, these instructions should be used carefully.
SetKeyValue/RemoveKeyValue
These instructions are used with the key/value Store asset type. This use case has not received much attention so far, because storing data in the blockchain is a rather advanced topic that we shall cover separately.
NewParameter/SetParameter
With these instructions, you can create (NewParameter) and change (SetParameter) chain-wide configuration parameters for Iroha.
ExecuteTrigger
This instruction is used to execute triggers.
Composite instructions
Iroha also offers composite instructions (If, Pair, Sequence) to execute instructions in a certain way:
If: execute one of the two given instructions based on a given conditionSequence: execute a provided vector of instructions in a given orderPair: execute both provided instructions in a specified order