Hyperledger Iroha

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.

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/: core Rust crates (iroha, irohad, iroha_cli, iroha_core, ivm, norito, etc.).
• integration_tests/: cross-component network/integration tests.
• IrohaSwift/: Swift SDK package.
• java/iroha_android/: Android SDK package.
• docs/: user/operator/developer documentation.

Quickstart

Prerequisites

• Rust stable
• Optional: Docker + Docker Compose for local multi-peer runs

Build and Test (Workspace)

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

cargo test -p <crate>
cargo test -p <crate> <test_name> -- --nocapture

SDK Test Commands

cd IrohaSwift
swift test

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:

docker compose -f defaults/docker-compose.yml up

Use the CLI against the default client config:

cargo run --bin iroha -- --config ./defaults/client.toml --help

For daemon-specific native deployment steps, see 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/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/: an installable Codex app/plugin with the built-in Taira MCP preset.
• skills/sora-taira-testnet/: a standalone Codex skill for live Taira testnet workflows.
• 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:

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: client library.
• crates/irohad: peer daemon binaries.
• crates/iroha_cli: reference CLI.
• crates/iroha_core: ledger/core execution engine.
• crates/iroha_config: typed configuration model.
• crates/iroha_data_model: canonical data model.
• crates/iroha_crypto: cryptographic primitives.
• crates/norito: deterministic serialization codec.
• crates/ivm: Iroha Virtual Machine.
• crates/iroha_kagami: key/genesis/config tooling.

Documentation Map

• Main docs index: docs/README.md
• Genesis: docs/genesis.md
• Consensus (Sumeragi): docs/source/sumeragi.md
• Transaction pipeline: docs/source/pipeline.md
• P2P internals: docs/source/p2p.md
• IVM syscalls: docs/source/ivm_syscalls.md
• Kotodama grammar: docs/source/kotodama_grammar.md
• Norito wire format: norito.md
• Current work tracking: status.md, roadmap.md

Translations

Japanese overview: README.ja.md

Other overviews: README.he.md, README.es.md, README.pt.md, README.fr.md, README.ru.md, README.ar.md, README.ur.md

Translation workflow: docs/i18n/README.md

Contributing and Help

• Contribution guide: CONTRIBUTING.md
• Community/support channels: CONTRIBUTING.md#contact

License

Iroha is licensed under Apache-2.0. See LICENSE.

Documentation is licensed under CC-BY-4.0: http://creativecommons.org/licenses/by/4.0/