rust-lightning

Document that `Future` callbacks are not reentrant-safe

Claude was complaining about this, and it seems worth documenting,
but not worth (and kinda hard to) fix.

Fix misleading comment on counterparty_commitment_txn_on_chain insert

The comment claimed this insert "isn't useful yet" and was only a
safety measure for a watchtower race. In practice it is also used by
provide_payment_preimage to look up the commitment number when a
preimage arrives after the counterparty commitment tx is confirmed.

AI tools were used in preparing this commit.

Ensure minimum RBF feerate satisfies BIP125

The spec's 25/24 multiplier doesn't always satisfy BIP125's relay
requirement of an absolute fee increase at low feerates, while a flat
+25 sat/kwu increment falls below the spec's 25/24 rule above 600
sat/kwu. Use max(prev + 25, ceil(prev * 25/24)) for our own RBFs to
satisfy both constraints, while still accepting the bare 25/24 rule
from counterparties.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

util: add default_value_vec for defaults without LengthReadable

Right now, use of `default_value` requires that the struct implements
`LengthReadable` itself. When trying to use `default_value` outside of
LDK for `Vec<T>`, your code will run into the orphan rule because it
does not own the trait `LengthReadable` or the type `Vec`.

There are various ugly workarounds for this (like using `custom`), but
wanting to persist a vec with a default value seems like a common enough
use case to justify the change.

Include recent blocks in the `synchronize_listeners`-returned cache

When `synchronize_listeners` runs, it returns a cache of the
headers it needed when doing chain difference-finding. This allows
us to ensure that when we start running normally we have all the
recent headers in case we need them to reorg.

Sadly, in some cases it was returning a mostly-empty cache.
Because it was only being filled during block difference
reconciliation it would only get a block around each listener's
fork point. Worse, because we were calling `disconnect_blocks` with
the cache the cache would assume we were reorging against the main
chain and drop blocks we actually want.

Instead, we avoid dropping blocks on `disconnect_blocks` calls and
ensure we always add connected blocks to the cache.

Make the `Cache` trait priv, just use `UnboundedCache` publicly

In the previous commit, we moved to relying on
`BestBlock::previous_blocks` to find the fork point in
`lightning-block-sync`'s `init::synchronize_listeners`. Here we now
drop the `Cache` parameter as we no longer rely on it.

Because we now have no reason to want a persistent `Cache`, we
remove the trait from the public interface. However, to keep
disconnections reliable we return the `UnboundedCache` we built up
during initial sync from `init::synchronize_listeners` which we
expect developers to pass to `SpvClient::new`.

Use the header cache across listeners during initial disconnect

In `lightning-blocksync::init::synchronize_listeners`, we may have
many listeners we want to do a chain diff on. When doing so, we
should make sure we utilize our header cache, rather than querying
our chain source for every header we need for each listener.

Here we do so, inserting into the cache as we do chain diffs.

On my node with a bitcoind on localhost, this brings the
calculate-differences step of `init::synchronize_listeners` from
~500ms to under 150ms.

Return `BestBlock` when deserializing chain-synced structs

The deserialization of `ChannelMonitor`, `ChannelManager`, and
`OutputSweeper` is implemented for a `(BlockHash, ...)` pair rather
than on the object itself. This ensures developers are pushed to
think about initial chain sync after deserialization and provides
the latest chain sync state conviniently at deserialization-time.

In the previous commit we started storing additional recent block
hashes in `BestBlock` for use during initial sync to ensure we can
handle reorgs while offline if the chain source loses the
reorged-out blocks. Here, we move the deserialization routines to
be on a `(BestBlock, ...)` pair instead of `(BlockHash, ...)`,
providing access to those recent block hashes at
deserialization-time.

Silence "elided lifetime has a name" warnings in no-std locking

Add `async_poll.rs` to `lightning-block-sync`

In the next commit we'll fetch blocks during initial connection
in parallel, which requires a multi-future poller. Here we add a
symlink to the existing `lightning` `async_poll.rs` file, making it
available in `lightning-block-sync`

Replace `Cache::block_disconnected` with `blocks_disconnected`

In 403dc1a48bb71ae794f6883ae0b760aad44cda39 we converted the
`Listen` disconnect semantics to only pass the fork point, rather
than each block being disconnected. We did not, however, update the
semantics of `lightning-block-sync`'s `Cache` to reduce patch size.

Here we go ahead and do so, dropping
`ChainDifference::disconnected_blocks` as well as its no longer
needed.

Update BestBlock to store ANTI_REORG_DELAY * 2 recent block hashes

On restart, LDK expects the chain to be replayed starting from
where it was when objects were last serialized. This is fine in the
normal case, but if there was a reorg and the node which we were
syncing from either resynced or was changed, the last block that we
were synced as of might no longer be available. As a result, it
becomes impossible to figure out where the fork point is, and thus
to replay the chain.

Luckily, changing the block source during a reorg isn't exactly
common, but we shouldn't end up with a bricked node.

