Add BIP-39 mnemonic phrase support for deterministic wallet recovery workflows

[iron-prog]

Problem

The SDK currently exposes key primitives such as PrivateKey and PublicKey, but does not provide a mnemonic-based workflow for seed phrase generation, validation, recovery, or deterministic key derivation.
Mnemonic phrases are the standard backup and recovery mechanism across modern wallet ecosystems. Without native SDK support, developers must integrate third-party libraries and custom logic themselves, which can lead to inconsistent implementations and fragmented developer experience.
This gap also makes deterministic local development and integration testing workflows more difficult.

Solution

Introduce a MnemonicPhrase crypto utility that supports:

• BIP-39 mnemonic generation
• Phrase validation and normalization
• Seed derivation with optional passphrase support
• Deterministic Ed25519 private key derivation from generated seeds
• The utility should also be exported through:
• the crypto package exports
• the top-level SDK exports

Benefits

• Simplifies developer onboarding
• Enables deterministic test environments
• Provides SDK-native wallet recovery workflows
• Reduces reliance on external mnemonic handling logic
• Improves consistency across applications using the SDK

Initial Scope

• English BIP-39 support
• Deterministic seed derivation
• Deterministic Ed25519 key derivation
• Unit tests for:
  • mnemonic generation
  • normalization/validation
  • invalid checksum rejection
  • deterministic derivation behavior

Alternatives

No response

[github-actions]

Thanks for your submission.

This issue is awaiting approval from @hiero-ledger/hiero-sdk-python-triage and @hiero-ledger/hiero-sdk-python-committers and @hiero-ledger/hiero-sdk-python-maintainers.

[exploreriii]

Hello @iron-prog
Thank you so much for this idea.

I notice the other SDKs provide mnemonic support, for example https://github.com/hiero-ledger/hiero-sdk-js/blob/main/src/Mnemonic.js.

I would like to approve the issue subject to the developer researching and verifying the correct methodology across the sdks, and since it will involve keys it is a sensitive issue, thus am marking this as an advanced issue. An implementation that's deterministic but non-standard would produce keys that no other SDK or wallet can recover. Worse than no feature. I expect this issue will take significant time to create and also review, with much testing that needs to be completed.

[github-actions]

Approved by @hiero-ledger/hiero-sdk-python-triage and @hiero-ledger/hiero-sdk-python-committers and @hiero-ledger/hiero-sdk-python-maintainers.

[github-actions]

@coderabbitai plan

[coderabbitai]

Coding Plan

Summary

• Add a single lightweight mnemonic dependency and implement a self-contained Mnemonic class in src/hiero_sdk_python/crypto/mnemonic.py covering generation, normalization/validation, BIP-39 seed derivation, and SLIP-10 standard-path Ed25519 key derivation that delegates to the existing PrivateKey.from_bytes_ed25519.
• Expose Mnemonic through both crypto/__init__.py and the top-level __init__.py/__all__ following existing export conventions.
• Provide a runnable example and a standalone user doc mirroring existing templates, plus flat tests/unit/mnemonic_test.py covering generation, validation, invalid-checksum rejection, and deterministic derivation.

Design Choices

Design Choice 1: How should BIP-39 wordlist/mnemonic operations be provided?

Options Considered:

1. Add the lightweight, well-established mnemonic PyPI package (provides English wordlist, generation, validation, and PBKDF2 seed derivation).
2. Add the broader bip-utils package (covers BIP-39/BIP-32/SLIP-10 end-to-end).
3. Implement BIP-39 fully in-house by bundling the English wordlist and using stdlib hashlib/hmac.

Chosen Option: 1

Rationale: The SDK has no BIP-39 dependency today; generation/validation requires a wordlist and checksum logic. The mnemonic package is small, widely trusted, and covers exactly the initial English-only scope while keeping the dependency surface minimal; SLIP-10 Ed25519 derivation (not covered by it) is small enough to implement in-house against the existing cryptography/stdlib primitives.

Design Choice 2: How should the Ed25519 private key be derived from the seed?

Options Considered:

