Thank you for taking the time to contribute to Iroha 2!

Please read this guide to learn how you can contribute and which guidelines we expect you to follow. This includes the guidelines about code and documentation as well as our conventions regarding git workflow.

Reading these guidelines will save you time later.

There are a lot of ways you could contribute to our project:

• Report bugs and vulnerabilities
• Suggest improvements and implement them
• Ask questions and engage with the community

New to our project? Make your first contribution!

• Find ZenHub.
• Fork Iroha.
• Fix your issue of choice.
• Ensure you follow our style guides for code and documentation.
• Write tests. Ensure they all pass (cargo test --workspace). If you touch the SM cryptography stack, also run cargo test -p iroha_crypto --features "sm sm_proptest" to execute the optional fuzz/property harness.
  • Note: Tests that exercise the IVM executor will automatically synthesize a minimal, deterministic executor bytecode if defaults/executor.to is not present. No pre-step is required to run tests. To generate the canonical bytecode for parity, you can run:
    • cargo run --manifest-path scripts/generate_executor_to/Cargo.toml
    • cargo run --manifest-path scripts/regenerate_codec_samples/Cargo.toml
• If you change derive/proc-macro crates, run the trybuild UI suites via make check-proc-macro-ui (or PROC_MACRO_UI_CRATES="crate1 crate2" make check-proc-macro-ui) and refresh .stderr fixtures when diagnostics change to keep messages stable.
• Run make dev-workflow (wrapper around scripts/dev_workflow.sh) to execute fmt/clippy/build/test with --locked plus swift test; expect cargo test --workspace to take hours and use --skip-tests only for quick local loops. See docs/source/dev_workflow.md for the full runbook.
• Enforce guardrails with make check-agents-guardrails to block Cargo.lock edits and new workspace crates, make check-dependency-discipline to fail on new dependencies unless explicitly allowed, and make check-missing-docs to prevent new #[allow(missing_docs)] shims, missing crate-level docs on touched crates, or new public items without doc comments (the guard refreshes docs/source/agents/missing_docs_inventory.{json,md} via scripts/inventory_missing_docs.py). Add make check-tests-guard so changed functions fail unless unit tests reference them (inline #[cfg(test)]/#[test] blocks or crate tests/; existing coverage counts) and make check-docs-tests-metrics so roadmap changes are paired with docs, tests, and metrics/dashboards. Keep TODO enforcement via make check-todo-guard so TODO markers are not dropped without accompanying docs/tests. make check-env-config-surface regenerates the env-toggle inventory and now fails when new production env shims appear relative to AGENTS_BASE_REF; set ENV_CONFIG_GUARD_ALLOW=1 only after documenting intentional additions in the migration tracker. make check-serde-guard refreshes the serde inventory and fails on stale snapshots or new production serde/serde_json hits; set SERDE_GUARD_ALLOW=1 only with an approved migration plan. Keep large deferrals visible via TODO breadcrumbs and follow-up tickets instead of deferring silently. Run make check-std-only to catch no_std/wasm32 cfgs and make check-status-sync to ensure roadmap.md open items remain open-only and that roadmap/status changes land together; set STATUS_SYNC_ALLOW_UNPAIRED=1 only for rare status-only typo fixes after pinning AGENTS_BASE_REF. For a single invocation, use make agents-preflight to run all guardrails together.
• Run local serialization guards before pushing: make guards.
  • This denies direct serde_json in production code, disallows new direct serde deps outside allowlist, and prevents ad‑hoc AoS/NCB helpers outside crates/norito.
• Optionally dry-run Norito feature matrix locally: make norito-matrix (uses a fast subset).
  • For full coverage, run scripts/run_norito_feature_matrix.sh without --fast.
  • To include a downstream smoke per combo (default crate iroha_data_model): make norito-matrix-downstream or scripts/run_norito_feature_matrix.sh --fast --downstream [crate].
• For proc-macro crates, add a trybuild UI harness (tests/ui.rs + tests/ui/pass/tests/ui/fail) and commit .stderr diagnostics for the failing cases. Keep diagnostics stable and non-panicking; refresh fixtures with TRYBUILD=overwrite cargo test -p <crate> -F trybuild-tests and guard them with cfg(all(feature = "trybuild-tests", not(coverage))).
• Perform pre-commit routine like formatting & artifacts regeneration (see pre-commit.sample)
• With the upstream set to track Hyperledger Iroha repository, git pull -r upstream main, git commit -s, git push <your-fork>, and create a pull request to the main branch. Ensure it follows the pull request guidelines.

