iroha
# Hyperledger Iroha [](https://opensource.org/licenses/Apache-2.0) Hyperledger Iroha is a deterministic blockchain platform for permissioned and consortium deployments. It provides account/asset management, on-chain permissions, and smart contracts through the Iroha Virtual Machine (IVM). > Workspace status and recent changes are tracked in [`status.md`](./status.md). ## Release Tracks This repository ships two deployment tracks from the same codebase: - **Iroha 2**: self-hosted permissioned/consortium networks. - **Iroha 3 (SORA Nexus)**: the Nexus-oriented deployment track using the same core crates. Both tracks share the same core components, including Norito serialization, Sumeragi consensus, and the Kotodama -> IVM toolchain. ## Repository Layout - [`crates/`](./crates): core Rust crates (`iroha`, `irohad`, `iroha_cli`, `iroha_core`, `ivm`, `norito`, etc.). - [`integration_tests/`](./integration_tests): cross-component network/integration tests. - [`IrohaSwift/`](./IrohaSwift): Swift SDK package. - [`java/iroha_android/`](./java/iroha_android): Android SDK package. - [`docs/`](./docs): user/operator/developer documentation. ## Quickstart ### Prerequisites - [Rust stable](https://www.rust-lang.org/tools/install) - Optional: Docker + Docker Compose for local multi-peer runs ### Build and Test (Workspace) ```bash cargo test cargo build --workspace cargo test --workspace cargo clippy --workspace --all-targets -- -D warnings cargo fmt --all ``` Notes: - Plain `cargo test` from the repository root runs every workspace member. `cargo test --workspace` is kept in examples when an explicit full-workspace command is clearer. Use `cargo test -p <crate>` for a focused crate suite. - Full workspace build can take about 20 minutes. - Full workspace tests can take multiple hours. - The workspace targets `std` (WASM/no-std builds are not supported). - Heavier local UI/media helpers are explicit features in default builds: `cargo run -p mochi-ui --features gui` for the egui desktop shell and `cargo run -p iroha_cli --features offline-visual-codecs -- ...` for Petal visual-codec commands. The SoraFS browser/SDK local QUIC proxy is available with `cargo build -p sorafs_orchestrator --features local-quic-proxy`. ### Targeted Test Commands ```bash cargo test -p <crate> cargo test -p <crate> <test_name> -- --nocapture ``` ### SDK Test Commands ```bash cd IrohaSwift swift test ``` ```bash cd java/iroha_android JAVA_HOME=$(/usr/libexec/java_home -v 21) \ ANDROID_HOME=~/Library/Android/sdk \ ANDROID_SDK_ROOT=~/Library/Android/sdk \ ./gradlew test ``` ## Run a Local Network Start the provided Docker Compose network: ```bash docker compose -f defaults/docker-compose.yml up ``` Use the CLI against the default client config: ```bash cargo run --bin iroha -- --config ./defaults/client.toml --help ``` For daemon-specific native deployment steps, see [`crates/irohad/README.md`](./crates/irohad/README.md). ## API and Observability Torii exposes both Norito and JSON APIs. Common operator endpoints: - `GET /status` - `GET /metrics` - `GET /v1/parameters` - `GET /v1/events/sse` See the full endpoint reference in: - [`docs/source/telemetry.md`](./docs/source/telemetry.md) - [`docs/portal/docs/reference/README.md`](./docs/portal/docs/reference/README.md) For contract apps, Torii now exposes both single-contract deploy and bundle deploy surfaces. The maintained public path is: - `iroha contract app build|plan|deploy|resume` for `iroha.app.toml` bundles - `POST /v1/contracts/deploy-bundle` for compiled bundle deploys (`?dry_run=true` for deterministic planning) - `GET /v1/contracts/deploy-bundles/{bundle_digest}` for receipt/status lookup - `POST /v1/contracts/deploy` for the single-contract path, implemented through the same planner/executor as a one-contract bundle - `POST /v1/contracts/view/batch` for batched read-only contract queries in one round-trip For the public-safe Torii posture, contract deploy/call/view/status routes stay public, while higher-risk app-facing surfaces are opt-in: - `torii.webhooks_enabled = false` by default - `torii.zk_attachments_enabled = false` by default - `torii.deploy_rate_per_origin_per_sec = 4` plus `torii.deploy_burst_per_origin = 8` are the public deploy baseline - trader/app rollups such as `/v1/contracts/rollups/swaps/fills` and `/v1/contracts/rollups/trader/account` remain app-facing surfaces rather than part of the public-safe baseline - enable them explicitly when the node is meant to expose those app features ## Codex Integration This repo includes Codex-facing SORA live-network surfaces: - [`plugins/iroha/`](./plugins/iroha): an installable Codex app/plugin with the built-in Taira MCP preset. - [`skills/sora-taira-testnet/`](./skills/sora-taira-testnet): a standalone Codex skill for live Taira testnet workflows. - [`skills/sora-minamoto-mainnet/`](./skills/sora-minamoto-mainnet): a standalone Codex skill for live Minamoto mainnet workflows. Install a standalone skill from a GitHub checkout of this repo with: ```bash python3 "${CODEX_HOME:-$HOME/.codex}"/skills/.system/skill-installer/scripts/install-skill-from-github.py \ --repo <owner>/<repo> \ --path skills/sora-taira-testnet python3 "${CODEX_HOME:-$HOME/.codex}"/skills/.system/skill-installer/scripts/install-skill-from-github.py \ --repo <owner>/<repo> \ --path skills/sora-minamoto-mainnet ``` Restart Codex after installation so the selected skill appears in the Skills tab. If you are operating the public Taira deployment itself, render per-validator configs from `configs/soranexus/taira/validator_roster.example.toml` plus `configs/soranexus/taira/validator_secrets.example.toml` with `python3 scripts/render_taira_validator_bundle.py --roster ... --secrets ... --output-dir ...` instead of cloning the checked-in peer-1 `config.toml` by hand. The secrets template now also carries the shared onboarding/faucet authority and streaming identity material, so the checked-in Taira config remains a template rather than a secret-bearing runtime profile. ## Core Crates - [`crates/iroha`](./crates/iroha): client library. - [`crates/irohad`](./crates/irohad): peer daemon binaries. - [`crates/iroha_cli`](./crates/iroha_cli): reference CLI. - [`crates/iroha_core`](./crates/iroha_core): ledger/core execution engine. - [`crates/iroha_config`](./crates/iroha_config): typed configuration model. - [`crates/iroha_data_model`](./crates/iroha_data_model): canonical data model. - [`crates/iroha_crypto`](./crates/iroha_crypto): cryptographic primitives. - [`crates/norito`](./crates/norito): deterministic serialization codec. - [`crates/ivm`](./crates/ivm): Iroha Virtual Machine. - [`crates/iroha_kagami`](./crates/iroha_kagami): key/genesis/config tooling. ## Documentation Map - Main docs index: [`docs/README.md`](./docs/README.md) - Genesis: [`docs/genesis.md`](./docs/genesis.md) - Consensus (Sumeragi): [`docs/source/sumeragi.md`](./docs/source/sumeragi.md) - Transaction pipeline: [`docs/source/pipeline.md`](./docs/source/pipeline.md) - P2P internals: [`docs/source/p2p.md`](./docs/source/p2p.md) - IVM syscalls: [`docs/source/ivm_syscalls.md`](./docs/source/ivm_syscalls.md) - Kotodama grammar: [`docs/source/kotodama_grammar.md`](./docs/source/kotodama_grammar.md) - Norito wire format: [`norito.md`](./norito.md) - Current work tracking: [`status.md`](./status.md), [`roadmap.md`](./roadmap.md) ## Translations Japanese overview: [`README.ja.md`](./README.ja.md) Other overviews: [`README.he.md`](./README.he.md), [`README.es.md`](./README.es.md), [`README.pt.md`](./README.pt.md), [`README.fr.md`](./README.fr.md), [`README.ru.md`](./README.ru.md), [`README.ar.md`](./README.ar.md), [`README.ur.md`](./README.ur.md) Translation workflow: [`docs/i18n/README.md`](./docs/i18n/README.md) ## Contributing and Help - Contribution guide: [`CONTRIBUTING.md`](./CONTRIBUTING.md) - Community/support channels: [`CONTRIBUTING.md#contact`](./CONTRIBUTING.md#contact) ## License Iroha is licensed under Apache-2.0. See [`LICENSE`](./LICENSE). Documentation is licensed under CC-BY-4.0: http://creativecommons.org/licenses/by/4.0/