bitcoindevkit / bitcoindevkit/bdk
Document trust requirements for floating-prevout accounting
- 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
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