Merge bitcoin/bitcoin#33201: Add functional test for IPC interface

glozow · glozow · commit e04cb9c1bdf2 · 2025-09-05T13:00:46.000-04:00
a341e11 ci: test IPC on additional hosts (Sjors Provoost) 6aee573 ci: enable IPC tests in CI (Pieter Wuille) 8d2ee88 tests: add functional tests for IPC interface (Pieter Wuille) 3cc9a06 test: Add TestNode ipcbind option (Ryan Ofsky) 3cceb60 test: Provide path to `bitcoin` binary (Ryan Ofsky) 8c7f005 test: add is_ipc_compiled() and skip_if_no_ipc() functions (Ryan Ofsky) Pull request description: This adds support to the functional test framework to run the multiprocess `bitcoin-node` binary, and then tests it in a new `interface_ipc.py` functional test through the `pycapnp` module. ACKs for top commit: Sjors: ACK a341e11 ryanofsky: Code review ACK a341e11. Changes since last review: rebasing, switching to miniwallet and expanding wallet test, improving pycapnp install steps in instructions and CI. TheCharlatan: ACK a341e11 Tree-SHA512: 98330283cf0d66d5537eec1219345b8aec5740dbc2171bd8b70680d7a282e0962fcdf0588a75518110761e8bc95af57d6097c93937cac710805b0df10837093c
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -95,6 +95,7 @@ jobs:
       - run: |
           sudo apt-get update
           sudo apt-get install clang mold ccache build-essential cmake ninja-build pkgconf python3-zmq libevent-dev libboost-dev libsqlite3-dev systemtap-sdt-dev libzmq3-dev qt6-base-dev qt6-tools-dev qt6-l10n-tools libqrencode-dev capnproto libcapnp-dev -y
+          sudo pip3 install --break-system-packages pycapnp
       - name: Compile and run tests
         run: |
           # Run tests on commits after the last merge commit and before the PR head commit
@@ -152,6 +153,11 @@ jobs:
           brew install --quiet python@3 || brew link --overwrite python@3
           brew install --quiet coreutils ninja pkgconf gnu-getopt ccache boost libevent zeromq qt@6 qrencode capnp
 
+      - name: Install Python packages
+        run: |
+          git clone -b v2.1.0 https://github.com/capnproto/pycapnp
+          pip3 install ./pycapnp -C force-bundled-libcapnp=True --break-system-packages
+
       - name: Set Ccache directory
         run: echo "CCACHE_DIR=${RUNNER_TEMP}/ccache_dir" >> "$GITHUB_ENV"
 
@@ -275,6 +281,7 @@ jobs:
         if: matrix.job-type == 'standard'
         working-directory: build
         env:
+          BITCOIN_BIN: '${{ github.workspace }}\build\bin\Release\bitcoin.exe'
           BITCOIND: '${{ github.workspace }}\build\bin\Release\bitcoind.exe'
           BITCOINCLI: '${{ github.workspace }}\build\bin\Release\bitcoin-cli.exe'
           BITCOINTX: '${{ github.workspace }}\build\bin\Release\bitcoin-tx.exe'
diff --git a/ci/test/00_setup_env_native_asan.sh b/ci/test/00_setup_env_native_asan.sh
@@ -20,7 +20,8 @@ fi
 
 export CONTAINER_NAME=ci_native_asan
 export APT_LLVM_V="21"
-export PACKAGES="systemtap-sdt-dev clang-${APT_LLVM_V} llvm-${APT_LLVM_V} libclang-rt-${APT_LLVM_V}-dev python3-zmq qt6-base-dev qt6-tools-dev qt6-l10n-tools libevent-dev libboost-dev libzmq3-dev libqrencode-dev libsqlite3-dev ${BPFCC_PACKAGE} libcapnp-dev capnproto"
+export PACKAGES="systemtap-sdt-dev clang-${APT_LLVM_V} llvm-${APT_LLVM_V} libclang-rt-${APT_LLVM_V}-dev python3-zmq qt6-base-dev qt6-tools-dev qt6-l10n-tools libevent-dev libboost-dev libzmq3-dev libqrencode-dev libsqlite3-dev ${BPFCC_PACKAGE} libcapnp-dev capnproto python3-pip"
+export PIP_PACKAGES="--break-system-packages pycapnp"
 export NO_DEPENDS=1
 export GOAL="install"
 export CI_LIMIT_STACK_SIZE=1
diff --git a/ci/test/00_setup_env_native_centos.sh b/ci/test/00_setup_env_native_centos.sh
@@ -9,7 +9,7 @@ export LC_ALL=C.UTF-8
 export CONTAINER_NAME=ci_native_centos
 export CI_IMAGE_NAME_TAG="quay.io/centos/centos:stream10"
 export CI_BASE_PACKAGES="gcc-c++ glibc-devel libstdc++-devel ccache make ninja-build git python3 python3-pip which patch xz procps-ng rsync coreutils bison e2fsprogs cmake dash"
-export PIP_PACKAGES="pyzmq"
+export PIP_PACKAGES="pyzmq pycapnp"
 export DEP_OPTS="DEBUG=1"
 export GOAL="install"
 export BITCOIN_CONFIG="\
diff --git a/ci/test/00_setup_env_native_msan.sh b/ci/test/00_setup_env_native_msan.sh
@@ -14,7 +14,8 @@ LIBCXX_FLAGS="-nostdinc++ -nostdlib++ -isystem ${LIBCXX_DIR}include/c++/v1 -L${L
 export MSAN_AND_LIBCXX_FLAGS="${MSAN_FLAGS} ${LIBCXX_FLAGS}"
 
 export CONTAINER_NAME="ci_native_msan"
-export PACKAGES="clang-${APT_LLVM_V} llvm-${APT_LLVM_V} llvm-${APT_LLVM_V}-dev libclang-${APT_LLVM_V}-dev libclang-rt-${APT_LLVM_V}-dev"
+export PACKAGES="clang-${APT_LLVM_V} llvm-${APT_LLVM_V} llvm-${APT_LLVM_V}-dev libclang-${APT_LLVM_V}-dev libclang-rt-${APT_LLVM_V}-dev python3-pip"
+export PIP_PACKAGES="--break-system-packages pycapnp"
 export DEP_OPTS="DEBUG=1 NO_QT=1 CC=clang CXX=clang++ CFLAGS='${MSAN_FLAGS}' CXXFLAGS='${MSAN_AND_LIBCXX_FLAGS}'"
 export GOAL="install"
 export CI_LIMIT_STACK_SIZE=1
diff --git a/ci/test/00_setup_env_native_nowallet_libbitcoinkernel.sh b/ci/test/00_setup_env_native_nowallet_libbitcoinkernel.sh
@@ -9,7 +9,8 @@ export LC_ALL=C.UTF-8
 export CONTAINER_NAME=ci_native_nowallet_libbitcoinkernel
 export CI_IMAGE_NAME_TAG="mirror.gcr.io/debian:bookworm"
 # Use minimum supported python3.10 (or best-effort 3.11) and clang-16, see doc/dependencies.md
-export PACKAGES="python3-zmq clang-16 llvm-16 libc++abi-16-dev libc++-16-dev"
+export PACKAGES="python3-zmq python3-pip clang-16 llvm-16 libc++abi-16-dev libc++-16-dev"
+export PIP_PACKAGES="--break-system-packages pycapnp"
 export DEP_OPTS="NO_WALLET=1 CC=clang-16 CXX='clang++-16 -stdlib=libc++'"
 export GOAL="install"
 export BITCOIN_CONFIG="-DREDUCE_EXPORTS=ON -DBUILD_UTIL_CHAINSTATE=ON -DBUILD_KERNEL_LIB=ON -DBUILD_SHARED_LIBS=ON"
diff --git a/ci/test/00_setup_env_native_tsan.sh b/ci/test/00_setup_env_native_tsan.sh
@@ -11,7 +11,8 @@ export CI_IMAGE_NAME_TAG="mirror.gcr.io/ubuntu:24.04"
 export APT_LLVM_V="21"
 LIBCXX_DIR="/cxx_build/"
 LIBCXX_FLAGS="-fsanitize=thread -nostdinc++ -nostdlib++ -isystem ${LIBCXX_DIR}include/c++/v1 -L${LIBCXX_DIR}lib -Wl,-rpath,${LIBCXX_DIR}lib -lc++ -lc++abi -lpthread -Wno-unused-command-line-argument"