• Run make dev-workflow (wrapper around scripts/dev_workflow.sh, documented in docs/source/dev_workflow.md). It wraps cargo fmt --all, cargo clippy --workspace --all-targets --locked -- -D warnings, cargo build/test --workspace --locked (tests can take several hours), and swift test.
• Use scripts/dev_workflow.sh --skip-tests or --skip-swift for faster iterations; rerun the full sequence before opening a pull request.
• Guardrails: avoid touching Cargo.lock, adding new workspace members, introducing new dependencies, adding new #[allow(missing_docs)] shims, omitting crate-level docs, skipping tests when changing functions, dropping TODO markers without docs/tests, or reintroducing no_std/wasm32 cfgs without approval. Run make check-agents-guardrails (or AGENTS_BASE_REF=origin/main bash ci/check_agents_guardrails.sh) plus make check-dependency-discipline, make check-missing-docs (refreshes docs/source/agents/missing_docs_inventory.{json,md}), make check-tests-guard (fails when production functions change without unit-test evidence—either tests change in the diff or existing tests must reference the function), make check-docs-tests-metrics (fails when roadmap changes lack docs/tests/metrics updates), make check-todo-guard, make check-env-config-surface (fails on stale inventories or new production env toggles; override with ENV_CONFIG_GUARD_ALLOW=1 only after updating docs), and make check-serde-guard (fails on stale serde inventories or new production serde hits; override with SERDE_GUARD_ALLOW=1 only with an approved migration plan) locally for early signal, make check-std-only for the std-only guard, and keep roadmap.md/status.md in sync with make check-status-sync (set STATUS_SYNC_ALLOW_UNPAIRED=1 only for rare status-only typo fixes after pinning AGENTS_BASE_REF). Use make agents-preflight if you want a single command to run all guards before opening a PR.

A bug is an error, design flaw, failure or fault in Iroha that causes it to produce an incorrect, unexpected, or unintended result or behaviour.

We track Iroha bugs via GitHub Issues labeled with the Bug tag.

When you create a new issue, there is a template for you to fill in. Here's the checklist of what you should do when you are reporting bugs:

• Add the Bug tag
• Explain the issue
• Provide a minimum working example
• Attach a screenshot

# Minting negative Assets with value spec `Numeric`.

I was able to mint negative values, which shouldn't be possible in Iroha. This is bad because <X>.

# Given

I managed to mint negative values by running
<paste the code here>

# I expected

not to be able to mint negative values

# But, I got

<code showing negative value>

<paste a screenshot>

Note: Issues such as outdated documentation, insufficient documentation, or feature requests should use the Documentation or Enhancement labels. They are not bugs.

While we are proactive in preventing security problems, it is possible that you might come across a security vulnerability before we do.

• Before the First Major Release (2.0) all vulnerabilities are considered bugs, so feel free to submit them as bugs following the instructions above.
• After the First Major Release, use our bug bounty program to submit vulnerabilities and get your reward.

❗ To minimize the damage caused by an unpatched security vulnerability, you should disclose the vulnerability directly to Hyperledger as soon as possible and avoid disclosing the same vulnerability publicly for a reasonable period of time.

If you have any questions regarding our handling of security vulnerabilities, please feel free to contact any of the currently active maintainers in Rocket.Chat private messages.

Create an issue on GitHub with the appropriate tags (Optimization, Enhancement) and describe the improvement you are suggesting. You may leave this idea for us or someone else to develop, or you may implement it yourself.

If you intend to implement the suggestion yourself, do the following:

1. Assign the issue you created to yourself before you start working on it.

2. Work on the feature you suggested and follow our guidelines for code and documentation.

3. When you are ready to open a pull request, make sure you follow the pull request guidelines and mark it as implementing the previously created issue:

   feat: Description of the feature
   
   Explanation of the feature
   
   Closes #1234
   

4. If your change requires an API change, use the api-changes tag.

   Note: features that require API changes may take longer to implement and approve as they require Iroha library makers to update their code.

A question is any discussion that is neither a bug nor a feature or optimization request.

1. Find a beginner-friendly issue among issues with the good-first-issue label.
2. Make sure that no one else is working on the issues you have chosen by checking that it is not assigned to anybody.
3. Assign the issue to yourself so that others can see that someone is working on it.
4. Read our Rust Style Guide before you start writing code.
5. When you are ready to commit your changes, read the pull request guidelines.

Please fork the repository and create a feature branch for your contributions. When working with PRs from forks, check this manual.

