`bitcoin_core_sv2` supports multiple versions of Bitcoin Core (v30.x + v31.x) by plebhash · Pull Request #548 · stratum-mining/sv2-apps

plebhash · 2026-06-08T21:22:24Z

close #516

in summary:

bitcoin_core_sv2 now supports both Bitcoin Core IPC v30.x and v31.x via one common API with versioned backends.
template_provider_type.BitcoinCoreIpc.version is now required (30 or 31) and wired through Pool/JDC/JDS runtime selection.
Added focused integration coverage for both versions in new IPC IO tests (JDP + TDP).
Docker config is now version-configurable via:
- POOL_BITCOIN_CORE_IPC_VERSION
- JDC_BITCOIN_CORE_IPC_VERSION

note: should be merged after #545

plebhash · 2026-06-18T20:33:07Z

Why didn't we get CI failures on #553 though?

I asked gpt-5.3-codex a similar question earlier:

Great question. Short answer: PR #573 was close, but still below the runner disk limit; PR #548 crossed it.

What’s different:

PR bump asic-rs to v0.6.2 #573 (run 27775350660, MSRV job 82185981896) used the same workflow and succeeded, including integration-tests --no-run.

In bitcoin_core_sv2 supports multiple versions of Bitcoin Core (v30.x + v31.x) #548 (run 27780182723, job 82202664566), logs show extra compile footprint from the multi-version runtime stack:

repeated capnp v0.21.7 builds across multiple workspaces (in addition to v0.25.x).

PR bump asic-rs to v0.6.2 #573 log does not show capnp v0.21.x.

Your branch also enables the facade feature in integration tests (integration-tests/Cargo.toml:17 includes bitcoin-core-sv2), which increases what gets compiled/linked in that job.

MSRV runs all workspace builds and then all test --no-run in one runner (.github/workflows/msrv.yaml:23 through .github/workflows/msrv.yaml:58), so artifact accumulation is the killer.

Result: PR bump asic-rs to v0.6.2 #573 stayed under threshold; bitcoin_core_sv2 supports multiple versions of Bitcoin Core (v30.x + v31.x) #548 hit /usr/bin/ld ... No space left on device.

So this is mostly a capacity threshold + branch footprint issue, not a “new code error.”

IIUC this PR is already increasing the build artifact footprint due to:

multiple capnp + capnp-rpc crate versions on the dependency list
more source code

then #553 increased it further with the addition of asic-rs

and now the combination of both started pushing the github runners over the limit

plebhash · 2026-06-18T20:39:26Z

also getting similar disk-out-of-space errors after merging #531:

so maybe f4a88f8 is not enough, and we might continue to get flaky PITA over this.... let's see

GitGab19

Besides of my last comments, which are only about the msrv.yaml workflow changes, I just tested with both v30.2 and v31, and everything worked fine!

tACK

Shourya742

Some suggestions and questions

Shourya742 · 2026-06-22T08:26:06Z


-      - name: Check test compilation for jd-server
-        run: cargo test --manifest-path=pool-apps/jd-server/Cargo.toml --no-run
-


this makes sense, can you do the same in ci,yaml and lockfile.yaml

