miden_serde_utils/
lib.rs

1// Copyright (c) Facebook, Inc. and its affiliates.
2//
3// This source code is licensed under the MIT license found in the
4// LICENSE file in the root directory of this source tree.
5
6#![cfg_attr(not(feature = "std"), no_std)]
7
8extern crate alloc;
9
10use alloc::{
11    collections::{BTreeMap, BTreeSet},
12    format,
13    string::String,
14    vec::Vec,
15};
16
17// ERROR
18// ================================================================================================
19
20/// Defines errors which can occur during deserialization.
21#[derive(Clone, Debug, PartialEq, Eq)]
22pub enum DeserializationError {
23    /// Indicates that the deserialization failed because of insufficient data.
24    UnexpectedEOF,
25    /// Indicates that the deserialization failed because the value was not valid.
26    InvalidValue(String),
27    /// Indicates that deserialization failed for an unknown reason.
28    UnknownError(String),
29}
30
31#[cfg(feature = "std")]
32impl std::error::Error for DeserializationError {}
33
34impl core::fmt::Display for DeserializationError {
35    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
36        match self {
37            Self::UnexpectedEOF => write!(f, "unexpected end of file"),
38            Self::InvalidValue(msg) => write!(f, "invalid value: {}", msg),
39            Self::UnknownError(msg) => write!(f, "unknown error: {}", msg),
40        }
41    }
42}
43
44mod byte_reader;
45#[cfg(feature = "std")]
46pub use byte_reader::ReadAdapter;
47pub use byte_reader::{BudgetedReader, ByteReader, ReadManyIter, SliceReader};
48
49mod byte_writer;
50pub use byte_writer::ByteWriter;
51
52// SERIALIZABLE TRAIT
53// ================================================================================================
54
55/// Defines how to serialize `Self` into bytes.
56pub trait Serializable {
57    // REQUIRED METHODS
58    // --------------------------------------------------------------------------------------------
59    /// Serializes `self` into bytes and writes these bytes into the `target`.
60    fn write_into<W: ByteWriter>(&self, target: &mut W);
61
62    // PROVIDED METHODS
63    // --------------------------------------------------------------------------------------------
64
65    /// Serializes `self` into a vector of bytes.
66    fn to_bytes(&self) -> Vec<u8> {
67        let mut result = Vec::with_capacity(self.get_size_hint());
68        self.write_into(&mut result);
69        result
70    }
71
72    /// Returns an estimate of how many bytes are needed to represent self.
73    ///
74    /// The default implementation returns zero.
75    fn get_size_hint(&self) -> usize {
76        0
77    }
78}
79
80impl<T: Serializable> Serializable for &T {
81    fn write_into<W: ByteWriter>(&self, target: &mut W) {
82        (*self).write_into(target)
83    }
84
85    fn get_size_hint(&self) -> usize {
86        (*self).get_size_hint()
87    }
88}
89
90impl Serializable for () {
91    fn write_into<W: ByteWriter>(&self, _target: &mut W) {}
92
93    fn get_size_hint(&self) -> usize {
94        0
95    }
96}
97
98impl<T1> Serializable for (T1,)
99where
100    T1: Serializable,
101{
102    fn write_into<W: ByteWriter>(&self, target: &mut W) {
103        self.0.write_into(target);
104    }
105
106    fn get_size_hint(&self) -> usize {
107        self.0.get_size_hint()
108    }
109}
110
111impl<T1, T2> Serializable for (T1, T2)
112where
113    T1: Serializable,
114    T2: Serializable,
115{
116    fn write_into<W: ByteWriter>(&self, target: &mut W) {
117        self.0.write_into(target);
118        self.1.write_into(target);
119    }
120
121    fn get_size_hint(&self) -> usize {
122        self.0.get_size_hint() + self.1.get_size_hint()
123    }
124}
125
126impl<T1, T2, T3> Serializable for (T1, T2, T3)
127where
128    T1: Serializable,
129    T2: Serializable,
130    T3: Serializable,
131{
132    fn write_into<W: ByteWriter>(&self, target: &mut W) {
133        self.0.write_into(target);
134        self.1.write_into(target);
135        self.2.write_into(target);
136    }
137
138    fn get_size_hint(&self) -> usize {
139        self.0.get_size_hint() + self.1.get_size_hint() + self.2.get_size_hint()
140    }
141}
142
143impl<T1, T2, T3, T4> Serializable for (T1, T2, T3, T4)
144where
145    T1: Serializable,
146    T2: Serializable,
147    T3: Serializable,
148    T4: Serializable,
149{
150    fn write_into<W: ByteWriter>(&self, target: &mut W) {
151        self.0.write_into(target);
152        self.1.write_into(target);
153        self.2.write_into(target);
154        self.3.write_into(target);
155    }
156
157    fn get_size_hint(&self) -> usize {
158        self.0.get_size_hint()
159            + self.1.get_size_hint()
160            + self.2.get_size_hint()
161            + self.3.get_size_hint()
162    }
163}
164
165impl<T1, T2, T3, T4, T5> Serializable for (T1, T2, T3, T4, T5)
166where
167    T1: Serializable,
168    T2: Serializable,
169    T3: Serializable,
170    T4: Serializable,
171    T5: Serializable,
172{
173    fn write_into<W: ByteWriter>(&self, target: &mut W) {
174        self.0.write_into(target);
175        self.1.write_into(target);
176        self.2.write_into(target);
177        self.3.write_into(target);
178        self.4.write_into(target);
179    }
180
181    fn get_size_hint(&self) -> usize {
182        self.0.get_size_hint()
183            + self.1.get_size_hint()
184            + self.2.get_size_hint()
185            + self.3.get_size_hint()
186            + self.4.get_size_hint()
187    }
188}
189
190impl<T1, T2, T3, T4, T5, T6> Serializable for (T1, T2, T3, T4, T5, T6)
191where
192    T1: Serializable,
193    T2: Serializable,
194    T3: Serializable,
195    T4: Serializable,
196    T5: Serializable,
197    T6: Serializable,
198{
199    fn write_into<W: ByteWriter>(&self, target: &mut W) {
200        self.0.write_into(target);
201        self.1.write_into(target);
202        self.2.write_into(target);
203        self.3.write_into(target);
204        self.4.write_into(target);
205        self.5.write_into(target);
206    }
207
208    fn get_size_hint(&self) -> usize {
209        self.0.get_size_hint()
210            + self.1.get_size_hint()
211            + self.2.get_size_hint()
212            + self.3.get_size_hint()
213            + self.4.get_size_hint()
214            + self.5.get_size_hint()
215    }
216}
217
218impl Serializable for u8 {
219    fn write_into<W: ByteWriter>(&self, target: &mut W) {
220        target.write_u8(*self);
221    }
222
223    fn get_size_hint(&self) -> usize {
224        core::mem::size_of::<u8>()
225    }
226}
227
228impl Serializable for u16 {
229    fn write_into<W: ByteWriter>(&self, target: &mut W) {
230        target.write_u16(*self);
231    }
232
233    fn get_size_hint(&self) -> usize {
234        core::mem::size_of::<u16>()
235    }
236}
237
238impl Serializable for u32 {
239    fn write_into<W: ByteWriter>(&self, target: &mut W) {
240        target.write_u32(*self);
241    }
242
243    fn get_size_hint(&self) -> usize {
244        core::mem::size_of::<u32>()
245    }
246}
247
248impl Serializable for u64 {
249    fn write_into<W: ByteWriter>(&self, target: &mut W) {
250        target.write_u64(*self);
251    }
252
253    fn get_size_hint(&self) -> usize {
254        core::mem::size_of::<u64>()
255    }
256}
257
258impl Serializable for u128 {
259    fn write_into<W: ByteWriter>(&self, target: &mut W) {
260        target.write_u128(*self);
261    }
262
263    fn get_size_hint(&self) -> usize {
264        core::mem::size_of::<u128>()
265    }
266}
267
268impl Serializable for usize {
269    fn write_into<W: ByteWriter>(&self, target: &mut W) {
270        target.write_usize(*self)
271    }
272
273    fn get_size_hint(&self) -> usize {
274        byte_writer::usize_encoded_len(*self as u64)
275    }
276}
277
278impl<T: Serializable> Serializable for Option<T> {
279    fn write_into<W: ByteWriter>(&self, target: &mut W) {
280        match self {
281            Some(v) => {
282                target.write_bool(true);
283                v.write_into(target);
284            },
285            None => target.write_bool(false),
286        }
287    }
288
289    fn get_size_hint(&self) -> usize {
290        core::mem::size_of::<bool>() + self.as_ref().map(|value| value.get_size_hint()).unwrap_or(0)
291    }
292}
293
294impl<T: Serializable, const C: usize> Serializable for [T; C] {
295    fn write_into<W: ByteWriter>(&self, target: &mut W) {
296        target.write_many(self)
297    }
298
299    fn get_size_hint(&self) -> usize {
300        let mut size = 0;
301        for item in self {
302            size += item.get_size_hint();
303        }
304        size
305    }
306}
307
308impl<T: Serializable> Serializable for [T] {
309    fn write_into<W: ByteWriter>(&self, target: &mut W) {
310        target.write_usize(self.len());
311        for element in self.iter() {
312            element.write_into(target);
313        }
314    }
315
316    fn get_size_hint(&self) -> usize {
317        let mut size = self.len().get_size_hint();
318        for element in self {
319            size += element.get_size_hint();
320        }
321        size
322    }
323}
324
325impl<T: Serializable> Serializable for Vec<T> {
326    fn write_into<W: ByteWriter>(&self, target: &mut W) {
327        target.write_usize(self.len());
328        target.write_many(self);
329    }
330
331    fn get_size_hint(&self) -> usize {
332        let mut size = self.len().get_size_hint();
333        for item in self {
334            size += item.get_size_hint();
335        }
336        size
337    }
338}
339
340impl<K: Serializable, V: Serializable> Serializable for BTreeMap<K, V> {
341    fn write_into<W: ByteWriter>(&self, target: &mut W) {
342        target.write_usize(self.len());
343        target.write_many(self);
344    }
345
346    fn get_size_hint(&self) -> usize {
347        let mut size = self.len().get_size_hint();
348        for item in self {
349            size += item.get_size_hint();
350        }
351        size
352    }
353}
354
355impl<T: Serializable> Serializable for BTreeSet<T> {
356    fn write_into<W: ByteWriter>(&self, target: &mut W) {
357        target.write_usize(self.len());
358        target.write_many(self);
359    }
360
361    fn get_size_hint(&self) -> usize {
362        let mut size = self.len().get_size_hint();
363        for item in self {
364            size += item.get_size_hint();
365        }
366        size
367    }
368}
369
370impl Serializable for str {
371    fn write_into<W: ByteWriter>(&self, target: &mut W) {
372        target.write_usize(self.len());
373        target.write_many(self.as_bytes());
374    }
375
376    fn get_size_hint(&self) -> usize {
377        self.len().get_size_hint() + self.len()
378    }
379}
380
381impl Serializable for String {
382    fn write_into<W: ByteWriter>(&self, target: &mut W) {
383        target.write_usize(self.len());
384        target.write_many(self.as_bytes());
385    }
386
387    fn get_size_hint(&self) -> usize {
388        self.len().get_size_hint() + self.len()
389    }
390}
391
392// DESERIALIZABLE
393// ================================================================================================
394
395/// Defines how to deserialize `Self` from bytes.
396pub trait Deserializable: Sized {
397    // REQUIRED METHODS
398    // --------------------------------------------------------------------------------------------
399
400    /// Reads a sequence of bytes from the provided `source`, attempts to deserialize these bytes
401    /// into `Self`, and returns the result.
402    ///
403    /// # Errors
404    /// Returns an error if:
405    /// * The `source` does not contain enough bytes to deserialize `Self`.
406    /// * Bytes read from the `source` do not represent a valid value for `Self`.
407    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError>;
408
409    /// Returns the minimum serialized size for one instance of this type.
410    ///
411    /// This is used by [`ByteReader::max_alloc`] to estimate how many elements can be
412    /// deserialized from the remaining budget, preventing denial-of-service attacks from
413    /// malicious length prefixes.
414    ///
415    /// The default implementation returns `size_of::<Self>()`, which is conservative: it may
416    /// reject valid input for types where the serialized size is smaller than the in-memory
417    /// size (e.g., structs with computed/cached fields that aren't serialized).
418    ///
419    /// Override this method for types where the serialized representation is smaller than
420    /// the in-memory representation to allow more elements to be deserialized.
421    fn min_serialized_size() -> usize {
422        core::mem::size_of::<Self>()
423    }
424
425    // PROVIDED METHODS
426    // --------------------------------------------------------------------------------------------
427
428    /// Attempts to deserialize the provided `bytes` into `Self` and returns the result.
429    ///
430    /// # Errors
431    /// Returns an error if:
432    /// * The `bytes` do not contain enough information to deserialize `Self`.
433    /// * The `bytes` do not represent a valid value for `Self`.
434    ///
435    /// Note: if `bytes` contains more data than needed to deserialize `self`, no error is
436    /// returned.
437    fn read_from_bytes(bytes: &[u8]) -> Result<Self, DeserializationError> {
438        Self::read_from(&mut SliceReader::new(bytes))
439    }
440
441    /// Deserializes `Self` from bytes with a byte budget limit.
442    ///
443    /// This is the recommended method for deserializing untrusted input. The budget limits
444    /// how many bytes can be consumed during deserialization, preventing denial-of-service
445    /// attacks that exploit length fields to cause huge allocations.
446    ///
447    /// # Errors
448    /// Returns an error if:
449    /// * The budget is exhausted before deserialization completes.
450    /// * The `bytes` do not contain enough information to deserialize `Self`.
451    /// * The `bytes` do not represent a valid value for `Self`.
452    fn read_from_bytes_with_budget(
453        bytes: &[u8],
454        budget: usize,
455    ) -> Result<Self, DeserializationError> {
456        Self::read_from(&mut BudgetedReader::new(SliceReader::new(bytes), budget))
457    }
458}
459
460impl Deserializable for () {
461    fn read_from<R: ByteReader>(_source: &mut R) -> Result<Self, DeserializationError> {
462        Ok(())
463    }
464}
465
466impl<T1> Deserializable for (T1,)
467where
468    T1: Deserializable,
469{
470    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
471        let v1 = T1::read_from(source)?;
472        Ok((v1,))
473    }
474}
475
476impl<T1, T2> Deserializable for (T1, T2)
477where
478    T1: Deserializable,
479    T2: Deserializable,
480{
481    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
482        let v1 = T1::read_from(source)?;
483        let v2 = T2::read_from(source)?;
484        Ok((v1, v2))
485    }
486}
487
488impl<T1, T2, T3> Deserializable for (T1, T2, T3)
489where
490    T1: Deserializable,
491    T2: Deserializable,
492    T3: Deserializable,
493{
494    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
495        let v1 = T1::read_from(source)?;
496        let v2 = T2::read_from(source)?;
497        let v3 = T3::read_from(source)?;
498        Ok((v1, v2, v3))
499    }
500}
501
502impl<T1, T2, T3, T4> Deserializable for (T1, T2, T3, T4)
503where
504    T1: Deserializable,
505    T2: Deserializable,
506    T3: Deserializable,
507    T4: Deserializable,
508{
509    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
510        let v1 = T1::read_from(source)?;
511        let v2 = T2::read_from(source)?;
512        let v3 = T3::read_from(source)?;
513        let v4 = T4::read_from(source)?;
514        Ok((v1, v2, v3, v4))
515    }
516}
517
518impl<T1, T2, T3, T4, T5> Deserializable for (T1, T2, T3, T4, T5)
519where
520    T1: Deserializable,
521    T2: Deserializable,
522    T3: Deserializable,
523    T4: Deserializable,
524    T5: Deserializable,
525{
526    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
527        let v1 = T1::read_from(source)?;
528        let v2 = T2::read_from(source)?;
529        let v3 = T3::read_from(source)?;
530        let v4 = T4::read_from(source)?;
531        let v5 = T5::read_from(source)?;
532        Ok((v1, v2, v3, v4, v5))
533    }
534}
535
536impl<T1, T2, T3, T4, T5, T6> Deserializable for (T1, T2, T3, T4, T5, T6)
537where
538    T1: Deserializable,
539    T2: Deserializable,
540    T3: Deserializable,
541    T4: Deserializable,
542    T5: Deserializable,
543    T6: Deserializable,
544{
545    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
546        let v1 = T1::read_from(source)?;
547        let v2 = T2::read_from(source)?;
548        let v3 = T3::read_from(source)?;
549        let v4 = T4::read_from(source)?;
550        let v5 = T5::read_from(source)?;
551        let v6 = T6::read_from(source)?;
552        Ok((v1, v2, v3, v4, v5, v6))
553    }
554}
555
556impl Deserializable for u8 {
557    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
558        source.read_u8()
559    }
560}
561
562impl Deserializable for u16 {
563    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
564        source.read_u16()
565    }
566}
567
568impl Deserializable for u32 {
569    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
570        source.read_u32()
571    }
572}
573
574impl Deserializable for u64 {
575    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
576        source.read_u64()
577    }
578}
579
580impl Deserializable for u128 {
581    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
582        source.read_u128()
583    }
584}
585
586impl Deserializable for usize {
587    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
588        source.read_usize()
589    }
590
591    fn min_serialized_size() -> usize {
592        1 // vint64 encoding: minimum 1 byte for values 0-127
593    }
594}
595
596impl<T: Deserializable> Deserializable for Option<T> {
597    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
598        if source.read_bool()? {
599            Ok(Some(T::read_from(source)?))
600        } else {
601            Ok(None)
602        }
603    }
604
605    /// Returns 1 (just the bool discriminator).
606    ///
607    /// The `Some` variant would be `1 + T::min_serialized_size()`, but we use the minimum
608    /// to allow more elements through the early check.
609    fn min_serialized_size() -> usize {
610        1
611    }
612}
613
614impl<T: Deserializable, const C: usize> Deserializable for [T; C] {
615    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
616        let data: Vec<T> = source.read_many_iter(C)?.collect::<Result<_, _>>()?;
617
618        // The iterator yields exactly C elements (or fails early), so this always succeeds
619        Ok(data.try_into().unwrap_or_else(|v: Vec<T>| {
620            panic!("Expected a Vec of length {} but it was {}", C, v.len())
621        }))
622    }
623
624    fn min_serialized_size() -> usize {
625        C.saturating_mul(T::min_serialized_size())
626    }
627}
628
629impl<T: Deserializable> Deserializable for Vec<T> {
630    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
631        let len = source.read_usize()?;
632        source.read_many_iter(len)?.collect()
633    }
634
635    /// Returns 1 (the minimum vint length prefix size).
636    ///
637    /// The actual serialized size depends on the number of elements, which we don't know
638    /// at the point this is called. Using the minimum allows more elements through the
639    /// early check; budget enforcement during actual reads provides the real protection.
640    fn min_serialized_size() -> usize {
641        1
642    }
643}
644
645impl<K: Deserializable + Ord, V: Deserializable> Deserializable for BTreeMap<K, V> {
646    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
647        let len = source.read_usize()?;
648        source.read_many_iter(len)?.collect()
649    }
650
651    fn min_serialized_size() -> usize {
652        1 // minimum vint length prefix
653    }
654}
655
656impl<T: Deserializable + Ord> Deserializable for BTreeSet<T> {
657    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
658        let len = source.read_usize()?;
659        source.read_many_iter(len)?.collect()
660    }
661
662    fn min_serialized_size() -> usize {
663        1 // minimum vint length prefix
664    }
665}
666
667impl Deserializable for String {
668    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
669        let len = source.read_usize()?;
670        let data: Vec<u8> = source.read_many_iter(len)?.collect::<Result<_, _>>()?;
671
672        String::from_utf8(data).map_err(|err| DeserializationError::InvalidValue(format!("{err}")))
673    }
674
675    fn min_serialized_size() -> usize {
676        1 // minimum vint length prefix
677    }
678}
679
680// GOLDILOCKS FIELD ELEMENT IMPLEMENTATIONS
681// ================================================================================================
682
683impl Serializable for p3_goldilocks::Goldilocks {
684    fn write_into<W: ByteWriter>(&self, target: &mut W) {
685        use p3_field::PrimeField64;
686        target.write_u64(self.as_canonical_u64());
687    }
688
689    fn get_size_hint(&self) -> usize {
690        core::mem::size_of::<u64>()
691    }
692}
693
694impl Deserializable for p3_goldilocks::Goldilocks {
695    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
696        use p3_field::integers::QuotientMap;
697
698        let value = source.read_u64()?;
699        Self::from_canonical_checked(value).ok_or_else(|| {
700            DeserializationError::InvalidValue(format!(
701                "value {} is not a valid Goldilocks field element",
702                value
703            ))
704        })
705    }
706}
miden_serde_utils/lib.rs

miden_serde_utils/
lib.rs
