Allow wallet imports from arbitrary heights, forcing full scans by tnull · Pull Request #884 · lightningdevkit/ldk-node

tnull · 2026-04-21T13:06:36Z

Fixes#818.

Previously, we would always start syncing from the latest block height or were able to force a full-resync from genesis via recovery_mode = true. Here we add more fine-grained control and allow an initial wallet import from a known birthday height for bitcoind RPC/REST chain sources. Relatedly, we also fix a minor bug where, if we failed to retrieve the tip hash on first startup, we'd always resync from genesis, which can be very costly.

Moreover, we also add a flag that allows the user to force a full scan for Esplora/Electrum wallets.

ldk-reviews-bot · 2026-04-21T13:06:40Z

I've assigned @wpaulino as a reviewer!
I'll wait for their review and will help manage the review process.
Once they submit their review, I'll check if a second reviewer would be helpful.

tnull · 2026-06-26T12:30:20Z

Rebased & refactored a bit, ready for review.

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

Allow Bitcoin Core RPC and REST chain-source configuration to specify the wallet birthday height used when creating a fresh wallet. This lets restored wallets rescan from a known height, including genesis, without overloading a global recovery toggle. Reject requested heights above the current chain tip with an explicit build error before wallet state is created. Existing wallets are not rewound by this option because a safe rewind must invalidate persisted wallet and LDK state before replaying blocks. Co-Authored-By: HAL 9000

Let Esplora and Electrum sync configs request BDK full scans until one succeeds. This keeps recovery scans retryable after transient sync failures while preserving normal incremental syncs once recovery has completed. Co-Authored-By: HAL 9000

tnull · 2026-06-29T14:19:58Z

Rebased to resolve minor conflict.

wpaulino

LGTM, just one comment

wpaulino · 2026-06-29T16:51:53Z

 	config: Arc<Config>,
 	logger: Arc<Logger>,
 	node_metrics: Arc<PersistedNodeMetrics>,
+	force_wallet_full_scan: AtomicBool,


Should we expose a block height as well to let the user optionally decide whether they want to start from a specific point?

You mean the current block height the node is synced to? That's already exposed via NodeStatus::current_best_block (cf. https://docs.rs/ldk-node/latest/ldk_node/struct.NodeStatus.html).

tnull · 2026-04-21T13:06:36Z

Fixes#818.

Previously, we would always start syncing from the latest block height or were able to force a full-resync from genesis via recovery_mode = true. Here we add more fine-grained control and allow an initial wallet import from a known birthday height for bitcoind RPC/REST chain sources. Relatedly, we also fix a minor bug where, if we failed to retrieve the tip hash on first startup, we'd always resync from genesis, which can be very costly.

Moreover, we also add a flag that allows the user to force a full scan for Esplora/Electrum wallets.

ldk-reviews-bot · 2026-04-21T13:06:40Z

I've assigned @wpaulino as a reviewer!
I'll wait for their review and will help manage the review process.
Once they submit their review, I'll check if a second reviewer would be helpful.

tnull · 2026-06-26T12:30:20Z

Rebased & refactored a bit, ready for review.

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

Allow Bitcoin Core RPC and REST chain-source configuration to specify the wallet birthday height used when creating a fresh wallet. This lets restored wallets rescan from a known height, including genesis, without overloading a global recovery toggle. Reject requested heights above the current chain tip with an explicit build error before wallet state is created. Existing wallets are not rewound by this option because a safe rewind must invalidate persisted wallet and LDK state before replaying blocks. Co-Authored-By: HAL 9000

Let Esplora and Electrum sync configs request BDK full scans until one succeeds. This keeps recovery scans retryable after transient sync failures while preserving normal incremental syncs once recovery has completed. Co-Authored-By: HAL 9000

tnull · 2026-06-29T14:19:58Z

Rebased to resolve minor conflict.

wpaulino

LGTM, just one comment

wpaulino · 2026-06-29T16:51:53Z

 	config: Arc<Config>,
 	logger: Arc<Logger>,
 	node_metrics: Arc<PersistedNodeMetrics>,
+	force_wallet_full_scan: AtomicBool,


Should we expose a block height as well to let the user optionally decide whether they want to start from a specific point?

You mean the current block height the node is synced to? That's already exposed via NodeStatus::current_best_block (cf. https://docs.rs/ldk-node/latest/ldk_node/struct.NodeStatus.html).

tnull · 2026-04-21T13:06:36Z

Fixes#818.

Previously, we would always start syncing from the latest block height or were able to force a full-resync from genesis via recovery_mode = true. Here we add more fine-grained control and allow an initial wallet import from a known birthday height for bitcoind RPC/REST chain sources. Relatedly, we also fix a minor bug where, if we failed to retrieve the tip hash on first startup, we'd always resync from genesis, which can be very costly.