Shourya742 · 2026-06-22T08:50:09Z


                let bitcoin_core_cancellation_token = CancellationToken::new();
                let bitcoin_core_config = BitcoinCoreSv2TDPConfig {
+                    version: version.to_bitcoin_core_version(),


why we have two different versioning shouldn't they be the same?

I also don't love the duplication of stratum-apps::tp_type::BitcoinCoreIpcVersion vs bitcoin_core_sv2::common::BitcoinCoreVersion

we can get rid of stratum-apps::tp_type::BitcoinCoreIpcVersion in favor of bitcoin_core_sv2::common::BitcoinCoreVersion, but with the tradeoff of having stratum-apps::tp_type::TemplateProviderType::BitcoinCoreIpc variant behind bitcoin-core-sv2 feature gate

tbh, that feels like a reasonable tradeoff, implementing it

Shourya742 · 2026-06-22T08:53:41Z

+    #[cfg(feature = "bitcoin-core-sv2")]
+    pub fn to_bitcoin_core_version(self) -> bitcoin_core_sv2::common::BitcoinCoreVersion {
+        bitcoin_core_sv2::common::BitcoinCoreVersion::try_from(self.as_major())
+            .expect("BitcoinCoreIpcVersion and BitcoinCoreVersion majors must stay aligned")
+    }


Shouldn't this be a from instead of try_from, considering we already converted from config to BitcoinCoreIpcVersion enum and after than any conversion should be lossless.

based on the adaptations from #548 (comment), this is no longer relevant

Shourya742 · 2026-06-22T08:53:59Z

+    }
 }

 impl TryFrom<u16> for BitcoinCoreIpcVersion {


Shouldn't this be u8?

based on the adaptations from #548 (comment), this is no longer relevant

Shourya742 · 2026-06-22T09:59:16Z

+#[async_trait::async_trait(?Send)]
+pub trait Sv2TemplateDistributionProtocol {
+    async fn run(&mut self);
+}
+
+/// Version-agnostic TDP runtime handle.
+///
+/// Instances are created with [`new`], which selects the concrete backend for the requested
+/// [`BitcoinCoreVersion`].
+pub type BitcoinCoreSv2TDP = Box<dyn Sv2TemplateDistributionProtocol>;


We can model it via enums having a common interface, something like this:

pub enum BitcoinCoreSv2TDP { V30X(v30x::template_distribution_protocol::BitcoinCoreSv2TDP), V31X(v31x::template_distribution_protocol::BitcoinCoreSv2TDP), } impl BitcoinCoreSv2TDP { pub async fn run(&mut self) { match self { Self::V30X(runtime) => runtime.run().await, Self::V31X(runtime) => runtime.run().await, } } }

Would help in removal of async_trait and vtable lookup

when I originally wrote the scope of #516 I explicitly mentioned the introduction of traits on the common module, which would serve the purpose of establishing clear interfaces for which all different version implementations would follow

but the implementation converged towards a very thin trait interface (limited to a single run method), which honestly makes it not so much valuable anymore

I think this suggestion makes sense, since we'd still be following the same run pattern, while enforcing it inside the match

so yeah thanks for the suggestion @Shourya742 implementing it

Shourya742 · 2026-06-22T10:18:28Z

+    async fn run(&mut self) {
+        BitcoinCoreSv2TDP::run(self).await;
+    }
+}


This can removed with enum dispatch.

Shourya742 · 2026-06-22T10:19:27Z

+#[async_trait::async_trait(?Send)]
+pub trait Sv2JobDeclarationProtocol {
+    async fn run(&self);
+}
+
+/// Version-agnostic JDP runtime handle.
+///
+/// Instances are created with [`new`], which selects the concrete backend for the requested
+/// [`BitcoinCoreVersion`].
+pub type BitcoinCoreSv2JDP = Box<dyn Sv2JobDeclarationProtocol>;


The enum variant for this can be very similar?

pub enum BitcoinCoreSv2JDP { V30X(v30x::job_declaration_protocol::BitcoinCoreSv2JDP), V31X(v31x::job_declaration_protocol::BitcoinCoreSv2JDP), } impl BitcoinCoreSv2JDP { pub async fn run(&self) { match self { Self::V30X(runtime) => runtime.run().await, Self::V31X(runtime) => runtime.run().await, } } }

Shourya742 · 2026-06-22T10:19:58Z

+#[derive(Debug)]
+pub struct BitcoinCoreSv2JDPError {
+    version: BitcoinCoreVersion,
+    details: String,
+}
+
+impl fmt::Display for BitcoinCoreSv2JDPError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(
+            f,
+            "failed to initialize bitcoin_core_sv2 JDP for v{}: {}",
+            self.version.as_major(),
+            self.details
+        )
+    }
+}
+
+impl std::error::Error for BitcoinCoreSv2JDPError {}


