Releases: bitcoin-cash-node/bitcoin-cash-node
28.0.0
Release Notes for Bitcoin Cash Node version 28.0.0
Bitcoin Cash Node version 28.0.0 is now available from:
Overview
This is a major release of Bitcoin Cash Node (BCHN) that implements the May 15, 2025 Network Upgrade. The upgrade
implements the following two consensus-level CHIPs:
- CHIP-2021-05 VM Limits: Targeted Virtual Machine Limits
- CHIP-2024-07 BigInt: High-Precision Arithmetic for Bitcoin Cash
Additionally, this version contains various other minor corrections and improvements.
Users who are running any of our previous releases (v27.x.x or before) are urged to upgrade to v28.0.0 ahead of
May 15, 2025.
Usage recommendations
The update to Bitcoin Cash Node 28.0.0 is required for the May 15, 2025 Bitcoin Cash network upgrade.
Network changes
- UPnP: If there is an error opening the port, BCHN will now keep retrying periodically until it succeeds, rather than
simply failing and giving up. - p2p protocol: BCHN now ignores timestamps from inbound peers for the purposes of calculating network adjusted
time. - p2p protocol: BCHN now ignores peer timestamps that seem bogus/malformed/garbage/unlikely.
- HTTP server: Set TCP_NODELAY on the server socket, which should improve RPC and REST server responsiveness.
Added functionality
- Added NAT-PMP port mapping support via
libnatpmp
.
Use the-natpmp
command line option to use NAT-PMP to map the listening port. If both UPnP
and NAT-PMP are enabled, a successful allocation from UPnP prevails over one from NAT-PMP. - bitcoin-seeder now saves its current state to the dump and db files immediately before exiting when gracefully
shut down via Ctrl-C, SIGINT, SIGTERM, etc.
Deprecated functionality
None
Modified functionality
- bitcoin-seeder now refuses to start if it cannot bind to the DNS port specified, rather than silently suceeding.
- The transaction script execution engine has been greatly extended and expanded. These changes include:
- Various execution limits for the Script VM have been greatly expanded and extended. For a full description,
of what has been added and improved, see: https://github.com/bitjson/bch-vm-limits/tree/master. - Support for arbitrary precision integers has been added to the Script VM. The previous limit was 64-bit integers,
now the integer limit has been expanded to support up to 80,000-bit integers. - Both of the above-mentioned consensus changes will activate on the mainnet network on May 15, 2025.
- Various execution limits for the Script VM have been greatly expanded and extended. For a full description,
Removed functionality
Support for 32-bit architectures (such as armhf and linux-i686) has been completely dropped. Due to the limitations
in available virtual memory on 32-bit, and the increasing demands of Bitcoin Cash to support large blocks, 32-bit
architectures are no longer supported by Bitcoin Cash Node. We apologize for the inconvenience but are hopeful that
this change in requirements will have minimal to zero impact on our users, most of whom are likely already using a
64-bit platform.
New RPC methods
- The
getindexinfo
RPC returns the actively running indices of the node,
including their current sync status and height. It also accepts anindex_name
to specify returning only the status of that index.
User interface changes
- RPC: Added input
tokenData
andscriptPubKey
to RPC methodgetrawtransaction
withverbosity=2
Regressions
Bitcoin Cash Node 28.0.0 does not introduce any known regressions as compared to 27.1.0 and/or 27.0.0.
Limitations
The following are limitations in this release of which users should be aware:
-
CashToken support is low-level at this stage. The wallet application does
not yet keep track of the user's tokens.
Tokens are only manageable via RPC commands currently.
They only persist through the UTXO database and block database at this
point.
There are existing RPC commands to list and filter for tokens in the UTXO set.
RPC raw transaction handling commands have been extended to allow creation
(and sending) of token transactions.
Interested users are advised to consult the functional test in
test/functional/bchn-rpc-tokens.py
for examples on token transaction
construction and listing.
Future releases will aim to extend the RPC API with more convenient
ways to create and spend tokens, as well as upgrading the wallet storage
and indexing subsystems to persistently store data about tokens of interest
to the user. Later we expect to add GUI wallet management of Cash Tokens. -
Transactions with SIGHASH_UTXO are not covered by DSProofs at present.
-
P2SH-32 is not used by default in the wallet (regular P2SH-20 remains
the default wherever P2SH is treated). -
The markup of Double Spend Proof events in the wallet does not survive
a restart of the wallet, as the information is not persisted to the
wallet. -
The ABLA algorithm for BCH is currently temporarily set to cap the max block
size at 2GB. This is due to limitations in the p2p protocol (as well as the
block data file format in BCHN).
Known Issues
Some issues could not be closed in time for release, but we are tracking all
of them on our GitLab repository.
-
The minimum macOS version is 10.14 (Mojave).
Earlier macOS versions are no longer supported. -
Windows users are recommended not to run multiple instances of bitcoin-qt
or bitcoind on the same machine if the wallet feature is enabled.
There is risk of data corruption if instances are configured to use the same
wallet folder. -
Some users have encountered unit tests failures when running in WSL
environments (e.g. WSL/Ubuntu). At this time, WSL is not considered a
supported environment for the software. This may change in future.
It has been reported that using WSL2 improves the issue. -
doc/dependencies.md
needs revision (Issue). -
For users running from sources built with BerkeleyDB releases newer than
the 5.3 which is used in this release, please take into consideration
the database format compatibility issues described in Issue.
When building from source it is recommended to use BerkeleyDB 5.3 as this
avoids wallet database incompatibility issues with the official release. -
The
test_bitcoin-qt
test executable fails on Linux Mint 20
(see Issue). This does not otherwise appear to impact the functioning
of the BCHN software on that platform. -
With a certain combination of build flags that included disabling
the QR code library, a build failure was observed where an erroneous
linking against the QR code library (not present) was attempted (Issue). -
Possible out-of-memory error when starting bitcoind with high excessiveblocksize
value (Issue) -
A problem was observed on scalenet where nodes would sometimes hang for
around 10 minutes, accepting RPC connections but not responding to them
(see Issue). -
Startup and shutdown time of nodes on scalenet can be long (see Issue).
-
Race condition in one of the
p2p_invalid_messages.py
tests (see Issue). -
Occasional failure in bchn-txbroadcastinterval.py (see Issue).
-
wallet_keypool.py test failure when run as part of suite on certain many-core
platforms (see Issue). -
Spurious 'insufficient funds' failure during p2p_stresstest.py benchmark
(see Issue). -
If compiling from source, secp256k1 now no longer works with latest openssl3.x series.
There are workarounds (see Issue). -
Spurious
AssertionError: Mempool sync timed out
in several tests
(see Issue). -
For some platforms, there may be a need to install additional libraries
in order to build from source (see Issue and discussion in MR 1523). -
More TorV3 static seeds may be needed to get
-onlynet=onion
working
(see Issue). -
Memory usage can be very high if repeatedly doing RPC
getblock
with
verbose=2 on a hash of known big blocks (see Issue). -
A GUI crash failure was observed when attempting to encrypt a large imported
wallet (see Issue). -
The 'wallet_multiwallet' functional test fails on latest Arch Linux due to
a change in semantics in a dependency (see Issue). This is not
expected to impact functionality otherwise, only a particular edge case
of the test. -
The 'p2p_extversion' functional test is sensitive to timing issues when
run at high load (see [Issue](https://gitlab.com/bitcoin-cash-node/bitcoin-cash-node/-/issues/...
27.1.0
Release Notes for Bitcoin Cash Node version 27.1.0
Bitcoin Cash Node version 27.1.0 is now available from:
Overview
This release of Bitcoin Cash Node (BCHN) includes some bug fixes and important reliability enhancements.
Usage recommendations
Users who are running v27.0.0 or earlier are encouraged to upgrade to v27.1.0 as it includes some bugfixes as well as
updated checkpoints for the recently completed (15 May 2024) network upgrade. It also include some performance and
reliability fixes related to transaction processing.
Network changes
The internal transaction processing logic for both regular and orphan transactions has been reworked to be more
performant and more reliable.
Added functionality
None.
Deprecated functionality
None.
Modified functionality
The command-line option -upgrade10activationtime has been renamed to -upgrade10activationheight and is now height-based,
rather than MTP time-based. The next upgrade is still expected to be MTP time-based.
Removed functionality
BIP70 payment request support has been removed from the Qt-based GUI. The
reason for this is that BIP70 payment requests have historically suffered
from a number of security flaws and maintainence of this feature poses a
risk to full node software. Users wishing to use a GUI wallet that supports
BIP70 are recommended to use one of the many light wallets such as Electron
Cash or Bitcoin.com that continue to support BIP70 payment requests.
New RPC methods
None.
User interface changes
- The
-wipeignore
bitcoin-seeder command line option has been removed. The way the
list of ignored nodes is handled has been broken for many years. Rather than ignoring
nodes until a particular time, nodes were being ignored from that time. This meant
that ignored nodes that ever reached this timeout would stay ignored forever; and
until that point, they would be processed as often as any other node rather than
being ignored for a cooling-off period as intended. To resolve this, we decided to
simply remove this facility entirely, meaning that nodes will now never be ignored. - The
datadir=
conf file variable appearing both outside and inside a section header in
the conf file works as expected now, and no longer leads to unexpectedblocksdir=
settings (!1816).
Regressions
Bitcoin Cash Node 27.1.0 does not introduce any known regressions as compared to 27.0.0.
Limitations
The following are limitations in this release of which users should be aware:
-
CashToken support is low-level at this stage. The wallet application does
not yet keep track of the user's tokens.
Tokens are only manageable via RPC commands currently.
They only persist through the UTXO database and block database at this
point.
There are existing RPC commands to list and filter for tokens in the UTXO set.
RPC raw transaction handling commands have been extended to allow creation
(and sending) of token transactions.
Interested users are advised to consult the functional test in
test/functional/bchn-rpc-tokens.py
for examples on token transaction
construction and listing.
Future releases will aim to extend the RPC API with more convenient
ways to create and spend tokens, as well as upgrading the wallet storage
and indexing subsystems to persistently store data about tokens of interest
to the user. Later we expect to add GUI wallet management of Cash Tokens. -
Transactions with SIGHASH_UTXO are not covered by DSProofs at present.
-
P2SH-32 is not used by default in the wallet (regular P2SH-20 remains
the default wherever P2SH is treated). -
The markup of Double Spend Proof events in the wallet does not survive
a restart of the wallet, as the information is not persisted to the
wallet. -
The ABLA algorithm for BCH is currently temporarily set to cap the max block
size at 2GB. This is due to limitations in the p2p protocol (as well as the
block data file format in BCHN).
Known Issues
Some issues could not be closed in time for release, but we are tracking all
of them on our GitLab repository.
-
The minimum macOS version is 10.14 (Mojave).
Earlier macOS versions are no longer supported. -
Windows users are recommended not to run multiple instances of bitcoin-qt
or bitcoind on the same machine if the wallet feature is enabled.
There is risk of data corruption if instances are configured to use the same
wallet folder. -
Some users have encountered unit tests failures when running in WSL
environments (e.g. WSL/Ubuntu). At this time, WSL is not considered a
supported environment for the software. This may change in future.
It has been reported that using WSL2 improves the issue. -
doc/dependencies.md
needs revision (Issue). -
For users running from sources built with BerkeleyDB releases newer than
the 5.3 which is used in this release, please take into consideration
the database format compatibility issues described in Issue.
When building from source it is recommended to use BerkeleyDB 5.3 as this
avoids wallet database incompatibility issues with the official release. -
The
test_bitcoin-qt
test executable fails on Linux Mint 20
(see Issue). This does not otherwise appear to impact the functioning
of the BCHN software on that platform. -
With a certain combination of build flags that included disabling
the QR code library, a build failure was observed where an erroneous
linking against the QR code library (not present) was attempted (Issue). -
Possible out-of-memory error when starting bitcoind with high excessiveblocksize
value (Issue) -
A problem was observed on scalenet where nodes would sometimes hang for
around 10 minutes, accepting RPC connections but not responding to them
(see Issue). -
Startup and shutdown time of nodes on scalenet can be long (see Issue).
-
Race condition in one of the
p2p_invalid_messages.py
tests (see Issue). -
Occasional failure in bchn-txbroadcastinterval.py (see Issue).
-
wallet_keypool.py test failure when run as part of suite on certain many-core
platforms (see Issue). -
Spurious 'insufficient funds' failure during p2p_stresstest.py benchmark
(see Issue). -
If compiling from source, secp256k1 now no longer works with latest openssl3.x series.
There are workarounds (see Issue). -
Spurious
AssertionError: Mempool sync timed out
in several tests
(see Issue). -
For some platforms, there may be a need to install additional libraries
in order to build from source (see Issue and discussion in MR 1523). -
More TorV3 static seeds may be needed to get
-onlynet=onion
working
(see Issue). -
Memory usage can be very high if repeatedly doing RPC
getblock
with
verbose=2 on a hash of known big blocks (see Issue). -
A GUI crash failure was observed when attempting to encrypt a large imported
wallet (see Issue). -
Nodes on 32-bit platforms could fail if blocks reach a size over 1GiB
(per ABLA this would take multiple years, and by then 32-bit platforms
will no longer be supported in any case).
Technically, this is because blocks may take 2x-3x as much memory when
unserialized into memory as they do when serialized, and 32-bit machines
often cannot address more than 2GiB in a userspace process, and can never
address more than 4GiB. -
The 'wallet_multiwallet' functional test fails on latest Arch Linux due to
a change in semantics in a dependency (see Issue). This is not
expected to impact functionality otherwise, only a particular edge case
of the test. -
The 'p2p_extversion' functional test is sensitive to timing issues when
run at high load (see Issue).
Changes since Bitcoin Cash Node 27.0.0
New documents
None
Removed documents
None
Notable commits grouped by functionality
Security or consensus relevant fixes
- 2443f18 Add checkpoints for blocks after upgrade10 ABLA activation
- 7f86271 Switch ABLA (upgrade10) to use height-based activation, rather than MTP
- 399f414 qa: Update chainparams assumevalid and minimumchainwork for 27.1.0
- 02c658c Update chainTxData for main, test3, test4, and chipnet
Interfaces / RPC
None
Features in internal development: support for UTXO commitments
Non...
27.0.0
Release Notes for Bitcoin Cash Node version 27.0.0
Bitcoin Cash Node version 27.0.0 is now available from:
Overview
This is a major release of Bitcoin Cash Node (BCHN) that implements the May 15, 2024 Network Upgrade.
This release implements the following consensus CHIPs:
- CHIP-2023-04 Adaptive Blocksize Limit Algorithm for Bitcoin Cash commit
ba9ed768
(19 Nov 2023)
This version contains various additional minor corrections and improvements.
Users who are running any of our previous releases (25.0.0 or v26.x.0) are urged to upgrade to v27.0.0 ahead of 15 May 2024.
Usage recommendations
The update to Bitcoin Cash Node 27.0.0 is required for the May 15, 2024 Bitcoin Cash network upgrade.
Network changes
This major release implements the Adaptive Blocksize Limit Algorithm for Bitcoin Cash, which is a change to consensus rules that allows the maximum block size to gradually increase and decrease based on how full blocks are.
Added functionality
- Added configuration option
-percentblockmaxsize
which is an alternative to-blockmaxsize
.-percentmaxblocksize
can be used to configure the node's maximum mined block size as a percentage of the maximum block size for the network. So for instance the default on mainnet is-percentblockmaxsize=50.0
(16 MB). Can be any value from 0.0 to 100.0.
Deprecated functionality
- While 32-bit builds are still supported in this release, they are deprecated and planned to be removed from BCHN after the May 2024 upgrade.
Modified functionality
- The -excessiveblocksize configuration value has modified semantics pre-upgrade vs post-upgrade. After ABLA activates, it acts as a floor value as the base "minimum" max block size.
- Added an additional returned data item to the
getmininginfo
RPC:
"miningblocksizelimit", which is the block size limit used for mining as configured for the node by e.g.:-blockmaxsize
. - The Qt GUI RPC console now is fixed to match the HTTP RPC with respect to stateful "config related" commands. Commands such as
getmininginfo
andgetexcessiveblock
now match the actual node config (and the HTTP RPC). - The default size cap for mining blocks has been set to 50% of the capacity on networks where it has previously been set to 25%. This effectively increases the soft (mining) blocksize default from 8MB to 16MB. Mining pools that wish to generate bigger or smaller blocks can still adjust the configuration option as usual.
Removed functionality
None.
New RPC methods
A 'fillmempool' RPC method has been added for regtest.
User interface changes
- The new configuration option
-percentblockmaxsize
has been added. It is described in more detail in the "Added functionality" section above.
Regressions
Bitcoin Cash Node 27.0.0 does not introduce any known regressions as compared to 26.1.0.
Limitations
The following are limitations in this release of which users should be aware:
-
CashToken support is low-level at this stage. The wallet application does not yet keep track of the user's tokens.
Tokens are only manageable via RPC commands currently. They only persist through the UTXO database and block database at this
point.
There are existing RPC commands to list and filter for tokens in the UTXO set.
RPC raw transaction handling commands have been extended to allow creation (and sending) of token transactions.
Interested users are advised to consult the functional test intest/functional/bchn-rpc-tokens.py
for examples on token transaction
construction and listing.
Future releases will aim to extend the RPC API with more convenient ways to create and spend tokens, as well as upgrading the wallet storage and indexing subsystems to persistently store data about tokens of interest to the user. Later we expect to add GUI wallet management of Cash Tokens. -
Transactions with SIGHASH_UTXO are not covered by DSProofs at present.
-
P2SH-32 is not used by default in the wallet (regular P2SH-20 remains the default wherever P2SH is treated).
-
The markup of Double Spend Proof events in the wallet does not survive a restart of the wallet, as the information is not persisted to the wallet.
-
The ABLA algorithm for BCH is currently temporarily set to cap the max block size at 2GB. This is due to limitations in the p2p protocol (as well as the block data file format in BCHN).
Known Issues
Some issues could not be closed in time for release, but we are tracking all of them on our GitLab repository.
-
The minimum macOS version is 10.14 (Mojave). Earlier macOS versions are no longer supported.
-
Windows users are recommended not to run multiple instances of bitcoin-qt or bitcoind on the same machine if the wallet feature is enabled. There is risk of data corruption if instances are configured to use the same wallet folder.
-
Some users have encountered unit tests failures when running in WSL environments (e.g. WSL/Ubuntu). At this time, WSL is not considered a supported environment for the software. This may change in future. It has been reported that using WSL2 improves the issue.
-
doc/dependencies.md
needs revision (Issue #65). -
For users running from sources built with BerkeleyDB releases newer than the 5.3 which is used in this release, please take into consideration the database format compatibility issues described in Issue #34. When building from source it is recommended to use BerkeleyDB 5.3 as this avoids wallet database incompatibility issues with the official release.
-
The
test_bitcoin-qt
test executable fails on Linux Mint 20 (see Issue #144). This does not otherwise appear to impact the functioning of the BCHN software on that platform. -
With a certain combination of build flags that included disabling the QR code library, a build failure was observed where an erroneous linking against the QR code library (not present) was attempted (Issue #138).
-
Possible out-of-memory error when starting bitcoind with high excessiveblocksize value (Issue #156)
-
A problem was observed on scalenet where nodes would sometimes hang for around 10 minutes, accepting RPC connections but not responding to them (see #210).
-
Startup and shutdown time of nodes on scalenet can be long (see Issue #313).
-
Race condition in one of the
p2p_invalid_messages.py
tests (see Issue #409). -
Occasional failure in bchn-txbroadcastinterval.py (see Issue #403).
-
wallet_keypool.py test failure when run as part of suite on certain many-core platforms (see Issue #380).
-
Spurious 'insufficient funds' failure during p2p_stresstest.py benchmark (see Issue #377).
-
If compiling from source, secp256k1 now no longer works with latest openssl3.x series. There are workarounds (see Issue #364).
-
Spurious
AssertionError: Mempool sync timed out
in several tests (see Issue #357). -
For some platforms, there may be a need to install additional libraries in order to build from source (see Issue #431 and discussion in MR 1523).
-
More TorV3 static seeds may be needed to get
-onlynet=onion
working (see Issue #429). -
Memory usage can be very high if repeatedly doing RPC
getblock
with verbose=2 on a hash of known big blocks (see Issue #466). -
A GUI crash failure was observed when attempting to encrypt a large imported wallet (see Issue #490).
-
Nodes on 32-bit platforms could fail if blocks reach a size over 1GiB (per ABLA this would take multiple years, and by then 32-bit platforms will no longer be supported in any case). Technically, this is because blocks may take 2x-3x as much memory when unserialized into memory as they do when serialized, and 32-bit machines often cannot address more than 2GiB in a userspace process, and can never address more than 4GiB.
-
The 'wallet_multiwallet' functional test fails on latest Arch Linux due to a change in semantics in a dependency (see Issue #505). This is not expected to impact functionality otherwise, only a particular edge case of the test.
-
The 'p2p_extversion' functional test is sensitive to timing issues when run at high load (see Issue #501).
Changes since Bitcoin Cash Node 26.1.0
New documents
None
Removed documents
None
Notable commits grouped by functionality
Security or consensus relevant fixes
- 286ca4e...
26.1.0
Release Notes for Bitcoin Cash Node version 26.1.0
Bitcoin Cash Node version 26.1.0 is now available from:
Overview
This release of Bitcoin Cash Node (BCHN) is a minor release.
It includes mostly bug fixes and performance enhancements, but there are some new features too, such as new fields in getpeerinfo
RPC and new syntax variable for -walletnotify
.
Usage recommendations
Users who are running v25.0.0 or v26.0.0 are encouraged to upgrade to v26.1.0 as it includes checkpoints and updated network static seeds for the recently completed (15 May 2023) network upgrade.
Network changes
Unsolicited ADDR
messages from network peers are now rate-limited to an average rate of 0.1 addresses per second, with allowance for bursts of up to 1000 addresses.
This change should have no noticeable deleterious effect on the peer-to-peer network for well-behaved peers, and was merely added as a performance optimization.
Added functionality
None.
Deprecated functionality
None.
Modified functionality
-
The
getpeerinfo
RPC method results now include two new additional data items for each peer:addr_processed
andaddr_rate_limited
. See thegetpeerinfo
RPC help for a description of these new items. -
The
-walletnotify
option now understands an additional %-token:%w
, which it will replace with the wallet name when executing the external command. For additional information see the help-hh
forbitcoind
. -
The current limit of 16 parallel script/sig verification threads, controlled by the
-par
configuration option, is substantially increased,
to a maximum of 256 threads, with the following rules:- For users that do not use the
-par
argument/config, current legacy functionality is preserved (clamped to 16) - For users that set
-par=0
, their number of cores will be used (clamped to 256) - For users that set
-par=N
, with N a positive integer, the parallelism will be set to N, clamped to 256; note that users can set this higher than their core count, which preserves current functionality - For users that set
-par=N
, with N a negative integer, the parallelism will be set to leave N threads free, clamped to 256 - For users using the GUI, the maximum number of threads they can set is equal to the number of cores, and is no longer 15 (sic!)
- GUI users will not be able to set this limit to a number higher than their number of cores, via the slider.
An upper limit is still needed, otherwise users can create thousands of threads and crash the node.
The old limit of 16 was set 10 years ago when this functionality was first introduced. Since then both hardware and software have progressed vastly. Users should be able to set the parallelism higher if their hardware supports it. There may be diminishing returns setting it to higher than 16, but verification times do improve with more cores to an extent on modern platforms.
NOTE 1: Current functionality is preserved only for users that don't use
-par
.NOTE 2: Only headless users can set
-par
above their core count. - For users that do not use the
Removed functionality
None.
New RPC methods
None.
User interface changes
- A bug in the fee rate override in the Send dialog of the GUI has been fixed.
- The
dumpwallet
file header comment now refers to "Bitcoin Cash Node", - The
importwallet
progress bar behaves more sanely. - Importing very large wallets has been made significantly faster.
Regressions
Bitcoin Cash Node 26.1.0 does not introduce any known regressions as compared to 26.0.0.
Limitations
The following are limitations in this release of which users should be aware:
-
CashToken support is low-level at this stage. The wallet application does not yet keep track of the user's tokens.
Tokens are only manageable via RPC commands currently.
They only persist through the UTXO database and block database at this point.
There are existing RPC commands to list and filter for tokens in the UTXO set.
RPC raw transaction handling commands have been extended to allow creation (and sending) of token transactions.
Interested users are advised to consult the functional test intest/functional/bchn-rpc-tokens.py
for examples on token transaction construction and listing.
Future releases will aim to extend the RPC API with more convenient ways to create and spend tokens, as well as upgrading the wallet storage and indexing subsystems to persistently store data about tokens of interest to the user. Later we expect to add GUI wallet management of Cash Tokens. -
Transactions with SIGHASH_UTXO are not covered by DSProofs at present.
-
P2SH-32 is not used by default in the wallet (regular P2SH-20 remains the default wherever P2SH is treated).
-
The markup of Double Spend Proof events in the wallet does not survive a restart of the wallet, as the information is not persisted to the wallet.
Known Issues
Some issues could not be closed in time for release, but we are tracking all of them on our GitLab repository.
-
The minimum macOS version is 10.14 (Mojave). Earlier macOS versions are no longer supported.
-
Windows users are recommended not to run multiple instances of bitcoin-qt or bitcoind on the same machine if the wallet feature is enabled. There is risk of data corruption if instances are configured to use the same wallet folder.
-
Some users have encountered unit tests failures when running in WSL environments (e.g. WSL/Ubuntu). At this time, WSL is not considered a supported environment for the software. This may change in future.
It has been reported that using WSL2 improves the issue. -
doc/dependencies.md
needs revision (Issue #65). -
For users running from sources built with BerkeleyDB releases newer than the 5.3 which is used in this release, please take into consideration the database format compatibility issues described in Issue #34.
When building from source it is recommended to use BerkeleyDB 5.3 as this avoids wallet database incompatibility issues with the official release. -
The
test_bitcoin-qt
test executable fails on Linux Mint 20 (see Issue #144). This does not otherwise appear to impact the functioning of the BCHN software on that platform. -
With a certain combination of build flags that included disabling the QR code library, a build failure was observed where an erroneous linking against the QR code library (not present) was attempted (Issue #138).
-
Possible out-of-memory error when starting bitcoind with high excessiveblocksize value (Issue #156)
-
A problem was observed on scalenet where nodes would sometimes hang for around 10 minutes, accepting RPC connections but not responding to them (see Issue #210).
-
Startup and shutdown time of nodes on scalenet can be long (see Issue #313).
-
Race condition in one of the
p2p_invalid_messages.py
tests (see Issue #409). -
Occasional failure in bchn-txbroadcastinterval.py (see Issue #403).
-
wallet_keypool.py test failure when run as part of suite on certain many-core platforms (see Issue #380).
-
Spurious 'insufficient funds' failure during p2p_stresstest.py benchmark (see Issue #377).
-
If compiling from source, secp256k1 now no longer works with latest openssl3.x series.
There are workarounds (see Issue #364). -
Spurious
AssertionError: Mempool sync timed out
in several tests (see Issue #357). -
For some platforms, there may be a need to install additional libraries in order to build from source (see Issue #431 and discussion in MR 1523).
-
More TorV3 static seeds may be needed to get
-onlynet=onion
working (see Issue #429). -
Memory usage can be very high if repeatedly doing RPC
getblock
with verbose=2 on a hash of known big blocks (see Issue #466). -
Building / testing on current Arch Linux requires some additional package installations which are not yet reflected in the documentation. (see Issue #477).
-
A GUI crash failure was observed when attempting to encrypt a large imported wallet (see Issue #490).
Changes since Bitcoin Cash Node 26.0.0
New documents
None.
Removed documents
None.
Notable commits grouped by functionality
Security or consensus relevant fixes
26.0.0
Release Notes for Bitcoin Cash Node version 26.0.0
Bitcoin Cash Node version 26.0.0 is now available from:
Overview
This release of Bitcoin Cash Node (BCHN) is marked as a major release but not due to consensus changes - only because it changes an interface (the rpcbind / rpcallowip options) in a way that is not completely backward compatible, and therefore needs to be tagged as a major version in accordance with Semantic Versioning.
However, for practical purposes, this version is more like a minor release, containing corrections and improvements such as:
- RPC related bug fixes and output improvements
- Performance optimization for getblock
- A new benchmark performance bisection script
- Some support code for future UTXO commitments
- Minor documentation updates
Users who are running any of our previous releases (24.x.y or 25.0.0) are encouraged to upgrade to v26.0.0.
Usage recommendations
If you have been using the rpcallowip
or rpcbind
options, please see the 'Modified functionality' subsection of this document to take
changes into account in your configuration.
Network changes
A few RPC calls have been modified to support additional output fields.
Added functionality
A new verbosity level (3) has been added to getblock
RPC command. It is like level 2 but each transaction will include inputs' prevout
information. The existing /rest/block/
REST endpoint is modified to contain this information too. Every vin
field will contain an additional prevout
subfield describing the spent output. prevout
contains the following keys:
generated
- true if the spent coin was a coinbaseheight
value
scriptPubKey
tokenData
(after May 2023 upgrade, appears if the transaction input had token data)
Deprecated functionality
None.
Modified functionality
-
The
rpcallowip
option can no longer be used to automatically listen on all network interfaces. Instead, therpcbind
parameter must be used to specify the IP addresses to listen on. Listening for RPC commands over a public network connection is insecure and should be disabled, so a warning is now printed if a user selects such a configuration. If you need to expose RPC in order to use a tool like Docker, ensure you only bind RPC to your localhost, e.g.docker run [...] -p 127.0.0.1:8332:8332
(this is an extra :8332 over the normal Docker port specification). -
The
getblock
RPC command has been modified: verbosity level 2 now returnsfee
information per transaction in the block. -
The
getblock
RPC command with verbosity level 0 now takes a faster path when returning raw block data to clients. It now skips some sanity checks, and assumes the block data read from disk is valid. Clients that read this serialized block data via this RPC call should be aware that it is not as stictly checked as it was previous to this release, and that it's now possible (in theory at least) to retrieve a corrupted block via the RPC interface.
In practice, it's almost always the case that blocks are not corrupt on-disk and this changed guarantee yields significant performance improvements for RPC clients retrieving raw block data. Node admins can disable this new fast-path behavior by using the-checkblockreads=1
configuration option, which will enable extra consistency checks for raw block reads via RPC.
Removed functionality
None.
New RPC methods
None.
User interface changes
The semantics of the rpcallowip
option have changed - see 'Modified functionality' subsection above.
Regressions
Bitcoin Cash Node 26.0.0 does not introduce any known regressions as compared to 25.0.0.
Limitations
Nothing new to report.
Known Issues
Some issues could not be closed in time for release, but we are tracking all of them on our GitLab repository.
-
The minimum macOS version is 10.14 (Mojave). Earlier macOS versions are no longer supported.
-
Windows users are recommended not to run multiple instances of bitcoin-qt or bitcoind on the same machine if the wallet feature is enabled. There is risk of data corruption if instances are configured to use the same wallet folder.
-
Some users have encountered unit tests failures when running in WSL environments (e.g. WSL/Ubuntu). At this time, WSL is not considered a supported environment for the software. This may change in future.
The functional failure on WSL is tracked in Issue #33. It arises when competing node program instances are not prevented from opening the same wallet folder. Running multiple program instances with the same configured walletdir could potentially lead to data corruption. The failure has not been observed on other operating systems so far.
-
doc/dependencies.md
needs revision (Issue #65). -
For users running from sources built with BerkeleyDB releases newer than the 5.3 which is used in this release, please take into consideration the database format compatibility issues described in Issue #34. When building from source it is recommended to use BerkeleyDB 5.3 as this avoids wallet database incompatibility issues with the official release.
-
The
test_bitcoin-qt
test executable fails on Linux Mint 20 (see Issue #144). This does not otherwise appear to impact the functioning of the BCHN software on that platform. -
With a certain combination of build flags that included disabling the QR code library, a build failure was observed where an erroneous
linking against the QR code library (not present) was attempted (Issue #138). -
Possible out-of-memory error when starting bitcoind with high excessiveblocksize value (Issue #156)
-
A problem was observed on scalenet where nodes would sometimes hang for around 10 minutes, accepting RPC connections but not responding to them (see #210).
-
At the time of writing, scalenet has not been mined for a while (since 10 August 2022), thus synchronization will stop at that block time. This isn't considered a BCHN issue per se, it depends on miners to resume mining this testnet.
-
Startup and shutdown time of nodes on scalenet can be long (see Issue #313).
-
Race condition in one of the
p2p_invalid_messages.py
tests (see Issue #409). -
Occasional failure in bchn-txbroadcastinterval.py (see Issue #403).
-
wallet_keypool.py test failure when run as part of suite on certain many-core platforms (see Issue #380).
-
Spurious 'insufficient funds' failure during p2p_stresstest.py benchmark (see Issue #377).
-
If compiling from source, secp256k1 now no longer works with latest openssl3.x series. There are workarounds (see Issue #364).
-
Spurious
AssertionError: Mempool sync timed out
in several tests (see Issue #357). -
For some platforms, there may be a need to install additional libraries in order to build from source (see Issue #431 and discussion in MR 1523).
-
More TorV3 static seeds may be needed to get
-onlynet=onion
working (see Issue #429). -
Memory usage can be very high if repeatedly doing RPC
getblock
with verbose=2 on a hash of known big blocks (see Issue #466).
Changes since Bitcoin Cash Node 25.0.0
New documents
None.
Removed documents
None.
Notable commits grouped by functionality
Security or consensus relevant fixes
The semantic changes to rpcallowip
have been made in consideration of increased node security, as listening for RPC commands on public network interfaces is insecure and should be disabled. See the 'Modified functionality' section above for details.
Interfaces / RPC
- 1592a89 Don't log on success by default in ReadRawBlockFromDisk with
-checkblockreads=1
- 751bb58 Fix getblockstats feerate unit in the RPC command help
- 931fe72 Nit: Some formatting nits in rpc/rawtransaction.cpp,
getrawtransaction
- b8c237a rpc: Add level 3 verbosity to
getblock
RPC call; Addfee
to level 2 - cf7e12c Improvements to
getrawtransaction
with verbosity=2 - eb0b086 Nit: More nits for getrawtransaction in rpc/rawtransaction.cpp
Features in internal development: support for UTXO commitments
- 718e29e Added new functions to secp256k1 for serializing the pubkey from a multiset
- ebc2a16 Modify the generic code in
hash.h
to support alternate hashers - eeab3ac Added C++ wrapper for EC multiset, plus tests
Data directory changes
None.
Pe...
25.0.0
Release Notes for Bitcoin Cash Node version 25.0.0
Bitcoin Cash Node version 25.0.0 is now available from:
Overview
This is a major release of Bitcoin Cash Node (BCHN) that implements the May 15, 2023 Network Upgrade.
This release implements the following consensus CHIPs:
- CHIP-2021-01 Restrict Transaction Version v1.0
- CHIP-2021-01 Minimum Transaction Size v0.4
- CHIP-2022-02 CashTokens v2.2.1
- CHIP-2022-05 P2SH32 v1.5.1
This version contains further corrections and improvements, such as:
- Support for new 'chipnet' test network (for pre-upgrade testing)
- Double Spend Proof notifications in the GUI wallet
- BIP69 input/output sorting in bitcoin-tx command line tool
- Enhancement for UI tests in test framework
Users who are running any of our previous releases (24.x.y) are urged to upgrade to v25.0.0 ahead of 15 May 2023.
Usage recommendations
The update to Bitcoin Cash Node 25.0.0 is required for the May 15, 2023 Bitcoin Cash network upgrade.
While there are no known regressions in this version at this time, as always we recommend that all users inform us of any potential regressions via our support channels.
Existing users, whether miners, exchanges or personal wallet users can expect to continue status quo operations without disruption by simply swapping binaries and restarting the node before May 2023, as long as they do not need the additional functionalities of Cashtokens and P2SH32. While Cashtokens and P2SH32 usage will already be possible after activation through custom software, exchanges looking to gain these capabilities may want to watch for a future release of BCHN that includes better support in the bundled wallet and RPC commands.
No post-activation tokens are going to be accidentally lost for any legacy operators who do not take any additional steps other than upgrading their nodes to this release.
Block explorer operators may begin to see transactions of a new and unfamiliar format in Cashtokens after upgrade activation. While these transactions should not impede status quo operations, operators may wish to modify their software in order to interpret the additional token information they carry.
This client release has a built-in expiry date of April 15, 2024, ie. a month ahead of the (tentative) next upgrade after May 2023. The expiry mechanism causes upgrade warnings to be issued, and preventively disables RPC if the software is run past the (tentative) scheduled upgrade date of May 2024.
Network changes
New test network supported: chipnet
A new chipnet
test network has been added to enable testing of all the new upgrade features (such as CashTokens, P2SH-32) ahead of the mainnet upgrade.
This network can be accessed by running with the -chipnet
option. It has activated the new features already, 6 months early, on 15 November, 2022.
Technically, it is a chain fork of 'testnet4', with much the same qualities. Its default ports are 48333, 48332, and 48334 for p2p, rpc, and onion respectively.
It retains the same cashaddr prefix as the other testnets: bchtest:
and the same legacy address checksum bytes. Like testnet4, it defaults to 2MB blocks and defaults to requiring standard txns for relay.
Further parameters are described in more detail in doc/test-networks.md
.
Historical discussion on its creation can be found here:
https://bitcoincashresearch.org/t/staging-chips-on-testnet
Seeders for this network should be started with -chipnet, and bitcoind should be started with -chipnet
and also have a section [chip]
for the new network.
Added functionality
32-byte Pay-to-Script-Hash (P2SH-32)
P2SH-32 (pay-to-scripthash 32) support has been added and consensus rules for this feature will activate on May 15, 2023.
This is a feature that provides more protection to certain smart contracts. It is currently only usable through the RPC interface, and sending is not enabled by default in the wallet functionality or accessible via the GUI, except through RPC commands. Receipt of P2SH-32 transactions is supported.
For more information on P2SH-32, see:
- CHIP-2022-05 P2SH32
- Discussion: https://bitcoincashresearch.org/t/chip-2022-05-pay-to-script-hash-32-p2sh32-for-bitcoin-cash/
'sort' command added to bitcoin-tx
The 'sort' command can be used to sort inputs and outputs according to BIP69.
Note that sorting usually requires re-signing (similar to other commands that mutate the transaction in some way).
BIP69 sorting is enabled by default in the wallet application.
Visual indication of transactions involved in Double Spend Proof
Upon arrival of a Double Spend Proof (DSProof), an application notification will be shown, additional information will be shown in the transaction list and transaction info window.
DSProof related transactions are indicated with a red color and an exclamation mark symbol in the graphical user interface.
Note: The GUI does not store information about transactions that have been double spent in the wallet.dat file. A restart of the GUI therefore clears the history and these transactions will look 'normal' again.
Deprecated functionality
Currently, standard relay rules restrict transaction versions to either 1 or 2.
After May 2023 upgrade, transaction versions will be restricted to be either 1 or 2 as a consensus rule, i.e. strictly enforced.
Therefore, applications that create transactions should not generate transaction versions other than 1 or 2, otherwise their transactions will be rejected after the upgrade.
Note: This is perhaps not strictly a deprecation, since we are not aware of any applications generating other transaction versions, but since consensus is being tightened up here, it seems prudent to mention it.
Modified functionality
New cash address formats for token-aware P2PKH and P2SH
Two new "address types" have been added to the cash address format.
These are described in the CashTokens v2.2.1 specification.
- TOKEN_PUBKEY (token-aware p2pkh, type=2)
- TOKEN_SCRIPT (token-aware p2sh, type=3)
The "address type" is encoded into the cashaddress string. Thus wallets wishing to signal token awareness will be required to
advertise their addresses using these two new "address types", making token-aware addresses distinct from the plain cash addresses.
For example the following p2pkh:
bitcoincash:qr6m7j9njldwwzlg9v7v53unlr4jkmx6eylep8ekg2
Could also be encoded as signaling token-awareness and it would look like this:
bitcoincash:zr6m7j9njldwwzlg9v7v53unlr4jkmx6eycnjehshe
Both of these addresses end up mapping to the same locking script.
Notes:
Token-aware addresses are not yet supported in the wallet database (wallet.dat). The bitcoin-qt wallet (and the RPC wallet) store addresses internally in the wallet.dat as "legacy" strings thus the "token awareness" of an address you sent to is "lost" in the UI or in RPC wallet history. So if one were to send to a 'z' address, when reading back the history one would be told it was a regular q address (same destination). This limitation will be removed in subsequent release to bring more token support.
The node wallet itself does not advertise these new "token aware" addresses when you ask it for a new receiving address, since at the
present time the wallet cannot actually manage and send tokens. The CashTokens specification says only wallets that can send tokens
may advertise these new type=2 and type=3 addresses. In future work we may add support for managing and sending CashTokens, at which time the wallet UI and RPC would be updated to advertise "token aware" addresses.
'getdsproofscore' DSProof scoring RPC
The 0.25 scoring criterion of the getdsproofscore
RPC has been extended to trigger if a transaction or any of its in-mempool ancestors happens to have a P2PKH input that is not signed with SIGHASH_ALL or is signed with SIGHASH_ANYONECANPAY (which indicates very weak DSProof protection).
As before this release, a value of 0.25 may also indicate that up to the first 20,000 unconfirmed ancestors were checked and all have no proofs but can have proofs. Since the transaction in question has a very large mempool ancestor set, double-spend confidence should be considered medium-to-low.
This value may also be returned for transactions which exceed depth 1,000 in an unconfirmed ancestor chain.
Two error messages have changed:
-
If the node receives a transaction that spends an UTXO with a locking script >10,000 bytes, the node now generates the error message
bad-txns-input-scriptpubkey-unspendable
. Previously it would generate the message
mandatory-script-verify-flag-failed (Script is too big)
-
Similarly, if the node receives a transaction that spends an
OP_RETURN
output, the node now generates the error message
bad-txns-input-scriptpubkey-unspendable
. Previously it would generate the message
mandatory-script-verify-flag-failed (OP_RETURN was encountered)
The reason for this change is that sometimes an oversized locking script ended up "looking like" an OP_RETURN
when read from the UTXO database. In that case, the pr...
24.1.0
Release Notes for Bitcoin Cash Node version 24.1.0
Bitcoin Cash Node version 24.1.0 is now available from:
Overview
This is a minor release of Bitcoin Cash Node (BCHN), containing:
- Upgrade of TOR network support from v2 to v3
- Upgrade checkpoints for May 15, 2022 upgrade
This version contains many further corrections and improvements and modifies the storage format of the internal peer database to accommodate new network address formats.
Usage recommendations
Users who are running v24.0.0 are encouraged to upgrade to v24.1.0. It offers up to date TOR network support, improves synching performance and fixes minor bugs.
MacOSX users who are running on OS versions prior Mojave (10.14), such as 10.12 or 10.13, and who are running 24.0.0 release binaries, are advised to keep running 24.0.0 until they can upgrade to Mojave.
Network changes
-
The Tor onion service that is automatically created by setting the
-listenonion
configuration parameter will now be created as a Tor v3 service instead of Tor v2. The private key that was used for Tor v2 (if any) will be left untouched in theonion_private_key
file in the data directory (see-datadir
) and can be removed if not needed. Bitcoin Cash Node will no longer attempt to read it. The private key for the Tor v3 service will be saved in a file namedonion_v3_private_key
. To use the deprecated Tor v2 service (not recommended), thenonion_private_key
can be copied overonion_v3_private_key
, e.g.cp -f onion_private_key onion_v3_private_key
. -
If using the
-listenonion=1
option (default: 1 if unspecified), then an additional new bindaddress:port
will be used for hidden-service-only incoming .onion connections. On mainnet, this will be 127.0.0.1:8334. This bind address is in addition to any-bind=
options specified on the CLI and/or in the config file.- To specify the local onion port to bind to explicitly, use the new syntax,
-bind=<HOST>:<PORT>=onion
. Seebitcoind -help
for more information on the new=onion
syntax which is used to specify local tor listening ports. - To not create an additional bind endpoint for tor, and/or to disable tor hidden service support, use
-listenonion=0
.
Note: As before, tor hidden services are always advertised publicly using a "generic" port for maximal anonymity (such as 8333 on mainnet, 18333 on testnet3, and so on). The
-bind=<HOST>:<PORT>=onion
syntax is to simply specify the local bind address which is connected-to privately by the localtor
process when a remote node connects to your .onion hidden service. - To specify the local onion port to bind to explicitly, use the new syntax,
Added functionality
-
Added wallet-tool
-
Added a new logging option,
-debug=httptrace
which logs all HTTP data to/from the internal JSON-RPC and REST server, including HTTP content.- This is an advanced debugging option intended for troubleshooting the low-level JSON-RPC and/or REST protocol, primarily aimed at developers.
- This option is not enabled by default, even if using
-debug=all
, and must be explicitly enabled using-debug=httptrace
. - Unlike the regular
-debug=http
debug option, incoming strings and data are not sanitized in any way in the log file, and are simply logged verbatim as they come in off the network.
Deprecated functionality
The setexcessiveblock
RPC method has been deprecated. Please use the excessiveblocksize
configuration option together with a restart of the node if you want to adapt this parameter.
An upgrade to Qt version 5.15.3 is planned for our next release. As a result, compatibility of the release binary with some older Linux platforms will be affected:
- Support for glibc versions older than 2.27 is now deprecated and may no longer be supported in a future release. This will impact older
platforms like CentOS 7, Debian 9, Mint 19, and Ubuntu 14 & 16. - Support for platforms that lack the X protocol C-language Binding library (libxcb) is deprecated, and future releases may require this library.
- This library seems available on most major Linux distributions but we urge you to check your node platform and notify us via a GitLab issue or via a comment on MR 1524 if you do not have this library.
If you are presently running on such older platforms, please upgrade to a newer OS version ahead of our next release.
Modified functionality
-
Netmasks that contain 1-bits after 0-bits (the 1-bits are not contiguous on the left side, e.g. 255.0.255.255) are no longer accepted. They are invalid according to RFC 4632.
-
The
-whitelistrelay
default has been restored to enabled. The help text indicated the default being enabled, despite the default actually being disabled. This has been broken since v22.0.0.
peers.dat file format
The node's known peers are persisted to disk in a file called peers.dat
. The format of this file has been changed in a backwards-incompatible way in order to accommodate the storage of Tor v3 and other BIP155 addresses. This means that if the file is modified by this version or newer then older versions will not be able to read it. Those old versions, in the event of a downgrade, will log an error message that deserialization has failed and will continue normal operation as if the file was missing, creating a new empty one.
Removed functionality
TORv2 support is replaced by TORv3.
New RPC methods
None.
User interface changes
peers.dat
file has changed format due to BIP155 / TORv3 support-blocksonly
option has been unhidden on bitcoind / bitcoin-qt command line helpwalletlock
,walletpassphrase
andwalletpassphrasechange
RPC methods were lacking documentation, which has been added.
Regressions
Bitcoin Cash Node 24.1.0 does not introduce any known regressions as compared to 24.0.0.
Known Issues
Some issues could not be closed in time for release, but we are tracking all of them on our GitLab repository.
-
MacOS versions earlier than 10.14 are no longer supported. Additionally, Bitcoin Cash Node does not yet change appearance when macOS "dark mode" is activated.
-
Windows users are recommended not to run multiple instances of bitcoin-qt or bitcoind on the same machine if the wallet feature is enabled.
There is risk of data corruption if instances are configured to use the same wallet folder. -
Some users have encountered unit tests failures when running in WSL environments (e.g. WSL/Ubuntu). At this time, WSL is not considered a supported environment for the software. This may change in future.
The functional failure on WSL is tracked in Issue #33. It arises when competing node program instances are not prevented from opening the same wallet folder. Running multiple program instances with the same configured walletdir could potentially lead to data corruption. The failure has not been observed on other operating systems so far.
-
doc/dependencies.md
needs revision (Issue #65). -
For users running from sources built with BerkeleyDB releases newer than the 5.3 which is used in this release, please take into consideration the database format compatibility issues described in Issue #34. When building from source it is recommended to use BerkeleyDB 5.3 as this avoids wallet database incompatibility issues with the official release.
-
The
test_bitcoin-qt
test executable fails on Linux Mint 20 (see Issue #144). This does not otherwise appear to impact the functioning of the BCHN software on that platform. -
With a certain combination of build flags that included disabling the QR code library, a build failure was observed where an erroneous linking against the QR code library (not present) was attempted (Issue #138).
-
Possible out-of-memory error when starting bitcoind with high excessiveblocksize value (Issue #156)
-
A problem was observed on scalenet where nodes would sometimes hang for around 10 minutes, accepting RPC connections but not responding to them (see Issue #210).
-
Startup and shutdown time of nodes on scalenet can be long (see Issue #313).
-
On Mac platforms with current Qt, the splash screen can be maximized, but it cannot be unmaximized again (see Issue #255). This issue will be resolved by a Qt library upgrade in a future release.
-
Race condition in one of the
p2p_invalid_messages.py
tests (see Issue #409). -
Occasional failure in bchn-txbroadcastinterval.py (see Issue #403).
-
wallet_keypool.py test failure when run as part of suite on certain many-core platforms (see Issue #380).
-
Spurious 'insufficient funds' failure during p2p_stresstest.py benchmark (see Issue #377).
-
bitcoin-tx
tool does not have BIP69 support (optional or enforced) yet (see Issue #383). -
secp256k1 now no longer works with latest openssl3.x series. There are workarounds (see [Issue Bitcoin-ABC#364](ht...
24.0.0
Release Notes for Bitcoin Cash Node version 24.0.0
Bitcoin Cash Node version 24.0.0 is now available from:
Overview
This is a major release of Bitcoin Cash Node (BCHN) that implements the May 15, 2022 Network Upgrade. This release implements the following two consensus CHIPs:
- CHIP-2021-03: Bigger Script Integers increased precision for arithmetic operations.
- CHIP-2021-02: Native Introspection Opcodes enabling smart contracts to inspect the current transaction.
This version contains further corrections and improvements, such as:
- BIP69 (privacy) lexicographical sorting of transaction inputs/outputs
- A new wallet RPC call attribute ('include_unsafe') which enables creation of transactions which spend unconfirmed outputs (the default is still to spend only confirmed transactions)
- New settings, confirmation and error messages for the GUI to detect and warn the user about error-prone legacy address types.
- Update of the seeds and addition of a new seeder (bitjson.com)
Users who are running any of our previous releases (23.x.y) are urged to upgrade to v24.0.0 ahead of May 2022.
Usage recommendations
The update to Bitcoin Cash Node 24.0.0 is required for the May 15, 2022 Bitcoin Cash network upgrade.
Network changes
This release brings two consensus CHIPs (increased precision for arithmetic operations and native introspection opcodes) and one optional network change - BIP69 - the sorting of inputs and output in transactions generated by the wallet.
The first two (consensus changes) take effect with the upgrade in 15 May 2022.
BIP69 is effective immediately and enabled by default in this release. The pre-BIP69 behavior can be obtained by passing -usebip69=0
on startup.
Added functionality
-
After activation of the May 2022 upgrade, smart contract designers will be able to use OP_MUL, native introspection opcodes and higher-precision integers in Script code.
-
coinsel
option has been added tosendmany
RPC call. This was done to keep uniformity with 'sendtoaddress'. -
A new option
-usebip69
has been added to toggle BIP69 usage (it is enabled by default). This sorts the inputs and outputs of a transaction
in lexicographical order to increase transactional privacy. -
The
fundrawtransaction
,sendmany
,sendtoaddress
andwalletcreatefundedpsbt
RPCs now support aninclude_unsafe
option that, whentrue
, allows using "unsafe inputs" to fund the transaction. The term "unsafe inputs" is a synonym for unconfirmed inputs not originating from the wallet. Note that the resulting transaction may become invalid if one of the "unsafe" inputs disappears due to a double-spend. This is a very unlikely scenario, however, on account of the strong zero-conf properties of the BCH network. However, if that happens, the transaction must be funded with different inputs and republished. -
Two new options have been added to make legacy address handling safer in the GUI wallet: "Allow legacy P2PKH addresses" under Options > Wallet and the
-allowlegacyp2sh
configuration option. -
A new CLI argument
-bytespersigcheck
has been introduced (conf file:bytespersigcheck
). It is identical to the existing argument-bytespersigop
(which has been deprecated), and the two arguments are now aliases for one other. -
A new option
-upgrade9activationtime
has been added to control the timestamp of the tentative upgrade in May 2023. This value is also used
to set the software expiry time.
Deprecated functionality
- The CLI argument
-bytespersigop
(conf file:bytespersigop
) has been deprecated. Use-bytespersigcheck
instead.
Modified functionality
- The software expiry deadline has now been shifted from 15 May 2022 to 15 May 2023.
Removed functionality
autotools build system
The autotools build system is no longer supported by BCHN and has been removed. Please use the CMake / ninja build system.
Mempool acceptance 'height' field in RPC calls
The getmempoolentry
RPC call, the verbose modes of the getrawmempool
/getmempoolancestors
/getmempooldescendants
RPC calls, and the JSON mode of the mempool REST call no longer include the height
field. This used to indicate the block height upon mempool acceptance. However, it was not guaranteed to be accurate after a node restart or reorg, thus limiting its usefulness. Since it has been marked as deprecated for some time, it has been removed in the interests of efficiency.
No more PPA support for Ubuntu 16.04
Ubuntu 16.04 is no longer supported via a PPA.
Users are encouraged to migrate to a more recent version of Ubuntu if they wish to use the Ubuntu PPAs.
Users who wish to compile from source are advised that the autotools build system is no longer supported from this release onwards.
New RPC methods
None.
User interface changes
Legacy address handling has been made safer in the GUI wallet. The aim is to save users from losing coins while using the error-prone legacy P2PKH and P2SH address types.
Such receiving address types are detected and the user is given relevant confirmation dialogs and error messages. For this legacy address handling, two new settings are introduced, one for P2PKH and one for P2SH addresses, to configure whether or not use of these legacy address types is allowed. These settings are:
- "Allow legacy P2PKH addresses" under Options > Wallet
-allowlegacyp2sh
configuration option
Regressions
Bitcoin Cash Node 24.0.0 does not introduce any known regressions as compared to 23.1.0.
Known Issues
Some issues could not be closed in time for release, but we are tracking all of them on our GitLab repository.
-
MacOS versions earlier than 10.12 are no longer supported. Additionally, Bitcoin Cash Node does not yet change appearance when macOS "dark mode" is activated.
-
Windows users are recommended not to run multiple instances of bitcoin-qt or bitcoind on the same machine if the wallet feature is enabled.
There is risk of data corruption if instances are configured to use the same wallet folder. -
Some users have encountered unit tests failures when running in WSL environments (e.g. WSL/Ubuntu). At this time, WSL is not considered a supported environment for the software. This may change in future. The functional failure on WSL is tracked in Issue #33. It arises when competing node program instances are not prevented from opening the same wallet folder. Running multiple program instances with the same configured walletdir could potentially lead to data corruption. The failure has not been observed on other operating systems so far.
-
doc/dependencies.md
needs revision (Issue #65). -
test_bitcoin
can collide with temporary files if used by more than one user on the same system simultaneously. (Issue #43) -
For users running from sources built with BerkeleyDB releases newer than the 5.3 which is used in this release, please take into consideration the database format compatibility issues described in Issue #34. When building from source it is recommended to use BerkeleyDB 5.3 as this voids wallet database incompatibility issues with the official release.
-
The
test_bitcoin-qt
test executable fails on Linux Mint 20 (see Issue #144). This does not otherwise appear to impact the functioning of the BCHN software on that platform. -
With a certain combination of build flags that included disabling the QR code library, a build failure was observed where an erroneous linking against the QR code library (not present) was attempted (Issue #138).
-
Some functional tests are known to fail spuriously with varying probability. (see e.g. Issue #148, and a fuller listing in Issue #162).
-
Possible out-of-memory error when starting bitcoind with high excessiveblocksize value (Issue #156)
-
A problem was observed on scalenet where nodes would sometimes hang for around 10 minutes, accepting RPC connections but not responding to them (see Issue #210).
-
Startup and shutdown time of nodes on scalenet can be long (see Issue #313).
-
On some platforms, the splash screen can be maximized, but it cannot be unmaximized again (see Issue #255). This has only been observed on Mac OSX, not on Linux or Windows builds.
-
There is an issue with
git-lfs
that may interfere with the refreshing of source code checkouts which have not been updated for a longer time (see Issues #326, #333). A known workaround is to do a fresh clone of the repository.
Changes since Bitcoin Cash Nod...
23.1.0
Release Notes for Bitcoin Cash Node version 23.1.0
Bitcoin Cash Node version 23.1.0 is now available from:
Overview
This is a minor release of Bitcoin Cash Node (BCHN) containing several minor bugfixes and some performance improvements, such as:
- Mempool: 40% performance speedup in removing confirmed txs and multiple speedups for other operations as well.
- Mempool: removal of all pre-May 15 2021 logic and data structures, including structures dealing with unconfirmed ancestor limits, saving memory and CPU cycles.
- Scalenet: Ensure the "disconnected block transactions" pool has enough memory.
- Added the JSON-RPC command:
getdsproofscore
. - Save known DSProofs across restarts to
dsproofs.dat
. - Fixed misspelling of "hexstring" param name in the "signrawtransactionwithwallet" method.
- Fix bug where
-txbroadcastinterval=0
would lead to a numerical singularity where no txs were sent. Instead, with this arg at 0, txs are now just sent as quickly as possible. - Remove
-tachyonactivationtime
from CLI args & consensus rules. - DSProofs: Bug fix where sometimes nodes would "discourage" each other incorrectly after they clean up expired proofs.
- Mining: Add
-gbtcheckvalidity
arg to CLI;"checkvalidity"
arg to GBT/GBTL. - Mining: Fix potential crash in
submitblock
if 2 RPC threads are submitting a block simultaneously. - Speedup to block validation and tx validation by removing a redundant map lookup when checking inputs.
Usage recommendations
Users who are running v22.x.x or earlier are strongly urged to upgrade to v23.1.0, since the v22 series (and previous) do not implement the recent May 15, 2021 Network Upgrade. Users running v23.0.0 may also wish to upgrade to this version, since it does improve performance and does fix some minor bugs.
Network changes
A minor bug has been corrected where in some corner cases P2P nodes may end up "discouraging" each other incorrectly when an old DSProof is removed after a block is confirmed.
Added functionality
- Double-spend proofs now are persisted across restarts to a file in the data directory called
dsproofs.dat
. The mechanism for this is similar to how the mempool is already persisted across restarts. Double-spend proofs are not persisted if the node was started with-persistmempool=0
or-doublespendproof=0
.
gbtcheckvalidity
configuration option and checkvalidity
RPC arg
This new command-line option (as well as its counterpart RPC arg) may be of interest to miners. With -gbtcheckvalidity=0
(or RPC arg checkvalidity=false
to the getblocktemplate
/getblocktemplatelight
RPC), all validity checks on a new block template are skipped. This saves significant time in generating a new block template (50% or greater speedup for large blocks).
The validity checks are redundant "belt-and-suspenders" checks -- and it should never be the case that this codebase produces an "invalid" block in getblocktemplate
. Producing an invalid block that fails these checks would be a serious bug in this codebase. As such, these checks can be optionally skipped for the intrepid miner wishing to maximize performance and minimize latency to getblocktemplate
and/or getblocktemplatelight
.
The default for these options is to preserve the status-quo (default: -gbtcheckvalidity=1
and/or checkvalidity=true
to the RPC), and perform these (redundant) validity checks on new block templates.
Deprecated functionality
In the getmempoolentry
RPC call, the verbose modes of the getrawmempool
/getmempoolancestors
/getmempooldescendants
RPC calls, and the JSON mode of the mempool REST call, the height
field is deprecated and will be removed in a subsequent release. This field indicates the block height upon mempool acceptance.
The bip125-replaceable
field in the result of gettransaction
is deprecated and will be removed in a subsequent release.
The arc lint
linting is deprecated and developers should use the ninja check-lint
target instead.
Modified functionality
The CLI/conf arg -txbroadcastinterval=0
would previously lead to a situation where the node would never relay transactions. This is considered a bug and has been corrected. Now, if the node operator specifies -txbroadcastinterval=0
, the node relays transactions as quickly as possible.
Removed functionality
The CLI arg -tachyonactivationtime
has been removed. All relay rules behave as if "tachyon" (the internal name for the May 15, 2021 network upgrade) has always been active.
The following CLI args (all related to the now-removed ancestor limit) have been removed: -walletrejectlongchains
, -limitdescendantcount
, -limitancestorcount
, -limitdescendantsize
, -limitancestorsize
.
New RPC methods
getdsproofscore
getdsproofscore
returns a double-spend confidence score for a mempool transaction.
This new method should help merchant or wallet server implementors quickly decide if a transaction is reliable for 0-conf (1.0: has no DSProofs and is eligible for DSProof mechanism), or is unreliable for 0-conf (<1.0: has DSProofs, or is ineligible for the DSProof mechanism, or has a very long ancestor chain).
Please refer to the documentation pages for getdsproofscore for details about additional arguments and the returned data.
Low-level RPC changes
The getmempoolancestors
and getmempooldescendants
RPC methods now return a list of transactions that are sorted topologically (with parents coming before children). Previously they were sorted by transaction ID.
Mempool entries from the verbose versions of: getrawmempool
, getmempoolentry
, getmempoolancestors
, and getmempooldescendants
which contain a spentby
key now have the transactions in the spentby
list sorted topologically (with parents coming before children). Previously this list was sorted by transaction ID.
The getblocktemplate
and getblocktemplatelight
template-request dictionary now accepts an additional key: checkvalidity
(default if unspecified: true). If set to false, then validity checks for the generated block template are skipped (thus leading to a faster return from the RPC call).
User interface changes
Bitcoin Cash Node 23.1.0 does not introduce any user interface changes as compared to 23.0.0.
Regressions
Bitcoin Cash Node 23.1.0 does not introduce any known regressions as compared to 23.0.0.
Known Issues
Some issues could not be closed in time for release, but we are tracking all of them on our GitLab repository.
-
MacOS versions earlier than 10.12 are no longer supported. Additionally, Bitcoin Cash Node does not yet change appearance when macOS "dark mode" is activated.
-
Windows users are recommended not to run multiple instances of bitcoin-qt or bitcoind on the same machine if the wallet feature is enabled. There is risk of data corruption if instances are configured to use the same wallet folder.
-
Some users have encountered unit tests failures when running in WSL environments (e.g. WSL/Ubuntu). At this time, WSL is not considered a supported environment for the software. This may change in future. The functional failure on WSL is tracked in Issue #33. It arises when competing node program instances are not prevented from opening the same wallet folder. Running multiple program instances with the same configured walletdir could potentially lead to data corruption. The failure has not been observed on other operating systems so far.
-
doc/dependencies.md
needs revision (Issue #65). -
test_bitcoin
can collide with temporary files if used by more than one user on the same system simultaneously. (Issue #43) -
For users running from sources built with BerkeleyDB releases newer than the 5.3 which is used in this release, please take into consideration the database format compatibility issues described in Issue #34. When building from source it is recommended to use BerkeleyDB 5.3 as this avoids wallet database incompatibility issues with the official release.
-
The
test_bitcoin-qt
test executable fails on Linux Mint 20 (see Issue #144). This does not otherwise appear to impact the functioning of the BCHN software on that platform. -
An 'autotools' build (the old build method) fails on OSX when using Clang. (Issue #129)
-
With a certain combination of build flags that included disabling the QR code library, a build failure was observed where an erroneous linking against the QR code library (not present) was attempted (Issue #138).
-
The 'autotools' build is known to require some workarounds in order to use the 'fuzzing' build feature (Issue #127).
-
Some functional tests are known to fail spuriously with varying probability. (see e.g. issue #148, and a fuller listing in #162).
-
Possible out-of-memory error when starting bitcoind with high excessiveblocksize value (Issue #156)
-
There are obstacles building the current version on Ubuntu 16.04 (see [Bitcoin-ABC#187](https://git...
23.0.0
Release Notes for Bitcoin Cash Node version 23.0.0
Bitcoin Cash Node version 23.0.0 is now available from:
Overview
This is a major release of Bitcoin Cash Node (BCHN) that implements the May 15, 2021 Network Upgrade. This upgrade will remove the unconfirmed chain limit and enable transactions with multiple OP_RETURN outputs.
This version contains many corrections and improvements, such as:
- Introducing the Double Spend Proof (beta) feature compatible with other clients
- Removing the limits on number of unconfirmed ancestors and descendants, and the limits on the byte size of these chains
- Raising the default soft limit for block generation to 8MB
- Adding support for multiple OP_RETURN standardness (within existing data carrier size)
- Removal of CPFP functionality
- Changes in mempool eviction order
- New ZMQ functionality (related to dsproof)
- Minor RPC additions and changes (incl. dsproof related)
- Minor changes in error codes
- Improving the graphical user interface
- Extension of software expiry timeframe (to 15 May 2022)
- Switch from C++14 to C++17
Users who are running any of our previous releases (0.22.x) are urged to upgrade to v23.0.0 ahead of May 2021.
Usage recommendations
The update to Bitcoin Cash Node 23.0.0 is required for the May 15, 2021 Bitcoin Cash network upgrade.
About the CPFP & unconfirmed chain limit removal
The CPFP (child-pays-for-parent) and the unconfirmed transaction chain limit will both be deactivated on May 15, 2021 when MTP of the chain tip reaches 12:00 UTC. After that time, it will be possible to "chain" unconfirmed transactions beyond the current limit of 50, in a limitless way, without any negative performance consequence for the node.
This has been accomplished by removing the algorithmically complex and slow code we inherited from Bitcoin Core which tries to maintain what is known as "Child Pays for Parent" (CPFP) -- a way in which a child transaction can bump up the priority of its parent transaction via paying a larger fee. Maintaining this feature, which is not even being used on BCH, was the reason for the algorithmic complexity in the mempool code and why we had a limit of 50 for unconfirmed tx chains.
Additionally, we removed a lot of the slow "quadratic" (complex) per-tx stats that were being maintained (also inherited from Core, and also used in fee calculations). Removing those stats, which only were added so that Core could limit the blocksize and also get a hyper-fee-market, allowed us to unleash the true scalability of BCH. The mempool code was slow -- and it was only slow because of Bitcoin Core's philosophy about what Bitcoin should be.
One might wonder if allowing limitless unconfirmed transaction chains opens up avenues of attack or flood/DoS. It does not do this. Since now our mempool and mining algorithm is linear and not quadratic, there is no real difference between a transaction that has an unconfirmed parent and one that does not. They both now cost the same amount of CPU time to process (and in some cases the unconfirmed parent tx is actually faster to process due to not needing to hit the UTXO db).
Should some user perform a (costly) attack and flood the network with unconfirmed tx chains, the only consequence will be that he will drain his own resources in fees. Under mempool pressure, normal fee bump logic occurs. Transactions get evicted in a "lowest fee first" order and then the mempool's minimum fee for acceptance is bumped up by some small increment. This logic has always been in place and is the way we prevent floods.
In summary, removing the unconfirmed tx chain limit does not impact performance and/or availability whether under normal usage or under congestion.
Network changes
The dsproof-beta
network message can be emitted and relayed when Double Spend Proofs are enabled (which they are by default).
For miners/pools running without a blockmaxsize configuration, the default soft limit of generated blocks will increase from 2MB to 8MB in this update. The default hard limit of 32MB remains unchanged in this release.
Added functionality
Double Spend Proofs (DSProof)
This release adds Double Spend Proofs that are compatible with the published dsproof-beta
message specification and existing implementations in Bitcoin Unlimited and Flowee The Hub.
Double spend proofs are enabled by default, but can be turned off with the doublespendproof=0
configuration setting.
This functionality is still in beta. In future BCHN releases we plan to gradually add more application interfaces to query double spend proof information about transactions and to provide wallet user with double spend notifications.
Please refer to <doc/dsproof-implementation-notes.md> for more information details on the DSProof implementation in BCHN, and the sections on New RPC methods and New ZeroMQ notifications below for a listing of the new API calls.
maxgbttime
and maxinitialgbttime
configuration options
These two new command-line options may be of interest to miners (pools). They enable setting maximum time limits for getblocktemplate calls, instead of relying on blockmaxsize limits to limit the time taken to construct a template.
The -maxinitialgbttime
setting determines the maximum number of milliseconds that can be spent adding transactions to block templates for the first template after an UpdateTip, whereas the -maxgbttime
setting does the same thing but for all block templates
(not just the first).
This should allow pools to create larger block sizes on average without taking on significantly greater costs and risks.
The default settings for -max*gbttime
are both 0 in this release, so it has no effect on node behavior when the default options are used.
-rejectsubversion
configuration option
This can be used to reject peers which have certain fixed strings in their user agents. Useful for blocking non-compatible SV and ABC
peers. The option can be specified multiple times to filter several matches.
Example:
bitcoind -rejectsubversion="Bitcoin SV" -rejectsubversion="Bitcoin ABC"
Care should be taken to filter out only peers which are definitely not useful to your Bitcoin Cash node.
Deprecated functionality
In the getmempoolentry
RPC call, the verbose modes of the getrawmempool
/getmempoolancestors
/getmempooldescendants
RPC calls, and the JSON mode of the mempool REST call, the height
field is deprecated and will be removed in a subsequent release. This field indicates the block height upon mempool acceptance.
The bip125-replaceable
field in the result of gettransaction
is deprecated and will be removed in a subsequent release.
The arc lint
linting is considered deprecated and developers should use the ninja check-lint
target instead.
Modified functionality
Mempool expiry works slightly differently now. Previously, the expiry of an old mempool tx would be checked thoroughly every time a new tx was accepted to the mempool, but this consumed a bit of extra memory to accomplish precisely and efficiently. Instead, we save on memory by doing a fast (imprecise) check each time a new tx is added to the mempool. This check may miss some txs that should be expired. In order to catch those txs, we now also run a perfect (slower) expiry check of the mempool periodically. A new CLI arg, -mempoolexpirytaskperiod=
was added to control the frequency of this thorough check (in hours). The new argument's default value is "24" (once per day).
Removed functionality
Manpages are no longer available in the autotools build system. You must switch to the CMake build system to continue using manpages. Note the autotools build system has been deprecated since v22.0.0.
New RPC methods
validateblocktemplate
The 'validateblocktemplate' RPC call has been added. This call checks if a block template would be accepted if the hash solution
were solved. The semantics of this call are the same as on BCHUnlimited from where a substantial portion of this new functionality has been ported. It is intended to be used by services that test compatibility of block generation with BCHN's consensus rules.
getdsproof
and getdsprooflist
getdsproof
retries more information about a specific double spend proof.
getdsprooflist
lists the double spend proofs that are known about transactions in the node's mempool.
Please refer to the documentation pages for getdsproof and getdsprooflist for details about additional arguments and the returned data.
New ZeroMQ (ZMQ) notifications
BCHN can now publish notification of both hashes and full raw double spend proofs generated or accepted by the node.
The notifications can be enabled via the -zmqpubhashds=address
and -zmqpubrawds=address
configuration options where address
must be a valid ZeroMQ endpoint. Please refer to the ZMQ API documentation for further details.
Low-level RPC changes
The getblockstats
RPC is faster for fee calculation by using BlockUndo data. Also, -txindex
is no longer required and getblockstats
works for all non-pruned blocks.
In the getmempoolentry
RPC call, the verbose modes of the getrawmempool
/getmempoolancestors
/getmempooldescendants
RPC calls, and the JSON mode of the mempool REST call, the fields fee
and modifiedfee
are removed. These fields were deprecated since v0.20.4. Please use the fees
subobject instead.
The (non-default) option in the getnetworkhashps
RPC call to calculate average hashrate using "blocks since last difficulty change" has been re...