Add x_only_serde module for XOnlyPublicKey serde encoding
What changed, and why it matters
This commit adds a new optional serde (serialization) helper module for x-only public keys. It does not change existing behavior or fix a vulnerability; it gives library users an explicit choice between round-tripping parity information or discarding it. There is no security bug visible in the diff.
No security action required. Treat as a normal feature addition. If reviewing further, verify that the existing default `XOnlyPublicKey` serde behavior (which still drops parity) is acceptable and documented, as the commit leaves it unchanged.
Security signals we found
No security signal: change is a feature addition, not a fix
No unsafe code or memory-unsafe constructs
No changes to signature/validation logic
No changes to existing public API behavior
Evidence from the diff
The patch introduces x_only_serde in crypto/src/key.rs and re-exports it in bitcoin/src/crypto/key.rs. It provides with_parity and without_parity serde adapters for XOnlyPublicKey, plus optional variants. The existing Serialize/Deserialize impls for XOnlyPublicKey remain unchanged. The new code is purely additive and gated behind the serde feature. No unsafe code, no cryptographic operation changes, and no input validation bypass is present.
Changed components
crypto/src/key.rsbitcoin/src/crypto/key.rsInspect captured patch +144 / −0
### bitcoin/src/crypto/key.rs
@@ -10,6 +10,8 @@ use crate::{script, P2wpkhScriptCode};
#[rustfmt::skip] // Keep public re-exports separate.
pub use secp256k1::{constants, Parity};
+#[cfg(feature = "serde")]
+pub use crypto::key::x_only_serde;
#[doc(no_inline)]
pub use crypto::key::{
FromSliceError, FromWifError, InvalidAddressVersionError, InvalidWifCompressionFlagError,
### crypto/src/key.rs
@@ -1313,6 +1313,148 @@ impl serde::Serialize for XOnlyPublicKey {
}
}
+#[cfg(feature = "serde")]
+pub mod x_only_serde {
+ //! Serde serialization and deserialization support for x-only public keys.
+ //!
+ //! An [`XOnlyPublicKey`] holds the parity of its full public key, but the standard 32-byte
+ //! x-only encoding cannot represent it. Since there is not a default way to serialize an x-only
+ //! public key that also round-trips, [`XOnlyPublicKey`] does not implement `Serialize` or
+ //! `Deserialize` and it's up to the user to decide whether the parity should be retained.
+ //!
+ //! The provided modules can be used as follows:
+ //!
+ //! ```
+ //! # #[cfg(feature = "hex")] {
+ //! use bitcoin_crypto::key::XOnlyPublicKey;
+ //! use serde::{Deserialize, Serialize};
+ //!
+ //! #[derive(Serialize, Deserialize)]
+ //! pub struct Foo {
+ //! #[serde(with = "bitcoin_crypto::key::x_only_serde::with_parity")]
+ //! pub key: XOnlyPublicKey,
+ //! #[serde(with = "bitcoin_crypto::key::x_only_serde::without_parity::opt")]
+ //! pub maybe_key: Option<XOnlyPublicKey>,
+ //! }
+ //! # }
+ //! ```
+ //!
+ //! [`XOnlyPublicKey`]: super::XOnlyPublicKey
+
+ #![allow(clippy::missing_errors_doc)] // Errors are on serde fn impls
+
+ #[cfg(feature = "hex")]
+ pub mod with_parity {
+ //! Serialize and deserialize [`XOnlyPublicKey`] including its parity.
+ //!
+ //! The key is encoded identically to a [`FullPublicKey`], so this format round-trips.
+ //!
+ //! Use with `#[serde(with = "bitcoin_crypto::key::x_only_serde::with_parity")]`.
+
+ use serde::{Deserialize, Deserializer, Serialize, Serializer};
+
+ use crate::key::{FullPublicKey, XOnlyPublicKey};
+
+ /// Serializes `key` as a [`FullPublicKey`] using its parity.
+ #[inline]
+ pub fn serialize<S: Serializer>(key: &XOnlyPublicKey, s: S) -> Result<S::Ok, S::Error> {
+ key.to_public_key().serialize(s)
+ }
+
+ /// Deserializes a [`FullPublicKey`] into an [`XOnlyPublicKey`] retaining its parity.
+ #[inline]
+ pub fn deserialize<'d, D: Deserializer<'d>>(d: D) -> Result<XOnlyPublicKey, D::Error> {
+ FullPublicKey::deserialize(d).map(XOnlyPublicKey::from)
+ }
+
+ pub mod opt {
+ //! Serialize and deserialize [`Option<XOnlyPublicKey>`] including its parity.
+ //!
+ //! Use with `#[serde(with = "bitcoin_crypto::key::x_only_serde::with_parity::opt")]`.
+
+ use serde::{Deserialize, Deserializer, Serialize, Serializer};
+
+ use crate::key::{FullPublicKey, XOnlyPublicKey};
+
+ /// Serializes `key` as an optional [`FullPublicKey`] using its parity.
+ #[inline]
+ #[allow(clippy::ref_option)] // API forced by serde.
+ pub fn serialize<S: Serializer>(
+ key: &Option<XOnlyPublicKey>,
+ s: S,
+ ) -> Result<S::Ok, S::Error> {
+ key.map(XOnlyPublicKey::to_public_key).serialize(s)
+ }
+
+ /// Deserializes an optional [`FullPublicKey`] into an [`XOnlyPublicKey`] retaining its
+ /// parity.
+ #[inline]
+ pub fn deserialize<'d, D: Deserializer<'d>>(
+ d: D,
+ ) -> Result<Option<XOnlyPublicKey>, D::Error> {
+ Option::<FullPublicKey>::deserialize(d).map(|key| key.map(XOnlyPublicKey::from))
+ }
+ }
+ }
+
+ pub mod without_parity {
+ //! Serialize and deserialize [`XOnlyPublicKey`] without its parity.
+ //!
+ //! The key is encoded identically to a [`secp256k1::XOnlyPublicKey`]. This format does not
+ //! round-trip for keys with odd parity; deserialized keys always have even parity.
+ //!
+ //! Use with `#[serde(with = "bitcoin_crypto::key::x_only_serde::without_parity")]`.
+
+ use secp256k1::Parity;
+ use serde::{Deserialize, Deserializer, Serialize, Serializer};
+
+ use crate::key::XOnlyPublicKey;
+
+ /// Serializes the x-coordinate of `key`, discarding its parity.
+ #[inline]
+ pub fn serialize<S: Serializer>(key: &XOnlyPublicKey, s: S) -> Result<S::Ok, S::Error> {
+ <secp256k1::XOnlyPublicKey as Serialize>::serialize(&key.to_inner(), s)
+ }
+
+ /// Deserializes an x-coordinate into an [`XOnlyPublicKey`] with even parity.
+ #[inline]
+ pub fn deserialize<'d, D: Deserializer<'d>>(d: D) -> Result<XOnlyPublicKey, D::Error> {
+ secp256k1::XOnlyPublicKey::deserialize(d)
+ .map(|key| XOnlyPublicKey::from_secp(key, Parity::Even))
+ }
+
+ pub mod opt {
+ //! Serialize and deserialize [`Option<XOnlyPublicKey>`] without its parity.
+ //!
+ //! Use with `#[serde(with = "bitcoin_crypto::key::x_only_serde::without_parity::opt")]`.
+
+ use secp256k1::Parity;
+ use serde::{Deserialize, Deserializer, Serialize, Serializer};
+
+ use crate::key::XOnlyPublicKey;
+
+ /// Serializes the x-coordinate of an optional `key`, discarding its parity.
+ #[inline]
+ #[allow(clippy::ref_option)] // API forced by serde.
+ pub fn serialize<S: Serializer>(
+ key: &Option<XOnlyPublicKey>,
+ s: S,
+ ) -> Result<S::Ok, S::Error> {
+ key.map(XOnlyPublicKey::to_inner).serialize(s)
+ }
+
+ /// Deserializes an optional x-coordinate into an [`XOnlyPublicKey`] with even parity.
+ #[inline]
+ pub fn deserialize<'d, D: Deserializer<'d>>(
+ d: D,
+ ) -> Result<Option<XOnlyPublicKey>, D::Error> {
+ Option::<secp256k1::XOnlyPublicKey>::deserialize(d)
+ .map(|key| key.map(|key| XOnlyPublicKey::from_secp(key, Parity::Even)))
+ }
+ }
+ }
+ }
+
#[cfg(feature = "serde")]
impl<'de> serde::Deserialize<'de> for XOnlyPublicKey {
#[inline]Why this scored 12/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.