docs(core): document hashbrown feature's fixed-key hashing

With the `hashbrown` feature, this crate's `HashMap`/`HashSet` are
hashbrown's (on `std` builds too), which hash with `ahash`. Unless
`ahash`'s `runtime-rng` or `compile-time-rng` feature is enabled
somewhere in the dependency graph, `ahash` uses fixed, publicly known
keys, so a malicious chain source can craft colliding txids and make
`TxGraph` insertion quadratic.

Document this, and how to randomize the keys by depending on `ahash`
directly with one of those features.

Fixes #2342

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

diff --git a/crates/core/src/lib.rs b/crates/core/src/lib.rs
index 3d9b47aa5f0ad19a85e1bc6282006b2f53229b4c..247cc915a322bdb6e9148284139902208f7daaa8 100644 (file)
--- a/crates/core/src/lib.rs
+++ b/crates/core/src/lib.rs
@@ -1,4 +1,17 @@
 //! This crate is a collection of core structures for [Bitcoin Dev Kit].
+//!
+//! # Features
+//!
+//! - `std` (default): use the standard library, including its `HashMap`/`HashSet`. Without it,
+//!   this crate is `no_std` and uses `alloc`'s `BTreeMap`/`BTreeSet` instead.
+//! - `serde`: implement `serde::Serialize`/`serde::Deserialize` for this crate's types.
+//! - `hashbrown`: use [`hashbrown`](https://docs.rs/hashbrown)'s `HashMap`/`HashSet` for this
+//!   crate's hash collections (e.g. `bdk_chain`'s `TxGraph`), on `std` builds too. These hash
+//!   with `ahash` using fixed, publicly known keys unless `ahash`'s `runtime-rng` or
+//!   `compile-time-rng` feature is enabled somewhere in the dependency graph. With fixed keys, a
+//!   malicious chain source can send transactions crafted to collide, making insertion
+//!   quadratic. To randomize the keys, depend on
+//!   `ahash = { version = "0.8", features = ["runtime-rng"] }` (or `compile-time-rng`) yourself.
 
 // only enables the `doc_cfg` feature when the `docsrs` configuration attribute is defined
 #![cfg_attr(docsrs, feature(doc_cfg))]