Add wallet birthday height for seed recovery on pruned nodes

bindings/ldk_node.udl

@@ -61,6 +61,7 @@ interface Builder {
 	[Throws=BuildError]
 	void set_async_payments_role(AsyncPaymentsRole? role);
 	void set_wallet_recovery_mode();
+	void set_wallet_birthday_height(u32 height);
 	[Throws=BuildError]
 	Node build(NodeEntropy node_entropy);
 	[Throws=BuildError]
@@ -194,6 +195,7 @@ enum NodeError {
 	"OnchainTxSigningFailed",
 	"TxSyncFailed",
 	"TxSyncTimeout",
+	"ChainAccessFailed",
 	"GossipUpdateFailed",
 	"GossipUpdateTimeout",
 	"LiquidityRequestFailed",

src/builder.rs

@@ -72,7 +72,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;
@@ -292,6 +292,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 {
@@ -310,6 +311,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,
@@ -320,6 +322,7 @@ impl NodeBuilder {
 			async_payments_role: None,
 			pathfinding_scores_sync_config,
 			recovery_mode,
+			wallet_birthday_height,
 		}
 	}
 
@@ -625,6 +628,27 @@ 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).
+	///
+	/// If [`set_wallet_recovery_mode`] is also set, the birthday height takes precedence and
+	/// the wallet is checkpointed at the birthday block.
+	///
+	/// [`set_wallet_recovery_mode`]: Self::set_wallet_recovery_mode
+	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> {
@@ -865,6 +889,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,
@@ -1163,6 +1188,13 @@ impl ArcedNodeBuilder {
 		self.inner.write().expect("lock").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> {
@@ -1358,8 +1390,9 @@ 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: 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();
 
@@ -1576,10 +1609,50 @@ 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) => {
+						// A birthday was explicitly set but we couldn't fetch the block hash
+						// for it. Silently checkpointing at the chain tip would defeat the
+						// feature: the wallet would scan from tip and recover nothing, leaving
+						// the user to assume their seed is wrong. Fail loudly instead.
+						log_error!(
+							logger,
+							"Failed to fetch block hash at birthday height {}: {}",
+							birthday_height,
+							e
+						);
+						return Err(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,
@@ -1594,6 +1667,7 @@ fn build_with_store_internal(
 					})?;
 				}
 			}
+			// else: recovery_mode without birthday syncs from genesis
 			wallet
 		},
 	};

src/chain/electrum.rs

@@ -89,6 +89,30 @@ impl ElectrumChainSource {
 		self.electrum_runtime_status.write().expect("lock").stop();
 	}
 
+	pub(super) async fn get_block_hash_by_height(
+		&self, height: u32,
+	) -> Result<bitcoin::BlockHash, ()> {
+		// Try the runtime client if started, otherwise create a temporary connection.
+		let status = self.electrum_runtime_status.read().unwrap();
+		if let Some(client) = status.client() {
+			drop(status);
+			return client.get_block_hash_by_height(height);
+		}
+		drop(status);
+
+		// Runtime not started yet (called during build). Use a temporary client.
+		let config = ElectrumConfigBuilder::new()
+			.timeout(Some(Duration::from_secs(
+				self.sync_config.timeouts_config.per_request_timeout_secs as u64,
+			)))
+			.build();
+		let client = ElectrumClient::from_config(&self.server_url, config).map_err(|_| ())?;
+		let header_bytes = client.block_header_raw(height as usize).map_err(|_| ())?;
+		let header: bitcoin::block::Header =
+			bitcoin::consensus::deserialize(&header_bytes).map_err(|_| ())?;
+		Ok(header.block_hash())
+	}
+
 	pub(crate) async fn sync_onchain_wallet(
 		&self, onchain_wallet: Arc<Wallet>,
 	) -> Result<(), Error> {
@@ -423,6 +447,14 @@ impl ElectrumRuntimeClient {
 		})
 	}
 
+	fn get_block_hash_by_height(&self, height: u32) -> Result<bitcoin::BlockHash, ()> {
+		let header_bytes =
+			self.electrum_client.block_header_raw(height as usize).map_err(|_| ())?;
+		let header: bitcoin::block::Header =
+			bitcoin::consensus::deserialize(&header_bytes).map_err(|_| ())?;
+		Ok(header.block_hash())
+	}
+
 	async fn sync_confirmables(
 		&self, confirmables: Vec<Arc<dyn Confirm + Sync + Send>>,
 	) -> Result<(), Error> {

src/chain/esplora.rs

@@ -76,6 +76,12 @@ impl EsploraChainSource {
 		})
 	}
 
