[#1924] Split governance PCZT API for Keystone vs software wallets

[p0mvn]

Summary

Splits the governance PCZT JNI into two explicit paths so Keystone (and any other hardware-wallet integration that cannot expose the wallet seed) can drive a delegation round, while software wallets keep their UFVK/walletSeed validation invariant.

Why this shape

The previous buildGovernancePczt JNI required walletSeed and validated, inside Rust, that the seed derived the account UFVK before constructing the PCZT. That contract is correct for software wallets but is unsatisfiable on Keystone, which never surfaces the wallet seed. The Android Keystone integration was working around it by passing the hotkey seed as the wallet seed, which then failed with ufvk does not match walletSeed for network_id=1, account_index=0 on a real round, immediately after also tripping bundle_index 1 is not present in note bundle set because the call site was pre-filtering the note set to a single bundle (the Rust side re-chunks internally from the full snapshot using bundle_index).

We considered three alternatives before landing this shape:

1. Loosening the seed/UFVK check to a runtime opt-in. Rejected: the check is a real safety invariant for software wallets; making it conditional inside Rust creates a quiet way to skip it.
2. Keeping a single API and switching on a walletKind flag. Rejected: it forces the FFI to know about wallet flavors, hides which inputs are actually consumed in each branch, and still requires an explicit hotkey-address path for hardware wallets.
3. Two narrowly typed APIs that share the construction core. Chosen: each entry point only takes inputs it can validate, the seed/UFVK invariant stays inside the seed path where it is meaningful, and the bundle/phase logic is shared so the on-disk state machine cannot drift between the two.

This also matches the iOS SDK contract (zcash-swift-wallet-sdk), which already exposes the explicit-FVK path for hardware-wallet flows.

What changed

• buildGovernancePczt now takes pre-derived fvkBytes (Orchard FVK) and hotkeyRawAddress. This is the path Keystone uses; the host derives the FVK from the UFVK and the raw hotkey address from the hotkey seed before calling.
• buildGovernancePcztFromSeed is the new software-wallet entry point. It takes ufvk, walletSeed, hotkeySeed and keeps the original UFVK<>walletSeed validation, then derives the hotkey raw address internally.
• Both paths share build_governance_pczt_for_bundle, which validates the bundle index, enforces the round phase, persists the constructed delegation state, and only advances the phase to DelegationConstructed on success.
• buildAndProveDelegation now takes hotkeyRawAddress directly. Keystone does not need to surface the hotkey seed beyond derivation, and software wallets derive once via the new helper.
• New deriveHotkeyRawAddress JNI exposes raw-address derivation to the app layer so the Keystone path can stay seed-free end-to-end.
• Mirror updates to TypesafeVotingBackend(Impl) and the JNI/SDK androidTest harnesses.

Manual testing

This was manually tested end-to-end on a Keystone hardware wallet: entering a poll no longer raises bundle_index 1 is not present in note bundle set, and constructing the delegation no longer raises ufvk does not match walletSeed. The software-wallet path was exercised through the existing app flow as well.

Author

• Self-review your own code in GitHub web interface
• Add automated tests as appropriate
• Update the manual tests as appropriate
• Check the code coverage report for the automated tests
• Update documentation as appropriate
• Run the demo app and try the changes
• Pull in the latest changes from the main branch and squash your commits before assigning a reviewer

Reviewer

• Check the code with the Code Review Guidelines checklist
• Perform an ad hoc review
• Review the automated tests
• Review the manual tests
• Review the documentation as appropriate
• Run the demo app and try the changes

The base branch was changed.

[nullcopy]

utACK 79589ef