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 with_datastore_key_length: bool,
47}
48
49impl KeyTypeSerializer {
50 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 with_datastore_key_length: bool,
85}
86
87impl KeyTypeDeserializer {
88 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#[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
151pub 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
165const 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
175pub const fn max_ledger_db_key_length(max_datastore_key_length: u8) -> u64 {
182 (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#[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 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 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#[derive(Clone)]
242pub struct KeyDeserializer {
243 address_deserializer: AddressDeserializer,
244 key_type_deserializer: KeyTypeDeserializer,
245 version_byte_deserializer: U64VarIntDeserializer,
246}
247
248impl KeyDeserializer {
249 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 fn deserialize<'a, E: ParseError<&'a [u8]> + ContextError<&'a [u8]>>(
291 &self,
292 buffer: &'a [u8],
293 ) -> nom::IResult<&'a [u8], Key, E> {
294 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 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 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 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 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}