feat(sdk)!: optional BIP-39 passphrase through the mnemonic resolver and wallet creation

[PastaPastaPasta]

Supersedes #4615, recreated from a dashpay/platform branch so the full CI (Rust, wallet, Kotlin, Swift, e2e) runs; fork PRs skip those jobs. The commits are unchanged (head f64c4e81b3). Review history is on #4615.

Issue being fixed or feature implemented

The iOS Dash Wallet wants to offer an optional BIP-39 passphrase ("25th word") as an advanced, hidden-by-default feature. The SDK could not support it: every seed derivation hardcoded the empty passphrase. key-wallet's Mnemonic wallet variant calls to_seed("") (rust-dashcore #747 removed MnemonicWithPassphrase), and the Swift→Rust MnemonicResolveCallback could only hand back the mnemonic, so every resolver consumer in rs-sdk-ffi / rs-platform-wallet-ffi derived with to_seed("") too. A wallet created from a raw seed via createWallet(seed:) would have had the right keys but no Keychain-backed resolver path, so it could not sign after a relaunch.

This is phase 0 (the SDK half) of the app feature; the app-side work follows in dashwallet-ios.

What was done?

Rust

• rs-sdk-ffi/src/mnemonic_resolver.rs: MnemonicResolveCallback gains out_passphrase_utf8 / out_passphrase_capacity / out_passphrase_len (length 0 = no passphrase). New PASSPHRASE_RESOLVER_BUFFER_CAPACITY. New resolve_seed(handle, wallet_id) -> Zeroizing<[u8; 64]> is now the only consumer of the vtable: result-code mapping, length/UTF-8 checks, any-language parse, to_seed(passphrase), zeroization, in one place. ResolveSeedError carries the failure kind.
• Every previous hand-rolled resolve→to_seed("") block routes through it: MnemonicResolverCoreSigner, dash_sdk_sign_with_mnemonic_resolver_and_path, dash_sdk_derive_and_persist_identity_keys, resolve_seed_from_resolver[_classified] (which feeds identity discovery / preview / loading / provider keys / shielded / address private key), and dash_sdk_derive_identity_key_at_slot_with_resolver.
• platform-wallet: PlatformWalletManager::create_wallet_from_mnemonic takes passphrase: &str and builds a Seed-typed key-wallet from to_seed(passphrase). The network-scoped wallet id is computed from the root xpub for both variants, so existing (empty-passphrase) wallets keep their ids — pinned by a new test. New free fn platform_wallet::seed_from_mnemonic.
• platform-wallet-ffi: new export platform_wallet_manager_create_wallet_from_mnemonic_with_passphrase_and_birth_height (NULL / "" passphrase ≡ existing export). Existing mnemonic create exports are unchanged wrappers. (Seed pre-derivation for the host uses key-wallet-ffi's mnemonic_to_seed, which auto-detects the language since rust-dashcore chore: v0.24-dev backports part 2 #980/fix(rs-drive-abci): Get rs-drive-abci to commit block 1 #981.)
• rs-unified-sdk-jni: trampoline reports passphrase length 0 (TODO(seed-passphrase)), so Android behaviour is unchanged.

Swift SDK

• WalletStorage: per-wallet wallet.passphrase.<walletIdHex> Keychain item (storePassphrase / retrievePassphrase[UTF8Bytes] / passphraseAvailability / hasPassphrase / deletePassphrase), same accessibility class as the mnemonic. An empty passphrase is rejected; absence of the item is the discriminator. mnemonicKeychainStamp folds the passphrase item in so a changed passphrase invalidates the cached seed-binding marker.
• MnemonicResolver: fills the passphrase buffer (masked while idle, same as the mnemonic); an unreadable passphrase item fails closed.
• PlatformWalletManager.createWallet(mnemonic:seedPassphrase:network:…) on the sync and async overloads; deleteWallet deletes the passphrase item before the mnemonic.
• Removed the throwing passphrase: parameter on WalletManager.addWalletAndSerialize and the stale README examples that documented a passphrase API that did not exist.

How Has This Been Tested?

• cargo test --lib for rs-sdk-ffi (330 pass), platform-wallet-ffi (329 pass), rs-unified-sdk-jni (37 pass); targeted platform-wallet lifecycle tests pass. cargo clippy / cargo fmt --check clean on the four touched crates.
• New Rust tests: BIP-39 reference vectors (abandon…about with "" and TREZOR) through resolve_seed; a passphrase resolver signs with the passphrase-derived key and the empty-passphrase key is refused as PUBKEY_MISMATCH; mnemonic-create id == seed-create id, passphrase changes the id, "" keeps today's id.
• Swift: built a macOS xcframework slice from this branch (build_ios.sh --target mac --profile dev), then swift build --build-tests and the full hermetic suite: 429 tests, 0 failures. New SeedPassphraseResolverTests covers toSeed vectors + Japanese phrase, resolver signing with/without a stored passphrase, passphrase deletion, and the empty-passphrase rejection; PlatformWalletCreateWalletTests asserts the passphrase reaches the native create verbatim.
• After the 2026-10 rebase onto v5.0-dev (rust-dashcore e4208c90), the Rust crates were re-checked and their unit tests re-run; the Swift numbers above are from before the rebase, and the macOS xcframework / Swift suite has not been rebuilt since.
• Not yet done: an on-device iOS smoke (create passphrase wallet → relaunch → spend). That happens with the app-side PR.

Breaking Changes

• MnemonicResolveCallback (C ABI) has three new trailing parameters. Every in-tree implementor is updated (Swift trampoline, JNI trampoline, all test callbacks); out-of-tree hosts must add them and set *out_passphrase_len = 0 when they have no passphrase.
• PlatformWalletManager::create_wallet_from_mnemonic (Rust) takes a passphrase: &str argument.
• Swift WalletManager.addWalletAndSerialize no longer has a passphrase: parameter (it only ever threw on a non-empty value).

Checklist:

• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have added or updated relevant unit/integration/functional/e2e tests
• I have added "!" to the title and described breaking changes in the corresponding section if my code contains any
• I have made corresponding changes to the documentation if needed

For repository code-owners and collaborators only

• I have assigned this pull request to a milestone

🤖 Generated with Claude Code

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[thepastaclaw]

🕓 Review not started yet because this PR is a draft.

• Request normal review — click when the PR is ready for review.
• Request priority review — click to move this review to the front of the queue.

Commit 043d12d. Normal review starts when eligible; priority review starts as soon as a slot is available.