Skip to content

29.0 Release Candidate Testing Guide

Jump to bottom
Jan B edited this page Apr 5, 2025 · 30 revisions

Testing Guide: Bitcoin Core 29.0 Release Candidate

For feedback on this guide, please visit this issue.

This document outlines some of the upcoming Bitcoin Core 29.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 29.0 release introduces a range of updates and improvements across networking, mempool policy, mining, RPCs, and overall system behaviour. This release removes support for UPnP in favour of NAT-PMP/PCP, refines transaction orphan handling for better reliability, and introduces ephemeral dust in order to defer committing to fees. Various RPCs have been updated with enhanced error reporting and new data fields, while the block size handling bug affecting reserved weight has been fixed. Additionally, the removal of the mempoolfullrbf option standardizes full replace-by-fee behaviour. The guide describes how to test the following updates:

  1. P2P and Network Changes:

  2. Mempool Policy and Mining Changes:

  3. Updated RPCs:

  4. New RPCs:

  5. Updated REST APIs:

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

Preparation

Choose a directory to work from, for example:

export RC_TEST_DIR=~/rctesting
mkdir $RC_TEST_DIR
cd $RC_TEST_DIR

1. Obtain Latest Release Candidate

Current Release Candidate: Bitcoin Core 29.0rc3 (release-notes)

There are two ways to grab the latest release candidate: source code or pre-compiled binary. Choose one of the two.

From Source

The source code for the release candidate can be obtained from the releases page (and extracted), or by using git directly:

cd $RC_TEST_DIR
git clone https://github.com/bitcoin/bitcoin.git -b v29.0rc3 --depth 1
cd bitcoin

(Ensure source is present in RC_TEST_DIR/bitcoin in either instance (run mv if necessary)).

From Binary

If using a binary is preferred, make sure to obtain the correct one for your system. When working from binary, extract (example for x86_64):

cd $RC_TEST_DIR
wget https://bitcoincore.org/bin/bitcoin-core-29.0/test.rc3/bitcoin-29.0rc3-x86_64-apple-darwin.tar.gz
tar xf bitcoin-29.0rc3-x86_64-apple-darwin.tar.gz

(Directory $RC_TEST_DIR/bitcoin-29.0rc3/ now exists)

2. Compile Release Candidate

If testing v29 from binary (rather than building from source), skip this step

Before compiling, make sure that your system has all the correct dependencies installed.

For more information on compiling from source, here are some guides to compile Bitcoin Core for UNIX/Linux, macOS, Windows, FreeBSD, NetBSD, and OpenBSD.

3. Obtain Previous Release

Some testing in this guide involves using previous releases such as v28.1.

Obtain the v28.1 binary from here and extract within RC_TEST_DIR:

cd $RC_TEST_DIR
wget https://bitcoincore.org/bin/bitcoin-core-28.1/bitcoin-28.1-x86_64-apple-darwin.tar.gz
tar xf bitcoin-28.1-x86_64-apple-darwin.tar.gz
(directory $RC_TEST_DIR/bitcoin-28.1 now exists)

4. Setting up command line environment

Create data directories

Create temporary data directories for each version.

export DATA_DIR_29=/tmp/29-rc-test
mkdir $DATA_DIR_29
export DATA_DIR_28=/tmp/28-test
mkdir $DATA_DIR_28

Specify paths

Define paths containing binaries that will be executed.

v29 from Source

If testing with v29 compiled source, run:

export BINARY_PATH_29=$RC_TEST_DIR/bitcoin/build/bin

v29 Pre-Compiled Binaries

If testing from v29 downloaded binaries, run:

export BINARY_PATH_29=$RC_TEST_DIR/bitcoin-29.0rc3/bin

Previous Release

Specify the binary path for the v28.1 binary.

export BINARY_PATH_28=$RC_TEST_DIR/bitcoin-28.1/bin

Create Aliases

To avoid specifying the data directory (-datadir=$DATA_DIR) on each command, below are a few extra variables to set.

v29 Aliases

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

Aliases for Previous Release

alias bitcoind28="$BINARY_PATH_28/bitcoind -datadir=$DATA_DIR_28"
alias bcli28="$BINARY_PATH_28/bitcoin-cli -datadir=$DATA_DIR_28"

Alias for Datadir cleanup

datadir-cleanup is created to make cleaning easier between tests.

alias datadir-cleanup='rm -r $DATA_DIR_29; mkdir $DATA_DIR_29; rm -r $DATA_DIR_28; mkdir $DATA_DIR_28;'

Verify Aliases

Verify that all versions are correct (e.g. that there are no accidental duplicates):

bcli29 --version | grep version
bitcoind29 --version | grep version
bcli28 --version | grep version
bitcoind28 --version | grep version

Expected results:

