From d7f4cf32c0091bda0e1334c6ff93f26fa0866a81 Mon Sep 17 00:00:00 2001 From: Sjors Provoost Date: Fri, 18 Sep 2026 10:29:07 +0200 Subject: [PATCH 01/11] doc: maintenance branch rules Document how maintenance branches are created and what they may receive: only backports and branch specific fixes, never a fast-forward to master. The latter happened to 31.x, which as a result picked up submitBlock() (not part of Bitcoin Core 31.x) and lost its CI configuration, see #35. Github-Pull: #36 Rebased-From: 94b2b73a7a4502a7cae538fd91af012a07c388a0 --- RELEASE_POLICY.md | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/RELEASE_POLICY.md b/RELEASE_POLICY.md index a4fd929..3ad2dd2 100644 --- a/RELEASE_POLICY.md +++ b/RELEASE_POLICY.md @@ -13,10 +13,23 @@ This policy applies to: ## Branch Model -- `master` tracks the current active development line. -- Maintenance branches (for example `30.x`, `31.x`, `32.x`) track stable backport lines. +- `master` tracks the current active development line, i.e. Bitcoin Core `master`. +- Maintenance branches (for example `30.x`, `31.x`) track stable backport lines, i.e. the Bitcoin Core branch of the same name. - A release must be cut from the branch that owns that version line. +### Maintenance Branches + +- A maintenance branch is created from `master` after Bitcoin Core branches off, at a point where the schema files match the new Bitcoin Core branch. +- Its CI builds the Bitcoin Core branch of the same name, and runs for pushes and pull requests that target the maintenance branch. +- After creation it only receives backports from `master` and fixes specific to that branch. It must never be fast-forwarded to, or merged with, `master`. +- The schema files must keep matching the corresponding Bitcoin Core branch. Interface changes are only backported if Bitcoin Core backported them. Test and build changes can be backported more freely. +- Backported commits reference the original pull request and commit on `master`, using the Bitcoin Core convention: + + ``` + Github-Pull: # + Rebased-From: + ``` + ## Version Line Mapping - `30.x` branch -> `0.1.x` From 6b1f2d34746ae9245cbec294cab39d3fc3097b1d Mon Sep 17 00:00:00 2001 From: rustaceanrob Date: Fri, 24 Jul 2026 19:13:02 +0100 Subject: [PATCH 02/11] Add test script to contrib folder Github-Pull: #33 Rebased-From: 2dd5740cf10857457f026a45ce153c042c1cbcdd --- README.md | 2 +- contrib/run-tests.sh | 47 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 48 insertions(+), 1 deletion(-) create mode 100755 contrib/run-tests.sh diff --git a/README.md b/README.md index af642a4..a86d620 100644 --- a/README.md +++ b/README.md @@ -34,7 +34,7 @@ cargo build ## Running integration tests -The integration tests connect to a running bitcoin node via IPC. +The integration tests connect to a running bitcoin node via IPC. For a single test script, see `contrib/run-tests.sh`. ### 1. Build Bitcoin Core diff --git a/contrib/run-tests.sh b/contrib/run-tests.sh new file mode 100755 index 0000000..24b5ea3 --- /dev/null +++ b/contrib/run-tests.sh @@ -0,0 +1,47 @@ +#!/usr/bin/env bash +# +# Build Bitcoin Core, launch a regtest node with IPC enabled, run the +# integration test suite against it, and shut the node down. +# +# Usage: contrib/run-tests.sh + +set -euo pipefail + +if [ "$#" -ne 1 ]; then + echo "Usage: $0 " >&2 + exit 1 +fi + +BITCOIN_SRC=$(cd "$1" && pwd) +REPO_ROOT=$(cd "$(dirname "$0")/.." && pwd) +BITCOIN_BIN="$BITCOIN_SRC/build/bin/bitcoin" + +echo "==> Building Bitcoin Core in $BITCOIN_SRC" +( + cd "$BITCOIN_SRC" + CMAKE_ARGS=(-DENABLE_WALLET=ON -DBUILD_TESTS=OFF) + if command -v ccache >/dev/null 2>&1; then + CMAKE_ARGS+=(-DCMAKE_C_COMPILER_LAUNCHER=ccache + -DCMAKE_CXX_COMPILER_LAUNCHER=ccache) + fi + cmake -B build "${CMAKE_ARGS[@]}" + cmake --build build -j"$(nproc)" +) + +stop_bitcoin() { + if [ -n "${BITCOIN_STARTED:-}" ]; then + echo "==> Stopping bitcoin" + "$BITCOIN_BIN" rpc -chain=regtest stop || true + fi +} +trap stop_bitcoin EXIT + +echo "==> Starting bitcoin node (regtest, IPC)" +"$BITCOIN_BIN" node -chain=regtest -ipcbind=unix -server -debug=ipc -daemon +BITCOIN_STARTED=1 + +echo "==> Running cargo test" +( + cd "$REPO_ROOT" + BITCOIN_BIN="$BITCOIN_BIN" cargo test +) From c8d8c2830470c22a223077dc353f69f2ffef0cd8 Mon Sep 17 00:00:00 2001 From: rustaceanrob Date: Fri, 18 Sep 2026 11:22:40 +0100 Subject: [PATCH 03/11] ci: Run tests through run-tests.sh Github-Pull: #33 Rebased-From: a80fd45f074d9c632af72293a401694504c46e81 --- .github/workflows/ci.yml | 13 ++----------- 1 file changed, 2 insertions(+), 11 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 50d7f77..c2d9d4c 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -26,14 +26,5 @@ jobs: restore-keys: ccache-${{ runner.os }}- - name: Checkout Bitcoin Core run: git clone --depth 1 --branch 32.x https://github.com/bitcoin/bitcoin.git - - name: Build Bitcoin Core - run: | - cd bitcoin - cmake -B build -DENABLE_WALLET=ON -DBUILD_TESTS=OFF -DCMAKE_C_COMPILER_LAUNCHER=ccache -DCMAKE_CXX_COMPILER_LAUNCHER=ccache - cmake --build build -j $(nproc) - - name: Run Bitcoin Core Daemon - run: cd bitcoin && ./build/bin/bitcoin node -chain=regtest -ipcbind=unix -server -debug=ipc -daemon - - name: Run Test Suite - env: - BITCOIN_BIN: ${{ github.workspace }}/bitcoin/build/bin/bitcoin - run: cargo test + - name: Build & Run Test Suite + run: contrib/run-tests.sh bitcoin From a6f4f01e0df8f4710585aa2ba78da39c85351642 Mon Sep 17 00:00:00 2001 From: Sjors Provoost Date: Fri, 18 Sep 2026 12:41:00 +0200 Subject: [PATCH 04/11] contrib: make run-tests.sh work on macOS nproc is not available on macOS. Use getconf instead and pass the job count via --parallel. A bare --parallel is avoided because it means unlimited jobs with the Makefile generator. Rebased-From: ee5128b75c55390be3ee3895f5157bd1906d2f47 --- contrib/run-tests.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contrib/run-tests.sh b/contrib/run-tests.sh index 24b5ea3..96923ed 100755 --- a/contrib/run-tests.sh +++ b/contrib/run-tests.sh @@ -25,7 +25,7 @@ echo "==> Building Bitcoin Core in $BITCOIN_SRC" -DCMAKE_CXX_COMPILER_LAUNCHER=ccache) fi cmake -B build "${CMAKE_ARGS[@]}" - cmake --build build -j"$(nproc)" + cmake --build build --parallel "$(getconf _NPROCESSORS_ONLN)" ) stop_bitcoin() { From ec9d4bb472353a5e16e45c1811ce794daf8777d3 Mon Sep 17 00:00:00 2001 From: Sjors Provoost Date: Fri, 18 Sep 2026 12:41:10 +0200 Subject: [PATCH 05/11] ci: show ccache stats Zero the stats restored with the cache, so the numbers reflect only this run. Rebased-From: 92eec7ff0e86f8f0c35a23fcce2bb0aeb1dcd84d --- .github/workflows/ci.yml | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index c2d9d4c..cac00d0 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -27,4 +27,7 @@ jobs: - name: Checkout Bitcoin Core run: git clone --depth 1 --branch 32.x https://github.com/bitcoin/bitcoin.git - name: Build & Run Test Suite - run: contrib/run-tests.sh bitcoin + run: | + ccache --zero-stats + contrib/run-tests.sh bitcoin + ccache --show-stats From d856415c789930d698da8818643a7456e895d998 Mon Sep 17 00:00:00 2001 From: Sjors Provoost Date: Fri, 18 Sep 2026 12:41:19 +0200 Subject: [PATCH 06/11] ci: bump actions/cache to v6 v4 targets the deprecated Node.js 20 runtime. Rebased-From: b718ae987cbb5ca17d7f7dac6e3b3dd951cfebec --- .github/workflows/ci.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index cac00d0..1aa84fc 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -19,7 +19,7 @@ jobs: sudo apt-get update sudo apt-get install build-essential cmake pkgconf python3 libevent-dev libboost-dev capnproto libcapnp-dev ccache - name: ccache - uses: actions/cache@v4 + uses: actions/cache@v6 with: path: ~/.cache/ccache key: ccache-${{ runner.os }}-${{ github.sha }} From a9655ae0ecf1b9766a7d52858ca5ed92e45fce5f Mon Sep 17 00:00:00 2001 From: Sjors Provoost Date: Fri, 18 Sep 2026 12:41:20 +0200 Subject: [PATCH 07/11] ci: bump actions/checkout to v7 v4 targets the deprecated Node.js 20 runtime. Rebased-From: 70f15dafa89b7d1099d81e6d26b688d3aa2341a5 --- .github/workflows/ci.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 1aa84fc..700dbe6 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -12,7 +12,7 @@ jobs: test: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v4 + - uses: actions/checkout@v7 - uses: actions-rust-lang/setup-rust-toolchain@v1 - name: Install Bitcoin Dependencies run: | From 2e7100afc1c102539e12f1ce9c6d3de1a0e34b99 Mon Sep 17 00:00:00 2001 From: Sjors Provoost Date: Fri, 18 Sep 2026 12:46:17 +0200 Subject: [PATCH 08/11] test: allow zero uptime in rpc_query_uptime The uptime RPC returns whole seconds, so it is 0 when the test runs within a second of node startup. This happens more often now that contrib/run-tests.sh starts the node right before the tests. Fixes #37 Github-Pull: #38 Rebased-From: 8fc3c8baf5a8c64b4383020db45234eaf11d0e28 --- tests/test.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/test.rs b/tests/test.rs index ef8eec2..81ef141 100644 --- a/tests/test.rs +++ b/tests/test.rs @@ -109,7 +109,7 @@ async fn rpc_query_uptime() { .map_err(|e| format!("failed to parse rpc response as JSON: {e}")) .unwrap(); let uptime = v["result"].as_i64().unwrap(); - assert!(uptime > 0, "Uptime must be greater than zero"); + assert!(uptime >= 0, "Uptime must not be negative"); }) .await; } From fddaccd82c140a06fffdb3bf0776865e1d226dbe Mon Sep 17 00:00:00 2001 From: xyzconstant <263061129+xyzconstant@users.noreply.github.com> Date: Sat, 26 Sep 2026 13:49:30 -0300 Subject: [PATCH 09/11] test: drop interrupt call with nothing to interrupt `mining_check_block_and_interrupt` calls interrupt() while nothing is waiting, so it only checks that the call doesn't fail. Rename it to `mining_check_block`. Github-Pull: #41 Rebased-From: 909aed91184fcfe8cccffb481a66515819242521 --- tests/test.rs | 15 +++------------ 1 file changed, 3 insertions(+), 12 deletions(-) diff --git a/tests/test.rs b/tests/test.rs index 81ef141..1dd3f06 100644 --- a/tests/test.rs +++ b/tests/test.rs @@ -627,11 +627,10 @@ async fn mining_get_transactions() { .await; } -/// checkBlock with a template block payload, and interrupt. +/// checkBlock with a template block payload. #[tokio::test] -// Serialized because interrupt() can affect other in-flight mining waits. -#[serial_test::serial] -async fn mining_check_block_and_interrupt() { +#[serial_test::parallel] +async fn mining_check_block() { with_mining_client(|_client, mining| async move { let template = make_block_template(&mining).await; @@ -663,14 +662,6 @@ async fn mining_check_block_and_interrupt() { } destroy_template(&template).await; - - // interrupt — should not crash. - mining - .interrupt_request() - .send() - .promise - .await - .expect("interrupt should not fail"); }) .await; } From ea2bcdc07684aa599d9dc380bb7dd85753b027ba Mon Sep 17 00:00:00 2001 From: xyzconstant <263061129+xyzconstant@users.noreply.github.com> Date: Sat, 26 Sep 2026 14:19:04 -0300 Subject: [PATCH 10/11] test: exercise interrupt methods Call `waitTipChanged` and `waitNext` with no timeout, let them block in a local task, then check that `interrupt` and `interruptWait` unblock them. Github-Pull: #41 Rebased-From: f3f1f8f0c762490be8f2303bc66940df4055ba0e --- tests/test.rs | 51 +++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 49 insertions(+), 2 deletions(-) diff --git a/tests/test.rs b/tests/test.rs index 1dd3f06..0f354a7 100644 --- a/tests/test.rs +++ b/tests/test.rs @@ -5,6 +5,7 @@ use bitcoin_capnp_types::{ }; use capnp_rpc::{RpcSystem, rpc_twoparty_capnp::Side}; use encoding::encode_to_vec; +use std::time::Duration; use tokio::task::LocalSet; mod util; @@ -242,6 +243,32 @@ async fn mining_wait_tip_changed() { let wait_result = resp.get().unwrap().get_result().unwrap(); assert_eq!(wait_result.get_hash().unwrap().len(), 32); assert_eq!(wait_result.get_height(), tip_height); + + // No timeout. Pin a local task on the wait, then interrupt it. + let mut req = mining.wait_tip_changed_request(); + req.get().set_current_tip(&tip_hash); + let waiter = tokio::task::spawn_local(req.send().promise); + + // Give the waiter time to block before interrupting. + tokio::time::sleep(Duration::from_millis(100)).await; + assert!( + !waiter.is_finished(), + "waitTipChanged returned before interrupt" + ); + mining + .interrupt_request() + .send() + .promise + .await + .expect("interrupt should not fail"); + + let joined = tokio::time::timeout(Duration::from_secs(10), waiter) + .await + .expect("interrupt should unblock waitTipChanged"); + assert!( + joined.is_ok_and(|resp| resp.is_ok()), + "interrupted waitTipChanged should return normally" + ); }) .await; } @@ -333,7 +360,7 @@ async fn mining_block_template_inspection() { .await; } -/// waitNext (short timeout), interruptWait, submitSolution (garbage), destroy. +/// waitNext (short timeout), waitNext interrupted by interruptWait, submitSolution (garbage), destroy. #[tokio::test] // Serialized because submitSolution behavior depends on current chain tip. #[serial_test::serial] @@ -355,7 +382,19 @@ async fn mining_block_template_lifecycle() { "waitNext should time out without a new template" ); - // interruptWait — should not crash. + // waitNext — no timeout. Pin a local task on the wait, then interrupt it. + let mut req = template.wait_next_request(); + req.get() + .init_options() + .set_fee_threshold(mining_capnp::MAX_MONEY); + let waiter = tokio::task::spawn_local(req.send().promise); + + // Give the waiter time to block before interrupting. + tokio::time::sleep(Duration::from_millis(100)).await; + assert!( + !waiter.is_finished(), + "waitNext returned before interruptWait" + ); template .interrupt_wait_request() .send() @@ -363,6 +402,14 @@ async fn mining_block_template_lifecycle() { .await .expect("interruptWait should not fail"); + let joined = tokio::time::timeout(Duration::from_secs(10), waiter) + .await + .expect("interrupWait should unblock waitNext"); + assert!( + joined.is_ok_and(|resp| resp.is_ok()), + "interrupted waitNext should return normally" + ); + // submitSolution — garbage coinbase should be rejected. // This mutates the template, so we do it right before destroy. let mut req = template.submit_solution_request(); From f2b9a15aa64588929ab00bf25c1c54999206fcec Mon Sep 17 00:00:00 2001 From: xyzconstant <263061129+xyzconstant@users.noreply.github.com> Date: Sat, 26 Sep 2026 20:59:45 -0300 Subject: [PATCH 11/11] contrib: run tests against a fresh datadir run-tests.sh started the node on the default datadir, so it reused whatever regtest state was already there and left its own behind. Start it on a fresh `/tmp/capnp-type-tests` instad, recreated on every run, and pass it to the tests as `BITCOIN_DATADIR`. Github-Pull: #40 Rebased-From: 369245b91ce2e4e191d2c17c42547f2f49e24c60 --- contrib/run-tests.sh | 9 +++++---- tests/util/bitcoin_core.rs | 26 ++++++++++++++++---------- tests/util/bitcoin_core_wallet.rs | 7 +++++++ 3 files changed, 28 insertions(+), 14 deletions(-) diff --git a/contrib/run-tests.sh b/contrib/run-tests.sh index 96923ed..88923ab 100755 --- a/contrib/run-tests.sh +++ b/contrib/run-tests.sh @@ -15,6 +15,7 @@ fi BITCOIN_SRC=$(cd "$1" && pwd) REPO_ROOT=$(cd "$(dirname "$0")/.." && pwd) BITCOIN_BIN="$BITCOIN_SRC/build/bin/bitcoin" +TEMP_DATADIR=$(mktemp -d) echo "==> Building Bitcoin Core in $BITCOIN_SRC" ( @@ -31,17 +32,17 @@ echo "==> Building Bitcoin Core in $BITCOIN_SRC" stop_bitcoin() { if [ -n "${BITCOIN_STARTED:-}" ]; then echo "==> Stopping bitcoin" - "$BITCOIN_BIN" rpc -chain=regtest stop || true + "$BITCOIN_BIN" rpc -chain=regtest -datadir="$TEMP_DATADIR" stop || true fi } trap stop_bitcoin EXIT -echo "==> Starting bitcoin node (regtest, IPC)" -"$BITCOIN_BIN" node -chain=regtest -ipcbind=unix -server -debug=ipc -daemon +echo "==> Starting bitcoin node (regtest, IPC) with -datadir=$TEMP_DATADIR" +"$BITCOIN_BIN" node -chain=regtest -ipcbind=unix -server -debug=ipc -datadir="$TEMP_DATADIR" -daemon BITCOIN_STARTED=1 echo "==> Running cargo test" ( cd "$REPO_ROOT" - BITCOIN_BIN="$BITCOIN_BIN" cargo test + BITCOIN_BIN="$BITCOIN_BIN" BITCOIN_DATADIR="$TEMP_DATADIR" cargo test ) diff --git a/tests/util/bitcoin_core.rs b/tests/util/bitcoin_core.rs index b830e16..1efebab 100644 --- a/tests/util/bitcoin_core.rs +++ b/tests/util/bitcoin_core.rs @@ -5,7 +5,8 @@ use std::{ }; use crate::util::bitcoin_core_wallet::{ - bitcoin_rpc_json, bitcoin_test_wallet, ensure_wallet_loaded, mine_blocks_to_new_address, + bitcoin_datadir, bitcoin_rpc_json, bitcoin_test_wallet, ensure_wallet_loaded, + mine_blocks_to_new_address, }; use bitcoin_capnp_types::{ init_capnp::init, @@ -23,15 +24,20 @@ use tokio_util::compat::{Compat, TokioAsyncReadCompatExt, TokioAsyncWriteCompatE static CHAIN_SETUP: Once = Once::new(); pub fn unix_socket_path() -> PathBuf { - let home_dir_string = std::env::var("HOME").unwrap(); - let home_dir = home_dir_string.parse::().unwrap(); - let bitcoin_dir = if cfg!(target_os = "macos") { - home_dir - .join("Library") - .join("Application Support") - .join("Bitcoin") - } else { - home_dir.join(".bitcoin") + let bitcoin_dir = match bitcoin_datadir() { + Some(datadir) => datadir.parse::().unwrap(), + None => { + let home_dir_string = std::env::var("HOME").unwrap(); + let home_dir = home_dir_string.parse::().unwrap(); + if cfg!(target_os = "macos") { + home_dir + .join("Library") + .join("Application Support") + .join("Bitcoin") + } else { + home_dir.join(".bitcoin") + } + } }; let regtest_dir = bitcoin_dir.join("regtest"); regtest_dir.join("node.sock") diff --git a/tests/util/bitcoin_core_wallet.rs b/tests/util/bitcoin_core_wallet.rs index 9c37fdf..e8fb4db 100644 --- a/tests/util/bitcoin_core_wallet.rs +++ b/tests/util/bitcoin_core_wallet.rs @@ -9,6 +9,10 @@ fn bitcoin_bin() -> String { std::env::var("BITCOIN_BIN").unwrap_or_else(|_| "bitcoin".to_owned()) } +pub fn bitcoin_datadir() -> Option { + std::env::var("BITCOIN_DATADIR").ok() +} + fn bitcoin_rpc(wallet: Option<&str>, args: &[&str]) -> Result { let owned_args: Vec = args.iter().map(|arg| (*arg).to_owned()).collect(); bitcoin_rpc_owned(wallet, &owned_args) @@ -29,6 +33,9 @@ pub fn bitcoin_test_wallet() -> String { fn bitcoin_rpc_owned(wallet: Option<&str>, args: &[String]) -> Result { let mut command = Command::new(bitcoin_bin()); command.arg("rpc").arg("-chain=regtest").arg("-rpcwait"); + if let Some(datadir) = bitcoin_datadir() { + command.arg(format!("-datadir={datadir}")); + } if let Some(wallet) = wallet { command.arg(format!("-rpcwallet={wallet}")); }