Generalize recovery_mode to an Option<RecoveryMode> struct

Rather than a binary "rescan from genesis" toggle, the new
`RecoveryMode { rescan_from_height: Option<u32> }` struct lets users
specify an explicit block height to rescan from on bitcoind-backed
nodes. This supports importing wallets on pruned nodes where the full
history is unavailable but the wallet's birthday height is known
(#818).

For Esplora/Electrum backends, `rescan_from_height` is ignored because
those clients do not expose a block-hash-by-height lookup. Instead,
any `Some(RecoveryMode { .. })` forces a one-shot BDK `full_scan` on
the next wallet sync, so funds sent to previously-unknown addresses
are re-discovered.

`None` retains the default "checkpoint at current tip, incremental
sync" behavior. The struct leaves room for future recovery options
(e.g. a timestamp) without another breaking change.

Generated with the assistance of AI (Claude).

Co-Authored-By: HAL 9000

Author: tnull

CHANGELOG.md

@@ -1,5 +1,8 @@
 # Unreleased
 
+## Feature and API updates
+- The `Builder::set_wallet_recovery_mode` method has been generalized to accept an `Option<RecoveryMode>` argument instead of being a no-argument toggle. `RecoveryMode::rescan_from_height` lets users specify an explicit block height to rescan from on bitcoind-backed nodes — useful for restoring a wallet on a pruned node where the wallet's birthday height is known but the full history is unavailable (#818). On Esplora/Electrum backends, any `Some(RecoveryMode { .. })` now forces a one-shot BDK `full_scan` on the next wallet sync to re-discover funds sent to previously-unknown addresses. This is a breaking API change.
+
 ## Bug Fixes and Improvements
 - Building a fresh node against a Bitcoin Core RPC or REST chain source that fails to return the current chain tip now aborts with a new `BuildError::ChainTipFetchFailed` variant instead of silently pinning the wallet birthday to genesis, which would have forced a full-history rescan once the chain source became reachable again.
 

bindings/ldk_node.udl

@@ -60,7 +60,7 @@ interface Builder {
 	void set_node_alias(string node_alias);
 	[Throws=BuildError]
 	void set_async_payments_role(AsyncPaymentsRole? role);
-	void set_wallet_recovery_mode();
+	void set_wallet_recovery_mode(RecoveryMode? recovery_mode);
 	[Throws=BuildError]
 	Node build(NodeEntropy node_entropy);
 	[Throws=BuildError]
@@ -241,6 +241,8 @@ dictionary BestBlock {
 
 typedef enum BuildError;
 
+typedef dictionary RecoveryMode;
+
 [Trait, WithForeign]
 interface VssHeaderProvider {
 	[Async, Throws=VssHeaderProviderError]

src/builder.rs

@@ -257,6 +257,34 @@ impl fmt::Display for BuildError {
 
 impl std::error::Error for BuildError {}
 
+/// Describes how the wallet should be recovered on the next startup.
+///
+/// Pass `Some(RecoveryMode { .. })` to [`NodeBuilder::set_wallet_recovery_mode`] to opt into
+/// recovery behavior; see [`RecoveryMode::rescan_from_height`] for the details of what each
+/// setting does on each chain source.
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
+#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
+pub struct RecoveryMode {
+	/// Where the wallet should start rescanning the chain from on the next startup.
+	///
+	/// Behavior depends on the configured chain source:
+	///
+	/// **`Bitcoind` (RPC or REST):**
+	/// * `None` — no wallet checkpoint is inserted; BDK rescans from genesis. This matches the
+	///   previous `recovery_mode = true` flag.
+	/// * `Some(h)` — the block hash at height `h` is resolved via the chain source and inserted
+	///   as the initial wallet checkpoint, so BDK rescans forward from `h`. Useful for
+	///   restoring a wallet on a pruned node where the full history is unavailable but the
+	///   wallet's birthday height is known.
+	///
+	/// **`Esplora` / `Electrum`:** this field is ignored — the BDK client APIs for these
+	/// backends do not currently expose a block-hash-by-height lookup. Instead, setting any
+	/// `Some(RecoveryMode { .. })` forces a one-shot BDK `full_scan` on the next wallet sync
+	/// after startup — even if the node has synced before — so funds sent to addresses the
+	/// current instance does not yet know about are re-discovered.
+	pub rescan_from_height: Option<u32>,
+}
+
 /// A builder for an [`Node`] instance, allowing to set some configuration and module choices from
 /// the getgo.
 ///
@@ -305,7 +333,7 @@ pub struct NodeBuilder {
 	async_payments_role: Option<AsyncPaymentsRole>,
 	runtime_handle: Option<tokio::runtime::Handle>,
 	pathfinding_scores_sync_config: Option<PathfindingScoresSyncConfig>,
-	recovery_mode: bool,
+	recovery_mode: Option<RecoveryMode>,
 }
 
 impl NodeBuilder {
@@ -323,7 +351,7 @@ impl NodeBuilder {
 		let log_writer_config = None;
 		let runtime_handle = None;
 		let pathfinding_scores_sync_config = None;
-		let recovery_mode = false;
+		let recovery_mode = None;
 		Self {
 			config,
 			chain_data_source_config,
@@ -629,13 +657,17 @@ impl NodeBuilder {
 		Ok(self)
 	}
 
-	/// Configures the [`Node`] to resync chain data from genesis on first startup, recovering any
-	/// historical wallet funds.
+	/// Configures the [`Node`] to perform wallet recovery on the next startup, optionally
+	/// specifying the block height to rescan the chain from.
+	///
+	/// Pass `Some(RecoveryMode { .. })` to enable recovery; pass `None` to clear any previously
+	/// configured recovery mode and use the default "checkpoint at current tip" behavior. See
+	/// [`RecoveryMode`] for the details of what each setting does on each chain source.
 	///
 	/// This should only be set on first startup when importing an older wallet from a previously
 	/// used [`NodeEntropy`].
-	pub fn set_wallet_recovery_mode(&mut self) -> &mut Self {
-		self.recovery_mode = true;
+	pub fn set_wallet_recovery_mode(&mut self, mode: Option<RecoveryMode>) -> &mut Self {
+		self.recovery_mode = mode;
 		self
 	}
 
@@ -1101,13 +1133,17 @@ impl ArcedNodeBuilder {
 		self.inner.write().expect("lock").set_async_payments_role(role).map(|_| ())
 	}
 
-	/// Configures the [`Node`] to resync chain data from genesis on first startup, recovering any
-	/// historical wallet funds.
+	/// Configures the [`Node`] to perform wallet recovery on the next startup, optionally
+	/// specifying the block height to rescan the chain from.
+	///
+	/// Pass `Some(RecoveryMode { .. })` to enable recovery; pass `None` to clear any previously
+	/// configured recovery mode and use the default "checkpoint at current tip" behavior. See
+	/// [`RecoveryMode`] for the details of what each setting does on each chain source.
 	///
 	/// This should only be set on first startup when importing an older wallet from a previously
 	/// used [`NodeEntropy`].
-	pub fn set_wallet_recovery_mode(&self) {
-		self.inner.write().expect("lock").set_wallet_recovery_mode();
+	pub fn set_wallet_recovery_mode(&self, mode: Option<RecoveryMode>) {
+		self.inner.write().expect("lock").set_wallet_recovery_mode(mode);
 	}
 
 	/// Builds a [`Node`] instance with a [`SqliteStore`] backend and according to the options
@@ -1253,8 +1289,8 @@ fn build_with_store_internal(
 	gossip_source_config: Option<&GossipSourceConfig>,
 	liquidity_source_config: Option<&LiquiditySourceConfig>,
 	pathfinding_scores_sync_config: Option<&PathfindingScoresSyncConfig>,
-	async_payments_role: Option<AsyncPaymentsRole>, recovery_mode: bool, seed_bytes: [u8; 64],
-	runtime: Arc<Runtime>, logger: Arc<Logger>, kv_store: Arc<DynStore>,
+	async_payments_role: Option<AsyncPaymentsRole>, recovery_mode: Option<RecoveryMode>,
+	seed_bytes: [u8; 64], runtime: Arc<Runtime>, logger: Arc<Logger>, kv_store: Arc<DynStore>,
 ) -> Result<Node, BuildError> {
 	optionally_install_rustls_cryptoprovider();
 
@@ -1462,7 +1498,7 @@ fn build_with_store_internal(
 			// retain their existing behavior.
 			let is_bitcoind_source =
 				matches!(chain_data_source_config, Some(ChainDataSourceConfig::Bitcoind { .. }));
-			if !recovery_mode && chain_tip_opt.is_none() && is_bitcoind_source {
+			if recovery_mode.is_none() && chain_tip_opt.is_none() && is_bitcoind_source {
 				log_error!(
 					logger,
 					"Failed to determine chain tip on first startup. Aborting to avoid pinning the wallet birthday to genesis."
@@ -1478,23 +1514,62 @@ fn build_with_store_internal(
 					BuildError::WalletSetupFailed
 				})?;
 
-			if !recovery_mode {
-				if let Some(best_block) = chain_tip_opt {
-					// Insert the first checkpoint if we have it, to avoid resyncing from genesis.
-					// TODO: Use a proper wallet birthday once BDK supports it.
-					let mut latest_checkpoint = wallet.latest_checkpoint();
-					let block_id = bdk_chain::BlockId {
-						height: best_block.height,
-						hash: best_block.block_hash,
-					};
-					latest_checkpoint = latest_checkpoint.insert(block_id);
-					let update =
-						bdk_wallet::Update { chain: Some(latest_checkpoint), ..Default::default() };
-					wallet.apply_update(update).map_err(|e| {
-						log_error!(logger, "Failed to apply checkpoint during wallet setup: {}", e);
+			// Decide which block (if any) to insert as the initial BDK checkpoint.
+			// - No recovery mode: use the current chain tip to avoid any rescan.
+			// - Recovery mode with an explicit `rescan_from_height` on a bitcoind backend:
+			//   resolve the block hash at that height and use it as the checkpoint, so BDK
+			//   rescans forward from there.
+			// - Recovery mode otherwise (no explicit height, or non-bitcoind backend): skip
+			//   the checkpoint entirely. For bitcoind this falls back to a full rescan from
+			//   genesis; for Esplora/Electrum the on-chain wallet syncer forces a one-shot
+			//   `full_scan` (see `Wallet::take_force_full_scan`).
+			let checkpoint_block = match recovery_mode {
+				None => chain_tip_opt,
+				Some(RecoveryMode { rescan_from_height: Some(height) }) if is_bitcoind_source => {
+					let utxo_source = chain_source.as_utxo_source().ok_or_else(|| {
+						log_error!(
+							logger,
+							"Recovery mode requested a rescan height but the chain source does not support block-by-height lookups.",
+						);
 						BuildError::WalletSetupFailed
 					})?;
-				}
+					let hash_res = runtime.block_on(async {
+						lightning_block_sync::gossip::UtxoSource::get_block_hash_by_height(
+							&utxo_source,
+							height,
+						)
+						.await
+					});
+					match hash_res {
+						Ok(hash) => Some(BestBlock { block_hash: hash, height }),
+						Err(e) => {
+							log_error!(
+								logger,
+								"Failed to resolve block hash at height {} for wallet rescan: {:?}",
+								height,
+								e,
+							);
+							return Err(BuildError::WalletSetupFailed);
+						},
+					}
+				},
+				Some(_) => None,
+			};
+
+			if let Some(best_block) = checkpoint_block {
+				// Insert the checkpoint so BDK starts scanning from there instead of from
+				// genesis.
+				// TODO: Use a proper wallet birthday once BDK supports it.
+				let mut latest_checkpoint = wallet.latest_checkpoint();
+				let block_id =
+					bdk_chain::BlockId { height: best_block.height, hash: best_block.block_hash };
+				latest_checkpoint = latest_checkpoint.insert(block_id);
+				let update =
+					bdk_wallet::Update { chain: Some(latest_checkpoint), ..Default::default() };
+				wallet.apply_update(update).map_err(|e| {
+					log_error!(logger, "Failed to apply checkpoint during wallet setup: {}", e);
+					BuildError::WalletSetupFailed
+				})?;
 			}
 			wallet
 		},
@@ -1514,6 +1589,12 @@ fn build_with_store_internal(
 		},
 	};
 
+	// On Esplora/Electrum the initial wallet-checkpoint logic above cannot honor a specific
+	// rescan height because the backends don't expose a block-hash-by-height lookup. When the
+	// user has explicitly opted into recovery mode we instead force the next on-chain sync to
+	// escalate to a BDK `full_scan` so funds sent to previously-unknown addresses are
+	// re-discovered.
+	let force_full_scan = recovery_mode.is_some();
 	let wallet = Arc::new(Wallet::new(
 		bdk_wallet,
 		wallet_persister,
@@ -1524,6 +1605,7 @@ fn build_with_store_internal(
 		Arc::clone(&config),
 		Arc::clone(&logger),
 		Arc::clone(&pending_payment_store),
+		force_full_scan,
 	));
 
 	// Initialize the KeysManager

src/chain/electrum.rs

@@ -125,9 +125,11 @@ impl ElectrumChainSource {
 			return Err(Error::FeerateEstimationUpdateFailed);
 		};
 		// If this is our first sync, do a full scan with the configured gap limit.
-		// Otherwise just do an incremental sync.
-		let incremental_sync =
+		// Otherwise just do an incremental sync. Also take one-shot priority over an incremental
+		// sync if the user opted into recovery mode via `NodeBuilder::set_wallet_recovery_mode`.
+		let has_prior_sync =
 			self.node_metrics.read().expect("lock").latest_onchain_wallet_sync_timestamp.is_some();
+		let incremental_sync = has_prior_sync && !onchain_wallet.take_force_full_scan();
 
 		let apply_wallet_update =
 			|update_res: Result<BdkUpdate, Error>, now: Instant| match update_res {

src/chain/esplora.rs

@@ -101,9 +101,11 @@ impl EsploraChainSource {
 
 	async fn sync_onchain_wallet_inner(&self, onchain_wallet: Arc<Wallet>) -> Result<(), Error> {
 		// If this is our first sync, do a full scan with the configured gap limit.
-		// Otherwise just do an incremental sync.
-		let incremental_sync =
+		// Otherwise just do an incremental sync. Also take one-shot priority over an incremental
+		// sync if the user opted into recovery mode via `NodeBuilder::set_wallet_recovery_mode`.
+		let has_prior_sync =
 			self.node_metrics.read().expect("lock").latest_onchain_wallet_sync_timestamp.is_some();
+		let incremental_sync = has_prior_sync && !onchain_wallet.take_force_full_scan();
 
 		macro_rules! get_and_apply_wallet_update {
 			($sync_future: expr) => {{

src/lib.rs

@@ -124,9 +124,9 @@ use bitcoin::FeeRate;
 use bitcoin::{Address, Amount};
 #[cfg(feature = "uniffi")]
 pub use builder::ArcedNodeBuilder as Builder;
-pub use builder::BuildError;
 #[cfg(not(feature = "uniffi"))]
 pub use builder::NodeBuilder as Builder;
+pub use builder::{BuildError, RecoveryMode};
 use chain::ChainSource;
 use config::{
 	default_user_config, may_announce_channel, AsyncPaymentsRole, ChannelConfig, Config,

src/wallet/mod.rs

@@ -8,6 +8,7 @@
 use std::future::Future;
 use std::ops::Deref;
 use std::str::FromStr;
+use std::sync::atomic::{AtomicBool, Ordering};
 use std::sync::{Arc, Mutex};
 
 use bdk_chain::spk_client::{FullScanRequest, SyncRequest};
@@ -89,6 +90,11 @@ pub(crate) struct Wallet {
 	config: Arc<Config>,
 	logger: Arc<Logger>,
 	pending_payment_store: Arc<PendingPaymentStore>,
+	// If set, the next on-chain wallet sync will force a BDK `full_scan` even when the node has
+	// synced before. Used on Esplora/Electrum backends to honor a user-requested recovery mode:
+	// those backends don't expose a block-hash-by-height lookup, so the only way to rediscover
+	// funds sent to previously-unknown addresses is to re-run the gap-limit scan once.
+	force_full_scan: AtomicBool,
 }
 
 impl Wallet {
@@ -97,7 +103,7 @@ impl Wallet {
 		wallet_persister: KVStoreWalletPersister, broadcaster: Arc<Broadcaster>,
 		fee_estimator: Arc<OnchainFeeEstimator>, chain_source: Arc<ChainSource>,
 		payment_store: Arc<PaymentStore>, config: Arc<Config>, logger: Arc<Logger>,
-		pending_payment_store: Arc<PendingPaymentStore>,
+		pending_payment_store: Arc<PendingPaymentStore>, force_full_scan: bool,
 	) -> Self {
 		let inner = Mutex::new(wallet);
 		let persister = Mutex::new(wallet_persister);
@@ -111,9 +117,19 @@ impl Wallet {
 			config,
 			logger,
 			pending_payment_store,
+			force_full_scan: AtomicBool::new(force_full_scan),
 		}
 	}
 
+	/// Consume a pending "force a full_scan on the next sync" flag.
+	///
+	/// Returns `true` exactly once if the flag was set at construction time, and `false` on every
+	/// subsequent call. Used by the Esplora/Electrum syncers to decide whether to escalate an
+	/// incremental sync to a full_scan.
+	pub(crate) fn take_force_full_scan(&self) -> bool {
+		self.force_full_scan.swap(false, Ordering::AcqRel)
+	}
+
 	pub(crate) fn get_full_scan_request(&self) -> FullScanRequest<KeychainKind> {
 		self.inner.lock().expect("lock").start_full_scan().build()
 	}

tests/common/mod.rs

@@ -37,7 +37,7 @@ use ldk_node::io::sqlite_store::SqliteStore;
 use ldk_node::payment::{PaymentDirection, PaymentKind, PaymentStatus};
 use ldk_node::{
 	Builder, ChannelShutdownState, CustomTlvRecord, Event, LightningBalance, Node, NodeError,
-	PendingSweepBalance, UserChannelId,
+	PendingSweepBalance, RecoveryMode, UserChannelId,
 };
 use lightning::io;
 use lightning::ln::msgs::SocketAddress;
@@ -349,7 +349,7 @@ pub(crate) struct TestConfig {
 	pub store_type: TestStoreType,
 	pub node_entropy: NodeEntropy,
 	pub async_payments_role: Option<AsyncPaymentsRole>,
-	pub recovery_mode: bool,
+	pub recovery_mode: Option<RecoveryMode>,
 }
 
 impl Default for TestConfig {
@@ -361,7 +361,7 @@ impl Default for TestConfig {
 		let mnemonic = generate_entropy_mnemonic(None);
 		let node_entropy = NodeEntropy::from_bip39_mnemonic(mnemonic, None);
 		let async_payments_role = None;
-		let recovery_mode = false;
+		let recovery_mode = None;
 		TestConfig {
 			node_config,
 			log_writer,
@@ -497,8 +497,8 @@ pub(crate) fn setup_node(chain_source: &TestChainSource, config: TestConfig) ->
 
 	builder.set_async_payments_role(config.async_payments_role).unwrap();
 
-	if config.recovery_mode {
-		builder.set_wallet_recovery_mode();
+	if config.recovery_mode.is_some() {
+		builder.set_wallet_recovery_mode(config.recovery_mode);
 	}
 
 	let node = match config.store_type {
@@ -509,10 +509,6 @@ pub(crate) fn setup_node(chain_source: &TestChainSource, config: TestConfig) ->
 		TestStoreType::Sqlite => builder.build(config.node_entropy.into()).unwrap(),
 	};
 
-	if config.recovery_mode {
-		builder.set_wallet_recovery_mode();
-	}
-
 	node.start().unwrap();
 	assert!(node.status().is_running);
 	assert!(node.status().latest_fee_rate_cache_update_timestamp.is_some());