30.0 Release Candidate Testing Guide - bitcoin-core/bitcoin-devwiki GitHub Wiki

Testing Guide: Bitcoin Core 30.0 Release Candidate

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.

Overview

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:

Extra / lower priority:

For a comprehensive list of changes in Bitcoin Core 30.0, check out the release notes.

Preparation

This chapter outlines the steps to configure a proper testing environment. Skip to the tests

1. Working directory.

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_DIR

2. Obtain latest Release Candidate

Current 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.

2a. From source code

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)

2b. From pre-compiled binary

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)

3. Compile Release Candidate

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;

4. Obtain previous release

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.gz

5. Setting up testing environment

5.1 Create data directories

Create 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_29

5.2 Specify paths

Specify path for executable binary, which depend on your selection in step 2: compiling from source or using a pre-compiled binary.

5.2a From Source

If testing with v30 from compiled source, set:

export BINARY_PATH_30=$RC_TEST_DIR/bitcoin/build/bin

5.2b Pre-Compiled Binaries

If testing from v30 downloaded binaries, set:

export BINARY_PATH_30=$RC_TEST_DIR/bitcoin-30.0rc3/bin

5.3 Previous Release

Specify path for the executable binary from the previous release. e.g. for V29.1

export BINARY_PATH_29=$RC_TEST_DIR/bitcoin-29.1/bin

5.4 Create Aliases

To avoid specifying the data directory (-datadir=$DATA_DIR) on each command, create these aliases:

5.4.1 V30 Aliases

alias bitcoind30="$BINARY_PATH_30/bitcoind -datadir=$DATA_DIR_30"
alias bcli30="$BINARY_PATH_30/bitcoin-cli -datadir=$DATA_DIR_30"

5.4.2 Aliases for previous release

alias bitcoind29="$BINARY_PATH_29/bitcoind -datadir=$DATA_DIR_29"
alias bcli29="$BINARY_PATH_29/bitcoin-cli -datadir=$DATA_DIR_29"

5.4.3 Alias to cleanup the data directory

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;'

6 Verify setup

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 version

Expected 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.0

If the output of the commands is as expected, the testing environment is set up correctly to continue with this testing guide!

Tests

1. Policy

1.1 Datacarriersize increase

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=83

Note: starting the node with the datacarriersize parameter 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 -daemon

Note: The bitcoin node is stared without datacarriersize parameter, 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:

true

cleanup

bcli30 stop && datadir-cleanup

2. P2P and network changes

3. New bitcoin command

A 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

3.1 Testing new bitcoin command

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 version

Validate that the output is equal to:

Bitcoin Core daemon version v30.0rc3
Bitcoin Core RPC client version v30.0.0rc3

4. Install changes

4.1 New location of (some) binaries (source build)

Bitcoin 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
ls

Validate that among other directories there is a bin and a libexec directory, for example:

bin  lib  libexec  share

Open the libexec folder and validate it's contents:

cd $DATA_DIR_30/install_test/libexec
ls

Validate the output, the libexec folder should at least contain a test_bitcoin:

bitcoin-chainstate  bitcoin-gui  bitcoin-node  test_bitcoin  test_bitcoin-qt

Note: folder contents can deviate based on used build flags.

Cleanup:

datadir-cleanup

5. Updated RPC's

5.1 Bumpfee without BIP-125 signalling

The 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 -daemon

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")

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:

false

Use the bumpfee RPC to bump the fee for the transaction without BIP-125 signalling

bcli30 bumpfee $tx

Validate that the fee has increased without an error:

{
"txid": "..",
"origfee": 0.00000141,
"fee": 0.00000847,
"errors": [
]
}

Stop node and clean up

bcli30 stop && datadir-cleanup

6. Wallet

6.1 TRUC transactions

Support 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:

3

Verify 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 tx

Mine the block:

bcli30 -generate 1

Verify 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") 1

Stop node and clean up

bcli30 stop && datadir-cleanup

Extra / lower priority tests

7. Mining

7.1 IPC mining interface (experimental)

The 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 node

Validate 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.sock

clean up:

bcli30 -regtest stop

8. Indexes

8.1 Coinstatsindex change

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 stop

Validate that the folder /indexes/coinstats/ is created (command should return SUCCES)

if [ -d "$DATA_DIR_30/regtest/indexes/coinstats/" ]; then echo "SUCCESS"; fi

Run Bitcoin Core 30.0 with -coinstatsindex argument:

bitcoind30 -regtest -coinstatsindex -daemon
sleep 5
bcli30 -regtest stop

Validate 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"; fi

Output should be:

New Folder is created
Old folder is still present

clean up

datadir-cleanup

9 P2P and network changes

9.1 maxorphantx option removal.

In 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)"
fi

Check 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" 
fi

cleanup

bcli30 stop && datadir-cleanup

Feedback

Kudos 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.