As far as i know that key pool gets refilled automatically with each address taken out of it. Why should i use keypoolrefill then ? What's the benefit of this command ?

  • At a guess: it refills automatically when it chooses to. keypoolrefill tells it to do it now.
    – Tim S.
    Mar 14 '14 at 17:41

Most people don't need to use keypoolrefill.

Bitcoin Core tries to fill the keypool to its configured maximum size whenever you take an address from the keypool. (It does not wait until the keypool is empty before regenerating it.) However, it isn't possible to add keys to the keypool unless the wallet is unlocked with walletpassphrase. So if you call getnewaddress 100 times (by default), your keypool will be empty and you will be prompted to unlock your wallet and run keypoolrefill. The same effect could be achieved by unlocking your wallet and then generating another address, which will also cause the keypool to be topped up.

Another use is if you want to temporarily increase the size of your keypool. For example, a really safe way of doing payment processing is to generate an encrypted wallet with a strong passphrase, generate thousands of keys using keypoolrefill 10000 or whatever, put this wallet on the live payment processing server, but only use the commands that don't require unlocking the wallet. Then even if the live server is compromised, the attacker can't steal the money because he can't unlock the wallet. This is similar to the idea of a watch-only wallet. You could do the same thing with the keypool setting, but I guess that restarting Bitcoin Core might be inconvenient in some cases.

Running Bitcoin with -keypool=0 and then only manually adjusting the keypool with keypoolresize might also be useful for some backup strategies, or if you have multiple servers using the same wallet (which is not recommended, but maybe possible if you're really careful).


If you believe that your databases files have been compromised at one time (which contain the key sets) it is a good idea to refill your keypool, so that attackers can't abuse any of the corrupted keys yet to be used by your Bitcoin client. You must do this of course before "transferring" any Bitcoins to newly requested addresses.

  • Refilling your keypool doesn't discard older keys in it.
    – theymos
    Nov 28 '14 at 2:20
  • @theymos Oh, my mistake. I'll delete this answer then, before someone uses it wrongly. But, then what was the command to generate an entirely new keypool and discard the old one (which could be used for a scenario like I described)?
    – Jori
    Nov 28 '14 at 10:33

Tim S. already alluded to this but it has to do with the performance penalty of a keypoolrefill. If you have a really large pool because you run a high volume site and don't want to frequently backup your wallet as an example you may want to run keypoolrefill at off-peak so as not to impact the performance of Bitcoind.

Otherwise keypoolrefill will run once the pool is exhausted which may happen at an inopportune time.

  • Bitcoin tries to keep your keypool topped up at all times. It doesn't wait until the keypool is empty to regenerate. If it did, that'd make the keypool completely pointless, since backups made right before the keypool was refilled would soon be missing some keys.
    – theymos
    Nov 28 '14 at 2:23
  • Looking at rpcwallet.cpp this doesn't seem to be true in all circumstances. If the wallet is locked it is possible to run through the available keys with getnewaddress without refilling. Check line 107. Maybe this is legacy functionality that changed? In any event it points at the real reason, which is simply to change the keypool size, and unlock -> refill an existing wallet. It seems like TopUpWallet is called automatically on unlocked wallets, so my reasoning about performance is wrong, I stand corrected.
    – Matt
    Nov 28 '14 at 3:06

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.