bitcoindevkit / bdk / 23007782720

78%

push

github

Merge bitcoindevkit/bdk#2135: docs: Document TxUpdate temporal context requirements (supports Wizardsardine audit recommendation)

<a class=hub.com/bitcoindevkit/bdk/commit/b69d7bfce32d20a5849052a2e61bf8d8bff813a6">b69d7bfce docs: document TxUpdate temporal context requirements (Rafael Turon)

Pull request description:

  Closes #2133

  This introduces clear temporal context **documentation** to the `TxUpdate` struct, explicitly stating that entries must have either `anchors` or `seen_ats` to be considered canonical and contribute to wallet balances.

  It also explicitly documents the `seen_ats` HashSet signature to prevent usage errors when writing custom chain sources.

  This fulfills the recommendation outlined in the Wizardsardine BDK Audit Report (Q4 2024).

  ### Description
  This primarily affects developers building **custom chain sources** — anyone constructing `Update` structs outside of `bdk_electrum`/`bdk_esplora`/`bdk_bitcoind_rpc`.
  As the ecosystem grows (streaming Electrum, Nostr relay sync, compact block filters, custom backends), more developers will encounter this undocumented contract.

  ### What I Changed

  *1. Doc comment on `TxUpdate` struct*
  * **`anchors` or `seen_ats`** are stored in the graph but do not affect the balance.
  * **`seen_ats` collection type**: `TxUpdate::seen_ats` is a `BTreeSet<(Txid, u64)>`, requiring `.insert((txid, timestamp))`.

  *2. Doc comment on `Wallet::apply_update()`*
  * **TxGraph `apply_update`**: transactions without temporal context note.
  * **IndexedTxGraph `apply_update`**: transactions without temporal context note.

  ### Impact
  This is just a documentation fix - no code changes, no breaking changes.

  ### Checklists

  #### All Submissions:

  * [x] I followed the [contribution guidelines](https://github.com/bitcoindevkit/bdk/blob/master/CONTRIBUTING.md)

ACKs for top commit:
  evanlinjin:
    ACK b69d7bfce32d20a5849052a2e61bf8d8bff813a6

Tree-SHA512: 669fbd2c2cef4146d6719e2d0c26b959253ce987eebf7373... (continued)

376 of 510 branches covered (73.73%)

Branch coverage included in aggregate %.

1 of 1 new or added line in 1 file covered. (100.0%)

4293 of 5465 relevant lines covered (78.55%)

3147.4 hits per line