Bitcoin Core

From Whonix
Jump to navigation Jump to search
Bitcoin Core Logo

Using Bitcoin Core in Whonix. Fully verifying a Bitcoin wallet. Based on the original reference code by Satoshi Nakamoto.

Bitcoin Logo


Documentation for this is incomplete. Contributions are happily considered! See this for potential alternatives.

Software Origin[edit]

Bitcoin Core is the client software directly descended from the original Bitcoin software client first released by Satoshi Nakamoto. Bitcoin Core consists of both "full-node" software which can fully validate the blockchain, as well as a Bitcoin wallet. [1] The official open source project that maintains and releases the software can be found (.oniononion). The project also maintains related software such as cryptographic libraries on GitHub.

Bitcoin Wallet Recommendation[edit]

It is impossible to provide a blanket recommendation regarding which Bitcoin wallet to use. This is an individual decision that depends upon:

  • technical skill
  • personal risk assignment
  • financial value in Bitcoin
  • available time
  • various other factors

Other bitcoin wallets like Electrum may have better usability, but they also come with their own issues; see Electrum Warnings for example. Despite Bitcoin Core limitations it should be seriously considered for security reasons because it is the official Bitcoin client, particularly if transacting with Bitcoin accounts of significant financial value. Relative strengths include:

  • developed by the Bitcoin Core development team
  • most peer reviewed
  • most conservative, security-focused development
  • reproducible builds [2]
  • full validating node
    • transactions are validated against the complete blockchain - this lowers the probability of servers 'lying' to the client (the client has a higher probability of seeing its true Bitcoin balance)
  • higher privacy
    • all blocks are downloaded - the locally running node will not tell servers which wallet addresses belong to the node

Unfortunately, it takes a very long time to download and verify the blockchain. A large amount of disk space is also required, which may or may not be more manageable by using Bitcoin pruning mode.

Bitcoin Core Usability[edit]

Compared to Electrum, some things are more difficult in Bitcoin Core such as:

  • Simple backups - unfortunately Bitcoin Core does not support mnemonic phrase backup.
  • Wallet configuration - it is not easy to set up a split offline wallet (cold storage) and online watch only wallet. However since Bitcoin Core v23.0 descriptor wallets are the default wallet type and makes it much easier to create an offline/air gap setup:

[OFFLINE PC]: Create a wallet and export descriptors

  1. WindowConsole


[ONLINE PC]: Create a watch-only wallet and import descriptors:

  1. WindowConsole


After importing descriptors, the watch-only wallet will be functional, allowing you to create receiving addresses and create unsigned transactions. Unsigned transactions are copied by default to the clipboard but can also be saved in a .PSBT file (Partially signed bitcoin transaction) which can be transferred to the offline PC in order to sign. After signing just transfer the signed .PSBT file to the online PC to broadcast the transaction.

Another way to do this activities are likely possible, but are undocumented here; refer to the footnotes for possible information sources. [3]

Bitcoin Core Setup[edit]


Perform these steps inside Whonix-Workstation (Qubes-Whonix: anon-whonix App Qube).

1. Note.

The installation process is unspecific to Whonix.

2. Retrieve, verify and add a signing key or multiple signing keys.

Note: Any alternative method could be used. This is unspecific to Whonix. The following method is available for convenience. [4]

gpg --import /usr/share/gpg-bash-lib/misc/bitcoind-pub-keys.d/*

3. Check version number.

24.0.1 is used below. Was up to date at time of writing. Might be a different version now. Adjust the commands below accordingly. Useful resources to read:

4. Download the signed hash sum file.


5. Download the signed hash sum signature.


6. Download Bitcoin.


7. Verify the hash sum digital signature.

gpg --verify SHA256SUMS.asc

If the hash sum digital signature is correct, the output will include a statement the signature is good:

Good signature

This output might be followed by a warning as follows.

gpg: WARNING: This key is not certified with a trusted signature!
gpg:          There is no indication that the signature belongs to the owner.

This message does not alter the validity of the signature related to the downloaded key. Rather, this warning refers to the level of trust placed in the Whonix signing key and the web of trust. To remove this warning, the Whonix signing key must be personally signed with your own key.

8. Perform a hash sum check.

sha256sum --check --ignore-missing SHA256SUMS

Expected output.

bitcoin-24.0.1-x86_64-linux-gnu.tar.gz: OK

9. Extract the tar file.

tar xvf bitcoin-24.0.1-x86_64-linux-gnu.tar.gz

10. Done.

Download, digital signature verification and extraction of Bitcoin Core is complete.

Enable Stream Isolation[edit]

1. Optional: Disable networking for the virtual machine.

This step is optional but recommended to ensure stream isolation is always used from the first connection. This step can be omitted if:

  • A) The Whonix transparent proxy feature has been disabled; [5] and/or
  • B) Proxy settings are configured using the Bitcoin Core configuration file ~/.bitcoin/bitcoin.conf before the first start. [6]

2. Start Bitcoin-Qt as documented further below.

3. Enable Stream Isolation in the client.

  • A) navigate to the client settings
  • B) locate the Network tab
  • C) enable the SOCKS5 proxy (default proxy) as follows:
    • Proxy IP:
    • Port: 9111

4. Re-enable networking for the virtual machine.

Add a bitcoin-qt Start Menu Entry[edit]

Perform the following steps to create a bitcoin-qt start menu entry; this procedure is optional.

Inside Whonix-Workstation (Qubes-Whonix: anon-whonix App Qube).

1. Create folder ~/.local/share/applications.

mkdir -p ~/.local/share/applications

2. Open file ~/.local/share/applications/bitcoin.desktop in an editor as a regular, non-root user.

mousepad ~/.local/share/applications/bitcoin.desktop

3. Paste the following contents.

[Desktop Entry] Name=bitcoin-qt Comment=bitcoin-qt Exec=bash -c '~/bitcoin-*/bin/bitcoin-qt' Terminal=false Type=Application Icon=money-manager-ex StartupWMClass=bitcoin MimeType=x-scheme-handler/bitcoin; Categories=Finance;

