wallet: Remove mapMasterKeys and enforce that only one encryption key can exist #36031

mapMasterKeys was introduced in #352 without a clear rationale. Likely it was to allow the user to have multiple passphrases by encrypting the wallet's encryption key with different passphrases. However, this functionality was never implemented, and current code enforces in a few places (inconsistently) that there is only one encryption key.

By removing mapMasterKeys and replacing it with a single m_encryption_key, we can remove this confusion and simplify encryption key handling. No one should have a wallet that has more than one encryption key, and the ID of that key should be 1.

The format of the database record remains unchanged. If a wallet somehow has an encryption key with an ID other than 1, the record will stay the same and the id is stored. Otherwise, new encryption keys always have an ID of 1.

If a wallet has more than one encryption key, this becomes a corruption error because it should never happen outside of someone doing something weird with their wallet.

I asked Matt for his rationale for adding mapMasterKeys and his response was

I have no idea I barely knew how to code when I wrote that shit.

<!--e57a25ab6845829454e8d69fc972939a-->

The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

<!--006a51241073e994b41acfe9ec718e94-->

Code Coverage & Benchmarks

For details see: https://corecheck.dev/bitcoin/bitcoin/pulls/36031.

<!--021abf342d371248e50ceaed478a90ca-->

Reviews

See the guideline and AI policy for information on the review process. A summary of reviews will appear here.

<!--174a7506f384e20aa4161008e828411d-->

Conflicts

Reviewers, this pull request conflicts with the following ones:

• #35752 (wallet: make encryption state updates atomic by l0rinc)
• #32895 (wallet: Prepare for future upgrades by recording versions of last client to open and decrypt by achow101)
• #30343 (wallet, logging: Replace WalletLogPrintf() with LogInfo() by ryanofsky)

If you consider this pull request important, please also help to review the conflicting pull requests. Ideally, start with the one that should be merged first.

<!--5faf32d7da4f0f540f40219e4f7537a3-->

LLM Linter (✨ experimental)

Possible places where named args for integral literals may be used (e.g. func(x, /*named_arg=*/0) in C++, and func(x, named_arg=0) in Python):

• WriteIC(std::make_pair(DBKeys::MASTER_KEY, kMasterKey.m_id), kMasterKey, true) in src/wallet/walletdb.cpp

^{2026-08-19 23:42:13}

<!--85328a0da195eb286784d51f73fa0af9-->

🚧 At least one of the CI tasks failed. _{Task iwyu: https://github.com/bitcoin/bitcoin/actions/runs/32314344744/job/96263457089} _{LLM reason (✨ experimental): CI failed because IWYU reported an include-fixing issue (“Failure generated from IWYU”) in src/bench/wallet_encrypt.cpp, causing the CI test script to exit with code 1.}

<details><summary>Hints</summary>

Try to run the tests locally, according to the documentation. However, a CI failure may still happen due to a number of reasons, for example:

• Possibly due to a silent merge conflict (the changes in this pull request being incompatible with the current code in the target branch). If so, make sure to rebase on the latest commit of the target branch.

• A sanitizer issue, which can only be found by compiling with the sanitizer and running the affected test.

• An intermittent issue.

Leave a comment here, if you need help tracking down a confusing failure.

</details>