bitcoindevkit / bitcoindevkit/bdk

Document trust requirements for floating-prevout accounting

Open Beginner friendly
#2,287 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**

`SpkTxOutIndex::scan_txout`, `sent_and_received`, and `net_value` do not document that accounting trusts supplied floating prevouts. An incorrect value with a tracked script is used directly, even when the parent transaction is unavailable. The first insertion is also included in `IndexedTxGraph`'s changeset, so restoring that state retains the value.

`TxGraph::calculate_fee` explicitly says to insert only values the caller trusts; the indexer accounting methods lack the equivalent qualification. Merely having scanned a prevout does not establish its correctness.

This issue was found by AI.

**To Reproduce**

1. Track a script in `SpkTxOutIndex` and scan a floating prevout claiming `1_000_000` sat to that script, without its parent transaction.
2. Call `sent_and_received` and `net_value` on a transaction spending that outpoint and returning `4_000` sat to the tracked script.
3. The reported sent amount is `1_000_000` sat and net value is `-996_000` sat, based solely on the supplied claim. The method docs mention prior scanning, but not this trust requirement.

**Expected behavior**

The indexer API documentation should clearly describe the trust assumptions behind floating-prevout accounting, including that scanning or persisting a value does not verify it.

Contributor guide

Open the contributing guide

Research direction

Start with the documentation for SpkTxOutIndex::scan_txout, sent_and_received, and net_value, then compare it with TxGraph::calculate_fee. Document that floating-prevout values are caller-supplied trust assumptions, and that scanning or persisting them does not verify correctness; done means the accounting API docs state this clearly.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
84/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.