Add populate_anchor_cache method to bdk

[Her-Code]

This PR addresses #1982
It introduces functionality to populate the anchor cache, improving how BDK handles stateful or performance-critical anchor data.

Changes

• Add populate_anchor_cache method to BdkElectrumClient in bdk-core
• Improves sync speed by caching anchor transactions in advance
• Enables pre-caching of anchor transactions to reduce redundant network calls

Follow-up work will extend this functionality to bdk-wallet.

[evanlinjin]

Thank you for approaching this.

The ticket was very brief and was not specific enough - sorry about that. Let me clarify what we are looking for.

• We need a way to populate the anchor cache with pre-existing data. For example, from our receiving structures (bdk_wallet::Wallet, bdk_chain::TxGraph+bdk_chain::LocalChain).
• This is similar to the BdkElectrumClient::populate_tx_cache method that we already have (can draw inspiration from that).

In other words, populate_anchor_cache should NOT be handling IO (i.e. fetching data from an Electrum server) and should only use data that is provided directly to it.

[LagginTimes]

Thanks for the contribution! A couple of things to take care of:

1. Rebase on the current master to bring it up to date with the latest changes.
2. Run cargo clippy and cargo +nightly fmt so it passes linting and formatting checks.

[evanlinjin]

You are getting the block hash from the anchor, so the API doesn't need to take in the block hash separately.

[evanlinjin]

Only introduce extension traits out of necessity. Is there another method on TxGraph that you can use? If not, you can introduce a method on TxGraph directly.

[evanlinjin]

I think you inserted anchors in the middle of the doc comments of all_txouts.

[evanlinjin]

Please double check and try running the code you have written (or the code written for you).

Comments need to capture non-obvious intent or constraints, not restate what is obvious by looking at the code.

[evanlinjin]

Have you tried running this? Since we lock graph again on line 143, wouldn't this result in a deadlock?

[evanlinjin]

Some of these comments are explaining very obvious things in a way that doesn’t add much beyond reading the code itself.

[evanlinjin]

Also, how about we populate the anchor & tx cache under a single lock of graph?

[evanlinjin]

Instead of introducing this anchors method, how about we make use of the all_anchors method we have already?

I propose changing BdkElectrumClient::populate_anchor_cache to the following:

    /// Insert anchors into the anchor cache so that they don’t have to be fetched again from
    /// Electrum. Typically used to pre-populate the cache from an existing `TxGraph`.
    pub fn populate_anchor_cache(
        &self,
        tx_anchors: impl IntoIterator<Item = (Txid, impl IntoIterator<Item = ConfirmationBlockTime>)>,
    ) {
        let mut cache = self.anchor_cache.lock().unwrap();
        for (txid, anchors) in tx_anchors {
            for anchor in anchors {
                cache.insert((txid, anchor.block_id.hash), anchor);
            }
        }
    }

Using the API will look like this:

        let graph = graph.lock().unwrap();
        client.populate_anchor_cache(graph.graph().all_anchors().clone());

[evanlinjin]

@Her-Code Thanks for taking this on! It would be really helpful to have this in soon. Do you think you’d be able to complete it by the end of the week, or would you need more time?

[Her-Code]

I've implemented the anchor caching using all_anchors() as you suggested. I noticed the original implementation could potentially create nested locks:

        let graph = graph.lock().unwrap();
        client.populate_anchor_cache(graph.graph().all_anchors().clone());

so I added explicit scoping with curly braces to ensure proper lock management:

{
        // Lock graph mutex - released automatically at scope end
        // Cache all anchors while holding the lock
        let graph = graph.lock().unwrap();
        client.populate_anchor_cache(graph.graph().all_anchors().clone());
}

[evanlinjin]

ACK 191bdb1