bitcoindevkit / bitcoindevkit/bdk

Document eviction handling for unknown txids in apply_update

Open
#2,289 0 comments 0 reactions 0 assignees View on GitHub
documentation
Dominant language
Rust
Stars
1.1k
Forks
483
Avg merge
20d 3h
Merged PRs (30d)
3

Description

**Describe the bug**

`TxGraph::apply_update` records `evicted_ats` for unknown txids, whereas `batch_insert_relevant_evicted_at` ignores them. This distinction is not explained in `apply_update` or `TxUpdate::evicted_ats` documentation.

With composed or hand-built updates, an eviction can therefore precede the transaction itself. If that transaction later arrives with `seen_at <= evicted_at`, it is immediately considered evicted and excluded from the unconfirmed canonical view. A newer sighting revives it. The eviction is also retained in the graph's changeset.

This issue was found by AI.

**To Reproduce**

1. Start with two empty `TxGraph`s and a transaction `T` not yet inserted in either.
2. On the first graph, apply a `TxUpdate` containing only `(T.compute_txid(), 200)` in `evicted_ats`. Its changeset records `last_evicted = 200`.
3. On the second graph, pass the same pair to `batch_insert_relevant_evicted_at`. Its changeset is empty.
4. Insert `T` into both graphs with `seen_at = 100`. `get_tx_node(T.compute_txid()).unwrap().is_evicted()` is `true` only in the first graph.
5. Record `seen_at = 201` in the first graph; it is no longer evicted.

**Expected behavior**

The update API should clearly document how evictions for unknown txids affect later transaction insertion, persistence, and canonicalization, and how this differs from the filtered batch API.

Contributor guide

Open the contributing guide

Research direction

Start by locating TxGraph::apply_update and the documentation for TxUpdate::evicted_ats, then compare their behavior with batch_insert_relevant_evicted_at using the reproduction steps. Update the API documentation to explain unknown-txid evictions, later insertion, persistence, canonicalization, and the difference from the filtered batch API; done means the documented behavior matches the example.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
74/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.