Moreover, we also add a flag that allows the user to force a full scan for Esplora/Electrum wallets.

ldk-reviews-bot · 2026-04-21T13:06:40Z

I've assigned @wpaulino as a reviewer!
I'll wait for their review and will help manage the review process.
Once they submit their review, I'll check if a second reviewer would be helpful.

tnull · 2026-06-26T12:30:20Z

Rebased & refactored a bit, ready for review.

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

Allow Bitcoin Core RPC and REST chain-source configuration to specify the wallet birthday height used when creating a fresh wallet. This lets restored wallets rescan from a known height, including genesis, without overloading a global recovery toggle. Reject requested heights above the current chain tip with an explicit build error before wallet state is created. Existing wallets are not rewound by this option because a safe rewind must invalidate persisted wallet and LDK state before replaying blocks. Co-Authored-By: HAL 9000

Let Esplora and Electrum sync configs request BDK full scans until one succeeds. This keeps recovery scans retryable after transient sync failures while preserving normal incremental syncs once recovery has completed. Co-Authored-By: HAL 9000

tnull · 2026-06-29T14:19:58Z

Rebased to resolve minor conflict.

wpaulino

LGTM, just one comment

wpaulino · 2026-06-29T16:51:53Z

 	config: Arc<Config>,
 	logger: Arc<Logger>,
 	node_metrics: Arc<PersistedNodeMetrics>,
+	force_wallet_full_scan: AtomicBool,


Should we expose a block height as well to let the user optionally decide whether they want to start from a specific point?

You mean the current block height the node is synced to? That's already exposed via NodeStatus::current_best_block (cf. https://docs.rs/ldk-node/latest/ldk_node/struct.NodeStatus.html).

tnull · 2026-04-21T13:06:36Z

Fixes#818.

Previously, we would always start syncing from the latest block height or were able to force a full-resync from genesis via recovery_mode = true. Here we add more fine-grained control and allow an initial wallet import from a known birthday height for bitcoind RPC/REST chain sources. Relatedly, we also fix a minor bug where, if we failed to retrieve the tip hash on first startup, we'd always resync from genesis, which can be very costly.

Moreover, we also add a flag that allows the user to force a full scan for Esplora/Electrum wallets.

ldk-reviews-bot · 2026-04-21T13:06:40Z

I've assigned @wpaulino as a reviewer!
I'll wait for their review and will help manage the review process.
Once they submit their review, I'll check if a second reviewer would be helpful.

tnull · 2026-06-26T12:30:20Z

Rebased & refactored a bit, ready for review.

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

Allow Bitcoin Core RPC and REST chain-source configuration to specify the wallet birthday height used when creating a fresh wallet. This lets restored wallets rescan from a known height, including genesis, without overloading a global recovery toggle. Reject requested heights above the current chain tip with an explicit build error before wallet state is created. Existing wallets are not rewound by this option because a safe rewind must invalidate persisted wallet and LDK state before replaying blocks. Co-Authored-By: HAL 9000

Let Esplora and Electrum sync configs request BDK full scans until one succeeds. This keeps recovery scans retryable after transient sync failures while preserving normal incremental syncs once recovery has completed. Co-Authored-By: HAL 9000

tnull · 2026-06-29T14:19:58Z

Rebased to resolve minor conflict.

wpaulino

LGTM, just one comment

wpaulino · 2026-06-29T16:51:53Z

 	config: Arc<Config>,
 	logger: Arc<Logger>,
 	node_metrics: Arc<PersistedNodeMetrics>,
+	force_wallet_full_scan: AtomicBool,


Should we expose a block height as well to let the user optionally decide whether they want to start from a specific point?

You mean the current block height the node is synced to? That's already exposed via NodeStatus::current_best_block (cf. https://docs.rs/ldk-node/latest/ldk_node/struct.NodeStatus.html).

tnull · 2026-04-21T13:06:36Z

Fixes#818.

Previously, we would always start syncing from the latest block height or were able to force a full-resync from genesis via recovery_mode = true. Here we add more fine-grained control and allow an initial wallet import from a known birthday height for bitcoind RPC/REST chain sources. Relatedly, we also fix a minor bug where, if we failed to retrieve the tip hash on first startup, we'd always resync from genesis, which can be very costly.

Moreover, we also add a flag that allows the user to force a full scan for Esplora/Electrum wallets.

ldk-reviews-bot · 2026-04-21T13:06:40Z

I've assigned @wpaulino as a reviewer!
I'll wait for their review and will help manage the review process.
Once they submit their review, I'll check if a second reviewer would be helpful.

tnull · 2026-06-26T12:30:20Z

Rebased & refactored a bit, ready for review.

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

Allow Bitcoin Core RPC and REST chain-source configuration to specify the wallet birthday height used when creating a fresh wallet. This lets restored wallets rescan from a known height, including genesis, without overloading a global recovery toggle. Reject requested heights above the current chain tip with an explicit build error before wallet state is created. Existing wallets are not rewound by this option because a safe rewind must invalidate persisted wallet and LDK state before replaying blocks. Co-Authored-By: HAL 9000

Let Esplora and Electrum sync configs request BDK full scans until one succeeds. This keeps recovery scans retryable after transient sync failures while preserving normal incremental syncs once recovery has completed. Co-Authored-By: HAL 9000

tnull · 2026-06-29T14:19:58Z

Rebased to resolve minor conflict.

wpaulino

LGTM, just one comment

wpaulino · 2026-06-29T16:51:53Z

 	config: Arc<Config>,
 	logger: Arc<Logger>,
 	node_metrics: Arc<PersistedNodeMetrics>,
+	force_wallet_full_scan: AtomicBool,


Should we expose a block height as well to let the user optionally decide whether they want to start from a specific point?

You mean the current block height the node is synced to? That's already exposed via NodeStatus::current_best_block (cf. https://docs.rs/ldk-node/latest/ldk_node/struct.NodeStatus.html).

tnull · 2026-04-21T13:06:36Z

Fixes#818.

Previously, we would always start syncing from the latest block height or were able to force a full-resync from genesis via recovery_mode = true. Here we add more fine-grained control and allow an initial wallet import from a known birthday height for bitcoind RPC/REST chain sources. Relatedly, we also fix a minor bug where, if we failed to retrieve the tip hash on first startup, we'd always resync from genesis, which can be very costly.

Moreover, we also add a flag that allows the user to force a full scan for Esplora/Electrum wallets.

ldk-reviews-bot · 2026-04-21T13:06:40Z

I've assigned @wpaulino as a reviewer!
I'll wait for their review and will help manage the review process.
Once they submit their review, I'll check if a second reviewer would be helpful.

tnull · 2026-06-26T12:30:20Z

Rebased & refactored a bit, ready for review.

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

Allow Bitcoin Core RPC and REST chain-source configuration to specify the wallet birthday height used when creating a fresh wallet. This lets restored wallets rescan from a known height, including genesis, without overloading a global recovery toggle. Reject requested heights above the current chain tip with an explicit build error before wallet state is created. Existing wallets are not rewound by this option because a safe rewind must invalidate persisted wallet and LDK state before replaying blocks. Co-Authored-By: HAL 9000

Let Esplora and Electrum sync configs request BDK full scans until one succeeds. This keeps recovery scans retryable after transient sync failures while preserving normal incremental syncs once recovery has completed. Co-Authored-By: HAL 9000

tnull · 2026-06-29T14:19:58Z

Rebased to resolve minor conflict.

wpaulino

LGTM, just one comment

wpaulino · 2026-06-29T16:51:53Z

 	config: Arc<Config>,
 	logger: Arc<Logger>,
 	node_metrics: Arc<PersistedNodeMetrics>,
+	force_wallet_full_scan: AtomicBool,


Should we expose a block height as well to let the user optionally decide whether they want to start from a specific point?

You mean the current block height the node is synced to? That's already exposed via NodeStatus::current_best_block (cf. https://docs.rs/ldk-node/latest/ldk_node/struct.NodeStatus.html).

tnull · 2026-04-21T13:06:36Z

Fixes#818.

Previously, we would always start syncing from the latest block height or were able to force a full-resync from genesis via recovery_mode = true. Here we add more fine-grained control and allow an initial wallet import from a known birthday height for bitcoind RPC/REST chain sources. Relatedly, we also fix a minor bug where, if we failed to retrieve the tip hash on first startup, we'd always resync from genesis, which can be very costly.

Moreover, we also add a flag that allows the user to force a full scan for Esplora/Electrum wallets.

ldk-reviews-bot · 2026-04-21T13:06:40Z

I've assigned @wpaulino as a reviewer!
I'll wait for their review and will help manage the review process.
Once they submit their review, I'll check if a second reviewer would be helpful.

tnull · 2026-06-26T12:30:20Z

Rebased & refactored a bit, ready for review.

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

Allow Bitcoin Core RPC and REST chain-source configuration to specify the wallet birthday height used when creating a fresh wallet. This lets restored wallets rescan from a known height, including genesis, without overloading a global recovery toggle. Reject requested heights above the current chain tip with an explicit build error before wallet state is created. Existing wallets are not rewound by this option because a safe rewind must invalidate persisted wallet and LDK state before replaying blocks. Co-Authored-By: HAL 9000

Let Esplora and Electrum sync configs request BDK full scans until one succeeds. This keeps recovery scans retryable after transient sync failures while preserving normal incremental syncs once recovery has completed. Co-Authored-By: HAL 9000

