refactor: BitcoinCoreController rcp rollout + housekeeping

[fdefelici]

Description

This patch is a follow-up to #6329 and introduces the following changes :

• New method roll out: adoption of new BitcoinCoreController methods introduced in refactor: bitcoin rpc porting #6329.
• RPC migration: migration from BitcoinRPCRequest to BitcoinRpcClient, replacing stop api.
• Housekeeping: test updates, documentation, logging (replacing eprintln!), and standardized error handling.
• Module reorganization: with helium now definitively deprecated, its misplaced tests near BitcoinCoreController have been removed, and BitcoinCoreController module reorganized.

Here a commit breakdown for easier review:

• Commit 1-7 (up to 4f2e749): are about: New method roll-out, RPC Migration and Housekeeping
• Commit 8 (da1bf1d): removes deprecated helium tests
• Commit 9 (3429977): move a BitcoinCoreController related test from neon_integration.rs
• Commit 10 (4a9dfd9): introduces a dedicated bitcoin module structure, moving BitcoinCoreController related code in src/burnchain/bitcoin/core_controller.rs (for logic) and src/tests/bitcoin/core_controller_integrations.rs (for integration tests)

Basically up-to Commit 9, the changes are related to the existing src/tests/bitcoin_regtest.rs module, while in Commit 10 the module bitcoin_regtest.rs is split into src/burnchain/bitcoin/core_controller.rs and src/tests/bitcoin/core_controller_integrations.rs.

The new structure should make it easier to locate and maintain Bitcoin-related code and tests. Once the BitcoinRegtestsController refactor is complete, we can fully consolidate the structure (tracked in #6251).

If Commit 10 feels too large for this PR, I can move it into a follow-up PR.

Applicable issues

• fixes Refactor: BitcoinRPCRequest Porting #6250

Additional info (benefits, drawbacks, caveats)

A couple of additional refactoring opportunities:

• The existing tests in stacks-node/src/tests/bitcoin_regtest.rs (bitcoind_integration_test and bitcoind_integration_test_segwit) appear more closely related to RunLoop in stacks-node/src/run_loop/helium.rs. Even though they exercise BitcoinCoreController behavior as a side effect (as most integration tests do), it may be more consistent to move them into stacks-node/src/tests/integrations.rs, alongside other similar integration tests.

stacks-core/stacks-node/src/tests/bitcoin_regtest.rs

Lines 152 to 168 in aaed1cc

	#[test]
	#[ignore]
	fn bitcoind_integration_test() {
	if env::var("BITCOIND_TEST") != Ok("1".into()) {
	return;
	}
	bitcoind_integration(false);
	}
	#[test]
	#[ignore]
	fn bitcoind_integration_test_segwit() {
	if env::var("BITCOIND_TEST") != Ok("1".into()) {
	return;
	}
	bitcoind_integration(true);
	}

• Even if primarily a test utility, it could make sense to move BitcoinCoreController alongside BitcoinRegtestController under stacks-node/src/burnchains. This could help to consolidate Bitcoin-related code in one place.

Checklist

• Test coverage for new or modified code paths
• Changelog is updated
• Required documentation changes (e.g., docs/rpc/openapi.yaml and rpc-endpoints.md for v2 endpoints, event-dispatcher.md for new events)
• New clarity functions have corresponding PR in clarity-benchmarking repo
• New integration test(s) added to bitcoin-tests.yml

[jcnelson]

The existing tests in stacks-node/src/tests/bitcoin_regtest.rs (bitcoind_integration_test and bitcoind_integration_test_segwit) appear more closely related to RunLoop in stacks-node/src/run_loop/helium.rs. Even though they exercise BitcoinCoreController behavior as a side effect (as most integration tests do), it may be more consistent to move them into stacks-node/src/tests/integrations.rs, alongside other similar integration tests.

helium.rs should be considered deprecated, as well as the tests for it. The Helium network was an early devnet implementation before Clarinet existed. It and its runloop can and should be removed, and its integration tests repurposed / refactored to work on the mainnet node implementation. We had kept it around because for a time it was not clear whether or not it was still being used, but I don't think it's needed anymore (cc @kantai @obycode @zone117x @hugoclrd)

[fdefelici]

The existing tests in stacks-node/src/tests/bitcoin_regtest.rs (bitcoind_integration_test and bitcoind_integration_test_segwit) appear more closely related to RunLoop in stacks-node/src/run_loop/helium.rs. Even though they exercise BitcoinCoreController behavior as a side effect (as most integration tests do), it may be more consistent to move them into stacks-node/src/tests/integrations.rs, alongside other similar integration tests.

helium.rs should be considered deprecated, as well as the tests for it. The Helium network was an early devnet implementation before Clarinet existed. It and its runloop can and should be removed, and its integration tests repurposed / refactored to work on the mainnet node implementation. We had kept it around because for a time it was not clear whether or not it was still being used, but I don't think it's needed anymore (cc @kantai @obycode @zone117x @hugoclrd)

Good to know, thanks! I had also noticed some helium related logic in the BitcoinRegtestController implementation, and I was planning to ask in another PR whether that behavior should still be preserved.

If it’s confirmed that helium is no longer needed, I could then:

• Drop the tests in stacks-node/src/tests/bitcoin_regtest.rs as part of this PR
• Open a dedicated issue to track the removal of helium related code across the codebase

[fdefelici]

For the record: @obycode confirmed that Hiro is still using helium for some API integration testing. However, those tests depend on an outdated Stacks image, so Hiro will need to rewrite them regardless.

With that in mind, we can safely proceed with removing helium from the codebase.

I’ve opened a dedicated issue (#6408) to track this work.

[obycode]

This looks great!

[jferrant]

This was so easy to follow. Looks great. :)

[codecov]

Codecov Report

❌ Patch coverage is 75.07331% with 85 lines in your changes missing coverage. Please review.
✅ Project coverage is 75.17%. Comparing base (26112c7) to head (4a9dfd9).
⚠️ Report is 60 commits behind head on develop.

Files with missing lines	Patch %	Lines
stacks-node/src/tests/neon_integrations.rs	60.78%	20 Missing ⚠️
stacks-node/src/tests/nakamoto_integrations.rs	66.66%	15 Missing ⚠️
...-node/src/burnchains/bitcoin_regtest_controller.rs	39.13%	14 Missing ⚠️
stacks-node/src/tests/epoch_21.rs	0.00%	13 Missing ⚠️
...cks-node/src/burnchains/bitcoin/core_controller.rs	94.84%	5 Missing ⚠️
stacks-node/src/tests/epoch_205.rs	0.00%	4 Missing ⚠️
.../src/tests/bitcoin/core_controller_integrations.rs	95.58%	3 Missing ⚠️
stacks-node/src/tests/bitcoin_rpc_integrations.rs	90.32%	3 Missing ⚠️
stacks-node/src/tests/epoch_22.rs	0.00%	3 Missing ⚠️
stacks-node/src/tests/epoch_24.rs	0.00%	2 Missing ⚠️
... and 2 more

❌ Your project status has failed because the head coverage (75.17%) is below the target coverage (80.00%). You can increase the head coverage or adjust the target coverage.

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #6385      +/-   ##
===========================================
- Coverage    75.62%   75.17%   -0.45%     
===========================================
  Files          555      556       +1     
  Lines       350915   350622     -293     
===========================================
- Hits        265365   263588    -1777     
- Misses       85550    87034    +1484     

Files with missing lines	Coverage Δ
stacks-node/src/burnchains/mod.rs	62.50% <ø> (ø)
...-node/src/burnchains/rpc/bitcoin_rpc_client/mod.rs	95.20% <ø> (ø)
...tacks-node/src/burnchains/rpc/rpc_transport/mod.rs	92.75% <ø> (+1.44%)	⬆️
stacks-node/src/tests/mod.rs	73.20% <ø> (+4.90%)	⬆️
stacks-node/src/tests/signer/mod.rs	53.96% <100.00%> (+4.77%)	⬆️
stacks-node/src/tests/epoch_23.rs	0.00% <0.00%> (ø)
stacks-node/src/tests/epoch_24.rs	0.00% <0.00%> (ø)
stacks-node/src/tests/stackerdb.rs	0.00% <0.00%> (ø)
.../src/tests/bitcoin/core_controller_integrations.rs	95.58% <95.58%> (ø)
stacks-node/src/tests/bitcoin_rpc_integrations.rs	90.70% <90.32%> (+0.57%)	⬆️
... and 7 more

... and 304 files with indirect coverage changes

---

Continue to review full report in Codecov by Sentry.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 26112c7...4a9dfd9. Read the comment docs.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.