Skip to content

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 tutorial for Rust or Python, you've already seen a couple of instructions: Register<Account> and Mint<Quantity>.

In the chapter on blockchain objects, we provide you with a summary of Iroha Special Instructions: what objects each instruction can be called for, and what are the instructions available for each object.

Here we present you with an overview of each instruction.

InstructionDescriptions
Register/UnregisterGive an ID to a new entity on the blockchain.
Mint/BurnMint/burn assets, triggers, or permission tokens.
SetKeyValue/RemoveKeyValueUpdate metadata of blockchain objects.
Grant/RevokeGive or remove certain permissions from accounts.
TransferTransfer assets between accounts.
ExecuteTriggerExecute triggers.
If, Pair, SequenceUse to create composite instructions.

(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 (more on them later).

Registering a peer is currently the only way of adding peers that were not part of the original TRUSTED_PEERS array to the network.

Registering an account is different. Iroha can be compiled in two modes: public and private. If it's compiled with private permissions, to register an account, you need an account. This is the default. If you want your users to be able to register without access to a pre-existing account, you need to compile Iroha in the public mode.

INFO

As of writing, the set of public blockchain permissions is incomplete, and as such Iroha source code needs to be modified to run it in the public mode.

Refer to one of the language-specific guides to walk you through the process of registering objects in a blockchain:

LanguageGuide
BashRegister a domain, an account, an asset
RustRegister a domain, an account, an asset
Kotlin/JavaRegister a domain, an account, an asset
PythonRegister a domain, an account, an asset
JavaScript/TypeScriptRegister 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 -1.0 of time or Burn a negative amount and get a Mint.

Transfer

Similar to mint and burn instructions, transferring refers to assets. You can transfer assets between different accounts.

Grant/Revoke

These are used for 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.

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 condition
  • Sequence: execute a provided vector of instructions in a given order
  • Pair: execute both provided instructions in a specified order