Merge rust-bitcoin#4931: Add initial primitives 1.0.0 design document

485118f Add encoding section to primitives 1.0.0 doc (Tobin C. Harding)
ca1ada7 doc: Document primitives v1.0.0 (Tobin C. Harding)

Pull request description:

  Please see patch 1 for motivation and purpose.
  
  (Note, I started this because everytime I  got to work on `primitives` `hashes` stuff I have to check out the API text files branch and grep for stuff to work out what I'm doing. This file documents it so its there on master.)


ACKs for top commit:
  apoelstra:
    ACK 485118f; successfully ran local tests; great!


Tree-SHA512: 0072e1e49e35645d872ae0825501a07fc9bccdbaca6bf5a5a56eb137b7bb80848bc7d2447a292a86aa722675f9e03109671476f470d757a4bc88ef7dc954d70d

Author: apoelstra

docs/primitives.md

@@ -0,0 +1,59 @@
+# primitives 1.0.0
+
+Design considerations and TODOs for the `bitcoin-primitives 1.0.0` release.
+
+## TODOs
+
+### consensus encoding
+
+GitHub discussion: https://github.com/rust-bitcoin/rust-bitcoin/discussions/4856
+
+Pull encoding done in: https://github.com/rust-bitcoin/rust-bitcoin/pull/4912
+
+<!-- TODO: Add a consenus-encoding.md file? -->
+
+### 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}`