iroha AGENTS.md

AGENTS Instructions

These guidelines apply to the entire repository, which is organised as a Cargo workspace.

Quickstart

• Build workspace: cargo build --workspace
• Builds can take about 20 minutes; use a 20-minute timeout for build steps.
• Test everything: cargo test or cargo test --workspace (note that this run typically takes several hours; plan accordingly)
• Lint strictly: cargo clippy --workspace --all-targets -- -D warnings
• Format code: cargo fmt --all (edition 2024)
• Test one crate: cargo test -p <crate>
• Run one test: cargo test -p <crate> <test_name> -- --nocapture
• Swift SDK: from the IrohaSwift directory run swift test to execute the Swift package tests.
• Kotlin SDK: from the kotlin directory run ./gradlew :core-jvm:test --console=plain; build Android artifacts with ./gradlew :client-android:assembleRelease :offline-wallet-android:assembleRelease --quiet.
• Android SDK: from java/iroha_android run JAVA_HOME=$(/usr/libexec/java_home -v 21) ANDROID_HOME=~/Library/Android/sdk ANDROID_SDK_ROOT=~/Library/Android/sdk ./gradlew test.
• Scripts dependencies: python3 -m pip install -r scripts/requirements.txt.
• Script tests: pytest pytests/scripts.

Overview

• Hyperledger Iroha is a blockchain platform
• DA/RBC support differs by major version: Iroha 2 can optionally have DA/RBC enabled; Iroha 3 can only have DA/RBC enabled.
• IVM is the Iroha Virtual Machine (IVM), a virtual machine for the Hyperledger Iroha v2 blockchain
• Kotodama is a high level smart contract language for the IVM that uses .ko file extension for raw contract code and it compiles to bytecode which uses .to file extension, when saved as a file or on-chain. Typically, .to bytecode is deployed onchain.
  • Clarification: Kotodama targets the Iroha Virtual Machine (IVM) and produces IVM bytecode (.to). It does not target “risc5”/RISC‑V as a standalone architecture. Where RISC‑V–like encodings appear in the repository, they are implementation details of IVM’s instruction formats and must not change observable behavior across hardware.
• Norito is the data serialization codec for Iroha
• The entire workspace targets the Rust standard library (std). WASM/no-std builds are no longer supported and should not be considered when making changes.
• Universal-account model:
  • AccountId is the canonical account identity and is always domainless.
  • Domain context for routing, aliasing, and ownership lives outside the canonical account identity in alias bindings and domain-owned entities.
  • Account aliases are a separate SNS/account-label layer. Both domain-qualified aliases like [email protected] and dataspace-root aliases like merchant@paynet bind to the same canonical AccountId.
  • In tests and fixtures, seed the universal AccountId first, then add alias leases, alias permissions, and any domain-owned state separately. Use Account::new(...) for account registration and bind aliases separately only when the behavior under test depends on them.