massa_ledger_exports/
key.rs

1use massa_db_exports::LEDGER_PREFIX;
2use massa_hash::HASH_SIZE_BYTES;
3use massa_models::{
4    address::{Address, AddressDeserializer, AddressSerializer},
5    serialization::{VecU8Deserializer, VecU8Serializer},
6};
7use massa_serialization::{
8    Deserializer, SerializeError, Serializer, U64VarIntDeserializer, U64VarIntSerializer,
9};
10use nom::error::{ContextError, ParseError};
11use num_enum::{IntoPrimitive, TryFromPrimitive};
12use std::ops::Bound::Included;
13
14pub const VERSION_IDENT: u8 = 0u8;
15pub const BALANCE_IDENT: u8 = 1u8;
16pub const BYTECODE_IDENT: u8 = 2u8;
17pub const DATASTORE_IDENT: u8 = 3u8;
18pub const KEY_VERSION: u64 = 0;
19
20#[derive(PartialEq, Eq, Clone, IntoPrimitive, TryFromPrimitive, Debug)]
21#[repr(u8)]
22enum KeyTypeId {
23    Version = 0,
24    Balance = 1,
25    Bytecode = 2,
26    Datastore = 3,
27}
28
29#[derive(PartialEq, Eq, Clone, Debug)]
30pub enum KeyType {
31    VERSION,
32    BALANCE,
33    BYTECODE,
34    DATASTORE(Vec<u8>),
35}
36
37#[derive(Default, Clone)]
38pub struct KeyTypeSerializer {
39    vec_u8_serializer: VecU8Serializer,
40    // Whether is deserialized with VecU8Deserializer or not.
41    // If true, we use the VecU8Serializer to serialize the key which will add the length at the beginning.
42    // If false, we just serialize the key as is.
43    // This allows us to store the datastore key length at the beginning of the key or not.
44    // The datastore key length is useful when transferring multiple keys, like in packets,
45    // but isn't when storing a datastore key in the ledger.
46    with_datastore_key_length: bool,
47}
48
49impl KeyTypeSerializer {
50    /// Creates a new KeyTypeSerializer.
51    /// `with_datastore_key_length` if true, the datastore key is serialized with its length.
52    pub fn new(with_datastore_key_length: bool) -> Self {
53        Self {
54            vec_u8_serializer: VecU8Serializer::new(),
55            with_datastore_key_length,
56        }
57    }
58}
59
60impl Serializer<KeyType> for KeyTypeSerializer {
61    fn serialize(&self, value: &KeyType, buffer: &mut Vec<u8>) -> Result<(), SerializeError> {
62        match value {
63            KeyType::VERSION => buffer.extend(&[u8::from(KeyTypeId::Version)]),
64            KeyType::BALANCE => buffer.extend(&[u8::from(KeyTypeId::Balance)]),
65            KeyType::BYTECODE => buffer.extend(&[u8::from(KeyTypeId::Bytecode)]),
66            KeyType::DATASTORE(data) => {
67                buffer.extend(&[u8::from(KeyTypeId::Datastore)]);
68                if self.with_datastore_key_length {
69                    self.vec_u8_serializer.serialize(data, buffer)?;
70                } else {
71                    buffer.extend(data);
72                }
73            }
74        }
75        Ok(())
76    }
77}
78
79#[derive(Clone)]
80pub struct KeyTypeDeserializer {
81    vec_u8_deserializer: VecU8Deserializer,
82    max_datastore_key_length: u8,
83    // Same as in KeyTypeSerializer but for deserialization.
84    with_datastore_key_length: bool,
85}
86
87impl KeyTypeDeserializer {
88    /// Creates a new KeyTypeDeserializer.
89    /// `max_datastore_key_length` is the maximum length of a datastore key.
90    /// `with_datastore_key_length` if true, the datastore key is deserialized with its length.
91    pub fn new(max_datastore_key_length: u8, with_datastore_key_length: bool) -> Self {
92        Self {
93            vec_u8_deserializer: VecU8Deserializer::new(
94                Included(u64::MIN),
95                Included(max_datastore_key_length as u64),
96            ),
97            max_datastore_key_length,
98            with_datastore_key_length,
99        }
100    }
101}
102
103impl Deserializer<KeyType> for KeyTypeDeserializer {
104    fn deserialize<'a, E: ParseError<&'a [u8]> + ContextError<&'a [u8]>>(
105        &self,
106        input: &'a [u8],
107    ) -> nom::IResult<&'a [u8], KeyType, E> {
108        let (rest, key_type) = nom::number::complete::le_u8(input)?;
109        match KeyTypeId::try_from(key_type) {
110            Ok(KeyTypeId::Balance) => Ok((rest, KeyType::BALANCE)),
111            Ok(KeyTypeId::Bytecode) => Ok((rest, KeyType::BYTECODE)),
112            Ok(KeyTypeId::Datastore) => {
113                if self.with_datastore_key_length {
114                    let (rest, data) = self.vec_u8_deserializer.deserialize(rest)?;
115                    Ok((rest, KeyType::DATASTORE(data)))
116                } else {
117                    if rest.len() > self.max_datastore_key_length as usize {
118                        return Err(nom::Err::Error(E::from_error_kind(
119                            rest,
120                            nom::error::ErrorKind::LengthValue,
121                        )));
122                    }
123                    Ok((&[], KeyType::DATASTORE(rest.to_vec())))
124                }
125            }
126            Ok(KeyTypeId::Version) => Ok((rest, KeyType::VERSION)),
127            Err(_) => Err(nom::Err::Error(E::from_error_kind(
128                rest,
129                nom::error::ErrorKind::Tag,
130            ))),
131        }
132    }
133}
134
135/// Disk ledger keys representation
136#[derive(PartialEq, Eq, Clone, Debug)]
137pub struct Key {
138    pub key_type: KeyType,
139    pub address: Address,
140}
141
142impl Key {
143    pub fn new(address: &Address, key_type: KeyType) -> Self {
144        Self {
145            key_type,
146            address: *address,
147        }
148    }
149}
150
151/// Gives the general prefix of the datastore of an address while respecting a provided key prefix
152pub fn datastore_prefix_from_address(address: &Address, prefix: &[u8]) -> Vec<u8> {
153    let mut res_prefix = LEDGER_PREFIX.as_bytes().to_vec();
154    U64VarIntSerializer::new()
155        .serialize(&KEY_VERSION, &mut res_prefix)
156        .unwrap();
157    AddressSerializer::new()
158        .serialize(address, &mut res_prefix)
159        .unwrap();
160    res_prefix.push(DATASTORE_IDENT);
161    res_prefix.extend(prefix);
162    res_prefix
163}
164
165/// Serialized size of `value` as a u64 varint (7 bits per byte)
166const fn u64_varint_length(value: u64) -> usize {
167    let bits = (u64::BITS - value.leading_zeros()) as usize;
168    if bits == 0 {
169        1
170    } else {
171        bits.div_ceil(7)
172    }
173}
174
175/// Maximum length of a serialized ledger key as stored in the state DB:
176/// `LEDGER_PREFIX`, key version, address (type, version, hash), `DATASTORE_IDENT` and
177/// a datastore key of at most `max_datastore_key_length` bytes.
178///
179/// This is larger than `max_datastore_key_length` itself, so anything bounding raw
180/// state DB keys (e.g. bootstrap streaming) must use this instead.
181pub const fn max_ledger_db_key_length(max_datastore_key_length: u8) -> u64 {
182    // The key version is always `KEY_VERSION` (enforced by `KeyDeserializer`). The address
183    // type and version are varints that may grow with new address kinds/versions, so count
184    // them at their maximum size to keep this bound valid without having to update it.
185    (LEDGER_PREFIX.len()
186        + u64_varint_length(KEY_VERSION)
187        + 2 * u64_varint_length(u64::MAX)
188        + HASH_SIZE_BYTES
189        + 1) as u64
190        + max_datastore_key_length as u64
191}
192
193/// Basic key serializer
194#[derive(Default, Clone)]
195pub struct KeySerializer {
196    address_serializer: AddressSerializer,
197    key_type_serializer: KeyTypeSerializer,
198    version_byte_serializer: U64VarIntSerializer,
199}
200
201impl KeySerializer {
202    /// Creates a new `KeySerializer`
203    /// `with_datastore_key_length` if true, the datastore key is serialized with its length.
204    pub fn new(with_datastore_key_length: bool) -> Self {
205        Self {
206            address_serializer: AddressSerializer::new(),
207            key_type_serializer: KeyTypeSerializer::new(with_datastore_key_length),
208            version_byte_serializer: U64VarIntSerializer::new(),
209        }
210    }
211}
212
213impl Serializer<Key> for KeySerializer {
214    /// ```
215    /// use massa_models::address::Address;
216    /// use massa_ledger_exports::{KeySerializer, KeyType, Key};
217    /// use massa_serialization::Serializer;
218    /// use massa_hash::Hash;
219    /// use std::str::FromStr;
220    ///
221    /// let mut serialized = Vec::new();
222    /// let address = Address::from_str("AU12dG5xP1RDEB5ocdHkymNVvvSJmUL9BgHwCksDowqmGWxfpm93x").unwrap();
223    /// let store_key = Hash::compute_from(b"test");
224    /// let mut key = Key::new(&address, KeyType::DATASTORE(store_key.into_bytes().to_vec()));
225    /// KeySerializer::new(true).serialize(&key, &mut serialized).unwrap();
226    /// ```
227    fn serialize(&self, value: &Key, buffer: &mut Vec<u8>) -> Result<(), SerializeError> {
228        buffer.extend(LEDGER_PREFIX.as_bytes());
229
230        self.version_byte_serializer
231            .serialize(&KEY_VERSION, buffer)?;
232        self.address_serializer.serialize(&value.address, buffer)?;
233        self.key_type_serializer
234            .serialize(&value.key_type, buffer)?;
235
236        Ok(())
237    }
238}
239
240/// Basic key deserializer
241#[derive(Clone)]
242pub struct KeyDeserializer {
243    address_deserializer: AddressDeserializer,
244    key_type_deserializer: KeyTypeDeserializer,
245    version_byte_deserializer: U64VarIntDeserializer,
246}
247
248impl KeyDeserializer {
249    /// Creates a new `KeyDeserializer`
250    /// `max_datastore_key_length` is the maximum length of a datastore key.
251    /// `with_datastore_key_length` if true, the datastore key is deserialized with its length.
252    pub fn new(max_datastore_key_length: u8, with_datastore_key_length: bool) -> Self {
253        Self {
254            address_deserializer: AddressDeserializer::new(),
255            key_type_deserializer: KeyTypeDeserializer::new(
256                max_datastore_key_length,
257                with_datastore_key_length,
258            ),
259            version_byte_deserializer: U64VarIntDeserializer::new(Included(0), Included(u64::MAX)),
260        }
261    }
262}
263
264impl Deserializer<Key> for KeyDeserializer {
265    /// ## Example
266    /// ```
267    /// use massa_models::address::Address;
268    /// use massa_ledger_exports::{KeyDeserializer, KeySerializer, DATASTORE_IDENT, BALANCE_IDENT, KeyType, Key};
269    /// use massa_serialization::{Deserializer, Serializer, DeserializeError};
270    /// use massa_hash::Hash;
271    /// use std::str::FromStr;
272    ///
273    /// let address = Address::from_str("AU12dG5xP1RDEB5ocdHkymNVvvSJmUL9BgHwCksDowqmGWxfpm93x").unwrap();
274    /// let store_key = Hash::compute_from(b"test");
275    ///
276    /// let mut key = Key::new(&address, KeyType::DATASTORE(store_key.into_bytes().to_vec()));
277    /// let mut serialized = Vec::new();
278    /// KeySerializer::new(true).serialize(&key, &mut serialized).unwrap();
279    /// let (rest, key_deser) = KeyDeserializer::new(255, true).deserialize::<DeserializeError>(&serialized).unwrap();
280    /// assert!(rest.is_empty());
281    /// assert_eq!(key_deser, key);
282    ///
283    /// let mut key = Key::new(&address, KeyType::BALANCE);
284    /// let mut serialized = Vec::new();
285    /// KeySerializer::new(true).serialize(&key, &mut serialized).unwrap();
286    /// let (rest, key_deser) = KeyDeserializer::new(255, true).deserialize::<DeserializeError>(&serialized).unwrap();
287    /// assert!(rest.is_empty());
288    /// assert_eq!(key_deser, key);
289    /// ```
290    fn deserialize<'a, E: ParseError<&'a [u8]> + ContextError<&'a [u8]>>(
291        &self,
292        buffer: &'a [u8],
293    ) -> nom::IResult<&'a [u8], Key, E> {
294        // Skip the ledger prefix without slicing past the end of the buffer:
295        // an undersized input must yield a clean parse error rather than an
296        // out-of-bounds panic.
297        let prefix_len = LEDGER_PREFIX.len();
298        let after_prefix = buffer.get(prefix_len..).ok_or_else(|| {
299            nom::Err::Error(E::from_error_kind(buffer, nom::error::ErrorKind::Eof))
300        })?;
301
302        let (rest, version) = self.version_byte_deserializer.deserialize(after_prefix)?;
303        // Enforce the canonical key version. `KeySerializer` always writes
304        // `KEY_VERSION`, so any other value is a non-canonical / malformed key.
305        // Rejecting it prevents version malleability where distinct encodings
306        // deserialize into the same logical `Key`.
307        if version != KEY_VERSION {
308            return Err(nom::Err::Error(E::from_error_kind(
309                after_prefix,
310                nom::error::ErrorKind::Verify,
311            )));
312        }
313        let (rest, address) = self.address_deserializer.deserialize(rest)?;
314        let (rest, key_type) = self.key_type_deserializer.deserialize(rest)?;
315
316        Ok((rest, Key { address, key_type }))
317    }
318}
319
320#[cfg(test)]
321mod tests {
322    use super::{
323        max_ledger_db_key_length, u64_varint_length, Key, KeyDeserializer, KeySerializer, KeyType,
324    };
325    use massa_db_exports::LEDGER_PREFIX;
326    use massa_models::address::Address;
327    use massa_models::config::MAX_DATASTORE_KEY_LENGTH;
328    use massa_serialization::{DeserializeError, Deserializer, Serializer, U64VarIntSerializer};
329    use std::str::FromStr;
330
331    fn sample_address() -> Address {
332        Address::from_str("AU12dG5xP1RDEB5ocdHkymNVvvSJmUL9BgHwCksDowqmGWxfpm93x").unwrap()
333    }
334
335    #[test]
336    fn canonical_key_still_round_trips() {
337        let key = Key::new(&sample_address(), KeyType::BALANCE);
338        let mut serialized = Vec::new();
339        KeySerializer::new(true)
340            .serialize(&key, &mut serialized)
341            .unwrap();
342        let (rest, deser) = KeyDeserializer::new(255, true)
343            .deserialize::<DeserializeError>(&serialized)
344            .unwrap();
345        assert!(rest.is_empty());
346        assert_eq!(deser, key);
347    }
348
349    #[test]
350    fn u64_varint_length_matches_serializer() {
351        for value in [0, 1, 127, 128, 16_383, 16_384, u32::MAX as u64, u64::MAX] {
352            let mut serialized = Vec::new();
353            U64VarIntSerializer::new()
354                .serialize(&value, &mut serialized)
355                .unwrap();
356            assert_eq!(serialized.len(), u64_varint_length(value), "value {value}");
357        }
358    }
359
360    #[test]
361    fn max_ledger_db_key_length_bounds_serialized_key() {
362        // The longest datastore key accepted by execution must fit within the bound.
363        let key = Key::new(
364            &sample_address(),
365            KeyType::DATASTORE(vec![0xFF; MAX_DATASTORE_KEY_LENGTH as usize]),
366        );
367        let mut serialized = Vec::new();
368        KeySerializer::new(false)
369            .serialize(&key, &mut serialized)
370            .unwrap();
371        assert!(serialized.len() as u64 <= max_ledger_db_key_length(MAX_DATASTORE_KEY_LENGTH));
372        assert!(serialized.len() > MAX_DATASTORE_KEY_LENGTH as usize);
373    }
374
375    #[test]
376    fn undersized_buffer_errors_instead_of_panicking() {
377        // A buffer shorter than the ledger prefix must not trigger an
378        // out-of-bounds slice panic.
379        let short = vec![0u8; LEDGER_PREFIX.len().saturating_sub(1)];
380        let res = KeyDeserializer::new(255, true).deserialize::<DeserializeError>(&short);
381        assert!(res.is_err(), "undersized buffer must produce a parse error");
382    }
383
384    #[test]
385    fn non_canonical_version_is_rejected() {
386        let key = Key::new(&sample_address(), KeyType::BALANCE);
387        let mut serialized = Vec::new();
388        KeySerializer::new(true)
389            .serialize(&key, &mut serialized)
390            .unwrap();
391
392        // The version is a u64 varint written immediately after the prefix;
393        // `KEY_VERSION == 0` encodes as a single `0x00` byte. Flip it to a
394        // non-canonical value.
395        let version_idx = LEDGER_PREFIX.len();
396        assert_eq!(serialized[version_idx], 0u8);
397        serialized[version_idx] = 1u8;
398
399        let res = KeyDeserializer::new(255, true).deserialize::<DeserializeError>(&serialized);
400        assert!(res.is_err(), "a non-canonical key version must be rejected");
401    }
402}
403
404#[cfg(test)]
405mod datastore_key_bounds {
406    use super::{KeyType, KeyTypeDeserializer, KeyTypeSerializer};
407    use massa_serialization::{DeserializeError, Deserializer, Serializer};
408
409    #[test]
410    fn datastore_key_bounds_layout_boundaries() {
411        for prefixed in [false, true] {
412            for maximum in [0u8, 8, 255] {
413                for length in [0, maximum as usize, maximum as usize + 1] {
414                    let key = KeyType::DATASTORE(vec![0x80; length]);
415                    let mut bytes = Vec::new();
416                    KeyTypeSerializer::new(prefixed)
417                        .serialize(&key, &mut bytes)
418                        .unwrap();
419                    let result = KeyTypeDeserializer::new(maximum, prefixed)
420                        .deserialize::<DeserializeError>(&bytes);
421                    if length <= maximum as usize {
422                        assert_eq!(result.unwrap(), (&[][..], key));
423                    } else {
424                        assert!(
425                            result.is_err(),
426                            "key bound: prefixed={prefixed}, maximum={maximum}, length={length}"
427                        );
428                    }
429                }
430            }
431        }
432    }
433
434    #[test]
435    fn datastore_key_bounds_prefixed_remainder() {
436        let key = KeyType::DATASTORE(vec![0x80; 8]);
437        let mut bytes = Vec::new();
438        KeyTypeSerializer::new(true)
439            .serialize(&key, &mut bytes)
440            .unwrap();
441        bytes.extend([0xff, 0x42]);
442        assert_eq!(
443            KeyTypeDeserializer::new(8, true)
444                .deserialize::<DeserializeError>(&bytes)
445                .unwrap(),
446            (&[0xff, 0x42][..], key)
447        );
448    }
449
450    #[test]
451    fn datastore_key_bounds_other_key_types() {
452        for prefixed in [false, true] {
453            for key in [KeyType::VERSION, KeyType::BALANCE, KeyType::BYTECODE] {
454                let mut bytes = Vec::new();
455                KeyTypeSerializer::new(prefixed)
456                    .serialize(&key, &mut bytes)
457                    .unwrap();
458                bytes.push(0x42);
459                assert_eq!(
460                    KeyTypeDeserializer::new(0, prefixed)
461                        .deserialize::<DeserializeError>(&bytes)
462                        .unwrap(),
463                    (&[0x42][..], key)
464                );
465            }
466        }
467    }
468}