We can abstract it out with common Error from common module

Shourya742 · 2026-06-22T10:25:55Z

+impl BitcoinCoreVersion {
+    pub const fn as_major(self) -> u8 {
+        match self {
+            Self::V30X => 30,
+            Self::V31X => 31,
+        }
+    }
+}


Maybe the new methods can become part of the version fields itself, instead of us having to pass version in the new constructor:

pub async fn new_jdp<P>( self, bitcoin_core_unix_socket_path: P, incoming_requests: async_channel::Receiver<job_declaration_protocol::io::JdRequest>, cancellation_token: tokio_util::sync::CancellationToken, ready_tx: tokio::sync::oneshot::Sender<()>, ) -> Result<job_declaration_protocol::BitcoinCoreSv2JDP, BitcoinCoreSv2Error> where P: AsRef<std::path::Path>, { ... } /// Builds a TDP runtime for this Bitcoin Core IPC schema family. #[allow(clippy::too_many_arguments)] pub async fn new_tdp<P>( self, bitcoin_core_unix_socket_path: P, fee_threshold: u64, min_interval: u8, incoming_messages: async_channel::Receiver< stratum_core::parsers_sv2::TemplateDistribution<'static>, >, outgoing_messages: async_channel::Sender< stratum_core::parsers_sv2::TemplateDistribution<'static>, >, global_cancellation_token: tokio_util::sync::CancellationToken, ) -> Result<template_distribution_protocol::BitcoinCoreSv2TDP, BitcoinCoreSv2Error> where P: AsRef<std::path::Path>, { ... }

specific version association attached to version itself.

I experimented with this but I didn't like the result... adding a new_jdp/new_tdp constructors to BitcoinCoreVersion feels like we're mixing abstractions

keeping as-is

Shourya742 · 2026-06-22T10:27:22Z

@@ -0,0 +1,126 @@
+//! Local mempool mirror for Bitcoin Core v31.x Sv2 Job Declaration Protocol via capnp over UNIX


Can we move the common module at the same level as versioning module?

I think its the same file as v30x?

that's similar to what's already been discussed here: #548 (comment)

Can we move the common module at the same level as versioning module?

tbh if we were to do this, we should apply the same pattern across the entire crate, which is the scope of #574

I just read the issue, with the current structuring it won't be easy for us to remove duplication. I am now thinking whether it will be viable to have version based distinct implementation, like in a method, based on version we can have different implementation (via match). What you think of this?

when I discussed this with @GitGab19 the consensus was to leave code de-duplication as something to be solved later.

I also don't fully understand what you're trying to say on the comment above.

with the current structuring it won't be easy for us to remove duplication.

by "current structuring" do you mean what is being done on this PR or what's proposed on #574?

I am now thinking whether it will be viable to have version based distinct implementation, like in a method, based on version we can have different implementation (via match). What you think of this?

assuming this suggestion is meant to be taken as an alternative approach to #574, I first need to understand what you understand as a problem with what was proposed there

and also, do you think this is something that needs to be addressed now?

if not, we should discuss it under #574 and not here

plebhash force-pushed the 2026-05-27-bitcoin-core-sv2-multi-version branch 20 times, most recently from 14a8b80 to c3bf3b1 Compare June 9, 2026 01:20

Shourya742 self-requested a review June 9, 2026 16:52

plebhash force-pushed the 2026-05-27-bitcoin-core-sv2-multi-version branch 4 times, most recently from df3ce2a to 9a17e32 Compare June 9, 2026 20:25

plebhash marked this pull request as ready for review June 9, 2026 20:26

plebhash force-pushed the 2026-05-27-bitcoin-core-sv2-multi-version branch from 9a17e32 to d757e22 Compare June 9, 2026 21:13