4. Save.

5. Qubes-Whonix: perform platform-specific steps.

In dom0, refresh Qubes' appmenu: VM settingsApplicationsRefresh ApplicationsAdd desktop shortcut.

6. Done.

The bitcoin-qt start menu entry should now be available.

Autostart bitcoin-qt[edit]

Perform these steps to automatically start bitcoin-qt; this step is optional.

Inside Whonix-Workstation (Qubes-Whonix: anon-whonix App Qube).

1. Apply the Add a bitcoin-qt Start Menu Entry instructions first.

2. Create folder ~/.config/autostart.

mkdir -p ~/.config/autostart

3. Create a symlink from ~/.local/share/applications/bitcoin.desktop to ~/.config/autostart/bitcoin.desktop.

ln -s ~/.local/share/applications/bitcoin.desktop ~/.config/autostart/bitcoin.desktop

4. Done.

bitcoin-qt will now automatically start the next time the VM is booted.

Start from Command Line[edit]

To start bitcoin-qt (part of Bitcoin Core) from the command line, run.


Creating a Watch-Only Wallet[edit]

  1. Start bitcoin-qt.
  2. WindowConsole
  3. Import address.

Note: replace address with the actual address to be watched.

importaddress address

Tor Control Protocol[edit]

Info COMMUNITY SUPPORT ONLY : THIS wiki CHAPTER only is only supported by the community. Whonix developers are very unlikely to provide free support for this content. See Community Support for further information, including implications and possible alternatives.

TODO: document what this is useful for

Tor control protocol access to Bitcoin Core can be optionally enabled.

1. Note.

Optional. It is not mandatory to use this. Bitcoin Core works without this.

2. Warning.

If using this, see onion-grater: a Tor Control Port Filter Proxy chapter onion-grater Warning.

3. Enable.

Extend the onion-grater whitelist in Whonix-Gateway (sys-whonix).

On Whonix-Gateway.

Add onion-grater profile.

sudo onion-grater-add 40_bitcoind.yml

4. Additional information.

Probably only needed in case of issues.

5. Done.

The process of enabling Tor control protocol access to Bitcoin Core has been completed.

See Also[edit]


After installing a Bitcoin client, please consider making a donation to Whonix to help keep it running for many years to come.

Bitcoin accepted here Donate Bitcoin (BTC) to Whonix.



  2. Special warning about as a trusted reference: While good to have a compilation of reproducible binaries, if nobody is auditing the build procedure, then it becomes a blind spot. Bitcoin core is reproducible and extensive work was made with guix sigs.

    One example that is not reproducible building from source is Sparrow wallet, which is listed on the site of the first post - deterministic build, differences in modules · Issue #192 · sparrowwallet/sparrow · GitHub. Observing the video of the reproducible build, made by the same person in Github Issue #192 it is noticeable that the entire folder is not compared, only a single file. If comparing the whole folder, which has more binaries, there would be a diff from the released binaries and the built ones

    In short:

    Bitcoin Core is reproducible but linking to bitcoinbinary(dot)org, is unfortunate, as the process of submitting new software to that page is not investigated, it is just accepted.

    Paraphrased from forum user nyxnor's post

  3. Non-Endorsement: these links have not been audited by Whonix, but are worthy of further investigation:
  4. Thanks to for Add example showcasing how multiple signatures can be!
  5. Because then Bitcoin Core cannot connect using transparent proxying anyhow.
  6. As part of the ElectrumX#Bitcoin-Qt_Configuration instructions.

We believe security software like Whonix needs to remain open source and independent. Would you help sustain and grow the project? Learn more about our 12 year success story and maybe DONATE!