Hyperledger Iroha Development Update – Week of May 16–23, 2025

Hello Iroha community!

This week has been productive with several new features, important fixes, and improvements across the codebase. We’ve added greater flexibility to how Iroha can be configured, strengthened our testing tools, squashed some bugs, and refined our continuous integration (CI) processes. Below is a rundown of all the development activity for the week, organized by category for easy reading.

New Features and Enhancements🆕

• Environment-Only Configuration: You can now run an Iroha node using only environment variables, without a configuration file. The team introduced additional environment variable settings covering all required configuration fields, so the --config flag is no longer mandatory. (Iroha will still default to client.toml if present, but it’s no longer required.) This change simplifies deployments and scripting, making Iroha more flexible to run in containerized or cloud environments. As part of this update, an integration test suite for the Iroha CLI was added to ensure these new config options work reliably.

• Test Network Improvements: Significant enhancements were made to the in-house test network framework to improve modularity and control. Each test peer in the network now gets a human-readable mnemonic name (e.g. spooky_tiger) used for its directory and logs, making debugging easier. The test network configuration is now layered, allowing easier customization and overrides of defaults. Developers can also generate network topologies deterministically by providing seeds, ensuring reproducible test scenarios. New utility functions have been introduced: NetworkPeer::start_checked will start a node and immediately check if it fails (catching startup failures early), and a standalone once_block_sync function can pause tests until all peers reach a certain block height (with failure detection). Additionally, a unified Program utility now resolves the correct binary (irohad or the newer iroha binary) in test environments. Collectively, these changes make writing and running integration tests more robust and developer-friendly.

• WASM Fuel Configuration for Tests: A new helper NetworkBuilder::with_wasm_fuel() was added to the testing toolkit. This lets developers configure the WASM execution fuel (instruction limits for smart contracts) in test networks, which helps in simulating and validating smart contract behavior under different resource limits. It’s a small addition but useful for fine-tuning how smart contracts run in a controlled environment.

Bug Fixes and Issue Resolutions🐞

• WASM Event Coverage: The team closed an issue related to WebAssembly smart contracts not properly declaring all possible events they can emit. The WASM executor now declares the full union of possible events, ensuring that event handling logic is aware of every event type a contract might produce. This fix improves correctness and transparency in Iroha’s contract system.

• Deduplicating WASM Blobs: Another fix addressed a problem of duplicate WASM binaries in the system. The resolution ensures that WASM blobs are not redundantly stored or processed (“Dedup wasm blobs”), which reduces unnecessary memory and storage overhead. This optimization makes Iroha’s handling of smart contract modules more efficient.

• Miscellaneous Fixes: Minor tweaks were made to keep the codebase healthy. For example, a flaky integration test issue was identified after a recent change. While not yet resolved, it’s on the team’s radar to fix soon, ensuring our test suite remains stable for all contributors.

Refactoring and Code Quality Improvements

• Test Network Refactor: As mentioned above, the overhaul of the iroha_test_network module was a major refactoring effort. This wasn’t just adding features, but also restructuring the code for clarity and maintainability. By splitting out these improvements (originally part of a larger pending update) into a dedicated change, the codebase becomes cleaner and the test framework more modular. These quality-of-life improvements (like mnemonic naming and layered configs) will make it easier for contributors to write tests and for the project to expand the test network’s capabilities in the future. Overall, this refactor enhances the modularity and reliability of our testing infrastructure, which benefits all development going forward.

• Documentation Warnings Cleanup: A number of warnings that appeared during documentation generation have been fixed. This “chore” involved correcting or updating Rust doc comments so that running cargo doc no longer produces warnings. It’s a minor cleanup, but it keeps our documentation build output clean and professional, which is especially helpful for new contributors generating docs locally.

Continuous Integration & Tooling Updates

• Consistency Check Script Enhanced: The consistency.sh utility script received an update to broaden its coverage and improve reliability. This script is used to verify various parts of the project for internal consistency. Now, it can be run with targets like genesis, schema, cli-help, docker-compose, or all, performing comprehensive checks in each area (for example, ensuring the genesis files match the expected schema, the CLI help text is up-to-date, etc.). These enhancements help catch discrepancies early and maintain consistency between code, configuration, and documentation.

