Update for Core version v22.0.0: There appears to be a bug when reading the dumptxoutset file from Core version v22.0.0. Previous version of Core work fine.

Project Overview

A new feature in Bitcoin Core 0.20 allows users to dump the state of the blockchain (the UTXO set) using the command dumptxoutset. I've written a python script utxo-live.py that takes the ouput of dumptxoutset and generates a heatmap of the blockchain via the UTXO set. Thus all of the active bitcoin in the blockchain is visualized in a single image from your own node.

Figure description: The heatmap is a two dimensional histogram showing the output date (x-axis), BTC amount (y-axis), and number of unspent outputs (color map) in each histogram bin. The BTC amounts on the y-axis are log scale and there are 100 bins in each log decade (e.g. 100 bins between 1 and 10 BTC). The bin size of output dates is one day. Zooming in to the image usually reveals more detail. A daily updating version of this image is running at utxo.live.

Privacy & Security

With the new dumptxouset command, the python script no longer requires an RPC password to access Core's databases. The script simply reads the dump file without interacting with Core at all. No private keys, passwords, xpubs, or wallet addresses are exchanged between Core and the python script.

Requirements

• Bitcoin Core version 0.20 or higher
• Python3 (comes standard on all operating systems)

Instructions for experienced users

• Create a folder called utxo-live in a familiar location
• Dump the utxo set bitcoin-cli dumptxoutset <path to utxo-live>/xxxxxx.dat where xxxxxxx is the current block height (10-20 min) (Note: bitcoin-cli doesn't ship with Core on Mac OS, use Window->Console instead)
• Install two python dependencies python3 -m pip install numpy matplotlib
• Download utxo-live.py to your utxo-live folder and run it python3 utxo-live.py (20 min)

Step by step instructions

1. Make sure Bitcoin Core (version 0.20 or higher) is running and synchronized.

2. Create a new folder called utxo-live in a familiar location on your machine (e.g. in your Documents folder).

3. Open a terminal window and display the current folder path. Do this by:

• Windows: open a terminal (Start -> Command Prompt) and type:

echo %cd%

• Mac/Linux: open a terminal (Mac: Applications -> Utilities -> Terminal) and type:

pwd

4. Navigate to the utxo-live folder using the change directory cd command. For example if you're currently in Users/Steve/ (or on Windows C:\Users\Steve\) and you've created the folder Steve/Documents/bitcoin-tools/utxo-live/ then type:

cd Document/bitcoin-tools/utxo-live/

Note: Windows sometimes requires forward slashes / instead of back slashes \.

5. Again display the current folder (Step 3) and copy to your clipboard the full path to the utxo-live folder. We will be pasting this path into Bitcoin Core soon.

6. Leave the terminal window momentarily, and open the Bitcoin Core console window. (Alternatively for bitcoin-cli users, open another terminal window and type the console commands in the next steps as bitcoin-cli commands.)

7. Get the current block count by typing in the console window:

getblockcount

and hitting enter. The output will look like:

8. Dump the current utxo set by typing in the console window:

  dumptxoutset <PATH to utxo-live>/<xxxxxx.dat>

where <PATH to utxo-live> is copy-pasted from Step 5, and <xxxxxx.dat> is the block count. For example if the block count is 678505, the command (for my path) is:

  dumptxoutset /Users/Steve/Documents/bitcoin-tools/utxo-live/678505.dat

If there are no error messages after hitting enter, then it's working. It will take 10-20 minutes. Look in your utxo-live folder and you should see the file being created as xxxxxx.dat.incomplete.

9. While the utxo file is dumping, download utxo-live.py and install two python dependencies. To do this:

• Right click on utxo-live.py, choose "Save Link As" and select the utxo-live folder.

• In the terminal window (not the Bitcoin console), type the following command to install two python dependencies:

  python3 -m pip install numpy matplotlib

Note: you might already have these installed, but running the command won't hurt anything.

10. If 10-20 minutes have passed, check that the utxo dump is completed. Do this in two ways:

• Check that the file no longer has .incomplete after xxxxxx.dat
• Check that the Bitcoin Core console displays the results of the dump as something like:

11. If the dump file is finished and Step 9 is completed (utxo-live.py is downloaded and python dependencies were installed), then run utxo-live.py by typing in the terminal:

  python3 utxo-live.py

12. The program will take 20-30 minutes to complete and it will update you on the progress. If there are multiple xxxxxxx.dat files in the folder, it will ask you which one you'd like to process. When finished the image is stored in the folder as utxo_heatmap_xxxxxx.png.

Acknowledgements

I'm indebted to three main projects for the code, understanding, and inspiration for this project. The python functions that parse and decode the utxo dump file were adapted from Bitcoin_Tools. I learned how Core serializes utxos from Bitcoin-UTXO-Dump . An inspiring project that visualizes changes in the UTXO set as a movie is BitcoinUtxoVisualizer .