Release Notes for Bitcoin Cash Node version 28.0.0

Bitcoin Cash Node version 28.0.0 is now available from:

https://bitcoincashnode.org

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.

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 an index_name
  to specify returning only the status of that index.

User interface changes

• RPC: Added input tokenData and scriptPubKey to RPC method getrawtransaction with verbosity=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:

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

2. Transactions with SIGHASH_UTXO are not covered by DSProofs at present.

3. P2SH-32 is not used by default in the wallet (regular P2SH-20 remains
   the default wherever P2SH is treated).

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

5. 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).

Changes since Bitcoin Cash Node 27.1.0

New documents

None

Removed documents

None

Notable commits grouped by functionality

Security or consensus relevant fixes

• 8ec4568 [net] Ignore unlikely timestamps in version messages
• 9914660 p2p: Don't use timestamps from inbound peers
• b5b6c27 Implement CHIP-2021-05-vm-limits: Targeted Virtual Machine Limits
• 697725b Implement CHIP-2024-07-BigInt: High-Precision Arithmetic for Bitcoin Cash (on top of VM Limits)

Interfaces / RPC

• a89d5fd RPC: Add input tokenData and scriptPubKey to getrawtransaction verbosity=2
• 71bf5fc net: Keep trying to use UPnP when -upnp=1
• c66609c net: Add libnatpmp support
• 82a5e52 net: Add -natpmp command line option
• 6f2b9b7 rpc: Add getindexinfo RPC

Features in internal development: support for UTXO commitments

None

Data directory changes

None

Performance optimizations

• 9f2f535 Minor optimization in OP_CHECKDATASIG* -- avoid a extra copy
• c967c23 net_processing: Avoid reading the block for MSG_FILTERED_BLOCK if no filter
• 6772bc4 [backport] http: set TCP_NODELAY when creating HTTP server
• ef5347e Update static seeds in preparation for v28 release
• 567b0fc Update checkpoints for v28.0.0 release
• faf18dd Update "assume valid" and "minimum chain work" for v28.0.0 release

GUI

• a6f94bd gui: Apply port mapping changes on dialog exit
• d0c1dbc gui: Add NAT-PMP network option

Code quality

• 0228ea5 [backport] Introduce utility function SysErrorString
• 06aaa05 Replace all usages of thread-unsafe strerror() with SysErrorString()
• 861aeb6 Bugfix: Fix potential UB in AddToCompactExtraTransactions in net_processing.cpp
• 0dc085d Fix compiler error in blockstorage.cpp for older compilers such as on ubuntu bionic
• a2d1054 fs: use the correct Boost versions for deprecated functionality check
• f8577fa backport: refactor: Cleanup thread ctor calls
• 667fc6a refactor: Move port mapping code to its own module
• ebacf9c net: Add flags for port mapping protocols
• f167208 Ensure natpmp unmapping of ports follows RFC 6886 and sets eport to 0
• 6054f2c backport: Fix compile warning, fix UB, and optimize CoinUndoSpend
• ba4282b Trivial: Fix some compiler warnings seen on GCC 14.2.1
• 5f0e053 net: Future-proof and prevent UB in CConnMan::SocketSendData for >2GiB messages
• 21c5ae9 util: Disallow negative mocktime
• 8668afb net: Avoid UBSan warning in ProcessMessage(...)
• 5831ef1 Trivial: Fix compiler warning on GCC 14.2 in src/bench/chained_tx.cpp
• 5a8c2a1 Prevent UB in index/base.* my removing pure virtual GetName() function
• 5a94f01 fuzz: Fix linking of fuzz.cpp and G_TRANSLATION_FUN
• a858b58 Nit in blockencodings.h: get rid of C-style typedef enum declaration
• 5056ff9 refactor: Move class BlockValidationOptions to consensus/validation.h

Documentation updates

• 94bcb55 Update documentation and gitian-build.py to reflect new workflow.
• baa4707 doc: Add release notes for getindexinfo RPC

Build / general

• 783fbe9 backport: [GITIAN] Pull gitian sources in our repo
• fc47c4b build: Propagate well-known vars into depends
• 60c0984 build: use C++17 in depends
• 6a3c14f depends: Split boost into build/host packages + bump + cleanup
• 25ef17b Fixup to toolchain files to get them to see the depends boost lib
• 761c285 [GITIAN] Don't ignore target-bin/
• 9ad5002 Suppress linting for gitian-builder
• 9dddaf8 [backport] cmake: define STRERROR_R_CHAR_P
• 4c4e89b backport: upgrade to miniupnpc 2.2.2
• b59af94 gitian: Disable NATPMP when building package sources
• 3b973ee Add config to disable test_bitcoin & bench_bitcoin
• 9ecd9c4 Bump version to 28.0.0

Build / Linux

None

Build / Windows

None

Build / MacOSX

None

Tests / test framework

• 0cd881a LibAuth tests: Rename/refactor to support dropping-in of non-CHIP tests & benchmarks
• 58c90ea Imported latest LibAuth regression tests for the "2023" VM.
• 81cd2b1 Put test_bitcoin common files into a library, use with bench_bitcoin
• d2f65fe tests: fix linting error in test_framework
• ecebf50 tests: fix wallet_multiwallet invalid wallet path expected message
• a09d04e Update LibAuth test vector and benchmark scheme (on top of BigInt + VMLimits CHIP)
• 3fbe538 rpc: Add getindexinfo RPC
• c9a7d18 tests: Add FuzzedDataProvider fuzzing helper from the Chromium project
• 790459c tests: Add fuzz utility header fuzz/util.h
• 492a6de [block encodings] Make CheckBlock mockable for PartiallyDownloadedBlock
• cf5cdf1 [block encodings] Avoid fuzz blocking asserts in PartiallyDownloadedBlock
• e357f54 Add fuzz/util function: ConsumeMempoolEntry
• 86237a0 fuzz: Add PartiallyDownloadedBlock target

