Gate backend-specific full_scan options by emma31-dev · Pull Request #367 · bitcoindevkit/bdk-cli

emma31-dev · 2026-10-25T15:34:20Z

Description

Make full_scan options reflect backend support: gate --scan-stop-gap to Electrum/Esplora builds and make Esplora's --parallel-request an optional override of the wallet-configured request count. Related to #340 .

Notes to the reviewers

The RPC backend still scans blocks through Emitter and does not use stop_gap as a lookahead. This change removes the option from RPC-only builds but does not make RPC discover funds beyond its current lookahead. In builds with multiple backend features enabled, the compile-time flag may still be available when the wallet is configured for RPC.

Checklists

All Submissions:

I've signed all my commits
I followed the contribution guidelines
I ran cargo fmt and cargo clippy before committing

New Features:

I've added tests for the new feature
I've added docs for the new feature

Olorunshogo · 2026-11-06T08:23:41Z

I tested this locally against #340 (regtest, Core v32.1.0, funds only at external index 30, RPC wallet):

Build	`full_scan`	`full_scan --scan-stop-gap 100`
`--features rpc`	exit 0, balance 0	rejected: `unexpected argument '--scan-stop-gap'`
`--features rpc,esplora`	exit 0, balance 0	accepted, exit 0, balance 0

Rejecting the flag in RPC-only builds is a nice improvement over silently ignoring it. In a multi-backend build, though, the flag is still accepted and ignored when the wallet uses RPC, because the gate is compile-time while the backend is picked at runtime from the wallet config. A runtime check on the client type would cover that case.

A few smaller things:

The --parallel-request change seems separate from full_scan over RPC ignores --scan-stop-gap: restored wallet silently misses funds at external index >= 25 #340 . It might be easier to review in its own PR.
The CHANGELOG line is in the middle of the Unreleased list rather than at the end.

Full reproduction details are in my comment on #340.

emma31-dev · 2026-11-06T10:01:44Z

Thanks for bringing this up I'll make the change soon

Olorunshogo

Tested b929aa1 against master (regtest, Core v32.1.0, Esplora electrs, built with rpc,esplora,electrum).

The runtime check works: an RPC wallet now rejects --scan-stop-gap and --parallel-request with a clear error instead of silently ignoring them, and Electrum rejects --parallel-request. Esplora and Electrum scans behave the same as on master, including --scan-stop-gap 40 recovering funds at index 30. Clippy is clean with rpc,esplora,electrum and with rpc only.

Left two inline comments: the STOP_GAP env var now breaks RPC scans, and the default of 20 no longer shows in --help.

Smaller: the PR description still says the flag may be available for RPC wallets in multi-backend builds, which the runtime check now prevents, and the branch has a merge commit.

Happy to ACK once the two inline points are addressed.

Olorunshogo · 2026-11-07T11:46:18Z

-    #[clap(long, default_value = "5")]
-    pub parallel_request: usize,
+    #[cfg(any(feature = "electrum", feature = "esplora"))]
+    #[arg(env = "STOP_GAP", long = "scan-stop-gap")]


Since this still reads STOP_GAP from the environment, an RPC full_scan fails when STOP_GAP is set, even if --scan-stop-gap isn't passed. I reproduced it: with STOP_GAP=50 exported, an RPC wallet errors with "--scan-stop-gap is only supported by the electrum and esplora backends", while the same scan works on master.

I don't think I can gate the env parsing. What do you suggest I do here?

Maybe I'll include it in the error message

Fixed in b6e54bf, thanks!

Olorunshogo · 2026-11-07T11:47:22Z

                client.populate_tx_cache(wallet.tx_graph().full_txs().map(|tx_node| tx_node.tx));
-                let update = client.full_scan(request, self.stop_gap, *batch_size, false)?;
+                let update =
+                    client.full_scan(request, self.stop_gap.unwrap_or(20), *batch_size, false)?;


With default_value = "20" gone, full_scan --help no longer shows [default: 20], and 20 is now repeated here and in the Esplora branch. A shared constant like DEFAULT_STOP_GAP, mentioned in the doc comment, would keep the default visible and in one place.

I was thinking of this yesterday thanks for bringing this up

Fixed in b6e54bf, thanks!

emma31-dev · 2026-11-07T11:58:45Z

@Olorunshogo Thanks for the review. I'll fix the minor issues.

emma31-dev · 2026-11-09T21:56:01Z

@vadim-anfv I would appreciate a review on this when you have the time.

The RPC and CBF backends never use `stop_gap`, so accepting the flag silently ignored it. Gate the option to the Electrum and Esplora backends and reject it at runtime for RPC and CBF wallets in multi-backend builds, where the backend is chosen from the wallet config rather than at compile time. Read `STOP_GAP` in the handler rather than through clap so that a globally exported value no longer turns an RPC or CBF scan into an error when the flag was never passed, while supported backends keep the environment behaviour. Keep the default of 20 in one place (`DEFAULT_STOP_GAP`) and document it, with the env var, in `--help`. Related to bitcoindevkit#340.

codecov · 2026-11-12T16:31:30Z

Codecov Report

❌ Patch coverage is 47.22222% with 19 lines in your changes missing coverage. Please review.
✅ Project coverage is 59.89%. Comparing base (5558555) to head (b6e54bf).
⚠️ Report is 1 commits behind head on master.