Shourya742 reviewed Jun 17, 2026

View reviewed changes

plebhash mentioned this pull request Jun 17, 2026

consider heuristics for detecting Bitcoin Core version #570

Open

plebhash force-pushed the 2026-05-27-bitcoin-core-sv2-multi-version branch from d757e22 to e0f2a39 Compare June 17, 2026 16:06

GitGab19 mentioned this pull request Jun 18, 2026

Monitoring API updated in PR #553 stratum-mining/sv2-ui#188

Open

3 tasks

plebhash mentioned this pull request Jun 18, 2026

consider shared modules on bitcoin_core_sv2 to avoid code duplication #574

Open

GitGab19 reviewed Jun 19, 2026

View reviewed changes

Comment thread .github/workflows/msrv.yaml Outdated

Comment thread .github/workflows/msrv.yaml Outdated

Comment thread .github/workflows/msrv.yaml Outdated

GitGab19 approved these changes Jun 19, 2026

View reviewed changes

Shourya742 self-requested a review June 19, 2026 10:03

plebhash force-pushed the 2026-05-27-bitcoin-core-sv2-multi-version branch 3 times, most recently from a721748 to 61d1eaf Compare June 19, 2026 13:50

GitGab19 approved these changes Jun 19, 2026

View reviewed changes

Shourya742 reviewed Jun 22, 2026

View reviewed changes

plebhash force-pushed the 2026-05-27-bitcoin-core-sv2-multi-version branch 2 times, most recently from 798d191 to c89290e Compare June 22, 2026 22:31

plebhash added 11 commits June 22, 2026 19:31

refactor bitcoin_core_sv2 for multi-version runtimes

c6cb68b

add optional bitcoin-core-sv2 facade to stratum-apps

58c1dcc

wire pool to common bitcoin_core_sv2 runtime API

76b43ed

wire jd-client to common bitcoin_core_sv2 runtime API

757cace

wire jd-server to common bitcoin_core_sv2 runtime API

fb1081f

document unix_capnp and future backend flavors

76691a9

add v30x and v31x bitcoin-core IPC IO integration tests

2d1cb87

make docker BitcoinCoreIpc version configurable

ae37b48

import tracing macros in bitcoin-core-sv2

1526d04

ci: reduce msrv runner disk pressure

947c058

remove JDS step from CI workflows

91a3d9e

plebhash force-pushed the 2026-05-27-bitcoin-core-sv2-multi-version branch from c89290e to 91a3d9e Compare June 22, 2026 22:31

plebhash mentioned this pull request Jun 22, 2026

version bumps for v0.6.0 #539

Open

plebhash added 2 commits June 22, 2026 19:52

bump bitcoin_core_sv2 to 0.4.0

0f61a6c

bump jd_server_sv2 to 0.4.0

c9ea2b7

plebhash force-pushed the 2026-05-27-bitcoin-core-sv2-multi-version branch from 868fd8a to c9ea2b7 Compare June 22, 2026 23:36


		- name: Check test compilation for jd-server
		run: cargo test --manifest-path=pool-apps/jd-server/Cargo.toml --no-run

		@@ -0,0 +1,126 @@
		//! Local mempool mirror for Bitcoin Core v31.x Sv2 Job Declaration Protocol via capnp over UNIX

Conversation

plebhash commented Jun 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

plebhash commented Jun 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

plebhash commented Jun 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

GitGab19 left a comment

Choose a reason for hiding this comment

Uh oh!

Shourya742 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

plebhash Jun 22, 2026 • 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

plebhash Jun 22, 2026 • 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!

Reviewers

Assignees

Labels

plebhash commented Jun 8, 2026 •

edited

Loading

plebhash commented Jun 18, 2026 •

edited

Loading

plebhash commented Jun 18, 2026 •

edited

Loading

plebhash Jun 22, 2026 •

edited

Loading

plebhash Jun 22, 2026 •

edited

Loading