How exactly does -rescan work?

26

6

-rescan is a command line argument that is passed to the bitcoin client after restoring wallet.dat from backup.

  1. Which files get recalculated?
  2. Which files does the rescan command read?
  3. Why is it a good practice to first download all the blocks, then rescan, and not the other way around? (as a comment on this answer suggests)

ripper234

Posted 2011-09-25T23:22:02.590

Reputation: 25 192

Answers

20

The bitcoin client stores, in the wallet, the transactions that affect coins it manages. If it sees a new transaction, it checks to see if that transaction affects any accounts stored in the wallet. If so, the wallet is updated. Similarly, if the chain is reorganized, the wallet is updated.

However, the client doesn't check to make sure the wallet is synchronized to the current block chain. To fix this, the rescan command can be used. This causes the client, on startup, to go through every single block it has downloaded, search for transactions affecting accounts in the wallet, and update the wallet's transaction store and balances to reflect that transaction.

There are a few cases when you definitely need to rescan. For example:

If you restore a backed up wallet, it will be missing any transactions in blocks you downloaded after you backed up the wallet. Since the client won't receive those blocks (since it already has them) the normal wallet update logic won't fix this. You will need to rescan.

If you modify your wallet, say by adding keys to it or removing transactions from it, the wallet update logic won't see the transactions. So if you use a program other than the client to modify your wallet, you will need to rescan.

Theoretically, it shouldn't matter whether you download all the blocks and then rescan or vice-versa. The client won't download blocks while it's rescanning. And newly-downloaded blocks should update the wallet anyway. The logic is basically that this ensures the rescan process sees the blocks containing any missing transactions, rather than the regular block update logic. (They should both work. But if you need to rescan, we know something's wrong anyway.)

David Schwartz

Posted 2011-09-25T23:22:02.590

Reputation: 46 931

will it block generating addresses, sending coins ?Pavel Niedoba 2019-09-11T11:33:01.573

5

As-of v0.3.21 the client will automatically rescan if the last block the wallet knew about is not the last block in the blockchain: http://bitcointalk.org/index.php?topic=6642.msg99812#msg99812

Stephen Gornick 2011-09-26T01:55:25.817

1

Also, using -checkblocks will verify the integrity of the entire blockchain: http://en.bitcoin.it/wiki/Running_Bitcoin

Stephen Gornick 2011-09-26T02:02:05.220

14

This is also useful if you are importing more than 1 private key into your wallet:

bitcoind importprivkey 1zbcvs.... "My Label" false
bitcoind importprivkey 1zbcvs.... "My Label" false
bitcoind importprivkey 1zbcvs.... "My Label" false
bitcoind stop

# One of the following
bitcoind -rescan 
bitcoin-qt -rescan

Andrew Burns

Posted 2011-09-25T23:22:02.590

Reputation: 601

very clever. never thought about it.Nick 2019-09-01T13:25:38.717