Files with missing lines	Patch %	Lines
src/handlers/online.rs	47.22%	19 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #367      +/-   ##
==========================================
- Coverage   60.00%   59.89%   -0.12%     
==========================================
  Files          25       25              
  Lines        4736     4770      +34     
==========================================
+ Hits         2842     2857      +15     
- Misses       1894     1913      +19

Flag	Coverage Δ
rust	`59.89% <47.22%> (-0.12%)`	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

vadim-anfv

tACK b6e54bf

Tested with no node running, so a scan fails at the connection and the gate is the only thing under test.

Setup, on an rpc,electrum,esplora build:

w() {
  cargo run -q --features rpc,electrum,esplora -- \
    -n regtest -d /tmp/bdk367 wallet -w rpc "$@"
}

w config -f \
  -e 'wpkh(tpubDDnGNapGEY6AZAdQbfRJgMg9fvz8pUBrLwvyvUqEgcUfgzM6zc2eVK4vY9x9L5FJWdX8WumXuLEDV5zDZnTfbn87vLe9XceCFwTu9so9Kks/0/*)' \
  -c rpc --database-type sqlite -u http://127.0.0.1:18443

The flag is present:

$ w full_scan --help
Options:
      --scan-stop-gap <STOP_GAP>
          Stop searching addresses for transactions after finding an unused gap of this length. Only available with the `electrum` and `esplora` backends. When the flag is omitted, the `STOP_GAP` environment variable is read if it is set. [default: 20]

An RPC wallet rejects it:

$ w full_scan --scan-stop-gap 100
Error: Generic error: `--scan-stop-gap` is only supported by the electrum and esplora backends

Without the flag the same wallet gets past the check:

$ w full_scan
Error: RPC error: JSON-RPC error: transport error: Couldn't connect to host: Connection refused (os error 111)

In an rpc only build the flag does not exist at all:

$ cargo run -q --no-default-features --features rpc,sqlite -- \
    -n regtest -d /tmp/bdk367 wallet -w rpc full_scan --scan-stop-gap 100
error: unexpected argument '--scan-stop-gap' found

Usage: bdk-cli wallet --wallet <WALLET> full_scan [OPTIONS]

For more information, try '--help'.

Thanks @Olorunshogo for the thorough testing and review. I did not test myself that the stop gap still reaches the Electrum and Esplora clients after the refactor.

@emma31-dev please update the PR description, it still describes the first version: the flag available for RPC wallets in multi-backend builds, and --parallel-request becoming an override. Neither matches the diff now.

vadim-anfv · 2026-11-12T16:15:45Z

+                #[cfg(any(feature = "electrum", feature = "esplora"))]
+                if self.stop_gap.is_some() {
+                    return Err(Error::Generic(
+                        "`--scan-stop-gap` is only supported by the electrum and esplora backends"
+                            .into(),
+                    ));
+                }


Nit: the rejection block is identical in the RPC and CBF arms, and each copy carries its own #[cfg(any(feature = "electrum", feature = "esplora"))]. A small fn reject_stop_gap(&self) -> Result<(), Error> next to stop_gap() would leave one cfg instead of three and one copy of the message.

Olorunshogo

tACK b6e54bf

Thanks for working through the env var issue, moving the STOP_GAP read into stop_gap() solves it cleanly.

Tested against master on regtest (Core v32.1.0, Esplora electrs, built with rpc,esplora,electrum).

Non-blocking:

STOP_GAP=0 is accepted and scans nothing, while the error says "must be a positive integer". Same as master, but rejecting 0 or saying "non-negative" would match.

github-project-automation Bot added this to BDK-CLI Oct 25, 2026

github-project-automation Bot moved this to Todo in BDK-CLI Oct 25, 2026

emma31-dev force-pushed the fix/full-scan-backend-options branch from 2fc5eb8 to 922dd64 Compare October 25, 2026 15:55

emma31-dev changed the title ~~Allow overriding Esplora scan parallelism~~ Gate backend-specific full_scan options Oct 25, 2026

Olorunshogo mentioned this pull request Nov 6, 2026

full_scan over RPC ignores --scan-stop-gap: restored wallet silently misses funds at external index >= 25 #340

Open

emma31-dev force-pushed the fix/full-scan-backend-options branch from 14a82b5 to f2c493e Compare November 6, 2026 13:20

Olorunshogo reviewed Nov 7, 2026

View reviewed changes

emma31-dev force-pushed the fix/full-scan-backend-options branch 2 times, most recently from 797c619 to 0e2f54b Compare November 7, 2026 16:11

emma31-dev requested a review from Olorunshogo November 9, 2026 21:32

emma31-dev force-pushed the fix/full-scan-backend-options branch from 0e2f54b to b6e54bf Compare November 10, 2026 11:21

vadim-anfv approved these changes Nov 12, 2026

View reviewed changes

Olorunshogo approved these changes Nov 12, 2026

View reviewed changes

Conversation

emma31-dev commented Oct 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Notes to the reviewers

Checklists

All Submissions:

New Features:

Uh oh!

Olorunshogo commented Nov 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

emma31-dev commented Nov 6, 2026

Uh oh!

Olorunshogo 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!

emma31-dev commented Nov 7, 2026

Uh oh!

emma31-dev commented Nov 9, 2026

Uh oh!

codecov Bot commented Nov 12, 2026

Codecov Report

Uh oh!

vadim-anfv left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Olorunshogo left a comment

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

emma31-dev commented Oct 25, 2026 •

edited

Loading

Olorunshogo commented Nov 6, 2026 •

edited

Loading