What the developer wrote
Authored by Tobin C. Harding
doc: Document primitives v1.0.0
`primitives 1.0.0-rc.0` may or may not be done by the summit in
Nashville in 5 weeks.
- If it is: this document can serve as the first place folk look to
understand any design decisions we made and/or upgrade
considerations.
- If it is not: this document can serve as the canonical list of whats
left to do (any hard bits anyways).
Add a design document for the upcoming `primitives 1.0.0` release.
What changed, and why it matters
This commit only adds a Markdown design document describing future plans for the `bitcoin-primitives 1.0.0` release. It contains no code changes, no bug fixes, and no security-related behavior changes. It is purely documentation.
No security action needed. Review as normal documentation if desired.
Security signals we found
No strong security signals were identified.
Evidence from the diff
The commit introduces docs/primitives.md, a planning document listing design considerations and TODOs for stabilizing the bitcoin-primitives crate at version 1.0.0. The main noted item is removing bitcoin_hashes from the public API to comply with Rust API stability guidelines (C-STABLE). No source code, build scripts, tests, or configuration files were modified.
Changed components
docs/primitives.mdInspect captured patch +51 / −0
diff --git a/docs/primitives.md b/docs/primitives.md
new file mode 100644
index 00000000..58415eaf
--- /dev/null
+++ b/docs/primitives.md
@@ -0,0 +1,51 @@
+# primitives 1.0.0
+
+Design considerations and TODOs for the `bitcoin-primitives 1.0.0` release.
+
+## TODOs
+
+### Remove `hashes` from the public API.
+
+Required due to [C-STABLE](https://rust-lang.github.io/api-guidelines/necessities.html#c-stable).
+
+Currently `hashes` shows up in the public API in all of our hash wrapper types. This can be seen by
+grepping the API text files introduced in
+[#4792](https://github.com/rust-bitcoin/rust-bitcoin/issues/4792)
+
+The wrapper types are:
+
+```bash
+$ grep hashes api/primitives/all-features.txt | grep impl | awk '{print $NF}'
+
+bitcoin_primitives::block::BlockHash
+bitcoin_primitives::block::WitnessCommitment
+bitcoin_primitives::merkle_tree::TxMerkleNode
+bitcoin_primitives::merkle_tree::WitnessMerkleNode
+bitcoin_primitives::script::ScriptHash
+bitcoin_primitives::script::WScriptHash
+bitcoin_primitives::transaction::Ntxid
+bitcoin_primitives::transaction::Txid
+bitcoin_primitives::transaction::Wtxid
+```
+
+Using `Txid` as an example, `hashes` appears in the following places:
+
+```bash
+$ grep hashes api/primitives/all-features.txt | grep Txid
+
+impl bitcoin_hashes::Hash for bitcoin_primitives::transaction::Txid
+pub const fn bitcoin_primitives::transaction::Txid::as_byte_array(&self) -> &<bitcoin_hashes::sha256d::Hash as bitcoin_hashes::Hash>::Bytes
+pub const fn bitcoin_primitives::transaction::Txid::from_byte_array(bytes: <bitcoin_hashes::sha256d::Hash as bitcoin_hashes::Hash>::Bytes) -> Self
+pub const fn bitcoin_primitives::transaction::Txid::to_byte_array(self) -> <bitcoin_hashes::sha256d::Hash as bitcoin_hashes::Hash>::Bytes
+pub type bitcoin_primitives::transaction::Txid::Bytes = <bitcoin_hashes::sha256d::Hash as bitcoin_hashes::Hash>::Bytes
+```
+
+All these come from the `hash_newtype` macro.
+
+Usage of `hash_newtype` in `bitcoin` (i.e. other usage outside of `primitives`):
+
+- `bip158::{FilterHash, FilterHeader}`
+- `bip32::XKeyIdentifier`
+- `crypto::key::{PubkeyHash, WPubkeyHash}`
+- `crypto::sighash::{LegacySighash, SegwitV0Sighash}`
+- `taproot::{TapLeafHash, TapNodeHash, TapTweakHash}`
Why this scored 15/100
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.