• Follow the Rust Style Guide and the Documentation Style Guide.
• Ensure that the code you've written is covered by tests. If you fixed a bug, please turn the minimum working example that reproduces the bug into a test.
• When touching derive/proc-macro crates, run make check-proc-macro-ui (or filter with PROC_MACRO_UI_CRATES="crate1 crate2") so trybuild UI fixtures stay in sync and diagnostics remain stable.
• Document new public APIs (crate-level //! and /// on new items), and run make check-missing-docs to verify the guardrail. Call out the docs/tests you added in your pull request description.

• Follow the Git Style Guide.

• Squash your commits either before or during the merge.

• If during the preparation of your pull request your branch got out of date, rebase it locally with git pull --rebase upstream main. Alternatively, you may use the drop-down menu for the Update branch button and choose the Update with rebase option.

  In the interest of making this process easier for everyone, try not to have more than a handful of commits for a pull request, and avoid re-using feature branches.

• Use an appropriate pull request description by following the guidance in the Pull Request Etiquette section. Avoid deviating from these guidelines if possible.
• Add an appropriately formatted pull request title.
• If you feel like your code isn't ready to merge, but you want the maintainers to look through it, create a draft pull request.

• A pull request must pass all automated checks before being merged. At a minimum, the code must be formatted, passing all tests, as well as having no outstanding clippy lints.
• A pull request cannot be merged without two approving reviews from the active maintainers.
• Each pull request will automatically notify the code owners. An up to date list of current maintainers can be found in MAINTAINERS.md.

• Do not resolve a conversation on your own. Let the reviewer make a decision.
• Acknowledge review comments and engage with the reviewer (agree, disagree, clarify, explain, etc.). Do not ignore comments.
• For simple code change suggestions, if you apply them directly, you can resolve the conversation.
• Avoid overwriting your previous commits when pushing new changes. It obfuscates what changed since the last review and forces the reviewer to start from scratch. Commits are squashed before merging automatically.

We parse the titles of all the merged pull requests to generate changelogs. We also check that the title follows the convention via the check-PR-title check.

To pass the check-PR-title check, the pull request title must adhere to the following guidelines:

• Fork the repository and create a feature branch for your contributions.
• Configure the remote to sync your fork with the Hyperledger Iroha repository.
• Use the Git Rebase Workflow. Avoid using git pull. Use git pull --rebase instead.
• Use the provided git hooks to ease the development process.

Follow these commit guidelines:

• Sign-off every commit. If you don't, DCO will not let you merge.

  Use git commit -s to automatically add Signed-off-by: $NAME <$EMAIL> as the final line of your commit message. Your name and email should be the same as specified in your GitHub account.

  We also encourage you to sign your commits with GPG key using git commit -sS (learn more).

  You may use the commit-msg hook to automatically sign-off your commits.

• Commit messages must follow conventional commits and the same naming schema as for pull request titles. This means:

  • Use present tense ("Add feature", not "Added feature")
  • Use imperative mood ("Deploy to docker..." not "Deploys to docker...")

• Write a meaningful commit message.

• Try keeping a commit message short.

• If you need to have a longer commit message:

  • Limit the first line of your commit message to 50 characters or less.
  • The first line of your commit message should contain the summary of the work you've done. If you need more than one line, leave a blank line between each paragraph and describe your changes in the middle. The last line must be the sign-off.

• If you modify the Schema (check by generating the schema with kagami schema and diff), you should make all changes to the schema in a separate commit with the message [schema].

• Try to stick to one commit per meaningful change.

  • If you fixed several issues in one PR, give them separate commits.
  • As mentioned previously, changes to the schema and the API should be done in appropriate commits separate from the rest of your work.
  • Add tests for functionality in the same commit as that functionality.

• To run the source-code based tests, execute cargo test in the Iroha root. Note that this is a long process.
• To run benchmarks, execute cargo bench from the Iroha root. To help debug benchmark outputs, set the debug_assertions environment variable like so: RUSTFLAGS="--cfg debug_assertions" cargo bench.
• If you are working on a particular component, be mindful that when you run cargo test in a workspace, it will only run the tests for that workspace, which usually doesn't include any integration tests.
• If you want to test your changes on a minimal network, the provided docker-compose.yml creates a network of 4 Iroha peers in docker containers that can be used to test consensus and asset propagation-related logic. We recommend interacting with that network using either iroha-python, or the included Iroha client CLI.
• Do not remove failing tests. Even tests that are ignored will be run in our pipeline eventually.
• If possible, please benchmark your code both before and after making your changes, as a significant performance regression can break existing users' installations.

Run make guards to validate repository policies locally:

• Deny-list direct serde_json in production sources (prefer norito::json).
• Forbid direct serde/serde_json dependencies/imports outside the allowlist.
• Prevent reintroduction of ad‑hoc AoS/NCB helpers outside crates/norito.

RUSTFLAGS="--cfg tokio_unstable" cargo build --features tokio-console

# 1. Compile Iroha
RUSTFLAGS="--cfg tokio_unstable" cargo build --features tokio-console
# 2. Run Iroha with TRACE log level
LOG_LEVEL=TRACE ./scripts/test_env.sh setup
# 3. Access Iroha. Peers will be available on ports 5555, 5556, ...
tokio-console http://127.0.0.1:5555

RUSTFLAGS="-C force-frame-pointers=on" cargo +nightly -Z build-std build --target your-desired-target --profile profiling --features profiling

docker build -f Dockerfile.glibc --build-arg="PROFILE=profiling" --build-arg='RUSTFLAGS=-C force-frame-pointers=on' --build-arg='FEATURES=profiling' --build-arg='CARGOFLAGS=-Z build-std' -t iroha:profiling .

# to capture profile
sudo perf record -g -p <PID>
# to analyze profile
sudo perf report

# compile executor without optimizations
cargo run --bin kagami -- ivm build ./path/to/executor --out-file executor.to

# profile Iroha for 30 seconds and download the profile data
curl host:port/debug/pprof/profile?seconds=30 -o profile.pb
# analyze profile in browser (required installed go)
go tool pprof -web profile.pb

Please follow these guidelines when you make code contributions to our project:

📖 Read git guidelines

Our community members are active at: