Add functional test for IPC interface #33201

sipa · 2025-08-15T20:10:28Z

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.

DrahtBot · 2025-08-15T20:10:34Z

The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

Code Coverage & Benchmarks

For details see: https://corecheck.dev/bitcoin/bitcoin/pulls/33201.

Reviews

See the guideline for information on the review process.

Type	Reviewers
ACK	janb84
Stale ACK	josibake, ismaelsadeeq, Sjors, ryanofsky

If your review is incorrectly listed, please react with 👎 to this comment and the bot will ignore it on the next update.

Conflicts

Reviewers, this pull request conflicts with the following ones:

#33142 (test: Run bench sanity checks in parallel with functional tests by maflcko)
#32297 (bitcoin-cli: Add -ipcconnect option by ryanofsky)
#31723 (qa debug: Add --debug_runs/-waitfordebugger [DRAFT] by hodlinator)
#30437 (ipc: add bitcoin-mine test program by ryanofsky)
#29838 (Feature: Use different datadirs for different signets by BrandonOdiwuor)

If you consider this pull request important, please also help to review the conflicting pull requests. Ideally, start with the one that should be merged first.

LLM Linter (✨ experimental)

Possible typos and grammar issues:

in test/README.md: “requires a python IPC library” -> “requires a Python IPC library” [“Python” is a proper noun]
in test/functional/interface_ipc.py comment: “have it’s own” -> “have its own” [possessive “its,” not contraction “it’s”]

No other comprehension-impacting typos were found.

^{drahtbot_id_4_m}

DrahtBot · 2025-08-15T20:14:21Z

🚧 At least one of the CI tasks failed.
_{Task lint: https://github.com/bitcoin/bitcoin/runs/48194727681}
_{LLM reason (✨ experimental): The CI failure is caused by errors detected during the linting process, specifically from ruff and mypy, indicating code issues and missing module imports.}

Hints

Try to run the tests locally, according to the documentation. However, a CI failure may still
happen due to a number of reasons, for example:

Possibly due to a silent merge conflict (the changes in this pull request being
incompatible with the current code in the target branch). If so, make sure to rebase on the latest
commit of the target branch.
A sanitizer issue, which can only be found by compiling with the sanitizer and running the
affected test.
An intermittent issue.

Leave a comment here, if you need help tracking down a confusing failure.

ryanofsky · 2025-08-15T20:46:14Z

Concept ACK. 27bd678 is really nice and simpler than I would have expected.

In case it's useful #30437 adds an interface_ipc_mining.py test, and #32297 adds an interface_ipc_cli.py test which are similar to this test and have similar test framework updates. Code from those PRs might be useful here or vice versa.

Sjors · 2025-08-16T07:06:46Z

Concept ACK

So far I achieved test coverage for the Mining interface with a combination of unit tests and by having RPC methods such as getblocktemplate use the interface internally. But the latter has side-effects (see #32547) and could be avoided once we have enough direct coverage.

CentOS CI fails with capnp.lib.capnp.KjException: mp/proxy.capnp:6: failed: Import failed: /capnp/c++.capn https://cirrus-ci.com/task/4824947408764928?logs=ci#L3320

test/functional/interface_ipc.py

Sjors

On macOS 15.6 with capnp 1.2.0 installed via Homebrew and Python 3.10.14 installed via PyEnv I get:

pip3 install pycapnp
...
Successfully installed pycapnp-2.0.0

cmake -B build
cmake --build build
...

% build/test/functional/interface_ipc.py
2025-08-17T07:05:49.321522Z TestFramework (INFO): PRNG seed is: 6039316184654231320
2025-08-17T07:05:49.322566Z TestFramework (INFO): Initializing test directory /var/folders/8p/qqdl2fsj7rd6q096jtmsfydc0000gn/T/bitcoin_func_test_z3jtr5u1
2025-08-17T07:05:50.595292Z TestFramework (ERROR): Unexpected exception
Traceback (most recent call last):
  File "/Users/sjors/dev/bitcoin/test/functional/test_framework/test_framework.py", line 200, in main
    self.run_test()
  File "/Users/sjors/dev/bitcoin/build/test/functional/interface_ipc.py", line 82, in run_test
    self.run_echo_test()
  File "/Users/sjors/dev/bitcoin/build/test/functional/interface_ipc.py", line 63, in run_echo_test
    asyncio.run(capnp.run(async_routine()))
  File "/Users/sjors/.pyenv/versions/3.10.14/lib/python3.10/asyncio/runners.py", line 44, in run
    return loop.run_until_complete(main)
  File "/Users/sjors/.pyenv/versions/3.10.14/lib/python3.10/asyncio/base_events.py", line 649, in run_until_complete
    return future.result()
  File "capnp/lib/capnp.pyx", line 1944, in run
  File "capnp/lib/capnp.pyx", line 1945, in capnp.lib.capnp.run
  File "/Users/sjors/dev/bitcoin/build/test/functional/interface_ipc.py", line 57, in async_routine
    init, ctx = await self.make_capnp_init_ctx()
  File "/Users/sjors/dev/bitcoin/build/test/functional/interface_ipc.py", line 45, in make_capnp_init_ctx
    modules = self.capnp_modules()
  File "/Users/sjors/dev/bitcoin/build/test/functional/interface_ipc.py", line 38, in capnp_modules
    "proxy": capnp.load(str(mp_dir / "mp" / "proxy.capnp"), imports=imports),
  File "capnp/lib/capnp.pyx", line 4385, in capnp.lib.capnp.load
  File "capnp/lib/capnp.pyx", line 3574, in capnp.lib.capnp.SchemaParser.load
capnp.lib.capnp.KjException: mp/proxy.capnp:6: failed: Import failed: /capnp/c++.capnp

Maybe related: capnproto/pycapnp#377 (though pycapnp-1.3.0 doesn't work at all, since it doesn't have the run method)

Suggested test doc improvement:

diff --git a/test/README.md b/test/README.md
index 37f2c07217..3b2979cdf6 100644
--- a/test/README.md
+++ b/test/README.md
@@ -34,6 +34,9 @@ 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. To install it:
+
+- `pip3 install pycapnp`

 On Windows the `PYTHONUTF8` environment variable must be set to 1:

ci/test/01_base_install.sh

Sjors

ACK 088dc2c (after base PR lands)

Sjors · 2025-08-19T17:00:38Z

test/functional/interface_ipc.py

+        # 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):


088dc2c: eventually I'd like to move this and load_capnp_modules into the test framework so that it's easier to expand e.g. mining_template_verification.py to call both getblocktemplate proposal and checkBlock().

Leaving this for a follow-up.

test/functional/interface_ipc.py

sipa · 2025-08-19T17:07:12Z

Addressed a number of comments, and rebased on top of #31802.

I will however not have (much) time to push this further forward until the end of this month. @Sjors or @ryanofsky, or someone else, feel free to take this over and/or integrate into other PRs.

janb84

ACK 088dc2c (after base #31802)

This PR adds some functional tests for the IPC interface, setups the CI to use IPC and changes build documentation to match the changes in this PR.

Current state of the PR works on nix on macOS, builds & test run without trouble.

build ✅
tested ✅
code review✅

small NIT if retouched, please see the remarks of DrahtBot's LLM linter.

ryanofsky

Code review ACK 088dc2c. Looks great! Left some comments that you should feel free to ignore. I am shocked and amazed about how much more friendly the python async API is compared to the c++ API, but I guess coroutines can bring similar benefits to c++. It is also nice how this tests covers different scenarios with waitNext()

test/functional/test_framework/test_framework.py

ryanofsky · 2025-08-20T13:34:30Z

test/README.md

+```sh
+git clone https://github.com/capnproto/pycapnp.git`
+cd pycapnp
+pip install . -C force-bundled-libcapnp=True


In commit "ci: add functional test for IPC interface" (088dc2c)

As mentioned #33201 (comment), would be curious to know if force-system-libcapnp=True works for people, since it seems wasteful to download and build a dependency that we already know must be installed (or the test would be skipped).

I opted to use system libcapnp in the description here because it's more likely to work. I've added a comment about it being optional now.

ci/test/00_setup_env_native_tidy.sh

test/functional/interface_ipc.py

Expose ENABLE_IPC build option to function tests so new tests can test IPC-only features.

Set new `BitcoinTestFramework.binary_paths.bitcoin_bin` property with path to the `bitcoin` wrapper binary. This allows new tests for `bitcoin-mine` in bitcoin#30437 and `bitcoin-cli` in bitcoin#32297 to find the `bitcoin` binary and call `bitcoin -m` to start nodes with IPC support. This way the new tests can run whenever the ENABLE_IPC build option is enabled, instead of only running when the `BITCOIN_CMD` environment variable is set to `bitcoin -m`

With this change, tests can specify `self.extra_init = [{ipcbind: True}]` to start a node listening on an IPC socket, instead of needing to choose which node binary to invoke and what `self.extra_args=[["-ipcbind=..."]]` value to pass to it. The eliminates boilerplate code bitcoin#30437 (interface_ipc_mining.py), bitcoin#32297 (interface_ipc_cli.py), and bitcoin#33201 (interface_ipc.py) previously needed in their test setup.

Sjors · 2025-08-21T07:10:33Z

@sipa let me know if you don't have to time to rebase, in which case I'll open a fresh PR next week.

sipa · 2025-08-21T07:21:43Z

Rebased, and addressed some of the feedback above.

Note that the last commit (which enables the tests in CI) may need work after moving to be on top of #31802, so that it matches the CI configurations which have IPC enabled.

DrahtBot · 2025-08-21T07:28:14Z

🚧 At least one of the CI tasks failed.
_{Task lint: https://github.com/bitcoin/bitcoin/runs/48558512670}
_{LLM reason (✨ experimental): Lint check failed due to unused variable capnp_bin.}

Hints

Try to run the tests locally, according to the documentation. However, a CI failure may still
happen due to a number of reasons, for example:

Possibly due to a silent merge conflict (the changes in this pull request being
incompatible with the current code in the target branch). If so, make sure to rebase on the latest
commit of the target branch.
A sanitizer issue, which can only be found by compiling with the sanitizer and running the
affected test.
An intermittent issue.

Leave a comment here, if you need help tracking down a confusing failure.

DrahtBot · 2025-08-21T07:43:23Z

test/functional/interface_ipc.py

+            # 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 system cap'nproto, the pycapnp module should have it's own "bundled" includes at this location


in test/functional/interface_ipc.py comment: “have it’s own” -> “have its own” [possessive “its,” not contraction “it’s”]

janb84

re ACK 03c66ee

changes since last ACK:

rebase
addressed some NIT's

Sjors · 2025-08-21T11:15:22Z

For some reason on the macOS native job (00_setup_env_mac_native.sh) the interface test is skipped despite pycapnp being installed and bitcoin-node being built: https://github.com/bitcoin/bitcoin/actions/runs/17120162263/job/48559027457?pr=33201#step:8:3718

I checked that this test did run for native_asan.

I wrote a commit that enables it for additional jobs, which I'm testing in Sjors#101:

CentOS
native man
kernel
native_tsan
previous releases
native valgrind

Update: 0c88edc should be safe to cherry-pick, we can add the previous_release job later.

sipa force-pushed the 202508_ipc_test branch from d317265 to 5050855 Compare August 15, 2025 20:14

DrahtBot added the CI failed label Aug 15, 2025

sipa force-pushed the 202508_ipc_test branch from 5050855 to 27bd678 Compare August 15, 2025 20:24

sipa force-pushed the 202508_ipc_test branch 4 times, most recently from b4cb8f6 to b87de46 Compare August 16, 2025 00:08

Sjors reviewed Aug 16, 2025

View reviewed changes

test/functional/interface_ipc.py Show resolved Hide resolved

sipa force-pushed the 202508_ipc_test branch 3 times, most recently from e6bfad6 to f5b8da2 Compare August 16, 2025 13:28

DrahtBot removed the CI failed label Aug 16, 2025

sipa force-pushed the 202508_ipc_test branch from f5b8da2 to 1aa7cf5 Compare August 16, 2025 15:01

DrahtBot mentioned this pull request Aug 16, 2025

build: Enable ENABLE_IPC option by default #33190

Closed

sipa force-pushed the 202508_ipc_test branch from 1aa7cf5 to 0637aa4 Compare August 16, 2025 22:17

This was referenced Aug 16, 2025

cmake: Do not require Python to build GUI #33156

Closed

test: Run bench sanity checks in parallel with functional tests #33142

Open

DrahtBot added the CI failed label Aug 16, 2025

DrahtBot mentioned this pull request Aug 17, 2025

ci: Migrate CI to hosted Cirrus Runners #32989

Open

sipa force-pushed the 202508_ipc_test branch 2 times, most recently from 74fc236 to eb482c1 Compare August 17, 2025 02:53

DrahtBot removed the CI failed label Aug 17, 2025

This was referenced Aug 17, 2025

bitcoin-cli: Add -ipcconnect option #32297

Open

depends: Switch from multilib to platform-specific toolchains #32162

Open

Sjors reviewed Aug 17, 2025

View reviewed changes

ci/test/01_base_install.sh Show resolved Hide resolved

DrahtBot mentioned this pull request Aug 17, 2025

Add bitcoin-{node,gui} to release binaries for IPC #31802

Merged

sipa force-pushed the 202508_ipc_test branch from 530ca0b to 088dc2c Compare August 19, 2025 15:14

Sjors approved these changes Aug 19, 2025

View reviewed changes

DrahtBot requested review from ismaelsadeeq, josibake and ryanofsky August 19, 2025 17:06

DrahtBot removed the CI failed label Aug 19, 2025

DrahtBot mentioned this pull request Aug 20, 2025

Feature: Use different datadirs for different signets #29838

Open

janb84 reviewed Aug 20, 2025

View reviewed changes

ryanofsky approved these changes Aug 20, 2025

View reviewed changes

DrahtBot added the Needs rebase label Aug 20, 2025

ryanofsky added 3 commits August 21, 2025 02:39

test: add is_ipc_compiled() and skip_if_no_ipc() functions

8bf4c00

Expose ENABLE_IPC build option to function tests so new tests can test IPC-only features.

sipa force-pushed the 202508_ipc_test branch from 088dc2c to efa8b24 Compare August 21, 2025 07:20

sipa added 2 commits August 21, 2025 03:27

tests: add functional tests for IPC interface

bb8a9af

ci: enable IPC tests in CI

03c66ee

sipa force-pushed the 202508_ipc_test branch from efa8b24 to 03c66ee Compare August 21, 2025 07:27

DrahtBot added the CI failed label Aug 21, 2025

DrahtBot reviewed Aug 21, 2025

View reviewed changes

DrahtBot removed the CI failed label Aug 21, 2025

janb84 reviewed Aug 21, 2025

View reviewed changes

DrahtBot requested review from Sjors and ryanofsky August 21, 2025 08:59

DrahtBot removed the Needs rebase label Aug 21, 2025

Sjors mentioned this pull request Aug 21, 2025

IPC interface tests on more CI hosts Sjors/bitcoin#101

Open

Add functional test for IPC interface #33201

Are you sure you want to change the base?

Add functional test for IPC interface #33201

Conversation

sipa commented Aug 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

DrahtBot commented Aug 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Code Coverage & Benchmarks

Reviews

Conflicts

LLM Linter (✨ experimental)

Uh oh!

DrahtBot commented Aug 15, 2025

Uh oh!

ryanofsky commented Aug 15, 2025

Uh oh!

Sjors commented Aug 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Sjors left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Sjors left a comment

Choose a reason for hiding this comment

Uh oh!

Sjors Aug 19, 2025

Choose a reason for hiding this comment

Uh oh!

sipa Aug 21, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sipa commented Aug 19, 2025

Uh oh!

janb84 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ryanofsky left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ryanofsky Aug 20, 2025

Choose a reason for hiding this comment

Uh oh!

sipa Aug 21, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Sjors commented Aug 21, 2025

Uh oh!

sipa commented Aug 21, 2025

Uh oh!

DrahtBot commented Aug 21, 2025

Uh oh!

DrahtBot Aug 21, 2025

Choose a reason for hiding this comment

Uh oh!

janb84 left a comment

Choose a reason for hiding this comment

Uh oh!

Sjors commented Aug 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

sipa commented Aug 15, 2025 •

edited

Loading

DrahtBot commented Aug 15, 2025 •

edited

Loading

Sjors commented Aug 16, 2025 •

edited

Loading

Sjors left a comment •

edited

Loading

janb84 left a comment •

edited

Loading

Sjors commented Aug 21, 2025 •

edited

Loading