fix: get uxtos stall

[fdefelici]

Description

This draft PR demonstrates a potential issue where the BitcoinRegtestController::get_utxos(..) method can stall under specific conditions.

The test test_get_utxos_none_due_to_filter_block_height() illustrates how the method may hang when called with a block height that has not yet been reached by the Bitcoin chain, producing this error log:

ERRO [1751452888.622912] [testnet/stacks-node/src/burnchains/bitcoin_regtest_controller.rs:775] [burnchains::bitcoin_regtest_controller::tests::test_get_utxos_none_due_to_filter_block_height] Bitcoin RPC failure: error listing utxos Network("IO Error: Custom { kind: Other, error: \"HTTP 'POST /' did not succeed (500 != 200). Response body = JSON(Object {\\\"error\\\": Object {\\\"code\\\": Number(-8), \\\"message\\\": String(\\\"Block height out of range\\\")}, \\\"id\\\": String(\\\"stacks\\\"), \\\"result\\\": Null})\" }")

The root cause is that get_utxos enters an infinite retry loop in case of errors, with a hardcoded 5-second sleep between attempts. As a result, it can stall indefinitely if the error condition persists.

Relevant code snippet:

stacks-core/testnet/stacks-node/src/burnchains/bitcoin_regtest_controller.rs

Lines 765 to 786 in 7d8b675

	let mut utxos = loop {
	let result = BitcoinRPCRequest::list_unspent(
	&self.config,
	filter_addresses.clone(),
	!self.allow_rbf, // if RBF is disabled, then we can use 0-conf txs
	total_required,
	&utxos_to_exclude,
	block_height,
	);
	// Perform request
	match result {
	Ok(utxos) => {
	break utxos;
	}
	Err(e) => {
	error!("Bitcoin RPC failure: error listing utxos {e:?}");
	sleep_ms(5000);
	continue;
	}
	};
	};

More generally, this issue can occur with any persistent error returned by the BitcoinRPCRequest::list_unspent call.

NOTE: The PR is currenly built on top of #6129, which introduces some testing facilities. It will be rebased once that PR is merged.

Applicable issues

• fixes BitcoinRegtestController::get_utxos(..) stalls when providing burn height greater than tip #6225

Additional info (benefits, drawbacks, caveats)

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

[codecov]

Codecov Report

Attention: Patch coverage is 36.89320% with 390 lines in your changes missing coverage. Please review.

Project coverage is 82.16%. Comparing base (f87444b) to head (39c6f92).
Report is 12 commits behind head on develop.

Files with missing lines	Patch %	Lines
...-node/src/burnchains/bitcoin_regtest_controller.rs	36.08%	379 Missing ⚠️
testnet/stacks-node/src/operations.rs	0.00%	6 Missing ⚠️
testnet/stacks-node/src/burnchains/mod.rs	0.00%	5 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #6242      +/-   ##
===========================================
+ Coverage    77.99%   82.16%   +4.17%     
===========================================
  Files          541      541              
  Lines       344244   344838     +594     
  Branches       323      323              
===========================================
+ Hits        268496   283340   +14844     
+ Misses       75740    61490   -14250     
  Partials         8        8              

Files with missing lines	Coverage Δ
stacks-common/src/util/mod.rs	88.88% <100.00%> (+1.19%)	⬆️
testnet/stacks-node/src/tests/bitcoin_regtest.rs	89.16% <100.00%> (+0.18%)	⬆️
testnet/stacks-node/src/tests/mod.rs	86.21% <ø> (ø)
testnet/stacks-node/src/burnchains/mod.rs	62.50% <0.00%> (-28.41%)	⬇️
testnet/stacks-node/src/operations.rs	72.72% <0.00%> (-8.91%)	⬇️
...-node/src/burnchains/bitcoin_regtest_controller.rs	76.20% <36.08%> (-11.79%)	⬇️

... and 207 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 f87444b...39c6f92. 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.