Skip to content

Keys for Network Deployment

If you're deploying your own Iroha 2 network, your unique cryptographic keys must be specified in all three of the configuration files:

  1. Peer configuration file: configs/peer/config.json
  2. Client configuration file: configs/client_cli/config.json
  3. Genesis block file: configs/peer/genesis.json

To learn more about cryptographic keys and their role, see Security > Public Key Cryptography.

Setting Keys For a New Network

1. Generate New Key Pairs

To generate new key pairs for the peers, a wide variety of methods can be used. However, within the Iroha 2 framework, you can conveniently use the built-in kagami tool for generating cryptographic keys.

To generate a new key pair run the following command from the project's root directory:

$ cargo run --bin kagami --release -- crypto --json


The output cryptographic keys generated by kagami are customizable by using preferences. Note that in the example above the --json parameter is specified to generate a key pair in the JSON format.

To learn more about generating cryptographic keys with kagami, available algorithms, and other parameters, see Generating Cryptographic Keys with Kagami.

If you plan to use the generated private_key with one of our SDKs, note that even though cryptographic keys are commonly encoded using ASCII characters, both the payload value of the private_key and the string representation of the public_key are encoded as Hex.

2. Update Keys For Peers

If you want to set up your own network, you should change the keys for all your peers: in peer/config.json change PUBLIC_KEY and PRIVATE_KEY to the fresh pair. When you've done that, you should add the keys to the TRUSTED_PEERS array in the same configuration file. Every peer that wants to connect to the given peer from the outside must know its PRIVATE_KEY specified in the TRUSTED_PEERS section.

To create a minimum BFT network one needs four peers, which means four different private keys split across four different configuration files (or environment variables).

Each peer must have their own PUBLIC_KEY and PRIVATE_KEY variables specified. All four of the public keys—including the peer that is being configured—must be added to the TRUSTED_PEERS array. The same TRUSTED_PEERS array must be copied across all four of the configuration files. If either one of the peers is missing, or there's an extraneous peer or one of the peers has the incorrect key, the network will fail to start.

After that, make sure that the peers agree on the GENESIS_ACCOUNT key pairs. Failure to do so will result in a network which cannot accept any transactions.


Even though the private key for the genesis account is known to all peers, the account itself loses all privileges after the first block is committed.

3. Register a Non-Genesis Account

Finally, while the first client could use the genesis account to register new users, it's not a great idea for most networks. You should, instead, register a non-genesis account (for example, alice@wonderland).


iroha_client_cli currently processes all of its instructions in the JSON format, it also provides a dedicated instruction to unregister accounts.

If you plan on creating a private blockchain, you should consider writing your own client based on the client Rust crate, or any of the provided client libraries: