Abort on first-startup chain tip fetch failure

When a fresh node's bitcoind RPC/REST chain source fails to return the
current chain tip, we previously silently fell back to the genesis
block as the wallet birthday. The next successful startup would then
force a full-history rescan of the whole chain. Instead, return a new
BuildError::ChainTipFetchFailed on the first build so the
misconfiguration surfaces immediately and no stale fresh state is
persisted.

Restarts with a previously-persisted wallet are unaffected: a
transient chain source outage on an existing node still allows startup
to proceed. Esplora/Electrum backends currently never expose a tip at
build time so the guard only fires for bitcoind sources; the latent
wallet-birthday-at-genesis issue on those backends is left for a
follow-up.

Co-Authored-By: HAL 9000

Author: tnull

CHANGELOG.md

@@ -6,6 +6,12 @@
 - Users of the VSS storage backend must upgrade their VSS server to at least version
   `v0.1.0-alpha.0` before upgrading LDK Node.
 
+## 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. (#884)
+
 # 0.7.0 - Dec. 3, 2025
 This seventh minor release introduces numerous new features, bug fixes, and API improvements. In particular, it adds support for channel Splicing, Async Payments, as well as sourcing chain data from a Bitcoin Core REST backend.
 

src/builder.rs

@@ -196,6 +196,13 @@ pub enum BuildError {
 	AsyncPaymentsConfigMismatch,
 	/// An attempt to setup a DNS Resolver failed.
 	DNSResolverSetupFailed,
+	/// We failed to determine the current chain tip on first startup.
+	///
+	/// Returned when a fresh node is built against a Bitcoin Core RPC or REST chain source that
+	/// is unreachable or misconfigured, so we cannot learn the tip height/hash to use as the
+	/// wallet birthday. Falling back to genesis would silently force a full-history rescan on
+	/// the next successful startup, so we abort instead.
+	ChainTipFetchFailed,
 }
 
 impl fmt::Display for BuildError {
@@ -233,6 +240,12 @@ impl fmt::Display for BuildError {
 			Self::DNSResolverSetupFailed => {
 				write!(f, "An attempt to setup a DNS resolver has failed.")
 			},
+			Self::ChainTipFetchFailed => {
+				write!(
+					f,
+					"Failed to determine the current chain tip on first startup. Verify the chain data source is reachable and correctly configured."
+				)
+			},
 		}
 	}
 }
@@ -1557,6 +1570,23 @@ fn build_with_store_internal(
 	let bdk_wallet = match wallet_opt {
 		Some(wallet) => wallet,
 		None => {
+			// Guard against silently setting the wallet birthday to genesis on a fresh node:
+			// if we are creating a new wallet but failed to learn the current chain tip from
+			// a Bitcoin Core RPC/REST backend, we'd otherwise persist fresh wallet state
+			// pinned at height 0 and force a full-history rescan once the backend comes back.
+			// Abort cleanly instead so the misconfiguration surfaces on the first startup.
+			// Esplora/Electrum backends currently never return a tip at build time, so they
+			// 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 {
+				log_error!(
+					logger,
+					"Failed to determine chain tip on first startup. Aborting to avoid pinning the wallet birthday to genesis."
+				);
+				return Err(BuildError::ChainTipFetchFailed);
+			}
+
 			let mut wallet = runtime
 				.block_on(async {
 					BdkWallet::create(descriptor, change_descriptor)

tests/integration_tests_rust.rs

@@ -36,7 +36,7 @@ use ldk_node::payment::{
 	ConfirmationStatus, PaymentDetails, PaymentDirection, PaymentKind, PaymentStatus,
 	TransactionType, UnifiedPaymentResult,
 };
-use ldk_node::{Builder, Event, Node, NodeError};
+use ldk_node::{BuildError, Builder, Event, Node, NodeError};
 use lightning::ln::channelmanager::PaymentId;
 use lightning::routing::gossip::{NodeAlias, NodeId};
 use lightning::routing::router::RouteParametersConfig;
@@ -936,6 +936,36 @@ async fn onchain_wallet_recovery() {
 	);
 }
 
+#[tokio::test(flavor = "multi_thread", worker_threads = 1)]
+async fn build_aborts_on_first_startup_bitcoind_tip_fetch_failure() {
+	// A fresh node pointed at an unreachable bitcoind RPC endpoint must not silently
+	// fall back to genesis as the wallet birthday. The build must abort cleanly so the
+	// misconfiguration surfaces immediately.
+	let config = random_config(false);
+	let entropy = config.node_entropy;
+
+	setup_builder!(builder, config.node_config);
+	// Pick a localhost port that is extremely unlikely to be bound. The kernel will
+	// refuse the connection immediately so the test does not have to wait for the
+	// chain-polling timeout.
+	let unreachable_port: u16 = 1;
+	builder.set_chain_source_bitcoind_rpc(
+		"127.0.0.1".to_string(),
+		unreachable_port,
+		"user".to_string(),
+		"password".to_string(),
+	);
+
+	let res = builder.build(entropy.into());
+	match res {
+		Err(BuildError::ChainTipFetchFailed) => {},
+		other => panic!(
+			"expected BuildError::ChainTipFetchFailed on fresh node with unreachable bitcoind, got {:?}",
+			other.map(|_| "Ok(_)")
+		),
+	}
+}
+
 #[tokio::test(flavor = "multi_thread", worker_threads = 1)]
 async fn test_rbf_via_mempool() {
 	run_rbf_test(false).await;