tnull · 2026-06-29T14:19:58Z

Rebased to resolve minor conflict.

wpaulino

LGTM, just one comment

wpaulino · 2026-06-29T16:51:53Z

 	config: Arc<Config>,
 	logger: Arc<Logger>,
 	node_metrics: Arc<PersistedNodeMetrics>,
+	force_wallet_full_scan: AtomicBool,


Should we expose a block height as well to let the user optionally decide whether they want to start from a specific point?

You mean the current block height the node is synced to? That's already exposed via NodeStatus::current_best_block (cf. https://docs.rs/ldk-node/latest/ldk_node/struct.NodeStatus.html).

tnull · 2026-04-21T13:06:36Z

Fixes#818.

Previously, we would always start syncing from the latest block height or were able to force a full-resync from genesis via recovery_mode = true. Here we add more fine-grained control and allow an initial wallet import from a known birthday height for bitcoind RPC/REST chain sources. Relatedly, we also fix a minor bug where, if we failed to retrieve the tip hash on first startup, we'd always resync from genesis, which can be very costly.

Moreover, we also add a flag that allows the user to force a full scan for Esplora/Electrum wallets.

ldk-reviews-bot · 2026-04-21T13:06:40Z

I've assigned @wpaulino as a reviewer!
I'll wait for their review and will help manage the review process.
Once they submit their review, I'll check if a second reviewer would be helpful.

tnull · 2026-06-26T12:30:20Z

Rebased & refactored a bit, ready for review.

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

Allow Bitcoin Core RPC and REST chain-source configuration to specify the wallet birthday height used when creating a fresh wallet. This lets restored wallets rescan from a known height, including genesis, without overloading a global recovery toggle. Reject requested heights above the current chain tip with an explicit build error before wallet state is created. Existing wallets are not rewound by this option because a safe rewind must invalidate persisted wallet and LDK state before replaying blocks. Co-Authored-By: HAL 9000

Let Esplora and Electrum sync configs request BDK full scans until one succeeds. This keeps recovery scans retryable after transient sync failures while preserving normal incremental syncs once recovery has completed. Co-Authored-By: HAL 9000

tnull · 2026-06-29T14:19:58Z

Rebased to resolve minor conflict.

wpaulino

LGTM, just one comment

wpaulino · 2026-06-29T16:51:53Z

 	config: Arc<Config>,
 	logger: Arc<Logger>,
 	node_metrics: Arc<PersistedNodeMetrics>,
+	force_wallet_full_scan: AtomicBool,


Should we expose a block height as well to let the user optionally decide whether they want to start from a specific point?

You mean the current block height the node is synced to? That's already exposed via NodeStatus::current_best_block (cf. https://docs.rs/ldk-node/latest/ldk_node/struct.NodeStatus.html).

tnull added this to the 0.8 milestone Apr 21, 2026

tnull marked this pull request as draft April 21, 2026 13:06

tnull force-pushed the 2026-04-abort-on-first-startup-tip-fetch-failure branch from c692081 to 608108aCompare April 21, 2026 13:07

tnull mentioned this pull request Apr 21, 2026
Add --rescan-from-height CLI argument lightningdevkit/ldk-server#196
Merged

tnull force-pushed the 2026-04-abort-on-first-startup-tip-fetch-failure branch from 608108a to 494a448Compare June 26, 2026 12:19

tnull changed the title ~~2026 04 abort on first startup tip fetch failure~~Allow wallet imports from arbitrary heights, forcing full scansJun 26, 2026

tnull marked this pull request as ready for review June 26, 2026 12:25

ldk-reviews-bot requested a review from wpaulino June 26, 2026 12:25

tnull mentioned this pull request Jun 26, 2026
Add wallet birthday height for seed recovery on pruned nodes #822
Closed

tnull added 3 commits June 29, 2026 16:18

Add forced wallet full scans
101c827
Let Esplora and Electrum sync configs request BDK full scans until one succeeds. This keeps recovery scans retryable after transient sync failures while preserving normal incremental syncs once recovery has completed. Co-Authored-By: HAL 9000

tnull force-pushed the 2026-04-abort-on-first-startup-tip-fetch-failure branch from 494a448 to 101c827Compare June 29, 2026 14:19

wpaulino approved these changes Jun 29, 2026
View reviewed changes

tnull merged commit f2e44fd into lightningdevkit:mainJun 30, 2026
23 checks passed

tonible14012002 mentioned this pull request Jun 30, 2026
Sync main with upstream lightningdevkit/ldk-node (86 commits) lamtuanvu/ldk-node#4
Open

thesimplekid mentioned this pull request Jul 28, 2026
fix(bdk): avoid genesis scans for new Bitcoin Core wallets cashubtc/cdk#2271
Merged
3 tasks