From 4653d3dd3a309229dd6308ac3aa94471d1cf7f0b Mon Sep 17 00:00:00 2001 From: Matthias Seitz Date: Tue, 28 Jan 2025 17:49:27 +0100 Subject: [PATCH] docs: add docs about bincode compat (#14045) --- crates/primitives-traits/src/lib.rs | 10 ++++++++++ crates/primitives-traits/src/serde_bincode_compat.rs | 5 +++++ 2 files changed, 15 insertions(+) diff --git a/crates/primitives-traits/src/lib.rs b/crates/primitives-traits/src/lib.rs index d82c7e1a2406..64baae580a72 100644 --- a/crates/primitives-traits/src/lib.rs +++ b/crates/primitives-traits/src/lib.rs @@ -17,6 +17,7 @@ //! - `secp256k1`: Adds secp256k1 support for transaction signing/recovery. (By default the no-std //! friendly `k256` is used) //! - `rayon`: Uses `rayon` for parallel transaction sender recovery in [`BlockBody`] by default. +//! - `serde-bincode-compat` provides helpers for dealing with the `bincode` crate. //! //! ## Overview //! @@ -51,6 +52,15 @@ //! Hence this function is necessary when dealing with pre EIP-2 transactions on the ethereum //! mainnet. Newer transactions must always be recovered with the regular `recover` functions, see //! also [`recover_signer`](crypto::secp256k1::recover_signer). +//! +//! ## Bincode serde compatibility +//! +//! The [bincode-crate](https://github.com/bincode-org/bincode) is often used by additional tools when sending data over the network. +//! `bincode` crate doesn't work well with optionally serializable serde fields, but some of the consensus types require optional serialization for RPC compatibility. Read more: +//! +//! As a workaround this crate introduces the +//! [`SerdeBincodeCompat`](serde_bincode_compat::SerdeBincodeCompat) trait used to a bincode +//! compatible serde representation. #![doc( html_logo_url = "https://raw.githubusercontent.com/paradigmxyz/reth/main/assets/reth-docs.png", diff --git a/crates/primitives-traits/src/serde_bincode_compat.rs b/crates/primitives-traits/src/serde_bincode_compat.rs index 9d3a2fbd509b..1921210d2def 100644 --- a/crates/primitives-traits/src/serde_bincode_compat.rs +++ b/crates/primitives-traits/src/serde_bincode_compat.rs @@ -8,8 +8,13 @@ pub use super::{ pub use block_bincode::{Block, BlockBody}; /// Trait for types that can be serialized and deserialized using bincode. +/// +/// The recommended way to add bincode compatible serialization is via the +/// [`serde_with`] crate and the `serde_as` macro that. See for reference [`header`]. pub trait SerdeBincodeCompat: Sized + 'static { /// Serde representation of the type for bincode serialization. + /// + /// This type defines the bincode compatible serde format for the type. type BincodeRepr<'a>: Debug + Serialize + DeserializeOwned + From<&'a Self> + Into; }