Add --rescan-from-height CLI argument

Expose the ldk-node wallet-recovery API through a new top-level CLI
flag (also overridable via the `LDK_SERVER_RESCAN_FROM_HEIGHT`
environment variable). When set on a fresh node's first startup, the
value is passed through to
`Builder::set_wallet_recovery_mode(Some(RecoveryMode { rescan_from_height: Some(h) }))`
so the wallet picks up funds sent before the current chain tip.

Bitcoin Core RPC/REST chain sources honor the height precisely by
resolving the block hash at `h` and using it as the wallet birthday.
Esplora/Electrum backends cannot resolve a block hash from a height
via the BDK client APIs, so they ignore the value but still escalate
the next sync to a one-shot `full_scan` to re-discover funds on
previously-unknown addresses.

The `ldk-node` dependency is temporarily pointed at the local
`2026-04-abort-on-first-startup-tip-fetch-failure` worktree since the
`RecoveryMode` API is not yet on ldk-node's upstream main; the
Cargo.toml entry should be restored to a pinned upstream git rev once
that branch merges.

Co-Authored-By: HAL 9000

Author: tnull

Cargo.lock

@@ -4,7 +4,10 @@ version = "0.1.0"
 edition = "2021"
 
 [dependencies]
-ldk-node = { git = "https://github.com/lightningdevkit/ldk-node", rev = "c754e2fe85c70741b5e370334cd16856c615265e" }
+# TODO: the `RecoveryMode` API used below lives on the ldk-node branch
+# `2026-04-abort-on-first-startup-tip-fetch-failure`. Restore this to a pinned upstream git rev
+# once that branch merges.
+ldk-node = { path = "/home/tnull/workspace/worktrees/ldk-node/2026-04-abort-on-first-startup-tip-fetch-failure" }
 serde = { version = "1.0.203", default-features = false, features = ["derive"] }
 hyper = { version = "1", default-features = false, features = ["server", "http2"] }
 http-body-util = { version = "0.1", default-features = false }

ldk-server/Cargo.toml

@@ -28,7 +28,7 @@ use ldk_node::bitcoin::Network;
 use ldk_node::config::Config;
 use ldk_node::entropy::NodeEntropy;
 use ldk_node::lightning::ln::channelmanager::PaymentId;
-use ldk_node::{Builder, Event, Node};
+use ldk_node::{Builder, Event, Node, RecoveryMode};
 use ldk_server_grpc::events;
 use ldk_server_grpc::events::{event_envelope, EventEnvelope};
 use ldk_server_grpc::types::Payment;
@@ -194,6 +194,17 @@ fn main() {
 		config_file.lsps2_service_config.expect("Missing liquidity.lsps2_server config"),
 	);
 
+	if let Some(rescan_from_height) = args_config.rescan_from_height {
+		info!(
+			"Wallet recovery mode requested via --rescan-from-height {}; the setting only \
+			 takes effect if this is the node's first startup.",
+			rescan_from_height
+		);
+		builder.set_wallet_recovery_mode(Some(RecoveryMode {
+			rescan_from_height: Some(rescan_from_height),
+		}));
+	}
+
 	let runtime = match tokio::runtime::Builder::new_multi_thread().enable_all().build() {
 		Ok(runtime) => Arc::new(runtime),
 		Err(e) => {

ldk-server/src/main.rs

@@ -702,6 +702,13 @@ pub struct ArgsConfig {
 		help = "Tor daemon SOCKS proxy address. Only connections to OnionV3 peers will be made via this proxy; other connections (IPv4 peers, Electrum server) will not be routed over Tor."
 	)]
 	tor_proxy_address: Option<String>,
+
+	#[arg(
+		long,
+		env = "LDK_SERVER_RESCAN_FROM_HEIGHT",
+		help = "Triggers wallet recovery on the next startup. On Bitcoin Core RPC/REST chain sources, the given block height is used as the wallet birthday so the chain is rescanned from that height (useful on pruned nodes when the wallet's birthday is known). On Esplora/Electrum chain sources the given height is ignored, but setting the flag still forces a one-shot BDK `full_scan` so funds sent to previously-unknown addresses are re-discovered. Only takes effect on first startup (i.e. for a freshly-persisted wallet)."
+	)]
+	pub rescan_from_height: Option<u32>,
 }
 
 pub fn load_config(args: &ArgsConfig) -> io::Result<Config> {