Skip to content

[Wallet] Save imported Sapling viewing keys and the witness cache size - #2988

Open
alexxiy wants to merge 1 commit into
PIVX-Project:masterfrom
alexxiy:fix/persist-sapling-viewing-keys
Open

alexxiy wants to merge 1 commit into
PIVX-Project:masterfrom
alexxiy:fix/persist-sapling-viewing-keys

Conversation

@alexxiy

@alexxiy alexxiy commented Nov 3, 2026

Copy link
Copy Markdown

Problem

importsaplingviewingkey adds the key in memory only. The notes the import finds are saved, tagged
with the key's ivk, but the key itself is not. After a restart a wallet that holds only viewing keys
breaks in one of two ways:

  • Crash. If the startup rescan reaches one of those notes, mapSaplingFullViewingKeys.at(ivk)
    throws and pivxd exits during init with map::at.
  • Silent loss. If it doesn't (the key has no notes yet, or the wallet's best block is past them),
    the node starts normally and logs nothing, but the address is gone from listshieldaddresses.
    New notes are not found and spends are missed, while the old notes still count in the balance.

Which of the two happens depends on how long the node ran, because the wallet's best block is only
saved periodically.

A second bug affects any key imported with a rescan into a wallet created on a running chain.
ScanForWalletTransactions writes the notes it touched with their witnesses, but not
nWitnessCacheSize. The wallet has no size saved yet, so it loads as 0, and the next start aborts on

Assertion `nWitnessCacheSize >= (int64_t) nd->witnesses.size()' failed.

in CopyPreviousWitnesses. This keeps happening until the first periodic SetBestChain writes the
size, up to an hour later. Wallets created at block 0, as in most tests, hide the bug: the startup
rescan raises the saved size.

Both bugs are in v5.6.1 and on master. We found them while running a node that watches shielded
addresses with viewing keys only.

Changes

  • New wallet record sapextfvk (key: ivk, value: extended full viewing key).
    AddViewingKeyToWallet writes it before adding the key in memory, and LoadWallet loads it.
    • Not encrypted: the key cannot spend, and csapzkey already stores the extfvk in the clear.
    • Counted as a key type for -salvagewallet.
    • Loading one sets the wallet's first-key time to 1, since viewing keys have no birthday, as for
      watch-only scripts.
    • Older versions ignore the unknown record, so they can still read the wallet.
  • UpdateSaplingNullifierNoteMapWithTx skips a note whose viewing key is missing, instead of
    throwing. This only happens in wallets written before this change. The node starts, and importing
    the key again with a rescan restores the address.
  • ScanForWalletTransactions writes nWitnessCacheSize in the same batch as the notes.

Recovering an affected wallet

Start once with -rescan, which rebuilds the witnesses. Then import the viewing key again:
importsaplingviewingkey "<key>" "yes" <start height>.

Tests

sapling_wallet_persistence.py now runs two nodes and covers:

  • a viewing key with notes and one without, over three restarts, while sending to and spending from
    the address;
  • the same after encryptwallet;
  • a new wallet on a running chain: a viewing key and then a spending key imported with a rescan,
    followed by a restart.

Without the fix the new cases fail: pivxd exits with map::at at the first restart.

Tested on master 4b3bc73, built in ubuntu:20.04 with depends, as in CI. All 87 unit test suites
pass (each in its own process), as do every sapling_* and wallet_* functional test and
tiertwo_deterministicmns.py. The same change also passes on v5.6.1.

importsaplingviewingkey kept the key in memory only, while the notes it
found were written to the wallet, tagged with the key's ivk. After a
restart the key was gone, in one of two ways:

- If a rescan reached one of those notes, mapSaplingFullViewingKeys.at()
  threw std::out_of_range and pivxd died with "map::at" in AppInit.
- If none did, the node started normally and logged nothing. It found
  no new notes for the key and missed its spends, while the old notes
  still counted in the balance.

Write the key to a new "sapextfvk" record and load it with the wallet.
Older clients ignore the record. It is not encrypted: it cannot spend,
and encrypted Sapling keys store their extended full viewing key in the
clear too. The record counts as a key for -salvagewallet. A viewing key
has no birthday, so loading one sets the wallet's to the start of time.

Wallets written before this change hold such notes and no key. Skip
those notes instead of throwing, so the node starts and the key can be
imported again; a rescan with the import finds what the wallet missed.

ScanForWalletTransactions also wrote the notes it touched, with their
witnesses, but not nWitnessCacheSize, which SetBestChain normally writes
with them. A wallet created on a running chain has none saved, so it
loads as 0. After importing a key (viewing or spending) with a rescan
over its notes, the next startup failed

    nWitnessCacheSize >= (int64_t) nd->witnesses.size()

in CopyPreviousWitnesses until the first periodic SetBestChain, up to
an hour later. Write the size in the same batch as the notes. A wallet
already in this state recovers by starting once with -rescan.

sapling_wallet_persistence.py now covers these cases.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant