ethers_impl_serde/
serialize.rs

1// Copyright 2020 Parity Technologies
2//
3// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
4// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
5// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
6// option. This file may not be copied, modified, or distributed
7// except according to those terms.
8
9use alloc::{string::String, vec::Vec};
10use core::{fmt, result::Result};
11use serde::{de, Deserializer, Serializer};
12
13static CHARS: &[u8] = b"0123456789abcdef";
14
15/// Serialize given bytes to a 0x-prefixed hex string.
16///
17/// If `skip_leading_zero` initial 0s will not be printed out,
18/// unless the byte string is empty, in which case `0x0` will be returned.
19/// The results are consistent with `serialize_uint` output if the flag is
20/// on and `serialize_raw` if the flag is off.
21pub fn to_hex(bytes: &[u8], skip_leading_zero: bool) -> String {
22	let bytes = if skip_leading_zero {
23		let non_zero = bytes.iter().take_while(|b| **b == 0).count();
24		let bytes = &bytes[non_zero..];
25		if bytes.is_empty() {
26			return "0x0".into()
27		} else {
28			bytes
29		}
30	} else if bytes.is_empty() {
31		return "0x".into()
32	} else {
33		bytes
34	};
35
36	let mut slice = vec![0u8; (bytes.len() + 1) * 2];
37	to_hex_raw(&mut slice, bytes, skip_leading_zero).into()
38}
39
40fn to_hex_raw<'a>(v: &'a mut [u8], bytes: &[u8], skip_leading_zero: bool) -> &'a str {
41	assert!(v.len() > 1 + bytes.len() * 2);
42
43	v[0] = b'0';
44	v[1] = b'x';
45
46	let mut idx = 2;
47	let first_nibble = bytes[0] >> 4;
48	if first_nibble != 0 || !skip_leading_zero {
49		v[idx] = CHARS[first_nibble as usize];
50		idx += 1;
51	}
52	v[idx] = CHARS[(bytes[0] & 0xf) as usize];
53	idx += 1;
54
55	for &byte in bytes.iter().skip(1) {
56		v[idx] = CHARS[(byte >> 4) as usize];
57		v[idx + 1] = CHARS[(byte & 0xf) as usize];
58		idx += 2;
59	}
60
61	// SAFETY: all characters come either from CHARS or "0x", therefore valid UTF8
62	unsafe { core::str::from_utf8_unchecked(&v[0..idx]) }
63}
64
65/// Decoding bytes from hex string error.
66#[derive(Debug, PartialEq, Eq)]
67pub enum FromHexError {
68	/// The `0x` prefix is missing.
69	#[deprecated(since = "0.3.2", note = "We support non 0x-prefixed hex strings")]
70	MissingPrefix,
71	/// Invalid (non-hex) character encountered.
72	InvalidHex {
73		/// The unexpected character.
74		character: char,
75		/// Index of that occurrence.
76		index: usize,
77	},
78}
79
80#[cfg(feature = "std")]
81impl std::error::Error for FromHexError {}
82
83impl fmt::Display for FromHexError {
84	fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
85		match *self {
86			#[allow(deprecated)]
87			Self::MissingPrefix => write!(fmt, "0x prefix is missing"),
88			Self::InvalidHex { character, index } => write!(fmt, "invalid hex character: {}, at {}", character, index),
89		}
90	}
91}
92
93/// Decode given (both 0x-prefixed or not) hex string into a vector of bytes.
94///
95/// Returns an error if non-hex characters are present.
96pub fn from_hex(v: &str) -> Result<Vec<u8>, FromHexError> {
97	let (v, stripped) = v.strip_prefix("0x").map_or((v, false), |v| (v, true));
98
99	let mut bytes = vec![0u8; (v.len() + 1) / 2];
100	from_hex_raw(v, &mut bytes, stripped)?;
101	Ok(bytes)
102}
103
104/// Decode given 0x-prefix-stripped hex string into provided slice.
105/// Used internally by `from_hex` and `deserialize_check_len`.
106///
107/// The method will panic if `bytes` have incorrect length (make sure to allocate enough beforehand).
108fn from_hex_raw(v: &str, bytes: &mut [u8], stripped: bool) -> Result<usize, FromHexError> {
109	let bytes_len = v.len();
110	let mut modulus = bytes_len % 2;
111	let mut buf = 0;
112	let mut pos = 0;
113	for (index, byte) in v.bytes().enumerate() {
114		buf <<= 4;
115
116		match byte {
117			b'A'..=b'F' => buf |= byte - b'A' + 10,
118			b'a'..=b'f' => buf |= byte - b'a' + 10,
119			b'0'..=b'9' => buf |= byte - b'0',
120			b' ' | b'\r' | b'\n' | b'\t' => {
121				buf >>= 4;
122				continue
123			},
124			b => {
125				let character = char::from(b);
126				return Err(FromHexError::InvalidHex { character, index: index + if stripped { 2 } else { 0 } })
127			},
128		}
129
130		modulus += 1;
131		if modulus == 2 {
132			modulus = 0;
133			bytes[pos] = buf;
134			pos += 1;
135		}
136	}
137
138	Ok(pos)
139}
140
141/// Serializes a slice of bytes.
142pub fn serialize_raw<S>(slice: &mut [u8], bytes: &[u8], serializer: S) -> Result<S::Ok, S::Error>
143where
144	S: Serializer,
145{
146	if bytes.is_empty() {
147		serializer.serialize_str("0x")
148	} else {
149		serializer.serialize_str(to_hex_raw(slice, bytes, false))
150	}
151}
152
153/// Serializes a slice of bytes.
154pub fn serialize<S>(bytes: &[u8], serializer: S) -> Result<S::Ok, S::Error>
155where
156	S: Serializer,
157{
158	let mut slice = vec![0u8; (bytes.len() + 1) * 2];
159	serialize_raw(&mut slice, bytes, serializer)
160}
161
162/// Serialize a slice of bytes as uint.
163///
164/// The representation will have all leading zeros trimmed.
165pub fn serialize_uint<S>(slice: &mut [u8], bytes: &[u8], serializer: S) -> Result<S::Ok, S::Error>
166where
167	S: Serializer,
168{
169	let non_zero = bytes.iter().take_while(|b| **b == 0).count();
170	let bytes = &bytes[non_zero..];
171	if bytes.is_empty() {
172		serializer.serialize_str("0x0")
173	} else {
174		serializer.serialize_str(to_hex_raw(slice, bytes, true))
175	}
176}
177
178/// Expected length of bytes vector.
179#[derive(Debug, PartialEq, Eq)]
180pub enum ExpectedLen<'a> {
181	/// Exact length in bytes.
182	Exact(&'a mut [u8]),
183	/// A bytes length between (min; slice.len()].
184	Between(usize, &'a mut [u8]),
185}
186
187impl<'a> fmt::Display for ExpectedLen<'a> {
188	fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
189		match *self {
190			ExpectedLen::Exact(ref v) => write!(fmt, "{} bytes", v.len()),
191			ExpectedLen::Between(min, ref v) => write!(fmt, "between ({}; {}] bytes", min, v.len()),
192		}
193	}
194}
195
196/// Deserialize into vector of bytes.  This will allocate an O(n) intermediate
197/// string.
198pub fn deserialize<'de, D>(deserializer: D) -> Result<Vec<u8>, D::Error>
199where
200	D: Deserializer<'de>,
201{
202	struct Visitor;
203
204	impl<'b> de::Visitor<'b> for Visitor {
205		type Value = Vec<u8>;
206
207		fn expecting(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
208			write!(formatter, "a (both 0x-prefixed or not) hex string or byte array")
209		}
210
211		fn visit_str<E: de::Error>(self, v: &str) -> Result<Self::Value, E> {
212			from_hex(v).map_err(E::custom)
213		}
214
215		fn visit_string<E: de::Error>(self, v: String) -> Result<Self::Value, E> {
216			self.visit_str(&v)
217		}
218
219		fn visit_bytes<E: de::Error>(self, v: &[u8]) -> Result<Self::Value, E> {
220			Ok(v.to_vec())
221		}
222
223		fn visit_byte_buf<E: de::Error>(self, v: Vec<u8>) -> Result<Self::Value, E> {
224			Ok(v)
225		}
226
227		fn visit_seq<A: de::SeqAccess<'b>>(self, mut seq: A) -> Result<Self::Value, A::Error> {
228			let mut bytes = vec![];
229			while let Some(n) = seq.next_element::<u8>()? {
230				bytes.push(n);
231			}
232			Ok(bytes)
233		}
234
235		fn visit_newtype_struct<D: Deserializer<'b>>(self, deserializer: D) -> Result<Self::Value, D::Error> {
236			deserializer.deserialize_bytes(self)
237		}
238	}
239
240	deserializer.deserialize_str(Visitor)
241}
242
243/// Deserialize into vector of bytes with additional size check.
244/// Returns number of bytes written.
245pub fn deserialize_check_len<'a, 'de, D>(deserializer: D, len: ExpectedLen<'a>) -> Result<usize, D::Error>
246where
247	D: Deserializer<'de>,
248{
249	struct Visitor<'a> {
250		len: ExpectedLen<'a>,
251	}
252
253	impl<'a, 'b> de::Visitor<'b> for Visitor<'a> {
254		type Value = usize;
255
256		fn expecting(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
257			write!(formatter, "a (both 0x-prefixed or not) hex string or byte array containing {}", self.len)
258		}
259
260		fn visit_str<E: de::Error>(self, v: &str) -> Result<Self::Value, E> {
261			let (v, stripped) = v.strip_prefix("0x").map_or((v, false), |v| (v, true));
262
263			let len = v.len();
264			let is_len_valid = match self.len {
265				ExpectedLen::Exact(ref slice) => len == 2 * slice.len(),
266				ExpectedLen::Between(min, ref slice) => len <= 2 * slice.len() && len > 2 * min,
267			};
268
269			if !is_len_valid {
270				return Err(E::invalid_length(v.len(), &self))
271			}
272
273			let bytes = match self.len {
274				ExpectedLen::Exact(slice) => slice,
275				ExpectedLen::Between(_, slice) => slice,
276			};
277
278			from_hex_raw(v, bytes, stripped).map_err(E::custom)
279		}
280
281		fn visit_string<E: de::Error>(self, v: String) -> Result<Self::Value, E> {
282			self.visit_str(&v)
283		}
284
285		fn visit_bytes<E: de::Error>(self, v: &[u8]) -> Result<Self::Value, E> {
286			let len = v.len();
287			let is_len_valid = match self.len {
288				ExpectedLen::Exact(ref slice) => len == slice.len(),
289				ExpectedLen::Between(min, ref slice) => len <= slice.len() && len > min,
290			};
291
292			if !is_len_valid {
293				return Err(E::invalid_length(v.len(), &self))
294			}
295
296			let bytes = match self.len {
297				ExpectedLen::Exact(slice) => slice,
298				ExpectedLen::Between(_, slice) => slice,
299			};
300
301			bytes[..len].copy_from_slice(v);
302			Ok(len)
303		}
304
305		fn visit_byte_buf<E: de::Error>(self, v: Vec<u8>) -> Result<Self::Value, E> {
306			self.visit_bytes(&v)
307		}
308
309		fn visit_seq<A: de::SeqAccess<'b>>(self, mut seq: A) -> Result<Self::Value, A::Error> {
310			let mut v = vec![];
311			while let Some(n) = seq.next_element::<u8>()? {
312				v.push(n);
313			}
314			self.visit_byte_buf(v)
315		}
316
317		fn visit_newtype_struct<D: Deserializer<'b>>(self, deserializer: D) -> Result<Self::Value, D::Error> {
318			deserializer.deserialize_bytes(self)
319		}
320	}
321
322	deserializer.deserialize_str(Visitor { len })
323}
324
325#[cfg(test)]
326mod tests {
327	use super::*;
328	use serde_derive::{Deserialize, Serialize};
329
330	#[derive(Serialize, Deserialize)]
331	struct Bytes(#[serde(with = "super")] Vec<u8>);
332
333	#[test]
334	fn should_not_fail_on_short_string_with_prefix() {
335		let a: Bytes = serde_json::from_str("\"0x\"").unwrap();
336		let b: Bytes = serde_json::from_str("\"0x1\"").unwrap();
337		let c: Bytes = serde_json::from_str("\"0x12\"").unwrap();
338		let d: Bytes = serde_json::from_str("\"0x123\"").unwrap();
339		let e: Bytes = serde_json::from_str("\"0x1234\"").unwrap();
340		let f: Bytes = serde_json::from_str("\"0x12345\"").unwrap();
341
342		assert!(a.0.is_empty());
343		assert_eq!(b.0, vec![1]);
344		assert_eq!(c.0, vec![0x12]);
345		assert_eq!(d.0, vec![0x1, 0x23]);
346		assert_eq!(e.0, vec![0x12, 0x34]);
347		assert_eq!(f.0, vec![0x1, 0x23, 0x45]);
348	}
349
350	#[test]
351	fn should_not_fail_on_other_strings_with_prefix() {
352		let a: Bytes =
353			serde_json::from_str("\"0x7f864e18e3dd8b58386310d2fe0919eef27c6e558564b7f67f22d99d20f587\"").unwrap();
354		let b: Bytes =
355			serde_json::from_str("\"0x7f864e18e3dd8b58386310d2fe0919eef27c6e558564b7f67f22d99d20f587b\"").unwrap();
356		let c: Bytes =
357			serde_json::from_str("\"0x7f864e18e3dd8b58386310d2fe0919eef27c6e558564b7f67f22d99d20f587b4\"").unwrap();
358
359		assert_eq!(a.0.len(), 31);
360		assert_eq!(b.0.len(), 32);
361		assert_eq!(c.0.len(), 32);
362	}
363
364	#[test]
365	fn should_not_fail_on_short_string_without_prefix() {
366		let a: Bytes = serde_json::from_str("\"\"").unwrap();
367		let b: Bytes = serde_json::from_str("\"1\"").unwrap();
368		let c: Bytes = serde_json::from_str("\"12\"").unwrap();
369		let d: Bytes = serde_json::from_str("\"123\"").unwrap();
370		let e: Bytes = serde_json::from_str("\"1234\"").unwrap();
371		let f: Bytes = serde_json::from_str("\"12345\"").unwrap();
372
373		assert!(a.0.is_empty());
374		assert_eq!(b.0, vec![1]);
375		assert_eq!(c.0, vec![0x12]);
376		assert_eq!(d.0, vec![0x1, 0x23]);
377		assert_eq!(e.0, vec![0x12, 0x34]);
378		assert_eq!(f.0, vec![0x1, 0x23, 0x45]);
379	}
380
381	#[test]
382	fn should_not_fail_on_other_strings_without_prefix() {
383		let a: Bytes =
384			serde_json::from_str("\"7f864e18e3dd8b58386310d2fe0919eef27c6e558564b7f67f22d99d20f587\"").unwrap();
385		let b: Bytes =
386			serde_json::from_str("\"7f864e18e3dd8b58386310d2fe0919eef27c6e558564b7f67f22d99d20f587b\"").unwrap();
387		let c: Bytes =
388			serde_json::from_str("\"7f864e18e3dd8b58386310d2fe0919eef27c6e558564b7f67f22d99d20f587b4\"").unwrap();
389
390		assert_eq!(a.0.len(), 31);
391		assert_eq!(b.0.len(), 32);
392		assert_eq!(c.0.len(), 32);
393	}
394
395	#[test]
396	fn should_serialize_and_deserialize_empty_bytes() {
397		let bytes = Bytes(Vec::new());
398
399		let data = serde_json::to_string(&bytes).unwrap();
400
401		assert_eq!("\"0x\"", &data);
402
403		let deserialized: Bytes = serde_json::from_str(&data).unwrap();
404		assert!(deserialized.0.is_empty())
405	}
406
407	#[test]
408	fn should_encode_to_and_from_hex_with_prefix() {
409		assert_eq!(to_hex(&[0, 1, 2], true), "0x102");
410		assert_eq!(to_hex(&[0, 1, 2], false), "0x000102");
411		assert_eq!(to_hex(&[0], true), "0x0");
412		assert_eq!(to_hex(&[], true), "0x0");
413		assert_eq!(to_hex(&[], false), "0x");
414		assert_eq!(to_hex(&[0], false), "0x00");
415		assert_eq!(from_hex("0x0102"), Ok(vec![1, 2]));
416		assert_eq!(from_hex("0x102"), Ok(vec![1, 2]));
417		assert_eq!(from_hex("0xf"), Ok(vec![0xf]));
418	}
419
420	#[test]
421	fn should_decode_hex_without_prefix() {
422		assert_eq!(from_hex("0102"), Ok(vec![1, 2]));
423		assert_eq!(from_hex("102"), Ok(vec![1, 2]));
424		assert_eq!(from_hex("f"), Ok(vec![0xf]));
425	}
426
427	#[test]
428	fn should_deserialize_from_owned_bytes() {
429		type BytesDeserializer<'a> = serde::de::value::BytesDeserializer<'a, serde::de::value::Error>;
430
431		// using `deserialize` to decode owned bytes.
432		let des = BytesDeserializer::new(&[1, 2, 3, 4, 5]);
433		let deserialized: Vec<u8> = deserialize(des).unwrap();
434		assert_eq!(deserialized, vec![1, 2, 3, 4, 5]);
435
436		// using `deserialize` to decode owned bytes into buffer with fixed length.
437		let des = BytesDeserializer::new(&[1, 2, 3, 4, 5]);
438		let mut output = vec![0, 0, 0, 0, 0];
439		let expected_len = ExpectedLen::Exact(&mut *output);
440		let n = deserialize_check_len(des, expected_len).unwrap();
441		assert_eq!(n, 5);
442		assert_eq!(output, vec![1, 2, 3, 4, 5]);
443
444		// using `deserialize` to decode owned bytes into buffer with min/max length.
445		let des = BytesDeserializer::new(&[1, 2, 3]);
446		let mut output = vec![0, 0, 0, 0, 0];
447		let expected_len = ExpectedLen::Between(2, &mut *output);
448		let n = deserialize_check_len(des, expected_len).unwrap();
449		assert_eq!(n, 3);
450		assert_eq!(output, vec![1, 2, 3, 0, 0]);
451	}
452
453	#[test]
454	fn should_deserialize_from_borrowed_bytes() {
455		type BytesDeserializer<'a> = serde::de::value::BorrowedBytesDeserializer<'a, serde::de::value::Error>;
456
457		// using `deserialize` to decode borrowed bytes.
458		let des = BytesDeserializer::new(&[1, 2, 3, 4, 5]);
459		let deserialized: Vec<u8> = deserialize(des).unwrap();
460		assert_eq!(deserialized, vec![1, 2, 3, 4, 5]);
461
462		// using `deserialize` to decode borrowed bytes into buffer with fixed length.
463		let des = BytesDeserializer::new(&[1, 2, 3, 4, 5]);
464		let mut output = vec![0, 0, 0, 0, 0];
465		let expected_len = ExpectedLen::Exact(&mut *output);
466		let n = deserialize_check_len(des, expected_len).unwrap();
467		assert_eq!(n, 5);
468		assert_eq!(output, vec![1, 2, 3, 4, 5]);
469
470		// using `deserialize` to decode borrowed bytes into buffer with min/max length.
471		let des = BytesDeserializer::new(&[1, 2, 3]);
472		let mut output = vec![0, 0, 0, 0, 0];
473		let expected_len = ExpectedLen::Between(2, &mut *output);
474		let n = deserialize_check_len(des, expected_len).unwrap();
475		assert_eq!(n, 3);
476		assert_eq!(output, vec![1, 2, 3, 0, 0]);
477	}
478
479	#[test]
480	fn should_deserialize_from_u8_sequence() {
481		use serde::de::value::SeqDeserializer;
482
483		// using `deserialize` to decode a sequence of bytes.
484		let des = SeqDeserializer::<_, serde::de::value::Error>::new([1u8, 2, 3, 4, 5].into_iter());
485		let deserialized: Vec<u8> = deserialize(des).unwrap();
486		assert_eq!(deserialized, vec![1, 2, 3, 4, 5]);
487
488		// using `deserialize` to decode a sequence of bytes into a buffer with fixed length.
489		let des = SeqDeserializer::<_, serde::de::value::Error>::new([1u8, 2, 3, 4, 5].into_iter());
490		let mut output = vec![0, 0, 0, 0, 0];
491		let expected_len = ExpectedLen::Exact(&mut *output);
492		let n = deserialize_check_len(des, expected_len).unwrap();
493		assert_eq!(n, 5);
494		assert_eq!(output, vec![1, 2, 3, 4, 5]);
495
496		// using `deserialize` to decode a sequence of bytes into a buffer with min/max length.
497		let des = SeqDeserializer::<_, serde::de::value::Error>::new([1u8, 2, 3].into_iter());
498		let mut output = vec![0, 0, 0, 0, 0];
499		let expected_len = ExpectedLen::Between(2, &mut *output);
500		let n = deserialize_check_len(des, expected_len).unwrap();
501		assert_eq!(n, 3);
502		assert_eq!(output, vec![1, 2, 3, 0, 0]);
503	}
504}
ethers_impl_serde/serialize.rs

ethers_impl_serde/
serialize.rs