+	pub(super) async fn get_block_hash_by_height(
+		&self, height: u32,
+	) -> Result<bitcoin::BlockHash, ()> {
+		self.esplora_client.get_block_hash(height).await.map_err(|_| ())
+	}
+
 	pub(super) async fn sync_onchain_wallet(
 		&self, onchain_wallet: Arc<Wallet>,
 	) -> Result<(), Error> {

src/chain/mod.rs

@@ -15,6 +15,7 @@ use std::time::Duration;
 
 use bitcoin::{Script, Txid};
 use lightning::chain::{BlockLocator, Filter};
+use lightning_block_sync::gossip::UtxoSource;
 
 use crate::chain::bitcoind::{BitcoindChainSource, UtxoSourceClient};
 use crate::chain::electrum::ElectrumChainSource;
@@ -214,6 +215,29 @@ 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, Error> {
+		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(|_| Error::ChainAccessFailed)
+			},
+			ChainSourceKind::Esplora(esplora_chain_source) => esplora_chain_source
+				.get_block_hash_by_height(height)
+				.await
+				.map_err(|_| Error::ChainAccessFailed),
+			ChainSourceKind::Electrum(electrum_chain_source) => electrum_chain_source
+				.get_block_hash_by_height(height)
+				.await
+				.map_err(|_| Error::ChainAccessFailed),
+		}
+	}
+
 	pub(crate) fn registered_txids(&self) -> Vec<Txid> {
 		self.registered_txids.lock().expect("lock").clone()
 	}

src/error.rs

@@ -63,6 +63,8 @@ pub enum Error {
 	TxSyncFailed,
 	/// A transaction sync operation timed out.
 	TxSyncTimeout,
+	/// Accessing the chain source to look up a block failed.
+	ChainAccessFailed,
 	/// A gossip updating operation failed.
 	GossipUpdateFailed,
 	/// A gossip updating operation timed out.
@@ -171,6 +173,7 @@ impl fmt::Display for Error {
 			Self::OnchainTxSigningFailed => write!(f, "Failed to sign given transaction."),
 			Self::TxSyncFailed => write!(f, "Failed to sync transactions."),
 			Self::TxSyncTimeout => write!(f, "Syncing transactions timed out."),
+			Self::ChainAccessFailed => write!(f, "Failed to access the chain source."),
 			Self::GossipUpdateFailed => write!(f, "Failed to update gossip data."),
 			Self::GossipUpdateTimeout => write!(f, "Updating gossip data timed out."),
 			Self::LiquidityRequestFailed => write!(f, "Failed to request inbound liquidity."),

tests/common/mod.rs

@@ -433,6 +433,7 @@ pub(crate) struct TestConfig {
 	pub node_entropy: NodeEntropy,
 	pub async_payments_role: Option<AsyncPaymentsRole>,
 	pub recovery_mode: bool,
+	pub wallet_birthday_height: Option<u32>,
 }
 
 impl Default for TestConfig {
@@ -445,13 +446,15 @@ impl Default for TestConfig {
 		let node_entropy = NodeEntropy::from_bip39_mnemonic(mnemonic, None);
 		let async_payments_role = None;
 		let recovery_mode = false;
+		let wallet_birthday_height = None;
 		TestConfig {
 			node_config,
 			log_writer,
 			store_type,
 			node_entropy,
 			async_payments_role,
 			recovery_mode,
+			wallet_birthday_height,
 		}
 	}
 }
@@ -587,6 +590,10 @@ pub(crate) fn setup_node(chain_source: &TestChainSource, config: TestConfig) ->
 		builder.set_wallet_recovery_mode();
 	}
 
+	if let Some(birthday_height) = config.wallet_birthday_height {
+		builder.set_wallet_birthday_height(birthday_height);
+	}
+
 	let node = match config.store_type {
 		TestStoreType::TestSyncStore => {
 			let kv_store = TestSyncStore::new(config.node_config.storage_dir_path.into());

tests/integration_tests_rust.rs

@@ -743,6 +743,48 @@ async fn onchain_wallet_recovery() {
 	);
 }
 
+#[tokio::test(flavor = "multi_thread", worker_threads = 1)]
+async fn onchain_wallet_recovery_with_birthday() {
+	let (bitcoind, electrsd) = setup_bitcoind_and_electrsd();
+
+	let chain_source = random_chain_source(&bitcoind, &electrsd);
+
+	let original_config = random_config(true);
+	let original_node_entropy = original_config.node_entropy;
+	let original_node = setup_node(&chain_source, original_config);
+
+	let premine_amount_sat = 100_000;
+
+	// Record the tip before funding. The restored node uses this as its wallet
+	// birthday, so the deposit lands in a block above the birthday checkpoint.
+	let birthday_height = bitcoind.client.get_blockchain_info().unwrap().blocks as u32;
+
+	let addr = original_node.onchain_payment().new_address().unwrap();
+	premine_and_distribute_funds(
+		&bitcoind.client,
+		&electrsd.client,
+		vec![addr],
+		Amount::from_sat(premine_amount_sat),
+	)
+	.await;
+	original_node.sync_wallets().unwrap();
+	assert_eq!(original_node.list_balances().spendable_onchain_balance_sats, premine_amount_sat);
+
+	original_node.stop().unwrap();
+	drop(original_node);
+
+	// Restore from the same seed using a wallet birthday instead of recovery
+	// mode: the wallet checkpoints at the birthday block and syncs forward,
+	// recovering the funds without scanning from genesis.
+	let mut recovered_config = random_config(true);
+	recovered_config.node_entropy = original_node_entropy;
+	recovered_config.wallet_birthday_height = Some(birthday_height);
+	let recovered_node = setup_node(&chain_source, recovered_config);
+
+	recovered_node.sync_wallets().unwrap();
+	assert_eq!(recovered_node.list_balances().spendable_onchain_balance_sats, premine_amount_sat);
+}
+
 #[tokio::test(flavor = "multi_thread", worker_threads = 1)]
 async fn test_rbf_via_mempool() {
 	run_rbf_test(false).await;