Iroha is a simple and efficient blockchain ledger based on the distributed ledger technology (DLT). Its design principles are inspired by the Japanese Kaizen principle of eliminating excesses (muri).
Iroha can help you manage your accounts, assets, on-chain data storage with efficient smart contracts, while being Byzantine- and crash-fault tolerant.
Iroha is a fully-featured blockchain ledger. With Iroha you can:
- Create and manage custom fungible assets, such as currencies, gold, and others
- Create and manage non-fungible assets
- Manage user accounts with a domain hierarchy and multi-signature transactions
- Use efficient portable smart contracts implemented either via WebAssembly or Iroha Special Instructions
- Use both permissioned and permission-less blockchain deployments
Iroha offers:
- Byzantine fault-tolerance with up to 33% fault rate
- Efficient in-memory operations
- Extensive telemetry support out of the box
- Modular structure
- Event-driven architecture with strongly-typed events
- Check system requirements and instructions on how to build and run Iroha
- Learn about the crates Iroha provides
- Learn how to configure and use Iroha
- Read more about Iroha
Engage with the community:
- Contribute to the repository
- Contact us to get help
RAM and storage requirements depend on your use case: whether you need to build or deploy a network, how big it is, and so on. This table summarises the requirements:
| Use case | CPU | RAM | Storage1 |
|---|---|---|---|
| Build (minimum) | Dual-core CPU | 4GB | 20GB |
| Build (recommend) | AMD Ryzen™ 5 1600 | 16GB | 40GB |
| Deploy (small) | Dual-core CPU | 8GB+ | 20GB+ |
| Deploy (large) | AMD Epyc™ 64-core | 128GB | 128GB+ |
Regarding RAM requirements:
- On average, you need 5 KiB of RAM per account. A network with 1 000 000 accounts uses 5GiB of memory.
- Each transfer or Mint instruction requires 1 KiB per instruction.
- RAM usage grows linearly, as all transactions are stored in memory. You should expect to consume more RAM with a higher TPS and uptime.
CPU considerations:
- Rust compilation highly favours multi-core CPUs such as Apple M1™, AMD Ryzen™/Threadripper™/Epyc™, and Intel Alder Lake™.
- On systems with restricted memory and many CPU cores, Iroha compilation may sometimes fail with
SIGKILL. To avoid it, restrict the number of CPU cores usingcargo build -j <number>, where<number>(without the angle brackets) is half of your RAM capacity rounded down.
Prerequisites:
- Rust
- (Optional) Docker
- (Optional) Docker Compose
(Optional) Run included tests
Run included code tests:
cargo testRun API functional tests:
cargo build
chmod +x target/debug/iroha
chmod +x target/debug/iroha_client_cli
bash ./scripts/test_env.sh setup
bash ./scripts/tests/register_mint_quantity.sh
bash ./scripts/test_env.sh cleanupTo generate WASM files for smart contracts, use the provided script generate_wasm.sh. If you are in the root directory of iroha run the following command:
bash ./scripts/generate_wasm.sh [path/to/smartcontracts]The generated WASM files will be saved in a generated directory test-smartcontracts, relative to your current working directory. The default path for smart contracts in this project is client/tests/integration/smartcontracts.
-
Build Iroha and accompanying binaries:
cargo build
-
(Optional) Build the latest Iroha image:
docker build . -t hyperledger/iroha2:devIf you skip this step, the Iroha container will be built using the latest available image.
Once you have built Iroha, you can instantiate the minimum viable network:
docker compose up
With the docker-compose instance running, use Iroha Client CLI:
cargo run --bin iroha_client_cli -- --config ./configs/swarm/client.tomlIroha project mainly consists of the following crates:
irohais the command-line application for deploying an Iroha peer. Contains the routing table and definitions of API endpoints.iroha_actorprovides a message passing model for Iroha components.iroha_clientprovides a library for building clients that communicate with peers.iroha_client_cliis the reference implementation of a client.iroha_confighandles configuration and documentation generation for options and run-time changes.iroha_coreis the primary library used by all other crates, including the peer endpoint management.iroha_cryptodefines cryptographic aspects of Iroha.kagamiis used to generate cryptographic keys, default genesis, configuration reference, and schema.iroha_data_modeldefines common data models in Iroha.iroha_futuresis used forasyncprogramming.iroha_loggerusestracingto provide logging facilities.iroha_macroprovides the convenience macros.iroha_p2pdefines peer creation and handshake logic.iroha_default_executordefines runtime validation logic.iroha_telemetryis used for monitoring and analysis of telemetry data.iroha_versionprovides message versioning for non-simultaneous system updates.
A brief overview on how to configure and maintain an Iroha instance:
There is a set of configuration parameters that could be passed either through a configuration file or environment variables.
iroha --config /path/to/config.tomlNote: detailed configuration reference is work in progress.
For a list of all endpoints, available operations, and ways to customize them with parameters, see API Reference > Torii Endpoints
By default, Iroha provides logs in a human-readable format and prints them out to stdout.
The logging level can be changed either via the logger.level configuration parameter or at run-time using the configuration endpoint.
Example: changing log level
For example, if your Iroha instance is running at 127.0.0.1:8080 and you want to change the log level to DEBUG using curl, you should send a POST request with a JSON containing the new log level. Like this:
curl -X POST \
-H 'content-type: application/json' \
http://127.0.0.1:8080/configuration \
-d '{"logger": {"level": "DEBUG"}}' -iThe log format might be configured via the logger.format configuration parameter. Possible values are: full (default), compact, pretty, and json.
Output goes to /dev/stdout. Piping to files or log rotation is the responsibility of the peer administrator.
The details of the Health endpoint can be found in the API Reference > Torii Endpoints.
Iroha can produce both JSON-formatted as well as prometheus-readable metrics at the status and metrics endpoints respectively.
The prometheus monitoring system is the de-factor standard for monitoring long-running services such as an Iroha peer. In order to get started, install prometheus and use configs/prometheus.template.yml for configuration.
Iroha stores blocks and snapshots in the storage directory, which is created automatically by Iroha in the working directory of the peer. If kura.block_store_path is specified in the config file, it overrides the default one and is resolved relative to the config file location.
Note: detailed configuration reference is work in progress.
Multiple instances of Iroha peer and client binaries can be run on the same physical machine and in the same working directory. However, we recommend to give each instance a clean new working directory.
The provided docker-compose file showcases a minimum viable network and the general methods of using the hyperledger/iroha2:dev docker image for deploying a network of peers.
We encourage you to check out our Iroha 2 Tutorial first. It is suitable for both experienced developers and prospective users of Iroha 2, and it provides language-specific guides for Bash, Python, Rust, Kotlin/Java, and Javascript/TypeScript.
Iroha SDKs:
We welcome community contributions! Report bugs and suggest improvements via GitHub issues and pull requests.
Check out our contributing guide to learn more.
Check out the channels you could use to get help or engage with the community.
Iroha codebase is licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
Iroha documentation files are made available under the Creative Commons Attribution 4.0 International License (CC-BY-4.0), available at http://creativecommons.org/licenses/by/4.0/
Footnotes
-
Note that all operations are done in RAM, so in theory Iroha can work without persistent storage. However, since synchronising blocks over the network after a power failure may take a long time, we recommend adding a hard drive. ↩
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent