The Archaeologist (src/rev*.dat): Handling Reorgs and Undo Data

16. The Archaeologist (src/rev*.dat): Handling Reorgs and Undo Data

Bitcoin history is usually described as being "written in stone," but in reality, the very edge of the blockchain—the most recent few blocks—is more like "wet cement." Sometimes, the network needs to "erase" the last few minutes of history and try again because two different versions of the truth appeared at once. This process is called a Chain Reorganization (Reorg). The code in src/validation.cpp (working with the files in src/index/) acts as the Archaeologist. He is the one who manages the "Undo Data" (stored in files like rev00001.dat). He ensures that even if the network makes a mistake, it can safely "Roll Back" without losing anyone's money.

The Problem of the Race: When Two Miners Win

Imagine two miners, one in Iceland and one in Australia, find a new block at the exact same time.

1. The Conflict: Both blocks are perfectly valid according to the Watchman (Section 5).

2. The Split: Half the world (the nodes closer to Iceland) hears about the Iceland block first; the other half (closer to Australia) hears about the Australia block first.

3. The Divergence: For a few minutes, there are two competing "Realities." People on the Iceland chain think Transaction A happened; people on the Australia chain might not even know Transaction A exists.

This is where the Archaeologist comes in. He knows that in a decentralized world, disagreements are inevitable. He doesn't panic; he just prepares for the possibility that his current reality might be the "Wrong" one.

The Undo Files: The Digital Safety Net

To handle this, every time a new block is added to the ledger, the Librarian (Section 4) doesn't just write down the new balance. He creates an Undo File (`rev*.dat`).

```cpp // src/validation.cpp - The Archaeologist's "Undo" Mechanism bool DisconnectBlock(const CBlock& block, const CBlockIndex* pindex, CCoinsViewCache& view) { // 1. Open the 'Undo File' for this specific block height. // 2. Identify every coin that was "spent" in this block. // 3. Move those coins back from the "Spent" pile to the "Unspent" pile (UTXO set). // 4. Identify every coin that was "created" in this block. // 5. Delete those new coins from the database entirely. // 6. It's as if the last 10 minutes of history never occurred. } ```

The Non-Coder's Technical Deep Dive: Think of the Archaeologist as a meticulous forensic scientist. Every time a block arrives, he doesn't just change the ledger; he takes a high-resolution "Polaroid" of the entire financial state of the world before that block arrived. He puts this photo into a folder labeled "In case of Reorg."

If a miner in Iceland finds a second block on top of the first one, the Australia chain is now "Stale." The Australia nodes must perform a Reorg. They call the Archaeologist, who pulls out the Polaroid and says: "Okay, before that Australia block arrived, Bob had 10 BTC and Alice had 0. I'm erasing the transaction where Bob sent 5 to Alice and putting the money back in Bob's pocket."

This ability to "Un-spend" money safely is what allows Bitcoin to reach a global consensus without a central coordinator. It ensures that no matter how many "Races" happen, the network always settles on one single, absolute truth.

The "Deep Reorg" Fear: Why We Wait for Confirmations

This architectural choice is why exchanges ask you to wait for "3 Confirmations" or "6 Confirmations" before they let you trade your Bitcoin.

• The Risk: A 1-block reorg happens fairly often (maybe once a week).

• The Rarity: A 2-block reorg is very rare.

• The Impossible: A 6-block reorg would require a massive attack or a global internet failure. By waiting for 6 blocks, you are ensuring that the cement has "Dried." The Archaeologist can still undo it if he has to, but it becomes exponentially less likely with every new block that is piled on top.

Protecting the Memory: The Reorg and the Mempool

One of the most complex jobs for the Archaeologist is what to do with the "Erased" transactions. If the Australia block was erased, those transactions didn't technically "happen," but they were still valid transactions. The Archaeologist doesn't just delete them; he hands them back to the Memory Bank Manager (Section 12).

• The transactions are put back into the "Waiting Room" (Mempool).

• They wait for the new winning chain (the Iceland chain) to pick them up in the next block. This ensures that users don't have to "Resend" their money just because a miner lost a race. The system is self-healing.

Pruning and History: The Archaeologist's Limit

If you are running a "Pruned" node (Section 4), the Archaeologist has a limit. He eventually throws away the old "Undo" photos to save space. Usually, a pruned node keeps the last 288 blocks of undo data (about 2 days of history). This is enough to handle any realistic reorg. If the network tried to reorg more than 2 days of history (which has never happened), a pruned node would stop and ask the user to re-download the history, because it no longer has the "Polaroids" to undo that much data safely.

Summary of Section 16

The Archaeologist in src/validation.cpp is the guardian of "Finality." By maintaining a perfect, bit-for-bit record of how to undo every change to the ledger, he allows the Bitcoin network to be both fast and incredibly secure. He is the reason that, even in a world of chaotic global competition, the "Truth" of the Bitcoin ledger is always preserved and always verifiable.

---

(End of sections 1-16. Appending more...)