rpc: Manual prune lock management (Take 2) #34534

pull fjahr wants to merge 6 commits into bitcoin:master from fjahr:2026-02-prunelocks-rpc-v2 changing 9 files +392 −1
  1. fjahr commented at 2:01 PM on February 8, 2026: contributor

    This is a refreshed version of #19463, which was closed due to inactivity.

    Motivation: On pruned nodes, if a wallet is not loaded while the node is running, blocks necessary for rescanning when the wallet is loaded may be pruned. This PR allows users and external wallet software to manually manage prune locks via RPC, so they can protect blocks needed for future rescans and also clean up locks that are no longer relevant (e.g. after permanently unloading a wallet from a node). This is useful both for Bitcoin Core's own wallet and for external wallets that use Bitcoin Core as a backend. Usage of temporary prune locking may also be helpful in other functional test scenarios but I didn't spend time to check where might apply.

    This PR leverages the existing prune locks system we already have. The interface of the RPCs of the old PR has been slightly updated, it now matches the pattern used by setban/listbanned exactly. The locks are prefixed to distinguish them from the systems locks and prevent naming colissions. They are not persisted across restarts.

  2. DrahtBot added the label RPC/REST/ZMQ on Feb 8, 2026
  3. DrahtBot commented at 2:01 PM on February 8, 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
    Concept ACK stickies-v, andrewtoth, optout21
    Stale ACK sedited

    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:

    • #36858 <sub><img src="https://drahtbot.space/ack_count/bitcoin/bitcoin/36858.svg"></sub> (refactor: break the blockstorage/validation circular dependency by pzafonte)
    • #36856 <sub><img src="https://drahtbot.space/ack_count/bitcoin/bitcoin/36856.svg"></sub> (kernel: add manual pruning by pzafonte)
    • #36778 <sub><img src="https://drahtbot.space/ack_count/bitcoin/bitcoin/36778.svg"></sub> (AssumeUTXO: replace loadtxoutset RPC with a startup arg by l0rinc)
    • #36738 <sub><img src="https://drahtbot.space/ack_count/bitcoin/bitcoin/36738.svg"></sub> (refactor: move block writes and pruning into BlockManager by pzafonte)
    • #36629 <sub><img src="https://drahtbot.space/ack_count/bitcoin/bitcoin/36629.svg"></sub> (Add output script index and corresponding script history RPC by andrewtoth)
    • #31260 <sub><img src="https://drahtbot.space/ack_count/bitcoin/bitcoin/31260.svg"></sub> (scripted-diff: Type-safe settings retrieval 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-->

  4. sedited commented at 2:15 PM on February 8, 2026: contributor

    Concept ACK

  5. DrahtBot added the label CI failed on Feb 8, 2026
  6. DrahtBot commented at 3:19 PM on February 8, 2026: contributor

    <!--85328a0da195eb286784d51f73fa0af9-->

    🚧 At least one of the CI tasks failed. <sub>Task Windows native, fuzz, VS 2022: https://github.com/bitcoin/bitcoin/actions/runs/21799390662/job/62892243983</sub> <sub>LLM reason (✨ experimental): Fuzz test failed because the RPC command "listprunelocks" is not registered as safe or unsafe for fuzzing in rpc.cpp.</sub>

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

  7. fjahr force-pushed on Feb 8, 2026
  8. fjahr commented at 3:29 PM on February 8, 2026: contributor

    Fixing CI failure: Forgot to set RPC_COMMANDS_[NOT_]SAFE_FOR_FUZZING for the new RPCs.

  9. DrahtBot removed the label CI failed on Feb 8, 2026
  10. in src/rpc/blockchain.cpp:886 in f192b06a3b
     881 | +        "Returns a list of all active prune locks.\n"
     882 | +        "Prune locks prevent block data at specific heights from being pruned.\n"
     883 | +        "These locks are used internally by indexes and can also be set manually via the setprunelock RPC.\n",
     884 | +        {},
     885 | +        RPCResult{
     886 | +            RPCResult::Type::ARR, "", "",
    


    luke-jr commented at 1:51 AM on February 10, 2026:

    This was an Object for future extensibility. No reason to lose that.


    fjahr commented at 1:54 PM on February 18, 2026:

    The RPC is called listprunelocks, I don't see how it could be extended to return anything else aside from a list of locks without that other thing feeling out of place. Can you give some specific ideas that you have? At least I would want to give the RPC a different name then (getpruneinfo or so) but potentially these ideas should rather be in a separate RPC. I prefer consistency and so I really like that we could be consistenty with the banning RPC.


    maflcko commented at 2:28 PM on February 18, 2026:

    listprunelocks could return a "blockman epoch" in the future, if there was need to further distinguish rpc results. (Yes, this is made up, but with an array, this is impossible, with an object, this is trivial and harmless)


    fjahr commented at 2:35 PM on February 18, 2026:

    What is a "blockman epoch"? I don't think I have heard of that before.


    fjahr commented at 3:40 PM on February 19, 2026:

    I guess TIL per this comment that the JSON object thing is in the dev notes, fair enough, I have changed it to return an object.

  11. in src/rpc/blockchain.cpp:890 in f192b06a3b
     885 | +        RPCResult{
     886 | +            RPCResult::Type::ARR, "", "",
     887 | +            {
     888 | +                {RPCResult::Type::OBJ, "", "",
     889 | +                {
     890 | +                    {RPCResult::Type::STR, "name", "The identifier of the prune lock"},
    


    luke-jr commented at 1:51 AM on February 10, 2026:
                        {RPCResult::Type::STR, "id", "The identifier of the prune lock"},
    

    fjahr commented at 1:54 PM on February 18, 2026:

    Done

  12. luke-jr changes_requested
  13. luke-jr commented at 1:53 AM on February 10, 2026: contributor

    Incomplete review. Basically, the original PR interface was way better.

  14. in src/rpc/blockchain.cpp:905 in f192b06a3b
     900 | +{
     901 | +    ChainstateManager& chainman = EnsureAnyChainman(request.context);
     902 | +    UniValue locks_arr(UniValue::VARR);
     903 | +    {
     904 | +        LOCK(::cs_main);
     905 | +        const auto& prune_locks = chainman.m_blockman.GetPruneLocks();
    


    bvbfan commented at 6:56 AM on February 10, 2026:

    You could get it as copy and don't keep lock while iterating, performance wise.

    const auto prune_locks = WITH_LOCK(::cs_main, return chainman.m_blockman.GetPruneLocks());
    

    fjahr commented at 1:54 PM on February 18, 2026:

    Done

  15. fjahr force-pushed on Feb 18, 2026
  16. fjahr commented at 1:55 PM on February 18, 2026: contributor

    @luke-jr

    Basically, the original PR interface was way better.

    Is this just about #34534 (review) or did you mean something else?

  17. fjahr commented at 1:55 PM on February 18, 2026: contributor

    Addressed feedback from @luke-jr and @bvbfan , thanks for the review!

  18. fjahr force-pushed on Feb 19, 2026
  19. sedited commented at 3:57 PM on March 18, 2026: contributor

    I can not recall who was mentioned as a potential user but I would appreciate if someone could ping them to take a look if this is still relevant to them.

    Do you remember at least who mentioned these users/use cases?

  20. sedited requested review from stickies-v on Mar 19, 2026
  21. stickies-v commented at 5:30 PM on March 19, 2026: contributor

    Unfortunately, I can not recall who was mentioned as a potential user but I would appreciate if someone could ping them to take a look if this is still relevant to them.

    This looks potentially interesting, but I don't think we should be implementing RPCs when we don't know anyone that would actually be using them? Since the previous PR has been open since 2020 already without users chiming in, it seems like there's no real demand for this?

  22. achow101 commented at 5:47 PM on March 19, 2026: member

    This is generally useful in the wallet and for any wallets that leverage Bitcoin Core. The fundamental issue is that if the wallet is not loaded while the node is running, blocks necessary for rescanning when the wallet is loaded may be pruned away. The wallet definitely should be using prune locks, but it's also necessary to have a way to for users to remove prune locks that are no longer relevant, e.g. if they unload a wallet that they don't plan to load on that node again. External wallets that use Bitcoin Core should also find this useful as they can then set prune locks that match the scan state of the external wallet.

  23. stickies-v commented at 10:10 AM on March 20, 2026: contributor

    Thanks for the explanation @achow101 . Concept ACK. Enabling wallets to build on top of a pruned node via RPC seems enough of a use case to move this forward. @fjahr I think this might be useful to include in PR description to give it more motivation?

  24. fjahr commented at 11:54 AM on March 20, 2026: contributor

    Thanks for the explanation @achow101 . Concept ACK. Enabling wallets to build on top of a pruned node via RPC seems enough of a use case to move this forward. @fjahr I think this might be useful to include in PR description to give it more motivation?

    Done, replace that vague part of the description with a better motivation paragraph.

  25. in src/rpc/blockchain.cpp:907 in 1f9cfa1a88
     902 | +    [&](const RPCHelpMan& self, const JSONRPCRequest& request) -> UniValue
     903 | +{
     904 | +    ChainstateManager& chainman = EnsureAnyChainman(request.context);
     905 | +    UniValue locks_arr(UniValue::VARR);
     906 | +    {
     907 | +        const auto prune_locks = WITH_LOCK(::cs_main, return chainman.m_blockman.GetPruneLocks());
    


    sedited commented at 11:41 AM on March 21, 2026:

    Don't we either have to hold this lock while iterating through the prune locks, or copy them? I think my preference would be to just take a copy here.


    fjahr commented at 1:41 PM on March 22, 2026:

    Hm, it certainly seems like I addressed this comment without thinking about it enough because the surrounding parentesis were unnecessary as well. I am now using a explicit unordered_map constructor now to ensure the copy happens before the lock scope ends and I have added a comment and removed the parenthesis.

  26. in src/node/blockstorage.h:461 in 22709b0adf outdated
     453 | @@ -454,6 +454,12 @@ class BlockManager
     454 |      //! Create or update a prune lock identified by its name
     455 |      void UpdatePruneLock(const std::string& name, const PruneLockInfo& lock_info) EXCLUSIVE_LOCKS_REQUIRED(::cs_main);
     456 |  
     457 | +    //! Delete a prune lock identified by its name. Returns true if the lock existed.
     458 | +    bool DeletePruneLock(const std::string& name) EXCLUSIVE_LOCKS_REQUIRED(::cs_main);
     459 | +
     460 | +    //! Return the current set of prune locks.
     461 | +    const std::unordered_map<std::string, PruneLockInfo>& GetPruneLocks() const EXCLUSIVE_LOCKS_REQUIRED(::cs_main) { return m_prune_locks; }
    


    sedited commented at 12:02 PM on March 21, 2026:

    Is there a reason for introducing this helper? Existing validation code that iterates through the locks directly.


    fjahr commented at 1:41 PM on March 22, 2026:

    m_prune_locks is private and the direct access to it in validation.cpp is only possible because ChainState is a friend class of BlockManager. Of course we could also just make it public but a getter method seemed nicer to me.

  27. sedited commented at 12:17 PM on March 21, 2026: contributor

    One thing that is still not clear to me is how this is actually useful to external applications if the locks are not persisted. I could see how this might be interesting for our own wallets, by setting prune locks for wallets even though they are not loaded yet. But for outside users this seems like a limitation that is difficult to deal with. If you want to add a wallet on startup, wouldn't that require racing to set a lock again if you restart? What is the exact scenario here?

  28. fjahr force-pushed on Mar 22, 2026
  29. fjahr commented at 1:41 PM on March 22, 2026: contributor

    Addressed latest @sedited feedback, thank you!

    One thing that is still not clear to me is how this is actually useful to external applications if the locks are not persisted. I could see how this might be interesting for our own wallets, by setting prune locks for wallets even though they are not loaded yet. But for outside users this seems like a limitation that is difficult to deal with. If you want to add a wallet on startup, wouldn't that require racing to set a lock again if you restart? What is the exact scenario here?

    First, I think we can agree that it's useful for long-running nodes and the internal wallet, right? So for the following I am still unsure if it should be included here or part of follow-up PR.

    For a node that is relaunched only every few weeks for usage of (cold-ish) wallet the persisted lock sounds useful. But I am not sure if just making the locks persistent is actually the best UI for this use-case. The pattern would probably be that the user, before shutdown, sets a prune lock to the last scan height (potentially the tip) and then shuts down. Then on restart the prune lock is respected. But then maybe it would actually be more convenient if there was a startup option -prunelocked or so where the node can be started with the current tip locked. It could get a height parameter too if an earlier height should be locked. I haven't spent much time thinking if this covers all the use-cases but so far I tend to think the startup option covers what I have in mind and comes with a few upsides: If the node crashes and the user couldn't set the lock before, with persistence they might be still screwed but with the startup option they are safe. And since we could avoid persistence this should be much easier to implement and have less code to maintain.

    EDIT: Also, for certain wallets that really need a lot of control, there is always the option to manually prune as well.

  30. sedited commented at 10:28 AM on March 25, 2026: contributor

    First, I think we can agree that it's useful for long-running nodes and the internal wallet, right? So for the following I am still unsure if it should be included here or part of follow-up PR.

    The case is still not quite clear to me to be honest. Would the wallet start tracking prune locks for unloaded wallets? Afaict it doesn't currently hold a lock during rescan - that does indeed seem like something useful. I can also see how deleting / cleaning up existing locks could be useful, though it also feels like bit of a footgun. I'm having a hard time thinking of a scenario where you can robustly race a node pruning and important an existing wallet / descriptor. The startup option does seem better to me too.

  31. fjahr commented at 1:34 PM on March 25, 2026: contributor

    The startup option does seem better to me too.

    Thanks, I have added a minimal implementation of the startup option because so far seems like a clearly useful feature to me if outside wallets want to use prune locks in any capacity. But conceptual feedback still very welcome!

    Would the wallet start tracking prune locks for unloaded wallets?

    I think so? I could see something like this become more common in the future when more users switch on pruning to avoid having to get a larger disk. I would expect there are wallet options that market themselves being compatible with (possibly aggressive) pruning on the node and that this option will become more common in the future. But of course it would be a stronger statement to hear from an implementer directly that they would use such a feature. I just looked at the sparrow docs as a start and they are rather "hands-off" so far and just warn about potential issues: https://sparrowwallet.com/docs/connect-node.html#pruned-nodes

  32. DrahtBot added the label Needs rebase on Mar 31, 2026
  33. fjahr force-pushed on Mar 31, 2026
  34. fjahr commented at 9:55 PM on March 31, 2026: contributor

    Rebased

  35. DrahtBot removed the label Needs rebase on Mar 31, 2026
  36. DrahtBot added the label Needs rebase on Apr 19, 2026
  37. fjahr force-pushed on Apr 19, 2026
  38. fjahr commented at 3:48 PM on April 19, 2026: contributor

    Rebased

  39. DrahtBot removed the label Needs rebase on Apr 19, 2026
  40. DrahtBot added the label Needs rebase on Apr 23, 2026
  41. fjahr force-pushed on Apr 23, 2026
  42. DrahtBot removed the label Needs rebase on Apr 23, 2026
  43. in src/rpc/blockchain.cpp:925 in 504c9064fa outdated
     917 | @@ -918,6 +918,119 @@ std::optional<int> GetPruneHeight(const BlockManager& blockman, const CChain& ch
     918 |      return CHECK_NONFATAL(first_unpruned.pprev)->nHeight;
     919 |  }
     920 |  
     921 | +static RPCMethod listprunelocks()
     922 | +{
     923 | +    return RPCMethod{"listprunelocks",
     924 | +        "Returns a list of all active prune locks.\n"
     925 | +        "Prune locks prevent block data at specific heights from being pruned.\n"
    


    sedited commented at 1:03 PM on April 23, 2026:

    Nit: Why not duplicate the description from setprunelock to describe their mechanics? The description here feels a bit incomplete, since it does not just prevent pruning at a single height.


    fjahr commented at 2:36 PM on April 23, 2026:

    Fair, I will address it the next time I touch this.


    fjahr commented at 2:16 PM on November 14, 2026:

    Addressed now in the latest push since @andrewtoth had a similar comment

  44. sedited approved
  45. sedited commented at 1:37 PM on April 23, 2026: contributor

    ACK 9465be6fd01138246337ec91745d08a65f7bea66

  46. sedited requested review from rkrux on May 22, 2026
  47. in src/init.cpp:530 in 9465be6fd0
     526 | @@ -527,6 +527,7 @@ void SetupServerArgs(ArgsManager& argsman, bool can_listen_ipc)
     527 |      argsman.AddArg("-prune=<n>", strprintf("Reduce storage requirements by enabling pruning (deleting) of old blocks. This allows the pruneblockchain RPC to be called to delete specific blocks and enables automatic pruning of old blocks if a target size in MiB is provided. This mode is incompatible with -txindex. "
     528 |              "Warning: Reverting this setting requires re-downloading the entire blockchain. "
     529 |              "(default: 0 = disable pruning blocks, 1 = allow manual pruning via RPC, >=%u = automatically prune block files to stay under the specified target size in MiB)", MIN_DISK_SPACE_FOR_BLOCK_FILES / 1_MiB), ArgsManager::ALLOW_ANY, OptionsCategory::OPTIONS);
     530 | +    argsman.AddArg("-prunelockheight=<n>", "If -prune is set, creates a prune lock at the specified block height to prevent block data at or above that height from being pruned. If set without a value or set to 0, locks at the current chain tip height at startup. ", ArgsManager::ALLOW_ANY, OptionsCategory::OPTIONS);
    


    rkrux commented at 2:56 PM on May 25, 2026:

    Can't there be a case wherein this new argument causes the -prune=<n> option to not be respected? If this has already been discussed before, please point me to that conversation.


    fjahr commented at 7:53 PM on May 25, 2026:

    Yes, unless I am misunderstanding your question that is the whole idea behind prune locks, to temporarily protect certain block ranges from pruning if there is some work left to do. I added that functionality here a few years ago with the initial goal to let indexes catch up without the necessary blocks disappearing suddenly if they are running on a pruned node. The basic discussion can be found there. This PR only allows to configure these prune locks via RPC which may be interesting for external wallets for example. Does that answer your question?


    rkrux commented at 1:55 PM on June 8, 2026:

    Sorry for the delay in getting back here, I should be able to get to it this week.


    rkrux commented at 11:41 AM on June 12, 2026:

    Ok, can add a sentence here that this option will cause the -prune option to not be respected - just to be explicit.


    fjahr commented at 9:48 PM on July 15, 2026:

    Good idea, done!

  48. rkrux commented at 2:59 PM on May 25, 2026: contributor

    Thanks for the review ping, I was not aware of this PR.

    I started looking and it looks interesting - also helpful if it can be leveraged by the wallet (or by external ones).

  49. in test/functional/rpc_prunelock.py:20 in 9465be6fd0 outdated
      15 | +)
      16 | +
      17 | +
      18 | +# Blocks needed to generate at minimum to allow pruning to work on
      19 | +# regtest (with fastprune).
      20 | +INITIAL_BLOCKS = 1500
    


    rkrux commented at 11:31 AM on June 12, 2026:

    Is this correct? The following diff passes where this value is halved along with the corresponding heights in the pruneblockchain RPCs.

    diff --git a/test/functional/rpc_prunelock.py b/test/functional/rpc_prunelock.py
    index a122a6164a..9a2dd5b6c2 100755
    --- a/test/functional/rpc_prunelock.py
    +++ b/test/functional/rpc_prunelock.py
    @@ -17,7 +17,7 @@ from test_framework.util import (
     
     # Blocks needed to generate at minimum to allow pruning to work on
     # regtest (with fastprune).
    -INITIAL_BLOCKS = 1500
    +INITIAL_BLOCKS = 750
     
     
     class PruneLockTest(BitcoinTestFramework):
    @@ -92,7 +92,7 @@ class PruneLockTest(BitcoinTestFramework):
                                 {"id": "rpc:protect_early"},
                                 {"height": 2})
     
    -        prune_height_locked = node.pruneblockchain(500)
    +        prune_height_locked = node.pruneblockchain(250)
             assert self.has_block_file(node, 0), "blk00000.dat should still exist with prune lock active"
     
             self.log.info("Test that removing the prune lock allows further pruning")
    @@ -101,7 +101,7 @@ class PruneLockTest(BitcoinTestFramework):
                                 {"id": "rpc:protect_early"}, {},
                                 should_not_find=True)
     
    -        prune_height_unlocked = node.pruneblockchain(500)
    +        prune_height_unlocked = node.pruneblockchain(250)
             assert_greater_than(prune_height_unlocked, prune_height_locked)
             assert not self.has_block_file(node, 0), "blk00000.dat should be pruned after lock removal"
     
    @@ -142,15 +142,15 @@ class PruneLockTest(BitcoinTestFramework):
             node = self.nodes[0]
     
             self.log.info("Test -prunelockheight with explicit height")
    -        self.restart_node(0, extra_args=["-prune=1", "-prunelockheight=500"])
    +        self.restart_node(0, extra_args=["-prune=1", "-prunelockheight=250"])
             assert_array_result(node.listprunelocks()["prune_locks"],
                                 {"id": "init"},
    -                            {"height": 500})
    +                            {"height": 250})
     
             self.log.info("Test -prunelockheight can coexist with RPC locks")
             node.setprunelock("mylock", "add", 100)
             locks = node.listprunelocks()["prune_locks"]
    -        assert_array_result(locks, {"id": "init"}, {"height": 500})
    +        assert_array_result(locks, {"id": "init"}, {"height": 250})
             assert_array_result(locks, {"id": "rpc:mylock"}, {"height": 100})
             node.setprunelock("mylock", "remove")
     
    
    

    Based it off of this conditional: https://github.com/bitcoin/bitcoin/blob/142e86a65c8a809911e37ead5ece63ad7854077e/src/kernel/chainparams.cpp#L603


    fjahr commented at 9:49 PM on July 15, 2026:

    Hm, for me the proposed diff fails because the blocks are not enough to get actual pruning. I am not sure why it would pass for you and not for me, it's possible that there is some dependency on filesystems but I usually try to tweak these values to the minimum that works reliably locally.

  50. in test/functional/rpc_prunelock.py:105 in 9465be6fd0
     100 | +        assert_array_result(node.listprunelocks()["prune_locks"],
     101 | +                            {"id": "rpc:protect_early"}, {},
     102 | +                            should_not_find=True)
     103 | +
     104 | +        prune_height_unlocked = node.pruneblockchain(500)
     105 | +        assert_greater_than(prune_height_unlocked, prune_height_locked)
    


    rkrux commented at 11:36 AM on June 12, 2026:

    prune_height_locked is -1 because the lock prevents the pruning from happening. I don't see much point in asserting that prune_height_unlocked is greater than prune_height_locked.


    fjahr commented at 9:49 PM on July 15, 2026:

    Changed this to check for -1 and >0 more explicitly now.

  51. in src/rpc/blockchain.cpp:1 in 9465be6fd0 outdated


    rkrux commented at 11:37 AM on June 12, 2026:

    The changes in this file require a release note because of new RPCs being added. Along with the new startup option.


    fjahr commented at 9:49 PM on July 15, 2026:

    Right, added the necessary release notes!

  52. in src/rpc/blockchain.cpp:1010 in 9465be6fd0 outdated
    1005 | +    if (command == "add") {
    1006 | +        const int height{request.params[2].isNull() ? 0 : request.params[2].getInt<int>()};
    1007 | +        if (height < 0) {
    1008 | +            throw JSONRPCError(RPC_INVALID_PARAMETER, "Block height must not be negative");
    1009 | +        }
    1010 | +
    


    rkrux commented at 11:40 AM on June 12, 2026:

    There isn't a check that forbids locking blocks that'd be generated in the future. Is it intentional? The following test change passes:

    -        node.setprunelock("testlock", "add", 100)
    +        node.setprunelock("testlock", "add", 1600)
             assert_array_result(node.listprunelocks()["prune_locks"],
                                 {"id": "rpc:testlock"},
    -                            {"height": 100})
    +                            {"height": 1600})
    

    fjahr commented at 9:49 PM on July 15, 2026:

    Right, that's a good observation, I didn't think about this explicitly so far but I don't see harm in allowing this and it may even be useful for some use-cases. So I tend to say I would keep allowing it and I have added a note in the docs on it. But if you (or other reviewers) strongly prefer these values to be rejected I can be convinced to do that as well.

  53. rkrux commented at 11:48 AM on June 12, 2026: contributor

    Overall, I feel this PR needs to market itself a bit. Either in the release notes or maybe a new section in the docs/ directory. I worry that this feature would be underutilised or, worse, unused because of lack of awareness. The motivation in the PR description and the use cases discussed in the PR comments previously can be listed there.

    From #34534 (comment):

    The fundamental issue is that if the wallet is not loaded while the node is running, blocks necessary for rescanning when the wallet is loaded may be pruned away. The wallet definitely should be using prune locks, but it's also necessary to have a way to for users to remove prune locks that are no longer relevant, e.g. if they unload a wallet that they don't plan to load on that node again.

    Also, a functional test for wallet exercising prune locks that solves the above scenario would be nice. Using prune locks temporarily instead of manually importing via importprunedfunds RPC (which requires the the proof via another RPC - gettxoutproof) seems like a more natural choice to me (can be a part of the motivation/marketing).

  54. fjahr force-pushed on Jul 15, 2026
  55. fjahr commented at 9:52 PM on July 15, 2026: contributor

    Addressed feedback by @rkrux , thanks a lot!

    I feel this PR needs to market itself a bit

    I added release notes per your inline comment

    a functional test for wallet exercising prune locks that solves the above scenario would be nice

    I added this in a separate commit. I folded it into the existing test file since generating all those blocks is pretty expensive and I didn't see this justifying a new functional test file. Let me know what you think.

  56. in doc/release-notes-34534.md:16 in 9fa4953f01
      11 | +New settings
      12 | +------------
      13 | +
      14 | +- The new `-prunelockheight=<n>` setting creates a prune lock at the given block
      15 | +  height at startup and requires `-prune` to be set. If no value is given, the lock is
      16 | +  placed at the chain tip height. (#34534)
    


    sedited commented at 9:30 PM on July 23, 2026:

    Maybe mention here that the lock may be viewed by listprunelockand removed by setprunelock.


    fjahr commented at 10:04 PM on July 28, 2026:

    Well, now that you say it.... the setprunelock removal part wasn't actually possible because of the forced rpc: prefix which the init option didn't use. I changed this and renamed the prefix to user: since it's not strictly used by RPCs anymore. Otherwise, removing the lock would have required a restart.

  57. sedited approved
  58. sedited commented at 9:31 PM on July 23, 2026: contributor

    Re-ACK 9fa4953f01cab3ab8669b316224b4eeb8433a8d8

  59. fjahr force-pushed on Jul 28, 2026
  60. sedited requested review from andrewtoth on Sep 9, 2026
  61. andrewtoth commented at 5:02 PM on September 9, 2026: contributor

    I'm not sure I find the motivation compelling. Would the same functionality be achieved via the pruneblockchain RPC and a -prune=1 setting? This way a user can have all their wallets sync, and then call pruneblockchain. Keeping the node running would not prune on its own.

  62. fjahr commented at 11:30 AM on September 13, 2026: contributor

    Would the same functionality be achieved via the pruneblockchain RPC and a -prune=1 setting?

    Partly yes, but I think it would be much more complex and difficult to implement managing that behavior on the side of an external wallet. With -prune=1 nothing is pruned unless pruneblockchain is called and to achieve some kind of constant disk usage threshold it needs to be called regularly. In order to decide when to prune the wallet would need to monitor disk usage constantly and then decide with which height to call pruneblockchain. It basically means the wallet has the burden to reimplement our automatic pruning logic, just to get that extra bit of control that the pull here provides. It gets even trickier if there are multiple consumers of RPC that need that pruning control, like a wallet and an external index, with management RPCs they both can set their locks as they need and it should be simple to implement that.

  63. sedited approved
  64. sedited commented at 10:37 AM on October 7, 2026: contributor

    Re-ACK 67960317cda01b102c5cbec7efb8ab56611b21a7

  65. shuv-amp commented at 2:09 PM on October 30, 2026: contributor

    The lock is registered here, but the startup prune at L1962–1972 already ran in Step 10. So restarting with -prune=550 -prunelockheight=H while block-file usage is above the target can delete the blocks the lock should keep, then sets the lock. Index prune locks don't have this problem because they're registered in Step 8, before the prune.

    The test diff below shows it on 67960317cd: it runs with -prune=550 -fastprune -prunelockheight=<tip+1> until usage is over the target, then restarts with the same args. The getblock on the locked height fails with Block not available (pruned data), and debug.log shows removed 63 blk/rev pairs before Initial prune lock set at height 2101. Moving the registration before Step 10 (after chainstate load so the tip is available for =0) makes the test pass for me.

    The PR's own rpc_prunelock.py doesn't catch this because it uses -prune=1, which never prunes automatically.

    <details><summary>diff</summary>

    diff --git a/test/functional/rpc_prunelock.py b/test/functional/rpc_prunelock.py
    index a6e8b7f..fc23fec 100755
    --- a/test/functional/rpc_prunelock.py
    +++ b/test/functional/rpc_prunelock.py
    @@ -6,6 +6,8 @@
     
     import os
     
    +from test_framework.blocktools import create_block, create_coinbase
    +from test_framework.script import CScript, OP_NOP, OP_RETURN
     from test_framework.test_framework import BitcoinTestFramework
     from test_framework.util import (
         assert_array_result,
    @@ -213,6 +215,20 @@ class PruneLockTest(BitcoinTestFramework):
                                 {"id": "user:init"}, {},
                                 should_not_find=True)
     
    +        self.log.info("Test the startup prune respects -prunelockheight")
    +        lock_args = ["-prune=550", "-fastprune", f"-prunelockheight={tip_height + 1}"]
    +        self.restart_node(0, extra_args=lock_args)
    +        big_script = CScript([OP_RETURN] + [OP_NOP] * 950000)
    +        best = node.getblockheader(node.getbestblockhash())
    +        prev = int(best["hash"], 16)
    +        for i in range(1, 651):
    +            block = create_block(prev, create_coinbase(tip_height + i, script_pubkey=big_script), ntime=best["time"] + i)
    +            block.solve()
    +            node.submitblock(block.serialize().hex())
    +            prev = block.hash_int
    +        self.restart_node(0, extra_args=lock_args)
    +        node.getblock(node.getblockhash(tip_height + 1))
    +
             self.log.info("Test -prunelockheight without -prune fails")
             self.stop_node(0)
             node.assert_start_raises_init_error(
    

    </details>

  66. fjahr force-pushed on Oct 31, 2026
  67. fjahr force-pushed on Oct 31, 2026
  68. DrahtBot added the label CI failed on Oct 31, 2026
  69. DrahtBot commented at 10:52 PM on October 31, 2026: contributor

    <!--85328a0da195eb286784d51f73fa0af9-->

    🚧 At least one of the CI tasks failed. <sub>Task iwyu: https://github.com/bitcoin/bitcoin/actions/runs/41248829209/job/124677834304</sub> <sub>LLM reason (✨ experimental): CI failed because IWYU reordered/added includes in src/rpc/blockchain.cpp, leaving a diff that the lint check rejects.</sub>

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

  70. blockstorage: Add GetPruneLocks to BlockManager
    This is needed in RPCs that manage prune locks manually.
    a85d65d348
  71. fjahr force-pushed on Oct 31, 2026
  72. fjahr commented at 11:11 PM on October 31, 2026: contributor

    The lock is registered here, but the startup prune at L1962–1972 already ran in Step 10.

    Good catch, thanks. Moved the lock add before the initial prune and added a minimal test that checks the debug log for it. Your suggested test seemed a bit too heavy for my taste.

    Also rebased and fixed a silent merge conflict.

  73. DrahtBot removed the label CI failed on Nov 1, 2026
  74. in src/rpc/blockchain.cpp:952 in 37e873e5aa
     944 | @@ -944,6 +945,121 @@ std::optional<int> GetPruneHeight(const BlockManager& blockman, const CChain& ch
     945 |      return CHECK_NONFATAL(first_unpruned.pprev)->nHeight;
     946 |  }
     947 |  
     948 | +static RPCMethod listprunelocks()
     949 | +{
     950 | +    return RPCMethod{"listprunelocks",
     951 | +        "Returns a list of all active prune locks.\n"
     952 | +        "Prune locks prevent block data at specific heights from being pruned.\n"
    


    andrewtoth commented at 8:52 PM on November 1, 2026:

    nit

            "Prune locks prevent block data at or above specific heights from being pruned.\n"
    

    fjahr commented at 2:17 PM on November 14, 2026:

    Done

  75. in src/rpc/blockchain.cpp:1001 in 37e873e5aa
     996 | +        "A prune lock prevents block data at or above the specified height from\n"
     997 | +        "being pruned. This can be used to ensure that blocks needed by external\n"
     998 | +        "applications remain available on disk for a certain amount of time.\n"
     999 | +        "\nNote: Manually created prune locks are stored in memory only and will\n"
    1000 | +        "not persist across node restarts.\n"
    1001 | +        "\nNote: The pruning mechanism operates on block files, not individual blocks.\n"
    


    andrewtoth commented at 8:55 PM on November 1, 2026:

    I think this second note can be struck. It describes an implementation detail that should have no effect on usage. To me it seems it doesn't give the user any useful information.


    fjahr commented at 2:17 PM on November 14, 2026:

    Removed

  76. in test/functional/rpc_prunelock.py:29 in 6810e48ec1
      24 | +    def set_test_params(self):
      25 | +        self.setup_clean_chain = True
      26 | +        self.num_nodes = 1
      27 | +        self.extra_args = [["-prune=1", "-fastprune"]]
      28 | +
      29 | +    def has_block_file(self, node, filenum):
    


    andrewtoth commented at 9:05 PM on November 1, 2026:

    The test framework has has_blockfile which could be used instead of this.


    fjahr commented at 2:18 PM on November 14, 2026:

    Ah, nice, replaced the helper with has_blockfile.

  77. in src/init.cpp:1039 in 3c7c4f78f2
    1035 | @@ -1035,6 +1036,11 @@ bool AppInitParameterInteraction(const ArgsManager& args)
    1036 |          }
    1037 |      }
    1038 |  
    1039 | +    // Check that prune mode is enabled if -prunelockheight is set
    


    andrewtoth commented at 9:07 PM on November 1, 2026:

    This comment doesn't seem to add any value here IMO.


    fjahr commented at 2:18 PM on November 14, 2026:

    Removed

  78. in src/init.cpp:2051 in 3c7c4f78f2
    2047 | @@ -2042,6 +2048,26 @@ bool AppInitMain(NodeContext& node, interfaces::BlockAndHeaderTipInfo* tip_info)
    2048 |      // if pruning, perform the initial blockstore prune
    2049 |      // after any wallet rescanning has taken place.
    2050 |      if (chainman.m_blockman.IsPruneMode()) {
    2051 | +        // Apply -prunelockheight startup option
    


    andrewtoth commented at 9:07 PM on November 1, 2026:

    Same with this comment. It doesn't seem necessary.


    fjahr commented at 2:18 PM on November 14, 2026:

    Removed

  79. in src/init.cpp:541 in 3c7c4f78f2
     537 | @@ -538,6 +538,7 @@ void SetupServerArgs(ArgsManager& argsman, bool can_listen_ipc)
     538 |      argsman.AddArg("-prune=<n>", strprintf("Reduce storage requirements by enabling pruning (deleting) of old blocks. This allows the pruneblockchain RPC to be called to delete specific blocks and enables automatic pruning of old blocks if a target size in MiB is provided. This mode is incompatible with -txindex. "
     539 |              "Warning: Reverting this setting requires re-downloading the entire blockchain. Wallets and indexes should be loaded at startup and kept active while pruning is enabled so they stay synchronized before old block data is deleted; wallets or indexes that fall behind pruned data may require a reindex. "
     540 |              "(default: 0 = disable pruning blocks, 1 = allow manual pruning via RPC, >=%u = automatically prune block files to stay under the specified target size in MiB)", MIN_DISK_SPACE_FOR_BLOCK_FILES / 1_MiB), ArgsManager::ALLOW_ANY, OptionsCategory::OPTIONS);
     541 | +    argsman.AddArg("-prunelockheight=<n>", "If -prune is set, creates a prune lock at the specified block height to prevent block data at or above that height from being pruned. If set without a value or set to 0, locks at the current chain tip height at startup. A prune lock can keep block files from being pruned, so the target size specified by -prune may be exceeded. The lock can be removed at runtime with the setprunelock RPC using the id \"init\".", ArgsManager::ALLOW_ANY, OptionsCategory::OPTIONS);
    


    andrewtoth commented at 9:13 PM on November 1, 2026:

    Hmm I think setting an explicit 0 value should set to genesis block, same as the RPC. What is the rationale for making 0 use tip? Using no-value to mean tip could make sense though.


    fjahr commented at 2:19 PM on November 14, 2026:

    With the latest push we now have -prunelock=<id> which doesn't take a height and always locks at height 0, so this comment should be obsolete.

  80. in doc/release-notes-34534.md:15 in c6814071d1
      10 | +
      11 | +New settings
      12 | +------------
      13 | +
      14 | +- The new `-prunelockheight=<n>` setting creates a prune lock at the given block
      15 | +  height at startup and requires `-prune` to be set. If no value is given, the lock is
    


    andrewtoth commented at 9:15 PM on November 1, 2026:

    The release notes also don't mention the 0 case meaning tip here.


    fjahr commented at 2:21 PM on November 14, 2026:

    Same reason as above, since there is no height parameter with the latest version this comment is obsolete.

  81. andrewtoth commented at 9:16 PM on November 1, 2026: contributor

    Concept ACK

  82. optout21 commented at 11:57 PM on November 3, 2026: contributor

    Concept ACK.

    A concrete use case for this: an Electrum server (electrs) backed by a pruned node. External indexers have only come up in passing here, so here is a data point.

    I prototyped a patched electrs on top of this PR and completed indexing on a pruned signet node (-prune=550). It uses the prune lock like this:

    • on connect, set a lock (user:electrs) at the first block not indexed yet, then remove the init lock
    • advance the lock after each index sync
    • across bitcoind restarts, -prunelockheight=<n> (at or below the indexed height) keeps the needed blocks until electrs reconnects and sets its lock again

    For this use case the startup option is enough, and locks don't need to be persisted. It does rely on the lock being in place before the startup prune (thanks for the fix in response to #34534 (comment)). The setup is resilient for either of the processes being stopped for a period.

    Out of scope here, but for context: there is a constraint in how the two processes are started (electrs has to be started before bitcoind starts to prune); relaxing this may require some new mechanism. Also, serving transactions from blocks that were pruned before indexing will need more work (an indexer-side concern).

    I'll review the code later.

  83. optout21 commented at 5:18 AM on November 8, 2026: contributor

    Concept ACK. Manual prune locks are needed to support external indexers on a pruned node. Some comments with that use case in mind:

    1. Initial lock. Its purpose is to keep the blocks an external app needs from being pruned while the app is not connected (not started yet, restarting, etc.). Rather than a general init lock, it could be the initial placement of the app's own lock, which the app then takes over. A height isn't needed either: the app controls the height, and until it connects the safest default is "don't prune anything". Suggestion: replace -prunelockheight=<n> with -prunelock=<id>, where <id> is the same id the app uses with setprunelock. When the app connects, its setprunelock call simply updates this lock, with no separate init lock to clean up. This way the app can safely remove or update "its" lock (with the same id). The option goes in the node's config file and stays there as long as the app is in use. It could be extended later with [:<height>], though I don't see a strict need for that now. The trade-off is that no pruning happens until the app connects, so disk usage can go above the -prune target for that time. (I briefly discussed this idea with the author offline.)

    2. Persistence. I agree that locks don't need to be persisted. If bitcoind starts with -prunelock=<id> and the app soon connects and calls setprunelock, the setup is robust. The app knows its own persisted state, and the node only has to make sure nothing is pruned while the app is away. Persisting locks would allow more fine-tuned pruning in some cases. For example: the indexer has reached height 800, blocks are pruned up to 600, and the node restarts before the indexer does. Without a persisted lock, the node cannot prune until the indexer reconnects, so disk usage grows. With one, it could prune roughly 600–799. But persistence adds complexity, such as having to remove stale persisted locks by hand.

    3. 0 meaning "tip" in -prunelockheight. In this PR, -prunelockheight=0 locks at the startup tip, while setprunelock <id> add 0 (also the default when height is omitted) locks at height 0, which means nothing is pruned. The same value has opposite meanings, and code that treats the lowest height as "keep everything" would use it the wrong way. The natural values are 0 for "keep everything" and "infinity" for "no lock" (height_first already defaults to max int). I'd use a separate value for "lock at the current tip", such as -1 or a named value like "tip". -1 has its own pitfalls (a negative number where heights are otherwise non-negative, and the current check that rejects negative heights). So I'd suggest named value "tip" in the RPC commands and max int in the internal representation for tip.

  84. rpc: Add setprunelock and listprunelocks
    These allow for manual management of prune locks by users and follow the UX pattern of setban/listbanned.
    
    Co-authored-by: Luke Dashjr <luke-jr+git@utopios.org>
    0a078767d3
  85. test: Add manual prune lock RPC coverage 395820fbb3
  86. init: Add -prunelock init option
    This allows to start a node with a prune lock already set in order to avoid racing with any unwanted pruning.
    3a99e7c09a
  87. doc: Add release note for prune lock RPCs and -prunelock 7ead178396
  88. test: Add prune lock coverage for an unloaded wallet e5411bf563
  89. fjahr force-pushed on Nov 14, 2026
  90. fjahr commented at 2:28 PM on November 14, 2026: contributor

    Addressed the feedback from @andrewtoth and @optout21, thanks for the reviews!

    The main change is that -prunelockheight=<n> is replaced by -prunelock=<id> in response to @optout21 's explicit use case description. The option creates a lock with the given id at height 0 before the startup prune, so nothing is pruned until the lock is updated or removed with setprunelock using the same id. It can be specified multiple times. This removes the "handover" of the init lock to the lock of the specific app, and it also works if more than one app needs a lock.

    Since it doesn't seem strictly necessary for the discussed use cases to have the explicit height or tip functionality, this is left out for now to keep things simple.


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-20 15:51 UTC

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