Add wallet birthday height for seed recovery on pruned nodes

When set_wallet_birthday_height(height) is called, the BDK wallet
checkpoint is set to the birthday block instead of the current chain
tip. This allows the wallet to sync from the birthday forward,
recovering historical UTXOs without scanning from genesis.

This is critical for pruned nodes where blocks before the birthday
are unavailable, making recovery_mode (which scans from genesis)
unusable.

Three-way logic:
- Birthday set: checkpoint at birthday block
- No birthday, no recovery mode: checkpoint at current tip (existing)
- Recovery mode without birthday: sync from genesis (existing)

Falls back to current tip if the birthday block hash cannot be
fetched.

Resolves the TODO: 'Use a proper wallet birthday once BDK supports it.'
Closes #818

Author: FreeOnlineUser

src/builder.rs

@@ -69,7 +69,7 @@ use crate::liquidity::{
 	LSPS1ClientConfig, LSPS2ClientConfig, LSPS2ServiceConfig, LiquiditySourceBuilder,
 };
 use crate::lnurl_auth::LnurlAuth;
-use crate::logger::{log_error, LdkLogger, LogLevel, LogWriter, Logger};
+use crate::logger::{log_error, log_info, LdkLogger, LogLevel, LogWriter, Logger};
 use crate::message_handler::NodeCustomMessageHandler;
 use crate::payment::asynchronous::om_mailbox::OnionMessageMailbox;
 use crate::peer_store::PeerStore;