To address this, `lightning-block-sync` allows the user to pass in
`Cache` which can be used to cache recent blocks and thus allow for
reorg handling in this case. However, serialization for, and a
reasonable default implementation of a `Cache` was never built.

Instead, here, we start taking a different approach. To avoid
developers having to persist yet another object, we move
`BestBlock` to storing some number of recent block hashes. This
allows us to find the fork point with just the serialized state.

In conjunction with 403dc1a48bb71ae794f6883ae0b760aad44cda39 (which
allows us to disconnect blocks without having the stored header),
this should allow us to replay chain state after a reorg even if
we no longer have access to the top few blocks of the old chain
tip.

While we only really need to store `ANTI_REORG_DELAY` blocks (as we
generally assume that any deeper reorg won't happen and thus we
don't guarantee we handle it correctly), its nice to store a few
more to be able to handle more than a six block reorg. While other
parts of the codebase may not be entirely robust against such a
reorg if the transactions confirmed change out from under us, its
entirely possible (and, indeed, common) for reorgs to contain
nearly identical transactions.

Pass a `BestBlock` to `init::synchronize_listeners`

On restart, LDK expects the chain to be replayed starting from
where it was when objects were last serialized. This is fine in the
normal case, but if there was a reorg and the node which we were
syncing from either resynced or was changed, the last block that we
were synced as of might no longer be available. As a result, it
becomes impossible to figure out where the fork point is, and thus
to replay the chain.

Luckily, changing the block source during a reorg isn't exactly
common, but we shouldn't end up with a bricked node.

To address this, `lightning-block-sync` allows the user to pass in
`Cache` which can be used to cache recent blocks and thus allow for
reorg handling in this case. However, serialization for, and a
reasonable default implementation of a `Cache` was never built.

Instead, here, we start taking a different approach. To avoid
developers having to persist yet another object, we move
`BestBlock` to storing some number of recent block hashes. This
allows us to find the fork point with just the serialized state.

In a previous commit, we moved deserialization of various structs
to return the `BestBlock` rather than a `BlockHash`. Here we move
to actually using it, taking a `BestBlock` in place of `BlockHash`
to `init::synchronize_listeners` and walking the `previous_blocks`
list to find the fork point rather than relying on the `Cache`.

Fetch blocks from source in parallel during initial sync

In `init::synchronize_listeners` we may end up spending a decent
chunk of our time just fetching block data. Here we parallelize
that step across up to 36 blocks at a time.

On my node with bitcoind on localhost, the impact of this is
somewhat muted by block deserialization being the bulk of the work,
however a networked bitcoind would likely change that. Even still,
fetching a batch of 36 blocks in parallel happens on my node in
~615 ms vs ~815ms in serial.

Make `UnboundedCache` bounded

In the previous commit we moved to hard-coding `UnboundedCache` in
the `lightning-block-sync` interface. This is great, except that
its an unbounded cache that can use arbitrary amounts of memory
(though never really all that much - its just headers that come in
while we're running).

Here we simply limit the size, and while we're at it give it a more
generic `HeaderCache` name.

Drop the `Cache` trait entirely

Now that `Cache` is crate-private, there's not actually any reason
to have it at all. In a later commit we'll have to reach into its
internals a bit, but all within the `lightning-block-sync` crate,
so having a trait indirection is somewhat useless.

Consolidate all the pub aync utils to `native_async`

Fix flakiness in `test_tor_connect`

Fixes #4519

Remove dead string search in fuzz SearchingOutput

The searched-for log message ("Outbound update_fee HTLC buffer
overflow") no longer exists in the lightning crate, so the
from_utf8 + contains check on every log line was pure waste.

AI tools were used in preparing this commit.

Skip log formatting entirely for DevNull output

Even though DevNull discards the bytes, the formatting work
(SubstringFormatter, fmt::write, from_utf8) was still being done
on every log call. Short-circuit in TestLogger::log via a TypeId
check, which monomorphization resolves at compile time.

AI tools were used in preparing this commit.

fuzz: fix coverage report to include library crates

Since cargo-llvm-cov 0.7.0, only workspace members are instrumented
by default. Since the fuzz crate is a standalone workspace, library
crates like lightning were not instrumented, and the coverage report
was empty.

Add --dep-coverage to instrument the library path dependencies.

This alone is not sufficient for the report: --dep-coverage's report
filtering only supports crates.io deps, not path deps (per a TODO in
cargo-llvm-cov source). Add --no-default-ignore-filename-regex to
include all instrumented code, then use a custom --ignore-filename-regex
to exclude unwanted paths (cargo registry, rustup toolchains, fuzz
harness).

AI tools were used in preparing this commit.

types: fix zero conf feature missing `clear_zero_conf`

Switch 0FC to production feature bit

Use inline format variables in channel/channelmanager format strings

Convert format string arguments to inline `{var}` captures where
the argument is a simple identifier (variable or constant). Field
accesses, method calls, and expressions remain as positional args.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Create better helper functions in `tx_builder`

Reduce line count and indentation