1. Hedera-standard SLIP-10 Ed25519 derivation over HMAC-SHA512 using the standard Hedera path (m/44'/3030'/0'/0'/0'), matching other Hedera SDKs' toStandardEd25519PrivateKey.
2. Simple derivation that takes the first 32 bytes of the BIP-39 seed and feeds them to PrivateKey.from_bytes_ed25519.

Chosen Option: 1

Rationale: The ticket requires "deterministic Ed25519 private key derivation from generated seeds" without pinning the exact algorithm. SLIP-10 with the standard Hedera derivation path produces keys interoperable with the broader Hedera ecosystem and is the correct "standard" behavior other SDKs expose, avoiding a divergent, non-portable scheme.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Core Mnemonic Utility & Derivation

This phase delivers the actual feature: a self-contained Mnemonic crypto utility that generates, normalizes, validates, and converts mnemonic phrases into seeds and deterministic Ed25519 private keys, plus the required dependency.

Task 1: Add the BIP-39 dependency

Make the BIP-39 wordlist/generation primitives available to the SDK.

• Update pyproject.toml to add the mnemonic package to the dependencies array, using a bounded version range consistent with existing entries (e.g. >=x,<y).
• Keep it in core dependencies (not optional extras) since mnemonic support is a first-class SDK feature per the ticket.

Task 2: Implement the `Mnemonic` crypto module

Create the core utility encapsulating all mnemonic workflows.

• Add a new module src/hiero_sdk_python/crypto/mnemonic.py defining a Mnemonic class that wraps a normalized phrase string.
• Provide generation entry points for 12- and 24-word English phrases (e.g. generate_12() / generate_24(), or a single generate(word_count)), delegating to the mnemonic library for wordlist-backed entropy and checksum generation.
• Provide construction/validation from an existing phrase (e.g. from_string(...)), applying normalization (Unicode NFKD normalization, whitespace collapsing, lowercasing) before validating word membership and the BIP-39 checksum; raise a clear ValueError on invalid checksum/words, following existing crypto error-message conventions.
• Provide to_seed(passphrase="") implementing BIP-39 PBKDF2-HMAC-SHA512 (salt "mnemonic" + passphrase, 2048 iterations, 64-byte output) via stdlib hashlib.pbkdf2_hmac or the library helper.
• Provide to_ed25519_private_key(passphrase="") that performs SLIP-10 Ed25519 derivation over the seed using HMAC-SHA512 (curve seed key "ed25519 seed") along the standard Hedera path m/44'/3030'/0'/0'/0', then delegates the resulting 32-byte key material to the existing PrivateKey.from_bytes_ed25519(...) in crypto/private_key.py.
• Add supporting representation helpers (__str__, words accessor) and keep the module dependency-light, reusing cryptography/stdlib primitives already present.

🤖 Prompt for AI agents

Implement the core BIP-39 `Mnemonic` crypto utility and its dependency. Goal:
deliver a self-contained module supporting mnemonic generation,
normalization/validation, seed derivation, and deterministic Ed25519 private key
derivation.

- Update `pyproject.toml`: add the `mnemonic` PyPI package to the core
`dependencies` array (not optional extras) using a bounded version range
consistent with existing dependency entries (e.g. `>=x,<y`).
- Create `src/hiero_sdk_python/crypto/mnemonic.py` defining a `Mnemonic` class
wrapping a normalized phrase string.
- Add generation entry points for 12- and 24-word English phrases (e.g.
`generate_12()` / `generate_24()`, or a single `generate(word_count)`)
delegating to the `mnemonic` library for wordlist-backed entropy and checksum
generation.
- Add a construction/validation entry point from an existing phrase (e.g.
`from_string(...)`): normalize input via Unicode NFKD normalization, whitespace
collapsing, and lowercasing; validate word membership and BIP-39 checksum; raise
`ValueError` with a clear message on invalid checksum/words following existing
crypto error-message conventions.
- Add `to_seed(passphrase="")` implementing BIP-39 PBKDF2-HMAC-SHA512 (salt =
`"mnemonic" + passphrase`, 2048 iterations, 64-byte output) using stdlib
`hashlib.pbkdf2_hmac` or the library helper.
- Add `to_ed25519_private_key(passphrase="")` implementing SLIP-10 Ed25519
derivation over the seed using HMAC-SHA512 (curve seed key `"ed25519 seed"`)
along the standard Hedera derivation path `m/44'/3030'/0'/0'/0'`, then pass the
resulting 32-byte key material to the existing
`PrivateKey.from_bytes_ed25519(...)` in `crypto/private_key.py`.
  - Add helper representations such as `__str__` and a `words` accessor.
- Keep the module dependency-light, reusing `cryptography`/stdlib primitives
already present in the codebase.

Phase 2: Exports, Example & Documentation

This phase makes the new utility discoverable and usable, wiring it into the SDK's public surface and providing usage guidance following established patterns.

Task 1: Wire package and top-level exports

Expose Mnemonic through both required export layers.

• Add a re-export of Mnemonic from src/hiero_sdk_python/crypto/__init__.py (currently empty) so the crypto package exposes it directly, satisfying the "crypto package exports" requirement.
• Update src/hiero_sdk_python/__init__.py: add from .crypto.mnemonic import Mnemonic under the # Crypto import group (alphabetical placement among crypto imports) and add "Mnemonic" to the # Crypto block of __all__, following existing formatting conventions.

Task 2: Add a runnable example

Demonstrate the end-to-end mnemonic workflow in the established example style.

• Create examples/crypto/mnemonic.py (name chosen to token-match the new source module for scripts/examples/match_examples_src.py).
• Follow the examples/crypto/private_key_ed25519.py template: module docstring with run instructions and any exposure warnings, SDK imports, discrete example_*() functions (generate phrase, validate/normalize a phrase, derive seed with/without passphrase, derive Ed25519 private key), a main_mnemonic() aggregator, and the __main__ guard.

Task 3: Add user documentation

Provide a standalone doc page for the new feature.

• Add docs/sdk_users/mnemonic.md following the transaction_bytes.md / error_handling.md template (Overview → New Methods/Attributes → fenced Python examples), covering generation, validation/normalization, seed derivation with passphrase, and deterministic Ed25519 derivation, including the standard derivation path note.

🤖 Prompt for AI agents

Wire the new `Mnemonic` utility into the SDK's public API and provide usage
guidance. Goal: make the feature discoverable and usable, following established
SDK export, example, and documentation conventions.

- Export wiring:
- Add a re-export of `Mnemonic` from `src/hiero_sdk_python/crypto/__init__.py`
(currently empty) so the crypto package exposes it directly.
- Update `src/hiero_sdk_python/__init__.py`: add `from .crypto.mnemonic import
Mnemonic` under the `# Crypto` import group (placed alphabetically among the
existing crypto imports), and add `"Mnemonic"` to the `# Crypto` block of
`__all__`, matching existing formatting conventions.
- Example:
- Create `examples/crypto/mnemonic.py` (named to token-match the new source
module `mnemonic.py` for `scripts/examples/match_examples_src.py`).
- Follow the `examples/crypto/private_key_ed25519.py` template: include a module
docstring with run instructions and any exposure warnings, SDK imports, discrete
`example_*()` functions covering: generating a phrase, validating/normalizing a
phrase, deriving a seed with and without a passphrase, and deriving an Ed25519
private key; add a `main_mnemonic()` aggregator function and an `__main__`
guard.
- Documentation:
- Add `docs/sdk_users/mnemonic.md` following the `transaction_bytes.md` /
`error_handling.md` template structure (Overview → New Methods/Attributes →
fenced Python examples).
- Cover generation, validation/normalization, seed derivation with passphrase,
and deterministic Ed25519 derivation, including a note on the standard
derivation path used.

Phase 3: Unit Tests

This phase validates correctness and determinism, matching the codebase's existing test conventions.

Add mnemonic unit tests

Cover all behaviors called out in the ticket's initial scope.

• Create tests/unit/mnemonic_test.py with pytestmark = pytest.mark.unit and from __future__ import annotations, using fixtures and @pytest.mark.parametrize per existing crypto test style.
• Test generation: correct word counts (12/24), all words from the English wordlist, and that generated phrases pass validation.
• Test normalization/validation: whitespace/casing/Unicode normalization produces canonical phrases; valid phrases pass.
• Test invalid checksum and invalid-word rejection via pytest.raises(ValueError, match=...).
• Test deterministic behavior: a fixed known mnemonic (+optional passphrase) always yields the same seed and the same Ed25519 private key across calls; assert against precomputed reference vectors where feasible, and verify passphrase changes the derived seed/key.

🤖 Prompt for AI agents

Add unit tests validating the new `Mnemonic` utility's correctness and
determinism, matching existing test conventions. Goal: cover all behaviors from
the ticket's initial scope.

- Create `tests/unit/mnemonic_test.py` with `pytestmark = pytest.mark.unit` and
`from __future__ import annotations` at the top, using fixtures and
`@pytest.mark.parametrize` per existing crypto test style.
- Test generation behavior: correct word counts (12/24), all generated words
come from the English wordlist, and generated phrases pass validation.
- Test normalization/validation behavior: whitespace/casing/Unicode
normalization produces canonical phrases; valid phrases pass validation.
- Test rejection behavior: invalid checksum and invalid-word phrases are
rejected via `pytest.raises(ValueError, match=...)`.
- Test deterministic behavior: a fixed known mnemonic (with and without a
passphrase) always yields the same seed and the same Ed25519 private key across
repeated calls; assert against precomputed reference vectors where feasible, and
verify that changing the passphrase changes the derived seed/key.

Research

Codebase Summary

src/hiero_sdk_python/ is a flat domain-oriented package. Crypto lives in src/hiero_sdk_python/crypto/ (private_key.py, public_key.py, key.py, key_list.py, evm_address.py); the crypto/__init__.py is empty and concrete classes are re-exported from the top-level src/hiero_sdk_python/__init__.py using grouped # Comment headers plus an __all__ list. PrivateKey (built on the cryptography library) already provides from_bytes_ed25519(seed_32) — the natural integration point for a mnemonic-derived key. No BIP-39/BIP-32/SLIP-10/mnemonic code, dependency, docs, or tests currently exist anywhere. Unit tests are flat files under tests/unit/ named <subject>_test.py, using pytestmark = pytest.mark.unit, from __future__ import annotations, fixtures, and @pytest.mark.parametrize. Examples live under examples/crypto/ following a docstring + example_*() + main_*() + __main__ guard template. TCK handlers exist for generateKey but currently have no mnemonic path.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement the core BIP-39 `Mnemonic` crypto utility and its dependency. Goal:
deliver a self-contained module supporting mnemonic generation,
normalization/validation, seed derivation, and deterministic Ed25519 private key
derivation.

- Update `pyproject.toml`: add the `mnemonic` PyPI package to the core
`dependencies` array (not optional extras) using a bounded version range
consistent with existing dependency entries (e.g. `>=x,<y`).
- Create `src/hiero_sdk_python/crypto/mnemonic.py` defining a `Mnemonic` class
wrapping a normalized phrase string.
- Add generation entry points for 12- and 24-word English phrases (e.g.
`generate_12()` / `generate_24()`, or a single `generate(word_count)`)
delegating to the `mnemonic` library for wordlist-backed entropy and checksum
generation.
- Add a construction/validation entry point from an existing phrase (e.g.
`from_string(...)`): normalize input via Unicode NFKD normalization, whitespace
collapsing, and lowercasing; validate word membership and BIP-39 checksum; raise
`ValueError` with a clear message on invalid checksum/words following existing
crypto error-message conventions.
- Add `to_seed(passphrase="")` implementing BIP-39 PBKDF2-HMAC-SHA512 (salt =
`"mnemonic" + passphrase`, 2048 iterations, 64-byte output) using stdlib
`hashlib.pbkdf2_hmac` or the library helper.
- Add `to_ed25519_private_key(passphrase="")` implementing SLIP-10 Ed25519
derivation over the seed using HMAC-SHA512 (curve seed key `"ed25519 seed"`)
along the standard Hedera derivation path `m/44'/3030'/0'/0'/0'`, then pass the
resulting 32-byte key material to the existing
`PrivateKey.from_bytes_ed25519(...)` in `crypto/private_key.py`.
  - Add helper representations such as `__str__` and a `words` accessor.
- Keep the module dependency-light, reusing `cryptography`/stdlib primitives
already present in the codebase.
===============================================================================

Task: 2

Wire the new `Mnemonic` utility into the SDK's public API and provide usage
guidance. Goal: make the feature discoverable and usable, following established
SDK export, example, and documentation conventions.

- Export wiring:
- Add a re-export of `Mnemonic` from `src/hiero_sdk_python/crypto/__init__.py`
(currently empty) so the crypto package exposes it directly.
- Update `src/hiero_sdk_python/__init__.py`: add `from .crypto.mnemonic import
Mnemonic` under the `# Crypto` import group (placed alphabetically among the
existing crypto imports), and add `"Mnemonic"` to the `# Crypto` block of
`__all__`, matching existing formatting conventions.
- Example:
- Create `examples/crypto/mnemonic.py` (named to token-match the new source
module `mnemonic.py` for `scripts/examples/match_examples_src.py`).
- Follow the `examples/crypto/private_key_ed25519.py` template: include a module
docstring with run instructions and any exposure warnings, SDK imports, discrete
`example_*()` functions covering: generating a phrase, validating/normalizing a
phrase, deriving a seed with and without a passphrase, and deriving an Ed25519
private key; add a `main_mnemonic()` aggregator function and an `__main__`
guard.
- Documentation:
- Add `docs/sdk_users/mnemonic.md` following the `transaction_bytes.md` /
`error_handling.md` template structure (Overview → New Methods/Attributes →
fenced Python examples).
- Cover generation, validation/normalization, seed derivation with passphrase,
and deterministic Ed25519 derivation, including a note on the standard
derivation path used.
===============================================================================

Task: 3

Add unit tests validating the new `Mnemonic` utility's correctness and
determinism, matching existing test conventions. Goal: cover all behaviors from
the ticket's initial scope.

- Create `tests/unit/mnemonic_test.py` with `pytestmark = pytest.mark.unit` and
`from __future__ import annotations` at the top, using fixtures and
`@pytest.mark.parametrize` per existing crypto test style.
- Test generation behavior: correct word counts (12/24), all generated words
come from the English wordlist, and generated phrases pass validation.
- Test normalization/validation behavior: whitespace/casing/Unicode
normalization produces canonical phrases; valid phrases pass validation.
- Test rejection behavior: invalid checksum and invalid-word phrases are
rejected via `pytest.raises(ValueError, match=...)`.
- Test deterministic behavior: a fixed known mnemonic (with and without a
passphrase) always yields the same seed and the same Ed25519 private key across
repeated calls; assert against precomputed reference vectors where feasible, and
verify that changing the passphrase changes the derived seed/key.

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!