-export PACKAGES="clang-${APT_LLVM_V} llvm-${APT_LLVM_V} llvm-${APT_LLVM_V}-dev libclang-${APT_LLVM_V}-dev libclang-rt-${APT_LLVM_V}-dev python3-zmq"
+export PACKAGES="clang-${APT_LLVM_V} llvm-${APT_LLVM_V} llvm-${APT_LLVM_V}-dev libclang-${APT_LLVM_V}-dev libclang-rt-${APT_LLVM_V}-dev python3-zmq python3-pip"
+export PIP_PACKAGES="--break-system-packages pycapnp"
 export DEP_OPTS="CC=clang CXX=clang++ CXXFLAGS='${LIBCXX_FLAGS}' NO_QT=1"
 export GOAL="install"
 export CI_LIMIT_STACK_SIZE=1
diff --git a/ci/test/00_setup_env_native_valgrind.sh b/ci/test/00_setup_env_native_valgrind.sh
@@ -8,7 +8,8 @@ export LC_ALL=C.UTF-8
 
 export CI_IMAGE_NAME_TAG="mirror.gcr.io/ubuntu:24.04"
 export CONTAINER_NAME=ci_native_valgrind
-export PACKAGES="valgrind python3-zmq libevent-dev libboost-dev libzmq3-dev libsqlite3-dev libcapnp-dev capnproto"
+export PACKAGES="valgrind python3-zmq libevent-dev libboost-dev libzmq3-dev libsqlite3-dev libcapnp-dev capnproto python3-pip"
+export PIP_PACKAGES="--break-system-packages pycapnp"
 export USE_VALGRIND=1
 export NO_DEPENDS=1
 # bind tests excluded for now, see https://github.com/bitcoin/bitcoin/issues/17765#issuecomment-602068547
diff --git a/test/CMakeLists.txt b/test/CMakeLists.txt
@@ -26,6 +26,7 @@ function(create_test_config)
   set_configure_variable(WITH_ZMQ ENABLE_ZMQ)
   set_configure_variable(ENABLE_EXTERNAL_SIGNER ENABLE_EXTERNAL_SIGNER)
   set_configure_variable(WITH_USDT ENABLE_USDT_TRACEPOINTS)
+  set_configure_variable(ENABLE_IPC ENABLE_IPC)
 
   configure_file(config.ini.in config.ini USE_SOURCE_PERMISSIONS @ONLY)
 endfunction()
diff --git a/test/README.md b/test/README.md
@@ -34,6 +34,22 @@ The ZMQ functional test requires a python ZMQ library. To install it:
 - on Unix, run `sudo apt-get install python3-zmq`
 - on mac OS, run `pip3 install pyzmq`
 
+The IPC functional test requires a python IPC library. `pip3 install pycapnp` may work, but if not, install it from source:
+
+```sh
+git clone -b v2.1.0 https://github.com/capnproto/pycapnp
+pip3 install ./pycapnp
+```
+
+If that does not work, try adding `-C force-bundled-libcapnp=True` to the `pip` command.
+Depending on the system, it may be necessary to install and run in a venv:
+
+```sh
+python -m venv venv
+git clone -b v2.1.0 https://github.com/capnproto/pycapnp
+venv/bin/pip3 install ./pycapnp -C force-bundled-libcapnp=True
+venv/bin/python3 build/test/functional/interface_ipc.py
+```
 
 On Windows the `PYTHONUTF8` environment variable must be set to 1:
 
diff --git a/test/config.ini.in b/test/config.ini.in
@@ -26,3 +26,4 @@ RPCAUTH=@abs_top_srcdir@/share/rpcauth/rpcauth.py
 @ENABLE_ZMQ_TRUE@ENABLE_ZMQ=true
 @ENABLE_EXTERNAL_SIGNER_TRUE@ENABLE_EXTERNAL_SIGNER=true
 @ENABLE_USDT_TRACEPOINTS_TRUE@ENABLE_USDT_TRACEPOINTS=true
