-
Notifications
You must be signed in to change notification settings - Fork 50
30.0 Release Candidate Testing Guide
For feedback on this guide, please visit this issue.
This document outlines some of the upcoming Bitcoin Core 30.0 release changes and provides steps to help test them. This guide is meant to be the starting point for experimentation and further testing, but is in no way comprehensive! After running through the steps in this guide, you are encouraged to do your own testing. To do additional tests 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-minimized! Your help in this endeavour is greatly appreciated.
The Bitcoin Core 30.0 release introduces a range of updates and improvements across networking, mempool policy, mining, RPCs, and overall system behaviour.
The guide describes how to test the following updates:
- 1.1 Datacarriersize increase(#32406)
- 3.1 Testing new bitcoin command (#31375)
- 4.1 New location of (some) binaries (source build) (#31679)
- 5.1 Bumpfee without BIP-125 signalling (#31953)
- 6.1 TRUC transactions (#32896)
Extra / lower priority:
- 7.1 IPC mining interface (Experimental) (#31098)
- 8.1 Coinstatsindex change (#30469)
- 9.1
maxorphantxoption removal (#31829)
For a comprehensive list of changes in Bitcoin Core 30.0, check out the release notes.
This chapter outlines the steps to configure a proper testing environment. Skip to the tests
Choose a directory to work from. Set the RC_TEST_DIR environment variable to the chosen directory for testing, e.g., export RC_TEST_DIR=~/rctesting. This designates a workspace/folder in your home directory (~) named rctesting for test-related files.
export RC_TEST_DIR=~/rctesting
mkdir $RC_TEST_DIR
cd $RC_TEST_DIRCurrent Release Candidate: Bitcoin Core 30.0rc3 (release-notes)
There are two ways to grab the latest release candidate: from source code or pre-compiled binary. Choose one of the two.
The source code for the release candidate can be obtained from the releases page, or by using git directly:
cd $RC_TEST_DIR
git clone https://github.com/bitcoin/bitcoin.git -b v30.0rc3 --depth 1
cd bitcoin(continue to step3 compile)
If using a pre-compiled binary is preferred, make sure to obtain the correct one for your systems architecture. When using the pre-compiled binary, extract the package to the folder set in RC_TEST_DIR. (example for x86_64-linux):
cd $RC_TEST_DIR
wget https://bitcoincore.org/bin/bitcoin-core-30.0/test.rc3/bitcoin-30.0rc3-x86_64-linux-gnu.tar.gz
tar xf bitcoin-30.0rc3-x86_64-linux-gnu.tar.gz(continue on step 4)
Note: This step is only needed when working from source
Before compiling, make sure that your system has all the correct dependencies installed (note the new Cap'n proto build dependency)
Compiling from source is highly dependent on your systems architecture and operating system. Refer to the Bitcoin Core compilation guide for details;
Some testing in this guide involves using previous releases such as v29.1.
Obtain the v29.1 binary from here and extract it to the folder set in RC_TEST_DIR, (example for V29.1 x86_64-linux):
cd $RC_TEST_DIR
wget https://bitcoincore.org/bin/bitcoin-core-29.1/bitcoin-29.1-x86_64-linux-gnu.tar.gz
tar xf bitcoin-29.1-x86_64-linux-gnu.tar.gzCreate temporary data directories for each version.
export DATA_DIR_30=/tmp/30-rc-test
mkdir $DATA_DIR_30
export DATA_DIR_29=/tmp/29-test
mkdir $DATA_DIR_29Specify path for executable binary, which depend on your selection in step 2: compiling from source or using a pre-compiled binary.
If testing with v30 from compiled source, set:
export BINARY_PATH_30=$RC_TEST_DIR/bitcoin/build/binIf testing from v30 downloaded binaries, set:
export BINARY_PATH_30=$RC_TEST_DIR/bitcoin-30.0rc3/binSpecify path for the executable binary from the previous release. e.g. for V29.1
export BINARY_PATH_29=$RC_TEST_DIR/bitcoin-29.1/binTo avoid specifying the data directory (-datadir=$DATA_DIR) on each command, create these aliases:
alias bitcoind30="$BINARY_PATH_30/bitcoind -datadir=$DATA_DIR_30"
alias bcli30="$BINARY_PATH_30/bitcoin-cli -datadir=$DATA_DIR_30"alias bitcoind29="$BINARY_PATH_29/bitcoind -datadir=$DATA_DIR_29"
alias bcli29="$BINARY_PATH_29/bitcoin-cli -datadir=$DATA_DIR_29"The alias datadir-cleanup is created to make resetting the data directory easier between tests.
alias datadir-cleanup='rm -r $DATA_DIR_30; mkdir $DATA_DIR_30; rm -r $DATA_DIR_29; mkdir $DATA_DIR_29;'Verify that all versions are correct (e.g. that there are no accidental duplicates):
bcli30 --version | grep version
bitcoind30 --version | grep version
bcli29 --version | grep version
bitcoind29 --version | grep versionExpected results:
Bitcoin Core RPC client version v30.0.0rc3
Bitcoin Core version v30.0.0rc3
Bitcoin Core RPC client version v29.1.0
Bitcoin Core version v29.1.0If the output of the commands is as expected, the testing environment is set up correctly to continue with this testing guide!
Bitcoin Core 30.0 has increased -datacarriersize to 100,000 by default, which effectively uncaps the limit (as the maximum transaction size limit will be hit first) #32406
First start Bitcoin Core 30.0 in regtest, datacarriersize of 83:
echo "regtest=1" > $DATA_DIR_30/bitcoin.conf
bitcoind30 -daemon -datacarriersize=83Note: starting the node with the
datacarriersizeparameter will result in a deprecation warning. That is expected and correct.
Generate new wallet, new address and mine 101 blocks:
bcli30 createwallet "satoshi"
bcli30 generatetoaddress 101 $(bcli30 getnewaddress)
coinbase_txid=$(bcli30 listunspent | jq -r ".[0].txid")Generate a new transaction with a OP_RETURN of >83
satoshi_address=$(bcli30 getnewaddress)
tx_opreturn=$(bcli30 createrawtransaction "[{\"txid\":\"$coinbase_txid\",\"vout\":0}]" \
"[{\"$satoshi_address\":49.99990000},{\"data\":\"6a4d50c3ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff\"}]")Sign and test the transaction
tx_op_return_signed=$(bcli30 signrawtransactionwithwallet $tx_opreturn | jq -r .hex)
bcli30 testmempoolaccept "[\"$tx_op_return_signed\"]"Validate that the output is equal to
[
{
"txid": "...",
"wtxid": "...",
"allowed": false,
"reject-reason": "datacarrier",
"reject-details": "datacarrier"
}
]Stop and restart the node with default datacarriersize
bcli30 stop
bitcoind30 -daemonNote: The bitcoin node is stared without
datacarriersizeparameter, default values are expected.
Retest the transaction:
bcli30 testmempoolaccept "[\"$tx_op_return_signed\"]" | jq -r ".[0].allowed"Validate that the transaction is now accepted, output should be equal to:
truecleanup
bcli30 stop && datadir-cleanupA new bitcoin command line tool has been introduced in Bitcoin Core 30.0 to make features more discoverable and convenient to use. The bitcoin tool just calls other executables and does not implement any functionality on its own. #31375
When downloading the pre-compiled Bitcoin Core 30.0 binary or compiling from source with default build flags, the new binary is added to the bin directory.
Validate basic functionality of new binary.
$BINARY_PATH_30/bitcoin -m node --version | grep version
$BINARY_PATH_30/bitcoin -m rpc --version | grep versionValidate that the output is equal to:
Bitcoin Core daemon version v30.0rc3
Bitcoin Core RPC client version v30.0.0rc3Bitcoin Core 30.0 introduces the folder libexec, this folder contains binaries that are not typically directly invoked by users. #31679
Note: This test is only for from source builds
cd $RC_TEST_DIR/bitcoin
cmake --install ./build/ --prefix $DATA_DIR_30/install_test
cd $DATA_DIR_30/install_test
lsValidate that among other directories there is a bin and a libexec directory, for example:
bin lib libexec shareOpen the libexec folder and validate it's contents:
cd $DATA_DIR_30/install_test/libexec
lsValidate the output, the libexec folder should at least contain a test_bitcoin:
bitcoin-chainstate bitcoin-gui bitcoin-node test_bitcoin test_bitcoin-qtNote: folder contents can deviate based on used build flags.
Cleanup:
datadir-cleanupThe RPCs psbtbumpfee and bumpfee allow a replacement under fullrbf and no longer require BIP-125 signalling. #31953
First start Bitcoin Core 30.0 in regtest:
echo "regtest=1" > $DATA_DIR_30/bitcoin.conf
bitcoind30 -daemonGenerate new wallet, new address and mine 101 blocks:
bcli30 createwallet "satoshi"
bcli30 generatetoaddress 101 $(bcli30 getnewaddress)
coinbase_txid=$(bcli30 listunspent | jq -r ".[0].txid")Create a transaction with low fee, without BIP 125 signaling (replaceable=false))
satoshi_address=$(bcli30 getnewaddress)
tx=$(bcli30 -named sendtoaddress address=$satoshi_address amount=1 fee_rate=1 replaceable=false)
bcli30 getmempoolentry $tx | jq -r ".\"bip125-replaceable\""Validate that the output is false:
falseUse the bumpfee RPC to bump the fee for the transaction without BIP-125 signalling
bcli30 bumpfee $txValidate that the fee has increased without an error:
{
"txid": "..",
"origfee": 0.00000141,
"fee": 0.00000847,
"errors": [
]
}Stop node and clean up
bcli30 stop && datadir-cleanupSupport has been added for spending TRUC transactions received by the wallet, as well as creating TRUC transactions. The wallet ensures that TRUC policy rules are being met. The wallet will throw an error if the user is trying to spend TRUC utxos with utxos of other versions. Additionally, the wallet will treat unconfirmed TRUC sibling transactions as mempool conflicts. The wallet will also ensure that transactions spending TRUC utxos meet the required size restrictions.#32896
First start Bitcoin Core 30.0 in regtest:
echo "regtest=1" > $DATA_DIR_30/bitcoin.conf
bitcoind30 -daemon Create and fund the wallet:
bcli30 createwallet "satoshi"
bcli30 generatetoaddress 101 $(bcli30 getnewaddress)
coinbase_txid=$(bcli30 listunspent | jq -r ".[0].txid")Create a TRUC transaction:
TRUC_address=$(bcli30 getnewaddress)
tx=$(bcli30 -named send outputs='{"'$TRUC_address'": 3}' fee_rate=25 version=3)Validate that a version 3 transaction has been made :
bcli30 getrawtransaction $(echo $tx|jq -r ".txid") 1 | jq -r ".version"Output should be:
3Verify that you cannot create a transaction with an unconfirmed TRUC transaction using a version 2 child.
TRUC_address2=$(bcli30 getnewaddress)
tx2=$(bcli30 -named send outputs='{"'$TRUC_address2'": 0.5}' options='{"inputs":[{"txid":"'$(echo $tx|jq -r ".txid")'","vout":0}]}' fee_rate=25 version=2)Error message should be:
error code: -4
error message:
Can't spend unconfirmed version 3 pre-selected input with a version 2 txMine the block:
bcli30 -generate 1Verify that the TRUC transaction is now spendable, create the transaction:
tx2=$(bcli30 -named send outputs='{"'$TRUC_address2'": 0.5}' options='{"inputs":[{"txid":"'$(echo $tx|jq -r ".txid")'","vout":0}]}' fee_rate=25 version=2)Check that the transaction is in the mempool:
bcli30 getrawtransaction $(echo $tx2|jq -r ".txid") 1Stop node and clean up
bcli30 stop && datadir-cleanupThe new bitcoin command does support one new feature: an (experimental) IPC Mining Interface that allows the node to work with Stratum v2 or other mining client software #31098.
Test that the new binary (bitcoin-node) will start and open an unix socket. Run the new bitcoin binary with the following arguments and check for a unix socket creation:
$BINARY_PATH_30/bitcoin node -regtest -datadir=$DATA_DIR_30 -ipcbind=unix -daemon
command -v netstat >/dev/null 2>&1 && netstat -f unix | grep node | grep node || ss -ax | grep nodeValidate that the output in the Addr/Local Address column contains the following, indicating that the node has indeed created a Unix socket:
/tmp/30-rc-test/regtest/node.sockclean up:
bcli30 -regtest stop
The implementation of coinstatsindex was changed to prevent an overflow bug that could already be observed on the default Signet. The new version of the index will need to be synced from scratch when starting the upgraded node for the first time. The new version is stored in /indexes/coinstatsindex/ in contrast to the old version which was stored at /indexes/coinstats/.
Start the previous version to generate the "old folder" /indexes/coinstats/ in the v30 data dir:
$BINARY_PATH_29/bitcoind -datadir=$DATA_DIR_30 -regtest -coinstatsindex -daemon
sleep 5
$BINARY_PATH_29/bitcoin-cli -datadir=$DATA_DIR_30 -regtest stopValidate that the folder /indexes/coinstats/ is created (command should return SUCCES)
if [ -d "$DATA_DIR_30/regtest/indexes/coinstats/" ]; then echo "SUCCESS"; fiRun Bitcoin Core 30.0 with -coinstatsindex argument:
bitcoind30 -regtest -coinstatsindex -daemon
sleep 5
bcli30 -regtest stopValidate that the new folder is created and old folder is still present:
if [ -d "$DATA_DIR_30/regtest/indexes/coinstatsindex/" ]; then echo "New Folder is created"; fi
if [ -d "$DATA_DIR_30/regtest/indexes/coinstats/" ]; then echo "Old folder is still present"; fiOutput should be:
New Folder is created
Old folder is still presentclean up
datadir-cleanupIn Bitcoin Core 30.0, the -maxorphantx option no longer has any effect, since the orphanage no longer limits the number of unique transactions. Users should remove this configuration option if they were using it, as the setting will cause an error in future versions when it is no longer recognized. #31829
Start Bitcoin Core 30 node, with -maxorphantx parameter:
echo "regtest=1" > $DATA_DIR_30/bitcoin.conf
if bitcoind30 -maxorphantx=50 -daemon 2>&1 | tee /tmp/bitcoind_output.log; then
echo "bitcoind started (shows deprecation warning)"
fiCheck if the deprecation warning is in the log:
if grep -i "Option '-maxorphantx" $DATA_DIR_30/regtest/debug.log | tail -5; then
echo ""
echo "Found maxorphantx references in debug log"
ficleanup
bcli30 stop && datadir-cleanupKudos if you made it this far 👏🎉
Thanks for your contribution and for taking the time to make this Bitcoin release awesome.
For feedback on this guide, please visit this issue.