Implement `z_importkey` and `z_exportkey` for Sapling by oxarbitrage · Pull Request #400 · zcash/zallet

oxarbitrage · 2026-03-20T12:02:31Z

Adds two new RPC methods:

z_importkey: Imports a Sapling extended spending key into the wallet. The key is encrypted with age and stored in the keystore. A UFVK is derived and imported into the wallet database so the sync engine can track transactions. The rescan parameter controls whether historical blocks are scanned ("yes", "no", or "whenkeyisnew"), and start_height sets the birthday for the imported account. Real treestates are fetched from the chain indexer for non-zero start heights.
z_exportkey: Exports the spending key for a Sapling payment address. Requires the wallet to be unlocked. Looks up the key by iterating standalone sapling DFVKs and using decrypt_diversifier to match the address.

Also adds fetch_account_birthday to json_rpc::utils as a shared helper for building an AccountBirthday from a chain treestate.

Includes unit tests for parameter validation, key encoding/decoding roundtrips, and address parsing.

Close #69
Close #79
Closes COR-254 and COR-259

nuttycom · 2026-03-23T16:56:50Z

I'm not sure that it makes sense to implement the legacy versions of these methods; their utility is extremely limited and I would prefer that we avoid introducing API surface that we then have to maintain. Both of these methods got zero points in our survey of what people are using: https://docs.google.com/spreadsheets/d/1UJxH1cowexGqadU32Uei5Qak6jGhXjb18-T_QBPmDAA/edit?gid=0#gid=0

nuttycom · 2026-03-23T16:59:26Z

I guess that I can see implementing z_importkey for Sapling paper wallet users. But key export in particular I'm skeptical of - it seems like an avenue to lose funds if you trust z_exportkey for backup without realizing that there might be Orchard funds associated with the same root of spending authority.

oxarbitrage · 2026-03-24T11:34:22Z

Thanks for the feedback.

I'm not sure that it makes sense to implement the legacy versions of these methods; their utility is extremely limited and I would prefer that we avoid introducing API surface that we then have to maintain. Both of these methods got zero points in our survey of what people are using: https://docs.google.com/spreadsheets/d/1UJxH1cowexGqadU32Uei5Qak6jGhXjb18-T_QBPmDAA/edit?gid=0#gid=0

I wasn’t aware of the survey, thanks for sharing it. I’ll consider it for future work. It might also make sense to close or re-evaluate issues in the repository that correspond to methods with zero usage.

That said, I do think import-related APIs may become more valuable as zcashd is deprecated and users look for ways to migrate into the new stack.

I guess that I can see implementing z_importkey for Sapling paper wallet users.

Not only for paper wallets. If you have a legacy Sapling key (with funds) and want to import it into the new stack without relying on zcashd, this provides a viable path. I used this same RPC method in zcashd to achieve that migration.

But key export in particular I'm skeptical of - it seems like an avenue to lose funds if you trust z_exportkey for backup without realizing that there might be Orchard funds associated with the same root of spending authority.

That makes sense. The export functionality was mainly added for completeness. I’m happy to remove it, or alternatively keep it with clearer documentation highlighting the risks.

Let me know how you’d prefer to proceed. Happy to adjust the PR accordingly.

oxarbitrage · 2026-03-24T11:41:14Z

By the way, I should have provided more context earlier. The main motivation here was recovering legacy funds that were otherwise inaccessible.

