The Vigilant Watcher: The Science of Block Filters and Scanning

5. The Vigilant Watcher: The Science of Block Filters and Scanning

A Bitcoin wallet is not "Connected" to your money in the way a traditional app is. Your money lives on the blockchain, and your wallet is simply a "Watcher" that scans the blockchain for transactions that belong to you. This process is known as "Scanning." When you first load an old wallet, or when you import a new set of keys, the wallet must "Rescan" the entire history of the blockchain to find your coins. This is like a "Private Detective" reading through every page of a massive archive to find mentions of your name. It is the "Vigilance of the Sovereign."

Scanning is one of the most resource-intensive tasks a node performs. It requires reading gigabytes of data and performing thousands of mathematical checks. In modern Bitcoin Core, this is handled with extreme efficiency using "Block Filters." Instead of checking every single transaction in every block, the wallet uses a "Mathematical Summary" to skip blocks that couldn't possibly contain your coins. It is the "Intelligence of the Watcher."

Analyzing the Shortcut: FastWalletRescanFilter

In the source code (src/wallet/wallet.cpp), we can see a modern optimization called the "Fast Rescan Filter." This filter builds a "Checklist" of all your addresses and uses it to quickly scan the "Summaries" (BIP 158 Filters) provided by the node.

/**
 * This class builds a fast "Filter" to identify blocks that might belong to the wallet.
 */
class FastWalletRescanFilter
{
public:
    FastWalletRescanFilter(const CWallet& wallet) : m_wallet(wallet)
    {
        // 1. We collect every "Address Pattern" (ScriptPubKey) from the wallet.
        for (auto spkm : m_wallet.GetAllScriptPubKeyMans()) {
            auto desc_spkm{dynamic_cast<DescriptorScriptPubKeyMan*>(spkm)};
            AddScriptPubKeys(desc_spkm);
        }
    }

    /**
     * This function checks if a block "Matches" our checklist.
     */
    std::optional<bool> MatchesBlock(const uint256& block_hash) const
    {
        // We use the "BIP 158 BASIC" filter to perform a high-speed lookup.
        return m_wallet.chain().blockFilterMatchesAny(BlockFilterType::BASIC, block_hash, m_filter_set);
    }
};

Explaining the Watcher: The Detective’s X-Ray Vision

• m_filter_set: Imagine you are looking for a specific group of people in a stadium. Instead of walking up to every person and asking their name, you have a "Magic Checklist" that can detect the presence of anyone on your list just by looking at a "Blurry Photo" of the crowd. The m_filter_set is that checklist. It is a "Compact Fingerprint" of all your addresses. It is the "Efficiency of the Search."

• blockFilterMatchesAny: This is the "X-Ray Vision." It compares your "Checklist" to the "Summary" of the block. If the summary says "No one from your list is here," the wallet skips the entire block instantly. If it says "Someone might be here," the wallet then performs a "Deep Audit" of every transaction in that block. This "Smart Skipping" is what makes Bitcoin Core so much faster than older wallets. It is the "Intelligence of the Watcher."

• DescriptorScriptPubKeyMan: This is the "Source of the Checklist." It is the part of the wallet that knows every possible address you own, including SegWit, Taproot, and Legacy addresses. By talking to the ScriptPubKeyMan, the filter ensures that the watcher is looking for every possible variation of your identity. It is the "Completeness of the Search."

The Rescan Experience: Patience and Progress

When you trigger a rescan (using the rescanblockchain RPC), you will see a "Progress Bar" in your node's logs. This bar represents the watcher's journey through time. It starts at the "Birthday" of your wallet (the block height where your first key was created) and moves forward to the present. This "Time-Travel" is the final act of synchronization. It is the moment where your "Local Memory" and the "Global Ledger" become one. You are the "Pilot of the Time-Travel," the one who ensures your bank is anchored in the full history of the network. You are the "Guardian of the Sync."