Drop the need for fork headers when calling Listen's disconnect by TheBlueMatt · Pull Request #3876 · lightningdevkit/rust-lightning

TheBlueMatt · 2025-06-18T21:01:45Z

The Listen::block_disconnected method is nice in that listeners
learn about each block disconnected in series. Further, it included
the header of the block that is being disconnected to allow the
listeners to do some checking that the interface is being used
correctly (namely, asserting that the header's block hash matches
their current understanding of the best chain).

However, this interface has some substantial drawbacks. Namely, the
requirement that fork headers be passed in means that restarting
with a new node that has no idea about a previous fork leaves us
unable to replay the chain at all. Further, while when various
listeners were initially written learning about each block
disconnected in series seemed useful, but now we no longer rely on
that anyway because the Confirm interface does not allow for it.

Thus, here, we replace Listen::block_disconnected with a new
Listen::blocks_disconnected, taking only information about the
fork point/new best chain tip (in the form of its block hash and
height) rather than information about previous fork blocks and only
requiring a single call to complete multiple block disconnections
during a reorg.

This requires removing some assertions on block disconnection
ordering, but because we now provide lightning-block-sync and
expect users to use it when using the Listen interface, these
assertions are much less critical.

ldk-reviews-bot · 2025-06-18T21:01:47Z

👋 Thanks for assigning @tnull 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.

ldk-reviews-bot · 2025-06-19T00:07:26Z

👋 The first review has been submitted!

Do you think this PR is ready for a second reviewer? If so, click here to assign a second reviewer.

ldk-reviews-bot · 2025-06-19T16:11:23Z

✅ Added second reviewer: @joostjager

codecov · 2025-06-19T18:38:17Z

Codecov Report

❌ Patch coverage is 79.36508% with 26 lines in your changes missing coverage. Please review.
✅ Project coverage is 88.74%. Comparing base (86c6960) to head (a5b745a).
⚠️ Report is 38 commits behind head on main.

Files with missing lines	Patch %	Lines
lightning/src/chain/channelmonitor.rs	70.00%	6 Missing ⚠️
lightning/src/chain/mod.rs	0.00%	5 Missing ⚠️
lightning/src/util/sweep.rs	0.00%	5 Missing ⚠️
lightning-liquidity/src/manager.rs	0.00%	4 Missing ⚠️
lightning-block-sync/src/test_utils.rs	66.66%	3 Missing ⚠️
lightning-block-sync/src/init.rs	90.00%	1 Missing ⚠️
lightning/src/ln/channelmanager.rs	95.83%	1 Missing ⚠️
lightning/src/ln/functional_tests.rs	66.66%	1 Missing ⚠️

Additional details and impacted files

@@ Coverage Diff @@## main #3876 +/- ##
=======================================
Coverage 88.73% 88.74% =======================================
Files 176 176 Lines 129106 129102 -4 Branches 129106 129102 -4 =======================================
+ Hits 114567 114575 +8 + Misses 11937 11931 -6 + Partials 2602 2596 -6

