wallet: rpc: Deprecate `encryptwallet` RPC for encrypting existing wallets. #36387

pull davidgumberg wants to merge 8 commits into bitcoin:master from davidgumberg:2026-09-29-deprecate-encryptwallet changing 19 files +166 −86
  1. davidgumberg commented at 2:11 AM on September 30, 2026: contributor

    For more context, see: #36027

    Encrypting existing wallets that are unencrypted is fraught with footguns and complexity both for users and for developers.

    For example:

    • No efforts are made to ensure that remnants of unencrypted key material are not left on the user's disk, as attempting to ensure this would be difficult and dangerous, and for some SSD's infeasible.

    • Encrypting a wallet that has manually imported descriptors will cause the wallet to change the spending conditions out from under the user. (https://github.com/bitcoin/bitcoin/issues/26607)

    • Because new keys are made after encryption, restoring from a backup made before encryption may result in loss of funds.

    LLM Disclosure: Used gemma4-26B and qwen3.8-next-flash as research and drafting tools, but all code and text present here were written by me.

  2. DrahtBot added the label Wallet on Sep 30, 2026
  3. DrahtBot commented at 2:11 AM on September 30, 2026: contributor

    <!--e57a25ab6845829454e8d69fc972939a-->

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

    <!--006a51241073e994b41acfe9ec718e94-->

    External sites

    <!--021abf342d371248e50ceaed478a90ca-->

    Reviews

    See the guideline and AI policy for information on the review process.

    Type Reviewers
    ACK w0xlt, Eunovo
    Concept ACK pseudoramdom, rkrux
    Stale ACK pablomartin4btc, achow101

    If your review is incorrectly listed, please copy-paste <code>&lt;!--meta-tag:bot-skip--&gt;</code> into the comment that the bot should ignore.

    <!--174a7506f384e20aa4161008e828411d-->

    Conflicts

    Reviewers, this pull request conflicts with the following ones:

    • #36868 <sub><img src="https://drahtbot.space/ack_count/bitcoin/bitcoin/36868.svg"></sub> (test: remove unused nodes and restarts from wallet tests by w0xlt)
    • #36864 <sub><img src="https://drahtbot.space/ack_count/bitcoin/bitcoin/36864.svg"></sub> (rpc: deprecate iswatchonly field of getaddressinfo by w0xlt)
    • #36796 <sub><img src="https://drahtbot.space/ack_count/bitcoin/bitcoin/36796.svg"></sub> (wallet, sqlite: Enable secure_delete by default by achow101)
    • #36577 <sub><img src="https://drahtbot.space/ack_count/bitcoin/bitcoin/36577.svg"></sub> (psbt: check sig sighash only if a type is given by fametrano)
    • #36257 <sub><img src="https://drahtbot.space/ack_count/bitcoin/bitcoin/36257.svg"></sub> (qa: assert_equals -> assert_true/assert_false by hodlinator)

    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 typos and grammar issues:

    • doc/managing-wallets.md: accompolished → accomplished [misspelling]

    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):

    • test/functional/test_framework/test_framework.py: wallet_importprivkey(n.get_wallet_rpc(wallet_name), n.get_deterministic_priv_key().key, 0, label="coinbase") (both branches)

    <sup>2026-11-12 23:55:40</sup>

  4. pseudoramdom commented at 5:00 AM on September 30, 2026: contributor

    Concept ACK, will review when I get a chance.

  5. w0xlt commented at 5:33 PM on September 30, 2026: contributor

    Concept ACK

  6. in doc/release-notes-deprecateencryptwallet.md:1 in 2cc0946985 outdated


    pablomartin4btc commented at 10:36 PM on October 20, 2026:

    nit: filename convention is release-notes-36387.md.


    davidgumberg commented at 1:56 AM on November 5, 2026:

    As we've discussed elsewhere, the main purpose of that convention/recommendation is to avoid naming collisions, but it has the downside that it also requires the PR to be opened before the release note can be made. I think it's a matter of preference which I feel a bit stubbornly about so I'll mark this as resolved.

  7. in test/functional/test_framework/test_framework.py:418 in 2cc0946985 outdated
     418 | +                with WalletUnlock(w, self.default_wallet_pass):
     419 | +                    wallet_importprivkey(n.get_wallet_rpc(wallet_name), n.get_deterministic_priv_key().key, 0, label="coinbase")
     420 | +            else:
     421 |                  n.createwallet(wallet_name=wallet_name, load_on_startup=True)
     422 | -            wallet_importprivkey(n.get_wallet_rpc(wallet_name), n.get_deterministic_priv_key().key, 0, label="coinbase")
     423 | +                wallet_importprivkey(n.get_wallet_rpc(wallet_name), n.get_deterministic_priv_key().key, 0, label="coinbase")
    


    pablomartin4btc commented at 11:44 PM on October 20, 2026:

    nit: the two branches only differ in the passphrase and the unlock around the import, so they could perhaps be collapsed. Also w is assigned but then get_wallet_rpc is called again for wallet_importprivkey, so w could be reused there.

    Since this drops the if wallet_name is not None: check, the wallet_names comment could also drop "If wallet names are None, wallet creation is skipped.". That case has been broken since #32452 (fcc457573f) anyway (get_wallet_rpc(None) would rase in urllib.parse.quote).

                passphrase_args = {"passphrase": self.default_wallet_pass} if encrypted else {}
                n.createwallet(wallet_name=wallet_name, load_on_startup=True, **passphrase_args)
                w = n.get_wallet_rpc(wallet_name)
                with WalletUnlock(w, self.default_wallet_pass) if encrypted else contextlib.nullcontext():
                    wallet_importprivkey(w, n.get_deterministic_priv_key().key, 0, label="coinbase")                
    

    (needs import contextlib; tested on top of 2cc0946985 with the full extended functional suite.)


    davidgumberg commented at 2:01 AM on November 5, 2026:

    Thanks for the suggestion, while your version is shorter, I think the current approach is more simple and legible, stylistic choice, but if you are insistent I'll change it.

  8. in test/functional/test_framework/test_framework.py:48 in 2cc0946985 outdated
      43 | @@ -44,6 +44,9 @@
      44 |      JSONRPCException,
      45 |  )
      46 |  
      47 | +from .wallet_util import WalletUnlock
      48 | +
    


    pablomartin4btc commented at 11:49 PM on October 20, 2026:

    nit: extra blank line here.


    davidgumberg commented at 2:33 AM on November 5, 2026:

    thanks, fixed.

  9. in test/functional/wallet_gethdkeys.py:23 in 2cc0946985 outdated
      18 | @@ -19,6 +19,8 @@ class WalletGetHDKeyTest(BitcoinTestFramework):
      19 |      def set_test_params(self):
      20 |          self.setup_clean_chain = True
      21 |          self.num_nodes = 1
      22 | +        self.extra_args = [["-deprecatedrpc=encryptwallet"]]
      23 | +
    


    pablomartin4btc commented at 11:49 PM on October 20, 2026:

    nit: extra blank line here.


    davidgumberg commented at 2:33 AM on November 5, 2026:

    Thanks, fixed.

  10. in test/functional/wallet_encryption.py:24 in 2cc0946985 outdated
      19 | @@ -20,6 +20,8 @@ class WalletEncryptionTest(BitcoinTestFramework):
      20 |      def set_test_params(self):
      21 |          self.setup_clean_chain = True
      22 |          self.num_nodes = 1
      23 | +        self.extra_args = [["-deprecatedrpc=encryptwallet"]]
      24 | +
    


    pablomartin4btc commented at 11:49 PM on October 20, 2026:

    nit: extra blank line here.


    davidgumberg commented at 2:33 AM on November 5, 2026:

    Thanks, fixed.

  11. in test/functional/wallet_listdescriptors.py:49 in 2cc0946985 outdated
      44 | +        self.log.info('- With private=true, errors when the wallet is locked.')
      45 | +        assert_raises_rpc_error(-13, 'Please enter the wallet passphrase with walletpassphrase first.', encrypted_wallet.listdescriptors, True)
      46 | +        encrypted_wallet.walletpassphrase(passphrase=self.default_wallet_pass, timeout=self.rpc_timeout)
      47 | +        encrypted_wallet.listdescriptors(True)
      48 | +        encrypted_wallet.unloadwallet()
      49 | +
    


    pablomartin4btc commented at 11:51 PM on October 20, 2026:

    nit: extra blank line here.


    davidgumberg commented at 2:33 AM on November 5, 2026:

    Thanks, fixed.

  12. in test/functional/wallet_listdescriptors.py:22 in 2cc0946985
      16 | @@ -17,7 +17,10 @@
      17 |      assert_equal,
      18 |      assert_raises_rpc_error,
      19 |  )
      20 | -from test_framework.wallet_util import generate_keypair
      21 | +from test_framework.wallet_util import (
      22 | +        WalletUnlock,
      23 | +        generate_keypair
    


    pablomartin4btc commented at 12:06 AM on October 21, 2026:

    nit: import block indented 8 spaces (and missing trailing comma after generate_keypair).

        WalletUnlock,
        generate_keypair,
    

    davidgumberg commented at 2:33 AM on November 5, 2026:

    Thanks for catching, fixed.

  13. in test/functional/wallet_listdescriptors.py:47 in 2cc0946985
      42 | +            assert_equal(encrypted_locked_output, encrypted_wallet.listdescriptors())
      43 | +
      44 | +        self.log.info('- With private=true, errors when the wallet is locked.')
      45 | +        assert_raises_rpc_error(-13, 'Please enter the wallet passphrase with walletpassphrase first.', encrypted_wallet.listdescriptors, True)
      46 | +        encrypted_wallet.walletpassphrase(passphrase=self.default_wallet_pass, timeout=self.rpc_timeout)
      47 | +        encrypted_wallet.listdescriptors(True)
    


    pablomartin4btc commented at 12:59 AM on October 21, 2026:

    nit: the previous version of the test compared the private output against expected_private and now the wallet is left unlocked until its unload.

             self.log.info("- With private=true, works when unlocked and matches the public descriptors.")
             with WalletUnlock(encrypted_wallet, self.default_wallet_pass):
                 private_output = encrypted_wallet.listdescriptors(True)
             public_descs = [d["desc"] for d in encrypted_locked_output["descriptors"]]
             private_descs = [d["desc"] for d in private_output["descriptors"]]
             assert all("tprv" in d for d in private_descs)
             assert_equal([self.nodes[0].deriveaddresses(d, [0, 2]) for d in private_descs],
                          [self.nodes[0].deriveaddresses(d, [0, 2]) for d in public_descs])
    

    davidgumberg commented at 2:33 AM on November 5, 2026:

    I dropped this coverage deliberately since it seemed kind of redundant to me, but I guess in theory listdescriptors private=true could work for unencrypted wallets but be broken for encrypted wallets and output incorrect stuff, even though that's unlikely, so taken, thanks for the approach.

  14. in test/functional/wallet_bumpfee.py:801 in 2cc0946985
     801 | +                            encrypted_wallet.bumpfee, rbfid)
     802 | +
     803 | +    self.log.info('Test that an unlocked wallet can bump txn')
     804 | +    with WalletUnlock(encrypted_wallet, self.default_wallet_pass):
     805 | +        bumpfee_res = encrypted_wallet.bumpfee(rbfid)
     806 | +    assert bumpfee_res["errors"] == []
    


    pablomartin4btc commented at 1:03 AM on October 21, 2026:

    nit:

        assert_equal(bumpfee_res["errors"], [])
    

    davidgumberg commented at 2:33 AM on November 5, 2026:

    taken

  15. in test/functional/rpc_deprecated.py:43 in 2cc0946985 outdated
      39 | @@ -40,6 +40,12 @@ def run_test(self):
      40 |                  "fakeargument"
      41 |              )
      42 |  
      43 | +            assert_raises_rpc_error(
    


    pablomartin4btc commented at 1:05 AM on October 21, 2026:

    nit (for consistency with the removeprunedfunds check above)...

                self.log.info("Test encryptwallet deprecation")
                assert_raises_rpc_error(
    

    davidgumberg commented at 2:32 AM on November 5, 2026:

    Thanks, taken!

  16. pablomartin4btc commented at 1:15 AM on October 21, 2026: member

    Concept ACK

    I think encryptwallet RPC was created before the createwalllet gained the passphrase, and for what it worth creating today a new encrypted wallet and sendall-ing to it is equivalent and cleaner.

    The GUI "Encrypt Wallet…" action (WalletView::encryptWallet → interfaces::Wallet::encryptWallet) is unaffected and is probably where most users hit this. It might be worth mentioning in the description and release notes so the GUI and RPC deprecations ship in the same release (?).

    Left some nits.

  17. rkrux commented at 12:32 PM on November 4, 2026: contributor

    Concept ACK

  18. in test/functional/rpc_psbt.py:254 in 2587fe96a8 outdated
     249 | +        # Need to get a handle for the default wallet since we'll have multiple wallets loaded during this test.
     250 | +        def_wallet = self.nodes[0].get_wallet_rpc(self.default_wallet_name)
     251 | +        def_wallet.sendtoaddress(encrypted_wallet.getnewaddress(), 1)
     252 | +        self.generate(self.nodes[0], 1)
     253 | +
     254 | +        self.log.info("- Does not work when sign = true (default) and the wallet is locked.")
    


    achow101 commented at 10:09 PM on November 4, 2026:

    In 2587fe96a8c54a97d2dd9c9d9fcc7d3ceda441b4 "refactor: test: rpc_psbt.py extract encrypted wallet signing"

    This logging is unnecessary.


  19. davidgumberg force-pushed on Nov 5, 2026
  20. davidgumberg commented at 2:34 AM on November 5, 2026: contributor

    Pushed to address reviewer feedback.

  21. pablomartin4btc commented at 8:02 PM on November 5, 2026: member

    ACK 854abafabece0b74d77eecac0cba5e4b3f550fb4

  22. DrahtBot requested review from pseudoramdom on Nov 5, 2026
  23. DrahtBot requested review from rkrux on Nov 5, 2026
  24. achow101 commented at 11:05 PM on November 5, 2026: member

    ACK 854abafabece0b74d77eecac0cba5e4b3f550fb4

  25. w0xlt commented at 11:22 PM on November 5, 2026: contributor

    ACK 854abafabece0b74d77eecac0cba5e4b3f550fb4

  26. achow101 commented at 12:21 AM on November 6, 2026: member

    Silent merge conflict I guess:

      File "/home/ava/bitcoin/bitcoin/master/clang_RelWithDebInfo/test/functional/rpc_deprecated.py", line 32
        self.log.info("Test encryptwallet deprecation")
    IndentationError: unexpected indent
    
  27. in doc/release-notes-deprecateencryptwallet.md:4 in 854abafabe outdated
       0 | @@ -0,0 +1,11 @@
       1 | +Updated RPCs
       2 | +------------
       3 | +
       4 | +- The `encryptwallet` RPC for encrypting an existing wallet that was created as
    


    fanquake commented at 10:28 AM on November 6, 2026:

    Not sure about the rest of the formatting, but can you add the missing (#36387):

    - The `encryptwallet` RPC for encrypting an existing wallet that was created as
      an unencrypted wallet has been deprecated and will be removed in a future major
      release. Support for creating encrypted wallets is not going away or being changed,
      it is only encrypting already unencrypted wallets that has footguns for
      users and is being deprecated. In order to continue using `encryptwallet`,
      `bitcoind` must be started with the `-deprecatedrpc=encryptwallet` flag
      set. (#36387)
    

    See #36773 for context.


    davidgumberg commented at 1:32 AM on November 7, 2026:

    Thanks for pointing this out, fixed.

  28. maflcko commented at 1:54 PM on November 6, 2026: member

    Silent merge conflict I guess:

      File "/home/ava/bitcoin/bitcoin/master/clang_RelWithDebInfo/test/functional/rpc_deprecated.py", line 32
        self.log.info("Test encryptwallet deprecation")
    IndentationError: unexpected indent
    

    Maybe a trailing comment can be added to avoid those in the future?

            if self.is_wallet_compiled():
                self.log.info("Tests for deprecated wallet-related RPC methods (if any)")
                self.nodes[0].createwallet("a_wallet")
                wallet = self.nodes[0].get_wallet_rpc("a_wallet")  # do not remove this boilerplate, even if unused, it will be needed again in the future
    

    Edit: Also, this should be updated to require the -deprecatedrpc toggle or be reworded?

    $ git grep encryptwallet
    doc/managing-wallets.md:$ bitcoin-cli -rpcwallet="wallet-01" encryptwallet "passphrase"
    
  29. davidgumberg force-pushed on Nov 7, 2026
  30. davidgumberg commented at 1:32 AM on November 7, 2026: contributor

    Pushed a rebase to fix the silent merge conflict and address reviewer feedback.

    • Added a comment to prevent (some) future silent merge conflicts
    • Fixed the managing-wallets.md file to not recommend encryptwallet
    • Added the PR number to the release notes
  31. Eunovo commented at 2:41 PM on November 10, 2026: contributor

    Concept ACK https://github.com/bitcoin/bitcoin/pull/36387/commits/a06ba1f5c883a8f451cfe7935831e9be8634e20c:

    Some modified tests, like wallet_multiwallet.py, indirectly tested encryptwallet persistence by unloading the encrypted wallet and reloading it. None of the current functional tests does this, so we lose that coverage on the now-deprecated encryptwallet RPC. A natural location for a test like this is wallet_encryption.py, which will be deleted when encryptwallet is deleted.

  32. davidgumberg force-pushed on Nov 10, 2026
  33. davidgumberg commented at 9:12 PM on November 10, 2026: contributor

    Some modified tests, like wallet_multiwallet.py, indirectly tested encryptwallet persistence by unloading the encrypted wallet and reloading it. None of the current functional tests does this, so we lose that coverage on the now-deprecated encryptwallet RPC. A natural location for a test like this is wallet_encryption.py, which will be deleted when encryptwallet is deleted.

    Good catch, thanks for the suggestion, I've pushed to add a check that the wallet is still encrypted after reloading in the sasme commit where I change wallet_multiwallet.py:

    diff --git a/test/functional/wallet_encryption.py b/test/functional/wallet_encryption.py
    index 7b5aae7bde..a319868d26 100755
    --- a/test/functional/wallet_encryption.py
    +++ b/test/functional/wallet_encryption.py
    @@ -46,6 +46,11 @@ class WalletEncryptionTest(BitcoinTestFramework):
             assert_raises_rpc_error(-8, "passphrase cannot be empty", self.nodes[0].walletpassphrase, '', 1)
             assert_raises_rpc_error(-8, "passphrase cannot be empty", self.nodes[0].walletpassphrasechange, '', 'ff')
     
    +        self.log.info("Test encryptwallet persistence")
    +        self.nodes[0].unloadwallet(self.default_wallet_name)
    +        self.nodes[0].loadwallet(self.default_wallet_name)
    +        assert_raises_rpc_error(-13, "Please enter the wallet passphrase with walletpassphrase first", self.nodes[0].signmessage, address, msg)
    +
             # Check that walletpassphrase works
             self.nodes[0].walletpassphrase(passphrase, 2)
    
  34. DrahtBot added the label CI failed on Nov 10, 2026
  35. davidgumberg force-pushed on Nov 10, 2026
  36. davidgumberg force-pushed on Nov 10, 2026
  37. davidgumberg commented at 11:29 PM on November 10, 2026: contributor

    Sorry for the noise, made the change to a stale branch on a different machine.

  38. DrahtBot removed the label CI failed on Nov 11, 2026
  39. DrahtBot added the label Needs rebase on Nov 12, 2026
  40. refactor: test: Avoid encryptwallet in interface_bitcoin_cli.py
    This RPC will be deprecated in a future commit, so tests should avoid
    relying on it. This commit also adds scaffolding to init_wallet that
    will be used when refactoring other tests.
    1bea70f93d
  41. refactor: test: rpc_psbt.py extract encrypted wallet signing
    This improves legibility of the test and avoids the use of
    `encryptwallet` which will be deprecated.
    99946b3356
  42. refactor: test: wallet_bumpfee.py isolate encrypted wallet tests 2655ddafe1
  43. refactor: test: wallet_fundrawtransaction.py avoid encryptwallet
    A later commit will deprecate this RPC.
    52ccf18216
  44. refactor: test: wallet_listdescriptors.py extract encrypted wallet test
    Co-authored-by: Pablo Martin <pablomartin4btc@gmail.com>
    91233b57ca
  45. refactor: test: wallet_multiwallet.py use a new encrypted wallet
    Also add coverage for persistence of encryption to
    `wallet_encryption.py` since this would be lost otherwise.
    549031115b
  46. refactor: test: signrawtransaction isolate encrypted wallet test
    This is useful since a future commit will deprecate `encryptwallet`.
    4bc039d932
  47. wallet: rpc: Deprecate `encryptwallet`
    Encrypting wallets from creation will still be supported, but there are
    footguns both for users and for developers in supporting wallets that
    are created unencrypted and then later become encrypted.
    
    The functional tests where the `deprecatedrpc` argument is added are
    ones where functionality or behavior of `encryptwallet` is being tested,
    they should be kept until the RPC command is removed.
    8833e3e13f
  48. davidgumberg force-pushed on Nov 12, 2026
  49. DrahtBot removed the label Needs rebase on Nov 13, 2026
  50. w0xlt commented at 12:06 AM on November 13, 2026: contributor

    reACK 8833e3e13fca1bbc80db53107e31e23855a650aa

  51. DrahtBot requested review from pablomartin4btc on Nov 13, 2026
  52. DrahtBot requested review from achow101 on Nov 13, 2026
  53. DrahtBot requested review from Eunovo on Nov 13, 2026
  54. Eunovo approved

github-metadata-mirror

This is a metadata mirror of the GitHub repository bitcoin/bitcoin. This site is not affiliated with GitHub. Content is generated from a GitHub metadata backup.
generated: 2026-11-16 17:51 UTC

This site is hosted by @0xB10C
More mirrored repositories can be found on mirror.b10c.me