Benchmarks

• 1599f4b bench: nit: Don't double-copy in VerifyScript.* benchmarks
• 4c784dd Added detection of "benchmark" and "baseline" LibAuth tests
• ea14cc6 Enable running the LibAuth benchmarks in bench_bitcoin
• 0bd8a58 bench: Support printing of supplemental stats; use this mechanism for LibAuth benches

Seeds / seeder software

• 6ebd566 seeder: Don't use std::rand(); it's not guaranteed thread-safe
• 08e4c30 seeder: Refactor C-style polymorphism -> C++ for CDnsThread
• 6693b7b seeder: Fix potential UB/race condition when starting DNS threads
• 9411c7a seeder: Fix bug where if DNS server can't start, app is silent with no indication of error
• e5c1c54 seeder: Refactor saving guts of ThreadDumper() to a separate function.
• 2dc062e seeder: Resurrect the (long deleted) "CAddrDb::Skipped" function(s)
• 402e22d seeder: Fix potential C++ UB by avoiding passing pointers through void *
• 7653e18 seeder: Refactor to use std::thread instead of pthread where appropriate
• 9e511fe seeder: Gracefully exit and always persist db immediately on exit
• f1ce09f Fixed a rare crash bug when process runs out of file descriptors
• a3a9c12 Use SysErrorString instead of strerror

Maintainer tools

• 7be3d54 lint: Add check for usage of strerror in the codebase
• 2e02b90 Add release notes 27.1.0 to docs site navigation
• 57d383e linter: Check for C header includes
• 4ff1b5d linter: Check for C-style void parameter
• ce905c2 linter: Source files must match naming convention
• 1403bc5 linter: avoid locale dependencies
• 4a9a82e Nuke lint-local-dependencies
• f181772 Nuke lint-cpp-void-parameters

Infrastructure

None

Cleanup

• 5cd2121 scripted-diff: Rename UPnP stuff
• b007a9c net: Add NAT-PMP to port mapping loop
• edc974e Bump node expiry to May 2026, add new -upgrade12activationtime.
• 48fbce1 Upgrade12: Update activation_tests, test_bitcoin, and the g_upgrade*tracker
• 0c2bc76 Fix ninja target: check-upgrade-activated
• 336132a net: remove is{Empty,Full} flags from CBloomFilter, clarify CVE fix

Continuous Integration (GitLab CI)

• 1975b09 CI: update to use libnatpmp

Compatibility

• 3eb874e [backport] upnp: add compatibility for miniupnpc 2.2.8
• 4f4fc44 depends: Fix boost compile error for aarch64 & arm with newer gcc
• dd85313 Drop support for 32-bit platforms

Backports

• 783fbe9 backport: [GITIAN] Pull gitian sources in our repo
• fc47c4b build: Propagate well-known vars into depends
• 60c0984 build: use C++17 in depends
• 6a3c14f depends: Split boost into build/host packages + bump + cleanup
• 761c285 [GITIAN] Don't ignore target-bin/
• 9dddaf8 [backport] cmake: define STRERROR_R_CHAR_P
• 0228ea5 [backport] Introduce utility function SysErrorString
• 06aaa05 Replace all usages of thread-unsafe strerror() with SysErrorString()
• 3eb874e [backport] upnp: add compatibility for miniupnpc 2.2.8
• 4c4e89b backport: upgrade to miniupnpc 2.2.2
• f8577fa backport: refactor: Cleanup thread ctor calls
• 667fc6a refactor: Move port mapping code to its own module
• 71bf5fc net: Keep trying to use UPnP when -upnp=1
• ebacf9c net: Add flags for port mapping protocols
• 5cd2121 scripted-diff: Rename UPnP stuff
• a6f94bd gui: Apply port mapping changes on dialog exit
• c66609c net: Add libnatpmp support
• b007a9c net: Add NAT-PMP to port mapping loop
• 82a5e52 net: Add -natpmp command line option
• d0c1dbc gui: Add NAT-PMP network option
• 6054f2c backport: Fix compile warning, fix UB, and optimize CoinUndoSpend
• 8ec4568 [net] Ignore unlikely timestamps in version messages
• 9914660 p2p: Don't use timestamps from inbound peers
• 21c5ae9 util: Disallow negative mocktime
• 8668afb net: Avoid UBSan warning in ProcessMessage(...)
• 6772bc4 [backport] http: set TCP_NODELAY when creating HTTP server
• 6f2b9b7 rpc: Add getindexinfo RPC
• 3fbe538 rpc: Add getindexinfo RPC
• baa4707 doc: Add release notes for getindexinfo RPC
• 5a8c2a1 Prevent UB in index/base.* my removing pure virtual GetName() function
• 336132a net: remove is{Empty,Full} flags from CBloomFilter, clarify CVE fix
• c9a7d18 tests: Add FuzzedDataProvider fuzzing helper from the Chromium project
• 790459c tests: Add fuzz utility header fuzz/util.h
• 492a6de [block encodings] Make CheckBlock mockable for PartiallyDownloadedBlock
• cf5cdf1 [block encodings] Avoid fuzz blocking asserts in PartiallyDownloadedBlock
• e357f54 Add fuzz/util function: ConsumeMempoolEntry
• 86237a0 fuzz: Add PartiallyDownloadedBlock target