Flag	Coverage Δ
fuzzing	`22.32% <13.18%> (+0.01%)`	⬆️
tests	`88.58% <79.36%> (+<0.01%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

ldk-reviews-bot · 2025-06-21T16:11:37Z

🔔 1st Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

tnull

Changes LGTM, but while we're here it would be good to add some details regarding the implicit assumptions on the Listen docs, and adding (back) some asserts/debug_asserts would be appreciated.

ldk-reviews-bot · 2025-06-30T00:00:45Z

🔔 1st Reminder

Hey @tnull @jkczyz! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-06-30T00:00:47Z

🔔 1st Reminder

Hey @tnull @jkczyz! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

tnull · 2025-06-30T11:56:15Z

+///
+/// Each block must be connected in chain order with one call to either
+/// [`Listen::block_connected`] or [`Listen::filtered_block_connected`]. If a call to the
+/// [`Filter`] interface was made during block processing and further transaction(s) from the same


Hmm, is this a new requirement? I imagine it's very hard to reliably implement this: keep track of all registered Txids/outputs, then match them on a block, apply the block, then check again if something new was registered, filter the block again, then potentially call once more. Also, why do we require it only here, but not on Confirm?

This has always been the case, just poorly documented. It is, indeed, not the case on Confirm (which doesn't require "blocks" to be connected in-order at all, though it does require all transactions to be topologically sorted).

tnull · 2025-06-30T12:03:50Z

 }
- self.chain_listener.block_disconnected(&header.header, header.height);
+ }
+ if let Some(block) = disconnected_blocks.last() {


If we're now happy to use the fork point, why are we keeping a Vec of all disconnected blocks around at all? Shouldn't we now be able to convert this to the new behavior entirely? Seems ChainDifference::common_ancestor would already provide what we need, no?

Its needed by the cache, which I didn't want to change in this PR - #3876 (comment)

tnull · 2025-06-30T12:13:59Z

- for header in disconnected_blocks.drain(..) {
+	fn disconnect_blocks(&mut self, disconnected_blocks: Vec<ValidatedBlockHeader>) {
+ for header in disconnected_blocks.iter() {
 if let Some(cached_header) = self.header_cache.block_disconnected(&header.block_hash) {


Should we change the Cache API accordingly?

We could, but it seems somewhat disjoint from this PR, given there's further work to do in lightning-block-sync anyway, so I kinda wanted to keep it as small as can be.

Mhh, might be good to document somewhere what steps you deem left before you'd consider the transition to this new approach complete. I guess all of them should land before the next release then, to not end up with a half-migrated codebase in the release?

I mean the API/stuff in lightning in in a perfectly fine state after this PR, and lightning-block-sync just deserves a bit of efficiency in dropping a vec and improving the cache afterwards. This PR obviously doesn't accomplish the goals that #3600 set out to, but is just a step towards it (the "complicated" step that requires making sure all the lightning-internal stuff isn't broken by changing the API).
AFAIU, to get to the point that bitcoind (and all) syncs support swapping to a new chain during a reorg and don't fetch a pile of redundant blocks we need to:
make BestBlock contain a list of 6(ish?) block hashes, not one
use that list in lightning-block-sync (and eventually lightning-transaction-sync) to do the sync without leaning on the cache
expand the runtime caching to cache partial chains across clients in the init sync logic
(eventually) ensure lightning-block-sync doesn't have any spare vecs or whatever lying around.

I still think it would make sense to open an issue for this larger refactoring you're planning, as there are connected aspects to discuss that don't really belong in this PR.
make BestBlock contain a list of 6(ish?) block hashes, not one
For example, how do we imagine this to work exactly, especially for the Confirm/lightning-transaction-sync case?
For Esplora, we currently retrieve the tip hash, retrieve the header and the block status (including the hight), before we call best_block_updated, which is already 3 costly RTTs. If we now would require to track the 6 most-recent hashes, we'd need to make at least 5 more subsequent calls (bringing this it at least 8 RTTs per sync round) to retrieve the hashes at [(height-5)..(height-1)]. But, given that these are individual calls, there is no way to tell if any reorg happened during some of these calls, so they are inherently race-y.
For Electrum, the results would be very similar for the polling client in its current form. Note we eventually want to switch the client to a streaming version making use of Electum's subscription model though, and requiring 'last 6 blocks' would probably require us to resort to costly polling again.
If we'd otherwise extend the client to start tracking more of the chain state (i.e., actually tracking a local chain 6-suffix) across rounds this would complicate the client logic quite a bit and make it even more susceptible to race conditions.
TLDR: I still maintain all of this would be/is resulting in a major refactor across our chain syncing crates and logic, and it would be great to discuss what we imagine to be involved and the corresponding trade-offs before we just jump into it heads first.

We can definitely make it optional (and only used for full-node-sync) if we think its a major issue. Of course the issue becomes that you cannot (even today) safely transition from an esplora/electrum-synced node to a full-chain-sync one, but addressing that really requires a substantial rework of how we think about chain sync, so maybe its not worth worrying about that.
Of course, storing the last 6 blocks is pretty trivial for a full-node-sync client, and the point is really just to expose the thing that the sync driver gave us, so its not like we'd use it in Listen/Confirm implementations.
My understanding is that this would address the restart-with-different-node case that #3600 wanted to address, even if its optional and just used by the full-node-syncing logic?

but addressing that really requires a substantial rework of how we think about chain sync, so maybe its not worth worrying about that.
Hmm, given that we even recently had users inquire whether they could switch chain sources at runtime, I do expect that we will need to tackle this eventually, as there will be users wanting to switch chain sources, and it's very unintuitive to either prohibit that, have it one-way, or even document the risks that might come from it.
Of course, storing the last 6 blocks is pretty trivial for a full-node-sync client, and the point is really just to expose the thing that the sync driver gave us, so its not like we'd use it in Listen/Confirm implementations.
So we would only do it when it's convenient, which means we could switch bitcoind nodes, but still not between chain sources?

Hmm, given that we even recently had users inquire whether they could switch chain sources at runtime, I do expect that we will need to tackle this eventually, as there will be users wanting to switch chain sources, and it's very unintuitive to either prohibit that, have it one-way, or even document the risks that might come from it.
Sure, I agree, hence why I suggested moving to storing several recent blocks rather than only one. However, as you note it might not be super practical, so we're kinda stuck.
I think, basically, if we did that plus required transactions_confirmed calls come before best_block_updated calls (which may we're doing anyway, cc #3867 (comment)) then moving from one chain source to another is totally fine, even at runtime (as long as you don't miss transactions).
So we would only do it when it's convenient, which means we could switch bitcoind nodes, but still not between chain sources?
I mean I'm not sure what else we can do? If its too impractical to do it on some chain sources we can't really make it required, and if its not available switching chain sources isn't going to be 100% reliable.

ldk-reviews-bot · 2025-07-02T00:01:36Z

🔔 2nd Reminder

Hey @jkczyz! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

tnull

rustfmt is unhappy right now

ldk-reviews-bot · 2025-07-05T00:01:06Z

🔔 3rd Reminder

Hey @jkczyz! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-07-07T00:01:51Z

🔔 4th Reminder

Hey @jkczyz! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-07-09T00:02:38Z

🔔 5th Reminder

Hey @jkczyz! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-07-12T00:00:34Z

🔔 6th Reminder

Hey @jkczyz! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

jkczyz

LGTM. Please squash.

TheBlueMatt · 2025-08-07T20:29:59Z

Squashed without further changes.

jkczyz

Linting CI failures look unrelated.

ldk-reviews-bot · 2025-08-23T15:02:08Z

🔔 1st Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-08-25T15:02:50Z

🔔 2nd Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-08-27T15:03:23Z

🔔 3rd Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-08-30T00:01:01Z

🔔 4th Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-09-01T00:01:44Z

🔔 5th Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

tnull

This unfortunately needs a small rebase by now.

tnull

ACK, after rebase. Please excuse the considerable delay here.

I still think it would be good to document in an issue what's 'left' post this PR, at least where we want to take things directionally. Maybe we can just transfer #3876 (comment) to an issue that can serve as a base for discussions?

The `Listen::block_disconnected` method is nice in that listeners learn about each block disconnected in series. Further, it included the header of the block that is being disconnected to allow the listeners to do some checking that the interface is being used correctly (namely, asserting that the header's block hash matches their current understanding of the best chain). However, this interface has some substantial drawbacks. Namely, the requirement that fork headers be passed in means that restarting with a new node that has no idea about a previous fork leaves us unable to replay the chain at all. Further, while when various listeners were initially written learning about each block disconnected in series seemed useful, but now we no longer rely on that anyway because the `Confirm` interface does not allow for it. Thus, here, we replace `Listen::block_disconnected` with a new `Listen::blocks_disconnected`, taking only information about the fork point/new best chain tip (in the form of its block hash and height) rather than information about previous fork blocks and only requiring a single call to complete multiple block disconnections during a reorg. We also swap to using a single `BestBlock` to describe the new chain tip, in anticipation of future extensions to `BestBlock`. This requires removing some assertions on block disconnection ordering, but because we now provide `lightning-block-sync` and expect users to use it when using the `Listen` interface, these assertions are much less critical.

`OnchainTxHandler` is an internal struct and doesn't implement `Listen`, but its still nice to have its API mirror the `Listen` API so that internal code all looks similar.

Now that the `Listen` interface allows blocks to be disconnected in batches rather than one at a time, we should test this. Here we add a new `ConnectStyle` for the functional test framework which tests doing so.

When calling `Channel::best_block_updated` we pass it the timestamp of the block we're connecting so that it can track the highest timestamp it has seen. However, in some cases, we don't actually have a timestamp to pass, which `Channel::best_block_updated` will happily ignore as it always takes the `max` of its existing value. Thus, we really should pass a `None` to ensure the API is understandable, which we do here.

`Listen` is somewhat quiet on high-level use and even requirements, which we document further here.

TheBlueMatt · 2025-09-02T13:50:21Z

Rebased with no further changes. Also opened #4042

ldk-reviews-bot · 2025-09-04T13:50:37Z

🔔 1st Reminder

Hey @jkczyz! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

TheBlueMatt · 2025-06-18T21:01:45Z

The Listen::block_disconnected method is nice in that listeners
learn about each block disconnected in series. Further, it included
the header of the block that is being disconnected to allow the
listeners to do some checking that the interface is being used
correctly (namely, asserting that the header's block hash matches
their current understanding of the best chain).

However, this interface has some substantial drawbacks. Namely, the
requirement that fork headers be passed in means that restarting
with a new node that has no idea about a previous fork leaves us
unable to replay the chain at all. Further, while when various
listeners were initially written learning about each block
disconnected in series seemed useful, but now we no longer rely on
that anyway because the Confirm interface does not allow for it.

Thus, here, we replace Listen::block_disconnected with a new
Listen::blocks_disconnected, taking only information about the
fork point/new best chain tip (in the form of its block hash and
height) rather than information about previous fork blocks and only
requiring a single call to complete multiple block disconnections
during a reorg.

This requires removing some assertions on block disconnection
ordering, but because we now provide lightning-block-sync and
expect users to use it when using the Listen interface, these
assertions are much less critical.

ldk-reviews-bot · 2025-06-18T21:01:47Z

👋 Thanks for assigning @tnull 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.

ldk-reviews-bot · 2025-06-19T00:07:26Z

👋 The first review has been submitted!

Do you think this PR is ready for a second reviewer? If so, click here to assign a second reviewer.

ldk-reviews-bot · 2025-06-19T16:11:23Z

✅ Added second reviewer: @joostjager

codecov · 2025-06-19T18:38:17Z

Codecov Report

❌ Patch coverage is 79.36508% with 26 lines in your changes missing coverage. Please review.
✅ Project coverage is 88.74%. Comparing base (86c6960) to head (a5b745a).
⚠️ Report is 38 commits behind head on main.

Files with missing lines	Patch %	Lines
lightning/src/chain/channelmonitor.rs	70.00%	6 Missing ⚠️
lightning/src/chain/mod.rs	0.00%	5 Missing ⚠️
lightning/src/util/sweep.rs	0.00%	5 Missing ⚠️
lightning-liquidity/src/manager.rs	0.00%	4 Missing ⚠️
lightning-block-sync/src/test_utils.rs	66.66%	3 Missing ⚠️
lightning-block-sync/src/init.rs	90.00%	1 Missing ⚠️
lightning/src/ln/channelmanager.rs	95.83%	1 Missing ⚠️
lightning/src/ln/functional_tests.rs	66.66%	1 Missing ⚠️

Additional details and impacted files

@@ Coverage Diff @@## main #3876 +/- ##
=======================================
Coverage 88.73% 88.74% =======================================
Files 176 176 Lines 129106 129102 -4 Branches 129106 129102 -4 =======================================
+ Hits 114567 114575 +8 + Misses 11937 11931 -6 + Partials 2602 2596 -6

Flag	Coverage Δ
fuzzing	`22.32% <13.18%> (+0.01%)`	⬆️
tests	`88.58% <79.36%> (+<0.01%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

ldk-reviews-bot · 2025-06-21T16:11:37Z

🔔 1st Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

tnull

Changes LGTM, but while we're here it would be good to add some details regarding the implicit assumptions on the Listen docs, and adding (back) some asserts/debug_asserts would be appreciated.

ldk-reviews-bot · 2025-06-30T00:00:45Z

🔔 1st Reminder

Hey @tnull @jkczyz! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-06-30T00:00:47Z

🔔 1st Reminder

Hey @tnull @jkczyz! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

tnull · 2025-06-30T11:56:15Z

+///
+/// Each block must be connected in chain order with one call to either
+/// [`Listen::block_connected`] or [`Listen::filtered_block_connected`]. If a call to the
+/// [`Filter`] interface was made during block processing and further transaction(s) from the same


Hmm, is this a new requirement? I imagine it's very hard to reliably implement this: keep track of all registered Txids/outputs, then match them on a block, apply the block, then check again if something new was registered, filter the block again, then potentially call once more. Also, why do we require it only here, but not on Confirm?

This has always been the case, just poorly documented. It is, indeed, not the case on Confirm (which doesn't require "blocks" to be connected in-order at all, though it does require all transactions to be topologically sorted).

tnull · 2025-06-30T12:03:50Z

 }
- self.chain_listener.block_disconnected(&header.header, header.height);
+ }
+ if let Some(block) = disconnected_blocks.last() {


If we're now happy to use the fork point, why are we keeping a Vec of all disconnected blocks around at all? Shouldn't we now be able to convert this to the new behavior entirely? Seems ChainDifference::common_ancestor would already provide what we need, no?

Its needed by the cache, which I didn't want to change in this PR - #3876 (comment)

tnull · 2025-06-30T12:13:59Z

- for header in disconnected_blocks.drain(..) {
+	fn disconnect_blocks(&mut self, disconnected_blocks: Vec<ValidatedBlockHeader>) {
+ for header in disconnected_blocks.iter() {
 if let Some(cached_header) = self.header_cache.block_disconnected(&header.block_hash) {


Should we change the Cache API accordingly?

We could, but it seems somewhat disjoint from this PR, given there's further work to do in lightning-block-sync anyway, so I kinda wanted to keep it as small as can be.

Mhh, might be good to document somewhere what steps you deem left before you'd consider the transition to this new approach complete. I guess all of them should land before the next release then, to not end up with a half-migrated codebase in the release?

I mean the API/stuff in lightning in in a perfectly fine state after this PR, and lightning-block-sync just deserves a bit of efficiency in dropping a vec and improving the cache afterwards. This PR obviously doesn't accomplish the goals that #3600 set out to, but is just a step towards it (the "complicated" step that requires making sure all the lightning-internal stuff isn't broken by changing the API).
AFAIU, to get to the point that bitcoind (and all) syncs support swapping to a new chain during a reorg and don't fetch a pile of redundant blocks we need to:
make BestBlock contain a list of 6(ish?) block hashes, not one
use that list in lightning-block-sync (and eventually lightning-transaction-sync) to do the sync without leaning on the cache
expand the runtime caching to cache partial chains across clients in the init sync logic
(eventually) ensure lightning-block-sync doesn't have any spare vecs or whatever lying around.

I still think it would make sense to open an issue for this larger refactoring you're planning, as there are connected aspects to discuss that don't really belong in this PR.
make BestBlock contain a list of 6(ish?) block hashes, not one
For example, how do we imagine this to work exactly, especially for the Confirm/lightning-transaction-sync case?
For Esplora, we currently retrieve the tip hash, retrieve the header and the block status (including the hight), before we call best_block_updated, which is already 3 costly RTTs. If we now would require to track the 6 most-recent hashes, we'd need to make at least 5 more subsequent calls (bringing this it at least 8 RTTs per sync round) to retrieve the hashes at [(height-5)..(height-1)]. But, given that these are individual calls, there is no way to tell if any reorg happened during some of these calls, so they are inherently race-y.
For Electrum, the results would be very similar for the polling client in its current form. Note we eventually want to switch the client to a streaming version making use of Electum's subscription model though, and requiring 'last 6 blocks' would probably require us to resort to costly polling again.
If we'd otherwise extend the client to start tracking more of the chain state (i.e., actually tracking a local chain 6-suffix) across rounds this would complicate the client logic quite a bit and make it even more susceptible to race conditions.
TLDR: I still maintain all of this would be/is resulting in a major refactor across our chain syncing crates and logic, and it would be great to discuss what we imagine to be involved and the corresponding trade-offs before we just jump into it heads first.

We can definitely make it optional (and only used for full-node-sync) if we think its a major issue. Of course the issue becomes that you cannot (even today) safely transition from an esplora/electrum-synced node to a full-chain-sync one, but addressing that really requires a substantial rework of how we think about chain sync, so maybe its not worth worrying about that.
Of course, storing the last 6 blocks is pretty trivial for a full-node-sync client, and the point is really just to expose the thing that the sync driver gave us, so its not like we'd use it in Listen/Confirm implementations.
My understanding is that this would address the restart-with-different-node case that #3600 wanted to address, even if its optional and just used by the full-node-syncing logic?

but addressing that really requires a substantial rework of how we think about chain sync, so maybe its not worth worrying about that.
Hmm, given that we even recently had users inquire whether they could switch chain sources at runtime, I do expect that we will need to tackle this eventually, as there will be users wanting to switch chain sources, and it's very unintuitive to either prohibit that, have it one-way, or even document the risks that might come from it.
Of course, storing the last 6 blocks is pretty trivial for a full-node-sync client, and the point is really just to expose the thing that the sync driver gave us, so its not like we'd use it in Listen/Confirm implementations.
So we would only do it when it's convenient, which means we could switch bitcoind nodes, but still not between chain sources?

Hmm, given that we even recently had users inquire whether they could switch chain sources at runtime, I do expect that we will need to tackle this eventually, as there will be users wanting to switch chain sources, and it's very unintuitive to either prohibit that, have it one-way, or even document the risks that might come from it.
Sure, I agree, hence why I suggested moving to storing several recent blocks rather than only one. However, as you note it might not be super practical, so we're kinda stuck.
I think, basically, if we did that plus required transactions_confirmed calls come before best_block_updated calls (which may we're doing anyway, cc #3867 (comment)) then moving from one chain source to another is totally fine, even at runtime (as long as you don't miss transactions).
So we would only do it when it's convenient, which means we could switch bitcoind nodes, but still not between chain sources?
I mean I'm not sure what else we can do? If its too impractical to do it on some chain sources we can't really make it required, and if its not available switching chain sources isn't going to be 100% reliable.

ldk-reviews-bot · 2025-07-02T00:01:36Z

🔔 2nd Reminder

Hey @jkczyz! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

tnull

rustfmt is unhappy right now

ldk-reviews-bot · 2025-07-05T00:01:06Z

🔔 3rd Reminder

Hey @jkczyz! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-07-07T00:01:51Z

🔔 4th Reminder

Hey @jkczyz! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-07-09T00:02:38Z

🔔 5th Reminder

Hey @jkczyz! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-07-12T00:00:34Z

🔔 6th Reminder

Hey @jkczyz! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

jkczyz

LGTM. Please squash.

TheBlueMatt · 2025-08-07T20:29:59Z

Squashed without further changes.

jkczyz

Linting CI failures look unrelated.

ldk-reviews-bot · 2025-08-23T15:02:08Z

🔔 1st Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-08-25T15:02:50Z

🔔 2nd Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-08-27T15:03:23Z

🔔 3rd Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-08-30T00:01:01Z

🔔 4th Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-09-01T00:01:44Z

🔔 5th Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

tnull

This unfortunately needs a small rebase by now.

tnull

ACK, after rebase. Please excuse the considerable delay here.

I still think it would be good to document in an issue what's 'left' post this PR, at least where we want to take things directionally. Maybe we can just transfer #3876 (comment) to an issue that can serve as a base for discussions?

The `Listen::block_disconnected` method is nice in that listeners learn about each block disconnected in series. Further, it included the header of the block that is being disconnected to allow the listeners to do some checking that the interface is being used correctly (namely, asserting that the header's block hash matches their current understanding of the best chain). However, this interface has some substantial drawbacks. Namely, the requirement that fork headers be passed in means that restarting with a new node that has no idea about a previous fork leaves us unable to replay the chain at all. Further, while when various listeners were initially written learning about each block disconnected in series seemed useful, but now we no longer rely on that anyway because the `Confirm` interface does not allow for it. Thus, here, we replace `Listen::block_disconnected` with a new `Listen::blocks_disconnected`, taking only information about the fork point/new best chain tip (in the form of its block hash and height) rather than information about previous fork blocks and only requiring a single call to complete multiple block disconnections during a reorg. We also swap to using a single `BestBlock` to describe the new chain tip, in anticipation of future extensions to `BestBlock`. This requires removing some assertions on block disconnection ordering, but because we now provide `lightning-block-sync` and expect users to use it when using the `Listen` interface, these assertions are much less critical.

`OnchainTxHandler` is an internal struct and doesn't implement `Listen`, but its still nice to have its API mirror the `Listen` API so that internal code all looks similar.

Now that the `Listen` interface allows blocks to be disconnected in batches rather than one at a time, we should test this. Here we add a new `ConnectStyle` for the functional test framework which tests doing so.

When calling `Channel::best_block_updated` we pass it the timestamp of the block we're connecting so that it can track the highest timestamp it has seen. However, in some cases, we don't actually have a timestamp to pass, which `Channel::best_block_updated` will happily ignore as it always takes the `max` of its existing value. Thus, we really should pass a `None` to ensure the API is understandable, which we do here.

`Listen` is somewhat quiet on high-level use and even requirements, which we document further here.

TheBlueMatt · 2025-09-02T13:50:21Z

Rebased with no further changes. Also opened #4042

ldk-reviews-bot · 2025-09-04T13:50:37Z

🔔 1st Reminder

Hey @jkczyz! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

TheBlueMatt · 2025-06-18T21:01:45Z

The Listen::block_disconnected method is nice in that listeners
learn about each block disconnected in series. Further, it included
the header of the block that is being disconnected to allow the
listeners to do some checking that the interface is being used
correctly (namely, asserting that the header's block hash matches
their current understanding of the best chain).

However, this interface has some substantial drawbacks. Namely, the
requirement that fork headers be passed in means that restarting
with a new node that has no idea about a previous fork leaves us
unable to replay the chain at all. Further, while when various
listeners were initially written learning about each block
disconnected in series seemed useful, but now we no longer rely on
that anyway because the Confirm interface does not allow for it.

Thus, here, we replace Listen::block_disconnected with a new
Listen::blocks_disconnected, taking only information about the
fork point/new best chain tip (in the form of its block hash and
height) rather than information about previous fork blocks and only
requiring a single call to complete multiple block disconnections
during a reorg.

This requires removing some assertions on block disconnection
ordering, but because we now provide lightning-block-sync and
expect users to use it when using the Listen interface, these
assertions are much less critical.

ldk-reviews-bot · 2025-06-18T21:01:47Z

👋 Thanks for assigning @tnull 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.

ldk-reviews-bot · 2025-06-19T00:07:26Z

👋 The first review has been submitted!

Do you think this PR is ready for a second reviewer? If so, click here to assign a second reviewer.

ldk-reviews-bot · 2025-06-19T16:11:23Z

✅ Added second reviewer: @joostjager

codecov · 2025-06-19T18:38:17Z

Codecov Report

❌ Patch coverage is 79.36508% with 26 lines in your changes missing coverage. Please review.
✅ Project coverage is 88.74%. Comparing base (86c6960) to head (a5b745a).
⚠️ Report is 38 commits behind head on main.

Files with missing lines	Patch %	Lines
lightning/src/chain/channelmonitor.rs	70.00%	6 Missing ⚠️
lightning/src/chain/mod.rs	0.00%	5 Missing ⚠️
lightning/src/util/sweep.rs	0.00%	5 Missing ⚠️
lightning-liquidity/src/manager.rs	0.00%	4 Missing ⚠️
lightning-block-sync/src/test_utils.rs	66.66%	3 Missing ⚠️
lightning-block-sync/src/init.rs	90.00%	1 Missing ⚠️
lightning/src/ln/channelmanager.rs	95.83%	1 Missing ⚠️
lightning/src/ln/functional_tests.rs	66.66%	1 Missing ⚠️

Additional details and impacted files

@@ Coverage Diff @@## main #3876 +/- ##
=======================================
Coverage 88.73% 88.74% =======================================
Files 176 176 Lines 129106 129102 -4 Branches 129106 129102 -4 =======================================
+ Hits 114567 114575 +8 + Misses 11937 11931 -6 + Partials 2602 2596 -6

Flag	Coverage Δ
fuzzing	`22.32% <13.18%> (+0.01%)`	⬆️
tests	`88.58% <79.36%> (+<0.01%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

ldk-reviews-bot · 2025-06-21T16:11:37Z

🔔 1st Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

tnull

Changes LGTM, but while we're here it would be good to add some details regarding the implicit assumptions on the Listen docs, and adding (back) some asserts/debug_asserts would be appreciated.

ldk-reviews-bot · 2025-06-30T00:00:45Z

🔔 1st Reminder

Hey @tnull @jkczyz! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-06-30T00:00:47Z

🔔 1st Reminder

Hey @tnull @jkczyz! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

tnull · 2025-06-30T11:56:15Z

+///
+/// Each block must be connected in chain order with one call to either
+/// [`Listen::block_connected`] or [`Listen::filtered_block_connected`]. If a call to the
+/// [`Filter`] interface was made during block processing and further transaction(s) from the same


Hmm, is this a new requirement? I imagine it's very hard to reliably implement this: keep track of all registered Txids/outputs, then match them on a block, apply the block, then check again if something new was registered, filter the block again, then potentially call once more. Also, why do we require it only here, but not on Confirm?

This has always been the case, just poorly documented. It is, indeed, not the case on Confirm (which doesn't require "blocks" to be connected in-order at all, though it does require all transactions to be topologically sorted).

tnull · 2025-06-30T12:03:50Z

 }
- self.chain_listener.block_disconnected(&header.header, header.height);
+ }
+ if let Some(block) = disconnected_blocks.last() {


If we're now happy to use the fork point, why are we keeping a Vec of all disconnected blocks around at all? Shouldn't we now be able to convert this to the new behavior entirely? Seems ChainDifference::common_ancestor would already provide what we need, no?

Its needed by the cache, which I didn't want to change in this PR - #3876 (comment)

tnull · 2025-06-30T12:13:59Z

- for header in disconnected_blocks.drain(..) {
+	fn disconnect_blocks(&mut self, disconnected_blocks: Vec<ValidatedBlockHeader>) {
+ for header in disconnected_blocks.iter() {
 if let Some(cached_header) = self.header_cache.block_disconnected(&header.block_hash) {


Should we change the Cache API accordingly?

We could, but it seems somewhat disjoint from this PR, given there's further work to do in lightning-block-sync anyway, so I kinda wanted to keep it as small as can be.

Mhh, might be good to document somewhere what steps you deem left before you'd consider the transition to this new approach complete. I guess all of them should land before the next release then, to not end up with a half-migrated codebase in the release?

I mean the API/stuff in lightning in in a perfectly fine state after this PR, and lightning-block-sync just deserves a bit of efficiency in dropping a vec and improving the cache afterwards. This PR obviously doesn't accomplish the goals that #3600 set out to, but is just a step towards it (the "complicated" step that requires making sure all the lightning-internal stuff isn't broken by changing the API).
AFAIU, to get to the point that bitcoind (and all) syncs support swapping to a new chain during a reorg and don't fetch a pile of redundant blocks we need to:
make BestBlock contain a list of 6(ish?) block hashes, not one
use that list in lightning-block-sync (and eventually lightning-transaction-sync) to do the sync without leaning on the cache
expand the runtime caching to cache partial chains across clients in the init sync logic
(eventually) ensure lightning-block-sync doesn't have any spare vecs or whatever lying around.

I still think it would make sense to open an issue for this larger refactoring you're planning, as there are connected aspects to discuss that don't really belong in this PR.
make BestBlock contain a list of 6(ish?) block hashes, not one
For example, how do we imagine this to work exactly, especially for the Confirm/lightning-transaction-sync case?
For Esplora, we currently retrieve the tip hash, retrieve the header and the block status (including the hight), before we call best_block_updated, which is already 3 costly RTTs. If we now would require to track the 6 most-recent hashes, we'd need to make at least 5 more subsequent calls (bringing this it at least 8 RTTs per sync round) to retrieve the hashes at [(height-5)..(height-1)]. But, given that these are individual calls, there is no way to tell if any reorg happened during some of these calls, so they are inherently race-y.
For Electrum, the results would be very similar for the polling client in its current form. Note we eventually want to switch the client to a streaming version making use of Electum's subscription model though, and requiring 'last 6 blocks' would probably require us to resort to costly polling again.
If we'd otherwise extend the client to start tracking more of the chain state (i.e., actually tracking a local chain 6-suffix) across rounds this would complicate the client logic quite a bit and make it even more susceptible to race conditions.
TLDR: I still maintain all of this would be/is resulting in a major refactor across our chain syncing crates and logic, and it would be great to discuss what we imagine to be involved and the corresponding trade-offs before we just jump into it heads first.

We can definitely make it optional (and only used for full-node-sync) if we think its a major issue. Of course the issue becomes that you cannot (even today) safely transition from an esplora/electrum-synced node to a full-chain-sync one, but addressing that really requires a substantial rework of how we think about chain sync, so maybe its not worth worrying about that.
Of course, storing the last 6 blocks is pretty trivial for a full-node-sync client, and the point is really just to expose the thing that the sync driver gave us, so its not like we'd use it in Listen/Confirm implementations.
My understanding is that this would address the restart-with-different-node case that #3600 wanted to address, even if its optional and just used by the full-node-syncing logic?

but addressing that really requires a substantial rework of how we think about chain sync, so maybe its not worth worrying about that.
Hmm, given that we even recently had users inquire whether they could switch chain sources at runtime, I do expect that we will need to tackle this eventually, as there will be users wanting to switch chain sources, and it's very unintuitive to either prohibit that, have it one-way, or even document the risks that might come from it.
Of course, storing the last 6 blocks is pretty trivial for a full-node-sync client, and the point is really just to expose the thing that the sync driver gave us, so its not like we'd use it in Listen/Confirm implementations.
So we would only do it when it's convenient, which means we could switch bitcoind nodes, but still not between chain sources?

Hmm, given that we even recently had users inquire whether they could switch chain sources at runtime, I do expect that we will need to tackle this eventually, as there will be users wanting to switch chain sources, and it's very unintuitive to either prohibit that, have it one-way, or even document the risks that might come from it.
Sure, I agree, hence why I suggested moving to storing several recent blocks rather than only one. However, as you note it might not be super practical, so we're kinda stuck.
I think, basically, if we did that plus required transactions_confirmed calls come before best_block_updated calls (which may we're doing anyway, cc #3867 (comment)) then moving from one chain source to another is totally fine, even at runtime (as long as you don't miss transactions).
So we would only do it when it's convenient, which means we could switch bitcoind nodes, but still not between chain sources?
I mean I'm not sure what else we can do? If its too impractical to do it on some chain sources we can't really make it required, and if its not available switching chain sources isn't going to be 100% reliable.

ldk-reviews-bot · 2025-07-02T00:01:36Z

🔔 2nd Reminder

Hey @jkczyz! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

tnull

rustfmt is unhappy right now

ldk-reviews-bot · 2025-07-05T00:01:06Z

🔔 3rd Reminder

Hey @jkczyz! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-07-07T00:01:51Z

🔔 4th Reminder

Hey @jkczyz! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-07-09T00:02:38Z

🔔 5th Reminder

Hey @jkczyz! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-07-12T00:00:34Z

🔔 6th Reminder

Hey @jkczyz! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

jkczyz

LGTM. Please squash.

TheBlueMatt · 2025-08-07T20:29:59Z

Squashed without further changes.

jkczyz

Linting CI failures look unrelated.

ldk-reviews-bot · 2025-08-23T15:02:08Z

🔔 1st Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-08-25T15:02:50Z

🔔 2nd Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-08-27T15:03:23Z

🔔 3rd Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-08-30T00:01:01Z

🔔 4th Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-09-01T00:01:44Z

🔔 5th Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

tnull

This unfortunately needs a small rebase by now.

tnull

ACK, after rebase. Please excuse the considerable delay here.

I still think it would be good to document in an issue what's 'left' post this PR, at least where we want to take things directionally. Maybe we can just transfer #3876 (comment) to an issue that can serve as a base for discussions?

The `Listen::block_disconnected` method is nice in that listeners learn about each block disconnected in series. Further, it included the header of the block that is being disconnected to allow the listeners to do some checking that the interface is being used correctly (namely, asserting that the header's block hash matches their current understanding of the best chain). However, this interface has some substantial drawbacks. Namely, the requirement that fork headers be passed in means that restarting with a new node that has no idea about a previous fork leaves us unable to replay the chain at all. Further, while when various listeners were initially written learning about each block disconnected in series seemed useful, but now we no longer rely on that anyway because the `Confirm` interface does not allow for it. Thus, here, we replace `Listen::block_disconnected` with a new `Listen::blocks_disconnected`, taking only information about the fork point/new best chain tip (in the form of its block hash and height) rather than information about previous fork blocks and only requiring a single call to complete multiple block disconnections during a reorg. We also swap to using a single `BestBlock` to describe the new chain tip, in anticipation of future extensions to `BestBlock`. This requires removing some assertions on block disconnection ordering, but because we now provide `lightning-block-sync` and expect users to use it when using the `Listen` interface, these assertions are much less critical.

`OnchainTxHandler` is an internal struct and doesn't implement `Listen`, but its still nice to have its API mirror the `Listen` API so that internal code all looks similar.

Now that the `Listen` interface allows blocks to be disconnected in batches rather than one at a time, we should test this. Here we add a new `ConnectStyle` for the functional test framework which tests doing so.

When calling `Channel::best_block_updated` we pass it the timestamp of the block we're connecting so that it can track the highest timestamp it has seen. However, in some cases, we don't actually have a timestamp to pass, which `Channel::best_block_updated` will happily ignore as it always takes the `max` of its existing value. Thus, we really should pass a `None` to ensure the API is understandable, which we do here.

`Listen` is somewhat quiet on high-level use and even requirements, which we document further here.

TheBlueMatt · 2025-09-02T13:50:21Z

Rebased with no further changes. Also opened #4042

ldk-reviews-bot · 2025-09-04T13:50:37Z

🔔 1st Reminder

Hey @jkczyz! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

TheBlueMatt · 2025-06-18T21:01:45Z

The Listen::block_disconnected method is nice in that listeners
learn about each block disconnected in series. Further, it included
the header of the block that is being disconnected to allow the
listeners to do some checking that the interface is being used
correctly (namely, asserting that the header's block hash matches
their current understanding of the best chain).

However, this interface has some substantial drawbacks. Namely, the
requirement that fork headers be passed in means that restarting
with a new node that has no idea about a previous fork leaves us
unable to replay the chain at all. Further, while when various
listeners were initially written learning about each block
disconnected in series seemed useful, but now we no longer rely on
that anyway because the Confirm interface does not allow for it.

Thus, here, we replace Listen::block_disconnected with a new
Listen::blocks_disconnected, taking only information about the
fork point/new best chain tip (in the form of its block hash and
height) rather than information about previous fork blocks and only
requiring a single call to complete multiple block disconnections
during a reorg.

This requires removing some assertions on block disconnection
ordering, but because we now provide lightning-block-sync and
expect users to use it when using the Listen interface, these
assertions are much less critical.

ldk-reviews-bot · 2025-06-18T21:01:47Z

👋 Thanks for assigning @tnull 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.

ldk-reviews-bot · 2025-06-19T00:07:26Z

👋 The first review has been submitted!

Do you think this PR is ready for a second reviewer? If so, click here to assign a second reviewer.

ldk-reviews-bot · 2025-06-19T16:11:23Z

✅ Added second reviewer: @joostjager

codecov · 2025-06-19T18:38:17Z

Codecov Report

❌ Patch coverage is 79.36508% with 26 lines in your changes missing coverage. Please review.
✅ Project coverage is 88.74%. Comparing base (86c6960) to head (a5b745a).
⚠️ Report is 38 commits behind head on main.

Files with missing lines	Patch %	Lines
lightning/src/chain/channelmonitor.rs	70.00%	6 Missing ⚠️
lightning/src/chain/mod.rs	0.00%	5 Missing ⚠️
lightning/src/util/sweep.rs	0.00%	5 Missing ⚠️
lightning-liquidity/src/manager.rs	0.00%	4 Missing ⚠️
lightning-block-sync/src/test_utils.rs	66.66%	3 Missing ⚠️
lightning-block-sync/src/init.rs	90.00%	1 Missing ⚠️
lightning/src/ln/channelmanager.rs	95.83%	1 Missing ⚠️
lightning/src/ln/functional_tests.rs	66.66%	1 Missing ⚠️

Additional details and impacted files

@@ Coverage Diff @@## main #3876 +/- ##
=======================================
Coverage 88.73% 88.74% =======================================
Files 176 176 Lines 129106 129102 -4 Branches 129106 129102 -4 =======================================
+ Hits 114567 114575 +8 + Misses 11937 11931 -6 + Partials 2602 2596 -6

Flag	Coverage Δ
fuzzing	`22.32% <13.18%> (+0.01%)`	⬆️
tests	`88.58% <79.36%> (+<0.01%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

ldk-reviews-bot · 2025-06-21T16:11:37Z

🔔 1st Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

tnull

Changes LGTM, but while we're here it would be good to add some details regarding the implicit assumptions on the Listen docs, and adding (back) some asserts/debug_asserts would be appreciated.

ldk-reviews-bot · 2025-06-30T00:00:45Z

🔔 1st Reminder

Hey @tnull @jkczyz! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-06-30T00:00:47Z

🔔 1st Reminder

Hey @tnull @jkczyz! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

tnull · 2025-06-30T11:56:15Z

+///
+/// Each block must be connected in chain order with one call to either
+/// [`Listen::block_connected`] or [`Listen::filtered_block_connected`]. If a call to the
+/// [`Filter`] interface was made during block processing and further transaction(s) from the same


Hmm, is this a new requirement? I imagine it's very hard to reliably implement this: keep track of all registered Txids/outputs, then match them on a block, apply the block, then check again if something new was registered, filter the block again, then potentially call once more. Also, why do we require it only here, but not on Confirm?

This has always been the case, just poorly documented. It is, indeed, not the case on Confirm (which doesn't require "blocks" to be connected in-order at all, though it does require all transactions to be topologically sorted).

tnull · 2025-06-30T12:03:50Z

 }
- self.chain_listener.block_disconnected(&header.header, header.height);
+ }
+ if let Some(block) = disconnected_blocks.last() {


If we're now happy to use the fork point, why are we keeping a Vec of all disconnected blocks around at all? Shouldn't we now be able to convert this to the new behavior entirely? Seems ChainDifference::common_ancestor would already provide what we need, no?

Its needed by the cache, which I didn't want to change in this PR - #3876 (comment)

tnull · 2025-06-30T12:13:59Z

- for header in disconnected_blocks.drain(..) {
+	fn disconnect_blocks(&mut self, disconnected_blocks: Vec<ValidatedBlockHeader>) {
+ for header in disconnected_blocks.iter() {
 if let Some(cached_header) = self.header_cache.block_disconnected(&header.block_hash) {


Should we change the Cache API accordingly?

We could, but it seems somewhat disjoint from this PR, given there's further work to do in lightning-block-sync anyway, so I kinda wanted to keep it as small as can be.

Mhh, might be good to document somewhere what steps you deem left before you'd consider the transition to this new approach complete. I guess all of them should land before the next release then, to not end up with a half-migrated codebase in the release?

I mean the API/stuff in lightning in in a perfectly fine state after this PR, and lightning-block-sync just deserves a bit of efficiency in dropping a vec and improving the cache afterwards. This PR obviously doesn't accomplish the goals that #3600 set out to, but is just a step towards it (the "complicated" step that requires making sure all the lightning-internal stuff isn't broken by changing the API).
AFAIU, to get to the point that bitcoind (and all) syncs support swapping to a new chain during a reorg and don't fetch a pile of redundant blocks we need to:
make BestBlock contain a list of 6(ish?) block hashes, not one
use that list in lightning-block-sync (and eventually lightning-transaction-sync) to do the sync without leaning on the cache
expand the runtime caching to cache partial chains across clients in the init sync logic
(eventually) ensure lightning-block-sync doesn't have any spare vecs or whatever lying around.

I still think it would make sense to open an issue for this larger refactoring you're planning, as there are connected aspects to discuss that don't really belong in this PR.
make BestBlock contain a list of 6(ish?) block hashes, not one
For example, how do we imagine this to work exactly, especially for the Confirm/lightning-transaction-sync case?
For Esplora, we currently retrieve the tip hash, retrieve the header and the block status (including the hight), before we call best_block_updated, which is already 3 costly RTTs. If we now would require to track the 6 most-recent hashes, we'd need to make at least 5 more subsequent calls (bringing this it at least 8 RTTs per sync round) to retrieve the hashes at [(height-5)..(height-1)]. But, given that these are individual calls, there is no way to tell if any reorg happened during some of these calls, so they are inherently race-y.
For Electrum, the results would be very similar for the polling client in its current form. Note we eventually want to switch the client to a streaming version making use of Electum's subscription model though, and requiring 'last 6 blocks' would probably require us to resort to costly polling again.
If we'd otherwise extend the client to start tracking more of the chain state (i.e., actually tracking a local chain 6-suffix) across rounds this would complicate the client logic quite a bit and make it even more susceptible to race conditions.
TLDR: I still maintain all of this would be/is resulting in a major refactor across our chain syncing crates and logic, and it would be great to discuss what we imagine to be involved and the corresponding trade-offs before we just jump into it heads first.

We can definitely make it optional (and only used for full-node-sync) if we think its a major issue. Of course the issue becomes that you cannot (even today) safely transition from an esplora/electrum-synced node to a full-chain-sync one, but addressing that really requires a substantial rework of how we think about chain sync, so maybe its not worth worrying about that.
Of course, storing the last 6 blocks is pretty trivial for a full-node-sync client, and the point is really just to expose the thing that the sync driver gave us, so its not like we'd use it in Listen/Confirm implementations.
My understanding is that this would address the restart-with-different-node case that #3600 wanted to address, even if its optional and just used by the full-node-syncing logic?

but addressing that really requires a substantial rework of how we think about chain sync, so maybe its not worth worrying about that.
Hmm, given that we even recently had users inquire whether they could switch chain sources at runtime, I do expect that we will need to tackle this eventually, as there will be users wanting to switch chain sources, and it's very unintuitive to either prohibit that, have it one-way, or even document the risks that might come from it.
Of course, storing the last 6 blocks is pretty trivial for a full-node-sync client, and the point is really just to expose the thing that the sync driver gave us, so its not like we'd use it in Listen/Confirm implementations.
So we would only do it when it's convenient, which means we could switch bitcoind nodes, but still not between chain sources?

Hmm, given that we even recently had users inquire whether they could switch chain sources at runtime, I do expect that we will need to tackle this eventually, as there will be users wanting to switch chain sources, and it's very unintuitive to either prohibit that, have it one-way, or even document the risks that might come from it.
Sure, I agree, hence why I suggested moving to storing several recent blocks rather than only one. However, as you note it might not be super practical, so we're kinda stuck.
I think, basically, if we did that plus required transactions_confirmed calls come before best_block_updated calls (which may we're doing anyway, cc #3867 (comment)) then moving from one chain source to another is totally fine, even at runtime (as long as you don't miss transactions).
So we would only do it when it's convenient, which means we could switch bitcoind nodes, but still not between chain sources?
I mean I'm not sure what else we can do? If its too impractical to do it on some chain sources we can't really make it required, and if its not available switching chain sources isn't going to be 100% reliable.

ldk-reviews-bot · 2025-07-02T00:01:36Z

🔔 2nd Reminder

Hey @jkczyz! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

tnull

rustfmt is unhappy right now

ldk-reviews-bot · 2025-07-05T00:01:06Z

🔔 3rd Reminder

Hey @jkczyz! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-07-07T00:01:51Z

🔔 4th Reminder

Hey @jkczyz! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-07-09T00:02:38Z

🔔 5th Reminder

Hey @jkczyz! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-07-12T00:00:34Z

🔔 6th Reminder

Hey @jkczyz! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

jkczyz

LGTM. Please squash.

TheBlueMatt · 2025-08-07T20:29:59Z

Squashed without further changes.

jkczyz

Linting CI failures look unrelated.

ldk-reviews-bot · 2025-08-23T15:02:08Z

🔔 1st Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-08-25T15:02:50Z

🔔 2nd Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-08-27T15:03:23Z

🔔 3rd Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-08-30T00:01:01Z

🔔 4th Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-09-01T00:01:44Z

🔔 5th Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

tnull

This unfortunately needs a small rebase by now.

tnull

ACK, after rebase. Please excuse the considerable delay here.

I still think it would be good to document in an issue what's 'left' post this PR, at least where we want to take things directionally. Maybe we can just transfer #3876 (comment) to an issue that can serve as a base for discussions?

The `Listen::block_disconnected` method is nice in that listeners learn about each block disconnected in series. Further, it included the header of the block that is being disconnected to allow the listeners to do some checking that the interface is being used correctly (namely, asserting that the header's block hash matches their current understanding of the best chain). However, this interface has some substantial drawbacks. Namely, the requirement that fork headers be passed in means that restarting with a new node that has no idea about a previous fork leaves us unable to replay the chain at all. Further, while when various listeners were initially written learning about each block disconnected in series seemed useful, but now we no longer rely on that anyway because the `Confirm` interface does not allow for it. Thus, here, we replace `Listen::block_disconnected` with a new `Listen::blocks_disconnected`, taking only information about the fork point/new best chain tip (in the form of its block hash and height) rather than information about previous fork blocks and only requiring a single call to complete multiple block disconnections during a reorg. We also swap to using a single `BestBlock` to describe the new chain tip, in anticipation of future extensions to `BestBlock`. This requires removing some assertions on block disconnection ordering, but because we now provide `lightning-block-sync` and expect users to use it when using the `Listen` interface, these assertions are much less critical.

`OnchainTxHandler` is an internal struct and doesn't implement `Listen`, but its still nice to have its API mirror the `Listen` API so that internal code all looks similar.

Now that the `Listen` interface allows blocks to be disconnected in batches rather than one at a time, we should test this. Here we add a new `ConnectStyle` for the functional test framework which tests doing so.

When calling `Channel::best_block_updated` we pass it the timestamp of the block we're connecting so that it can track the highest timestamp it has seen. However, in some cases, we don't actually have a timestamp to pass, which `Channel::best_block_updated` will happily ignore as it always takes the `max` of its existing value. Thus, we really should pass a `None` to ensure the API is understandable, which we do here.

`Listen` is somewhat quiet on high-level use and even requirements, which we document further here.

TheBlueMatt · 2025-09-02T13:50:21Z

Rebased with no further changes. Also opened #4042

ldk-reviews-bot · 2025-09-04T13:50:37Z

🔔 1st Reminder

Hey @jkczyz! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

TheBlueMatt · 2025-06-18T21:01:45Z

The Listen::block_disconnected method is nice in that listeners
learn about each block disconnected in series. Further, it included
the header of the block that is being disconnected to allow the
listeners to do some checking that the interface is being used
correctly (namely, asserting that the header's block hash matches
their current understanding of the best chain).

However, this interface has some substantial drawbacks. Namely, the
requirement that fork headers be passed in means that restarting
with a new node that has no idea about a previous fork leaves us
unable to replay the chain at all. Further, while when various
listeners were initially written learning about each block
disconnected in series seemed useful, but now we no longer rely on
that anyway because the Confirm interface does not allow for it.

Thus, here, we replace Listen::block_disconnected with a new
Listen::blocks_disconnected, taking only information about the
fork point/new best chain tip (in the form of its block hash and
height) rather than information about previous fork blocks and only
requiring a single call to complete multiple block disconnections
during a reorg.

This requires removing some assertions on block disconnection
ordering, but because we now provide lightning-block-sync and
expect users to use it when using the Listen interface, these
assertions are much less critical.

ldk-reviews-bot · 2025-06-18T21:01:47Z

👋 Thanks for assigning @tnull 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.

ldk-reviews-bot · 2025-06-19T00:07:26Z

👋 The first review has been submitted!

Do you think this PR is ready for a second reviewer? If so, click here to assign a second reviewer.

ldk-reviews-bot · 2025-06-19T16:11:23Z

✅ Added second reviewer: @joostjager

codecov · 2025-06-19T18:38:17Z

Codecov Report

❌ Patch coverage is 79.36508% with 26 lines in your changes missing coverage. Please review.
✅ Project coverage is 88.74%. Comparing base (86c6960) to head (a5b745a).
⚠️ Report is 38 commits behind head on main.

Files with missing lines	Patch %	Lines
lightning/src/chain/channelmonitor.rs	70.00%	6 Missing ⚠️
lightning/src/chain/mod.rs	0.00%	5 Missing ⚠️
lightning/src/util/sweep.rs	0.00%	5 Missing ⚠️
lightning-liquidity/src/manager.rs	0.00%	4 Missing ⚠️
lightning-block-sync/src/test_utils.rs	66.66%	3 Missing ⚠️
lightning-block-sync/src/init.rs	90.00%	1 Missing ⚠️
lightning/src/ln/channelmanager.rs	95.83%	1 Missing ⚠️
lightning/src/ln/functional_tests.rs	66.66%	1 Missing ⚠️

Additional details and impacted files

@@ Coverage Diff @@## main #3876 +/- ##
=======================================
Coverage 88.73% 88.74% =======================================
Files 176 176 Lines 129106 129102 -4 Branches 129106 129102 -4 =======================================
+ Hits 114567 114575 +8 + Misses 11937 11931 -6 + Partials 2602 2596 -6

Flag	Coverage Δ
fuzzing	`22.32% <13.18%> (+0.01%)`	⬆️
tests	`88.58% <79.36%> (+<0.01%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

ldk-reviews-bot · 2025-06-21T16:11:37Z

🔔 1st Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

tnull

Changes LGTM, but while we're here it would be good to add some details regarding the implicit assumptions on the Listen docs, and adding (back) some asserts/debug_asserts would be appreciated.

ldk-reviews-bot · 2025-06-30T00:00:45Z

🔔 1st Reminder

Hey @tnull @jkczyz! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-06-30T00:00:47Z

🔔 1st Reminder

Hey @tnull @jkczyz! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

tnull · 2025-06-30T11:56:15Z

+///
+/// Each block must be connected in chain order with one call to either
+/// [`Listen::block_connected`] or [`Listen::filtered_block_connected`]. If a call to the
+/// [`Filter`] interface was made during block processing and further transaction(s) from the same


Hmm, is this a new requirement? I imagine it's very hard to reliably implement this: keep track of all registered Txids/outputs, then match them on a block, apply the block, then check again if something new was registered, filter the block again, then potentially call once more. Also, why do we require it only here, but not on Confirm?

This has always been the case, just poorly documented. It is, indeed, not the case on Confirm (which doesn't require "blocks" to be connected in-order at all, though it does require all transactions to be topologically sorted).

tnull · 2025-06-30T12:03:50Z

 }
- self.chain_listener.block_disconnected(&header.header, header.height);
+ }
+ if let Some(block) = disconnected_blocks.last() {


If we're now happy to use the fork point, why are we keeping a Vec of all disconnected blocks around at all? Shouldn't we now be able to convert this to the new behavior entirely? Seems ChainDifference::common_ancestor would already provide what we need, no?

Its needed by the cache, which I didn't want to change in this PR - #3876 (comment)

tnull · 2025-06-30T12:13:59Z

- for header in disconnected_blocks.drain(..) {
+	fn disconnect_blocks(&mut self, disconnected_blocks: Vec<ValidatedBlockHeader>) {
+ for header in disconnected_blocks.iter() {
 if let Some(cached_header) = self.header_cache.block_disconnected(&header.block_hash) {


Should we change the Cache API accordingly?

We could, but it seems somewhat disjoint from this PR, given there's further work to do in lightning-block-sync anyway, so I kinda wanted to keep it as small as can be.

Mhh, might be good to document somewhere what steps you deem left before you'd consider the transition to this new approach complete. I guess all of them should land before the next release then, to not end up with a half-migrated codebase in the release?

I mean the API/stuff in lightning in in a perfectly fine state after this PR, and lightning-block-sync just deserves a bit of efficiency in dropping a vec and improving the cache afterwards. This PR obviously doesn't accomplish the goals that #3600 set out to, but is just a step towards it (the "complicated" step that requires making sure all the lightning-internal stuff isn't broken by changing the API).
AFAIU, to get to the point that bitcoind (and all) syncs support swapping to a new chain during a reorg and don't fetch a pile of redundant blocks we need to:
make BestBlock contain a list of 6(ish?) block hashes, not one
use that list in lightning-block-sync (and eventually lightning-transaction-sync) to do the sync without leaning on the cache
expand the runtime caching to cache partial chains across clients in the init sync logic
(eventually) ensure lightning-block-sync doesn't have any spare vecs or whatever lying around.

I still think it would make sense to open an issue for this larger refactoring you're planning, as there are connected aspects to discuss that don't really belong in this PR.
make BestBlock contain a list of 6(ish?) block hashes, not one
For example, how do we imagine this to work exactly, especially for the Confirm/lightning-transaction-sync case?
For Esplora, we currently retrieve the tip hash, retrieve the header and the block status (including the hight), before we call best_block_updated, which is already 3 costly RTTs. If we now would require to track the 6 most-recent hashes, we'd need to make at least 5 more subsequent calls (bringing this it at least 8 RTTs per sync round) to retrieve the hashes at [(height-5)..(height-1)]. But, given that these are individual calls, there is no way to tell if any reorg happened during some of these calls, so they are inherently race-y.
For Electrum, the results would be very similar for the polling client in its current form. Note we eventually want to switch the client to a streaming version making use of Electum's subscription model though, and requiring 'last 6 blocks' would probably require us to resort to costly polling again.
If we'd otherwise extend the client to start tracking more of the chain state (i.e., actually tracking a local chain 6-suffix) across rounds this would complicate the client logic quite a bit and make it even more susceptible to race conditions.
TLDR: I still maintain all of this would be/is resulting in a major refactor across our chain syncing crates and logic, and it would be great to discuss what we imagine to be involved and the corresponding trade-offs before we just jump into it heads first.

We can definitely make it optional (and only used for full-node-sync) if we think its a major issue. Of course the issue becomes that you cannot (even today) safely transition from an esplora/electrum-synced node to a full-chain-sync one, but addressing that really requires a substantial rework of how we think about chain sync, so maybe its not worth worrying about that.
Of course, storing the last 6 blocks is pretty trivial for a full-node-sync client, and the point is really just to expose the thing that the sync driver gave us, so its not like we'd use it in Listen/Confirm implementations.
My understanding is that this would address the restart-with-different-node case that #3600 wanted to address, even if its optional and just used by the full-node-syncing logic?

but addressing that really requires a substantial rework of how we think about chain sync, so maybe its not worth worrying about that.
Hmm, given that we even recently had users inquire whether they could switch chain sources at runtime, I do expect that we will need to tackle this eventually, as there will be users wanting to switch chain sources, and it's very unintuitive to either prohibit that, have it one-way, or even document the risks that might come from it.
Of course, storing the last 6 blocks is pretty trivial for a full-node-sync client, and the point is really just to expose the thing that the sync driver gave us, so its not like we'd use it in Listen/Confirm implementations.
So we would only do it when it's convenient, which means we could switch bitcoind nodes, but still not between chain sources?

Hmm, given that we even recently had users inquire whether they could switch chain sources at runtime, I do expect that we will need to tackle this eventually, as there will be users wanting to switch chain sources, and it's very unintuitive to either prohibit that, have it one-way, or even document the risks that might come from it.
Sure, I agree, hence why I suggested moving to storing several recent blocks rather than only one. However, as you note it might not be super practical, so we're kinda stuck.
I think, basically, if we did that plus required transactions_confirmed calls come before best_block_updated calls (which may we're doing anyway, cc #3867 (comment)) then moving from one chain source to another is totally fine, even at runtime (as long as you don't miss transactions).
So we would only do it when it's convenient, which means we could switch bitcoind nodes, but still not between chain sources?
I mean I'm not sure what else we can do? If its too impractical to do it on some chain sources we can't really make it required, and if its not available switching chain sources isn't going to be 100% reliable.

ldk-reviews-bot · 2025-07-02T00:01:36Z

🔔 2nd Reminder

Hey @jkczyz! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

tnull

rustfmt is unhappy right now

ldk-reviews-bot · 2025-07-05T00:01:06Z

🔔 3rd Reminder

Hey @jkczyz! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-07-07T00:01:51Z

🔔 4th Reminder

Hey @jkczyz! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-07-09T00:02:38Z

🔔 5th Reminder

Hey @jkczyz! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-07-12T00:00:34Z

🔔 6th Reminder

Hey @jkczyz! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

jkczyz

LGTM. Please squash.

TheBlueMatt · 2025-08-07T20:29:59Z

Squashed without further changes.

jkczyz

Linting CI failures look unrelated.

ldk-reviews-bot · 2025-08-23T15:02:08Z

🔔 1st Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-08-25T15:02:50Z

🔔 2nd Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-08-27T15:03:23Z

🔔 3rd Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-08-30T00:01:01Z

🔔 4th Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-09-01T00:01:44Z

🔔 5th Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

tnull

This unfortunately needs a small rebase by now.

tnull

ACK, after rebase. Please excuse the considerable delay here.

I still think it would be good to document in an issue what's 'left' post this PR, at least where we want to take things directionally. Maybe we can just transfer #3876 (comment) to an issue that can serve as a base for discussions?

The `Listen::block_disconnected` method is nice in that listeners learn about each block disconnected in series. Further, it included the header of the block that is being disconnected to allow the listeners to do some checking that the interface is being used correctly (namely, asserting that the header's block hash matches their current understanding of the best chain). However, this interface has some substantial drawbacks. Namely, the requirement that fork headers be passed in means that restarting with a new node that has no idea about a previous fork leaves us unable to replay the chain at all. Further, while when various listeners were initially written learning about each block disconnected in series seemed useful, but now we no longer rely on that anyway because the `Confirm` interface does not allow for it. Thus, here, we replace `Listen::block_disconnected` with a new `Listen::blocks_disconnected`, taking only information about the fork point/new best chain tip (in the form of its block hash and height) rather than information about previous fork blocks and only requiring a single call to complete multiple block disconnections during a reorg. We also swap to using a single `BestBlock` to describe the new chain tip, in anticipation of future extensions to `BestBlock`. This requires removing some assertions on block disconnection ordering, but because we now provide `lightning-block-sync` and expect users to use it when using the `Listen` interface, these assertions are much less critical.

`OnchainTxHandler` is an internal struct and doesn't implement `Listen`, but its still nice to have its API mirror the `Listen` API so that internal code all looks similar.

Now that the `Listen` interface allows blocks to be disconnected in batches rather than one at a time, we should test this. Here we add a new `ConnectStyle` for the functional test framework which tests doing so.

When calling `Channel::best_block_updated` we pass it the timestamp of the block we're connecting so that it can track the highest timestamp it has seen. However, in some cases, we don't actually have a timestamp to pass, which `Channel::best_block_updated` will happily ignore as it always takes the `max` of its existing value. Thus, we really should pass a `None` to ensure the API is understandable, which we do here.

`Listen` is somewhat quiet on high-level use and even requirements, which we document further here.

TheBlueMatt · 2025-09-02T13:50:21Z

Rebased with no further changes. Also opened #4042

ldk-reviews-bot · 2025-09-04T13:50:37Z

🔔 1st Reminder

Hey @jkczyz! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

TheBlueMatt · 2025-06-18T21:01:45Z

The Listen::block_disconnected method is nice in that listeners
learn about each block disconnected in series. Further, it included
the header of the block that is being disconnected to allow the
listeners to do some checking that the interface is being used
correctly (namely, asserting that the header's block hash matches
their current understanding of the best chain).

However, this interface has some substantial drawbacks. Namely, the
requirement that fork headers be passed in means that restarting
with a new node that has no idea about a previous fork leaves us
unable to replay the chain at all. Further, while when various
listeners were initially written learning about each block
disconnected in series seemed useful, but now we no longer rely on
that anyway because the Confirm interface does not allow for it.

Thus, here, we replace Listen::block_disconnected with a new
Listen::blocks_disconnected, taking only information about the
fork point/new best chain tip (in the form of its block hash and
height) rather than information about previous fork blocks and only
requiring a single call to complete multiple block disconnections
during a reorg.

This requires removing some assertions on block disconnection
ordering, but because we now provide lightning-block-sync and
expect users to use it when using the Listen interface, these
assertions are much less critical.

ldk-reviews-bot · 2025-06-18T21:01:47Z

👋 Thanks for assigning @tnull 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.

ldk-reviews-bot · 2025-06-19T00:07:26Z

👋 The first review has been submitted!

Do you think this PR is ready for a second reviewer? If so, click here to assign a second reviewer.

ldk-reviews-bot · 2025-06-19T16:11:23Z

✅ Added second reviewer: @joostjager

codecov · 2025-06-19T18:38:17Z

Codecov Report

❌ Patch coverage is 79.36508% with 26 lines in your changes missing coverage. Please review.
✅ Project coverage is 88.74%. Comparing base (86c6960) to head (a5b745a).
⚠️ Report is 38 commits behind head on main.

Files with missing lines	Patch %	Lines
lightning/src/chain/channelmonitor.rs	70.00%	6 Missing ⚠️
lightning/src/chain/mod.rs	0.00%	5 Missing ⚠️
lightning/src/util/sweep.rs	0.00%	5 Missing ⚠️
lightning-liquidity/src/manager.rs	0.00%	4 Missing ⚠️
lightning-block-sync/src/test_utils.rs	66.66%	3 Missing ⚠️
lightning-block-sync/src/init.rs	90.00%	1 Missing ⚠️
lightning/src/ln/channelmanager.rs	95.83%	1 Missing ⚠️
lightning/src/ln/functional_tests.rs	66.66%	1 Missing ⚠️

Additional details and impacted files

@@ Coverage Diff @@## main #3876 +/- ##
=======================================
Coverage 88.73% 88.74% =======================================
Files 176 176 Lines 129106 129102 -4 Branches 129106 129102 -4 =======================================
+ Hits 114567 114575 +8 + Misses 11937 11931 -6 + Partials 2602 2596 -6

Flag	Coverage Δ
fuzzing	`22.32% <13.18%> (+0.01%)`	⬆️
tests	`88.58% <79.36%> (+<0.01%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

ldk-reviews-bot · 2025-06-21T16:11:37Z

🔔 1st Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

tnull

Changes LGTM, but while we're here it would be good to add some details regarding the implicit assumptions on the Listen docs, and adding (back) some asserts/debug_asserts would be appreciated.

ldk-reviews-bot · 2025-06-30T00:00:45Z

🔔 1st Reminder

Hey @tnull @jkczyz! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-06-30T00:00:47Z

🔔 1st Reminder

Hey @tnull @jkczyz! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

tnull · 2025-06-30T11:56:15Z

+///
+/// Each block must be connected in chain order with one call to either
+/// [`Listen::block_connected`] or [`Listen::filtered_block_connected`]. If a call to the
+/// [`Filter`] interface was made during block processing and further transaction(s) from the same


Hmm, is this a new requirement? I imagine it's very hard to reliably implement this: keep track of all registered Txids/outputs, then match them on a block, apply the block, then check again if something new was registered, filter the block again, then potentially call once more. Also, why do we require it only here, but not on Confirm?

This has always been the case, just poorly documented. It is, indeed, not the case on Confirm (which doesn't require "blocks" to be connected in-order at all, though it does require all transactions to be topologically sorted).

tnull · 2025-06-30T12:03:50Z

 }
- self.chain_listener.block_disconnected(&header.header, header.height);
+ }
+ if let Some(block) = disconnected_blocks.last() {


If we're now happy to use the fork point, why are we keeping a Vec of all disconnected blocks around at all? Shouldn't we now be able to convert this to the new behavior entirely? Seems ChainDifference::common_ancestor would already provide what we need, no?

Its needed by the cache, which I didn't want to change in this PR - #3876 (comment)

tnull · 2025-06-30T12:13:59Z

- for header in disconnected_blocks.drain(..) {
+	fn disconnect_blocks(&mut self, disconnected_blocks: Vec<ValidatedBlockHeader>) {
+ for header in disconnected_blocks.iter() {
 if let Some(cached_header) = self.header_cache.block_disconnected(&header.block_hash) {


Should we change the Cache API accordingly?

We could, but it seems somewhat disjoint from this PR, given there's further work to do in lightning-block-sync anyway, so I kinda wanted to keep it as small as can be.

Mhh, might be good to document somewhere what steps you deem left before you'd consider the transition to this new approach complete. I guess all of them should land before the next release then, to not end up with a half-migrated codebase in the release?

I mean the API/stuff in lightning in in a perfectly fine state after this PR, and lightning-block-sync just deserves a bit of efficiency in dropping a vec and improving the cache afterwards. This PR obviously doesn't accomplish the goals that #3600 set out to, but is just a step towards it (the "complicated" step that requires making sure all the lightning-internal stuff isn't broken by changing the API).
AFAIU, to get to the point that bitcoind (and all) syncs support swapping to a new chain during a reorg and don't fetch a pile of redundant blocks we need to:
make BestBlock contain a list of 6(ish?) block hashes, not one
use that list in lightning-block-sync (and eventually lightning-transaction-sync) to do the sync without leaning on the cache
expand the runtime caching to cache partial chains across clients in the init sync logic
(eventually) ensure lightning-block-sync doesn't have any spare vecs or whatever lying around.

I still think it would make sense to open an issue for this larger refactoring you're planning, as there are connected aspects to discuss that don't really belong in this PR.
make BestBlock contain a list of 6(ish?) block hashes, not one
For example, how do we imagine this to work exactly, especially for the Confirm/lightning-transaction-sync case?
For Esplora, we currently retrieve the tip hash, retrieve the header and the block status (including the hight), before we call best_block_updated, which is already 3 costly RTTs. If we now would require to track the 6 most-recent hashes, we'd need to make at least 5 more subsequent calls (bringing this it at least 8 RTTs per sync round) to retrieve the hashes at [(height-5)..(height-1)]. But, given that these are individual calls, there is no way to tell if any reorg happened during some of these calls, so they are inherently race-y.
For Electrum, the results would be very similar for the polling client in its current form. Note we eventually want to switch the client to a streaming version making use of Electum's subscription model though, and requiring 'last 6 blocks' would probably require us to resort to costly polling again.
If we'd otherwise extend the client to start tracking more of the chain state (i.e., actually tracking a local chain 6-suffix) across rounds this would complicate the client logic quite a bit and make it even more susceptible to race conditions.
TLDR: I still maintain all of this would be/is resulting in a major refactor across our chain syncing crates and logic, and it would be great to discuss what we imagine to be involved and the corresponding trade-offs before we just jump into it heads first.

We can definitely make it optional (and only used for full-node-sync) if we think its a major issue. Of course the issue becomes that you cannot (even today) safely transition from an esplora/electrum-synced node to a full-chain-sync one, but addressing that really requires a substantial rework of how we think about chain sync, so maybe its not worth worrying about that.
Of course, storing the last 6 blocks is pretty trivial for a full-node-sync client, and the point is really just to expose the thing that the sync driver gave us, so its not like we'd use it in Listen/Confirm implementations.
My understanding is that this would address the restart-with-different-node case that #3600 wanted to address, even if its optional and just used by the full-node-syncing logic?

but addressing that really requires a substantial rework of how we think about chain sync, so maybe its not worth worrying about that.
Hmm, given that we even recently had users inquire whether they could switch chain sources at runtime, I do expect that we will need to tackle this eventually, as there will be users wanting to switch chain sources, and it's very unintuitive to either prohibit that, have it one-way, or even document the risks that might come from it.
Of course, storing the last 6 blocks is pretty trivial for a full-node-sync client, and the point is really just to expose the thing that the sync driver gave us, so its not like we'd use it in Listen/Confirm implementations.
So we would only do it when it's convenient, which means we could switch bitcoind nodes, but still not between chain sources?

Hmm, given that we even recently had users inquire whether they could switch chain sources at runtime, I do expect that we will need to tackle this eventually, as there will be users wanting to switch chain sources, and it's very unintuitive to either prohibit that, have it one-way, or even document the risks that might come from it.
Sure, I agree, hence why I suggested moving to storing several recent blocks rather than only one. However, as you note it might not be super practical, so we're kinda stuck.
I think, basically, if we did that plus required transactions_confirmed calls come before best_block_updated calls (which may we're doing anyway, cc #3867 (comment)) then moving from one chain source to another is totally fine, even at runtime (as long as you don't miss transactions).
So we would only do it when it's convenient, which means we could switch bitcoind nodes, but still not between chain sources?
I mean I'm not sure what else we can do? If its too impractical to do it on some chain sources we can't really make it required, and if its not available switching chain sources isn't going to be 100% reliable.

ldk-reviews-bot · 2025-07-02T00:01:36Z

🔔 2nd Reminder

Hey @jkczyz! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

tnull

rustfmt is unhappy right now

ldk-reviews-bot · 2025-07-05T00:01:06Z

🔔 3rd Reminder

Hey @jkczyz! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-07-07T00:01:51Z

🔔 4th Reminder

Hey @jkczyz! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-07-09T00:02:38Z

🔔 5th Reminder

Hey @jkczyz! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-07-12T00:00:34Z

🔔 6th Reminder

Hey @jkczyz! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

jkczyz

LGTM. Please squash.

TheBlueMatt · 2025-08-07T20:29:59Z

Squashed without further changes.

jkczyz

Linting CI failures look unrelated.

ldk-reviews-bot · 2025-08-23T15:02:08Z

🔔 1st Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-08-25T15:02:50Z

🔔 2nd Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-08-27T15:03:23Z

🔔 3rd Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-08-30T00:01:01Z

🔔 4th Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-09-01T00:01:44Z

🔔 5th Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

tnull

This unfortunately needs a small rebase by now.

tnull

ACK, after rebase. Please excuse the considerable delay here.

I still think it would be good to document in an issue what's 'left' post this PR, at least where we want to take things directionally. Maybe we can just transfer #3876 (comment) to an issue that can serve as a base for discussions?

The `Listen::block_disconnected` method is nice in that listeners learn about each block disconnected in series. Further, it included the header of the block that is being disconnected to allow the listeners to do some checking that the interface is being used correctly (namely, asserting that the header's block hash matches their current understanding of the best chain). However, this interface has some substantial drawbacks. Namely, the requirement that fork headers be passed in means that restarting with a new node that has no idea about a previous fork leaves us unable to replay the chain at all. Further, while when various listeners were initially written learning about each block disconnected in series seemed useful, but now we no longer rely on that anyway because the `Confirm` interface does not allow for it. Thus, here, we replace `Listen::block_disconnected` with a new `Listen::blocks_disconnected`, taking only information about the fork point/new best chain tip (in the form of its block hash and height) rather than information about previous fork blocks and only requiring a single call to complete multiple block disconnections during a reorg. We also swap to using a single `BestBlock` to describe the new chain tip, in anticipation of future extensions to `BestBlock`. This requires removing some assertions on block disconnection ordering, but because we now provide `lightning-block-sync` and expect users to use it when using the `Listen` interface, these assertions are much less critical.

`OnchainTxHandler` is an internal struct and doesn't implement `Listen`, but its still nice to have its API mirror the `Listen` API so that internal code all looks similar.

Now that the `Listen` interface allows blocks to be disconnected in batches rather than one at a time, we should test this. Here we add a new `ConnectStyle` for the functional test framework which tests doing so.

When calling `Channel::best_block_updated` we pass it the timestamp of the block we're connecting so that it can track the highest timestamp it has seen. However, in some cases, we don't actually have a timestamp to pass, which `Channel::best_block_updated` will happily ignore as it always takes the `max` of its existing value. Thus, we really should pass a `None` to ensure the API is understandable, which we do here.

`Listen` is somewhat quiet on high-level use and even requirements, which we document further here.

TheBlueMatt · 2025-09-02T13:50:21Z

Rebased with no further changes. Also opened #4042

ldk-reviews-bot · 2025-09-04T13:50:37Z

🔔 1st Reminder

Hey @jkczyz! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

TheBlueMatt · 2025-06-18T21:01:45Z

The Listen::block_disconnected method is nice in that listeners
learn about each block disconnected in series. Further, it included
the header of the block that is being disconnected to allow the
listeners to do some checking that the interface is being used
correctly (namely, asserting that the header's block hash matches
their current understanding of the best chain).

However, this interface has some substantial drawbacks. Namely, the
requirement that fork headers be passed in means that restarting
with a new node that has no idea about a previous fork leaves us
unable to replay the chain at all. Further, while when various
listeners were initially written learning about each block
disconnected in series seemed useful, but now we no longer rely on
that anyway because the Confirm interface does not allow for it.

Thus, here, we replace Listen::block_disconnected with a new
Listen::blocks_disconnected, taking only information about the
fork point/new best chain tip (in the form of its block hash and
height) rather than information about previous fork blocks and only
requiring a single call to complete multiple block disconnections
during a reorg.

This requires removing some assertions on block disconnection
ordering, but because we now provide lightning-block-sync and
expect users to use it when using the Listen interface, these
assertions are much less critical.

ldk-reviews-bot · 2025-06-18T21:01:47Z

👋 Thanks for assigning @tnull 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.

ldk-reviews-bot · 2025-06-19T00:07:26Z

👋 The first review has been submitted!

Do you think this PR is ready for a second reviewer? If so, click here to assign a second reviewer.

ldk-reviews-bot · 2025-06-19T16:11:23Z

✅ Added second reviewer: @joostjager

codecov · 2025-06-19T18:38:17Z

Codecov Report

❌ Patch coverage is 79.36508% with 26 lines in your changes missing coverage. Please review.
✅ Project coverage is 88.74%. Comparing base (86c6960) to head (a5b745a).
⚠️ Report is 38 commits behind head on main.

Files with missing lines	Patch %	Lines
lightning/src/chain/channelmonitor.rs	70.00%	6 Missing ⚠️
lightning/src/chain/mod.rs	0.00%	5 Missing ⚠️
lightning/src/util/sweep.rs	0.00%	5 Missing ⚠️
lightning-liquidity/src/manager.rs	0.00%	4 Missing ⚠️
lightning-block-sync/src/test_utils.rs	66.66%	3 Missing ⚠️
lightning-block-sync/src/init.rs	90.00%	1 Missing ⚠️
lightning/src/ln/channelmanager.rs	95.83%	1 Missing ⚠️
lightning/src/ln/functional_tests.rs	66.66%	1 Missing ⚠️

Additional details and impacted files

@@ Coverage Diff @@## main #3876 +/- ##
=======================================
Coverage 88.73% 88.74% =======================================
Files 176 176 Lines 129106 129102 -4 Branches 129106 129102 -4 =======================================
+ Hits 114567 114575 +8 + Misses 11937 11931 -6 + Partials 2602 2596 -6

Flag	Coverage Δ
fuzzing	`22.32% <13.18%> (+0.01%)`	⬆️
tests	`88.58% <79.36%> (+<0.01%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

ldk-reviews-bot · 2025-06-21T16:11:37Z

🔔 1st Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

tnull

Changes LGTM, but while we're here it would be good to add some details regarding the implicit assumptions on the Listen docs, and adding (back) some asserts/debug_asserts would be appreciated.

ldk-reviews-bot · 2025-06-30T00:00:45Z

🔔 1st Reminder

Hey @tnull @jkczyz! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-06-30T00:00:47Z

🔔 1st Reminder

Hey @tnull @jkczyz! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

tnull · 2025-06-30T11:56:15Z

+///
+/// Each block must be connected in chain order with one call to either
+/// [`Listen::block_connected`] or [`Listen::filtered_block_connected`]. If a call to the
+/// [`Filter`] interface was made during block processing and further transaction(s) from the same


Hmm, is this a new requirement? I imagine it's very hard to reliably implement this: keep track of all registered Txids/outputs, then match them on a block, apply the block, then check again if something new was registered, filter the block again, then potentially call once more. Also, why do we require it only here, but not on Confirm?

This has always been the case, just poorly documented. It is, indeed, not the case on Confirm (which doesn't require "blocks" to be connected in-order at all, though it does require all transactions to be topologically sorted).

tnull · 2025-06-30T12:03:50Z

 }
- self.chain_listener.block_disconnected(&header.header, header.height);
+ }
+ if let Some(block) = disconnected_blocks.last() {


If we're now happy to use the fork point, why are we keeping a Vec of all disconnected blocks around at all? Shouldn't we now be able to convert this to the new behavior entirely? Seems ChainDifference::common_ancestor would already provide what we need, no?

Its needed by the cache, which I didn't want to change in this PR - #3876 (comment)

tnull · 2025-06-30T12:13:59Z

- for header in disconnected_blocks.drain(..) {
+	fn disconnect_blocks(&mut self, disconnected_blocks: Vec<ValidatedBlockHeader>) {
+ for header in disconnected_blocks.iter() {
 if let Some(cached_header) = self.header_cache.block_disconnected(&header.block_hash) {


Should we change the Cache API accordingly?

We could, but it seems somewhat disjoint from this PR, given there's further work to do in lightning-block-sync anyway, so I kinda wanted to keep it as small as can be.

Mhh, might be good to document somewhere what steps you deem left before you'd consider the transition to this new approach complete. I guess all of them should land before the next release then, to not end up with a half-migrated codebase in the release?

I mean the API/stuff in lightning in in a perfectly fine state after this PR, and lightning-block-sync just deserves a bit of efficiency in dropping a vec and improving the cache afterwards. This PR obviously doesn't accomplish the goals that #3600 set out to, but is just a step towards it (the "complicated" step that requires making sure all the lightning-internal stuff isn't broken by changing the API).
AFAIU, to get to the point that bitcoind (and all) syncs support swapping to a new chain during a reorg and don't fetch a pile of redundant blocks we need to:
make BestBlock contain a list of 6(ish?) block hashes, not one
use that list in lightning-block-sync (and eventually lightning-transaction-sync) to do the sync without leaning on the cache
expand the runtime caching to cache partial chains across clients in the init sync logic
(eventually) ensure lightning-block-sync doesn't have any spare vecs or whatever lying around.

I still think it would make sense to open an issue for this larger refactoring you're planning, as there are connected aspects to discuss that don't really belong in this PR.
make BestBlock contain a list of 6(ish?) block hashes, not one
For example, how do we imagine this to work exactly, especially for the Confirm/lightning-transaction-sync case?
For Esplora, we currently retrieve the tip hash, retrieve the header and the block status (including the hight), before we call best_block_updated, which is already 3 costly RTTs. If we now would require to track the 6 most-recent hashes, we'd need to make at least 5 more subsequent calls (bringing this it at least 8 RTTs per sync round) to retrieve the hashes at [(height-5)..(height-1)]. But, given that these are individual calls, there is no way to tell if any reorg happened during some of these calls, so they are inherently race-y.
For Electrum, the results would be very similar for the polling client in its current form. Note we eventually want to switch the client to a streaming version making use of Electum's subscription model though, and requiring 'last 6 blocks' would probably require us to resort to costly polling again.
If we'd otherwise extend the client to start tracking more of the chain state (i.e., actually tracking a local chain 6-suffix) across rounds this would complicate the client logic quite a bit and make it even more susceptible to race conditions.
TLDR: I still maintain all of this would be/is resulting in a major refactor across our chain syncing crates and logic, and it would be great to discuss what we imagine to be involved and the corresponding trade-offs before we just jump into it heads first.

We can definitely make it optional (and only used for full-node-sync) if we think its a major issue. Of course the issue becomes that you cannot (even today) safely transition from an esplora/electrum-synced node to a full-chain-sync one, but addressing that really requires a substantial rework of how we think about chain sync, so maybe its not worth worrying about that.
Of course, storing the last 6 blocks is pretty trivial for a full-node-sync client, and the point is really just to expose the thing that the sync driver gave us, so its not like we'd use it in Listen/Confirm implementations.
My understanding is that this would address the restart-with-different-node case that #3600 wanted to address, even if its optional and just used by the full-node-syncing logic?

but addressing that really requires a substantial rework of how we think about chain sync, so maybe its not worth worrying about that.
Hmm, given that we even recently had users inquire whether they could switch chain sources at runtime, I do expect that we will need to tackle this eventually, as there will be users wanting to switch chain sources, and it's very unintuitive to either prohibit that, have it one-way, or even document the risks that might come from it.
Of course, storing the last 6 blocks is pretty trivial for a full-node-sync client, and the point is really just to expose the thing that the sync driver gave us, so its not like we'd use it in Listen/Confirm implementations.
So we would only do it when it's convenient, which means we could switch bitcoind nodes, but still not between chain sources?

Hmm, given that we even recently had users inquire whether they could switch chain sources at runtime, I do expect that we will need to tackle this eventually, as there will be users wanting to switch chain sources, and it's very unintuitive to either prohibit that, have it one-way, or even document the risks that might come from it.
Sure, I agree, hence why I suggested moving to storing several recent blocks rather than only one. However, as you note it might not be super practical, so we're kinda stuck.
I think, basically, if we did that plus required transactions_confirmed calls come before best_block_updated calls (which may we're doing anyway, cc #3867 (comment)) then moving from one chain source to another is totally fine, even at runtime (as long as you don't miss transactions).
So we would only do it when it's convenient, which means we could switch bitcoind nodes, but still not between chain sources?
I mean I'm not sure what else we can do? If its too impractical to do it on some chain sources we can't really make it required, and if its not available switching chain sources isn't going to be 100% reliable.

ldk-reviews-bot · 2025-07-02T00:01:36Z

🔔 2nd Reminder

Hey @jkczyz! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

tnull

rustfmt is unhappy right now

ldk-reviews-bot · 2025-07-05T00:01:06Z

🔔 3rd Reminder

Hey @jkczyz! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-07-07T00:01:51Z

🔔 4th Reminder

Hey @jkczyz! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-07-09T00:02:38Z

🔔 5th Reminder

Hey @jkczyz! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-07-12T00:00:34Z

🔔 6th Reminder

Hey @jkczyz! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

jkczyz

LGTM. Please squash.

TheBlueMatt · 2025-08-07T20:29:59Z

Squashed without further changes.

jkczyz

Linting CI failures look unrelated.

ldk-reviews-bot · 2025-08-23T15:02:08Z

🔔 1st Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-08-25T15:02:50Z

🔔 2nd Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-08-27T15:03:23Z

🔔 3rd Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-08-30T00:01:01Z

🔔 4th Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-09-01T00:01:44Z

🔔 5th Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

tnull

This unfortunately needs a small rebase by now.

tnull

ACK, after rebase. Please excuse the considerable delay here.

I still think it would be good to document in an issue what's 'left' post this PR, at least where we want to take things directionally. Maybe we can just transfer #3876 (comment) to an issue that can serve as a base for discussions?

The `Listen::block_disconnected` method is nice in that listeners learn about each block disconnected in series. Further, it included the header of the block that is being disconnected to allow the listeners to do some checking that the interface is being used correctly (namely, asserting that the header's block hash matches their current understanding of the best chain). However, this interface has some substantial drawbacks. Namely, the requirement that fork headers be passed in means that restarting with a new node that has no idea about a previous fork leaves us unable to replay the chain at all. Further, while when various listeners were initially written learning about each block disconnected in series seemed useful, but now we no longer rely on that anyway because the `Confirm` interface does not allow for it. Thus, here, we replace `Listen::block_disconnected` with a new `Listen::blocks_disconnected`, taking only information about the fork point/new best chain tip (in the form of its block hash and height) rather than information about previous fork blocks and only requiring a single call to complete multiple block disconnections during a reorg. We also swap to using a single `BestBlock` to describe the new chain tip, in anticipation of future extensions to `BestBlock`. This requires removing some assertions on block disconnection ordering, but because we now provide `lightning-block-sync` and expect users to use it when using the `Listen` interface, these assertions are much less critical.

`OnchainTxHandler` is an internal struct and doesn't implement `Listen`, but its still nice to have its API mirror the `Listen` API so that internal code all looks similar.

Now that the `Listen` interface allows blocks to be disconnected in batches rather than one at a time, we should test this. Here we add a new `ConnectStyle` for the functional test framework which tests doing so.

When calling `Channel::best_block_updated` we pass it the timestamp of the block we're connecting so that it can track the highest timestamp it has seen. However, in some cases, we don't actually have a timestamp to pass, which `Channel::best_block_updated` will happily ignore as it always takes the `max` of its existing value. Thus, we really should pass a `None` to ensure the API is understandable, which we do here.

`Listen` is somewhat quiet on high-level use and even requirements, which we document further here.

TheBlueMatt · 2025-09-02T13:50:21Z

Rebased with no further changes. Also opened #4042

ldk-reviews-bot · 2025-09-04T13:50:37Z

🔔 1st Reminder

Hey @jkczyz! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot requested a review from jkczyz June 18, 2025 21:12

TheBlueMatt force-pushed the 2025-06-disconnect-less-info branch 2 times, most recently from 5942c8b to ddc0400Compare June 18, 2025 21:26

TheBlueMatt mentioned this pull request Jun 18, 2025
lightning-block-sync: Implement serialization logic for header Cache types #3600
Closed

jkczyz reviewed Jun 19, 2025
View reviewed changes

Comment threadlightning/src/ln/channelmanager.rs Outdated

ldk-reviews-bot requested a review from joostjager June 19, 2025 16:11

tnull requested review from tnull and removed request for joostjager June 19, 2025 16:11

TheBlueMatt force-pushed the 2025-06-disconnect-less-info branch from b06cbd4 to a54159cCompare June 19, 2025 18:47

jkczyz previously approved these changes Jun 20, 2025
View reviewed changes

tnull reviewed Jun 23, 2025
View reviewed changes

Comment threadlightning/src/chain/mod.rs
Comment threadlightning/src/util/sweep.rs Outdated

TheBlueMatt dismissed jkczyz’s stale review via 29d3577June 25, 2025 18:48

jkczyz reviewed Jun 26, 2025
View reviewed changes

Comment threadlightning/src/chain/mod.rs Outdated
Comment threadlightning/src/chain/mod.rs Outdated
Comment threadlightning/src/chain/mod.rs Outdated
Comment threadlightning/src/chain/mod.rs Outdated

TheBlueMatt requested review from jkczyz and tnull June 27, 2025 21:01

tnull reviewed Jun 30, 2025
View reviewed changes

tnull reviewed Jul 2, 2025
View reviewed changes

TheBlueMatt force-pushed the 2025-06-disconnect-less-info branch from ef73b0a to a6985ebCompare July 2, 2025 22:37

jkczyz reviewed Aug 7, 2025
View reviewed changes

TheBlueMatt force-pushed the 2025-06-disconnect-less-info branch from bf41b15 to c78b08bCompare August 7, 2025 20:29

jkczyz previously approved these changes Aug 7, 2025
View reviewed changes

TheBlueMatt dismissed jkczyz’s stale review via 7b590eeAugust 21, 2025 14:57

TheBlueMatt force-pushed the 2025-06-disconnect-less-info branch from c78b08b to 7b590eeCompare August 21, 2025 14:57

TheBlueMatt requested review from tnull and removed request for tnull August 21, 2025 15:01

tnull reviewed Sep 2, 2025
View reviewed changes

tnull previously approved these changes Sep 2, 2025
View reviewed changes

TheBlueMatt added 5 commits September 2, 2025 13:35

Use similar blocks_disconnected semantics in OnchainTxHandler
2d3aaa5
`OnchainTxHandler` is an internal struct and doesn't implement `Listen`, but its still nice to have its API mirror the `Listen` API so that internal code all looks similar.

Add more robust functional test of Listen::blocks_disconnected
fea0bee
Now that the `Listen` interface allows blocks to be disconnected in batches rather than one at a time, we should test this. Here we add a new `ConnectStyle` for the functional test framework which tests doing so.

Add further additional documentation to Listen
a5b745a
`Listen` is somewhat quiet on high-level use and even requirements, which we document further here.

TheBlueMatt dismissed tnull’s stale review via a5b745aSeptember 2, 2025 13:38

TheBlueMatt force-pushed the 2025-06-disconnect-less-info branch from 7b590ee to a5b745aCompare September 2, 2025 13:38

TheBlueMatt mentioned this pull request Sep 2, 2025
Support switching block sync backends #4042
Open

TheBlueMatt requested review from jkczyz and tnull September 2, 2025 13:50

tnull approved these changes Sep 2, 2025
View reviewed changes

jkczyz approved these changes Sep 5, 2025
View reviewed changes

jkczyz merged commit eb300b6 into lightningdevkit:mainSep 5, 2025
25 checks passed