I had the mnemonic, but none of the available tools worked for recovery (zeccavator, zodl/zashi, and ywallet all failed in this case). The only viable path was to derive the Sapling key from the mnemonic (I wrote a small tool for that: https://github.com/oxarbitrage/zcash-sapling-derive) and then import it into zcashd using z_importkey.

That worked for me, but it made me realize that this recovery path would no longer be available once zcashd is deprecated. That’s what motivated porting these calls into zallet.

ValarDragon · 2026-04-25T04:12:13Z

I suggest we add the import key logic here, so zcashd folks can migrate

nullcopy

Looks good to me! I left a few minor comments, but nothing blocking (modulo merge conflicts)

utACK 532371e

nullcopy · 2026-05-04T20:20:23Z

+        .get_treestate(treestate_height.to_string())
+        .await
+        .map_err(|e| {
+            LegacyCode::InvalidParameter.with_message(format!(


s/LegacyCode::InvalidParameter/RpcErrorCode::InternalError/

Done — now InternalError (kept the message via ErrorObjectOwned, since ErrorCode has no with_message).

nullcopy · 2026-05-04T20:50:03Z

+        .map_err(|e| LegacyCode::Database.with_message(e.to_string()))?;
+
+    if let Some(tip) = chain_tip {
+        if start_height > tip {


(not blocking) might be nice to skip this check if rescan="no".

Done — the start_height > tip check is now skipped when rescan="no".

nullcopy · 2026-05-04T20:51:41Z

+        // - "no" → use the current chain tip so the sync engine only tracks new
+        //   transactions going forward.
+        //
+        // TODO: When rescan is "yes" and the key already exists, zcashd would force a


The recently added rewind_to_height() method should do this for you now

Deferred — rewind_to_height rewinds the whole wallet (all accounts), not just this key, so I left the TODO (now referencing it) rather than trigger a global rewind on import.

nullcopy · 2026-05-04T20:54:32Z

+        // does not expose a way to reset scan ranges for an existing account.
+        let effective_height = match rescan {
+            "yes" | "whenkeyisnew" => start_height,
+            "no" => chain_tip.unwrap_or(BlockHeight::from_u32(0)),


Not sure how I feel about silently failing over to 0 here

Thinking on it some more, I'm actually ok with it. I would support logging a warning here, though (not blocking)

Superseded by your follow-up below — added a warning log.

Done — tracing::warn! when the rescan="no" path falls back to genesis.

nullcopy · 2026-05-04T21:00:30Z

+) -> RpcResult<AccountBirthday> {
+    if height == BlockHeight::from_u32(0) {
+        return Ok(AccountBirthday::from_parts(
+            ChainState::empty(BlockHeight::from_u32(0), BlockHash([0; 32])),


Should this at least include the real genesis hash?

Left as zeros, with a comment explaining why: the chain state is the state before the birthday, and nothing precedes genesis, so the zero parent hash is the correct anchor — the real genesis hash would be the hash of block 0 itself.

oxarbitrage · 2026-06-04T12:32:37Z

Thanks for the review, and apologies for the delay in getting back to this!

Rebased onto main and resolved the keystore.rs conflict from the migration refactor: the encrypt helpers are now Encryptor methods on main, so I dropped the branch's duplicate free functions and kept only the new decrypt_standalone_sapling_extsk; I also dropped the zcashd-import cfg from Encryptor::encrypt_standalone_sapling_key, since the always-built z_importkey path needs it.

Addressed the review comments (replied inline on each thread):

fetch_account_birthday: treestate-fetch failure now returns InternalError instead of InvalidParameter.
import_key: skip the start_height > tip check when rescan="no" (start_height is unused there); tracing::warn! when the rescan="no" path falls back to genesis; refined the existing-key-rescan TODO to note rewind_to_height (deferred, since it rewinds the whole wallet rather than just this key).
Genesis ChainState: left as BlockHash([0; 32]) with a comment explaining why (no block precedes genesis, so the zero parent hash is the correct anchor).

Re @nuttycom's concern: z_exportkey's help text now warns that it is not a complete backup (Orchard funds under the same spending authority are not exported). Added a CHANGELOG entry for both methods.

Note: the two CI failures (Test NU7 and Latest build) look pre-existing and dependency-related (zebra-chain not covering NetworkUpgrade::Nu7, and orchard = "^0.13" failing to resolve), not from this PR.

linear · 2026-06-08T10:03:36Z

COR-254

COR-259

Adds two new RPC methods: - `z_importkey`: Imports a Sapling extended spending key into the wallet. The key is encrypted with age and stored in the keystore. A UFVK is derived and imported into the wallet database so the sync engine can track transactions. The rescan parameter controls whether historical blocks are scanned ("yes", "no", or "whenkeyisnew"), and start_height sets the birthday for the imported account. Real treestates are fetched from the chain indexer for non-zero start heights. - `z_exportkey`: Exports the spending key for a Sapling payment address. Requires the wallet to be unlocked. Looks up the key by iterating standalone sapling DFVKs and using decrypt_diversifier to match the address. Its documentation warns that the exported key is not a complete backup, as Orchard funds under the same spending authority are not represented. Also adds `fetch_account_birthday` to `json_rpc::utils` as a shared helper for building an AccountBirthday from a chain treestate. Includes unit tests for parameter validation, key encoding/decoding roundtrips, and address parsing, and a CHANGELOG entry for both methods. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

oxarbitrage · 2026-06-16T18:55:10Z

Validated this PR end-to-end against the dedicated integration test (zcash/integration-tests#76, wallet_import_export_key.py) by running it through the interop CI (ZIT-Revision), building zallet from this branch:

✅ wallet_import_export_key.py | True | 16 s — covers import → listaddresses (sapling UA under imported_watchonly) → re-import idempotency → z_exportkey round-trip → cross-wallet isolation → rescan param values → and the error paths (out-of-range height, invalid rescan, invalid key, address-not-in-wallet).

The only red shard in that run was an unrelated, pre-existing failure on nuparams.py (getblocksubsidy subsidy assertion), which this PR's diff doesn't touch — tracking that separately on the integration-tests side.

This is approved + mergeable + green, and now interop-validated. Planning to merge shortly.

oxarbitrage force-pushed the z_importexportkey branch from 67e0b34 to 532371e Compare March 20, 2026 12:14

oxarbitrage mentioned this pull request Mar 20, 2026

Add z_importkey and z_exportkey test zcash/integration-tests#76

Draft

nuttycom requested review from nullcopy and nuttycom April 6, 2026 16:42

mnm458 mentioned this pull request Apr 24, 2026

rpc: Implement z_importviewingkey for Sapling #431

Open

3 tasks

nullcopy approved these changes May 4, 2026

View reviewed changes

oxarbitrage force-pushed the z_importexportkey branch from 532371e to 1804337 Compare June 4, 2026 12:16

oxarbitrage force-pushed the z_importexportkey branch from 1804337 to 368ec79 Compare June 8, 2026 21:40

oxarbitrage merged commit a0f4556 into main Jun 23, 2026
38 checks passed

nuttycom deleted the z_importexportkey branch June 23, 2026 14:49

oxarbitrage mentioned this pull request Jun 23, 2026

rpc: make z_importkey generic over Chain #505

Closed

Uh oh!

Conversation

oxarbitrage commented Mar 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nuttycom commented Mar 23, 2026

Uh oh!

nuttycom commented Mar 23, 2026

Uh oh!

oxarbitrage commented Mar 24, 2026

Uh oh!

oxarbitrage commented Mar 24, 2026

Uh oh!

ValarDragon commented Apr 25, 2026

Uh oh!

nullcopy left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

oxarbitrage commented Jun 4, 2026

Uh oh!

linear Bot commented Jun 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

oxarbitrage commented Jun 16, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

oxarbitrage commented Mar 20, 2026 •

edited

Loading

nullcopy left a comment •

edited

Loading

linear Bot commented Jun 8, 2026 •

edited

Loading