+@ENABLE_IPC_TRUE@ENABLE_IPC=true
diff --git a/test/functional/interface_ipc.py b/test/functional/interface_ipc.py
@@ -0,0 +1,188 @@
+#!/usr/bin/env python3
+# Copyright (c) The Bitcoin Core developers
+# Distributed under the MIT software license, see the accompanying
+# file COPYING or http://www.opensource.org/licenses/mit-license.php.
+"""Test the IPC (multiprocess) interface."""
+import asyncio
+from io import BytesIO
+from pathlib import Path
+import shutil
+from test_framework.messages import (CBlock, CTransaction, ser_uint256)
+from test_framework.test_framework import (BitcoinTestFramework, assert_equal)
+from test_framework.wallet import MiniWallet
+
+# Test may be skipped and not have capnp installed
+try:
+    import capnp  # type: ignore[import] # noqa: F401
+except ImportError:
+    pass
+
+
+class IPCInterfaceTest(BitcoinTestFramework):
+
+    def skip_test_if_missing_module(self):
+        self.skip_if_no_ipc()
+        self.skip_if_no_py_capnp()
+
+    def load_capnp_modules(self):
+        if capnp_bin := shutil.which("capnp"):
+            # Add the system cap'nproto path so include/capnp/c++.capnp can be found.
+            capnp_dir = Path(capnp_bin).parent.parent / "include"
+        else:
+            # If there is no system cap'nproto, the pycapnp module should have its own "bundled"
+            # includes at this location. If pycapnp was installed with bundled capnp,
+            # capnp/c++.capnp can be found here.
+            capnp_dir = Path(capnp.__path__[0]).parent
+        src_dir = Path(self.config['environment']['SRCDIR']) / "src"
+        mp_dir = src_dir / "ipc" / "libmultiprocess" / "include"
+        imports = [str(capnp_dir), str(src_dir), str(mp_dir)]
+        return {
+            "proxy": capnp.load(str(mp_dir / "mp" / "proxy.capnp"), imports=imports),
+            "init": capnp.load(str(src_dir / "ipc" / "capnp" / "init.capnp"), imports=imports),
+            "echo": capnp.load(str(src_dir / "ipc" / "capnp" / "echo.capnp"), imports=imports),
+            "mining": capnp.load(str(src_dir / "ipc" / "capnp" / "mining.capnp"), imports=imports),
+        }
+
+    def set_test_params(self):
+        self.num_nodes = 1
+
+    def setup_nodes(self):
+        self.extra_init = [{"ipcbind": True}]
+        super().setup_nodes()
+        # Use this function to also load the capnp modules (we cannot use set_test_params for this,
+        # as it is being called before knowing whether capnp is available).
+        self.capnp_modules = self.load_capnp_modules()
+
+    async def make_capnp_init_ctx(self):
+        node = self.nodes[0]
+        # Establish a connection, and create Init proxy object.
+        connection = await capnp.AsyncIoStream.create_unix_connection(node.ipc_socket_path)
+        client = capnp.TwoPartyClient(connection)
+        init = client.bootstrap().cast_as(self.capnp_modules['init'].Init)
+        # Create a remote thread on the server for the IPC calls to be executed in.
+        threadmap = init.construct().threadMap
+        thread = threadmap.makeThread("pythread").result
+        ctx = self.capnp_modules['proxy'].Context()
+        ctx.thread = thread
+        # Return both.
+        return ctx, init
+
+    async def parse_and_deserialize_block(self, block_template, ctx):
+        block_data = BytesIO((await block_template.result.getBlock(ctx)).result)
+        block = CBlock()
+        block.deserialize(block_data)
+        return block
+
+    def run_echo_test(self):
+        self.log.info("Running echo test")
+        async def async_routine():
+            ctx, init = await self.make_capnp_init_ctx()
+            self.log.debug("Create Echo proxy object")
+            echo = init.makeEcho(ctx).result
+            self.log.debug("Test a few invocations of echo")
+            for s in ["hallo", "", "haha"]:
+                result_eval = (await echo.echo(ctx, s)).result
+                assert_equal(s, result_eval)
+            self.log.debug("Destroy the Echo object")
+            echo.destroy(ctx)
+        asyncio.run(capnp.run(async_routine()))
+
+    def run_mining_test(self):
+        self.log.info("Running mining test")
+        block_hash_size = 32
+        block_header_size = 80
+        timeout = 1000.0 # 1000 milliseconds
+        miniwallet = MiniWallet(self.nodes[0])
+
+        async def async_routine():
+            ctx, init = await self.make_capnp_init_ctx()
+            self.log.debug("Create Mining proxy object")
+            mining = init.makeMining(ctx)
+            self.log.debug("Test simple inspectors")
+            assert (await mining.result.isTestChain(ctx))
+            assert (await mining.result.isInitialBlockDownload(ctx))
+            blockref = await mining.result.getTip(ctx)
+            assert blockref.hasResult
+            assert_equal(len(blockref.result.hash), block_hash_size)
+            current_block_height = self.nodes[0].getchaintips()[0]["height"]
+            assert blockref.result.height == current_block_height
+            self.log.debug("Mine a block")
+            wait = mining.result.waitTipChanged(ctx, blockref.result.hash, )
+            self.generate(self.nodes[0], 1)
+            newblockref = await wait
+            assert_equal(len(newblockref.result.hash), block_hash_size)
+            assert_equal(newblockref.result.height, current_block_height + 1)
+            self.log.debug("Wait for timeout")
+            wait = mining.result.waitTipChanged(ctx, newblockref.result.hash, timeout)
+            oldblockref = await wait
+            assert_equal(len(newblockref.result.hash), block_hash_size)
+            assert_equal(oldblockref.result.hash, newblockref.result.hash)
+            assert_equal(oldblockref.result.height, newblockref.result.height)
+
+            self.log.debug("Create a template")
+            opts = self.capnp_modules['mining'].BlockCreateOptions()
+            opts.useMempool = True
+            opts.blockReservedWeight = 4000
+            opts.coinbaseOutputMaxAdditionalSigops = 0
+            template = mining.result.createNewBlock(opts)
+            self.log.debug("Test some inspectors of Template")
+            header = await template.result.getBlockHeader(ctx)
+            assert_equal(len(header.result), block_header_size)
+            block = await self.parse_and_deserialize_block(template, ctx)
+            assert_equal(ser_uint256(block.hashPrevBlock), newblockref.result.hash)
+            assert len(block.vtx) >= 1
+            txfees = await template.result.getTxFees(ctx)
+            assert_equal(len(txfees.result), 0)
+            txsigops = await template.result.getTxSigops(ctx)
+            assert_equal(len(txsigops.result), 0)
+            coinbase_data = BytesIO((await template.result.getCoinbaseTx(ctx)).result)
+            coinbase = CTransaction()
+            coinbase.deserialize(coinbase_data)
+            assert_equal(coinbase.vin[0].prevout.hash, 0)
+            self.log.debug("Wait for a new template")
+            waitoptions = self.capnp_modules['mining'].BlockWaitOptions()
+            waitoptions.timeout = timeout
+            waitnext = template.result.waitNext(ctx, waitoptions)
+            self.generate(self.nodes[0], 1)
+            template2 = await waitnext
+            block2 = await self.parse_and_deserialize_block(template2, ctx)
+            assert_equal(len(block2.vtx), 1)
+            self.log.debug("Wait for another, but time out")
+            template3 = await template2.result.waitNext(ctx, waitoptions)
+            assert_equal(template3.to_dict(), {})
+            self.log.debug("Wait for another, get one after increase in fees in the mempool")
+            waitnext = template2.result.waitNext(ctx, waitoptions)
+            miniwallet.send_self_transfer(fee_rate=10, from_node=self.nodes[0])
+            template4 = await waitnext
+            block3 = await self.parse_and_deserialize_block(template4, ctx)
+            assert_equal(len(block3.vtx), 2)
+            self.log.debug("Wait again, this should return the same template, since the fee threshold is zero")
+            template5 = await template4.result.waitNext(ctx, waitoptions)
+            block4 = await self.parse_and_deserialize_block(template5, ctx)
+            assert_equal(len(block4.vtx), 2)
+            waitoptions.feeThreshold = 1
+            self.log.debug("Wait for another, get one after increase in fees in the mempool")
+            waitnext = template5.result.waitNext(ctx, waitoptions)
+            miniwallet.send_self_transfer(fee_rate=10, from_node=self.nodes[0])
+            template6 = await waitnext
+            block4 = await self.parse_and_deserialize_block(template6, ctx)
+            assert_equal(len(block4.vtx), 3)
+            self.log.debug("Wait for another, but time out, since the fee threshold is set now")
+            template7 = await template6.result.waitNext(ctx, waitoptions)
+            assert_equal(template7.to_dict(), {})
+            self.log.debug("Destroy template objects")
+            template.result.destroy(ctx)
+            template2.result.destroy(ctx)
+            template3.result.destroy(ctx)
+            template4.result.destroy(ctx)
+            template5.result.destroy(ctx)
+            template6.result.destroy(ctx)
+            template7.result.destroy(ctx)
+        asyncio.run(capnp.run(async_routine()))
+
+    def run_test(self):
+        self.run_echo_test()
+        self.run_mining_test()
+
+if __name__ == '__main__':
+    IPCInterfaceTest(__file__).main()
diff --git a/test/functional/test_framework/test_framework.py b/test/functional/test_framework/test_framework.py
diff --git a/test/functional/test_framework/test_node.py b/test/functional/test_framework/test_node.py
diff --git a/test/functional/test_runner.py b/test/functional/test_runner.py
