sbor/
decoder.rs

1use crate::rust::prelude::*;
2use crate::value_kind::*;
3use crate::*;
4
5/// Represents an error occurred during decoding.
6#[derive(Debug, Copy, Clone, PartialEq, Eq, Sbor)]
7pub enum DecodeError {
8    ExtraTrailingBytes(usize),
9
10    BufferUnderflow { required: usize, remaining: usize },
11
12    UnexpectedPayloadPrefix { expected: u8, actual: u8 },
13
14    UnexpectedValueKind { expected: u8, actual: u8 },
15
16    UnexpectedCustomValueKind { actual: u8 },
17
18    UnexpectedSize { expected: usize, actual: usize },
19
20    UnexpectedDiscriminator { expected: u8, actual: u8 },
21
22    UnknownValueKind(u8),
23
24    UnknownDiscriminator(u8),
25
26    InvalidBool(u8),
27
28    InvalidUtf8,
29
30    InvalidSize,
31
32    MaxDepthExceeded(usize),
33
34    DuplicateKey,
35
36    InvalidCustomValue, // TODO: generify custom error codes
37}
38
39pub trait Decoder<X: CustomValueKind>: Sized {
40    /// Consumes the Decoder and decodes the value as a full payload
41    ///
42    /// This includes a check of the payload prefix byte: It's the intention that each version of SBOR
43    /// or change to the custom codecs should be given its own prefix
44    #[inline]
45    fn decode_payload<T: Decode<X, Self>>(mut self, expected_prefix: u8) -> Result<T, DecodeError> {
46        self.read_and_check_payload_prefix(expected_prefix)?;
47        let value = self.decode()?;
48        self.check_end()?;
49        Ok(value)
50    }
51
52    /// Decodes the value as part of a larger payload
53    ///
54    /// This method decodes the SBOR value's kind, and then its body.
55    fn decode<T: Decode<X, Self>>(&mut self) -> Result<T, DecodeError> {
56        let value_kind = self.read_value_kind()?;
57        self.decode_deeper_body_with_value_kind(value_kind)
58    }
59
60    /// Decodes the SBOR body of a child value as part of a larger payload.
61    ///
62    /// In many cases, you may wish to directly call `T::decode_body_with_value_kind` instead of this method.
63    /// See the below section for details.
64    ///
65    /// ## Direct calls and SBOR Depth
66    ///
67    /// In order to avoid SBOR depth differentials and disagreement about whether a payload
68    /// is valid, typed codec implementations should ensure that the SBOR depth as measured
69    /// during the encoding/decoding process agrees with the SBOR [`Value`] codec.
70    ///
71    /// Each layer of the SBOR `Value` counts as one depth.
72    ///
73    /// If the decoder you're writing is embedding a child type (and is represented as such
74    /// in the SBOR `Value` type), then you should call `decoder.decode_body_with_value_kind` to increment
75    /// the SBOR depth tracker.
76    ///
77    /// You should call `T::decode_body_with_value_kind` directly when the decoding of that type
78    /// into an SBOR `Value` doesn't increase the SBOR depth in the decoder, that is:
79    /// * When the wrapping type is invisible to the SBOR `Value`, ie:
80    ///   * Smart pointers
81    ///   * Transparent wrappers
82    /// * Where the use of the inner type is invisible to SBOR `Value`, ie:
83    ///   * Where the use of `T::decode_body_with_value_kind` is coincidental / code re-use
84    fn decode_deeper_body_with_value_kind<T: Decode<X, Self>>(
85        &mut self,
86        value_kind: ValueKind<X>,
87    ) -> Result<T, DecodeError>;
88
89    #[inline]
90    fn read_value_kind(&mut self) -> Result<ValueKind<X>, DecodeError> {
91        let id = self.read_byte()?;
92        ValueKind::from_u8(id).ok_or(DecodeError::UnknownValueKind(id))
93    }
94
95    #[inline]
96    fn read_discriminator(&mut self) -> Result<u8, DecodeError> {
97        self.read_byte()
98    }
99
100    fn read_size(&mut self) -> Result<usize, DecodeError> {
101        // LEB128 and 4 bytes max
102        let mut size = 0usize;
103        let mut shift = 0;
104        let mut byte;
105        loop {
106            byte = self.read_byte()?;
107            size |= ((byte & 0x7F) as usize) << shift;
108            if byte < 0x80 {
109                break;
110            }
111            shift += 7;
112            if shift >= 28 {
113                return Err(DecodeError::InvalidSize);
114            }
115        }
116
117        // The last byte should not be zero, unless the size is zero
118        if byte == 0 && shift != 0 {
119            return Err(DecodeError::InvalidSize);
120        }
121
122        Ok(size)
123    }
124
125    #[inline]
126    fn check_preloaded_value_kind(
127        &self,
128        value_kind: ValueKind<X>,
129        expected: ValueKind<X>,
130    ) -> Result<ValueKind<X>, DecodeError> {
131        if value_kind == expected {
132            Ok(value_kind)
133        } else {
134            Err(DecodeError::UnexpectedValueKind {
135                actual: value_kind.as_u8(),
136                expected: expected.as_u8(),
137            })
138        }
139    }
140
141    #[inline]
142    fn read_expected_discriminator(
143        &mut self,
144        expected_discriminator: u8,
145    ) -> Result<(), DecodeError> {
146        let actual = self.read_discriminator()?;
147        if actual == expected_discriminator {
148            Ok(())
149        } else {
150            Err(DecodeError::UnexpectedDiscriminator {
151                actual,
152                expected: expected_discriminator,
153            })
154        }
155    }
156
157    #[inline]
158    fn read_and_check_payload_prefix(&mut self, expected_prefix: u8) -> Result<(), DecodeError> {
159        let actual_payload_prefix = self.read_byte()?;
160        if actual_payload_prefix != expected_prefix {
161            return Err(DecodeError::UnexpectedPayloadPrefix {
162                actual: actual_payload_prefix,
163                expected: expected_prefix,
164            });
165        }
166
167        Ok(())
168    }
169
170    #[inline]
171    fn read_and_check_value_kind(
172        &mut self,
173        expected: ValueKind<X>,
174    ) -> Result<ValueKind<X>, DecodeError> {
175        let value_kind = self.read_value_kind()?;
176        self.check_preloaded_value_kind(value_kind, expected)
177    }
178
179    #[inline]
180    fn read_and_check_size(&mut self, expected: usize) -> Result<(), DecodeError> {
181        let len = self.read_size()?;
182        if len != expected {
183            return Err(DecodeError::UnexpectedSize {
184                expected,
185                actual: len,
186            });
187        }
188
189        Ok(())
190    }
191
192    fn check_end(&self) -> Result<(), DecodeError>;
193
194    fn read_byte(&mut self) -> Result<u8, DecodeError>;
195
196    fn read_slice(&mut self, n: usize) -> Result<&[u8], DecodeError>;
197
198    // Advanced methods - mostly for use by traversers
199
200    fn peek_remaining(&self) -> &[u8];
201
202    fn get_depth_limit(&self) -> usize;
203
204    fn get_stack_depth(&self) -> usize;
205
206    fn get_offset(&self) -> usize;
207
208    fn peek_value_kind(&self) -> Result<ValueKind<X>, DecodeError> {
209        let id = self.peek_byte()?;
210        ValueKind::from_u8(id).ok_or(DecodeError::UnknownValueKind(id))
211    }
212
213    fn peek_byte(&self) -> Result<u8, DecodeError>;
214}
215
216pub trait BorrowingDecoder<'de, X: CustomValueKind>: Decoder<X> {
217    fn read_slice_from_payload(&mut self, n: usize) -> Result<&'de [u8], DecodeError>;
218}
219
220/// A `Decoder` abstracts the logic for decoding basic types.
221pub struct VecDecoder<'de, X: CustomValueKind> {
222    input: &'de [u8],
223    offset: usize,
224    stack_depth: usize,
225    max_depth: usize,
226    phantom: PhantomData<X>,
227}
228
229impl<'de, X: CustomValueKind> VecDecoder<'de, X> {
230    pub fn new(input: &'de [u8], max_depth: usize) -> Self {
231        Self {
232            input,
233            offset: 0,
234            stack_depth: 0,
235            max_depth,
236            phantom: PhantomData,
237        }
238    }
239
240    #[inline]
241    pub fn get_input_slice(&self) -> &'de [u8] {
242        &self.input
243    }
244
245    #[inline]
246    fn require_remaining(&self, n: usize) -> Result<(), DecodeError> {
247        if self.remaining_bytes() < n {
248            Err(DecodeError::BufferUnderflow {
249                required: n,
250                remaining: self.remaining_bytes(),
251            })
252        } else {
253            Ok(())
254        }
255    }
256
257    #[inline]
258    fn remaining_bytes(&self) -> usize {
259        self.input.len() - self.offset
260    }
261
262    #[inline]
263    pub fn track_stack_depth_increase(&mut self) -> Result<(), DecodeError> {
264        self.stack_depth += 1;
265        if self.stack_depth > self.max_depth {
266            return Err(DecodeError::MaxDepthExceeded(self.max_depth));
267        }
268        Ok(())
269    }
270
271    #[inline]
272    pub fn track_stack_depth_decrease(&mut self) -> Result<(), DecodeError> {
273        self.stack_depth -= 1;
274        Ok(())
275    }
276}
277
278impl<'de, X: CustomValueKind> Decoder<X> for VecDecoder<'de, X> {
279    fn decode_deeper_body_with_value_kind<T: Decode<X, Self>>(
280        &mut self,
281        value_kind: ValueKind<X>,
282    ) -> Result<T, DecodeError> {
283        self.track_stack_depth_increase()?;
284        let decoded = T::decode_body_with_value_kind(self, value_kind)?;
285        self.track_stack_depth_decrease()?;
286        Ok(decoded)
287    }
288
289    #[inline]
290    fn read_byte(&mut self) -> Result<u8, DecodeError> {
291        self.require_remaining(1)?;
292        let result = self.input[self.offset];
293        self.offset += 1;
294        Ok(result)
295    }
296
297    #[inline]
298    fn read_slice(&mut self, n: usize) -> Result<&[u8], DecodeError> {
299        // Note - the Decoder trait can't capture all the lifetimes correctly
300        self.read_slice_from_payload(n)
301    }
302
303    #[inline]
304    fn check_end(&self) -> Result<(), DecodeError> {
305        let n = self.remaining_bytes();
306        if n != 0 {
307            Err(DecodeError::ExtraTrailingBytes(n))
308        } else {
309            Ok(())
310        }
311    }
312
313    #[inline]
314    fn peek_remaining(&self) -> &[u8] {
315        &self.input[self.offset..]
316    }
317
318    #[inline]
319    fn get_depth_limit(&self) -> usize {
320        self.max_depth
321    }
322
323    #[inline]
324    fn get_stack_depth(&self) -> usize {
325        self.stack_depth
326    }
327
328    #[inline]
329    fn get_offset(&self) -> usize {
330        self.offset
331    }
332
333    #[inline]
334    fn peek_byte(&self) -> Result<u8, DecodeError> {
335        self.require_remaining(1)?;
336        let result = self.input[self.offset];
337        Ok(result)
338    }
339}
340
341impl<'de, X: CustomValueKind> BorrowingDecoder<'de, X> for VecDecoder<'de, X> {
342    #[inline]
343    fn read_slice_from_payload(&mut self, n: usize) -> Result<&'de [u8], DecodeError> {
344        self.require_remaining(n)?;
345        let slice = &self.input[self.offset..self.offset + n];
346        self.offset += n;
347        Ok(slice)
348    }
349}
350
351#[cfg(test)]
352mod tests {
353    use super::*;
354    use crate::internal_prelude::*;
355
356    fn encode_decode_size(size: usize) -> Result<(), DecodeError> {
357        // Encode
358        let mut bytes = Vec::with_capacity(512);
359        let mut enc = BasicEncoder::new(&mut bytes, 256);
360        enc.write_size(size).unwrap();
361
362        let mut dec = BasicDecoder::new(&bytes, 256);
363        dec.read_and_check_size(size)?;
364        dec.check_end()?;
365        Ok(())
366    }
367
368    #[test]
369    pub fn test_vlq() {
370        encode_decode_size(0x00000000).unwrap();
371        encode_decode_size(0x0000007F).unwrap();
372        encode_decode_size(0x00000080).unwrap();
373        encode_decode_size(0x00002000).unwrap();
374        encode_decode_size(0x00003FFF).unwrap();
375        encode_decode_size(0x00004000).unwrap();
376        encode_decode_size(0x001FFFFF).unwrap();
377        encode_decode_size(0x00200000).unwrap();
378        encode_decode_size(0x08000000).unwrap();
379        encode_decode_size(0x0FFFFFFF).unwrap();
380    }
381
382    #[test]
383    pub fn test_vlq_too_large() {
384        let mut dec = BasicDecoder::new(&[0xff, 0xff, 0xff, 0xff, 0x00], 256);
385        assert_eq!(dec.read_size(), Err(DecodeError::InvalidSize));
386    }
387
388    fn assert_decoding(dec: &mut BasicDecoder) {
389        dec.decode::<()>().unwrap();
390        assert_eq!(true, dec.decode::<bool>().unwrap());
391        assert_eq!(1, dec.decode::<i8>().unwrap());
392        assert_eq!(1, dec.decode::<i16>().unwrap());
393        assert_eq!(1, dec.decode::<i32>().unwrap());
394        assert_eq!(1, dec.decode::<i64>().unwrap());
395        assert_eq!(1, dec.decode::<i128>().unwrap());
396        assert_eq!(1, dec.decode::<u8>().unwrap());
397        assert_eq!(1, dec.decode::<u16>().unwrap());
398        assert_eq!(1, dec.decode::<u32>().unwrap());
399        assert_eq!(1, dec.decode::<u64>().unwrap());
400        assert_eq!(1, dec.decode::<u128>().unwrap());
401        assert_eq!("hello", dec.decode::<String>().unwrap());
402
403        assert_eq!([1u32, 2u32, 3u32], dec.decode::<[u32; 3]>().unwrap());
404        assert_eq!((1u32, 2u32), dec.decode::<(u32, u32)>().unwrap());
405
406        assert_eq!(vec![1u32, 2u32, 3u32], dec.decode::<Vec<u32>>().unwrap());
407        let mut set = BTreeSet::<u8>::new();
408        set.insert(1);
409        set.insert(2);
410        assert_eq!(set, dec.decode::<BTreeSet<u8>>().unwrap());
411        let mut map = BTreeMap::<u8, u8>::new();
412        map.insert(1, 2);
413        map.insert(3, 4);
414        assert_eq!(map, dec.decode::<BTreeMap<u8, u8>>().unwrap());
415
416        assert_eq!(None, dec.decode::<Option<u32>>().unwrap());
417        assert_eq!(Some(1u32), dec.decode::<Option<u32>>().unwrap());
418        assert_eq!(Ok(1u32), dec.decode::<Result<u32, String>>().unwrap());
419        assert_eq!(
420            Err("hello".to_owned()),
421            dec.decode::<Result<u32, String>>().unwrap()
422        );
423    }
424
425    #[test]
426    pub fn test_decoding() {
427        let bytes = vec![
428            33, 0, // unit (encoded as empty tuple)
429            1, 1, // bool
430            2, 1, // i8
431            3, 1, 0, // i16
432            4, 1, 0, 0, 0, // i32
433            5, 1, 0, 0, 0, 0, 0, 0, 0, // i64
434            6, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, // i128
435            7, 1, // u8
436            8, 1, 0, // u16
437            9, 1, 0, 0, 0, // u32
438            10, 1, 0, 0, 0, 0, 0, 0, 0, // u64
439            11, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, // u128
440            12, 5, 104, 101, 108, 108, 111, // string
441            32, 9, 3, 1, 0, 0, 0, 2, 0, 0, 0, 3, 0, 0, 0, // array
442            33, 2, 9, 1, 0, 0, 0, 9, 2, 0, 0, 0, // tuple
443            32, 9, 3, 1, 0, 0, 0, 2, 0, 0, 0, 3, 0, 0, 0, // vec
444            32, 7, 2, 1, 2, // set
445            35, 7, 7, 2, 1, 2, 3, 4, // map
446            34, 0, 0, // None
447            34, 1, 1, 9, 1, 0, 0, 0, // Some<T>
448            34, 0, 1, 9, 1, 0, 0, 0, // Ok<T>
449            34, 1, 1, 12, 5, 104, 101, 108, 108, 111, // Err<T>
450        ];
451        let mut dec = BasicDecoder::new(&bytes, 256);
452        assert_decoding(&mut dec);
453    }
454
455    #[test]
456    pub fn test_decode_box() {
457        let bytes = vec![7u8, 5u8];
458        let mut dec = BasicDecoder::new(&bytes, 256);
459        let x = dec.decode::<Box<u8>>().unwrap();
460        assert_eq!(Box::new(5u8), x);
461    }
462
463    #[test]
464    pub fn test_decode_rc() {
465        let bytes = vec![7u8, 5u8];
466        let mut dec = BasicDecoder::new(&bytes, 256);
467        let x = dec.decode::<Rc<u8>>().unwrap();
468        assert_eq!(Rc::new(5u8), x);
469    }
470
471    #[test]
472    pub fn test_decode_ref_cell() {
473        let bytes = vec![7u8, 5u8];
474        let mut dec = BasicDecoder::new(&bytes, 256);
475        let x = dec.decode::<RefCell<u8>>().unwrap();
476        assert_eq!(RefCell::new(5u8), x);
477    }
478
479    #[test]
480    pub fn test_decode_duplicates_in_set() {
481        let input_with_duplicates = vec![5u16, 5u16];
482        let payload = basic_encode(&input_with_duplicates).unwrap();
483        // Check decode works into vec and BasicValue - which represent sets as arrays
484        assert_eq!(
485            basic_decode::<Vec<u16>>(&payload),
486            Ok(input_with_duplicates)
487        );
488        assert_matches!(basic_decode::<BasicValue>(&payload), Ok(_));
489        // Decode doesn't work into any typed sets
490        assert_eq!(
491            basic_decode::<HashSet<u16>>(&payload),
492            Err(DecodeError::DuplicateKey)
493        );
494        assert_eq!(
495            basic_decode::<BTreeSet<u16>>(&payload),
496            Err(DecodeError::DuplicateKey)
497        );
498        assert_eq!(
499            basic_decode::<IndexSet<u16>>(&payload),
500            Err(DecodeError::DuplicateKey)
501        );
502    }
503
504    #[test]
505    pub fn test_decode_duplicates_in_map() {
506        let input_with_duplicates = BasicValue::Map {
507            key_value_kind: ValueKind::U16,
508            value_value_kind: ValueKind::String,
509            entries: vec![
510                (
511                    BasicValue::U16 { value: 5 },
512                    BasicValue::String {
513                        value: "test".to_string(),
514                    },
515                ),
516                (
517                    BasicValue::U16 { value: 5 },
518                    BasicValue::String {
519                        value: "test2".to_string(),
520                    },
521                ),
522            ],
523        };
524        let payload = basic_encode(&input_with_duplicates).unwrap();
525        // Check decode works into BasicValue - which represent sets as arrays of (k, v) tuples
526        assert_matches!(basic_decode::<BasicValue>(&payload), Ok(_));
527        // Decode doesn't work into any typed maps
528        assert_eq!(
529            basic_decode::<HashMap<u16, String>>(&payload),
530            Err(DecodeError::DuplicateKey)
531        );
532        assert_eq!(
533            basic_decode::<BTreeMap<u16, String>>(&payload),
534            Err(DecodeError::DuplicateKey)
535        );
536        assert_eq!(
537            basic_decode::<IndexMap<u16, String>>(&payload),
538            Err(DecodeError::DuplicateKey)
539        );
540    }
541
542    #[derive(sbor::Categorize, sbor::Encode, sbor::Decode, PartialEq, Eq, Debug)]
543    struct NFA {
544        a: [u8; 32],
545        b: Vec<u8>,
546    }
547
548    #[test]
549    pub fn test_generic_array() {
550        let value1 = [
551            NFA {
552                a: [1u8; 32],
553                b: vec![1],
554            },
555            NFA {
556                a: [2u8; 32],
557                b: vec![2],
558            },
559        ];
560
561        // Encode
562        let mut bytes = Vec::with_capacity(512);
563        let mut encoder = BasicEncoder::new(&mut bytes, 256);
564        encoder.encode(&value1).unwrap();
565
566        let mut decoder = BasicDecoder::new(&bytes, 256);
567        let value2 = decoder.decode::<[NFA; 2]>().unwrap();
568        assert_eq!(value1, value2);
569    }
570
571    #[test]
572    pub fn test_invalid_size() {
573        assert_eq!(
574            BasicDecoder::new(&[0x80], 256).read_size(),
575            Err(DecodeError::BufferUnderflow {
576                required: 1,
577                remaining: 0
578            })
579        );
580
581        // Trailing zeros
582        // LE: [0, 0]
583        assert_eq!(
584            BasicDecoder::new(&[0x80, 00], 256).read_size(),
585            Err(DecodeError::InvalidSize)
586        );
587        // LE: [0, 1, 0]
588        assert_eq!(
589            BasicDecoder::new(&[0x80, 0x81, 0x00], 256).read_size(),
590            Err(DecodeError::InvalidSize)
591        );
592        assert_eq!(
593            BasicDecoder::new(&[0x80, 0x01], 256).read_size(),
594            Ok(1 << 7)
595        );
596
597        // Out of range
598        assert_eq!(
599            BasicDecoder::new(&[0xFF, 0xFF, 0xFF, 0x80], 256).read_size(),
600            Err(DecodeError::InvalidSize)
601        );
602        assert_eq!(
603            BasicDecoder::new(&[0xFF, 0xFF, 0xFF, 0xFF], 256).read_size(),
604            Err(DecodeError::InvalidSize)
605        );
606    }
607
608    #[test]
609    pub fn test_valid_size() {
610        assert_eq!(BasicDecoder::new(&[00], 256).read_size(), Ok(0));
611        assert_eq!(BasicDecoder::new(&[123], 256).read_size(), Ok(123));
612        assert_eq!(
613            BasicDecoder::new(&[0xff, 0xff, 0xff, 0x7f], 256).read_size(),
614            Ok(0x0fffffff)
615        );
616
617        let delta = 0x1fffff;
618        let ranges = [
619            0..delta,                                       /* low */
620            0x0fffffff / 2 - delta..0x0fffffff / 2 + delta, /* mid */
621            0x0fffffff - delta..0x0fffffff,                 /* high */
622        ];
623        for range in ranges {
624            for i in range {
625                let mut vec = Vec::new();
626                let mut enc = BasicEncoder::new(&mut vec, 256);
627                enc.write_size(i).unwrap();
628                let mut dec = BasicDecoder::new(&vec, 256);
629                assert_eq!(dec.read_size(), Ok(i));
630                assert_eq!(dec.remaining_bytes(), 0);
631            }
632        }
633    }
634}
sbor/decoder.rs

sbor/
decoder.rs