@@ -250,6 +250,7 @@ pub struct NodeBuilder {
 	runtime_handle: Option<tokio::runtime::Handle>,
 	pathfinding_scores_sync_config: Option<PathfindingScoresSyncConfig>,
 	recovery_mode: bool,
+	wallet_birthday_height: Option<u32>,
 }
 
 impl NodeBuilder {
@@ -268,6 +269,7 @@ impl NodeBuilder {
 		let runtime_handle = None;
 		let pathfinding_scores_sync_config = None;
 		let recovery_mode = false;
+		let wallet_birthday_height = None;
 		Self {
 			config,
 			chain_data_source_config,
@@ -278,6 +280,7 @@ impl NodeBuilder {
 			async_payments_role: None,
 			pathfinding_scores_sync_config,
 			recovery_mode,
+			wallet_birthday_height,
 		}
 	}
 
@@ -579,6 +582,22 @@ impl NodeBuilder {
 		self
 	}
 
+	/// Sets the wallet birthday height for seed recovery on pruned nodes.
+	///
+	/// When set, the on-chain wallet will start scanning from the given block height
+	/// instead of the current chain tip. This allows recovery of historical funds
+	/// without scanning from genesis, which is critical for pruned nodes where
+	/// early blocks are unavailable.
+	///
+	/// The birthday height should be set to a block height at or before the wallet's
+	/// first transaction. If unknown, use a conservative estimate.
+	///
+	/// This only takes effect when creating a new wallet (not when loading existing state).
+	pub fn set_wallet_birthday_height(&mut self, height: u32) -> &mut Self {
+		self.wallet_birthday_height = Some(height);
+		self
+	}
+
 	/// Builds a [`Node`] instance with a [`SqliteStore`] backend and according to the options
 	/// previously configured.
 	pub fn build(&self, node_entropy: NodeEntropy) -> Result<Node, BuildError> {
@@ -752,6 +771,7 @@ impl NodeBuilder {
 			self.pathfinding_scores_sync_config.as_ref(),
 			self.async_payments_role,
 			self.recovery_mode,
+			self.wallet_birthday_height,
 			seed_bytes,
 			runtime,
 			logger,
@@ -1010,6 +1030,13 @@ impl ArcedNodeBuilder {
 		self.inner.write().unwrap().set_wallet_recovery_mode();
 	}
 
+	/// Sets the wallet birthday height for seed recovery on pruned nodes.
+	///
+	/// See [`NodeBuilder::set_wallet_birthday_height`] for details.
+	pub fn set_wallet_birthday_height(&self, height: u32) {
+		self.inner.write().unwrap().set_wallet_birthday_height(height);
+	}
+
 	/// Builds a [`Node`] instance with a [`SqliteStore`] backend and according to the options
 	/// previously configured.
 	pub fn build(&self, node_entropy: Arc<NodeEntropy>) -> Result<Arc<Node>, BuildError> {
@@ -1153,7 +1180,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],
+	async_payments_role: Option<AsyncPaymentsRole>, recovery_mode: bool,
+	wallet_birthday_height: Option<u32>, seed_bytes: [u8; 64],
 	runtime: Arc<Runtime>, logger: Arc<Logger>, kv_store: Arc<DynStore>,
 ) -> Result<Node, BuildError> {
 	optionally_install_rustls_cryptoprovider();
@@ -1359,10 +1387,65 @@ fn build_with_store_internal(
 					BuildError::WalletSetupFailed
 				})?;
 
-			if !recovery_mode {
+			if let Some(birthday_height) = wallet_birthday_height {
+				// Wallet birthday: checkpoint at the birthday block so the wallet
+				// syncs from there, allowing fund recovery on pruned nodes.
+				let birthday_hash_res = runtime.block_on(async {
+					chain_source.get_block_hash_by_height(birthday_height).await
+				});
+				match birthday_hash_res {
+					Ok(birthday_hash) => {
+						log_info!(
+							logger,
+							"Setting wallet checkpoint at birthday height {} ({})",
+							birthday_height,
+							birthday_hash
+						);
+						let mut latest_checkpoint = wallet.latest_checkpoint();
+						let block_id = bdk_chain::BlockId {
+							height: birthday_height,
+							hash: birthday_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 birthday checkpoint: {}", e);
+							BuildError::WalletSetupFailed
+						})?;
+					},
+					Err(e) => {
+						log_error!(
+							logger,
+							"Failed to fetch block hash at birthday height {}: {:?}. \
+							 Falling back to current tip.",
+							birthday_height,
+							e
+						);
+						// Fall back to current tip
+						if let Some(best_block) = chain_tip_opt {
+							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 fallback checkpoint: {}", e);
+								BuildError::WalletSetupFailed
+							})?;
+						}
+					},
+				}
+			} else 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.
+					// No birthday: insert current tip to avoid resyncing from genesis.
 					let mut latest_checkpoint = wallet.latest_checkpoint();
 					let block_id = bdk_chain::BlockId {
 						height: best_block.height,
@@ -1377,6 +1460,7 @@ fn build_with_store_internal(
 					})?;
 				}
 			}
+			// else: recovery_mode without birthday syncs from genesis
 			wallet
 		},
 	};

src/chain/mod.rs

@@ -17,6 +17,7 @@ use bitcoin::{Script, Txid};
 use lightning::chain::{BestBlock, Filter};
 
 use crate::chain::bitcoind::{BitcoindChainSource, UtxoSourceClient};
+use lightning_block_sync::gossip::UtxoSource;
 use crate::chain::electrum::ElectrumChainSource;
 use crate::chain::esplora::EsploraChainSource;
 use crate::config::{
@@ -214,6 +215,19 @@ impl ChainSource {
 		}
 	}
 
+	/// Fetches the block hash at the given height from the chain source.
+	pub(crate) async fn get_block_hash_by_height(
+		&self, height: u32,
+	) -> Result<bitcoin::BlockHash, ()> {
+		match &self.kind {
+			ChainSourceKind::Bitcoind(bitcoind_chain_source) => {
+				let utxo_source = bitcoind_chain_source.as_utxo_source();
+				utxo_source.get_block_hash_by_height(height).await.map_err(|_| ())
+			},
+			_ => Err(()),
+		}
+	}
+
 	pub(crate) fn registered_txids(&self) -> Vec<Txid> {
 		self.registered_txids.lock().unwrap().clone()
 	}