primitives: Add serde note to crate docs
What the developer wrote
Authored by Mitchell Bagot
primitives: Add serde note to crate docs
Currently, the consensus encodable types in primitives don't have
serde trait implementations, and are instead supposed to be used with
consensus_encoding's serde_as_consensus module. However, this is not
documented anywhere.
Add short section to crate docs to mention use of serde_as_consensus
for consensus_encodable types.
What changed, and why it matters
This commit only adds documentation to the primitives crate explaining how users should handle serde serialization for certain Bitcoin data types. It does not change any code behavior, fix a bug, or alter security-relevant logic.
No security action required. This is a documentation improvement and can be reviewed as normal project maintenance.
Security signals we found
No strong security signals were identified.
Evidence from the diff
The patch is a documentation-only change in primitives/src/lib.rs. It adds a ‘serde’ section to the crate-level documentation noting that consensus-encodable types such as Block, block::Header, Transaction, TxIn, and TxOut do not implement serde traits directly, and that users should use bitcoin_consensus_encoding::serde_as_consensus instead. The change includes a doc-test example. No executable code is modified.
Changed components
primitives/src/lib.rs documentationInspect captured patch +19 / −0
diff --git a/primitives/src/lib.rs b/primitives/src/lib.rs
index 61dd2fae..5679beb6 100644
--- a/primitives/src/lib.rs
+++ b/primitives/src/lib.rs
@@ -10,6 +10,25 @@
//! This crate can be used in a no-std environment but a lot of the functionality requires an
//! allocator i.e., requires the `alloc` feature to be enabled.
//!
+//! ### serde
+//!
+//! The consensus encodable types (`Block`, `block::Header`, `Transaction`, `TxIn`, and `TxOut`)
+//! deliberately do not implement serde traits. Instead, they can be de/serialized with the
+//! `bitcoin_consensus_encoding::serde_as_consensus` module.
+//!
+//! ```rust
+//! # #[cfg(feature = "serde")] {
+//! use serde::{Deserialize, Serialize};
+//! use bitcoin_primitives::Transaction;
+//!
+//! #[derive(Serialize, Deserialize)]
+//! struct Foo {
+//! #[serde(with = "bitcoin_primitives::encoding::serde_as_consensus")]
+//! tx: Transaction,
+//! }
+//! # }
+//! ```
+//!
//! [`rust-bitcoin`]: <https://github.com/rust-bitcoin/rust-bitcoin>
#![no_std]
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.