bitcoindevkit / bitcoindevkit/bdk
Document eviction handling for unknown txids in apply_update
- 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
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