• GitHub Labeler Fix: Our CI pipeline’s automatic labeler (which tags pull requests based on file changes) has been fixed. Previously, some PRs weren’t being labeled correctly due to a misconfiguration. The corrected labeler workflow now maps to the repository’s file structure properly, so contributors should notice that PR labels (like documentation, bug, feature, etc.) are applied more consistently. This helps maintainers triage and review incoming PRs more efficiently.

• Multi-Arch Docker Image (Work in Progress): A new pull request is in progress to build multi-architecture Docker images for Iroha. Once merged, this will allow official Iroha Docker images to support multiple CPU architectures (e.g., ARM64 and x86_64) out-of-the-box. This enhancement is great for developers running Iroha on different platforms (like Raspberry Pis or ARM-based cloud instances) and will broaden Iroha’s accessibility. Stay tuned as this PR (#5435) goes through review.

• CI Cache Adjustment for WASM Builds: An improvement to our CI was proposed to disable Rust caching specifically for the wasm workspace. This change (#5444) targets some build inconsistencies in our WebAssembly compilation process. By not relying on cached artifacts for the WASM module, we ensure that any changes to WASM-related code produce a fresh build, reducing the chance of CI flakes or outdated binaries in tests. This is part of ongoing efforts to make the CI more stable and developer-friendly.

Ongoing Discussions and Upcoming Work

• Trigger Safety Enhancements: A series of new issue threads opened this week are dedicated to improving the safety and robustness of Iroha’s trigger feature (triggers are automated actions in response to blockchain events). These proposals include making sure that data triggers execute with the proper originator’s authority (so that triggers cannot bypass permission checks and will act only within the rights of the entity that created or owns the trigger). Another suggested enhancement introduces quota-based economic deterrents for triggers – in other words, adding limits or costs to trigger execution to prevent abuse (this is labeled Trigger Safety 3). Similarly, defining permissions for event subscriptions is on the table (ensuring that subscribing to certain event streams is access-controlled as part of Trigger Safety 2-A). Alongside these, a plan to add a retry mechanism for failed time-based triggers is being discussed, so that if a scheduled trigger fails (perhaps due to a temporary issue), Iroha can retry it and not miss the event. All of these changes are under discussion to make triggers more secure and reliable. Community feedback is very welcome on these topics as they evolve.

• Core Execution Path Consistency: In parallel with trigger-related work, there’s an ongoing consideration to ensure every transaction execution path goes through the unified executor component. This would streamline how transactions and triggers are executed under the hood, by funneling all execution through a single well-defined mechanism. The goal is to eliminate any inconsistent execution routes, thereby improving determinism and making the system’s behavior easier to reason about. It’s a technical change, but an important one for maintainability and security.

• Build and Workflow Improvements: Other community-reported issues are driving improvements in our development workflow. One issue highlights the need to allow setting the GIT_SHA (git commit hash) without having Git installed. This is especially relevant for environments like packaged builds or Docker containers, where the source might be present without a .git folder; the proposed solution is to use an environment variable (VERGEN_GIT_SHA) to supply the commit hash so that Iroha can still report its version accurately. Another issue was opened to fix the developer-facing Docker Compose setup (pr_docker_compose.yml) which is currently not functioning as expected – resolving this will make it easier for new contributors to spin up Iroha in a local dev cluster. We also saw that our PR pre-build checks have been failing due to outdated lint rules; the team is updating those checks so contributors won’t be blocked by false alarms. Finally, the flaky test mentioned earlier (#5432) is slated for a fix soon to keep our CI green and trustworthy.

That’s all for this week’s update! 🎉 We covered a lot of ground – from new features and test improvements to bug fixes and plans for future enhancements. A big thank you to everyone who contributed with code, reviews, and issue reports. 🙏 As always, we welcome external contributors to jump in: whether it’s reviewing the open PRs, helping with the newly opened issues, or suggesting improvements. Hyperledger Iroha is a collaborative effort, and every bit of help makes a difference.

Stay tuned for next week’s update, and happy coding! 🚀