[DISPLAY_BYTES] Make helper methods public (#918)

* Make helper methods public

* Add Hex struct to use with 'serde_as' crate

* Bump to v1.1.0

libs/display-bytes/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "blockscout-display-bytes"
-version = "1.0.0"
+version = "1.1.0"
 description = "Wrapper type around Bytes to deserialize/serialize \"0x\" prefixed hex strings."
 license = "MIT"
 repository = "https://github.com/blockscout/blockscout-rs"
@@ -11,8 +11,10 @@ categories = ["encoding"]
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [dependencies]
-bytes = "1.3"
+bytes = "1"
 ethers-core = { version = "1.0", optional = true}
 hex = "0.4"
 serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"
+serde_with = "3.0"
 thiserror = "1.0"

libs/display-bytes/src/bytes.rs

@@ -148,13 +148,9 @@ impl FromStr for Bytes {
     type Err = ParseBytesError;
 
     fn from_str(value: &str) -> Result<Self, Self::Err> {
-        if let Some(value) = value.strip_prefix("0x") {
-            hex::decode(value)
-        } else {
-            hex::decode(value)
-        }
-        .map(Into::into)
-        .map_err(|e| ParseBytesError(format!("Invalid hex: {e}")))
+        super::decode_hex(value)
+            .map(Into::into)
+            .map_err(|e| ParseBytesError(format!("Invalid hex: {e}")))
     }
 }
 
@@ -171,13 +167,9 @@ where
     D: Deserializer<'de>,
 {
     let value = String::deserialize(d)?;
-    if let Some(value) = value.strip_prefix("0x") {
-        hex::decode(value)
-    } else {
-        hex::decode(&value)
-    }
-    .map(Into::into)
-    .map_err(|e| serde::de::Error::custom(e.to_string()))
+    super::decode_hex(&value)
+        .map(Into::into)
+        .map_err(|e| serde::de::Error::custom(e.to_string()))
 }
 
 #[cfg(test)]

libs/display-bytes/src/lib.rs

@@ -5,3 +5,33 @@ pub use ethers_core::types::Bytes;
 mod bytes;
 #[cfg(not(feature = "ethers-core"))]
 pub use crate::bytes::Bytes;
+
+pub mod serde_as;
+
+/// Allows to decode both "0x"-prefixed and non-prefixed hex strings
+pub fn decode_hex(value: &str) -> Result<Vec<u8>, hex::FromHexError> {
+    if let Some(value) = value.strip_prefix("0x") {
+        hex::decode(value)
+    } else {
+        hex::decode(value)
+    }
+}
+
+pub trait ToHex {
+    /// Encodes given value as "0x"-prefixed hex string using lowercase characters
+    fn to_hex(&self) -> String;
+
+    fn to_hex_upper(&self) -> String {
+        self.to_hex().to_uppercase()
+    }
+}
+
+impl<T: AsRef<[u8]>> ToHex for T {
+    fn to_hex(&self) -> String {
+        format!("0x{}", hex::encode(self))
+    }
+
+    fn to_hex_upper(&self) -> String {
+        format!("0x{}", hex::encode_upper(self))
+    }
+}

libs/display-bytes/src/serde_as.rs

@@ -0,0 +1,144 @@
+//! De/Serialization of hexadecimal encoded bytes with "0x" prefix
+//!
+//! Adapted from `serde_with::hex` (https://docs.rs/serde_with/3.8.1/serde_with/hex/index.html)
+//!
+//! Please check the documentation on the [`Hex`] type for details.
+
+use crate::ToHex;
+use serde::{de::Error as DeError, Deserialize, Deserializer, Serializer};
+use serde_with::{formats, DeserializeAs, SerializeAs};
+use std::{borrow::Cow, marker::PhantomData};
+
+/// Serialize bytes as a hex string
+///
+/// The type serializes a sequence of bytes as a hexadecimal string.
+/// It works on any type implementing `AsRef<[u8]>` for serialization and `TryFrom<Vec<u8>>` for deserialization.
+///
+/// The format type parameter specifies if the hex string should use lower- or uppercase characters.
+/// Valid options are the types [`formats::Lowercase`] and [`formats::Uppercase`].
+/// Deserialization always supports lower- and uppercase characters, even mixed in one string.
+///
+/// # Example
+///
+/// ```rust
+/// # use serde::{Deserialize, Serialize};
+/// # use serde_json::json;
+/// # use serde_with::serde_as;
+/// #
+/// #[serde_as]
+/// # #[derive(Debug, PartialEq, Eq)]
+/// #[derive(Deserialize, Serialize)]
+/// struct BytesLowercase(
+///     // Equivalent to blockscout_display_bytes::serde_as::Hex<serde_with::formats::Lowercase>
+///     #[serde_as(as = "blockscout_display_bytes::serde_as::Hex")]
+///     Vec<u8>
+/// );
+///
+/// #[serde_as]
+/// # #[derive(Debug, PartialEq, Eq)]
+/// #[derive(Deserialize, Serialize)]
+/// struct BytesUppercase(
+///     #[serde_as(as = "blockscout_display_bytes::serde_as::Hex<serde_with::formats::Uppercase>")]
+///     Vec<u8>
+/// );
+///
+/// let b = b"Hello World!";
+///
+/// // Hex with lowercase letters
+/// assert_eq!(
+///     json!("0x48656c6c6f20576f726c6421"),
+///     serde_json::to_value(BytesLowercase(b.to_vec())).unwrap()
+/// );
+/// // Hex with uppercase letters
+/// assert_eq!(
+///     json!("0x48656C6C6F20576F726C6421"),
+///     serde_json::to_value(BytesUppercase(b.to_vec())).unwrap()
+/// );
+///
+/// // Serialization always work from lower- and uppercase characters, even mixed case.
+/// assert_eq!(
+///     BytesLowercase(vec![0x00, 0xaa, 0xbc, 0x99, 0xff]),
+///     serde_json::from_value(json!("00aAbc99FF")).unwrap()
+/// );
+/// assert_eq!(
+///     BytesUppercase(vec![0x00, 0xaa, 0xbc, 0x99, 0xff]),
+///     serde_json::from_value(json!("00aAbc99FF")).unwrap()
+/// );
+///
+/// #[serde_as]
+/// # #[derive(Debug, PartialEq, Eq)]
+/// #[derive(Deserialize, Serialize)]
+/// struct ByteArray(
+///     // Equivalent to serde_with::hex::Hex<serde_with::formats::Lowercase>
+///     #[serde_as(as = "blockscout_display_bytes::serde_as::Hex")]
+///     [u8; 12]
+/// );
+///
+/// let b = *b"Hello World!";
+///
+/// assert_eq!(
+///     json!("0x48656c6c6f20576f726c6421"),
+///     serde_json::to_value(ByteArray(b)).unwrap()
+/// );
+///
+/// // Serialization always work from lower- and uppercase characters, even mixed case.
+/// assert_eq!(
+///     ByteArray([0x00, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0xaa, 0xbc, 0x99, 0xff]),
+///     serde_json::from_value(json!("0x0011223344556677aAbc99FF")).unwrap()
+/// );
+///
+/// // Remember that the conversion may fail. (The following errors are specific to fixed-size arrays)
+/// let error_result: Result<ByteArray, _> = serde_json::from_value(json!("42")); // Too short
+/// error_result.unwrap_err();
+///
+/// let error_result: Result<ByteArray, _> =
+///     serde_json::from_value(json!("0x000000000000000000000000000000")); // Too long
+/// error_result.unwrap_err();
+/// ```
+pub struct Hex<FORMAT: formats::Format = formats::Lowercase>(PhantomData<FORMAT>);
+
+impl<T> SerializeAs<T> for Hex<formats::Lowercase>
+where
+    T: AsRef<[u8]>,
+{
+    fn serialize_as<S>(source: &T, serializer: S) -> Result<S::Ok, S::Error>
+    where
+        S: Serializer,
+    {
+        serializer.serialize_str(&ToHex::to_hex(source))
+    }
+}
+
+impl<T> SerializeAs<T> for Hex<formats::Uppercase>
+where
+    T: AsRef<[u8]>,
+{
+    fn serialize_as<S>(source: &T, serializer: S) -> Result<S::Ok, S::Error>
+    where
+        S: Serializer,
+    {
+        serializer.serialize_str(&ToHex::to_hex_upper(source))
+    }
+}
+
+impl<'de, T, FORMAT> DeserializeAs<'de, T> for Hex<FORMAT>
+where
+    T: TryFrom<Vec<u8>>,
+    FORMAT: formats::Format,
+{
+    fn deserialize_as<D>(deserializer: D) -> Result<T, D::Error>
+    where
+        D: Deserializer<'de>,
+    {
+        <Cow<'de, str> as Deserialize<'de>>::deserialize(deserializer)
+            .and_then(|s| crate::decode_hex(s.as_ref()).map_err(DeError::custom))
+            .and_then(|vec: Vec<u8>| {
+                let length = vec.len();
+                vec.try_into().map_err(|_e: T::Error| {
+                    DeError::custom(format_args!(
+                        "Can't convert a Byte Vector of length {length} to the output type."
+                    ))
+                })
+            })
+    }
+}