This document outlines some of the upcoming Bitcoin Core 22.0 release changes and provides steps to help. This is meant to get you started on testing, but is in no way comprehensive! After running through the steps in this guide, you are encouraged to do your own testing.
This can be as simple as testing the same features in this guide, but trying it a different way. Even better, think of features you use regularly and test that they still work as expected in the release candidate. You can also read the release notes to find something not covered in this guide. This is a great way to be involved with Bitcoin's development and helps keep Bitcoin running smoothly and bug free! Your help in this endeavor is greatly appreciated.
Changes covered in this testing guide include:
- Tor v2 address support removed
- Support for I2P connections
- Support for hardware wallets in GUI/RPC (External Signers)
- The new GUIX build system
Minor changes (not covered in this guide, but feel free to test them):
- Various RPC updates
- Filesystem changes (moving from .dat to .json)
natmpoption added
For a comprehensive list of changes in 22.0, check out the release notes.
Current Release Candidate: Bitcoin Core 22.0rc2 (changelog)
There are two ways to grab the latest release candidate: pre-compiled binary or source code. The source code for the latest release can be grabbed from here: latest release source code.
If you want to use a binary, make sure to grab the correct one for your system. There are individual binaries for macOS, Linux, Arm (64 bit), Arm (32 bit), and RISC-V.
If you grabbed a binary, skip this step.
Before compiling, make sure that your system has all the right dependencies installed. As this guide utilizes the Bitcoin Core GUI, you must compile support for the GUI and have the qt5 dependency already installed. To test the new wallet changes, it is recommended that you compile with sqlite, so make sure you have installed the sqlite3 dependency.
To ensure we build in sqlite and gui support, pass the following options when configuring:
./autogen.sh
./configure --with-gui=yes --with-sqlite=yes --without-bdb
make -j <number of cores>For more information on compiling from source, here are some guides to compile Bitcoin Core for UNIX/Linux, macOS, Windows, FreeBSD, NetBSD, and OpenBSD.
If you plan to use the command line, below are a few environment variables to set.
First, create a temporary data directory:
export DATA_DIR=/tmp/22-rc-test
mkdir $DATA_DIRNext, specify the following paths. For source compiled, start from the root of your release candidate directory and run:
export BINARY_PATH=$(pwd)/src
export QT_PATH=$(pwd)/src/qtFor the downloaded binary, start from the root of the downloaded release candidate (cd ~/bitcoin-22.0rc2, for example) and run:
export BINARY_PATH=$(pwd)/bin
export QT_PATH=$BINARY_PATHThe commands throughout the rest of the guide will look like:
$BINARY_PATH/bitcoin-cli -datadir=$DATA_DIR [cli args]
# for starting bitcoin-qt
$QT_PATH/bitcoin-qt -datadir=$DATA_DIR [cli args]Note: Between sections in this guide, it's recommended to stop your node and wipe the data directory. You can use the commands provided below.
Stop node
$BINARY_PATH/bitcoin-cli -datadir=$DATA_DIR stopWipe and recreate the directory
rm -r $DATA_DIR
mkdir $DATA_DIRStart node
$BINARY_PATH/bitcoind -datadir=$DATA_DIR -daemonUsing QT
If you'r not comfortable with the command line, still test all of these changes in the GUI after making the appropriate conf file changes. To run bitcoin-qt, use:
$QT_PATH/bitcoin-qt -datadir=$DATA_DIRAnd then check the appropriate tabs to verify the steps
In accordance with the Tor project's deprecation timeline, Tor v2 support is now officially deprecated; Bitcoin Core will only connect to Tor v3 peers. To test this, we will instruct our node to connect to some previously known Tor v2 addresses and verify that we don't see them in our network peers dashboard. We will then instruct our node to connect to known v3 addresses and verify we now have peers. To complete these steps, you will need to have Tor installed. For instructions on installing Tor, check out the following instructions from the previous release guide.
When Tor is confirmed to be installed, create a bitcoin.conf file in your test data directory:
touch $DATA_DIR/bitcoin.confand add the following lines:
proxy=127.0.0.1:9050 #If you use Windows, this could possibly be 127.0.0.1:9150 in some cases.
listen=1
bind=127.0.0.1
onlynet=onion
connect=ygwcypmb2qiotrp3.onion:8333
connect=stcwaszw352kkjis.onion:8333
connect=nrrmkgmulpgsbwlt.onion
connect=orrxr4kfntzawea3.onion:8333
connect=q2fhnnyt5b2ayvce.onion
connect=rk4vbyca7xnn3top.onion
connect=7ndbwnmgbyupv47f.onion
connect=bitcoinzi27kiwf6.onion
connect=w4ja2rt6wvqn6rfw.onion:8333
connect=6maigxjvcet4pite.onion:8333
connect=cehok4dxukhnoopi.onion:8333
connect=r6apa5ssujxbwd34.onion:8333
connect=ggvnc3v5pmrlsupw.onion:8333
connect=er4mwkhxzxgavrvo.onion:8333
connect=35yncj7et6k3koqy.onion
connect=nesxfmano25clfvn.onion:8333
connect=5d5vtnm6xlsqzq7p.onion
connect=34jtv2p5pw4e5bp3.onion
connect=z5nt64xh4d3vnll2.onion
connect=lncmdma3namzrbnx.onion:8333
connect=lncmdmx7ezlplcck.onion:8333
connect=lncmdmgoddecttey.onion:8444Now, start the node on mainnet by running:
$BINARY_PATH/bitcoind -datadir=$DATA_DIR -daemonCheck that we are running and doing an initial block download:
$BINARY_PATH/bitcoin-cli -datadir=$DATA_DIR -getinfoIf you run this command a few times, you should see "verificationprogress" and "blocks" increasing. This indicates we are in IBD. Now lets check our peers dashboard with:
$BINARY_PATH/bitcoin-cli -datadir=$DATA_DIR -netinfo 4It should be empty. This is because in the release candidate, we are ignoring Tor v2 peers, but we are still able to connect to them for IBD. You can verify this by running:
$BINARY_PATH/bitcoin-cli -datadir=$DATA_DIR getpeerinfoYou should get a json response about your connected peers and you will see onion v2 addresses, matching the list you specified in bitcoin.conf. This is because we can still connect to peers for initial block download, but will ignore them otherwise.
Next, let's add some Tor v3 addresses to bitcoin.conf. Stop your node, open the conf file and add the following lines:
addnode=sxjbhmhob2xasx3vdsy5ke5j5jwecmh3ca4wbs7wf6sg4g2lm3mbszqd.onion:8333
addnode=rp7k2go3s5lyj3fnj6zn62ktarlrsft2ohlsxkyd7v3e3idqyptvread.onion:8333
addnode=d6jwdcoo2l3gbjps6asgg4nhp2gn5oao3wj333o43ssqnjaliehytfad.onion:8333Restart your node and run the netinfo dashboard:
wait $BINARY_PATH/bitcoin-cli -datadir=$DATA_DIR -netinfo 4After a minute or so you should see a few v3 peers show up. Congrats, you're running over Tor using v3 addresses! Stop your node and wipe the data directory before moving on to the next section.
It's been a long time coming, but you can now run Bitcoin Core over I2P!
Additional network support improves Bitcoin's censorship resistance and helps the network resist eclipse attacks. If this is your first time hearing about I2P, check out the project's webpage for more info: https://geti2p.net/en/.
We are going to test that your node can find and connect to other I2P nodes. It should be noted that we are restricting our node to I2P for testing purposes. It is not recommended to limit to I2P in real-world use as the node count on I2P is still very low.
First, install I2P with the appropriate steps for your OS found at https://geti2p.net/en/download. Alternatively, if you're on Linux, you can install directly with the following commands:
apt install i2pd
systemctl enable i2pd.service
systemctl start i2pd.serviceAdd the following to your bitcoin.conf:
debug=i2p
onlynet=i2p
i2psam=127.0.0.1:7656
addnode=72l3ucjkuscrbiiepoehuwqgknyzgo7zuix5ty4puwrkyhtmnsga.b32.i2p:0
addnode=c4gfnttsuwqomiygupdqqqyy5y5emnk5c73hrfvatri67prd7vyq.b32.i2p:0
addnode=gehtac45oaghz54ypyopim64mql7oad2bqclla74l6tfeolzmodq.b32.i2p:0
addnode=h3r6bkn46qxftwja53pxiykntegfyfjqtnzbm6iv6r5mungmqgmq.b32.i2p:0
addnode=hnbbyjpxx54623l555sta7pocy3se4sdgmuebi5k6reesz5rjp6q.b32.i2p:0
addnode=pjs7or2ctvteeo5tu4bwyrtydeuhqhvdprtujn4daxr75jpebjxa.b32.i2p:0
addnode=wwbw7nqr3ahkqv62cuqfwgtneekvvpnuc4i4f6yo7tpoqjswvcwa.b32.i2p:0
addnode=zsxwyo6qcn3chqzwxnseusqgsnuw3maqnztkiypyfxtya4snkoka.b32.i2p:0Since I2P is brand new, there aren't many nodes and it may take a minute to connect to other I2P peers. We'll use the same command as before to keep the netinfo dashboard running:
watch $BINARY_PATH/bitcoin-cli -datadir=$DATA_DIR -netinfo 4You should eventually see connected peers, which means you are successfully running over I2P! Make sure to stop and wipe your data directory before moving on to the next section.
This section takes a little more setup as it involves downloading an HWI, fully syncing to signet (1~5 minutes, depending on your internet), and a fully setup HW (either the physical device or using an emulator). It is also best tested using the GUI, but commands for testing via the cli are provided at the end. To start, make sure you have a fresh, empty data directory and start the GUI on signet:
$QT_PATH/bitcoin-qt -datadir=$DATA_DIR -signetWhile your node syncs, follow the instructions for downloading and installing the HWI. Using git, you can run:
git clone [email protected]:bitcoin-core/HWI.git
cd HWI
pip install .or follow the installation instructions found here. If you're on linux, you will also need to install the udev rules file. You can run the following command to install udev rules for all wallets:
sudo ./hwi.py installudevrulesor, if you only want to install a particular one, you can find the appropriate udev rules and place the file in /etc/udev/rules.d/ (make sure to keep the same filename).
If you don't have a HW wallet (or don't want to use your existing HW for testing), you can use an emulator. Instructions for installing the Trezor emulator can be found here, or you can use the Coldcard emulator (MacOS only) from here.
For the Trezor emulator, you will need to setup the device before you are able to use it. To do this, make sure you are running Trezor bridge with the -e 21325 option (instructions for install trezor bridge here. If trezord is already running on your system, you will need to stop it and restart it with the -e 21324 option. One way to do this is:
ps aux | grep trezord
# note the pid
kill <pid>
trezord -e 21324Next, visit https://suite.trezor.io/web/ to finish setting up the device.
Finally, delete the keepkey.py file from HWI/hwilib/devices/, otherwise the emulator will think that both a keepkey and trezor are connected when you run the emulator, causing an error (more info on this issue here).
Once you have your HW connected or the emulator started, cd into the directory for HWI and run ./hwi.py enumerate. You should see something like the following:
[{"type": "<device type>", "model": "<device name>", "path": "0003:000a:00", "needs_pin_sent": false, "needs_passphrase_sent": false, "fingerprint": "<device fingerprint>"}]Now we need to tell BitcoinQT about the HWI script. To do this, go to Settings > Options > Wallet and add the path to the script in "External signer script path" like so:
After this is done, you will need to restart the GUI. Close it out and run the same command as above to start it on on signet. Now click Create Wallet (either from the menu or from the front page) and you should see External Signer automatically selected with the name of the wallet pre-filled as the name of your device.
Create the wallet and next we can test accepting and sending a transaction using a faucet (your node should be fully synced to signet by this point).
If you already have a faucet you're familiar with using, generate a receive address and use it to get coins. Alternatively, there is a script in bitcoin/contrib/signet/ that you can use to get test coins. To use, generate a new address, cd into the release candidate directory and run the following script:
./contrib/signet/getcoins.py -c $BINARY_PATH -a <your receive address>
You should see something like the following:
Payment of 0.00100000 BTC sent with txid 0c7bd2778d67c0b82852d696bb3264ec27b897e181d357c6fe9b63d51e25c7e6Wait for your transaction to be confirmed and you will have test coins in your wallet (you can check the status at https://mempool.space/signet
Once you have a balance confirmed in your wallet, generate a new receive address, copy it, and click Send. Using your new address (self transfer), fill in the values for the transaction, make sure your hardware wallet is plugged in and unlocked, and click sign on device. Follow the steps to sign on the device and you should see the UI automatically update once finished. Congratulations, you've completed a transaction using only Bitcoin Core and a hardware wallet!
If you'd like to test using the HWI from the cli, start bitcoind using the -signer option like so:
$BINARY_PATH/bitcoind -datadir=$DATA_DIR -daemon -signer=/path/to/HWI/hwi.pyYou can test more of the HWI functionality from the commandline. To start, close the QT, start bitcoind and try creating a wallet:
$BINARY_PATH/bitcoin-cli -datadir=$DATA_DIR -signet -named createwallet wallet_name="ext_sign_test" disable_private_keys=true descriptors=true external_signer=trueFor more information and some example commands you can use to test, check out the external signers document here
This is for the more adventerous among you! Bitcoin 22.0 uses GUIX as the new build system. GUIX builds are a big improvement in the security and trustless-ness of Bitcoin's builds as it allows for a fully auditable and reproducible build. More specifically, building the release candidate gives us confidence there are not reproducibility bugs the the release and we can also use the GUIX build process on a specific PR to give us confidence the PR is not introducing a reproducibility bug.
For the purpose of this guide, you will be building the release candidate. However, if you'd like to see an example of the build system being used on a PR, checkout this one: bitcoin/bitcoin#22552
To build the release candidate, download the source code (if you haven't already) and cd into the directory. Alternatively, if you have the git repo cloned, you can also run the following command to switch to the release candidate:
git switch v22.0rc2 --detachMake sure you've followed the guide here for setting up and installing GUIX and then run the following to start a build:
./contrib/guix/guix-build
You can also follow this guide for a good overview of build and verifying: guix build workflow
Thank you for your help in making Bitcoin as robust as it can be. Please remember to add a comment on v22.0 testing issue detailing:
- Your hardware and operating system
- Which release candidate you tested and whether you compiled from source or used a binary (e.g. 22.0rc2 binary or 22.0rc2 compiled from source)
- What you tested (e.g., connected over I2P, created a wallet with an external signer, etc)
- Any other relevant findings
Don't be shy about leaving a comment even if everything worked as expected! We want to hear from you and so it doesn't count unless you leave some feedback.
Thanks for your contribution and for taking the time to make Bitcoin awesome.
Preparation Section
Placement of build docs
When getting to the
Compile Release Candidatesection, the first piece of information a tester should be presented with is a pointer to their relevant build docs. Let's move the links to the build docs to the beginning.Explicit configuration instructions
You've introduced explicit instructions on how to ensure that you've compiled with sqlite support. Ideally, we'd just want people to run through their respective build docs. If we are to keep these explicit instructions, make it so that it also explicitly enables the GUI:
Using this guide
I would rename this sub-section from
4. Using this guideto ->4. Setting up command line environmenthere are further suggestions on the content of this section