Bitcoin Core RPC client version v29.0.0rc3
Bitcoin Core version v29.0.0rc3
Bitcoin Core RPC client version v28.1.0
Bitcoin Core version v28.1.0

Command Execution

Throughout the rest of the guide, command execution will look similar to the following:

When using RPC:

bcli29 [cli args]

Starting a node in the foreground:

bitcoind29

Use CTRL-C to stop a node running in the foreground.

Note: When starting a node, allow a few seconds to pass (e.g. 10 seconds) for the node to listen for RPC before running subsequent bcli commands

For the rest of the guide, bitcoind will be started in daemon mode (-daemonwait) and as such CTRL-C will not stop the process. Instead, use bcli stop.

Tests

1. P2P and Network Changes

Bitcoin Core 29.0 introduces several updates to its peer-to-peer (P2P) and networking functionality. These changes include the removal of UPnP in favour of a more modern NAT-PMP/PCP implementation, a shift in how onion listening ports are assigned, and enhanced handling of orphan transactions

1.1 Dropped UPnP support & mini-upnp dependency

Support for UPnP has been removed from this release, the user will get a warning to use '-natpmp=true' (#31130)

Start the Bitcoin Core 29.0 node by running the following command:

bitcoind29 -upnp

Stop the node by pressing ctrl + c and check the output for the warning:

2025-MM-DDT20:43:44Z [warning] Option '-upnp=true' is given but UPnP support was dropped in version 29.0. Substituting '-natpmp=true'.

1.2 Added support for PCP & IPv6 pinholing

Libnatpmp was replaced with a custom implementation of PCP and NAT-PMP. This supports automatic IPv4 port forwarding as well as IPv6 pinholing. (#30043)

Please test this change against your home router and share all results, whether positive or negative here.

Start the Bitcoin Core 29.0 node by running the following command:

bitcoind29 -regtest -natpmp=1 -debug=net

Check the log/output for either failing PCP requests, eg:

[net] pcp: Requesting port mapping for addr xxx port xxx from gateway xxx
[net] pcp: Internal address after connect: xxx
[net:warning] pcp: Could not receive response: Connection refused (61)

Note: (optional) in case of failure, check if you need to manually enable PCP support in your router's configuration

Or successful PCP requests, eg:

 [net] portmap: gateway [IPv4]: 192.168.0.1
 [net] pcp: Requesting port mapping for addr 0.0.0.0 port 8333 from gateway 192.168.0.1
 [net] pcp: Internal address after connect: 192.168.0.150
 [net] pcp: Received response of 8 bytes: (scrubbed)
 [net] portmap: Got unsupported PCP version response, falling back to NAT-PMP
 [net] natpmp: Requesting port mapping port 8333 from gateway 192.168.0.1
 [net] natpmp: Received response of 12 bytes: (scrubbed)
 [net] natpmp: Received response of 16 bytes: (scrubbed)
 [net:info] portmap: Added mapping natpmp:(scrubbed) -> 192.168.0.150:8333 (for 2400s)
 [net] portmap: gateway [IPv6]: (scrubbed)
 [net] pcp: Requesting port mapping for addr (scrubbed) port 8333 from gateway (scrubbed)
 [net] pcp: Internal address after connect: (scrubbed)

2. Mempool Policy and Mining Changes

2.1 New startup option -blockreservedweight

In versions lower than release V29.0, a bug set the default reserved weight for block headers and transactions at 8,000 WU, limiting actual block sizes to 3,992,000 WU. The fix introduces a new option, -blockreservedweight, defaulting to 8,000 WU for compatibility. (31384)
Setting this option to a value lower than 2000 WU or higher than 4,000,000 WU will cause Bitcoin Core to fail to start.

Use the following commands to set the incorrect value and start Bitcoin core:

echo "blockreservedweight=4000001" > $DATA_DIR_29/bitcoin.conf
bitcoind29 -regtest

Check that Bitcoin core fails to start and returns the following error:

Error: Specified -blockreservedweight (4000001) exceeds consensus maximum block weight (4000000)

Use the following commands to set the incorrect value and start Bitcoin core:

echo "blockreservedweight=1999" > $DATA_DIR_29/bitcoin.conf
bitcoind29 -regtest

Check that Bitcoin core fails to start and returns the following error:

Error: Specified -blockreservedweight (1999) is lower than minimum safety value of (2000)

For completeness, check if a valid setting does not block Bitcoin core from starting

echo "blockreservedweight=4001" > $DATA_DIR_29/bitcoin.conf
bitcoind29 -regtest

Cleanup:

datadir-cleanup

2.2 Relay transaction packages containing ephemeral dust

An ephemeral dust output is a small output (below the dust treshold) that is created in a v3 zero-fee transaction and spent in a subsequent v3 transaction. The two transactions must be part of the same package. The output is ephemeral because it is both created and spent simultaneously. (30239)

Get some regtest coins

Change the bitcoin.conf file to run on regtest.

echo "regtest=1" > $DATA_DIR_29/bitcoin.conf

Start the bitcoind session

bitcoind29 -daemon

Create a wallet

bcli29 -regtest createwallet ephemeral_dust
{
  "name": "ephemeral_dust"
}

Mine 101 blocks.

bcli29 -regtest generatetoaddress 101 $(bcli29 -regtest getnewaddress)
[
  # ... 101 hashes are displayed ...
]

We now have one regtest spendable UTXO and we can get the id of the transaction that generated it.

coinbase_txid=$(bcli29 -regtest listunspent | jq -r ".[0].txid")
echo $coinbase_txid
f20d0afe42fbda3e53d6b07dc3f0358af275685471f053c2fd46d4fa023123f3
Create an ephemeral dust output

We need two new addresses: one for the dust output and one to which the coins will be sent.

dust_address=$(bcli29 -regtest getnewaddress)
coins_address=$(bcli29 -regtest getnewaddress)
echo $dust_address
echo $coins_address
bcrt1q8laca583j8wfeu8pcyjej2dtaajrcrg7urvra8
bcrt1q8e5vlev9tvphtxpz7y2tat239u5j6c9ly30w2p

We now create a zero-fee transaction spending our UTXO. The transaction has one zero-amount output (the ephemeral dust output) and a change output.

tx1_v2=$(bcli29 -regtest createrawtransaction "[{\"txid\":\"$coinbase_txid\",\"vout\":0}]" \
    "[{\"$dust_address\":0},{\"$coins_address\":50}]")
echo $tx1_v2
0200000001f3233102fad446fdc253f071546875f28a35f0c37db0d6533edafb42fe0a0df20000000000fdffffff0200000000000000001600143ffb8ed0f191dc9cf0e1c1259929abef643c0d1e00f2052a010000001600143e68cfe5855b03759822f114bead512f292d60bf00000000

This is a v2 transaction but we need a v3 transaction. The format of the transaction remains the same, we only change the version bits by replacing the first two digits with "03".

tx1="03${tx1_v2:2}"
echo $tx1
0300000001f3233102fad446fdc253f071546875f28a35f0c37db0d6533edafb42fe0a0df20000000000fdffffff0200000000000000001600143ffb8ed0f191dc9cf0e1c1259929abef643c0d1e00f2052a010000001600143e68cfe5855b03759822f114bead512f292d60bf00000000
Destroy ephemeral dust

We decode the previously created transaction to get the transaction id and the scriptPubKey hex value, that are required in the next steps.

tx1_decoded=$(bcli29 -regtest decoderawtransaction $tx1)
tx1_txid=$(echo $tx1_decoded | jq -r .txid)
tx1_script_dust=$(echo $tx1_decoded | jq -r ".vout[0].scriptPubKey.hex")
tx1_script_coins=$(echo $tx1_decoded | jq -r ".vout[1].scriptPubKey.hex")
echo $tx1_txid
echo $tx1_script_dust
echo $tx1_script_coins
33b70932a641432488cab448910c6ec2cec931daec7365a2c69de88427fafc22
00143ffb8ed0f191dc9cf0e1c1259929abef643c0d1e
00143e68cfe5855b03759822f114bead512f292d60bf

We now want to spend these transaction outputs. The child transaction must also spend the ephemeral dust to be accepted. We spend both outputs of the previous transaction and we add a fee that will pay for the entire package. Also in this case, we need to convert to a v3 transaction.

tx2_v2=$(bcli29 -regtest createrawtransaction "[{\"txid\":\"$tx1_txid\",\"vout\":0},{\"txid\":\"$tx1_txid\",\"vout\":1}]" "[{\"$coins_address\":49.995}]")
tx2="03${tx2_v2:2}"
echo $tx2
030000000222fcfa2784e89dc6a26573ecda31c9cec26e0c9148b4ca88244341a63209b7330000000000fdffffff22fcfa2784e89dc6a26573ecda31c9cec26e0c9148b4ca88244341a63209b7330100000000fdffffff01e050fe29010000001600143e68cfe5855b03759822f114bead512f292d60bf00000000
Signing

We sign the first transaction:

tx1_signed=$(bcli29 -regtest signrawtransactionwithwallet $tx1 | jq -r .hex)
echo $tx1_signed
03000000000101f3233102fad446fdc253f071546875f28a35f0c37db0d6533edafb42fe0a0df20000000000fdffffff0200000000000000001600143ffb8ed0f191dc9cf0e1c1259929abef643c0d1e00f2052a010000001600143e68cfe5855b03759822f114bead512f292d60bf0247304402202f1e1a53fa11b593853f1535114243ff628ae71a8b769a5f0ffd5e0e8e576df402200cf126817b74e860fb11bc45147776f0757689dcd4ea760061e6504fa1fcb07c0121026efaada55665a9ce205c78764d5c42c802af1134eca662fbc118f5846aa95a8e00000000

And we sign the second transaction, by also providing the txid, vout, scriptPubKey and amount of the outputs of the first transaction.

tx2_signed=$(bcli29 -regtest signrawtransactionwithwallet $tx2 \
"[{\"txid\":\"$tx1_txid\",\"vout\":0,\"scriptPubKey\":\"$tx1_script_dust\",\"amount\":0},{\"txid\":\"$tx1_txid\",\"vout\":1,\"scriptPubKey\":\"$tx1_script_coins\",\"amount\":50}]" | jq -r .hex)
echo $tx2_signed
0300000000010222fcfa2784e89dc6a26573ecda31c9cec26e0c9148b4ca88244341a63209b7330000000000fdffffff22fcfa2784e89dc6a26573ecda31c9cec26e0c9148b4ca88244341a63209b7330100000000fdffffff01e050fe29010000001600143e68cfe5855b03759822f114bead512f292d60bf02473044022044a9a0c25309a7a09a4bb2731e3a4f31b4e22eb5af96b59e5395488b33126a8b02206d19e1e147193c2fad2189f19fa7f8802e6822892acad5935557d69e7683d63a012103ebd3fcba8eccdbfca60ae343d209b3132d9ef7d4f341f3214cc6fc44d8d216db024730440220019ff3cb31afcad56c6fee55194b2c35c50205ae2d3e4c6dfcc76cc737e067a60220691a56b43f6706be4af520c86e07aabe7257770022ac22d4b4378a6e5d1774c70121036ae7ee47b4a9575f2f5b4977650806b22389c98bde5a29f725af4435877f460600000000

We now try to submit the package containing the two signed transactions to the mempool:

bcli29 -regtest submitpackage "[\"$tx1_signed\",\"$tx2_signed\"]"
{
  "package_msg": "success",
  "tx-results": {
    "570cc77a1a3a981418c67feba39625b5b650f97aa106e0cfab14fbd1b6920143": {
      "txid": "33b70932a641432488cab448910c6ec2cec931daec7365a2c69de88427fafc22",
      "vsize": 141,
      "fees": {
        "base": 0.00000000,
        "effective-feerate": 0.01572327,
        "effective-includes": [
          "570cc77a1a3a981418c67feba39625b5b650f97aa106e0cfab14fbd1b6920143",
          "72893787a375f8d1fb8deed8b461855beb199463ba8e0d008e98d973198f01db"
        ]
      }
    },
    "72893787a375f8d1fb8deed8b461855beb199463ba8e0d008e98d973198f01db": {
      "txid": "8d328bede7afe34dc92a6f4bc9ff1398faa75883d0c85fe8cf04b6489bff901e",
      "vsize": 177,
      "fees": {
        "base": 0.00500000,
        "effective-feerate": 0.01572327,
        "effective-includes": [
          "570cc77a1a3a981418c67feba39625b5b650f97aa106e0cfab14fbd1b6920143",
          "72893787a375f8d1fb8deed8b461855beb199463ba8e0d008e98d973198f01db"
        ]
      }
    }
  },
  "replaced-transactions": [
  ]
}

The same command on Bitcoin 28.1 would have failed with a result similar to the following:

{
  "package_msg": "transaction failed",
  "tx-results": {
    "a57fc569502539603d4ac2b675b35c51f63a62d0cc028434040cff199236ecdc": {
      "txid": "e13f9b8c6cc2fe52f3ceae7d651d138a48b1adcbb4046513bddd6cce31c3f612",
      "error": "dust"
    },
    "770b84163ed471e335ec188b7000b7d5dd774b7927d52c012b5a63bdabf2c7e9": {
      "txid": "d9b1e72acd02f3f63b82f4dc37603e3840b5f107271f2a58b77d2e42de5c6fde",
      "error": "bad-txns-inputs-missingorspent"
    }
  },
  "replaced-transactions": [
  ]
}
Cleanup
bcli29 -regtest stop && datadir-cleanup
Ideas for further testing:
  • try with v2 transansactions (one of them is enough): the package should be rejected
  • add another non-dust output to the first transaction: the package should be accepted
  • add another dust output to the first transaction: the package should be rejected
  • in the second transaction, do not spend the ephemeral dust: the package should be rejected
  • add a fee to the first transaction, the package should be rejected
  • use a Pay-To-Anchor script in the dust output: the package should be accepted

3. Updated RPCs

3.1 Enhanced RPC Response: testmempoolaccept Now Includes Reject Details

Bitcoin core 29.0 introduces verbose reject-details field in testmempoolaccept rpc for some of the reject reasons . One of the reject reason is insufficient-fee with a detailed reject-details response. ((#28121))

Steps to Test

Start the Bitcoin Core 29.0 in regtest

echo "regtest=1" > $DATA_DIR_29/bitcoin.conf
bitcoind29 -daemon

Create a new wallet for testing purposes

bcli29 createwallet "satoshi"                                        
{
  "name": "satoshi"
}

Generate a newaddress and mine 101 blocks:

bcli29 generatetoaddress 101 $(bcli29 getnewaddress)
[
  "15a3b270b902b8f1dad72a9359bafa015403a39017d5e89aee2a146b2dfbb7c1",
  "6a15b3e6466f4cdb4086aee7d867b9362b094310f353754b17a46bd6815b2fa9",
  "425dfacc96a0bd11047b510e270db7225a68584cb738c4928e008bce483cfdeb",
  "7f1b86b1adbb6bd0a692d468d55324fe7aa4c907ac272a872c8888384127610c",
  "35dda0d7c82bc0c2ee7ed0b91e9cfe139f7121a40f575b97d479992f96fa3f1f",
  "3c80eec99e82846740fbbbb508f34f170427bdcf87bdbc7e73f4bf5681cc616e",
  ...
 ]

Verify that the number of blocks on regtest is now 101

bcli29 getblockcount 
101

Verify that your wallet has some BTC to spend. You can either use getwalletinfo or getbalance rpc to check this.

bcli29 getbalance
50.00000000

You will now have a UTXO to spend which can be seen using listunspent rpc

coinbase_txid=$(bcli29 listunspent | jq -r ".[0].txid")
echo $coinbase_txid
dae8cb45e38ddadb46d1542341a11b8ad67363c643259033ef604e1eb7631f4a

Now we will create a transaction and send it to the mempool. First we will have to create one . We create a transaction with an OP_RETURN output.

satoshi_address=$(bcli29 getnewaddress)

tx_highfee=$(bcli29 createrawtransaction "[{\"txid\":\"$coinbase_txid\",\"vout\":0}]" \
    "[{\"$satoshi_address\":49.99990000},{\"data\":\"6a0001\"}]")
echo $tx_highfee
02000000014a1f63b71e4e60ef33902543c66373d68a1ba1412354d146dbda8de345cbe8da0000000000fdffffff02f0ca052a01000000160014dc267c817008619bf4327398e90ad35b4a6c56130000000000000000056a036a000100000000

We then sign this transaction

tx_highfee_signed=$(bcli29 signrawtransactionwithwallet $tx_highfee | jq -r .hex)
echo $tx_highfee_signed
020000000001014a1f63b71e4e60ef33902543c66373d68a1ba1412354d146dbda8de345cbe8da0000000000fdffffff02f0ca052a01000000160014dc267c817008619bf4327398e90ad35b4a6c56130000000000000000056a036a00010247304402203aa964764f88d3762c7f88bd679a3d0673fdcd66561b8ded1935066e3b0924c9022015be6a9e8a651dc38e2301f693228f8614954beba274c9e894dcb2f85d93c2db012102b0f748e7b7f75c75a474a2888ea34c95ae63d506546dc5d5efe18eb1a51f604500000000

We then send the transaction to the mempool

bcli29 sendrawtransaction $tx_highfee_signed
eeeaec05ef30b4a92364da21c915d3eca2c60a967b177731c9d552a97ecac661

By now we have sent a transaction to the mempool. Keep in mind that since we are the only miner in the regtest , this transaction will remain in the mempool until we mine another block again. We will now create another transaction with a lower fee to replace this transaction.

We repeat the steps we took before till signing the transaction

tx_lowfee=$(bcli29 createrawtransaction "[{\"txid\":\"$coinbase_txid\",\"vout\":0}]" \
    "[{\"$satoshi_address\":49.99995000},{\"data\":\"6a0001\"}]")
echo $tx_lowfee
02000000014a1f63b71e4e60ef33902543c66373d68a1ba1412354d146dbda8de345cbe8da0000000000fdffffff0178de052a01000000160014dc267c817008619bf4327398e90ad35b4a6c561300000000
tx_lowfee_signed=$(bcli29 signrawtransactionwithwallet $tx_lowfee | jq -r .hex)
echo $tx_lowfee_signed
020000000001014a1f63b71e4e60ef33902543c66373d68a1ba1412354d146dbda8de345cbe8da0000000000fdffffff0178de052a01000000160014dc267c817008619bf4327398e90ad35b4a6c561302473044022002d1a19ba0bd81f516f478a8b855197322031e79c2335bfed94e6dc178b0452b02206dd096d3333626caa71516cf6e4721a13289bcc45a3e25e7104aa6ac1fd12f0c012102b0f748e7b7f75c75a474a2888ea34c95ae63d506546dc5d5efe18eb1a51f604500000000

We now use the testmempoolaccept rpc to check if the mempool will accept this transaction.

bcli29 testmempoolaccept "[\"$tx_lowfee_signed\"]"
[
  {
    "txid": "bc4793b107295bc149377c32ed170c42290e40ad9b7cdb71dc7104adbf84fe9a",
    "wtxid": "c03046bb75024d47e7060fd4b1d3d37cf0c8eafaa346bc53d2a63350e23ee505",
    "allowed": false,
    "reject-reason": "insufficient fee",
    "reject-details": "insufficient fee, rejecting replacement bc4793b107295bc149377c32ed170c42290e40ad9b7cdb71dc7104adbf84fe9a; new feerate 0.00045454 BTC/kvB <= old feerate 0.00080645 BTC/kvB"
  }
]

We see that the second transaction has been rejected with reject-details field giving us a verbose reason as to why our transaction was rejected.

Now stop the regtest and clean the data directories.

bcli29 stop && datadir-cleanup

3.2 Persistent Block Data for Duplicate submitblock Submissions

No available test, feel free to provide one (please notify us in the feedback issue)

3.3 Updated getmininginfo: New nBits, Target, and Next Block Details

In Bitcoin Core 29.0, the getmininginfo RPC now includes the nBits value and the current target in the target field. Additionally, it introduces a new next object, which provides details about the next block, including its height, nBits, difficulty, and target. (#31583)

Steps to Test

Start the Bitcoin Core 29.0 node by running:

bitcoind29 -daemonwait

Retrieve mining information using the getmininginfo method:

bcli29 getmininginfo

Example output:

{
  "blocks": 0,
  "bits": "1d00ffff",
  "difficulty": 1,
  "target": "00000000ffff0000000000000000000000000000000000000000000000000000",
  "networkhashps": 0,
  "pooledtx": 0,
  "chain": "main",
  "next": {
    "height": 1,
    "bits": "1d00ffff",
    "difficulty": 1,
    "target": "00000000ffff0000000000000000000000000000000000000000000000000000"
  }
}

Verify that the output now includes the new target field and the next object, which contains attributes for the next block.

3.4 target & bits fields added to RPC methods

In Bitcoin Core 29.0, the getblock, getblockheader, getblockchaininfo, and getchainstates RPC commands now return the target field, with getblockchaininfo and getchainstates also including the bits field (#31583)

To start a Bitcoin Core 29.0 node, run:

bitcoind29 -daemonwait

Wait a few seconds for the node to start.

  • getblock and getblockheader now return the target field.
bcli29 getblock $(bcli29 getbestblockhash)
bcli29 getblockheader $(bcli29 getbestblockhash)

Example output:

{
  "hash": "00000000000000e7df03b9131d064bdb30f0007bed27ce42bc0750c64c134894",
  ...
  "target": "00000000000006dfbe0000000000000000000000000000000000000000000000"
}

New fields: target

  • getblockchaininfo and getchainstates now return target and bits fields.
bcli29 -regtest getblockchaininfo
bcli29 -regtest getchainstates

Example output:

{
   "chain": "main",
   ...
   "bits": "1d00ffff",
   "target": "00000000ffff0000000000000000000000000000000000000000000000000000",
}

New fields: target, bits

3.5 getblocktemplate RPC Now Considers BIP94 Timewarp Fix

No available test, feel free to provide one (please notify us in the feedback issue)

4. New RPCs

4.1 Introduce new getdescriptoractivity rpc to track activity of a given set of descriptors

getdescriptoractivity is a new rpc introduced in the 29.0 release which can be used to find all spend/receive activity relevant to a given set of descriptors within a set of specified blocks. (30708)

Steps to Test

Change the bitcoin.conf file to run on regtest with blockfilterindex=basic. Not using blockfilterindex=basic will error out when using the scanblocks command. (#30708)

echo "regtest=1" > $DATA_DIR_29/bitcoin.conf
echo "[regtest]" >> $DATA_DIR_29/bitcoin.conf
echo "blockfilterindex=basic" >> $DATA_DIR_29/bitcoin.conf

Start the bitcoind session

bitcoind29 -daemon

Create a new wallet

bcli29 createwallet "satoshi"  
{
  "name": "satoshi"
}

Generate a new address and mine 420 blocks

satoshi_address=$(bcli29 getnewaddress)
bcli29 generatetoaddress 420 $satoshi_address
[
  "15a3b270b902b8f1dad72a9359bafa015403a39017d5e89aee2a146b2dfbb7c1",
  "6a15b3e6466f4cdb4086aee7d867b9362b094310f353754b17a46bd6815b2fa9",
  "425dfacc96a0bd11047b510e270db7225a68584cb738c4928e008bce483cfdeb",
  "7f1b86b1adbb6bd0a692d468d55324fe7aa4c907ac272a872c8888384127610c",
  "35dda0d7c82bc0c2ee7ed0b91e9cfe139f7121a40f575b97d479992f96fa3f1f",
  "3c80eec99e82846740fbbbb508f34f170427bdcf87bdbc7e73f4bf5681cc616e",
  ...
 ]

Pick one of the UTXOs to spend. You can view your UTXOs with the listunspent rpc.

coinbase_txid=$(bcli29 listunspent 350 | jq -r ".[0].txid")
echo $coinbase_txid
96fb39414a5a9577739e3e1e4b7e8dd28764d0b58d4afa61435cc8b50382789f

Create a transaction and send it to to the network.

tx=$(bcli29 createrawtransaction "[{\"txid\":\"$coinbase_txid\",\"vout\":0}]" \
    "[{\"$satoshi_address\":49.99995000}]")
echo $tx
02000000019f788203b5c85c4361fa4a8db5d06487d28d7e4b1e3e9e7377955a4a4139fb960000000000fdffffff0178de052a01000000160014eaac91dcf5b191ca95b72c8af7b51fcfc52a0b9c00000000
tx_signed=$(bcli29 -regtest signrawtransactionwithwallet $tx | jq -r .hex)
echo $tx_signed
020000000001019f788203b5c85c4361fa4a8db5d06487d28d7e4b1e3e9e7377955a4a4139fb960000000000fdffffff0178de052a01000000160014eaac91dcf5b191ca95b72c8af7b51fcfc52a0b9c02473044022030e88d1363299888ede77442080c1b4f1f19298eeaa4194566c31c19ac682f780220638f4795ffb21d66c65b5d7087eca506e9f087d05b4c870e7fa71fa0a4803f5b012103f6ec0f4ab86a3af2f13a174103c649e067dbb909e5788f0f298f82769c0887e400000000

bcli29 sendrawtransaction $tx_signed
005ad3e0467f7cec7841c363193a077edac2e67d57b5cb81f7a5b99ef8086114

Now mine the block and verify that the blockcount has increased.

bcli29 generatetoaddress 1 $satoshi_address
[
  "252e486763d2f2e03b1dc82806425233f72245d2ecf9f1401fb7db726ab26d60"
]

Now to use the getdescriptoractivity rpc, we first have to use the scanblocks rpc to scan the blocks we want. We will specify the rpc to scan the descriptor of our newly created address starting from block 420 and ending at the latest block on the chain.

relevant_blocks=$(bcli29 scanblocks start "[\"addr($satoshi_address)\"]" 420 | jq -c .relevant_blocks)
echo $relevant_blocks
[
    "523177f4fbd0e709fee8b89174d73e07d251aab05dd7e29fbf9d37d7b71f2e6e",
    "252e486763d2f2e03b1dc82806425233f72245d2ecf9f1401fb7db726ab26d60"
  ]

Now that we have the relevant blocks where this descriptor has an activity , we look for its activity in these blocks.

bcli29 getdescriptoractivity "$relevant_blocks" "[\"addr($satoshi_address)\"]"
{
  "activity": [
    {
      "type": "receive",
      "amount": 12.50000000,
      "blockhash": "523177f4fbd0e709fee8b89174d73e07d251aab05dd7e29fbf9d37d7b71f2e6e",
      "height": 420,
      "txid": "73ea5227dee75cf03f7d86b5ad3f2ef6b56d965213cee8d51a629f9166ca918c",
      "vout": 0,
      "output_spk": {
        "asm": "0 eaac91dcf5b191ca95b72c8af7b51fcfc52a0b9c",
        "desc": "addr(bcrt1qa2kfrh84kxgu49dh9j900dglelzj5zuuy7ayhg)#a0jsteev",
        "hex": "0014eaac91dcf5b191ca95b72c8af7b51fcfc52a0b9c",
        "address": "bcrt1qa2kfrh84kxgu49dh9j900dglelzj5zuuy7ayhg",
        "type": "witness_v0_keyhash"
      }
    },
    {
      "type": "receive",
      "amount": 12.50005000,
      "blockhash": "252e486763d2f2e03b1dc82806425233f72245d2ecf9f1401fb7db726ab26d60",
      "height": 421,
      "txid": "fa2edd9535ee54d4e535148eaa8b278ce94edca71c067a5b5bbfdb5dd36232c9",
      "vout": 0,
      "output_spk": {
        "asm": "0 eaac91dcf5b191ca95b72c8af7b51fcfc52a0b9c",
        "desc": "addr(bcrt1qa2kfrh84kxgu49dh9j900dglelzj5zuuy7ayhg)#a0jsteev",
        "hex": "0014eaac91dcf5b191ca95b72c8af7b51fcfc52a0b9c",
        "address": "bcrt1qa2kfrh84kxgu49dh9j900dglelzj5zuuy7ayhg",
        "type": "witness_v0_keyhash"
      }
    },
    {
      "type": "spend",
      "amount": 50.00000000,
      "blockhash": "252e486763d2f2e03b1dc82806425233f72245d2ecf9f1401fb7db726ab26d60",
      "height": 421,
      "spend_txid": "005ad3e0467f7cec7841c363193a077edac2e67d57b5cb81f7a5b99ef8086114",
      "spend_vin": 0,
      "prevout_txid": "96fb39414a5a9577739e3e1e4b7e8dd28764d0b58d4afa61435cc8b50382789f",
      "prevout_vout": 0,
      "prevout_spk": {
        "asm": "0 eaac91dcf5b191ca95b72c8af7b51fcfc52a0b9c",
        "desc": "addr(bcrt1qa2kfrh84kxgu49dh9j900dglelzj5zuuy7ayhg)#a0jsteev",
        "hex": "0014eaac91dcf5b191ca95b72c8af7b51fcfc52a0b9c",
        "address": "bcrt1qa2kfrh84kxgu49dh9j900dglelzj5zuuy7ayhg",
        "type": "witness_v0_keyhash"
      }
    },
    {
      "type": "receive",
      "amount": 49.99995000,
      "blockhash": "252e486763d2f2e03b1dc82806425233f72245d2ecf9f1401fb7db726ab26d60",
      "height": 421,
      "txid": "005ad3e0467f7cec7841c363193a077edac2e67d57b5cb81f7a5b99ef8086114",
      "vout": 0,
      "output_spk": {
        "asm": "0 eaac91dcf5b191ca95b72c8af7b51fcfc52a0b9c",
        "desc": "addr(bcrt1qa2kfrh84kxgu49dh9j900dglelzj5zuuy7ayhg)#a0jsteev",
        "hex": "0014eaac91dcf5b191ca95b72c8af7b51fcfc52a0b9c",
        "address": "bcrt1qa2kfrh84kxgu49dh9j900dglelzj5zuuy7ayhg",
        "type": "witness_v0_keyhash"
      }
    }
  ]
}

Now stop the regtest and clean the data directories.

bcli29 stop && datadir-cleanup

5. Updated REST APIs

5.1 Get block and Get headers return target in the target field

In the 29.0 release, the GET /rest/block/.json and GET /rest/headers/.json now return the current target in the target field (31583)

Setup the env.

echo "server=1" > $DATA_DIR_29/bitcoin.conf
echo "rest=1" >> $DATA_DIR_29/bitcoin.conf
echo "regtest=1" >> $DATA_DIR_29/bitcoin.conf
echo "[regtest]" >> $DATA_DIR_29/bitcoin.conf
echo "rpcallowip=127.0.0.1" >> $DATA_DIR_29/bitcoin.conf
echo "rpcport=18343" >> $DATA_DIR_29/bitcoin.conf

Start the v29 node:

bitcoind29 -daemonwait

Run command to test:

blockhash=$(bcli29 getbestblockhash)
curl localhost:18343/rest/block/${blockhash}.json 2>/dev/null | jq

Example output:

{
  "hash": "0f9188f13cb7b2c71f2a335e3a4fc328bf5beb436012afca590b1a11466e2206",
  "confirmations": 1,
  "height": 0,
  "version": 1,
  "versionHex": "00000001",
  "merkleroot": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b",
  "time": 1296688602,
  "mediantime": 1296688602,
  "nonce": 2,
  "bits": "207fffff",
  "target": "7fffff0000000000000000000000000000000000000000000000000000000000",
  "difficulty": 4.656542373906925E-10,
  "chainwork": "0000000000000000000000000000000000000000000000000000000000000002",
  "nTx": 1,
  "strippedsize": 285,
  "size": 285,
  "weight": 1140,
  [...]
}

Ensure that the target and bits fields are included for in the array.

blockhash=$(bcli29 getbestblockhash)
curl localhost:18343/rest/headers/${blockhash}.json 2>/dev/null | jq 
[
  {
    "hash": "0f9188f13cb7b2c71f2a335e3a4fc328bf5beb436012afca590b1a11466e2206",
    "confirmations": 1,
    "height": 0,
    "version": 1,
    "versionHex": "00000001",
    "merkleroot": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b",
    "time": 1296688602,
    "mediantime": 1296688602,
    "nonce": 2,
    "bits": "207fffff",
    "target": "7fffff0000000000000000000000000000000000000000000000000000000000",
    "difficulty": 4.656542373906925E-10,
    "chainwork": "0000000000000000000000000000000000000000000000000000000000000002",
    "nTx": 1
  }
]

Ensure that the target and bits fields are included in the array.

cleanup

bcli29 stop && datadir-cleanup

Feedback

Kudos if you make it this far 👏🎉

Thanks for your contribution and for taking the time to make Bitcoin awesome. For feedback on this guide, please visit this issue.

Clone this wiki locally